sam-t2/devtools/amd64/html/python/api/dictObjects.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="api.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="api.html" title='Python/C API Reference Manual' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="prev" href="mapObjects.html" />
<link rel="parent" href="mapObjects.html" />
<link rel="next" href="otherObjects.html" />
<meta name='aesop' content='information' />
<title>7.4.1 Dictionary Objects </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="7.4 Mapping Objects"
  href="mapObjects.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="7.4 Mapping Objects"
  href="mapObjects.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="7.5 Other Objects"
  href="otherObjects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python/C API Reference Manual</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="mapObjects.html">7.4 Mapping Objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="mapObjects.html">7.4 Mapping Objects</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="otherObjects.html">7.5 Other Objects</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION009410000000000000000"></A><A NAME="dictObjects"></A>
<BR>
7.4.1 Dictionary Objects
</H2>

<P>
<a id='l2h-603' xml:id='l2h-603'></a><dl><dt><b><tt class="ctype"><a id='l2h-604' xml:id='l2h-604'>PyDictObject</a></tt></b></dt>
<dd>
  This subtype of <tt class="ctype">PyObject</tt> represents a Python dictionary
  object.
</dl>

<P>
<dl><dt>PyTypeObject <b><tt id='l2h-605' xml:id='l2h-605' class="cdata">PyDict_Type</tt></b></dt>
<dd>
  This instance of <tt class="ctype">PyTypeObject</tt> represents the Python
  dictionary type.  This is exposed to Python programs as
  <code>types.DictType</code> and <code>types.DictionaryType</code>.
  <a id='l2h-607' xml:id='l2h-607'></a></dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-608' xml:id='l2h-608' class="cfunction">PyDict_Check</tt></b>(</nobr></td><td>PyObject *<var>p</var>)</td></tr></table></dt>
<dd>
  Return true if <var>p</var> is a dict object or an instance of a
  subtype of the dict type.

<span class="versionnote">Changed in version 2.2:
Allowed subtypes to be accepted.</span>

</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-609' xml:id='l2h-609' class="cfunction">PyDict_CheckExact</tt></b>(</nobr></td><td>PyObject *<var>p</var>)</td></tr></table></dt>
<dd>
  Return true if <var>p</var> is a dict object, but not an instance of a
  subtype of the dict type.

<span class="versionnote">New in version 2.4.</span>

</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-610' xml:id='l2h-610' class="cfunction">PyDict_New</tt></b>(</nobr></td><td>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">New reference.</span>
</div>
  Return a new empty dictionary, or <tt class="constant">NULL</tt> on failure.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-611' xml:id='l2h-611' class="cfunction">PyDictProxy_New</tt></b>(</nobr></td><td>PyObject *<var>dict</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">New reference.</span>
</div>
  Return a proxy object for a mapping which enforces read-only
  behavior.  This is normally used to create a proxy to prevent
  modification of the dictionary for non-dynamic class types.

<span class="versionnote">New in version 2.2.</span>

</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-612' xml:id='l2h-612' class="cfunction">PyDict_Clear</tt></b>(</nobr></td><td>PyObject *<var>p</var>)</td></tr></table></dt>
<dd>
  Empty an existing dictionary of all key-value pairs.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-613' xml:id='l2h-613' class="cfunction">PyDict_Contains</tt></b>(</nobr></td><td>PyObject *<var>p</var>, PyObject *<var>key</var>)</td></tr></table></dt>
<dd>
  Determine if dictionary <var>p</var> contains <var>key</var>.  If an item
  in <var>p</var> is matches <var>key</var>, return <code>1</code>, otherwise return
  <code>0</code>.  On error, return <code>-1</code>.  This is equivalent to the
  Python expression "<tt class="samp"><var>key</var> in <var>p</var></tt>".

<span class="versionnote">New in version 2.4.</span>

</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-614' xml:id='l2h-614' class="cfunction">PyDict_Copy</tt></b>(</nobr></td><td>PyObject *<var>p</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">New reference.</span>
</div>
  Return a new dictionary that contains the same key-value pairs as
  <var>p</var>.

<span class="versionnote">New in version 1.6.</span>

</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-615' xml:id='l2h-615' class="cfunction">PyDict_SetItem</tt></b>(</nobr></td><td>PyObject *<var>p</var>, PyObject *<var>key</var>,
                                       PyObject *<var>val</var>)</td></tr></table></dt>
