diff --git a/doc/Text Formatting.html b/doc/Text Formatting.html index ae137fa1..fda0c067 100644 --- a/doc/Text Formatting.html +++ b/doc/Text Formatting.html @@ -66,7 +66,8 @@ Victor Zverovich, victor.zverovich@gmail.com     Safety
    Locale Support
    Positional Arguments
-Wording
+    Binary Footprint
+Proposed Wording
References

@@ -134,7 +135,8 @@ and it is described in details in TODO:link. Here are some of the advantages:
  • Positional arguments
  • Support for both locale-specific and locale-independent formatting (see Locale Support)
    • -
  • Minor formatting improvements such as center alignment and binary format +
  • Formatting improvements such as better alignment control, fill character, + and binary format

    @@ -145,40 +147,40 @@ and the new syntax is given in the following table. - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    printfnewcomment
    printfnew
    -<left alignment
    ++
    spacespace
    ##
    00
    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)
    -<
    ++
    spacespace
    ##
    00
    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)
    @@ -223,17 +225,12 @@ 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 } -
    -
    +
    +replacement-field ::=  '{' [arg-id] [':' format-spec] '}'
+

    -where format-spec is predefined for built-in types, but can be +where format-spec is predefined for built-in types, but can be customized for user-defined types. For example, the syntax can be extended for put_time-like date and time formatting

    @@ -277,21 +274,105 @@ easily control whether to use locales or not during formatting. We follow Python's approach [3] and designate a separate format specifier 'n' for locale-aware numeric formatting. It applies to all integral and floating-point types. All other specifiers produce output -unaffected by locale settings. +unaffected by locale settings. This can also have positive peformance effect +because locale-independent formatting can be implemented more efficiently.

    Positional Arguments

    -

    TODO

    +

    +An important feature for localization is the ability to rearrange formatting +arguments because the word order may vary in different languages +[3]. For example: +

    + +
    +printf("String `%s' has %d characters\n", string, length(string)))
+
    + +

    A possible German translation of the format string might be:

    + +
    +"%2$d Zeichen lang ist die Zeichenkette `%1$s'\n"
+
    + +

    +using POSIX positional arguments [2]. Unfortunately these +positional specifiers are not portable [6]. The C++ I/O +streams don't support positional arguments by design because formatting +arguments are interleaved with the portions of the literal string: +

    + +
    +std::cout << "String `" << string << "' has " << length(string) << " characters\n"
+
    + +

    +The current proposal allows both positional and automatically numbered +arguments, for example: +

    + +
    +std::format("String `{}' has {} characters\n", string, length(string)))
+
    + +

    with the German translation of the format string:

    + +
    +"{1} Zeichen lang ist die Zeichenkette `{0}'\n"
+

    Performance

    TODO

    -

    Wording

    +

    Binary Footprint

    TODO

    +

    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

    + +
    +namespace std {
+  class format_args;
+
+  template <class Char>
+  basic_string<Char> format(const Char *fmt, format_args args);
+
+  template <class Char, class ...Args>
+  basic_string<Char> format(const Char *fmt, const Args&... args);
+}
+
    + +

    Format string syntax

    + +
    +replacement-field ::=  '{' [arg-id] [':' format-spec] '}'
+arg-id            ::=  integer
+integer           ::=  digit+
+digit             ::=  '0'...'9'
+
    + + +
    +format-spec ::=  [[fill] align] [sign] ['#'] ['0'] [width] ['.' precision] [type]
+fill        ::=  <a character other than '{' or '}'>
+align       ::=  '<' | '>' | '=' | '^'
+sign        ::=  '+' | '-' | ' '
+width       ::=  integer | '{' arg-id '}'
+precision   ::=  integer | '{' arg-id '}'
+type        ::=  int-type | 'a' | 'A' | 'c' | 'e' | 'E' | 'f' | 'F' | 'g' | 'G' | 'p' | 's'
+int-type    ::=  'b' | 'B' | 'd' | 'o' | 'x' | 'X'
+
    +

    Implementation

    @@ -321,6 +402,9 @@ Module std::fmt. The Rust Standard Library.
    Format Specification Syntax: printf and wprintf Functions. C++ Language and Standard Libraries.
    +[7] + +10.4.2 Rearranging printf Arguments. The GNU Awk User's Guide.