Interface ICellRanges

An ICellRanges is a collection of ICellRanges.

Useful when working with a discontinuous set of ranges.

interface ICellRanges {
    isICellRanges: true;
    get length(): number;
    get size(): number;
    "[iterator]"(): IterableIterator<Scalar>;
    "[iterator]"(options?: ICellRange.IteratorOptions<any>): Iterator<Scalar>;
    addListener(listener: Listener, options?: ListenerOptions): Remove;
    addWatch(
        formula: string | IFormula,
        callback: ICellRanges.WatchCallback,
        options?: WatchOptions,
    ): Remove;
    at(index: number): ICellRange;
    autoFit(options?: AutoFitOptions): this;
    calculate(fullRecalc?: boolean): this;
    clear(
        applyTo?: ICell.Content,
        options?: ITransaction.OperationOptions,
    ): this;
    copyFrom(
        source: ICellRange.Address | ICellRange.ISnapshot<any, any>,
        options?: ICellRange.CopyOptions,
    ): Promise<ICellRanges | null>;
    delete(options?: Axis | DeleteOptions): this;
    doBatch<R>(
        callback: (commit: ICommit) => R | Promise<R>,
        options?: string | ITransaction.OperationOptions,
    ): R | Promise<R>;
    entries(
        options?: ICellRange.IteratorOptions<ICellRange.Address>,
    ): IterableIterator<ICellRange.Entry<Scalar>>;
    find(options: string | FindOptions): Iterator<ICell>;
    getAddress(r1c1?: boolean): string;
    getColumnCount(): number;
    getColumnHeaders(
        options?: ICellHeaderRange.GetRangeOptions,
    ): ICellHeaderRanges;
    getCoords(): readonly Readonly<FixableCoords>[];
    getCount(): number;
    getCounts(
        features?: ICellRange.Feature | readonly ICellRange.Feature[],
    ): Counts;
    getDefaultShiftAxis(): Axis;
    getDependents(entireSet?: boolean): Promise<ICellRanges | null>;
    getEntireColumns(
        shiftRows?: boolean,
        options?: ICellRange.GetRangeOptions,
    ): this;
    getEntireRows(
        shiftColumns?: boolean,
        options?: ICellRange.GetRangeOptions,
    ): this;
    getFixed(options: boolean | GetFixedOptions): this;
    getFlattened(options?: GetFlattenOptions): this;
    getMerges(): Coords[];
    getPrecedents(entireSet?: boolean): Promise<ICellRanges | null>;
    getRowCount(): number;
    getRowHeaders(
        options?: ICellHeaderRange.GetRangeOptions,
    ): ICellHeaderRanges;
    getSheet(): ISheet;
    getSnapshot(options?: ICellRange.CopyOptions): ICellRange.ISnapshot;
    getStats(options?: GetStatsOptions): IRangeStats;
    getStyle(): IStyle;
    getVisible(options?: GetVisibleOptions): ICellRanges | null;
    insert(options?: Axis | InsertOptions): this;
    insertFrom(
        source: ICellRange.Address | ICellRange.ISnapshot<any, any>,
        options?: InsertFromOptions,
    ): Promise<ICellRanges | null>;
    isContentful(
        features?: ICellRange.Feature | readonly ICellRange.Feature[],
    ): boolean;
    isEntireColumns(): boolean;
    isEntireColumnsAny(): boolean;
    isEntireRows(): boolean;
    isEntireRowsAny(): boolean;
    isEqual(
        address: ICellRanges.Address,
        options?: ICellRange.GetRangeOptions,
    ): boolean;
    isInvalid(): boolean;
    isInvalidAny(): boolean;
    isOverlapping(): boolean;
    isReadOnly(): boolean;
    isSingleCell(): boolean;
    merge(options?: AxisSelection | MergeOptions): this;
    select(options?: ICellRange.SelectOptions): Promise<ICellRanges>;
    setValue(value: ScalarUpdate, options?: SetValuesOptions): this;
    toString(): string;
    unmerge(options?: ITransaction.OperationOptions): this;
}

Properties

`Readonly`isICellRanges

isICellRanges: true

For runtime type checking.

