Mr.Combet Webshell 🔥

Edit File Name : conversion.html

<!DOCTYPE html>

<title>String conversion and formatting &#8212; Python 3.12.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
 
 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />
 <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=bb723527" />
 <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" />
 
 <script src="../_static/documentation_options.js?v=2c828074"></script>
 <script src="../_static/doctools.js?v=888ff710"></script>
 <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
 
 <script src="../_static/sidebar.js"></script>
 
 <link rel="search" type="application/opensearchdescription+xml"
 title="Search within Python 3.12.3 documentation"
 href="../_static/opensearch.xml"/>
 <link rel="author" title="About these documents" href="../about.html" />
 <link rel="index" title="Index" href="../genindex.html" />
 <link rel="search" title="Search" href="../search.html" />
 <link rel="copyright" title="Copyright" href="../copyright.html" />
 <link rel="next" title="PyHash API" href="hash.html" />
 <link rel="prev" title="Parsing arguments and building values" href="arg.html" />
 <link rel="canonical" href="https://docs.python.org/3/c-api/conversion.html" />

</head>
<body>
<div class="mobile-nav">
 <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
 aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
 <nav class="nav-content" role="navigation">
 <label for="menuToggler" class="toggler__label">
 
 </label>
 
 <a href="https://www.python.org/" class="nav-logo">
 <img src="../_static/py.svg" alt="Python logo"/>
 </a>
 
 <form role="search" class="search" action="../search.html" method="get">
 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
 <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
 </svg>
 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />
 <input type="submit" value="Go"/>
 </form>
 
 </nav>
 <div class="menu-wrapper">
 <nav class="menu" role="navigation" aria-label="main navigation">
 <div class="language_switcher_placeholder"></div>
 
<label class="theme-selector-label">
 Theme
 <select class="theme-selector" oninput="activateTheme(this.value)">
 <option value="auto" selected>Auto</option>
 <option value="light">Light</option>
 <option value="dark">Dark</option>
 </select>
</label>
 <div>
 <h4>Previous topic</h4>
 <a href="arg.html"
 title="previous chapter">Parsing arguments and building values</a>
 </div>
 <div>
 <h4>Next topic</h4>
 <a href="hash.html"
 title="next chapter">PyHash API</a>
 </div>
 <div role="note" aria-label="source link">
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="../bugs.html">Report a Bug</a></li>
 <li>
 <a href="https://github.com/python/cpython/blob/main/Doc/c-api/conversion.rst"
 rel="nofollow">Show Source
 </a>
 </li>
 </ul>
 </div>
 </nav>
 </div>
</div>

<div class="related" role="navigation" aria-label="related navigation">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="../genindex.html" title="General Index"
 accesskey="I">index</a></li>
 <li class="right" >
 <a href="../py-modindex.html" title="Python Module Index"
 >modules</a> |</li>
 <li class="right" >
 <a href="hash.html" title="PyHash API"
 accesskey="N">next</a> |</li>
 <li class="right" >
 <a href="arg.html" title="Parsing arguments and building values"
 accesskey="P">previous</a> |</li>

<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
 <li><a href="https://www.python.org/">Python</a> &#187;</li>
 <li class="switchers">
 <div class="language_switcher_placeholder"></div>
 <div class="version_switcher_placeholder"></div>
 </li>
 <li>
 
 </li>
 <li id="cpython-language-and-version">
 <a href="../index.html">3.12.3 Documentation</a> &#187;
 </li>

<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> &#187;</li>
 <li class="nav-item nav-item-2"><a href="utilities.html" accesskey="U">Utilities</a> &#187;</li>
 <li class="nav-item nav-item-this"><a href="">String conversion and formatting</a></li>
 <li class="right">

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body" role="main">
 
 <section id="string-conversion-and-formatting">
<h1>String conversion and formatting<a class="headerlink" href="#string-conversion-and-formatting" title="Link to this heading">¶</a></h1>
Functions for number conversion and formatted string output.
<dl class="c function">
<dt class="sig sig-object c" id="c.PyOS_snprintf">
int PyOS_snprintf(char *str, size_t size, const char *format, ...)<a class="headerlink" href="#c.PyOS_snprintf" title="Link to this definition">¶</a> </dt>
<dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Output not more than size bytes to str according to the format string
format and the extra arguments. See the Unix man page <a class="manpage reference external" href="https://manpages.debian.org/snprintf(3)">snprintf(3)</a>.
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.PyOS_vsnprintf">
int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)<a class="headerlink" href="#c.PyOS_vsnprintf" title="Link to this definition">¶</a> </dt>
<dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Output not more than size bytes to str according to the format string
format and the variable argument list va. Unix man page
<a class="manpage reference external" href="https://manpages.debian.org/vsnprintf(3)">vsnprintf(3)</a>.
</dd></dl>

