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