§ 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 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 but native Array.prototype.find()/Array.prototype.some() are around 85x faster.
§ Changelog
See it in the monorepo , on Sourcehut.
§ Licence
Copyright © 2010–2020 Roy Revelt and other contributors
Related packages:
📦 ranges-offset 1.0.3
Increment or decrement each index in every range
📦 ranges-invert 3.0.2
Invert string index ranges
📦 ranges-apply 4.0.2
Take an array of string index ranges, delete/replace the string according to them
📦 ranges-iterate 1.2.2
Iterate a string and any changes within given string index ranges
📦 ranges-merge 6.2.0
Merge and sort string index ranges
📦 ranges-push 4.0.2
Gather string index ranges
📦 ranges-process-outside 3.0.2
Iterate string considering ranges, as if they were already applied