inc/main/classes/stacker/class_BaseStacker.php

   1 <?php
   2 /**
   3  * A general Stacker
   4  *
   5  * @author              Roland Haeder <webmaster@shipsimu.org>
   6  * @version             0.0.0
   7  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2015 Core Developer Team
   8  * @license             GNU GPL 3.0 or any newer version
   9  * @link                http://www.shipsimu.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 function initStack ($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, $forceReInit), self::EXCEPTION_STACKER_ALREADY_INITIALIZED);
  55                 } // END - if
  56
  57                 // Initialize the given stack
  58                 $this->initGenericArrayKey('stacks', $stackerName, 'entries', $forceReInit);
  59         }
  60
  61         /**
  62          * Initializes all stacks
  63          *
  64          * @return      void
  65          */
  66         public function initStacks (array $stacks, $forceReInit = FALSE) {
  67                 // "Walk" through all (more will be added as needed
  68                 foreach ($stacks as $stackerName) {
  69                         // Init this stack
  70                         $this->initStack($stackerName, $forceReInit);
  71                 } // END - foreach
  72         }
  73
  74         /**
  75          * Checks whether the given stack is initialized (set in array $stackers)
  76          *
  77          * @param       $stackerName    Name of the stack
  78          * @return      $isInitialized  Whether the stack is initialized
  79          */
  80         public function isStackInitialized ($stackerName) {
  81                 // Is is there?
  82                 $isInitialized = ($this->isValidGenericArrayKey('stacks', $stackerName, 'entries'));
  83
  84                 // Return result
  85                 return $isInitialized;
  86         }
  87
  88         /**
  89          * Checks whether the given stack is full
  90          *
  91          * @param       $stackerName    Name of the stack
  92          * @return      $isFull                 Whether the stack is full
  93          * @throws      NoStackerException      If given stack is missing
  94          */
  95         protected function isStackFull ($stackerName) {
  96                 // Is the stack not yet initialized?
  97                 if (!$this->isStackInitialized($stackerName)) {
  98                         // Throw an exception
  99                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 100                 } // END - if
 101
 102                 // So, is the stack full?
 103                 $isFull = (($this->getStackCount($stackerName)) == $this->getConfigInstance()->getConfigEntry('stacker_' . $stackerName . '_max_size'));
 104
 105                 // Return result
 106                 return $isFull;
 107         }
 108
 109         /**
 110          * Checks whether the given stack is empty
 111          *
 112          * @param       $stackerName            Name of the stack
 113          * @return      $isEmpty                        Whether the stack is empty
 114          * @throws      NoStackerException      If given stack is missing
 115          */
 116         public function isStackEmpty ($stackerName) {
 117                 // Is the stack not yet initialized?
 118                 if (!$this->isStackInitialized($stackerName)) {
 119                         // Throw an exception
 120                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 121                 } // END - if
 122
 123                 // So, is the stack empty?
 124                 $isEmpty = (($this->getStackCount($stackerName)) == 0);
 125
 126                 // Return result
 127                 return $isEmpty;
 128         }
 129
 130         /**
 131          * Getter for size of given stack (array count)
 132          *
 133          * @param       $stackerName    Name of the stack
 134          * @return      $count                  Size of stack (array count)
 135          * @throws      NoStackerException      If given stack is missing
 136          */
 137         public function getStackCount ($stackerName) {
 138                 // Is the stack not yet initialized?
 139                 if (!$this->isStackInitialized($stackerName)) {
 140                         // Throw an exception
 141                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 142                 } // END - if
 143
 144                 // Now, count the array of entries
 145                 $count = $this->countGenericArrayElements('stacks', $stackerName, 'entries');
 146
 147                 // Return result
 148                 return $count;
 149         }
 150
 151         /**
 152          * Adds a value to given stack
 153          *
 154          * @param       $stackerName    Name of the stack
 155          * @param       $value                  Value to add to this stacker
 156          * @return      void
 157          * @throws      FullStackerException    Thrown if the stack is full
 158          */
 159         protected function addValue ($stackerName, $value) {
 160                 // Is the stack not yet initialized or full?
 161                 if (!$this->isStackInitialized($stackerName)) {
 162                         // Then do it here
 163                         $this->initStack($stackerName);
 164                 } elseif ($this->isStackFull($stackerName)) {
 165                         // Stacker is full
 166                         throw new FullStackerException(array($this, $stackerName, $value), self::EXCEPTION_STACKER_IS_FULL);
 167                 }
 168
 169                 // Now add the value to the stack
 170                 $this->pushValueToGenericArrayKey('stacks', $stackerName, 'entries', $value);
 171         }
 172
 173         /**
 174          * Get last value from named stacker
 175          *
 176          * @param       $stackerName    Name of the stack
 177          * @return      $value                  Value of last added value
 178          * @throws      NoStackerException      If the named stacker was not found
 179          * @throws      EmptyStackerException   If the named stacker is empty
 180          */
 181         protected function getLastValue ($stackerName) {
 182                 // Is the stack not yet initialized or full?
 183                 if (!$this->isStackInitialized($stackerName)) {
 184                         // Throw an exception
 185                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 186                 } elseif ($this->isStackEmpty($stackerName)) {
 187                         // Throw an exception
 188                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
 189                 }
 190
 191                 // Now get the last value
 192                 $value = $this->getGenericArrayElement('stacks', $stackerName, 'entries', $this->getStackCount($stackerName) - 1);
 193
 194                 // Return it
 195                 return $value;
 196         }
 197
 198         /**
 199          * Get first value from named stacker
 200          *
 201          * @param       $stackerName    Name of the stack
 202          * @return      $value                  Value of last added value
 203          * @throws      NoStackerException      If the named stacker was not found
 204          * @throws      EmptyStackerException   If the named stacker is empty
 205          */
 206         protected function getFirstValue ($stackerName) {
 207                 // Is the stack not yet initialized or full?
 208                 if (!$this->isStackInitialized($stackerName)) {
 209                         // Throw an exception
 210                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 211                 } elseif ($this->isStackEmpty($stackerName)) {
 212                         // Throw an exception
 213                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
 214                 }
 215
 216                 // Now get the first value
 217                 $value = $this->getGenericArrayElement('stacks', $stackerName, 'entries', 0);
 218
 219                 // Return it
 220                 return $value;
 221         }
 222
 223         /**
 224          * "Pops" last entry from stack
 225          *
 226          * @param       $stackerName    Name of the stack
 227          * @return      $value                  Value "poped" from array
 228          * @throws      NoStackerException      If the named stacker was not found
 229          * @throws      EmptyStackerException   If the named stacker is empty
 230          */
 231         protected function popLast ($stackerName) {
 232                 // Is the stack not yet initialized or full?
 233                 if (!$this->isStackInitialized($stackerName)) {
 234                         // Throw an exception
 235                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 236                 } elseif ($this->isStackEmpty($stackerName)) {
 237                         // Throw an exception
 238                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
 239                 }
 240
 241                 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
 242                 return $this->popGenericArrayElement('stacks', $stackerName, 'entries');
 243         }
 244
 245         /**
 246          * "Pops" first entry from stack
 247          *
 248          * @param       $stackerName    Name of the stack
 249          * @return      $value                  Value "shifted" from array
 250          * @throws      NoStackerException      If the named stacker was not found
 251          * @throws      EmptyStackerException   If the named stacker is empty
 252          */
 253         protected function popFirst ($stackerName) {
 254                 // Is the stack not yet initialized or full?
 255                 if (!$this->isStackInitialized($stackerName)) {
 256                         // Throw an exception
 257                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 258                 } elseif ($this->isStackEmpty($stackerName)) {
 259                         // Throw an exception
 260                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
 261                 }
 262
 263                 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
 264                 return $this->shiftGenericArrayElement('stacks', $stackerName, 'entries');
 265         }
 266 }
 267
 268 // [EOF]
 269 ?>