README

PHP数组和集合变得简单

通过使用类似jQuery和Laravel集合对象提供的类似数组集合对象轻松优雅地处理PHP数组。

composer req aimeos/map

支持的PHP版本

PHP 7.1+
PHP 8+

为什么选择PHP Map
方法列表
- 创建
- 访问
- 添加
- 聚合
- 调试
- 排序
- 缩短
- 测试
- 转换
- 其他
文档
自定义方法
性能
升级指南

为什么选择PHP Map

代替

$list = [['id' => 'one', 'value' => 'value1'], ['id' => 'two', 'value' => 'value2'], null];
$list[] = ['id' => 'three', 'value' => 'value3'];    // add element
unset( $list[0] );                                   // remove element
$list = array_filter( $list );                       // remove empty values
sort( $list );                                       // sort elements
$pairs = array_column( $list, 'value', 'id' );       // create ['three' => 'value3']
$value = reset( $pairs ) ?: null;                    // return first value

仅使用

$list = [['id' => 'one', 'value' => 'value1'], ['id' => 'two', 'value' => 'value2'], null];
$value = map( $list )                                // create Map
    ->push( ['id' => 'three', 'value' => 'value3'] ) // add element
    ->remove( 0 )                                    // remove element
    ->filter()                                       // remove empty values
    ->sort()                                         // sort elements
    ->col( 'value', 'id' )                           // create ['three' => 'value3']
    ->first();                                       // return first value

您仍然可以使用

$map[] = ['id' => 'three', 'value' => 'value3'];
$value = $map[0];
count( $map );
foreach( $map as $key => value );

使用回调

此外，Map对象允许您将匿名函数传递给许多方法，例如。

$map->each( function( $val, $key ) {
	echo $key . ': ' . $val;
} );

jQuery样式

如果您的Map元素是对象，您可以调用每个对象的方法并获取类似于jQuery的新Map的结果

// MyClass implements setStatus() (returning $this) and getCode() (initialized by constructor)

$map = Map::from( ['a' => new MyClass( 'x' ), 'b' => new MyClass( 'y' )] );
$map->setStatus( 1 )->getCode()->toArray();

这将调用两个对象的setStatus( 1 )。如果setStatus()的实现返回$this，则新Map也将包含

['a' => MyClass(), 'b' => MyClass()]

在这些新Map元素上，将调用getCode()，它对第一个对象返回x，对第二个对象返回y。从getCode()的结果创建的Map将返回

['a' => 'x', 'b' => 'y']

方法

function map function is_map __call __callStatic __construct after all arsort asort at avg before bool call cast chunk clear clone col collapse combine compare concat contains copy count countBy dd delimiter diff diffAssoc diffKeys dump duplicates each empty equals every except explode filter find first firstKey flat flip float from fromJson get getIterator grep groupBy has if ifAny ifEmpty implements in includes index insertAfter insertAt insertBefore inString int intersect intersectAssoc intersectKeys is isEmpty isNumeric isObject isScalar isString join jsonSerialize keys krsort ksort last lastKey ltrim map max merge method min none nth offsetExists offsetGet offsetSet offsetUnset only order pad partition percentage pipe pluck pop pos prefix prepend pull push put random reduce reject rekey remove replace reverse rsort rtrim search sep set shift shuffle skip slice some sort splice split strAfter strContains strContainsAll strEnds strEndsAll string strLower strReplace strStarts strStartsAll strUpper suffix sum take tap times toArray toJson toUrl transpose traverse tree trim uasort uksort union unique unshift usort values walk where with zip

创建

function map() : 从传递的元素创建一个新的Map
__construct() : 创建一个新的Map
clone() : 克隆Map及其所有对象
copy() : 创建一个新的副本
explode() : 将字符串分割成元素Map
from() : 从传递的元素创建一个新的Map
fromJson() : 从JSON字符串创建一个新的Map
times() : 通过调用闭包多次创建一个新的Map
tree() : 从列表项创建树结构

访问

__call() : 调用自定义方法
__callStatic() : 静态调用自定义方法
all() : 返回普通数组
at() : 返回给定位置的价值
bool() : 通过键返回元素并将其转换为布尔值
call() : 在所有项上调用给定方法
find() : 返回第一个/最后一个匹配元素
first() : 返回第一个元素
firstKey() : 返回第一个键
get() : 通过键返回一个元素
index() : 返回给定键的数值索引
int() : 通过键返回一个元素并将其转换为整数
float() : 通过键返回一个元素并将其转换为浮点数
keys() : 返回所有键
last() : 返回最后一个元素
lastKey() : 返回最后一个键
pop() : 返回并移除最后一个元素
pos() : 返回值的数值索引
pull() : 通过键返回并移除一个元素
random() : 返回保留键的随机元素
search() : 查找元素的键
shift() : 返回并移除第一个元素
string() : 通过键返回一个元素并将其转换为字符串
toArray() : 返回普通数组
unique() : 返回保留键的所有唯一元素
values() : 返回所有元素，带有新键

添加

concat() : 添加所有元素，带有新键
insertAfter() : 在给定元素之后插入值
insertAt() : 在映射中给定位置插入元素
insertBefore() : 在给定元素之前插入值
merge() : 合并元素，覆盖现有元素
pad() : 用给定值填充到指定长度
prepend() : 在开头添加元素
push() : 将元素添加到末尾
put() : 在映射中设置给定的键和值
set() : 覆盖或添加一个元素
union() : 添加元素，不覆盖现有元素
unshift() : 在开头添加元素
with() : 返回一个副本并设置一个元素

聚合

avg() : 返回所有值的平均值
count() : 返回元素总数
countBy() : 统计映射中相同值的出现频率
max() : 返回所有元素的最大值
min() : 返回所有元素的最小值
percentage() : 返回通过测试的所有元素的百分比
sum() : 返回地图中所有值的总和

调试

dd() : 打印地图内容并终止脚本
dump() : 打印地图内容
tap() : 将地图的副本传递给指定的回调函数

排序

arsort() : 反向排序元素，保留键
asort() : 排序元素，保留键
krsort() : 按键反向排序元素
ksort() : 按键排序元素
order() : 按传入的键排序元素
reverse() : 反转数组顺序，保留键
rsort() : 使用新键反向排序元素
shuffle() : 随机化元素顺序
sort() : 排序元素，分配新键
uasort() : 使用回调保留键排序元素
uksort() : 使用回调按键排序元素
usort() : 使用回调排序元素，分配新键

缩短

after() : 返回给定元素之后的元素
before() : 返回给定元素之前的元素
clear() : 移除所有元素
diff() : 返回给定列表中缺失的元素
diffAssoc() : 返回给定列表中缺失的元素并检查键
diffKeys() : 返回给定列表中按键缺失的元素
except() : 返回一个新的地图，其中不包含传递的元素键
filter() : 对所有元素应用过滤器
grep() : 对所有元素应用正则表达式
intersect() : 返回共享的元素
intersectAssoc() : 返回共享的元素并检查键
intersectKeys() : 返回按键共享的元素
nth() : 返回从地图中返回的每隔 nth 个元素
only() : 返回由键指定的元素
pop() : 返回并移除最后一个元素
pull() : 通过键返回并移除一个元素
reject() : 移除所有匹配的元素
remove() : 通过键移除一个元素
shift() : 返回并移除第一个元素
skip() : 跳过指定数量的项并返回剩余的项
slice() : 返回映射的一个切片
take() : 返回具有给定数量项的新映射
where() : 通过给定条件过滤元素列表

测试

function is_map() : 测试变量是否为映射对象
compare() : 将值与映射中的所有元素进行比较
contains() : 测试项是否存在于映射中
each() : 对每个元素应用回调函数
empty() : 测试映射是否为空
equals() : 测试映射内容是否相等
every() : 验证所有元素是否通过给定回调函数的测试
has() : 测试键是否存在
if() : 根据条件执行回调函数
ifAny() : 如果映射包含元素，则执行回调函数
ifEmpty() : 如果映射为空，则执行回调函数
in() : 测试元素是否包含在内
includes() : 测试元素是否包含在内
inString() : 测试项是否是映射中字符串的一部分
is() : 测试映射是否由相同的键和值组成
isEmpty() : 测试映射是否为空
isNumeric() : 测试所有条目是否都是数值
isObject() : 测试所有条目是否都是对象
isScalar() : 测试所有条目是否都是标量值。
isString() : 测试所有条目是否都是字符串值。
implements() : 测试所有条目是否都是实现接口的对象
none() : 测试元素是否都不是映射的一部分
some() : 测试至少有一个元素被包含
strContains() : 测试至少有一个传入的字符串是至少一个条目的部分
strContainsAll() : 测试所有条目都包含至少一个传入的字符串
strEnds() : 测试至少一个条目以至少一个传入的字符串结尾
strEndsAll() : 测试所有条目都至少以一个传入的字符串结尾
strStarts() : 检查至少有一个条目以传递的字符串之一开始
strStartsAll() : 检查所有条目是否以传递的字符串之一开始

转换

cast() : 将所有条目转换为传递的类型
chunk() : 将映射分割成块
col() : 创建键/值映射
collapse() : 通过覆盖元素合并多维元素
combine() : 将映射元素作为键与给定的值结合
flat() : 不覆盖元素地扁平化多维元素
flip() : 交换键与其值
groupBy() : 对关联数组元素或对象进行分组
join() : 使用分隔符返回连接的元素作为字符串
ltrim() : 从所有字符串的左侧删除传递的字符
map() : 对每个元素应用回调并返回结果
partition() : 将列表拆分为给定的组数
pipe() : 对整个映射应用回调
pluck() : 创建键/值映射
prefix() : 为每个映射条目添加前缀
reduce() : 从映射内容计算单个值
rekey() : 根据传递的函数更改键
replace() : 递归替换元素
rtrim() : 从所有字符串的右侧删除传递的字符
splice() : 用新元素替换切片
strAfter() : 返回传递值之后的字符串
strLower() : 将所有字母字符转换为小写
strReplace() : 将搜索字符串的所有出现替换为替换字符串
strUpper() : 将所有字母字符转换为大写
suffix() : 为每个映射条目添加后缀
toJson() : 以JSON格式返回元素
toUrl() : 创建HTTP查询字符串
transpose() : 交换二维映射的行和列
traverse() : 遍历嵌套项的树，将每个项传递给回调
trim() : 从所有字符串的左右两侧移除指定的字符
walk() : 将给定的回调函数应用于所有元素
zip() : 将所有数组在对应索引处的值合并

其他

delimiter() : 设置或返回多维度数组路径的分隔符
getIterator() : 返回元素的迭代器
jsonSerialize() : 指定应该序列化为JSON的数据
method() : 注册自定义方法
offsetExists() : 检查键是否存在
offsetGet() : 通过键返回一个元素
offsetSet() : 覆盖一个元素
offsetUnset() : 通过键移除一个元素
sep() : 设置当前映射中多维度数组路径的分隔符

方法文档

is_map() 函数

检查变量是否是映射对象

function is_map( $var ) : bool

@param mixed $var 要测试的变量

示例

is_map( new Map() );
// true

is_map( [] );
// false

map() 函数

返回一个新映射，包含传递的元素。

function map( $elements = [] ) : \Aimeos\Map

@param mixed $elements 元素列表或单个值
@return \Aimeos\Map 映射实例

示例

// array
map( [] );

// null
map( null );

// scalar
map( 'a' );

// object
map( new \stdClass() );

// map object
map( new Map() );

// iterable object
map( new ArrayObject() );

// closure evaluated lazily
map( function() {
    return [];
} );

__construct()

创建一个新的映射对象。

public function __construct( $elements = [] )

@param mixed $elements 单个元素、元素列表、映射对象、可迭代对象或迭代器，或其他任何内容

示例

// array
new Map( [] );

// null
new Map( null );

// scalar
new Map( 'a' );

// object
new Map( new \stdClass() );

// map object
new Map( new Map() );

// iterable object
new Map( new ArrayObject() );

// closure evaluated lazily
new Map( function() {
    return [];
} );

__call()

处理类中对自定义方法的动态调用。

public function __call( string $name, array $params )

@param string $name 方法名称
@param array<mixed> $params 参数列表
@return mixed 调用函数的结果或包含元素方法结果的新的映射

调用通过 Map::method() 添加的自定义方法。调用方法可以通过使用 $this->items 访问内部数组。

示例

Map::method( 'case', function( $case = CASE_LOWER ) {
    return new self( array_change_key_case( $this->items, $case ) );
} );

Map::from( ['a' => 'bar'] )->case( CASE_UPPER );
// ['A' => 'bar']

这也允许在元素是对象的情况下调用对象方法

$item = new MyClass(); // with method setStatus() (returning $this) and getCode() implemented
Map::from( [$item, $item] )->setStatus( 1 )->getCode()->toArray();

这将调用映射中每个元素的 setStatus() 方法，并使用它们的返回值创建一个新的映射。在新映射上，对每个元素调用 getCode() 方法，并将其返回值也存储在新映射中。然后返回最后一个映射，并保留原始映射的映射键。

如果元素不是对象，则跳过，如果所有元素都适用，则返回一个空映射。如果映射包含混合类型的对象，并且其中一个没有实现调用方法，则会抛出错误。

__callStatic()

处理类中对自定义方法的静态调用。

public static function __callStatic( string $name, array $params )

@param string $name 方法名称
@param array<mixed> $params 参数列表
@return mixed 调用函数的结果或包含元素方法结果的新的映射
@throws \BadMethodCallException 如果没有为该名称注册方法

静态调用通过 Map::method() 添加的自定义方法。调用方法没有访问内部数组，因为没有可用的对象。

示例

Map::method( 'foo', function( $arg1, $arg2 ) {} );
Map::foo( $arg1, $arg2 );

after()

返回给定元素之后的元素。

public function after( $value ) : self

@param \Closure|int|string $value 值或带有 (item, key) 参数的函数
@return self<int|string,mixed> 包含给定元素之后元素的新的映射

使用此方法保留键。

示例

Map::from( [0 => 'b', 1 => 'a'] )->after( 'b' );
// [1 => 'a']

Map::from( ['a' => 1, 'b' => 0] )->after( 1 );
// ['b' => 0]

Map::from( [0 => 'b', 1 => 'a'] )->after( 'c' );
// []

Map::from( ['a', 'c', 'b'] )->after( function( $item, $key ) {
    return $item >= 'c';
} );
// [2 => 'b']

all()

以纯数组的形式返回元素。

public function all() : array

@return array 纯数组

示例

Map::from( ['a'] )->all();
// ['a']

arsort()

按降序对所有元素进行排序并保持键关联。

public function arsort( int $options = SORT_REGULAR ) : self

@param int $options 为 arsort() 服务的排序选项
@return self<int|string,mixed> 更新的映射，用于流畅接口

使用此方法保留键，不创建新映射。

$options 参数修改了值的比较方式。可能的参数值包括

SORT_REGULAR : 正常比较元素（不更改类型）
SORT_NUMERIC : 数值比较元素
SORT_STRING : 将元素作为字符串比较
SORT_LOCALE_STRING : 根据当前区域设置或通过 setlocale() 修改的区域设置，将元素作为字符串比较
SORT_NATURAL : 使用“自然排序”比较元素，如 natsort()
SORT_FLAG_CASE : 使用 SORT_STRING|SORT_FLAG_CASE 和 SORT_NATURAL|SORT_FLAG_CASE 对字符串进行不区分大小写的排序

示例

Map::from( ['b' => 0, 'a' => 1] )->arsort();
// ['a' => 1, 'b' => 0]

Map::from( ['a', 'b'] )->arsort();
// ['b', 'a']

Map::from( [0 => 'C', 1 => 'b'] )->arsort();
// [1 => 'b', 0 => 'C']

Map::from( [0 => 'C', 1 => 'b'] )->arsort( SORT_STRING|SORT_FLAG_CASE );
// [0 => 'C', 1 => 'b'] because 'C' -> 'c' and 'c' > 'b'

asort()

对所有元素进行排序并保留键关联。

public function asort( int $options = SORT_REGULAR ) : self

@param int $options 为 asort() 服务的排序选项
@return self<int|string,mixed> 更新的映射，用于流畅接口

使用此方法保留键，不创建新映射。

参数修改了值的比较方式。可能的参数值包括

SORT_REGULAR : 正常比较元素（不更改类型）
SORT_NUMERIC : 数值比较元素
SORT_STRING : 将元素作为字符串比较
SORT_LOCALE_STRING : 根据当前区域设置或通过 setlocale() 修改的区域设置，将元素作为字符串比较
SORT_NATURAL : 使用“自然排序”比较元素，如 natsort()
SORT_FLAG_CASE : 使用 SORT_STRING|SORT_FLAG_CASE 和 SORT_NATURAL|SORT_FLAG_CASE 对字符串进行不区分大小写的排序

示例

Map::from( ['a' => 1, 'b' => 0] )->asort();
// ['b' => 0, 'a' => 1]

Map::from( [0 => 'b', 1 => 'a'] )->asort();
// [1 => 'a', 0 => 'b']

Map::from( [0 => 'C', 1 => 'b'] )->asort();
// [0 => 'C', 1 => 'b'] because 'C' < 'b'

Map::from( [0 => 'C', 1 => 'b'] )->arsort( SORT_STRING|SORT_FLAG_CASE );
// [1 => 'b', 0 => 'C'] because 'C' -> 'c' and 'c' > 'b'

at()

返回指定位置的值。

public function at( int $pos )

@param int $pos 值在映射中的位置
@return mixed�null 指定位置的值，如果没有值则返回 NULL

位置从零开始，位置 "0" 返回映射的第一个元素，"1" 返回第二个，以此类推。如果位置为负，则从映射的末尾开始。

示例

Map::from( [1, 3, 5] )->at( 0 );
// 1

Map::from( [1, 3, 5] )->at( 1 );
// 3

Map::from( [1, 3, 5] )->at( -1 );
// 5

Map::from( [1, 3, 5] )->at( 3 );
// NULL

avg()

返回映射中所有整数和浮点值的平均值。

public function avg( $col = null ) : float

@param Closure|string|null $col 闭包、键或嵌套数组或对象的值的路径，用于计算平均值
@return float 所有元素的平均值，如果映射中没有元素则为 0

NULL 值被视为 0，非数字值将生成错误。

这也适用于多维数组，通过传递分隔符（默认为 "/"）分隔的数组键，例如 "key1/key2/key3" 从 ['key1' => ['key2' => ['key3' => 'val']]] 获取 "val"。同样适用于对象的公共属性或实现 __isset() 和 __get() 方法的对象。

示例

Map::from( [1, 3, 5] )->avg();
// 3

Map::from( [1, null, 5] )->avg();
// 3

Map::from( [1, 'sum', 5] )->avg();
// 2

Map::from( [['p' => 30], ['p' => 50], ['p' => 10]] )->avg( 'p' );
// 30

