/**
 * Shared helpers for native function implementations.
 *
 * Centralizes small utilities that were previously duplicated across multiple
 * function files (math, statistical, financial, text, date, engineering,
 * conditional, dynamic-array, database, lookup). None of these change runtime
 * semantics — they are the canonical extractions of the identical helpers that
 * appeared in several modules.
 */
import type { RuntimeValue, ScalarValue, NumberValue, ErrorValue, ArrayValue } from "../runtime/values.js";
/**
 * Return the error value if `v` (as a scalar, extracted via `topLeft`) is an
 * error; otherwise return `null`. Used by text / date / engineering functions
 * for the standard "propagate first-arg error" pattern.
 */
export declare function checkError(v: RuntimeValue): ErrorValue | null;
/**
 * Coerce a single RuntimeValue argument to a number. Applies `topLeft` first
 * so that a 1×1 (or arbitrary) array yields its top-left scalar before
 * numeric coercion. Matches the semantics formerly found as `argToNumber` in
 * `math.ts` and `numArg(args, idx)` in `statistical.ts`.
 */
export declare function argToNumber(arg: RuntimeValue): NumberValue | ErrorValue;
/**
 * Flatten a list of arguments into a sequence of numeric values (or errors).
 *
 * Array arguments contribute only their `Number` and `Error` cells — booleans,
 * strings, and blanks inside arrays are skipped (Excel range semantics).
 * Direct scalar arguments are coerced via `toNumberRV`, except for direct
 * `Blank` scalars which are skipped (Excel aggregate semantics).
 *
 * Returns a list of `NumberValue | ErrorValue`. Callers that need raw
 * `number[]` after an error check should map `.value` themselves.
 */
export declare function flattenNumbers(args: RuntimeValue[]): (NumberValue | ErrorValue)[];
/**
 * Streaming fold over numeric arguments.
 *
 * Same selection rules as `flattenNumbers` (array cells contribute only
 * Number/Error; direct scalar coercion via `toNumberRV`; blanks dropped),
 * but the caller's `onNumber` callback fires inline — no intermediate
 * array is allocated. On the first error encountered the scan short-
 * circuits and returns that error.
 *
 * Returns:
 *   - `null` when iteration finished without encountering an error, or
 *   - the `ErrorValue` that aborted the scan.
 *
 * Prefer this over `flattenNumbers` + `firstError` + manual loop in hot
 * aggregates (SUM / AVERAGE / MIN / MAX / …). The allocation saved is
 * one `NumberValue | ErrorValue` array per invocation — meaningful
 * when the engine sums tens of thousands of cells.
 */
export declare function forEachNumber(args: readonly RuntimeValue[], onNumber: (n: number) => void): ErrorValue | null;
/**
 * Flatten all cells from the arguments into a flat list of ScalarValue,
 * preserving every cell (including blanks, errors, booleans, strings).
 * Direct scalar arguments are projected via `topLeft`.
 */
export declare function flattenAll(args: RuntimeValue[]): ScalarValue[];
/**
 * Return the first `ErrorValue` in a list of `NumberValue | ErrorValue`,
 * or `null` if none is present.
 */
export declare function firstError(values: readonly (NumberValue | ErrorValue)[]): ErrorValue | null;
/**
 * Narrow a RuntimeValue to an ArrayValue, returning `null` if it is not an
 * array. Used by conditional / database / lookup / dynamic-array families.
 */
export declare function asArray(v: RuntimeValue): ArrayValue | null;
/**
 * Safe cell accessor for ArrayValue — returns `BLANK` for out-of-bounds (r, c).
 */
export declare function getCell(arr: ArrayValue, r: number, c: number): ScalarValue;
/**
 * Return `true` if `s` contains an unescaped `*` or `?`. Excel uses `~` as
 * the escape character, so `~*` and `~?` are literals while `*` and `?` at
 * any other position are wildcards. `~~` is an escaped tilde.
 *
 * Centralised here so every wildcard-consuming function (SEARCH, MATCH,
 * XLOOKUP, SUMIF/COUNTIF/…) agrees on whether a criterion should trigger
 * the wildcard code path.
 */
export declare function hasUnescapedWildcard(s: string): boolean;
/**
 * Convert an Excel wildcard pattern to a JavaScript regex source. Rules:
 *   `*`     → `.*`
 *   `?`     → `.`
 *   `~*`    → literal `*`
 *   `~?`    → literal `?`
 *   `~~`    → literal `~`
 *   `~x`    → literal `x` (any other character after `~` is treated literally,
 *             matching Excel's tolerant behaviour)
 *   everything else → regex-escaped literal
 *
 * Callers typically wrap the result in `^…$` and use the `i` flag for
 * case-insensitive matching.
 */
export declare function excelWildcardToRegex(s: string): string;
/**
 * Strip `~` escape characters from an Excel criteria string so the remaining
 * text can be used for a literal comparison. `~*` → `*`, `~?` → `?`,
 * `~~` → `~`, etc. Only used when the caller has already determined that the
 * pattern contains no unescaped wildcards.
 */
export declare function unescapeExcelWildcard(s: string): string;
/**
 * Replace every cell marked by the array's `subtotalMask` with BLANK so an
 * outer SUBTOTAL/AGGREGATE call does not double-count the inner aggregate's
 * result. Only ArrayValue args carrying a mask are rewritten; scalars and
 * arrays without masks pass through unchanged.
 *
 * Excel behavior: SUBTOTAL and AGGREGATE deliberately skip any cell whose
 * own formula is itself SUBTOTAL or AGGREGATE — this is how the classic
 * "totals row inside a filtered range" case works without double-counting.
 */
export declare function stripSubtotalMaskedCells(args: RuntimeValue[]): RuntimeValue[];
/**
 * Replace every cell in a hidden row with BLANK so aggregate functions
 * drop them during flattening. Callers: SUBTOTAL's 1xx-variant codes
 * (101-111) and AGGREGATE with option 5 or 7.
 *
 * Only ArrayValue args carrying a hiddenRowMask are rewritten.
 */
export declare function stripHiddenRowCells(args: RuntimeValue[]): RuntimeValue[];
/**
 * Replace every error cell inside ArrayValue args with BLANK so
 * aggregate functions simply skip them during flattening. Callers:
 * AGGREGATE with option 2, 3, 6, or 7.
 *
 * Direct scalar error args are left alone — AGGREGATE's caller
 * already passes them as scalars; our aggregators will surface them
 * as-is, which matches Excel when a direct literal is an error.
 *
 * This is distinct from the standard error-propagation path: arrays
 * that contain errors normally propagate those errors out of the
 * aggregate. With option 2/3/6/7, errors inside the *arrays* are
 * deliberately ignored.
 */
export declare function stripErrorCells(args: RuntimeValue[]): RuntimeValue[];