Documentation

Documentation »API »Utilities »Fixed-Point Maths

Fixed-Point Maths

The FixedNumber class permits using values with decimal places, using fixed-pont math.

Fixed-point math is still based on integers under-the-hood, but uses an internal offset to store fractional components below, and each operation corrects for this after each operation.

TYPES

<src>FixedFormat⇒ number | string | { decimals?: number , signed?: boolean , width?: number }

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.

class 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

<src>fixedNumber.decimals⇒ numberread-only

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

<src>fixedNumber.format⇒ stringread-only

The specific fixed-point arithmetic field for this value.

<src>fixedNumber.signed⇒ booleanread-only

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

<src>fixedNumber.value⇒ bigintread-only

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

<src>fixedNumber.width⇒ numberread-only

The number of bits available to store the value.

CREATING INSTANCES

<src>FixedNumber.fromBytes(value: BytesLike, 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.

<src>FixedNumber.fromString(value: string, 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).

<src>FixedNumber.fromValue(value: BigNumberish, decimals?: Numeric, 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).

METHODS

<src>fixedNumber.add(other: FixedNumber)⇒ FixedNumber

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

<src>fixedNumber.addUnsafe(other: FixedNumber)⇒ FixedNumber

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

<src>fixedNumber.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.

<src>fixedNumber.cmp(other: FixedNumber)⇒ 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.

<src>fixedNumber.div(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.

<src>fixedNumber.divSignal(other: FixedNumber)⇒ FixedNumber

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

<src>fixedNumber.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.

<src>fixedNumber.eq(other: FixedNumber)⇒ boolean

Returns true if other is equal to this.

<src>fixedNumber.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.

<src>fixedNumber.gt(other: FixedNumber)⇒ boolean

Returns true if other is greater than to this.

<src>fixedNumber.gte(other: FixedNumber)⇒ boolean

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

<src>fixedNumber.isNegative()⇒ boolean

Returns true if this is less than 0.

<src>fixedNumber.isZero()⇒ boolean

Returns true if this is equal to 0.

<src>fixedNumber.lt(other: FixedNumber)⇒ boolean

Returns true if other is less than to this.

<src>fixedNumber.lte(other: FixedNumber)⇒ boolean

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

<src>fixedNumber.mul(other: FixedNumber)⇒ FixedNumber

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

<src>fixedNumber.mulSignal(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.

<src>fixedNumber.mulUnsafe(other: FixedNumber)⇒ FixedNumber

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

<src>fixedNumber.round(decimals?: number)⇒ FixedNumber

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

<src>fixedNumber.sub(other: FixedNumber)⇒ FixedNumber

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

<src>fixedNumber.subUnsafe(other: FixedNumber)⇒ FixedNumber

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

<src>fixedNumber.toFormat(format: FixedFormat)⇒ 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.

<src>fixedNumber.toString()⇒ string

Returns the string representation of this.

<src>fixedNumber.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.