A Range object describes a contiguous block of elements in some larger context. For example, a range of characters is a block of characters that are all adjacent to one another in the same document. However, such a range only describes the location of these character, it does not contain the actual characters.
A range can describe any kind of element, such as indexes in an array or rows in a table. The type of element being described by a range is irrelevant, the only properties a range maintains are the indexes (integers) of the elements in the larger context. This means that you can use the exact same range object to access different types of elements if you like.
Range Type Commands
Range.new [location], [length] v1.1
Returns a new range with the given location and length, which respectively are the index of the first element in the range and the number of elements in the range. If either is not provided the property will be set to zero.
Range.newWithText textObject v3.0
Returns a new range for all characters in the given Text object. In other words, returns a new range whose location is zero and whose length matches the text length.
Range.newWithLocations location1, location2 v1.1
Returns a new range that contains both of the locations (indexes) given and all the locations in between, if any. Thus the returned range will always have a length of one or more. The given locations need not be in any order.
Range.newWithLocationAndBound location, bound v1.1
Returns a new range with the given location and bound. The bound is the index of the first element not to be included in the range. The bound must not be less than the given location, or an error will be displayed.
Range Object Properties
.location v1.1
The index of the first element contained in the range. This index is zero-based, eg: the location of the first character in a document is zero. If a range is zero in length (and thus does not contain any elements) then this property is the index of the first element that would be included in the range if its length were extended.
.length v1.1
The number of elements contained in the range. This can be zero if no elements are in the range, eg: a zero-length selection. Changing the length also changes the bound and lastLocation.
.bound v1.1
The index of the first element after the range (eg: not included in the range). If an attempt is made to set the bound to a number less than the current location, then an error is displayed. Changing the bound also changes the length and lastLocation.
.lastLocation v3.1
The index of the last location contained in the range. For example, if your range has a location of 10 and length of 3, then its lastLocation is 12. A zero length range returns its location as its lastLocation, even though technically it does not contain that location.
If an attempt is made to set the lastLocation to a number less than location, then an error is displayed. Changing the lastLocation also changes the length and bound.
Range Object Commands
.intersectsRange otherRange v1.3
Returns @true if the ranges intersect, otherwise @false.
.containsLocation location v1.3
Returns @true if the location is contained in the range, otherwise @false.
.containsRange otherRange v1.3
Returns @true if the other range is completely contained, otherwise @false.
.intersectionRange otherRange v1.3
Returns the range that contains only those locations contained in both ranges. If the ranges do not intersect, this returns a zero-length range.
.unionRange otherRange v1.3
Returns the range that contains all locations contained in either range. If the ranges are disjoint (do not overlap), the locations between them are also included in the returned range.
Range Object Examples
Creating a range that includes five elements starting at index ten:
$range = Range.new(10, 5)
Two other ways to create exactly the same range:
$range = Range.newWithLocations(10, 14)
$range = Range.newWithLocationAndBound(10, 15)
Creating a range that is used to access the first three values in an array, and then the first three characters in some text:
$range = Range.new(0, 3)
$firstValues = $array.subarrayInRange($range)
$firstChars = $text.subtextInRange($range)
| Previous Chapter Language Object |
<< index >> |
Next Chapter Rect Object |