Files
hustoj/web/python-docs/c-api/conversion.html
2025-03-09 17:10:56 +08:00

320 lines
24 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="zh_CN">
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>字符串转换与格式化 &#8212; Python 3.8.20 文档</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script src="../_static/translations.js"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="在 Python 3.8.20 文档 中搜索"
href="../_static/opensearch.xml"/>
<link rel="author" title="关于这些文档" href="../about.html" />
<link rel="index" title="索引" href="../genindex.html" />
<link rel="search" title="搜索" href="../search.html" />
<link rel="copyright" title="版权所有" href="../copyright.html" />
<link rel="next" title="反射" href="reflection.html" />
<link rel="prev" title="解析参数并构建值变量" href="arg.html" />
<link rel="canonical" href="https://docs.python.org/3/c-api/conversion.html" />
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
</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" />
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<nav class="nav-content" role="navigation">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Logo"/>
</a>
<div class="version_switcher_placeholder"></div>
<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"
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" fill="#444"></path>
</svg>
<input type="text" name="q" aria-label="快速搜索"/>
<input type="submit" value="转向"/>
</form>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<h4>上一个主题</h4>
<p class="topless"><a href="arg.html"
title="上一章">解析参数并构建值变量</a></p>
<h4>下一个主题</h4>
<p class="topless"><a href="reflection.html"
title="下一章">反射</a></p>
<div role="note" aria-label="source link">
<h3>本页</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">报告 Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.8/Doc/c-api/conversion.rst"
rel="nofollow">显示源代码
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div id="outdated-warning" style="padding: .5em; text-align: center; background-color: #FFBABA; color: #6A0E0E;">
这个文档所针对的是一个已不再受支持的 Python 旧版本。
你应当升级版本,并阅读
<a href="/3/c-api/conversion.html"> Python 当前稳定版本的文档</a>.
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>导航</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="总目录"
accesskey="I">索引</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python 模块索引"
>模块</a> |</li>
<li class="right" >
<a href="reflection.html" title="反射"
accesskey="N">下一页</a> |</li>
<li class="right" >
<a href="arg.html" title="解析参数并构建值变量"
accesskey="P">上一页</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.8.20 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API 参考手册</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="utilities.html" accesskey="U">工具</a> &#187;</li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
<input type="submit" value="转向" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
|
</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="string-conversion-and-formatting">
<span id="string-conversion"></span><h1>字符串转换与格式化<a class="headerlink" href="#string-conversion-and-formatting" title="永久链接至标题"></a></h1>
<p>用于数字转换和格式化字符串输出的函数</p>
<dl class="function">
<dt id="c.PyOS_snprintf">
int <code class="sig-name 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="永久链接至目标"></a></dt>
<dd><p>根据格式字符串 <em>format</em> 和额外参数,输出不超过 <em>size</em> 个字节到 <em>str</em>。 参见 Unix 手册页面 <em class="manpage"><a class="manpage reference external" href="https://manpages.debian.org/snprintf(3)">snprintf(3)</a></em></p>
</dd></dl>
<dl class="function">
<dt id="c.PyOS_vsnprintf">
int <code class="sig-name 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="永久链接至目标"></a></dt>
<dd><p>根据格式字符串 <em>format</em> 和变量参数列表 <em>va</em>,输出不超过 <em>size</em> 个字节到 <em>str</em>。 参见 Unix 手册页面 <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 class="xref c c-func docutils literal notranslate"><span class="pre">PyOS_snprintf()</span></code></a><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> 包装 C 标准库函数 <code class="xref c c-func docutils literal notranslate"><span class="pre">snprintf()</span></code><code class="xref c c-func docutils literal notranslate"><span class="pre">vsnprintf()</span></code> 。它们的目的是保证在极端情况下的一致行为,而标准 C 的函数则不然。</p>
<p>包装器会确保 <code class="docutils literal notranslate"><span class="pre">str[size-1]</span></code> 在返回时始终为 <code class="docutils literal notranslate"><span class="pre">'\0'</span></code>。 它们从不写入超过 <em>size</em> 个字节 (包括末尾的 <code class="docutils literal notranslate"><span class="pre">'\0'</span></code>) 到字符串。 两个函数都要求 <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">&gt;</span> <span class="pre">0</span></code><code class="docutils literal notranslate"><span class="pre">format</span> <span class="pre">!=</span> <span class="pre">NULL</span></code></p>
<p>如果平台没有 <code class="xref c c-func docutils literal notranslate"><span class="pre">vsnprintf()</span></code> 而且缓冲区大小需要避免截断超出 <em>size</em> 512 字节以上Python 会以一个 <a class="reference internal" href="sys.html#c.Py_FatalError" title="Py_FatalError"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_FatalError()</span></code></a> 来中止。</p>
<p>这些函数的返回值( <em>rv</em> )应按照以下规则被解释:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre">&lt;=</span> <span class="pre">rv</span> <span class="pre">&lt;</span> <span class="pre">size</span></code> 时,输出转换即成功并将 <em>rv</em> 个字符写入到 <em>str</em> (不包括末尾 <code class="docutils literal notranslate"><span class="pre">str[rv]</span></code> 位置的 <code class="docutils literal notranslate"><span class="pre">'\0'</span></code> 字节)。</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">rv</span> <span class="pre">&gt;=</span> <span class="pre">size</span></code> 时,输出转换会被截断并且需要一个具有 <code class="docutils literal notranslate"><span class="pre">rv</span> <span class="pre">+</span> <span class="pre">1</span></code> 字节的缓冲区才能成功执行。 在此情况下 <code class="docutils literal notranslate"><span class="pre">str[size-1]</span></code><code class="docutils literal notranslate"><span class="pre">'\0'</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">rv</span> <span class="pre">&lt;</span> <span class="pre">0</span></code> 时,&quot;会发生不好的事情。&quot; 在此情况下 <code class="docutils literal notranslate"><span class="pre">str[size-1]</span></code> 也为 <code class="docutils literal notranslate"><span class="pre">'\0'</span></code>,但 <em>str</em> 的其余部分是未定义的。 错误的确切原因取决于底层平台。</p></li>
</ul>
<p>以下函数提供与语言环境无关的字符串到数字转换。</p>
<dl class="function">
<dt id="c.PyOS_string_to_double">
double <code class="sig-name 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="永久链接至目标"></a></dt>
<dd><p>将字符串 <code class="docutils literal notranslate"><span class="pre">s</span></code> 转换为 <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code> 类型失败时引发Python异常。接受的字符串的集合对应于被 Python 的 <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> 构造函数接受的字符串的集合,除了 <code class="docutils literal notranslate"><span class="pre">s</span></code> 必须没有前导或尾随空格。转换必须独立于当前的区域。</p>
<p>如果 <code class="docutils literal notranslate"><span class="pre">endptr</span></code><code class="docutils literal notranslate"><span class="pre">NULL</span></code> ,转换整个字符串。引发 <a class="reference internal" href="../library/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> 并且 返回 <code class="docutils literal notranslate"><span class="pre">-1.0</span></code> 如果字符串不是浮点数的有效的表达方式。</p>
<p>如果 <code class="docutils literal notranslate"><span class="pre">endptr</span></code> 不是 <code class="docutils literal notranslate"><span class="pre">NULL</span></code> ,尽可能多的转换字符串并将 <code class="docutils literal notranslate"><span class="pre">*endptr</span></code> 设置为指向第一个未转换的字符。如果字符串的初始段不是浮点数的有效的表达方式,将 <code class="docutils literal notranslate"><span class="pre">*endptr</span></code> 设置为指向字符串的开头,引发 ValueError 异常,并且返回 <code class="docutils literal notranslate"><span class="pre">-1.0</span></code></p>
<p>如果 <code class="docutils literal notranslate"><span class="pre">s</span></code> 表示一个太大而不能存储在一个浮点数中的值(比方说, <code class="docutils literal notranslate"><span class="pre">&quot;1e500&quot;</span></code> 在许多平台上是一个字符串)然后如果 <code class="docutils literal notranslate"><span class="pre">overflow_exception</span></code><code class="docutils literal notranslate"><span class="pre">NULL</span></code> 返回 <code class="docutils literal notranslate"><span class="pre">Py_HUGE_VAL</span></code> (用适当的符号)并且不设置任何异常。 在其他方面, <code class="docutils literal notranslate"><span class="pre">overflow_exception</span></code> 必须指向一个 Python 异常对象;引发异常并返回 <code class="docutils literal notranslate"><span class="pre">-1.0</span></code> 。在这两种情况下,设置 <code class="docutils literal notranslate"><span class="pre">*endptr</span></code> 指向转换值之后的第一个字符。</p>
<p>如果在转换期间发生任何其他错误(比如一个内存不足的错误),设置适当的 Python 异常并且返回 <code class="docutils literal notranslate"><span class="pre">-1.0</span></code></p>
<div class="versionadded">
<p><span class="versionmodified added">3.1 新版功能.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyOS_double_to_string">
char* <code class="sig-name 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="永久链接至目标"></a></dt>
<dd><p>转换 <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code> <em>val</em> 为一个使用 <em>format_code</em> <em>precision</em><em>flags</em> 的字符串</p>
<p><em>格式码</em> 必须是以下其中之一, <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> 或者 <code class="docutils literal notranslate"><span class="pre">'r'</span></code>。对于 <code class="docutils literal notranslate"><span class="pre">'r'</span></code> , 提供的 <em>精度</em> 必须是0。<code class="docutils literal notranslate"><span class="pre">'r'</span></code> 格式码指定了标准函数 <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> 格式。</p>
<p><em>flags</em> 可以为零或者其他值 <code class="docutils literal notranslate"><span class="pre">Py_DTSF_SIGN</span></code>, <code class="docutils literal notranslate"><span class="pre">Py_DTSF_ADD_DOT_0</span></code><code class="docutils literal notranslate"><span class="pre">Py_DTSF_ALT</span></code> 或其组合:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">Py_DTSF_SIGN</span></code> 表示总是在返回的字符串前附加一个符号字符,即使 <em>val</em> 为非负数。</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">Py_DTSF_ADD_DOT_0</span></code> 表示确保返回的字符串看起来不像是一个整数。</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">Py_DTSF_ALT</span></code> 表示应用 &quot;替代的&quot; 格式化规则。 相关细节请参阅 <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> 定义文档。</p></li>
</ul>
<p>如果 <em>ptype</em> 不为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>,则它指向的值将被设为 <code class="docutils literal notranslate"><span class="pre">Py_DTST_FINITE</span></code>, <code class="docutils literal notranslate"><span class="pre">Py_DTST_INFINITE</span></code><code class="docutils literal notranslate"><span class="pre">Py_DTST_NAN</span></code> 中的一个,分别表示 <em>val</em> 是一个有限数字、无限数字或非数字。</p>
<p>返回值是一个指向包含转换后字符串的 <em>buffer</em> 的指针,如果转换失败则为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>。 调用方要负责调用 <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 added">3.1 新版功能.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyOS_stricmp">
int <code class="sig-name 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="永久链接至目标"></a></dt>
<dd><p>字符串不区分大小写。该函数几乎与 <code class="xref c c-func docutils literal notranslate"><span class="pre">strcmp()</span></code> 的工作方式相同,只是它忽略了大小写。</p>
</dd></dl>
<dl class="function">
<dt id="c.PyOS_strnicmp">
int <code class="sig-name 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="永久链接至目标"></a></dt>
<dd><p>字符串不区分大小写。该函数几乎与 <code class="xref c c-func docutils literal notranslate"><span class="pre">strncmp()</span></code> 的工作方式相同,只是它忽略了大小写。</p>
</dd></dl>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>上一个主题</h4>
<p class="topless"><a href="arg.html"
title="上一章">解析参数并构建值变量</a></p>
<h4>下一个主题</h4>
<p class="topless"><a href="reflection.html"
title="下一章">反射</a></p>
<div role="note" aria-label="source link">
<h3>本页</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">报告 Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.8/Doc/c-api/conversion.rst"
rel="nofollow">显示源代码
</a>
</li>
</ul>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>导航</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="总目录"
>索引</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python 模块索引"
>模块</a> |</li>
<li class="right" >
<a href="reflection.html" title="反射"
>下一页</a> |</li>
<li class="right" >
<a href="arg.html" title="解析参数并构建值变量"
>上一页</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.8.20 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API 参考手册</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="utilities.html" >工具</a> &#187;</li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
<input type="submit" value="转向" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
|
</li>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">版权所有</a> 2001-2024, Python Software Foundation.
<br />
This page is licensed under the Python Software Foundation License Version 2.
<br />
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br />
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
<br />
最后更新于 12月 09, 2024.
<a href="https://docs.python.org/3/bugs.html">Found a bug</a>?
<br />
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 2.4.4.
</div>
</body>
</html>