FixedNumber - Quai Network Docs

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.

Properties

Property	Modifier	Type	Description
`format`	`readonly`	`string`	The specific fixed-point arithmetic field for this value.

Accessors

decimals

get decimals(): number

The number of decimal places in the fixed-point arithment field.

Returns

number

Source

utils/fixednumber.ts:266

signed

get signed(): boolean

If true, negative values are permitted, otherwise only positive values and zero are allowed.

Returns

boolean

Source

utils/fixednumber.ts:252

value

get value(): bigint

The value as an integer, based on the smallest unit the decimals allow.

Returns

bigint

Source

utils/fixednumber.ts:273

width

get width(): number

The number of bits available to store the value.

Returns

number

Source

utils/fixednumber.ts:259

Methods

add()

add(other): FixedNumber

Returns a new FixedNumber with the result of this added to other. A NumericFaultError is thrown if overflow occurs.

Parameters

Parameter	Type	Description
`other`	`FixedNumber`	The value to add to `this`.

Returns

FixedNumber The result of the addition.

Source

utils/fixednumber.ts:308

addUnsafe()

addUnsafe(other): FixedNumber

Returns a new FixedNumber with the result of this added to other, ignoring overflow.

Parameters

Parameter	Type	Description
`other`	`FixedNumber`	The value to add to `this`.

Returns

FixedNumber The result of the addition.

Source

utils/fixednumber.ts:297

ceiling()

ceiling(): 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.

Returns

FixedNumber The ceiling value.

Source

utils/fixednumber.ts:549

cmp()

cmp(other): number

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.

Parameters

Parameter	Type	Description
`other`	`FixedNumber`	The value to compare to `this`.

Returns

number The comparison result.

Source

utils/fixednumber.ts:452

div()

div(other): FixedNumber

Returns a new FixedNumber with the result of this divided by other, ignoring underflow (precision loss). A NumericFaultError is thrown if overflow occurs.

Parameters

Parameter	Type	Description
`other`	`FixedNumber`	The value to divide `this` by.

Returns

FixedNumber The result of the division.

Source

utils/fixednumber.ts:415

divSignal()

divSignal(other): FixedNumber

Returns a new FixedNumber with the result of this divided by other. A NumericFaultError is thrown if underflow (precision loss) occurs.

Parameters

Parameter	Type	Description
`other`	`FixedNumber`	The value to divide `this` by.

Returns

FixedNumber The result of the division.

Throws

Thrown if underflow occurs.

Source

utils/fixednumber.ts:427

divUnsafe()

divUnsafe(other): FixedNumber

Returns a new FixedNumber with the result of this divided by other, ignoring underflow (precision loss). A NumericFaultError is thrown if overflow occurs.

Parameters

Parameter	Type	Description
`other`	`FixedNumber`	The value to divide `this` by.

Returns

FixedNumber The result of the division.

Source

utils/fixednumber.ts:404

eq()

eq(other): boolean

Returns true if other is equal to this.

Parameters

Parameter	Type	Description
`other`	`FixedNumber`	The value to compare to `this`.

Returns

boolean True if other is equal to this.

Source

utils/fixednumber.ts:480

floor()

floor(): FixedNumber

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.

Returns

FixedNumber The floored value.

Source

utils/fixednumber.ts:532

gt()

gt(other): boolean

Returns true if other is greater than to this.

Parameters

Parameter	Type	Description
`other`	`FixedNumber`	The value to compare to `this`.

Returns

boolean True if other is greater than to this.

Source

utils/fixednumber.ts:510

gte()

gte(other): boolean

Returns true if other is greater than or equal to this.

Parameters

Parameter	Type	Description
`other`	`FixedNumber`	The value to compare to `this`.

Returns

boolean True if other is greater than or equal to this.

Source

utils/fixednumber.ts:520

isNegative()

isNegative(): boolean

Returns true if this is less than 0.

Returns

boolean True if this is less than 0.

Source

utils/fixednumber.ts:601

isZero()

isZero(): boolean

Returns true if this is equal to 0.

Returns

boolean True if this is equal to 0.

Source

utils/fixednumber.ts:592

lt()

lt(other): boolean

Returns true if other is less than to this.

Parameters

Parameter	Type	Description
`other`	`FixedNumber`	The value to compare to `this`.

Returns

boolean True if other is less than to this.

Source

utils/fixednumber.ts:490

lte()

lte(other): boolean

Returns true if other is less than or equal to this.

Parameters

Parameter	Type	Description
`other`	`FixedNumber`	The value to compare to `this`.

Returns

boolean True if other is less than or equal to this.

Source

utils/fixednumber.ts:500

mul()

mul(other): FixedNumber

Returns a new FixedNumber with the result of this multiplied by other. A NumericFaultError is thrown if overflow occurs.

Parameters

Parameter	Type	Description
`other`	`FixedNumber`	The value to multiply `this` by.

Returns

FixedNumber The result of the multiplication.

Source

utils/fixednumber.ts:362

mulSignal()

mulSignal(other): 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.

Parameters

