adafruit · dhalbert · Mar 26, 2024 · Mar 20, 2024 · Mar 20, 2024 · Mar 20, 2024
diff --git a/docs/library/collections.rst b/docs/library/collections.rst
@@ -14,33 +14,58 @@ hold/accumulate various objects.
 Classes
 -------
 
-.. class:: deque(iterable, maxlen[, flags])
+.. class:: deque(iterable, maxlen[, flag])
 
-    Deques (double-ended queues) are a list-like container that support O(1)
-    appends and pops from either side of the deque.  New deques are created
-    using the following arguments:
+    Deques (pronounced "deck" and short for "double-ended queue") are fixed length
+    list-like containers that support O(1) appends and pops from either side of the
+    deque.  New deques are created using the following arguments:
 
-        - *iterable* must be the empty tuple, and the new deque is created empty.
+        - *iterable* must be specified as an empty or non-empty iterable.
+          If the iterable is empty, the new deque is created empty.  If the
+          iterable is not empty, the new deque is created with the items
+          from the iterable.
 
         - *maxlen* must be specified and the deque will be bounded to this
           maximum length.  Once the deque is full, any new items added will
           discard items from the opposite end.
 
-        - The optional *flags* can be 1 to check for overflow when adding items.
+        - *flag* is optional and can be set to 1 to check for overflow when
+          adding items.  If the deque is full and overflow checking is enabled,
+          an IndexError will be raised when adding items.
 
-    As well as supporting ``bool`` and ``len``, deque objects have the following
-    methods:
+    Deque objects have the following methods:
 
     .. method:: deque.append(x)
 
         Add *x* to the right side of the deque.
         Raises IndexError if overflow checking is enabled and there is no more room left.
 
+    .. method:: deque.appendleft(x)
+
+        Add *x* to the left side of the deque.
+        Raises IndexError if overflow checking is enabled and there is no more room left.
+
+    .. method:: deque.pop()
+
+        Remove and return an item from the right side of the deque.
+        Raises IndexError if no items are present.
+
     .. method:: deque.popleft()
 
         Remove and return an item from the left side of the deque.
         Raises IndexError if no items are present.
 
+    .. method:: deque.extend(iterable)
+
+        Extend the right side of the deque by appending items from the *iterable* argument.
+        Raises IndexError if overflow checking is enabled and there is no more room left
+        for all of the items in *iterable*.
+
+    In addition to the above, deques support iteration, ``bool``, ``len(d)``, ``reversed(d)``,
+    membership testing with the ``in`` operator, and subscript references like ``d[0]``.
+    Note: Indexed access is O(1) at both ends but slows to O(n) in the middle of the deque,
+    so for fast random access use a ``list`` instead.
+
 .. function:: namedtuple(name, fields)
 
     This is factory function to create a new namedtuple type with a specific

diff --git a/py/circuitpy_mpconfig.h b/py/circuitpy_mpconfig.h
@@ -259,6 +259,8 @@ typedef long mp_off_t;
 #endif
 #ifndef MICROPY_PY_COLLECTIONS_DEQUE
 #define MICROPY_PY_COLLECTIONS_DEQUE          (CIRCUITPY_FULL_BUILD)
+#define MICROPY_PY_COLLECTIONS_DEQUE_ITER     (CIRCUITPY_FULL_BUILD)
+#define MICROPY_PY_COLLECTIONS_DEQUE_SUBSCR   (CIRCUITPY_FULL_BUILD)
 #endif
 #define MICROPY_PY_RE_MATCH_GROUPS           (CIRCUITPY_RE)
 #define MICROPY_PY_RE_MATCH_SPAN_START_END   (CIRCUITPY_RE)

diff --git a/py/mpconfig.h b/py/mpconfig.h
@@ -1324,6 +1324,16 @@ typedef double mp_float_t;
 #define MICROPY_PY_COLLECTIONS_DEQUE (MICROPY_CONFIG_ROM_LEVEL_AT_LEAST_EXTRA_FEATURES)
 #endif
 
