Improve the documented advice on how to best use heapq.heapreplace().

diff --git a/Doc/lib/libheapq.tex b/Doc/lib/libheapq.tex
index ffcafcd2a5f19f550bab6c89fe9ac19ddc49e6e7..edacf791587af4cfc6f8d47fcd57092a7dd11df1 100644 (file)
--- a/Doc/lib/libheapq.tex
+++ b/Doc/lib/libheapq.tex
@@ -59,7 +59,11 @@ If the heap is empty, \exception{IndexError} is raised.
 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.
+than \var{item}!  That constrains reasonable uses of this routine
+unless written as part of a larger expression:
+\begin{verbatim}
+        result = item <= heap[0] and item  or  heapreplace(heap, item)
+\end{verbatim}
 \end{funcdesc}
 
 Example of use:

diff --git a/Lib/heapq.py b/Lib/heapq.py
index 09f996aff80be633d60a0e00e553e8b288fc69cf..9fb4e70824028b5d81a5ec5c02426c012cec0884 100644 (file)
--- a/Lib/heapq.py
+++ b/Lib/heapq.py
@@ -154,7 +154,9 @@ def heapreplace(heap, item):
     This is more efficient than heappop() followed by heappush(), and can be
     more appropriate when using a fixed-size heap.  Note that the value
     returned may be larger than item!  That constrains reasonable uses of
-    this routine.
+    this routine unless written as part of a larger expression:
+
+        result = item <= heap[0] and item  or  heapreplace(heap, item)
     """
     returnitem = heap[0]    # raises appropriate IndexError if heap is empty
     heap[0] = item

diff --git a/Modules/_heapqmodule.c b/Modules/_heapqmodule.c
index 21df796095b8347f9c15ca389e391b68ba3726d1..13e6a3d6040074f4ffe42d3fc8ec0d98b8f4fa76 100644 (file)
--- a/Modules/_heapqmodule.c
+++ b/Modules/_heapqmodule.c
@@ -186,7 +186,8 @@ PyDoc_STRVAR(heapreplace_doc,
 This is more efficient than heappop() followed by heappush(), and can be\n\
 more appropriate when using a fixed-size heap.  Note that the value\n\
 returned may be larger than item!  That constrains reasonable uses of\n\
-this routine.\n");
+this routine unless written as part of a larger expression:\n\n\
+    result = item <= heap[0] and item  or  heapreplace(heap, item)\n");
 
 static PyObject *
 heapify(PyObject *self, PyObject *heap)