feat(collections): add fromItems and containsKey

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.
      *

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.
      *

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.
      *

src/Psl/Collection/MutableSet.php

@@ -71,6 +71,20 @@ 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> $items
+     *
+     * @return MutableSet<Ts>
+     */
+    public static function fromItems(iterable $items): MutableSet
+    {
+        return self::fromArray(iterator_to_array($items));
+    }
+
     /**
      * Create a set from the given $elements array, using the keys of the array as the set values.
      *
@@ -219,6 +233,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.
      *

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,20 @@ public static function fromArray(array $elements): MutableVector
         return new self($elements);
     }
 
+    /**
+     * Create a vector from the given $items iterable.
+     *
+     * @template Ts
+     *
+     * @param iterable<Ts> $items
+     *
+     * @return MutableVector<Ts>
+     */
+    public static function fromItems(iterable $items): MutableVector
+    {
+        return self::fromArray(iterator_to_array($items));
+    }
+
     /**
      * Returns the first value in the current `MutableVector`.
      *
@@ -189,6 +204,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`.
      *

src/Psl/Collection/Set.php

@@ -72,6 +72,22 @@ 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<Ts, mixed> $items
+     *
+     * @return Set<Ts>
+     *
+     * @pure
+     */
+    public static function fromItems(iterable $items): Set
+    {
+        return self::fromArray(iterator_to_array($items));
+    }
+
     /**
      * Create a set from the given $elements array, using the keys of the array as the set values.
      *
@@ -220,6 +236,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.
      *

src/Psl/Collection/Vector.php

@@ -69,6 +69,20 @@ public static function fromArray(array $elements): Vector
         return new self($elements);
     }
 
+    /**
+     * Create a vector from the given $items iterable.
+     *
+     * @template Ts
+     *
+     * @param iterable<Ts> $items
+     *
+     * @return Vector<Ts>
+     */
+    public static function fromItems(iterable $items): Vector
+    {
+        return self::fromArray(iterator_to_array($items));
+    }
+
     /**
      * Returns the first value in the current `Vector`.
      *
@@ -190,6 +204,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`.
      *

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

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

tests/unit/Collection/MutableSetTest.php

@@ -109,7 +109,7 @@ public function testArrayAccess(): void
 
         static::assertTrue(isset($set['foo']));
         static::assertSame('foo', $set['foo']);
-        
+
         unset($set['foo']);
         static::assertFalse(isset($set['foo']));
 
@@ -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());
+    }
+
     /**
      * @template T of array-key
      *

tests/unit/Collection/MutableVectorTest.php

@@ -149,7 +149,7 @@ public function testArrayAccess(): void
 
         static::assertTrue(isset($vector[0]));
         static::assertSame('foo', $vector[0]);
-        
+
         unset($vector[0]);
         static::assertFalse(isset($vector[2]));
 
@@ -230,6 +230,11 @@ public function testOffsetGetThrowsForInvalidOffsetType(): void
         $vector[false];
     }
 
+    public function testFromItems(): void
+    {
+        $vector = MutableVector::fromItems([1, 2, 3]);
+        static::assertSame([1, 2, 3], $vector->toArray());
+    }
 
     /**
      * @template     T

tests/unit/Collection/SetTest.php

@@ -15,6 +15,19 @@ final class SetTest extends AbstractSetTest
      */
     protected string $setClass = Set::class;
 
+    public function testFromItems(): void
+    {
+        $set = Set::fromItems([
+            'foo',
+            'bar',
+            'baz',
+        ]);
+
+        static::assertTrue($set->contains('foo'));
+        static::assertTrue($set->contains('bar'));
+        static::assertTrue($set->contains('baz'));
+    }
+
     /**
      * @template T of array-key
      *

tests/unit/Collection/VectorTest.php

@@ -15,6 +15,12 @@ final class VectorTest extends AbstractVectorTest
      */
     protected string $vectorClass = Vector::class;
 
+    public function testFromItems(): void
+    {
+        $vector = Vector::fromItems([1, 2, 3]);
+        static::assertSame([1, 2, 3], $vector->toArray());
+    }
+
     /**
      * @template T
      *