Implement array argments for the DATE() function sothat we can verify that paired arrays/vectors work with functions that support more than 2 arguments

Author: MarkBaker

src/PhpSpreadsheet/Calculation/DateTimeExcel/Date.php

@@ -2,13 +2,16 @@
 
 namespace PhpOffice\PhpSpreadsheet\Calculation\DateTimeExcel;
 
+use PhpOffice\PhpSpreadsheet\Calculation\ArrayEnabled;
 use PhpOffice\PhpSpreadsheet\Calculation\Exception;
 use PhpOffice\PhpSpreadsheet\Calculation\Functions;
 use PhpOffice\PhpSpreadsheet\Shared\Date as SharedDateHelper;
 use PhpOffice\PhpSpreadsheet\Shared\StringHelper;
 
 class Date
 {
+    use ArrayEnabled;
+
     /**
      * DATE.
      *
@@ -24,7 +27,7 @@ class Date
      * A Month name or abbreviation (English only at this point) such as 'January' or 'Jan' will still be accepted,
      *     as will a day value with a suffix (e.g. '21st' rather than simply 21); again only English language.
      *
-     * @param int $year The value of the year argument can include one to four digits.
+     * @param array|int $year The value of the year argument can include one to four digits.
      *                                Excel interprets the year argument according to the configured
      *                                date system: 1900 or 1904.
      *                                If year is between 0 (zero) and 1899 (inclusive), Excel adds that
@@ -35,7 +38,7 @@ class Date
      *                                2008.
      *                                If year is less than 0 or is 10000 or greater, Excel returns the
      *                                #NUM! error value.
-     * @param int $month A positive or negative integer representing the month of the year
+     * @param array|int $month A positive or negative integer representing the month of the year
      *                                from 1 to 12 (January to December).
      *                                If month is greater than 12, month adds that number of months to
      *                                the first month in the year specified. For example, DATE(2008,14,2)
@@ -44,7 +47,7 @@ class Date
      *                                number of months, plus 1, from the first month in the year
      *                                specified. For example, DATE(2008,-3,2) returns the serial number
      *                                representing September 2, 2007.
-     * @param int $day A positive or negative integer representing the day of the month
+     * @param array|int $day A positive or negative integer representing the day of the month
      *                                from 1 to 31.
      *                                If day is greater than the number of days in the month specified,
      *                                day adds that number of days to the first day in the month. For
@@ -57,9 +60,15 @@ class Date
      *
      * @return mixed Excel date/time serial value, PHP date/time serial value or PHP date/time object,
      *                        depending on the value of the ReturnDateType flag
+     *         If an array of numbers is passed as the argument, then the returned result will also be an array
+     *            with the same dimensions
      */
     public static function fromYMD($year, $month, $day)
     {
+        if (is_array($year) || is_array($month) || is_array($day)) {
+            return self::evaluateArrayArguments([self::class, __FUNCTION__], $year, $month, $day);
+        }
+
         $baseYear = SharedDateHelper::getExcelCalendar();
 
         try {

tests/PhpSpreadsheetTests/Calculation/Functions/DateTime/DateTest.php

@@ -2,6 +2,7 @@
 
 namespace PhpOffice\PhpSpreadsheetTests\Calculation\Functions\DateTime;
 
+use PhpOffice\PhpSpreadsheet\Calculation\Calculation;
 use PhpOffice\PhpSpreadsheet\Calculation\DateTimeExcel\Date;
 
 class DateTest extends AllSetupTeardown
@@ -56,4 +57,61 @@ public function testDATEwith1904Calendar(): void
         $result = Date::fromYMD(1901, 1, 31);
         self::assertEquals($result, '#NUM!');
     }
+
+    /**
+     * @dataProvider providerDateArray
+     */
+    public function testDateArray(array $expectedResult, string $year, string $month, string $day): void
+    {
+        $calculation = Calculation::getInstance();
+
+        $formula = "=DATE({$year}, {$month}, {$day})";
+        $result = $calculation->_calculateFormulaValue($formula);
+        self::assertEqualsWithDelta($expectedResult, $result, 1.0e-14);
+    }
+
+    public function providerDateArray(): array
+    {
+        return [
+            'row vector year' => [[[44197, 44562, 44927]], '{2021,2022,2023}', '1', '1'],
+            'column vector year' => [[[44197], [44562], [44927]], '{2021;2022;2023}', '1', '1'],
+            'matrix year' => [[[43831.00, 44197], [44562, 44927]], '{2020,2021;2022,2023}', '1', '1'],
+            'row vector month' => [[[44562, 44652, 44743, 44835]], '2022', '{1, 4, 7, 10}', '1'],
+            'column vector month' => [[[44562], [44652], [44743], [44835]], '2022', '{1; 4; 7; 10}', '1'],
+            'matrix month' => [[[44562, 44652], [44743, 44835]], '2022', '{1, 4; 7, 10}', '1'],
+            'row vector day' => [[[44561, 44562]], '2022', '1', '{0,1}'],
+            'column vector day' => [[[44561], [44562]], '2022', '1', '{0;1}'],
+            'vectors year and month' => [
+                [
+                    [44197, 44287, 44378, 44470],
+                    [44562, 44652, 44743, 44835],
+                    [44927, 45017, 45108, 45200],
+                ],
+                '{2021;2022;2023}',
+                '{1, 4, 7, 10}',
+                '1',
+            ],
+            'vectors year and day' => [
+                [
+                    [44196, 44197],
+                    [44561, 44562],
+                    [44926, 44927],
+                ],
+                '{2021;2022;2023}',
+                '1',
+                '{0,1}',
+            ],
+            'vectors month and day' => [
+                [
+                    [44561, 44562],
+                    [44651, 44652],
+                    [44742, 44743],
+                    [44834, 44835],
+                ],
+                '2022',
+                '{1; 4; 7; 10}',
+                '{0,1}',
+            ],
+        ];
+    }
 }