Functions for Strings

CountStringTokens function

Counts how many string-separated tokens a string contains.

Synopsis

%tokens = CountStringTokens("one;two;three;four", ";") // sets %tokens to 4

Parameters

Returns

• If string is an empty string, returns 0.

• Otherwise, returns the number of occurrences of separator in string, plus 1.

FormatString_inplace function

Synopsis

%result = 42
%message = FormatString_inplace("The result is %result")

Parameters

Returns

The function returns a string in which all references to local and global variables are replaced by the respective stored values.

GetStringToken function

Returns one token from a token string.

Synopsis

%sub_token = GetStringToken("one;two;three;four", ";", 1) // sets %sub_token to "two"

Parameters

Returns

• If index is a number equal to or greater than zero and less than the value returned by CountStringTokens, returns the portion of string between the (index-1)-th and index-th occurrence of separator.

  • For index equal to 0, this is the portion of string before the first separator.

  • For index equal to the result of CountStringTokens, this is the portion of string after the last separator.

• Otherwise, returns an empty string.

regex_match function

Matches a string against a regular expression.

Synopsis

%res = regex_match("Hello world", "[he]+ll..w.*", icase) // result: 1
%res = regex_match("Hello world", "ll..w", icase) // result: 0

Parameters

Returns

1 if string matches regex, and 0 otherwise.

Remarks

• The match is case insensitive if the icase parameter is present and has the value "icase" in any combination of upper and lower case characters.

• The regular expression uses ECMAScript syntax.

regex_search function

Searches within a string for a substring that matches the regular expression.

Synopsis

%res = regex_search("Hello world", "LL..w") // result: 0
%res = regex_search("Hello world", "LL..w", icase) // result: 1

Parameters

Returns

1 if string contains a portion that matches regex, and 0 otherwise.

Remarks

• The match is case insensitive if the icase parameter is present and has the value "icase" in any combination of upper and lower case characters.

• The regular expression uses ECMAScript syntax.

replacechr function

Replaces all occurrences of a character in a string by another character.

Synopsis

%result = replacechr("Hello world", "o", "x") // result: "Hellx wxrld"

Parameters

Returns

The string string, with all occurrences of search replaced by replace.

Remarks

• If either search or replace (or both) are empty strings, replacechr returns string.

• If search or replace are more than 1 character long, only the first character is used.

strcat function

Concatenates several strings into one.

Synopsis

%message = strcat("We have ", %number_of_hens, " and they have laid ", %number_of_eggs, ", of which ", %number_of_broken, " were broken.")

Parameters

strcat takes from one to any number of parameters. Numeric values are implicitly converted into strings.

Returns

The function returns a string which is created from the concatenation of the values from all parameters.

strchr, strrchr functions

Finds the first or last occurrence of a character within a string.

Synopsis

%first_pos = strchr("Hello world", "o") // returns 4
%last_pos  = strrchr("Hello world", "o") // returns 7

Parameters

Returns

The 0-based offset of the position of the first (for strchr) or last (strrchr) occurrence of the first character of char within str.

strcmp function

Compares two strings for equality.

Synopsis

if (strcmp(%data, "OK", icase))
{
  return
}

Parameters

Returns

• If string1 and string2 are identical with respect to length and content, returns 1.

• If ignore_case is present and contains the value "icase", and string1 and string2 are identical with respect to length and content, except for upper and lower case, return 1.

• Otherwise returns 0.

strlen function

Counts the characters in a string.

Synopsis

%str = "This is my string."
%len = strlen(%str)

Parameters

Returns

The number of characters in string. (If stringis a number, it is converted into a string before the length is calculated.)

strsearch function

Returns a value that indicates whether a string contains a certain sub string.

Synopsis

%contains = strsearch("YesNo", %answer, icase)

Parameters

Returns

• If search_string is an empty string, returns 1.

• Otherwise, if search_string is exactly contained in string, returns 1.

• Otherwise, if ignore_case is specified as "icase", and search_string is contained in string if upper/lower case is not regarded, returns 1.

• Otherwise, returns 0.

strstr function

Returns the offset of a sub string within a string.

Synopsis

%position = strstr("YesNo", %answer, icase)

Parameters

Returns

• If search_string is an empty string, returns 0.

• Otherwise, if ignore_case is specified as "icase", and search_string is contained in string if upper/lower case is not regarded, returns the offset of the first occurrence of search_string from the start of string.

• Otherwise, if search_string is exactly contained in string, returns the offset of the first occurrence of search_string from the start of string.

• Otherwise, returns -1.

strupper function

Converts a string into all upper case.

Synopsis

%upper = strupper("Hello world!") // result: "HELLO WORLD!"

Parameters

Returns

The string str, converted to upper case.

substr function

Returns a part of a string.

Synopsis

%sub = substr("Hello world", 4, 3) // assigns "o w" to %sub

Parameters

Returns

• If start is negative or equal to or greater than the length of string, returns an empty string.

• Otherwise, if length is not supplied or is zero or negative, returns the part of string that starts at offset and extends to the end of the string.

• Otherwise returns the part of string that starts at offset start and extends to the end of the string, but at most length characters.

string function

Converts a value into a string.

Synopsis

%str = string(%my_value)

Parameters

Returns

• If value is a string returns value.

• Otherwise, converts value into a string and returns it as string.