smath/types/index.d.ts

Small math function library

/**
 * @packageDocumentation
 * Small math function library
 *
 * ![NPM Downloads](https://img.shields.io/npm/d18m/smath)
 * ![NPM Last Update](https://img.shields.io/npm/last-update/smath)
 */
/**
 * Check if two numbers are approximately equal with a maximum abolute error.
 * @param a Any number
 * @param b Any number
 * @param epsilon Maximum absolute error
 * @returns True if `a` is approximately `b`
 * @example
 * ```js
 * const b1 = SMath.approx(1 / 3, 0.33, 1e-6), // false
 *       b2 = SMath.approx(1 / 3, 0.33, 1e-2); // true
 * ```
 */
export declare function approx(a: number, b: number, epsilon?: number): boolean;
/**
 * Clamp a number within a range.
 * @param n The number to clamp
 * @param min The minimum value of the range
 * @param max The maximum value of the range
 * @returns A clamped number
 * @example
 * ```js
 * const n1 = SMath.clamp(5, 0, 10),  // 5
 *       n2 = SMath.clamp(-2, 0, 10); // 0
 * ```
 */
export declare function clamp(n: number, min: number, max: number): number;
/**
 * Normalize the number `n` from the range `min, max` to the range `0, 1`
 * @param n The number to normalize
 * @param min The minimum value in the range
 * @param max The maximum value in the range
 * @returns A normalized value
 * @example
 * ```js
 * const y = SMath.normalize(18, 9, 99); // 0.1
 * ```
 */
export declare function normalize(n: number, min: number, max: number): number;
/**
 * Expand a normalized number `n` to the range `min, max`
 * @param n A normalized number
 * @param min The minimum value in the range
 * @param max The maximum value in the range
 * @returns A value within the number range
 * @example
 * ```js
 * const y = SMath.expand(0.25, 4, 6); // 4.5
 * ```
 */
export declare function expand(n: number, min: number, max: number): number;
/**
 * Translate a number `n` from the range `min1, max1` to the range `min2, max2`
 * @param n The number to translate
 * @param min1 The minimum value from the initial range
 * @param max1 The maximum value from the initial range
 * @param min2 The minimum value for the final range
 * @param max2 The maximum value for the final range
 * @returns A translated number in the final range
 * @example
 * ```js
 * const C = 20,
 *       F = SMath.translate(C, 0, 100, 32, 212); // 68
 * ```
 */
export declare function translate(n: number, min1: number, max1: number, min2: number, max2: number): number;
/**
 * Generate an array of linearly spaced numbers.
 * @param min The initial value of the linear space
 * @param max The final value of the linear space
 * @param count The number of values in the space
 * @returns The linear space as an array of numbers
 * @example
 * ```js
 * const space = SMath.linspace(1, 5, 6);
 * // [ 1, 1.8, 2.6, 3.4, 4.2, 5 ]
 * ```
 */
export declare function linspace(min: number, max: number, count: number): Array<number>;
/**
 * Generate an array of logarithmically spaced numbers.
 * @param min The initial magnitude of the space
 * @param max The final magnitude of the space
 * @param count The number of values in the space
 * @returns The logarithmic space as an array of numbers
 * @example
 * ```js
 * const space = SMath.logspace(0, 2, 5);
 * // [ 1, 3.2, 10, 31.6, 100 ]
 * ```
 */
export declare function logspace(min: number, max: number, count: number): Array<number>;
/**
 * Compute the factorial of `n`.
 * @param n Any positive integer
 * @returns `n!`
 * @example
 * ```js
 * const y = SMath.factorial(5); // 120
 * ```
 */
export declare function factorial(n: number): number;
/**
 * Factorize `n` into its prime factors.
 * @param n Any positive integer
 * @returns The array of prime factors
 * @example
 * ```js
 * const y = SMath.factors(12); // [ 2, 2, 3 ]
 * ```
 */
