4.7 Formatting Strings

Formatting means constructing a string by substitution of computed values at various places in a constant string. This constant string controls how the other values are printed, as well as where they appear; it is called a format string.

Formatting is often useful for computing messages to be displayed. In fact, the functions message and error provide the same formatting feature described here; they differ from format only in how they use the result of formatting.

Function: format string &rest objects

This function returns a new string that is made by copying string and then replacing any format specification in the copy with encodings of the corresponding objects. The arguments objects are the computed values to be formatted.

The characters in string, other than the format specifications, are copied directly into the output; starting in Emacs 21, if they have text properties, these are copied into the output also.

A format specification is a sequence of characters beginning with a `%'. Thus, if there is a `%d' in string, the format function replaces it with the printed representation of one of the values to be formatted (one of the arguments objects). For example:

(format "The value of fill-column is %d." fill-column) => "The value of fill-column is 72."

If string contains more than one format specification, the format specifications correspond to successive values from objects. Thus, the first format specification in string uses the first such value, the second format specification uses the second such value, and so on. Any extra format specifications (those for which there are no corresponding values) cause unpredictable behavior. Any extra values to be formatted are ignored.

Certain format specifications require values of particular types. If you supply a value that doesn't fit the requirements, an error is signaled.

Here is a table of valid format specifications:

`%s'

Replace the specification with the printed representation of the object, made without quoting (that is, using princ, not prin1---see section 19.5 Output Functions). Thus, strings are represented by their contents alone, with no `"' characters, and symbols appear without `\' characters.

Starting in Emacs 21, if the object is a string, its text properties are copied into the output. The text properties of the `%s' itself are also copied, but those of the object take priority.

If there is no corresponding object, the empty string is used.

`%S'

Replace the specification with the printed representation of the object, made with quoting (that is, using prin1---see section 19.5 Output Functions). Thus, strings are enclosed in `"' characters, and `\' characters appear where necessary before special characters.

If there is no corresponding object, the empty string is used.

`%o'

Replace the specification with the base-eight representation of an integer.

`%d'

Replace the specification with the base-ten representation of an integer.

`%x'

`%X'

Replace the specification with the base-sixteen representation of an integer. `%x' uses lower case and `%X' uses upper case.

`%c'

Replace the specification with the character which is the value given.

`%e'

Replace the specification with the exponential notation for a floating point number.

`%f'

Replace the specification with the decimal-point notation for a floating point number.

`%g'

Replace the specification with notation for a floating point number, using either exponential notation or decimal-point notation, whichever is shorter.

`%%'

Replace the specification with a single `%'. This format specification is unusual in that it does not use a value. For example, (format "%% %d" 30) returns "% 30".

Any other format character results in an `Invalid format operation' error.

Here are several examples:

(format "The name of this buffer is %s." (buffer-name)) => "The name of this buffer is strings.texi." (format "The buffer object prints as %s." (current-buffer)) => "The buffer object prints as strings.texi." (format "The octal value of %d is %o, and the hex value is %x." 18 18 18) => "The octal value of 18 is 22, and the hex value is 12."

All the specification characters allow an optional numeric prefix between the `%' and the character. The optional numeric prefix defines the minimum width for the object. If the printed representation of the object contains fewer characters than this, then it is padded. The padding is on the left if the prefix is positive (or starts with zero) and on the right if the prefix is negative. The padding character is normally a space, but if the numeric prefix starts with a zero, zeros are used for padding. Here are some examples of padding:

(format "%06d is padded on the left with zeros" 123) => "000123 is padded on the left with zeros" (format "%-6d is padded on the right" 123) => "123 is padded on the right"

format never truncates an object's printed representation, no matter what width you specify. Thus, you can use a numeric prefix to specify a minimum spacing between columns with no risk of losing information.

In the following three examples, `%7s' specifies a minimum width of 7. In the first case, the string inserted in place of `%7s' has only 3 letters, so 4 blank spaces are inserted for padding. In the second case, the string "specification" is 13 letters wide but is not truncated. In the third case, the padding is on the right.

(format "The word `%7s' actually has %d letters in it." "foo" (length "foo")) => "The word ` foo' actually has 3 letters in it." (format "The word `%7s' actually has %d letters in it." "specification" (length "specification")) => "The word `specification' actually has 13 letters in it." (format "The word `%-7s' actually has %d letters in it." "foo" (length "foo")) => "The word `foo ' actually has 3 letters in it."