XLOOKUP function

CHANGELOG.md

@@ -7,6 +7,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+### Added
+
+- Added a new function: XLOOKUP. [#1458](https://github.com/handsontable/hyperformula/issues/1458)
+
 ### Changed
 
 - **Breaking change**: Changed ES module build to use `mjs` files and `exports` property in `package.json` to make importing language files possible in Node environment. [#1344](https://github.com/handsontable/hyperformula/issues/1344)

docs/guide/built-in-functions.md

@@ -212,21 +212,22 @@ Total number of functions: **{{ $page.functionsCount }}**
 
 ### Lookup and reference
 
-| Function ID | Description                                                                                                                              | Syntax                                                                 |
-|:------------|:-----------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------|
-| ADDRESS     | Returns a cell reference as a string.                                                                                                    | ADDRESS(Row, Column[, AbsoluteRelativeMode[, UseA1Notation[, Sheet]]]) |
-| CHOOSE      | Uses an index to return a value from a list of values.                                                                                   | CHOOSE(Index, Value1, Value2, ...ValueN)                               |
-| COLUMN      | Returns column number of a given reference or formula reference if argument not provided.                                                | COLUMNS([Reference])                                                   |
-| COLUMNS     | Returns the number of columns in the given reference.                                                                                    | COLUMNS(Array)                                                         |
-| FORMULATEXT | Returns a formula in a given cell as a string.                                                                                           | FORMULATEXT(Reference)                                                 |
-| HLOOKUP     | Searches horizontally with reference to adjacent cells to the bottom.                                                                    | HLOOKUP(Search_Criterion, Array, Index, Sort_Order)                    |
-| HYPERLINK   | Stores the url in the cell's metadata. It can be read using method [`getCellHyperlink`](../api/classes/hyperformula.md#getcellhyperlink) | HYPERLINK(Url[, LinkLabel])                                            |
-| INDEX       | Returns the contents of a cell specified by row and column number. The column number is optional and defaults to 1.                      | INDEX(Range, Row [, Column])                                           |
-| MATCH       | Returns the relative position of an item in an array that matches a specified value.                                                     | MATCH(Searchcriterion, Lookuparray [, MatchType])                      |
-| OFFSET      | Returns the value of a cell offset by a certain number of rows and columns from a given reference point.                                 | OFFSET(Reference, Rows, Columns, Height, Width)                        |
-| 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)                    |
+| Function ID | Description                                                                                                                                                          | Syntax                                                                                  |
+|:------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------|
+| ADDRESS     | Returns a cell reference as a string.                                                                                                                                | ADDRESS(Row, Column[, AbsoluteRelativeMode[, UseA1Notation[, Sheet]]])                  |
+| CHOOSE      | Uses an index to return a value from a list of values.                                                                                                               | CHOOSE(Index, Value1, Value2, ...ValueN)                                                |
+| COLUMN      | Returns column number of a given reference or formula reference if argument not provided.                                                                            | COLUMNS([Reference])                                                                    |
+| COLUMNS     | Returns the number of columns in the given reference.                                                                                                                | COLUMNS(Array)                                                                          |
+| FORMULATEXT | Returns a formula in a given cell as a string.                                                                                                                       | FORMULATEXT(Reference)                                                                  |
+| HLOOKUP     | Searches horizontally with reference to adjacent cells to the bottom.                                                                                                | HLOOKUP(Search_Criterion, Array, Index, Sort_Order)                                     |
+| HYPERLINK   | Stores the url in the cell's metadata. It can be read using method [`getCellHyperlink`](../api/classes/hyperformula.md#getcellhyperlink)                             | HYPERLINK(Url[, LinkLabel])                                                             |
+| INDEX       | Returns the contents of a cell specified by row and column number. The column number is optional and defaults to 1.                                                  | INDEX(Range, Row [, Column])                                                            |
+| MATCH       | Returns the relative position of an item in an array that matches a specified value.                                                                                 | MATCH(Searchcriterion, LookupArray [, MatchType])                                       |
+| OFFSET      | Returns the value of a cell offset by a certain number of rows and columns from a given reference point.                                                             | OFFSET(Reference, Rows, Columns, Height, Width)                                         |
+| 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     | Searches for a key in a range and returns the item corresponding to the match it finds. If no match exists, then XLOOKUP can return the closest (approximate) match. | XLOOKUP(LookupValue, LookupArray, ReturnArray, [IfNotFound], [MatchMode], [SearchMode]) |
 
 ### Math and trigonometry
 

package.json

@@ -78,6 +78,7 @@
     "test": "npm-run-all lint test:unit test:browser",
     "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:watch-tmp": "cross-env NODE_ICU_DATA=node_modules/full-icu jest --watch xlookup",
     "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",

src/Lookup/AdvancedFind.ts

@@ -11,59 +11,93 @@
   RawNoErrorScalarValue
 } from '../interpreter/InterpreterValue'
 import {SimpleRangeValue} from '../SimpleRangeValue'
