Skip to content

Commit 0673d4c

Browse files
miss-islingtonerlend-aaslandAA-Turner
authored
[3.11] Docs: format sys.float_info properly (GH-108107) (#108131)
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 ca0c6c1) Co-authored-by: Erlend E. Aasland <[email protected]> Co-authored-by: Adam Turner <[email protected]>
1 parent 441797d commit 0673d4c

File tree

1 file changed

+73
-52
lines changed

1 file changed

+73
-52
lines changed

‎Doc/library/sys.rst

Lines changed: 73 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -570,61 +570,82 @@ always available.
570570
programming language; see section 5.2.4.2.2 of the 1999 ISO/IEC C standard
571571
[C99]_, 'Characteristics of floating types', for details.
572572

573-
.. tabularcolumns:: |l|l|L|
574-
575-
+---------------------+---------------------+--------------------------------------------------+
576-
| attribute | float.h macro | explanation |
577-
+=====================+=====================+==================================================+
578-
| ``epsilon`` | ``DBL_EPSILON`` | difference between 1.0 and the least value |
579-
| | | greater than 1.0 that is representable as a float|
580-
| | | |
581-
| | | See also :func:`math.ulp`. |
582-
+---------------------+---------------------+--------------------------------------------------+
583-
| ``dig`` | ``DBL_DIG`` | maximum number of decimal digits that can be |
584-
| | | faithfully represented in a float; see below |
585-
+---------------------+---------------------+--------------------------------------------------+
586-
| ``mant_dig`` | ``DBL_MANT_DIG`` | float precision: the number of base-``radix`` |
587-
| | | digits in the significand of a float |
588-
+---------------------+---------------------+--------------------------------------------------+
589-
| ``max`` | ``DBL_MAX`` | maximum representable positive finite float |
590-
+---------------------+---------------------+--------------------------------------------------+
591-
| ``max_exp`` | ``DBL_MAX_EXP`` | maximum integer *e* such that ``radix**(e-1)`` is|
592-
| | | a representable finite float |
593-
+---------------------+---------------------+--------------------------------------------------+
594-
| ``max_10_exp`` | ``DBL_MAX_10_EXP`` | maximum integer *e* such that ``10**e`` is in the|
595-
| | | range of representable finite floats |
596-
+---------------------+---------------------+--------------------------------------------------+
597-
| ``min`` | ``DBL_MIN`` | minimum representable positive *normalized* float|
598-
| | | |
599-
| | | Use :func:`math.ulp(0.0) <math.ulp>` to get the |
600-
| | | smallest positive *denormalized* representable |
601-
| | | float. |
602-
+---------------------+---------------------+--------------------------------------------------+
603-
| ``min_exp`` | ``DBL_MIN_EXP`` | minimum integer *e* such that ``radix**(e-1)`` is|
604-
| | | a normalized float |
605-
+---------------------+---------------------+--------------------------------------------------+
606-
| ``min_10_exp`` | ``DBL_MIN_10_EXP`` | minimum integer *e* such that ``10**e`` is a |
607-
| | | normalized float |
608-
+---------------------+---------------------+--------------------------------------------------+
609-
| ``radix`` | ``FLT_RADIX`` | radix of exponent representation |
610-
+---------------------+---------------------+--------------------------------------------------+
611-
| ``rounds`` | ``FLT_ROUNDS`` | integer representing the rounding mode for |
612-
| | | floating-point arithmetic. This reflects the |
613-
| | | value of the system ``FLT_ROUNDS`` macro at |
614-
| | | interpreter startup time: |
615-
| | | ``-1`` indeterminable, |
616-
| | | ``0`` toward zero, |
617-
| | | ``1`` to nearest, |
618-
| | | ``2`` toward positive infinity, |
619-
| | | ``3`` toward negative infinity |
620-
| | | |
621-
| | | All other values for ``FLT_ROUNDS`` characterize |
622-
| | | implementation-defined rounding behavior. |
623-
+---------------------+---------------------+--------------------------------------------------+
573+
.. list-table:: Attributes of the :data:`!float_info` :term:`named tuple`
574+
:header-rows: 1
575+
576+
* - attribute
577+
- float.h macro
578+
- explanation
579+
580+
* - .. attribute:: float_info.epsilon
581+
- :c:macro:`!DBL_EPSILON`
582+
- difference between 1.0 and the least value greater than 1.0 that is
583+
representable as a float.
584+
585+
See also :func:`math.ulp`.
586+
587+
* - .. attribute:: float_info.dig
588+
- :c:macro:`!DBL_DIG`
589+
- The maximum number of decimal digits that can be faithfully
590+
represented in a float; see below.
591+
592+
* - .. attribute:: float_info.mant_dig
593+
- :c:macro:`!DBL_MANT_DIG`
594+
- Float precision: the number of base-``radix`` digits in the
595+
significand of a float.
596+
597+
* - .. attribute:: float_info.max
598+
- :c:macro:`!DBL_MAX`
599+
- The maximum representable positive finite float.
600+
601+
* - .. attribute:: float_info.max_exp
602+
- :c:macro:`!DBL_MAX_EXP`
603+
- The maximum integer *e* such that ``radix**(e-1)`` is a representable
604+
finite float.
605+
606+
* - .. attribute:: float_info.max_10_exp
607+
- :c:macro:`!DBL_MAX_10_EXP`
608+
- The maximum integer *e* such that ``10**e`` is in the range of
609+
representable finite floats.
610+
611+
* - .. attribute:: float_info.min
612+
- :c:macro:`!DBL_MIN`
613+
- The minimum representable positive *normalized* float.
614+
615+
Use :func:`math.ulp(0.0) <math.ulp>` to get the smallest positive
616+
*denormalized* representable float.
617+
618+
* - .. attribute:: float_info.min_exp
619+
- :c:macro:`!DBL_MIN_EXP`
620+
- The minimum integer *e* such that ``radix**(e-1)`` is a normalized
621+
float.
622+
623+
* - .. attribute:: float_info.min_10_exp
624+
- :c:macro:`!DBL_MIN_10_EXP`
625+
- The minimum integer *e* such that ``10**e`` is a normalized float.
626+
627+
* - .. attribute:: float_info.radix
628+
- :c:macro:`!FLT_RADIX`
629+
- The radix of exponent representation.
630+
631+
* - .. attribute:: float_info.rounds
632+
- :c:macro:`!FLT_ROUNDS`
633+
- An integer representing the rounding mode for floating-point arithmetic.
634+
This reflects the value of the system :c:macro:`!FLT_ROUNDS` macro
635+
at interpreter startup time:
636+
637+
* ``-1``: indeterminable
638+
* ``0``: toward zero
639+
* ``1``: to nearest
640+
* ``2``: toward positive infinity
641+
* ``3``: toward negative infinity
642+
643+
All other values for :c:macro:`!FLT_ROUNDS` characterize
644+
implementation-defined rounding behavior.
624645

625646
The attribute :attr:`sys.float_info.dig` needs further explanation. If
626647
``s`` is any string representing a decimal number with at most
627-
:attr:`sys.float_info.dig` significant digits, then converting ``s`` to a
648+
:attr:`!sys.float_info.dig` significant digits, then converting ``s`` to a
628649
float and back again will recover a string representing the same decimal
629650
value::
630651

0 commit comments

Comments
 (0)