Previous: Output Functions, Up: Streams [Contents][Index]
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:
Write the printed representation of the value without quoting (as if from
the princ
function).
Write the printed representation with quoting enabled (like the
prin1
function).
Output the value as a decimal number.
Write the value in octal.
In hexadecimal.
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.
Pad the field with zeros instead of spaces.
For ‘d’, ‘x’, and ‘o’ conversions, output a leading plus sign if the argument is positive.
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*>
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: Output Functions, Up: Streams [Contents][Index]