diff --git a/Doc/c-api/conversion.rst b/Doc/c-api/conversion.rst index fc42508ede4..b32100b82bf 100644 --- a/Doc/c-api/conversion.rst +++ b/Doc/c-api/conversion.rst @@ -51,6 +51,40 @@ The return value (*rv*) for these functions should be interpreted as follows: The following functions provide locale-independent string to number conversions. +.. cfunction:: double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception) + + Convert a string ``s`` to a :ctype:`double`, raising a Python + exception on failure. The set of accepted strings corresponds to + the set of strings accepted by Python's :func:`float` constructor, + except that ``s`` must not have leading or trailing whitespace. + The conversion is independent of the current locale. + + If ``endptr`` is ``NULL``, convert the whole string. Raise + ValueError and return ``-1.0`` if the string is not a valid + representation of a floating-point number. + + If endptr is not ``NULL``, convert as much of the string as + possible and set ``*endptr`` to point to the first unconverted + character. If no initial segment of the string is the valid + representation of a floating-point number, set ``*endptr`` to point + to the beginning of the string, raise ValueError, and return + ``-1.0``. + + If ``s`` represents a value that is too large to store in a float + (for example, ``"1e500"`` is such a string on many platforms) then + if ``overflow_exception`` is ``NULL`` return ``Py_HUGE_VAL`` (with + an appropriate sign) and don't set any exception. Otherwise, + ``overflow_exception`` must point to a Python exception object; + raise that exception and return ``-1.0``. In both cases, set + ``*endptr`` to point to the first character after the converted value. + + If any other error occurs during the conversion (for example an + out-of-memory error), set the appropriate Python exception and + return ``-1.0``. + + .. versionadded:: 2.7 + + .. cfunction:: double PyOS_ascii_strtod(const char *nptr, char **endptr) Convert a string to a :ctype:`double`. This function behaves like the Standard C @@ -60,9 +94,13 @@ The following functions provide locale-independent string to number conversions. :cfunc:`PyOS_ascii_strtod` should typically be used for reading configuration files or other non-user input that should be locale independent. + See the Unix man page :manpage:`strtod(2)` for details. + .. versionadded:: 2.4 - See the Unix man page :manpage:`strtod(2)` for details. + .. deprecated:: 2.7 + Use :cfunc:`PyOS_string_to_double` instead. + .. cfunction:: char* PyOS_ascii_formatd(char *buffer, size_t buf_len, const char *format, double d) @@ -119,9 +157,12 @@ The following functions provide locale-independent string to number conversions. Convert a string to a :ctype:`double` in a locale-independent way. + See the Unix man page :manpage:`atof(2)` for details. + .. versionadded:: 2.4 - See the Unix man page :manpage:`atof(2)` for details. + .. deprecated:: 3.1 + Use :cfunc:`PyOS_string_to_double` instead. .. cfunction:: char* PyOS_stricmp(char *s1, char *s2) diff --git a/Misc/NEWS b/Misc/NEWS index 8fcef1d662f..e2695053427 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -1414,6 +1414,9 @@ Documentation C-API ----- +- Add new C-API function PyOS_string_to_double, and deprecated + PyOS_ascii_atof and PyOS_ascii_strtod. + - Removed _PyOS_double_to_string. Use PyOS_double_to_string instead. This is in preparation for (but not strictly related to) issue #7117, short float repr. diff --git a/Python/pystrtod.c b/Python/pystrtod.c index 64bf73daecd..27ddc941c2d 100644 --- a/Python/pystrtod.c +++ b/Python/pystrtod.c @@ -270,6 +270,8 @@ _PyOS_ascii_strtod(const char *nptr, char **endptr) #endif +/* PyOS_ascii_strtod is DEPRECATED in Python 2.7 and 3.1 */ + double PyOS_ascii_strtod(const char *nptr, char **endptr) { @@ -277,6 +279,12 @@ PyOS_ascii_strtod(const char *nptr, char **endptr) const char *p; double x; + if (PyErr_WarnEx(PyExc_DeprecationWarning, + "PyOS_ascii_strtod and PyOS_ascii_atof are " + "deprecated. Use PyOS_string_to_double " + "instead.", 1) < 0) + return -1.0; + /* _PyOS_ascii_strtod already does everything that we want, except that it doesn't parse leading whitespace */ p = nptr; @@ -290,13 +298,15 @@ PyOS_ascii_strtod(const char *nptr, char **endptr) return x; } +/* PyOS_ascii_strtod is DEPRECATED in Python 2.7 and 3.1 */ + double PyOS_ascii_atof(const char *nptr) { return PyOS_ascii_strtod(nptr, NULL); } -/* PyOS_string_to_double is the recommended replacement for the +/* PyOS_string_to_double is the recommended replacement for the deprecated PyOS_ascii_strtod and PyOS_ascii_atof functions. It converts a null-terminated byte string s (interpreted as a string of ASCII characters) to a float. The string should not have leading or trailing whitespace (in @@ -332,7 +342,7 @@ PyOS_string_to_double(const char *s, errno = 0; PyFPE_START_PROTECT("PyOS_string_to_double", return -1.0) - x = PyOS_ascii_strtod(s, &fail_pos); + x = _PyOS_ascii_strtod(s, &fail_pos); PyFPE_END_PROTECT(x) if (errno == ENOMEM) {