Source for file Iterator.class.php

Documentation is available at Iterator.class.php

  1. <?php
  2. /**
  3.  * Gumbo Library Framework
  4.  *
  5.  * LICENSE
  6.  * This library is being released under the terms of the New BSD License.  A
  7.  * copy of the license is packaged with the software (LICENSE.txt).  If no
  8.  * copy is found, a copy of the license template can be found at:
  9.  * http://www.opensource.org/licenses/bsd-license.php
  10.  * 
  11.  * @category Gumbo
  12.  * @package Iterator
  13.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  14.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  15.  * @author Michael Luster <mluster79@yahoo.com>
  16.  * @link http://sourceforge.net/projects/phpgumbo
  17.  * @version 0.0.1
  18.  */
  19.  
  20. /**
  21.  * Iterator Pattern Interface
  22.  * 
  23.  * The Iterator is an OOP method for looping through a list of data.  The
  24.  * pattern consists of an Iterator and an IteratorAggregate (defined in PHP5).
  25.  * An Aggregate is responsible for creating and returning an Iterator to the
  26.  * program.  The following code samples demonstrate the variety of ways to
  27.  * loop through an Iterator.
  28.  *
  29.  * <pre>
  30.  * $it = new Gumbo_Iterator (array (...));
  31.  * $it->rewind ();
  32.  * foreach ($it as $key=>$val) {
  33.  *     ...
  34.  * }
  35.  * </pre>
  36.  * 
  37.  * <pre>
  38.  * $it->rewind ();
  39.  * for ($it;$it->valid ();$it->next ()) {
  40.  *     $key = $it->key ();
  41.  *     $val = $it->current ();
  42.  *     ...
  43.  * }
  44.  * </pre>
  45.  *
  46.  * <pre>
  47.  * $it->rewind ();
  48.  * while ($it->valid ()) {
  49.  *     $key = $it->key ();
  50.  *     $val = $it->current ();
  51.  *     ...
  52.  *     $it->next ();
  53.  * }
  54.  * </pre>
  55.  *
  56.  * An IteratorAggregate is responsible for creating an Iterator.  This
  57.  * is done by defining an implementation to the single IteratorAggregate
  58.  * method.  An aggregate works well inside a foreach() loop, in that it does
  59.  * not require a new variable to hold a reference to the Iterator, it will
  60.  * simply use the Aggregate method to retrieve the Iterator.  The for(..) and
  61.  * while(..) loops require an Iterator variable reference.
  62.  *
  63.  * <pre>
  64.  * class ConcreteAggregate implements IteratorAggregate {
  65.  *     ...
  66.  *     public function getIterator () {
  67.  *         return new Iterator (array (...)); // where array as data
  68.  *     }
  69.  * }
  70.  *
  71.  * // to loop through an aggregate
  72.  * $aggregate = new ConcreteAggregate ();
  73.  * foreach ($aggregate as $key=>$val) {
  74.  *     ...
  75.  * }
  76.  * </pre>
  77.  * 
  78.  * The additional methods were defined for diagnostic purposes.  They don't
  79.  * hold much use for an Iterator object, and may be removed.  They work well
  80.  * if the programmer uses the Iterator directly.
  81.  *
  82.  * @category Gumbo
  83.  * @package Iterator
  84.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  85.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  86.  * @author Michael Luster <mluster79@yahoo.com>
  87.  * @link http://sourceforge.net/projects/phpgumbo
  88.  * @desc Iterator Pattern Interface
  89.  * @version 0.0.1
  90.  */
  91.  
  92. interface Gumbo_Interface_Iterator extends Iterator {
  93.     
  94.     /** ACCESSOR METHODS **/
  95.     /**
  96.      * Returns the array of keys in the object
  97.      * @return array 
  98.      */
  99.     public function getKeys ();
  100.  
  101.     /**
  102.      * Returns the full array list
  103.      * @return array 
  104.      */
  105.     public function getList ();
  106.  
  107.     /**
  108.      * Returns the current element incremental number
  109.      * @return int 
  110.      */
  111.     public function getCurrent ();
  112.  
  113.     /**
  114.      * Returns the total number of elements in the Iterator
  115.      * @return int 
  116.      */
  117.     public function getTotal ();
  118.     
  119. }
  120.  
  121. ?>