SPFLite - V3.0.24069 2024-03-09

Note: The following functions should not be considered a complete list of all available thinBasic string functions, but this set will probably do for 99% of your requirements. If time permits, explore the full thinBasic Help document to review the complete set. Enter HELP thinBasic at the SPFLite command prompt to open the thinBasic help file.

ASC returns the character code of a particular character in the string-expression. The returned value will be in the range of 0 to 255. 

The optional position parameter determines which character is to be checked. The first character is one, the second two, etc. If the position parameter is missing, the first character is presumed. If position is negative, ASC counts from the end of the string in reverse. That is, -1 specifies the last character, -2 specifies the second to last character, etc.

Return one of several values, based upon the value of an index. It returns one of the parameters based upon the value of index. That is, if index is one, choice1 is returned. If two, choice2 is returned, etc. If index is not equal to one of the choice values, "" ( zero-length string) is returned.

This function creates a string of characters. Arguments must be normal characters, or codes in the range of 0 to 255. 

CHR$ creates and returns a string. There are two forms of arguments available, and they may be intermixed in a single CHR$ function. The created string may contain no characters, one character, or multiple characters, depending upon the arguments you use. You may specify any number of arguments for this function.

If the argument is a numeric expression, it is translated into the character defined by that number. A character code of -1 is treated as a special case. If you use it as an argument, CHR$ returns an empty (zero length) string for that character. For example, CHR$(65, -1, 66) returns "AB".

CHR$(numvar1 TO numvar2) returns a sequence of all characters from CHR$(numvar1) through CHR$(numvar2) inclusive. The characters may be ascending or descending in sequence. For example, CHR$(65 TO 70) returns the string "ABCDEF". CHR$(52 T0 50) returns the string "432", and CHR$(65 TO 65) returns the string "A".

CHR$ complements the ASC function, which returns the numeric character code of a nominated character in a string.

This function returns a Carriage Return / Line Feed pair. Equivalent to CHR$(13, 10)

This function returns a Double-Quote character  Equivalent to CHR$(34)

Return a string containing a centered (padded) string. CSET$ centers the string string-expression into a string of str-len characters.

If string-expression2 is "" ( zero-length string) or is not specified, CSET$ pads string-expression with space characters. Otherwise, CSET$ pads the string with the first character of string-expression2.

If string-expression is shorter then str-len, CSET$ centers string-expression within Result-String, padding both sides as described above; otherwise, CSET$ returns the left-most str-len bytes of string-expression.

Returns the system date. You can assign DATE$ to a string variable, which stores 10 characters in the form "mm-dd-yyyy", where mm represents the month, dd the day, and yyyy the year.

EXTRACT$ returns a sub-string of String-Expression, starting with its first character (or the character specified by start) and up to (but not including) the first occurrence of Match-Str. 

If Match-Str is not present in String-Expression, or either string parameter is nul, all of String-Expression is returned.

start is the optional starting position to begin extracting. If start is not specified, it will start at position 1. If start is zero, or beyond the length of String-Expression, a nul string is returned. If start is negative, the starting position is counted from right to left: if -1, the search begins at the last character; if -2, the second to last, and so forth. 

String-Expression is the string from which to extract. Match-Str is the string expression to extract up to. EXTRACT$ is case-sensitive.

If the ANY keyword is included, Match-Str specifies a list of single characters to be searched for individually, a match on any one of which will cause the extract operation to be performed up to that character.

A similar function to EXTRACT$ is PARSE$, which extracts delimited substrings from a string.

Returns a string version of numeric expression, formatted according to the Format-Mask operand.

If no Format-Mask operand is present, the number will be returned as a maximum of 16 significant digits.

Note: If you wish to just concatenate a string and a numeric value without formatting, this can be done with a simple expression of the form string-constant + numeric-expression or string-constant & numeric-expression.

Format-Mask

Format characters that will determine how numeric-expression should be formatted. This expression is termed the mask. There may be up to 18 digit-formatting digits on either side of the decimal point. The mask may not contain literal characters unless each character is preceded with a backslash (\) escape character, or the literal characters are enclosed in quotes.

Format-Mask may contain one, two or three formatting masks, separated by semicolon (;) characters:

Digit placeholders in a mask do not have to be contiguous. This allows you to format a single number into multiple displayed parts. For example:

A$ = FORMAT$(123456, "00\:00\:00") ' 12:34:56

The following table shows the characters you can use to create the user-defined format strings (masks) and the definition of each formatting character:

IIF$  returns one of two values based on numeric-expression.  If numeric-expression evaluates to TRUE (non-zero), the true-string is returned, else the false-string is returned. Compare to the IIF function.