Accessors

length

get length(): number

Return the number of contiguous ranges.

Returns number

Remarks
Alias for getCount but named to be more consistent with IListLike and Array.

size

get size(): number

Returns the size of all of the ranges this is the rows * columns.

Returns number

Methods

[iterator]

"[iterator]"(): IterableIterator<Scalar>

Iterates over the values, yielding each values in the collection.

Returns IterableIterator<Scalar>

Remarks
This does not iterate over the ranges but rather the individual cells within the ranges.

See
()
"[iterator]"(options?: ICellRange.IteratorOptions<any>): Iterator<Scalar>
Returns an iterator that allows you to iterate over the individual values within the range.
Parameters
- Optionaloptions: ICellRange.IteratorOptions<any>
  Configuration options for the iterator, such as filtering or sorting.
Returns Iterator<Scalar>
An iterator that yields Scalar value, each representing a single cell within the range.

addListener

addListener(listener: Listener, options?: ListenerOptions): Remove
Add a listener to the range.
Parameters
- listener: Listener
- Optionaloptions: ListenerOptions
Returns Remove
A callback to remove. IListener.Remove

Remarks
If the range becomes invalid through a delete this will auto remove.

addWatch

addWatch(
    formula: string | IFormula,
    callback: ICellRanges.WatchCallback,
    options?: WatchOptions,
): Remove
ICellRange.addWatch across every area, as ONE expression authored at a shared origin.
Parameters
- formula: string | IFormula
  An expression, or a formula, authored at the top-left of the bounding box of every area — which need not be a cell of any area.
- callback: ICellRanges.WatchCallback
  Receives each area's results separately, with the area's index and the area.
- Optionaloptions: WatchOptions
  How each cell is evaluated; see ICellRange.WatchOptions.
Returns Remove
A callback removing every area's watch.

Remarks
This is the form a multi-area rule wants, and the reason it exists is the anchor. A conditional format over E5:F6 E10:F11 stores ONE formula, authored at the sqref origin E5 — so E10 must evaluate that formula FILLED to E10, an anchor no cell in the second area carries. Over E7:F7 B11:C11 the origin is B7: the areas' order does not matter. Compiling each area against its own top-left instead makes area two read area one's cells: E5>5 read from E10 means "is the cell five rows up greater than 5".

So the fill lives here, where the areas are known to belong to one rule, rather than on ICellRange.addWatch, which takes what it is given and refuses to guess. Callers pass no anchor and compute no offsets.

One watch per area — deliberately not pooled by expression. The callback therefore fires per area, and an edit touching two of them delivers twice.

at

at(index: number): ICellRange
Returns the range at a specific index.
Parameters
- index: number
Returns ICellRange

autoFit

autoFit(options?: AutoFitOptions): this
Adjusts the column widths and rows heights to fit the content.
Parameters
- Optionaloptions: AutoFitOptions
Returns this
The current ICellRange.

calculate

calculate(fullRecalc?: boolean): this
Re-evaluates and formulas within the range.
Parameters
- OptionalfullRecalc: boolean
  If true then all formulas will be recalculated.
Returns this

clear

