CHOOSECOLS, CHOOSEROWS, DROP, TAKE, and EXPAND

These are 5 closely related functions for manipulating arrays. Now that dynamic arrays are part of PhpSpreadsheet, this PR implements those previously-unimplemented functions. Documentation undergoes a very minor change, since they are re-categorized as "Lookup and Reference", which is how Excel classifies them, rather than "Math and Trig".
oleibman · Dec 22, 2024 · ee7ddf7 · ee7ddf7
1 parent eccbcce
commit ee7ddf7
Show file tree

Hide file tree

Showing 16 changed files with 1,270 additions and 20 deletions.
diff --git a/docs/references/function-list-by-category.md b/docs/references/function-list-by-category.md
@@ -240,8 +240,12 @@ Excel Function           | PhpSpreadsheet Function
 ADDRESS                  | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\Address::cell
 AREAS                    | **Not yet Implemented**
 CHOOSE                   | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\Selection::CHOOSE
+CHOOSECOLS               | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\ChooseRowsEtc::chooseCols
+CHOOSEROWS               | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\ChooseRowsEtc::chooseRows
 COLUMN                   | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\RowColumnInformation::COLUMN
 COLUMNS                  | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\RowColumnInformation::COLUMNS
+DROP                     | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\ChooseRowsEtc::drop
+EXPAND                   | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\ChooseRowsEtc::expand
 FILTER                   | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\Filter::filter
 FORMULATEXT              | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\Formula::text
 GETPIVOTDATA             | **Not yet Implemented**
@@ -257,6 +261,7 @@ ROWS                     | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\RowCo
 RTD                      | **Not yet Implemented**
 SORT                     | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\Sort::sort
 SORTBY                   | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\Sort::sortBy
+TAKE                     | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\ChooseRowsEtc::take
 TRANSPOSE                | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\Matrix::transpose
 UNIQUE                   | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\Unique::unique
 VLOOKUP                  | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\VLookup::lookup
@@ -283,8 +288,6 @@ BASE                     | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Base::
 CEILING                  | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Ceiling::ceiling
 CEILING.MATH             | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Ceiling::math
 CEILING.PRECISE          | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Ceiling::precise
-CHOOSECOLS               | **Not yet Implemented**
-CHOOSEROWS               | **Not yet Implemented**
 COMBIN                   | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Combinations::withoutRepetition
 COMBINA                  | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Combinations::withRepetition
 COS                      | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Trig\Cosine::cos
@@ -295,11 +298,9 @@ CSC                      | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Trig\C
 CSCH                     | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Trig\Cosecant::csch
 DECIMAL                  | **Not yet Implemented**
 DEGREES                  | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Angle::toDegrees
-DROP                     | **Not yet Implemented**
 ECMA.CEILING             | **Not yet Implemented**
 EVEN                     | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Round::even
 EXP                      | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Exp::evaluate
-EXPAND                   | **Not yet Implemented**
 FACT                     | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Factorial::fact
 FACTDOUBLE               | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Factorial::factDouble
 FLOOR                    | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Floor::floor
@@ -353,7 +354,6 @@ SUMSQ                    | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\SumSqu
 SUMX2MY2                 | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\SumSquares::sumXSquaredMinusYSquared
 SUMX2PY2                 | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\SumSquares::sumXSquaredPlusYSquared
 SUMXMY2                  | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\SumSquares::sumXMinusYSquared
-TAKE                     | **Not yet Implemented**
 TAN                      | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Trig\Tangent::tan
 TANH                     | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Trig\Tangent::tanh
 TOCOL                    | **Not yet Implemented**

diff --git a/docs/references/function-list-by-name.md b/docs/references/function-list-by-name.md
@@ -79,8 +79,8 @@ CHISQ.INV.RT             | CATEGORY_STATISTICAL           | \PhpOffice\PhpSpread
 CHISQ.TEST               | CATEGORY_STATISTICAL           | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Distributions\ChiSquared::test
 CHITEST                  | CATEGORY_STATISTICAL           | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Distributions\ChiSquared::test
 CHOOSE                   | CATEGORY_LOOKUP_AND_REFERENCE  | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\Selection::CHOOSE
