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
| 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
signed
get signed(): boolean
If true, negative values are permitted, otherwise only positive values and zero are allowed.
Returns
boolean
Source
value
get value(): bigint
The value as an integer, based on the smallest unit the decimals allow.
Returns
bigint
Source
width
get width(): number
The number of bits available to store the value.
Returns
number
Source
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
The result of the addition.
Source
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
The result of the addition.
Source
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
The ceiling value.
Source
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
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
The result of the division.
Source
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
The result of the division.
Throws
Thrown if underflow occurs.
Source
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
The result of the division.
Source
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
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
The floored value.
Source
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
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
isNegative()
isNegative(): boolean
Returns true if this is less than 0.
Returns
boolean
True if this is less than 0.
Source
isZero()
isZero(): boolean
Returns true if this is equal to 0.
Returns
boolean
True if this is equal to 0.
Source
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
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
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
The result of the multiplication.
Source
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
The result of the multiplication.
Throws
Thrown if overflow or underflow occurs.
Throws
Thrown if division by 0 occurs.
Source
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
The result of the multiplication.
Source
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
The rounded value.
Source
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
The result of the subtraction.
Source
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
The result of the subtraction.
Source
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
Source
toString()
toString(): string
Returns the string representation of this.
Returns
string
The string representation.
Source
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
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
The FixedNumber for value.
Source
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
The FixedNumber for value.
Source
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
The FixedNumber for value.
Source
Was this page helpful?