dictobject.h 6.58 KB
Newer Older
1 2 3 4 5 6
#ifndef Py_DICTOBJECT_H
#define Py_DICTOBJECT_H
#ifdef __cplusplus
extern "C" {
#endif

7

8 9
/* Dictionary object type -- mapping from hashable object to object */

10
/* The distribution includes a separate file, Objects/dictnotes.txt,
11
   describing explorations into dictionary design and optimization.
12 13 14 15
   It covers typical dictionary use patterns, the parameters for
   tuning dictionaries, and several ideas for possible optimizations.
*/

16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
/*
There are three kinds of slots in the table:

1. Unused.  me_key == me_value == NULL
   Does not hold an active (key, value) pair now and never did.  Unused can
   transition to Active upon key insertion.  This is the only case in which
   me_key is NULL, and is each slot's initial state.

2. Active.  me_key != NULL and me_key != dummy and me_value != NULL
   Holds an active (key, value) pair.  Active can transition to Dummy upon
   key deletion.  This is the only case in which me_value != NULL.

3. Dummy.  me_key == dummy and me_value == NULL
   Previously held an active (key, value) pair, but that was deleted and an
   active pair has not yet overwritten the slot.  Dummy can transition to
   Active upon key insertion.  Dummy slots cannot be made Unused again
   (cannot have me_key set to NULL), else the probe sequence in case of
   collision would have no way to know they were once active.

Note: .popitem() abuses the me_hash field of an Unused or Dummy slot to
hold a search finger.  The me_hash field of Unused or Dummy slots has no
meaning otherwise.
*/

/* PyDict_MINSIZE is the minimum size of a dictionary.  This many slots are
 * allocated directly in the dict object (in the ma_smalltable member).
 * It must be a power of 2, and at least 4.  8 allows dicts with no more
 * than 5 active entries to live in ma_smalltable (and so avoid an
 * additional malloc); instrumentation suggested this suffices for the
 * majority of dicts (consisting mostly of usually-small instance dicts and
 * usually-small dicts created to pass keyword arguments).
 */
48
#ifndef Py_LIMITED_API
49 50 51
#define PyDict_MINSIZE 8

typedef struct {
52 53
    /* Cached hash code of me_key. */
    Py_hash_t me_hash;
54 55
    PyObject *me_key;
    PyObject *me_value;
56 57 58 59 60 61 62 63 64 65 66 67 68
} PyDictEntry;

/*
To ensure the lookup algorithm terminates, there must be at least one Unused
slot (NULL key) in the table.
The value ma_fill is the number of non-NULL keys (sum of Active and Dummy);
ma_used is the number of non-NULL, non-dummy keys (== the number of non-NULL
values == the number of Active items).
To avoid slowing down lookups on a near-full table, we resize the table when
it's two-thirds full.
*/
typedef struct _dictobject PyDictObject;
struct _dictobject {
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84
    PyObject_HEAD
    Py_ssize_t ma_fill;  /* # Active + # Dummy */
    Py_ssize_t ma_used;  /* # Active */

    /* The table contains ma_mask + 1 slots, and that's a power of 2.
     * We store the mask instead of the size because the mask is more
     * frequently needed.
     */
    Py_ssize_t ma_mask;

    /* ma_table points to ma_smalltable for small tables, else to
     * additional malloc'ed memory.  ma_table is never NULL!  This rule
     * saves repeated runtime null-tests in the workhorse getitem and
     * setitem calls.
     */
    PyDictEntry *ma_table;
85
    PyDictEntry *(*ma_lookup)(PyDictObject *mp, PyObject *key, Py_hash_t hash);
86
    PyDictEntry ma_smalltable[PyDict_MINSIZE];
87
};
88
#endif /* Py_LIMITED_API */
89

90
PyAPI_DATA(PyTypeObject) PyDict_Type;
91 92 93 94 95 96
PyAPI_DATA(PyTypeObject) PyDictIterKey_Type;
PyAPI_DATA(PyTypeObject) PyDictIterValue_Type;
PyAPI_DATA(PyTypeObject) PyDictIterItem_Type;
PyAPI_DATA(PyTypeObject) PyDictKeys_Type;
PyAPI_DATA(PyTypeObject) PyDictItems_Type;
PyAPI_DATA(PyTypeObject) PyDictValues_Type;
97

98
#define PyDict_Check(op) \
99 100 101 102 103
                 PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_DICT_SUBCLASS)