-CHOOSECOLS               | CATEGORY_MATH_AND_TRIG         | **Not yet Implemented**
-CHOOSEROWS               | CATEGORY_MATH_AND_TRIG         | **Not yet Implemented**
+CHOOSECOLS               | CATEGORY_LOOKUP_AND_REFERENCE  | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\ChooseRowsEtc::chooseCols
+CHOOSEROWS               | CATEGORY_LOOKUP_AND_REFERENCE  | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\ChooseRowsEtc::chooseRows
 CLEAN                    | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Trim::nonPrintable
 CODE                     | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpreadsheet\Calculation\TextData\CharacterConvert::code
 COLUMN                   | CATEGORY_LOOKUP_AND_REFERENCE  | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\RowColumnInformation::COLUMN
@@ -158,7 +158,7 @@ DOLLAR                   | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpread
 DOLLARDE                 | CATEGORY_FINANCIAL             | \PhpOffice\PhpSpreadsheet\Calculation\Financial\Dollar::decimal
 DOLLARFR                 | CATEGORY_FINANCIAL             | \PhpOffice\PhpSpreadsheet\Calculation\Financial\Dollar::fractional
 DPRODUCT                 | CATEGORY_DATABASE              | \PhpOffice\PhpSpreadsheet\Calculation\Database\DProduct::evaluate
-DROP                     | CATEGORY_MATH_AND_TRIG         | **Not yet Implemented**
+DROP                     | CATEGORY_LOOKUP_AND_REFERENCE  | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\ChooseRowsEtc::drop
 DSTDEV                   | CATEGORY_DATABASE              | \PhpOffice\PhpSpreadsheet\Calculation\Database\DStDev::evaluate
 DSTDEVP                  | CATEGORY_DATABASE              | \PhpOffice\PhpSpreadsheet\Calculation\Database\DStDevP::evaluate
 DSUM                     | CATEGORY_DATABASE              | \PhpOffice\PhpSpreadsheet\Calculation\Database\DSum::evaluate
@@ -183,7 +183,7 @@ ERROR.TYPE               | CATEGORY_INFORMATION           | \PhpOffice\PhpSpread
 EVEN                     | CATEGORY_MATH_AND_TRIG         | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Round::even
 EXACT                    | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Text::exact
 EXP                      | CATEGORY_MATH_AND_TRIG         | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Exp::evaluate
-EXPAND                   | CATEGORY_MATH_AND_TRIG         | **Not yet Implemented**
+EXPAND                   | CATEGORY_LOOKUP_AND_REFERENCE  | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\ChooseRowsEtc::expand
 EXPON.DIST               | CATEGORY_STATISTICAL           | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Distributions\Exponential::distribution
 EXPONDIST                | CATEGORY_STATISTICAL           | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Distributions\Exponential::distribution
 
@@ -553,7 +553,7 @@ T.DIST.RT                | CATEGORY_STATISTICAL           | **Not yet Implemente
 T.INV                    | CATEGORY_STATISTICAL           | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Distributions\StudentT::inverse
 T.INV.2T                 | CATEGORY_STATISTICAL           | **Not yet Implemented**
 T.TEST                   | CATEGORY_STATISTICAL           | **Not yet Implemented**
-TAKE                     | CATEGORY_MATH_AND_TRIG         | **Not yet Implemented**
+TAKE                     | CATEGORY_LOOKUP_AND_REFERENCE  | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\ChooseRowsEtc::take
 TAN                      | CATEGORY_MATH_AND_TRIG         | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Trig\Tangent::tan
 TANH                     | CATEGORY_MATH_AND_TRIG         | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Trig\Tangent::tanh
 TBILLEQ                  | CATEGORY_FINANCIAL             | \PhpOffice\PhpSpreadsheet\Calculation\Financial\TreasuryBill::bondEquivalentYield

