RangeType

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.

Parameters:
NameTypeAttributesDescription
modeComparisonModes

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.

aany

The Range#start or Range#end to be compared

bany

The Range#start or Range#end to compare with

aExclboolean<nullable>

Whether a is an exclusive bound

bExclboolean<nullable>

Whether b is an exclusive bound

(static) copy(range) → {Range}

Copy a Range of this RangeType

Parameters:
NameTypeDescription
rangeRange

the range to be copied

Returns:

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.

Parameters:
NameTypeAttributesDescription
argsany<repeatable>

arguments to initialize the range

Returns:

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.

Parameters:
NameTypeAttributesDescription
reverseboolean<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.

argsany<repeatable>

Arbitrary arguments used to customize the iteration. These are forwarded from RangeGroup#iterate

Returns:

Can return a generator, or some other object implementing the iterable interface

Type: 
iterable

(static) sample(range, i) → {Range}

Draw a sample from a Range. This is used by Sampler

Parameters:
NameTypeDescription
rangeRange

the range to sample from

inumber

a float between [0,1) indicating what sample to return

Returns:

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.

Parameters:
NameTypeAttributesDescription
rangeRange

the range to modify

endany

the new ending bound

endExclboolean<nullable>

whether the end is exclusive

Returns:

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.

Parameters:
NameTypeAttributesDescription
rangeRange

the range to modify

startany

the starting bound

startExclboolean<nullable>

whether the start is exclusive

Returns:

the modified range

Type: 
Range

(static) size(range) → {number}

Return the size, or cardinality of this range. This is called by RangeGroup#size

Parameters:
NameTypeDescription
rangeRange

the range to retrieve the size of

Returns:

the range size

Type: 
number

Type Definitions

CompareResult

Type:
  • object
Properties
NameTypeDescription
distancenumber

The signed distance between a and b. For continuous domains, this is a traditional distance measure, e.g. a - b for numbers. For discrete domains, it should measure the number of elements in between a and b; e.g. for integers, the distance between 3 and 5 is 1, since only one integer, 4, is between.

The distance is used for several things:

  1. To merge adjacent ranges if the distance (or gap) between them is zero. For example, the integer ranges [0,2] [3,5] or floating point ranges [0,3) [3,5] could be merged as [0,5]. Another case might be, [-2,-0] [+0,3] which can be merged as [-2,3].
  2. To perform interpolation search in RangeGroup#search. You can opt-out of interpolation search by returning the sign of distance (-1, 0, or +1); this causes the search to reduce to binary search instead. See CommonType.compareBinarySearch for a decorator which does this.
sidenumber

One of the following:

  • -1: a comes before b
  • 0: a equals b exactly; signed zero -0 is also fine here
  • 1: a comes after b