Math

Various math helper functions.

min

fun min(x: Int, y: Int): Int;

Computes and returns the minimum of two Int values x and y.

Usage examples:

min(1, 2);        // 1
min(2, 2);        // 2
min(007, 3);      // 3
min(0x45, 3_0_0); // 69, nice
//  ↑     ↑
//  69    300

max

fun max(x: Int, y: Int): Int;

Computes and returns the maximum of two Int values x and y.

Usage examples:

max(1, 2);        // 2
max(2, 2);        // 2
max(007, 3);      // 7
max(0x45, 3_0_0); // 300
//  ↑     ↑
//  69    300

abs

fun abs(x: Int): Int;

Computes and returns the absolute value of the Int value x.

Usage examples:

abs(42);        // 42
abs(-42);       // 42
abs(-(-(-42))); // 42

sign

Available since Tact 1.6

fun sign(x: Int): Int;

Computes and returns the sign of the Int value x. Produces $1$ if x is positive, $-1$ if x is negative, and $0$ if x is $0$.

Usage examples:

sign(42);        // 1
sign(-42);       // -1
sign(-(-42));    // 1
sign(-(-(-42))); // -1
sign(0);         // 0

sqrt

500+ gas Available since Tact 1.6

fun sqrt(num: Int): Int;

Computes the square root of the Int value num. Returns the result rounded to the nearest integer. If there are two equally close integers, rounding is done toward the even one.

Attempts to specify a negative value for num throw an exception with exit code 5: Integer out of expected range.

Usage examples:

sqrt(4);  // 2
sqrt(3);  // 2
sqrt(2);  // 1
sqrt(1);  // 1
sqrt(0);  // 0
sqrt(-1); // ERROR! Exit code 5: Integer out of expected range

divc

Available since Tact 1.6

fun divc(x: Int, y: Int): Int;

Computes and returns the rounded up result of division of the Int x by the Int y.

Attempts to divide by y equal to $0$ throw an exception with exit code 4: Integer overflow.

Usage examples:

divc(4, 2);  // 2
divc(3, 2);  // 2
divc(-4, 2); // -2
divc(-3, 2); // -1

muldivc

Available since Tact 1.6

fun muldivc(x: Int, y: Int, z: Int): Int;

Computes and returns the rounded up result of (x * y) / z.

If the value in calculation goes beyond the range from $-2^{256}$ to $2^{256} - 1$ inclusive, or if there is an attempt to divide by z equal to $0$, an exception with exit code 4 is thrown: Integer overflow.

Usage examples:

muldivc(4, 1, 2);  // 2
muldivc(3, 1, 2);  // 2
muldivc(-4, 1, 2); // -2
muldivc(-3, 1, 2); // -1
muldivc(-3, 0, 2); // 0
muldivc(-3, 0, 0); // ERROR! Exit code 4: Integer overflow

mulShiftRight

Available since Tact 1.6

fun mulShiftRight(x: Int, y: Int, z: Int): Int;

Computes and returns the rounded down result of (x * y) / 2^z. It is a more gas-efficient equivalent of performing the bitwise shift right on the result of multiplication of Int x by Int y, where Int z is the right operand of the shift.

If the value in calculation goes beyond the range from $-2^{256}$ to $2^{256} - 1$ inclusive, an exception with exit code 4 is thrown: Integer overflow.

Attempts to specify any value of z outside the inclusive range from $0$ to $256$ throw an exception with exit code 5: Integer out of expected range.

Usage examples:

mulShiftRight(5, 5, 2);  // 6
mulShiftRight(5, 5, 1);  // 12
mulShiftRight(5, 5, 0);  // 25
mulShiftRight(5, 5, -1); // ERROR! Exit code 5: Integer out of expected range

mulShiftRightRound

Available since Tact 1.6

fun mulShiftRightRound(x: Int, y: Int, z: Int): Int;

Similar to mulShiftRight(), but instead of rounding down, the result value is rounded to the nearest integer. If there are two equally close integers, rounding is done toward the even one.

If the value in calculation goes beyond the range from $-2^{256}$ to $2^{256} - 1$ inclusive, an exception with exit code 4 is thrown: Integer overflow.

