README

Jitsu\ArrayUtil 类是一组用于处理PHP数组中的静态方法。

为什么？因为许多PHP内置的数组函数名称复杂且接口不友好。

ArrayUtil 解决这些问题，提供了一个更直观的接口来访问标准PHP数组函数，同时提供了内置库中缺少的功能。

此包是 Jitsu 的一部分。

安装

使用 Composer 安装此包

composer require jitsu/array

测试

按照以下方式运行单元测试套件

composer install
./vendor/bin/phpunit test/

命名空间

该类在 Jitsu 命名空间下定义。

API

class Jitsu\ArrayUtil

处理数组的静态方法集合。

ArrayUtil::size($array)

返回数组中的键值对数量。

ArrayUtil::length($array)

size 的别名。请参阅 \jitsu\ArrayUtil::size()。

ArrayUtil::isEmpty($array)

返回数组是否为空。

ArrayUtil::get($array, $key, $default = null)

获取数组元素或默认值。

检索数组中存储在键下的值，如果键不存在，则返回默认值。

ArrayUtil::hasKey($array, $key)

返回数组是否包含某个键。

与 isset 不同，即使值是 null，此方法也有效。

对于整数键，使用字符串等效值进行测试仍会返回 true。

ArrayUtil::normalizeKey($k)

将任意字符串或整数转换为PHP数组键等效。

PHP数组通过将所有无多余前导0的十进制数字字符串转换为它们的整数等效来标准化其键。整数始终保持不变。重要的是要记住，将键插入数组可能会改变其类型，这可能在稍后从数组检索该键时执行严格比较时产生后果。例如

$a = array();
$k = '123';
$a[$k] = 456;
$keys = array_keys($a);
echo ($keys[0] === $k); // suprisingly, this is false

在这种情况下，可以使用 normalizeKey 确保任意字符串值可以进行严格比较。

echo ($keys[0] === \Jitsu\ArrayUtil::normalizeKey($k)); // true

ArrayUtil::remove(&$array, $key)

从数组中删除一个键。

删除不存在的键不是错误。

ArrayUtil::keys($array)

列出数组中的所有键。

ArrayUtil::values($array)

以序列数组的形式列出数组中的值。

ArrayUtil::listValues($array, $keys, $default = null)

按顺序获取数组中给定键列表下的值。

ArrayUtil::requireValues($array, $keys)

按顺序获取数组中给定必需键列表下的值。

ArrayUtil::first($array)

获取顺序数组中的第一个元素。

如果数组为空，则返回 null。

ArrayUtil::last($array)

获取顺序数组中的最后一个元素。

如果数组为空，则返回 null。

ArrayUtil::append(&$array, $value)

将值追加到顺序数组的末尾。

请注意，这相当于更简洁的 $array[] = $value。

ArrayUtil::appendMany(&$array1, $array2)

将值列表追加到数组中。

ArrayUtil::concat($array1, $array2)

连接两个顺序数组。

这不会在关联数组上按预期工作。

ArrayUtil::push(&$array, $value)

是append的别名。参见\jitsu\ArrayUtil::append()。

ArrayUtil::pop(&$array)

从数组的末尾弹出值。

如果数组为空，则返回null。

ArrayUtil::shift(&$array)

从数组的开头移除一个元素。

如果数组为空，则返回null。重新索引顺序数组。

ArrayUtil::unshift(&$array, $value)

将值添加到数组的开头。

重新索引顺序数组。

ArrayUtil::keyOf($array, $value)

通过线性搜索使用值查找键。

返回第一个值严格等于给定值的键。如果该值不存在于数组中，则返回null。适用于关联数组和顺序数组。

ArrayUtil::indexOf($array, $value)

参见\jitsu\ArrayUtil::keyOf()。

ArrayUtil::keysOf($array, $value)

找到映射到特定值的数组中的所有键。

返回一个顺序数组，其中包含数组中所有值严格等于给定值的键。使用线性搜索。

ArrayUtil::contains($array, $value)

使用线性搜索确定数组是否包含一个值。

使用严格比较。

ArrayUtil::at($array, $i)

获取数组中某个位置上的值。

注意，这与通过键查找值完全不同。而是根据键值对的内部顺序查找偏移量。

关于“内部顺序”的讨论可能需要一些解释。尽管如此，PHP中的array类型实际上实现了一个有序字典数据结构。所有数组，无论是顺序数组还是关联数组，都记录了键到值的映射以及这些键值对插入的顺序。顺序数组只是一个键值正好与其顺序相对应的数组。这种顺序决定了foreach循环遍历数组元素的方式，以及其他行为。此函数利用这种内部顺序并在常数时间内通过位置查找元素。

ArrayUtil::pairAt($array, $i)

获取数组中某个位置上的键值对。

参见\jitsu\ArrayUtil::at()。

ArrayUtil::keyAt($array, $i)

获取数组中某个位置上的键。

参见\jitsu\ArrayUtil::at()。

ArrayUtil::slice($array, $i, $j = null)

获取数组的切片。

