Strings
Functions
string
collapseEscape(string text)
Replace all escape sequences in text with their respective character codes.
ColorI
ColorFloatToInt(LinearColorF color)
Convert from a float color to an integer color (0.0 - 1.0 to 0 to 255).
ColorI
ColorHEXToRGB(string hex)
Convert from a hex color value to an integer RGB (red, green, blue) color (00 - FF to 0 to 255).
ColorI
ColorHSBToRGB(Point3I hsb)
Convert from a HSB (hue, saturation, brightness) to an integer RGB (red, green, blue) color. HSB is also know as HSL or HSV as well, with the last letter standing for lightness or value.
LinearColorF
ColorIntToFloat(ColorI color)
Convert from a integer color to an float color (0 to 255 to 0.0 - 1.0).
string
ColorRGBToHEX(ColorI color)
Convert from a integer RGB (red, green, blue) color to hex color value (0 to 255 to 00 - FF).
string
ColorRGBToHSB(ColorI color)
Convert from a integer RGB (red, green, blue) color to HSB (hue, saturation, brightness). HSB is also know as HSL or HSV as well, with the last letter standing for lightness or value.
void
Dumps information about String memory usage.
bool
endsWith(string str, string suffix, bool caseSensitive)
Test whether the given string ends with the given suffix.
string
expandEscape(string text)
Replace all characters in text that need to be escaped for the string to be a valid string literal with their respective escape sequences.
string
getSubStr(string str, int start, int numChars)
Return a substring of str starting at start and continuing either through to the end of str (if numChars is -1) or for numChars characters (except if this would exceed the actual source string length).
int
getTrailingNumber(string str)
Get the numeric suffix of the given input string.
bool
isalnum(string str, int index)
Test whether the character at the given position is an alpha-numeric character.
bool
isFloat(string str, bool sciOk)
Returns true if the string is a float.
bool
isInt(string str)
Returns true if the string is an integer.
bool
isspace(string str, int index)
Test whether the character at the given position is a whitespace character.
bool
isValidIP(string str)
Returns true if the string is a valid ip address, excepts localhost.
bool
isValidPort(string str)
Returns true if the string is a valid port number.
string
ltrim(string str)
Remove leading whitespace from the string.
string
nextToken(string str1, string token, string delim)
Tokenize a string using a set of delimiting characters.
string
rtrim(string str)
Remove trailing whitespace from the string.
bool
startsWith(string str, string prefix, bool caseSensitive)
Test whether the given string begins with the given prefix.
int
strasc(string chr)
Return the integer character code value corresponding to the first character in the given string.
string
strchr(string str, string chr)
Find the first occurrence of the given character in str.
int
strchrpos(string str, string chr, int start)
Find the first occurrence of the given character in the given string.
int
strcmp(string str1, string str2)
Compares two strings using case-sensitive comparison.
string
strformat(string format, string value)
Format the given value as a string using printf-style formatting.
int
stricmp(string str1, string str2)
Compares two strings using case-insensitive comparison.
int
strinatcmp(string str1, string str2)
Compares two strings using "natural order" case-insensitive comparison.
string
stripChars(string str, string chars)
Remove all occurrences of characters contained in chars from str.
String
stripTrailingNumber(string str)
Strip a numeric suffix from the given string.
bool
strIsMatchExpr(string pattern, string str, bool caseSensitive)
Match a pattern against a string.
bool
strIsMatchMultipleExpr(string patterns, string str, bool caseSensitive)
Match a multiple patterns against a single string.
int
strlen(string str)
Get the length of the given string in bytes.
int
strlenskip(string str, string first, string last)
Calculate the length of a string in characters, skipping everything between and including first and last.
string
strlwr(string str)
Return an all lower-case version of the given string.
int
strnatcmp(string str1, string str2)
Compares two strings using "natural order" case-sensitive comparison.
int
strpos(string haystack, string needle, int offset)
Find the start of needle in haystack searching from left to right beginning at the given offset.
int
strposr(string haystack, string needle, int offset)
Find the start of needle in haystack searching from right to left beginning at the given offset.
string
strrchr(string str, string chr)
Find the last occurrence of the given character in str.
int
strrchrpos(string str, string chr, int start)
Find the last occurrence of the given character in the given string.
string
strrepeat(string str, int numTimes, string delimiter)
Return a string that repeats str numTimes number of times delimiting each occurrence with delimiter.
string
strreplace(string source, string from, string to)
Replace all occurrences of from in source with to.
int
strstr(string string, string substring)
Find the start of substring in the given string searching from left to right.
string
strToggleCaseToWords(string str)
Parse a Toggle Case word into separate words.
string
strupr(string str)
Return an all upper-case version of the given string.
string
trim(string str)
Remove leading and trailing whitespace from the string.
Detailed Description
Functions
collapseEscape(string text)
Replace all escape sequences in text with their respective character codes.
This function replaces all escape sequences (\n, \t, etc) in the given string with the respective characters they represent.
The primary use of this function is for converting strings from their literal form into their compiled/translated form, as is normally done by the TorqueScript compiler.
Parameters:
| text | A string. |
A duplicate of text with all escape sequences replaced by their respective character codes.
// Print: // // str // ing // // to the console. Note how the backslash in the string must be escaped here // in order to prevent the TorqueScript compiler from collapsing the escape // sequence in the resulting string. echo( collapseEscape( "str\ning" ) );
ColorFloatToInt(LinearColorF color)
Convert from a float color to an integer color (0.0 - 1.0 to 0 to 255).
Parameters:
| color | Float color value to be converted in the form "R G B A", where R is red, G is green, B is blue, and A is alpha. |
Converted color value (0 - 255)
ColorFloatToInt( "0 0 1 0.5" ) // Returns "0 0 255 128".
ColorHEXToRGB(string hex)
Convert from a hex color value to an integer RGB (red, green, blue) color (00 - FF to 0 to 255).
Parameters:
| hex | Hex color value (#000000 - #FFFFFF) to be converted to an RGB (red, green, blue) value. |
Integer color value to be converted in the form "R G B A", where R is red, G is green, B is blue, and A is alpha. Alpha isn't handled/converted so only pay attention to the RGB value
ColorHEXToRGB( "#0000FF" ) // Returns "0 0 255 0".
ColorHSBToRGB(Point3I hsb)
Convert from a HSB (hue, saturation, brightness) to an integer RGB (red, green, blue) color. HSB is also know as HSL or HSV as well, with the last letter standing for lightness or value.
Parameters:
| hsb | HSB (hue, saturation, brightness) value to be converted. |
Integer color value to be converted in the form "R G B A", where R is red, G is green, B is blue, and A is alpha. Alpha isn't handled/converted so only pay attention to the RGB value
ColorHSBToRGB( "240 100 100" ) // Returns "0 0 255 0".
ColorIntToFloat(ColorI color)
Convert from a integer color to an float color (0 to 255 to 0.0 - 1.0).
Parameters:
| color | Integer color value to be converted in the form "R G B A", where R is red, G is green, B is blue, and A is alpha. |
Converted color value (0.0 - 1.0)
ColorIntToFloat( "0 0 255 128" ) // Returns "0 0 1 0.5".
ColorRGBToHEX(ColorI color)
Convert from a integer RGB (red, green, blue) color to hex color value (0 to 255 to 00 - FF).
Parameters:
| color | Integer color value to be converted in the form "R G B A", where R is red, G is green, B is blue, and A is alpha. It excepts an alpha, but keep in mind this will not be converted. |
Hex color value (#000000 - #FFFFFF), alpha isn't handled/converted so it is only the RGB value
ColorRBGToHEX( "0 0 255 128" ) // Returns "#0000FF".
ColorRGBToHSB(ColorI color)
Convert from a integer RGB (red, green, blue) color to HSB (hue, saturation, brightness). HSB is also know as HSL or HSV as well, with the last letter standing for lightness or value.
Parameters:
| color | Integer color value to be converted in the form "R G B A", where R is red, G is green, B is blue, and A is alpha. It excepts an alpha, but keep in mind this will not be converted. |
HSB color value, alpha isn't handled/converted so it is only the RGB value
ColorRBGToHSB( "0 0 255 128" ) // Returns "240 100 100".
dumpStringMemStats()
Dumps information about String memory usage.
endsWith(string str, string suffix, bool caseSensitive)
Test whether the given string ends with the given suffix.
Parameters:
| str | The string to test. |
| suffix | The potential suffix of str. |
| caseSensitive | If true, the comparison will be case-sensitive; if false, differences in casing will not be taken into account. |
True if the last characters in str match the complete contents of suffix; false otherwise.
startsWith( "TEST123", "123" ) // Returns true.
expandEscape(string text)
Replace all characters in text that need to be escaped for the string to be a valid string literal with their respective escape sequences.
All characters in text that cannot appear in a string literal will be replaced by an escape sequence (\n, \t, etc).
The primary use of this function is for converting strings suitable for being passed as string literals to the TorqueScript compiler.
Parameters:
| text | A string |
A duplicate of the text parameter with all unescaped characters that cannot appear in string literals replaced by their respective escape sequences.
getSubStr(string str, int start, int numChars)
Return a substring of str starting at start and continuing either through to the end of str (if numChars is -1) or for numChars characters (except if this would exceed the actual source string length).
Parameters:
| str | The string from which to extract a substring. |
| start | The offset at which to start copying out characters. |
| numChars | Optional argument to specify the number of characters to copy. If this is -1, all characters up the end of the input string are copied. |
A string that contains the given portion of the input string.
getSubStr( "foobar", 1, 2 ) // Returns "oo".
getTrailingNumber(string str)
Get the numeric suffix of the given input string.
Parameters:
| str | The string from which to read out the numeric suffix. |
The numeric value of the number suffix of str or -1 if str has no such suffix.
getTrailingNumber( "test123" ) // Returns '123'.
isalnum(string str, int index)
Test whether the character at the given position is an alpha-numeric character.
Alpha-numeric characters are characters that are either alphabetic (a-z, A-Z) or numbers (0-9). Parameters:
| str | The string to test. |
| index | The index of a character in str. |
True if the character at the given index in str is an alpha-numeric character; false otherwise.
isFloat(string str, bool sciOk)
Returns true if the string is a float.
Parameters:
| str | The string to test. |
| sciOk | Test for correct scientific notation and accept it (ex. 1.2e+14) |
true if str is a float and false if not
isFloat( "13.5" ) // Returns true.
isInt(string str)
Returns true if the string is an integer.
Parameters:
| str | The string to test. |
true if str is an integer and false if not
isInt( "13" ) // Returns true.
isspace(string str, int index)
Test whether the character at the given position is a whitespace character.
Characters such as tab, space, or newline are considered whitespace. Parameters:
| str | The string to test. |
| index | The index of a character in str. |
True if the character at the given index in str is a whitespace character; false otherwise.
isValidIP(string str)
Returns true if the string is a valid ip address, excepts localhost.
Parameters:
| str | The string to test. |
true if str is a valid ip address and false if not
isValidIP( "localhost" ) // Returns true.
isValidPort(string str)
Returns true if the string is a valid port number.
Parameters:
| str | The string to test. |
true if str is a port and false if not
isValidPort( "8080" ) // Returns true.
ltrim(string str)
Remove leading whitespace from the string.
Parameters:
| str | A string. |
A string that is the same as str but with any leading (i.e. leftmost) whitespace removed.
ltrim( " string " ); // Returns "string ".
nextToken(string str1, string token, string delim)
Tokenize a string using a set of delimiting characters.
This function first skips all leading charaters in str that are contained in delimiters. From that position, it then scans for the next character in str that is contained in delimiters and stores all characters from the starting position up to the first delimiter in a variable in the current scope called token. Finally, it skips all characters in delimiters after the token and then returns the remaining string contents in str.
To scan out all tokens in a string, call this function repeatedly by passing the result it returns each time as the new str until the function returns "".
Parameters:
| str | A string. |
| token | The name of the variable in which to store the current token. This variable is set in the scope in which nextToken is called. |
| delimiters | A string of characters. Each character is considered a delimiter. |
The remainder of str after the token has been parsed out or "" if no more tokens were found in str.
// Prints: // a // b // c %str = "a b c"; while ( %str !$= "" ) { // First time, stores "a" in the variable %token and sets %str to "b c". %str = nextToken( %str, "token", " " ); echo( %token ); }
rtrim(string str)
Remove trailing whitespace from the string.
Parameters:
| str | A string. |
A string that is the same as str but with any trailing (i.e. rightmost) whitespace removed.
rtrim( " string " ); // Returns " string".
startsWith(string str, string prefix, bool caseSensitive)
Test whether the given string begins with the given prefix.
Parameters:
| str | The string to test. |
| prefix | The potential prefix of str. |
| caseSensitive | If true, the comparison will be case-sensitive; if false, differences in casing will not be taken into account. |
True if the first characters in str match the complete contents of prefix; false otherwise.
startsWith( "TEST123", "test" ) // Returns true.
strasc(string chr)
Return the integer character code value corresponding to the first character in the given string.
Parameters:
| chr | a (one-character) string. |
the UTF32 code value for the first character in the given string.
strchr(string str, string chr)
Find the first occurrence of the given character in str.
Parameters:
| str | The string to search. |
| chr | The character to search for. Only the first character from the string is taken. |
The remainder of the input string starting with the given character or the empty string if the character could not be found.
strchrpos(string str, string chr, int start)
Find the first occurrence of the given character in the given string.
Parameters:
| str | The string to search. |
| chr | The character to look for. Only the first character of this string will be searched for. |
| start | The index into str at which to start searching for the given character. |
The index of the first occurrence of chr in str or -1 if str does not contain the given character.
strchrpos( "test", "s" ) // Returns 2.
strcmp(string str1, string str2)
Compares two strings using case-sensitive comparison.
Parameters:
| str1 | The first string. |
| str2 | The second string. |
0 if both strings are equal, a value <0 if the first character different in str1 has a smaller character code value than the character at the same position in str2, and a value >1 otherwise.
if( strcmp( %var, "foobar" ) == 0 ) echo( "%var is equal to 'foobar'" );
strformat(string format, string value)
Format the given value as a string using printf-style formatting.
Parameters:
| format | A printf-style format string. |
| value | The value argument matching the given format string. |
// Convert the given integer value to a string in a hex notation. %hex = strformat( "%x", %value );
stricmp(string str1, string str2)
Compares two strings using case-insensitive comparison.
Parameters:
| str1 | The first string. |
| str2 | The second string. |
0 if both strings are equal, a value <0 if the first character different in str1 has a smaller character code value than the character at the same position in str2, and a value >0 otherwise.
if( stricmp( "FOObar", "foobar" ) == 0 ) echo( "this is always true" );
strinatcmp(string str1, string str2)
Compares two strings using "natural order" case-insensitive comparison.
Natural order means that rather than solely comparing single character code values, strings are ordered in a natural way. For example, the string "hello10" is considered greater than the string "hello2" even though the first numeric character in "hello10" actually has a smaller character value than the corresponding character in "hello2". However, since 10 is greater than 2, strnatcmp will put "hello10" after "hello2". Parameters:
| str1 | The first string. |
| str2 | The second string. |
0 if the strings are equal, a value >0 if str1 comes after str2 in a natural order, and a value <0 if str1 comes before str2 in a natural order.
// Bubble sort 10 elements of %array using natural order do { %swapped = false; for( %i = 0; %i < 10 - 1; %i ++ ) if( strnatcmp( %array[ %i ], %array[ %i + 1 ] ) > 0 ) { %temp = %array[ %i ]; %array[ %i ] = %array[ %i + 1 ]; %array[ %i + 1 ] = %temp; %swapped = true; } } while( %swapped );
stripChars(string str, string chars)
Remove all occurrences of characters contained in chars from str.
Parameters:
| str | The string to filter characters out from. |
| chars | A string of characters to filter out from str. |
A version of str with all occurrences of characters contained in chars filtered out.
stripChars( "teststring", "se" ); // Returns "tttring".
stripTrailingNumber(string str)
Strip a numeric suffix from the given string.
Parameters:
| str | The string from which to strip its numeric suffix. |
The string str without its number suffix or the original string str if it has no such suffix.
stripTrailingNumber( "test123" ) // Returns "test".
strIsMatchExpr(string pattern, string str, bool caseSensitive)
Match a pattern against a string.
Parameters:
| pattern | The wildcard pattern to match against. The pattern can include characters, '*' to match any number of characters and '?' to match a single character. |
| str | The string which should be matched against pattern. |
| caseSensitive | If true, characters in the pattern are matched in case-sensitive fashion against this string. If false, differences in casing are ignored. |
True if str matches the given pattern.
strIsMatchExpr( "f?o*R", "foobar" ) // Returns true.
strIsMatchMultipleExpr(string patterns, string str, bool caseSensitive)
Match a multiple patterns against a single string.
Parameters:
| patterns | A tab-separated list of patterns. Each pattern can include charaters, '*' to match any number of characters and '?' to match a single character. Each of the patterns is tried in turn. |
| str | The string which should be matched against patterns. |
| caseSensitive | If true, characters in the pattern are matched in case-sensitive fashion against this string. If false, differences in casing are ignored. |
True if str matches any of the given patterns.
strIsMatchMultipleExpr( "*.cs *.gui *.mis", "mymission.mis" ) // Returns true.
strlen(string str)
Get the length of the given string in bytes.
note:Parameters:This does not return a true character count for strings with multi-byte characters!
| str | A string. |
The length of the given string in bytes.
strlenskip(string str, string first, string last)
Calculate the length of a string in characters, skipping everything between and including first and last.
Parameters:
| str | A string. |
| first | First character to look for to skip block of text. |
| last | Second character to look for to skip block of text. |
The length of the given string skipping blocks of text between characters.
strlwr(string str)
Return an all lower-case version of the given string.
Parameters:
| str | A string. |
A version of str with all characters converted to lower-case.
strlwr( "TesT1" ) // Returns "test1"
strnatcmp(string str1, string str2)
Compares two strings using "natural order" case-sensitive comparison.
Natural order means that rather than solely comparing single character code values, strings are ordered in a natural way. For example, the string "hello10" is considered greater than the string "hello2" even though the first numeric character in "hello10" actually has a smaller character value than the corresponding character in "hello2". However, since 10 is greater than 2, strnatcmp will put "hello10" after "hello2". Parameters:
| str1 | The first string. |
| str2 | The second string. |
0 if the strings are equal, a value >0 if str1 comes after str2 in a natural order, and a value <0 if str1 comes before str2 in a natural order.
// Bubble sort 10 elements of %array using natural order do { %swapped = false; for( %i = 0; %i < 10 - 1; %i ++ ) if( strnatcmp( %array[ %i ], %array[ %i + 1 ] ) > 0 ) { %temp = %array[ %i ]; %array[ %i ] = %array[ %i + 1 ]; %array[ %i + 1 ] = %temp; %swapped = true; } } while( %swapped );
strpos(string haystack, string needle, int offset)
Find the start of needle in haystack searching from left to right beginning at the given offset.
Parameters:
| haystack | The string to search. |
| needle | The string to search for. |
The index at which the first occurrence of needle was found in haystack or -1 if no match was found.
strpos( "b ab", "b", 1 ) // Returns 3.
strposr(string haystack, string needle, int offset)
Find the start of needle in haystack searching from right to left beginning at the given offset.
Parameters:
| haystack | The string to search. |
| needle | The string to search for. |
The index at which the first occurrence of needle was found in heystack or -1 if no match was found.
strposr( "b ab", "b", 1 ) // Returns 2.
strrchr(string str, string chr)
Find the last occurrence of the given character in str.
Parameters:
| str | The string to search. |
| chr | The character to search for. Only the first character from the string is taken. |
The remainder of the input string starting with the given character or the empty string if the character could not be found.
strrchrpos(string str, string chr, int start)
Find the last occurrence of the given character in the given string.
Parameters:
| str | The string to search. |
| chr | The character to look for. Only the first character of this string will be searched for. |
| start | The index into str at which to start searching for the given character. |
The index of the last occurrence of chr in str or -1 if str does not contain the given character.
strrchrpos( "test", "t" ) // Returns 3.
strrepeat(string str, int numTimes, string delimiter)
Return a string that repeats str numTimes number of times delimiting each occurrence with delimiter.
Parameters:
| str | The string to repeat multiple times. |
| numTimes | The number of times to repeat str in the result string. |
| delimiter | The string to put between each repetition of str. |
A string containing str repeated numTimes times.
strrepeat( "a", 5, "b" ) // Returns "ababababa".
strreplace(string source, string from, string to)
Replace all occurrences of from in source with to.
Parameters:
| source | The string in which to replace the occurrences of from. |
| from | The string to replace in source. |
| to | The string with which to replace occurrences of @from. |
A string with all occurrences of from in source replaced by to.
strreplace( "aabbccbb", "bb", "ee" ) // Returns "aaeeccee".
strstr(string string, string substring)
Find the start of substring in the given string searching from left to right.
Parameters:
| string | The string to search. |
| substring | The string to search for. |
The index into string at which the first occurrence of substring was found or -1 if substring could not be found.
strstr( "abcd", "c" ) // Returns 2.
strToggleCaseToWords(string str)
Parse a Toggle Case word into separate words.
Parameters:
| str | The string to parse. |
new string space separated.
strToggleCaseToWords( "HelloWorld" ) // Returns "Hello World".
strupr(string str)
Return an all upper-case version of the given string.
Parameters:
| str | A string. |
A version of str with all characters converted to upper-case.
strupr( "TesT1" ) // Returns "TEST1"
trim(string str)
Remove leading and trailing whitespace from the string.
Parameters:
| str | A string. |
A string that is the same as str but with any leading (i.e. leftmost) and trailing (i.e. rightmost) whitespace removed.
trim( " string " ); // Returns "string".