The String 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 occurrent 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:
|
TAB |
Horizontal tabulation |
|
VT |
Vertical tabulation |
|
FF |
Form feed |
|
SP |
Space |
|
LF |
Line feed |
|
CR |
Carriage return |
Included in this section are the following function calls:
string.charAt(string, index)
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.
string = String
index = Number (the index of the character to be returned)
String or invalid.
If index is out of range, an empty string ("") is returned.
var a = "Monday, May 24";
var b = String.charAt(a, 0); // b = "M"
var c = String.charAt(a, 100); // c = ""
var d = String.charAt(34, 0); // d = "3"
var e = String.charAt(a, "first"); // e = invalid
string.compare(string1, string2)
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.
string1 = String
string2 = String
Integer or invalid
var a = "Hello";
var b = "Hello";
var c = String.compare(a, b); // c = 0
var d = String.compare("Bye", "Jon"); // d = -1
var e = String.compare("Jon", "Bye"); // e = 1
string.elementAt(string, index, separator)
Search string for the element enumerated by index, elements being separated by separator, and return the corresponding element. If the index is less than 0, the first element is returned. If the index is larger than the number of elements, the last element is returned. If the string is an empty string, an empty string is returned.
If the index is of type floating-point, Float.int() is first used to calculate the actual index value.
string = String
index = Number (the index of the element to be returned)
separator = String (the first character of the string used as separator)
String or invalid.
Returns invalid if the separator is an empty string ("")
var a = "My name is Joe; Age 50;";
var b = String.elementAt(a, 0, " "); // b = "My"
var c = String.elementAt(a, 14, ";"); // c = ""
var d = String.elementAt(a, 1, ";"); // d = " Age 50"
string.elements(string, separator)
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 than or equal to zero).
string = String
separator = String (the first character of the string used as separator)
Integer or invalid.
Returns invalid if the separator is an empty string ("")
var a = "My name is Joe; Age 50;";
var b = String.elements(a, " "); // b = 6
var c = String.elements(a, ";"); // c = 3
var d = String.elements(""; ";"); // d = 1
var e = String.elements("a", ";"); // e = 1
var f = String.elements(";", ";"); // f = 2
var g = String.elements(";;,;", ";,");
// g = 4 separator = ;
string.find(string, subString)
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.
string = String
subString = String
Integer or invalid
var a = "abcde";
var b = string.find(a, "cd"); // b = 2
var c = string.find(34.2, "de"); // c = -1
var d = string.find(a, "qz"); // d = -1
var e = string.find(34, "3"); // e = 0
string.format(format, value)
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 non-negative 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 non-negative 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:
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. The supported type arguments are:
Percent character (%) in the format string can be presented by preceding it with another percent character (%%).
format = String
value = Any
String or invalid.
Illegal format specifier results in an invalid return value
var a = 45;
var b = -45;
var c = "now";
var d = 1.2345678
var e = String.format("e: %6d", a); // e = "e: 45"
var f = String.format("%6d", b); // f = " -45"
var g = String.format("%6.4d", a); // g = " 0045"
var h = String.format("%6.4d", b); // h = " -0045"
var i = String.format("Do it %s", c); // i = "Do it now"
var j = String.format("%3f", d); // j = "1.234567"
var k = String.format("%10.2f%%", d); // k = " 1.23%"
var l = String.format("%3f %2f.", d); // l = "1.234567."
var m = String.format("%.0d", 0); // m = ""
var n = String.format("%7d", "Int"); // n = invalid
var o = String.format("%s", true); // o = "true"
string.insertAt(string, element, index, separator)
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.
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)
String or invalid.
Returns invalid if the separator is an empty string ("")
var a = "B C; E";
var s = " ";
var b = String.insertAt(a, "A", 0, s); // b = "A B C; E"
var c = String.insertAt(a, "X", 3, s) // c = "B C; E X"
var d = String.insertAt(a, "D", 1, ";"); // d = "B C;D; E"
var e = String.insertAt(a, "F", 5, ";"); // e = "B C; E;F"
string.isEmpty(string)
Returns a boolean true if the string length is zero; otherwise returns a boolean false.
string = String
Boolean or invalid
var a = "Hello";
var b = "";
var c = String.isEmpty(a); // c = false
var d = String.isEmpty(b); // d = true
var e = String.isEmpty(true); // e = false
string.length(string)
Returns the length (number of characters) of the given string.
string = String
Integer or invalid
var a = "ABC";
var b = String.length(a); // b = 3
var c = String.length("") // c = 0
var d = String.length(342); // d = 3
string.removeAt(string, index, separator)
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, 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.
string = String
index = Number (the index of the element to be deleted)
separator = String (the first character of the string used as separator)
String or invalid.
Returns invalid if the separator is an empty string ("")
var a = "A A; B C D";
var s = "";
var b = String.removeAt(a, 1, s); // b = "A B C D"
var c = String.removeAt(a, 0, ";"); // c = " B C D"
var d = String.removeAt(a, 14, ";"); // d = "A A"
string.replace(string, oldSubString, newSubString)
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.
string = String
oldSubString = String
newSubString = String
String or invalid
var a = "Hello Christina. What is up Christina?";
var newName = "Marie"
var oldName = "Christina"
var c = String.replace(a, oldName, newName);
// c = "Hello Marie. What is up Marie?"
var d = String.replace(a, newName, oldName);
// d = "Hello Christina. What is up Christina?"
string.replaceAt(string, element, index, separator)
Returns a string with the current element at the specified index replaced with the given element. If the index is less than 0, the first element is replaced. If the index is larger than the number of elements, 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.
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)
String or invalid.
Returns invalid if the separator is an empty string ("")
var a = "B C; E";
var s = "";
var b = String.replaceAt(a, "A", 0, s); // b = "A C; E"
var c = String.replaceAt(a, "F", 5, ";"); // c = "B C;F"
string.squeeze(string)
Returns a string where all consecutive series of white spaces within the string are reduced to one.
string = String
String or invalid
var a = "Hello";
var b = " Bye Jon . See you! ";
var c = String.squeeze(a); // c = "Hello";
var d = String.squeeze(b) // d = " Bye Jon . See you! "
string.subString(string, startIndex, length)
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.
string = String
startIndex = Number (the beginning index, inclusive)
length = Number (the length of the substring)
String or invalid.
If startIndex is larger than the last index, an empty string ("") is returned.
If length <= 0, an empty string ("") is returned.
var a = "ABCD";
var b = String.subString(a, 1, 2); // b = "BC"
var c = String.subString(a, 2, 5); // c = "CD"
var d = String.subString(1234, 0, 2); // d = "12"
string.toString(value)
Returns a string representation of the given value. This function performs exactly the same conversions as supported by the WMLScript 1.1 language (automatic conversion from boolean, integer, and floating-point values to strings) except that invalid value returns the string "invalid".
value = Any
String
var a = String.toString(12); // a = "12"
var b = String.toString(true) // b = "true"
string.trim(string)
Returns a string where all trailing and leading white spaces in the given string have been trimmed.
string = String
String or invalid
var a = "Hello";
var b = " Bye Jon . See you! ";
var c = String.trim(a); // c = "Hello";
var d = String.trim(b) // d = "Bye Jon . See you!"