diff --git a/src/PhpSpreadsheet/Calculation/Calculation.php b/src/PhpSpreadsheet/Calculation/Calculation.php
@@ -553,13 +553,13 @@ public static function getExcelConstants(string $key): bool|null
             'argumentCount' => '2+',
         ],
         'CHOOSECOLS' => [
-            'category' => Category::CATEGORY_MATH_AND_TRIG,
-            'functionCall' => [Functions::class, 'DUMMY'],
+            'category' => Category::CATEGORY_LOOKUP_AND_REFERENCE,
+            'functionCall' => [LookupRef\ChooseRowsEtc::class, 'chooseCols'],
             'argumentCount' => '2+',
         ],
         'CHOOSEROWS' => [
-            'category' => Category::CATEGORY_MATH_AND_TRIG,
-            'functionCall' => [Functions::class, 'DUMMY'],
+            'category' => Category::CATEGORY_LOOKUP_AND_REFERENCE,
+            'functionCall' => [LookupRef\ChooseRowsEtc::class, 'chooseRows'],
             'argumentCount' => '2+',
         ],
         'CLEAN' => [
@@ -925,8 +925,8 @@ public static function getExcelConstants(string $key): bool|null
             'argumentCount' => '3',
         ],
         'DROP' => [
-            'category' => Category::CATEGORY_MATH_AND_TRIG,
-            'functionCall' => [Functions::class, 'DUMMY'],
+            'category' => Category::CATEGORY_LOOKUP_AND_REFERENCE,
+            'functionCall' => [LookupRef\ChooseRowsEtc::class, 'drop'],
             'argumentCount' => '2-3',
         ],
         'DSTDEV' => [
@@ -1025,8 +1025,8 @@ public static function getExcelConstants(string $key): bool|null
             'argumentCount' => '1',
         ],
         'EXPAND' => [
-            'category' => Category::CATEGORY_MATH_AND_TRIG,
-            'functionCall' => [Functions::class, 'DUMMY'],
+            'category' => Category::CATEGORY_LOOKUP_AND_REFERENCE,
+            'functionCall' => [LookupRef\ChooseRowsEtc::class, 'expand'],
             'argumentCount' => '2-4',
         ],
         'EXPONDIST' => [
@@ -2485,8 +2485,8 @@ public static function getExcelConstants(string $key): bool|null
             'argumentCount' => '1',
         ],
         'TAKE' => [
-            'category' => Category::CATEGORY_MATH_AND_TRIG,
-            'functionCall' => [Functions::class, 'DUMMY'],
+            'category' => Category::CATEGORY_LOOKUP_AND_REFERENCE,
+            'functionCall' => [LookupRef\ChooseRowsEtc::class, 'take'],
             'argumentCount' => '2-3',
         ],
         'TAN' => [

diff --git a/src/PhpSpreadsheet/Calculation/Functions.php b/src/PhpSpreadsheet/Calculation/Functions.php
@@ -230,6 +230,32 @@ public static function flattenArray(mixed $array): array
         return $flattened;
     }
 
+    /**
+     * Convert a multi-dimensional array to a simple 1-dimensional array.
+     * Same as above but argument is specified in ... format.
+     *
+     * @param mixed $array Array to be flattened
+     *
+     * @return array Flattened array
+     */
+    public static function flattenArray2(mixed ...$array): array
+    {
+        $flattened = [];
+        $stack = array_values($array);
+
+        while (!empty($stack)) {
+            $value = array_shift($stack);
+
+            if (is_array($value)) {
+                array_unshift($stack, ...array_values($value));
+            } else {
+                $flattened[] = $value;
+            }
+        }
+
+        return $flattened;
+    }
+
     public static function scalar(mixed $value): mixed
     {
         if (!is_array($value)) {