<dd>
  Insert <var>value</var> into the dictionary <var>p</var> with a key of
  <var>key</var>.  <var>key</var> must be hashable; if it isn't,
  <tt class="exception">TypeError</tt> will be raised.
  Return <code>0</code> on success or <code>-1</code> on failure.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-616' xml:id='l2h-616' class="cfunction">PyDict_SetItemString</tt></b>(</nobr></td><td>PyObject *<var>p</var>,
            char *<var>key</var>,
            PyObject *<var>val</var>)</td></tr></table></dt>
<dd>
  Insert <var>value</var> into the dictionary <var>p</var> using <var>key</var> as a
  key. <var>key</var> should be a <tt class="ctype">char*</tt>.  The key object is created
  using <code>PyString_FromString(<var>key</var>)</code>. Return <code>0</code> on
  success or <code>-1</code> on failure.
  <a id='l2h-630' xml:id='l2h-630'></a>
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-617' xml:id='l2h-617' class="cfunction">PyDict_DelItem</tt></b>(</nobr></td><td>PyObject *<var>p</var>, PyObject *<var>key</var>)</td></tr></table></dt>
<dd>
  Remove the entry in dictionary <var>p</var> with key <var>key</var>.
  <var>key</var> must be hashable; if it isn't, <tt class="exception">TypeError</tt> is
  raised.  Return <code>0</code> on success or <code>-1</code> on failure.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-618' xml:id='l2h-618' class="cfunction">PyDict_DelItemString</tt></b>(</nobr></td><td>PyObject *<var>p</var>, char *<var>key</var>)</td></tr></table></dt>
<dd>
  Remove the entry in dictionary <var>p</var> which has a key specified by
  the string <var>key</var>.  Return <code>0</code> on success or <code>-1</code> on
  failure.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-619' xml:id='l2h-619' class="cfunction">PyDict_GetItem</tt></b>(</nobr></td><td>PyObject *<var>p</var>, PyObject *<var>key</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">Borrowed reference.</span>
</div>
  Return the object from dictionary <var>p</var> which has a key
  <var>key</var>.  Return <tt class="constant">NULL</tt> if the key <var>key</var> is not present, but
  <em>without</em> setting an exception.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-620' xml:id='l2h-620' class="cfunction">PyDict_GetItemString</tt></b>(</nobr></td><td>PyObject *<var>p</var>, char *<var>key</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">Borrowed reference.</span>
</div>
  This is the same as <tt class="cfunction">PyDict_GetItem()</tt>, but <var>key</var> is
  specified as a <tt class="ctype">char*</tt>, rather than a <tt class="ctype">PyObject*</tt>.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-621' xml:id='l2h-621' class="cfunction">PyDict_Items</tt></b>(</nobr></td><td>PyObject *<var>p</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">New reference.</span>
</div>
  Return a <tt class="ctype">PyListObject</tt> containing all the items from the
  dictionary, as in the dictionary method <tt class="method">items()</tt> (see the
  <em class="citetitle"><a
 href="../lib/lib.html"
 title="Python Library Reference"
 >Python Library Reference</a></em>).
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-622' xml:id='l2h-622' class="cfunction">PyDict_Keys</tt></b>(</nobr></td><td>PyObject *<var>p</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">New reference.</span>
</div>
  Return a <tt class="ctype">PyListObject</tt> containing all the keys from the
  dictionary, as in the dictionary method <tt class="method">keys()</tt> (see the
  <em class="citetitle"><a
 href="../lib/lib.html"
 title="Python Library Reference"
 >Python Library Reference</a></em>).
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-623' xml:id='l2h-623' class="cfunction">PyDict_Values</tt></b>(</nobr></td><td>PyObject *<var>p</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">New reference.</span>
</div>
  Return a <tt class="ctype">PyListObject</tt> containing all the values from the
  dictionary <var>p</var>, as in the dictionary method <tt class="method">values()</tt>
  (see the <em class="citetitle"><a
 href="../lib/lib.html"
 title="Python Library Reference"
 >Python Library Reference</a></em>).
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-624' xml:id='l2h-624' class="cfunction">PyDict_Size</tt></b>(</nobr></td><td>PyObject *<var>p</var>)</td></tr></table></dt>
<dd>
  Return the number of items in the dictionary.  This is equivalent
  to "<tt class="samp">len(<var>p</var>)</tt>" on a dictionary.<a id='l2h-625' xml:id='l2h-625'></a></dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-626' xml:id='l2h-626' class="cfunction">PyDict_Next</tt></b>(</nobr></td><td>PyObject *<var>p</var>, int *<var>ppos</var>,
                                    PyObject **<var>pkey</var>, PyObject **<var>pvalue</var>)</td></tr></table></dt>
