Add Amp\Iterator\discard (#315)

lib/functions.php

@@ -762,6 +762,31 @@ function concat(array $iterators): Iterator
         return $emitter->iterate();
     }
 
+    /**
+     * Discards all remaining items and returns the number of discarded items.
+     *
+     * @template TValue
+     *
+     * @param Iterator $iterator
+     *
+     * @return Promise
+     *
+     * @psalm-param Iterator<TValue> $iterator
+     * @psalm-return Promise<int>
+     */
+    function discard(Iterator $iterator): Promise
+    {
+        return call(static function () use ($iterator): \Generator {
+            $count = 0;
+
+            while (yield $iterator->advance()) {
+                $count++;
+            }
+
+            return $count;
+        });
+    }
+
     /**
      * Collects all items from an iterator into an array.
      *

test/IteratorDiscardTest.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Amp\Test;
+
+use Amp\Iterator;
+use Amp\PHPUnit\AsyncTestCase;
+use function Amp\Iterator\discard;
+
+class IteratorDiscardTest extends AsyncTestCase
+{
+    public function testEmpty(): \Generator
+    {
+        $this->assertSame(0, yield discard(Iterator\fromIterable([])));
+    }
+
+    public function testCount(): \Generator
+    {
+        $this->assertSame(3, yield discard(Iterator\fromIterable(['a', 1, false], 1)));
+    }
+}