(lispref.info)Formatting Strings


Next: Character Case Prev: String Conversion Up: Strings and Characters

Formatting Strings
==================

   "Formatting" means constructing a string by substitution of computed
values at various places in a constant string.  This 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.

   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 are matched with successive values from OBJECTS.  Thus,
the first format specification in STRING is matched with the first such
value, the second format specification is matched with 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 will be ignored.

   Certain format specifications require values of particular types.
However, no error is signaled if the value actually supplied fails to
have the expected type.  Instead, the output is likely to be
meaningless.

   Here is a table of the characters that can follow `%' to make up a
format specification:

`s'
     Replace the specification with the printed representation of the
     object, made without quoting.  Thus, strings are represented by
     their contents alone, with no `"' characters, and symbols appear
     without `\' characters.

     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.  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'
     Replace the specification with the base-sixteen representation of
     an integer.

`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.

`%'
     A single `%' is placed in the string.  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 #<buffer strings.texi>."
     
     (format "The octal value of 18 is %o,
              and the hex value is %x." 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.

     (format "%06d will be padded on the left with zeros" 123)
          => "000123 will be padded on the left with zeros"
     
     (format "%-6d will be padded on the right" 123)
          => "123    will be 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."


automatically generated by info2www