Package Exports

string-overlap-one-on-another

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (string-overlap-one-on-another) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

string-overlap-one-on-another

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

Install
Idea
API
Practical use
Edge cases
Contributing
Licence

Install

npm i string-overlap-one-on-another

// consume via a require():
const overlap = require("string-overlap-one-on-another");
// or as a ES Module:
import overlap from "string-overlap-one-on-another";

Here's what you'll get:

Type	Key in `package.json`	Path	Size
Main export - CommonJS version, transpiled to ES5, contains `require` and `module.exports`	`main`	`dist/string-overlap-one-on-another.cjs.js`	3 KB
ES module build that Webpack/Rollup understands. Untranspiled ES6 code with `import`/`export`.	`module`	`dist/string-overlap-one-on-another.esm.js`	3 KB
UMD build for browsers, transpiled, minified, containing `iife`'s and has all dependencies baked-in	`browser`	`dist/string-overlap-one-on-another.umd.js`	28 KB

⬆ back to top

Idea

Place one string "on top" of another:

const str1 = "aaa";
const str2 = "bbb";
const result = overlap(str1, str2, { offset: -2 });
console.log(
  `${`\u001b[${33}m${`result`}\u001b[${39}m`} = ${JSON.stringify(
    result,
    null,
    4
  )}`
);
// result = "bbbaa"

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

Practical use

It will be used in ranges-recursive-resolve when calculating the third argument's value ("string to be added") when two or more ranges clash and all have third arguments. Recursive resolve "joins" two ranges applied on the same string, performed over time. One range "changes" the string and then another range changes the previous result further. When multiple ranges insert or replace character range with some string, two such "replacements" are the same as laying one on top of another. Precisely what this library does.

See other range libraries here: https://bitbucket.org/account/user/codsen/projects/RNG

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

Practically,

const res = overlap("", "456", { offset: 99, offsetFillerCharacter: "zzzz" });
console.log(`res = ${res}`);
// => res = "456"

Consider the sample above - even though offset is long enough to warrant the filler, no characters are added to the str2, 456 because the first argument, str1 is empty.

⬆ back to top

Contributing

If you want a new feature in this package or you would like us to change some of its functionality, raise an issue on this repo.
If you tried to use this library but it misbehaves, or you need advice setting it up, and its readme doesn't make sense, just document it and raise an issue on this repo.
If you would like to add or change some features, just fork it, hack away, and file a pull request. We'll do our best to merge it quickly. Prettier is enabled, so you don't need to worry about the code style.

⬆ back to top

Licence

MIT License (MIT)