Map::from( [['i' => ['p' => 30]], ['i' => ['p' => 50]]] )->avg( 'i/p' );
// 40

Map::from( [30, 50, 10] )->avg( fn( $val, $key ) => $val < 50 );
// 20

before()

返回给定元素之前的元素。

public function before( $value ) : self

@param \Closure|int|string $value 值或带有 (item, key) 参数的函数
@return self<int|string,mixed> 包含给定元素之前元素的新映射

使用此方法保留键。

示例

Map::from( ['a' => 1, 'b' => 0] )->before( 0 );
// ['a' => 1]

Map::from( [0 => 'b', 1 => 'a'] )->before( 'a' );
// [0 => 'b']

Map::from( [0 => 'b', 1 => 'a'] )->before( 'c' );
// []

Map::from( ['a', 'c', 'b'] )->before( function( $item, $key ) {
    return $key >= 1;
} );
// [0 => 'a']

bool()

通过键返回一个元素，并在可能的情况下将其转换为布尔值。

public function bool( $key, $default = false ) : bool

@param int|string $key 请求项的键或路径
@param mixed $default 如果键未找到的默认值（将转换为 bool）
@return bool 来自映射的值或默认值

这也适用于通过传递分隔符（默认为 "/"）分隔的数组键从多维数组中映射值，例如 key1/key2/key3 从 ['key1' => ['key2' => ['key3' => 'val']]] 获取 val。同样适用于对象的公共属性或实现 __isset() 和 __get() 方法的对象。

示例

Map::from( ['a' => true] )->bool( 'a' );
// true

Map::from( ['a' => '1'] )->bool( 'a' );
// true (casted to boolean)

Map::from( ['a' => 1.1] )->bool( 'a' );
// true (casted to boolean)

Map::from( ['a' => '10'] )->bool( 'a' );
// true (casted to boolean)

Map::from( ['a' => 'abc'] )->bool( 'a' );
// true (casted to boolean)

Map::from( ['a' => ['b' => ['c' => true]]] )->bool( 'a/b/c' );
// true

Map::from( [] )->bool( 'c', function() { return rand( 1, 2 ); } );
// true (value returned by closure is casted to boolean)

Map::from( [] )->bool( 'a', true );
// true (default value used)

Map::from( [] )->bool( 'a' );
// false

Map::from( ['b' => ''] )->bool( 'b' );
// false (casted to boolean)

Map::from( ['b' => null] )->bool( 'b' );
// false (null is not scalar)

Map::from( ['b' => [true]] )->bool( 'b' );
// false (arrays are not scalar)

Map::from( ['b' => '#resource'] )->bool( 'b' );
// false (resources are not scalar)

Map::from( ['b' => new \stdClass] )->bool( 'b' );
// false (objects are not scalar)

Map::from( [] )->bool( 'c', new \Exception( 'error' ) );
// throws exception

call()

在所有项上调用给定方法并返回结果。

public function call( string $name, array $params = [] ) : self

@param string $name 方法名称
@param array<mixed> $params 参数列表
@return self<int|string,mixed> 包含所有元素结果的新映射

此方法可以调用映射条目上的方法，这些方法也由映射对象本身实现，因此当使用魔法 __call() 方法时不可访问。如果某些条目不是对象，则将跳过它们。

原始映射中的键在返回的新映射中保留。

示例

$item = new MyClass( ['myprop' => 'val'] ); // implements methods get() and toArray()

Map::from( [$item, $item] )->call( 'get', ['myprop'] );
// ['val', 'val']

Map::from( [$item, $item] )->call( 'toArray' );
// [['myprop' => 'val'], ['myprop' => 'val']]

cast()

将所有条目转换为传递的类型。

public function cast( string $type = 'string' ) : self

@param string $type 要转换值的类型 ("string", "bool", "int", "float", "array", "object")
@return self<int|string,mixed> 包含转换元素的新映射

将数组或对象转换为标量值将不会返回任何有用的结果！

示例

Map::from( [true, 1, 1.0, 'yes'] )->cast();
// ['1', '1', '1.0', 'yes']

Map::from( [true, 1, 1.0, 'yes'] )->cast( 'bool' );
// [true, true, true, true]

Map::from( [true, 1, 1.0, 'yes'] )->cast( 'int' );
// [1, 1, 1, 0]

Map::from( [true, 1, 1.0, 'yes'] )->cast( 'float' );
// [1.0, 1.0, 1.0, 0.0]

Map::from( [new stdClass, new stdClass] )->cast( 'array' );
// [[], []]

Map::from( [[], []] )->cast( 'object' );
// [new stdClass, new stdClass]

chunk()

将地图分割成具有指定元素数量的数组。

public function chunk( int $size, bool $preserve = false ) : self

@param int $size 子数组的最大大小
@param bool $preserve 保留新地图中的键
@return self<int|string,mixed> 新地图，元素已分割到子数组中
@throws \InvalidArgumentException 如果大小小于1

最后一个块可能包含的元素数量少于指定数量。

返回地图的子数组是普通的PHP数组。如果您需要Map对象，则在遍历地图时使用Map::from()将其包装。

示例

Map::from( [0, 1, 2, 3, 4] )->chunk( 3 );
// [[0, 1, 2], [3, 4]]

Map::from( ['a' => 0, 'b' => 1, 'c' => 2] )->chunk( 2 );
// [['a' => 0, 'b' => 1], ['c' => 2]]

clear()

从当前地图中删除所有元素。

public function clear() : self

@return self<int|string,mixed> 更新的映射，用于流畅接口

示例

Map::from( [0, 1] )->clear();
// internal : []

clone()

克隆地图及其内部的所有对象。

public function clone() : self

@return self<int|string,mixed> 新地图，包含已克隆的对象

Map内部的对象与之前的不相同，而是新的克隆对象。这与copy()不同，后者不会克隆内部的对象。

使用此方法保留键。

示例

Map::from( [new \stdClass, new \stdClass] )->clone();
// [new \stdClass, new \stdClass]

col()

从数组数组的单个列/属性返回值，或从列表元素返回的新地图中的元素。

public function col( string $valuecol = null, string $indexcol = null ) : self

@param string|null $valuecol 值属性的名称或路径
@param string|null $indexcol 索引属性的名称或路径
@return self<int|string,mixed> 新地图，包含映射的条目

如果省略了$indexcol，则其值为NULL或未设置，结果将从0-n索引。具有相同$indexcol值的项将覆盖之前的项，并且只有最后一个将包含在结果地图中。

示例

Map::from( [['id' => 'i1', 'val' => 'v1'], ['id' => 'i2', 'val' => 'v2']] )->col( 'val' );
// ['v1', 'v2']

Map::from( [['id' => 'i1', 'val' => 'v1'], ['id' => 'i2', 'val' => 'v2']] )->col( 'val', 'id' );
// ['i1' => 'v1', 'i2' => 'v2']

Map::from( [['id' => 'i1', 'val' => 'v1'], ['id' => 'i2', 'val' => 'v2']] )->col( null, 'id' );
// ['i1' => ['id' => 'i1', 'val' => 'v1'], 'i2' => ['id' => 'i2', 'val' => 'v2']]

Map::from( [['id' => 'ix', 'val' => 'v1'], ['id' => 'ix', 'val' => 'v2']] )->col( null, 'id' );
// ['ix' => ['id' => 'ix', 'val' => 'v2']]

Map::from( [['foo' => ['bar' => 'one', 'baz' => 'two']]] )->col( 'foo/baz', 'foo/bar' );
// ['one' => 'two']

Map::from( [['foo' => ['bar' => 'one']]] )->col( 'foo/baz', 'foo/bar' );
// ['one' => null]

Map::from( [['foo' => ['baz' => 'two']]] )->col( 'foo/baz', 'foo/bar' );
// ['two']

collapse()

递归地将所有子数组元素合并到新地图中。

public function collapse( int $depth = null ) : self

@param int|null $depth 要合并的层数，或NULL为所有
@return self<int|string,mixed> 新地图，包含递归添加到其中的所有子数组元素，最多指定深度

保留键，并且已存在的元素将被覆盖。这对于数字键也适用！此方法与flat()类似，但会替换已存在的元素。

对于深度小于1的值，将返回相同的地图元素。合并还可以在元素实现"Traversable"接口时（Map对象就是这样）工作。

示例

Map::from( [0 => ['a' => 0, 'b' => 1], 1 => ['c' => 2, 'd' => 3]] )->collapse();
// ['a' => 0, 'b' => 1, 'c' => 2, 'd' => 3]

Map::from( [0 => ['a' => 0, 'b' => 1], 1 => ['a' => 2]] )->collapse();
// ['a' => 2, 'b' => 1]

Map::from( [0 => [0 => 0, 1 => 1], 1 => [0 => ['a' => 2, 0 => 3], 1 => 4]] )->collapse();
// [0 => 3, 1 => 4, 'a' => 2]

Map::from( [0 => [0 => 0, 'a' => 1], 1 => [0 => ['b' => 2, 0 => 3], 1 => 4]] )->collapse( 1 );
// [0 => ['b' => 2, 0 => 3], 1 => 4, 'a' => 1]

Map::from( [0 => [0 => 0, 'a' => 1], 1 => Map::from( [0 => ['b' => 2, 0 => 3], 1 => 4] )] )->collapse();
// [0 => 3, 'a' => 1, 'b' => 2, 1 => 4]

combine()

将地图的值作为键与传递的元素作为值组合。

public function combine( iterable $values ) : self

@param iterable<int|string,mixed> $values 新地图的值
@return self<int|string,mixed> 新地图

示例

Map::from( ['name', 'age'] )->combine( ['Tom', 29] );
// ['name' => 'Tom', 'age' => 29]

compare()

将值与所有地图元素进行比较。

public function compare( string $value, bool $case = true ) : bool

@param string $value 与地图元素比较的值
@param bool $case 如果比较区分大小写则为TRUE，否则为FALSE
@return bool 如果至少有一个元素匹配，则为TRUE，如果值不在地图中，则为FALSE

所有标量值（bool、float、int和string）在比较之前都转换为字符串值。地图中的非标量值将被忽略。

示例

Map::from( ['foo', 'bar'] )->compare( 'foo' );
// true

Map::from( ['foo', 'bar'] )->compare( 'Foo', false );
// true (case insensitive)

Map::from( [123, 12.3] )->compare( '12.3' );
// true

Map::from( [false, true] )->compare( '1' );
// true

Map::from( ['foo', 'bar'] )->compare( 'Foo' );
// false (case sensitive)

Map::from( ['foo', 'bar'] )->compare( 'baz' );
// false

Map::from( [new \stdClass(), 'bar'] )->compare( 'foo' );
// false

concat()

将所有给定元素推送到地图中，而无需创建新地图。

public function concat( iterable $elements ) : self

@param iterable<int|string,mixed> $elements 元素列表
@return self<int|string,mixed> 更新的映射，用于流畅接口

不会保留传递元素的键！

示例

Map::from( ['foo'] )->concat( ['bar'] );
// ['foo', 'bar']

Map::from( ['foo'] )->concat( new Map( ['bar' => 'baz'] ) );
// ['foo', 'baz']

contains()

确定地图中是否存在项目。

public function contains( $key, string $operator = null, $value = null ) : bool

此方法结合了where()方法的强大功能与some()来检查地图是否包含至少一个传递的值或条件。

@param \Closure|iterable|mixed $values 带有(item, key)参数的匿名函数，元素或要测试的元素列表
@param string|null $op 用于比较的运算符
@param mixed $value 用于比较的值
返回值 bool：如果映射中至少有一个元素可用，则为 TRUE；如果映射中不包含这些元素，则为 FALSE

检查 where() 方法中的可用运算符。

示例

Map::from( ['a', 'b'] )->contains( 'a' );
// true

Map::from( ['a', 'b'] )->contains( ['a', 'c'] );
// true

Map::from( ['a', 'b'] )->contains( function( $item, $key ) {
    return $item === 'a'
} );
// true

Map::from( [['type' => 'name']] )->contains( 'type', 'name' );
// true

Map::from( [['type' => 'name']] )->contains( 'type', '!=', 'name' );
// false

copy()

创建一个新的映射，包含相同的元素。

public function copy() : self

@return self<int|string,mixed> 新地图

两个映射共享相同的数组，直到其中一个映射对象修改了数组。然后，数组被复制，复制被修改（写时复制）。

示例

$m = Map::from( ['foo', 'bar'] );

$m2 = $m->copy();
// internal: ['foo', 'bar'] both two maps

count()

计算映射中元素的数量。

public function count() : int

返回值 int：元素数量

示例

Map::from( ['foo', 'bar'] )->count();
// 2

countBy()

计算映射中相同值出现的频率。

public function countBy( callable $callback = null ) : self

参数 callable|null $callback：函数，带有 (value, key) 参数，返回用于计数的值
返回值 self<int|string,mixed>：新的映射，以值为键，以计数为值

示例

Map::from( [1, 'foo', 2, 'foo', 1] )->countBy();
// [1 => 2, 'foo' => 2, 2 => 1]

Map::from( [1.11, 3.33, 3.33, 9.99] )->countBy();
// ['1.11' => 1, '3.33' => 2, '9.99' => 1]

Map::from( ['[email protected]', '[email protected]', '[email protected]'] )->countBy( function( $email ) {
    return substr( strrchr( $email, '@' ), 1 );
} );
// ['gmail.com' => 2, 'yahoo.com' => 1]

dd()

转储映射内容并终止脚本。

public function dd( callable $callback = null ) : void

参数 callable|null $callback：接收映射元素作为参数的函数（可选）

dd() 方法非常有用，可以查看方法调用链中两个映射方法之间传递的映射元素。之后停止脚本执行，以避免进一步输出。

示例

Map::from( ['a' => 'foo', 'b' => 'bar'] )->sort()->dd()->first();
/*
Array
(
    [0] => bar
    [1] => foo
)
*/

first() 方法根本不会执行。

delimiter()

设置或返回多维数组或对象中值路径的分隔符。

public static function delimiter( ?string $char = null ) : string

参数 string $char：分隔符字符，例如，对于 "key.to.value"，使用 "." 而不是 "key/to/value"
返回值 string：至今为止使用的分隔符

静态方法仅更改之后创建的新映射的分隔符。已存在的映射将继续使用之前的分隔符。要更改现有映射的分隔符，请使用 sep() 方法。

示例

Map::delimiter( '.' );
// '/'

Map::from( ['foo' => ['bar' => 'baz']] )->get( 'foo.bar' );
// 'baz'

diff()

返回映射中其值不在传入元素中的键/值的新映射。

public function diff( iterable $elements, callable $callback = null ) : self

@param iterable<int|string,mixed> $elements 元素列表
参数 callable|null $callback：带有 (valueA, valueB) 参数的函数，并返回 -1 (<), 0 (=) 和 1 (>)
@return self<int|string,mixed> 新地图

示例

Map::from( ['a' => 'foo', 'b' => 'bar'] )->diff( ['bar'] );
// ['a' => 'foo']

如果传递了回调函数，则使用给定的函数来比较值。该函数必须接受两个参数（值 A 和 B）并必须返回 -1 如果值 A 小于值 B，0 如果两者相等，1 如果值 A 大于值 B。可以传递方法名和匿名函数

Map::from( [0 => 'a'] )->diff( [0 => 'A'], 'strcasecmp' );
// []

Map::from( ['b' => 'a'] )->diff( ['B' => 'A'], 'strcasecmp' );
// []

Map::from( ['b' => 'a'] )->diff( ['c' => 'A'], function( $valA, $valB ) {
    return strtolower( $valA ) <=> strtolower( $valB );
} );
// []

所有示例都将返回空映射，因为当进行不区分大小写的比较时，两者包含相同的值。

使用此方法保留键。

diffAssoc()

返回映射中其键和值都不在传入元素中的键/值的新映射。

public function diffAssoc( iterable $elements, callable $callback = null ) : self

@param iterable<int|string,mixed> $elements 元素列表
参数 callable|null $callback：带有 (valueA, valueB) 参数的函数，并返回 -1 (<), 0 (=) 和 1 (>)
@return self<int|string,mixed> 新地图

示例

Map::from( ['a' => 'foo', 'b' => 'bar'] )->diffAssoc( new Map( ['foo', 'b' => 'bar'] ) );
// ['a' => 'foo']

如果传递了回调函数，则使用给定的函数来比较值。该函数必须接受两个参数（valA, valB）并必须返回 -1 如果值 A 小于值 B，0 如果两者相等，1 如果值 A 大于值 B。可以传递方法名和匿名函数

Map::from( [0 => 'a'] )->diffAssoc( [0 => 'A'], 'strcasecmp' );
// []

Map::from( ['b' => 'a'] )->diffAssoc( ['B' => 'A'], 'strcasecmp' );
// []

Map::from( ['b' => 'a'] )->diffAssoc( ['c' => 'A'], function( $valA, $valB ) {
    return strtolower( $valA ) <=> strtolower( $valB );
} );
// ['b' => 'a']

第一个和第二个示例将返回空映射，因为当进行不区分大小写的比较时，两者包含相同的值。在第三个示例中，键不匹配（"b" 与 "c"）。

使用此方法保留键。

diffKeys()

返回映射中其键不在传入元素中的键/值对的新映射。

public function diffKeys( iterable $elements, callable $callback = null ) : self

@param iterable<int|string,mixed> $elements 元素列表
参数 callable|null $callback：带有 (keyA, keyB) 参数的函数，并返回 -1 (<), 0 (=) 和 1 (>)
@return self<int|string,mixed> 新地图

示例

Map::from( ['a' => 'foo', 'b' => 'bar'] )->diffKeys( new Map( ['foo', 'b' => 'baz'] ) );
// ['a' => 'foo']

如果传递了一个回调函数，则将使用给定的函数来比较键。该函数必须接受两个参数（键A和键B），并在键A小于键B时返回-1，在两者相等时返回0，在键A大于键B时返回1。可以传递方法名称和匿名函数。

Map::from( [0 => 'a'] )->diffKeys( [0 => 'A'], 'strcasecmp' );
// []

Map::from( ['b' => 'a'] )->diffKeys( ['B' => 'X'], 'strcasecmp' );
// []

Map::from( ['b' => 'a'] )->diffKeys( ['c' => 'a'], function( $keyA, $keyB ) {
    return strtolower( $keyA ) <=> strtolower( $keyB );
} );
// ['b' => 'a']

第一个和第二个示例将返回一个空映射，因为它们都包含相同的键（不区分大小写）。第三个示例将返回 ['b' => 'a']，因为键不匹配（"b" 对 "c"）。

使用此方法保留键。

dump()

使用给定的函数（默认为 print_r）输出映射内容。

public function dump( callable $callback = null ) : self

参数 callable|null $callback：接收映射元素作为参数的函数（可选）
@return self<int|string,mixed> 同一映射，用于流畅接口

dump() 方法非常有用，可以查看在方法调用链中两个映射方法之间传递的映射元素。

