| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <link rel="STYLESHEET" href="api.css" type='text/css' /> |
| 5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> |
| 6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> |
| 7 | <link rel="first" href="api.html" title='Python/C API Reference Manual' /> |
| 8 | <link rel='contents' href='contents.html' title="Contents" /> |
| 9 | <link rel='index' href='genindex.html' title='Index' /> |
| 10 | <link rel='last' href='about.html' title='About this document...' /> |
| 11 | <link rel='help' href='about.html' title='About this document...' /> |
| 12 | <link rel="prev" href="tupleObjects.html" /> |
| 13 | <link rel="parent" href="sequenceObjects.html" /> |
| 14 | <link rel="next" href="mapObjects.html" /> |
| 15 | <meta name='aesop' content='information' /> |
| 16 | <title>7.3.5 List Objects </title> |
| 17 | </head> |
| 18 | <body> |
| 19 | <DIV CLASS="navigation"> |
| 20 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> |
| 21 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 22 | <tr> |
| 23 | <td class='online-navigation'><a rel="prev" title="7.3.4 Tuple Objects" |
| 24 | href="tupleObjects.html"><img src='../icons/previous.png' |
| 25 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 26 | <td class='online-navigation'><a rel="parent" title="7.3 Sequence Objects" |
| 27 | href="sequenceObjects.html"><img src='../icons/up.png' |
| 28 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 29 | <td class='online-navigation'><a rel="next" title="7.4 Mapping Objects" |
| 30 | href="mapObjects.html"><img src='../icons/next.png' |
| 31 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 32 | <td align="center" width="100%">Python/C API Reference Manual</td> |
| 33 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 34 | href="contents.html"><img src='../icons/contents.png' |
| 35 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 36 | <td class='online-navigation'><img src='../icons/blank.png' |
| 37 | border='0' height='32' alt='' width='32' /></td> |
| 38 | <td class='online-navigation'><a rel="index" title="Index" |
| 39 | href="genindex.html"><img src='../icons/index.png' |
| 40 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 41 | </tr></table> |
| 42 | <div class='online-navigation'> |
| 43 | <b class="navlabel">Previous:</b> |
| 44 | <a class="sectref" rel="prev" href="tupleObjects.html">7.3.4 Tuple Objects</A> |
| 45 | <b class="navlabel">Up:</b> |
| 46 | <a class="sectref" rel="parent" href="sequenceObjects.html">7.3 Sequence Objects</A> |
| 47 | <b class="navlabel">Next:</b> |
| 48 | <a class="sectref" rel="next" href="mapObjects.html">7.4 Mapping Objects</A> |
| 49 | </div> |
| 50 | <hr /></div> |
| 51 | </DIV> |
| 52 | <!--End of Navigation Panel--> |
| 53 | |
| 54 | <H2><A NAME="SECTION009350000000000000000"></A><A NAME="listObjects"></A> |
| 55 | <BR> |
| 56 | 7.3.5 List Objects |
| 57 | </H2> |
| 58 | |
| 59 | <P> |
| 60 | <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> |
| 61 | <dd> |
| 62 | This subtype of <tt class="ctype">PyObject</tt> represents a Python list object. |
| 63 | </dl> |
| 64 | |
| 65 | <P> |
| 66 | <dl><dt>PyTypeObject <b><tt id='l2h-581' xml:id='l2h-581' class="cdata">PyList_Type</tt></b></dt> |
| 67 | <dd> |
| 68 | This instance of <tt class="ctype">PyTypeObject</tt> represents the Python list |
| 69 | type. This is the same object as <code>types.ListType</code>. |
| 70 | <a id='l2h-583' xml:id='l2h-583'></a></dd></dl> |
| 71 | |
| 72 | <P> |
| 73 | <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> |
| 74 | <dd> |
| 75 | Return true if <var>p</var> is a list object or an instance of a |
| 76 | subtype of the list type. |
| 77 | |
| 78 | <span class="versionnote">Changed in version 2.2: |
| 79 | Allowed subtypes to be accepted.</span> |
| 80 | |
| 81 | </dd></dl> |
| 82 | |
| 83 | <P> |
| 84 | <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> |
| 85 | <dd> |
| 86 | Return true if <var>p</var> is a list object, but not an instance of a |
| 87 | subtype of the list type. |
| 88 | |
| 89 | <span class="versionnote">New in version 2.2.</span> |
| 90 | |
| 91 | </dd></dl> |
| 92 | |
| 93 | <P> |
| 94 | <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> |
| 95 | <dd> |
| 96 | <div class="refcount-info"> |
| 97 | <span class="label">Return value:</span> |
| 98 | <span class="value">New reference.</span> |
| 99 | </div> |
| 100 | Return a new list of length <var>len</var> on success, or <tt class="constant">NULL</tt> on |
| 101 | failure. |
| 102 | </dd></dl> |
| 103 | |
| 104 | <P> |
| 105 | <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> |
| 106 | <dd> |
| 107 | Return the length of the list object in <var>list</var>; this is |
| 108 | equivalent to "<tt class="samp">len(<var>list</var>)</tt>" on a list object. |
| 109 | <a id='l2h-588' xml:id='l2h-588'></a></dd></dl> |
| 110 | |
| 111 | <P> |
| 112 | <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> |
| 113 | <dd> |
| 114 | Macro form of <tt class="cfunction">PyList_Size()</tt> without error checking. |
| 115 | </dd></dl> |
| 116 | |
| 117 | <P> |
| 118 | <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> |
| 119 | <dd> |
| 120 | <div class="refcount-info"> |
| 121 | <span class="label">Return value:</span> |
| 122 | <span class="value">Borrowed reference.</span> |
| 123 | </div> |
| 124 | Return the object at position <var>pos</var> in the list pointed to by |
| 125 | <var>p</var>. If <var>pos</var> is out of bounds, return <tt class="constant">NULL</tt> and set an |
| 126 | <tt class="exception">IndexError</tt> exception. |
| 127 | </dd></dl> |
| 128 | |
| 129 | <P> |
| 130 | <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> |
| 131 | <dd> |
| 132 | <div class="refcount-info"> |
| 133 | <span class="label">Return value:</span> |
| 134 | <span class="value">Borrowed reference.</span> |
| 135 | </div> |
| 136 | Macro form of <tt class="cfunction">PyList_GetItem()</tt> without error checking. |
| 137 | </dd></dl> |
| 138 | |
| 139 | <P> |
| 140 | <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>, |
| 141 | PyObject *<var>item</var>)</td></tr></table></dt> |
| 142 | <dd> |
| 143 | Set the item at index <var>index</var> in list to <var>item</var>. Return |
| 144 | <code>0</code> on success or <code>-1</code> on failure. <span class="note"><b class="label">Note:</b> |
| 145 | This function |
| 146 | ``steals'' a reference to <var>item</var> and discards a reference to an |
| 147 | item already in the list at the affected position.</span> |
| 148 | </dd></dl> |
| 149 | |
| 150 | <P> |
| 151 | <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>, |
| 152 | PyObject *<var>o</var>)</td></tr></table></dt> |
| 153 | <dd> |
| 154 | Macro form of <tt class="cfunction">PyList_SetItem()</tt> without error checking. |
| 155 | This is normally only used to fill in new lists where there is no |
| 156 | previous content. |
| 157 | <span class="note"><b class="label">Note:</b> |
| 158 | This function ``steals'' a reference to <var>item</var>, and, |
| 159 | unlike <tt class="cfunction">PyList_SetItem()</tt>, does <em>not</em> discard a |
| 160 | reference to any item that it being replaced; any reference in |
| 161 | <var>list</var> at position <var>i</var> will be leaked.</span> |
| 162 | </dd></dl> |
| 163 | |
| 164 | <P> |
| 165 | <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>, |
| 166 | PyObject *<var>item</var>)</td></tr></table></dt> |
| 167 | <dd> |
| 168 | Insert the item <var>item</var> into list <var>list</var> in front of index |
| 169 | <var>index</var>. Return <code>0</code> if successful; return <code>-1</code> and |
| 170 | set an exception if unsuccessful. Analogous to |
| 171 | <code><var>list</var>.insert(<var>index</var>, <var>item</var>)</code>. |
| 172 | </dd></dl> |
| 173 | |
| 174 | <P> |
| 175 | <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> |
| 176 | <dd> |
| 177 | Append the object <var>item</var> at the end of list <var>list</var>. |
| 178 | Return <code>0</code> if successful; return <code>-1</code> and set an |
| 179 | exception if unsuccessful. Analogous to |
| 180 | <code><var>list</var>.append(<var>item</var>)</code>. |
| 181 | </dd></dl> |
| 182 | |
| 183 | <P> |
| 184 | <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>, |
| 185 | int <var>low</var>, int <var>high</var>)</td></tr></table></dt> |
| 186 | <dd> |
| 187 | <div class="refcount-info"> |
| 188 | <span class="label">Return value:</span> |
| 189 | <span class="value">New reference.</span> |
| 190 | </div> |
| 191 | Return a list of the objects in <var>list</var> containing the objects |
| 192 | <em>between</em> <var>low</var> and <var>high</var>. Return <tt class="constant">NULL</tt> and set |
| 193 | an exception if unsuccessful. |
| 194 | Analogous to <code><var>list</var>[<var>low</var>:<var>high</var>]</code>. |
| 195 | </dd></dl> |
| 196 | |
| 197 | <P> |
| 198 | <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>, |
| 199 | int <var>low</var>, int <var>high</var>, |
| 200 | PyObject *<var>itemlist</var>)</td></tr></table></dt> |
| 201 | <dd> |
| 202 | Set the slice of <var>list</var> between <var>low</var> and <var>high</var> to the |
| 203 | contents of <var>itemlist</var>. Analogous to |
| 204 | <code><var>list</var>[<var>low</var>:<var>high</var>] = <var>itemlist</var></code>. |
| 205 | The <var>itemlist</var> may be <tt class="constant">NULL</tt>, indicating the assignment |
| 206 | of an empty list (slice deletion). |
| 207 | Return <code>0</code> on success, <code>-1</code> on failure. |
| 208 | </dd></dl> |
| 209 | |
| 210 | <P> |
| 211 | <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> |
| 212 | <dd> |
| 213 | Sort the items of <var>list</var> in place. Return <code>0</code> on |
| 214 | success, <code>-1</code> on failure. This is equivalent to |
| 215 | "<tt class="samp"><var>list</var>.sort()</tt>". |
| 216 | </dd></dl> |
| 217 | |
| 218 | <P> |
| 219 | <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> |
| 220 | <dd> |
| 221 | Reverse the items of <var>list</var> in place. Return <code>0</code> on |
| 222 | success, <code>-1</code> on failure. This is the equivalent of |
| 223 | "<tt class="samp"><var>list</var>.reverse()</tt>". |
| 224 | </dd></dl> |
| 225 | |
| 226 | <P> |
| 227 | <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> |
| 228 | <dd> |
| 229 | <div class="refcount-info"> |
| 230 | <span class="label">Return value:</span> |
| 231 | <span class="value">New reference.</span> |
| 232 | </div> |
| 233 | Return a new tuple object containing the contents of <var>list</var>; |
| 234 | equivalent to "<tt class="samp">tuple(<var>list</var>)</tt>".<a id='l2h-601' xml:id='l2h-601'></a></dd></dl> |
| 235 | |
| 236 | <P> |
| 237 | |
| 238 | <DIV CLASS="navigation"> |
| 239 | <div class='online-navigation'> |
| 240 | <p></p><hr /> |
| 241 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 242 | <tr> |
| 243 | <td class='online-navigation'><a rel="prev" title="7.3.4 Tuple Objects" |
| 244 | href="tupleObjects.html"><img src='../icons/previous.png' |
| 245 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 246 | <td class='online-navigation'><a rel="parent" title="7.3 Sequence Objects" |
| 247 | href="sequenceObjects.html"><img src='../icons/up.png' |
| 248 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 249 | <td class='online-navigation'><a rel="next" title="7.4 Mapping Objects" |
| 250 | href="mapObjects.html"><img src='../icons/next.png' |
| 251 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 252 | <td align="center" width="100%">Python/C API Reference Manual</td> |
| 253 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 254 | href="contents.html"><img src='../icons/contents.png' |
| 255 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 256 | <td class='online-navigation'><img src='../icons/blank.png' |
| 257 | border='0' height='32' alt='' width='32' /></td> |
| 258 | <td class='online-navigation'><a rel="index" title="Index" |
| 259 | href="genindex.html"><img src='../icons/index.png' |
| 260 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 261 | </tr></table> |
| 262 | <div class='online-navigation'> |
| 263 | <b class="navlabel">Previous:</b> |
| 264 | <a class="sectref" rel="prev" href="tupleObjects.html">7.3.4 Tuple Objects</A> |
| 265 | <b class="navlabel">Up:</b> |
| 266 | <a class="sectref" rel="parent" href="sequenceObjects.html">7.3 Sequence Objects</A> |
| 267 | <b class="navlabel">Next:</b> |
| 268 | <a class="sectref" rel="next" href="mapObjects.html">7.4 Mapping Objects</A> |
| 269 | </div> |
| 270 | </div> |
| 271 | <hr /> |
| 272 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 273 | </DIV> |
| 274 | <!--End of Navigation Panel--> |
| 275 | <ADDRESS> |
| 276 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 277 | </ADDRESS> |
| 278 | </BODY> |
| 279 | </HTML> |