# Types and literals

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

## 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.

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

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

```lane
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.

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

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

```lane
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`.

```lane
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.

```lane
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.

```lane
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:

```lane
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:

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

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

```text
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:

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

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

```text
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:

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

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

```lane
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`.

```lane
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:

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

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

```text
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.

```lane
nul main() { if 1 { } }
```

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

```text
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:

| Level | Operators | Note |
|---|---|---|
| 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.

```lane
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.

| Type | Stored as | Value | Range |
|---|---|---|---|
| `f32` | IEEE binary32 | the stored float | |
| `f64` | IEEE binary64 | the stored float | |
| `f16` | IEEE binary16 | the stored float | |
| `un8`, `un16` (unorm) | unsigned 8 or 16-bit integer `n` | `n / (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 `n` | `max(n / (2^(k-1) - 1), -1.0)` | -1.0 to 1.0 |
| `bf16`, `f8e4m3`, `f8e5m2` | 16-bit and 8-bit floats for machine-learning data | the stored float | by 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](/docs/targets-hints.md)).
- **`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:

| Field | Type | Size | Holds |
|---|---|---|---|
| `normal` | 3 x `sn8` | 3 bytes | a direction, each component from -1.0 to 1.0 |
| `color` | 4 x `un8` | 4 bytes | red, 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).

```lane
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.

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