示例

Map::from( ['a' => 'foo', 'b' => 'bar'] )->dump()->asort()->dump( 'var_dump' );
/*
Array
(
    [a] => foo
    [b] => bar
)

array(1) {
  ["b"]=>
  string(3) "bar"
  ["a"]=>
  string(3) "foo"
}
*/

duplicates()

从映射中返回重复的值。

public function duplicates( string $col = null ) : self

@param string|null $col 检查嵌套数组或对象的键
@return self<int|string,mixed> 新地图

对于嵌套数组，您必须传递用于检查重复项的嵌套数组的列名。

结果映射中的键保持不变。

示例

Map::from( [1, 2, '1', 3] )->duplicates()
// [2 => '1']

Map::from( [['p' => '1'], ['p' => 1], ['p' => 2]] )->duplicates( 'p' )
// [1 => ['p' => 1]]

Map::from( [['i' => ['p' => '1']], ['i' => ['p' => 1]]] )->duplicates( 'i/p' )
// [1 => ['i' => ['p' => '1']]]

each()

对每个条目执行回调，直到返回 FALSE。

public function each( \Closure $callback ) : self

@param \Closure $callback 带有（值，键）参数的函数并返回 TRUE/FALSE
@return self<int|string,mixed> 同一映射，用于流畅接口

示例

$result = [];
Map::from( [0 => 'a', 1 => 'b'] )->each( function( $value, $key ) use ( &$result ) {
    $result[$key] = strtoupper( $value );
    return false;
} );
// $result = [0 => 'A']

因为第一个条目返回 FALSE，所以 $result 数组将包含 [0 => 'A']，然后跳过所有其他条目。

empty()

确定映射是否为空。

public function empty() : bool

@return bool 如果映射为空，则为 TRUE，否则为 FALSE

该方法与 isEmpty() 方法等价。

示例

Map::from( [] )->empty();
// true

Map::from( ['a'] )->empty();
// false

equals()

测试传递的元素是否等于映射中的元素。

public function equals( iterable $elements ) : bool

@param iterable<int|string,mixed> $elements 要测试的元素列表
@return bool 如果两者相等，则为 TRUE，否则为 FALSE

与 is() 方法不同，该方法默认不关心键。元素仅进行松散比较，键被忽略。

值通过它们的字符串值进行比较

(string) $item1 === (string) $item2

示例

Map::from( ['a'] )->equals( ['a', 'b'] );
// false

Map::from( ['a', 'b'] )->equals( ['b'] );
// false

Map::from( ['a', 'b'] )->equals( ['b', 'a'] );
// true

every()

验证所有元素是否通过给定回调的测试。

public function every( \Closure $callback ) : bool

@param \Closure $callback 带有（值，键）参数的函数并返回 TRUE/FALSE
@return bool 如果所有元素都通过测试，则为 TRUE，如果至少有一个元素失败，则为 FALSE

示例

Map::from( [0 => 'a', 1 => 'b'] )->every( function( $value, $key ) {
    return is_string( $value );
} );
// true

Map::from( [0 => 'a', 1 => 100] )->every( function( $value, $key ) {
    return is_string( $value );
} );
// false

except()

返回一个不包含传递的元素键的新映射。

public function except( $keys ) : self

@param iterable<int|string>|array<int|string>|string|int $keys 要删除的键列表
@return self<int|string,mixed> 新地图

结果映射中的键保持不变。

示例

Map::from( ['a' => 1, 'b' => 2, 'c' => 3] )->except( 'b' );
// ['a' => 1, 'c' => 3]

Map::from( [1 => 'a', 2 => 'b', 3 => 'c'] )->except( [1, 3] );
// [2 => 'b']

explode()

创建一个新映射，使用分隔符拆分字符串。

public static function explode( string $delimiter , string $string , int $limit = PHP_INT_MAX ) : self

@param string $delimiter 分隔符字符，字符串或空字符串
@param string $string 要拆分的字符串
@param int $limit 元素的最大数量，最后一个元素包含字符串的其余部分
@return self<int|string,mixed> 包含拆分部分的新的映射

"0" 的限制与 "1" 相同。如果限制为负数，则丢弃字符串的其余部分，且不属于返回的映射。

此方法创建一个懒加载的映射，字符串在调用操作映射内容的另一个方法后拆分。

示例

Map::explode( ',', 'a,b,c' );
// ['a', 'b', 'c']

Map::explode( '<-->', 'a a<-->b b<-->c c' );
// ['a a', 'b b', 'c c']

Map::explode( '', 'string' );
// ['s', 't', 'r', 'i', 'n', 'g']

Map::explode( '|', 'a|b|c', 2 );
// ['a', 'b|c']

Map::explode( '', 'string', 2 );
// ['s', 't', 'ring']

Map::explode( '|', 'a|b|c|d', -2 );
// ['a', 'b']

Map::explode( '', 'string', -3 );
// ['s', 't', 'r']

filter()

在映射的每个元素上运行过滤器并返回一个新映射。

public function filter( callable $callback = null ) : self

@param callable|null $callback 带有（项，键）参数的函数并返回 TRUE/FALSE
@return self<int|string,mixed> 新地图

如果没有传递回调函数，则所有值为空、null 或 false 的值将删除，如果其布尔转换为 FALSE

(bool) $value === false

结果映射中的键保持不变。

示例

Map::from( [null, 0, 1, '', '0', 'a'] )->filter();
// [1, 'a']

Map::from( [2 => 'a', 6 => 'b', 13 => 'm', 30 => 'z'] )->filter( function( $value, $key ) {
    return $key < 10 && $value < 'n';
} );
// ['a', 'b']

find()

返回第一个匹配的元素，其中回调返回 TRUE。

public function find( \Closure $callback, $default = null, bool $reverse = false )

@param \Closure $callback 带有（值，键）参数的函数并返回 TRUE/FALSE
@param mixed $default 如果映射不包含元素，则为默认值或异常
@param bool $reverse 从后向前测试元素（默认）为 TRUE，从前往后为 FALSE
@return mixed|null 第一个匹配值，传递的默认值或异常

示例

Map::from( ['a', 'c', 'e'] )->find( function( $value, $key ) {
    return $value >= 'b';
} );
// 'c'

Map::from( ['a', 'c', 'e'] )->find( function( $value, $key ) {
    return $value >= 'b';
}, null, true );
// 'e' because $reverse = true

Map::from( [] )->find( function( $value, $key ) {
    return $value >= 'b';
}, 'none' );
// 'none'

Map::from( [] )->find( function( $value, $key ) {
    return $value >= 'b';
}, new \Exception( 'error' ) );
// throws \Exception

first()

从映射中返回第一个元素。

public function first( $default = null )

@param mixed $default 如果映射不包含元素，则为默认值或异常
@return mixed 映射的第一个值、(生成的)默认值或异常

示例

Map::from( ['a', 'b'] )->first();
// 'a'

Map::from( [] )->first( 'x' );
// 'x'

Map::from( [] )->first( new \Exception( 'error' ) );
// throws \Exception

Map::from( [] )->first( function() { return rand(); } );
// random integer

firstKey()

从映射中返回第一个键。

public function firstKey()

@return mixed 映射的第一个键或为空时返回NULL

示例

Map::from( ['a' => 1, 'b' => 2] )->lastKey();
// 'a'

Map::from( [] )->lastKey();
// null

flat()

创建一个新的映射，其中包含递归添加的所有子数组元素。

public function flat( int $depth = null ) : self

@param int|null $depth 要扁平化的多维数组级别的数量
@return self<int|string,mixed> 新地图，包含递归添加到其中的所有子数组元素，最多指定深度

键不会被保留，并且新映射元素将从0到n编号。深度小于1的值将返回相同的映射元素，从0到n索引。如果元素实现了“可遍历”接口（映射对象确实实现了），则扁平化也会工作。

此方法类似于collapse()，但不会替换现有元素。使用此方法不保留键！

示例

Map::from( [[0, 1], [2, 3]] )->flat();
// [0, 1, 2, 3]

Map::from( [[0, 1], [[2, 3], 4]] )->flat();
// [0, 1, 2, 3, 4]

Map::from( [[0, 1], [[2, 3], 4]] )->flat( 1 );
// [0, 1, [2, 3], 4]

Map::from( [[0, 1], Map::from( [[2, 3], 4] )] )->flat();
// [0, 1, 2, 3, 4]

flip()

交换键与其值以及反之亦然。

public function flip() : self

@return self<int|string,mixed> 新映射，其键为值，值为键

示例

Map::from( ['a' => 'X', 'b' => 'Y'] )->flip();
// ['X' => 'a', 'Y' => 'b']

float()

通过键获取一个元素并将其转换为浮点数（如果可能）。

public function float( $key, $default = 0.0 ) : float

@param int|string $key 请求项的键或路径
@param mixed $default 如果找不到键时的默认值（将转换为浮点数）
@return float 映射中的值或默认值

示例

Map::from( ['a' => true] )->float( 'a' );
// 1.0 (casted to float)

Map::from( ['a' => 1] )->float( 'a' );
// 1.0 (casted to float)

Map::from( ['a' => '1.1'] )->float( 'a' );
// 1.1 (casted to float)

Map::from( ['a' => '10'] )->float( 'a' );
// 10.0 (casted to float)

Map::from( ['a' => ['b' => ['c' => 1.1]]] )->float( 'a/b/c' );
// 1.1

Map::from( [] )->float( 'c', function() { return 1.1; } );
// 1.1

Map::from( [] )->float( 'a', 1 );
// 1.0 (default value used)

Map::from( [] )->float( 'a' );
// 0.0

Map::from( ['b' => ''] )->float( 'b' );
// 0.0 (casted to float)

Map::from( ['a' => 'abc'] )->float( 'a' );
// 0.0 (casted to float)

Map::from( ['b' => null] )->float( 'b' );
// 0.0 (null is not scalar)

Map::from( ['b' => [true]] )->float( 'b' );
// 0.0 (arrays are not scalar)

Map::from( ['b' => '#resource'] )->float( 'b' );
// 0.0 (resources are not scalar)

Map::from( ['b' => new \stdClass] )->float( 'b' );
// 0.0 (objects are not scalar)

Map::from( [] )->float( 'c', new \Exception( 'error' ) );
// throws exception

from()

如果值不是一个映射实例，则创建一个新的映射实例。

public static function from( $elements = [] ) : self

@param mixed $elements 元素列表或单个值
@return self<int|string,mixed> 新地图

示例

// array
Map::from( [] );

// null
Map::from( null );

// scalar
Map::from( 'a' );

// object
Map::from( new \stdClass() );

// map object
Map::from( new Map() );

// iterable object
Map::from( new ArrayObject() );

// closure evaluated lazily
Map::from( function() {
    return [];
} );

fromJson()

从JSON字符串创建一个新的映射实例。

public static function fromJson( string $json, int $options = JSON_BIGINT_AS_STRING ) : self

@param int $options JSON_*常量的组合
@return self<int|string,mixed> 从解码的JSON字符串中创建的新映射
@throws \RuntimeException 如果传入的JSON字符串无效

有几种用于解码JSON字符串的选项，这些选项在PHP json_decode()手册中描述。参数可以是单个JSON_*常量或多个常量的位掩码，通过按位或(|)组合，例如

此方法创建了一个懒惰的映射，字符串在调用操作映射内容的另一个方法之后解码。因此，错误异常不会立即抛出，而是在调用下一个方法之后抛出。

JSON_BIGINT_AS_STRING|JSON_INVALID_UTF8_IGNORE

示例

Map::fromJson( '["a", "b"]' );
// ['a', 'b']

Map::fromJson( '{"a": "b"}' );
// ['a' => 'b']

Map::fromJson( '""' );
['']

get()

通过键从映射中获取一个元素。

public function get( $key, $default = null )

@param int|string $key 请求项的键或路径
@param mixed $default 如果没有元素匹配时的默认值
@return mixed 映射中的值或默认值

示例

Map::from( ['a' => 'X', 'b' => 'Y'] )->get( 'a' );
// 'X'

Map::from( ['a' => 'X', 'b' => 'Y'] )->get( 'c', 'Z' );
// 'Z'

Map::from( ['a' => ['b' => ['c' => 'Y']]] )->get( 'a/b/c' );
// 'Y'

Map::from( [] )->get( 'c', new \Exception( 'error' ) );
// throws \Exception

Map::from( [] )->get( 'c', function() { return rand(); } );
// random integer

getIterator()

返回元素的迭代器。

public function getIterator() : \ArrayIterator

@return \Iterator 映射元素

此方法将由例如foreach()用于遍历所有条目。

示例

foreach( Map::from( ['a', 'b'] ) as $value ) {
    // ...
}

grep()

仅返回与正则表达式匹配的项目。

public function grep( string $pattern, int $flags = 0 ) : self

@param string $pattern 正则表达式模式，例如“/ab/”
@param int $flags PREG_GREP_INVERT以返回不匹配模式的项目
@return self<int|string,mixed> 仅包含匹配元素的新映射

首先将所有项目转换为字符串，然后再将它们与正则表达式进行比较。因此，浮点数中的“0”将移除，这可能导致意外的结果。使用此方法保留键。

示例

Map::from( ['ab', 'bc', 'cd'] )->grep( '/b/' );
// ['ab', 'bc']

Map::from( ['ab', 'bc', 'cd'] )->grep( '/a/', PREG_GREP_INVERT );
// ['bc', 'cd']

Map::from( [1.5, 0, 1.0, 'a'] )->grep( '/^(\d+)?\.\d+$/' );
// [1.5]
// float 1.0 is converted to string "1"

groupBy()

根据传递的键或闭包对关联数组元素或对象进行分组。

public function groupBy( $key ) : self

@param \Closure|string|int $key 参数为(item, idx)的闭包函数，返回键或要分组的键本身
@return self<int|string,mixed> 新映射，元素按给定键分组

与col()方法覆盖具有相同键的项不同，groupBy()保留所有条目在子数组中。它还保留了原始映射条目的键。

示例

$list = [
    10 => ['aid' => 123, 'code' => 'x-abc'],
    20 => ['aid' => 123, 'code' => 'x-def'],
    30 => ['aid' => 456, 'code' => 'x-def']
];

Map::from( $list )->groupBy( 'aid' );
/*
[
    123 => [
        10 => ['aid' => 123, 'code' => 'x-abc'],
        20 => ['aid' => 123, 'code' => 'x-def']
    ],
    456 => [
        30 => ['aid' => 456, 'code' => 'x-def']
    ]
]
*/

Map::from( $list )->groupBy( function( $item, $key ) {
    return substr( $item['code'], -3 );
} );
/*
[
    'abc' => [
        10 => ['aid' => 123, 'code' => 'x-abc']
    ],
    'def' => [
        20 => ['aid' => 123, 'code' => 'x-def'],
        30 => ['aid' => 456, 'code' => 'x-def']
    ]
]
*/

如果传递的键在其中一个或多个项目中不存在，则将这些项目存储在子数组中，使用空字符串作为键

$list = [
    10 => ['aid' => 123, 'code' => 'x-abc'],
    20 => ['aid' => 123, 'code' => 'x-def'],
    30 => ['aid' => 456, 'code' => 'x-def']
];

Map::from( $list )->groupBy( 'xid' );
/*
[
    '' => [
        10 => ['aid' => 123, 'code' => 'x-abc'],
        20 => ['aid' => 123, 'code' => 'x-def'],
        30 => ['aid' => 456, 'code' => 'x-def']
    ]
]
*/

has()

确定一个键或多个键是否存在于映射中。

public function has( $key ) : bool

@param array<int|string<|int|string $key 请求项的键或路径
@return bool 如果键存在于映射中，则返回 TRUE，否则返回 FALSE

如果作为数组传递了多个键，则必须所有键都存在于映射中才返回 TRUE。

示例

Map::from( ['a' => 'X', 'b' => 'Y'] )->has( 'a' );
// true

Map::from( ['a' => 'X', 'b' => 'Y'] )->has( ['a', 'b'] );
// false

Map::from( ['a' => ['b' => ['c' => 'Y']]] )->has( 'a/b/c' );
// true

Map::from( ['a' => 'X', 'b' => 'Y'] )->has( 'c' );
// false

Map::from( ['a' => 'X', 'b' => 'Y'] )->has( ['a', 'c'] );
// false

Map::from( ['a' => 'X', 'b' => 'Y'] )->has( 'X' );
// false

if()

根据条件执行回调。

public function if( $condition, \Closure $then, \Closure $else = null ) : self

@param \Closure|bool $condition 布尔值或带有 (map) 参数返回布尔值的函数
@param \Closure $then 带有 (map) 参数的函数
@param \Closure|null $else 带有 (map) 参数的函数（可选）
@return self<int|string,mixed> 用于流畅接口的新映射

如果传递了 "then" 和/或 "else" 回调，则将执行这些回调，并将它们返回的值作为 Map 对象传递回。如果没有提供 "then" 或 "else" 闭包，则当条件为真时，方法将返回相同的映射对象，当条件为假时，将返回空映射对象。

示例

Map::from( ['a' => 1, 'b' => 0] )->if(
    'a' == 'b',
    function( Map $_ ) { echo "then"; }
);
// no output

Map::from( ['a' => 1, 'b' => 0] )->if(
    function( Map $map ) { return $map->has( 'a' ); },
    function( Map $_ ) { echo "then"; },
    function( Map $_ ) { echo "else"; }
);
// then

Map::from( ['a' => 1, 'b' => 0] )->if(
    fn( Map $map ) => $map->has( 'c' ),
    function( Map $_ ) { echo "then"; },
    function( Map $_ ) { echo "else"; }
);
// else

Map::from( ['a', 'b'] )->if( true, function( $map ) {
    return $map->push( 'c' );
} );
// ['a', 'b', 'c']

Map::from( ['a', 'b'] )->if( false, null, function( $map ) {
  return $map->pop();
} );
// ['b']

从 PHP 7.4 开始，您还可以传递类似 fn($map) => $map->has('c') 的箭头函数（匿名闭包的简写）作为参数。它们自动具有对先前定义变量的访问权限，但不能修改它们。此外，它们不能有 void 返回类型，并且必须/始终返回某些值。有关 PHP 箭头函数的详细信息

ifAny()

根据映射是否包含元素来执行回调。

public function ifAny( \Closure $then = null, \Closure $else = null ) : self

@param \Closure|null $then 带有 (map, condition) 参数的函数（可选）
@param \Closure|null $else 带有 (map, condition) 参数的函数（可选）
@return self<int|string,mixed> 用于流畅接口的新映射

如果传递了 "then" 和/或 "else" 回调，则将执行这些回调，并将它们返回的值作为 Map 对象传递回。如果没有提供 "then" 或 "else" 闭包，则方法将返回相同的映射对象。

示例

Map::from( ['a'] )->ifAny( function( $map ) {
  $map->push( 'b' );
} );
// ['a', 'b']

