feat: add peekable to iterator interface

include/rusty_iterators/interface.hpp

@@ -10,6 +10,7 @@
 #include "interperse.hpp"
 #include "map.hpp"
 #include "moving_window.hpp"
+#include "peekable.hpp"
 #include "skip.hpp"
 #include "step_by.hpp"
 #include "take.hpp"
@@ -50,6 +51,7 @@ using iterator::Inspect;
 using iterator::Interperse;
 using iterator::Map;
 using iterator::MovingWindow;
+using iterator::Peekable;
 using iterator::Skip;
 using iterator::StepBy;
 using iterator::Take;
@@ -148,6 +150,7 @@ class IterInterface
     [[nodiscard]] auto neBy(Other&& it, Functor&& f) -> bool;
 
     [[nodiscard]] auto nth(size_t element) -> std::optional<T>;
+    [[nodiscard]] auto peekable() -> Peekable<T, Derived>;
 
     template <class Functor>
         requires PositionFunctor<T, Functor>
@@ -426,6 +429,12 @@ auto rusty_iterators::interface::IterInterface<T, Derived>::nth(size_t n) -> std
     return self().next();
 }
 
+template <class T, class Derived>
+auto rusty_iterators::interface::IterInterface<T, Derived>::peekable() -> Peekable<T, Derived>
+{
+    return Peekable<T, Derived>{std::forward<Derived>(self())};
+}
+
 template <class T, class Derived>
 template <class Functor>
     requires rusty_iterators::concepts::PositionFunctor<T, Functor>

include/rusty_iterators/peekable.hpp

@@ -0,0 +1,63 @@
+#pragma once
+
+#include "interface.fwd.hpp"
+
+#include <optional>
+
+namespace rusty_iterators::iterator
+{
+using interface::IterInterface;
+
+template <class T, class Other>
+class Peekable : public IterInterface<T, Peekable<T, Other>>
+{
+  public:
+    explicit Peekable(Other&& it) : it(std::forward<Other>(it)) {}
+
+    auto next() -> std::optional<T>;
+    auto peek() -> std::optional<T>;
+    [[nodiscard]] auto sizeHint() const -> std::optional<size_t>;
+
+  private:
+    Other it;
+    std::optional<std::optional<T>> peeked = std::nullopt;
+};
+} // namespace rusty_iterators::iterator
+
+template <class T, class Other>
+auto rusty_iterators::iterator::Peekable<T, Other>::next() -> std::optional<T>
+{
+    if (peeked.has_value())
+    {
+        auto item = peeked.value();
+        peeked    = std::nullopt;
+        return std::move(item);
+    }
+    return std::move(it.next());
+}
+
+template <class T, class Other>
+auto rusty_iterators::iterator::Peekable<T, Other>::peek() -> std::optional<T>
+{
+    if (peeked.has_value())
+        return peeked.value();
+
+    peeked = std::make_optional(it.next());
+    return peeked.value();
+}
+
+template <class T, class Other>
+auto rusty_iterators::iterator::Peekable<T, Other>::sizeHint() const -> std::optional<size_t>
+{
+    auto underlyingSize = it.sizeHint();
+
+    if (!underlyingSize.has_value())
+        return std::move(underlyingSize);
+
+    auto fullSize = underlyingSize.value();
+
+    if (peeked.has_value() && peeked.value().has_value())
+        fullSize += 1;
+
+    return fullSize;
+}

tests/peekable.test.cpp

@@ -0,0 +1,78 @@
+#include <gmock/gmock.h>
+#include <gtest/gtest.h>
+
+#include <rusty_iterators/iterator.hpp>
+
+using ::rusty_iterators::iterator::LazyIterator;
+using ::testing::ElementsAreArray;
+
+TEST(TestPeekableIterator, TestNextReturnsNextItem)
+{
+    auto vec = std::vector{1, 2, 3};
+    auto it  = LazyIterator{vec}.peekable();
+
+    ASSERT_EQ(it.next(), 1);
+    ASSERT_EQ(it.next(), 2);
+    ASSERT_EQ(it.next(), 3);
+    ASSERT_EQ(it.next(), std::nullopt);
+}
+
+TEST(TestPeekableIterator, TestPeekGivesNextItem)
+{
+    auto vec = std::vector{1, 2, 3};
+    auto it  = LazyIterator{vec}.peekable();
+
+    ASSERT_EQ(it.peek(), 1);
+    ASSERT_EQ(it.next(), 1);
+    ASSERT_EQ(it.peek(), 2);
+    ASSERT_EQ(it.next(), 2);
+}
+
+TEST(TestPeekableIterator, TestPeekMultipleTimes)
+{
+    auto vec = std::vector{1, 2, 3};
+    auto it  = LazyIterator{vec}.peekable();
+
+    ASSERT_EQ(it.peek(), 1);
+    ASSERT_EQ(it.peek(), 1);
+    ASSERT_EQ(it.peek(), 1);
+    ASSERT_EQ(it.next(), 1);
+}
+
+TEST(TestPeekableIterator, TestCollectPeekedIterator)
+{
+    auto vec = std::vector{1, 2, 3};
+    auto it  = LazyIterator{vec}.peekable();
+
+    it.peek();
+
+    EXPECT_THAT(it.collect(), ElementsAreArray({1, 2, 3}));
+}
+
+TEST(TestPeekableIterator, TestSizeHintOnNotPeeked)
+{
+    auto vec = std::vector{1, 2, 3};
+    auto it  = LazyIterator{vec}.peekable();
+
+    ASSERT_EQ(it.sizeHint(), 3);
+}
+
+TEST(TestPeekableIterator, TestSizeHinttPeeked)
+{
+    auto vec = std::vector{1, 2, 3};
+    auto it  = LazyIterator{vec}.peekable();
+
+    it.peek();
+
+    ASSERT_EQ(it.sizeHint(), 3);
+}
+
+TEST(TestPeekableIterator, TestSizeHintOnPeekedInfinite)
+{
+    auto vec = std::vector{1, 2, 3};
+    auto it  = LazyIterator{vec}.cycle().peekable();
+
+    it.peek();
+
+    ASSERT_EQ(it.sizeHint(), std::nullopt);
+}