README

封装 PHP 数组并维护次级查找映射，以快速通过嵌套字段值检索项目。

这与数据库中次级键的概念类似。

特性

实现了 ArrayAccess、Iterator 和 Countable 接口，因此可以像使用标准 PHP 数组一样使用它

$a[] = ['foo' => 'bar'];
$value = $a[0];
unset($a[0]);
count($a);
foreach ($a as $key => $value);

完全用 PHP 实现。次级索引作为 PHP 关联数组实现，是具有 O(1) 平均查找时间的哈希表。

由于次级索引是哈希索引，其键默认是唯一的。虽然集合中的多个文档可能具有相同的次级键值，但在这种情况下，次级键将被覆盖，并指向最后添加/修改的文档。

API 参考

"document" 是与主键相关联的值。它可以有任何类型。如果文档是数组，可以使用 "点" 表示法指定次级索引。

当添加/删除/更新值时，所有创建的次级键索引都会自动更新。

构造函数

ArrayWithSecondaryKeys(array $array = [])

创建一个新的 ArrayWithSecondaryKeys 集合，从给定的数组初始化。如果没有传递参数，则创建一个空集合。

containsPrimaryKey

containsPrimaryKey($key): bool

检查指定的主键是否存在于集合中。

containsSecondaryKey

containsSecondaryKey($index, $key): bool

检查指定的次级键是否存在于指定的索引中。

count

count(): int

返回集合中的文档数量。

get

get($key, $default = null): mixed

通过键检索文档。

如果键是 "点" 表示法，则返回文档的相应嵌套部分。如果键不是包含点的字符串，则将其视为主键。

has

has($key): bool

使用 "点" 表示法检查集合中是否存在项目或项目。

isEmpty

isEmpty(): bool

如果集合中没有主键，则返回 true，否则返回 false。

put

put($key, $document): ArrayWithSecondaryKeys

在给定的键下向集合添加新的文档。

如果键是 "点" 表示法，并且顶层主键存在，则向现有文档添加嵌套部分。

如果键不是包含点的字符串，则将其视为主键。

add

add($key, $document): ArrayWithSecondaryKeys

put 的别名。

remove

remove($key): ArrayWithSecondaryKeys

删除与给定主键关联的文档，或者如果键是 "点" 表示法，则删除文档的嵌套部分。

如果键是 "点" 表示法，则删除文档的相应嵌套部分。如果键不是包含点的字符串，则将其视为主键。

updateSecondaryKey

updateSecondaryKey($index, $existingValue, $newValue)

通过现有次级键值查找文档，并更新文档中现有次级键值到新值。

返回更新文档的主键，如果找不到具有现有值的文档，则返回 null。

append

append($document): ArrayWithSecondaryKeys

使用 []= 追加文档。

createIndex

createIndex($index)

创建一个新的索引并索引现有文档。索引作为 "点" 表示法的字符串提供（例如 state.pid）。

getPrimaryKeyByIndex

getPrimaryKeyByIndex($index, $secondaryKey): mixed

通过次级键检索主键。索引作为 "点" 表示法的字符串提供（例如 state.pid）。

如果集合中没有文档匹配给定的次级键，则返回 null。

如果给定的索引不存在，则抛出 VladimirVrzic\ArrayWithSecondaryKeys\NoSuchIndexException。

getByIndex

getByIndex($index, $secondaryKey, $default = null): mixed

通过索引（次级键）检索文档。索引作为 "点" 表示法的字符串提供（例如 state.pid）。

如果给定的索引不存在，则抛出 VladimirVrzic\ArrayWithSecondaryKeys\NoSuchIndexException。

updateByIndex

updateByIndex($index, $secondaryKey, $document)

通过索引（次级键）更新文档。索引以“点”表示法给出作为字符串（例如 state.pid）。

如果给定的索引不存在，则抛出 VladimirVrzic\ArrayWithSecondaryKeys\NoSuchIndexException。

如果找到与给定次级键关联的现有文档并替换它，则返回 true。如果未找到与给定次级键关联的文档，则返回 false。

removeByIndex

removeByIndex($index, $secondaryKey)

通过索引（次级键）删除文档。索引以字符串形式给出，使用“点”表示法（例如 state.pid）。

如果给定的索引不存在，则抛出 VladimirVrzic\ArrayWithSecondaryKeys\NoSuchIndexException。

如果找到与给定次级键关联的文档并删除它，则返回 true。如果未找到与给定次级键关联的文档，则返回 false。

putIfAbsent

putIfAbsent($key, $document): mixed

如果键不存在，则添加与给定文档关联的新键并返回 null。

如果键存在，则返回当前文档。

asArray

asArray(): array

返回数组的副本，作为普通PHP数组（不带次级索引）。

primaryKeys

primaryKeys(): array

返回所有主键的数组。

secondaryKeys

secondaryKeys($index): array

返回与给定索引关联的所有次级键的数组。

安装

假设您已安装PHP Composer，并且 composer 可执行文件在您的 $PATH 中。

composer require cardinal-collections/array-with-secondary-keys

命名建议

• <[关联]数组 | 地图 | 字典>，带有次级键

• 多索引 <[关联]数组 | 地图 | 字典>