@@ -61,45 +61,16 @@ The following functions are provided:
61
61
62
62
Pop and return the smallest item from the *heap *, and also push the new *item *.
63
63
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::
68
64
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 *.
71
69
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.
103
74
104
75
105
76
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
139
110
functions.
140
111
141
112
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
+
142
142
Priority Queue Implementation Notes
143
143
-----------------------------------
144
144
0 commit comments