Range Essential

Represents a region in a buffer in row/column coordinates.

Every public method that takes a range also accepts a range-compatible Array. This means a 2-element array containing Points or point-compatible arrays. So the following are equivalent:

Examples

new Range(new Point(0, 1), new Point(2, 3))
new Range([0, 1], [2, 3])
[[0, 1], [2, 3]] # Range compatible array

Properties

::start

A Point representing the start of the Range.

::end

A Point representing the end of the Range.

Construction

.fromObject(object, copy)

Convert any range-compatible object to a Range.

Argument	Description
`object`	This can be an object that’s already a Range, in which case it’s simply returned, or an array containing two Points or point-compatible arrays.
`copy`	An optional boolean indicating whether to force the copying of objects that are already ranges.

Return values
Returns: A Range based on the given object.

::constructor(pointA, pointB)

Construct a Range object

Argument	Description
`pointA`	Point or Point compatible Array (default: [0,0])
`pointB`	Point or Point compatible Array (default: [0,0])

::copy()

Return values
Returns a new range with the same start and end positions.

::negate()

Return values
Returns a new range with the start and end positions negated.

Serialization and Deserialization

.deserialize(array)

Call this with the result of Range::serialize to construct a new Range.

Argument	Description
`array`	Array of params to pass to the ::constructor

::serialize()

Return values
Returns a plain javascript object representation of the range.

Range Details

::isEmpty()

Is the start position of this range equal to the end position?

Return values
Returns a Boolean.

::isSingleLine()

Return values
Returns a Boolean indicating whether this range starts and ends on the same row.

::getRowCount()

Get the number of rows in this range.

Return values
Returns a Number.

::getRows()

Return values
Returns an array of all rows in the range.

Operations

::freeze()

Freezes the range and its start and end point so it becomes immutable and returns itself.

Return values
Returns an immutable version of this Range

::union(otherRange)

Argument	Description
`otherRange`	A Range or range-compatible Array

Return values
Returns a new range that contains this range and the given range.

::translate(startDelta, endDelta)

Build and return a new range by translating this range’s start and end points by the given delta(s).

Argument	Description
`startDelta`	A Point by which to translate the start of this range.
`endDelta`	optional A Point to by which to translate the end of this range. If omitted, the `startDelta` will be used instead.

Return values
Returns a Range.

::traverse(delta)

Build and return a new range by traversing this range’s start and end points by the given delta.

See Point::traverse for details of how traversal differs from translation.

Argument	Description
`delta`	A Point containing the rows and columns to traverse to derive the new range.

Return values
Returns a Range.

Comparison

::compare(otherRange)

Compare two Ranges

Argument	Description
`otherRange`	A Range or range-compatible Array.

Return values
Returns `-1` if this range starts before the argument or contains it.
Returns `0` if this range is equivalent to the argument.
Returns `1` if this range starts after the argument or is contained by it.

::isEqual(otherRange)

Argument	Description
`otherRange`	A Range or range-compatible Array.

Return values
Returns a Boolean indicating whether this range has the same start and end points as the given Range or range-compatible Array.

::coversSameRows(otherRange)

Argument	Description
`otherRange`	A Range or range-compatible Array.

Return values
Returns a Boolean indicating whether this range starts and ends on the same row as the argument.

::intersectsWith(otherRange, exclusive)

Determines whether this range intersects with the argument.

Argument	Description
`otherRange`	A Range or range-compatible Array
`exclusive`	optional Boolean indicating whether to exclude endpoints when testing for intersection. Defaults to `false`.

Return values
Returns a Boolean.

::containsRange(otherRange, exclusive)

Argument	Description
`otherRange`	A Range or range-compatible Array
`exclusive`	optional Boolean including that the containment should be exclusive of endpoints. Defaults to false.

Return values
Returns a Boolean indicating whether this range contains the given range.

::containsPoint(point, exclusive)

Argument	Description
`point`	A Point or point-compatible Array
`exclusive`	optional Boolean including that the containment should be exclusive of endpoints. Defaults to false.

Return values
Returns a Boolean indicating whether this range contains the given point.

::intersectsRow(row)

Argument	Description
`row`	Row Number

Return values
Returns a Boolean indicating whether this range intersects the given row Number.

::intersectsRowRange(startRow, endRow)

Argument	Description
`startRow`	Number start row
`endRow`	Number end row

Return values
Returns a Boolean indicating whether this range intersects the row range indicated by the given startRow and endRow Numbers.

Conversion

::toString()

Return values
Returns a string representation of the range.