clear(applyTo?: ICell.Content, options?: ITransaction.OperationOptions): this
Clear the range.
Parameters
- OptionalapplyTo: ICell.Content
  The type of content to clear. Defaults to all@returns The currentICellRange`.
- Optionaloptions: ITransaction.OperationOptions
Returns this

copyFrom

copyFrom(
source: ICellRange.Address | ICellRange.ISnapshot<any, any>,
options?: ICellRange.CopyOptions,
): Promise<ICellRanges | null>
Copies (or cuts) data and formatting from a specified source to the current range.
Parameters
- source: ICellRange.Address | ICellRange.ISnapshot<any, any>
  The source of the data and formatting to be copied or cut. This can be either a range address, another range object, or an ISnapshot created using the getSnapshot method.
- Optionaloptions: ICellRange.CopyOptions
Returns Promise<ICellRanges | null>
A promise that resolve to an ICellRange or 'null' when the copy has completed.
Remarks
- Will return null if nothing was inserted or the source doesn't have a range.

delete

delete(options?: Axis | DeleteOptions): this
Delete the cells within the range and shifts the remaining cells to fill the gap.
Parameters
- Optionaloptions: Axis | DeleteOptions
  The axis or The direction in which to shift existing cells. Defaults to the axis where the range's dimension is smaller (e.g., shifts down if the range is wider than it is tall). See ICellRange.getDefaultShiftAxis for details on the default behavior. See ITransaction.OperationOptions
Returns this
The current ICellRange.

Remarks
This is different from clearing cells, which removes their content but doesn't affect the overall sheet structure. Deleting cells results in a shift of the remaining data.

doBatch

doBatch<R>(
callback: (commit: ICommit) => R | Promise<R>,
options?: string | ITransaction.OperationOptions,
): R | Promise<R>
Perform a set of operations as a batch.
Type Parameters
- R
  The callback return type.
Parameters
- callback: (commit: ICommit) => R | Promise<R>
  Function to perform the operations.
- Optionaloptions: string | ITransaction.OperationOptions
  Description of the operation or additional options. This will be used for tracking undo/redo and history.
Returns R | Promise<R>
The result of the callback.

entries

entries(
options?: ICellRange.IteratorOptions<ICellRange.Address>,
): IterableIterator<ICellRange.Entry<Scalar>>
Returns an iterator that allows you to iterate over the individual cells within the ranges, yielding pairs of IteratorContext and a Value.
Parameters
- Optionaloptions: ICellRange.IteratorOptions<ICellRange.Address>
  Configuration options for the iterator, such as filtering or sorting.
Returns IterableIterator<ICellRange.Entry<Scalar>>
An iterator that yields [ICell.IteratorContext, Value] tuples for each value within the range.

Remarks
If the ranges overlap this will return the same value multiple times. If each cell should only be visited once, use ICellRanges.getFlattened to remove overlaps.

find

find(options: string | FindOptions): Iterator<ICell>
Returns an iterator of ICells that match the results.
Parameters
- options: string | FindOptions
  The text to search for or FindOptions
Returns Iterator<ICell>

getAddress

getAddress(r1c1?: boolean): string
The address of these ranges. See ICellRange.getAddress.
Parameters
- Optionalr1c1: boolean
Returns string
Remarks
Whether the address is sheet-QUALIFIED is a property of where the ranges came from, not an option — and it is the caller's signal for what these ranges mean:
- sheet-scoped (sheet.getRanges(...), sheet.getSelectedRanges(), a table's range) — BARE ($B$2:$D$5). One implicit sheet; there is nothing to qualify against.
- workbook-scoped (workbook.getRanges(...), a formula's getReferences()) — always QUALIFIED (Sheet1!$B$2:$D$5), each range by its own scope, so a multi-sheet set round-trips.
Both keep $ fixability. Callers must NOT re-derive either form (prefixing a sheet name onto an already-qualified address doubles it; rebuilding from numeric coords drops the $ flags) — take the string as given, and choose the SOURCE that carries the scoping you want.

getColumnCount

getColumnCount(): number

Returns the count for all columns in the ranges. This will ensure columns that are included in multiples ranges are not double counted.

Returns number

getColumnHeaders

getColumnHeaders(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRanges
Returns the header range for the columns.
Parameters
- Optionaloptions: ICellHeaderRange.GetRangeOptions
Returns ICellHeaderRanges
ICellHeaderRange for the columns.

getCoords

getCoords(): readonly Readonly<FixableCoords>[]

The RangeCoords.

Returns readonly Readonly<FixableCoords>[]

getCount

getCount(): number

Returns the total number of contiguous ranges in this collection.

Returns number

getCounts

getCounts(features?: ICellRange.Feature | readonly ICellRange.Feature[]): Counts
Returns per-feature cell counts for the range.
Parameters
- Optionalfeatures: ICellRange.Feature | readonly ICellRange.Feature[]
  The features to count. Defaults to all public features — counting is the discovery call.
Returns Counts
Remarks
getCounts answers "how much of each feature is here"; getStats answers "what are the values like". Feature occupancy vs value analysis — they do not overlap.
- Every public ICellRange.Feature appears as a key; features not requested, or not present, are an explicit 0 — the shape is stable and self-describing, never null.
- Each feature is counted independently. getCounts([Fill, Border]) is two numbers, not the count of their refined intersection — the refined count is getRegions.
- Counts are cells, never regions: a region count would either disagree with the partition getRegions returns or cost as much as computing it.

getDefaultShiftAxis

getDefaultShiftAxis(): Axis

Returns the default shift IRange.Axis for insert and delete if no axis is provided.

Returns Axis
Default IRange.Axis that will be used to shift the range.

Remarks
By default the direction of the shift will be the direction that shifts the fewest cells. If the range is the same size in both directions IRange.Axis.Row will be used.

For example, a range with 5 columns and 1 row will have a default axis of IRange.Axis.Row.

getDependents

getDependents(entireSet?: boolean): Promise<ICellRanges | null>
Returns the ranges whose formulas reference these ranges.
Parameters
- OptionalentireSet: boolean
  If true the search is recursive downstream through the full calculation chain to find the total impact of a value change; if false (the default) only the immediate consumers are returned.
Returns Promise<ICellRanges | null>

Remarks
Resolves null if the ranges have no dependents.

See
ICellRanges.getDirectDependents / ICellRanges.getDependents for the single-cell equivalents.

getEntireColumns

getEntireColumns(
shiftRows?: boolean,
options?: ICellRange.GetRangeOptions,
): this
Returns a range that includes the columns for the entire sheet. For example, if the range is A1:B2, this method will return A:B.
Parameters
- OptionalshiftRows: boolean
  If true this will also shift the columns by the width of the range. default false.
- Optionaloptions: ICellRange.GetRangeOptions
Returns this
ICellRange at the repositioned range.

getEntireRows

getEntireRows(
shiftColumns?: boolean,
options?: ICellRange.GetRangeOptions,
): this
Returns a range that includes the rows for the entire sheet. For example, if the range is A1:B2, this method will return 1:2.
Parameters
- OptionalshiftColumns: boolean
  If true this will also shift the rows by the height of the range. default false.
- Optionaloptions: ICellRange.GetRangeOptions
Returns this
ICellRange at the repositioned range.

getFixed

getFixed(options: boolean | GetFixedOptions): this
Returns a ranges with coordinates adjusted to be fixed (absolute) or flexible (relative).
Parameters
- options: boolean | GetFixedOptions
Returns this

See
ICellRange.getFixed

getFlattened

getFlattened(options?: GetFlattenOptions): this
Returns a set of ranges with overlaps removed and attempts to merge adjacent ranges into larger ranges.
Parameters
- Optionaloptions: GetFlattenOptions
Returns this

Remarks
By default, ranges will also be merged into larger ranges where possible, but this behavior can be customized using the mergeAxis parameter. This method will not modify the original ranges.

See
isOverlapping

getMerges

getMerges(): Coords[]
Return an array of coords for all merges.
Returns Coords[]
An array of 'IRange.Coords` that contain merges.

