Add reversed() iterator.

Author: paulross

doc/sphinx/source/iterators_generators.rst

@@ -656,6 +656,80 @@ Result in the stdout:
             assert captured.out == expected
 
 
+.. _PySequenceMethods: https://docs.python.org/3/c-api/typeobj.html#c.PySequenceMethods
+
+-----------------------------------------
+Reverse Iterators
+-----------------------------------------
+
+Reverse iterators are slightly unusual, the ``reversed()`` function calls the object ``__reversed__`` method and that
+in turn uses ``__len__`` and ``__getitem__``.
+
+To support this in C we need to implement these last two methods using the `PySequenceMethods`_ method table.
+
+First the implementation of ``__len__`` in C:
+
+.. code-block:: c
+
+    static Py_ssize_t
+    SequenceOfLong_len(PyObject *self) {
+        return ((SequenceOfLong *)self)->size;
+    }
+
+Then the implementation of ``__getitem__``, not here that we support negative indexes and set and exception if the
+index is out of range:
+
+.. code-block:: c
+
+    static PyObject *
+    SequenceOfLong_getitem(PyObject *self, Py_ssize_t index) {
+        Py_ssize_t my_index = index;
+        if (my_index < 0) {
+            my_index += SequenceOfLong_len(self);
+        }
+        if (my_index > SequenceOfLong_len(self)) {
+            PyErr_Format(
+                PyExc_IndexError,
+                "Index %ld is out of range for length %ld",
+                index,
+                SequenceOfLong_len(self)
+            );
+            return NULL;
+        }
+        return PyLong_FromLong(((SequenceOfLong *)self)->array_long[my_index]);
+    }
+
+Create `PySequenceMethods`_ method table:
+
+.. code-block:: c
+
+    PySequenceMethods SequenceOfLong_sequence_methods = {
+        .sq_length = &SequenceOfLong_len,
+        .sq_item = &SequenceOfLong_getitem,
+    };
+
+Add this method table into the type specification:
+
+.. code-block:: c
+
+    static PyTypeObject SequenceOfLongType = {
+        PyVarObject_HEAD_INIT(NULL, 0)
+        /* Other stuff. */
+        .tp_dealloc = (destructor) SequenceOfLong_dealloc,
+        .tp_as_sequence = &SequenceOfLong_sequence_methods,
+        /* Other stuff. */
+    };
+
+And we can test it thus:
+
+.. code-block:: python
+
+    def test_c_iterator_reversed():
+        sequence = cIterator.SequenceOfLong([1, 7, 4])
+        result = reversed(sequence)
+        assert list(result) == [4, 7, 1,]
+
+
 .. index::
     single: Generators
 

src/cpy/Iterators/cIterator.c

@@ -193,6 +193,35 @@ static PyMethodDef SequenceOfLong_methods[] = {
         {NULL, NULL, 0, NULL}  /* Sentinel */
 };
 
+/* Sequence methods. */
+static Py_ssize_t
+SequenceOfLong_len(PyObject *self) {
+    return ((SequenceOfLong *)self)->size;
+}
+
+static PyObject *
+SequenceOfLong_getitem(PyObject *self, Py_ssize_t index) {
+    Py_ssize_t my_index = index;
+    if (my_index < 0) {
+        my_index += SequenceOfLong_len(self);
+    }
+    if (my_index > SequenceOfLong_len(self)) {
+        PyErr_Format(
+            PyExc_IndexError,
+            "Index %ld is out of range for length %ld",
+            index,
+            SequenceOfLong_len(self)
+        );
+        return NULL;
+    }
+    return PyLong_FromLong(((SequenceOfLong *)self)->array_long[my_index]);
+}
+
+PySequenceMethods SequenceOfLong_sequence_methods = {
+        .sq_length = &SequenceOfLong_len,
+        .sq_item = &SequenceOfLong_getitem,
+};
+
 static PyObject *
 SequenceOfLong___str__(SequenceOfLong *self, PyObject *Py_UNUSED(ignored)) {
     assert(!PyErr_Occurred());
@@ -205,6 +234,7 @@ static PyTypeObject SequenceOfLongType = {
         .tp_basicsize = sizeof(SequenceOfLong),
         .tp_itemsize = 0,
         .tp_dealloc = (destructor) SequenceOfLong_dealloc,
+        .tp_as_sequence = &SequenceOfLong_sequence_methods,
         .tp_str = (reprfunc) SequenceOfLong___str__,
         .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
         .tp_doc = "Sequence of long integers.",

tests/unit/test_c_iterators.py

@@ -29,12 +29,14 @@ def test_c_iterator_sequence_of_long_dir_pre_311():
                       '__format__',
                       '__ge__',
                       '__getattribute__',
+                      '__getitem__',
                       '__gt__',
                       '__hash__',
                       '__init__',
                       '__init_subclass__',
                       '__iter__',
                       '__le__',
+                      '__len__',
                       '__lt__',
                       '__ne__',
                       '__new__',
@@ -59,13 +61,15 @@ def test_c_iterator_sequence_of_long_dir_311_plus():
                       '__format__',
                       '__ge__',
                       '__getattribute__',
+                      '__getitem__',
                       '__getstate__',
                       '__gt__',
                       '__hash__',
                       '__init__',
                       '__init_subclass__',
                       '__iter__',
                       '__le__',
+                      '__len__',
                       '__lt__',
                       '__ne__',
                       '__new__',
@@ -210,6 +214,14 @@ def test_c_iterator_sorted():
     assert original == [1, 7, 4, ]
 
 
+def test_c_iterator_reversed():
+    sequence = cIterator.SequenceOfLong([1, 7, 4])
+    result = reversed(sequence)
+    print()
+    print(result)
+    assert list(result) == [4, 7, 1,]
+
+
 def test_c_iterator_generator_expression_sum():
     """https://docs.python.org/3/glossary.html#term-generator-expression"""
     sequence = cIterator.SequenceOfLong([1, 7, 4])