framework/main/classes/stacker/class_BaseStacker.php

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