getPrecedents

getPrecedents(entireSet?: boolean): Promise<ICellRanges | null>
Returns the ranges referenced by the formulas within these ranges.
Parameters
- OptionalentireSet: boolean
  If true the search is recursive upstream through the full calculation chain to find all contributing ranges; if false (the default) only the direct inputs are returned.
Returns Promise<ICellRanges | null>

Remarks
Resolves null if the ranges have no precedents.

See
ICellRanges.getDirectPrecedents / ICellRanges.getPrecedents for the single-cell equivalents.

getRowCount

getRowCount(): number

Returns the count for all rows in the ranges. This will ensure rows that are included in multiples ranges are not double counted.

Returns number

getRowHeaders

getRowHeaders(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRanges
Returns the header range for the rows.
Parameters
- Optionaloptions: ICellHeaderRange.GetRangeOptions
Returns ICellHeaderRanges
ICellHeaderRange for the rows.

getSheet

getSheet(): ISheet

Returns the Sheet.

Returns ISheet

getSnapshot

getSnapshot(options?: ICellRange.CopyOptions): ICellRange.ISnapshot
Returns a ICellRange.ISnapshot for all of the ranges.
Parameters
- Optionaloptions: ICellRange.CopyOptions
Returns ICellRange.ISnapshot
Remarks
- This will fail if the ranges are not 'aligned'.
See
ICellRange.getSnapshot

getStats

getStats(options?: GetStatsOptions): IRangeStats
Returns the statistics for the ranges.
Parameters
- Optionaloptions: GetStatsOptions
  Iterator options the stats are created with — most usefully { onError: 'ignore' } so aggregate reads degrade instead of faulting on error values.
Returns IRangeStats

Remarks
Overlapping areas are flattened first — each cell contributes once, agreeing with getCounts.

See
ICellRange.getStats

getStyle

getStyle(): IStyle

Returns the style for the anchor of the ranges.

Returns IStyle

See
ICellRange.getStyle

getVisible

getVisible(options?: GetVisibleOptions): ICellRanges | null
Returns a range that excludes any hidden rows or columns.
Parameters
- Optionaloptions: GetVisibleOptions
  Optional parameters that can adjust how visibility is determined (e.g., by ignoring specific visibility rules).
Returns ICellRanges | null
An ICellRanges object that contains the visible portions of the range, excluding any hidden rows or columns.
Remarks
- If all ranges within the original selection are visible, this method returns an ICellRanges object with a single range and a length of 1.
- If the entire range is hidden, the method will return null.
- The resulting ranges reflect the currently visible state of the sheet, including hidden rows, columns, or headers.

insert

insert(options?: Axis | InsertOptions): this
Insert a new, empty range within the sheet and shifts existing cells to accommodate it.
Parameters
- Optionaloptions: Axis | InsertOptions
  The axis or The direction in which to shift existing cells. Defaults to the axis where the range's dimension is smaller (e.g., shifts down if the range is wider than it is tall). See ICellRange.getDefaultShiftAxis for details on the default behavior. See ITransaction.OperationOptions
Returns this
The current ICellRange.

Remarks
By default the values will direction in whichever direction the selection shape is smaller. For example a selection with a 5 column by 1 row will direction Down (rows). Note - This will error if direction data will fall outsize of the max sheet size.

insertFrom

insertFrom(
source: ICellRange.Address | ICellRange.ISnapshot<any, any>,
options?: InsertFromOptions,
): Promise<ICellRanges | null>
Inserts the contents of the source into the sheet, shifting existing cells to make space.
Parameters
- source: ICellRange.Address | ICellRange.ISnapshot<any, any>
  The source of the data and formatting to insert. This can be either a range address, another range object, or an ISnapshot created using the getSnapshot method.
- Optionaloptions: InsertFromOptions
Returns Promise<ICellRanges | null>
A promise that resolve to an ICellRange or 'null' when the copy has completed.
Remarks
- Behaves similarly to insert and copyFrom, but instead of inserting empty space at the range it also inserts the content of the source.
- Will return null if nothing was inserted or the source doesn't have a range.

isContentful

isContentful(
features?: ICellRange.Feature | readonly ICellRange.Feature[],
): boolean
Returns true if there is any content within the range.
Parameters
- Optionalfeatures: ICellRange.Feature | readonly ICellRange.Feature[]
  Restrict the check to specific features. Defaults to any content.
Returns boolean
'boolean' indicating if there is content.

Remarks
Some uses cases for this are checking for data to delete a sheet, checking for multiple values for merges.

isEntireColumns

isEntireColumns(): boolean

Returns true if every range is entire columns, such as B:D.

Returns boolean

Remarks
isEntireColumnsAny asks the same of any one range.

See
ICellRange.isEntireColumns

isEntireColumnsAny

isEntireColumnsAny(): boolean

Returns true if any range is entire columns, such as B:D.

Returns boolean

Remarks
isEntireColumns asks the same of every range.

isEntireRows

isEntireRows(): boolean

Returns true if every range is entire rows, such as 2:4.

Returns boolean

Remarks
isEntireRowsAny asks the same of any one range.

See
ICellRange.isEntireRows

isEntireRowsAny

isEntireRowsAny(): boolean

Returns true if any range is entire rows, such as 2:4.

Returns boolean

Remarks
isEntireRows asks the same of every range.

isEqual

isEqual(
address: ICellRanges.Address,
options?: ICellRange.GetRangeOptions,
): boolean
Returns true if the given address represents the same range as the current range.
Parameters
- address: ICellRanges.Address
  The address to compare against.
- Optionaloptions: ICellRange.GetRangeOptions
  Options for getting the range from the address.
Returns boolean

isInvalid

isInvalid(): boolean

Returns true if the range is invalid. This can occur if a range is removed or created with invalid coordinates.

Returns boolean

isInvalidAny

isInvalidAny(): boolean

Returns true if any of the ranges are invalid.

Returns boolean

isOverlapping

isOverlapping(): boolean

Returns a flag indicating if any of the ranges are overlapping.

Returns boolean

Remarks
To get a range with no overlaps ICellRanges.getFlattened can be used.

isReadOnly

isReadOnly(): boolean

Indicates if the range is readonly only.

Returns boolean

Remarks
Not an indicator of if the range is protected but rather if the range is being used in a way that doesn't support write operations. (e.g. the range is being provided as a listener source ICellRange.Event or the range belongs to a historical snapshot.)

isSingleCell

isSingleCell(): boolean

Returns true if only a single cell is included in the ranges.

Returns boolean

merge

merge(options?: AxisSelection | MergeOptions): this
Merges all cells within the selection ranges.
Parameters
- Optionaloptions: AxisSelection | MergeOptions
Returns this
The current ICellRange.

Remarks
If the ranges overlap then this operation will throw an exception

select

select(options?: ICellRange.SelectOptions): Promise<ICellRanges>
Selects the current range.
Parameters
- Optionaloptions: ICellRange.SelectOptions
Returns Promise<ICellRanges>
An async ICellRange.

setValue

setValue(value: ScalarUpdate, options?: SetValuesOptions): this
Broadcasts a single value into every cell of every range in the collection.
Parameters
- value: ScalarUpdate
- Optionaloptions: SetValuesOptions
Returns this

Remarks
This is Excel's Ctrl+Enter fill: the same scalar is written to all selected cells — across every discontiguous range — as a single ICellRanges.doBatch operation (one undo step). A formula string (e.g. "=A1+1") is coerced and its relative references adjust per cell, exactly as ICellRange.setValue does within one range.

Only the scalar-broadcast form exists (no setValues): a 2D shape has no coherent meaning spread across discontiguous ranges of differing sizes.

See
ICellRange.setValue

toString

toString(): string

Returns the address as a string.

Returns string

unmerge

unmerge(options?: ITransaction.OperationOptions): this
Unmerge all cells within the selection ranges.
Parameters
- Optionaloptions: ITransaction.OperationOptions
Returns this
The current ICellRange.

Interface ICellRanges

Index

Properties

Accessors

Methods

Properties

ReadonlyisICellRanges

Accessors

length

Returns number

Remarks

size

Returns number

Methods

[iterator]

Returns IterableIterator<Scalar>

Remarks

See

Parameters

Returns Iterator<Scalar>

addListener

Parameters

Returns Remove

Remarks

addWatch

Parameters

Returns Remove

Remarks

at

Parameters

Returns ICellRange

autoFit

Parameters

Returns this

calculate

Parameters

Returns this

clear

Parameters

Returns this

copyFrom

Parameters

Returns Promise<ICellRanges | null>

Remarks

delete

Parameters

Returns this

Remarks

doBatch

Type Parameters

Parameters

Returns R | Promise<R>

entries

Parameters

Returns IterableIterator<ICellRange.Entry<Scalar>>

Remarks

find

Parameters

Returns Iterator<ICell>

getAddress

Parameters

Returns string

Remarks

getColumnCount

Returns number

getColumnHeaders

Parameters

Returns ICellHeaderRanges

getCoords

Returns readonly Readonly<FixableCoords>[]

getCount

Returns number

getCounts

Parameters

Returns Counts

Remarks

getDefaultShiftAxis

Returns Axis

Remarks

getDependents

`Readonly`isICellRanges