Generic range type interface for use with RangeGroup. This provides all the definitions for creating and manipulating a Range. An important design choice was to allow ranges to be defined with plain JSON objects. Because of this, RangeType provide a C-like interface for performing operations on those objects, rather than forcing a class based design. You can still use a class to implement a particular type of Range; if going that route, you'll supply a supplementary RangeType to RangeGroup, where you are simply calling the class methods.
Methods
(static) compare(mode, a, b, aExclnullable, bExclnullable) → {RangeType~CompareResult}
Compares two start/end boundaries.
The comparison function should return a tuple, which is a little different than what you might use with Array.prototype.sort
. This is to allow proper handling of exclusive bounds. As an example, consider the gap between ranges [0,5) [5,10]
: the distance between the ranges is infinitely small, but not quite equal. So in this case, the compare function returns {distance:0, side:-1}
, to indicate zero gap approaching from the left. See RangeType~CompareResult for more details.
Name | Type | Attributes | Description |
---|---|---|---|
mode | ComparisonModes | What combination of range starts/ends is being compared. See documentation for ComparisonModes for the specific enumeration values, or for details on using it as a bitmask instead. This allows you to properly handle exclusive bounds for start vs end. | |
a | any | The Range#start or Range#end to be compared | |
b | any | The Range#start or Range#end to compare with | |
aExcl | boolean | <nullable> | Whether |
bExcl | boolean | <nullable> | Whether |
- Type:
- RangeType~CompareResult
(static) copy(range) → {Range}
Name | Type | Description |
---|---|---|
range | Range | the range to be copied |
copied range
- Type:
- Range
(static) create(…args) → {Range}
Create a new Range object. If no arguments are passed, an empty/default range should be created. Otherwise, a new range should be initialized using the arguments passed. The form of these arguments is up to the RangeType.
Name | Type | Attributes | Description |
---|---|---|---|
args | any | <repeatable> | arguments to initialize the range |
the newly created range
- Type:
- Range
(static) iterate(reversenullable, …args) → {iterable}
Iterate values inside the range. This is called by RangeGroup#iterate, and should be implemented if the type wishes to support that method.
Name | Type | Attributes | Description |
---|---|---|---|
reverse | boolean | <nullable> | Whether values should be iterated forward or backward. The ordering is up to the RangeType, but in general forward should correspond to ascending order. |
args | any | <repeatable> | Arbitrary arguments used to customize the iteration. These are forwarded from RangeGroup#iterate |
Can return a generator, or some other object implementing the iterable interface
- Type:
- iterable
(static) sample(range, i) → {Range}
Name | Type | Description |
---|---|---|
range | Range | the range to sample from |
i | number | a float between [0,1) indicating what sample to return |
a sample drawn from range
- Type:
- Range
(static) setEnd(range, end, endExclnullable) → {Range}
Set the ending bound of a Range. Range ends are always modified using this method, so that a RangeType can implement auto-normalization: normalizing the bound to be inclusive.
Name | Type | Attributes | Description |
---|---|---|---|
range | Range | the range to modify | |
end | any | the new ending bound | |
endExcl | boolean | <nullable> | whether the end is exclusive |
the modified range
- Type:
- Range
(static) setStart(range, start, startExclnullable) → {Range}
Set the starting bound of a Range. Range starts are always modified using this method, so that a RangeType can implement auto-normalization: normalizing the bound to be inclusive.
Name | Type | Attributes | Description |
---|---|---|---|
range | Range | the range to modify | |
start | any | the starting bound | |
startExcl | boolean | <nullable> | whether the start is exclusive |
the modified range
- Type:
- Range
(static) size(range) → {number}
Return the size, or cardinality of this range. This is called by RangeGroup#size
Name | Type | Description |
---|---|---|
range | Range | the range to retrieve the size of |
the range size
- Type:
- number
Type Definitions
CompareResult
Result of RangeType.compare
- object
Name | Type | Description |
---|---|---|
distance | number | The signed distance between The
|
side | number | One of the following:
|