nhb-toolbox/dist/dts/number/basics.d.ts

A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.

import type { Maybe, Numeric } from '../types/index';
import type { ConvertedDecimal, DecimalOptions, RandomNumberOptions } from './types';
/**
 * * Utility to generate a random number between a given range.
 * * If no options are provided, it will generate a random number between `0` and `100` (inclusive).
 * * If `min` is greater than `max`, it will swap the values and generate a random number.
 *
 * @param options - Options for configuring random number generator.
 * @returns Random number.
 */
export declare const getRandomNumber: (options?: RandomNumberOptions) => number;
/**
 * * Utility to round a number to given decimal places.
 *
 * @param input - Number or `stringified` number to round.
 * @param options - Options for rounding behavior, including decimal places and return type.
 * @returns Converted number as `number` (default) or `string` (if `isString` is `true`).
 */
export declare const convertToDecimal: <T extends Maybe<boolean> = false>(input: Numeric, options?: DecimalOptions<T>) => ConvertedDecimal<T>;
/**
 * * Calculates the HCF/GCD of multiple numbers.
 *
 * @param numbers - List of numbers to find the HCF/GCD for.
 * @returns The HCF/GCD of all the provided numbers.
 */
export declare const calculateHCF: (...numbers: Numeric[]) => number;
/**
 * * Calculates the LCM/LCD of multiple numbers.
 *
 * @param numbers - List of numbers to find the LCM/LCD for.
 * @returns The LCM/LCD of all the provided numbers.
 */
export declare const calculateLCM: (...numbers: Numeric[]) => number;
/**
 * * Computes the factorial of a non-negative numeric value (integer).
 *
 * @param int - A numeric input value (integer) whose factorial should be calculated.
 *
 * @returns The factorial result as a number if valid, otherwise `undefined`.
 *
 * @example
 * factorial(5); // → 120
 * factorial(0); // → 1
 * factorial(-3); // → undefined
 * factorial(undefined); // → undefined
 * factorial(5.5); // → undefined
 *
 * @remarks
 * - Factorial of `0` and `1` is `1`.
 * - Uses recursive approach internally.
 * - Input is normalized via `normalizeNumber` before computation.
 * - May return large values quickly due to factorial growth rate.
 * - Returns `undefined` if the input is negative, not numeric, non-integer, or `undefined`.
 */
export declare function factorial(int: Maybe<Numeric>): Maybe<number>;
/**
 * * Efficiently computes all positive integer factors (divisors) of a number.
 *
 * @param int - Numeric value to find factors for. Non-integer or negative values return an empty array.
 *
 * @returns An array of positive factors in ascending order.
 *
 * @example
 * getFactors(12); // → [1, 2, 3, 4, 6, 12]
 * getFactors(7);  // → [1, 7]
 * getFactors(-4); // → []
 * getFactors(undefined); // → []
 *
 * @remarks
 * - Uses the square root method for better performance (`O(√n)`).
 * - Returns an empty array for invalid, negative, or non-integer input.
 */
export declare function getFactors(int: Maybe<Numeric>): number[];
/**
 * * Sums up all digits of a number.
 *
 * @param num The input number.
 * @returns The sum of its digits.
 */
export declare function sumDigits(num: Numeric): number;
/**
 * * Sums up numbers.
 *
 * @param numbers The input numbers.
 * @returns The sum of the numbers.
 */
export declare function sumNumbers(...numbers: Numeric[]): number;
/**
 * * Reverses a number (e.g., `123` → `321`).
 *
 * @param num The number to reverse.
 * @returns The reversed number.
 */
export declare function reverseNumber(num: Numeric): number;
/**
 * * Calculates the average of a set of numbers.
 *
 * @param numbers - A list of numbers for which to calculate the average.
 * @returns The average of the provided numbers. Returns `NaN` if no numbers are valid.
 */
export declare function getAverage(...numbers: Numeric[]): number;
/**
 * * Rounds a number to a specified number of decimal places.
 *
 * @param number - The number to round.
 * @param roundTo - The number of decimal places to round to (default is `2`).
 * - If `roundTo` is negative, the number is rounded to the left of the decimal point (e.g., `-1` rounds to the nearest 10, `-2` to nearest 100 etc.).
 * @returns The rounded number, either in float or integer (if a whole number).
 *
 * @example
 * roundNumber(1234.56, -2); // 1200
 * roundNumber(1234.56, 1);  // 1234.6
 */
export declare function roundNumber(number: Numeric, roundTo?: number): number;