python-project/python-3.7.4-docs-html/c-api/list.html
Caleb Fontenot 335515d331 add files
2019-07-15 09:16:41 -07:00

342 lines
22 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title>List Objects &#8212; Python 3.7.4 documentation</title>
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/language_data.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.7.4 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Dictionary Objects" href="dict.html" />
<link rel="prev" title="Tuple Objects" href="tuple.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/3/c-api/list.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/switchers.js"></script>
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="dict.html" title="Dictionary Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="tuple.html" title="Tuple Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li>
<span class="language_switcher_placeholder">en</span>
<span class="version_switcher_placeholder">3.7.4</span>
<a href="../index.html">Documentation </a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> &#187;</li>
<li class="right">
<div class="inline-search" style="display: none" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('.inline-search').show(0);</script>
|
</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="list-objects">
<span id="listobjects"></span><h1>List Objects<a class="headerlink" href="#list-objects" title="Permalink to this headline"></a></h1>
<span class="target" id="index-0"></span><dl class="type">
<dt id="c.PyListObject">
<code class="descname">PyListObject</code><a class="headerlink" href="#c.PyListObject" title="Permalink to this definition"></a></dt>
<dd><p>This subtype 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> represents a Python list object.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyList_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyList_Type</code><a class="headerlink" href="#c.PyList_Type" title="Permalink to this definition"></a></dt>
<dd><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 list type.
This is the same object as <a class="reference internal" href="../library/stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a> in the Python layer.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyList_Check">
int <code class="descname">PyList_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_Check" title="Permalink to this definition"></a></dt>
<dd><p>Return true if <em>p</em> is a list object or an instance of a subtype of the list
type.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyList_CheckExact">
int <code class="descname">PyList_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_CheckExact" title="Permalink to this definition"></a></dt>
<dd><p>Return true if <em>p</em> is a list object, but not an instance of a subtype of
the list type.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyList_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyList_New</code><span class="sig-paren">(</span>Py_ssize_t<em> len</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_New" title="Permalink to this definition"></a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new list of length <em>len</em> on success, or <em>NULL</em> on failure.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If <em>len</em> is greater than zero, the returned list objects items are
set to <code class="docutils literal notranslate"><span class="pre">NULL</span></code>. Thus you cannot use abstract API functions such as
<a class="reference internal" href="sequence.html#c.PySequence_SetItem" title="PySequence_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_SetItem()</span></code></a> or expose the object to Python code before
setting all items to a real object with <a class="reference internal" href="#c.PyList_SetItem" title="PyList_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyList_SetItem()</span></code></a>.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyList_Size">
Py_ssize_t <code class="descname">PyList_Size</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_Size" title="Permalink to this definition"></a></dt>
<dd><p id="index-1">Return the length of the list object in <em>list</em>; this is equivalent to
<code class="docutils literal notranslate"><span class="pre">len(list)</span></code> on a list object.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyList_GET_SIZE">
Py_ssize_t <code class="descname">PyList_GET_SIZE</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_GET_SIZE" title="Permalink to this definition"></a></dt>
<dd><p>Macro form of <a class="reference internal" href="#c.PyList_Size" title="PyList_Size"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyList_Size()</span></code></a> without error checking.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyList_GetItem">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyList_GetItem</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em>, Py_ssize_t<em> index</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_GetItem" title="Permalink to this definition"></a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the object at position <em>index</em> in the list pointed to by <em>list</em>. The
position must be non-negative; indexing from the end of the list is not
supported. If <em>index</em> is out of bounds (&lt;0 or &gt;=len(list)),
return <em>NULL</em> and set an <a class="reference internal" href="../library/exceptions.html#IndexError" title="IndexError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IndexError</span></code></a> exception.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyList_GET_ITEM">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyList_GET_ITEM</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em>, Py_ssize_t<em> i</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_GET_ITEM" title="Permalink to this definition"></a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Macro form of <a class="reference internal" href="#c.PyList_GetItem" title="PyList_GetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyList_GetItem()</span></code></a> without error checking.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyList_SetItem">
int <code class="descname">PyList_SetItem</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em>, Py_ssize_t<em> index</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *item</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_SetItem" title="Permalink to this definition"></a></dt>
<dd><p>Set the item at index <em>index</em> in list to <em>item</em>. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success
or <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This function “steals” a reference to <em>item</em> and discards a reference to
an item already in the list at the affected position.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyList_SET_ITEM">
void <code class="descname">PyList_SET_ITEM</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em>, Py_ssize_t<em> i</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_SET_ITEM" title="Permalink to this definition"></a></dt>
<dd><p>Macro form of <a class="reference internal" href="#c.PyList_SetItem" title="PyList_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyList_SetItem()</span></code></a> without error checking. This is
normally only used to fill in new lists where there is no previous content.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This macro “steals” a reference to <em>item</em>, and, unlike
<a class="reference internal" href="#c.PyList_SetItem" title="PyList_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyList_SetItem()</span></code></a>, does <em>not</em> discard a reference to any item that
is being replaced; any reference in <em>list</em> at position <em>i</em> will be
leaked.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyList_Insert">
int <code class="descname">PyList_Insert</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em>, Py_ssize_t<em> index</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *item</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_Insert" title="Permalink to this definition"></a></dt>
<dd><p>Insert the item <em>item</em> into list <em>list</em> in front of index <em>index</em>. Return
<code class="docutils literal notranslate"><span class="pre">0</span></code> if successful; return <code class="docutils literal notranslate"><span class="pre">-1</span></code> and set an exception if unsuccessful.
Analogous to <code class="docutils literal notranslate"><span class="pre">list.insert(index,</span> <span class="pre">item)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyList_Append">
int <code class="descname">PyList_Append</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *item</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_Append" title="Permalink to this definition"></a></dt>
<dd><p>Append the object <em>item</em> at the end of list <em>list</em>. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> if
successful; return <code class="docutils literal notranslate"><span class="pre">-1</span></code> and set an exception if unsuccessful. Analogous
to <code class="docutils literal notranslate"><span class="pre">list.append(item)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyList_GetSlice">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyList_GetSlice</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em>, Py_ssize_t<em> low</em>, Py_ssize_t<em> high</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_GetSlice" title="Permalink to this definition"></a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a list of the objects in <em>list</em> containing the objects <em>between</em> <em>low</em>
and <em>high</em>. Return <em>NULL</em> and set an exception if unsuccessful. Analogous
to <code class="docutils literal notranslate"><span class="pre">list[low:high]</span></code>. Negative indices, as when slicing from Python, are not
supported.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyList_SetSlice">
int <code class="descname">PyList_SetSlice</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em>, Py_ssize_t<em> low</em>, Py_ssize_t<em> high</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *itemlist</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_SetSlice" title="Permalink to this definition"></a></dt>
<dd><p>Set the slice of <em>list</em> between <em>low</em> and <em>high</em> to the contents of
<em>itemlist</em>. Analogous to <code class="docutils literal notranslate"><span class="pre">list[low:high]</span> <span class="pre">=</span> <span class="pre">itemlist</span></code>. The <em>itemlist</em> may
be <em>NULL</em>, indicating the assignment of an empty list (slice deletion).
Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success, <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure. Negative indices, as when
slicing from Python, are not supported.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyList_Sort">
int <code class="descname">PyList_Sort</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_Sort" title="Permalink to this definition"></a></dt>
<dd><p>Sort the items of <em>list</em> in place. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success, <code class="docutils literal notranslate"><span class="pre">-1</span></code> on
failure. This is equivalent to <code class="docutils literal notranslate"><span class="pre">list.sort()</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyList_Reverse">
int <code class="descname">PyList_Reverse</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_Reverse" title="Permalink to this definition"></a></dt>
<dd><p>Reverse the items of <em>list</em> in place. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success, <code class="docutils literal notranslate"><span class="pre">-1</span></code> on
failure. This is the equivalent of <code class="docutils literal notranslate"><span class="pre">list.reverse()</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyList_AsTuple">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyList_AsTuple</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_AsTuple" title="Permalink to this definition"></a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-2">Return a new tuple object containing the contents of <em>list</em>; equivalent to
<code class="docutils literal notranslate"><span class="pre">tuple(list)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyList_ClearFreeList">
int <code class="descname">PyList_ClearFreeList</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_ClearFreeList" title="Permalink to this definition"></a></dt>
<dd><p>Clear the free list. Return the total number of freed items.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.3.</span></p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="tuple.html"
title="previous chapter">Tuple Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="dict.html"
title="next chapter">Dictionary Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.7/Doc/c-api/list.rst"
rel="nofollow">Show Source
</a>
</li>
</ul>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="dict.html" title="Dictionary Objects"
>next</a> |</li>
<li class="right" >
<a href="tuple.html" title="Tuple Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li>
<span class="language_switcher_placeholder">en</span>
<span class="version_switcher_placeholder">3.7.4</span>
<a href="../index.html">Documentation </a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> &#187;</li>
<li class="right">
<div class="inline-search" style="display: none" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('.inline-search').show(0);</script>
|
</li>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Jul 13, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
</div>
</body>
</html>