PHPLIB-81: Move CachingIterator to MongoDB\Model

Author: jmikola

src/CachingIterator.php

@@ -0,0 +1,150 @@
+<?php
+/*
+ * Copyright 2017 MongoDB, Inc.
+ *
+ * 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.
+ */
+
+namespace MongoDB\Model;
+
+use Countable;
+use Generator;
+use Iterator;
+use Traversable;
+
+/**
+ * Iterator for wrapping a Traversable and caching its results.
+ *
+ * By caching results, this iterators allows a Traversable to be counted and
+ * rewound multiple times, even if the wrapped object does not natively support
+ * those operations (e.g. MongoDB\Driver\Cursor).
+ *
+ * @internal
+ */
+class CachingIterator implements Countable, Iterator
+{
+    private $items;
+    private $iterator;
+    private $iteratorExhausted = false;
+
+    /**
+     * @param Traversable $traversable
+     */
+    public function __construct(Traversable $traversable)
+    {
+        $this->iterator = $this->wrapTraversable($traversable);
+        $this->storeCurrentItem();
+    }
+
+    /**
+     * @see http://php.net/countable.count
+     * @return integer
+     */
+    public function count()
+    {
+        $this->exhaustIterator();
+
+        return count($this->items);
+    }
+
+    /**
+     * @see http://php.net/iterator.current
+     * @return mixed
+     */
+    public function current()
+    {
+        return current($this->items);
+    }
+
+    /**
+     * @see http://php.net/iterator.mixed
+     * @return mixed
+     */
+    public function key()
+    {
+        return key($this->items);
+    }
+
+    /**
+     * @see http://php.net/iterator.next
+     * @return void
+     */
+    public function next()
+    {
+        if ( ! $this->iteratorExhausted) {
+            $this->iterator->next();
+            $this->storeCurrentItem();
+        }
+
+        next($this->items);
+    }
+
+    /**
+     * @see http://php.net/iterator.rewind
+     * @return void
+     */
+    public function rewind()
+    {
+        $this->exhaustIterator();
+        reset($this->items);
+    }
+
+    /**
+     * 
+     * @see http://php.net/iterator.valid
+     * @return boolean
+     */
+    public function valid()
+    {
+        return $this->key() !== null;
+    }
+
+    /**
+     * Ensures that the inner iterator is fully consumed and cached.
+     */
+    private function exhaustIterator()
+    {
+        while ( ! $this->iteratorExhausted) {
+            $this->next();
+        }
+    }
+
+    /**
+     * Stores the current item in the cache.
+     */
+    private function storeCurrentItem()
+    {
+        $key = $this->iterator->key();
+
+        if ($key === null) {
+            return;
+        }
+
+        $this->items[$key] = $this->iterator->current();
+    }
+
+    /**
+     * Wraps the Traversable with a Generator.
+     *
+     * @param Traversable $traversable
+     * @return Generator
+     */
+    private function wrapTraversable(Traversable $traversable)
+    {
+        foreach ($traversable as $key => $value) {
+            yield $key => $value;
+        }
+
+        $this->iteratorExhausted = true;
+    }
+}

src/Model/CachingIterator.php

@@ -1,37 +1,40 @@
 <?php
 
-namespace MongoDB\Tests;
+namespace MongoDB\Tests\Model;
 
-use MongoDB\CachingIterator;
+use MongoDB\Model\CachingIterator;
 
 class CachingIteratorTest extends \PHPUnit_Framework_TestCase
 {
     /**
-     * Sanity check for all following tests
+     * Sanity check for all following tests.
+     *
      * @expectedException \Exception
      * @expectedExceptionMessage Cannot traverse an already closed generator
      */
-    public function testTraverseGeneratorConsumesIt()
+    public function testTraversingGeneratorConsumesIt()
     {
         $iterator = $this->getTraversable([1, 2, 3]);
         $this->assertSame([1, 2, 3], iterator_to_array($iterator));
         $this->assertSame([1, 2, 3], iterator_to_array($iterator));
     }
 
-    public function testIterateOverItems()
+    public function testIteration()
     {
         $iterator = new CachingIterator($this->getTraversable([1, 2, 3]));
 
         $expectedKey = 0;
         $expectedItem = 1;
+
         foreach ($iterator as $key => $item) {
             $this->assertSame($expectedKey++, $key);
             $this->assertSame($expectedItem++, $item);
         }
+
         $this->assertFalse($iterator->valid());
     }
 
-    public function testIteratePartiallyThenRewind()
+    public function testRewindAfterPartialIteration()
     {
         $iterator = new CachingIterator($this->getTraversable([1, 2, 3]));
 
@@ -47,7 +50,7 @@ public function testCount()
         $this->assertCount(3, $iterator);
     }
 
-    public function testCountAfterPartiallyIterating()
+    public function testCountAfterPartialIteration()
     {
         $iterator = new CachingIterator($this->getTraversable([1, 2, 3]));
         $iterator->next();