Standard Library

class int32

A signed 32-bit integer: an int32 holds -2147483648 to 2147483647 and is stored unboxed.

since 0.1.0-alpha.1linuxwindowswasm

Overview

Arithmetic between int32 values wraps around in two's complement at 32 bits instead of failing: 2147483647 + 1 is -2147483648 and -2147483648 - 1 is 2147483647. Even -2147483648 / -1, whose true result 2147483648 does not fit, gives -2147483648. >> keeps the sign. A bare integer literal next to an int32 operand counts as an int32, while an int variable makes the result an int. Division or remainder by zero throws a RuntimeException. A literal assigned to an int32 is checked when the program is compiled.

Converting an int with int.toInt32() does not wrap, it throws when the value is outside -2147483648..2147483647. toInt() converts back and never fails.

Examples

Wrapping and range

int32 top = 2147483647;
int32 one = 1;
console.writeln(top + one);
int32 bottom = -2147483648;
console.writeln(bottom - one);
console.writeln(bottom.abs());
int32 big = 2000000000;
console.writeln(big + big);
try {
    console.writeln(3000000000.toInt32());
} catch (RuntimeException e) {
    console.writeln("caught: ${e.message}");
}

Run it ▶

-2147483648
2147483647
-2147483648
-294967296
caught: toInt32: value out of range (-2147483648..2147483647)

Methods

abs

@__narrowShared("abs")
abs() -> int32

Return the absolute value.

Two's complement has one more negative value than positive ones, so the absolute value of -2147483648, the smallest int32, does not fit and abs returns -2147483648 unchanged.

Returns

this when it is zero or positive, otherwise -this, as a int32.

Examples

int32 n = -300000;
console.writeln(n.abs());
int32 bottom = -2147483648;
console.writeln(bottom.abs());
int32 top = 2147483647;
console.writeln(top.abs());

Run it ▶

300000
-2147483648
2147483647

clamp

@__narrowShared("clamp")
clamp(int32 lo, int32 hi) -> int32

Limit the int32 to the range from lo to hi.

Parameters

lo: The smallest value to return.
hi: The largest value to return.

Returns

lo if this is below it, hi if this is above it, otherwise this.

Throws

RuntimeException: when lo is greater than hi.

Examples

int32 lo = -1000;
int32 hi = 1000;
int32 top = 2147483647;
int32 bottom = -2147483648;
int32 mid = 300;
console.writeln(top.clamp(lo, hi));
console.writeln(bottom.clamp(lo, hi));
console.writeln(mid.clamp(lo, hi));
try {
    console.writeln(mid.clamp(hi, lo));
} catch (RuntimeException e) {
    console.writeln("caught: ${e.message}");
}

Run it ▶

1000
-1000
300
caught: clamp: lo > hi

max

@__narrowShared("max")
max(int32 other) -> int32

Return the larger of two int32 values.

Parameters

other: The value to compare with.

Returns

this if it is greater than other, otherwise other.

Examples

int32 top = 2147483647;
int32 bottom = -2147483648;
console.writeln(top.max(bottom));
console.writeln(bottom.max(bottom));

Run it ▶

2147483647
-2147483648

min

@__narrowShared("min")
min(int32 other) -> int32

Return the smaller of two int32 values.

Parameters

other: The value to compare with.

Returns

this if it is less than other, otherwise other.

Examples

int32 top = 2147483647;
int32 bottom = -2147483648;
console.writeln(top.min(bottom));
console.writeln(top.min(top));

Run it ▶

-2147483648
2147483647

pow

@__narrowShared("pow")
pow(int32 e) -> int32

Raise the int32 to a power, wrapping at 32 bits.

The multiplication is repeated squaring and wraps at 32 bits at every step, so the result is the true power folded into -2147483648..2147483647: 3 to the 20th is -808182895 (3486784401 minus 4294967296) and 2 to the 31st is -2147483648. A negative exponent has no integer result and gives 0, as with int.pow.

Parameters

e: The exponent.

Returns

this to the power e, as a int32.

Examples

int32 three = 3;
int32 twenty = 20;
int32 twentyOne = 21;
console.writeln(three.pow(twenty));
console.writeln(three.pow(twentyOne));
int32 two = 2;
int32 thirtyOne = 31;
console.writeln(two.pow(thirtyOne));
int32 minusOne = -1;
console.writeln(two.pow(minusOne));

Run it ▶

-808182895
1870418611
-2147483648
0

sign

@__narrowShared("sign")
sign() -> int32

Return the sign of the value.

Returns

-1 if this is negative, 0 if it is zero, and 1 if it is positive, as a int32.

Examples

int32 bottom = -2147483648;
int32 zero = 0;
int32 top = 2147483647;
console.writeln(bottom.sign());
console.writeln(zero.sign());
console.writeln(top.sign());

Run it ▶

-1
0
1

toFloat

toFloat() -> float

Convert the int32 to a float.

The conversion is exact: every value of a int32 is representable as a float.

Returns

The value as a float.

Examples

int32 top = 2147483647;
console.writeln(top.toFloat());
console.writeln(top.toFloat() / 2.0);

Run it ▶

2147483647.000000
1073741823.500000

toHex

toHex() -> string

Format the int32 in hexadecimal.

The digits are lowercase with no 0x prefix and no padding. A negative value gets a leading - before the digits of its magnitude, so -2147483648 formats as -80000000 and -1 as -1.

Returns

The hexadecimal digits of this.

Examples

int32 top = 2147483647;
console.writeln(top.toHex());
int32 bottom = -2147483648;
console.writeln(bottom.toHex());
int32 minusOne = -1;
console.writeln(minusOne.toHex());

Run it ▶

7fffffff
-80000000
-1

toInt

toInt() -> int

Convert the int32 to an int.

The value is unchanged; every int32 value fits in an int, so this conversion never throws. Convert back with int.toInt32, which throws when the value is outside -2147483648..2147483647.

Returns

The same number as an int.

Examples

int32 m = -2147483648;
console.writeln(m.toInt() - 1);
console.writeln(m - 1);

Run it ▶

-2147483649
2147483647

toString

toString() -> string

Format the int32 as decimal text.

A negative value gets a leading -. The toString(int radix) overload formats in another base.

Returns

The decimal digits of this.

Examples

int32 n = -2147483648;
console.writeln(n.toString());
console.writeln("n = " + n.toString());
console.writeln(n.toString(2));
console.writeln(n.toString(16));

Run it ▶

-2147483648
n = -2147483648
-10000000000000000000000000000000
-80000000

toString(int radix) -> string

Format the int32 as text in the given base.

Digits above 9 are lowercase letters (a is ten). A negative value gets a leading - before the digits of its magnitude. This formats the same number as toInt().toString(radix).

Parameters

radix: The base, from 2 to 36 inclusive.

Returns

The digits of this in base radix.

Throws

RuntimeException: when radix is outside 2..36.