The following is a list of string functions that can be used when writing Templates or Scripts.

double Atof( const char s[] )
Converts a string to a floating-point number. Returns zero on error.

int Atoi( const char s[] )
Converts a string to an integer. Returns zero on error.

int64 BinaryStrToInt( const char s[] )
Converts a string containing a binary number s to an integer and returns the result. For example:

      return BinaryStrToInt( "01001101" ); 

would return the number 77. If the string is not a valid binary string, zero is returned.

char[] ConvertString( const char src[], int srcCharSet, int destCharSet )
Given a string src that uses the character set encoding srcCharSet, the string is converted to use the character set encoding destCharSet and returned as a string. The following character set constants exist:

• CHARSET_ASCII
• CHARSET_ANSI
• CHARSET_OEM
• CHARSET_EBCDIC
• CHARSET_UNICODE
• CHARSET_MAC
• CHARSET_ARABIC
• CHARSET_BALTIC
• CHARSET_CHINESE_S
• CHARSET_CHINESE_T
• CHARSET_CYRILLIC
• CHARSET_EASTEUROPE
• CHARSET_GREEK
• CHARSET_HEBREW
• CHARSET_JAPANESE
• CHARSET_KOREAN_J
• CHARSET_KOREAN_W
• CHARSET_THAI
• CHARSET_TURKISH
• CHARSET_VIETNAMESE
• CHARSET_UTF8
• CHARSET_ARABIC_ISO
• CHARSET_BALTIC_ISO
• CHARSET_CYRILLIC_KOI8R
• CHARSET_CYRILLIC_KOI8U
• CHARSET_CYRILLIC_ISO
• CHARSET_EASTEUROPE_ISO
• CHARSET_GREEK_ISO
• CHARSET_HEBREW_ISO
• CHARSET_JAPANESE_EUCJP
• CHARSET_TURKISH_ISO

Custom character sets can also be specified using the ID Number specified in the Character Set Options dialog. This function should not be used with Unicode character sets (CHARSET_UNICODE). To perform conversions with Unicode strings see the StringToWString and WStringToString functions.

string DosDateToString( DOSDATE d, char format[] = "MM/dd/yyyy" )
Converts the given DOSDATE into a string and returns the results. By default the date will be in the format 'MM/dd/yyyy' but other formats can be used as described in the GetCurrentDateTime function. Click here for more information on the DOSDATE type and see the FileTimeToString function for an example of using SScanf to parse the resulting string.

string DosTimeToString( DOSTIME t, char format[] = "hh:mm:ss" )
Converts the given DOSTIME into a string and returns the results. By default the time will be in the format 'hh:mm:ss' but other formats can be used as described in the GetCurrentDateTime function. Click here for more information on the DOSTIME type and see the FileTimeToString function for an example of using SScanf to parse the resulting string.

string EnumToString( enum e )
If the given variable e is an enum, the value is converted into the string which represents that enum value and returned. The enum may be a constant or an enum variable. For example:

     enum { FIRST, SECOND, THIRD } value;
     string s1, s2;
     value = SECOND;
     s1 = EnumToString( THIRD ); //s1 = "THIRD"
     s2 = EnumToString( value ); //s2 = "SECOND"

char[] FileNameGetBase( const char path[], int includeExtension=true )
wchar_t[] FileNameGetBaseW( const wchar_t path[], int includeExtension=true )
When called with a full path name for a file in path, this function removes the path name and returns the resulting string. If includeExtension is true, the file path will still contain any file extension if it exists, or if false the file extension is removed. For example:

      return FileNameGetBase( "C:\\temp\\file.dat" ); 

would return "file.dat", and

      return FileNameGetBase( "C:\\temp\\file.dat", false );

would return "file". FileNameGetBaseW works in the same way except this function accepts a Unicode string and returns a Unicode string.

char[] FileNameGetExtension( const char path[] )
wchar_t[] FileNameGetExtensionW( const wchar_t path[] )
Given a file name path, this function returns the extension for the file name including the '.'. For example:

      return FileNameGetExtension( "C:\\temp\\file.dat" ); 

would return ".dat". FileNameGetExtensionW works the same way except the path is a Unicode string and a Unicode string is returned.

