ranges-process-outside4.0.14

Iterate string considering ranges, as if they were already applied

§ Quick Take

import { strict as assert } from "assert";
import { rProcessOutside } from "ranges-process-outside";

const gathered = [];

// a callback interface:
rProcessOutside(
  "abcdefghij",
  [
    [1, 5], // delete from "b" to "f"
  ],
  (fromIdx, toIdx, offsetValueCb) => {
    gathered.push(fromIdx);
  }
);

assert.deepEqual(gathered, [0, 5, 6, 7, 8, 9]);

§ Purpose

Processes the string outside the given ranges. Each "gap" in the string between ranges will be fed into callback you supply — same like in Array.prototype.forEach().

This program makes the life easier because if you did it manually, you'd have to invert ranges and loop over each inverted chunk. Finally, you'd have to write unit tests of all that.

§ API

rProcessOutside(
  originalStr, 
  originalRanges, 
  cb, 
  [skipChecks]
)

In other words, it's a function which takes 4 arguments:

Input argumentTypeObligatory?Description
originalStrstringyesSource string
originalRangesnull or ranges - array of arraysyesString indexes outside these ranges will be processed (fed to callback function)
cbfunctionyesCallback function you provide (like in Array.forEach)
skipChecksbooleannoBy default checks are performed upon inputs but you can turn that off to boost the performance

§ Callback cb

This program operates in a callback fashion, just like Array.prototype.forEach(), for example:

const { rProcessOutside } = require("ranges-process-outside");
const gather = [];
rProcessOutside(
"abcdefghij",
[[0, 5]],
(idx) => {
gather.push(idx);
}
);
console.log(gather);
// => [5, 6, 7, 8, 9]

This (idx) => { gather.push(idx); } above is the callback function (as arrow opens in a new tab-function).

It's API is the following:

Input argumentTypeDescription
fromIdxString index: natural number or zeroStarting index of the chunk programs pings you
toIdxString index: natural number or zeroEnding index of the chunk programs pings you
offsetValueCbFunction or something falsyCallback function to bump the indexes in the loop that pings you all this. See below for more.

§ offsetValueCb API

A callback inside a callback!

offsetValueCb argument the cb() gives you is a function. Call it with a single argument, a natural number — that will instruct the outer loop function to skip that many characters.

For example, skip one character:

const { rProcessOutside } = require("ranges-process-outside");
const gather = [];
rProcessOutside(
"abcdefghij",
[[0, 5]],
(fromIdx, toIdx, offsetValueCb) => {
gather.push(fromIdx);
if (fromIdx === 6) {
// at index 6, skip the next index:
offsetValueCb(1);
}
}
);
console.log(gather);
// => [5, 6, 8, 9]
// notice 7 is missing because we skipped by 1 while being at index 6

The third argument in the callback cb (the arrow function (fromIdx, toIdx, offsetValueCb) => {...} above) is a function which lets you bump the looping index. This way, you can skip the characters being pinged.

For example, Detergent processes HTML code. A string with bunch of invisible characters are detected and their from-to ranges are pushed to ranges being gathered. While processing the input further, Detergent avoids processing the characters booked for deletion (marked by ranges). It uses this program to work on everything in-between the ranges (invisible character locations). Now, Detergent detects a named HTML entity:  . Once it stumbles on its first character, the ampersand &, it does what it has to do and it needs to skip 6 characters further.

This skipping is performed by this callback.

§ 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-ent-decode 4.0.14
Recursive HTML entity decoding for Ranges workflow
📦 ranges-regex 4.0.14
Integrate regex operations into Ranges workflow
📦 ranges-push 5.0.14
Gather string index ranges
📦 ranges-merge 7.0.14
Merge and sort string index ranges
📦 ranges-sort 4.0.14
Sort string index ranges
📦 ranges-is-index-within 2.0.14
Checks if index is within any of the given string index ranges
📦 ranges-crop 4.0.14
Crop array of ranges when they go beyond the reference string's length