ranges-apply

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

Table of Contents

• Install
• Idea
• API
• The algorithm
• In my case
• Contributing
• Licence

Install

npm i ranges-apply

// consume as CommonJS require:
const replaceSlicesArr = require("ranges-apply");
// or as ES Module:
import replaceSlicesArr from "ranges-apply";

Here's what you'll get:

⬆ back to top

Idea

Let's say you want to delete bunch of characters from a string and also to replace some. Technically, this means you need to mark the indexes of the characters where you start deletion and where you end.

For example, in this string, "a" has index 7 and "e" has index 14.

some example text
       ^  || |^ |
0123456789|11|14|
          10|13|16
            12 15

If you want to do something to the word "example" above, that's indexes 5 and 12. You can easily see them if you select the string - good code editors will report the index of the end of the selection in the status bar. Like Atom for example:

That's two numbers to put into an array. They mark a slice of string. Let's add a third element into that array - what to put instead. If it's blank, nothing will be added (it becomes a deletion operation), if it's a non-empty string, it will be inserted insted of the deleted characters (it becomes a replacement operation).

[
  [10, 15], // <-- delete this string slice range
  [18, 20, "replace with this"] // <-- delete from 18th to 20th, then insert string there
];

Now what happens when you have a few slices? You put them into a parent array.

This library consumes such parent array and does the actual job crunching your string according to the list of slices.

Now, let's do it practically. Slice ranges match String.slice() indexing, so you can always check is the slice you want correspond to the indexes you've got.

const repl = require("ranges-apply");
let str = "aaa delete me bbb and me too ccc";
// we preview the slice #1, "delete me", is it actually indexes from 4 to 13:
console.log("slice 1: >>>" + str.slice(4, 13) + "<<<");
// preview slice #2, "and me too", is it actually indexes from 18 to 28:
console.log("slice 2: >>>" + str.slice(18, 28) + "<<<\n");
//
// then instruct this library to replace each with `zzz` and `yyy`:
str = repl(str, [[4, 13, "zzz"], [18, 28, "yyy"]]);
console.log("str = " + str);
// => 'aaa zzz bbb yyy ccc',

If you omit the third argument, that slice will be deleted.

Slice ranges can be the same index. In that case, if there is third argument, its value will be inserted before the string at given index. If there's no third argument, nothing will happen.

⬆ back to top

API

stringReplaceSlicesArray(inputString, rangesArray);

Returns a string with requested slices deleted/replaced.

inputString

Type: string - the string we want to work on.

rangesArray

Type: array - the array of zero or more arrays containing a range and an optional replacement string.

For example,

[
  [10, 15], // <-- deletion
  [18, 20, "replace with this"] // <-- replacement
];

PSST. Check out ranges-push which helps to manage the rangesArray. It has methods to add and retrieve the slices. Also, it helps in cases where slices overlap and helps to maintain the order of index ranges (it always goes from smallest to largest index, everywhere).

⬆ back to top

The algorithm

The plan is simple - we array.reduce your given ranges array, slicing the input string accordingly.

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 my case

Originally this library was part of email-remove-unused-css, where I 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, I 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.

I'm going to use this library in all my HTML processing libraries who work on HTML as on string, without parsing it.

⬆ back to top

Contributing

• If you want a new feature in this package or you would like us to change some of its functionality, raise an issue on this repo.

• If you tried to use this library but it misbehaves, or you need advice setting it up, and its readme doesn't make sense, just document it and raise an issue on this repo.

• If you would like to add or change some features, just fork it, hack away, and file a pull request. We'll do our best to merge it quickly. Prettier is enabled, so you don't need to worry about the code style.

⬆ back to top

Licence

MIT License (MIT)

Copyright © 2018 Codsen Ltd, Roy Revelt