stellar-plus/lib/stellar-plus/utils/unit-conversion/index.d.ts

beta version of stellar-plus, an all-in-one sdk for the Stellar blockchain

/**
 * Converts an amount from its decimal representation.
 *
 * This function takes an amount, either as a number or bigint, and a specified number of decimal places,
 * and returns the amount divided by 10 to the power of the decimal places.
 *
 * @param amount - The amount to convert, either as a number or bigint.
 * @param decimal - The number of decimal places to consider.
 * @returns The amount converted from its decimal representation.
 *
 * @example
 * // Converts 10000000 to 1 with 7 decimal places
 * const result = fromDecimals(10000000, 7);
 */
export declare const fromDecimals: <T extends number | bigint>(amount: T, decimal: number) => T;
/**
 * Converts an amount to its decimal representation.
 *
 * This function takes an amount, either as a number or bigint, and a specified number of decimal places,
 * and returns the amount multiplied by 10 to the power of the decimal places.
 *
 * @param amount - The amount to convert, either as a number or bigint.
 * @param decimal - The number of decimal places to consider.
 * @returns The amount converted to its decimal representation.
 *
 * @example
 * // Converts 1 to 10000000 with 7 decimal places
 * const result = toDecimals(1, 7);
 */
export declare const toDecimals: <T extends number | bigint>(amount: T, decimal: number) => T;
/**
 * Converts an amount from Stroops to the standard unit.
 *
 * This function takes an amount in Stroops (smallest unit), either as a number or bigint,
 * and converts it to the standard unit by dividing by 10^7.
 *
 * @param amount - The amount in Stroops, either as a number or bigint.
 * @returns The amount converted from Stroops.
 *
 * @example
 * // Converts 10000000 Stroops to 1 standard unit
 * const result = fromStroops(10000000);
 */
export declare const fromStroops: <T extends number | bigint>(amount: T) => T;
/**
 * Converts an amount to Stroops from the standard unit.
 *
 * This function takes an amount in the standard unit, either as a number or bigint,
 * and converts it to Stroops (smallest unit) by multiplying by 10^7.
 *
 * @param amount - The amount to convert, either as a number or bigint.
 * @returns The amount converted to Stroops.
 *
 * @example
 * // Converts 1 standard unit to 10000000 Stroops
 * const result = toStroops(1);
 */
export declare const toStroops: <T extends number | bigint>(amount: T) => T;
/**
 * Converts a number balance to its string representation with a specified number of decimal places.
 *
 * This function takes a number and converts it to a string with the specified number of decimal places.
 * It handles rounding and ensures the fractional part is padded with zeros if necessary.
 *
 * @param amount - The number balance to convert.
 * @param decimal - The number of decimal places to include in the string.
 * @returns The string representation of the number balance.
 *
 * @example
 * // Converts 123.456 to '123.4560' with 4 decimal places
 * const result = numberBalanceToString(123.456, 4);
 */
export declare const numberBalanceToString: (amount: number, decimal: number) => string;
/**
 * Converts a string representation of a number balance to its numeric form.
 *
 * This function takes a string representing a number with a decimal point and converts it to a number.
 * It handles both integer and fractional parts.
 *
 * @param amountStr - The string representation of the number balance.
 * @returns The numeric form of the balance.
 *
 * @example
 * // Converts '123.456' to 123.456
 * const result = numberBalanceFromString('123.456');
 */
export declare const numberBalanceFromString: (amountStr: string) => number;
/**
 * Converts a bigint balance to its string representation with a specified number of decimal places.
 *
 * The bigint number will be considered as the whole number to be partitioned with the specified decimals.
 * When the number of decimals is 0, no "." will be added.
 *
 * @param amount - The bigint balance to convert.
 * @param decimal - The number of decimal places to include in the string.
 * @returns The string representation of the bigint balance.
 *
 * @example
 * // Converts 123456n to '1234.56' with 2 decimal places
 * const result = bigIntBalanceToString(123456n, 2);
 */
export declare const bigIntBalanceToString: (amount: bigint, decimal: number) => string;
/**
 * Converts a string representation of a bigint balance to its bigint form.
 *
 * This function takes a string representing a bigint with a decimal point and converts it to a bigint.
 * It handles both integer and fractional parts by removing the decimal point and concatenating the parts.
 *
 * @param amountStr - The string representation of the bigint balance.
 * @returns The bigint form of the balance.
 *
 * @example
 * // Converts '1234.56' to 123456n
 * const result = bigIntBalanceFromString('1234.56');
 */
export declare const bigIntBalanceFromString: (amountStr: string) => bigint;
/**
 * Converts a balance to its string representation with a specified number of decimal places.
 *
 * This function takes a balance, either as a number or bigint, and converts it to a string with the specified number of decimal places.
 * It delegates the conversion to either `numberBalanceToString` or `bigIntBalanceToString` based on the type of the balance.
 *
 * @param amount - The balance to convert, either as a number or bigint.
 * @param decimal - The number of decimal places to include in the string.
 * @returns The string representation of the balance.
 *
 * @example
 * // Converts 123.456 to '123.4560' with 4 decimal places
 * const result = balanceToString(123.456, 4);
 *
 * // Converts 123456n to '1234.56' with 2 decimal places
 * const result = balanceToString(123456n, 2);
 */
export declare const balanceToString: <T extends number | bigint>(amount: T, decimal: number) => string;