From 28224f897a1849dd616ad82538bdda45f3351d42 Mon Sep 17 00:00:00 2001
From: Raymond Hettinger <python@rcn.com>
Date: Sun, 20 Jun 2004 09:07:53 +0000
Subject: Improve the documented advice on how to best use heapq.heapreplace().

---
 Doc/lib/libheapq.tex   | 6 +++++-
 Lib/heapq.py           | 4 +++-
 Modules/_heapqmodule.c | 3 ++-
 3 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/Doc/lib/libheapq.tex b/Doc/lib/libheapq.tex
index ffcafcd..edacf79 100644
--- 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 09f996a..9fb4e70 100644
--- 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 21df796..13e6a3d 100644
--- 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)
-- 
cgit v0.12