Lookup & reference functions

CHANGELOG.md

@@ -8,6 +8,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - Added 9 text functions EXACT, LOWER, UPPER, MID, T, SUBSTITUTE, REPLACE, UNICODE, UNICHAR. (#159)
+- Added 3 information functions HLOOKUP, ROW, COLUMN. (#158)
+
+### Fixed
+- Fixed multiple issues with VLOOKUP function. (#526, #528)
+- Fixed MATCH and INDEX functions compatiblity. (#520)
 
 ### Fixed
 - Fixed minor issue with arithmetic operations error messages. (#532)

docs/guide/built-in-functions.md

@@ -151,11 +151,14 @@ lets you design your own [custom functions](custom-functions).
 | TRUE | Logical | The logical value is set to TRUE. | TRUE() |
 | XOR | Logical | Returns true if an odd number of arguments evaluates to TRUE. | XOR(Logicalvalue1; Logicalvalue2 ...Logicalvalue30) |
 | CHOOSE | Lookup and reference | Uses an index to return a value from a list of up to 30 values.| CHOOSE(Index; Value1; ...; Value30) |
+| COLUMN | Lookup and reference | Returns column number of a given reference or formula reference if argument not provided. | COLUMNS([Reference]) |
 | COLUMNS | Lookup and reference | Returns the number of columns in the given reference. | COLUMNS(Array) |
 | FORMULATEXT <br><Badge text="v0.2.0"/>| Lookup and reference | Returns a formula in a given cell as a string. | FORMULATEXT(Reference) |
+| HLOOKUP | Lookup and reference | Searches horizontally with reference to adjacent cells to the bottom. | HLOOKUP(Search_Criterion; Array; Index; Sort_Order) |
 | INDEX | Lookup and reference | Returns the content of a cell, specified by row and column number, or an optional range name. | INDEX(Reference; Row; Column; Range) |
 | MATCH | Lookup and reference | Returns the relative position of an item in an array that matches a specified value. | MATCH(Searchcriterion; Lookuparray; Type) |
 | OFFSET | Lookup and reference | 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 | Lookup and reference | Returns row number of a given reference or formula reference if argument not provided. | ROW([Reference]) |
 | ROWS | Lookup and reference | Returns the number of rows in the given reference. | ROWS(Array) |
 | VLOOKUP | Lookup and reference | Searches vertically with reference to adjacent cells to the right. | VLOOKUP(Search_Criterion; Array; Index; Sort_Order) |
 | ABS | Math and trigonometry | Returns the absolute value of a number. | ABS(Number) |

docs/guide/performance.md

@@ -19,7 +19,7 @@ Leaving this option disabled will cause the engine to use binary
 search when dealing with sorted data, and the naive approach otherwise.
 Binary search will not be used when the size of the data being searched
 doesn't exceed a given threshold which can be customized using the
-`vlookupThreshold` option in the configuration.
+`binarySearchThreshold` option in the configuration.
 
 ## Address mapping strategies
 
@@ -128,4 +128,4 @@ The resulting times are returned in seconds.
 |   |   |   |
 | **Huawei Mate 20** |   |   |
 | Average total time | 6.611 | 40.166 |
-| Standard deviation | 0.394 | 0.594 |
+| Standard deviation | 0.394 | 0.594 |

src/BuildEngineFactory.ts

@@ -6,7 +6,7 @@
 import {LazilyTransformingAstService} from './LazilyTransformingAstService'
 import {CellContentParser} from './CellContentParser'
 import {Exporter} from './CellValue'
-import {buildColumnSearchStrategy, ColumnSearchStrategy} from './ColumnSearch/ColumnSearchStrategy'
+import {buildColumnSearchStrategy, ColumnSearchStrategy} from './Lookup/SearchStrategy'
 import {Config, ConfigParams} from './Config'
 import {DateTimeHelper} from './DateTimeHelper'
 import {CrudOperations} from './CrudOperations'

src/Config.ts

@@ -296,13 +296,25 @@ export interface ConfigParams {
   /**
    * Determines minimum number of elements a range must have in order to use binary search.
    * Shorter ranges will be searched naively.
-   * Used by VLOOKUP and MATCH functions.
+   * Used by VLOOKUP, HLOOKUP and MATCH functions.
    *
    * @default 20
    *
    * @category Engine
+   *
+   * @deprecated Use {@link binarySearchThreshold} instead.
    */
   vlookupThreshold: number,
+  /**
+   * Determines minimum number of elements a range must have in order to use binary search.
+   * Shorter ranges will be searched naively.
+   * Used by VLOOKUP, HLOOKUP and MATCH functions.
+   *
+   * @default 20
+   *
+   * @category Engine
+   */
+  binarySearchThreshold: number,
   /**
    * Allows to set a specific date from which the number of days will be counted.
    * Dates are represented internally as a number of days that passed since this `nullDate`.
@@ -393,6 +405,7 @@ export class Config implements ConfigParams, ParserConfig {
     useColumnIndex: false,
     useStats: false,
     vlookupThreshold: 20,
+    binarySearchThreshold: 20,
     nullDate: {year: 1899, month: 12, day: 30},
     undoLimit: 20,
     useRegularExpressions: false,
@@ -425,7 +438,7 @@ export class Config implements ConfigParams, ParserConfig {
   /** @inheritDoc */
   public readonly licenseKey: string
   /** @inheritDoc */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
   public readonly functionPlugins: FunctionPluginDefinition[]
   /** @inheritDoc */
   public readonly gpuMode: GPUMode
@@ -462,6 +475,8 @@ export class Config implements ConfigParams, ParserConfig {
   /** @inheritDoc */
   public readonly vlookupThreshold: number
   /** @inheritDoc */
+  public readonly binarySearchThreshold: number
+  /** @inheritDoc */
   public readonly nullDate: SimpleDate
   /** @inheritDoc */
   public readonly undoLimit: number
@@ -530,6 +545,7 @@ export class Config implements ConfigParams, ParserConfig {
       precisionRounding,
       useColumnIndex,
       vlookupThreshold,
+      binarySearchThreshold,
       nullDate,
       useStats,
       undoLimit,
@@ -572,6 +588,8 @@ export class Config implements ConfigParams, ParserConfig {
     this.useStats = this.valueFromParam(useStats, 'boolean', 'useStats')
     this.vlookupThreshold = this.valueFromParam(vlookupThreshold, 'number', 'vlookupThreshold')
     this.validateNumberToBeAtLeast(this.vlookupThreshold, 'vlookupThreshold', 1)
+    this.binarySearchThreshold = this.valueFromParam(binarySearchThreshold ?? vlookupThreshold, 'number', 'vlookupThreshold')
+    this.validateNumberToBeAtLeast(this.binarySearchThreshold, 'binarySearchThreshold', 1)
     this.parseDateTime = this.valueFromParam(parseDateTime, 'function', 'parseDateTime')
     this.stringifyDateTime = this.valueFromParam(stringifyDateTime, 'function', 'stringifyDateTime')
     this.stringifyDuration = this.valueFromParam(stringifyDuration, 'function', 'stringifyDuration')
@@ -589,6 +607,7 @@ export class Config implements ConfigParams, ParserConfig {
     this.maxColumns = this.valueFromParam(maxColumns, 'number', 'maxColumns')
     this.validateNumberToBeAtLeast(this.maxColumns, 'maxColumns', 1)
 
+    this.warnDeprecatedIfUsed(vlookupThreshold, 'vlookupThreshold', 'v.0.3.0', 'binarySearchThreshold')
 
     this.checkIfParametersNotInConflict(
       {value: this.decimalSeparator, name: 'decimalSeparator'},
@@ -607,6 +626,12 @@ export class Config implements ConfigParams, ParserConfig {
     return new Config(mergedConfig)
   }
 
+  private warnDeprecatedIfUsed(inputValue: any, paramName: string, fromVersion: string, replacementName: string) {
+    if (inputValue !== undefined) {
+      console.warn(`${paramName} option is deprecated since ${fromVersion}, please use ${replacementName}`)
+    }
+  }
+
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private valueFromParam(inputValue: any, expectedType: string | string[], paramName: ConfigParamsList) {
     if (typeof inputValue === 'undefined') {

src/CrudOperations.ts

@@ -8,7 +8,7 @@ import {invalidSimpleCellAddress, simpleCellAddress, SimpleCellAddress} from './
 import {CellContent, CellContentParser, isMatrix, RawCellContent} from './CellContentParser'
 import {ClipboardCell, ClipboardOperations} from './ClipboardOperations'
 import {AddColumnsCommand, AddRowsCommand, Operations, RemoveColumnsCommand, RemoveRowsCommand} from './Operations'
-import {ColumnSearchStrategy} from './ColumnSearch/ColumnSearchStrategy'
+import {ColumnSearchStrategy} from './Lookup/SearchStrategy'
 import {Config} from './Config'
 import {ContentChanges} from './ContentChanges'
 import {DependencyGraph, SheetMapping} from './DependencyGraph'

src/DependencyGraph/DependencyGraph.ts

@@ -763,6 +763,15 @@ export class DependencyGraph {
     }
   }
 
+  public computeListOfValuesInRange(range: AbsoluteCellRange): InternalScalarValue[] {
+    const values: InternalScalarValue[] = []
+    for (const cellFromRange of range.addresses(this)) {
+      const value = this.getScalarValue(cellFromRange)
+      values.push(value)
+    }
+    return values
+  }
+
   private rangeDependencyQuery = (vertex: RangeVertex) => {
     const allDeps: [(SimpleCellAddress | AbsoluteCellRange), Vertex][] = []
     const {smallerRangeVertex, restRange} = this.rangeMapping.findSmallerRange(vertex.range) //checking whether this range was splitted by bruteForce or not

src/Evaluator.ts

@@ -6,7 +6,7 @@
 import {AbsoluteCellRange} from './AbsoluteCellRange'
 import {absolutizeDependencies} from './absolutizeDependencies'
 import {CellError, EmptyValue, ErrorType, SimpleCellAddress} from './Cell'
-import {ColumnSearchStrategy} from './ColumnSearch/ColumnSearchStrategy'
+import {ColumnSearchStrategy} from './Lookup/SearchStrategy'
 import {Config} from './Config'
 import {ContentChanges} from './ContentChanges'
 import {DateTimeHelper} from './DateTimeHelper'

src/GraphBuilder.ts

@@ -7,7 +7,7 @@ import {absolutizeDependencies} from './absolutizeDependencies'
 import {CellError, simpleCellAddress, SimpleCellAddress} from './Cell'
 import {CellContent, CellContentParser} from './CellContentParser'
 import {CellDependency} from './CellDependency'
-import {ColumnSearchStrategy} from './ColumnSearch/ColumnSearchStrategy'
+import {ColumnSearchStrategy} from './Lookup/SearchStrategy'
 import {Config} from './Config'
 import {
   DependencyGraph,

src/GraphBuilderMatrixHeuristic.ts

@@ -6,7 +6,7 @@
 import {AbsoluteCellRange} from './AbsoluteCellRange'
 import {simpleCellAddress, SimpleCellAddress} from './Cell'
 import {CellContent, CellContentParser, RawCellContent} from './CellContentParser'
-import {ColumnSearchStrategy} from './ColumnSearch/ColumnSearchStrategy'
+import {ColumnSearchStrategy} from './Lookup/SearchStrategy'
 import {DependencyGraph, MatrixVertex} from './DependencyGraph'
 import {Matrix, MatrixSize} from './Matrix'
 import {Sheets} from './Sheet'

src/HyperFormula.ts

@@ -7,7 +7,7 @@ import {AbsoluteCellRange} from './AbsoluteCellRange'
 import {CellType, CellValueType, getCellType, getCellValueType, SimpleCellAddress} from './Cell'
 import {CellContent, CellContentParser, RawCellContent} from './CellContentParser'
 import {CellValue, ExportedChange, Exporter, NoErrorCellValue} from './CellValue'
-import {ColumnSearchStrategy} from './ColumnSearch/ColumnSearchStrategy'
+import {ColumnSearchStrategy} from './Lookup/SearchStrategy'
 import {Config, ConfigParams} from './Config'
 import {ColumnRowIndex, CrudOperations} from './CrudOperations'
 import {DateTime, numberToSimpleTime} from './DateTimeHelper'

src/Lookup/AdvancedFind.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright (c) 2020 Handsoncode. All rights reserved.
+ */
+
+import {DependencyGraph} from '../DependencyGraph'
+import {InternalScalarValue} from '../Cell'
+import {AbsoluteCellRange} from '../AbsoluteCellRange'
+
+export abstract class AdvancedFind {
+  protected constructor(
+    protected dependencyGraph: DependencyGraph
+  ) {
+  }
+
+  public advancedFind(keyMatcher: (arg: InternalScalarValue) => boolean, range: AbsoluteCellRange): number {
+    const values = this.dependencyGraph.computeListOfValuesInRange(range)
+    for (let i = 0; i < values.length; i++) {
+      if (keyMatcher(values[i])) {
+        return i + range.start.col
+      }
+    }
+    return -1
+  }
+}

src/ColumnSearch/ColumnBinarySearch.ts → src/Lookup/ColumnBinarySearch.ts

@@ -9,14 +9,18 @@ import {Config} from '../Config'
 import {DependencyGraph} from '../DependencyGraph'
 import {rangeLowerBound} from '../interpreter/binarySearch'
 import {Matrix} from '../Matrix'
-import {ColumnSearchStrategy} from './ColumnSearchStrategy'
+import {ColumnSearchStrategy} from './SearchStrategy'
 import {ColumnsSpan} from '../Span'
+import {AdvancedFind} from './AdvancedFind'
 
-export class ColumnBinarySearch implements ColumnSearchStrategy {
+export class ColumnBinarySearch extends AdvancedFind implements ColumnSearchStrategy {
   constructor(
-    private dependencyGraph: DependencyGraph,
+    protected dependencyGraph: DependencyGraph,
     private config: Config,
-  ) {}
+  ) {
+    super(dependencyGraph)
+  }
+
   // eslint-disable-next-line @typescript-eslint/no-unused-vars 
   public add(value: InternalScalarValue | Matrix, address: SimpleCellAddress): void {}
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -37,31 +41,12 @@ export class ColumnBinarySearch implements ColumnSearchStrategy {
   public destroy(): void {}
 
   public find(key: InternalNoErrorCellValue, range: AbsoluteCellRange, sorted: boolean): number {
-    if (range.height() < this.config.vlookupThreshold || !sorted) {
-      const values = this.computeListOfValuesInRange(range)
+    if (range.height() < this.config.binarySearchThreshold || !sorted) {
+      const values = this.dependencyGraph.computeListOfValuesInRange(range)
       const index =  values.indexOf(key)
       return index < 0 ? index : index + range.start.row
     } else {
-      return rangeLowerBound(range, key, this.dependencyGraph)
-    }
-  }
-
-  public advancedFind(keyMatcher: (arg: InternalScalarValue) => boolean, range: AbsoluteCellRange): number {
-    const values = this.computeListOfValuesInRange(range)
-    for(let i=0; i<values.length; i++) {
-      if(keyMatcher(values[i])) {
-        return i + range.start.row
-      }
-    }
-    return -1
-  }
-
-  private computeListOfValuesInRange(range: AbsoluteCellRange): InternalScalarValue[] {
-    const values: InternalScalarValue[] = []
-    for (const cellFromRange of range.addresses(this.dependencyGraph)) {
-      const value = this.dependencyGraph.getScalarValue(cellFromRange)
-      values.push(value)
+      return rangeLowerBound(range, key, this.dependencyGraph, 'row')
     }
-    return values
   }
 }

src/ColumnSearch/ColumnIndex.ts → src/Lookup/ColumnIndex.ts

@@ -18,7 +18,7 @@ import {Matrix} from '../Matrix'
 import {ColumnsSpan, RowsSpan} from '../Span'
 import {Statistics, StatType} from '../statistics'
 import {ColumnBinarySearch} from './ColumnBinarySearch'
-import {ColumnSearchStrategy} from './ColumnSearchStrategy'
+import {ColumnSearchStrategy} from './SearchStrategy'
 import {AddRowsTransformer} from '../dependencyTransformers/AddRowsTransformer'
 import {RemoveRowsTransformer} from '../dependencyTransformers/RemoveRowsTransformer'
 import {FormulaTransformer} from '../dependencyTransformers/Transformer'
@@ -112,7 +112,7 @@ export class ColumnIndex implements ColumnSearchStrategy {
     return rowNumber <= range.end.row ? rowNumber : this.binarySearchStrategy.find(key, range, sorted)
   }
 
-  public advancedFind(keyMatcher: (arg: InterpreterValue) => boolean, range: AbsoluteCellRange): number {
+  public advancedFind(keyMatcher: (arg: InternalScalarValue) => boolean, range: AbsoluteCellRange): number {
     return this.binarySearchStrategy.advancedFind(keyMatcher, range)
   }
 

src/Lookup/RowSearchStrategy.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright (c) 2020 Handsoncode. All rights reserved.
+ */
+
+import {SearchStrategy} from './SearchStrategy'
+import {InternalNoErrorCellValue} from '../Cell'
+import {AbsoluteCellRange} from '../AbsoluteCellRange'
+import {rangeLowerBound} from '../interpreter/binarySearch'
+import {Config} from '../Config'
+import {DependencyGraph} from '../DependencyGraph'
+import {AdvancedFind} from './AdvancedFind'
+
+export class RowSearchStrategy extends AdvancedFind implements SearchStrategy {
+  constructor(
+    private config: Config,
+    protected dependencyGraph: DependencyGraph,
+  ) {
+    super(dependencyGraph)
+  }
+
+  public find(key: InternalNoErrorCellValue, range: AbsoluteCellRange, sorted: boolean): number {
+    if (range.width() < this.config.binarySearchThreshold || !sorted) {
+      const values = this.dependencyGraph.computeListOfValuesInRange(range)
+      const index =  values.indexOf(key)
+      return index < 0 ? index : index + range.start.col
+    } else {
+      return rangeLowerBound(range, key, this.dependencyGraph, 'col')
+    }
+  }
+}

src/ColumnSearch/ColumnSearchStrategy.ts → src/Lookup/SearchStrategy.ts

@@ -14,7 +14,13 @@ import {ColumnBinarySearch} from './ColumnBinarySearch'
 import {ColumnIndex} from './ColumnIndex'
 import {ColumnsSpan} from '../Span'
 
-export interface ColumnSearchStrategy {
+export interface SearchStrategy {
+  find(key: InternalNoErrorCellValue, range: AbsoluteCellRange, sorted: boolean): number,
+
+  advancedFind(keyMatcher: (arg: InternalScalarValue) => boolean, range: AbsoluteCellRange): number,
+}
+
+export interface ColumnSearchStrategy extends SearchStrategy {
   add(value: InterpreterValue | Matrix, address: SimpleCellAddress): void,
 
   remove(value: InterpreterValue | Matrix | null, address: SimpleCellAddress): void,
@@ -31,10 +37,6 @@ export interface ColumnSearchStrategy {
 
   removeValues(range: IterableIterator<[InternalScalarValue, SimpleCellAddress]>): void,
 
-  find(key: InternalNoErrorCellValue, range: AbsoluteCellRange, sorted: boolean): number,
-
-  advancedFind(keyMatcher: (arg: InterpreterValue) => boolean, range: AbsoluteCellRange): number,
-
   destroy(): void,
 }
 

src/Operations.ts

@@ -9,7 +9,7 @@ import {EmptyValue, invalidSimpleCellAddress, simpleCellAddress, SimpleCellAddre
 import {CellContent, CellContentParser, RawCellContent} from './CellContentParser'
 import {ColumnsSpan, RowsSpan} from './Span'
 import {ContentChanges} from './ContentChanges'
-import {ColumnSearchStrategy} from './ColumnSearch/ColumnSearchStrategy'
+import {ColumnSearchStrategy} from './Lookup/SearchStrategy'
 import {absolutizeDependencies} from './absolutizeDependencies'
 import {LazilyTransformingAstService} from './LazilyTransformingAstService'
 import {buildMatrixVertex} from './GraphBuilder'

src/error-message.ts

@@ -33,7 +33,7 @@ export class ErrorMessage {
   public static NotOctal = 'String does not represent an octal number.'
   public static NotHex = 'String does not represent a hexadecimal number.'
   public static EndStartPeriod = 'End period needs to be at least start period.'
-  public static CellRef = 'Cell reference expected.'
+  public static CellRefExpected = 'Cell reference expected.'
   public static BadRef = 'Address is not correct.'
   public static NumberRange = 'Number-only range expected.'
   public static ValueNotFound = 'Value not found.'