rest25/library/heapq.rst => rest262/library/heapq.rst
n1- 
2:mod:`heapq` --- Heap queue algorithm
3=====================================
4
5.. module:: heapq
6   :synopsis: Heap queue algorithm (a.k.a. priority queue).
7.. moduleauthor:: Kevin O'Connor
8.. sectionauthor:: Guido van Rossum <guido@python.org>
9.. sectionauthor:: François Pinard
n10- 
11- 
12-.. % Theoretical explanation:
13
14.. versionadded:: 2.3
15
16This module provides an implementation of the heap queue algorithm, also known
17as the priority queue algorithm.
18
19Heaps are arrays for which ``heap[k] <= heap[2*k+1]`` and ``heap[k] <=
20heap[2*k+2]`` for all *k*, counting elements from zero.  For the sake of
44   Push the value *item* onto the *heap*, maintaining the heap invariant.
45
46
47.. function:: heappop(heap)
48
49   Pop and return the smallest item from the *heap*, maintaining the heap
50   invariant.  If the heap is empty, :exc:`IndexError` is raised.
51
n48+.. function:: heappushpop(heap, item)
49+ 
50+   Push *item* on the heap, then pop and return the smallest item from the
51+   *heap*.  The combined action runs more efficiently than :func:`heappush`
52+   followed by a separate call to :func:`heappop`.
53+ 
54+   .. versionadded:: 2.6
52
53.. function:: heapify(x)
54
55   Transform list *x* into a heap, in-place, in linear time.
56
57
58.. function:: heapreplace(heap, item)
59
62   This is more efficient than :func:`heappop` followed by  :func:`heappush`, and
63   can be more appropriate when using a fixed-size heap.  Note that the value
64   returned may be larger than *item*!  That constrains reasonable uses of this
65   routine unless written as part of a conditional replacement::
66
67      if item > heap[0]:
68          item = heapreplace(heap, item)
69
n70-Example of use::
n73+Example of use:
71
72   >>> from heapq import heappush, heappop
73   >>> heap = []
74   >>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0]
75   >>> for item in data:
76   ...     heappush(heap, item)
77   ...
n78-   >>> sorted = []
n81+   >>> ordered = []
79   >>> while heap:
n80-   ...     sorted.append(heappop(heap))
n83+   ...     ordered.append(heappop(heap))
81   ...
n82-   >>> print sorted
n85+   >>> print ordered
83   [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
84   >>> data.sort()
n85-   >>> print data == sorted
n88+   >>> print data == ordered
86   True
n87-   >>>
88
n91+Using a heap to insert items at the correct place in a priority queue:
92+ 
93+   >>> heap = []
94+   >>> data = [(1, 'J'), (4, 'N'), (3, 'H'), (2, 'O')]
95+   >>> for item in data:
96+   ...     heappush(heap, item)
97+   ...
98+   >>> while heap:
99+   ...     print heappop(heap)[1]
100+   J
101+   O
102+   H
103+   N
104+ 
105+ 
89-The module also offers two general purpose functions based on heaps.
106+The module also offers three general purpose functions based on heaps.
107+ 
108+ 
109+.. function:: merge(*iterables)
110+ 
111+   Merge multiple sorted inputs into a single sorted output (for example, merge
112+   timestamped entries from multiple log files).  Returns an :term:`iterator`
113+   over the sorted values.
114+ 
115+   Similar to ``sorted(itertools.chain(*iterables))`` but returns an iterable, does
116+   not pull the data into memory all at once, and assumes that each of the input
117+   streams is already sorted (smallest to largest).
118+ 
119+   .. versionadded:: 2.6
90
91
92.. function:: nlargest(n, iterable[, key])
93
94   Return a list with the *n* largest elements from the dataset defined by
95   *iterable*.  *key*, if provided, specifies a function of one argument that is
96   used to extract a comparison key from each element in the iterable:
97   ``key=str.lower`` Equivalent to:  ``sorted(iterable, key=key,
110   used to extract a comparison key from each element in the iterable:
111   ``key=str.lower`` Equivalent to:  ``sorted(iterable, key=key)[:n]``
112
113   .. versionadded:: 2.4
114
115   .. versionchanged:: 2.5
116      Added the optional *key* argument.
117
t118-Both functions perform best for smaller values of *n*.  For larger values, it is
t148+The latter two functions perform best for smaller values of *n*.  For larger
119-more efficient to use the :func:`sorted` function.  Also, when ``n==1``, it is
149+values, it is more efficient to use the :func:`sorted` function.  Also, when
120-more efficient to use the builtin :func:`min` and :func:`max` functions.
150+``n==1``, it is more efficient to use the builtin :func:`min` and :func:`max`
151+functions.
121
122
123Theory
124------
125
126(This explanation is due to François Pinard.  The Python code for this module
127was contributed by Kevin O'Connor.)
128
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op