|
1 .. highlightlang:: c |
|
2 |
|
3 .. _string-conversion: |
|
4 |
|
5 String conversion and formatting |
|
6 ================================ |
|
7 |
|
8 Functions for number conversion and formatted string output. |
|
9 |
|
10 |
|
11 .. cfunction:: int PyOS_snprintf(char *str, size_t size, const char *format, ...) |
|
12 |
|
13 Output not more than *size* bytes to *str* according to the format string |
|
14 *format* and the extra arguments. See the Unix man page :manpage:`snprintf(2)`. |
|
15 |
|
16 |
|
17 .. cfunction:: int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va) |
|
18 |
|
19 Output not more than *size* bytes to *str* according to the format string |
|
20 *format* and the variable argument list *va*. Unix man page |
|
21 :manpage:`vsnprintf(2)`. |
|
22 |
|
23 :cfunc:`PyOS_snprintf` and :cfunc:`PyOS_vsnprintf` wrap the Standard C library |
|
24 functions :cfunc:`snprintf` and :cfunc:`vsnprintf`. Their purpose is to |
|
25 guarantee consistent behavior in corner cases, which the Standard C functions do |
|
26 not. |
|
27 |
|
28 The wrappers ensure that *str*[*size*-1] is always ``'\0'`` upon return. They |
|
29 never write more than *size* bytes (including the trailing ``'\0'`` into str. |
|
30 Both functions require that ``str != NULL``, ``size > 0`` and ``format != |
|
31 NULL``. |
|
32 |
|
33 If the platform doesn't have :cfunc:`vsnprintf` and the buffer size needed to |
|
34 avoid truncation exceeds *size* by more than 512 bytes, Python aborts with a |
|
35 *Py_FatalError*. |
|
36 |
|
37 The return value (*rv*) for these functions should be interpreted as follows: |
|
38 |
|
39 * When ``0 <= rv < size``, the output conversion was successful and *rv* |
|
40 characters were written to *str* (excluding the trailing ``'\0'`` byte at |
|
41 *str*[*rv*]). |
|
42 |
|
43 * When ``rv >= size``, the output conversion was truncated and a buffer with |
|
44 ``rv + 1`` bytes would have been needed to succeed. *str*[*size*-1] is ``'\0'`` |
|
45 in this case. |
|
46 |
|
47 * When ``rv < 0``, "something bad happened." *str*[*size*-1] is ``'\0'`` in |
|
48 this case too, but the rest of *str* is undefined. The exact cause of the error |
|
49 depends on the underlying platform. |
|
50 |
|
51 The following functions provide locale-independent string to number conversions. |
|
52 |
|
53 |
|
54 .. cfunction:: double PyOS_ascii_strtod(const char *nptr, char **endptr) |
|
55 |
|
56 Convert a string to a :ctype:`double`. This function behaves like the Standard C |
|
57 function :cfunc:`strtod` does in the C locale. It does this without changing the |
|
58 current locale, since that would not be thread-safe. |
|
59 |
|
60 :cfunc:`PyOS_ascii_strtod` should typically be used for reading configuration |
|
61 files or other non-user input that should be locale independent. |
|
62 |
|
63 .. versionadded:: 2.4 |
|
64 |
|
65 See the Unix man page :manpage:`strtod(2)` for details. |
|
66 |
|
67 |
|
68 .. cfunction:: char * PyOS_ascii_formatd(char *buffer, size_t buf_len, const char *format, double d) |
|
69 |
|
70 Convert a :ctype:`double` to a string using the ``'.'`` as the decimal |
|
71 separator. *format* is a :cfunc:`printf`\ -style format string specifying the |
|
72 number format. Allowed conversion characters are ``'e'``, ``'E'``, ``'f'``, |
|
73 ``'F'``, ``'g'`` and ``'G'``. |
|
74 |
|
75 The return value is a pointer to *buffer* with the converted string or NULL if |
|
76 the conversion failed. |
|
77 |
|
78 .. versionadded:: 2.4 |
|
79 |
|
80 |
|
81 .. cfunction:: double PyOS_ascii_atof(const char *nptr) |
|
82 |
|
83 Convert a string to a :ctype:`double` in a locale-independent way. |
|
84 |
|
85 .. versionadded:: 2.4 |
|
86 |
|
87 See the Unix man page :manpage:`atof(2)` for details. |
|
88 |
|
89 |
|
90 .. cfunction:: char * PyOS_stricmp(char *s1, char *s2) |
|
91 |
|
92 Case insensitive comparison of strings. The function works almost |
|
93 identically to :cfunc:`strcmp` except that it ignores the case. |
|
94 |
|
95 .. versionadded:: 2.6 |
|
96 |
|
97 |
|
98 .. cfunction:: char * PyOS_strnicmp(char *s1, char *s2, Py_ssize_t size) |
|
99 |
|
100 Case insensitive comparison of strings. The function works almost |
|
101 identically to :cfunc:`strncmp` except that it ignores the case. |
|
102 |
|
103 .. versionadded:: 2.6 |