import { EvalContext } from './context.js';
/**
 * §18.17.2 — the seven error values a formula can carry. Stored as their literal
 * display text so they round-trip and read naturally in diagnostics.
 */
export type FErr = '#NULL!' | '#DIV/0!' | '#VALUE!' | '#REF!' | '#NAME?' | '#NUM!' | '#N/A';
/**
 * A rectangle of cells (absolute, 0-indexed, inclusive) — the value an `A1:B3`
 * reference evaluates to. A single cell is a 1×1 rect. Aggregate functions iterate
 * it; scalar contexts dereference it (1×1 → its value, else `#VALUE!`).
 */
export interface Rect {
    readonly r0: number;
    readonly c0: number;
    readonly r1: number;
    readonly c1: number;
}
/** One of the five scalar value kinds a formula evaluates to. */
export type Scalar = {
    readonly t: 'num';
    readonly v: number;
} | {
    readonly t: 'str';
    readonly v: string;
} | {
    readonly t: 'bool';
    readonly v: boolean;
} | {
    readonly t: 'err';
    readonly v: FErr;
} | {
    readonly t: 'blank';
};
/**
 * Any value a formula evaluates to: a {@link Scalar}, a `ref` (a {@link Rect},
 * optionally cross-sheet), or an `arr` (an inline array constant).
 *
 * `sheet` (a workbook sheet index) is set only for a cross-sheet qualifier
 * (`Sheet2!A1`) or a defined name that targets another sheet; when undefined the
 * reference is on the rule's own sheet (the common case).
 *
 * An `arr` value is an inline array constant (`{1,2;3,4}`) — rows of scalars. It
 * flattens into aggregates, broadcasts element-wise against a scalar in the
 * operators, and collapses to its top-left element in a scalar context (Excel's
 * implicit intersection of a constant array).
 */
export type FValue = Scalar | {
    readonly t: 'ref';
    readonly rect: Rect;
    readonly sheet?: number;
} | {
    readonly t: 'arr';
    readonly rows: ReadonlyArray<ReadonlyArray<Scalar>>;
};
/** The blank scalar (an empty / absent cell). */
export declare const BLANK: Scalar;
/** The logical TRUE scalar. */
export declare const TRUE: Scalar;
/** The logical FALSE scalar. */
export declare const FALSE: Scalar;
/** Wrap a number as a scalar; a non-finite result (overflow, 0/0) becomes `#NUM!`. */
export declare function num(v: number): Scalar;
/** Wrap a string as a text scalar. */
export declare function str(v: string): Scalar;
/** The {@link TRUE} / {@link FALSE} scalar for a boolean. */
export declare function bool(v: boolean): Scalar;
/** Wrap an error code as an error scalar. */
export declare function err(v: FErr): Scalar;
/** Type guard: is the value an error scalar? */
export declare function isErr(v: FValue): v is {
    t: 'err';
    v: FErr;
};
/**
 * Collapse a reference to a scalar: a 1×1 rect yields the cell's value (a blank cell
 * → blank); any larger rect in a scalar context is `#VALUE!` (we do not implement
 * implicit intersection). An array constant collapses to its top-left element;
 * non-refs pass through unchanged.
 */
export declare function deref(v: FValue, ctx: EvalContext): Scalar;
/** Visit every scalar element of an array constant, row by row. */
export declare function arrEach(rows: ReadonlyArray<ReadonlyArray<Scalar>>, visit: (value: Scalar) => void): void;
/**
 * Iterate the populated cells of a reference, honouring a cross-sheet qualifier (an
 * absent `eachCellOn` ⇒ no cross-sheet support ⇒ the foreign range is empty).
 */
export declare function refEach(v: {
    readonly rect: Rect;
    readonly sheet?: number;
}, ctx: EvalContext, visit: (row: number, col: number, value: Scalar) => void): void;
/** Read one absolute cell on a reference's sheet (the current sheet when `sheet` is unset). */
export declare function refGet(sheet: number | undefined, ctx: EvalContext, row: number, col: number): Scalar;
/**
 * §18.17.3 — number coercion. blank → 0, logical → 1/0, a numeric string → its
 * number (Excel parses `"5"` and `" 5 "` leniently); non-numeric text → `#VALUE!`.
 * An error propagates (returned as the {@link FErr}); references are dereferenced first.
 */
export declare function toNumber(v: FValue, ctx: EvalContext): number | FErr;
/**
 * §18.17.3 — text coercion. A number formats with the shortest round-trip
 * representation, a logical as `TRUE`/`FALSE`, blank as the empty string. Errors
 * propagate (returned as the {@link FErr}).
 */
export declare function toText(v: FValue, ctx: EvalContext): string | FErr;
export declare function toBool(v: FValue, ctx: EvalContext): boolean | FErr;