Interface IReferenceRange<T>

A range that belongs to a container; usually a sheet.

interface IReferenceRange<T extends Scalar = Scalar> {
    get isIRange(): true;
    get isIReferenceRange(): true;
    get size(): number;
    "[iterator]"(): IterableIterator<Scalar>;
    broadcast<TS extends Scalar = T>(
        other: IRange<Scalar> | TS,
        callbackFn: (
            a: TS,
            b: TS,
            coords: IRange.CellCoords,
            range: IRange<T>,
        ) => TS,
        options?: BroadcastOptions,
    ): this;
    empty(): this;
    entries<TS extends Scalar = T>(
        options?: IteratorOptions,
    ): IterableIterator<IRange.Entry<TS>>;
    every<TS extends Scalar = T>(
        callbackFn: (
            value: TS,
            coords: IRange.CellCoords,
            range: IRange<T>,
        ) => boolean,
        options?: IteratorOptions,
    ): boolean;
    fill(value: Scalar, coords?: Partial<IRange.Coords>): this;
    fillEmpty(value: Scalar, minWidth?: number, minHeight?: number): this;
    filter<TS extends Scalar = T>(
        callbackFn: (
            value: TS,
            coords: IRange.CellCoords,
            range: IRange<T>,
        ) => boolean,
        options?: IteratorOptions,
    ): this;
    flatten(options?: IteratorOptions): Scalar[];
    forEach<TS extends Scalar = T, B = any>(
        callbackFn: (
            value: TS,
            coords: IRange.CellCoords,
            range: IRange<T>,
        ) => void | { break: B },
        options?: IteratorOptions,
    ): void | B;
    getCoords(): IRange.Coords;
    getHeight(): number;
    getScalarType(): ScalarType;
    getValueAt<TS extends Scalar = T>(
        rowIndex: number,
        colIndex: number,
        options?: ValueOptions,
    ): TS;
    getValues<TS extends Scalar = T>(options?: GetValuesOptions): TS[][];
    getWidth(): number;
    intersect<TS extends Scalar = T>(
        other: IRange,
        callbackFn?: (
            a: TS,
            b: TS,
            coords: IRange.CellCoords,
            range: IRange<T>,
        ) => TS,
        options?: IteratorOptions,
    ): this;
    isLiteral(): boolean;
    map<TS extends Scalar = T>(
        callbackFn: (
            value: TS,
            coords: IRange.CellCoords,
            range: IRange<T>,
        ) => TS,
        options?: IteratorOptions,
    ): this;
    reduce<TS extends Scalar = T>(
        callbackFn: (
            accumulator: TS,
            value: TS,
            coords: IRange.CellCoords,
            range: IRange<T>,
        ) => TS,
        initialValue: TS,
        options?: IteratorOptions,
    ): TS;
    replace<TS extends Scalar = T>(
        other: IRange<Scalar> | TS[][],
        coords?: IRange.CellCoords,
    ): this;
    resize(width: number, height: number, fillValue?: Scalar): this;
    slice(coords: Partial<IRange.Coords>): this;
    some<TS extends Scalar = T>(
        callbackFn: (
            value: TS,
            coords: IRange.CellCoords,
            range: IRange<T>,
        ) => boolean,
        options?: IteratorOptions,
    ): boolean;
    startIncrementalUpdates<TS extends Scalar = T>(
        options?: StartUpdateOptions,
    ): IRange.IncrementalUpdater<TS>;
    toString(): string;
    toType(type: ScalarType): this;
    transpose(): this;
    values<TS extends Scalar = T>(
        options?: IteratorOptions,
    ): IterableIterator<TS>;
}

Type Parameters

T extends Scalar = Scalar

Hierarchy (View Summary)

IRange<T>
- IReferenceRange

Accessors

isIRange

get isIRange(): true
Returns true
Inherited from IRange.isIRange

isIReferenceRange

get isIReferenceRange(): true
For runtime type checking.

Returns true

size

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

Returns number
Inherited from IRange.size

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 IRange.entries or IRange.forEach.

Inherited from IRange.[iterator]

