String Library
The String library contains a set of string functions. In WMLScript, a string is essentially an array of characters, the first element of which is at offset 0.
charAt
Description: Returns the character at the specified position in a string.
Syntax: String.charAt(string,index)
Example: The following example returns the first letter of a user's name:
// Get initial var initial=String.charAt(first_name, 0);
compare
Description: Compares two strings. Returns 1 if first string is greater than the second string, 0 if both strings are the same, or -1 if first string is less than the first string.
Syntax: String.compare(string1,string2)
Example: The following example (part of a sorting routine) compares two strings and switches them if the first is greater than the second:
// Is a greater than b?
if (String.compare(a,b)) {
// Yes, switch a and b
var x=a;
a=b;
b=x;
}
elementAt
Description: Returns the element found at a specified location within a string (using a specified delimiter):
Syntax: String.elementAt(string,index,separator)
Example: The following example returns the first word in a sentence:
// Get first word var first_word=String.elementAt(sentence,0," ");
elements
Description: Returns the total number of elements in a specified string.
Syntax: String.elements(string,separator)
Example: The following example determines the number of words in a sentence:
// How many words in the sentence? var num_words=String.elements(sentence," ");
find
Description: Determines if a block of text is contained within a specified string. If so, the result is the index of the first character of the first occurrence of the string. If no occurrence is found the result is -1.
Syntax: String.find(string,subString)
Example: The following example finds the start of a page's title text:
// Find start off page title var a=String.find(page, "<TITLE>"); }
format
Description: Converts a specified 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:
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 zeros. 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. When the number of digits after the decimal point in the value is less than the precision, letter O should be padded to fill columns. For example, the result of String.format("%2.3f", 1.2) will be "1.200".
s specifies the maximum number of characters to be printed. By default, all characters are printed. When the width is larger than the precision, the width should be ignored.
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
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.
s String—Characters are printed up to the end of the string or until the precision value is reached.
% The percent character in the format string can be presented by preceding it with another percent character (%%).
Syntax: String.format(format,value)
Example: The following example formats and displays the user's age (previously calculated):
// Display age
Dialogs.alert(String.format("You are %d years old", age));
insertAt
Description: Creates a string with a specified element and separator inserted into the original string at a specified position.
Syntax: String.insertAt(string,element,index,separator)
Example: The following example inserts an item (in variable item) at the front of a list:
// Insert new item at front of list var list=String.insertAt(list,item,0,",");
isEmpty
Description: Returns true if a string is zero-length (empty), and false if string is not zero-length.
Syntax: String.isEmpty(string)
Example: The following example displays an error message if a variable is not empty:
// Check e-mail address is not empty
if (String.isEmpty(email)) {
Dialogs.alert("E-Mail address cannot be left blank!");
}
length
Description: Returns the total number of characters in a string. The result is an integer.
Example: The following example displays an error message if a variable is not the desired length:
// Check enough digits entered
if (String.length(acn)!=12) {
Dialogs.alert("You must enter the full 12 digit account number!");
}
removeAt
Description: Returns a string with a specified element removed.
Syntax: String.removeAt(string,index,separator)
Example: The following example removes the last item in a list:
// Remove last element from list var list=String.removeAt(list,String.elements(list)-1,",");
replace
Description: Returns a new string where all the occurrences of a string are replaced with a new string.
Syntax: String.replace(string,oldSubString,newSubString)
Example: The following example replaces all occurrences of "wap" with "WAP":
// Replace all "wap" with "WAP" var string=String.replace(string, "wap", "WAP");
replaceAt
Description: Replaces a specified element in a string with a new element.
Syntax: String.replaceAt(string,element,index,separator)
Example: The following example replaces the first item in a list with an updated value:
// Update first element var list=String.replaceAt(list,new_value,0,",");
squeeze
Description: Replaces consecutive series of white spaces in a string with one white space.
Syntax: String.squeeze(string)
Example: The following example removes any extraneous white spaces in a string:
// Remove extraneous white spaces var name=String.squeeze(name);
subString
Description: Creates a new string from a specified string, using specified start position and length.
Syntax: String.subString(string,startIndex,length)
Example: The following example extracts the first sentence of a paragraph (found by looking for a period):
// Get first sentence var sentence=String.subString(paragraph,0,String.find(paragraph,".")-1);
toString
Description: Converts a value to a string.
Syntax: String.toString(value)
Example: The following example converts three parts of a phone number into strings so as to be able to concatenate them:
// Build displayable phone number
var phone="("+String.toString(p1)+")"+String.toString(p2)+"-"+ String.toString(p3);
trim
Description: Removes all leading and trailing white spaces from a string.
Example: The following example trims all leading and trailing space from an email address:
// Trim address var email=String.trim(email);