Standard Library

class uint

An unsigned 32-bit integer: a uint holds 0 to 4294967295 and is stored unboxed.

since 0.1.0-alpha.1linuxwindowswasm

Overview

Arithmetic between uint values wraps around at 32 bits instead of failing: 4294967295 + 1 is 0 and 0 - 1 is 4294967295. Values above 2147483647 are ordinary: 3000000000 / 2 is 1500000000, comparisons order them as the large numbers they are, and >> shifts in zeros. A bare integer literal next to a uint operand counts as a uint, but combining a uint with any signed integer, int included, computes as int. Division or remainder by zero throws a RuntimeException. A literal assigned to a uint is checked when the program is compiled.

Converting an int with int.toUint() does not wrap, it throws when the value is below 0 or above 4294967295. toInt() converts back and never fails. A uint has no abs or sign, because an unsigned value has nothing to negate.

Examples

Wrapping and range

uint top = 4294967295;
uint one = 1;
console.writeln(top + one);
uint zero = 0;
console.writeln(zero - one);
uint big = 3000000000;
console.writeln(big / 2);
console.writeln(big >> 4);
try {
    console.writeln((-1).toUint());
} catch (RuntimeException e) {
    console.writeln("caught: ${e.message}");
}

Run it ▶

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

Methods

clamp

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

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

uint lo = 10;
uint hi = 100;
uint top = 4294967295;
uint zero = 0;
uint mid = 50;
console.writeln(top.clamp(lo, hi));
console.writeln(zero.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 ▶

100
10
50
caught: clamp: lo > hi

max

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

Return the larger of two uint values.

Parameters

other: The value to compare with.

Returns

this if it is greater than other, otherwise other.

Examples

uint top = 4294967295;
uint small = 5;
console.writeln(top.max(small));
console.writeln(small.max(small));

Run it ▶

4294967295
5

min

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

Return the smaller of two uint values.

Parameters

other: The value to compare with.

Returns

this if it is less than other, otherwise other.

Examples

uint top = 4294967295;
uint small = 5;
console.writeln(top.min(small));
console.writeln(top.min(top));

Run it ▶

5
4294967295

pow

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

Raise the uint 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 modulo 4294967296: 3 to the 20th is 3486784401, but 3 to the 21st is 1870418611 (10460353203 minus two times 4294967296). The exponent is a uint too, so it cannot be negative.

Parameters

e: The exponent.

Returns

this to the power e, as a uint.

Examples

uint three = 3;
uint twenty = 20;
uint twentyOne = 21;
console.writeln(three.pow(twenty));
console.writeln(three.pow(twentyOne));
uint two = 2;
uint thirtyTwo = 32;
console.writeln(two.pow(thirtyTwo));

Run it ▶

3486784401
1870418611
0

toFloat

toFloat() -> float

Convert the uint to a float.

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

Returns

The value as a float.

Examples

uint top = 4294967295;
console.writeln(top.toFloat());
console.writeln(top.toFloat() / 2.0);

Run it ▶

4294967295.000000
2147483647.500000

toHex

toHex() -> string

Format the uint in hexadecimal.

The digits are lowercase with no 0x prefix and no padding. Because a uint is never negative there is no - form: 4294967295 formats as ffffffff.

Returns

The hexadecimal digits of this.

Examples

uint top = 4294967295;
console.writeln(top.toHex());
uint small = 255;
console.writeln(small.toHex());
uint zero = 0;
console.writeln(zero.toHex());

Run it ▶

ffffffff
ff
0

toInt

toInt() -> int

Convert the uint to an int.

The value is unchanged; every uint value fits in an int, so this conversion never throws. Convert back with int.toUint, which throws when the value is outside 0..4294967295.

Returns

The same number as an int.

Examples

uint top = 4294967295;
console.writeln(top.toInt() + 1);
console.writeln(top + 1);

Run it ▶

4294967296
0

toString

toString() -> string

Format the uint 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

uint n = 4294967295;
console.writeln(n.toString());
console.writeln("n = " + n.toString());
console.writeln(n.toString(2));
console.writeln(n.toString(16));

Run it ▶

4294967295
n = 4294967295
11111111111111111111111111111111
ffffffff

toString(int radix) -> string

Format the uint 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.