Merge pull request #53 from xp-forge/feature/zip

Implement Sequence::zip() intermediate operation

Author: thekid

README.md

@@ -99,6 +99,7 @@ The following operations return a new `Sequence` instance on which more intermed
 * **collecting** - Collects elements in this sequence to a `util.data.ICollector` instance. Unlike the terminal operation below, passes the elements on.
 * **flatten** - Flattens sequences inside the sequence and returns a new list containing all values from all sequences.
 * **distinct** - Returns a new sequence which only consists of unique elements. Uniqueness is calculated using the `util.Objects::hashOf()` method by default (*but can be passed another function*).
+* **zip** - Combines values from this sequence with a given enumerable value, optionally using a given transformation function.
 * **sorted** - Returns a sorted collection. Can be invoked with a comparator function, a `util.Comparator` instance or the sort flags from PHP's sort() function (e.g. `SORT_NUMERIC | SORT_DESC`).
 
 Terminal operations

src/main/php/util/data/Enumeration.class.php

@@ -23,7 +23,7 @@ abstract class Enumeration {
   /**
    * Verifies a given argument is an enumeration
    *
-   * @param  var $arg
+   * @param  ?iterable|util.XPIterator|function(): iterable $arg
    * @return iterable
    * @throws lang.IllegalArgumentException
    */

src/main/php/util/data/Sequence.class.php

@@ -44,7 +44,7 @@ public function getIterator(): Traversable { yield from $this->elements; }
    * Creates a new stream with an enumeration of elements
    *
    * @see    xp://util.data.Enumeration
-   * @param  var... $enumerables an iterator, iterable, generator or array
+   * @param  ?iterable|util.XPIterator|function(): iterable... $enumerables
    * @return self
    * @throws lang.IllegalArgumentException if type of elements argument is incorrect
    */
@@ -405,6 +405,43 @@ public function map($function) {
     return new self($f());
   }
 
+  /**
+   * Combines values from this sequence with a given enumerable value,
+   * optionally using a given transformation function.
+   *
+   * @param  ?iterable|util.XPIterator|function(): iterable $enumerable
+   * @param  ?function(var, var): var $transform
+   * @return self
+   * @throws lang.IllegalArgumentException
+   */
+  public function zip($enumerable, $transform= null) {
+    $it= self::of($enumerable)->getIterator();
+    if (null === $transform) {
+      $f= function() use($it) {
+        foreach ($this->elements as $key => $element) {
+          yield $key => [$element, $it->current()];
+          $it->next();
+          if (!$it->valid()) break;
+        }
+      };
+    } else {
+      $op= Functions::$BINARYOP->newInstance($transform);
+      $f= function() use($it, $op) {
+        foreach ($this->elements as $key => $element) {
+          $r= $op($element, $it->current());
+          if ($r instanceof \Generator) {
+            yield from $r;
+          } else {
+            yield $key => $r;
+          }
+          $it->next();
+          if (!$it->valid()) break;
+        }
+      };
+    }
+    return new self($f());
+  }
+
   /**
    * Returns a new stream which flattens, mapping the given function to each
    * element.

src/test/php/util/data/unittest/SequenceZipTest.class.php

@@ -0,0 +1,37 @@
+<?php namespace util\data\unittest;
+
+use unittest\{Assert, Test};
+use util\data\Sequence;
+
+class SequenceZipTest extends AbstractSequenceTest {
+
+  #[Test]
+  public function basic_functionality() {
+    $result= Sequence::of([1, 2, 3, 4])->zip(['a', 'b', 'c', 'd'])->toArray();
+    Assert::equals([[1, 'a'], [2, 'b'], [3, 'c'], [4, 'd']], $result);
+  }
+
+  #[Test]
+  public function transform_using_function() {
+    $result= Sequence::of([1, 2, 3, 4])->zip([1, 0, -1, 6], function($a, $b) { return $a - $b; })->toArray();
+    Assert::equals([0, 2, 4, -2], $result);
+  }
+
+  #[Test]
+  public function create_map_with_generator() {
+    $result= Sequence::of([1, 2, 3, 4])->zip(['a', 'b', 'c', 'd'], function($a, $b) { yield $a => $b; })->toMap();
+    Assert::equals([1 => 'a', 2 => 'b', 3 => 'c', 4 => 'd'], $result);
+  }
+
+  #[Test]
+  public function shorter_sequence() {
+    $result= Sequence::of([1, 2, 3])->zip(['a', 'b', 'c', 'd'])->toArray();
+    Assert::equals([[1, 'a'], [2, 'b'], [3, 'c']], $result);
+  }
+
+  #[Test]
+  public function shorter_argument() {
+    $result= Sequence::of([1, 2, 3, 4])->zip(['a', 'b', 'c'])->toArray();
+    Assert::equals([[1, 'a'], [2, 'b'], [3, 'c']], $result);
+  }
+}