multi-integer-range API Reference
October 31, 2025 · View on GitHub
- All functions are pure functions. They do not alter the input arguments nor do they have side effects.
- All functions and types are exported as named exports.
- All MultiIntegerRange returned by these functions are normalized.
- The legacy
MultiRangeclass is also available but is not documented here. See the docs for v4 for this.
Contents
parse()normalize()initialize()append()subtract()intersect()has()length()isUnbounded()equals()min()max()at()tail()init()stringify()flatten()iterate()
type: Range
type Range = readonly [min: number, max: number];
A [min, max] tuple to denote one integer range.
type: MultiIntegerRange
type MultiIntegerRange = readonly Range[];
An immutable Range array. This is the fundamental data type of this package.
Warning: Most functions of this package work correctly
only when normalized MultiIntegerRange's are passed.
If you have a Range array that may not be sorted, use normalize() first.
function: parse
parse(data: string, options?: Options): MultiIntegerRange
| Param | Description |
|---|---|
data | The string to parse. |
options | Options to modify the parsing behavior. |
| Returns | A new normalized MultiIntegerRange. |
Parses a string and creates a new MultiIntegerRange.
options.parseNegative(boolean): When set to true, parses negative integers enclosed in parentheses.options.parseUnbounded(boolean): When set to true, parses unbounded ranges like10-or-10.
This is the default parser, but you don't necessarily have to use this.
You can create your own parser to suit your needs
as long as it produces a normalized array of Ranges.
Example
parse('1-10'); // [[1, 10]]
parse(' 10-, 7', { parseUnbounded: true }); // [[7, 7], [10, Infinity]]
function: normalize
normalize(data?: (number | Range)[] | number): MultiIntegerRange
| Param | Description |
|---|---|
data | A number or an unsorted array, e.g., [[7, 5], 1]. |
| Returns | Normalized array, e.g., [[1, 1], [5, 7]]. |
Takes a number or an unsorted array of ranges, and returns a new normalized MultiIntegerRange.
Here, "normalized" means the range data is in the smallest possible representation and is sorted in ascending order.
This is the only function that can take an unsorted array of Range's.
Unsorted range data MUST be normalized before being passed to
other functions such as append() and length().
Example
normalize(5); // [[5, 5]]
normalize([1, 8]); // [[1, 1], [8, 8]]
normalize([[1, 8]]); // [[1, 8]]
normalize([2, 3, 1, 5, 4, 0, 1, 3]); // [[0, 5]]
normalize([[Infinity, 1]]); // [[1, Infinity]]
function: initialize
initialize(
data?: (number | Range)[] | number | string,
options?: Options
): MultiIntegerRange
| Param | Description |
|---|---|
data | Anything understood by either parse() or normalize(). |
options | Parse options passed to parse(). |
| Returns | A new normalized MultiIntegerRange. |
Takes any supported data and returns a normalized MultiIntegerRange.
Conditionally calls either parse() or normalize() under the hood.
This is an equivalent of "initializer" constructor of version ≤ 4.
Example
initialize(5); // [[5, 5]]
initialize('2-8'); // [[2,8]]
function: append
append(a: MultiIntegerRange, b: MultiIntegerRange): MultiIntegerRange
| Param | Description |
|---|---|
a | The first value. |
b | The second value. |
| Returns | A new MultiIntegerRange containing all integers that belong to either a or b (or both). |
Appends two MultiIntegerRange's.
Example
append([[1, 5]], [[3, 8], [10, 15]]); // [[1, 8], [10, 15]]
append([[5, 9]], [[-Infinity, 2]]); // [[-Infinity, 2], [5, 9]]
function: subtract
subtract(a: MultiIntegerRange, b: MultiIntegerRange): MultiIntegerRange
| Param | Description |
|---|---|
a | The value to be subtracted. |
b | The value to subtract. |
| Returns | A new MultiIntegerRange containing all integers that belong to a but not b. |
Subtracts the second value from the first value.
Example
subtract([[1, 7]], [[2, 4]]); // [[1, 1], [5, 7]]
subtract([[-Infinity, Infinity]], [[2, 4]]); // [[-Infinity, 1], [5, Infinity]]
function: intersect
intersect(a: MultiIntegerRange, b: MultiIntegerRange): MultiIntegerRange
| Param | Description |
|---|---|
a | The first value. |
b | The second value. |
| Returns | A new MultiIntegerRange containing all integers that belong to both a and b. |
Calculates the intersection (common integers) of the two MultiIntegerRange's.
Example
intersect([[2, 5]], [[4, 9]]); // [[4, 5]]
intersect([[5, 10]], [[-Infinity, Infinity]]); // [[5, 10]]
function: has
has(a: MultiIntegerRange, b: MultiIntegerRange): boolean
| Param | Description |
|---|---|
a | The value that possibly contains b. |
b | The value that is possibly contained by a. |
| Returns | True if b is equal to or a subset of a. |
Checks if a contains or is equal to b (a ⊇ b).
Example
has([[0, 100]], [[2, 10]]); // true
has([[5, 7]], [[5, 7]]); // true
has([[2, 10]], [[0, 100]]); // false
function: length
length(data: MultiIntegerRange): number
| Param | Description |
|---|---|
data | The value to calculate the length on. |
| Returns | The number of integers contained in data. May be Infinity. |
Calculates how many integers are included in the given MultiIntegerRange.
Note: If you want to know the number of Ranges (segments), just use the
standard Array#length.
Example
length([[1, 3], [8, 10]]); // 6
length([[1, Infinity]]); // Infinity
function: isUnbounded
isUnbounded(data: MultiIntegerRange): boolean
| Param | Description |
|---|---|
data | The value to check. |
| Returns | True if data is unbounded. |
Checks if the data contains an unbounded (aka inifinite) range.
Example
isUnbounded([[1, Infinity]]); // true
isUnbounded([[-Infinity, 4]]); // true
isUnbounded([[7, 9]]); // false
function: equals
equals(a: MultiIntegerRange, b: MultiIntegerRange): boolean
| Param | Description |
|---|---|
a | The first value to compare. |
b | The second value to compare. |
| Returns | True if a and b have the same range data. |
Checks if the two values are the same. (Altenatively, you can use any "deep-equal" utility function.)
Example
equals([[1, 5], [7, 8]], [[1, 5], [7, 8]]); // true
equals([[1, 5]], [[2, 7]]); // false
function: min
min(data: MultiIntegerRange): number | undefined
| Param | Description |
|---|---|
data | The value. |
| Returns | The minimum integer. May be undefined or -Infinity. |
Returns the minimum integer of the given MultiIntegerRange.
Example
min([[2, 5], [8, 10]]); // 2
min([[-Infinity, 0]]); // -Infinity
min([]); // undefined
function: max
max(data: MultiIntegerRange): number | undefined
| Param | Description |
|---|---|
data | The value. |
| Returns | The minimum integer. May be undefined or Infinity. |
Returns the maximum integer of the given MultiIntegerRange.
Example
max([[2, 5], [8, 10]]); // 10
max([[3, Infinity]]); // Infinity
max([]); // undefined
function: at
at(data: MultiIntegerRange, index: number): number | undefined
| Param | Description |
|---|---|
data | The value. |
index | The 0-based index of the integer to return. Can be negative. |
| Returns | The integer at the specified index. Returns undefined if the index is out of bounds. |
Returns the integer at the specified 0-based index. If a negative index is given, the index is counted from the end.
Example
at([[2, 4], [8, 10]], 4); // 9
at([[2, 4], [8, 10]], 6); // undefined
at([[2, 4], [8, 10]], -1); // 10
function: tail
tail(data: MultiIntegerRange): MultiIntegerRange
| Param | Description |
|---|---|
data | The value. |
| Returns | A new MultiIntegerRange which is almost the same as data but with its minimum integer removed. |
Returns all but the minimum integer.
Example
tail([[2, 5], [8, 10]]); // [[3, 5], [8, 10]]
function: init
init(data: MultiIntegerRange): MultiIntegerRange
| Param | Description |
|---|---|
data | The value. |
| Returns | A new MultiIntegerRange which is almost the same as data but with its maximum integer removed. |
Returns all but the maximum integer.
Example
init([[2, 5], [8, 10]]); // [[2, 5], [8, 9]]
function: stringify
stringify(
data: MultiIntegerRange,
options: StringifyOptions = {}
): string
| Param | Description |
|---|---|
data | The MultiIntegerRange to stringify. |
options | Options for the stringification. |
| Returns | The string representation of the given data. |
Returns the string respresentation of the given MultiIntegerRange.
options.individualThreshold(number): If set, small ranges with a length smaller than or equal to this will be output as individual integers. Defaults to1, which means only ranges with a length of 1 will be output as a single integer.
Example
stringify([[2, 3], [5, 5], [7, 9]]); // '2-3,5,7-9'
stringify([[2, 3], [5, 5], [7, 9]], { individualThreshold: 0 }); // '2-3,5-5,7-9'
stringify([[2, 3], [5, 5], [7, 9]], { individualThreshold: 2 }); // '2,3,5,7-9'
stringify([[2, 3], [5, 5], [7, 9]], { individualThreshold: 3 }); // '2,3,5,7,8,9'
stringify([[3, 5], [7, Infinity]]); // '3-5,7-'
function: flatten
flatten(data: MultiIntegerRange): number[]
| Param | Description |
|---|---|
data | The value to build an array on. |
| Returns | The flattened array of numbers. |
Builds a flattened array of integers. Note that this may be slow and memory-consuming for large ranges. Consider using the iterator whenever possible.
Example
flatten([[-1, 1], [7, 9]]); // [-1, 0, 1, 7, 8, 9]
function: iterate
iterate(
data: MultiIntegerRange,
options: IterateOptions = {}
): Iterable<number>
| Param | Description |
|---|---|
data | The normalized MultiIntegerRange to iterate over. |
options | Options for the iteration. |
| Returns | An Iterable object. |
Returns an Iterable with which you can use for-of or the spread syntax.
options.descending(boolean): If set to true, the iterator will iterate in descending order.
Example
Array.from(iterate([[1, 3], [7, 9]])); // [1, 2, 3, 7, 8, 9]
Array.from(iterate([[1, 3], [7, 9]], { descending: true })); // [9, 8, 7, 3, 2, 1]
[...iterate([[-1, 2]])]; // [-1, 0, 1, 2]