Interface ICellRange

A ICellRange represents a rectangular collection of ICell within an ISheet.

Naming Conventions: Methods usually adhere to the following conventions except when adhering to a idiomatic existing conventions of Typescript (for example size or 'length'):

Methods returning information about the range (e.g., width, count) use a get prefix.
Methods that transform the range's data into a different type use a to prefix (e.g., toArray()).

interface ICellRange {
 isICellRange: true;
 get size(): number;
 "[iterator]"(): IterableIterator<Scalar>;
 addListener(listener: Listener, options?: ListenerOptions): Remove;
 autoFill(destination: ICellRange.Address, options?: AutoFillOptions): this;
 autoFit(options?: AutoFitOptions): this;
 calculate(full?: boolean): this;
 clear(applyTo?: Content, options?: OperationOptions): this;
 copyFrom(
 source: ICellRange.Address | ICellRange.ISnapshot<any, any>,
 options?: ICellRange.CopyOptions,
 ): Promise<ICellRange>;
 delete(orientation?: IRange.Orientation, options?: OperationOptions): this;
 doBatch<R>(
 callback: (commit: ICommit) => R | Promise<R>,
 options?: string | OperationOptions,
 ): R | Promise<R>;
 entries(
 options?: ICellRange.IteratorOptions,
 ): IterableIterator<ICellRange.Entry<Scalar>>;
 find(text: string, options?: FindOptions): Iterator<ICell>;
 forEach(
 callback: ICellRange.ForEachCallback,
 options?: ICellRange.IteratorOptions,
 ): void | B;
 getA1(): string;
 getBounds(): Bounds;
 getCell(): ICell;
 getCells(options?: GetValuesOptions): ICell[][];
 getColumnCount(): number;
 getColumnEnd(): number;
 getColumnHeaders(options?: GetRangeOptions): ICellHeaderRange;
 getColumnStart(): number;
 getCoords(): Readonly<IRange.FixableCoords>;
 getCount(): number;
 getCounts(types?: Content[]): Partial<Record<Content, number>>;
 getDefaultShiftOrientation(): IRange.Orientation;
 getDefaultSortCriteria(
 orientation?: IRange.Orientation,
 cell?: ICell.Address,
 ): DefaultSortCriteria;
 getDifferences(
 address: ICellRange.Address,
 options?: GetRangeOptions,
 ): ICellRanges;
 getEntireColumns(shift?: boolean, options?: GetRangeOptions): this;
 getEntireRows(shift?: boolean, options?: GetRangeOptions): this;
 getExtended(direction: IRange.Direction, cell?: ICell.Address): this;
 getFixed(options?: boolean | GetFixedOptions): this;
 getHeight(): number;
 getIntersect(
 address?: ICellRange.Address,
 options?: GetRangeOptions,
 ): ICellRange;
 getMerges(): IRange.Coords[];
 getOffsetBy(
 rowDelta: number,
 colDelta: number,
 options?: GetRangeOptions,
 ): this;
 getOffsetTo(
 rowStart: number,
 colStart: number,
 options?: GetRangeOptions,
 ): this;
 getResizeBy(
 rowDelta: number,
 colDelta: number,
 options?: GetRangeOptions,
 ): this;
 getResizeTo(
 rowEnd: number,
 colEnd: number,
 options?: GetRangeOptions,
 ): this;
 getRowCount(): number;
 getRowEnd(): number;
 getRowHeaders(options?: GetRangeOptions): ICellHeaderRange;
 getRowStart(): number;
 getSnapshot(options?: ICellRange.CopyOptions): ICellRange.ISnapshot;
 getSource<S>(): S;
 getStyleUpdater(): Updater;
 getSurrounding(options?: GetSurroundingOptions): this;
 getUnion(address?: ICellRange.Address, options?: GetRangeOptions): this;
 getUsedRange(options?: GetRangeOptions): ICellRange;
 getValue(
 options?: GetValuesOptions,
 ): string | number | boolean | FormulaError.Known | IRichData | Date;
 getValues(options?: GetValuesOptions): Scalar[][];
 getVisible(options?: GetVisibleOptions): ICellRanges;
 getWidth(): number;
 insert(orientation?: IRange.Orientation, options?: OperationOptions): this;
 insertFrom(
 source: ICellRange.Address | ICellRange.ISnapshot<any, any>,
 options?: InsertFromOptions,
 ): Promise<ICellRange>;
 isContentful(): boolean;
 isEmpty(): boolean;
 isEntireColumns(): boolean;
 isEntireRange(): boolean;
 isEntireRows(): boolean;
 isInvalid(): boolean;
 isReadOnly(): boolean;
 merge(options?: IRange.Orientations | MergeOptions): this;
 select(options?: ICellRange.SelectOptions): Promise<ICellRange>;
 setComments(comments: Properties, options?: OperationOptions): this;
 setHyperlink(
 hyperlink: IHyperlink.Update,
 options?: OperationOptions,
 ): this;
 setValue(value: ValuesUpdateOrCallback, options?: SetValuesOptions): this;
 setValues(values: ValuesUpdate, options?: SetValuesOptions): this;
 sort(options?: boolean | RangeOptions & OperationOptions): this;
 startIncrementalUpdates(
 options?: StartUpdateOptions,
 ): ICellRange.IncrementalUpdater;
 toString(): string;
 unmerge(options?: OperationOptions): this;
 updateCells(update: ICellRange.Update, options?: UpdateCellsOptions): this;
 updateStyle(style: IStyle.Update, options?: UpdateOptions): this;
}

