Nat16

Provides utility functions on 16-bit unsigned integers.

:::note Most operations on integer numbers (e.g. addition) are available as built-in operators (e.g. 1 + 1). This module provides equivalent functions and Text conversion. :::

:::info Function form for higher-order use

Several arithmetic and comparison functions (e.g. add, sub, equal, less, pow) are defined in this module to enable their use as first-class function values, which is not possible with operators like +, -, ==, etc., in Motoko. This allows you to pass these operations to higher-order functions such as map, foldLeft, or sort. :::

Import from the base library to use this module.

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

type Nat16 = Prim.Types.Nat16

16-bit natural numbers.

public let maximumValue : Nat16

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

Example:

motoko include=import
Nat16.maximumValue; // => 65536 : Nat16

public func toNat(_ : Nat16) : Nat

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

Example:

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

public func fromNat(_ : Nat) : Nat16

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

Traps on overflow.

Example:

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

public func fromNat8(x : Nat8) : Nat16

Converts an 8-bit unsigned integer to a 16-bit unsigned integer.

Example:

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

public func toNat8(x : Nat16) : Nat8

Converts a 16-bit unsigned integer to an 8-bit unsigned integer.

Traps on overflow.

Example:

motoko include=import
Nat16.toNat8(123); // => 123 : Nat8

public func fromNat32(x : Nat32) : Nat16

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

Traps on overflow.

Example:

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

public func toNat32(x : Nat16) : Nat32

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

Example:

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

public func fromIntWrap(_ : Int) : Nat16

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

Wraps on overflow/underflow.

Example:

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

public func toText(x : Nat16) : Text

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

Example:

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

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

Returns the minimum of x and y.

Example:

motoko include=import
Nat16.min(123, 200); // => 123 : Nat16

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

Returns the maximum of x and y.

Example:

motoko include=import
Nat16.max(123, 200); // => 200 : Nat16

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

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

Example:

motoko include=import
ignore Nat16.equal(1, 1); // => true
(1 : Nat16) == (1 : Nat16) // => true

Example:

motoko include=import
import Buffer "mo:base/Buffer";

let buffer1 = Buffer.Buffer<Nat16>(3);
let buffer2 = Buffer.Buffer<Nat16>(3);
Buffer.equal(buffer1, buffer2, Nat16.equal) // => true

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

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

Example:

motoko include=import
ignore Nat16.notEqual(1, 2); // => true
(1 : Nat16) != (2 : Nat16) // => true

public func less(x : Nat16, y : Nat16) : Bool

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

Example:

motoko include=import
ignore Nat16.less(1, 2); // => true
(1 : Nat16) < (2 : Nat16) // => true

public func lessOrEqual(x : Nat16, y : Nat16) : Bool

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

Example:

motoko include=import
ignore Nat16.lessOrEqual(1, 2); // => true
(1 : Nat16) <= (2 : Nat16) // => true

public func greater(x : Nat16, y : Nat16) : Bool

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

Example:

motoko include=import
ignore Nat16.greater(2, 1); // => true
(2 : Nat16) > (1 : Nat16) // => true

public func greaterOrEqual(x : Nat16, y : Nat16) : Bool

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

Example:

motoko include=import
ignore Nat16.greaterOrEqual(2, 1); // => true
(2 : Nat16) >= (1 : Nat16) // => true

