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.