mirror of
https://github.com/fmtlib/fmt.git
synced 2025-01-27 15:35:18 +00:00
Update docs.
This commit is contained in:
parent
d7db2657a0
commit
2e6d79a523
@ -169,27 +169,23 @@ Format Specification Mini-Language
|
|||||||
|
|
||||||
"Format specifications" are used within replacement fields contained within a
|
"Format specifications" are used within replacement fields contained within a
|
||||||
format string to define how individual values are presented (see
|
format string to define how individual values are presented (see
|
||||||
:ref:`formatstrings`). They can also be passed directly to the built-in
|
:ref:`formatstrings`). They can also be passed directly to the
|
||||||
:func:`format` function. Each formattable type may define how the format
|
:func:`Format` function. Each formattable type may define how the format
|
||||||
specification is to be interpreted.
|
specification is to be interpreted.
|
||||||
|
|
||||||
Most built-in types implement the following options for format specifications,
|
Most built-in types implement the following options for format specifications,
|
||||||
although some of the formatting options are only supported by the numeric types.
|
although some of the formatting options are only supported by the numeric types.
|
||||||
|
|
||||||
A general convention is that an empty format string (``""``) produces
|
|
||||||
the same result as if you had called :func:`str` on the value. A
|
|
||||||
non-empty format string typically modifies the result.
|
|
||||||
|
|
||||||
The general form of a *standard format specifier* is:
|
The general form of a *standard format specifier* is:
|
||||||
|
|
||||||
.. productionlist:: sf
|
.. productionlist:: sf
|
||||||
format_spec: [[`fill`]`align`][`sign`][#][0][`width`][,][.`precision`][`type`]
|
format_spec: [[`fill`]`align`][`sign`]["#"]["0"][`width`]["." `precision`][`type`]
|
||||||
fill: <a character other than '{' or '}'>
|
fill: <a character other than '{' or '}'>
|
||||||
align: "<" | ">" | "=" | "^"
|
align: "<" | ">" | "=" | "^"
|
||||||
sign: "+" | "-" | " "
|
sign: "+" | "-" | " "
|
||||||
width: `integer`
|
width: `integer`
|
||||||
precision: `integer`
|
precision: `integer`
|
||||||
type: "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "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
|
||||||
of a fill character is signaled by the character following it, which must be
|
of a fill character is signaled by the character following it, which must be
|
||||||
@ -240,22 +236,21 @@ following:
|
|||||||
|
|
||||||
The ``'#'`` option causes the "alternate form" to be used for the
|
The ``'#'`` option causes the "alternate form" to be used for the
|
||||||
conversion. The alternate form is defined differently for different
|
conversion. The alternate form is defined differently for different
|
||||||
types. This option is only valid for integer, float, complex and
|
types. This option is only valid for integer and floating-point types.
|
||||||
Decimal types. For integers, when binary, octal, or hexadecimal output
|
For integers, when octal, or hexadecimal output
|
||||||
is used, this option adds the prefix respective ``'0b'``, ``'0o'``, or
|
is used, this option adds the prefix respective ``'0'``, or
|
||||||
``'0x'`` to the output value. For floats, complex and Decimal the
|
``'0x'`` to the output value. For floating-point numbers the
|
||||||
alternate form causes the result of the conversion to always contain a
|
alternate form causes the result of the conversion to always contain a
|
||||||
decimal-point character, even if no digits follow it. Normally, a
|
decimal-point character, even if no digits follow it. Normally, a
|
||||||
decimal-point character appears in the result of these conversions
|
decimal-point character appears in the result of these conversions
|
||||||
only if a digit follows it. In addition, for ``'g'`` and ``'G'``
|
only if a digit follows it. In addition, for ``'g'`` and ``'G'``
|
||||||
conversions, trailing zeros are not removed from the result.
|
conversions, trailing zeros are not removed from the result.
|
||||||
|
|
||||||
The ``','`` option signals the use of a comma for a thousands separator.
|
.. ifconfig:: False
|
||||||
For a locale aware separator, use the ``'n'`` integer presentation type
|
|
||||||
instead.
|
|
||||||
|
|
||||||
.. versionchanged:: 3.1
|
The ``','`` option signals the use of a comma for a thousands separator.
|
||||||
Added the ``','`` option (see also :pep:`378`).
|
For a locale aware separator, use the ``'n'`` integer presentation type
|
||||||
|
instead.
|
||||||
|
|
||||||
*width* is a decimal integer defining the minimum field width. If not
|
*width* is a decimal integer defining the minimum field width. If not
|
||||||
specified, then the field width will be determined by the content.
|
specified, then the field width will be determined by the content.
|
||||||
@ -281,7 +276,18 @@ The available string presentation types are:
|
|||||||
| ``'s'`` | String format. This is the default type for strings and |
|
| ``'s'`` | String format. This is the default type for strings and |
|
||||||
| | may be omitted. |
|
| | may be omitted. |
|
||||||
+---------+----------------------------------------------------------+
|
+---------+----------------------------------------------------------+
|
||||||
| None | The same as ``'s'``. |
|
| none | The same as ``'s'``. |
|
||||||
|
+---------+----------------------------------------------------------+
|
||||||
|
|
||||||
|
The available character presentation types are:
|
||||||
|
|
||||||
|
+---------+----------------------------------------------------------+
|
||||||
|
| Type | Meaning |
|
||||||
|
+=========+==========================================================+
|
||||||
|
| ``'c'`` | Character format. This is the default type for |
|
||||||
|
| | characters and may be omitted. |
|
||||||
|
+---------+----------------------------------------------------------+
|
||||||
|
| none | The same as ``'c'``. |
|
||||||
+---------+----------------------------------------------------------+
|
+---------+----------------------------------------------------------+
|
||||||
|
|
||||||
The available integer presentation types are:
|
The available integer presentation types are:
|
||||||
@ -289,11 +295,6 @@ The available integer presentation types are:
|
|||||||
+---------+----------------------------------------------------------+
|
+---------+----------------------------------------------------------+
|
||||||
| Type | Meaning |
|
| Type | Meaning |
|
||||||
+=========+==========================================================+
|
+=========+==========================================================+
|
||||||
| ``'b'`` | Binary format. Outputs the number in base 2. |
|
|
||||||
+---------+----------------------------------------------------------+
|
|
||||||
| ``'c'`` | Character. Converts the integer to the corresponding |
|
|
||||||
| | unicode character before printing. |
|
|
||||||
+---------+----------------------------------------------------------+
|
|
||||||
| ``'d'`` | Decimal Integer. Outputs the number in base 10. |
|
| ``'d'`` | Decimal Integer. Outputs the number in base 10. |
|
||||||
+---------+----------------------------------------------------------+
|
+---------+----------------------------------------------------------+
|
||||||
| ``'o'`` | Octal format. Outputs the number in base 8. |
|
| ``'o'`` | Octal format. Outputs the number in base 8. |
|
||||||
@ -304,16 +305,12 @@ The available integer presentation types are:
|
|||||||
| ``'X'`` | Hex format. Outputs the number in base 16, using upper- |
|
| ``'X'`` | Hex format. Outputs the number in base 16, using upper- |
|
||||||
| | case letters for the digits above 9. |
|
| | case letters for the digits above 9. |
|
||||||
+---------+----------------------------------------------------------+
|
+---------+----------------------------------------------------------+
|
||||||
| ``'n'`` | Number. This is the same as ``'d'``, except that it uses |
|
| none | The same as ``'d'``. |
|
||||||
| | the current locale setting to insert the appropriate |
|
|
||||||
| | number separator characters. |
|
|
||||||
+---------+----------------------------------------------------------+
|
|
||||||
| None | The same as ``'d'``. |
|
|
||||||
+---------+----------------------------------------------------------+
|
+---------+----------------------------------------------------------+
|
||||||
|
|
||||||
In addition to the above presentation types, integers can be formatted
|
In addition to the above presentation types, integers can be formatted
|
||||||
with the floating point presentation types listed below (except
|
with the floating point presentation types listed below (except
|
||||||
``'n'`` and None). When doing so, :func:`float` is used to convert the
|
``'n'`` and none). When doing so, :func:`float` is used to convert the
|
||||||
integer to a floating point number before formatting.
|
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 and decimal values are:
|
||||||
@ -361,14 +358,7 @@ The available presentation types for floating point and decimal values are:
|
|||||||
| | ``'E'`` if the number gets too large. The |
|
| | ``'E'`` if the number gets too large. The |
|
||||||
| | representations of infinity and NaN are uppercased, too. |
|
| | representations of infinity and NaN are uppercased, too. |
|
||||||
+---------+----------------------------------------------------------+
|
+---------+----------------------------------------------------------+
|
||||||
| ``'n'`` | Number. This is the same as ``'g'``, except that it uses |
|
| none | Similar to ``'g'``, except with at least one digit past |
|
||||||
| | the current locale setting to insert the appropriate |
|
|
||||||
| | number separator characters. |
|
|
||||||
+---------+----------------------------------------------------------+
|
|
||||||
| ``'%'`` | Percentage. Multiplies the number by 100 and displays |
|
|
||||||
| | in fixed (``'f'``) format, followed by a percent sign. |
|
|
||||||
+---------+----------------------------------------------------------+
|
|
||||||
| None | Similar to ``'g'``, except with at least one digit past |
|
|
||||||
| | the decimal point and a default precision of 12. This is |
|
| | the decimal point and a default precision of 12. This is |
|
||||||
| | intended to match :func:`str`, except you can add the |
|
| | intended to match :func:`str`, except you can add the |
|
||||||
| | other format modifiers. |
|
| | other format modifiers. |
|
||||||
@ -411,32 +401,12 @@ Accessing arguments by name::
|
|||||||
>>> 'Coordinates: {latitude}, {longitude}'.format(**coord)
|
>>> 'Coordinates: {latitude}, {longitude}'.format(**coord)
|
||||||
'Coordinates: 37.24N, -115.81W'
|
'Coordinates: 37.24N, -115.81W'
|
||||||
|
|
||||||
Accessing arguments' attributes::
|
|
||||||
|
|
||||||
>>> c = 3-5j
|
|
||||||
>>> ('The complex number {0} is formed from the real part {0.real} '
|
|
||||||
... 'and the imaginary part {0.imag}.').format(c)
|
|
||||||
'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.'
|
|
||||||
>>> class Point:
|
|
||||||
... def __init__(self, x, y):
|
|
||||||
... self.x, self.y = x, y
|
|
||||||
... def __str__(self):
|
|
||||||
... return 'Point({self.x}, {self.y})'.format(self=self)
|
|
||||||
...
|
|
||||||
>>> str(Point(4, 2))
|
|
||||||
'Point(4, 2)'
|
|
||||||
|
|
||||||
Accessing arguments' items::
|
Accessing arguments' items::
|
||||||
|
|
||||||
>>> coord = (3, 5)
|
>>> coord = (3, 5)
|
||||||
>>> 'X: {0[0]}; Y: {0[1]}'.format(coord)
|
>>> 'X: {0[0]}; Y: {0[1]}'.format(coord)
|
||||||
'X: 3; Y: 5'
|
'X: 3; Y: 5'
|
||||||
|
|
||||||
Replacing ``%s`` and ``%r``::
|
|
||||||
|
|
||||||
>>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2')
|
|
||||||
"repr() shows quotes: 'test1'; str() doesn't: test2"
|
|
||||||
|
|
||||||
Aligning the text and specifying a width::
|
Aligning the text and specifying a width::
|
||||||
|
|
||||||
>>> '{:<30}'.format('left aligned')
|
>>> '{:<30}'.format('left aligned')
|
||||||
|
Loading…
x
Reference in New Issue
Block a user