README

PHP 核心或 SPL 集合所缺少的功能。

这个库试图将尽可能多的 Java 集合框架功能添加到 PHP 世界。

序列

一个有序集合（也称为列表）。

使用此接口的用户可以精确控制每个元素在列表中的位置。用户可以通过其整数索引（列表中的位置）访问元素，并在列表中搜索元素。

用法

您可以计算集合中的元素数量

$count = $sequence->count();

您可以从集合中移除所有元素

$sequence->clear();

您可以检查集合是否包含任何元素

$sequence->isEmpty();

您可以将一个元素添加到序列的末尾

$added = $sequence->add($element);
if ($added) {
    echo 'element is added';
} else {
    echo 'element is not added to sequence';
}

或元素集合（添加的元素将附加到序列的末尾）

$elements = [
    $element1,
    $element2,
    $element3,
];
$sequence->addAll($elements);

您可以在特定索引处添加元素，这将移动当前位于该位置的元素（如果有的话）以及任何后续元素到右边（增加它们的索引）

$sequence->addAtIndex($index, $element);

您甚至可以在指定索引处添加元素集合。这将移动当前位于该位置的元素（如果有的话）以及任何后续元素到右边（增加它们的索引）

$sequence->addAllAtIndex($index, $elements);

您可以移除一个元素（仅第一次出现）

$changed = $sequence->remove($element);
if ($changed) {
    echo 'element removed';
} else {
    echo 'element not found in sequence';
}

或移除元素的任何出现

$changed = $sequence->removeAll([$element]);
if ($changed) {
    echo 'element is removed from sequence';
} else {
    echo 'element is not found in sequence';
}

或甚至移除元素集合的任何出现

$changed = $sequence->removeAll([
    $element1,
    $element2
]);
if ($changed) {
    echo 'at least one from given elements is removed from sequence';
} else {
    echo 'none of given elements are not found in sequence';
}

您可以在指定索引处替换元素

$oldElement = $sequence->set(1, $element);

您可以从序列中移除所有元素

$sequence->clear();

如果您需要，可以根据指定的比较器排序此序列

$sequence->sort(Comparator $comparator);

您可以通过获取子序列来操作序列的一部分

$subSequence = $sequence->subSequence($fromIndex, $toIndex);

但请记住，子序列仍然是主序列的一部分，因此对子序列的更改也会影响序列

$subSequence = $sequence->subSequence($fromIndex, $toIndex);
$subSequence->remove($element);

$found = $sequence->contains($element); 
//$found will be false as we remove $element from $sequence by removing it from $subSequence

提供的序列实现

您可以使用序列用于任何类型的元素，但如果您需要特定类型的元素序列，您可以使用特定类型的序列。

MixedSequence

此类序列接受所有类型的元素，除了 null 元素。

$mySequence = new MixedSequence();

ScalarsSequence

此类序列仅接受标量元素。不允许 null 元素。

$mySequence = new ScalarsSequence();

IntegersSequence

此类序列仅接受整数元素。不允许 null 元素。

$mySequence = new IntegersSequence();

StringsSequence

此类序列仅接受字符串元素。不允许 null 元素。

$mySequence = new StringsSequence();

ObjectsSequence

此类序列仅接受指定类实例的元素。不允许 null 元素。

$mySequence = new ObjectsSequence(SequenceElement::class);

集合

唯一元素的集合。

用法

您可以计算集合中的元素数量

$count = $set->count();

您可以从集合中移除所有元素

$set->clear();

您可以检查集合是否包含任何元素

$set->isEmpty();

添加元素将返回布尔值：true - 如果元素已添加，false 如果元素无法添加（集合中已存在相同元素）。

$added = $set->add($element);
if ($added) {
    echo 'element is added';
} else {
    echo 'element exist in set and cannot be added';
}

您可以添加多个元素

$modified = $set->addAll([$element1, $element2]);
if ($modified) {
    echo 'some of given elements are added to set';
} else {
    echo 'non of given elements are added to set';
}

