string-overlap-one-on-another^1.6.0

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

Install via npm

npm i string-overlap-one-on-another

The default is exported, so instead of overlap below, you can name the consumed function however you want.

Consume via a require():

const overlap = require("string-overlap-one-on-another");

or as an ES Module:

import overlap from "string-overlap-one-on-another";

Install as a script, via CDN

Put this in your HTML:

<script src="https://cdn.jsdelivr.net/npm/string-overlap-one-on-another/dist/string-overlap-one-on-another.umd.js">

Then, you’ll get a global variable stringOverlapOneOnAnother in your Global object and you consume it like this:

const overlap = stringOverlapOneOnAnother;

This overlap is your main function. See its API in the main section.

Trivia

This program has 41 assertions in its unit tests. That's less than all unit test assertions' median (50) and less than geometric mean (70).

§ Quick Take

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

assert.equal(
  overlap("aaa", "bbb", { offset: -2 }),
  "bbbaa"
);

⬆ back to top

§ Examples

program example: Empty Strings

⬆ back to top

§ Idea

In essence,

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

⬆ back to top

§ API

overlap(str1, str2, [opts])

§ API - Input

API for both methods is the same:

Input argument	Type	Obligatory?	Description
`str1`	String	yes	The string which will be put "under" `str2`
`str2`	String	yes	The string which will be put "over" `str1`
`opts`	Plain object	no	An Optional Options Object. See its API below, in a separate table.

⬆ back to top

§ Optional Options Object

Optional Options Object's key	Type of its value	Default	Description
`offset`	Positive or negative integer or zero	`0`	It 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.
`offsetFillerCharacter`	String	`` (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)
}

⬆ back to top

§ Edge cases

The algorithm is the following:

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

⬆ back to top