Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 11 | .. c:function:: int PyOS_snprintf(char *str, size_t size, const char *format, ...) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 17 | .. c:function:: int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 23 | :c:func:`PyOS_snprintf` and :c:func:`PyOS_vsnprintf` wrap the Standard C library |
| 24 | functions :c:func:`snprintf` and :c:func:`vsnprintf`. Their purpose is to |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 33 | If the platform doesn't have :c:func:`vsnprintf` and the buffer size needed to |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 54 | .. c:function:: double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception) |
Mark Dickinson | 725bfd8 | 2009-05-03 20:33:40 +0000 | [diff] [blame] | 55 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 56 | Convert a string ``s`` to a :c:type:`double`, raising a Python |
Mark Dickinson | 725bfd8 | 2009-05-03 20:33:40 +0000 | [diff] [blame] | 57 | exception on failure. The set of accepted strings corresponds to |
| 58 | the set of strings accepted by Python's :func:`float` constructor, |
| 59 | except that ``s`` must not have leading or trailing whitespace. |
| 60 | The conversion is independent of the current locale. |
| 61 | |
| 62 | If ``endptr`` is ``NULL``, convert the whole string. Raise |
| 63 | ValueError and return ``-1.0`` if the string is not a valid |
| 64 | representation of a floating-point number. |
| 65 | |
| 66 | If endptr is not ``NULL``, convert as much of the string as |
| 67 | possible and set ``*endptr`` to point to the first unconverted |
| 68 | character. If no initial segment of the string is the valid |
| 69 | representation of a floating-point number, set ``*endptr`` to point |
| 70 | to the beginning of the string, raise ValueError, and return |
| 71 | ``-1.0``. |
| 72 | |
| 73 | If ``s`` represents a value that is too large to store in a float |
| 74 | (for example, ``"1e500"`` is such a string on many platforms) then |
| 75 | if ``overflow_exception`` is ``NULL`` return ``Py_HUGE_VAL`` (with |
| 76 | an appropriate sign) and don't set any exception. Otherwise, |
| 77 | ``overflow_exception`` must point to a Python exception object; |
| 78 | raise that exception and return ``-1.0``. In both cases, set |
| 79 | ``*endptr`` to point to the first character after the converted value. |
| 80 | |
| 81 | If any other error occurs during the conversion (for example an |
| 82 | out-of-memory error), set the appropriate Python exception and |
| 83 | return ``-1.0``. |
| 84 | |
| 85 | .. versionadded:: 3.1 |
| 86 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 87 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 88 | .. c:function:: char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype) |
Eric Smith | cc32a11 | 2009-04-26 21:35:14 +0000 | [diff] [blame] | 89 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 90 | Convert a :c:type:`double` *val* to a string using supplied |
Eric Smith | cc32a11 | 2009-04-26 21:35:14 +0000 | [diff] [blame] | 91 | *format_code*, *precision*, and *flags*. |
| 92 | |
Eric Smith | 6337622 | 2009-05-05 14:04:18 +0000 | [diff] [blame] | 93 | *format_code* must be one of ``'e'``, ``'E'``, ``'f'``, ``'F'``, |
| 94 | ``'g'``, ``'G'`` or ``'r'``. For ``'r'``, the supplied *precision* |
| 95 | must be 0 and is ignored. The ``'r'`` format code specifies the |
| 96 | standard :func:`repr` format. |
Eric Smith | cc32a11 | 2009-04-26 21:35:14 +0000 | [diff] [blame] | 97 | |
| 98 | *flags* can be zero or more of the values *Py_DTSF_SIGN*, |
| 99 | *Py_DTSF_ADD_DOT_0*, or *Py_DTSF_ALT*, or-ed together: |
| 100 | |
| 101 | * *Py_DTSF_SIGN* means to always precede the returned string with a sign |
| 102 | character, even if *val* is non-negative. |
| 103 | |
| 104 | * *Py_DTSF_ADD_DOT_0* means to ensure that the returned string will not look |
| 105 | like an integer. |
| 106 | |
| 107 | * *Py_DTSF_ALT* means to apply "alternate" formatting rules. See the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 108 | documentation for the :c:func:`PyOS_snprintf` ``'#'`` specifier for |
Eric Smith | cc32a11 | 2009-04-26 21:35:14 +0000 | [diff] [blame] | 109 | details. |
| 110 | |
| 111 | If *ptype* is non-NULL, then the value it points to will be set to one of |
| 112 | *Py_DTST_FINITE*, *Py_DTST_INFINITE*, or *Py_DTST_NAN*, signifying that |
| 113 | *val* is a finite number, an infinite number, or not a number, respectively. |
| 114 | |
| 115 | The return value is a pointer to *buffer* with the converted string or |
| 116 | *NULL* if the conversion failed. The caller is responsible for freeing the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 117 | returned string by calling :c:func:`PyMem_Free`. |
Eric Smith | cc32a11 | 2009-04-26 21:35:14 +0000 | [diff] [blame] | 118 | |
| 119 | .. versionadded:: 3.1 |
| 120 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 121 | |
Eli Bendersky | 0813168 | 2012-06-03 08:07:47 +0300 | [diff] [blame] | 122 | .. c:function:: int PyOS_stricmp(char *s1, char *s2) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 123 | |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 124 | Case insensitive comparison of strings. The function works almost |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 125 | identically to :c:func:`strcmp` except that it ignores the case. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 126 | |
| 127 | |
Eli Bendersky | 0813168 | 2012-06-03 08:07:47 +0300 | [diff] [blame] | 128 | .. c:function:: int PyOS_strnicmp(char *s1, char *s2, Py_ssize_t size) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 129 | |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 130 | Case insensitive comparison of strings. The function works almost |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 131 | identically to :c:func:`strncmp` except that it ignores the case. |