From 6d5eff109fe5be07674b59f53acf706285e66f84 Mon Sep 17 00:00:00 2001 From: Mark Dickinson Date: Sat, 28 Nov 2020 10:54:31 +0000 Subject: [PATCH 1/5] Improve description of 'e', 'f' and 'g' presentation types --- Doc/library/string.rst | 33 ++++++++++++++++++++++++--------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 91f43e9353d915..5c8c978b6297de 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -476,20 +476,32 @@ 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 :class:`float` and +:class:`~decimal.Decimal` values are: +---------+----------------------------------------------------------+ | Type | Meaning | +=========+==========================================================+ - | ``'e'`` | Exponent notation. Prints the number in scientific | - | | notation using the letter 'e' to indicate the exponent. | - | | The default precision is ``6``. | + | ``'e'`` | Scientific "E" notation. For a given precision ``p >= | + | | 0``, formats the number in scientific notation with the | + | | letter 'e' separating the coefficient from the exponent. | + | | The coefficient has one digit before and ``p`` digits | + | | after the decimal point, for a total of ``p + 1`` | + | | significant digits. With no precision given, uses a | + | | precision of ``6`` digits after the decimal point for | + | | :class:`float`, and shows all coefficient digits | + | | for :class:`~decimal.Decimal`. | +---------+----------------------------------------------------------+ - | ``'E'`` | Exponent notation. Same as ``'e'`` except it uses an | - | | upper case 'E' as the separator character. | + | ``'E'`` | Scientific "E" notation. Same as ``'e'`` except it uses | + | | an upper case 'E' as the separator character. | +---------+----------------------------------------------------------+ - | ``'f'`` | Fixed-point notation. Displays the number as a | - | | fixed-point number. The default precision is ``6``. | + | ``'f'`` | Fixed-point notation. For a given precision ``p >= 0``, | + | | formats the number as a decimal number with exactly | + | | ``p`` digits following the decimal point. With no | + | | precision given, uses a precision of ``6`` digits after | + | | the decimal point for :class:`float`, and uses a | + | | precision large enough to show all coefficient digits | + | | for :class:`~decimal.Decimal`. | +---------+----------------------------------------------------------+ | ``'F'`` | Fixed-point notation. Same as ``'f'``, but converts | | | ``nan`` to ``NAN`` and ``inf`` to ``INF``. | @@ -518,7 +530,10 @@ The available presentation types for floating point and decimal values are: | | the precision. | | | | | | A precision of ``0`` is treated as equivalent to a | - | | precision of ``1``. The default precision is ``6``. | + | | precision of ``1``. With no precision given, uses a | + | | precision of ``6`` significant digits for | + | | :class:`float`, and shows all coefficient digits | + | | for :class:`~decimal.Decimal`. | +---------+----------------------------------------------------------+ | ``'G'`` | General format. Same as ``'g'`` except switches to | | | ``'E'`` if the number gets too large. The | From 37092477085884c4b6eb6315939f56ed065e7712 Mon Sep 17 00:00:00 2001 From: Mark Dickinson Date: Sat, 28 Nov 2020 14:23:31 +0000 Subject: [PATCH 2/5] Drop the 'E' from Scientific 'E' notation; remove >= 0 qualifications --- Doc/library/string.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 5c8c978b6297de..f73d68fed0223b 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -482,8 +482,8 @@ The available presentation types for :class:`float` and +---------+----------------------------------------------------------+ | Type | Meaning | +=========+==========================================================+ - | ``'e'`` | Scientific "E" notation. For a given precision ``p >= | - | | 0``, formats the number in scientific notation with the | + | ``'e'`` | Scientific notation. For a given precision ``p``, | + | | formats the number in scientific notation with the | | | letter 'e' separating the coefficient from the exponent. | | | The coefficient has one digit before and ``p`` digits | | | after the decimal point, for a total of ``p + 1`` | @@ -492,10 +492,10 @@ The available presentation types for :class:`float` and | | :class:`float`, and shows all coefficient digits | | | for :class:`~decimal.Decimal`. | +---------+----------------------------------------------------------+ - | ``'E'`` | Scientific "E" notation. Same as ``'e'`` except it uses | + | ``'E'`` | Scientific notation. Same as ``'e'`` except it uses | | | an upper case 'E' as the separator character. | +---------+----------------------------------------------------------+ - | ``'f'`` | Fixed-point notation. For a given precision ``p >= 0``, | + | ``'f'`` | Fixed-point notation. For a given precision ``p``, | | | formats the number as a decimal number with exactly | | | ``p`` digits following the decimal point. With no | | | precision given, uses a precision of ``6`` digits after | From 9e44b9636504774b983d9c6f2bb8274715a1b181 Mon Sep 17 00:00:00 2001 From: Mark Dickinson Date: Sat, 28 Nov 2020 14:34:40 +0000 Subject: [PATCH 3/5] Fix false statement that the alternate form is valid for Decimal --- Doc/library/string.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index f73d68fed0223b..a06f58dc1c5b11 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -384,10 +384,10 @@ following: The ``'#'`` option causes the "alternate form" to be used for the conversion. The alternate form is defined differently for different -types. This option is only valid for integer, float, complex and -Decimal types. For integers, when binary, octal, or hexadecimal output +types. This option is only valid for integer, float, and complex +types. For integers, when binary, octal, or hexadecimal output is used, this option adds the prefix respective ``'0b'``, ``'0o'``, or -``'0x'`` to the output value. For floats, complex and Decimal the +``'0x'`` to the output value. For float and complex the 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 appears in the result of these conversions From 06a9df7da1337846b63ee18b79e0786583e0d25b Mon Sep 17 00:00:00 2001 From: Mark Dickinson Date: Sat, 28 Nov 2020 14:38:42 +0000 Subject: [PATCH 4/5] Nitpick: remove the Harvard/Oxford comma --- Doc/library/string.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index a06f58dc1c5b11..1ae664b37c3d62 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -384,7 +384,7 @@ following: The ``'#'`` option causes the "alternate form" to be used for the conversion. The alternate form is defined differently for different -types. This option is only valid for integer, float, and complex +types. This option is only valid for integer, float and complex types. For integers, when binary, octal, or hexadecimal output is used, this option adds the prefix respective ``'0b'``, ``'0o'``, or ``'0x'`` to the output value. For float and complex the From 7666444eb1b01241dfb291ae11593e030d64b236 Mon Sep 17 00:00:00 2001 From: Mark Dickinson Date: Sat, 28 Nov 2020 14:48:03 +0000 Subject: [PATCH 5/5] Add note that the decimal point is also removed if no digits follow it, except in alternate form --- Doc/library/string.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 1ae664b37c3d62..5542e9b727a6b8 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -490,7 +490,9 @@ The available presentation types for :class:`float` and | | significant digits. With no precision given, uses a | | | precision of ``6`` digits after the decimal point for | | | :class:`float`, and shows all coefficient digits | - | | for :class:`~decimal.Decimal`. | + | | for :class:`~decimal.Decimal`. If no digits follow the | + | | decimal point, the decimal point is also removed unless | + | | the ``#`` option is used. | +---------+----------------------------------------------------------+ | ``'E'`` | Scientific notation. Same as ``'e'`` except it uses | | | an upper case 'E' as the separator character. | @@ -501,7 +503,9 @@ The available presentation types for :class:`float` and | | precision given, uses a precision of ``6`` digits after | | | the decimal point for :class:`float`, and uses a | | | precision large enough to show all coefficient digits | - | | for :class:`~decimal.Decimal`. | + | | for :class:`~decimal.Decimal`. If no digits follow the | + | | decimal point, the decimal point is also removed unless | + | | the ``#`` option is used. | +---------+----------------------------------------------------------+ | ``'F'`` | Fixed-point notation. Same as ``'f'``, but converts | | | ``nan`` to ``NAN`` and ``inf`` to ``INF``. |