字典对象¶
-
PyTypeObject
PyDict_Type
¶ Python字典类型表示为
PyTypeObject
的实例。这与Python层面的dict
是相同的对象。
-
PyObject*
PyDictProxy_New
(PyObject *mapping)¶ - Return value: New reference.
返回
types.MappingProxyType
对象,用于强制执行只读行为的映射。这通常用于创建视图以防止修改非动态类类型的字典。
-
int
PyDict_Contains
(PyObject *p, PyObject *key)¶ 确定 key 是否包含在字典 p 中。如果 key 匹配上 p 的某一项,则返回
1
,否则返回0
。返回-1
表示出错。这等同于Python表达式key in p
。
-
int
PyDict_SetItem
(PyObject *p, PyObject *key, PyObject *val)¶ 使用 key 作为键将 value 插入字典 p 。 key 必须为 hashable ;如果不是,会抛出
TypeError
异常。成功返回0
,失败返回-1
。
-
int
PyDict_SetItemString
(PyObject *p, const char *key, PyObject *val)¶ Insert value into the dictionary p using key as a key. key should be a
char*
. The key object is created usingPyUnicode_FromString(key)
. Return0
on success or-1
on failure.
-
int
PyDict_DelItem
(PyObject *p, PyObject *key)¶ 使用键 key 删除字典 p 中的条目。 key 必须是可哈希的;如果不是,则抛出
TypeError
异常。成功时返回0
,失败时返回-1
。
-
int
PyDict_DelItemString
(PyObject *p, const char *key)¶ 删除字典 p 中的条目,其中包含由字符串 key 指定的键。成功时返回“0,失败时返回“-1”。
-
PyObject*
PyDict_GetItem
(PyObject *p, PyObject *key)¶ - Return value: Borrowed reference.
返回字典 p 中 key 作为键的对象。如果键 key 不存在则返回 NULL ,但可以使用 without 设置例外。
需要注意的是,调用
__hash__()
和__eq__()
方法产生的异常不会被抛出。改用PyDict_GetItemWithError()
获得错误报告。
-
PyObject*
PyDict_GetItemWithError
(PyObject *p, PyObject *key)¶ 变种的
PyDict_GetItem()
会抛出异常。当异常发生,返回 NULL 并 设置异常。当键不存在,返回 NULL 但不会 设置异常。
-
PyObject*
PyDict_GetItemString
(PyObject *p, const char *key)¶ - Return value: Borrowed reference.
This is the same as
PyDict_GetItem()
, but key is specified as achar*
, rather than aPyObject*
.需要注意的是,调用
__hash__()
、__eq__()
方法和创建一个临时的字符串对象时产生的异常不会被抛出。改用PyDict_GetItemWithError()
获得错误报告。
-
PyObject*
PyDict_SetDefault
(PyObject *p, PyObject *key, PyObject *default)¶ - Return value: Borrowed reference.
这跟Python层面的
dict.setdefault()
一样。如果键 key 存在,它返回在字典 p 里面对应的值。如果键不存在,它会和值 defaultobj 一起插入并返回 defaultobj 。这个函数只计算 key 的哈希函数一次,而不是在查找和插入时分别计算它。3.4 新版功能.
-
PyObject*
PyDict_Items
(PyObject *p)¶ - Return value: New reference.
返回一个包含字典中所有键值项的
PyListObject
。
-
PyObject*
PyDict_Keys
(PyObject *p)¶ - Return value: New reference.
返回一个包含字典中所有键(keys)的
PyListObject
。
-
PyObject*
PyDict_Values
(PyObject *p)¶ - Return value: New reference.
返回一个包含字典中所有值(values)的
PyListObject
。
-
int
PyDict_Next
(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)¶ 迭代字典 p 中的所有键值对。在第一次调用此函数开始迭代之前,必须将 ppos 引用的
Py_ssize_t
初始化为0
;对于字典中的每一对,该函数返回 true ,一旦报告了所有对,该函数返回 false 。参数 pkey 和 pvalue 应指向PyObject*
变量,分别用每个键和值填充,或者可以是 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)¶ Iterate over mapping object b adding key-value pairs to dictionary a. b may be a dictionary, or any object supporting
PyMapping_Keys()
andPyObject_GetItem()
. If override is true, existing pairs in a will be replaced if a matching key is found in b, otherwise pairs will only be added if there is not a matching key in a. Return0
on success or-1
if an exception was raised.
-
int
PyDict_Update
(PyObject *a, PyObject *b)¶ This is the same as
PyDict_Merge(a, b, 1)
in C, and is similar toa.update(b)
in Python except thatPyDict_Update()
doesn’t fall back to the iterating over a sequence of key value pairs if the second argument has no “keys” attribute. Return0
on success or-1
if an exception was raised.
-
int
PyDict_MergeFromSeq2
(PyObject *a, PyObject *seq2, int override)¶ Update or merge into dictionary a, from the key-value pairs in seq2. seq2 must be an iterable object producing iterable objects of length 2, viewed as key-value pairs. In case of duplicate keys, the last wins if override is true, else the first wins. Return
0
on success or-1
if an exception was raised. Equivalent Python (except for the return value):def PyDict_MergeFromSeq2(a, seq2, override): for key, value in seq2: if override or key not in a: a[key] = value
-
int
PyDict_ClearFreeList
()¶ Clear the free list. Return the total number of freed items.
3.3 新版功能.