Index

Properties

isICellRange

Accessors

size

Properties

`Readonly`isICellRange

isICellRange: true

For runtime type checking.

Accessors

size

get size(): number
Returns the size of the range this is the width * height.

Returns number

Methods

[iterator]

"[iterator]"(): IterableIterator<Scalar>
Returns an iterator that allows you to iterate over the individual values within the range.

Returns IterableIterator<Scalar>
Remarks
For more advanced iteration, use ICellRange.entries or ICellRange.forEach.

addListener

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

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

autoFill

autoFill(destination: ICellRange.Address, options?: AutoFillOptions): this
Fill the range to a destination using an array of IAutoFill.Filler.
Parameters
- destination: ICellRange.Address
  The range to autoFill including the current range.
- Optionaloptions: AutoFillOptions
  ICellRange.AutoFillOptions
Returns this
ICellRange at the destination.
Throws
Error If the destination range does not overlap with the range on 3 out of 4 sides.
Remarks
- If the range contains merges then the amount must be a 'fill' dimension must a multiple of the initialRange 'fill' dimension.
- The destination range must be the same size as the original with 1 edge adjusted.

autoFit

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

calculate

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

clear

clear(applyTo?: Content, options?: OperationOptions): this
Clear the range.
Parameters
- OptionalapplyTo: Content
  ICell.Content
- Optionaloptions: OperationOptions
  ITransaction.OperationOptions
Returns this
Current ICellRange.
Default Value
```
ICell.Content.Values
```

copyFrom

copyFrom(
source: ICellRange.Address | ICellRange.ISnapshot<any, any>,
options?: ICellRange.CopyOptions,
): Promise<ICellRange>
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
 Additional options for customizing the paste operation (e.g., transpose, skipBlanks).
Returns Promise<ICellRange>
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.
See
ICellRange.getSnapshot

delete

delete(orientation?: IRange.Orientation, options?: OperationOptions): this
Delete the cells within the range and shifts the remaining cells to fill the gap.
Parameters
- Optionalorientation: IRange.Orientation
  The direction in which to shift the remaining cells. Defaults to the orientation where the range's dimension is smaller (e.g., shifts left if the range is taller than it is wide). See ICellRange.getDefaultShiftOrientation for details on the default behavior.
- Optionaloptions: OperationOptions
  ITransaction.OperationOptions