<dd>
  Iterate over all key-value pairs in the dictionary <var>p</var>.  The
  <tt class="ctype">int</tt> referred to by <var>ppos</var> must be initialized to
  <code>0</code> 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 <var>pkey</var> and <var>pvalue</var> should either point to
  <tt class="ctype">PyObject*</tt> variables that will be filled in with each key and
  value, respectively, or may be <tt class="constant">NULL</tt>.  Any references returned through
  them are borrowed.  <var>ppos</var> should not be altered during iteration.
  Its value represents offsets within the internal dictionary structure,
  and since the structure is sparse, the offsets are not consecutive.

<P>
For example:

<P>
<div class="verbatim"><pre>
PyObject *key, *value;
int pos = 0;

while (PyDict_Next(self-&gt;dict, &amp;pos, &amp;key, &amp;value)) {
    /* do something interesting with the values... */
    ...
}
</pre></div>

<P>
The dictionary <var>p</var> 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, but only so long as the set of keys
  does not change.  For example:

<P>
<div class="verbatim"><pre>
PyObject *key, *value;
int pos = 0;

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

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-627' xml:id='l2h-627' class="cfunction">PyDict_Merge</tt></b>(</nobr></td><td>PyObject *<var>a</var>, PyObject *<var>b</var>, int <var>override</var>)</td></tr></table></dt>
<dd>
  Iterate over mapping object <var>b</var> adding key-value pairs to dictionary
  <var>a</var>.
  <var>b</var> may be a dictionary, or any object supporting
  <tt class="function">PyMapping_Keys()</tt> and <tt class="function">PyObject_GetItem()</tt>.
  If <var>override</var> is true, existing pairs in <var>a</var> will
  be replaced if a matching key is found in <var>b</var>, otherwise pairs
  will only be added if there is not a matching key in <var>a</var>.
  Return <code>0</code> on success or <code>-1</code> if an exception was
  raised.

<span class="versionnote">New in version 2.2.</span>

</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-628' xml:id='l2h-628' class="cfunction">PyDict_Update</tt></b>(</nobr></td><td>PyObject *<var>a</var>, PyObject *<var>b</var>)</td></tr></table></dt>
<dd>
  This is the same as <code>PyDict_Merge(<var>a</var>, <var>b</var>, 1)</code> in C,
  or <code><var>a</var>.update(<var>b</var>)</code> in Python.  Return <code>0</code> on
  success or <code>-1</code> if an exception was raised.

<span class="versionnote">New in version 2.2.</span>

</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-629' xml:id='l2h-629' class="cfunction">PyDict_MergeFromSeq2</tt></b>(</nobr></td><td>PyObject *<var>a</var>, PyObject *<var>seq2</var>,
                                             int <var>override</var>)</td></tr></table></dt>
<dd>
  Update or merge into dictionary <var>a</var>, from the key-value pairs in
  <var>seq2</var>.  <var>seq2</var> 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 <var>override</var> is true, else the
  first wins.
  Return <code>0</code> on success or <code>-1</code> if an exception
  was raised.
  Equivalent Python (except for the return value):

<P>
<div class="verbatim"><pre>
def PyDict_MergeFromSeq2(a, seq2, override):
    for key, value in seq2:
        if override or key not in a:
            a[key] = value
</pre></div>

<P>

<span class="versionnote">New in version 2.2.</span>

</dd></dl>

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="7.4 Mapping Objects"
  href="mapObjects.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="7.4 Mapping Objects"
  href="mapObjects.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="7.5 Other Objects"
  href="otherObjects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python/C API Reference Manual</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="mapObjects.html">7.4 Mapping Objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="mapObjects.html">7.4 Mapping Objects</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="otherObjects.html">7.5 Other Objects</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>