Introduce DoubleEndedIterator concept

Vec, Array, and Slice iterators all implement DoubleEndedIterator
as they know their full size.

Author: danakj

subspace/containers/__private/array_iter.h

@@ -41,29 +41,38 @@ struct ArrayIntoIter final
   }
 
   Option<Item> next() noexcept final {
-    if (next_index_.primitive_value == N) [[unlikely]]
+    if (front_index_ == back_index_) [[unlikely]]
       return Option<Item>::none();
-    // SAFETY: The array has a fixed size. The next_index_ is encapsulated and
-    // only changed in this class/method. The next_index_ stops incrementing
-    // when it reaches N and starts at 0, and N >= 0, so when we get here we
-    // know next_index_ is in range of the array. We use get_unchecked_mut()
-    // here because it's difficult for the compiler to make the same
-    // observations we have here, as next_index_ is a field and changes across
-    // multiple method calls.
+    // SAFETY: The front and back indicies are kept within the length of the
+    // Array so can not go out of bounds.
     Item& item = array_.get_unchecked_mut(
         ::sus::marker::unsafe_fn,
-        ::sus::mem::replace(mref(next_index_), next_index_ + 1_usize));
+        ::sus::mem::replace(mref(front_index_), front_index_ + 1_usize));
+    return Option<Item>::some(move(item));
+  }
+
+  // sus::iter::DoubleEndedIterator trait.
+  Option<Item> next_back() noexcept {
+    if (front_index_ == back_index_) [[unlikely]]
+      return Option<Item>::none();
+    // SAFETY: The front and back indicies are kept within the length of the
+    // Array so can not go out of bounds.
+    back_index_ -= 1u;
+    Item& item =
+        array_.get_unchecked_mut(::sus::marker::unsafe_fn, back_index_);
     return Option<Item>::some(move(item));
   }
 
  private:
   ArrayIntoIter(Array<Item, N>&& array) noexcept : array_(::sus::move(array)) {}
 
-  usize next_index_ = 0_usize;
   Array<Item, N> array_;
+  usize front_index_ = 0_usize;
+  usize back_index_ = N;
 
   sus_class_trivially_relocatable_if_types(::sus::marker::unsafe_fn,
-                                           decltype(next_index_),
+                                           decltype(front_index_),
+                                           decltype(back_index_),
                                            decltype(array_));
 };
 

subspace/containers/__private/slice_iter.h

@@ -57,6 +57,16 @@ struct [[sus_trivial_abi]] SliceIter final
     return Option<Item>::some(*::sus::mem::replace_ptr(mref(ptr_), ptr_ + 1u));
   }
 
+  // sus::iter::DoubleEndedIterator trait.
+  Option<Item> next_back() noexcept {
+    if (ptr_ == end_) [[unlikely]]
+      return Option<Item>::none();
+    // SAFETY: Since end_ > ptr_, which is checked in the constructor, end_ - 1
+    // will never be null.
+    end_ -= 1u;
+    return Option<Item>::some(*end_);
+  }
+
   ::sus::iter::SizeHint size_hint() noexcept final {
     // SAFETY: end_ is always larger than ptr_ which is only incremented until
     // end_, so this static cast does not drop a negative sign bit. That ptr_
@@ -106,6 +116,16 @@ struct [[sus_trivial_abi]] SliceIterMut final
         mref(*::sus::mem::replace_ptr(mref(ptr_), ptr_ + 1u)));
   }
 