Attempts to specify any value of z outside the inclusive range from $0$ to $256$ throw an exception with exit code 5: Integer out of expected range.

Usage examples:

mulShiftRightRound(5, 5, 2);  // 6
mulShiftRightRound(5, 5, 1);  // 13
mulShiftRightRound(5, 5, 0);  // 25
mulShiftRightRound(5, 5, -1); // ERROR! Exit code 5: Integer out of expected range

mulShiftRightCeil

Available since Tact 1.6

fun mulShiftRightCeil(x: Int, y: Int, z: Int): Int;

Similar to mulShiftRight(), but instead of rounding down, the result value is rounded up.

If the value in calculation goes beyond the range from $-2^{256}$ to $2^{256} - 1$ inclusive, an exception with exit code 4 is thrown: Integer overflow.

Attempts to specify any value of z outside the inclusive range from $0$ to $256$ throw an exception with exit code 5: Integer out of expected range.

Usage examples:

mulShiftRightCeil(5, 5, 2);  // 7
mulShiftRightCeil(5, 5, 1);  // 13
mulShiftRightCeil(5, 5, 0);  // 25
mulShiftRightCeil(5, 5, -1); // ERROR! Exit code 5: Integer out of expected range

log

fun log(num: Int, base: Int): Int;

Computes and returns the logarithm of a number num $> 0$ to the base base $≥ 2$. Results are rounded down.

Attempts to specify a non-positive num value or a base less than 2 throw an exception with exit code 5: Integer out of expected range.

Usage examples:

log(1000, 10); // 3, as 10^3 is 1000
//  ↑     ↑             ↑       ↑
//  num   base          base    num

log(1001, 10);  // 3
log(999, 10);   // 2
try {
    log(-1000, 10); // exit code 5 because of the non-positive num
}
log(1024, 2);   // 10
try {
    log(1024, -2);  // exit code 5 because the base is less than 1
}

Note

If you only need to obtain logarithms to the base 2, use the log2() function, as it’s more gas-efficient.

log2

fun log2(num: Int): Int;

Similar to log(), but sets the base to 2.

Attempts to specify a non-positive num value throw an exception with exit code 5: Integer out of expected range.

Usage example:

log2(1024); // 10, as 2^10 is 1024
//   ↑                ↑       ↑
//   num              base₂   num

Note

In order to reduce gas usage, prefer using this function over calling log() when you only need to obtain logarithms to the base 2.

pow

fun pow(base: Int, exp: Int): Int;

Computes and returns the exponentiation involving two numbers: the base and the exponent (or power) exp. Exponent exp must be non-negative; otherwise, an exception with exit code 5 is thrown: Integer out of expected range.

This function tries to resolve constant values at compile-time whenever possible.

Usage examples:

contract Example {
    // Persistent state variables
    p23: Int = pow(2, 3); // raises 2 to the 3rd power, which is 8
    one: Int = pow(5, 0); // raises 5 to the power 0, which always produces 1
                          // works at compile-time!

    // Internal message receiver
    receive() {
        pow(self.p23, self.one + 1); // 64, works at run-time too!
        try {
            pow(0, -1); // exit code 5: Integer out of expected range
        }
    }
}

Note

If you only need to obtain powers of $2$, use the pow2() function, as it’s more gas-efficient.

Note

List of functions that only work at compile-time: API Comptime.

pow2

fun pow2(exp: Int): Int;

Similar to pow(), but sets the base to $2$. The exponent exp must be non-negative; otherwise, an error with exit code 5 will be thrown: Integer out of expected range.

This function tries to resolve constant values at compile-time whenever possible.

Usage examples:

contract Example {
    // Persistent state variables
    p23: Int = pow2(3); // raises 2 to the 3rd power, which is 8
    one: Int = pow2(0); // raises 2 to the power 0, which always produces 1
                        // works at compile-time!

    // Internal message receiver, which accepts message ExtMsg
    receive() {
        pow2(self.one + 1); // 4, works at run-time too!
        try {
            pow(-1); // exit code 5: Integer out of expected range
        }
    }
}

Note

In order to reduce gas usage, prefer using this function over calling pow() when you only need to obtain powers of $2$.

Note

List of functions that only work at compile-time: API Comptime.