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; + + + +

Text Formatting

@@ -58,19 +117,7 @@ td { text-align: left; vertical-align: top; Victor Zverovich, victor.zverovich@gmail.com -

-Introduction
-Design
-    Format String Syntax
-    Extensibility
-    Safety
-    Locale Support
-    Positional Arguments
-    Performance
-    Binary Footprint
-Proposed Wording
-References
-

+

Introduction

@@ -334,12 +381,6 @@ arguments, for example:

Proposed Wording

-

-The header <format> defines the function templates -format that format arguments and return the results as strings. -TODO: rephrase and mention format_args -

-

Header <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 a format-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-ids 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 the format-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 the format-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: +

+
 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'
 
+TODO +

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