diff --git a/doc/string.rst b/doc/string.rst index 1618f160..0509de7a 100644 --- a/doc/string.rst +++ b/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- | - | | case letters for the digits above 9. | + | ``'x'`` | Hex format. Outputs the number in base 16, using | + | | lower-case letters for the digits above 9. | +---------+----------------------------------------------------------+ - | ``'X'`` | Hex format. Outputs the number in base 16, using upper- | - | | case letters for the digits above 9. | + | ``'X'`` | Hex format. Outputs the number in base 16, using | + | | upper-case letters for the digits above 9. | +---------+----------------------------------------------------------+ | none | The same as ``'d'``. | +---------+----------------------------------------------------------+ -In addition to the above presentation types, integers can be formatted -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: +The available presentation types for floating point 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 | - | | representations of infinity and NaN are uppercased, too. | + +The available presentation types for pointers are: + +---------+----------------------------------------------------------+ - | none | Similar to ``'g'``, except with at least one digit past | - | | the decimal point and a default precision of 12. This is | - | | intended to match :func:`str`, except you can add the | - | | other format modifiers. | + | Type | Meaning | + +=========+==========================================================+ + | ``'p'`` | Pointer format. This is the default type for | + | | pointers and may be omitted. | + +---------+----------------------------------------------------------+ + | none | The same as ``'p'``. | +---------+----------------------------------------------------------+ @@ -370,117 +378,102 @@ 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 -the old ``%``-formatting. +This section contains examples of the format syntax and comparison with +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') - 'a, b, c' - >>> '{}, {}, {}'.format('a', 'b', 'c') # 3.1+ only - 'a, b, c' - >>> '{2}, {1}, {0}'.format('a', 'b', 'c') - 'c, b, a' - >>> '{2}, {1}, {0}'.format(*'abc') # unpacking argument sequence - 'c, b, a' - >>> '{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' + Format("{0}, {1}, {2}") << 'a' << 'b' << 'c'; + // Result: "a, b, c" + Format("{}, {}, {}") << 'a' << 'b' << 'c'; + // Result: "a, b, c" + Format("{2}, {1}, {0}") << 'a' << 'b' << 'c'; + // Result: "c, b, a" + Format("{0}{1}{0}" << "abra" << "cad"; // arguments' indices can be repeated + // Result: "abracadabra" Aligning the text and specifying a width:: - >>> '{:<30}'.format('left aligned') - 'left aligned ' - >>> '{:>30}'.format('right aligned') - ' right aligned' - >>> '{:^30}'.format('centered') - ' centered ' - >>> '{:*^30}'.format('centered') # use '*' as a fill char - '***********centered***********' + Format("{:<30}") << "left aligned"; + // Result: "left aligned " + Format("{:>30}") << "right aligned" + // Result: " right aligned" + Format("{:^30}") << "centered" + // Result: " centered " + Format("{:*^30}") << "centered" // use '*' as a fill char + // Result: "***********centered***********" Replacing ``%+f``, ``%-f``, and ``% f`` and specifying a sign:: - >>> '{:+f}; {:+f}'.format(3.14, -3.14) # show it always - '+3.140000; -3.140000' - >>> '{: f}; {: f}'.format(3.14, -3.14) # show a space for positive numbers - ' 3.140000; -3.140000' - >>> '{:-f}; {:-f}'.format(3.14, -3.14) # show only the minus -- same as '{:f}; {:f}' - '3.140000; -3.140000' + Format("{:+f}; {:+f}") << 3.14 << -3.14; // show it always + // Result: "+3.140000; -3.140000" + Format("{: f}; {: f}") << 3.14 << -3.14; // show a space for positive numbers + // Result: " 3.140000; -3.140000" + Format("{:-f}; {:-f}") << 3.14 << -3.14; // show only the minus -- same as '{:f}; {:f}' + // Result: "3.140000; -3.140000" Replacing ``%x`` and ``%o`` and converting the value to different bases:: - >>> # format also supports binary numbers - >>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: {0:b}".format(42) - 'int: 42; hex: 2a; oct: 52; bin: 101010' - >>> # with 0x, 0o, or 0b as prefix: - >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: {0:#b}".format(42) - 'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010' + Format("int: {0:d}; hex: {0:x}; oct: {0:o}") << 42; + // Result: "int: 42; hex: 2a; oct: 52" + // with 0x or 0 as prefix: + Format("int: {0:d}; hex: {0:#x}; oct: {0:#o}") << 42; + // Result: "int: 42; hex: 0x2a; oct: 052" -Using the comma as a thousands separator:: +.. ifconfig:: False - >>> '{:,}'.format(1234567890) - '1,234,567,890' + Using the comma as a thousands separator:: -Expressing a percentage:: + Format("{:,}") << 1234567890) + '1,234,567,890' - >>> points = 19 - >>> total = 22 - >>> 'Correct answers: {:.2%}'.format(points/total) - 'Correct answers: 86.36%' + Expressing a percentage:: -Using type-specific formatting:: + >>> points = 19 + >>> total = 22 + Format("Correct answers: {:.2%}") << points/total) + 'Correct answers: 86.36%' - >>> import datetime - >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58) - >>> '{:%Y-%m-%d %H:%M:%S}'.format(d) - '2010-07-04 12:15:58' + Using type-specific formatting:: -Nesting arguments and more complex examples:: + >>> import datetime + >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58) + Format("{:%Y-%m-%d %H:%M:%S}") << d) + '2010-07-04 12:15:58' - >>> for align, text in zip('<^>', ['left', 'center', 'right']): - ... '{0:{fill}{align}16}'.format(text, fill=align, align=align) - ... - 'left<<<<<<<<<<<<' - '^^^^^center^^^^^' - '>>>>>>>>>>>right' - >>> - >>> octets = [192, 168, 0, 1] - >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets) - 'C0A80001' - >>> int(_, 16) - 3232235521 - >>> - >>> width = 5 - >>> for num in range(5,12): - ... for base in 'dXob': - ... print('{0:{width}{base}}'.format(num, base=base, width=width), end=' ') - ... print() - ... - 5 5 5 101 - 6 6 6 110 - 7 7 7 111 - 8 8 10 1000 - 9 9 11 1001 - 10 A 12 1010 - 11 B 13 1011 + Nesting arguments and more complex examples:: + + >>> for align, text in zip('<^>', ['left', 'center', 'right']): + ... '{0:{fill}{align}16}") << text, fill=align, align=align) + ... + 'left<<<<<<<<<<<<' + '^^^^^center^^^^^' + '>>>>>>>>>>>right' + >>> + >>> octets = [192, 168, 0, 1] + Format("{:02X}{:02X}{:02X}{:02X}") << *octets) + 'C0A80001' + >>> int(_, 16) + 3232235521 + >>> + >>> width = 5 + >>> for num in range(5,12): + ... for base in 'dXob': + ... print('{0:{width}{base}}") << num, base=base, width=width), end=' ') + ... print() + ... + 5 5 5 101 + 6 6 6 110 + 7 7 7 111 + 8 8 10 1000 + 9 9 11 1001 + 10 A 12 1010 + 11 B 13 1011