Lay one string on top of another, with an optional offset

§ Quick Take

import { strict as assert } from "assert";
import overlap from "string-overlap-one-on-another";

  overlap("aaa", "bbb", { offset: -2 }),

§ Examples

§ Idea

In essence,

//           aaa
// + bbb (negative offset of 2 means it's pushed to the left by 2 places)
// --
// = bbbaa


overlap(str1, str2, [opts])

§ API - Input

API for both methods is the same:

Input argumentTypeObligatory?Description
str1StringyesThe string which will be put "under" str2
str2StringyesThe string which will be put "over" str1
optsPlain objectnoAn Optional Options Object. See its API below, in a separate table.

§ Optional Options Object

Optional Options Object's keyType of its valueDefaultDescription
offsetPositive or negative integer or zero0It instructs to offset the top string by this many characters to the right (if a positive number) or to the left (if a negative number). The default value is zero.
offsetFillerCharacterString`` (space)If the offset value (character amount to push left) pushes the str2 outside the boundaries of str1 and not even there's no overlap, but there is a gap, this gap is formed out of these characters. The default is a single space.

Here are all the defaults in one place:

offset: 0, // how many characters str2 is to the right? (negative means it's off to the left)
offsetFillerCharacter: " " // how many characters str2 is to the right? (negative means it's off to the left)

§ Edge cases

The algorithm is the following:

  1. If one and only one of two input strings is zero-long, the other string is returned as a result.
  2. If both input strings are empty, an empty string is returned.
  3. If both input strings are non-empty, the result is second string overlaid on the first, considering the offset.

§ Changelog

See it in the monorepo opens in a new tab, on Sourcehut.

§ Licence

MIT opens in a new tab

Copyright © 2010–2020 Roy Revelt and other contributors

Related packages:

📦 detergent 6.1.1
Extracts, cleans and encodes text
📦 string-extract-class-names 5.10.1
Extract class (or id) name from a string
📦 string-find-heads-tails 3.17.0
Finds where are arbitrary templating marker heads and tails located
📦 string-collapse-white-space 8.0.5
Replace chunks of whitespace with a single spaces
📦 string-convert-indexes 3.0.1
Convert between native JS string character indexes and grapheme-count-based indexes
📦 string-character-is-astral-surrogate 1.11.0
Tells, is given character a part of astral character, specifically, a high and low surrogate
📦 string-split-by-whitespace 1.7.0
Split string into array by chunks of whitespace