export declare function factors(n: number): Array<number>;
/**
 * Round a number to the nearest multiple of an arbitrary
 * base. Does not round when the base is set to zero.
 * @param n Any number to round
 * @param base Any base to round to
 * @returns `n` rounded to the nearest multiple of `base`
 * @example
 * ```js
 * const y = SMath.round2(Math.PI, 0.2); // 3.2
 * ```
 */
export declare function round2(n: number, base: number): number;
/**
 * Calculate the relative normalized error or deviation from any
 * value to an accepted value. An error of 0 indicates that the
 * two values are identical. An error of -0.1 indicates that the
 * experimental value is 10% smaller than (90% of) the accepted
 * value. An error of 1.0 indicates that the experimental value
 * is 100% greater (or twice the size) of the accepted value.
 * @param experimental The value observed or produced by a test
 * @param actual The accepted or theoretical value
 * @returns The relative (normalized) error
 * @example
 * ```js
 * const e = SMath.error(22.5, 25); // -0.1
 * ```
 */
export declare function error(experimental: number, actual: number): number;
/**
 * Add up all the inputs.
 * If none are present, returns 0.
 * @param data An array of numeric inputs
 * @returns The sum total
 * @example
 * ```js
 * const y = SMath.sum([1, 2, 3]); // 6
 * ```
 */
export declare function sum(data: Array<number>): number;
/**
 * Multiply all the inputs.
 * If none are present, returns 1.
 * @param data An array of numeric inputs
 * @returns The product
 * @example
 * ```js
 * const y = SMath.prod([2, 2, 3, 5]); // 60
 * ```
 */
export declare function prod(data: Array<number>): number;
/**
 * Compute the average, or mean, of a set of numbers.
 * @param data An array of numeric inputs
 * @returns The average, or mean
 * @example
 * ```js
 * const y = SMath.avg([1, 2, 4, 4]); // 2.75
 * ```
 */
export declare function avg(data: Array<number>): number;
/**
 * Compute the median of a set of numbers.
 * @param data An array of numeric inputs
 * @returns The median of the dataset
 * @example
 * ```js
 * const y = SMath.median([2, 5, 3, 1]); // 2.5
 * ```
 */
export declare function median(data: Array<number>): number;
/**
 * Compute the variance of a **complete population**.
 * @param data An array of numeric inputs
 * @returns The population variance
 * @example
 * ```js
 * const y = SMath.varp([1, 2, 4, 4]); // 1.6875
 * ```
 */
export declare function varp(data: Array<number>): number;
/**
 * Compute the variance of a **sample**.
 * @param data An array of numeric inputs
 * @returns The sample variance
 * @example
 * ```js
 * const y = SMath.vars([1, 2, 4, 4]); // 2.25
 * ```
 */
export declare function vars(data: Array<number>): number;
/**
 * Compute the standard deviation of a **complete population**.
 * @param data An array of numeric inputs
 * @returns The population standard deviation
 * @example
 * ```js
 * const y = SMath.stdevp([1, 2, 3, 4]); // 1.118...
 * ```
 */
export declare function stdevp(data: Array<number>): number;
/**
 * Compute the standard deviation of a **sample**.
 * @param data An array of numeric inputs
 * @returns The sample standard deviation
 * @example
 * ```js
 * const y = SMath.stdevs([1, 2, 3, 4]); // 1.29...
 * ```
 */
export declare function stdevs(data: Array<number>): number;
/**
 * Generate a uniformly-distributed floating-point number within the range.
 * @param min The minimum bound
 * @param max The maximum bound
 * @returns A random float within the range
 * @example
 * ```js
 * const y = SMath.runif(-2, 2); // 0.376...
 * ```
 */
export declare function runif(min: number, max: number): number;
/**
 * Generate a uniformly-distributed integer within the range.
 * @param min The minimum bound (inclusive)
 * @param max The maximum bound (inclusive)
 * @returns A random integer within the range
 * @example
 * ```js
 * const y = SMath.rint(-4, 3); // -4
 * ```
 */
