Function N (#1606)

sequba · web-flow · commit a1fb6002f666 · 2026-01-14T10:28:30.000+01:00
* Add tests for function N

* Add function N

* Fix linter error
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 ### Added
 
 - 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)
 
 ## [3.1.1] - 2025-12-18
 
diff --git a/docs/guide/built-in-functions.md b/docs/guide/built-in-functions.md
@@ -492,6 +492,7 @@ Total number of functions: **{{ $page.functionsCount }}**
 | LEN         | Returns length of a given text.                                                                                                                                                                                                                                                                                                 | LEN("Text")                                        |
 | LOWER       | Returns text converted to lowercase.                                                                                                                                                                                                                                                                                            | LOWER(Text)                                        |
 | MID         | Returns substring of a given length starting from Start_position.                                                                                                                                                                                                                                                               | MID(Text, Start_position, Length)                  |
+| N           | Converts a value to a number.                                                                                                                                                                                                                                                                                                   | N(Value)                                           |
 | PROPER      | Capitalizes words given text string.                                                                                                                                                                                                                                                                                            | PROPER("Text")                                     |
 | REPLACE     | Replaces substring of a text of a given length that starts at given position.                                                                                                                                                                                                                                                   | REPLACE(Text, Start_position, Length, New_text)    |
 | REPT        | Repeats text a given number of times.                                                                                                                                                                                                                                                                                           | REPT("Text", Number)                               |
