v0.4.0

Integers

An integer type holds a whole number in a fixed number of bits. The signed types int8 to int512 use two's complement; the unsigned types uint8 to uint512 hold zero and up. int and uint are as wide as a pointer.

The integer types

TypeBitsBytesMinMaxSuffix
int881−128127i8
int16162−32,76832,767i16
int32324−2,147,483,6482,147,483,647i32
int64648−263 ≈ −9.22 × 1018263 − 1i64
int12812816−2127 ≈ −1.70 × 10382127 − 1i128
int25625632−2255 ≈ −5.79 × 10762255 − 1i256
int51251264−2511 ≈ −6.70 × 101532511 − 1i512
int648as int64as int64i
uint8810255u8
uint16162065,535u16
uint3232404,294,967,295u32
uint646480264 − 1 ≈ 1.84 × 1019u64
uint1281281602128 − 1 ≈ 3.40 × 1038u128
uint2562563202256 − 1 ≈ 1.16 × 1077u256
uint5125126402512 − 1 ≈ 1.34 × 10154u512
uint6480as uint64u

byte is a built-in alias of uint8, for values that are raw storage rather than numbers.

int and uint are pointer-sized: their width follows the target, and it is 64 bits on every target rux 0.4.0 supports. int is the type of an unsuffixed integer literal and of Main's exit status; uint is the type of lengths, indices and sizeof. When a value must keep a width across targets — a file format, a protocol, a C structure — name a fixed-width type.

The 128-, 256- and 512-bit types are ordinary integers: they support every operator and conversion below.

Associated constants

Every integer type has four constants. They are declared in an extension in the standard Core package, so the extension has to be imported from it, by the type's name, and Core listed under [Dependencies]:

ConstantTypeValue
BitsuintWidth in bits
BytesuintStorage size in bytes
Minthe typeSmallest value
Maxthe typeLargest value
import Core::{ int, int8, uint64 };
import Io::PrintLine;

func Main() -> int {
    PrintLine("int8   {} to {}", int8::Min, int8::Max);   // -128 to 127
    PrintLine("uint64 max {}", uint64::Max);              // 18446744073709551615
    PrintLine("int    {} bits", int::Bits);               // 64
    return 0;
}

Without the import, the constant is not found: error: 'Max' not found in extend for type 'int8'. An alias carries the constants of its target, so byte::Max is 255 once byte (or uint8) is imported.

Literals

Integer literals are decimal, hexadecimal (0x), octal (0o) or binary (0b), with _ between digits, and an optional suffix from the table above. An unsuffixed literal takes the type its context requires — the declared type it initialises, or the other operand's type — and is an int otherwise. It must fit that type:

let level: uint8 = 200;
let raised = level + 50;    // 50 is a uint8
let mask = 0xFF00u16;

let tooBig: uint8 = 256; is error: integer literal is out of range for type 'uint8'. Literals gives the full spelling rules.

Operations

OperatorsResultRules
+ - *The operand typeChecked: a result that does not fit stops the program
+% -% *%The operand typeWrap around modulo 2bits
/ %The operand typeTruncate toward zero; panic on a zero divisor
prefix -The operand typeChecked, as 0 - x is
& | ^ ~The operand typeBitwise
<< >> >>>The left operand's typeSee Shift
== != < <= > >=boolNumeric order
++ -- and compound assignment—As the operator they stand for

Overflow

+, -, *, negation, and their compound forms +=, -=, *=, ++ and -- are checked at every width, on every target and in every build profile. A result that does not fit the operation's type stops the program, naming the operator as written:

Panic: integer overflow in '+='
  at Main (Src/Main.rux:3:11)

Nothing is unwound, as for any panic. When the operands are known while compiling, the overflow is a compile error instead: const Sum: uint8 = 200u8 + 100u8; is error: integer overflow in '+': the constant result does not fit 'uint8'.

Wrapping

The wrapping operators +%, -% and *%, and their compound forms +%=, -%= and *%=, keep the low bits of the two's-complement result and never stop. Hashes, random number generators, checksums and ciphers use them; everything else keeps the checked forms, so an overflow nobody meant is a report rather than a wrong value.

var level: uint8 = 250;
level +%= 10;       // 4

var small: int8 = 127;
small +%= 1;        // -128

let hash = (2166136261u32 ^ 0x61) *% 16777619;

They take integer operands only: a float, character or pointer operand is an error.

Checked and saturating methods

Where overflow is an expected answer rather than a mistake, every integer type has methods in Core. CheckedAdd, CheckedSub and CheckedMul return an optional that is none when the result does not fit, and SaturatingAdd, SaturatingSub and SaturatingMul clamp to the type's Min or Max. As with the constants, the type is imported to use them:

import Core::uint8;
import Io::PrintLine;

func Main() -> int {
    let level: uint8 = 250;
    let sum = level.CheckedAdd(10) ?? 0;
    PrintLine("checked: {}", sum);                         // 0
    PrintLine("saturated: {}", level.SaturatingAdd(10));   // 255
    return 0;
}

Generic code, whose type parameters have no such methods, uses the Core functions AddChecked, SubChecked, MulChecked and AddSaturating and its siblings.

Division

/ truncates toward zero and % takes the sign of the dividend: -7 / 2 is -3, and -7 % 2 is -1.

A zero divisor stops the program with a panic, on every target and in every build profile. So does the one signed quotient that does not fit, a type's Min divided by -1, and the matching %:

Panic: division by zero
  at Divide (Src/Main.rux:5:14)

Panic: division overflow
  at Main (Src/Main.rux:16:23)

Mixed operands

Two operands of the same signedness meet at the wider type: an int32 plus an int64 is an int64. Operands of different signedness are an error, since either conversion could change a value — convert one with as to choose:

error: operator '+' cannot combine left operand 'uint64' with right operand 'int64'
error: operator '<' cannot compare left operand 'uint64' with right operand 'int64'

Conversions

An integer widens implicitly to a wider integer of the same signedness, and int and int64 (likewise uint and uint64) convert to each other freely. Everything else is written with as:

ConversionResult
To another integer typeThe same value; a value the target cannot hold stops the program
To a floating-point typeThe nearest representable value
To a boolean typefalse for zero, true for anything else
To a character typeThe character with that code, checked; see Characters
let big: int32 = 300;
let fits = big as int16;           // 300
let small: int32 = 44;
let narrowed = small as int8;      // 44
let ratio = 7 as float64 / 2.0;    // 3.5
let flag = 256 as bool;            // true

An integer as keeps the value or stops the program with Panic: integer cast out of range: big as int8, -1 as uint64 and uint64::Max as int64 all stop, and a constant like them is a compile error, error: constant cast from 'int' to 'uint8' is outside the target type's range. A conversion every source value survives, such as int32 to int64, has no check.

To keep the low bits on purpose, call the Core method Truncate<T>(), imported with the type like the constants: an int32 holding 300 truncates to the int8 44, and an int64 holding -1 to uint64::Max. A wider T extends by the source's signedness, as as does. Generic code converts with Core::ConvertWrapping, and Core::ConvertChecked reports whether a conversion lost the value.

Implicit widening refuses what it cannot do losslessly: let d: int16 = c; for a uint8 c is error: cannot assign 'uint8' to 'int16', and let i: int32 = n; for an int n is error: cannot assign 'int' to 'int32'.

See also