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

A large library of useful functions

import { type Numbering } from './numbering.ts';
/**
 * Options for customizing the output and behavior of fraction number representations.
 * @group Math
 * @category Verbalization
 */
export type FractionOptions = {
    /**
     * Output format for the number representation.
     * @defaultValue 'alphabetic'
     */
    output?: 'numeric' | 'alphabetic' | 'hybrid' | Numbering['output'];
    /**
     * Text to use for "and" in compound numbers (e.g., "one hundred and one").
     * @defaultValue (empty string)
     */
    and?: Numbering['and'];
    /**
     * Text to use for hyphens in compound numbers (e.g., "twenty-one").
     * @defaultValue ' ' (space)
     */
    hyphen?: Numbering['hyphen'];
    /**
     * Tolerance for floating-point comparison when converting decimals to fractions.
     * @defaultValue 0.01
     */
    tolerance?: Numbering['tolerance'];
    /**
     * Type of denominators to use when expressing fractions.
     * @defaultValue 'common'
     */
    denominators?: Numbering['denominators'];
    /**
     * Precision for decimal/fraction conversion.
     * @defaultValue 9
     */
    precision?: Numbering['precision'];
    /**
     * Whether to output ordinal numbers (e.g., "first", "second") instead of cardinal numbers.
     * @defaultValue false
     */
    ordinal?: Numbering['ordinal'];
    /**
     * Whether to shift the fractional part of the number.
     */
    shift?: Numbering['shift'];
};
/**
 * Converts a numeric input into a formatted fraction string, either in numeric or alphabetic form.
 *
 * The function finds the closest matching fraction from a predefined list and formats the output
 * based on the specified options. If the input is negative, the result is prefixed accordingly.
 * The output can be either a numeric representation (e.g., "1 1⁄2") or an alphabetic representation
 * (e.g., "one and one half").
 * @param input - The number to convert to a fraction string.
 * @param options - An optional object specifying the output format.
 * @returns The formatted fraction string.
 * @example
 * ```typescript
 * fraction(1.5); // "one and one half"
 * fraction(2.75, { output: 'numeric' }); // "2 3⁄4"
 * fraction(-0.25, { output: 'alphabetic' }); // "negative one quarter"
 * fraction(0.333, { precision: 2 }); // "one third"
 * ```
 * @group Math
 * @category Verbalization
 */
export declare function fraction(input: number, options?: FractionOptions): string;