/**
 * Utility functions for ExcelTS
 * Provides convenient helper functions for common spreadsheet operations
 */
import { Workbook } from "../workbook.js";
import type { Worksheet } from "../worksheet.js";
import type { CellValue } from "../types.js";
/**
 * Cell address object (0-indexed)
 */
export interface CellAddress {
    /** 0-indexed column number */
    c: number;
    /** 0-indexed row number */
    r: number;
}
/**
 * Range object with start and end addresses
 */
export interface Range {
    /** Start cell (top-left) */
    s: CellAddress;
    /** End cell (bottom-right) */
    e: CellAddress;
}
/**
 * Row data for JSON conversion
 */
export type JSONRow = Record<string, CellValue>;
/**
 * Decode column string to 0-indexed number
 * @example decodeCol("A") => 0, decodeCol("Z") => 25, decodeCol("AA") => 26
 */
export declare function decodeCol(colstr: string): number;
/**
 * Encode 0-indexed column number to string
 * @example encodeCol(0) => "A", encodeCol(25) => "Z", encodeCol(26) => "AA"
 */
export declare function encodeCol(col: number): string;
/**
 * Decode row string to 0-indexed number
 * @example decodeRow("1") => 0, decodeRow("10") => 9
 */
export declare function decodeRow(rowstr: string): number;
/**
 * Encode 0-indexed row number to string
 * @example encodeRow(0) => "1", encodeRow(9) => "10"
 */
export declare function encodeRow(row: number): string;
/**
 * Decode cell address string to CellAddress object
 * @example decodeCell("A1") => {c: 0, r: 0}, decodeCell("B2") => {c: 1, r: 1}
 */
export declare function decodeCell(cstr: string): CellAddress;
/**
 * Encode CellAddress object to cell address string
 * @example encodeCell({c: 0, r: 0}) => "A1", encodeCell({c: 1, r: 1}) => "B2"
 */
export declare function encodeCell(cell: CellAddress): string;
/**
 * Decode range string to Range object
 * @example decodeRange("A1:B2") => {s: {c: 0, r: 0}, e: {c: 1, r: 1}}
 */
export declare function decodeRange(range: string): Range;
/**
 * Encode Range object to range string
 */
export declare function encodeRange(range: Range): string;
export declare function encodeRange(start: CellAddress, end: CellAddress): string;
/** Origin can be cell address string, cell object, row number, or -1 to append */
export type Origin = string | CellAddress | number;
export interface JSON2SheetOpts {
    /** Use specified field order (default Object.keys) */
    header?: string[];
    /** Use specified date format in string output */
    dateFormat?: string;
    /** Store dates as type d (default is n) */
    cellDates?: boolean;
    /** If true, do not include header row in output */
    skipHeader?: boolean;
    /** If true, emit #NULL! error cells for null values */
    nullError?: boolean;
}
export interface SheetAddJSONOpts extends JSON2SheetOpts {
    /** Use specified cell as starting point */
    origin?: Origin;
}
/**
 * Create a worksheet from an array of objects (xlsx compatible)
 * @example
 * const ws = jsonToSheet([{name: "Alice", age: 30}, {name: "Bob", age: 25}])
 */
export declare function jsonToSheet(data: JSONRow[], opts?: JSON2SheetOpts): Worksheet;
/**
 * Add data from an array of objects to an existing worksheet (xlsx compatible)
 */
export declare function sheetAddJson(worksheet: Worksheet, data: JSONRow[], opts?: SheetAddJSONOpts): Worksheet;
export interface Sheet2JSONOpts {
    /**
     * Control output format:
     * - 1: Generate an array of arrays
     * - "A": Row object keys are literal column labels (A, B, C, ...)
     * - string[]: Use specified strings as keys in row objects
     * - undefined: Read and disambiguate first row as keys
     */
    header?: 1 | "A" | string[];
    /**
     * Override Range:
     * - number: Use worksheet range but set starting row to the value
     * - string: Use specified range (A1-Style bounded range string)
     * - undefined: Use worksheet range
     */
    range?: number | string;
    /** Use raw values (true, default) or formatted text strings with trim (false) */
    raw?: boolean;
    /** Default value for empty cells */
    defval?: CellValue;
    /** Include blank lines in the output */
    blankrows?: boolean;
    /**
     * Override format for date values (not applied to time-only formats).
     * When provided, Date values will be formatted using this format string.
     * @example "dd/mm/yyyy" or "yyyy-mm-dd"
     */
    dateFormat?: string;
}
/**
 * Convert worksheet to JSON array (xlsx compatible)
 * @example
 * // Default: array of objects with first row as headers
 * const data = sheetToJson(worksheet)
 * // => [{name: "Alice", age: 30}, {name: "Bob", age: 25}]
 *
 * // Array of arrays
 * const aoa = sheetToJson(worksheet, { header: 1 })
 * // => [["name", "age"], ["Alice", 30], ["Bob", 25]]
 *
 * // Column letters as keys
 * const cols = sheetToJson(worksheet, { header: "A" })
 * // => [{A: "name", B: "age"}, {A: "Alice", B: 30}]
 */
export declare function sheetToJson<T = JSONRow>(worksheet: Worksheet, opts?: Sheet2JSONOpts): T[];
export interface Sheet2CSVOpts {
    /** Field separator (default: ",") */
    FS?: string;
    /** Record separator (default: "\n") */
    RS?: string;
    /** Skip blank rows */
    blankrows?: boolean;
    /** Force quote all fields */
    forceQuotes?: boolean;
}
/**
 * Convert worksheet to CSV string
 */
export declare function sheetToCsv(worksheet: Worksheet, opts?: Sheet2CSVOpts): string;
/**
 * Create a new workbook
 */
export declare function bookNew(): Workbook;
/**
 * Append worksheet to workbook (xlsx compatible)
 * @example
 * const wb = bookNew();
 * const ws = jsonToSheet([{a: 1, b: 2}]);
 * bookAppendSheet(wb, ws, "Sheet1");
 */
export declare function bookAppendSheet(workbook: Workbook, worksheet: Worksheet, name?: string): void;
export interface AOA2SheetOpts {
    /** Use specified cell as starting point */
    origin?: Origin;
    /** Use specified date format in string output */
    dateFormat?: string;
    /** Store dates as type d (default is n) */
    cellDates?: boolean;
}
/**
 * Create a worksheet from an array of arrays (xlsx compatible)
 * @example
 * const ws = aoaToSheet([["Name", "Age"], ["Alice", 30], ["Bob", 25]])
 */
export declare function aoaToSheet(data: CellValue[][], opts?: AOA2SheetOpts): Worksheet;
/**
 * Add data from an array of arrays to an existing worksheet (xlsx compatible)
 */
export declare function sheetAddAoa(worksheet: Worksheet, data: CellValue[][], opts?: AOA2SheetOpts): Worksheet;
/**
 * Convert worksheet to array of arrays
 */
export declare function sheetToAoa(worksheet: Worksheet): CellValue[][];
