Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Range<T>

A convenience range/interval type.

Built around number by default, it supports custom types through the spec argument of its constructor methods.

Examples:

// Working with numbers:
const instance: Range<number> = Range.openClose(0, 10); // (0; 10]
const instance: Range<number> = Range.closeOpen(-10, 10); // [-10; 10)
const instance: Range<number> = Range.empty(); // {}, an empty range

// Working with a custom type:
type MyType;
class MyTypeRangeSpec extends AbstractRangeSpec<MyType> {
  comparator: (a: MyType, b: MyType): number => a.valueOf() - b.valueOf();
  isInfinity: (v: MyType): boolean => false; // You custom type can also be finite
}
// Creates a ["hello", "world") range.
const instance: Range<MyType> = Range.closeOpen(MyType("hello"), MyType("world"),
                                                new MyTypeRangeSpec());

This class is fully immutable.

Type parameters

  • T

    the target type stored by this range. A custom spec is required unless it's coercible to number.

    Extra care is required around handling empty ranges, since they may have their bounds set to null if created with Range.empty.

    Note: since it's not possible to make an infinite bound inclusive, relevant constructor methods override the requested bound type for values that conform to RangeSpec.isInfinity.

Hierarchy

  • Range

Index

Properties

Readonly isLowerEnclosed

isLowerEnclosed: boolean

