diff --git a/doc/Text Formatting.html b/doc/Text Formatting.html index e066313e..e8feaa88 100644 --- a/doc/Text Formatting.html +++ b/doc/Text Formatting.html @@ -4,6 +4,48 @@ Text Formatting + + +

Text Formatting

@@ -20,7 +62,8 @@ Victor Zverovich, victor.zverovich@gmail.com Introduction
Design
    Format String Syntax
-    Locale Support
+    Extensibility
+    Locale Support
Wording
References

@@ -38,8 +81,8 @@ user-defined types.

Example: -

-std::string message = std::format("The answer is {}.", 42)
+
+std::string message = std::format("The answer is {}.", 42);
 

 
 
Design

@@ -62,7 +105,7 @@ of issues:
 
  • There is no standard way to extend the syntax for user-defined types.
    • 
 
  • There are subtle differences between different implementations. For example,
     POSIX positional arguments [2] are not supported on
-    MSVC.
    • 
+    some systems [6].
 
  • Using '%' in a custom format specifier, e.g. for
     put_time-like time formatting, poses difficulties.
    • 
 
@@ -94,10 +137,88 @@ and it is described in details in TODO:link. Here are some of the advantages:
 
 
    
 The syntax is expressive enough to enable translation, possibly automated,
-of most printf format strings. TODO: table of correspondence between
-printf and the new syntax
+of most printf format strings. The correspondence between printf
+and the new syntax is given in the following table.
 
    
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
    printfnewcomment
    -<left alignment
    ++
    spacespace
    hhunused
    hunused
    lunused
    llunused
    junused
    zunused
    tunused
    Lunused
    cc (optional)
    ss (optional)
    dd (optional)
    id (optional)
    oo
    xx
    XX
    ud (optional)
    ff
    FF
    ee
    EE
    aa
    AA
    gg (optional)
    GG
    nunused
    pp (optional)
    
+
+
    
+Width and precision are represented similarly in printf and the
+proposed syntax with the only difference that runtime value is specified by
+* in the former and {} in the latter, possibly with
+the index of the argument inside the braces.
+
    
+
+
    
+As can be seen from the table above, most of the specifiers remain the same
+which simplifies migration from printf. Notable difference is in
+the alignment specification. The proposed syntax allows left, center, and right
+alignment represented by '<', '^', and
+'>' respectively which is more expressive than the corresponding
+printf syntax.
+
    
+
+
    Extensibility
    
+
+
    
+Both format string syntax and API are designed with extensibility in mind.
+The mini-language can be extended for user-defined types and users can provide
+functions that do parsing and formatting for such types.
+
    
+
+
    The general syntax of a replacement field in a format string is
+
+
    
+
    replacement-field:
    
+
    
+{ integeropt }
    
+{ integeropt
+  : format-spec }
+
    
+
    
+
+
    
+where format-spec is predefined for built-in types, but can be
+customized for user-defined types. For example, time formatting
+
+TODO: elaborate
    
+
 
    Locale Support
    
 
 
    TODO
    
@@ -106,8 +227,6 @@ printf and the new syntax
 
 
    TODO
    
 
-
    References
    
-
 
    Implementation
    
 
 
    
@@ -115,6 +234,8 @@ The ideas proposed in this paper have been implemented in the open-source fmt
 library. TODO: link
 
    
 
+
    References
    
+
 
    
 [1]
 The fprintf function. ISO/IEC 9899:2011. 7.21.6.1.
    
@@ -131,6 +252,10 @@ String.Format Method. .NET Framework Class Library.
    
 [5]
 
 Module std::fmt. The Rust Standard Library.
    
+[6]
+
+Format Specification Syntax: printf and wprintf Functions. C++ Language and
+Standard Libraries.