Skip to main content

core/Nat64

Utility functions on 64-bit unsigned integers.

Note that most operations are available as built-in operators (e.g. 1 + 1).

Import from the core library to use this module.

import Nat64 "mo:core/Nat64";

Type Nat64​

type Nat64 = Prim.Types.Nat64

64-bit natural numbers.

Value maxValue​

let maxValue : Nat64

Maximum 64-bit natural number. 2 ** 64 - 1.

Example:

assert Nat64.maxValue == (18446744073709551615 : Nat64);

Function toNat​

func toNat(_ : Nat64) : Nat

Converts a 64-bit unsigned integer to an unsigned integer with infinite precision.

Example:

assert Nat64.toNat(123) == (123 : Nat);

Function fromNat​

func fromNat(_ : Nat) : Nat64

Converts an unsigned integer with infinite precision to a 64-bit unsigned integer.

Traps on overflow.

Example:

assert Nat64.fromNat(123) == (123 : Nat64);

Function fromNat32​

func fromNat32(x : Nat32) : Nat64

Converts a 32-bit unsigned integer to a 64-bit unsigned integer.

Example:

assert Nat64.fromNat32(123) == (123 : Nat64);

Function toNat32​

func toNat32(x : Nat64) : Nat32

Converts a 64-bit unsigned integer to a 32-bit unsigned integer.

Traps on overflow.

Example:

assert Nat64.toNat32(123) == (123 : Nat32);

Function fromIntWrap​

func fromIntWrap(_ : Int) : Nat64

Converts a signed integer with infinite precision to a 64-bit unsigned integer.

Traps on overflow/underflow.

Example:

assert Nat64.fromIntWrap(123) == (123 : Nat64);

Function toText​

func toText(x : Nat64) : Text

Converts x to its textual representation. Textual representation do not contain underscores to represent commas.

Example:

assert Nat64.toText(1234) == ("1234" : Text);

Function min​

func min(x : Nat64, y : Nat64) : Nat64

Returns the minimum of x and y.

Example:

assert Nat64.min(123, 456) == (123 : Nat64);

Function max​

func max(x : Nat64, y : Nat64) : Nat64

Returns the maximum of x and y.

Example:

assert Nat64.max(123, 456) == (456 : Nat64);

Function equal​

func equal(x : Nat64, y : Nat64) : Bool

Equality function for Nat64 types. This is equivalent to x == y.

Example:

assert Nat64.equal(1, 1);
assert (1 : Nat64) == (1 : Nat64);

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:

let a : Nat64 = 111;
let b : Nat64 = 222;
assert not Nat64.equal(a, b);

Function notEqual​

func notEqual(x : Nat64, y : Nat64) : Bool

Inequality function for Nat64 types. This is equivalent to x != y.

Example:

assert Nat64.notEqual(1, 2);
assert (1 : Nat64) != (2 : Nat64);

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.

Function less​

func less(x : Nat64, y : Nat64) : Bool

"Less than" function for Nat64 types. This is equivalent to x < y.

Example:

assert Nat64.less(1, 2);
assert (1 : Nat64) < (2 : Nat64);

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.

Function lessOrEqual​

func lessOrEqual(x : Nat64, y : Nat64) : Bool

"Less than or equal" function for Nat64 types. This is equivalent to x <= y.

Example:

assert Nat64.lessOrEqual(1, 2);
assert (1 : Nat64) <= (2 : Nat64);

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.

Function greater​

func greater(x : Nat64, y : Nat64) : Bool

"Greater than" function for Nat64 types. This is equivalent to x > y.

Example:

assert Nat64.greater(2, 1);
assert (2 : Nat64) > (1 : Nat64);

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.

Function greaterOrEqual​

func greaterOrEqual(x : Nat64, y : Nat64) : Bool

"Greater than or equal" function for Nat64 types. This is equivalent to x >= y.

Example:

assert Nat64.greaterOrEqual(2, 1);
assert (2 : Nat64) >= (1 : Nat64);

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.

