diff options
author | Guido van Rossum <guido@python.org> | 2007-01-10 01:28:32 (GMT) |
---|---|---|
committer | Guido van Rossum <guido@python.org> | 2007-01-10 01:28:32 (GMT) |
commit | 33552e92fe37194c867921675a2cf25e7432008c (patch) | |
tree | b295ab25918393368d06239f8e3bf7a145931479 /Doc/lib | |
parent | 902d6ebddd07a6086b54ae42929293418f0852d7 (diff) | |
download | cpython-33552e92fe37194c867921675a2cf25e7432008c.zip cpython-33552e92fe37194c867921675a2cf25e7432008c.tar.gz cpython-33552e92fe37194c867921675a2cf25e7432008c.tar.bz2 |
Excise the sets module. SF #1500611 by Collin Winter.
Diffstat (limited to 'Doc/lib')
-rw-r--r-- | Doc/lib/lib.tex | 1 | ||||
-rw-r--r-- | Doc/lib/libsets.tex | 264 | ||||
-rw-r--r-- | Doc/lib/libstdtypes.tex | 10 |
3 files changed, 0 insertions, 275 deletions
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 837c759..427d71d 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -104,7 +104,6 @@ and how to embed it in other applications. \input{libheapq} \input{libbisect} \input{libarray} -\input{libsets} \input{libsched} \input{libmutex} \input{libqueue} diff --git a/Doc/lib/libsets.tex b/Doc/lib/libsets.tex index 22bf34b..e69de29 100644 --- a/Doc/lib/libsets.tex +++ b/Doc/lib/libsets.tex @@ -1,264 +0,0 @@ -\section{\module{sets} --- - Unordered collections of unique elements} - -\declaremodule{standard}{sets} -\modulesynopsis{Implementation of sets of unique elements.} -\moduleauthor{Greg V. Wilson}{gvwilson@nevex.com} -\moduleauthor{Alex Martelli}{aleax@aleax.it} -\moduleauthor{Guido van Rossum}{guido@python.org} -\sectionauthor{Raymond D. Hettinger}{python@rcn.com} - -\versionadded{2.3} - -The \module{sets} module provides classes for constructing and manipulating -unordered collections of unique elements. Common uses include membership -testing, removing duplicates from a sequence, and computing standard math -operations on sets such as intersection, union, difference, and symmetric -difference. - -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. - -Most set applications use the \class{Set} class which provides every set -method except for \method{__hash__()}. For advanced applications requiring -a hash method, the \class{ImmutableSet} class adds a \method{__hash__()} -method but omits methods which alter the contents of the set. Both -\class{Set} and \class{ImmutableSet} derive from \class{BaseSet}, an -abstract class useful for determining whether something is a set: -\code{isinstance(\var{obj}, BaseSet)}. - -The set classes are implemented using dictionaries. Accordingly, the -requirements for set elements are the same as those for dictionary keys; -namely, that the element defines both \method{__eq__} and \method{__hash__}. -As a result, sets -cannot contain mutable elements such as lists or dictionaries. -However, they can contain immutable collections such as tuples or -instances of \class{ImmutableSet}. For convenience in implementing -sets of sets, inner sets are automatically converted to immutable -form, for example, \code{Set([Set(['dog'])])} is transformed to -\code{Set([ImmutableSet(['dog'])])}. - -\begin{classdesc}{Set}{\optional{iterable}} -Constructs a new empty \class{Set} object. If the optional \var{iterable} -parameter is supplied, updates the set with elements obtained from iteration. -All of the elements in \var{iterable} should be immutable or be transformable -to an immutable using the protocol described in -section~\ref{immutable-transforms}. -\end{classdesc} - -\begin{classdesc}{ImmutableSet}{\optional{iterable}} -Constructs a new empty \class{ImmutableSet} object. If the optional -\var{iterable} parameter is supplied, updates the set with elements obtained -from iteration. All of the elements in \var{iterable} should be immutable or -be transformable to an immutable using the protocol described in -section~\ref{immutable-transforms}. - -Because \class{ImmutableSet} objects provide a \method{__hash__()} method, -they can be used as set elements or as dictionary keys. \class{ImmutableSet} -objects do not have methods for adding or removing elements, so all of the -elements must be known when the constructor is called. -\end{classdesc} - - -\subsection{Set Objects \label{set-objects}} - -Instances of \class{Set} and \class{ImmutableSet} both 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} \textbar{} \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()} 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')}. -\versionchanged[Formerly all arguments were required to be sets]{2.3.1} - -In addition, both \class{Set} and \class{ImmutableSet} -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. - -The following table lists operations available in \class{ImmutableSet} -but not found in \class{Set}: - -\begin{tableii}{c|l}{code}{Operation}{Result} - \lineii{hash(\var{s})}{returns a hash value for \var{s}} -\end{tableii} - -The following table lists operations available in \class{Set} -but not found in \class{ImmutableSet}: - -\begin{tableiii}{c|c|l}{code}{Operation}{Equivalent}{Result} - \lineiii{\var{s}.update(\var{t})} - {\var{s} \textbar= \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 \exception{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 \method{update()}, -\method{intersection_update()}, \method{difference_update()}, and -\method{symmetric_difference_update()} will accept any iterable as -an argument. -\versionchanged[Formerly all arguments were required to be sets]{2.3.1} - -Also note, the module also includes a \method{union_update()} method -which is an alias for \method{update()}. The method is included for -backwards compatibility. Programmers should prefer the -\method{update()} method because it is supported by the builtin -\class{set()} and \class{frozenset()} types. - -\subsection{Example \label{set-example}} - -\begin{verbatim} ->>> from sets import Set ->>> engineers = Set(['John', 'Jane', 'Jack', 'Janice']) ->>> programmers = Set(['Jack', 'Sam', 'Susan', 'Janice']) ->>> managers = Set(['Jane', 'Jack', 'Susan', 'Zack']) ->>> employees = engineers | programmers | managers # union ->>> engineering_management = engineers & managers # intersection ->>> fulltime_management = managers - engineers - programmers # difference ->>> engineers.add('Marvin') # add element ->>> print engineers -Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack']) ->>> employees.issuperset(engineers) # superset test -False ->>> employees.union_update(engineers) # update from another set ->>> employees.issuperset(engineers) -True ->>> for group in [engineers, programmers, managers, employees]: -... group.discard('Susan') # unconditionally remove element -... print group -... -Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack']) -Set(['Janice', 'Jack', 'Sam']) -Set(['Jane', 'Zack', 'Jack']) -Set(['Jack', 'Sam', 'Jane', 'Marvin', 'Janice', 'John', 'Zack']) -\end{verbatim} - - -\subsection{Protocol for automatic conversion to immutable - \label{immutable-transforms}} - -Sets can only contain immutable elements. For convenience, mutable -\class{Set} objects are automatically copied to an \class{ImmutableSet} -before being added as a set element. - -The mechanism is to always add a hashable element, or if it is not -hashable, the element is checked to see if it has an -\method{__as_immutable__()} method which returns an immutable equivalent. - -Since \class{Set} objects have a \method{__as_immutable__()} method -returning an instance of \class{ImmutableSet}, it is possible to -construct sets of sets. - -A similar mechanism is needed by the \method{__contains__()} and -\method{remove()} methods which need to hash an element to check -for membership in a set. Those methods check an element for hashability -and, if not, check for a \method{__as_temporarily_immutable__()} method -which returns the element wrapped by a class that provides temporary -methods for \method{__hash__()}, \method{__eq__()}, and \method{__ne__()}. - -The alternate mechanism spares the need to build a separate copy of -the original mutable object. - -\class{Set} objects implement the \method{__as_temporarily_immutable__()} -method which returns the \class{Set} object wrapped by a new class -\class{_TemporarilyImmutableSet}. - -The two mechanisms for adding hashability are normally invisible to the -user; however, a conflict can arise in a multi-threaded environment -where one thread is updating a set while another has temporarily wrapped it -in \class{_TemporarilyImmutableSet}. In other words, sets of mutable sets -are not thread-safe. - - -\subsection{Comparison to the built-in \class{set} types - \label{comparison-to-builtin-set}} - -The built-in \class{set} and \class{frozenset} types were designed based -on lessons learned from the \module{sets} module. The key differences are: - -\begin{itemize} -\item \class{Set} and \class{ImmutableSet} were renamed to \class{set} and - \class{frozenset}. -\item There is no equivalent to \class{BaseSet}. Instead, use - \code{isinstance(x, (set, frozenset))}. -\item The hash algorithm for the built-ins performs significantly better - (fewer collisions) for most datasets. -\item The built-in versions have more space efficient pickles. -\item The built-in versions do not have a \method{union_update()} method. - Instead, use the \method{update()} method which is equivalent. -\item The built-in versions do not have a \method{_repr(sorted=True)} method. - Instead, use the built-in \function{repr()} and \function{sorted()} - functions: \code{repr(sorted(s))}. -\item The built-in version does not have a protocol for automatic conversion - to immutable. Many found this feature to be confusing and no one - in the community reported having found real uses for it. -\end{itemize} diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex index 8a527f6..a07e7d7 100644 --- a/Doc/lib/libstdtypes.tex +++ b/Doc/lib/libstdtypes.tex @@ -1334,16 +1334,6 @@ 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. - -The design of the set types was based on lessons learned from the -\module{sets} module. - -\begin{seealso} - \seelink{comparison-to-builtin-set.html} - {Comparison to the built-in set types} - {Differences between the \module{sets} module and the - built-in set types.} -\end{seealso} \section{Mapping Types --- \class{dict} \label{typesmapping}} |