Final part of breaking down the Engineering class for Excel Engineering functions into smaller individual/group classes (#1940)

* Final breaking down the Engineering class for Excel Engineering functions into smaller individual/group classes
* Additional unhappy path tests for Complex Number functions
* Fix return docblocks for floats to allow for error strings

src/PhpSpreadsheet/Calculation/Calculation.php

@@ -565,7 +565,7 @@ class Calculation
         ],
         'COMPLEX' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'COMPLEX'],
+            'functionCall' => [Engineering\Complex::class, 'COMPLEX'],
             'argumentCount' => '2,3',
         ],
         'CONCAT' => [
@@ -1278,127 +1278,127 @@ class Calculation
         ],
         'IMABS' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMABS'],
+            'functionCall' => [Engineering\ComplexFunctions::class, 'IMABS'],
             'argumentCount' => '1',
         ],
         'IMAGINARY' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMAGINARY'],
+            'functionCall' => [Engineering\Complex::class, 'IMAGINARY'],
             'argumentCount' => '1',
         ],
         'IMARGUMENT' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMARGUMENT'],
+            'functionCall' => [Engineering\ComplexFunctions::class, 'IMARGUMENT'],
             'argumentCount' => '1',
         ],
         'IMCONJUGATE' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMCONJUGATE'],
+            'functionCall' => [Engineering\ComplexFunctions::class, 'IMCONJUGATE'],
             'argumentCount' => '1',
         ],
         'IMCOS' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMCOS'],
+            'functionCall' => [Engineering\ComplexFunctions::class, 'IMCOS'],
             'argumentCount' => '1',
         ],
         'IMCOSH' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMCOSH'],
+            'functionCall' => [Engineering\ComplexFunctions::class, 'IMCOSH'],
             'argumentCount' => '1',
         ],
         'IMCOT' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMCOT'],
+            'functionCall' => [Engineering\ComplexFunctions::class, 'IMCOT'],
             'argumentCount' => '1',
         ],
         'IMCSC' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMCSC'],
+            'functionCall' => [Engineering\ComplexFunctions::class, 'IMCSC'],
             'argumentCount' => '1',
         ],
         'IMCSCH' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMCSCH'],
+            'functionCall' => [Engineering\ComplexFunctions::class, 'IMCSCH'],
             'argumentCount' => '1',
         ],
         'IMDIV' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMDIV'],
+            'functionCall' => [Engineering\ComplexOperations::class, 'IMDIV'],
             'argumentCount' => '2',
         ],
         'IMEXP' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMEXP'],
+            'functionCall' => [Engineering\ComplexFunctions::class, 'IMEXP'],
             'argumentCount' => '1',
         ],
         'IMLN' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMLN'],
+            'functionCall' => [Engineering\ComplexFunctions::class, 'IMLN'],
             'argumentCount' => '1',
         ],
         'IMLOG10' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMLOG10'],
+            'functionCall' => [Engineering\ComplexFunctions::class, 'IMLOG10'],
             'argumentCount' => '1',
         ],
         'IMLOG2' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMLOG2'],
+            'functionCall' => [Engineering\ComplexFunctions::class, 'IMLOG2'],
             'argumentCount' => '1',
         ],
         'IMPOWER' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMPOWER'],
+            'functionCall' => [Engineering\ComplexFunctions::class, 'IMPOWER'],
             'argumentCount' => '2',
         ],
         'IMPRODUCT' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMPRODUCT'],
+            'functionCall' => [Engineering\ComplexOperations::class, 'IMPRODUCT'],
             'argumentCount' => '1+',
         ],
         'IMREAL' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMREAL'],
+            'functionCall' => [Engineering\Complex::class, 'IMREAL'],
             'argumentCount' => '1',
         ],
         'IMSEC' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMSEC'],
+            'functionCall' => [Engineering\ComplexFunctions::class, 'IMSEC'],
             'argumentCount' => '1',
         ],
         'IMSECH' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMSECH'],
+            'functionCall' => [Engineering\ComplexFunctions::class, 'IMSECH'],
             'argumentCount' => '1',
         ],
         'IMSIN' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMSIN'],
+            'functionCall' => [Engineering\ComplexFunctions::class, 'IMSIN'],
             'argumentCount' => '1',
         ],
         'IMSINH' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMSINH'],
+            'functionCall' => [Engineering\ComplexFunctions::class, 'IMSINH'],
             'argumentCount' => '1',
         ],
         'IMSQRT' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMSQRT'],
+            'functionCall' => [Engineering\ComplexFunctions::class, 'IMSQRT'],
             'argumentCount' => '1',
         ],
         'IMSUB' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMSUB'],
+            'functionCall' => [Engineering\ComplexOperations::class, 'IMSUB'],
             'argumentCount' => '2',
         ],
         'IMSUM' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMSUM'],
