Nat32

motoko name=import
import Nat32 "mo:base/Nat32";

type Nat32 = Prim.Types.Nat32

32-bit natural numbers.

public let maximumValue : Nat32

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

Example:

motoko include=import
Nat32.maximumValue; // => 4294967295 : Nat32

public let toNat : Nat32 -> Nat

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

Example:

motoko include=import
Nat32.toNat(123); // => 123 : Nat

public let fromNat : Nat -> Nat32

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

Traps on overflow.

Example:

motoko include=import
Nat32.fromNat(123); // => 123 : Nat32

public func fromNat16(x : Nat16) : Nat32

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

Example:

motoko include=import
Nat32.fromNat16(123); // => 123 : Nat32

public func toNat16(x : Nat32) : Nat16

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

Traps on overflow.

Example:

motoko include=import
Nat32.toNat16(123); // => 123 : Nat16

public func fromNat64(x : Nat64) : Nat32

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

Traps on overflow.

Example:

motoko include=import
Nat32.fromNat64(123); // => 123 : Nat32

public func toNat64(x : Nat32) : Nat64

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

Example:

motoko include=import
Nat32.toNat64(123); // => 123 : Nat64

public let fromIntWrap : Int -> Nat32

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

Traps on overflow/underflow.

Example:

motoko include=import
Nat32.fromIntWrap(123); // => 123 : Nat32

public func toText(x : Nat32) : Text

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

Example:

motoko include=import
Nat32.toText(1234); // => "1234" : Text

public func min(x : Nat32, y : Nat32) : Nat32

Returns the minimum of x and y.

Example:

motoko include=import
Nat32.min(123, 456); // => 123 : Nat32

public func max(x : Nat32, y : Nat32) : Nat32

Returns the maximum of x and y.

Example:

motoko include=import
Nat32.max(123, 456); // => 456 : Nat32

public func equal(x : Nat32, y : Nat32) : Bool

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

Example:

motoko include=import
ignore Nat32.equal(1, 1); // => true
(1 : Nat32) == (1 : Nat32) // => 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<Nat32>(3);
let buffer2 = Buffer.Buffer<Nat32>(3);
Buffer.equal(buffer1, buffer2, Nat32.equal) // => true

public func notEqual(x : Nat32, y : Nat32) : Bool

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

Example:

motoko include=import
ignore Nat32.notEqual(1, 2); // => true
(1 : Nat32) != (2 : Nat32) // => 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 : Nat32, y : Nat32) : Bool

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

Example:

motoko include=import
ignore Nat32.less(1, 2); // => true
(1 : Nat32) < (2 : Nat32) // => 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 : Nat32, y : Nat32) : Bool

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

Example:

motoko include=import
ignore Nat32.lessOrEqual(1, 2); // => true
(1 : Nat32) <= (2 : Nat32) // => 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 : Nat32, y : Nat32) : Bool

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

Example:

motoko include=import
ignore Nat32.greater(2, 1); // => true
(2 : Nat32) > (1 : Nat32) // => 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 : Nat32, y : Nat32) : Bool

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

Example:

motoko include=import
ignore Nat32.greaterOrEqual(2, 1); // => true
(2 : Nat32) >= (1 : Nat32) // => 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 : Nat32, y : Nat32) : {#less; #equal; #greater}

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

Example:

motoko include=import
Nat32.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] : [Nat32], Nat32.compare) // => [1, 2, 3]

public func add(x : Nat32, y : Nat32) : Nat32

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

Example:

motoko include=import
ignore Nat32.add(1, 2); // => 3
(1 : Nat32) + (2 : Nat32) // => 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<Nat32, Nat32>([2, 3, 1], 0, Nat32.add) // => 6

public func sub(x : Nat32, y : Nat32) : Nat32

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

Example:

motoko include=import
ignore Nat32.sub(2, 1); // => 1
(2 : Nat32) - (1 : Nat32) // => 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.

Example:

motoko include=import
import Array "mo:base/Array";
Array.foldLeft<Nat32, Nat32>([2, 3, 1], 20, Nat32.sub) // => 14

public func mul(x : Nat32, y : Nat32) : Nat32

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

Example:

motoko include=import
ignore Nat32.mul(2, 3); // => 6
(2 : Nat32) * (3 : Nat32) // => 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<Nat32, Nat32>([2, 3, 1], 1, Nat32.mul) // => 6

public func div(x : Nat32, y : Nat32) : Nat32

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

