ranges-is-index-within open source npm package

Installation

Choose the installation type:

Quick Take

Examples

API — `isIndexWithin()`

The main function isIndexWithin() is imported like this:

It’s a function which takes three input arguments:

Input argument	Type	Obligatory	Description
	`index` Type: Natural number Obligatory: yes
`index`	Natural number	yes	The natural number index you’re checking

	`rangesArr` Type: Array of zero or more arrays or `null` Obligatory: yes
`rangesArr`	Array of zero or more arrays or `null`	yes	Array of ranges, for example, `[ [1, 5], [10, 20] ]`

	`opts` Type: Plain object Obligatory: no
`opts`	Plain object	no	Optional Options Object.

The Optional Options Object has the following shape:

Key	Type	Default	Description
	`inclusiveRangeEnds` Type: Boolean Default: `false`
`inclusiveRangeEnds`	Boolean	`false`	That is, are `1` or `5` considered to be within range `[1, 5]`? The default answer is no, but if set to `true`, the answer would be yes.

	`returnMatchedRangeInsteadOfTrue` Type: Boolean Default: `false`
`returnMatchedRangeInsteadOfTrue`	Boolean	`false`	If set to `true`, instead of result `true` it will return the matched range. `false` is still used as a negative answer. It’s handy when you want to know which range it matched.

Here are all defaults in one place for copying:

The function will return either a boolean, or the matched range (opts.returnMatchedRangeInsteadOfTrue).

If opts.returnMatchedRangeInsteadOfTrue is set to true, positive result will be the range which was matched. Negative result would be still false.

API — `defaults`

You can import defaults:

It's a plain object:

The main function calculates the options to be used by merging the options you passed with these defaults.

API — `version`

You can import version:

API — types

This package is written in TypeScript and exports the following types:

Type	Description
	`Opts` Type: `Opts`
`Opts`	The Optional Options Object of `isIndexWithin()`, documented above.

	`Range` Type: `Range`
`Range`	A single range: a two- or three-element array.

	`Ranges` Type: `Ranges`
`Ranges`	Zero or more `Range`s, or `null`.

import type { Opts, Range, Ranges } from "ranges-is-index-within";

Example

Simple encoding using default settings:

import { isIndexWithin } from "ranges-is-index-within";
let res1 = isIndexWithin(79, [
  [5, 10],
  [15, 20],
  [25, 30],
  [35, 40],
  [45, 50],
  [55, 60],
  [65, 70],
  [75, 80], // <-- "true", - "79" would be within this range, answer is "true"
  [85, 90],
  [95, 100],
  [105, 110],
  [115, 120],
  [125, 130],
]);
console.log(res1);
// > true

let res2 = isIndexWithin(31, [
  [5, 10],
  [15, 20],
  [25, 30], // <-- "false" because "31" falls in between this and next range. It's not within.
  [35, 40],
  [45, 50],
  [55, 60],
  [65, 70],
  [75, 80],
  [85, 90],
  [95, 100],
  [105, 110],
  [115, 120],
  [125, 130],
]);
console.log(res2);
// > false

let res3 = isIndexWithin(
  30,
  [
    [5, 10],
    [15, 20],
    [25, 30], // <-- "true" because opts.inclusiveRangeEnds=true and "30" is on the edge of the range.
    [35, 40],
    [45, 50],
    [55, 60],
    [65, 70],
    [75, 80],
    [85, 90],
    [95, 100],
    [105, 110],
    [115, 120],
    [125, 130],
  ],
  { inclusiveRangeEnds: true },
);
console.log(res3);
// > true

let res4 = isIndexWithin(
  30,
  [
    [5, 10],
    [15, 20],
    [25, 30], // <-- "true" because opts.inclusiveRangeEnds=true and "30" is on the edge of the range.
    [35, 40],
    [45, 50],
    [55, 60],
    [65, 70],
    [75, 80],
    [85, 90],
    [95, 100],
    [105, 110],
    [115, 120],
    [125, 130],
  ],
  { inclusiveRangeEnds: true, returnMatchedRangeInsteadOfTrue: true },
);
console.log(res4);
// > [25, 30]  <------ ! not Boolean, but the range itself.

The algorithm

We tried Binary Search algorithm but native Array.prototype.find()/Array.prototype.some() are around 85x faster.

Changelog

Open Changelog

ranges-is-index-within4.2.0