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 see an error, raise an issue.
If you want a new feature but can't code it up yourself, also raise an issue. Let's discuss it.
If you tried to use this package, but something didn't work out, also raise an issue. We'll try to help.
If you want to contribute some code, fork the monorepo via BitBucket, then write code, then file a pull request via BitBucket. We'll merge it in and release.

In monorepo, npm libraries are located in packages/ folder. Inside, the source code is located either in src/ folder (normal npm library) or in the root, cli.js (if it's a command line application).

The npm script "dev", the "dev": "rollup -c --dev --silent" builds the development version retaining all console.logs with row numbers. It's handy to have js-row-num-cli installed globally so you can automatically update the row numbers on all console.logs.

⬆ back to top

Licence

MIT License