cpython/Doc/c-api/tuple.rst

111 lines
3.4 KiB
ReStructuredText
Raw Normal View History

2008-01-20 05:30:57 -04:00
.. highlightlang:: c
.. _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.
.. 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.
.. 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.
.. 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
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;
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
out of bounds, return *NULL* and sets an :exc:`IndexError` exception.
.. 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
Take a slice of the tuple pointed to by *p* from *low* to *high* and return it
as a new tuple.
.. 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.
.. note::
This function "steals" a reference to *o*.
.. 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*.
.. 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
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
.. c:function:: int PyTuple_ClearFreeList()
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
Clear the free list. Return the total number of freed items.