<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<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=
"typesmapping.html" />
<link rel=
"prev" href=
"typesseq.html" />
<link rel=
"parent" href=
"types.html" />
<link rel=
"next" href=
"typesmapping.html" />
<meta name='aesop' content='information'
/>
<title>2.3.7 Set Types -- set, frozenset
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"2.3.6.4 Mutable Sequence Types"
href=
"typesseq-mutable.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.8 Mapping Types "
href=
"typesmapping.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>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"typesseq-mutable.html">2.3.6.4 Mutable Sequence 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=
"typesmapping.html">2.3.8 Mapping Types
</A>
<!--End of Navigation Panel-->
<H2><A NAME=
"SECTION004370000000000000000"></A><A NAME=
"types-set"></A>
<tt class=
"class">set
</tt>,
<tt class=
"class">frozenset
</tt>
<a id='l2h-
226' xml:id='l2h-
226'
></a>
A
<i class=
"dfn">set
</i> object is an unordered collection of immutable values.
Common uses include membership testing, removing duplicates from a sequence,
and computing mathematical operations such as intersection, union, difference,
and symmetric difference.
<span class=
"versionnote">New in version
2.4.
</span>
Like other collections, sets support
<code><var>x
</var> in
<var>set
</var></code>,
<code>len(
<var>set
</var>)
</code>, and
<code>for
<var>x
</var> in
<var>set
</var></code>. Being an
unordered collection, sets do not record element position or order of
insertion. Accordingly, sets do not support indexing, slicing, or
other sequence-like behavior.
There are currently two builtin set types,
<tt class=
"class">set
</tt> and
<tt class=
"class">frozenset
</tt>.
The
<tt class=
"class">set
</tt> type is mutable -- the contents can be changed using methods
like
<tt class=
"method">add()
</tt> and
<tt class=
"method">remove()
</tt>. Since it is mutable, it has no
hash value and cannot be used as either a dictionary key or as an element of
another set. The
<tt class=
"class">frozenset
</tt> type is immutable and hashable -- its
contents cannot be altered after is created; however, it can be used as
a dictionary key or as an element of another set.
Instances of
<tt class=
"class">set
</tt> and
<tt class=
"class">frozenset
</tt> provide the following operations:
<div class=
"center"><table class=
"realtable">
<th class=
"center">Operation
</th>
<th class=
"center">Equivalent
</th>
<th class=
"left" >Result
</th>
<tr><td class=
"center" valign=
"baseline"><code>len(
<var>s
</var>)
</code></td>
<td class=
"left" >cardinality of set
<var>s
</var></td></tr><P>
<tr><td class=
"center" valign=
"baseline"><code><var>x
</var> in
<var>s
</var></code></td>
<td class=
"left" >test
<var>x
</var> for membership in
<var>s
</var></td></tr>
<tr><td class=
"center" valign=
"baseline"><code><var>x
</var> not in
<var>s
</var></code></td>
<td class=
"left" >test
<var>x
</var> for non-membership in
<var>s
</var></td></tr>
<tr><td class=
"center" valign=
"baseline"><code><var>s
</var>.issubset(
<var>t
</var>)
</code></td>
<td class=
"center"><code><var>s
</var> <=
<var>t
</var></code></td>
<td class=
"left" >test whether every element in
<var>s
</var> is in
<var>t
</var></td></tr>
<tr><td class=
"center" valign=
"baseline"><code><var>s
</var>.issuperset(
<var>t
</var>)
</code></td>
<td class=
"center"><code><var>s
</var> >=
<var>t
</var></code></td>
<td class=
"left" >test whether every element in
<var>t
</var> is in
<var>s
</var></td></tr><P>
<tr><td class=
"center" valign=
"baseline"><code><var>s
</var>.union(
<var>t
</var>)
</code></td>
<td class=
"center"><var>s
</var> |
<var>t
</var></td>
<td class=
"left" >new set with elements from both
<var>s
</var> and
<var>t
</var></td></tr>
<tr><td class=
"center" valign=
"baseline"><code><var>s
</var>.intersection(
<var>t
</var>)
</code></td>
<td class=
"center"><var>s
</var> & <var>t
</var></td>
<td class=
"left" >new set with elements common to
<var>s
</var> and
<var>t
</var></td></tr>
<tr><td class=
"center" valign=
"baseline"><code><var>s
</var>.difference(
<var>t
</var>)
</code></td>
<td class=
"center"><var>s
</var> -
<var>t
</var></td>
<td class=
"left" >new set with elements in
<var>s
</var> but not in
<var>t
</var></td></tr>
<tr><td class=
"center" valign=
"baseline"><code><var>s
</var>.symmetric_difference(
<var>t
</var>)
</code></td>
<td class=
"center"><var>s
</var> ^
<var>t
</var></td>
<td class=
"left" >new set with elements in either
<var>s
</var> or
<var>t
</var> but not both
</td></tr>
<tr><td class=
"center" valign=
"baseline"><code><var>s
</var>.copy()
</code></td>
<td class=
"left" >new set with a shallow copy of
<var>s
</var></td></tr></tbody>
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>,
<tt class=
"method">issubset()
</tt>, and
<tt class=
"method">issuperset()
</tt> methods 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>.
Both
<tt class=
"class">set
</tt> and
<tt class=
"class">frozenset
</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).
Instances of
<tt class=
"class">set
</tt> are compared to instances of
<tt class=
"class">frozenset
</tt> based
on their members. For example,
"<tt class="samp
">set('abc') == frozenset('abc')</tt>" returns
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
<em>all
</em> 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.
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.
Set elements are like dictionary keys; they need to define both
<tt class=
"method">__hash__
</tt> and
<tt class=
"method">__eq__
</tt> methods.
Binary operations that mix
<tt class=
"class">set
</tt> instances with
<tt class=
"class">frozenset
</tt>
return the type of the first operand. For example:
"<tt class="samp
">frozenset('ab') | set('bc')</tt>" returns an instance of
<tt class=
"class">frozenset
</tt>.
The following table lists operations available for
<tt class=
"class">set
</tt>
that do not apply to immutable instances of
<tt class=
"class">frozenset
</tt>:
<div class=
"center"><table class=
"realtable">
<th class=
"center">Operation
</th>
<th class=
"center">Equivalent
</th>
<th class=
"left" >Result
</th>
<tr><td class=
"center" valign=
"baseline"><code><var>s
</var>.update(
<var>t
</var>)
</code></td>
<td class=
"center"><var>s
</var> |=
<var>t
</var></td>
<td class=
"left" >return set
<var>s
</var> with elements added from
<var>t
</var></td></tr>
<tr><td class=
"center" valign=
"baseline"><code><var>s
</var>.intersection_update(
<var>t
</var>)
</code></td>
<td class=
"center"><var>s
</var> &=
<var>t
</var></td>
<td class=
"left" >return set
<var>s
</var> keeping only elements also found in
<var>t
</var></td></tr>
<tr><td class=
"center" valign=
"baseline"><code><var>s
</var>.difference_update(
<var>t
</var>)
</code></td>
<td class=
"center"><var>s
</var> -=
<var>t
</var></td>
<td class=
"left" >return set
<var>s
</var> after removing elements found in
<var>t
</var></td></tr>
<tr><td class=
"center" valign=
"baseline"><code><var>s
</var>.symmetric_difference_update(
<var>t
</var>)
</code></td>
<td class=
"center"><var>s
</var> ^=
<var>t
</var></td>
<td class=
"left" >return set
<var>s
</var> with elements from
<var>s
</var> or
<var>t
</var>
but not both
</td></tr><P>
<tr><td class=
"center" valign=
"baseline"><code><var>s
</var>.add(
<var>x
</var>)
</code></td>
<td class=
"left" >add element
<var>x
</var> to set
<var>s
</var></td></tr>
<tr><td class=
"center" valign=
"baseline"><code><var>s
</var>.remove(
<var>x
</var>)
</code></td>
<td class=
"left" >remove
<var>x
</var> from set
<var>s
</var>; raises KeyError if not present
</td></tr>
<tr><td class=
"center" valign=
"baseline"><code><var>s
</var>.discard(
<var>x
</var>)
</code></td>
<td class=
"left" >removes
<var>x
</var> from set
<var>s
</var> if present
</td></tr>
<tr><td class=
"center" valign=
"baseline"><code><var>s
</var>.pop()
</code></td>
<td class=
"left" >remove and return an arbitrary element from
<var>s
</var>; raises
<tt class=
"exception">KeyError
</tt> if empty
</td></tr>
<tr><td class=
"center" valign=
"baseline"><code><var>s
</var>.clear()
</code></td>
<td class=
"left" >remove all elements from set
<var>s
</var></td></tr></tbody>
Note, the non-operator versions of the
<tt class=
"method">update()
</tt>,
<tt class=
"method">intersection_update()
</tt>,
<tt class=
"method">difference_update()
</tt>, and
<tt class=
"method">symmetric_difference_update()
</tt> methods will accept any iterable
The design of the set types was based on lessons learned from the
<tt class=
"module">sets
</tt> module.
<p class=
"heading">See Also:
</p>
<dl compact=
"compact" class=
"seemodule">
<dt>Module
<b><tt class=
"module"><a href=
"module-comparison-to-builtin-set.html">sets
</a></tt>:
</b>
the
<tt class=
"module">sets
</tt> module and the built-in set types.
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"2.3.6.4 Mutable Sequence Types"
href=
"typesseq-mutable.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.8 Mapping Types "
href=
"typesmapping.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>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"typesseq-mutable.html">2.3.6.4 Mutable Sequence 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=
"typesmapping.html">2.3.8 Mapping Types
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.