Output is sent to this writer. Typical output writers include std.array.Appender!string and std.stdio.LockingTextWriter.
Format string.
Variadic argument list.
Formatted number of arguments.
Mismatched arguments and formats result in a FormatException being thrown.
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.
The format string has the following grammar:
FormatString: FormatStringItem* FormatStringItem: '%%' '%' Position Flags Width Separator Precision FormatChar '%(' FormatString '%)' '%-(' FormatString '%)' OtherCharacterExceptPercent Position: empty Integer '$' Flags: empty '-' Flags '+' Flags '#' Flags '0' Flags ' ' Flags Width: empty Integer '*' Separator: empty ',' ',' '?' ',' '*' '?' ',' Integer '?' ',' '*' ',' Integer Precision: empty '.' '.' Integer '.*' Integer: Digit Digit Integer Digit: '0'|'1'|'2'|'3'|'4'|'5'|'6'|'7'|'8'|'9' FormatChar: 's'|'c'|'b'|'d'|'o'|'x'|'X'|'e'|'E'|'f'|'F'|'g'|'G'|'a'|'A'|'|'
Flag | Types affected | Semantics |
---|---|---|
'-' | numeric, bool, null, char, string, enum, pointer | Left justify the result in the field. It overrides any 0 flag. |
'+' | numeric | Prefix positive numbers in a signed conversion with a +. It overrides any space flag. |
'#' | integral ('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. |
'#' | integral ('x', 'X') | If non-zero, prefix result with 0x (0X). |
'#' | floating | Always insert the decimal point and print trailing zeros. |
'0' | numeric | Use leading zeros to pad rather than spaces (except for the floating point values nan and infinity). Ignore if there's a Precision. |
' ' | numeric | Prefix positive numbers in a signed conversion with a space. |
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.
The positional and non-positional styles can be mixed in the same format string. (POSIX leaves this behavior undefined.) The internal counter for non-positional parameters tracks the next parameter after the largest positional parameter already used.
Example using array and nested array formatting:
import std.stdio; void main() { writefln("My items are %(%s %).", [1,2,3]); writefln("My items are %(%s, %).", [1,2,3]); }
The output is:
My items are 1 2 3. My items are 1, 2, 3.
The trailing end of the sub-format string following the specifier for each item is interpreted as the array delimiter, and is therefore omitted following the last array item. The %| delimiter specifier may be used to indicate where the delimiter begins, so that the portion of the format string prior to it will be retained in the last array element:
import std.stdio; void main() { writefln("My items are %(-%s-%|, %).", [1,2,3]); }
which gives the output:
My items are -1-, -2-, -3-.
These compound format specifiers may be nested in the case of a nested array argument:
1 import std.stdio; 2 void main() { 3 auto mat = [[1, 2, 3], 4 [4, 5, 6], 5 [7, 8, 9]]; 6 7 writefln("%(%(%d %)\n%)", mat); 8 writeln(); 9 10 writefln("[%(%(%d %)\n %)]", mat); 11 writeln(); 12 13 writefln("[%([%(%d %)]%|\n %)]", mat); 14 writeln(); 15 }
The output is:
1 2 3 4 5 6 7 8 9[1 2 3 4 5 6 7 8 9]
[[1 2 3] [4 5 6] [7 8 9]]
Inside a compound format specifier, strings and characters are escaped automatically. To avoid this behavior, add '-' flag to "%$(LPAREN)".
import std.stdio; void main() { writefln("My friends are %s.", ["John", "Nancy"]); writefln("My friends are %(%s, %).", ["John", "Nancy"]); writefln("My friends are %-(%s, %).", ["John", "Nancy"]); }
which gives the output:
My friends are ["John", "Nancy"]. My friends are "John", "Nancy". My friends are John, Nancy.
The format string can be checked at compile-time (see format for details):
import std.array : appender; auto writer = appender!string(); writer.formattedWrite!"%s is the ultimate %s."(42, "answer"); assert(writer.data == "42 is the ultimate answer."); // Clear the writer writer = appender!string(); formattedWrite(writer, "Date: %2$s %1$s", "October", 5); assert(writer.data == "Date: 5 October");
assert(format("%,d", 1000) == "1,000"); assert(format("%,f", 1234567.891011) == "1,234,567.891011"); assert(format("%,?d", '?', 1000) == "1?000"); assert(format("%,1d", 1000) == "1,0,0,0", format("%,1d", 1000)); assert(format("%,*d", 4, -12345) == "-1,2345"); assert(format("%,*?d", 4, '_', -12345) == "-1_2345"); assert(format("%,6?d", '_', -12345678) == "-12_345678"); assert(format("%12,3.3f", 1234.5678) == " 1,234.568", "'" ~ format("%12,3.3f", 1234.5678) ~ "'");
Interprets variadic argument list args, formats them according to fmt, and sends the resulting characters to w. The encoding of the output is the same as Char. The type Writer must satisfy std.range.primitives.isOutputRange!(Writer, Char).
The variadic arguments are normally consumed in order. POSIX-style positional parameter syntax is also supported. Each argument is formatted into a sequence of chars according to the format specification, and the characters are passed to w. As many arguments as specified in the format string are consumed and formatted. If there are fewer arguments than format specifiers, a FormatException is thrown. If there are more remaining arguments than needed by the format specification, they are ignored but only if at least one argument was formatted.
The format string supports the formatting of array and nested array elements via the grouping format specifiers %( and %). Each matching pair of %( and %) corresponds with a single array argument. The enclosed sub-format string is applied to individual array elements. The trailing portion of the sub-format string following the conversion specifier for the array element is interpreted as the array delimiter, and is therefore omitted following the last array element. The %| specifier may be used to explicitly indicate the start of the delimiter, so that the preceding portion of the string will be included following the last array element. (See below for explicit examples.)