Map::from( [] )->ifAny( null, function( $map ) {
  return $map->push( 'b' );
} );
// ['b']

Map::from( ['a'] )->ifAny( function( $map ) {
  return 'c';
} );
// ['c']

ifEmpty()

根据映射是否为空来执行回调。

public function ifEmpty( \Closure $then = null, \Closure $else = null ) : self

@param \Closure|null $then 带有 (map, condition) 参数的函数（可选）
@param \Closure|null $else 带有 (map, condition) 参数的函数（可选）
@return self<int|string,mixed> 用于流畅接口的新映射

示例

Map::from( [] )->ifEmpty( function( $map ) {
    $map->push( 'a' );
} );
// ['a']

Map::from( ['a'] )->ifEmpty( null, function( $map ) {
    return $map->push( 'b' );
} );
// ['a', 'b']

implements()

测试映射中的所有条目是否都是实现给定接口的对象。

public function implements( string $interface, $throw = false ) : bool

@param string $interface 必须实现的接口名称
@param \Throwable|bool $throw 传递 TRUE 或异常名称将引发异常而不是返回 FALSE
@return bool 如果所有条目都实现接口，则返回 TRUE，如果至少有一个不实现，则返回 FALSE
@throws \UnexpectedValueException|\Throwable 如果某个条目没有实现接口

示例

Map::from( [new Map(), new Map()] )->implements( '\Countable' );
// true

Map::from( [new Map(), new \stdClass()] )->implements( '\Countable' );
// false

Map::from( [new Map(), 123] )->implements( '\Countable' );
// false

Map::from( [new Map(), 123] )->implements( '\Countable', true );
// throws \UnexpectedValueException

Map::from( [new Map(), 123] )->implements( '\Countable', '\RuntimeException' );
// throws \RuntimeException

in()

测试传入的元素或元素是否是映射的一部分。

public function in( $element, bool $strict = false ) : bool

@param mixed|array $element 要在映射中搜索的元素或元素数组
@param bool $strict TRUE 用于检查类型，使用 FALSE '1' 和 1 将被视为相同
@return bool 如果所有元素都存在于映射中，则返回 TRUE，否则返回 FALSE

示例

Map::from( ['a', 'b'] )->in( 'a' );
// true

Map::from( ['a', 'b'] )->in( ['a', 'b'] );
// true

Map::from( ['a', 'b'] )->in( 'x' );
// false

Map::from( ['a', 'b'] )->in( ['a', 'x'] );
// false

Map::from( ['1', '2'] )->in( 2, true );
// false

includes()

测试传入的元素或元素是否是映射的一部分。

public function includes( $element, bool $strict = false ) : bool

@param mixed|array $element 要在映射中搜索的元素或元素数组
@param bool $strict TRUE 用于检查类型，使用 FALSE '1' 和 1 将被视为相同
@return bool 如果所有元素都存在于映射中，则返回 TRUE，否则返回 FALSE

此方法是对 in() 的别名。出于性能原因，应首选 in()，因为它比 includes() 使用的方法调用少。

示例

Map::from( ['a', 'b'] )->includes( 'a' );
// true

Map::from( ['a', 'b'] )->includes( ['a', 'b'] );
// true

Map::from( ['a', 'b'] )->includes( 'x' );
// false

Map::from( ['a', 'b'] )->includes( ['a', 'x'] );
// false

Map::from( ['1', '2'] )->includes( 2, true );
// false

index()

返回给定键的数值索引。

public function index( $value ) : ?int

@param \Closure|string|int $value 要搜索的键或带有 (key) 参数的函数，如果找到键则返回 TRUE
@return int|null 找到的值的位置（基于零）或未找到时返回 NULL

示例

Map::from( [4 => 'a', 8 => 'b'] )->index( '8' );
// 1

Map::from( [4 => 'a', 8 => 'b'] )->index( function( $key ) {
    return $key == '8';
} );
// 1

两个示例都将返回 "1"，因为值 "b" 在第二个位置，返回的索引是零基的，因此第一个项的索引是 "0"。

insertAfter()

在给定元素之后插入值或值。

public function insertAfter( $element, $value ) : self

@param mixed $element 值插入后的元素
@param mixed $value 要插入的元素或元素列表
@return self<int|string,mixed> 更新的映射，用于流畅接口

数值数组索引不会被保留。

示例

Map::from( ['a' => 'foo', 'b' => 'bar'] )->insertAfter( 'foo', 'baz' );
// ['a' => 'foo', 0 => 'baz', 'b' => 'bar']

Map::from( ['foo', 'bar'] )->insertAfter( 'foo', ['baz', 'boo'] );
// ['foo', 'baz', 'boo', 'bar']

Map::from( ['foo', 'bar'] )->insertAfter( null, 'baz' );
// ['foo', 'bar', 'baz']

insertAt()

在映射中的给定位置插入项。

public function insertAt( int $pos, $element, $key = null ) : self

@param int $pos 元素应插入的位置
@param mixed $element 要插入的元素
@param 混合|null $key 元素键或NULL自动分配整数键
@return self<int|string,mixed> 更新的映射，用于流畅接口

示例

Map::from( ['a' => 'foo', 'b' => 'bar'] )->insertAt( 0, 'baz' );
// [0 => 'baz', 'a' => 'foo', 'b' => 'bar']

Map::from( ['a' => 'foo', 'b' => 'bar'] )->insertAt( 1, 'baz', 'c' );
// ['a' => 'foo', 'c' => 'baz', 'b' => 'bar']

Map::from( ['a' => 'foo', 'b' => 'bar'] )->insertAt( 5, 'baz' );
// ['a' => 'foo', 'b' => 'bar', 'c' => 'baz']

Map::from( ['a' => 'foo', 'b' => 'bar'] )->insertAt( -1, 'baz', 'c' );
// ['a' => 'foo', 'c' => 'baz', 'b' => 'bar']

insertBefore()

在指定元素之前插入值或值。

public function insertBefore( $element, $value ) : self

@param 混合 $element 插入值之前的元素
@param mixed $value 要插入的元素或元素列表
@return self<int|string,mixed> 更新的映射，用于流畅接口

数值数组索引不会被保留。

示例

Map::from( ['a' => 'foo', 'b' => 'bar'] )->insertBefore( 'bar', 'baz' );
// ['a' => 'foo', 0 => 'baz', 'b' => 'bar']

Map::from( ['foo', 'bar'] )->insertBefore( 'bar', ['baz', 'boo'] );
// ['foo', 'baz', 'boo', 'bar']

Map::from( ['foo', 'bar'] )->insertBefore( null, 'baz' );
// ['foo', 'bar', 'baz']

inString()

检查传入的值是否为映射中字符串的一部分。

此方法已过时，建议使用多字节感知的 strContains() 方法。

public function inString( $value, bool $case = true ) : bool

@param 数组|string $value 要比较映射元素的值，将转换为字符串类型
@param bool $case 如果比较区分大小写则为TRUE，否则为FALSE
@return bool 如果至少有一个元素匹配，则返回TRUE，如果值不在映射的任何字符串中，则返回FALSE

所有标量值（bool、float、int和string）在比较之前都转换为字符串值。地图中的非标量值将被忽略。

示例

Map::from( ['abc'] )->inString( 'c' );
// true ('abc' contains 'c')

Map::from( ['abc'] )->inString( 'bc' );
// true ('abc' contains 'bc')

Map::from( [12345] )->inString( '23' );
// true ('12345' contains '23')

Map::from( [123.4] )->inString( 23.4 );
// true ('123.4' contains '23.4')

Map::from( [12345] )->inString( false );
// true ('12345' contains '')

Map::from( [12345] )->inString( true );
// true ('12345' contains '1')

Map::from( [false] )->inString( false );
// true  ('' contains '')

Map::from( ['abc'] )->inString( '' );
// true ('abc' contains '')

Map::from( [''] )->inString( false );
// true ('' contains '')

Map::from( ['abc'] )->inString( 'BC', false );
// true ('abc' contains 'BC' when case-insentive)

Map::from( ['abc', 'def'] )->inString( ['de', 'xy'] );
// true ('def' contains 'de')

Map::from( ['abc', 'def'] )->inString( ['E', 'x'] );
// false (doesn't contain "E" when case sensitive)

Map::from( ['abc', 'def'] )->inString( 'E' );
// false (doesn't contain "E" when case sensitive)

Map::from( [23456] )->inString( true );
// false ('23456' doesn't contain '1')

Map::from( [false] )->inString( 0 );
// false ('' doesn't contain '0')

int()

通过键返回元素，如果可能，将其转换为整数。

public function int( $key, $default = 0 ) : int

@param int|string $key 请求项的键或路径
@param 混合 $default 如果找不到键的默认值（将转换为int）
@return int 映射中的值或默认值

示例

Map::from( ['a' => true] )->int( 'a' );
// 1

Map::from( ['a' => '1'] )->int( 'a' );
// 1 (casted to integer)

Map::from( ['a' => 1.1] )->int( 'a' );
// 1 (casted to integer)

Map::from( ['a' => '10'] )->int( 'a' );
// 10 (casted to integer)

Map::from( ['a' => ['b' => ['c' => 1]]] )->int( 'a/b/c' );
// 1

Map::from( [] )->int( 'c', function() { return rand( 1, 1 ); } );
// 1

Map::from( [] )->int( 'a', 1 );
// 1 (default value used)

Map::from( [] )->int( 'a' );
// 0

Map::from( ['b' => ''] )->int( 'b' );
// 0 (casted to integer)

Map::from( ['a' => 'abc'] )->int( 'a' );
// 0 (casted to integer)

Map::from( ['b' => null] )->int( 'b' );
// 0 (null is not scalar)

Map::from( ['b' => [true]] )->int( 'b' );
// 0 (arrays are not scalar)

Map::from( ['b' => '#resource'] )->int( 'b' );
// 0 (resources are not scalar)

Map::from( ['b' => new \stdClass] )->int( 'b' );
// 0 (objects are not scalar)

Map::from( [] )->int( 'c', new \Exception( 'error' ) );
// throws exception

intersect()

返回一个新映射，其中包含在映射和给定元素中都可用的所有值。

public function intersect( iterable $elements, callable $callback = null ) : self

@param iterable<int|string,mixed> $elements 元素列表
参数 callable|null $callback：带有 (valueA, valueB) 参数的函数，并返回 -1 (<), 0 (=) 和 1 (>)
@return self<int|string,mixed> 新地图

使用此方法保留键。

示例

Map::from( ['a' => 'foo', 'b' => 'bar'] )->intersect( ['bar'] );
// ['b' => 'bar']

如果传递了回调函数，将使用该函数来比较值。函数必须接受两个参数（valA, valB），如果valA小于valB，则返回-1，如果两者相等，则返回0，如果valA大于valB，则返回1。可以传递方法名和匿名函数。

Map::from( [0 => 'a'] )->intersect( [0 => 'A'], 'strcasecmp' );
// ['a']

Map::from( ['b' => 'a'] )->intersect( ['B' => 'A'], 'strcasecmp' );
// ['a']

Map::from( ['b' => 'a'] )->intersect( ['c' => 'A'], function( $valA, $valB ) {
    return strtolower( $valA ) <=> strtolower( $valB );
} );
// ['a']

intersectAssoc()

返回一个新映射，其中包含在映射和给定元素中都可用的所有值，同时比较键。

public function intersectAssoc( iterable $elements, callable $callback = null ) : self

@param iterable<int|string,mixed> $elements 元素列表
参数 callable|null $callback：带有 (valueA, valueB) 参数的函数，并返回 -1 (<), 0 (=) 和 1 (>)
@return self<int|string,mixed> 新地图

使用此方法保留键。

示例

Map::from( ['a' => 'foo', 'b' => 'bar'] )->intersectAssoc( new Map( ['foo', 'b' => 'bar'] ) );
// ['a' => 'foo']

Map::from( [0 => 'a'] )->intersectAssoc( [0 => 'A'], 'strcasecmp' );
// [0 => 'a']

Map::from( ['b' => 'a'] )->intersectAssoc( ['B' => 'A'], 'strcasecmp' );
// ['b' => 'a']

Map::from( ['b' => 'a'] )->intersectAssoc( ['c' => 'A'], function( $valA, $valB ) {
    return strtolower( $valA ) <=> strtolower( $valB );
} );
// []

intersectKeys()

通过仅比较键，返回一个新映射，其中包含在映射和给定元素中都可用的所有值。

public function intersectKeys( iterable $elements, callable $callback = null ) : self

@param iterable<int|string,mixed> $elements 元素列表
参数 callable|null $callback：带有 (keyA, keyB) 参数的函数，并返回 -1 (<), 0 (=) 和 1 (>)
@return self<int|string,mixed> 新地图

使用此方法保留键。

示例

Map::from( ['a' => 'foo', 'b' => 'bar'] )->intersectKeys( new Map( ['foo', 'b' => 'baz'] ) );
// ['b' => 'bar']

Map::from( [0 => 'a'] )->intersectKeys( [0 => 'A'], 'strcasecmp' );
// [0 => 'a']

Map::from( ['b' => 'a'] )->intersectKeys( ['B' => 'X'], 'strcasecmp' );
// ['b' => 'a']

Map::from( ['b' => 'a'] )->intersectKeys( ['c' => 'a'], function( $keyA, $keyB ) {
    return strtolower( $keyA ) <=> strtolower( $keyB );
} );
// []

is()

检查映射是否由相同的键和值组成。

public function is( iterable $list, bool $strict = false ) : bool

@param iterable<int|string,mixed> $list 要比较的键/值对列表
@param bool $strict 如果为TRUE，则比较元素的顺序，如果为FALSE，则仅比较键/值
@return bool 如果给定列表相等，则返回TRUE，否则返回FALSE

示例

Map::from( ['a', 'b'] )->is( ['b', 'a'] );
// true

Map::from( ['a', 'b'] )->is( ['b', 'a'], true );
// false

Map::from( [1, 2] )->is( ['1', '2'] );
// false

isEmpty()

确定映射是否为空。

public function isEmpty() : bool

@return bool 如果映射为空，则为 TRUE，否则为 FALSE

此方法与 empty() 方法等效。

示例

Map::from( [] )->isEmpty();
// true

Map::from( ['a'] )-isEmpty();
// false

isObject()

确定所有条目是否是对象。

public function isObject() : bool

@return bool 如果所有映射条目都是对象，则返回TRUE，否则返回FALSE

示例

Map::from( [] )->isObject();
// true

Map::from( [new stdClass] )->isObject();
// true

Map::from( [1] )->isObject();
// false

isNumeric()

确定所有条目是否是数值。

public function isNumeric() : bool

@return bool 如果所有映射条目都是数值，则返回TRUE，否则返回FALSE

示例

Map::from( [] )->isNumeric();
// true

Map::from( [1] )->isNumeric();
// true

Map::from( [1.1] )->isNumeric();
// true

Map::from( [010] )->isNumeric();
// true

Map::from( [0x10] )->isNumeric();
// true

Map::from( [0b10] )->isNumeric();
// true

Map::from( ['010'] )->isNumeric();
// true

Map::from( ['10'] )->isNumeric();
// true

Map::from( ['10.1'] )->isNumeric();
// true

Map::from( [' 10 '] )->isNumeric();
// true

Map::from( ['10e2'] )->isNumeric();
// true

Map::from( ['0b10'] )->isNumeric();
// false

Map::from( ['0x10'] )->isNumeric();
// false

Map::from( ['null'] )->isNumeric();
// false

Map::from( [null] )->isNumeric();
// false

Map::from( [true] )->isNumeric();
// false

Map::from( [[]] )->isNumeric();
// false

Map::from( [''] )->isNumeric();
// false

isScalar()

确定所有条目是否是标量值。

public function isScalar() : bool

@return bool 如果所有映射条目都是标量值，则返回TRUE，否则返回FALSE

示例

Map::from( [] )->isScalar();
// true

Map::from( [1] )->isScalar();
// true

Map::from( [1.1] )->isScalar();
// true

Map::from( ['abc'] )->isScalar();
// true

Map::from( [true, false] )->isScalar();
// true

Map::from( [new stdClass] )->isScalar();
// false

Map::from( [resource] )->isScalar();
// false

Map::from( [null] )->isScalar();
// false

Map::from( [[1]] )->isScalar();
// false

isString()

确定所有条目是否是字符串值。

public function isString() : bool

@return bool 如果所有映射条目都是字符串值，则返回TRUE，否则返回FALSE

示例

Map::from( ['abc'] )->isString();
// true

Map::from( [] )->isString();
// true

Map::from( [1] )->isString();
// false

Map::from( [1.1] )->isString();
// false

Map::from( [true, false] )->isString();
// false

Map::from( [new stdClass] )->isString();
// false

Map::from( [resource] )->isString();
// false

Map::from( [null] )->isString();
// false

Map::from( [[1]] )->isString();
// false

join()

连接所有元素的字符串表示。

public function join( $glue = '' ) : string

@param string $glue 在元素之间添加的字符或字符串
@return string 连接的映射元素字符串

实现 __toString() 的对象也有效，否则（以及数组的情况下）将生成PHP通知。NULL和FALSE值被视为空字符串。

示例

Map::from( ['a', 'b', false] )->join();
// 'ab'

Map::from( ['a', 'b', null, false] )->join( '-' );
// 'a-b--'

jsonSerialize()

指定应该由 json_encode() 序列化的数据。

public function jsonSerialize()

@return array<int|string,mixed> 要序列化为JSON的数据

示例

json_encode( Map::from( ['a', 'b'] ) );
// ["a", "b"]

json_encode( Map::from( ['a' => 0, 'b' => 1] ) );
// {"a":0,"b":1}

keys()

返回映射元素键的新映射对象中的键。

public function keys() : self

@return self<int|string,mixed> 新地图

示例

Map::from( ['a', 'b'] );
// [0, 1]

Map::from( ['a' => 0, 'b' => 1] );
// ['a', 'b']

krsort()

按键的逆序对元素进行排序。

public function krsort( int $options = SORT_REGULAR ) : self

@param int $options krsort() 的排序选项
@return self<int|string,mixed> 更新的映射，用于流畅接口

参数修改了键的比较方式。可能的值是

SORT_REGULAR : 正常比较元素（不更改类型）
SORT_NUMERIC : 数值比较元素
SORT_STRING : 将元素作为字符串比较
SORT_LOCALE_STRING : 根据当前区域设置或通过 setlocale() 修改的区域设置，将元素作为字符串比较
SORT_NATURAL : 使用“自然排序”比较元素，如 natsort()
SORT_FLAG_CASE : 使用 SORT_STRING|SORT_FLAG_CASE 和 SORT_NATURAL|SORT_FLAG_CASE 对字符串进行不区分大小写的排序

使用此方法保留键，不创建新映射。

示例

Map::from( ['b' => 0, 'a' => 1] )->krsort();
// ['a' => 1, 'b' => 0]

