# 字典对象

`PyDictObject`

  这个 `PyObject` 的子类型代表一个Python字典对象。

PyTypeObject `PyDict_Type`

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

int `PyDict_Check`(PyObject *p)

  如果 p 是字典对象或者字典类型的子类型的实例，则返回真。

int `PyDict_CheckExact`(PyObject *p)

  如果 p 是字典对象但不是字典类型的子类型的实例，则返回真。

PyObject* `PyDict_New`()
  Return value: New reference.

  返回一个新的空字典或者返回 NULL 表示失败。

PyObject* `PyDictProxy_New`(PyObject *mapping)
  Return value: New reference.

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

void `PyDict_Clear`(PyObject *p)

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

int `PyDict_Contains`(PyObject *p, PyObject *key)

  确定 key 是否包含在字典 p 中。如果 key 匹配上 p 的某一项，则返回 `1` ，否则返回 `0` 。返回 `-1` 表示出错。这等同于Python表达式 `key in p` 。

PyObject* `PyDict_Copy`(PyObject *p)
  Return value: New reference.

  返回与 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)

  使用 key 作为键将 value 插入到字典 p 中。key 必须为 `const char*`。键对象是由 `PyUnicode_FromString(key)` 创建的。成功时返回 `0`，失败时返回 `-1`。

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)
  Return value: Borrowed reference.

  变种的 `PyDict_GetItem()` 会抛出异常。当异常发生，返回 NULL 并 设置异常。当键不存在，返回 NULL 但不会 设置异常。

PyObject* `PyDict_GetItemString`(PyObject *p, const char *key)
  Return value: Borrowed reference.

  这与 `PyDict_GetItem()` 一样，但是 key 需要指定一个 `const char*` ，而不是 `PyObject*` 。

  需要注意的是，调用 `__hash__()` 、 `__eq__()` 方法和创建一个临时的字符串对象时产生的异常不会被抛出。改用 `PyDict_GetItemWithError()` 获得错误报告。

PyObject* `PyDict_SetDefault`(PyObject *p, PyObject *key, PyObject *defaultobj)
  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`。

Py_ssize_t `PyDict_Size`(PyObject *p)

  返回字典中项目数，等价于对字典 p 使用 `len(p)`。

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()` and `PyObject_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. Return `0` 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 to `a.update(b)` in Python except that `PyDict_Update()` doesn't fall back to the iterating over a sequence of key value pairs if the second argument has no "keys" attribute. Return `0` 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 新版功能.