Merge pull request #3033 from PHPOffice/ExcelFunctions-ValueToText

Implementation of the `VALUETOTEXT()` Excel Function

Author: MarkBaker

CHANGELOG.md

@@ -10,7 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 ### Added
 
 - Implementation of the new `TEXTBEFORE()`, `TEXTAFTER()` and `TEXTSPLIT()` Excel Functions
-- Implementation of the `ARRAYTOTEXT()` Excel Function
+- Implementation of the `ARRAYTOTEXT()` and `VALUETOTEXT()` Excel Functions
 - Support for [mitoteam/jpgraph](https://packagist.org/packages/mitoteam/jpgraph) implementation of
   JpGraph library to render charts added.
 - Charts: Add Gradients, Transparency, Hidden Axes, Rounded Corners, Trendlines.

src/PhpSpreadsheet/Calculation/Calculation.php

@@ -2659,8 +2659,8 @@ class Calculation
         ],
         'VALUETOTEXT' => [
             'category' => Category::CATEGORY_TEXT_AND_DATA,
-            'functionCall' => [Functions::class, 'DUMMY'],
-            'argumentCount' => '?',
+            'functionCall' => [TextData\Format::class, 'valueToText'],
+            'argumentCount' => '1,2',
         ],
         'VAR' => [
             'category' => Category::CATEGORY_STATISTICAL,

src/PhpSpreadsheet/Calculation/Engineering/ConvertUOM.php

@@ -106,6 +106,7 @@ class ConvertUOM
         'W' => ['Group' => self::CATEGORY_POWER, 'Unit Name' => 'Watt', 'AllowPrefix' => true],
         'w' => ['Group' => self::CATEGORY_POWER, 'Unit Name' => 'Watt', 'AllowPrefix' => true],
         'PS' => ['Group' => self::CATEGORY_POWER, 'Unit Name' => 'Pferdestärke', 'AllowPrefix' => false],
+        // Magnetism
         'T' => ['Group' => self::CATEGORY_MAGNETISM, 'Unit Name' => 'Tesla', 'AllowPrefix' => true],
         'ga' => ['Group' => self::CATEGORY_MAGNETISM, 'Unit Name' => 'Gauss', 'AllowPrefix' => true],
         // Temperature

src/PhpSpreadsheet/Calculation/TextData/Format.php

@@ -4,11 +4,13 @@
 
 use DateTimeInterface;
 use PhpOffice\PhpSpreadsheet\Calculation\ArrayEnabled;
+use PhpOffice\PhpSpreadsheet\Calculation\Calculation;
 use PhpOffice\PhpSpreadsheet\Calculation\DateTimeExcel;
 use PhpOffice\PhpSpreadsheet\Calculation\Exception as CalcExp;
 use PhpOffice\PhpSpreadsheet\Calculation\Functions;
 use PhpOffice\PhpSpreadsheet\Calculation\Information\ExcelError;
 use PhpOffice\PhpSpreadsheet\Calculation\MathTrig;
+use PhpOffice\PhpSpreadsheet\RichText\RichText;
 use PhpOffice\PhpSpreadsheet\Shared\Date;
 use PhpOffice\PhpSpreadsheet\Shared\StringHelper;
 use PhpOffice\PhpSpreadsheet\Style\NumberFormat;
@@ -208,6 +210,38 @@ public static function VALUE($value = '')
         return (float) $value;
     }
 
+    /**
+     * TEXT.
+     *
+     * @param mixed $value The value to format
+     *                         Or can be an array of values
+     * @param mixed $format
+     *
+     * @return array|string
+     *         If an array of values is passed for either of the arguments, then the returned result
+     *            will also be an array with matching dimensions
+     */
+    public static function valueToText($value, $format = false)
+    {
+        if (is_array($value) || is_array($format)) {
+            return self::evaluateArrayArguments([self::class, __FUNCTION__], $value, $format);
+        }
+
+        $format = (bool) $format;
+
+        if (is_object($value) && $value instanceof RichText) {
+            $value = $value->getPlainText();
+        }
+        if (is_string($value)) {
+            $value = ($format === true) ? Calculation::wrapResult($value) : $value;
+            $value = str_replace("\n", '', $value);
+        } elseif (is_bool($value)) {
+            $value = Calculation::$localeBoolean[$value === true ? 'TRUE' : 'FALSE'];
+        }
+
+        return (string) $value;
+    }
+
     /**
      * @param mixed $decimalSeparator
      */

tests/PhpSpreadsheetTests/Calculation/Functions/TextData/ValueToTextTest.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace PhpOffice\PhpSpreadsheetTests\Calculation\Functions\TextData;
+
+class ValueToTextTest extends AllSetupTeardown
+{
+    /**
+     * @dataProvider providerVALUE
+     *
+     * @param mixed $expectedResult
+     * @param mixed $value
+     * @param mixed $format
+     */
+    public function testVALUETOTEXT($expectedResult, $value, $format): void
+    {
+        $sheet = $this->getSheet();
+        $this->setCell('A1', $value);
+        $sheet->getCell('B1')->setValue("=VALUETOTEXT(A1, {$format})");
+
+        $result = $sheet->getCell('B1')->getCalculatedValue();
+        self::assertSame($expectedResult, $result);
+    }
+
+    public function providerVALUE(): array
+    {
+        return require 'tests/data/Calculation/TextData/VALUETOTEXT.php';
+    }
+}

tests/data/Calculation/TextData/VALUETOTEXT.php

@@ -0,0 +1,27 @@
+<?php
+
+use PhpOffice\PhpSpreadsheet\RichText\RichText;
+
+$richText1 = new RichText();
+$richText1->createTextRun('Hello');
+$richText1->createText(' World');
+
+$richText2 = new RichText();
+$richText2->createTextRun('Hello');
+$richText2->createText("\nWorld");
+
+return [
+    ['1', 1, 0],
+    ['1.23', 1.23, 0],
+    ['-123.456', -123.456, 0],
+    ['TRUE', true, 0],
+    ['FALSE', false, 0],
+    ['Hello World', 'Hello World', 0],
+    ['HelloWorld', "Hello\nWorld", 0],
+    ['"Hello World"', 'Hello World', 1],
+    ['"HelloWorld"', "Hello\nWorld", 1],
+    ['Hello World', $richText1, 0],
+    ['HelloWorld', $richText2, 0],
+    ['"Hello World"', $richText1, 1],
+    ['"HelloWorld"', $richText2, 1],
+];