ranges-is-index-within3.0.1

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

isIndexWithin(
idx,
ranges,
[opts]
)
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.

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.

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 algorithm opens in a new tab but native Array.prototype.find()/Array.prototype.some() are around 85x faster.

Changelog

See it in the monorepo opens in a new tab, on GitHub.

Contributing

To report bugs or request features or assistance, raise an issue on GitHub opens in a new tab.

Any code contributions welcome! All Pull Requests will be dealt promptly.

Licence

MIT opens in a new tab

Copyright © 2010–2021 Roy Revelt and other contributors

Related packages:

📦 ranges-push 6.0.1
Gather string index ranges
📦 ranges-crop 5.0.1
Crop array of ranges when they go beyond the reference string's length
📦 ranges-invert 5.0.1
Invert string index ranges
📦 ranges-ent-decode 5.0.1
Recursive HTML entity decoding for Ranges workflow
📦 ranges-offset 3.0.1
Increment or decrement each index in every range
📦 ranges-regex 5.0.1
Integrate regex operations into Ranges workflow
📦 ranges-iterate 3.0.1
Iterate a string and any changes within given string index ranges