3.2. Collections

All Xyster_Collection_Interface-based objects are traversable – they can be iterated through.

<?php
// if $stuff implements Xyster_Collection_Interface
foreach( $stuff as $k=>$v ) {
        printf( 'key: %s, value: %s', $k, $v );
}

Here are some other useful methods on Xyster_Collection_Interface:

<?php
// if $stuff implements Xyster_Collection_Interface
echo count($stuff);
if ( $stuff->isEmpty() ) {
        echo 'Empty collection';
}
if ( $stuff->contains('some value') ) {
        echo 'Yes, it's in there\n';
}
if ( $stuff->containsAll( array('value1', 'value2', 'value3') ) ) {
        echo 'They're all there';
}

This collection can be added to, changed, or have items removed.

<?php
// if $items is an Xyster_Collection_Interface
// let's say $items contains the values 'earth', 'mars', and 'jupiter'

$innerPlanets = Xyster_Collection::using(array('mercury', 'venus', 'earth', 'mars'));

$items->merge($innerPlanets); // $items now contains 'mercury', 'venus', 'earth', 'mars', 'jupiter'

$items->remove('mars'); // $items now contains 'mercury', 'venus', 'earth', 'jupiter'
$items->remove('saturn'); // throws an exception – 'saturn' isn't in the collection

$items->removeAll(Xyster_Collection::using(array('mercury', 'venus'))); // $items now contains 'earth', 'jupiter'
// the items supplied to removeAll must all be in the collection

$items->retainAll(Xyster_Collection::using(array('earth'))); // $items now contains 'earth'
// the items supplied to retainAll must all be in the collection

$items->clear(); // $items now contains nothing