[Arr] deprecate duplicated functions

src/Psl/Arr/at.php

@@ -21,9 +21,12 @@
  * @psalm-pure
  *
  * @throws Psl\Exception\InvariantViolationException If $key is out-of-bounds.
+ *
+ * @deprecated use `$array[$key]` instead.
  */
 function at(array $array, $key)
 {
+    /** @psalm-suppress DeprecatedFunction */
     Psl\invariant(contains_key($array, $key), 'Key (%s) is out-of-bounds.', $key);
 
     /** @psalm-var Tv */

src/Psl/Arr/contains.php

@@ -4,6 +4,8 @@
 
 namespace Psl\Arr;
 
+use Psl\Iter;
+
 /**
  * Returns true if the given array contains the value. Strict equality is
  * used.
@@ -15,6 +17,10 @@
  * @psalm-param Tv              $value
  *
  * @psalm-pure
+ *
+ * @deprecated use `Iter\contains` instead.
+ *
+ * @see Iter\contains()
  */
 function contains(array $array, $value): bool
 {

src/Psl/Arr/contains_key.php

@@ -4,6 +4,8 @@
 
 namespace Psl\Arr;
 
+use Psl\Iter;
+
 use function array_key_exists;
 
 /**
@@ -16,6 +18,10 @@
  * @psalm-param Tk            $key
  *
  * @psalm-pure
+ *
+ * @deprecated use `Iter\contains_key()` instead.
+ *
+ * @see Iter\contains_key()
  */
 function contains_key(array $array, $key): bool
 {

src/Psl/Arr/count.php

@@ -30,7 +30,7 @@
  *
  * @psalm-pure
  *
- * @deprecated since 1.2, use Iter\count instead.
+ * @deprecated use Iter\count instead.
  *
  * @see Iter\count()
  */

src/Psl/Arr/count_values.php

@@ -4,38 +4,23 @@
 
 namespace Psl\Arr;
 
-use Psl;
-use Psl\Type;
+use Psl\Dict;
 
 /**
  * Returns a new array mapping each value to the number of times it appears
  * in the given array.
  *
  * @psalm-template T of array-key
  *
- * @psalm-param list<T> $values
+ * @psalm-param iterable<T> $values
  *
  * @psalm-return array<T, int>
  *
- * @psalm-pure
+ * @deprecated use `Dict\count_values` instead.
+ *
+ * @see Dict\count_values()
  */
-function count_values(array $values): array
+function count_values(iterable $values): array
 {
-    /** @psalm-var array<T, int> $result */
-    $result = [];
-
-    foreach ($values as $value) {
-        Psl\invariant(
-            Type\is_arraykey($value),
-            'Expected all values to be of type array-key, value of type (%s) provided.',
-            gettype($value)
-        );
-
-        /** @psalm-var int $count */
-        $count = idx($result, $value, 0);
-        /** @psalm-var T $value */
-        $result[$value] = $count + 1;
-    }
-
-    return $result;
+    return Dict\count_values($values);
 }

src/Psl/Arr/fill.php

@@ -4,6 +4,8 @@
 
 namespace Psl\Arr;
 
+use Psl\Vec;
+
 use function array_fill;
 
 /**
@@ -16,6 +18,10 @@
  * @psalm-return array<int, T>
  *
  * @psalm-pure
+ *
+ * @deprecated use `Vec\fill` instead.
+ *
+ * @see Vec\fill()
  */
 function fill($value, int $start_index, int $num): array
 {

src/Psl/Arr/filter_nulls.php

@@ -19,7 +19,9 @@
  *
  * @psalm-return list<T>
  *
- * @deprecated since 1.2, use Vec\filter_nulls instead.
+ * @deprecated use `Vec\filter_nulls` instead.
+ *
+ * @see Vec\filter_nulls()
  */
 function filter_nulls(iterable $iterable): array
 {

src/Psl/Arr/first.php

@@ -4,6 +4,8 @@
 
 namespace Psl\Arr;
 
+use Psl\Iter;
+
 /**
  * Get the first value of an array, If the array is empty, null will be returned.
  *
@@ -15,12 +17,22 @@
  * @psalm-return Tv|null
  *
  * @psalm-pure
+ *
+ * @deprecated use `Iter\first()` instead.
+ *
+ * @see Iter\first()
  */
 function first(array $array)
 {
-    /** @psalm-var Tk|null $first */
+    /**
+     * @psalm-var Tk|null $first
+     * @psalm-suppress DeprecatedFunction
+     */
     $first = first_key($array);
 
-    /** @psalm-var Tv|null */
-    return null !== $first ? at($array, $first) : null;
+    if (null === $first) {
+        return null;
+    }
+
+    return $array[$first];
 }

src/Psl/Arr/first_key.php

@@ -4,6 +4,8 @@
 
 namespace Psl\Arr;
 
+use Psl\Iter;
+
 use function array_key_first;
 
 /**
@@ -16,6 +18,10 @@
  * @psalm-return Tk|null
  *
  * @psalm-pure
+ *
+ * @deprecated use `Iter\first_key` instead.
+ *
+ * @see Iter\first_key()
  */
 function first_key(array $array)
 {

src/Psl/Arr/firstx.php

@@ -5,6 +5,7 @@
 namespace Psl\Arr;
 
 use Psl;
+use Psl\Iter;
 
 /**
  * Get the first value of an array, If the array is empty, an InvariantViolationException
@@ -20,13 +21,19 @@
  * @psalm-pure
  *
  * @throws Psl\Exception\InvariantViolationException If $array is empty.
+ *
+ * @deprecated use `Iter\first` instead.
+ *
+ * @see Iter\first()
  */
 function firstx(array $array)
 {
-    /** @psalm-var Tk|null $first */
+    /**
+     * @psalm-var Tk|null $first
+     * @psalm-suppress DeprecatedFunction
+     */
     $first = first_key($array);
     Psl\invariant(null !== $first, 'Expected a non-empty array.');
 
-    /** @psalm-var Tv */
-    return at($array, $first);
+    return $array[$first];
 }

src/Psl/Arr/flat_map.php

@@ -16,7 +16,9 @@
  *
  * @psalm-return list<T>
  *
- * @deprecated since 1.2, use Vec\flat_map instead.
+ * @deprecated use `Vec\flat_map` instead.
+ *
+ * @see Vec\flat_map()
  */
 function flat_map(iterable $iterable, callable $mapper): array
 {

src/Psl/Arr/flatten.php

@@ -29,7 +29,7 @@
  *
  * @deprecated use `Dict\flatten` instead.
  *
- * @see Dict\flatten
+ * @see Dict\flatten()
  */
 function flatten(iterable $iterables): array
 {

src/Psl/Arr/flip.php

@@ -24,7 +24,7 @@
  *
  * @deprecated use `Dict\flip` instead.
  *
- * @see Dict\flip
+ * @see Dict\flip()
  */
 function flip(array $array): array
 {

src/Psl/Arr/group_by.php

@@ -37,9 +37,9 @@
  *
  * @psalm-return array<Tk, list<Tv>>
  *
- * @deprecated use Dict\group_by
+ * @deprecated use `Dict\group_by` instead.
  *
- * @see Dict\group_by
+ * @see Dict\group_by()
  */
 function group_by(iterable $values, callable $key_func): array
 {

src/Psl/Arr/idx.php

@@ -29,9 +29,12 @@
  * @psalm-return   Tv
  *
  * @psalm-pure
+ *
+ * @deprecated use `$array[$index] ?? $default` instead.
  */
 function idx(array $array, $index, $default = null)
 {
+    /** @psalm-suppress DeprecatedFunction */
     if (contains_key($array, $index)) {
         return $array[$index];
     }

src/Psl/Arr/keys.php

@@ -16,7 +16,7 @@
  *
  * @psalm-return list<Tk>
  *
- * @deprecated since 1.2, use Vec\keys instead.
+ * @deprecated use `Vec\keys` instead.
  *
  * @see Vec\keys()
  */

src/Psl/Arr/last.php

@@ -4,6 +4,8 @@
 
 namespace Psl\Arr;
 
+use Psl\Iter;
+
 /**
  * Get the last value of an array, if the array is empty, returns null.
  *
@@ -15,15 +17,21 @@
  * @psalm-return Tv|null
  *
  * @psalm-pure
+ *
+ * @deprecated use `Iter\last` instead.
+ *
+ * @see Iter\last()
  */
 function last(array $array)
 {
-    /** @psalm-var Tk|null $last */
+    /**
+     * @psalm-var Tk|null $last
+     * @psalm-suppress DeprecatedFunction
+     */
     $last = last_key($array);
     if (null === $last) {
         return null;
     }
 
-    /** @psalm-suppress MissingThrowsDocblock - we are sure that $last is within-bounds. */
-    return at($array, $last);
+    return $array[$last];
 }

src/Psl/Arr/last_key.php

@@ -4,6 +4,8 @@
 
 namespace Psl\Arr;
 
+use Psl\Iter;
+
 use function array_key_last;
 
 /**
@@ -17,6 +19,10 @@
  * @psalm-return Tk|null
  *
  * @psalm-pure
+ *
+ * @deprecated use `Iter\last_key` instead.
+ *
+ * @see Iter\last_key()
  */
 function last_key(array $array)
 {

src/Psl/Arr/lastx.php

@@ -5,6 +5,7 @@
 namespace Psl\Arr;
 
 use Psl;
+use Psl\Iter;
 
 /**
  * Get the last value of an array, If the array is empty, an InvariantViolationException
@@ -20,13 +21,19 @@
  * @psalm-pure
  *
  * @throws Psl\Exception\InvariantViolationException If $array is empty.
+ *
+ * @deprecated use `Iter\last` instead.
+ *
+ * @see Iter\last()
  */
 function lastx(array $array)
 {
-    /** @psalm-var Tk|null $last */
+    /**
+     * @psalm-var Tk|null $last
+     * @psalm-suppress DeprecatedFunction
+     */
     $last = last_key($array);
     Psl\invariant(null !== $last, 'Expected a non-empty array.');
 
-    /** @psalm-var Tv */
-    return at($array, $last);
+    return $array[$last];
 }