Merge pull request #57 from xp-forge/feature/window-chunked

Author: thekid

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

@@ -7,18 +7,19 @@
 /**
  * Sequences API for PHP
  *
- * @test xp://util.data.unittest.SequenceTest
- * @test xp://util.data.unittest.SequenceCreationTest
- * @test xp://util.data.unittest.SequenceSortingTest
- * @test xp://util.data.unittest.SequenceCollectionTest
- * @test xp://util.data.unittest.SequenceConcatTest
- * @test xp://util.data.unittest.SequenceFilteringTest
- * @test xp://util.data.unittest.SequenceFlatteningTest
- * @test xp://util.data.unittest.SequenceIteratorTest
- * @test xp://util.data.unittest.SequenceMappingTest
- * @test xp://util.data.unittest.SequenceReductionTest
- * @test xp://util.data.unittest.SequenceResultSetTest
- * @test xp://util.data.unittest.SequenceSkipTest
+ * @test  util.data.unittest.SequenceTest
+ * @test  util.data.unittest.SequenceCreationTest
+ * @test  util.data.unittest.SequenceSortingTest
+ * @test  util.data.unittest.SequenceCollectionTest
+ * @test  util.data.unittest.SequenceConcatTest
+ * @test  util.data.unittest.SequenceFilteringTest
+ * @test  util.data.unittest.SequenceFlatteningTest
+ * @test  util.data.unittest.SequenceIteratorTest
+ * @test  util.data.unittest.SequenceMappingTest
+ * @test  util.data.unittest.SequenceReductionTest
+ * @test  util.data.unittest.SequenceResultSetTest
+ * @test  util.data.unittest.SequenceSkipTest
+ * @test  util.data.unittest.SequenceWindowTest
  */
 class Sequence implements Value, IteratorAggregate {
   public static $EMPTY;
@@ -642,6 +643,79 @@ public function sorted($comparator= null) {
     return new self($sort);
   }
 
+  /**
+   * Returns a chunked stream with chunks not exceeding the given size.
+   * The last chunk may have a smaller size.
+   *
+   * Calling `chunked($n)` is the same as `windowed($n, $n, true)` but
+   * uses a much simpler algorithm internally.
+   *
+   * @param  int $size
+   * @return self
+   * @throws lang.IllegalArgumentException
+   */
+  public function chunked($size) {
+    if ($size <= 0) {
+      throw new IllegalArgumentException('Size must be greater than zero');
+    }
+
+    $f= function() use($size) {
+      $chunk= [];
+      foreach ($this->elements as $element) {
+        $chunk[]= $element;
+        if (sizeof($chunk) < $size) continue;
+
+        yield $chunk;
+        $chunk= [];
+      }
+      if ($chunk) yield $chunk;
+    };
+    return new self($f());
+  }
+
+  /**
+   * Returns a sliding window stream - a list of element ranges that you
+   * would see if you were looking at the collection through a sliding
+   * window of the given size. 
+   *
+   * @param  int $size
+   * @param  int $step
+   * @param  bool $partial
+   * @return self
+   * @throws lang.IllegalArgumentException
+   */
+  public function windowed($size, $step= 1, $partial= false) {
+    if ($size <= 0 || $step <= 0) {
+      throw new IllegalArgumentException('Both size and step must be greater than zero');
+    }
+
+    $f= function() use($size, $step, $partial) {
+      $it= $this->getIterator();
+      $chunk= [];
+      do {
+
+        // Fetch $size elements and yield them as a chunk
+        while (sizeof($chunk) < $size && $it->valid()) {
+          $chunk[]= $it->current();
+          $it->next();
+        }
+        if ($chunk && $partial || $size === sizeof($chunk)) yield $chunk;
+
+        // Step forward, potentially skipping some elements
+        $s= $step - sizeof($chunk);
+        if ($s > 0) {
+          while ($s-- > 0 && $it->valid()) $it->next();
+          $chunk= [];
+        } else {
+          $chunk= array_slice($chunk, $step);
+        }
+      } while ($it->valid());
+
+      if ($chunk && $partial) yield $chunk;
+    };
+    return new self($f());
+  }
+
   /** @return string */
   public function hashCode() {
     return 'S'.Objects::hashOf($this->elements);

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

@@ -0,0 +1,102 @@
+<?php namespace util\data\unittest;
+
+use lang\IllegalArgumentException;
+use test\{Assert, Expect, Test, Values};
+use util\data\Sequence;
+
+class SequenceWindowTest extends AbstractSequenceTest {
+
+  #[Test]
+  public function chunked() {
+    $this->assertSequence(
+      [[1, 2], [3, 4]],
+      Sequence::of([1, 2, 3, 4])->chunked(2)
+    );
+  }
+
+  #[Test]
+  public function chunked_with_partial() {
+    $this->assertSequence(
+      [[1, 2], [3, 4], [5]],
+      Sequence::of([1, 2, 3, 4, 5])->chunked(2)
+    );
+  }
+
+  #[Test]
+  public function sliding_window() {
+    $this->assertSequence(
+      [[1, 2], [2, 3], [3, 4]],
+      Sequence::of([1, 2, 3, 4])->windowed(2)
+    );
+  }
+
+  #[Test]
+  public function window_size_equal_to_step() {
+    $this->assertSequence(
+      [[1, 2], [3, 4]],
+      Sequence::of([1, 2, 3, 4])->windowed(2, 2)
+    );
+  }
+
+  #[Test]
+  public function skip_elements() {
+    $this->assertSequence(
+      [[1, 2], [4, 5]],
+      Sequence::of([1, 2, 3, 4, 5])->windowed(2, 3)
+    );
+  }
+
+  #[Test, Values([[true, [[1, 2], [3, 4], [5]]], [false, [[1, 2], [3, 4]]]])]
+  public function partial_window($flag, $expected) {
+    $this->assertSequence(
+      $expected,
+      Sequence::of([1, 2, 3, 4, 5])->windowed(2, 2, $flag)
+    );
+  }
+
+  #[Test]
+  public function partial_window_multiple_partials_at_end() {
+    $this->assertSequence(
+      [[1, 2, 3, 4, 5], [4, 5, 6, 7, 8], [7, 8, 9, 10], [10]],
+      Sequence::of([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])->windowed(5, 3, true)
+    );
+  }
+
+  #[Test]
+  public function skip_elements_and_return_partial() {
+    $this->assertSequence(
+      [[1, 2], [5]],
+      Sequence::of([1, 2, 3, 4, 5])->windowed(2, 4, true)
+    );
+  }
+
+  #[Test, Values([[[], []], [[1], [[1]]]])]
+  public function chunked_edge_cases($elements, $expected) {
+    $this->assertSequence($expected, Sequence::of($elements)->chunked(2));
+  }
+
+  #[Test, Values([[[], []], [[1], []]])]
+  public function windowed_edge_cases_without_partial($elements, $expected) {
+    $this->assertSequence($expected, Sequence::of($elements)->windowed(2, 1, false));
+  }
+
+  #[Test, Values([[[], []], [[1], [[1]]]])]
+  public function windowed_edge_cases_with_partial($elements, $expected) {
+    $this->assertSequence($expected, Sequence::of($elements)->windowed(2, 1, true));
+  }
+
+  #[Test, Expect(IllegalArgumentException::class), Values([-1, 0])]
+  public function chunk_size_must_greater_than_zero($size) {
+    Sequence::of([1])->chunked($size);
+  }
+
+  #[Test, Expect(IllegalArgumentException::class), Values([-1, 0])]
+  public function window_size_must_greater_than_zero($size) {
+    Sequence::of([1])->windowed($size);
+  }
+
+  #[Test, Expect(IllegalArgumentException::class), Values([-1, 0])]
+  public function window_step_must_greater_than_zero($step) {
+    Sequence::of([1])->windowed(1, $step);
+  }
+}