<!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.gif" /> <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="set-example.html"> <LINK rel="prev" href="module-sets.html"> <LINK rel="parent" href="module-sets.html"> <LINK rel="next" href="set-example.html"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <meta name='aesop' content='information' /> <META name="description" content="Set Objects "> <META name="keywords" content="lib"> <META name="resource-type" content="document"> <META name="distribution" content="global"> <title>5.13.1 Set Objects </title> </head> <body> <DIV CLASS="navigation"> <div id='top-navigation-panel'> <table align="center" width="100%" cellpadding="0" cellspacing="2"> <tr> <td class='online-navigation'><a rel="prev" title="5.13 sets " href="module-sets.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="5.13 sets " href="module-sets.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="5.13.2 Example" href="set-example.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="module-sets.html">5.13 sets </A> <b class="navlabel">Up:</b> <a class="sectref" rel="parent" href="module-sets.html">5.13 sets </A> <b class="navlabel">Next:</b> <a class="sectref" rel="next" href="set-example.html">5.13.2 Example</A> </div> <hr /></div> </DIV> <!--End of Navigation Panel--> <H2><A NAME="SECTION0071310000000000000000"><!--x--></A><A NAME="set-objects"><!--z--></A> <BR> 5.13.1 Set Objects </H2> <P> Instances of <tt class="class">Set</tt> and <tt class="class">ImmutableSet</tt> both provide the following operations: <P> <table border align="center" style="border-collapse: collapse"> <thead> <tr class="tableheader"> <th align="center"><b>Operation</b> </th> <th align="center"><b>Equivalent</b> </th> <th align="left"><b>Result</b> </th> </tr> </thead> <tbody valign="baseline"> <tr><td align="center" valign="baseline"><code>len(<var>s</var>)</code></td> <td align="center"> </td> <td align="left">cardinality of set <var>s</var></td><P> <tr><td align="center" valign="baseline"><code><var>x</var> in <var>s</var></code></td> <td align="center"> </td> <td align="left">test <var>x</var> for membership in <var>s</var></td> <tr><td align="center" valign="baseline"><code><var>x</var> not in <var>s</var></code></td> <td align="center"> </td> <td align="left">test <var>x</var> for non-membership in <var>s</var></td> <tr><td align="center" valign="baseline"><code><var>s</var>.issubset(<var>t</var>)</code></td> <td align="center"><code><var>s</var> <= <var>t</var></code></td> <td align="left">test whether every element in <var>s</var> is in <var>t</var></td> <tr><td align="center" valign="baseline"><code><var>s</var>.issuperset(<var>t</var>)</code></td> <td align="center"><code><var>s</var> >= <var>t</var></code></td> <td align="left">test whether every element in <var>t</var> is in <var>s</var></td><P> <tr><td align="center" valign="baseline"><code><var>s</var>.union(<var>t</var>)</code></td> <td align="center"><var>s</var> | <var>t</var></td> <td align="left">new set with elements from both <var>s</var> and <var>t</var></td> <tr><td align="center" valign="baseline"><code><var>s</var>.intersection(<var>t</var>)</code></td> <td align="center"><var>s</var> & <var>t</var></td> <td align="left">new set with elements common to <var>s</var> and <var>t</var></td> <tr><td align="center" valign="baseline"><code><var>s</var>.difference(<var>t</var>)</code></td> <td align="center"><var>s</var> - <var>t</var></td> <td align="left">new set with elements in <var>s</var> but not in <var>t</var></td> <tr><td align="center" valign="baseline"><code><var>s</var>.symmetric_difference(<var>t</var>)</code></td> <td align="center"><var>s</var> ^ <var>t</var></td> <td align="left">new set with elements in either <var>s</var> or <var>t</var> but not both</td> <tr><td align="center" valign="baseline"><code><var>s</var>.copy()</code></td> <td align="center"> </td> <td align="left">new set with a shallow copy of <var>s</var></td></tbody> </table> <P> Note, the non-operator versions of <tt class="method">union()</tt>, <tt class="method">intersection()</tt>, <tt class="method">difference()</tt>, and <tt class="method">symmetric_difference()</tt> will accept any iterable as an argument. In contrast, their operator based counterparts require their arguments to be sets. This precludes error-prone constructions like <code>Set('abc') & 'cbs'</code> in favor of the more readable <code>Set('abc').intersection('cbs')</code>. <span class="versionnote">Changed in version 2.3.1: Formerly all arguments were required to be sets.</span> <P> In addition, both <tt class="class">Set</tt> and <tt class="class">ImmutableSet</tt> support set to set comparisons. Two sets are equal if and only if every element of each set is contained in the other (each is a subset of the other). A set is less than another set if and only if the first set is a proper subset of the second set (is a subset, but is not equal). A set is greater than another set if and only if the first set is a proper superset of the second set (is a superset, but is not equal). <P> The subset and equality comparisons do not generalize to a complete ordering function. For example, any two disjoint sets are not equal and are not subsets of each other, so <i>all</i> of the following return <code>False</code>: <code><var>a</var><<var>b</var></code>, <code><var>a</var>==<var>b</var></code>, or <code><var>a</var>><var>b</var></code>. Accordingly, sets do not implement the <tt class="method">__cmp__</tt> method. <P> Since sets only define partial ordering (subset relationships), the output of the <tt class="method">list.sort()</tt> method is undefined for lists of sets. <P> The following table lists operations available in <tt class="class">ImmutableSet</tt> but not found in <tt class="class">Set</tt>: <P> <table border align="center" style="border-collapse: collapse"> <thead> <tr class="tableheader"> <th align="center"><b>Operation</b> </th> <th align="left"><b>Result</b> </th> </tr> </thead> <tbody valign="baseline"> <tr><td align="center" valign="baseline"><code>hash(<var>s</var>)</code></td> <td align="left">returns a hash value for <var>s</var></td></tbody> </table> <P> The following table lists operations available in <tt class="class">Set</tt> but not found in <tt class="class">ImmutableSet</tt>: <P> <table border align="center" style="border-collapse: collapse"> <thead> <tr class="tableheader"> <th align="center"><b>Operation</b> </th> <th align="center"><b>Equivalent</b> </th> <th align="left"><b>Result</b> </th> </tr> </thead> <tbody valign="baseline"> <tr><td align="center" valign="baseline"><code><var>s</var>.union_update(<var>t</var>)</code></td> <td align="center"><var>s</var> |= <var>t</var></td> <td align="left">return set <var>s</var> with elements added from <var>t</var></td> <tr><td align="center" valign="baseline"><code><var>s</var>.intersection_update(<var>t</var>)</code></td> <td align="center"><var>s</var> &= <var>t</var></td> <td align="left">return set <var>s</var> keeping only elements also found in <var>t</var></td> <tr><td align="center" valign="baseline"><code><var>s</var>.difference_update(<var>t</var>)</code></td> <td align="center"><var>s</var> -= <var>t</var></td> <td align="left">return set <var>s</var> after removing elements found in <var>t</var></td> <tr><td align="center" valign="baseline"><code><var>s</var>.symmetric_difference_update(<var>t</var>)</code></td> <td align="center"><var>s</var> ^= <var>t</var></td> <td align="left">return set <var>s</var> with elements from <var>s</var> or <var>t</var> but not both</td><P> <tr><td align="center" valign="baseline"><code><var>s</var>.add(<var>x</var>)</code></td> <td align="center"> </td> <td align="left">add element <var>x</var> to set <var>s</var></td> <tr><td align="center" valign="baseline"><code><var>s</var>.remove(<var>x</var>)</code></td> <td align="center"> </td> <td align="left">remove <var>x</var> from set <var>s</var>; raises KeyError if not present</td> <tr><td align="center" valign="baseline"><code><var>s</var>.discard(<var>x</var>)</code></td> <td align="center"> </td> <td align="left">removes <var>x</var> from set <var>s</var> if present</td> <tr><td align="center" valign="baseline"><code><var>s</var>.pop()</code></td> <td align="center"> </td> <td align="left">remove and return an arbitrary element from <var>s</var>; raises KeyError if empty</td> <tr><td align="center" valign="baseline"><code><var>s</var>.clear()</code></td> <td align="center"> </td> <td align="left">remove all elements from set <var>s</var></td></tbody> </table> <P> Note, the non-operator versions of <tt class="method">union_update()</tt>, <tt class="method">intersection_update()</tt>, <tt class="method">difference_update()</tt>, and <tt class="method">symmetric_difference_update()</tt> will accept any iterable as an argument. <span class="versionnote">Changed in version 2.3.1: Formerly all arguments were required to be sets.</span> <P> <DIV CLASS="navigation"> <div class='online-navigation'><hr /> <table align="center" width="100%" cellpadding="0" cellspacing="2"> <tr> <td class='online-navigation'><a rel="prev" title="5.13 sets " rel="prev" title="5.13 sets " href="module-sets.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="5.13 sets " rel="parent" title="5.13 sets " href="module-sets.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="5.13.2 Example" rel="next" title="5.13.2 Example" href="set-example.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" 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" 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="module-sets.html">5.13 sets </A> <b class="navlabel">Up:</b> <a class="sectref" rel="parent" href="module-sets.html">5.13 sets </A> <b class="navlabel">Next:</b> <a class="sectref" rel="next" href="set-example.html">5.13.2 Example</A> </div> </div> <hr /> <span class="release-info">Release 2.3.4, documentation updated on May 20, 2004.</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>