Standard Library

class byte

An unsigned 8-bit integer: a byte holds 0 to 255 and is stored unboxed.

since 0.1.0-alpha.1linuxwindowswasm

Overview

Arithmetic between byte values wraps around at 8 bits instead of failing: 250 + 10 is 4 and 0 - 1 is 255. A bare integer literal next to a byte operand counts as a byte, while an int variable makes the result an int. Division or remainder by zero throws a RuntimeException. A literal assigned to a byte is checked when the program is compiled, so byte b = 256; is an error.

Converting an int with int.toByte() does not wrap, it throws when the value is outside 0..255; to keep only the low eight bits, mask first with (x & 255).toByte(). toInt() converts back and never fails. A byte has no abs or sign, because an unsigned value has nothing to negate.

Examples

Wrapping and range

byte b = 250;
byte step = 10;
console.writeln(b + step);
int n = 10;
console.writeln(b + n);
byte zero = 0;
console.writeln(zero - 1);
try {
    console.writeln(300.toByte());
} catch (RuntimeException e) {
    console.writeln("caught: ${e.message}");
}

Run it ▶

4
260
255
caught: toByte: value out of range (0..255)

Methods

clamp

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

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

byte lo = 10;
byte hi = 20;
byte big = 250;
byte low = 3;
byte mid = 15;
console.writeln(big.clamp(lo, hi));
console.writeln(low.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 ▶

20
10
15
caught: clamp: lo > hi

max

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

Return the larger of two byte values.

Parameters

other: The value to compare with.

Returns

this if it is greater than other, otherwise other.

Examples

byte a = 250;
byte b = 7;
console.writeln(a.max(b));
console.writeln(b.max(b));

Run it ▶

250
7

min

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

Return the smaller of two byte values.

Parameters

other: The value to compare with.

Returns

this if it is less than other, otherwise other.

Examples

byte a = 250;
byte b = 7;
console.writeln(a.min(b));
console.writeln(a.min(a));

Run it ▶

7
250

pow

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

Raise the byte to a power, wrapping at 8 bits.

The multiplication is repeated squaring and wraps at 8 bits at every step, so the result is the true power modulo 256: 3 to the 5th is 243, but 3 to the 6th is 217 (729 minus 512). The exponent is a byte too, so it cannot be negative.

Parameters

e: The exponent.

Returns

this to the power e, as a byte.

Examples

byte three = 3;
byte five = 5;
byte six = 6;
console.writeln(three.pow(five));
console.writeln(three.pow(six));
byte two = 2;
byte eight = 8;
console.writeln(two.pow(eight));

Run it ▶

243
217
0

toFloat

toFloat() -> float

Convert the byte to a float.

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

Returns

The value as a float.

Examples

byte b = 250;
console.writeln(b.toFloat());
console.writeln(b.toFloat() / 4.0);

Run it ▶

250.000000
62.500000

toHex

toHex() -> string

Format the byte in hexadecimal.

The digits are lowercase with no 0x prefix and no padding. Because a byte is never negative there is no - form: 255 formats as ff.

Returns

The hexadecimal digits of this.

Examples

byte b = 250;
console.writeln(b.toHex());
byte small = 5;
console.writeln(small.toHex());
byte top = 255;
console.writeln(top.toHex());

Run it ▶

fa
5
ff

toInt

toInt() -> int

Convert the byte to an int.

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

Returns

The same number as an int.

Examples

byte b = 255;
int wide = b.toInt();
console.writeln(wide + 1);
console.writeln(b + 1);

Run it ▶

256
0

toString

toString() -> string

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

byte b = 200;
console.writeln(b.toString());
console.writeln("b = " + b.toString());
console.writeln(b.toString(2));
console.writeln(b.toString(16));

Run it ▶

toString(int radix) -> string

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