broadcast

broadcast<TS extends Scalar = T>(
    other: IRange<Scalar> | TS,
    callbackFn: (
        a: TS,
        b: TS,
        coords: IRange.CellCoords,
        range: IRange<T>,
    ) => TS,
    options?: BroadcastOptions,
): this
Applies a callback function to elements from this range and another range or a scalar, using NumPy-style broadcasting.

Broadcasting Rules:
- If other is a scalar, it is broadcasted to match the shape of this range.
- If other is a range, both ranges must have the same length.
Type Parameters
- TS extends Scalar = T
Parameters
- other: IRange<Scalar> | TS
  The other range or scalar to broadcast with.
- callbackFn: (a: TS, b: TS, coords: IRange.CellCoords, range: IRange<T>) => TS
  The function to apply to corresponding elements.
- Optionaloptions: BroadcastOptions
  IRange.BroadcastOptions
Returns this
A new range with the broadcasted results.

Throws
If the ranges have different length when broadcasting two ranges.

Inherited from IRange.broadcast

empty

empty(): this
Returns a range of 0x0.

Returns this
Inherited from IRange.empty

entries

entries<TS extends Scalar = T>(
options?: IteratorOptions,
): IterableIterator<IRange.Entry<TS>>
Returns an iterator that allows you to iterate over the individual entries within the range, yielding pairs of IRange.CellCoords and Scalar.
Type Parameters
- TS extends Scalar = T
Parameters
- Optionaloptions: IteratorOptions
  IRange.IteratorOptions
Returns IterableIterator<IRange.Entry<TS>>
An iterator that yields a IRange.Entry for each value within the range.

Inherited from IRange.entries

every

every<TS extends Scalar = T>(
    callbackFn: (
        value: TS,
        coords: IRange.CellCoords,
        range: IRange<T>,
    ) => boolean,
    options?: IteratorOptions,
): boolean
Tests whether all elements in the range pass the test implemented by the provided function.
Type Parameters
- TS extends Scalar = T
Parameters
- callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => boolean
  The function to test each element.
- Optionaloptions: IteratorOptions
  IRange.IteratorOptions
Returns boolean
true if all elements pass the test, otherwise false.

Inherited from IRange.every

fill

fill(value: Scalar, coords?: Partial<IRange.Coords>): this
Fill the entire range with a single value.
Parameters
- value: Scalar
  The value to fill.
- Optionalcoords: Partial<IRange.Coords>
  If provided will fill from the coordinates to this area.
Returns this
Inherited from IRange.fill

fillEmpty

fillEmpty(value: Scalar, minWidth?: number, minHeight?: number): this
Returns a new range with all values set to a specific value.
Parameters
- value: Scalar
  The value to fill
- OptionalminWidth: number
  A fixed width for the range. DefaultValue original width.
- OptionalminHeight: number
  A fixed height for the range. DefaultValue original height.
Returns this
Inherited from IRange.fillEmpty

filter

filter<TS extends Scalar = T>(
    callbackFn: (
        value: TS,
        coords: IRange.CellCoords,
        range: IRange<T>,
    ) => boolean,
    options?: IteratorOptions,
): this
Creates a new range with elements that pass the test implemented by the provided function.
Type Parameters
- TS extends Scalar = T
Parameters
- callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => boolean
  The function to test each element.
- Optionaloptions: IteratorOptions
  IRange.IteratorOptions
Returns this
A new range containing only the elements that pass the test.

Inherited from IRange.filter

flatten

flatten(options?: IteratorOptions): Scalar[]
Returns the values as an array of values.
Parameters
- Optionaloptions: IteratorOptions
  IRange.IteratorOptions
Returns Scalar[]
Inherited from IRange.flatten

forEach

