@odoo/o-spreadsheet/dist/types/functions/helpers.d.ts

A spreadsheet component

import { DateTime } from "../helpers/dates";
import { CellValue } from "../types/cells";
import { ErrorValue } from "../types/errors";
import { LookupCaches } from "../types/functions";
import { Locale } from "../types/locale";
import { Arg, FunctionResultNumber, FunctionResultObject, Matrix, Maybe, SortDirection } from "../types/misc";
export declare function inferFormat(data: Arg | undefined): string | undefined;
export declare function isEvaluationError(error: Maybe<CellValue>): error is ErrorValue;
export declare function valueNotAvailable(searchKey: Maybe<FunctionResultObject>): FunctionResultObject;
export declare const expectReferenceError: string;
export declare const expectNumberRangeError: (lowerBound: number, upperBound: number, value: number) => string;
export declare const expectStringSetError: (stringSet: string[], value: string) => string;
export declare function toNumber(data: FunctionResultObject | CellValue | undefined, locale: Locale): number;
export declare function tryToNumber(value: string | number | boolean | null | undefined, locale: Locale): number | undefined;
export declare function toNumberMatrix(data: Arg, argName: string): Matrix<number>;
export declare function strictToNumber(data: FunctionResultObject | CellValue | undefined, locale: Locale): number;
export declare function toInteger(value: FunctionResultObject | CellValue | undefined, locale: Locale): number;
export declare function strictToInteger(value: FunctionResultObject | CellValue | undefined, locale: Locale): number;
export declare function toString(data: FunctionResultObject | CellValue | undefined): string;
/**
 * Normalize range by setting all the string in the range to lowercase and replacing
 * accent letters with plain letters
 */
export declare function normalizeRange<T>(range: T[]): (string | T)[];
export declare function toBoolean(data: FunctionResultObject | CellValue | undefined): boolean;
export declare function toJsDate(data: FunctionResultObject | CellValue | undefined, locale: Locale): DateTime;
export declare function toValue(data: FunctionResultObject | CellValue | undefined): CellValue | undefined;
export declare function visitAny(args: Arg[], cb: (a: Maybe<FunctionResultObject>) => void): void;
export declare function visitNumbers(args: Arg[], cb: (arg: FunctionResultNumber) => void, locale: Locale): void;
export declare function reduceAny<T, M>(args: (T | Matrix<T>)[], cb: (acc: M, a: T) => M, initialValue: M, dir?: "rowFirst" | "colFirst"): M;
export declare function reduceNumbers(args: Arg[], cb: (acc: number, a: number) => number, initialValue: number, locale: Locale): number;
export declare function reduceNumbersTextAs0(args: Arg[], cb: (acc: number, a: number) => number, initialValue: number, locale: Locale): number;
/**
 * Generate a matrix of size nColumns x nRows and apply a callback on each position
 */
export declare function generateMatrix<T>(nColumns: number, nRows: number, callback: (col: number, row: number) => T): Matrix<T>;
export declare function matrixMap<T, M>(matrix: Matrix<T>, callback: (value: T) => M): Matrix<M>;
export declare function matrixForEach<T>(matrix: Matrix<T>, fn: (value: T) => void): void;
export declare function transposeMatrix<T>(matrix: Matrix<T>): Matrix<T>;
/**
 * Enables a formula function to accept matrix or vector inputs instead of simple value, computing results across multiple dimensions.
 *
 * ```
 *                    /         |‾                 ‾| \        |‾                                                    ‾|
 *                   |          | [A]               |  |       | compute(A, D, E), compute(A, D, F), compute(A, D, G) |
 * applyVectorization| compute, | [B], D, [E, F, G] |  |  <=>  | compute(B, D, E), compute(B, D, F), compute(B, D, G) |
 *                   |          | [C]               |  |       | compute(C, D, E), compute(C, D, F), compute(C, D, G) |
 *                    \         |_                 _| /        |_                                                    _|
 * ```
 *
 * By default, all arguments are vectorized. To control which arguments are vectorized,
 * pass an `acceptToVectorize` boolean array of the same length as `args`:
 * - `true`  enables vectorization for that argument
 * - `false` disables vectorization for that argument
 *
 * For example, with `[true, true, false]` on previous example you get:
 *
 * ```
 * |‾                        ‾|
 * | compute(A, D, [E, F, G]) |
 * | compute(B, D, [E, F, G]) |
 * | compute(C, D, [E, F, G]) |
 * |_                        _|
 * ```
 *
 * @remarks
 * This helper is automatically applied (by default) to **all** `compute` functions
 * across the various spreadsheet formula modules:
 * - If an argument is declared **scalar** (not `"range"`), it is vectorized.
 * - If **all** arguments are declared **ranges**, no vectorization occurs.
 *   - e.g. `SUM(A1:B2)` returns a 1×1 sum over the range.
 *   - e.g. `COS(A1:B2)` over `A1:B2` returns a 2×2 element-wise result.
 * - For special behaviors (e.g. the `IF` function), you may declare all arguments
 *   as ranges and invoke this helper directly within your `compute` implementation.
 */
