Int8
Provides utility functions on 8-bit signed integers.
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.
Most operations are available as built-in operators (e.g. 1 + 1).
Import from the base library to use this module.
import Int8 "mo:base/Int8";
Type Int8
type Int8 = Prim.Types.Int8
8-bit signed integers.
Value minimumValue
let minimumValue : Int8
Minimum 8-bit integer value, -2 ** 7.
Example:
Int8.minimumValue // => -128
Value maximumValue
let maximumValue : Int8
Maximum 8-bit integer value, +2 ** 7 - 1.
Example:
Int8.maximumValue // => +127
Function toInt
func toInt(_ : Int8) : Int
Converts an 8-bit signed integer to a signed integer with infinite precision.
Example:
Int8.toInt(123) // => 123 : Int
Function fromInt
func fromInt(_ : Int) : Int8
Converts a signed integer with infinite precision to an 8-bit signed integer.
Traps on overflow/underflow.
Example:
Int8.fromInt(123) // => +123 : Int8
Function fromIntWrap
func fromIntWrap(_ : Int) : Int8
Converts a signed integer with infinite precision to an 8-bit signed integer.
Wraps on overflow/underflow.
Example:
Int8.fromIntWrap(-123) // => -123 : Int
Function fromInt16
func fromInt16(_ : Int16) : Int8
Converts a 16-bit signed integer to an 8-bit signed integer.
Traps on overflow/underflow.
Example:
Int8.fromInt16(123) // => +123 : Int8
Function toInt16
func toInt16(_ : Int8) : Int16
Converts an 8-bit signed integer to a 16-bit signed integer.
Example:
Int8.toInt16(123) // => +123 : Int16
Function fromNat8
func fromNat8(_ : Nat8) : Int8
Converts an unsigned 8-bit integer to a signed 8-bit integer.
Wraps on overflow/underflow.
Example:
Int8.fromNat8(123) // => +123 : Int8
Function toNat8
func toNat8(_ : Int8) : Nat8
Converts a signed 8-bit integer to an unsigned 8-bit integer.
Wraps on overflow/underflow.
Example:
Int8.toNat8(-1) // => 255 : Nat8 // underflow
Function toText
func toText(x : Int8) : Text
Converts an integer number to its textual representation.
Example:
Int8.toText(-123) // => "-123"
Function abs
func abs(x : Int8) : Int8
Returns the absolute value of x.
Traps when x == -2 ** 7 (the minimum Int8 value).
Example:
Int8.abs(-123) // => +123
Function min
func min(x : Int8, y : Int8) : Int8
Returns the minimum of x and y.
Example:
Int8.min(+2, -3) // => -3
Function max
func max(x : Int8, y : Int8) : Int8
Returns the maximum of x and y.
Example:
Int8.max(+2, -3) // => +2
Function equal
func equal(x : Int8, y : Int8) : Bool
Equality function for Int8 types.
This is equivalent to x == y.
Example:
Int8.equal(-1, -1); // => true
Example:
import Buffer "mo:base/Buffer";
let buffer1 = Buffer.Buffer<Int8>(1);
buffer1.add(-3);
let buffer2 = Buffer.Buffer<Int8>(1);
buffer2.add(-3);
Buffer.equal(buffer1, buffer2, Int8.equal) // => true
Function notEqual
func notEqual(x : Int8, y : Int8) : Bool
Inequality function for Int8 types.
This is equivalent to x != y.
Example:
Int8.notEqual(-1, -2); // => true
Function less
func less(x : Int8, y : Int8) : Bool
"Less than" function for Int8 types.
This is equivalent to x < y.
Example:
Int8.less(-2, 1); // => true
Function lessOrEqual
func lessOrEqual(x : Int8, y : Int8) : Bool
"Less than or equal" function for Int8 types.
This is equivalent to x <= y.
Example:
Int8.lessOrEqual(-2, -2); // => true
Function greater
func greater(x : Int8, y : Int8) : Bool
"Greater than" function for Int8 types.
This is equivalent to x > y.
Example:
Int8.greater(-2, -3); // => true
Function greaterOrEqual
func greaterOrEqual(x : Int8, y : Int8) : Bool
"Greater than or equal" function for Int8 types.
This is equivalent to x >= y.
Example:
Int8.greaterOrEqual(-2, -2); // => true
Function compare
func compare(x : Int8, y : Int8) : {#less; #equal; #greater}
General-purpose comparison function for Int8. Returns the Order (
either #less, #equal, or #greater) of comparing x with y.
Example:
Int8.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] : [Int8], Int8.compare) // => [-3, -2, 1]
Function neg
func neg(x : Int8) : Int8
Returns the negation of x, -x.
Traps on overflow, i.e. for neg(-2 ** 7).
Example:
Int8.neg(123) // => -123
Function add
func add(x : Int8, y : Int8) : Int8
Returns the sum of x and y, x + y.
Traps on overflow/underflow.
Example:
Int8.add(100, 23) // => +123
Example:
import Array "mo:base/Array";
Array.foldLeft<Int8, Int8>([1, -2, -3], 0, Int8.add) // => -4
Function sub
func sub(x : Int8, y : Int8) : Int8
Returns the difference of x and y, x - y.
Traps on overflow/underflow.
Example:
Int8.sub(123, 23) // => +100
Example:
import Array "mo:base/Array";
Array.foldLeft<Int8, Int8>([1, -2, -3], 0, Int8.sub) // => 4
Function mul
func mul(x : Int8, y : Int8) : Int8
Returns the product of x and y, x * y.
Traps on overflow/underflow.
Example:
Int8.mul(12, 10) // => +120
Example:
import Array "mo:base/Array";
Array.foldLeft<Int8, Int8>([1, -2, -3], 1, Int8.mul) // => 6
Function div
func div(x : Int8, y : Int8) : Int8
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:
Int8.div(123, 10) // => +12
Function rem
func rem(x : Int8, y : Int8) : Int8
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:
Int8.rem(123, 10) // => +3
Function pow
func pow(x : Int8, y : Int8) : Int8
Returns x to the power of y, x ** y.
Traps on overflow/underflow and when y < 0 or y >= 8.
Example:
Int8.pow(2, 6) // => +64
Function bitnot
func bitnot(x : Int8) : Int8
Returns the bitwise negation of x, ^x.
Example:
Int8.bitnot(-16 /* 0xf0 */) // => +15 // 0x0f
Function bitand
func bitand(x : Int8, y : Int8) : Int8
Returns the bitwise "and" of x and y, x & y.
Example:
Int8.bitand(0x1f, 0x70) // => +16 // 0x10
Function bitor
func bitor(x : Int8, y : Int8) : Int8
Returns the bitwise "or" of x and y, x | y.
Example:
Int8.bitor(0x0f, 0x70) // => +127 // 0x7f
Function bitxor
func bitxor(x : Int8, y : Int8) : Int8
Returns the bitwise "exclusive or" of x and y, x ^ y.
Example:
Int8.bitxor(0x70, 0x7f) // => +15 // 0x0f
Function bitshiftLeft
func bitshiftLeft(x : Int8, y : Int8) : Int8
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 >= 8, the semantics is the same as for bitshiftLeft(x, y % 8).
For y < 0, the semantics is the same as for bitshiftLeft(x, y + y % 8).
Example:
Int8.bitshiftLeft(1, 4) // => +16 // 0x10 equivalent to `2 ** 4`.
Function bitshiftRight
func bitshiftRight(x : Int8, y : Int8) : Int8
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 >= 8, the semantics is the same as for bitshiftRight(x, y % 8).
For y < 0, the semantics is the same as for bitshiftRight (x, y + y % 8).
Example:
Int8.bitshiftRight(64, 4) // => +4 // equivalent to `64 / (2 ** 4)`
Function bitrotLeft
func bitrotLeft(x : Int8, y : Int8) : Int8
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 >= 8, the semantics is the same as for bitrotLeft(x, y % 8).
Example:
Int8.bitrotLeft(0x11 /* 0b0001_0001 */, 2) // => +68 // 0b0100_0100 == 0x44.
Function bitrotRight
func bitrotRight(x : Int8, y : Int8) : Int8
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 >= 8, the semantics is the same as for bitrotRight(x, y % 8).
Example:
Int8.bitrotRight(0x11 /* 0b0001_0001 */, 1) // => -120 // 0b1000_1000 == 0x88.
Function bittest
func bittest(x : Int8, p : Nat) : Bool
Returns the value of bit p in x, x & 2**p == 2**p.
If p >= 8, the semantics is the same as for bittest(x, p % 8).
This is equivalent to checking if the p-th bit is set in x, using 0 indexing.
Example:
Int8.bittest(64, 6) // => true
Function bitset
func bitset(x : Int8, p : Nat) : Int8
Returns the value of setting bit p in x to 1.
If p >= 8, the semantics is the same as for bitset(x, p % 8).
Example:
Int8.bitset(0, 6) // => +64
Function bitclear
func bitclear(x : Int8, p : Nat) : Int8
Returns the value of clearing bit p in x to 0.
If p >= 8, the semantics is the same as for bitclear(x, p % 8).
Example:
Int8.bitclear(-1, 6) // => -65
Function bitflip
func bitflip(x : Int8, p : Nat) : Int8
Returns the value of flipping bit p in x.
If p >= 8, the semantics is the same as for bitclear(x, p % 8).
Example:
Int8.bitflip(127, 6) // => +63
Function bitcountNonZero
func bitcountNonZero(x : Int8) : Int8
Returns the count of non-zero bits in x.
Example:
Int8.bitcountNonZero(0x0f) // => +4
Function bitcountLeadingZero
func bitcountLeadingZero(x : Int8) : Int8
Returns the count of leading zero bits in x.
Example:
Int8.bitcountLeadingZero(0x08) // => +4
Function bitcountTrailingZero
func bitcountTrailingZero(x : Int8) : Int8
Returns the count of trailing zero bits in x.
Example:
Int8.bitcountTrailingZero(0x10) // => +4
Function addWrap
func addWrap(x : Int8, y : Int8) : Int8
Returns the sum of x and y, x +% y.
Wraps on overflow/underflow.
Example:
Int8.addWrap(2 ** 6, 2 ** 6) // => -128 // overflow
Function subWrap
func subWrap(x : Int8, y : Int8) : Int8
Returns the difference of x and y, x -% y.
Wraps on overflow/underflow.
Example:
Int8.subWrap(-2 ** 7, 1) // => +127 // underflow
Function mulWrap
func mulWrap(x : Int8, y : Int8) : Int8
Returns the product of x and y, x *% y. Wraps on overflow.
Wraps on overflow/underflow.
Example:
Int8.mulWrap(2 ** 4, 2 ** 4) // => 0 // overflow
Function powWrap
func powWrap(x : Int8, y : Int8) : Int8
Returns x to the power of y, x **% y.
Wraps on overflow/underflow.
Traps if y < 0 or y >= 8.
Example:
Int8.powWrap(2, 7) // => -128 // overflow