numeric-wrench 🔧

Number manipulation and math functions.

npm install --save-prod numeric-wrench

📚 API documentation is available here.

Usage

This library contains multiple helper functions:

• Comparators asc desc

• Arrays swap range

• Size-of casting int byte uint unNaN

• Number clamping clamp clamp1 closest cycle snap flip

• Math logx deg rad sq sign trunc

• Checks isBetween isEpsClose isNumeric

• Easing functions easeExp easeLog easeInQuad easeOutQuad easeInOutQuad easeInCubic easeOutCubic easeInOutCubic easeInQuart easeOutQuart easeInOutQuart easeInQuint easeOutQuint easeInOutQuint

Interpolation

lerp

Creates a linear interpolator:

const f = lerp(xs, ys);
const y = f(x);

Here xs is the array of X coordinates of pivot points in ascending order, and ys is the array of corresponding Y coordinates of pivot points.

cspline

Creates a cubic spline interpolator for given pivot points:

const f = cspline(xs, ys);
const y = f(x);

More control over spline caching and computation:

// Pre-allocate an array of spline components that can be later reused
// to avoid excessive memory allocations
const splines = new Float32Array(xs.length * 3);

createCSplines(xs, ys, xs.length, splines); // → splines
// or
// const splines = createCSplines(xs, ys, xs.length); // → Float32Array

const y = interpolateCSpline(xs, ys, x, xs.length, splines);

csplineMonot

Creates a monotone cubic interpolator for given pivot points:

const f = csplineMonot(xs, ys);
const y = f(x);

Or using more fine-grained approach:

const y = interpolateCSplineMonot(xs, ys, x, xs.length, createCSplinesMonot(xs, ys, xs.length));

The plot below shows that cspline interpolation overshoots pivot points while csplineMonot provides monotonous results.

Sort

Non-recursive sorting implementation. In contrast to Array.sort, this function doesn't convert array elements to strings before comparison and uses > and < operators directly. So numeric arrays are sorted in natural order. You can provide an element comparator to change the sorting order.

Provide a swap callback that is invoked when elements are swapped during sorting, this simplifies sorting multiple arrays in parallel.

sort(
    arr, // Mutable array that would be sorted
    (i, j) => {
      // Called when i and j elements of arr were swapped
    },
    (a, b) => 0, // Comparator works the same way as in Array.sort
);

Binary search

Searches the specified array for the specified value using the binary search algorithm. The array must be sorted into ascending order according to the natural ordering of its elements prior to making this call. If it is not sorted, the results are undefined.

Returns the index of the searched value, if it is contained in the array; otherwise, -insertionPoint - 1. The insertion point is defined as the point at which the searched value would be inserted into the array: the index of the first element greater than the searched value, or array length if all elements in the array are less than the specified key. Note that this guarantees that the return value will be ≥ 0 if and only if the searched value is found.

binarySearch([10, 20, 30, 40], 20); // → 1

binarySearch([10, 20, 30, 40], 25); // → -3

Bitwise operations

Bitwise operations left, right, and, or and xor for unsigned integers that exceed 32-bit range:

left(0xAB, 8); // Same as 0xAB << 8
// → 0xAB_00 

left(0xAB_CD_EF_AB_CD, 24)
// → 0xAB_CD_EF_AB_CD_00_00_00

right(0xAB_CD, 8); // Same as 0xAB_CD >> 8
// → 0xAB