mirror of
https://github.com/python/cpython.git
synced 2025-08-31 05:58:33 +00:00
gh-131912: Improve description of grouping options in the format specification docs (#132030)
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
This commit is contained in:
Prometheus3375
GitHub
parent
ac14d4a23f
commit
06a110f522
1 changed files with 50 additions and 37 deletions
|
|
@ -325,11 +325,11 @@ The general form of a *standard format specifier* is:
|
|||
align: "<" | ">" | "=" | "^"
|
||||
sign: "+" | "-" | " "
|
||||
width_and_precision: [`width_with_grouping`][`precision_with_grouping`]
|
||||
width_with_grouping: [`width`][`grouping_option`]
|
||||
precision_with_grouping: "." [`precision`]`grouping_option`
|
||||
width_with_grouping: [`width`][`grouping`]
|
||||
precision_with_grouping: "." [`precision`][`grouping`]
|
||||
width: `~python-grammar:digit`+
|
||||
grouping_option: "_" | ","
|
||||
precision: `~python-grammar:digit`+
|
||||
grouping: "," | "_"
|
||||
type: "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g"
|
||||
: | "G" | "n" | "o" | "s" | "x" | "X" | "%"
|
||||
|
||||
|
|
@ -385,13 +385,13 @@ following:
|
|||
+---------+----------------------------------------------------------+
|
||||
| Option | Meaning |
|
||||
+=========+==========================================================+
|
||||
| ``'+'`` | indicates that a sign should be used for both |
|
||||
| ``'+'`` | Indicates that a sign should be used for both |
|
||||
| | positive as well as negative numbers. |
|
||||
+---------+----------------------------------------------------------+
|
||||
| ``'-'`` | indicates that a sign should be used only for negative |
|
||||
| ``'-'`` | Indicates that a sign should be used only for negative |
|
||||
| | numbers (this is the default behavior). |
|
||||
+---------+----------------------------------------------------------+
|
||||
| space | indicates that a leading space should be used on |
|
||||
| space | Indicates that a leading space should be used on |
|
||||
| | positive numbers, and a minus sign on negative numbers. |
|
||||
+---------+----------------------------------------------------------+
|
||||
|
||||
|
|
@ -419,30 +419,7 @@ decimal-point character appears in the result of these conversions
|
|||
only if a digit follows it. In addition, for ``'g'`` and ``'G'``
|
||||
conversions, trailing zeros are not removed from the result.
|
||||
|
||||
.. index:: single: , (comma); in string formatting
|
||||
|
||||
The ``','`` option signals the use of a comma for a thousands separator for
|
||||
floating-point presentation types and for integer presentation type ``'d'``.
|
||||
For other presentation types, this option is an error.
|
||||
For a locale aware separator, use the ``'n'`` integer presentation type
|
||||
instead.
|
||||
|
||||
.. versionchanged:: 3.1
|
||||
Added the ``','`` option (see also :pep:`378`).
|
||||
|
||||
.. index:: single: _ (underscore); in string formatting
|
||||
|
||||
The ``'_'`` option signals the use of an underscore for a thousands
|
||||
separator for floating-point presentation types and for integer
|
||||
presentation type ``'d'``. For integer presentation types ``'b'``,
|
||||
``'o'``, ``'x'``, and ``'X'``, underscores will be inserted every 4
|
||||
digits. For other presentation types, specifying this option is an
|
||||
error.
|
||||
|
||||
.. versionchanged:: 3.6
|
||||
Added the ``'_'`` option (see also :pep:`515`).
|
||||
|
||||
*width* is a decimal integer defining the minimum total field width,
|
||||
The *width* is a decimal integer defining the minimum total field width,
|
||||
including any prefixes, separators, and other formatting characters.
|
||||
If not specified, then the field width will be determined by the content.
|
||||
|
||||
|
|
@ -463,12 +440,43 @@ indicates the maximum field size - in other words, how many characters will be
|
|||
used from the field content. The *precision* is not allowed for integer
|
||||
presentation types.
|
||||
|
||||
The ``'_'`` or ``','`` option after *precision* means the use of an underscore
|
||||
or a comma for a thousands separator of the fractional part for floating-point
|
||||
presentation types.
|
||||
The *grouping* option after *width* and *precision* fields specifies
|
||||
a digit group separator for the integral and fractional parts
|
||||
of a number respectively. It can be one of the following:
|
||||
|
||||
.. index::
|
||||
single: , (comma); in string formatting
|
||||
single: _ (underscore); in string formatting
|
||||
|
||||
+---------+----------------------------------------------------------+
|
||||
| Option | Meaning |
|
||||
+=========+==========================================================+
|
||||
| ``','`` | Inserts a comma every 3 digits for |
|
||||
| | integer presentation type ``'d'`` and |
|
||||
| | floating-point presentation types, excluding ``'n'``. |
|
||||
| | For other presentation types, |
|
||||
| | this option is not supported. |
|
||||
+---------+----------------------------------------------------------+
|
||||
| ``'_'`` | Inserts an underscore every 3 digits for |
|
||||
| | integer presentation type ``'d'`` and |
|
||||
| | floating-point presentation types, excluding ``'n'``. |
|
||||
| | For integer presentation types |
|
||||
| | ``'b'``, ``'o'``, ``'x'``, and ``'X'``, |
|
||||
| | underscores are inserted every 4 digits. |
|
||||
| | For other presentation types, |
|
||||
| | this option is not supported. |
|
||||
+---------+----------------------------------------------------------+
|
||||
|
||||
For a locale aware separator, use the ``'n'`` presentation type instead.
|
||||
|
||||
.. versionchanged:: 3.1
|
||||
Added the ``','`` option (see also :pep:`378`).
|
||||
|
||||
.. versionchanged:: 3.6
|
||||
Added the ``'_'`` option (see also :pep:`515`).
|
||||
|
||||
.. versionchanged:: 3.14
|
||||
Support thousands separators for the fractional part.
|
||||
Support the *grouping* option for the fractional part.
|
||||
|
||||
Finally, the *type* determines how the data should be presented.
|
||||
|
||||
|
|
@ -507,7 +515,7 @@ The available integer presentation types are:
|
|||
+---------+----------------------------------------------------------+
|
||||
| ``'n'`` | Number. This is the same as ``'d'``, except that it uses |
|
||||
| | the current locale setting to insert the appropriate |
|
||||
| | number separator characters. |
|
||||
| | digit group separators. |
|
||||
+---------+----------------------------------------------------------+
|
||||
| None | The same as ``'d'``. |
|
||||
+---------+----------------------------------------------------------+
|
||||
|
|
@ -589,7 +597,8 @@ The available presentation types for :class:`float` and
|
|||
+---------+----------------------------------------------------------+
|
||||
| ``'n'`` | Number. This is the same as ``'g'``, except that it uses |
|
||||
| | the current locale setting to insert the appropriate |
|
||||
| | number separator characters. |
|
||||
| | digit group separators |
|
||||
| | for the integral part of a number. |
|
||||
+---------+----------------------------------------------------------+
|
||||
| ``'%'`` | Percentage. Multiplies the number by 100 and displays |
|
||||
| | in fixed (``'f'``) format, followed by a percent sign. |
|
||||
|
|
@ -716,12 +725,16 @@ Replacing ``%x`` and ``%o`` and converting the value to different bases::
|
|||
>>> "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 or the underscore as a thousands separator::
|
||||
Using the comma or the underscore as a digit group separator::
|
||||
|
||||
>>> '{:,}'.format(1234567890)
|
||||
'1,234,567,890'
|
||||
>>> '{:_}'.format(1234567890)
|
||||
'1_234_567_890'
|
||||
>>> '{:_b}'.format(1234567890)
|
||||
'100_1001_1001_0110_0000_0010_1101_0010'
|
||||
>>> '{:_x}'.format(1234567890)
|
||||
'4996_02d2'
|
||||
>>> '{:_}'.format(123456789.123456789)
|
||||
'123_456_789.12345679'
|
||||
>>> '{:._}'.format(123456789.123456789)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue