Implement VALUE function (#1605)

sequba · budnix · web-flow · commit b87d2815a6eb · 2026-01-14T10:51:09.000+01:00
* Tests for function VALUE

* Function VALUE implementation

* Refactor

---------

Co-authored-by: Krzysztof ‘Budzio’ Budnik &lt;571316+budnix@users.noreply.github.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - Added a new function: IRR. [#1591](https://github.com/handsontable/hyperformula/issues/1591)
 - Added a new function: N. [#1585](https://github.com/handsontable/hyperformula/issues/1585)
+- Added a new function: VALUE. [#1592](https://github.com/handsontable/hyperformula/issues/1592)
 
 ## [3.1.1] - 2025-12-18
 
diff --git a/docs/guide/built-in-functions.md b/docs/guide/built-in-functions.md
@@ -506,6 +506,7 @@ Total number of functions: **{{ $page.functionsCount }}**
 | UNICHAR     | Returns the character created by using provided code point.                                                                                                                                                                                                                                                                     | UNICHAR(Number)                                    |
 | UNICODE     | Returns the Unicode code point of a first character of a text.                                                                                                                                                                                                                                                                  | UNICODE(Text)                                      |
 | UPPER       | Returns text converted to uppercase.                                                                                                                                                                                                                                                                                            | UPPER(Text)                                        |
+| VALUE       | Parses a number, date, time, datetime, currency, or percentage from a text string.                                                                                                                                                                                                                                                                         | VALUE(Text)                                        |
 
 [^non-odff]:
     The return value of this function is compliant with the
diff --git a/package.json b/package.json
@@ -78,7 +78,7 @@
     "test": "npm-run-all lint test:unit test:browser test:compatibility",
     "test:unit": "cross-env NODE_ICU_DATA=node_modules/full-icu jest",
     "test:watch": "cross-env NODE_ICU_DATA=node_modules/full-icu jest --watch",
-    "test:tdd": "cross-env NODE_ICU_DATA=node_modules/full-icu jest --watch adding-sheet",
+    "test:tdd": "cross-env NODE_ICU_DATA=node_modules/full-icu jest --watch function-value",
     "test:coverage": "npm run test:unit -- --coverage",
     "test:logMemory": "cross-env NODE_ICU_DATA=node_modules/full-icu jest --runInBand --logHeapUsage",
     "test:unit.ci": "cross-env NODE_ICU_DATA=node_modules/full-icu node --expose-gc ./node_modules/jest/bin/jest --forceExit",
diff --git a/src/NumberLiteralHelper.ts b/src/NumberLiteralHelper.ts
@@ -16,7 +16,7 @@ export class NumberLiteralHelper {
     const thousandSeparator = this.config.thousandSeparator === '.' ? `\\${this.config.thousandSeparator}` : this.config.thousandSeparator
     const decimalSeparator = this.config.decimalSeparator === '.' ? `\\${this.config.decimalSeparator}` : this.config.decimalSeparator
 
-    this.numberPattern = new RegExp(`^([+-]?((${decimalSeparator}\\d+)|(\\d+(${thousandSeparator}\\d{3,})*(${decimalSeparator}\\d*)?)))(e[+-]?\\d+)?$`)
+    this.numberPattern = new RegExp(`^([+-]?((${decimalSeparator}\\d+)|(\\d+(${thousandSeparator}\\d{3,})*(${decimalSeparator}\\d*)?)))([eE][+-]?\\d+)?$`)
     this.allThousandSeparatorsRegex = new RegExp(`${thousandSeparator}`, 'g')
   }
 
diff --git a/src/i18n/languages/csCZ.ts b/src/i18n/languages/csCZ.ts
@@ -225,6 +225,7 @@ const dictionary: RawTranslationPackage = {
     UNICHAR: 'UNICHAR',
     UNICODE: 'UNICODE',
     UPPER: 'VELKÁ',
+    VALUE: 'HODNOTA',
     VARA: 'VARA',
     'VAR.P': 'VAR.P',
     VARPA: 'VARPA',
diff --git a/src/i18n/languages/daDK.ts b/src/i18n/languages/daDK.ts
@@ -225,6 +225,7 @@ const dictionary: RawTranslationPackage = {
     UNICHAR: 'UNICHAR',
     UNICODE: 'UNICODE',
     UPPER: 'STORE.BOGSTAVER',
+    VALUE: 'VÆRDI',
     VARA: 'VARIANSV',
     'VAR.P': 'VARIANS.P',
     VARPA: 'VARIANSPV',
diff --git a/src/i18n/languages/deDE.ts b/src/i18n/languages/deDE.ts
@@ -225,6 +225,7 @@ const dictionary: RawTranslationPackage = {
     UNICHAR: 'UNIZEICHEN',
     UNICODE: 'UNICODE',
     UPPER: 'GROSS',
+    VALUE: 'WERT',
     VARA: 'VARIANZA',
     'VAR.P': 'VAR.P',
     VARPA: 'VARIANZENA',
diff --git a/src/i18n/languages/enGB.ts b/src/i18n/languages/enGB.ts
@@ -227,6 +227,7 @@ const dictionary: RawTranslationPackage = {
     UNICHAR: 'UNICHAR',
     UNICODE: 'UNICODE',
     UPPER: 'UPPER',
+    VALUE: 'VALUE',
     VARA: 'VARA',
     'VAR.P': 'VAR.P',
     VARPA: 'VARPA',
diff --git a/src/i18n/languages/esES.ts b/src/i18n/languages/esES.ts
@@ -225,6 +225,7 @@ export const dictionary: RawTranslationPackage = {
     UNICHAR: 'UNICHAR',
     UNICODE: 'UNICODE',
     UPPER: 'MAYUSC',
+    VALUE: 'VALOR',
     VARA: 'VARA',
     'VAR.P': 'VAR.P',
     VARPA: 'VARPA',
diff --git a/src/i18n/languages/fiFI.ts b/src/i18n/languages/fiFI.ts
@@ -225,6 +225,7 @@ const dictionary: RawTranslationPackage = {
     UNICHAR: 'UNICODEMERKKI',
     UNICODE: 'UNICODE',
     UPPER: 'ISOT',
+    VALUE: 'ARVO',
     VARA: 'VARA',
     'VAR.P': 'VAR.P',
     VARPA: 'VARPA',
diff --git a/src/i18n/languages/frFR.ts b/src/i18n/languages/frFR.ts
@@ -225,6 +225,7 @@ const dictionary: RawTranslationPackage = {
     UNICHAR: 'UNICAR',
     UNICODE: 'UNICODE',
     UPPER: 'MAJUSCULE',
+    VALUE: 'CNUM',
     VARA: 'VARA',
     'VAR.P': 'VAR.P.N',
     VARPA: 'VARPA',
diff --git a/src/i18n/languages/huHU.ts b/src/i18n/languages/huHU.ts
@@ -225,6 +225,7 @@ const dictionary: RawTranslationPackage = {
     UNICHAR: 'UNIKARAKTER',
     UNICODE: 'UNICODE',
     UPPER: 'NAGYBETŰS',
+    VALUE: 'ÉRTÉK',
     VARA: 'VARA',
     'VAR.P': 'VAR.S',
     VARPA: 'VARPA',
diff --git a/src/i18n/languages/itIT.ts b/src/i18n/languages/itIT.ts
@@ -225,6 +225,7 @@ const dictionary: RawTranslationPackage = {
     UNICHAR: 'CARATT.UNI',
     UNICODE: 'UNICODE',
     UPPER: 'MAIUSC',
+    VALUE: 'VALORE',
     VARA: 'VAR.VALORI',
     'VAR.P': 'VAR.P',
     VARPA: 'VAR.POP.VALORI',
diff --git a/src/i18n/languages/nbNO.ts b/src/i18n/languages/nbNO.ts
@@ -225,6 +225,7 @@ const dictionary: RawTranslationPackage = {
     UNICHAR: 'UNICODETEGN',
     UNICODE: 'UNICODE',
     UPPER: 'STORE',
+    VALUE: 'VERDI',
     VARA: 'VARIANSA',
     'VAR.P': 'VARIANS.P',
     VARPA: 'VARIANSPA',
diff --git a/src/i18n/languages/nlNL.ts b/src/i18n/languages/nlNL.ts
@@ -225,6 +225,7 @@ const dictionary: RawTranslationPackage = {
     UNICHAR: 'UNITEKEN',
     UNICODE: 'UNICODE',
     UPPER: 'HOOFDLETTERS',
+    VALUE: 'WAARDE',
     VARA: 'VARA',
     'VAR.P': 'VAR.P',
     VARPA: 'VARPA',
diff --git a/src/i18n/languages/plPL.ts b/src/i18n/languages/plPL.ts
@@ -225,6 +225,7 @@ const dictionary: RawTranslationPackage = {
     UNICHAR: 'ZNAK.UNICODE',
     UNICODE: 'UNICODE',
     UPPER: 'LITERY.WIELKIE',
+    VALUE: 'WARTOŚĆ',
     VARA: 'WARIANCJA.A',
     'VAR.P': 'WARIANCJA.POP',
     VARPA: 'WARIANCJA.POPUL.A',
diff --git a/src/i18n/languages/ptPT.ts b/src/i18n/languages/ptPT.ts
@@ -225,6 +225,7 @@ const dictionary: RawTranslationPackage = {
     UNICHAR: 'CARACTUNI',
     UNICODE: 'UNICODE',
     UPPER: 'MAIÚSCULA',
+    VALUE: 'VALOR',
     VARA: 'VARA',
     'VAR.P': 'VAR.P',
     VARPA: 'VARPA',
diff --git a/src/i18n/languages/ruRU.ts b/src/i18n/languages/ruRU.ts
@@ -225,6 +225,7 @@ const dictionary: RawTranslationPackage = {
     UNICHAR: 'ЮНИСИМВ',
     UNICODE: 'UNICODE',
     UPPER: 'ПРОПИСН',
+    VALUE: 'ЗНАЧ',
     VARA: 'ДИСПА',
     'VAR.P': 'ДИСП.Г',
     VARPA: 'ДИСПРА',
diff --git a/src/i18n/languages/svSE.ts b/src/i18n/languages/svSE.ts
@@ -225,6 +225,7 @@ const dictionary: RawTranslationPackage = {
     UNICHAR: 'UNICHAR',
     UNICODE: 'UNICODE',
     UPPER: 'VERSALER',
+    VALUE: 'TEXTNUM',
     VARA: 'VARA',
     'VAR.P': 'VARIANS.P',
     VARPA: 'VARPA',
diff --git a/src/i18n/languages/trTR.ts b/src/i18n/languages/trTR.ts
@@ -225,6 +225,7 @@ const dictionary: RawTranslationPackage = {
     UNICHAR: 'UNICODEKARAKTERİ',
     UNICODE: 'UNICODE',
     UPPER: 'BÜYÜKHARF',
+    VALUE: 'DEĞER',
     VARA: 'VARA',
     'VAR.P': 'VAR.P',
     VARPA: 'VARSA',
diff --git a/src/interpreter/plugin/TextPlugin.ts b/src/interpreter/plugin/TextPlugin.ts
@@ -5,10 +5,11 @@
 
 import {CellError, ErrorType} from '../../Cell'
 import {ErrorMessage} from '../../error-message'
+import {Maybe} from '../../Maybe'
 import {ProcedureAst} from '../../parser'
 import {InterpreterState} from '../InterpreterState'
-import {InternalScalarValue, InterpreterValue, RawScalarValue} from '../InterpreterValue'
 import {SimpleRangeValue} from '../../SimpleRangeValue'
+import {ExtendedNumber, InterpreterValue, isExtendedNumber, RawScalarValue, InternalScalarValue} from '../InterpreterValue'
 import {FunctionArgumentType, FunctionPlugin, FunctionPluginTypecheck, ImplementedFunctions} from './FunctionPlugin'
 
 /**
@@ -149,15 +150,21 @@ export class TextPlugin extends FunctionPlugin implements FunctionPluginTypechec
         {argumentType: FunctionArgumentType.STRING}
       ]
     },
+    'VALUE': {
+      method: 'value',
+      parameters: [
+        {argumentType: FunctionArgumentType.SCALAR}
+      ]
+    },
   }
 
   /**
    * Corresponds to CONCATENATE(value1, [value2, ...])
    *
    * Concatenates provided arguments to one string.
    *
-   * @param ast
-   * @param state
+   * @param {ProcedureAst} ast - The procedure AST node
+   * @param {InterpreterState} state - The interpreter state
    */
   public concatenate(ast: ProcedureAst, state: InterpreterState): InterpreterValue {
     return this.runFunction(ast.args, state, this.metadata('CONCATENATE'), (...args) => {
@@ -170,8 +177,8 @@ export class TextPlugin extends FunctionPlugin implements FunctionPluginTypechec
    *
    * Splits provided string using space separator and returns chunk at zero-based position specified by second argument
    *
-   * @param ast
-   * @param state
+   * @param {ProcedureAst} ast - The procedure AST node
+   * @param {InterpreterState} state - The interpreter state
    */
   public split(ast: ProcedureAst, state: InterpreterState): InterpreterValue {
     return this.runFunction(ast.args, state, this.metadata('SPLIT'), (stringToSplit: string, indexToUse: number) => {
@@ -376,6 +383,63 @@ export class TextPlugin extends FunctionPlugin implements FunctionPluginTypechec
     })
   }
 
+  /**
+   * Corresponds to VALUE(text)
+   *
+   * Converts a text string that represents a number to a number.
+   *
+   * @param {ProcedureAst} ast - The procedure AST node
+   * @param {InterpreterState} state - The interpreter state
+   */
+  public value(ast: ProcedureAst, state: InterpreterState): InterpreterValue {
+    return this.runFunction(ast.args, state, this.metadata('VALUE'), (arg: RawScalarValue): ExtendedNumber | CellError => {
+      if (arg instanceof CellError) {
+        return arg
+      }
+
+      if (isExtendedNumber(arg)) {
+        return arg
+      }
+
+      if (typeof arg !== 'string') {
+        return new CellError(ErrorType.VALUE, ErrorMessage.NumberCoercion)
+      }
+
+      const trimmedArg = arg.trim()
+
+      const parenthesesMatch = /^\(([^()]+)\)$/.exec(trimmedArg)
+      if (parenthesesMatch) {
+        const innerValue = this.parseStringToNumber(parenthesesMatch[1])
+        if (innerValue !== undefined) {
+          return -innerValue
+        }
+      }
+
+      const parsedValue = this.parseStringToNumber(trimmedArg)
+      if (parsedValue !== undefined) {
+        return parsedValue
+      }
+
+      return new CellError(ErrorType.VALUE, ErrorMessage.NumberCoercion)
+    })
+  }
+
+  /**
+   * Parses a string to a numeric value, handling whitespace trimming and empty string validation.
+   *
+   * @param {string} input - The string to parse
+   * @returns {Maybe<ExtendedNumber>} The parsed number or undefined if parsing fails or input is empty
+   */
+  private parseStringToNumber(input: string): Maybe<ExtendedNumber> {
+    const trimmedInput = input.trim()
+
+    if (trimmedInput === '') {
+      return undefined
+    }
+
+    return this.arithmeticHelper.coerceToMaybeNumber(trimmedInput)
+  }
+
   private escapeRegExpSpecialCharacters(text: string): string {
     return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
   }
diff --git a/test/unit/interpreter/function-value.spec.ts b/test/unit/interpreter/function-value.spec.ts

Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,7 @@ export class NumberLiteralHelper {`
`16`	`16`	const thousandSeparator = this.config.thousandSeparator === '.' ? `\\${this.config.thousandSeparator}` : this.config.thousandSeparator
`17`	`17`	const decimalSeparator = this.config.decimalSeparator === '.' ? `\\${this.config.decimalSeparator}` : this.config.decimalSeparator
`18`	`18`
`19`		- this.numberPattern = new RegExp(`^([+-]?((${decimalSeparator}\\d+)\|(\\d+(${thousandSeparator}\\d{3,})(${decimalSeparator}\\d)?)))(e[+-]?\\d+)?$`)
	`19`	+ this.numberPattern = new RegExp(`^([+-]?((${decimalSeparator}\\d+)\|(\\d+(${thousandSeparator}\\d{3,})(${decimalSeparator}\\d)?)))([eE][+-]?\\d+)?$`)
`20`	`20`	this.allThousandSeparatorsRegex = new RegExp(`${thousandSeparator}`, 'g')
`21`	`21`	`}`
`22`	`22`