[Python-checkins] python/dist/src/Doc/lib libstdtypes.tex,1.100,1.101

[tim_one@users.sourceforge.net]

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

Modified Files:
	libstdtypes.tex 
Log Message:
Added new footnote about list.sort() stability.  Repaired footnote about
using sort() with comparison functions (it made reference to the non-
existent "builtin-in function sort()").

BTW, I changed list.sort's docstring to contain the word "stable" -- the
easiest way to tell whether a particular Python version's sort *is* stable
is to look for "stable" in the docstring.  I'm not sure whether to
advertise this <wink>.


Index: libstdtypes.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libstdtypes.tex,v
retrieving revision 1.100
retrieving revision 1.101
diff -C2 -d -r1.100 -r1.101
*** libstdtypes.tex	16 Jul 2002 19:53:39 -0000	1.100
--- libstdtypes.tex	1 Aug 2002 03:10:45 -0000	1.101
***************
*** 902,906 ****
  	{reverses the items of \var{s} in place}{(6)}
    \lineiii{\var{s}.sort(\optional{\var{cmpfunc}})}
! 	{sort the items of \var{s} in place}{(6), (7)}
  \end{tableiii}
  \indexiv{operations on}{mutable}{sequence}{types}
--- 902,906 ----
  	{reverses the items of \var{s} in place}{(6)}
    \lineiii{\var{s}.sort(\optional{\var{cmpfunc}})}
! 	{sort the items of \var{s} in place}{(6), (7), (8)}
  \end{tableiii}
  \indexiv{operations on}{mutable}{sequence}{types}
***************
*** 948,955 ****
    than the second argument.  Note that this slows the sorting process
    down considerably; e.g. to sort a list in reverse order it is much
!   faster to use calls to the methods \method{sort()} and
!   \method{reverse()} than to use the built-in function
!   \function{sort()} with a comparison function that reverses the
    ordering of the elements.
  \end{description}
  
--- 948,963 ----
    than the second argument.  Note that this slows the sorting process
    down considerably; e.g. to sort a list in reverse order it is much
!   faster to call method \method{sort()} followed by
!   \method{reverse()} than to use method
!   \method{sort()} with a comparison function that reverses the
    ordering of the elements.
+ 
+ \item[(8)] 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.
  \end{description}