SheetXL - v0.3.20
    Preparing search index...

    Interface ICellRanges

    An ICellRanges is a collection of ICellRanges.

    Useful when working with a discontinuous set of ranges.

    interface ICellRanges {
        isICellRanges: true;
        "[iterator]"(): IterableIterator<Scalar>;
        "[iterator]"(options?: ICellRange.IteratorOptions<any>): Iterator<Scalar>;
        addListener(listener: Listener, options?: ListenerOptions): Remove;
        at(index: number): ICellRange;
        at(index: number): ICellRange;
        autoFit(options?: AutoFitOptions): this;
        calculate(fullRecalc?: boolean): this;
        clear(applyTo?: Content, options?: OperationOptions): this;
        copyFrom(
            source: ICellRange.Address | ICellRange.ISnapshot<any, any>,
            options?: ICellRange.CopyOptions,
        ): Promise<ICellRanges>;
        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(findText: string, options?: FindOptions): Iterator<ICell>;
        getA1(): string;
        getColumnCount(): number;
        getCoords(): readonly Readonly<IRange.FixableCoords>[];
        getCount(): number;
        getCount(): number;
        getCounts(
            types?: Partial<Record<Content, number | boolean>>,
        ): Partial<Record<Content, number>>;
        getDefaultShiftOrientation(): IRange.Orientation;
        getEntireColumns(shiftRows?: boolean, options?: GetRangeOptions): this;
        getEntireRows(shiftColumns?: boolean, options?: GetRangeOptions): this;
        getFixed(options: boolean | GetFixedOptions): this;
        getFlattened(options?: GetFlattenOptions): this;
        getMerges(): IRange.Coords[];
        getRowCount(): number;
        getSnapshot(options?: ICellRange.CopyOptions): ICellRange.ISnapshot;
        getSource<S>(): S;
        getStyleUpdater(): Updater;
        getVisible(options?: GetVisibleOptions): ICellRanges;
        insert(orientation?: IRange.Orientation, options?: OperationOptions): this;
        insertFrom(
            source: ICellRange.Address | ICellRange.ISnapshot<any, any>,
            options?: InsertFromOptions,
        ): Promise<ICellRanges>;
        isContentful(types?: Content | Content[]): boolean;
        isEntireColumns(): boolean;
        isEntireColumnsAny(): boolean;
        isEntireRows(): boolean;
        isEntireRowsAny(): boolean;
        isInvalid(): boolean;
        isInvalidAny(): boolean;
        isOverlapping(): boolean;
        isReadOnly(): boolean;
        merge(options?: IRange.Orientations | MergeOptions): this;
        select(options?: ICellRange.SelectOptions): Promise<ICellRanges>;
        toString(): string;
        unmerge(options?: OperationOptions): this;
        updateStyle(style: IStyle.Update, options?: UpdateOptions): this;
    }
    Index

    Properties

    isICellRanges

    Methods

    [iterator] addListener at autoFit calculate clear copyFrom delete doBatch entries find getA1 getColumnCount getCoords getCount getCounts getDefaultShiftOrientation getEntireColumns getEntireRows getFixed getFlattened getMerges getRowCount getSnapshot getSource getStyleUpdater getVisible insert insertFrom isContentful isEntireColumns isEntireColumnsAny isEntireRows isEntireRowsAny isInvalid isInvalidAny isOverlapping isReadOnly merge select toString unmerge updateStyle

    Properties

    isICellRanges: true

    For runtime type checking.

    Methods

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

      Returns IterableIterator<Scalar>

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

      ()

    • Returns an iterator that allows you to iterate over the individual values within the range.

      Parameters

      Returns Iterator<Scalar>

      An iterator that yields Scalar value, each representing a single cell within the range.

    • Returns the range at a specific index.

      Parameters

      • index: number

      Returns ICellRange

    • Returns the range at a specific index.

      Parameters

      • index: number

      Returns ICellRange

    • Re-evaluates and formulas within the range.

      Parameters

      • OptionalfullRecalc: boolean

        If true then all formulas will be recalculated.

      Returns this

    • 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<ICellRanges>

      A promise that resolve to an ICellRange or 'null' when the copy has completed.

      • Will return null if nothing was inserted or the source doesn't have a range.

    • Delete the cells within the range and shifts the remaining cells to fill the gap.

      Parameters

      Returns this

      Current ICellRange.

      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.

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

    • Returns an iterator that allows you to iterate over the individual cells within the ranges, yielding pairs of IteratorContext and a Value.

      Parameters

      Returns IterableIterator<ICellRange.Entry<Scalar>>

      An iterator that yields [ICell.IteratorContext, Value] tuples for each value within the range.

      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.

    • Returns an iterator of ICells that match the results.

      Parameters

      Returns Iterator<ICell>

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

      Returns string

    • 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

    • Returns the total number of contiguous ranges in this collection.

      Returns number

    • Returns the total number of contiguous ranges in this collection.

      Returns number

    • Returns a record of multiple counts for the given types.

      Parameters

      • Optionaltypes: Partial<Record<Content, number | boolean>>

        The type of content to count. If not specified it will return the context for all content types`

      Returns Partial<Record<Content, number>>

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

      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.

    • 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: GetRangeOptions

        Additional options for getting the range.

      Returns this

      ICellRange at the repositioned range.

    • 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: GetRangeOptions

        Additional options for getting the range.

      Returns this

      ICellRange at the repositioned range.

    • Returns a set of ranges with overlaps removed and attempts to merge adjacent ranges into larger ranges.

      Parameters

      Returns this

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

      isOverlapping

    • Return an array of coords for all merges.

      Returns IRange.Coords[]

      A array of 'IRange.Coords` that contain merges.

    • 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

    • Returns the Sheet.

      Type Parameters

      • S

        The callback return type.

      Returns S

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

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

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

      • 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 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

      Returns this

      Current ICellRange.

    • Returns true if there is any content within the range.

      Parameters

      Returns boolean

      'boolean' indicating if there is content.

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

    • Returns true if all of the the ranges have selected all of the columns.

      Returns boolean

      This is different from isEntireColumnsAny in that it will return true if 'ALL' of the ranges have isEntireColumns true.

    • Returns true if any of the ranges have selected all of the columns.

      Returns boolean

      This is different from isEntireColumns in that it will return true if 'ANY' of the ranges have isEntireColumns true.

    • Returns true if all of the the ranges have selected all of the rows.

      Returns boolean

      This is different from isEntireRowsAny in that it will return true if 'ALL' of the ranges have isEntireRows true.

    • Returns true if any of the ranges have selected all of the rows.

      Returns boolean

      This is different from isEntireRows in that it it will return true if 'ANY' of the ranges have isEntireRows true.

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

      Returns boolean

    • Returns true if any of the ranges are invalid.

      Returns boolean

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

      Returns boolean

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

    • Indicates if the range is readonly only.

      Returns boolean

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

    • Returns the address as a string.

      Returns string

    Settings

    Member Visibility

    On This Page

    Properties
    Methods