std.format
This module implements the workhorse functionality for string and I/O formatting. It's comparable to C99's vsprintf().Source:
std/format.d
- class FormatError: object.Error;
- Signals a mismatch between a format and its corresponding argument.
- void doFormat(void delegate(dchar) putc, TypeInfo[] arguments, va_list argptr);
- Interprets variadic argument list pointed to by argptr whose types are given
by arguments[], formats them according to embedded format strings in the
variadic argument list, and sends the resulting characters to putc.
The variadic arguments are consumed in order. Each is formatted into a sequence of chars, using the default format specification for its type, and the characters are sequentially passed to putc. If a char[], wchar[], or dchar[] argument is encountered, it is interpreted as a format string. As many arguments as specified in the format string are consumed and formatted according to the format specifications in that string and passed to putc. If there are too few remaining arguments, a FormatError is thrown. If there are more remaining arguments than needed by the format specification, the default processing of arguments resumes until they are all consumed.
Params:
void delegate(dchar) putc Output is sent do this delegate, character by character. TypeInfo[] arguments Array of TypeInfo's, one for each argument to be formatted. va_list argptr Points to variadic argument list.
Throws:
Mismatched arguments and formats result in a FormatError being thrown.
Format String:
Format strings consist of characters interspersed with format specifications. Characters are simply copied to the output (such as putc) after any necessary conversion to the corresponding UTF-8 sequence.
A format specification starts with a '%' character, and has the following grammar:
FormatSpecification: '%%' '%' Flags Width Precision FormatChar
Flags: empty '-' Flags '+' Flags '#' Flags '0' Flags ' ' Flags
Width: empty Integer '*'
Precision: empty '.' '.' Integer '.*'
Integer: Digit Digit Integer
Digit: '0' '1' '2' '3' '4' '5' '6' '7' '8' '9'
FormatChar: 's' 'b' 'd' 'o' 'x' 'X' 'e' 'E' 'f' 'F' 'g' 'G' 'a' 'A'- Flags
- '-'
-
Left justify the result in the field.
It overrides any 0 flag.
- '+'
- Prefix positive numbers in a signed conversion with a +.
It overrides any space flag.
- '#'
- Use alternative formatting:
- For 'o':
- Add to precision as necessary so that the first digit of the octal formatting is a '0', even if both the argument and the Precision are zero.
- For 'x' ('X'):
- If non-zero, prefix result with 0x (0X).
- For floating point formatting:
- Always insert the decimal point.
- For 'g' ('G'):
- Do not elide trailing zeros.
- '0'
- For integer and floating point formatting when not nan or
infinity, use leading zeros
to pad rather than spaces.
Ignore if there's a Precision.
- ' '
- Prefix positive numbers in a signed conversion with a space.
- Width
-
Specifies the minimum field width.
If the width is a *, the next argument, which must be
of type int, is taken as the width.
If the width is negative, it is as if the - was given
as a Flags character.
- Precision
- Gives the precision for numeric conversions.
If the precision is a *, the next argument, which must be
of type int, is taken as the precision. If it is negative,
it is as if there was no Precision.
- FormatChar
-
- 's'
- The corresponding argument is formatted in a manner consistent
with its type:
- bool
- The result is 'true' or 'false'.
- integral types
- The %d format is used.
- floating point types
- The %g format is used.
- string types
- The result is the string converted to UTF-8. A Precision specifies the maximum number of characters to use in the result.
- classes derived from Object
- The result is the string returned from the class instance's .toString() method. A Precision specifies the maximum number of characters to use in the result.
- non-string static and dynamic arrays
- The result is [s0, s1, ...] where sk is the kth element formatted with the default format.
- 'b','d','o','x','X'
- The corresponding argument must be an integral type
and is formatted as an integer. If the argument is a signed type
and the FormatChar is d it is converted to
a signed string of characters, otherwise it is treated as
unsigned. An argument of type bool is formatted as '1'
or '0'. The base used is binary for b, octal for o,
decimal
for d, and hexadecimal for x or X.
x formats using lower case letters, X uppercase.
If there are fewer resulting digits than the Precision,
leading zeros are used as necessary.
If the Precision is 0 and the number is 0, no digits
result.
- 'e','E'
- A floating point number is formatted as one digit before
the decimal point, Precision digits after, the FormatChar,
±, followed by at least a two digit exponent: d.dddddde±dd.
If there is no Precision, six
digits are generated after the decimal point.
If the Precision is 0, no decimal point is generated.
- 'f','F'
- A floating point number is formatted in decimal notation.
The Precision specifies the number of digits generated
after the decimal point. It defaults to six. At least one digit
is generated before the decimal point. If the Precision
is zero, no decimal point is generated.
- 'g','G'
- A floating point number is formatted in either e or
f format for g; E or F format for
G.
The f format is used if the exponent for an e format
is greater than -5 and less than the Precision.
The Precision specifies the number of significant
digits, and defaults to six.
Trailing zeros are elided after the decimal point, if the fractional
part is zero then no decimal point is generated.
- 'a','A'
- A floating point number is formatted in hexadecimal exponential notation 0xh.hhhhhhp±d. There is one hexadecimal digit before the decimal point, and as many after as specified by the Precision. If the Precision is zero, no decimal point is generated. If there is no Precision, as many hexadecimal digits as necessary to exactly represent the mantissa are generated. The exponent is written in as few digits as possible, but at least one, is in decimal, and represents a power of 2 as in h.hhhhhh*2±d. The exponent for zero is zero. The hexadecimal digits, x and p are in upper case if the FormatChar is upper case.
Floating point NaN's are formatted as nan if the FormatChar is lower case, or NAN if upper. Floating point infinities are formatted as inf or infinity if the FormatChar is lower case, or INF or INFINITY if upper.
Example:
import std.c.stdio; import std.format; void formattedPrint(...) { void putc(char c) { fputc(c, stdout); } std.format.doFormat(&putc, _arguments, _argptr); } ... int x = 27; // prints 'The answer is 27:6' formattedPrint("The answer is %s:", x, 6);