Skip to content

Commit 6f80b4c

Browse files
committed
Cleanup heapq docs
1 parent c73b909 commit 6f80b4c

File tree

1 file changed

+37
-37
lines changed

1 file changed

+37
-37
lines changed

Doc/library/heapq.rst

+37-37
Original file line numberDiff line numberDiff line change
@@ -61,45 +61,16 @@ The following functions are provided:
6161

6262
Pop and return the smallest item from the *heap*, and also push the new *item*.
6363
The heap size doesn't change. If the heap is empty, :exc:`IndexError` is raised.
64-
This is more efficient than :func:`heappop` followed by :func:`heappush`, and
65-
can be more appropriate when using a fixed-size heap. Note that the value
66-
returned may be larger than *item*! That constrains reasonable uses of this
67-
routine unless written as part of a conditional replacement::
6864

69-
if item > heap[0]:
70-
item = heapreplace(heap, item)
65+
This one step operation is more efficient than a :func:`heappop` followed by
66+
:func:`heappush` and can be more appropriate when using a fixed-size heap.
67+
The pop/push combination always returns an element from the heap and replaces
68+
it with *item*.
7169

72-
Example of use:
73-
74-
>>> from heapq import heappush, heappop
75-
>>> heap = []
76-
>>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0]
77-
>>> for item in data:
78-
... heappush(heap, item)
79-
...
80-
>>> ordered = []
81-
>>> while heap:
82-
... ordered.append(heappop(heap))
83-
...
84-
>>> ordered
85-
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
86-
>>> data.sort()
87-
>>> data == ordered
88-
True
89-
90-
Using a heap to insert items at the correct place in a priority queue:
91-
92-
>>> heap = []
93-
>>> data = [(1, 'J'), (4, 'N'), (3, 'H'), (2, 'O')]
94-
>>> for item in data:
95-
... heappush(heap, item)
96-
...
97-
>>> while heap:
98-
... print(heappop(heap)[1])
99-
J
100-
O
101-
H
102-
N
70+
The value returned may be larger than the *item* added. If that isn't
71+
desired, consider using :func:`heappushpop` instead. Its push/pop
72+
combination returns the smaller of the two values, leaving the larger value
73+
on the heap.
10374

10475

10576
The module also offers three general purpose functions based on heaps.
@@ -139,6 +110,35 @@ values, it is more efficient to use the :func:`sorted` function. Also, when
139110
functions.
140111

141112

113+
Basic Examples
114+
--------------
115+
116+
A `heapsort <http://en.wikipedia.org/wiki/Heapsort>`_ can be implemented by
117+
pushing all values onto a heap and then popping off the smallest values one at a
118+
time::
119+
120+
>>> def heapsort(iterable):
121+
... 'Equivalent to sorted(iterable)'
122+
... h = []
123+
... for value in iterable:
124+
... heappush(h, value)
125+
... return [heappop(h) for i in range(len(h))]
126+
...
127+
>>> heapsort([1, 3, 5, 7, 9, 2, 4, 6, 8, 0])
128+
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
129+
130+
Heap elements can be tuples. This is useful for assigning comparison values
131+
(such as task priorities) alongside the main record being tracked::
132+
133+
>>> h = []
134+
>>> heappush(h, (5, 'write code'))
135+
>>> heappush(h, (7, 'release product'))
136+
>>> heappush(h, (1, 'write spec'))
137+
>>> heappush(h, (3, 'create tests'))
138+
>>> heappop(h)
139+
(1, 'write spec')
140+
141+
142142
Priority Queue Implementation Notes
143143
-----------------------------------
144144

0 commit comments

Comments
 (0)