Int32

motoko name=import
import Int32 "mo:core/Int32";

type Int32 = Prim.Types.Int32

32-bit signed integers.

public let minValue : Int32

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

Example:

motoko include=import
assert Int32.minValue == -2_147_483_648;

public let maxValue : Int32

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

Example:

motoko include=import
assert Int32.maxValue == +2_147_483_647;

public func toInt(self : Int32) : Int

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

Example:

motoko include=import
assert Int32.toInt(123_456) == (123_456 : Int);

public func fromInt(_ : Int) : Int32

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

Traps on overflow/underflow.

Example:

motoko include=import
assert Int32.fromInt(123_456) == (+123_456 : Int32);

public func fromIntWrap(_ : Int) : Int32

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

Wraps on overflow/underflow.

Example:

motoko include=import
assert Int32.fromIntWrap(-123_456) == (-123_456 : Int);

public func fromInt16(_ : Int16) : Int32

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

Example:

motoko include=import
assert Int32.fromInt16(-123) == (-123 : Int32);

public func toInt16(self : Int32) : Int16

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

Traps on overflow/underflow.

Example:

motoko include=import
assert Int32.toInt16(-123) == (-123 : Int16);

public func fromInt64(_ : Int64) : Int32

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

Traps on overflow/underflow.

Example:

motoko include=import
assert Int32.fromInt64(-123_456) == (-123_456 : Int32);

public func toInt64(self : Int32) : Int64

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

Example:

motoko include=import
assert Int32.toInt64(-123_456) == (-123_456 : Int64);

public func fromNat32(_ : Nat32) : Int32

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

Wraps on overflow/underflow.

Example:

motoko include=import
assert Int32.fromNat32(123_456) == (+123_456 : Int32);

public func toNat32(self : Int32) : Nat32

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

Wraps on overflow/underflow.

Example:

motoko include=import
assert Int32.toNat32(-1) == (4_294_967_295 : Nat32); // underflow

public func toText(self : Int32) : Text

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

Example:

motoko include=import
assert Int32.toText(-123456) == "-123456";

public func abs(x : Int32) : Int32

Returns the absolute value of x.

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

Example:

motoko include=import
assert Int32.abs(-123456) == +123_456;

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

Returns the minimum of x and y.

Example:

motoko include=import
assert Int32.min(+2, -3) == -3;

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

Returns the maximum of x and y.

Example:

motoko include=import
assert Int32.max(+2, -3) == +2;

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

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

Example:

motoko include=import
assert Int32.equal(-1, -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
let a : Int32 = -123;
let b : Int32 = 123;
assert not Int32.equal(a, b);

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

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

Example:

motoko include=import
assert Int32.notEqual(-1, -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 less(x : Int32, y : Int32) : Bool

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

Example:

motoko include=import
assert Int32.less(-2, 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 lessOrEqual(x : Int32, y : Int32) : Bool

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

Example:

motoko include=import
assert Int32.lessOrEqual(-2, -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 greater(x : Int32, y : Int32) : Bool

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

Example:

motoko include=import
assert Int32.greater(-2, -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 greaterOrEqual(x : Int32, y : Int32) : Bool

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

Example:

motoko include=import
assert Int32.greaterOrEqual(-2, -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 compare(x : Int32, y : Int32) : Order.Order

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

Example:

motoko include=import
assert Int32.compare(-3, 2) == #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:core/Array";
assert Array.sort([1, -2, -3] : [Int32], Int32.compare) == [-3, -2, 1];

public func neg(x : Int32) : Int32

Returns the negation of x, -x.

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

Example:

motoko include=import
assert Int32.neg(123) == -123;

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

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

Traps on overflow/underflow.

Example:

motoko include=import
assert Int32.add(100, 23) == +123;

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:core/Array";
assert Array.foldLeft<Int32, Int32>([1, -2, -3], 0, Int32.add) == -4;

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

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

Traps on overflow/underflow.

Example:

motoko include=import
assert Int32.sub(1234, 123) == +1_111;

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:core/Array";
assert Array.foldLeft<Int32, Int32>([1, -2, -3], 0, Int32.sub) == 4;

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

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

Traps on overflow/underflow.

Example:

motoko include=import
assert Int32.mul(123, 100) == +12_300;

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:core/Array";
assert Array.foldLeft<Int32, Int32>([1, -2, -3], 1, Int32.mul) == 6;

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

motoko include=import
assert Int32.div(123, 10) == +12;

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

motoko include=import
assert Int32.rem(123, 10) == +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 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:

motoko include=import
assert Int32.pow(2, 10) == +1_024;

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

Returns the bitwise negation of x, ^x.

Example:

motoko include=import
assert Int32.bitnot(-256 /* 0xffff_ff00 */) == +255 // 0xff;

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

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

Example:

motoko include=import
assert Int32.bitand(0xffff, 0x00f0) == +240 // 0xf0;

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

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

Example:

motoko include=import
assert Int32.bitor(0xffff, 0x00f0) == +65_535 // 0xffff;

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

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

Example:

motoko include=import
assert Int32.bitxor(0xffff, 0x00f0) == +65_295 // 0xff0f;

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

motoko include=import
assert Int32.bitshiftLeft(1, 8) == +256 // 0x100 equivalent to `2 ** 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 : 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:

motoko include=import
assert Int32.bitshiftRight(1024, 8) == +4 // equivalent to `1024 / (2 ** 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 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 y 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:

motoko include=import
assert Int32.bitrotLeft(0x2000_0001, 4) == +18 // 0x12.;

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

motoko include=import
assert Int32.bitrotRight(0x0002_0001, 8) == +16_777_728 // 0x0100_0200.;

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

motoko include=import
assert Int32.bittest(128, 7);

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

motoko include=import
assert Int32.bitset(0, 7) == +128;

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

motoko include=import
assert Int32.bitclear(-1, 7) == -129;

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

motoko include=import
assert Int32.bitflip(255, 7) == +127;

public func bitcountNonZero(x : Int32) : Int32

Returns the count of non-zero bits in x.

Example:

motoko include=import
assert Int32.bitcountNonZero(0xffff) == +16;

public func bitcountLeadingZero(x : Int32) : Int32

Returns the count of leading zero bits in x.

Example:

motoko include=import
assert Int32.bitcountLeadingZero(0x8000) == +16;

public func bitcountTrailingZero(x : Int32) : Int32

Returns the count of trailing zero bits in x.

Example:

motoko include=import
assert Int32.bitcountTrailingZero(0x0201_0000) == +16;

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

motoko include=import
assert Int32.explode 0x66885511 == (102, 136, 85, 17);

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

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

Wraps on overflow/underflow.

Example:

motoko include=import
assert Int32.addWrap(2 ** 30, 2 ** 30) == -2_147_483_648; // overflow

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

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

Wraps on overflow/underflow.

Example:

motoko include=import
assert Int32.subWrap(-2 ** 31, 1) == +2_147_483_647; // underflow

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

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

Wraps on overflow/underflow.

Example:

motoko include=import
assert Int32.mulWrap(2 ** 16, 2 ** 16) == 0; // overflow

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

motoko include=import
assert Int32.powWrap(2, 31) == -2_147_483_648; // overflow

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 range(fromInclusive : Int32, toExclusive : Int32) : Iter.Iter<Int32>

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

motoko include=import
import Iter "mo:core/Iter";

let iter = Int32.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.

motoko include=import
import Iter "mo:core/Iter";

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

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

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

motoko include=import
import Iter "mo:core/Iter";

let iter = Int32.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.

motoko include=import
import Iter "mo:core/Iter";

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

public func allValues() : Iter.Iter<Int32>

Returns an iterator over all Int32 values, from minValue to maxValue.

motoko include=import
import Iter "mo:core/Iter";

let iter = Int32.allValues();
assert iter.next() == ?-2_147_483_648;
assert iter.next() == ?-2_147_483_647;
assert iter.next() == ?-2_147_483_646;
// ...