forEach<TS extends Scalar = T, B = any>(
    callbackFn: (
        value: TS,
        coords: IRange.CellCoords,
        range: IRange<T>,
    ) => void | { break: B },
    options?: 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
- TS extends Scalar = T
- B = any
  The callback return type.
Parameters
- callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => void | { break: B }
  A function that will be called for each non-empty cell in the range. The callback receives:
  
  value: The Scalar at the current cell.
  
  coords: A IRange.CellCoords.
  
  The callback can return { break: T } to stop the iteration early.
- Optionaloptions: IteratorOptions
  IRange.IteratorOptions
Returns void | B
The value returned by the callback function if it explicitly returned to stop the iteration early; otherwise, void.

Inherited from IRange.forEach

getCoords

getCoords(): IRange.Coords
Adds coordinates to a range reference.

Returns IRange.Coords

getHeight

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

Returns number
Inherited from IRange.getHeight

getScalarType

getScalarType(): ScalarType
Indicates if the range has a type.

Returns ScalarType
Inherited from IRange.getScalarType

getValueAt

getValueAt<TS extends Scalar = T>(
    rowIndex: number,
    colIndex: number,
    options?: ValueOptions,
): TS
Returns a scalar value at a specific row and column index.
Type Parameters
- TS extends Scalar = T
Parameters
- rowIndex: number
  The row index of the value to retrieve.
- colIndex: number
  The column index of the value to retrieve.
- Optionaloptions: ValueOptions
  IRange.GetValuesOptions
  
  Returns a value at a specific row and column index.
Returns TS
Inherited from IRange.getValueAt

getValues

getValues<TS extends Scalar = T>(options?: GetValuesOptions): TS[][]
Returns the values as a materialized 2D array.
Type Parameters
- TS extends Scalar = T
Parameters
- Optionaloptions: GetValuesOptions
  IRange.GetValuesOptions
Returns TS[][]
Remarks
This is useful if a libraries or functions require a 2D array but can be very expensive for large ranges.

Inherited from IRange.getValues

getWidth

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

Returns number
Inherited from IRange.getWidth

intersect

intersect<TS extends Scalar = T>(
    other: IRange,
    callbackFn?: (
        a: TS,
        b: TS,
        coords: IRange.CellCoords,
        range: IRange<T>,
    ) => TS,
    options?: IteratorOptions,
): this
Intersects two ranges and applies a callback function to elements.
Type Parameters
- TS extends Scalar = T
Parameters
- other: IRange
  The other range.
- OptionalcallbackFn: (a: TS, b: TS, coords: IRange.CellCoords, range: IRange<T>) => TS
- Optionaloptions: IteratorOptions
Returns this
A new range with the intersected results or null if the ranges do not intersect.

Inherited from IRange.intersect

isLiteral

isLiteral(): boolean
Returns true if the range is a literal range from a parameter.

Returns boolean
Inherited from IRange.isLiteral

map

map<TS extends Scalar = T>(
    callbackFn: (
        value: TS,
        coords: IRange.CellCoords,
        range: IRange<T>,
    ) => TS,
    options?: IteratorOptions,
): this
Applies a transformation function to each value, returning a new IRange.
Type Parameters
- TS extends Scalar = T
Parameters
- callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => TS
  A function applied to each non-empty cell
- Optionaloptions: IteratorOptions
  IRange.IteratorOptions
Returns this
Inherited from IRange.map

reduce

reduce<TS extends Scalar = T>(
    callbackFn: (
        accumulator: TS,
        value: TS,
        coords: IRange.CellCoords,
        range: IRange<T>,
    ) => TS,
    initialValue: TS,
    options?: IteratorOptions,
): TS
Applies a function against an accumulator and each element of the range (from left to right) to reduce it to a single value.
Type Parameters
- TS extends Scalar = T
Parameters
- callbackFn: (accumulator: TS, value: TS, coords: IRange.CellCoords, range: IRange<T>) => TS
  The function to execute on each element.
- initialValue: TS
  The initial value of the accumulator.
- Optionaloptions: IteratorOptions
  IRange.IteratorOptions
Returns TS
The reduced value.

Inherited from IRange.reduce

replace

replace<TS extends Scalar = T>(
other: IRange<Scalar> | TS[][],
coords?: IRange.CellCoords,
): this
Replaces values in the range with values from another range.
Type Parameters
- TS extends Scalar = T
Parameters
- other: IRange<Scalar> | TS[][]
  The other range or a 2d array.
- Optionalcoords: IRange.CellCoords
  The starting coordinates for the replacement. Default Value {0 ,0}
Returns this
Inherited from IRange.replace

resize

resize(width: number, height: number, fillValue?: Scalar): this
Returns a new range either trimmed or expanded to fix the new width/height.
Parameters
- width: number
- height: number
- OptionalfillValue: Scalar
Returns this
Inherited from IRange.resize

slice

slice(coords: Partial<IRange.Coords>): this
Returns a sliced subrange of the current range.
Parameters
- coords: Partial<IRange.Coords>
  A partial range definition ({ rowStart, rowEnd, colStart, colEnd }).
Returns this
A new IRange representing the sliced section.

Remarks
If any coordinate is omitted, it defaults to the full extent of the range.

Inherited from IRange.slice

some

some<TS extends Scalar = T>(
    callbackFn: (
        value: TS,
        coords: IRange.CellCoords,
        range: IRange<T>,
    ) => boolean,
    options?: IteratorOptions,
): boolean
Tests whether at least one element in the range passes the test implemented by the provided function.
Type Parameters
- TS extends Scalar = T
Parameters
- callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => boolean
  The function to test each element.
- Optionaloptions: IteratorOptions
  IRange.IteratorOptions
Returns boolean
true if at least one element passes the test, otherwise false.

Inherited from IRange.some

startIncrementalUpdates

startIncrementalUpdates<TS extends Scalar = T>(
options?: StartUpdateOptions,
): IRange.IncrementalUpdater<TS>
Creates a IncrementalUpdater for efficiently updating sparsely populated cells in a streaming low memory way.
Type Parameters
- TS extends Scalar = T
Parameters
- Optionaloptions: StartUpdateOptions
  IRange.StartUpdateOptions
Returns IRange.IncrementalUpdater<TS>
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()
.pushAt(1, 0, 2)
.pushAt(1, 0, 567)
.pushAt(1, 0, 3)
.pushAt(1, 0, 123)
.pushAt(1, 0, 1)
.apply();
});
```
Inherited from IRange.startIncrementalUpdates

toString

toString(): string
Returns a string representation of the range.

Returns string
Inherited from IRange.toString

toType

toType(type: ScalarType): this
Change the type of default range coercion for the values in the range.
Parameters
- type: ScalarType
  The new scalar type.
Returns this
Inherited from IRange.toType

transpose

transpose(): this
Returns the range transposed.

Returns this
Inherited from IRange.transpose

values

values<TS extends Scalar = T>(options?: IteratorOptions): IterableIterator<TS>
Iterate values.
Type Parameters
- TS extends Scalar = T
Parameters
- Optionaloptions: IteratorOptions
  IRange.IteratorOptions
Returns IterableIterator<TS>
Inherited from IRange.values

Interface IReferenceRange<T>

Type Parameters

Hierarchy (View Summary)

Index

Accessors

Methods

Accessors

isIRange

Returns true

isIReferenceRange

Returns true

size

Returns number

Methods

[iterator]

Returns IterableIterator<Scalar>

Remarks

broadcast

Type Parameters

Parameters

Returns this

Throws

empty

Returns this

entries

Type Parameters

Parameters

Returns IterableIterator<IRange.Entry<TS>>

every

Type Parameters

Parameters

Returns boolean

fill

Parameters

Returns this

fillEmpty

Parameters

Returns this

filter

Type Parameters

Parameters

Returns this

flatten

Parameters

Returns Scalar[]

forEach

Type Parameters

Parameters

Returns void | B

getCoords

Returns IRange.Coords

getHeight

Returns number

getScalarType

Returns ScalarType

getValueAt

Type Parameters

Parameters

Returns TS

getValues

Type Parameters

Parameters

Returns TS[][]

Remarks

getWidth

Returns number

intersect

Type Parameters

Parameters

Returns this

isLiteral

Returns boolean

map

Type Parameters

Parameters

Returns this

reduce

Type Parameters

Parameters

Returns TS