XLOOKUP function

docs/guide/built-in-functions.md

@@ -227,6 +227,7 @@ Total number of functions: **{{ $page.functionsCount }}**
 | ROW         | Returns row number of a given reference or formula reference if argument not provided.                                                   | ROW([Reference])                                                       |
 | ROWS        | Returns the number of rows in the given reference.                                                                                       | ROWS(Array)                                                            |
 | VLOOKUP     | Searches vertically with reference to adjacent cells to the right.                                                                       | VLOOKUP(Search_Criterion, Array, Index, Sort_Order)                    |
+| XLOOKUP     | The XLOOKUP function searches a range or an array, and then returns the item corresponding to the first match it finds. If no match exists, then XLOOKUP can return the closest (approximate) match. Current limitations: only default match_mode and search_mode are supported, a range of value is returned, not a range, so having XLOOKUP(...):XLOOKUP(...) will not work.                                                                      | XLOOKUP(lookup_value, lookup_array, return_array, [if_not_found], [match_mode], [search_mode])                    |
 
 ### Math and trigonometry
 

src/i18n/languages/csCZ.ts

@@ -232,6 +232,7 @@ const dictionary: RawTranslationPackage = {
     WEEKNUM: 'WEEKNUM',
     WORKDAY: 'WORKDAY',
     'WORKDAY.INTL': 'WORKDAY.INTL',
+    XLOOKUP: 'XVYHLEDAT',
     XNPV: 'XNPV',
     XOR: 'XOR',
     YEAR: 'ROK',

src/i18n/languages/daDK.ts

@@ -232,6 +232,7 @@ const dictionary: RawTranslationPackage = {
     WEEKNUM: 'UGE.NR',
     WORKDAY: 'ARBEJDSDAG',
     'WORKDAY.INTL': 'ARBEJDSDAG.INTL',
+    XLOOKUP: 'XOPSLAG',
     XNPV: 'NETTO.NUTIDSVÆRDI',
     XOR: 'XELLER',
     YEAR: 'ÅR',

src/i18n/languages/deDE.ts

@@ -232,6 +232,7 @@ const dictionary: RawTranslationPackage = {
     WEEKNUM: 'KALENDERWOCHE',
     WORKDAY: 'ARBEITSTAG',
     'WORKDAY.INTL': 'ARBEITSTAG.INTL',
+    XLOOKUP: 'XVERWEIS',
     XNPV: 'XKAPITALWERT',
     XOR: 'XODER',
     YEAR: 'JAHR',

src/i18n/languages/enGB.ts

@@ -236,6 +236,7 @@ const dictionary: RawTranslationPackage = {
     'WORKDAY.INTL': 'WORKDAY.INTL',
     XNPV: 'XNPV',
     XOR: 'XOR',
+    XLOOKUP: 'XLOOKUP',
     YEAR: 'YEAR',
     YEARFRAC: 'YEARFRAC',
     'HF.ADD': 'HF.ADD',

src/i18n/languages/esES.ts

@@ -232,6 +232,7 @@ export const dictionary: RawTranslationPackage = {
     WEEKNUM: 'NUM.DE.SEMANA',
     WORKDAY: 'DIA.LAB',
     'WORKDAY.INTL': 'DIA.LAB.INTL',
+    XLOOKUP: 'BUSCARX',
     XNPV: 'VNA.NO.PER',
     XOR: 'XOR',
     YEAR: 'AÑO',

src/i18n/languages/fiFI.ts

@@ -232,6 +232,7 @@ const dictionary: RawTranslationPackage = {
     WEEKNUM: 'VIIKKO.NRO',
     WORKDAY: 'TYÖPÄIVÄ',
     'WORKDAY.INTL': 'TYÖPÄIVÄ.KANSVÄL',
+    XLOOKUP: 'XHAKU',
     XNPV: 'NNA.JAKSOTON',
     XOR: 'EHDOTON.TAI',
     YEAR: 'VUOSI',

src/i18n/languages/frFR.ts

@@ -232,6 +232,7 @@ const dictionary: RawTranslationPackage = {
     WEEKNUM: 'NO.SEMAINE',
     WORKDAY: 'SERIE.JOUR.OUVRE',
     'WORKDAY.INTL': 'SERIE.JOUR.OUVRE.INTL',
+    XLOOKUP: 'RECHERCHEX',
     XNPV: 'VAN.PAIEMENTS',
     XOR: 'OUX',
     YEAR: 'ANNEE',

src/i18n/languages/huHU.ts

@@ -232,6 +232,7 @@ const dictionary: RawTranslationPackage = {
     WEEKNUM: 'HÉT.SZÁMA',
     WORKDAY: 'KALK.MUNKANAP',
     'WORKDAY.INTL': 'KALK.MUNKANAP.INTL',
+    XLOOKUP: 'XKERES',
     XNPV: 'XNJÉ',
     XOR: 'XVAGY',
     YEAR: 'ÉV',

src/i18n/languages/itIT.ts

@@ -232,6 +232,7 @@ const dictionary: RawTranslationPackage = {
     WEEKNUM: 'NUM.SETTIMANA',
     WORKDAY: 'GIORNO.LAVORATIVO',
     'WORKDAY.INTL': 'GIORNO.LAVORATIVO.INTL',
+    XLOOKUP: 'CERCA.X',
     XNPV: 'VAN.X',
     XOR: 'XOR',
     YEAR: 'ANNO',

src/i18n/languages/nbNO.ts

@@ -232,6 +232,7 @@ const dictionary: RawTranslationPackage = {
     WEEKNUM: 'UKENR',
     WORKDAY: 'ARBEIDSDAG',
     'WORKDAY.INTL': 'ARBEIDSDAG.INTL',
+    XLOOKUP: 'XOPPSLAG',
     XNPV: 'XNNV',
     XOR: 'EKSKLUSIVELLER',
     YEAR: 'ÅR',

src/i18n/languages/nlNL.ts

@@ -232,6 +232,7 @@ const dictionary: RawTranslationPackage = {
     WEEKNUM: 'WEEKNUMMER',
     WORKDAY: 'WERKDAG',
     'WORKDAY.INTL': 'WERKDAG.INTL',
+    XLOOKUP: 'X.ZOEKEN',
     XNPV: 'NHW2',
     XOR: 'EX.OF',
     YEAR: 'JAAR',

src/i18n/languages/plPL.ts

@@ -232,6 +232,7 @@ const dictionary: RawTranslationPackage = {
     WEEKNUM: 'NUM.TYG',
     WORKDAY: 'DZIEŃ.ROBOCZY',
     'WORKDAY.INTL': 'DZIEŃ.ROBOCZY.NIESTAND',
+    XLOOKUP: 'X.WYSZUKAJ',
     XNPV: 'XNPV',
     XOR: 'XOR',
     YEAR: 'ROK',

src/i18n/languages/ptPT.ts

@@ -232,6 +232,7 @@ const dictionary: RawTranslationPackage = {
     WEEKNUM: 'NÚMSEMANA',
     WORKDAY: 'DIATRABALHO',
     'WORKDAY.INTL': 'DIATRABALHO.INTL',
+    XLOOKUP: 'PROCX',
     XNPV: 'XVPL',
     XOR: 'OUEXCL',
     YEAR: 'ANO',

src/i18n/languages/ruRU.ts

@@ -232,6 +232,7 @@ const dictionary: RawTranslationPackage = {
     WEEKNUM: 'НОМНЕДЕЛИ',
     WORKDAY: 'РАБДЕНЬ',
     'WORKDAY.INTL': 'РАБДЕНЬ.МЕЖД',
+    XLOOKUP: 'ПРОСМОТРХ',
     XNPV: 'ЧИСТНЗ',
     XOR: 'ИСКЛИЛИ',
     YEAR: 'ГОД',

src/i18n/languages/svSE.ts

@@ -232,6 +232,7 @@ const dictionary: RawTranslationPackage = {
     WEEKNUM: 'VECKONR',
     WORKDAY: 'ARBETSDAGAR',
     'WORKDAY.INTL': 'ARBETSDAGAR.INT',
+    XLOOKUP: 'XLETAUPP',
     XNPV: 'XNUVÄRDE',
     XOR: 'XOR',
     YEAR: 'ÅR',

src/i18n/languages/trTR.ts

@@ -232,6 +232,7 @@ const dictionary: RawTranslationPackage = {
     WEEKNUM: 'HAFTASAY',
     WORKDAY: 'İŞGÜNÜ',
     'WORKDAY.INTL': 'İŞGÜNÜ.ULUSL',
+    XLOOKUP: 'ÇAPRAZARA',
     XNPV: 'ANBD',
     XOR: 'ÖZELVEYA',
     YEAR: 'YIL',

src/interpreter/plugin/LookupPlugin.ts

@@ -3,45 +3,64 @@
  * Copyright (c) 2024 Handsoncode. All rights reserved.
  */
 
-import {AbsoluteCellRange} from '../../AbsoluteCellRange'
-import {CellError, ErrorType, simpleCellAddress} from '../../Cell'
-import {ErrorMessage} from '../../error-message'
-import {RowSearchStrategy} from '../../Lookup/RowSearchStrategy'
-import {SearchOptions, SearchStrategy} from '../../Lookup/SearchStrategy'
-import {ProcedureAst} from '../../parser'
-import {StatType} from '../../statistics'
-import {zeroIfEmpty} from '../ArithmeticHelper'
-import {InterpreterState} from '../InterpreterState'
-import {InternalScalarValue, InterpreterValue, RawNoErrorScalarValue} from '../InterpreterValue'
-import {SimpleRangeValue} from '../../SimpleRangeValue'
-import {FunctionArgumentType, FunctionPlugin, FunctionPluginTypecheck, ImplementedFunctions} from './FunctionPlugin'
+import { AbsoluteCellRange } from '../../AbsoluteCellRange'
+import { CellError, CellRange, ErrorType, simpleCellAddress } from '../../Cell'
+import { ErrorMessage } from '../../error-message'
+import { RowSearchStrategy } from '../../Lookup/RowSearchStrategy'
+import { SearchOptions, SearchStrategy } from '../../Lookup/SearchStrategy'
+import { ProcedureAst } from '../../parser'
+import { StatType } from '../../statistics'
+import { zeroIfEmpty } from '../ArithmeticHelper'
+import { InterpreterState } from '../InterpreterState'
+import { InternalScalarValue, InterpreterValue, RawNoErrorScalarValue } from '../InterpreterValue'
+import { SimpleRangeValue } from '../../SimpleRangeValue'
+import { FunctionArgumentType, FunctionPlugin, FunctionPluginTypecheck, ImplementedFunctions } from './FunctionPlugin'
+import { ArraySize } from '../../ArraySize'
 
 export class LookupPlugin extends FunctionPlugin implements FunctionPluginTypecheck<LookupPlugin> {
   public static implementedFunctions: ImplementedFunctions = {
     'VLOOKUP': {
       method: 'vlookup',
       parameters: [
-        {argumentType: FunctionArgumentType.NOERROR},
-        {argumentType: FunctionArgumentType.RANGE},
-        {argumentType: FunctionArgumentType.NUMBER},
-        {argumentType: FunctionArgumentType.BOOLEAN, defaultValue: true},
-      ]
+        { argumentType: FunctionArgumentType.NOERROR },
+        { argumentType: FunctionArgumentType.RANGE },
+        { argumentType: FunctionArgumentType.NUMBER },
+        { argumentType: FunctionArgumentType.BOOLEAN, defaultValue: true },
+      ],
     },
     'HLOOKUP': {
       method: 'hlookup',
       parameters: [
-        {argumentType: FunctionArgumentType.NOERROR},
-        {argumentType: FunctionArgumentType.RANGE},
-        {argumentType: FunctionArgumentType.NUMBER},
-        {argumentType: FunctionArgumentType.BOOLEAN, defaultValue: true},
+        { argumentType: FunctionArgumentType.NOERROR },
+        { argumentType: FunctionArgumentType.RANGE },
+        { argumentType: FunctionArgumentType.NUMBER },
+        { argumentType: FunctionArgumentType.BOOLEAN, defaultValue: true },
+      ]
+    },
+    'XLOOKUP': {
+      method: 'xlookup',
+      arraySizeMethod: 'xlookupArraySize',
+      parameters: [
+        // lookup_value
+        { argumentType: FunctionArgumentType.NOERROR },
+        // lookup_array
+        { argumentType: FunctionArgumentType.RANGE },
+        // return_array
+        { argumentType: FunctionArgumentType.RANGE },
+        // [if_not_found]
+        { argumentType: FunctionArgumentType.SCALAR, optionalArg: true, defaultValue: ErrorType.NA },
+        // [match_mode]
+        { argumentType: FunctionArgumentType.NUMBER, optionalArg: true, defaultValue: 0 },
+        // [search_mode]
+        { argumentType: FunctionArgumentType.NUMBER, optionalArg: true, defaultValue: 1 },
       ]
     },
     'MATCH': {
       method: 'match',
       parameters: [
-        {argumentType: FunctionArgumentType.NOERROR},
-        {argumentType: FunctionArgumentType.RANGE},
-        {argumentType: FunctionArgumentType.NUMBER, defaultValue: 1},
+        { argumentType: FunctionArgumentType.NOERROR },
+        { argumentType: FunctionArgumentType.RANGE },
+        { argumentType: FunctionArgumentType.NUMBER, defaultValue: 1 },
       ]
     },
   }
@@ -67,7 +86,7 @@ export class LookupPlugin extends FunctionPlugin implements FunctionPluginTypech
         return new CellError(ErrorType.REF, ErrorMessage.IndexLarge)
       }
 
-      return this.doVlookup(zeroIfEmpty(key), rangeValue, index - 1, sorted)
+      return this.doVlookup(zeroIfEmpty(key), rangeValue, index - 1, { ordering: sorted ? 'asc' : 'none' })
     })
   }
 
@@ -90,29 +109,92 @@ export class LookupPlugin extends FunctionPlugin implements FunctionPluginTypech
         return new CellError(ErrorType.REF, ErrorMessage.IndexLarge)
       }
 
-      return this.doHlookup(zeroIfEmpty(key), rangeValue, index - 1, sorted)
+      return this.doHlookup(zeroIfEmpty(key), rangeValue, index - 1, { ordering: sorted ? 'asc' : 'none' })
     })
   }
 
+  /**
+   * Corresponds to XLOOKUP(lookup_value, lookup_array, return_array, [if_not_found], [match_mode], [search_mode])
+   * 
+   * @param ast
+   * @param state
+   */
+  public xlookup(ast: ProcedureAst, state: InterpreterState): InterpreterValue {
+    return this.runFunction(ast.args, state, this.metadata('XLOOKUP'), (key: RawNoErrorScalarValue, lookupRangeValue: SimpleRangeValue, returnRangeValue: SimpleRangeValue, ifNotFound: any, matchMode: number, searchMode: number) => {      
+      if (![0, -1, 1, 2].includes(matchMode)) {
+        return new CellError(ErrorType.VALUE, ErrorMessage.BadMode)
+      }
+
+      if (![1, -1, 1, 2].includes(searchMode)) {
+        return new CellError(ErrorType.VALUE, ErrorMessage.BadMode)
+      }
+
+      if (matchMode !== 0) {
+        // not supported yet
+        // TODO: Implement match mode
+        return new CellError(ErrorType.VALUE, ErrorMessage.BadMode)
+      }
+
+      const lookupRange = lookupRangeValue instanceof SimpleRangeValue ? lookupRangeValue : SimpleRangeValue.fromScalar(lookupRangeValue)
+      const returnRange = returnRangeValue instanceof SimpleRangeValue ? returnRangeValue : SimpleRangeValue.fromScalar(returnRangeValue)
+      const searchOptions: SearchOptions = { ordering: searchMode === 2 ? 'asc' : searchMode === -2 ? 'desc' : 'none' }
+
+      return this.doXlookup(zeroIfEmpty(key), lookupRange, returnRange, ifNotFound, matchMode, searchOptions)
+    })
+  }
+
+  public xlookupArraySize(ast: ProcedureAst): ArraySize {
+    const lookupRange = ast?.args?.[1] as CellRange
+    const returnRange  = ast?.args?.[2] as CellRange
+
+    if (lookupRange?.start == null
+      || lookupRange?.end == null
+      || returnRange?.start == null
+      || returnRange?.end == null
+    ) {
+      return ArraySize.error()
+    }
+
+    const lookupRangeHeight = lookupRange.end.row - lookupRange.start.row + 1
+    const lookupRangeWidth = lookupRange.end.col - lookupRange.start.col + 1
+    const returnRangeHeight = returnRange.end.row - returnRange.start.row + 1
+    const returnRangeWidth = returnRange.end.col - returnRange.start.col + 1
+
+    const isVerticalSearch = lookupRangeWidth === 1 && returnRangeHeight === lookupRangeHeight
+    const isHorizontalSearch = lookupRangeHeight === 1 && returnRangeWidth === lookupRangeWidth
+
+    if (!isVerticalSearch && !isHorizontalSearch) {
+      return ArraySize.error()
+    }
+
+    if (isVerticalSearch) {
+      return new ArraySize(returnRangeWidth, 1)
+    }
+
+    return new ArraySize(1, returnRangeHeight)
+  }
+
   public match(ast: ProcedureAst, state: InterpreterState): InterpreterValue {
     return this.runFunction(ast.args, state, this.metadata('MATCH'), (key: RawNoErrorScalarValue, rangeValue: SimpleRangeValue, type: number) => {
       return this.doMatch(zeroIfEmpty(key), rangeValue, type)
     })
   }
 
-  protected searchInRange(key: RawNoErrorScalarValue, range: SimpleRangeValue, sorted: boolean, searchStrategy: SearchStrategy): number {
-    if (!sorted && typeof key === 'string' && this.arithmeticHelper.requiresRegex(key)) {
+  protected searchInRange(key: RawNoErrorScalarValue, range: SimpleRangeValue, searchOptions: SearchOptions, searchStrategy: SearchStrategy): number {
+    // for sorted option: use findInOrderedArray
+
+    if (searchOptions.ordering === 'none' && typeof key === 'string' && this.arithmeticHelper.requiresRegex(key)) {
       return searchStrategy.advancedFind(
         this.arithmeticHelper.eqMatcherFunction(key),
         range
       )
     } else {
-      const searchOptions: SearchOptions = sorted ? { ordering: 'asc' } : { ordering: 'none', matchExactly: true }
-      return searchStrategy.find(key, range, searchOptions)
+      const newSearchOptions: SearchOptions = searchOptions.ordering === 'none' ? { ordering: 'none', matchExactly: true } : searchOptions
+      return searchStrategy.find(key, range, newSearchOptions)
     }
   }
 
-  private doVlookup(key: RawNoErrorScalarValue, rangeValue: SimpleRangeValue, index: number, sorted: boolean): InternalScalarValue {
+  private doVlookup(key: RawNoErrorScalarValue, rangeValue: SimpleRangeValue, index: number, searchOptions: SearchOptions): InternalScalarValue {
     this.dependencyGraph.stats.start(StatType.VLOOKUP)
     const range = rangeValue.range
     let searchedRange
@@ -121,7 +203,7 @@ export class LookupPlugin extends FunctionPlugin implements FunctionPluginTypech
     } else {
       searchedRange = SimpleRangeValue.onlyRange(AbsoluteCellRange.spanFrom(range.start, 1, range.height()), this.dependencyGraph)
     }
-    const rowIndex = this.searchInRange(key, searchedRange, sorted, this.columnSearch)
+    const rowIndex = this.searchInRange(key, searchedRange, searchOptions, this.columnSearch)
 
     this.dependencyGraph.stats.end(StatType.VLOOKUP)
 
@@ -143,15 +225,15 @@ export class LookupPlugin extends FunctionPlugin implements FunctionPluginTypech
     return value
   }
 
-  private doHlookup(key: RawNoErrorScalarValue, rangeValue: SimpleRangeValue, index: number, sorted: boolean): InternalScalarValue {
+  private doHlookup(key: RawNoErrorScalarValue, rangeValue: SimpleRangeValue, index: number, searchOptions: SearchOptions): InternalScalarValue {
     const range = rangeValue.range
     let searchedRange
     if (range === undefined) {
       searchedRange = SimpleRangeValue.onlyValues([rangeValue.data[0]])
     } else {
       searchedRange = SimpleRangeValue.onlyRange(AbsoluteCellRange.spanFrom(range.start, range.width(), 1), this.dependencyGraph)
     }
-    const colIndex = this.searchInRange(key, searchedRange, sorted, this.rowSearch)
+    const colIndex = this.searchInRange(key, searchedRange, searchOptions, this.rowSearch)
 
     if (colIndex === -1) {
       return new CellError(ErrorType.NA, ErrorMessage.ValueNotFound)
@@ -171,6 +253,25 @@ export class LookupPlugin extends FunctionPlugin implements FunctionPluginTypech
     return value
   }
 
+  private doXlookup(key: RawNoErrorScalarValue, lookupRange: SimpleRangeValue, returnRange: SimpleRangeValue, ifNotFound: any, matchMode: number, searchOptions: SearchOptions): InterpreterValue {
+    const isVerticalSearch = lookupRange.width() === 1 && returnRange.height() === lookupRange.height()
+    const isHorizontalSearch = lookupRange.height() === 1 && returnRange.width() === lookupRange.width()
+
+    if (!isVerticalSearch && !isHorizontalSearch) {
+      return new CellError(ErrorType.VALUE, ErrorMessage.WrongDimension)
+    }
+
+    const searchStrategy = isVerticalSearch ? this.columnSearch : this.rowSearch
+    const indexFound = this.searchInRange(key, lookupRange, searchOptions, searchStrategy)
+
+    if (indexFound === -1) {
+      return (ifNotFound == ErrorType.NA) ? new CellError(ErrorType.NA, ErrorMessage.ValueNotFound) : ifNotFound
+    }
+
+    const returnValues: InternalScalarValue[][] = isVerticalSearch ? [returnRange.data[indexFound]] : returnRange.data.map((row) => [row[indexFound]])
+    return SimpleRangeValue.onlyValues(returnValues)
+  }
+
   private doMatch(key: RawNoErrorScalarValue, rangeValue: SimpleRangeValue, type: number): InternalScalarValue {
     if (![-1, 0, 1].includes(type)) {
       return new CellError(ErrorType.VALUE, ErrorMessage.BadMode)