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”
staticMAX_COL:number
MAX_ROW
Section titled “MAX_ROW”
staticMAX_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.
null | SlimRange
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):null|Range
Parameters
Section titled “Parameters”Returns
Section titled “Returns”null | Range
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.
null | SlimRange & Pick<Range, "$top" | "$bottom" | "$left" | "$right">
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()”
staticcreateColumnRange(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()”
staticcreateRowRange(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()”
staticwithinBounds(col,row):boolean
Parameters
Section titled “Parameters”number
number
Returns
Section titled “Returns”boolean