inc/classes/main/stacker/class_BaseStacker.php

   1 <?php
   2 /**
   3  * A general Stacker
   4  *
   5  * @author              Roland Haeder <webmaster@ship-simu.org>
   6  * @version             0.0.0
   7  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2011 Core Developer Team
   8  * @license             GNU GPL 3.0 or any newer version
   9  * @link                http://www.ship-simu.org
  10  *
  11  * This program is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU General Public License as published by
  13  * the Free Software Foundation, either version 3 of the License, or
  14  * (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License
  22  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  23  */
  24 class BaseStacker extends BaseFrameworkSystem {
  25         // Exception codes
  26         const EXCEPTION_STACKER_ALREADY_INITIALIZED = 0x050;
  27         const EXCEPTION_STACKER_IS_FULL             = 0x051;
  28         const EXCEPTION_NO_STACKER_FOUND            = 0x052;
  29         const EXCEPTION_STACKER_IS_EMPTY            = 0x053;
  30
  31         /**
  32          * An array holding all stacks
  33          */
  34         private $stacks = array();
  35
  36         /**
  37          * Protected constructor
  38          *
  39          * @param       $className      Name of the class
  40          * @return      void
  41          */
  42         protected function __construct ($className) {
  43                 // Call parent constructor
  44                 parent::__construct($className);
  45         }
  46
  47         /**
  48          * Initializes given stacker
  49          *
  50          * @param       $stackerName    Name of the stack
  51          * @param       $forceReInit    Force re-initialization
  52          * @return      void
  53          * @throws      AlreadyInitializedStackerException      If the stack is already initialized
  54          */
  55         public final function initStacker ($stackerName, $forceReInit = false) {
  56                 // Is the stack already initialized?
  57                 if (($forceReInit === false) && ($this->isStackInitialized($stackerName))) {
  58                         // Then throw the exception
  59                         throw new AlreadyInitializedStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_ALREADY_INITIALIZED);
  60                 } // END - if
  61
  62                 // Initialize the given stack
  63                 $this->stacks[$stackerName] = array(
  64                         'max_size' => $this->getConfigInstance()->getConfigEntry('stacker_' . $stackerName . '_max_size'),
  65                         'entries'  => array()
  66                 );
  67         }
  68
  69         /**
  70          * Checks wether the given stack is initialized (set in array $stackers)
  71          *
  72          * @param       $stackerName    Name of the stack
  73          * @return      $isInitialized  Wether the stack is initialized
  74          */
  75         public final function isStackInitialized ($stackerName) {
  76                 // Is is there?
  77                 $isInitialized = ((isset($this->stacks[$stackerName])) && (is_array($this->stacks[$stackerName])));
  78
  79                 // Return result
  80                 return $isInitialized;
  81         }
  82
  83         /**
  84          * Checks wether the given stack is full
  85          *
  86          * @param       $stackerName    Name of the stack
  87          * @return      $isFull                 Wether the stack is full
  88          * @throws      NoStackerException      If given stack is missing
  89          */
  90         protected final function isStackFull ($stackerName) {
  91                 // Is the stack not yet initialized?
  92                 if (!$this->isStackInitialized($stackerName)) {
  93                         // Throw an exception
  94                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
  95                 } // END - if
  96
  97                 // So, is the stack full?
  98                 $isFull = (($this->getStackCount($stackerName)) == $this->getConfigInstance()->getConfigEntry('stacker_' . $stackerName . '_max_size'));
  99
 100                 // Return result
 101                 return $isFull;
 102         }
 103
 104         /**
 105          * Checks wether the given stack is empty
 106          *
 107          * @param       $stackerName            Name of the stack
 108          * @return      $isEmpty                        Wether the stack is empty
 109          * @throws      NoStackerException      If given stack is missing
 110          */
 111         public final function isStackEmpty ($stackerName) {
 112                 // Is the stack not yet initialized?
 113                 if (!$this->isStackInitialized($stackerName)) {
 114                         // Throw an exception
 115                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 116                 } // END - if
 117
 118                 // So, is the stack empty?
 119                 $isEmpty = (($this->getStackCount($stackerName)) == 0);
 120
 121                 // Return result
 122                 return $isEmpty;
 123         }
 124
 125         /**
 126          * Getter for size of given stack (array count)
 127          *
 128          * @param       $stackerName    Name of the stack
 129          * @return      $count                  Size of stack (array count)
 130          * @throws      NoStackerException      If given stack is missing
 131          */
 132         public final function getStackCount ($stackerName) {
 133                 // Is the stack not yet initialized?
 134                 if (!$this->isStackInitialized($stackerName)) {
 135                         // Throw an exception
 136                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 137                 } // END - if
 138
 139                 // Now, count the array of entries
 140                 $count = count($this->stacks[$stackerName]['entries']);
 141
 142                 // Return result
 143                 return $count;
 144         }
 145
 146         /**
 147          * Adds a value to given stack
 148          *
 149          * @param       $stackerName    Name of the stack
 150          * @param       $value                  Value to add to this stacker
 151          * @return      void
 152          * @throws      FullStackerException    Thrown if the stack is full
 153          */
 154         protected final function addValue ($stackerName, $value) {
 155                 // Is the stack not yet initialized or full?
 156                 if (!$this->isStackInitialized($stackerName)) {
 157                         // Then do it here
 158                         $this->initStacker($stackerName);
 159                 } elseif ($this->isStackFull($stackerName)) {
 160                         // Stacker is full
 161                         throw new FullStackerException(array($this, $stackerName, $value), self::EXCEPTION_STACKER_IS_FULL);
 162                 }
 163
 164                 // Now add the value to the stack
 165                 array_push($this->stacks[$stackerName]['entries'], $value);
 166         }
 167
 168         /**
 169          * Get last value from named stacker
 170          *
 171          * @param       $stackerName    Name of the stack
 172          * @return      $value                  Value of last added value
 173          * @throws      NoStackerException      If the named stacker was not found
 174          * @throws      EmptyStackerException   If the named stacker is empty
 175          */
 176         protected final function getLastValue ($stackerName) {
 177                 // Is the stack not yet initialized or full?
 178                 if (!$this->isStackInitialized($stackerName)) {
 179                         // Throw an exception
 180                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 181                 } elseif ($this->isStackEmpty($stackerName)) {
 182                         //Throw an exception
 183                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
 184                 }
 185
 186                 // Now get the last value
 187                 $value = $this->stacks[$stackerName]['entries'][$this->getStackCount($stackerName) - 1];
 188
 189                 // Return it
 190                 return $value;
 191         }
 192
 193         /**
 194          * Get first value from named stacker
 195          *
 196          * @param       $stackerName    Name of the stack
 197          * @return      $value                  Value of last added value
 198          * @throws      NoStackerException      If the named stacker was not found
 199          * @throws      EmptyStackerException   If the named stacker is empty
 200          */
 201         protected final function getFirstValue ($stackerName) {
 202                 // Is the stack not yet initialized or full?
 203                 if (!$this->isStackInitialized($stackerName)) {
 204                         // Throw an exception
 205                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 206                 } elseif ($this->isStackEmpty($stackerName)) {
 207                         //Throw an exception
 208                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
 209                 }
 210
 211                 // Now get the last value
 212                 $value = $this->stacks[$stackerName]['entries'][0];
 213
 214                 // Return it
 215                 return $value;
 216         }
 217
 218         /**
 219          * "Pops" last entry from stack
 220          *
 221          * @param       $stackerName    Name of the stack
 222          * @return      void
 223          * @throws      NoStackerException      If the named stacker was not found
 224          * @throws      EmptyStackerException   If the named stacker is empty
 225          */
 226         protected final function popLast ($stackerName) {
 227                 // Is the stack not yet initialized or full?
 228                 if (!$this->isStackInitialized($stackerName)) {
 229                         // Throw an exception
 230                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 231                 } elseif ($this->isStackEmpty($stackerName)) {
 232                         //Throw an exception
 233                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
 234                 }
 235
 236                 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
 237                 array_pop($this->stacks[$stackerName]['entries']);
 238         }
 239
 240         /**
 241          * "Pops" first entry from stack
 242          *
 243          * @param       $stackerName    Name of the stack
 244          * @return      void
 245          * @throws      NoStackerException      If the named stacker was not found
 246          * @throws      EmptyStackerException   If the named stacker is empty
 247          */
 248         protected final function popFirst ($stackerName) {
 249                 // Is the stack not yet initialized or full?
 250                 if (!$this->isStackInitialized($stackerName)) {
 251                         // Throw an exception
 252                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 253                 } elseif ($this->isStackEmpty($stackerName)) {
 254                         //Throw an exception
 255                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
 256                 }
 257
 258                 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
 259                 array_shift($this->stacks[$stackerName]['entries']);
 260         }
 261 }
 262
 263 // [EOF]
 264 ?>