summaryrefslogtreecommitdiffstats
path: root/Doc/library
diff options
context:
space:
mode:
authorEli Bendersky <eliben@gmail.com>2015-03-15 03:17:38 (GMT)
committerEli Bendersky <eliben@gmail.com>2015-03-15 03:17:38 (GMT)
commita84099bcc5cf9bba4bb6e14a296202a4fca5f106 (patch)
treed0c8c10ab099764a5ba43cc8f63a412cfe820a82 /Doc/library
parent7aaa85932cf576470f2befe8257b29039b2cb411 (diff)
parent39430daa3b82a121b80633436170d0e0757f0fac (diff)
downloadcpython-a84099bcc5cf9bba4bb6e14a296202a4fca5f106.zip
cpython-a84099bcc5cf9bba4bb6e14a296202a4fca5f106.tar.gz
cpython-a84099bcc5cf9bba4bb6e14a296202a4fca5f106.tar.bz2
Issue #23549: Clarify confusion in heapq doc - accessing the mininmal element
Merge 3.4 The current documentation only mentions heap[0] as the smallest element in the beginning, and not in any of the methods' docs. There's no method to access the minimal element without popping it, and the documentation of nsmallest is confusing because it may suggest that min() is the way to go for n==1.
Diffstat (limited to 'Doc/library')
-rw-r--r--Doc/library/heapq.rst6
1 files changed, 4 insertions, 2 deletions
diff --git a/Doc/library/heapq.rst b/Doc/library/heapq.rst
index 9682b59..9fbbcc6 100644
--- a/Doc/library/heapq.rst
+++ b/Doc/library/heapq.rst
@@ -47,7 +47,8 @@ The following functions are provided:
.. function:: heappop(heap)
Pop and return the smallest item from the *heap*, maintaining the heap
- invariant. If the heap is empty, :exc:`IndexError` is raised.
+ invariant. If the heap is empty, :exc:`IndexError` is raised. To access the
+ smallest item without popping it, use ``heap[0]``.
.. function:: heappushpop(heap, item)
@@ -124,7 +125,8 @@ The module also offers three general purpose functions based on heaps.
The latter two functions perform best for smaller values of *n*. For larger
values, it is more efficient to use the :func:`sorted` function. Also, when
``n==1``, it is more efficient to use the built-in :func:`min` and :func:`max`
-functions.
+functions. If repeated usage of these functions is required, consider turning
+the iterable into an actual heap.
Basic Examples