string-split-by-whitespace^4.2.6

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

Permalink to InstallationInstallation

Permalink to Quick TakeQuick Take

Permalink to ExamplesExamples

• Exclude a template variable range from the returned words
• Split on line breaks, tabs, and repeated spaces

Purpose

Split a string into whitespace-separated tokens while excluding specified substrings. Use ignoreRanges to omit template delimiters, complete variables, or other spans that must not appear in the result.

Whitespace follows native String.prototype.trim() semantics, including spaces, tabs, CR/LF line breaks, non-breaking spaces, and other Unicode whitespace. Empty tokens are omitted.

API — splitByW()

The main function splitByW() is imported like this:

The function takes a string and an optional options object:

Here are all defaults in one place for copying:

The function returns an array of strings. Empty or whitespace-only input returns [].

opts.ignoreRanges

Each [from, to] range uses UTF-16 indices into the original input. The start is inclusive and the end is exclusive, matching String.prototype.slice(). An ignored span separates tokens on its two sides, even when no whitespace separates them.

import { splitByW } from "string-split-by-whitespace";

splitByW("abc", { ignoreRanges: [[1, 2]] });
// => ["a", "c"]

splitByW("ab cd", { ignoreRanges: [[1, 4]] });
// => ["a", "d"]

splitByW("a b", { ignoreRanges: undefined });
// => ["a", "b"]

Ranges can arrive in any order. Overlapping or adjacent ranges exclude their combined span, and empty ranges exclude nothing. The function leaves the supplied array and its ranges unchanged. It prepares their order once and advances through the input and ranges together.

A template’s head and tail are its opening and closing delimiters. In Hi {{ firstName }}!, the ranges of {{ and }} are [[3, 5], [16, 18]]:

import { splitByW } from "string-split-by-whitespace";

splitByW("Hi {{ firstName }}!", {
  ignoreRanges: [[3, 5], [16, 18]],
});
// => ["Hi", "firstName", "!"]

Use string-find-heads-tails to locate delimiters, then convert its results into ranges. Ignoring the delimiters preserves the variable contents:

import { strFindHeadsTails } from "string-find-heads-tails";
import { splitByW } from "string-split-by-whitespace";

const input = "some interesting {{text}} {% and %} {{ some more }} text.";
const matches = strFindHeadsTails(input, ["{{", "{%"], ["}}", "%}"]);
const headsAndTails = matches.reduce((ranges, match) => {
  ranges.push([match.headsStartAt, match.headsEndAt]);
  ranges.push([match.tailsStartAt, match.tailsEndAt]);
  return ranges;
}, []);

splitByW(input, { ignoreRanges: headsAndTails });
// => ["some", "interesting", "text", "and", "some", "more", "text."]

To omit complete variables, create one range from each head’s start to its tail’s end. Continuing the example above:

const wholeVariables = matches.map((match) => [
  match.headsStartAt,
  match.tailsEndAt,
]);

splitByW(input, { ignoreRanges: wholeVariables });
// => ["some", "interesting", "text."]

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-split-by-whitespace";

Permalink to changelogChangelog