Parameter	Type	Description
`other`	`FixedNumber`	The value to multiply `this` by.

Returns

FixedNumber The result of the multiplication.

Throws

Thrown if overflow or underflow occurs.

Throws

Thrown if division by 0 occurs.

Source

utils/fixednumber.ts:376

mulUnsafe()

mulUnsafe(other): FixedNumber

Returns a new FixedNumber with the result of this multiplied by other, ignoring overflow and underflow (precision loss).

Parameters

Parameter	Type	Description
`other`	`FixedNumber`	The value to multiply `this` by.

Returns

FixedNumber The result of the multiplication.

Source

utils/fixednumber.ts:351

round()

round(decimals?): FixedNumber

Returns a new FixedNumber with the decimal component rounded up on ties at decimals places.

Parameters

Parameter	Type	Description
`decimals`?	`number`	The number of decimal places to round to.

Returns

FixedNumber The rounded value.

Source

utils/fixednumber.ts:565

sub()

sub(other): FixedNumber

Returns a new FixedNumber with the result of other subtracted from this. A NumericFaultError is thrown if overflow occurs.

Parameters

Parameter	Type	Description
`other`	`FixedNumber`	The value to subtract from `this`.

Returns

FixedNumber The result of the subtraction.

Source

utils/fixednumber.ts:335

subUnsafe()

subUnsafe(other): FixedNumber

Returns a new FixedNumber with the result of other subtracted from this, ignoring overflow.

Parameters

Parameter	Type	Description
`other`	`FixedNumber`	The value to subtract from `this`.

Returns

FixedNumber The result of the subtraction.

Source

utils/fixednumber.ts:324

toFormat()

toFormat(format): FixedNumber

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.

Parameters

Parameter	Type	Description
`format`	`FixedFormat`	The new format for the value.

Returns

FixedNumber

Source

utils/fixednumber.ts:633

toString()

toString(): string

Returns the string representation of this.

Returns

string The string representation.

Source

utils/fixednumber.ts:610

toUnsafeFloat()

toUnsafeFloat(): number

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.

Returns

number The float approximation.

Source

utils/fixednumber.ts:622

fromBytes()

static fromBytes(_value, _format?): 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.

Parameters

Parameter	Type	Description
`_value`	`BytesLike`	The big-endian representation of the value.
`_format`?	`FixedFormat`	The format for the FixedNumber.

Returns

FixedNumber The FixedNumber for value.

Source

utils/fixednumber.ts:727

fromString()

static fromString(_value, _format?): 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).

Parameters

Parameter	Type	Description
`_value`	`string`	The value to create a FixedNumber for.
`_format`?	`FixedFormat`	The format for the FixedNumber.

Returns

FixedNumber The FixedNumber for value.

Source

utils/fixednumber.ts:681

fromValue()

static fromValue(
   _value, 
   _decimals?, 
   _format?): 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).

Parameters

Parameter	Type	Description
`_value`	`BigNumberish`	The value to create a FixedNumber for.
`_decimals`?	`Numeric`	The number of decimal places in `value`.
`_format`?	`FixedFormat`	The format for the FixedNumber.

Returns

FixedNumber The FixedNumber for value.

Source

utils/fixednumber.ts:648

​Properties

​Accessors

​decimals

​Returns

​Source

​signed

​Returns

​Source

​value

​Returns

​Source

​width

​Returns

​Source

​Methods

​add()

​Parameters

​Returns

​Source

​addUnsafe()

​Parameters

​Returns

​Source

​ceiling()

​Returns

​Source

​cmp()

​Parameters

​Returns

​Source

​div()

​Parameters

​Returns

​Source

​divSignal()

​Parameters

​Returns

​Throws

​Source

​divUnsafe()

​Parameters

​Returns

​Source

​eq()

​Parameters

​Returns

​Source

​floor()

​Returns

​Source

​gt()

​Parameters

​Returns

​Source

​gte()

​Parameters

​Returns

​Source

​isNegative()

​Returns

​Source

​isZero()

​Returns

​Source

​lt()

​Parameters

​Returns

​Source

​lte()

​Parameters

​Returns

​Source

​mul()

​Parameters

​Returns

​Source

​mulSignal()

​Parameters

​Returns

​Throws

Properties

Accessors

decimals

Returns

Source

signed

Returns

Source

value

Returns

Source

width

Returns

Source

Methods

add()

Parameters

Returns

Source

addUnsafe()

Parameters

Returns

Source

ceiling()

Returns

Source

cmp()

Parameters

Returns

Source

div()

Parameters

Returns

Source

divSignal()

Parameters

Returns

Throws

Source

divUnsafe()

Parameters

Returns

Source

eq()

Parameters

Returns

Source

floor()

Returns

Source

gt()

Parameters

Returns

Source

gte()

Parameters

Returns

Source

isNegative()

Returns

Source

isZero()

Returns

Source

lt()

Parameters

Returns

Source

lte()

Parameters

Returns

Source

mul()

Parameters

Returns

Source

mulSignal()

Parameters

Returns

Throws