~sircmpwn/hare

hare/fmt/README -rw-r--r-- 3.2 KiB
5c7cd775Alexey Yerin all: add 0 value to enums used as flags 2 days ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
A format string consists of a string of literal characters, to be printed
verbatim, and format sequences, which describe how to format arguments from a
set of variadic parameters for printing.

A format sequence is enclosed in curly braces "{}". An empty sequence takes the
next argument from the parameter list, in order. A specific parameter may be
selected by indexing it from zero: "{0}", "{1}", and so on. To print "{", use
"{{", and for "}", use "}}".

There are two ways to specify how an argument shall be formatted: inline format
modifiers, and parametric format modifiers.

Inline format modifiers are a series of characters within a format sequence.
You may use a colon to add format modifiers; for example, "{:x}" will format an
argument in hexadecimal, and "{3:-10}" will left-align the 3rd argument to at
least 10 characters.

The format modifiers takes the form of an optional flag character:

- "0": Numeric values are zero-padded up to the required width.
- "-": The value shall be left-aligned, and spaces inserted on the right to meet the required width. "-" takes precedence over "0" if both are used.
- " ": (a space) insert a space before positive numbers, where "-" would be if it were negative.
- "+": insert a "+" before positive numbers, where "-" would be if it were negative. "+" takes precedence over " " if both are used.

Following the flag, an optional decimal number shall specify the minimum width
of this field. If "0" or "-" were not given, the default behavior shall be to
pad with spaces to achieve the necessary width.

Following the width, an optional precision may be given as a decimal number
following a "." character. For integer types, this gives the minimum number of
digits to include. For floating types, this gives the number of digits following
the radix to include.

Following the precision, an optional character controls the output format:

- x, X: print in lowercase or uppercase hexadecimal
- o, b: print in octal or binary

Some inline modifier examples:

	fmt::printf("hello {}", "world");		// "hello world"
	fmt::printf("{1} {0}", "hello", "world");	// "world hello"
	fmt::printf("{:x} {:X}", 51966, 61453);		// "cafe F00D"
	fmt::printf("{:-5}", 42);			// "42   "
	fmt::printf("{:5}", 42);			// "   42"
	fmt::printf("{:05}", 42);			// "00042"

A parametric format modifier is a secondary argument from the parameter list,
which is a pointer to an instance of [[fmt::modifiers]]. This modifier parameter
shall describe how the primary formattable argument is formatted.

A parametric format sequence of this sort takes the form of "{i%j}", where i is
the formattable parameter index, j is the modifiers parameter index, and i & j
are optional. If either i or j aren't explicitly provided by the user, they
will evaluate to index of the next unused argument.

Some parametric modifier examples:

	// "hello world hello"
	fmt::printf("{%} {%} {0%1}", // evaluates to "{0%1} {2%3} {0%1}"
		"hello", &fmt::modifiers { ... },
		"world", &fmt::modifiers { ... });

	// "|hello|     world|0000000123|BEEF|"
	fmt::printf("|{%}|{%}|{%}|{%}|",
		"hello", &fmt::modifiers { ... },
		"world", &fmt::modifiers { width = 10, ... },
		123,     &fmt::modifiers { width = 10, padding = fmt::padding::ZEROES, ... },
		0xBEEF,  &fmt::modifiers { base = strconv::base::HEX, ... });