ContextQMD
Back to Sui

Module `std::uq64_64`

external-crates/move/crates/move-stdlib/docs/std/uq64_64.md

latest20.1 KB
Original Source

<a name="std_uq64_64"></a>

Module std::uq64_64

Defines an unsigned, fixed-point numeric type with a 64-bit integer part and a 64-bit fractional part. The notation <code><a href="../std/uq64_64.md#std_uq64_64">uq64_64</a></code> and <code><a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a></code> is based on Q notation. <code>q</code> indicates it a fixed-point number. The <code>u</code> prefix indicates it is unsigned. The <code>64_64</code> 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.

<pre><code></code></pre>

<a name="std_uq64_64_UQ64_64"></a>

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).

<pre><code><b>public</b> <b>struct</b> <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a> <b>has</b> <b>copy</b>, drop, store </code></pre> <details> <summary>Fields</summary> <dl> <dt> <code>0: <a href="../std/u128.md#std_u128">u128</a></code> </dt> <dd> </dd> </dl> </details>

<a name="@Constants_0"></a>

Constants

<a name="std_uq64_64_EDenominator"></a>

<pre><code>#[error] <b>const</b> <a href="../std/uq64_64.md#std_uq64_64_EDenominator">EDenominator</a>: <a href="../std/vector.md#std_vector">vector</a>&lt;<a href="../std/u8.md#std_u8">u8</a>&gt; = b"Quotient specified with a zero denominator"; </code></pre>

<a name="std_uq64_64_EQuotientTooSmall"></a>

<pre><code>#[error] <b>const</b> <a href="../std/uq64_64.md#std_uq64_64_EQuotientTooSmall">EQuotientTooSmall</a>: <a href="../std/vector.md#std_vector">vector</a>&lt;<a href="../std/u8.md#std_u8">u8</a>&gt; = b"Quotient specified is too small, and is outside of the supported range"; </code></pre>

<a name="std_uq64_64_EQuotientTooLarge"></a>

<pre><code>#[error] <b>const</b> <a href="../std/uq64_64.md#std_uq64_64_EQuotientTooLarge">EQuotientTooLarge</a>: <a href="../std/vector.md#std_vector">vector</a>&lt;<a href="../std/u8.md#std_u8">u8</a>&gt; = b"Quotient specified is too large, and is outside of the supported range"; </code></pre>

<a name="std_uq64_64_EOverflow"></a>

<pre><code>#[error] <b>const</b> <a href="../std/uq64_64.md#std_uq64_64_EOverflow">EOverflow</a>: <a href="../std/vector.md#std_vector">vector</a>&lt;<a href="../std/u8.md#std_u8">u8</a>&gt; = b"Overflow from an arithmetic operation"; </code></pre>

<a name="std_uq64_64_EDivisionByZero"></a>

<pre><code>#[error] <b>const</b> <a href="../std/uq64_64.md#std_uq64_64_EDivisionByZero">EDivisionByZero</a>: <a href="../std/vector.md#std_vector">vector</a>&lt;<a href="../std/u8.md#std_u8">u8</a>&gt; = b"Division by zero"; </code></pre>

<a name="std_uq64_64_TOTAL_BITS"></a>

The total number of bits in the fixed-point number. Used in <code><b>macro</b></code> invocations.

<pre><code><b>const</b> <a href="../std/uq64_64.md#std_uq64_64_TOTAL_BITS">TOTAL_BITS</a>: <a href="../std/u8.md#std_u8">u8</a> = 128; </code></pre>

<a name="std_uq64_64_FRACTIONAL_BITS"></a>

The number of fractional bits in the fixed-point number. Used in <code><b>macro</b></code> invocations.

<pre><code><b>const</b> <a href="../std/uq64_64.md#std_uq64_64_FRACTIONAL_BITS">FRACTIONAL_BITS</a>: <a href="../std/u8.md#std_u8">u8</a> = 64; </code></pre>

<a name="std_uq64_64_from_quotient"></a>

Function from_quotient

Create a fixed-point value from a quotient specified by its numerator and denominator. <code><a href="../std/uq64_64.md#std_uq64_64_from_quotient">from_quotient</a></code> and <code><a href="../std/uq64_64.md#std_uq64_64_from_int">from_int</a></code> should be preferred over using <code><a href="../std/uq64_64.md#std_uq64_64_from_raw">from_raw</a></code>. 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.

<pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_from_quotient">from_quotient</a>(numerator: <a href="../std/u128.md#std_u128">u128</a>, denominator: <a href="../std/u128.md#std_u128">u128</a>): <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_from_quotient">from_quotient</a>(numerator: <a href="../std/u128.md#std_u128">u128</a>, denominator: <a href="../std/u128.md#std_u128">u128</a>): <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a> { <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>( <a href="../std/macros.md#std_macros_uq_from_quotient">std::macros::uq_from_quotient</a>!&lt;<a href="../std/u128.md#std_u128">u128</a>, <a href="../std/u256.md#std_u256">u256</a>&gt;( numerator, denominator, <a href="../std/u128.md#std_u128_max_value">std::u128::max_value</a>!(), <a href="../std/uq64_64.md#std_uq64_64_TOTAL_BITS">TOTAL_BITS</a>, <a href="../std/uq64_64.md#std_uq64_64_FRACTIONAL_BITS">FRACTIONAL_BITS</a>, <b>abort</b> <a href="../std/uq64_64.md#std_uq64_64_EDenominator">EDenominator</a>, <b>abort</b> <a href="../std/uq64_64.md#std_uq64_64_EQuotientTooSmall">EQuotientTooSmall</a>, <b>abort</b> <a href="../std/uq64_64.md#std_uq64_64_EQuotientTooLarge">EQuotientTooLarge</a>, ), ) } </code></pre> </details>

<a name="std_uq64_64_from_int"></a>

Function from_int

Create a fixed-point value from an integer. <code><a href="../std/uq64_64.md#std_uq64_64_from_int">from_int</a></code> and <code><a href="../std/uq64_64.md#std_uq64_64_from_quotient">from_quotient</a></code> should be preferred over using <code><a href="../std/uq64_64.md#std_uq64_64_from_raw">from_raw</a></code>.

<pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_from_int">from_int</a>(integer: <a href="../std/u64.md#std_u64">u64</a>): <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_from_int">from_int</a>(integer: <a href="../std/u64.md#std_u64">u64</a>): <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a> { <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>(<a href="../std/macros.md#std_macros_uq_from_int">std::macros::uq_from_int</a>!(integer, <a href="../std/uq64_64.md#std_uq64_64_FRACTIONAL_BITS">FRACTIONAL_BITS</a>)) } </code></pre> </details>

<a name="std_uq64_64_add"></a>

Function add

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

<pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_add">add</a>(a: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a>, b: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a>): <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_add">add</a>(a: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>, b: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>): <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a> { <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>(<a href="../std/macros.md#std_macros_uq_add">std::macros::uq_add</a>!&lt;<a href="../std/u128.md#std_u128">u128</a>, <a href="../std/u256.md#std_u256">u256</a>&gt;(a.0, b.0, <a href="../std/u128.md#std_u128_max_value">std::u128::max_value</a>!(), <b>abort</b> <a href="../std/uq64_64.md#std_uq64_64_EOverflow">EOverflow</a>)) } </code></pre> </details>

<a name="std_uq64_64_sub"></a>

Function sub

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

<pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_sub">sub</a>(a: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a>, b: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a>): <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_sub">sub</a>(a: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>, b: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>): <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a> { <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>(<a href="../std/macros.md#std_macros_uq_sub">std::macros::uq_sub</a>!(a.0, b.0, <b>abort</b> <a href="../std/uq64_64.md#std_uq64_64_EOverflow">EOverflow</a>)) } </code></pre> </details>

<a name="std_uq64_64_mul"></a>

Function mul

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

<pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_mul">mul</a>(a: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a>, b: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a>): <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_mul">mul</a>(a: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>, b: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>): <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a> { <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>(<a href="../std/uq64_64.md#std_uq64_64_int_mul">int_mul</a>(a.0, b)) } </code></pre> </details>

<a name="std_uq64_64_div"></a>

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.

<pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_div">div</a>(a: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a>, b: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a>): <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_div">div</a>(a: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>, b: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>): <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a> { <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>(<a href="../std/uq64_64.md#std_uq64_64_int_div">int_div</a>(a.0, b)) } </code></pre> </details>

<a name="std_uq64_64_to_int"></a>

Function to_int

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

<pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_to_int">to_int</a>(a: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a>): <a href="../std/u64.md#std_u64">u64</a> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_to_int">to_int</a>(a: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>): <a href="../std/u64.md#std_u64">u64</a> { <a href="../std/macros.md#std_macros_uq_to_int">std::macros::uq_to_int</a>!(a.0, <a href="../std/uq64_64.md#std_uq64_64_FRACTIONAL_BITS">FRACTIONAL_BITS</a>) } </code></pre> </details>

<a name="std_uq64_64_int_mul"></a>

Function int_mul

Multiply a <code><a href="../std/u128.md#std_u128">u128</a></code> integer by a fixed-point number, truncating any fractional part of the product. Aborts if the product overflows.

<pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_int_mul">int_mul</a>(val: <a href="../std/u128.md#std_u128">u128</a>, multiplier: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a>): <a href="../std/u128.md#std_u128">u128</a> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_int_mul">int_mul</a>(val: <a href="../std/u128.md#std_u128">u128</a>, multiplier: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>): <a href="../std/u128.md#std_u128">u128</a> { <a href="../std/macros.md#std_macros_uq_int_mul">std::macros::uq_int_mul</a>!&lt;<a href="../std/u128.md#std_u128">u128</a>, <a href="../std/u256.md#std_u256">u256</a>&gt;( val, multiplier.0, <a href="../std/u128.md#std_u128_max_value">std::u128::max_value</a>!(), <a href="../std/uq64_64.md#std_uq64_64_FRACTIONAL_BITS">FRACTIONAL_BITS</a>, <b>abort</b> <a href="../std/uq64_64.md#std_uq64_64_EOverflow">EOverflow</a>, ) } </code></pre> </details>

<a name="std_uq64_64_int_div"></a>

Function int_div

Divide a <code><a href="../std/u128.md#std_u128">u128</a></code> integer by a fixed-point number, truncating any fractional part of the quotient. Aborts if the divisor is zero. Aborts if the quotient overflows.

<pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_int_div">int_div</a>(val: <a href="../std/u128.md#std_u128">u128</a>, divisor: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a>): <a href="../std/u128.md#std_u128">u128</a> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_int_div">int_div</a>(val: <a href="../std/u128.md#std_u128">u128</a>, divisor: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>): <a href="../std/u128.md#std_u128">u128</a> { <a href="../std/macros.md#std_macros_uq_int_div">std::macros::uq_int_div</a>!&lt;<a href="../std/u128.md#std_u128">u128</a>, <a href="../std/u256.md#std_u256">u256</a>&gt;( val, divisor.0, <a href="../std/u128.md#std_u128_max_value">std::u128::max_value</a>!(), <a href="../std/uq64_64.md#std_uq64_64_FRACTIONAL_BITS">FRACTIONAL_BITS</a>, <b>abort</b> <a href="../std/uq64_64.md#std_uq64_64_EDivisionByZero">EDivisionByZero</a>, <b>abort</b> <a href="../std/uq64_64.md#std_uq64_64_EOverflow">EOverflow</a>, ) } </code></pre> </details>

<a name="std_uq64_64_le"></a>

Function le

Less than or equal to. Returns <code><b>true</b></code> if and only if <code>a <= a</code>.

<pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_le">le</a>(a: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a>, b: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a>): <a href="../std/bool.md#std_bool">bool</a> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_le">le</a>(a: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>, b: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>): <a href="../std/bool.md#std_bool">bool</a> { a.0 &lt;= b.0 } </code></pre> </details>

<a name="std_uq64_64_lt"></a>

Function lt

Less than. Returns <code><b>true</b></code> if and only if <code>a < b</code>.

<pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_lt">lt</a>(a: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a>, b: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a>): <a href="../std/bool.md#std_bool">bool</a> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_lt">lt</a>(a: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>, b: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>): <a href="../std/bool.md#std_bool">bool</a> { a.0 &lt; b.0 } </code></pre> </details>

<a name="std_uq64_64_ge"></a>

Function ge

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

<pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_ge">ge</a>(a: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a>, b: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a>): <a href="../std/bool.md#std_bool">bool</a> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_ge">ge</a>(a: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>, b: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>): <a href="../std/bool.md#std_bool">bool</a> { a.0 &gt;= b.0 } </code></pre> </details>

<a name="std_uq64_64_gt"></a>

Function gt

Greater than. Returns <code><b>true</b></code> if and only if <code>a > b</code>.

<pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_gt">gt</a>(a: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a>, b: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a>): <a href="../std/bool.md#std_bool">bool</a> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_gt">gt</a>(a: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>, b: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>): <a href="../std/bool.md#std_bool">bool</a> { a.0 &gt; b.0 } </code></pre> </details>

<a name="std_uq64_64_to_raw"></a>

Function to_raw

Accessor for the raw u128 value. Can be paired with <code><a href="../std/uq64_64.md#std_uq64_64_from_raw">from_raw</a></code> to perform less common operations on the raw values directly.

<pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_to_raw">to_raw</a>(a: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a>): <a href="../std/u128.md#std_u128">u128</a> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_to_raw">to_raw</a>(a: <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>): <a href="../std/u128.md#std_u128">u128</a> { a.0 } </code></pre> </details>

<a name="std_uq64_64_from_raw"></a>

Function from_raw

Accessor for the raw u128 value. Can be paired with <code><a href="../std/uq64_64.md#std_uq64_64_to_raw">to_raw</a></code> to perform less common operations on the raw values directly.

<pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_from_raw">from_raw</a>(raw_value: <a href="../std/u128.md#std_u128">u128</a>): <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">std::uq64_64::UQ64_64</a> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="../std/uq64_64.md#std_uq64_64_from_raw">from_raw</a>(raw_value: <a href="../std/u128.md#std_u128">u128</a>): <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a> { <a href="../std/uq64_64.md#std_uq64_64_UQ64_64">UQ64_64</a>(raw_value) } </code></pre> </details>