+// Whether "collections.deque" supports iteration
+#ifndef MICROPY_PY_COLLECTIONS_DEQUE_ITER
+#define MICROPY_PY_COLLECTIONS_DEQUE_ITER (MICROPY_CONFIG_ROM_LEVEL_AT_LEAST_EXTRA_FEATURES)
+#endif
+
+// Whether "collections.deque" supports subscription
+#ifndef MICROPY_PY_COLLECTIONS_DEQUE_SUBSCR
+#define MICROPY_PY_COLLECTIONS_DEQUE_SUBSCR (MICROPY_CONFIG_ROM_LEVEL_AT_LEAST_EXTRA_FEATURES)
+#endif
+
 // Whether to provide "collections.OrderedDict" type
 #ifndef MICROPY_PY_COLLECTIONS_ORDEREDDICT
 #define MICROPY_PY_COLLECTIONS_ORDEREDDICT (MICROPY_CONFIG_ROM_LEVEL_AT_LEAST_EXTRA_FEATURES)

diff --git a/py/objdeque.c b/py/objdeque.c
@@ -25,13 +25,11 @@
  */
 
 #include <unistd.h> // for ssize_t
-#include <string.h>
-
-#include "py/mpconfig.h"
-#if MICROPY_PY_COLLECTIONS_DEQUE
 
 #include "py/runtime.h"
 
+#if MICROPY_PY_COLLECTIONS_DEQUE
+
 typedef struct _mp_obj_deque_t {
     mp_obj_base_t base;
     size_t alloc;
@@ -42,14 +40,14 @@ typedef struct _mp_obj_deque_t {
     #define FLAG_CHECK_OVERFLOW 1
 } mp_obj_deque_t;
 
-STATIC mp_obj_t deque_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) {
-    mp_arg_check_num(n_args, n_kw, 2, 3, false);
+static mp_obj_t mp_obj_deque_append(mp_obj_t self_in, mp_obj_t arg);
+static mp_obj_t mp_obj_deque_extend(mp_obj_t self_in, mp_obj_t arg_in);
+#if MICROPY_PY_COLLECTIONS_DEQUE_ITER
+static mp_obj_t mp_obj_new_deque_it(mp_obj_t deque, mp_obj_iter_buf_t *iter_buf);
+#endif
 
-    /* Initialization from existing sequence is not supported, so an empty
-       tuple must be passed as such. */
-    if (args[0] != mp_const_empty_tuple) {
-        mp_raise_ValueError(NULL);
-    }
+static mp_obj_t deque_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) {
+    mp_arg_check_num(n_args, n_kw, 2, 3, false);
 
     // Protect against -1 leading to zero-length allocation and bad array access
     mp_int_t maxlen = mp_obj_get_int(args[1]);
@@ -66,21 +64,27 @@ STATIC mp_obj_t deque_make_new(const mp_obj_type_t *type, size_t n_args, size_t
         o->flags = mp_obj_get_int(args[2]);
     }
 
+    mp_obj_deque_extend(MP_OBJ_FROM_PTR(o), args[0]);
+
     return MP_OBJ_FROM_PTR(o);
 }
 
