core/Int
Signed integer numbers with infinite precision (also called big integers).
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.
Import from the core library to use this module.
import Int "mo:core/Int";
Type Int
type Int = Prim.Types.Int
Infinite precision signed integers.
Function abs
func abs(x : Int) : Nat
Returns the absolute value of x
.
Example:
assert Int.abs(-12) == 12;
Function toText
func toText(x : Int) : Text
Converts an integer number to its textual representation. Textual representation do not contain underscores to represent commas.
Example:
assert Int.toText(-1234) == "-1234";
Function fromText
func fromText(text : Text) : ?Int
Creates a integer from its textual representation. Returns null
if the input is not a valid integer.
The textual representation must not contain underscores but may begin with a '+' or '-' character.
Example:
assert Int.fromText("-1234") == ?-1234;
Function toNat
func toNat(int : Int) : Nat
Converts an integer to a natural number. Traps if the integer is negative.
Example:
import Debug "mo:core/Debug";
assert Int.toNat(1234 : Int) == (1234 : Nat);
Function fromNat
func fromNat(nat : Nat) : Int
Converts a natural number to an integer.
Example:
assert Int.fromNat(1234 : Nat) == (1234 : Int);
Function min
func min(x : Int, y : Int) : Int
Returns the minimum of x
and y
.
Example:
assert Int.min(2, -3) == -3;
Function max
func max(x : Int, y : Int) : Int
Returns the maximum of x
and y
.
Example:
assert Int.max(2, -3) == 2;
Function equal
func equal(x : Int, y : Int) : Bool
Equality function for Int types.
This is equivalent to x == y
.
Example:
assert Int.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:
let a : Int = 1;
let b : Int = -1;
assert not Int.equal(a, b);
Function notEqual
func notEqual(x : Int, y : Int) : Bool
Inequality function for Int types.
This is equivalent to x != y
.
Example:
assert Int.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.
Function less
func less(x : Int, y : Int) : Bool
"Less than" function for Int types.
This is equivalent to x < y
.
Example:
assert Int.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.
Function lessOrEqual
func lessOrEqual(x : Int, y : Int) : Bool
"Less than or equal" function for Int types.
This is equivalent to x <= y
.
Example:
assert Int.lessOrEqual(-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.
Function greater
func greater(x : Int, y : Int) : Bool
"Greater than" function for Int types.
This is equivalent to x > y
.
Example:
assert Int.greater(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.
Function greaterOrEqual
func greaterOrEqual(x : Int, y : Int) : Bool
"Greater than or equal" function for Int types.
This is equivalent to x >= y
.
Example:
assert Int.greaterOrEqual(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.
Function compare
func compare(x : Int, y : Int) : Order.Order
General-purpose comparison function for Int
. Returns the Order
(
either #less
, #equal
, or #greater
) of comparing x
with y
.
Example:
assert Int.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:core/Array";
assert Array.sort([1, -2, -3], Int.compare) == [-3, -2, 1];
Function neg
func neg(x : Int) : Int
Returns the negation of x
, -x
.
Example:
assert Int.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.
Function add
func add(x : Int, y : Int) : Int
Returns the sum of x
and y
, x + y
.
No overflow since Int
has infinite precision.
Example:
assert Int.add(1, -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.
Example:
import Array "mo:core/Array";
assert Array.foldLeft([1, -2, -3], 0, Int.add) == -4;
Function sub
func sub(x : Int, y : Int) : Int
Returns the difference of x
and y
, x - y
.
No overflow since Int
has infinite precision.
Example:
assert Int.sub(1, 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.
Example:
import Array "mo:core/Array";
assert Array.foldLeft([1, -2, -3], 0, Int.sub) == 4;
Function mul
func mul(x : Int, y : Int) : Int
Returns the product of x
and y
, x * y
.
No overflow since Int
has infinite precision.
Example:
assert Int.mul(-2, 3) == -6;
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:
import Array "mo:core/Array";
assert Array.foldLeft([1, -2, -3], 1, Int.mul) == 6;
Function div
func div(x : Int, y : Int) : Int
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:
assert Int.div(6, -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.
Function rem
func rem(x : Int, y : Int) : Int
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:
assert Int.rem(6, -4) == 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.
Function pow
func pow(x : Int, y : Int) : Int
Returns x
to the power of y
, x ** y
.
Traps when y
is negative or y > 2 ** 32 - 1
.
No overflow since Int
has infinite precision.
Example:
assert Int.pow(-2, 3) == -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.
Function range
func range(fromInclusive : Int, toExclusive : Int) : Iter.Iter<Int>
Returns an iterator over the integers from the first to second argument with an exclusive upper bound.
import Iter "mo:core/Iter";
let iter = Int.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.
import Iter "mo:core/Iter";
let iter = Int.range(4, 1);
assert iter.next() == null; // empty iterator
Function rangeBy
func rangeBy(fromInclusive : Int, toExclusive : Int, step : Int) : Iter.Iter<Int>
Returns an iterator over Int
values from the first to second argument with an exclusive upper bound,
incrementing by the specified step size.
import Iter "mo:core/Iter";
// Positive step
let iter1 = Int.rangeBy(1, 7, 2);
assert iter1.next() == ?1;
assert iter1.next() == ?3;
assert iter1.next() == ?5;
assert iter1.next() == null;
// Negative step
let iter2 = Int.rangeBy(7, 1, -2);
assert iter2.next() == ?7;
assert iter2.next() == ?5;
assert iter2.next() == ?3;
assert iter2.next() == null;
If step
is 0 or if the iteration would not progress towards the bound, returns an empty iterator.
Function rangeInclusive
func rangeInclusive(from : Int, to : Int) : Iter.Iter<Int>
Returns an iterator over the integers from the first to second argument, inclusive.
import Iter "mo:core/Iter";
let iter = Int.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.
import Iter "mo:core/Iter";
let iter = Int.rangeInclusive(3, 1);
assert iter.next() == null; // empty iterator
Function rangeByInclusive
func rangeByInclusive(from : Int, to : Int, step : Int) : Iter.Iter<Int>
Returns an iterator over the integers from the first to second argument, inclusive, incrementing by the specified step size.
import Iter "mo:core/Iter";
// Positive step
let iter1 = Int.rangeByInclusive(1, 7, 2);
assert iter1.next() == ?1;
assert iter1.next() == ?3;
assert iter1.next() == ?5;
assert iter1.next() == ?7;
assert iter1.next() == null;
// Negative step
let iter2 = Int.rangeByInclusive(7, 1, -2);
assert iter2.next() == ?7;
assert iter2.next() == ?5;
assert iter2.next() == ?3;
assert iter2.next() == ?1;
assert iter2.next() == null;
If from == to
, return an iterator which only returns that value.
Otherwise, if step
is 0 or if the iteration would not progress towards the bound, returns an empty iterator.