From: Tim Peters <tim.peters@gmail.com>
Date: Thu, 1 Aug 2002 03:10:45 +0000 (+0000)
Subject: Added new footnote about list.sort() stability.  Repaired footnote about
X-Git-Tag: v2.3c1~4803
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=74824584ef6358eed6fe56cf5513fec5ad9da0da;p=python

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

diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex
index aabc9bfa48..87d5402d05 100644
--- a/Doc/lib/libstdtypes.tex
+++ b/Doc/lib/libstdtypes.tex
@@ -901,7 +901,7 @@ The following operations are defined on mutable sequence types (where
   \lineiii{\var{s}.reverse()}
 	{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)}
+	{sort the items of \var{s} in place}{(6), (7), (8)}
 \end{tableiii}
 \indexiv{operations on}{mutable}{sequence}{types}
 \indexiii{operations on}{sequence}{types}
@@ -947,10 +947,18 @@ Notes:
   the first argument is considered smaller than, equal to, or larger
   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
+  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}