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 GitHub.

§ Contributing

To report bugs or request features or assistance, raise an issue on GitHub opens in a new tab.

Any code contributions welcome! All Pull Requests will be dealt promptly.

§ Licence

MIT opens in a new tab

Copyright © 2010–2021 Roy Revelt and other contributors

Related packages:

📦 detergent 7.0.14
Extracts, cleans and encodes text
📦 string-unfancy 4.0.14
Replace all n/m dashes, curly quotes with their simpler equivalents
📦 string-uglify 1.4.14
Shorten sets of strings deterministically, to be git-friendly
📦 string-range-expander 2.0.14
Expands string index ranges within whitespace boundaries until letters are met
📦 string-apostrophes 1.4.14
Comprehensive, HTML-entities-aware tool to typographically-correct the apostrophes and single/double quotes
📦 string-remove-thousand-separators 5.0.14
Detects and removes thousand separators (dot/comma/quote/space) from string-type digits
📦 string-trim-spaces-only 3.0.14
Like String.trim() but you can choose granularly what to trim