/
usr
/
share
/
doc
/
python2-docs
/
html
/
c-api
/
/usr/share/doc/python2-docs/html/c-api
mkdir
upload
Name
Size
Mode
Actions
abstract.html
7475
0644
edit
dl
rm
allocation.html
18783
0644
edit
dl
rm
arg.html
61746
0644
edit
dl
rm
bool.html
10025
0644
edit
dl
rm
buffer.html
48743
0644
edit
dl
rm
bytearray.html
14205
0644
edit
dl
rm
capsule.html
20971
0644
edit
dl
rm
cell.html
11194
0644
edit
dl
rm
class.html
11417
0644
edit
dl
rm
cobject.html
12082
0644
edit
dl
rm
code.html
11664
0644
edit
dl
rm
codec.html
21321
0644
edit
dl
rm
complex.html
20897
0644
edit
dl
rm
concrete.html
15868
0644
edit
dl
rm
conversion.html
23406
0644
edit
dl
rm
datetime.html
26469
0644
edit
dl
rm
descriptor.html
12035
0644
edit
dl
rm
dict.html
33222
0644
edit
dl
rm
exceptions.html
92999
0644
edit
dl
rm
file.html
24313
0644
edit
dl
rm
float.html
17526
0644
edit
dl
rm
function.html
14312
0644
edit
dl
rm
gcsupport.html
23878
0644
edit
dl
rm
gen.html
8524
0644
edit
dl
rm
import.html
35730
0644
edit
dl
rm
index.html
13463
0644
edit
dl
rm
init.html
107309
0644
edit
dl
rm
int.html
20528
0644
edit
dl
rm
intro.html
66178
0644
edit
dl
rm
iter.html
10162
0644
edit
dl
rm
iterator.html
11830
0644
edit
dl
rm
list.html
24670
0644
edit
dl
rm
long.html
33667
0644
edit
dl
rm
mapping.html
16026
0644
edit
dl
rm
marshal.html
16257
0644
edit
dl
rm
memory.html
32963
0644
edit
dl
rm
method.html
13606
0644
edit
dl
rm
module.html
17150
0644
edit
dl
rm
none.html
8027
0644
edit
dl
rm
number.html
48578
0644
edit
dl
rm
objbuffer.html
12307
0644
edit
dl
rm
object.html
59828
0644
edit
dl
rm
objimpl.html
7249
0644
edit
dl
rm
refcounting.html
12844
0644
edit
dl
rm
reflection.html
10691
0644
edit
dl
rm
sequence.html
32324
0644
edit
dl
rm
set.html
31735
0644
edit
dl
rm
slice.html
13587
0644
edit
dl
rm
string.html
36740
0644
edit
dl
rm
structures.html
39419
0644
edit
dl
rm
sys.html
21239
0644
edit
dl
rm
tuple.html
21489
0644
edit
dl
rm
type.html
14996
0644
edit
dl
rm
typeobj.html
181174
0644
edit
dl
rm
unicode.html
118633
0644
edit
dl
rm
utilities.html
7588
0644
edit
dl
rm
veryhigh.html
44510
0644
edit
dl
rm
weakref.html
13603
0644
edit
dl
rm
Edit:
/usr/share/doc/python2-docs/html/c-api/conversion.html
(23406B)
<!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 2.7.16 documentation</title> <link rel="stylesheet" href="../_static/classic.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 2.7.16 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/2/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">Python 2.7.16 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> </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 2.7.</span></p> </div> </dd></dl> <dl class="function"> <dt id="c.PyOS_ascii_strtod"> double <code class="descname">PyOS_ascii_strtod</code><span class="sig-paren">(</span>const char<em> *nptr</em>, char<em> **endptr</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_ascii_strtod" title="Permalink to this definition">¶</a></dt> <dd><p>Convert a string to a <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code>. This function behaves like the Standard C function <code class="xref c c-func docutils literal notranslate"><span class="pre">strtod()</span></code> does in the C locale. It does this without changing the current locale, since that would not be thread-safe.</p> <p><a class="reference internal" href="#c.PyOS_ascii_strtod" title="PyOS_ascii_strtod"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyOS_ascii_strtod()</span></code></a> should typically be used for reading configuration files or other non-user input that should be locale independent.</p> <p>See the Unix man page <em class="manpage">strtod(2)</em> for details.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.4.</span></p> </div> <div class="deprecated"> <p><span class="versionmodified">Deprecated since version 2.7: </span>Use <a class="reference internal" href="#c.PyOS_string_to_double" title="PyOS_string_to_double"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyOS_string_to_double()</span></code></a> instead.</p> </div> </dd></dl> <dl class="function"> <dt id="c.PyOS_ascii_formatd"> char* <code class="descname">PyOS_ascii_formatd</code><span class="sig-paren">(</span>char<em> *buffer</em>, size_t<em> buf_len</em>, const char<em> *format</em>, double<em> d</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_ascii_formatd" 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> to a string using the <code class="docutils literal notranslate"><span class="pre">'.'</span></code> as the decimal separator. <em>format</em> is a <code class="xref c c-func docutils literal notranslate"><span class="pre">printf()</span></code>-style format string specifying the number format. Allowed conversion characters are <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> and <code class="docutils literal notranslate"><span class="pre">'G'</span></code>.</p> <p>The return value is a pointer to <em>buffer</em> with the converted string or NULL if the conversion failed.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.4.</span></p> </div> <div class="deprecated"> <p><span class="versionmodified">Deprecated since version 2.7: </span>This function is removed in Python 2.7 and 3.1. Use <code class="xref py py-func docutils literal notranslate"><span class="pre">PyOS_double_to_string()</span></code> instead.</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 <code class="docutils literal notranslate"><span class="pre">0</span></code> 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 2.7.</span></p> </div> </dd></dl> <dl class="function"> <dt id="c.PyOS_ascii_atof"> double <code class="descname">PyOS_ascii_atof</code><span class="sig-paren">(</span>const char<em> *nptr</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_ascii_atof" title="Permalink to this definition">¶</a></dt> <dd><p>Convert a string to a <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code> in a locale-independent way.</p> <p>See the Unix man page <em class="manpage">atof(2)</em> for details.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.4.</span></p> </div> <div class="deprecated"> <p><span class="versionmodified">Deprecated since version 3.1: </span>Use <a class="reference internal" href="#c.PyOS_string_to_double" title="PyOS_string_to_double"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyOS_string_to_double()</span></code></a> instead.</p> </div> </dd></dl> <dl class="function"> <dt id="c.PyOS_stricmp"> char* <code class="descname">PyOS_stricmp</code><span class="sig-paren">(</span>char<em> *s1</em>, 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> <div class="versionadded"> <p><span class="versionmodified">New in version 2.6.</span></p> </div> </dd></dl> <dl class="function"> <dt id="c.PyOS_strnicmp"> char* <code class="descname">PyOS_strnicmp</code><span class="sig-paren">(</span>char<em> *s1</em>, 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> <div class="versionadded"> <p><span class="versionmodified">New in version 2.6.</span></p> </div> </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="../_sources/c-api/conversion.rst.txt" rel="nofollow">Show Source</a></li> </ul> </div> <div id="searchbox" style="display: none" role="search"> <h3>Quick search</h3> <div class="searchformwrapper"> <form class="search" action="../search.html" method="get"> <input 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> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </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">Python 2.7.16 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> </ul> </div> <div class="footer"> © <a href="../copyright.html">Copyright</a> 1990-2019, 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 Mar 27, 2019. <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