@technobuddha/library/dist/numbering.d.ts

A large library of useful functions

/**
 * Options for controlling how numbers are converted to words or symbols.
 * @group Math
 * @category Verbalization
 */
export type Numbering = {
    /**
     * Output format for integer and fraction parts.
     * - integer: 'numeric' | 'alphabetic' | 'hybrid'
     * - fraction: 'numeric' | 'alphabetic'
     */
    output: {
        /** integer output format: 'numeric', 'alphabetic', or 'hybrid' */
        integer: 'numeric' | 'alphabetic' | 'hybrid';
        /** fraction output format: 'numeric' or 'alphabetic' */
        fraction: 'numeric' | 'alphabetic';
    };
    /** Word to place after the hundreds.  E.g., "one hundred and one" vs. "one hundred one" */
    and: string;
    /** Character to place between the tens and ones units. E.g., "twenty-one" vs. "twenty one" */
    hyphen: string;
    /** Maximum allowed difference between the actual and represented value. */
    tolerance: number;
    /**
     * Allowed denominators for fractions.
     * - 'common': typical denominators (2, 3, 4, etc.)
     * - 'wrench': denominators used in wrench sizes
     * - number[]: custom denominators
     */
    denominators: 'common' | 'wrench' | number[];
    /** Number of decimal places or significant digits to use (1-9). */
    precision: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
    /** Whether to use ordinal form (e.g., "first", "second", "third"). */
    ordinal: boolean;
    /**
     * Whether to shift the output.
     * - false: no shift
     * - 'decimal': shift decimal part
     * - 'fraction': shift fraction part
     */
    shift: false | 'decimal' | 'fraction';
};
/**
 * Returns a string representation of the sign.
 * @param sign - The sign of the number, where `1` represents positive and `-1` represents negative.
 * @returns An empty string for positive sign, or the string `'negative '` for negative sign.
 * @internal
 */
export declare function signWord(sign: 1 | -1): string;
/**
 * Returns the string representation of a sign symbol based on the input value.
 * @param sign - The sign indicator, where `1` represents positive and `-1` represents negative.
 * @returns The corresponding sign symbol as a string.
 * @internal
 */
export declare function signSymbol(sign: 1 | -1): string;
/**
 * Converts a numeric input into a formatted string representation based on the provided options.
 *
 * The formatting can be numeric, alphabetic, or hybrid, and supports custom precision, ordinal forms,
 * and special handling for zero, NaN, and infinity values. The output can include both integer and fractional
 * parts, formatted according to the specified options.
 * @param input - The number to be formatted.
 * @param options - An object specifying formatting options, including:
 *   - `output`: Determines the style for integer and fractional parts (`numeric`, `alphabetic`, or `hybrid`).
 *   - `precision`: The number of decimal places to consider for the fractional part.
 *   - `ordinal`: Whether to return the ordinal form (e.g., "1st", "second", "zeroth").
 * @returns The formatted string representation of the input number according to the specified options.
 * @internal
 */
export declare function numbering(input: number, options: Numbering): string;