FixedNumber

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

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

​

Returns

FixedNumber

The FixedNumber for value.

​

Source

utils/fixednumber.ts:648