Some more unit tests for array functions and spillage; and updates to documentation

Author: MarkBaker

docs/topics/calculation-engine.md

@@ -44,6 +44,8 @@ $spreadsheet->getActiveSheet()->getCell('E11')->arrayFormulaRange();
 which returns a string containing a cell reference (e.g. `E11`) or a cell range reference (e.g. `E11:G13`).
 
 
+For more details on working with array formulae, see the [the recipes documentationn](./recipes.md/#array-formulae). 
+
 ### Adjustments to formulae when Inserting/Deleting Columns/Rows
 
 Another nice feature of PhpSpreadsheet's formula parser, is that it can

docs/topics/recipes.md

@@ -239,6 +239,46 @@ $spreadsheet->getActiveSheet()
     );
 ```
 
+Simply setting an array formula in a cell and specifying the range won't populate the spillage area for that formula.
+```php
+$spreadsheet->getActiveSheet()
+    ->setCellValue(
+        'A10',
+        '=SEQUENCE(3,3)',
+        true,
+        'A1:C3'
+    );
+
+// Will return a null, because the formula for A1 hasn't been calculated to populate the spillage area 
+$result = $spreadsheet->getActiveSheet()->getCell('C3')->getValue();
+```
+To do that, we need to retrieve the calculated value for the cell.
+```php
+$spreadsheet->getActiveSheet()
+    ->setCellValue(
+        'A10',
+        '=SEQUENCE(3,3)',
+        true,
+        'A1:C3'
+    );
+
+$spreadsheet->getActiveSheet()->getCell('A1')->getCalculatedValue();
+
+// Will return 9, because the formula for A1 has now been calculated, and the spillage area is populated 
+$result = $spreadsheet->getActiveSheet()->getCell('C3')->getValue();
+```
+When we call `getCalculatedValue()` for a cell that contains an array formula, PhpSpreadsheet returns the single value that would appear in that cell in MS Excel.
+```php
+// Will return integer 1, the value for that cell within the array
+$a1result = $spreadsheet->getActiveSheet()->getCell('A1')->getCalculatedValue();
+```
+
+If we want to return the full array, then we need to call `getCalculatedValue()` with an additional argument, a boolean `true` to return the value as an array.
+```php
+// Will return an array [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
+$a1result = $spreadsheet->getActiveSheet()->getCell('A1')->getCalculatedValue(true);
+```
+
 ---
 
 Excel365 introduced a number of new functions that return arrays of results.

tests/PhpSpreadsheetTests/Calculation/Functions/MathTrig/SequenceTest.php

@@ -22,4 +22,28 @@ public function providerSEQUENCE(): array
     {
         return require 'tests/data/Calculation/MathTrig/SEQUENCE.php';
     }
+
+    public function testSequenceAsCellFormula()
+    {
+        $sheet = $this->getSheet();
+        $sheet->getCell('B2')->setValue('=SEQUENCE(3,3,9,-1)', true, 'B2:D4');
+
+        $result = $sheet->getCell('B2')->getCalculatedValue();
+        self::assertSame(9, $result);
+
+        // Check that spillage area has been populated
+        self::assertSame(5, $sheet->getCell('C3')->getCalculatedValue());
+    }
+
+    public function testSequenceAsCellFormulaAsArray()
+    {
+        $sheet = $this->getSheet();
+        $sheet->getCell('B2')->setValue('=SEQUENCE(3,3,9,-1)', true, 'B2:D4');
+
+        $result = $sheet->getCell('B2')->getCalculatedValue(true);
+        self::assertSame([[9, 8, 7], [6, 5, 4], [3, 2, 1]], $result);
+
+        // Check that spillage area has been populated
+        self::assertSame(5, $sheet->getCell('C3')->getCalculatedValue());
+    }
 }