[Python-checkins] python/dist/src/Doc/lib libsets.tex, 1.11,
1.11.16.1
rhettinger at users.sourceforge.net
rhettinger at users.sourceforge.net
Sun Aug 17 16:09:00 EDT 2003
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv27709/Doc/lib
Modified Files:
Tag: release23-maint
libsets.tex
Log Message:
Backport improvements to set.py so that the interface will remain
consistent across versions.
* Relaxed the argument restrictions for non-operator methods. They now
allow any iterable instead of requiring a set. This makes the module
a little easier to use and paves the way for an efficient C
implementation which can take better advantage of iterable arguments
while screening out immutables.
* Added a PendingDeprecationWarning for Set.update() because it now
duplicates Set.union_update()
* Adapted the tests and docs to include the above changes.
* Added more test coverage including testing identities and checking
to make sure non-restartable generators work as arguments.
Index: libsets.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libsets.tex,v
retrieving revision 1.11
retrieving revision 1.11.16.1
diff -C2 -d -r1.11 -r1.11.16.1
*** libsets.tex 14 Feb 2003 03:42:11 -0000 1.11
--- libsets.tex 17 Aug 2003 22:08:58 -0000 1.11.16.1
***************
*** 66,104 ****
the following operations:
! \begin{tableii}{c|l}{code}{Operation}{Result}
! \lineii{len(\var{s})}{cardinality of set \var{s}}
\hline
! \lineii{\var{x} in \var{s}}
{test \var{x} for membership in \var{s}}
! \lineii{\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}
\hline
! \lineii{\var{s} | \var{t}}
! {new set with elements from both \var{s} and \var{t}}
! \lineii{\var{s}.union(\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}}
! \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})}
{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}
! \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()}
{new set with a shallow copy of \var{s}}
! \end{tableii}
In addition, both \class{Set} and \class{ImmutableSet}
--- 66,103 ----
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, this 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}
***************
*** 113,118 ****
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}}.
Accordingly, sets do not implement the \method{__cmp__} method.
--- 112,118 ----
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.
***************
*** 123,127 ****
but not found in \class{Set}:
! \begin{tableii}{c|l|c}{code}{Operation}{Result}
\lineii{hash(\var{s})}{returns a hash value for \var{s}}
\end{tableii}
--- 123,127 ----
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}
***************
*** 130,167 ****
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})}
{return set \var{s} with elements added from \var{t}}
! \lineii{\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})}
{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})}
{return set \var{s} with elements from \var{s} or \var{t}
but not both}
\hline
! \lineii{\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})}
{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})}
! {add elements from \var{t} to set \var{s}}
! \lineii{\var{s}.clear()}
{remove all elements from set \var{s}}
! \end{tableii}
--- 130,170 ----
but not found in \class{ImmutableSet}:
! \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}}
! \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
! KeyError if empty}
! \lineiii{\var{s}.clear()}{}
{remove all elements from set \var{s}}
! \end{tableiii}
!
! \versionchanged[Earlier versions had an \method{update()} method; use
! \method{union_update()} instead]{2.3.1}
!
! Note, this non-operator versions of \method{union_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}
***************
*** 172,185 ****
>>> 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
>>> print engineers
Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack'])
>>> employees.issuperset(engineers) # superset test
False
! >>> employees.update(engineers) # update from another set
>>> employees.issuperset(engineers)
True
--- 175,188 ----
>>> 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
More information about the Python-checkins
mailing list