# Constants

> NAME :: expr; constants, exact compile-time arithmetic on 128 bits, typed and untyped constants, and dependency order.

## Declaring a constant

`NAME :: expr;` declares a constant at the top of a module or, as a statement, inside a block. A constant is never assigned. Its value is an integer, a `bool` or an enum value, computed by the compiler from literals, other constants, enum variants, the operators and the conversions `u8(x)` and `Color(n)`, and `size_of(T)` and `align_of(T)`. A call to any other function, a variable, a string, an index or an address is an error.

```lane
STACK :: 64;
MEM :: 16;
```

A constant is the length of an array, a `match` pattern, or a value of its own:

```lane
rec Vm { [STACK]i32 stack; [MEM]i32 mem; usz sp; usz pc; u64 steps; }
```

```lane
N :: f(); 
nul main() { }
```

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

```text
main.ln:1:7: error: this is not a constant expression
```

```lane
N :: 3; 
nul main() { N = 4; }
```

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

```text
main.ln:2:14: error: constant `N` cannot be assigned
```

## Order does not matter

A module-level constant may use constants and types declared later in the file or in an imported module. Constants and records are evaluated in dependency order, however long the chain: a hundred thousand constants, each defined by the next, compile. A dependency cycle is an error whatever the values, and it is reported once, naming the declarations on the way.

```lane
A :: B; 
B :: A; 
nul main() { }
```

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

```text
main.ln:1:1: error: constant `A` is defined in terms of itself through `B`
```

## Untyped and typed constants

An integer constant made only of literals and other untyped constants is **untyped**: its arithmetic is exact on the integers from -2^127 to 2^127 - 1, so `(1 << 64) - 1` is the largest `u64`. An operation whose exact result is outside that range is an error, with the operands in the message. Nothing wraps and nothing is approximated.

```lane
N :: 1 << 127; 
nul main() { }
```

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

```text
main.ln:1:8: error: the constant `1 << 127` is too large to compute
```

Where an untyped constant is used it behaves like a literal: it takes the integer type the context expects and must fit in it.

```lane
N :: 300; 
nul main() { u8 x = N; }
```

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

```text
main.ln:2:21: error: constant `N` = 300 does not fit in `u8`
```

A constant made with a conversion (`u8(200)`) is **typed**: it has that type everywhere, and an operation on typed constants wraps to the type's width exactly as it does at run time (`u8(200) + u8(100)` is 44). Both operands typed must have the same type.

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

Division by zero in a constant is an error, not a fault:

```lane
N :: 10 / 0; 
nul main() { }
```

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

```text
main.ln:1:9: error: division by zero in a constant expression
```

## Constants and visibility

`size_of(T)` and `align_of(T)` take a type name and give an untyped integer constant. A constant of a `pub` declaration is reached from another module as `module.NAME`; one that is not `pub` is refused.

```lane
use limits; 
N :: limits.HIDDEN + 1;
```

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

```text
main.ln:2:12: error: `limits.HIDDEN` is not `pub`
```

The names `size_of`, `align_of`, `cast`, `slice`, `nul` and those of the scalar types cannot be declared as anything that is in scope by its own name: a function, a constant, a record, an enum, a parameter, a variable or a loop variable.

```lane
i8 :: 1; 
nul main() { }
```

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

```text
main.ln:1:1: error: `i8` is a predeclared type and cannot be declared
```

Arithmetic in a runtime expression on constants is not folded: `N * 2` in `u8 c = N * 2;` is a literal operation, so each operand must fit `u8` and the product wraps.
