Continued:

[core.git] / framework / main / classes / utils / strings / class_StringUtils.php

diff --git a/framework/main/classes/utils/strings/class_StringUtils.php b/framework/main/classes/utils/strings/class_StringUtils.php
index 257d325d5e23b44c947c479b327fcbb30cef3162..c97c9fe3d23c0c3247fa8fb7b3e691bbedeef494 100644 (file)
--- a/framework/main/classes/utils/strings/class_StringUtils.php
+++ b/framework/main/classes/utils/strings/class_StringUtils.php
@@ -5,6 +5,7 @@ namespace Org\Mxchange\CoreFramework\Utils\Strings;
 // Import framework stuff
 use Org\Mxchange\CoreFramework\Bootstrap\FrameworkBootstrap;
 use Org\Mxchange\CoreFramework\Configuration\FrameworkConfiguration;
+use Org\Mxchange\CoreFramework\Generic\FrameworkInterface;
 use Org\Mxchange\CoreFramework\Generic\NullPointerException;
 use Org\Mxchange\CoreFramework\Object\BaseFrameworkSystem;
 
@@ -16,7 +17,7 @@ use \InvalidArgumentException;
  *
  * @author             Roland Haeder <webmaster@ship-simu.org>
  * @version            0.0.0
- * @copyright  Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2021 Core Developer Team
+ * @copyright  Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2023 Core Developer Team
  * @license            GNU GPL 3.0 or any newer version
  * @link               http://www.ship-simu.org
  *
