include/python3.13/dictobject.h

0001 #ifndef Py_DICTOBJECT_H
0002 #define Py_DICTOBJECT_H
0003 #ifdef __cplusplus
0004 extern "C" {
0005 #endif
0006
0007 /* Dictionary object type -- mapping from hashable object to object */
0008
0009 /* The distribution includes a separate file, Objects/dictnotes.txt,
0010    describing explorations into dictionary design and optimization.
0011    It covers typical dictionary use patterns, the parameters for
0012    tuning dictionaries, and several ideas for possible optimizations.
0013 */
0014
0015 PyAPI_DATA(PyTypeObject) PyDict_Type;
0016
0017 #define PyDict_Check(op) \
0018                  PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_DICT_SUBCLASS)
0019 #define PyDict_CheckExact(op) Py_IS_TYPE((op), &PyDict_Type)
0020
0021 PyAPI_FUNC(PyObject *) PyDict_New(void);
0022 PyAPI_FUNC(PyObject *) PyDict_GetItem(PyObject *mp, PyObject *key);
0023 PyAPI_FUNC(PyObject *) PyDict_GetItemWithError(PyObject *mp, PyObject *key);
0024 PyAPI_FUNC(int) PyDict_SetItem(PyObject *mp, PyObject *key, PyObject *item);
0025 PyAPI_FUNC(int) PyDict_DelItem(PyObject *mp, PyObject *key);
0026 PyAPI_FUNC(void) PyDict_Clear(PyObject *mp);
0027 PyAPI_FUNC(int) PyDict_Next(
0028     PyObject *mp, Py_ssize_t *pos, PyObject **key, PyObject **value);
0029 PyAPI_FUNC(PyObject *) PyDict_Keys(PyObject *mp);
0030 PyAPI_FUNC(PyObject *) PyDict_Values(PyObject *mp);
0031 PyAPI_FUNC(PyObject *) PyDict_Items(PyObject *mp);
0032 PyAPI_FUNC(Py_ssize_t) PyDict_Size(PyObject *mp);
0033 PyAPI_FUNC(PyObject *) PyDict_Copy(PyObject *mp);
0034 PyAPI_FUNC(int) PyDict_Contains(PyObject *mp, PyObject *key);
0035
0036 /* PyDict_Update(mp, other) is equivalent to PyDict_Merge(mp, other, 1). */
0037 PyAPI_FUNC(int) PyDict_Update(PyObject *mp, PyObject *other);
0038
0039 /* PyDict_Merge updates/merges from a mapping object (an object that
0040    supports PyMapping_Keys() and PyObject_GetItem()).  If override is true,
0041    the last occurrence of a key wins, else the first.  The Python
0042    dict.update(other) is equivalent to PyDict_Merge(dict, other, 1).
0043 */
0044 PyAPI_FUNC(int) PyDict_Merge(PyObject *mp,
0045                              PyObject *other,
0046                              int override);
0047
0048 /* PyDict_MergeFromSeq2 updates/merges from an iterable object producing
0049    iterable objects of length 2.  If override is true, the last occurrence
0050    of a key wins, else the first.  The Python dict constructor dict(seq2)
0051    is equivalent to dict={}; PyDict_MergeFromSeq(dict, seq2, 1).
0052 */
0053 PyAPI_FUNC(int) PyDict_MergeFromSeq2(PyObject *d,
0054                                      PyObject *seq2,
0055                                      int override);
0056
0057 PyAPI_FUNC(PyObject *) PyDict_GetItemString(PyObject *dp, const char *key);
0058 PyAPI_FUNC(int) PyDict_SetItemString(PyObject *dp, const char *key, PyObject *item);
0059 PyAPI_FUNC(int) PyDict_DelItemString(PyObject *dp, const char *key);
0060
0061 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030D0000
0062 // Return the object from dictionary *op* which has a key *key*.
0063 // - If the key is present, set *result to a new strong reference to the value
0064 //   and return 1.
0065 // - If the key is missing, set *result to NULL and return 0 .
0066 // - On error, raise an exception and return -1.
0067 PyAPI_FUNC(int) PyDict_GetItemRef(PyObject *mp, PyObject *key, PyObject **result);
0068 PyAPI_FUNC(int) PyDict_GetItemStringRef(PyObject *mp, const char *key, PyObject **result);
0069 #endif
0070
0071 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030A0000
0072 PyAPI_FUNC(PyObject *) PyObject_GenericGetDict(PyObject *, void *);
0073 #endif
0074
0075 /* Dictionary (keys, values, items) views */
0076
0077 PyAPI_DATA(PyTypeObject) PyDictKeys_Type;
0078 PyAPI_DATA(PyTypeObject) PyDictValues_Type;
0079 PyAPI_DATA(PyTypeObject) PyDictItems_Type;
0080
0081 #define PyDictKeys_Check(op) PyObject_TypeCheck((op), &PyDictKeys_Type)
0082 #define PyDictValues_Check(op) PyObject_TypeCheck((op), &PyDictValues_Type)
0083 #define PyDictItems_Check(op) PyObject_TypeCheck((op), &PyDictItems_Type)
0084 /* This excludes Values, since they are not sets. */
0085 # define PyDictViewSet_Check(op) \
0086     (PyDictKeys_Check(op) || PyDictItems_Check(op))
0087
0088 /* Dictionary (key, value, items) iterators */
0089
0090 PyAPI_DATA(PyTypeObject) PyDictIterKey_Type;
0091 PyAPI_DATA(PyTypeObject) PyDictIterValue_Type;
0092 PyAPI_DATA(PyTypeObject) PyDictIterItem_Type;
0093
0094 PyAPI_DATA(PyTypeObject) PyDictRevIterKey_Type;
0095 PyAPI_DATA(PyTypeObject) PyDictRevIterItem_Type;
0096 PyAPI_DATA(PyTypeObject) PyDictRevIterValue_Type;
0097
0098
0099 #ifndef Py_LIMITED_API
0100 #  define Py_CPYTHON_DICTOBJECT_H
0101 #  include "cpython/dictobject.h"
0102 #  undef Py_CPYTHON_DICTOBJECT_H
0103 #endif
0104
0105 #ifdef __cplusplus
0106 }
0107 #endif
0108 #endif /* !Py_DICTOBJECT_H */