Ods Handling of Ceiling and Floor

oleibman · oleibman · commit 39511e03b58e · 2025-05-10T21:40:28.000-07:00
Fix #407, which went stale over 7 years ago, and is now reopened. Ods handling of CEILING and FLOOR functions is, apparently by design, subject to interoperability problems with Excel. See [FLOOR](https://wiki.documentfoundation.org/Documentation/Calc_Functions/FLOOR) and [CEILING](https://wiki.documentfoundation.org/Documentation/Calc_Functions/CEILING). Ods implements its own `CEILING.XCL` and `FLOOR.XCL` functions for interoperability purposes. PhpSpreadsheet will implement those, and `CEILING.ODS` and `FLOOR.ODS` psuedo-functions as well; none of these four will be listed in the official Functions documentation. In all of the descriptions below, FLOOR follows CEILING exactly. Ods writes its functions to Xml as follows: - CEILING.XCL becomes COM.MICROSOFT.CEILING - CEILING.MATH becomes COM.MICROSOFT.CEILING.MATH - CEILING.PRECISE becomes COM.MICROSOFT.CEILING.PRECISE - CEILING remains unchanged PhpSpreadsheet Ods Writer will do the same, plus: - CEILING.ODS becomes CEILING PhpSpreadsheet Ods Reader will act as follows: - CEILING (not preceded by 'COM.MICROSOFT.') becomes CEILING.ODS - COM.MICROSOFT.CEILING.MATH becomes CEILING.MATH - COM.MICROSOFT.CEILING.PRECISE becomes CEILING.PRECISE - COM.MICROSOFT.CEILING becomes CEILING PhpSpreadsheet Xlsx Writer will act as follows: - CEILING.ODS becomes CEILING.MATH - CEILING.XCL becomes CEILING PhpSpreadsheet Xls Writer will recognize only the CEILING and FLOOR functions. Note that the only difference between Ods CEILING and CEILING.MATH is that CEILING will return an error if the number and significance operands have opposite signs. PhpSpreadsheet implements this as `#VALUE!`.
diff --git a/infra/DocumentGenerator.php b/infra/DocumentGenerator.php
@@ -9,6 +9,13 @@
 
 class DocumentGenerator
 {
+    private const EXCLUDED_FUNCTIONS = [
+        'CEILING.ODS',
+        'CEILING.XCL',
+        'FLOOR.ODS',
+        'FLOOR.XCL',
+    ];
+
     /**
      * @param array<string, array{category: string, functionCall: string|string[], argumentCount: string, passCellReference?: bool, passByReference?: bool[], custom?: bool}> $phpSpreadsheetFunctions
      */
@@ -23,6 +30,9 @@ public static function generateFunctionListByCategory($phpSpreadsheetFunctions):
             $result .= self::tableRow($lengths, ['Excel Function', 'PhpSpreadsheet Function']) . "\n";
             $result .= self::tableRow($lengths, null) . "\n";
             foreach ($phpSpreadsheetFunctions as $excelFunction => $functionInfo) {
+                if (in_array($excelFunction, self::EXCLUDED_FUNCTIONS, true)) {
+                    continue;
+                }
                 if ($category === $functionInfo['category']) {
                     $phpFunction = self::getPhpSpreadsheetFunctionText($functionInfo['functionCall']);
                     $result .= self::tableRow($lengths, [$excelFunction, $phpFunction]) . "\n";
@@ -87,6 +97,9 @@ public static function generateFunctionListByName(array $phpSpreadsheetFunctions
         $result = "# Function list by name\n";
         $lastAlphabet = null;
         foreach ($phpSpreadsheetFunctions as $excelFunction => $functionInfo) {
+            if (in_array($excelFunction, self::EXCLUDED_FUNCTIONS, true)) {
+                continue;
+            }
             $lengths = [25, 31, 37];
             if ($lastAlphabet !== $excelFunction[0]) {
                 $lastAlphabet = $excelFunction[0];
diff --git a/src/PhpSpreadsheet/Calculation/FunctionArray.php b/src/PhpSpreadsheet/Calculation/FunctionArray.php
@@ -277,11 +277,23 @@ class FunctionArray extends CalculationBase
             'functionCall' => [MathTrig\Ceiling::class, 'math'],
             'argumentCount' => '1-3',
         ],
+        // pseudo-function to help with Ods
+        'CEILING.ODS' => [
+            'category' => Category::CATEGORY_MATH_AND_TRIG,
+            'functionCall' => [MathTrig\Ceiling::class, 'mathOds'],
+            'argumentCount' => '1-3',
+        ],
         'CEILING.PRECISE' => [
             'category' => Category::CATEGORY_MATH_AND_TRIG,
             'functionCall' => [MathTrig\Ceiling::class, 'precise'],
             'argumentCount' => '1,2',
         ],
+        // pseudo-function implemented in Ods
+        'CEILING.XCL' => [
+            'category' => Category::CATEGORY_MATH_AND_TRIG,
+            'functionCall' => [MathTrig\Ceiling::class, 'ceiling'],
+            'argumentCount' => '2',
+        ],
         'CELL' => [
             'category' => Category::CATEGORY_INFORMATION,
             'functionCall' => [Functions::class, 'DUMMY'],
@@ -914,11 +926,23 @@ class FunctionArray extends CalculationBase
             'functionCall' => [MathTrig\Floor::class, 'math'],
             'argumentCount' => '1-3',
         ],
+        // pseudo-function to help with Ods
+        'FLOOR.ODS' => [
+            'category' => Category::CATEGORY_MATH_AND_TRIG,
+            'functionCall' => [MathTrig\Floor::class, 'mathOds'],
+            'argumentCount' => '1-3',
+        ],
         'FLOOR.PRECISE' => [
             'category' => Category::CATEGORY_MATH_AND_TRIG,
             'functionCall' => [MathTrig\Floor::class, 'precise'],
             'argumentCount' => '1-2',
         ],
+        // pseudo-function implemented in Ods
+        'FLOOR.XCL' => [
+            'category' => Category::CATEGORY_MATH_AND_TRIG,
+            'functionCall' => [MathTrig\Floor::class, 'floor'],
+            'argumentCount' => '2',
+        ],
         'FORECAST' => [
             'category' => Category::CATEGORY_STATISTICAL,
             'functionCall' => [Statistical\Trends::class, 'FORECAST'],
diff --git a/src/PhpSpreadsheet/Calculation/MathTrig/Ceiling.php b/src/PhpSpreadsheet/Calculation/MathTrig/Ceiling.php
@@ -22,12 +22,12 @@ class Ceiling
      * Excel Function:
      *        CEILING(number[,significance])
      *
-     * @param array|float $number the number you want the ceiling
+     * @param array<mixed>|float $number the number you want the ceiling
      *                      Or can be an array of values
-     * @param array|float $significance the multiple to which you want to round
+     * @param array<mixed>|float $significance the multiple to which you want to round
      *                      Or can be an array of values
      *
-     * @return array|float|string Rounded Number, or a string containing an error
+     * @return array<mixed>|float|string Rounded Number, or a string containing an error
      *         If an array of numbers is passed as an argument, then the returned result will also be an array
      *            with the same dimensions
      */
@@ -63,14 +63,14 @@ public static function ceiling($number, $significance = null)
      *                      Or can be an array of values
      * @param mixed $significance Significance
      *                      Or can be an array of values
-     * @param array|int $mode direction to round negative numbers
+     * @param array<mixed>|int $mode direction to round negative numbers
      *                      Or can be an array of values
      *
-     * @return array|float|string Rounded Number, or a string containing an error
+     * @return array<mixed>|float|string Rounded Number, or a string containing an error
      *         If an array of numbers is passed as an argument, then the returned result will also be an array
      *            with the same dimensions
      */
-    public static function math(mixed $number, mixed $significance = null, $mode = 0): array|string|float
+    public static function math(mixed $number, mixed $significance = null, $mode = 0, bool $checkSigns = false): array|string|float
     {
         if (is_array($number) || is_array($significance) || is_array($mode)) {
             return self::evaluateArrayArguments([self::class, __FUNCTION__], $number, $significance, $mode);
@@ -87,6 +87,11 @@ public static function math(mixed $number, mixed $significance = null, $mode = 0
         if (empty($significance * $number)) {
             return 0.0;
         }
+        if ($checkSigns) {
+            if (($number > 0 && $significance < 0) || ($number < 0 && $significance > 0)) {
+                return ExcelError::VALUE();
+            }
+        }
         if (self::ceilingMathTest((float) $significance, (float) $number, (int) $mode)) {
             return floor($number / $significance) * $significance;
         }
@@ -104,10 +109,10 @@ public static function math(mixed $number, mixed $significance = null, $mode = 0
      *
      * @param mixed $number the number you want to round
      *                      Or can be an array of values
-     * @param array|float $significance the multiple to which you want to round
+     * @param array<mixed>|float $significance the multiple to which you want to round
      *                      Or can be an array of values
      *
-     * @return array|float|string Rounded Number, or a string containing an error
+     * @return array<mixed>|float|string Rounded Number, or a string containing an error
      *         If an array of numbers is passed as an argument, then the returned result will also be an array
      *            with the same dimensions
      */
@@ -132,6 +137,23 @@ public static function precise(mixed $number, $significance = 1): array|string|f
         return ceil($result) * $significance * (($significance < 0) ? -1 : 1);
     }
 
+    /**
+     * CEILING.ODS, pseudo-function - CEILING as implemented in ODS.
+     *
+     * ODS Function (theoretical):
+     *        CEILING.ODS(number[,significance[,mode]])
+     *
+     * @param mixed $number Number to round
+     * @param mixed $significance Significance
+     * @param array<mixed>|int $mode direction to round negative numbers
+     *
+     * @return array<mixed>|float|string Rounded Number, or a string containing an error
+     */
+    public static function mathOds(mixed $number, mixed $significance = null, $mode = 0): array|string|float
+    {
+        return self::math($number, $significance, $mode, true);
+    }
+
     /**
      * Let CEILINGMATH complexity pass Scrutinizer.
      */
diff --git a/src/PhpSpreadsheet/Calculation/MathTrig/Floor.php b/src/PhpSpreadsheet/Calculation/MathTrig/Floor.php
@@ -32,7 +32,7 @@ private static function floorCheck1Arg(): void
      * @param mixed $significance Expect float. Significance
      *                      Or can be an array of values
      *
-     * @return array|float|string Rounded Number, or a string containing an error
+     * @return array<mixed>|float|string Rounded Number, or a string containing an error
      *         If an array of numbers is passed as an argument, then the returned result will also be an array
      *            with the same dimensions
      */
@@ -71,11 +71,11 @@ public static function floor(mixed $number, mixed $significance = null)
      * @param mixed $mode direction to round negative numbers
      *                      Or can be an array of values
      *
-     * @return array|float|string Rounded Number, or a string containing an error
+     * @return array<mixed>|float|string Rounded Number, or a string containing an error
      *         If an array of numbers is passed as an argument, then the returned result will also be an array
      *            with the same dimensions
      */
-    public static function math(mixed $number, mixed $significance = null, mixed $mode = 0)
+    public static function math(mixed $number, mixed $significance = null, mixed $mode = 0, bool $checkSigns = false)
     {
         if (is_array($number) || is_array($significance) || is_array($mode)) {
             return self::evaluateArrayArguments([self::class, __FUNCTION__], $number, $significance, $mode);
@@ -89,9 +89,34 @@ public static function math(mixed $number, mixed $significance = null, mixed $mo
             return $e->getMessage();
         }
 
+        if ($checkSigns) {
+            if (($number > 0 && $significance < 0) || ($number < 0 && $significance > 0)) {
+                return ExcelError::VALUE();
+            }
+        }
+
         return self::argsOk((float) $number, (float) $significance, (int) $mode);
     }
 
+    /**
+     * FLOOR.ODS, pseudo-function - FLOOR as implemented in ODS.
+     *
+     * Round a number down to the nearest integer or to the nearest multiple of significance.
+     *
+     * ODS Function (theoretical):
+     *        FLOOR.ODS(number[,significance[,mode]])
+     *
+     * @param mixed $number Number to round
+     * @param mixed $significance Significance
+     * @param array<mixed>|int $mode direction to round negative numbers
+     *
+     * @return array<mixed>|float|string Rounded Number, or a string containing an error
+     */
+    public static function mathOds(mixed $number, mixed $significance = null, mixed $mode = 0)
+    {
+        return self::math($number, $significance, $mode, true);
+    }
+
     /**
      * FLOOR.PRECISE.
      *
@@ -100,12 +125,12 @@ public static function math(mixed $number, mixed $significance = null, mixed $mo
      * Excel Function:
      *        FLOOR.PRECISE(number[,significance])
      *
-     * @param array|float $number Number to round
+     * @param array<mixed>|float $number Number to round
      *                      Or can be an array of values
-     * @param array|float $significance Significance
+     * @param array<mixed>|float $significance Significance
      *                      Or can be an array of values
      *
-     * @return array|float|string Rounded Number, or a string containing an error
+     * @return array<mixed>|float|string Rounded Number, or a string containing an error
      *         If an array of numbers is passed as an argument, then the returned result will also be an array
      *            with the same dimensions
      */
diff --git a/src/PhpSpreadsheet/Reader/Ods/FormulaTranslator.php b/src/PhpSpreadsheet/Reader/Ods/FormulaTranslator.php
@@ -2,6 +2,7 @@
 
 namespace PhpOffice\PhpSpreadsheet\Reader\Ods;
 
+use Composer\Pcre\Preg;
 use PhpOffice\PhpSpreadsheet\Calculation\Calculation;
 
 class FormulaTranslator
@@ -27,7 +28,7 @@ public static function convertToExcelAddressValue(string $openOfficeAddress): st
         // Cell range 3-d reference
         // As we don't support 3-d ranges, we're just going to take a quick and dirty approach
         //  and assume that the second worksheet reference is the same as the first
-        $excelAddress = (string) preg_replace(
+        $excelAddress = Preg::replace(
             [
                 '/\$?([^\.]+)\.([^\.]+):\$?([^\.]+)\.([^\.]+)/miu',
                 '/\$?([^\.]+)\.([^\.]+):\.([^\.]+)/miu', // Cell range reference in another sheet
@@ -62,7 +63,7 @@ public static function convertToExcelFormulaValue(string $openOfficeFormula): st
             //      so that conversion isn't done in string values
             $tKey = $tKey === false;
             if ($tKey) {
-                $value = (string) preg_replace(
+                $value = Preg::replace(
                     [
                         '/\[\$?([^\.]+)\.([^\.]+):\.([^\.]+)\]/miu', // Cell range reference in another sheet
                         '/\[\$?([^\.]+)\.([^\.]+)\]/miu', // Cell reference in another sheet
@@ -103,7 +104,18 @@ public static function convertToExcelFormulaValue(string $openOfficeFormula): st
                     Calculation::FORMULA_CLOSE_MATRIX_BRACE
                 );
 
-                $value = (string) preg_replace('/COM\.MICROSOFT\./ui', '', $value);
+                $value = Preg::replace(
+                    [
+                        '/\b(?<!com[.]microsoft[.])'
+                            . '(floor|ceiling)\s*[(]/ui',
+                        '/COM\.MICROSOFT\./ui',
+                    ],
+                    [
+                        '$1.ODS(',
+                        '',
+                    ],
+                    $value
+                );
             }
         }
 
diff --git a/src/PhpSpreadsheet/Writer/Ods/Formula.php b/src/PhpSpreadsheet/Writer/Ods/Formula.php
@@ -26,6 +26,7 @@ public function convertFormula(string $formula, string $worksheetName = ''): str
     {
         $formula = $this->convertCellReferences($formula, $worksheetName);
         $formula = $this->convertDefinedNames($formula);
+        $formula = $this->convertFunctionNames($formula);
 
         if (!str_starts_with($formula, '=')) {
             $formula = '=' . $formula;
@@ -117,4 +118,22 @@ private function convertCellReferences(string $formula, string $worksheetName):
 
         return $formula;
     }
+
+    private function convertFunctionNames(string $formula): string
+    {
+        return Preg::replace(
+            [
+                '/\b((CEILING|FLOOR)'
+                    . '([.](MATH|PRECISE))?)\s*[(]/ui',
+                '/\b(CEILING|FLOOR)[.]XCL\s*[(]/ui',
+                '/\b(CEILING|FLOOR)[.]ODS\s*[(]/ui',
+            ],
+            [
+                'COM.MICROSOFT.$1(',
+                'COM.MICROSOFT.$1(',
+                '$1(',
+            ],
+            $formula
+        );
+    }
 }
diff --git a/src/PhpSpreadsheet/Writer/Xlsx/FunctionPrefix.php b/src/PhpSpreadsheet/Writer/Xlsx/FunctionPrefix.php
@@ -216,6 +216,18 @@ public static function addFunctionPrefix(string $functionString): string
      */
     public static function addFunctionPrefixStripEquals(string $functionString): string
     {
+        $functionString = Preg::replace(
+            [
+                '/\b(CEILING|FLOOR)[.]ODS\s*[(]/',
+                '/\b(CEILING|FLOOR)[.]XCL\s*[(]/',
+            ],
+            [
+                '$1.MATH(',
+                '$1(',
+            ],
+            $functionString
+        );
+
         return self::addFunctionPrefix(substr($functionString, 1));
     }
 }
diff --git a/tests/PhpSpreadsheetTests/Reader/Ods/CeilingFloorTest.php b/tests/PhpSpreadsheetTests/Reader/Ods/CeilingFloorTest.php
diff --git a/tests/data/Reader/Ods/issue.407.ods b/tests/data/Reader/Ods/issue.407.ods

Original file line number	Diff line number	Diff line change
`@@ -216,6 +216,18 @@ public static function addFunctionPrefix(string $functionString): string`
`216`	`216`	`*/`
`217`	`217`	`public static function addFunctionPrefixStripEquals(string $functionString): string`
`218`	`218`	`{`
	`219`	`+ $functionString = Preg::replace(`
	`220`	`+ [`
	`221`	`+ '/\b(CEILING\|FLOOR)[.]ODS\s*[(]/',`
	`222`	`+ '/\b(CEILING\|FLOOR)[.]XCL\s*[(]/',`
	`223`	`+ ],`
	`224`	`+ [`
	`225`	`+ '$1.MATH(',`
	`226`	`+ '$1(',`
	`227`	`+ ],`
	`228`	`+ $functionString`
	`229`	`+ );`
	`230`	`+`
`219`	`231`	`return self::addFunctionPrefix(substr($functionString, 1));`
`220`	`232`	`}`
`221`	`233`	`}`