@signumjs/util/out/chainValue.d.ts

Useful utilities and tools for building Signum Network applications

/**
 * Copyright (c) 2022 Signum Network
 */
import BigNumber from 'bignumber.js';
/**
 * Structure to determine the representation format of [ChainValue] string
 *
 * @category value-objects
 */
export interface ChainValueFormat {
    /**
     * Decimal separator, Default: '.'
     */
    decimalSeparator: string;
    /**
     * grouping separator of the integer part, Default: ','
     */
    groupSeparator: string;
    /**
     * Primary grouping size of the integer part, Default: 3
     */
    groupSize: number;
    /**
     * Secondary grouping size of the integer part, Default 0
     */
    secondaryGroupSize: number;
    /**
     * Grouping separator of the fraction part, Default: ''
     */
    fractionGroupSeparator: string;
    /**
     * Grouping size of the fraction part, Default: 0
     */
    fractionGroupSize: number;
    /**
     * String to append, Default: ''
     */
    suffix: string;
}
/**
 * Amount formatting presets, see {@link ChainValue.toFormat}
 *
 * @category value-objects
 */
export declare const ChainValueFormats: {
    /**
     * 1,000,000.123456
     */
    DotDecimal: ChainValueFormat;
    /**
     * 1.000.000,123456
     */
    CommaDecimal: ChainValueFormat;
};
/**
 * A Value Object to facilitate calculations for token and coin values (QNT/NQT).
 *
 *
 * For efficiency reasons, the monetary values/quantities are stored as integers with a prefined set of decimals,
 * e.g. Signa has 8 decimals and stores the values as Planck that is 1 Signa = 100_000_000 Planck (NQT)
 * and tokens have configurable decimals (0 to 8), so that a custom FooCoin can hav 2 decimals only where 1 FOO = 100 FOOQNT
 *
 * In this context integer quantities are denominates as __atomic_ values and
 * fractional values considering the decimals are denominated as _compound_ values.
 *
 *
 * Note: This class uses a big number representation (ES5 compatible) under the hood, so
 * number limits and numeric calculations are much more precise than JS number type
 *
 * @category value-objects
 */
export declare class ChainValue {
    private _big;
    private readonly _decimals;
    /**
     * Constructs a value object instance for calculations. The initial value is 0;
     * @param decimals The number of decimals of the amount. Must be between 0 and 8
     */
    constructor(decimals: number);
    /**
     * Constructs a value object instance for calculations. The initial value is 0;
     * @param decimals The number of decimals of the amount. Must be between 0 and 8
     */
    static create(decimals: number): ChainValue;
    /**
     * @return The set decimals amount
     */
    getDecimals(): number;
    /**
     * Leaky value getter
     * @return the underlying value in its big number representation (immutable)
     */
    getRaw(): BigNumber;
    /**
     * @return Gets Atomic representation
     */
    getAtomic(): string;
    /**
     * Sets value as atomic value, i.e. overwrites current hold value
     * @param a The atomic value. Float numbers are floored to first lower integer, i.e. `1.23` -> `1`
     * @return the updated value object
     */
    setAtomic(a: number | string): ChainValue;
    /**
     * Gets the _'compound'_ representation
     * @return value in decimal related representation, i.e. 100 QNT with 3 decimals results in `'0.3'`
     */
    getCompound(): string;
    /**
     * Sets as _'compound'_ representation
     * @param c compound value
     * @return the updated value object
     */
    setCompound(c: string | number): ChainValue;
    /**
     * Checks for equality
     * @param value The other value to be compared
     * @return true if equal, otherwise false
     */
    equals(value: ChainValue): boolean;
    /**
     * Checks for lesser or equality
     * @param chainValue The other value to be compared
     * @return true if less or equal, otherwise false
     */
    lessOrEqual(chainValue: ChainValue): boolean;
    /**
     * Checks for lesser value
     * @param chainValue The other value to be compared
     * @return true if less, otherwise false
     */
    less(chainValue: ChainValue): boolean;
    /**
     * Checks for greater or equality value
     * @param chainValue The other value to be compared
     * @return true if greater or equal, otherwise false
     */
    greaterOrEqual(chainValue: ChainValue): boolean;
    /**
     * Checks for greater value
     * @param chainValue The other value to be compared
     * @return true if greater, otherwise false
     */
    greater(chainValue: ChainValue): boolean;
    /**
     * Adds another value to this value
     * @param chainValue The other value to be added
     * @return the _mutated_ value object
     */
    add(chainValue: ChainValue): ChainValue;
    /**
     * Subtracts another value from this value
     * @param chainValue The other value to be subtracted
     * @return the _mutated_ value object
     */
    subtract(chainValue: ChainValue): ChainValue;
    /**
     * Multiplies this value object with a _numeric_ value (not ChainValue!)
     * @param value A numeric value to be multiplied with
     * @return the _mutated_ value object
     */
    multiply(value: number | string): ChainValue;
    /**
     * Divides this value object with a _numeric_ value (not ChainValue!)
     * @param value A numeric value to be divided by
     * @return the _mutated_ value object
     */
    divide(value: number | string): ChainValue;
    /**
     * Gets a string representation according to {@link ChainValueFormat}
     * @param prefix The prefix for value
     * @param format The format object, Default: {@link ChainValueFormats.DotDecimal}
     * @return The formatted string
     */
    toFormat(prefix: string, format?: ChainValueFormat): string;
    /**
     * Clones/Copies the current ChainValue to a new object
     * @return new ChainValue instance
     */
    clone(): ChainValue;
}