Function compare​

func compare(x : Nat64, y : Nat64) : Order.Order

General purpose comparison function for Nat64. Returns the Order ( either #less, #equal, or #greater) of comparing x with y.

Example:

assert Nat64.compare(2, 3) == #less;

This function can be used as value for a high order function, such as a sort function.

Example:

import Array "mo:core/Array";
assert Array.sort([2, 3, 1] : [Nat64], Nat64.compare) == [1, 2, 3];

Function add​

func add(x : Nat64, y : Nat64) : Nat64

Returns the sum of x and y, x + y. Traps on overflow.

Example:

assert Nat64.add(1, 2) == 3;
assert (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:

import Array "mo:core/Array";
assert Array.foldLeft<Nat64, Nat64>([2, 3, 1], 0, Nat64.add) == 6;

Function sub​

func sub(x : Nat64, y : Nat64) : Nat64

Returns the difference of x and y, x - y. Traps on underflow.

Example:

assert Nat64.sub(3, 1) == 2;
assert (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:

import Array "mo:core/Array";
assert Array.foldLeft<Nat64, Nat64>([2, 3, 1], 10, Nat64.sub) == 4;

Function mul​

func mul(x : Nat64, y : Nat64) : Nat64

Returns the product of x and y, x * y. Traps on overflow.

Example:

assert Nat64.mul(2, 3) == 6;
assert (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:

import Array "mo:core/Array";
assert Array.foldLeft<Nat64, Nat64>([2, 3, 1], 1, Nat64.mul) == 6;

Function div​

func div(x : Nat64, y : Nat64) : Nat64

Returns the quotient of x divided by y, x / y. Traps when y is zero.

Example:

assert Nat64.div(6, 2) == 3;
assert (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.

Function rem​

func rem(x : Nat64, y : Nat64) : Nat64

Returns the remainder of x divided by y, x % y. Traps when y is zero.

Example:

assert Nat64.rem(6, 4) == 2;
assert (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.

Function pow​

func pow(x : Nat64, y : Nat64) : Nat64

Returns x to the power of y, x ** y. Traps on overflow.

Example:

assert Nat64.pow(2, 3) == 8;
assert (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.

Function bitnot​

func bitnot(x : Nat64) : Nat64

Returns the bitwise negation of x, ^x.

Example:

assert Nat64.bitnot(0) == 18446744073709551615;
assert ^(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.

Function bitand​

func bitand(x : Nat64, y : Nat64) : Nat64

Returns the bitwise and of x and y, x & y.

Example:

assert Nat64.bitand(1, 3) == 1;
assert (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.

Function bitor​

func bitor(x : Nat64, y : Nat64) : Nat64

Returns the bitwise or of x and y, x | y.

Example:

assert Nat64.bitor(1, 3) == 3;
assert (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.

Function bitxor​

func bitxor(x : Nat64, y : Nat64) : Nat64

Returns the bitwise exclusive or of x and y, x ^ y.

Example:

assert Nat64.bitxor(1, 3) == 2;
assert (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.

Function bitshiftLeft​

func bitshiftLeft(x : Nat64, y : Nat64) : Nat64

Returns the bitwise shift left of x by y, x << y.

Example:

assert Nat64.bitshiftLeft(1, 3) == 8;
assert (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.

Function bitshiftRight​

func bitshiftRight(x : Nat64, y : Nat64) : Nat64

Returns the bitwise shift right of x by y, x >> y.

Example:

assert Nat64.bitshiftRight(8, 3) == 1;
assert (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.

Function bitrotLeft​

func bitrotLeft(x : Nat64, y : Nat64) : Nat64

Returns the bitwise rotate left of x by y, x <<> y.

Example:

assert Nat64.bitrotLeft(1, 3) == 8;
assert (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.

Function bitrotRight​

func bitrotRight(x : Nat64, y : Nat64) : Nat64

Returns the bitwise rotate right of x by y, x <>> y.

Example:

assert Nat64.bitrotRight(8, 3) == 1;
assert (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.

Function bittest​

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:

assert Nat64.bittest(5, 2);

Function bitset​

func bitset(x : Nat64, p : Nat) : Nat64

Returns the value of setting bit p mod 64 in x to 1.

Example:

assert Nat64.bitset(5, 1) == 7;

Function bitclear​

func bitclear(x : Nat64, p : Nat) : Nat64

Returns the value of clearing bit p mod 64 in x to 0.

Example:

assert Nat64.bitclear(5, 2) == 1;

Function bitflip​

func bitflip(x : Nat64, p : Nat) : Nat64

Returns the value of flipping bit p mod 64 in x.

Example:

assert Nat64.bitflip(5, 2) == 1;

Function bitcountNonZero​

func bitcountNonZero(x : Nat64) : Nat64

Returns the count of non-zero bits in x.

Example:

assert Nat64.bitcountNonZero(5) == 2;

Function bitcountLeadingZero​

func bitcountLeadingZero(x : Nat64) : Nat64

Returns the count of leading zero bits in x.

Example:

assert Nat64.bitcountLeadingZero(5) == 61;

Function bitcountTrailingZero​

func bitcountTrailingZero(x : Nat64) : Nat64

Returns the count of trailing zero bits in x.

Example:

assert Nat64.bitcountTrailingZero(16) == 4;

Function addWrap​

func addWrap(x : Nat64, y : Nat64) : Nat64

Returns the sum of x and y, x +% y. Wraps on overflow.

Example:

assert Nat64.addWrap(Nat64.maxValue, 1) == 0;
assert Nat64.maxValue +% (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.

Function subWrap​

func subWrap(x : Nat64, y : Nat64) : Nat64

Returns the difference of x and y, x -% y. Wraps on underflow.

Example:

assert Nat64.subWrap(0, 1) == 18446744073709551615;
assert (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.

Function mulWrap​

func mulWrap(x : Nat64, y : Nat64) : Nat64

Returns the product of x and y, x *% y. Wraps on overflow.

Example:

assert Nat64.mulWrap(4294967296, 4294967296) == 0;
assert (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.

Function powWrap​

func powWrap(x : Nat64, y : Nat64) : Nat64

Returns x to the power of y, x **% y. Wraps on overflow.

Example:

assert Nat64.powWrap(2, 64) == 0;
assert (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.

Function range​

func range(fromInclusive : Nat64, toExclusive : Nat64) : Iter.Iter<Nat64>

Returns an iterator over Nat64 values from the first to second argument with an exclusive upper bound.

import Iter "mo:core/Iter";

let iter = Nat64.range(1, 4);
assert iter.next() == ?1;
assert iter.next() == ?2;
assert iter.next() == ?3;
assert iter.next() == null;

If the first argument is greater than the second argument, the function returns an empty iterator.

import Iter "mo:core/Iter";

let iter = Nat64.range(4, 1);
assert iter.next() == null; // empty iterator

Function rangeInclusive​

func rangeInclusive(from : Nat64, to : Nat64) : Iter.Iter<Nat64>

Returns an iterator over Nat64 values from the first to second argument, inclusive.

import Iter "mo:core/Iter";

let iter = Nat64.rangeInclusive(1, 3);
assert iter.next() == ?1;
assert iter.next() == ?2;
assert iter.next() == ?3;
assert iter.next() == null;

If the first argument is greater than the second argument, the function returns an empty iterator.

import Iter "mo:core/Iter";

let iter = Nat64.rangeInclusive(4, 1);
assert iter.next() == null; // empty iterator

Function allValues​

func allValues() : Iter.Iter<Nat64>

Returns an iterator over all Nat64 values, from 0 to maxValue.

import Iter "mo:core/Iter";

let iter = Nat64.allValues();
assert iter.next() == ?0;
assert iter.next() == ?1;
assert iter.next() == ?2;
// ...