/
usr
/
share
/
doc
/
python3-docs
/
html
/
c-api
/
/usr/share/doc/python3-docs/html/c-api
mkdir
upload
Name
Size
Mode
Actions
abstract.html
9716
0644
edit
dl
rm
allocation.html
14728
0644
edit
dl
rm
apiabiversion.html
10681
0644
edit
dl
rm
arg.html
89735
0644
edit
dl
rm
bool.html
10333
0644
edit
dl
rm
buffer.html
64150
0644
edit
dl
rm
bytearray.html
15098
0644
edit
dl
rm
bytes.html
25487
0644
edit
dl
rm
capsule.html
21699
0644
edit
dl
rm
cell.html
11942
0644
edit
dl
rm
code.html
12388
0644
edit
dl
rm
codec.html
22641
0644
edit
dl
rm
complex.html
21268
0644
edit
dl
rm
concrete.html
17602
0644
edit
dl
rm
conversion.html
19525
0644
edit
dl
rm
coro.html
9452
0644
edit
dl
rm
datetime.html
26513
0644
edit
dl
rm
descriptor.html
11959
0644
edit
dl
rm
dict.html
35244
0644
edit
dl
rm
exceptions.html
128414
0644
edit
dl
rm
file.html
14544
0644
edit
dl
rm
float.html
15155
0644
edit
dl
rm
function.html
18215
0644
edit
dl
rm
gcsupport.html
23787
0644
edit
dl
rm
gen.html
10939
0644
edit
dl
rm
import.html
42920
0644
edit
dl
rm
index.html
15759
0644
edit
dl
rm
init.html
116862
0644
edit
dl
rm
intro.html
68136
0644
edit
dl
rm
iter.html
10062
0644
edit
dl
rm
iterator.html
11928
0644
edit
dl
rm
list.html
22504
0644
edit
dl
rm
long.html
44839
0644
edit
dl
rm
mapping.html
17524
0644
edit
dl
rm
marshal.html
16935
0644
edit
dl
rm
memory.html
58531
0644
edit
dl
rm
memoryview.html
13510
0644
edit
dl
rm
method.html
17051
0644
edit
dl
rm
module.html
56821
0644
edit
dl
rm
none.html
8755
0644
edit
dl
rm
number.html
44801
0644
edit
dl
rm
objbuffer.html
12624
0644
edit
dl
rm
object.html
60861
0644
edit
dl
rm
objimpl.html
8087
0644
edit
dl
rm
refcounting.html
13454
0644
edit
dl
rm
reflection.html
11189
0644
edit
dl
rm
sequence.html
28925
0644
edit
dl
rm
set.html
31197
0644
edit
dl
rm
slice.html
13459
0644
edit
dl
rm
stable.html
9193
0644
edit
dl
rm
structures.html
37151
0644
edit
dl
rm
sys.html
35639
0644
edit
dl
rm
tuple.html
30022
0644
edit
dl
rm
type.html
18813
0644
edit
dl
rm
typeobj.html
164125
0644
edit
dl
rm
unicode.html
188046
0644
edit
dl
rm
utilities.html
8966
0644
edit
dl
rm
veryhigh.html
54572
0644
edit
dl
rm
weakref.html
13615
0644
edit
dl
rm
Edit:
/usr/share/doc/python3-docs/html/c-api/conversion.html
(19525B)
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>String conversion and formatting — Python 3.6.7 documentation</title> <link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" /> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script> <script type="text/javascript" src="../_static/jquery.js"></script> <script type="text/javascript" src="../_static/underscore.js"></script> <script type="text/javascript" src="../_static/doctools.js"></script> <script type="text/javascript" src="../_static/sidebar.js"></script> <link rel="search" type="application/opensearchdescription+xml" title="Search within Python 3.6.7 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="Reflection" href="reflection.html" /> <link rel="prev" title="Parsing arguments and building values" href="arg.html" /> <link rel="shortcut icon" type="image/png" href="../_static/py.png" /> <link rel="canonical" href="https://docs.python.org/3/c-api/conversion.html" /> <script type="text/javascript" src="../_static/copybutton.js"></script> </head><body> <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="reflection.html" title="Reflection" 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.png" alt="" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="https://www.python.org/">Python</a> »</li> <li> <a href="../index.html">3.6.7 Documentation</a> » </li> <li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li> <li class="nav-item nav-item-2"><a href="utilities.html" accesskey="U">Utilities</a> »</li> <li class="right"> <div class="inline-search" style="display: none" role="search"> <form class="inline-search" action="../search.html" method="get"> <input placeholder="Quick search" type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> <script type="text/javascript">$('.inline-search').show(0);</script> | </li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body" role="main"> <div class="section" id="string-conversion-and-formatting"> <span id="string-conversion"></span><h1>String conversion and formatting<a class="headerlink" href="#string-conversion-and-formatting" title="Permalink to this headline">¶</a></h1> <p>Functions for number conversion and formatted string output.</p> <dl class="function"> <dt id="c.PyOS_snprintf"> int <code class="descname">PyOS_snprintf</code><span class="sig-paren">(</span>char<em> *str</em>, size_t<em> size</em>, const char<em> *format</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_snprintf" title="Permalink to this definition">¶</a></dt> <dd><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">snprintf(2)</em>.</p> </dd></dl> <dl class="function"> <dt id="c.PyOS_vsnprintf"> int <code class="descname">PyOS_vsnprintf</code><span class="sig-paren">(</span>char<em> *str</em>, size_t<em> size</em>, const char<em> *format</em>, va_list<em> va</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_vsnprintf" title="Permalink to this definition">¶</a></dt> <dd><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">vsnprintf(2)</em>.</p> </dd></dl> <p><a class="reference internal" href="#c.PyOS_snprintf" title="PyOS_snprintf"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyOS_snprintf()</span></code></a> and <a class="reference internal" href="#c.PyOS_vsnprintf" title="PyOS_vsnprintf"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyOS_vsnprintf()</span></code></a> wrap the Standard C library functions <code class="xref c c-func docutils literal notranslate"><span class="pre">snprintf()</span></code> and <code class="xref c c-func docutils literal notranslate"><span class="pre">vsnprintf()</span></code>. Their purpose is to guarantee consistent behavior in corner cases, which the Standard C functions do not.</p> <p>The wrappers ensure that <em>str*[*size</em>-1] is always <code class="docutils literal notranslate"><span class="pre">'\0'</span></code> upon return. They never write more than <em>size</em> bytes (including the trailing <code class="docutils literal notranslate"><span class="pre">'\0'</span></code>) into str. Both functions require that <code class="docutils literal notranslate"><span class="pre">str</span> <span class="pre">!=</span> <span class="pre">NULL</span></code>, <code class="docutils literal notranslate"><span class="pre">size</span> <span class="pre">></span> <span class="pre">0</span></code> and <code class="docutils literal notranslate"><span class="pre">format</span> <span class="pre">!=</span> <span class="pre">NULL</span></code>.</p> <p>If the platform doesn’t have <code class="xref c c-func docutils literal notranslate"><span class="pre">vsnprintf()</span></code> and the buffer size needed to avoid truncation exceeds <em>size</em> by more than 512 bytes, Python aborts with a <em>Py_FatalError</em>.</p> <p>The return value (<em>rv</em>) for these functions should be interpreted as follows:</p> <ul class="simple"> <li>When <code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre"><=</span> <span class="pre">rv</span> <span class="pre"><</span> <span class="pre">size</span></code>, the output conversion was successful and <em>rv</em> characters were written to <em>str</em> (excluding the trailing <code class="docutils literal notranslate"><span class="pre">'\0'</span></code> byte at <em>str*[*rv</em>]).</li> <li>When <code class="docutils literal notranslate"><span class="pre">rv</span> <span class="pre">>=</span> <span class="pre">size</span></code>, the output conversion was truncated and a buffer with <code class="docutils literal notranslate"><span class="pre">rv</span> <span class="pre">+</span> <span class="pre">1</span></code> bytes would have been needed to succeed. <em>str*[*size</em>-1] is <code class="docutils literal notranslate"><span class="pre">'\0'</span></code> in this case.</li> <li>When <code class="docutils literal notranslate"><span class="pre">rv</span> <span class="pre"><</span> <span class="pre">0</span></code>, “something bad happened.” <em>str*[*size</em>-1] is <code class="docutils literal notranslate"><span class="pre">'\0'</span></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="function"> <dt id="c.PyOS_string_to_double"> double <code class="descname">PyOS_string_to_double</code><span class="sig-paren">(</span>const char<em> *s</em>, char<em> **endptr</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *overflow_exception</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_string_to_double" title="Permalink to this definition">¶</a></dt> <dd><p>Convert a string <code class="docutils literal notranslate"><span class="pre">s</span></code> to a <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code>, 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"><span class="pre">float()</span></code></a> constructor, except that <code class="docutils literal notranslate"><span class="pre">s</span></code> must not have leading or trailing whitespace. The conversion is independent of the current locale.</p> <p>If <code class="docutils literal notranslate"><span class="pre">endptr</span></code> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, convert the whole string. Raise ValueError and return <code class="docutils literal notranslate"><span class="pre">-1.0</span></code> if the string is not a valid representation of a floating-point number.</p> <p>If endptr is not <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, convert as much of the string as possible and set <code class="docutils literal notranslate"><span class="pre">*endptr</span></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"><span class="pre">*endptr</span></code> to point to the beginning of the string, raise ValueError, and return <code class="docutils literal notranslate"><span class="pre">-1.0</span></code>.</p> <p>If <code class="docutils literal notranslate"><span class="pre">s</span></code> represents a value that is too large to store in a float (for example, <code class="docutils literal notranslate"><span class="pre">"1e500"</span></code> is such a string on many platforms) then if <code class="docutils literal notranslate"><span class="pre">overflow_exception</span></code> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code> return <code class="docutils literal notranslate"><span class="pre">Py_HUGE_VAL</span></code> (with an appropriate sign) and don’t set any exception. Otherwise, <code class="docutils literal notranslate"><span class="pre">overflow_exception</span></code> must point to a Python exception object; raise that exception and return <code class="docutils literal notranslate"><span class="pre">-1.0</span></code>. In both cases, set <code class="docutils literal notranslate"><span class="pre">*endptr</span></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 class="docutils literal notranslate"><span class="pre">-1.0</span></code>.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 3.1.</span></p> </div> </dd></dl> <dl class="function"> <dt id="c.PyOS_double_to_string"> char* <code class="descname">PyOS_double_to_string</code><span class="sig-paren">(</span>double<em> val</em>, char<em> format_code</em>, int<em> precision</em>, int<em> flags</em>, int<em> *ptype</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_double_to_string" title="Permalink to this definition">¶</a></dt> <dd><p>Convert a <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code> <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 class="docutils literal notranslate"><span class="pre">'e'</span></code>, <code class="docutils literal notranslate"><span class="pre">'E'</span></code>, <code class="docutils literal notranslate"><span class="pre">'f'</span></code>, <code class="docutils literal notranslate"><span class="pre">'F'</span></code>, <code class="docutils literal notranslate"><span class="pre">'g'</span></code>, <code class="docutils literal notranslate"><span class="pre">'G'</span></code> or <code class="docutils literal notranslate"><span class="pre">'r'</span></code>. For <code class="docutils literal notranslate"><span class="pre">'r'</span></code>, the supplied <em>precision</em> must be 0 and is ignored. The <code class="docutils literal notranslate"><span class="pre">'r'</span></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"><span class="pre">repr()</span></code></a> format.</p> <p><em>flags</em> can be zero or more of the values <em>Py_DTSF_SIGN</em>, <em>Py_DTSF_ADD_DOT_0</em>, or <em>Py_DTSF_ALT</em>, or-ed together:</p> <ul class="simple"> <li><em>Py_DTSF_SIGN</em> means to always precede the returned string with a sign character, even if <em>val</em> is non-negative.</li> <li><em>Py_DTSF_ADD_DOT_0</em> means to ensure that the returned string will not look like an integer.</li> <li><em>Py_DTSF_ALT</em> 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"><span class="pre">PyOS_snprintf()</span></code></a> <code class="docutils literal notranslate"><span class="pre">'#'</span></code> specifier for details.</li> </ul> <p>If <em>ptype</em> is non-NULL, then the value it points to will be set to one of <em>Py_DTST_FINITE</em>, <em>Py_DTST_INFINITE</em>, or <em>Py_DTST_NAN</em>, 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 <em>NULL</em> 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"><span class="pre">PyMem_Free()</span></code></a>.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 3.1.</span></p> </div> </dd></dl> <dl class="function"> <dt id="c.PyOS_stricmp"> int <code class="descname">PyOS_stricmp</code><span class="sig-paren">(</span>const char<em> *s1</em>, const char<em> *s2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_stricmp" title="Permalink to this definition">¶</a></dt> <dd><p>Case insensitive comparison of strings. The function works almost identically to <code class="xref c c-func docutils literal notranslate"><span class="pre">strcmp()</span></code> except that it ignores the case.</p> </dd></dl> <dl class="function"> <dt id="c.PyOS_strnicmp"> int <code class="descname">PyOS_strnicmp</code><span class="sig-paren">(</span>const char<em> *s1</em>, const char<em> *s2</em>, Py_ssize_t <em> size</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_strnicmp" title="Permalink to this definition">¶</a></dt> <dd><p>Case insensitive comparison of strings. The function works almost identically to <code class="xref c c-func docutils literal notranslate"><span class="pre">strncmp()</span></code> except that it ignores the case.</p> </dd></dl> </div> </div> </div> </div> <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebarwrapper"> <h4>Previous topic</h4> <p class="topless"><a href="arg.html" title="previous chapter">Parsing arguments and building values</a></p> <h4>Next topic</h4> <p class="topless"><a href="reflection.html" title="next chapter">Reflection</a></p> <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/3.6/Doc/c-api/conversion.rst" rel="nofollow">Show Source </a> </li> </ul> </div> </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="reflection.html" title="Reflection" >next</a> |</li> <li class="right" > <a href="arg.html" title="Parsing arguments and building values" >previous</a> |</li> <li><img src="../_static/py.png" alt="" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="https://www.python.org/">Python</a> »</li> <li> <a href="../index.html">3.6.7 Documentation</a> » </li> <li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li> <li class="nav-item nav-item-2"><a href="utilities.html" >Utilities</a> »</li> <li class="right"> <div class="inline-search" style="display: none" role="search"> <form class="inline-search" action="../search.html" method="get"> <input placeholder="Quick search" type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> <script type="text/javascript">$('.inline-search').show(0);</script> | </li> </ul> </div> <div class="footer"> © <a href="../copyright.html">Copyright</a> 2001-2023, Python Software Foundation. <br /> The Python Software Foundation is a non-profit corporation. <a href="https://www.python.org/psf/donations/">Please donate.</a> <br /> Last updated on Dec 18, 2023. <a href="../bugs.html">Found a bug</a>? <br /> Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6. </div> </body> </html>
Save
cmd:
run