@basementuniverse/utils

utils

A small library of useful functions

Usage

Node:

const utils = require('@basementuniverse/utils');

Browser:

<script src="utils.js"></script>

Typescript:

import * as utils from '@basementuniverse/utils';

Contents

Functions

floatEquals(a, b, [p]) ⇒ boolean

Check if two numbers are approximately equal

clamp(a, [min], [max]) ⇒ number

Clamp a number between min and max

frac(a) ⇒ number

Get the fractional part of a number

round(n, [d]) ⇒ number

Round n to d decimal places

lerp(a, b, i) ⇒ number

Do a linear interpolation between a and b

unlerp(a, b, i) ⇒ number

Get the position of i between a and b

blerp(c00, c10, c01, c11, ix, iy) ⇒ number

Do a bilinear interpolation

remap(i, a1, a2, b1, b2) ⇒ number

Re-map a number i from range a1...a2 to b1...b2

smoothstep(a, b, i) ⇒ number

Do a smooth interpolation between a and b

radians(degrees) ⇒ number

Get an angle in radians

degrees(radians) ⇒ number

Get an angle in degrees

randomBetween(min, max) ⇒ number

Get a random float in the interval [min, max)

randomIntBetween(min, max) ⇒ number

Get a random integer in the interval [min, max]

cltRandom([mu], [sigma], [samples]) ⇒ number

Get a normally-distributed random number

cltRandomInt(min, max) ⇒ number

Get a normally-distributed random integer in the interval [min, max]

weightedRandom(w) ⇒ number

Return a weighted random integer

lerpArray(a, i, [f]) ⇒ number

Return an interpolated value from an array

dot(a, b) ⇒ number

Get the dot product of two vectors

factorial(a) ⇒ number

Get the factorial of a number

npr(n, r) ⇒ number

Get the number of permutations of r elements from a set of n elements

ncr(n, r) ⇒ number

Get the number of combinations of r elements from a set of n elements

combinations(a, r) ⇒ Array.<Array.<*>>

Generate all combinations of r elements from an array

cartesian()

Get a cartesian product of arrays

times(f, n) ⇒ Array.<*>

Return a new array with length n by calling function f(i) on each element

range(n) ⇒ Array.<number>

Return an array containing numbers 0->(n - 1)

zip(a, b) ⇒ Array.<Array.<*>>

Zip 2 arrays together, i.e. ([1, 2, 3], [a, b, c]) => [[1, a], [2, b], [3, c]]

at(a, i) ⇒ *

Return array[i] with positive and negative wrapping

peek(a) ⇒ *

Return the last element of an array without removing it

chunk(a, n) ⇒ Array.<Array.<*>>

Chop an array into chunks of size n

shuffle(a) ⇒ Array.<*>

Randomly shuffle a shallow copy of an array

flat(o, concatenator) ⇒ object

Flatten an object

unflat(o, concatenator) ⇒ object

Unflatten an object

split(array, predicate) ⇒ Array.<Array.<*>>

Split an array into sub-arrays based on a predicate

pluck(o, ...keys) ⇒ object

Pluck keys from an object

exclude(o, ...keys) ⇒ object

Exclude keys from an object

Typedefs

InterpolationFunction ⇒ number

An interpolation function

TimesFunction ⇒ *

A function for generating array values

SplitPredicate ⇒ boolean

A split predicate

floatEquals(a, b, [p]) ⇒ boolean

Check if two numbers are approximately equal

Kind: global function
Returns: boolean - True if numbers a and b are approximately equal

Param	Type	Default	Description
a	number		Number a
b	number		Number b
[p]	number	Number.EPSILON	The precision value

clamp(a, [min], [max]) ⇒ number

Clamp a number between min and max

Kind: global function
Returns: number - A clamped number

Param	Type	Default	Description
a	number		The number to clamp
[min]	number	0	The minimum value
[max]	number	1	The maximum value

frac(a) ⇒ number

Get the fractional part of a number

Kind: global function
Returns: number - The fractional part of the number

