Update doc.

doc/string.rst

@@ -184,7 +184,7 @@ The general form of a *standard format specifier* is:
    align: "<" | ">" | "=" | "^"
    sign: "+" | "-" | " "
    width: `integer`
-   precision: `integer`
+   precision: `integer` | "{" `arg_index` "}"
    type: "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "o" | "p" | s" | "x" | "X"
 
 The *fill* character can be any character other than '{' or '}'.  The presence
@@ -299,21 +299,16 @@ The available integer presentation types are:
    +---------+----------------------------------------------------------+
    | ``'o'`` | Octal format. Outputs the number in base 8.              |
    +---------+----------------------------------------------------------+
-   | ``'x'`` | Hex format. Outputs the number in base 16, using lower-  |
+   | ``'x'`` | Hex format. Outputs the number in base 16, using         |
-   |         | case letters for the digits above 9.                     |
+   |         | lower-case letters for the digits above 9.               |
    +---------+----------------------------------------------------------+
-   | ``'X'`` | Hex format. Outputs the number in base 16, using upper-  |
+   | ``'X'`` | Hex format. Outputs the number in base 16, using         |
-   |         | case letters for the digits above 9.                     |
+   |         | upper-case letters for the digits above 9.               |
    +---------+----------------------------------------------------------+
    | none    | The same as ``'d'``.                                     |
    +---------+----------------------------------------------------------+
 
-In addition to the above presentation types, integers can be formatted
+The available presentation types for floating point values are:
-with the floating point presentation types listed below (except
-``'n'`` and none). When doing so, :func:`float` is used to convert the
-integer to a floating point number before formatting.
-
-The available presentation types for floating point and decimal values are:
 
    +---------+----------------------------------------------------------+
    | Type    | Meaning                                                  |
@@ -335,6 +330,19 @@ The available presentation types for floating point and decimal values are:
    |         | then formats the result in either fixed-point format     |
    |         | or in scientific notation, depending on its magnitude.   |
    |         |                                                          |
+   |         | A precision of ``0`` is treated as equivalent to a       |
+   |         | precision of ``1``.                                      |
+   +---------+----------------------------------------------------------+
+   | ``'G'`` | General format. Same as ``'g'`` except switches to       |
+   |         | ``'E'`` if the number gets too large. The                |
+   |         | representations of infinity and NaN are uppercased, too. |
+   +---------+----------------------------------------------------------+
+   | none    | The same as ``'g'``.                                     |
+   +---------+----------------------------------------------------------+
+
+.. ifconfig:: False
+
+   +---------+----------------------------------------------------------+
    |         | The precise rules are as follows: suppose that the       |
    |         | result formatted with presentation type ``'e'`` and      |
    |         | precision ``p-1`` would have exponent ``exp``.  Then     |
@@ -351,17 +359,17 @@ The available presentation types for floating point and decimal values are:
    |         | ``0``, ``-0`` and ``nan`` respectively, regardless of    |
    |         | the precision.                                           |
    |         |                                                          |
-   |         | A precision of ``0`` is treated as equivalent to a       |
-   |         | precision of ``1``.                                      |
    +---------+----------------------------------------------------------+
-   | ``'G'`` | General format. Same as ``'g'`` except switches to       |
+
-   |         | ``'E'`` if the number gets too large. The                |
+The available presentation types for pointers are:
-   |         | representations of infinity and NaN are uppercased, too. |
+
    +---------+----------------------------------------------------------+
-   | none    | Similar to ``'g'``, except with at least one digit past  |
+   | Type    | Meaning                                                  |
-   |         | the decimal point and a default precision of 12. This is |
+   +=========+==========================================================+
-   |         | intended to match :func:`str`, except you can add the    |
+   | ``'p'`` | Pointer format. This is the default type for             |
-   |         | other format modifiers.                                  |
+   |         | pointers and may be omitted.                             |
+   +---------+----------------------------------------------------------+
+   | none    | The same as ``'p'``.                                     |
    +---------+----------------------------------------------------------+
 
 
@@ -370,102 +378,87 @@ The available presentation types for floating point and decimal values are:
 Format examples
 ^^^^^^^^^^^^^^^
 
-This section contains examples of the new format syntax and comparison with
+This section contains examples of the format syntax and comparison with
-the old ``%``-formatting.
+the printf formatting.
 
-In most of the cases the syntax is similar to the old ``%``-formatting, with the
+In most of the cases the syntax is similar to the printf formatting, with the
 addition of the ``{}`` and with ``:`` used instead of ``%``.
-For example, ``'%03.2f'`` can be translated to ``'{:03.2f}'``.
+For example, ``"%03.2f"`` can be translated to ``"{:03.2f}"``.
 
 The new format syntax also supports new and different options, shown in the
-follow examples.
+following examples.
 
 Accessing arguments by position::
 
