ranges-iterate^1.1.48

Iterate a string and any changes within given string index ranges

Install via npm

npm i ranges-iterate

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

Consume via a require():

const iterate = require("ranges-iterate");

or as an ES Module:

import iterate from "ranges-iterate";

Install as a script, via CDN

Put this in your HTML:

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

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

const iterate = rangesIterate;

This iterate 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 139 assertions in its unit tests. That's more than all unit test assertions' median (52) and more than geometric mean (71).

§ Quick Take

import { strict as assert } from "assert";
import iterate from "ranges-iterate";

// Ranges in the following example "punches out" a "hole" from `a` to `g`
// (included), replacing it with `xyz`. That's what gets iterated.

const gathered = [];

// a callback-based interface:
iterate(
  "abcdefghij",
  [[0, 7, "xyz"]],
  ({ i, val }) => {
    gathered.push(`i = ${i}; val = ${val}`);
  }
);

assert.deepEqual(gathered, [
  "i = 0; val = x",
  "i = 1; val = y",
  "i = 2; val = z",
  "i = 3; val = h",
  "i = 4; val = i",
  "i = 5; val = j",
]);

⬆ back to top

§ Quick Take

It iterates all characters in a string, as if given ranges were already applied.

Sometimes certain operations on a string aren't really composable — sometimes we want to traverse the string as if ranges were applied, as if we already had the final result.

⬆ back to top

§ API

iterate(str, ranges, cb, [offset])

In other words, this library gives you a synchronous function (exported as a default) and you must feed three obligatory arguments and fourth, optional (marked with square brackets).

Input argument	Type	Obligatory?	Description
`str`	`string`	yes	The input string we are operating on
`ranges`	`null` or `array` of zero or more arrays (ranges)	yes	The ranges gathered so far
`cb`	Something falsy or a `function`	yes	Callback function to be able to consume the indexes and character values
`offset`	String index, a natural number	no	You can cut corners and start operations later in the string