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

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

import type { Numeric } from '../types/index';
import type { BnDigitResult, LooseRomanNumeral, RomanCapital } from './types';
/**
 * * Converts a numeric value into its corresponding English word representation.
 * @warning ***Supports numeric values up to `10e19` or `10^20` (one hundred quintillion).***
 * @warning ***Decimal values are ignored; only the integer part is converted.***
 * @param number - The number to convert into words.
 * @returns The number converted in words.
 */
export declare function numberToWords(num: Numeric): string;
/**
 * * Converts a number to an uppercase Roman numeral.
 * @param value - The number to convert. Number must be an integer and `between 1 and 3999`.
 * @returns The Roman numeral representation in uppercase.
 *
 * @example convertToRomanNumerals(29) // → "XXIX"
 */
export declare const convertToRomanNumerals: (value: Numeric) => RomanCapital;
/**
 * * Converts a Roman numeral to its Arabic numeric representation.
 * @param roman - The Roman numeral to convert. Case-insensitive but must represent a valid Roman numeral (`I`–`MMMCMXCIX`) otherwise throws runtime error.
 * @returns The numeric (Arabic system) representation of the Roman numeral.
 *
 * @example
 * romanToInteger("XXIX") // → 29
 * romanToInteger("mmxxv") // → 2025
 */
export declare const romanToInteger: (roman: LooseRomanNumeral) => number;
/**
 * * Converts a number, numeric string, or cardinal word string into its ordinal word representation.
 *
 * @param number - A number (e.g. `42`), numeric string (e.g. `"42"`), or cardinal word (e.g. `"forty-two"`).
 * @returns The ordinal word form (always in lowercase) of the input.
 *
 * @example
 * numberToWordsOrdinal(1); // "first"
 * numberToWordsOrdinal("23"); // "twenty-third"
 * numberToWordsOrdinal("twenty-three"); // "twenty-third"
 */
export declare function numberToWordsOrdinal(number: Numeric | string): string;
/**
 * * Convert an English cardinal/ordinal word string into a number.
 *
 * - Accepts hyphenated words, "and", ordinals (first, second, etc.), negatives, and large scales (thousand, million etc.).
 *
 * @example
 * wordsToNumber('forty-two') // 42
 * wordsToNumber('one hundred and seven') // 107
 * wordsToNumber('two thousand three hundred') // 2300
 * wordsToNumber('twenty-first') // 21
 * wordsToNumber('negative five') // -5
 *
 * @param word - A human readable number (cardinal or ordinal) in words
 * @returns Numeric value of the word or NaN if cannot parse
 *
 * @remarks
 * **NOTE** - *For very large numbers (e.g. more than quintillion) results may not always be correct.*
 */
export declare function wordsToNumber(word: string): number;
/**
 * * Converts Bangla (Arabic system) digits to Latin (Arabic system) digits.
 *
 * @remarks
 * - Behavior depends on the `forceNumber` flag:
 *   - When `forceNumber` is `true`, always returns a `number` (strips non-digit characters).
 * 	   - Returns `NaN` if the input is non empty string or does not include any numeric string.
 *   - When `forceNumber` is `false`, always returns a string, including non-digit characters.
 * 	   - Returns empty string if the input is non empty string.
 *
 * @param bnDigit - A string containing Bangla (Arabic system) digits.
 * @param forceNumber - Whether to force number conversion even if the input includes non-digit character(s). Default is `false`.
 *
 * @example
 * banglaToDigit('১২৩abc'); // 123
 * banglaToDigit(''); // NaN
 * banglaToDigit('৪৫৬');    // 456
 *
 * @example
 * banglaToDigit('১২৩', false);	// "123"
 * banglaToDigit('১২৩abc', false);	// "123abc"
 */
export declare function banglaToDigit<Force extends boolean = true>(bnDigit: string, forceNumber?: Force): BnDigitResult<Force>;
/**
 * * Converts Latin (Arabic system) digits to Bangla digits (Arabic system).
 *
 * @remarks
 * - Accepts numbers or numeric strings including non-digit characters.
 * - When `preserveNonDigit` is `true`, non-digit characters are preserved in the output.
 * - When `preserveNonDigit` is `false`, non-numeric strings are stripped.
 * - Returns empty string for invalid input.
 *
 * @param digit - A number or string containing Latin (Arabic system) digits.
 * @param preserveNonDigit - Whether to preserve non-digit characters in the output. Default is `true`.
 *
 * @example
 * digitToBangla(123);          // "১২৩"
 * digitToBangla('456');        // "৪৫৬"
 *
 * @example
 * digitToBangla('12ab', false);	// "১২"
 * digitToBangla('12ab');		// "১২ab"
 */
export declare function digitToBangla(digit: number | string, preserveNonDigit?: boolean): string;