From 7ceb29e4a51b12b08884bd2b43c6255228bdd5e5 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Sat, 16 Aug 2003 00:56:40 +0000 Subject: 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 --- Doc/lib/libsets.tex | 97 +++++++++++++++++++++++------------------------------ 1 file changed, 42 insertions(+), 55 deletions(-) diff --git a/Doc/lib/libsets.tex b/Doc/lib/libsets.tex index 4d87a4f..71b6d3d 100644 --- a/Doc/lib/libsets.tex +++ b/Doc/lib/libsets.tex @@ -65,41 +65,31 @@ elements must be known when the constructor is called. Instances of \class{Set} and \class{ImmutableSet} both provide the following operations: -\begin{tableii}{c|l}{code}{Operation}{Result} - \lineii{len(\var{s})}{cardinality of set \var{s}} +\begin{tableiii}{c|c|l}{code}{Operation}{Equivalent}{Result} + \lineiii{len(\var{s})}{}{cardinality of set \var{s}} \hline - \lineii{\var{x} in \var{s}} + \lineiii{\var{x} 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}} - \lineii{\var{s}.issubset(\var{t})} - {test whether every element in \var{s} is in \var{t}; - \code{\var{s} <= \var{t}} is equivalent} - \lineii{\var{s}.issuperset(\var{t})} - {test whether every element in \var{t} is in \var{s}; - \code{\var{s} >= \var{t}} is equivalent} + \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 - \lineii{\var{s} | \var{t}} - {new set with elements from both \var{s} and \var{t}} - \lineii{\var{s}.union(\var{t})} + \lineiii{\var{s}.union(\var{t})}{\var{s} | \var{t}} {new set with elements from both \var{s} and \var{t}} - \lineii{\var{s} \&\ \var{t}} + \lineiii{\var{s}.intersection(\var{t})}{\var{s} \&\ \var{t}} {new set with elements common to \var{s} and \var{t}} - \lineii{\var{s}.intersection(\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}} - \lineii{\var{s}.difference(\var{t})} + \lineiii{\var{s}.difference(\var{t})}{\var{s} - \var{t}} {new set with elements in \var{s} but not in \var{t}} - \lineii{\var{s} \^\ \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} - \lineii{\var{s}.symmetric_difference(\var{t})} - {new set with elements in either \var{s} or \var{t} but not both} - \lineii{\var{s}.copy()} + \lineiii{\var{s}.copy()}{} {new set with a shallow copy of \var{s}} -\end{tableii} +\end{tableiii} In addition, both \class{Set} and \class{ImmutableSet} 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 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: -\code{\var{a}<\var{b}}, \code{\var{a}==\var{b}}, or \code{\var{a}>\var{b}}. +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 @@ -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} 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}} \end{tableii} The following table lists operations available in \class{Set} but not found in \class{ImmutableSet}: -\begin{tableii}{c|l}{code}{Operation}{Result} - \lineii{\var{s} |= \var{t}} - {return set \var{s} with elements added from \var{t}} - \lineii{\var{s}.union_update(\var{t})} +\begin{tableiii}{c|c|l}{code}{Operation}{Equivalent}{Result} + \lineiii{\var{s}.union_update(\var{t})} + {\var{s} |= \var{t}} {return set \var{s} with elements added from \var{t}} - \lineii{\var{s} \&= \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}} - \lineii{\var{s}.intersection_update(\var{t})} - {return set \var{s} keeping only elements also found in \var{t}} - \lineii{\var{s} -= \var{t}} - {return set \var{s} after removing elements found in \var{t}} - \lineii{\var{s}.difference_update(\var{t})} + \lineiii{\var{s}.difference_update(\var{t})} + {\var{s} -= \var{t}} {return set \var{s} after removing elements found in \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})} + \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 - \lineii{\var{s}.add(\var{x})} + \lineiii{\var{s}.add(\var{x})}{} {add element \var{x} to set \var{s}} - \lineii{\var{s}.remove(\var{x})} - {remove \var{x} from set \var{s}} - \lineii{\var{s}.discard(\var{x})} + \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} - \lineii{\var{s}.pop()} - {remove and return an arbitrary element from \var{s}} - \lineii{\var{s}.update(\var{t})} + \lineiii{\var{s}.pop()}{} + {remove and return an arbitrary element from \var{s}; raises + KeyError if empty} + \lineiii{\var{s}.update(\var{t})}{} {add elements from \var{t} to set \var{s}} - \lineii{\var{s}.clear()} + \lineiii{\var{s}.clear()}{} {remove all elements from set \var{s}} -\end{tableii} +\end{tableiii} \subsection{Example \label{set-example}} @@ -171,11 +158,11 @@ but not found in \class{ImmutableSet}: >>> from sets import Set >>> engineers = Set(['John', 'Jane', 'Jack', 'Janice']) >>> programmers = Set(['Jack', 'Sam', 'Susan', 'Janice']) ->>> management = Set(['Jane', 'Jack', 'Susan', 'Zack']) ->>> employees = engineers | programmers | management # union ->>> engineering_management = engineers & programmers # intersection ->>> fulltime_management = management - engineers - programmers # difference ->>> engineers.add('Marvin') # add element +>>> 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 -- cgit v0.12