Introduce the IntoIterator iterator_concept

Iterators are always also IntoIterator, returning a reference to
themselves.

This allows code to receive an iterator or a container, and is
most useful when receiving an iterator over non-reference values.

Author: danakj

subdoc/lib/gen/html_writer.h

@@ -361,7 +361,6 @@ class HtmlWriter {
     }
   }
 
-  // TODO: Add an Iterator<T> concept and use that to know what Item is here.
   void write_open(
       std::string_view type,
       sus::iter::Iterator<const std::string&> auto classes_iter,

subspace/iter/iterator_concept.h

@@ -14,26 +14,46 @@
 
 #pragma once
 
+#include <type_traits>
+
 #include "subspace/convert/subclass.h"
+#include "subspace/mem/forward.h"
 
 namespace sus::iter {
 
 template <class Iter, class Item>
 class IteratorImpl;
 
-/// A concept for dealing with iterators.
+/// A concept for all implementations of iterators.
 ///
 /// 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`.
 template <class T, class Item>
 concept Iterator = requires {
   // Has a T::Item typename.
-  requires(!std::is_void_v<typename T::Item>);
+  requires(!std::is_void_v<typename std::decay_t<T>::Item>);
   // The T::Item matches the concept input.
-  requires(std::same_as<typename T::Item, Item>);
+  requires(std::same_as<typename std::decay_t<T>::Item, Item>);
   // Subclasses from IteratorImpl<T, T::Item>.
-  requires ::sus::convert::SameOrSubclassOf<T*, IteratorImpl<T, Item>*>;
+  requires ::sus::convert::SameOrSubclassOf<
+      std::decay_t<T>*, IteratorImpl<std::decay_t<T>, Item>*>;
+};
+
+/// Conversion into an `Iterator`.
+///
+/// A more general trait than `Iterator` which will accept anything that can be
+/// iterated, including an `Iterator` (since all `Iterator`s also satisfy
+/// `IntoIterator`). This can be particularly useful when receiving an iterator
+/// over a set of non-reference values, allowing the caller to pass a container
+/// directly in place of an iterator.
+///
+/// Note that an `IntoIterator` type is not directly iterable in for loops, and
+/// requires calling `into_iter()` on it to convert it into an `Iterator`
+/// which is iterable in for loops.
+template <class T, class Item>
+concept IntoIterator = requires(T&& t) {
+  { ::sus::forward<T>(t).into_iter() } -> Iterator<Item>;
 };
 
 }  // namespace sus::iter

subspace/iter/iterator_defn.h

@@ -128,6 +128,11 @@ class [[nodiscard]] IteratorImpl : public IteratorBase<Item> {
   }
 
  public:
+  /// An Iterator also satisfies IntoIterator, which simply returns itself.
+  ///
+  /// sus::iter::IntoIterator trait implementation.
+  Iter&& into_iter() && noexcept { return ::sus::move(*this); }
+
   // Provided methods.
 
   /// Tests whether all elements of the iterator match a predicate.

subspace/iter/iterator_unittest.cc

@@ -42,7 +42,7 @@ static_assert(
 static_assert(
   sus::iter::Iterator<sus::iter::Map<int, int, 8, 8>, int>);
 static_assert(
-  ::sus::iter::Iterator<sus::iter::Once<int>, int>);
+  sus::iter::Iterator<sus::iter::Once<int>, int>);
 static_assert(
   sus::iter::Iterator<sus::containers::ArrayIntoIter<int, 1>, int>);
 static_assert(
@@ -51,6 +51,18 @@ static_assert(
   sus::iter::Iterator<sus::containers::SliceIter<const int&>, const int&>);
 static_assert(
   sus::iter::Iterator<sus::containers::SliceIterMut<int&>, int&>);
+
+static_assert(
+  sus::iter::IntoIterator<sus::containers::Array<int, 3u>, int>);
+static_assert(
+  sus::iter::IntoIterator<sus::containers::Slice<const int>, const int&>);
+static_assert(
+  sus::iter::IntoIterator<sus::containers::Slice<int>, int&>);
+static_assert(
+  sus::iter::IntoIterator<sus::containers::Vec<int>, int>);
+
+static_assert(
+  sus::iter::IntoIterator<sus::iter::Once<int>, int>);
 // clang-format on
 
 template <class Item, size_t N>