framework/main/classes/stacker/filo/class_FiLoStacker.php

   1 <?php
   2 // Own namespace
   3 namespace Org\Mxchange\CoreFramework\Stack;
   4
   5 // Import framework-specific stuff
   6 use Org\Mxchange\CoreFramework\Generic\FrameworkInterface;
   7
   8 /**
   9  * A FiLo Stacker class
  10  *
  11  * @author              Roland Haeder <webmaster@shipsimu.org>
  12  * @version             0.0.0
  13  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2023 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 class FiLoStacker extends BaseStacker implements Stackable {
  31         /**
  32          * Protected constructor
  33          *
  34          * @return      void
  35          */
  36         private function __construct () {
  37                 // Call parent constructor
  38                 parent::__construct(__CLASS__);
  39         }
  40
  41         /**
  42          * Creates an instance of the class Stacker and prepares it for usage
  43          *
  44          * @return      $stackInstance  An instance of FiLoStacker
  45          */
  46         public static final function createFiLoStacker () {
  47                 // Get a new instance
  48                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILO-FILE-STACK: CALLED!');
  49                 $stackInstance = new FiLoStacker();
  50
  51                 // Init the generic stacker
  52                 $stackInstance->initStack('generic');
  53
  54                 // Return the prepared instance
  55                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILO-FILE-STACK: stackInstance=%s - EXIT!', $stackInstance->__toString()));
  56                 return $stackInstance;
  57         }
  58
  59         /**
  60          * Pushs a value on a named stacker
  61          *
  62          * @param       $stackerName    Name of the stack
  63          * @param       $value                  Value to push on it
  64          * @return      void
  65          * @throws      InvalidArgumentException If a parameter is invalid
  66          * @throws      BadMethodCallException  If the stack is full
  67          */
  68         public function pushNamed (string $stackerName, $value) {
  69                 // Validate parameter
  70                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILO-FILE-STACK: stackerName=%s,value[]=%s - CALLED!', $stackerName, gettype($value)));
  71                 if (empty($stackerName)) {
  72                         // No empty stack name
  73                         throw new InvalidArgumentException('Parameter "stackerName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
  74                 }
  75
  76                 // Call the protected method
  77                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILO-FILE-STACK: Invoking parent::addValueToStack(%s,%s) ...', $stackerName, gettype($value)));
  78                 parent::addValueToStack($stackerName, $value);
  79
  80                 // Trace message
  81                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILO-FILE-STACK: EXIT!');
  82         }
  83
  84         /**
  85          * 'Pops' a value from a named stacker and returns it's value
  86          *
  87          * @param       $stackerName    Name of the stack
  88          * @return      $value                  Value of the current stack entry
  89          * @throws      InvalidArgumentException If a parameter is invalid
  90          * @throws      BadMethodCallException  If the named stacker was not found
  91          * @throws      BadMethodCallException  If the named stacker is empty
  92          */
  93         public function popNamed (string $stackerName) {
  94                 // Validate parameter
  95                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILO-FILE-STACK: stackerName=%s - CALLED!', $stackerName));
  96                 if (empty($stackerName)) {
  97                         // No empty stack name
  98                         throw new InvalidArgumentException('Parameter "stackerName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
  99                 }
 100
 101                 // Get the value
 102                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILO-FILE-STACK: this->getNamed(%s) ...', $stackerName));
 103                 $value = $this->getNamed($stackerName);
 104
 105                 // Call the protected method
 106                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILO-FILE-STACK: parent::popLast(%s) ...', $stackerName));
 107                 parent::popLast($stackerName);
 108
 109                 // Return the value
 110                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILO-FILE-STACK: value[]=%s - EXIT!', gettype($value)));
 111                 return $value;
 112         }
 113
 114         /**
 115          * Get value from named stacker
 116          *
 117          * @param       $stackerName    Name of the stack
 118          * @return      $value                  Value of last added value
 119          * @throws      InvalidArgumentException If a parameter is invalid
 120          * @throws      BadMethodCallException  If the named stacker was not found
 121          * @throws      BadMethodCallException  If the named stacker is empty
 122          */
 123         public function getNamed (string $stackerName) {
 124                 // Validate parameter
 125                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILO-FILE-STACK: stackerName=%s - CALLED!', $stackerName));
 126                 if (empty($stackerName)) {
 127                         // No empty stack name
 128                         throw new InvalidArgumentException('Parameter "stackerName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 129                 }
 130
 131                 // Call the protected method
 132                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILO-FILE-STACK: parent::getLastValue(%s) ...', $stackerName));
 133                 $value = parent::getLastValue($stackerName);
 134
 135                 // Return the value
 136                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILO-FILE-STACK: value[]=%s - EXIT!', gettype($value)));
 137                 return $value;
 138         }
 139
 140 }