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$1;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$1
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$1;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 collapses the Range to its top/left corner, false to its bottom/right.
Returns
Section titled “Returns”Range$1
collapseToBottomRight()
Section titled “collapseToBottomRight()”collapseToBottomRight(): Range$1;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$1
collapseToColumn()
Section titled “collapseToColumn()”collapseToColumn(c?): Range$1;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
zero-based index of the column to collapse to.
Returns
Section titled “Returns”Range$1
collapseToRow()
Section titled “collapseToRow()”collapseToRow(r?): Range$1;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
zero-based index of the row to collapse to.
Returns
Section titled “Returns”Range$1
collapseToTopLeft()
Section titled “collapseToTopLeft()”collapseToTopLeft(): Range$1;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$1
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”SlimRange | null
the reference range with which to compare.
Returns
Section titled “Returns”boolean
except()
Section titled “except()”except(range): IterableIterator<Range$1>;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$1>
extendSide()
Section titled “extendSide()”extendSide(side, position): Range$1;Parameters
Section titled “Parameters”Side
position
Section titled “position”number
Returns
Section titled “Returns”Range$1
extendToLength()
Section titled “extendToLength()”extendToLength(newLength): Range$1;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$1
a range like this one but with its longer dimension changed to newLength.
getIntersection()
Section titled “getIntersection()”getIntersection(other): Range$1 | null;Parameters
Section titled “Parameters”Returns
Section titled “Returns”Range$1 | null
hasUnanchoredBound()
Section titled “hasUnanchoredBound()”hasUnanchoredBound(kind): boolean;True if any bound the address writes out is unanchored, i.e. written without a $.
Parameters
Section titled “Parameters”AddressKind
which bounds the address writes out (see AddressKind)
Returns
Section titled “Returns”boolean
true if a written bound has no $
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$1;Parameters
Section titled “Parameters”deltaX
Section titled “deltaX”number
deltaY
Section titled “deltaY”number
Returns
Section titled “Returns”Range$1
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”| SlimRange & Pick<Range$1, "$top" | "$left" | "$bottom" | "$right">
| null
the reference range with which to compare.
Returns
Section titled “Returns”boolean
toBoundingBox()
Section titled “toBoundingBox()”toBoundingBox(): object;Returns
Section titled “Returns”object
maxX: number;maxY: number;minX: number;minY: number;toString()
Section titled “toString()”toString(abs?): string;Parameters
Section titled “Parameters”boolean
Returns
Section titled “Returns”string
translateFromOrigin()
Section titled “translateFromOrigin()”translateFromOrigin( originRow, originCol, kind): Range$1;Return a copy with every unanchored bound shifted by the given zero-based origin, which is how
a defined name’s coordinates read: an unanchored one is an offset from A1, resolved against
the cell that references the name. A bound shifted past the last row or column wraps around to
the first, so that up-and-left from A1 is the bottom-right cell.
Parameters
Section titled “Parameters”originRow
Section titled “originRow”number
zero-based row of the cell the coordinates are resolved against
originCol
Section titled “originCol”number
zero-based column of that cell
AddressKind
which bounds the address writes out (see AddressKind)
Returns
Section titled “Returns”Range$1
the shifted copy, its anchoring flags as on this range
createColumnRange()
Section titled “createColumnRange()”static createColumnRange(left, right?): Range$1;Parameters
Section titled “Parameters”number
right?
Section titled “right?”number
defaults to left
Returns
Section titled “Returns”Range$1
createRowRange()
Section titled “createRowRange()”static createRowRange(top, bottom?): Range$1;Parameters
Section titled “Parameters”number
bottom?
Section titled “bottom?”number
defaults to top
Returns
Section titled “Returns”Range$1
withinBounds()
Section titled “withinBounds()”static withinBounds(col, row): boolean;Parameters
Section titled “Parameters”number
number
Returns
Section titled “Returns”boolean