Map::from( [1 => 'a', 0 => 'b'] )->krsort();
// [0 => 'b', 1 => 'a']

ksort()

按键对元素进行排序。

public function ksort( int $options = SORT_REGULAR ) : self

@param int $options ksort() 的排序选项
@return self<int|string,mixed> 更新的映射，用于流畅接口

参数修改了键的比较方式。可能的值是

SORT_REGULAR : 正常比较元素（不更改类型）
SORT_NUMERIC : 数值比较元素
SORT_STRING : 将元素作为字符串比较
SORT_LOCALE_STRING : 根据当前区域设置或通过 setlocale() 修改的区域设置，将元素作为字符串比较
SORT_NATURAL : 使用“自然排序”比较元素，如 natsort()
SORT_FLAG_CASE : 使用 SORT_STRING|SORT_FLAG_CASE 和 SORT_NATURAL|SORT_FLAG_CASE 对字符串进行不区分大小写的排序

使用此方法保留键，不创建新映射。

示例

Map::from( ['b' => 0, 'a' => 1] )->ksort();
// ['a' => 1, 'b' => 0]

Map::from( [1 => 'a', 0 => 'b'] )->ksort();
// [0 => 'b', 1 => 'a']

last()

返回映射中的最后一个元素。

public function last( $default = null )

@param mixed $default 如果映射不包含元素，则为默认值或异常
@return mixed 映射的最后一个值，(生成)默认值或异常

示例

Map::from( ['a', 'b'] )->last();
// 'b'

Map::from( [] )->last( 'x' );
// 'x'

Map::from( [] )->last( new \Exception( 'error' ) );
// throws \Exception

Map::from( [] )->last( function() { return rand(); } );
// random integer

lastKey()

返回映射中的最后一个键。

public function lastKey()

@return mixed 映射的最后一个键或为空时返回 NULL

示例

Map::from( ['a' => 1, 'b' => 2] )->lastKey();
// 'b'

Map::from( [] )->lastKey();
// null

ltrim()

从所有字符串的左侧删除传入的字符。

public function ltrim( string $chars = " \n\r\t\v\x00" ) : self

@param string $chars 要修剪的字符列表
@return self<int|string,mixed> 更新的映射，用于流畅接口

示例

Map::from( [" abc\n", "\tcde\r\n"] )->ltrim();
// ["abc\n", "cde\r\n"]

Map::from( ["a b c", "cbxa"] )->ltrim( 'abc' );
// [" b c", "xa"]

map()

对每个元素调用传入的函数一次，并返回一个包含结果的新映射。

public function map( callable $callback ) : self

@param callable $callback 带有 (value, key) 参数的函数并返回计算结果
@return self<int|string,mixed> 新映射，包含原始键和计算值

使用此方法保留键。

示例

Map::from( ['a' => 2, 'b' => 4] )->map( function( $value, $key ) {
    return $value * 2;
} );
// ['a' => 4, 'b' => 8]

max()

返回所有元素的最大值。

public function max( $col = null )

@param Closure|string|null $col 闭包，嵌套数组或对象中的键
@return mixed 最大值或映射中没有元素时返回 NULL

请注意比较不同类型的元素，因为这可能会由于 PHP 比较规则而产生不可预测的结果

示例

Map::from( [1, 3, 2, 5, 4] )->max();
// 5

Map::from( ['bar', 'foo', 'baz'] )->max();
// 'foo'

Map::from( [['p' => 30], ['p' => 50], ['p' => 10]] )->max( 'p' );
// 50

Map::from( [['i' => ['p' => 30]], ['i' => ['p' => 50]]] )->max( 'i/p' );
// 50

Map::from( [50, 10, 30] )->max( fn( $val, $key ) => $key > 0 );
// 30

merge()

将映射与给定的元素合并，而不返回新的映射。

public function merge( iterable $elements, bool $recursive = false ) : self

@param iterable<int|string,mixed> $elements 元素列表
@param bool $recursive TRUE 为合并嵌套数组，FALSE 只合并第一级元素
@return self<int|string,mixed> 更新的映射，用于流畅接口

具有相同非数字键的元素将被覆盖，具有相同数字键的元素将被添加。

此方法类似于 replace()，但不替换具有相同数字键的元素。如果想要确保所有传入的元素都添加而不替换现有的元素，请使用 concat()。

使用此方法保留键。

示例

Map::from( ['a', 'b'] )->merge( ['b', 'c'] );
// ['a', 'b', 'b', 'c']

Map::from( ['a' => 1, 'b' => 2] )->merge( ['b' => 4, 'c' => 6] );
// ['a' => 1, 'b' => 4, 'c' => 6]

Map::from( ['a' => 1, 'b' => 2] )->merge( ['b' => 4, 'c' => 6], true );
// ['a' => 1, 'b' => [2, 4], 'c' => 6]

method()

注册自定义方法或返回现有的方法。

public static function method( string $method, \Closure $fcn = null ) : ?\Closure

@param string $method 方法名
@param \Closure|null $fcn 匿名函数或 NULL 以返回可用的闭包
@return \Closure|null 注册的匿名函数或未注册时返回 NULL

已注册的方法在非静态调用时可以访问类属性。

示例

Map::method( 'foo', function( $arg1, $arg2 ) {
    return array_merge( $this->elements, [$arg1, $arg2] );
} );

Map::method( 'foo' );
// registered closure

Map::method( 'foo2' );
// NULL

Map::from( ['bar'] )->foo( 'foo', 'baz' );
// ['bar', 'foo', 'baz']



Map::foo( 'foo', 'baz' );
// error because `$this->elements` isn't available

静态调用不能访问 $this->elements，但可以操作参数值

Map::method( 'bar', function( $arg1, $arg2 ) {
    return new static( [$arg1, $arg2] );
} );

Map::foo( 'foo', 'baz' );
// ['foo', 'baz']

min()

返回所有元素的最小值。

public function min( $col = null )

@param Closure|string|null $col 闭包，嵌套数组或对象中的键
@return mixed 最小值或映射中没有元素时返回 NULL

请注意比较不同类型的元素，因为这可能会由于 PHP 比较规则而产生不可预测的结果

示例

Map::from( [2, 3, 1, 5, 4] )->min();
// 1

Map::from( ['baz', 'foo', 'bar'] )->min();
// 'bar'

Map::from( [['p' => 30], ['p' => 50], ['p' => 10]] )->min( 'p' );
// 10

Map::from( [['i' => ['p' => 30]], ['i' => ['p' => 50]]] )->min( 'i/p' );
// 30

Map::from( [10, 50, 30] )->min( fn( $val, $key ) => $key > 0 );
// 30

none()

检查元素是否都不是映射的一部分。

public function none( $element, bool $strict = false ) : bool

@param mixed|array $element 要在映射中搜索的元素或元素数组
@param bool $strict TRUE 用于检查类型，使用 FALSE '1' 和 1 将被视为相同
@return bool 如果所有元素都不是映射的一部分，返回 TRUE，如果至少有一个是，返回 FALSE

示例

Map::from( ['a', 'b'] )->none( 'x' );
// true

Map::from( ['1', '2'] )->none( 2, true );
// true

Map::from( ['a', 'b'] )->none( 'a' );
// false

Map::from( ['a', 'b'] )->none( ['a', 'b'] );
// false

Map::from( ['a', 'b'] )->none( ['a', 'x'] );
// false

nth()

返回映射中的每个第 n 个元素。

public function nth( int $step, int $offset = 0 ) : self

@param int $step 步长宽度
@param int $offset 从哪个元素开始（基于 0）
@return self<int|string,mixed> 新地图

示例

Map::from( ['a', 'b', 'c', 'd', 'e', 'f'] )->nth( 2 );
// ['a', 'c', 'e']

Map::from( ['a', 'b', 'c', 'd', 'e', 'f'] )->nth( 2, 1 );
// ['b', 'd', 'f']

offsetExists()

确定是否存在给定偏移的元素。

public function offsetExists( $key )

@param int|string $key 要检查的键
@return bool 如果键存在，返回 TRUE，如果不存在，返回 FALSE

示例

$map = Map::from( ['a' => 1, 'b' => 3, 'c' => null] );

isset( $map['b'] );
// true

isset( $map['c'] );
// false

isset( $map['d'] );
// false

offsetGet()

返回给定偏移的元素。

public function offsetGet( $key )

@param int|string $key 返回元素的键
@return mixed 与给定键关联的值

示例

$map = Map::from( ['a' => 1, 'b' => 3] );

$map['b'];
// 3

offsetSet()

在给定偏移处设置元素。

public function offsetSet( $key, $value )

@param int|string|null $key 设置元素的键或 NULL 以追加值
@param mixed $value 为键设置的新值

示例

$map = Map::from( ['a' => 1] );

$map['b'] = 2;
// ['a' => 1, 'b' => 2]

$map[0] = 4;
// ['a' => 1, 'b' => 2, 0 => 4]

offsetUnset()

在给定偏移处删除元素。

public function offsetUnset( $key )

@param int|string $key 要删除项的键

示例

$map = Map::from( ['a' => 1] );

unset( $map['a'] );
// []

only()

返回一个新的映射，其中只包含通过给定的键指定的元素。

public function only( $keys ) : self

@param iterable<mixed>|array<mixed>|string|int $keys 应返回的元素的键
@return self<int|string,mixed> 只包含通过键指定的元素的新映射

使用此方法保留键。

示例

Map::from( ['a' => 1, 0 => 'b'] )->only( 'a' );
// ['a' => 1]

Map::from( ['a' => 1, 0 => 'b', 1 => 'c'] )->only( [0, 1] );
// [0 => 'b', 1 => 'c']

order()

返回一个新的映射，其元素按传递的键排序。

public function order( iterable $keys ) : self

@param 可迭代 $keys 元素所需顺序的键
@return self 按传入键排序的新映射

使用此方法保留键。

示例

Map::from( ['a' => 1, 1 => 'c', 0 => 'b'] )->order( [0, 1, 'a'] );
// [0 => 'b', 1 => 'c', 'a' => 1]

Map::from( ['a' => 1, 1 => 'c', 0 => 'b'] )->order( [0, 1, 2] );
// [0 => 'b', 1 => 'c', 2 => null]

Map::from( ['a' => 1, 1 => 'c', 0 => 'b'] )->order( [0, 1] );
// [0 => 'b', 1 => 'c']

pad()

使用给定值填充到指定长度

public function pad( int $size, $value = null ) : self

@param int $size 列表中应包含的总元素数量
@param mixed $value 如果映射长度小于给定大小，则用于填充的值
@return self<int|string,mixed> 更新的映射，用于流畅接口

如果给定数字小于列表中已有的元素数量，则映射不变。如果大小为正，则新元素填充在右侧，如果为负，则填充在左侧。

保留关联键，数值键被替换，并使用数值键为新元素。

示例

Map::from( [1, 2, 3] )->pad( 5 );
// [1, 2, 3, null, null]

Map::from( [1, 2, 3] )->pad( -5 );
// [null, null, 1, 2, 3]

Map::from( [1, 2, 3] )->pad( 5, '0' );
// [1, 2, 3, '0', '0']

Map::from( [1, 2, 3] )->pad( 2 );
// [1, 2, 3]

Map::from( [10 => 1, 20 => 2] )->pad( 3 );
// [0 => 1, 1 => 2, 2 => null]

Map::from( ['a' => 1, 'b' => 2] )->pad( 3, 3 );
// ['a' => 1, 'b' => 2, 0 => 3]

partition()

将元素列表拆分为给定数量的组。

public function partition( $num ) : self

@param \Closure|int $number 以(value, index)为参数的函数，返回桶键或组数
@return self<int|string,mixed> 新地图

返回映射中保留原始映射的键。

示例

Map::from( [1, 2, 3, 4, 5] )->partition( 3 );
// [[0 => 1, 1 => 2], [2 => 3, 3 => 4], [4 => 5]]

Map::from( [1, 2, 3, 4, 5] )->partition( function( $val, $idx ) {
	return $idx % 3;
} );
// [0 => [0 => 1, 3 => 4], 1 => [1 => 2, 4 => 5], 2 => [2 => 3]]

percentage()

返回映射中所有通过测试的元素的百分比。

public function percentage( \Closure $fcn, int $precision = 2 ) : float

@param \Closure $fcn 闭包，用于过滤嵌套数组或对象中的值以计算百分比
@param int $precision 结果值使用的十进制位数
@return float 映射中通过测试的所有元素的百分比

示例

Map::from( [30, 50, 10] )->percentage( fn( $val, $key ) => $val < 50 );
// 66.67

Map::from( [] )->percentage( fn( $val, $key ) => true );
// 0.0

Map::from( [30, 50, 10] )->percentage( fn( $val, $key ) => $val > 100 );
// 0.0

Map::from( [30, 50, 10] )->percentage( fn( $val, $key ) => $val > 30, 3 );
// 33.333

Map::from( [30, 50, 10] )->percentage( fn( $val, $key ) => $val > 30, 0 );
// 33.0

Map::from( [30, 50, 10] )->percentage( fn( $val, $key ) => $val < 50, -1 );
// 70.0

pipe()

将映射传递给给定的回调并返回结果。

public function pipe( \Closure $callback )

@param \Closure $callback 以映射为参数的函数，返回任意结果
@return mixed 回调返回的结果

示例

Map::from( ['a', 'b'] )->pipe( function( $map ) {
    return strrev( $map->join( '-' ) );
} );
// 'b-a'

pluck()

从数组数组的单个列/属性返回值，或从列表元素返回的新地图中的元素。

public function pluck( string $valuecol = null, string $indexcol = null ) : self

@param string|null $valuecol 值属性的名称或路径
@param string|null $indexcol 索引属性的名称或路径
@return self<int|string,mixed> 新地图，包含映射的条目

此方法是col()的别名。出于性能原因，应首选col()，因为它比pluck()少一个方法调用。

pop()

返回并删除映射的最后一个元素。

public function pop()

@return mixed 映射的最后一个元素或为空时返回null

示例

Map::from( ['a', 'b'] )->pop();
// 'b', map contains ['a']

pos

返回值的数值索引。

public function pos( $value ) : ?int

@param \Closure|mixed $value 要搜索的值或具有(item, key)参数的函数，如果找到值则返回TRUE
@return int|null 找到的值的位置（基于零）或未找到时返回 NULL

示例

Map::from( [4 => 'a', 8 => 'b'] )->pos( 'b' );
// 1

Map::from( [4 => 'a', 8 => 'b'] )->pos( function( $item, $key ) {
    return $item === 'b';
} );
// 1

两个示例都将返回 "1"，因为值 "b" 在第二个位置，返回的索引是零基的，因此第一个项的索引是 "0"。

prefix

在映射的每个条目前添加前缀。

public function prefix( $prefix, int $depth = null ) : self

@param \Closure|string $prefix 以映射为参数的函数，返回任意结果
@param int|null $depth 从"1"开始的最大深度，用于多维度数组
@return self<int|string,mixed> 更新的映射，用于流畅接口

默认情况下，递归遍历嵌套数组，因此所有级别的条目都添加了前缀。返回映射中保留原始映射的键。

示例

Map::from( ['a', 'b'] )->prefix( '1-' );
// ['1-a', '1-b']

Map::from( ['a', ['b']] )->prefix( '1-' );
// ['1-a', ['1-b']]

Map::from( ['a', ['b']] )->prefix( '1-', 1 );
// ['1-a', ['b']]

Map::from( ['a', 'b'] )->prefix( function( $item, $key ) {
    return ( ord( $item ) + ord( $key ) ) . '-';
} );
// ['145-a', '147-b']

prepend()

将元素推送到映射的开始而不返回新的映射。

public function prepend( $value, $key = null ) : self

@param mixed $value 添加到开始的项
@param int|string|null $key 项的键或NULL以重新索引所有数值键
@return self<int|string,mixed> 更新的映射，用于流畅接口

此方法是对unshift()方法的别名。

示例

Map::from( ['a', 'b'] )->prepend( 'd' );
// ['d', 'a', 'b']

Map::from( ['a', 'b'] )->prepend( 'd', 'first' );
// ['first' => 'd', 0 => 'a', 1 => 'b']

pull()

通过键返回并删除映射中的元素。

public function pull( $key, $default = null )

@param int|string $key 用于检索值的键
@param mixed $default 如果键不可用，则返回的默认值
@return mixed 映射中的值或默认值

示例

Map::from( ['a', 'b', 'c'] )->pull( 1 );
// 'b', map contains ['a', 'c']

Map::from( ['a', 'b', 'c'] )->pull( 'x', 'none' );
// 'none', map contains ['a', 'b', 'c']

push()

将元素添加到映射的末尾而不返回新的映射。

public function push( $value ) : self

@param mixed $value 添加到末尾的值
@return self<int|string,mixed> 更新的映射，用于流畅接口

示例

Map::from( ['a', 'b'] )->push( 'aa' );
// ['a', 'b', 'aa']

put()

在映射中设置给定的键和值而不返回新的映射。

public function put( $key, $value ) : self

此方法是对set()的别名。出于性能原因，应首选set()，因为它比put()少一个方法调用。

@param int|string $key 设置新值的键
@param mixed $value 应设置的新元素
@return self<int|string,mixed> 更新的映射，用于流畅接口

示例

Map::from( ['a'] )->put( 1, 'b' );
// [0 => 'a', 1 => 'b']

Map::from( ['a'] )->put( 0, 'b' );
// [0 => 'b']

random()

从映射中返回一个或多个随机元素。

public function random( int $max = 1 ) : self

@param int $max 应返回的最大元素数量
@return self<int|string,mixed> 原地图中键/元素对的新地图，顺序随机
@throws \InvalidArgumentException 如果请求的元素数量小于1

地图中的元素越少，顺序越不随机，特别是当最大值数很高或接近元素数量时。

返回映射中保留原始映射的键。

示例

Map::from( [2, 4, 8, 16] )->random();
// [2 => 8] or any other key/value pair

Map::from( [2, 4, 8, 16] )->random( 2 );
// [3 => 16, 0 => 2] or any other key/value pair

Map::from( [2, 4, 8, 16] )->random( 5 );
// [0 => 2,  1 => 4, 2 => 8, 3 => 16] in random order

reduce()

迭代使用回调函数将数组减少到单个值。

public function reduce( callable $callback, $initial = null )

@param callable $callback 具有参数(result, value)的函数并返回结果
@param mixed $initial 计算结果时的初始值
@return mixed 回调函数计算出的值

之后，地图将为空。

示例

Map::from( [2, 8] )->reduce( function( $result, $value ) {
    return $result += $value;
}, 10 );
// 20 because 10 + 2 + 8 and map equals []

reject()

删除所有匹配的元素并返回一个新的地图。

public function reject( $callback = true ) : self

@param Closure|mixed $callback 具有参数(item)的函数，返回TRUE/FALSE或与值比较的值
@return self<int|string,mixed> 新地图

