ranges-regex^2.1.3

Integrate regex operations into Ranges workflow

Install globally, via npm

npm i ranges-regex

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

Consume via a require():

const raReg = require("ranges-regex");

or as an ES Module:

import raReg from "ranges-regex";

Install as a script, via CDN

Put this in your HTML:

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

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

const raReg = rangesRegex;

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

§ Quick Take

import { strict as assert } from "assert";
import raReg from "ranges-regex";

const oldString = `The quick brown fox jumps over the lazy dog.`;
const result = raReg(/the/gi, oldString);

// all regex matches, but in Ranges notation (see codsen.com/ranges/):
assert.deepEqual(result, [
  [0, 3],
  [31, 34],
]);

// if you slice the ranges, you'll get original regex caught values:
assert.deepEqual(
  result.map(([from, to]) =>
    oldString.slice(from, to)
  ),
  ["The", "the"]
);

⬆ back to top

§ Purpose

Takes a string, matches the given regex on it and returns ranges which would do the same thing.

Similarly to String.prototype.match(), a no-results case will yield null (which ranges-merge and others would gladly accept).

⬆ back to top

§ API

raReg(regexp, str, [replacement])

In other words, it's a function which takes three input arguments, third one is optional (marked with square brackets).

Input argument	Type	Obligatory?	Description
`regexp`	Regular expression	yes	Provide the regexp to apply onto a string
`str`	String	yes	Provide a string upon which to match the regex
`replacement`	String or `null`	no	If you want to add a third argument on every of the finding's third argument values, put it here.

Output: array of zero or more arrays (so-called ranges) where each consists of two or more natural number (or zero) indexes OR null.

This package does not mutate its inputs.

If the input arguments' types are incorrect or absent, library will throw an error.

⬆ back to top

§ Examples

Nothing to find:

// nothing to find:
console.log(raReg(/yyy/g, "zzzzzzzz"));
// => null

// stick `null` to add onto every of the findings:
const res = raReg(/def/g, "abcdefghij_abcdefghij", null);
console.log(JSON.stringify(res, null, 4));
// => [[3, 6, null], [14, 17, null]]

Notice, you can use all the features of regexes: global, case insensitive flags and so on.

PS. Be careful not to signify the intention to omit the third argument by setting it to null. The null is a valid value in ranges ecosystem and it is used in ranges to "kill off" any present insertion values. For example, you merge two ranges and one says "add this" (in a form of third argument) and second says, disregard all that content to add, here's null to defuse them for good.

⬆ back to top