[Python-checkins] python/dist/src/Doc/lib libstdtypes.tex, 1.140, 1.141

Sun Nov 23 21:57:35 EST 2003

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv19524/Doc/lib
Modified Files:
	libstdtypes.tex 
Log Message:
* Checkin remaining documentation
* Add more tests
* Refactor and neaten the code a bit.
* Rename union_update() to update().
* Improve the algorithms (making them a closer to sets.py).
Index: libstdtypes.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libstdtypes.tex,v
retrieving revision 1.140
retrieving revision 1.141
diff -C2 -d -r1.140 -r1.141
*** libstdtypes.tex	30 Oct 2003 06:08:32 -0000	1.140
--- libstdtypes.tex	24 Nov 2003 02:57:33 -0000	1.141
***************
*** 1072,1075 ****
--- 1072,1195 ----
 \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}}