@@ -128,9 +129,11 @@ final class StringUtils extends BaseFrameworkSystem {
         */
        private function __construct () {
                // Call parent constructor
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('STRING-UTILS: CONSTRUCTED!');
                parent::__construct(__CLASS__);
 
                // Is one not set?
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('STRING-UTILS: self::archArrayElement=%d', self::$archArrayElement));
                if (empty(self::$archArrayElement)) {
                        // Set array element
                        self::$archArrayElement = (PHP_INT_SIZE === 8 ? 64 : 32);
@@ -139,6 +142,9 @@ final class StringUtils extends BaseFrameworkSystem {
                        self::$thousands = FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('thousands_separator');
                        self::$decimals = FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('decimals_separator');
                }
+
+               // Trace message
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('STRING-UTILS: EXIT!');
        }
 
        /**
@@ -151,15 +157,17 @@ final class StringUtils extends BaseFrameworkSystem {
         */
        public static function convertDashesToUnderscores (string $str) {
                // Validate parameter
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: str=%s - CALLED!', $str));
                if (empty($str)) {
                        // Entry is empty
-                       throw new InvalidArgumentException('Parameter "str" is empty');
+                       throw new InvalidArgumentException('Parameter "str" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
                }
 
                // Convert them all
                $str = str_replace('-', '_', $str);
 
                // Return converted string
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: str=%s - EXIT!', $str));
                return $str;
        }
 
@@ -173,7 +181,7 @@ final class StringUtils extends BaseFrameworkSystem {
         */
        public static function encodeData ($rawData) {
                // Make sure no objects or resources pass through
-               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('STRING-UTILS: rawData[]=%s - CALLED!', gettype($rawData)));
+               //* N NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: rawData[]=%s - CALLED!', gettype($rawData)));
                if (is_object($rawData) || is_resource($rawData)) {
                        // Not all variable types should be serialized here
                        throw new InvalidArgumentException(sprintf('rawData[]=%s cannot be serialized.', gettype($rawData)));
@@ -186,7 +194,7 @@ final class StringUtils extends BaseFrameworkSystem {
                $encoded = self::packString(json_encode($rawData));
 
                // And return it
-               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('STRING-UTILS: encoded()=%d - EXIT!', strlen($encoded)));
+               //* N NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: encoded()=%d - EXIT!', strlen($encoded)));
                return $encoded;
        }
 
@@ -199,10 +207,10 @@ final class StringUtils extends BaseFrameworkSystem {
         */
        public static final function convertToClassName (string $str) {
                // Is the parameter valid?
-               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('STRING-UTILS: str=%s - CALLED!', $str));
+               //* N NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: str=%s - CALLED!', $str));
                if (empty($str)) {
                        // No empty strings, please
-                       throw new InvalidArgumentException('Parameter "str" is empty', self::EXCEPTION_CONFIG_KEY_IS_EMPTY);
+                       throw new InvalidArgumentException('Parameter "str" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
                } elseif (!isset(self::$cache[$str])) {
                        // Init class name
                        $className = '';
@@ -211,19 +219,19 @@ final class StringUtils extends BaseFrameworkSystem {
                        $str = self::convertDashesToUnderscores($str);
 
                        // Now use that underscores to get classname parts for hungarian style
-                       //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('STRING-UTILS: str=%s - AFTER!', $str));
+                       //* N NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('STRING-UTILS: str=%s - AFTER!', $str));
                        foreach (explode('_', $str) as $strPart) {
                                // Make the class name part lower case and first upper case
                                $className .= ucfirst(strtolower($strPart));
                        }
 
                        // Set cache
-                       //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('STRING-UTILS: self[%s]=%s - SET!', $str, $className));
+                       //* N NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('STRING-UTILS: self[%s]=%s - SET!', $str, $className));
                        self::$cache[$str] = $className;
                }
 
                // Return class name
-               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('STRING-UTILS: self[%s]=%s - EXIT!', $str, $className));
+               //* N NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: self[%s]=%s - EXIT!', $str, $className));
                return self::$cache[$str];
        }
 
@@ -239,12 +247,14 @@ final class StringUtils extends BaseFrameworkSystem {
         */
        public static function formatCurrency (float $value, string $currency = '&euro;', int $decNum = 2) {
                // Init instance
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: value=%s,currency=%s,decNum=%d - CALLED!', $value, $currency, $decNum));
                $dummyInstance = new StringUtils();
 
                // Reformat the US number
                $price = number_format($value, $decNum, self::$decimals, self::$thousands) . $currency;
 
                // Return as string...
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: price=%s - EXIT!', $price));
                return $price;
        }
 
@@ -257,8 +267,16 @@ final class StringUtils extends BaseFrameworkSystem {
         *
         * @param       $hex    Hexadecimal string
         * @return      $dec    Decimal number
+        * @throws      InvalidArgumentException        If a paramter is invalid
         */
        public static function hex2dec (string $hex) {
+               // Check parameter
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: hex=%s - CALLED!', $hex));
+               if (empty($hex)) {
+                       // Throw IAE
+                       throw new InvalidArgumentException('Parameter "hex" is empty');
+               }
+
                // Convert to all lower-case
                $hex = strtolower($hex);
 
@@ -277,6 +295,7 @@ final class StringUtils extends BaseFrameworkSystem {
                }
 
                // Return the decimal number
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: sign=%s,dec=%s - EXIT!', $sign, $dec));
                return $sign . $dec;
        }
 
@@ -290,10 +309,18 @@ final class StringUtils extends BaseFrameworkSystem {
         * @param       $dec            Decimal number, even with negative sign
         * @param       $maxLength      Optional maximum length of the string
         * @return      $hex    Hexadecimal string
+        * @throws      InvalidArgumentException        If a paramter is invalid
         */
-       public static function dec2hex (string $dec, int $maxLength = 0) {
-               // maxLength can be zero or devideable by 2
-               assert(($maxLength == 0) || (($maxLength % 2) == 0));
+       public static function dec2hex (int $dec, int $maxLength = 0) {
+               // Check parameter
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: dec=%d,maxLength=%d - CALLED!', $dec, $maxLength));
+               if ($dec < 0) {
+                       // Throw IAE
+                       throw new InvalidArgumentException(sprintf('dec=%d is below zero', $dec));
+               } elseif ($maxLength != 0 && ($maxLength % 2) != 0) {
+                       // Throw it again
+                       throw new InvalidArgumentException(sprintf('maxLength=%d is not dividable by 2 or zero', $maxLength));
+               }
 
                // Detect sign (negative/positive numbers)
                $sign = '';
@@ -323,6 +350,7 @@ final class StringUtils extends BaseFrameworkSystem {
                }
 
                // Return the hexadecimal string
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: sign=%s,hex=%s - EXIT!', $sign, $hex));
                return $sign . $hex;
        }
 
@@ -331,15 +359,25 @@ final class StringUtils extends BaseFrameworkSystem {
         *
         * @param       $asc    The ASCII string to be converted
         * @return      $dec    Decimal number
+        * @throws      InvalidArgumentException        If a paramter is invalid
         */
        public static function asc2dec (string $asc) {
+               // Check parameter
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: asc=%s - CALLED!', $asc));
+               if (empty($asc)) {
+                       // Throw IAE
+                       throw new InvalidArgumentException('Parameter "asc" is empty');
+               }
+
                // Convert it into a hexadecimal number
                $hex = bin2hex($asc);
 
                // And back into a decimal number
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('STRING-UTILS: hex=%s', $hex));
                $dec = self::hex2dec($hex);
 
                // Return it
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: dec=%d - EXIT!', $dec));
                return $dec;
        }
 
@@ -348,15 +386,25 @@ final class StringUtils extends BaseFrameworkSystem {
         *
         * @param       $dec            Decimal number
         * @return      $asc    An ASCII string
+        * @throws      InvalidArgumentException        If a paramter is invalid
         */
-       public static function dec2asc (string $dec) {
+       public static function dec2asc (int $dec) {
+               // Check parameter
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: dec=%d - CALLED!', $dec));
+               if ($dec < 0) {
+                       // Throw IAE
+                       throw new InvalidArgumentException(sprintf('dec=%d is below zero', $dec));
+               }
+
                // First convert the number into a hexadecimal string
                $hex = self::dec2hex($dec);
 
                // Then convert it into the ASCII string
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('STRING-UTILS: hex=%s', $hex));
                $asc = self::hex2asc($hex);
 
                // Return it
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: asc=%s - EXIT!', $asc));
                return $asc;
        }
 
@@ -366,11 +414,18 @@ final class StringUtils extends BaseFrameworkSystem {
         *
         * @param       $hex    Hexadecimal string
         * @return      $asc    An ASCII string
+        * @throws      InvalidArgumentException        If a paramter is invalid
         */
-       public static function hex2asc ($hex) {
+       public static function hex2asc (string $hex) {
                // Check for length, it must be devideable by 2
-               //* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('hex='.$hex);
-               assert((strlen($hex) % 2) == 0);
+               /* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: hex=%s - CALLED!', $hex));
+               if (empty($hex)) {
+                       // Throw IAE
+                       throw new InvalidArgumentException('Parameter "hex" is empty');
+               } elseif ((strlen($hex) % 2) != 0) {
+                       // Throw it again
+                       throw new InvalidArgumentException(sprintf('hex=%s length not dividable by 2', $hex));
+               }
 
                // Walk the string
                $asc = '';
@@ -383,6 +438,7 @@ final class StringUtils extends BaseFrameworkSystem {
                }
 
                // Return the final string
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: asc=%s - EXIT!', $asc));
                return $asc;
        }
 
@@ -392,17 +448,25 @@ final class StringUtils extends BaseFrameworkSystem {
         *
         * @param       $str            Unpacked string
         * @return      $packed         Packed string
+        * @throws      InvalidArgumentException        If a paramter is invalid
         * @todo        Improve documentation
         */
        private static function packString (string $str) {
+               // Check parameter
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: str=%s - CALLED!', $str));
+               if (empty($str)) {
+                       // Throw IAE
+                       throw new InvalidArgumentException('Parameter "str" is empty');
+               }
+
                // First compress the string (gzcompress is okay)
-               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('STRING-UTILS: str=%s - CALLED!', $str));
                $str = gzcompress($str);
 
                // Init variable
                $packed = '';
 
                // And start the "encoding" loop
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('STRING-UTILS: Looping through str()=%d ...', strlen($str)));
                for ($idx = 0; $idx < strlen($str); $idx += self::$packingData[self::$archArrayElement]['step']) {
                        $big = 0;
                        for ($i = 0; $i < self::$packingData[self::$archArrayElement]['step']; $i++) {
@@ -425,13 +489,13 @@ final class StringUtils extends BaseFrameworkSystem {
 
                        // Create chunk
                        $chunk = str_pad(pack(self::$packingData[self::$archArrayElement]['format'], $l, $r), 8, '0', STR_PAD_LEFT);
-                       //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('STRING-UTILS: big=%d,chunk(%d)=%s', $big, strlen($chunk), md5($chunk)));
+                       //* N NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('STRING-UTILS: big=%d,chunk(%d)=%s', $big, strlen($chunk), md5($chunk)));
 
                        $packed .= $chunk;
-               } // END - for
+               }
 
                // Return it
-               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('STRING-UTILS: packed=%s - EXIT!', $packed));
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: packed=%s - EXIT!', $packed));
                return $packed;
        }
 
@@ -441,18 +505,28 @@ final class StringUtils extends BaseFrameworkSystem {
         * @param       $num    A string consisting only chars between 0 and 9
         * @param       $assertMismatch         Whether to assert mismatches
         * @return      $ret    The (hopefully) secured hext-numbered value
+        * @throws      InvalidArgumentException        If a paramter is invalid
         */
        public static function hexval (string $num, bool $assertMismatch = false) {
+               // Check parameter
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: num=%s,assertMismatch=%d - CALLED!', $num, intval($assertMismatch)));
+               if (empty($num)) {
+                       // Throw IAE
+                       throw new InvalidArgumentException('Parameter "num" is empty');
+               }
+
                // Filter all numbers out
                $ret = preg_replace('/[^0123456789abcdefABCDEF]/', '', $num);
 
                // Assert only if requested
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('STRING-UTILS: ret=%s', $ret));
                if ($assertMismatch === true) {
                        // Has the whole value changed?
                        assert(('' . $ret . '' != '' . $num . '') && (!is_null($num)));
                }
 
                // Return result
+               //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('STRING-UTILS: ret=%s - EXIT!', $ret));
                return $ret;
        }