Format a variable number of arguments with the C-style formatting string.

>>>printf "%s, %d, %.4f" "hello" 123 pihello, 123, 3.1416

The return value is eitherString or(IO a) (which should be(IO '()'), but Haskell's type system makes this hard).

The format string consists of ordinary characters andconversion specifications, which specify how to format one of the arguments toprintf 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 Cprintf(3), the formatting of thisprintf is driven by the argument type; formatting is type specific. The types formatted byprintf "out of the box" are:

• Integral types, includingChar
• String
• RealFloat types

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 conversionsspace  leading space for positive numbers in signed conversions0      pad with zeros rather than spaces#      use an \"alternate form\": see below

When both flags are given,- overrides0 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 Cprintf(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 showRealFloat   number of digits after the decimal pointString      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     Int8h      Int16l      Int32ll     Int64L      Int64

The specification ends with a format character:

c      character               Integrald      decimal                 Integralo      octal                   Integralx      hexadecimal             IntegralX      hexadecimal             Integralb      binary                  Integralu      unsigned decimal        Integralf      floating point          RealFloatF      floating point          RealFloatg      general format float    RealFloatG      general format float    RealFloate      exponent format float   RealFloatE      exponent format float   RealFloats      string                  Stringv      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      Charu      other unsigned Integrald      other signed Integralg      RealFloats      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 forRealFloat types is currently a bit different from that of Cprintf(3), conforming instead toshowEFloat,showFFloat andshowGFloat (and their alternate versionsshowFFloatAlt andshowGFloatAlt). 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:

• Haskellprintf never uses the default "6-digit" precision used by C printf.
• Haskellprintf treats the "precision" specifier as indicating the number of digits after the decimal point.
• Haskellprintf prints the exponent of e-format numbers without a gratuitous plus sign, and with the minimum possible number of digits.
• Haskellprintf will place a zero after a decimal point when possible.

Similar toprintf, except that output is via the specifiedHandle. The return type is restricted to(IO a).

Typeclass ofprintf-formattable values. TheformatArg method takes a value and a field format descriptor and either fails due to a bad descriptor or produces aShowS as the result. The defaultparseFormat expects no modifiers: this is the normal case. Minimal instance:formatArg.

Minimal complete definition

formatArg

Methods

formatArg :: a ->FieldFormatterSource#

parseFormat :: a ->ModifierParserSource#

This is the type of a field formatter reified over its argument.

Since: 4.7.0.0

Description of field formatting forformatArg. See UNIXprintf(3) for a description of how field formatting works.

Since: 4.7.0.0

Constructors

Whether to left-adjust or zero-pad a field. These are mutually exclusive, withLeftAdjust taking precedence.

Since: 4.7.0.0

Constructors

How to handle the sign of a numeric field. These are mutually exclusive, withSignPlus taking precedence.

Since: 4.7.0.0

Constructors

Substitute a 'v' format character with the given default format character in theFieldFormat. A convenience for user-implemented types, which should support "%v".

Since: 4.7.0.0

Type of a function that will parse modifier characters from the format string.

Since: 4.7.0.0

The "format parser" walks over argument-type-specific modifier characters to find the primary format character. This is the type of its result.

Since: 4.7.0.0

Constructors

Formatter forString values.

Since: 4.7.0.0

Formatter forChar values.

Since: 4.7.0.0

Formatter forInt values.

Since: 4.7.0.0

Formatter forInteger values.

Since: 4.7.0.0

Formatter forRealFloat values.

Since: 4.7.0.0

Callsperror to indicate an unknown format letter for a given type.

Since: 4.7.0.0

Callsperror to indicate that the format string ended early.

Since: 4.7.0.0

Callsperror to indicate that there is a missing argument in the argument list.

Since: 4.7.0.0

Callsperror to indicate that there is a type error or similar in the given argument.

Since: 4.7.0.0

Raises anerror with a printf-specific prefix on the message string.

Since: 4.7.0.0

ThePrintfType class provides the variable argument magic forprintf. Its implementation is intentionally not visible from this module. If you attempt to pass an argument of a type which is not an instance of this class toprintf orhPrintf, then the compiler will report it as a missing instance ofPrintfArg.

Minimal complete definition

spr

TheHPrintfType class provides the variable argument magic forhPrintf. Its implementation is intentionally not visible from this module.

Minimal complete definition

hspr

This class, with only the one instance, is used as a workaround for the fact thatString, as a concrete type, is not allowable as a typeclass instance.IsChar is exported for backward-compatibility.

Methods

toChar :: c ->CharSource#

fromChar ::Char -> cSource#