2004-01-29 03:27:45 -04:00
|
|
|
\section{\module{collections} ---
|
|
|
|
High-performance datatypes}
|
|
|
|
|
|
|
|
\declaremodule{standard}{collections}
|
|
|
|
\modulesynopsis{High-performance datatypes}
|
|
|
|
\moduleauthor{Raymond Hettinger}{python@rcn.com}
|
|
|
|
\sectionauthor{Raymond Hettinger}{python@rcn.com}
|
|
|
|
\versionadded{2.4}
|
|
|
|
|
|
|
|
|
|
|
|
This module implements high-performance datatypes. Currently, the
|
|
|
|
only datatype is a deque. Future additions may include B-trees
|
|
|
|
and Fibonacci heaps.
|
|
|
|
|
|
|
|
\begin{funcdesc}{deque}{\optional{iterable}}
|
|
|
|
Returns a new deque objected initialized left-to-right (using
|
|
|
|
\method{append()}) with data from \var{iterable}. If \var{iterable}
|
|
|
|
is not specified, the new deque is empty.
|
|
|
|
|
|
|
|
Deques are a generalization of stacks and queues. They support
|
|
|
|
thread-safe, memory efficient appends and pops from either side of the
|
|
|
|
deque with approximately the same performance in either direction.
|
|
|
|
\versionadded{2.4}
|
|
|
|
\end{funcdesc}
|
|
|
|
|
|
|
|
Deque objects support the following methods:
|
|
|
|
|
|
|
|
\begin{methoddesc}{append}{x}
|
|
|
|
Add \var{x} to the right side of the deque.
|
|
|
|
\end{methoddesc}
|
|
|
|
|
|
|
|
\begin{methoddesc}{appendleft}{x}
|
|
|
|
Add \var{x} to the left side of the deque.
|
|
|
|
\end{methoddesc}
|
|
|
|
|
|
|
|
\begin{methoddesc}{clear}{}
|
|
|
|
Remove all elements from the deque leaving it with length 0.
|
|
|
|
\end{methoddesc}
|
|
|
|
|
2004-02-06 15:04:56 -04:00
|
|
|
\begin{methoddesc}{extend}{iterable}
|
|
|
|
Extend the right side of the deque by appending elements from
|
|
|
|
the iterable argument.
|
|
|
|
\end{methoddesc}
|
|
|
|
|
|
|
|
\begin{methoddesc}{extendleft}{iterable}
|
|
|
|
Extend the left side of the deque by appending elements from
|
|
|
|
\var{iterable}. Note, the series of left appends results in
|
|
|
|
reversing the order of elements in the iterable argument.
|
|
|
|
\end{methoddesc}
|
|
|
|
|
2004-01-29 03:27:45 -04:00
|
|
|
\begin{methoddesc}{pop}{}
|
|
|
|
Remove and return an element from the right side of the deque.
|
|
|
|
If no elements are present, raises a \exception{LookupError}.
|
|
|
|
\end{methoddesc}
|
|
|
|
|
|
|
|
\begin{methoddesc}{popleft}{}
|
|
|
|
Remove and return an element from the left side of the deque.
|
|
|
|
If no elements are present, raises a \exception{LookupError}.
|
|
|
|
\end{methoddesc}
|
|
|
|
|
|
|
|
In addition to the above, deques support iteration, membership testing
|
|
|
|
using the \keyword{in} operator, \samp{len(d)}, \samp{copy.copy(d)},
|
2004-02-06 22:45:22 -04:00
|
|
|
\samp{copy.deepcopy(d)}, \samp{reversed(d)} and pickling.
|
2004-01-29 03:27:45 -04:00
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
>>> from collections import deque
|
|
|
|
>>> d = deque('ghi') # make a new deque with three items
|
|
|
|
>>> for elem in d: # iterate over the deque's elements
|
|
|
|
print elem.upper()
|
|
|
|
|
|
|
|
|
|
|
|
G
|
|
|
|
H
|
|
|
|
I
|
|
|
|
>>> d.append('j') # add a new entry to the right side
|
|
|
|
>>> d.appendleft('f') # add a new entry to the left side
|
|
|
|
>>> d # show the representation of the deque
|
|
|
|
deque(['f', 'g', 'h', 'i', 'j'])
|
|
|
|
>>> d.pop() # return and remove the rightmost item
|
|
|
|
'j'
|
|
|
|
>>> d.popleft() # return and remove the leftmost item
|
|
|
|
'f'
|
|
|
|
>>> list(d) # list the contents of the deque
|
|
|
|
['g', 'h', 'i']
|
2004-02-06 22:45:22 -04:00
|
|
|
>>> list(reversed(d)) # list the contents of a deque in reverse
|
|
|
|
['i', 'h', 'g']
|
2004-01-29 03:27:45 -04:00
|
|
|
>>> 'h' in d # search the deque
|
|
|
|
True
|
2004-02-06 15:04:56 -04:00
|
|
|
>>> d.extend('jkl') # extend() will append many elements at once
|
2004-01-29 03:27:45 -04:00
|
|
|
>>> d
|
|
|
|
deque(['g', 'h', 'i', 'j', 'k', 'l'])
|
|
|
|
>>> d.clear() # empty the deque
|
2004-02-06 15:04:56 -04:00
|
|
|
>>> d.pop() # cannot pop from an empty deque
|
2004-01-29 03:27:45 -04:00
|
|
|
|
|
|
|
Traceback (most recent call last):
|
|
|
|
File "<pyshell#6>", line 1, in -toplevel-
|
|
|
|
d.pop()
|
|
|
|
LookupError: pop from an empty deque
|
2004-02-06 15:04:56 -04:00
|
|
|
|
|
|
|
>>> d.extendleft('abc') # extendleft() reverses the element order
|
|
|
|
>>> d
|
|
|
|
deque(['c', 'b', 'a'])
|
|
|
|
|
2004-01-29 03:27:45 -04:00
|
|
|
\end{verbatim}
|