§ Quick Take

import { strict as assert } from "assert";
import { rIterate } 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:
rIterate(
  "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",
]);

§ 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.

§ API

rIterate(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 argumentTypeObligatory?Description
strstringyesThe input string we are operating on
rangesnull or array of zero or more arrays (ranges)yesThe ranges gathered so far
cbSomething falsy or a functionyesCallback function to be able to consume the indexes and character values
offsetString index, a natural numbernoYou can cut corners and start operations later in the string

§ 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-offset 2.0.14
Increment or decrement each index in every range
📦 ranges-ent-decode 4.0.14
Recursive HTML entity decoding for Ranges workflow
📦 ranges-push 5.0.14
Gather string index ranges
📦 ranges-sort 4.0.14
Sort string index ranges
📦 ranges-crop 4.0.14
Crop array of ranges when they go beyond the reference string's length
📦 ranges-regex 4.0.14
Integrate regex operations into Ranges workflow
📦 ranges-apply 5.0.14
Take an array of string index ranges, delete/replace the string according to them