JavaScript

String class method format()


Formats a string, much like the standard C library function sprintf().

Synopsis


  try {
    var str = String.format(fmt, args...);
  } catch (e) {...}
    

Arguments

fmt
A string containing zero or more format specifiers.
args...
One or more arguments. The number of arguments must correspond to the number of format specifiers occurring in fmt.

Returns

The string, identical to fmt, except that each format specifier occurring in fmt is replaced by the converted string value of its corresponding argument.

Throws

String.format.E_NUMARGS
There are less args than there are format specifiers in fmt.


Description

The fmt parameter is a string that contains zero or more characters as well as the following format specifiers (a.k.a, "conversions"):

  %c  a character with the given number
  %s  a string
  %d  a signed integer, in decimal
  %i  a synonym for %d
  %o  a octal integer
  %x  a hexadecimal integer

Non-standard format specifiers:
  %b  a boolean value
  %C  a character, enclosed in single quotation marks
  %S  a string, enclosed in double-quotation marks
  %O  like %o, but with a "0" prefix for non-zero values
  %X  like %x, but with a "0x" prefix for non-zero values

  %e  a floating-point number, in scientific notation
  %f  a floating-point number, in fixed decimal notation

Flags between the % and the conversion letters e or f):
  number  digits after decimal point for floating-point
          (NOTE: Use with s or d or i won't be supported)

Use %% for a single percent sign (%) in the fmt string.

String.format() is intended for producing message strings that are useful for debugging, logging, or displaying output to the user. To permit this, format specifiers exist such as %b and %S that are well-suited for these purposes. Consequently, there is no attempt to adhere to, nor implement all of, the format specifiers found in sprintf() and related C library functions printf(), fprintf(), etc.

String.format() is a class method. It is not necessary to invoke it on a String instance.


Example

var str = new String(); str = str.concat(String.format("%%%% Welcome! %%%%"), "\n"); /*** str = str.concat(String.format("We expect a %s here."), "\n"); // This line would throw an exception! ***/ str = str.concat(String.format("The %z is not a valid format specifier. Neither is %y", 3.14159, null, "ignore-me"), "\n"); str = str.concat(String.format("The number %d in octal is %o; in hex is %x", 8888, 8888, 8888), "\n"); str = str.concat(String.format("The number %d in octal is %O; in hex is %X", 8888, 8888, 8888), "\n"); str = str.concat(String.format("The number %d in octal is %o; in hex is %x", 0, 0, 0), "\n"); str = str.concat(String.format("The number %d in octal is %O; in hex is %X", 0, 0, 0), "\n"); str = str.concat(String.format("ASCII code %i is %C.", 65, 65), "\n"); str = str.concat(String.format("%% stands for %s", "percent"), "\n"); str = str.concat(String.format("Give it your %d%% %s, %clex!", 100 + 10, "effort", 65), "\n"); // Floating point numbers str = str.concat(String.format("Current interest rate (default number of decimal places): %f%%", 2.60), "\n"); str = str.concat(String.format("Current interest rate (to 2 decimal places): %2f%%", 2.632525), "\n"); str = str.concat(String.format("Maximum integer is (no precision): %e", Number.MAX_VALUE), "\n"); str = str.concat(String.format("Maximum integer is (rounded to 6 significant digits): %6e", Number.MAX_VALUE), "\n"); str = str.concat(String.format("2 to the power of -25 is (rounded to 12 significant digits): %12e", Math.pow(2, -25)), "\n"); // Boolean values var i = 1, j = -1, t = true, s = "false"; var e = "", f = false, n = 0.0, x = -0, y = 8.08; str = str.concat(String.format("It is %b that i < j.\ni = %b, j = %b, t = %b, s = %b, e = %b, f = %b, n = %b,\nx = %b, y = %b, -y = %b", i < j, i, j, t, s, e, f, n, x, y, -y), "\n"); // null and undefined str = str.concat(String.format("Tests for %s and %s args - string %%s (%s, %s)", "null", "undefined", null, undefined), "\n"); str = str.concat(String.format("bool %%b (%b, %b)", null, undefined), "; "); str = str.concat(String.format("char %%c (%c, %c)", null, undefined), "; "); str = str.concat(String.format("int %%d (%d, %d)", null, undefined), "; "); str = str.concat(String.format("float %%f (%f, %f)", null, undefined), "\n"); str = str.concat(String.format("%s %s\n%s %s.", "First", "line", "Second", "line"), "\n"); str = str.concat(String.format("Joel User says, %S", "Goodbye, cruel world!"), "\n"); str = str.concat(String.format(""), "\n"); str = str.concat(String.format(null, 23, "foo", undefined), "\n"); var undef; str = str.concat(String.format(undef, 3.14159, null, "bar"), "\n"); document.getElementById("textarea").value = str;

Click the button below to run the test. Back to Example

Back to Top


Alex Eng,