Merge pull request #59 from xp-forge/feature/except

Add `except()`, returns a sequence with values except those passed

Author: thekid

README.md

@@ -94,6 +94,7 @@ The following operations return a new `Sequence` instance on which more intermed
 * **limit** - Stops iteration when limit is reached. Using `limit(10)` stops iteration once ten elements have been returned, `limit(function($e) { return 'stop' === $e; })` will stop once the first element equal to the string *stop* is encountered.
 * **filter** - Filters the sequence by a given criterion. The new sequence will only contain values for which it returns true. Accepts a function or a `util.Filter` instance.
 * **map** - Maps each element in the sequence by applying a function on it and returning a new sequence with the return value of that function.
+* **except** - Returns the sequence with all values except the ones given.
 * **peek** - Calls a function for each element in the sequence; especially useful for debugging, e.g. `peek('var_dump', [])`.
 * **counting** - Increments the integer given as its argument for each element in the sequence.
 * **collecting** - Collects elements in this sequence to a `util.data.ICollector` instance. Unlike the terminal operation below, passes the elements on.

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

@@ -8,17 +8,18 @@
  * Sequences API for PHP
  *
  * @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.SequenceCreationTest
+ * @test  util.data.unittest.SequenceExceptTest
  * @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.SequenceSortingTest
  * @test  util.data.unittest.SequenceWindowTest
  */
 class Sequence implements Value, IteratorAggregate {
@@ -443,6 +444,36 @@ public function map($function) {
     return new self($f());
   }
 
+  /**
+   * Returns a new sequence yielding values except for those passed to this
+   * method. Uses `util.Objects::equal()` to compare values.
+   *
+   * @param  var... $values
+   * @return self
+   */
+  public function except(... $values) {
+    if (empty($values)) {
+      return $this;
+    } else if (1 === sizeof($values)) {
+      $value= current($values);
+      $f= function() use($value) {
+        foreach ($this->elements as $key => $element) {
+          Objects::equal($element, $value) || yield $key => $element;
+        }
+      };
+    } else {
+      $f= function() use($values) {
+        foreach ($this->elements as $key => $element) {
+          foreach ($values as $value) {
+            if (Objects::equal($element, $value)) continue 2;
+          }
+          yield $key => $element;
+        }
+      };
+    }
+    return new self($f());
+  }
+
   /**
    * Combines values from this sequence with a given enumerable value,
    * optionally using a given transformation function.

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

@@ -0,0 +1,45 @@
+<?php namespace util\data\unittest;
+
+use test\{Assert, Test};
+use util\data\Sequence;
+
+class SequenceExceptTest extends AbstractSequenceTest {
+
+  #[Test]
+  public function except_empty() {
+    $this->assertSequence([1, 2, 3, 4], Sequence::of([1, 2, 3, 4])->except());
+  }
+
+  #[Test]
+  public function except_one() {
+    $this->assertSequence([1, 2, 4], Sequence::of([1, 2, 3, 4])->except(3));
+  }
+
+  #[Test]
+  public function except_multiple() {
+    $this->assertSequence([1, 3], Sequence::of([1, 2, 3, 4])->except(2, 4));
+  }
+
+  #[Test]
+  public function except_varargs() {
+    $this->assertSequence([1, 3], Sequence::of([1, 2, 3, 4])->except(...[2, 4]));
+  }
+
+  #[Test]
+  public function except_uses_object_comparison() {
+    $a= new Person(1, 'A');
+    $b= new Person(2, 'B');
+    $c= new Person(3, 'C');
+
+    $this->assertSequence([$a, $c], Sequence::of([$a, $b, $c])->except(new Person(2, 'B')));
+  }
+
+  #[Test]
+  public function except_uses_array_comparison() {
+    $a= ['id' => 1, 'name' => 'A'];
+    $b= ['id' => 2, 'name' => 'B'];
+    $c= ['id' => 3, 'name' => 'C'];
+
+    $this->assertSequence([$a, $c], Sequence::of([$a, $b, $c])->except(['id' => 2, 'name' => 'B']));
+  }
+}