Types and literals

Scalar types, wrapping arithmetic, literals that take their type from context, and why nothing converts implicitly.

Markdown version of this page

#Scalars

The scalar types are i8 i16 i32 i64 u8 u16 u32 u64 isz usz f16 f32 f64 bool. nul is the empty type: the return type of a function that returns nothing, and the pointee of an untyped pointer (*nul). The names of types are ordinary identifiers that the compiler predeclares, so adding a type never changes the lexer.

isz and usz are distinct types from i64 and u64, so code that mixes them does not silently depend on the pointer width. A bool occupies one byte that is 0 or 1.

#Integer arithmetic wraps

Arithmetic is two's complement and wraps: +, -, * and unary - keep the low bits of the exact result. Overflow is never an error and never undefined.

i32 main() { i8 a = 127; a += 1; ret i32(a); }

Verified: builds and runs. Exit code -128 (0xffffff80). No stdout.

i32 main() { u8 a = 0; a -= 1; ret i32(a); }

Verified: builds and runs. Exit code 255. No stdout.

/ truncates toward zero and % has the sign of the dividend; both are unsigned for unsigned types.

i32 main() { i32 a = -7; ret a / 2; }

Verified: builds and runs. Exit code -3 (0xfffffffd). No stdout.

i32 main() { i32 a = -7; ret a % 2; }

Verified: builds and runs. Exit code -1 (0xffffffff). No stdout.

Division and remainder by zero are not checked. The processor's divide fault stops the program; on Windows the exit code is 0xc0000094.

i32 main() { u32 a = 5; u32 b = 0; ret i32(a / b); }

Verified: builds and runs. Exit code -1073741676 (0xc0000094). No stdout.

>> copies the sign of a signed value and shifts zeros into an unsigned one. The shift count is taken modulo the width of the type, so shifting a u8 by 8 leaves it unchanged.

i32 main() { u8 a = 1; u8 n = 8; ret i32(a << n); }

Verified: builds and runs. Exit code 1. No stdout.

#Literals take their type from where they are used

An integer literal has no type of its own. It takes the type of the other operand, or the type the context expects, and it must fit. There are no literal suffixes: a number that runs into identifier bytes (12abc, 1.5f) is one error token. Digits may be separated by _, and there are hexadecimal (0xff) and binary (0b1010) forms.

i32 main() { u8 a = 200; u8 b = a + 100; ret i32(b); }

Verified: builds and runs. Exit code 44. No stdout.

When both operands are literals they take the type the context expects, each must fit, and the result wraps:

i32 main() { u8 c = 200 + 100; ret i32(c); }

Verified: builds and runs. Exit code 44. No stdout.

Where nothing gives a type, that is an error, and the message says how to give one:

nul main() { a := 1 + 2; }

Verified: the compiler refuses this program (exit code 1). Compiler output:

main.ln:1:19: error: the type of this integer is not known here; convert it, as in `u32(1)`

A literal that does not fit is an error as well, and no negative literal fits in an unsigned type:

nul main() { u8 a = -1; }

Verified: the compiler refuses this program (exit code 1). Compiler output:

main.ln:1:21: error: `-1` does not fit in `u8`

A character literal is an integer, the value of its one byte, and takes its type from where it is used:

i32 main() { u8 c = 'a'; ret i32(c); }

Verified: builds and runs. Exit code 97. No stdout.

i32 main() { ret 'a' + 1; }

Verified: builds and runs. Exit code 98. No stdout.

A string literal is a []u8 of its bytes with no terminator; its escapes are \n \t \r \0 \\ \" \' and \xNN. Source files are ASCII: any byte other than tab, line feed, carriage return and 0x20 to 0x7e is a lexical error, even inside a string or a comment. Write other bytes as \xNN.

#No implicit conversions

There are no implicit conversions between types. u32(x) converts between integer types: narrowing keeps the low bits, widening extends by the sign of the source type. A bool converts to any integer type as the 0 or 1 it is; there is no conversion from an integer to bool, so write x != 0.

i32 main() { i8 a = -7; i8 b = 2; ret i32(a / b) * 10 + i32(a % b); }

Verified: builds and runs. Exit code -31 (0xffffffe1). No stdout.

