framework/main/classes/utils/numbers/class_NumberUtils.php

   1 <?php
   2 // Own namespace
   3 namespace Org\Mxchange\CoreFramework\Utils\Numbers;
   4
   5 // Import framework stuff
   6 use Org\Mxchange\CoreFramework\Bootstrap\FrameworkBootstrap;
   7 use Org\Mxchange\CoreFramework\Object\BaseFrameworkSystem;
   8
   9 // Import SPL stuff
  10 use \InvalidArgumentException;
  11
  12 /**
  13  * A number utility class
  14  *
  15  * @author              Roland Haeder <webmaster@ship-simu.org>
  16  * @version             0.0.0
  17  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2023 Core Developer Team
  18  * @license             GNU GPL 3.0 or any newer version
  19  * @link                http://www.ship-simu.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 final class NumberUtils extends BaseFrameworkSystem {
  35         /**
  36          * Private constructor, no instance needed. If PHP would have a static initializer ...
  37          *
  38          * @return      void
  39          */
  40         private function __construct () {
  41                 // Call parent constructor
  42                 parent::__construct(__CLASS__);
  43         }
  44
  45         /**
  46          * Filter a given number into a localized number
  47          *
  48          * @param       $value          The raw float value from e.g. database
  49          * @return      $localized      Localized value
  50          * @throws      InvalidArgumentException        If a parameter has an invalid value
  51          */
  52         public static function doFilterFormatNumber (float $value) {
  53                 // Check value
  54                 //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('NUMBER-UTILS: value=%s - CALLED!', $value));
  55                 if ($value < 0) {
  56                         // Not valid value
  57                         throw new InvalidArgumentException(sprintf('value=%s cannot be below zero', $value));
  58                 }
  59
  60                 // Generate it from config and localize dependencies
  61                 switch (FrameworkBootstrap::getLanguageInstance()->getLanguageCode()) {
  62                         case 'de': // German format is a bit different to default
  63                                 $localized = number_format($value, FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('decimals'), ',', '.');
  64                                 break;
  65
  66                         default: // US, etc.
  67                                 $localized = number_format($value, FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('decimals'), '.', ',');
  68                                 break;
  69                 }
  70
  71                 // Return it
  72                 //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('NUMBER-UTILS: localized=%s - CALLED!', $localized));
  73                 return $localized;
  74         }
  75
  76         /**
  77          * Filter a given GMT timestamp (non Uni* stamp!) to make it look more
  78          * beatiful for web-based front-ends. If null is given a message id
  79          * null_timestamp will be resolved and returned.
  80          *
  81          * @param       $timestamp      Timestamp to prepare (filter) for display
  82          * @return      $readable       A readable timestamp
  83          * @throws      InvalidArgumentException        If a parameter has an invalid value
  84          */
  85         public static function doFilterFormatTimestamp (string $timestamp = NULL) {
  86                 // Check parameter
  87                 //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('NUMBER-UTILS: timestamp[%s]=%s - CALLED!', gettype($timestamp), $timestamp));
  88                 if (empty($timestamp)) {
  89                         // Throw IAE
  90                         throw new InvalidArgumentException('Parameter "timestamp" is empty');
  91                 }
  92
  93                 // Default value to return
  94                 $readable = '???';
  95
  96                 // Is the timestamp null?
  97                 if (is_null($timestamp)) {
  98                         // Get a message string
  99                         $readable = FrameworkBootstrap::getLanguageInstance()->getMessage('null_timestamp');
 100                 } else {
 101                         switch (FrameworkBootstrap::getLanguageInstance()->getLanguageCode()) {
 102                                 case 'de': // German format is a bit different to default
 103                                         // Split the GMT stamp up
 104                                         $dateTime  = explode(' ', $timestamp  );
 105                                         $dateArray = explode('-', $dateTime[0]);
 106                                         $timeArray = explode(':', $dateTime[1]);
 107
 108                                         // Construct the timestamp
 109                                         $readable = sprintf(FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('german_date_time'),
 110                                                 $dateArray[0],
 111                                                 $dateArray[1],
 112                                                 $dateArray[2],
 113                                                 $timeArray[0],
 114                                                 $timeArray[1],
 115                                                 $timeArray[2]
 116                                         );
 117                                         break;
 118
 119                                 default: // Default is pass-through
 120                                         $readable = $timestamp;
 121                                         break;
 122                         }
 123                 }
 124
 125                 // Return the stamp
 126                 //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('NUMBER-UTILS: readable=%s - EXIT!', $readable));
 127                 return $readable;
 128         }
 129
 130         /**
 131          * Checks whether the given number is really a number (only chars 0-9).
 132          *
 133          * @param       $num    A string consisting only chars between 0 and 9
 134          * @param       $castValue      Whether to cast the value to double. Do only use this to secure numbers from Requestable classes.
 135          * @param       $assertMismatch         Whether to assert mismatches
 136          * @return      $formatted      The (hopefully) secured numbered value
 137          * @throws      InvalidArgumentException        If a parameter has an invalid value
 138          */
 139         public static function bigintval (string $num, bool $castValue = true, bool $assertMismatch = false) {
 140                 // Check parameter
 141                 //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('NUMBER-UTILS: num=%s,castValue=%d,assertMismatch=%d - CALLED!', $num, intval($castValue), intval($assertMismatch)));
 142                 if ($num === '') {
 143                         // Throw IAE
 144                         throw new InvalidArgumentException('Parameter "num" is empty');
 145                 }
 146
 147                 // Filter all numbers out
 148                 $formatted = preg_replace('/[^0123456789]/', '', $num);
 149
 150                 // Shall we cast?
 151                 //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('NUMBER-UTILS: formatted=%s', $formatted));
 152                 if ($castValue === true) {
 153                         // Cast to biggest numeric type, int is not enough for this cast
 154                         $formatted = (double) $formatted;
 155                 }
 156
 157                 // Assert only if requested
 158                 //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('NUMBER-UTILS: formatted[%s]=%s', gettype($formatted), $formatted));
 159                 if ($assertMismatch === true) {
 160                         // Has the whole value changed?
 161                         assert(('' . $formatted . '' != '' . $num . '') && (!is_null($num)));
 162                 }
 163
 164                 // Return result
 165                 //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('NUMBER-UTILS: formatted[%s]=%s - EXIT!', gettype($formatted), $formatted));
 166                 return $formatted;
 167         }
 168
 169 }