hare

README (4311B)

---

 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 can 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 will be formatted: inline format
 modifiers, and parametric format modifiers.
 
 Inline format modifiers are a series of characters within a format sequence.
 You can use a colon to add format modifiers; for example, "{:x}" will format an
 argument in hexadecimal, and "{3:-10}" will left-align the 4th argument (zero
 indexed) to at least 10 characters.
 
 Format modifiers can be written in any order, and can also be repeated. If a
 modifier is repeated (or two conflicting modifiers are given, such as both "x"
 and "X") the one furthest to the right will be used.
 
 A format modifier can be any of the following:
 - A number N: Sets the width to N. If the value would otherwise be shorter than
   N runes, insert padding characters in order to make it N runes long. By
   default, the value is right-aligned, with padding inserted on the left side,
   and the padding character is " " (a space).
 - "-": Left-align the value, inserting padding characters inserted on the right
   side of the value in order to meet the width requirement.
 - "=": Center-align the value, inserting the same amount of padding on the left
   as on the right. If an odd number of padding characters need to be placed, the
   extra one will be on the left of the value.
 - "_" followed by a rune: Use the given rune as the padding character rather
   than the default of " " (a space).
 - " " (a space): Insert a space before positive integers, where "-" would be if
   it were negative.
 - "+": Insert a "+" before positive integers.
 - "x": Format numbers in lowercase hexadecimal.
 - "X": Format numbers in uppercase hexadecimal.
 - "o": Format numbers in octal.
 - "b": Format numbers in binary.
 - "e": Format floats in scientific notation.
 - "f": Format floats in fixed-point notation.
 - "g": Format floats in whichever of scientific and fixed-point notation is
   shortest. This is the default.
 - "F" followed by "s": Use a sign for both positive and negative numbers.
 - "F" followed by ".": Always include at least one digit after the decimal
   point.
 - "F" followed by "U": Uppercase INFINITY and NAN.
 - "F" followed by "E": Uppercase exponent symbols (E and P rather than e and p).
 - "F" followed by "S": Use a sign for both positive and negative exponents.
 - "F" followed by "2": Show at least two digits of the exponent.
 - "." followed by a number N: Sets the precision to N. Integers will be
   left-padded with "0"s between the sign and the number itself. Strings
   will be truncated to N runes. Floats will only include up to N digits after
   the decimal point.
 
 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("{:.5}", 42);			// "00042"
 
 A parametric format modifier is a secondary argument from the parameter list,
 which is a pointer to an instance of [[mods]]. This modifier parameter
 describes 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 the 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::mods { ... },
 		"world", &fmt::mods { ... });
 
 	// "|hello|     world|0000000123|BEEF|"
 	fmt::printf("|{%}|{%}|{%}|{%}|",
 		"hello", &fmt::mods { ... },
 		"world", &fmt::mods { pad = ' ', width = 10, ... },
 		123,     &fmt::mods { prec = 10, ... },
 		0xBEEF,  &fmt::mods { base = strconv::base::HEX, ... });