Param	Type	Description
a	number	The number from which to get the fractional part

round(n, [d]) ⇒ number

Round n to d decimal places

Kind: global function
Returns: number - A rounded number

Param	Type	Default	Description
n	number		The number to round
[d]	number	0	The number of decimal places to round to

lerp(a, b, i) ⇒ number

Do a linear interpolation between a and b

Kind: global function
Returns: number - An interpolated value in the interval [a, b]

Param	Type	Description
a	number	The minimum number
b	number	The maximum number
i	number	The interpolation value, should be in the interval [0, 1]

unlerp(a, b, i) ⇒ number

Get the position of i between a and b

Kind: global function
Returns: number - The position of i between a and b

Param	Type	Description
a	number	The minimum number
b	number	The maximum number
i	number	The interpolated value in the interval [a, b]

blerp(c00, c10, c01, c11, ix, iy) ⇒ number

Do a bilinear interpolation

Kind: global function
Returns: number - A bilinear interpolated value

Param	Type	Description
c00	number	Top-left value
c10	number	Top-right value
c01	number	Bottom-left value
c11	number	Bottom-right value
ix	number	Interpolation value along x
iy	number	Interpolation value along y

remap(i, a1, a2, b1, b2) ⇒ number

Re-map a number i from range a1...a2 to b1...b2

Kind: global function

Param	Type	Description
i	number	The number to re-map
a1	number
a2	number
b1	number
b2	number

smoothstep(a, b, i) ⇒ number

Do a smooth interpolation between a and b

Kind: global function
Returns: number - An interpolated value in the interval [a, b]

Param	Type	Description
a	number	The minimum number
b	number	The maximum number
i	number	The interpolation value

radians(degrees) ⇒ number

Get an angle in radians

Kind: global function
Returns: number - The angle in radians

Param	Type	Description
degrees	number	The angle in degrees

degrees(radians) ⇒ number

Get an angle in degrees

Kind: global function
Returns: number - The angle in degrees

Param	Type	Description
radians	number	The angle in radians

randomBetween(min, max) ⇒ number

Get a random float in the interval [min, max)

Kind: global function
Returns: number - A random float in the interval [min, max)

Param	Type	Description
min	number	Inclusive min
max	number	Exclusive max

randomIntBetween(min, max) ⇒ number

Get a random integer in the interval [min, max]

Kind: global function
Returns: number - A random integer in the interval [min, max]

Param	Type	Description
min	number	Inclusive min
max	number	Inclusive max

cltRandom([mu], [sigma], [samples]) ⇒ number

Get a normally-distributed random number

Kind: global function
Returns: number - A normally-distributed random number

Param	Type	Default	Description
[mu]	number	0.5	The mean value
[sigma]	number	0.5	The standard deviation
[samples]	number	2	The number of samples

cltRandomInt(min, max) ⇒ number

Get a normally-distributed random integer in the interval [min, max]

Kind: global function
Returns: number - A normally-distributed random integer

Param	Type	Description
min	number	Inclusive min
max	number	Inclusive max

weightedRandom(w) ⇒ number

Return a weighted random integer

Kind: global function
Returns: number - An index from w

Param	Type	Description
w	Array.<number>	An array of weights

lerpArray(a, i, [f]) ⇒ number

Return an interpolated value from an array

Kind: global function
Returns: number - An interpolated value in the interval [min(a), max(a)]

Param	Type	Default	Description
a	Array.<number>		An array of values interpolate
i	number		A number in the interval [0, 1]
[f]	InterpolationFunction	Math.lerp	The interpolation function to use

dot(a, b) ⇒ number

Get the dot product of two vectors

Kind: global function
Returns: number - a ∙ b

Param	Type	Description
a	Array.<number>	Vector a
b	Array.<number>	Vector b

factorial(a) ⇒ number

Get the factorial of a number

Kind: global function
Returns: number - a!

Param	Type
a	number

npr(n, r) ⇒ number

Get the number of permutations of r elements from a set of n elements

Kind: global function
Returns: number - nPr

