@sv443-network/coreutils
Version:
Cross-platform, general-purpose, JavaScript core library for Node, Deno and the browser. Intended to be used in conjunction with `@sv443-network/userutils` and `@sv443-network/djsutils`, but can be used independently as well.
66 lines (65 loc) • 4.22 kB
TypeScript
/**
* @module math
* This module contains general-purpose math functions like clamping, mapping and random number generation - [see the documentation for more info](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#math)
*/
import type { NumberFormat, Stringifiable } from "./types.js";
/** Checks if the given {@linkcode bitSet} contains the given {@linkcode checkVal} */
export declare function bitSetHas<TType extends number | bigint>(bitSet: TType, checkVal: TType): boolean;
/** Ensures the passed {@linkcode value} always stays between {@linkcode min} and {@linkcode max} */
export declare function clamp(value: number, min: number, max: number): number;
/** Ensures the passed {@linkcode value} always stays between 0 and {@linkcode max} */
export declare function clamp(value: number, max: number): number;
/**
* Calculates the amount of digits in the given number - the given number or string will be passed to the `Number()` constructor.
* Returns NaN if the number is invalid.
* @param num The number to count the digits of
* @param withDecimals Whether to count the decimal places as well (defaults to true)
* @example ```ts
* digitCount(); // NaN
* digitCount(123); // 3
* digitCount(1.23); // 3
* digitCount(1.23, false); // 1
* digitCount(Infinity); // Infinity
* ```
*/
export declare function digitCount(num: number | Stringifiable, withDecimals?: boolean): number;
/** Formats a number with the given locale and format */
export declare function formatNumber(number: number, locale: string, format: NumberFormat): string;
/**
* Transforms the value parameter from the numerical range `range1min` to `range1max` to the numerical range `range2min` to `range2max`
* For example, you can map the value 2 in the range of 0-5 to the range of 0-10 and you'd get a 4 as a result.
*/
export declare function mapRange(value: number, range1min: number, range1max: number, range2min: number, range2max: number): number;
/**
* Transforms the value parameter from the numerical range `0` to `range1max` to the numerical range `0` to `range2max`
* For example, you can map the value 2 in the range of 0-5 to the range of 0-10 and you'd get a 4 as a result.
*/
export declare function mapRange(value: number, range1max: number, range2max: number): number;
/** Makes the {@linkcode value} over- & underflow so it is always between {@linkcode min} and {@linkcode max}, if it's outside the range */
export declare function overflowVal(value: number, min: number, max: number): number;
/** Makes the {@linkcode value} over- & underflow so it is always between `0` and {@linkcode max}, if it's outside the range */
export declare function overflowVal(value: number, max: number): number;
/**
* Returns a random number between {@linkcode min} and {@linkcode max} (inclusive)
* Set {@linkcode enhancedEntropy} to true to use `crypto.getRandomValues()` for better cryptographic randomness (this also makes it take longer to generate)
*/
export declare function randRange(min: number, max: number, enhancedEntropy?: boolean): number;
/**
* Returns a random number between 0 and {@linkcode max} (inclusive)
* Set {@linkcode enhancedEntropy} to true to use `crypto.getRandomValues()` for better cryptographic randomness (this also makes it take longer to generate)
*/
export declare function randRange(max: number, enhancedEntropy?: boolean): number;
/**
* Rounds {@linkcode num} to a fixed amount of decimal places, specified by {@linkcode fractionDigits} (supports negative values to round to the nearest power of 10).
* @example ```ts
* roundFixed(234.567, -2); // 200
* roundFixed(234.567, -1); // 230
* roundFixed(234.567, 0); // 235
* roundFixed(234.567, 1); // 234.6
* roundFixed(234.567, 2); // 234.57
* roundFixed(234.567, 3); // 234.567
* ```
*/
export declare function roundFixed(num: number, fractionDigits: number): number;
/** Rounds the given values at the given decimal place (same as in {@linkcode roundFixed()}) and checks if they are within the given range (0.5 by default) */
export declare function valsWithin(a: number, b: number, dec?: number, withinRange?: number): boolean;