diff --git a/doc/Text Formatting.html b/doc/Text Formatting.html index 4ad2700c..214cf7aa 100644 --- a/doc/Text Formatting.html +++ b/doc/Text Formatting.html @@ -46,6 +46,65 @@ td { text-align: left; vertical-align: top; + + + +
-Introduction
-Design
- Format String Syntax
- Extensibility
- Safety
- Locale Support
- Positional Arguments
- Performance
- Binary Footprint
-Proposed Wording
-References
-
-The header <format>
defines the function templates
-format
that format arguments and return the results as strings.
-TODO: rephrase and mention format_args
-
<format>
synopsis@@ -363,9 +404,13 @@ Format strings contain replacement fields surrounded by curly braces{}
. Anything that is not contained in braces is considered literal text, which is copied unchanged to the output. A brace character can be included in the literal text by doubling:{{
and}}
. -The syntax for replacement fields is as follows: ++The grammar for a replacement field is as follows: +
+ +- +replacement-field ::= '{' [arg-id] [':' format-spec] '}' arg-id ::= integer @@ -373,7 +418,75 @@ integer ::= digit+ digit ::= '0'...'9'
+In less formal terms, the replacement field can start with an +
+ +arg-id
that specifies the argument whose value is to be formatted +and inserted into the output instead of the replacement field. The +arg-id
is optionally followed by aformat-spec
, +which is preceded by a colon':'
. These specify a non-default +format for the replacement value. ++See also the Format specification mini-language +section. +
+ ++If the numerical
+ +arg-id
s in a format string are 0, 1, 2, ... in +sequence, they can all be omitted (not just some) and the numbers 0, 1, 2, ... +will be automatically inserted in that order. ++Some simple format string examples: +
+ +++ +"First, thou shalt count to {0}" // References the first argument +"Bring me a {}" // Implicitly references the first argument +"From {} to {}" // Same as "From {0} to {1}"
++The
+ +format-spec
field contains a specification of how the value +should be presented, including such details as field width, alignment, padding, +decimal precision and so on. Each value type can define its own formatting +mini-language or interpretation of theformat-spec
. ++Most built-in types support a common formatting mini-language, which is +described in the next section. +
+ ++A
+ +format-spec
field can also include nested replacement fields +within it. These nested replacement fields can contain only an argument index; +format specifications are not allowed. Formatting is performed as if the +replacement fields within theformat-spec
are substituted before +the format-spec string is interpreted. This allows the formatting of a value +to be dynamically specified. +Format specification mini-language
+ ++Format specifications are used within replacement fields contained +within a format string to define how individual values are presented (see +Format string syntax). Each formattable type may define +how the format specification is to be interpreted. +
+ ++Most built-in types implement the following options for format specifications, +although some of the formatting options are only supported by the numeric types. +
+ ++The general form of a standard format specifier is: +
++TODO +format-spec ::= [[fill] align] [sign] ['#'] ['0'] [width] ['.' precision] [type] fill ::= <a character other than '{' or '}'> @@ -385,6 +498,8 @@ type ::= int-type | 'a' | 'A' | 'c' | 'e' | 'E' | 'f' | 'F' | 'g' | 'G' int-type ::= 'b' | 'B' | 'd' | 'o' | 'x' | 'X'
Class
format_error
@@ -413,6 +528,10 @@ exceptions to report errors from the formatting library.Postcondition:
+strcmp(what(), what_arg) == 0
.Class
+ +format_args
TODO
+Function template
format