char[] FileNameGetPath( const char path[], int includeSlash=true )
wchar_t[] FileNameGetPathW( const wchar_t path[], int includeSlash=true )
Given a full file name path, this function returns just the path portion of the file name. If includeSlash is true, the last character in the returned path will be a slash. For example:.

      return FileNameGetPath( "C:\\temp\\file.dat" );

would return "C:\temp\", and

      return FileNameGetPath( "C:\\temp\\file.dat", false ); 

would return "C:\temp". FileNameGetBaseW operates the same way but accepts a Unicode path and returns a Unicode string.

char[] FileNameSetExtension( const char path[], const char extension[] )
wchar_t[] FileNameSetExtensionW( const wchar_t path[], const wchar_t extension[] )
This function takes as input a file name path and an extension. The function then removes any existing extension in path, appends the new extension and then returns the resulting string. Note that extension may or may not start with a '.' character and the original path argument is not modified. For example:

      return FileNameSetExtension( "C:\\temp\\file.dat", "bmp" ); 

would return "C:\temp\file.bmp". Similarly, FileNameSetExtensionW can be used on Unicode strings and a Unicode string is returned.

string FileTimeToString( FILETIME ft, char format[] = "MM/dd/yyyy hh:mm:ss" )
Converts the given FILETIME into a string and returns the results. By default the time will be in the format 'MM/dd/yyyy hh:mm:ss' but other formats can be used as described in the GetCurrentDateTime function. Click here for more information on the FILETIME type. The resulting string can be separated into parts using the SScanf function. For example:

     int hour, minute, second, day, month, year;
     string s = FileTimeToString( ft );
     SScanf( s, "%02d/%02d/%04d %02d:%02d:%02d", 
         month, day, year, hour, minute, second );
     year++;
     SPrintf( s, "%02d/%02d/%04d %02d:%02d:%02d", 
         month, day, year, hour, minute, second );

string GUIDToString( GUID g )
Given a GUID g, the GUID is converted into a string in the format "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}" and returned. Note that a GUID is the same as an array of 16 unsigned bytes (see Data Types, Typedefs, and Enums). See StringToGUID to convert from a string to a GUID.

char[] IntToBinaryStr( int64 num, int numGroups=0, int includeSpaces=true )
Takes an input an integer num and returns that number converted to a binary string. The returned string will contain as many groups of 8 binary digits as are necessary to represent the number, and the minimum number of groups returned can be controlled with the numGroups parameter. If includeSpaces is true, a space will be included between each group. For example:

      return IntToBinaryStr( 1132 ); 

would return "00000100 01101100" and

      return IntToBinaryStr( 62, 2, false ); 

would return "0000000000111110".

int IsCharAlpha( char c )
int IsCharAlphaW( wchar_t c )
Returns true if the given character c is a letter or false otherwise.

int IsCharNum( char c )
int IsCharNumW( wchar_t c )
Returns true if the given character c is a number or false otherwise.

int IsCharAlphaNum( char c )
int IsCharAlphaNumW( wchar_t c )
Returns true if the given character c is a letter or number, or false otherwise.

int IsCharPunct( char c )
int IsCharPunctW( wchar_t c )
Returns true if the given character c is punctuation, or false otherwise. Punctuation includes the characters !"#%&'()*,-./:;?@[\]_{}

