Gumbo PHP Library API Documentation

Iterator Pattern Interface

The Iterator is an OOP method for looping through a list of data. The pattern consists of an Iterator and an IteratorAggregate (defined in PHP5). An Aggregate is responsible for creating and returning an Iterator to the program. The following code samples demonstrate the variety of ways to loop through an Iterator.

 $it = new Gumbo_Iterator (array (...));
 $it->rewind ();
 foreach ($it as $key=>$val) {
 	...
 }

 $it->rewind ();
 for ($it;$it->valid ();$it->next ()) {
 	$key = $it->key ();
 	$val = $it->current ();
 	...
 }

 $it->rewind ();
 while ($it->valid ()) {
 	$key = $it->key ();
 	$val = $it->current ();
 	...
 	$it->next ();
 }

An IteratorAggregate is responsible for creating an Iterator. This is done by defining an implementation to the single IteratorAggregate method. An aggregate works well inside a foreach() loop, in that it does not require a new variable to hold a reference to the Iterator, it will simply use the Aggregate method to retrieve the Iterator. The for(..) and while(..) loops require an Iterator variable reference.

 class ConcreteAggregate implements IteratorAggregate {
 	...
 	public function getIterator () {
 		return new Iterator (array (...)); // where array as data
 	}
 }

 // to loop through an aggregate
 $aggregate = new ConcreteAggregate ();
 foreach ($aggregate as $key=>$val) {
 	...
 }

The additional methods were defined for diagnostic purposes. They don't hold much use for an Iterator object, and may be removed. They work well if the programmer uses the Iterator directly.