此方法与filter()相反，如果项目应从返回的地图中删除，则应返回TRUE。

如果没有传递回调函数，则将删除所有非空、null或false的值。保留原始地图的键。

示例

Map::from( [2 => 'a', 6 => 'b', 13 => 'm', 30 => 'z'] )->reject( function( $value, $key ) {
    return $value < 'm';
} );
// [13 => 'm', 30 => 'z']

Map::from( [2 => 'a', 13 => 'm', 30 => 'z'] )->reject( 'm' );
// [2 => 'a', 30 => 'z']

Map::from( [2 => 'a', 6 => null, 13 => 'm'] )->reject();
// [6 => null]

rekey()

根据传入的函数更改键。

public function rekey( callable $callback ) : self

@param callable $callback 具有参数(value, key)的函数并返回新键
@return self<int|string,mixed> 新地图，具有新键和原始值

示例

Map::from( ['a' => 2, 'b' => 4] )->rekey( function( $value, $key ) {
    return 'key-' . $key;
} );
// ['key-a' => 2, 'key-b' => 4]

remove()

通过键从地图中删除一个或多个元素，而不返回新地图。

public function remove( $keys ) : self

@param iterable<int|string>|array<int|string>|string|int $keys 键列表
@return self<int|string,mixed> 更新的映射，用于流畅接口

示例

Map::from( ['a' => 1, 2 => 'b'] )->remove( 'a' );
// [2 => 'b']

Map::from( ['a' => 1, 2 => 'b'] )->remove( [2, 'a'] );
// []

replace()

在不返回新地图的情况下用给定的元素替换地图中的元素。

public function replace( iterable $elements, bool $recursive = true ) : self

@param iterable<int|string,mixed> $elements 元素列表
@param bool $recursive TRUE为递归替换（默认），FALSE仅替换元素
@return self<int|string,mixed> 更新的映射，用于流畅接口

此方法与merge()类似，但也用数字键替换元素。这些将由merge()添加，并使用新的数字键。

键在返回的地图中保留。

示例

Map::from( ['a' => 1, 2 => 'b'] )->replace( ['a' => 2] );
// ['a' => 2, 2 => 'b']

Map::from( ['a' => 1, 'b' => ['c' => 3, 'd' => 4]] )->replace( ['b' => ['c' => 9]] );
// ['a' => 1, 'b' => ['c' => 9, 'd' => 4]]

reverse()

反转元素顺序，而不返回新地图。

public function reverse() : self

@return self<int|string,mixed> 更新的映射，用于流畅接口

使用此方法保留键。

示例

Map::from( ['a', 'b'] )->reverse();
// ['b', 'a']

Map::from( ['name' => 'test', 'last' => 'user'] )->reverse();
// ['last' => 'user', 'name' => 'test']

rsort()

以逆序对所有元素进行排序，而不保持键关联。

public function rsort( int $options = SORT_REGULAR ) : self

@param int $options rsort()的排序选项
@return self<int|string,mixed> 更新的映射，用于流畅接口

参数修改了值的比较方式。可能的参数值包括

SORT_REGULAR : 正常比较元素（不更改类型）
SORT_NUMERIC : 数值比较元素
SORT_STRING : 将元素作为字符串比较
SORT_LOCALE_STRING : 根据当前区域设置或通过 setlocale() 修改的区域设置，将元素作为字符串比较
SORT_NATURAL : 使用“自然排序”比较元素，如 natsort()
SORT_FLAG_CASE : 使用 SORT_STRING|SORT_FLAG_CASE 和 SORT_NATURAL|SORT_FLAG_CASE 对字符串进行不区分大小写的排序

键不被保留，元素得到新的索引。不创建新地图。

示例

Map::from( ['a' => 1, 'b' => 0] )->rsort();
// [0 => 1, 1 => 0]

Map::from( [0 => 'b', 1 => 'a'] )->rsort();
// [0 => 'b', 1 => 'a']

Map::from( [0 => 'C', 1 => 'b'] )->rsort();
// [0 => 'b', 1 => 'C']

Map::from( [0 => 'C', 1 => 'b'] )->rsort( SORT_STRING|SORT_FLAG_CASE );
// [0 => 'C', 1 => 'b'] because 'C' -> 'c' and 'c' > 'b'

rtrim()

从所有字符串的右侧删除传入的字符。

public function rtrim( string $chars = " \n\r\t\v\x00" ) : self

@param string $chars 要修剪的字符列表
@return self<int|string,mixed> 更新的映射，用于流畅接口

示例

Map::from( [" abc\n", "\tcde\r\n"] )->rtrim();
// [" abc", "\tcde"]

Map::from( ["a b c", "cbxa"] )->rtrim( 'abc' );
// ["a b ", "cbx"]

search()

在地图中搜索给定的值，如果成功则返回相应的键。

public function search( $value, $strict = true )

@param mixed $value 要搜索的项目
@param bool $strict 如果元素类型也应进行检查，则TRUE
@return int|string|null 与值关联的键或未找到则null

示例

Map::from( ['a', 'b', 'c'] )->search( 'b' );
// 1

Map::from( [1, 2, 3] )->search( '2', true );
// null because the types doesn't match (int vs. string)

sep()

设置多维数组或对象中值路径的分隔符。

public static function sep( string $char ) : self

@param string $char 分隔符字符，例如，用"."代替"key/to/value"中的"key/to/value"
@return self<int|string,mixed> 同一映射，用于流畅接口

此方法仅更改当前地图实例的分隔符。要更改之后创建的所有地图的分隔符，请使用静态Map::delimiter()方法。

示例

Map::from( ['foo' => ['bar' => 'baz']] )->sep( '.' )->get( 'foo.bar' );
// 'baz'

set()

通过键在地图中设置元素，而不返回新地图。

public function set( $key, $value ) : self

@param int|string $key 设置新值的键
@param mixed $value 应设置的新元素
@return self<int|string,mixed> 更新的映射，用于流畅接口

示例

Map::from( ['a'] )->set( 1, 'b' );
// [0 => 'a', 1 => 'b']

Map::from( ['a'] )->set( 0, 'b' );
// [0 => 'b']

shift()

返回并从地图中删除第一个元素。

public function shift()

@return mixed|null 地图中的值或未找到则null

示例

Map::from( ['a', 'b'] )->shift();
// 'a'

Map::from( [] )->shift();
// null

性能说明

列表越大，性能影响越高，因为 shift() 会重新索引所有现有元素。通常，如果要从列表中删除大量元素，最好先使用 reverse() 逆序列表，然后 pop() 列表中的条目。

$map->reverse()->pop();

而不是

$map->shift();

shuffle()

在映射中随机排列元素而不返回新的映射。

public function shuffle( bool $assoc = false ) : self

@param bool $assoc 为 true 时保留键，为 false 时分配新键
@return self<int|string,mixed> 更新的映射，用于流畅接口

示例

Map::from( [2 => 'a', 4 => 'b'] )->shuffle();
// ['a', 'b'] in random order with new keys

Map::from( [2 => 'a', 4 => 'b'] )->shuffle( true );
// [2 => 'a', 4 => 'b'] in random order with keys preserved

skip()

返回一个包含指定数量跳过项的新映射。

public function skip( $offset ) : self

@param \Closure|int $offset 跳过的项目数或返回 true 以跳过项的函数($item, $key)
@return self<int|string,mixed> 新地图

新映射中返回的项目键与原始映射中的键相同。

示例

Map::from( [1, 2, 3, 4] )->skip( 2 );
// [2 => 3, 3 => 4]

Map::from( [1, 2, 3, 4] )->skip( function( $item, $key ) {
    return $item < 4;
} );
// [3 => 4]

slice()

返回原始映射的切片。

public function slice( int $offset, int $length = null ) : self

@param int $offset 从哪里开始的数量
@param int|null $length 要返回的数量或 NULL 无限制
@return self<int|string,mixed> 新地图

偏移量的规则是

如果偏移量非负，则序列将从该偏移量开始
如果偏移量是负数，则序列将从末尾开始那个距离

长度类似

如果给出了长度并且是正数，那么序列将包含最多那么多元素
如果数组比长度短，则只包含可用的数组元素
如果长度给出并且是负数，则序列将停止在结束前的那个距离
如果省略，则序列将从偏移量到末尾的所有内容

新映射中返回的项目键与原始映射中的键相同。

示例

Map::from( ['a', 'b', 'c'] )->slice( 1 );
// ['b', 'c']

Map::from( ['a', 'b', 'c'] )->slice( 1, 1 );
// ['b']

Map::from( ['a', 'b', 'c', 'd'] )->slice( -2, -1 );
// ['c']

some()

测试至少一个元素是否通过测试或是否是映射的一部分。

public function some( $values, bool $strict = false ) : bool

@param \Closure|iterable|mixed $values 带有(item, key)参数的匿名函数，元素或要测试的元素列表
@param bool $strict TRUE 用于检查类型，使用 FALSE '1' 和 1 将被视为相同
返回值 bool：如果映射中至少有一个元素可用，则为 TRUE；如果映射中不包含这些元素，则为 FALSE

示例

Map::from( ['a', 'b'] )->some( 'a' );
// true

Map::from( ['a', 'b'] )->some( ['a', 'c'] );
// true

Map::from( ['a', 'b'] )->some( function( $item, $key ) {
    return $item === 'a'
} );
// true

Map::from( ['a', 'b'] )->some( ['c', 'd'] );
// false

Map::from( ['1', '2'] )->some( [2], true );
// false

sort()

对所有元素进行排序而不保持键关联。

public function sort( int $options = SORT_REGULAR ) : self

@param int $options sort() 的排序选项
@return self<int|string,mixed> 更新的映射，用于流畅接口

参数修改了值的比较方式。可能的参数值包括

SORT_REGULAR : 正常比较元素（不更改类型）
SORT_NUMERIC : 数值比较元素
SORT_STRING : 将元素作为字符串比较
SORT_LOCALE_STRING : 根据当前区域设置或通过 setlocale() 修改的区域设置，将元素作为字符串比较
SORT_NATURAL : 使用“自然排序”比较元素，如 natsort()
SORT_FLAG_CASE : 使用 SORT_STRING|SORT_FLAG_CASE 和 SORT_NATURAL|SORT_FLAG_CASE 对字符串进行不区分大小写的排序

键不被保留，元素得到新的索引。不创建新地图。

示例

Map::from( ['a' => 1, 'b' => 0] )->sort();
// [0 => 0, 1 => 1]

Map::from( [0 => 'b', 1 => 'a'] )->sort();
// [0 => 'a', 1 => 'b']

splice()

删除映射的一部分并用给定的替换项替换，然后返回更新后的映射。

public function splice( int $offset, int $length = null, $replacement = [] ) : self

@param int $offset 从哪里开始的数量
@param int|null $length 要删除的元素数，NULL 为全部
@param mixed $replacement 要插入的元素列表
@return self<int|string,mixed> 新地图

偏移量的规则是

如果偏移量非负，则序列将从该偏移量开始
如果偏移量是负数，则序列将从末尾开始那个距离

长度类似

如果给出了长度并且是正数，那么序列将包含最多那么多元素
如果数组比长度短，则只包含可用的数组元素
如果长度给出并且是负数，则序列将停止在结束前的那个距离
如果省略，则序列将从偏移量到末尾的所有内容

数值数组索引不被保留。

示例

Map::from( ['a', 'b', 'c'] )->splice( 1 );
// ['b', 'c'] and map contains ['a']

Map::from( ['a', 'b', 'c'] )->splice( 1, 1, ['x', 'y'] );
// ['b'] and map contains ['a', 'x', 'y', 'c']

strAfter()

返回传递值之后的字符串。

public function strAfter( string $value, bool $case = false, string $encoding = 'UTF-8' ) : self

@param string $value 要搜索的字符或字符串
@param bool $case 如果搜索不区分大小写则为 TRUE，如果区分大小写则为 FALSE
@param string $encoding 字符串的字符编码，例如 "UTF-8"（默认）,"ASCII"，“ISO-8859-1”，等等
@return self<int|string,mixed> 新地图

所有标量值（bool、int、float、string）都将转换为字符串。非标量值以及空字符串将被跳过，不包括在结果中。

示例

Map::from( ['äöüß'] )->strAfter( 'ö' );
// ['üß']

Map::from( ['abc'] )->strAfter( '' );
// ['abc']

Map::from( ['abc'] )->strAfter( 'b' );
// ['c']

Map::from( ['abc'] )->strAfter( 'c' );
// ['']

Map::from( ['abc'] )->strAfter( 'x' )
// []

Map::from( [''] )->strAfter( '' );
// []

Map::from( [1, 1.0, true, ['x'], new \stdClass] )->strAfter( '' );
// ['1', '1', '1']

Map::from( [0, 0.0, false, []] )->strAfter( '' );
// ['0', '0']

strBefore()

返回传递值之前的字符串。

public function strBefore( string $value, bool $case = false, string $encoding = 'UTF-8' ) : self

@param string $value 要搜索的字符或字符串
@param bool $case 如果搜索不区分大小写则为 TRUE，如果区分大小写则为 FALSE
@param string $encoding 字符串的字符编码，例如 "UTF-8"（默认）,"ASCII"，“ISO-8859-1”，等等
@return self<int|string,mixed> 新地图

所有标量值（bool、int、float、string）都将转换为字符串。非标量值以及空字符串将被跳过，不包括在结果中。

示例

Map::from( ['äöüß'] )->strBefore( 'ü' );
// ['äö']

Map::from( ['abc'] )->strBefore( '' );
// ['abc']

Map::from( ['abc'] )->strBefore( 'b' );
// ['a']

Map::from( ['abc'] )->strBefore( 'a' );
// ['']

Map::from( ['abc'] )->strBefore( 'x' )
// []

Map::from( [''] )->strBefore( '' );
// []

Map::from( [1, 1.0, true, ['x'], new \stdClass] )->strBefore( '' );
// ['1', '1', '1']

Map::from( [0, 0.0, false, []] )->strBefore( '' );
// ['0', '0']

strContains()

测试至少一个传递的字符串是否至少在一条条目中。

public function strContains( $value, string $encoding = 'UTF-8' ) : bool

@param array|string $value 要在每条条目中搜索的字符串或字符串列表
@param string $encoding 字符串的字符编码，例如 "UTF-8"（默认）,"ASCII"，“ISO-8859-1”，等等
@return bool 如果条目包含字符串之一则为 TRUE，如果不包含则为 FALSE

示例

Map::from( ['abc'] )->strContains( '' );
// true

Map::from( ['abc'] )->strContains( 'a' );
// true

Map::from( ['abc'] )->strContains( 'bc' );
// true

Map::from( [12345] )->strContains( '23' );
// true

Map::from( [123.4] )->strContains( 23.4 );
// true

Map::from( [12345] )->strContains( false );
// true ('12345' contains '')

Map::from( [12345] )->strContains( true );
// true ('12345' contains '1')

Map::from( [false] )->strContains( false );
// true  ('' contains '')

Map::from( [''] )->strContains( false );
// true ('' contains '')

Map::from( ['abc'] )->strContains( ['b', 'd'] );
// true

Map::from( ['abc'] )->strContains( 'c', 'ASCII' );
// true

Map::from( ['abc'] )->strContains( 'd' );
// false

Map::from( ['abc'] )->strContains( 'cb' );
// false

Map::from( [23456] )->strContains( true );
// false ('23456' doesn't contain '1')

Map::from( [false] )->strContains( 0 );
// false ('' doesn't contain '0')

Map::from( ['abc'] )->strContains( ['d', 'e'] );
// false

Map::from( ['abc'] )->strContains( 'cb', 'ASCII' );
// false

strContainsAll()

测试所有条目是否都包含传递的字符串之一。

public function strContainsAll( $value, string $encoding = 'UTF-8' ) : bool

@param array|string $value 要在每条条目中搜索的字符串或字符串列表
@param string $encoding 字符串的字符编码，例如 "UTF-8"（默认）,"ASCII"，“ISO-8859-1”，等等
@return bool 如果所有条目都包含至少一个字符串则为 TRUE，如果不包含则为 FALSE

示例

Map::from( ['abc', 'def'] )->strContainsAll( '' );
// true

Map::from( ['abc', 'cba'] )->strContainsAll( 'a' );
// true

Map::from( ['abc', 'bca'] )->strContainsAll( 'bc' );
// true

Map::from( [12345, '230'] )->strContainsAll( '23' );
// true

Map::from( [123.4, 23.42] )->strContainsAll( 23.4 );
// true

Map::from( [12345, '234'] )->strContainsAll( [true, false] );
// true ('12345' contains '1' and '234' contains '')

Map::from( ['', false] )->strContainsAll( false );
// true ('' contains '')

Map::from( ['abc', 'def'] )->strContainsAll( ['b', 'd'] );
// true

Map::from( ['abc', 'ecf'] )->strContainsAll( 'c', 'ASCII' );
// true

Map::from( ['abc', 'def'] )->strContainsAll( 'd' );
// false

Map::from( ['abc', 'cab'] )->strContainsAll( 'cb' );
// false

Map::from( [23456, '123'] )->strContains( true );
// false ('23456' doesn't contain '1')

Map::from( [false, '000'] )->strContains( 0 );
// false ('' doesn't contain '0')

Map::from( ['abc', 'acf'] )->strContainsAll( ['d', 'e'] );
// false

Map::from( ['abc', 'bca'] )->strContainsAll( 'cb', 'ASCII' );
// false

strEnds()

测试至少一个条目是否以传递的字符串之一结束。

public function strEnds( $value, string $encoding = 'UTF-8' ) : bool

@param array|string $value 要在每条条目中搜索的字符串或字符串列表
@param string $encoding 字符串的字符编码，例如 "UTF-8"（默认）,"ASCII"，“ISO-8859-1”，等等
@return bool 如果条目以字符串结束则为 TRUE，如果不结束则为 FALSE

示例

Map::from( ['abc'] )->strEnds( '' );
// true

Map::from( ['abc'] )->strEnds( 'c' );
// true

Map::from( ['abc'] )->strEnds( 'bc' );
// true

Map::from( ['abc'] )->strEnds( ['b', 'c'] );
// true

Map::from( ['abc'] )->strEnds( 'c', 'ASCII' );
// true

Map::from( ['abc'] )->strEnds( 'a' );
// false

Map::from( ['abc'] )->strEnds( 'cb' );
// false

Map::from( ['abc'] )->strEnds( ['d', 'b'] );
// false

Map::from( ['abc'] )->strEnds( 'cb', 'ASCII' );
// false

strEndsAll()

测试所有条目是否都以传递的字符串之一结束。

public function strEndsAll( $value, string $encoding = 'UTF-8' ) : bool

