Mercurial > cpython-lru_cache-weakref
annotate Doc/lib/libsets.tex @ 28646:193b8aec00ce legacy-trunk
Changes from Jonathan Riehl to allow his pgen extension (PEP 269) to
work. This includes some more code that used to be part of pgen in
the main parser; I'm okay with that. I'll see if the Windows build
needs work next.
| author | Guido van Rossum <guido@python.org> |
|---|---|
| date | Thu, 17 Apr 2003 14:55:42 +0000 |
| parents | cedf9efa68f8 |
| children | 60aae8a1e237 a332dcc7902b |
| rev | line source |
|---|---|
| 24980 | 1 \section{\module{sets} --- |
| 2 Unordered collections of unique elements} | |
| 3 | |
| 4 \declaremodule{standard}{sets} | |
| 5 \modulesynopsis{Implementation of sets of unique elements.} | |
| 6 \moduleauthor{Greg V. Wilson}{gvwilson@nevex.com} | |
| 7 \moduleauthor{Alex Martelli}{aleax@aleax.it} | |
| 8 \moduleauthor{Guido van Rossum}{guido@python.org} | |
| 9 \sectionauthor{Raymond D. Hettinger}{python@rcn.com} | |
| 10 | |
| 11 \versionadded{2.3} | |
| 12 | |
| 13 The \module{sets} module provides classes for constructing and manipulating | |
| 14 unordered collections of unique elements. Common uses include membership | |
| 15 testing, removing duplicates from a sequence, and computing standard math | |
| 16 operations on sets such as intersection, union, difference, and symmetric | |
| 17 difference. | |
| 18 | |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
19 Like other collections, sets support \code{\var{x} in \var{set}}, |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
20 \code{len(\var{set})}, and \code{for \var{x} in \var{set}}. Being an |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
21 unordered collection, sets do not record element position or order of |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
22 insertion. Accordingly, sets do not support indexing, slicing, or |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
23 other sequence-like behavior. |
| 24980 | 24 |
| 25 Most set applications use the \class{Set} class which provides every set | |
| 26 method except for \method{__hash__()}. For advanced applications requiring | |
| 27 a hash method, the \class{ImmutableSet} class adds a \method{__hash__()} | |
| 28 method but omits methods which alter the contents of the set. Both | |
| 29 \class{Set} and \class{ImmutableSet} derive from \class{BaseSet}, an | |
| 30 abstract class useful for determining whether something is a set: | |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
31 \code{isinstance(\var{obj}, BaseSet)}. |
| 24980 | 32 |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
33 The set classes are implemented using dictionaries. As a result, sets |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
34 cannot contain mutable elements such as lists or dictionaries. |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
35 However, they can contain immutable collections such as tuples or |
|
25002
0b726496cf44
Fix markup and punctuation
Raymond Hettinger <python@rcn.com>
parents:
25000
diff
changeset
|
36 instances of \class{ImmutableSet}. For convenience in implementing |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
37 sets of sets, inner sets are automatically converted to immutable |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
38 form, for example, \code{Set([Set(['dog'])])} is transformed to |
| 24980 | 39 \code{Set([ImmutableSet(['dog'])])}. |
| 40 | |
| 41 \begin{classdesc}{Set}{\optional{iterable}} | |
| 42 Constructs a new empty \class{Set} object. If the optional \var{iterable} | |
| 43 parameter is supplied, updates the set with elements obtained from iteration. | |
| 44 All of the elements in \var{iterable} should be immutable or be transformable | |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
45 to an immutable using the protocol described in |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
46 section~\ref{immutable-transforms}. |
| 24980 | 47 \end{classdesc} |
| 48 | |
| 49 \begin{classdesc}{ImmutableSet}{\optional{iterable}} | |
| 50 Constructs a new empty \class{ImmutableSet} object. If the optional | |
| 51 \var{iterable} parameter is supplied, updates the set with elements obtained | |
| 52 from iteration. All of the elements in \var{iterable} should be immutable or | |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
53 be transformable to an immutable using the protocol described in |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
54 section~\ref{immutable-transforms}. |
| 24980 | 55 |
| 56 Because \class{ImmutableSet} objects provide a \method{__hash__()} method, | |
| 57 they can be used as set elements or as dictionary keys. \class{ImmutableSet} | |
| 58 objects do not have methods for adding or removing elements, so all of the | |
| 59 elements must be known when the constructor is called. | |
| 60 \end{classdesc} | |
| 61 | |
| 62 | |
|
27111
0364aae5a5a4
Fix some nits Guido brought up last August:
Fred Drake <fdrake@acm.org>
parents:
25031
diff
changeset
|
63 \subsection{Set Objects \label{set-objects}} |
| 24980 | 64 |
| 65 Instances of \class{Set} and \class{ImmutableSet} both provide | |
| 66 the following operations: | |
| 67 | |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
68 \begin{tableii}{c|l}{code}{Operation}{Result} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
69 \lineii{len(\var{s})}{cardinality of set \var{s}} |
| 24980 | 70 |
| 71 \hline | |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
72 \lineii{\var{x} in \var{s}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
73 {test \var{x} for membership in \var{s}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
74 \lineii{\var{x} not in \var{s}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
75 {test \var{x} for non-membership in \var{s}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
76 \lineii{\var{s}.issubset(\var{t})} |
|
25031
40e9cfde1c50
Implemented <, <=, >, >= for sets, giving subset and proper-subset
Tim Peters <tim.peters@gmail.com>
parents:
25018
diff
changeset
|
77 {test whether every element in \var{s} is in \var{t}; |
|
40e9cfde1c50
Implemented <, <=, >, >= for sets, giving subset and proper-subset
Tim Peters <tim.peters@gmail.com>
parents:
25018
diff
changeset
|
78 \code{\var{s} <= \var{t}} is equivalent} |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
79 \lineii{\var{s}.issuperset(\var{t})} |
|
25031
40e9cfde1c50
Implemented <, <=, >, >= for sets, giving subset and proper-subset
Tim Peters <tim.peters@gmail.com>
parents:
25018
diff
changeset
|
80 {test whether every element in \var{t} is in \var{s}; |
|
40e9cfde1c50
Implemented <, <=, >, >= for sets, giving subset and proper-subset
Tim Peters <tim.peters@gmail.com>
parents:
25018
diff
changeset
|
81 \code{\var{s} >= \var{t}} is equivalent} |
| 24980 | 82 |
| 83 \hline | |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
84 \lineii{\var{s} | \var{t}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
85 {new set with elements from both \var{s} and \var{t}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
86 \lineii{\var{s}.union(\var{t})} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
87 {new set with elements from both \var{s} and \var{t}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
88 \lineii{\var{s} \&\ \var{t}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
89 {new set with elements common to \var{s} and \var{t}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
90 \lineii{\var{s}.intersection(\var{t})} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
91 {new set with elements common to \var{s} and \var{t}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
92 \lineii{\var{s} - \var{t}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
93 {new set with elements in \var{s} but not in \var{t}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
94 \lineii{\var{s}.difference(\var{t})} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
95 {new set with elements in \var{s} but not in \var{t}} |
|
27886
206c5e3b5be7
SF bug #663701. The caret wasn't printing well in the PDF documentation.
Raymond Hettinger <python@rcn.com>
parents:
27252
diff
changeset
|
96 \lineii{\var{s} \^\ \var{t}} |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
97 {new set with elements in either \var{s} or \var{t} but not both} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
98 \lineii{\var{s}.symmetric_difference(\var{t})} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
99 {new set with elements in either \var{s} or \var{t} but not both} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
100 \lineii{\var{s}.copy()} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
101 {new set with a shallow copy of \var{s}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
102 \end{tableii} |
| 24980 | 103 |
|
25031
40e9cfde1c50
Implemented <, <=, >, >= for sets, giving subset and proper-subset
Tim Peters <tim.peters@gmail.com>
parents:
25018
diff
changeset
|
104 In addition, both \class{Set} and \class{ImmutableSet} |
|
40e9cfde1c50
Implemented <, <=, >, >= for sets, giving subset and proper-subset
Tim Peters <tim.peters@gmail.com>
parents:
25018
diff
changeset
|
105 support set to set comparisons. Two sets are equal if and only if |
|
40e9cfde1c50
Implemented <, <=, >, >= for sets, giving subset and proper-subset
Tim Peters <tim.peters@gmail.com>
parents:
25018
diff
changeset
|
106 every element of each set is contained in the other (each is a subset |
|
40e9cfde1c50
Implemented <, <=, >, >= for sets, giving subset and proper-subset
Tim Peters <tim.peters@gmail.com>
parents:
25018
diff
changeset
|
107 of the other). |
|
40e9cfde1c50
Implemented <, <=, >, >= for sets, giving subset and proper-subset
Tim Peters <tim.peters@gmail.com>
parents:
25018
diff
changeset
|
108 A set is less than another set if and only if the first set is a proper |
|
40e9cfde1c50
Implemented <, <=, >, >= for sets, giving subset and proper-subset
Tim Peters <tim.peters@gmail.com>
parents:
25018
diff
changeset
|
109 subset of the second set (is a subset, but is not equal). |
|
40e9cfde1c50
Implemented <, <=, >, >= for sets, giving subset and proper-subset
Tim Peters <tim.peters@gmail.com>
parents:
25018
diff
changeset
|
110 A set is greater than another set if and only if the first set is a proper |
|
40e9cfde1c50
Implemented <, <=, >, >= for sets, giving subset and proper-subset
Tim Peters <tim.peters@gmail.com>
parents:
25018
diff
changeset
|
111 superset of the second set (is a superset, but is not equal). |
| 24980 | 112 |
|
27252
40cd74782600
Document that __cmp__() is not defined for sets.
Raymond Hettinger <python@rcn.com>
parents:
27111
diff
changeset
|
113 The subset and equality comparisons do not generalize to a complete |
|
40cd74782600
Document that __cmp__() is not defined for sets.
Raymond Hettinger <python@rcn.com>
parents:
27111
diff
changeset
|
114 ordering function. For example, any two disjoint sets are not equal and |
|
40cd74782600
Document that __cmp__() is not defined for sets.
Raymond Hettinger <python@rcn.com>
parents:
27111
diff
changeset
|
115 are not subsets of each other, so \emph{none} of the following are true: |
|
40cd74782600
Document that __cmp__() is not defined for sets.
Raymond Hettinger <python@rcn.com>
parents:
27111
diff
changeset
|
116 \code{\var{a}<\var{b}}, \code{\var{a}==\var{b}}, or \code{\var{a}>\var{b}}. |
|
40cd74782600
Document that __cmp__() is not defined for sets.
Raymond Hettinger <python@rcn.com>
parents:
27111
diff
changeset
|
117 Accordingly, sets do not implement the \method{__cmp__} method. |
|
40cd74782600
Document that __cmp__() is not defined for sets.
Raymond Hettinger <python@rcn.com>
parents:
27111
diff
changeset
|
118 |
|
40cd74782600
Document that __cmp__() is not defined for sets.
Raymond Hettinger <python@rcn.com>
parents:
27111
diff
changeset
|
119 Since sets only define partial ordering (subset relationships), the output |
|
40cd74782600
Document that __cmp__() is not defined for sets.
Raymond Hettinger <python@rcn.com>
parents:
27111
diff
changeset
|
120 of the \method{list.sort()} method is undefined for lists of sets. |
|
40cd74782600
Document that __cmp__() is not defined for sets.
Raymond Hettinger <python@rcn.com>
parents:
27111
diff
changeset
|
121 |
| 24980 | 122 The following table lists operations available in \class{ImmutableSet} |
| 123 but not found in \class{Set}: | |
| 124 | |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
125 \begin{tableii}{c|l|c}{code}{Operation}{Result} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
126 \lineii{hash(\var{s})}{returns a hash value for \var{s}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
127 \end{tableii} |
| 24980 | 128 |
| 129 The following table lists operations available in \class{Set} | |
| 130 but not found in \class{ImmutableSet}: | |
| 131 | |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
132 \begin{tableii}{c|l}{code}{Operation}{Result} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
133 \lineii{\var{s} |= \var{t}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
134 {return set \var{s} with elements added from \var{t}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
135 \lineii{\var{s}.union_update(\var{t})} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
136 {return set \var{s} with elements added from \var{t}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
137 \lineii{\var{s} \&= \var{t}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
138 {return set \var{s} keeping only elements also found in \var{t}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
139 \lineii{\var{s}.intersection_update(\var{t})} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
140 {return set \var{s} keeping only elements also found in \var{t}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
141 \lineii{\var{s} -= \var{t}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
142 {return set \var{s} after removing elements found in \var{t}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
143 \lineii{\var{s}.difference_update(\var{t})} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
144 {return set \var{s} after removing elements found in \var{t}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
145 \lineii{\var{s} \textasciicircum= \var{t}} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
146 {return set \var{s} with elements from \var{s} or \var{t} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
147 but not both} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
148 \lineii{\var{s}.symmetric_difference_update(\var{t})} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
149 {return set \var{s} with elements from \var{s} or \var{t} |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
150 but not both} |
| 24980 | 151 |
| 152 \hline | |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
153 \lineii{\var{s}.add(\var{x})} |
|
27111
0364aae5a5a4
Fix some nits Guido brought up last August:
Fred Drake <fdrake@acm.org>
parents:
25031
diff
changeset
|
154 {add element \var{x} to set \var{s}} |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
155 \lineii{\var{s}.remove(\var{x})} |
|
27111
0364aae5a5a4
Fix some nits Guido brought up last August:
Fred Drake <fdrake@acm.org>
parents:
25031
diff
changeset
|
156 {remove \var{x} from set \var{s}} |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
157 \lineii{\var{s}.discard(\var{x})} |
|
27111
0364aae5a5a4
Fix some nits Guido brought up last August:
Fred Drake <fdrake@acm.org>
parents:
25031
diff
changeset
|
158 {removes \var{x} from set \var{s} if present} |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
159 \lineii{\var{s}.pop()} |
|
27111
0364aae5a5a4
Fix some nits Guido brought up last August:
Fred Drake <fdrake@acm.org>
parents:
25031
diff
changeset
|
160 {remove and return an arbitrary element from \var{s}} |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
161 \lineii{\var{s}.update(\var{t})} |
|
27111
0364aae5a5a4
Fix some nits Guido brought up last August:
Fred Drake <fdrake@acm.org>
parents:
25031
diff
changeset
|
162 {add elements from \var{t} to set \var{s}} |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
163 \lineii{\var{s}.clear()} |
|
27111
0364aae5a5a4
Fix some nits Guido brought up last August:
Fred Drake <fdrake@acm.org>
parents:
25031
diff
changeset
|
164 {remove all elements from set \var{s}} |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
165 \end{tableii} |
| 24980 | 166 |
| 167 | |
|
27111
0364aae5a5a4
Fix some nits Guido brought up last August:
Fred Drake <fdrake@acm.org>
parents:
25031
diff
changeset
|
168 \subsection{Example \label{set-example}} |
| 24980 | 169 |
| 170 \begin{verbatim} | |
| 171 >>> from sets import Set | |
| 172 >>> engineers = Set(['John', 'Jane', 'Jack', 'Janice']) | |
| 173 >>> programmers = Set(['Jack', 'Sam', 'Susan', 'Janice']) | |
| 174 >>> management = Set(['Jane', 'Jack', 'Susan', 'Zack']) | |
| 175 >>> employees = engineers | programmers | management # union | |
| 176 >>> engineering_management = engineers & programmers # intersection | |
| 177 >>> fulltime_management = management - engineers - programmers # difference | |
| 178 >>> engineers.add('Marvin') # add element | |
| 179 >>> print engineers | |
| 180 Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack']) | |
| 181 >>> employees.issuperset(engineers) # superset test | |
| 182 False | |
| 183 >>> employees.update(engineers) # update from another set | |
| 184 >>> employees.issuperset(engineers) | |
| 185 True | |
| 186 >>> for group in [engineers, programmers, management, employees]: | |
|
27252
40cd74782600
Document that __cmp__() is not defined for sets.
Raymond Hettinger <python@rcn.com>
parents:
27111
diff
changeset
|
187 ... group.discard('Susan') # unconditionally remove element |
|
40cd74782600
Document that __cmp__() is not defined for sets.
Raymond Hettinger <python@rcn.com>
parents:
27111
diff
changeset
|
188 ... print group |
|
40cd74782600
Document that __cmp__() is not defined for sets.
Raymond Hettinger <python@rcn.com>
parents:
27111
diff
changeset
|
189 ... |
| 24980 | 190 Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack']) |
| 191 Set(['Janice', 'Jack', 'Sam']) | |
| 192 Set(['Jane', 'Zack', 'Jack']) | |
| 193 Set(['Jack', 'Sam', 'Jane', 'Marvin', 'Janice', 'John', 'Zack']) | |
| 194 \end{verbatim} | |
| 195 | |
| 196 | |
| 197 \subsection{Protocol for automatic conversion to immutable | |
| 198 \label{immutable-transforms}} | |
| 199 | |
| 200 Sets can only contain immutable elements. For convenience, mutable | |
| 201 \class{Set} objects are automatically copied to an \class{ImmutableSet} | |
| 202 before being added as a set element. | |
| 203 | |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
204 The mechanism is to always add a hashable element, or if it is not |
|
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
205 hashable, the element is checked to see if it has an |
|
27887
cedf9efa68f8
SF bug #663701: sets module review
Raymond Hettinger <python@rcn.com>
parents:
27886
diff
changeset
|
206 \method{__as_immutable__()} method which returns an immutable equivalent. |
| 24980 | 207 |
|
27887
cedf9efa68f8
SF bug #663701: sets module review
Raymond Hettinger <python@rcn.com>
parents:
27886
diff
changeset
|
208 Since \class{Set} objects have a \method{__as_immutable__()} method |
| 24980 | 209 returning an instance of \class{ImmutableSet}, it is possible to |
| 210 construct sets of sets. | |
| 211 | |
| 212 A similar mechanism is needed by the \method{__contains__()} and | |
| 213 \method{remove()} methods which need to hash an element to check | |
| 214 for membership in a set. Those methods check an element for hashability | |
|
27887
cedf9efa68f8
SF bug #663701: sets module review
Raymond Hettinger <python@rcn.com>
parents:
27886
diff
changeset
|
215 and, if not, check for a \method{__as_temporarily_immutable__()} method |
| 24980 | 216 which returns the element wrapped by a class that provides temporary |
| 217 methods for \method{__hash__()}, \method{__eq__()}, and \method{__ne__()}. | |
| 218 | |
| 219 The alternate mechanism spares the need to build a separate copy of | |
| 220 the original mutable object. | |
| 221 | |
|
27887
cedf9efa68f8
SF bug #663701: sets module review
Raymond Hettinger <python@rcn.com>
parents:
27886
diff
changeset
|
222 \class{Set} objects implement the \method{__as_temporarily_immutable__()} |
|
24998
ac468e20b4ce
Adjust the markup in a few places so this will actually format.
Fred Drake <fdrake@acm.org>
parents:
24980
diff
changeset
|
223 method which returns the \class{Set} object wrapped by a new class |
| 24980 | 224 \class{_TemporarilyImmutableSet}. |
| 225 | |
| 226 The two mechanisms for adding hashability are normally invisible to the | |
| 227 user; however, a conflict can arise in a multi-threaded environment | |
|
25002
0b726496cf44
Fix markup and punctuation
Raymond Hettinger <python@rcn.com>
parents:
25000
diff
changeset
|
228 where one thread is updating a set while another has temporarily wrapped it |
| 24980 | 229 in \class{_TemporarilyImmutableSet}. In other words, sets of mutable sets |
| 230 are not thread-safe. |