Merge remote-tracking branch 'origin/master'

# Conflicts:
#	src/PhpSpreadsheet/Calculation/Calculation.php
#	src/PhpSpreadsheet/Calculation/Engine/Operands/StructuredReference.php

Author: MarkBaker

CHANGELOG.md

@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ### Added
 
-- Nothing
+- Support for Structured References in the Calculation Engine [PR #3261](https://github.com/PHPOffice/PhpSpreadsheet/pull/3261)
 
 ### Changed
 

docs/topics/reading-and-writing-to-file.md

@@ -184,6 +184,22 @@ code:
 it disables several Office2007 file format options, resulting in a
 lower-featured Office2007 spreadsheet.
 
+### Form Control Fields
+
+PhpSpreadsheet offers limited support for Forms Controls (buttons,
+checkboxes, etc.). The support is available only for Excel 2007 format,
+and is offered solely to allow loading a spreadsheet with such controls
+and saving it as a new file.
+Support is not available for adding such elements to the spreadsheet,
+nor even to locate them to determine their properties
+(so you can't modify or delete them).
+Modifications to a worksheet with controls are "caveat emptor";
+some modifications will work correctly,
+but others are very likely to cause problems,
+e.g. adding a comment to the worksheet,
+or inserting or deleting rows or columns in a manner that would
+cause the controls to change location.
+
 ## Excel 5 (BIFF) file format
 
 Xls file format is the old Excel file format, implemented in
@@ -1099,7 +1115,7 @@ Flags that are available that can be passed to the Reader in this way include:
 | Slk      | N/A              | NO             | NO               |
 | Csv      | N/A              | NO             | NO               |
 
-Likewise, when saving a file using a Writer, loaded charts wil not be saved unless you explicitly tell the Writer to include them:
+Likewise, when saving a file using a Writer, loaded charts will not be saved unless you explicitly tell the Writer to include them:
 
 ```php
 $writer = IOFactory::createWriter($spreadsheet, 'Xlsx');

samples/Reader/22_Reader_formscomments.php

@@ -0,0 +1,22 @@
+<?php
+
+use PhpOffice\PhpSpreadsheet\IOFactory;
+
+require __DIR__ . '/../Header.php';
+
+$helper->log('Start');
+
+$inputFileType = 'Xlsx';
+$inputFileName = __DIR__ . '/sampleData/formscomments.xlsx';
+
+$helper->log('Loading file ' . $inputFileName . ' using IOFactory with a defined reader type of ' . $inputFileType);
+$reader = IOFactory::createReader($inputFileType);
+$helper->log('Loading all WorkSheets');
+$reader->setLoadAllSheets();
+$spreadsheet = $reader->load($inputFileName);
+
+// Save
+$helper->write($spreadsheet, __FILE__, ['Xlsx']);
+$spreadsheet->disconnectWorksheets();
+
+$helper->log('end');

samples/Reader/22_Reader_issue1767.php

@@ -17,5 +17,6 @@
 
 // Save
 $helper->write($spreadsheet, __FILE__);
+$spreadsheet->disconnectWorksheets();
 
 $helper->log('end');

samples/Reader/sampleData/formscomments.xlsx

@@ -4732,24 +4732,28 @@ private function processTokenStack($tokens, $cellID = null, ?Cell $cell = null)
             }
 
             if ($token instanceof Operands\StructuredReference) {
-                // The next step is converting any structured reference to a cell value of range
-                //     to a new $token value (a cell range), which can then be processed in the following code.
-                var_dump($token);
-
                 if ($cell === null) {
                     return $this->raiseFormulaError('Structured References must exist in a Cell context');
                 }
 
                 try {
-                    $token->parse($cell);
+                    $cellRange = $token->parse($cell);
+                    if (strpos($cellRange, ':') !== false) {
+                        $this->debugLog->writeDebugLog('Evaluating Structured Reference %s as Cell Range %s', $token->value(), $cellRange);
+                        $rangeValue = self::getInstance($cell->getWorksheet()->getParent())->_calculateFormulaValue("={$cellRange}", $token->value(), $cell);
+                        $stack->push('Value', $rangeValue);
+                        $this->debugLog->writeDebugLog('Evaluated Structured Reference %s as a value %s', $token->value(), $this->showValue($rangeValue));
+                    } else {
+                        $this->debugLog->writeDebugLog('Evaluating Structured Reference %s as Cell %s', $token->value(), $cellRange);
+                        $cellValue = $cell->getWorksheet()->getCell($cellRange)->getCalculatedValue(false);
+                        $stack->push('Cell Reference', $cellValue, $cellRange);
+                        $this->debugLog->writeDebugLog('Evaluated Structured Reference %s as a value %s', $token->value(), $this->showValue($cellValue));
+                    }
                 } catch (Exception $e) {
                     return $this->raiseFormulaError($e->getMessage());
                 }
-                die();
-            }
-
-            // if the token is a binary operator, pop the top two values off the stack, do the operation, and push the result back on the stack
-            if (!is_numeric($token) && !is_object($token) && isset(self::BINARY_OPERATORS[$token])) {
+            } elseif (!is_numeric($token) && !is_object($token) && isset(self::BINARY_OPERATORS[$token])) {
+                // if the token is a binary operator, pop the top two values off the stack, do the operation, and push the result back on the stack
                 //    We must have two operands, error if we don't
                 if (($operand2Data = $stack->pop()) === null) {
                     return $this->raiseFormulaError('Internal error - Operand value missing from stack');

src/PhpSpreadsheet/Calculation/Calculation.php

@@ -34,8 +34,6 @@ final class StructuredReference implements Operand
 
     private string $tableName;
 
-    private Table $table;
-
     private string $reference;
 
     private ?int $headersRow;
@@ -104,16 +102,16 @@ private function getTableStructure(Cell $cell): void
         preg_match(self::TABLE_REFERENCE, $this->value, $matches);
 
         $this->tableName = $matches[1];
-        $this->table = ($this->tableName === '')
+        $table = ($this->tableName === '')
             ? $this->getTableForCell($cell)
             : $this->getTableByName($cell);
         $this->reference = $matches[2];
-        $tableRange = Coordinate::getRangeBoundaries($this->table->getRange());
+        $tableRange = Coordinate::getRangeBoundaries($table->getRange());
 
-        $this->headersRow = ($this->table->getShowHeaderRow()) ? (int) $tableRange[0][1] : null;
-        $this->firstDataRow = ($this->table->getShowHeaderRow()) ? (int) $tableRange[0][1] + 1 : $tableRange[0][1];
-        $this->totalsRow = ($this->table->getShowTotalsRow()) ? (int) $tableRange[1][1] : null;
-        $this->lastDataRow = ($this->table->getShowTotalsRow()) ? (int) $tableRange[1][1] - 1 : $tableRange[1][1];
+        $this->headersRow = ($table->getShowHeaderRow()) ? (int) $tableRange[0][1] : null;
+        $this->firstDataRow = ($table->getShowHeaderRow()) ? (int) $tableRange[0][1] + 1 : $tableRange[0][1];
+        $this->totalsRow = ($table->getShowTotalsRow()) ? (int) $tableRange[1][1] : null;
+        $this->lastDataRow = ($table->getShowTotalsRow()) ? (int) $tableRange[1][1] - 1 : $tableRange[1][1];
 
         $this->columns = $this->getColumns($cell, $tableRange);
     }
@@ -180,16 +178,18 @@ private function getRowReference(Cell $cell): string
         foreach ($this->columns as $columnId => $columnName) {
             $columnName = str_replace("\u{a0}", ' ', $columnName);
             $cellReference = $columnId . $cell->getRow();
+            $pattern1 = '/\[' . preg_quote($columnName) . '\]/miu';
+            $pattern2 = '/@' . preg_quote($columnName) . '/miu';
             /** @var string $reference */
-            if (stripos($reference, '[' . $columnName . ']') !== false) {
-                $reference = preg_replace('/\[' . preg_quote($columnName) . '\]/miu', $cellReference, $reference);
-            } elseif (stripos($reference, $columnName) !== false) {
-                $reference = preg_replace('/@' . preg_quote($columnName) . '/miu', $cellReference, $reference);
+            if (preg_match($pattern1, $reference) === 1) {
+                $reference = preg_replace($pattern1, $cellReference, $reference);
+            } elseif (preg_match($pattern2, $reference) === 1) {
+                $reference = preg_replace($pattern2, $cellReference, $reference);
             }
         }
 
         /** @var string $reference */
-        return $this->validateParsedReference(trim($reference, '[]@ '));
+        return $this->validateParsedReference(trim($reference, '[]@, '));
     }
 
     /**
@@ -202,43 +202,10 @@ private function getColumnReference(): string
         $startRow = ($this->totalsRow === null) ? $this->lastDataRow : $this->totalsRow;
         $endRow = ($this->headersRow === null) ? $this->firstDataRow : $this->headersRow;
 
-        $rowsSelected = false;
-        foreach (self::ITEM_SPECIFIER_ROWS_SET as $rowReference) {
-            /** @var string $reference */
-            if (stripos($reference, '[' . $rowReference . ']') !== false) {
-                $rowsSelected = true;
-                $startRow = min($startRow, $this->getMinimumRow($rowReference));
-                $endRow = max($endRow, $this->getMaximumRow($rowReference));
-                $reference = preg_replace('/\[' . $rowReference . '\],/mui', '', $reference);
-            }
-        }
-        if ($rowsSelected === false) {
-            // If there isn't any Special Item Identifier specified, then the selection defaults to data rows only.
-            $startRow = $this->firstDataRow;
-            $endRow = $this->lastDataRow;
-        }
+        [$startRow, $endRow] = $this->getRowsForColumnReference($reference, $startRow, $endRow);
+        $reference = $this->getColumnsForColumnReference($reference, $startRow, $endRow);
 
-        $columnsSelected = false;
-        foreach ($this->columns as $columnId => $columnName) {
-            $columnName = str_replace("\u{a0}", ' ', $columnName);
-            $cellFrom = "{$columnId}{$startRow}";
-            $cellTo = "{$columnId}{$endRow}";
-            $cellReference = ($cellFrom === $cellTo) ? $cellFrom : "{$cellFrom}:{$cellTo}";
-            /** @var string $reference */
-            if (stripos($reference, '[' . $columnName . ']') !== false) {
-                $columnsSelected = true;
-                $reference = preg_replace('/\[' . preg_quote($columnName) . '\]/miu', $cellReference, $reference);
-            } elseif (stripos($reference, $columnName) !== false) {
-                $reference = preg_replace('/@' . preg_quote($columnName) . '/miu', $cellReference, $reference);
-                $columnsSelected = true;
-            }
-        }
-        if ($columnsSelected === false) {
-            return $this->fullData($startRow, $endRow);
-        }
-
-        /** @var string $reference */
-        $reference = trim($reference, '[]@ ');
+        $reference = trim($reference, '[]@, ');
         if (substr_count($reference, ':') > 1) {
             $cells = explode(':', $reference);
             $firstCell = array_shift($cells);
@@ -284,6 +251,8 @@ private function getMinimumRow(string $reference): int
             case self::ITEM_SPECIFIER_TOTALS:
                 return $this->totalsRow ?? $this->lastDataRow;
         }
+
+        return $this->headersRow ?? $this->firstDataRow;
     }
 
     private function getMaximumRow(string $reference): int
@@ -297,10 +266,59 @@ private function getMaximumRow(string $reference): int
             case self::ITEM_SPECIFIER_TOTALS:
                 return $this->totalsRow ?? $this->lastDataRow;
         }
+
+        return $this->totalsRow ?? $this->lastDataRow;
     }
 
     public function value(): string
     {
         return $this->value;
     }
+
+    /**
+     * @return array<int, int>
+     */
+    private function getRowsForColumnReference(string &$reference, int $startRow, int $endRow): array
+    {
+        $rowsSelected = false;
+        foreach (self::ITEM_SPECIFIER_ROWS_SET as $rowReference) {
+            $pattern = '/\[' . $rowReference . '\]/mui';
+            /** @var string $reference */
+            if (preg_match($pattern, $reference) === 1) {
+                $rowsSelected = true;
+                $startRow = min($startRow, $this->getMinimumRow($rowReference));
+                $endRow = max($endRow, $this->getMaximumRow($rowReference));
+                $reference = preg_replace($pattern, '', $reference);
+            }
+        }
+        if ($rowsSelected === false) {
+            // If there isn't any Special Item Identifier specified, then the selection defaults to data rows only.
+            $startRow = $this->firstDataRow;
+            $endRow = $this->lastDataRow;
+        }
+
+        return [$startRow, $endRow];
+    }
+
+    private function getColumnsForColumnReference(string $reference, int $startRow, int $endRow): string
+    {
+        $columnsSelected = false;
+        foreach ($this->columns as $columnId => $columnName) {
+            $columnName = str_replace("\u{a0}", ' ', $columnName);
+            $cellFrom = "{$columnId}{$startRow}";
+            $cellTo = "{$columnId}{$endRow}";
+            $cellReference = ($cellFrom === $cellTo) ? $cellFrom : "{$cellFrom}:{$cellTo}";
+            $pattern = '/\[' . preg_quote($columnName) . '\]/mui';
+            if (preg_match($pattern, $reference) === 1) {
+                $columnsSelected = true;
+                $reference = preg_replace($pattern, $cellReference, $reference);
+            }
+            /** @var string $reference */
+        }
+        if ($columnsSelected === false) {
+            return $this->fullData($startRow, $endRow);
+        }
+
+        return $reference;
+    }
 }

src/PhpSpreadsheet/Calculation/Engine/Operands/StructuredReference.php

@@ -51,8 +51,11 @@ public static function rate($values, $dates, $guess = self::DEFAULT_GUESS)
         $f2 = self::xnpvOrdered($x2, $values, $dates, false);
         $found = false;
         for ($i = 0; $i < self::FINANCIAL_MAX_ITERATIONS; ++$i) {
-            if (!is_numeric($f1) || !is_numeric($f2)) {
-                break;
+            if (!is_numeric($f1)) {
+                return $f1;
+            }
+            if (!is_numeric($f2)) {
+                return $f2;
             }
             $f1 = (float) $f1;
             $f2 = (float) $f2;
@@ -68,11 +71,32 @@ public static function rate($values, $dates, $guess = self::DEFAULT_GUESS)
                 $f2 = self::xnpvOrdered($x2, $values, $dates, false);
             }
         }
-        if (!$found) {
-            return ExcelError::NAN();
+        if ($found) {
+            return self::xirrPart3($values, $dates, $x1, $x2);
         }
 
-        return self::xirrPart3($values, $dates, $x1, $x2);
+        // Newton-Raphson didn't work - try bisection
+        $x1 = $guess - 0.5;
+        $x2 = $guess + 0.5;
+        for ($i = 0; $i < self::FINANCIAL_MAX_ITERATIONS; ++$i) {
+            $f1 = self::xnpvOrdered($x1, $values, $dates, false, true);
+            $f2 = self::xnpvOrdered($x2, $values, $dates, false, true);
+            if (!is_numeric($f1) || !is_numeric($f2)) {
+                break;
+            }
+            if ($f1 * $f2 <= 0) {
+                $found = true;
+
+                break;
+            }
+            $x1 -= 0.5;
+            $x2 += 0.5;
+        }
+        if ($found) {
+            return self::xirrBisection($values, $dates, $x1, $x2);
+        }
+
+        return ExcelError::NAN();
     }
 
     /**
@@ -190,14 +214,53 @@ private static function xirrPart3(array $values, array $dates, float $x1, float
         return $rslt;
     }
 
+    /**
+     * @return float|string
+     */
+    private static function xirrBisection(array $values, array $dates, float $x1, float $x2)
+    {
+        $rslt = ExcelError::NAN();
+        for ($i = 0; $i < self::FINANCIAL_MAX_ITERATIONS; ++$i) {
+            $rslt = ExcelError::NAN();
+            $f1 = self::xnpvOrdered($x1, $values, $dates, false, true);
+            $f2 = self::xnpvOrdered($x2, $values, $dates, false, true);
+            if (!is_numeric($f1) || !is_numeric($f2)) {
+                break;
+            }
+            $f1 = (float) $f1;
+            $f2 = (float) $f2;
+            if (abs($f1) < self::FINANCIAL_PRECISION && abs($f2) < self::FINANCIAL_PRECISION) {
+                break;
+            }
+            if ($f1 * $f2 > 0) {
+                break;
+            }
+            $rslt = ($x1 + $x2) / 2;
+            $f3 = self::xnpvOrdered($rslt, $values, $dates, false, true);
+            if (!is_float($f3)) {
+                break;
+            }
+            if ($f3 * $f1 < 0) {
+                $x2 = $rslt;
+            } else {
+                $x1 = $rslt;
+            }
+            if (abs($f3) < self::FINANCIAL_PRECISION) {
+                break;
+            }
+        }
+
+        return $rslt;
+    }
+
     /**
      * @param mixed $rate
      * @param mixed $values
      * @param mixed $dates
      *
      * @return float|string
      */
-    private static function xnpvOrdered($rate, $values, $dates, bool $ordered = true)
+    private static function xnpvOrdered($rate, $values, $dates, bool $ordered = true, bool $capAtNegative1 = false)
     {
         $rate = Functions::flattenSingleValue($rate);
         $values = Functions::flattenArray($values);
@@ -206,6 +269,9 @@ private static function xnpvOrdered($rate, $values, $dates, bool $ordered = true
 
         try {
             self::validateXnpv($rate, $values, $dates);
+            if ($capAtNegative1 && $rate <= -1) {
+                $rate = -1.0 + 1.0E-10;
+            }
             $date0 = DateTimeExcel\Helpers::getDateValue($dates[0]);
         } catch (Exception $e) {
             return $e->getMessage();