| 1 |
fmt: formatted string I/O |
| 2 |
|
| 3 |
A format string consists of a string of literal characters, to be printed |
| 4 |
verbatim, and format sequences, which describe how to format arguments from a |
| 5 |
set of variadic parameters for printing. |
| 6 |
|
| 7 |
A format sequence is enclosed in curly braces "{}". An empty sequence takes the |
| 8 |
next argument from the parameter list, in order. A specific parameter can be |
| 9 |
selected by indexing it from zero: "{0}", "{1}", and so on. To print "{", use |
| 10 |
"{{", and for "}", use "}}". |
| 11 |
|
| 12 |
There are two ways to specify how an argument will be formatted: inline format |
| 13 |
modifiers, and parametric format modifiers. |
| 14 |
|
| 15 |
Inline format modifiers are a series of characters within a format sequence. |
| 16 |
You can use a colon to add format modifiers; for example, "{:x}" will format an |
| 17 |
argument in hexadecimal, and "{3:-10}" will left-align the 4th argument (zero |
| 18 |
indexed) to at least 10 characters. |
| 19 |
|
| 20 |
Format modifiers can be written in any order, and can also be repeated. If |
| 21 |
multiple conflicting modifiers are given (such as both "x" and "X"), the one |
| 22 |
furthest to the right will be used. |
| 23 |
|
| 24 |
A format modifier can be any of the following: |
| 25 |
- a number N: Sets the width to N. If the value would otherwise be shorter than |
| 26 |
N runes, insert padding characters in order to make it N runes long. By |
| 27 |
default, the value is right-aligned, with padding inserted on the left side, |
| 28 |
and the padding character is " " (a space). |
| 29 |
- "-": Left-align the value, inserting padding characters on the right side of |
| 30 |
the value in order to meet the width requirement. |
| 31 |
- "=": Center-align the value, inserting the same amount of padding on the left |
| 32 |
as on the right. If an odd number of padding characters need to be placed, the |
| 33 |
extra one will be on the left of the value. |
| 34 |
- "_" followed by a rune: Use the given rune as the padding character rather |
| 35 |
than the default of " " (a space). |
| 36 |
- " " (a space): Insert a space before positive integers, where "-" would be if |
| 37 |
it were negative. |
| 38 |
- "+": Insert a "+" before positive integers. |
| 39 |
- "x": Format numbers in lowercase hexadecimal. |
| 40 |
- "X": Format numbers in uppercase hexadecimal. |
| 41 |
- "o": Format numbers in octal. |
| 42 |
- "b": Format numbers in binary. |
| 43 |
- "e": Format floats in scientific notation. |
| 44 |
- "f": Format floats in fixed-point notation. |
| 45 |
- "g": Format floats in whichever of scientific and fixed-point notation is |
| 46 |
shortest. This is the default. |
| 47 |
- "F" followed by "s": Use a sign for both positive and negative numbers. |
| 48 |
- "F" followed by ".": Always include at least one digit after the decimal |
| 49 |
point. |
| 50 |
- "F" followed by "U": Uppercase INFINITY and NAN. |
| 51 |
- "F" followed by "E": Uppercase exponent symbols (E and P rather than e and p). |
| 52 |
- "F" followed by "S": Use a sign for both positive and negative exponents. |
| 53 |
- "F" followed by "2": Show at least two digits of the exponent. |
| 54 |
- "." followed by a number N: Sets the precision to N. Integers will be |
| 55 |
left-padded with "0"s between the sign and the number itself. Strings |
| 56 |
will be truncated to N runes. Floats will include up to N digits, counted |
| 57 |
as per [[strconv::ftosf]], including those before the decimal point in the |
| 58 |
default case ("g"), excluding them when "f" or "e" are set. |
| 59 |
|
| 60 |
Some inline modifier examples: |
| 61 |
|
| 62 |
fmt::printf("hello {}", "world"); // "hello world" |
| 63 |
fmt::printf("{1} {0}", "hello", "world"); // "world hello" |
| 64 |
fmt::printf("{:x} {:X}", 51966, 61453); // "cafe F00D" |
| 65 |
fmt::printf("{:-5}", 42); // "42 " |
| 66 |
fmt::printf("{:5}", 42); // " 42" |
| 67 |
fmt::printf("{:.5}", 42); // "00042" |
| 68 |
fmt::printf("{:.2f}", 42.87934); // "42.88" |
| 69 |
|
| 70 |
A parametric format modifier is a secondary argument from the parameter list, |
| 71 |
which is a pointer to an instance of [[mods]]. This modifier parameter |
| 72 |
describes how the primary formattable argument is formatted. |
| 73 |
|
| 74 |
A parametric format sequence of this sort takes the form of "{i%j}", where i is |
| 75 |
the formattable parameter index, j is the modifiers parameter index, and i & j |
| 76 |
are optional. If either i or j aren't explicitly provided by the user, they |
| 77 |
will evaluate to the index of the next unused argument. |
| 78 |
|
| 79 |
Some parametric modifier examples: |
| 80 |
|
| 81 |
// "hello world hello" |
| 82 |
fmt::printf("{%} {%} {0%1}", // evaluates to "{0%1} {2%3} {0%1}" |
| 83 |
"hello", &fmt::mods { ... }, |
| 84 |
"world", &fmt::mods { ... }); |
| 85 |
|
| 86 |
// "|hello| world|0000000123|BEEF|" |
| 87 |
fmt::printf("|{%}|{%}|{%}|{%}|", |
| 88 |
"hello", &fmt::mods { ... }, |
| 89 |
"world", &fmt::mods { pad = ' ', width = 10, ... }, |
| 90 |
123, &fmt::mods { prec = 10, ... }, |
| 91 |
0xBEEF, &fmt::mods { base = strconv::base::HEX, ... }); |
| 92 |
|