Skip to content

F
fmt
Commit bee2b6a5 authored by Victor Zverovich's avatar Victor Zverovich
Browse files
Options

Update doc.

parent 77a5ffa9
Hide whitespace changes
Inline Side-by-side
Showing with 110 additions and 117 deletions
doc/string.rst
View file @ bee2b6a5
......@@ -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:
+---------+----------------------------------------------------------+
| Type | Meaning |
+=========+==========================================================+
| ``'p'`` | Pointer format. This is the default type for |
| | pointers and may be omitted. |
+---------+----------------------------------------------------------+
| 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. |
| 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'
Using the comma as a thousands separator::
>>> '{:,}'.format(1234567890)
'1,234,567,890'
Expressing a percentage::
>>> points = 19
>>> total = 22
>>> 'Correct answers: {:.2%}'.format(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)
'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)
...
'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
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"
.. ifconfig:: False
Using the comma as a thousands separator::
Format("{:,}") << 1234567890)
'1,234,567,890'
Expressing a percentage::
>>> points = 19
>>> total = 22
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)
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}") << 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
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment