Type System

Neuro is statically typed. Annotations are explicit by default and optional where the initializer's type is unambiguous: literals take their type from context, and every other expression already carries the type the checker resolved for it.

Current Status

• Implemented: primitive types (integers, floats, booleans, char)
• Implemented: half-precision scalars (f16, bf16) with a narrow storage/cast/compare contract
• Implemented: extended integer types (i8-i64, u8-u64)
• Implemented: function types
• Implemented: void type
• Implemented: contextual inference for numeric literals
• Implemented: string type
• Implemented: structs (definition, instantiation, field access, field mutation)
• Implemented: fixed-size arrays [T; N] of Copy elements
• Implemented: borrowed slices &[T] / &mut [T] over an array, a Vec<T>, or a sub-range
• Implemented: tuples (T1, T2, ...) of Copy elements, with destructuring
• Implemented: generic functions, structs, and impls, monomorphized
• Implemented: traits, operator traits, and impl / dyn dispatch
• Implemented: enums, generic enums, Option<T> / Result<T, E>, and the standard collections
• Implemented: statically shaped tensors Tensor<T, [d0, ...]> — annotations, literal coercion, the construction helpers, and the ownership surface (.clone(), .to(device))

Primitive Types

Integer Types

Neuro supports 8 integer types with different sizes and signedness:

Signed Integers

Unsigned Integers

Examples:

1func demo_integers() -> i32 {2    val tiny: i8 = 127           // Smallest signed3    val small: i16 = 32767       // Medium signed4    val normal: i32 = 2147483647 // Default signed5    val big: i64 = 9223372036854775807  // Largest signed6 7    val byte: u8 = 255           // Smallest unsigned8    val word: u16 = 65535        // Medium unsigned9    val dword: u32 = 4294967295  // Large unsigned10    val qword: u64 = 18446744073709551615  // Largest unsigned11 12    return normal13}

Default Type: Integer literals default to i32 when no annotation is present. Contextual inference from declaration, parameter, and return context is implemented; range validation is enforced (e.g. 300 cannot be assigned to i8). If an unannotated integer literal exceeds the range of i32 (e.g. 5000000000), a compile error is emitted. It is not silently promoted to i64.

Type Suffixes: A suffix appended directly to an integer literal overrides contextual inference and pins the type:

1val a = 42i64      // i64, no annotation needed2val b = 255u8      // u83val c = 0xFFu8     // hex literal with suffix4val d = 0b1010i32  // binary literal with suffix

Valid suffixes: i8, i16, i32, i64, u8, u16, u32, u64. The value is range-checked against the suffix type at compile time; 300u8 is a compile error.

Integer Overflow

When a runtime +, -, or * produces a result outside the range of its integer type, the behavior depends on the optimization level the program was compiled with:

1func main() -> i32 {2    mut x: u8 = 200u83    val y: u8 = 100u84    val z: u8 = x + y   // 300 > u8::MAX5    // Debug (-O0):   aborts here6    // Release (-O2): wraps to 447    return z as i328}

The debug-build trap turns a silent miscalculation into an immediate failure during development, while release builds match the zero-overhead wrapping behavior of the underlying hardware. The check is applied to +, -, *, and unary - only; division and modulo are unaffected. Compile-time constant folding always uses wrapping arithmetic regardless of optimization level.

Unary negation is 0 - x, so it overflows wherever that subtraction does: at a signed type's MIN, and at every nonzero value of an unsigned type.

1mut y: u8 = 1u82val n = -y          // Debug: aborts. Release: wraps to 255.

A negative literal written for an unsigned type is rejected outright rather than deferred to run time, because a literal is range-checked against the value it denotes:

1// val x: u8 = -1        // COMPILE ERROR: -1 is negative and u8 is unsigned2val x: u8 = 0u8.wrapping_sub(1u8)   // 255, if the wrap is what you meant

Integer Methods

When the overflow behavior matters, request it explicitly with a builtin intrinsic method. These dispatch on any integer receiver and take one same-typed argument. They are compiler-known intrinsics, not user-defined impl methods.

1val a: u8 = 2002val b: u8 = 1003val wrapped: u8   = a.wrapping_add(b)     // 44   (200 + 100 = 300, wraps mod 256)4val saturated: u8 = a.saturating_add(b)   // 255  (clamps to u8::MAX)5val floored: u8   = b.saturating_sub(a)   // 0    (unsigned underflow clamps to 0)6val shifted: u8   = a.shr(2)              // 50   (200 >> 2, logical)

checked_* is the reporting form: the overflow is not papered over, and the caller must deconstruct the Option before using the value. T is the receiver's own type, so 200u8.checked_add(100u8) is an Option<u8>.

1val checked: Option<u8> = a.checked_add(b)2val total: u8 = match checked {3    Option::Some(v) => v,4    Option::None => 0u8               // 300 does not fit in a u85}

None of these ever trap: the checked forms compile to the LLVM *.with.overflow intrinsics and select the variant from the overflow bit, so there is no branch on the happy path.

Floating-Point Types

f16 is the IEEE-754 half float; bf16 is bfloat16, which trades mantissa bits for an f32-sized exponent range. Both are full scalar primitives with a deliberately narrow contract (see Half-Precision Types below).

Examples:

1func demo_floats() -> f64 {2    val pi: f32 = 3.14159        // Single precision3    val e: f64 = 2.71828182845   // Double precision (default)4    val sci: f64 = 1.23e10       // Scientific notation5 6    return e7}

Default Type: Float literals default to f64. Contextual inference from declaration, parameter, and return context is implemented.

Type Suffixes: A suffix appended directly to a float literal overrides contextual inference and pins the type:

1val a = 1.5f32        // f32, no annotation needed2val b = 2.0f64        // f643val c = 1e10f32       // exponent form with suffix4val d = 1.5e-5f64     // fractional + exponent with suffix

Valid suffixes: f16, bf16, f32, f64. The suffix attaches directly to the literal; no whitespace is permitted between the digits and the suffix. The exponent form (1e10f32) and the fractional form (1.5f32) both accept a suffix.

Float Methods

Floats follow IEEE 754 in full, so every comparison against NaN is false — NaN == NaN and NaN != NaN alike. That makes NaN undetectable with the comparison operators, and .is_nan() is the way to test for it:

1val zero: f64 = 0.02val nan: f64 = zero / zero    // 0.0 / 0.0 is NaN3val inf: f64 = 1.0 / zero     // division by zero is Inf, an ordinary ordered value4 5val a: bool = nan.is_nan()    // true6val b: bool = inf.is_nan()    // false — infinity is not NaN7val c: bool = nan == nan      // false: the equality operator cannot see it

The result is an ordinary bool, so it composes with !, &&, and ||. Like the integer intrinsics, .is_nan() needs a value receiver: read through a &f64 with *r first. f16 / bf16 do not provide it — their scalar contract is storage and casts only, with no arithmetic that could produce a NaN (see below).

Half-Precision Types (f16 / bf16)

Modern AI relies on half-precision for mixed-precision training, so f16 and bf16 are first-class scalar primitives. To avoid the cross-hardware inconsistency of half-precision ALUs, they carry a narrow scalar contract:

Half-precision literals must carry their suffix; there is no contextual default, so val x: f16 = 1.5 is an error. Write 1.5f16.

Scalar arithmetic is intentionally undefined: half-precision math is not portably specified across hardware. Compute in f32 and cast back:

1func main() -> i32 {2    val a: bf16 = 10.0bf163    val b: bf16 = 4.0bf164 5    // val bad = a + b            // compile error: arithmetic not defined on bf166    val sum: bf16 = (a as f32 + b as f32) as bf16   // 14.07 8    val h: f16 = 1.5f169    val same: bool = h == 1.5f16  // equality is allowed10    return sum as i32             // 1411}

As tensor element types (Tensor<bf16, [...]>, Phase 2) the restriction lifts entirely: elementwise math, matmul, and reductions lower through MLIR to the accelerator's native half-precision units. The split keeps half-precision where it pays off (bulk tensor compute) without committing the scalar layer to non-portable semantics.

Digit Separators

Underscores may be placed between digits of any numeric literal to improve readability. They carry no value (the compiler strips them before parsing) and work in every base, in floats, in exponents, and alongside type suffixes.

1val million = 1_000_000      // decimal grouping2val mask    = 0xFF_FF        // hex3val flags   = 0b1010_0011    // binary4val perms   = 0o7_5_5        // octal5val ratio   = 1_000.000_5    // float6val scaled  = 1_0e1_0        // exponent7val wide    = 1_000_000i64   // with a type suffix

A separator is only recognized between digits: a leading underscore (_1000) is an identifier, not a number.

Boolean Type

The bool type represents truth values:

1func demo_booleans() -> i32 {2    val is_true: bool = true3    val is_false: bool = false4 5    if is_true {6        return 17    } else {8        return 09    }10}

Values: true or false Operations: Logical operators (&&, ||, !), comparison results

Character Type

The char type is a single Unicode scalar value (a 32-bit code point), not a byte. Char literals are written with single quotes and support escape sequences:

1func demo_chars() -> i32 {2    val letter: char = 'A'3    val newline: char = '\n'4    val emoji: char = '\u{1F44D}'   // thumbs-up, U+1F44D5 6    // char is Copy, so the source stays valid after a bind.7    val also = letter8 9    // Built-in total order: all six comparison operators work directly.10    if letter < 'Z' && also == letter {11        return letter as i32        // as-cast char -> integer (65)12    }13    return 014}

An empty literal (''), a multi-character literal ('ab'), and an unterminated literal ('a) are all lexer errors.

String Type

The string type is an immutable, UTF-8 encoded fat pointer { ptr, i64 }, a pointer to the bytes plus a stored byte length. Equality (==, !=) compares byte content; the + operator concatenates two strings into a new owned string.

Storage and the len Guarantee

String literals live in read-only program memory (.rodata) for the lifetime of the program; they are not heap-allocated, so a program that only reads literals never leaks. Concatenation (a + b) is the first runtime heap-backed string: it mallocs a fresh buffer and copies both operands' bytes in, yielding a new owned string. Both literal and heap-backed forms share the same { ptr, i64 } ABI, so consumers cannot tell them apart. An anonymous heap string — the result of +, of interpolation, or of String::to_string — is owned by no binding the drop machinery tracks, so it still leaks; see the alpha memory warning in the README. A String builder is different: it is a tracked binding, so its buffer is freed at scope exit.

The pointer addresses a NUL-terminated byte sequence so it doubles as a valid C string for future FFI, but the stored len field excludes that trailing NUL. len is the authoritative length: it is the exact UTF-8 byte count of the content. Consumers must use len and must not scan for a NUL terminator, because interior NUL bytes are legal content "a\0b".len() is 3, not 1.

String Methods

Builtin intrinsic methods dispatch on a string receiver via the usual receiver.method() syntax:

1val s: string = "hello, world"2val n: u64 = s.len()    // 12, O(1) read of the stored byte length3val copy: string = s.clone()   // a fresh string equal to s4val hello: &string = s.slice(0..5)    // "hello", borrowed, zero copy5val world: &string = s.slice(7..=11)  // "world", inclusive upper bound

.len() -> u64, returns the number of UTF-8 bytes, read directly from the fat pointer in O(1) with no scan. The length excludes the null terminator. Because the index is a byte count, a multi-byte code point contributes more than one to the length.

.clone() -> string, returns a fresh string equal to its receiver. It is the canonical explicit deep copy for non-Copy owned types and, now that move-by-default has landed (1C, see variables), the way to keep using a value after it would otherwise be moved. Today strings are immutable and .rodata-backed (no heap string type exists yet), so the clone copies the (ptr, len) fat pointer, observationally a deep copy because the pointee bytes are immutable and shared safely. .clone() takes no arguments and returns a string, so it chains with other builtin methods ("hi".clone().len()). Copy scalar types (i8..u64, f32/f64, bool) do not provide .clone(): assignment already duplicates them.

.slice(range) -> &string, returns a borrowed &string view into the receiver's UTF-8 data, with no allocation: since strings are immutable, a sub-range is just a (ptr + start, len) fat pointer (the analogue of Rust's &str). The range is exclusive (s.slice(a..b)) or inclusive (s.slice(a..=b)). Indices are byte offsets, not character offsets. The slice is itself a &string, so it chains (s.slice(0..5).len()) and compares byte-wise (s.slice(0..5) == "hello"). Two boundary rules are enforced at runtime in both debug and release builds and panic (abort, no unwinding, see control flow) on violation:

• Bounds: the range must satisfy 0 <= start <= end <= len. An out-of-bounds or reversed range panics with string slice out of bounds.
• Code-point alignment: each endpoint must fall on a UTF-8 code-point boundary. A range that splits a multi-byte code point panics with string slice splits a UTF-8 code point.

.char_slice(range) -> &string, the codepoint-indexed companion to .slice. It returns the same borrowed, zero-copy &string, but its range counts Unicode code points rather than bytes, walking the UTF-8 data to locate each endpoint — O(n) on the receiver's length, where .slice is O(1). Use it whenever the indices came from counting characters (tokenizer and NLP work); use .slice when the offsets are already byte offsets or the text is known to be ASCII.

1val s = "héllo"                       // 5 characters, 6 bytes: 'é' takes two2val by_char = s.char_slice(0..3)      // "hél" — three characters, four bytes3val by_byte = s.slice(0..3)           // "hé"  — three bytes4val tail = s.char_slice(3..=4)        // "lo", inclusive upper bound5val empty = s.char_slice(5..5)        // "", the character count is a legal bound

Only the bounds rule applies: the range must satisfy 0 <= start <= end <= character count, and a reversed or out-of-range range panics with string char slice out of bounds. There is no code-point-alignment rule to break — a code point index cannot name a position inside a code point, which is the reason to reach for this method in the first place.

A range expression a..b / a..=b is valid only as a .slice or .char_slice argument; used anywhere else it is a compile error.

.chars() -> Chars, an iterator over the receiver's Unicode scalar values. Each step is O(1): the cursor decodes the code point standing at its byte offset and advances by that code point's own UTF-8 width, so no part of the text is scanned twice. Chars is an ordinary Iterator from the prelude (see control flow), which means a for head drives it, .enumerate() numbers the scalars, .map(f) / .filter(p) decorate them, and the iterator itself is a value that can be held and stepped by hand. The receiver is borrowed, not consumed, so the text stays usable afterwards.

1val text = "héllo"2 3for c in text.chars() {4    println("{c}")                    // 5 scalars, though text.len() is 6 bytes5}6 7for (position, c) in text.chars().enumerate() { }   // position counts code points8 9mut walk = text.chars()10val first = walk.next() ?? '?'        // Option::Some('h')

for (offset, c) in text.char_indices(), the same walk with the byte offset of each scalar bound alongside it. Those are the offsets .slice(range) takes, which is what makes the pair the tokenizer's tool: find a position by reading characters, then cut by bytes. An offset names the code point its step yields, never the one after it.

1mut cut: u64 = 02for (offset, c) in "aé漢".char_indices() {3    if c == '漢' { cut = offset }     // 3 — 'a' is one byte, 'é' two4}

.char_indices() is a for-head form, like .enumerate(), rather than a method: it binds a pair, and a pair cannot travel through Iterator::next, whose Option payload is limited to scalars in this phase. So it appears only in a for head, it binds a pair there (never a single variable), and it takes no .enumerate() and no adapters — it already carries a position of its own. Where a chain is wanted, walk .chars() instead.

Growable Strings (String)

string is immutable, which makes it cheap to pass, slice, and share, but wrong for text that is assembled. Writing s = s + piece in a loop allocates a new buffer and recopies everything accumulated so far on every step, so building an n-piece string costs O(n²) bytes copied.

String is the growable counterpart: an owned, mutable, heap-backed UTF-8 buffer that appends in amortized O(1). The pair mirrors [T; N] / Vec<T> exactly, and for the same reason.

1mut report = String::new()          // no annotation needed: `String` takes no type arguments2report.push_str("run: ")3report.push_str(name)               // `name` is read, not moved4report.push_str(" ok")5 6val line: string = report.to_string()   // finished text, immutable from here

String is a compiler-known library type, not a keyword and not a language primitive, the same status Vec<T> has: the language exposes no allocator and no raw pointers, so nothing in .nr source could implement it. A program that declares its own String shadows this one.

String Methods

String::new() -> String, an empty builder. Allocates nothing until the first append, so an unused builder costs no heap traffic. It takes no type arguments, so unlike Vec::new() it needs no annotation to be inferred.

.push_str(text), appends the bytes of a string or an immutable &string. The argument is read, not moved — the same latitude a + operand or a map lookup key gets — so the caller's binding stays usable afterwards. It mutates, so it needs a mut binding or a &mut String.

.len() -> u64, the byte length, read from the header in O(1). Bytes, not characters, for the same reason string.len() is.

.clear(), resets the length to zero and retains the buffer, so refilling in a loop does not reallocate. This is what makes one builder reusable across iterations. It mutates.

.to_string() -> string, copies the accumulated bytes into a fresh owned immutable string. This is the bridge back to string: everything that consumes text — +, ==, .len(), a Vec<string> element, a map key — takes the result. A borrowed view into the buffer would be zero-copy, but a later push_str may reallocate and leave it dangling, and the borrow checker does not yet track a builder's outstanding views, so the copy is the sound answer. It is one allocation at the end of a build, not one per append.

Ownership

String owns a heap buffer, so it follows the ordinary rules with no exceptions: it is never Copy, assignment and argument passing move it, &String / &mut String borrow it, and the buffer is freed when the owner leaves scope.

1mut buf = String::new()2buf.push_str("a")3val moved = buf          // buf is MOVED4// buf.push_str("b")     // COMPILE ERROR: use of moved value 'buf'

Phase 1C Limitations

• No .push(char), String::with_capacity(n), String::from(s), or .is_empty().
• No borrowed .as_str(); use .to_string().
• A String cannot be a collection element or a map key.
• String is not an interpolation hole or a + operand — call .to_string() first.

Struct Types

Structs are user-defined types that group named fields. They use nominal typing, two structs with identical fields are distinct types.

Definition

1struct Point {2    x: f64,3    y: f644}5 6struct Counter {7    value: i32,8    step: i329}

Fields are listed as name: Type, separated by commas or newlines. Any primitive type (or another struct type) is valid as a field type.

Instantiation

1val p = Point { x: 3.0, y: 4.0 }2val c = Counter { value: 0, step: 1 }

All fields must be provided. Extra or missing fields are compile errors.

Field Access

1val x_coord = p.x   // reads field x from p2val total = c.value + c.step

Field access resolves to the declared field type.

Field Mutation

Field mutation is only allowed on mut bindings:

1mut cursor = Point { x: 0.0, y: 0.0 }2cursor.x = 5.0   // OK: cursor is mut3 4val fixed = Point { x: 1.0, y: 2.0 }5fixed.x = 3.0    // Error: AssignToImmutableField

Definition Order

Structs can be used before they are defined in the source file, the compiler performs a pre-registration pass:

1func main() -> i32 {2    val s = Score { value: 42 }3    return s.value4}5 6struct Score {7    value: i328}

Copy and Clone (@derive)

By default a struct is move-by-default, just like string: binding, assigning, returning, or passing it by value moves the source, and reading the source afterward is a use of moved value error. A struct opts out of moving by deriving Copy:

1@derive(Copy, Clone)2struct Point { x: i32, y: i32 }3 4val a = Point { x: 3, y: 4 }5val b = a          // a is COPIED, not moved6val s = a.x + b.y  // a is still valid here

Rules:

• A struct may derive Copy only when every field is Copy. Primitive scalars (i8 to u64, f32, f64, bool) are Copy; string is not; a struct field is Copy only when its type also derives Copy. Violating this is a CopyDeriveNonCopyField error.
• Copy implies Clone.
• @derive(Clone) (or Copy) enables struct.clone(), an explicit deep copy that returns a fresh value without moving the receiver. A user-defined clone method in an impl block shadows the builtin.
• @derive(Debug) gives the struct its {value:?} rendering: the struct's name followed by each field in declaration order, e.g. Point { x: 1, y: 2 }. A field-less struct renders as its bare name. Every field must itself be renderable — a scalar, string, char, bool, or another struct that derives Debug — otherwise the derive is a DeriveFieldUnsupported error. A struct has no display form, so "{p}" stays an error even with the derive; write "{p:?}".
• @derive(PartialEq) gives the struct == and !=, compared field by field. The same field rule applies: a nested struct must derive PartialEq too. The comparison is generated inline and never calls a method, which is why a struct that both derives PartialEq and declares impl PartialEq for it is a DeriveConflictsWithImpl error — keep one.
• The derivable-and-implemented set is exactly Copy, Clone, Debug, PartialEq. Any other name in a @derive list is a compile error, never a silent no-op: Hashable is specified but not generated yet (UnimplementedDerive — write the impl by hand), and anything else is UnknownDerive. A repeated name is DuplicateDerive.
• A derived PartialEq does not satisfy the impl PartialEq a struct key of a HashMap or BTreeMap requires: a collection key calls the trait method, and a derive provides none.

1@derive(Clone)2struct Vec2 { x: f64, y: f64 }3 4val v = Vec2 { x: 1.0, y: 2.0 }5val w = v.clone()  // independent copy; v stays usable

1@derive(Debug, PartialEq)2struct Point { x: i32, y: i32 }3 4val a = Point { x: 1, y: 2 }5val b = Point { x: 1, y: 2 }6println("{a:?} == {b:?} is {a == b}")   // Point { x: 1, y: 2 } == Point { x: 1, y: 2 } is true

See examples/structs/derives.nr for both derives run end to end, including the recursion through a nested struct.

Type Errors

Enum Types

Enums are user-defined types that hold exactly one of several named variants. A variant may be a bare tag, carry a positional tuple payload, or carry named fields, all three may appear in one enum. Like structs, enums use nominal typing.

Definition

1// Bare variants2enum Color {3    Red,4    Green,5    Blue6}7 8// Mixed variant shapes9enum Shape {10    Circle { radius: f64 },              // named-field variant11    Rectangle { width: f64, height: f64 },12    Triangle { base: f64, height: f64 }13}14 15enum Message {16    Quit,                                // unit variant17    Move(i32, i32),                      // tuple variant18    Write(bool)19}

Construction

Each variant shape has its own construction syntax, all prefixed with the enum name:

1val c = Color::Red                       // unit variant2val m = Message::Move(1, 2)              // tuple variant3val s = Shape::Circle { radius: 5.0 }    // struct variant

An enum value can be bound to a val/mut, passed to and returned from functions, and stored in a struct field. Enums are Copy (their payloads are scalar Copy primitives, see below), so binding or passing one duplicates it rather than moving it.

Memory Layout

An enum is a tagged union: a discriminant identifying the active variant, plus storage for the widest variant's payload. Two enums with the same variant names but declared separately are distinct types.

Generic Enums

An enum may take type parameters. Each distinct set of type arguments is monomorphized into its own nominal tagged union, exactly as a generic struct is, so Slot<i32> and Slot<i64> are different types, each with its own payload width, and there is no runtime cost.

1enum Slot<T> { Filled(T), Vacant }2enum Tagged<T, U> { Left(T), Right(U) }3 4val a = Slot::Filled(4)                  // T inferred from the payload → Slot<i32>5val b: Slot<bool> = Slot::Vacant         // no payload, so the annotation fixes T

Where the type arguments come from, in order:

1. The expected type, an annotated binding, a parameter, a struct field, a return.
2. The payload, Slot::Filled(4) determines T = i32 by unifying 4's type against the variant's declared payload.
3. The enclosing function's return type, when it is an instance of the same enum. This is what makes the common fallible-function shape work, because a tail if branch has no other context:

1func divide(a: i32, b: i32) -> Result<i32, i32> {2    if b == 0 {3        Result::Err(1)                   // Err determines E; T comes from the return type4    } else {5        Result::Ok(a / b)                // Ok determines T; E comes from the return type6    }7}

If none of the three determines an argument, the construction is rejected with GenericEnumNotInferable, annotate the target. Using the bare name as a type (func f(o: Slot) -> i32) is GenericEnumNeedsArgs.

A match pattern is written with the base name; it matches whatever instance the scrutinee has, and its payload binds at that instance's concrete type:

1match a {2    Slot::Filled(v) => v + 1,            // v is i32 here3    Slot::Vacant => 04}

Option<T> and Result<T, E>

These two generic enums are the standard library's absence and failure types. They are available in every program without a declaration, the compiler prepends an implicit prelude:

1enum Option<T> { Some(T), None }2enum Result<T, E> { Ok(T), Err(E) }

They are ordinary generic enums: nothing about them is special-cased in the type checker or the backend, and a program that declares its own Option or Result shadows the prelude entry.

1func unwrap_or(o: Option<i32>, fallback: i32) -> i32 {2    match o {3        Option::Some(v) => v,4        Option::None => fallback5    }6}7 8val present = Option::Some(30)9val absent: Option<i32> = Option::None

Variants may be written qualified (Option::Some, Result::Err) or, because the implicit prelude imports Some, None, Ok, and Err into every file without @no_prelude, unqualified (Some(x)). The ?? operator unwraps either type with a fallback, the ? operator unwraps one or hands the failure to the caller, and val-else unwraps one or exits the scope.

Phase 1 Limitations

• Payloads are scalar Copy primitives only, integers, floats, bool, char. A payload of string, a struct, an array, a tuple, or a reference is rejected (UnsupportedEnumPayload); broader payloads arrive with heap support. The rule is enforced per instance, so Option<i32> is available while Option<string> is not yet.
• Type arguments are Copy, the same restriction generic functions and structs carry this phase.
• No impl blocks on enums, methods (and therefore Option/Result helpers such as .map_err) need impls over enums, which are struct-only today.
• No lifetime parameters on an enum, with scalar-only payloads there is nothing to annotate; enum E<'a, T> is a parse error.

Type Errors

Newtype Declarations

A newtype creates a distinct nominal type that wraps an inner type. Unlike a type alias, which is transparent, so the alias and its target are interchangeable, a newtype and its inner type are different types. This buys unit-of-measure and domain-identifier safety at zero runtime cost.

1newtype Meters = i322newtype Seconds = i323newtype Celsius = f64

Construction and Inner Access

Build a newtype value by calling the newtype name with a single inner-typed argument, and read the wrapped value back with .0:

1val d: Meters = Meters(30)     // construction2val raw: i32 = d.0             // inner access

Distinctness

Because a newtype is a separate type, its values are not interchangeable with the inner type or with another newtype over the same inner type:

1val m: Meters = Meters(3)2val bad: i32 = m               // ERROR: expected i32, found Meters3val also_bad = Meters(1) + Seconds(2)  // ERROR: arithmetic is not defined on newtypes

A newtype forwards Copy/Clone from its inner type, so a Copy-inner newtype is itself Copy. It can be a val/mut binding, a function parameter or return type, and a struct field.

Phase 1E Limitations

• Inner type must be Copy, integers, floats, bool, char, and other Copy aggregates. A non-Copy inner such as string is rejected (NewtypeInnerNotCopy); non-Copy wrappers arrive with broader move/heap support.
• No inherent methods or operator traits yet, arithmetic and other operators on a newtype await the trait system (1F). Use .0 to compute on the inner value.

Type Errors

References, Immutable Borrows (&T)

An immutable borrow &T is a non-owning reference to a value. It lets a function read a value without taking ownership, so the caller keeps using its binding afterward. The borrow expression &x takes a reference to the place x.

1func describe(s: &string) -> u64 {2    s.len()                 // method call auto-derefs through the borrow3}4 5func main() -> i32 {6    val msg: string = "Neuro"7    val n: u64 = describe(&msg)   // borrow, msg is NOT moved8    val again: u64 = msg.len()    // still valid: borrowing never consumes9    return 010}

Rules:

• A reference type &T may appear on parameters, return types, and local bindings.
• Borrowing does not move the borrowed value; that is the whole point of a reference. A non-Copy value such as string stays usable after being borrowed.
• &T is itself Copy: passing or re-borrowing a reference duplicates the pointer.
• Method and field access auto-deref through a borrow: r.len() / r.clone() on a &string, and r.field / r.method() on a &Struct, behave as if applied to the referent.
• Only a place (a val/mut/parameter binding) can be borrowed. Borrowing a temporary (a literal or a call result) or a const (an inlined value, not a memory location) is a CannotBorrowValue error.

1struct Point { x: i64, y: i64 }2impl Point {3    func sum(&self) -> i64 { self.x + self.y }4}5 6func read_sum(p: &Point) -> i64 { p.sum() }   // borrow a struct, call through it

Not yet lifetime-verified: a returned &T is not yet checked against the lifetime of the value it points into; that check lands with lifetime inference. Integer intrinsics (r.wrapping_add(..)) still require a value receiver, read through *r first.

References, Mutable Borrows (&mut T)

A mutable borrow &mut T is a non-owning reference that grants write access to a value. The borrow expression &mut x requires x to be a mut binding, you cannot acquire write access through a reference to a value you may not write directly.

Values are read and written through the prefix dereference operator *:

1func increment(n: &mut i32) {2    *n = *n + 1          // read with *n, write with *n = ...3}4 5func main() -> i32 {6    mut counter: i32 = 407    increment(&mut counter)       // mutate in place, counter is borrowed, not moved8    increment(&mut counter)9    return counter                // 4210}

Rules:

• &mut x requires a mut binding; mutably borrowing a val is a compile error (cannot mutably borrow).
• *r reads the referent; dereferencing a non-reference is an error (cannot dereference).
• *r = value writes through the reference and requires r: &mut T; writing through an immutable &T is an error (cannot assign through an immutable reference).
• &mut T and &T are distinct types, there is no implicit &mut T → &T coercion (explicit over implicit).

1func main() -> i32 {2    mut x: i32 = 73    val r: &mut i32 = &mut x4    *r = 355    return *r                     // 356}

Borrow Exclusivity (& / &mut aliasing rules)

The borrow checker enforces two coexistence rules at compile time:

• Any number of shared &T borrows of a place may be live at the same time.
• A &mut T borrow is exclusive: while it is live, no other borrow of that place shared or mutable, may exist.

A borrow's region is lexical. A borrow held by a binding (val r = &x) lives until that binding leaves scope; a borrow passed to a function, used in a condition, or returned ends with the statement that took it. So sequential borrows in separate statements never conflict, and a borrow taken inside a block is released at the block's closing brace.

1func main() -> i32 {2    mut x: i32 = 53    val a: &i32 = &x4    val b: &i32 = &x          // ok, shared borrows coexist5    val c: &mut i32 = &mut x  // ERROR: cannot borrow 'x' as mutable, it is already borrowed6    return 07}

1func inc(n: &mut i32) { *n = *n + 1 }2 3func main() -> i32 {4    mut x: i32 = 05    inc(&mut x)               // the &mut ends with this call6    inc(&mut x)               // ok, the previous borrow is no longer live7    return x                  // 28}

The diagnostics are cannot borrow '<name>' as mutable (a &mut while any borrow is live) and cannot borrow '<name>' as immutable (a & while a &mut is live).

Deferred: this is a lexical check, not non-lexical liveness (NLL). Reading or moving a value while it is borrowed lands with full lifetime inference, which extends the same borrow-region analysis.

Lifetimes, Returned References

Lifetimes are inferred in the vast majority of cases. The elision rules match Rust: a single input reference lifetime is applied to the outputs, and the &self lifetime is applied to a method's outputs. In practice this means a function or method that returns a reference may borrow one of its reference parameters (or, in a method, &self); the returned borrow then lives as long as the caller's borrow.

1func first(a: &i32, b: &i32) -> &i32 {2    a                       // ok, the returned borrow outlives the call3}

The borrow checker rejects returning a reference to a value that dies when the function returns a body-local or a by-value parameter, because the reference would dangle:

1func dangle() -> &i32 {2    val local: i32 = 53    return &local           // ERROR: cannot return a reference to 'local', it is local to4                            //        this function and does not outlive the call5}

The check follows a returned reference through a local reference binding (val r = &local; r is also rejected) and into the arms of a returned if/else. The diagnostic is cannot return a reference to '<name>'.

Explicit lifetime annotations

For the advanced patterns elision cannot express, a lifetime parameter is declared in the generic-parameter list as 'a and used on reference types as &'a T / &'a mut T:

1func longest<'a>(a: &'a string, b: &'a string) -> &'a string {2    if a.len() > b.len() { a } else { b }3}

An annotation is a well-formedness surface only: every lifetime used on a reference must be declared in the enclosing <...> list (an undeclared 'b is the undeclared lifetime error), and the annotation is then erased, &'a T and &T are the same type, so a lifetime costs nothing at runtime and never changes which values a signature accepts. The elision rules above still do the real outlives checking; explicit lifetimes do not tighten or relax it. Lifetime parameters may be mixed with type and const parameters (func f<'a, T>(...)); only the type/const parameters drive monomorphization. Lifetime bounds ('a: 'b) and struct-field references are not part of this surface yet.

String Slices (&string)

&string is the borrowed string slice: a non-owning (ptr, len) view into UTF-8 data. There is no separate slice type, &string is both "a borrow of an owned string" and "a string slice," the analogue of Rust's &str.

A slice is read-only, so its fundamental operation is equality. The operators == and != compare the underlying UTF-8 bytes for any combination of an owned string and a &string slice; a borrowed operand is auto-dereferenced to its fat pointer before the byte compare, so it costs no copy.

1func slices_equal(a: &string, b: &string) -> bool {2    a == b                       // two borrowed slices3}4 5func main() -> i32 {6    val lang: string = "Neuro"7    val same: string = "Neuro"8    val eq: bool = slices_equal(&lang, &same)   // true9    val lit: bool = (&lang == "Neuro")          // true, slice vs owned literal10    if eq && lit { return 0 }11    return 112}

Comparing through borrows never moves: lang stays usable after each &lang. Reference peeling for equality is string-only, so comparing a non-string reference to its value (&n == n on an i32) or mixing types (i32 == &string) is still a type error; reading other &T through == needs the * deref operator.

Void Type

Functions that don't return a value have implicit void return type:

1func print_debug() {2    // No return type specified = void3    // Implicit return at end of function4}5 6// Explicit void (optional, rarely used)7func print_debug_explicit() -> void {8    return9}

Note: The main function must return i32 (exit code), not void.

Type Annotations

Variable Declarations

Type annotations are optional when the type can be inferred from context:

1val x: i32 = 42              // Explicit type annotation2val pi: f64 = 3.14159        // Explicit type annotation3val flag: bool = true        // Explicit type annotation4val n = 100                  // Inferred i32 (default for integer literals)5val pi = 3.14159             // Inferred f64 (default for float literals)

Function Parameters

Function parameters must have explicit type annotations:

1func add(a: i32, b: i32) -> i32 {2    return a + b3}

Function Return Types

Return types must be explicitly specified (or omitted for void):

1func returns_int() -> i32 {2    return 423}4 5func returns_float() -> f64 {6    return 3.147}8 9func returns_nothing() {10    // Implicit void return11}

Type Compatibility

Strict Type System

Neuro uses strict type checking with no implicit conversions in Phase 1:

1func strict_types() -> i32 {2    val x: i32 = 423    val y: i64 = x  // Error: type mismatch (i32 vs i64)4    return y5}

Even compatible types require explicit conversion.

Function Type Checking

Function calls are type-checked strictly:

1func takes_i32(x: i32) -> i32 {2    return x3}4 5func test() -> i32 {6    val x: i64 = 1007    return takes_i32(x)  // Error: expected i32, found i648}

Return Type Checking

All return statements must match the declared return type:

1func returns_i32() -> i32 {2    if true {3        return 42       // OK: i324    } else {5        return 3.14     // Error: expected i32, found f646    }7}

Type System Features

Phase 1, Core Language

Landed (✅):

• Primitive types (i8-i64, u8-u64, f32, f64, bool, char, f16/bf16)

• String type with fat pointer ABI ({ ptr, i64 })

• Explicit type annotations + contextual numeric inference with range validation

• Explicit type conversions via as

• Function types, strict type checking, type-mismatch error reporting

• Structs, methods, fixed-size arrays [T; N], borrowed slices &[T] / &mut [T], tuples + destructuring, type aliases

• Enums with associated data enum E { A, B(T), C { f: T } }, generic enums enum Slot<T> { ... }

• Pattern matching, newtypes

• Generics + monomorphization, traits, operator traits, static/dynamic dispatch, closures

• Option<T> / Result<T, E> from the implicit prelude, the ?? coalescing and ? propagation operators, val-else binding

• Collections Vec<T> / HashMap<K, V> / BTreeMap<K, V>, checked_* integer methods

• Modules and imports: multi-file programs, inline module blocks, re-exports, and the implicit prelude (see modules.md)

• String interpolation with the format mini-language ("{x:.2}") and triple-quoted block strings with dedent, see expressions.md

• Named arguments with external labels, see functions.md

• Growable runtime strings through the String buffer (String::new / .push_str / .clear / .to_string)

Phase 1 has no remaining work; every sub-phase 1A-1H is complete.

Phase 2, Tensors

• Implemented: static tensor types Tensor<f32, [3, 3]>, literal coercion, the construction helpers, and tensor ownership (see Tensor Types)
• Planned: reading a tensor back — indexing, slicing, arithmetic, and reductions
• Planned: broadcasting rules
• Planned: shape generics, named dimensions, and dynamic shapes

Type Safety Guarantees

Neuro's type system provides:

1. No undefined behavior from type errors: All type errors caught at compile time
2. No implicit conversions: Explicit is better than implicit
3. Function type safety: Arguments and returns type-checked
4. Memory safety: Types prevent invalid memory access (future: ownership system)

Common Type Errors

Type Mismatch

1func mismatch() -> i32 {2    val x: i32 = true  // Error: expected i32, found bool3    return x4}

Error message:

Argument Type Mismatch

1func takes_i32(x: i32) -> i32 {2    return x3}4 5func wrong_arg() -> i32 {6    return takes_i32(true)  // Error: expected i32, found bool7}

Error message:

Return Type Mismatch

1func returns_wrong() -> i32 {2    return true  // Error: expected i32, found bool3}

Error message:

Best Practices

1. Choose Appropriate Integer Types

1// Good: use smallest type that fits2val age: u8 = 25          // Ages fit in u8 (0-255)3val year: u16 = 2025      // Years fit in u164val file_size: u64 = 1000000000  // Large files need u645 6// Avoid: unnecessarily large types7val counter: i64 = 0      // Wasteful if i32 suffices

2. Use f64 for Most Floating-Point Math

1// Good: f64 for precision2val pi: f64 = 3.1415926535897933 4// Only use f32 when:5// - Memory is constrained6// - Precision is not critical7// - Interfacing with f32 APIs

3. Be Explicit About Types

Even with future type inference, explicit types improve readability:

1// Clear intent2func calculate_area(radius: f64) -> f64 {3    val pi: f64 = 3.141594    return pi * radius * radius5}

4. Use Booleans for Flags

1// Good: boolean for true/false2val is_valid: bool = true3 4// Avoid: integer for boolean logic5val is_valid: i32 = 1  // Less clear

Type Conversion

Explicit type conversions are supported via the as operator. There are no implicit type conversions in Neuro.

1func convert_types() -> i64 {2    val x: i32 = 423    val y: i64 = x as i64      // Explicit conversion (widening)4    val f: f64 = y as f64      // Int to float5    6    val pi: f64 = 3.147    val trunc: i32 = pi as i32 // Float to int (truncates)8    9    val flag: bool = true10    val num: i32 = flag as i32 // Boolean to int (1)11    12    return y13}

The compiler will reject invalid casts (e.g. casting a string to an integer).

Examples

Working with Multiple Types

1func compute(a: i32, b: f64) -> f64 {2    // Mix i32 and f64 by casting one3    // return a + b  // ERROR: Type mismatch4 5    // Explicit conversion6    return (a as f64) + b7 8    9}

Type-Safe Function Composition

1func double(x: i32) -> i32 {2    x * 23}4 5func add_ten(x: i32) -> i32 {6    x + 107}8 9func compose() -> i32 {10    val x: i32 = 511    val y: i32 = double(x)      // 1012    val z: i32 = add_ten(y)     // 2013    z14}

Type Aliases

A type declaration introduces a transparent alias for an existing type. The alias and its target are fully interchangeable, no new nominal type is created, so a value of the alias type and a value of the target type are the same type to the compiler (contrast with newtype, which is a distinct type).

1type Meters = f642type Id = i643 4struct Sensor {5    location: Meters        // same as `location: f64`6}7 8func to_id(raw: i32) -> Id {9    raw as Id               // same as `raw as i64`10}11 12func main() -> i32 {13    val s = Sensor { location: 10.0 }14    val tag: Id = to_id(7)15    return tag as i32       // 716}

Aliases resolve in every type-annotation position: variable and const annotations, function parameters and return types, struct fields, and as cast targets. Alias chains collapse to their ultimate target:

1type A = B2type B = i323val x: A = 1                // x : i32

Rules and diagnostics:

• A duplicate alias name is a compile error.
• An alias may not shadow a built-in type name (i32, f64, string, …).
• A cyclic alias chain (type A = B; type B = A) is a compile error.
• An unknown target type is reported where the alias is used, against the resolved name.

Aliases are resolved at parse time, so they carry zero runtime cost and produce exactly the same code as writing the target type directly. Using an alias as a value-position constructor or path name (e.g. MyAlias { ... }) is not part of this feature.

Arrays

A fixed-size array [T; N] holds exactly N values of element type T, with N fixed at compile time and part of the type, [i32; 3] and [i32; 4] are distinct types. N is an integer literal, or, inside a generic definition, a const generic parameter ([T; CAP]), resolved to a concrete length by monomorphization.

1val a: [i32; 4] = [10, 20, 30, 40]   // explicit type2val b = [1, 2, 3]                    // inferred [i32; 3]3 4val first = a[0]                     // index read5mut c = [0, 0, 0]6c[1] = 42                            // element assignment (mut binding)7val n = a.len()                      // 4, as u64 (compile-time constant)8 9for x in a {  }                      // iterate by value10for x in &a {  }                     // iterate over a borrow

• Element type: currently restricted to Copy scalar primitives (the integer types, f16/bf16/f32/f64, bool, char). An array of Copy elements is itself Copy. Arrays of non-Copy elements (strings, structs) are not yet supported.
• Literals must be homogeneous; the length is the element count and, when a [T; N] annotation is present, must equal N.
• Bounds: an out-of-range index panics with a located diagnostic in debug builds (-O0); release builds omit the check (matching the integer-overflow policy).
• Iteration: for x in arr / for x in &arr bind each element in order, and for (i, x) in arr.enumerate() binds its u64 position alongside it (see Control Flow).

Borrowed Slices (&[T] / &mut [T])

&[T] is a non-owning (ptr, len) view over a contiguous run of T — the array-and-Vec analogue of &string. A function that only reads or writes elements takes one, and stops caring whether they came from a [T; N], a Vec<T>, or the interior of either.

1func sum(xs: &[i32]) -> i32 {2    mut total = 03    for x in xs { total = total + x }4    total5}6 7func double_each(xs: &mut [i32]) {8    mut i: u64 = 09    while i < xs.len() {10        xs[i] = xs[i] * 211        i = i + 112    }13}14 15val fixed: [i32; 4] = [1, 2, 3, 4]16mut grown: Vec<i32> = Vec::new()17 18val a = sum(&fixed)                  // whole array19val b = sum(fixed.slice(1..3))       // sub-range, zero copy20val c = sum(&grown)                  // Vec, same signature

• [T] alone is unsized and never appears outside a reference; annotating a parameter [T] is a compile error. The owned forms are [T; N] and Vec<T>.
• Unsizing: &[T; N], &Vec<T>, and &[T] all satisfy a &[T] parameter, and the &mut forms a &mut [T] one. Mutability must match exactly — there is no &T → &mut T strengthening, and no &mut T → &T weakening.
• .slice(range) on an array, a Vec<T>, or another slice yields a &[T] view over the named sub-range, copying nothing. It accepts a..b and a..=b. An out-of-range or reversed range panics in every build, debug and release alike: the call hands back a view that outlives the check, so there is no later point at which the mistake could still be caught.
• .len() is O(1), read from the length word of the view — the borrowed run's length, not the container's.
• Indexing is bounds-checked exactly as on the owning container: debug builds panic on an out-of-range index, release builds omit the check. xs[i] = v requires a &mut [T]; the write reaches the buffer, so the owner sees it.
• Iteration: for x in xs binds each element by value, and .enumerate() works on a slice like it does on an array.
• Borrow rules are the ordinary ones. A live view counts as a shared borrow of the place it came from, so a &mut of that place while the view is alive is rejected, and returning a view of a function-local buffer is rejected as a dangling reference.

Tuples

A tuple (T1, T2, ...) is an anonymous, fixed-size, heterogeneous aggregate. Element types may differ; the arity is part of the type, so (i32, bool) and (i32, i32) are distinct.

1val pair: (i32, i32) = (12, 30)     // explicit type2val mixed = (5, true, 'a')          // inferred (i32, bool, char)3 4val a = pair.0                      // index access by constant position5val b = pair.16 7val (x, y) = pair                   // destructuring bind8val (_, keep, _) = mixed            // `_` discards an element9val ((p, q), r) = ((1, 2), 3)       // nested destructuring

• Element type: currently restricted to Copy types, so a tuple is itself Copy. Tuples holding a string or another non-Copy value are not yet supported (the same restriction as array elements).
• Grouping vs. tuple: a single parenthesized expression (x) is grouping, not a one-element tuple. A tuple literal needs at least two elements.
• Index access: t.0, t.1, … read by a constant index; an out-of-range index is a compile error. (Because t.0.1 lexes as the float 0.1, write a nested access as (t.0).1.)
• Destructuring: val (a, b) = t binds each position; _ is a wildcard, and patterns nest. It is a binding form, not a new value, it desugars to ordinary bindings.
• Function boundaries: tuples may be passed as parameters and returned, e.g. func min_max(a: i32, b: i32) -> (i32, i32).

Struct and array destructuring patterns are also supported: val Point { x, y } = p binds each named field, and val [first, second, ..rest] = arr binds array elements positionally with an optional trailing ..rest (a fresh [T; N - k] remainder) or bare .. to ignore it. A rest-less array pattern must match the array's length exactly. See Variables → Destructuring.

Tensor Types

Tensor<T, [d0, d1, ...]> is a statically shaped tensor: the element type and every extent are known at compile time and are part of the type.

1type Weights = Tensor<f32, [784, 128]>2 3struct Layer {4    bias: Tensor<f32, [128]>5}6 7func forward(w: Weights, x: Tensor<f32, [128]>) -> Tensor<f32, [128]> {8    return x9}10 11func loss(l: Tensor<f32, []>) { }        // rank-0 scalar tensor12func image(px: Tensor<u8, [3, 224, 224]>) { }

The shape is written as a bracketed list of non-negative integer literals. An empty list [] is the rank-0 scalar tensor. The element must be a fixed-width scalar: any integer type, f16 / bf16 / f32 / f64, or bool.

Rank and every extent are part of the type, so Tensor<f32, [2, 2]> and Tensor<f32, [3, 3]> are different types and a mismatch is a compile error naming both:

1func takes_square(t: Tensor<f32, [3, 3]>) { }2 3func pass_through(t: Tensor<f32, [2, 2]>) {4    takes_square(t)                       // error: expected Tensor<f32, [3, 3]>,5}                                         //        found Tensor<f32, [2, 2]>

A tensor owns its buffer, so it is not Copy. Passing one to a function moves it; pass &Tensor<T, S> or &mut Tensor<T, S> to share it.

1func consume(t: Tensor<f32, [2, 2]>) { }2 3func twice(t: Tensor<f32, [2, 2]>) {4    consume(t)5    consume(t)                            // error: use of moved value 't'6}

.clone() is the explicit way to get a second owner. It takes no arguments, yields a tensor of the same type, and leaves the receiver usable — including when it is called through a borrow, where the result is an owned tensor rather than the borrow.

1func consume(t: Tensor<f32, [2, 2]>) { }2 3func read(t: &Tensor<f32, [2, 2]>) -> i32 { return 2 }4 5func twice(t: Tensor<f32, [2, 2]>) {6    consume(t.clone())7    consume(t)                            // fine: the clone was consumed, not `t`8}9 10func borrowed(t: &Tensor<f32, [2, 2]>) {11    consume(t.clone())                    // an owned copy of someone else's tensor12    read(t)                               // the borrow was never consumed13}

Device transfer

.to(device) consumes the tensor and returns one whose buffer lives on the requested device. Its argument is the prelude enum Device:

1enum Device {2    CPU,3    GPU(i32)                              // GPU index4}

1func main() -> i32 {2    val a = Tensor::<f32, [2, 2]>::identity()3    val here = a.to(Device::CPU)4    return 0                              // `a` is moved: using it here is an error5}

To keep the source, clone first: t.clone().to(Device::CPU).

A borrow cannot be consumed, so .to is not offered on &Tensor<T, S> — calling it there reports that the borrowed type has no such method.

The host is the only device this compiler can lower to today; the GPU backend is later work. .to(Device::CPU) is therefore the move itself and copies nothing, and a transfer to any other device aborts at run time with a diagnostic rather than quietly leaving the buffer on the host.

Tensor is a prelude name rather than a keyword, so a module declaring its own Tensor shadows it; a shape argument is what marks a type application as a tensor, and writing one under any other name is a parse error.

Building a tensor

A nested array literal becomes a tensor wherever an explicit Tensor<...> annotation is in scope. The annotation supplies the element type and every extent, and it types the literal's leaves — 1.0 under a Tensor<f32, ...> annotation is an f32 literal, not an f64 one being narrowed, exactly as val x: f32 = 0.01 types its literal.

1val v: Tensor<f32, [3]> = [1.0, 2.0, 3.0]2 3val m: Tensor<f32, [2, 3]> = [4    [1.0, 2.0, 3.0],5    [4.0, 5.0, 6.0]6]7 8val arr = [1.0, 2.0, 3.0]          // no annotation: a plain [f64; 3], not a tensor

A nested literal must be rectangular: every sub-array at a given depth has the length the corresponding extent declares, and the nesting is as deep as the shape is long. A ragged literal, a wrong extent, and a literal shallower than the shape are all compile errors. A value that already has a type is not converted for the annotation's benefit — a non-literal element must already be the element type.

Where no annotation reaches, name the type with a turbofish and use a constructor:

1val zeros = Tensor::<f32, [3, 3]>::zeros()2val ones  = Tensor::<f32, [3, 3]>::ones()3val eye   = Tensor::<f32, [4, 4]>::identity()4val w     = Tensor::<f32, [128, 64]>::random_normal(mean: 0.0f32, std: 0.02f32)5val v     = Tensor::<f32, [3]>::from([1.0, 2.0, 3.0])6val loss: Tensor<f32, []> = Tensor::scalar(0.5)

identity() applies only to a square rank-2 shape, random_normal draws only into f32 or f64, scalar builds only the rank-0 tensor, and from takes the same nested literal the annotated form coerces. A rank-0 tensor has no array-literal form at all — it is written with Tensor::scalar(value). The generator behind random_normal is seeded from a fixed constant, so a compiled program draws the same values on every run.

A tensor owns its buffer, and that buffer lives out of line: the value is a pointer to a flat, row-major run of its elements, allocated when the tensor is constructed and released when its binding leaves scope. The buffer keeps one address for its whole life, and a tensor of any size compiles at every optimization level. .clone() allocates a second buffer and copies into it, so the copy is independent of the original. The buffer is host memory; device placement and DLPack handles are later work.

A tensor moves like any other non-Copy value, and the move hands the buffer on rather than copying it — binding it, passing it to a function, returning it, storing it in a struct field, and .to(device) all transfer ownership, and only the last owner releases it. A tensor held in a struct field is not released when the struct goes out of scope; that gap is shared with the standard collections.

What tensors cannot do yet

A tensor can be built, bound, moved, cloned, passed, returned, transferred with .to(device), and stored in a struct — but not yet read back. Indexing and slicing (t[i, j], t[1..3, ..]), tensor arithmetic (a + b, a @ b), in-place compound assignment, .t(), .reshape(...), and the reductions (.sum(), .mean(), .max(), .min()) are all later work. Symbolic extents (Tensor<f32, [M, K]>), named dimensions, and dynamic axes (Tensor<f32, [?, 768]>) are not accepted; a non-literal extent is a parse error.

Standard Collections

Beyond the fixed-size [T; N], the standard library provides three heap-backed collections. They are library types, not language primitives, but because the language exposes no allocator, the compiler knows all three by name and lowers their operations directly.

1mut counts: Vec<i32> = Vec::new()               // growable contiguous array2mut stock: HashMap<string, i32> = HashMap::new() // average-O(1) lookup3mut ranks: BTreeMap<i32, i32> = BTreeMap::new()  // key-ordered map

Vec::new() and its siblings carry no value to infer an element type from, so the binding must be annotated.

Ownership

All three own a heap buffer, so none is Copy: assignment and by-value passing move them, and the buffer is freed when the owner leaves scope. A method that mutates (push, pop, insert, remove, clear) needs a mut binding, exactly like a &mut self method.

1mut a: Vec<i32> = Vec::new()2val b: Vec<i32> = a       // moves; `a` is invalid from here

Vec<T>

Unlike [T; N], whose length is a compile-time constant, a Vec's length is only known at run time, so its bounds check is never elided in release builds.

HashMap<K, V> and BTreeMap<K, V>

Both share one surface:

HashMap is open-addressed with linear probing and average-O(1) lookup. BTreeMap keeps its entries ordered by key, so keys() comes back ascending: that ordering is the reason to choose it.

Element and key types

• Elements and values must be Copy (any integer, float, bool, char, Copy struct, enum, tuple, or array) or string.
• Keys additionally need equality and, per map, a hash or a total order. The compiler supplies both for integer, bool, char, and string keys. A struct key supplies them itself: impl PartialEq plus impl Hashable (HashMap) or impl Comparable (BTreeMap).
• Float keys are rejected. IEEE-754 comparison is a partial order, NaN compares false against everything, including itself, so a map keyed on a raw float could hold a key it can never find again. Use the prelude's validating wrappers, which reject NaN at construction:

1mut scores: BTreeMap<OrderedF32, i32> = BTreeMap::new()2scores.insert(OrderedF32::new(0.75f32), 3)

OrderedF32 / OrderedF64 implement Comparable, not Hashable: hashing a float has no representation-independent answer, so they are ordered-map keys.

Hashable

Hashable is a compiler-known lang-item trait, like Drop and the operator traits, write the impl, never a trait declaration:

1impl Hashable for Point {2    func hash(&self) -> u64 {3        (self.x * 31 + self.y) as u644    }5}

The shape is fixed: exactly one hash(&self) -> u64. Equal keys must hash equally; the map only needs that much.

Current limits

• pop() and get() build an Option<T>, so they are available only for element types Option can carry, scalar Copy primitives in this phase. Index a Vec of structs or strings with v[i] instead.
• A string stored in a collection is not freed when the collection is dropped; only the collection's own buffer is. This matches the existing string-concat limitation and resolves with the heap-string work.
• Vec<T> does not go through the IntoIterator / Iterator protocol (control flow): for x in v lowers to a counted loop, exactly as for x in arr does — and so does for (i, x) in v.enumerate(), which binds the counter that loop already keeps. The protocol is what a user-defined type implements to stand in a for head; the built-in sequences take the direct path instead.

References

• Variables - Variable declaration and usage
• Functions - Function types and signatures
• Operators - Type requirements for operators
• Expressions - Expression type checking

See Also

• Rust Book: Data Types
• Type System Design