|
1 .. highlightlang:: c |
|
2 |
|
3 .. _mapping: |
|
4 |
|
5 Mapping Protocol |
|
6 ================ |
|
7 |
|
8 |
|
9 .. cfunction:: int PyMapping_Check(PyObject *o) |
|
10 |
|
11 Return ``1`` if the object provides mapping protocol, and ``0`` otherwise. This |
|
12 function always succeeds. |
|
13 |
|
14 |
|
15 .. cfunction:: Py_ssize_t PyMapping_Length(PyObject *o) |
|
16 |
|
17 .. index:: builtin: len |
|
18 |
|
19 Returns the number of keys in object *o* on success, and ``-1`` on failure. For |
|
20 objects that do not provide mapping protocol, this is equivalent to the Python |
|
21 expression ``len(o)``. |
|
22 |
|
23 |
|
24 .. cfunction:: int PyMapping_DelItemString(PyObject *o, char *key) |
|
25 |
|
26 Remove the mapping for object *key* from the object *o*. Return ``-1`` on |
|
27 failure. This is equivalent to the Python statement ``del o[key]``. |
|
28 |
|
29 |
|
30 .. cfunction:: int PyMapping_DelItem(PyObject *o, PyObject *key) |
|
31 |
|
32 Remove the mapping for object *key* from the object *o*. Return ``-1`` on |
|
33 failure. This is equivalent to the Python statement ``del o[key]``. |
|
34 |
|
35 |
|
36 .. cfunction:: int PyMapping_HasKeyString(PyObject *o, char *key) |
|
37 |
|
38 On success, return ``1`` if the mapping object has the key *key* and ``0`` |
|
39 otherwise. This is equivalent to ``o[key]``, returning ``True`` on success |
|
40 and ``False`` on an exception. This function always succeeds. |
|
41 |
|
42 |
|
43 .. cfunction:: int PyMapping_HasKey(PyObject *o, PyObject *key) |
|
44 |
|
45 Return ``1`` if the mapping object has the key *key* and ``0`` otherwise. |
|
46 This is equivalent to ``o[key]``, returning ``True`` on success and ``False`` |
|
47 on an exception. This function always succeeds. |
|
48 |
|
49 |
|
50 .. cfunction:: PyObject* PyMapping_Keys(PyObject *o) |
|
51 |
|
52 On success, return a list of the keys in object *o*. On failure, return *NULL*. |
|
53 This is equivalent to the Python expression ``o.keys()``. |
|
54 |
|
55 |
|
56 .. cfunction:: PyObject* PyMapping_Values(PyObject *o) |
|
57 |
|
58 On success, return a list of the values in object *o*. On failure, return |
|
59 *NULL*. This is equivalent to the Python expression ``o.values()``. |
|
60 |
|
61 |
|
62 .. cfunction:: PyObject* PyMapping_Items(PyObject *o) |
|
63 |
|
64 On success, return a list of the items in object *o*, where each item is a tuple |
|
65 containing a key-value pair. On failure, return *NULL*. This is equivalent to |
|
66 the Python expression ``o.items()``. |
|
67 |
|
68 |
|
69 .. cfunction:: PyObject* PyMapping_GetItemString(PyObject *o, char *key) |
|
70 |
|
71 Return element of *o* corresponding to the object *key* or *NULL* on failure. |
|
72 This is the equivalent of the Python expression ``o[key]``. |
|
73 |
|
74 |
|
75 .. cfunction:: int PyMapping_SetItemString(PyObject *o, char *key, PyObject *v) |
|
76 |
|
77 Map the object *key* to the value *v* in object *o*. Returns ``-1`` on failure. |
|
78 This is the equivalent of the Python statement ``o[key] = v``. |