ranges-apply^7.2.3

Permalink to InstallationInstallation

Permalink to Quick TakeQuick Take

Permalink to ExamplesExamples

• Delete a range by omitting its replacement value
• Insert text with a zero-width range
• Apply and merge numeric replacement values
• Apply ranges whose indexes arrive as numeric strings
• Gather progress while applying multiple ranges

API — rApply()

The main function rApply() is imported like this:

This function takes two required arguments and one optional progress callback:

rApply() returns the amended string. It does not mutate the supplied range arrays.

Each range has one of these forms:

• [from, to] deletes str.slice(from, to).
• [from, to, replacement] replaces that slice. Equal indexes create an insertion.

Indexes can be non-negative integers or numeric strings containing non-negative integers. from must not be greater than to; reversed ranges throw a RangeError. A replacement can be a string, a number, null, or undefined. Numeric zero is preserved and renders as "0". When overlapping ranges contain numeric replacements, two numbers are added; if either value is a string, the values are concatenated in range order.

The supported no-op values for progressFn are undefined, null, false, 0, and "". Other non-function values are rejected.

Tip: Use ranges-push to collect and manage ranges before applying them. It handles overlap and sorting while ranges are accumulated.

API — version

You can import version:

API — types

This package is written in TypeScript and exports the following types:

import type {
  ProgressFn,
  ProgressInput,
  Range,
  RangeInput,
  Ranges,
  RangesInput,
} from "ranges-apply";

The algorithm

rApply() validates and normalizes the supplied ranges, then delegates sorting and overlap resolution to ranges-merge. It assembles the result from slices of the original string, so all edits are applied in one pass. If the second argument is null, an empty array, or an array containing only nullish members, the original string is returned.

In our case

This library originated in email-comb. That package scans HTML as a string and records the slices to delete or replace. Applying the collected edits once avoids repeatedly rebuilding the string during the scan.

The same approach is useful in HTML-processing libraries that operate directly on source text without parsing it into a document tree.

Permalink to changelogChangelog