Skip to main content

Module 0x1::uq64_64

Defines an unsigned, fixed-point numeric type with a 64-bit integer part and a 64-bit fractional part. The notation uq64_64 and UQ64_64 is based on Q notation. q indicates it a fixed-point number. The u prefix indicates it is unsigned. The 64_64 suffix indicates the number of bits, where the first number indicates the number of bits in the integer part, and the second the number of bits in the fractional part--in this case 64 bits for each.

Struct UQ64_64​

A fixed-point numeric type with 64 integer bits and 64 fractional bits, represented by an underlying 128 bit value. This is a binary representation, so decimal values may not be exactly representable, but it provides more than 19 decimal digits of precision both before and after the decimal point (38 digits total).

struct UQ64_64 has copy, drop, store
Click to open
Fields
pos0: u128

Constants​

#[error]
const EDenominator: vector<u8> = b"Quotient specified with a zero denominator";


#[error]
const EDivisionByZero: vector<u8> = b"Division by zero";


#[error]
const EOverflow: vector<u8> = b"Overflow from an arithmetic operation";


#[error]
const EQuotientTooLarge: vector<u8> = b"Quotient specified is too large, and is outside of the supported range";


#[error]
const EQuotientTooSmall: vector<u8> = b"Quotient specified is too small, and is outside of the supported range";

The number of fractional bits in the fixed-point number. Used in macro invocations.

const FRACTIONAL_BITS: u8 = 64;

The total number of bits in the fixed-point number. Used in macro invocations.

const TOTAL_BITS: u8 = 128;

Function from_quotient​

Create a fixed-point value from a quotient specified by its numerator and denominator. from_quotient and from_int should be preferred over using from_raw. Unless the denominator is a power of two, fractions can not be represented accurately, so be careful about rounding errors. Aborts if the denominator is zero. Aborts if the input is non-zero but so small that it will be represented as zero, e.g. smaller than 2^{-64}. Aborts if the input is too large, e.g. larger than or equal to 2^64.

public fun from_quotient(numerator: u128, denominator: u128): uq64_64::UQ64_64
Click to open
Implementation
public fun from_quotient(numerator: u128, denominator: u128): UQ64_64 {
    UQ64_64(std::macros::uq_from_quotient!<u128, u256>(
        numerator,
        denominator,
        std::u128::max_value!(),
        TOTAL_BITS,
        FRACTIONAL_BITS,
        abort EDenominator,
        abort EQuotientTooSmall,
        abort EQuotientTooLarge,
    ))
}

Function from_int​

Create a fixed-point value from an integer. from_int and from_quotient should be preferred over using from_raw.

public fun from_int(integer: u64): uq64_64::UQ64_64
Click to open
Implementation
public fun from_int(integer: u64): UQ64_64 {
    UQ64_64(std::macros::uq_from_int!(integer, FRACTIONAL_BITS))
}

Function add​

Add two fixed-point numbers, a + b. Aborts if the sum overflows.

public fun add(a: uq64_64::UQ64_64, b: uq64_64::UQ64_64): uq64_64::UQ64_64
Click to open
Implementation
public fun add(a: UQ64_64, b: UQ64_64): UQ64_64 {
    UQ64_64(std::macros::uq_add!<u128, u256>(
        a.0,
        b.0,
        std::u128::max_value!(),
        abort EOverflow,
    ))
}

Function sub​

Subtract two fixed-point numbers, a - b. Aborts if a < b.

public fun sub(a: uq64_64::UQ64_64, b: uq64_64::UQ64_64): uq64_64::UQ64_64
Click to open
Implementation
public fun sub(a: UQ64_64, b: UQ64_64): UQ64_64 {
    UQ64_64(std::macros::uq_sub!(a.0, b.0, abort EOverflow))
}

Function mul​

Multiply two fixed-point numbers, truncating any fractional part of the product. Aborts if the product overflows.

public fun mul(a: uq64_64::UQ64_64, b: uq64_64::UQ64_64): uq64_64::UQ64_64
Click to open
Implementation
public fun mul(a: UQ64_64, b: UQ64_64): UQ64_64 {
    UQ64_64(int_mul(a.0, b))
}

Function div​

Divide two fixed-point numbers, truncating any fractional part of the quotient. Aborts if the divisor is zero. Aborts if the quotient overflows.

public fun div(a: uq64_64::UQ64_64, b: uq64_64::UQ64_64): uq64_64::UQ64_64
Click to open
Implementation
public fun div(a: UQ64_64, b: UQ64_64): UQ64_64 {
    UQ64_64(int_div(a.0, b))
}

Function to_int​

Convert a fixed-point number to an integer, truncating any fractional part.

public fun to_int(a: uq64_64::UQ64_64): u64
Click to open
Implementation
public fun to_int(a: UQ64_64): u64 {
    std::macros::uq_to_int!(a.0, FRACTIONAL_BITS)
}

Function int_mul​

Multiply a u128 integer by a fixed-point number, truncating any fractional part of the product. Aborts if the product overflows.

public fun int_mul(val: u128, multiplier: uq64_64::UQ64_64): u128
Click to open
Implementation
public fun int_mul(val: u128, multiplier: UQ64_64): u128 {
    std::macros::uq_int_mul!<u128, u256>(
        val,
        multiplier.0,
        std::u128::max_value!(),
        FRACTIONAL_BITS,
        abort EOverflow,
    )
}

Function int_div​

Divide a u128 integer by a fixed-point number, truncating any fractional part of the quotient. Aborts if the divisor is zero. Aborts if the quotient overflows.

public fun int_div(val: u128, divisor: uq64_64::UQ64_64): u128
Click to open
Implementation
public fun int_div(val: u128, divisor: UQ64_64): u128 {
    std::macros::uq_int_div!<u128, u256>(
        val,
        divisor.0,
        std::u128::max_value!(),
        FRACTIONAL_BITS,
        abort EDivisionByZero,
        abort EOverflow,
    )
}

Function le​

Less than or equal to. Returns true if and only if a <= a.

public fun le(a: uq64_64::UQ64_64, b: uq64_64::UQ64_64): bool
Click to open
Implementation
public fun le(a: UQ64_64, b: UQ64_64): bool {
    a.0 <= b.0
}

Function lt​

Less than. Returns true if and only if a < b.

public fun lt(a: uq64_64::UQ64_64, b: uq64_64::UQ64_64): bool
Click to open
Implementation
public fun lt(a: UQ64_64, b: UQ64_64): bool {
    a.0 < b.0
}

Function ge​

Greater than or equal to. Returns true if and only if a >= b.

public fun ge(a: uq64_64::UQ64_64, b: uq64_64::UQ64_64): bool
Click to open
Implementation
public fun ge(a: UQ64_64, b: UQ64_64): bool {
    a.0 >= b.0
}

Function gt​

Greater than. Returns true if and only if a > b.

public fun gt(a: uq64_64::UQ64_64, b: uq64_64::UQ64_64): bool
Click to open
Implementation
public fun gt(a: UQ64_64, b: UQ64_64): bool {
    a.0 > b.0
}

Function to_raw​

Accessor for the raw u128 value. Can be paired with from_raw to perform less common operations on the raw values directly.

public fun to_raw(a: uq64_64::UQ64_64): u128
Click to open
Implementation
public fun to_raw(a: UQ64_64): u128 {
    a.0
}

Function from_raw​

Accessor for the raw u128 value. Can be paired with to_raw to perform less common operations on the raw values directly.

public fun from_raw(raw_value: u128): uq64_64::UQ64_64
Click to open
Implementation
public fun from_raw(raw_value: u128): UQ64_64 {
    UQ64_64(raw_value)
}