1#ifndef Py_CPYTHON_DICTOBJECT_H
2# error "this header file must not be included directly"
3#endif
4
5typedef struct _dictkeysobject PyDictKeysObject;
6typedef struct _dictvalues PyDictValues;
7
8/* The ma_values pointer is NULL for a combined table
9 * or points to an array of PyObject* for a split table
10 */
11typedef struct {
12 PyObject_HEAD
13
14 /* Number of items in the dictionary */
15 Py_ssize_t ma_used;
16
17 /* Dictionary version: globally unique, value change each time
18 the dictionary is modified */
19#ifdef Py_BUILD_CORE
20 uint64_t ma_version_tag;
21#else
22 Py_DEPRECATED(3.12) uint64_t ma_version_tag;
23#endif
24
25 PyDictKeysObject *ma_keys;
26
27 /* If ma_values is NULL, the table is "combined": keys and values
28 are stored in ma_keys.
29
30 If ma_values is not NULL, the table is split:
31 keys are stored in ma_keys and values are stored in ma_values */
32 PyDictValues *ma_values;
33} PyDictObject;
34
35PyAPI_FUNC(PyObject *) _PyDict_GetItem_KnownHash(PyObject *mp, PyObject *key,
36 Py_hash_t hash);
37PyAPI_FUNC(PyObject *) _PyDict_GetItemWithError(PyObject *dp, PyObject *key);
38PyAPI_FUNC(PyObject *) _PyDict_GetItemIdWithError(PyObject *dp,
39 _Py_Identifier *key);
40PyAPI_FUNC(PyObject *) _PyDict_GetItemStringWithError(PyObject *, const char *);
41PyAPI_FUNC(PyObject *) PyDict_SetDefault(
42 PyObject *mp, PyObject *key, PyObject *defaultobj);
43PyAPI_FUNC(int) _PyDict_SetItem_KnownHash(PyObject *mp, PyObject *key,
44 PyObject *item, Py_hash_t hash);
45PyAPI_FUNC(int) _PyDict_DelItem_KnownHash(PyObject *mp, PyObject *key,
46 Py_hash_t hash);
47PyAPI_FUNC(int) _PyDict_DelItemIf(PyObject *mp, PyObject *key,
48 int (*predicate)(PyObject *value));
49PyAPI_FUNC(int) _PyDict_Next(
50 PyObject *mp, Py_ssize_t *pos, PyObject **key, PyObject **value, Py_hash_t *hash);
51
52/* Get the number of items of a dictionary. */
53static inline Py_ssize_t PyDict_GET_SIZE(PyObject *op) {
54 PyDictObject *mp;
55 assert(PyDict_Check(op));
56 mp = _Py_CAST(PyDictObject*, op);
57 return mp->ma_used;
58}
59#define PyDict_GET_SIZE(op) PyDict_GET_SIZE(_PyObject_CAST(op))
60
61PyAPI_FUNC(int) _PyDict_Contains_KnownHash(PyObject *, PyObject *, Py_hash_t);
62PyAPI_FUNC(int) _PyDict_ContainsId(PyObject *, _Py_Identifier *);
63PyAPI_FUNC(PyObject *) _PyDict_NewPresized(Py_ssize_t minused);
64PyAPI_FUNC(void) _PyDict_MaybeUntrack(PyObject *mp);
65PyAPI_FUNC(int) _PyDict_HasOnlyStringKeys(PyObject *mp);
66PyAPI_FUNC(Py_ssize_t) _PyDict_SizeOf(PyDictObject *);
67PyAPI_FUNC(PyObject *) _PyDict_Pop(PyObject *, PyObject *, PyObject *);
68#define _PyDict_HasSplitTable(d) ((d)->ma_values != NULL)
69
70/* Like PyDict_Merge, but override can be 0, 1 or 2. If override is 0,
71 the first occurrence of a key wins, if override is 1, the last occurrence
72 of a key wins, if override is 2, a KeyError with conflicting key as
73 argument is raised.
74*/
75PyAPI_FUNC(int) _PyDict_MergeEx(PyObject *mp, PyObject *other, int override);
76PyAPI_FUNC(int) _PyDict_SetItemId(PyObject *dp, _Py_Identifier *key, PyObject *item);
77
78PyAPI_FUNC(int) _PyDict_DelItemId(PyObject *mp, _Py_Identifier *key);
79PyAPI_FUNC(void) _PyDict_DebugMallocStats(FILE *out);
80
81/* _PyDictView */
82
83typedef struct {
84 PyObject_HEAD
85 PyDictObject *dv_dict;
86} _PyDictViewObject;
87
88PyAPI_FUNC(PyObject *) _PyDictView_New(PyObject *, PyTypeObject *);
89PyAPI_FUNC(PyObject *) _PyDictView_Intersect(PyObject* self, PyObject *other);
90
91/* Dictionary watchers */
92
93#define PY_FOREACH_DICT_EVENT(V) \
94 V(ADDED) \
95 V(MODIFIED) \
96 V(DELETED) \
97 V(CLONED) \
98 V(CLEARED) \
99 V(DEALLOCATED)
100
101typedef enum {
102 #define PY_DEF_EVENT(EVENT) PyDict_EVENT_##EVENT,
103 PY_FOREACH_DICT_EVENT(PY_DEF_EVENT)
104 #undef PY_DEF_EVENT
105} PyDict_WatchEvent;
106
107// Callback to be invoked when a watched dict is cleared, dealloced, or modified.
108// In clear/dealloc case, key and new_value will be NULL. Otherwise, new_value will be the
109// new value for key, NULL if key is being deleted.
110typedef int(*PyDict_WatchCallback)(PyDict_WatchEvent event, PyObject* dict, PyObject* key, PyObject* new_value);
111
112// Register/unregister a dict-watcher callback
113PyAPI_FUNC(int) PyDict_AddWatcher(PyDict_WatchCallback callback);
114PyAPI_FUNC(int) PyDict_ClearWatcher(int watcher_id);
115
116// Mark given dictionary as "watched" (callback will be called if it is modified)
117PyAPI_FUNC(int) PyDict_Watch(int watcher_id, PyObject* dict);
118PyAPI_FUNC(int) PyDict_Unwatch(int watcher_id, PyObject* dict);
119

source code of include/python3.12/cpython/dictobject.h