Dictionary Objects

PyDictObject

PyObject的此子类型表示一个Python字典对象。

PyTypeObject PyDict_Type

此实例PyTypeObject表示Python字典类型。这是与Python层中的dict相同的对象。

int PyDict_Check(PyObject *p)

如果p是dict对象或dict类型的子类型的实例，则返回true。

int PyDict_CheckExact(PyObject *p)

如果p是dict对象，而不是dict类型的子类型的实例，则返回true。

PyObject* PyDict_New()

返回值：新引用。

失败时返回一个新的空字典，或NULL。

PyObject* PyDictProxy_New(PyObject *mapping)

返回值：新引用。

为强制执行只读行为的映射返回types.MappingProxyType对象。这通常用于创建一个视图，以防止非动态类类型的字典修改。

void PyDict_Clear(PyObject *p)

清空所有键值对的现有字典。

int PyDict_Contains(PyObject *p, PyObject *key)

确定字典p是否包含键。如果p中的项目符合键，则返回1，否则返回0。出错时，返回-1。这等同于 p中的Python表达式键 。

PyObject* PyDict_Copy(PyObject *p)

返回值：新引用。

返回包含与p相同的键值对的新字典。

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)

使用键将值插入字典p。键必须为hashable；如果不是，则会引发TypeError。成功时返回0，失败时返回-1。

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)

使用键作为键，将值插入字典p。键应为char*。键对象使用PyUnicode_FromString(key)创建。成功时返回0，失败时返回-1。

int PyDict_DelItem(PyObject *p, PyObject *key)

使用键键删除字典中的条目p。键必须是可散列的；如果不是，则会引发TypeError。成功时返回0，失败时返回-1。

int PyDict_DelItemString(PyObject *p, const char *key)

删除字典p中的条目，该条目具有由字符串键指定的键。成功时返回0，失败时返回-1。

PyObject* PyDict_GetItem(PyObject *p, PyObject *key)

返回值：借用引用。

从字典p返回对象，其中键键。Return NULL if the key key is not present, but without setting an exception.

PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key)

PyDict_GetItem()的变体，不会抑制异常。如果发生异常，则返回NULL 与异常集合。如果键不存在，则返回NULL （不设置异常集）。

PyObject* PyDict_GetItemString(PyObject *p, const char *key)

返回值：借用引用。

这与PyDict_GetItem()相同，但键被指定为char*，而不是PyObject*

PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *default)

返回值：借用引用。

这与Python级别dict.setdefault()相同。如果存在，则从字典p返回与键对应的值。如果键不在dict中，则插入值defaultobj和返回defaultobj。此函数仅对键的哈希函数求值一次，而不是独立地为查找和插入求值。

版本3.4中的新功能。

PyObject* PyDict_Items(PyObject *p)

返回值：新引用。

返回包含字典中所有项的PyListObject。

PyObject* PyDict_Keys(PyObject *p)

返回值：新引用。

返回包含字典中所有键的PyListObject。

PyObject* PyDict_Values(PyObject *p)

返回值：新引用。

返回包含字典p中所有值的PyListObject。

Py_ssize_t PyDict_Size(PyObject *p)

返回字典中的项目数。这相当于字典中的len(p)。

int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)

迭代字典中的所有键值对p。在对该函数的第一次调用开始迭代之前，由ppos引用的Py_ssize_t必须初始化为0该函数对字典中的每个对返回true，并且在所有对已经被报告之后返回false。The parameters pkey and pvalue should either point to PyObject* variables that will be filled in with each key and value, respectively, or may be NULL. 通过它们返回的任何引用都是借用的。ppos不应在迭代过程中更改。其值表示内部字典结构中的偏移，并且由于结构是稀疏的，所以偏移不是连续的。

例如：

PyObject *key, *value;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    /* do something interesting with the values... */
    ...
}

在迭代期间，字典p不应该改变。在迭代字典时，可以安全地修改键的值，但只要键的集合不发生更改即可。例如：

PyObject *key, *value;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    long i = PyLong_AsLong(value);
    if (i == -1 && PyErr_Occurred()) {
        return -1;
    }
    PyObject *o = PyLong_FromLong(i + 1);
    if (o == NULL)
        return -1;
    if (PyDict_SetItem(self->dict, key, o) < 0) {
        Py_DECREF(o);
        return -1;
    }
    Py_DECREF(o);
}

int PyDict_Merge(PyObject *a, PyObject *b, int override)

迭代映射对象b将键值对添加到字典a。 b可以是字典或支持PyMapping_Keys()和PyObject_GetItem()的任何对象。如果b中找到匹配的键，则a中的现有对将被替换，否则只有在添加了在a中不是匹配键。如果出现异常，则返回0成功或-1。

int PyDict_Update(PyObject *a, PyObject *b)

这与C中的PyDict_Merge（a， b， 1）相同，类似于a.update(b)，除了PyDict_Update()不会回退到键值对的序列，如果第二个参数没有“keys”属性。如果出现异常，则返回0成功或-1。

int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)

从seq2中的键值对更新或合并到字典a中。seq2必须是可迭代对象，生成长度为2的可迭代对象，并视为键值对。在重复键的情况下，如果重写为真，则最后的胜利，否则第一胜利。如果出现异常，则返回0成功或-1。等效Python（返回值除外）：

def PyDict_MergeFromSeq2(a, seq2, override):
    for key, value in seq2:
        if override or key not in a:
            a[key] = value

int PyDict_ClearFreeList()

清除空闲列表。返回已释放项目的总数。

版本3.3中的新功能。