@resk/core/build/utils/numbers.d.ts

An innovative TypeScript framework that empowers developers to build applications with a fully decorator-based architecture for efficient resource management. By combining the power of decorators with a resource-oriented design, DecorRes enhances code cla

import { ICurrency, ICurrencyFormatters } from "../currency/types";
/**
 * Extends the Number interface with additional methods for formatting and abbreviating numbers.
 */
declare global {
    interface Number extends ICurrencyFormatters {
        /**
         * Counts the number of decimal places in the number.
         * @returns {number} The number of decimal places.
         */
        countDecimals: () => number;
        /**
         * Formats the number as a currency string.
         * @param {ICurrency | string} [symbol] The currency symbol to use (optional).
         * @param {number} [decimalDigits] The number of decimal places to display (optional).
         * @param {string} [thousandSeparator] The separator to use for thousands (optional).
         * @param {string} [decimalSeparator] The separator to use for decimals (optional).
         * @param {string} [format] The format to use for the currency string (optional).
         * @returns {string} The formatted currency string.
         * @example
         * ```ts
         * (12).formatMoney(); // Output: "12 FCFA"
         * (12000).formatMoney(); // Output: "12 000 FCFA"
         * ```
         */
        formatMoney: (symbol?: ICurrency | string, decimalDigits?: number, thousandSeparator?: string, decimalSeparator?: string, format?: string) => string;
        /**
         * Formats the number using the specified formatter.
         * @param {string} [formatter] The formatter to use (optional).
         * @param {boolean} [abreviate] Whether to abbreviate the number (optional).
         * @returns {string} The formatted string.
         * @example
         * ```ts
         * (12).format("moneyCAD"); // Output: "CA$12"
         * ```
         */
        format: (formatter?: string, abreviate?: boolean) => string;
        /**
         * Formats the number as a formatted number string with thousands separators.
         * @param {ICurrency | number} [optionsOrDecimalDigits] The options or decimal digits to use (optional).
         * @param {string} [thousandSeparator] The separator to use for thousands (optional).
         * @param {string} [decimalSeparator] The separator to use for decimals (optional).
         * @returns {string} The formatted number string.
         */
        formatNumber: (optionsOrDecimalDigits?: ICurrency | number, thousandSeparator?: string, decimalSeparator?: string) => string;
        /**
         * Abbreviates the number and formats it as a currency string.
         * @param {ICurrency | string} [symbol] The currency symbol to use (optional).
         * @param {number} [decimalDigits] The number of decimal places to display (optional).
         * @param {string} [thousandSeparator] The separator to use for thousands (optional).
         * @param {string} [decimalSeparator] The separator to use for decimals (optional).
         * @param {string} [format] The format to use for the currency string (optional).
         * @returns {string} The formatted and abbreviated currency string.
         */
        abreviate2FormatMoney: (symbol?: ICurrency | string, decimalDigits?: number, thousandSeparator?: string, decimalSeparator?: string, format?: string) => string;
        /***
         * Abbreviates a number and formats it as a number string.
         * @param {number} [decimalDigits] The number of decimal places to display (optional).
         * @param {string} [thousandSeparator] The separator to use for thousands (optional).
         * @param {string} [decimalSeparator] The separator to use for decimals (optional).
         * @returns {string} The formatted and abbreviated number string.
         */
        abreviate2FormatNumber: (decimalDigits?: number, thousandSeparator?: string, decimalSeparator?: string) => string;
    }
}
/**
 * Represents the result of abbreviating a number.
 */
export type IAbreviateNumberResult = {
    /**
     * The abbreviated result.
     */
    result: string;
    /**
     * The original value that was abbreviated.
     */
    value: number;
    /**
     * The format used for abbreviation.
     */
    format: string;
    /**
     * The suffix used for abbreviation (e.g. "K", "M", etc.).
     */
    suffix: string;
    /**
     * The formatted value.
     */
    formattedValue: string;
    /**
     * The minimum number of decimal digits required for a given number when abbreviating it,
     * ensuring that the abbreviated value does not lose significant information compared to the original number.
     */
    minAbreviationDecimalDigits: number;
};
/**
 * Abbreviates a number to a shorter form (e.g. 1000 -> 1K).
 * @see : https://stackoverflow.com/questions/10599933/convert-long-number-into-abbreviated-string-in-javascript-with-a-special-shortn
 * @param {number} num The number to abbreviate.
 *
*  @param {IAbreviateNumberOptions} [options] Formatting options when returnObject is true.
*  @param {number} num The number to abbreviate.
*  @param {number} [options.decimalDigits] Number of decimal digits to display. If not provided, will use the minimum number required for precision.
*  @param {string} [options.thousandsSeparator] Character to use as thousands separator. Example: "," for 1,234 or " " for 1 234.
*  @param {string} [options.decimalSeparator] Character to use as decimal separator. Example: "." for 1.5 or "," for 1,5.
 * @returns {IAbreviateNumberResult} The abbreviated number or an object with additional information.
 */
export declare const _abreviateNumber: (num: number, decimalDigits?: number, thousandsSeparator?: string, decimalSeparator?: string) => IAbreviateNumberResult;
/**
 * Abbreviates a number to a shorter form with optional formatting.
 *
 * This function converts a large number into a shorter representation
 * with suffixes such as 'K' for thousands, 'M' for millions, etc.
 * It also allows optional customization of the number of decimal digits
 * and the separators used for thousands and decimals.
 *
 * @param {number} num The number to abbreviate.
 * @param {number} [decimalDigits] Optional number of decimal digits to display.
 *   If not provided, the function will use the minimum number required for precision.
 * @param {string} [thousandsSeparator] Optional character to use as thousands separator.
 *   Example: ',' for 1,234 or ' ' for 1 234.
 * @param {string} [decimalSeparator] Optional character to use as decimal separator.
 *   Example: '.' for 1.5 or ',' for 1,5.
 * @returns {string} The abbreviated number as a string.
 */
export declare const abreviateNumber: (num: number, decimalDigits?: number, thousandsSeparator?: string, decimalSeparator?: string) => string;
/**
 * Abbreviates a number and formats it as a monetary value.
 *
 * @param {number} number The number to abbreviate and format.
 * @param {ICurrency | string} [symbol] The currency symbol or name.
 * @param {number} [decimalDigits] The number of decimal digits to use.
 * @param {string} [thousandSeparator] The thousand separator to use.
 * @param {string} [decimalSeparator] The decimal separator to use.
 * @param {string} [format] The format string to use.
 * @returns {string} The abbreviated and formatted monetary value.
 */
export declare const abreviate2FormatMoney: (number: number, symbol?: ICurrency | string, decimalDigits?: number, thousandSeparator?: string, decimalSeparator?: string, format?: string) => string;
/**
 * Returns the first non-zero number from a list of arguments, or 0 if no such number exists.
 *
 * This function iterates over the arguments and returns the first one that is a non-zero number.
 * If no such number is found, it returns 0.
 *
 * @param args A list of arguments to check.
 * @returns The first non-zero number, or 0 if no such number exists.
 */
export declare function defaultNumber(...args: any[]): number;