Provides utility functions on 64-bit unsigned integers.
Note that most operations are available as built-in operators (e.g. 1 + 1
).
Import from the base library to use this module.
motoko name=import
import Nat64 "mo:base/Nat64";
64-bit natural numbers.
public let maximumValue : Nat64
Maximum 64-bit natural number. 2 ** 64 - 1
.
Example:
motoko include=import
Nat64.maximumValue; // => 18446744073709551615 : Nat64
public let toNat : Nat64 -> Nat
Converts a 64-bit unsigned integer to an unsigned integer with infinite precision.
Example:
motoko include=import
Nat64.toNat(123); // => 123 : Nat
public let fromNat : Nat -> Nat64
Converts an unsigned integer with infinite precision to a 64-bit unsigned integer.
Traps on overflow.
Example:
motoko include=import
Nat64.fromNat(123); // => 123 : Nat64
public func fromNat32(x : Nat32) : Nat64
Converts a 32-bit unsigned integer to a 64-bit unsigned integer.
Example:
motoko include=import
Nat64.fromNat32(123); // => 123 : Nat64
public func toNat32(x : Nat64) : Nat32
Converts a 64-bit unsigned integer to a 32-bit unsigned integer.
Traps on overflow.
Example:
motoko include=import
Nat64.toNat32(123); // => 123 : Nat32
public let fromIntWrap : Int -> Nat64
Converts a signed integer with infinite precision to a 64-bit unsigned integer.
Traps on overflow/underflow.
Example:
motoko include=import
Nat64.fromIntWrap(123); // => 123 : Nat64
public func toText(x : Nat64) : Text
Converts x
to its textual representation. Textual representation do not
contain underscores to represent commas.
Example:
motoko include=import
Nat64.toText(1234); // => "1234" : Text
public func min(x : Nat64, y : Nat64) : Nat64
Returns the minimum of x
and y
.
Example:
motoko include=import
Nat64.min(123, 456); // => 123 : Nat64
public func max(x : Nat64, y : Nat64) : Nat64
Returns the maximum of x
and y
.
Example:
motoko include=import
Nat64.max(123, 456); // => 456 : Nat64
public func equal(x : Nat64, y : Nat64) : Bool
Equality function for Nat64 types.
This is equivalent to x == y
.
Example:
motoko include=import
ignore Nat64.equal(1, 1); // => true
(1 : Nat64) == (1 : Nat64) // => true
Note: The reason why this function is defined in this library (in addition
to the existing ==
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use ==
as a function value at the moment.
Example:
motoko include=import
import Buffer "mo:base/Buffer";
let buffer1 = Buffer.Buffer<Nat64>(3);
let buffer2 = Buffer.Buffer<Nat64>(3);
Buffer.equal(buffer1, buffer2, Nat64.equal) // => true
public func notEqual(x : Nat64, y : Nat64) : Bool
Inequality function for Nat64 types.
This is equivalent to x != y
.
Example:
motoko include=import
ignore Nat64.notEqual(1, 2); // => true
(1 : Nat64) != (2 : Nat64) // => true
Note: The reason why this function is defined in this library (in addition
to the existing !=
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use !=
as a function value at the moment.
public func less(x : Nat64, y : Nat64) : Bool
"Less than" function for Nat64 types.
This is equivalent to x < y
.
Example:
motoko include=import
ignore Nat64.less(1, 2); // => true
(1 : Nat64) < (2 : Nat64) // => true
Note: The reason why this function is defined in this library (in addition
to the existing <
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use <
as a function value at the moment.
public func lessOrEqual(x : Nat64, y : Nat64) : Bool
"Less than or equal" function for Nat64 types.
This is equivalent to x <= y
.
Example:
motoko include=import
ignore Nat64.lessOrEqual(1, 2); // => true
(1 : Nat64) <= (2 : Nat64) // => true
Note: The reason why this function is defined in this library (in addition
to the existing <=
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use <=
as a function value at the moment.
public func greater(x : Nat64, y : Nat64) : Bool
"Greater than" function for Nat64 types.
This is equivalent to x > y
.
Example:
motoko include=import
ignore Nat64.greater(2, 1); // => true
(2 : Nat64) > (1 : Nat64) // => true
Note: The reason why this function is defined in this library (in addition
to the existing >
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use >
as a function value at the moment.
public func greaterOrEqual(x : Nat64, y : Nat64) : Bool
"Greater than or equal" function for Nat64 types.
This is equivalent to x >= y
.
Example:
motoko include=import
ignore Nat64.greaterOrEqual(2, 1); // => true
(2 : Nat64) >= (1 : Nat64) // => true
Note: The reason why this function is defined in this library (in addition
to the existing >=
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use >=
as a function value at the moment.
public func compare(x : Nat64, y : Nat64) : {#less; #equal; #greater}
General purpose comparison function for Nat64
. Returns the Order
(
either #less
, #equal
, or #greater
) of comparing x
with y
.
Example:
motoko include=import
Nat64.compare(2, 3) // => #less
This function can be used as value for a high order function, such as a sort function.
Example:
motoko include=import
import Array "mo:base/Array";
Array.sort([2, 3, 1] : [Nat64], Nat64.compare) // => [1, 2, 3]
public func add(x : Nat64, y : Nat64) : Nat64
Returns the sum of x
and y
, x + y
.
Traps on overflow.
Example:
motoko include=import
ignore Nat64.add(1, 2); // => 3
(1 : Nat64) + (2 : Nat64) // => 3
Note: The reason why this function is defined in this library (in addition
to the existing +
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use +
as a function value at the moment.
Example:
motoko include=import
import Array "mo:base/Array";
Array.foldLeft<Nat64, Nat64>([2, 3, 1], 0, Nat64.add) // => 6
public func sub(x : Nat64, y : Nat64) : Nat64
Returns the difference of x
and y
, x - y
.
Traps on underflow.
Example:
motoko include=import
ignore Nat64.sub(3, 1); // => 2
(3 : Nat64) - (1 : Nat64) // => 2
Note: The reason why this function is defined in this library (in addition
to the existing -
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use -
as a function value at the moment.
Example:
motoko include=import
import Array "mo:base/Array";
Array.foldLeft<Nat64, Nat64>([2, 3, 1], 10, Nat64.sub) // => 4
public func mul(x : Nat64, y : Nat64) : Nat64
Returns the product of x
and y
, x * y
.
Traps on overflow.
Example:
motoko include=import
ignore Nat64.mul(2, 3); // => 6
(2 : Nat64) * (3 : Nat64) // => 6
Note: The reason why this function is defined in this library (in addition
to the existing *
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use *
as a function value at the moment.
Example:
motoko include=import
import Array "mo:base/Array";
Array.foldLeft<Nat64, Nat64>([2, 3, 1], 1, Nat64.mul) // => 6
public func div(x : Nat64, y : Nat64) : Nat64
Returns the quotient of x
divided by y
, x / y
.
Traps when y
is zero.
Example:
motoko include=import
ignore Nat64.div(6, 2); // => 3
(6 : Nat64) / (2 : Nat64) // => 3
Note: The reason why this function is defined in this library (in addition
to the existing /
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use /
as a function value at the moment.
public func rem(x : Nat64, y : Nat64) : Nat64
Returns the remainder of x
divided by y
, x % y
.
Traps when y
is zero.
Example:
motoko include=import
ignore Nat64.rem(6, 4); // => 2
(6 : Nat64) % (4 : Nat64) // => 2
Note: The reason why this function is defined in this library (in addition
to the existing %
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use %
as a function value at the moment.
public func pow(x : Nat64, y : Nat64) : Nat64
Returns x
to the power of y
, x ** y
. Traps on overflow.
Example:
motoko include=import
ignore Nat64.pow(2, 3); // => 8
(2 : Nat64) ** (3 : Nat64) // => 8
Note: The reason why this function is defined in this library (in addition
to the existing **
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use **
as a function value at the moment.
public func bitnot(x : Nat64) : Nat64
Returns the bitwise negation of x
, ^x
.
Example:
motoko include=import
ignore Nat64.bitnot(0); // => 18446744073709551615
^(0 : Nat64) // => 18446744073709551615
Note: The reason why this function is defined in this library (in addition
to the existing ^
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use ^
as a function value at the moment.
public func bitand(x : Nat64, y : Nat64) : Nat64
Returns the bitwise and of x
and y
, x & y
.
Example:
motoko include=import
ignore Nat64.bitand(1, 3); // => 1
(1 : Nat64) & (3 : Nat64) // => 1
Note: The reason why this function is defined in this library (in addition
to the existing &
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use &
as a function value at the moment.
public func bitor(x : Nat64, y : Nat64) : Nat64
Returns the bitwise or of x
and y
, x | y
.
Example:
motoko include=import
ignore Nat64.bitor(1, 3); // => 3
(1 : Nat64) | (3 : Nat64) // => 3
Note: The reason why this function is defined in this library (in addition
to the existing |
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use |
as a function value at the moment.
public func bitxor(x : Nat64, y : Nat64) : Nat64
Returns the bitwise exclusive or of x
and y
, x ^ y
.
Example:
motoko include=import
ignore Nat64.bitxor(1, 3); // => 2
(1 : Nat64) ^ (3 : Nat64) // => 2
Note: The reason why this function is defined in this library (in addition
to the existing ^
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use ^
as a function value at the moment.
public func bitshiftLeft(x : Nat64, y : Nat64) : Nat64
Returns the bitwise shift left of x
by y
, x << y
.
Example:
motoko include=import
ignore Nat64.bitshiftLeft(1, 3); // => 8
(1 : Nat64) << (3 : Nat64) // => 8
Note: The reason why this function is defined in this library (in addition
to the existing <<
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use <<
as a function value at the moment.
public func bitshiftRight(x : Nat64, y : Nat64) : Nat64
Returns the bitwise shift right of x
by y
, x >> y
.
Example:
motoko include=import
ignore Nat64.bitshiftRight(8, 3); // => 1
(8 : Nat64) >> (3 : Nat64) // => 1
Note: The reason why this function is defined in this library (in addition
to the existing >>
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use >>
as a function value at the moment.
public func bitrotLeft(x : Nat64, y : Nat64) : Nat64
Returns the bitwise rotate left of x
by y
, x <<> y
.
Example:
motoko include=import
ignore Nat64.bitrotLeft(1, 3); // => 8
(1 : Nat64) <<> (3 : Nat64) // => 8
Note: The reason why this function is defined in this library (in addition
to the existing <<>
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use <<>
as a function value at the moment.
public func bitrotRight(x : Nat64, y : Nat64) : Nat64
Returns the bitwise rotate right of x
by y
, x <>> y
.
Example:
motoko include=import
ignore Nat64.bitrotRight(8, 3); // => 1
(8 : Nat64) <>> (3 : Nat64) // => 1
Note: The reason why this function is defined in this library (in addition
to the existing <>>
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use <>>
as a function value at the moment.
public func bittest(x : Nat64, p : Nat) : Bool
Returns the value of bit p mod 64
in x
, (x & 2^(p mod 64)) == 2^(p mod 64)
.
This is equivalent to checking if the p
-th bit is set in x
, using 0 indexing.
Example:
motoko include=import
Nat64.bittest(5, 2); // => true
public func bitset(x : Nat64, p : Nat) : Nat64
Returns the value of setting bit p mod 64
in x
to 1
.
Example:
motoko include=import
Nat64.bitset(5, 1); // => 7
public func bitclear(x : Nat64, p : Nat) : Nat64
Returns the value of clearing bit p mod 64
in x
to 0
.
Example:
motoko include=import
Nat64.bitclear(5, 2); // => 1
public func bitflip(x : Nat64, p : Nat) : Nat64
Returns the value of flipping bit p mod 64
in x
.
Example:
motoko include=import
Nat64.bitflip(5, 2); // => 1
public let bitcountNonZero : (x : Nat64) -> Nat64
Returns the count of non-zero bits in x
.
Example:
motoko include=import
Nat64.bitcountNonZero(5); // => 2
public let bitcountLeadingZero : (x : Nat64) -> Nat64
Returns the count of leading zero bits in x
.
Example:
motoko include=import
Nat64.bitcountLeadingZero(5); // => 61
public let bitcountTrailingZero : (x : Nat64) -> Nat64
Returns the count of trailing zero bits in x
.
Example:
motoko include=import
Nat64.bitcountTrailingZero(16); // => 4
public func addWrap(x : Nat64, y : Nat64) : Nat64
Returns the sum of x
and y
, x +% y
. Wraps on overflow.
Example:
motoko include=import
ignore Nat64.addWrap(Nat64.maximumValue, 1); // => 0
Nat64.maximumValue +% (1 : Nat64) // => 0
Note: The reason why this function is defined in this library (in addition
to the existing +%
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use +%
as a function value at the moment.
public func subWrap(x : Nat64, y : Nat64) : Nat64
Returns the difference of x
and y
, x -% y
. Wraps on underflow.
Example:
motoko include=import
ignore Nat64.subWrap(0, 1); // => 18446744073709551615
(0 : Nat64) -% (1 : Nat64) // => 18446744073709551615
Note: The reason why this function is defined in this library (in addition
to the existing -%
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use -%
as a function value at the moment.
public func mulWrap(x : Nat64, y : Nat64) : Nat64
Returns the product of x
and y
, x *% y
. Wraps on overflow.
Example:
motoko include=import
ignore Nat64.mulWrap(4294967296, 4294967296); // => 0
(4294967296 : Nat64) *% (4294967296 : Nat64) // => 0
Note: The reason why this function is defined in this library (in addition
to the existing *%
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use *%
as a function value at the moment.
public func powWrap(x : Nat64, y : Nat64) : Nat64
Returns x
to the power of y
, x **% y
. Wraps on overflow.
Example:
motoko include=import
ignore Nat64.powWrap(2, 64); // => 0
(2 : Nat64) **% (64 : Nat64) // => 0
Note: The reason why this function is defined in this library (in addition
to the existing **%
operator) is so that you can use it as a function
value to pass to a higher order function. It is not possible to use **%
as a function value at the moment.