SF patch #969791: Add nlargest() and nsmallest() to heapq.

2 files changed, 28 insertions, 1 deletions

diff --git a/Doc/lib/libheapq.tex b/Doc/lib/libheapq.tex
index 38f9b1a..4585058 100644
--- a/Doc/lib/libheapq.tex
+++ b/Doc/lib/libheapq.tex
@@ -83,6 +83,30 @@ True
 >>>
 \end{verbatim}
 
+The module also offers two general purpose functions based on heaps.
+
+\begin{funcdesc}{nlargest}{iterable, n}
+Return a list with the \var{n} largest elements from the dataset defined
+by \var{iterable}. Equivalent to:  \code{sorted(iterable, reverse=True)[:n]}
+\versionadded{2.4}              
+\end{funcdesc}
+
+\begin{funcdesc}{nsmallest}{iterable, n}
+Return a list with the \var{n} smallest elements from the dataset defined
+by \var{iterable}. Equivalent to:  \code{sorted(iterable)[:n]}
+\versionadded{2.4}              
+\end{funcdesc}
+
+Though the above functions appear symmetrical, they each have different
+speed and space requirements.  In particular, \function{nsmallest()}
+operates on a full copy of the dataset.  In contrast, \function{nlargest()}
+only requires storage space for \var{n} elements.
+
+Both functions perform best for smaller values of \var{n}.  For larger
+values, it is more efficient to use the \function{sorted()} function.  Also,
+when \code{n==1}, it is more efficient to use the builtin \function{min()}
+and \function{max()} functions.
+
 
 \subsection{Theory}
 
diff --git a/Doc/whatsnew/whatsnew24.tex b/Doc/whatsnew/whatsnew24.tex
index 3f4151f..4a67916 100644
--- a/Doc/whatsnew/whatsnew24.tex
+++ b/Doc/whatsnew/whatsnew24.tex
@@ -449,7 +449,10 @@ improved performance:  \module{Queue}, \module{mutex}, \module{shlex}
 
 \item The \module{heapq} module has been converted to C.  The resulting
    tenfold improvement in speed makes the module suitable for handling
-   high volumes of data.
+   high volumes of data.  In addition, the module has two new functions
+   \function{nlargest()} and \function{nsmallest()} that use heaps to
+   find the largest or smallest n values in a dataset without the
+   expense of a full sort.
 
 \item The \module{imaplib} module now supports IMAP's THREAD command.
 (Contributed by Yves Dionne.)