Range

added in 0.0.1 • updated in 0.3.0 • last revisions

A class that encompasses a range between two numbers.

Constructor

new Range(from: number, to: number)

Creates a range from the given number to another.

Note that from does not necessarily need to be smaller than to. If it is greater, the range is considered inverted.

Public Properties

`from`	Gets the number that was passed in as the range’s left bound.
`to`	Gets the number that was passed in as the range’s right bound.

Public Mutator Methods

`set(from: number, to: number): this`	Sets the values of `from` and `to` to the new values.
`invert(): this`	Gets the number that was passed in as the range’s right bound.

Public Computed Properties

`min(): number`	Gets either `from` or `to`, depending on which is smaller.
`max(): number`	Gets either `from` or `to`, depending on which is greater.
`center(): number`	Gets the number in-between `from` and `to` which is an equal distance away from both `from` and `to`. Example: `new Range(5, 10).center()` returns `7.5`.
`span(): number`	Gets the total length of the range. This value will always be positive. Example: `new Range(3, 7).span()` returns `4`.

Public Non-Mutator Methods

`clamp(value: number): number`	Clamps `value` to this range. If `value` exceeds the range’s bounds, it will be clamped to that bound, otherwise `value` is returned unchanged. Example: `new Range(0, 10).clamp(11)` returns `10`.
`contains(range: ReadonlyRange): boolean`	Returns `true` if the target range is completely contained in this range.
`contains(value: number, tolerance?: number): boolean`	Checks if the number is contained in this range. A number is considered contained by the range if it lies in-between or on the bounds of this range. This function allows you to specify a tolerance to combat floating point inaccuracies. By default a tolerance of `0.00000001` is used. The tolerance does not need to be a decimal number though—you can specify arbitrary positive or negative tolerances to expand or narrow the range before the contains check.
`isBetween(value: number): boolean`	Checks if the number is in-between the end points of this range. This function differs from `contains()` in that `contains()` also considers values on the two end points to be “inside” the range. This function does not. It is recommended not to use this function with floating point numbers. Use `contains()` with an appropriate tolerance instead.
`overlaps(range: ReadonlyRange): boolean`	Returns `true` if some part of `range` overlaps with this range.
`intersectionPoint(range: ReadonlyRange): number`	Finds the intersection point closest to this range’s center with the given range. If this range completely envelops the target range, returns this range’s center. If there is no intersection, returns NaN.
`intersect(range: ReadonlyRange): Range`	Gets the intersection between this range and range as a new Range. If there is no intersection, returns an empty Range. For example, a `Range(0, 3)` intersecting with a `Range(2, 5)` will return a new `Range(2, 3)`.
`union(range: ReadonlyRange): Range`	Gets the union between this range and range as a new Range. If there is no true union (that is, the two ranges do not intersect), the returned Range will "bridge the gap", so to speak, acting as if either of the ranges were large enough to meet the other. For example, a `Range(0, 3)` unioning with a `Range(2, 5)` will return a new `Range(0, 5)`. A `Range(0, 3)` unioning with a `Range(5, 6)` will return a new `Range(0, 6)`.
`getOffset(range: ReadonlyRange): number`	If this range intersects with `range`, gets the total distance that this range should be moved so that it no longer intersects with `range`. This function will always choose the shortest distance. The distance can be negative. If the ranges don’t intersect, the return value will be 0. For example, a `Range(0, 3)` and a `Range(2, 5)` will return an offset of `-1` (“move this range backwards by 1 to get `Range(-1, 2)`, thus no longer intersecting with the other range”).
`at(value: number): number`	Gets the value located at `value`. For the returned value to be inside this range, `value` should be between 0.0 and 1.0.
`relative(value: number): number`	Gets a relative value between 0.0 and 1.0 to indicate the position of the passed value inside the range. This function is the counter-component to `at()`.
`wrap(value: number): number`	Wraps the number into this range. That is, if the number exceeds this range, it will "wrap around" the range's start. For instance, in a range of -3 to 3, the value 4 would be wrapped to -2.
`isEmpty(): boolean`	Returns `true` if the range is empty, that is its length is 0.
`equals(range: ReadonlyRange): boolean`	Checks if the given range is identical to this one.
`equals(from: number, to: number): boolean`	Checks if this range has the given `from` and `to` values.
`clone(): ReadonlyRange`	Clones the range.

Remarks

Note that all computed properties like min() or max() are cached after the first call and only recomputed if the range bounds change. As a result, there is no need to store their results in temporary variables to avoid recomputation.

There is also a read-only interface of Range available called ReadonlyRange.

Due to conflicts with the Range from lib.dom.d.ts, you may wish to create a new range using Numbers.range() instead of using the constructor directly.