format

A format string.

args

An array of objects to format.

A copy of the string with the formatting applied.

Use the format function to replace specified format items with the text representation of the corresponding object values. The args argument can contain a single object or an array of objects. The format argument contains zero or more runs of fixed text intermixed with one or more format items. Each format item corresponds to an object in objects. At run time, each format item is replaced by the string representation of the corresponding object in the list.

Format items consist of a number enclosed in braces, such as {0}, that identifies a corresponding item in the objects list. Numbering starts with zero. To specify a single literal brace character in format, specify two leading or trailing brace characters; that is, "{{" or "}}". Nested braces are not supported.

Specifying a Custom Formatting Routine

The following example shows how to use the format function to replace specified format items with the text representation of the corresponding object values. The code includes an example of a custom formatting object that has a toFormattedString method.

// Define an class with a custom toFormattedString
// formatting routine.
Type.registerNamespace('Samples');

Samples.ToFormattedStringExample = function() {
}
Samples.ToFormattedStringExample.prototype = {
    toFormattedString: function(format) {
        return "This was custom formatted: " + format;
    }
}
Samples.ToFormattedStringExample.registerClass('Samples.ToFormattedStringExample');

var result = "";

// Format a string.
result = String.format("{0:d}", 123);
// Displays: "123"
alert(result);

// Format a string with an object that has 
// a custom toFormattedString method.
var o = new Samples.ToFormattedStringExample();
result = String.format("{0:12345}", o);
// Displays: "This was custom formatted: 12345"
alert(result);

Reference

Other Resources