Return InternalIterator from collection getIterator() methods

README.md

@@ -20,6 +20,8 @@ Documentation is available on [php.net](https://www.php.net/manual/en/book.ds.ph
 - **Ds\Pair** -- readonly key-value pair
 - **Ds\Key** -- interface for custom key equality (replaces Hashable)
 
+`getIterator()` on `Seq`, `Map`, `Set`, and `Heap` returns an `InternalIterator` supporting the standard `Iterator` methods.
+
 You should also include the [polyfill](https://github.com/php-ds/polyfill) in your project for IDE integration.
 
 ## Installation

src/php/classes/php_heap_ce.c

@@ -163,7 +163,7 @@ METHOD(__unserialize)
 
 METHOD(getIterator) {
     PARSE_NONE;
-    ZVAL_COPY(return_value, getThis());
+    zend_create_internal_iterator_zval(return_value, ZEND_THIS);
 }
 
 void php_ds_register_heap()

src/php/classes/php_map_ce.c

@@ -379,7 +379,7 @@ METHOD(__unserialize)
 
 METHOD(getIterator) {
     PARSE_NONE;
-    ZVAL_COPY(return_value, getThis());
+    zend_create_internal_iterator_zval(return_value, ZEND_THIS);
 }
 
 METHOD(offsetExists)

src/php/classes/php_seq_ce.c

@@ -300,7 +300,7 @@ METHOD(__unserialize)
 
 METHOD(getIterator) {
     PARSE_NONE;
-    ZVAL_COPY(return_value, getThis());
+    zend_create_internal_iterator_zval(return_value, ZEND_THIS);
 }
 
 METHOD(offsetExists)

src/php/classes/php_set_ce.c

@@ -260,7 +260,7 @@ METHOD(__unserialize)
 
 METHOD(getIterator) {
     PARSE_NONE;
-    ZVAL_COPY(return_value, getThis());
+    zend_create_internal_iterator_zval(return_value, ZEND_THIS);
 }
 
 

tests/Heap/getIterator.phpt

@@ -0,0 +1,43 @@
+--TEST--
+Heap: getIterator returns an independent InternalIterator
+--FILE--
+<?php
+$collection = new Ds\Heap([10, 20, 30]);
+$expected = iterator_to_array($collection);
+$iterator = $collection->getIterator();
+var_dump($iterator instanceof InternalIterator);
+var_dump($iterator instanceof Iterator);
+var_dump($iterator !== $collection);
+
+$other = $collection->getIterator();
+var_dump($iterator !== $other);
+$iterator->rewind();
+$other->rewind();
+$iterator->next();
+var_dump($other->key() === array_key_first($expected));
+var_dump($other->current() === reset($expected));
+
+$result = [];
+while ($other->valid()) {
+    $result[$other->key()] = $other->current();
+    $other->next();
+}
+var_dump($result === $expected);
+var_dump(iterator_to_array($collection->getIterator()) === $expected);
+var_dump($collection->count() === 3);
+
+$empty = (new Ds\Heap())->getIterator();
+$empty->rewind();
+var_dump($empty->valid());
+?>
+--EXPECT--
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(false)

tests/Map/getIterator.phpt

@@ -0,0 +1,43 @@
+--TEST--
+Map: getIterator returns an independent InternalIterator
+--FILE--
+<?php
+$collection = new Ds\Map(['a' => 10, 'b' => 20, 'c' => 30]);
+$expected = iterator_to_array($collection);
+$iterator = $collection->getIterator();
+var_dump($iterator instanceof InternalIterator);
+var_dump($iterator instanceof Iterator);
+var_dump($iterator !== $collection);
+
+$other = $collection->getIterator();
+var_dump($iterator !== $other);
+$iterator->rewind();
+$other->rewind();
+$iterator->next();
+var_dump($other->key() === array_key_first($expected));
+var_dump($other->current() === reset($expected));
+
+$result = [];
+while ($other->valid()) {
+    $result[$other->key()] = $other->current();
+    $other->next();
+}
+var_dump($result === $expected);
+var_dump(iterator_to_array($collection->getIterator()) === $expected);
+var_dump($collection->count() === 3);
+
+$empty = (new Ds\Map())->getIterator();
+$empty->rewind();
+var_dump($empty->valid());
+?>
+--EXPECT--
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(false)

tests/Seq/getIterator.phpt

@@ -0,0 +1,43 @@
+--TEST--
+Seq: getIterator returns an independent InternalIterator
+--FILE--
+<?php
+$collection = new Ds\Seq([10, 20, 30]);
+$expected = iterator_to_array($collection);
+$iterator = $collection->getIterator();
+var_dump($iterator instanceof InternalIterator);
+var_dump($iterator instanceof Iterator);
+var_dump($iterator !== $collection);
+
+$other = $collection->getIterator();
+var_dump($iterator !== $other);
+$iterator->rewind();
+$other->rewind();
+$iterator->next();
+var_dump($other->key() === array_key_first($expected));
+var_dump($other->current() === reset($expected));
+
+$result = [];
+while ($other->valid()) {
+    $result[$other->key()] = $other->current();
+    $other->next();
+}
+var_dump($result === $expected);
+var_dump(iterator_to_array($collection->getIterator()) === $expected);
+var_dump($collection->count() === 3);
+
+$empty = (new Ds\Seq())->getIterator();
+$empty->rewind();
+var_dump($empty->valid());
+?>
+--EXPECT--
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(false)

tests/Set/getIterator.phpt

@@ -0,0 +1,43 @@
+--TEST--
+Set: getIterator returns an independent InternalIterator
+--FILE--
+<?php
+$collection = new Ds\Set([10, 20, 30]);
+$expected = iterator_to_array($collection);
+$iterator = $collection->getIterator();
+var_dump($iterator instanceof InternalIterator);
+var_dump($iterator instanceof Iterator);
+var_dump($iterator !== $collection);
+
+$other = $collection->getIterator();
+var_dump($iterator !== $other);
+$iterator->rewind();
+$other->rewind();
+$iterator->next();
+var_dump($other->key() === array_key_first($expected));
+var_dump($other->current() === reset($expected));
+
+$result = [];
+while ($other->valid()) {
+    $result[$other->key()] = $other->current();
+    $other->next();
+}
+var_dump($result === $expected);
+var_dump(iterator_to_array($collection->getIterator()) === $expected);
+var_dump($collection->count() === 3);
+
+$empty = (new Ds\Set())->getIterator();
+$empty->rewind();
+var_dump($empty->valid());
+?>
+--EXPECT--
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(false)