NAME ^

runtime/wmlsstring.pir - WMLScript String library

DESCRIPTION ^

This library contains a set of string functions. A string is an array of characters. Each of the characters has an index. The first character in a string has an index zero (0). The length of the string is the number of characters in the array.

The user of the String library can specify a special separator by which elements in a string can be separated. These elements can be accessed by specifying the separator and the element index. The first element in a string has an index zero (0). Each occurrence of the separator in the string separates two elements (no escaping of separators is allowed).

A White space character is one of the following characters:

See "WMLScript Standard Libraries Specification", section 9 "String".

FUNCTIONS ^

length(string) ^

DESCRIPTION

Returns the length (number of characters) of the given string.

PARAMETERS

string = String

RETURN VALUE

Integer or invalid.

isEmpty(string) ^

DESCRIPTION

Returns a boolean true if the string length is zero and boolean false otherwise.

PARAMETERS

string = String

RETURN VALUE

Boolean or invalid.

charAt(string, index) ^

DESCRIPTION

Returns a new string of length one containing the character at the specified index of the given string.

If the index is of type floating-point, Float.int() is first used to calculate the actual integer index.

PARAMETERS

string = String

index = Number (the index of the character to be returned)

RETURN VALUE

String or invalid.

EXCEPTIONS

If index is out of range then an empty string ("") is returned.

subString(string, startIndex, length) ^

DESCRIPTION

Returns a new string that is a substring of the given string. The substring begins at the specified startIndex and its length (number of characters) is the given length. If the startIndex is less than 0 then 0 is used for the startIndex. If the length is larger than the remaining number of characters in the string, the length is replaced with the number of remaining characters.

If the startIndex or the length is of type floating-point, Float.int() is first used to calculate the actual integer value.

PARAMETERS

string = String

startIndex = Number (the beginning index, inclusive)

length = Number (the length of the substring)

RETURN VALUE

String or invalid.

EXCEPTIONS

If startIndex is larger than the last index an empty string ("") is returned.

If length <= 0 an empty string ("") is returned.

find(string, subString) ^

DESCRIPTION

Returns the index of the first character in the string that matches the requested subString. If no match is found integer value -1 is returned.

Two strings are defined to match when they are identical. Characters with multiple possible representations match only if they have the same representation in both strings. No case folding is performed.

PARAMETERS

string = String

subString = String

RETURN VALUE

Integer or invalid.

EXCEPTIONS

If subString is an empty string (""), an invalid value is returned.

replace(string, oldSubString, newSubString) ^

DESCRIPTION

Returns a new string resulting from replacing all occurrences of oldSubString in this string with newSubString.

Two strings are defined to match when they are identical. Characters with multiple possible representations match only if they have the same representation in both strings. No case folding is performed.

PARAMETERS

string = String

oldSubString = String

newSubString = String

RETURN VALUE

String or invalid.

EXCEPTIONS

If oldSubString is an empty string an invalid value is returned.

elements(string, separator) ^

DESCRIPTION

Returns the number of elements in the given string separated by the given separator. Empty string ("") is a valid element (thus, this function can never return a value that is less or equal to zero).

PARAMETERS

string = String

separator = String (the first character of the string used as separator)

RETURN VALUE

Integer or invalid.

EXCEPTIONS

Returns invalid if the separator is an empty string.

elementAt(string, index, separator) ^

DESCRIPTION

Search string for index'th element, elements being separated by separator and return the corresponding element. If the index is less than 0 then the first element is returned. If the index is larger than the number of elements then the last element is returned. If the string is an empty string then an empty string is returned.

If the index is of type floating-point, Float.int() is first used to calculate the actual index value.

PARAMETERS

string = String

index = Number (the index of the element to be returned)

separator = String (the first character of the string used as separator)

RETURN VALUE

String or invalid.

EXCEPTIONS

Returns invalid if the separator is an empty string.

removeAt(string, index, separator) ^

DESCRIPTION

Returns a new string where the element and the corresponding separator (if existing) with the given index are removed from the given string. If the index is less than 0 then the first element is removed. If the index is larger than the number of elements then the last element is removed. If the string is empty, the function returns a new empty string.

If the index is of type floating-point, Float.int() is first used to calculate the actual index value.

PARAMETERS

string = String

index = Number (the index of the element to be deleted)

separator = String (the first character of the string used as separator)

RETURN VALUE

String or invalid.

EXCEPTIONS

Returns invalid if the separator is an empty string.

replaceAt(string, element, index, separator) ^

DESCRIPTION

Returns a string with the current element at the specified index replaced with the given element. If the index is less than 0 then the first element is replaced. If the index is larger than the number of elements then the last element is replaced. If the string is empty, the function returns a new string with the given element.

