Next: Case Conversion, Previous: String Conversion, Up: Strings and Characters
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.
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, including their text properties, if any.
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."
Since format interprets `%' characters as format
specifications, you should never pass an arbitrary string as
the first argument. This is particularly true when the string is
generated by some Lisp code. Unless the string is known to
never include any `%' characters, pass "%s", described
below, as the first argument, and the string as the second, like this:
(format "%s" arbitrary-string)
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 an error. 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:
princ, not
prin1—see Output Functions). Thus, strings are represented
by their contents alone, with no `"' characters, and symbols appear
without `\' characters.
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.
prin1—see Output Functions). Thus, strings are enclosed in `"' characters, and
`\' characters appear where necessary before special characters.
(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 “width,” which is a digit-string between the `%' and the character. If the printed representation of the object contains fewer characters than this width, then it is padded. The padding is on the left if the width is positive (or starts with zero) and on the right if the width is negative. The padding character is normally a space, but if the width starts with a zero, zeros are used for padding. Some of these conventions are ignored for specification characters for which they do not make sense. That is, `%s', `%S' and `%c' accept a width starting with 0, but still pad with spaces on the left. Also, `%%' accepts a width, but ignores it. 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"
If the width is too small, format does not truncate the
object's printed representation. Thus, you can use a width 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."
All the specification characters allow an optional “precision” before the character (after the width, if present). The precision is a decimal-point `.' followed by a digit-string. For the floating-point specifications (`%e', `%f', `%g'), the precision specifies how many decimal places to show; if zero, the decimal-point itself is also omitted. For `%s' and `%S', the precision truncates the string to the given width, so `%.3s' shows only the first three characters of the representation for object. Precision is ignored for other specification characters.
Immediately after the `%' and before the optional width and precision, you can put certain “flag” characters.
A space character inserts a space for positive numbers (otherwise nothing is inserted for positive numbers). This flag is ignored except for `%d', `%e', `%f', `%g'.
The flag `#' indicates “alternate form.” For `%o' it ensures that the result begins with a 0. For `%x' and `%X' the result is prefixed with `0x' or `0X'. For `%e', `%f', and `%g' a decimal point is always shown even if the precision is zero.