Returns this
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 | 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 | 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.
Default Value
```
'Range Update'
```

entries

entries(
options?: ICellRange.IteratorOptions,
): IterableIterator<ICellRange.Entry<Scalar>>
Returns an iterator that allows you to iterate over the individual entries within the range, yielding pairs of IteratorContext and a Value.
Parameters
- Optionaloptions: ICellRange.IteratorOptions
 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.

find

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

forEach

forEach(
callback: ICellRange.ForEachCallback,
options?: ICellRange.IteratorOptions,
): void | B
Iterates over the cells within the range, applying the provided callback function to each cell.

This method is a more scalable alternative to getValues or getCells for large or sparse ranges, as it:
1. Skips empty values by default.
2. Avoids creating large arrays.
3. Allows for early termination.
Type Parameters
- B
Parameters
- callback: ICellRange.ForEachCallback
 A function that will be called for each non-empty cell in the range. The callback receives:
 
 value: The Scalar at the current cell.
 
 context: A IteratorContext object providing additional information and utilities for the cell.
 
 The callback can return { break: T } to stop the iteration early.
- Optionaloptions: ICellRange.IteratorOptions
 ICellRange.IteratorOptions for configuring which cells to visit.
Returns void | B
The value returned by the callback function if it explicitly returned to stop the iteration early; otherwise, void.

getA1

getA1(): string
Returns the Coords an A1-style address string (e.g., 'A1' or 'A1:E5').

Returns string

getBounds

getBounds(): Bounds
Returns the absolute bounds for the range.

Returns Bounds

getCell

getCell(): ICell
A convenience method to get the top left ICell.

Returns ICell
See
ICellRange.getCells

getCells

getCells(options?: GetValuesOptions): ICell[][]
Return a 2D array of cells in the shape of the range.
Parameters
- Optionaloptions: GetValuesOptions
  ICellRange.GetValuesOptions
Returns ICell[][]
A 2D array of ICells.
Remarks
- Empty values will be null.
- ICellRange.GetValuesOptions.asJSDate is ignored; use ICell.asDate() when working with ICell.

getColumnCount

getColumnCount(): number
Returns the number of columns of the range.

Returns number

getColumnEnd

getColumnEnd(): number
Returns the right of the range.

Returns number

getColumnHeaders

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

getColumnStart

getColumnStart(): number
Returns the column start.

Returns number

getCoords

getCoords(): Readonly<IRange.FixableCoords>
The IRange.Coords.

Returns Readonly<IRange.FixableCoords>

getCount

getCount(): number
Returns a count for of values.

Returns number

getCounts