-STATIC mp_obj_t deque_unary_op(mp_unary_op_t op, mp_obj_t self_in) {
+static size_t deque_len(mp_obj_deque_t *self) {
+    ssize_t len = self->i_put - self->i_get;
+    if (len < 0) {
+        len += self->alloc;
+    }
+    return len;
+}
+
+static mp_obj_t deque_unary_op(mp_unary_op_t op, mp_obj_t self_in) {
     mp_obj_deque_t *self = MP_OBJ_TO_PTR(self_in);
     switch (op) {
         case MP_UNARY_OP_BOOL:
             return mp_obj_new_bool(self->i_get != self->i_put);
-        case MP_UNARY_OP_LEN: {
-            ssize_t len = self->i_put - self->i_get;
-            if (len < 0) {
-                len += self->alloc;
-            }
-            return MP_OBJ_NEW_SMALL_INT(len);
-        }
+        case MP_UNARY_OP_LEN:
+            return MP_OBJ_NEW_SMALL_INT(deque_len(self));
+
         #if MICROPY_PY_SYS_GETSIZEOF
         case MP_UNARY_OP_SIZEOF: {
             size_t sz = sizeof(*self) + sizeof(mp_obj_t) * self->alloc;
@@ -92,7 +96,7 @@ STATIC mp_obj_t deque_unary_op(mp_unary_op_t op, mp_obj_t self_in) {
     }
 }
 
-STATIC mp_obj_t mp_obj_deque_append(mp_obj_t self_in, mp_obj_t arg) {
+static mp_obj_t mp_obj_deque_append(mp_obj_t self_in, mp_obj_t arg) {
     mp_obj_deque_t *self = MP_OBJ_TO_PTR(self_in);
 
     size_t new_i_put = self->i_put + 1;
@@ -115,9 +119,48 @@ STATIC mp_obj_t mp_obj_deque_append(mp_obj_t self_in, mp_obj_t arg) {
 
     return mp_const_none;
 }
-STATIC MP_DEFINE_CONST_FUN_OBJ_2(deque_append_obj, mp_obj_deque_append);
+static MP_DEFINE_CONST_FUN_OBJ_2(deque_append_obj, mp_obj_deque_append);
+
+static mp_obj_t mp_obj_deque_appendleft(mp_obj_t self_in, mp_obj_t arg) {
+    mp_obj_deque_t *self = MP_OBJ_TO_PTR(self_in);
+
+    size_t new_i_get = self->i_get - 1;
+    if (self->i_get == 0) {
+        new_i_get = self->alloc - 1;
+    }
+
+    if (self->flags & FLAG_CHECK_OVERFLOW && new_i_get == self->i_put) {
+        mp_raise_msg(&mp_type_IndexError, MP_ERROR_TEXT("full"));
+    }
+
+    self->i_get = new_i_get;
+    self->items[self->i_get] = arg;
+
+    // overwriting first element in deque
+    if (self->i_put == new_i_get) {
+        if (self->i_put == 0) {
+            self->i_put = self->alloc - 1;
+        } else {
+            self->i_put--;
+        }
+    }
+
+    return mp_const_none;
+}
+static MP_DEFINE_CONST_FUN_OBJ_2(deque_appendleft_obj, mp_obj_deque_appendleft);
 
-STATIC mp_obj_t deque_popleft(mp_obj_t self_in) {
+static mp_obj_t mp_obj_deque_extend(mp_obj_t self_in, mp_obj_t arg_in) {
+    mp_obj_iter_buf_t iter_buf;
+    mp_obj_t iter = mp_getiter(arg_in, &iter_buf);
+    mp_obj_t item;
+    while ((item = mp_iternext(iter)) != MP_OBJ_STOP_ITERATION) {
+        mp_obj_deque_append(self_in, item);
+    }
+    return mp_const_none;
+}
+static MP_DEFINE_CONST_FUN_OBJ_2(deque_extend_obj, mp_obj_deque_extend);
+
+static mp_obj_t deque_popleft(mp_obj_t self_in) {
     mp_obj_deque_t *self = MP_OBJ_TO_PTR(self_in);
 
     if (self->i_get == self->i_put) {
@@ -133,35 +176,139 @@ STATIC mp_obj_t deque_popleft(mp_obj_t self_in) {
 
     return ret;
 }
-STATIC MP_DEFINE_CONST_FUN_OBJ_1(deque_popleft_obj, deque_popleft);
+static MP_DEFINE_CONST_FUN_OBJ_1(deque_popleft_obj, deque_popleft);
+
+static mp_obj_t deque_pop(mp_obj_t self_in) {
+    mp_obj_deque_t *self = MP_OBJ_TO_PTR(self_in);
+
+    if (self->i_get == self->i_put) {
+        mp_raise_msg(&mp_type_IndexError, MP_ERROR_TEXT("empty"));
+    }
+
+    if (self->i_put == 0) {
+        self->i_put = self->alloc - 1;
+    } else {
+        self->i_put--;
+    }
+
+    mp_obj_t ret = self->items[self->i_put];
+    self->items[self->i_put] = MP_OBJ_NULL;
+
+    return ret;
+}
+static MP_DEFINE_CONST_FUN_OBJ_1(deque_pop_obj, deque_pop);
+
+#if MICROPY_PY_COLLECTIONS_DEQUE_SUBSCR
+static mp_obj_t deque_subscr(mp_obj_t self_in, mp_obj_t index, mp_obj_t value) {
+    if (value == MP_OBJ_NULL) {
+        // delete not supported, fall back to mp_obj_subscr() error message
+        return MP_OBJ_NULL;
+    }
+    mp_obj_deque_t *self = MP_OBJ_TO_PTR(self_in);
+
+    size_t offset = mp_get_index(self->base.type, deque_len(self), index, false);
+    size_t index_val = self->i_get + offset;
+    if (index_val > self->alloc) {
+        index_val -= self->alloc;
+    }
+
+    if (value == MP_OBJ_SENTINEL) {
+        // load
+        return self->items[index_val];
+    } else {
+        // store into deque
+        self->items[index_val] = value;
+        return mp_const_none;
+    }
+}
+#endif
 
 #if 0
-STATIC mp_obj_t deque_clear(mp_obj_t self_in) {
+static mp_obj_t deque_clear(mp_obj_t self_in) {
     mp_obj_deque_t *self = MP_OBJ_TO_PTR(self_in);
     self->i_get = self->i_put = 0;
     mp_seq_clear(self->items, 0, self->alloc, sizeof(*self->items));
     return mp_const_none;
 }
-STATIC MP_DEFINE_CONST_FUN_OBJ_1(deque_clear_obj, deque_clear);
+static MP_DEFINE_CONST_FUN_OBJ_1(deque_clear_obj, deque_clear);
 #endif
 
-STATIC const mp_rom_map_elem_t deque_locals_dict_table[] = {
+static const mp_rom_map_elem_t deque_locals_dict_table[] = {
     { MP_ROM_QSTR(MP_QSTR_append), MP_ROM_PTR(&deque_append_obj) },
+    { MP_ROM_QSTR(MP_QSTR_appendleft), MP_ROM_PTR(&deque_appendleft_obj) },
+    { MP_ROM_QSTR(MP_QSTR_extend), MP_ROM_PTR(&deque_extend_obj) },
     #if 0
     { MP_ROM_QSTR(MP_QSTR_clear), MP_ROM_PTR(&deque_clear_obj) },
     #endif
+    { MP_ROM_QSTR(MP_QSTR_pop), MP_ROM_PTR(&deque_pop_obj) },
     { MP_ROM_QSTR(MP_QSTR_popleft), MP_ROM_PTR(&deque_popleft_obj) },
 };
 
-STATIC MP_DEFINE_CONST_DICT(deque_locals_dict, deque_locals_dict_table);
+static MP_DEFINE_CONST_DICT(deque_locals_dict, deque_locals_dict_table);
+
+#if MICROPY_PY_COLLECTIONS_DEQUE_ITER
+#define DEQUE_TYPE_FLAGS MP_TYPE_FLAG_ITER_IS_GETITER
+#define DEQUE_TYPE_ITER iter, mp_obj_new_deque_it,
+#else
+#define DEQUE_TYPE_FLAGS MP_TYPE_FLAG_NONE
+#define DEQUE_TYPE_ITER
+#endif
+
+#if MICROPY_PY_COLLECTIONS_DEQUE_SUBSCR
+#define DEQUE_TYPE_SUBSCR subscr, deque_subscr,
+#else
+#define DEQUE_TYPE_SUBSCR
+#endif
 
 MP_DEFINE_CONST_OBJ_TYPE(
     mp_type_deque,
     MP_QSTR_deque,
-    MP_TYPE_FLAG_NONE,
+    MP_TYPE_FLAG_ITER_IS_GETITER,
     make_new, deque_make_new,
     unary_op, deque_unary_op,
+    DEQUE_TYPE_SUBSCR
+    DEQUE_TYPE_ITER
     locals_dict, &deque_locals_dict
     );
 
+/******************************************************************************/
+/* deque iterator                                                             */
+
+#if MICROPY_PY_COLLECTIONS_DEQUE_ITER
+
+typedef struct _mp_obj_deque_it_t {
+    mp_obj_base_t base;
+    mp_fun_1_t iternext;
+    mp_obj_t deque;
+    size_t cur;
+} mp_obj_deque_it_t;
+
+static mp_obj_t deque_it_iternext(mp_obj_t self_in) {
+    mp_obj_deque_it_t *self = MP_OBJ_TO_PTR(self_in);
+    mp_obj_deque_t *deque = MP_OBJ_TO_PTR(self->deque);
+    if (self->cur != deque->i_put) {
+        mp_obj_t o_out = deque->items[self->cur];
+        if (++self->cur == deque->alloc) {
+            self->cur = 0;
+        }
+        return o_out;
+    } else {
+        return MP_OBJ_STOP_ITERATION;
+    }
+}
+
+static mp_obj_t mp_obj_new_deque_it(mp_obj_t deque, mp_obj_iter_buf_t *iter_buf) {
+    mp_obj_deque_t *deque_ = MP_OBJ_TO_PTR(deque);
+    size_t i_get = deque_->i_get;
+    assert(sizeof(mp_obj_deque_it_t) <= sizeof(mp_obj_iter_buf_t));
+    mp_obj_deque_it_t *o = (mp_obj_deque_it_t *)iter_buf;
+    o->base.type = &mp_type_polymorph_iter;
+    o->iternext = deque_it_iternext;
+    o->deque = deque;
+    o->cur = i_get;
+    return MP_OBJ_FROM_PTR(o);
+}
+
+#endif
+
 #endif // MICROPY_PY_COLLECTIONS_DEQUE