负索引表示从数组末尾的偏移量。

根据数组的顺序切片。顺序数组的切片将重新索引。

ArrayUtil::pairSlice($array, $i, $j = null)

获取数组切片的同时保留数字键。

类似于\jitsu\ArrayUtil::slice()，但即使对于顺序数组也保留键。

参见\jitsu\ArrayUtil::slice()。

ArrayUtil::assignSlice(&$array, $sub, $i, $j = null)

用值列表替换数组的切片。

参见\jitsu\ArrayUtil::slice()。

ArrayUtil::removeSlice(&$array, $i, $j = null)

从数组中移除切片。

参见\jitsu\ArrayUtil::slice()。

ArrayUtil::reverse($array)

获取顺序数组的反转和重新索引副本。

ArrayUtil::reversePairs($array)

获取一个数组的副本，其键值对的顺序被反转。

ArrayUtil::range($i, $j = null, $step = 1)

生成一个由数字范围组成的顺序数组。

可以指定步长大小。

如果所有参数都是整数或未指定，则结果将包含在范围 [$i, $j) 内的整数，其中端点是非包含的。

否则，结果将包含在范围 [$i, $j] 内的数字，包含端点。

如果只提供了第一个参数，则它作为结束索引，假定偏移量为0，步长为1。

任何参数都可以是负数。如果区间的开始发生在结束之后，则返回空列表。使用步长0是错误的。可以使用大于区间大小的步长。

ArrayUtil::fromPairs($pairs)

从键值对列表中构造关联数组。

ArrayUtil::fromLists($keys, $values)

从键数组和值数组中构建一个关联数组。

ArrayUtil::toSet($array, $value = true)

将值列表哈希到关联数组的键中。

这返回一个关联数组，将 $array 的值映射到 true。这种结构可以用来高效地测试元素的成员资格，就像一个集合。

ArrayUtil::fill($value, $n)

生成一个包含 $value 的 $n 个副本的顺序数组。

ArrayUtil::pad($array, $value, $n)

使用 $value 的副本填充顺序数组。

ArrayUtil::pluck($arrays, $key)

给定一个数组列表，列出所有特定键下的值。

返回一个顺序数组，包含在数组列表中特定键下的所有值。当该键在数组中缺失时，该数组被简单地跳过。

ArrayUtil::pick($array, $keys)

使用键列表选择数组的一部分。

返回具有列表中键的所有键值对。结果以键的顺序返回为一个关联数组。不存在的键将被省略。

ArrayUtil::getPick($array, $keys, $default = null)

类似于 pick，但对于缺失的键使用默认值。

ArrayUtil::invert($array)

反转数组的键值对。

反转数组，使其值成为键，反之亦然。当然，尝试反转包含非整数或非字符串值的数组是一个错误。

ArrayUtil::extend($array1, $array2)

将两个数组的键值对合并为一个。

第二个数组的值优先于第一个数组。

ArrayUtil::deepExtend($array1, $array2)

递归地合并两个数组结构。

第二个数组结构的值优先于第一个数组。

参见 \jitsu\ArrayUtil::extend()。

ArrayUtil::chunks($array, $n)

将数组的值拆分为特定大小的块。

返回一个顺序数组，包含作为顺序数组的值块。最后一个块可能少于 $n 个元素。根据顺序拆分。不保留关联数组键，而是总是重新索引每个块。

ArrayUtil::map($array, $callback)

对一个数组的值应用一个函数以生成一个新的数组。

保留键。

ArrayUtil::filter($array, $callback = null)

通过谓词过滤数组的值以生成一个新的数组。

保留键（不重新索引顺序数组）。

ArrayUtil::filterPairs($array, $callback)

通过谓词过滤数组的键值对以生成一个新的数组。

ArrayUtil::sum($array)

取数组的值的总和。

ArrayUtil::product($array)

取数组的值的乘积。

ArrayUtil::reduce($array, $callback, $initial = null)

使用二元函数减少数组的值。

ArrayUtil::apply(&$array, $callback)

对数组中的每个元素调用回调函数。

ArrayUtil::traverseLeaves(&$array, $callback)

执行嵌套数组结构的有序遍历。

ArrayUtil::difference($array1, $array2, $key_cmp = null, $value_cmp = true)

获取一个数组中存在但另一个数组中不存在的键值对。

返回一个关联数组，包含第一个数组中存在但第二个数组中不存在的所有键值对，根据通过 $key_cmp 和 $value_cmp 传递的值的一些唯一标准来确定。$key_cmp 和 $value_cmp 都可以是 null、true 或比较回调函数，并分别用于比较数组元素的键和值。如果比较器是 null，则忽略其组件。如果比较器是 true，则使用默认的字符串比较方法用于该组件。否则，可以使用实现任意比较函数的回调函数。默认情况下，忽略键并通过字符串比较比较值。

ArrayUtil::pairDifference($array1, $array2, $key_cmp = null, $value_cmp = null)

获取只存在于一个数组中但不存在于另一个数组中的键值对，其中键和值均决定唯一性。

