Add unlerp() as inverse of lerp()

Author: danburzo

docs/api.md

@@ -100,6 +100,7 @@ codebase: 'https://github.com/evercoder/culori/blob/main'
 <li><a href='#color-spaces'>rgb</a></li>
 <li><a href='#round'>round</a></li>
 <li><a href='#samples'>samples</a></li>
+<li><a href='#unlerp'>unlerp</a></li>
 <li><a href='#useMode'>useMode</a></li>
 <li><a href='#wcagContrast'>wcagContrast</a></li>
 <li><a href='#wcagLuminance'>wcagLuminance</a></li>
@@ -838,6 +839,12 @@ lerp(5, 10, 0.5);
 // ⇒ 7.5
 ```
 
+<a id="unlerp" href="#unlerp">#</a> **unlerp**(_a_, _b_, _v_) → _value_
+
+<span aria-label='Source:'>☞</span> [src/interpolate/lerp.js]({{codebase}}/src/interpolate/lerp.js)
+
+Returns the point `t` at which the value `v` is located between the values `a` and `b`. The inverse of `lerp`.
+
 ### Mappings
 
 <a id="mapper" href="#mapper">#</a> **mapper**(_fn_, _mode = "rgb"_) → _function (color | string)_

src/deficiency.js

@@ -1,6 +1,6 @@
 import converter from './converter.js';
 import prepare from './_prepare.js';
-import lerp from './interpolate/lerp.js';
+import { lerp } from './interpolate/lerp.js';
 
 let rgb = converter('rgb');
 

src/filter.js

@@ -1,11 +1,12 @@
 import { mapper, mapTransferLinear } from './map.js';
 import converter from './converter.js';
 import prepare from './_prepare.js';
-import lerp from './util/lerp.js';
 import { getMode } from './modes.js';
 
 const minzero = v => Math.max(v, 0);
 const clamp = v => Math.max(Math.min(v, 1), 0);
+const lerp = (a, b, t) =>
+	a === undefined || b === undefined ? undefined : a + t * (b - a);
 
 const matrixSepia = amount => {
 	let a = 1 - clamp(amount);

src/index-fn.js

@@ -93,7 +93,7 @@ export {
 	interpolatorSplineMonotoneClosed
 } from './interpolate/splineMonotone.js';
 
-export { default as lerp } from './interpolate/lerp.js';
+export { lerp, unlerp } from './interpolate/lerp.js';
 export { default as samples } from './samples.js';
 export { default as displayable } from './displayable.js';
 export { clampRgb, clampChroma } from './clamp.js';

src/index.js

@@ -94,7 +94,7 @@ export {
 	interpolatorSplineMonotoneClosed
 } from './interpolate/splineMonotone.js';
 
-export { default as lerp } from './interpolate/lerp.js';
+export { lerp, unlerp } from './interpolate/lerp.js';
 export { default as samples } from './samples.js';
 export { default as displayable } from './displayable.js';
 export { clampRgb, clampChroma } from './clamp.js';

src/interpolate/lerp.js

@@ -1,3 +1,4 @@
 const lerp = (a, b, t) => a + t * (b - a);
+const unlerp = (a, b, v) => (v - a) / (b - a);
 
-export default lerp;
+export { lerp, unlerp };

src/interpolate/linear.js

@@ -1,4 +1,4 @@
-import lerp from './lerp.js';
+import { lerp } from './lerp.js';
 import { interpolatorPiecewise } from './piecewise.js';
 
 export const interpolatorLinear = interpolatorPiecewise(lerp);

src/util/lerp.js

@@ -208,6 +208,7 @@ const API_FULL = [
 	'serializeHex8',
 	'serializeHsl',
 	'serializeRgb',
+	'unlerp',
 	'useMode',
 	'useParser',
 	'wcagContrast',
@@ -442,6 +443,7 @@ const API_FN = [
 	'serializeHex8',
 	'serializeHsl',
 	'serializeRgb',
+	'unlerp',
 	'useMode',
 	'useParser',
 	'wcagContrast',

test/api.test.js

@@ -0,0 +1,12 @@
+import tape from 'tape';
+import { lerp, unlerp } from '../src/index.js';
+
+tape('lerp()', t => {
+	t.equal(lerp(10, 2, 0.5), 6);
+	t.end();
+});
+
+tape('unlerp()', t => {
+	t.equal(unlerp(5, 10, 2.5), -0.5);
+	t.end();
+});