getCounts(types?: Content[]): Partial<Record<Content, number>>
Returns a record of multiple counts for the given types.
Parameters
- Optionaltypes: Content[]
 The type of content to count. If not specified it will return the context for all content types`
Returns Partial<Record<Content, number>>

getDefaultShiftOrientation

getDefaultShiftOrientation(): IRange.Orientation
Returns the default shift IRange.Orientation for insert and delete if no orientation is provided.

Returns IRange.Orientation
Default IRange.Orientation 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.Orientation.Row will be used.

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

getDefaultSortCriteria

getDefaultSortCriteria(
orientation?: IRange.Orientation,
cell?: ICell.Address,
): DefaultSortCriteria
Returns a default sort that would be used if no overrides where provided.
Parameters
- Optionalorientation: IRange.Orientation
  The orientation to sort. Default Value IRange.Orientation.Row.
- Optionalcell: ICell.Address
  A cell location that can be used to determine the sort column.
Returns DefaultSortCriteria
Default ISort.DefaultSortCriteria or null if there is not valid sort criteria.

Remarks
Useful for displaying options to the ui. The default behavior will look for headers and merges.

getDifferences

getDifferences(
address: ICellRange.Address,
options?: GetRangeOptions,
): ICellRanges
Returns a set of non-overlapping ranges the represents the difference between the current range and the specified range.
Parameters
- address: ICellRange.Address
  The address of the range to subtract from the current range.
- Optionaloptions: GetRangeOptions
Returns ICellRanges
ICellRanges containing the resulting non-overlapping ranges, or null if:
- There is no intersection between the current range and the specified address.
- The specified address is the same as or encompasses the current range.
Remarks
- The method will always return between 0 and 4 ranges.
- If there's no intersection, it returns an ICellRanges containing only the current range.

getEntireColumns

getEntireColumns(shift?: boolean, options?: 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
- Optionalshift: boolean
  If true this will also shift the columns by the width of the range. default false.
- Optionaloptions: GetRangeOptions
  Additional options for getting the range.
Returns this
ICellRange at the repositioned range.

getEntireRows

getEntireRows(shift?: boolean, options?: 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
- Optionalshift: boolean
  If true this will also shift the rows by the height of the range. default false.
- Optionaloptions: GetRangeOptions
  Additional options for getting the range.
Returns this
ICellRange at the repositioned range.

getExtended

getExtended(direction: IRange.Direction, cell?: ICell.Address): this
Returns a range that includes the current range up to a content edge boundary.
Parameters
- direction: IRange.Direction
  The direction.
- Optionalcell: ICell.Address
  The cell to use as a starting point. If not provide the cell closest to the edge will be used.
Returns this
ICellRange extended in the given direction.

getFixed

getFixed(options?: boolean | GetFixedOptions): this
Returns a range with coordinates adjusted to be fixed (absolute) or flexible (relative).
Parameters
- Optionaloptions: boolean | GetFixedOptions
  Either a ICellRange.GetFixedOptions object to specify individual coordinate settings, or a boolean to adjust all coordinates at once. If a boolean is provided: - true sets all coordinates to absolute. - false sets all coordinates to relative.
Returns this
ICellRange with updated coordinate references types.

Remarks
If no options are provided, this method toggles the fixed flags for the range's coordinates based on their current settings. Calling this repeatedly will cycle between relative and absolute references. For example: A1 → $A$1 → A$1 → $A1 → A1

getHeight

getHeight(): number
Returns the height of the range.

Returns number

getIntersect

getIntersect(
address?: ICellRange.Address,
options?: GetRangeOptions,
): ICellRange
Returns the intersection of the current range and the specified range.
Parameters
- Optionaladdress: ICellRange.Address
  The address of the other range to intersect with..
- Optionaloptions: GetRangeOptions
Returns ICellRange
ICellRange at the intersection of the two ranges, or null if there's no overlap.

getMerges

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

getOffsetBy

getOffsetBy(rowDelta: number, colDelta: number, options?: GetRangeOptions): this
Returns a range with the top-left corner moved by the specified row and column offsets.
Parameters
- rowDelta: number
  The number of rows to move the top-left corner up (negative) or down (positive).
- colDelta: number
  The number of columns to move the top-left corner left (negative) or right (positive).
- Optionaloptions: GetRangeOptions
Returns this
ICellRange at the repositioned range.

getOffsetTo

getOffsetTo(rowStart: number, colStart: number, options?: GetRangeOptions): this
Returns a range repositioned to the specified starting row and column indices.
Parameters
- rowStart: number
  The new starting row index (inclusive).
- colStart: number
  The new starting column index (inclusive).
- Optionaloptions: GetRangeOptions
Returns this
ICellRange at the repositioned range.

getResizeBy

getResizeBy(rowDelta: number, colDelta: number, options?: GetRangeOptions): this
Returns a range with the bottom-right corner moved by the specified row and column offsets.
Parameters
- rowDelta: number
  The number of rows to move the bottom-right corner up (negative) or down (positive).
- colDelta: number
  The number of columns to move the bottom-right corner left (negative) or right (positive).
- Optionaloptions: GetRangeOptions
Returns this
ICellRange with the resized range.

getResizeTo

getResizeTo(rowEnd: number, colEnd: number, options?: GetRangeOptions): this
Resizes the current range to the specified ending row and column indices.
Parameters
- rowEnd: number
  The new ending row index (inclusive).
- colEnd: number
  The new ending column index (inclusive).
- Optionaloptions: GetRangeOptions
Returns this
ICellRange with the resized range.

getRowCount

getRowCount(): number
Returns the number of rows of the range.

Returns number

getRowEnd

getRowEnd(): number
Returns the bottom of the range.

Returns number

getRowHeaders

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

getRowStart

getRowStart(): number
Returns the top of the range.

Returns number

getSnapshot

getSnapshot(options?: ICellRange.CopyOptions): ICellRange.ISnapshot
Returns a snapshot of the current range's data and formatting suitable for copying or archiving.
Parameters
- Optionaloptions: ICellRange.CopyOptions
  Default options to apply during the copy operation.
Returns ICellRange.ISnapshot
A ISnapshot object representing the range.
Remarks
- Option Merging: If options are also provided during the copy operation, the two will be merged with the copy options taking precedence.
- getSnapshot can be called multiple times allowing for multiple snapshots.

getSource

getSource<S>(): S
Returns the Sheet.
Type Parameters
- S
 The callback return type.
Returns S

getStyleUpdater

getStyleUpdater(): Updater
Retrieves an IStyle.Updater object for updating the styles of the range.

Unlike ICell.getStyle, which provides a read-only view of a cell's style, this method returns an updater object that allows modifications to the styles of all cells in the range.

Returns Updater
A style updater for the range.
Example
```
const updater = range.getStyleUpdater();
updater.setColor("blue").setFont("Arial");
```
Remarks
- Deterministic Behavior: All updates via the IStyle.Updater are applied to the entire range, overriding any mixed styles with the specified values.
- Read-Only Alternatives: To inspect styles across all cells in the range without modifying them, use ICellRange.entries or ICellRange.forEach to iterate over immutable ICells.
- Immutable Philosophy: This API aligns with the principle that ICell objects are immutable, while ICellRange is the interface for mutable operations.

getSurrounding

getSurrounding(options?: GetSurroundingOptions): this
Returns a range with surrounding data or the entire range if there is no data nearby.
Parameters
- Optionaloptions: GetSurroundingOptions
Returns this
ICellRange containing either nearby content or the entire range.

getUnion

getUnion(address?: ICellRange.Address, options?: GetRangeOptions): this
Returns the union of the current range with the specified range.
Parameters
- Optionaladdress: ICellRange.Address
  The address of the other range to intersect with.
- Optionaloptions: GetRangeOptions
Returns this
ICellRange at the union of the two ranges.

getUsedRange

getUsedRange(options?: GetRangeOptions): ICellRange
Returns the smallest range within the range that contains any used cells.

This method returns the range of cells that have been "used," which includes cells with data, as well as certain types of formatting or styling. It focuses on cells that have been interacted with in some form, whether through data entry or other modifications. Merged cells and overflow values may not always be included in this range.
Parameters
- Optionaloptions: GetRangeOptions
Returns ICellRange
ICellRange that contains the smallest range with used cells, or null if the range is empty.

getValue

getValue(
options?: GetValuesOptions,
): string | number | boolean | FormulaError.Known | IRichData | Date
Returns the value for the top left Scalar.
Parameters
- Optionaloptions: GetValuesOptions
Returns string | number | boolean | FormulaError.Known | IRichData | Date
Remarks
The excludeHidden option is ignored.

See
ICellRange.getValues

getValues

getValues(options?: GetValuesOptions): Scalar[][]
Returns a 2D array of values in the shape of the range.
Parameters
- Optionaloptions: GetValuesOptions
  asJSDate Return dates as Javascript dates instead of OADates but is slower due to need to determine if the Cell is a date or a number. See ICell.IteratorContext.toJSDate. defaultValue false.
  
  maxSize Limit the size of the results. defaultValue 10000.
Returns Scalar[][]
A 2D array of values.
Remarks
- Empty values will be null.
- This is faster than getCells when only the values are needed.
- Setting ICellRange.GetValuesOptions.asJSDate to true will add make slower.

getVisible

getVisible(options?: GetVisibleOptions): ICellRanges
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
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.

getWidth

getWidth(): number
Returns the width of the range.

Returns number

insert

insert(orientation?: IRange.Orientation, options?: OperationOptions): this
Insert a new, empty range within the sheet and shifts existing cells to accommodate it.

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.
Parameters
- Optionalorientation: IRange.Orientation
  The direction in which to shift existing cells. Defaults to the orientation where the range's dimension is smaller (e.g., shifts down if the range is wider than it is tall). See ICellRange.getDefaultShiftOrientation for details on the default behavior.
- Optionaloptions: OperationOptions
  ITransaction.OperationOptions
Returns this
Current ICellRange.

Throws
Error If the insertion would cause data to exceed the maximum sheet size.

insertFrom

insertFrom(
source: ICellRange.Address | ICellRange.ISnapshot<any, any>,
options?: InsertFromOptions,
): Promise<ICellRange>
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
 ICellRange.InsertFromOptions
Returns Promise<ICellRange>
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(): boolean
Returns true if there is any content within the range.

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.

isEmpty

isEmpty(): boolean
Checks if the ranges is empty, meaning it has no values or formatting.

Returns boolean
Remarks
Convenience getUsedRange() !== null or getCount() === 0.

See
ICellRange.getUsedRange

isEntireColumns

isEntireColumns(): boolean
Returns true if the range represents the entire columns.

Returns boolean

isEntireRange

isEntireRange(): boolean
Returns true if the range represents both entire rows and entire columns.

Returns boolean

isEntireRows

isEntireRows(): boolean
Returns true if the range represents the entire rows.

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

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.)

merge

merge(options?: IRange.Orientations | MergeOptions): this
Merges all cells within the selection ranges.
Parameters
- Optionaloptions: IRange.Orientations | MergeOptions
  ICellRange.MergeOptions
Returns this
Current ICellRange.

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

select

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

setComments

setComments(comments: Properties, options?: OperationOptions): this
Update the comments for the range.
Parameters
- comments: Properties
  Comment properties
- Optionaloptions: OperationOptions
  ITransaction.OperationOptions
Returns this
Current ICellRange.

Remarks
NOT FINISHED

setHyperlink

setHyperlink(hyperlink: IHyperlink.Update, options?: OperationOptions): this
Set the hyperlink for a range of values.
Parameters
- hyperlink: IHyperlink.Update
  IHyperlink.Update
- Optionaloptions: OperationOptions
  ITransaction.OperationOptions
Returns this
Current ICellRange.

Remarks
To clear hyperlinks either set to null or call clear(ICell.Content.Hyperlinks).

setValue

setValue(value: ValuesUpdateOrCallback, options?: SetValuesOptions): this
Set a single value to the entire range.
Parameters
- value: ValuesUpdateOrCallback
- Optionaloptions: SetValuesOptions
Returns this
See
ICellRange.setValues

setValues

setValues(values: ValuesUpdate, options?: SetValuesOptions): this
Set the value(s) of one or more cells within a range.
Parameters
- values: ValuesUpdate
  The value to be set or a callback that will generate a value.
- Optionaloptions: SetValuesOptions
  ICellRange.SetValuesOptions
Returns this
The current ICellRange.
Remarks
- null values will clear the corresponding cells.
- undefined values will be ignored, leaving the existing cell values unchanged.
- If an array is passed the values will be in row-major order and will repeat if the range is larger than the array
- If a single value is passed in it will repeat the entire range.

sort

sort(options?: boolean | RangeOptions & OperationOptions): this
Sort the given range.
Parameters
- Optionaloptions: boolean | RangeOptions & OperationOptions
  boolean | ISort.RangeOptions
Returns this
Current ICellRange.

Remarks
The sorting of various data types has a default priority of of boolean > string > number and dates are treated as numbers. If true then the sort is reversed (descending).

startIncrementalUpdates

startIncrementalUpdates(
options?: StartUpdateOptions,
): ICellRange.IncrementalUpdater
Creates a IncrementalUpdater for efficiently updating sparsely populated cells in a streaming low memory way.

For contiguous or mostly contiguous updates, the ICellRange.updateCells method is simpler and will use ICellRange.IncrementalUpdater internally.
Parameters
- Optionaloptions: StartUpdateOptions
  ICellRange.StartUpdateOptions
Returns ICellRange.IncrementalUpdater
Remarks
- Ordering: By default updates must be added in either row-major or column-major order, as specified by the orientation parameter, with major/minor coordinates increasing monotonically. Unless allowUnorderedWrites is set to `true out of order updates will result in an error.
- Performance: Setting orientation to IRange.Orientation.Column is generally faster as it aligns with the internal data representation.
- Performance: Setting allowUnorderedWrites adds a nominal performance overhead for all updates and will do a full apply when an out of order update is detected. The default IRange.Orientation.Row is provided for compatibility with common spreadsheet APIs.
- Validation: Data validation (e.g., for protected cells or boundaries) is performed when the apply method is called.
- Transactions:
  
  Adding values to the IncrementalUpdater only builds a temporary representation of the updates. No actual changes are made to the sheet until apply is called.
  
  This allows for safe batching of updates within a single transaction using doBatch.