+            'functionCall' => [Engineering\ComplexOperations::class, 'IMSUM'],
             'argumentCount' => '1+',
         ],
         'IMTAN' => [
             'category' => Category::CATEGORY_ENGINEERING,
-            'functionCall' => [Engineering::class, 'IMTAN'],
+            'functionCall' => [Engineering\ComplexFunctions::class, 'IMTAN'],
             'argumentCount' => '1',
         ],
         'INDEX' => [

src/PhpSpreadsheet/Calculation/Engineering.php

@@ -3,14 +3,21 @@
 namespace PhpOffice\PhpSpreadsheet\Calculation;
 
 use Complex\Complex;
-use Complex\Exception as ComplexException;
+use PhpOffice\PhpSpreadsheet\Calculation\Engineering\ComplexFunctions;
+use PhpOffice\PhpSpreadsheet\Calculation\Engineering\ComplexOperations;
 
+/**
+ * @deprecated 1.18.0
+ */
 class Engineering
 {
     /**
      * EULER.
+     *
+     * @deprecated 1.18.0
+     * @see Use Engineering\Constants\EULER instead
      */
-    const EULER = 2.71828182845904523536;
+    public const EULER = 2.71828182845904523536;
 
     /**
      * parseComplex.
@@ -552,6 +559,10 @@ class Engineering
      * Excel Function:
      *        COMPLEX(realNumber,imaginary[,suffix])
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the COMPLEX() method in the Engineering\Complex class instead
+     *
      * @param float $realNumber the real coefficient of the complex number
      * @param float $imaginary the imaginary coefficient of the complex number
      * @param string $suffix The suffix for the imaginary component of the complex number.
@@ -561,20 +572,7 @@ class Engineering
      */
     public static function COMPLEX($realNumber = 0.0, $imaginary = 0.0, $suffix = 'i')
     {
-        $realNumber = ($realNumber === null) ? 0.0 : Functions::flattenSingleValue($realNumber);
+        return Engineering\Complex::COMPLEX($realNumber, $imaginary, $suffix);
-        $imaginary = ($imaginary === null) ? 0.0 : Functions::flattenSingleValue($imaginary);
-        $suffix = ($suffix === null) ? 'i' : Functions::flattenSingleValue($suffix);
-
-        if (
-            ((is_numeric($realNumber)) && (is_numeric($imaginary))) &&
-            (($suffix == 'i') || ($suffix == 'j') || ($suffix == ''))
-        ) {
-            $complex = new Complex($realNumber, $imaginary, $suffix);
-
-            return (string) $complex;
-        }
-
-        return Functions::VALUE();
     }
 
     /**
@@ -585,16 +583,18 @@ class Engineering
      * Excel Function:
      *        IMAGINARY(complexNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMAGINARY() method in the Engineering\Complex class instead
+     *
      * @param string $complexNumber the complex number for which you want the imaginary
      *                                         coefficient
      *
-     * @return float
+     * @return float|string
      */
     public static function IMAGINARY($complexNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return Engineering\Complex::IMAGINARY($complexNumber);
-
-        return (new Complex($complexNumber))->getImaginary();
     }
 
     /**
@@ -605,15 +605,17 @@ class Engineering
      * Excel Function:
      *        IMREAL(complexNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMREAL() method in the Engineering\Complex class instead
+     *
      * @param string $complexNumber the complex number for which you want the real coefficient
      *
-     * @return float
+     * @return float|string
      */
     public static function IMREAL($complexNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return Engineering\Complex::IMREAL($complexNumber);
-
-        return (new Complex($complexNumber))->getReal();
     }
 
     /**
@@ -624,15 +626,17 @@ class Engineering
      * Excel Function:
      *        IMABS(complexNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMABS() method in the Engineering\ComplexFunctions class instead
+     *
      * @param string $complexNumber the complex number for which you want the absolute value
      *
-     * @return float
+     * @return float|string
      */
     public static function IMABS($complexNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return ComplexFunctions::IMABS($complexNumber);
-
-        return (new Complex($complexNumber))->abs();
     }
 
     /**
@@ -644,20 +648,17 @@ class Engineering
      * Excel Function:
      *        IMARGUMENT(complexNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMARGUMENT() method in the Engineering\ComplexFunctions class instead
+     *
      * @param string $complexNumber the complex number for which you want the argument theta
      *
      * @return float|string
      */
     public static function IMARGUMENT($complexNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return ComplexFunctions::IMARGUMENT($complexNumber);
-
-        $complex = new Complex($complexNumber);
-        if ($complex->getReal() == 0.0 && $complex->getImaginary() == 0.0) {
-            return Functions::DIV0();
-        }
-
-        return $complex->argument();
     }
 
     /**
@@ -668,15 +669,17 @@ class Engineering
      * Excel Function:
      *        IMCONJUGATE(complexNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMARGUMENT() method in the Engineering\ComplexFunctions class instead
+     *
      * @param string $complexNumber the complex number for which you want the conjugate
      *
      * @return string
      */
     public static function IMCONJUGATE($complexNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return ComplexFunctions::IMCONJUGATE($complexNumber);
-
-        return (string) (new Complex($complexNumber))->conjugate();
     }
 
     /**
@@ -687,15 +690,17 @@ class Engineering
      * Excel Function:
      *        IMCOS(complexNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMCOS() method in the Engineering\ComplexFunctions class instead
+     *
      * @param string $complexNumber the complex number for which you want the cosine
      *
      * @return float|string
      */
     public static function IMCOS($complexNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return ComplexFunctions::IMCOS($complexNumber);
-
-        return (string) (new Complex($complexNumber))->cos();
     }
 
     /**
@@ -706,15 +711,17 @@ class Engineering
      * Excel Function:
      *        IMCOSH(complexNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMCOSH() method in the Engineering\ComplexFunctions class instead
+     *
      * @param string $complexNumber the complex number for which you want the hyperbolic cosine
      *
      * @return float|string
      */
     public static function IMCOSH($complexNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return ComplexFunctions::IMCOSH($complexNumber);
-
-        return (string) (new Complex($complexNumber))->cosh();
     }
 
     /**
@@ -725,15 +732,17 @@ class Engineering
      * Excel Function:
      *        IMCOT(complexNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMCOT() method in the Engineering\ComplexFunctions class instead
+     *
      * @param string $complexNumber the complex number for which you want the cotangent
      *
      * @return float|string
      */
     public static function IMCOT($complexNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return ComplexFunctions::IMCOT($complexNumber);
-
-        return (string) (new Complex($complexNumber))->cot();
     }
 
     /**
@@ -744,15 +753,17 @@ class Engineering
      * Excel Function:
      *        IMCSC(complexNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMCSC() method in the Engineering\ComplexFunctions class instead
+     *
      * @param string $complexNumber the complex number for which you want the cosecant
      *
      * @return float|string
      */
     public static function IMCSC($complexNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return ComplexFunctions::IMCSC($complexNumber);
-
-        return (string) (new Complex($complexNumber))->csc();
     }
 
     /**
@@ -763,15 +774,17 @@ class Engineering
      * Excel Function:
      *        IMCSCH(complexNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMCSCH() method in the Engineering\ComplexFunctions class instead
+     *
      * @param string $complexNumber the complex number for which you want the hyperbolic cosecant
      *
      * @return float|string
      */
     public static function IMCSCH($complexNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return ComplexFunctions::IMCSCH($complexNumber);
-
-        return (string) (new Complex($complexNumber))->csch();
     }
 
     /**
@@ -782,15 +795,17 @@ class Engineering
      * Excel Function:
      *        IMSIN(complexNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMSIN() method in the Engineering\ComplexFunctions class instead
+     *
      * @param string $complexNumber the complex number for which you want the sine
      *
      * @return float|string
      */
     public static function IMSIN($complexNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return ComplexFunctions::IMSIN($complexNumber);
-
-        return (string) (new Complex($complexNumber))->sin();
     }
 
     /**
@@ -801,15 +816,17 @@ class Engineering
      * Excel Function:
      *        IMSINH(complexNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMSINH() method in the Engineering\ComplexFunctions class instead
+     *
      * @param string $complexNumber the complex number for which you want the hyperbolic sine
      *
      * @return float|string
      */
     public static function IMSINH($complexNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return ComplexFunctions::IMSINH($complexNumber);
-
-        return (string) (new Complex($complexNumber))->sinh();
     }
 
     /**
@@ -820,15 +837,17 @@ class Engineering
      * Excel Function:
      *        IMSEC(complexNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMSEC() method in the Engineering\ComplexFunctions class instead
+     *
      * @param string $complexNumber the complex number for which you want the secant
      *
      * @return float|string
      */
     public static function IMSEC($complexNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return ComplexFunctions::IMSEC($complexNumber);
-
-        return (string) (new Complex($complexNumber))->sec();
     }
 
     /**
@@ -839,15 +858,17 @@ class Engineering
      * Excel Function:
      *        IMSECH(complexNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMSECH() method in the Engineering\ComplexFunctions class instead
+     *
      * @param string $complexNumber the complex number for which you want the hyperbolic secant
      *
      * @return float|string
      */
     public static function IMSECH($complexNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return ComplexFunctions::IMSECH($complexNumber);
-
-        return (string) (new Complex($complexNumber))->sech();
     }
 
     /**
@@ -858,15 +879,17 @@ class Engineering
      * Excel Function:
      *        IMTAN(complexNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMTAN() method in the Engineering\ComplexFunctions class instead
+     *
      * @param string $complexNumber the complex number for which you want the tangent
      *
      * @return float|string
      */
     public static function IMTAN($complexNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return ComplexFunctions::IMTAN($complexNumber);
-
-        return (string) (new Complex($complexNumber))->tan();
     }
 
     /**
@@ -877,20 +900,17 @@ class Engineering
      * Excel Function:
      *        IMSQRT(complexNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMSQRT() method in the Engineering\ComplexFunctions class instead
+     *
      * @param string $complexNumber the complex number for which you want the square root
      *
      * @return string
      */
     public static function IMSQRT($complexNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return ComplexFunctions::IMSQRT($complexNumber);
-
-        $theta = self::IMARGUMENT($complexNumber);
-        if ($theta === Functions::DIV0()) {
-            return '0';
-        }
-
-        return (string) (new Complex($complexNumber))->sqrt();
     }
 
     /**
@@ -901,20 +921,17 @@ class Engineering
      * Excel Function:
      *        IMLN(complexNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMLN() method in the Engineering\ComplexFunctions class instead
+     *
      * @param string $complexNumber the complex number for which you want the natural logarithm
      *
      * @return string
      */
     public static function IMLN($complexNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return ComplexFunctions::IMLN($complexNumber);
-
-        $complex = new Complex($complexNumber);
-        if ($complex->getReal() == 0.0 && $complex->getImaginary() == 0.0) {
-            return Functions::NAN();
-        }
-
-        return (string) (new Complex($complexNumber))->ln();
     }
 
     /**
@@ -925,20 +942,17 @@ class Engineering
      * Excel Function:
      *        IMLOG10(complexNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMLOG10() method in the Engineering\ComplexFunctions class instead
+     *
      * @param string $complexNumber the complex number for which you want the common logarithm
      *
      * @return string
      */
     public static function IMLOG10($complexNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return ComplexFunctions::IMLOG10($complexNumber);
-
-        $complex = new Complex($complexNumber);
-        if ($complex->getReal() == 0.0 && $complex->getImaginary() == 0.0) {
-            return Functions::NAN();
-        }
-
-        return (string) (new Complex($complexNumber))->log10();
     }
 
     /**
@@ -949,20 +963,17 @@ class Engineering
      * Excel Function:
      *        IMLOG2(complexNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMLOG2() method in the Engineering\ComplexFunctions class instead
+     *
      * @param string $complexNumber the complex number for which you want the base-2 logarithm
      *
      * @return string
      */
     public static function IMLOG2($complexNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return ComplexFunctions::IMLOG2($complexNumber);
-
-        $complex = new Complex($complexNumber);
-        if ($complex->getReal() == 0.0 && $complex->getImaginary() == 0.0) {
-            return Functions::NAN();
-        }
-
-        return (string) (new Complex($complexNumber))->log2();
     }
 
     /**
@@ -973,15 +984,17 @@ class Engineering
      * Excel Function:
      *        IMEXP(complexNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMEXP() method in the Engineering\ComplexFunctions class instead
+     *
      * @param string $complexNumber the complex number for which you want the exponential
      *
      * @return string
      */
     public static function IMEXP($complexNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return ComplexFunctions::IMEXP($complexNumber);
-
-        return (string) (new Complex($complexNumber))->exp();
     }
 
     /**
@@ -992,6 +1005,10 @@ class Engineering
      * Excel Function:
      *        IMPOWER(complexNumber,realNumber)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMPOWER() method in the Engineering\ComplexFunctions class instead
+     *
      * @param string $complexNumber the complex number you want to raise to a power
      * @param float $realNumber the power to which you want to raise the complex number
      *
@@ -999,14 +1016,7 @@ class Engineering
      */
     public static function IMPOWER($complexNumber, $realNumber)
     {
-        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        return ComplexFunctions::IMPOWER($complexNumber, $realNumber);
-        $realNumber = Functions::flattenSingleValue($realNumber);
-
-        if (!is_numeric($realNumber)) {
-            return Functions::VALUE();
-        }
-
-        return (string) (new Complex($complexNumber))->pow($realNumber);
     }
 
     /**
@@ -1017,6 +1027,10 @@ class Engineering
      * Excel Function:
      *        IMDIV(complexDividend,complexDivisor)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMDIV() method in the Engineering\ComplexOperations class instead
+     *
      * @param string $complexDividend the complex numerator or dividend
      * @param string $complexDivisor the complex denominator or divisor
      *
@@ -1024,14 +1038,7 @@ class Engineering
      */
     public static function IMDIV($complexDividend, $complexDivisor)
     {
-        $complexDividend = Functions::flattenSingleValue($complexDividend);
+        return ComplexOperations::IMDIV($complexDividend, $complexDivisor);
-        $complexDivisor = Functions::flattenSingleValue($complexDivisor);
-
-        try {
-            return (string) (new Complex($complexDividend))->divideby(new Complex($complexDivisor));
-        } catch (ComplexException $e) {
-            return Functions::NAN();
-        }
     }
 
     /**
@@ -1042,6 +1049,10 @@ class Engineering
      * Excel Function:
      *        IMSUB(complexNumber1,complexNumber2)
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMSUB() method in the Engineering\ComplexOperations class instead
+     *
      * @param string $complexNumber1 the complex number from which to subtract complexNumber2
      * @param string $complexNumber2 the complex number to subtract from complexNumber1
      *
@@ -1049,14 +1060,7 @@ class Engineering
      */
     public static function IMSUB($complexNumber1, $complexNumber2)
     {
-        $complexNumber1 = Functions::flattenSingleValue($complexNumber1);
+        return ComplexOperations::IMSUB($complexNumber1, $complexNumber2);
-        $complexNumber2 = Functions::flattenSingleValue($complexNumber2);
-
-        try {
-            return (string) (new Complex($complexNumber1))->subtract(new Complex($complexNumber2));
-        } catch (ComplexException $e) {
-            return Functions::NAN();
-        }
     }
 
     /**
@@ -1067,26 +1071,17 @@ class Engineering
      * Excel Function:
      *        IMSUM(complexNumber[,complexNumber[,...]])
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMSUM() method in the Engineering\ComplexOperations class instead
+     *
      * @param string ...$complexNumbers Series of complex numbers to add
      *
      * @return string
      */
     public static function IMSUM(...$complexNumbers)
     {
-        // Return value
+        return ComplexOperations::IMSUM(...$complexNumbers);
-        $returnValue = new Complex(0.0);
-        $aArgs = Functions::flattenArray($complexNumbers);
-
-        try {
-            // Loop through the arguments
-            foreach ($aArgs as $complex) {
-                $returnValue = $returnValue->add(new Complex($complex));
-            }
-        } catch (ComplexException $e) {
-            return Functions::NAN();
-        }
-
-        return (string) $returnValue;
     }
 
     /**
@@ -1097,26 +1092,17 @@ class Engineering
      * Excel Function:
      *        IMPRODUCT(complexNumber[,complexNumber[,...]])
      *
+     * @Deprecated 1.18.0
+     *
+     * @see Use the IMPRODUCT() method in the Engineering\ComplexOperations class instead
+     *
      * @param string ...$complexNumbers Series of complex numbers to multiply
      *
      * @return string
      */
     public static function IMPRODUCT(...$complexNumbers)
     {
-        // Return value
+        return ComplexOperations::IMPRODUCT(...$complexNumbers);
-        $returnValue = new Complex(1.0);
-        $aArgs = Functions::flattenArray($complexNumbers);
-
-        try {
-            // Loop through the arguments
-            foreach ($aArgs as $complex) {
-                $returnValue = $returnValue->multiply(new Complex($complex));
-            }
-        } catch (ComplexException $e) {
-            return Functions::NAN();
-        }
-
-        return (string) $returnValue;
     }
 
     /**

src/PhpSpreadsheet/Calculation/Engineering/Complex.php

@@ -0,0 +1,94 @@
+<?php
+
+namespace PhpOffice\PhpSpreadsheet\Calculation\Engineering;
+
+use Complex\Complex as ComplexObject;
+use Complex\Exception as ComplexException;
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
+class Complex
+{
+    /**
+     * COMPLEX.
+     *
+     * Converts real and imaginary coefficients into a complex number of the form x +/- yi or x +/- yj.
+     *
+     * Excel Function:
+     *        COMPLEX(realNumber,imaginary[,suffix])
+     *
+     * @param float $realNumber the real coefficient of the complex number
+     * @param float $imaginary the imaginary coefficient of the complex number
+     * @param string $suffix The suffix for the imaginary component of the complex number.
+     *                                        If omitted, the suffix is assumed to be "i".
+     *
+     * @return string
+     */
+    public static function COMPLEX($realNumber = 0.0, $imaginary = 0.0, $suffix = 'i')
+    {
+        $realNumber = ($realNumber === null) ? 0.0 : Functions::flattenSingleValue($realNumber);
+        $imaginary = ($imaginary === null) ? 0.0 : Functions::flattenSingleValue($imaginary);
+        $suffix = ($suffix === null) ? 'i' : Functions::flattenSingleValue($suffix);
+
+        if (
+            ((is_numeric($realNumber)) && (is_numeric($imaginary))) &&
+            (($suffix == 'i') || ($suffix == 'j') || ($suffix == ''))
+        ) {
+            $complex = new ComplexObject($realNumber, $imaginary, $suffix);
+
+            return (string) $complex;
+        }
+
+        return Functions::VALUE();
+    }
+
+    /**
+     * IMAGINARY.
+     *
+     * Returns the imaginary coefficient of a complex number in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMAGINARY(complexNumber)
+     *
+     * @param string $complexNumber the complex number for which you want the imaginary
+     *                                         coefficient
+     *
+     * @return float|string
+     */
+    public static function IMAGINARY($complexNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        return $complex->getImaginary();
+    }
+
+    /**
+     * IMREAL.
+     *
+     * Returns the real coefficient of a complex number in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMREAL(complexNumber)
+     *
+     * @param string $complexNumber the complex number for which you want the real coefficient
+     *
+     * @return float|string
+     */
+    public static function IMREAL($complexNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        return $complex->getReal();
+    }
+}

src/PhpSpreadsheet/Calculation/Engineering/ComplexFunctions.php

@@ -0,0 +1,513 @@
+<?php
+
+namespace PhpOffice\PhpSpreadsheet\Calculation\Engineering;
+
+use Complex\Complex as ComplexObject;
+use Complex\Exception as ComplexException;
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
+class ComplexFunctions
+{
+    /**
+     * IMABS.
+     *
+     * Returns the absolute value (modulus) of a complex number in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMABS(complexNumber)
+     *
+     * @param string $complexNumber the complex number for which you want the absolute value
+     *
+     * @return float|string
+     */
+    public static function IMABS($complexNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        return $complex->abs();
+    }
+
+    /**
+     * IMARGUMENT.
+     *
+     * Returns the argument theta of a complex number, i.e. the angle in radians from the real
+     * axis to the representation of the number in polar coordinates.
+     *
+     * Excel Function:
+     *        IMARGUMENT(complexNumber)
+     *
+     * @param string $complexNumber the complex number for which you want the argument theta
+     *
+     * @return float|string
+     */
+    public static function IMARGUMENT($complexNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        if ($complex->getReal() == 0.0 && $complex->getImaginary() == 0.0) {
+            return Functions::DIV0();
+        }
+
+        return $complex->argument();
+    }
+
+    /**
+     * IMCONJUGATE.
+     *
+     * Returns the complex conjugate of a complex number in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMCONJUGATE(complexNumber)
+     *
+     * @param string $complexNumber the complex number for which you want the conjugate
+     *
+     * @return string
+     */
+    public static function IMCONJUGATE($complexNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        return (string) $complex->conjugate();
+    }
+
+    /**
+     * IMCOS.
+     *
+     * Returns the cosine of a complex number in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMCOS(complexNumber)
+     *
+     * @param string $complexNumber the complex number for which you want the cosine
+     *
+     * @return float|string
+     */
+    public static function IMCOS($complexNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        return (string) $complex->cos();
+    }
+
+    /**
+     * IMCOSH.
+     *
+     * Returns the hyperbolic cosine of a complex number in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMCOSH(complexNumber)
+     *
+     * @param string $complexNumber the complex number for which you want the hyperbolic cosine
+     *
+     * @return float|string
+     */
+    public static function IMCOSH($complexNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        return (string) $complex->cosh();
+    }
+
+    /**
+     * IMCOT.
+     *
+     * Returns the cotangent of a complex number in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMCOT(complexNumber)
+     *
+     * @param string $complexNumber the complex number for which you want the cotangent
+     *
+     * @return float|string
+     */
+    public static function IMCOT($complexNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        return (string) $complex->cot();
+    }
+
+    /**
+     * IMCSC.
+     *
+     * Returns the cosecant of a complex number in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMCSC(complexNumber)
+     *
+     * @param string $complexNumber the complex number for which you want the cosecant
+     *
+     * @return float|string
+     */
+    public static function IMCSC($complexNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        return (string) $complex->csc();
+    }
+
+    /**
+     * IMCSCH.
+     *
+     * Returns the hyperbolic cosecant of a complex number in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMCSCH(complexNumber)
+     *
+     * @param string $complexNumber the complex number for which you want the hyperbolic cosecant
+     *
+     * @return float|string
+     */
+    public static function IMCSCH($complexNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        return (string) $complex->csch();
+    }
+
+    /**
+     * IMSIN.
+     *
+     * Returns the sine of a complex number in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMSIN(complexNumber)
+     *
+     * @param string $complexNumber the complex number for which you want the sine
+     *
+     * @return float|string
+     */
+    public static function IMSIN($complexNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        return (string) $complex->sin();
+    }
+
+    /**
+     * IMSINH.
+     *
+     * Returns the hyperbolic sine of a complex number in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMSINH(complexNumber)
+     *
+     * @param string $complexNumber the complex number for which you want the hyperbolic sine
+     *
+     * @return float|string
+     */
+    public static function IMSINH($complexNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        return (string) $complex->sinh();
+    }
+
+    /**
+     * IMSEC.
+     *
+     * Returns the secant of a complex number in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMSEC(complexNumber)
+     *
+     * @param string $complexNumber the complex number for which you want the secant
+     *
+     * @return float|string
+     */
+    public static function IMSEC($complexNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        return (string) $complex->sec();
+    }
+
+    /**
+     * IMSECH.
+     *
+     * Returns the hyperbolic secant of a complex number in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMSECH(complexNumber)
+     *
+     * @param string $complexNumber the complex number for which you want the hyperbolic secant
+     *
+     * @return float|string
+     */
+    public static function IMSECH($complexNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        return (string) $complex->sech();
+    }
+
+    /**
+     * IMTAN.
+     *
+     * Returns the tangent of a complex number in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMTAN(complexNumber)
+     *
+     * @param string $complexNumber the complex number for which you want the tangent
+     *
+     * @return float|string
+     */
+    public static function IMTAN($complexNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        return (string) $complex->tan();
+    }
+
+    /**
+     * IMSQRT.
+     *
+     * Returns the square root of a complex number in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMSQRT(complexNumber)
+     *
+     * @param string $complexNumber the complex number for which you want the square root
+     *
+     * @return string
+     */
+    public static function IMSQRT($complexNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        $theta = self::IMARGUMENT($complexNumber);
+        if ($theta === Functions::DIV0()) {
+            return '0';
+        }
+
+        return (string) $complex->sqrt();
+    }
+
+    /**
+     * IMLN.
+     *
+     * Returns the natural logarithm of a complex number in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMLN(complexNumber)
+     *
+     * @param string $complexNumber the complex number for which you want the natural logarithm
+     *
+     * @return string
+     */
+    public static function IMLN($complexNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        if ($complex->getReal() == 0.0 && $complex->getImaginary() == 0.0) {
+            return Functions::NAN();
+        }
+
+        return (string) $complex->ln();
+    }
+
+    /**
+     * IMLOG10.
+     *
+     * Returns the common logarithm (base 10) of a complex number in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMLOG10(complexNumber)
+     *
+     * @param string $complexNumber the complex number for which you want the common logarithm
+     *
+     * @return string
+     */
+    public static function IMLOG10($complexNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        if ($complex->getReal() == 0.0 && $complex->getImaginary() == 0.0) {
+            return Functions::NAN();
+        }
+
+        return (string) $complex->log10();
+    }
+
+    /**
+     * IMLOG2.
+     *
+     * Returns the base-2 logarithm of a complex number in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMLOG2(complexNumber)
+     *
+     * @param string $complexNumber the complex number for which you want the base-2 logarithm
+     *
+     * @return string
+     */
+    public static function IMLOG2($complexNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        if ($complex->getReal() == 0.0 && $complex->getImaginary() == 0.0) {
+            return Functions::NAN();
+        }
+
+        return (string) $complex->log2();
+    }
+
+    /**
+     * IMEXP.
+     *
+     * Returns the exponential of a complex number in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMEXP(complexNumber)
+     *
+     * @param string $complexNumber the complex number for which you want the exponential
+     *
+     * @return string
+     */
+    public static function IMEXP($complexNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        return (string) $complex->exp();
+    }
+
+    /**
+     * IMPOWER.
+     *
+     * Returns a complex number in x + yi or x + yj text format raised to a power.
+     *
+     * Excel Function:
+     *        IMPOWER(complexNumber,realNumber)
+     *
+     * @param string $complexNumber the complex number you want to raise to a power
+     * @param float $realNumber the power to which you want to raise the complex number
+     *
+     * @return string
+     */
+    public static function IMPOWER($complexNumber, $realNumber)
+    {
+        $complexNumber = Functions::flattenSingleValue($complexNumber);
+        $realNumber = Functions::flattenSingleValue($realNumber);
+
+        try {
+            $complex = new ComplexObject($complexNumber);
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        if (!is_numeric($realNumber)) {
+            return Functions::VALUE();
+        }
+
+        return (string) $complex->pow($realNumber);
+    }
+}

src/PhpSpreadsheet/Calculation/Engineering/ComplexOperations.php

@@ -0,0 +1,120 @@
+<?php
+
+namespace PhpOffice\PhpSpreadsheet\Calculation\Engineering;
+
+use Complex\Complex as ComplexObject;
+use Complex\Exception as ComplexException;
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
+class ComplexOperations
+{
+    /**
+     * IMDIV.
+     *
+     * Returns the quotient of two complex numbers in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMDIV(complexDividend,complexDivisor)
+     *
+     * @param string $complexDividend the complex numerator or dividend
+     * @param string $complexDivisor the complex denominator or divisor
+     *
+     * @return string
+     */
+    public static function IMDIV($complexDividend, $complexDivisor)
+    {
+        $complexDividend = Functions::flattenSingleValue($complexDividend);
+        $complexDivisor = Functions::flattenSingleValue($complexDivisor);
+
+        try {
+            return (string) (new ComplexObject($complexDividend))->divideby(new ComplexObject($complexDivisor));
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+    }
+
+    /**
+     * IMSUB.
+     *
+     * Returns the difference of two complex numbers in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMSUB(complexNumber1,complexNumber2)
+     *
+     * @param string $complexNumber1 the complex number from which to subtract complexNumber2
+     * @param string $complexNumber2 the complex number to subtract from complexNumber1
+     *
+     * @return string
+     */
+    public static function IMSUB($complexNumber1, $complexNumber2)
+    {
+        $complexNumber1 = Functions::flattenSingleValue($complexNumber1);
+        $complexNumber2 = Functions::flattenSingleValue($complexNumber2);
+
+        try {
+            return (string) (new ComplexObject($complexNumber1))->subtract(new ComplexObject($complexNumber2));
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+    }
+
+    /**
+     * IMSUM.
+     *
+     * Returns the sum of two or more complex numbers in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMSUM(complexNumber[,complexNumber[,...]])
+     *
+     * @param string ...$complexNumbers Series of complex numbers to add
+     *
+     * @return string
+     */
+    public static function IMSUM(...$complexNumbers)
+    {
+        // Return value
+        $returnValue = new ComplexObject(0.0);
+        $aArgs = Functions::flattenArray($complexNumbers);
+
+        try {
+            // Loop through the arguments
+            foreach ($aArgs as $complex) {
+                $returnValue = $returnValue->add(new ComplexObject($complex));
+            }
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        return (string) $returnValue;
+    }
+
+    /**
+     * IMPRODUCT.
+     *
+     * Returns the product of two or more complex numbers in x + yi or x + yj text format.
+     *
+     * Excel Function:
+     *        IMPRODUCT(complexNumber[,complexNumber[,...]])
+     *
+     * @param string ...$complexNumbers Series of complex numbers to multiply
+     *
+     * @return string
+     */
+    public static function IMPRODUCT(...$complexNumbers)
+    {
+        // Return value
+        $returnValue = new ComplexObject(1.0);
+        $aArgs = Functions::flattenArray($complexNumbers);
+
+        try {
+            // Loop through the arguments
+            foreach ($aArgs as $complex) {
+                $returnValue = $returnValue->multiply(new ComplexObject($complex));
+            }
+        } catch (ComplexException $e) {
+            return Functions::NAN();
+        }
+
+        return (string) $returnValue;
+    }
+}

src/PhpSpreadsheet/Calculation/Engineering/Constants.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace PhpOffice\PhpSpreadsheet\Calculation\Engineering;
+
+class Constants
+{
+    /**
+     * EULER.
+     */
+    public const EULER = 2.71828182845904523536;
+}

tests/data/Calculation/Engineering/COMPLEX.php

@@ -1,5 +1,7 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         '3+4i',
@@ -14,8 +16,16 @@ return [
         12.34, 5.6699999999999999, 'j',
     ],
     [
-        '#VALUE!',
+        Functions::VALUE(),
-        3.5, 'A',
+        3.5, 'NaN',
+    ],
+    [
+        Functions::VALUE(),
+        'NaN', 3.5,
+    ],
+    [
+        Functions::VALUE(),
+        1.5, 3.5, 'invalid suffix',
     ],
     [
         '1.234E-5+6780000000i',

tests/data/Calculation/Engineering/IMABS.php

@@ -1,10 +1,16 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         13.58029822942,
         '12.34+5.67j',
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+    ],
     [
         6780000000.0,
         '1.234E-5+6.78E9i',

tests/data/Calculation/Engineering/IMAGINARY.php

@@ -1,5 +1,7 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         5.6699999999999999,
@@ -121,4 +123,8 @@ return [
         -2.5,
         '-3.5-2.5i',
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+    ],
 ];

tests/data/Calculation/Engineering/IMARGUMENT.php

@@ -1,10 +1,16 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         0.43071059555000002,
         '12.34+5.67j',
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+    ],
     [
         0.620249485983,
         '3.5+2.5i',

tests/data/Calculation/Engineering/IMCONJUGATE.php

@@ -1,10 +1,16 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         '12.34-5.67j',
         '12.34+5.67j',
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+    ],
     [
         '3.5-2.5i',
         '3.5+2.5i',

tests/data/Calculation/Engineering/IMCOS.php

@@ -1,10 +1,16 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         '141.319179436356+32.547610312508j',
         '12.34+5.67j',
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+    ],
     [
         '-5.74262349163406+2.12231025604134i',
         '3.5+2.5i',

tests/data/Calculation/Engineering/IMCOSH.php

@@ -1,10 +1,16 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         '93502.0563713182121-65794.6618967782119j',
         '12.34+5.67j',
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+    ],
     [
         '-13.2772126767962807+9.90030162194353525i',
         '3.5+2.5i',

tests/data/Calculation/Engineering/IMCOT.php

@@ -1,10 +1,16 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         '-0.0000104004141424230319-1.00002138037057154j',
         '12.34+5.67j',
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+    ],
     [
         '0.00894394174578834370-1.01017158348808170i',
         '3.5+2.5i',

tests/data/Calculation/Engineering/IMCSC.php

@@ -1,10 +1,16 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         '-0.00154774455592154432-0.00671986631601416928j',
         '12.34+5.67j',
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+    ],
     [
         '-0.0585684747824233590+0.154262439469903774i',
         '3.5+2.5i',

tests/data/Calculation/Engineering/IMCSCH.php

@@ -1,10 +1,16 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         '7.15308425027293823E-6+5.03341614148979354E-6j',
         '12.34+5.67j',
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+    ],
     [
         '-0.0483657415388563464-0.0361962406084861128i',
         '3.5+2.5i',

tests/data/Calculation/Engineering/IMDIV.php

@@ -1,11 +1,18 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
-        '#NUM!',
+        Functions::NAN(),
         '12.34+5.67j',
         '123.45+67.89i',
     ],
+    [
+        Functions::NAN(),
+        '12.34+5.67j',
+        'Invalid Complex Number',
+    ],
     [
         '0.0961415519586104-0.00694248653276682j',
         '12.34+5.67j',

tests/data/Calculation/Engineering/IMEXP.php

@@ -1,10 +1,16 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         '187004.11273906-131589.323796073j',
         '12.34+5.67j',
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+    ],
     [
         '0.519482808316086+0.85433649244115i',
         '-12.34E-5+6.78E9i',

tests/data/Calculation/Engineering/IMLN.php

@@ -1,10 +1,16 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         '2.60862008281875+0.430710595550204j',
         '12.34+5.67j',
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+    ],
     [
         '22.6372429388987+1.5707963267949i',
         '-1.234E-5+6.78E9i',
@@ -58,7 +64,7 @@ return [
         'i',
     ],
     [
-        '#NUM!',
+        Functions::NAN(),
         '0',
     ],
     [

tests/data/Calculation/Engineering/IMLOG10.php

@@ -1,10 +1,16 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         '1.13290930735019+0.187055234944717j',
         '12.34+5.67j',
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+    ],
     [
         '9.83122969386706+0.682188176920927i',
         '-12.34E-5+6.78E9i',
@@ -58,7 +64,7 @@ return [
         'i',
     ],
     [
-        '#NUM!',
+        Functions::NAN(),
         '0',
     ],
     [

tests/data/Calculation/Engineering/IMLOG2.php

@@ -1,10 +1,16 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         '3.76344325733562+0.621384040306436j',
         '12.34+5.67j',
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+    ],
     [
         '32.6586381298614+2.26618007108803i',
         '-12.34E-5+6.78E9i',
@@ -58,7 +64,7 @@ return [
         'i',
     ],
     [
-        '#NUM!',
+        Functions::NAN(),
         '0',
     ],
     [

tests/data/Calculation/Engineering/IMPOWER.php

@@ -1,11 +1,18 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         '120.1267+139.9356j',
         '12.34+5.67j',
         2,
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+        2,
+    ],
     [
         '688.928626+2407.923693j',
         '12.34+5.67j',
@@ -57,7 +64,7 @@ return [
         '2.5',
     ],
     [
-        '#VALUE!',
+        Functions::VALUE(),
         '2.5i',
         '2.5i',
     ],

tests/data/Calculation/Engineering/IMPRODUCT.php

@@ -1,11 +1,18 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
-        '#NUM!',
+        Functions::NAN(),
         '12.34+5.67j',
         '123.45+67.89i',
     ],
+    [
+        Functions::NAN(),
+        '12.34+5.67j',
+        'Invalid Complex Number',
+    ],
     [
         '12.34+5.67j',
         '12.34+5.67j',

tests/data/Calculation/Engineering/IMREAL.php

@@ -1,5 +1,7 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         12.34,
@@ -121,4 +123,8 @@ return [
         -3.5,
         '-3.5-2.5i',
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+    ],
 ];

tests/data/Calculation/Engineering/IMSEC.php

@@ -1,10 +1,16 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         '0.00671973874162309199-0.00154764157870523791j',
         '12.34+5.67j',
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+    ],
     [
         '-0.153210472299609239-0.0566222314884645297i',
         '3.5+2.5i',

tests/data/Calculation/Engineering/IMSECH.php

@@ -1,10 +1,16 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         '7.15308425036177674E-6+5.03341614116724074E-6j',
         '12.34+5.67j',
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+    ],
     [
         '-0.0484039219824442559-0.0360929239424409676i',
         '3.5+2.5i',

tests/data/Calculation/Engineering/IMSIN.php

@@ -1,10 +1,16 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         '-32.5483841590412+141.315819535092j',
         '12.34+5.67j',
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+    ],
     [
         '-2.15110429680353-5.66575444574645i',
         '3.5+2.5i',

tests/data/Calculation/Engineering/IMSINH.php

@@ -1,10 +1,16 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         '93502.0563677416700-65794.6618992949199j',
         '12.34+5.67j',
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+    ],
     [
         '-13.2530202358612674+9.91837391474661948i',
         '3.5+2.5i',

tests/data/Calculation/Engineering/IMSQRT.php

@@ -1,10 +1,16 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         '3.60002071031685+0.787495469644252j',
         '12.34+5.67j',
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+    ],
     [
         '58223.7065120385+58223.7065120386i',
         '-1.234E-5+6.78E9i',

tests/data/Calculation/Engineering/IMSUB.php

@@ -1,11 +1,18 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
-        '#NUM!',
+        Functions::NAN(),
         '12.34+5.67j',
         '123.45+67.89i',
     ],
+    [
+        Functions::NAN(),
+        '12.34+5.67j',
+        'Invalid Complex Number',
+    ],
     [
         '111.11+62.22j',
         '123.45+67.89j',

tests/data/Calculation/Engineering/IMSUM.php

@@ -1,11 +1,18 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
-        '#NUM!',
+        Functions::NAN(),
         '12.34+5.67j',
         '123.45+67.89i',
     ],
+    [
+        Functions::NAN(),
+        '12.34+5.67j',
+        'Invalid Complex Number',
+    ],
     [
         '135.79+73.56j',
         '12.34+5.67j',
@@ -33,7 +40,7 @@ return [
         '123.45+67.89i',
     ],
     [
-        '#NUM!',
+        Functions::NAN(),
         '12.34+5.67i',
         '123.45+67.89i',
         '123.45+67.89j',

tests/data/Calculation/Engineering/IMTAN.php

@@ -1,10 +1,16 @@
 <?php
 
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+
 return [
     [
         '-0.0000103999694261435177+0.999978619978377253j',
         '12.34+5.67j',
     ],
+    [
+        Functions::NAN(),
+        'Invalid Complex Number',
+    ],
     [
         '0.00876404549513463160+0.989853240015864536i',
         '3.5+2.5i',