- added example of using a comparison function with list.sort(), and

  explained the construction of a [(key, value), ...] list as an
  alternative
- note that support for cmpfunc=None was added in 2.3

1 files changed, 25 insertions, 3 deletions

diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex
index 1a7b505..469b9d3 100644
--- a/Doc/lib/libstdtypes.tex
+++ b/Doc/lib/libstdtypes.tex
@@ -999,12 +999,34 @@ Notes:
   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; 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
+  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