int IsCharSymbol( char c )
int IsCharSymbolW( wchar_t c )
Returns true if the given character c is a symbol, or false otherwise. Symbols include the characters $+<=>^`|~

int IsCharWhitespace( char c )
int IsCharWhitespaceW( wchar_t c )
Returns true if the given character c is a space, tab, or linefeed character.

int Memcmp( const uchar s1[], const uchar s2[], int n )
Compares the first n bytes of s1 and s2. Returns a value less than zero if s1 is less than s2, zero if they are equal, or a value greater than zero if s1 is greater than s2.

void Memcpy( uchar dest[], const uchar src[], int n, int destOffset=0, int srcOffset=0 )
Copies a block of n bytes from src to dest. If srcOffset is not zero, the bytes are copied starting from the srcOffset byte in src. If destOffset is not zero, the bytes are copied to dest starting at the byte destOffset. See the WMemcpy function for copying wchar_t data.

void Memset( uchar s[], int c, int n )
Sets the first n bytes of s to the byte c.

string OleTimeToString( OLETIME ot, char format[] = "MM/dd/yyyy hh:mm:ss" )
Converts the given OLETIME into a string and returns the results. By default the time will be in the format 'MM/dd/yyyy hh:mm:ss' but other formats can be used as described in the GetCurrentDateTime function. Click here for more information on the OLETIME type and see the FileTimeToString function for an example of using SScanf to parse the resulting string.

int RegExMatch( string str, string regex );
int RegExMatchW( wstring str, wstring regex );
Attempts to match the Regular Expression regex with the string str. For the RegExMatch function both strings are assumed to be in ASCII+ANSI format and for the RegExMatchW function both strings are in Unicode format. These functions return 1 if the regular expression completely matches the string, 0 if they do not match, or -1 if regex is an invalid regular expression. To match just part of a string see the RegExSearch function. For example, to test if an email address is valid use:

      if( RegExMatch( "test@test.ca", 
          "\\b[A-Za-z0-9.%_+\\-]+@[A-Za-z0-9.\\-]+\\.[A-Za-z]{2,4}\\b" ) 
          == false )
      {
          Warning( "Invalid email address" );
          return -1;
      } 

int RegExSearch( string str, string regex, int &matchSize, int startPos=0 );
int RegExSearchW( wstring str, wstring regex, int &matchSize, int startPos=0 );
Searches for an occurrence of the Regular Expression regex within the string str. Use RegExSearch to search ASCII+ANSI strings or the RegExSearchW function to search Unicode strings. These functions return the index of the first matching character in str if a match is found, -1 if no match is found, or -2 if the regular expression is invalid. The number of characters in the match will be stored in the matchSize parameter. By default the search starts from the first character of str but to specify a different starting character use the startPos parameter. For example, to search for an IP address within a string use:

      int result, size;
      result = RegExSearch( 
          "12:03:23 AM - 192.168.0.10 : www.sweetscape.com/",
          "\\d{1,3}\\.\\d{1,3}.\\d{1,3}.\\d{1,3}", size );
      Printf( "Match at pos %d of size %d\n", result, size ); 

This code would display: 'Match at pos 14 of size 12'.

int SPrintf( char buffer[], const char format[] [, argument, ... ] )
Performs a Printf starting from format and places the result into buffer. See Printf for more information. This function is similar to the Str function.

int SScanf( char str[], char format[], ... )
This function parses the str parameter into a number of variables according to the format string. The format string uses the same specifiers as the Printf function. Following the format must be a list of arguments, one for each format specifier in the format string. Note that unlike the regular C function, do not use '&' for each argument. For example:

     int a, b;
     SScanf( "34, 62", "%d, %d", a, b );

would read the value 34 and 62 into a and b. The return value will be the number of successfully read arguments (in this example the return value would be 2).

string Str( const char format[] [, argument, ... ] )
Similar to the Printf function except the generated output is returned as a string instead of being displayed in the Output Window. This function is useful when writing inline read functions and is similar to the SPrintf function. For a list of supported formats see the Printf function.

void Strcat( char dest[], const char src[] )
Appends the characters from src to the end of the string dest. The string may be resized if necessary. The += operator can also be used for a similar result.

int Strchr( const char s[], char c )
Scans the string s for the first occurrence of the character c. Returns the index of the match, or -1 if no characters match.

int Strcmp( const char s1[], const char s2[] )
Compares the one string to another. Returns a value less than zero if s1 is less than s2, zero if they are equal, or a value greater than zero if s1 is greater than s2.

void Strcpy( char dest[], const char src[] )
Copies string src to string dest, stopping when the null-character has been copied.

char[] StrDel( const char str[], int start, int count )
Removes count characters from str starting at the index start and returns the resulting string.

int Stricmp( const char s1[], const char s2[] )
Identical to Strcmp except the strings are compared without case sensitivity.

int StringToDosDate( string s, DOSDATE &d, char format[] = "MM/dd/yyyy" )
Converts the given string into a DOSDATE and stores the results in d. The format of the date string is given with the format parameter and is by default 'MM/dd/yyyy' but other formats can be used as described in the GetCurrentDateTime function. This function returns 0 if it succeeds or a negative number on failure. More information on date types is available here.

int StringToDosTime( string s, DOSTIME &t, char format[] = "hh:mm:ss" )
Converts the given string into a DOSTIME and stores the results in t. The format of the time string is given with the format parameter and is by default 'hh:mm:ss' but other formats can be used as described in the GetCurrentDateTime function. This function returns 0 if it succeeds or a negative number on failure. More information on date types is available here.

int StringToFileTime( string s, FILETIME &ft, char format[] = "MM/dd/yyyy hh:mm:ss" )
Converts the given string into a FILETIME and stores the results in ft. The format of the time string is given with the format parameter and is by default 'MM/dd/yyyy hh:mm:ss' but other formats can be used as described in the GetCurrentDateTime function. This function returns 0 if it succeeds or a negative number on failure. More information on date types is available here.

int StringToGUID( string str, GUID g )
Given a string str in the format "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}" where each X is 0..9 or A..F, the string is converted into a GUID and stored in the g parameter. Note that a GUID is the same as an array of 16 unsigned bytes (see Data Types, Typedefs, and Enums). A negative number is returned if the string could not be converted or zero is returned on success. See GUIDToString to convert from a GUID to a string.

int StringToOleTime( string s, OLETIME &ot, char format[] = "MM/dd/yyyy hh:mm:ss" )
Converts the given string into an OLETIME and stores the results in ot. The format of the string is given with the format parameter and is by default 'MM/dd/yyyy hh:mm:ss' but other formats can be used as described in the GetCurrentDateTime function. This function returns 0 if it succeeds or a negative number on failure. More information on date types is available here.

int StringToTimeT( string s, time_t &t, char format[] = "MM/dd/yyyy hh:mm:ss" )
Converts the given string into a time_t and stores the results in t. The format of the string is given with the format parameter and is by default 'MM/dd/yyyy hh:mm:ss' but other formats can be used as described in the GetCurrentDateTime function. This function returns 0 if it succeeds or a negative number on failure. More information on date types is available here.

int StringToTime64T( string s, time64_t &t, char format[] = "MM/dd/yyyy hh:mm:ss" )
Converts the given string into a time64_t and stores the results in t. The format of the string is given with the format parameter and is by default 'MM/dd/yyyy hh:mm:ss' but other formats can be used as described in the GetCurrentDateTime function. This function returns 0 if it succeeds or a negative number on failure. More information on date types is available here.

char[] StringToUTF8( const char src[], int srcCharSet=CHARSET_ANSI )
Takes as input a string src which uses the character set encoding srcCharSet. The string is converted to the UTF-8 character set and returned. The list of character set constants is available in the ConvertString function and this function is equivalent to 'ConvertString( src, srcCharSet, CHARSET_UTF8 );'.

wstring StringToWString( const char str[], int srcCharSet=CHARSET_ANSI )
Converts the given string str into a wide (unicode) string. str is assumed to be an ANSI string but other character sets can be specified using the srcCharSet parameter (see the ConvertString function for a list of character set constants). See Strings for information on wide strings and note that wstring and wchar_t[] are equivalent.

int Strlen( const char s[] )
Returns the number of bytes in s before the null-character.

int Strncmp( const char s1[], const char s2[], int n )
Similar to Strcmp, except that no more than n characters are compared.

void Strncpy( char dest[], const char src[], int n )
Similar to Strcpy, except that at most n characters will be copied.

int Strnicmp( const char s1[], const char s2[], int n )
Similar to Strcmp except that at most n characters are compared and the characters are compared without case sensitivity.

int Strstr( const char s1[], const char s2[] )
Scans the string s1 for the first occurrence of s2. Returns the index of the first matching character, or -1 if no match is found.

char[] SubStr( const char str[], int start, int count=-1 )
Returns a string containing count characters from str starting at the index start. If count is -1, all the characters from the start index to the end of the string are returned.

string TimeTToString( time_t t, char format[] = "MM/dd/yyyy hh:mm:ss" )
Converts the given time_t into a string and returns the results. By default the time will be in the format 'MM/dd/yyyy hh:mm:ss' but other formats can be used as described in the GetCurrentDateTime function. Click here for more information on the time_t type and see the FileTimeToString function for an example of using SScanf to parse the resulting string.

string Time64TToString( time64_t t, char format[] = "MM/dd/yyyy hh:mm:ss" )
Converts the given time64_t into a string and returns the results. By default the time will be in the format 'MM/dd/yyyy hh:mm:ss' but other formats can be used as described in the GetCurrentDateTime function. Click here for more information on the time64_t type and see the FileTimeToString function for an example of using SScanf to parse the resulting string.

char ToLower( char c )
wchar_t ToLowerW( wchar_t c )
Takes as input a character c, converts the character to lowercase and then returns the result. If the character cannot be converted to lowercase, the unmodified character is returned. For example:

      return ToLower( 'A' );

would return 'a'. The ToLowerW function operates on wide characters and handles converting Unicode characters to lowercase.

char ToUpper( char c )
wchar_t ToUpperW( wchar_t c )
Returns the given character c converted to an uppercase character. If the character cannot be converted to uppercase the same character is returned. For example:

      return ToUpper( 'c' ); 

would return 'C'. Use the ToUpperW function to convert Unicode characters to uppercase.

void WMemcmp( const wchar_t s1[], const wchar_t s2[], int n )
Compares the first n wchar_t items of the arrays s1 and s2. This function returns a value less than zero if s1 is less than s2, zero if they are equal, or a value greater than zero if s1 is greater than s2.

void WMemcpy( wchar_t dest[], const wchar_t src[], int n, int destOffset=0, int srcOffset=0 )
Copies n wchar_t items from the array src to the array dest. If srcOffset is not zero, the bytes are copied starting from the srcOffset index in src. If destOffset is not zero, the bytes are copied to dest starting at the index destOffset. See the Memcpy function for copying byte data.

void WMemset( wchar_t s[], int c, int n )
Sets the first n wchar_t items of the array s to the value c.

void WStrcat( wchar_t dest[], const wchar_t src[] )
Appends all characters from the src string to the end of the dest string. Note that the string may be resized if required and the += operator can also be used for a similar result.

int WStrchr( const wchar_t s[], wchar_t c )
Searchs through the string s for the first occurrence of the character c. If the character is found, this function returns the index of the match, otherwise -1 is returned.

int WStrcmp( const wchar_t s1[], const wchar_t s2[] )
Use this function to compare one wide string to another. Returns a value less than zero if s1 is less than s2, zero if they are equal, or a value greater than zero if s1 is greater than s2.

void WStrcpy( wchar_t dest[], const wchar_t src[] )
Copies the string src to the string dest, stopping when the null-character has been copied.

wchar_t[] WStrDel( const whar_t str[], int start, int count )
Returns a string where count characters have been removed from the string str starting at the index start. Note that the str argument is not modified.

int WStricmp( const wchar_t s1[], const wchar_t s2[] )
Identical to WStrcmp except the strings are compared without case sensitivity.

char[] WStringToString( const wchar_t str[], int destCharSet=CHARSET_ANSI )
Converts the given wide string str by default into an ANSI string and returns it. The string can be converted to other character sets using the destCharSet parameter (see the ConvertString function for a list of character set constants). Note that not all characters can be successfully converted from wide characters to other character sets and any characters that cannot be converted will be replaced with the '?' character. See Strings for information on wide strings and note that wstring and wchar_t[] are equivalent.

char[] WStringToUTF8( const wchar_t str[] )
Takes as input a Unicode string str which is then converted to the UTF-8 character set and returned as a string.

int WStrlen( const wchar_t s[] )
Counts the number of characters in s before the null-character is encountered and returns the result.

int WStrncmp( const wchar_t s1[], const wchar_t s2[], int n )
Similar to WStrcmp, except that at most n characters are compared between the two strings.

void WStrncpy( wchar_t dest[], const wchar_t src[], int n )
Similar to WStrcpy, except that at most n characters will be copied.

int WStrnicmp( const wchar_t s1[], const wchar_t s2[], int n )
Similar to WStrcmp except that at most n characters are compared and the characters are compared without case sensitivity.

int WStrstr( const wchar_t s1[], const wchar_t s2[] )
Searches through the wide string s1 for the first occurrence of the string s2. If the string is found, the index of the first matching character is returned, otherwise -1 is returned.

wchar_t[] WSubStr( const wchar_t str[], int start, int count=-1 )
Returns a wide string containing count characters from str starting at the index start. If count is -1, all the characters from the start index to the end of the string are returned.