OrderedList

An OrderedList is a basic stack container to store sequences and append, insert and remove items. It implements Countable, IteratorAggregate and ArrayAccess so you can use it like a normal array. As all of collection classes you will get an exception if a key does not exist, a value could not be found etc. This allows the OrderedList to support fluid syntax (like $list->append(2)->remove(5)) an all manipulating method calls.

Add items

The basic syntax to add items is:

use Collection\OrderedList;

$list = new OrderedList;
$list->append(2);
$list->append(3);
$list->push(4); // Does the same as append for more php-ish syntax

// Result: OrderedList[2,3,4]

You can also pass an array to the constructor or set it via setSrc() to fill the OrderedList. The indexes of your array will be lost.

use Collection\OrderedList;

$list = new OrderedList([2,3,4]);

// Result: OrderedList[2,3,4]

Add many items

If you like to add more values to your OrderedList use extend($other).

use Collection\OrderedList;

$list = new OrderedList([2,3,4]);
// Result: OrderedList[2,3,4]

$list2 = new OrderedList([5,4,3]);
// Result: OrderedList[5,4,3]

$list->extend($list2); // extends $list by all values of $list2
// $list is now OrderedList[2,3,4,5,4,3]

Add items at a certain position

To insert values use the insert($index, $item) method. The new item will be inserted at the position you specified by $index and the previous item of this position will be moved one index up and all following items too. If you pass an index to index that does not exist, an OutOfRangeException will be thrown.

use Collection\OrderedList;

$list = new OrderedList([2,3,4]);
// Result: OrderedList[2,3,4]
$list->insert(1,5);
// Result: OrderedList[2,5,3,4]

Removing items

Removing values is done by remove(value). Internally OrderedList uses indexOf($value) to get the index of an value. So remove($value) is the same as $list->pop($list->indexOf($value)). The items a compared by absolute equality (===). If indexOf($value) does not find the value an exception is thrown.

use Collection\OrderedList;

$list = new OrderedList([2,3,4]);
// Result: OrderedList[2,3,4]
$list->remove(3);
// Result: OrderedList[2,4]

Removing values by index.

Removing the item at position $index is done by pop($index=null). It is important to know that this will (unless you remove the last item) not remove this index. It will remove the value at index $index and all items past that index will slip down one index. If you omit the index param the last item will be removed.

use Collection\OrderedList;

$list = new OrderedList([2,3,4]);
// Result: OrderedList[2,3,4]
$list->pop(0);
// Result: OrderedList[3,4]
$list->pop();
// Result: OrderedList[3]

Find the index of an value

If you like to find the index of value $x use indexOf($value). If the value is not found a Exception will be thrown.

use Collection\OrderedList;

$list = new OrderedList([2,3,4]);
// Result: OrderedList[2,3,4]
$list->indexOf(4)
// Return value: 2
$list->indexOf(5)
// Throws Exception

Check if an value exists

To check if a value exists choose contains($value). Returns true or false.

Counting

OrderedList has a nifty count method. It implements the Countable interface so to count it, just use count($list) or $list->count(). But the nifty part is that this method allows you to pass an value and retrieve how often this value is assigned in the OrderedList. To directly use this functionality use countValue($value)

use Collection\OrderedList;

$list = new OrderedList([1,2,3,4,1,5,7]);
// Result: OrderedList[1,2,3,4,1,5,7]
$list->count()
// Return value: 7
$list->count(1)
// Returns value: 2
$list->count(5)
// Returns value: 1
$list->count(8)
// Returns value: 0

Sorting and reversing

Its very easy to sort and reverse a OrderedList. Just use sort() or reverse().

First and last Item

To retrieve the first or last item just use first() or last()

Basic usage and syntax considerations

Like all collection classes the manipulating methods will alter the current object and return itself. This allows things like that:

use Collection\OrderedList;

$list = new OrderedList([1,2,3,4,1,5,7]);

$list->pop()->remove(1)->append(32);
// Result: OrderedList[2,3,4,5,32]

If you like to return a new OrderedList just use clone $list or for fluid syntax $list->copy().

use Collection\OrderedList;

$list = new OrderedList([1,2,3,4,1,5,7]);

$list2 = $list->copy()->pop()->remove(1)->append(32);
// $list: OrderedList[1,2,3,4,1,5,7] (unaltered)
// $list2: OrderedList[2,3,4,5,32]