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.

§ Licence

MIT opens in a new tab

Copyright © 2010–2020 Roy Revelt and other contributors

Related packages:

📦 detergent 5.11.7
Extracts, cleans and encodes text
📦 string-range-expander 1.11.11
Expands string index ranges within whitespace boundaries until letters are met
📦 string-find-malformed 1.1.16
Search for a malformed string. Think of Levenshtein distance but in search.
📦 string-strip-html 6.0.4
Strips HTML tags from strings. No parser, accepts mixed sources.
📦 string-collapse-white-space 5.2.31
Efficient collapsing of white space with optional outer- and/or line-trimming and HTML tag recognition
📦 string-left-right 2.3.31
Looks up the first non-whitespace character to the left/right of a given index
📦 string-convert-indexes 2.0.2
Convert between native JS string character indexes and grapheme-count-based indexes