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