Document new heapreplace() function.

1 files changed, 9 insertions, 0 deletions

diff --git a/Doc/lib/libheapq.tex b/Doc/lib/libheapq.tex
index d1aaaae..38c38d8 100644
--- a/Doc/lib/libheapq.tex
+++ b/Doc/lib/libheapq.tex
@@ -52,6 +52,15 @@ heap invariant.
 Transform list \var{x} into a heap, in-place, in linear time.
 \end{funcdesc}
 
+\begin{funcdesc}{heapreplace}{heap, item}
+Pop and return the smallest item from the \var{heap}, and also push
+the new \var{item}.  The heap size doesn't change.
+This is more efficient than \function{heappop()} followed
+by  \function{heappush()}, and can be more appropriate when using
+a fixed-size heap.  Note that the value returned may be larger
+than \var{item}!  That constrains reasonable uses of this routine.
+\end{funcdesc}
+
 Example of use:
 
 \begin{verbatim}