@param array|string $value 要在每条条目中搜索的字符串或字符串列表
@param string $encoding 字符串的字符编码，例如 "UTF-8"（默认）,"ASCII"，“ISO-8859-1”，等等
@return bool 如果所有条目都以至少一个字符串结束则为 TRUE，如果不结束则为 FALSE

示例

Map::from( ['abc', 'def'] )->strEndsAll( '' );
// true

Map::from( ['abc', 'bac'] )->strEndsAll( 'c' );
// true

Map::from( ['abc', 'cbc'] )->strEndsAll( 'bc' );
// true

Map::from( ['abc', 'def'] )->strEndsAll( ['c', 'f'] );
// true

Map::from( ['abc', 'efc'] )->strEndsAll( 'c', 'ASCII' );
// true

Map::from( ['abc', 'fed'] )->strEndsAll( 'd' );
// false

Map::from( ['abc', 'bca'] )->strEndsAll( 'ca' );
// false

Map::from( ['abc', 'acf'] )->strEndsAll( ['a', 'c'] );
// false

Map::from( ['abc', 'bca'] )->strEndsAll( 'ca', 'ASCII' );
// false

string()

通过键获取元素并将其转换为字符串（如果可能）。

public function string( $key, $default = '' ) : string

@param int|string $key 请求项的键或路径
@param mixed $default 如果找不到键时的默认值（将被转换为字符串）
@return string 地图中的值或默认值

示例

Map::from( ['a' => true] )->string( 'a' );
// '1'

Map::from( ['a' => 1] )->string( 'a' );
// '1'

Map::from( ['a' => 1.1] )->string( 'a' );
// '1.1'

Map::from( ['a' => 'abc'] )->string( 'a' );
// 'abc'

Map::from( ['a' => ['b' => ['c' => 'yes']]] )->string( 'a/b/c' );
// 'yes'

Map::from( [] )->string( 'c', function() { return 'no'; } );
// 'no'

Map::from( [] )->string( 'b' );
// ''

Map::from( ['b' => ''] )->string( 'b' );
// ''

Map::from( ['b' => null] )->string( 'b' );
// ''

Map::from( ['b' => [true]] )->string( 'b' );
// ''

Map::from( ['b' => '#resource'] )->string( 'b' );
// '' (resources are not scalar)

Map::from( ['b' => new \stdClass] )->string( 'b' );
// '' (objects are not scalar)

Map::from( [] )->string( 'c', new \Exception( 'error' ) );
// throws exception

strLower()

将字符串中的所有字母字符转换为小写。

public function strLower( string $encoding = 'UTF-8' ) : self

@param string $encoding 字符串的字符编码，例如 "UTF-8"（默认）,"ASCII"，“ISO-8859-1”，等等
@return self<int|string,mixed> 更新的映射，用于流畅接口

示例

Map::from( ['My String'] )->strLower();
// ["my string"]

Map::from( ['Τάχιστη'] )->strLower();
// ["τάχιστη"]

Map::from( ['Äpfel', 'Birnen'] )->strLower( 'ISO-8859-1' );
// ["äpfel", "birnen"]

strReplace()

将搜索字符串的所有出现替换为替换字符串。

public function strReplace( $search, $replace, bool $case = false ) : self

@param array|string $search 要搜索的字符串或字符串列表
@param array|string $replace 替换字符串或字符串列表
@param bool $case 如果替换不区分大小写则为 TRUE，如果区分大小写则为 FALSE
@return self<int|string,mixed> 更新的映射，用于流畅接口

如果您使用字符串数组进行搜索或搜索/替换，字符串的顺序很重要！每个找到的搜索字符串都由同一位置的对应替换字符串替换。

如果参数为数组，并且替换字符串的数量少于搜索字符串的数量，则没有对应替换字符串的搜索字符串将被替换为空字符串。没有对应搜索字符串的替换字符串将被忽略。

只有当搜索参数也是字符串数组时，才允许替换参数为数组。

由于该方法从左到右替换，因此在执行多次替换时可能会替换先前插入的值。非字符串值保持不变。

示例

Map::from( ['google.com', 'aimeos.com'] )->strReplace( '.com', '.de' );
// ['google.de', 'aimeos.de']

Map::from( ['google.com', 'aimeos.org'] )->strReplace( ['.com', '.org'], '.de' );
// ['google.de', 'aimeos.de']

Map::from( ['google.com', 'aimeos.org'] )->strReplace( ['.com', '.org'], ['.de'] );
// ['google.de', 'aimeos']

Map::from( ['google.com', 'aimeos.org'] )->strReplace( ['.com', '.org'], ['.fr', '.de'] );
// ['google.fr', 'aimeos.de']

Map::from( ['google.com', 'aimeos.com'] )->strReplace( ['.com', '.co'], ['.co', '.de', '.fr'] );
// ['google.de', 'aimeos.de']

Map::from( ['google.com', 'aimeos.com', 123] )->strReplace( '.com', '.de' );
// ['google.de', 'aimeos.de', 123]

Map::from( ['GOOGLE.COM', 'AIMEOS.COM'] )->strReplace( '.com', '.de', true );
// ['GOOGLE.de', 'AIMEOS.de']

strStarts()

检查至少一个条目是否以传递的字符串之一开头。

public function strStarts( $value, string $encoding = 'UTF-8' ) : bool

@param array|string $value 要在每条条目中搜索的字符串或字符串列表
@param string $encoding 字符串的字符编码，例如 "UTF-8"（默认）,"ASCII"，“ISO-8859-1”，等等
@return bool 如果一个条目以一个字符串开头则为 TRUE，否则为 FALSE

示例

Map::from( ['abc'] )->strStarts( '' );
// true

Map::from( ['abc'] )->strStarts( 'a' );
// true

Map::from( ['abc'] )->strStarts( 'ab' );
// true

Map::from( ['abc'] )->strStarts( ['a', 'b'] );
// true

Map::from( ['abc'] )->strStarts( 'ab', 'ASCII' );
// true

Map::from( ['abc'] )->strStarts( 'b' );
// false

Map::from( ['abc'] )->strStarts( 'bc' );
// false

Map::from( ['abc'] )->strStarts( ['b', 'c'] );
// false

Map::from( ['abc'] )->strStarts( 'bc', 'ASCII' );
// false

strStartsAll()

检查所有条目是否以传递的字符串之一开头。

public function strStartsAll( $value, string $encoding = 'UTF-8' ) : bool

@param array|string $value 要在每条条目中搜索的字符串或字符串列表
@param string $encoding 字符串的字符编码，例如 "UTF-8"（默认）,"ASCII"，“ISO-8859-1”，等等
@return bool 如果一个条目以一个字符串开头则为 TRUE，否则为 FALSE

示例

Map::from( ['abc', 'def'] )->strStartsAll( '' );
// true

Map::from( ['abc', 'acb'] )->strStartsAll( 'a' );
// true

Map::from( ['abc', 'aba'] )->strStartsAll( 'ab' );
// true

Map::from( ['abc', 'def'] )->strStartsAll( ['a', 'd'] );
// true

Map::from( ['abc', 'acf'] )->strStartsAll( 'a', 'ASCII' );
// true

Map::from( ['abc', 'def'] )->strStartsAll( 'd' );
// false

Map::from( ['abc', 'bca'] )->strStartsAll( 'ab' );
// false

Map::from( ['abc', 'bac'] )->strStartsAll( ['a', 'c'] );
// false

Map::from( ['abc', 'cab'] )->strStartsAll( 'ab', 'ASCII' );
// false

strUpper()

将字符串中的所有字母字符转换为大写。

public function strUpper( string $encoding = 'UTF-8' ) :self

@param string $encoding 字符串的字符编码，例如 "UTF-8"（默认）,"ASCII"，“ISO-8859-1”，等等
@return self<int|string,mixed> 更新的映射，用于流畅接口

示例

Map::from( ['My String'] )->strUpper();
// ["MY STRING"]

Map::from( ['τάχιστη'] )->strUpper();
// ["ΤΆΧΙΣΤΗ"]

Map::from( ['äpfel', 'birnen'] )->strUpper( 'ISO-8859-1' );
// ["ÄPFEL", "BIRNEN"]

suffix

在每个地图条目的末尾添加后缀。

public function suffix( $suffix, int $depth = null ) : self

@param \Closure|string $suffix 接受地图作为参数并返回任意结果的功能
@param int|null $depth 从"1"开始的最大深度，用于多维度数组
@return self<int|string,mixed> 更新的映射，用于流畅接口

默认情况下，嵌套数组递归遍历，因此所有级别的条目都添加后缀。使用此方法保留键。

示例

Map::from( ['a', 'b'] )->suffix( '-1' );
// ['a-1', 'b-1']

Map::from( ['a', ['b']] )->suffix( '-1' );
// ['a-1', ['b-1']]

Map::from( ['a', ['b']] )->suffix( '-1', 1 );
// ['a-1', ['b']]

Map::from( ['a', 'b'] )->suffix( function( $item, $key ) {
    return '-' . ( ord( $item ) + ord( $key ) );
} );
// ['a-145', 'b-147']

sum()

返回地图中所有整数和浮点值的总和。

public function sum( $col = null ) : float

@param Closure|string|null $col 闭包，嵌套数组或对象中的键，用于求和
@return float 所有元素的总和或 0（如果地图中没有元素）

示例

Map::from( [1, 3, 5] )->sum();
// 9

Map::from( [1, 'sum', 5] )->sum();
// 6

Map::from( [['p' => 30], ['p' => 50], ['p' => 10]] )->sum( 'p' );
// 90

Map::from( [['i' => ['p' => 30]], ['i' => ['p' => 50]]] )->sum( 'i/p' );
// 80

Map::from( [30, 50, 10] )->sum( fn( $val, $key ) => $val < 50 );
// 40

take()

返回具有给定项目数的新地图。

public function take( int $size, $offset = 0 ) : self

@param int $size 要返回的项目数
@param \Closure|int $offset 跳过的项目数或返回 true 以跳过项的函数($item, $key)
@return self<int|string,mixed> 新地图

新映射中返回的项目键与原始映射中的键相同。

示例

Map::from( [1, 2, 3, 4] )->take( 2 );
// [0 => 1, 1 => 2]

Map::from( [1, 2, 3, 4] )->take( 2, 1 );
// [1 => 2, 2 => 3]

Map::from( [1, 2, 3, 4] )->take( 2, -2 );
// [2 => 3, 3 => 4]

Map::from( [1, 2, 3, 4] )->take( 2, function( $item, $key ) {
    return $item < 2;
} );
// [1 => 2, 2 => 3]

tap()

将地图的副本传递给给定的回调。

public function tap( callable $callback ) : self

@param callable $callback 接收 ($map) 参数的功能
@return self<int|string,mixed> 同一映射，用于流畅接口

用于在两个方法调用之间“检查”方法链的状态。回调中执行的操作不会更改原始地图。

示例

Map::from( [3, 2, 1] )->rsort()->tap( function( $map ) {
    print_r( $map->remove( 0 )->toArray() );
} )->first();
// 1

它将列表按反向顺序排序（[1, 2, 3]），然后打印项目（[2, 3]），不包括传递给 tap() 的函数中的第一个项目，并在最后返回第一个项目（“1”）。

times()

通过调用闭包指定的次数创建新地图。

public static function times( int $num, \Closure $callback ) : self

@param int $num 函数调用的次数
@param \Closure $callback 接受 (value, key) 参数并返回新值的功能
@return self<int|string,mixed> 包含生成元素的新地图

此方法创建了一个懒惰的地图，条目在调用操作地图内容的另一个方法后生成。因此，传递的回调不会立即调用！

示例

Map::times( 3, function( $num ) {
    return $num * 10;
} );
// [0 => 0, 1 => 10, 2 => 20]

Map::times( 3, function( $num, &$key ) {
    $key = $num * 2;
    return $num * 5;
} );
// [0 => 0, 2 => 5, 4 => 10]

Map::times( 2, function( $num ) {
    return new \stdClass();
} );
// [0 => new \stdClass(), 1 => new \stdClass()]

toArray()

以纯数组的形式返回元素。

public function toArray() : array

@return array 纯数组

示例

Map::from( ['a'] )->toArray();
// ['a']

toJson()

返回作为 JSON 字符串编码的元素。

public function toJson( int $options = 0 ) : ?string

@param int $options JSON_*常量的组合
@return 字符串|null 将数组编码为JSON字符串或在失败时返回NULL

有几种选项可以修改JSON字符串，具体请参阅PHP json_encode()手册。参数可以是一个单独的JSON_*常量，或者由位或（|）组合的几个常量的位掩码，例如

JSON_FORCE_OBJECT|JSON_HEX_QUOT

示例

Map::from( ['a', 'b'] )->toJson();
// '["a","b"]'

Map::from( ['a' => 'b'] )->toJson();
// '{"a":"b"}'

Map::from( ['a', 'b'] )->toJson( JSON_FORCE_OBJECT );
// '{"0":"a", "1":"b"}'

toUrl()

从映射元素创建HTTP查询字符串。

public function toUrl() : string

@return 字符串 GET请求的参数字符串

示例

Map::from( ['a' => 1, 'b' => 2] )->toUrl();
// a=1&b=2

Map::from( ['a' => ['b' => 'abc', 'c' => 'def'], 'd' => 123] )->toUrl();
// a%5Bb%5D=abc&a%5Bc%5D=def&d=123

transpose()

交换二维映射的行和列。

public function transpose() : self

@return self<int|string,mixed> 新地图

示例

Map::from( [
  ['name' => 'A', 2020 => 200, 2021 => 100, 2022 => 50],
  ['name' => 'B', 2020 => 300, 2021 => 200, 2022 => 100],
  ['name' => 'C', 2020 => 400, 2021 => 300, 2022 => 200],
] )->transpose();
/*
[
  'name' => ['A', 'B', 'C'],
  2020 => [200, 300, 400],
  2021 => [100, 200, 300],
  2022 => [50, 100, 200]
]
*/

Map::from( [
  ['name' => 'A', 2020 => 200, 2021 => 100, 2022 => 50],
  ['name' => 'B', 2020 => 300, 2021 => 200],
  ['name' => 'C', 2020 => 400]
] );
/*
[
  'name' => ['A', 'B', 'C'],
  2020 => [200, 300, 400],
  2021 => [100, 200],
  2022 => [50]
]
*/

traverse()

遍历嵌套项的树，将每个项传递给回调。

public function traverse( \Closure $callback = null, string $nestKey = 'children' ) : self

@param \Closure|null $callback 带有（entry，key，level，$parent）参数的回调，返回添加到结果中的项
@param 字符串 $nestKey 每个项子项的键
@return self<int|string,mixed> 新映射，其中所有项都是扁平列表

这适用于嵌套数组和具有公共属性的对象或实现__isset()和__get()方法的对象。要构建嵌套项的树，请使用tree()方法。

示例

Map::from( [[
  'id' => 1, 'pid' => null, 'name' => 'n1', 'children' => [
    ['id' => 2, 'pid' => 1, 'name' => 'n2', 'children' => []],
    ['id' => 3, 'pid' => 1, 'name' => 'n3', 'children' => []]
  ]
]] )->traverse();
/*
[
  ['id' => 1, 'pid' => null, 'name' => 'n1', 'children' => [...]],
  ['id' => 2, 'pid' => 1, 'name' => 'n2', 'children' => []],
  ['id' => 3, 'pid' => 1, 'name' => 'n3', 'children' => []],
]
*/

Map::from( [[
  'id' => 1, 'pid' => null, 'name' => 'n1', 'children' => [
    ['id' => 2, 'pid' => 1, 'name' => 'n2', 'children' => []],
    ['id' => 3, 'pid' => 1, 'name' => 'n3', 'children' => []]
  ]
]] )->traverse( function( $entry, $key, $level ) {
  return str_repeat( '-', $level ) . '- ' . $entry['name'];
} );
// ['- n1', '-- n2', '-- n3']

Map::from( [[
  'id' => 1, 'pid' => null, 'name' => 'n1', 'children' => [
    ['id' => 2, 'pid' => 1, 'name' => 'n2', 'children' => []],
    ['id' => 3, 'pid' => 1, 'name' => 'n3', 'children' => []]
  ]
]] )->traverse( function( &$entry, $key, $level, $parent ) {
  $entry['path'] = isset( $parent['path'] ) ? $parent['path'] . '/' . $entry['name'] : $entry['name'];
  return $entry;
} );
/*
[
  ['id' => 1, 'pid' => null, 'name' => 'n1', 'children' => [...], 'path' => 'n1'],
  ['id' => 2, 'pid' => 1, 'name' => 'n2', 'children' => [], 'path' => 'n1/n2'],
  ['id' => 3, 'pid' => 1, 'name' => 'n3', 'children' => [], 'path' => 'n1/n3'],
]
*/

Map::from( [[
  'id' => 1, 'pid' => null, 'name' => 'n1', 'nodes' => [
    ['id' => 2, 'pid' => 1, 'name' => 'n2', 'nodes' => []]
  ]
]] )->traverse( null, 'nodes' );
/*
[
  ['id' => 1, 'pid' => null, 'name' => 'n1', 'nodes' => [...]],
  ['id' => 2, 'pid' => 1, 'name' => 'n2', 'nodes' => []],
]
*/

tree()

从列表项创建树结构。

public function tree( string $idKey, string $parentKey, string $nestKey = 'children' ) : self

@param 字符串 $idKey 节点唯一ID的键的名称
@param 字符串 $parentKey 节点ID的键的名称
@param 字符串 $nestKey 将包含节点子项的键的名称
@return self<int|string,mixed> 新映射，包含一个或多个根树节点

使用此方法重建树，例如从数据库记录中重建。要遍历树，请使用traverse()方法。

示例

Map::from( [
  ['id' => 1, 'pid' => null, 'lvl' => 0, 'name' => 'n1'],
  ['id' => 2, 'pid' => 1, 'lvl' => 1, 'name' => 'n2'],
  ['id' => 3, 'pid' => 2, 'lvl' => 2, 'name' => 'n3'],
  ['id' => 4, 'pid' => 1, 'lvl' => 1, 'name' => 'n4'],
  ['id' => 5, 'pid' => 3, 'lvl' => 2, 'name' => 'n5'],
  ['id' => 6, 'pid' => 1, 'lvl' => 1, 'name' => 'n6'],
] )->tree( 'id', 'pid' );
/*
[1 => [
  'id' => 1, 'pid' => null, 'lvl' => 0, 'name' => 'n1', 'children' => [
    2 => ['id' => 2, 'pid' => 1, 'lvl' => 1, 'name' => 'n2', 'children' => [
      3 => ['id' => 3, 'pid' => 2, 'lvl' => 2, 'name' => 'n3', 'children' => []]
    ]],
    4 => ['id' => 4, 'pid' => 1, 'lvl' => 1, 'name' => 'n4', 'children' => [
      5 => ['id' => 5, 'pid' => 3, 'lvl' => 2, 'name' => 'n5', 'children' => []]
    ]],
    6 => ['id' => 6, 'pid' => 1, 'lvl' => 1, 'name' => 'n6', 'children' => []]
  ]
]]
*/

