diff options
Diffstat (limited to 'Doc/c-api/mapping.rst')
| -rw-r--r-- | Doc/c-api/mapping.rst | 66 |
1 files changed, 37 insertions, 29 deletions
diff --git a/Doc/c-api/mapping.rst b/Doc/c-api/mapping.rst index 308a976..b8eaadb 100644 --- a/Doc/c-api/mapping.rst +++ b/Doc/c-api/mapping.rst @@ -5,11 +5,17 @@ Mapping Protocol ================ +See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and +:c:func:`PyObject_DelItem`. + .. c:function:: int PyMapping_Check(PyObject *o) - Return ``1`` if the object provides mapping protocol, and ``0`` otherwise. This - function always succeeds. + Return ``1`` if the object provides mapping protocol or supports slicing, + and ``0`` otherwise. Note that it returns ``1`` for Python classes with + a :meth:`__getitem__` method since in general case it is impossible to + determine what the type of keys it supports. This function always + succeeds. .. c:function:: Py_ssize_t PyMapping_Size(PyObject *o) @@ -17,35 +23,49 @@ Mapping Protocol .. index:: builtin: len - Returns the number of keys in object *o* on success, and ``-1`` on failure. For - objects that do not provide mapping protocol, this is equivalent to the Python - expression ``len(o)``. + Returns the number of keys in object *o* on success, and ``-1`` on failure. + This is equivalent to the Python expression ``len(o)``. -.. c:function:: int PyMapping_DelItemString(PyObject *o, const char *key) +.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, const char *key) + + Return element of *o* corresponding to the string *key* or *NULL* on failure. + This is the equivalent of the Python expression ``o[key]``. + See also :c:func:`PyObject_GetItem`. + - Remove the mapping for object *key* from the object *o*. Return ``-1`` on - failure. This is equivalent to the Python statement ``del o[key]``. +.. c:function:: int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v) + + Map the string *key* to the value *v* in object *o*. Returns ``-1`` on + failure. This is the equivalent of the Python statement ``o[key] = v``. + See also :c:func:`PyObject_SetItem`. .. c:function:: int PyMapping_DelItem(PyObject *o, PyObject *key) - Remove the mapping for object *key* from the object *o*. Return ``-1`` on - failure. This is equivalent to the Python statement ``del o[key]``. + Remove the mapping for the object *key* from the object *o*. Return ``-1`` + on failure. This is equivalent to the Python statement ``del o[key]``. + This is an alias of :c:func:`PyObject_DelItem`. -.. c:function:: int PyMapping_HasKeyString(PyObject *o, const char *key) +.. c:function:: int PyMapping_DelItemString(PyObject *o, const char *key) - On success, return ``1`` if the mapping object has the key *key* and ``0`` - otherwise. This is equivalent to the Python expression ``key in o``. - This function always succeeds. + Remove the mapping for the string *key* from the object *o*. Return ``-1`` + on failure. This is equivalent to the Python statement ``del o[key]``. .. c:function:: int PyMapping_HasKey(PyObject *o, PyObject *key) - Return ``1`` if the mapping object has the key *key* and ``0`` otherwise. This - is equivalent to the Python expression ``key in o``. This function always - succeeds. + Return ``1`` if the mapping object has the key *key* and ``0`` otherwise. + This is equivalent to the Python expression ``key in o``. + This function always succeeds. + + +.. c:function:: int PyMapping_HasKeyString(PyObject *o, const char *key) + + Return ``1`` if the mapping object has the key *key* and ``0`` otherwise. + This is equivalent to the Python expression ``key in o``. + This function always succeeds. .. c:function:: PyObject* PyMapping_Keys(PyObject *o) @@ -73,15 +93,3 @@ Mapping Protocol .. versionchanged:: 3.7 Previously, the function returned a list or a tuple. - - -.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, const char *key) - - Return element of *o* corresponding to the object *key* or *NULL* on failure. - This is the equivalent of the Python expression ``o[key]``. - - -.. c:function:: int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v) - - Map the object *key* to the value *v* in object *o*. Returns ``-1`` on failure. - This is the equivalent of the Python statement ``o[key] = v``. |