Practical Common Lisp

As I mentioned previously, with a colon modifier it adds commas.

(format nil '~:d' 1000000) ==> '1,000,000'

And with an at-sign modifier, it always prints a sign.

(format nil '~@d' 1000000) ==> '+1000000'

And the two modifiers can be combined.

(format nil '~:@d' 1000000) ==> '+1,000,000'

The first prefix parameter can specify a minimum width for the output, and the second parameter can specify a padding character to use. The default padding character is space, and padding is always inserted before the number itself.

(format nil '~12d' 1000000)    ==> '     1000000'
(format nil '~12,'0d' 1000000) ==> '000001000000'

These parameters are handy for formatting things such as dates in a fixed-width format.

(format nil '~4,'0d-~2,'0d-~2,'0d' 2005 6 10) ==> '2005-06-10'

The third and fourth parameters are used in conjunction with the colon modifier: the third parameter specifies the character to use as the separator between groups and digits, and the fourth parameter specifies the number of digits per group. These parameters default to a comma and the number 3. Thus, you can use the directive ~:D without parameters to output large integers in standard format for the United States but can change the comma to a period and the grouping from 3 to 4 with ~,,'.,4D.

(format nil '~:d' 100000000)       ==> '100,000,000'
(format nil '~,,'.,4:d' 100000000) ==> '1.0000.0000'

Note that you must use commas to hold the places of the unspecified width and padding character parameters, allowing them to keep their default values.

The ~X, ~O, and ~B directives work just like the ~D directive except they emit numbers in hexadecimal (base 16), octal (base 8), and binary (base 2).

(format nil '~x' 1000000) ==> 'f4240'
(format nil '~o' 1000000) ==> '3641100'
(format nil '~b' 1000000) ==> '11110100001001000000'

Finally, the ~R directive is the general radix directive. Its first parameter is a number between 2 and 36 (inclusive) that indicates what base to use. The remaining parameters are the same as the four parameters accepted by the ~D, ~X, ~O, and ~B directives, and the colon and at-sign modifiers modify its behavior in the same way. The ~R directive also has some special behavior when used with no prefix parameters, which I'll discuss in the section 'English-Language Directives.'

Floating-Point Directives

Four directives format floating-point values: ~F, ~E, ~G, and ~$. The first three of these are the directives based on FORTRAN's edit descriptors. I'll skip most of the details of those directives since they mostly have to do with formatting floating-point values for use in tabular form. However, you can use the ~F, ~E, and ~$ directives to interpolate floating-point values into text. The ~G, or general, floating-point directive, on the other hand, combines aspects of the ~F and ~E directives in a way that only really makes sense for generating tabular output.

The ~F directive emits its argument, which should be a number,[197] in decimal format, possibly controlling the number of digits after the decimal point. The ~F directive is, however, allowed to use computerized scientific notation if the number is sufficiently large or small. The ~E directive, on the other hand, always emits numbers in computerized scientific notation. Both of these directives take a number of prefix parameters, but you need to worry only about the second, which controls the number of digits to print after the decimal point.

(format nil '~f' pi)   ==> '3.141592653589793d0'
(format nil '~,4f' pi) ==> '3.1416'
(format nil '~e' pi)   ==> '3.141592653589793d+0'
(format nil '~,4e' pi) ==> '3.1416d+0'

The ~$, or monetary, directive is similar to ~F but a bit simpler. As its name suggests, it's intended for emitting monetary units. With no parameters, it's basically equivalent to ~,2F. To modify the number of digits printed after the decimal point, you use the first parameter, while the second parameter controls the minimum number of digits to print before the decimal point.

(format nil '~$' pi)    ==> '3.14'
(format nil '~2,4$' pi) ==> '0003.14'

All three directives, ~F, ~E, and ~$, can be made to always print a sign, plus or minus, with the at-sign modifier.[198]

English-Language Directives

Some of the handiest FORMAT directives for generating human-readable messages are the ones for emitting English text. These directives allow you to emit numbers as English words, to emit plural markers based on the value of a format argument, and to apply case conversions to sections of FORMAT's output.

The ~R directive, which I discussed in 'Character and Integer Directives,' when used with no base specified, prints numbers as English words or Roman numerals. When used with no prefix parameter and no modifiers, it emits the number in words as a cardinal number.

(format nil '~r' 1234) ==> 'one thousand two hundred thirty-four'

With the colon modifier, it emits the number as an ordinal.

(format nil '~:r' 1234) ==> 'one thousand two hundred thirty-fourth'

And with an at-sign modifier, it emits the number as a Roman numeral; with both an at-sign and a colon, it emits 'old-style' Roman numerals in which fours and nines are written as IIII and VIIII instead of IV and IX.

(format nil '~@r' 1234)  ==> 'MCCXXXIV'
(format nil '~:@r' 1234) ==> 'MCCXXXIIII'

For numbers too large to be represented in the given form, ~R behaves like ~D.

To help you generate messages with words properly pluralized, FORMAT provides the ~P directive, which simply emits an s unless the corresponding argument is 1.

(format nil 'file~p' 1)  ==> 'file'
(format nil 'file~p' 10) ==> 'files'
(format nil 'file~p' 0)  ==> 'files'

Typically, however, you'll use ~P with the colon modifier, which causes it to reprocess the previous format argument.

(format nil '~r file~:p' 1)  ==> 'one file'
(format nil '~r file~:p' 10) ==> 'ten files'
(format nil '~r file~:p' 0)  ==> 'zero files'

With the at-sign modifier, which can be combined with the colon modifier, ~P emits either