diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/lib/libstdtypes.tex | 120 |
1 files changed, 120 insertions, 0 deletions
diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex index 917ca4b..4eb4595 100644 --- a/Doc/lib/libstdtypes.tex +++ b/Doc/lib/libstdtypes.tex @@ -1071,6 +1071,126 @@ Notes: \versionadded{2.4} \end{description} +\subsection{Set Types \label{types-set}} +\obindex{set} + +A \dfn{set} 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. +\versionadded{2.4} + +Like other collections, sets support \code{\var{x} in \var{set}}, +\code{len(\var{set})}, and \code{for \var{x} in \var{set}}. 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, \class{set} and \class{frozenset}. +The \class{set} type is mutable --- the contents can be changed using methods +like \method{add()} and \method{remove()}. 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 \class{frozenset} 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 \class{set} and \class{frozenset} provide the following operations: + +\begin{tableiii}{c|c|l}{code}{Operation}{Equivalent}{Result} + \lineiii{len(\var{s})}{}{cardinality of set \var{s}} + + \hline + \lineiii{\var{x} in \var{s}}{} + {test \var{x} for membership in \var{s}} + \lineiii{\var{x} not in \var{s}}{} + {test \var{x} for non-membership in \var{s}} + \lineiii{\var{s}.issubset(\var{t})}{\code{\var{s} <= \var{t}}} + {test whether every element in \var{s} is in \var{t}} + \lineiii{\var{s}.issuperset(\var{t})}{\code{\var{s} >= \var{t}}} + {test whether every element in \var{t} is in \var{s}} + + \hline + \lineiii{\var{s}.union(\var{t})}{\var{s} | \var{t}} + {new set with elements from both \var{s} and \var{t}} + \lineiii{\var{s}.intersection(\var{t})}{\var{s} \&\ \var{t}} + {new set with elements common to \var{s} and \var{t}} + \lineiii{\var{s}.difference(\var{t})}{\var{s} - \var{t}} + {new set with elements in \var{s} but not in \var{t}} + \lineiii{\var{s}.symmetric_difference(\var{t})}{\var{s} \^\ \var{t}} + {new set with elements in either \var{s} or \var{t} but not both} + \lineiii{\var{s}.copy()}{} + {new set with a shallow copy of \var{s}} +\end{tableiii} + +Note, the non-operator versions of \method{union()}, \method{intersection()}, +\method{difference()}, and \method{symmetric_difference()}, +\method{issubset()}, and \method{issuperset()} 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'} in favor of the more readable +\code{set('abc').intersection('cbs')}. + +Both \class{set} and \class{frozenset} 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). + +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 \emph{all} of the following return +\code{False}: \code{\var{a}<\var{b}}, \code{\var{a}==\var{b}}, or +\code{\var{a}>\var{b}}. +Accordingly, sets do not implement the \method{__cmp__} method. + +Since sets only define partial ordering (subset relationships), the output +of the \method{list.sort()} method is undefined for lists of sets. + +For convenience in implementing sets of sets, the \method{__contains__()}, +\method{remove()}, and \method{discard()} methods automatically match +instances of the \class{set} class their \class{frozenset} counterparts +inside a set. For example, \code{set('abc') in set([frozenset('abc')])} +returns \code{True}. + +The following table lists operations available for \class{set} +that do not apply to immutable instances of \class{frozenset}: + +\begin{tableiii}{c|c|l}{code}{Operation}{Equivalent}{Result} + \lineiii{\var{s}.update(\var{t})} + {\var{s} |= \var{t}} + {return set \var{s} with elements added from \var{t}} + \lineiii{\var{s}.intersection_update(\var{t})} + {\var{s} \&= \var{t}} + {return set \var{s} keeping only elements also found in \var{t}} + \lineiii{\var{s}.difference_update(\var{t})} + {\var{s} -= \var{t}} + {return set \var{s} after removing elements found in \var{t}} + \lineiii{\var{s}.symmetric_difference_update(\var{t})} + {\var{s} \textasciicircum= \var{t}} + {return set \var{s} with elements from \var{s} or \var{t} + but not both} + + \hline + \lineiii{\var{s}.add(\var{x})}{} + {add element \var{x} to set \var{s}} + \lineiii{\var{s}.remove(\var{x})}{} + {remove \var{x} from set \var{s}; raises KeyError if not present} + \lineiii{\var{s}.discard(\var{x})}{} + {removes \var{x} from set \var{s} if present} + \lineiii{\var{s}.pop()}{} + {remove and return an arbitrary element from \var{s}; raises + \exception{KeyError} if empty} + \lineiii{\var{s}.clear()}{} + {remove all elements from set \var{s}} +\end{tableiii} + +Note, the non-operator versions of the \method{update()}, +\method{intersection_update()}, \method{difference_update()}, and +\method{symmetric_difference_update()} methods will accept any iterable +as an argument. + \subsection{Mapping Types \label{typesmapping}} \obindex{mapping} |