projects / OpenSPARC-T2-SAM / blame
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Initial commit of OpenSPARC T2 architecture model.
[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / api / dictObjects.html
CommitLineData
920dae64
AT		 1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3<head>
4<link rel="STYLESHEET" href="api.css" type='text/css' />
5<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
6<link rel='start' href='../index.html' title='Python Documentation Index' />
7<link rel="first" href="api.html" title='Python/C API Reference Manual' />
8<link rel='contents' href='contents.html' title="Contents" />
9<link rel='index' href='genindex.html' title='Index' />
10<link rel='last' href='about.html' title='About this document...' />
11<link rel='help' href='about.html' title='About this document...' />
12<link rel="prev" href="mapObjects.html" />
13<link rel="parent" href="mapObjects.html" />
14<link rel="next" href="otherObjects.html" />
15<meta name='aesop' content='information' />
16<title>7.4.1 Dictionary Objects </title>
17</head>
18<body>
19<DIV CLASS="navigation">
20<div id='top-navigation-panel' xml:id='top-navigation-panel'>
21<table align="center" width="100%" cellpadding="0" cellspacing="2">
22<tr>
23<td class='online-navigation'><a rel="prev" title="7.4 Mapping Objects"
24 href="mapObjects.html"><img src='../icons/previous.png'
25 border='0' height='32' alt='Previous Page' width='32' /></A></td>
26<td class='online-navigation'><a rel="parent" title="7.4 Mapping Objects"
27 href="mapObjects.html"><img src='../icons/up.png'
28 border='0' height='32' alt='Up One Level' width='32' /></A></td>
29<td class='online-navigation'><a rel="next" title="7.5 Other Objects"
30 href="otherObjects.html"><img src='../icons/next.png'
31 border='0' height='32' alt='Next Page' width='32' /></A></td>
32<td align="center" width="100%">Python/C API Reference Manual</td>
33<td class='online-navigation'><a rel="contents" title="Table of Contents"
34 href="contents.html"><img src='../icons/contents.png'
35 border='0' height='32' alt='Contents' width='32' /></A></td>
36<td class='online-navigation'><img src='../icons/blank.png'
37 border='0' height='32' alt='' width='32' /></td>
38<td class='online-navigation'><a rel="index" title="Index"
39 href="genindex.html"><img src='../icons/index.png'
40 border='0' height='32' alt='Index' width='32' /></A></td>
41</tr></table>
42<div class='online-navigation'>
43<b class="navlabel">Previous:</b>
44<a class="sectref" rel="prev" href="mapObjects.html">7.4 Mapping Objects</A>
45<b class="navlabel">Up:</b>
46<a class="sectref" rel="parent" href="mapObjects.html">7.4 Mapping Objects</A>
47<b class="navlabel">Next:</b>
48<a class="sectref" rel="next" href="otherObjects.html">7.5 Other Objects</A>
49</div>
50<hr /></div>
51</DIV>
52<!--End of Navigation Panel-->
53
54<H2><A NAME="SECTION009410000000000000000"></A><A NAME="dictObjects"></A>
55<BR>
567.4.1 Dictionary Objects
57</H2>
58
59<P>
60<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>
61<dd>
62 This subtype of <tt class="ctype">PyObject</tt> represents a Python dictionary
63 object.
64</dl>
65
66<P>
67<dl><dt>PyTypeObject <b><tt id='l2h-605' xml:id='l2h-605' class="cdata">PyDict_Type</tt></b></dt>
68<dd>
69 This instance of <tt class="ctype">PyTypeObject</tt> represents the Python
70 dictionary type. This is exposed to Python programs as
71 <code>types.DictType</code> and <code>types.DictionaryType</code>.
72 <a id='l2h-607' xml:id='l2h-607'></a></dd></dl>
73
74<P>
75<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>
76<dd>
77 Return true if <var>p</var> is a dict object or an instance of a
78 subtype of the dict type.
79
80<span class="versionnote">Changed in version 2.2:
81Allowed subtypes to be accepted.</span>
82
83</dd></dl>
84
85<P>
86<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>
87<dd>
88 Return true if <var>p</var> is a dict object, but not an instance of a
89 subtype of the dict type.
90
91<span class="versionnote">New in version 2.4.</span>
92
93</dd></dl>
94
95<P>
96<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>
97<dd>
98<div class="refcount-info">
99 <span class="label">Return value:</span>
100 <span class="value">New reference.</span>
101</div>
102 Return a new empty dictionary, or <tt class="constant">NULL</tt> on failure.
103</dd></dl>
104
105<P>
106<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>
107<dd>
108<div class="refcount-info">
109 <span class="label">Return value:</span>
110 <span class="value">New reference.</span>
111</div>
112 Return a proxy object for a mapping which enforces read-only
113 behavior. This is normally used to create a proxy to prevent
114 modification of the dictionary for non-dynamic class types.
115
116<span class="versionnote">New in version 2.2.</span>
117
118</dd></dl>
119
120<P>
121<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>
122<dd>
123 Empty an existing dictionary of all key-value pairs.
124</dd></dl>
125
126<P>
127<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>
128<dd>
129 Determine if dictionary <var>p</var> contains <var>key</var>. If an item
130 in <var>p</var> is matches <var>key</var>, return <code>1</code>, otherwise return
131 <code>0</code>. On error, return <code>-1</code>. This is equivalent to the
132 Python expression "<tt class="samp"><var>key</var> in <var>p</var></tt>".
133
134<span class="versionnote">New in version 2.4.</span>
135
136</dd></dl>
137
138<P>
139<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>
140<dd>
141<div class="refcount-info">
142 <span class="label">Return value:</span>
143 <span class="value">New reference.</span>
144</div>
145 Return a new dictionary that contains the same key-value pairs as
146 <var>p</var>.
147
148<span class="versionnote">New in version 1.6.</span>
149
150</dd></dl>
151
152<P>
153<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>,
154 PyObject *<var>val</var>)</td></tr></table></dt>
155<dd>
156 Insert <var>value</var> into the dictionary <var>p</var> with a key of
157 <var>key</var>. <var>key</var> must be hashable; if it isn't,
158 <tt class="exception">TypeError</tt> will be raised.
159 Return <code>0</code> on success or <code>-1</code> on failure.
160</dd></dl>
161
162<P>
163<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>,
164 char *<var>key</var>,
165 PyObject *<var>val</var>)</td></tr></table></dt>
166<dd>
167 Insert <var>value</var> into the dictionary <var>p</var> using <var>key</var> as a
168 key. <var>key</var> should be a <tt class="ctype">char*</tt>. The key object is created
169 using <code>PyString_FromString(<var>key</var>)</code>. Return <code>0</code> on
170 success or <code>-1</code> on failure.
171 <a id='l2h-630' xml:id='l2h-630'></a>
172</dd></dl>
173
174<P>
175<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>
176<dd>
177 Remove the entry in dictionary <var>p</var> with key <var>key</var>.
178 <var>key</var> must be hashable; if it isn't, <tt class="exception">TypeError</tt> is
179 raised. Return <code>0</code> on success or <code>-1</code> on failure.
180</dd></dl>
181
182<P>
183<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>
184<dd>
185 Remove the entry in dictionary <var>p</var> which has a key specified by
186 the string <var>key</var>. Return <code>0</code> on success or <code>-1</code> on
187 failure.
188</dd></dl>
189
190<P>
191<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>
192<dd>
193<div class="refcount-info">
194 <span class="label">Return value:</span>
195 <span class="value">Borrowed reference.</span>
196</div>
197 Return the object from dictionary <var>p</var> which has a key
198 <var>key</var>. Return <tt class="constant">NULL</tt> if the key <var>key</var> is not present, but
199 <em>without</em> setting an exception.
200</dd></dl>
201
202<P>
203<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>
204<dd>
205<div class="refcount-info">
206 <span class="label">Return value:</span>
207 <span class="value">Borrowed reference.</span>
208</div>
209 This is the same as <tt class="cfunction">PyDict_GetItem()</tt>, but <var>key</var> is
210 specified as a <tt class="ctype">char*</tt>, rather than a <tt class="ctype">PyObject*</tt>.
211</dd></dl>
212
213<P>
214<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>
215<dd>
216<div class="refcount-info">
217 <span class="label">Return value:</span>
218 <span class="value">New reference.</span>
219</div>
220 Return a <tt class="ctype">PyListObject</tt> containing all the items from the
221 dictionary, as in the dictionary method <tt class="method">items()</tt> (see the
222 <em class="citetitle"><a
223 href="../lib/lib.html"
224 title="Python Library Reference"
225 >Python Library Reference</a></em>).
226</dd></dl>
227
228<P>
229<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>
230<dd>
231<div class="refcount-info">
232 <span class="label">Return value:</span>
233 <span class="value">New reference.</span>
234</div>
235 Return a <tt class="ctype">PyListObject</tt> containing all the keys from the
236 dictionary, as in the dictionary method <tt class="method">keys()</tt> (see the
237 <em class="citetitle"><a
238 href="../lib/lib.html"
239 title="Python Library Reference"
240 >Python Library Reference</a></em>).
241</dd></dl>
242
243<P>
244<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>
245<dd>
246<div class="refcount-info">
247 <span class="label">Return value:</span>
248 <span class="value">New reference.</span>
249</div>
250 Return a <tt class="ctype">PyListObject</tt> containing all the values from the
251 dictionary <var>p</var>, as in the dictionary method <tt class="method">values()</tt>
252 (see the <em class="citetitle"><a
253 href="../lib/lib.html"
254 title="Python Library Reference"
255 >Python Library Reference</a></em>).
256</dd></dl>
257
258<P>
259<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>
260<dd>
261 Return the number of items in the dictionary. This is equivalent
262 to "<tt class="samp">len(<var>p</var>)</tt>" on a dictionary.<a id='l2h-625' xml:id='l2h-625'></a></dd></dl>
263
264<P>
265<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>,
266 PyObject **<var>pkey</var>, PyObject **<var>pvalue</var>)</td></tr></table></dt>
267<dd>
268 Iterate over all key-value pairs in the dictionary <var>p</var>. The
269 <tt class="ctype">int</tt> referred to by <var>ppos</var> must be initialized to
270 <code>0</code> prior to the first call to this function to start the
271 iteration; the function returns true for each pair in the
272 dictionary, and false once all pairs have been reported. The
273 parameters <var>pkey</var> and <var>pvalue</var> should either point to
274 <tt class="ctype">PyObject*</tt> variables that will be filled in with each key and
275 value, respectively, or may be <tt class="constant">NULL</tt>. Any references returned through
276 them are borrowed. <var>ppos</var> should not be altered during iteration.
277 Its value represents offsets within the internal dictionary structure,
278 and since the structure is sparse, the offsets are not consecutive.
279
280<P>
281For example:
282
283<P>
284<div class="verbatim"><pre>
285PyObject *key, *value;
286int pos = 0;
287
288while (PyDict_Next(self-&gt;dict, &amp;pos, &amp;key, &amp;value)) {
289 /* do something interesting with the values... */
290 ...
291}
292</pre></div>
293
294<P>
295The dictionary <var>p</var> should not be mutated during iteration. It
296 is safe (since Python 2.1) to modify the values of the keys as you
297 iterate over the dictionary, but only so long as the set of keys
298 does not change. For example:
299
300<P>
301<div class="verbatim"><pre>
302PyObject *key, *value;
303int pos = 0;
304
305while (PyDict_Next(self-&gt;dict, &amp;pos, &amp;key, &amp;value)) {
306 int i = PyInt_AS_LONG(value) + 1;
307 PyObject *o = PyInt_FromLong(i);
308 if (o == NULL)
309 return -1;
310 if (PyDict_SetItem(self-&gt;dict, key, o) &lt; 0) {
311 Py_DECREF(o);
312 return -1;
313 }
314 Py_DECREF(o);
315}
316</pre></div>
317</dd></dl>
318
319<P>
320<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>
321<dd>
322 Iterate over mapping object <var>b</var> adding key-value pairs to dictionary
323 <var>a</var>.
324 <var>b</var> may be a dictionary, or any object supporting
325 <tt class="function">PyMapping_Keys()</tt> and <tt class="function">PyObject_GetItem()</tt>.
326 If <var>override</var> is true, existing pairs in <var>a</var> will
327 be replaced if a matching key is found in <var>b</var>, otherwise pairs
328 will only be added if there is not a matching key in <var>a</var>.
329 Return <code>0</code> on success or <code>-1</code> if an exception was
330 raised.
331
332<span class="versionnote">New in version 2.2.</span>
333
334</dd></dl>
335
336<P>
337<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>
338<dd>
339 This is the same as <code>PyDict_Merge(<var>a</var>, <var>b</var>, 1)</code> in C,
340 or <code><var>a</var>.update(<var>b</var>)</code> in Python. Return <code>0</code> on
341 success or <code>-1</code> if an exception was raised.
342
343<span class="versionnote">New in version 2.2.</span>
344
345</dd></dl>
346
347<P>
348<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>,
349 int <var>override</var>)</td></tr></table></dt>
350<dd>
351 Update or merge into dictionary <var>a</var>, from the key-value pairs in
352 <var>seq2</var>. <var>seq2</var> must be an iterable object producing
353 iterable objects of length 2, viewed as key-value pairs. In case of
354 duplicate keys, the last wins if <var>override</var> is true, else the
355 first wins.
356 Return <code>0</code> on success or <code>-1</code> if an exception
357 was raised.
358 Equivalent Python (except for the return value):
359
360<P>
361<div class="verbatim"><pre>
362def PyDict_MergeFromSeq2(a, seq2, override):
363 for key, value in seq2:
364 if override or key not in a:
365 a[key] = value
366</pre></div>
367
368<P>
369
370<span class="versionnote">New in version 2.2.</span>
371
372</dd></dl>
373
374<P>
375
376<DIV CLASS="navigation">
377<div class='online-navigation'>
378<p></p><hr />
379<table align="center" width="100%" cellpadding="0" cellspacing="2">
380<tr>
381<td class='online-navigation'><a rel="prev" title="7.4 Mapping Objects"
382 href="mapObjects.html"><img src='../icons/previous.png'
383 border='0' height='32' alt='Previous Page' width='32' /></A></td>
384<td class='online-navigation'><a rel="parent" title="7.4 Mapping Objects"
385 href="mapObjects.html"><img src='../icons/up.png'
386 border='0' height='32' alt='Up One Level' width='32' /></A></td>
387<td class='online-navigation'><a rel="next" title="7.5 Other Objects"
388 href="otherObjects.html"><img src='../icons/next.png'
389 border='0' height='32' alt='Next Page' width='32' /></A></td>
390<td align="center" width="100%">Python/C API Reference Manual</td>
391<td class='online-navigation'><a rel="contents" title="Table of Contents"
392 href="contents.html"><img src='../icons/contents.png'
393 border='0' height='32' alt='Contents' width='32' /></A></td>
394<td class='online-navigation'><img src='../icons/blank.png'
395 border='0' height='32' alt='' width='32' /></td>
396<td class='online-navigation'><a rel="index" title="Index"
397 href="genindex.html"><img src='../icons/index.png'
398 border='0' height='32' alt='Index' width='32' /></A></td>
399</tr></table>
400<div class='online-navigation'>
401<b class="navlabel">Previous:</b>
402<a class="sectref" rel="prev" href="mapObjects.html">7.4 Mapping Objects</A>
403<b class="navlabel">Up:</b>
404<a class="sectref" rel="parent" href="mapObjects.html">7.4 Mapping Objects</A>
405<b class="navlabel">Next:</b>
406<a class="sectref" rel="next" href="otherObjects.html">7.5 Other Objects</A>
407</div>
408</div>
409<hr />
410<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
411</DIV>
412<!--End of Navigation Panel-->
413<ADDRESS>
414See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
415</ADDRESS>
416</BODY>
417</HTML>
Full OpenSPARC architecture tarball including simulator, hypervisor, and OBP.