Structs and Methods

Structs are user-defined types that group related fields together. Methods add behaviour to structs via impl blocks.

Struct Definition

1struct Point {2    x: f64,3    y: f644}5 6struct Rectangle {7    width: i32,8    height: i329}

Fields are declared as name: Type and separated by commas. Trailing commas are allowed.

Field visibility

A field is private to the module (the file) that declares its struct unless it carries export. In a single-file program every field is reachable throughout it, so this only begins to matter once a second file reads your code:

1export struct Config {2    export host: string,3    export port: i32,4    timeout: i32          // private, internal implementation detail5}

export is per field, so an exported struct can still hold something back. Another module cannot read c.timeout, assign to it, list it in a literal, or reach it through ..base which is what makes a constructor like Config::new the only way in. See Modules → Visibility.

Struct Instantiation

Use StructName { field: value, ... } to create a value:

1val origin = Point { x: 0.0, y: 0.0 }2val rect = Rectangle { width: 10, height: 5 }

All fields must be provided. Field order in the literal does not need to match the definition order.

Field-Init Shorthand

When a local variable has the same name as the field it initialises, write the name once:

1val x = 1.02val y = 2.03val p = Point { x, y }   // equivalent to Point { x: x, y: y }

Shorthand and explicit field: value entries may be mixed: Point { x, y: 2.0 }. A shorthand field references the same-named binding in scope; if no such binding exists, it is an ordinary undefined-name error.

Functional Update (..base)

A trailing ..base supplies every field not listed explicitly from an existing value of the same struct type. Listed fields override the base:

1val p = Point { x: 1.0, y: 2.0 }2val shifted = Point { x: 10.0, ..p }   // x = 10.0, y inherited from p (2.0)3val copy = Point { ..p }               // all fields copied from p

The base must be the same struct type as the literal (otherwise a type Mismatch error). When a base is present, omitting fields is not a MissingStructField error, the base fills them in. The base is evaluated and its fields are copied into the new value; no allocation is introduced.

Field Access

Use dot notation to read a field:

1val p = Point { x: 3.0, y: 4.0 }2val px = p.x   // 3.03val py = p.y   // 4.0

Field Mutation

Fields on a mut binding can be reassigned:

1mut cursor = Point { x: 0.0, y: 0.0 }2cursor.x = 5.03cursor.y = 3.0

Mutating a field of a val binding is a compile error:

1val fixed = Point { x: 1.0, y: 2.0 }2// fixed.x = 3.0  // Error: AssignToImmutableField

Passing Structs to Functions

Structs can be passed as function parameters:

1func area(r: Rectangle) -> i32 {2    return r.width * r.height3}4 5func main() -> i32 {6    val rect = Rectangle { width: 6, height: 7 }7    return area(rect)  // 428}

A function of any kind may return a struct — free functions, associated functions, and methods alike. The by-value struct ABI covers all three, which is what makes both a plain factory function and the Type::new(...) constructor pattern work.

impl Blocks

Use impl TypeName { ... } to add methods and associated functions to a struct.

Instance Methods (&self)

Instance methods take &self as their first parameter and can read any field:

1struct Counter {2    value: i323}4 5impl Counter {6    func get(&self) -> i32 {7        self.value8    }9 10    func add(&self, n: i32) -> i32 {11        self.value + n12    }13}14 15func main() -> i32 {16    val c = Counter { value: 10 }17    return c.add(32)  // 4218}

• self inside the method refers to the receiver struct value.
• All struct fields are accessible via self.field.
• The receiver is passed by value (read-only snapshot).

Mutating Methods (&mut self)

A method may take &mut self to mutate the receiver in place. Writes to self.field propagate back to the caller's value because the receiver is passed by pointer:

1struct Accumulator {2    total: i323}4 5impl Accumulator {6    func add(&mut self, n: i32) {7        self.total = self.total + n8    }9 10    func get(&self) -> i32 {11        self.total12    }13}14 15func main() -> i32 {16    mut acc = Accumulator { total: 0 }17    acc.add(10)18    acc.add(32)19    return acc.get()  // 4220}

• Calling a &mut self method requires a mut receiver (or one reached through a &mut T). Calling it on a val binding is a cannot mutably borrow error.
• The call takes an exclusive borrow of the receiver for its duration, so it is rejected while another borrow of that receiver is live (aliasing rule).

Associated Functions (no self)

Associated functions belong to the type but do not take a receiver. They are called via TypeName::func(args):

1struct Point {2    x: i32,3    y: i324}5 6impl Point {7    func new(x: i32, y: i32) -> Point {8        Point { x: x, y: y }9    }10}11 12func main() -> i32 {13    val p = Point::new(10, 32)14    return p.x + p.y  // 4215}

Combining Methods and Associated Functions

1struct Rect {2    width: i32,3    height: i324}5 6impl Rect {7    func new(w: i32, h: i32) -> Rect {8        Rect { width: w, height: h }9    }10 11    func area(&self) -> i32 {12        self.width * self.height13    }14}15 16func main() -> i32 {17    val r = Rect::new(6, 7)18    return r.area()  // 4219}

Destructors (impl Drop)

A struct can define a destructor by implementing the built-in Drop trait. Its drop(&mut self) method runs automatically when an owner of the value goes out of scope:

1struct Guard {2    sink: &mut i323}4 5impl Drop for Guard {6    func drop(&mut self) {7        *self.sink = *self.sink + 1   // record that the destructor ran8    }9}10 11func main() -> i32 {12    mut dropped: i32 = 013    {14        val g = Guard { sink: &mut dropped }15    }                 // `g` goes out of scope here → `drop` runs, dropped == 116    return dropped    // 117}

Rules:

• Destructors run only on normal scope exit: fall-through, return, break, and continue. A panic aborts the process without running any destructor (there is no stack unwinding).
• When several owned values leave the same scope, they are dropped in reverse declaration order (LIFO).
• A value that has been moved out (rebound, returned, passed by value, or stored into a struct) is dropped exactly once, by its final owner, never twice. Reading a moved value is already a compile error.
• A Copy type may not implement Drop (a type with a destructor is moved, not duplicated). @derive(Copy) together with impl Drop is a compile error.
• The drop method must be exactly drop(&mut self): no extra parameters and no return type, and an impl Drop block may contain no other methods.

Not yet supported: reassigning a Drop binding does not run the prior value's destructor, and a struct's Drop-typed fields are not dropped automatically (no recursive destructor glue).

Derived Traits (@derive)

A struct opts into a small set of compiler-generated traits with @derive(...). The derivable-and-implemented set is Copy, Clone, Debug, PartialEq; any other name in the list is a compile error rather than a silent no-op.

1@derive(Debug, PartialEq)2struct Sensor { id: i32, label: string }3 4@derive(Debug, PartialEq)5struct Reading { sensor: Sensor, value: f64 }6 7func main() -> i32 {8    val a = Reading { sensor: Sensor { id: 7, label: "intake" }, value: 21.5 }9    val b = Reading { sensor: Sensor { id: 7, label: "intake" }, value: 21.5 }10    println("{a:?}")            // Reading { sensor: Sensor { id: 7, label: "intake" }, value: 21.5 }11    if a == b { return 1 }      // structural equality, recursing into `Sensor`12    return 013}

Both derives recurse, and both are generated inline over the fields rather than through a method. That has two consequences worth knowing:

• Every field must itself be renderable / comparable — a scalar, string, char, bool, or another struct carrying the same derive. Anything else is a DeriveFieldUnsupported error naming the field.
• Deriving PartialEq and also writing impl PartialEq for the same struct is a DeriveConflictsWithImpl error. Pick one: the derive for structural equality, the impl when the comparison is not field-wise (or when the struct is a HashMap / BTreeMap key, which calls the trait method and so needs the impl).

{value:?} is the only hole a struct renders in — a struct has no display form, so "{p}" is an error even with @derive(Debug). See examples/structs/derives.nr.

Definition Order Independence

Structs and impl blocks can appear in any order. Forward references are supported:

1impl Score {2    func doubled(&self) -> i32 {3        self.value * 24    }5}6 7struct Score {8    value: i329}10 11func main() -> i32 {12    val s = Score { value: 21 }13    return s.doubled()  // 4214}

Generic Structs and Impls

A struct may declare type parameters in <...> after its name; each distinct set of concrete type arguments is monomorphized into its own specialized struct at zero runtime cost. Type arguments are inferred from the field values at a struct literal, or written explicitly in a type annotation (Pair<i32, f64>).

1struct Pair<T, U> {2    first: T,3    second: U4}5 6// A generic inherent impl: `impl<T> Wrapper<T>` specializes its methods per instance.7struct Wrapper<T> {8    value: T9}10 11impl<T> Wrapper<T> {12    func get(&self) -> T {13        self.value14    }15}16 17func first_of(p: &Pair<i32, i32>) -> i32 {18    p.first19}20 21func main() -> i32 {22    val p = Pair { first: 40, second: 2 }   // Pair<i32, i32> inferred23    val w = Wrapper { value: 30 }           // Wrapper<i32>24    val flag = Wrapper { value: true }      // Wrapper<bool>, distinct instance25    return first_of(&p) + w.get()           // 40 + 30 = 7026}

Restrictions (this phase). Type arguments are restricted to Copy types (a bare type parameter has no move semantics yet). A generic struct is usable only with type arguments; its bare name is rejected. A generic instantiated with an enclosing type parameter (a Wrapper<T> field inside another generic struct) is a documented limitation, deferred with broader generic support.

Const (value) parameters

A generic struct may also declare a const parameter, a compile-time value used as an array length, so [T; CAP] is sized concretely per instance:

1struct Buffer<T, const CAP: u32> {2    data: [T; CAP],3    count: u324}5 6// CAP is inferred from the field array's length (Buffer<i32, 4>):7val buf = Buffer { data: [1, 2, 3, 4], count: 4 }8 9// or written explicitly in a type annotation:10val other: Buffer<i32, 4> = Buffer { data: [5, 6, 7, 8], count: 4 }

Each distinct CAP produces its own monomorphized struct at zero runtime cost. A generic impl over a struct's const parameter is a documented limitation deferred to broader generic support.

Traits

A trait defines shared behaviour that many types can implement. Traits are Neuro's mechanism for bounded polymorphism. A trait method is either required (a signature with no body, implementors must provide one) or a default method (a signature with a body that implementors inherit unless they override it).

1trait Shape {2    // Required: every implementor must define this.3    func area(&self) -> i324 5    // Default (provided): inherited unless the implementor writes its own.6    func is_big(&self) -> i32 {7        if self.area() > 20 { 1 } else { 0 }8    }9}

Implement a trait for a type with impl Trait for Type:

1struct Square { side: i32 }2 3impl Shape for Square {4    func area(&self) -> i32 { self.side * self.side }5    // `is_big` is not written, so Square inherits the trait's default.6}

The compiler checks each trait impl for conformance: every required method must be present, each method's signature must match the trait's, and an impl may only contain methods the trait declares.

Trait bounds on generics

A generic parameter may be bounded by a trait (<T: Shape>). Inside the body, the trait's methods may be called on the bounded parameter; at the call site the concrete type argument must implement the trait:

1func scaled_area<T: Shape>(s: &T, factor: i32) -> i32 {2    s.area() * factor          // dispatched through the `Shape` bound3}

A trait-bounded generic is fully monomorphized and erased: each impl lowers to ordinary methods and each bound is specialized per concrete type, so there is no vtable and no runtime cost. Supertraits (Comparable requires PartialEq), dynamic dispatch (dyn Trait, which does use a vtable), and the operator traits have all landed.

Associated types

A trait may declare an associated type: a member type each implementor chooses. The trait writes the name alone; the impl binds it, and either side names it as Self::Name:

1trait Channel {2    type Sample3 4    func sample(&self) -> Self::Sample5}6 7struct Tally { counted: i32 }8 9impl Channel for Tally {10    type Sample = i3211 12    func sample(&self) -> Self::Sample { self.counted }13}

Self::Sample resolves to whatever the impl bound, in a signature, in a method body, and nested inside another type (Option<Self::Sample>). An impl may spell the position either way — -> i32 above means the same thing. Conformance requires every declared associated type to be bound, and rejects a binding the trait never declared.

Constraining an associated type in a bound

A bare T: Channel bound erases the implementor, and with it the only thing that says what Sample is — so a generic body cannot call a method whose signature names it. The Trait<Assoc = T> form puts the answer in the bound:

1func scaled<T: Channel<Sample = i32>>(source: &T, factor: i32) -> i32 {2    source.sample() * factor       // typed as i32 by the bound3}

The constraint is written wherever a bound is:

1func clause<T>(source: &T) -> i32 where T: Channel<Sample = i32> { source.sample() }2 3func anonymous(source: &impl Channel<Sample = i32>) -> i32 { source.sample() }4 5func make(seed: i32) -> impl Channel<Sample = i32> { Tally { counted: seed } }

At the call site the concrete type argument's own binding must match the one the bound demands: passing a Channel implementor whose type Sample = f64 to a Sample = i32 bound is an error naming both types. A bound may only constrain an associated type the trait declares, and a bare bound still cannot type a call to a method that names one.

A trait declaring an associated type remains not object-safe, so it has no dyn form: a trait object erases the implementor, which is exactly what the binding would have to come from.

Unsupported (Phase 1+)

The following are not yet implemented and will be rejected at compile time:

• self (consuming) on a non-Copy struct (needs the by-value struct ABI). On a Copy struct an owned self is accepted, because copying by value is ABI-identical to &self (this is what lets an operator-trait method func add(self, ...) work)
• Nested structs as field types

1// Consuming `self` on a non-`Copy` struct is rejected with a clear error:2struct Wrapper { value: i32 }       // no @derive(Copy)3impl Wrapper {4    func unwrap(self) -> i32 { ... }   // Error: UnsupportedSelfParam5}

Nominal Typing

Neuro uses nominal typing for structs: two struct types are compatible only if they have the same name, regardless of field layout.

Error Types

References

• Types, type system overview
• Variables, val and mut bindings
• Functions, function definitions