Functions

Functions are the primary unit of code organization in Neuro.

Function Declaration

Basic Syntax

1func function_name(param1: Type1, param2: Type2) -> ReturnType {2    // function body3    return value4}

Components:

• func keyword
• Function name (identifier)
• Parameter list (optional)
• Return type annotation (required unless void)
• Function body (block of statements)

Simple Function

1func greet() -> i32 {2    return 03}

Function with Parameters

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

Function without Return Value

1func do_something() {2    // Implicit void return3    val x: i32 = 104}

Parameters

Parameter Syntax

Each parameter requires:

1. Parameter name
2. Type annotation

1func process(input: i32, flag: bool) -> i32 {2    if flag {3        return input * 24    } else {5        return input6    }7}

Multiple Parameters

1func complex(a: i32, b: i32, c: i32, d: i32) -> i32 {2    return a + b + c + d3}

Parameter Passing

A parameter of scalar type is passed by value (copied). Reference parameters (&T / &mut T) pass a borrow instead, see Borrows; a non-Copy value passed by value is moved rather than copied.

1func modify(x: i32) -> i32 {2    mut temp: i32 = x3    temp = temp + 104    return temp  // Returns modified value, original unchanged5}6 7func test() -> i32 {8    val original: i32 = 59    val result: i32 = modify(original)10    // original is still 511    // result is 1512    return result13}

Named Arguments

An argument may be passed by name at the call site. Named arguments may appear in any order, and any number of positional arguments may come first.

1func connect(host: string, port: i32, timeout: i32) -> i32 {2    return port + timeout3}4 5val a = connect("localhost", 8080, 30)               // all positional6val b = connect("localhost", port: 8080, timeout: 30)7val c = connect("localhost", timeout: 30, port: 8080) // same call as b

External labels

A parameter may be declared with two names — an external label the caller writes and an internal name the body uses — written external internal: T. The external label is then required at every call site.

1func clamp(_ value: f32, min lo: f32, max hi: f32) -> f32 {2    if value < lo { return lo }3    if value > hi { return hi }4    return value          // the body says lo / hi, never min / max5}6 7val x = clamp(1.5, min: 0.0, max: 1.0)8// val y = clamp(1.5, 0.0, 1.0)   // error: min and max must be named

An external label of _ suppresses the call-site name: the argument is positional and naming it is an error.

1func scale(_ value: f32, _ factor: f32) -> f32 {2    return value * factor3}4 5val r = scale(2.0, 3.0)      // no names accepted6// val s = scale(value: 2.0, factor: 3.0)   // error: both are positional-only

Rules

• Positional arguments must precede named arguments.
• Named arguments may appear in any order relative to each other.
• A plain name: T parameter may be passed positionally or as name: value.
• An external internal: T parameter must always be named external:.
• A _ name: T parameter must always be positional.
• Two parameters of one function may not answer to the same call-site name.
• Free functions, associated functions (Type::f(...)), and methods (x.m(...)) all accept named arguments. Closures, the panic builtins, enum variants, and newtype constructors declare no parameter names, so a label on one is an error.

Arguments are bound to parameters before type checking, and are evaluated in the order they are written, exactly as a positional call evaluates them left to right. Naming them therefore changes which parameter each value reaches, never when it is computed:

1func bump(r: &mut i32) -> i32 { *r = *r + 12    return 0 }3func combine(first: i32, second: i32) -> i32 { first * 10 + second }4 5func main() -> i32 {6    mut x = 07    // `bump` is written first, so it runs first and `x` is read as 1: the call is8    // `combine(first: 1, second: 0)` and `n` is 10.9    val n = combine(second: bump(&mut x), first: x)10    return n - 1011}

A call that only passes values costs nothing at runtime — it produces exactly the IR the equivalent positional call produces. A call that reorders arguments carrying effects binds each of them to a temporary first, which is one binding per argument and no other cost.

Limitation

A method call is matched on the method name alone, because the receiver's type is not yet known when arguments are bound. If two different types declare a method of the same name with different parameter names, a named argument on that method is rejected; write the call positionally, or rename one of the methods. Positional calls are never affected.

Return Values

Explicit Return

Use the return keyword to exit a function with a value:

1func explicit_return() -> i32 {2    return 423}

Multiple Return Points

1func conditional_return(x: i32) -> i32 {2    if x > 0 {3        return 14    } else if x < 0 {5        return -16    } else {7        return 08    }9}

Expression-Based Returns (Implicit Return)

The last expression in a function body automatically becomes the return value (Neuro has no semicolons; statements are newline-terminated):

1func implicit_return() -> i32 {2    42  // No 'return' keyword needed3}4 5func add(a: i32, b: i32) -> i32 {6    a + b  // Implicit return7}

Mixing explicit and implicit returns:

1func mixed(x: i32) -> i32 {2    if x > 10 {3        return 100  // Explicit return for early exit4    }5    x * 2  // Implicit return for normal case6}

Key points:

• The last expression in the body is the return value
• Must match function return type
• Can mix with explicit return statements
• There are no semicolons; a stray ; is a parse error

Void Return

Functions without a return value:

1func no_return() {2    val x: i32 = 103    // Implicit void return at end4}5 6func explicit_void() {7    val x: i32 = 108    return  // Explicit void return9}

Function Calls

Basic Call

1func add(a: i32, b: i32) -> i32 {2    return a + b3}4 5func main() -> i32 {6    val result: i32 = add(5, 3)7    return result8}

Nested Calls

1func double(x: i32) -> i32 {2    x * 23}4 5func add(a: i32, b: i32) -> i32 {6    a + b7}8 9func main() -> i32 {10    val result: i32 = add(double(5), double(3))11    // double(5) = 10, double(3) = 612    // add(10, 6) = 1613    return result14}

Call Expressions

Function calls can appear anywhere an expression is expected:

1func compute() -> i32 {2    val x: i32 = add(1, 2) + add(3, 4)  // 3 + 7 = 103    return x4}

Recursion

Basic Recursion

1func factorial(n: i32) -> i32 {2    if n <= 1 {3        14    } else {5        n * factorial(n - 1)6    }7}8 9func main() -> i32 {10    factorial(5)  // Returns 12011}

Tail Recursion

While Neuro doesn't yet optimize tail calls, you can write tail-recursive functions:

1func factorial_tail(n: i32, acc: i32) -> i32 {2    if n <= 1 {3        acc4    } else {5        factorial_tail(n - 1, n * acc)6    }7}8 9func factorial(n: i32) -> i32 {10    factorial_tail(n, 1)11}

Mutual Recursion

1func is_even(n: i32) -> bool {2    if n == 0 {3        true4    } else {5        is_odd(n - 1)6    }7}8 9func is_odd(n: i32) -> bool {10    if n == 0 {11        false12    } else {13        is_even(n - 1)14    }15}

The main Function

Every Neuro program requires a main function as the entry point:

1func main() -> i32 {2    // Program entry point3    return 0  // Exit code4}

Requirements:

• Must be named main
• Must return i32 (exit code)
• Must not have parameters (Phase 1)

Exit codes:

• 0 = success
• Non-zero = error (convention)

Function Scope

Local Variables

Variables declared in a function are local to that function:

1func scoped() -> i32 {2    val x: i32 = 10  // Local to scoped()3    return x4}5 6func other() -> i32 {7    // val y: i32 = x  // Error: x not in scope8    return 09}

Parameter Scope

Parameters are local variables initialized with argument values:

1func params(a: i32, b: i32) -> i32 {2    // a and b are local variables3    val sum: i32 = a + b4    return sum5}

Shadowing

Inner scopes can shadow outer scope variables:

1func shadowing() -> i32 {2    val x: i32 = 13    if true {4        val x: i32 = 2  // Shadows outer x5        // Inner x is 26    }7    // Outer x is still 18    return x9}

Type Checking

Argument Type Checking

Function calls are strictly type-checked:

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 paths must match the declared return type:

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

Argument Count Checking

1func two_params(a: i32, b: i32) -> i32 {2    return a + b3}4 5func wrong_count() -> i32 {6    return two_params(1)  // Error: expected 2 args, found 17}

Function Examples

Mathematical Functions

1func abs(x: i32) -> i32 {2    if x < 0 {3        -x4    } else {5        x6    }7}8 9func max(a: i32, b: i32) -> i32 {10    if a > b { a } else { b }11}12 13func min(a: i32, b: i32) -> i32 {14    if a < b { a } else { b }15}16 17func clamp(x: i32, min_val: i32, max_val: i32) -> i32 {18    min(max(x, min_val), max_val)19}

Boolean Logic Functions

1func and(a: bool, b: bool) -> bool {2    a && b3}4 5func or(a: bool, b: bool) -> bool {6    a || b7}8 9func xor(a: bool, b: bool) -> bool {10    (a && !b) || (!a && b)11}12 13func implies(a: bool, b: bool) -> bool {14    !a || b15}

Recursive Functions

1func fibonacci(n: i32) -> i32 {2    if n <= 1 {3        n4    } else {5        fibonacci(n - 1) + fibonacci(n - 2)6    }7}8 9func gcd(a: i32, b: i32) -> i32 {10    if b == 0 {11        a12    } else {13        gcd(b, a % b)14    }15}16 17func power(base: i32, exp: i32) -> i32 {18    if exp == 0 {19        120    } else {21        base * power(base, exp - 1)22    }23}

Best Practices

1. Keep Functions Focused

Each function should do one thing well:

1// Good: focused functions2func is_positive(x: i32) -> bool {3    x > 04}5 6func absolute_value(x: i32) -> i32 {7    if is_positive(x) { x } else { -x }8}

2. Use Descriptive Names

1// Good: clear purpose2func calculate_area(width: i32, height: i32) -> i32 {3    width * height4}5 6// Bad: unclear7func calc(w: i32, h: i32) -> i32 {8    w * h9}

3. Use Expression Returns for Simple Functions

1// Good: concise2func double(x: i32) -> i32 {3    x * 24}5 6// Verbose (but acceptable)7func double_verbose(x: i32) -> i32 {8    return x * 29}

4. Use Explicit Returns for Complex Logic

1// Good: explicit returns for clarity2func complex_logic(x: i32) -> i32 {3    if x > 100 {4        return 1005    }6    if x < 0 {7        return 08    }9    return x10}

5. Minimize Nesting

1// Good: early returns reduce nesting2func process(x: i32) -> i32 {3    if x < 0 {4        return 05    }6    if x > 100 {7        return 1008    }9    return x * 210}11 12// Bad: deeply nested13func process_nested(x: i32) -> i32 {14    if x >= 0 {15        if x <= 100 {16            return x * 217        } else {18            return 10019        }20    } else {21        return 022    }23}

Common Mistakes

Missing Return

1func missing_return(x: i32) -> i32 {2    if x > 0 {3        return x4    }5    // Error: missing return for x <= 0 case6}7 8// Fix: add else branch9func fixed(x: i32) -> i32 {10    if x > 0 {11        return x12    } else {13        return 014    }15}

Unreachable Code

1func unreachable() -> i32 {2    return 423    val x: i32 = 10  // Warning: unreachable4}

Stray Semicolon

1func wrong() -> i32 {2    val x: i32 = 423    x;  // Error: `;` is not a valid token (Neuro has no semicolons)4}5 6// Fix: remove the semicolon7func right() -> i32 {8    val x: i32 = 429    x  // Implicit return10}

Not Yet Implemented

Default Parameters

1// Not yet implemented2func greet(name: string, greeting: string = "Hello") -> string {3    greeting + ", " + name4}

Variadic Functions

1// Not yet implemented2func sum(values: ...i32) -> i32 {3    // Sum all arguments4}

Spread / Variadic Call Sites

1// Not yet implemented (Phase 7)2val args = [1, 2, 3]3sum(...args)

Panic Builtins

Three compiler-known builtins terminate the program when an unrecoverable condition is reached. They follow the abort, no unwinding model: each prints a diagnostic (message at file:line:col) to standard error and calls abort(). The stack is not unwound, so future Drop / defer cleanup runs only on normal scope exit, never during a panic.

1func divide(a: i32, b: i32) -> i32 {2    if b == 0 {3        panic("division by zero")4    }5    a / b6}7 8func main() -> i32 {9    assert(divide(10, 2) == 5)   // passes silently10    val x = divide(1, 0)         // prints "panic: division by zero at main.nr:3:9" and aborts11    return 012}

Because these builtins diverge (they never return), a call may appear anywhere a value is expected, including the implicit-return (tail) position of a non-void function:

1func parse_digit(c: i32) -> i32 {2    if c >= 48 && c <= 57 { c - 48 } else { panic("not a digit") }3}

A user-defined function whose name is panic, assert, or unreachable shadows the builtin within the program.

return, break, and continue diverge the same way, so an if or match arm that uses one takes its type from its siblings rather than imposing one on them, see expressions.md.

Standard Output Builtins

Two more compiler-known builtins write text to standard output. Unlike the panic family they return: the result is void, so a call is a statement and not a value.

The newline is one \n byte. Standard output is the platform's text stream, so on Windows it reaches the console or pipe as \r\n, exactly as it would from a C program.

1func main() -> i32 {2    val name: string = "Neuro"3    val ratio: f64 = 0.8754 5    print("hello from ")6    println(name)7    println("phase 2 is {ratio:.2} done")8    return 09}

Each takes exactly one argument, and that argument is text: an owned string or an immutable &string sub-slice (text.slice(1..4)). There is no variadic form and no format string at the call site, because there is no need for one — string interpolation has already rendered every hole, with its full format mini-language, into one ordinary string before the call is reached:

1println("{label:>10}: {count} of {total}")

The text is read, not consumed, so the value stays usable afterwards:

1val text: string = "kept"2println(text)3println(text)     // still valid — printing does not move its argument

A user-defined function named print or println shadows the builtin within the program, exactly as one named panic does. Both are compiler builtins rather than declarations, so @no_prelude does not take them away.

Output is buffered. A call copies its bytes into a page-sized buffer, and the buffer reaches the operating system when it fills — so a printing loop pays one write for thousands of lines rather than one, or for println two, per call.

That buffer is emptied on every path out of the program, so buffering never costs output: when main returns, when the panic runtime aborts, and when a debug-build arithmetic overflow traps. A line printed before a panic therefore still appears, and it appears before the panic's diagnostic on standard error rather than after it.

When standard output is a terminal, the buffer is emptied at the end of every println instead of only when it fills, so a program's progress is visible while it runs. A pipe or a file gets the full buffer. This is the behaviour of C's standard library, and of every language's standard output built on it. print writes no line terminator and so ends no line: its bytes wait for the next println or for the program to finish.

Generic Functions

A function may declare type parameters in angle brackets after its name. Each type parameter stands for a type supplied at the call site; the compiler generates one specialized copy of the function per distinct set of concrete type arguments (monomorphization), so a type parameter carries zero runtime cost.

1// A single template, instantiated at each concrete type it is called with.2func identity<T>(x: T) -> T {3    x4}5 6// Multiple type parameters.7func second<T, U>(a: T, b: U) -> U {8    b9}10 11func main() -> i32 {12    val a = identity(41)     // identity<i32>13    val f = identity(2.5)    // identity<f64>, a separate specialized copy14    val s = second(1.5, 7)   // second<f64, i32> -> 715    return a + s             // 41 + 7 = 4816}

Type-argument inference. Type arguments are inferred from the call's value arguments where possible. A type parameter that appears only in return position cannot be inferred and must be supplied explicitly with a turbofish (identity::<i32>(x)).

What a generic body may do. On an unbounded type parameter the body may use only operations valid for any type: binding a value, returning it, passing it to another function, and building or observing tuples. Operations that need a known concrete type (arithmetic, comparison, field access, method calls) are rejected on a bare type parameter:

1func bad<T>(a: T, b: T) -> T {2    a + b   // error: `+` is not defined on the unbounded type parameter T3}

Bounds. A trait bound (func f<T: Shape>(x: &T)) is enforced: the bound's methods become callable on the type parameter inside the body, and a type argument that does not implement the trait is rejected at the call site.

1func scaled_area<T: Shape>(s: &T, factor: i32) -> i32 {2    s.area() * factor       // dispatched through the `Shape` bound3}4 5// error: type argument `NoImpl` for 'T' does not implement required trait 'Shape'

Restrictions (this phase). Type arguments are restricted to Copy types. Generic structs and impl blocks are supported too (see Structs).

Const (value) parameters

A generic parameter list may also declare a const parameter, a compile-time value (of an integer type), written const NAME: T. A const parameter is usable as an array length and as a value in the body, and each distinct value is monomorphized into its own specialized code (zero runtime cost). Const parameters are inferred from array-argument lengths:

1func sum<const N: u32>(a: [i32; N]) -> i32 {2    mut total: i32 = 03    for x in a {4        total = total + x5    }6    total          // N is inferred from the array's length7}8 9val xs: [i32; 3] = [10, 20, 12]10val s = sum(xs)    // sum<3>  ->  42

where clauses

For a readable signature, constraints may move into a where clause after the return type. A where clause carries trait bounds (parsed, still unenforced) and value predicates over const parameters, a boolean expression checked at every instantiation and reported at the offending call:

1func head<const N: u32>(a: [i32; N]) -> i32 where N > 0 {2    a[0]           // guaranteed non-empty by `where N > 0`3}

Turbofish, explicit generic arguments

When inference cannot reach a parameter (or you want to be explicit), supply the arguments at the call with a turbofish ::<...>. This is the only call-site form for explicit generic arguments; arguments may be types or const values:

1val a = identity::<i32>(5)   // explicit type argument2val b = zeros::<4>()         // explicit const argument

Static and Dynamic Dispatch

A trait bound can be satisfied two ways, and the keyword chooses which.

impl Trait, static dispatch

impl Trait is anonymous-generic sugar. Each concrete type flowing through it produces a specialized copy of the function, exactly as a named type parameter does, so it carries zero runtime cost and no pointer indirection.

1// These two signatures compile to the same code:2func train(model: &impl Model) -> i32 { model.step() }3func train<T: Model>(model: &T) -> i32 { model.step() }

Each impl Trait parameter is its own anonymous parameter, so one call may bind two different concrete types, unlike a single shared <T>:

1func total(a: &impl Shape, b: &impl Shape) -> i32 { a.area() + b.area() }2total(&square, &rect)   // valid: two different types

In return position, impl Trait names the one concrete type the body produces. It resolves transparently to that type, and the compiler verifies the type implements the trait:

1func make() -> impl Shape { Square { side: 3 } }

The body's result must be a direct constructor (a struct literal or enum value) for the concrete type to be inferable; richer forms arrive with closures and iterators.

dyn Trait, dynamic dispatch

dyn Trait is a single runtime type that can hold any implementor. Method calls go through a vtable: the reference carries a pointer to the value plus a pointer to that concrete type's method table, and the call jumps through a fixed slot.

A trait object is unsized, so it only appears behind a reference, &dyn Trait or &mut dyn Trait. A bare dyn Trait is a compile error.

1// One function body serves every implementor.2func measure(s: &dyn Shape) -> i32 { s.area() }3 4measure(&square)   // &Square coerces to &dyn Shape5measure(&rect)     // &Rect   coerces to &dyn Shape

Use dyn when values of different concrete types must be handled behind one interface; use impl Trait (or a named bound) when each call site has one concrete type.

Object safety

A trait is usable as dyn only if it is object-safe: every method must dispatch on a &self or &mut self receiver, so the vtable has a fixed layout. A method that consumes self by value, or one with no receiver at all, makes the trait unusable as a trait object (it remains fully usable through impl Trait and named bounds).

1trait Consume { func take(self) -> i32 }   // not object-safe: consumes self2trait Maker   { func build() -> i32 }      // not object-safe: no receiver

A &mut self method requires a &mut dyn Trait receiver; mutations through it are visible to the caller.

Closures and Lambdas

A closure is an anonymous callable written with pipe-delimited parameters, |params| body. It can capture variables from the enclosing scope.

1// Single-expression body (no braces): the return type is inferred.2val square = |x: i32| x * x3val nine   = square(3)              // 94 5// Block body: an explicit return type is required.6val clamp = |x: i32| -> i32 {7    if x < 0 { 0 } else { x }8}9 10// Zero parameters.11val make = || 4212 13// `move` forces every capture to be taken by value (required when the closure14// would outlive the captured bindings).15val label = 10016val tagged = move |x: i32| x + label

Capture

A closure captures each free variable its body reads by value; the variable must be Copy this phase, and it remains usable after the closure is created because it was copied, not moved:

1func main() -> i32 {2    val offset = 103    val shift  = |n: i32| n + offset   // captures `offset` by value4    val a = shift(5)                   // 155    a + offset                         // `offset` still usable -> 256}

Capturing a non-Copy value (such as a string), or assigning to a captured variable inside the closure, is a compile error in this phase.

Function types and higher-order functions

A closure or function value has the type (T1, ...) -> R. A function that takes one as a parameter and calls it is a higher-order function:

1func apply(v: i32, f: (i32) -> i32) -> i32 {2    f(v)3}4 5func main() -> i32 {6    val bump = 37    apply(5, |x: i32| x + bump)        // 88}

Each closure compiles to a { function pointer, environment pointer } value with no heap allocation; a call dispatches indirectly through it.

Not yet supported

• Parameter-type inference (|x| x * x without an annotation).
• Passing a closure to a generic higher-order function (func f<T, U>(x: T, g: (T) -> U) -> U).
• The Fn / FnMut / FnOnce distinction with by-reference, mutable, or move-of-owned capture (all capture is currently by-value Copy).
• Returning or storing a closure so it escapes its defining scope, and dyn Fn.

References

• Types - Function types and type checking
• Variables - Local variables in functions
• Control Flow - If/else and function control flow
• Expressions - Expression-based returns

See Also

• Rust Book: Functions
• Recursion