# Nat32

Provides utility functions on 32-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.

`import Nat32 "mo:base/Nat32";`

## Type `Nat32`

`type Nat32 = Prim.Types.Nat32`

32-bit natural numbers.

## Value `maximumValue`

`let maximumValue : Nat32`

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

.

Example:

`Nat32.maximumValue; // => 4294967295 : Nat32`

## Value `toNat`

`let toNat : Nat32 -> Nat`

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

Example:

`Nat32.toNat(123); // => 123 : Nat`

## Value `fromNat`

`let fromNat : Nat -> Nat32`

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

Traps on overflow.

Example:

`Nat32.fromNat(123); // => 123 : Nat32`

## Function `fromNat16`

`func fromNat16(x : Nat16) : Nat32`

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

Example:

`Nat32.fromNat16(123); // => 123 : Nat32`

## Function `toNat16`

`func toNat16(x : Nat32) : Nat16`

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

Traps on overflow.

Example:

`Nat32.toNat16(123); // => 123 : Nat16`

## Function `fromNat64`

`func fromNat64(x : Nat64) : Nat32`

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

Traps on overflow.

Example:

`Nat32.fromNat64(123); // => 123 : Nat32`

## Function `toNat64`

`func toNat64(x : Nat32) : Nat64`

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

Example:

`Nat32.toNat64(123); // => 123 : Nat64`

## Value `fromIntWrap`

`let fromIntWrap : Int -> Nat32`

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

Traps on overflow/underflow.

Example:

`Nat32.fromIntWrap(123); // => 123 : Nat32`

## Function `toText`

`func toText(x : Nat32) : Text`

Converts `x`

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

Example:

`Nat32.toText(1234); // => "1234" : Text`

## Function `min`

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

Returns the minimum of `x`

and `y`

.

Example:

`Nat32.min(123, 456); // => 123 : Nat32`

## Function `max`

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

Returns the maximum of `x`

and `y`

.

Example:

`Nat32.max(123, 456); // => 456 : Nat32`

## Function `equal`

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

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

.

Example:

`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:

`import Buffer "mo:base/Buffer";`

let buffer1 = Buffer.Buffer<Nat32>(3);

let buffer2 = Buffer.Buffer<Nat32>(3);

Buffer.equal(buffer1, buffer2, Nat32.equal) // => true

## Function `notEqual`

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

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

.

Example:

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

## Function `less`

`func less(x : Nat32, y : Nat32) : Bool`

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

.

Example:

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

## Function `lessOrEqual`

`func lessOrEqual(x : Nat32, y : Nat32) : Bool`

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

.

Example:

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

## Function `greater`

`func greater(x : Nat32, y : Nat32) : Bool`

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

.

Example:

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

## Function `greaterOrEqual`

`func greaterOrEqual(x : Nat32, y : Nat32) : Bool`

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

.

Example:

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

## Function `compare`

`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:

`Nat32.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:base/Array";`

Array.sort([2, 3, 1] : [Nat32], Nat32.compare) // => [1, 2, 3]

## Function `add`

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

Returns the sum of `x`

and `y`

, `x + y`

.
Traps on overflow.

Example:

`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:

`import Array "mo:base/Array";`

Array.foldLeft<Nat32, Nat32>([2, 3, 1], 0, Nat32.add) // => 6

## Function `sub`

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

Returns the difference of `x`

and `y`

, `x - y`

.
Traps on underflow.

Example:

`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:

`import Array "mo:base/Array";`

Array.foldLeft<Nat32, Nat32>([2, 3, 1], 20, Nat32.sub) // => 14

## Function `mul`

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

Returns the product of `x`

and `y`

, `x * y`

.
Traps on overflow.

Example:

`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:

`import Array "mo:base/Array";`

Array.foldLeft<Nat32, Nat32>([2, 3, 1], 1, Nat32.mul) // => 6

## Function `div`

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

Returns the division of `x by y`

, `x / y`

.
Traps when `y`

is zero.

Example:

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

## Function `rem`

`func rem(x : Nat32, y : Nat32) : Nat32`

Returns the remainder of `x`

divided by `y`

, `x % y`

.
Traps when `y`

is zero.

Example:

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

## Function `pow`

`func pow(x : Nat32, y : Nat32) : Nat32`

Returns `x`

to the power of `y`

, `x ** y`

. Traps on overflow.

Example:

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

## Function `bitnot`

`func bitnot(x : Nat32) : Nat32`

Returns the bitwise negation of `x`

, `^x`

.

Example:

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

## Function `bitand`

`func bitand(x : Nat32, y : Nat32) : Nat32`

Returns the bitwise and of `x`

and `y`

, `x & y`

.

Example:

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

## Function `bitor`

`func bitor(x : Nat32, y : Nat32) : Nat32`

Returns the bitwise or of `x`

and `y`

, `x | y`

.

Example:

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

## Function `bitxor`

`func bitxor(x : Nat32, y : Nat32) : Nat32`

Returns the bitwise exclusive or of `x`

and `y`

, `x ^ y`

.

Example:

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

## Function `bitshiftLeft`

`func bitshiftLeft(x : Nat32, y : Nat32) : Nat32`

Returns the bitwise shift left of `x`

by `y`

, `x << y`

.

Example:

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

## Function `bitshiftRight`

`func bitshiftRight(x : Nat32, y : Nat32) : Nat32`

Returns the bitwise shift right of `x`

by `y`

, `x >> y`

.

Example:

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

## Function `bitrotLeft`

`func bitrotLeft(x : Nat32, y : Nat32) : Nat32`

Returns the bitwise rotate left of `x`

by `y`

, `x <<> y`

.

Example:

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

## Function `bitrotRight`

`func bitrotRight(x : Nat32, y : Nat32) : Nat32`

Returns the bitwise rotate right of `x`

by `y`

, `x <>> y`

.

Example:

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

## Function `bittest`

`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:

`Nat32.bittest(5, 2); // => true`

## Function `bitset`

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

Returns the value of setting bit `p mod 32`

in `x`

to `1`

.

Example:

`Nat32.bitset(5, 1); // => 7`

## Function `bitclear`

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

Returns the value of clearing bit `p mod 32`

in `x`

to `0`

.

Example:

`Nat32.bitclear(5, 2); // => 1`

## Function `bitflip`

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

Returns the value of flipping bit `p mod 32`

in `x`

.

Example:

`Nat32.bitflip(5, 2); // => 1`

## Value `bitcountNonZero`

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

Returns the count of non-zero bits in `x`

.

Example:

`Nat32.bitcountNonZero(5); // => 2`

## Value `bitcountLeadingZero`

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

Returns the count of leading zero bits in `x`

.

Example:

`Nat32.bitcountLeadingZero(5); // => 29`

## Value `bitcountTrailingZero`

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

Returns the count of trailing zero bits in `x`

.

Example:

`Nat32.bitcountTrailingZero(16); // => 4`

## Function `addWrap`

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

Returns the sum of `x`

and `y`

, `x +% y`

. Wraps on overflow.

Example:

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

## Function `subWrap`

`func subWrap(x : Nat32, y : Nat32) : Nat32`

Returns the difference of `x`

and `y`

, `x -% y`

. Wraps on underflow.

Example:

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

## Function `mulWrap`

`func mulWrap(x : Nat32, y : Nat32) : Nat32`

Returns the product of `x`

and `y`

, `x *% y`

. Wraps on overflow.

Example:

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

## Function `powWrap`

`func powWrap(x : Nat32, y : Nat32) : Nat32`

Returns `x`

to the power of `y`

, `x **% y`

. Wraps on overflow.

Example:

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