[Vec] Introduce vec component

src/Psl/Arr/concat.php

@@ -4,6 +4,8 @@
 
 namespace Psl\Arr;
 
+use Psl\Vec;
+
 /**
  * Returns a new array formed by concatenating the given arrays together.
  *
@@ -13,17 +15,12 @@
  * @psalm-param iterable<T> ...$rest
  *
  * @psalm-return list<T>
+ *
+ * @deprecated since 1.2, use Vec\concat instead.
+ *
+ * @see Vec\concat()
  */
 function concat(array $first, iterable ...$rest): array
 {
-    /** @psalm-var list<T> $first */
-    $first = values($first);
-
-    foreach ($rest as $arr) {
-        foreach ($arr as $value) {
-            $first[] = $value;
-        }
-    }
-
-    return $first;
+    return Vec\concat($first, ...$rest);
 }

src/Psl/Arr/count.php

@@ -4,6 +4,8 @@
 
 namespace Psl\Arr;
 
+use Psl\Iter;
+
 /**
  * Returns the number of elements an array contains.
  *
@@ -27,6 +29,10 @@
  * @psalm-param array<Tk, Tv> $array
  *
  * @psalm-pure
+ *
+ * @deprecated since 1.2, use Iter\count instead.
+ *
+ * @see Iter\count()
  */
 function count(array $array): int
 {

src/Psl/Arr/equal.php

@@ -4,6 +4,8 @@
 
 namespace Psl\Arr;
 
+use Psl\Iter;
+
 /**
  * Returns whether the two given arrays have the same entries, using strict
  * equality. To guarantee equality of order as well as contents, use `===`.
@@ -13,16 +15,14 @@
  *
  * @psalm-param array<Tk, Tv> $array
  * @psalm-param array<Tk, Tv> $array2
- *
- * @psalm-pure
  */
 function equal(array $array, array $array2): bool
 {
     if ($array === $array2) {
         return true;
     }
 
-    if (count($array) !== count($array2)) {
+    if (Iter\count($array) !== Iter\count($array2)) {
         return false;
     }
 

src/Psl/Arr/filter_nulls.php

@@ -4,6 +4,8 @@
 
 namespace Psl\Arr;
 
+use Psl\Vec;
+
 /**
  * Filter out null values from the given iterable.
  *
@@ -16,16 +18,10 @@
  * @psalm-param iterable<T|null> $iterable
  *
  * @psalm-return list<T>
+ *
+ * @deprecated since 1.2, use Vec\filter_nulls instead.
  */
 function filter_nulls(iterable $iterable): array
 {
-    /** @psalm-var list<T> $result */
-    $result = [];
-    foreach ($iterable as $value) {
-        if (null !== $value) {
-            $result[] = $value;
-        }
-    }
-
-    return $result;
+    return Vec\filter_nulls($iterable);
 }

src/Psl/Arr/flat_map.php

@@ -4,6 +4,8 @@
 
 namespace Psl\Arr;
 
+use Psl\Vec;
+
 /**
  * @psalm-template Tk of array-key
  * @psalm-template Tv
@@ -13,15 +15,10 @@
  * @psalm-param (callable(Tv): iterable<T>) $mapper
  *
  * @psalm-return list<T>
+ *
+ * @deprecated since 1.2, use Vec\flat_map instead.
  */
 function flat_map(iterable $iterable, callable $mapper): array
 {
-    $flattened = [];
-    foreach ($iterable as $value) {
-        foreach ($mapper($value) as $item) {
-            $flattened[] = $item;
-        }
-    }
-
-    return $flattened;
+    return Vec\flat_map($iterable, $mapper);
 }

src/Psl/Arr/keys.php

@@ -4,7 +4,7 @@
 
 namespace Psl\Arr;
 
-use function array_keys;
+use Psl\Vec;
 
 /**
  * Return all the keys of an array.
@@ -16,9 +16,9 @@
  *
  * @psalm-return list<Tk>
  *
- * @psalm-pure
+ * @deprecated since 1.2, use Vec\keys instead.
  */
 function keys(array $arr): array
 {
-    return array_keys($arr);
+    return Vec\keys($arr);
 }

src/Psl/Arr/random.php

@@ -5,7 +5,9 @@
 namespace Psl\Arr;
 
 use Psl;
+use Psl\Iter;
 use Psl\PseudoRandom;
+use Psl\Vec;
 
 /**
  * Retrieve a random value from a non-empty array.
@@ -21,12 +23,13 @@
  */
 function random(array $values)
 {
-    Psl\invariant(0 !== count($values), 'Expected a non-empty-array.');
+    $size = Iter\count($values);
+
+    Psl\invariant(0 !== $size, 'Expected a non-empty-array.');
 
     /** @psalm-var list<Tv> $shuffled */
-    $shuffled = namespace\shuffle($values);
+    $shuffled = Vec\shuffle($values);
 
-    $size = namespace\count($values);
 
     if (1 === $size) {
         /** @psalm-var Tv */

src/Psl/Arr/shuffle.php

@@ -4,7 +4,7 @@
 
 namespace Psl\Arr;
 
-use Psl;
+use Psl\Vec;
 
 /**
  * Shuffle the given array.
@@ -14,7 +14,7 @@
  *      Arr\shuffle([1, 2, 3])
  *      => Arr(2, 3, 1)
  *
- *      Arr\shuffle('a' => 1, 'b' => 2, 'c' => 3)
+ *      Arr\shuffle(['a' => 1, 'b' => 2, 'c' => 3])
  *      => Arr(2, 3, 1)
  *
  * @psalm-template Tk of array-key
@@ -24,13 +24,11 @@
  *
  * @psalm-return list<Tv> the shuffled array.
  *
- * @psalm-pure
+ * @deprecated since 1.2, use Vec\shuffle instead.
+ *
+ * @see Vec\shuffle()
  */
 function shuffle(array $array): array
 {
-    $shuffled = \shuffle($array);
-    /** @psalm-suppress MissingThrowsDocblock */
-    Psl\invariant($shuffled, 'Unexpected error');
-
-    return $array;
+    return Vec\shuffle($array);
 }

src/Psl/Arr/sort.php

@@ -4,31 +4,24 @@
 
 namespace Psl\Arr;
 
-use function sort as php_sort;
-use function usort;
+use Psl\Vec;
 
 /**
- * Returns a new array sorted by the values of the given array.
+ * Returns a new list sorted by the values of the given iterable.
  *
  * If the optional comparator function isn't provided, the values will be sorted in
  * ascending order.
  *
- * @psalm-template Tk of array-key
- * @psalm-template Tv
+ * @psalm-template T
  *
- * @psalm-param array<Tk, Tv>                  $array
- * @psalm-param (callable(Tv, Tv): int)|null   $comparator
+ * @psalm-param iterable<T>                  $array
+ * @psalm-param (callable(T, T): int)|null   $comparator
  *
+ * @psalm-return list<T>
  *
- * @psalm-return list<Tv>
+ * @deprecated since 1.2, use Vec\sort instead.
  */
-function sort(array $array, ?callable $comparator = null): array
+function sort(iterable $array, ?callable $comparator = null): array
 {
-    if (null !== $comparator) {
-        usort($array, $comparator);
-    } else {
-        php_sort($array);
-    }
-
-    return $array;
+    return Vec\sort($array, $comparator);
 }

src/Psl/Arr/sort_by.php

@@ -4,47 +4,27 @@
 
 namespace Psl\Arr;
 
-use function asort;
-use function uasort;
+use Psl\Vec;
 
 /**
- * Returns a new array sorted by some scalar property of each value of the given
+ * Returns a new list sorted by some scalar property of each value of the given
  * iterable, which is computed by the given function.
  *
  * If the optional comparator function isn't provided, the values will be sorted
  * in ascending order of scalar key.
  *
- * @psalm-template Tk of array-key
  * @psalm-template Tv
  * @psalm-template Ts
  *
- * @psalm-param iterable<Tk, Tv>               $iterable
+ * @psalm-param iterable<Tv>                   $iterable
  * @psalm-param (callable(Tv): Ts)             $scalar_func
  * @psalm-param (callable(Ts, Ts): int)|null   $comparator
  *
  * @psalm-return list<Tv>
+ *
+ * @deprecated since 1.2, use Vec\sort_by instead.
  */
 function sort_by(iterable $iterable, callable $scalar_func, ?callable $comparator = null): array
 {
-    /** @psalm-var array<Tk, Ts> $order_by */
-    $order_by = [];
-    /** @psalm-var array<Tk, Tv> $values */
-    $original_values = [];
-    foreach ($iterable as $k => $v) {
-        $original_values[$k] = $v;
-        $order_by[$k] = $scalar_func($v);
-    }
-
-    if (null !== $comparator) {
-        uasort($order_by, $comparator);
-    } else {
-        asort($order_by);
-    }
-
-    $result = [];
-    foreach ($order_by as $k => $_) {
-        $result[] = $original_values[$k];
-    }
-
-    return $result;
+    return Vec\sort_by($iterable, $scalar_func, $comparator);
 }

src/Psl/Arr/values.php

@@ -4,6 +4,8 @@
 
 namespace Psl\Arr;
 
+use Psl\Vec;
+
 use function array_values;
 
 /**
@@ -16,6 +18,10 @@
  * @psalm-return   list<T>
  *
  * @psalm-pure
+ *
+ * @deprecated since 1.2, use Vec\values instead.
+ *
+ * @see Vec\values()
  */
 function values(array $arr): array
 {

src/Psl/Collection/Map.php

@@ -7,6 +7,7 @@
 use Psl;
 use Psl\Arr;
 use Psl\Iter;
+use Psl\Vec;
 
 /**
  * @template Tk of array-key
@@ -121,7 +122,7 @@ public function isEmpty(): bool
      */
     public function count(): int
     {
-        return Arr\count($this->elements);
+        return Iter\count($this->elements);
     }
 
     /**
@@ -189,7 +190,7 @@ public function get($k)
      */
     public function values(): Vector
     {
-        return new Vector(Arr\values($this->elements));
+        return new Vector(Vec\values($this->elements));
     }
 
     /**
@@ -199,7 +200,7 @@ public function values(): Vector
      */
     public function keys(): Vector
     {
-        return new Vector(Iter\keys($this->elements));
+        return new Vector(Vec\keys($this->elements));
     }
 
     /**