Strings
[Core]

Functions for dealing with string values. More...

Modules
	Field Manipulators
	Functions to deal with whitespace-separated lists of values in strings.
Functions
string	collapseEscape (string text)
	Replace all escape sequences in text with their respective character codes.
void	dumpStringMemStats ()
	Dumps information about String memory usage.
bool	endsWith (string str, string suffix, bool caseSensitive=false)
	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=-1)
	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	isspace (string str, int index)
	Test whether the character at the given position is a whitespace character.
string	ltrim (string str)
	Remove leading whitespace from the string.
string	nextToken (string str, string token, string delimiters)
	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=false)
	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=0)
	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=false)
	Match a pattern against a string.
bool	strIsMatchMultipleExpr (string patterns, string str, bool caseSensitive=false)
	Match a multiple patterns against a single string.
int	strlen (string str)
	Get the length of the given string in bytes.
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=0)
	Find the start of needle in haystack searching from left to right 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=0)
	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	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 for dealing with string values.

Since in TorqueScript any value is implicitly also a string, these functions can be used with all values.

---

Function Documentation

string 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.

Returns:

A duplicate of text with all escape sequences replaced by their respective character codes.

Example:

// 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" ) );

See also:

expandEscape

void dumpStringMemStats

(

)

Dumps information about String memory usage.

bool endsWith	(	string	str,
		string	suffix,
		bool	caseSensitive = false
	)

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.

Returns:

True if the last characters in str match the complete contents of suffix; false otherwise.

Example:

startsWith( "TEST123", "123" ) // Returns true.

See also:

startsWith

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.

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

Returns:

A duplicate of the text parameter with all unescaped characters that cannot appear in string literals replaced by their respective escape sequences.

expandEscape( "str" NL "ing" ) // Returns "str\ning".

See also:

collapseEscape

string getSubStr	(	string	str,
		int	start,
		int	numChars = -1
	)

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.

Returns:

A string that contains the given portion of the input string.

Example:

getSubStr( "foobar", 1, 2 ) // Returns "oo".

int getTrailingNumber

(

string

str

)

Get the numeric suffix of the given input string.

Parameters:

str

The string from which to read out the numeric suffix.

Returns:

The numeric value of the number suffix of str or -1 if str has no such suffix.

Example:

getTrailingNumber( "test123" ) // Returns '123'.

See also:

stripTrailingNumber

bool 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.

Returns:

True if the character at the given index in str is an alpha-numeric character; false otherwise.

See also:

isspace

bool 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.

Returns:

True if the character at the given index in str is a whitespace character; false otherwise.

See also:

isalnum

string ltrim

(

string

str

)

Remove leading whitespace from the string.

Parameters:

str

A string.

Returns:

A string that is the same as str but with any leading (i.e. leftmost) whitespace removed.

Example:

ltrim( "   string  " ); // Returns "string  ".

See also:

rtrim

trim

string nextToken	(	string	str,
		string	token,
		string	delimiters
	)

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.

Returns:

The remainder of str after the token has been parsed out or "" if no more tokens were found in str.

Example:

// 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 );
}

string rtrim

(

string

str

)

Remove trailing whitespace from the string.

Parameters:

str

A string.

Returns:

A string that is the same as str but with any trailing (i.e. rightmost) whitespace removed.

Example:

rtrim( "   string  " ); // Returns "   string".

See also:

ltrim

trim

bool startsWith	(	string	str,
		string	prefix,
		bool	caseSensitive = false
	)

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.

Returns:

True if the first characters in str match the complete contents of prefix; false otherwise.

Example:

startsWith( "TEST123", "test" ) // Returns true.

See also:

endsWith

int strasc

(

string

chr

)

Return the integer character code value corresponding to the first character in the given string.

Parameters:

chr

a (one-character) string.

Returns:

the UTF32 code value for the first character in the given string.

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.

Returns:

The remainder of the input string starting with the given character or the empty string if the character could not be found.

See also:

strrchr

int strchrpos	(	string	str,
		string	chr,
		int	start = 0
	)

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.

Returns:

The index of the first occurrence of chr in str or -1 if str does not contain the given character.

Example:

strchrpos( "test", "s" ) // Returns 2.