diff --git a/src/i18n/languages/csCZ.ts b/src/i18n/languages/csCZ.ts
@@ -149,6 +149,7 @@ const dictionary: RawTranslationPackage = {
     MMULT: 'SOUČIN.MATIC',
     MOD: 'MOD',
     MONTH: 'MĚSÍC',
+    N: 'N',
     NA: 'NEDEF',
     NETWORKDAYS: 'NETWORKDAYS',
     'NETWORKDAYS.INTL': 'NETWORKDAYS.INTL',
diff --git a/src/i18n/languages/daDK.ts b/src/i18n/languages/daDK.ts
@@ -149,6 +149,7 @@ const dictionary: RawTranslationPackage = {
     MMULT: 'MPRODUKT',
     MOD: 'REST',
     MONTH: 'MÅNED',
+    N: 'TAL',
     NA: 'IKKE.TILGÆNGELIG',
     NETWORKDAYS: 'ANTAL.ARBEJDSDAGE',
     'NETWORKDAYS.INTL': 'ANTAL.ARBEJDSDAGE.INTL',
diff --git a/src/i18n/languages/deDE.ts b/src/i18n/languages/deDE.ts
@@ -149,6 +149,7 @@ const dictionary: RawTranslationPackage = {
     MMULT: 'MMULT',
     MOD: 'REST',
     MONTH: 'MONAT',
+    N: 'N',
     NA: 'NV',
     NETWORKDAYS: 'NETTOARBEITSTAGE',
     'NETWORKDAYS.INTL': 'NETTOARBEITSTAGE.INTL',
diff --git a/src/i18n/languages/enGB.ts b/src/i18n/languages/enGB.ts
@@ -150,6 +150,7 @@ const dictionary: RawTranslationPackage = {
     MMULT: 'MMULT',
     MOD: 'MOD',
     MONTH: 'MONTH',
+    N: 'N',
     NA: 'NA',
     NETWORKDAYS: 'NETWORKDAYS',
     'NETWORKDAYS.INTL': 'NETWORKDAYS.INTL',
diff --git a/src/i18n/languages/esES.ts b/src/i18n/languages/esES.ts
@@ -149,6 +149,7 @@ export const dictionary: RawTranslationPackage = {
     MMULT: 'MMULT',
     MOD: 'RESIDUO',
     MONTH: 'MES',
+    N: 'N',
     NA: 'NOD',
     NETWORKDAYS: 'DIAS.LAB',
     'NETWORKDAYS.INTL': 'DIAS.LAB.INTL',
diff --git a/src/i18n/languages/fiFI.ts b/src/i18n/languages/fiFI.ts
@@ -149,6 +149,7 @@ const dictionary: RawTranslationPackage = {
     MMULT: 'MKERRO',
     MOD: 'JAKOJ',
     MONTH: 'KUUKAUSI',
+    N: 'N',
     NA: 'PUUTTUU',
     NETWORKDAYS: 'TYÖPÄIVÄT',
     'NETWORKDAYS.INTL': 'TYÖPÄIVÄT.KANSVÄL',
diff --git a/src/i18n/languages/frFR.ts b/src/i18n/languages/frFR.ts
@@ -149,6 +149,7 @@ const dictionary: RawTranslationPackage = {
     MMULT: 'PRODUITMAT',
     MOD: 'MOD',
     MONTH: 'MOIS',
+    N: 'N',
     NA: 'NA',
     NETWORKDAYS: 'NB.JOURS.OUVRES',
     'NETWORKDAYS.INTL': 'NB.JOURS.OUVRES.INTL',
diff --git a/src/i18n/languages/huHU.ts b/src/i18n/languages/huHU.ts
@@ -149,6 +149,7 @@ const dictionary: RawTranslationPackage = {
     MMULT: 'MSZORZAT',
     MOD: 'MARADÉK',
     MONTH: 'HÓNAP',
+    N: 'S',
     NA: 'HIÁNYZIK',
     NETWORKDAYS: 'ÖSSZ.MUNKANAP',
     'NETWORKDAYS.INTL': 'ÖSSZ.MUNKANAP.INTL',
diff --git a/src/i18n/languages/itIT.ts b/src/i18n/languages/itIT.ts
@@ -149,6 +149,7 @@ const dictionary: RawTranslationPackage = {
     MMULT: 'MATR.PRODOTTO',
     MOD: 'RESTO',
     MONTH: 'MESE',
+    N: 'NUM',
     NA: 'NON.DISP',
     NETWORKDAYS: 'GIORNI.LAVORATIVI.TOT',
     'NETWORKDAYS.INTL': 'GIORNI.LAVORATIVI.TOT.INTL',
diff --git a/src/i18n/languages/nbNO.ts b/src/i18n/languages/nbNO.ts
@@ -149,6 +149,7 @@ const dictionary: RawTranslationPackage = {
     MMULT: 'MMULT',
     MOD: 'REST',
     MONTH: 'MÅNED',
+    N: 'N',
     NA: 'IT',
     NETWORKDAYS: 'NETT.ARBEIDSDAGER',
     'NETWORKDAYS.INTL': 'NETT.ARBEIDSDAGER.INTL',
diff --git a/src/i18n/languages/nlNL.ts b/src/i18n/languages/nlNL.ts
@@ -149,6 +149,7 @@ const dictionary: RawTranslationPackage = {
     MMULT: 'PRODUCTMAT',
     MOD: 'REST',
     MONTH: 'MAAND',
+    N: 'N',
     NA: 'NB',
     NETWORKDAYS: 'NETTO.WERKDAGEN',
     'NETWORKDAYS.INTL': 'NETWERKDAGEN.INTL',
diff --git a/src/i18n/languages/plPL.ts b/src/i18n/languages/plPL.ts
@@ -149,6 +149,7 @@ const dictionary: RawTranslationPackage = {
     MMULT: 'MACIERZ.ILOCZYN',
     MOD: 'MOD',
     MONTH: 'MIESIĄC',
+    N: 'N',
     NA: 'BRAK',
     NETWORKDAYS: 'DNI.ROBOCZE',
     'NETWORKDAYS.INTL': 'DNI.ROBOCZE.NIESTAND',
diff --git a/src/i18n/languages/ptPT.ts b/src/i18n/languages/ptPT.ts
@@ -149,6 +149,7 @@ const dictionary: RawTranslationPackage = {
     MMULT: 'MATRIZ.MULT',
     MOD: 'MOD',
     MONTH: 'MÊS',
+    N: 'N',
     NA: 'NÃO.DISP',
     NETWORKDAYS: 'DIATRABALHOTOTAL',
     'NETWORKDAYS.INTL': 'DIATRABALHOTOTAL.INTL',
diff --git a/src/i18n/languages/ruRU.ts b/src/i18n/languages/ruRU.ts
@@ -149,6 +149,7 @@ const dictionary: RawTranslationPackage = {
     MMULT: 'МУМНОЖ',
     MOD: 'ОСТАТ',
     MONTH: 'МЕСЯЦ',
+    N: 'Ч',
     NA: 'НД',
     NETWORKDAYS: 'ЧИСТРАБДНИ',
     'NETWORKDAYS.INTL': 'ЧИСТРАБДНИ.МЕЖД',
diff --git a/src/i18n/languages/svSE.ts b/src/i18n/languages/svSE.ts
@@ -149,6 +149,7 @@ const dictionary: RawTranslationPackage = {
     MMULT: 'MMULT',
     MOD: 'REST',
     MONTH: 'MÅNAD',
+    N: 'N',
     NA: 'SAKNAS',
     NETWORKDAYS: 'NETTOARBETSDAGAR',
     'NETWORKDAYS.INTL': 'NETTOARBETSDAGAR.INT',
diff --git a/src/i18n/languages/trTR.ts b/src/i18n/languages/trTR.ts
@@ -149,6 +149,7 @@ const dictionary: RawTranslationPackage = {
     MMULT: 'DÇARP',
     MOD: 'MOD',
     MONTH: 'AY',
+    N: 'S',
     NA: 'YOKSAY',
     NETWORKDAYS: 'TAMİŞGÜNÜ',
     'NETWORKDAYS.INTL': 'TAMİŞGÜNÜ.ULUSL',
diff --git a/src/interpreter/plugin/TextPlugin.ts b/src/interpreter/plugin/TextPlugin.ts
@@ -7,7 +7,8 @@ import {CellError, ErrorType} from '../../Cell'
 import {ErrorMessage} from '../../error-message'
 import {ProcedureAst} from '../../parser'
 import {InterpreterState} from '../InterpreterState'
-import {InterpreterValue, RawScalarValue} from '../InterpreterValue'
+import {InternalScalarValue, InterpreterValue, RawScalarValue} from '../InterpreterValue'
+import {SimpleRangeValue} from '../../SimpleRangeValue'
 import {FunctionArgumentType, FunctionPlugin, FunctionPluginTypecheck, ImplementedFunctions} from './FunctionPlugin'
 
 /**
@@ -69,6 +70,12 @@ export class TextPlugin extends FunctionPlugin implements FunctionPluginTypechec
         {argumentType: FunctionArgumentType.SCALAR}
       ]
     },
+    'N': {
+      method: 'n',
+      parameters: [
+        {argumentType: FunctionArgumentType.ANY}
+      ]
+    },
     'PROPER': {
       method: 'proper',
       parameters: [
@@ -335,6 +342,34 @@ export class TextPlugin extends FunctionPlugin implements FunctionPluginTypechec
     })
   }
 
+  /**
+   * Corresponds to N(value)
+   *
+   * Converts a value to a number according to Excel specification:
+   * - Numbers return themselves
+   * - Dates return their serial number (stored as numbers internally)
+   * - TRUE returns 1, FALSE returns 0
+   * - Error values propagate
+   * - Anything else (text, empty) returns 0
+   * - For ranges, uses the first cell value
+   */
+  public n(ast: ProcedureAst, state: InterpreterState): InterpreterValue {
+    return this.runFunction(ast.args, state, this.metadata('N'), (arg: InternalScalarValue | SimpleRangeValue) => {
+      const value = arg instanceof SimpleRangeValue ? arg.data[0]?.[0] : arg
+
+      if (value instanceof CellError) {
+        return value
+      }
+      if (typeof value === 'number') {
+        return value
+      }
+      if (typeof value === 'boolean') {
+        return value ? 1 : 0
+      }
+      return 0
+    })
+  }
+
   public upper(ast: ProcedureAst, state: InterpreterState): InterpreterValue {
     return this.runFunction(ast.args, state, this.metadata('UPPER'), (arg: string) => {
       return arg.toUpperCase()
diff --git a/test/unit/interpreter/function-n.spec.ts b/test/unit/interpreter/function-n.spec.ts
