PHPTAL-NP-0.7.0/libs/Types/Iterator.php

   1 <?php
   2 /* vim: set expandtab tabstop=4 shiftwidth=4: */
   3 //
   4 //  Copyright (c) 2003 Laurent Bedubourg
   5 //
   6 //  This library is free software; you can redistribute it and/or
   7 //  modify it under the terms of the GNU Lesser General Public
   8 //  License as published by the Free Software Foundation; either
   9 //  version 2.1 of the License, or (at your option) any later version.
  10 //
  11 //  This library is distributed in the hope that it will be useful,
  12 //  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 //  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 //  Lesser General Public License for more details.
  15 //
  16 //  You should have received a copy of the GNU Lesser General Public
  17 //  License along with this library; if not, write to the Free Software
  18 //  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  19 //
  20 //  Authors: Laurent Bedubourg <laurent.bedubourg@free.fr>
  21 //
  22
  23 /**
  24  * Iterable interface.
  25  *
  26  * An iterable object can produce Iterator(s) related to itself.
  27  *
  28  * @author Laurent Bedubourg <laurent.bedubourg@free.fr>
  29  */
  30 class Iterable
  31 {
  32     /**
  33      * Retrieve iterable size.
  34      */
  35     function size(){}
  36
  37     /**
  38      * Get an initialized iterator for this object.
  39      */
  40     function &getNewIterator(){}
  41 }
  42
  43
  44 /**
  45  * Iterator interface.
  46  *
  47  * This class provides common methods for Iterator objects.
  48  *
  49  * An iterator is a 'pointer' to a data item extracted from some collection of
  50  * resources.
  51  *
  52  * The aim of Iterator is to allow some abstraction between your program
  53  * resources and the way you fetch these resources.
  54  *
  55  * Thus, you can loop over a file content and later replace this file with a
  56  * database backend whithout changing the program logic.
  57  *
  58  * @author Laurent Bedubourg <laurent.bedubourg@free.fr>
  59  */
  60 class Iterator
  61 {
  62     /**
  63      * Reset iterator to first item.
  64      *
  65      * This method should throw an exception for once only iterators.
  66      *
  67      * @throws ResetFailed
  68      */
  69     function reset()
  70     {
  71         return PEAR::raiseError('\'reset\' method not implemented');
  72     }
  73
  74     /**
  75      * Test if current item is not the end of iterator.
  76      *
  77      * @return boolean
  78      */
  79     function isValid()
  80     {
  81         return PEAR::raiseError('\'isValid\' method not implemented');
  82     }
  83
  84     /**
  85      * Iterate on the next element and returns the next item.
  86      *
  87      * @return mixed (by reference)
  88      */
  89     function &next()
  90     {
  91         return PEAR::raiseError('\'next\' method not implemented');
  92     }
  93
  94     // ----------------------------------------------------------------------
  95     // getters
  96     // ----------------------------------------------------------------------
  97
  98     /**
  99      * Retrieve the current item index.
 100      *
 101      * @return int
 102      */
 103     function index()
 104     {
 105         return PEAR::raiseError('\'index\' method not implemented');
 106     }
 107
 108     /**
 109      * Retrieve current item value.
 110      *
 111      * @return mixed (by reference)
 112      */
 113     function &value()
 114     {
 115         return PEAR::raiseError('\'value\' method not implemented');
 116     }
 117
 118     // ----------------------------------------------------------------------
 119     // optional methods
 120     // ----------------------------------------------------------------------
 121
 122     /**
 123      * (optional) Additional index for hashes.
 124      *
 125      * @return string
 126      */
 127     function key()
 128     {
 129         return $this->index();
 130     }
 131
 132     /**
 133      * (optional) Remove the current value from container.
 134      *
 135      * Implement this method only when the iterator can do a secured remove
 136      * without breaking other iterators works.
 137      */
 138     function remove()
 139     {
 140         return PEAR::raiseError('\'remove\' method not implemented');
 141     }
 142 }
 143
 144 /**
 145  * Exception thrown by iterators that can be reseted only once.
 146  *
 147  * @author Laurent Bedubourg <laurent.bedubourg@free.fr>
 148  */
 149 class ResetFailed extends PEAR_Error
 150 {
 151 }
 152
 153 ?>