int strcmp	(	string	str1,
		string	str2
	)

Compares two strings using case-sensitive comparison.

Parameters:

	str1	The first string.
	str2	The second string.

Returns:

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.

Example:

if( strcmp( %var, "foobar" ) == 0 )
   echo( "%var is equal to 'foobar'" );

See also:

stricmp

strnatcmp

string 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.

Example:

// Convert the given integer value to a string in a hex notation.
%hex = strformat( "%x", %value );

See also:

http://en.wikipedia.org/wiki/Printf

int stricmp	(	string	str1,
		string	str2
	)

Compares two strings using case-insensitive comparison.

Parameters:

	str1	The first string.
	str2	The second string.

Returns:

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.

Example:

if( stricmp( "FOObar", "foobar" ) == 0 )
   echo( "this is always true" );

See also:

strcmp

strinatcmp

int 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.

Returns:

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.

Example:

// 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 );

See also:

stricmp

strnatcmp

string 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.

Returns:

A version of str with all occurrences of characters contained in chars filtered out.

Example:

stripChars( "teststring", "se" ); // Returns "tttring".

String stripTrailingNumber

(

string

str

)

Strip a numeric suffix from the given string.

Parameters:

str

The string from which to strip its numeric suffix.

Returns:

The string str without its number suffix or the original string str if it has no such suffix.

Example:

stripTrailingNumber( "test123" ) // Returns "test".

See also:

getTrailingNumber

bool strIsMatchExpr	(	string	pattern,
		string	str,
		bool	caseSensitive = false
	)

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.

Returns:

True if str matches the given pattern.

Example:

strIsMatchExpr( "f?o*R", "foobar" ) // Returns true.

See also:

strIsMatchMultipleExpr

bool strIsMatchMultipleExpr	(	string	patterns,
		string	str,
		bool	caseSensitive = false
	)

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.

Returns:

True if str matches any of the given patterns.

Example:

strIsMatchMultipleExpr( "*.cs *.gui *.mis", "mymission.mis" ) // Returns true.

See also:

strIsMatchExpr

int strlen

(

string

str

)

Get the length of the given string in bytes.

Note:

This does not return a true character count for strings with multi-byte characters!

Parameters:

str

A string.

Returns:

The length of the given string in bytes.

string strlwr

(

string

str

)

Return an all lower-case version of the given string.

Parameters:

str

A string.

Returns:

A version of str with all characters converted to lower-case.

Example:

strlwr( "TesT1" ) // Returns "test1"

See also:

strupr

int 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.

Returns:

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.

Example:

// 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 );

See also:

strcmp

strinatcmp

int strpos	(	string	haystack,
		string	needle,
		int	offset = 0
	)

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.

Returns:

The index at which the first occurrence of needle was found in haystack or -1 if no match was found.

Example:

strpos( "b ab", "b", 1 ) // Returns 3.

string 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.

Returns:

The remainder of the input string starting with the given character or the empty string if the character could not be found.

See also:

strchr

int strrchrpos	(	string	str,
		string	chr,
		int	start = 0
	)

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.

Returns:

The index of the last occurrence of chr in str or -1 if str does not contain the given character.

Example:

strrchrpos( "test", "t" ) // Returns 3.

string 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.

Returns:

A string containing str repeated numTimes times.

Example:

strrepeat( "a", 5, "b" ) // Returns "ababababa".

string 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 .

Returns:

A string with all occurrences of from in source replaced by to.

Example:

strreplace( "aabbccbb", "bb", "ee" ) // Returns "aaeeccee".

int 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.

Returns:

The index into string at which the first occurrence of substring was found or -1 if substring could not be found.

Example:

strstr( "abcd", "c" ) // Returns 2.

string strupr

(

string

str

)

Return an all upper-case version of the given string.

Parameters:

str

A string.

Returns:

A version of str with all characters converted to upper-case.

Example:

strupr( "TesT1" ) // Returns "TEST1"

See also:

strlwr

string trim

(

string

str

)

Remove leading and trailing whitespace from the string.

Parameters:

str

A string.

Returns:

A string that is the same as str but with any leading (i.e. leftmost) and trailing (i.e. rightmost) whitespace removed.

Example:

trim( "   string  " ); // Returns "string".