+  // sus::iter::DoubleEndedIterator trait.
+  Option<Item> next_back() noexcept {
+    if (ptr_ == end_) [[unlikely]]
+      return Option<Item>::none();
+    // SAFETY: Since end_ > ptr_, which is checked in the constructor, end_ - 1
+    // will never be null.
+    end_ -= 1u;
+    return Option<Item>::some(mref(*end_));
+  }
+
   ::sus::iter::SizeHint size_hint() noexcept final {
     // SAFETY: end_ is always larger than ptr_ which is only incremented until
     // end_, so this static cast does not drop a negative sign bit. That ptr_

subspace/containers/__private/vec_iter.h

@@ -40,35 +40,48 @@ struct VecIntoIter final
   }
 
   Option<Item> next() noexcept final {
-    if (next_index_.primitive_value == vec_.len()) [[unlikely]]
+    if (front_index_ == back_index_) [[unlikely]]
       return Option<Item>::none();
-    // SAFETY: The array has a fixed size. The next_index_ is encapsulated and
-    // only changed in this class/method. The next_index_ stops incrementing
-    // when it reaches N and starts at 0, and N >= 0, so when we get here we
-    // know next_index_ is in range of the array. We use get_unchecked_mut()
-    // here because it's difficult for the compiler to make the same
-    // observations we have here, as next_index_ is a field and changes across
-    // multiple method calls.
+    // SAFETY: This class owns the Vec and does not expose it, so its length is
+    // known and can not change. Thus the indices which are kept within the
+    // length of the Vec can not go out of bounds.
     Item& item = vec_.get_unchecked_mut(
         ::sus::marker::unsafe_fn,
-        ::sus::mem::replace(mref(next_index_), next_index_ + 1_usize));
+        ::sus::mem::replace(mref(front_index_), front_index_ + 1_usize));
+    return Option<Item>::some(move(item));
+  }
+
+  // sus::iter::DoubleEndedIterator trait.
+  Option<Item> next_back() noexcept {
+    if (front_index_ == back_index_) [[unlikely]]
+      return Option<Item>::none();
+    // SAFETY: This class owns the Vec and does not expose it, so its length is
+    // known and can not change. Thus the indices which are kept within the
+    // length of the Vec can not go out of bounds.
+    back_index_ -= 1u;
+    Item& item = vec_.get_unchecked_mut(::sus::marker::unsafe_fn, back_index_);
     return Option<Item>::some(move(item));
   }
 
   ::sus::iter::SizeHint size_hint() noexcept final {
-    const usize remaining = vec_.len() - next_index_;
+    const usize remaining = back_index_ - front_index_;
     return ::sus::iter::SizeHint(
         remaining, ::sus::Option<::sus::num::usize>::some(remaining));
   }
 
  private:
   VecIntoIter(Vec<Item>&& vec) noexcept : vec_(::sus::move(vec)) {}
 
-  usize next_index_ = 0_usize;
+  // TODO: Decompose the Vec (with a Vec::into_raw_parts) into a (pointer, len,
+  // cap) and just store the pointer here, as the front_index_ and back_index_
+  // are all we need to retain wrt the Vec's size.
   Vec<Item> vec_;
+  usize front_index_ = 0_usize;
+  usize back_index_ = vec_.len();
 
   sus_class_trivially_relocatable_if_types(::sus::marker::unsafe_fn,
-                                           decltype(next_index_),
+                                           decltype(front_index_),
+                                           decltype(back_index_),
                                            decltype(vec_));
 };
 

subspace/containers/array_unittest.cc

@@ -436,6 +436,16 @@ TEST(Array, IntoIter) {
   EXPECT_EQ(sum, 15_usize);
 }
 
+TEST(Array, IntoIterDoubleEnded) {
+  auto a = Array<usize, 3>::with_values(1u, 2u, 3u);
+
+  auto it = sus::move(a).into_iter();
+  EXPECT_EQ(it.next_back(), sus::some(3_usize).construct());
+  EXPECT_EQ(it.next_back(), sus::some(2_usize).construct());
+  EXPECT_EQ(it.next_back(), sus::some(1_usize).construct());
+  EXPECT_EQ(it.next_back(), sus::None);
+}
+
 TEST(Array, ImplicitIter) {
   const auto a = Array<usize, 5>::with_value(3u);
   auto sum = 0_usize;

subspace/containers/slice_unittest.cc

@@ -294,6 +294,29 @@ TEST(Slice, IntoIter) {
   }
 }
 
+TEST(Slice, DoubleEndedIterator) {
+  {
+    const usize ar[] = {1u, 2u, 3u};
+    auto slice = Slice<const usize>::from(ar);
+
+    auto it = slice.iter();
+    EXPECT_EQ(it.next_back(), sus::some(3_usize).construct());
+    EXPECT_EQ(it.next_back(), sus::some(2_usize).construct());
+    EXPECT_EQ(it.next_back(), sus::some(1_usize).construct());
+    EXPECT_EQ(it.next_back(), sus::None);
+  }
+  {
+    usize ar[] = {1u, 2u, 3u};
+    auto slice = Slice<usize>::from(ar);
+
+    auto it = slice.iter_mut();
+    EXPECT_EQ(it.next_back(), sus::some(3_usize).construct());
+    EXPECT_EQ(it.next_back(), sus::some(2_usize).construct());
+    EXPECT_EQ(it.next_back(), sus::some(1_usize).construct());
+    EXPECT_EQ(it.next_back(), sus::None);
+  }
+}
+
 TEST(Slice, ImplicitIter) {
   const usize ar[] = {1u, 2u, 3u};
   auto slice = Slice<const usize>::from(ar);

subspace/containers/vec_unittest.cc

@@ -316,6 +316,19 @@ TEST(Vec, IntoIter) {
   EXPECT_EQ(sum, 6);
 }
 
+TEST(Vec, IntoIterDoubleEnded) {
+  auto v = Vec<i32>();
+  v.push(1_i32);
+  v.push(2_i32);
+  v.push(3_i32);
+
+  auto it = sus::move(v).into_iter();
+  EXPECT_EQ(it.next_back(), sus::some(3_i32).construct());
+  EXPECT_EQ(it.next_back(), sus::some(2_i32).construct());
+  EXPECT_EQ(it.next_back(), sus::some(1_i32).construct());
+  EXPECT_EQ(it.next_back(), sus::None);
+}
+
 TEST(Vec, Growth) {
   auto v = Vec<i32>();
   v.reserve_exact(2_usize);

subspace/iter/iterator_concept.h

@@ -14,10 +14,12 @@
 
 #pragma once
 
+#include <concepts>
 #include <type_traits>
 
 #include "subspace/convert/subclass.h"
 #include "subspace/mem/forward.h"
+#include "subspace/option/option.h"
 
 namespace sus::iter {
 
@@ -26,9 +28,22 @@ class IteratorImpl;
 
 /// A concept for all implementations of iterators.
 ///
+/// An iterator has a method, `next()`, which when called, returns an
+/// `Option<Item>`. Calling next will return an `Option` containing the next
+/// `Item` as long as there are elements, and once they've all been exhausted,
+/// will return `None` to indicate that iteration is finished. Individual
+/// iterators may choose to resume iteration, and so calling next again may or
+/// may not eventually start returning an `Item` again at some point.
+///
 /// Types that satisfy this concept can be used in for loops and provide
 /// all the methods of an iterator type, which are found in
 /// `sus::iter::IteratorImpl`.
+///
+/// Any Iterator's full definition includes a number of other methods as well,
+/// built on top of next, and so you get them for free.
+///
+/// Iterators are also composable, and it's possible to chain them together to
+/// do more complex forms of processing.
 template <class T, class Item>
 concept Iterator = requires {
   // Has a T::Item typename.
@@ -40,6 +55,24 @@ concept Iterator = requires {
       std::decay_t<T>*, IteratorImpl<std::decay_t<T>, Item>*>;
 };
 
+/// An `Iterator` able to yield elements from both ends.
+///
+/// Something that implements `DoubleEndedIterator` has one extra capability
+/// over something that implements `Iterator`: the ability to also take Items
+/// from the back, as well as the front.
+///
+/// It is important to note that both back and forth work on the same range, and
+/// do not cross: iteration is over when they meet in the middle.
+///
+/// In a similar fashion to the `Iterator` protocol, once a
+/// `DoubleEndedIterator` returns `None` from a `next_back()`, calling it again
+/// may or may not ever return `Some` again. `next()` and `next_back()` are
+/// interchangeable for this purpose.
+template <class T, class Item>
+concept DoubleEndedIterator = Iterator<T, Item> && requires(T& t) {
+  { t.next_back() } -> std::same_as<::sus::option::Option<Item>>;
+};
+
 /// Conversion into an `Iterator`.
 ///
 /// A more general trait than `Iterator` which will accept anything that can be

subspace/iter/iterator_unittest.cc

@@ -14,12 +14,12 @@
 
 #include "subspace/iter/iterator.h"
 
-#include "subspace/iter/empty.h"
 #include "googletest/include/gtest/gtest.h"
 #include "subspace/assertions/unreachable.h"
 #include "subspace/construct/into.h"
 #include "subspace/containers/array.h"
 #include "subspace/containers/vec.h"
+#include "subspace/iter/empty.h"
 #include "subspace/iter/filter.h"
 #include "subspace/macros/__private/compiler_bugs.h"
 #include "subspace/prelude.h"
@@ -52,6 +52,15 @@ static_assert(
 static_assert(
   sus::iter::Iterator<sus::containers::SliceIterMut<int&>, int&>);
 
+static_assert(
+  sus::iter::DoubleEndedIterator<sus::containers::ArrayIntoIter<int, 1>, int>);
+static_assert(
+  sus::iter::DoubleEndedIterator<sus::containers::SliceIter<const int&>, const int&>);
+static_assert(
+  sus::iter::DoubleEndedIterator<sus::containers::SliceIterMut<int&>, int&>);
+static_assert(
+  sus::iter::DoubleEndedIterator<sus::containers::VecIntoIter<int>, int>);
+
 static_assert(
   sus::iter::IntoIterator<sus::containers::Array<int, 3u>, int>);
 static_assert(