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!
npr(n, r) ⇒ number
Get the number of permutations of r elements from a set of n elements
Kind: global function
Returns: number
- nPr
ncr(n, r) ⇒ number
Get the number of combinations of r elements from a set of n elements
Kind: global function
Returns: number
- nCr
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
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
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
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
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 |