smath 1.12.0 → 1.13.0

package/types/index.d.ts

@@ -3,357 +3,363 @@
  * Small math function library
  *
  * ![NPM Downloads](https://img.shields.io/npm/d18m/smath)
+ * ![NPM Last Update](https://img.shields.io/npm/last-update/smath)
  */
 /**
- * Contains a small math function library including
- * useful interpolation and extrapolation functions.
+ * 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 namespace 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
-     * ```
-     */
-    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
-     * ```
-     */
-    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
-     * ```
-     */
-    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
-     * ```
-     */
-    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
-     * ```
-     */
-    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 ]
-     * ```
-     */
-    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 ]
-     * ```
-     */
-    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
-     * ```
-     */
-    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 ]
-     * ```
-     */
-    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
-     * ```
-     */
-    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
-     * ```
-     */
-    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
-     * ```
-     */
-    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
-     * ```
-     */
-    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
-     * ```
-     */
-    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
-     * ```
-     */
-    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
-     * ```
-     */
-    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
-     * ```
-     */
-    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...
-     * ```
-     */
-    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...
-     * ```
-     */
-    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...
-     * ```
-     */
-    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
-     * ```
-     */
-    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...
-     * ```
-     */
-    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... ]
-     * ```
-     */
-    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' ]
-     * ```
-     */
-    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
-     * ```
-     */
-    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
-     * ```
-     */
-    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
-     * ```
-     */
-    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 }
-     * ```
-     */
-    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 }
-     * ```
-     */
-    function mixed(n: number, epsilon?: number): {
-        whole: number;
-        num: number;
-        den: number;
-    };
-}
+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;