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

Typedefs

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 |