ranges-is-index-within1.15.2

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

§ 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
);

§ Purpose

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

§ API - Input

Input argumentTypeObligatory?Description
indexNatural numberyesThe natural number index you're checking
rangesArrArray of zero or more arrays or nullyesArray of ranges, for example, [ [1, 5], [10, 20] ]
optionsPlain objectnoOptional options object. See below for its API.

A wrong type will cause throws.

§ Options object

options object's keyType of its valueDefaultDescription
inclusiveRangeEndsBooleanfalseThat 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.
returnMatchedRangeInsteadOfTrueBooleanfalseIf 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.

§ 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.

§ 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.

§ The algorithm

We tried Binary Search algorithmopens in a new tab but native Array.prototype.find()/Array.prototype.some() are around 85x faster.

§ Licence

MITopens in a new tab

Copyright © 2010–2020 Roy Revelt and other contributors

Related packages:

📦 ranges-invert 2.1.49
Invert string index ranges
📦 ranges-crop 2.1.3
Crop array of ranges when they go beyond the reference string's length
📦 ranges-sort 3.13.3
Sort string index ranges
📦 ranges-process-outside 2.2.35
Iterate string considering ranges, as if they were already applied
📦 ranges-ent-decode 2.1.3
Recursive HTML entity decoding for Ranges workflow
📦 ranges-apply 3.2.3
Take an array of string index ranges, delete/replace the string according to them
📦 ranges-iterate 1.1.48
Iterate a string and any changes within given string index ranges