sam-t2/devtools/amd64/html/python/api/tupleObjects.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<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="next" href="listObjects.html" />
<link rel="prev" href="bufferObjects.html" />
<link rel="parent" href="sequenceObjects.html" />
<link rel="next" href="listObjects.html" />
<meta name='aesop' content='information' />
<title>7.3.4 Tuple Objects </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="7.3.3 Buffer Objects"
  href="bufferObjects.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.3.5 List Objects"
  href="listObjects.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>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="bufferObjects.html">7.3.3 Buffer 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="listObjects.html">7.3.5 List Objects</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION009340000000000000000"></A><A NAME="tupleObjects"></A>
<BR>
7.3.4 Tuple Objects
</H2>

<P>
<a id='l2h-562' xml:id='l2h-562'></a><dl><dt><b><tt class="ctype"><a id='l2h-563' xml:id='l2h-563'>PyTupleObject</a></tt></b></dt>
<dd>
  This subtype of <tt class="ctype">PyObject</tt> represents a Python tuple object.
</dl>

<P>
<dl><dt>PyTypeObject <b><tt id='l2h-564' xml:id='l2h-564' class="cdata">PyTuple_Type</tt></b></dt>
<dd>
  This instance of <tt class="ctype">PyTypeObject</tt> represents the Python tuple
  type; it is the same object as <code>types.TupleType</code> in the Python
  layer.<a id='l2h-566' xml:id='l2h-566'></a>.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-567' xml:id='l2h-567' class="cfunction">PyTuple_Check</tt></b>(</nobr></td><td>PyObject *<var>p</var>)</td></tr></table></dt>
<dd>
  Return true if <var>p</var> is a tuple object or an instance of a subtype
  of the tuple type.

<span class="versionnote">Changed in version 2.2:
Allowed subtypes to be accepted.</span>

</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-568' xml:id='l2h-568' class="cfunction">PyTuple_CheckExact</tt></b>(</nobr></td><td>PyObject *<var>p</var>)</td></tr></table></dt>
<dd>
  Return true if <var>p</var> is a tuple object, but not an instance of a
  subtype of the tuple type.

<span class="versionnote">New in version 2.2.</span>

</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-569' xml:id='l2h-569' class="cfunction">PyTuple_New</tt></b>(</nobr></td><td>int <var>len</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">New reference.</span>
</div>
  Return a new tuple object of size <var>len</var>, or <tt class="constant">NULL</tt> on failure.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-570' xml:id='l2h-570' class="cfunction">PyTuple_Pack</tt></b>(</nobr></td><td>int <var>n</var>, ...)</td></tr></table></dt>
<dd>
  Return a new tuple object of size <var>n</var>, or <tt class="constant">NULL</tt> on failure.
  The tuple values are initialized to the subsequent <var>n</var> C arguments
  pointing to Python objects.  "<tt class="samp">PyTuple_Pack(2, <var>a</var>, <var>b</var>)</tt>"  is equivalent to "<tt class="samp">Py_BuildValue("(OO)", <var>a</var>, <var>b</var>)</tt>".

<span class="versionnote">New in version 2.4.</span>

</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-571' xml:id='l2h-571' class="cfunction">PyTuple_Size</tt></b>(</nobr></td><td>PyObject *<var>p</var>)</td></tr></table></dt>
<dd>
  Take a pointer to a tuple object, and return the size of that
  tuple.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-572' xml:id='l2h-572' class="cfunction">PyTuple_GET_SIZE</tt></b>(</nobr></td><td>PyObject *<var>p</var>)</td></tr></table></dt>
<dd>
  Return the size of the tuple <var>p</var>, which must be non-<tt class="constant">NULL</tt> and
  point to a tuple; no error checking is performed.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-573' xml:id='l2h-573' class="cfunction">PyTuple_GetItem</tt></b>(</nobr></td><td>PyObject *<var>p</var>, int <var>pos</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">Borrowed reference.</span>
</div>
  Return the object at position <var>pos</var> in the tuple pointed to by
  <var>p</var>.  If <var>pos</var> is out of bounds, return <tt class="constant">NULL</tt> and sets an
  <tt class="exception">IndexError</tt> exception.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-574' xml:id='l2h-574' class="cfunction">PyTuple_GET_ITEM</tt></b>(</nobr></td><td>PyObject *<var>p</var>, int <var>pos</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">Borrowed reference.</span>
</div>
  Like <tt class="cfunction">PyTuple_GetItem()</tt>, but does no checking of its
  arguments.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-575' xml:id='l2h-575' class="cfunction">PyTuple_GetSlice</tt></b>(</nobr></td><td>PyObject *<var>p</var>,
                                               int <var>low</var>, int <var>high</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">New reference.</span>
</div>
  Take a slice of the tuple pointed to by <var>p</var> from <var>low</var> to
  <var>high</var> and return it as a new tuple.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-576' xml:id='l2h-576' class="cfunction">PyTuple_SetItem</tt></b>(</nobr></td><td>PyObject *<var>p</var>,
                                        int <var>pos</var>, PyObject *<var>o</var>)</td></tr></table></dt>
<dd>
  Insert a reference to object <var>o</var> at position <var>pos</var> of the
  tuple pointed to by <var>p</var>. Return <code>0</code> on success.
  <span class="note"><b class="label">Note:</b>
This function ``steals'' a reference to <var>o</var>.</span>
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-577' xml:id='l2h-577' class="cfunction">PyTuple_SET_ITEM</tt></b>(</nobr></td><td>PyObject *<var>p</var>,
                                          int <var>pos</var>, PyObject *<var>o</var>)</td></tr></table></dt>
<dd>
  Like <tt class="cfunction">PyTuple_SetItem()</tt>, but does no error checking, and
  should <em>only</em> be used to fill in brand new tuples.  <span class="note"><b class="label">Note:</b>
This
  function ``steals'' a reference to <var>o</var>.</span>
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-578' xml:id='l2h-578' class="cfunction">_PyTuple_Resize</tt></b>(</nobr></td><td>PyObject **<var>p</var>, int <var>newsize</var>)</td></tr></table></dt>
<dd>
  Can be used to resize a tuple.  <var>newsize</var> will be the new length
  of the tuple.  Because tuples are <em>supposed</em> to be immutable,
  this should only be used if there is only one reference to the
  object.  Do <em>not</em> use this if the tuple may already be known to
  some other part of the code.  The tuple will always grow or shrink
  at the end.  Think of this as destroying the old tuple and creating
  a new one, only more efficiently.  Returns <code>0</code> on success.
  Client code should never assume that the resulting value of
  <code>*<var>p</var></code> will be the same as before calling this function.
  If the object referenced by <code>*<var>p</var></code> is replaced, the
  original <code>*<var>p</var></code> is destroyed.  On failure, returns
  <code>-1</code> and sets <code>*<var>p</var></code> to <tt class="constant">NULL</tt>, and raises
  <tt class="exception">MemoryError</tt> or
  <tt class="exception">SystemError</tt>.

<span class="versionnote">Changed in version 2.2:
Removed unused third parameter, <var>last_is_sticky</var>.</span>

</dd></dl>

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="7.3.3 Buffer Objects"
  href="bufferObjects.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.3.5 List Objects"
  href="listObjects.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>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="bufferObjects.html">7.3.3 Buffer 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="listObjects.html">7.3.5 List Objects</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>