Standard Library

class int

The signed 64-bit integer type, the default type of whole numbers.

since 0.1.0-alpha.1linuxwindowswasm

Overview

An int holds any value from -9223372036854775808 to 9223372036854775807. A plain integer literal is an int. Arithmetic wraps around in two's complement instead of failing, so 9223372036854775807 + 1 is -9223372036854775808. / and % truncate toward zero (-7 / 2 is -3 and -7 % 2 is -1), and dividing or taking the remainder by zero throws a RuntimeException. &, |, ^, << and >> work on the 64-bit pattern, and >> keeps the sign.

To store an int in one of the narrower integer types, convert it explicitly with toByte, toInt8, toInt16, toInt32 or toUint; those throw when the value does not fit. toFloat converts to float.

Description

int is a signed 64-bit two's-complement integer, the default type of an integer literal. It is a value type: assigning or passing an int copies it.

Arithmetic is exact within the 64-bit range and wraps around at the ends. Division truncates toward zero, and the remainder takes the sign of the dividend. The bitwise operators (&, |, ^, ~) and the shifts work on the full 64-bit pattern, and >> is an arithmetic shift that keeps the sign.

Integer operators

console.writeln(7 / 2);
console.writeln(-7 / 2);
console.writeln(-7 % 3);
console.writeln(6 & 3);
console.writeln(6 | 3);
console.writeln(6 ^ 3);
console.writeln(~6);
console.writeln(1 << 4);
console.writeln(-16 >> 2);
int big = 9223372036854775807;
console.writeln(big + 1);
console.writeln(3.toFloat() / 2);
try {
    console.writeln(1 / (big - big));
} catch (RuntimeException e) {
    console.writeln("caught: ${e.message}");
}
try {
    console.writeln(1 << 64);
} catch (RuntimeException e) {
    console.writeln("caught: ${e.message}");
}

3
-3
-1
2
7
5
-7
16
-4
-9223372036854775808
1.500000
caught: division by zero
caught: shift count out of range

Rules

The range is -9223372036854775808 to 9223372036854775807. Addition, subtraction, multiplication and negation wrap at the ends.
/ truncates toward zero and % has the sign of the left operand: -7 / 2 is -3 and -7 % 3 is -1.
Division or remainder by zero throws a catchable RuntimeException.
A shift count must be in 0..63; any other count throws.
int and float mix freely in arithmetic, and the result is a float. A float stored into an int is truncated toward zero. See lang.numeric-conversions.
Converting to a narrower integer type with toByte(), toInt8(), toInt16(), toInt32() or toUint() throws if the value does not fit. See lang.sized-integers.
toString(radix) formats in any base from 2 to 36 and throws outside that range. toHex() is lowercase with no prefix, and a negative value gets a leading -.
pow wraps like the operators, and a negative exponent gives 0. clamp(lo, hi) throws when lo is greater than hi.

Examples

Formatting and clamping:

Formatting and bounds

console.writeln(2.pow(10));
console.writeln(2.pow(-1));
console.writeln(255.toString(16));
console.writeln((-255).toHex());
console.writeln(5.clamp(1, 3));
try {
    console.writeln(5.toString(1));
} catch (RuntimeException e) {
    console.writeln("caught: ${e.message}");
}
try {
    console.writeln(5.clamp(3, 1));
} catch (RuntimeException e) {
    console.writeln("caught: ${e.message}");
}

1024
0
ff
-ff
3
caught: radix out of range 2..36
caught: clamp: lo > hi

Notes

The method list of int is generated from the standard library source; this page describes the type's behavior.

Examples

Working with int

int a = 7;
int b = 2;
console.writeln(a / b);
console.writeln(a % b);
console.writeln((0 - a) / b);
console.writeln(9223372036854775807 + 1);
console.writeln(-17 >> 2);
console.writeln(a.max(b).pow(3));
int zero = 0;
try {
    console.writeln(a / zero);
} catch (RuntimeException e) {
    console.writeln("caught: ${e.message}");
}

3
1
-3
-9223372036854775808
-5
343
caught: division by zero

Methods

abs

abs() -> int

Return the absolute value.

Two's complement has one more negative value than positive ones, so the absolute value of the smallest int, -9223372036854775808, does not fit and abs returns it unchanged (still negative).

Returns

this when it is zero or positive, otherwise -this.

Examples

console.writeln((-7).abs());
console.writeln(7.abs());
int smallest = 0 - 9223372036854775807 - 1;
console.writeln(smallest.abs());

7
7
-9223372036854775808

clamp

clamp(int lo, int hi) -> int

Limit the integer 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

console.writeln(15.clamp(0, 10));
console.writeln((-4).clamp(0, 10));
console.writeln(7.clamp(0, 10));
try {
    console.writeln(5.clamp(10, 0));
} catch (RuntimeException e) {
    console.writeln("caught: ${e.message}");
}

10
0
7
caught: clamp: lo > hi

max

max(int other) -> int

Return the larger of two integers.

Parameters

other: The value to compare with.

Returns

this if it is greater than other, otherwise other.

Examples

console.writeln(3.max(9));
console.writeln((-5).max(-9));
console.writeln(5.max(-3).min(4));

9
-5
4

See also: min

min

min(int other) -> int

Return the smaller of two integers.

Parameters

other: The value to compare with.

Returns

this if it is less than other, otherwise other.

Examples

console.writeln(3.min(9));
console.writeln((-5).min(-9));
console.writeln(100.min(100));

3
-9
100

See also: max

pow

pow(int e) -> int