export declare function rint(min: number, max: number): number;
/**
 * Generate a normally-distributed floating-point number.
 * @param mean The mean of the population distribution
 * @param stdev The standard deviation of the population
 * @returns A random float
 * @example
 * ```js
 * const y = SMath.rnorm(2, 3); // 1.627...
 * ```
 */
export declare function rnorm(mean?: number, stdev?: number): number;
/**
 * Generate a population of normally-distributed floating-point numbers.
 * @param count The number of values to generate
 * @param mean The mean of the population distribution
 * @param stdev The standard deviation of the population
 * @returns A population of random floats
 * @example
 * ```js
 * const dataset = SMath.rdist(3); // [ 1.051..., -0.779..., -2.254... ]
 * ```
 */
export declare function rdist(count: number, mean?: number, stdev?: number): Array<number>;
/**
 * Randomize an array of arbitrary elements.
 * @param stack An array of arbitrary elements
 * @returns The `stack` array in a random order
 * @example
 * ```js
 * const shuffled = SMath.shuffle(['a', 'b', 'c']); // [ 'c', 'a', 'b' ]
 * ```
 */
export declare function shuffle<T>(stack: Array<T>): Array<T>;
/**
 * Take the limit of a function. A return value of `NaN` indicates
 * that no limit exists either due to a discontinuity or imaginary value.
 * @param f Function `f(x)`
 * @param x The x-value where to take the limit
 * @param h The approach distance
 * @param discontinuity_cutoff The discontinuity cutoff
 * @returns `lim(f(x->x))`
 * @example
 * ```js
 * const y = SMath.lim(Math.log, 0); // -Infinity
 * ```
 */
export declare function lim(f: (x: number) => number, x: number, h?: number, discontinuity_cutoff?: number): number;
/**
 * Take the derivative of a function.
 * @param f Function `f(x)`
 * @param x The x-value where to evaluate the derivative
 * @param h Small step value
 * @returns `f'(x)`
 * @example
 * ```js
 * const y = SMath.differentiate(x => 3 * x ** 2, 2); // 12
 * ```
 */
export declare function differentiate(f: (x: number) => number, x: number, h?: number): number;
/**
 * Compute the definite integral of a function.
 * @param f Function `f(x)`
 * @param a The miminum integral bound
 * @param b The maximum integral bound
 * @param Ndx The number of rectangles to compute
 * @returns `F(b)-F(a)`
 * @example
 * ```js
 * const y = SMath.integrate(x => 3 * x ** 2, 1, 2); // 7
 * ```
 */
export declare function integrate(f: (x: number) => number, a: number, b: number, Ndx?: number): number;
/**
 * Convert an arbitrary decimal number into a simplified fraction (or ratio).
 * See `mixed()` for instructions on how to break out the whole number part.
 * @param n The decimal number to convert
 * @param epsilon Maximum absolute error
 * @returns An object containing the fraction's numerator and denominator
 * @example
 * ```js
 * const frac = SMath.rat(0.625); // { num: 5, den: 8 }
 * ```
 */
export declare function rat(n: number, epsilon?: number): {
    num: number;
    den: number;
};
/**
 * Convert an arbitrary decimal number into a simplified fraction, after
 * breaking out the whole number part first. See `rat()` for keeping the
 * number as a ratio without separating the whole number part.
 * @param n A decimal number to convert
 * @param epsilon Maximum absolute error
 * @returns An object containing the whole part and fraction numerator and denominator
 * @example
 * ```js
 * const frac = SMath.mixed(-8 / 6); // { whole: -1, num: 1, den: 3 }
 * ```
 */
export declare function mixed(n: number, epsilon?: number): {
    whole: number;
    num: number;
    den: number;
};
/**
 * Convert any number to its hexadecimal equivalent.
 * @param n A decimal number to convert
 * @param length The minimum number of digits to show
 * @returns The number `n` converted to hexadecimal
 * @example
 * ```js
 * const hex = SMath.toHex(10, 2); // '0A'
 * ```
 */
export declare function toHex(n: number, length?: number): string;