Add cursor() (#266)

Author: sanmai

README.md

@@ -237,7 +237,7 @@ In general, Pipeline instances are mutable, meaning every Pipeline-returning met
     /** @var $iterator \Iterator */
     ```
 
-- Iterating over a pipeline all over again results in undefined behavior. Best to avoid doing this.
+- Iterating over a pipeline all over again results in undefined behavior. Best to avoid doing this. If you need to break out of iteration and continue later, see [`cursor()`](#pipeline-cursor).
 
 # Classes and interfaces: overview
 
@@ -453,6 +453,30 @@ foreach ($pipeline as $value) {
 
 This allows to skip type checks for return values if one has no results to return: instead of `false` or `null` it is safe to return an unprimed pipeline.
 
+## `$pipeline->cursor()`
+
+Returns a forward-only iterator that maintains position across iterations. A cursor allows breaking out of a loop and continuing later:
+
+```php
+$pipeline = \Pipeline\fromArray([1, 2, 3, 4, 5]);
+$cursor = $pipeline->cursor();
+
+foreach ($cursor as $value) {
+    echo $value; // 1, 2
+    if ($value === 2) {
+        break;
+    }
+}
+
+// Continue with remaining elements
+foreach ($cursor as $value) {
+    echo $value; // 3, 4, 5
+}
+
+// Or use take() to re-enter Pipeline world
+$remaining = \Pipeline\take($cursor)->count();
+```
+
 ## `$pipeline->runningVariance()`
 
 Computes online statistics for the sequence: counts, sample  mean, sample variance, standard deviation. You can access these numbers on the fly with methods such as `getCount()`, `getMean()`, `getVariance()`, `getStandardDeviation()`.

src/Helper/CursorIterator.php

@@ -0,0 +1,67 @@
+<?php
+
+/**
+ * Copyright 2017, 2018 Alexey Kopytko <[email protected]>
+ *
+ * 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
+ *
+ * http://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.
+ */
+
+declare(strict_types=1);
+
+namespace Pipeline\Helper;
+
+use Iterator;
+use NoRewindIterator;
+use Override;
+
+/**
+ * A forward-only iterator that auto-advances when iteration resumes.
+ *
+ * Unlike NoRewindIterator which repeats the current element on resume,
+ * CursorIterator advances past it as a database cursor would.
+ *
+ * @template TKey
+ * @template TValue
+ * @template TIterator of Iterator<TKey, TValue>
+ *
+ * @extends NoRewindIterator<TKey, TValue, TIterator>
+ *
+ * @final
+ */
+class CursorIterator extends NoRewindIterator
+{
+    private bool $started = false;
+
+    /**
+     * @param TIterator $iterator
+     */
+    public function __construct(Iterator $iterator)
+    {
+        parent::__construct($iterator);
+
+        // Get the inner iterator ready; otherwise valid()/current() won't work
+        $iterator->rewind();
+    }
+
+    #[Override]
+    public function rewind(): void
+    {
+        if (!$this->started) {
+            $this->started = true;
+
+            return;
+        }
+
+        $this->next();
+    }
+}

src/Standard.php

@@ -30,6 +30,7 @@
 use IteratorAggregate;
 use Traversable;
 use Override;
+use Pipeline\Helper\CursorIterator;
 
 use function array_chunk;
 use function array_filter;
@@ -660,6 +661,27 @@ public function getIterator(): Traversable
         return new ArrayIterator($this->pipeline);
     }
 
+    /**
+     * Returns a forward-only iterator that maintains position across iterations.
+     * @return Iterator<TKey, TValue>
+     */
+    public function cursor(): Iterator
+    {
+        if ($this->empty()) {
+            return new EmptyIterator();
+        }
+
+        $iterator = $this->getIterator();
+
+        // Avoid double wrapping
+        if ($iterator instanceof CursorIterator) {
+            return $iterator;
+        }
+
+        /** @var Iterator $iterator */
+        return new CursorIterator($iterator);
+    }
+
     /**
      * By default, returns all values regardless of keys used, discarding all keys in the process. This is a terminal operation.
      * @return list<TValue>

tests/ChunkTest.php

@@ -69,6 +69,11 @@ public static function provideIterables(): iterable
             $iteratorItem[2] = fromArray($iteratorItem[2]);
 
             yield $iteratorItem;
+
+            $iteratorItem = $item;
+            $iteratorItem[2] = take($iteratorItem[2]);
+
+            yield $iteratorItem;
         }
     }
 

tests/CursorTest.php

@@ -0,0 +1,217 @@
+<?php
+
+/**
+ * Copyright 2017, 2018 Alexey Kopytko <[email protected]>
+ *
+ * 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
+ *
+ * http://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.
+ */
+
+declare(strict_types=1);
+
+namespace Tests\Pipeline;
+
+use ArrayIterator;
+use IteratorIterator;
+use PHPUnit\Framework\TestCase;
+use Iterator;
+use Pipeline\Helper\CursorIterator;
+use Pipeline\Standard;
+
+use function iterator_count;
+use function Pipeline\fromArray;
+use function Pipeline\map;
+use function Pipeline\take;
+
+/**
+ * @covers \Pipeline\Standard::cursor
+ * @covers \Pipeline\Helper\CursorIterator
+ *
+ * @internal
+ */
+final class CursorTest extends TestCase
+{
+    public static function provideIterables(): iterable
+    {
+        yield 'array' => [fromArray([1, 2, 3, 4, 5])];
+
+        yield 'ArrayIterator' => [take(new ArrayIterator([1, 2, 3, 4, 5]))];
+
+        yield 'IteratorIterator' => [take(new IteratorIterator(new ArrayIterator([1, 2, 3, 4, 5])))];
+
+        yield 'IteratorAggregate' => [take(new Standard(new IteratorIterator(new ArrayIterator([1, 2, 3, 4, 5]))))];
+
+        yield 'generator' => [map(fn() => yield from [1, 2, 3, 4, 5])];
+
+        yield 'stream' => [fromArray([1, 2, 3, 4, 5])->stream()];
+    }
+
+    /**
+     * @dataProvider provideIterables
+     */
+    public function testCursorContinuesAfterBreak(Standard $pipeline): void
+    {
+        $cursor = $pipeline->cursor();
+
+        $collected = [];
+        foreach ($cursor as $i) {
+            $collected[] = $i;
+            if (2 === $i) {
+                break;
+            }
+        }
+
+        $this->assertSame([1, 2], $collected);
+
+        $remaining = [];
+        foreach ($cursor as $i) {
+            $remaining[] = $i;
+        }
+
+        // CursorIterator auto-advances past the break point
+        $this->assertSame([3, 4, 5], $remaining);
+    }
+
+    /**
+     * @dataProvider provideIterables
+     */
+    public function testCursorWithTakeCount(Standard $pipeline): void
+    {
+        $cursor = $pipeline->cursor();
+
+        foreach ($cursor as $i) {
+            if (2 === $i) {
+                break;
+            }
+        }
+
+        // 3 elements remain: 3, 4, 5
+        $this->assertSame(3, take($cursor)->count());
+    }
+
+    /**
+     * @dataProvider provideIterables
+     */
+    public function testCursorWithSlice(Standard $pipeline): void
+    {
+        $cursor = $pipeline->cursor();
+
+        $this->assertSame([1, 2], take($cursor)->slice(0, 2)->toList());
+
+        // 3 elements remain: 3, 4, 5
+        $this->assertSame(3, take($cursor)->count());
+    }
+
+    /**
+     * @dataProvider provideIterables
+     */
+    public function testCursorWithTakeReduce(Standard $pipeline): void
+    {
+        $cursor = $pipeline->cursor();
+
+        foreach ($cursor as $i) {
+            if (2 === $i) {
+                break;
+            }
+        }
+
+        // Remaining: 3 + 4 + 5 = 12
+        $this->assertSame(12, take($cursor)->reduce());
+    }
+
+    /**
+     * @dataProvider provideIterables
+     */
+    public function testExhaustedCursorReturnsEmpty(Standard $pipeline): void
+    {
+        $cursor = $pipeline->cursor();
+
+        // Consume all elements
+        $this->assertSame(5, iterator_count($cursor));
+
+        $remaining = [];
+        foreach ($cursor as $i) {
+            $remaining[] = $i;
+        }
+
+        $this->assertSame([], $remaining);
+    }
+
+    public function testCursorReturnsIterator(): void
+    {
+        $pipeline = fromArray([1, 2, 3]);
+        $cursor = $pipeline->cursor();
+
+        $this->assertInstanceOf(Iterator::class, $cursor);
+    }
+
+    public function testCursorAvoidDoubleWrapping(): void
+    {
+        $pipeline = fromArray([1, 2, 3]);
+
+        $cursor1 = $pipeline->cursor();
+        $cursor2 = take($cursor1)->cursor();
+
+        // Should be the same instance (no double wrapping)
+        $this->assertSame($cursor1, $cursor2);
+    }
+
+    public function testCursorWithEmptyPipeline(): void
+    {
+        $pipeline = fromArray([]);
+        $cursor = $pipeline->cursor();
+
+        $this->assertSame([], take($cursor)->toList());
+    }
+
+    public function testCursorPreservesKeys(): void
+    {
+        $pipeline = fromArray(['a' => 1, 'b' => 2, 'c' => 3]);
+        $cursor = $pipeline->cursor();
+
+        $collected = [];
+        foreach ($cursor as $key => $value) {
+            $collected[$key] = $value;
+            if ('a' === $key) {
+                break;
+            }
+        }
+
+        $this->assertSame(['a' => 1], $collected);
+
+        $remaining = [];
+        foreach ($cursor as $key => $value) {
+            $remaining[$key] = $value;
+        }
+
+        // CursorIterator auto-advances past 'a'
+        $this->assertSame(['b' => 2, 'c' => 3], $remaining);
+    }
+
+    public function testCursorManualIteration(): void
+    {
+        $pipeline = fromArray([1, 2, 3]);
+        $cursor = $pipeline->cursor();
+
+        $this->assertTrue($cursor->valid());
+        $this->assertSame(1, $cursor->current());
+
+        $cursor->next();
+        $this->assertSame(2, $cursor->current());
+
+        $cursor->next();
+        $this->assertSame(3, $cursor->current());
+
+        $cursor->next();
+        $this->assertFalse($cursor->valid());
+    }
+}