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 - 2012 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          * Protected constructor
  33          *
  34          * @param       $className      Name of the class
  35          * @return      void
  36          */
  37         protected function __construct ($className) {
  38                 // Call parent constructor
  39                 parent::__construct($className);
  40         }
  41
  42         /**
  43          * Initializes given stacker
  44          *
  45          * @param       $stackerName    Name of the stack
  46          * @param       $forceReInit    Force re-initialization
  47          * @return      void
  48          * @throws      AlreadyInitializedStackerException      If the stack is already initialized
  49          */
  50         public final function initStacker ($stackerName, $forceReInit = FALSE) {
  51                 // Is the stack already initialized?
  52                 if (($forceReInit === FALSE) && ($this->isStackInitialized($stackerName))) {
  53                         // Then throw the exception
  54                         throw new AlreadyInitializedStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_ALREADY_INITIALIZED);
  55                 } // END - if
  56
  57                 // Initialize the given stack
  58                 $this->pushValueToGenericArrayElement('stacks', $stackerName, 'max_size', $this->getConfigInstance()->getConfigEntry('stacker_' . $stackerName . '_max_size'));
  59         }
  60
  61         /**
  62          * Checks whether the given stack is initialized (set in array $stackers)
  63          *
  64          * @param       $stackerName    Name of the stack
  65          * @return      $isInitialized  Whether the stack is initialized
  66          */
  67         public final function isStackInitialized ($stackerName) {
  68                 // Is is there?
  69                 $isInitialized = ($this->isValidGenericArrayGroup('stacks', $stackerName));
  70
  71                 // Return result
  72                 return $isInitialized;
  73         }
  74
  75         /**
  76          * Checks whether the given stack is full
  77          *
  78          * @param       $stackerName    Name of the stack
  79          * @return      $isFull                 Whether the stack is full
  80          * @throws      NoStackerException      If given stack is missing
  81          */
  82         protected final function isStackFull ($stackerName) {
  83                 // Is the stack not yet initialized?
  84                 if (!$this->isStackInitialized($stackerName)) {
  85                         // Throw an exception
  86                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
  87                 } // END - if
  88
  89                 // So, is the stack full?
  90                 $isFull = (($this->getStackCount($stackerName)) == $this->getConfigInstance()->getConfigEntry('stacker_' . $stackerName . '_max_size'));
  91
  92                 // Return result
  93                 return $isFull;
  94         }
  95
  96         /**
  97          * Checks whether the given stack is empty
  98          *
  99          * @param       $stackerName            Name of the stack
 100          * @return      $isEmpty                        Whether the stack is empty
 101          * @throws      NoStackerException      If given stack is missing
 102          */
 103         public final function isStackEmpty ($stackerName) {
 104                 // Is the stack not yet initialized?
 105                 if (!$this->isStackInitialized($stackerName)) {
 106                         // Throw an exception
 107                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 108                 } // END - if
 109
 110                 // So, is the stack empty?
 111                 $isEmpty = (($this->getStackCount($stackerName)) == 0);
 112
 113                 // Return result
 114                 return $isEmpty;
 115         }
 116
 117         /**
 118          * Getter for size of given stack (array count)
 119          *
 120          * @param       $stackerName    Name of the stack
 121          * @return      $count                  Size of stack (array count)
 122          * @throws      NoStackerException      If given stack is missing
 123          */
 124         public final function getStackCount ($stackerName) {
 125                 // Is the stack not yet initialized?
 126                 if (!$this->isStackInitialized($stackerName)) {
 127                         // Throw an exception
 128                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 129                 } // END - if
 130
 131                 // Now, count the array of entries
 132                 $count = $this->countGenericArrayElements('stacks', $stackerName, 'entries');
 133
 134                 // Return result
 135                 return $count;
 136         }
 137
 138         /**
 139          * Adds a value to given stack
 140          *
 141          * @param       $stackerName    Name of the stack
 142          * @param       $value                  Value to add to this stacker
 143          * @return      void
 144          * @throws      FullStackerException    Thrown if the stack is full
 145          */
 146         protected final function addValue ($stackerName, $value) {
 147                 // Is the stack not yet initialized or full?
 148                 if (!$this->isStackInitialized($stackerName)) {
 149                         // Then do it here
 150                         $this->initStacker($stackerName);
 151                 } elseif ($this->isStackFull($stackerName)) {
 152                         // Stacker is full
 153                         throw new FullStackerException(array($this, $stackerName, $value), self::EXCEPTION_STACKER_IS_FULL);
 154                 }
 155
 156                 // Now add the value to the stack
 157                 $this->pushValueToGenericArrayElement('stacks', $stackerName, 'entries', $value);
 158         }
 159
 160         /**
 161          * Get last value from named stacker
 162          *
 163          * @param       $stackerName    Name of the stack
 164          * @return      $value                  Value of last added value
 165          * @throws      NoStackerException      If the named stacker was not found
 166          * @throws      EmptyStackerException   If the named stacker is empty
 167          */
 168         protected final function getLastValue ($stackerName) {
 169                 // Is the stack not yet initialized or full?
 170                 if (!$this->isStackInitialized($stackerName)) {
 171                         // Throw an exception
 172                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 173                 } elseif ($this->isStackEmpty($stackerName)) {
 174                         //Throw an exception
 175                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
 176                 }
 177
 178                 // Now get the last value
 179                 $value = $this->getGenericArrayKey('stacks', $stackerName, 'entries', $this->getStackCount($stackerName) - 1);
 180
 181                 // Return it
 182                 return $value;
 183         }
 184
 185         /**
 186          * Get first value from named stacker
 187          *
 188          * @param       $stackerName    Name of the stack
 189          * @return      $value                  Value of last added value
 190          * @throws      NoStackerException      If the named stacker was not found
 191          * @throws      EmptyStackerException   If the named stacker is empty
 192          */
 193         protected final function getFirstValue ($stackerName) {
 194                 // Is the stack not yet initialized or full?
 195                 if (!$this->isStackInitialized($stackerName)) {
 196                         // Throw an exception
 197                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 198                 } elseif ($this->isStackEmpty($stackerName)) {
 199                         //Throw an exception
 200                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
 201                 }
 202
 203                 // Now get the first value
 204                 $value = $this->getGenericArrayKey('stacks', $stackerName, 'entries', 0);
 205
 206                 // Return it
 207                 return $value;
 208         }
 209
 210         /**
 211          * "Pops" last entry from stack
 212          *
 213          * @param       $stackerName    Name of the stack
 214          * @return      void
 215          * @throws      NoStackerException      If the named stacker was not found
 216          * @throws      EmptyStackerException   If the named stacker is empty
 217          */
 218         protected final function popLast ($stackerName) {
 219                 // Is the stack not yet initialized or full?
 220                 if (!$this->isStackInitialized($stackerName)) {
 221                         // Throw an exception
 222                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 223                 } elseif ($this->isStackEmpty($stackerName)) {
 224                         //Throw an exception
 225                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
 226                 }
 227
 228                 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
 229                 $this->popGenericArrayElement('stacks', $stackerName, 'entries');
 230         }
 231
 232         /**
 233          * "Pops" first entry from stack
 234          *
 235          * @param       $stackerName    Name of the stack
 236          * @return      void
 237          * @throws      NoStackerException      If the named stacker was not found
 238          * @throws      EmptyStackerException   If the named stacker is empty
 239          */
 240         protected final function popFirst ($stackerName) {
 241                 // Is the stack not yet initialized or full?
 242                 if (!$this->isStackInitialized($stackerName)) {
 243                         // Throw an exception
 244                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 245                 } elseif ($this->isStackEmpty($stackerName)) {
 246                         //Throw an exception
 247                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
 248                 }
 249
 250                 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
 251                 $this->shiftGenericArrayElement('stacks', $stackerName, 'entries');
 252         }
 253 }
 254
 255 // [EOF]
 256 ?>