252 lines
8.9 KiB
TypeScript
252 lines
8.9 KiB
TypeScript
import type { BigNumberish, BytesLike } 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 %%other%% 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?: number, _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;
|
|
}
|