您可以检查集合是否包含元素

$contains = $set->contains($element);
if ($contains) {
    echo 'set contains specified element';
} else {
    echo 'set do not contains specified element';
}

或检查集合是否包含所有给定元素

$contains = $set->contains([$element1, $element2, element3]);
if ($contains) {
    echo 'set contains element1 and element2 and element3';
} else {
    echo 'set do not contains some of given elements or even any element from given collection';
}

您可以从集合中移除元素

$removed = $set->remove($element);
if ($removed) {
    echo "given element removed from set";
} else {
    echo "set do not contains given element";
}

或移除元素集合

$changed = $set->removeAll([$element1, $element2]);
if ($changed) {
    echo "Some or all elements from given collection are removed from set";
} else {
    echo "None element from given collection was found in set";
}

或甚至移除所有不在给定集合中的元素

$changed = $set->retainAll([$element1, $element2]);
if ($changed) {
    echo "All elements that are not present in given collection are removed from set";
} else {
    echo "None element id removed from set, so this set and given collection has same elements";
}

您可以检查两个集合是否相等

if ($set1->equals($set2) {
    echo 'given sets are equal'
} else {
    echo 'given sets are not equal'
}

如果您需要将集合作为数组操作，则可以将其转换

$array = $set->toArray();

提供的集合实现

IntegersSet

此类集合仅接受整数元素。不允许 null 元素。

$mySet = new IntegersSet();

FloatsSet

此类集合只接受浮点元素。不允许空元素。

$mySet = new FloatsSet();

StringsSet

此类集合只接受字符串元素。不允许空元素。

$mySet = new StringsSet();

ObjectsSet

此类集合只接受指定类的实例元素。不允许空元素。

$mySet = new ObjectsSet(SetElement::class);

SortedSet

提供其元素上的总排序的集合。

用法

SortedSet 包含 Set 提供的所有功能，并添加了几个我们的功能。所有元素都按照所需的比较器实现进行排序（字符串、整数和浮点数的实现包含默认比较器，这些比较器按照自然顺序排序元素）。

添加的功能包括

获取第一个和最后一个元素
获取集合视图（子集）

获取第一个和最后一个元素

$first = $mySortedSet->first();
$last = $mySortedSet->last();

创建子集（集合视图）

创建子集有 3 种方法

$head = $mySortedSet->headSet($toElement); // where $toElement is exclusive
$tail = $mySortedSet->tailSet($fromElement); //where $fromElement is inclusive
$subSet = $mySortedSet->subSet($fromElement, $toElement); // same rules as above

但请记住，子集仍然是主集合的一部分，因此对子集所做的更改将影响父集，反之亦然。

因此您可以

$subset = $mySet->subSet($fromElement, $toElement);
$subset->clear();

然后从 $fromElement 到 $toElement（不包括）的所有元素都从 $subset 和 $mySet 中移除，这意味着 $subset 现在是空的集合。

为了更清楚

$mySet->addAll([
    $elem01,
    $elem03,
    $elem10,
]);
$subset = $mySet->subset($elem01,$elem10);
// $subset contains now $elem01, $elem03

$subset->add($elem02);
//subset contains now $elem01, $elem02, $elem03
//$mySet contains now $elem01, $elem02, $elem03, $elem10

$mySet->add($elem07);
//subset contains now $elem01, $elem02, $elem03, $elem07
//$mySet contains now $elem01, $elem02, $elem03, $elem07, $elem10

$mySet->add($elem11);
//subset contains now $elem01, $elem02, $elem03, $elem07
//$mySet contains now $elem01, $elem02, $elem03, $elem07, $elem10, $elem11

如果您需要静态子集，只需这样做（假设您想要字符串集合）

$mySet = new StringsSortedSet();
//...
$subset = $mySet->subset($elem01,$elem10);
$myStaticSubSet = new StringsSortedSet($subset);

SortedSet 的实现提供

IntegersSortedSet