<a class="reference internal" href="#c.PyOS_snprintf" title="PyOS_snprintf"><code class="xref c c-func docutils literal notranslate">PyOS_snprintf()</code></a> and <a class="reference internal" href="#c.PyOS_vsnprintf" title="PyOS_vsnprintf"><code class="xref c c-func docutils literal notranslate">PyOS_vsnprintf()</code></a> wrap the Standard C library
functions <code class="xref c c-func docutils literal notranslate">snprintf()</code> and <code class="xref c c-func docutils literal notranslate">vsnprintf()</code>. Their purpose is to
guarantee consistent behavior in corner cases, which the Standard C functions do
not.
The wrappers ensure that <code class="docutils literal notranslate">str[size-1]</code> is always <code class="docutils literal notranslate">'\0'</code> upon return. They
never write more than size bytes (including the trailing <code class="docutils literal notranslate">'\0'</code>) into str.
Both functions require that <code class="docutils literal notranslate">str != NULL</code>, <code class="docutils literal notranslate">size &gt; 0</code>, <code class="docutils literal notranslate">format != NULL</code>
and <code class="docutils literal notranslate">size &lt; INT_MAX</code>. Note that this means there is no equivalent to the C99
<code class="docutils literal notranslate">n = snprintf(NULL, 0, ...)</code> which would determine the necessary buffer size.
The return value (rv) for these functions should be interpreted as follows:
<ul class="simple">
<li>When <code class="docutils literal notranslate">0 &lt;= rv &lt; size</code>, the output conversion was successful and rv
characters were written to str (excluding the trailing <code class="docutils literal notranslate">'\0'</code> byte at
<code class="docutils literal notranslate">str[rv]</code>).</li>
<li>When <code class="docutils literal notranslate">rv &gt;= size</code>, the output conversion was truncated and a buffer with
<code class="docutils literal notranslate">rv + 1</code> bytes would have been needed to succeed. <code class="docutils literal notranslate">str[size-1]</code> is <code class="docutils literal notranslate">'\0'</code>
in this case.</li>
<li>When <code class="docutils literal notranslate">rv &lt; 0</code>, “something bad happened.” <code class="docutils literal notranslate">str[size-1]</code> is <code class="docutils literal notranslate">'\0'</code> in
this case too, but the rest of str is undefined. The exact cause of the error
depends on the underlying platform.</li>
</ul>
The following functions provide locale-independent string to number conversions.
<dl class="c function">
<dt class="sig sig-object c" id="c.PyOS_strtoul">
unsigned long PyOS_strtoul(const char *str, char **ptr, int base)<a class="headerlink" href="#c.PyOS_strtoul" title="Link to this definition">¶</a> </dt>
<dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Convert the initial part of the string in <code class="docutils literal notranslate">str</code> to an unsigned long value according to the given <code class="docutils literal notranslate">base</code>, which must be between <code class="docutils literal notranslate">2</code> and
<code class="docutils literal notranslate">36</code> inclusive, or be the special value <code class="docutils literal notranslate">0</code>.
Leading white space and case of characters are ignored. If <code class="docutils literal notranslate">base</code> is zero
it looks for a leading <code class="docutils literal notranslate">0b</code>, <code class="docutils literal notranslate">0o</code> or <code class="docutils literal notranslate">0x</code> to tell which base. If
these are absent it defaults to <code class="docutils literal notranslate">10</code>. Base must be 0 or between 2 and 36
(inclusive). If <code class="docutils literal notranslate">ptr</code> is non-<code class="docutils literal notranslate">NULL</code> it will contain a pointer to the
end of the scan.
If the converted value falls out of range of corresponding return type,
range error occurs (<code class="xref c c-data docutils literal notranslate">errno</code> is set to <code class="xref c c-macro docutils literal notranslate">ERANGE</code>) and
<code class="xref c c-macro docutils literal notranslate">ULONG_MAX</code> is returned. If no conversion can be performed, <code class="docutils literal notranslate">0</code>
is returned.
See also the Unix man page <a class="manpage reference external" href="https://manpages.debian.org/strtoul(3)">strtoul(3)</a>.
<div class="versionadded">
New in version 3.2.
</div>
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.PyOS_strtol">
long PyOS_strtol(const char *str, char **ptr, int base)<a class="headerlink" href="#c.PyOS_strtol" title="Link to this definition">¶</a> </dt>
<dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Convert the initial part of the string in <code class="docutils literal notranslate">str</code> to an long value
according to the given <code class="docutils literal notranslate">base</code>, which must be between <code class="docutils literal notranslate">2</code> and <code class="docutils literal notranslate">36</code>
inclusive, or be the special value <code class="docutils literal notranslate">0</code>.
Same as <a class="reference internal" href="#c.PyOS_strtoul" title="PyOS_strtoul"><code class="xref c c-func docutils literal notranslate">PyOS_strtoul()</code></a>, but return a long value instead
and <code class="xref c c-macro docutils literal notranslate">LONG_MAX</code> on overflows.
See also the Unix man page <a class="manpage reference external" href="https://manpages.debian.org/strtol(3)">strtol(3)</a>.
<div class="versionadded">
New in version 3.2.
</div>
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.PyOS_string_to_double">
double PyOS_string_to_double(const char *s, char **endptr, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *overflow_exception)<a class="headerlink" href="#c.PyOS_string_to_double" title="Link to this definition">¶</a> </dt>
<dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Convert a string <code class="docutils literal notranslate">s</code> to a double, 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.html#float" title="float"><code class="xref py py-func docutils literal notranslate">float()</code></a> constructor,
except that <code class="docutils literal notranslate">s</code> must not have leading or trailing whitespace.
The conversion is independent of the current locale.
If <code class="docutils literal notranslate">endptr</code> is <code class="docutils literal notranslate">NULL</code>, convert the whole string. Raise
<a class="reference internal" href="../library/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate">ValueError</code></a> and return <code class="docutils literal notranslate">-1.0</code> if the string is not a valid
representation of a floating-point number.
If endptr is not <code class="docutils literal notranslate">NULL</code>, convert as much of the string as
possible and set <code class="docutils literal notranslate">*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 class="docutils literal notranslate">*endptr</code> to point
to the beginning of the string, raise ValueError, and return
<code class="docutils literal notranslate">-1.0</code>.
If <code class="docutils literal notranslate">s</code> represents a value that is too large to store in a float
(for example, <code class="docutils literal notranslate">&quot;1e500&quot;</code> is such a string on many platforms) then
if <code class="docutils literal notranslate">overflow_exception</code> is <code class="docutils literal notranslate">NULL</code> return <code class="docutils literal notranslate">Py_HUGE_VAL</code> (with
an appropriate sign) and don’t set any exception. Otherwise,
<code class="docutils literal notranslate">overflow_exception</code> must point to a Python exception object;
raise that exception and return <code class="docutils literal notranslate">-1.0</code>. In both cases, set
<code class="docutils literal notranslate">*endptr</code> 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 <code class="docutils literal notranslate">-1.0</code>.
<div class="versionadded">
New in version 3.1.
</div>
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.PyOS_double_to_string">
char *PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)<a class="headerlink" href="#c.PyOS_double_to_string" title="Link to this definition">¶</a> </dt>
<dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Convert a double val to a string using supplied
format_code, precision, and flags.
format_code must be one of <code class="docutils literal notranslate">'e'</code>, <code class="docutils literal notranslate">'E'</code>, <code class="docutils literal notranslate">'f'</code>, <code class="docutils literal notranslate">'F'</code>,
<code class="docutils literal notranslate">'g'</code>, <code class="docutils literal notranslate">'G'</code> or <code class="docutils literal notranslate">'r'</code>. For <code class="docutils literal notranslate">'r'</code>, the supplied precision
must be 0 and is ignored. The <code class="docutils literal notranslate">'r'</code> format code specifies the
standard <a class="reference internal" href="../library/functions.html#repr" title="repr"><code class="xref py py-func docutils literal notranslate">repr()</code></a> format.
flags can be zero or more of the values <code class="docutils literal notranslate">Py_DTSF_SIGN</code>,
<code class="docutils literal notranslate">Py_DTSF_ADD_DOT_0</code>, or <code class="docutils literal notranslate">Py_DTSF_ALT</code>, or-ed together:
<ul class="simple">
<li><code class="docutils literal notranslate">Py_DTSF_SIGN</code> means to always precede the returned string with a sign
character, even if val is non-negative.</li>
<li><code class="docutils literal notranslate">Py_DTSF_ADD_DOT_0</code> means to ensure that the returned string will not look
like an integer.</li>
<li><code class="docutils literal notranslate">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 class="xref c c-func docutils literal notranslate">PyOS_snprintf()</code></a> <code class="docutils literal notranslate">'#'</code> specifier for
details.</li>
</ul>
If ptype is non-<code class="docutils literal notranslate">NULL</code>, then the value it points to will be set to one of
<code class="docutils literal notranslate">Py_DTST_FINITE</code>, <code class="docutils literal notranslate">Py_DTST_INFINITE</code>, or <code class="docutils literal notranslate">Py_DTST_NAN</code>, signifying that
val is a finite number, an infinite number, or not a number, respectively.
The return value is a pointer to buffer with the converted string or
<code class="docutils literal notranslate">NULL</code> if the conversion failed. The caller is responsible for freeing the
returned string by calling <a class="reference internal" href="memory.html#c.PyMem_Free" title="PyMem_Free"><code class="xref c c-func docutils literal notranslate">PyMem_Free()</code></a>.
<div class="versionadded">
New in version 3.1.
</div>
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.PyOS_stricmp">
int PyOS_stricmp(const char *s1, const char *s2)<a class="headerlink" href="#c.PyOS_stricmp" title="Link to this definition">¶</a> </dt>
<dd>Case insensitive comparison of strings. The function works almost
identically to <code class="xref c c-func docutils literal notranslate">strcmp()</code> except that it ignores the case.
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.PyOS_strnicmp">
int PyOS_strnicmp(const char *s1, const char *s2, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t">Py_ssize_t</a> size)<a class="headerlink" href="#c.PyOS_strnicmp" title="Link to this definition">¶</a> </dt>
<dd>Case insensitive comparison of strings. The function works almost
identically to <code class="xref c c-func docutils literal notranslate">strncmp()</code> except that it ignores the case.
</dd></dl>

</section>

<div class="clearer"></div>
 </div>
 </div>
 </div>
 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
 <div class="sphinxsidebarwrapper">
 <div>
 <h4>Previous topic</h4>
 <a href="arg.html"
 title="previous chapter">Parsing arguments and building values</a>
 </div>
 <div>
 <h4>Next topic</h4>
 <a href="hash.html"
 title="next chapter">PyHash API</a>
 </div>
 <div role="note" aria-label="source link">
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="../bugs.html">Report a Bug</a></li>
 <li>
 <a href="https://github.com/python/cpython/blob/main/Doc/c-api/conversion.rst"
 rel="nofollow">Show Source
 </a>
 </li>
 </ul>
 </div>
 </div>
<div id="sidebarbutton" title="Collapse sidebar">
«
</div>

</div>
 <div class="clearer"></div>
 </div> 
 <div class="related" role="navigation" aria-label="related navigation">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="../genindex.html" title="General Index"
 >index</a></li>
 <li class="right" >
 <a href="../py-modindex.html" title="Python Module Index"
 >modules</a> |</li>
 <li class="right" >
 <a href="hash.html" title="PyHash API"
 >next</a> |</li>
 <li class="right" >
 <a href="arg.html" title="Parsing arguments and building values"
 >previous</a> |</li>

<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> &#187;</li>
 <li class="nav-item nav-item-2"><a href="utilities.html" >Utilities</a> &#187;</li>
 <li class="nav-item nav-item-this"><a href="">String conversion and formatting</a></li>
 <li class="right">

<div class="inline-search" role="search">
 <form class="inline-search" action="../search.html" method="get">
 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
 <input type="submit" value="Go" />
 </form>
 </div>
 |
 </li>
 <li class="right">
<label class="theme-selector-label">
 Theme
 <select class="theme-selector" oninput="activateTheme(this.value)">
 <option value="auto" selected>Auto</option>
 <option value="light">Light</option>
 <option value="dark">Dark</option>
 </select>
</label> |</li>
 
 </ul>
 </div> 
 <div class="footer">
 &copy; 
 <a href="../copyright.html">
 
 Copyright
 
 </a>
 2001-2024, Python Software Foundation.
 
 This page is licensed under the Python Software Foundation License Version 2.
 
 Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
 
 
 See <a href="/license.html">History and License</a> for more information.

The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
 
 
 Last updated on Apr 09, 2024 (13:47 UTC).
 
 <a href="/bugs.html">Found a bug</a>?

Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.
 </div>

</body>
</html>