+# String Lerp
+
+This is a library to linearly interpolate between two string values,
+that is, progressively turn one string into another. It implements
+several ways to do this, and can automatically pick the best one based
+on the strings given to it.
+
+For example, it knows:
+
+* "explore" is between "implore" and "explode".
+* Or conversely, "implode" between "explode" and "implore".
+* "chicken wing" and "buffalo wing" are actually the same "wing".
+* Likewise, "apple core" and "core dump" can keep the "core".
+* 1/3 of the way from "0%" to "100%" is "33%".
+* Halfway between rgb(255, 0, 0) and rgb(0, 0, 255) is rgb(128, 0, 128).
+ (Well, it's good at strings, not color science.)
+
+To try more, open up [demo.html] in your browser.
+
+## Setting Up
+
+Include the following in your HTML:
+
+ <script type="text/javascript" src="string-lerp.js"></script>
+
+Then, you can use `window.stringLerp` (or just `stringLerp`).
+
+Or if you're using Node or some other non-browser whatever,
+
+ var stringLerp = require("./string-lerp");
+
+If you want a minified version, at a shell run
+
+ $ make ugly
+
+If you think something's wrong, or make changes, run
+
+ $ make check
+
+(Running these will also download modules from [NPM].)
+
+## API
+
+### stringLerp.lerp(a, b, p)
+
+Interpolate between strings a and b, given a parameter p.
+
+This automatically picks the best interpolator based on the strings
+provided. If the strings are identical aside from numbers in them,
+they are passed through `numericLerp`.
+
+If the strings are not numbers and short, they are passed through
+`diffLerp`.
+
+Otherwise, they are passed through `fastLerp`.
+
+
+### stringLerp.numericLerp(a, b, p)
+
+Lerp all the numbers in the string from their values in `a` to their
+values in `b`.
+
+Numbers may have a leading `-` and a single `.` to mark the decimal
+point, but something must be after the `.`. If both of the numbers in
+a pair are integers, the result is clamped to an integer.
+
+For example, `numericLerp("0.0", "100", 0.123) === "12.3"` because the
+`.` in `0.0` is interpreted as a decimal point.
+
+But `numericLerp("0.", "100.", 0.123) === "12."` because the strings
+are interpreted as integers followed by a full stop.
+
+Calling this functions on strings that differ in more than numerals
+gives undefined results.
+
+
+### stringLerp.diffLerp(a, b, p)
+
+Lerp from `a` to `b` based on edit operations.
+
+This interpolation algorithm applys a partial edit of one string into
+the other. This produces nice looking results, but can take a
+significant amount of time and memory to compute the edits. It is not
+recommended for strings longer than a few hundred characters.
+
+
+### stringLerp.fastLerp(a, b, p)
+
+Lerp from `a` to `b` using a simple algorithm based on length.
+
+This interpolation algorithm progressively replaces the front of one
+string with another. This approach is fast but does not look good when
+the strings are similar.
+
+
+### stringLerp.diff(s, t) and stringLerp.patch(edits, s)
+
+These are the functions used to implement `diffLerp`. `diff`
+calculates a series of edit operations - substitutions, insertions,
+and deletions - to turn `s` into `t`.
+
+
+### stringLerp.levenshteinMatrix(s, t, ins, del, sub)
+
+Calculate the edit distance between the source and target sequences,
+and return a matrix representing the possible edits and their
+costs. The matrix returned is a flat typed array.
+
+Because stringLerp needs to be able to reconstruct the edit path, this
+is not an optimal algorithm if you only need the Levenshtein distance.
+
+
+## Unicode Concerns
+
+String Lerp handles Unicode reasonably well. Surrogate pairs are
+recognized and not split, and combining characters stay attached to
+the character they started with. All algorithms will be notably
+slower, and memory-intensive, when given such strings.
+
+Some scripts, such as Hangul and Tamil, do not work ideally.
+Multi-glyph graphemes will be split up, and potentially rejoined,
+during interpolation. The intermediate string is always a valid
+Unicode string containing only glyphs present in one string or the
+other, but the glyphs may be arranged very differently.
+
+A similar problem occurs when switching between LTR and RTL in the
+same string. The codepoints indicating bidi switches may move around
+the string capturing glyphs in ways that are not visually appealing.
+
+
+[NPM]: https://www.npmjs.org/
projects / string-lerp.git / commitdiff