mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-17 07:11:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

[3.12] Docs: format sys.float_info properly (GH-108107) (#108130)

Browse source 
Docs: format sys.float_info properly (GH-108107)

- Normalise capitalisation and punctuation
- Use attribute markup for named tuple attributes
- Use :c:macro: markup for C macros
- Use a list for the 'rounds' attribute values
- Use list-table, for better .rst readability
- Remove one unneeded sys.float_info.dig link

(cherry picked from commit ca0c6c1f1e)

Co-authored-by: Erlend E. Aasland <erlend@python.org>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
This commit is contained in:
Miss Islington (bot) 2023-08-19 16:00:31 -07:00 • committed by GitHub
parent 71e3581c96
commit 2807430657
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 72 additions and 51 deletions
Download patch file Download diff file Expand all files Collapse all files

123
Doc/library/sys.rst
View file

@ -574,61 +574,82 @@ always available.
programming language; see section 5.2.4.2.2 of the 1999 ISO/IEC C standard programming language; see section 5.2.4.2.2 of the 1999 ISO/IEC C standard
[C99]_, 'Characteristics of floating types', for details. [C99]_, 'Characteristics of floating types', for details.
.. tabularcolumns:: |l|l|L| .. list-table:: Attributes of the :data:`!float_info` :term:`named tuple`
:header-rows: 1
+---------------------+---------------------+--------------------------------------------------+ * - attribute
| attribute | float.h macro | explanation | - float.h macro
+=====================+=====================+==================================================+ - explanation
| ``epsilon`` | ``DBL_EPSILON`` | difference between 1.0 and the least value |
| | | greater than 1.0 that is representable as a float| * - .. attribute:: float_info.epsilon
| | | | - :c:macro:`!DBL_EPSILON`
| | | See also :func:`math.ulp`. | - difference between 1.0 and the least value greater than 1.0 that is
+---------------------+---------------------+--------------------------------------------------+ representable as a float.
| ``dig`` | ``DBL_DIG`` | maximum number of decimal digits that can be |
| | | faithfully represented in a float; see below | See also :func:`math.ulp`.
+---------------------+---------------------+--------------------------------------------------+
| ``mant_dig`` | ``DBL_MANT_DIG`` | float precision: the number of base-``radix`` | * - .. attribute:: float_info.dig
| | | digits in the significand of a float | - :c:macro:`!DBL_DIG`
+---------------------+---------------------+--------------------------------------------------+ - The maximum number of decimal digits that can be faithfully
| ``max`` | ``DBL_MAX`` | maximum representable positive finite float | represented in a float; see below.
+---------------------+---------------------+--------------------------------------------------+
| ``max_exp`` | ``DBL_MAX_EXP`` | maximum integer *e* such that ``radix**(e-1)`` is| * - .. attribute:: float_info.mant_dig
| | | a representable finite float | - :c:macro:`!DBL_MANT_DIG`
+---------------------+---------------------+--------------------------------------------------+ - Float precision: the number of base-``radix`` digits in the
| ``max_10_exp`` | ``DBL_MAX_10_EXP`` | maximum integer *e* such that ``10**e`` is in the| significand of a float.
| | | range of representable finite floats |
+---------------------+---------------------+--------------------------------------------------+ * - .. attribute:: float_info.max
| ``min`` | ``DBL_MIN`` | minimum representable positive *normalized* float| - :c:macro:`!DBL_MAX`
| | | | - The maximum representable positive finite float.
| | | Use :func:`math.ulp(0.0) <math.ulp>` to get the |
| | | smallest positive *denormalized* representable | * - .. attribute:: float_info.max_exp
| | | float. | - :c:macro:`!DBL_MAX_EXP`
+---------------------+---------------------+--------------------------------------------------+ - The maximum integer *e* such that ``radix**(e-1)`` is a representable
| ``min_exp`` | ``DBL_MIN_EXP`` | minimum integer *e* such that ``radix**(e-1)`` is| finite float.
| | | a normalized float |
+---------------------+---------------------+--------------------------------------------------+ * - .. attribute:: float_info.max_10_exp
| ``min_10_exp`` | ``DBL_MIN_10_EXP`` | minimum integer *e* such that ``10**e`` is a | - :c:macro:`!DBL_MAX_10_EXP`
| | | normalized float | - The maximum integer *e* such that ``10**e`` is in the range of
+---------------------+---------------------+--------------------------------------------------+ representable finite floats.
| ``radix`` | ``FLT_RADIX`` | radix of exponent representation |
+---------------------+---------------------+--------------------------------------------------+ * - .. attribute:: float_info.min
| ``rounds`` | ``FLT_ROUNDS`` | integer representing the rounding mode for | - :c:macro:`!DBL_MIN`
| | | floating-point arithmetic. This reflects the | - The minimum representable positive *normalized* float.
| | | value of the system ``FLT_ROUNDS`` macro at |
| | | interpreter startup time: | Use :func:`math.ulp(0.0) <math.ulp>` to get the smallest positive
| | | ``-1`` indeterminable, | *denormalized* representable float.
| | | ``0`` toward zero, |
| | | ``1`` to nearest, | * - .. attribute:: float_info.min_exp
| | | ``2`` toward positive infinity, | - :c:macro:`!DBL_MIN_EXP`
| | | ``3`` toward negative infinity | - The minimum integer *e* such that ``radix**(e-1)`` is a normalized
| | | | float.
| | | All other values for ``FLT_ROUNDS`` characterize |
| | | implementation-defined rounding behavior. | * - .. attribute:: float_info.min_10_exp
+---------------------+---------------------+--------------------------------------------------+ - :c:macro:`!DBL_MIN_10_EXP`
- The minimum integer *e* such that ``10**e`` is a normalized float.
* - .. attribute:: float_info.radix
- :c:macro:`!FLT_RADIX`
- The radix of exponent representation.
* - .. attribute:: float_info.rounds
- :c:macro:`!FLT_ROUNDS`
- An integer representing the rounding mode for floating-point arithmetic.
This reflects the value of the system :c:macro:`!FLT_ROUNDS` macro
at interpreter startup time:
* ``-1``: indeterminable
* ``0``: toward zero
* ``1``: to nearest
* ``2``: toward positive infinity
* ``3``: toward negative infinity
All other values for :c:macro:`!FLT_ROUNDS` characterize
implementation-defined rounding behavior.
The attribute :attr:`sys.float_info.dig` needs further explanation. If The attribute :attr:`sys.float_info.dig` needs further explanation. If
``s`` is any string representing a decimal number with at most ``s`` is any string representing a decimal number with at most
:attr:`sys.float_info.dig` significant digits, then converting ``s`` to a :attr:`!sys.float_info.dig` significant digits, then converting ``s`` to a
float and back again will recover a string representing the same decimal float and back again will recover a string representing the same decimal
value:: value::