Add distinctBy examples to README and add unit tests.

markrogoyski · Sep 9, 2023 · 11b9ca6 · 11b9ca6
1 parent 09117b2
commit 11b9ca6
Show file tree

Hide file tree

Showing 2 changed files with 83 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -113,6 +113,7 @@ Quick Reference
 | Iterator                                                        | Description                                               | Code Snippet                                                 |
 |-----------------------------------------------------------------|-----------------------------------------------------------|--------------------------------------------------------------|
 | [`distinct`](#Distinct)                                         | Iterate only distinct items                               | `Set::distinct($data)`                                       |
+| [`distinctBy`](#Distinct-By)                                    | Iterate only distinct items using custom comparator       | `Set::distinct($data, $compareBy)`                           |
 | [`intersection`](#Intersection)                                 | Intersection of iterables                                 | `Set::intersection(...$iterables)`                           |
 | [`intersectionCoercive`](#Intersection-Coercive)                | Intersection with type coercion                           | `Set::intersectionCoercive(...$iterables)`                   |
 | [`partialIntersection`](#Partial-Intersection)                  | Partial intersection of iterables                         | `Set::partialIntersection($minCount, ...$iterables)`         |
@@ -203,6 +204,7 @@ Quick Reference
 | [`chunkwise`](#Chunkwise-1)                                               | Iterate by chunks                                                                         | `$stream->chunkwise($chunkSize)`                                                  |
 | [`chunkwiseOverlap`](#Chunkwise-Overlap-1)                                | Iterate by overlapped chunks                                                              | `$stream->chunkwiseOverlap($chunkSize, $overlap)`                                 |
 | [`distinct`](#Distinct-1)                                                 | Filter out elements: iterate only unique items                                            | `$stream->distinct([$strict])`                                                    |
+| [`distinctBy`](#Distinct-By-1)                                            | Filter out elements: iterate only unique items using custom comparator                    | `$stream->distinct($compareBy)`                                                   |
 | [`dropWhile`](#Drop-While-1)                                              | Drop elements from the iterable source while the predicate function is true               | `$stream->dropWhile($predicate)`                                                  |
 | [`filter`](#Filter-1)                                                     | Filter for only elements where the predicate function is true                             | `$stream->filterTrue($predicate)`                                                 |
 | [`filterTrue`](#Filter-True-1)                                            | Filter for only truthy elements                                                           | `$stream->filterTrue()`                                                           |
@@ -1250,7 +1252,7 @@ foreach (Math::runningTotal($prices, $initialValue) as $runningTotal) {
 // 5, 6, 8, 11, 15, 20
 ```
 
-## Set and multiset
+## Set and Multiset
 ### Distinct
 Filter out elements from the iterable only returning distinct elements.
 
@@ -1276,6 +1278,34 @@ foreach (Set::distinct($mixedTypes, false) as $datum) {
 // 1, 2, 3
 ```
 
+### Distinct By
+Filter out elements from the iterable only returning distinct elements according to a custom comparator function.
+
+```Set::distinctBy(iterable $data, callable $compareBy)```
+
+Defaults to [strict type](#Strict-and-Coercive-Types) comparisons. Set strict to false for type coercion comparisons.
+
+```php
+use IterTools\Set;
+
+$streetFighterConsoleReleases = [
+    ['id' => '112233', 'name' => 'Street Fighter 3 3rd Strike', 'console' => 'Dreamcast'],
+    ['id' => '223344', 'name' => 'Street Fighter 3 3rd Strike', 'console' => 'PS4'],
+    ['id' => '334455', 'name' => 'Street Fighter 3 3rd Strike', 'console' => 'PS5'],
+    ['id' => '445566', 'name' => 'Street Fighter VI', 'console' => 'PS4'],
+    ['id' => '556677', 'name' => 'Street Fighter VI', 'console' => 'PS5'],
+    ['id' => '667788', 'name' => 'Street Fighter VI', 'console' => 'PC'],
+];
+$compareBy = fn ($sfTitle) => $sfTitle['name'];
+
+$uniqueTitles = [];
+foreach (Set::distinctBy($streetFighterConsoleReleases, $compareBy) as $sfTitle) {
+    $uniqueTitles[] = $sfTitle;
+}
+
+// Contains one SF3 3rd Strike entry and one SFVI entry.
+```
+
 ### Intersection
 Iterates intersection of iterables.
 
@@ -2485,6 +2515,28 @@ $stream = Stream::of($input)
 // 1, 2, 3
 ```
 
+#### Distinct By
+Return a stream filtering out elements from the stream only returning distinct elements according to a custom comparator function.
+
+```$stream->distinctBy(callable $compareBy): Stream```
+
+```php
+use IterTools\Stream;
+
+$streetFighterConsoleReleases = [
+    ['id' => '112233', 'name' => 'Street Fighter 3 3rd Strike', 'console' => 'Dreamcast'],
+    ['id' => '223344', 'name' => 'Street Fighter 3 3rd Strike', 'console' => 'PS4'],
+    ['id' => '334455', 'name' => 'Street Fighter 3 3rd Strike', 'console' => 'PS5'],
+    ['id' => '445566', 'name' => 'Street Fighter VI', 'console' => 'PS4'],
+    ['id' => '556677', 'name' => 'Street Fighter VI', 'console' => 'PS5'],
+    ['id' => '667799', 'name' => 'Street Fighter VI', 'console' => 'PC'],
+];
+$stream = Stream::of($streetFighterConsoleReleases)
+    ->distinctBy(fn ($sfTitle) => $sfTitle['name'])
+    ->toArray();
+// Contains one SF3 3rd Strike entry and one SFVI entry
+```
+
 #### Drop While
 Drop elements from the stream while the predicate function is true.
 

diff --git a/tests/Set/DistinctByTest.php b/tests/Set/DistinctByTest.php
@@ -11,6 +11,36 @@
 
 class DistinctByTest extends \PHPUnit\Framework\TestCase
 {
+    /**
+     * @test distinctBy example usage
+     */
+    public function testExampleUsage(): void
+    {
+        // Given
+        $streetFighterConsoleReleases = [
+            ['id' => '112233', 'name' => 'Street Fighter 3 3rd Strike', 'console' => 'Dreamcast'],
+            ['id' => '223344', 'name' => 'Street Fighter 3 3rd Strike', 'console' => 'PS4'],
+            ['id' => '334455', 'name' => 'Street Fighter 3 3rd Strike', 'console' => 'PS5'],
+            ['id' => '445566', 'name' => 'Street Fighter VI', 'console' => 'PS4'],
+            ['id' => '556677', 'name' => 'Street Fighter VI', 'console' => 'PS5'],
+            ['id' => '667788', 'name' => 'Street Fighter VI', 'console' => 'PC'],
+        ];
+
+        // And
+        $compareBy = fn ($sfTitle) => $sfTitle['name'];
+
+        // When
+        $uniqueTitles = [];
+        foreach (Set::distinctBy($streetFighterConsoleReleases, $compareBy) as $sfTitle) {
+            $uniqueTitles[] = $sfTitle;
+        }
+
+        // Then
+        $this->assertCount(2, $uniqueTitles);
+        $this->assertContains('Street Fighter 3 3rd Strike', [$uniqueTitles[0]['name'], $uniqueTitles[1]['name']]);
+        $this->assertContains('Street Fighter VI', [$uniqueTitles[0]['name'], $uniqueTitles[1]['name']]);
+    }
+
     /**
      * @dataProvider dataProviderForArray
      * @param        array $data