export declare function applyVectorization(formula: (...args: Arg[]) => Matrix<FunctionResultObject> | FunctionResultObject, args: Arg[], acceptToVectorize?: boolean[] | undefined): FunctionResultObject | Matrix<FunctionResultObject>;
export declare function conditionalVisitBoolean(args: Arg[], cb: (a: boolean) => boolean): void;
/**
 * Functions used especially for predicate evaluation on ranges.
 *
 * Take ranges with same dimensions and take predicates, one for each range.
 * For (i, j) coordinates, if all elements with coordinates (i, j) of each
 * range correspond to the associated predicate, then the function uses a callback
 * function with the parameters "i" and "j".
 *
 * Syntax:
 * visitMatchingRanges([range1, predicate1, range2, predicate2, ...], cb(i,j), likeSelection)
 *
 * - range1 (range): The range to check against predicate1.
 * - predicate1 (string): The pattern or test to apply to range1.
 * - range2: (range, repeatable) ranges to check.
 * - predicate2 (string, repeatable): Additional pattern or test to apply to range2.
 *
 * - cb(i: number, j: number) => void: the callback function.
 *
 * - isQuery (boolean) indicates if the comparison with a string should be done as a SQL-like query.
 * (Ex1 isQuery = true, predicate = "abc", element = "abcde": predicate match the element),
 * (Ex2 isQuery = false, predicate = "abc", element = "abcde": predicate not match the element).
 * (Ex3 isQuery = true, predicate = "abc", element = "abc": predicate match the element),
 * (Ex4 isQuery = false, predicate = "abc", element = "abc": predicate match the element).
 */
export declare function visitMatchingRanges(args: Arg[], cb: (i: number, j: number) => void, locale: Locale, isQuery?: boolean): void;
/**
 * Perform a dichotomic search on an array and return the index of the nearest match.
 *
 * The array should be sorted, if not an incorrect value might be returned. In the case where multiple
 * element of the array match the target, the method will return the first match if the array is sorted
 * in descending order, and the last match if the array is in ascending order.
 *
 *
 * @param data the array in which to search.
 * @param target the value to search.
 * @param mode "nextGreater/nextSmaller" : return next greater/smaller value if no exact match is found.
 * @param sortOrder whether the array is sorted in ascending or descending order.
 * @param rangeLength the number of elements to consider in the search array.
 * @param getValueInData function returning the element at index i in the search array.
 */
export declare function dichotomicSearch<T>(data: T, target: Maybe<FunctionResultObject>, mode: "nextGreater" | "nextSmaller" | "strict", sortOrder: SortDirection, rangeLength: number, getValueInData: (range: T, index: number) => CellValue | undefined): number;
export type LinearSearchMode = "nextSmaller" | "nextGreater" | "strict" | "wildcard";
/**
 * Perform a linear search and return the index of the match.
 * -1 is returned if no value is found.
 *
 * Example:
 * - [3, 6, 10], 3 => 0
 * - [3, 6, 10], 6 => 1
 * - [3, 6, 10], 9 => -1
 * - [3, 6, 10], 2 => -1
 *
 * @param data the array to search in.
 * @param target the value to search in the array.
 * @param mode if "strict" return exact match index. "nextGreater" returns the next greater
 * element from the target and "nextSmaller" the next smaller
 * @param numberOfValues the number of elements to consider in the search array.
 * @param getValueInData function returning the element at index i in the search array.
 * @param reverseSearch if true, search in the array starting from the end.

 */
export declare function linearSearch<T>(data: T, target: Maybe<FunctionResultObject> | undefined, mode: LinearSearchMode, numberOfValues: number, getValueInData: (data: T, index: number) => CellValue | undefined, lookupCaches?: LookupCaches, reverseSearch?: boolean): number;
export declare function toMatrix<T>(data: T | Matrix<T> | undefined): Matrix<T>;
/**
 * Flatten an array of items, where each item can be a single value or a 2D array, and apply the
 * callback to each element.
 *
 * The 2D array are flattened row first.
 */
export declare function flattenRowFirst<T, K>(items: Array<T | Matrix<T>>, callback: (val: T) => K): K[];
export declare function isDataNonEmpty(data: FunctionResultObject | undefined): boolean;
export declare const noValidInputErrorMessage: string;
export declare function emptyDataErrorMessage(argName: string): string;