From 4dc9fd995fad81a508bf8d852209593b9daea54f Mon Sep 17 00:00:00 2001 From: Victor Zverovich Date: Wed, 24 Aug 2016 06:55:18 -0700 Subject: [PATCH] Update paper --- doc/Text Formatting.html | 161 ++++++++++++++++++++++++++++++++++----- 1 file changed, 140 insertions(+), 21 deletions(-) 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