为了正确构建树，项必须按顺序排列，或者至少低级别的节点必须首先排列。对于这样的树

n1
|- n2
|  |- n3
|- n4
|  |- n5
|- n6

接受的项目顺序

顺序：n1, n2, n3, n4, n5, n6
低级别首先：n1, n2, n4, n6, n3, n5

如果您的项目是无序的，请先对映射条目应用usort()，例如

Map::from( [['id' => 3, 'lvl' => 2], ...] )->usort( function( $item1, $item2 ) {
  return $item1['lvl'] <=> $item2['lvl'];
} );

trim()

从所有字符串的左侧/右侧删除指定的字符。

public function trim( string $chars = " \n\r\t\v\x00" ) : self

@param string $chars 要修剪的字符列表
@return self<int|string,mixed> 更新的映射，用于流畅接口

示例

Map::from( [" abc\n", "\tcde\r\n"] )->trim();
// ["abc", "cde"]

Map::from( ["a b c", "cbax"] )->trim( 'abc' );
// [" b ", "x"]

uasort()

使用回调对所有元素进行排序并保持键关联。

public function uasort( callable $callback ) : self

@param callable $callback 带有（itemA，itemB）参数的函数，并返回-1 (<), 0 (=) 和 1 (>)
@return self<int|string,mixed> 更新的映射，用于流畅接口

给定的回调将用于比较值。该回调必须接受两个参数（项目A和B），如果项目A小于项目B，则返回-1，如果两者相等，则返回0，如果项目A大于项目B，则返回1。可以传递方法名和匿名函数。

使用此方法保留键，不创建新映射。

示例

Map::from( ['a' => 'B', 'b' => 'a'] )->uasort( 'strcasecmp' );
// ['b' => 'a', 'a' => 'B']

Map::from( ['a' => 'B', 'b' => 'a'] )->uasort( function( $itemA, $itemB ) {
    return strtolower( $itemA ) <=> strtolower( $itemB );
} );
// ['b' => 'a', 'a' => 'B']

uksort()

使用回调按键对映射元素进行排序。

public function uksort( callable $callback ) : self

@param callable $callback 带有（keyA，keyB）参数的函数，并返回-1 (<), 0 (=) 和 1 (>)
@return self<int|string,mixed> 更新的映射，用于流畅接口

给定的回调将用于比较键。该回调必须接受两个参数（键A和B），如果键A小于键B，则返回-1，如果两者相等，则返回0，如果键A大于键B，则返回1。可以传递方法名和匿名函数。

使用此方法保留键，不创建新映射。

示例

Map::from( ['B' => 'a', 'a' => 'b'] )->uksort( 'strcasecmp' );
// ['a' => 'b', 'B' => 'a']

Map::from( ['B' => 'a', 'a' => 'b'] )->uksort( function( $keyA, $keyB ) {
    return strtolower( $keyA ) <=> strtolower( $keyB );
} );
// ['a' => 'b', 'B' => 'a']

union()

构建元素和给定元素的并集，而不返回新的映射。映射中现有的键不会被覆盖

public function union( iterable $elements ) : self

@param iterable<int|string,mixed> $elements 元素列表
@return self<int|string,mixed> 更新的映射，用于流畅接口

如果应覆盖列表条目，请使用merge()代替。此方法使用键并创建新映射。

示例

Map::from( [0 => 'a', 1 => 'b'] )->union( [0 => 'c'] );
// [0 => 'a', 1 => 'b'] because the key 0 isn't overwritten

Map::from( ['a' => 1, 'b' => 2] )->union( ['c' => 1] );
// ['a' => 1, 'b' => 2, 'c' => 1]

unique()

从映射中返回唯一元素的新映射

public function unique( string $key = null ) : self

@param 字符串|null $key 要检查的嵌套数组或对象的键或路径
@return self<int|string,mixed> 新地图

两个元素被认为是相等的，如果比较它们的字符串表示形式返回 TRUE

(string) $elem1 === (string) $elem2

只有在没有传递键的情况下，元素的键才会保留在新映射中。

示例

Map::from( [0 => 'a', 1 => 'b', 2 => 'b', 3 => 'c'] )->unique();
// [0 => 'a', 1 => 'b', 3 => 'c']

Map::from( [['p' => '1'], ['p' => 1], ['p' => 2]] )->unique( 'p' );
// [['p' => 1], ['p' => 2]]

Map::from( [['i' => ['p' => '1']], ['i' => ['p' => 1]]] )->unique( 'i/p' );
// [['i' => ['p' => '1']]]

unshift()

将元素推送到映射的开始而不返回新的映射。

public function unshift( $value, $key = null ) : self

@param mixed $value 添加到开始的项
@param int|string|null $key 项的键或NULL以重新索引所有数值键
@return self<int|string,mixed> 更新的映射，用于流畅接口

只有在没有传递键的情况下，元素的键才会保留在新映射中。

示例

Map::from( ['a', 'b'] )->unshift( 'd' );
// ['d', 'a', 'b']

Map::from( ['a', 'b'] )->unshift( 'd', 'first' );
// ['first' => 'd', 0 => 'a', 1 => 'b']

性能说明

列表越大，性能影响越高，因为 unshift() 需要创建一个新列表并将所有现有元素复制到新数组中。通常，最好在列表末尾push()新条目，然后reverse()列表

$map->push( 'a' )->push( 'b' )->reverse();

而不是

$map->unshift( 'a' )->unshift( 'b' );

usort()

使用回调函数对所有元素进行排序，而不保持键关联。

public function usort( callable $callback ) : self

@param callable $callback 带有（itemA，itemB）参数的函数，并返回-1 (<), 0 (=) 和 1 (>)
@return self<int|string,mixed> 更新的映射，用于流畅接口

键不被保留，元素得到新的索引。不创建新地图。

示例

Map::from( ['a' => 'B', 'b' => 'a'] )->usort( 'strcasecmp' );
// [0 => 'a', 1 => 'B']

Map::from( ['a' => 'B', 'b' => 'a'] )->usort( function( $itemA, $itemB ) {
    return strtolower( $itemA ) <=> strtolower( $itemB );
} );
// [0 => 'a', 1 => 'B']

values()

重置键并返回一个新映射中的值。

public function values() : self

@return self<int|string,mixed> 新的值映射

示例

Map::from( ['x' => 'b', 2 => 'a', 'c'] )->values();
// [0 => 'b', 1 => 'a', 2 => 'c']

walk()

将给定的回调函数应用于所有元素。

public function walk( callable $callback, $data = null, bool $recursive = true ) : self

@param callable $callback 带有 (item, key, data) 参数的函数
@param mixed $data 作为第三个参数传递给回调函数的任意数据
@param bool $recursive TRUE 以递归方式遍历子数组（默认），FALSE 仅迭代映射元素
@return self<int|string,mixed> 更新的映射，用于流畅接口

要更改映射的值，将值参数指定为引用（&$value）。您只能更改值，但不能更改键或数组结构。

默认情况下，映射中的数组元素将递归遍历。要仅迭代映射元素，将第三个参数传递为 FALSE。

示例

Map::from( ['a', 'B', ['c', 'd'], 'e'] )->walk( function( &$value ) {
    $value = strtoupper( $value );
} );
// ['A', 'B', ['C', 'D'], 'E']

Map::from( [66 => 'B', 97 => 'a'] )->walk( function( $value, $key ) {
    echo 'ASCII ' . $key . ' is ' . $value . "\n";
} );
/*
ASCII 66 is B
ASCII 97 is a
*/

Map::from( [1, 2, 3] )->walk( function( &$value, $key, $data ) {
    $value = $data[$value] ?? $value;
}, [1 => 'one', 2 => 'two'] );
// ['one', 'two', 3]

where()

通过给定条件过滤元素列表。

public function where( string $key, string $op, $value ) : self

@param string $key 用于比较的数组或对象的键或值路径
@param string $op 用于比较的运算符
@param mixed $value 用于比较的值
@return self<int|string,mixed> 用于流畅接口的新映射

支持的运算符有

'==' : 等于
'===' : 等于且类型相同
'!=' : 不等于
'!==' : 不等于且类型相同
'<=' : 小于等于
'>=' : 大于等于
'<' : 小于
'>' : 大于
'in' : 值数组在列表中的值
'-' : 数组中的值在开始和结束值之间，例如 [10, 100]（包含）

返回映射中保留原始映射的键。

示例

Map::from( [
  ['id' => 1, 'type' => 'name'],
  ['id' => 2, 'type' => 'short'],
] )->where( 'type', '==', 'name' );
/*
[
    ['id' => 1, 'type' => 'name']
]
*/

Map::from( [
  ['id' => 3, 'price' => 10],
  ['id' => 4, 'price' => 50],
] )->where( 'price', '>', 20 );
/*
[
    ['id' => 4, 'price' => 50]
]
*/

Map::from( [
  ['id' => 3, 'price' => 10],
  ['id' => 4, 'price' => 50],
] )->where( 'price', 'in', [10, 25] );
/*
[
    ['id' => 3, 'price' => 10]
]
*/

Map::from( [
  ['id' => 3, 'price' => 10],
  ['id' => 4, 'price' => 50],
] )->where( 'price', '-', [10, 100] );
/*
[
    ['id' => 3, 'price' => 10],
    ['id' => 4, 'price' => 50]
]
*/

Map::from( [
  ['item' => ['id' => 3, 'price' => 10]],
  ['item' => ['id' => 4, 'price' => 50]],
] )->where( 'item/price', '>', 30 );
/*
[
    ['id' => 4, 'price' => 50]
]
*/

with()

返回一个新映射的副本，其中给定索引处的元素替换为给定值。

public function with( $key, $value ) : self

@param int|string $key 要设置或替换的数组键
@param mixed $value 给定键的新值
@return self<int|string,mixed> 新的值映射

原始映射保持不变！此方法是调用 copy() 和 set() 方法的快捷方式。

示例

$m = Map::from( ['a' => 1] );

$m->with( 2, 'b' );
// ['a' => 1, 2 => 'b']

$m->with( 'a', 2 );
// ['a' => 2]

$m->all();
// ['a' => 1]

zip()

合并所有数组在对应索引的值。

public function zip( $array1, ... ) : self

@param array<int|string,mixed>|\Traversable<int|string,mixed>|\Iterator<int|string,mixed> $array1 要合并的数组列表
@return self<int|string,mixed> 新的数组映射

示例

Map::from( [1, 2, 3] )->zip( ['one', 'two', 'three'], ['uno', 'dos', 'tres'] );
/*
[
    [1, 'one', 'uno'],
    [2, 'two', 'dos'],
    [3, 'three', 'tres'],
]
*/

自定义方法

通常，只需将匿名函数传递给 pipe() 方法即可在映射对象中实现自定义功能

Map::from( ['a', 'b'] )->pipe( function( $map ) {
    return strrev( $map->join( '-' ) );
} );

如果您需要在源代码的不同位置频繁使用某些功能，那么最好一次性注册自定义方法并在所有地方调用它

Map::method( 'strrev', function( $sep ) {
    return strrev( join( '-', $this->list() ) );
} );
Map::from( ['a', 'b'] )->strrev( '-' );

确保在使用之前注册方法。您可以传递任意参数给您的函数，并且它可以访问映射的内部。因此，您的函数可以使用 $this 调用所有可用方法

Map::method( 'notInBoth', function( iterable $elements ) {
    return new self( $this->diff( $elements ) + Map::from( $elements )->diff( $this->items ) );
} );

您的自定义方法可以访问包含映射元素的 $this->items 数组，也可以使用内部 $this->getArray( iterable $list ) 方法将可迭代参数（数组、生成器和实现 \Traversable 的对象）转换为普通数组

Map::method( 'mycombine', function( iterable $keys ) {
    return new self( array_combine( $this->getArray( $keys ), $this-items ) );
} );

性能

大多数方法的性能仅取决于Map类内部使用的array_*函数。如果Map类的其他方法包含额外的代码，它们将被优化以尽可能快。

创建Map与数组的比较

使用数组创建Map对象而不是仅创建一个普通数组会慢得多（大约10倍），但从绝对值来看，我们谈论的是纳秒。只有在创建10,000个Map对象而不是10,000个数组时，这才会变得明显。然后，创建Map对象将额外耗时约10毫秒。

通常，这并不是一个大问题，因为应用程序创建的数组元素数量很多，而不是10,000多个数组。不过，如果你的应用程序在某个区域内创建了非常大量的数组，你应该考虑在该区域内避免使用Map对象。

如果你使用map()函数或Map::from()来创建Map对象，请注意这会添加另一个函数调用。使用这些方法创建Map对象的时间大约是new Map()时间的1.1倍或1.3倍。

结论：使用new Map()是最快的，而map()比Map::from()更快。

填充Map与数组

使用$map[] = 'a'向Map对象添加元素大约比在普通数组中执行相同的操作慢5倍。这是因为会调用offsetSet()方法而不是直接将新元素添加到数组中。这也适用于$map->push( 'a' )方法。

在循环中创建数组时，应首先填充数组，然后从数组创建Map对象

$list = [];
for( $i = 0; $i < 1000; $i++ ) {
	$list[] = $i;
}
$map = map( $list );

创建Map对象时不会复制数组，因此在之后使用Map几乎没有性能损失。

使用Map方法与语言构造

像empty()、count()或isset()这样的语言构造比调用方法快，使用$map->isEmpty()或$map->count()大约慢4倍。

我们再次谈论的是纳秒。对于10,000次对empty( $array )的调用与对$map->isEmpty()的调用相比，总成本大约是4毫秒。

使用Map方法与array_*函数

使用Map方法而不是array_*函数会添加一个额外的函数调用。内部，Map对象使用相同的array_*函数，但提供了一个更易用的接口。

额外函数调用的时间几乎可以忽略不计，因为array_*方法需要更长的时间来执行对数组元素的操作，这取决于数组的大小。

使用匿名函数

Map的几个方法支持传递一个应用于Map中每个元素的匿名函数。PHP需要一些时间来调用传递的函数并执行其代码。根据元素的数量，这可能会对性能产生重大影响！

Map对象的pipe()方法是例外，因为它接收整个Map对象而不是每个元素单独接收。它的性能主要取决于实现代码。

$map->pipe( function( Map $map ) {
	// perform operations on the map
} );

使用shift()和unshift()

这两种方法都很昂贵，特别是在大型数组上。使用的array_shift()和array_unshift()函数将重新索引数组中所有数值键。

如果您想以迭代方式从开头减少或创建大量元素，应使用 reverse() 和 pop()/push() 而不是 shift() 和 unshift()/prepend()

$map->reverse()->pop(); // use pop() until it returns NULL
$map->push( 'z' )->push( 'y' )->push( 'x' )->reverse(); // use push() for adding

升级指南

2.x -> 3.x

使用 list() 方法

当向 Map 对象添加自己的方法时，不要直接访问 $this->list 类变量。它不再保证是一个数组，而是将存储传递给 Map 构造函数的值。相反，使用 `list()` 方法获取元素数组的引用

$this->list();

因为它是对元素数组的引用，所以您可以直接修改它，甚至可以使用需要变量引用的 PHP 函数

$this->list()[] = 123;
reset( $this->list() );

重命名内部方法

已经重命名了两个内部方法，如果您已经向 Map 对象添加了自己的方法，则必须使用它们的新名称

// instead of $this->getArray( $array )
$this->array( $array )

 // instead of $this->getValue( $entry, array $parts )
$this->val( $entry, array $parts )

1.x -> 2.x

jQuery 风格的方法调用

您可以使用这种方式调用 map 中的对象方法

// MyClass implements setStatus() (returning $this) and getCode() (initialized by constructor)

$map = Map::from( ['a' => new MyClass( 'x' ), 'b' => new MyClass( 'y' )] );
$map->setStatus( 1 )->getCode()->toArray();

以前，会检查对象是否实现了 setStatus() 和 getCode()。

现在不再这样检查，以避免在方法名错误或调用的方法使用 __call() 魔术方法实现时返回空 map。现在，如果方法不是所有对象都实现，PHP 将生成一个致命错误。

equals() 的第二个参数

equals() 方法的第二个参数（$assoc）用于比较键也已被删除。请使用 is() 方法代替

// 1.x
map( ['one' => 1] )->equals( ['one' => 1], true );

// 2.x
map( ['one' => 1] )->is( ['one' => 1] );

新的 find() 参数

现在可以向 find() 方法作为第二个参数传递默认值或异常对象。将 $reverse 参数移至第三个位置。

// 1.x
Map::from( ['a', 'c', 'e'] )->find( function( $value, $key ) {
    return $value >= 'b';
}, true );

// 2.x
Map::from( ['a', 'c', 'e'] )->find( function( $value, $key ) {
    return $value >= 'b';
}, null, true );

groupBy() 语义变更

如果传递给 groupBy() 的键不存在，则使用给定键对项目进行分组。现在，使用空字符串作为键，以提供更容易的键检查和排序。

Map::from( [
    10 => ['aid' => 123, 'code' => 'x-abc'],
] )->groupBy( 'xid' );

// 1.x
[
    'xid' => [
        10 => ['aid' => 123, 'code' => 'x-abc']
    ]
]

// 2.x
[
    '' => [
        10 => ['aid' => 123, 'code' => 'x-abc']
    ]
]

offsetExists() 语义变更

为了与典型的 PHP 行为保持一致，现在 offsetExists() 方法使用 isset() 而不是 array_key_exists()。这改变了处理 NULL 值时的行为。

$m = Map::from( ['foo' => null] );

// 1.x
isset( $m['foo'] ); // true

// 2.x
isset( $m['foo'] ); // false

重命名 split() 方法

静态 Map::split() 方法已重命名为 Map::explode()，参数顺序已更改。这避免了与 Laravel split() 方法的冲突，并与 PHP explode() 方法保持一致。

// 1.x
Map::split( 'a,b,c', ',' );

// 2.x
Map::explode( ',', 'a,b,c' );

aimeos / map

维护者

详细信息

README

PHP数组和集合变得简单

为什么选择PHP Map

方法

创建

访问

添加

聚合

调试

排序

缩短

测试

转换

其他

方法文档

is_map() 函数

map() 函数

__construct()

__call()

__callStatic()

after()

all()

arsort()

asort()

at()

avg()

before()

bool()

call()

cast()

chunk()

clear()

clone()

col()

collapse()

combine()

compare()

concat()

contains()

copy()

count()

countBy()

dd()

delimiter()

diff()

diffAssoc()

diffKeys()

dump()

duplicates()

each()

empty()

equals()

every()

except()

explode()

filter()

find()

first()

firstKey()

flat()

flip()

float()

from()

fromJson()

get()

getIterator()

grep()

groupBy()

has()

if()

ifAny()

ifEmpty()

implements()

in()

includes()

index()

insertAfter()