Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
關註 1
收藏 0
Wiki 捐赠
gooderp18绿色标准版
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
目錄樹: 0f75e31513
分支列表 標籤列表
${ item.name }
Create branch ${ searchTerm }
from '0f75e31513'
${ noResults }
Green_GoodERP18_FSJ_Standard/python/Doc/html/c-api/unicode.html

1878 line
239KB
原始文件 Blame 文件歷史 

  1. <!DOCTYPE html>

  2. 

  3. <html lang="en" data-content_root="../">

  4.   <head>

  5.     <meta charset="utf-8" />

  6.     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  7. <meta property="og:title" content="Unicode Objects and Codecs" />

  8. <meta property="og:type" content="website" />

  9. <meta property="og:url" content="https://docs.python.org/3/c-api/unicode.html" />

  10. <meta property="og:site_name" content="Python documentation" />

  11. <meta property="og:description" content="Unicode Objects: Since the implementation of PEP 393 in Python 3.3, Unicode objects internally use a variety of representations, in order to allow handling the complete range of Unicode characters ..." />

  12. <meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />

  13. <meta property="og:image:alt" content="Python documentation" />

  14. <meta name="description" content="Unicode Objects: Since the implementation of PEP 393 in Python 3.3, Unicode objects internally use a variety of representations, in order to allow handling the complete range of Unicode characters ..." />

  15. <meta property="og:image:width" content="200" />

  16. <meta property="og:image:height" content="200" />

  17. <meta name="theme-color" content="#3776ab" />

  18. 

  19.     <title>Unicode Objects and Codecs &#8212; Python 3.12.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">

  20.     

  21.     <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />

  22.     <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=bb723527" />

  23.     <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" />

  24.     

  25.     <script src="../_static/documentation_options.js?v=2c828074"></script>

  26.     <script src="../_static/doctools.js?v=888ff710"></script>

  27.     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>

  28.     

  29.     <script src="../_static/sidebar.js"></script>

  30.     

  31.     <link rel="search" type="application/opensearchdescription+xml"

  32.           title="Search within Python 3.12.3 documentation"

  33.           href="../_static/opensearch.xml"/>

  34.     <link rel="author" title="About these documents" href="../about.html" />

  35.     <link rel="index" title="Index" href="../genindex.html" />

  36.     <link rel="search" title="Search" href="../search.html" />

  37.     <link rel="copyright" title="Copyright" href="../copyright.html" />

  38.     <link rel="next" title="Tuple Objects" href="tuple.html" />

  39.     <link rel="prev" title="Byte Array Objects" href="bytearray.html" />

  40.     <link rel="canonical" href="https://docs.python.org/3/c-api/unicode.html" />

  41.     

  42.       

  43.     

  44. 

  45.     

  46.     <style>

  47.       @media only screen {

  48.         table.full-width-table {

  49.             width: 100%;

  50.         }

  51.       }

  52.     </style>

  53. <link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">

  54.     <link rel="shortcut icon" type="image/png" href="../_static/py.svg" />

  55.             <script type="text/javascript" src="../_static/copybutton.js"></script>

  56.             <script type="text/javascript" src="../_static/menu.js"></script>

  57.             <script type="text/javascript" src="../_static/search-focus.js"></script>

  58.             <script type="text/javascript" src="../_static/themetoggle.js"></script> 

  59. 

  60.   </head>

  61. <body>

  62. <div class="mobile-nav">

  63.     <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"

  64.            aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />

  65.     <nav class="nav-content" role="navigation">

  66.         <label for="menuToggler" class="toggler__label">

  67.             <span></span>

  68.         </label>

  69.         <span class="nav-items-wrapper">

  70.             <a href="https://www.python.org/" class="nav-logo">

  71.                 <img src="../_static/py.svg" alt="Python logo"/>

  72.             </a>

  73.             <span class="version_switcher_placeholder"></span>

  74.             <form role="search" class="search" action="../search.html" method="get">

  75.                 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">

  76.                     <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>

  77.                 </svg>

  78.                 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />

  79.                 <input type="submit" value="Go"/>

  80.             </form>

  81.         </span>

  82.     </nav>

  83.     <div class="menu-wrapper">

  84.         <nav class="menu" role="navigation" aria-label="main navigation">

  85.             <div class="language_switcher_placeholder"></div>

  86.             

  87. <label class="theme-selector-label">

  88.     Theme

  89.     <select class="theme-selector" oninput="activateTheme(this.value)">

  90.         <option value="auto" selected>Auto</option>

  91.         <option value="light">Light</option>

  92.         <option value="dark">Dark</option>

  93.     </select>

  94. </label>

  95.   <div>

  96.     <h3><a href="../contents.html">Table of Contents</a></h3>

  97.     <ul>

  98. <li><a class="reference internal" href="#">Unicode Objects and Codecs</a><ul>

  99. <li><a class="reference internal" href="#unicode-objects">Unicode Objects</a><ul>

  100. <li><a class="reference internal" href="#unicode-type">Unicode Type</a></li>

  101. <li><a class="reference internal" href="#unicode-character-properties">Unicode Character Properties</a></li>

  102. <li><a class="reference internal" href="#creating-and-accessing-unicode-strings">Creating and accessing Unicode strings</a></li>

  103. <li><a class="reference internal" href="#locale-encoding">Locale Encoding</a></li>

  104. <li><a class="reference internal" href="#file-system-encoding">File System Encoding</a></li>

  105. <li><a class="reference internal" href="#wchar-t-support">wchar_t Support</a></li>

  106. </ul>

  107. </li>

  108. <li><a class="reference internal" href="#built-in-codecs">Built-in Codecs</a><ul>

  109. <li><a class="reference internal" href="#generic-codecs">Generic Codecs</a></li>

  110. <li><a class="reference internal" href="#utf-8-codecs">UTF-8 Codecs</a></li>

  111. <li><a class="reference internal" href="#utf-32-codecs">UTF-32 Codecs</a></li>

  112. <li><a class="reference internal" href="#utf-16-codecs">UTF-16 Codecs</a></li>

  113. <li><a class="reference internal" href="#utf-7-codecs">UTF-7 Codecs</a></li>

  114. <li><a class="reference internal" href="#unicode-escape-codecs">Unicode-Escape Codecs</a></li>

  115. <li><a class="reference internal" href="#raw-unicode-escape-codecs">Raw-Unicode-Escape Codecs</a></li>

  116. <li><a class="reference internal" href="#latin-1-codecs">Latin-1 Codecs</a></li>

  117. <li><a class="reference internal" href="#ascii-codecs">ASCII Codecs</a></li>

  118. <li><a class="reference internal" href="#character-map-codecs">Character Map Codecs</a></li>

  119. <li><a class="reference internal" href="#mbcs-codecs-for-windows">MBCS codecs for Windows</a></li>

  120. <li><a class="reference internal" href="#methods-slots">Methods &amp; Slots</a></li>

  121. </ul>

  122. </li>

  123. <li><a class="reference internal" href="#methods-and-slot-functions">Methods and Slot Functions</a></li>

  124. </ul>

  125. </li>

  126. </ul>

  127. 

  128.   </div>

  129.   <div>

  130.     <h4>Previous topic</h4>

  131.     <p class="topless"><a href="bytearray.html"

  132.                           title="previous chapter">Byte Array Objects</a></p>

  133.   </div>

  134.   <div>

  135.     <h4>Next topic</h4>

  136.     <p class="topless"><a href="tuple.html"

  137.                           title="next chapter">Tuple Objects</a></p>

  138.   </div>

  139.   <div role="note" aria-label="source link">

  140.     <h3>This Page</h3>

  141.     <ul class="this-page-menu">

  142.       <li><a href="../bugs.html">Report a Bug</a></li>

  143.       <li>

  144.         <a href="https://github.com/python/cpython/blob/main/Doc/c-api/unicode.rst"

  145.             rel="nofollow">Show Source

  146.         </a>

  147.       </li>

  148.     </ul>

  149.   </div>

  150.         </nav>

  151.     </div>

  152. </div>

  153. 

  154.   

  155.     <div class="related" role="navigation" aria-label="related navigation">

  156.       <h3>Navigation</h3>

  157.       <ul>

  158.         <li class="right" style="margin-right: 10px">

  159.           <a href="../genindex.html" title="General Index"

  160.              accesskey="I">index</a></li>

  161.         <li class="right" >

  162.           <a href="../py-modindex.html" title="Python Module Index"

  163.              >modules</a> |</li>

  164.         <li class="right" >

  165.           <a href="tuple.html" title="Tuple Objects"

  166.              accesskey="N">next</a> |</li>

  167.         <li class="right" >

  168.           <a href="bytearray.html" title="Byte Array Objects"

  169.              accesskey="P">previous</a> |</li>

  170. 

  171.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  172.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  173.           <li class="switchers">

  174.             <div class="language_switcher_placeholder"></div>

  175.             <div class="version_switcher_placeholder"></div>

  176.           </li>

  177.           <li>

  178.               

  179.           </li>

  180.     <li id="cpython-language-and-version">

  181.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  182.     </li>

  183. 

  184.           <li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> &#187;</li>

  185.           <li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> &#187;</li>

  186.         <li class="nav-item nav-item-this"><a href="">Unicode Objects and Codecs</a></li>

  187.                 <li class="right">

  188.                     

  189. 

  190.     <div class="inline-search" role="search">

  191.         <form class="inline-search" action="../search.html" method="get">

  192.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  193.           <input type="submit" value="Go" />

  194.         </form>

  195.     </div>

  196.                      |

  197.                 </li>

  198.             <li class="right">

  199. <label class="theme-selector-label">

  200.     Theme

  201.     <select class="theme-selector" oninput="activateTheme(this.value)">

  202.         <option value="auto" selected>Auto</option>

  203.         <option value="light">Light</option>

  204.         <option value="dark">Dark</option>

  205.     </select>

  206. </label> |</li>

  207.             

  208.       </ul>

  209.     </div>    

  210. 

  211.     <div class="document">

  212.       <div class="documentwrapper">

  213.         <div class="bodywrapper">

  214.           <div class="body" role="main">

  215.             

  216.   <section id="unicode-objects-and-codecs">

  217. <span id="unicodeobjects"></span><h1>Unicode Objects and Codecs<a class="headerlink" href="#unicode-objects-and-codecs" title="Link to this heading">¶</a></h1>

  218. <section id="unicode-objects">

  219. <h2>Unicode Objects<a class="headerlink" href="#unicode-objects" title="Link to this heading">¶</a></h2>

  220. <p>Since the implementation of <span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0393/"><strong>PEP 393</strong></a> in Python 3.3, Unicode objects internally

  221. use a variety of representations, in order to allow handling the complete range

  222. of Unicode characters while staying memory efficient.  There are special cases

  223. for strings where all code points are below 128, 256, or 65536; otherwise, code

  224. points must be below 1114112 (which is the full Unicode range).</p>

  225. <p>UTF-8 representation is created on demand and cached in the Unicode object.</p>

  226. <div class="admonition note">

  227. <p class="admonition-title">Note</p>

  228. <p>The <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> representation has been removed since Python 3.12

  229. with deprecated APIs.

  230. See <span class="target" id="index-1"></span><a class="pep reference external" href="https://peps.python.org/pep-0623/"><strong>PEP 623</strong></a> for more information.</p>

  231. </div>

  232. <section id="unicode-type">

  233. <h3>Unicode Type<a class="headerlink" href="#unicode-type" title="Link to this heading">¶</a></h3>

  234. <p>These are the basic Unicode object types used for the Unicode implementation in

  235. Python:</p>

  236. <dl class="c type">

  237. <dt class="sig sig-object c" id="c.Py_UCS4">

  238. <span class="k"><span class="pre">type</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UCS4</span></span></span><a class="headerlink" href="#c.Py_UCS4" title="Link to this definition">¶</a><br /></dt>

  239. <dt class="sig sig-object c" id="c.Py_UCS2">

  240. <span class="k"><span class="pre">type</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UCS2</span></span></span><a class="headerlink" href="#c.Py_UCS2" title="Link to this definition">¶</a><br /></dt>

  241. <dt class="sig sig-object c" id="c.Py_UCS1">

  242. <span class="k"><span class="pre">type</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UCS1</span></span></span><a class="headerlink" href="#c.Py_UCS1" title="Link to this definition">¶</a><br /></dt>

  243. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>These types are typedefs for unsigned integer types wide enough to contain

  244. characters of 32 bits, 16 bits and 8 bits, respectively.  When dealing with

  245. single Unicode characters, use <a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UCS4</span></code></a>.</p>

  246. <div class="versionadded">

  247. <p><span class="versionmodified added">New in version 3.3.</span></p>

  248. </div>

  249. </dd></dl>

  250. 

  251. <dl class="c type">

  252. <dt class="sig sig-object c" id="c.Py_UNICODE">

  253. <span class="k"><span class="pre">type</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE</span></span></span><a class="headerlink" href="#c.Py_UNICODE" title="Link to this definition">¶</a><br /></dt>

  254. <dd><p>This is a typedef of <code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code>, which is a 16-bit type or 32-bit type

  255. depending on the platform.</p>

  256. <div class="versionchanged">

  257. <p><span class="versionmodified changed">Changed in version 3.3: </span>In previous versions, this was a 16-bit type or a 32-bit type depending on

  258. whether you selected a “narrow” or “wide” Unicode version of Python at

  259. build time.</p>

  260. </div>

  261. </dd></dl>

  262. 

  263. <dl class="c type">

  264. <dt class="sig sig-object c" id="c.PyASCIIObject">

  265. <span class="k"><span class="pre">type</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyASCIIObject</span></span></span><a class="headerlink" href="#c.PyASCIIObject" title="Link to this definition">¶</a><br /></dt>

  266. <dt class="sig sig-object c" id="c.PyCompactUnicodeObject">

  267. <span class="k"><span class="pre">type</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyCompactUnicodeObject</span></span></span><a class="headerlink" href="#c.PyCompactUnicodeObject" title="Link to this definition">¶</a><br /></dt>

  268. <dt class="sig sig-object c" id="c.PyUnicodeObject">

  269. <span class="k"><span class="pre">type</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicodeObject</span></span></span><a class="headerlink" href="#c.PyUnicodeObject" title="Link to this definition">¶</a><br /></dt>

  270. <dd><p>These subtypes of <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> represent a Python Unicode object.  In

  271. almost all cases, they shouldn’t be used directly, since all API functions

  272. that deal with Unicode objects take and return <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> pointers.</p>

  273. <div class="versionadded">

  274. <p><span class="versionmodified added">New in version 3.3.</span></p>

  275. </div>

  276. </dd></dl>

  277. 

  278. <dl class="c var">

  279. <dt class="sig sig-object c" id="c.PyUnicode_Type">

  280. <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_Type</span></span></span><a class="headerlink" href="#c.PyUnicode_Type" title="Link to this definition">¶</a><br /></dt>

  281. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>This instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> represents the Python Unicode type.  It

  282. is exposed to Python code as <code class="docutils literal notranslate"><span class="pre">str</span></code>.</p>

  283. </dd></dl>

  284. 

  285. <p>The following APIs are C macros and static inlined functions for fast checks and

  286. access to internal read-only data of Unicode objects:</p>

  287. <dl class="c function">

  288. <dt class="sig sig-object c" id="c.PyUnicode_Check">

  289. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_Check</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">obj</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Check" title="Link to this definition">¶</a><br /></dt>

  290. <dd><p>Return true if the object <em>obj</em> is a Unicode object or an instance of a Unicode

  291. subtype.  This function always succeeds.</p>

  292. </dd></dl>

  293. 

  294. <dl class="c function">

  295. <dt class="sig sig-object c" id="c.PyUnicode_CheckExact">

  296. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_CheckExact</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">obj</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_CheckExact" title="Link to this definition">¶</a><br /></dt>

  297. <dd><p>Return true if the object <em>obj</em> is a Unicode object, but not an instance of a

  298. subtype.  This function always succeeds.</p>

  299. </dd></dl>

  300. 

  301. <dl class="c function">

  302. <dt class="sig sig-object c" id="c.PyUnicode_READY">

  303. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_READY</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_READY" title="Link to this definition">¶</a><br /></dt>

  304. <dd><p>Returns <code class="docutils literal notranslate"><span class="pre">0</span></code>. This API is kept only for backward compatibility.</p>

  305. <div class="versionadded">

  306. <p><span class="versionmodified added">New in version 3.3.</span></p>

  307. </div>

  308. <div class="deprecated">

  309. <p><span class="versionmodified deprecated">Deprecated since version 3.10: </span>This API does nothing since Python 3.12.</p>

  310. </div>

  311. </dd></dl>

  312. 

  313. <dl class="c function">

  314. <dt class="sig sig-object c" id="c.PyUnicode_GET_LENGTH">

  315. <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_GET_LENGTH</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_GET_LENGTH" title="Link to this definition">¶</a><br /></dt>

  316. <dd><p>Return the length of the Unicode string, in code points.  <em>unicode</em> has to be a

  317. Unicode object in the “canonical” representation (not checked).</p>

  318. <div class="versionadded">

  319. <p><span class="versionmodified added">New in version 3.3.</span></p>

  320. </div>

  321. </dd></dl>

  322. 

  323. <dl class="c function">

  324. <dt class="sig sig-object c" id="c.PyUnicode_1BYTE_DATA">

  325. <a class="reference internal" href="#c.Py_UCS1" title="Py_UCS1"><span class="n"><span class="pre">Py_UCS1</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_1BYTE_DATA</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_1BYTE_DATA" title="Link to this definition">¶</a><br /></dt>

  326. <dt class="sig sig-object c" id="c.PyUnicode_2BYTE_DATA">

  327. <a class="reference internal" href="#c.Py_UCS2" title="Py_UCS2"><span class="n"><span class="pre">Py_UCS2</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_2BYTE_DATA</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_2BYTE_DATA" title="Link to this definition">¶</a><br /></dt>

  328. <dt class="sig sig-object c" id="c.PyUnicode_4BYTE_DATA">

  329. <a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_4BYTE_DATA</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_4BYTE_DATA" title="Link to this definition">¶</a><br /></dt>

  330. <dd><p>Return a pointer to the canonical representation cast to UCS1, UCS2 or UCS4

  331. integer types for direct character access.  No checks are performed if the

  332. canonical representation has the correct character size; use

  333. <a class="reference internal" href="#c.PyUnicode_KIND" title="PyUnicode_KIND"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_KIND()</span></code></a> to select the right function.</p>

  334. <div class="versionadded">

  335. <p><span class="versionmodified added">New in version 3.3.</span></p>

  336. </div>

  337. </dd></dl>

  338. 

  339. <dl class="c macro">

  340. <dt class="sig sig-object c" id="c.PyUnicode_1BYTE_KIND">

  341. <span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_1BYTE_KIND</span></span></span><a class="headerlink" href="#c.PyUnicode_1BYTE_KIND" title="Link to this definition">¶</a><br /></dt>

  342. <dt class="sig sig-object c" id="c.PyUnicode_2BYTE_KIND">

  343. <span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_2BYTE_KIND</span></span></span><a class="headerlink" href="#c.PyUnicode_2BYTE_KIND" title="Link to this definition">¶</a><br /></dt>

  344. <dt class="sig sig-object c" id="c.PyUnicode_4BYTE_KIND">

  345. <span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_4BYTE_KIND</span></span></span><a class="headerlink" href="#c.PyUnicode_4BYTE_KIND" title="Link to this definition">¶</a><br /></dt>

  346. <dd><p>Return values of the <a class="reference internal" href="#c.PyUnicode_KIND" title="PyUnicode_KIND"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_KIND()</span></code></a> macro.</p>

  347. <div class="versionadded">

  348. <p><span class="versionmodified added">New in version 3.3.</span></p>

  349. </div>

  350. <div class="versionchanged">

  351. <p><span class="versionmodified changed">Changed in version 3.12: </span><code class="docutils literal notranslate"><span class="pre">PyUnicode_WCHAR_KIND</span></code> has been removed.</p>

  352. </div>

  353. </dd></dl>

  354. 

  355. <dl class="c function">

  356. <dt class="sig sig-object c" id="c.PyUnicode_KIND">

  357. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_KIND</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_KIND" title="Link to this definition">¶</a><br /></dt>

  358. <dd><p>Return one of the PyUnicode kind constants (see above) that indicate how many

  359. bytes per character this Unicode object uses to store its data.  <em>unicode</em> has to

  360. be a Unicode object in the “canonical” representation (not checked).</p>

  361. <div class="versionadded">

  362. <p><span class="versionmodified added">New in version 3.3.</span></p>

  363. </div>

  364. </dd></dl>

  365. 

  366. <dl class="c function">

  367. <dt class="sig sig-object c" id="c.PyUnicode_DATA">

  368. <span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_DATA</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DATA" title="Link to this definition">¶</a><br /></dt>

  369. <dd><p>Return a void pointer to the raw Unicode buffer.  <em>unicode</em> has to be a Unicode

  370. object in the “canonical” representation (not checked).</p>

  371. <div class="versionadded">

  372. <p><span class="versionmodified added">New in version 3.3.</span></p>

  373. </div>

  374. </dd></dl>

  375. 

  376. <dl class="c function">

  377. <dt class="sig sig-object c" id="c.PyUnicode_WRITE">

  378. <span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_WRITE</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">kind</span></span>, <span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">data</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">index</span></span>, <a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">value</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_WRITE" title="Link to this definition">¶</a><br /></dt>

  379. <dd><p>Write into a canonical representation <em>data</em> (as obtained with

  380. <a class="reference internal" href="#c.PyUnicode_DATA" title="PyUnicode_DATA"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DATA()</span></code></a>).  This function performs no sanity checks, and is

  381. intended for usage in loops.  The caller should cache the <em>kind</em> value and

  382. <em>data</em> pointer as obtained from other calls.  <em>index</em> is the index in

  383. the string (starts at 0) and <em>value</em> is the new code point value which should

  384. be written to that location.</p>

  385. <div class="versionadded">

  386. <p><span class="versionmodified added">New in version 3.3.</span></p>

  387. </div>

  388. </dd></dl>

  389. 

  390. <dl class="c function">

  391. <dt class="sig sig-object c" id="c.PyUnicode_READ">

  392. <a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_READ</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">kind</span></span>, <span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">data</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">index</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_READ" title="Link to this definition">¶</a><br /></dt>

  393. <dd><p>Read a code point from a canonical representation <em>data</em> (as obtained with

  394. <a class="reference internal" href="#c.PyUnicode_DATA" title="PyUnicode_DATA"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DATA()</span></code></a>).  No checks or ready calls are performed.</p>

  395. <div class="versionadded">

  396. <p><span class="versionmodified added">New in version 3.3.</span></p>

  397. </div>

  398. </dd></dl>

  399. 

  400. <dl class="c function">

  401. <dt class="sig sig-object c" id="c.PyUnicode_READ_CHAR">

  402. <a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_READ_CHAR</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">index</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_READ_CHAR" title="Link to this definition">¶</a><br /></dt>

  403. <dd><p>Read a character from a Unicode object <em>unicode</em>, which must be in the “canonical”

  404. representation.  This is less efficient than <a class="reference internal" href="#c.PyUnicode_READ" title="PyUnicode_READ"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_READ()</span></code></a> if you

  405. do multiple consecutive reads.</p>

  406. <div class="versionadded">

  407. <p><span class="versionmodified added">New in version 3.3.</span></p>

  408. </div>

  409. </dd></dl>

  410. 

  411. <dl class="c function">

  412. <dt class="sig sig-object c" id="c.PyUnicode_MAX_CHAR_VALUE">

  413. <a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_MAX_CHAR_VALUE</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_MAX_CHAR_VALUE" title="Link to this definition">¶</a><br /></dt>

  414. <dd><p>Return the maximum code point that is suitable for creating another string

  415. based on <em>unicode</em>, which must be in the “canonical” representation.  This is

  416. always an approximation but more efficient than iterating over the string.</p>

  417. <div class="versionadded">

  418. <p><span class="versionmodified added">New in version 3.3.</span></p>

  419. </div>

  420. </dd></dl>

  421. 

  422. <dl class="c function">

  423. <dt class="sig sig-object c" id="c.PyUnicode_IsIdentifier">

  424. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_IsIdentifier</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_IsIdentifier" title="Link to this definition">¶</a><br /></dt>

  425. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> if the string is a valid identifier according to the language

  426. definition, section <a class="reference internal" href="../reference/lexical_analysis.html#identifiers"><span class="std std-ref">Identifiers and keywords</span></a>. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise.</p>

  427. <div class="versionchanged">

  428. <p><span class="versionmodified changed">Changed in version 3.9: </span>The function does not call <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> anymore if the string

  429. is not ready.</p>

  430. </div>

  431. </dd></dl>

  432. 

  433. </section>

  434. <section id="unicode-character-properties">

  435. <h3>Unicode Character Properties<a class="headerlink" href="#unicode-character-properties" title="Link to this heading">¶</a></h3>

  436. <p>Unicode provides many different character properties. The most often needed ones

  437. are available through these macros which are mapped to C functions depending on

  438. the Python configuration.</p>

  439. <dl class="c function">

  440. <dt class="sig sig-object c" id="c.Py_UNICODE_ISSPACE">

  441. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_ISSPACE</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISSPACE" title="Link to this definition">¶</a><br /></dt>

  442. <dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is a whitespace character.</p>

  443. </dd></dl>

  444. 

  445. <dl class="c function">

  446. <dt class="sig sig-object c" id="c.Py_UNICODE_ISLOWER">

  447. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_ISLOWER</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISLOWER" title="Link to this definition">¶</a><br /></dt>

  448. <dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is a lowercase character.</p>

  449. </dd></dl>

  450. 

  451. <dl class="c function">

  452. <dt class="sig sig-object c" id="c.Py_UNICODE_ISUPPER">

  453. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_ISUPPER</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISUPPER" title="Link to this definition">¶</a><br /></dt>

  454. <dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is an uppercase character.</p>

  455. </dd></dl>

  456. 

  457. <dl class="c function">

  458. <dt class="sig sig-object c" id="c.Py_UNICODE_ISTITLE">

  459. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_ISTITLE</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISTITLE" title="Link to this definition">¶</a><br /></dt>

  460. <dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is a titlecase character.</p>

  461. </dd></dl>

  462. 

  463. <dl class="c function">

  464. <dt class="sig sig-object c" id="c.Py_UNICODE_ISLINEBREAK">

  465. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_ISLINEBREAK</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISLINEBREAK" title="Link to this definition">¶</a><br /></dt>

  466. <dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is a linebreak character.</p>

  467. </dd></dl>

  468. 

  469. <dl class="c function">

  470. <dt class="sig sig-object c" id="c.Py_UNICODE_ISDECIMAL">

  471. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_ISDECIMAL</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISDECIMAL" title="Link to this definition">¶</a><br /></dt>

  472. <dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is a decimal character.</p>

  473. </dd></dl>

  474. 

  475. <dl class="c function">

  476. <dt class="sig sig-object c" id="c.Py_UNICODE_ISDIGIT">

  477. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_ISDIGIT</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISDIGIT" title="Link to this definition">¶</a><br /></dt>

  478. <dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is a digit character.</p>

  479. </dd></dl>

  480. 

  481. <dl class="c function">

  482. <dt class="sig sig-object c" id="c.Py_UNICODE_ISNUMERIC">

  483. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_ISNUMERIC</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISNUMERIC" title="Link to this definition">¶</a><br /></dt>

  484. <dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is a numeric character.</p>

  485. </dd></dl>

  486. 

  487. <dl class="c function">

  488. <dt class="sig sig-object c" id="c.Py_UNICODE_ISALPHA">

  489. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_ISALPHA</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISALPHA" title="Link to this definition">¶</a><br /></dt>

  490. <dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is an alphabetic character.</p>

  491. </dd></dl>

  492. 

  493. <dl class="c function">

  494. <dt class="sig sig-object c" id="c.Py_UNICODE_ISALNUM">

  495. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_ISALNUM</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISALNUM" title="Link to this definition">¶</a><br /></dt>

  496. <dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is an alphanumeric character.</p>

  497. </dd></dl>

  498. 

  499. <dl class="c function">

  500. <dt class="sig sig-object c" id="c.Py_UNICODE_ISPRINTABLE">

  501. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_ISPRINTABLE</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISPRINTABLE" title="Link to this definition">¶</a><br /></dt>

  502. <dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is a printable character.

  503. Nonprintable characters are those characters defined in the Unicode character

  504. database as “Other” or “Separator”, excepting the ASCII space (0x20) which is

  505. considered printable.  (Note that printable characters in this context are

  506. those which should not be escaped when <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> is invoked on a string.

  507. It has no bearing on the handling of strings written to <a class="reference internal" href="../library/sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout</span></code></a> or

  508. <a class="reference internal" href="../library/sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stderr</span></code></a>.)</p>

  509. </dd></dl>

  510. 

  511. <p>These APIs can be used for fast direct character conversions:</p>

  512. <dl class="c function">

  513. <dt class="sig sig-object c" id="c.Py_UNICODE_TOLOWER">

  514. <a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_TOLOWER</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_TOLOWER" title="Link to this definition">¶</a><br /></dt>

  515. <dd><p>Return the character <em>ch</em> converted to lower case.</p>

  516. <div class="deprecated">

  517. <p><span class="versionmodified deprecated">Deprecated since version 3.3: </span>This function uses simple case mappings.</p>

  518. </div>

  519. </dd></dl>

  520. 

  521. <dl class="c function">

  522. <dt class="sig sig-object c" id="c.Py_UNICODE_TOUPPER">

  523. <a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_TOUPPER</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_TOUPPER" title="Link to this definition">¶</a><br /></dt>

  524. <dd><p>Return the character <em>ch</em> converted to upper case.</p>

  525. <div class="deprecated">

  526. <p><span class="versionmodified deprecated">Deprecated since version 3.3: </span>This function uses simple case mappings.</p>

  527. </div>

  528. </dd></dl>

  529. 

  530. <dl class="c function">

  531. <dt class="sig sig-object c" id="c.Py_UNICODE_TOTITLE">

  532. <a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_TOTITLE</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_TOTITLE" title="Link to this definition">¶</a><br /></dt>

  533. <dd><p>Return the character <em>ch</em> converted to title case.</p>

  534. <div class="deprecated">

  535. <p><span class="versionmodified deprecated">Deprecated since version 3.3: </span>This function uses simple case mappings.</p>

  536. </div>

  537. </dd></dl>

  538. 

  539. <dl class="c function">

  540. <dt class="sig sig-object c" id="c.Py_UNICODE_TODECIMAL">

  541. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_TODECIMAL</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_TODECIMAL" title="Link to this definition">¶</a><br /></dt>

  542. <dd><p>Return the character <em>ch</em> converted to a decimal positive integer.  Return

  543. <code class="docutils literal notranslate"><span class="pre">-1</span></code> if this is not possible.  This function does not raise exceptions.</p>

  544. </dd></dl>

  545. 

  546. <dl class="c function">

  547. <dt class="sig sig-object c" id="c.Py_UNICODE_TODIGIT">

  548. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_TODIGIT</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_TODIGIT" title="Link to this definition">¶</a><br /></dt>

  549. <dd><p>Return the character <em>ch</em> converted to a single digit integer. Return <code class="docutils literal notranslate"><span class="pre">-1</span></code> if

  550. this is not possible.  This function does not raise exceptions.</p>

  551. </dd></dl>

  552. 

  553. <dl class="c function">

  554. <dt class="sig sig-object c" id="c.Py_UNICODE_TONUMERIC">

  555. <span class="kt"><span class="pre">double</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_TONUMERIC</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_TONUMERIC" title="Link to this definition">¶</a><br /></dt>

  556. <dd><p>Return the character <em>ch</em> converted to a double. Return <code class="docutils literal notranslate"><span class="pre">-1.0</span></code> if this is not

  557. possible.  This function does not raise exceptions.</p>

  558. </dd></dl>

  559. 

  560. <p>These APIs can be used to work with surrogates:</p>

  561. <dl class="c function">

  562. <dt class="sig sig-object c" id="c.Py_UNICODE_IS_SURROGATE">

  563. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_IS_SURROGATE</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_IS_SURROGATE" title="Link to this definition">¶</a><br /></dt>

  564. <dd><p>Check if <em>ch</em> is a surrogate (<code class="docutils literal notranslate"><span class="pre">0xD800</span> <span class="pre">&lt;=</span> <span class="pre">ch</span> <span class="pre">&lt;=</span> <span class="pre">0xDFFF</span></code>).</p>

  565. </dd></dl>

  566. 

  567. <dl class="c function">

  568. <dt class="sig sig-object c" id="c.Py_UNICODE_IS_HIGH_SURROGATE">

  569. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_IS_HIGH_SURROGATE</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_IS_HIGH_SURROGATE" title="Link to this definition">¶</a><br /></dt>

  570. <dd><p>Check if <em>ch</em> is a high surrogate (<code class="docutils literal notranslate"><span class="pre">0xD800</span> <span class="pre">&lt;=</span> <span class="pre">ch</span> <span class="pre">&lt;=</span> <span class="pre">0xDBFF</span></code>).</p>

  571. </dd></dl>

  572. 

  573. <dl class="c function">

  574. <dt class="sig sig-object c" id="c.Py_UNICODE_IS_LOW_SURROGATE">

  575. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_IS_LOW_SURROGATE</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_IS_LOW_SURROGATE" title="Link to this definition">¶</a><br /></dt>

  576. <dd><p>Check if <em>ch</em> is a low surrogate (<code class="docutils literal notranslate"><span class="pre">0xDC00</span> <span class="pre">&lt;=</span> <span class="pre">ch</span> <span class="pre">&lt;=</span> <span class="pre">0xDFFF</span></code>).</p>

  577. </dd></dl>

  578. 

  579. <dl class="c function">

  580. <dt class="sig sig-object c" id="c.Py_UNICODE_JOIN_SURROGATES">

  581. <a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UNICODE_JOIN_SURROGATES</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">high</span></span>, <a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">low</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_JOIN_SURROGATES" title="Link to this definition">¶</a><br /></dt>

  582. <dd><p>Join two surrogate characters and return a single <a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UCS4</span></code></a> value.

  583. <em>high</em> and <em>low</em> are respectively the leading and trailing surrogates in a

  584. surrogate pair. <em>high</em> must be in the range [0xD800; 0xDBFF] and <em>low</em> must

  585. be in the range [0xDC00; 0xDFFF].</p>

  586. </dd></dl>

  587. 

  588. </section>

  589. <section id="creating-and-accessing-unicode-strings">

  590. <h3>Creating and accessing Unicode strings<a class="headerlink" href="#creating-and-accessing-unicode-strings" title="Link to this heading">¶</a></h3>

  591. <p>To create Unicode objects and access their basic sequence properties, use these

  592. APIs:</p>

  593. <dl class="c function">

  594. <dt class="sig sig-object c" id="c.PyUnicode_New">

  595. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_New</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span>, <a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">maxchar</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_New" title="Link to this definition">¶</a><br /></dt>

  596. <dd><em class="refcount">Return value: New reference.</em><p>Create a new Unicode object.  <em>maxchar</em> should be the true maximum code point

  597. to be placed in the string.  As an approximation, it can be rounded up to the

  598. nearest value in the sequence 127, 255, 65535, 1114111.</p>

  599. <p>This is the recommended way to allocate a new Unicode object.  Objects

  600. created using this function are not resizable.</p>

  601. <div class="versionadded">

  602. <p><span class="versionmodified added">New in version 3.3.</span></p>

  603. </div>

  604. </dd></dl>

  605. 

  606. <dl class="c function">

  607. <dt class="sig sig-object c" id="c.PyUnicode_FromKindAndData">

  608. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_FromKindAndData</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">kind</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">buffer</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_FromKindAndData" title="Link to this definition">¶</a><br /></dt>

  609. <dd><em class="refcount">Return value: New reference.</em><p>Create a new Unicode object with the given <em>kind</em> (possible values are

  610. <a class="reference internal" href="#c.PyUnicode_1BYTE_KIND" title="PyUnicode_1BYTE_KIND"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyUnicode_1BYTE_KIND</span></code></a> etc., as returned by

  611. <a class="reference internal" href="#c.PyUnicode_KIND" title="PyUnicode_KIND"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_KIND()</span></code></a>).  The <em>buffer</em> must point to an array of <em>size</em>

  612. units of 1, 2 or 4 bytes per character, as given by the kind.</p>

  613. <p>If necessary, the input <em>buffer</em> is copied and transformed into the

  614. canonical representation.  For example, if the <em>buffer</em> is a UCS4 string

  615. (<a class="reference internal" href="#c.PyUnicode_4BYTE_KIND" title="PyUnicode_4BYTE_KIND"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyUnicode_4BYTE_KIND</span></code></a>) and it consists only of codepoints in

  616. the UCS1 range, it will be transformed into UCS1

  617. (<a class="reference internal" href="#c.PyUnicode_1BYTE_KIND" title="PyUnicode_1BYTE_KIND"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyUnicode_1BYTE_KIND</span></code></a>).</p>

  618. <div class="versionadded">

  619. <p><span class="versionmodified added">New in version 3.3.</span></p>

  620. </div>

  621. </dd></dl>

  622. 

  623. <dl class="c function">

  624. <dt class="sig sig-object c" id="c.PyUnicode_FromStringAndSize">

  625. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_FromStringAndSize</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_FromStringAndSize" title="Link to this definition">¶</a><br /></dt>

  626. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Create a Unicode object from the char buffer <em>str</em>.  The bytes will be

  627. interpreted as being UTF-8 encoded.  The buffer is copied into the new

  628. object.

  629. The return value might be a shared object, i.e. modification of the data is

  630. not allowed.</p>

  631. <p>This function raises <a class="reference internal" href="../library/exceptions.html#SystemError" title="SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a> when:</p>

  632. <ul class="simple">

  633. <li><p><em>size</em> &lt; 0,</p></li>

  634. <li><p><em>str</em> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code> and <em>size</em> &gt; 0</p></li>

  635. </ul>

  636. <div class="versionchanged">

  637. <p><span class="versionmodified changed">Changed in version 3.12: </span><em>str</em> == <code class="docutils literal notranslate"><span class="pre">NULL</span></code> with <em>size</em> &gt; 0 is not allowed anymore.</p>

  638. </div>

  639. </dd></dl>

  640. 

  641. <dl class="c function">

  642. <dt class="sig sig-object c" id="c.PyUnicode_FromString">

  643. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_FromString</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_FromString" title="Link to this definition">¶</a><br /></dt>

  644. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Create a Unicode object from a UTF-8 encoded null-terminated char buffer

  645. <em>str</em>.</p>

  646. </dd></dl>

  647. 

  648. <dl class="c function">

  649. <dt class="sig sig-object c" id="c.PyUnicode_FromFormat">

  650. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_FromFormat</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">format</span></span>, <span class="p"><span class="pre">...</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_FromFormat" title="Link to this definition">¶</a><br /></dt>

  651. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Take a C <code class="xref c c-func docutils literal notranslate"><span class="pre">printf()</span></code>-style <em>format</em> string and a variable number of

  652. arguments, calculate the size of the resulting Python Unicode string and return

  653. a string with the values formatted into it.  The variable arguments must be C

  654. types and must correspond exactly to the format characters in the <em>format</em>

  655. ASCII-encoded string.</p>

  656. <p>A conversion specifier contains two or more characters and has the following

  657. components, which must occur in this order:</p>

  658. <ol class="arabic simple">

  659. <li><p>The <code class="docutils literal notranslate"><span class="pre">'%'</span></code> character, which marks the start of the specifier.</p></li>

  660. <li><p>Conversion flags (optional), which affect the result of some conversion

  661. types.</p></li>

  662. <li><p>Minimum field width (optional).

  663. If specified as an <code class="docutils literal notranslate"><span class="pre">'*'</span></code> (asterisk), the actual width is given in the

  664. next argument, which must be of type <span class="c-expr sig sig-inline c"><span class="kt">int</span></span>, and the object to

  665. convert comes after the minimum field width and optional precision.</p></li>

  666. <li><p>Precision (optional), given as a <code class="docutils literal notranslate"><span class="pre">'.'</span></code> (dot) followed by the precision.

  667. If specified as <code class="docutils literal notranslate"><span class="pre">'*'</span></code> (an asterisk), the actual precision is given in

  668. the next argument, which must be of type <span class="c-expr sig sig-inline c"><span class="kt">int</span></span>, and the value to

  669. convert comes after the precision.</p></li>

  670. <li><p>Length modifier (optional).</p></li>

  671. <li><p>Conversion type.</p></li>

  672. </ol>

  673. <p>The conversion flag characters are:</p>

  674. <table class="docutils align-default">

  675. <thead>

  676. <tr class="row-odd"><th class="head"><p>Flag</p></th>

  677. <th class="head"><p>Meaning</p></th>

  678. </tr>

  679. </thead>

  680. <tbody>

  681. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">0</span></code></p></td>

  682. <td><p>The conversion will be zero padded for numeric values.</p></td>

  683. </tr>

  684. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-</span></code></p></td>

  685. <td><p>The converted value is left adjusted (overrides the <code class="docutils literal notranslate"><span class="pre">0</span></code>

  686. flag if both are given).</p></td>

  687. </tr>

  688. </tbody>

  689. </table>

  690. <p>The length modifiers for following integer conversions (<code class="docutils literal notranslate"><span class="pre">d</span></code>, <code class="docutils literal notranslate"><span class="pre">i</span></code>,

  691. <code class="docutils literal notranslate"><span class="pre">o</span></code>, <code class="docutils literal notranslate"><span class="pre">u</span></code>, <code class="docutils literal notranslate"><span class="pre">x</span></code>, or <code class="docutils literal notranslate"><span class="pre">X</span></code>) specify the type of the argument

  692. (<span class="c-expr sig sig-inline c"><span class="kt">int</span></span> by default):</p>

  693. <table class="docutils align-default">

  694. <thead>

  695. <tr class="row-odd"><th class="head"><p>Modifier</p></th>

  696. <th class="head"><p>Types</p></th>

  697. </tr>

  698. </thead>

  699. <tbody>

  700. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">l</span></code></p></td>

  701. <td><p><span class="c-expr sig sig-inline c"><span class="kt">long</span></span> or <span class="c-expr sig sig-inline c"><span class="kt">unsigned</span><span class="w"> </span><span class="kt">long</span></span></p></td>

  702. </tr>

  703. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">ll</span></code></p></td>

  704. <td><p><span class="c-expr sig sig-inline c"><span class="kt">long</span><span class="w"> </span><span class="kt">long</span></span> or <span class="c-expr sig sig-inline c"><span class="kt">unsigned</span><span class="w"> </span><span class="kt">long</span><span class="w"> </span><span class="kt">long</span></span></p></td>

  705. </tr>

  706. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">j</span></code></p></td>

  707. <td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">intmax_t</span></code> or <code class="xref c c-type docutils literal notranslate"><span class="pre">uintmax_t</span></code></p></td>

  708. </tr>

  709. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">z</span></code></p></td>

  710. <td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">size_t</span></code> or <code class="xref c c-type docutils literal notranslate"><span class="pre">ssize_t</span></code></p></td>

  711. </tr>

  712. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">t</span></code></p></td>

  713. <td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">ptrdiff_t</span></code></p></td>

  714. </tr>

  715. </tbody>

  716. </table>

  717. <p>The length modifier <code class="docutils literal notranslate"><span class="pre">l</span></code> for following conversions <code class="docutils literal notranslate"><span class="pre">s</span></code> or <code class="docutils literal notranslate"><span class="pre">V</span></code> specify

  718. that the type of the argument is <span class="c-expr sig sig-inline c"><span class="k">const</span><span class="w"> </span><span class="n">wchar_t</span><span class="p">*</span></span>.</p>

  719. <p>The conversion specifiers are:</p>

  720. <table class="docutils align-default">

  721. <thead>

  722. <tr class="row-odd"><th class="head"><p>Conversion Specifier</p></th>

  723. <th class="head"><p>Type</p></th>

  724. <th class="head"><p>Comment</p></th>

  725. </tr>

  726. </thead>

  727. <tbody>

  728. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">%</span></code></p></td>

  729. <td><p><em>n/a</em></p></td>

  730. <td><p>The literal <code class="docutils literal notranslate"><span class="pre">%</span></code> character.</p></td>

  731. </tr>

  732. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">d</span></code>, <code class="docutils literal notranslate"><span class="pre">i</span></code></p></td>

  733. <td><p>Specified by the length modifier</p></td>

  734. <td><p>The decimal representation of a signed C integer.</p></td>

  735. </tr>

  736. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">u</span></code></p></td>

  737. <td><p>Specified by the length modifier</p></td>

  738. <td><p>The decimal representation of an unsigned C integer.</p></td>

  739. </tr>

  740. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">o</span></code></p></td>

  741. <td><p>Specified by the length modifier</p></td>

  742. <td><p>The octal representation of an unsigned C integer.</p></td>

  743. </tr>

  744. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">x</span></code></p></td>

  745. <td><p>Specified by the length modifier</p></td>

  746. <td><p>The hexadecimal representation of an unsigned C integer (lowercase).</p></td>

  747. </tr>

  748. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">X</span></code></p></td>

  749. <td><p>Specified by the length modifier</p></td>

  750. <td><p>The hexadecimal representation of an unsigned C integer (uppercase).</p></td>

  751. </tr>

  752. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">c</span></code></p></td>

  753. <td><p><span class="c-expr sig sig-inline c"><span class="kt">int</span></span></p></td>

  754. <td><p>A single character.</p></td>

  755. </tr>

  756. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">s</span></code></p></td>

  757. <td><p><span class="c-expr sig sig-inline c"><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="p">*</span></span> or <span class="c-expr sig sig-inline c"><span class="k">const</span><span class="w"> </span><span class="n">wchar_t</span><span class="p">*</span></span></p></td>

  758. <td><p>A null-terminated C character array.</p></td>

  759. </tr>

  760. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">p</span></code></p></td>

  761. <td><p><span class="c-expr sig sig-inline c"><span class="k">const</span><span class="w"> </span><span class="kt">void</span><span class="p">*</span></span></p></td>

  762. <td><p>The hex representation of a C  pointer.

  763. Mostly equivalent to <code class="docutils literal notranslate"><span class="pre">printf(&quot;%p&quot;)</span></code> except that it is guaranteed to

  764. start with the literal <code class="docutils literal notranslate"><span class="pre">0x</span></code> regardless of what the platform’s

  765. <code class="docutils literal notranslate"><span class="pre">printf</span></code> yields.</p></td>

  766. </tr>

  767. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">A</span></code></p></td>

  768. <td><p><span class="c-expr sig sig-inline c"><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n">PyObject</span></a><span class="p">*</span></span></p></td>

  769. <td><p>The result of calling <a class="reference internal" href="../library/functions.html#ascii" title="ascii"><code class="xref py py-func docutils literal notranslate"><span class="pre">ascii()</span></code></a>.</p></td>

  770. </tr>

  771. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">U</span></code></p></td>

  772. <td><p><span class="c-expr sig sig-inline c"><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n">PyObject</span></a><span class="p">*</span></span></p></td>

  773. <td><p>A Unicode object.</p></td>

  774. </tr>

  775. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">V</span></code></p></td>

  776. <td><p><span class="c-expr sig sig-inline c"><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n">PyObject</span></a><span class="p">*</span></span>, <span class="c-expr sig sig-inline c"><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="p">*</span></span> or <span class="c-expr sig sig-inline c"><span class="k">const</span><span class="w"> </span><span class="n">wchar_t</span><span class="p">*</span></span></p></td>

  777. <td><p>A Unicode object (which may be <code class="docutils literal notranslate"><span class="pre">NULL</span></code>) and a null-terminated

  778. C character array as a second parameter (which will be used,

  779. if the first parameter is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>).</p></td>

  780. </tr>

  781. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">S</span></code></p></td>

  782. <td><p><span class="c-expr sig sig-inline c"><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n">PyObject</span></a><span class="p">*</span></span></p></td>

  783. <td><p>The result of calling <a class="reference internal" href="object.html#c.PyObject_Str" title="PyObject_Str"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Str()</span></code></a>.</p></td>

  784. </tr>

  785. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">R</span></code></p></td>

  786. <td><p><span class="c-expr sig sig-inline c"><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n">PyObject</span></a><span class="p">*</span></span></p></td>

  787. <td><p>The result of calling <a class="reference internal" href="object.html#c.PyObject_Repr" title="PyObject_Repr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Repr()</span></code></a>.</p></td>

  788. </tr>

  789. </tbody>

  790. </table>

  791. <div class="admonition note">

  792. <p class="admonition-title">Note</p>

  793. <p>The width formatter unit is number of characters rather than bytes.

  794. The precision formatter unit is number of bytes or <code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code>

  795. items (if the length modifier <code class="docutils literal notranslate"><span class="pre">l</span></code> is used) for <code class="docutils literal notranslate"><span class="pre">&quot;%s&quot;</span></code> and

  796. <code class="docutils literal notranslate"><span class="pre">&quot;%V&quot;</span></code> (if the <code class="docutils literal notranslate"><span class="pre">PyObject*</span></code> argument is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>), and a number of

  797. characters for <code class="docutils literal notranslate"><span class="pre">&quot;%A&quot;</span></code>, <code class="docutils literal notranslate"><span class="pre">&quot;%U&quot;</span></code>, <code class="docutils literal notranslate"><span class="pre">&quot;%S&quot;</span></code>, <code class="docutils literal notranslate"><span class="pre">&quot;%R&quot;</span></code> and <code class="docutils literal notranslate"><span class="pre">&quot;%V&quot;</span></code>

  798. (if the <code class="docutils literal notranslate"><span class="pre">PyObject*</span></code> argument is not <code class="docutils literal notranslate"><span class="pre">NULL</span></code>).</p>

  799. </div>

  800. <div class="admonition note">

  801. <p class="admonition-title">Note</p>

  802. <p>Unlike to C <code class="xref c c-func docutils literal notranslate"><span class="pre">printf()</span></code> the <code class="docutils literal notranslate"><span class="pre">0</span></code> flag has effect even when

  803. a precision is given for integer conversions (<code class="docutils literal notranslate"><span class="pre">d</span></code>, <code class="docutils literal notranslate"><span class="pre">i</span></code>, <code class="docutils literal notranslate"><span class="pre">u</span></code>, <code class="docutils literal notranslate"><span class="pre">o</span></code>,

  804. <code class="docutils literal notranslate"><span class="pre">x</span></code>, or <code class="docutils literal notranslate"><span class="pre">X</span></code>).</p>

  805. </div>

  806. <div class="versionchanged">

  807. <p><span class="versionmodified changed">Changed in version 3.2: </span>Support for <code class="docutils literal notranslate"><span class="pre">&quot;%lld&quot;</span></code> and <code class="docutils literal notranslate"><span class="pre">&quot;%llu&quot;</span></code> added.</p>

  808. </div>

  809. <div class="versionchanged">

  810. <p><span class="versionmodified changed">Changed in version 3.3: </span>Support for <code class="docutils literal notranslate"><span class="pre">&quot;%li&quot;</span></code>, <code class="docutils literal notranslate"><span class="pre">&quot;%lli&quot;</span></code> and <code class="docutils literal notranslate"><span class="pre">&quot;%zi&quot;</span></code> added.</p>

  811. </div>

  812. <div class="versionchanged">

  813. <p><span class="versionmodified changed">Changed in version 3.4: </span>Support width and precision formatter for <code class="docutils literal notranslate"><span class="pre">&quot;%s&quot;</span></code>, <code class="docutils literal notranslate"><span class="pre">&quot;%A&quot;</span></code>, <code class="docutils literal notranslate"><span class="pre">&quot;%U&quot;</span></code>,

  814. <code class="docutils literal notranslate"><span class="pre">&quot;%V&quot;</span></code>, <code class="docutils literal notranslate"><span class="pre">&quot;%S&quot;</span></code>, <code class="docutils literal notranslate"><span class="pre">&quot;%R&quot;</span></code> added.</p>

  815. </div>

  816. <div class="versionchanged">

  817. <p><span class="versionmodified changed">Changed in version 3.12: </span>Support for conversion specifiers <code class="docutils literal notranslate"><span class="pre">o</span></code> and <code class="docutils literal notranslate"><span class="pre">X</span></code>.

  818. Support for length modifiers <code class="docutils literal notranslate"><span class="pre">j</span></code> and <code class="docutils literal notranslate"><span class="pre">t</span></code>.

  819. Length modifiers are now applied to all integer conversions.

  820. Length modifier <code class="docutils literal notranslate"><span class="pre">l</span></code> is now applied to conversion specifiers <code class="docutils literal notranslate"><span class="pre">s</span></code> and <code class="docutils literal notranslate"><span class="pre">V</span></code>.

  821. Support for variable width and precision <code class="docutils literal notranslate"><span class="pre">*</span></code>.

  822. Support for flag <code class="docutils literal notranslate"><span class="pre">-</span></code>.</p>

  823. <p>An unrecognized format character now sets a <a class="reference internal" href="../library/exceptions.html#SystemError" title="SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a>.

  824. In previous versions it caused all the rest of the format string to be

  825. copied as-is to the result string, and any extra arguments discarded.</p>

  826. </div>

  827. </dd></dl>

  828. 

  829. <dl class="c function">

  830. <dt class="sig sig-object c" id="c.PyUnicode_FromFormatV">

  831. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_FromFormatV</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">format</span></span>, <span class="n"><span class="pre">va_list</span></span><span class="w"> </span><span class="n"><span class="pre">vargs</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_FromFormatV" title="Link to this definition">¶</a><br /></dt>

  832. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Identical to <a class="reference internal" href="#c.PyUnicode_FromFormat" title="PyUnicode_FromFormat"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_FromFormat()</span></code></a> except that it takes exactly two

  833. arguments.</p>

  834. </dd></dl>

  835. 

  836. <dl class="c function">

  837. <dt class="sig sig-object c" id="c.PyUnicode_FromObject">

  838. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_FromObject</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">obj</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_FromObject" title="Link to this definition">¶</a><br /></dt>

  839. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Copy an instance of a Unicode subtype to a new true Unicode object if

  840. necessary. If <em>obj</em> is already a true Unicode object (not a subtype),

  841. return a new <a class="reference internal" href="../glossary.html#term-strong-reference"><span class="xref std std-term">strong reference</span></a> to the object.</p>

  842. <p>Objects other than Unicode or its subtypes will cause a <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.</p>

  843. </dd></dl>

  844. 

  845. <dl class="c function">

  846. <dt class="sig sig-object c" id="c.PyUnicode_FromEncodedObject">

  847. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_FromEncodedObject</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">obj</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">encoding</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_FromEncodedObject" title="Link to this definition">¶</a><br /></dt>

  848. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Decode an encoded object <em>obj</em> to a Unicode object.</p>

  849. <p><a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>, <a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> and other

  850. <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like objects</span></a>

  851. are decoded according to the given <em>encoding</em> and using the error handling

  852. defined by <em>errors</em>. Both can be <code class="docutils literal notranslate"><span class="pre">NULL</span></code> to have the interface use the default

  853. values (see <a class="reference internal" href="#builtincodecs"><span class="std std-ref">Built-in Codecs</span></a> for details).</p>

  854. <p>All other objects, including Unicode objects, cause a <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> to be

  855. set.</p>

  856. <p>The API returns <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if there was an error.  The caller is responsible for

  857. decref’ing the returned objects.</p>

  858. </dd></dl>

  859. 

  860. <dl class="c function">

  861. <dt class="sig sig-object c" id="c.PyUnicode_GetLength">

  862. <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_GetLength</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_GetLength" title="Link to this definition">¶</a><br /></dt>

  863. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p>Return the length of the Unicode object, in code points.</p>

  864. <div class="versionadded">

  865. <p><span class="versionmodified added">New in version 3.3.</span></p>

  866. </div>

  867. </dd></dl>

  868. 

  869. <dl class="c function">

  870. <dt class="sig sig-object c" id="c.PyUnicode_CopyCharacters">

  871. <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_CopyCharacters</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">to</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">to_start</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">from</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">from_start</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">how_many</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_CopyCharacters" title="Link to this definition">¶</a><br /></dt>

  872. <dd><p>Copy characters from one Unicode object into another.  This function performs

  873. character conversion when necessary and falls back to <code class="xref c c-func docutils literal notranslate"><span class="pre">memcpy()</span></code> if

  874. possible.  Returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> and sets an exception on error, otherwise returns

  875. the number of copied characters.</p>

  876. <div class="versionadded">

  877. <p><span class="versionmodified added">New in version 3.3.</span></p>

  878. </div>

  879. </dd></dl>

  880. 

  881. <dl class="c function">

  882. <dt class="sig sig-object c" id="c.PyUnicode_Fill">

  883. <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_Fill</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">start</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">length</span></span>, <a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">fill_char</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Fill" title="Link to this definition">¶</a><br /></dt>

  884. <dd><p>Fill a string with a character: write <em>fill_char</em> into

  885. <code class="docutils literal notranslate"><span class="pre">unicode[start:start+length]</span></code>.</p>

  886. <p>Fail if <em>fill_char</em> is bigger than the string maximum character, or if the

  887. string has more than 1 reference.</p>

  888. <p>Return the number of written character, or return <code class="docutils literal notranslate"><span class="pre">-1</span></code> and raise an

  889. exception on error.</p>

  890. <div class="versionadded">

  891. <p><span class="versionmodified added">New in version 3.3.</span></p>

  892. </div>

  893. </dd></dl>

  894. 

  895. <dl class="c function">

  896. <dt class="sig sig-object c" id="c.PyUnicode_WriteChar">

  897. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_WriteChar</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">index</span></span>, <a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">character</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_WriteChar" title="Link to this definition">¶</a><br /></dt>

  898. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p>Write a character to a string.  The string must have been created through

  899. <a class="reference internal" href="#c.PyUnicode_New" title="PyUnicode_New"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_New()</span></code></a>.  Since Unicode strings are supposed to be immutable,

  900. the string must not be shared, or have been hashed yet.</p>

  901. <p>This function checks that <em>unicode</em> is a Unicode object, that the index is

  902. not out of bounds, and that the object can be modified safely (i.e. that it

  903. its reference count is one).</p>

  904. <div class="versionadded">

  905. <p><span class="versionmodified added">New in version 3.3.</span></p>

  906. </div>

  907. </dd></dl>

  908. 

  909. <dl class="c function">

  910. <dt class="sig sig-object c" id="c.PyUnicode_ReadChar">

  911. <a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_ReadChar</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">index</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_ReadChar" title="Link to this definition">¶</a><br /></dt>

  912. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p>Read a character from a string.  This function checks that <em>unicode</em> is a

  913. Unicode object and the index is not out of bounds, in contrast to

  914. <a class="reference internal" href="#c.PyUnicode_READ_CHAR" title="PyUnicode_READ_CHAR"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_READ_CHAR()</span></code></a>, which performs no error checking.</p>

  915. <div class="versionadded">

  916. <p><span class="versionmodified added">New in version 3.3.</span></p>

  917. </div>

  918. </dd></dl>

  919. 

  920. <dl class="c function">

  921. <dt class="sig sig-object c" id="c.PyUnicode_Substring">

  922. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_Substring</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">start</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">end</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Substring" title="Link to this definition">¶</a><br /></dt>

  923. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p>Return a substring of <em>unicode</em>, from character index <em>start</em> (included) to

  924. character index <em>end</em> (excluded).  Negative indices are not supported.</p>

  925. <div class="versionadded">

  926. <p><span class="versionmodified added">New in version 3.3.</span></p>

  927. </div>

  928. </dd></dl>

  929. 

  930. <dl class="c function">

  931. <dt class="sig sig-object c" id="c.PyUnicode_AsUCS4">

  932. <a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_AsUCS4</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">buffer</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">buflen</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">copy_null</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsUCS4" title="Link to this definition">¶</a><br /></dt>

  933. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p>Copy the string <em>unicode</em> into a UCS4 buffer, including a null character, if

  934. <em>copy_null</em> is set.  Returns <code class="docutils literal notranslate"><span class="pre">NULL</span></code> and sets an exception on error (in

  935. particular, a <a class="reference internal" href="../library/exceptions.html#SystemError" title="SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a> if <em>buflen</em> is smaller than the length of

  936. <em>unicode</em>).  <em>buffer</em> is returned on success.</p>

  937. <div class="versionadded">

  938. <p><span class="versionmodified added">New in version 3.3.</span></p>

  939. </div>

  940. </dd></dl>

  941. 

  942. <dl class="c function">

  943. <dt class="sig sig-object c" id="c.PyUnicode_AsUCS4Copy">

  944. <a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_AsUCS4Copy</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsUCS4Copy" title="Link to this definition">¶</a><br /></dt>

  945. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p>Copy the string <em>unicode</em> into a new UCS4 buffer that is allocated using

  946. <a class="reference internal" href="memory.html#c.PyMem_Malloc" title="PyMem_Malloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_Malloc()</span></code></a>.  If this fails, <code class="docutils literal notranslate"><span class="pre">NULL</span></code> is returned with a

  947. <a class="reference internal" href="../library/exceptions.html#MemoryError" title="MemoryError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">MemoryError</span></code></a> set.  The returned buffer always has an extra

  948. null code point appended.</p>

  949. <div class="versionadded">

  950. <p><span class="versionmodified added">New in version 3.3.</span></p>

  951. </div>

  952. </dd></dl>

  953. 

  954. </section>

  955. <section id="locale-encoding">

  956. <h3>Locale Encoding<a class="headerlink" href="#locale-encoding" title="Link to this heading">¶</a></h3>

  957. <p>The current locale encoding can be used to decode text from the operating

  958. system.</p>

  959. <dl class="c function">

  960. <dt class="sig sig-object c" id="c.PyUnicode_DecodeLocaleAndSize">

  961. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_DecodeLocaleAndSize</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">length</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeLocaleAndSize" title="Link to this definition">¶</a><br /></dt>

  962. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p>Decode a string from UTF-8 on Android and VxWorks, or from the current

  963. locale encoding on other platforms. The supported

  964. error handlers are <code class="docutils literal notranslate"><span class="pre">&quot;strict&quot;</span></code> and <code class="docutils literal notranslate"><span class="pre">&quot;surrogateescape&quot;</span></code>

  965. (<span class="target" id="index-2"></span><a class="pep reference external" href="https://peps.python.org/pep-0383/"><strong>PEP 383</strong></a>). The decoder uses <code class="docutils literal notranslate"><span class="pre">&quot;strict&quot;</span></code> error handler if

  966. <em>errors</em> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.  <em>str</em> must end with a null character but

  967. cannot contain embedded null characters.</p>

  968. <p>Use <a class="reference internal" href="#c.PyUnicode_DecodeFSDefaultAndSize" title="PyUnicode_DecodeFSDefaultAndSize"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeFSDefaultAndSize()</span></code></a> to decode a string from

  969. the <a class="reference internal" href="../glossary.html#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem encoding and error handler</span></a>.</p>

  970. <p>This function ignores the <a class="reference internal" href="../library/os.html#utf8-mode"><span class="std std-ref">Python UTF-8 Mode</span></a>.</p>

  971. <div class="admonition seealso">

  972. <p class="admonition-title">See also</p>

  973. <p>The <a class="reference internal" href="sys.html#c.Py_DecodeLocale" title="Py_DecodeLocale"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DecodeLocale()</span></code></a> function.</p>

  974. </div>

  975. <div class="versionadded">

  976. <p><span class="versionmodified added">New in version 3.3.</span></p>

  977. </div>

  978. <div class="versionchanged">

  979. <p><span class="versionmodified changed">Changed in version 3.7: </span>The function now also uses the current locale encoding for the

  980. <code class="docutils literal notranslate"><span class="pre">surrogateescape</span></code> error handler, except on Android. Previously, <a class="reference internal" href="sys.html#c.Py_DecodeLocale" title="Py_DecodeLocale"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DecodeLocale()</span></code></a>

  981. was used for the <code class="docutils literal notranslate"><span class="pre">surrogateescape</span></code>, and the current locale encoding was

  982. used for <code class="docutils literal notranslate"><span class="pre">strict</span></code>.</p>

  983. </div>

  984. </dd></dl>

  985. 

  986. <dl class="c function">

  987. <dt class="sig sig-object c" id="c.PyUnicode_DecodeLocale">

  988. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_DecodeLocale</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeLocale" title="Link to this definition">¶</a><br /></dt>

  989. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p>Similar to <a class="reference internal" href="#c.PyUnicode_DecodeLocaleAndSize" title="PyUnicode_DecodeLocaleAndSize"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeLocaleAndSize()</span></code></a>, but compute the string

  990. length using <code class="xref c c-func docutils literal notranslate"><span class="pre">strlen()</span></code>.</p>

  991. <div class="versionadded">

  992. <p><span class="versionmodified added">New in version 3.3.</span></p>

  993. </div>

  994. </dd></dl>

  995. 

  996. <dl class="c function">

  997. <dt class="sig sig-object c" id="c.PyUnicode_EncodeLocale">

  998. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_EncodeLocale</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_EncodeLocale" title="Link to this definition">¶</a><br /></dt>

  999. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p>Encode a Unicode object to UTF-8 on Android and VxWorks, or to the current

  1000. locale encoding on other platforms. The

  1001. supported error handlers are <code class="docutils literal notranslate"><span class="pre">&quot;strict&quot;</span></code> and <code class="docutils literal notranslate"><span class="pre">&quot;surrogateescape&quot;</span></code>

  1002. (<span class="target" id="index-3"></span><a class="pep reference external" href="https://peps.python.org/pep-0383/"><strong>PEP 383</strong></a>). The encoder uses <code class="docutils literal notranslate"><span class="pre">&quot;strict&quot;</span></code> error handler if

  1003. <em>errors</em> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>. Return a <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object. <em>unicode</em> cannot

  1004. contain embedded null characters.</p>

  1005. <p>Use <a class="reference internal" href="#c.PyUnicode_EncodeFSDefault" title="PyUnicode_EncodeFSDefault"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_EncodeFSDefault()</span></code></a> to encode a string to the

  1006. <a class="reference internal" href="../glossary.html#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem encoding and error handler</span></a>.</p>

  1007. <p>This function ignores the <a class="reference internal" href="../library/os.html#utf8-mode"><span class="std std-ref">Python UTF-8 Mode</span></a>.</p>

  1008. <div class="admonition seealso">

  1009. <p class="admonition-title">See also</p>

  1010. <p>The <a class="reference internal" href="sys.html#c.Py_EncodeLocale" title="Py_EncodeLocale"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_EncodeLocale()</span></code></a> function.</p>

  1011. </div>

  1012. <div class="versionadded">

  1013. <p><span class="versionmodified added">New in version 3.3.</span></p>

  1014. </div>

  1015. <div class="versionchanged">

  1016. <p><span class="versionmodified changed">Changed in version 3.7: </span>The function now also uses the current locale encoding for the

  1017. <code class="docutils literal notranslate"><span class="pre">surrogateescape</span></code> error handler, except on Android. Previously,

  1018. <a class="reference internal" href="sys.html#c.Py_EncodeLocale" title="Py_EncodeLocale"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_EncodeLocale()</span></code></a>

  1019. was used for the <code class="docutils literal notranslate"><span class="pre">surrogateescape</span></code>, and the current locale encoding was

  1020. used for <code class="docutils literal notranslate"><span class="pre">strict</span></code>.</p>

  1021. </div>

  1022. </dd></dl>

  1023. 

  1024. </section>

  1025. <section id="file-system-encoding">

  1026. <h3>File System Encoding<a class="headerlink" href="#file-system-encoding" title="Link to this heading">¶</a></h3>

  1027. <p>Functions encoding to and decoding from the <a class="reference internal" href="../glossary.html#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem encoding and

  1028. error handler</span></a> (<span class="target" id="index-4"></span><a class="pep reference external" href="https://peps.python.org/pep-0383/"><strong>PEP 383</strong></a> and <span class="target" id="index-5"></span><a class="pep reference external" href="https://peps.python.org/pep-0529/"><strong>PEP 529</strong></a>).</p>

  1029. <p>To encode file names to <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> during argument parsing, the <code class="docutils literal notranslate"><span class="pre">&quot;O&amp;&quot;</span></code>

  1030. converter should be used, passing <a class="reference internal" href="#c.PyUnicode_FSConverter" title="PyUnicode_FSConverter"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_FSConverter()</span></code></a> as the

  1031. conversion function:</p>

  1032. <dl class="c function">

  1033. <dt class="sig sig-object c" id="c.PyUnicode_FSConverter">

  1034. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_FSConverter</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">obj</span></span>, <span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">result</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_FSConverter" title="Link to this definition">¶</a><br /></dt>

  1035. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>ParseTuple converter: encode <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> objects – obtained directly or

  1036. through the <a class="reference internal" href="../library/os.html#os.PathLike" title="os.PathLike"><code class="xref py py-class docutils literal notranslate"><span class="pre">os.PathLike</span></code></a> interface – to <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> using

  1037. <a class="reference internal" href="#c.PyUnicode_EncodeFSDefault" title="PyUnicode_EncodeFSDefault"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_EncodeFSDefault()</span></code></a>; <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> objects are output as-is.

  1038. <em>result</em> must be a <span class="c-expr sig sig-inline c"><a class="reference internal" href="bytes.html#c.PyBytesObject" title="PyBytesObject"><span class="n">PyBytesObject</span></a><span class="p">*</span></span> which must be released when it is

  1039. no longer used.</p>

  1040. <div class="versionadded">

  1041. <p><span class="versionmodified added">New in version 3.1.</span></p>

  1042. </div>

  1043. <div class="versionchanged">

  1044. <p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>

  1045. </div>

  1046. </dd></dl>

  1047. 

  1048. <p>To decode file names to <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> during argument parsing, the <code class="docutils literal notranslate"><span class="pre">&quot;O&amp;&quot;</span></code>

  1049. converter should be used, passing <a class="reference internal" href="#c.PyUnicode_FSDecoder" title="PyUnicode_FSDecoder"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_FSDecoder()</span></code></a> as the

  1050. conversion function:</p>

  1051. <dl class="c function">

  1052. <dt class="sig sig-object c" id="c.PyUnicode_FSDecoder">

  1053. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_FSDecoder</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">obj</span></span>, <span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">result</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_FSDecoder" title="Link to this definition">¶</a><br /></dt>

  1054. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>ParseTuple converter: decode <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> objects – obtained either

  1055. directly or indirectly through the <a class="reference internal" href="../library/os.html#os.PathLike" title="os.PathLike"><code class="xref py py-class docutils literal notranslate"><span class="pre">os.PathLike</span></code></a> interface – to

  1056. <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> using <a class="reference internal" href="#c.PyUnicode_DecodeFSDefaultAndSize" title="PyUnicode_DecodeFSDefaultAndSize"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeFSDefaultAndSize()</span></code></a>; <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>

  1057. objects are output as-is. <em>result</em> must be a <span class="c-expr sig sig-inline c"><a class="reference internal" href="#c.PyUnicodeObject" title="PyUnicodeObject"><span class="n">PyUnicodeObject</span></a><span class="p">*</span></span> which

  1058. must be released when it is no longer used.</p>

  1059. <div class="versionadded">

  1060. <p><span class="versionmodified added">New in version 3.2.</span></p>

  1061. </div>

  1062. <div class="versionchanged">

  1063. <p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>

  1064. </div>

  1065. </dd></dl>

  1066. 

  1067. <dl class="c function">

  1068. <dt class="sig sig-object c" id="c.PyUnicode_DecodeFSDefaultAndSize">

  1069. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_DecodeFSDefaultAndSize</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeFSDefaultAndSize" title="Link to this definition">¶</a><br /></dt>

  1070. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Decode a string from the <a class="reference internal" href="../glossary.html#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem encoding and error handler</span></a>.</p>

  1071. <p>If you need to decode a string from the current locale encoding, use

  1072. <a class="reference internal" href="#c.PyUnicode_DecodeLocaleAndSize" title="PyUnicode_DecodeLocaleAndSize"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeLocaleAndSize()</span></code></a>.</p>

  1073. <div class="admonition seealso">

  1074. <p class="admonition-title">See also</p>

  1075. <p>The <a class="reference internal" href="sys.html#c.Py_DecodeLocale" title="Py_DecodeLocale"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DecodeLocale()</span></code></a> function.</p>

  1076. </div>

  1077. <div class="versionchanged">

  1078. <p><span class="versionmodified changed">Changed in version 3.6: </span>The <a class="reference internal" href="../glossary.html#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem error handler</span></a> is now used.</p>

  1079. </div>

  1080. </dd></dl>

  1081. 

  1082. <dl class="c function">

  1083. <dt class="sig sig-object c" id="c.PyUnicode_DecodeFSDefault">

  1084. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_DecodeFSDefault</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeFSDefault" title="Link to this definition">¶</a><br /></dt>

  1085. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Decode a null-terminated string from the <a class="reference internal" href="../glossary.html#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem encoding and

  1086. error handler</span></a>.</p>

  1087. <p>If the string length is known, use

  1088. <a class="reference internal" href="#c.PyUnicode_DecodeFSDefaultAndSize" title="PyUnicode_DecodeFSDefaultAndSize"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeFSDefaultAndSize()</span></code></a>.</p>

  1089. <div class="versionchanged">

  1090. <p><span class="versionmodified changed">Changed in version 3.6: </span>The <a class="reference internal" href="../glossary.html#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem error handler</span></a> is now used.</p>

  1091. </div>

  1092. </dd></dl>

  1093. 

  1094. <dl class="c function">

  1095. <dt class="sig sig-object c" id="c.PyUnicode_EncodeFSDefault">

  1096. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_EncodeFSDefault</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_EncodeFSDefault" title="Link to this definition">¶</a><br /></dt>

  1097. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Encode a Unicode object to the <a class="reference internal" href="../glossary.html#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem encoding and error

  1098. handler</span></a>, and return <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>. Note that the resulting <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>

  1099. object can contain null bytes.</p>

  1100. <p>If you need to encode a string to the current locale encoding, use

  1101. <a class="reference internal" href="#c.PyUnicode_EncodeLocale" title="PyUnicode_EncodeLocale"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_EncodeLocale()</span></code></a>.</p>

  1102. <div class="admonition seealso">

  1103. <p class="admonition-title">See also</p>

  1104. <p>The <a class="reference internal" href="sys.html#c.Py_EncodeLocale" title="Py_EncodeLocale"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_EncodeLocale()</span></code></a> function.</p>

  1105. </div>

  1106. <div class="versionadded">

  1107. <p><span class="versionmodified added">New in version 3.2.</span></p>

  1108. </div>

  1109. <div class="versionchanged">

  1110. <p><span class="versionmodified changed">Changed in version 3.6: </span>The <a class="reference internal" href="../glossary.html#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem error handler</span></a> is now used.</p>

  1111. </div>

  1112. </dd></dl>

  1113. 

  1114. </section>

  1115. <section id="wchar-t-support">

  1116. <h3>wchar_t Support<a class="headerlink" href="#wchar-t-support" title="Link to this heading">¶</a></h3>

  1117. <p><code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code> support for platforms which support it:</p>

  1118. <dl class="c function">

  1119. <dt class="sig sig-object c" id="c.PyUnicode_FromWideChar">

  1120. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_FromWideChar</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="n"><span class="pre">wchar_t</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">wstr</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_FromWideChar" title="Link to this definition">¶</a><br /></dt>

  1121. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Create a Unicode object from the <code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code> buffer <em>wstr</em> of the given <em>size</em>.

  1122. Passing <code class="docutils literal notranslate"><span class="pre">-1</span></code> as the <em>size</em> indicates that the function must itself compute the length,

  1123. using <code class="xref c c-func docutils literal notranslate"><span class="pre">wcslen()</span></code>.

  1124. Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> on failure.</p>

  1125. </dd></dl>

  1126. 

  1127. <dl class="c function">

  1128. <dt class="sig sig-object c" id="c.PyUnicode_AsWideChar">

  1129. <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_AsWideChar</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <span class="n"><span class="pre">wchar_t</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">wstr</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsWideChar" title="Link to this definition">¶</a><br /></dt>

  1130. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Copy the Unicode object contents into the <code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code> buffer <em>wstr</em>.  At most

  1131. <em>size</em> <code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code> characters are copied (excluding a possibly trailing

  1132. null termination character).  Return the number of <code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code> characters

  1133. copied or <code class="docutils literal notranslate"><span class="pre">-1</span></code> in case of an error.</p>

  1134. <p>When <em>wstr</em> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, instead return the <em>size</em> that would be required

  1135. to store all of <em>unicode</em> including a terminating null.</p>

  1136. <p>Note that the resulting <span class="c-expr sig sig-inline c"><span class="n">wchar_t</span><span class="p">*</span></span>

  1137. string may or may not be null-terminated.  It is the responsibility of the caller

  1138. to make sure that the <span class="c-expr sig sig-inline c"><span class="n">wchar_t</span><span class="p">*</span></span> string is null-terminated in case this is

  1139. required by the application. Also, note that the <span class="c-expr sig sig-inline c"><span class="n">wchar_t</span><span class="p">*</span></span> string

  1140. might contain null characters, which would cause the string to be truncated

  1141. when used with most C functions.</p>

  1142. </dd></dl>

  1143. 

  1144. <dl class="c function">

  1145. <dt class="sig sig-object c" id="c.PyUnicode_AsWideCharString">

  1146. <span class="n"><span class="pre">wchar_t</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_AsWideCharString</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">size</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsWideCharString" title="Link to this definition">¶</a><br /></dt>

  1147. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p>Convert the Unicode object to a wide character string. The output string

  1148. always ends with a null character. If <em>size</em> is not <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, write the number

  1149. of wide characters (excluding the trailing null termination character) into

  1150. <em>*size</em>. Note that the resulting <code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code> string might contain

  1151. null characters, which would cause the string to be truncated when used with

  1152. most C functions. If <em>size</em> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code> and the <span class="c-expr sig sig-inline c"><span class="n">wchar_t</span><span class="p">*</span></span> string

  1153. contains null characters a <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> is raised.</p>

  1154. <p>Returns a buffer allocated by <a class="reference internal" href="memory.html#c.PyMem_New" title="PyMem_New"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyMem_New</span></code></a> (use

  1155. <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> to free it) on success. On error, returns <code class="docutils literal notranslate"><span class="pre">NULL</span></code>

  1156. and <em>*size</em> is undefined. Raises a <a class="reference internal" href="../library/exceptions.html#MemoryError" title="MemoryError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">MemoryError</span></code></a> if memory allocation

  1157. is failed.</p>

  1158. <div class="versionadded">

  1159. <p><span class="versionmodified added">New in version 3.2.</span></p>

  1160. </div>

  1161. <div class="versionchanged">

  1162. <p><span class="versionmodified changed">Changed in version 3.7: </span>Raises a <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> if <em>size</em> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code> and the <span class="c-expr sig sig-inline c"><span class="n">wchar_t</span><span class="p">*</span></span>

  1163. string contains null characters.</p>

  1164. </div>

  1165. </dd></dl>

  1166. 

  1167. </section>

  1168. </section>

  1169. <section id="built-in-codecs">

  1170. <span id="builtincodecs"></span><h2>Built-in Codecs<a class="headerlink" href="#built-in-codecs" title="Link to this heading">¶</a></h2>

  1171. <p>Python provides a set of built-in codecs which are written in C for speed. All of

  1172. these codecs are directly usable via the following functions.</p>

  1173. <p>Many of the following APIs take two arguments encoding and errors, and they

  1174. have the same semantics as the ones of the built-in <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a> string object

  1175. constructor.</p>

  1176. <p>Setting encoding to <code class="docutils literal notranslate"><span class="pre">NULL</span></code> causes the default encoding to be used

  1177. which is UTF-8.  The file system calls should use

  1178. <a class="reference internal" href="#c.PyUnicode_FSConverter" title="PyUnicode_FSConverter"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_FSConverter()</span></code></a> for encoding file names. This uses the

  1179. <a class="reference internal" href="../glossary.html#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem encoding and error handler</span></a> internally.</p>

  1180. <p>Error handling is set by errors which may also be set to <code class="docutils literal notranslate"><span class="pre">NULL</span></code> meaning to use

  1181. the default handling defined for the codec.  Default error handling for all

  1182. built-in codecs is “strict” (<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> is raised).</p>

  1183. <p>The codecs all use a similar interface.  Only deviations from the following

  1184. generic ones are documented for simplicity.</p>

  1185. <section id="generic-codecs">

  1186. <h3>Generic Codecs<a class="headerlink" href="#generic-codecs" title="Link to this heading">¶</a></h3>

  1187. <p>These are the generic codec APIs:</p>

  1188. <dl class="c function">

  1189. <dt class="sig sig-object c" id="c.PyUnicode_Decode">

  1190. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_Decode</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">encoding</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Decode" title="Link to this definition">¶</a><br /></dt>

  1191. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Create a Unicode object by decoding <em>size</em> bytes of the encoded string <em>str</em>.

  1192. <em>encoding</em> and <em>errors</em> have the same meaning as the parameters of the same name

  1193. in the <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a> built-in function.  The codec to be used is looked up

  1194. using the Python codec registry.  Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was raised by

  1195. the codec.</p>

  1196. </dd></dl>

  1197. 

  1198. <dl class="c function">

  1199. <dt class="sig sig-object c" id="c.PyUnicode_AsEncodedString">

  1200. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_AsEncodedString</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">encoding</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsEncodedString" title="Link to this definition">¶</a><br /></dt>

  1201. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Encode a Unicode object and return the result as Python bytes object.

  1202. <em>encoding</em> and <em>errors</em> have the same meaning as the parameters of the same

  1203. name in the Unicode <a class="reference internal" href="../library/stdtypes.html#str.encode" title="str.encode"><code class="xref py py-meth docutils literal notranslate"><span class="pre">encode()</span></code></a> method. The codec to be used is looked up

  1204. using the Python codec registry. Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was raised by

  1205. the codec.</p>

  1206. </dd></dl>

  1207. 

  1208. </section>

  1209. <section id="utf-8-codecs">

  1210. <h3>UTF-8 Codecs<a class="headerlink" href="#utf-8-codecs" title="Link to this heading">¶</a></h3>

  1211. <p>These are the UTF-8 codec APIs:</p>

  1212. <dl class="c function">

  1213. <dt class="sig sig-object c" id="c.PyUnicode_DecodeUTF8">

  1214. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_DecodeUTF8</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeUTF8" title="Link to this definition">¶</a><br /></dt>

  1215. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Create a Unicode object by decoding <em>size</em> bytes of the UTF-8 encoded string

  1216. <em>str</em>. Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was raised by the codec.</p>

  1217. </dd></dl>

  1218. 

  1219. <dl class="c function">

  1220. <dt class="sig sig-object c" id="c.PyUnicode_DecodeUTF8Stateful">

  1221. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_DecodeUTF8Stateful</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">consumed</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeUTF8Stateful" title="Link to this definition">¶</a><br /></dt>

  1222. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>If <em>consumed</em> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, behave like <a class="reference internal" href="#c.PyUnicode_DecodeUTF8" title="PyUnicode_DecodeUTF8"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeUTF8()</span></code></a>. If

  1223. <em>consumed</em> is not <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, trailing incomplete UTF-8 byte sequences will not be

  1224. treated as an error. Those bytes will not be decoded and the number of bytes

  1225. that have been decoded will be stored in <em>consumed</em>.</p>

  1226. </dd></dl>

  1227. 

  1228. <dl class="c function">

  1229. <dt class="sig sig-object c" id="c.PyUnicode_AsUTF8String">

  1230. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_AsUTF8String</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsUTF8String" title="Link to this definition">¶</a><br /></dt>

  1231. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Encode a Unicode object using UTF-8 and return the result as Python bytes

  1232. object.  Error handling is “strict”.  Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was

  1233. raised by the codec.</p>

  1234. </dd></dl>

  1235. 

  1236. <dl class="c function">

  1237. <dt class="sig sig-object c" id="c.PyUnicode_AsUTF8AndSize">

  1238. <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_AsUTF8AndSize</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">size</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsUTF8AndSize" title="Link to this definition">¶</a><br /></dt>

  1239. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.10.</em><p>Return a pointer to the UTF-8 encoding of the Unicode object, and

  1240. store the size of the encoded representation (in bytes) in <em>size</em>.  The

  1241. <em>size</em> argument can be <code class="docutils literal notranslate"><span class="pre">NULL</span></code>; in this case no size will be stored.  The

  1242. returned buffer always has an extra null byte appended (not included in

  1243. <em>size</em>), regardless of whether there are any other null code points.</p>

  1244. <p>In the case of an error, <code class="docutils literal notranslate"><span class="pre">NULL</span></code> is returned with an exception set and no

  1245. <em>size</em> is stored.</p>

  1246. <p>This caches the UTF-8 representation of the string in the Unicode object, and

  1247. subsequent calls will return a pointer to the same buffer.  The caller is not

  1248. responsible for deallocating the buffer. The buffer is deallocated and

  1249. pointers to it become invalid when the Unicode object is garbage collected.</p>

  1250. <div class="versionadded">

  1251. <p><span class="versionmodified added">New in version 3.3.</span></p>

  1252. </div>

  1253. <div class="versionchanged">

  1254. <p><span class="versionmodified changed">Changed in version 3.7: </span>The return type is now <code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></code> rather of <code class="docutils literal notranslate"><span class="pre">char</span> <span class="pre">*</span></code>.</p>

  1255. </div>

  1256. <div class="versionchanged">

  1257. <p><span class="versionmodified changed">Changed in version 3.10: </span>This function is a part of the <a class="reference internal" href="stable.html#limited-c-api"><span class="std std-ref">limited API</span></a>.</p>

  1258. </div>

  1259. </dd></dl>

  1260. 

  1261. <dl class="c function">

  1262. <dt class="sig sig-object c" id="c.PyUnicode_AsUTF8">

  1263. <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_AsUTF8</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsUTF8" title="Link to this definition">¶</a><br /></dt>

  1264. <dd><p>As <a class="reference internal" href="#c.PyUnicode_AsUTF8AndSize" title="PyUnicode_AsUTF8AndSize"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_AsUTF8AndSize()</span></code></a>, but does not store the size.</p>

  1265. <div class="versionadded">

  1266. <p><span class="versionmodified added">New in version 3.3.</span></p>

  1267. </div>

  1268. <div class="versionchanged">

  1269. <p><span class="versionmodified changed">Changed in version 3.7: </span>The return type is now <code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></code> rather of <code class="docutils literal notranslate"><span class="pre">char</span> <span class="pre">*</span></code>.</p>

  1270. </div>

  1271. </dd></dl>

  1272. 

  1273. </section>

  1274. <section id="utf-32-codecs">

  1275. <h3>UTF-32 Codecs<a class="headerlink" href="#utf-32-codecs" title="Link to this heading">¶</a></h3>

  1276. <p>These are the UTF-32 codec APIs:</p>

  1277. <dl class="c function">

  1278. <dt class="sig sig-object c" id="c.PyUnicode_DecodeUTF32">

  1279. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_DecodeUTF32</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">byteorder</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeUTF32" title="Link to this definition">¶</a><br /></dt>

  1280. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Decode <em>size</em> bytes from a UTF-32 encoded buffer string and return the

  1281. corresponding Unicode object.  <em>errors</em> (if non-<code class="docutils literal notranslate"><span class="pre">NULL</span></code>) defines the error

  1282. handling. It defaults to “strict”.</p>

  1283. <p>If <em>byteorder</em> is non-<code class="docutils literal notranslate"><span class="pre">NULL</span></code>, the decoder starts decoding using the given byte

  1284. order:</p>

  1285. <div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="o">*</span><span class="n">byteorder</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="mi">-1</span><span class="o">:</span><span class="w"> </span><span class="n">little</span><span class="w"> </span><span class="n">endian</span>

  1286. <span class="o">*</span><span class="n">byteorder</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="mi">0</span><span class="o">:</span><span class="w">  </span><span class="n">native</span><span class="w"> </span><span class="n">order</span>

  1287. <span class="o">*</span><span class="n">byteorder</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="mi">1</span><span class="o">:</span><span class="w">  </span><span class="n">big</span><span class="w"> </span><span class="n">endian</span>

  1288. </pre></div>

  1289. </div>

  1290. <p>If <code class="docutils literal notranslate"><span class="pre">*byteorder</span></code> is zero, and the first four bytes of the input data are a

  1291. byte order mark (BOM), the decoder switches to this byte order and the BOM is

  1292. not copied into the resulting Unicode string.  If <code class="docutils literal notranslate"><span class="pre">*byteorder</span></code> is <code class="docutils literal notranslate"><span class="pre">-1</span></code> or

  1293. <code class="docutils literal notranslate"><span class="pre">1</span></code>, any byte order mark is copied to the output.</p>

  1294. <p>After completion, <em>*byteorder</em> is set to the current byte order at the end

  1295. of input data.</p>

  1296. <p>If <em>byteorder</em> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, the codec starts in native order mode.</p>

  1297. <p>Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was raised by the codec.</p>

  1298. </dd></dl>

  1299. 

  1300. <dl class="c function">

  1301. <dt class="sig sig-object c" id="c.PyUnicode_DecodeUTF32Stateful">

  1302. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_DecodeUTF32Stateful</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">byteorder</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">consumed</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeUTF32Stateful" title="Link to this definition">¶</a><br /></dt>

  1303. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>If <em>consumed</em> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, behave like <a class="reference internal" href="#c.PyUnicode_DecodeUTF32" title="PyUnicode_DecodeUTF32"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeUTF32()</span></code></a>. If

  1304. <em>consumed</em> is not <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, <a class="reference internal" href="#c.PyUnicode_DecodeUTF32Stateful" title="PyUnicode_DecodeUTF32Stateful"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeUTF32Stateful()</span></code></a> will not treat

  1305. trailing incomplete UTF-32 byte sequences (such as a number of bytes not divisible

  1306. by four) as an error. Those bytes will not be decoded and the number of bytes

  1307. that have been decoded will be stored in <em>consumed</em>.</p>

  1308. </dd></dl>

  1309. 

  1310. <dl class="c function">

  1311. <dt class="sig sig-object c" id="c.PyUnicode_AsUTF32String">

  1312. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_AsUTF32String</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsUTF32String" title="Link to this definition">¶</a><br /></dt>

  1313. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a Python byte string using the UTF-32 encoding in native byte

  1314. order. The string always starts with a BOM mark.  Error handling is “strict”.

  1315. Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was raised by the codec.</p>

  1316. </dd></dl>

  1317. 

  1318. </section>

  1319. <section id="utf-16-codecs">

  1320. <h3>UTF-16 Codecs<a class="headerlink" href="#utf-16-codecs" title="Link to this heading">¶</a></h3>

  1321. <p>These are the UTF-16 codec APIs:</p>

  1322. <dl class="c function">

  1323. <dt class="sig sig-object c" id="c.PyUnicode_DecodeUTF16">

  1324. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_DecodeUTF16</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">byteorder</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeUTF16" title="Link to this definition">¶</a><br /></dt>

  1325. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Decode <em>size</em> bytes from a UTF-16 encoded buffer string and return the

  1326. corresponding Unicode object.  <em>errors</em> (if non-<code class="docutils literal notranslate"><span class="pre">NULL</span></code>) defines the error

  1327. handling. It defaults to “strict”.</p>

  1328. <p>If <em>byteorder</em> is non-<code class="docutils literal notranslate"><span class="pre">NULL</span></code>, the decoder starts decoding using the given byte

  1329. order:</p>

  1330. <div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="o">*</span><span class="n">byteorder</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="mi">-1</span><span class="o">:</span><span class="w"> </span><span class="n">little</span><span class="w"> </span><span class="n">endian</span>

  1331. <span class="o">*</span><span class="n">byteorder</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="mi">0</span><span class="o">:</span><span class="w">  </span><span class="n">native</span><span class="w"> </span><span class="n">order</span>

  1332. <span class="o">*</span><span class="n">byteorder</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="mi">1</span><span class="o">:</span><span class="w">  </span><span class="n">big</span><span class="w"> </span><span class="n">endian</span>

  1333. </pre></div>

  1334. </div>

  1335. <p>If <code class="docutils literal notranslate"><span class="pre">*byteorder</span></code> is zero, and the first two bytes of the input data are a

  1336. byte order mark (BOM), the decoder switches to this byte order and the BOM is

  1337. not copied into the resulting Unicode string.  If <code class="docutils literal notranslate"><span class="pre">*byteorder</span></code> is <code class="docutils literal notranslate"><span class="pre">-1</span></code> or

  1338. <code class="docutils literal notranslate"><span class="pre">1</span></code>, any byte order mark is copied to the output (where it will result in

  1339. either a <code class="docutils literal notranslate"><span class="pre">\ufeff</span></code> or a <code class="docutils literal notranslate"><span class="pre">\ufffe</span></code> character).</p>

  1340. <p>After completion, <code class="docutils literal notranslate"><span class="pre">*byteorder</span></code> is set to the current byte order at the end

  1341. of input data.</p>

  1342. <p>If <em>byteorder</em> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, the codec starts in native order mode.</p>

  1343. <p>Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was raised by the codec.</p>

  1344. </dd></dl>

  1345. 

  1346. <dl class="c function">

  1347. <dt class="sig sig-object c" id="c.PyUnicode_DecodeUTF16Stateful">

  1348. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_DecodeUTF16Stateful</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">byteorder</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">consumed</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeUTF16Stateful" title="Link to this definition">¶</a><br /></dt>

  1349. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>If <em>consumed</em> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, behave like <a class="reference internal" href="#c.PyUnicode_DecodeUTF16" title="PyUnicode_DecodeUTF16"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeUTF16()</span></code></a>. If

  1350. <em>consumed</em> is not <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, <a class="reference internal" href="#c.PyUnicode_DecodeUTF16Stateful" title="PyUnicode_DecodeUTF16Stateful"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeUTF16Stateful()</span></code></a> will not treat

  1351. trailing incomplete UTF-16 byte sequences (such as an odd number of bytes or a

  1352. split surrogate pair) as an error. Those bytes will not be decoded and the

  1353. number of bytes that have been decoded will be stored in <em>consumed</em>.</p>

  1354. </dd></dl>

  1355. 

  1356. <dl class="c function">

  1357. <dt class="sig sig-object c" id="c.PyUnicode_AsUTF16String">

  1358. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_AsUTF16String</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsUTF16String" title="Link to this definition">¶</a><br /></dt>

  1359. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a Python byte string using the UTF-16 encoding in native byte

  1360. order. The string always starts with a BOM mark.  Error handling is “strict”.

  1361. Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was raised by the codec.</p>

  1362. </dd></dl>

  1363. 

  1364. </section>

  1365. <section id="utf-7-codecs">

  1366. <h3>UTF-7 Codecs<a class="headerlink" href="#utf-7-codecs" title="Link to this heading">¶</a></h3>

  1367. <p>These are the UTF-7 codec APIs:</p>

  1368. <dl class="c function">

  1369. <dt class="sig sig-object c" id="c.PyUnicode_DecodeUTF7">

  1370. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_DecodeUTF7</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeUTF7" title="Link to this definition">¶</a><br /></dt>

  1371. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Create a Unicode object by decoding <em>size</em> bytes of the UTF-7 encoded string

  1372. <em>str</em>.  Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was raised by the codec.</p>

  1373. </dd></dl>

  1374. 

  1375. <dl class="c function">

  1376. <dt class="sig sig-object c" id="c.PyUnicode_DecodeUTF7Stateful">

  1377. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_DecodeUTF7Stateful</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">consumed</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeUTF7Stateful" title="Link to this definition">¶</a><br /></dt>

  1378. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>If <em>consumed</em> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, behave like <a class="reference internal" href="#c.PyUnicode_DecodeUTF7" title="PyUnicode_DecodeUTF7"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeUTF7()</span></code></a>.  If

  1379. <em>consumed</em> is not <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, trailing incomplete UTF-7 base-64 sections will not

  1380. be treated as an error.  Those bytes will not be decoded and the number of

  1381. bytes that have been decoded will be stored in <em>consumed</em>.</p>

  1382. </dd></dl>

  1383. 

  1384. </section>

  1385. <section id="unicode-escape-codecs">

  1386. <h3>Unicode-Escape Codecs<a class="headerlink" href="#unicode-escape-codecs" title="Link to this heading">¶</a></h3>

  1387. <p>These are the “Unicode Escape” codec APIs:</p>

  1388. <dl class="c function">

  1389. <dt class="sig sig-object c" id="c.PyUnicode_DecodeUnicodeEscape">

  1390. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_DecodeUnicodeEscape</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeUnicodeEscape" title="Link to this definition">¶</a><br /></dt>

  1391. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Create a Unicode object by decoding <em>size</em> bytes of the Unicode-Escape encoded

  1392. string <em>str</em>.  Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was raised by the codec.</p>

  1393. </dd></dl>

  1394. 

  1395. <dl class="c function">

  1396. <dt class="sig sig-object c" id="c.PyUnicode_AsUnicodeEscapeString">

  1397. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_AsUnicodeEscapeString</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsUnicodeEscapeString" title="Link to this definition">¶</a><br /></dt>

  1398. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Encode a Unicode object using Unicode-Escape and return the result as a

  1399. bytes object.  Error handling is “strict”.  Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was

  1400. raised by the codec.</p>

  1401. </dd></dl>

  1402. 

  1403. </section>

  1404. <section id="raw-unicode-escape-codecs">

  1405. <h3>Raw-Unicode-Escape Codecs<a class="headerlink" href="#raw-unicode-escape-codecs" title="Link to this heading">¶</a></h3>

  1406. <p>These are the “Raw Unicode Escape” codec APIs:</p>

  1407. <dl class="c function">

  1408. <dt class="sig sig-object c" id="c.PyUnicode_DecodeRawUnicodeEscape">

  1409. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_DecodeRawUnicodeEscape</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeRawUnicodeEscape" title="Link to this definition">¶</a><br /></dt>

  1410. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Create a Unicode object by decoding <em>size</em> bytes of the Raw-Unicode-Escape

  1411. encoded string <em>str</em>.  Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was raised by the codec.</p>

  1412. </dd></dl>

  1413. 

  1414. <dl class="c function">

  1415. <dt class="sig sig-object c" id="c.PyUnicode_AsRawUnicodeEscapeString">

  1416. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_AsRawUnicodeEscapeString</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsRawUnicodeEscapeString" title="Link to this definition">¶</a><br /></dt>

  1417. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Encode a Unicode object using Raw-Unicode-Escape and return the result as

  1418. a bytes object.  Error handling is “strict”.  Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception

  1419. was raised by the codec.</p>

  1420. </dd></dl>

  1421. 

  1422. </section>

  1423. <section id="latin-1-codecs">

  1424. <h3>Latin-1 Codecs<a class="headerlink" href="#latin-1-codecs" title="Link to this heading">¶</a></h3>

  1425. <p>These are the Latin-1 codec APIs: Latin-1 corresponds to the first 256 Unicode

  1426. ordinals and only these are accepted by the codecs during encoding.</p>

  1427. <dl class="c function">

  1428. <dt class="sig sig-object c" id="c.PyUnicode_DecodeLatin1">

  1429. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_DecodeLatin1</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeLatin1" title="Link to this definition">¶</a><br /></dt>

  1430. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Create a Unicode object by decoding <em>size</em> bytes of the Latin-1 encoded string

  1431. <em>str</em>.  Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was raised by the codec.</p>

  1432. </dd></dl>

  1433. 

  1434. <dl class="c function">

  1435. <dt class="sig sig-object c" id="c.PyUnicode_AsLatin1String">

  1436. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_AsLatin1String</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsLatin1String" title="Link to this definition">¶</a><br /></dt>

  1437. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Encode a Unicode object using Latin-1 and return the result as Python bytes

  1438. object.  Error handling is “strict”.  Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was

  1439. raised by the codec.</p>

  1440. </dd></dl>

  1441. 

  1442. </section>

  1443. <section id="ascii-codecs">

  1444. <h3>ASCII Codecs<a class="headerlink" href="#ascii-codecs" title="Link to this heading">¶</a></h3>

  1445. <p>These are the ASCII codec APIs.  Only 7-bit ASCII data is accepted. All other

  1446. codes generate errors.</p>

  1447. <dl class="c function">

  1448. <dt class="sig sig-object c" id="c.PyUnicode_DecodeASCII">

  1449. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_DecodeASCII</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeASCII" title="Link to this definition">¶</a><br /></dt>

  1450. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Create a Unicode object by decoding <em>size</em> bytes of the ASCII encoded string

  1451. <em>str</em>.  Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was raised by the codec.</p>

  1452. </dd></dl>

  1453. 

  1454. <dl class="c function">

  1455. <dt class="sig sig-object c" id="c.PyUnicode_AsASCIIString">

  1456. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_AsASCIIString</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsASCIIString" title="Link to this definition">¶</a><br /></dt>

  1457. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Encode a Unicode object using ASCII and return the result as Python bytes

  1458. object.  Error handling is “strict”.  Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was

  1459. raised by the codec.</p>

  1460. </dd></dl>

  1461. 

  1462. </section>

  1463. <section id="character-map-codecs">

  1464. <h3>Character Map Codecs<a class="headerlink" href="#character-map-codecs" title="Link to this heading">¶</a></h3>

  1465. <p>This codec is special in that it can be used to implement many different codecs

  1466. (and this is in fact what was done to obtain most of the standard codecs

  1467. included in the <code class="xref py py-mod docutils literal notranslate"><span class="pre">encodings</span></code> package). The codec uses mappings to encode and

  1468. decode characters.  The mapping objects provided must support the

  1469. <a class="reference internal" href="../reference/datamodel.html#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a> mapping interface; dictionaries and sequences work well.</p>

  1470. <p>These are the mapping codec APIs:</p>

  1471. <dl class="c function">

  1472. <dt class="sig sig-object c" id="c.PyUnicode_DecodeCharmap">

  1473. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_DecodeCharmap</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">length</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">mapping</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeCharmap" title="Link to this definition">¶</a><br /></dt>

  1474. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Create a Unicode object by decoding <em>size</em> bytes of the encoded string <em>str</em>

  1475. using the given <em>mapping</em> object.  Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was raised

  1476. by the codec.</p>

  1477. <p>If <em>mapping</em> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, Latin-1 decoding will be applied.  Else

  1478. <em>mapping</em> must map bytes ordinals (integers in the range from 0 to 255)

  1479. to Unicode strings, integers (which are then interpreted as Unicode

  1480. ordinals) or <code class="docutils literal notranslate"><span class="pre">None</span></code>.  Unmapped data bytes – ones which cause a

  1481. <a class="reference internal" href="../library/exceptions.html#LookupError" title="LookupError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">LookupError</span></code></a>, as well as ones which get mapped to <code class="docutils literal notranslate"><span class="pre">None</span></code>,

  1482. <code class="docutils literal notranslate"><span class="pre">0xFFFE</span></code> or <code class="docutils literal notranslate"><span class="pre">'\ufffe'</span></code>, are treated as undefined mappings and cause

  1483. an error.</p>

  1484. </dd></dl>

  1485. 

  1486. <dl class="c function">

  1487. <dt class="sig sig-object c" id="c.PyUnicode_AsCharmapString">

  1488. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_AsCharmapString</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">mapping</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsCharmapString" title="Link to this definition">¶</a><br /></dt>

  1489. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Encode a Unicode object using the given <em>mapping</em> object and return the

  1490. result as a bytes object.  Error handling is “strict”.  Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an

  1491. exception was raised by the codec.</p>

  1492. <p>The <em>mapping</em> object must map Unicode ordinal integers to bytes objects,

  1493. integers in the range from 0 to 255 or <code class="docutils literal notranslate"><span class="pre">None</span></code>.  Unmapped character

  1494. ordinals (ones which cause a <a class="reference internal" href="../library/exceptions.html#LookupError" title="LookupError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">LookupError</span></code></a>) as well as mapped to

  1495. <code class="docutils literal notranslate"><span class="pre">None</span></code> are treated as “undefined mapping” and cause an error.</p>

  1496. </dd></dl>

  1497. 

  1498. <p>The following codec API is special in that maps Unicode to Unicode.</p>

  1499. <dl class="c function">

  1500. <dt class="sig sig-object c" id="c.PyUnicode_Translate">

  1501. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_Translate</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">table</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Translate" title="Link to this definition">¶</a><br /></dt>

  1502. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Translate a string by applying a character mapping table to it and return the

  1503. resulting Unicode object. Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was raised by the

  1504. codec.</p>

  1505. <p>The mapping table must map Unicode ordinal integers to Unicode ordinal integers

  1506. or <code class="docutils literal notranslate"><span class="pre">None</span></code> (causing deletion of the character).</p>

  1507. <p>Mapping tables need only provide the <a class="reference internal" href="../reference/datamodel.html#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a> interface; dictionaries

  1508. and sequences work well.  Unmapped character ordinals (ones which cause a

  1509. <a class="reference internal" href="../library/exceptions.html#LookupError" title="LookupError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">LookupError</span></code></a>) are left untouched and are copied as-is.</p>

  1510. <p><em>errors</em> has the usual meaning for codecs. It may be <code class="docutils literal notranslate"><span class="pre">NULL</span></code> which indicates to

  1511. use the default error handling.</p>

  1512. </dd></dl>

  1513. 

  1514. </section>

  1515. <section id="mbcs-codecs-for-windows">

  1516. <h3>MBCS codecs for Windows<a class="headerlink" href="#mbcs-codecs-for-windows" title="Link to this heading">¶</a></h3>

  1517. <p>These are the MBCS codec APIs. They are currently only available on Windows and

  1518. use the Win32 MBCS converters to implement the conversions.  Note that MBCS (or

  1519. DBCS) is a class of encodings, not just one.  The target encoding is defined by

  1520. the user settings on the machine running the codec.</p>

  1521. <dl class="c function">

  1522. <dt class="sig sig-object c" id="c.PyUnicode_DecodeMBCS">

  1523. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_DecodeMBCS</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeMBCS" title="Link to this definition">¶</a><br /></dt>

  1524. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> on Windows since version 3.7.</em><p>Create a Unicode object by decoding <em>size</em> bytes of the MBCS encoded string <em>str</em>.

  1525. Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was raised by the codec.</p>

  1526. </dd></dl>

  1527. 

  1528. <dl class="c function">

  1529. <dt class="sig sig-object c" id="c.PyUnicode_DecodeMBCSStateful">

  1530. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_DecodeMBCSStateful</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">size</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">consumed</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeMBCSStateful" title="Link to this definition">¶</a><br /></dt>

  1531. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> on Windows since version 3.7.</em><p>If <em>consumed</em> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, behave like <a class="reference internal" href="#c.PyUnicode_DecodeMBCS" title="PyUnicode_DecodeMBCS"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeMBCS()</span></code></a>. If

  1532. <em>consumed</em> is not <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, <a class="reference internal" href="#c.PyUnicode_DecodeMBCSStateful" title="PyUnicode_DecodeMBCSStateful"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeMBCSStateful()</span></code></a> will not decode

  1533. trailing lead byte and the number of bytes that have been decoded will be stored

  1534. in <em>consumed</em>.</p>

  1535. </dd></dl>

  1536. 

  1537. <dl class="c function">

  1538. <dt class="sig sig-object c" id="c.PyUnicode_AsMBCSString">

  1539. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_AsMBCSString</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsMBCSString" title="Link to this definition">¶</a><br /></dt>

  1540. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> on Windows since version 3.7.</em><p>Encode a Unicode object using MBCS and return the result as Python bytes

  1541. object.  Error handling is “strict”.  Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was

  1542. raised by the codec.</p>

  1543. </dd></dl>

  1544. 

  1545. <dl class="c function">

  1546. <dt class="sig sig-object c" id="c.PyUnicode_EncodeCodePage">

  1547. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_EncodeCodePage</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">code_page</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errors</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_EncodeCodePage" title="Link to this definition">¶</a><br /></dt>

  1548. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> on Windows since version 3.7.</em><p>Encode the Unicode object using the specified code page and return a Python

  1549. bytes object.  Return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if an exception was raised by the codec. Use

  1550. <code class="xref c c-macro docutils literal notranslate"><span class="pre">CP_ACP</span></code> code page to get the MBCS encoder.</p>

  1551. <div class="versionadded">

  1552. <p><span class="versionmodified added">New in version 3.3.</span></p>

  1553. </div>

  1554. </dd></dl>

  1555. 

  1556. </section>

  1557. <section id="methods-slots">

  1558. <h3>Methods &amp; Slots<a class="headerlink" href="#methods-slots" title="Link to this heading">¶</a></h3>

  1559. </section>

  1560. </section>

  1561. <section id="methods-and-slot-functions">

  1562. <span id="unicodemethodsandslots"></span><h2>Methods and Slot Functions<a class="headerlink" href="#methods-and-slot-functions" title="Link to this heading">¶</a></h2>

  1563. <p>The following APIs are capable of handling Unicode objects and strings on input

  1564. (we refer to them as strings in the descriptions) and return Unicode objects or

  1565. integers as appropriate.</p>

  1566. <p>They all return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> or <code class="docutils literal notranslate"><span class="pre">-1</span></code> if an exception occurs.</p>

  1567. <dl class="c function">

  1568. <dt class="sig sig-object c" id="c.PyUnicode_Concat">

  1569. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_Concat</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">left</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">right</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Concat" title="Link to this definition">¶</a><br /></dt>

  1570. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Concat two strings giving a new Unicode string.</p>

  1571. </dd></dl>

  1572. 

  1573. <dl class="c function">

  1574. <dt class="sig sig-object c" id="c.PyUnicode_Split">

  1575. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_Split</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">sep</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">maxsplit</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Split" title="Link to this definition">¶</a><br /></dt>

  1576. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Split a string giving a list of Unicode strings.  If <em>sep</em> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, splitting

  1577. will be done at all whitespace substrings.  Otherwise, splits occur at the given

  1578. separator.  At most <em>maxsplit</em> splits will be done.  If negative, no limit is

  1579. set.  Separators are not included in the resulting list.</p>

  1580. </dd></dl>

  1581. 

  1582. <dl class="c function">

  1583. <dt class="sig sig-object c" id="c.PyUnicode_Splitlines">

  1584. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_Splitlines</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">keepends</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Splitlines" title="Link to this definition">¶</a><br /></dt>

  1585. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Split a Unicode string at line breaks, returning a list of Unicode strings.

  1586. CRLF is considered to be one line break.  If <em>keepends</em> is <code class="docutils literal notranslate"><span class="pre">0</span></code>, the Line break

  1587. characters are not included in the resulting strings.</p>

  1588. </dd></dl>

  1589. 

  1590. <dl class="c function">

  1591. <dt class="sig sig-object c" id="c.PyUnicode_Join">

  1592. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_Join</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">separator</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">seq</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Join" title="Link to this definition">¶</a><br /></dt>

  1593. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Join a sequence of strings using the given <em>separator</em> and return the resulting

  1594. Unicode string.</p>

  1595. </dd></dl>

  1596. 

  1597. <dl class="c function">

  1598. <dt class="sig sig-object c" id="c.PyUnicode_Tailmatch">

  1599. <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_Tailmatch</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">substr</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">start</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">end</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">direction</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Tailmatch" title="Link to this definition">¶</a><br /></dt>

  1600. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> if <em>substr</em> matches <code class="docutils literal notranslate"><span class="pre">unicode[start:end]</span></code> at the given tail end

  1601. (<em>direction</em> == <code class="docutils literal notranslate"><span class="pre">-1</span></code> means to do a prefix match, <em>direction</em> == <code class="docutils literal notranslate"><span class="pre">1</span></code> a suffix match),

  1602. <code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise. Return <code class="docutils literal notranslate"><span class="pre">-1</span></code> if an error occurred.</p>

  1603. </dd></dl>

  1604. 

  1605. <dl class="c function">

  1606. <dt class="sig sig-object c" id="c.PyUnicode_Find">

  1607. <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_Find</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">substr</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">start</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">end</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">direction</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Find" title="Link to this definition">¶</a><br /></dt>

  1608. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return the first position of <em>substr</em> in <code class="docutils literal notranslate"><span class="pre">unicode[start:end]</span></code> using the given

  1609. <em>direction</em> (<em>direction</em> == <code class="docutils literal notranslate"><span class="pre">1</span></code> means to do a forward search, <em>direction</em> == <code class="docutils literal notranslate"><span class="pre">-1</span></code> a

  1610. backward search).  The return value is the index of the first match; a value of

  1611. <code class="docutils literal notranslate"><span class="pre">-1</span></code> indicates that no match was found, and <code class="docutils literal notranslate"><span class="pre">-2</span></code> indicates that an error

  1612. occurred and an exception has been set.</p>

  1613. </dd></dl>

  1614. 

  1615. <dl class="c function">

  1616. <dt class="sig sig-object c" id="c.PyUnicode_FindChar">

  1617. <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_FindChar</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <a class="reference internal" href="#c.Py_UCS4" title="Py_UCS4"><span class="n"><span class="pre">Py_UCS4</span></span></a><span class="w"> </span><span class="n"><span class="pre">ch</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">start</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">end</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">direction</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_FindChar" title="Link to this definition">¶</a><br /></dt>

  1618. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p>Return the first position of the character <em>ch</em> in <code class="docutils literal notranslate"><span class="pre">unicode[start:end]</span></code> using

  1619. the given <em>direction</em> (<em>direction</em> == <code class="docutils literal notranslate"><span class="pre">1</span></code> means to do a forward search,

  1620. <em>direction</em> == <code class="docutils literal notranslate"><span class="pre">-1</span></code> a backward search).  The return value is the index of the

  1621. first match; a value of <code class="docutils literal notranslate"><span class="pre">-1</span></code> indicates that no match was found, and <code class="docutils literal notranslate"><span class="pre">-2</span></code>

  1622. indicates that an error occurred and an exception has been set.</p>

  1623. <div class="versionadded">

  1624. <p><span class="versionmodified added">New in version 3.3.</span></p>

  1625. </div>

  1626. <div class="versionchanged">

  1627. <p><span class="versionmodified changed">Changed in version 3.7: </span><em>start</em> and <em>end</em> are now adjusted to behave like <code class="docutils literal notranslate"><span class="pre">unicode[start:end]</span></code>.</p>

  1628. </div>

  1629. </dd></dl>

  1630. 

  1631. <dl class="c function">

  1632. <dt class="sig sig-object c" id="c.PyUnicode_Count">

  1633. <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_Count</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">substr</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">start</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">end</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Count" title="Link to this definition">¶</a><br /></dt>

  1634. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return the number of non-overlapping occurrences of <em>substr</em> in

  1635. <code class="docutils literal notranslate"><span class="pre">unicode[start:end]</span></code>.  Return <code class="docutils literal notranslate"><span class="pre">-1</span></code> if an error occurred.</p>

  1636. </dd></dl>

  1637. 

  1638. <dl class="c function">

  1639. <dt class="sig sig-object c" id="c.PyUnicode_Replace">

  1640. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_Replace</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">substr</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">replstr</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">maxcount</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Replace" title="Link to this definition">¶</a><br /></dt>

  1641. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Replace at most <em>maxcount</em> occurrences of <em>substr</em> in <em>unicode</em> with <em>replstr</em> and

  1642. return the resulting Unicode object. <em>maxcount</em> == <code class="docutils literal notranslate"><span class="pre">-1</span></code> means replace all

  1643. occurrences.</p>

  1644. </dd></dl>

  1645. 

  1646. <dl class="c function">

  1647. <dt class="sig sig-object c" id="c.PyUnicode_Compare">

  1648. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_Compare</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">left</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">right</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Compare" title="Link to this definition">¶</a><br /></dt>

  1649. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Compare two strings and return <code class="docutils literal notranslate"><span class="pre">-1</span></code>, <code class="docutils literal notranslate"><span class="pre">0</span></code>, <code class="docutils literal notranslate"><span class="pre">1</span></code> for less than, equal, and greater than,

  1650. respectively.</p>

  1651. <p>This function returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> upon failure, so one should call

  1652. <a class="reference internal" href="exceptions.html#c.PyErr_Occurred" title="PyErr_Occurred"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_Occurred()</span></code></a> to check for errors.</p>

  1653. </dd></dl>

  1654. 

  1655. <dl class="c function">

  1656. <dt class="sig sig-object c" id="c.PyUnicode_CompareWithASCIIString">

  1657. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_CompareWithASCIIString</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">string</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_CompareWithASCIIString" title="Link to this definition">¶</a><br /></dt>

  1658. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Compare a Unicode object, <em>unicode</em>, with <em>string</em> and return <code class="docutils literal notranslate"><span class="pre">-1</span></code>, <code class="docutils literal notranslate"><span class="pre">0</span></code>, <code class="docutils literal notranslate"><span class="pre">1</span></code> for less

  1659. than, equal, and greater than, respectively. It is best to pass only

  1660. ASCII-encoded strings, but the function interprets the input string as

  1661. ISO-8859-1 if it contains non-ASCII characters.</p>

  1662. <p>This function does not raise exceptions.</p>

  1663. </dd></dl>

  1664. 

  1665. <dl class="c function">

  1666. <dt class="sig sig-object c" id="c.PyUnicode_RichCompare">

  1667. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_RichCompare</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">left</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">right</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">op</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_RichCompare" title="Link to this definition">¶</a><br /></dt>

  1668. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Rich compare two Unicode strings and return one of the following:</p>

  1669. <ul class="simple">

  1670. <li><p><code class="docutils literal notranslate"><span class="pre">NULL</span></code> in case an exception was raised</p></li>

  1671. <li><p><a class="reference internal" href="bool.html#c.Py_True" title="Py_True"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_True</span></code></a> or <a class="reference internal" href="bool.html#c.Py_False" title="Py_False"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_False</span></code></a> for successful comparisons</p></li>

  1672. <li><p><a class="reference internal" href="object.html#c.Py_NotImplemented" title="Py_NotImplemented"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_NotImplemented</span></code></a> in case the type combination is unknown</p></li>

  1673. </ul>

  1674. <p>Possible values for <em>op</em> are <a class="reference internal" href="typeobj.html#c.Py_GT" title="Py_GT"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_GT</span></code></a>, <a class="reference internal" href="typeobj.html#c.Py_GE" title="Py_GE"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_GE</span></code></a>, <a class="reference internal" href="typeobj.html#c.Py_EQ" title="Py_EQ"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_EQ</span></code></a>,

  1675. <a class="reference internal" href="typeobj.html#c.Py_NE" title="Py_NE"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_NE</span></code></a>, <a class="reference internal" href="typeobj.html#c.Py_LT" title="Py_LT"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_LT</span></code></a>, and <a class="reference internal" href="typeobj.html#c.Py_LE" title="Py_LE"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_LE</span></code></a>.</p>

  1676. </dd></dl>

  1677. 

  1678. <dl class="c function">

  1679. <dt class="sig sig-object c" id="c.PyUnicode_Format">

  1680. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_Format</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">format</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Format" title="Link to this definition">¶</a><br /></dt>

  1681. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a new string object from <em>format</em> and <em>args</em>; this is analogous to

  1682. <code class="docutils literal notranslate"><span class="pre">format</span> <span class="pre">%</span> <span class="pre">args</span></code>.</p>

  1683. </dd></dl>

  1684. 

  1685. <dl class="c function">

  1686. <dt class="sig sig-object c" id="c.PyUnicode_Contains">

  1687. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_Contains</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">unicode</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">substr</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Contains" title="Link to this definition">¶</a><br /></dt>

  1688. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Check whether <em>substr</em> is contained in <em>unicode</em> and return true or false

  1689. accordingly.</p>

  1690. <p><em>substr</em> has to coerce to a one element Unicode string. <code class="docutils literal notranslate"><span class="pre">-1</span></code> is returned

  1691. if there was an error.</p>

  1692. </dd></dl>

  1693. 

  1694. <dl class="c function">

  1695. <dt class="sig sig-object c" id="c.PyUnicode_InternInPlace">

  1696. <span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_InternInPlace</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">p_unicode</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_InternInPlace" title="Link to this definition">¶</a><br /></dt>

  1697. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Intern the argument <span class="c-expr sig sig-inline c"><span class="o">*</span><a class="reference internal" href="#c.PyUnicode_InternInPlace" title="p_unicode"><span class="n">p_unicode</span></a></span> in place.  The argument must be the address of a

  1698. pointer variable pointing to a Python Unicode string object.  If there is an

  1699. existing interned string that is the same as <span class="c-expr sig sig-inline c"><span class="o">*</span><a class="reference internal" href="#c.PyUnicode_InternInPlace" title="p_unicode"><span class="n">p_unicode</span></a></span>, it sets <span class="c-expr sig sig-inline c"><span class="o">*</span><a class="reference internal" href="#c.PyUnicode_InternInPlace" title="p_unicode"><span class="n">p_unicode</span></a></span> to

  1700. it (releasing the reference to the old string object and creating a new

  1701. <a class="reference internal" href="../glossary.html#term-strong-reference"><span class="xref std std-term">strong reference</span></a> to the interned string object), otherwise it leaves

  1702. <span class="c-expr sig sig-inline c"><span class="o">*</span><a class="reference internal" href="#c.PyUnicode_InternInPlace" title="p_unicode"><span class="n">p_unicode</span></a></span> alone and interns it (creating a new <a class="reference internal" href="../glossary.html#term-strong-reference"><span class="xref std std-term">strong reference</span></a>).

  1703. (Clarification: even though there is a lot of talk about references, think

  1704. of this function as reference-neutral; you own the object after the call

  1705. if and only if you owned it before the call.)</p>

  1706. </dd></dl>

  1707. 

  1708. <dl class="c function">

  1709. <dt class="sig sig-object c" id="c.PyUnicode_InternFromString">

  1710. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyUnicode_InternFromString</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">str</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_InternFromString" title="Link to this definition">¶</a><br /></dt>

  1711. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>A combination of <a class="reference internal" href="#c.PyUnicode_FromString" title="PyUnicode_FromString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_FromString()</span></code></a> and

  1712. <a class="reference internal" href="#c.PyUnicode_InternInPlace" title="PyUnicode_InternInPlace"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_InternInPlace()</span></code></a>, returning either a new Unicode string

  1713. object that has been interned, or a new (“owned”) reference to an earlier

  1714. interned string object with the same value.</p>

  1715. </dd></dl>

  1716. 

  1717. </section>

  1718. </section>

  1719. 

  1720. 

  1721.             <div class="clearer"></div>

  1722.           </div>

  1723.         </div>

  1724.       </div>

  1725.       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">

  1726.         <div class="sphinxsidebarwrapper">

  1727.   <div>

  1728.     <h3><a href="../contents.html">Table of Contents</a></h3>

  1729.     <ul>

  1730. <li><a class="reference internal" href="#">Unicode Objects and Codecs</a><ul>

  1731. <li><a class="reference internal" href="#unicode-objects">Unicode Objects</a><ul>

  1732. <li><a class="reference internal" href="#unicode-type">Unicode Type</a></li>

  1733. <li><a class="reference internal" href="#unicode-character-properties">Unicode Character Properties</a></li>

  1734. <li><a class="reference internal" href="#creating-and-accessing-unicode-strings">Creating and accessing Unicode strings</a></li>

  1735. <li><a class="reference internal" href="#locale-encoding">Locale Encoding</a></li>

  1736. <li><a class="reference internal" href="#file-system-encoding">File System Encoding</a></li>

  1737. <li><a class="reference internal" href="#wchar-t-support">wchar_t Support</a></li>

  1738. </ul>

  1739. </li>

  1740. <li><a class="reference internal" href="#built-in-codecs">Built-in Codecs</a><ul>

  1741. <li><a class="reference internal" href="#generic-codecs">Generic Codecs</a></li>

  1742. <li><a class="reference internal" href="#utf-8-codecs">UTF-8 Codecs</a></li>

  1743. <li><a class="reference internal" href="#utf-32-codecs">UTF-32 Codecs</a></li>

  1744. <li><a class="reference internal" href="#utf-16-codecs">UTF-16 Codecs</a></li>

  1745. <li><a class="reference internal" href="#utf-7-codecs">UTF-7 Codecs</a></li>

  1746. <li><a class="reference internal" href="#unicode-escape-codecs">Unicode-Escape Codecs</a></li>

  1747. <li><a class="reference internal" href="#raw-unicode-escape-codecs">Raw-Unicode-Escape Codecs</a></li>

  1748. <li><a class="reference internal" href="#latin-1-codecs">Latin-1 Codecs</a></li>

  1749. <li><a class="reference internal" href="#ascii-codecs">ASCII Codecs</a></li>

  1750. <li><a class="reference internal" href="#character-map-codecs">Character Map Codecs</a></li>

  1751. <li><a class="reference internal" href="#mbcs-codecs-for-windows">MBCS codecs for Windows</a></li>

  1752. <li><a class="reference internal" href="#methods-slots">Methods &amp; Slots</a></li>

  1753. </ul>

  1754. </li>

  1755. <li><a class="reference internal" href="#methods-and-slot-functions">Methods and Slot Functions</a></li>

  1756. </ul>

  1757. </li>

  1758. </ul>

  1759. 

  1760.   </div>

  1761.   <div>

  1762.     <h4>Previous topic</h4>

  1763.     <p class="topless"><a href="bytearray.html"

  1764.                           title="previous chapter">Byte Array Objects</a></p>

  1765.   </div>

  1766.   <div>

  1767.     <h4>Next topic</h4>

  1768.     <p class="topless"><a href="tuple.html"

  1769.                           title="next chapter">Tuple Objects</a></p>

  1770.   </div>

  1771.   <div role="note" aria-label="source link">

  1772.     <h3>This Page</h3>

  1773.     <ul class="this-page-menu">

  1774.       <li><a href="../bugs.html">Report a Bug</a></li>

  1775.       <li>

  1776.         <a href="https://github.com/python/cpython/blob/main/Doc/c-api/unicode.rst"

  1777.             rel="nofollow">Show Source

  1778.         </a>

  1779.       </li>

  1780.     </ul>

  1781.   </div>

  1782.         </div>

  1783. <div id="sidebarbutton" title="Collapse sidebar">

  1784. <span>«</span>

  1785. </div>

  1786. 

  1787.       </div>

  1788.       <div class="clearer"></div>

  1789.     </div>  

  1790.     <div class="related" role="navigation" aria-label="related navigation">

  1791.       <h3>Navigation</h3>

  1792.       <ul>

  1793.         <li class="right" style="margin-right: 10px">

  1794.           <a href="../genindex.html" title="General Index"

  1795.              >index</a></li>

  1796.         <li class="right" >

  1797.           <a href="../py-modindex.html" title="Python Module Index"

  1798.              >modules</a> |</li>

  1799.         <li class="right" >

  1800.           <a href="tuple.html" title="Tuple Objects"

  1801.              >next</a> |</li>

  1802.         <li class="right" >

  1803.           <a href="bytearray.html" title="Byte Array Objects"

  1804.              >previous</a> |</li>

  1805. 

  1806.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  1807.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  1808.           <li class="switchers">

  1809.             <div class="language_switcher_placeholder"></div>

  1810.             <div class="version_switcher_placeholder"></div>

  1811.           </li>

  1812.           <li>

  1813.               

  1814.           </li>

  1815.     <li id="cpython-language-and-version">

  1816.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  1817.     </li>

  1818. 

  1819.           <li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> &#187;</li>

  1820.           <li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> &#187;</li>

  1821.         <li class="nav-item nav-item-this"><a href="">Unicode Objects and Codecs</a></li>

  1822.                 <li class="right">

  1823.                     

  1824. 

  1825.     <div class="inline-search" role="search">

  1826.         <form class="inline-search" action="../search.html" method="get">

  1827.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  1828.           <input type="submit" value="Go" />

  1829.         </form>

  1830.     </div>

  1831.                      |

  1832.                 </li>

  1833.             <li class="right">

  1834. <label class="theme-selector-label">

  1835.     Theme

  1836.     <select class="theme-selector" oninput="activateTheme(this.value)">

  1837.         <option value="auto" selected>Auto</option>

  1838.         <option value="light">Light</option>

  1839.         <option value="dark">Dark</option>

  1840.     </select>

  1841. </label> |</li>

  1842.             

  1843.       </ul>

  1844.     </div>  

  1845.     <div class="footer">

  1846.     &copy; 

  1847.       <a href="../copyright.html">

  1848.     

  1849.     Copyright

  1850.     

  1851.       </a>

  1852.      2001-2024, Python Software Foundation.

  1853.     <br />

  1854.     This page is licensed under the Python Software Foundation License Version 2.

  1855.     <br />

  1856.     Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.

  1857.     <br />

  1858.     

  1859.       See <a href="/license.html">History and License</a> for more information.<br />

  1860.     

  1861.     

  1862.     <br />

  1863. 

  1864.     The Python Software Foundation is a non-profit corporation.

  1865. <a href="https://www.python.org/psf/donations/">Please donate.</a>

  1866. <br />

  1867.     <br />

  1868.       Last updated on Apr 09, 2024 (13:47 UTC).

  1869.     

  1870.       <a href="/bugs.html">Found a bug</a>?

  1871.     

  1872.     <br />

  1873. 

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

  1875.     </div>

  1876. 

  1877.   </body>

  1878. </html>
上海开阖软件有限公司 沪ICP备12045867号-1