Skip to main content

format

format Function

Syntax:

format destination control-string &rest args ! result

Arguments and Values:

destination—nil, t, a stream, or a string with a fill pointer .

control-string—a format control.

args—format arguments for control-string.

result—if destination is non-nil, then nil; otherwise, a string.

Description:

format produces formatted output by outputting the characters of control-string and observing that a tilde introduces a directive. The character after the tilde, possibly preceded by prefix parameters and modifiers, specifies what kind of formatting is desired. Most directives use one or more elements of args to create their output.

If destination is a string, a stream, or t, then the result is nil. Otherwise, the result is a string containing the ‘output.’

format is useful for producing nicely formatted text, producing good-looking messages, and so on. format can generate and return a string or output to destination.

For details on how the control-string is interpreted, see Section 22.3 (Formatted Output).

Aected By:

*standard-output*, *print-escape*, *print-radix*, *print-base*, *print-circle*, *print-pretty*, *print-level*, *print-length*, *print-case*, *print-gensym*, *print-array*.

Exceptional Situations:

If destination is a string with a fill pointer , the consequences are undefined if destructive modifications are performed directly on the string during the dynamic extent of the call.

See Also:

write, Section 13.1.10 (Documentation of Implementation-Defined Scripts)

22. Printer

Expanded Reference: format​

Basic String Output​

format with nil as the destination returns a string. With t, it prints to *standard-output*.

;; Return a formatted string
(format nil "Hello, ~A!" "world")
=> "Hello, world!"

;; Print to standard output (returns NIL)
(format t "Hello, ~A!~%" "world")
.. Hello, world!
..
=> NIL

Common Directives: ~A, ~S, ~D, ~F​

~A prints aesthetically (like princ), ~S prints readably (like prin1), ~D prints integers in decimal, and ~F prints floating-point numbers.

(format nil "Name: ~A, Symbol: ~S, Count: ~D" "Alice" :hello 42)
=> "Name: Alice, Symbol: :HELLO, Count: 42"

(format nil "Pi is approximately ~F" 3.14159)
=> "Pi is approximately 3.14159"

(format nil "~5D" 42)
=> "   42"

(format nil "~5,'0D" 42)
=> "00042"

Padding and Alignment with ~A and ~S​

Use column width and padding parameters to align output.

(format nil "|~10A|" "hello")
=> "|hello     |"

(format nil "|~10@A|" "hello")
=> "|     hello|"

(format nil "|~10,,,'*A|" "hi")
=> "|hi********|"

Radix and Number Formatting​

~B for binary, ~O for octal, ~X for hexadecimal, and ~R for general radix or English words.

(format nil "Binary: ~B, Octal: ~O, Hex: ~X" 255 255 255)
=> "Binary: 11111111, Octal: 377, Hex: FF"

(format nil "~R" 42)
=> "forty-two"

(format nil "~:R" 3)
=> "third"

Iteration with ~{ and ~}​

~{...~} iterates over a list, applying the enclosed directives to each element.

(format nil "Items: ~{~A~^, ~}" '("apple" "banana" "cherry"))
=> "Items: apple, banana, cherry"

(format nil "~{(~A ~A)~^ ~}" '("a" 1 "b" 2 "c" 3))
=> "(a 1) (b 2) (c 3)"

Conditional Expressions with ~[, ~;, ~]​

~[...~;...~] selects output based on an integer argument. ~:[...~;...~] provides boolean if-else.

;; Boolean conditional: ~:[ picks false-branch ~; true-branch ~]
(format nil "~:[no~;yes~]" t)
=> "yes"

(format nil "~:[no~;yes~]" nil)
=> "no"

;; Numeric selection (0-indexed)
(format nil "~[zero~;one~;two~;other~]" 1)
=> "one"

Freshline, Newline, and Tilde​

~% outputs a newline, ~& outputs a freshline (newline only if not at start of line), and ~~ outputs a literal tilde.

(format nil "Line 1~%Line 2~%Line 3")
=> "Line 1
Line 2
Line 3"

(format nil "100~~ complete")
=> "100~ complete"