nhb-toolbox/dist/dts/number/utilities.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 { CurrencyCode, LocaleCode } from './types';
/**
 * * Rounds a number to the nearest specified interval.
 * @param value - The number to round.
 * @param interval - The interval to round to. Defaults to `5`.
 * @returns The number rounded to the nearest interval.
 * @example roundToNearest(27, 5) → 25
 */
export declare const roundToNearest: (value: Numeric, interval?: number) => number;
/**
 * * Formats a number as a currency string.
 * @param value - The number to format.
 * @param currency - The currency code (default: `USD`).
 * @param locale - The locale for formatting (default: matching currency locale).
 * @returns A formatted currency string.
 * @example formatCurrency(1234.56) → "$1,234.56"
 * @example formatCurrency(1234.56, "USD") → "$1,234.56"
 * @example formatCurrency(1234.56, "USD", "en-US") → "$1,234.56"
 */
export declare const formatCurrency: (value: Numeric, currency?: CurrencyCode, locale?: LocaleCode) => string;
/**
 * * Clamps a number within a specified range.
 * @param value - The number to clamp.
 * @param min - The minimum allowed value.
 * @param max - The maximum allowed value.
 * @returns The clamped number.
 * @example clampNumber(15, 10, 20) → 15
 * @example clampNumber(5, 10, 20) → 10
 * @example clampNumber(25, 10, 20) → 20
 */
export declare const clampNumber: (value: number, min: number, max: number) => number;
/**
 * * Generates a random floating-point number within a range.
 * @param min - The minimum value.
 * @param max - The maximum value.
 * @returns A random floating-point number between min and max.
 * @example randomFloat(1.5, 3.5) → 2.84623
 */
export declare const getRandomFloat: (min: Numeric, max: Numeric) => number;
/**
 * * Returns the ordinal suffix for a given number (e.g., 1 -> 'st', 2 -> 'nd', 3 -> 'rd', 4 -> 'th' etc.).
 * @description The function handles special cases for 11, 12, and 13, which all use 'th' despite the last digit.
 * If the `withNumber` parameter is `true`, the function returns the number along with its ordinal suffix (e.g., "1st").
 * Otherwise, it returns only the ordinal suffix (e.g., "st").
 *
 * @param num - The number or number string to get the ordinal suffix for.
 * @param withNumber - Whether to include the number along with its ordinal suffix (defaults to `true`).
 * @returns The appropriate ordinal suffix, optionally with the number (e.g., '1st' or 'st`, '2nd' or 'nd' and so on.).
 */
export declare const getOrdinal: (num: Numeric, withNumber?: boolean) => string;
/**
 * * Normalize a number or numeric string to a number.
 * @description
 * This function checks if the input is a number or a numeric string and converts it to a number.
 * If the input is not a valid number or numeric string, it returns `undefined`.
 * @param num - The number to normalize.
 * @returns The normalized number or `undefined` if the input is not a valid number or numeric string.
 */
export declare function normalizeNumber(num: unknown): Maybe<number>;