String Functions

Summary
This returns the value of an integer as a string.
Return the numeric value of a string.
Return the length (in bytes) of a string.
Extract one or more words from a string.
Return the number of words in a string.
Find the first occurance of a substring in a string starting at a given position.
Extract the N left-most characters of a string.
Extract a substring.
Extract the N right-most characters of a string.
Make an uppercase copy of a string.
Make a lowercase copy of a string.
Determine if a string is composed entirely of alphabetic characters.
Determine if a string is solely numeric characters.
Return a string corresponding to the ASCII character given.
Return the ASCII value of the first character in the string.
Generate a hexadecimal representation of an MD5 hash of the string.
Generate an ANSI color code sequence for the specified foreground and background combination.
Replace all instances of one string with another.
Match a text against a provided regular expression.
Similar to match, but returns the matched string and capture groups.

string$

This returns the value of an integer as a string.

Params

numthe number to convert

Returns

The string representation of num.

val

Return the numeric value of a string.

Params

str$a string

Returns

A positive or negative integer if it begins with a number, or 0 if it is not numeric.

length

Return the length (in bytes) of a string.

Params

str$a string

Returns

An integer length.

words$

Extract one or more words from a string.  A word, in this case, is a sequence of non-whitespace characters.  If the ‘last’ word (as in the parameter ‘last’) is 0, it means extract everything from the first through the end of the string.  The numbers are inclusive, so:

words$("this is a test", 1, 2) = "this is"
words$("this is a test", 2, 0) = "is a test"
words$("this is a test", 3, 3) = "a"
words$("this is a test", 2, 10) = "is a test"

Note that the first and last values are automatically clipped to the largest values possible Also, the whitespace is preserved between the first and last words (but whitespace on the front or back is stripped).

words$("this is a test",

Params

str$the source string
firstthe first word to extract
lastthe last word to extract (or 0 for the rest of the string)

Returns

A string containing the words between first and last inclusive.

words

Return the number of words in a string.

Params

str$a string

Returns

An integer indicating the number of words in the string.

pos

Find the first occurance of a substring in a string starting at a given position.  Searching begins at position start + 1, and a return value of 0 indicates no match found, otherwise the position of the first character of the search string is returned.

You might think that the start + 1 searching mechanism is odd, but it allows easy construction of enumeration loops (and is more consistent with other search routines such as database searching).  For an example see the following.

i = pos(str$, "foo", 0);
while( i )do
{
do_stuff(i);
i = pos(str$, "foo", i);
}

Some examples of use might illustrate the behavior better.

pos("blahb", "a", 0) = 3
pos("blahb", "b", 0) = 1
pos("blahb", "b", 1) = 5
pos("blahb", "b", 5) = 0
pos("blahb", "la", 0) = 2
pos("blahb", "al", 0) = 0

Params

haystack$The string to search.
needle$The substring to search for.
startThe first character to check - 1

Returns

The position of the first character of needle$ in haystack$ or 0 if no match is found.

left$

Extract the N left-most characters of a string.

Params

str$Source string.
nNumber of characters to extract

Returns

A the left-most part of str$ not longer than N characters.

mid$

Extract a substring.  This will extract a portion of the string beginning anywhere in it.

Params

str$Source string.
startThe first character to extract
nNumber of characters to extract

Returns

A the slice of str$ not longer than N characters and starting at the ‘start’th character.

right$

Extract the N right-most characters of a string.

Params

str$Source string.
nNumber of characters to extract

Returns

A the right-most part of str$ not longer than N characters.

upper$

Make an uppercase copy of a string.

Params

str$The string to copy

Returns

A copy of str$ with every character uppercased.

lower$

Make a lowercase copy of a string.

Params

str$The string to copy

Returns

A lowercase version of the string.

alpha

Determine if a string is composed entirely of alphabetic characters.

Params

str$a string to check

Returns

Returns true if every character is an alphabetic character.

numeric

Determine if a string is solely numeric characters.  The string can optionally have a negative sign on the front and still be considered numeric.  Basically, this returns true if val() would make sense on this string.

Params

str$a string to check

Returns

Returns true if every character is numeric.

chr$

Return a string corresponding to the ASCII character given.

Params

chAn ASCII value (0 - 255)

Returns

A string of that character.

ord

Return the ASCII value of the first character in the string.

Params

ch$A string

Returns

The ASCII value of the first character in the string.

md5$

Generate a hexadecimal representation of an MD5 hash of the string.  An MD5 hash is a cryptographically strong hashing algorithm for generating a signature of a string.  This routine returns a hexadecimal representation of the 16 byte hash value.

Params

str$a string to hash

Returns

A 32 character hexadecimal string representing the hash value.

ansicolor$

Generate an ANSI color code sequence for the specified foreground and background combination.  The ansi colors are listed below.  Note that only the lower 8 colors may be used for background colors (this is a limitation of the ANSI standard).  Bold colors are generally interpreted as brighter on most client programs, but they can also make the font used actually bold as well.  A color value of -1 will generate a color code sequence that sets only the other color.  For example ansicolor$(1, -1) will leave the background color alone and set the foreground to red.

] Color Name FG?  BG?  ] -1 (Default color) y y ] 0 Black y y ] 1 Red y y ] 2 Green y y ] 3 Yellow y y ] 4 Blue y y ] 5 Magenta y y ] 6 Cyan y y ] 7 White y y ] 8 Grey (Bold Black) y - ] 9 Bold red y - ] 10 Bold green y - ] 11 Bold yellow y - ] 12 Bold blue y - ] 13 Bold magenta y - ] 14 Bold cyan y - ] 15 Bold white y -

Params

fgA numeric color
bgA numeric color

Returns

An ANSI color code sequence (string) that can be sent to a player to instruct his/her client to change the color of any incoming text.

replace$

Replace all instances of one string with another.

Params

str$the original string
pat$the pattern to search for
repl$the string to replace with

Returns

A new string with every instance of pat$ in str$ replaced with repl$.

match

Match a text against a provided regular expression.  The compiled expression is cached, making the matching very fast.  Note that character groups (\d, \w, ...) need to have the backslash doubled.

Params

re$regular expression
str$the string to match

Returns

Index of the matching substring, or 0 if no match found.

match@

Similar to match, but returns the matched string and capture groups.

Params

re$regular expression
str$the string to match

Returns

A vector with the matched string in index 0, and matched capture groups in subsequent ones.