Start work on array-enabling the Lookup and Reference functions

MarkBaker · MarkBaker · commit a0f20f666175 · 2022-02-18T14:23:21.000+01:00
Requires a new method (`evaluateArrayArgumentsSubsetFrom()`) in the `ArrayEnabled` Trait to handle functions where the arguments that need special array handling are trailing rather than leading arguments
diff --git a/src/PhpSpreadsheet/Calculation/ArrayEnabled.php b/src/PhpSpreadsheet/Calculation/ArrayEnabled.php
@@ -53,4 +53,25 @@ protected static function evaluateArrayArgumentsSubset(callable $method, int $li
 
         return ArrayArgumentProcessor::processArguments(self::$arrayArgumentHelper, $method, ...$arguments);
     }
+
+    /**
+     * @param mixed ...$arguments
+     */
+    protected static function evaluateArrayArgumentsSubsetFrom(callable $method, int $start, ...$arguments): array
+    {
+        $arrayArgumentsSubset = array_combine(
+            range($start, count($arguments) - $start),
+            array_slice($arguments, $start)
+        );
+        if ($arrayArgumentsSubset === false) {
+            return ['#VALUE!'];
+        }
+
+        self::initialiseHelper($arrayArgumentsSubset);
+        $leadingArguments = array_slice($arguments, 0, $start);
+        $arguments = self::$arrayArgumentHelper->arguments();
+        $arguments = array_merge($leadingArguments, $arguments);
+
+        return ArrayArgumentProcessor::processArguments(self::$arrayArgumentHelper, $method, ...$arguments);
+    }
 }