Raise the integer to a non-negative power.

The result is an int, computed by repeated squaring, and it wraps around in two's complement if it does not fit: 2.pow(64) is 0 and 2.pow(63) is -9223372036854775808. A negative exponent has no integer result and gives 0. x.pow(0) is 1 for every x, including 0.

Parameters

e: The exponent.

Returns

this to the power e, or 0 when e is negative.

Examples

console.writeln(2.pow(10));
console.writeln(2.pow(63));
console.writeln(2.pow(64));
console.writeln(5.pow(-1));
console.writeln(0.pow(0));

1024
-9223372036854775808
0
0
1

sign

sign() -> int

Return the sign of the integer.

Returns

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

Examples

console.writeln((-42).sign());
console.writeln(0.sign());
console.writeln(42.sign());

-1
0
1

toByte

toByte() -> byte

Convert the integer to a byte.

A byte holds 0 to 255. The conversion does not wrap: a value outside that range throws. To keep only the low eight bits instead, mask first: (x & 255).toByte().

Returns

The value as a byte.

Throws

RuntimeException: when this is below 0 or above 255.

Examples

console.writeln(200.toByte());
console.writeln((300 & 255).toByte());
try {
    console.writeln(300.toByte());
} catch (RuntimeException e) {
    console.writeln("caught: ${e.message}");
}

200
44
caught: toByte: value out of range (0..255)

See also: byte

toFloat

toFloat() -> float

Convert the integer to a float.

The conversion is exact for values whose magnitude is below 2^53 (9007199254740992). Larger values are rounded to the nearest representable float.

Returns

The value as a float.

Examples

console.writeln(7.toFloat());
console.writeln(7.toFloat() / 2.0);
console.writeln(9007199254740993.toFloat());

7.000000
3.500000
9007199254740992.000000

toHex

toHex() -> string

Format the integer in hexadecimal.

The digits are lowercase, there is no 0x prefix and no padding, and a negative value gets a leading - before the digits of its magnitude. The smallest int formats as -8000000000000000.

Returns

The hexadecimal digits of this.

Examples

console.writeln(255.toHex());
console.writeln((-255).toHex());
console.writeln(0.toHex());
console.writeln(9223372036854775807.toHex());

ff
-ff
0
7fffffffffffffff

See also: toString

toInt16

toInt16() -> int16

Convert the integer to an int16.

An int16 holds -32768 to 32767. The conversion does not wrap: a value outside that range throws.

Returns

The value as an int16.

Throws

RuntimeException: when this is below -32768 or above 32767.

Examples

console.writeln((-32768).toInt16());
console.writeln(32767.toInt16());
try {
    console.writeln(40000.toInt16());
} catch (RuntimeException e) {
    console.writeln("caught: ${e.message}");
}

-32768
32767
caught: toInt16: value out of range (-32768..32767)

See also: int16

toInt32

toInt32() -> int32

Convert the integer to an int32.

An int32 holds -2147483648 to 2147483647. The conversion does not wrap: a value outside that range throws.

Returns

The value as an int32.

Throws

RuntimeException: when this is below -2147483648 or above 2147483647.

Examples

console.writeln(2147483647.toInt32());
console.writeln((-2147483648).toInt32());
try {
    console.writeln(3000000000.toInt32());
} catch (RuntimeException e) {
    console.writeln("caught: ${e.message}");
}

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

See also: int32

toInt8

toInt8() -> int8

Convert the integer to an int8.

An int8 holds -128 to 127. The conversion does not wrap: a value outside that range throws. To keep only the low eight bits instead, mask first and subtract 256 when the result exceeds 127.

Returns

The value as an int8.

Throws

RuntimeException: when this is below -128 or above 127.

Examples

console.writeln((-128).toInt8());
console.writeln(127.toInt8());
try {
    console.writeln(200.toInt8());
} catch (RuntimeException e) {
    console.writeln("caught: ${e.message}");
}

-128
127
caught: toInt8: value out of range (-128..127)

See also: int8

toString

toString() -> string

Convert the integer to its decimal text.

A negative value gets a leading -. Use the toString(int radix) overload for another base and toHex for hexadecimal.

Returns

The decimal digits of this.

Examples

console.writeln(42.toString());
console.writeln((-7).toString());
console.writeln("count: " + 3.toString());
console.writeln(255.toString(2));
console.writeln(35.toString(36));

42
-7
count: 3
11111111
z

toString(int radix) -> string

Format the integer as text in the given base.

Digits above 9 are lowercase letters, so a is ten and z is thirty-five. A negative value gets a leading -. Unlike the no-argument overload this works for every base from 2 to 36.

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.

See also: toHex

toUint

toUint() -> uint

Convert the integer to a uint.

A uint is an unsigned 32-bit integer holding 0 to 4294967295. The conversion does not wrap: a negative value or one above 4294967295 throws.

Returns

The value as a uint.

Throws

RuntimeException: when this is below 0 or above 4294967295.

Examples

console.writeln(4294967295.toUint());
try {
    console.writeln((-1).toUint());
} catch (RuntimeException e) {
    console.writeln("caught: ${e.message}");
}

4294967295
caught: toUint: value out of range (0..4294967295)

See also: uint

See also

Sized integers: byte, int8, int16, int32, uint — The fixed-width integer types, how arithmetic wraps, how mixed widths combine, and when conversions throw.
Numeric conversions and working types — How operands of different numeric types combine, and when a value is converted on its way into a typed variable, field, parameter or return.
float — A 64-bit IEEE 754 floating-point number (binary64).