DevGuru WMLScript Function: String.format

FUNCTION: String.format

String.format(format, value)

The String.format function converts the given value into a formatted string. By formatted, we mean that the value is modified to have a specified appearance when it is displayed. You can apply formatting to fixed-point numbers (integers), floating-point numbers, and strings. For example, you can specify how many digits can occur after a decimal point in a floating-point number, or you could set the minimum number of characters that can be displayed in a string.

The mandatory format parameter string contains a format specifier and can optionally contain an associated string of characters. If this parameter contains more than one format specifier, only the first occurrence will be applied to the value. The format specifier is of the following form and contains three arguments:

% [width] [.precision] type

The leading percent sign % is required and signifies the start of the format specifier.

The mandatory type argument has only three permitted values (d, f, and s) that denote whether the output value is to be interpreted as a fixed-point (integer) number, floating-point number, or string. Here is an explanation of the three permitted values:

d designates a positive or negative integer number (including zero).
f designates a positive or negative floating-point number (including zero) that contains one decimal point. The number of digits appearing to the right of the decimal point is set by the optional precision argument.
s designates a string. You can use the optional width argument to set the minimum display size. You can use the optional precision argument to set the maximum display size.

The optional width argument is a positive integer (greater than zero) that sets the minimum number of characters that will be displayed in the output. Note that this argument places no limitation on the maximum number of characters that can be displayed (i.e., the full value will not be truncated by of this argument). If the value is smaller in size than the number set by the width, then blank spaces are added to the left until the minimum width is reached.

The optional precision argument is a positive integer (including zero) that sets the precision for the display value. The leading decimal point . is required and signifies the start of the precision argument. The exact effect of this argument depends on the type of the value, as follows:

d: Sets the minimum number of digits in the integer that will be displayed. If the number of characters in the value is larger than the number set by the precision, the value is not truncated and the full value is displayed. If the value is smaller in size than the precision, then an appropriate number of leading zeros or blank spaces (browser dependent) will be added onto the left side. The default is to display one digit.
f: Sets the number of digits that appear to the right of the decimal point. If the actual number of digits after the decimal point is greater than the number set by the precision, the floating-point value is rounded down. If the actual number of digits after the decimal point is less than the number set by the precision, extra zeros are added to the right side. If the precision is set to zero or no number occurs after the leading decimal point, then the displayed output will be an integer and will not contain a decimal point. The default is to display six digits.
s: Sets the maximum number of characters that can be displayed in the output of a string. The default is to display all characters.

The mandatory value parameter can be any combination of one or more letters, numbers, and white spaces.

Here are some examples of format parameters:

format	value	output
"%4d"	38	38
"%4d"	-38	-38
"%7.4d"	38	0038
"%5.3f"	8.34567	8.346
"MyNum=%5.2f"	44.99	MyNum= 44.99
"%4.0f meters"	123.456	123 meters
"%7s"	jaguar	jaguar
"My pet %7s is named Oztotl"	jaguar	My pet jaguar is named Oztotl
"%6.1f"	Fred	invalid

Note: to display the percent sign in a format string, use %%.

Code for FormatExample.wml
<?xml version="1.0"?>
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN"
"http://www.WAPforum.org/DTD/wml_1.1.xml">
<wml>

<card id="card1">
 
 format example
 
 <do type="accept">
 <go href="FormatExample.wmls#findformat()" />
 </do>
</card>

<card id="card2">

 format = $(format)
 
 value = $(value)
 
 result = $(result)

</card>

</wml>

Code for FormatExample.wmls
extern function findformat()
{
 var formt = Dialogs.prompt("Enter a format", "");
 var val = Dialogs.prompt("Enter a value", "");
 var res = String.format(formt, val);
 WMLBrowser.setVar("format", formt);
 WMLBrowser.setVar("value", val);
 WMLBrowser.setVar("result", res);
 WMLBrowser.go("FormatExample.wml#card2");
};