From 738ec90ca14154493a88fb38728537837a45eebf Mon Sep 17 00:00:00 2001
From: Raymond Hettinger <python@rcn.com>
Date: Sun, 29 Feb 2004 02:15:56 +0000
Subject: [PATCH] Improvements to collections.deque():
* Add doctests for the examples in the library reference.
* Add two methods, left() and right(), modeled after deques in C++ STL.
* Apply the new method to asynchat.py.
* Add comparison operators to make deques more substitutable for lists.
* Replace the LookupErrors with IndexErrors to more closely match lists.
---
Doc/lib/libcollections.tex | 29 ++++++---
Lib/asynchat.py | 6 +-
Lib/test/test_deque.py | 92 ++++++++++++++++++++++++++-
Modules/collectionsmodule.c | 120 +++++++++++++++++++++++++++++++++++-
4 files changed, 229 insertions(+), 18 deletions(-)
diff --git a/Doc/lib/libcollections.tex b/Doc/lib/libcollections.tex
index 0378ea5882d..27930957890 100644
--- a/Doc/lib/libcollections.tex
+++ b/Doc/lib/libcollections.tex
@@ -54,14 +54,24 @@ Deque objects support the following methods:
reversing the order of elements in the iterable argument.
\end{methoddesc}
+\begin{methoddesc}{left}{}
+ Return leftmost element from the deque.
+ If no elements are present, raises a \exception{IndexError}.
+\end{methoddesc}
+
\begin{methoddesc}{pop}{}
Remove and return an element from the right side of the deque.
- If no elements are present, raises a \exception{LookupError}.
+ If no elements are present, raises a \exception{IndexError}.
\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}.
+ If no elements are present, raises a \exception{IndexError}.
+\end{methoddesc}
+
+\begin{methoddesc}{right}{}
+ Return the rightmost element from the deque.
+ If no elements are present, raises a \exception{IndexError}.
\end{methoddesc}
\begin{methoddesc}{rotate}{n}
@@ -80,22 +90,27 @@ Example:
>>> 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()
-
-
+... 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']
+
+>>> d.left() # peek at leftmost item
+'g'
+>>> d.right() # peek at rightmost item
+'i'
>>> list(reversed(d)) # list the contents of a deque in reverse
['i', 'h', 'g']
>>> 'h' in d # search the deque
@@ -109,15 +124,15 @@ deque(['l', 'g', 'h', 'i', 'j', 'k'])
>>> d.rotate(-1) # left rotation
>>> d
deque(['g', 'h', 'i', 'j', 'k', 'l'])
+
>>> deque(reversed(d)) # make a new deque in reverse order
deque(['l', 'k', 'j', 'i', 'h', 'g'])
>>> d.clear() # empty the deque
>>> d.pop() # cannot pop from an empty deque
-
Traceback (most recent call last):
File "<pyshell#6>", line 1, in -toplevel-
d.pop()
-LookupError: pop from an empty deque
+IndexError: pop from an empty deque
>>> d.extendleft('abc') # extendleft() reverses the input order
>>> d
diff --git a/Lib/asynchat.py b/Lib/asynchat.py
index 4bfab302a1c..2c0bc3e9022 100644
--- a/Lib/asynchat.py
+++ b/Lib/asynchat.py
@@ -262,11 +262,7 @@ class fifo:
return self.list == []
def first (self):
- it = iter(self.list)
- try:
- return it.next()
- except StopIteration:
- raise IndexError
+ return self.list.left()
def push (self, data):
self.list.append(data)
diff --git a/Lib/test/test_deque.py b/Lib/test/test_deque.py
index f3bc59f8ce7..db9733e8eee 100644
--- a/Lib/test/test_deque.py
+++ b/Lib/test/test_deque.py
@@ -28,6 +28,23 @@ class TestBasic(unittest.TestCase):
self.assertEqual(right, range(150, 400))
self.assertEqual(list(d), range(50, 150))
+ def test_comparisons(self):
+ d = deque('xabc'); d.popleft()
+ for e in [d, deque('abc'), deque('ab'), deque(), list(d)]:
+ self.assertEqual(d==e, type(d)==type(e) and list(d)==list(e))
+ self.assertEqual(d!=e, not(type(d)==type(e) and list(d)==list(e)))
+
+ args = map(deque, ('', 'a', 'b', 'ab', 'ba', 'abc', 'xba', 'xabc', 'cba'))
+ for x in args:
+ for y in args:
+ self.assertEqual(x == y, list(x) == list(y), (x,y))
+ self.assertEqual(x != y, list(x) != list(y), (x,y))
+ self.assertEqual(x < y, list(x) < list(y), (x,y))
+ self.assertEqual(x <= y, list(x) <= list(y), (x,y))
+ self.assertEqual(x > y, list(x) > list(y), (x,y))
+ self.assertEqual(x >= y, list(x) >= list(y), (x,y))
+ self.assertEqual(cmp(x,y), cmp(list(x),list(y)), (x,y))
+
def test_extend(self):
d = deque('a')
self.assertRaises(TypeError, d.extend, 1)
@@ -40,6 +57,14 @@ class TestBasic(unittest.TestCase):
d.extendleft('bcd')
self.assertEqual(list(d), list(reversed('abcd')))
+ def test_leftright(self):
+ d = deque('superman')
+ self.assertEqual(d.left(), 's')
+ self.assertEqual(d.right(), 'n')
+ d = deque()
+ self.assertRaises(IndexError, d.left)
+ self.assertRaises(IndexError, d.right)
+
def test_rotate(self):
s = tuple('abcde')
n = len(s)
@@ -93,7 +118,7 @@ class TestBasic(unittest.TestCase):
self.assertEqual(len(d), 1)
d.pop()
self.assertEqual(len(d), 0)
- self.assertRaises(LookupError, d.pop)
+ self.assertRaises(IndexError, d.pop)
self.assertEqual(len(d), 0)
d.append('c')
self.assertEqual(len(d), 1)
@@ -104,8 +129,8 @@ class TestBasic(unittest.TestCase):
def test_underflow(self):
d = deque()
- self.assertRaises(LookupError, d.pop)
- self.assertRaises(LookupError, d.popleft)
+ self.assertRaises(IndexError, d.pop)
+ self.assertRaises(IndexError, d.popleft)
def test_clear(self):
d = deque(xrange(100))
@@ -374,6 +399,63 @@ class TestSubclass(unittest.TestCase):
#==============================================================================
+libreftest = """
+Example from the Library Reference: Doc/lib/libcollections.tex
+
+>>> 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']
+>>> d.left() # peek at leftmost item
+'g'
+>>> d.right() # peek at rightmost item
+'i'
+>>> list(reversed(d)) # list the contents of a deque in reverse
+['i', 'h', 'g']
+>>> 'h' in d # search the deque
+True
+>>> d.extend('jkl') # add multiple elements at once
+>>> d
+deque(['g', 'h', 'i', 'j', 'k', 'l'])
+>>> d.rotate(1) # right rotation
+>>> d
+deque(['l', 'g', 'h', 'i', 'j', 'k'])
+>>> d.rotate(-1) # left rotation
+>>> d
+deque(['g', 'h', 'i', 'j', 'k', 'l'])
+>>> deque(reversed(d)) # make a new deque in reverse order
+deque(['l', 'k', 'j', 'i', 'h', 'g'])
+>>> d.clear() # empty the deque
+>>> d.pop() # cannot pop from an empty deque
+Traceback (most recent call last):
+ File "<pyshell#6>", line 1, in -toplevel-
+ d.pop()
+IndexError: pop from an empty deque
+
+>>> d.extendleft('abc') # extendleft() reverses the input order
+>>> d
+deque(['c', 'b', 'a'])
+
+"""
+
+
+#==============================================================================
+
+__test__ = {'libreftest' : libreftest}
+
def test_main(verbose=None):
import sys
from test import test_sets
@@ -394,6 +476,10 @@ def test_main(verbose=None):
gc.collect()
counts[i] = sys.gettotalrefcount()
print counts
+
+ # doctests
+ from test import test_deque
+ test_support.run_doctest(test_deque, verbose)
if __name__ == "__main__":
test_main(verbose=True)
diff --git a/Modules/collectionsmodule.c b/Modules/collectionsmodule.c
index d534aa9f699..2b5cb105f05 100644
--- a/Modules/collectionsmodule.c
+++ b/Modules/collectionsmodule.c
@@ -34,6 +34,8 @@ typedef struct {
int len;
} dequeobject;
+PyTypeObject deque_type;
+
static PyObject *
deque_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
@@ -109,7 +111,7 @@ deque_pop(dequeobject *deque, PyObject *unused)
block *prevblock;
if (deque->len == 0) {
- PyErr_SetString(PyExc_LookupError, "pop from an empty deque");
+ PyErr_SetString(PyExc_IndexError, "pop from an empty deque");
return NULL;
}
item = deque->rightblock->data[deque->rightindex];
@@ -144,7 +146,7 @@ deque_popleft(dequeobject *deque, PyObject *unused)
block *prevblock;
if (deque->len == 0) {
- PyErr_SetString(PyExc_LookupError, "pop from an empty deque");
+ PyErr_SetString(PyExc_IndexError, "pop from an empty deque");
return NULL;
}
item = deque->leftblock->data[deque->leftindex];
@@ -174,6 +176,38 @@ deque_popleft(dequeobject *deque, PyObject *unused)
PyDoc_STRVAR(popleft_doc, "Remove and return the leftmost element.");
+static PyObject *
+deque_right(dequeobject *deque, PyObject *unused)
+{
+ PyObject *item;
+
+ if (deque->len == 0) {
+ PyErr_SetString(PyExc_IndexError, "deque is empty");
+ return NULL;
+ }
+ item = deque->rightblock->data[deque->rightindex];
+ Py_INCREF(item);
+ return item;
+}
+
+PyDoc_STRVAR(right_doc, "Return the rightmost element.");
+
+static PyObject *
+deque_left(dequeobject *deque, PyObject *unused)
+{
+ PyObject *item;
+
+ if (deque->len == 0) {
+ PyErr_SetString(PyExc_IndexError, "deque is empty");
+ return NULL;
+ }
+ item = deque->leftblock->data[deque->leftindex];
+ Py_INCREF(item);
+ return item;
+}
+
+PyDoc_STRVAR(left_doc, "Return the leftmost element.");
+
static PyObject *
deque_extend(dequeobject *deque, PyObject *iterable)
{
@@ -467,6 +501,82 @@ deque_tp_print(PyObject *deque, FILE *fp, int flags)
return 0;
}
+static PyObject *
+deque_richcompare(PyObject *v, PyObject *w, int op)
+{
+ PyObject *it1=NULL, *it2=NULL, *x, *y;
+ int i, b, vs, ws, minlen, cmp=-1;
+
+ if (v->ob_type != &deque_type || w->ob_type != &deque_type) {
+ Py_INCREF(Py_NotImplemented);
+ return Py_NotImplemented;
+ }
+
+ /* Shortcuts */
+ vs = ((dequeobject *)v)->len;
+ ws = ((dequeobject *)w)->len;
+ if (op == Py_EQ) {
+ if (v == w)
+ Py_RETURN_TRUE;
+ if (vs != ws)
+ Py_RETURN_FALSE;
+ }
+ if (op == Py_NE) {
+ if (v == w)
+ Py_RETURN_FALSE;
+ if (vs != ws)
+ Py_RETURN_TRUE;
+ }
+
+ /* Search for the first index where items are different */
+ it1 = PyObject_GetIter(v);
+ if (it1 == NULL)
+ goto done;
+ it2 = PyObject_GetIter(w);
+ if (it2 == NULL)
+ goto done;
+ minlen = (vs < ws) ? vs : ws;
+ for (i=0 ; i < minlen ; i++) {
+ x = PyIter_Next(it1);
+ if (x == NULL)
+ goto done;
+ y = PyIter_Next(it2);
+ if (y == NULL) {
+ Py_DECREF(x);
+ goto done;
+ }
+ b = PyObject_RichCompareBool(x, y, Py_EQ);
+ if (b == 0) {
+ cmp = PyObject_RichCompareBool(x, y, op);
+ Py_DECREF(x);
+ Py_DECREF(y);
+ goto done;
+ }
+ Py_DECREF(x);
+ Py_DECREF(y);
+ if (b == -1)
+ goto done;
+ }
+ /* Elements are equal through minlen. The longest input is the greatest */
+ switch (op) {
+ case Py_LT: cmp = vs < ws; break;
+ case Py_LE: cmp = vs <= ws; break;
+ case Py_EQ: cmp = vs == ws; break;
+ case Py_NE: cmp = vs != ws; break;
+ case Py_GT: cmp = vs > ws; break;
+ case Py_GE: cmp = vs >= ws; break;
+ }
+
+done:
+ Py_XDECREF(it1);
+ Py_XDECREF(it2);
+ if (cmp == 1)
+ Py_RETURN_TRUE;
+ if (cmp == 0)
+ Py_RETURN_FALSE;
+ return NULL;
+}
+
static int
deque_init(dequeobject *deque, PyObject *args, PyObject *kwds)
{
@@ -509,6 +619,8 @@ static PyMethodDef deque_methods[] = {
METH_O, extend_doc},
{"extendleft", (PyCFunction)deque_extendleft,
METH_O, extendleft_doc},
+ {"left", (PyCFunction)deque_left,
+ METH_NOARGS, left_doc},
{"pop", (PyCFunction)deque_pop,
METH_NOARGS, pop_doc},
{"popleft", (PyCFunction)deque_popleft,
@@ -517,6 +629,8 @@ static PyMethodDef deque_methods[] = {
METH_NOARGS, reduce_doc},
{"__reversed__", (PyCFunction)deque_reviter,
METH_NOARGS, reversed_doc},
+ {"right", (PyCFunction)deque_right,
+ METH_NOARGS, right_doc},
{"rotate", (PyCFunction)deque_rotate,
METH_VARARGS, rotate_doc},
{NULL, NULL} /* sentinel */
@@ -553,7 +667,7 @@ PyTypeObject deque_type = {
deque_doc, /* tp_doc */
(traverseproc)set_traverse, /* tp_traverse */
(inquiry)deque_clear, /* tp_clear */
- 0, /* tp_richcompare */
+ (richcmpfunc)deque_richcompare, /* tp_richcompare */
0, /* tp_weaklistoffset*/
(getiterfunc)deque_iter, /* tp_iter */
0, /* tp_iternext */
--
2.30.9