sam-t2/devtools/v8plus/html/python/lib/typesmapping.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.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="lib.html" title='Python Library Reference' />
<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="next" href="bltin-file-objects.html" />
<link rel="prev" href="types-set.html" />
<link rel="parent" href="types.html" />
<link rel="next" href="bltin-file-objects.html" />
<meta name='aesop' content='information' />
<title>2.3.8 Mapping Types -- classdict </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="2.3.7 Set Types "
  href="types-set.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="2.3 Built-in Types"
  href="types.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="2.3.9 File Objects"
  href="bltin-file-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</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'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></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="types-set.html">2.3.7 Set Types </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="types.html">2.3 Built-in Types</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="bltin-file-objects.html">2.3.9 File Objects</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION004380000000000000000"></A><A NAME="typesmapping"></A>
<BR>
2.3.8 Mapping Types -- classdict
</H2>
<a id='l2h-227' xml:id='l2h-227'></a><a id='l2h-228' xml:id='l2h-228'></a>
<P>
A <i class="dfn">mapping</i> object maps  immutable values to
arbitrary objects.  Mappings are mutable objects.  There is currently
only one standard mapping type, the <i class="dfn">dictionary</i>.  A dictionary's keys are
almost arbitrary values.  Only values containing lists, dictionaries
or other mutable types (that are compared by value rather than by
object identity) may not be used as keys.
Numeric types used for keys obey the normal rules for numeric
comparison: if two numbers compare equal (such as <code>1</code> and
<code>1.0</code>) then they can be used interchangeably to index the same
dictionary entry.

<P>
Dictionaries are created by placing a comma-separated list of
<code><var>key</var>: <var>value</var></code> pairs within braces, for example:
<code>{'jack': 4098, 'sjoerd': 4127}</code> or
<code>{4098: 'jack', 4127: 'sjoerd'}</code>.

<P>
The following operations are defined on mappings (where <var>a</var> and
<var>b</var> are mappings, <var>k</var> is a key, and <var>v</var> and <var>x</var> are
arbitrary objects):
<a id='l2h-229' xml:id='l2h-229'></a><a id='l2h-230' xml:id='l2h-230'></a><a id='l2h-231' xml:id='l2h-231'></a><a id='l2h-232' xml:id='l2h-232'></a><a id='l2h-234' xml:id='l2h-234'></a>
<P>
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="center">Operation</th>
      <th class="left"  >Result</th>
      <th class="center">Notes</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="center" valign="baseline"><code>len(<var>a</var>)</code></td>
        <td class="left"  >the number of items in <var>a</var></td>
        <td class="center"></td></tr>
    <tr><td class="center" valign="baseline"><code><var>a</var>[<var>k</var>]</code></td>
        <td class="left"  >the item of <var>a</var> with key <var>k</var></td>
        <td class="center">(1)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>a</var>[<var>k</var>] = <var>v</var></code></td>
        <td class="left"  >set <code><var>a</var>[<var>k</var>]</code> to <var>v</var></td>
        <td class="center"></td></tr>
    <tr><td class="center" valign="baseline"><code>del <var>a</var>[<var>k</var>]</code></td>
        <td class="left"  >remove <code><var>a</var>[<var>k</var>]</code> from <var>a</var></td>
        <td class="center">(1)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>a</var>.clear()</code></td>
        <td class="left"  >remove all items from <code>a</code></td>
        <td class="center"></td></tr>
    <tr><td class="center" valign="baseline"><code><var>a</var>.copy()</code></td>
        <td class="left"  >a (shallow) copy of <code>a</code></td>
        <td class="center"></td></tr>
    <tr><td class="center" valign="baseline"><code><var>a</var>.has_key(<var>k</var>)</code></td>
        <td class="left"  ><code>True</code> if <var>a</var> has a key <var>k</var>, else <code>False</code></td>
        <td class="center"></td></tr>
    <tr><td class="center" valign="baseline"><code><var>k</var> <code>in</code> <var>a</var></code></td>
        <td class="left"  >Equivalent to <var>a</var>.has_key(<var>k</var>)</td>
        <td class="center">(2)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>k</var> not in <var>a</var></code></td>
        <td class="left"  >Equivalent to <code>not</code> <var>a</var>.has_key(<var>k</var>)</td>
        <td class="center">(2)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>a</var>.items()</code></td>
        <td class="left"  >a copy of <var>a</var>'s list of (<var>key</var>, <var>value</var>) pairs</td>
        <td class="center">(3)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>a</var>.keys()</code></td>
        <td class="left"  >a copy of <var>a</var>'s list of keys</td>
        <td class="center">(3)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>a</var>.update(<big>[</big><var>b</var><big>]</big>)</code></td>
        <td class="left"  >updates (and overwrites) key/value pairs from <var>b</var></td>
        <td class="center">(9)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>a</var>.fromkeys(<var>seq</var><big>[</big>, <var>value</var><big>]</big>)</code></td>
        <td class="left"  >Creates a new dictionary with keys from <var>seq</var> and values set to <var>value</var></td>
        <td class="center">(7)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>a</var>.values()</code></td>
        <td class="left"  >a copy of <var>a</var>'s list of values</td>
        <td class="center">(3)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>a</var>.get(<var>k</var><big>[</big>, <var>x</var><big>]</big>)</code></td>
        <td class="left"  ><code><var>a</var>[<var>k</var>]</code> if <code><var>k</var> in <var>a</var></code>,
           else <var>x</var></td>
        <td class="center">(4)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>a</var>.setdefault(<var>k</var><big>[</big>, <var>x</var><big>]</big>)</code></td>
        <td class="left"  ><code><var>a</var>[<var>k</var>]</code> if <code><var>k</var> in <var>a</var></code>,
           else <var>x</var> (also setting it)</td>
        <td class="center">(5)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>a</var>.pop(<var>k</var><big>[</big>, <var>x</var><big>]</big>)</code></td>
        <td class="left"  ><code><var>a</var>[<var>k</var>]</code> if <code><var>k</var> in <var>a</var></code>,
           else <var>x</var> (and remove k)</td>
        <td class="center">(8)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>a</var>.popitem()</code></td>
        <td class="left"  >remove and return an arbitrary (<var>key</var>, <var>value</var>) pair</td>
        <td class="center">(6)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>a</var>.iteritems()</code></td>
        <td class="left"  >return an iterator over (<var>key</var>, <var>value</var>) pairs</td>
        <td class="center">(2), (3)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>a</var>.iterkeys()</code></td>
        <td class="left"  >return an iterator over the mapping's keys</td>
        <td class="center">(2), (3)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>a</var>.itervalues()</code></td>
        <td class="left"  >return an iterator over the mapping's values</td>
        <td class="center">(2), (3)</td></tr></tbody>
</table></div>

<P>
Notes:
<DL>
<DT><STRONG>(1)</STRONG></DT>
<DD>Raises a <tt class="exception">KeyError</tt> exception if <var>k</var> is not
in the map.

<P>
</DD>
<DT><STRONG>(2)</STRONG></DT>
<DD>
<span class="versionnote">New in version 2.2.</span>

<P>
</DD>
<DT><STRONG>(3)</STRONG></DT>
<DD>Keys and values are listed in an arbitrary order which is
non-random, varies across Python implementations, and depends on the
dictionary's history of insertions and deletions.
If <tt class="method">items()</tt>, <tt class="method">keys()</tt>, <tt class="method">values()</tt>,
<tt class="method">iteritems()</tt>, <tt class="method">iterkeys()</tt>, and <tt class="method">itervalues()</tt>
are called with no intervening modifications to the dictionary, the
lists will directly correspond.  This allows the creation of
<code>(<var>value</var>, <var>key</var>)</code> pairs using <tt class="function">zip()</tt>:
"<tt class="samp">pairs = zip(<var>a</var>.values(), <var>a</var>.keys())</tt>".  The same
relationship holds for the <tt class="method">iterkeys()</tt> and
<tt class="method">itervalues()</tt> methods: "<tt class="samp">pairs = zip(<var>a</var>.itervalues(),
<var>a</var>.iterkeys())</tt>" provides the same value for <code>pairs</code>.
Another way to create the same list is "<tt class="samp">pairs = [(v, k) for (k,
v) in <var>a</var>.iteritems()]</tt>".

<P>
</DD>
<DT><STRONG>(4)</STRONG></DT>
<DD>Never raises an exception if <var>k</var> is not in the map,
instead it returns <var>x</var>.  <var>x</var> is optional; when <var>x</var> is not
provided and <var>k</var> is not in the map, <code>None</code> is returned.

<P>
</DD>
<DT><STRONG>(5)</STRONG></DT>
<DD><tt class="function">setdefault()</tt> is like <tt class="function">get()</tt>, except
that if <var>k</var> is missing, <var>x</var> is both returned and inserted into
the dictionary as the value of <var>k</var>. <var>x</var> defaults to <var>None</var>.

<P>
</DD>
<DT><STRONG>(6)</STRONG></DT>
<DD><tt class="function">popitem()</tt> is useful to destructively iterate
over a dictionary, as often used in set algorithms.  If the dictionary
is empty, calling <tt class="function">popitem()</tt> raises a <tt class="exception">KeyError</tt>.

<P>
</DD>
<DT><STRONG>(7)</STRONG></DT>
<DD><tt class="function">fromkeys()</tt> is a class method that returns a
new dictionary. <var>value</var> defaults to <code>None</code>.
<span class="versionnote">New in version 2.3.</span>

<P>
</DD>
<DT><STRONG>(8)</STRONG></DT>
<DD><tt class="function">pop()</tt> raises a <tt class="exception">KeyError</tt> when no default
value is given and the key is not found.
<span class="versionnote">New in version 2.3.</span>

<P>
</DD>
<DT><STRONG>(9)</STRONG></DT>
<DD><tt class="function">update()</tt> accepts either another mapping object
or an iterable of key/value pairs (as a tuple or other iterable of
length two).  If keyword arguments are specified, the mapping is
then is updated with those key/value pairs:
"<tt class="samp">d.update(red=1, blue=2)</tt>".

<span class="versionnote">Changed in version 2.4:
Allowed the argument to be an iterable of key/value
                pairs and allowed keyword arguments.</span>

<P>
</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="2.3.7 Set Types "
  href="types-set.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="2.3 Built-in Types"
  href="types.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="2.3.9 File Objects"
  href="bltin-file-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</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'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></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="types-set.html">2.3.7 Set Types </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="types.html">2.3 Built-in Types</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="bltin-file-objects.html">2.3.9 File 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>