feat: add interperse to iterator interface

include/rusty_iterators/interface.hpp

@@ -7,6 +7,7 @@
 #include "filter.hpp"
 #include "filter_map.hpp"
 #include "inspect.hpp"
+#include "interperse.hpp"
 #include "map.hpp"
 #include "moving_window.hpp"
 #include "skip.hpp"
@@ -45,6 +46,7 @@ using iterator::Enumerate;
 using iterator::Filter;
 using iterator::FilterMap;
 using iterator::Inspect;
+using iterator::Interperse;
 using iterator::Map;
 using iterator::MovingWindow;
 using iterator::Skip;
@@ -118,8 +120,9 @@ class IterInterface
 
     template <class Functor>
         requires InspectFunctor<T, Functor>
-    auto inspect(Functor&& f) -> Inspect<T, Functor, Derived>;
+    [[nodiscard]] auto inspect(Functor&& f) -> Inspect<T, Functor, Derived>;
 
+    [[nodiscard]] auto interperse(T&& item) -> Interperse<T, Derived>;
     [[nodiscard]] auto last() -> std::optional<T>;
 
     template <class Functor>
@@ -350,6 +353,13 @@ auto rusty_iterators::interface::IterInterface<T, Derived>::inspect(Functor&& f)
     return Inspect<T, Functor, Derived>{std::forward<Derived>(self()), std::forward<Functor>(f)};
 }
 
+template <class T, class Derived>
+auto rusty_iterators::interface::IterInterface<T, Derived>::interperse(T&& item)
+    -> Interperse<T, Derived>
+{
+    return Interperse<T, Derived>{std::forward<Derived>(self()), std::forward<T>(item)};
+}
+
 template <class T, class Derived>
 auto rusty_iterators::interface::IterInterface<T, Derived>::last() -> std::optional<T>
 {

include/rusty_iterators/interperse.hpp

@@ -0,0 +1,56 @@
+#pragma once
+
+#include "interface.fwd.hpp"
+
+#include <optional>
+
+namespace rusty_iterators::iterator
+{
+using interface::IterInterface;
+
+template <class T, class Other>
+class Interperse : public IterInterface<T, Interperse<T, Other>>
+{
+  public:
+    explicit Interperse(Other&& it, T&& item)
+        : it(std::forward<Other>(it)), item(std::forward<T>(item))
+    {}
+
+    auto next() -> std::optional<T>;
+    [[nodiscard]] auto sizeHint() const -> std::optional<size_t>;
+
+  private:
+    Other it;
+    T item;
+    bool interperse = false;
+};
+} // namespace rusty_iterators::iterator
+
+template <class T, class Other>
+auto rusty_iterators::iterator::Interperse<T, Other>::next() -> std::optional<T>
+{
+    if (interperse)
+    {
+        interperse = false;
+        return item;
+    }
+
+    auto nextItem = it.next();
+
+    if (!nextItem.has_value())
+        return std::move(nextItem);
+
+    interperse = true;
+    return std::move(nextItem);
+}
+
+template <class T, class Other>
+auto rusty_iterators::iterator::Interperse<T, Other>::sizeHint() const -> std::optional<size_t>
+{
+    auto underlyingSize = it.sizeHint();
+
+    if (!underlyingSize.has_value())
+        return std::nullopt;
+
+    return underlyingSize.value() * 2;
+}

tests/interperse.test.cpp

@@ -0,0 +1,41 @@
+#include <gmock/gmock.h>
+#include <gtest/gtest.h>
+
+#include <rusty_iterators/iterator.hpp>
+
+using ::rusty_iterators::iterator::LazyIterator;
+using ::testing::ElementsAreArray;
+
+TEST(TestInterperseIterator, TestNextReturnsInterpersed)
+{
+    auto vec = std::vector{1, 2};
+
+    auto item = 5;
+    auto it   = LazyIterator{vec}.interperse(std::cref(item));
+
+    ASSERT_EQ(it.next(), 1);
+    ASSERT_EQ(it.next(), 5);
+    ASSERT_EQ(it.next(), 2);
+    ASSERT_EQ(it.next(), 5);
+    ASSERT_EQ(it.next(), std::nullopt);
+}
+
+TEST(TestInterperseIterator, TestCollectReturnsAllValues)
+{
+    auto vec = std::vector{1, 2, 3};
+
+    auto item = 5;
+    auto it   = LazyIterator{vec}.interperse(std::cref(item));
+
+    EXPECT_THAT(it.collect(), ElementsAreArray({1, 5, 2, 5, 3, 5}));
+}
+
+TEST(TestInterperseIterator, TestSizeHintIsDoubled)
+{
+    auto vec = std::vector{1, 2, 3};
+
+    auto item = 5;
+    auto it   = LazyIterator{vec}.interperse(std::cref(item));
+
+    ASSERT_EQ(it.sizeHint(), 6);
+}