[Python-checkins] python/dist/src/Doc/lib libsets.tex,1.12,1.13

[rhettinger at users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv12812/Doc/lib

Modified Files:
	libsets.tex 
Log Message:
Improvements to set.py:

* 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.

* Deprecated 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.

Will backport to Py2.3.1 so that the interface remains consistent 
across versions.  The deprecation of update() will be changed to 
a FutureWarning.



Index: libsets.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libsets.tex,v
retrieving revision 1.12
retrieving revision 1.13
diff -C2 -d -r1.12 -r1.13
*** libsets.tex	16 Aug 2003 00:56:40 -0000	1.12
--- libsets.tex	17 Aug 2003 08:34:09 -0000	1.13
***************
*** 92,95 ****
--- 92,104 ----
  \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}
  support set to set comparisons.  Two sets are equal if and only if
***************
*** 146,155 ****
           {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}}
    \lineiii{\var{s}.clear()}{}
           {remove all elements from set \var{s}}
  \end{tableiii}
  
  
  \subsection{Example \label{set-example}}
--- 155,171 ----
           {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}
+ 
  
  \subsection{Example \label{set-example}}
***************
*** 168,172 ****
  >>> employees.issuperset(engineers)           # superset test
  False
! >>> employees.update(engineers)               # update from another set
  >>> employees.issuperset(engineers)
  True
--- 184,188 ----
  >>> employees.issuperset(engineers)           # superset test
  False
! >>> employees.union_update(engineers)         # update from another set
  >>> employees.issuperset(engineers)
  True