GNU Info

(python2.1-api.info)Dictionary Objects

---

Prev: Mapping Objects Up: Mapping Objects

---

Enter node , (file) or (file)node

Dictionary Objects
------------------

`PyDictObject'
     This subtype of `PyObject' represents a Python dictionary object.

`PyTypeObject PyDict_Type'
     This instance of `PyTypeObject' represents the Python dictionary
     type.  This is exposed to Python programs as `types.DictType' and
     `types.DictionaryType'.

`int PyDict_Check(PyObject *p)'
     Returns true if its argument is a `PyDictObject'.

`PyObject* PyDict_New()'
     Returns a new empty dictionary, or `NULL' on failure.

`void PyDict_Clear(PyObject *p)'
     Empties an existing dictionary of all key-value pairs.

`PyObject* PyDict_Copy(PyObject *p)'
     Returns a new dictionary that contains the same key-value pairs as
     p.  Empties an existing dictionary of all key-value pairs.

`int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)'
     Inserts VALUE into the dictionary P with a key of KEY.  KEY must
     be hashable; if it isn't, `TypeError' will be raised.  Returns `0'
     on success or `-1' on failure.

`int PyDict_SetItemString(PyObject *p, char *key, PyObject *val)'
     Inserts VALUE into the dictionary P using KEY as a key. KEY should
     be a `char*'.  The key object is created using
     `PyString_FromString(KEY)'.  Returns `0' on success or `-1' on
     failure.

`int PyDict_DelItem(PyObject *p, PyObject *key)'
     Removes the entry in dictionary P with key KEY.  KEY must be
     hashable; if it isn't, `TypeError' is raised.

`int PyDict_DelItemString(PyObject *p, char *key)'
     Removes the entry in dictionary P which has a key specified by the
     string KEY.  Returns `0' on success or `-1' on failure.

`PyObject* PyDict_GetItem(PyObject *p, PyObject *key)'
     Returns the object from dictionary P which has a key KEY.  Returns
     `NULL' if the key KEY is not present, but _without_ setting an
     exception.

`PyObject* PyDict_GetItemString(PyObject *p, char *key)'
     This is the same as `PyDict_GetItem()', but KEY is specified as a
     `char*', rather than a `PyObject*'.

`PyObject* PyDict_Items(PyObject *p)'
     Returns a `PyListObject' containing all the items from the
     dictionary, as in the dictinoary method `items()' (see the ).

`PyObject* PyDict_Keys(PyObject *p)'
     Returns a `PyListObject' containing all the keys from the
     dictionary, as in the dictionary method `keys()' (see the ).

`PyObject* PyDict_Values(PyObject *p)'
     Returns a `PyListObject' containing all the values from the
     dictionary P, as in the dictionary method `values()' (see the ).

`int PyDict_Size(PyObject *p)'
     Returns the number of items in the dictionary.  This is equivalent
     to `len(P)' on a dictionary.

`int PyDict_Next(PyObject *p, int *ppos, PyObject **pkey, PyObject **pvalue)'
     Iterate over all key-value pairs in the dictionary P.  The `int'
     referred to by PPOS must be initialized to `0' prior to the first
     call to this function to start the iteration; the function returns
     true for each pair in the dictionary, and false once all pairs
     have been reported.  The parameters PKEY and PVALUE should either
     point to `PyObject*' variables that will be filled in with each
     key and value, respectively, or may be `NULL'.

     For example:

          PyObject *key, *value;
          int pos = 0;
          
          while (PyDict_Next(self->dict, &pos, &key, &value)) {
              /* do something interesting with the values... */
              ...
          }

     The dictionary P should not be mutated during iteration.  It is
     safe (since Python 2.1) to modify the values of the keys as you
     iterate over the dictionary, for example:

          PyObject *key, *value;
          int pos = 0;
          
          while (PyDict_Next(self->dict, &pos, &key, &value)) {
              int i = PyInt_AS_LONG(value) + 1;
              PyObject *o = PyInt_FromLong(i);
              if (o == NULL)
                  return -1;
              if (PyDict_SetItem(self->dict, key, o) < 0) {
                  Py_DECREF(o);
                  return -1;
              }
              Py_DECREF(o);
          }