string-overlap-one-on-another^3.0.1

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

Install via npm

npm i string-overlap-one-on-another

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required:

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

If you need a legacy version which works with require, use version 2.1.0:

"string-overlap-one-on-another": "2.1.0",

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"></script>

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

const { overlap } = stringOverlapOneOnAnother;

Trivia

This program has 38 assertions in its unit tests. That's less than all unit test assertions' median (48) 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