cpython/Doc/c-api/tuple.rst

224 lines
8.5 KiB
ReStructuredText
Raw Normal View History

.. highlight:: c
2008-01-20 05:30:57 -04:00
.. _tupleobjects:
Tuple Objects
-------------
.. index:: object: tuple
.. c:type:: PyTupleObject
2008-01-20 05:30:57 -04:00
This subtype of :c:type:`PyObject` represents a Python tuple object.
2008-01-20 05:30:57 -04:00
.. c:var:: PyTypeObject PyTuple_Type
2008-01-20 05:30:57 -04:00
This instance of :c:type:`PyTypeObject` represents the Python tuple type; it
is the same object as :class:`tuple` in the Python layer.
2008-01-20 05:30:57 -04:00
.. c:function:: int PyTuple_Check(PyObject *p)
2008-01-20 05:30:57 -04:00
Return true if *p* is a tuple object or an instance of a subtype of the
tuple type. This function always succeeds.
2008-01-20 05:30:57 -04:00
.. c:function:: int PyTuple_CheckExact(PyObject *p)
2008-01-20 05:30:57 -04:00
Return true if *p* is a tuple object, but not an instance of a subtype of the
tuple type. This function always succeeds.
2008-01-20 05:30:57 -04:00
.. c:function:: PyObject* PyTuple_New(Py_ssize_t len)
2008-01-20 05:30:57 -04:00
Return a new tuple object of size *len*, or ``NULL`` on failure.
2008-01-20 05:30:57 -04:00
.. c:function:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
2008-01-20 05:30:57 -04:00
Return a new tuple object of size *n*, or ``NULL`` on failure. The tuple values
2008-01-20 05:30:57 -04:00
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)``.
.. c:function:: Py_ssize_t PyTuple_Size(PyObject *p)
2008-01-20 05:30:57 -04:00
Take a pointer to a tuple object, and return the size of that tuple.
.. c:function:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
2008-01-20 05:30:57 -04:00
Return the size of the tuple *p*, which must be non-``NULL`` and point to a tuple;
2008-01-20 05:30:57 -04:00
no error checking is performed.
.. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
2008-01-20 05:30:57 -04:00
Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is
negative or out of bounds, return ``NULL`` and set an :exc:`IndexError` exception.
2008-01-20 05:30:57 -04:00
.. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
2008-01-20 05:30:57 -04:00
Like :c:func:`PyTuple_GetItem`, but does no checking of its arguments.
2008-01-20 05:30:57 -04:00
.. c:function:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
2008-01-20 05:30:57 -04:00
Return the slice of the tuple pointed to by *p* between *low* and *high*,
or ``NULL`` on failure. This is the equivalent of the Python expression
``p[low:high]``. Indexing from the end of the list is not supported.
2008-01-20 05:30:57 -04:00
.. c:function:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
2008-01-20 05:30:57 -04:00
Insert a reference to object *o* at position *pos* of the tuple pointed to by
*p*. Return ``0`` on success. If *pos* is out of bounds, return ``-1``
and set an :exc:`IndexError` exception.
2008-01-20 05:30:57 -04:00
.. note::
This function "steals" a reference to *o* and discards a reference to
an item already in the tuple at the affected position.
2008-01-20 05:30:57 -04:00
.. c:function:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)
2008-01-20 05:30:57 -04:00
Like :c:func:`PyTuple_SetItem`, but does no error checking, and should *only* be
2008-01-20 05:30:57 -04:00
used to fill in brand new tuples.
.. note::
This function "steals" a reference to *o*, and, unlike
:c:func:`PyTuple_SetItem`, does *not* discard a reference to any item that
is being replaced; any reference in the tuple at position *pos* will be
leaked.
2008-01-20 05:30:57 -04:00
.. c:function:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
2008-01-20 05:30:57 -04:00
Can be used to resize a tuple. *newsize* will be the new length of the tuple.
Because tuples are *supposed* to be immutable, this should only be used if there
is only one reference to the object. Do *not* 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 ``0`` on success. Client code should never
assume that the resulting value of ``*p`` will be the same as before calling
this function. If the object referenced by ``*p`` is replaced, the original
``*p`` is destroyed. On failure, returns ``-1`` and sets ``*p`` to ``NULL``, and
2008-01-20 05:30:57 -04:00
raises :exc:`MemoryError` or :exc:`SystemError`.
Merged revisions 60481,60485,60489-60492,60494-60496,60498-60499,60501-60503,60505-60506,60508-60509,60523-60524,60532,60543,60545,60547-60548,60552,60554,60556-60559,60561-60562,60569,60571-60572,60574,60576-60583,60585-60586,60589,60591,60594-60595,60597-60598,60600-60601,60606-60612,60615,60617,60619-60621,60623-60625,60627-60629,60631,60633,60635,60647,60650,60652,60654,60656,60658-60659,60664-60666,60668-60670,60672,60676,60678,60680-60683,60685-60686,60688,60690,60692-60694,60697-60700,60705-60706,60708,60711,60714,60720,60724-60730,60732,60736,60742,60744,60746,60748,60750-60751,60753,60756-60757,60759-60761,60763-60764,60766,60769-60770,60774-60784,60787-60845 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r60790 | raymond.hettinger | 2008-02-14 10:32:45 +0100 (Thu, 14 Feb 2008) | 4 lines Add diagnostic message to help figure-out why SocketServer tests occasionally crash when trying to remove a pid that in not in the activechildren list. ........ r60791 | raymond.hettinger | 2008-02-14 11:46:57 +0100 (Thu, 14 Feb 2008) | 1 line Add fixed-point examples to the decimal FAQ ........ r60792 | raymond.hettinger | 2008-02-14 12:01:10 +0100 (Thu, 14 Feb 2008) | 1 line Improve rst markup ........ r60794 | raymond.hettinger | 2008-02-14 12:57:25 +0100 (Thu, 14 Feb 2008) | 1 line Show how to remove exponents. ........ r60795 | raymond.hettinger | 2008-02-14 13:05:42 +0100 (Thu, 14 Feb 2008) | 1 line Fix markup. ........ r60797 | christian.heimes | 2008-02-14 13:47:33 +0100 (Thu, 14 Feb 2008) | 1 line Implemented Martin's suggestion to clear the free lists during the garbage collection of the highest generation. ........ r60798 | raymond.hettinger | 2008-02-14 13:49:37 +0100 (Thu, 14 Feb 2008) | 1 line Simplify moneyfmt() recipe. ........ r60810 | raymond.hettinger | 2008-02-14 20:02:39 +0100 (Thu, 14 Feb 2008) | 1 line Fix markup ........ r60811 | raymond.hettinger | 2008-02-14 20:30:30 +0100 (Thu, 14 Feb 2008) | 1 line No need to register subclass of ABCs. ........ r60814 | thomas.heller | 2008-02-14 22:00:28 +0100 (Thu, 14 Feb 2008) | 1 line Try to correct a markup error that does hide the following paragraph. ........ r60822 | christian.heimes | 2008-02-14 23:40:11 +0100 (Thu, 14 Feb 2008) | 1 line Use a static and interned string for __subclasscheck__ and __instancecheck__ as suggested by Thomas Heller in #2115 ........ r60827 | christian.heimes | 2008-02-15 07:57:08 +0100 (Fri, 15 Feb 2008) | 1 line Fixed repr() and str() of complex numbers. Complex suffered from the same problem as floats but I forgot to test and fix them. ........ r60830 | christian.heimes | 2008-02-15 09:20:11 +0100 (Fri, 15 Feb 2008) | 2 lines Bug #2111: mmap segfaults when trying to write a block opened with PROT_READ Thanks to Thomas Herve for the fix. ........ r60835 | eric.smith | 2008-02-15 13:14:32 +0100 (Fri, 15 Feb 2008) | 1 line In PyNumber_ToBase, changed from an assert to returning an error when PyObject_Index() returns something other than an int or long. It should never be possible to trigger this, as PyObject_Index checks to make sure it returns an int or long. ........ r60837 | skip.montanaro | 2008-02-15 20:03:59 +0100 (Fri, 15 Feb 2008) | 8 lines Two new functions: * place_summary_first copies the regrtest summary to the front of the file making it easier to scan quickly for problems. * count_failures gets the actual count of the number of failing tests, not just a 1 (some failures) or 0 (no failures). ........ r60840 | raymond.hettinger | 2008-02-15 22:21:25 +0100 (Fri, 15 Feb 2008) | 1 line Update example to match the current syntax. ........ r60841 | amaury.forgeotdarc | 2008-02-15 22:22:45 +0100 (Fri, 15 Feb 2008) | 8 lines Issue #2115: __slot__ attributes setting was 10x slower. Also correct a possible crash using ABCs. This change is exactly the same as an optimisation done 5 years ago, but on slot *access*: http://svn.python.org/view?view=rev&rev=28297 ........ r60842 | amaury.forgeotdarc | 2008-02-15 22:27:44 +0100 (Fri, 15 Feb 2008) | 2 lines Temporarily let these tests pass ........ r60843 | kurt.kaiser | 2008-02-15 22:56:36 +0100 (Fri, 15 Feb 2008) | 2 lines ScriptBinding event handlers weren't returning 'break'. Patch 2050, Tal Einat. ........ r60844 | kurt.kaiser | 2008-02-15 23:25:09 +0100 (Fri, 15 Feb 2008) | 4 lines Configured selection highlighting colors were ignored; updating highlighting in the config dialog would cause non-Python files to be colored as if they were Python source; improve use of ColorDelagator. Patch 1334. Tal Einat. ........ r60845 | amaury.forgeotdarc | 2008-02-15 23:44:20 +0100 (Fri, 15 Feb 2008) | 9 lines Re-enable tests, they were failing since gc.collect() clears the various freelists. They still remain fragile. For example, a call to assertEqual currently does not make any allocation (which surprised me at first). But this can change when gc.collect also deletes the numerous "zombie frames" attached to each function. ........
2008-02-16 03:38:31 -04:00
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines The type for ppos has been Py_ssize_t since 2.5, reflect this in the documentation. ........ r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines Reformat paragraph. ........ r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines Issue #4129: Belatedly document which C API functions had their argument(s) or return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this might cause problems on 64-bit platforms. ........ r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines Issue #4129: Document more int -> Py_ssize_t changes. ........ r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines Reference to an int type, whereas it's a Py_ssize_t as the synopsis states. ........ r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines Since I edited this file, reformat for future edits. ........ r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........
2009-04-26 18:06:15 -03:00
Struct Sequence Objects
-----------------------
Struct sequence objects are the C equivalent of :func:`~collections.namedtuple`
objects, i.e. a sequence whose items can also be accessed through attributes.
To create a struct sequence, you first have to create a specific struct sequence
type.
.. c:function:: PyTypeObject* PyStructSequence_NewType(PyStructSequence_Desc *desc)
Create a new struct sequence type from the data in *desc*, described below. Instances
of the resulting type can be created with :c:func:`PyStructSequence_New`.
.. c:function:: void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)
Initializes a struct sequence type *type* from *desc* in place.
.. c:function:: int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)
The same as ``PyStructSequence_InitType``, but returns ``0`` on success and ``-1`` on
failure.
.. versionadded:: 3.4
.. c:type:: PyStructSequence_Desc
Contains the meta information of a struct sequence type to create.
+-------------------+------------------------------+--------------------------------------+
| Field | C Type | Meaning |
+===================+==============================+======================================+
| ``name`` | ``const char *`` | name of the struct sequence type |
+-------------------+------------------------------+--------------------------------------+
| ``doc`` | ``const char *`` | pointer to docstring for the type |
| | | or ``NULL`` to omit |
+-------------------+------------------------------+--------------------------------------+
| ``fields`` | ``PyStructSequence_Field *`` | pointer to ``NULL``-terminated array |
| | | with field names of the new type |
+-------------------+------------------------------+--------------------------------------+
| ``n_in_sequence`` | ``int`` | number of fields visible to the |
| | | Python side (if used as tuple) |
+-------------------+------------------------------+--------------------------------------+
.. c:type:: PyStructSequence_Field
Describes a field of a struct sequence. As a struct sequence is modeled as a
tuple, all fields are typed as :c:type:`PyObject*`. The index in the
:attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which
field of the struct sequence is described.
+-----------+------------------+-----------------------------------------+
| Field | C Type | Meaning |
+===========+==================+=========================================+
| ``name`` | ``const char *`` | name for the field or ``NULL`` to end |
| | | the list of named fields, set to |
| | | :c:data:`PyStructSequence_UnnamedField` |
| | | to leave unnamed |
+-----------+------------------+-----------------------------------------+
| ``doc`` | ``const char *`` | field docstring or ``NULL`` to omit |
+-----------+------------------+-----------------------------------------+
.. c:var:: const char * const PyStructSequence_UnnamedField
Special value for a field name to leave it unnamed.
.. versionchanged:: 3.9
The type was changed from ``char *``.
.. c:function:: PyObject* PyStructSequence_New(PyTypeObject *type)
Creates an instance of *type*, which must have been created with
:c:func:`PyStructSequence_NewType`.
.. c:function:: PyObject* PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)
Return the object at position *pos* in the struct sequence pointed to by *p*.
No bounds checking is performed.
.. c:function:: PyObject* PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)
Macro equivalent of :c:func:`PyStructSequence_GetItem`.
.. c:function:: void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
Sets the field at index *pos* of the struct sequence *p* to value *o*. Like
:c:func:`PyTuple_SET_ITEM`, this should only be used to fill in brand new
instances.
.. note::
This function "steals" a reference to *o*.
.. c:function:: void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)
Similar to :c:func:`PyStructSequence_SetItem`, but implemented as a static
inlined function.
.. note::
This function "steals" a reference to *o*.