ranges-apply^3.2.4

Take an array of string index ranges, delete/replace the string according to them

Install via npm

npm i ranges-apply

The default is exported, so instead of applyR below, you can name the consumed function however you want.

Consume via a require():

const applyR = require("ranges-apply");

or as an ES Module:

import applyR from "ranges-apply";

Install as a script, via CDN

Put this in your HTML:

<script src="https://cdn.jsdelivr.net/npm/ranges-apply/dist/ranges-apply.umd.js">

Then, you’ll get a global variable rangesApply in your Global object and you consume it like this:

const applyR = rangesApply;

This applyR is your main function. See its API in the main section.

Learn more about Ranges

We have a dedicated page about Ranges. Learn more

Trivia

This program has 87 assertions in its unit tests. That's more than all unit test assertions' median (51.5) and more than geometric mean (73).

In monorepo, 16 other packages consume this package.

§ Quick Take

import { strict as assert } from "assert";
import applyR from "ranges-apply";

const oldString = `The quick brown fox jumps over the lazy dog.`;
const ranges = [
  [4, 19, "bad grey wolf"],
  [35, 43, "little Red Riding Hood"],
];
assert.equal(
  applyR(oldString, ranges),
  "The bad grey wolf jumps over the little Red Riding Hood."
);

⬆ back to top

§ Purpose

It takes the source string and the amendments described by Ranges and produces a new string.

⬆ back to top

§ API

applyR(
  inputString,
  rangesArray,
  [progressFn]
)

Input argument	Type	Obligatory?	Description
`inputString`	String	yes	Provide an array of ranges to invert. Ranges do not have to be sorted or merged.
`rangesArray`	Array of zero or more arrays - OR - `null`	yes	Ranges to apply onto the string
`progressFn`	Function or something falsy	no	Provide a callback function to report the progress - numbers `0` to `100` will be fed into it as the program advances.

§ API - Output

Function returns an amended string.

⬆ back to top

Check out ranges-push which helps to manage the rangesArray. It has methods to add and retrieve the ranges. Also, it helps in cases where ranges overlap and helps to maintain the sorting order.

§ The algorithm

We array.reduce() your given ranges array, slicing the input string accordingly. If given ranges is not array but null (meaning absence of ranges), same string is returned.

The main thing is unit tests and edge case scenarios. Also, fancy optional features (upcoming) like using character enumeration counting emoji as one character.

⬆ back to top

§ In our case

Originally this library was part of email-comb, where we traversed HTML as a string and compiled an array of things to delete or replace later, in one go. The performance was important, so it was not a good idea to delete/replace things on the spot because each deletion slowed down the process. Instead, we traversed the string, compiled this to-do array, then did the deletion/replacement on the whole thing, once. This appears to be the fastest way.

We're going to use this library in all our HTML processing libraries who work on HTML as on string, without parsing it.

⬆ back to top