#define PyDict_CheckExact(op) (Py_TYPE(op) == &PyDict_Type)
#define PyDictKeys_Check(op) (Py_TYPE(op) == &PyDictKeys_Type)
#define PyDictItems_Check(op) (Py_TYPE(op) == &PyDictItems_Type)
#define PyDictValues_Check(op) (Py_TYPE(op) == &PyDictValues_Type)
104 105
/* This excludes Values, since they are not sets. */
# define PyDictViewSet_Check(op) \
106
    (PyDictKeys_Check(op) || PyDictItems_Check(op))
107

108

109 110
PyAPI_FUNC(PyObject *) PyDict_New(void);
PyAPI_FUNC(PyObject *) PyDict_GetItem(PyObject *mp, PyObject *key);
111
PyAPI_FUNC(PyObject *) PyDict_GetItemWithError(PyObject *mp, PyObject *key);
112 113 114 115
PyAPI_FUNC(int) PyDict_SetItem(PyObject *mp, PyObject *key, PyObject *item);
PyAPI_FUNC(int) PyDict_DelItem(PyObject *mp, PyObject *key);
PyAPI_FUNC(void) PyDict_Clear(PyObject *mp);
PyAPI_FUNC(int) PyDict_Next(
116
    PyObject *mp, Py_ssize_t *pos, PyObject **key, PyObject **value);
117
#ifndef Py_LIMITED_API
118
PyAPI_FUNC(int) _PyDict_Next(
119
    PyObject *mp, Py_ssize_t *pos, PyObject **key, PyObject **value, Py_hash_t *hash);
120
#endif
121 122 123
PyAPI_FUNC(PyObject *) PyDict_Keys(PyObject *mp);
PyAPI_FUNC(PyObject *) PyDict_Values(PyObject *mp);
PyAPI_FUNC(PyObject *) PyDict_Items(PyObject *mp);
Martin v. Löwis's avatar
Martin v. Löwis committed
124
PyAPI_FUNC(Py_ssize_t) PyDict_Size(PyObject *mp);
125
PyAPI_FUNC(PyObject *) PyDict_Copy(PyObject *mp);
126
PyAPI_FUNC(int) PyDict_Contains(PyObject *mp, PyObject *key);
127
#ifndef Py_LIMITED_API
128
PyAPI_FUNC(int) _PyDict_Contains(PyObject *mp, PyObject *key, Py_hash_t hash);
129
PyAPI_FUNC(PyObject *) _PyDict_NewPresized(Py_ssize_t minused);
130
PyAPI_FUNC(void) _PyDict_MaybeUntrack(PyObject *mp);
131
PyAPI_FUNC(int) _PyDict_HasOnlyStringKeys(PyObject *mp);
132
#endif
133 134

/* PyDict_Update(mp, other) is equivalent to PyDict_Merge(mp, other, 1). */
135
PyAPI_FUNC(int) PyDict_Update(PyObject *mp, PyObject *other);
136

137 138 139 140 141
/* PyDict_Merge updates/merges from a mapping object (an object that
   supports PyMapping_Keys() and PyObject_GetItem()).  If override is true,
   the last occurrence of a key wins, else the first.  The Python
   dict.update(other) is equivalent to PyDict_Merge(dict, other, 1).
*/
142
PyAPI_FUNC(int) PyDict_Merge(PyObject *mp,
143 144
                                   PyObject *other,
                                   int override);
145 146 147 148 149 150

/* PyDict_MergeFromSeq2 updates/merges from an iterable object producing
   iterable objects of length 2.  If override is true, the last occurrence
   of a key wins, else the first.  The Python dict constructor dict(seq2)
   is equivalent to dict={}; PyDict_MergeFromSeq(dict, seq2, 1).
*/
151
PyAPI_FUNC(int) PyDict_MergeFromSeq2(PyObject *d,
152 153
                                           PyObject *seq2,
                                           int override);
154

155 156 157
PyAPI_FUNC(PyObject *) PyDict_GetItemString(PyObject *dp, const char *key);
PyAPI_FUNC(int) PyDict_SetItemString(PyObject *dp, const char *key, PyObject *item);
PyAPI_FUNC(int) PyDict_DelItemString(PyObject *dp, const char *key);
Guido van Rossum's avatar
Guido van Rossum committed
158

159 160 161 162
#ifdef __cplusplus
}
#endif
#endif /* !Py_DICTOBJECT_H */