Skip to content

Commit e2fe21f

Browse files
mdickinsonmdickinson
committed
Clarify sys.float_info documentation.
1 parent 00ee9c0 commit e2fe21f

File tree

1 file changed

+62
-35
lines changed

1 file changed

+62
-35
lines changed

‎Doc/library/sys.rst

Lines changed: 62 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -296,43 +296,65 @@ always available.
296296
.. data:: float_info
297297

298298
A structseq holding information about the float type. It contains low level
299-
information about the precision and internal representation. Please study
300-
your system's :file:`float.h` for more information.
301-
302-
+---------------------+--------------------------------------------------+
303-
| attribute | explanation |
304-
+=====================+==================================================+
305-
| :const:`epsilon` | Difference between 1 and the next representable |
306-
| | floating point number |
307-
+---------------------+--------------------------------------------------+
308-
| :const:`dig` | digits (see :file:`float.h`) |
309-
+---------------------+--------------------------------------------------+
310-
| :const:`mant_dig` | mantissa digits (see :file:`float.h`) |
311-
+---------------------+--------------------------------------------------+
312-
| :const:`max` | maximum representable finite float |
313-
+---------------------+--------------------------------------------------+
314-
| :const:`max_exp` | maximum int e such that radix**(e-1) is in the |
315-
| | range of finite representable floats |
316-
+---------------------+--------------------------------------------------+
317-
| :const:`max_10_exp` | maximum int e such that 10**e is in the |
318-
| | range of finite representable floats |
319-
+---------------------+--------------------------------------------------+
320-
| :const:`min` | Minimum positive normalizer float |
321-
+---------------------+--------------------------------------------------+
322-
| :const:`min_exp` | minimum int e such that radix**(e-1) is a |
323-
| | normalized float |
324-
+---------------------+--------------------------------------------------+
325-
| :const:`min_10_exp` | minimum int e such that 10**e is a normalized |
326-
| | float |
327-
+---------------------+--------------------------------------------------+
328-
| :const:`radix` | radix of exponent |
329-
+---------------------+--------------------------------------------------+
330-
| :const:`rounds` | addition rounds (see :file:`float.h`) |
331-
+---------------------+--------------------------------------------------+
299+
information about the precision and internal representation. The values
300+
correspond to the various floating-point constants defined in the standard
301+
header file :file:`float.h` for the 'C' programming language; see section
302+
5.2.4.2.2 of the 1999 ISO/IEC C standard [C99]_, 'Characteristics of
303+
floating types', for details.
304+
305+
+---------------------+----------------+--------------------------------------------------+
306+
| attribute | float.h macro | explanation |
307+
+=====================+================+==================================================+
308+
| :const:`epsilon` | DBL_MAX | difference between 1 and the least value greater |
309+
| | | than 1 that is representable as a float |
310+
+---------------------+----------------+--------------------------------------------------+
311+
| :const:`dig` | DBL_DIG | maximum number of decimal digits that can be |
312+
| | | faithfully represented in a float; see below |
313+
+---------------------+----------------+--------------------------------------------------+
314+
| :const:`mant_dig` | DBL_MANT_DIG | float precision: the number of base-``radix`` |
315+
| | | digits in the significand of a float |
316+
+---------------------+----------------+--------------------------------------------------+
317+
| :const:`max` | DBL_MAX | maximum representable finite float |
318+
+---------------------+----------------+--------------------------------------------------+
319+
| :const:`max_exp` | DBL_MAX_EXP | maximum integer e such that ``radix**(e-1)`` is |
320+
| | | a representable finite float |
321+
+---------------------+----------------+--------------------------------------------------+
322+
| :const:`max_10_exp` | DBL_MAX_10_EXP | maximum integer e such that ``10**e`` is in the |
323+
| | | range of representable finite floats |
324+
+---------------------+----------------+--------------------------------------------------+
325+
| :const:`min` | DBL_MIN | minimum positive normalized float |
326+
+---------------------+----------------+--------------------------------------------------+
327+
| :const:`min_exp` | DBL_MIN_EXP | minimum integer e such that ``radix**(e-1)`` is |
328+
| | | a normalized float |
329+
+---------------------+----------------+--------------------------------------------------+
330+
| :const:`min_10_exp` | DBL_MIN_10_EXP | minimum integer e such that ``10**e`` is a |
331+
| | | normalized float |
332+
+---------------------+----------------+--------------------------------------------------+
333+
| :const:`radix` | FLT_RADIX | radix of exponent representation |
334+
+---------------------+----------------+--------------------------------------------------+
335+
| :const:`rounds` | FLT_ROUNDS | constant representing rounding mode |
336+
| | | used for arithmetic operations |
337+
+---------------------+----------------+--------------------------------------------------+
338+
339+
The attribute :attr:`sys.float_info.dig` needs further explanation. If
340+
``s`` is any string representing a decimal number with at most
341+
:attr:`sys.float_info.dig` significant digits, then converting ``s`` to a
342+
float and back again will recover a string representing the same decimal
343+
value::
332344

333-
.. note::
345+
>>> import sys
346+
>>> sys.float_info.dig
347+
15
348+
>>> s = '3.14159265358979' # decimal string with 15 significant digits
349+
>>> format(float(s), '.15g') # convert to float and back -> same value
350+
'3.14159265358979'
351+
352+
But for strings with more than :attr:`sys.float_info.dig` significant digits,
353+
this isn't always true::
334354

335-
The information in the table is simplified.
355+
>>> s = '9876543211234567' # 16 significant digits is too many!
356+
>>> format(float(s), '.16g') # conversion changes value
357+
'9876543211234568'
336358

337359
.. versionadded:: 2.6
338360

@@ -992,3 +1014,8 @@ always available.
9921014
first three characters of :const:`version`. It is provided in the :mod:`sys`
9931015
module for informational purposes; modifying this value has no effect on the
9941016
registry keys used by Python. Availability: Windows.
1017+
1018+
.. rubric:: Citations
1019+
1020+
.. [C99] ISO/IEC 9899:1999. "Programming languages -- C." A public draft of this standard is available at http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf .
1021+

0 commit comments

Comments
 (0)