Merge pull request #2580 from PHPOffice/Issue-2551-Array-Ready-Functi…

…on-Financial

Issue 2551 - array ready functions - Text (phase #1)

phpstan-baseline.neon

@@ -927,7 +927,12 @@ parameters:
 
 		-
 			message: "#^Parameter \\#1 \\$year of static method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\Financial\\\\Helpers\\:\\:daysPerYear\\(\\) expects int\\|string, array\\|int\\|string given\\.$#"
-			count: 3
+			count: 1
+			path: src/PhpSpreadsheet/Calculation/Financial/Coupons.php
+
+		-
+			message: "#^Parameter \\#1 \\$year of static method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\Financial\\\\Helpers\\:\\:daysPerYear\\(\\) expects int\\|string, mixed given\\.$#"
+			count: 2
 			path: src/PhpSpreadsheet/Calculation/Financial/Coupons.php
 
 		-
@@ -961,12 +966,12 @@ parameters:
 			path: src/PhpSpreadsheet/Calculation/Financial/Depreciation.php
 
 		-
-			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\Financial\\\\Securities\\\\AccruedInterest\\:\\:atMaturity\\(\\) should return float\\|string but returns array\\|string\\.$#"
+			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\Financial\\\\Securities\\\\AccruedInterest\\:\\:atMaturity\\(\\) should return float\\|string but returns mixed\\.$#"
 			count: 1
 			path: src/PhpSpreadsheet/Calculation/Financial/Securities/AccruedInterest.php
 
 		-
-			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\Financial\\\\Securities\\\\AccruedInterest\\:\\:periodic\\(\\) should return float\\|string but returns array\\|string\\.$#"
+			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\Financial\\\\Securities\\\\AccruedInterest\\:\\:periodic\\(\\) should return float\\|string but returns mixed\\.$#"
 			count: 2
 			path: src/PhpSpreadsheet/Calculation/Financial/Securities/AccruedInterest.php
 
@@ -976,12 +981,12 @@ parameters:
 			path: src/PhpSpreadsheet/Calculation/Financial/Securities/Price.php
 
 		-
-			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\Financial\\\\Securities\\\\Price\\:\\:priceAtMaturity\\(\\) should return float\\|string but returns array\\|string\\.$#"
-			count: 3
+			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\Financial\\\\Securities\\\\Price\\:\\:priceAtMaturity\\(\\) should return float\\|string but returns mixed\\.$#"
+			count: 4
 			path: src/PhpSpreadsheet/Calculation/Financial/Securities/Price.php
 
 		-
-			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\Financial\\\\Securities\\\\Price\\:\\:priceDiscounted\\(\\) should return float\\|string but returns array\\|string\\.$#"
+			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\Financial\\\\Securities\\\\Price\\:\\:priceDiscounted\\(\\) should return float\\|string but returns mixed\\.$#"
 			count: 1
 			path: src/PhpSpreadsheet/Calculation/Financial/Securities/Price.php
 
@@ -996,22 +1001,22 @@ parameters:
 			path: src/PhpSpreadsheet/Calculation/Financial/Securities/Price.php
 
 		-
-			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\Financial\\\\Securities\\\\Rates\\:\\:discount\\(\\) should return float\\|string but returns array\\|string\\.$#"
+			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\Financial\\\\Securities\\\\Rates\\:\\:discount\\(\\) should return float\\|string but returns mixed\\.$#"
 			count: 1
 			path: src/PhpSpreadsheet/Calculation/Financial/Securities/Rates.php
 
 		-
-			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\Financial\\\\Securities\\\\Rates\\:\\:interest\\(\\) should return float\\|string but returns array\\|string\\.$#"
+			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\Financial\\\\Securities\\\\Rates\\:\\:interest\\(\\) should return float\\|string but returns mixed\\.$#"
 			count: 1
 			path: src/PhpSpreadsheet/Calculation/Financial/Securities/Rates.php
 
 		-
-			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\Financial\\\\Securities\\\\Yields\\:\\:yieldAtMaturity\\(\\) should return float\\|string but returns array\\|string\\.$#"
+			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\Financial\\\\Securities\\\\Yields\\:\\:yieldAtMaturity\\(\\) should return float\\|string but returns mixed\\.$#"
 			count: 3
 			path: src/PhpSpreadsheet/Calculation/Financial/Securities/Yields.php
 
 		-
-			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\Financial\\\\Securities\\\\Yields\\:\\:yieldDiscounted\\(\\) should return float\\|string but returns array\\|string\\.$#"
+			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\Financial\\\\Securities\\\\Yields\\:\\:yieldDiscounted\\(\\) should return float\\|string but returns mixed\\.$#"
 			count: 1
 			path: src/PhpSpreadsheet/Calculation/Financial/Securities/Yields.php
 
@@ -1021,7 +1026,7 @@ parameters:
 			path: src/PhpSpreadsheet/Calculation/Financial/Securities/Yields.php
 
 		-
-			message: "#^Parameter \\#1 \\$year of static method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\Financial\\\\Helpers\\:\\:daysPerYear\\(\\) expects int\\|string, array\\|int\\|string given\\.$#"
+			message: "#^Parameter \\#1 \\$year of static method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\Financial\\\\Helpers\\:\\:daysPerYear\\(\\) expects int\\|string, mixed given\\.$#"
 			count: 3
 			path: src/PhpSpreadsheet/Calculation/Financial/TreasuryBill.php
 
@@ -1925,21 +1930,6 @@ parameters:
 			count: 1
 			path: src/PhpSpreadsheet/Calculation/TextData.php
 
-		-
-			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\TextData\\:\\:SEARCHINSENSITIVE\\(\\) should return string but returns int\\|string\\.$#"
-			count: 1
-			path: src/PhpSpreadsheet/Calculation/TextData.php
-
-		-
-			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\TextData\\:\\:SEARCHSENSITIVE\\(\\) should return string but returns int\\|string\\.$#"
-			count: 1
-			path: src/PhpSpreadsheet/Calculation/TextData.php
-
-		-
-			message: "#^Method PhpOffice\\\\PhpSpreadsheet\\\\Calculation\\\\TextData\\:\\:TRIMNONPRINTABLE\\(\\) should return string but returns string\\|null\\.$#"
-			count: 1
-			path: src/PhpSpreadsheet/Calculation/TextData.php
-
 		-
 			message: "#^Parameter \\#1 \\$glue of function implode expects string, mixed given\\.$#"
 			count: 1

src/PhpSpreadsheet/Calculation/DateTimeExcel/NetworkDays.php

@@ -30,6 +30,8 @@ class NetworkDays
      * @param mixed $dateArgs An array of dates (such as holidays) to exclude from the calculation
      *
      * @return array|int|string Interval between the dates
+     *         If an array of values is passed for the $startDate or $endDate arguments, then the returned result
+     *            will also be an array with matching dimensions
      */
     public static function count($startDate, $endDate, ...$dateArgs)
     {

src/PhpSpreadsheet/Calculation/DateTimeExcel/YearFrac.php

@@ -26,7 +26,7 @@ class YearFrac
      *
      * @param mixed $startDate Excel date serial value (float), PHP date timestamp (integer),
      *                                    PHP DateTime object, or a standard date string
-     *                         Or can be an array of methods
+     *                         Or can be an array of values
      * @param mixed $endDate Excel date serial value (float), PHP date timestamp (integer),
      *                                    PHP DateTime object, or a standard date string
      *                         Or can be an array of methods

src/PhpSpreadsheet/Calculation/Financial.php

@@ -587,10 +587,10 @@ public static function DISC($settlement, $maturity, $price, $redemption, $basis
      * @see Financial\Dollar::decimal()
      *      Use the decimal() method in the Financial\Dollar class instead
      *
-     * @param float $fractional_dollar Fractional Dollar
-     * @param int $fraction Fraction
+     * @param array|float $fractional_dollar Fractional Dollar
+     * @param array|int $fraction Fraction
      *
-     * @return float|string
+     * @return array|float|string
      */
     public static function DOLLARDE($fractional_dollar = null, $fraction = 0)
     {
@@ -612,10 +612,10 @@ public static function DOLLARDE($fractional_dollar = null, $fraction = 0)
      * @see Financial\Dollar::fractional()
      *      Use the fractional() method in the Financial\Dollar class instead
      *
-     * @param float $decimal_dollar Decimal Dollar
-     * @param int $fraction Fraction
+     * @param array|float $decimal_dollar Decimal Dollar
+     * @param array|int $fraction Fraction
      *
-     * @return float|string
+     * @return array|float|string
      */
     public static function DOLLARFR($decimal_dollar = null, $fraction = 0)
     {

src/PhpSpreadsheet/Calculation/Financial/Amortization.php

@@ -168,7 +168,7 @@ public static function AMORLINC(
 
         if (
             ($basis == FinancialConstants::BASIS_DAYS_PER_YEAR_ACTUAL) &&
-            ($yearFrac < 1) && (DateTimeExcel\Helpers::isLeapYear($purchasedYear))
+            ($yearFrac < 1) && (Functions::scalar(DateTimeExcel\Helpers::isLeapYear($purchasedYear)))
         ) {
             $yearFrac *= 365 / 366;
         }

src/PhpSpreadsheet/Calculation/Financial/Coupons.php

@@ -64,7 +64,7 @@ public static function COUPDAYBS(
             return $e->getMessage();
         }
 
-        $daysPerYear = Helpers::daysPerYear(DateTimeExcel\DateParts::year($settlement), $basis);
+        $daysPerYear = Helpers::daysPerYear(Functions::scalar(DateTimeExcel\DateParts::year($settlement)), $basis);
         if (is_string($daysPerYear)) {
             return Functions::VALUE();
         }
@@ -134,7 +134,7 @@ public static function COUPDAYS(
             case FinancialConstants::BASIS_DAYS_PER_YEAR_ACTUAL:
                 // Actual/actual
                 if ($frequency == FinancialConstants::FREQUENCY_ANNUAL) {
-                    $daysPerYear = (int) Helpers::daysPerYear(DateTimeExcel\DateParts::year($settlement), $basis);
+                    $daysPerYear = (int) Helpers::daysPerYear(Functions::scalar(DateTimeExcel\DateParts::year($settlement)), $basis);
 
                     return $daysPerYear / $frequency;
                 }

src/PhpSpreadsheet/Calculation/Financial/Dollar.php

@@ -2,22 +2,26 @@
 
 namespace PhpOffice\PhpSpreadsheet\Calculation\Financial;
 
+use PhpOffice\PhpSpreadsheet\Calculation\ArrayEnabled;
 use PhpOffice\PhpSpreadsheet\Calculation\Exception;
 use PhpOffice\PhpSpreadsheet\Calculation\Functions;
 use PhpOffice\PhpSpreadsheet\Calculation\TextData\Format;
 
 class Dollar
 {
+    use ArrayEnabled;
+
     /**
      * DOLLAR.
      *
      * This function converts a number to text using currency format, with the decimals rounded to the specified place.
      * The format used is $#,##0.00_);($#,##0.00)..
      *
-     * @param mixed $number The value to format
+     * @param mixed $number The value to format, or can be an array of numbers
      * @param mixed $precision The number of digits to display to the right of the decimal point (as an integer).
      *                            If precision is negative, number is rounded to the left of the decimal point.
      *                            If you omit precision, it is assumed to be 2
+     *              Or can be an array of precision values
      */
     public static function format($number, $precision = 2): string
     {
@@ -35,12 +39,18 @@ public static function format($number, $precision = 2): string
      *        DOLLARDE(fractional_dollar,fraction)
      *
      * @param mixed $fractionalDollar Fractional Dollar
+     *              Or can be an array of values
      * @param mixed $fraction Fraction
+     *              Or can be an array of values
      *
-     * @return float|string
+     * @return array|float|string
      */
     public static function decimal($fractionalDollar = null, $fraction = 0)
     {
+        if (is_array($fractionalDollar) || is_array($fraction)) {
+            return self::evaluateArrayArguments([self::class, __FUNCTION__], $fractionalDollar, $fraction);
+        }
+
         try {
             $fractionalDollar = FinancialValidations::validateFloat(
                 Functions::flattenSingleValue($fractionalDollar) ?? 0.0
@@ -58,8 +68,8 @@ public static function decimal($fractionalDollar = null, $fraction = 0)
             return Functions::DIV0();
         }
 
-        $dollars = ($fractionalDollar < 0.0) ? ceil($fractionalDollar) : floor($fractionalDollar);
-        $cents = fmod($fractionalDollar, 1);
+        $dollars = ($fractionalDollar < 0) ? ceil($fractionalDollar) : floor($fractionalDollar);
+        $cents = fmod($fractionalDollar, 1.0);
         $cents /= $fraction;
         $cents *= 10 ** ceil(log10($fraction));
 
@@ -77,12 +87,18 @@ public static function decimal($fractionalDollar = null, $fraction = 0)
      *        DOLLARFR(decimal_dollar,fraction)
      *
      * @param mixed $decimalDollar Decimal Dollar
+     *              Or can be an array of values
      * @param mixed $fraction Fraction
+     *              Or can be an array of values
      *
-     * @return float|string
+     * @return array|float|string
      */
     public static function fractional($decimalDollar = null, $fraction = 0)
     {
+        if (is_array($decimalDollar) || is_array($fraction)) {
+            return self::evaluateArrayArguments([self::class, __FUNCTION__], $decimalDollar, $fraction);
+        }
+
         try {
             $decimalDollar = FinancialValidations::validateFloat(
                 Functions::flattenSingleValue($decimalDollar) ?? 0.0

src/PhpSpreadsheet/Calculation/Financial/Securities/AccruedInterest.php

@@ -78,12 +78,12 @@ public static function periodic(
             return $e->getMessage();
         }
 
-        $daysBetweenIssueAndSettlement = YearFrac::fraction($issue, $settlement, $basis);
+        $daysBetweenIssueAndSettlement = Functions::scalar(YearFrac::fraction($issue, $settlement, $basis));
         if (!is_numeric($daysBetweenIssueAndSettlement)) {
             //    return date error
             return $daysBetweenIssueAndSettlement;
         }
-        $daysBetweenFirstInterestAndSettlement = YearFrac::fraction($firstInterest, $settlement, $basis);
+        $daysBetweenFirstInterestAndSettlement = Functions::scalar(YearFrac::fraction($firstInterest, $settlement, $basis));
         if (!is_numeric($daysBetweenFirstInterestAndSettlement)) {
             //    return date error
             return $daysBetweenFirstInterestAndSettlement;
@@ -140,7 +140,7 @@ public static function atMaturity(
             return $e->getMessage();
         }
 
-        $daysBetweenIssueAndSettlement = YearFrac::fraction($issue, $settlement, $basis);
+        $daysBetweenIssueAndSettlement = Functions::scalar(YearFrac::fraction($issue, $settlement, $basis));
         if (!is_numeric($daysBetweenIssueAndSettlement)) {
             //    return date error
             return $daysBetweenIssueAndSettlement;

src/PhpSpreadsheet/Calculation/Financial/Securities/Price.php

@@ -134,7 +134,7 @@ public static function priceDiscounted(
             return $e->getMessage();
         }
 
-        $daysBetweenSettlementAndMaturity = DateTimeExcel\YearFrac::fraction($settlement, $maturity, $basis);
+        $daysBetweenSettlementAndMaturity = Functions::scalar(DateTimeExcel\YearFrac::fraction($settlement, $maturity, $basis));
         if (!is_numeric($daysBetweenSettlementAndMaturity)) {
             //    return date error
             return $daysBetweenSettlementAndMaturity;
@@ -194,23 +194,23 @@ public static function priceAtMaturity(
             return $e->getMessage();
         }
 
-        $daysPerYear = Helpers::daysPerYear(DateTimeExcel\DateParts::year($settlement), $basis);
+        $daysPerYear = Functions::scalar(Helpers::daysPerYear(DateTimeExcel\DateParts::year($settlement), $basis));
         if (!is_numeric($daysPerYear)) {
             return $daysPerYear;
         }
-        $daysBetweenIssueAndSettlement = DateTimeExcel\YearFrac::fraction($issue, $settlement, $basis);
+        $daysBetweenIssueAndSettlement = Functions::scalar(DateTimeExcel\YearFrac::fraction($issue, $settlement, $basis));
         if (!is_numeric($daysBetweenIssueAndSettlement)) {
             //    return date error
             return $daysBetweenIssueAndSettlement;
         }
         $daysBetweenIssueAndSettlement *= $daysPerYear;
-        $daysBetweenIssueAndMaturity = DateTimeExcel\YearFrac::fraction($issue, $maturity, $basis);
+        $daysBetweenIssueAndMaturity = Functions::scalar(DateTimeExcel\YearFrac::fraction($issue, $maturity, $basis));
         if (!is_numeric($daysBetweenIssueAndMaturity)) {
             //    return date error
             return $daysBetweenIssueAndMaturity;
         }
         $daysBetweenIssueAndMaturity *= $daysPerYear;
-        $daysBetweenSettlementAndMaturity = DateTimeExcel\YearFrac::fraction($settlement, $maturity, $basis);
+        $daysBetweenSettlementAndMaturity = Functions::scalar(DateTimeExcel\YearFrac::fraction($settlement, $maturity, $basis));
         if (!is_numeric($daysBetweenSettlementAndMaturity)) {
             //    return date error
             return $daysBetweenSettlementAndMaturity;

src/PhpSpreadsheet/Calculation/Financial/Securities/Rates.php

@@ -63,7 +63,7 @@ public static function discount(
             return Functions::NAN();
         }
 
-        $daysBetweenSettlementAndMaturity = DateTimeExcel\YearFrac::fraction($settlement, $maturity, $basis);
+        $daysBetweenSettlementAndMaturity = Functions::scalar(DateTimeExcel\YearFrac::fraction($settlement, $maturity, $basis));
         if (!is_numeric($daysBetweenSettlementAndMaturity)) {
             //    return date error
             return $daysBetweenSettlementAndMaturity;
@@ -126,7 +126,7 @@ public static function interest(
             return Functions::NAN();
         }
 
-        $daysBetweenSettlementAndMaturity = DateTimeExcel\YearFrac::fraction($settlement, $maturity, $basis);
+        $daysBetweenSettlementAndMaturity = Functions::scalar(DateTimeExcel\YearFrac::fraction($settlement, $maturity, $basis));
         if (!is_numeric($daysBetweenSettlementAndMaturity)) {
             //    return date error
             return $daysBetweenSettlementAndMaturity;

src/PhpSpreadsheet/Calculation/Financial/Securities/Yields.php

@@ -61,7 +61,7 @@ public static function yieldDiscounted(
         if (!is_numeric($daysPerYear)) {
             return $daysPerYear;
         }
-        $daysBetweenSettlementAndMaturity = DateTimeExcel\YearFrac::fraction($settlement, $maturity, $basis);
+        $daysBetweenSettlementAndMaturity = Functions::scalar(DateTimeExcel\YearFrac::fraction($settlement, $maturity, $basis));
         if (!is_numeric($daysBetweenSettlementAndMaturity)) {
             //    return date error
             return $daysBetweenSettlementAndMaturity;
@@ -126,19 +126,19 @@ public static function yieldAtMaturity(
         if (!is_numeric($daysPerYear)) {
             return $daysPerYear;
         }
-        $daysBetweenIssueAndSettlement = DateTimeExcel\YearFrac::fraction($issue, $settlement, $basis);
+        $daysBetweenIssueAndSettlement = Functions::scalar(DateTimeExcel\YearFrac::fraction($issue, $settlement, $basis));
         if (!is_numeric($daysBetweenIssueAndSettlement)) {
             //    return date error
             return $daysBetweenIssueAndSettlement;
         }
         $daysBetweenIssueAndSettlement *= $daysPerYear;
-        $daysBetweenIssueAndMaturity = DateTimeExcel\YearFrac::fraction($issue, $maturity, $basis);
+        $daysBetweenIssueAndMaturity = Functions::scalar(DateTimeExcel\YearFrac::fraction($issue, $maturity, $basis));
         if (!is_numeric($daysBetweenIssueAndMaturity)) {
             //    return date error
             return $daysBetweenIssueAndMaturity;
         }
         $daysBetweenIssueAndMaturity *= $daysPerYear;
-        $daysBetweenSettlementAndMaturity = DateTimeExcel\YearFrac::fraction($settlement, $maturity, $basis);
+        $daysBetweenSettlementAndMaturity = Functions::scalar(DateTimeExcel\YearFrac::fraction($settlement, $maturity, $basis));
         if (!is_numeric($daysBetweenSettlementAndMaturity)) {
             //    return date error
             return $daysBetweenSettlementAndMaturity;