Skip to main content

base/Int32

Provides utility functions on 32-bit signed integers.

Most operations are available as built-in operators (e.g. 1 + 1).

Function form for higher-order use

Several arithmetic and comparison functions (e.g. add, sub, bitor, bitand, 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 Int32 "mo:base/Int32";

Type Int32​

type Int32 = Prim.Types.Int32

32-bit signed integers.

Value minimumValue​

let minimumValue : Int32

Minimum 32-bit integer value, -2 ** 31.

Example:

Int32.minimumValue // => -2_147_483_648

Value maximumValue​

let maximumValue : Int32

Maximum 32-bit integer value, +2 ** 31 - 1.

Example:

Int32.maximumValue // => +2_147_483_647

Function toInt​

func toInt(_ : Int32) : Int

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

Example:

Int32.toInt(123_456) // => 123_456 : Int

Function fromInt​

func fromInt(_ : Int) : Int32

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

Traps on overflow/underflow.

Example:

Int32.fromInt(123_456) // => +123_456 : Int32

Function fromIntWrap​

func fromIntWrap(_ : Int) : Int32

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

Wraps on overflow/underflow.

Example:

Int32.fromIntWrap(-123_456) // => -123_456 : Int

Function fromInt16​

func fromInt16(_ : Int16) : Int32

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

Example:

Int32.fromInt16(-123) // => -123 : Int32

Function toInt16​

func toInt16(_ : Int32) : Int16

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

Traps on overflow/underflow.

Example:

Int32.toInt16(-123) // => -123 : Int16

Function fromInt64​

func fromInt64(_ : Int64) : Int32

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

Traps on overflow/underflow.

Example:

Int32.fromInt64(-123_456) // => -123_456 : Int32

Function toInt64​

func toInt64(_ : Int32) : Int64

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

Example:

Int32.toInt64(-123_456) // => -123_456 : Int64

Function fromNat32​

func fromNat32(_ : Nat32) : Int32

Converts an unsigned 32-bit integer to a signed 32-bit integer.

Wraps on overflow/underflow.

Example:

Int32.fromNat32(123_456) // => +123_456 : Int32

Function toNat32​

func toNat32(_ : Int32) : Nat32

Converts a signed 32-bit integer to an unsigned 32-bit integer.

Wraps on overflow/underflow.

Example:

Int32.toNat32(-1) // => 4_294_967_295 : Nat32 // underflow

Function toText​

func toText(x : Int32) : Text

Returns the Text representation of x. Textual representation do not contain underscores to represent commas.

Example:

Int32.toText(-123456) // => "-123456"

Function abs​

func abs(x : Int32) : Int32

Returns the absolute value of x.

Traps when x == -2 ** 31 (the minimum Int32 value).

Example:

Int32.abs(-123456) // => +123_456

Function min​

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

Returns the minimum of x and y.

Example:

Int32.min(+2, -3) // => -3

Function max​

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

Returns the maximum of x and y.

Example:

Int32.max(+2, -3) // => +2

Function equal​

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

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

Example:

Int32.equal(-1, -1); // => true

Example:

import Buffer "mo:base/Buffer";

let buffer1 = Buffer.Buffer<Int32>(1);
buffer1.add(-3);
let buffer2 = Buffer.Buffer<Int32>(1);
buffer2.add(-3);
Buffer.equal(buffer1, buffer2, Int32.equal) // => true

Function notEqual​

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

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

Example:

Int32.notEqual(-1, -2); // => true

Function less​

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

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

Example:

Int32.less(-2, 1); // => true

Function lessOrEqual​

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

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

Example:

Int32.lessOrEqual(-2, -2); // => true

Function greater​

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

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

Example:

Int32.greater(-2, -3); // => true

Function greaterOrEqual​

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

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

Example:

Int32.greaterOrEqual(-2, -2); // => true

Function compare​

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

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

Example:

Int32.compare(-3, 2) // => #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([1, -2, -3] : [Int32], Int32.compare) // => [-3, -2, 1]

Function neg​

func neg(x : Int32) : Int32

Returns the negation of x, -x.

Traps on overflow, i.e. for neg(-2 ** 31).

Example:

Int32.neg(123) // => -123

Function add​

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

Returns the sum of x and y, x + y.

Traps on overflow/underflow.

Example:

Int32.add(100, 23) // => +123

Example:

import Array "mo:base/Array";
Array.foldLeft<Int32, Int32>([1, -2, -3], 0, Int32.add) // => -4

Function sub​

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

Returns the difference of x and y, x - y.

Traps on overflow/underflow.

Example:

Int32.sub(1234, 123) // => +1_111

Example:

import Array "mo:base/Array";
Array.foldLeft<Int32, Int32>([1, -2, -3], 0, Int32.sub) // => 6

Function mul​

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

Returns the product of x and y, x * y.

Traps on overflow/underflow.

Example:

Int32.mul(123, 100) // => +12_300

Example:

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

Function div​

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

Returns the signed integer division of x by y, x / y. Rounds the quotient towards zero, which is the same as truncating the decimal places of the quotient.

Traps when y is zero.

Example:

Int32.div(123, 10) // => +12

Function rem​

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

Returns the remainder of the signed integer division of x by y, x % y, which is defined as x - x / y * y.

Traps when y is zero.

Example:

Int32.rem(123, 10) // => +3

Function pow​

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

Returns x to the power of y, x ** y.

Traps on overflow/underflow and when y < 0 or y >= 32.

Example:

Int32.pow(2, 10) // => +1_024

Function bitnot​

func bitnot(x : Int32) : Int32

Returns the bitwise negation of x, ^x.

Example:

Int32.bitnot(-256 /* 0xffff_ff00 */) // => +255 // 0xff

Function bitand​

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

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

Example:

Int32.bitand(0xffff, 0x00f0) // => +240 // 0xf0

Function bitor​

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

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

Example:

Int32.bitor(0xffff, 0x00f0) // => +65_535 // 0xffff

Function bitxor​

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

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

Example:

Int32.bitxor(0xffff, 0x00f0) // => +65_295 // 0xff0f

Function bitshiftLeft​

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

Returns the bitwise left shift of x by y, x << y. The right bits of the shift filled with zeros. Left-overflowing bits, including the sign bit, are discarded.

For y >= 32, the semantics is the same as for bitshiftLeft(x, y % 32). For y < 0, the semantics is the same as for bitshiftLeft(x, y + y % 32).

Example:

Int32.bitshiftLeft(1, 8) // => +256 // 0x100 equivalent to `2 ** 8`.

Function bitshiftRight​

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

Returns the signed bitwise right shift of x by y, x >> y. The sign bit is retained and the left side is filled with the sign bit. Right-underflowing bits are discarded, i.e. not rotated to the left side.

For y >= 32, the semantics is the same as for bitshiftRight(x, y % 32). For y < 0, the semantics is the same as for bitshiftRight (x, y + y % 32).

Example:

Int32.bitshiftRight(1024, 8) // => +4 // equivalent to `1024 / (2 ** 8)`

Function bitrotLeft​

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

Returns the bitwise left rotatation of x by y, x <<> y. Each left-overflowing bit is inserted again on the right side. The sign bit is rotated like other bits, i.e. the rotation interprets the number as unsigned.

Changes the direction of rotation for negative y. For y >= 32, the semantics is the same as for bitrotLeft(x, y % 32).

Example:

Int32.bitrotLeft(0x2000_0001, 4) // => +18 // 0x12.

Function bitrotRight​

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

Returns the bitwise right rotation of x by y, x <>> y. Each right-underflowing bit is inserted again on the right side. The sign bit is rotated like other bits, i.e. the rotation interprets the number as unsigned.

Changes the direction of rotation for negative y. For y >= 32, the semantics is the same as for bitrotRight(x, y % 32).

Example:

Int32.bitrotRight(0x0002_0001, 8) // => +16_777_728 // 0x0100_0200.

Function bittest​

func bittest(x : Int32, p : Nat) : Bool

Returns the value of bit p in x, x & 2**p == 2**p. If p >= 32, the semantics is the same as for bittest(x, p % 32). This is equivalent to checking if the p-th bit is set in x, using 0 indexing.

Example:

Int32.bittest(128, 7) // => true

Function bitset​

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

Returns the value of setting bit p in x to 1. If p >= 32, the semantics is the same as for bitset(x, p % 32).

Example:

Int32.bitset(0, 7) // => +128

Function bitclear​

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

Returns the value of clearing bit p in x to 0. If p >= 32, the semantics is the same as for bitclear(x, p % 32).

Example:

Int32.bitclear(-1, 7) // => -129

Function bitflip​

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

Returns the value of flipping bit p in x. If p >= 32, the semantics is the same as for bitclear(x, p % 32).

Example:

Int32.bitflip(255, 7) // => +127

Function bitcountNonZero​

func bitcountNonZero(x : Int32) : Int32

Returns the count of non-zero bits in x.

Example:

Int32.bitcountNonZero(0xffff) // => +16

Function bitcountLeadingZero​

func bitcountLeadingZero(x : Int32) : Int32

Returns the count of leading zero bits in x.

Example:

Int32.bitcountLeadingZero(0x8000) // => +16

Function bitcountTrailingZero​

func bitcountTrailingZero(x : Int32) : Int32

Returns the count of trailing zero bits in x.

Example:

Int32.bitcountTrailingZero(0x0201_0000) // => +16

Function explode​

func explode(x : Int32) : (msb : Nat8, Nat8, Nat8, lsb : Nat8)

Returns the upper (i.e. most significant), lower (least significant) and in-between bytes of x.

Example:

Int32.explode 0x66885511 // => (102, 136, 85, 17)

Function addWrap​

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

Returns the sum of x and y, x +% y.

Wraps on overflow/underflow.

Example:

Int32.addWrap(2 ** 30, 2 ** 30) // => -2_147_483_648 // overflow

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

Returns the difference of x and y, x -% y.

Wraps on overflow/underflow.

Example:

Int32.subWrap(-2 ** 31, 1) // => +2_147_483_647 // underflow

Function mulWrap​

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

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

Wraps on overflow/underflow.

Example:

Int32.mulWrap(2 ** 16, 2 ** 16) // => 0 // overflow

Function powWrap​

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

Returns x to the power of y, x **% y.

Wraps on overflow/underflow. Traps if y < 0 or y >= 32.

Example:

Int32.powWrap(2, 31) // => -2_147_483_648 // overflow