INSTR returns the position of Match-Str within Main-Str. The return value is indexed to one, while zero means "not found".

Position specifies the character position to begin the search. If Position is one or greater, Main-Str is searched left to right. The value one starts at the first character, two the second, etc. If Position is -1 or less, Main-Str is searched from right to left. The value -1 starts at the last character, -2 the second to last, etc. If Position is not given, the default value of +1 is assumed.

x& = INSTR("xyz", "y")     ' returns 2

x& = INSTR("xyz", "a")     ' returns 0

a$ = "My Dog" : b$ = " "

x& = INSTR(a$, b$)         ' returns 3

It is important to note that in all cases, even when Position is negative, the return value of INSTR() is the absolute position of the match, from left to right, starting with the first character.

ANY

If the ANY keyword is included, Match-Str specifies a list of single characters. INSTR searches for each of these characters individually. As soon as any one of these characters is found, INSTR returns the position of the match.

x& = INSTR(-2, "efcdef", ANY "ef")     returns a result of 5

INSTR is case-sensitive, meaning that upper-case and lower-case letters must match exactly in Match-Str and Main-Str.

Returns a lowercase version of the specified string-expression.

Num-chars specifies the number of characters in string-expression to be returned.

LEFT$ returns a string consisting of the left most Num-chars characters of its string argument. If Num-chars is greater than or equal to the length of string-expression, all of string-expression is returned. If Num-chars is zero, LEFT$ returns an empty string. 

LEN will return the current length of string-expression.

LSET$ left-aligns the string string-expression into a string of str-len characters.

USING

If pad-string is "" (a zero-length string) or is not specified, LSET$ pads string-expression with space characters. Otherwise, LSET$ pads the string with the first character of pad-string.

If string-expression is shorter then str-len, LSET$ left-justifies string-expression within result-str, padding the right side as described above; otherwise, LSET$ returns the left-most str-len bytes of string-expression.

String-to-trim is the string-expression from which to remove characters, and Chars-to-trim is the string-expression containing the characters to remove.

If Chars-to-trim is not specified, LTRIM$ removes leading spaces. LTRIM$ returns a sub-string of String-to-trim, from the first non-Chars-to-trim (or non-space) to the end of the string. If Chars-to-trim (or a space) is not present at the beginning of String-to-trim, all of String-to-trim is returned.

If the ANY keyword is included, Chars-to-trim specifies a list of single characters to be searched for individually. A match on any one of these as a leading character will cause the character to be removed from the result.

LTRIM$ is case sensitive

MCASE$ returns a string equivalent to string-expression, except that the first letter of each word is capitalized, while the remaining characters are forced to lowercase. A word is considered to be a consecutive series of letters. 

The MID$ function returns a part of a string-expression. The start-loc specifies the location of the first character of the extracted string. The length specifies how many characters, starting at start-loc are to be returned.

If length is omitted, or there aren't enough characters in String-expression, all remaining characters are returned. If there are no characters at the Start-loc position, an empty string is returned.

Returns a delimited field from string-expression. string-expression is the string to parse. If string-expression is "" (a zero-length string) or contains no delimiter character(s), the string is considered to contain exactly one field. In this case, PARSE$ will return string-expression.

The str-delimiter contains delimiter character(s). A delimiter is a character, list of characters, or string, that is used to mark the end of a field in string-expression. For example, if you consider a sentence to be a list of words, the delimiter between the works is a space (or punctuation). A delimiter is not considered part of a field, but as the divider between fields, so the delimiter is never returned by PARSE$.

If str-delim is not specified or is "" (a zero-length string), standard comma-delimited (optionally quoted) fields are presumed. In this case only, the following p

arsing rules apply. If a standard field is enclosed in optional quotes, they are removed. If any characters appear between a quoted field and the next comma delimiter, they are discarded. If no leading quote is found, any leading or trailing blank spaces are trimmed before the field is returned.

Delimiters are case-sensitive, so capitalization may be a consideration.

ANY

If the ANY keyword is used, str-delimiter contains a set of characters, any of which may act as a delimiter character. If the ANY keyword is omitted, the entire str-delimiter string acts as a single delimiter.

index

A variable or expression that specifies the delimited field number to return. The first field is 1, and so on up to the maximum number of fields contained in string-expression, which may be determined with the PARSECOUNT function. If index is negative, string-expression is parsed from right to left. In this case, index  =  -1  returns the last field in string-expression, -2 returns the second to last, etc. If index evaluates to zero, or is outside of the actual field count, an empty string is returned.

Return the count of delimited strings in a string-expression. PARSECOUNT uses the same rules as PARSE$ in the determination of fields within string-expression. Individual fields within string-expression are evaluated, and the tally of the fields forms the result value.