Mixing types in one operator is an error, in constants as well as in code:

N :: u8(1) + u16(1); 
nul main() { }

Verified: the compiler refuses this program (exit code 1). Compiler output:

main.ln:1:12: error: `+` needs operands of the same type, found `u8` and `u16`

The condition of if and for is a bool; an integer is not a condition.

nul main() { if 1 { } }

Verified: the compiler refuses this program (exit code 1). Compiler output:

main.ln:1:17: error: expected `bool`, found an integer

#Operators

+ - * / % & | ^ << >> take two operands of the same integer type and give that type. Comparisons give a bool. && and || evaluate the right operand only when the left does not decide. Operands and arguments are evaluated left to right. Operators from loosest to tightest:

LevelOperatorsNote
0.. ..=do not chain
1||
2&&
3== != < <= > >=do not chain
4+ - | ^
5* / % << >> &

Bitwise operators bind tighter than comparisons, so a & b == c means (a & b) == c. Comparisons do not chain. Unary - ! ~ * and & bind tighter than any binary operator.

i32 main() { i32 a = 6; if a & 3 == 2 { ret 1; } ret 2; }

Verified: builds and runs. Exit code 1. No stdout.

#Number types

Besides the integers, Lane has a family of number types for fractional values. They are all described by one rule: arithmetic happens in f32, and the result is rounded once when it is stored. Because the rounding is one exact step, every operation gives bit-identical results on every processor.

TypeStored asValueRange
f32IEEE binary32the stored float
f64IEEE binary64the stored float
f16IEEE binary16the stored float
un8, un16 (unorm)unsigned 8 or 16-bit integer nn / (2^k - 1), with k the bit count (8 or 16)0.0 to 1.0
sn8, sn16 (snorm)signed 8 or 16-bit integer nmax(n / (2^(k-1) - 1), -1.0)-1.0 to 1.0
bf16, f8e4m3, f8e5m216-bit and 8-bit floats for machine-learning datathe stored floatby format
  • f32 and f64 are IEEE floats. They are strict by default: operations happen in source order and nothing is fused, so the bits are the same on every target. A function relaxes this with @fp (see Per-ISA code, hints and floats).
  • f16 is IEEE binary16. Every operation is computed in f32 and rounded once, so it is correctly rounded and gives identical bits on every processor.
  • un8 and un16 (unorm) store an integer n that means n / (2^k - 1), a value from 0.0 to 1.0. Converting from a float clamps to 0.0..1.0 first, then rounds to nearest even; a NaN gives 0.
  • sn8 and sn16 (snorm) store a signed integer n that means max(n / (2^(k-1) - 1), -1.0), a value from -1.0 to 1.0. The most negative integer, -128 for sn8, means -1.0, the same value as -127. Converting from a float clamps to -1.0..1.0, rounds to nearest even, and turns a NaN into 0.
  • bf16, f8e4m3 and f8e5m2 are for machine-learning data. They follow the same rule: a conversion to or from f32 rounds once, to nearest even, and gives the same bits on every processor.
  • packed arrays store these types at their real width: an array of un8 takes one byte per element, an array of f16 two.

A vertex shows why they exist. A record with a normal and a colour:

FieldTypeSizeHolds
normal3 x sn83 bytesa direction, each component from -1.0 to 1.0
color4 x un84 bytesred, green, blue and alpha, each from 0.0 to 1.0

That is 7 bytes for a normal and a colour, where f32 components would need 28. Code that reads the fields sees f32 values; the conversions are the rules above.

#Vectors and function types

Vector types are written <scalar>x<lanes>. f32x4 is one SIMD register holding four floats and is a value; [4]f32 is four floats in memory; f32xw has as many lanes as the target's widest vector (16 with AVX-512, 8 with AVX2, 4 with NEON or SIMD128).

f32 dot4(f32x4 a, f32x4 b) {
    ret hsum(a * b);
}

A function type puts the return type first, like a function declaration: f32 fn(f32, f32). It is a code address and nothing else; there are no closures, so a callback that needs state takes it as a parameter.

f32 fold([]f32 v, f32 init, f32 fn(f32, f32) op) {