ranges-process-outside5.0.1

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 argument Type Obligatory? Description
originalStr string yes Source string
originalRanges null or ranges - array of arrays yes String indexes outside these ranges will be processed (fed to callback function)
cb function yes Callback function you provide (like in Array.forEach)
skipChecks boolean no By 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 argument Type Description
fromIdx String index: natural number or zero Starting index of the chunk programs pings you
toIdx String index: natural number or zero Ending index of the chunk programs pings you
offsetValueCb Function or something falsy Callback 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-crop 5.0.1
Crop array of ranges when they go beyond the reference string's length
📦 ranges-is-index-within 3.0.1
Checks if index is within any of the given string index ranges
📦 ranges-regex 5.0.1
Integrate regex operations into Ranges workflow
📦 ranges-invert 5.0.1
Invert string index ranges
📦 ranges-apply 6.0.1
Take an array of string index ranges, delete/replace the string according to them
📦 ranges-ent-decode 5.0.1
Recursive HTML entity decoding for Ranges workflow
📦 ranges-iterate 3.0.1
Iterate a string and any changes within given string index ranges