@rnacanvas/math

Installation

With npm:

npm install @rnacanvas/math

Usage

All exports of this package can be accessed as named imports.

// some example imports
import { min, max } from '@rnacanvas/math';
import { mean, median } from '@rnacanvas/math';
import { sortNumbers, sortedNumbers } from '@rnacanvas/math';

How to pass collections of numbers as parameters

In general throughout this package collections of numbers are passed to functions/methods in the form of iterable objects (e.g., an array), as opposed to argument lists.

sum([1, 2, 3, 4, 5]); // do this
sum(1, 2, 3, 4, 5); // NOT this

This decision was made due to the limit on how many arguments can possibly be passed to a function in JavaScript on the stack (often only in the 10's of thousands), while numbers passed in as arrays are limited only by the total memory available.

function distance()

Returns the distance (i.e., the absolute difference) between two numbers.

distance(-1, 8); // 9

// order doesn't matter
distance(8, -1); // 9

function sum()

Calculates the sum of an array of numbers. Returns 0 for an empty array of numbers.

sum([]); // 0
sum([4]); // 4
sum([5, 10, -2, 23, -54]); // -18

function mean()

Calculates the mean of an array of numbers. Returns NaN for an empty array of numbers.

mean([]); // NaN
mean([18]); // 18
mean([8, 2, -20, 16, 54]); // 12

function average()

An alias for the mean() function.

function median()

Returns the median of an array of numbers. If there an even number of numbers, then the average of the middle two numbers is returned. Returns NaN for an empty array of numbers.

median([]); // NaN
median([6]); // 6
median([11, 17]); // 14
median([4, -9, 28, 22, 9, 7, -3]); // 7

function min()

Returns the minimum of an array of numbers. Returns Infinity for an empty array of numbers.

min([]); // Infinity
min([57]); // 57
min([5, 9, -12, 18, -19, 24]); // -19

function max()

Returns the maximum of an array of numbers. Returns -Infinity for an empty array of numbers.

max([]); // -Infinity
max([-84]); // -84
max([18, 1, 55, -28, 19.4]); // 55

function isBetween()

Returns true if and only if a number is within a specified range, inclusive.

isBetween(n, floor, ceiling); // usage

isBetween(6, 7, 9); // false
isBetween(7, 7, 9); // true
isBetween(8, 7, 9); // true
isBetween(9, 7, 9); // true
isBetween(10, 7, 9); // false

function isBetweenInclusive()

An alias for the isBetween() function.

function isBetweenExclusive()

Returns true if and only if a number is within a specified range, exclusive.

isBetweenExclusive(n, floor, ceiling); // usage

isBetweenExclusive(6, 7, 9); // false
isBetweenExclusive(7, 7, 9); // false
isBetweenExclusive(8, 7, 9); // true
isBetweenExclusive(9, 7, 9); // false
isBetweenExclusive(10, 7, 9); // false

function clamp()

Clamp a number to a given range.

clamp(n, floor, ceiling); // usage

clamp(2, 5, 10); // 5
clamp(18, 5, 10); // 10
clamp(6, 5, 10); // 6 (is already in range)

function areWithin()

Returns true if two numbers are within a specified distance from each other.

areWithin(n1, n2, maxDifference); // usage

areWithin(5, 5, 0); // true
areWithin(5, 5, 2); // true
areWithin(5, 6, 2); // true
areWithin(5, 7, 2); // true
areWithin(5, 8, 2); // false

function sortNumbers()

Sorts an array of numbers in place in ascending order.

var ns = [8, -3, 55, 24, 39];
sortNumbers(ns);
ns; // [-3, 8, 24, 39, 55]

function sortNumbersAscending()

An alias for the sortNumbers() function.

function sortNumbersDescending()

Sorts an array of numbers in place in descending order.

var ns = [9, 27, -84, 0, -19];
sortNumbersDescending(ns);
ns; // [27, 9, 0, -19, -84]

function sortedNumbers()

Returns a copy of an array of numbers sorted in ascending order. Does not modify the input array of numbers.

sortedNumbers([5, 28, -44, 2, -1]); // [-44, -1, 2, 5, 28]

function sortedNumbersAscending()

An alias for the sortedNumbers() function.

function sortedNumbersDescending()

Returns a copy of an array of numbers sorted in descending order. Does not modify the input array of numbers.

sortedNumbersDescending([6, 2, 91, -15, 25]); // [91, 25, 6, 2, -15]

function round()

Rounds a number to the specified number of decimal places (rounds to zero decimal places by default).

Number of decimal places must be between 0 and 20, inclusive. (This function will throw otherwise.)

// round to 2 decimal places
round(1.2583, 2); // 1.26

// round to 3 decimal places
round(10.713414, 3); // 10.713

// rounds to 0 decimal places by default
round(-8.7827); // -9

// explicitly round to 0 decimal places
round(-8.7827, 0); // -9

function degrees()

Convert a given angle in radians to degrees.

degrees(Math.PI); // 180
degrees(-Math.PI); // -180

degrees(Math.PI / 3); // 60
degrees(-11 * Math.PI / 4); // -495

function radians()

Convert a given angle in degrees to radians.

radians(180); // Math.PI
radians(-180); // -Math.PI

radians(60); // Math.PI / 3
radians(-495); // -11 * Math.PI / 4

function normalizeAngle()

Normalize an angle (in radians) to a given range.

By default, normalizes angles to the range [-Math.PI, Math.PI), which is the default range returned by methods such as Math.atan2().

The range to normalize to is indicated by specifying a second floor argument, which is the bottom end (inclusive) of the range to normalize to.

normalizeAngle((Math.PI / 3) + (12 * Math.PI)); // Math.PI / 3

// normalizes to the range [-Math.PI, Math.PI) by default
normalizeAngle(3 * Math.PI / 2); // -Math.PI / 2

// normalize angles to the range [0, 2 * Math.PI) instead
// (by passing in a second "floor" argument of zero)
normalizeAngle(3 * Math.PI / 2, 0); // 3 * Math.PI / 2

// the second "floor" argument can be any angle
normalizeAngle(Math.PI, -14 * Math.PI); // Math.PI - (14 * Math.PI)

function flipAway()

Flip an angle (i.e., add 180 degrees to it) if it is within 90 degrees of another angle.

Otherwise, the flipAway() function returns the angle unchanged.

Angles input to the flipAway() function and the angle returned by the flipAway() function are all expressed in radians.

// Math.PI / 3 is within 90 degrees of 0
flipAway(Math.PI / 3, 0); // 4 * Math.PI / 3

// 4 * Math.PI / 3 is already more than 90 degrees away from 0
flipAway(4 * Math.PI / 3, 0); // 4 * Math.PI / 3