Example:

motoko include=import
ignore Nat32.div(6, 2); // => 3
(6 : Nat32) / (2 : Nat32) // => 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 : Nat32, y : Nat32) : Nat32

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

Example:

motoko include=import
ignore Nat32.rem(6, 4); // => 2
(6 : Nat32) % (4 : Nat32) // => 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 : Nat32, y : Nat32) : Nat32

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

Example:

motoko include=import
ignore Nat32.pow(2, 3); // => 8
(2 : Nat32) ** (3 : Nat32) // => 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 : Nat32) : Nat32

Returns the bitwise negation of x, ^x.

Example:

motoko include=import
ignore Nat32.bitnot(0) // => 4294967295
^(0 : Nat32) // => 4294967295

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 : Nat32, y : Nat32) : Nat32

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

Example:

motoko include=import
ignore Nat32.bitand(1, 3); // => 1
(1 : Nat32) & (3 : Nat32) // => 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 : Nat32, y : Nat32) : Nat32

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

Example:

motoko include=import
ignore Nat32.bitor(1, 3); // => 3
(1 : Nat32) | (3 : Nat32) // => 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 : Nat32, y : Nat32) : Nat32

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

Example:

motoko include=import
ignore Nat32.bitxor(1, 3); // => 2
(1 : Nat32) ^ (3 : Nat32) // => 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 : Nat32, y : Nat32) : Nat32

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

Example:

motoko include=import
ignore Nat32.bitshiftLeft(1, 3); // => 8
(1 : Nat32) << (3 : Nat32) // => 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 : Nat32, y : Nat32) : Nat32

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

Example:

motoko include=import
ignore Nat32.bitshiftRight(8, 3); // => 1
(8 : Nat32) >> (3 : Nat32) // => 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 : Nat32, y : Nat32) : Nat32

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

Example:

motoko include=import
ignore Nat32.bitrotLeft(1, 3); // => 8
(1 : Nat32) <<> (3 : Nat32) // => 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 : Nat32, y : Nat32) : Nat32

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

Example:

motoko include=import
ignore Nat32.bitrotRight(1, 1); // => 2147483648
(1 : Nat32) <>> (1 : Nat32) // => 2147483648

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 : Nat32, p : Nat) : Bool

Returns the value of bit p mod 32 in x, (x & 2^(p mod 32)) == 2^(p mod 32). This is equivalent to checking if the p-th bit is set in x, using 0 indexing.

Example:

motoko include=import
Nat32.bittest(5, 2); // => true

public func bitset(x : Nat32, p : Nat) : Nat32

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

Example:

motoko include=import
Nat32.bitset(5, 1); // => 7

public func bitclear(x : Nat32, p : Nat) : Nat32

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

Example:

motoko include=import
Nat32.bitclear(5, 2); // => 1

public func bitflip(x : Nat32, p : Nat) : Nat32

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

Example:

motoko include=import
Nat32.bitflip(5, 2); // => 1

public let bitcountNonZero : (x : Nat32) -> Nat32

Returns the count of non-zero bits in x.

Example:

motoko include=import
Nat32.bitcountNonZero(5); // => 2

public let bitcountLeadingZero : (x : Nat32) -> Nat32

Returns the count of leading zero bits in x.

Example:

motoko include=import
Nat32.bitcountLeadingZero(5); // => 29

public let bitcountTrailingZero : (x : Nat32) -> Nat32

Returns the count of trailing zero bits in x.

Example:

motoko include=import
Nat32.bitcountTrailingZero(16); // => 4

public func addWrap(x : Nat32, y : Nat32) : Nat32

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

Example:

motoko include=import
ignore Nat32.addWrap(4294967295, 1); // => 0
(4294967295 : Nat32) +% (1 : Nat32) // => 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 : Nat32, y : Nat32) : Nat32

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

Example:

motoko include=import
ignore Nat32.subWrap(0, 1); // => 4294967295
(0 : Nat32) -% (1 : Nat32) // => 4294967295

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 : Nat32, y : Nat32) : Nat32

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

Example:

motoko include=import
ignore Nat32.mulWrap(2147483648, 2); // => 0
(2147483648 : Nat32) *% (2 : Nat32) // => 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 : Nat32, y : Nat32) : Nat32

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

Example:

motoko include=import
ignore Nat32.powWrap(2, 32); // => 0
(2 : Nat32) **% (32 : Nat32) // => 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.