diff --git a/src/PhpSpreadsheet/Calculation/Engine/ArrayArgumentHelper.php b/src/PhpSpreadsheet/Calculation/Engine/ArrayArgumentHelper.php
@@ -6,6 +6,11 @@
 
 class ArrayArgumentHelper
 {
+    /**
+     * @var int
+     */
+    protected $indexStart = 0;
+
     /**
      * @var array
      */
@@ -28,6 +33,8 @@ class ArrayArgumentHelper
 
     public function initialise(array $arguments): void
     {
+        $keys = array_keys($arguments);
+        $this->indexStart = (int) array_shift($keys);
         $this->rows = $this->rows($arguments);
         $this->columns = $this->columns($arguments);
 
@@ -57,7 +64,7 @@ public function getFirstArrayArgumentNumber(): int
         $rowArrays = $this->filterArray($this->rows);
         $columnArrays = $this->filterArray($this->columns);
 
-        for ($index = 0; $index < $this->argumentCount; ++$index) {
+        for ($index = $this->indexStart; $index < $this->argumentCount; ++$index) {
             if (isset($rowArrays[$index]) || isset($columnArrays[$index])) {
                 return ++$index;
             }
@@ -76,7 +83,7 @@ public function getSingleRowVector(): ?int
     private function getRowVectors(): array
     {
         $rowVectors = [];
-        for ($index = 0; $index < $this->argumentCount; ++$index) {
+        for ($index = $this->indexStart; $index < ($this->indexStart + $this->argumentCount); ++$index) {
             if ($this->rows[$index] === 1 && $this->columns[$index] > 1) {
                 $rowVectors[] = $index;
             }
@@ -95,7 +102,7 @@ public function getSingleColumnVector(): ?int
     private function getColumnVectors(): array
     {
         $columnVectors = [];
-        for ($index = 0; $index < $this->argumentCount; ++$index) {
+        for ($index = $this->indexStart; $index < ($this->indexStart + $this->argumentCount); ++$index) {
             if ($this->rows[$index] > 1 && $this->columns[$index] === 1) {
                 $columnVectors[] = $index;
             }
@@ -106,7 +113,7 @@ private function getColumnVectors(): array
 
     public function getMatrixPair(): array
     {
-        for ($i = 0; $i < ($this->argumentCount - 1); ++$i) {
+        for ($i = $this->indexStart; $i < ($this->indexStart + $this->argumentCount - 1); ++$i) {
             for ($j = $i + 1; $j < $this->argumentCount; ++$j) {
                 if (isset($this->rows[$i], $this->rows[$j])) {
                     return [$i, $j];
diff --git a/src/PhpSpreadsheet/Calculation/Engine/ArrayArgumentProcessor.php b/src/PhpSpreadsheet/Calculation/Engine/ArrayArgumentProcessor.php
@@ -33,6 +33,7 @@ public static function processArguments(
 
         $singleRowVectorIndex = self::$arrayArgumentHelper->getSingleRowVector();
         $singleColumnVectorIndex = self::$arrayArgumentHelper->getSingleColumnVector();
+
         if ($singleRowVectorIndex !== null && $singleColumnVectorIndex !== null) {
             // Basic logic for a single row vector and a single column vector
             return self::evaluateVectorPair($method, $singleRowVectorIndex, $singleColumnVectorIndex, ...$arguments);
diff --git a/src/PhpSpreadsheet/Calculation/LookupRef.php b/src/PhpSpreadsheet/Calculation/LookupRef.php
@@ -41,9 +41,9 @@ class LookupRef
      * @param bool $referenceStyle A logical value that specifies the A1 or R1C1 reference style.
      *                                TRUE or omitted      CELL_ADDRESS returns an A1-style reference
      *                                FALSE                CELL_ADDRESS returns an R1C1-style reference
-     * @param string $sheetText Optional Name of worksheet to use
+     * @param array|string $sheetText Optional Name of worksheet to use
      *
-     * @return string
+     * @return array|string
      */
     public static function cellAddress($row, $column, $relativity = 1, $referenceStyle = true, $sheetText = '')
     {
diff --git a/src/PhpSpreadsheet/Calculation/LookupRef/Address.php b/src/PhpSpreadsheet/Calculation/LookupRef/Address.php
@@ -2,11 +2,14 @@
 
 namespace PhpOffice\PhpSpreadsheet\Calculation\LookupRef;
 
+use PhpOffice\PhpSpreadsheet\Calculation\ArrayEnabled;
 use PhpOffice\PhpSpreadsheet\Calculation\Functions;
 use PhpOffice\PhpSpreadsheet\Cell\Coordinate;
 
 class Address
 {
+    use ArrayEnabled;
+
     public const ADDRESS_ABSOLUTE = 1;
     public const ADDRESS_COLUMN_RELATIVE = 2;
     public const ADDRESS_ROW_RELATIVE = 3;
@@ -24,26 +27,44 @@ class Address
      *        =ADDRESS(row, column, [relativity], [referenceStyle], [sheetText])
      *
      * @param mixed $row Row number (integer) to use in the cell reference
+     *                      Or can be an array of values
      * @param mixed $column Column number (integer) to use in the cell reference
+     *                      Or can be an array of values
      * @param mixed $relativity Integer flag indicating the type of reference to return
      *                             1 or omitted    Absolute
      *                             2               Absolute row; relative column
      *                             3               Relative row; absolute column
      *                             4               Relative
+     *                      Or can be an array of values
      * @param mixed $referenceStyle A logical (boolean) value that specifies the A1 or R1C1 reference style.
      *                                TRUE or omitted    ADDRESS returns an A1-style reference
      *                                FALSE              ADDRESS returns an R1C1-style reference
+     *                      Or can be an array of values
      * @param mixed $sheetName Optional Name of worksheet to use
+     *                      Or can be an array of values
      *
-     * @return string
+     * @return array|string
+     *         If an array of values is passed as the $testValue argument, then the returned result will also be
+     *            an array with the same dimensions
      */
     public static function cell($row, $column, $relativity = 1, $referenceStyle = true, $sheetName = '')
     {
-        $row = Functions::flattenSingleValue($row);
-        $column = Functions::flattenSingleValue($column);
-        $relativity = ($relativity === null) ? 1 : Functions::flattenSingleValue($relativity);
-        $referenceStyle = ($referenceStyle === null) ? true : Functions::flattenSingleValue($referenceStyle);
-        $sheetName = Functions::flattenSingleValue($sheetName);
+        if (
+            is_array($row) || is_array($column) ||
+            is_array($relativity) || is_array($referenceStyle) || is_array($sheetName)
+        ) {
+            return self::evaluateArrayArguments(
+                [self::class, __FUNCTION__],
+                $row,
+                $column,
+                $relativity,
+                $referenceStyle,
+                $sheetName
+            );
+        }
+
+        $relativity = $relativity ?? 1;
+        $referenceStyle = $referenceStyle ?? true;
 
         if (($row < 1) || ($column < 1)) {
             return Functions::VALUE();
diff --git a/src/PhpSpreadsheet/Calculation/LookupRef/Matrix.php b/src/PhpSpreadsheet/Calculation/LookupRef/Matrix.php
@@ -2,11 +2,14 @@
 
 namespace PhpOffice\PhpSpreadsheet\Calculation\LookupRef;
 
+use PhpOffice\PhpSpreadsheet\Calculation\ArrayEnabled;
 use PhpOffice\PhpSpreadsheet\Calculation\Exception;
 use PhpOffice\PhpSpreadsheet\Calculation\Functions;
 
 class Matrix
 {
+    use ArrayEnabled;
+
     /**
      * TRANSPOSE.
      *
@@ -45,17 +48,25 @@ public static function transpose($matrixData)
      * @param mixed $matrix A range of cells or an array constant
      * @param mixed $rowNum The row in the array or range from which to return a value.
      *                          If row_num is omitted, column_num is required.
+     *                      Or can be an array of values
      * @param mixed $columnNum The column in the array or range from which to return a value.
      *                          If column_num is omitted, row_num is required.
+     *                      Or can be an array of values
      *
      * TODO Provide support for area_num, currently not supported
      *
      * @return mixed the value of a specified cell or array of cells
+     *         If an array of values is passed as the $rowNum and/or $columnNum arguments, then the returned result
+     *            will also be an array with the same dimensions
      */
     public static function index($matrix, $rowNum = 0, $columnNum = 0)
     {
-        $rowNum = ($rowNum === null) ? 0 : Functions::flattenSingleValue($rowNum);
-        $columnNum = ($columnNum === null) ? 0 : Functions::flattenSingleValue($columnNum);
+        if (is_array($rowNum) || is_array($columnNum)) {
+            return self::evaluateArrayArgumentsSubsetFrom([self::class, __FUNCTION__], 1, $matrix, $rowNum, $columnNum);
+        }
+
+        $rowNum = $rowNum ?? 0;
+        $columnNum = $columnNum ?? 0;
 
         try {
             $rowNum = LookupRefValidations::validatePositiveInt($rowNum);
diff --git a/tests/PhpSpreadsheetTests/Calculation/Functions/LookupRef/AddressTest.php b/tests/PhpSpreadsheetTests/Calculation/Functions/LookupRef/AddressTest.php
@@ -2,6 +2,7 @@
 
 namespace PhpOffice\PhpSpreadsheetTests\Calculation\Functions\LookupRef;
 
+use PhpOffice\PhpSpreadsheet\Calculation\Calculation;
 use PhpOffice\PhpSpreadsheet\Calculation\Functions;
 use PhpOffice\PhpSpreadsheet\Calculation\LookupRef;
 use PHPUnit\Framework\TestCase;
@@ -28,4 +29,27 @@ public function providerADDRESS(): array
     {
         return require 'tests/data/Calculation/LookupRef/ADDRESS.php';
     }
+
+    /**
+     * @dataProvider providerAddressArray
+     */
+    public function testAddressArray(array $expectedResult, string $argument1, string $argument2): void
+    {
+        $calculation = Calculation::getInstance();
+
+        $formula = "=ADDRESS({$argument1}, {$argument2}, 4)";
+        $result = $calculation->_calculateFormulaValue($formula);
+        self::assertEquals($expectedResult, $result);
+    }
+
+    public function providerAddressArray(): array
+    {
+        return [
+            'row/column vectors' => [
+                [['A1', 'B1', 'C1'], ['A2', 'B2', 'C2'], ['A3', 'B3', 'C3']],
+                '{1; 2; 3}',
+                '{1, 2, 3}',
+            ],
+        ];
+    }
 }
diff --git a/tests/PhpSpreadsheetTests/Calculation/Functions/LookupRef/IndexTest.php b/tests/PhpSpreadsheetTests/Calculation/Functions/LookupRef/IndexTest.php
@@ -2,6 +2,7 @@
 
 namespace PhpOffice\PhpSpreadsheetTests\Calculation\Functions\LookupRef;
 
+use PhpOffice\PhpSpreadsheet\Calculation\Calculation;
 use PhpOffice\PhpSpreadsheet\Calculation\Functions;
 use PhpOffice\PhpSpreadsheet\Calculation\LookupRef;
 use PHPUnit\Framework\TestCase;
@@ -21,12 +22,35 @@ protected function setUp(): void
     public function testINDEX($expectedResult, ...$args): void
     {
         $result = LookupRef::INDEX(...$args);
-//        var_dump($result);
         self::assertEquals($expectedResult, $result);
     }
 
     public function providerINDEX(): array
     {
         return require 'tests/data/Calculation/LookupRef/INDEX.php';
     }
+
+    /**
+     * @dataProvider providerIndexArray
+     */
+    public function testIndexArray(array $expectedResult, string $matrix, string $rows, string $columns): void
+    {
+        $calculation = Calculation::getInstance();
+
+        $formula = "=INDEX({$matrix}, {$rows}, {$columns})";
+        $result = $calculation->_calculateFormulaValue($formula);
+        self::assertEquals($expectedResult, $result);
+    }
+
+    public function providerIndexArray(): array
+    {
+        return [
+            'row/column vectors' => [
+                [[2, 3], [5, 6]],
+                '{1, 2, 3; 4, 5, 6; 7, 8, 9}',
+                '{1; 2}',
+                '{2, 3}',
+            ],
+        ];
+    }
 }
diff --git a/tests/data/Calculation/LookupRef/INDEX.php b/tests/data/Calculation/LookupRef/INDEX.php
@@ -112,7 +112,7 @@
         2,
     ],
     [
-        4, // Expected
+        [4], // Expected
         // Input
         [
             '20' => ['R' => 1, 'S' => 3],

Original file line number	Diff line number	Diff line change
`@@ -41,9 +41,9 @@ class LookupRef`
`41`	`41`	`* @param bool $referenceStyle A logical value that specifies the A1 or R1C1 reference style.`
`42`	`42`	`* TRUE or omitted CELL_ADDRESS returns an A1-style reference`
`43`	`43`	`* FALSE CELL_ADDRESS returns an R1C1-style reference`
`44`		`- * @param string $sheetText Optional Name of worksheet to use`
	`44`	`+ * @param array\|string $sheetText Optional Name of worksheet to use`
`45`	`45`	`*`
`46`		`- * @return string`
	`46`	`+ * @return array\|string`
`47`	`47`	`*/`
`48`	`48`	`public static function cellAddress($row, $column, $relativity = 1, $referenceStyle = true, $sheetText = '')`
`49`	`49`	`{`
Original file line number	Diff line number	Diff line change
`@@ -112,7 +112,7 @@`
`112`	`112`	`2,`
`113`	`113`	`],`
`114`	`114`	`[`
`115`		`- 4, // Expected`
	`115`	`+ [4], // Expected`
`116`	`116`	`// Input`
`117`	`117`	`[`
`118`	`118`	`'20' => ['R' => 1, 'S' => 3],`