/**
 * Excel-compatible value coercion and error-propagation helpers — the single
 * source of truth for how the evaluator and every {@link FormulaFunction} turn
 * loosely-typed {@link FormulaValue}s into numbers, text and booleans, and how
 * they compare and aggregate them.
 *
 * Centralizing these rules (rather than re-deriving them per function) keeps
 * behavior consistent with Excel/Sheets and avoids duplicated, subtly-divergent
 * coercion logic across ~50 functions.
 *
 * ### Key rules encoded here
 * - **Blanks** (`null`) coerce to `0` / `""` / `false` by context.
 * - **Booleans** coerce to `1`/`0` and `"TRUE"`/`"FALSE"`.
 * - **Errors short-circuit**: any {@link FormulaError} operand is returned
 *   unchanged, so a `#DIV/0!` deep in an expression surfaces at the top.
 * - **Range vs. literal aggregation**: numeric aggregators (SUM, AVERAGE, …)
 *   count only real numbers found *inside ranges*, but coerce *scalar literal*
 *   arguments — matching Excel's long-standing distinction.
 *
 * @packageDocumentation
 */
import { FormulaError, isFormulaError } from '../error/formula-error';
import type { FormulaValue, FormulaArgument, FormulaMatrix } from '../types/formula.types';
export { isFormulaError };
/** `true` when `arg` is a range matrix rather than a scalar value. */
export declare function isMatrix(arg: FormulaArgument): arg is FormulaMatrix;
/**
 * Collapses an argument to a single scalar: a 1×1 matrix becomes its cell, an
 * empty matrix is `#REF!`, and a wider matrix is `#VALUE!`. Scalar arguments
 * pass through unchanged. Used by functions that expect a single value in a
 * given argument position (e.g. `ABS`, `LEFT`).
 *
 * @param arg - A scalar or matrix argument.
 * @returns The scalar value (possibly a {@link FormulaError}).
 */
export declare function scalarArg(arg: FormulaArgument): FormulaValue;
/**
 * Scans a scalar or matrix argument for the first {@link FormulaError}.
 *
 * @param arg - A scalar or matrix argument.
 * @returns The first error found, or `null` if the argument is error-free.
 */
export declare function findError(arg: FormulaArgument): FormulaError | null;
/**
 * Returns the first error among several arguments (scanning inside matrices),
 * used to short-circuit strict functions before doing any work.
 *
 * @param args - The evaluated arguments.
 * @returns The first {@link FormulaError}, or `null` if none is present.
 */
export declare function firstErrorIn(args: readonly FormulaArgument[]): FormulaError | null;
/**
 * Invokes `cb` for every scalar value in an argument, flattening matrices in
 * `[row][col]` order. Allocation-free (no intermediate arrays).
 *
 * @param arg - A scalar or matrix argument.
 * @param cb  - Receiver for each scalar value.
 */
export declare function forEachValue(arg: FormulaArgument, cb: (v: FormulaValue) => void): void;
/**
 * Coerces a value to a number using Excel rules.
 *
 * - number → itself
 * - blank (`null`) → `0`
 * - boolean → `1` / `0`
 * - numeric string (trimmed) → its number; empty/non-numeric string → `#VALUE!`
 * - error → propagated unchanged
 *
 * @param v - The value to coerce.
 * @returns The number, or a {@link FormulaError}.
 */
export declare function toNumber(v: FormulaValue): number | FormulaError;
/**
 * Coerces a value to display text using Excel rules.
 *
 * - string → itself
 * - blank (`null`) → `""`
 * - boolean → `"TRUE"` / `"FALSE"`
 * - number → its general-format string
 * - error → propagated unchanged
 *
 * @param v - The value to coerce.
 * @returns The text, or a {@link FormulaError}.
 */
export declare function toText(v: FormulaValue): string | FormulaError;
/**
 * Coerces a value to a boolean using Excel rules.
 *
 * - boolean → itself
 * - blank (`null`) → `false`
 * - number → `v !== 0`
 * - `"TRUE"`/`"FALSE"` (case-insensitive) → the boolean; other strings → `#VALUE!`
 * - error → propagated unchanged
 *
 * @param v - The value to coerce.
 * @returns The boolean, or a {@link FormulaError}.
 */
export declare function toBoolean(v: FormulaValue): boolean | FormulaError;
/**
 * Renders a number as Excel's "General" format would: integers plainly, and
 * floats trimmed of binary-float noise (`0.1 + 0.2` → `"0.3"`).
 *
 * @param n - The number to render.
 * @returns The display string.
 */
export declare function numberToText(n: number): string;
/**
 * Three-way comparison of two scalar values with Excel semantics.
 *
 * Numbers compare numerically, strings case-insensitively, booleans `false <
 * true`; across types the order is number < text < boolean. Blanks adopt the
 * counterpart's type (so `blank = 0` and `blank = ""` are both true). Any error
 * operand short-circuits.
 *
 * @param a - Left value.
 * @param b - Right value.
 * @returns `-1`, `0`, `1`, or a {@link FormulaError}.
 */
export declare function compareValues(a: FormulaValue, b: FormulaValue): number | FormulaError;
/**
 * Collects numeric operands for an aggregation into `out`, applying Excel's
 * range-vs-literal rule:
 *
 * - **Inside a range (matrix)**: only genuine numbers are collected; blanks,
 *   text and booleans are ignored (they never turn a SUM into `#VALUE!`).
 * - **A scalar literal argument**: coerced via {@link toNumber}, so `SUM(1,"2",TRUE)`
 *   is `4`; a non-numeric literal string yields `#VALUE!`.
 *
 * Any error encountered (in a range cell or a literal) is returned immediately.
 *
 * @param args - The evaluated arguments.
 * @param out  - Destination array, appended in place (reused to avoid allocation).
 * @returns A {@link FormulaError} on the first error, otherwise `null`.
 */
export declare function collectNumbers(args: readonly FormulaArgument[], out: number[]): FormulaError | null;
//# sourceMappingURL=coerce.d.ts.map