It is important to note that PARSECOUNT may only be used with string data which contains variable length sub-fields, each of which is separated by a delimiter. To determine the count of fixed length data, divide the String-Expression length by the sub-field length. If this function is used with fixed length data, the results are undefined.

string-expression

This is the string to examine and parse. If String-Expression is "" (a zero-length string) or contains no delimiter character(s), the string is considered to contain exactly one sub-field. In this case, PARSECOUNT returns the value 1.

str-delimiter

This defines one or more characters to use as a delimiter. To be valid, the entire delimiter must match exactly, but the delimiter itself is never returned as part of the field.

If str-delimiter is not specified, or contains an empty string, special rules apply. The delimiter is assumed to be a comma. Fields may optionally be enclosed in quotes, and are ignored before the result string is returned. Any characters that appear between a quote mark and the next comma delimiter character are discarded. If no leading quote is found, any leading or trailing quotes are trimmed before the result string is returned.

ANY

If the ANY keyword is used, str-delimiter contains a set of characters, any of which may act as a delimiter character. If the ANY keyword is omitted, the entire str-delimiter string acts as a single delimiter.

Return a copy of a string with characters or strings removed.

string-expression is the string from which to remove characters. chars-to-remove is the string expression to remove all occurrences of. If chars-to-remove is not present in string-expression, all of string-expression is returned intact.

ANY

If the ANY keyword is included, chars-to-remove specifies a list of single characters to be searched for individually, a match on any one of which will cause that character to be removed from the result.

REMOVE$ is case-sensitive.

Returns a string consisting of multiple copies of the specified string. number-of-times is an expression, constant or variable, specifying the number of copies of string-expression to be included in the result. 

string-expression  is the string to be duplicated.

Within a specified string , replace all occurrences of one string with another string. The REPLACE$ statement replaces all occurrences of Match-String in string-expression with New-String. The replacement can cause string-expression to grow or condense in size. string-expression must be a string variable; Match-String and New-String may be string expressions. REPLACE$ is case-sensitive. When a match is found, the scan for the next match begins at the position immediately following the prior match.

ANY

If you use the ANY option, within String-expression, each occurrence of each character in Match-String will be replaced with the corresponding character in New-String. In this case, Match-string and New-String must be the same length, because there is a one-to-one correspondence between their characters.

Num-chars specifies the number of characters in string-expression to be returned.

RIGHT$ returns a string consisting of the right most Num-chars characters of its string argument. If Num-chars is greater than or equal to the length of string-expression, all of string-expression is returned. If Num-chars is zero, RIGHT$ returns an empty string. 

RSET$ left-aligns the string string-expression into a string of str-len characters.

USING

If pad-string is "" (a zero-length string) or is not specified, RSET$ pads string-expression with space characters. Otherwise, RSET$ pads the string with the first character of pad-string.

If string-expression is shorter then str-len, RSET$ right-justifies string-expression within result-str, padding the left side as described above; otherwise, RSET$ returns the right-most str-len bytes of string-expression.

String-to-trim is the string-expression from which to remove characters, and Chars-to-trim is the string-expression containing the characters to remove.

String-to-trim is the string-expression from which to remove characters, and Chars-to-trim is the string expression specifying the characters that should be removed from the right hand side of String-to-trim.

If Chars-to-trim is not specified, RTRIM$ removes trailing spaces. RTRIM$ returns a sub-string of String-to-trim, from the beginning of the string to the character preceding the consecutive occurrences of Chars-to-trim (or space), which continues to the end of the original string . If Chars-to-trim (or a space) is not present at the end of String-to-trim, all of String-to-trim is returned.

If the ANY keyword is included, Chars-to-trim specifies a list of single characters to be searched for individually - a match on any one of which as a trailing character will cause the character to be removed from the result.

RTRIM$ is case-sensitive.

Return the representation of a number in printable string form.

STR$ returns the string form of a variable or expression in printable text form. digits is an optional expression specifying the maximum total number of digits to appear in the result. If num-expression is greater than or equal to zero, STR$ adds a leading space character; if num-expression is less than zero, STR$ adds a leading negation (minus) character.

For example, STR$(14) returns a three-character string, of which the first character is a space, and the second and third are "1" and "4". 

digits specifies the maximum number of significant digits (1 to 18) desired in the result.

The complementary function is VAL, which takes a string argument and returns the numeric equivalent. 

Thus,  number = VAL(STR$(number)).

A numeric value may also be converted to a string with the TSTR$ function which returns the string without the leading blank or - character, or the FORMAT$ function. FORMAT$ is capable of many additional formatting options.

