String Functions
String functions manipulate text data, allowing you to convert, extract, search, and format strings for display and data processing.
String Conversion
STR$( number ) or STR$( number, m ) or STR$( number, m, n ) or STR$( number, m, n, c$ )
Returns a string in the decimal (base 10) representation of number.
If m is specified sufficient spaces will be added to the start of the number to
ensure that the number of characters before the decimal point (including the
negative or positive sign) will be at least m characters. If m is zero or the
number has more than m significant digits no padding spaces will be added.
If m is negative, positive numbers will be prefixed with the plus symbol and
negative numbers with the negative symbol. If m is positive then only the
negative symbol will be used.
n is the number of digits required to follow the decimal place. If it is zero the
string will be returned without the decimal point. If it is negative the output
will always use the exponential format with n digits resolution. If n is not
specified the number of decimal places and output format will vary
automatically according to the number.
c$ is a string and if specified the first character of this string will be used as
the padding character instead of a space (see the m argument).
Examples:
Command | result :-:vvvv | :-: STR$(123.456) | "123.456" STR$(-123.456) | "-123.456" STR$(123.456, 1) | "123.456" STR$(123.456, -1) | "+123.456" STR$(123.456, 6) | " 123.456" STR$(123.456, -6) | " +123.456" STR$(-123.456, 6) | " -123.456" STR$(-123.456, 6, 5) | " -123.45600" STR$(-123.456, 6, -5) | " -1.23456e+02" STR$(53, 6) | " 53" STR$(53, 6, 2) | " 53.00" STR$(53, 6, 2, "*") | "****53.00"
STRING$( nbr, ascii ) or STRING$( nbr, string$ )
Returns a string nbr bytes long consisting of either the first character of string$
or the character representing the ASCII value ascii which is an integer or float
number in the range of 0 to 255.
VAL( string$ )
Returns the numerical value of the string$. If string$ is an invalid number
the function will return zero.
This function will recognise the &H prefix for a hexadecimal number, &O for octal and &B for binary.
String Case Conversion
UCASE$( string$ )
Returns string$ converted to uppercase characters.
LCASE$( string$ )
Returns string$ converted to lowercase characters.
String Extraction
LEFT$( string$, nbr )
Returns a substring of string$ with nbr of characters from the left
(beginning) of the string.
MID$( string$, start ) or MID$( string$, start, nbr )
Returns a substring of string$ beginning at start and continuing for nbr
characters. The first character in the string is number 1.
If nbr is omitted the returned string will extend to the end of string$
RIGHT$( string$, number-of- chars )
Returns a substring of string$ with number-of-chars from the right (end) of
the string.
String Formatting & Utilities
SPACE$( number )
Returns a string of blank spaces number characters long.
TAB( number )
Outputs spaces until the column indicated by number has been reached on the
console output.
String Search
INSTR( [start-position,] string-searched$, string- pattern$ [,size] )
Returns the position at which string-pattern$ occurs in string-searched$,
beginning at start-position. If start-position is not provided it will default to 1.
Both the position returned and start-position use 1 for the first character, 2 for
the second, etc.
The function returns zero if string-pattern$ is not found.
If the optional parameter “size” is specified the “string-pattern” is treated as a regular expression. See Appendix E for the details.
LINSTR(array%(), search$ [,start] [,size]))
Returns the position of a search string in a long string.
The returned value is an integer and will be zero if the substring cannot be
found. array%() is the string to be searched and must be a long string
variable. search$ is the substring to look for and it must be a normal
MMBasic string or expression (not a long string). The search is case sensitive.
Normally the search will start at the first character in ' array%()' but the optional third parameter allows the start position of the search to be specified.
If the optional parameter size is specified the search$ is treated as a regular
expression. See Appendix E for the details.
Binary String Conversion
BIN2STR$(type, value [,BIG])
Returns a string containing the binary representation of value.
type | description |
|---|---|
| INT64 | signed 64-bit integer converted to an 8 byte string |
| UINT64 | unsigned 64-bit integer converted to an 8 byte string |
| INT32 | signed 32-bit integer converted to a 4 byte string |
| UINT32 | unsigned 32-bit integer converted to a 4 byte string |
| INT16 | signed 16-bit integer converted to a 2 byte string |
| UINT16 | unsigned 16-bit integer converted to a 2 byte string |
| INT8 | signed 8-bit integer converted to a 1 byte string |
| UINT8 | unsigned 8-bit integer converted to a 1 byte string |
| SINGLE | single precision floating point number converted to a 4 byte string |
| DOUBLE | double precision floating point number converted to a 8 byte string |
By default the string contains the number in little-endian format (i.e. the least
significant byte is the first one in the string). Setting the third parameter to
BIG will return the string in big-endian format (i.e. the most significant byte
is the first one in the string). In the case of the integer conversions, an error
will be generated if the value cannot fit into the type (eg, an attempt to store
the value 400 in a INT8).
This function makes it easy to prepare data for efficient binary file I/O or for preparing numbers for output to sensors and saving to flash memory.
See also the function STR2BIN
STR2BIN(type, string$ [,BIG])
Returns a number equal to the binary representation in string$.
type can be:
- INT64 converts 8 byte string representing a signed 64-bit integer to an integer
- UINT64 converts 8 byte string representing an unsigned 64-bit integer to an integer
- INT32 converts 4 byte string representing a signed 32-bit integer to an integer
- UINT32 converts 4 byte string representing an unsigned 32-bit integer to an integer
- INT16 converts 2 byte string representing a signed 16-bit integer to an integer
- UINT16 converts 2 byte string representing an unsigned 16-bit integer to an integer
- INT8 converts 1 byte string representing a signed 8-bit integer to an integer
- UINT8 converts 1 byte string representing an unsigned 8-bit integer to an integer
- SINGLE converts 4 byte string representing single precision float to a float
- DOUBLE converts 8 byte string representing single precision float to a float
By default the string must contain the number in little-endian format (i.e. the
least significant byte is the first one in the string). Setting the third parameter
to BIG will interpret the string in big-endian format (i.e. the most
significant byte is the first one in the string).
This function makes it easy to read data from binary data files, interpret numbers from sensors or efficiently read binary data from flash memory chips.
An error will be generated if the string is the incorrect length for the conversion requested
See also the function BIN2STR$
Long String Operations
LGETSTR$(array%(), start, length)
Returns part of a long string stored in array%() as a normal MMBasic string.
The parameters start and length define the part of the string to be returned.