Indicates whether the lower bound is included (i.e. if it's an open bound).

Readonly isUpperEnclosed

isUpperEnclosed: boolean

Indicates whether the upper bound is included (i.e. if it's an open bound).

Readonly lower

lower: T

The lower bound of this range, regardless of whether it's included.

Readonly spec

spec: RangeSpec<T>

The spec this range is built upon. Defaults to an instance of NumberSpec

Readonly upper

upper: T

The upper bound of this range, regardless of whether it's included.

Accessors

isEmpty

  • get isEmpty(): boolean
  • Tells whether this is an empty range, i.e. the one including no elements.

    Returns boolean

isLowerInfinity

  • get isLowerInfinity(): boolean
  • Tells whether the spec this range is built upon returns isInfinity -> true for its lower bound.

    Returns boolean

isUpperInfinity

  • get isUpperInfinity(): boolean
  • Tells whether the spec this range is built upon returns isInfinity -> true for its upper bound.

    Returns boolean

Methods

adjacent

  • adjacent(other: Range<T>): boolean

adjacentLeft

  • adjacentLeft(other: Range<T>): boolean
  • Tests whether other is adjacent to this on the left, i.e. other.upper is connected to this.lower, but does not intersect with it.

    Range.open(10, 20).adjacentLeft(Range.close(0, 10)); // -> true
    Range.open(10, 20).adjacentLeft(Range.empty()); // -> false
    Range.open(10, 20).adjacentLeft(Range.singleton(10)); // -> true
    

    Parameters

    • other: Range<T>

      The range that is expected to be connected to this on the left.

    Returns boolean

adjacentRight

  • adjacentRight(other: Range<T>): boolean
  • Tests whether other is adjacent to this on the right, i.e. other.lower is connected to this.upper, but does not intersect with it.

    Range.open(10, 20).adjacentLeft(Range.close(20, 30)); // -> true
    Range.open(10, 20).adjacentLeft(Range.empty()); // -> false
    Range.open(10, 20).adjacentLeft(Range.singleton(20)); // -> true
    

    Parameters

    • other: Range<T>

      The range that is expected to be connected to this on the right.

    Returns boolean

contains

  • contains(other: Range<T>): boolean
  • contains(element: T): boolean
  • Tests whether this range contains the entire other.

    Empty ranges are contained in any other range, including another empty range.

    Range.open(10, 20).contains(Range.open(5, 7)); // -> true
    Range.open(10, 20).contains(Range.open(10, 20)); // -> true
    Range.close(10, 20).contains(Range.open(10, 20)); // -> true
    Range.open(10, 20).contains(Range.close(10, 20)); // -> false
    Range.empty().contains(Range.open(50, 50)); // -> true
    Range.singleton(10).contains(Range.empty()); // -> true
    

    Parameters

    • other: Range<T>

      The range to test containment against.

    Returns boolean

  • Tests whether this range contains the element.

    Range.open(10, 20).contains(5); // -> true
    Range.open(10, 20).contains(10); // -> false
    Range.close(10, 20).contains(10); // -> true
    Range.empty().contains(0); // -> false
    Range.singleton(10).contains(10); // -> true
    

    Parameters

    • element: T

      The element to test containment against.

    Returns boolean

equals

  • equals(other: Range<T>): boolean
  • Tests whether this has the same bounds & bound inclusion as other.

    Empty ranges are always equal, regardless of what bounds they were built with.

    Range.open(10, 20).equals(Range.open(10, 20)); // -> true
    Range.empty().equals(Range.open(50, 50)); // -> true
    Range.singleton(10).equals(Range.empty()); // -> false
    

    Parameters

    • other: Range<T>

      The range expected to be equal to this.

    Returns boolean

intersection

  • Returns an intersection of this range with other.

    The result of range intersection shall include the narrowest range that includes all the elements present in both of the source ranges.

    Range.open(10, 20).intersection(Range.closeOpen(12, 16)); // -> [12; 16)
    Range.open(10, 20).intersection(Range.empty()); // -> {}, an empty range
    Range.empty().intersection(Range.close(10, 20)); // -> {}, an empty range
    

    Parameters

    • other: Range<T>

      The right-hand side argument of the intersection.

    Returns Range<T>

subtract

  • Returns parts of this range, excluding all the elements present in the other one.

    Range.open(10, 20).subtract(Range.closeOpen(12, 16)); // -> [ (10; 12), [16; 20) ]
    Range.open(10, 20).subtract(Range.empty()); // (10; 20)
    Range.empty().subtract(Range.close(10, 20)); // -> [], an empty array
    

    Parameters

    • other: Range<T>

      The range to subtract from this.

    Returns Range<T>[]

    A list of ranges containing all the elements present in this, but not in other. The list does not include any empty ranges. The resulting list will be empty if other contains this.

toString

  • toString(): string
  • Returns this range's textual representation.

    Returns string

    A mathematical representation of this range, relying on lower and upper's toString. Returns {} for empty range.

union

  • Returns a union of this range with other.

    The united range is the narrowest range that includes all the elements from both of the source ranges.

    Union is impossible for non-intersecting ranges, so it might be a good idea to check if they are intersecting/adjacent to avoid excptions:

    const r1 = Range.open(10, 20);
    const r2 = Range.close(30, 40);
    if (!r1.intersection(r2).isEmpty || r1.isAdjacent(r2)) {
      const united = r1.union(r2);
      // Do something with this united range
    }
    

    Examples:

    Range.open(10, 20).union(Range.closeOpen(15, 25)); // -> (10; 25)
    Range.open(10, 20).union(Range.empty()); // -> (10; 20)
    Range.empty().union(Range.close(10, 20)); // -> (10; 20)
    Range.open(10, 20).union(Range.singleton(50)); // -> Error("Cannot union non-intersecting and non-adjacent ranges")
    
    throws

    if the provided ranges cannot be combined into a contiguous range: they neither intersect nor are adjacent.

    Parameters

    • other: Range<T>

      The right-hand side argument of the intersection.

    Returns Range<T>

Static close

  • Create a closed range, i.e. the one that includes both its bounds.

    const instance: Range<number> = Range.close(-1, 1); // [-1; 1]
    

    It can also be used to implicitly create a singleton range:

    Range.close(10, 10).isEqual(Range.singleton(10)); // -> true
    

    Bounds are forcibly overriden to open for infinity bounds, i.e. bound values that conform to RangeSpec.isInfinity.

    Type parameters

    • T

      the target type to b represented by the resulting range. A custom spec is required unless it's coercible to number.

    Parameters

    • from: T

      A lower bound of the resulting range, included.

    • to: T

      An upper bound of the resulting range, included.

    • Optional spec: RangeSpec<T>

      Optional. See RangeSpec.

    Returns Range<T>

Static closeOpen

  • Create a close-open range, i.e. the one that only includes its lower bound.

    const instance: Range<number> = Range.closeOpen(-1, 1); // [-1; 1)
    

    It can also be used to implicitly create an empty range:

    const instance: Range<number> = Range.closeOpen(10, 10); // {}, an empty range
    

    Bounds are forcibly overriden to open for infinity bounds, i.e. bound values that conform to RangeSpec.isInfinity.

    Type parameters

    • T

      the target type to b represented by the resulting range. A custom spec is required unless it's coercible to number.

    Parameters

    • from: T

      A lower bound of the resulting range, included.

    • to: T

      An upper bound of the resulting range, excluded.

    • Optional spec: RangeSpec<T>

      Optional. See RangeSpec.

    Returns Range<T>

Static empty

  • Create an empty range, i.e. the one that doesn't include anything.

    const instance: Range<number> = Range.empty(); // {}, an empty range
    

    Type parameters

    • T

      the target type to b represented by the resulting range. A custom spec is required unless it's coercible to number.

    Parameters

    Returns Range<T>

Static open

  • Create an open range, i.e. the one that does not include either of its bounds.

    const instance: Range<number> = Range.open(-1, 1); // (-1; 1)
    

    It can also be used to implicitly create an empty range:

    const instance: Range<number> = Range.open(10, 10); // {}, an empty range
    

    Type parameters

    • T

      the target type to b represented by the resulting range. A custom spec is required unless it's coercible to number.

    Parameters

    • from: T

      A lower bound of the resulting range, excluded.

    • to: T

      An upper bound of the resulting range, excluded.

    • Optional spec: RangeSpec<T>

      Optional. See RangeSpec.

    Returns Range<T>

Static openClose

  • Create an open-close range, i.e. one that only includes its upper bound.

    const instance: Range<number> = Range.openClose(-1, 1); // (-1; 1]
    

    It can also be used to implicitly create an empty range:

    const instance: Range<number> = Range.openClose(10, 10); // {}, an empty range
    

    Bounds are forcibly overriden to open for infinity bounds, i.e. bound values that conform to RangeSpec.isInfinity.

    Type parameters

    • T

      the target type to b represented by the resulting range. A custom spec is required unless it's coercible to number.

    Parameters

    • from: T

      A lower bound of the resulting range, excluded.

    • to: T

      An upper bound of the resulting range, included.

    • Optional spec: RangeSpec<T>

      Optional. See RangeSpec.

    Returns Range<T>

Static singleton

  • Create a singleton range, i.e. the one that only includes a single value

    const instance: Range<number> = Range.singleton(5); // [5; 5]
    

    Note: a singleton instance cannot be created out of a [[RangeSpec.infinity]] value, since infinity cannot be enclosed in an interval.

    throws

    Error if the supplied value conforms to RangeSpec.isInfinity.

    Type parameters

    • T

      the target type to b represented by the resulting range. A custom spec is required unless it's coercible to number.

    Parameters

    • value: T

      The value the resulting range will include.

    • Optional spec: RangeSpec<T>

      Optional. See RangeSpec.

    Returns Range<T>

Generated using TypeDoc