mirror of
https://github.com/fmtlib/fmt.git
synced 2024-11-10 05:10:05 +00:00
Update doc.
This commit is contained in:
Victor Zverovich
parent
77a5ffa9df
commit
bee2b6a5ac
211
doc/string.rst
211
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
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user