-import {SearchOptions} from './SearchStrategy'
+import {AdvancedFindOptions, SearchOptions} from './SearchStrategy'
 import {forceNormalizeString} from '../interpreter/ArithmeticHelper'
-import {findLastOccurrenceInOrderedRange} from '../interpreter/binarySearch'
+import {compare, findLastOccurrenceInOrderedRange} from '../interpreter/binarySearch'
+
+const NOT_FOUND = -1
 
 export abstract class AdvancedFind {
   protected constructor(
     protected dependencyGraph: DependencyGraph
   ) {
   }
 
-  public advancedFind(keyMatcher: (arg: RawInterpreterValue) => boolean, rangeValue: SimpleRangeValue): number {
-    let values: InternalScalarValue[]
+  public advancedFind(keyMatcher: (arg: RawInterpreterValue) => boolean, rangeValue: SimpleRangeValue, { returnOccurence }: AdvancedFindOptions = { returnOccurence: 'first' }): number {
     const range = rangeValue.range
-    if (range === undefined) {
-      values = rangeValue.valuesFromTopLeftCorner()
-    } else {
-      values = this.dependencyGraph.computeListOfValuesInRange(range)
-    }
-    for (let i = 0; i < values.length; i++) {
+    const values: InternalScalarValue[] = (range === undefined)
+      ? rangeValue.valuesFromTopLeftCorner()
+      : this.dependencyGraph.computeListOfValuesInRange(range)
+
+    const initialIterationIndex = returnOccurence === 'first' ? 0 : values.length-1
+    const iterationCondition = returnOccurence === 'first' ? (i: number) => i < values.length : (i: number) => i >= 0
+    const incrementIndex = returnOccurence === 'first' ? (i: number) => i+1 : (i: number) => i-1
+
+    for (let i = initialIterationIndex; iterationCondition(i); i = incrementIndex(i)) {
       if (keyMatcher(getRawValue(values[i]))) {
         return i
       }
     }
-    return -1
+    return NOT_FOUND
   }
 
-  /*
-   * WARNING: Finding lower/upper bounds in unordered ranges is not supported. When ordering === 'none', assumes matchExactly === true
-   */
-  protected basicFind(searchKey: RawNoErrorScalarValue, rangeValue: SimpleRangeValue, searchCoordinate: 'col' | 'row', { ordering, matchExactly }: SearchOptions): number {
+  protected basicFind(searchKey: RawNoErrorScalarValue, rangeValue: SimpleRangeValue, searchCoordinate: 'col' | 'row', { ordering, ifNoMatch, returnOccurence }: SearchOptions): number {
     const normalizedSearchKey = typeof searchKey === 'string' ? forceNormalizeString(searchKey) : searchKey
     const range = rangeValue.range
 
     if (range === undefined) {
-      return this.findNormalizedValue(normalizedSearchKey, rangeValue.valuesFromTopLeftCorner())
+      return this.findNormalizedValue(normalizedSearchKey, rangeValue.valuesFromTopLeftCorner(), ifNoMatch, returnOccurence)
     }
 
     if (ordering === 'none') {
-      return this.findNormalizedValue(normalizedSearchKey, this.dependencyGraph.computeListOfValuesInRange(range))
+      return this.findNormalizedValue(normalizedSearchKey, this.dependencyGraph.computeListOfValuesInRange(range), ifNoMatch, returnOccurence)
     }
 
     return findLastOccurrenceInOrderedRange(
       normalizedSearchKey,
       range,
-      { searchCoordinate, orderingDirection: ordering, matchExactly },
+      { searchCoordinate, orderingDirection: ordering, ifNoMatch },
       this.dependencyGraph
     )
   }
 
-  protected findNormalizedValue(searchKey: RawNoErrorScalarValue, searchArray: InternalScalarValue[]): number {
-    return searchArray
-    .map(getRawValue)
-    .map(val => typeof val === 'string' ? forceNormalizeString(val) : val)
-    .indexOf(searchKey)
+  protected findNormalizedValue(searchKey: RawNoErrorScalarValue, searchArray: InternalScalarValue[], ifNoMatch: 'returnLowerBound' | 'returnUpperBound' | 'returnNotFound' = 'returnNotFound', returnOccurence: 'first' | 'last' = 'first'): number {
+    const normalizedArray = searchArray
+      .map(getRawValue)
+      .map(val => typeof val === 'string' ? forceNormalizeString(val) : val)
+
+    if (ifNoMatch === 'returnNotFound') {
+      return returnOccurence === 'first' ? normalizedArray.indexOf(searchKey) : normalizedArray.lastIndexOf(searchKey)
+    }
+
+    const compareFn = ifNoMatch === 'returnLowerBound'
+      ? (left: RawNoErrorScalarValue, right: RawInterpreterValue) => compare(left, right)
+      : (left: RawNoErrorScalarValue, right: RawInterpreterValue) => -compare(left, right)
+
+    let bestValue: RawNoErrorScalarValue = ifNoMatch === 'returnLowerBound' ? -Infinity : Infinity
+    let bestIndex = NOT_FOUND
+
+    const initialIterationIndex = returnOccurence === 'first' ? 0 : normalizedArray.length-1
+    const iterationCondition = returnOccurence === 'first' ? (i: number) => i < normalizedArray.length : (i: number) => i >= 0
+    const incrementIndex = returnOccurence === 'first' ? (i: number) => i+1 : (i: number) => i-1
+
+    for (let i = initialIterationIndex; iterationCondition(i); i = incrementIndex(i)) {
+      const value = normalizedArray[i] as RawNoErrorScalarValue
+
+      if (value === searchKey) {
+        return i
+      }
+
+      if (compareFn(value, searchKey) > 0) {
+        continue
+      }
+
+      if (compareFn(bestValue, value) < 0) {
+        bestValue = value
+        bestIndex = i
+      }
+    }
+
+    return bestIndex
   }
 }

src/Lookup/ColumnIndex.ts

@@ -23,7 +23,7 @@
 import {ColumnsSpan, RowsSpan} from '../Span'
 import {Statistics, StatType} from '../statistics'
 import {ColumnBinarySearch} from './ColumnBinarySearch'
-import {ColumnSearchStrategy, SearchOptions} from './SearchStrategy'
+import {AdvancedFindOptions, ColumnSearchStrategy, SearchOptions} from './SearchStrategy'
 import {Maybe} from '../Maybe'
 import {AbsoluteCellRange} from '../AbsoluteCellRange'
 
@@ -107,16 +107,20 @@
     }
   }
 
-  /*
-   * WARNING: Finding lower/upper bounds in unordered ranges is not supported. When ordering === 'none', assumes matchExactly === true
-   */
-  public find(searchKey: RawNoErrorScalarValue, rangeValue: SimpleRangeValue, { ordering, matchExactly }: SearchOptions): number {
-    const handlingDuplicates = matchExactly === true ? 'findFirst' : 'findLast'
-    const resultUsingColumnIndex = this.findUsingColumnIndex(searchKey, rangeValue, handlingDuplicates)
-    return resultUsingColumnIndex !== undefined ? resultUsingColumnIndex : this.binarySearchStrategy.find(searchKey, rangeValue, { ordering, matchExactly })
+  public find(searchKey: RawNoErrorScalarValue, rangeValue: SimpleRangeValue, { ordering, ifNoMatch, returnOccurence }: SearchOptions): number {
+    if (ifNoMatch == null) {
+      ifNoMatch = 'returnNotFound'
+    }
+
+    if (returnOccurence == null) {
+      returnOccurence = ordering === 'none' ? 'first' : 'last'
+    }
+
+    const resultUsingColumnIndex = this.findUsingColumnIndex(searchKey, rangeValue, returnOccurence)
+    return resultUsingColumnIndex !== undefined ? resultUsingColumnIndex : this.binarySearchStrategy.find(searchKey, rangeValue, { ordering, ifNoMatch, returnOccurence })
   }
 
-  private findUsingColumnIndex(key: RawNoErrorScalarValue, rangeValue: SimpleRangeValue, handlingDuplicates: 'findFirst' | 'findLast'): Maybe<number> {
+  private findUsingColumnIndex(key: RawNoErrorScalarValue, rangeValue: SimpleRangeValue, returnOccurence: 'first' | 'last'): Maybe<number> {
     const range = rangeValue.range
     if (range === undefined) {
       return undefined
@@ -135,15 +139,15 @@
       return undefined
     }
 
-    const rowNumber = ColumnIndex.findRowBelongingToRange(valueIndexForTheKey, range, handlingDuplicates)
+    const rowNumber = ColumnIndex.findRowBelongingToRange(valueIndexForTheKey, range, returnOccurence)
     return rowNumber !== undefined ? rowNumber - range.start.row : undefined
   }
 
-  private static findRowBelongingToRange(valueIndex: ValueIndex, range: AbsoluteCellRange, handlingDuplicates: 'findFirst' | 'findLast'): Maybe<number> {
+  private static findRowBelongingToRange(valueIndex: ValueIndex, range: AbsoluteCellRange, returnOccurence: 'first' | 'last'): Maybe<number> {
     const start = range.start.row
     const end = range.end.row
 
-    const positionInIndex = handlingDuplicates === 'findFirst'
+    const positionInIndex = returnOccurence === 'first'
       ? findInOrderedArray(start, valueIndex.index, 'upperBound')
       : findInOrderedArray(end, valueIndex.index, 'lowerBound')
 
@@ -158,8 +162,8 @@
   }
 
 
-  public advancedFind(keyMatcher: (arg: RawInterpreterValue) => boolean, range: SimpleRangeValue): number {
-    return this.binarySearchStrategy.advancedFind(keyMatcher, range)
+  public advancedFind(keyMatcher: (arg: RawInterpreterValue) => boolean, range: SimpleRangeValue, options: AdvancedFindOptions = { returnOccurence: 'first' }): number {
+    return this.binarySearchStrategy.advancedFind(keyMatcher, range, options)
   }
 
   public addColumns(columnsSpan: ColumnsSpan) {

src/Lookup/SearchStrategy.ts

@@ -16,7 +16,12 @@ import {ColumnIndex} from './ColumnIndex'
 
 export interface SearchOptions {
   ordering: 'asc' | 'desc' | 'none',
-  matchExactly?: boolean,
+  ifNoMatch: 'returnLowerBound' | 'returnUpperBound' | 'returnNotFound',
+  returnOccurence?: 'first' | 'last',
+}
+
+export interface AdvancedFindOptions {
+  returnOccurence?: 'first' | 'last',
 }
 
 export interface SearchStrategy {
@@ -25,7 +30,7 @@ export interface SearchStrategy {
    */
   find(searchKey: RawNoErrorScalarValue, range: SimpleRangeValue, options: SearchOptions): number,
 
-  advancedFind(keyMatcher: (arg: RawInterpreterValue) => boolean, range: SimpleRangeValue): number,
+  advancedFind(keyMatcher: (arg: RawInterpreterValue) => boolean, range: SimpleRangeValue, options: AdvancedFindOptions): number,
 }
 
 export interface ColumnSearchStrategy extends SearchStrategy {

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',