traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Incorporate documentation suggestions from feedback on comp.lang.python. 

* Positive wording for the description of why < and > and = can all
  be False.

* Move to a three column table format that puts long method names
  side-by-side with their operator equivalents

* Mention that KeyError can be raised by Set.pop() and Set.remove().

* Minor tweaks to the examples.

Will backport as soon as Fred rebuilds the docs so I can confirm
the tables formatted properly
This commit is contained in:
Raymond Hettinger 2003-08-16 00:56:40 +00:00
parent ee562fc084
commit 7ceb29e4a5
1 changed files with 42 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
Doc/lib/libsets.tex
View File

@ -65,41 +65,31 @@ elements must be known when the constructor is called.
Instances of \class{Set} and \class{ImmutableSet} both provide Instances of \class{Set} and \class{ImmutableSet} both provide
the following operations: the following operations:
\begin{tableii}{c|l}{code}{Operation}{Result} \begin{tableiii}{c|c|l}{code}{Operation}{Equivalent}{Result}
\lineii{len(\var{s})}{cardinality of set \var{s}} \lineiii{len(\var{s})}{}{cardinality of set \var{s}}
\hline \hline
\lineii{\var{x} in \var{s}} \lineiii{\var{x} in \var{s}}{}
{test \var{x} for membership in \var{s}} {test \var{x} for membership in \var{s}}
\lineii{\var{x} not in \var{s}} \lineiii{\var{x} not in \var{s}}{}
{test \var{x} for non-membership in \var{s}} {test \var{x} for non-membership in \var{s}}
\lineii{\var{s}.issubset(\var{t})} \lineiii{\var{s}.issubset(\var{t})}{\code{\var{s} <= \var{t}}}
{test whether every element in \var{s} is in \var{t}; {test whether every element in \var{s} is in \var{t}}
\code{\var{s} <= \var{t}} is equivalent} \lineiii{\var{s}.issuperset(\var{t})}{\code{\var{s} >= \var{t}}}
\lineii{\var{s}.issuperset(\var{t})} {test whether every element in \var{t} is in \var{s}}
{test whether every element in \var{t} is in \var{s};
\code{\var{s} >= \var{t}} is equivalent}
\hline \hline
\lineii{\var{s} | \var{t}} \lineiii{\var{s}.union(\var{t})}{\var{s} | \var{t}}
{new set with elements from both \var{s} and \var{t}} {new set with elements from both \var{s} and \var{t}}
\lineii{\var{s}.union(\var{t})} \lineiii{\var{s}.intersection(\var{t})}{\var{s} \&\ \var{t}}
{new set with elements from both \var{s} and \var{t}}
\lineii{\var{s} \&\ \var{t}}
{new set with elements common to \var{s} and \var{t}} {new set with elements common to \var{s} and \var{t}}
\lineii{\var{s}.intersection(\var{t})} \lineiii{\var{s}.difference(\var{t})}{\var{s} - \var{t}}
{new set with elements common to \var{s} and \var{t}}
\lineii{\var{s} - \var{t}}
{new set with elements in \var{s} but not in \var{t}} {new set with elements in \var{s} but not in \var{t}}
\lineii{\var{s}.difference(\var{t})} \lineiii{\var{s}.symmetric_difference(\var{t})}{\var{s} \^\ \var{t}}
{new set with elements in \var{s} but not in \var{t}}
\lineii{\var{s} \^\ \var{t}}
{new set with elements in either \var{s} or \var{t} but not both} {new set with elements in either \var{s} or \var{t} but not both}
\lineii{\var{s}.symmetric_difference(\var{t})} \lineiii{\var{s}.copy()}{}
{new set with elements in either \var{s} or \var{t} but not both}
\lineii{\var{s}.copy()}
{new set with a shallow copy of \var{s}} {new set with a shallow copy of \var{s}}
\end{tableii} \end{tableiii}
In addition, both \class{Set} and \class{ImmutableSet} In addition, both \class{Set} and \class{ImmutableSet}
support set to set comparisons. Two sets are equal if and only if support set to set comparisons. Two sets are equal if and only if
@ -112,8 +102,9 @@ superset of the second set (is a superset, but is not equal).
The subset and equality comparisons do not generalize to a complete The subset and equality comparisons do not generalize to a complete
ordering function. For example, any two disjoint sets are not equal and ordering function. For example, any two disjoint sets are not equal and
are not subsets of each other, so \emph{none} of the following are true: are not subsets of each other, so \emph{all} of the following return
\code{\var{a}<\var{b}}, \code{\var{a}==\var{b}}, or \code{\var{a}>\var{b}}. \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. Accordingly, sets do not implement the \method{__cmp__} method.
Since sets only define partial ordering (subset relationships), the output Since sets only define partial ordering (subset relationships), the output
@ -122,47 +113,43 @@ of the \method{list.sort()} method is undefined for lists of sets.
The following table lists operations available in \class{ImmutableSet} The following table lists operations available in \class{ImmutableSet}
but not found in \class{Set}: but not found in \class{Set}:
\begin{tableii}{c|l|c}{code}{Operation}{Result} \begin{tableii}{c|l}{code}{Operation}{Result}
\lineii{hash(\var{s})}{returns a hash value for \var{s}} \lineii{hash(\var{s})}{returns a hash value for \var{s}}
\end{tableii} \end{tableii}
The following table lists operations available in \class{Set} The following table lists operations available in \class{Set}
but not found in \class{ImmutableSet}: but not found in \class{ImmutableSet}:
\begin{tableii}{c|l}{code}{Operation}{Result} \begin{tableiii}{c|c|l}{code}{Operation}{Equivalent}{Result}
\lineii{\var{s} |= \var{t}} \lineiii{\var{s}.union_update(\var{t})}
{\var{s} |= \var{t}}
{return set \var{s} with elements added from \var{t}} {return set \var{s} with elements added from \var{t}}
\lineii{\var{s}.union_update(\var{t})} \lineiii{\var{s}.intersection_update(\var{t})}
{return set \var{s} with elements added from \var{t}} {\var{s} \&= \var{t}}
\lineii{\var{s} \&= \var{t}}
{return set \var{s} keeping only elements also found in \var{t}} {return set \var{s} keeping only elements also found in \var{t}}
\lineii{\var{s}.intersection_update(\var{t})} \lineiii{\var{s}.difference_update(\var{t})}
{return set \var{s} keeping only elements also found in \var{t}} {\var{s} -= \var{t}}
\lineii{\var{s} -= \var{t}}
{return set \var{s} after removing elements found in \var{t}} {return set \var{s} after removing elements found in \var{t}}
\lineii{\var{s}.difference_update(\var{t})} \lineiii{\var{s}.symmetric_difference_update(\var{t})}
{return set \var{s} after removing elements found in \var{t}} {\var{s} \textasciicircum= \var{t}}
\lineii{\var{s} \textasciicircum= \var{t}}
{return set \var{s} with elements from \var{s} or \var{t}
but not both}
\lineii{\var{s}.symmetric_difference_update(\var{t})}
{return set \var{s} with elements from \var{s} or \var{t} {return set \var{s} with elements from \var{s} or \var{t}
but not both} but not both}
\hline \hline
\lineii{\var{s}.add(\var{x})} \lineiii{\var{s}.add(\var{x})}{}
{add element \var{x} to set \var{s}} {add element \var{x} to set \var{s}}
\lineii{\var{s}.remove(\var{x})} \lineiii{\var{s}.remove(\var{x})}{}
{remove \var{x} from set \var{s}} {remove \var{x} from set \var{s}; raises KeyError if not present}
\lineii{\var{s}.discard(\var{x})} \lineiii{\var{s}.discard(\var{x})}{}
{removes \var{x} from set \var{s} if present} {removes \var{x} from set \var{s} if present}
\lineii{\var{s}.pop()} \lineiii{\var{s}.pop()}{}
{remove and return an arbitrary element from \var{s}} {remove and return an arbitrary element from \var{s}; raises
\lineii{\var{s}.update(\var{t})} KeyError if empty}
\lineiii{\var{s}.update(\var{t})}{}
{add elements from \var{t} to set \var{s}} {add elements from \var{t} to set \var{s}}
\lineii{\var{s}.clear()} \lineiii{\var{s}.clear()}{}
{remove all elements from set \var{s}} {remove all elements from set \var{s}}
\end{tableii} \end{tableiii}
\subsection{Example \label{set-example}} \subsection{Example \label{set-example}}
@ -171,10 +158,10 @@ but not found in \class{ImmutableSet}:
>>> from sets import Set >>> from sets import Set
>>> engineers = Set(['John', 'Jane', 'Jack', 'Janice']) >>> engineers = Set(['John', 'Jane', 'Jack', 'Janice'])
>>> programmers = Set(['Jack', 'Sam', 'Susan', 'Janice']) >>> programmers = Set(['Jack', 'Sam', 'Susan', 'Janice'])
>>> management = Set(['Jane', 'Jack', 'Susan', 'Zack']) >>> managers = Set(['Jane', 'Jack', 'Susan', 'Zack'])
>>> employees = engineers | programmers | management # union >>> employees = engineers | programmers | managers # union
>>> engineering_management = engineers & programmers # intersection >>> engineering_management = engineers & managers # intersection
>>> fulltime_management = management - engineers - programmers # difference >>> fulltime_management = managers - engineers - programmers # difference
>>> engineers.add('Marvin') # add element >>> engineers.add('Marvin') # add element
>>> print engineers >>> print engineers
Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack']) Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack'])