Param	Type
n	number
r	number

ncr(n, r) ⇒ number

Get the number of combinations of r elements from a set of n elements

Kind: global function
Returns: number - nCr

Param	Type
n	number
r	number

combinations(a, r) ⇒ Array.<Array.<*>>

Generate all combinations of r elements from an array

Kind: global function
Returns: Array.<Array.<*>> - An array of combination arrays

Param	Type	Description
a	Array.<*>
r	number	The number of elements to choose in each combination

Example

combinations([1, 2, 3], 2);

Output:

[
  [1, 2],
  [1, 3],
  [2, 3]
]

cartesian()

Get a cartesian product of arrays

Kind: global function
Example

cartesian([1, 2, 3], ['a', 'b']);

Output:

[
  [1, "a"],
  [1, "b"],
  [2, "a"],
  [2, "b"],
  [3, "a"],
  [3, "b"]
]

times(f, n) ⇒ Array.<*>

Return a new array with length n by calling function f(i) on each element

Kind: global function

Param	Type	Description
f	TimesFunction
n	number	The size of the array

range(n) ⇒ Array.<number>

Return an array containing numbers 0->(n - 1)

Kind: global function
Returns: Array.<number> - An array of integers 0->(n - 1)

Param	Type	Description
n	number	The size of the array

zip(a, b) ⇒ Array.<Array.<*>>

Zip 2 arrays together, i.e. ([1, 2, 3], [a, b, c]) => [[1, a], [2, b], [3, c]]

Kind: global function

Param	Type
a	Array.<*>
b	Array.<*>

at(a, i) ⇒ *

Return array[i] with positive and negative wrapping

Kind: global function
Returns: * - An element from the array

Param	Type	Description
a	Array.<*>
i	number	The positively/negatively wrapped array index

peek(a) ⇒ *

Return the last element of an array without removing it

Kind: global function
Returns: * - The last element from the array

Param	Type
a	Array.<*>

chunk(a, n) ⇒ Array.<Array.<*>>

Chop an array into chunks of size n

Kind: global function
Returns: Array.<Array.<*>> - An array of array chunks

Param	Type	Description
a	Array.<*>
n	number	The chunk size

shuffle(a) ⇒ Array.<*>

Randomly shuffle a shallow copy of an array

Kind: global function
Returns: Array.<*> - The shuffled array

Param	Type
a	Array.<*>

flat(o, concatenator) ⇒ object

Flatten an object

Kind: global function
Returns: object - A flattened object

Param	Type	Default	Description
o	object
concatenator	string	"."	The string to use for concatenating keys

unflat(o, concatenator) ⇒ object

Unflatten an object

Kind: global function
Returns: object - An un-flattened object

Param	Type	Default	Description
o	object
concatenator	string	"."	The string to check for in concatenated keys

split(array, predicate) ⇒ Array.<Array.<*>>

Split an array into sub-arrays based on a predicate

Kind: global function
Returns: Array.<Array.<*>> - An array of arrays

Param	Type
array	Array.<*>
predicate	SplitPredicate

pluck(o, ...keys) ⇒ object

Pluck keys from an object

Kind: global function
Returns: object - An object containing the plucked keys

Param	Type	Description
o	object
...keys	string	The keys to pluck from the object

exclude(o, ...keys) ⇒ object

Exclude keys from an object

Kind: global function
Returns: object - An object containing all keys except excluded keys

Param	Type	Description
o	object
...keys	string	The keys to exclude from the object

InterpolationFunction ⇒ number

An interpolation function

Kind: global typedef
Returns: number - The interpolated value in the interval [a, b]

Param	Type	Description
a	number	The minimum number
b	number	The maximum number
i	number	The interpolation value, should be in the interval [0, 1]

TimesFunction ⇒ *

A function for generating array values

Kind: global typedef
Returns: * - The array value

Param	Type	Description
i	number	The array index

SplitPredicate ⇒ boolean

A split predicate

Kind: global typedef
Returns: boolean - True if the array should split at this index

Param	Type	Description
value	any	The current value