diff options
Diffstat (limited to 'devdocs/python~3.12/c-api%2Fconversion.html')
| -rw-r--r-- | devdocs/python~3.12/c-api%2Fconversion.html | 27 |
1 files changed, 27 insertions, 0 deletions
diff --git a/devdocs/python~3.12/c-api%2Fconversion.html b/devdocs/python~3.12/c-api%2Fconversion.html new file mode 100644 index 00000000..2d974ed8 --- /dev/null +++ b/devdocs/python~3.12/c-api%2Fconversion.html @@ -0,0 +1,27 @@ + <span id="string-conversion"></span><h1>String conversion and formatting</h1> <p>Functions for number conversion and formatted string output.</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PyOS_snprintf"> +<code>int PyOS_snprintf(char *str, size_t size, const char *format, ...)</code> </dt> <dd> +<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Output not more than <em>size</em> bytes to <em>str</em> according to the format string <em>format</em> and the extra arguments. See the Unix man page <em class="manpage"><a class="manpage reference external" href="https://manpages.debian.org/snprintf(3)">snprintf(3)</a></em>.</p> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyOS_vsnprintf"> +<code>int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)</code> </dt> <dd> +<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Output not more than <em>size</em> bytes to <em>str</em> according to the format string <em>format</em> and the variable argument list <em>va</em>. Unix man page <em class="manpage"><a class="manpage reference external" href="https://manpages.debian.org/vsnprintf(3)">vsnprintf(3)</a></em>.</p> </dd> +</dl> <p><a class="reference internal" href="#c.PyOS_snprintf" title="PyOS_snprintf"><code>PyOS_snprintf()</code></a> and <a class="reference internal" href="#c.PyOS_vsnprintf" title="PyOS_vsnprintf"><code>PyOS_vsnprintf()</code></a> wrap the Standard C library functions <code>snprintf()</code> and <code>vsnprintf()</code>. Their purpose is to guarantee consistent behavior in corner cases, which the Standard C functions do not.</p> <p>The wrappers ensure that <code>str[size-1]</code> is always <code>'\0'</code> upon return. They never write more than <em>size</em> bytes (including the trailing <code>'\0'</code>) into str. Both functions require that <code>str != NULL</code>, <code>size > 0</code>, <code>format != NULL</code> and <code>size < INT_MAX</code>. Note that this means there is no equivalent to the C99 <code>n = snprintf(NULL, 0, ...)</code> which would determine the necessary buffer size.</p> <p>The return value (<em>rv</em>) for these functions should be interpreted as follows:</p> <ul class="simple"> <li>When <code>0 <= rv < size</code>, the output conversion was successful and <em>rv</em> characters were written to <em>str</em> (excluding the trailing <code>'\0'</code> byte at <code>str[rv]</code>).</li> <li>When <code>rv >= size</code>, the output conversion was truncated and a buffer with <code>rv + 1</code> bytes would have been needed to succeed. <code>str[size-1]</code> is <code>'\0'</code> in this case.</li> <li>When <code>rv < 0</code>, “something bad happened.” <code>str[size-1]</code> is <code>'\0'</code> in this case too, but the rest of <em>str</em> is undefined. The exact cause of the error depends on the underlying platform.</li> </ul> <p>The following functions provide locale-independent string to number conversions.</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PyOS_string_to_double"> +<code>double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)</code> </dt> <dd> +<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Convert a string <code>s</code> to a <span class="c-expr sig sig-inline c"><span class="kt">double</span></span>, raising a Python exception on failure. The set of accepted strings corresponds to the set of strings accepted by Python’s <a class="reference internal" href="../library/functions#float" title="float"><code>float()</code></a> constructor, except that <code>s</code> must not have leading or trailing whitespace. The conversion is independent of the current locale.</p> <p>If <code>endptr</code> is <code>NULL</code>, convert the whole string. Raise <a class="reference internal" href="../library/exceptions#ValueError" title="ValueError"><code>ValueError</code></a> and return <code>-1.0</code> if the string is not a valid representation of a floating-point number.</p> <p>If endptr is not <code>NULL</code>, convert as much of the string as possible and set <code>*endptr</code> to point to the first unconverted character. If no initial segment of the string is the valid representation of a floating-point number, set <code>*endptr</code> to point to the beginning of the string, raise ValueError, and return <code>-1.0</code>.</p> <p>If <code>s</code> represents a value that is too large to store in a float (for example, <code>"1e500"</code> is such a string on many platforms) then if <code>overflow_exception</code> is <code>NULL</code> return <code>Py_HUGE_VAL</code> (with an appropriate sign) and don’t set any exception. Otherwise, <code>overflow_exception</code> must point to a Python exception object; raise that exception and return <code>-1.0</code>. In both cases, set <code>*endptr</code> to point to the first character after the converted value.</p> <p>If any other error occurs during the conversion (for example an out-of-memory error), set the appropriate Python exception and return <code>-1.0</code>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.1.</span></p> </div> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyOS_double_to_string"> +<code>char *PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)</code> </dt> <dd> +<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Convert a <span class="c-expr sig sig-inline c"><span class="kt">double</span></span> <em>val</em> to a string using supplied <em>format_code</em>, <em>precision</em>, and <em>flags</em>.</p> <p><em>format_code</em> must be one of <code>'e'</code>, <code>'E'</code>, <code>'f'</code>, <code>'F'</code>, <code>'g'</code>, <code>'G'</code> or <code>'r'</code>. For <code>'r'</code>, the supplied <em>precision</em> must be 0 and is ignored. The <code>'r'</code> format code specifies the standard <a class="reference internal" href="../library/functions#repr" title="repr"><code>repr()</code></a> format.</p> <p><em>flags</em> can be zero or more of the values <code>Py_DTSF_SIGN</code>, <code>Py_DTSF_ADD_DOT_0</code>, or <code>Py_DTSF_ALT</code>, or-ed together:</p> <ul class="simple"> <li> +<code>Py_DTSF_SIGN</code> means to always precede the returned string with a sign character, even if <em>val</em> is non-negative.</li> <li> +<code>Py_DTSF_ADD_DOT_0</code> means to ensure that the returned string will not look like an integer.</li> <li> +<code>Py_DTSF_ALT</code> means to apply “alternate” formatting rules. See the documentation for the <a class="reference internal" href="#c.PyOS_snprintf" title="PyOS_snprintf"><code>PyOS_snprintf()</code></a> <code>'#'</code> specifier for details.</li> </ul> <p>If <em>ptype</em> is non-<code>NULL</code>, then the value it points to will be set to one of <code>Py_DTST_FINITE</code>, <code>Py_DTST_INFINITE</code>, or <code>Py_DTST_NAN</code>, signifying that <em>val</em> is a finite number, an infinite number, or not a number, respectively.</p> <p>The return value is a pointer to <em>buffer</em> with the converted string or <code>NULL</code> if the conversion failed. The caller is responsible for freeing the returned string by calling <a class="reference internal" href="memory#c.PyMem_Free" title="PyMem_Free"><code>PyMem_Free()</code></a>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.1.</span></p> </div> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyOS_stricmp"> +<code>int PyOS_stricmp(const char *s1, const char *s2)</code> </dt> <dd> +<p>Case insensitive comparison of strings. The function works almost identically to <code>strcmp()</code> except that it ignores the case.</p> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyOS_strnicmp"> +<code>int PyOS_strnicmp(const char *s1, const char *s2, Py_ssize_t size)</code> </dt> <dd> +<p>Case insensitive comparison of strings. The function works almost identically to <code>strncmp()</code> except that it ignores the case.</p> </dd> +</dl> <div class="_attribution"> + <p class="_attribution-p"> + © 2001–2023 Python Software Foundation<br>Licensed under the PSF License.<br> + <a href="https://docs.python.org/3.12/c-api/conversion.html" class="_attribution-link">https://docs.python.org/3.12/c-api/conversion.html</a> + </p> +</div> |