Range
A Range specifies an area in cell coordinate space that is enclosed by the Range’s upper-left point (top,left) and its lower-right point (bottom,right), both inclusive.
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new Range(src): Range;Parameters
Section titled “Parameters”zero-based coordinates of the bounds of a range, and optionally the “lockedness” of any of those bounds. The bottom and right bounds default to top and left, respectively.
$bottom?
Section titled “$bottom?”boolean
$left?
Section titled “$left?”boolean
$right?
Section titled “$right?”boolean
boolean
bottom?
Section titled “bottom?”number
number
right?
Section titled “right?”number
number
unbounded?
Section titled “unbounded?”number
Returns
Section titled “Returns”Range
Properties
Section titled “Properties”$bottom
Section titled “$bottom”$bottom: boolean;$left: boolean;$right
Section titled “$right”$right: boolean;$top: boolean;bottom
Section titled “bottom”bottom: number;left: number;right: number;top: number;unbounded
Section titled “unbounded”unbounded: Unbounded;MAX_COL
Section titled “MAX_COL”static MAX_COL: number;MAX_ROW
Section titled “MAX_ROW”static MAX_ROW: number;Accessors
Section titled “Accessors”height
Section titled “height”Get Signature
Section titled “Get Signature”get height(): number;Returns
Section titled “Returns”number
isCollapsed
Section titled “isCollapsed”Get Signature
Section titled “Get Signature”get isCollapsed(): boolean;Returns true if this is 1x1, a single-cell range.
Returns
Section titled “Returns”boolean
Get Signature
Section titled “Get Signature”get size(): number;Returns
Section titled “Returns”number
Get Signature
Section titled “Get Signature”get width(): number;Returns
Section titled “Returns”number
Methods
Section titled “Methods”collapse()
Section titled “collapse()”collapse(toTopLeft?): Range;Returns a new Range collapsed to a single point at to one of the boundary points of this range.
Parameters
Section titled “Parameters”toTopLeft?
Section titled “toTopLeft?”boolean = true
true collapses the Range to its top/left corner, false to its bottom/right.
Returns
Section titled “Returns”Range
collapseToBottomRight()
Section titled “collapseToBottomRight()”collapseToBottomRight(): Range;Returns a new Range collapsed to a single point at the bottom-right corner of this range. Does not copy lock attributes ($top etc.).
Returns
Section titled “Returns”Range
collapseToColumn()
Section titled “collapseToColumn()”collapseToColumn(c?): Range;Returns a new Range collapsed to the given column of this range (default leftmost column). Does not copy lock attributes ($top etc.). Does not check bounds, so result will be outside this range if c >= width.
Parameters
Section titled “Parameters”number = 0
zero-based index of the column to collapse to.
Returns
Section titled “Returns”Range
collapseToRow()
Section titled “collapseToRow()”collapseToRow(r?): Range;Returns a new Range collapsed to the given row of this range (default top row) Does not copy lock attributes ($top etc.). Does not check bounds, so result will be outside this range if r >= height.
Parameters
Section titled “Parameters”number = 0
zero-based index of the row to collapse to.
Returns
Section titled “Returns”Range
collapseToTopLeft()
Section titled “collapseToTopLeft()”collapseToTopLeft(): Range;Returns a new Range collapsed to a single point at the top-left corner of this range. Does not copy lock attributes ($top etc.).
Returns
Section titled “Returns”Range
contains()
Section titled “contains()”contains(rangeOrCoords): boolean;Checks whether the specified range is fully covered by this range.
Parameters
Section titled “Parameters”rangeOrCoords
Section titled “rangeOrCoords”the reference range with which to compare.
Returns
Section titled “Returns”boolean
equals()
Section titled “equals()”equals(range): boolean;Compares this range to another range to test if their defined rectangles are equal. This only tests the values of top, left, bottom, right; ignoring any locks.
Parameters
Section titled “Parameters”the reference range with which to compare.
SlimRange | null
Returns
Section titled “Returns”boolean
except()
Section titled “except()”except(range): IterableIterator<Range>;Subtract the supplied range from the current one. Yields up to 4 ranges, depending on how the ranges overlap.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”IterableIterator<Range>
extendSide()
Section titled “extendSide()”extendSide(side, position): Range;Parameters
Section titled “Parameters”Side
position
Section titled “position”number
Returns
Section titled “Returns”Range
extendToLength()
Section titled “extendToLength()”extendToLength(newLength): Range;Returns a new Range with the same shorter dimension as this one, but the longer dimension set to newLength.
(This will make the longer dimension the shorter one, if newLength < the shorter dimension. The intended
use case of this is to extend rather than contract, in which case the longer dimension remains longer, so this
will need changing if the opposite use case becomes relevant.)
Does not copy lock attributes ($top etc.).
Parameters
Section titled “Parameters”newLength
Section titled “newLength”number
the length of the longer dimension (width or height) of the new range
Returns
Section titled “Returns”Range
a range like this one but with its longer dimension changed to newLength.
getIntersection()
Section titled “getIntersection()”getIntersection(other): Range | null;Parameters
Section titled “Parameters”Returns
Section titled “Returns”Range | null
intersects()
Section titled “intersects()”intersects(range): boolean;Parameters
Section titled “Parameters”Returns
Section titled “Returns”boolean
iterCoordinates()
Section titled “iterCoordinates()”iterCoordinates(): IterableIterator<{ column: number; row: number;}>;Returns
Section titled “Returns”IterableIterator<{
column: number;
row: number;
}>
moveBy()
Section titled “moveBy()”moveBy(deltaX, deltaY): Range;Parameters
Section titled “Parameters”deltaX
Section titled “deltaX”number
deltaY
Section titled “deltaY”number
Returns
Section titled “Returns”Range
a new range that has been shifted by X and Y.
strictEquals()
Section titled “strictEquals()”strictEquals(range): boolean;Compares this range to another range to test if their defined rectangles are equal. This tests both the rectangles as well as the status of locks on the dimensions.
Parameters
Section titled “Parameters”the reference range with which to compare.
SlimRange & Pick<Range, "$top" | "$bottom" | "$left" | "$right"> | null
Returns
Section titled “Returns”boolean
toBoundingBox()
Section titled “toBoundingBox()”toBoundingBox(): object;Returns
Section titled “Returns”object
maxX: number = right;maxY: number = bottom;minX: number = left;minY: number = top;toString()
Section titled “toString()”toString(abs): string;Parameters
Section titled “Parameters”boolean = false
Returns
Section titled “Returns”string
createColumnRange()
Section titled “createColumnRange()”static createColumnRange(left, right?): Range;Parameters
Section titled “Parameters”number
right?
Section titled “right?”number = left
defaults to left
Returns
Section titled “Returns”Range
createRowRange()
Section titled “createRowRange()”static createRowRange(top, bottom?): Range;Parameters
Section titled “Parameters”number
bottom?
Section titled “bottom?”number = top
defaults to top
Returns
Section titled “Returns”Range
withinBounds()
Section titled “withinBounds()”static withinBounds(col, row): boolean;Parameters
Section titled “Parameters”number
number
Returns
Section titled “Returns”boolean