@lost-types/range

Range

Usage

In the terminal:

% npm install @lost-types/range

Then in the module:

// JavaScript modules
import Range from '@lost-types/range';

// CommonJS
const Range = require('@lost-types/range');

const range = new Range(-1, 1, 0.01);

Motivation

Range class is somewhat influenced by the function of the same name from Python. The important difference is that both start and end arguments are inclusive!

const range = new Range(1, 2);
range.toArray(); // [1, 2]

There is no particular reason behind it, I just wanted to humanize behavior.

Why do we need Range type? If you think deeply enough you will realize that we use ranges all the time. All the types and libraries from @lost-types series are exclusively created for my personal usage, Range in particular I've created as a helper type for another type in @lost-types series - Color, here are some usage examples:

const hueRange = new Range(359);
const percentRange = new Range(0, 1, 0.0001);

// Ensure hue value is always  in [0 ... 359] range
// (This is default browser behavior)
const hue = -45;
hueRange.mod(hue); // 315

// Ensure percentage value is clamped in [0 ... 1] range
const percentage = 1.25;
percentRange.clamp(percentage); // 1

Another useful case is just to generate array of numbers with provided step:

[...new Range(9)]; // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
[...new Range(3, -1)]; // [3, 2, 1, 0, -1]
[...new Range(1, -1, 0.25)]; // [1, 0.75, 0.5, 0.25, 0, -0.25, -0.5, -0.75, -1]

More examples below in the API section.

API

Constructor

Creates a new Range instance. Parameters:

Parameter	Type	Default value	Notes
rangeStart	number	0	Defaults to zero if only one argument provided
rangeEnd	number		rangeEnd is inclusive in the range
step	number	1	Cannot be less or equal than 0

new Range(-1, 1, 0.01); // Range{ from: -1, to: 1, step: 0.01 }
new Range(-1, 1); // Range{ from: -1, to: 1, step: 1 }
new Range(100); // Range{ from: 0, to: 100, step: 1 }
new Range(); // Range{}

Properties

Range.length

Returns total number of numbers in the range, if range will be converted to the array

const range = new Range(0, 100, 0.01);
range.length; // 10001

const array = [...range];
array.length; // 10001

It is useful to check the length prior to converting range into array:

const range = new Range(Infinity);
range.length; // Infinity

[...range]; // Throws error: Cannot iterate through infinite range

---

Range.from

Range.to

Range.step

Return initial values used to create the range:

const range = new Range(0, 100, 0.01);
range.from; // 0
range.to; // 100
range.step; // 0.01

---

Range.max

Range.min

Range.center

Return the number from the range with the greatest value, the least value and the center of the range

const range = new Range(5, -5);
range.min; // -5
range.max; // 5
range.center; // 0

Note: All properties of the Range instance are read-only

Methods

Range.from()

Static method on Range to generate range from array or any other iterable type. Returns a new Range instance.

Parameter	Type	Default value	Notes
iterable	any		Any iterable type, like Array, Set, String...

const arr = [7, 6, 5, 42, 16, 9];
Range.from(arr); // Range{ from: 5, to: 42, step: 1 }

const str = '420';
// By no way I encourage you to do this! :)
Range.from(str); // Range{ from: 0, to: 4, step: 1 }

Range.from([]); // Range{}

---

Range.prototype.clamp()

Similarly to _.clamp(), ensures the resulting number is in the range. Returns clamped number.

Parameter	Type	Default value	Notes
number	number

const range = new Range(99);
range.clamp(100); // 99
range.clamp(-42); // 0
range.clamp(15); // 15
range.clamp(); // NaN

---

Range.prototype.has()

Returns boolean indicating whether provided number within a range.

Parameter	Type	Default value	Notes
number	number

const range = new Range(99);
range.has(100); // false
range.has(-42); // false
range.has(15); // true
range.has(); // false

---

Range.prototype.forEach()

Executes provided function on every element of the range with the provided step. If no step provided initial Range.step will be used. Similarly to forEach in Array, following arguments will be passed to the callback:

• currentValue
• index
• range

Will try to account for precision errors between numbers in the range. Always returns undefined.

Parameter	Type	Default value	Notes
fn	function		To be invoked as fn(number, index, range)
step	number	Range.step	forEach() can be invoked with custom step

const range = new Range(-1, 1);
range.forEach((number) => {
  console.log(number);
}, 0.5);
// -1
// -0.5
// 0
// 0.5
// 1

---

Range.prototype.forEachReverse()

Similarly to Range.prototype.forEach(), executes provided function on every element of the range with the provided step in reversed manner. If no step provided initial Range.step will be used. Similarly to forEach in Array, following arguments will be passed to the callback:

• currentValue
• index
• range

Will try to account for precision errors between numbers in the range. Always returns undefined.

Parameter	Type	Default value	Notes
fn	function		To be invoked as fn(number, index, range)
step	number	Range.step	forEachReverse() can be invoked with custom step

const range = new Range(-1, 1);
range.forEachReverse((number) => {
  console.log(number);
}, 0.5);
// 1
// 0.5
// 0
// -0.5
// -1

---

Range.prototype.getFraction()

Returns ratio of the provided number proportional to the range.

Parameter	Type	Default value	Notes
number	number
precision	number	12	Optional

Useful to calculate percentage value of the range.

const range = new Range(255);
range.getFraction(17, 4); // 0.0667
// Value 17 represents 6.67% of the [0 ... 255] range

---

Range.prototype.fromFraction()

Inverse method from Range.prototype.getFraction(). Returns number represented by provided ratio relative to the range.

Parameter	Type	Default value	Notes
ratio	number
precision	number	12	Optional

Useful to calculate value from the percentage.

const range = new Range(255);
range.fromFraction(0.065, 0); // 17
// Value 17 represents 6.5% of the [0 ... 255] range with 0 floating point precision

---

Range.prototype.toArray()

Converts range to array. Throws error with range length is greater than max possible array size.

const range = new Range(0.1, 0.5, 0.1);
range.toArray(); // [0.1, 0.2, 0.3, 0.4, 0.5]
// same as [...range]

const infiniteRange = new Range(0.1, 0.5, Number.MIN_VALUE);
infiniteRange.length; // Infinity
range.toArray(); // throws Error: Cannot iterate infinite size range

---

Range.prototype.mod()

Returns number in the range which is the result of modulo operation of the provided input number to the range.

Parameter	Type	Default value	Notes
number	number

It's really much easier to explain on the example:

const range = new Range(359);
range.mod(360); // 0
range.mod(-45); // 315
range.mod(15); // 15
range.mod(89352); // 72

---

Range.prototype.slice()

Slices range into the provided number of equal parts. Returns array of numbers representing starting boundaries of each such slice.

Parameter	Type	Default value	Notes
parts	number		Cannot be negative number

const range = new Range(359);
range.slice(6); // [0, 60, 120, 180, 240, 300]
range.slice(9); // [0, 40, 80, 120, 160, 200, 240, 280, 320]
range.slice(12); // [0, 30, 60, 90, 120, 150, 180, 210, 240, 270, 300, 330]