4.7 Formatting Strings
Formatting means constructing a string by substituting 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-message only in how they use the result of formatting.
function format string \&rest objects
This function returns a string equal to string, replacing any format specifications 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. Any text properties of the format specifications are copied to the produced string representations of the argument objects.
The output string need not be newly-allocated. For example, if x is the string "foo", the expressions (eq x (format x)) and (eq x (format "%s" x)) might both yield t.
function format-message string \&rest objects
This function acts like format, except it also converts any grave accents (`) and apostrophes (') in string as per the value of text-quoting-style.
Typically grave accent and apostrophe in the format translate to matching curved quotes, e.g., "Missing `%s'" might result in "Missing ‘foo’". See Text Quoting Style, for how to influence or inhibit this translation.
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)
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 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.
‘%S’
Replace the specification with the printed representation of the object, made with quoting (that is, using prin1—see Output Functions). Thus, strings are enclosed in ‘"’ characters, and ‘\’ characters appear where necessary before special characters.
‘%o’
Replace the specification with the base-eight representation of an integer. Negative integers are formatted in a platform-dependent way. The object can also be a floating-point number that is formatted as an integer, dropping any fraction.
‘%d’
Replace the specification with the base-ten representation of a signed integer. The object can also be a floating-point number that is formatted as an integer, dropping any fraction.
‘%x’
‘%X’
Replace the specification with the base-sixteen representation of an integer. Negative integers are formatted in a platform-dependent way. ‘%x’ uses lower case and ‘%X’ uses upper case. The object can also be a floating-point number that is formatted as an integer, dropping any fraction.
‘%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. The exponential notation is used if the exponent would be less than -4 or greater than or equal to the precision (default: 6). By default, trailing zeros are removed from the fractional portion of the result and a decimal-point character appears only if it is followed by a digit.
‘%%’
Replace the specification with a single ‘%’. This format specification is unusual in that its only form is plain ‘%%’ and 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, which assume the typical text-quoting-style settings:
(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."
(format-message
"The name of this buffer is ‘%s’." (buffer-name))
⇒ "The name of this buffer is ‘strings.texi’."
(format-message
"The buffer object prints as `%s'." (current-buffer))
⇒ "The buffer object prints as ‘strings.texi’."
By default, 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.
A format specification can have a field number, which is a decimal number immediately after the initial ‘%’, followed by a literal dollar sign ‘$’. It causes the format specification to convert the argument with the given number instead of the next argument. Field numbers start at 1. A format can contain either numbered or unnumbered format specifications but not both, except that ‘%%’ can be mixed with numbered specifications.
(format "%2$s, %3$s, %%, %1$s" "x" "y" "z")
⇒ "y, z, %, x"
After the ‘%’ and any field number, you can put certain flag characters.
The flag ‘+’ inserts a plus sign before a nonnegative number, so that it always has a sign. A space character as flag inserts a space before a nonnegative number. (Otherwise, nonnegative numbers start with the first digit.) These flags are useful for ensuring that nonnegative and negative numbers use the same number of columns. They are ignored except for ‘%d’, ‘%e’, ‘%f’, ‘%g’, and if both flags are used, ‘+’ takes precedence.
The flag ‘#’ specifies an alternate form which depends on the format in use. For ‘%o’, it ensures that the result begins with a ‘0’. For ‘%x’ and ‘%X’, it prefixes nonzero results with ‘0x’ or ‘0X’. For ‘%e’ and ‘%f’, the ‘#’ flag means include a decimal point even if the precision is zero. For ‘%g’, it always includes a decimal point, and also forces any trailing zeros after the decimal point to be left in place where they would otherwise be removed.
The flag ‘0’ ensures that the padding consists of ‘0’ characters instead of spaces. This flag is ignored for non-numerical specification characters like ‘%s’, ‘%S’ and ‘%c’. These specification characters accept the ‘0’ flag, but still pad with spaces.
The flag ‘-’ causes any padding inserted by the width, if specified, to be inserted on the right rather than the left. If both ‘-’ and ‘0’ are present, the ‘0’ flag is ignored.
(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 "The word '%-7s' actually has %d letters in it."
"foo" (length "foo"))
⇒ "The word 'foo ' actually has 3 letters in it."
A specification can have a width, which is a decimal number that appears after any field number and flags. If the printed representation of the object contains fewer characters than this width, format extends it with padding. Any padding introduced by the width normally consists of spaces inserted on the left:
(format "%5d is padded on the left with spaces" 123)
⇒ " 123 is padded on the left with spaces"
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 two examples, ‘%7s’ specifies a minimum width of 7. In the first case, the string inserted in place of ‘%7s’ has only 3 letters, and needs 4 blank spaces as padding. In the second case, the string "specification" is 13 letters wide but is not truncated.
(format "The word '%7s' has %d letters in it."
"foo" (length "foo"))
⇒ "The word ' foo' has 3 letters in it."
(format "The word '%7s' has %d letters in it."
"specification" (length "specification"))
⇒ "The word 'specification' has 13 letters in it."
All the specification characters allow an optional precision after the field number, flags and width, if present. The precision is a decimal-point ‘.’ followed by a digit-string. For the floating-point specifications (‘%e’ and ‘%f’), the precision specifies how many digits following the decimal point to show; if zero, the decimal-point itself is also omitted. For ‘%g’, the precision specifies how many significant digits to show (significant digits are the first digit before the decimal point and all the digits after it). If the precision of %g is zero or unspecified, it is treated as 1. 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. For other specification characters, the effect of precision is what the local library functions of the printf family produce.
If you plan to use read later on the formatted string to retrieve a copy of the formatted value, use a specification that lets read reconstruct the value. To format numbers in this reversible way you can use ‘%s’ and ‘%S’, to format just integers you can also use ‘%d’, and to format just nonnegative integers you can also use ‘#x%x’ and ‘#o%o’. Other formats may be problematic; for example, ‘%d’ and ‘%g’ can mishandle NaNs and can lose precision and type, and ‘#x%x’ and ‘#o%o’ can mishandle negative integers. See Input Functions.
The functions described in this section accept a fixed set of specification characters. The next section describes a function format-spec which can accept custom specification characters, such as ‘%a’ or ‘%z’.