string-range-expander^4.2.3

No 3rd party dependencies. All dependencies and devDependencies, checked recursively, are Codsen packages.

Permalink to InstallationInstallation

Permalink to Quick TakeQuick Take

Permalink to ExamplesExamples

• Include configured left-side marker characters in the range
• Include a configured right-side marker in the range
• Expand whitespace only on the left side
• Expand whitespace only on the right side
• Request one replacement space when deletion would join words
• Preserve a separator between international words
• Crop tightly when a configured marker appears on the left
• Include all adjacent whitespace on the left
• Include all adjacent whitespace on the right

Purpose

Use this package when a string range needs to include adjacent whitespace or configured marker characters. Give expander() the range you plan to delete or replace, and it returns boundaries that are ready to pass to JavaScript string slicing or a ranges package.

API: expander()

The main function expander() is imported like this:

The function takes one options object:

The options object has the following shape:

from and to use JavaScript’s UTF-16 string offsets. They must be non-negative integers that satisfy 0 <= from <= to <= str.length. The input range is [from, to): from is its inclusive left boundary and expands backward, while to is its exclusive right boundary and expands forward.

str, from, and to are required at the call site. Their entries in the exported defaults object describe the fully resolved internal shape; they do not make those input keys optional.

Marker matching preserves complete Unicode code points, including astral characters. Returned indexes remain UTF-16 offsets, so applying the tuple with String.prototype.slice() does not require index conversion.

Here are all defaults in one place for copying:

The function returns one of these tuples:

• [from, to] contains the expanded, end-exclusive deletion boundaries.
• [from, to, " "] also requests a single-space replacement. The third item appears only when addSingleSpaceToPreventAccidentalConcatenation is enabled, the final range deletes at least one character, both retained boundary characters are non-whitespace, and at least one is a Unicode letter or number. When tight-marker options are set, the replacement space is suppressed if every configured side matches its boundary marker.

For example, pass [12, 14] to a ranges consumer to delete that span. Pass [12, 14, " "] to replace the same span with one space.

Expansion boundaries

Crop markers are consumed even when their run reaches the beginning or end of the string. Ordinary whitespace at the outer edge retains one separator unless the corresponding wipe option is enabled.

import { expander } from "string-range-expander";

expander({
  str: ";x",
  from: 1,
  to: 2,
  ifLeftSideIncludesThisCropItToo: ";",
});
// => [0, 2]

Tight-crop markers must be adjacent to the expanded range or separated from it by the retained whitespace separator. A marker behind retained solid text does not trigger tightening. For example, deleting x from >ax b with > as a left tight-crop marker returns [2, 3], preserving >a b.

One valid tight-crop marker can remove the retained whitespace on both enabled sides. extendToOneSide still prevents movement on the other side.

An empty range inside a word remains empty, including when concatenation prevention is enabled:

expander({
  str: "ab",
  from: 1,
  to: 1,
  addSingleSpaceToPreventAccidentalConcatenation: true,
});
// => [1, 1]

An initially empty range can still expand over adjacent whitespace or crop markers. If the expanded range deletes characters that would join text, the concatenation option can return a replacement space for that final range.

API: defaults

You can import defaults:

It's a plain object:

The main function calculates the options to be used by merging the options you passed with these defaults.

API: version

You can import version:

API: types

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

import type { Opts, Range } from "string-range-expander";

Permalink to changelogChangelog