ethers.js/lib.commonjs/utils/fixednumber.d.ts
2023-06-13 21:47:44 -04:00

252 lines
8.9 KiB
TypeScript

import type { BigNumberish, BytesLike, Numeric } from "./index.js";
/**
* A description of a fixed-point arithmetic field.
*
* When specifying the fixed format, the values override the default of
* a ``fixed128x18``, which implies a signed 128-bit value with 18
* decimals of precision.
*
* The alias ``fixed`` and ``ufixed`` can be used for ``fixed128x18`` and
* ``ufixed128x18`` respectively.
*
* When a fixed format string begins with a ``u``, it indicates the field
* is unsigned, so any negative values will overflow. The first number
* indicates the bit-width and the second number indicates the decimal
* precision.
*
* When a ``number`` is used for a fixed format, it indicates the number
* of decimal places, and the default width and signed-ness will be used.
*
* The bit-width must be byte aligned and the decimals can be at most 80.
*/
export type FixedFormat = number | string | {
signed?: boolean;
width?: number;
decimals?: number;
};
/**
* A FixedNumber represents a value over its [[FixedFormat]]
* arithmetic field.
*
* A FixedNumber can be used to perform math, losslessly, on
* values which have decmial places.
*
* A FixedNumber has a fixed bit-width to store values in, and stores all
* values internally by multiplying the value by 10 raised to the power of
* %%decimals%%.
*
* If operations are performed that cause a value to grow too high (close to
* positive infinity) or too low (close to negative infinity), the value
* is said to //overflow//.
*
* For example, an 8-bit signed value, with 0 decimals may only be within
* the range ``-128`` to ``127``; so ``-128 - 1`` will overflow and become
* ``127``. Likewise, ``127 + 1`` will overflow and become ``-127``.
*
* Many operation have a normal and //unsafe// variant. The normal variant
* will throw a [[NumericFaultError]] on any overflow, while the //unsafe//
* variant will silently allow overflow, corrupting its value value.
*
* If operations are performed that cause a value to become too small
* (close to zero), the value loses precison and is said to //underflow//.
*
* For example, an value with 1 decimal place may store a number as small
* as ``0.1``, but the value of ``0.1 / 2`` is ``0.05``, which cannot fit
* into 1 decimal place, so underflow occurs which means precision is lost
* and the value becomes ``0``.
*
* Some operations have a normal and //signalling// variant. The normal
* variant will silently ignore underflow, while the //signalling// variant
* will thow a [[NumericFaultError]] on underflow.
*/
export declare class FixedNumber {
#private;
/**
* The specific fixed-point arithmetic field for this value.
*/
readonly format: string;
/**
* This is a property so console.log shows a human-meaningful value.
*
* @private
*/
readonly _value: string;
/**
* @private
*/
constructor(guard: any, value: bigint, format: any);
/**
* If true, negative values are permitted, otherwise only
* positive values and zero are allowed.
*/
get signed(): boolean;
/**
* The number of bits available to store the value.
*/
get width(): number;
/**
* The number of decimal places in the fixed-point arithment field.
*/
get decimals(): number;
/**
* The value as an integer, based on the smallest unit the
* [[decimals]] allow.
*/
get value(): bigint;
/**
* Returns a new [[FixedNumber]] with the result of %%this%% added
* to %%other%%, ignoring overflow.
*/
addUnsafe(other: FixedNumber): FixedNumber;
/**
* Returns a new [[FixedNumber]] with the result of %%this%% added
* to %%other%%. A [[NumericFaultError]] is thrown if overflow
* occurs.
*/
add(other: FixedNumber): FixedNumber;
/**
* Returns a new [[FixedNumber]] with the result of %%other%% subtracted
* from %%this%%, ignoring overflow.
*/
subUnsafe(other: FixedNumber): FixedNumber;
/**
* Returns a new [[FixedNumber]] with the result of %%other%% subtracted
* from %%this%%. A [[NumericFaultError]] is thrown if overflow
* occurs.
*/
sub(other: FixedNumber): FixedNumber;
/**
* Returns a new [[FixedNumber]] with the result of %%this%% multiplied
* by %%other%%, ignoring overflow and underflow (precision loss).
*/
mulUnsafe(other: FixedNumber): FixedNumber;
/**
* Returns a new [[FixedNumber]] with the result of %%this%% multiplied
* by %%other%%. A [[NumericFaultError]] is thrown if overflow
* occurs.
*/
mul(other: FixedNumber): FixedNumber;
/**
* Returns a new [[FixedNumber]] with the result of %%this%% multiplied
* by %%other%%. A [[NumericFaultError]] is thrown if overflow
* occurs or if underflow (precision loss) occurs.
*/
mulSignal(other: FixedNumber): FixedNumber;
/**
* Returns a new [[FixedNumber]] with the result of %%this%% divided
* by %%other%%, ignoring underflow (precision loss). A
* [[NumericFaultError]] is thrown if overflow occurs.
*/
divUnsafe(other: FixedNumber): FixedNumber;
/**
* Returns a new [[FixedNumber]] with the result of %%this%% divided
* by %%other%%, ignoring underflow (precision loss). A
* [[NumericFaultError]] is thrown if overflow occurs.
*/
div(other: FixedNumber): FixedNumber;
/**
* Returns a new [[FixedNumber]] with the result of %%this%% divided
* by %%other%%. A [[NumericFaultError]] is thrown if underflow
* (precision loss) occurs.
*/
divSignal(other: FixedNumber): FixedNumber;
/**
* Returns a comparison result between %%this%% and %%other%%.
*
* This is suitable for use in sorting, where ``-1`` implies %%this%%
* is smaller, ``1`` implies %%this%% is larger and ``0`` implies
* both are equal.
*/
cmp(other: FixedNumber): number;
/**
* Returns true if %%other%% is equal to %%this%%.
*/
eq(other: FixedNumber): boolean;
/**
* Returns true if %%other%% is less than to %%this%%.
*/
lt(other: FixedNumber): boolean;
/**
* Returns true if %%other%% is less than or equal to %%this%%.
*/
lte(other: FixedNumber): boolean;
/**
* Returns true if %%other%% is greater than to %%this%%.
*/
gt(other: FixedNumber): boolean;
/**
* Returns true if %%other%% is greater than or equal to %%this%%.
*/
gte(other: FixedNumber): boolean;
/**
* Returns a new [[FixedNumber]] which is the largest **integer**
* that is less than or equal to %%this%%.
*
* The decimal component of the result will always be ``0``.
*/
floor(): FixedNumber;
/**
* Returns a new [[FixedNumber]] which is the smallest **integer**
* that is greater than or equal to %%this%%.
*
* The decimal component of the result will always be ``0``.
*/
ceiling(): FixedNumber;
/**
* Returns a new [[FixedNumber]] with the decimal component
* rounded up on ties at %%decimals%% places.
*/
round(decimals?: number): FixedNumber;
/**
* Returns true if %%this%% is equal to ``0``.
*/
isZero(): boolean;
/**
* Returns true if %%this%% is less than ``0``.
*/
isNegative(): boolean;
/**
* Returns the string representation of %%this%%.
*/
toString(): string;
/**
* Returns a float approximation.
*
* Due to IEEE 754 precission (or lack thereof), this function
* can only return an approximation and most values will contain
* rounding errors.
*/
toUnsafeFloat(): number;
/**
* Return a new [[FixedNumber]] with the same value but has had
* its field set to %%format%%.
*
* This will throw if the value cannot fit into %%format%%.
*/
toFormat(format: FixedFormat): FixedNumber;
/**
* Creates a new [[FixedNumber]] for %%value%% divided by
* %%decimal%% places with %%format%%.
*
* This will throw a [[NumericFaultError]] if %%value%% (once adjusted
* for %%decimals%%) cannot fit in %%format%%, either due to overflow
* or underflow (precision loss).
*/
static fromValue(_value: BigNumberish, _decimals?: Numeric, _format?: FixedFormat): FixedNumber;
/**
* Creates a new [[FixedNumber]] for %%value%% with %%format%%.
*
* This will throw a [[NumericFaultError]] if %%value%% cannot fit
* in %%format%%, either due to overflow or underflow (precision loss).
*/
static fromString(_value: string, _format?: FixedFormat): FixedNumber;
/**
* Creates a new [[FixedNumber]] with the big-endian representation
* %%value%% with %%format%%.
*
* This will throw a [[NumericFaultError]] if %%value%% cannot fit
* in %%format%% due to overflow.
*/
static fromBytes(_value: BytesLike, _format?: FixedFormat): FixedNumber;
}
//# sourceMappingURL=fixednumber.d.ts.map