Return a string representing the mnemonic string passed as str-expression. str-expression may be any of  "CRLF", "TAB", "CR", "LF", "FF", "VT", "SPC", "DQ", "NUL", "ESC"

Delete a specified number of characters from str-expression.

Returns a string based on copying str-expression, but with count characters deleted starting at position start. The first character in the string is position 1, etc.

Insert ins-expression string at a specified position within str-expression.

Returns a string consisting of the string expression str-expression, with the string expression ins-expression inserted at position. If position is greater than the length of str-expression, ins-expression is appended to str-expression. The first character in the string is position 1, etc.

Reverse the contents of str-expression.

Count the number of occurrences of specified characters or strings within str-expression .

str-expression is the string in which to count characters. Match-String is the string expression to count all occurrences of. If Match-String is not present in str-expression, zero is returned. When a match is found, the scan for the next match begins at the position immediately following the prior match.

ANY

If the ANY keyword is included, Match-String specifies a list of single characters to be searched for individually: a match on any one of which will cause the count to be incremented for each occurrence of that character. Note that repeated characters in Match-String will not increase the tally. For example:

X = TALLY("ABCD", ANY "BDB")    ' returns 2, not 3

TALLY is case-sensitive, so be wary of capitalization.

Return a string with system time in the format  of HH:MM:SS using 24-hour time.

Removes leading and trailing characters or substrings from str-expression.

TRIM$ combines the functionality of LTRIM$ and RTRIM$ into a single function. str-expression is the string expression from which to remove characters, and Chars-To-Trim is the string expression to remove leading and trailing occurrences. If Chars-To-Trim is not specified, TRIM$ removes leading and trailing spaces.

ANY

If the ANY keyword is included, Chars-To-Trim specifies a list of single characters to be searched for individually, a match on any one of which as a leading or trailing character will cause the character to be removed from the result.

Return the representation of a number in printable string form.

TSTR$ returns the string form of a variable or expression in printable text form. digits is an optional expression specifying the maximum total number of digits to appear in the result. 

For example, TSTR$(14) returns a two-character string, "14".

digits specifies the maximum number of significant digits (1 to 18) desired in the result.

The complementary function is VAL, which takes a string argument and returns the numeric equivalent. 

Thus,  number = VAL(TSTR$(number)).

A numeric value may also be converted to a string with the FORMAT$ function. FORMAT$ can optionally perform many additional formatting functions.

Returns an uppercase version of the specified string-expression.

Convert a text string to a numeric value.

The VAL function converts a string argument to a number. Leading white-space characters (spaces, tabs, carriage-returns, and linefeeds) are skipped and ignored. Evaluation of the number continues until a non-numeric character is found, or the end of the string is reached. If no number is found, the VAL() function returns zero (0). Format characters (like commas) are not allowed, and will cause early termination of the evaluation.

VAL interprets the letters "e" and "d" (and "E" and "D") as the symbols for exponentiation and scientific notation:

i& = VAL("10.101e3")     ' 10101 ~ 10.101*(10^3)

j& = VAL("2D4")          ' 20000 ~ 2 * (10 ^ 4)

Hexadecimal, Binary and Octal conversions

VAL can also be used to convert string arguments that are in the form of Hexadecimal, Binary and Octal numbers. Hexadecimal values should be prefixed with "&H" and Binary with "&B". Octal values may be prefixed "&O", "&Q" or just "&". If the string-expression contains a leading zero, the result is returned as an unsigned value; otherwise, a signed value is returned. For example:

i& = VAL("&HF5F3")        ' Hex, returns -2573 (signed)

j& = VAL("&H0F5F3")                ' Hex, returns 62963 (unsigned)

x& = VAL("&B0100101101")    ' Binary, returns 301 (unsigned)

y& = VAL("&O4574514")           ' Octal, returns 1243468 (signed)

Valid hex characters include 0 to 9, A to F (and a to f). Valid Octal characters include 0 to 7, and binary 0 to 1.

VAL stops analyzing string-expression when non-numeric characters are encountered. When dealing with Hexadecimal, Binary, and Octal number systems, the period character is classified as non-numeric. 

Determine whether each character of a string is present in another string.

VERIFY returns zero if each character in string-expression is present in Match-String. If not, it returns the position of the first non-matching character in string-expression.

This function is useful for determining if a string contains only digits. For example, VERIFY(NUM, "0123456789") = 0 if NUM is a numeric string.

VERIFY is case-sensitive, so capitalization matters.

If start evaluates to a position outside of the string on either side, or if start is zero, VERIFY returns zero.

Created with the Personal Edition of HelpNDoc: Transform your help documentation into a stunning website