Previous: , Up: Streams   [Contents][Index]


5.24.5 Formatted Output

Function: format stream template #!rest values

Writes to a stream, stream, a string constructed from the format string, template, and list of arguments values.

If stream is false the resulting string will be returned, not written to a stream.

template is a template for the output string, any ‘%’ characters introduce a substitution, using the next unused argument. The substitutions have the following syntax,

%[index$][flags][field-width]conversion

index is an optional decimal number specifying exactly which of the values this conversion refers to (with the first at position one), and is usually used when translating messages; by default the next value is used.

field-width is a positive decimal integer, defining the size in characters of the substitution output.

conversion is a character defining how to convert the corresponding argument value to text. The default options are:

s

Write the printed representation of the value without quoting (as if from the princ function).

S

Write the printed representation with quoting enabled (like the prin1 function).

d

Output the value as a decimal number.

o

Write the value in octal.

x
X

In hexadecimal.

c

Write the character specified by the value.

%

Print a literal percent character. None of the values are used.

flags is a sequence of zero or more of the following characters,

_

Left justify the substitution within the field.

^

Truncate the substitution at the size of the field.

0

Pad the field with zeros instead of spaces.

+

For ‘d’, ‘x’, and ‘o’ conversions, output a leading plus sign if the argument is positive.

’ (a space)

For ‘d’, ‘x’, and ‘o’ conversions, if the result doesn’t start with a plus or minus sign, output a leading space.

The list of conversions can be extended through the format-hooks-alist variable; the strings created by these extra conversions are formatted as if by the ‘s’ conversion.

Note that the field-width and all flags currently have no effect on the ‘S’ conversion, (or the ‘s’ conversion when the argument isn’t a string).

If stream isn’t false (in which case the created string is returned) the value of stream is returned.

(format nil "foo %S bar 0x%x" '(x . y) 255)
    ⇒ "foo (x . y) bar 0xff"

(format standard-output "The %2$s is %1$s!" "purple" "dog")
    -| The dog is purple!
    ⇒ #<buffer *jade*>
Variable: format-hooks-alist

This variable is an association-list, each element being (char . function), defining extra conversions for the format function.

If a conversion ‘%x’ is given, and the alist contains an element whose car is the character x, the the associated function is called with one value, the next argument to be formatted. It should return the string to be inserted.


Previous: , Up: Streams   [Contents][Index]