Format a variable number of arguments with the C-style formatting
string.
>>> printf "%s, %d, %.4f" "hello" 123 pi
hello, 123, 3.1416
The return value is either
String or
(IO a)
(which should be
(IO ()), but Haskell's type system
makes this hard).
The format string consists of ordinary characters and
conversion
specifications, which specify how to format one of the arguments
to
printf in the output string. A format specification is
introduced by the
% character; this character can be
self-escaped into the format string using
%%. A format
specification ends with a
format character that provides the
primary information about how to format the value. The rest of the
conversion specification is optional. In order, one may have flag
characters, a width specifier, a precision specifier, and
type-specific modifier characters.
Unlike C
printf(3), the formatting of this
printf is
driven by the argument type; formatting is type specific. The types
formatted by
printf "out of the box" are:
printf is also extensible to support other types: see below.
A conversion specification begins with the character
%,
followed by zero or more of the following flags:
- left adjust (default is right adjust)
+ always use a sign (+ or -) for signed conversions
space leading space for positive numbers in signed conversions
0 pad with zeros rather than spaces
# use an \"alternate form\": see below
When both flags are given,
- overrides
0 and
+ overrides space. A negative width specifier in a
*
conversion is treated as positive but implies the left adjust flag.
The "alternate form" for unsigned radix conversions is as in C
printf(3):
%o prefix with a leading 0 if needed
%x prefix with a leading 0x if nonzero
%X prefix with a leading 0X if nonzero
%b prefix with a leading 0b if nonzero
%[eEfFgG] ensure that the number contains a decimal point
Any flags are followed optionally by a field width:
num field width
* as num, but taken from argument list
The field width is a minimum, not a maximum: it will be expanded as
needed to avoid mutilating a value.
Any field width is followed optionally by a precision:
.num precision
. same as .0
.* as num, but taken from argument list
Negative precision is taken as 0. The meaning of the precision depends
on the conversion type.
Integral minimum number of digits to show
RealFloat number of digits after the decimal point
String maximum number of characters
The precision for Integral types is accomplished by zero-padding. If
both precision and zero-pad are given for an Integral field, the
zero-pad is ignored.
Any precision is followed optionally for Integral types by a width
modifier; the only use of this modifier being to set the implicit size
of the operand for conversion of a negative operand to unsigned:
hh Int8
h Int16
l Int32
ll Int64
L Int64
The specification ends with a format character:
c character Integral
d decimal Integral
o octal Integral
x hexadecimal Integral
X hexadecimal Integral
b binary Integral
u unsigned decimal Integral
f floating point RealFloat
F floating point RealFloat
g general format float RealFloat
G general format float RealFloat
e exponent format float RealFloat
E exponent format float RealFloat
s string String
v default format any type
The "%v" specifier is provided for all built-in types, and should be
provided for user-defined type formatters as well. It picks a "best"
representation for the given type. For the built-in types the "%v"
specifier is converted as follows:
c Char
u other unsigned Integral
d other signed Integral
g RealFloat
s String
Mismatch between the argument types and the format string, as well as
any other syntactic or semantic errors in the format string, will
cause an exception to be thrown at runtime.
Note that the formatting for
RealFloat types is currently a bit
different from that of C
printf(3), conforming instead to
showEFloat,
showFFloat and
showGFloat (and their
alternate versions
showFFloatAlt and
showGFloatAlt).
This is hard to fix: the fixed versions would format in a
backward-incompatible way. In any case the Haskell behavior is
generally more sensible than the C behavior. A brief summary of some
key differences:
- Haskell printf never uses the default "6-digit" precision
used by C printf.
- Haskell printf treats the "precision" specifier as
indicating the number of digits after the decimal point.
- Haskell printf prints the exponent of e-format numbers
without a gratuitous plus sign, and with the minimum possible number
of digits.
- Haskell printf will place a zero after a decimal point when
possible.