WMLScript » String » String.format

String.format(format, value)
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:
The mandatory value parameter can be any combination of one or more letters, numbers, and white spaces.

Converts a given value to a string using a specified format.

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.

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 %%.


<?xml version="1.0"?>

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

<card id="card2">
   format = $(format)
   <br />
   value = $(value)
   <br />
   result = $(result)


Code for FormatExample.wml

Language(s): WML
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);

Code for FormatExample.wmls

Language(s): WML

See Also: