Add Iterator::reverse() based on DoubleEndedIterator

Author: danakj

subspace/CMakeLists.txt

@@ -62,6 +62,7 @@ target_sources(subspace PUBLIC
     "iter/map.h"
     "iter/once.h"
     "iter/sized_iterator.h"
+    "iter/reverse.h"
     "macros/__private/compiler_bugs.h"
     "macros/always_inline.h"
     "macros/builtin.h"

subspace/iter/filter.h

@@ -15,7 +15,6 @@
 #pragma once
 
 #include "subspace/fn/fn_defn.h"
-#include "subspace/iter/iterator_concept.h"
 #include "subspace/iter/iterator_defn.h"
 #include "subspace/iter/sized_iterator.h"
 #include "subspace/mem/move.h"
@@ -60,10 +59,8 @@ class Filter final
   Pred pred_;
   InnerSizedIter next_iter_;
 
-  // The InnerSizedIter is already known to be trivially relocatable, as
-  // SizedIterator is only constructed for trivially relocatable iterators.
-  // Likewise, the predicate is known to be trivially relocatable because FnMut
-  // is.
+  // The InnerSizedIter is trivially relocatable. Likewise, the predicate is
+  // known to be trivially relocatable because FnMut is.
   sus_class_trivially_relocatable(::sus::marker::unsafe_fn, decltype(pred_),
                                   decltype(next_iter_));
 };

subspace/iter/iterator.h

@@ -32,3 +32,4 @@
 // them all every time.
 #include "subspace/iter/filter.h"
 #include "subspace/iter/map.h"
+#include "subspace/iter/reverse.h"

subspace/iter/iterator_defn.h

@@ -20,7 +20,6 @@
 #include "subspace/iter/__private/iterator_loop.h"
 #include "subspace/iter/boxed_iterator.h"
 #include "subspace/iter/from_iterator.h"
-#include "subspace/iter/iterator_defn.h"
 #include "subspace/iter/sized_iterator.h"
 #include "subspace/macros/__private/compiler_bugs.h"
 #include "subspace/mem/move.h"
@@ -48,6 +47,8 @@ class Filter;
 template <class FromItem, class Item, size_t InnerIterSize,
           size_t InnerIterAlign>
 class Map;
+template <class Item, class InnerIter>
+class Reverse;
 
 struct SizeHint {
   ::sus::num::usize lower;
@@ -203,6 +204,9 @@ class [[nodiscard]] IteratorImpl : public IteratorBase<Item> {
                   pred) && noexcept
     requires(::sus::mem::relocate_by_memcpy<Iter>);
 
+  auto reverse() && noexcept
+    requires(::sus::mem::relocate_by_memcpy<Iter>);
+
   /// Transforms an iterator into a collection.
   ///
   /// collect() can turn anything iterable into a relevant collection. If this
@@ -305,6 +309,14 @@ auto IteratorImpl<Iter, Item>::filter(
                       make_sized_iterator(static_cast<Iter&&>(*this)));
 }
 
+template <class Iter, class Item>
+auto IteratorImpl<Iter, Item>::reverse() && noexcept
+  requires(::sus::mem::relocate_by_memcpy<Iter>)
+{
+  using Reverse = Reverse<Item, Iter>;
+  return Reverse::with(make_sized_iterator(static_cast<Iter&&>(*this)));
+}
+
 template <class Iter, class Item>
 template <::sus::iter::FromIterator<Item> C>
 ::sus::iter::FromIterator<Item> auto

subspace/iter/iterator_unittest.cc

@@ -22,6 +22,7 @@
 #include "subspace/iter/empty.h"
 #include "subspace/iter/filter.h"
 #include "subspace/macros/__private/compiler_bugs.h"
+#include "subspace/mem/replace.h"
 #include "subspace/prelude.h"
 
 using sus::containers::Array;
@@ -82,12 +83,14 @@ class ArrayIterator final : public IteratorImpl<ArrayIterator<Item, N>, Item> {
   }
 
   Option<Item> next() noexcept final {
-    if (++(index_) < N) {
-      return items_[index_].take();
-    } else {
-      --(index_);
-      return Option<Item>::none();
-    }
+    if (front_ == back_) return sus::none();
+    return items_[sus::mem::replace(front_, front_ + 1u)].take();
+  }
+
+  Option<Item> next_back() noexcept {
+    if (front_ == back_) return sus::none();
+    back_ -= 1u;
+    return items_[back_].take();
   }
 
  protected:
@@ -98,11 +101,12 @@ class ArrayIterator final : public IteratorImpl<ArrayIterator<Item, N>, Item> {
             })) {}
 
  private:
-  size_t index_ = static_cast<size_t>(-1);
+  size_t front_ = size_t{0};
+  size_t back_ = N;
   Array<Option<Item>, N> items_;
 
-  sus_class_trivially_relocatable_if_types(unsafe_fn, decltype(index_),
-                                           decltype(items_));
+  sus_class_trivially_relocatable_if_types(unsafe_fn, decltype(front_),
+                                           decltype(back_), decltype(items_));
 };
 
 static_assert(sus::iter::Iterator<ArrayIterator<int, 1>, int>);
@@ -340,4 +344,18 @@ TEST(Iterator, CollectVec) {
   EXPECT_EQ(collected[4u], 5);
 }
 
+TEST(Iterator, Reverse) {
+  i32 nums[5] = {1, 2, 3, 4, 5};
+
+  auto it = ArrayIterator<i32, 5>::with_array(nums).reverse();
+  static_assert(sus::iter::Iterator<decltype(it), i32>);
+  static_assert(sus::iter::DoubleEndedIterator<decltype(it), i32>);
+  EXPECT_EQ(it.next(), sus::some(5).construct());
+  EXPECT_EQ(it.next(), sus::some(4).construct());
+  EXPECT_EQ(it.next(), sus::some(3).construct());
+  EXPECT_EQ(it.next(), sus::some(2).construct());
+  EXPECT_EQ(it.next(), sus::some(1).construct());
+  EXPECT_EQ(it.next(), sus::None);
+}
+
 }  // namespace

subspace/iter/map.h

@@ -16,15 +16,12 @@
 
 #include "subspace/fn/fn_defn.h"
 #include "subspace/iter/iterator_defn.h"
-#include "subspace/iter/iterator_concept.h"
 #include "subspace/iter/sized_iterator.h"
 #include "subspace/mem/move.h"
 #include "subspace/mem/relocate.h"
 
 namespace sus::iter {
 
-using ::sus::mem::relocate_by_memcpy;
-
 template <class FromItem, class ToItem, size_t InnerIterSize,
           size_t InnerIterAlign>
 class Map final
@@ -57,10 +54,9 @@ class Map final
   MapFn fn_;
   InnerSizedIter next_iter_;
 
-  // The InnerSizedIter is already known to be trivially relocatable, by
-  // pushing the inner Iterator onto the heap if needed. Likewise, the
-  // predicate is known to be trivially relocatable because the FnMut will
-  // either be a function pointer or a heap allocation itself.
+  // The InnerSizedIter is trivially relocatable. Likewise, the predicate is
+  // known to be trivially relocatable because the FnMut will either be a
+  // function pointer or a heap allocation itself.
   sus_class_trivially_relocatable(::sus::marker::unsafe_fn, decltype(fn_),
                                   decltype(next_iter_));
 };

subspace/iter/once.h

@@ -14,9 +14,7 @@
 
 #pragma once
 
-#include "subspace/iter/iterator_concept.h"
 #include "subspace/iter/iterator_defn.h"
-#include "subspace/macros/__private/compiler_bugs.h"
 #include "subspace/mem/move.h"
 #include "subspace/mem/relocate.h"
 

subspace/iter/reverse.h

@@ -0,0 +1,78 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include "subspace/fn/fn_defn.h"
+#include "subspace/iter/iterator_concept.h"
+#include "subspace/iter/iterator_defn.h"
+#include "subspace/iter/sized_iterator.h"
+#include "subspace/mem/move.h"
+#include "subspace/mem/relocate.h"
+#include "subspace/mem/size_of.h"
+
+namespace sus::iter {
+
+using ::sus::mem::relocate_by_memcpy;
+
+/// An iterator that iterates over another iterator but in reverse.
+///
+/// The iterator wrapped by Reverse must be a DoubleEndedIterator.
+template <class ItemT, class InnerIter>
+class Reverse final : public IteratorImpl<Reverse<ItemT, InnerIter>, ItemT> {
+  using InnerSizedIter = SizedIterator<ItemT, ::sus::mem::size_of<InnerIter>(),
+                                       alignof(InnerIter)>;
+
+ public:
+  using Item = ItemT;
+
+  static Reverse with(InnerSizedIter&& next_iter) noexcept
+    requires(sus::iter::DoubleEndedIterator<InnerIter, Item>)
+  {
+    return Reverse(::sus::move(next_iter));
+  }
+
+  Option<Item> next() noexcept final {
+    // This class must know the full type of the inner iterator in order to
+    // access its next_back() method.
+    //
+    // TODO: We could consider storing an object pointer and method pointer
+    // instead to erase the type, but needs to be a properly casted pointer
+    // into the SizedIterator's storage to deal with the case where the Iterator
+    // implementation has another virtual base class which comes before Iterator
+    // and thus casting moves the pointer.
+    //
+    // TODO: If SizedIterator stored the method pointer for next_back and a
+    // `static constexpr` tag to say if `next_back()` is callable, then all
+    // composible iterators could preserve DoubleEndedIterator the same way
+    // Reverse does.
+    return static_cast<InnerIter&>(next_iter_.iterator_mut()).next_back();
+  }
+
+  // Reverse is reversible, and implements DoubleEndedIterator.
+  Option<Item> next_back() noexcept {
+    return static_cast<InnerIter&>(next_iter_.iterator_mut()).next();
+  }
+
+ private:
+  Reverse(InnerSizedIter&& next_iter) : next_iter_(::sus::move(next_iter)) {}
+
+  InnerSizedIter next_iter_;
+
+  // The InnerSizedIter is trivially relocatable.
+  sus_class_trivially_relocatable(::sus::marker::unsafe_fn,
+                                  decltype(next_iter_));
+};
+
+}  // namespace sus::iter