[Python-checkins] r86648 - python/branches/py3k/Doc/library/functions.rst
python-checkins at python.org
Sun Nov 21 22:09:58 CET 2010
Date: Sun Nov 21 22:09:58 2010
New Revision: 86648
Issue #10488: Bring documentation for 'float' builtin up to date.
--- python/branches/py3k/Doc/library/functions.rst (original)
+++ python/branches/py3k/Doc/library/functions.rst Sun Nov 21 22:09:58 2010
@@ -399,26 +399,54 @@
.. function:: float([x])
- Convert a string or a number to floating point. If the argument is a string,
- it must contain a possibly signed decimal or floating point number, possibly
- embedded in whitespace. The argument may also be ``'[+|-]nan'`` or
- ``'[+|-]inf'``. Otherwise, the argument may be an integer or a floating
- point number, and a floating point number with the same value (within
- Python's floating point precision) is returned. If no argument is given,
- ``0.0`` is returned.
+ .. index::
+ single: NaN
+ single: Infinity
- .. note::
+ Convert a string or a number to floating point.
- .. index::
- single: NaN
- single: Infinity
- When passing in a string, values for NaN and Infinity may be returned,
- depending on the underlying C library. Float accepts the strings
- ``'nan'``, ``'inf'`` and ``'-inf'`` for NaN and positive or negative
- infinity. The case and a leading + are ignored as well as a leading - is
- ignored for NaN. Float always represents NaN and infinity as ``nan``,
- ``inf`` or ``-inf``.
+ If the argument is a string, it should contain a decimal number, optionally
+ preceded by a sign, and optionally embedded in whitespace. The optional
+ sign may be ``'+'`` or ``'-'``; a ``'+'`` sign has no effect on the value
+ produced. The argument may also be a string representing a NaN
+ (not-a-number), or a positive or negative infinity. More precisely, the
+ input must conform to the following grammar after leading and trailing
+ whitespace characters are removed:
+ .. productionlist::
+ sign: "+" | "-"
+ infinity: "Infinity" | "inf"
+ nan: "nan"
+ numeric-value: `floatnumber` | `infinity` | `nan`
+ numeric-string: [`sign`] `numeric-value`
+ Here ``floatnumber`` is the form of a Python floating-point literal,
+ described in :ref:`floating`. Case is not significant, so, for example,
+ "inf", "Inf", "INFINITY" and "iNfINity" are all acceptable spellings for
+ positive infinity.
+ Otherwise, if the argument is an integer or a floating point number, a
+ floating point number with the same value (within Python's floating point
+ precision) is returned. If the argument is outside the range of a Python
+ float, an :exc:`OverflowError` will be raised.
+ For a general Python object ``x``, ``float(x)`` delegates to
+ If no argument is given, ``0.0`` is returned.
+ >>> float('+1.23')
+ >>> float(' -12345\n')
+ >>> float('1e-003')
+ >>> float('+1E6')
+ >>> float('-Infinity')
The float type is described in :ref:`typesnumeric`.
More information about the Python-checkins