# 對映協定

另請參閱 `PyObject_GetItem()`、`PyObject_SetItem()` 和 `PyObject_DelItem()`。

int PyMapping_Check(PyObject *o)
  為 穩定 ABI 的一部分.

  如果物件有提供對映協定或支援切片 (slicing) 則回傳 `1`，否則回傳 `0`。請注意，對於具有 `__getitem__()` 方法的 Python 類別，它會回傳 `1`，因為通常無法確定該類別支援什麼類型的鍵。這個函式總會是成功的。

Py_ssize_t PyMapping_Size(PyObject *o)
Py_ssize_t PyMapping_Length(PyObject *o)
  為 穩定 ABI 的一部分.

  成功時回傳物件 o 中的鍵數，失敗時回傳 `-1`。這相當於 Python 運算式 `len(o)`。

PyObject *PyMapping_GetItemString(PyObject *o, const char *key)
  回傳值：新的參照。 為 穩定 ABI 的一部分.

  這與 `PyObject_GetItem()` 相同，但 key 被指定為 const char* UTF-8 編碼位元組字串，而不是 PyObject*。

int PyMapping_GetOptionalItem(PyObject *obj, PyObject *key, PyObject **result)
  為 穩定 ABI 的一部分 自 3.13 版本開始.

  Variant of `PyObject_GetItem()` which doesn't raise `KeyError` if the key is not found.

  If the key is found, return `1` and set *result to a new strong reference to the corresponding value. If the key is not found, return `0` and set *result to `NULL`; the `KeyError` is silenced. If an error other than `KeyError` is raised, return `-1` and set *result to `NULL`.

  在 3.13 版被加入.

int PyMapping_GetOptionalItemString(PyObject *obj, const char *key, PyObject **result)
  為 穩定 ABI 的一部分 自 3.13 版本開始.

  這與 `PyMapping_GetOptionalItem()` 相同，但 key 被指定為 const char* UTF-8 編碼位元組字串，而不是 PyObject*。

  在 3.13 版被加入.

int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v)
  為 穩定 ABI 的一部分.

  這與 `PyObject_SetItem()` 相同，但 key 被指定為 const char* UTF-8 編碼位元組字串，而不是 PyObject*。

int PyMapping_DelItem(PyObject *o, PyObject *key)

  這是 `PyObject_DelItem()` 的別名。

int PyMapping_DelItemString(PyObject *o, const char *key)

  這與 `PyObject_DelItem()` 相同，但 key 被指定為 const char* UTF-8 編碼位元組字串，而不是 PyObject*。

int PyMapping_HasKeyWithError(PyObject *o, PyObject *key)
  為 穩定 ABI 的一部分 自 3.13 版本開始.

  如果對映物件具有鍵 key 則回傳 `1`，否則回傳 `0`。這相當於 Python 運算式 `key in o`。失敗時回傳 `-1`。

  在 3.13 版被加入.

int PyMapping_HasKeyStringWithError(PyObject *o, const char *key)
  為 穩定 ABI 的一部分 自 3.13 版本開始.

  這與 `PyMapping_HasKeyWithError()` 相同，但 key 被指定為 const char* UTF-8 編碼位元組字串，而不是 PyObject*。

  在 3.13 版被加入.

int PyMapping_HasKey(PyObject *o, PyObject *key)
  為 穩定 ABI 的一部分.

  如果對映物件具有鍵 key 則回傳 `1`，否則回傳 `0`。這相當於 Python 運算式 `key in o`。這個函式總會是成功的。

  備註

  當它呼叫 `__getitem__()` 方法時發生的例外將被默默忽略。為了適當地處理錯誤，請改用 `PyMapping_HasKeyWithError()`、`PyMapping_GetOptionalItem()` 或 `PyObject_GetItem()`。

int PyMapping_HasKeyString(PyObject *o, const char *key)
  為 穩定 ABI 的一部分.

  這與 `PyMapping_HasKey()` 相同，但 key 被指定為 const char* UTF-8 編碼位元組字串，而不是 PyObject*。

  備註

  當它呼叫 `__getitem__()` 方法或建立臨時 `str` 物件時發生的例外將被默默忽略。為了適當地處理錯誤，請改用 `PyMapping_HasKeyStringWithError()`、`PyMapping_GetOptionalItemString()` 或 `PyMapping_GetItemString()`。

PyObject *PyMapping_Keys(PyObject *o)
  回傳值：新的參照。 為 穩定 ABI 的一部分.

  成功時回傳一個物件 o 內之鍵的串列，失敗時回傳 `NULL`。

  在 3.7 版的變更: 在以前，該函式會回傳串列或元組。

PyObject *PyMapping_Values(PyObject *o)
  回傳值：新的參照。 為 穩定 ABI 的一部分.

  成功時回傳物件 o 中值的串列。失敗時回傳 `NULL`。

  在 3.7 版的變更: 在以前，該函式會回傳串列或元組。

PyObject *PyMapping_Items(PyObject *o)
  回傳值：新的參照。 為 穩定 ABI 的一部分.

  成功時回傳物件 o 內之項目的串列，其中每個項目都是包含鍵值對的元組。失敗時回傳 `NULL`。

  在 3.7 版的變更: 在以前，該函式會回傳串列或元組。