[Python-checkins] python/dist/src/Doc/lib libstdtypes.tex, 1.133, 1.134

[rhettinger at users.sourceforge.net]

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

Modified Files:
	libstdtypes.tex 
Log Message:
* list.sort() now supports three keyword arguments:  cmp, key, and reverse.
  key provides C support for the decorate-sort-undecorate pattern.
  reverse provide a stable sort of the list with the comparisions reversed.

* Amended the docs to guarantee sort stability.



Index: libstdtypes.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libstdtypes.tex,v
retrieving revision 1.133
retrieving revision 1.134
diff -C2 -d -r1.133 -r1.134
*** libstdtypes.tex	12 Sep 2003 00:02:37 -0000	1.133
--- libstdtypes.tex	16 Oct 2003 03:41:09 -0000	1.134
***************
*** 971,975 ****
    \lineiii{\var{s}.reverse()}
  	{reverses the items of \var{s} in place}{(7)}
!   \lineiii{\var{s}.sort(\optional{\var{cmpfunc=None}})}
  	{sort the items of \var{s} in place}{(7), (8), (9), (10)}
  \end{tableiii}
--- 971,976 ----
    \lineiii{\var{s}.reverse()}
  	{reverses the items of \var{s} in place}{(7)}
!   \lineiii{\var{s}.sort(\optional{\var{cmp}=None\optional{, \var{key}=None
!                         \optional{, \var{reverse}=False}}})}
  	{sort the items of \var{s} in place}{(7), (8), (9), (10)}
  \end{tableiii}
***************
*** 1022,1066 ****
    the sorted or reversed list.
  
! \item[(8)] The \method{sort()} method takes an optional argument
!   specifying a comparison function of two arguments (list items) which
!   should return a negative, zero or positive number depending on whether
!   the first argument is considered smaller than, equal to, or larger
!   than the second argument.  Note that this slows the sorting process
!   down considerably; for example to sort a list in reverse order it is much
!   faster to call \method{sort()} followed by \method{reverse()}
!   than to use \method{sort()} with a comparison function that
!   reverses the ordering of the elements.  Passing \constant{None} as the
!   comparison function is semantically equivalent to calling
!   \method{sort()} with no comparison function.
!   \versionchanged[Support for \code{None} as an equivalent to omitting
!   \var{cmpfunc} was added]{2.3}
  
!   As an example of using the \var{cmpfunc} argument to the
!   \method{sort()} method, consider sorting a list of sequences by the
!   second element of that list:
  
! \begin{verbatim}
! def mycmp(a, b):
!     return cmp(a[1], b[1])
  
! mylist.sort(mycmp)
! \end{verbatim}
  
!   A more time-efficient approach for reasonably-sized data structures can
!   often be used:
  
! \begin{verbatim}
! tmplist = [(x[1], x) for x in mylist]
! tmplist.sort()
! mylist = [x for (key, x) in tmplist]
! \end{verbatim}
  
! \item[(9)] Whether the \method{sort()} method is stable is not defined by
!   the language (a sort is stable if it guarantees not to change the
!   relative order of elements that compare equal).  In the C
!   implementation of Python, sorts were stable only by accident through
!   Python 2.2.  The C implementation of Python 2.3 introduced a stable
!   \method{sort()} method, but code that intends to be portable across
!   implementations and versions must not rely on stability.
  
  \item[(10)] While a list is being sorted, the effect of attempting to
--- 1023,1058 ----
    the sorted or reversed list.
  
! \item[(8)] The \method{sort()} method takes optional arguments for
!   controlling the comparisions.
  
!   \var{cmp} specifies a custom comparison function of two arguments
!      (list items) which should return a negative, zero or positive number
!      depending on whether the first argument is considered smaller than,
!      equal to, or larger than the second argument:
!      \samp{\var{cmp}=\keyword{lambda} \var{x},\var{y}:
!      \function{cmp}(x.lower(), y.lower())}
!      
!   \var{key} specifies a function of one argument that is used to
!      extract a comparison key from each list element:
!      \samp{\var{cmp}=\function{str.lower}}
  
!   \var{reverse} is a boolean value.  If set to \code{True}, then the
!      list elements are sorted as if each comparison were reversed.
  
!   In general, the \var{key} and \var{reverse} conversion processes are
!   much faster than specifying an equivalent \var{cmp} function.  This is
!   because \var{cmp} is called multiple times for each list element while
!   \var{key} and \{reverse} touch each element only once.
  
!   \versionchanged[Support for \code{None} as an equivalent to omitting
!   \var{cmpfunc} was added]{2.3}
  
!   \versionadded[Support for \var{key} and \var{reverse} was added]{2.4}
  
! \item[(9)]  Starting with Python 2.3, the \method{sort()} method is
!   guaranteed to be stable.  A sort is stable if it guarantees not to
!   change the relative order of elements that compare equal --- this is
!   helpful for sorting in multiple passes (for example, sort by
!   department, then by salary grade).
  
  \item[(10)] While a list is being sorted, the effect of attempting to