feat(collections): add fromItems and containsKey (#484)

* feat(collections): add fromItems to MutableVector * adding fromItems all around * add containsKey alias * adding tests for containsKey * psalm types * coding standards fix * documenter
azjezz · Sep 3, 2024 · d68cd6b · d68cd6b
1 parent c10ae65
commit d68cd6b
Show file tree

Hide file tree

Showing 17 changed files with 259 additions and 4 deletions.
diff --git a/docs/component/collection.md b/docs/component/collection.md
@@ -30,7 +30,7 @@
 - [Map](./../../src/Psl/Collection/Map.php#L25)
 - [MutableMap](./../../src/Psl/Collection/MutableMap.php#L25)
 - [MutableSet](./../../src/Psl/Collection/MutableSet.php#L22)
-- [MutableVector](./../../src/Psl/Collection/MutableVector.php#L23)
+- [MutableVector](./../../src/Psl/Collection/MutableVector.php#L24)
 - [Set](./../../src/Psl/Collection/Set.php#L23)
 - [Vector](./../../src/Psl/Collection/Vector.php#L22)
 

diff --git a/src/Psl/Collection/IndexAccessInterface.php b/src/Psl/Collection/IndexAccessInterface.php
@@ -34,6 +34,17 @@ public function at(int|string $k): mixed;
      */
     public function contains(int|string $k): bool;
 
+    /**
+     * Alias of `contains`.
+     *
+     * @param Tk $k
+     *
+     * @see contains() method
+     *
+     * @psalm-mutation-free
+     */
+    public function containsKey(int|string $k): bool;
+
     /**
      * Returns the value at the specified key in the current collection.
      *

diff --git a/src/Psl/Collection/Map.php b/src/Psl/Collection/Map.php
@@ -66,6 +66,19 @@ public static function fromArray(array $elements): Map
         return new self($elements);
     }
 
+    /**
+     * @template Tsk of array-key
+     * @template Tsv
+     *
+     * @param array<Tsk, Tsv> $items
+     *
+     * @return Map<Tsk, Tsv>
+     */
+    public static function fromItems(iterable $items): Map
+    {
+        return self::fromArray(iterator_to_array($items));
+    }
+
     /**
      * Returns the first value in the current collection.
      *
@@ -240,6 +253,18 @@ public function contains(int|string $k): bool
         return array_key_exists($k, $this->elements);
     }
 
+    /**
+     * Alias of `contains`.
+     *
+     * @param Tk $k
+     *
+     * @psalm-mutation-free
+     */
+    public function containsKey(int|string $k): bool
+    {
+        return $this->contains($k);
+    }
+
     /**
      * Returns the value at the specified key in the current map.
      *

diff --git a/src/Psl/Collection/MutableMap.php b/src/Psl/Collection/MutableMap.php
@@ -66,6 +66,19 @@ public static function fromArray(array $elements): MutableMap
         return new self($elements);
     }
 
+    /**
+     * @template Tsk of array-key
+     * @template Tsv
+     *
+     * @param array<Tsk, Tsv> $items
+     *
+     * @return MutableMap<Tsk, Tsv>
+     */
+    public static function fromItems(iterable $items): MutableMap
+    {
+        return self::fromArray(iterator_to_array($items));
+    }
+
     /**
      * Returns the first value in the current collection.
      *
@@ -240,6 +253,18 @@ public function contains(int|string $k): bool
         return array_key_exists($k, $this->elements);
     }
 
+    /**
+     * Alias of `contains`.
+     *
+     * @param Tk $k
+     *
+     * @psalm-mutation-free
+     */
+    public function containsKey(int|string $k): bool
+    {
+        return $this->contains($k);
+    }
+
     /**
      * Returns the value at the specified key in the current map.
      *

diff --git a/src/Psl/Collection/MutableSet.php b/src/Psl/Collection/MutableSet.php
@@ -71,6 +71,26 @@ public static function fromArray(array $elements): MutableSet
         return new self($elements);
     }
 
+    /**
+     * Create a set from the given iterable, using the values of the iterable as the set values.
+     *
+     * @template Ts of array-key
+     *
+     * @param iterable<Ts, Ts> $items
+     *
+     * @return MutableSet<Ts>
+     */
+    public static function fromItems(iterable $items): MutableSet
+    {
+        /**
+         * @psalm-suppress InvalidArgument
+         *
+         * @var array<Ts, Ts>
+         */
+        $array = iterator_to_array($items);
+        return self::fromArray($array);
+    }
+
     /**
      * Create a set from the given $elements array, using the keys of the array as the set values.
      *
@@ -219,6 +239,20 @@ public function contains(int|string $k): bool
         return array_key_exists($k, $this->elements);
     }
 
+    /**
+     * Alias of `contains`.
+     *
+     * @param T $k
+     *
+     * @return bool True if the value is in the set, false otherwise.
+     *
+     * @psalm-mutation-free
+     */
+    public function containsKey(int|string $k): bool
+    {
+        return $this->contains($k);
+    }
+
     /**
      * Returns the provided value if it is part of the set, or null if it is not.
      *

diff --git a/src/Psl/Collection/MutableVector.php b/src/Psl/Collection/MutableVector.php
@@ -14,6 +14,7 @@
 use function array_keys;
 use function array_values;
 use function count;
+use function iterator_to_array;
 
 /**
  * @template T
@@ -69,6 +70,26 @@ public static function fromArray(array $elements): MutableVector
         return new self($elements);
     }
 
+    /**
+     * Create a vector from the given $items iterable.
+     *
+     * @template Ts
+     *
+     * @param iterable<array-key, Ts> $items
+     *
+     * @return MutableVector<Ts>
+     */
+    public static function fromItems(iterable $items): MutableVector
+    {
+        /**
+         * @psalm-suppress InvalidArgument
+         *
+         * @var array<array-key, Ts>
+         */
+        $array = iterator_to_array($items);
+        return self::fromArray($array);
+    }
+
     /**
      * Returns the first value in the current `MutableVector`.
      *
@@ -189,6 +210,18 @@ public function contains(int|string $k): bool
         return array_key_exists($k, $this->elements);
     }
 
+    /**
+     * Alias of `contains`.
+     *
+     * @param int<0, max> $k
+     *
+     * @psalm-mutation-free
+     */
+    public function containsKey(int|string $k): bool
+    {
+        return $this->contains($k);
+    }
+
     /**
      * Returns the value at the specified key in the current `MutableVector`.
      *

diff --git a/src/Psl/Collection/Set.php b/src/Psl/Collection/Set.php
@@ -72,6 +72,26 @@ public static function fromArray(array $elements): Set
         return new self($elements);
     }
 
+    /**
+     * Create a set from the given items, using the keys of the array as the set values.
+     *
+     * @template Ts of array-key
+     *
+     * @param iterable<array-key, Ts> $items
+     *
+     * @return Set<Ts>
+     */
+    public static function fromItems(iterable $items): Set
+    {
+        /**
+         * @var array<array-key, Ts>
+         *
+         * @psalm-suppress InvalidArgument
+         */
+        $array = iterator_to_array($items);
+        return self::fromArray($array);
+    }
+
     /**
      * Create a set from the given $elements array, using the keys of the array as the set values.
      *
@@ -220,6 +240,20 @@ public function contains(int|string $k): bool
         return array_key_exists($k, $this->elements);
     }
 
+    /**
+     * Alias of `contains`.
+     *
+     * @param T $k
+     *
+     * @return bool True if the value is in the set, false otherwise.
+     *
+     * @psalm-mutation-free
+     */
+    public function containsKey(int|string $k): bool
+    {
+        return $this->contains($k);
+    }
+
     /**
      * Returns the provided value if it is part of the set, or null if it is not.
      *

diff --git a/src/Psl/Collection/Vector.php b/src/Psl/Collection/Vector.php
@@ -69,6 +69,26 @@ public static function fromArray(array $elements): Vector
         return new self($elements);
     }
 
+    /**
+     * Create a vector from the given $items iterable.
+     *
+     * @template Ts
+     *
+     * @param iterable<array-key, Ts> $items
+     *
+     * @return Vector<Ts>
+     */
+    public static function fromItems(iterable $items): Vector
+    {
+        /**
+         * @psalm-suppress InvalidArgument
+         *
+         * @var array<array-key, Ts>
+         */
+        $array = iterator_to_array($items);
+        return self::fromArray($array);
+    }
+
     /**
      * Returns the first value in the current `Vector`.
      *
@@ -190,6 +210,18 @@ public function contains(int|string $k): bool
         return array_key_exists($k, $this->elements);
     }
 
+    /**
+     * Alias of `contains`.
+     *
+     * @param int<0, max> $k
+     *
+     * @psalm-mutation-free
+     */
+    public function containsKey(int|string $k): bool
+    {
+        return $this->contains($k);
+    }
+
     /**
      * Returns the value at the specified key in the current `Vector`.
      *

diff --git a/tests/unit/Collection/AbstractMapTest.php b/tests/unit/Collection/AbstractMapTest.php
@@ -555,8 +555,9 @@ public function testContains(): void
         ]);
 
         static::assertTrue($map->contains('foo'));
+        static::assertTrue($map->containsKey('foo'));
         static::assertTrue($map->contains('bar'));
-        static::assertFalse($map->contains('baz'));
+        static::assertFalse($map->containsKey('baz'));
     }
 
     public function testGet(): void

diff --git a/tests/unit/Collection/AbstractSetTest.php b/tests/unit/Collection/AbstractSetTest.php
@@ -484,8 +484,10 @@ public function testContains(): void
         ]);
 
         static::assertTrue($vector->contains('hello'));
+        static::assertTrue($vector->containsKey('hello'));
         static::assertTrue($vector->contains('world'));
         static::assertFalse($vector->contains('foo'));
+        static::assertFalse($vector->containsKey('foo'));
     }
 
     public function testGet(): void

diff --git a/tests/unit/Collection/AbstractVectorTest.php b/tests/unit/Collection/AbstractVectorTest.php
@@ -529,7 +529,9 @@ public function testContains(): void
 
         static::assertTrue($vector->contains(0));
         static::assertTrue($vector->contains(1));
+        static::assertTrue($vector->containsKey(1));
         static::assertFalse($vector->contains(2));
+        static::assertFalse($vector->containsKey(2));
     }
 
     public function testGet(): void

diff --git a/tests/unit/Collection/MapTest.php b/tests/unit/Collection/MapTest.php
@@ -19,6 +19,19 @@ final class MapTest extends AbstractMapTest
      */
     protected string $vectorClass = Vector::class;
 
+    public function testFromItems(): void
+    {
+        $map = Map::fromItems([
+            'foo' => 'bar',
+            'bar' => 'baz',
+            'baz' => 'qux',
+        ]);
+
+        static::assertSame('bar', $map->at('foo'));
+        static::assertSame('baz', $map->at('bar'));
+        static::assertSame('qux', $map->at('baz'));
+    }
+
     /**
      * @template     Tk of array-key
      * @template     Tv

diff --git a/tests/unit/Collection/MutableMapTest.php b/tests/unit/Collection/MutableMapTest.php
@@ -153,7 +153,7 @@ public function testArrayAccess(): void
 
         static::assertTrue(isset($map['foo']));
         static::assertSame('1', $map['foo']);
-        
+
         unset($map['foo']);
         static::assertFalse(isset($map['foo']));
 
@@ -235,6 +235,19 @@ public function testOffsetGetThrowsForInvalidOffsetType(): void
         $map[false];
     }
 
+    public function testFromItems(): void
+    {
+        $map = MutableMap::fromItems([
+            'foo' => 'bar',
+            'bar' => 'baz',
+            'baz' => 'qux',
+        ]);
+
+        static::assertSame('bar', $map->at('foo'));
+        static::assertSame('baz', $map->at('bar'));
+        static::assertSame('qux', $map->at('baz'));
+    }
+
     /**
      * @template     Tk of array-key
      * @template     Tv

diff --git a/tests/unit/Collection/MutableSetTest.php b/tests/unit/Collection/MutableSetTest.php
@@ -191,6 +191,12 @@ public function testOffsetGetThrowsForInvalidOffsetType(): void
         $set[false];
     }
 
+    public function testFromItems(): void
+    {
+        $set = MutableSet::fromItems(['a', 'b', 'b', 'c']);
+        static::assertSame(['a' => 'a', 'b' => 'b', 'c' => 'c'], $set->toArray());
+    }
+
     public function testFromArrayKeysConstructor()
     {
         $set = MutableSet::fromArrayKeys(['foo' => 1, 'bar' => 1, 'baz' => 1]);