203:3
 s    .. highlightlang:: c

.. _tupleobjects:

Tuple Objects
-------------

.. index:: object: tuple


.. c:type:: PyTupleObject

   This subtype of :c:type:`PyObject` represents a Python tuple object.


.. c:var:: PyTypeObject PyTuple_Type

   .. index:: single: TupleType (in module types)

   This instance of :c:type:`PyTypeObject` represents the Python tuple type; it is
   the same object as ``tuple`` and ``types.TupleType`` in the Python layer..


.. c:function:: int PyTuple_Check(PyObject *p)

   Return true if *p* is a tuple object or an instance of a subtype of the tuple
   type.

   .. versionchanged:: 2.2
      Allowed subtypes to be accepted.


.. c:function:: int PyTuple_CheckExact(PyObject *p)

   Return true if *p* is a tuple object, but not an instance of a subtype of the
   tuple type.

   .. versionadded:: 2.2


.. c:function:: PyObject* PyTuple_New(Py_ssize_t len)

   Return a new tuple object of size *len*, or *NULL* on failure.

   .. versionchanged:: 2.5
      This function used an :c:type:`int` type for *len*. This might require
      changes in your code for properly supporting 64-bit systems.


.. c:function:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)

   Return a new tuple object of size *n*, or *NULL* on failure. The tuple values
   are initialized to the subsequent *n* C arguments pointing to Python objects.
   ``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``.

   .. versionadded:: 2.4

   .. versionchanged:: 2.5
      This function used an :c:type:`int` type for *n*. This might require
      changes in your code for properly supporting 64-bit systems.


.. c:function:: Py_ssize_t PyTuple_Size(PyObject *p)

   Take a pointer to a tuple object, and return the size of that tuple.

   .. versionchanged:: 2.5
      This function returned an :c:type:`int` type. This might require changes
      in your code for properly supporting 64-bit systems.


.. c:function:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)

   Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple;
   no error checking is performed.

   .. versionchanged:: 2.5
      This function returned an :c:type:`int` type. This might require changes
      in your code for properly supporting 64-bit systems.


.. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)

   Return the object at position *pos* in the tuple pointed to by *p*.  If *pos* is
   out of bounds, return *NULL* and sets an :exc:`IndexError` exception.

   .. versionchanged:: 2.5
      This function used an :c:type:`int` type for *pos*. This might require
      changes in your code for properly supporting 64-bit systems.


.. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)

   Like :c:func:`PyTuple_GetItem`, but does no checking of its arguments.

   .. versionchanged:: 2.5
      This function used an :c:type:`int` type for *pos*. This might require
      changes in your code for properly supporting 64-bit systems.


.. c:function:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)

   Take a slice of the tuple pointed to by *p* from *low* to *high* and return it
   as a new tuple.

   .. versionchanged:: 2.5
      This function used an :c:type:`int` type for *low* and *high*. This might
      require changes in your code for properly supporting 64-bit systems.


.. c:function:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)

   Insert a reference to object *o* at position *pos* of the tuple pointed to by
   *p*. Return ``0`` on success.

   .. note::

      This function "steals" a reference to *o*.

   .. versionchanged:: 2.5
      This function used an :c:type:`int` type for *pos*. This might require
      changes in your code for properly supporting 64-bit systems.


.. c:function:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)

   Like :c:func:`PyTuple_SetItem`, but does no error checking, and should *only* be
   used to fill in brand new tuples.

   .. note::

      This function "steals" a reference to *o*.

   .. versionchan