Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/conversion.rst @ 79675:c0a2294de787 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16199: Backport 2to3 typo fix from 3.2.
author Chris Jerdonek <chris.jerdonek@gmail.com>
date Thu, 11 Oct 2012 16:15:46 -0700
parents 74ff71b2f53d
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. highlightlang:: c
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 .. _string-conversion:
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 String conversion and formatting
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 ================================
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 Functions for number conversion and formatted string output.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
9
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
11 .. c:function:: int PyOS_snprintf(char *str, size_t size, const char *format, ...)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
12
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 Output not more than *size* bytes to *str* according to the format string
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 *format* and the extra arguments. See the Unix man page :manpage:`snprintf(2)`.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
15
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
16
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
17 .. c:function:: int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
18
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
19 Output not more than *size* bytes to *str* according to the format string
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 *format* and the variable argument list *va*. Unix man page
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 :manpage:`vsnprintf(2)`.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
22
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
23 :c:func:`PyOS_snprintf` and :c:func:`PyOS_vsnprintf` wrap the Standard C library
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
24 functions :c:func:`snprintf` and :c:func:`vsnprintf`. Their purpose is to
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
25 guarantee consistent behavior in corner cases, which the Standard C functions do
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
26 not.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
27
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
28 The wrappers ensure that *str*[*size*-1] is always ``'\0'`` upon return. They
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
29 never write more than *size* bytes (including the trailing ``'\0'`` into str.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 Both functions require that ``str != NULL``, ``size > 0`` and ``format !=
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 NULL``.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
32
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
33 If the platform doesn't have :c:func:`vsnprintf` and the buffer size needed to
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 avoid truncation exceeds *size* by more than 512 bytes, Python aborts with a
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 *Py_FatalError*.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
36
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 The return value (*rv*) for these functions should be interpreted as follows:
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
38
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
39 * When ``0 <= rv < size``, the output conversion was successful and *rv*
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
40 characters were written to *str* (excluding the trailing ``'\0'`` byte at
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
41 *str*[*rv*]).
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
42
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
43 * When ``rv >= size``, the output conversion was truncated and a buffer with
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
44 ``rv + 1`` bytes would have been needed to succeed. *str*[*size*-1] is ``'\0'``
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
45 in this case.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
46
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
47 * When ``rv < 0``, "something bad happened." *str*[*size*-1] is ``'\0'`` in
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
48 this case too, but the rest of *str* is undefined. The exact cause of the error
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
49 depends on the underlying platform.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
50
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
51 The following functions provide locale-independent string to number conversions.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
52
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
53
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
54 .. c:function:: double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
56999
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
55
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
56 Convert a string ``s`` to a :c:type:`double`, raising a Python
56999
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
57 exception on failure. The set of accepted strings corresponds to
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
58 the set of strings accepted by Python's :func:`float` constructor,
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
59 except that ``s`` must not have leading or trailing whitespace.
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
60 The conversion is independent of the current locale.
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
61
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
62 If ``endptr`` is ``NULL``, convert the whole string. Raise
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
63 ValueError and return ``-1.0`` if the string is not a valid
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
64 representation of a floating-point number.
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
65
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
66 If endptr is not ``NULL``, convert as much of the string as
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
67 possible and set ``*endptr`` to point to the first unconverted
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
68 character. If no initial segment of the string is the valid
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
69 representation of a floating-point number, set ``*endptr`` to point
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
70 to the beginning of the string, raise ValueError, and return
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
71 ``-1.0``.
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
72
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
73 If ``s`` represents a value that is too large to store in a float
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
74 (for example, ``"1e500"`` is such a string on many platforms) then
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
75 if ``overflow_exception`` is ``NULL`` return ``Py_HUGE_VAL`` (with
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
76 an appropriate sign) and don't set any exception. Otherwise,
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
77 ``overflow_exception`` must point to a Python exception object;
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
78 raise that exception and return ``-1.0``. In both cases, set
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
79 ``*endptr`` to point to the first character after the converted value.
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
80
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
81 If any other error occurs during the conversion (for example an
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
82 out-of-memory error), set the appropriate Python exception and
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
83 return ``-1.0``.
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
84
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
85 .. versionadded:: 2.7
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
86
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
87
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
88 .. c:function:: double PyOS_ascii_strtod(const char *nptr, char **endptr)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
89
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
90 Convert a string to a :c:type:`double`. This function behaves like the Standard C
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
91 function :c:func:`strtod` does in the C locale. It does this without changing the
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 current locale, since that would not be thread-safe.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
93
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
94 :c:func:`PyOS_ascii_strtod` should typically be used for reading configuration
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 files or other non-user input that should be locale independent.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
96
56999
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
97 See the Unix man page :manpage:`strtod(2)` for details.
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
98
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 .. versionadded:: 2.4
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
100
56999
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
101 .. deprecated:: 2.7
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
102 Use :c:func:`PyOS_string_to_double` instead.
56999
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
103
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
104
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
105
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
106 .. c:function:: char* PyOS_ascii_formatd(char *buffer, size_t buf_len, const char *format, double d)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
107
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
108 Convert a :c:type:`double` to a string using the ``'.'`` as the decimal
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
109 separator. *format* is a :c:func:`printf`\ -style format string specifying the
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
110 number format. Allowed conversion characters are ``'e'``, ``'E'``, ``'f'``,
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
111 ``'F'``, ``'g'`` and ``'G'``.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
112
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
113 The return value is a pointer to *buffer* with the converted string or NULL if
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
114 the conversion failed.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
115
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
116 .. versionadded:: 2.4
53442
6947bc3dd433 Issue #5835, deprecate PyOS_ascii_formatd.
Eric Smith <eric@trueblade.com>
parents: 50522
diff changeset
117 .. deprecated:: 2.7
6947bc3dd433 Issue #5835, deprecate PyOS_ascii_formatd.
Eric Smith <eric@trueblade.com>
parents: 50522
diff changeset
118 This function is removed in Python 2.7 and 3.1. Use :func:`PyOS_double_to_string`
6947bc3dd433 Issue #5835, deprecate PyOS_ascii_formatd.
Eric Smith <eric@trueblade.com>
parents: 50522
diff changeset
119 instead.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
120
53456
1c2d11a7eb23 Mostly formatting nits, and "and-ed together" -> "or-ed together" flags.
Georg Brandl <georg@python.org>
parents: 53442
diff changeset
121
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
122 .. c:function:: char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
53442
6947bc3dd433 Issue #5835, deprecate PyOS_ascii_formatd.
Eric Smith <eric@trueblade.com>
parents: 50522
diff changeset
123
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
124 Convert a :c:type:`double` *val* to a string using supplied
53442
6947bc3dd433 Issue #5835, deprecate PyOS_ascii_formatd.
Eric Smith <eric@trueblade.com>
parents: 50522
diff changeset
125 *format_code*, *precision*, and *flags*.
6947bc3dd433 Issue #5835, deprecate PyOS_ascii_formatd.
Eric Smith <eric@trueblade.com>
parents: 50522
diff changeset
126
53802
1d8f24d40c2c Issue #5920: Changed format.__float__ and complex.__float__ to use a precision of 12 when using the empty presentation type. This more closely matches str()'s behavior and reduces surprises when adding alignment flags to an empty format string. Patch by Mark Dickinson.
Eric Smith <eric@trueblade.com>
parents: 53463
diff changeset
127 *format_code* must be one of ``'e'``, ``'E'``, ``'f'``, ``'F'``,
1d8f24d40c2c Issue #5920: Changed format.__float__ and complex.__float__ to use a precision of 12 when using the empty presentation type. This more closely matches str()'s behavior and reduces surprises when adding alignment flags to an empty format string. Patch by Mark Dickinson.
Eric Smith <eric@trueblade.com>
parents: 53463
diff changeset
128 ``'g'``, ``'G'`` or ``'r'``. For ``'r'``, the supplied *precision*
1d8f24d40c2c Issue #5920: Changed format.__float__ and complex.__float__ to use a precision of 12 when using the empty presentation type. This more closely matches str()'s behavior and reduces surprises when adding alignment flags to an empty format string. Patch by Mark Dickinson.
Eric Smith <eric@trueblade.com>
parents: 53463
diff changeset
129 must be 0 and is ignored. The ``'r'`` format code specifies the
1d8f24d40c2c Issue #5920: Changed format.__float__ and complex.__float__ to use a precision of 12 when using the empty presentation type. This more closely matches str()'s behavior and reduces surprises when adding alignment flags to an empty format string. Patch by Mark Dickinson.
Eric Smith <eric@trueblade.com>
parents: 53463
diff changeset
130 standard :func:`repr` format.
53442
6947bc3dd433 Issue #5835, deprecate PyOS_ascii_formatd.
Eric Smith <eric@trueblade.com>
parents: 50522
diff changeset
131
6947bc3dd433 Issue #5835, deprecate PyOS_ascii_formatd.
Eric Smith <eric@trueblade.com>
parents: 50522
diff changeset
132 *flags* can be zero or more of the values *Py_DTSF_SIGN*,
53456
1c2d11a7eb23 Mostly formatting nits, and "and-ed together" -> "or-ed together" flags.
Georg Brandl <georg@python.org>
parents: 53442
diff changeset
133 *Py_DTSF_ADD_DOT_0*, or *Py_DTSF_ALT*, or-ed together:
53442
6947bc3dd433 Issue #5835, deprecate PyOS_ascii_formatd.
Eric Smith <eric@trueblade.com>
parents: 50522
diff changeset
134
53456
1c2d11a7eb23 Mostly formatting nits, and "and-ed together" -> "or-ed together" flags.
Georg Brandl <georg@python.org>
parents: 53442
diff changeset
135 * *Py_DTSF_SIGN* means to always precede the returned string with a sign
1c2d11a7eb23 Mostly formatting nits, and "and-ed together" -> "or-ed together" flags.
Georg Brandl <georg@python.org>
parents: 53442
diff changeset
136 character, even if *val* is non-negative.
53442
6947bc3dd433 Issue #5835, deprecate PyOS_ascii_formatd.
Eric Smith <eric@trueblade.com>
parents: 50522
diff changeset
137
53456
1c2d11a7eb23 Mostly formatting nits, and "and-ed together" -> "or-ed together" flags.
Georg Brandl <georg@python.org>
parents: 53442
diff changeset
138 * *Py_DTSF_ADD_DOT_0* means to ensure that the returned string will not look
1c2d11a7eb23 Mostly formatting nits, and "and-ed together" -> "or-ed together" flags.
Georg Brandl <georg@python.org>
parents: 53442
diff changeset
139 like an integer.
53442
6947bc3dd433 Issue #5835, deprecate PyOS_ascii_formatd.
Eric Smith <eric@trueblade.com>
parents: 50522
diff changeset
140
53456
1c2d11a7eb23 Mostly formatting nits, and "and-ed together" -> "or-ed together" flags.
Georg Brandl <georg@python.org>
parents: 53442
diff changeset
141 * *Py_DTSF_ALT* means to apply "alternate" formatting rules. See the
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
142 documentation for the :c:func:`PyOS_snprintf` ``'#'`` specifier for
53456
1c2d11a7eb23 Mostly formatting nits, and "and-ed together" -> "or-ed together" flags.
Georg Brandl <georg@python.org>
parents: 53442
diff changeset
143 details.
53442
6947bc3dd433 Issue #5835, deprecate PyOS_ascii_formatd.
Eric Smith <eric@trueblade.com>
parents: 50522
diff changeset
144
53456
1c2d11a7eb23 Mostly formatting nits, and "and-ed together" -> "or-ed together" flags.
Georg Brandl <georg@python.org>
parents: 53442
diff changeset
145 If *ptype* is non-NULL, then the value it points to will be set to one of
1c2d11a7eb23 Mostly formatting nits, and "and-ed together" -> "or-ed together" flags.
Georg Brandl <georg@python.org>
parents: 53442
diff changeset
146 *Py_DTST_FINITE*, *Py_DTST_INFINITE*, or *Py_DTST_NAN*, signifying that
1c2d11a7eb23 Mostly formatting nits, and "and-ed together" -> "or-ed together" flags.
Georg Brandl <georg@python.org>
parents: 53442
diff changeset
147 *val* is a finite number, an infinite number, or not a number, respectively.
53442
6947bc3dd433 Issue #5835, deprecate PyOS_ascii_formatd.
Eric Smith <eric@trueblade.com>
parents: 50522
diff changeset
148
53456
1c2d11a7eb23 Mostly formatting nits, and "and-ed together" -> "or-ed together" flags.
Georg Brandl <georg@python.org>
parents: 53442
diff changeset
149 The return value is a pointer to *buffer* with the converted string or
53463
a15c28bfbb38 Note that the caller is resposible for freeing the result of PyOS_double_to_string.
Eric Smith <eric@trueblade.com>
parents: 53456
diff changeset
150 *NULL* if the conversion failed. The caller is responsible for freeing the
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
151 returned string by calling :c:func:`PyMem_Free`.
53442
6947bc3dd433 Issue #5835, deprecate PyOS_ascii_formatd.
Eric Smith <eric@trueblade.com>
parents: 50522
diff changeset
152
6947bc3dd433 Issue #5835, deprecate PyOS_ascii_formatd.
Eric Smith <eric@trueblade.com>
parents: 50522
diff changeset
153 .. versionadded:: 2.7
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47937
diff changeset
154
53456
1c2d11a7eb23 Mostly formatting nits, and "and-ed together" -> "or-ed together" flags.
Georg Brandl <georg@python.org>
parents: 53442
diff changeset
155
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
156 .. c:function:: double PyOS_ascii_atof(const char *nptr)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
157
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
158 Convert a string to a :c:type:`double` in a locale-independent way.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
159
56999
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
160 See the Unix man page :manpage:`atof(2)` for details.
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
161
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
162 .. versionadded:: 2.4
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
163
56999
bab3e3cd76f1 Deprecate PyOS_ascii_strtod and PyOS_ascii_atof, and document the replacement function PyOS_string_to_double.
Mark Dickinson <dickinsm@gmail.com>
parents: 53802
diff changeset
164 .. deprecated:: 3.1
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
165 Use :c:func:`PyOS_string_to_double` instead.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
166
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47937
diff changeset
167
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
168 .. c:function:: char* PyOS_stricmp(char *s1, char *s2)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
169
47937
38d3a50defec fix various doc typos #3320
Benjamin Peterson <benjamin@python.org>
parents: 44797
diff changeset
170 Case insensitive comparison of strings. The function works almost
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
171 identically to :c:func:`strcmp` except that it ignores the case.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
172
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
173 .. versionadded:: 2.6
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
174
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
175
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
176 .. c:function:: char* PyOS_strnicmp(char *s1, char *s2, Py_ssize_t size)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
177
47937
38d3a50defec fix various doc typos #3320
Benjamin Peterson <benjamin@python.org>
parents: 44797
diff changeset
178 Case insensitive comparison of strings. The function works almost
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 56999
diff changeset
179 identically to :c:func:`strncmp` except that it ignores the case.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
180
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
181 .. versionadded:: 2.6