public func compare(x : Nat16, y : Nat16) : {#less; #equal; #greater}

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

Example:

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

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

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

Example:

motoko include=import
ignore Nat16.add(1, 2); // => 3
(1 : Nat16) + (2 : Nat16) // => 3

Example:

motoko include=import
import Array "mo:base/Array";
Array.foldLeft<Nat16, Nat16>([2, 3, 1], 0, Nat16.add) // => 6

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

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

Example:

motoko include=import
ignore Nat16.sub(2, 1); // => 1
(2 : Nat16) - (1 : Nat16) // => 1

Example:

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

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

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

Example:

motoko include=import
ignore Nat16.mul(2, 3); // => 6
(2 : Nat16) * (3 : Nat16) // => 6

Example:

motoko include=import
import Array "mo:base/Array";
Array.foldLeft<Nat16, Nat16>([2, 3, 1], 1, Nat16.mul) // => 6

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

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

Example:

motoko include=import
ignore Nat16.div(6, 2); // => 3
(6 : Nat16) / (2 : Nat16) // => 3

public func rem(x : Nat16, y : Nat16) : Nat16

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

Example:

motoko include=import
ignore Nat16.rem(6, 4); // => 2
(6 : Nat16) % (4 : Nat16) // => 2

public func pow(x : Nat16, y : Nat16) : Nat16

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

Example:

motoko include=import
ignore Nat16.pow(2, 3); // => 8
(2 : Nat16) ** (3 : Nat16) // => 8

public func bitnot(x : Nat16) : Nat16

Returns the bitwise negation of x, ^x.

Example:

motoko include=import
ignore Nat16.bitnot(0); // => 65535
^(0 : Nat16) // => 65535

public func bitand(x : Nat16, y : Nat16) : Nat16

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

Example:

motoko include=import
ignore Nat16.bitand(0, 1); // => 0
(0 : Nat16) & (1 : Nat16) // => 0

public func bitor(x : Nat16, y : Nat16) : Nat16

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

Example:

motoko include=import
ignore Nat16.bitor(0, 1); // => 1
(0 : Nat16) | (1 : Nat16) // => 1

public func bitxor(x : Nat16, y : Nat16) : Nat16

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

Example:

motoko include=import
ignore Nat16.bitxor(0, 1); // => 1
(0 : Nat16) ^ (1 : Nat16) // => 1

public func bitshiftLeft(x : Nat16, y : Nat16) : Nat16

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

Example:

motoko include=import
ignore Nat16.bitshiftLeft(1, 3); // => 8
(1 : Nat16) << (3 : Nat16) // => 8

public func bitshiftRight(x : Nat16, y : Nat16) : Nat16

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

Example:

motoko include=import
ignore Nat16.bitshiftRight(8, 3); // => 1
(8 : Nat16) >> (3 : Nat16) // => 1

public func bitrotLeft(x : Nat16, y : Nat16) : Nat16

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

Example:

motoko include=import
ignore Nat16.bitrotLeft(2, 1); // => 4
(2 : Nat16) <<> (1 : Nat16) // => 4

public func bitrotRight(x : Nat16, y : Nat16) : Nat16

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

Example:

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

public func bittest(x : Nat16, p : Nat) : Bool

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

Example:

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

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

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

Example:

motoko include=import
Nat16.bitset(0, 2); // => 4

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

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

Example:

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

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

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

Example:

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

public func bitcountNonZero(x : Nat16) : Nat16

Returns the count of non-zero bits in x.

Example:

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

public func bitcountLeadingZero(x : Nat16) : Nat16

Returns the count of leading zero bits in x.

Example:

motoko include=import
Nat16.bitcountLeadingZero(5); // => 13

public func bitcountTrailingZero(x : Nat16) : Nat16

Returns the count of trailing zero bits in x.

Example:

motoko include=import
Nat16.bitcountTrailingZero(5); // => 0

public func explode(x : Nat16) : (msb : Nat8, lsb : Nat8)

Returns the upper (i.e. most significant) and lower (least significant) byte of x.

Example:

motoko include=import
Nat16.explode 0xaa88 // => (170, 136)

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

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

Example:

motoko include=import
ignore Nat16.addWrap(65532, 5); // => 1
(65532 : Nat16) +% (5 : Nat16) // => 1

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

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

Example:

motoko include=import
ignore Nat16.subWrap(1, 2); // => 65535
(1 : Nat16) -% (2 : Nat16) // => 65535

public func mulWrap(x : Nat16, y : Nat16) : Nat16

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

Example:

motoko include=import
ignore Nat16.mulWrap(655, 101); // => 619
(655 : Nat16) *% (101 : Nat16) // => 619

public func powWrap(x : Nat16, y : Nat16) : Nat16

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

Example:

motoko include=import
ignore Nat16.powWrap(2, 16); // => 0
(2 : Nat16) **% (16 : Nat16) // => 0