Skip to content

Commit 2807430

Browse files
miss-islingtonerlend-aaslandAA-Turner
authored
[3.12] Docs: format sys.float_info properly (GH-108107) (#108130)
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 71e3581 commit 2807430

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
@@ -574,61 +574,82 @@ always available.
574574
programming language; see section 5.2.4.2.2 of the 1999 ISO/IEC C standard
575575
[C99]_, 'Characteristics of floating types', for details.
576576

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

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

0 commit comments

Comments
 (0)