From 7efaf750941f3a1edd5dc03fbe5a290d5ab0236f Mon Sep 17 00:00:00 2001
From: Gert de Pagter <BackEndTea@users.noreply.github.com>
Date: Sat, 4 May 2024 08:10:42 +0200
Subject: [PATCH] Add `Vec` versions of the `unique` functions (#472)

Vec counterparts for the Dict versions of these functions
---
 docs/component/vec.md               |  3 ++
 src/Psl/Internal/Loader.php         |  3 ++
 src/Psl/Vec/unique.php              | 29 +++++++++++++++++++
 src/Psl/Vec/unique_by.php           | 39 +++++++++++++++++++++++++
 src/Psl/Vec/unique_scalar.php       | 37 ++++++++++++++++++++++++
 tests/unit/Vec/UniqueByTest.php     | 37 ++++++++++++++++++++++++
 tests/unit/Vec/UniqueScalarTest.php | 44 +++++++++++++++++++++++++++++
 tests/unit/Vec/UniqueTest.php       | 38 +++++++++++++++++++++++++
 8 files changed, 230 insertions(+)
 create mode 100644 src/Psl/Vec/unique.php
 create mode 100644 src/Psl/Vec/unique_by.php
 create mode 100644 src/Psl/Vec/unique_scalar.php
 create mode 100644 tests/unit/Vec/UniqueByTest.php
 create mode 100644 tests/unit/Vec/UniqueScalarTest.php
 create mode 100644 tests/unit/Vec/UniqueTest.php

diff --git a/docs/component/vec.md b/docs/component/vec.md
index 90dc80a2..c2074422 100644
--- a/docs/component/vec.md
+++ b/docs/component/vec.md
@@ -36,6 +36,9 @@
 - [sort](./../../src/Psl/Vec/sort.php#L25)
 - [sort_by](./../../src/Psl/Vec/sort_by.php#L28)
 - [take](./../../src/Psl/Vec/take.php#L22)
+- [unique](./../../src/Psl/Vec/unique.php#L16)
+- [unique_by](./../../src/Psl/Vec/unique_by.php#L23)
+- [unique_scalar](./../../src/Psl/Vec/unique_scalar.php#L20)
 - [values](./../../src/Psl/Vec/values.php#L19)
 - [zip](./../../src/Psl/Vec/zip.php#L37)
 
diff --git a/src/Psl/Internal/Loader.php b/src/Psl/Internal/Loader.php
index 4d9ea29e..fed9c596 100644
--- a/src/Psl/Internal/Loader.php
+++ b/src/Psl/Internal/Loader.php
@@ -155,6 +155,9 @@ final class Loader
         'Psl\\Vec\\sort' => 'Psl/Vec/sort.php',
         'Psl\\Vec\\sort_by' => 'Psl/Vec/sort_by.php',
         'Psl\\Vec\\take' => 'Psl/Vec/take.php',
+        'Psl\\Vec\\unique' => 'Psl/Vec/unique.php',
+        'Psl\\Vec\\unique_by' => 'Psl/Vec/unique_by.php',
+        'Psl\\Vec\\unique_scalar' => 'Psl/Vec/unique_scalar.php',
         'Psl\\Vec\\values' => 'Psl/Vec/values.php',
         'Psl\\Vec\\zip' => 'Psl/Vec/zip.php',
         'Psl\\Math\\abs' => 'Psl/Math/abs.php',
diff --git a/src/Psl/Vec/unique.php b/src/Psl/Vec/unique.php
new file mode 100644
index 00000000..ae171bc1
--- /dev/null
+++ b/src/Psl/Vec/unique.php
@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Vec;
+
+/**
+ * Return all the unique values of an array, as a list.
+ *
+ * @template Tv
+ *
+ * @param iterable<Tv> $iterable
+ *
+ * @return list<Tv>
+ */
+function unique(iterable $iterable): array
+{
+    return namespace\unique_by(
+        $iterable,
+        /**
+         * @param Tv $v
+         *
+         * @return Tv
+         *
+         * @pure
+         */
+        static fn($v) => $v,
+    );
+}
diff --git a/src/Psl/Vec/unique_by.php b/src/Psl/Vec/unique_by.php
new file mode 100644
index 00000000..01315f3c
--- /dev/null
+++ b/src/Psl/Vec/unique_by.php
@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Vec;
+
+use Closure;
+use Psl\Iter;
+
+/**
+ * Returns a new array in which each value appears exactly once, where the
+ * value's uniqueness is determined by transforming it to a scalar via the
+ * given function.
+ *
+ * @template Tv
+ * @template Ts
+ *
+ * @param iterable<Tv> $iterable
+ * @param (Closure(Tv): Ts) $scalar_func
+ *
+ * @return list<Tv>
+ */
+function unique_by(iterable $iterable, Closure $scalar_func): array
+{
+    /** @var list<Ts> $unique */
+    $unique = [];
+    /** @var list<Tv> $original_values */
+    $original_values = [];
+    foreach ($iterable as $v) {
+        $scalar = $scalar_func($v);
+
+        if (!Iter\contains($unique, $scalar)) {
+            $unique[] = $scalar;
+            $original_values[] = $v;
+        }
+    }
+
+    return $original_values;
+}
diff --git a/src/Psl/Vec/unique_scalar.php b/src/Psl/Vec/unique_scalar.php
new file mode 100644
index 00000000..81c35f9e
--- /dev/null
+++ b/src/Psl/Vec/unique_scalar.php
@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Vec;
+
+use function array_unique;
+use function is_array;
+
+/**
+ * Returns a new list in which each value appears exactly once. Better performant than `Vec\unique()` when the values
+ * are only scalars.
+ *
+ * @template Tv of scalar
+ *
+ * @param iterable<Tv> $iterable
+ *
+ * @return list<Tv>
+ */
+function unique_scalar(iterable $iterable): array
+{
+    if (is_array($iterable)) {
+        return namespace\values(array_unique($iterable));
+    }
+
+    return unique_by(
+        $iterable,
+        /**
+         * @param scalar $v
+         *
+         * @return scalar
+         *
+         * @pure
+         */
+        static fn($v) => $v
+    );
+}
diff --git a/tests/unit/Vec/UniqueByTest.php b/tests/unit/Vec/UniqueByTest.php
new file mode 100644
index 00000000..83717734
--- /dev/null
+++ b/tests/unit/Vec/UniqueByTest.php
@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Unit\Vec;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Str;
+use Psl\Vec;
+
+final class UniqueByTest extends TestCase
+{
+    /**
+     * @dataProvider provideData
+     */
+    public function testUniqueBy(array $expected, array $array, callable $scalar_fun): void
+    {
+        static::assertSame($expected, Vec\unique_by($array, $scalar_fun));
+    }
+
+    public function provideData(): array
+    {
+        return [
+            [
+                ['a', 'saif'],
+                ['a', 'b', 'c', 'd', 'saif', 'jack'],
+                static fn (string $value): int => Str\length($value),
+            ],
+
+            [
+                ['foo', 'bar', '@baz'],
+                ['foo', '@foo', 'bar', '@bar', '@baz'],
+                static fn (string $value): string => Str\replace($value, '@', ''),
+            ],
+        ];
+    }
+}
diff --git a/tests/unit/Vec/UniqueScalarTest.php b/tests/unit/Vec/UniqueScalarTest.php
new file mode 100644
index 00000000..0d5cbce5
--- /dev/null
+++ b/tests/unit/Vec/UniqueScalarTest.php
@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Unit\Vec;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Collection;
+use Psl\Iter;
+use Psl\Vec;
+
+final class UniqueScalarTest extends TestCase
+{
+    public function testUniqueScalars(): void
+    {
+        $array   = Vec\fill(10, 'foo');
+        $array[] = 'bar';
+
+        $unique = Vec\unique_scalar($array);
+
+        static::assertCount(2, $unique);
+        static::assertSame(['foo', 'bar'], $unique);
+    }
+
+    public function testUniqueIterator()
+    {
+        $array = Iter\Iterator::create(['foo', 'foo', 'bar', 'bar', 'baz']);
+
+        $unique = Vec\unique_scalar($array);
+
+        static::assertCount(3, $unique);
+        static::assertSame(['foo', 'bar', 'baz'], $unique);
+    }
+
+    public function testUniqueIteratorAgggregate()
+    {
+        $array = Collection\Map::fromArray(['foo', 'foo', 'bar', 'bar', 'baz']);
+
+        $unique = Vec\unique_scalar($array);
+
+        static::assertCount(3, $unique);
+        static::assertSame(['foo', 'bar', 'baz'], $unique);
+    }
+}
diff --git a/tests/unit/Vec/UniqueTest.php b/tests/unit/Vec/UniqueTest.php
new file mode 100644
index 00000000..bbe6e6b4
--- /dev/null
+++ b/tests/unit/Vec/UniqueTest.php
@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Unit\Vec;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Collection;
+use Psl\Iter;
+use Psl\Vec;
+
+final class UniqueTest extends TestCase
+{
+    public function testUnique(): void
+    {
+        $array = Vec\fill(10, 'foo');
+
+        $unique = Vec\unique($array);
+
+        static::assertCount(1, $unique);
+
+        static::assertSame('foo', Iter\first($unique));
+    }
+
+    public function testUniqueWithObjects(): void
+    {
+        $array = Vec\fill(10, 'foo');
+        $object = new Collection\Map([]);
+        $array  = Vec\concat($array, Vec\fill(10, $object));
+
+        $unique = Vec\unique($array);
+
+        static::assertCount(2, $unique);
+
+        static::assertSame('foo', Iter\first($unique));
+        static::assertSame($object, Iter\last($unique));
+    }
+}