blob: 7a887d1d2eb17f1287de608c3172404780d502c5 [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
Guido van Rossum3f5da241990-12-20 15:06:42 +000024typedef struct {
Fred Drake3cf4d2b2000-07-09 00:55:06 +000025 PyObject_VAR_HEAD
26 PyObject *ob_item[1];
Armin Rigo89a39462004-10-28 16:32:00 +000027
28 /* ob_item contains space for 'ob_size' elements.
29 * Items must normally not be NULL, except during construction when
30 * the tuple is not yet visible outside the function that builds it.
31 */
Guido van Rossumcaa63801995-01-12 11:45:45 +000032} PyTupleObject;
Guido van Rossum3f5da241990-12-20 15:06:42 +000033
Mark Hammond91a681d2002-08-12 07:21:58 +000034PyAPI_DATA(PyTypeObject) PyTuple_Type;
Christian Heimesa22e8bd2007-11-29 22:35:39 +000035PyAPI_DATA(PyTypeObject) PyTupleIter_Type;
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000036
Thomas Wouters27d517b2007-02-25 20:39:11 +000037#define PyTuple_Check(op) \
Christian Heimes90aa7642007-12-19 02:45:37 +000038 PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_TUPLE_SUBCLASS)
39#define PyTuple_CheckExact(op) (Py_TYPE(op) == &PyTuple_Type)
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000040
Martin v. Löwis18e16552006-02-15 17:27:45 +000041PyAPI_FUNC(PyObject *) PyTuple_New(Py_ssize_t size);
42PyAPI_FUNC(Py_ssize_t) PyTuple_Size(PyObject *);
43PyAPI_FUNC(PyObject *) PyTuple_GetItem(PyObject *, Py_ssize_t);
44PyAPI_FUNC(int) PyTuple_SetItem(PyObject *, Py_ssize_t, PyObject *);
45PyAPI_FUNC(PyObject *) PyTuple_GetSlice(PyObject *, Py_ssize_t, Py_ssize_t);
46PyAPI_FUNC(int) _PyTuple_Resize(PyObject **, Py_ssize_t);
47PyAPI_FUNC(PyObject *) PyTuple_Pack(Py_ssize_t, ...);
Guido van Rossum3f5da241990-12-20 15:06:42 +000048
49/* Macro, trading safety for speed */
Guido van Rossum599de5a1995-03-09 12:10:16 +000050#define PyTuple_GET_ITEM(op, i) (((PyTupleObject *)(op))->ob_item[i])
Christian Heimes90aa7642007-12-19 02:45:37 +000051#define PyTuple_GET_SIZE(op) Py_SIZE(op)
Guido van Rossum599de5a1995-03-09 12:10:16 +000052
53/* Macro, *only* to be used to fill in brand new tuples */
54#define PyTuple_SET_ITEM(op, i, v) (((PyTupleObject *)(op))->ob_item[i] = v)
Guido van Rossuma3309961993-07-28 09:05:47 +000055
Christian Heimesa156e092008-02-16 07:38:31 +000056PyAPI_FUNC(int) PyTuple_ClearFreeList(void);
57
Guido van Rossuma3309961993-07-28 09:05:47 +000058#ifdef __cplusplus
59}
60#endif
61#endif /* !Py_TUPLEOBJECT_H */