LONGSTRING
The LONGSTRING commands allow for the manipulation of strings longer than the normal MMBasic limit of 255 characters. Variables for holding long strings must be defined as single dimensioned integer arrays with the number of elements set to the number of characters required for the maximum string length divided by eight. The reason for dividing by eight is that each integer in an MMBasic array occupies eight bytes. Note that the long string routines do not check for overflow in the length of the strings. If an attempt is made to create a string longer than a long string variable's size the outcome will be undefined.
Basic Operations
LONGSTRING CLEAR array%()
Will clear the long string variable 'array%()'. i.e. it will be set to an empty string.
LONGSTRING COPY dest%(), src%()
Copy one long string to another. 'dest%()' is the destination variable and 'src%()' is the source variable. Whatever was in 'dest%()' will be overwritten.
LONGSTRING CONCAT dest%(), src%()
Concatenate one long string to another. 'dest%()' is the destination variable and 'src%()' is the source variable. 'src%()' will be added to the end of 'dest%()' (the destination will not be overwritten).
LONGSTRING APPEND array%(), string$
Append a normal MMBasic string to a long string variable. 'array%()' is a long string variable while 'string$' is a normal MMBasic string expression.
LONGSTRING LOAD array%(), nbr, string$
Will copy 'nbr' characters from 'string$' to the long string variable 'array%()' overwriting whatever was in 'array%()'.
String Manipulation
LONGSTRING LEFT dest%(), src%(), nbr
Will copy the left hand 'nbr' characters from 'src%()' to 'dest%()' overwriting whatever was in 'dest%()'. i.e. copy from the beginning of 'src%()'. 'src%()' and 'dest%()' must be long string variables. 'nbr' must be an integer constant or expression.
See also: LEFT$() - regular string left extraction function.
LONGSTRING MID dest%(), src%(), start, nbr
Will copy 'nbr' characters from 'src%()' to 'dest%()' starting at character position 'start' overwriting whatever was in 'dest%()'. i.e. copy from the middle of 'src%()'. 'nbr' is optional and if omitted the characters from 'start' to the end of the string will be copied. 'src%()' and 'dest%()' must be long string variables. 'start' and 'nbr' must be integer constants or expressions.
See also: MID$() - regular string mid extraction function.
LONGSTRING RIGHT dest%(), src%(), n%
Extracts the rightmost 'n%' characters from the longstring 'src%()' and stores them in 'dest%()'. This is similar to the RIGHT$() function but operates on longstrings.
LONGSTRING TRIM dest%(), src%()
Removes leading and trailing whitespace from the longstring 'src%()' and stores the result in 'dest%()'. This is similar to the TRIM$() function but operates on longstrings.
Case Conversion
LONGSTRING LCASE array%()
Will convert any uppercase characters in 'array%()' to lowercase. 'array%()' must be long string variable.
See also: LCASE$() - regular string case conversion function.
LONGSTRING UCASE dest%(), src%()
Converts all lowercase letters in the longstring 'src%()' to uppercase and stores the result in 'dest%()'. This is similar to the UCASE$() function but operates on longstrings.
Encoding and Encryption
LONGSTRING AES128 ENCRYPT/DECRYPT CBC/ECB/CTR key$/key!/%, in%(), out%() [,iv$/iv!/%]
Encrypts or decrypts the longstring in in%() putting the answer in out%(). Supports CBC, ECB, and CTR encryption modes.
For CBC and CTR modes the encryption will generate a random initialisation vector and prepend out%() with the IV. If an explicit IV is specified this will be used instead of the random vector and this will be prepended to out%().
For CBC and CTR decryption the firmware assumes that the first 16 bytes of in%() are the initialisation vector. In the case where you want to transmit a message without IV you can use LONGSTRING RIGHT to remove the IV before sending the message. In this case the recipient must know the IV as well as the key and create a complete longstring before using DECRYPT. This can be done by using LONGSTRING CONCAT to add the incoming message to a longstring containing the IV.
The parameters can each be either a string, integer array, or float array with any mix possible. The key must be 16 elements long (16*8=128bits), in and out must be a multiple of 16 elements long. In the case of out being specified as a string (e.g. out$), the string variable must exist and should be set to empty (DIM out$="").
The maximum number of elements in 'in' and 'out' is limited by memory when defined as arrays. Strings for encrypting are limited to 240bytes (ECB) and 224bytes (CTR and CBC). For CBC and CTR encryption you can optionally specify an initialisation vector 'iv'. 'iv' must be 16 elements long (16*8=128bits). If an initialisation vector is not specified encryption will generate a random initialisation vector. In both cases the output is prepended with the IV.
For CBC and CTR, decryption requires that the first 16 elements of the input are the initialisation vector. In the case where you want to transmit a message without IV you should remove the IV before sending the message using standard MMBasic manipulations. In this case the recipient must know the IV as well as the key and create a complete message before using DECRYPT by prepending the IV to the incoming message.
LONGSTRING BASE64
This BASE64 encodes or decodes the longstring in in%() placing the answer in out%().
Output
LONGSTRING PRINT [#n,] src%() [;]
Prints the longstring stored in 'src%()' to the file or COM port opened as '#n'. If '#n' is not specified the output will be sent to the console. Add a semi-colon to suppress CR/LF.
Advanced Operations
LONGSTRING REPLACE dest%(), src%(), old$, new$
Replaces all occurrences of the string 'old$' with 'new$' in the longstring 'src%()' and stores the result in 'dest%()'. This is similar to the REPLACE$() function but operates on longstrings.
LONGSTRING RESIZE src%(), size%
Resizes the longstring 'src%()' to 'size%' bytes. If 'size%' is larger than the current size, the longstring will be extended with null bytes. If 'size%' is smaller, the longstring will be truncated.
LONGSTRING SETBYTE src%(), position%, value%
Sets the byte at 'position%' in the longstring 'src%()' to 'value%'. Position numbering starts from 1.