blob: f17b7882bed9e021d39f49d3d0d10994ab0ea74f [file] [log] [blame]
Guido van Rossumf70e43a1991-02-19 12:39:46 +00001
Guido van Rossum85a5fbb1990-10-14 12:07:46 +00002/* Tuple object interface */
3
Fred Drake3cf4d2b2000-07-09 00:55:06 +00004#ifndef Py_TUPLEOBJECT_H
5#define Py_TUPLEOBJECT_H
6#ifdef __cplusplus
7extern "C" {
8#endif
9
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000010/*
Armin Rigo89a39462004-10-28 16:32:00 +000011Another generally useful object type is a tuple of object pointers.
12For Python, this is an immutable type. C code can change the tuple items
13(but not their number), and even use tuples are general-purpose arrays of
14object references, but in general only brand new tuples should be mutated,
15not ones that might already have been exposed to Python code.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000016
Guido van Rossumcaa63801995-01-12 11:45:45 +000017*** WARNING *** PyTuple_SetItem does not increment the new item's reference
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000018count, but does decrement the reference count of the item it replaces,
19if not nil. It does *decrement* the reference count if it is *not*
Guido van Rossumcaa63801995-01-12 11:45:45 +000020inserted in the tuple. Similarly, PyTuple_GetItem does not increment the
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000021returned item's reference count.
22*/
23
Martin v. Löwis4d0d4712010-12-03 20:14:31 +000024#ifndef Py_LIMITED_API
Guido van Rossum3f5da241990-12-20 15:06:42 +000025typedef struct {
Fred Drake3cf4d2b2000-07-09 00:55:06 +000026 PyObject_VAR_HEAD
27 PyObject *ob_item[1];
Armin Rigo89a39462004-10-28 16:32:00 +000028
29 /* ob_item contains space for 'ob_size' elements.
30 * Items must normally not be NULL, except during construction when
31 * the tuple is not yet visible outside the function that builds it.
32 */
Guido van Rossumcaa63801995-01-12 11:45:45 +000033} PyTupleObject;
Martin v. Löwis4d0d4712010-12-03 20:14:31 +000034#endif
Guido van Rossum3f5da241990-12-20 15:06:42 +000035
Mark Hammond91a681d2002-08-12 07:21:58 +000036PyAPI_DATA(PyTypeObject) PyTuple_Type;
Christian Heimesa22e8bd2007-11-29 22:35:39 +000037PyAPI_DATA(PyTypeObject) PyTupleIter_Type;
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000038
Thomas Wouters27d517b2007-02-25 20:39:11 +000039#define PyTuple_Check(op) \
Christian Heimes90aa7642007-12-19 02:45:37 +000040 PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_TUPLE_SUBCLASS)
41#define PyTuple_CheckExact(op) (Py_TYPE(op) == &PyTuple_Type)
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000042
Martin v. Löwis18e16552006-02-15 17:27:45 +000043PyAPI_FUNC(PyObject *) PyTuple_New(Py_ssize_t size);
44PyAPI_FUNC(Py_ssize_t) PyTuple_Size(PyObject *);
45PyAPI_FUNC(PyObject *) PyTuple_GetItem(PyObject *, Py_ssize_t);
46PyAPI_FUNC(int) PyTuple_SetItem(PyObject *, Py_ssize_t, PyObject *);
47PyAPI_FUNC(PyObject *) PyTuple_GetSlice(PyObject *, Py_ssize_t, Py_ssize_t);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +000048#ifndef Py_LIMITED_API
Martin v. Löwis18e16552006-02-15 17:27:45 +000049PyAPI_FUNC(int) _PyTuple_Resize(PyObject **, Py_ssize_t);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +000050#endif
Martin v. Löwis18e16552006-02-15 17:27:45 +000051PyAPI_FUNC(PyObject *) PyTuple_Pack(Py_ssize_t, ...);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +000052#ifndef Py_LIMITED_API
Antoine Pitrou3a652b12009-03-23 18:52:06 +000053PyAPI_FUNC(void) _PyTuple_MaybeUntrack(PyObject *);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +000054#endif
Guido van Rossum3f5da241990-12-20 15:06:42 +000055
56/* Macro, trading safety for speed */
Martin v. Löwis4d0d4712010-12-03 20:14:31 +000057#ifndef Py_LIMITED_API
Guido van Rossum599de5a1995-03-09 12:10:16 +000058#define PyTuple_GET_ITEM(op, i) (((PyTupleObject *)(op))->ob_item[i])
Christian Heimes90aa7642007-12-19 02:45:37 +000059#define PyTuple_GET_SIZE(op) Py_SIZE(op)
Guido van Rossum599de5a1995-03-09 12:10:16 +000060
61/* Macro, *only* to be used to fill in brand new tuples */
62#define PyTuple_SET_ITEM(op, i, v) (((PyTupleObject *)(op))->ob_item[i] = v)
Martin v. Löwis4d0d4712010-12-03 20:14:31 +000063#endif
Guido van Rossuma3309961993-07-28 09:05:47 +000064
Christian Heimesa156e092008-02-16 07:38:31 +000065PyAPI_FUNC(int) PyTuple_ClearFreeList(void);
66
Guido van Rossuma3309961993-07-28 09:05:47 +000067#ifdef __cplusplus
68}
69#endif
70#endif /* !Py_TUPLEOBJECT_H */