shelving/util/number.d.ts

Toolkit for using data in JavaScript.

import type { AnyCaller } from "./function.js";
/** Values that can be converted to a number. */
export type PossibleNumber = number | string | Date;
/** Is a value a finite number? */
export declare function isNumber(value: unknown, min?: number, max?: number): value is number;
/** Assert that a value is a finite number. */
export declare function assertNumber(value: unknown, min?: number, max?: number, caller?: AnyCaller): asserts value is number;
/**
 * Convert an unknown value to a finite number, or return `undefined` if it cannot be converted.
 * - Note: numbers can be non-finite numbers like `NaN` or `Infinity`. These are detected and will always return `undefined`
 *
 * Conversion rules:
 * - Finite numbers return numbers.
 * - `-0` is normalised to `0`
 * - Strings are parsed as numbers using `Number.parseFloat()` after removing all non-numeric characters.
 * - Dates return their milliseconds (e.g. `date.getTime()`).
 * - Everything else returns `undefined`
 */
export declare function getNumber(value: unknown): number | undefined;
/**
 * Convert a possible number to a finite number, or throw `ValueError` if the value cannot be converted.
 */
export declare function requireNumber(value: PossibleNumber, min?: number, max?: number, caller?: AnyCaller): number;
/** Is an unknown value an integer (optionally with specified min/max values). */
export declare function isInteger(value: unknown, min?: number, max?: number): value is number;
/** Assert that a value is an integer. */
export declare function assertInteger(value: unknown, min?: number, max?: number, caller?: AnyCaller): asserts value is number;
/**
 * Convert an unknown value to an integer, or return `undefined` if it cannot be converted.
 *
 * Conversion rules:
 * - Integers return integers.
 * - `-0` is normalised to `0`
 * - Strings are parsed as integers using `parseInt()` after removing non-numeric characters.
 * - Dates return their milliseconds (e.g. `date.getTime()`).
 * - Everything else returns `undefined`
 */
export declare function getInteger(value: unknown): number | undefined;
/** Convert a possible number to an integer, or throw `ValueError` if the value cannot be converted. */
export declare function requireInteger(value: PossibleNumber, min?: number, max?: number, caller?: AnyCaller): number;
/**
 * Is a number within a specified range?
 *
 * @param num The number to test, e.g. `17`
 * @param min The start of the range, e.g. `10`
 * @param max The end of the range, e.g. `20`
 */
export declare function isBetween(num: number, min: number, max: number): boolean;
/**
 * Round numbers to a given step.
 *
 * @param num The number to round.
 * @param step The rounding to round to, e.g. `2` or `0.1` (defaults to `1`, i.e. round numbers).
 *
 * @returns The number rounded to the specified step.
 */
export declare function roundStep(num: number, step?: number): number;
/**
 * Round a number to a specified set of decimal places.
 * - Better than `Math.round()` because it allows a `precision` argument.
 * - Better than `num.toFixed()` because it trims excess `0` zeroes.
 *
 * @param num The number to round.
 * @param precision Maximum number of digits shown after the decimal point (defaults to 10).
 *
 * @returns The number rounded to the specified precision.
 */
export declare function roundNumber(num: number, precision?: number): number;
/**
 * Truncate a number to a specified set of decimal places.
 * - Better than `Math.trunc()` because it allows a `precision` argument.
 *
 * @param num The number to truncate.
 * @param precision Maximum number of digits shown after the decimal point (defaults to 0).
 * @returns The number truncated to the specified precision.
 */
export declare function truncateNumber(num: number, precision?: number): number;
/**
 * Bound a number between two values.
 * - e.g. `12` bounded by `2` and `8` is `8`
 */
export declare function boundNumber(num: number, min: number, max: number): number;
/**
 * Wrap a number between two values.
 * - Numbers wrap around between min and max (like a clock).
 * - e.g. `12` bounded by `2` and `8` is `6`
 * - Words in both directions.
 * - e.g. `-2` bounded by `2` and `8` is `4`
 */
export declare function wrapNumber(num: number, min: number, max: number): number;
/**
 * Get a number as a percentage of another number.
 *
 * @param numerator Number representing the amount of progress.
 * @param denumerator The number representing the whole amount.
 */
export declare function getPercent(numerator: number, denumerator: number): number;
/** Sum an iterable set of numbers and return the total. */
export declare function sumNumbers(nums: Iterable<number>): number;
/** Find the number that's closest to a target in an iterable set of numbers. */
export declare function getClosestNumber<T extends number>(nums: Iterable<T>, target: number): T | undefined;