If the index is of type floating-point, Float.int() is first used to calculate the actual index value.

PARAMETERS

string = String

element = String

index = Number (the index of the element to be replaced)

separator = String (the first character of the string used as separator)

RETURN VALUE

String or invalid.

EXCEPTIONS

Returns invalid if the separator is an empty string.

insertAt(string, element, index, separator) ^

DESCRIPTION

Returns a string with the element and the corresponding separator (if needed) inserted at the specified element index of the original string. If the index is less than 0 then 0 is used as the index. If the index is larger than the number of elements then the element is appended at the end of the string. If the string is empty, the function returns a new string with the given element.

If the index is of type floating-point, Float.int() is first used to calculate the actual index value.

PARAMETERS

string = String (original string)

element = String (element to be inserted)

index = Number (the index of the element to be added)

separator = String (the first character of the string used as separator)

RETURN VALUE

String or invalid.

EXCEPTIONS

Returns invalid if the separator is an empty string.

squeeze(string) ^

DESCRIPTION

Returns a string where all consecutive series of white spaces within the string are reduced to single inter-word space.

PARAMETERS

String = String

RETURN VALUE

String or invalid.

trim(string) ^

DESCRIPTION

Returns a string where all trailing and leading white spaces in the given string have been trimmed.

PARAMETERS

String = String

RETURN VALUE

String or invalid.

compare(string1, string2) ^

DESCRIPTION

The return value indicates the lexicographic relation of string1 to string2. The relation is based on the relation of the character codes in the native character set. The return value is -1 if string1 is less than string2, 0 if string1 is identical to string2 or 1 if string1 is greater than string2.

PARAMETERS

String1 = String

String2 = String

RETURN VALUE

Integer or invalid.

toString(value) ^

DESCRIPTION

Returns a string representation of the given value. This function performs exactly the same conversions as supported by the [WMLScript] language (automatic conversion from boolean, integer and floating-point values to strings) except that invalid value returns the string "invalid".

PARAMETERS

value = Any

RETURN VALUE

String.

format(format, value) ^

DESCRIPTION

Converts the given value to a string by using the given formatting provided as a format string. The format string can contain only one format specifier, which can be located anywhere inside the string. If more than one is specified, only the first one (leftmost) is used and the remaining specifiers are replaced by an empty string. The format specifier has the following form:

 % [width] [.precision] type

The width argument is a nonnegative decimal integer controlling the minimum number of characters printed. If the number of characters in the output value is less than the specified width, blanks are added to the left until the minimum width is reached. The width argument never causes the value to be truncated. If the number of characters in the output value is greater than the specified width or, if width is not given, all characters of the value are printed (subject to the precision argument).

The precision argument specifies a nonnegative decimal integer, preceded by a period (.), which can be used to set the precision of the output value. The interpretation of this value depends on the given type:

d

Specifies the minimum number of digits to be printed. If the number of digits in the value is less than precision, the output value is padded on the left with zeroes. The value is not truncated when the number of digits exceeds precision. Default precision is 1. If precision is specified as 0 and the value to be converted is 0, the result is an empty string.

f

Specifies the number of digits after the decimal point. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits. Default precision is 6; if precision is 0 or if the period (.) appears without a number following it, no decimal point is printed.

s

Specifies the maximum number of characters to be printed. By default, all characters are printed.

Unlike the width argument, the precision argument can cause either truncation of the output value or rounding of a floating-point value.

The type argument is the only required format argument; it appears after any optional format fields. The type character determines whether the given value is interpreted as integer, floating-point or string. If the value argument is of a different type than is specified by the type argument, it is converted according to WMLScript standard automatic conversion rules, with the addition that if value is of type floating-point and type is d, Float.int() is called to convert the value. The supported type arguments are:

d

Integer: The output value has the form [-]dddd, where dddd is one or more decimal digits.

f

Floating-point: The output value has the form [-]dddd.dddd, where dddd is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number and the number of digits after the decimal point depends on the requested precision. When the number of digits after the decimal point in the value is less than the precision, letter 0 should be padded to fill columns (e.g. the result of String.format("%2.3f", 1.2) will be "1.200")

s

String: Characters are printed up to the end of the string or until the precision value is reached. When the width is larger than precision, the width should be ignored.

A literal percent character (%) may be included in the format string by preceding it with another percent character (%%).

MINIMALIST IMPLEMENTATION

PARAMETERS

format = String

value = Any

RETURN VALUE

String or invalid.

EXCEPTIONS

Illegal format specifier results in an invalid return value.

AUTHORS ^

Francois Perrad.


 parrot