返回一个关联数组，包含所有存在于第一个数组但不存在于第二个数组的键值对。可以提供键和值的比较函数。默认使用字符串比较。

ArrayUtil::keyDifference($array1, $array2, $key_cmp = null)

获取只存在于一个数组中但不存在于另一个数组中的键值对，其中只有键决定唯一性。

返回一个关联数组，包含所有存在于第一个数组但第二个数组中不存在其键的键值对。可以提供键的比较函数。默认使用字符串比较。

ArrayUtil::valueDifference($array1, $array2, $value_cmp = null)

获取只存在于一个数组中但不存在于另一个数组中的键值对，其中只有值决定唯一性。

返回一个关联数组，包含所有存在于第一个数组但第二个数组中不存在其值的键值对。可以提供值的比较函数。默认使用字符串比较。

ArrayUtil::pairIntersection($array1, $array2, $key_cmp = null, $value_cmp = null)

获取存在于两个数组中的键值对。

返回一个关联数组，其键值对存在于两个数组中。默认使用字符串比较值。可以提供键和值的比较函数。

ArrayUtil::keyIntersection($array1, $array2, $key_cmp = null)

获取存在于两个数组中的键值对，其中只有键决定唯一性。

返回一个关联数组，包含所有第一个数组中的键存在于第二个数组中的键值对。可以提供键的比较函数。

ArrayUtil::valueIntersection($array1, $array2, $value_cmp = null)

获取存在于两个数组中的键值对，其中只有值决定唯一性。

返回一个关联数组，包含所有第一个数组中的值存在于第二个数组中的键值对。默认使用字符串比较。可以提供值的比较函数。

ArrayUtil::uniqueValues($array)

获取数组中所有唯一的值，去重。

从数组中移除所有值与其他数组中较早出现的值重复的键值对。比较是非严格的。键被保留。

ArrayUtil::hasOnlyKeys($array, $keys, &$unexpected = null)

确定数组是否只包含给定列表中的键。

ArrayUtil::hasKeys($array, $keys, &$missing = null)

确定数组是否包含给定列表中的所有键。

ArrayUtil::hasExactKeys($array, $keys, &$unexpected = null, &$missing = null)

确定数组是否包含给定列表中的所有键。

ArrayUtil::randomKey($array)

从数组中随机选择一个键。

ArrayUtil::randomValue($array)

从数组中随机选择一个值。

ArrayUtil::randomPair($array)

从数组中随机选择一个键值对。

ArrayUtil::randomKeys($array, $n)

从数组中随机选择$n个键。

ArrayUtil::shuffle(&$array)

就地随机打乱并重新索引数组的值。

ArrayUtil::sort(&$array, $value_cmp = null)

就地排序并重新索引数组的值。

ArrayUtil::reverseSort(&$array)

就地排序并重新索引数组的值，反向。

ArrayUtil::localeSort(&$array)

就地根据当前区域规则对字符串数组进行排序。

ArrayUtil::sortPairs(&$array, $value_cmp = null)

就地根据值对数组的键值对进行排序。

与sort类似，但保留键。

ArrayUtil::reverseSortPairs(&$array)

在原地对数组中的键值对根据其值进行降序排序。

ArrayUtil::sortKeys(&$array, $key_cmp = null)

在原地对数组中的键值对根据其键进行排序。

ArrayUtil::reverseSortKeys(&$array)

在原地对数组中的键值对根据其键进行降序排序。

ArrayUtil::humanSortValues(&$array)

在原地对字符串数组根据其值以人类可理解的方式进行排序。

ArrayUtil::iHumanSortValues(&$array)

在原地对字符串数组根据其值以人类可理解的方式进行排序，忽略大小写。

ArrayUtil::lowerKeys($array)

将数组中的键转换为小写。

ArrayUtil::upperKeys($array)

将数组中的键转换为大写。

ArrayUtil::isSequential($array)

确定一个值是否是顺序数组。

检查该值是否是一个键与其顺序完全一致的数组。

注意：由于此函数的复杂度与数组大小成线性关系，应避免使用。

ArrayUtil::isAssociative($array)

确定一个值是否是关联数组。

注意：由于此函数的复杂度与数组大小成线性关系，应避免使用。

参见 \Jitsu\ArrayUtil::isSequential()。

ArrayUtil::looksSequential($array)

高效猜测一个值是否是顺序数组。

在常数时间内猜测一个值是否看似顺序数组。这仅仅检查一个值是否是一个数组，其第一个键是0或一个空数组。

主要用于实现重载函数。

ArrayUtil::looksAssociative($array)

高效猜测一个值是否是关联数组。

在常数时间内猜测一个值是否看似关联数组。这仅仅检查数组中的第一个键是否不是0。注意，空数组既被视为顺序数组，也视为关联数组。

主要用于实现重载函数。

ArrayUtil::countValues($array)

统计数组中每个值的出现次数。

计算数组中每个值出现的次数，并生成一个关联数组，将那些值映射到它们的频率。当然，这限制了数组值只能是字符串和整数。