summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
authorMark Dickinson <dickinsm@gmail.com>2010-07-02 20:26:07 (GMT)
committerMark Dickinson <dickinsm@gmail.com>2010-07-02 20:26:07 (GMT)
commitbe5846bfdc90bb4216a179dcc3ced11bf4aaaf8c (patch)
tree96314bea7ac05d754c4e06830bfcc65d51ac1dea /Doc
parent5d4708374c71dc00c55467aff74f373879703d20 (diff)
downloadcpython-be5846bfdc90bb4216a179dcc3ced11bf4aaaf8c.zip
cpython-be5846bfdc90bb4216a179dcc3ced11bf4aaaf8c.tar.gz
cpython-be5846bfdc90bb4216a179dcc3ced11bf4aaaf8c.tar.bz2
Merged revisions 82446 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk ........ r82446 | mark.dickinson | 2010-07-02 19:06:52 +0100 (Fri, 02 Jul 2010) | 1 line Clarify sys.float_info documentation. ........
Diffstat (limited to 'Doc')
-rw-r--r--Doc/library/sys.rst96
1 files changed, 61 insertions, 35 deletions
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index e2a2f72..2ce748f 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -223,44 +223,65 @@ always available.
.. data:: float_info
A structseq holding information about the float type. It contains low level
- information about the precision and internal representation. Please study
- your system's :file:`float.h` for more information.
+ information about the precision and internal representation. The values
+ 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 | float.h macro | explanation |
+ +=====================+================+==================================================+
+ | :const:`epsilon` | DBL_MAX | difference between 1 and the least value greater |
+ | | | than 1 that is representable as a float |
+ +---------------------+----------------+--------------------------------------------------+
+ | :const:`dig` | DBL_DIG | maximum number of decimal digits that can be |
+ | | | faithfully represented in a float; see below |
+ +---------------------+----------------+--------------------------------------------------+
+ | :const:`mant_dig` | DBL_MANT_DIG | float precision: the number of base-``radix`` |
+ | | | digits in the significand of a float |
+ +---------------------+----------------+--------------------------------------------------+
+ | :const:`max` | DBL_MAX | maximum representable finite float |
+ +---------------------+----------------+--------------------------------------------------+
+ | :const:`max_exp` | DBL_MAX_EXP | maximum integer e such that ``radix**(e-1)`` is |
+ | | | a representable finite float |
+ +---------------------+----------------+--------------------------------------------------+
+ | :const:`max_10_exp` | DBL_MAX_10_EXP | maximum integer e such that ``10**e`` is in the |
+ | | | range of representable finite floats |
+ +---------------------+----------------+--------------------------------------------------+
+ | :const:`min` | DBL_MIN | minimum positive normalized float |
+ +---------------------+----------------+--------------------------------------------------+
+ | :const:`min_exp` | DBL_MIN_EXP | minimum integer e such that ``radix**(e-1)`` is |
+ | | | a normalized float |
+ +---------------------+----------------+--------------------------------------------------+
+ | :const:`min_10_exp` | DBL_MIN_10_EXP | minimum integer e such that ``10**e`` is a |
+ | | | normalized float |
+ +---------------------+----------------+--------------------------------------------------+
+ | :const:`radix` | FLT_RADIX | radix of exponent representation |
+ +---------------------+----------------+--------------------------------------------------+
+ | :const:`rounds` | FLT_ROUNDS | constant representing rounding mode |
+ | | | used for arithmetic operations |
+ +---------------------+----------------+--------------------------------------------------+
+
+ 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::
- +---------------------+--------------------------------------------------+
- | attribute | explanation |
- +=====================+==================================================+
- | :const:`epsilon` | Difference between 1 and the next representable |
- | | floating point number |
- +---------------------+--------------------------------------------------+
- | :const:`dig` | digits (see :file:`float.h`) |
- +---------------------+--------------------------------------------------+
- | :const:`mant_dig` | mantissa digits (see :file:`float.h`) |
- +---------------------+--------------------------------------------------+
- | :const:`max` | maximum representable finite float |
- +---------------------+--------------------------------------------------+
- | :const:`max_exp` | maximum int e such that radix**(e-1) is in the |
- | | range of finite representable floats |
- +---------------------+--------------------------------------------------+
- | :const:`max_10_exp` | maximum int e such that 10**e is in the |
- | | range of finite representable floats |
- +---------------------+--------------------------------------------------+
- | :const:`min` | Minimum positive normalizer float |
- +---------------------+--------------------------------------------------+
- | :const:`min_exp` | minimum int e such that radix**(e-1) is a |
- | | normalized float |
- +---------------------+--------------------------------------------------+
- | :const:`min_10_exp` | minimum int e such that 10**e is a normalized |
- | | float |
- +---------------------+--------------------------------------------------+
- | :const:`radix` | radix of exponent |
- +---------------------+--------------------------------------------------+
- | :const:`rounds` | addition rounds (see :file:`float.h`) |
- +---------------------+--------------------------------------------------+
-
- .. note::
+ >>> 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'
- The information in the table is simplified.
+ 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'
.. data:: float_repr_style
@@ -957,3 +978,8 @@ always available.
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
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 .
+