-   >>> '{0}, {1}, {2}'.format('a', 'b', 'c')
+   Format("{0}, {1}, {2}") << 'a' << 'b' << 'c';
-   'a, b, c'
+   // Result: "a, b, c"
-   >>> '{}, {}, {}'.format('a', 'b', 'c')  # 3.1+ only
+   Format("{}, {}, {}") << 'a' << 'b' << 'c';
-   'a, b, c'
+   // Result: "a, b, c"
-   >>> '{2}, {1}, {0}'.format('a', 'b', 'c')
+   Format("{2}, {1}, {0}") << 'a' << 'b' << 'c';
-   'c, b, a'
+   // Result: "c, b, a"
-   >>> '{2}, {1}, {0}'.format(*'abc')      # unpacking argument sequence
+   Format("{0}{1}{0}" << "abra" << "cad";  // arguments' indices can be repeated
-   'c, b, a'
+   // Result: "abracadabra"
-   >>> '{0}{1}{0}'.format('abra', 'cad')   # arguments' indices can be repeated
-   'abracadabra'
-
-Accessing arguments by name::
-
-   >>> 'Coordinates: {latitude}, {longitude}'.format(latitude='37.24N', longitude='-115.81W')
-   'Coordinates: 37.24N, -115.81W'
-   >>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'}
-   >>> 'Coordinates: {latitude}, {longitude}'.format(**coord)
-   'Coordinates: 37.24N, -115.81W'
-
-Accessing arguments' items::
-
-   >>> coord = (3, 5)
-   >>> 'X: {0[0]};  Y: {0[1]}'.format(coord)
-   'X: 3;  Y: 5'
 
 Aligning the text and specifying a width::
 
-   >>> '{:<30}'.format('left aligned')
+   Format("{:<30}") << "left aligned";
-   'left aligned                  '
+   // Result: "left aligned                  "
-   >>> '{:>30}'.format('right aligned')
+   Format("{:>30}") << "right aligned"
-   '                 right aligned'
+   // Result: "                 right aligned"
-   >>> '{:^30}'.format('centered')
+   Format("{:^30}") << "centered"
-   '           centered           '
+   // Result: "           centered           "
-   >>> '{:*^30}'.format('centered')  # use '*' as a fill char
+   Format("{:*^30}") << "centered"  // use '*' as a fill char
-   '***********centered***********'
+   // Result: "***********centered***********"
 
 Replacing ``%+f``, ``%-f``, and ``% f`` and specifying a sign::
 
-   >>> '{:+f}; {:+f}'.format(3.14, -3.14)  # show it always
+   Format("{:+f}; {:+f}") << 3.14 << -3.14;  // show it always
-   '+3.140000; -3.140000'
+   // Result: "+3.140000; -3.140000"
-   >>> '{: f}; {: f}'.format(3.14, -3.14)  # show a space for positive numbers
+   Format("{: f}; {: f}") << 3.14 << -3.14;  // show a space for positive numbers
-   ' 3.140000; -3.140000'
+   // Result: " 3.140000; -3.140000"
-   >>> '{:-f}; {:-f}'.format(3.14, -3.14)  # show only the minus -- same as '{:f}; {:f}'
+   Format("{:-f}; {:-f}") << 3.14 << -3.14;  // show only the minus -- same as '{:f}; {:f}'
-   '3.140000; -3.140000'
+   // Result: "3.140000; -3.140000"
 
 Replacing ``%x`` and ``%o`` and converting the value to different bases::
 
-   >>> # format also supports binary numbers
+   Format("int: {0:d};  hex: {0:x};  oct: {0:o}") << 42;
-   >>> "int: {0:d};  hex: {0:x};  oct: {0:o};  bin: {0:b}".format(42)
+   // Result: "int: 42;  hex: 2a;  oct: 52"
-   'int: 42;  hex: 2a;  oct: 52;  bin: 101010'
+   // with 0x or 0 as prefix:
-   >>> # with 0x, 0o, or 0b as prefix:
+   Format("int: {0:d};  hex: {0:#x};  oct: {0:#o}") << 42;
-   >>> "int: {0:d};  hex: {0:#x};  oct: {0:#o};  bin: {0:#b}".format(42)
+   // Result: "int: 42;  hex: 0x2a;  oct: 052"
-   'int: 42;  hex: 0x2a;  oct: 0o52;  bin: 0b101010'
+
+.. ifconfig:: False
 
    Using the comma as a thousands separator::
 
-   >>> '{:,}'.format(1234567890)
+      Format("{:,}") << 1234567890)
       '1,234,567,890'
 
    Expressing a percentage::
 
       >>> points = 19
       >>> total = 22
-   >>> 'Correct answers: {:.2%}'.format(points/total)
+      Format("Correct answers: {:.2%}") << points/total)
       'Correct answers: 86.36%'
 
    Using type-specific formatting::
 
       >>> import datetime
       >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)
-   >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)
+      Format("{:%Y-%m-%d %H:%M:%S}") << d)
       '2010-07-04 12:15:58'
 
    Nesting arguments and more complex examples::
 
       >>> for align, text in zip('<^>', ['left', 'center', 'right']):
-   ...     '{0:{fill}{align}16}'.format(text, fill=align, align=align)
+      ...     '{0:{fill}{align}16}") << text, fill=align, align=align)
       ...
       'left<<<<<<<<<<<<'
       '^^^^^center^^^^^'
       '>>>>>>>>>>>right'
       >>>
       >>> octets = [192, 168, 0, 1]
-   >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)
+      Format("{:02X}{:02X}{:02X}{:02X}") << *octets)
       'C0A80001'
       >>> int(_, 16)
       3232235521
@@ -473,7 +466,7 @@ Nesting arguments and more complex examples::
       >>> width = 5
       >>> for num in range(5,12):
       ...     for base in 'dXob':
-   ...         print('{0:{width}{base}}'.format(num, base=base, width=width), end=' ')
+      ...         print('{0:{width}{base}}") << num, base=base, width=width), end=' ')
       ...     print()
       ...
           5     5     5   101