External/fmt
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update doc.

Browse Source
This commit is contained in:
Victor Zverovich 2012-12-19 09:05:07 -08:00
parent 77a5ffa9df
commit bee2b6a5ac
1 changed files with 102 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

211
doc/string.rst
View File

@ -184,7 +184,7 @@ The general form of a *standard format specifier* is:
align: "<" | ">" | "=" | "^" align: "<" | ">" | "=" | "^"
sign: "+" | "-" | " " sign: "+" | "-" | " "
width: `integer` width: `integer`
precision: `integer` precision: `integer` | "{" `arg_index` "}"
type: "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "o" | "p" | s" | "x" | "X" 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 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. | | ``'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'``. | | 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 | | 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 | | | then formats the result in either fixed-point format |
| | or in scientific notation, depending on its magnitude. | | | 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 | | | The precise rules are as follows: suppose that the |
| | result formatted with presentation type ``'e'`` and | | | result formatted with presentation type ``'e'`` and |
| | precision ``p-1`` would have exponent ``exp``. Then | | | 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 | | | ``0``, ``-0`` and ``nan`` respectively, regardless of |
| | the precision. | | | 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,117 +378,102 @@ The available presentation types for floating point and decimal values are:
Format examples 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 ``%``. 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 The new format syntax also supports new and different options, shown in the
follow examples. following examples.
Accessing arguments by position:: 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:: 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:: 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:: 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'
Using the comma as a thousands separator:: .. ifconfig:: False
>>> '{:,}'.format(1234567890) Using the comma as a thousands separator::
'1,234,567,890'
Expressing a percentage:: Format("{:,}") << 1234567890)
'1,234,567,890'
>>> points = 19 Expressing a percentage::
>>> total = 22
>>> 'Correct answers: {:.2%}'.format(points/total)
'Correct answers: 86.36%'
Using type-specific formatting:: >>> points = 19
>>> total = 22
Format("Correct answers: {:.2%}") << points/total)
'Correct answers: 86.36%'
>>> import datetime Using type-specific formatting::
>>> 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:: >>> 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']): Nesting arguments and more complex examples::
... '{0:{fill}{align}16}'.format(text, fill=align, align=align)
... >>> for align, text in zip('<^>', ['left', 'center', 'right']):
'left<<<<<<<<<<<<' ... '{0:{fill}{align}16}") << text, fill=align, align=align)
'^^^^^center^^^^^' ...
'>>>>>>>>>>>right' 'left<<<<<<<<<<<<'
>>> '^^^^^center^^^^^'
>>> octets = [192, 168, 0, 1] '>>>>>>>>>>>right'
>>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets) >>>
'C0A80001' >>> octets = [192, 168, 0, 1]
>>> int(_, 16) Format("{:02X}{:02X}{:02X}{:02X}") << *octets)
3232235521 'C0A80001'
>>> >>> int(_, 16)
>>> width = 5 3232235521
>>> for num in range(5,12): >>>
... for base in 'dXob': >>> width = 5
... print('{0:{width}{base}}'.format(num, base=base, width=width), end=' ') >>> for num in range(5,12):
... print() ... for base in 'dXob':
... ... print('{0:{width}{base}}") << num, base=base, width=width), end=' ')
5 5 5 101 ... print()
6 6 6 110 ...
7 7 7 111 5 5 5 101
8 8 10 1000 6 6 6 110
9 9 11 1001 7 7 7 111
10 A 12 1010 8 8 10 1000
11 B 13 1011 9 9 11 1001
10 A 12 1010
11 B 13 1011