<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"api.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"api.html" title='Python/C API Reference Manual'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"prev" href=
"tupleObjects.html" />
<link rel=
"parent" href=
"sequenceObjects.html" />
<link rel=
"next" href=
"mapObjects.html" />
<meta name='aesop' content='information'
/>
<title>7.3.5 List Objects
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"7.3.4 Tuple Objects"
href=
"tupleObjects.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"7.3 Sequence Objects"
href=
"sequenceObjects.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"7.4 Mapping Objects"
href=
"mapObjects.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python/C API Reference Manual
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"tupleObjects.html">7.3.4 Tuple Objects
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"sequenceObjects.html">7.3 Sequence Objects
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"mapObjects.html">7.4 Mapping Objects
</A>
<!--End of Navigation Panel-->
<H2><A NAME=
"SECTION009350000000000000000"></A><A NAME=
"listObjects"></A>
<a id='l2h-
579' xml:id='l2h-
579'
></a><dl><dt><b><tt class=
"ctype"><a id='l2h-
580' xml:id='l2h-
580'
>PyListObject
</a></tt></b></dt>
This subtype of
<tt class=
"ctype">PyObject
</tt> represents a Python list object.
<dl><dt>PyTypeObject
<b><tt id='l2h-
581' xml:id='l2h-
581'
class=
"cdata">PyList_Type
</tt></b></dt>
This instance of
<tt class=
"ctype">PyTypeObject
</tt> represents the Python list
type. This is the same object as
<code>types.ListType
</code>.
<a id='l2h-
583' xml:id='l2h-
583'
></a></dd></dl>
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>int
<b><tt id='l2h-
584' xml:id='l2h-
584'
class=
"cfunction">PyList_Check
</tt></b>(
</nobr></td><td>PyObject *
<var>p
</var>)
</td></tr></table></dt>
Return true if
<var>p
</var> is a list object or an instance of a
subtype of the list type.
<span class=
"versionnote">Changed in version
2.2:
Allowed subtypes to be accepted.
</span>
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>int
<b><tt id='l2h-
585' xml:id='l2h-
585'
class=
"cfunction">PyList_CheckExact
</tt></b>(
</nobr></td><td>PyObject *
<var>p
</var>)
</td></tr></table></dt>
Return true if
<var>p
</var> is a list object, but not an instance of a
subtype of the list type.
<span class=
"versionnote">New in version
2.2.
</span>
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>PyObject*
<b><tt id='l2h-
586' xml:id='l2h-
586'
class=
"cfunction">PyList_New
</tt></b>(
</nobr></td><td>int
<var>len
</var>)
</td></tr></table></dt>
<div class=
"refcount-info">
<span class=
"label">Return value:
</span>
<span class=
"value">New reference.
</span>
Return a new list of length
<var>len
</var> on success, or
<tt class=
"constant">NULL
</tt> on
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>int
<b><tt id='l2h-
587' xml:id='l2h-
587'
class=
"cfunction">PyList_Size
</tt></b>(
</nobr></td><td>PyObject *
<var>list
</var>)
</td></tr></table></dt>
Return the length of the list object in
<var>list
</var>; this is
equivalent to
"<tt class="samp
">len(<var>list</var>)</tt>" on a list object.
<a id='l2h-
588' xml:id='l2h-
588'
></a></dd></dl>
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>int
<b><tt id='l2h-
589' xml:id='l2h-
589'
class=
"cfunction">PyList_GET_SIZE
</tt></b>(
</nobr></td><td>PyObject *
<var>list
</var>)
</td></tr></table></dt>
Macro form of
<tt class=
"cfunction">PyList_Size()
</tt> without error checking.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>PyObject*
<b><tt id='l2h-
590' xml:id='l2h-
590'
class=
"cfunction">PyList_GetItem
</tt></b>(
</nobr></td><td>PyObject *
<var>list
</var>, int
<var>index
</var>)
</td></tr></table></dt>
<div class=
"refcount-info">
<span class=
"label">Return value:
</span>
<span class=
"value">Borrowed reference.
</span>
Return the object at position
<var>pos
</var> in the list pointed to by
<var>p
</var>. If
<var>pos
</var> is out of bounds, return
<tt class=
"constant">NULL
</tt> and set an
<tt class=
"exception">IndexError
</tt> exception.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>PyObject*
<b><tt id='l2h-
591' xml:id='l2h-
591'
class=
"cfunction">PyList_GET_ITEM
</tt></b>(
</nobr></td><td>PyObject *
<var>list
</var>, int
<var>i
</var>)
</td></tr></table></dt>
<div class=
"refcount-info">
<span class=
"label">Return value:
</span>
<span class=
"value">Borrowed reference.
</span>
Macro form of
<tt class=
"cfunction">PyList_GetItem()
</tt> without error checking.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>int
<b><tt id='l2h-
592' xml:id='l2h-
592'
class=
"cfunction">PyList_SetItem
</tt></b>(
</nobr></td><td>PyObject *
<var>list
</var>, int
<var>index
</var>,
PyObject *
<var>item
</var>)
</td></tr></table></dt>
Set the item at index
<var>index
</var> in list to
<var>item
</var>. Return
<code>0</code> on success or
<code>-
1</code> on failure.
<span class=
"note"><b class=
"label">Note:
</b>
``steals'' a reference to
<var>item
</var> and discards a reference to an
item already in the list at the affected position.
</span>
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>void
<b><tt id='l2h-
593' xml:id='l2h-
593'
class=
"cfunction">PyList_SET_ITEM
</tt></b>(
</nobr></td><td>PyObject *
<var>list
</var>, int
<var>i
</var>,
PyObject *
<var>o
</var>)
</td></tr></table></dt>
Macro form of
<tt class=
"cfunction">PyList_SetItem()
</tt> without error checking.
This is normally only used to fill in new lists where there is no
<span class=
"note"><b class=
"label">Note:
</b>
This function ``steals'' a reference to
<var>item
</var>, and,
unlike
<tt class=
"cfunction">PyList_SetItem()
</tt>, does
<em>not
</em> discard a
reference to any item that it being replaced; any reference in
<var>list
</var> at position
<var>i
</var> will be leaked.
</span>
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>int
<b><tt id='l2h-
594' xml:id='l2h-
594'
class=
"cfunction">PyList_Insert
</tt></b>(
</nobr></td><td>PyObject *
<var>list
</var>, int
<var>index
</var>,
PyObject *
<var>item
</var>)
</td></tr></table></dt>
Insert the item
<var>item
</var> into list
<var>list
</var> in front of index
<var>index
</var>. Return
<code>0</code> if successful; return
<code>-
1</code> and
set an exception if unsuccessful. Analogous to
<code><var>list
</var>.insert(
<var>index
</var>,
<var>item
</var>)
</code>.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>int
<b><tt id='l2h-
595' xml:id='l2h-
595'
class=
"cfunction">PyList_Append
</tt></b>(
</nobr></td><td>PyObject *
<var>list
</var>, PyObject *
<var>item
</var>)
</td></tr></table></dt>
Append the object
<var>item
</var> at the end of list
<var>list
</var>.
Return
<code>0</code> if successful; return
<code>-
1</code> and set an
exception if unsuccessful. Analogous to
<code><var>list
</var>.append(
<var>item
</var>)
</code>.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>PyObject*
<b><tt id='l2h-
596' xml:id='l2h-
596'
class=
"cfunction">PyList_GetSlice
</tt></b>(
</nobr></td><td>PyObject *
<var>list
</var>,
int
<var>low
</var>, int
<var>high
</var>)
</td></tr></table></dt>
<div class=
"refcount-info">
<span class=
"label">Return value:
</span>
<span class=
"value">New reference.
</span>
Return a list of the objects in
<var>list
</var> containing the objects
<em>between
</em> <var>low
</var> and
<var>high
</var>. Return
<tt class=
"constant">NULL
</tt> and set
an exception if unsuccessful.
Analogous to
<code><var>list
</var>[
<var>low
</var>:
<var>high
</var>]
</code>.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>int
<b><tt id='l2h-
597' xml:id='l2h-
597'
class=
"cfunction">PyList_SetSlice
</tt></b>(
</nobr></td><td>PyObject *
<var>list
</var>,
int
<var>low
</var>, int
<var>high
</var>,
PyObject *
<var>itemlist
</var>)
</td></tr></table></dt>
Set the slice of
<var>list
</var> between
<var>low
</var> and
<var>high
</var> to the
contents of
<var>itemlist
</var>. Analogous to
<code><var>list
</var>[
<var>low
</var>:
<var>high
</var>] =
<var>itemlist
</var></code>.
The
<var>itemlist
</var> may be
<tt class=
"constant">NULL
</tt>, indicating the assignment
of an empty list (slice deletion).
Return
<code>0</code> on success,
<code>-
1</code> on failure.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>int
<b><tt id='l2h-
598' xml:id='l2h-
598'
class=
"cfunction">PyList_Sort
</tt></b>(
</nobr></td><td>PyObject *
<var>list
</var>)
</td></tr></table></dt>
Sort the items of
<var>list
</var> in place. Return
<code>0</code> on
success,
<code>-
1</code> on failure. This is equivalent to
"<tt class="samp
"><var>list</var>.sort()</tt>".
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>int
<b><tt id='l2h-
599' xml:id='l2h-
599'
class=
"cfunction">PyList_Reverse
</tt></b>(
</nobr></td><td>PyObject *
<var>list
</var>)
</td></tr></table></dt>
Reverse the items of
<var>list
</var> in place. Return
<code>0</code> on
success,
<code>-
1</code> on failure. This is the equivalent of
"<tt class="samp
"><var>list</var>.reverse()</tt>".
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>PyObject*
<b><tt id='l2h-
600' xml:id='l2h-
600'
class=
"cfunction">PyList_AsTuple
</tt></b>(
</nobr></td><td>PyObject *
<var>list
</var>)
</td></tr></table></dt>
<div class=
"refcount-info">
<span class=
"label">Return value:
</span>
<span class=
"value">New reference.
</span>
Return a new tuple object containing the contents of
<var>list
</var>;
equivalent to
"<tt class="samp
">tuple(<var>list</var>)</tt>".
<a id='l2h-
601' xml:id='l2h-
601'
></a></dd></dl>
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"7.3.4 Tuple Objects"
href=
"tupleObjects.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"7.3 Sequence Objects"
href=
"sequenceObjects.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"7.4 Mapping Objects"
href=
"mapObjects.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python/C API Reference Manual
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"tupleObjects.html">7.3.4 Tuple Objects
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"sequenceObjects.html">7.3 Sequence Objects
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"mapObjects.html">7.4 Mapping Objects
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.