ranges-is-index-within^1.15.2

Checks if index is within any of the given string index ranges

Install via npm

npm i ranges-is-index-within

The default is exported, so instead of "isIndexWithin" below, you can name the consumed function however you want.

Consume via a require():

const isIndexWithin = require("ranges-is-index-within");

or as an ES Module:

import isIndexWithin from "ranges-is-index-within";

Install as a script, via CDN

Put this in your HTML:

<script src="https://cdn.jsdelivr.net/npm/ranges-is-index-within/dist/ranges-is-index-within.umd.js">

Then, you’ll get a global variable rangesIsIndexWithin in your Global object and you consume it like this:

const isIndexWithin = rangesIsIndexWithin;

This isIndexWithin is your main function. See its API in the main section.

Learn more about Ranges

We have a dedicated page about Ranges. Learn more

Trivia

This program has 267 assertions in its unit tests. That's more than all unit test assertions' median (52) and more than geometric mean (71).

In monorepo, 2 other packages consume this package.

§ Quick Take

import { strict as assert } from "assert";
import isIndexWithin from "ranges-is-index-within";

assert.equal(
  isIndexWithin(8, [
    [1, 2],
    [5, 10],
  ]),
  true
);

assert.equal(
  isIndexWithin(12, [
    [1, 2],
    [5, 10],
  ]),
  false
);

⬆ back to top

§ Purpose

Tells, is a given natural number index within any of the ranges. It's a wrapper on top of Array.prototype.find().

⬆ back to top

§ API - Input

Input argument	Type	Obligatory?	Description
`index`	Natural number	yes	The natural number index you're checking
`rangesArr`	Array of zero or more arrays or null	yes	Array of ranges, for example, `[ [1, 5], [10, 20] ]`
`options`	Plain object	no	Optional options object. See below for its API.

A wrong type will cause throws.

⬆ back to top

§ Options object

options object's key	Type of its value	Default	Description
`inclusiveRangeEnds`	Boolean	`false`	That is, do we consider `1` or `5` to be within range `[1, 5]`? The default answer is no, but if set to `true`, the answer would be yes.
`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.

⬆ back to top

§ API - Output

Boolean true^ or false, answering the question, is the given index found within any of the ranges.

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

⬆ back to top

§ Example

Simple encoding using default settings:

const isIndexWithin = require("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.