Example
```
const updates = range.startIncrementalUpdates()
 .push('A1', 2)
 .push('A2', 567)
 .push('A3', 3)
 .push('A4', 123)
 .push('A5', 1)
 .apply();
});
```

toString

toString(): string
Returns the address as a string.

Returns string

unmerge

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

updateCells

updateCells(update: ICellRange.Update, options?: UpdateCellsOptions): this
Provides a convenient method for setting values with a range of calls.
Parameters
- update: ICellRange.Update
  ICellRange.Update
- Optionaloptions: UpdateCellsOptions
  ICellRange.UpdateCellsOptions
Returns this
The current ICellRange.
Remarks
- Performance This is will always be significantly slow than setting attributes use the related range APIs.
- For setting non contiguous values see ICellRange.startIncrementalUpdates
See
- updateStyle
- setHyperlink

updateStyle

updateStyle(style: IStyle.Update, options?: UpdateOptions): this
Update the style for the range(s).
Parameters
- style: IStyle.Update
  IStyle.Update
- Optionaloptions: UpdateOptions
  IStyle.UpdateOptions
Returns this
Current ICellRange.

Interface ICellRange

Index

Properties

Accessors

Methods

Properties

ReadonlyisICellRange

Accessors

size

Returns number

Methods

[iterator]

Returns IterableIterator<Scalar>

Remarks

addListener

Parameters

Returns Remove

Remarks

autoFill

Parameters

Returns this

Throws

Remarks

autoFit

Parameters

Returns this

calculate

Parameters

Returns this

clear

Parameters

Returns this

Default Value

copyFrom

Parameters

Returns Promise<ICellRange>

Remarks

See

delete

Parameters

Returns this

Remarks

doBatch

Type Parameters

Parameters

Returns R | Promise<R>

Default Value

entries

Parameters

Returns IterableIterator<ICellRange.Entry<Scalar>>

find

Parameters

Returns Iterator<ICell>

forEach

Type Parameters

Parameters

Returns void | B

getA1

Returns string

getBounds

Returns Bounds

getCell

Returns ICell

See

getCells

Parameters

Returns ICell[][]

Remarks

getColumnCount

Returns number

getColumnEnd

Returns number

getColumnHeaders

Parameters

Returns ICellHeaderRange

getColumnStart

Returns number

getCoords

Returns Readonly<IRange.FixableCoords>

getCount

`Readonly`isICellRange