python3.12/cpython/dictobject.h

0001 #ifndef Py_CPYTHON_DICTOBJECT_H
0002 #  error "this header file must not be included directly"
0003 #endif
0004
0005 typedef struct _dictkeysobject PyDictKeysObject;
0006 typedef struct _dictvalues PyDictValues;
0007
0008 /* The ma_values pointer is NULL for a combined table
0009  * or points to an array of PyObject* for a split table
0010  */
0011 typedef struct {
0012     PyObject_HEAD
0013
0014     /* Number of items in the dictionary */
0015     Py_ssize_t ma_used;
0016
0017     /* Dictionary version: globally unique, value change each time
0018        the dictionary is modified */
0019 #ifdef Py_BUILD_CORE
0020     uint64_t ma_version_tag;
0021 #else
0022     Py_DEPRECATED(3.12) uint64_t ma_version_tag;
0023 #endif
0024
0025     PyDictKeysObject *ma_keys;
0026
0027     /* If ma_values is NULL, the table is "combined": keys and values
0028        are stored in ma_keys.
0029
0030        If ma_values is not NULL, the table is split:
0031        keys are stored in ma_keys and values are stored in ma_values */
0032     PyDictValues *ma_values;
0033 } PyDictObject;
0034
0035 PyAPI_FUNC(PyObject *) _PyDict_GetItem_KnownHash(PyObject *mp, PyObject *key,
0036                                        Py_hash_t hash);
0037 PyAPI_FUNC(PyObject *) _PyDict_GetItemWithError(PyObject *dp, PyObject *key);
0038 PyAPI_FUNC(PyObject *) _PyDict_GetItemIdWithError(PyObject *dp,
0039                                                   _Py_Identifier *key);
0040 PyAPI_FUNC(PyObject *) _PyDict_GetItemStringWithError(PyObject *, const char *);
0041 PyAPI_FUNC(PyObject *) PyDict_SetDefault(
0042     PyObject *mp, PyObject *key, PyObject *defaultobj);
0043 PyAPI_FUNC(int) _PyDict_SetItem_KnownHash(PyObject *mp, PyObject *key,
0044                                           PyObject *item, Py_hash_t hash);
0045 PyAPI_FUNC(int) _PyDict_DelItem_KnownHash(PyObject *mp, PyObject *key,
0046                                           Py_hash_t hash);
0047 PyAPI_FUNC(int) _PyDict_DelItemIf(PyObject *mp, PyObject *key,
0048                                   int (*predicate)(PyObject *value));
0049 PyAPI_FUNC(int) _PyDict_Next(
0050     PyObject *mp, Py_ssize_t *pos, PyObject **key, PyObject **value, Py_hash_t *hash);
0051
0052 /* Get the number of items of a dictionary. */
0053 static inline Py_ssize_t PyDict_GET_SIZE(PyObject *op) {
0054     PyDictObject *mp;
0055     assert(PyDict_Check(op));
0056     mp = _Py_CAST(PyDictObject*, op);
0057     return mp->ma_used;
0058 }
0059 #define PyDict_GET_SIZE(op) PyDict_GET_SIZE(_PyObject_CAST(op))
0060
0061 PyAPI_FUNC(int) _PyDict_Contains_KnownHash(PyObject *, PyObject *, Py_hash_t);
0062 PyAPI_FUNC(int) _PyDict_ContainsId(PyObject *, _Py_Identifier *);
0063 PyAPI_FUNC(PyObject *) _PyDict_NewPresized(Py_ssize_t minused);
0064 PyAPI_FUNC(void) _PyDict_MaybeUntrack(PyObject *mp);
0065 PyAPI_FUNC(int) _PyDict_HasOnlyStringKeys(PyObject *mp);
0066 PyAPI_FUNC(Py_ssize_t) _PyDict_SizeOf(PyDictObject *);
0067 PyAPI_FUNC(PyObject *) _PyDict_Pop(PyObject *, PyObject *, PyObject *);
0068 #define _PyDict_HasSplitTable(d) ((d)->ma_values != NULL)
0069
0070 /* Like PyDict_Merge, but override can be 0, 1 or 2.  If override is 0,
0071    the first occurrence of a key wins, if override is 1, the last occurrence
0072    of a key wins, if override is 2, a KeyError with conflicting key as
0073    argument is raised.
0074 */
0075 PyAPI_FUNC(int) _PyDict_MergeEx(PyObject *mp, PyObject *other, int override);
0076 PyAPI_FUNC(int) _PyDict_SetItemId(PyObject *dp, _Py_Identifier *key, PyObject *item);
0077
0078 PyAPI_FUNC(int) _PyDict_DelItemId(PyObject *mp, _Py_Identifier *key);
0079 PyAPI_FUNC(void) _PyDict_DebugMallocStats(FILE *out);
0080
0081 /* _PyDictView */
0082
0083 typedef struct {
0084     PyObject_HEAD
0085     PyDictObject *dv_dict;
0086 } _PyDictViewObject;
0087
0088 PyAPI_FUNC(PyObject *) _PyDictView_New(PyObject *, PyTypeObject *);
0089 PyAPI_FUNC(PyObject *) _PyDictView_Intersect(PyObject* self, PyObject *other);
0090
0091 /* Dictionary watchers */
0092
0093 #define PY_FOREACH_DICT_EVENT(V) \
0094     V(ADDED)                     \
0095     V(MODIFIED)                  \
0096     V(DELETED)                   \
0097     V(CLONED)                    \
0098     V(CLEARED)                   \
0099     V(DEALLOCATED)
0100
0101 typedef enum {
0102     #define PY_DEF_EVENT(EVENT) PyDict_EVENT_##EVENT,
0103     PY_FOREACH_DICT_EVENT(PY_DEF_EVENT)
0104     #undef PY_DEF_EVENT
0105 } PyDict_WatchEvent;
0106
0107 // Callback to be invoked when a watched dict is cleared, dealloced, or modified.
0108 // In clear/dealloc case, key and new_value will be NULL. Otherwise, new_value will be the
0109 // new value for key, NULL if key is being deleted.
0110 typedef int(*PyDict_WatchCallback)(PyDict_WatchEvent event, PyObject* dict, PyObject* key, PyObject* new_value);
0111
0112 // Register/unregister a dict-watcher callback
0113 PyAPI_FUNC(int) PyDict_AddWatcher(PyDict_WatchCallback callback);
0114 PyAPI_FUNC(int) PyDict_ClearWatcher(int watcher_id);
0115
0116 // Mark given dictionary as "watched" (callback will be called if it is modified)
0117 PyAPI_FUNC(int) PyDict_Watch(int watcher_id, PyObject* dict);
0118 PyAPI_FUNC(int) PyDict_Unwatch(int watcher_id, PyObject* dict);