Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Clarify sys.float_info documentation.

This commit is contained in:
Mark Dickinson 2010-07-02 18:06:52 +00:00
parent 601ec58f3e
commit 2547ce7fd8
1 changed files with 61 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
Doc/library/sys.rst
View File

@ -296,43 +296,65 @@ always available.
.. data:: float_info .. data:: float_info
A structseq holding information about the float type. It contains low level A structseq holding information about the float type. It contains low level
information about the precision and internal representation. Please study information about the precision and internal representation. The values
your system's :file:`float.h` for more information. correspond to the various floating-point constants defined in the standard
header file :file:`float.h` for the 'C' programming language; see section
5.2.4.2.2 of the 1999 ISO/IEC C standard [C99]_, 'Characteristics of
floating types', for details.
+---------------------+--------------------------------------------------+ +---------------------+----------------+--------------------------------------------------+
| attribute | explanation | | attribute | float.h macro | explanation |
+=====================+==================================================+ +=====================+================+==================================================+
| :const:`epsilon` | Difference between 1 and the next representable | | :const:`epsilon` | DBL_MAX | difference between 1 and the least value greater |
| | floating point number | | | | than 1 that is representable as a float |
+---------------------+--------------------------------------------------+ +---------------------+----------------+--------------------------------------------------+
| :const:`dig` | digits (see :file:`float.h`) | | :const:`dig` | DBL_DIG | maximum number of decimal digits that can be |
+---------------------+--------------------------------------------------+ | | | faithfully represented in a float; see below |
| :const:`mant_dig` | mantissa digits (see :file:`float.h`) | +---------------------+----------------+--------------------------------------------------+
+---------------------+--------------------------------------------------+ | :const:`mant_dig` | DBL_MANT_DIG | float precision: the number of base-``radix`` |
| :const:`max` | maximum representable finite float | | | | digits in the significand of a float |
+---------------------+--------------------------------------------------+ +---------------------+----------------+--------------------------------------------------+
| :const:`max_exp` | maximum int e such that radix**(e-1) is in the | | :const:`max` | DBL_MAX | maximum representable finite float |
| | range of finite representable floats | +---------------------+----------------+--------------------------------------------------+
+---------------------+--------------------------------------------------+ | :const:`max_exp` | DBL_MAX_EXP | maximum integer e such that ``radix**(e-1)`` is |
| :const:`max_10_exp` | maximum int e such that 10**e is in the | | | | a representable finite float |
| | range of finite representable floats | +---------------------+----------------+--------------------------------------------------+
+---------------------+--------------------------------------------------+ | :const:`max_10_exp` | DBL_MAX_10_EXP | maximum integer e such that ``10**e`` is in the |
| :const:`min` | Minimum positive normalizer float | | | | range of representable finite floats |
+---------------------+--------------------------------------------------+ +---------------------+----------------+--------------------------------------------------+
| :const:`min_exp` | minimum int e such that radix**(e-1) is a | | :const:`min` | DBL_MIN | minimum positive normalized float |
| | normalized float | +---------------------+----------------+--------------------------------------------------+
+---------------------+--------------------------------------------------+ | :const:`min_exp` | DBL_MIN_EXP | minimum integer e such that ``radix**(e-1)`` is |
| :const:`min_10_exp` | minimum int e such that 10**e is a normalized | | | | a normalized float |
| | float | +---------------------+----------------+--------------------------------------------------+
+---------------------+--------------------------------------------------+ | :const:`min_10_exp` | DBL_MIN_10_EXP | minimum integer e such that ``10**e`` is a |
| :const:`radix` | radix of exponent | | | | normalized float |
+---------------------+--------------------------------------------------+ +---------------------+----------------+--------------------------------------------------+
| :const:`rounds` | addition rounds (see :file:`float.h`) | | :const:`radix` | FLT_RADIX | radix of exponent representation |
+---------------------+--------------------------------------------------+ +---------------------+----------------+--------------------------------------------------+
| :const:`rounds` | FLT_ROUNDS | constant representing rounding mode |
| | | used for arithmetic operations |
+---------------------+----------------+--------------------------------------------------+
.. note:: The attribute :attr:`sys.float_info.dig` needs further explanation. If
``s`` is any string representing a decimal number with at most
:attr:`sys.float_info.dig` significant digits, then converting ``s`` to a
float and back again will recover a string representing the same decimal
value::
The information in the table is simplified. >>> import sys
>>> sys.float_info.dig
15
>>> s = '3.14159265358979' # decimal string with 15 significant digits
>>> format(float(s), '.15g') # convert to float and back -> same value
'3.14159265358979'
But for strings with more than :attr:`sys.float_info.dig` significant digits,
this isn't always true::
>>> s = '9876543211234567' # 16 significant digits is too many!
>>> format(float(s), '.16g') # conversion changes value
'9876543211234568'
.. versionadded:: 2.6 .. versionadded:: 2.6
@ -992,3 +1014,8 @@ always available.
first three characters of :const:`version`. It is provided in the :mod:`sys` first three characters of :const:`version`. It is provided in the :mod:`sys`
module for informational purposes; modifying this value has no effect on the module for informational purposes; modifying this value has no effect on the
registry keys used by Python. Availability: Windows. registry keys used by Python. Availability: Windows.
.. rubric:: Citations
.. [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 .