String Functions

These functions provide string handling. Prior to version 3.0.6, many of them used an approach to memory management chosen for absolute minimal memory footprint. A function using this approach constructed its output string in its own string buffer, reusing that buffer each time it was called. When a function using this approach returned a string value it returned its buffer. In consequence the strings returned by these functions were to be either used or saved before the function was called again.

By the release of version 3.0.6, all string values are local copies, and the save and strsave functions should be entirely unnecessary.

Lower and upper convert the letters in their arguments to lower or upper case, respectively. Capitalize converts the first character of the argument, if it is a letter, to upper case. Lower and upper historically used the buffer return method; capitalize operates on and returns its argument.

Trim shortens a string to the length specified by the second parameter. If the string is already of that length or shorter the string is not changed. Rjustify right justifies a string into another string of the length specified by the second parameter. If the original string is shorter than the justified string, blanks are inserted to the left of the original string; if the string is longer than the justified string, the original string is truncated on the right. Trim historically used the buffer return method; rjustify creates and returns a new string.

Save creates a copy of the argument string and returns it. This function is required because built-in functions that return strings use the buffer return method; if a string is to be used repeatedly or long after it is returned from a function, it should first be saved by using the save function. Strsave is the same function as save. With version 3.0.6 or later, this should be unnecessary.

Concat and strconcat catenate strings and return the result. They are identical functions. They may take two to 32 string arguments; null arguments are allowed. The arguments are catenated together into a single, newly allocated string, which is returned.

Strlen returns the length of the string argument.

Substring returns a substring of the first argument string. The second and third arguments are the indices of the first and last characters in the argument string to use to form the substring. The indexes are relative one. Substring historically used the buffer return method.

Index returns the character index of the nth occurrence of a substring within a string. The index is the relative one character offset to the beginning of the substring. The first argument is the string; the second argument is the substring; and the third argument is the occurrence number.

D, card, ord, alpha and roman convert integers to strings. D converts an integer to a numeric string; card converts an integer to a cardinal number string (eg, one, two, three); ord converts an integer to an ordinal number (eg, first, second, third); alpha converts an integer to a letter (eg, a, b, c); and roman converts an integer to a Roman numeral (eg, i, ii, iii).

Strsoundex converts an arbitrary string to a SOUNDEX value. Non-ASCII text characters are ignored in the string.

Strtoint converts a numeric string to an integer. Atoi is identical to strtoint.

Strcmp compares two strings and returns an integer that is less than zero, equal to zero, or greater than zero, if, respectively, the first string is lexicographically less than, equal to, or greater than the second string. Eqstr and nestr return whether two strings are equal or not equal, respectively. Strcmp, Eqstr, and nestr all treat null strings as empty strings, which is to say they pretend that a null string is actually "". This means that all null and empty strings compare as equal.