Provides utility functions on 32-bit signed integers.
:::note
Most operations are available as built-in operators (e.g. 1 + 1
).
:::
:::info 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
.
:::
motoko name=import
import Int32 "mo:base/Int32";
32-bit signed integers.
public let minimumValue : Int32
Minimum 32-bit integer value, -2 ** 31
.
Example:
motoko include=import
Int32.minimumValue // => -2_147_483_648
public let maximumValue : Int32
Maximum 32-bit integer value, +2 ** 31 - 1
.
Example:
motoko include=import
Int32.maximumValue // => +2_147_483_647
public func toInt(_ : Int32) : Int
Converts a 32-bit signed integer to a signed integer with infinite precision.
Example:
motoko include=import
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
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
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
Int32.fromInt16(-123) // => -123 : Int32
public func toInt16(_ : Int32) : Int16
Converts a 32-bit signed integer to a 16-bit signed integer.
Traps on overflow/underflow.
Example:
motoko include=import
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
Int32.fromInt64(-123_456) // => -123_456 : Int32
public func toInt64(_ : Int32) : Int64
Converts a 32-bit signed integer to a 64-bit signed integer.
Example:
motoko include=import
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
Int32.fromNat32(123_456) // => +123_456 : Int32
public func toNat32(_ : Int32) : Nat32
Converts a signed 32-bit integer to an unsigned 32-bit integer.
Wraps on overflow/underflow.
Example:
motoko include=import
Int32.toNat32(-1) // => 4_294_967_295 : Nat32 // underflow
public func toText(x : Int32) : Text
Returns the Text representation of x
. Textual representation do not
contain underscores to represent commas.
Example:
motoko include=import
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
Int32.abs(-123456) // => +123_456
public func min(x : Int32, y : Int32) : Int32
Returns the minimum of x
and y
.
Example:
motoko include=import
Int32.min(+2, -3) // => -3
public func max(x : Int32, y : Int32) : Int32
Returns the maximum of x
and y
.
Example:
motoko include=import
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
Int32.equal(-1, -1); // => true
Example:
motoko include=import
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
public func notEqual(x : Int32, y : Int32) : Bool
Inequality function for Int32 types.
This is equivalent to x != y
.
Example:
motoko include=import
Int32.notEqual(-1, -2); // => true
public func less(x : Int32, y : Int32) : Bool
"Less than" function for Int32 types.
This is equivalent to x < y
.
Example:
motoko include=import
Int32.less(-2, 1); // => true
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
Int32.lessOrEqual(-2, -2); // => true
public func greater(x : Int32, y : Int32) : Bool
"Greater than" function for Int32 types.
This is equivalent to x > y
.
Example:
motoko include=import
Int32.greater(-2, -3); // => true
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
Int32.greaterOrEqual(-2, -2); // => true
public 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:
motoko include=import
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:base/Array";
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
Int32.neg(123) // => -123
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
Int32.add(100, 23) // => +123
Example:
motoko include=import
import Array "mo:base/Array";
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
Int32.sub(1234, 123) // => +1_111
Example:
motoko include=import
import Array "mo:base/Array";
Array.foldLeft<Int32, Int32>([1, -2, -3], 0, Int32.sub) // => 6
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
Int32.mul(123, 100) // => +12_300
Example:
motoko include=import
import Array "mo:base/Array";
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
Int32.div(123, 10) // => +12
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
Int32.rem(123, 10) // => +3
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
Int32.pow(2, 10) // => +1_024
public func bitnot(x : Int32) : Int32
Returns the bitwise negation of x
, ^x
.
Example:
motoko include=import
Int32.bitnot(-256 /* 0xffff_ff00 */) // => +255 // 0xff
public func bitand(x : Int32, y : Int32) : Int32
Returns the bitwise "and" of x
and y
, x & y
.
Example:
motoko include=import
Int32.bitand(0xffff, 0x00f0) // => +240 // 0xf0
public func bitor(x : Int32, y : Int32) : Int32
Returns the bitwise "or" of x
and y
, x | y
.
Example:
motoko include=import
Int32.bitor(0xffff, 0x00f0) // => +65_535 // 0xffff
public func bitxor(x : Int32, y : Int32) : Int32
Returns the bitwise "exclusive or" of x
and y
, x ^ y
.
Example:
motoko include=import
Int32.bitxor(0xffff, 0x00f0) // => +65_295 // 0xff0f
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
Int32.bitshiftLeft(1, 8) // => +256 // 0x100 equivalent to `2 ** 8`.
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
Int32.bitshiftRight(1024, 8) // => +4 // equivalent to `1024 / (2 ** 8)`
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 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:
motoko include=import
Int32.bitrotLeft(0x2000_0001, 4) // => +18 // 0x12.
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 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:
motoko include=import
Int32.bitrotRight(0x0002_0001, 8) // => +16_777_728 // 0x0100_0200.
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
Int32.bittest(128, 7) // => true
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
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
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
Int32.bitflip(255, 7) // => +127
public func bitcountNonZero(x : Int32) : Int32
Returns the count of non-zero bits in x
.
Example:
motoko include=import
Int32.bitcountNonZero(0xffff) // => +16
public func bitcountLeadingZero(x : Int32) : Int32
Returns the count of leading zero bits in x
.
Example:
motoko include=import
Int32.bitcountLeadingZero(0x8000) // => +16
public func bitcountTrailingZero(x : Int32) : Int32
Returns the count of trailing zero bits in x
.
Example:
motoko include=import
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
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
Int32.addWrap(2 ** 30, 2 ** 30) // => -2_147_483_648 // overflow
:::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 : Int32, y : Int32) : Int32
Returns the difference of x
and y
, x -% y
.
Wraps on overflow/underflow.
Example:
motoko include=import
Int32.subWrap(-2 ** 31, 1) // => +2_147_483_647 // underflow