Preface

Within the narrative and theoretical scope of the book, this appendix serves primarily to demonstrate how a memory-safe, C-successor language ought to define its semantic boundaries, rather than to provide a drop-in replacement for a rigorous ISO-level standard.

In this context, CobaltC can best be described as a systems language designed to address the safety problems of C while adopting a more robust structural model.

If nothing else, it illustrates the exact pain points and formal guarantees required to make a safe systems programming language actually function.

As argued throughout The Wrong Memory essays, attempting to tack a "safe subset" onto an inherently unsafe language usually fails because the core language semantics still allow invariant violations. By embedding ownership and borrowing into the core type system, CobaltC makes safety an intrinsic property of the language rather than an optional discipline imposed upon it.

CobaltC unashamedly draws on the ownership and memory-safety techniques demonstrated by Rust. Although Rust isn't the origin of most of these ideas, its significant contribution was demonstrating how they could be combined into a practical, high-performance systems language. CobaltC adopts that safety architecture without attempting to reproduce Rust's syntax or overall language philosophy. Instead, it applies the broader body of ideas to the problem identified in Appendix II: making semantic invariants such as ownership, lifetime, aliasing, mutability, and bounds properties that the compiler can represent and enforce, rather than obligations the programmer must maintain by convention.

The CobaltC Proposition

The distinction is perhaps easiest to see in a deliberately small example. Allocate some storage, keep a second name for it, destroy the storage, and use the second name.

#include <stdlib.h>

int main(void)
{
    int* data = malloc(3 * sizeof *data);
    data[0] = 7;

    int* alias = data;    /* a second name for the same storage */
    free(data);           /* the storage is gone... */

    return alias[0];      /* ...but this still compiles, and reads
                             the wrong memory */
}

C accepts this program without complaint — GCC and Clang compile it silently even with every common warning enabled. At best, a modern compiler may warn about a case this obvious; move the free behind one function call and the warning disappears, while the bug does not. The program compiles, runs, and reads the wrong memory. The fact that alias still refers to freed storage exists only in the programmer's head.

import std;

fn main()
{
    Vec<i32> data = Vec::new();
    Vec::push(&mut data, 7);

    ref<i32, shared> alias = &data[0];   // a second name for the same storage
    drop(data);                          // ✗ rejected before the program runs:
                                         //   diag.destroy-while-aliased
    printf("%v\n", *alias);
}

The same program, the same shape — allocate, alias, destroy, use — and it does not run. The fact that alias still points into data lives in the language, so destroying data underneath it is refused before the program starts, with a named diagnostic: heuristic warnings on one side, a semantic guarantee on the other.

The guarantee is not bought by removing capability. Below, two exclusive (mutable) references into the same array are held at once — something safety-minded languages commonly refuse — legal here because the compiler has proven they touch disjoint elements. CobaltC forbids the crime, not the capability.

import std;
fn main()
{
    array<i32, 2> values = [0, 0];

    // Two mutable (exclusive) references into the same array, allowed
    // because their targets are statically proven to be disjoint
    // (pointing both at values[0] is rejected before the program runs:
    // diag.aliasing-conflict).
    ref<i32, exclusive> a = &mut values[0];
    ref<i32, exclusive> b = &mut values[1];

    *a = 7;
    *b = 8;
}

CobaltC retains the same fine-grained control, while allowing the compiler to establish the relevant safety properties: a and b refer to distinct elements of values, their mutable accesses are disjoint, and the underlying storage remains owned by values.

Introduction

Why CobaltC exists, what it promises, and which features were chosen to keep those promises.

import std;

fn main()
{
    printf("hello, world\n");
}

hello, world

What CobaltC is

CobaltC is a small systems programming language with a C-family surface syntax. It is designed around one idea: the facts that correct low-level code depends on should live in the language, not in the programmer's memory. When you write C, you have to remember that a pointer is still valid, that an integer cannot overflow here, that a buffer has been initialised, that nobody else is writing to that struct right now, and that this handle is closed exactly once. CobaltC's goal is that every such fact is either represented and checked by the language, or explicitly marked as trusted by you.

CobaltC is not a safe language obtained by removing low-level capability. You still get deterministic control over resources, raw storage, foreign functions, threads, and predictable data layout. What changes is that each of those capabilities comes with a precise account of what is checked, when it is checked, and what you are asserting when the language cannot check it.

The two implementations: coby and cobc

CobaltC ships with two implementations, both written in Rust, and they share one front end — the same parser, name resolution and static checks — so they accept and reject exactly the same programs, with the same diagnostics.

coby is the reference interpreter. It runs a program straight from its source on the abstract machine the specification defines, performing every check the specification requires on every operation. It is the specification's meaning made executable: when this guide says a program prints something or stops with a diagnostic, that is what coby does. There is no build step, so it is the quickest way to run a program or try an idea.

cobc is the native compiler. After the shared front end has checked the program, it translates it to plain C and compiles that with the system's C compiler (GCC or Clang) against cbrt, its run-time library. A compiled program keeps every run-time check the specification requires except those the compiler proves can never fail — the rest becomes ordinary C — so it runs many times faster than the interpreter while behaving identically. cobc --keep-c leaves the generated C beside the executable if you want to read what your program became; Reading the C that cobc generates, below, says what is in it and what you can do with it.

The two are kept honest against each other: the test suites require cobc's executables to match coby's output and diagnostics byte for byte on every program, under both GCC and Clang — including every complete example in this guide. Use coby to run a program at once; use cobc to build an executable, or to see how fast the program can be.

On Linux the two work side by side, and everything in this guide runs under either. On Windows, coby runs programs today, and the formatter cobfmt (below) runs there too; cobc does not yet follow them there.

The objectives

The language design was derived from a short list of objectives, in priority order. Where two objectives conflict, the earlier one wins.

1. Preserve semantic invariants. Arithmetic stays in range, references point at live objects, a resource has exactly one owner, an object is initialised before it is read, two threads never race on one location, and external data is treated as a claim until validated.
2. Safety of valid safe programs. A well-formed program that writes no unsafe block of its own cannot violate any of those invariants on any conforming implementation. The standard library's own bodies do use unsafe (a Vec writes its elements through a raw pointer); those blocks are the implementation's to keep true, each listed in the specification with the fact that justifies it, so they cost the program nothing (§20, Who asserts what). If the language cannot establish a fact, the operation is one of: statically rejected, dynamically checked, explicitly fallible (returns a Result or Option), explicitly trusted (inside unsafe), or simply not provided.
3. Consistency and composability. A handful of mechanisms that combine cleanly, instead of many overlapping features. Every value-placing construct (declarations, arguments, fields, returns) follows one rule; every access (through a name, a field, an index, a reference) follows one rule.
4. Formal precision and deterministic diagnostics. The specification is written as rules, so two implementations must reject exactly the same programs and report the same named diagnostic. Every error you see has a stable identifier such as diag.aliasing-conflict.
5. A small language. Every feature starts as absent and must earn its place. The result is a language you can hold in your head: no traits, no inheritance, no exceptions, no implicit conversions, no operator overloading, no macros.
6. Low-level capability. Raw pointers, manual allocation, FFI, threads, and defined representation are all available, gated by unsafe where the language cannot check them.

Which features were chosen, and why

Each mechanism in CobaltC exists because a specific invariant needed a home. The table below is the map from objective to feature; the rest of this guide explains each feature in turn.

What CobaltC deliberately leaves out

These are considered decisions, not gaps. Each one either duplicated an existing mechanism or would have hidden a semantic fact the language wants to keep visible.

• Implicit conversions and subtyping. i32 and i64 never mix silently.
• User-defined traits or bounds. A type parameter's operations come from five built-in bounds — eq, ordered, number, integer, clone (§12) — and nothing else: there is no way to declare a new bound. Your own struct or enum satisfies clone alone, by its fields or its own T::clone; to compare or combine values of your own types in generic code, pass the operation in as a function value.
• Exceptions. A fault terminates the program after running destructors; expected failure is a Result.
• Garbage collection. Ownership and scope-end destruction are deterministic; Rc<T> is a library type.
• Character literals, and indexing or slicing a str. A str is a whole value; its bytes are reached with str_byte, and a single byte is written b'a': a u8, or the wider unsigned type its context asks for (§06). A String is sliced into views, &s[i..j], and taken apart by String::split, find and chars (§21). Text that arrives from outside is still bytes until String::from_utf8 validates it.
• Method-call syntax. A call names the function's owner and writes the borrow it takes: Vec::push(&mut v, x), never v.push(x). The mode of every access path is visible where the path is formed, and . means one thing, field access. This is final (CHG-0132): no receiver sugar, no uniform call syntax, no auto-borrowing dot, no chaining.
• A mut qualifier on bindings, switch and goto, import … as renaming, partial initialisation, lifetime annotations, atomics.

How to read this guide

The next section is a complete program you can read top to bottom to absorb the syntax. After that there is one section per chapter of the normative specification, numbered the same way (§06 to §22) so you can cross-reference. If you are new, a good order is: the tour, then §22 (syntax reference), then §06 onward. Each section ends with a short list of rules of thumb.

Every code block that is a complete program has been run through both implementations, the reference interpreter coby and the native compiler cobc, which agree on every one. A green runs badge means it executes to completion; a red badge names the diagnostic the language reports for that program. Diagnostics are labelled static (the program is rejected before it runs) or dynamic (a checked fault at run time); where a check is static only when the operands are literal, both labels may appear in the text. Comments inside examples use ✓ for accepted lines and ✗ for rejected ones.

The language and its standard library are still moving: an edition may change what an earlier one accepted, and the specification's register says so in each such edition's row. When a part is offered as stable it is first a candidate for thirty days, then stable, and after that a program written against it keeps compiling and keeps doing what it did, apart from a repair that closes a soundness hole or a change announced a release ahead (spec/STABILITY.md).

Running a program

Save a program as a .cb file. coby program.cb interprets it; cobc --run program.cb compiles it to native code and runs it, and cobc -o program program.cb keeps the executable. Both take the program's entry file (it may name other files as modules, §17), both exit with status 0 when the program runs to completion, and both print a rejected program's diagnostic the same way and exit with status 1. coby --check program.cb (or cobc --check) runs only the checks made before a program starts, and prints the same diagnostic for a program they reject; nothing runs, so a program that reads input, writes files or serves the network can be checked without doing so. Given a directory, it checks every .cb file in it.

There is no project file and no build step besides these commands. A program that spans several files names them itself: module parser "./parser.cb"; loads a file as a module, its path relative to the file that says so (§17), and extern "./fast.c"; or extern "z"; links C code of the program's own or an installed library (§20). cobc main.cb then builds the whole program from that one file, and coby main.cb runs it, with nothing else to keep in step (D-0231).

Testing a program

Tests live beside the code they test, in unittest blocks: a block at the top level of a file or a module, with an optional name. A test sees the module's private items, and is checked every time the program is, so a test that no longer compiles stops the build at once. Nothing runs it until you ask for a test run.

import std;

fn parse_port(StringView s) : Option<u16>
{
    match (StringView::parse<u32>(s))
    {
        Ok(n)  : if (n > 65535) { None } else { Some(narrow<u16>(n)) },
        Err(_) : None,
    }
}

unittest "parse_port: bounds"
{
    assert(parse_port(StringView::of("0")) == Some(0));
    assert(parse_port(StringView::of("65535")) == Some(65535));
    assert(parse_port(StringView::of("65536")) == None);
}

unittest
{
    assert(parse_port(StringView::of("x")) == None);
}

fn main()
{
    printf("%v\n", parse_port(StringView::of("8080")) == Some(8080));
}

true

coby port.cb runs the program as always. coby --unittest port.cb runs its tests instead of main, each in a thread of its own: a failed assert, or any other fault, is reported, and the next test still runs. cobc --unittest --run port.cb does the same with the compiled program, and reports it identically; cobc --unittest -o port_tests port.cb keeps the test program.

test port.cb:12 parse_port: bounds ... ok
test port.cb:19 ... ok
2 tests: 2 passed, 0 failed

The exit status is 1 when a test failed, so a test run can gate a build. --unittest-filter TEXT runs only the tests whose name contains TEXT. A file that holds only a library and its tests needs no main. A /// comment on a test right after a function makes it that function's example in the generated documentation (D-0230).

All code in this guide uses Allman brace style (every opening brace on its own line) and four-space indentation. That is a documentation convention: CobaltC ignores whitespace between tokens, so any brace placement is equally valid.

cobfmt, the formatter, writes that style for you: cobfmt program.cb rewrites the file in place, cobfmt --backup src/ does every .cb file under src/ and keeps each changed file's previous contents as NAME.cb.format.bak, and cobfmt --check src/ only lists the files it would change (for a test or a commit hook). It changes layout and nothing else: indentation, braces, spacing, blank lines, the : of a match's arms and of a bitstruct's fields aligned in one column, and trailing comments kept in theirs. Before writing, it checks that the result is the same program token for token, so formatting can never change what a program does. It keeps your line breaks — a short if (n == 0) { return; } stays on one line, though a function's body always opens on its own line — and a line longer than 120 characters that holds a list of arguments, parameters or array elements is broken one item per line. --width N sets another width, and --no-wrap leaves every line as long as it is. cobfmt --help lists the rest. Like coby, cobfmt runs on Windows as well as Linux, and it keeps a file's Windows line endings (\r\n) as they are.

Reading the C that cobc generates

cobc does not produce machine code itself. Once the shared front end has checked your program, cobc translates it into one C file and hands that file to GCC or Clang, which builds the executable against libcbrt.a, the run-time library. Normally the C file is deleted afterwards; cobc --keep-c -o prog prog.cb keeps it as prog.c, beside prog (without -o, a.out gets a.c). Under --run without -o it lives in a temporary directory and is deleted with it. If the C compiler ever rejects the file, cobc keeps it whatever you asked and prints its path.

The file is the complete translation of your program, not an excerpt: nothing but libcbrt.a is needed to build it. Even a seven-line program comes to a few hundred lines, because the file carries everything it uses, in this order:

• The run-time interface, cbrt.h, copied in at the top: the C declarations of every cb_… function the program calls.
• /* ---- types ---- */: each struct, enum and generic instantiation as a C struct, each followed by a _Static_assert that its size and alignment are the ones the specification fixes. Vec<i32> becomes struct s_std__Vec_Li32_R.
• /* ---- string literals ---- */: your text literals as byte arrays.
• /* ---- functions ---- */: one C function for each function the program actually uses, std's included, and one copy per instantiation of a generic one (f_std__Vec__push_Li32_R is Vec::push for i32). Your main is f_main; every other function is static, so the C compiler may inline it where it is called.
• Call thunks and type descriptors: what fn values and the run-time checks need to know about each type.
• int main, last: it hands the program's arguments to the runtime and starts f_main.

Inside a function, the C follows your statements one by one, and every run-time check the specification requires is an explicit line, so you can see exactly which checks your code still pays for. This is printf("%v\n", v[0]); with v a Vec<i32> (without the #line directives described below):

cb_at(0u, 7u);                                   // now at line 7 of file 0, for diagnostics
struct s_std__Vec_Li32_R *v9 = &(l_v_1);
if (t8 >= v9->len) cb_fault("diag.index-out-of-bounds", CB_NOLOC, 0);
int32_t *e10 = v9->ptr + (int64_t)t8;            // the element's address
int32_t t11 = (*e10);

Elsewhere you will meet cb_borrow, cb_read and cb_write (the access and aliasing checks of §08–§09), __builtin_add_overflow and its relatives (checked arithmetic, §06), and cb_frame_push, cb_stmt_push and their _pop partners (the bookkeeping that runs destructors at scope end). A check the compiler has proved can never fail is simply absent.

Each line of C made from one of your statements is preceded by a directive such as #line 7 "prog.cb", which tells the C compiler which line of your file the next line of C came from. The C compiler's own messages, a debugger and a sanitizer then name prog.cb:7 rather than a line of prog.c; code made for std keeps the C file's own numbering. cobc --no-line-directives leaves the directives out, for reading the C on its own terms.

What you can do with it

• Read it to see how a construct is compiled, which checks a loop costs, or why one way of writing it is faster than another. Performance (chapter P) collects what such reading and measuring found.
• Build it yourself, with your own flags. cobc's own build of prog.c is the command below, and cobc -v prints the exact one it runs, with the real path of libcbrt.a (and any extern C file's compilation), ready to paste and change; -O2 is the default level and libcbrt.a sits beside the cobc executable. Add -g -O0 for a build to step through in a debugger, -fsanitize=address,undefined to have the sanitizers watch it, -march=native or -flto, or leave out -w to see the C compiler's warnings, which cobc silences.
• Debug it. cobc -O0 -g prog.cb compiles with debug information and keeps it in the executable; gdb prog then stops at and steps through the lines of prog.cb, and a sanitizer build (--cc naming a wrapper that adds -fsanitize=address) reports a memory error in unsafe code at its .cb line. perf annotate shows the C beside them.
• Report a compiler bug. If GCC or Clang rejects the generated C, that kept file and the C compiler's message are the whole report.

gcc -std=gnu11 -O2 -ffp-contract=off -fno-optimize-sibling-calls -w prog.c \
    -L /path/to/cobc/dir -lcbrt -lpthread -ldl -lm \
    -Wl,--gc-sections -Wl,--strip-debug -o prog

Keep -std=gnu11 and the two -f flags when you change the rest; each is part of the program's meaning. -ffp-contract=off stops the C compiler fusing a * b + c into one fused multiply-add with a single rounding, since the specification rounds each operation on its own (§06). -fno-optimize-sibling-calls keeps every call a real call, so a recursion too deep for the stack stops with the same diagnostic it gets from coby, instead of being turned into a loop that runs to completion. A program that links its own C code (extern "./mine.c";, §20) also needs that code compiled and added before -lcbrt; cobc -v shows both commands. The last two options only make the executable smaller: they leave out the parts of the runtime the program does not use, and the runtime's debug information (a hello world is about 0.8 MB with them, 5.9 MB without); drop them if you link a -g build to debug. cobc -s also leaves out the symbol table (--strip-all in place of --strip-debug, about 0.6 MB), which only profilers and debuggers read.

Why compile to C

Compiling through C is a long tradition rather than a shortcut: C++ began as Cfront, which translated it into C, and Nim, Vala, Cython and several Scheme compilers work this way today. Few compilers write machine code entirely on their own; most hand the last step to a shared back end such as LLVM or GCC's. C as the target brings:

• Portability for free. Wherever there is a C compiler, the language can run.
• Decades of optimisation for free. GCC's and Clang's -O2 do register allocation, inlining, vectorisation and instruction scheduling better than a young compiler could.
• Readable output. You can see what your program became, which is what --keep-c is for; LLVM IR or assembly would be far harder to read.
• Easy C interoperation. Calling C functions and linking C libraries is natural, which is what unsafe extern fn (§20) needs.

What it costs

• C's own rules come along. The generated C must avoid C's undefined behaviour, and it has to keep up as C compilers grow stricter: code an older compiler accepted with a warning, a newer one may reject outright.
• Less control. Some things C cannot say directly (exact stack layout, particular calling conventions, precise debug information), so they are worked around with flags such as -ffp-contract=off above.
• Slower builds. Every build includes a full C compilation.
• Debuggers show C lines, not CobaltC lines. cobc emits no #line directives, so gdb steps through the C; the cb_at(file, line) calls lead back to your source.

For CobaltC the trade is a good one. Its central promise is that coby and cobc behave identically, and letting GCC and Clang do the machine-code work leaves cobc free to get the semantics and the checks exactly right.

A tour in one program

A complete, runnable program that introduces the syntax and the main capabilities, and the mistakes the compiler stops, before the reference sections begin.

Here is a complete program. Read it once for the shape of the syntax; every construct it uses has its own section later. It runs under both the interpreter and the compiler and prints the output shown below the code.

// ------------------------------------------------------------------
// A first CobaltC program: a temperature log.
//
// One page that touches most of what CobaltC is for: structs, an enum
// with payloads and `match`, a resource with a destructor, Vec, String
// and HashMap, references the compiler checks, slices, Option, Result
// and `?`, checked arithmetic, generics, a closure, and two threads
// sharing a counter through a mutex.
// ------------------------------------------------------------------

import std;

// A module. Its `export` items are reached as `limits::COLD`; the rest
// stay inside. A `const` is a value fixed when the program is compiled.
module limits
{
    export const i32 COLD = 150;                          // tenths of a degree
    export const i32 HOT = 300;
}

// A plain struct: copied on assignment, comparable with ==.
struct Reading
{
    i32 tenths;                                           // temperature in tenths of a degree
    u8 sensor;
}

// An enum. Variants may carry a payload.
enum Verdict
{
    Cold(i32),
    Fine,
    Hot(i32)
}

// `ref<Reading, shared>` is a read-only reference. `if` is an expression,
// so the function's value is whichever branch runs.
fn judge(ref<Reading, shared> r) : Verdict
{
    if (r.tenths < limits::COLD)
    {
        Cold(limits::COLD - r.tenths)
    }
    else if (r.tenths > limits::HOT)
    {
        Hot(r.tenths - limits::HOT)
    }
    else
    {
        Fine
    }
}

// A resource: something that owns other things. It is moved, never
// copied, and destroyed exactly once, automatically, at scope end.
resource struct Log
{
    Vec<Reading> entries;
    HashMap<String, u32> per_sensor;                      // readings counted by sensor name
}

// The destructor. It is never called directly; the language runs it.
fn Log::drop(ref<Log, exclusive> self)
{
    printf("L%d\n", Vec::len(&self.entries));             // printf's format is checked when compiled
}

fn record(ref<Log, exclusive> log, i32 tenths, u8 sensor)
{
    Vec::push(&mut log.entries, Reading { .tenths = tenths, .sensor = sensor });
    *HashMap::entry(&mut log.per_sensor, sprintf("sensor-%d", sensor), 0) += 1;
}

// A slice is a borrowed run of elements. Arithmetic never wraps
// silently: `checked_add` gives None on overflow, and `?` on an Option
// returns that None from this function at once.
fn average(slice<Reading, shared> rs) : Option<i32>
{
    if (slice_len(rs) == 0)
    {
        return None;
    }
    i32 total = 0;
    foreach (r in rs)
    {
        total = checked_add(total, r.tenths)?;
    }
    Some(total / narrow<i32>(slice_len(rs)))              // `narrow` checks that the value fits
}

// A fallible function returns a Result. Err carries the offending byte.
fn digit(u8 b) : Result<i32, u8>
{
    if (b > b'9' || b < b'0')
    {
        return Err(b);
    }
    Ok(widen<i32>(b - b'0'))                              // widening is always safe, still spelled out
}

// `?` unwraps an Ok, or returns the Err from this function at once.
fn parse_two(u8 hi, u8 lo) : Result<i32, u8>
{
    i32 h = digit(hi)?;
    i32 l = digit(lo)?;
    Ok(h * 10 + l)
}

// A generic function: T is any integer type, fixed at each call.
fn larger<T: integer>(T a, T b) : T
{
    if (a > b) { a } else { b }
}

// Runs on its own thread: counts the hot readings in its half of the
// log into a counter the two threads share. Only the lock reaches it.
fn count_hot(ref<mutex<u32>, shared> hot, slice<Reading, shared> part) : usize
{
    foreach (r in part)
    {
        if (r.tenths > limits::HOT)
        {
            *lock(hot) += 1;
        }
    }
    slice_len(part)
}

fn main()
{
    Log log = Log { .entries = Vec::new(), .per_sensor = HashMap::new() };
    record(&mut log, 120, 1);
    record(&mut log, 215, 1);
    record(&mut log, 340, 2);
    record(&mut log, 310, 2);

    // Loop over the entries through a shared reference to each one.
    // `match` takes the Verdict apart; it must handle every variant.
    foreach (r in &log.entries)                           // r : ref<Reading, shared>
    {
        match (judge(r))
        {
            Cold(by) : printf("C%d ", by),                // "C" then the shortfall
            Fine     : printf("F "),
            Hot(by)  : printf("H%d ", by),                // "H" then the excess
        }
    }
    printf("\n");

    // A lookup gives an Option; a pattern condition takes it apart.
    if (Some(n) = HashMap::get(&log.per_sensor, &String::from_str("sensor-2")))
    {
        printf("sensor-2: %d\n", *n);
    }

    // A slice of the Vec, and an average that cannot overflow unseen.
    if (Some(avg) = average(&log.entries[0 .. 2]))
    {
        printf("avg %d\n", avg);
    }

    // Sorting, and a closure: `to_f` captures nothing, `offset` is read.
    Vec<i32> temps = Vec::new();
    foreach (r in &log.entries)
    {
        Vec::push(&mut temps, r.tenths);
    }
    Vec::sort(&mut temps);
    i32 offset = 32;
    auto to_f = [offset](i32 tenths)
    {
        tenths * 9 / 50 + offset
    };
    printf("coldest %dF, warmest %dF\n", to_f(temps[0]), to_f(temps[3]));

    // Result handling: `b"42"` is a byte-array literal (52 and 50).
    auto digits = b"42";
    if (Ok(v) = parse_two(digits[0], digits[1]))
    {
        printf("%d %d\n", v, larger(v, 17));             // T := i32
    }

    // Two threads share the counter through a mutex; each gets its own
    // half of the log as a slice. `join` waits and gives the result.
    auto hot = Mutex::new(0: u32);
    auto h1 = spawn(count_hot, &hot, &log.entries[0 .. 2]);
    auto h2 = spawn(count_hot, &hot, &log.entries[2 .. 4]);
    usize seen = join(h1) + join(h2);
    printf("%d of %d readings hot\n", *lock(&hot), seen);
}   // `log` is destroyed here: its destructor prints "L4", then its Vec and HashMap are freed.

C30 F H40 H10 
sensor-2: 2
avg 167
coldest 53F, warmest 93F
42 42
2 of 4 readings hot
L4

What the compiler stops

The program above is correct, so it shows what CobaltC lets you write. Just as much of the language is what it will not let through. Each of these mistakes, a one-line change to the same kind of code, is rejected before the program runs, by both the interpreter and the compiler, with a diagnostic that names the rule; what cannot be decided in advance is checked while the program runs, and stops it at the line where it happens (§08–§10).

import std;

struct Reading
{
    i32 tenths;
    u8 sensor;
}

fn main()
{
    Vec<Reading> entries = Vec::new();
    Vec::push(&mut entries, Reading { .tenths = 120, .sensor = 1 });
    ref<Reading, shared> first = Vec::index_shared(&entries, 0);
    Vec::push(&mut entries, Reading { .tenths = 215, .sensor = 1 });   // ✗ the push may move the elements
    printf("%d\n", first.tenths);                                     //   while `first` still points into them
}

import std;

resource struct Log
{
    Vec<i32> entries;
}

fn archive(Log l)                     // takes the log: it is destroyed when this call ends
{
}

fn main()
{
    Log log = Log { .entries = Vec::new() };
    archive(log);                     // `log` moves into the call
    Vec::push(&mut log.entries, 7);   // ✗ `log` no longer owns anything
}

import std;

fn digit(u8 b) : Result<i32, u8>
{
    if (b > b'9' || b < b'0')
    {
        return Err(b);
    }
    Ok(widen<i32>(b - b'0'))
}

fn main()
{
    digit(b'x');                      // ✗ an error dropped on the floor would go unseen
    // Handle it (`?`, `match`, `if (Err(e) = …)`), or say you mean to drop
    // it: `_ = digit(b'x');` discards the value on purpose.
}

import std;

fn main()
{
    i32 tenths = 2000000000;
    i32 twice = tenths * 2;           // ✗ the product does not fit in an i32: no silent wrap
    printf("%d\n", twice);
}

enum Verdict
{
    Cold(i32),
    Fine,
    Hot(i32)
}

fn label(Verdict v) : i32
{
    match (v)                         // ✗ `Hot` is not handled: every variant must be
    {
        Cold(by) : -by,
        Fine     : 0,
    }
}

fn main()
{
    label(Fine);
}

Reading a diagnostic

Both tools report a mistake the same way, character for character. This is what either prints for the first example above, a reference kept across a push:

error[diag.aliasing-conflict]: `first` still borrows `entries`, so it cannot be written or borrowed `mut` here; end that borrow first
  --> tour.cb:14:15
   |
14 |     Vec::push(&mut entries, Reading { .tenths = 215, .sensor = 1 });
   |               ^
   = repair: end the conflicting reference (let its holder go out of scope) before this access, or use `shared` on both sides

• The first line says what went wrong. error means the program was rejected before it ran; a check that fails while the program runs is a fault instead (fault[diag.index-out-of-bounds]: index out of bounds), and the program stops there. In the brackets is the diagnostic's identifier: it is the same in every implementation and every version, and the specification's diagnostic registry has an entry for each.
• --> gives the file, the line and the column, in the form editors and terminals turn into a link.
• The source line, with carets under the token the rule applies to.
• = repair: is the registry's advice for this diagnostic.

coby --explain tour.cb (or cobc --explain) adds the registry's whole entry: the rule of the specification that rejected the program, the invariant it protects, what it required and what it observed, and the examples that show it. A compiled program shows its faults that way when it runs with COBALTC_EXPLAIN=1 in its environment.

What you just saw

• Declarations are type-first, like C: i32 x = 5;, Vec<Reading> entries;. auto infers the type from the initialiser. Function return types follow a colon: fn judge(…) : Verdict.
• Blocks, if and match are expressions. The last expression in a block, with no semicolon, is the block's value. judge returns whatever branch of the if runs.
• Conditions need parentheses (if (c), while (c), match (e)); match arms are Pattern : expression,, and a match must cover every variant (a missing one is rejected, above). A pattern can also be a condition: if (Some(n) = HashMap::get(…)) runs its block only when the lookup found something, with n bound.
• &x is a shared (read-only) reference and &mut x an exclusive one. The compiler checks every use: a reference kept into the Vec across a push, a value used after it moved, are rejected before the program runs (above). &log.entries[0 .. 2] is a slice, a borrowed run of elements.
• Log is a resource: it owns a Vec and a HashMap. Its destructor fn Log::drop runs at the end of main, then its fields are freed. Passing or assigning a resource moves it.
• String, HashMap and sprintf. sprintf("sensor-%d", s) builds a String; *HashMap::entry(&mut m, key, 0) += 1 counts. The standard library lives in the module std, imported by import std;.
• Errors are values. A Result must be used (dropping one is rejected), ? returns an Err or a None early, and checked_add turns an overflow into None. Plain arithmetic that overflows is never silent: it is rejected when the compiler can see it, and stops the program when it happens.
• No implicit conversions. widen<i32>(b - b'0') and narrow<i32>(n) say what happens to the representation; narrow checks that the value fits.
• Library calls are qualified: Vec::push(&mut v, x), Vec::sort(&mut v), HashMap::get(&m, &k). There is no method-call syntax.
• Generics, closures and threads. larger<T: integer> works for any integer type; to_f is a closure whose capture list names what it uses; spawn starts a thread and join waits for its result. The two threads share their counter only through a mutex: lock is the only way in.

Further showcases can be found in the repository's showcase directory; its README describes them all.

Core language and std

Which parts of CobaltC are the language itself, always available, and which come from the standard library and need import std;.

CobaltC comes in two layers. The core language is always there: its types, its constructs, and a set of intrinsics, functions defined by a rule of the specification rather than by a body. The standard library, std, is a module, written mostly in CobaltC itself. Nothing of std is in scope until a module writes import std;, and each module imports it for itself (§17). This page says which layer each part belongs to.

// No `import std;`: only the core language.
fn main() : u8
{
    array<i32, 4> a = [3, 4, 5, 6];
    i32 s = 0;
    foreach (x in a)
    {
        s += x;
    }
    u32 m = max_value<u32>();
    s += narrow<i32>(m % 10);            // 4294967295 % 10 is 5
    narrow<u8>(s)                        // the exit status: 23
}

fn main()
{
    printf("hello\n");                   // ✗ diag.unbound-name (static): printf is std's
}

Core: always available, no import

Types built into the language

• Integers i8–i128, u8–u128, isize, usize; floats f32, f64
• bool, str (string literals), void / ()
• array<T, N>, slice<T, shared> and slice<T, exclusive>
• ref<T, shared> and ref<T, exclusive>, rawptr<T>
• fn(…) : R values and closures
• handle<T> (a thread), mutex<T>, guard<T>

Language constructs

struct, bitstruct, enum (with numeric codes), resource, destructors (Type::drop), generics with the built-in bounds eq, ordered, number, integer and clone, match with nested, literal and text patterns, if and while (either with a pattern as the condition), for, foreach (over collections and ranges), break, continue, ?, const, modules and import, unsafe, unsafe extern fn and extern "code";.

Intrinsics

allocate returns a Result, which a program can use without the import even though it cannot name the Result type without it.

Intrinsics private to std

key_hash, key_eq, key_less, key_less_at, swap_places, append_native, text_write, parse_check, parse_value, str_slice (beneath StringView::of), and the names that begin with $: the machinery std's own code is built on. A program cannot call them, nor std's private externs stderr_write, which eprintf writes through, and stdout_flush, beneath flush_stdout.

std: needs import std;

Mostly written in CobaltC itself; a few parts are provided natively by each implementation. std is divided into submodules by subject, and import std; brings in all of them, so a program never needs to know which holds what; the column says, for a program that wants one subject alone (import std::text;). §21 covers it in full.

What may surprise you

• printf and assert are std, not core: a program without the import cannot print.
• Vec, String and Option are std, but array, str, slice, handle and mutex are core.
• swap, the one to use, is std; swap_places, which it is built on, is private to std.
• min and max are std; min_value and max_value are core.
• sqrt, round and the other floating-point functions are std (std::math), not core: they are ordinary library functions, so they need the import, and a function of your own named round is an ordinary name.

§06Arithmetic and numeric types

Checked integer arithmetic, explicit conversions, how literals get their types, and the sizes and limits of types.

Numbers are where silent corruption usually starts, so CobaltC's arithmetic is checked by default: an operation whose mathematical result does not fit its type does not wrap around, it faults. Every other policy (wrapping, saturating, or returning None) is a named function you call on purpose. Types never convert implicitly; every change of representation is a named intrinsic with a documented behaviour.

Numeric types

There is no implicit promotion: i32 + i64 is a type error, and a u8 cannot be passed where an i32 is expected. Unary minus applies only to signed and float types.

Literals

Integer literals are digit strings: decimal, or hexadecimal, octal or binary after 0x, 0o or 0b (0xFF, 0o755, 0b1010), with no sign. A _ between two digits groups them and is ignored: 1_000_000, 0xFFFF_0000, 3.141_592 (anywhere else, a _ is a syntax error). A literal's type comes from, in order: an explicit suffix 123: u8; the expected type at that position (a declared variable type, a parameter type, a field type, or the other operand of the same operator); otherwise the default, i32 for integers and f64 for floats. An expression made only of literals and operators takes the expected type as a whole, so u64 x = 1024 * 1024 * 1024 * 16; is computed in u64, while auto y = 65536 * 65536; has no expected type, is an i32, and overflows. A literal that does not fit its type is a static error. A minus written directly before an integer literal is checked with it, as one negative value, so -2147483648 is the smallest i32. A type's limits also have names, min_value<i32>() and max_value<i32>() (below). Float literals are digits . digits, with an optional exponent (1.5e-3, 2.5E3, or 1e5 with no fraction), optionally suffixed : f32; one too large for its type (1e400) is a static error, not infinity. A byte character b'a' is one ASCII character or an escape (b'\n', b'\'', b'\x7f'), for writing bytes readably in code that parses. It is a number like any other literal and takes an unsigned type from its context (u32 c = …; c == b'|' compares two u32s), and is a u8 when nothing fixes its type; a signed context is a type error. A string literal "…" is always a str and a byte literal b"…" always an array<u8, N> (§21, §22); neither takes an expected type.

import std;

fn main()
{
    auto a = 5;                       // i32: no suffix, no expected type
    u8 b = 200;                       // u8 from the declared type; 200 fits
    auto c = 7: u64;                  // u64 from the suffix
    auto d = b + 1;                   // the 1 takes u8 from b; d is u8
    auto e = 2.5;                     // f64
    f32 f = 0.5: f32;
    f64 tiny = 1.5e-3;                // an exponent: 0.0015
    u8 comma = b',';                  // a byte character: 44
    u32 mask = 0xFF00;                // hexadecimal; also 0o17 (octal) and 0b1010 (binary)
    u64 ns = 1_000_000_000;           // _ groups digits: one second in nanoseconds
    u64 sixteen_gib = 16 * 1024 * 1024 * 1024;   // literals only: computed in u64
    i64 g = -1;                       // the expected type reaches through unary minus
    i32 lo = -2147483648;             // min(i32): 2147483648 alone would not fit
    assert(d == 201);
    assert(g < 0);
    assert(lo + 2147483647 == -1);
    assert(tiny == 0.0015 && comma == 44 && mask == 65280);
    assert(sixteen_gib == 17_179_869_184 && ns == 1000000000);
    static_assert(sizeof<u64>() == 8);        // sizeof and alignof are intrinsics returning usize
    static_assert(alignof<u16>() == 2);
}

fn main()
{
    256: u8;                          // ✗ diag.literal-out-of-range (static): 256 does not fit u8
}

Checked arithmetic

+, - and * on integers fault with diag.arith-overflow when the result leaves the type's range. / and % truncate toward zero (the remainder takes the sign of the dividend); dividing by zero is diag.div-by-zero, and the one overflowing division, the minimum value of a signed type divided by -1, is diag.div-overflow. Negating the minimum signed value is an overflow too. When both operands are literals the fault is detected statically and the program is rejected; otherwise it is a run-time fault that terminates the program (see §18). A local initialized with a literal counts as that literal until something writes it, borrows it or captures it in a closure, so u8 x = 200; u8 y = x + 100; is rejected too. After such a write, or after an if that writes it on only one branch, the check happens at run time.

fn add(i32 a, i32 b) : i32
{
    a + b                             // checked: faults if the sum leaves i32
}

fn main()
{
    add(2147483647, 1);               // ✗ diag.arith-overflow (dynamic): 2^31 does not fit i32
}

fn main()
{
    2147483647 + 1;                   // ✗ diag.arith-overflow (static): both operands are literals
}

fn div(i32 a, i32 b) : i32
{
    a / b
}

fn main()
{
    div(-2147483647 - 1, -1);         // ✗ diag.div-overflow (dynamic): -MIN does not fit
}

Choosing a different overflow policy

When wrapping or clamping is what you actually want, say so. The wrapping_ and saturating_ families never fault; the checked_ family returns an Option so the caller can decide. These are ordinary generic calls with the operand type inferred from the arguments.

import std;

fn main()
{
    u8 top = 255;
    assert(wrapping_add(top, 1: u8) == 0);          // 255 + 1 wraps to 0
    assert(saturating_add(top, 9: u8) == 255);      // clamps at the maximum
    match (checked_add(top, 1: u8))
    {
        Some(_) :                 // must not happen
        {
            assert(false, "unreachable");
        },
        None    : {},                              // overflow reported as None
    }
    match (checked_add(1: u8, 1: u8))
    {
        Some(v) :
        {
            assert(v == 2);
        },
        None    :
        {
            assert(false, "unreachable");
        },
    }
}

Shifts, bitwise operators and comparison

• << and >> take a u32 shift amount that must be less than the type's bit width; anything else is diag.shift-amount-out-of-range. Left shift discards high bits by definition (it is not an overflow); right shift is arithmetic on signed types.
• &, |, ^ and ~ work on any integer type; ! is boolean not.
• == != < <= > >= compare two operands of the same type and yield bool. Floats follow IEEE rules: every comparison involving NaN is false except !=.

import std;

fn main()
{
    u32 one = 1;
    assert(one << 4 == 16);
    static_assert(-8 >> 1 == -4);                          // arithmetic shift keeps the sign
    static_assert((12 & 10) == 8);
    static_assert((12 | 3) == 15);
    static_assert((6 ^ 3) == 5);
    static_assert(~0 == -1);
    f64 zero = 0.0;
    auto nan = zero / zero;                        // floats do not fault
    assert(!(nan == nan));
    assert(nan != nan);
}

Conversions are explicit

There is exactly one way to change a number's type: call the intrinsic that names the conversion. Each takes the target type as a type argument.

Five intrinsics work on an integer's bits directly: count_ones(x), leading_zeros(x) and trailing_zeros(x) (each a u32; zero gives the type's width), and rotate_left(x, k) and rotate_right(x, k) (by k modulo the width, keeping x's type). They act on the value's cell image, so a negative i8 has eight ones, and none of them faults (D-0123).

import std;

fn main()
{
    u8 small = 200;
    i32 wide = widen<i32>(small);                  // always safe
    assert(wide == 200);
    assert(narrow<u8>(wide) == 200);                // fits, so it succeeds
    static_assert(narrow_wrapping<u8>(300) == 44);  // 300 mod 256
    static_assert(reinterpret<i32>(4294967295: u32) == -1);
    f64 f = to_float<f64>(wide);
    assert(to_int<i32>(f * 1.5) == 300);
    usize n = 12;
    assert(narrow<i32>(n) == 12);                   // usize → i32 is a narrowing, so it is checked
}

Between the two float types: widen<f64>(x) takes an f32 to an f64 exactly, and to_float<f32>(x) takes an f64 to the nearest f32, rounding as float arithmetic does. There is no widen<f32> of an f64, since most f64 values have no exact f32. reinterpret gives a float's IEEE-754 bits as an integer of the same width, and turns such an integer back into a float, with no unsafe.

import std;

fn main()
{
    f32 sample = 0.1;
    f64 d = widen<f64>(sample);                    // exact: 0.100000001490116...
    assert(to_float<f32>(d) == sample);             // and back, rounded, to the same f32
    static_assert(to_float<f32>(1.0 / 3.0) == 0.33333334: f32);
    u64 bits = reinterpret<u64>(-2.0);
    assert(bits >> 63 == 1);                        // the sign bit
    assert(reinterpret<f64>(bits) == -2.0);
    static_assert(reinterpret<u32>(1.0: f32) == 0x3f80_0000: u32);
    static_assert(max_value<f32>() == 3.4028235e38: f32);  // the largest finite f32
}

fn to_byte(i32 x) : u8
{
    narrow<u8>(x)                     // checked at run time
}

fn main()
{
    to_byte(300);                     // ✗ diag.narrowing-overflow (dynamic)
}

widen is only accepted where every value of the source fits the target, so it can never lose one: widen<u64> of an i32 is a static error, because a negative i32 has no u64 value. narrow works between any two integer types, and never faults where the value fits. Use it for usize and isize: whether usize → u64 is a widening depends on the address width, so narrow<u64>(n) is the spelling that is accepted by every implementation.

fn to_u64(i32 x) : u64
{
    widen<u64>(x)                     // ✗ diag.type-mismatch (static): -1 has no u64 value; use narrow
}

fn main()
{
    to_u64(1);
}

Sizes and limits of types

Four intrinsics describe a type rather than a value. Each takes the type as its type argument, written explicitly, and no other arguments.

Every fixed-width type has the same size and limits on every implementation: sizeof<i32>() is 4 and max_value<i32>() is 2147483647. isize and usize have the address width, which each implementation documents, so for them the intrinsics are the portable way to write a size or limit, where a literal is not. A struct's size and alignment follow from its fields (§16): each field is aligned, and the struct's alignment is its largest field's.

import std;

struct Pair
{
    u8 tag;
    u32 value;
}

fn main()
{
    static_assert(sizeof<i32>() == 4);
    static_assert(sizeof<u64>() == 8);
    static_assert(alignof<u64>() == 8);                      // a number is aligned to its own size
    static_assert(sizeof<bool>() == 1);
    static_assert(sizeof<array<u16, 10>>() == 20);           // an array has no padding
    static_assert(alignof<Pair>() == 4);                     // its largest field's alignment
    static_assert(sizeof<Pair>() == 8);                      // tag, 3 bytes of padding, value
    static_assert(sizeof<usize>() == sizeof<isize>());       // the address width, whatever it is

    static_assert(min_value<i8>() == -128);
    static_assert(max_value<u8>() == 255);
    static_assert(max_value<i32>() == 2147483647);
    static_assert(min_value<u64>() == 0);
    static_assert(max_value<usize>() == ~(0: usize));        // every bit set, at any address width
    static_assert(wrapping_add(max_value<i32>(), 1) == min_value<i32>());
}

Limits are most often the starting value of a search, a bound to clamp against, or a value that means "none". Here are all three:

import std;

// The spread of a list: start the minimum at the largest i64 and the
// maximum at the smallest, so the first element replaces both.
fn spread(ref<Vec<i64>, shared> v) : i64
{
    i64 lo = max_value<i64>();
    i64 hi = min_value<i64>();
    foreach (p in v)
    {
        i64 x = *p;
        if (x < lo)
        {
            lo = x;
        }
        if (x > hi)
        {
            hi = x;
        }
    }
    hi - lo
}

// Clamp into i32's range, then narrow: the narrow can no longer fault.
fn clamp_to_i32(i64 x) : i32
{
    if (x > widen<i64>(max_value<i32>()))
    {
        max_value<i32>()
    }
    else if (x < widen<i64>(min_value<i32>()))
    {
        min_value<i32>()
    }
    else
    {
        narrow<i32>(x)
    }
}

// The index of the first b, or usize's maximum for "not found".
fn find(ref<Vec<u8>, shared> v, u8 b) : usize
{
    foreach (i, x in v)
    {
        if (*x == b)
        {
            return i;
        }
    }
    max_value<usize>()
}

fn main()
{
    Vec<i64> v = Vec::new();
    Vec::push(&mut v, 7);
    Vec::push(&mut v, -3);
    Vec::push(&mut v, 12);
    assert(spread(&v) == 15);

    assert(clamp_to_i32(5000000000) == 2147483647);
    assert(clamp_to_i32(-5000000000) == -2147483648);
    assert(clamp_to_i32(42) == 42);

    Vec<u8> bytes = Vec::new();
    Vec::push(&mut bytes, 10);
    Vec::push(&mut bytes, 20);
    assert(find(&bytes, 20) == 1);
    assert(find(&bytes, 99) == max_value<usize>());
}

A generic function may use the limits of its own type parameter. It cannot do arithmetic on a T without a bound (§12), but it can produce a T's limit and pass it on. Each use is checked when the function is instantiated, so a T that is not an integer type is rejected before the program runs.

import std;

// The value inside, or T's maximum if there is none.
fn or_max<T>(Option<T> r) : T
{
    match (r)
    {
        Some(x) : x,
        None    : max_value<T>(),
    }
}

fn main()
{
    u64 big = 5000000000;
    assert(or_max(checked_mul(big, big)) == max_value<u64>());   // the product overflows u64
    assert(or_max(checked_add(2: i32, 3)) == 5);
}

fn main()
{
    max_value<bool>();                // ✗ diag.type-mismatch (static): only number types have these
}

fn main()
{
    max_value<i32>() + 1;             // ✗ diag.arith-overflow (dynamic): a limit is a value, not a literal
}

§07Resources, ownership and destruction

Resource types have exactly one owner, move instead of copying, and are destroyed automatically and exactly once.

Some values are just data: an i32, a bool, a struct of numbers. Copying them is harmless. Other values own something that must be released exactly once: a heap buffer, a file handle, a lock, a thread. CobaltC calls the second kind resources, and the rules in this section exist so that a resource always has exactly one owner, is never copied, and is destroyed exactly once, at a predictable moment, whether or not you remember to do it.

Plain types and resource types

A type is a resource if it is declared with the resource keyword, or if any of its fields, elements or payloads is a resource. Vec<T>, String, Rc<T>, a thread handle, a mutex and a lock guard are all resources. Numbers, bool, references, raw pointers and function values are plain. A struct of plain fields is plain; a struct containing a Vec is a resource by derivation, with no keyword needed.

struct Point                          // plain: two numbers
{
    i32 x;
    i32 y;
}

struct Path                           // a resource by derivation: it contains a Vec
{
    Vec<Point> points;
}

resource struct Handle                // a resource by declaration: it manages something
{                                     // beyond its fields (an OS handle, say)
    i32 fd;
}

One owner: moves, not copies

A resource lives in exactly one place. When you initialise a variable from it, pass it by value to a function, store it in a field, or return it, the resource moves: the new place becomes the owner and the old name becomes stale. Using a stale name is an error (diag.stale-binding), caught at compile time when the move is visible in the same function and at run time otherwise. A name moved on only some paths (in one branch of an if, or in a loop body that runs again) counts as moved: give it a new value on every path before using it again. Nothing is ever copied silently, so there can never be two owners.

resource struct Token
{
    i32 id;
}

fn consume(Token t)                   // a by-value resource parameter takes ownership
{
}                                     // t is destroyed here, at the callee's scope exit

fn main()
{
    Token t = Token { .id = 1 };
    consume(t);                       // ✓ t moves into consume
    consume(t);                       // ✗ diag.stale-binding: t no longer owns anything
}

import std;

fn main()
{
    Vec<i32> v = Vec::new();
    auto w = v;                       // moves the Vec into w; v is now stale
    Vec::push(&mut w, 1);             // ✓ use the new owner
}

Because a resource is never copied, it cannot appear where a copy would be made: you cannot compare two Vecs with ==, and you cannot read one out of a field of a live struct. Take a reference instead (§09), or move the whole container.

import std;

fn main()
{
    Vec<i32> a = Vec::new();
    Vec<i32> b = Vec::new();
    auto same = a == b;               // ✗ diag.read-of-resource: comparison would copy both
}

Automatic destruction

Every resource is destroyed automatically: a named resource when the block that declared it ends, and a temporary (an unnamed call result or literal) at the end of the statement that created it. Locals are destroyed in reverse order of creation. A struct's resource fields are destroyed after the struct's own destructor, innermost first, in reverse declaration order. A return, break, continue or run-time fault unwinds the same way. There is no way to leak a resource, so there is no leak diagnostic.

You can also destroy a resource early with drop(x). Afterwards x is stale until you give it a new value: once x's value has gone, moved away or dropped, x = e gives it a new one, which is destroyed at the end of x's own block like its first value. A value whose end only frees memory (a String, a Vec, a HashMap, an Option or struct made of such: a *quiet* type, D-0194) is simply replaced: s = String::from_str("new"); destroys the old String there. Assigning over any other resource that is still there is an error (diag.overwrite-of-live-resource), because its end does something you should see: a destructor of yours runs, a file closes, a thread is joined. Write overwrite(&mut x, e), which destroys the old value and stores the new one, or drop it first. The same holds for a field (g.file = f;) and for a write through a reference (*r = v;, r.rows = v;): where the compiler can see the old value is still there, it rejects the assignment before the program runs; elsewhere, the run does. What counts is whether the value there owns anything: a None of an Option<File> owns nothing, so o = Some(f); over it is fine, while a Some must be dropped first. A type declared resource, or with a destructor, always owns. Declaring the name again in the same block does not: that is diag.duplicate-local (§11).

import std;

fn make() : Vec<i32>
{
    Vec<i32> v = Vec::new();
    Vec::push(&mut v, 1);
    v                                 // moved out to the caller, not destroyed here
}

fn main()
{
    {
        auto result = make();         // result owns the Vec now
        Vec::push(&mut result, 2);
    }                                 // destroyed here, at the caller's block exit
    make();                           // an unstored temporary: destroyed at this `;`
    Vec<i32> v = Vec::new();
    drop(v);                          // ✓ destroyed early; v is now stale
    v = Vec::new();                   // ✓ v's value has gone, so v takes a new one
    Vec::push(&mut v, 3);
}

Destructors

A type gets a destructor by declaring an associated function named drop that takes an exclusive reference to the value and returns nothing. The language calls it exactly once, when the resource is destroyed; you may not call it yourself. Inside it you can mutate the value but not move out of it. Field resources are destroyed after the body runs. The type must be a resource: declare it resource struct. A plain struct is copied and never destroyed, so a destructor on one would never run, and is refused (diag.destructor-on-plain-type).

import std;

resource struct Tagged
{
    str tag;
}

fn Tagged::drop(ref<Tagged, exclusive> self)
{
    printf("%s", self.tag);          // runs once, when this Tagged is destroyed
}

resource struct Holder
{
    Tagged a;
    Tagged b;
}

fn main()
{
    Tagged x = Tagged { .tag = "1" };
    Tagged y = Tagged { .tag = "2" };
    Holder h = Holder { .a = Tagged { .tag = "3" }, .b = Tagged { .tag = "4" } };
    printf("\n");
}   // h first (its fields in reverse order: 4 then 3), then y, then x

4321

Things the rules forbid

import std;

resource struct Lock
{
    u32 id;
}

fn Lock::drop(ref<Lock, exclusive> self)
{
    printf("released %u\n", self.id);
}

fn main()
{
    Vec<i32> v = Vec::new();
    v = Vec::new();                   // fine: a Vec of numbers is quiet, the old one is destroyed
    Lock l = Lock { .id = 1 };
    l = Lock { .id = 2 };             // ✗ diag.overwrite-of-live-resource: lock 1's release would be hidden
}

The fix is overwrite(&mut l, Lock { .id = 2 });, which destroys the old Lock there (and prints its release where you wrote it), or drop(l); first. Two more rejections you will meet: drop(v) twice is diag.stale-binding (the first drop ended v); and moving a resource out of a field of a live struct (auto inner = holder.field;) is diag.move-out-of-field, because the struct would be left half-owned. Move the whole struct, or take a reference to the field.

§08Aliasing: shared and exclusive access

Any number of readers, or one writer, never both. The rule is checked at every access, so a conflict cannot go unnoticed.

Two pieces of code touching one object at the same time is the root of most memory bugs: an iterator invalidated by a push, a struct half-updated by two threads, a buffer freed while something still points into it. CobaltC's answer is a discipline on access paths: every way of reaching an object (its name, a reference, a field projection) has a mode, and the modes that may coexist are fixed.

Two modes

A variable's own name is always an exclusive path: there is no mut keyword on bindings, because whether you may write is decided by what references currently exist, not by how the variable was declared. Restricting access is what a borrow does.

The one rule

At every read and every write, the language checks: is there another live path to the same storage whose mode conflicts with this access? Shared and shared never conflict. Anything involving an exclusive path conflicts, unless the other path is an ancestor of this one (the thing it was borrowed from). Forming a conflicting borrow is reported at once as diag.aliasing-conflict; so is using the owner while a conflicting borrow lives.

fn main()
{
    i32 x = 1;
    auto r1 = &x;                     // ✓ shared
    auto r2 = &x;                     // ✓ any number of shared readers; the owner may still read x
    x = 2;                            // ✗ diag.aliasing-conflict: writing while r1, r2 are live
    i32 sum = *r1 + *r2;
}

fn main()
{
    i32 x = 1;
    auto r1 = &mut x;                 // ✓ exclusive
    auto r2 = &x;                     // ✗ diag.aliasing-conflict: r1 is exclusive and still live
    *r1 = 2;
}

Borrows in one argument list are all formed before the call holds any of them, so passing two conflicting references to the same storage is accepted at the call. The conflict is reported at the first access inside the function that meets both, the point where it actually matters.

fn set_then_read(ref<i32, exclusive> a, ref<i32, shared> b) : i32
{
    *a = 1;                           // ✗ diag.aliasing-conflict (dynamic): b reaches the same i32
    *b
}

fn main()
{
    i32 x = 0;
    set_then_read(&mut x, &x);        // accepted here; each borrow formed while the other was not yet held
}

Most conflicts are reported before the program runs, marked (static): whenever the function body itself shows that a conflicting reference is certainly live. That covers a borrow held in a variable, a reborrow through a reference or a guard (&*r, &r.f), the binder of a match (&e) arm, and the arguments a thread was spawned with, until join. What one body cannot see, like the call above, is reported when the conflicting access runs, marked (dynamic).

struct Counter
{
    i32 hits;
    i32 misses;
}

fn bump(ref<Counter, exclusive> c)
{
    auto n = &mut c.hits;             // a reborrow of c.hits, through c
    c.misses = 0;                     // ✓ a different field
    c.hits = 0;                       // ✗ diag.aliasing-conflict (static): n still borrows c.hits
    *n += 1;
}

fn main()
{
    Counter k = Counter { .hits = 0, .misses = 0 };
    bump(&mut k);
}

When does a borrow end?

A reference lives as long as something holds it. A reference passed straight to a call dies when the statement ends, which is why consecutive calls that each borrow the same variable are fine. A reference, slice or StringView kept in a local variable lives until the last statement of its block that uses it, and ends there. So does any other local that holds references but owns nothing to destroy: the Option<ref<V, shared>> that HashMap::get returns, or a struct of references. Using it inside a loop, a branch or a nested block counts as a use by that whole statement, so a reference used in a loop lives through the loop. A reference variable lives to the end of its block, as before, when a closure captures it, when another reference was borrowed through it, or when a variable that can hold references (a Vec<StringView>, say) shares a statement with it and is used later, since that variable may keep a reference derived from it.

import std;

fn main()
{
    String cur = "abc";
    ref<Vec<u8>, shared> b = String::as_bytes(&cur);
    assert(Vec::len(b) == 3);         // the last use of b: it ends after this statement
    String::clear(&mut cur);          // ✓ nothing borrows cur any more
    assert(String::len(&cur) == 0);
    HashMap<String, u32> m = HashMap::new();
    HashMap::insert(&mut m, String::from_str("a"), 1);
    Option<ref<u32, shared>> hit = HashMap::get(&m, &String::from_str("a"));
    assert(Option::is_some(&hit));    // the last use of hit
    HashMap::insert(&mut m, String::from_str("b"), 2);   // ✓ hit no longer borrows m
}

import std;

fn main()
{
    Vec<i32> v = Vec::new();
    Vec::push(&mut v, 1);
    ref<i32, shared> first = &v[0];
    foreach (k in 0..2: i32)
    {
        printf("%v\n", *first);      // used in the loop: first lives through the whole loop
        Vec::push(&mut v, k);         // ✗ diag.aliasing-conflict: first still borrows v
    }
}

A block ends every borrow it holds, so wrapping a borrow in a block still works, and reads well when a borrow should visibly end.

import std;

fn main()
{
    Vec<i32> nums = Vec::new();
    Vec::push(&mut nums, 10);         // the borrow dies at this `;`
    Vec::push(&mut nums, 20);         // ✓ a fresh borrow; nothing conflicts
    i32 x = 1;
    {
        auto r = &mut x;              // r lives until the end of this block
        *r = 5;
    }
    x += 1;                           // ✓ r is gone
    assert(x == 6);
}

Reborrowing and ancestors

A path derived from another (a reborrow &*r, or a field projection r.a) has that path as its ancestor. Ancestors never conflict with their descendants, but the ancestor cannot be used in a conflicting way while a descendant lives. Once the descendants are gone, the ancestor is usable again.

import std;

fn main()
{
    i32 x = 1;
    {
        auto r1 = &mut x;
        {
            auto r2 = &*r1;           // ✓ a shared reborrow, child of r1
            assert(*r2 == 1);          // writing through r1 here would be diag.aliasing-conflict
        }
        *r1 = 3;                      // ✓ r2 is gone, the parent is usable again
    }
    assert(x == 3);                    // ✓ r1 is gone, the owner is usable again
}

Disjoint fields

Conflicts are decided by overlap of storage, not by which variable the paths come from. Two exclusive borrows of different fields of the same struct do not overlap and may coexist.

import std;

struct Pair
{
    i32 a;
    i32 b;
}

fn main()
{
    Pair p = Pair { .a = 1, .b = 2 };
    auto ra = &mut p.a;
    auto rb = &mut p.b;               // ✓ disjoint from p.a
    p.b = 30;                         // ✗ diag.aliasing-conflict: rb is a live exclusive path to p.b
    *ra = 10;
    *rb = 20;
}

The write to p.b above is rejected because rb, a live exclusive path to exactly that storage, still exists until the block ends. The same applies to reading p.b through the owner: an exclusive child excludes every non-ancestor access, reads included, until it is gone. Confine the borrows to a block and the owner is free again:

import std;

struct Pair
{
    i32 a;
    i32 b;
}

fn main()
{
    Pair p = Pair { .a = 1, .b = 2 };
    {
        auto ra = &mut p.a;
        auto rb = &mut p.b;
        *ra = 10;
        *rb = 20;                     // reading p.a or p.b here would conflict with the live exclusive borrows
    }
    assert(p.a == 10);                 // ✓ both borrows ended with the block
    assert(p.b == 20);
}

Shared means read-only, all the way down

An exclusive path can only be derived from an exclusive path. Given a ref<T, shared> you cannot write through it and cannot reborrow it exclusively: the mode is part of the reference's type, so a function's signature tells the caller exactly what it may do. The other direction is always allowed: an exclusive reference can be passed to a function that asks for a shared one, and the function gets a shared reborrow of it (as if you had written &*r). With v : ref<Vec<T>, exclusive>, Vec::len(v) just works; likewise a slice<T, exclusive> for a slice<T, shared>.

struct P
{
    i32 a;
}

fn bump(ref<P, shared> p)
{
    p.a = 1;                          // ✗ diag.write-through-shared
}

fn main()
{
    P v = P { .a = 0 };
    bump(&v);
}

All the way down includes the references a value holds. Read through a ref<S, shared>, an exclusive reference stored in S comes out as a shared one: you can read through it, keep it, pass it or return it as a ref<T, shared>, but not write through it. A copy of a value that holds an exclusive reference cannot be taken out through a shared reference either, and clone cannot copy one (diag.borrow-exceeds-source). A fn field is checked when it is called: a closure that writes a variable it captured cannot be called through a shared reference to the struct that holds it (diag.borrow-exceeds-source, at run time, since a fn type does not show what the closure captured). To change something through a value others share, put it in a mutex (§19).

import std;

struct Counter
{
    ref<i32, exclusive> total;
}

fn peek(ref<Counter, shared> c) : i32
{
    *c.total                          // ✓ reading is fine
}

fn bump(ref<Counter, shared> c)
{
    *c.total = *c.total + 1;          // ✗ diag.write-through-shared
}

fn main()
{
    i32 n = 0;
    Counter c = Counter { .total = &mut n };
    printf("%v\n", peek(&c));
    bump(&c);
}

Moving or destroying needs solitude

Moving a resource, or destroying it (with drop or at scope end), requires that no other path to it exists at all. Otherwise a reference would be left pointing at nothing.

import std;

fn main()
{
    Vec<i32> v = Vec::new();
    auto r = &v;
    drop(v);                          // ✗ diag.destroy-while-aliased: r is still live
    usize n = Vec::len(r);            // (because r is used here)
}

import std;

fn take(Vec<i32> v)
{
}

fn main()
{
    Vec<i32> v = Vec::new();
    auto r = &v;
    take(v);                          // ✗ diag.move-while-aliased: r still reaches v
    usize n = Vec::len(r);            // (because r is used here)
}

§09References

References are copyable values that name a place; dereferencing gives you that place back with every check intact.

A reference is the value form of an access path: a way to reach an object without owning it. References are plain values (copyable, no destroy authority) and carry their mode in their type. Raw pointers are a different thing entirely and live in §20.

Forming and using references

The operand of & must be a place: a variable, a field, an element, or *r. You cannot borrow a temporary such as a call result or a literal (&make()); bind it to a variable first. This is rejected rather than given a lifetime because the temporary would end at the semicolon and take the reference with it.

import std;

struct Pair
{
    i32 a;
    i32 b;
}

fn main()
{
    i32 x = 5;
    {
        auto r = &mut x;
        *r += 1;                      // read and write through the same reference
    }
    assert(x == 6);

    Pair p = Pair { .a = 1, .b = 2 };
    auto rp = &p;
    assert(rp.a == 1);                 // auto-deref: rp.a means (*rp).a
    auto ra = &p.a;
    auto rb = &p.b;
    assert(!(ra == rb));               // different fields, so different identities
    auto ra2 = &p.a;
    assert(ra == ra2);                 // same field of the same object

    ref<i32, shared> copy = ra;       // references are plain values: copying is fine
    assert(*copy == 1);
}

fn make() : i32
{
    5
}

fn main()
{
    auto r = &make();                 // ✗ diag.borrow-of-non-place: a call result is not a place
}

The one place a temporary may be borrowed is as an argument: f(&make()) or printf("%v", &sprintf(…)). The value lives until the end of the statement, and the call is over before then. This works when the call's own result is not a reference, since such a result could carry the borrow out. An operator's result, the value ? gives, and a number or bool literal may be borrowed there too: HashMap::get(&m, &(k + 1)), Vec::len(&names()?), HashMap::get(&m, &3). A literal takes the type the parameter refers to, so &3 passed where a ref<u64, shared> is expected is a reference to a u64.

import std;

fn total(ref<Vec<i32>, shared> v) : i32
{
    i32 t = 0;
    foreach (x in v)
    {
        t += *x;
    }
    t
}

fn make(i32 n) : Vec<i32>
{
    Vec<i32> v = Vec::new();
    for (i32 i = 1; i <= n; i += 1)
    {
        Vec::push(&mut v, i);
    }
    v
}

fn main()
{
    assert(total(&make(4)) == 10);     // the Vec lives until the end of this statement
    printf("%v\n", &sprintf("%v-%v", 1, 2));

    HashMap<u64, str> names = HashMap::new();
    HashMap::insert(&mut names, 3, "three");
    u64 k = 2;
    assert(HashMap::contains(&names, &(k + 1)));     // an operator's result
    printf("%s\n", *Option::unwrap(HashMap::get(&names, &3)));   // a literal, as a u64
}

Part of a temporary may be borrowed there too: a field (String::len(&person().name)), an element, or a slice of an array literal or a call's result (sum(&[1, 2, 3][0..2])). A String that a call returns may be viewed the same way, so a computed path needs no binding: read_file(&sprintf("%s/%s", dir, name)[0..$]). It lives as long as the temporary does, to the end of the statement. A field can also be moved out of a temporary, String n = person().name;: the rest of the temporary ends at once, as if the struct had been destructured. That needs a struct without a destructor of its own.

import std;

struct Person
{
    String name;
    String city;
}

fn person() : Person
{
    Person { .name = "Ada", .city = "London" }
}

fn sum(slice<i32, shared> xs) : i32
{
    i32 t = 0;
    foreach (x in xs)
    {
        t += *x;
    }
    t
}

fn main()
{
    assert(String::len(&person().name) == 3);        // a field of a temporary, borrowed
    assert(sum(&[1, 2, 3][0..2]) == 3);              // a slice of an array literal
    assert(StringView::len(&person().city[0..3]) == 3);  // a view of a temporary's String
    String n = person().name;                        // moved out; `city` ends here
    assert(String::eq_str(&n, "Ada"));
}

References inside structs

A reference may be stored in a field. It then lives as long as the struct that holds it, which in turn may not outlive the referent (§10).

import std;

struct View
{
    ref<i32, shared> r;
}

fn main()
{
    i32 x = 1;
    auto v = View { .r = &x };        // the borrow is held by v's object
    assert(*v.r == 1);                 // ✓ valid as long as v lives
}

References as parameters

Passing &x or &mut x to a function creates a borrow that the parameter holds for the duration of the call and releases when the call returns. Inside the function the parameter is an ordinary reference. A parameter of type ref<T, exclusive> can be passed on to another call directly, without a new &mut, because it already is an exclusive reference.

import std;

fn bump(ref<i32, exclusive> counter) : i32
{
    *counter += 1;
    *counter
}

fn bump_twice(ref<i32, exclusive> c) : i32
{
    bump(c);                          // pass the reference on as a value
    bump(c)
}

fn main()
{
    i32 n = 0;
    assert(bump(&mut n) == 1);         // the borrow lives for the call only
    assert(bump_twice(&mut n) == 3);
    assert(n == 3);
}

§10Lifetimes and temporal validity

A reference is checked statically where the escape is visible and dynamically everywhere else; either way it never outlives its target.

A reference must never outlive the object it refers to. CobaltC enforces this with two layers: a lexical check that rejects the obvious escapes before the program runs, and a use-time check that catches everything else as diag.stale-binding at the first use of a dead reference. No lifetime annotations exist; the language decides validity from where things are declared.

A reference cannot leave its referent's scope

If a reference to a local is returned from the function, or stored into a variable declared in an enclosing block, it is rejected statically as diag.reference-escapes-scope.

fn dangling() : ref<i32, shared>
{
    i32 x = 1;
    &x                                // ✗ diag.reference-escapes-scope: x dies with this call
}

fn main()
{
    auto r = dangling();
    *r;
}

The corrected form returns the value itself: fn ok() : i32 { i32 x = 1; x }.

When the escape is not lexically visible (the reference is stored through another reference, into an aggregate the checker cannot see the owner of, or through a call), the static rule does not fire and the run-time check takes over. The program is still rejected, just later.

struct Holder
{
    ref<i32, shared> r;
}

fn stash(ref<Holder, exclusive> h)
{
    i32 local = 5;
    h.r = &local;                     // a store through a reference: not lexically visible as an escape
}                                     // local ends here; whatever h points at now holds a dead reference

fn main()
{
    i32 outer = 0;
    auto held = Holder { .r = &outer };
    stash(&mut held);
    *held.r;                          // ✗ diag.stale-binding (dynamic): first use of the dead reference
}

Returning references from functions

A function may return a reference when it has exactly one reference-typed parameter: the result is understood to point into whatever that argument pointed at, and callers are checked accordingly. This is the shape of every library accessor (Vec::index_shared, Rc::get). A function with zero or several reference parameters may not return a reference (diag.lifetime-elision-ambiguous); compose single-reference helpers instead, or return an owned value.

import std;

struct Pair
{
    i32 a;
    i32 b;
}

fn first(ref<Pair, shared> p) : ref<i32, shared>
{
    &p.a                              // ✓ one reference parameter: the result borrows from it
}

fn main()
{
    Pair pr = Pair { .a = 1, .b = 2 };
    auto y = first(&pr);              // y is a shared borrow of pr.a, held by y
    assert(*y == 1);
}

fn pick(ref<i32, shared> p1, ref<i32, shared> p2) : ref<i32, shared>
{
    p1                                // ✗ diag.lifetime-elision-ambiguous: which argument does the
}                                     //   result depend on? The language will not guess.

Because y above is known to borrow from pr, a later pr.a = 3; while y is still in use is an aliasing conflict (§08), exactly as if you had written auto y = &pr.a;.

Growth invalidates element references

A Vec may move its elements to a new buffer when it grows. A reference to an element obtained before a push that reallocates is stale afterwards. Where the checker can see both the borrow and the push in one function, it rejects the program; where it cannot (the push happens through a reference parameter, say), the stale reference faults at its next use. Either way it does not read freed memory.

import std;

fn main()
{
    Vec<i32> v = Vec::new();
    Vec::push(&mut v, 10);
    auto first = Vec::index_shared(&v, 0);   // a shared borrow into v, held by first
    Vec::push(&mut v, 20);                   // ✗ diag.aliasing-conflict: an exclusive borrow of v
    *first;                                  //   while first (derived from v) is still live
}

§11Initialisation

Every variable is written before it is read, on every path, and every aggregate is built whole; constants name values known before the program runs.

Reading storage that has never been written is undefined behaviour in C. In CobaltC it is impossible in a well-formed program: a variable declared without an initialiser must be assigned on every path before it is read, and the check is static. Aggregates are always initialised whole.

Declarations

Initialising from a plain value copies it; from a resource, moves it; from a temporary such as a struct literal or a call result, adopts it.

One name, one declaration per block

A block declares a name once. A second i32 total further down the same block is diag.duplicate-local, which says where the first one is: to change the variable, assign to it (total = 10;); for a value of another type, give it another name. A function's parameters count as declared in its body, and so do the names a foreach, a for header, a match arm or an if-pattern binds for the block they govern, so fn f(i32 n) { i32 n = n * 2; } is rejected too: write n = n * 2;.

A block inside it may reuse the name: the inner variable shadows the outer one until the inner block ends, and the outer one is untouched. Separate blocks, successive loops and separate match arms each have their own names, and a local may take the name of a function or a constant (a program's own names never clash with names added to std later). Languages differ here: Rust lets any declaration shadow, Java and C# forbid shadowing a local even from an inner block; CobaltC follows C and C++. Every local can already be assigned, so a second declaration in the same block would only hide a mistake.

import std;

fn main()
{
    i32 total = 0;
    total += 4;                       // ✓ change it by assigning
    {
        i32 total = 100;              // ✓ an inner block's own total
        assert(total == 100);
    }
    assert(total == 4);               // the outer one is untouched
    i32 total = 10;                   // ✗ diag.duplicate-local: declared above, in this block
}

Constants

const τ NAME = e; names a value, at the top level of any module or inside a function (below). NAME can be used wherever its value could, with the visibility, export, import and qualified paths of any item. e must be a constant expression: literals, other constants, operators, struct, array and variant literals of constant expressions and their fields and elements (SCREEN.w, PRIMES[2]), a function's name, and the pure intrinsics (min_value, sizeof, widen, …). A constant cannot be a resource, cannot depend on itself, and cannot be assigned to or borrowed; an overflow in computing one is reported at the constant, before the program runs. Integer, float, bool and str constants cost nothing at run time: each use becomes the literal.

import std;

const u64 KIB = 1024;
const u64 MIB = KIB * KIB;
const u32 READ = 0x1;
const u32 WRITE = 0x2;
const u32 READ_WRITE = READ | WRITE;
const i32 LOWEST = -2147483648;

struct Size
{
    u32 w;
    u32 h;
}

const Size SCREEN = Size { .w = 640, .h = 480 };

fn main()
{
    static_assert(MIB == 1048576);
    static_assert(READ_WRITE == 3);
    static_assert(LOWEST < 0);
    static_assert(SCREEN.w * SCREEN.h == 307200);   // a field of a constant is a constant
}

A constant is typed exactly as a declaration τ x = e; would be: in const u64 MIB = 1024 * 1024; the literals are u64s, and an initializer that overflows its type, such as const i32 BIG = 65536 * 65536;, is rejected at the constant. const auto NAME = e; takes its type from e, as auto x = e; does: const auto MIB = KIB * KIB; is a u64 when KIB is, and a bare literal is an i32 (or an f64). When e alone does not settle a type — None, say — write the type.

A constant can also be declared inside a function, as a statement: const u8 LIMIT = 200;. It is the same kind of constant, but its name is scoped like a local: it can be used from its declaration to the end of its block, and an inner block can declare another constant or a variable of the same name, which hides it there (in its own block, a second declaration of the name is diag.duplicate-local, above). A local variable, even one set from a literal, is not a constant — any later statement could change it — so static_assert cannot use it; name the value with const when you want the check made before the program runs. A local constant's initializer can use other constants, but not a local variable or the function's type parameters.

import std;

fn checksum(slice<u8, shared> data) : u32
{
    const u32 PRIME = 16777619;       // FNV-1a: the 32-bit prime and offset basis
    const u32 SEED = 2166136261;
    static_assert(PRIME % 2 == 1);
    u32 h = SEED;
    foreach (b in data)
    {
        h = wrapping_mul(h ^ widen<u32>(*b), PRIME);
    }
    h
}

fn main()
{
    u8 b = 200;
    auto d = b + 1;                   // a variable: checked when the program runs
    assert(d == 201);
    const u8 B = 200;
    const auto D = B + 1;             // constants: checked before it runs (auto: D is a u8)
    static_assert(D == 201, "D is %v", D);
    array<u8, 3> abc = [97, 98, 99];
    assert(checksum(&abc[0..$]) == 440920331);
}

const means known when the program is compiled

A const can never change: assigning to it, or borrowing it with &mut, is rejected when the program is compiled. A constant is not a variable at all, but stands for its value, so assigning to it is like assigning to a literal. Copying its value out is fine: i32 y = LIMIT; gives a variable y, which can change, while LIMIT stays as it is.

import std;

const i32 LIMIT = 10;

fn main()
{
    i32 y = LIMIT;                    // a copy of the value: y is an ordinary variable
    y += 1;
    LIMIT = 11;                       // ✗ diag.type-mismatch: a constant cannot be assigned
}

What makes it a constant is when its value is known: before the program runs, like const in Rust, Go and C# or constexpr in C++. That differs from C, C++, Java or JavaScript, where const (or final) often marks a variable that is set once, at run time, and never reassigned. const usize N = arg_count(); is diag.const-not-constant, because the value is only known once the program runs.

CobaltC has no read-only local variables either: every local can be assigned. It does not need them for safety, because every change to a variable shows where it happens. Only two things can change a local: an assignment to its name in its own function, or an exclusive reference to it, &mut x, which must be written out where it is made. A function given &x or a copy of x cannot change it; while a shared reference to it is in use, nothing can (diag.aliasing-conflict, §8); and threads share changing state only through a mutex. So to see whether x can change, look in its function for x = and &mut x. To lend a value without letting it change, lend it with &.

import std;

fn peek(ref<i32, shared> r) : i32
{
    *r                                // may read; writing *r is diag.write-through-shared
}

fn bump(ref<i32, exclusive> r)
{
    *r += 1;
}

fn main()
{
    i32 limit = 10;                   // a variable: it can be assigned, as every local can
    assert(peek(&limit) == 10);       // &limit: the callee can only read it
    bump(&mut limit);                 // the one way another function changes it, visible here
    assert(limit == 11);
    ref<i32, shared> view = &limit;
    assert(*view == 11);              // while view is in use, nothing may write limit
    limit = 12;                       // ✓ view's last use is above, so it no longer holds limit
    assert(limit == 12);
}

Definite assignment

import std;

fn main()
{
    i32 x;                            // uninitialised
    bool c = true;
    if (c)
    {
        x = 1;
    }
    else
    {
        x = 2;
    }
    assert(x == 1);                    // ✓ assigned on both paths
}

fn main()
{
    i32 x;
    bool c = false;
    if (c)
    {
        x = 1;
    }
    i32 y = x + 1;                    // ✗ diag.use-of-uninitialized: no write on the else path
}

The analysis is purely about the function's own control flow: it does not know that c happens to be true. If it cannot prove a write on some path, the program is rejected (this is one of the few checks where "unknown" means rejected rather than "check at run time").

Aggregates are initialised whole

You cannot declare a struct uninitialised and then fill its fields one by one. A struct literal supplies every field at once; after that, individual fields can be assigned freely.

import std;

struct Pair
{
    i32 a;
    i32 b;
}

fn main()
{
    Pair p = Pair { .a = 1, .b = 2 };  // every field, exactly once, in any order
    p.a = 10;                          // ✓ a field write on an initialised object
    assert(p.a == 10);
    assert(p.b == 2);
}

Destructuring a struct

import std;

struct Entry
{
    String item;
    i64 change;
}

fn main()
{
    Entry e = Entry { .item = "pens", .change = -3 };
    Entry { item, change } = e;       // binds `item` and `change`; e is consumed
    assert(String::len(&item) == 4 && change == -3);
}

This is the only pattern form outside match and the pattern conditions of if and while (§14). It names fields of the struct, each once, in any order, and consumes the struct: a resource field moves out to its new binding, a plain one is copied. It is how a struct gives up a resource it holds (the library's String::into_bytes uses it to hand back the Vec<u8>), since a resource field cannot otherwise be moved out of a struct that lives on. field : name binds a field to another name, so two values of one type can be taken apart side by side, and a final .. stands for the fields not named: they are not bound, and those holding resources are destroyed when the block ends. Naming a field twice, or leaving one out without .., is a type error, and a struct with its own destructor cannot be destructured, since the destructor would then run on a struct whose fields had left it (diag.move-out-of-field).

import std;

struct Entry
{
    String item;
    i64 change;
    String note;
}

fn main()
{
    Entry a = Entry { .item = "pens", .change = -3, .note = String::new() };
    Entry b = Entry { .item = "ink", .change = 5, .note = String::new() };
    Entry { item : first, change : da, .. } = a;     // renamed; `note` is left and ends with the block
    Entry { item : second, change : db, .. } = b;
    assert(String::len(&first) + String::len(&second) == 7 && da + db == 2);
}

§12The type system

Nominal types, no coercions, monomorphic generics (one copy per use with concrete types) with five built-in bounds, and local inference that only flows downward.

CobaltC's type system is deliberately plain: every type is exactly what it is declared to be, nothing converts to anything else, and generics are templates instantiated with concrete types. What it gives you in return is that the type of every expression is decidable from the text, and that a function signature is a complete statement of what the function may do with its arguments.

The built-in types

Nominal, exact, no coercions

Two types are the same only if they have the same name and the same type arguments. ref<i32, shared> and ref<i32, exclusive> are different types. There is no subtyping and no implicit conversion anywhere: not between integer widths, not from T to ref<T, m>, not from Option<T> to T. This applies to arguments too. A literal is not an exception but a different thing: it has no type of its own until its position gives it one, so u64 x = 5;, StringView v = "x"; and String s = "x"; type the literal (§21) rather than convert a value, and the same positions still reject an i32, a str or any other typed value.

fn takes_i64(i64 x) : i64
{
    x
}

fn main()
{
    i32 y = 5;
    takes_i64(y);                     // ✗ diag.type-mismatch: i32 is not i64; write takes_i64(widen<i64>(y))
}

A bare integer literal is the one flexible thing: takes_i64(5) is fine, because the literal takes its type from the parameter (§06).

Equality

== and != are defined for numbers, bool, (), str (bytewise), references (identity), raw pointers (address), and for structs, arrays and enums whose parts are all comparable (element by element; enums must have the same variant and equal payloads). They are not defined for function values or for anything that is a resource, with one exception: two Strings compare by their text.

< <= > >= order numbers, bool (false before true), and text: two strs, two Strings or two StringViews, by their bytes, a prefix first (for UTF-8 that is code point order). A String operand is not copied or moved: it is borrowed for the comparison, as &s would be, so it stays usable afterwards.

import std;

fn main()
{
    String a = "app";
    String b = "apple";
    assert(a != b && a < b);          // text order: a prefix first
    assert("b" > "abc");
    assert(false < true);
    String c = a;                     // a was only borrowed by the comparisons; it can still move
    assert(c == String::from_str("app"));
}

Generics

Functions, structs and enums can take type parameters. Generics are monomorphic: each use with a different set of concrete types is a separate copy of the declaration, compiled (or, in the interpreter, run) as if you had written it out with those types: identity(5) and identity(2.5) below call two functions, one for i32 and one for f64. So there is no run-time type information, no boxing and no indirect call at call sites; the cost is one copy per combination of types used. Inside a generic body a value of a type parameter T can be stored, passed, returned, referenced and moved. To do more with it — compare it, add it — give T a bound (below).

import std;

struct Box<T>
{
    T value;
}

enum Maybe<T>
{
    Just(T),
    Nothing
}

fn identity<T>(T x) : T
{
    x                                 // all a bare T can do: be moved around
}

fn boxed<T>(T x) : Box<T>
{
    Box { .value = x }                // the field type is T, so this is fine
}

fn main()
{
    assert(identity(5) == 5);          // T := i32, from the argument
    assert(identity<i64>(5) == 5);     // T given explicitly: name<Type>(...)
    Box<i32> b = Box { .value = 7 };  // Box's T from the declared type
    assert(b.value == 7);
    Box<Vec<u8>> c = boxed(Vec::new());   // both T's from the declared type of c
    assert(Vec::len(&c.value) == 0);
}

Bounds

A function's type parameter may carry one of five bounds, written after a colon: fn max<T: ordered>(T a, T b) : T. Each of the first four names a fixed set of built-in types and the operators every one of them has, and each includes the ones before it; the fifth, clone, says a value of T can be copied (below):

import std;

fn largest<T: ordered>(slice<T, shared> xs) : T
{
    T best = xs[0];
    foreach (x in xs)
    {
        if (*x > best) { best = *x; }
    }
    best
}

fn total<T: number>(slice<T, shared> xs) : T
{
    T sum = 0;                        // a literal takes T's type, a float one too
    foreach (x in xs)
    {
        sum += *x;
    }
    sum
}

fn main()
{
    array<i32, 3> a = [4, -2, 9];
    array<f64, 2> f = [1.5, 2.25];
    assert(largest(&a[0..$]) == 9);
    assert(total(&a[0..$]) == 11);
    assert(total(&f[0..$]) == 3.75);
}

The body is checked once against the bound: a + b in a function whose T is only ordered is diag.unbounded-type-parameter. Each call is checked for a type that satisfies it: largest of bools, or of a String, is diag.type-mismatch. Each use is also checked at its concrete type, so -x at T = u32 is still rejected there. Structs and enums take no bounds; put them on the functions that use the operations.

clone(&x) copies a value of any clone type: a plain one by reading it, String and the containers by their own clone, and a struct or enum of clone fields by a copy the compiler derives, field by field. A resource type — one with a destructor — declares its own T::clone or has none, because only it knows how to copy what it manages. Generic code says what it needs with the bound:

import std;

struct Person
{
    String name;                     // Person is clone: every field is
    u32 age;
}

enum Shape
{
    Dot,
    Labelled(String),                // Shape is clone too
}

resource struct Ticket
{
    u32 id;
}

fn Ticket::drop(ref<Ticket, exclusive> self)
{
}

fn Ticket::clone(ref<Ticket, shared> self) : Ticket   // a resource says how it is copied
{
    Ticket { .id = self.id + 1000 }
}

fn pair_up<T: clone>(ref<T, shared> x) : Vec<T>     // needs T: clone to call clone(x)
{
    Vec<T> v = Vec::new();
    Vec::push(&mut v, clone(x));
    Vec::push(&mut v, clone(x));
    v
}

fn main()
{
    Person a = Person { .name = "Ada", .age = 36 };
    Person b = clone(&a);                              // derived: name copied, age copied
    String::push_ascii(&mut b.name, b'!');
    assert(String::eq_str(&a.name, "Ada") && String::eq_str(&b.name, "Ada!"));
    Shape s = Labelled(String::from_str("x"));
    Shape s2 = clone(&s);
    Vec<Person> people = pair_up(&a);
    Vec<String> names = Vec::from_fn(2, [](usize i) : String { sprintf("n%d", i) });
    Vec<String> copy = Vec::clone(&names);              // Vec::clone needs T: clone; String is
    Ticket t = Ticket { .id = 1 };
    Vec<Ticket> tickets = Vec::filled(2, clone(&t));    // Ticket::clone, three times
    assert(Vec::len(&people) == 2 && Vec::len(&copy) == 2 && tickets[1].id == 2001);
}

Inference is local and downward. A type parameter is found from, in order: an explicit type argument (identity<i64>(5)), the type of an argument in the same call, or the expected type where the call appears (a declared variable type, a parameter type, a field type). An unsuffixed literal argument comes last: it takes the type the other arguments or the expected type give its parameter, so with i64 x, pick(true, 0, x) makes T an i64 and the 0 with it; only when nothing else fixes T does a literal's own default (i32, f64) decide. Nothing is ever inferred from how a value is used later, so a call that fixes nothing is rejected:

import std;

fn main()
{
    auto v = Vec::new();              // ✗ diag.cannot-infer-type-parameter: nothing says what T is
    Vec::push(&mut v, 1);             //   (a later use does not count)
}

The same holds when the call is an argument to another generic call. Mutex::new<T> is one: with auto nothing reaches it, so nothing reaches the Vec::new() inside it either. Give the outer binding its type and both are fixed.

import std;

fn main()
{
    mutex<Vec<u8>> m = Mutex::new(Vec::new());   // T of Mutex::new, then T of Vec::new, from the declaration
    mutex<i64> big = Mutex::new(5000000000);     // and the literal is an i64 for the same reason
    assert(Vec::len(&*lock(&m)) == 0);
}

import std;

fn main()
{
    auto m = Mutex::new(Vec::new());  // ✗ diag.cannot-infer-type-parameter: nothing fixes Vec's T
}

import std;

struct Box<T>
{
    T value;
}

fn identity<T>(T x) : T
{
    x
}

fn pick<T>(bool first, T a, T b) : T
{
    if (first) { a } else { b }
}

fn main()
{
    Vec<i32> a = Vec::new();                  // T from the declaration
    Box<Vec<u8>> c = Box { .value = Vec::new() };   // both T's from the declared type
    Vec::push(&mut c.value, 200);             // the literal becomes u8 from the field type
    assert(Vec::len(&c.value) == 1);
    assert(Vec::len(&a) == 0);
    i64 w = identity<i64>(3);                 // explicit: name<Type>(...)
    assert(w == 3);
    i64 big = 5000000000;
    Vec<i64> both = Vec::new();
    Vec::push(&mut both, pick(true, 0, big)); // T from big; the 0 is an i64
    assert(both[0] == 0);
}

auto and the expected type

auto x = e; gives x the type of e. Since inference is downward only, auto works whenever e has a type of its own: a literal (i32/f64 by default), an arithmetic expression, a call whose type parameters are already fixed, a struct literal with a concrete type. Where e needs help (Vec::new()), write the type on the left instead: auto m = Mutex::new(HashMap::new()); cannot know the map's types, but mutex<HashMap<String, i64>> m = Mutex::new(HashMap::new()); can. The branches of an if or match share one type, and a branch that is only a literal takes it from the others: in auto n = if (big) { count } else { 0 }; with count : i64, the 0 is an i64.

import std;

fn main()
{
    i64 count = 5000000000;
    auto n = if (count > 10) { count } else { 0 };     // 0 : i64, from the other branch
    Option<i64> o = None;
    auto m = match (o) { None : -1, Some(v) : v };     // -1 : i64, from the Some arm
    assert(n + m == 4999999999);
    mutex<HashMap<String, i64>> totals = Mutex::new(HashMap::new());   // the declaration fixes K and V
    assert(HashMap::len(&*lock(&totals)) == 0);
}

§13Expressions

Places versus values, strict left-to-right evaluation, and the operators.

CobaltC has a small expression language with a fixed evaluation order and a clear line between places (things you can assign to or borrow) and values. Almost everything is an expression, including blocks, if and match, which is what lets you write i32 x = if (c) { 1 } else { 2 };.

Places and values

A place is a variable name, a field access e.f, an index e[i], or a dereference *r. A place can be read (yielding its value), written (place = e), borrowed (&place, &mut place), or projected further. Everything else, such as a literal, an arithmetic result, a call result or a struct literal, is a value or a temporary. Reading a place that holds a resource is not allowed (that would copy the resource, §07); such a place may only be moved, borrowed, or destructured.

import std;

struct Pair
{
    i32 a;
    array<i32, 3> items;
}

fn main()
{
    Pair p = Pair { .a = 1, .items = [10, 20, 30] };
    p.a = 99;                         // a field is a place
    p.items[1] = 200;                 // so is an element
    {
        auto r = &mut p.items[2];
        *r = 300;                     // and so is *r
    }
    assert(p.a == 99);
    assert(p.items[1] == 200);
    assert(p.items[2] == 300);
}

Evaluation order

Every expression is evaluated strictly left to right: the left operand before the right, the callee before its arguments, arguments in written order, struct-literal fields in written order. Assignment evaluates the target place first, then the value. && and || short-circuit: the right operand runs only when needed.

import std;

fn bump(ref<i32, exclusive> counter) : i32
{
    *counter += 1;
    *counter
}

fn main()
{
    i32 n = 0;
    i32 left = bump(&mut n);
    i32 right = bump(&mut n);
    assert(left == 1);                 // the first call ran first
    assert(right == 2);
    bool touched = false;
    if (true || bump(&mut n) == 0)    // the right side is never evaluated
    {
        touched = true;
    }
    assert(touched);
    assert(n == 2);
}

Expressions that produce values

import std;

fn main()
{
    bool c = true;
    i32 x = if (c)                            // if is an expression; both arms must have one type
    {
        1
    }
    else
    {
        2
    };
    i32 y =                                   // a block's value is its trailing expression
    {
        i32 t = x * 3;
        t + 1
    };
    Option<i32> o = Some(x);
    i32 z = match (o)                         // so is match
    {
        Some(v) : v * 10,
        None    : 0,
    };
    assert(x == 1);
    assert(y == 4);
    assert(z == 10);
    i32 w = 0;
    w = 5;                                    // assignment is an expression of type void
    assert(w == 5);
}

Operator precedence

From tightest to loosest binding. Comparison is non-associative: a < b < c is a syntax error, and a < b == c needs parentheses.

x op= e is x = x op e with x evaluated once: the same types, the same overflow check (x += 1 can overflow), the same write rules. Evaluating the place once matters only when it contains a call, as in *Vec::index_exclusive(&mut v, i) += 1, which calls index_exclusive once. There is no ++ or --; write += 1.

§14Control flow and scopes

Blocks, if, while, for, foreach, break and continue; scope exit as the moment of destruction; and the fixed line between compile-time and run-time checks.

Control flow is C's if, while and for, without switch and goto, plus expression-valued if and match and a foreach over collections. What is new is how carefully the language ties scope to destruction, and the precise line between what the compiler proves and what the run time checks.

Blocks and scopes

A block { … } opens a scope. Variables declared in it die when it ends, in reverse order; resources are destroyed at that point (§07); references held by those variables end too. A block is an expression: its value is its trailing expression, or () if there is none. Every statement is a scope of its own for temporaries: a value created during a statement and not stored anywhere is destroyed at the semicolon.

if and else

if (cond) { … } else { … } with mandatory parentheses and mandatory braces. else if chains as expected. An if without else has type void; an if used as a value needs both arms, of the same type.

The condition may also be a pattern test, if (Some(x) = e) { … } else { … }: it means match (e) { Some(x) : { … }, _ : { … } }, so x exists in the first block only, e is consumed exactly as that match would consume it, and the whole if can be a value. Any match pattern works — nested (Ok(Some(l))), a literal (if (0 = n)), a qualified variant — as long as it can fail: a bare name on the left of = is the assignment it always is, which is not a bool and is rejected, so if (x = e) never silently tests anything. A match stays the form when both cases do work, and the only form that checks every case is handled.

import std;

fn main()
{
    HashMap<String, i32> ages = HashMap::new();
    HashMap::insert(&mut ages, String::from_str("Ada"), 36);
    if (Some(a) = HashMap::get_str(&ages, "Ada"))
    {
        assert(*a == 36);             // a: ref<i32, shared>, in scope here only
    }
    Option<i32> o = Some(4);
    i32 doubled = if (Some(x) = o) { x * 2 } else { 0 };
    assert(doubled == 8);
    Result<Option<i32>, str> r = Ok(Some(7));
    if (Ok(Some(n)) = r) { assert(n == 7); } else { assert(false); }
    if (Err(_) = r) { assert(false); }
}

while, for, break, continue

while (cond) { … } loops while cond holds; for (init; cond; step) { … } is C's counted loop: init runs once (a declaration there belongs to the loop), cond is tested before each iteration, and step runs after each one. Any of the three may be left out; a missing cond is true, so for (;;) loops until a break. The body is a fresh scope each iteration, so anything declared inside it is destroyed before the next test. break exits the innermost loop; continue goes to its next iteration, running a for's step first. Both are typed never and must appear inside a loop. A body is always a block, so C's trap for (…); (an empty loop, then a block that runs once) is a syntax error here, and the message says to remove the ;.

A while condition may be a pattern test too: while (Some(x) = e) { … } is while (true) { match (e) { Some(x) : { … }, _ : break } } — e is evaluated again each time round, the body runs with x bound while the pattern matches, and the first value that does not match ends the loop. That last point matters for a Result: while (Ok(Some(line)) = read_line()) stops at the end of input and on a read error alike, which is the loop's written decision; a loop that must tell them apart keeps the match.

import std;

fn main()
{
    Vec<String> stack = Vec::from_fn(3, [](usize i) : String { sprintf("job %d", i) });
    usize done = 0;
    while (Some(job) = Vec::pop(&mut stack))     // each job moved out, destroyed at the body's end
    {
        if (String::ends_with(&job, "1")) { continue; }
        done += 1;
    }
    assert(done == 2 && Vec::len(&stack) == 0);
    u32 n = 10;
    while (Some(m) = checked_sub(n, 3))          // stops when the subtraction would go below zero
    {
        n = m;
    }
    assert(n == 1);
}

import std;

fn main()
{
    i32 sum = 0;
    i32 i = 0;
    while (i < 10)
    {
        i += 1;
        if (i == 3)
        {
            continue;                 // skip 3
        }
        if (i == 7)
        {
            break;                    // stop before adding 7
        }
        sum += i;
    }
    assert(sum == 1 + 2 + 4 + 5 + 6);
    Vec<i32> v = Vec::new();
    Vec::push(&mut v, 4);
    Vec::push(&mut v, 9);
    i32 total = 0;
    for (usize k = 0; k < Vec::len(&v); k += 1)   // an index loop; foreach (below) is shorter
    {
        total += v[k];
    }
    assert(total == 13);
    u32 odd = 0;
    for (u32 j = 0; j < 10; j += 1)
    {
        if (j % 2 == 0)
        {
            continue;                 // still runs j += 1
        }
        odd += j;
    }
    assert(odd == 25);
}

fn main()
{
    break;                            // ✗ diag.break-outside-loop
}

Loops that only end by returning. A while (true) that no break leaves can end only by return, a fault or exit, so nothing after it ever runs: its type is never, like return's (D-0175). A function may therefore end with such a loop and needs no value after it. A break inside a nested loop leaves only that loop and does not count; a break that leaves the while (true) itself makes it an ordinary loop again, after which the function must still give its value. Only the literal true has this meaning: the compiler does not look into a condition that merely happens to stay true. There is no separate loop keyword; while (true) is the way to say "forever".

import std;

// The first line that starts with `#`, read until one does; no value is
// needed after the loop, because nothing after it can run.
fn first_comment(ref<Vec<String>, shared> lines) : usize
{
    usize i = 0;
    while (true)
    {
        if (String::starts_with(&lines[i], "#"))
        {
            return i;
        }
        i += 1;
    }
}

fn main()
{
    Vec<String> lines = Vec::new();
    Vec::push(&mut lines, String::from_str("x = 1"));
    Vec::push(&mut lines, String::from_str("# note"));
    printf("line %v\n", first_comment(&lines));
}

line 1

foreach

foreach (x in c) { … } visits every element of a Vec, an array, a slice, a HashSet or a HashMap, in order: by index for a Vec or an array, in insertion order for a set or a map. How the loop holds the collection is written at the loop, the same three ways a function takes a value:

Use &c most of the time. A second name gives the position: foreach (i, x in &v) has i : usize. A HashMap is always looped over with two names, the key and the value: foreach (k, v in &m), or three to have the position too, foreach (i, k, v in &m). printf prints what a reference refers to, so printf("%d", x) works with x a ref<i32, shared>; elsewhere write *x for the number.

import std;

fn shout(String s)                    // takes ownership
{
    printf("%s!\n", &s);
}

fn main()
{
    Vec<String> names = Vec::new();
    Vec::push(&mut names, String::from_str("ada"));
    Vec::push(&mut names, String::from_str("lin"));
    foreach (i, name in &names)       // read: names is still usable afterwards
    {
        printf("%d: %s\n", i, name);
    }

    Vec<i32> numbers = Vec::new();
    Vec::push(&mut numbers, 3);
    Vec::push(&mut numbers, 5);
    foreach (n in &mut numbers)       // change in place
    {
        *n *= 2;
    }
    foreach (n in &numbers)
    {
        printf("%d ", n);             // printf reads through the reference
    }
    printf("\n");

    HashMap<str, u32> stock = HashMap::new();
    HashMap::insert(&mut stock, "pens", 12);
    HashMap::insert(&mut stock, "ink", 3);
    foreach (item, count in &stock)
    {
        printf("%-5s %2d\n", item, count);
    }

    foreach (name in names)           // consume: each String moves into shout
    {
        shout(name);
    }
    // names is gone here; using it would be diag.stale-binding
}

0: ada
1: lin
6 10 
pens  12
ink    3
ada!
lin!

The loop's borrow of the collection lasts the whole loop, so a body that tries to change the collection itself (push to it, clear it) is rejected before the program runs, the same aliasing rule as anywhere else. There is no iterator invalidation to debug. A consuming loop left early, by break, return or a fault, destroys the elements it had not reached, exactly once.

import std;

fn main()
{
    Vec<i32> v = Vec::new();
    Vec::push(&mut v, 1);
    foreach (x in &v)
    {
        Vec::push(&mut v, *x);        // ✗ diag.aliasing-conflict (static): v is borrowed by the loop
    }
}

An array of plain values, such as array<i32, 5>, is copied by the by-value form: foreach (i, e in arr) walks a copy, so arr is neither borrowed nor used up, a write to arr[j] in the body is allowed (and not seen by e), and arr is still there afterwards. To change the elements themselves, loop over &mut arr and write through the reference: *e = …. While that loop runs, arr is borrowed by it, so reach the elements through e, not through arr[j].

import std;

fn main()
{
    array<i32, 5> arr = [0, 0, 0, 0, 0];

    foreach (i, e in &mut arr)
    {
        *e = narrow<i32>(i) * 10;       // write through the element's reference
    }
    arr[4] += 1;                        // direct indexing works too, outside the loop

    foreach (i, e in &arr)
    {
        printf("[%v] = %v\n", i, *e);
    }
}

[0] = 0
[1] = 10
[2] = 20
[3] = 30
[4] = 41

Counting with a range

foreach (x in lo..hi) counts from lo up to, not including, hi, the same way &a[lo..hi] takes elements lo up to hi. So 0..n runs exactly n times, and 1..10 stops at 9. A second name gives the position, counted from 0: foreach (i, x in lo..hi). Both bounds are evaluated once, lo first. If hi is not above lo, the body never runs.

x has the bounds' integer type. A plain number takes the other bound's type, so with u8 top, 0..top counts in u8. Two plain numbers are usize, so the counter can index an array or a Vec directly; for a negative range, give one bound a type: -3..0: i32. Bounds of two different types are rejected rather than converted. A range can end at its type's largest value without overflowing, because the counter never passes hi.

import std;

fn main()
{
    foreach (v in 1..10)
    {
        printf("%v ", v);
    }
    printf("\n");

    auto names = ["ada", "lin", "kay"];
    foreach (i in 0..3)                        // i : usize, so it can index
    {
        printf("%v: %v\n", i, names[i]);
    }

    u8 top = 255;
    foreach (i, b in 253..top)                // b : u8; i is the position
    {
        printf("step %v is %v\n", i, b);
    }
}

1 2 3 4 5 6 7 8 9 
0: ada
1: lin
2: kay
step 0 is 253
step 1 is 254

A range to count over is written only in a foreach (a slice's lo..hi, §16, is the same notation for elements). It is not a value you can store, and it has no inclusive form or step. To count down or in steps, use a for loop.

Early exit and unwinding

return, break, continue, and a run-time fault all leave scopes the same way: every statement scope and block between here and the target is exited in order, destroying what each one owns. A return e first moves e out so it survives the unwinding. You never have to write cleanup code on an early exit.

What is checked when

Many rules in this guide say a program is "rejected" in one example and "faults at run time" in another. The boundary is fixed by the language, not left to the compiler's cleverness, so that every implementation accepts and rejects the same programs. A compiler may prove more than this checker does and leave out the run-time checks it has proved unnecessary (that is what cobc does; see the performance chapter), but it may not accept a program the language rejects or reject one it accepts: coby --check is the reference, and what it accepts is the language. Within one function body, the checker tracks a few facts about each variable: whether it has been moved from, whether it has been initialised, which references were visibly borrowed from it, and whether a reference to it has been handed somewhere the checker cannot follow (a call, a field, a thread). At each checked operation the outcome is one of three:

The analysis looks only at the current function and only at literals for value ranges. So 2147483647 + 1 is refuted statically, add(2147483647, 1) is checked when add runs, and borrowing x twice exclusively in one function is refuted while doing so through two reference parameters is checked at the use. Three exceptions are stricter: definite assignment (§11), a use of a variable that may have been moved (§7), and reference escape (§10) reject on "unknown" rather than deferring.

§15Functions and closures

Signatures that state the whole contract, associated functions, function values, and closures with checked capture lists.

Functions in CobaltC carry their whole contract in the signature. A parameter's type says whether the function takes ownership, may only look, or may modify. Closures are ordinary structs that capture what they use, and the capture list is checked, not trusted.

Declaring and calling

import std;

// Parameters are type-first; the return type follows a colon.
fn area(i32 w, i32 h) : i32
{
    w * h                             // the trailing expression is the result
}

// No return type means void; `return;` leaves early.
fn clamp_in_place(ref<i32, exclusive> x, i32 hi)
{
    if (*x <= hi)
    {
        return;
    }
    *x = hi;
}

// An associated function: a plain function whose name is qualified by a type.
struct Rect
{
    i32 w;
    i32 h;
}

fn Rect::square(i32 side) : Rect
{
    Rect { .w = side, .h = side }
}

fn Rect::area(ref<Rect, shared> r) : i32
{
    area(r.w, r.h)
}

fn fact(i32 n) : i32
{
    if (n <= 1)                       // recursion needs nothing special
    {
        1
    }
    else
    {
        n * fact(n - 1)
    }
}

fn main()
{
    i32 v = 50;
    clamp_in_place(&mut v, 10);
    assert(v == 10);
    auto sq = Rect::square(4);
    assert(Rect::area(&sq) == 16);     // called by qualified name; there is no method syntax
    assert(fact(5) == 120);
}

Recursion needs nothing special, and its depth is limited only by the stack. Every implementation allows at least 10 000 nested calls, and both tools allow far more: they run a program and each of its threads on a large stack. A call beyond the limit is not a crash but a fault at the call, diag.stack-exhausted, so a recursion that runs away ends with a diagnostic like any other failure.

A parameter list and an argument list may end with a comma, as array and struct literals may: handy when a long call is split one argument per line. A comma is never the whole list: f(,) is a syntax error.

import std;

fn span(
    i32 from,
    i32 to,
) : i32
{
    to - from
}

fn main()
{
    assert(span(
        3,
        10,
    ) == 7);
}

What a parameter type promises

Function values

A function type is written fn(T1, T2) : R (or fn(T1) for a void result). A parameter of that type accepts a function with that signature, or a closure with the same parameters and result. Function values cannot be compared.

A closure's type is fn(parameters) : result, the result being what its body gives. Where a fn type is expected, as when a closure is declared fn(u32) : u32 f = … or passed to such a parameter, the body is checked against that result, and its literals take that type. A closure declared with auto takes its body's own type: [](u32 x) { 1 } gives an i32, as auto y = 1 does. A closure can be stored like any value: in a variable, a field, a Vec<fn(…) : …> or a Box, and called from there.

A function value owns the closure it holds and destroys it when it ends. Copying the value (g = f, passing it by value) copies the closure with its captures, so each copy keeps its own state. The one exception is a closure that owns a resource, such as a move closure that captured a String: copying it would duplicate the resource, so it moves instead, and the value it came from is left empty. Calling an empty function value is diag.stale-binding; the function type does not say what its closure owns, so this is found when the program runs. Calling through a reference, a field or an element ((*f)(x), (t.run)(), (fs[i])()) calls the value where it is and moves nothing.

Closures

Functions do not nest: a fn declared inside another function is a syntax error, unless it is a function of a type declared in the same block (fn T::name, §16). A function needed only inside another is written there as a closure, which can also use the variables around it.

A closure is written [captures](params) { body }, in the style of a C++ lambda. The bracket must list exactly the outer variables the body uses, no more and no fewer; it is documentation that the compiler checks (diag.capture-list-mismatch). How each variable is captured is decided by the body, not the list: a variable the body only reads is captured by shared reference; one the body writes, borrows exclusively, or moves is captured by exclusive reference. Prefix move to capture by value instead, moving resources into the closure. The result type is taken from the body, or from the fn(…) : R the closure is passed as; write it after the parameters, as for a function, when neither says enough: [](i64 a) : i64 { 0 }.

import std;

fn main()
{
    auto zero = [](i64 a) : i64 { 0 };        // without `: i64` the 0 would be an i32
    auto small = [](u8 a) : bool { a < 10 };
    assert(zero(5000000000) == 0 && small(3));
}

import std;

fn apply(fn(i32) : i32 f, i32 x) : i32
{
    f(x)
}

fn main()
{
    i32 k = 10;
    auto add_k = [k](i32 x)           // k is read only: captured as ref<i32, shared>
    {
        x + k
    };
    assert(add_k(5) == 15);
    assert(apply(add_k, 4) == 14);     // a closure where a fn(i32) : i32 is expected

    Vec<i32> v = Vec::new();
    Vec::push(&mut v, 7);
    auto reader = move [v]()          // v moves into the closure; the closure owns it now
    {
        v[0]
    };
    assert(reader() == 7);
    assert(reader() == 7);             // calling twice is fine: nothing is consumed
}                                     // reader is destroyed here, and its Vec with it

fn main()
{
    i32 x = 1;
    i32 unused = 2;
    auto f = [x, unused]()            // ✗ diag.capture-list-mismatch: unused is not used by the body
    {
        x
    };
    f();
}

A closure that captures by reference holds those borrows for as long as the closure object lives, so the captured variables are subject to the usual aliasing rules until it goes out of scope: a closure that writes total blocks every other use of total while it exists. Put such closures in a block, or use move. Calling a closure borrows it shared for the call: its writes go through the captures, which are checked as any reference is, so a closure that writes a capture cannot be called through a shared reference to it.

fn main()
{
    i32 total = 0;
    {
        auto add = [total](i32 x)     // the body writes total: captured as ref<i32, exclusive>
        {
            total += x;
        };
        add(5);
        add(7);
    }                                 // add ends here and releases its borrow of total
    i32 seen = total;                 // ✓ 12: no borrow remains
}

Generic functions

fn name<T>(...) declares type parameters; see §12 for what a body may do with T and how T is inferred at each call.

main

A program is a set of declarations with exactly one main at the top level, taking no parameters: fn main(), or fn main() : u8. Execution is the evaluation of main(); the program's observable behaviour is its termination outcome (success or a named fault) plus the sequence of extern calls it makes.

A main that returns a u8 sets the program's exit status; fn main() exits with 0. Returning from main runs every destructor still pending and waits for every thread, as leaving any block does, so the status is reported only after all of that. A fault still ends the program with its diagnostic instead. The arguments the program was started with come from arg_count() and arg(i) (§21); argument 0 is the first one after the program, not the program's name.

import std;

fn main() : u8
{
    if (arg_count() != 1)
    {
        printf("usage: greet NAME\n");
        return 2;                     // exit status 2
    }
    match (arg(0))
    {
        Ok(name) :
        {
            printf("hello, %v\n", &name);
            0
        },
        Err(_)   :
        {
            printf("the name is not UTF-8\n");
            1
        },
    }
}

hello, Ada

Run with no argument, the same program prints its usage line and exits with status 2. A main with parameters, or returning anything other than u8, is rejected with diag.no-main.

§16Structs, arrays, enums and match

The four aggregate kinds, how they nest, and exhaustive matching over enums with payloads.

CobaltC has four aggregate kinds: structs (named fields), bitstructs (named runs of bits packed into one unsigned integer), arrays (a fixed number of elements) and enums (one of several variants, each with an optional payload). They compose freely, and all but bitstructs generically. match is how you take an enum apart, and it must handle every variant.

Structs

import std;

struct Point
{
    i32 x;
    i32 y;
}

struct Segment
{
    Point from;                       // structs nest by value
    Point to;
}

fn main()
{
    auto a = Point { .x = 1, .y = 2 };           // every field, once, in any order
    Point b = Point { .y = 2, .x = 1 };
    assert(a == b);                                // plain structs compare field by field
    auto s = Segment { .from = a, .to = Point { .x = 4, .y = 6 } };
    s.to.y = 7;                                   // nested fields are places
    assert(s.to.y == 7);
    Point c = a;                                  // plain structs copy
    c.x = 100;
    assert(a.x == 1);
}

Field initialisers use C99's designated form .name = value. Fields are private to the module that declares the struct unless marked export (§17). A struct with no fields is allowed. Mark a struct resource if it manages something beyond its fields (§07).

bitstruct: named bits of one integer

A bitstruct is a struct whose fields are runs of bits of one unsigned integer, its backing type: bitstruct Instr : u32 { op : 6; rd : 5; rs : 5; imm : 16; }. The fields are laid out from the low bit up in declaration order and must fill the backing type exactly (name the unused bits, pad : 3;). Each field has the smallest unsigned type that holds its width — u8 up to 8 bits, u16 up to 16, and so on — and is read and written like any field, i.op, i.imm = 500. A write that does not fit its field faults with diag.narrowing-overflow, or is rejected outright when the value is a literal; nothing is ever truncated. Instr::bits(i) is the whole integer and Instr::from_bits(w) the fields of one, both total. A bitstruct is a plain value: copied by a read, clone, equal by its bits, a HashMap key, and its bytes in raw memory are the integer's. A field has no address of its own, so it cannot be borrowed — borrow the whole value — and a bitstruct is not taken apart by destructuring. Byte order is not its concern: Vec::push_le and push_be write it out (D-0119), and an unsafe extern fn takes Instr::bits(i).

import std;

bitstruct Double : u64
{
    mantissa : 52;                    // bits 0 .. 52
    exponent : 11;                    // bits 52 .. 63
    sign     : 1;                     // bit 63
}

bitstruct Instr : u32
{
    op  : 6;
    rd  : 5;
    rs  : 5;
    imm : 16;
}

fn main()
{
    Double d = Double::from_bits(reinterpret<u64>(-2.5));
    assert(d.sign == 1 && d.exponent == 1024);           // exponent: u16, sign: u8
    d.exponent = 1023;                                    // fits in 11 bits: checked
    assert(reinterpret<f64>(Double::bits(d)) == -1.25);

    Instr i = Instr { .op = 3, .rd = 1, .rs = 2, .imm = 500 };
    u32 word = Instr::bits(i);
    assert(word == 3 | 1 << 6 | 2 << 11 | 500 << 16);
    Instr j = Instr::from_bits(word);
    assert(j == i && sizeof<Instr>() == 4);
    j.imm = 65535;                                        // the largest 16-bit value
    assert(j.imm == 65535 && j.op == 3);
}

import std;

bitstruct Flags : u8 { carry : 1; zero : 1; pad : 6; }

fn main()
{
    Flags f = Flags { .carry = 2, .zero = 0, .pad = 0 };  // ✗ 2 does not fit 1 bit: diag.narrowing-overflow
}

Arrays

array<T, N> holds exactly N elements; N is a constant expression — a literal, a const name (m::N too), or + - * / % & | ^ << >> ~ ( ) over them, folded before the program runs (D-0126); outside parentheses > ends it, so Vec<array<u8, N * 2>> reads as expected. The literal form is [a, b, c]. Indexing takes a usize and is bounds-checked: a literal index out of range is rejected statically, a computed one faults at run time with diag.index-out-of-bounds. Arrays of plain elements are plain (copied on assignment); an array of resources is a resource.

import std;

fn sum(ref<array<i32, 4>, shared> a) : i32
{
    i32 t = 0;
    foreach (i in 0..4)
    {
        t += a[i];                    // indexing looks through the reference
    }
    t
}

fn main()
{
    array<i32, 4> a = [10, 20, 30, 40];
    a[2] = 33;
    assert(sum(&a) == 103);
    auto grid = [[1, 2], [3, 4]];     // array<array<i32, 2>, 2>
    assert(grid[1][0] == 3);
    array<u32, 256> counts = [0; 256];    // one value in every element
    counts[65] += 1;
    auto flags = [false; 8];          // array<bool, 8>
    array<str, 3> names = [
        "ann",
        "bo",
        "cy",                         // a trailing comma is allowed
    ];
    assert(counts[65] == 1 && !flags[7] && names[2] == "cy");
}

[v; N] makes an array of N copies of v, which is evaluated once. N is written as in the type array<T, N>, a constant expression: a number, a constant (const usize W = 24; then array<u8, W> and [0; W], in this module or, qualified, a visible one of another, array<u8, screen::W>), or arithmetic on them ([0; W * 2]). Because the value is copied, its type must be plain: a String or other resource, a reference, or a function value cannot be repeated (diag.read-of-resource or diag.type-mismatch); build such arrays element by element, or use a Vec.

fn get(array<i32, 3> a, usize i) : i32
{
    a[i]                              // checked against 3 when the index arrives
}

fn main()
{
    array<i32, 3> a = [1, 2, 3];
    get(a, 3);                        // ✗ diag.index-out-of-bounds (dynamic)
}

Arrays of arrays

CobaltC has no separate multidimensional array type. An array's element can itself be an array, so a grid, a cube, or anything with more dimensions is the one constructor used again: array<array<i64, 3>, 2> is an array of 2 elements, each an array<i64, 3>. The same holds for the literal forms, [[1, 2, 3], [4, 5, 6]] and [[0; 3]; 2], and for auto, which infers the nesting from the literal.

Two directions are worth keeping straight:

• The type reads from the inside out. In array<array<array<i64, 3>, 2>, 4> the innermost array<i64, 3> is a row of 3 numbers, the next array<…, 2> holds 2 such rows (a block), and the outermost array<…, 4> holds 4 blocks. The length written last is the outermost one.
• Indexing and loops go from the outside in. cube[i][j][k] picks block i (below 4), then row j of it (below 2), then element k of that row (below 3). Nested loops follow the same order: the outer loop walks the blocks, the innermost the elements of one row, so the elements are visited in the order they lie in memory.

Each index is checked against its own length. Because every level is an ordinary array, cube[1] is a whole block and cube[1][0] a whole row, values you can copy, pass and loop over. Writing those inner types out gets long; where the type is clear from the right-hand side, auto reads better. To print every value, nest one foreach per level: foreach (i, block in &cube) borrows each block, and the loop inside it over block borrows each row of that block, so nothing is copied.

import std;

fn main()
{
    // Read the type from the inside out: rows of 3 i64s, 2 rows to a
    // block, 4 blocks.
    array<array<array<i64, 3>, 2>, 4> cube = [[[0; 3]; 2]; 4];
    // Index from the outside in: cube[block][row][column].
    foreach (i in 0..4)
    {
        foreach (j in 0..2)
        {
            foreach (k in 0..3)
            {
                cube[i][j][k] = narrow<i64>(100 * i + 10 * j + k);
            }
        }
    }
    printf("cube[3][1][2] = %v\n", cube[3][1][2]);
    // Print every value: each loop borrows one level of the one outside it.
    foreach (i, block in &cube)
    {
        foreach (j, row in block)
        {
            printf("cube[%v][%v]:", i, j);
            foreach (x in row)
            {
                printf(" %v", x);
            }
            printf("\n");
        }
    }
    // `auto` spares spelling the inner types; each is a copy (the elements are plain).
    auto block = cube[1];             // array<array<i64, 3>, 2>
    auto row = block[0];              // array<i64, 3>
    auto grid = [[1, 2, 3], [4, 5, 6]];    // array<array<i32, 3>, 2>
    printf("row %v %v %v, grid[1][2] = %v\n", row[0], row[1], row[2], grid[1][2]);
}

cube[3][1][2] = 312
cube[0][0]: 0 1 2
cube[0][1]: 10 11 12
cube[1][0]: 100 101 102
cube[1][1]: 110 111 112
cube[2][0]: 200 201 202
cube[2][1]: 210 211 212
cube[3][0]: 300 301 302
cube[3][1]: 310 311 312
row 100 101 102, grid[1][2] = 6

For a growable sequence use Vec<T> (§21). A Vec is indexed the same way, v[i]: it reads through Vec::index_shared, and writes (an assignment, &mut v[i]) through Vec::index_exclusive, so every rule about borrowing the Vec applies.

Slices

A slice is a borrowed run of consecutive elements of an array, a Vec, or another slice: &a[i..j] is elements i up to (not including) j, and &mut a[i..j] the same for writing. Inside the brackets, $ stands for the length of what is being indexed, so &a[0..$] is all of it and &a[$ - 3 .. $] the last three, and v[$ - 1] is a Vec's last element. $ is a usize like any index, so v[$ - 1] of an empty v is an overflow fault, never a wrapped-around index.

The type is slice<T, shared> or slice<T, exclusive>. One parameter of that type takes any array, any Vec, or part of either, so a function need not be written once per container or per array length. slice_len(s) is its length; s[i] is bounds-checked; foreach works over it. A slice is a borrow like a reference: while it lives, the elements it views cannot be changed except through it, its source cannot be pushed to or popped from, and a slice of a local cannot be returned.

import std;

// Sorts any run of i32 in place: an array, a Vec, or part of one.
fn sort(slice<i32, exclusive> s)
{
    for (usize i = 1; i < slice_len(s); i += 1)
    {
        usize j = i;
        while (j > 0 && s[j - 1] > s[j])
        {
            i32 t = s[j - 1];
            s[j - 1] = s[j];
            s[j] = t;
            j -= 1;
        }
    }
}

fn sum(slice<i32, shared> s) : i32
{
    i32 total = 0;
    foreach (x in s)
    {
        total += *x;
    }
    total
}

fn main()
{
    auto a = [5, 3, 9, 1, 7, 2];
    sort(&mut a[0..3]);                     // only the first three: [3, 5, 9, 1, 7, 2]
    assert(a[0] == 3 && a[3] == 1);
    assert(sum(&a[$ - 3 .. $]) == 10);       // the last three

    Vec<i32> v = Vec::new();
    foreach (x in [40, 10, 30, 20])
    {
        Vec::push(&mut v, x);
    }
    sort(&mut v[0..$]);                     // the same function, on a Vec
    assert(v[0] == 10 && v[$ - 1] == 40);
    v[0] += 1;                              // indexing a Vec, written
    assert(sum(&v[0..$]) == 101);
}

import std;

fn main()
{
    Vec<i32> v = Vec::new();
    Vec::push(&mut v, 1);
    auto s = &v[0..1];
    Vec::push(&mut v, 2);             // ✗ diag.aliasing-conflict: s still borrows v
    i32 first = s[0];                 // (because s is used here)
}

A slice borrows only its own elements. Two slices of one array or Vec conflict only if their ranges share an element, so a buffer can be split into parts that are each written through their own exclusive slice, at the same time: the halves of a divide-and-conquer algorithm, or one part per thread. What reaches the whole source (&mut v, Vec::push) still conflicts with every live slice of it.

import std;

fn sum_into(slice<u64, exclusive> s, u64 start) : u64
{
    u64 total = 0;
    foreach (i in 0..slice_len(s))
    {
        s[i] = start + widen<u64>(i);
        total += s[i];
    }
    total
}

fn main()
{
    Vec<u64> v = Vec::new();
    for (usize i = 0; i < 100; i += 1)
    {
        Vec::push(&mut v, 0);
    }
    usize mid = slice_len(&v[0 .. $]) / 2;
    {
        slice<u64, exclusive> left = &mut v[0 .. mid];     // elements 0 .. 50
        slice<u64, exclusive> right = &mut v[mid .. $];    // elements 50 .. 100: disjoint
        auto a = spawn(sum_into, left, 0: u64);           // each half filled by its own thread
        auto b = spawn(sum_into, right, 1000: u64);
        assert(join(a) + join(b) == 1225 + 51225);
    }
    assert(v[49] == 49 && v[50] == 1000);
}

Types declared inside a function

A struct, enum or bitstruct used by one function can be declared inside it, as a statement, and so can its functions, fn T::name(…) (a destructor too). It is an ordinary type whose name is scoped like a local: usable from its declaration to the end of its block. Two functions can each have their own Entry. A local type and its functions see module items and the local types and constants around them, but not the function's variables or type parameters; a plain local function is written as a closure (§15).

import std;

fn shortest(ref<Vec<String>, shared> words) : usize
{
    struct Entry                      // visible only in this function
    {
        usize len;
        usize at;
    }

    fn Entry::better(ref<Entry, shared> a, ref<Entry, shared> b) : bool
    {
        a.len < b.len || (a.len == b.len && a.at < b.at)
    }

    Entry best = Entry { .len = max_value<usize>(), .at = 0 };
    foreach (i, w in words)
    {
        Entry e = Entry { .len = String::len(w), .at = i };
        if (Entry::better(&e, &best))
        {
            best = e;
        }
    }
    best.at
}

fn main()
{
    Vec<String> w = Vec::new();
    Vec::push(&mut w, String::from_str("banana"));
    Vec::push(&mut w, String::from_str("fig"));
    Vec::push(&mut w, String::from_str("pea"));
    assert(shortest(&w) == 1);        // "fig": as short as "pea", and first
}

A bitstruct declared in a function is the same as one at module level: it gets its Name::bits and Name::from_bits, and its fields read and write in the same way. A packed header that one decoder reads can live inside that decoder.

import std;

fn payload_len(u16 raw) : u16
{
    bitstruct Header : u16            // bits 0..4, 4..14, 14..16
    {
        kind  : 4;
        len   : 10;
        flags : 2;
    }

    Header h = Header::from_bits(raw);
    h.len
}

fn main()
{
    assert(payload_len(0x0123) == 18);        // 0x0123 >> 4 is 0x12
    assert(payload_len(0xFFFF) == 1023);
}

Enums and match

An enum lists its variants; each may carry one payload type. Variant names are used bare (Cold(3), Fine) or qualified (Verdict::Fine) when two visible enums share a name. A variant with no payload behaves as if it carried ().

match (e) { … } compares the discriminant and runs the arm for that variant. Each arm is Variant(binder) : expression, for a payload, Variant : expression, for none, or _ : expression, as a catch-all; every arm ends with a comma. The arms must cover every variant or include _. Arms are expressions, so a match produces a value; use a block as the arm body for statements. Arms are tried in order and the first that fits is taken.

import std;

enum Shape
{
    Circle(i32),                      // radius
    Square(i32),                      // side
    Dot
}

fn area(Shape s) : i32
{
    match (s)
    {
        Circle(r) : 3 * r * r,        // the payload is bound to r for this arm
        Square(w) : w * w,
        Dot       : 0,
    }
}

fn is_round(Shape s) : bool
{
    match (s)
    {
        Circle(_) : true,             // _ as a binder ignores the payload
        _         : false,            // a wildcard arm covers the rest
    }
}

fn main()
{
    assert(area(Circle(2)) == 12);
    assert(area(Shape::Dot) == 0);
    assert(is_round(Square(1)) == false);
    array<Shape, 2> shapes = [Circle(1), Square(3)];
    assert(area(shapes[1]) == 9);
}

enum Sign
{
    Pos,
    Neg,
    Zero
}

fn describe(Sign s) : i32
{
    match (s)
    {
        Pos : 1,
        Neg : -1,                     // ✗ diag.non-exhaustive-match: Zero is not covered
    }
}

fn main()
{
    describe(Zero);
}

Nested patterns

Inside the parentheses, a pattern can say what the payload itself must be, as deep as needed: Ok(Some(line)) matches an Ok whose payload is a Some, and binds the Some's payload. A name there is a binder, unless it is a variant's name (Some(None)), and _ ignores that level. Since a variant has one payload, an arm binds one name, the innermost payload it reaches, unless that payload is a struct taken apart by a struct pattern (below). Every value must reach some arm (the error names one that does not, such as Ok(None)), and every arm must be reachable: an arm whose values all go to earlier arms is rejected, since it could never run.

import std;

fn classify(Result<Option<i32>, ParseError> r) : i32
{
    match (r)
    {
        Ok(Some(n))      : n,         // two levels tested, the inner payload bound
        Ok(None)         : 0,
        Err(Invalid(at)) : -100 - narrow<i32>(at),
        Err(_)           : -1,
    }
}

fn main()
{
    assert(classify(Ok(Some(7))) == 7);
    assert(classify(Ok(None)) == 0);
    assert(classify(Err(Invalid(3))) == -103);
    assert(classify(Err(Empty)) == -1);
}

import std;

fn main()
{
    Option<Option<i32>> o = Some(None);
    i32 v = match (o)
    {
        Some(Some(x)) : x,
        Some(None)    : 1,
        Some(_)       : 2,            // ✗ diag.unreachable-arm: every Some went to the arms above
        None          : 0,
    };
}

Struct patterns

Where a binder could stand, a struct pattern can take the payload apart at once: Some(Question { name, end }) binds name and end, as Question { name, end } = q; would after binding q. The rules are destructuring's (§11): every field is named once, or .. stands for the rest; end : e binds a field to another name; and the fields are taken by value, so a String field moved out consumes the value matched, as any binder of a resource payload does. A struct pattern always fits, so it counts as a binder for exhaustiveness. It works in match arms and in if and while patterns. Through a reference (match (&o)) it is rejected: bind the payload and read its fields through it.

import std;

struct Question
{
    String name;
    u32 end;
}

fn ask(u32 k) : Option<Question>
{
    if (k == 0)
    {
        return None;
    }
    Some(Question { .name = "who", .end = k })
}

fn main()
{
    if (Some(Question { name, end }) = ask(4))
    {
        assert(name == "who" && end == 4);
    }
    u32 n = match (ask(7))
    {
        Some(Question { end : e, .. }) : e,       // renamed; `name` left and ended
        None                           : 0,
    };
    assert(n == 7);
}

Literal patterns

A pattern can also be a literal: an integer (3, -1, 0x10), a byte (b'x'), true or false. It can stand alone, when the value being matched is an integer or a bool, or at the end of a nested pattern: Ok(0), Some(b'\n'). This is CobaltC's multi-way branch in place of switch, and it is checked: a literal must be of the type it is compared with, a repeated case is an arm that can never run, and an integer match needs a _ arm, since literals never list every value (true and false do cover a bool). Text is matched the same way: a match on a str, a String or a StringView takes text literals ("get" : …), compared byte for byte where the text is, so a String you match on is still yours afterwards; Some("quit") works inside a payload too, and if ("quit" = cmd) as a condition. Floats are not patterns. With that, patterns are _, a literal, a variant, and a variant with a pattern for its payload; there is nothing else to learn.

import std;

fn step(u8 op, i64 acc) : i64
{
    match (op)
    {
        0x01 : acc + 1,               // a byte from an instruction stream
        0x02 : acc * 2,
        0x10 : 0,
        _    : acc,                   // any other opcode: no effect
    }
}

fn is_end(Result<usize, FileError> r) : bool
{
    match (r)
    {
        Ok(0)  : true,                // a read of 0 bytes: the end of the file
        Ok(_)  : false,
        Err(_) : true,
    }
}

fn main()
{
    array<u8, 5> program = [0x01, 0x02, 0x02, 0x7f, 0x01];
    i64 acc = 0;
    foreach (op in program)
    {
        acc = step(op, acc);
    }
    assert(acc == 5);
    assert(is_end(Ok(0)) && !is_end(Ok(16)));
}

import std;

fn opcode(str word) : i32
{
    match (word)
    {
        "load"  : 1,
        "store" : 2,
        "jump"  : 3,
        _       : -1,                 // any other word: not an instruction
    }
}

fn is_quit(ref<String, shared> line) : bool
{
    match (*line)                     // a String is read where it is, not moved
    {
        "quit" : true,
        "exit" : true,
        _      : false,
    }
}

fn main()
{
    assert(opcode("jump") == 3 && opcode("halt") == -1);
    String cmd = "exit";
    assert(is_quit(&cmd) && String::len(&cmd) == 4);
    Option<String> first = Some(String::from_str("load"));
    i32 k = match (first) { Some("load") : 1, Some(_) : 2, None : 0, };
    assert(k == 1);
}

Ranges and several values

An arm names one pattern: there are no range patterns (10..15 : …) and no lists of alternatives (1, 4, 6 : … or 1 | 4 | 6 : …); each is a syntax error. Two forms cover these cases. To test a range, match on the test itself: the condition is a bool, and true and false cover it, so no _ arm is needed. Write the bounds as a range would mean them, the upper one left out (v < 15 for 10..15).

import std;

fn check(i32 v)
{
    match (v >= 10 && v < 15)         // 10 to 14, as 10..15 would mean
    {
        true  : printf("%v\n", v),
        false : printf("%v is not in the correct range\n", v),
    }
}

fn main()
{
    check(12);
    check(15);
    check(9);
}

12
15 is not in the correct range
9 is not in the correct range

For several values that share an action, give each value its own arm, and put an action longer than a line in a function the arms call: the match still checks every literal's type and reports a repeated one. When the values are the whole question, match on the test instead, as for a range. For a longer list, keep the values in an array and ask contains, or in a HashSet when the list is built at run time. Text works the same way: one arm per word.

import std;

fn weekend(ref<array<str, 7>, shared> names, u32 day)
{
    printf("%v is a weekend day\n", names[widen<usize>(day)]);
}

fn describe(u32 day)
{
    array<str, 7> names = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
    match (day)
    {
        0 : weekend(&names, day),     // one arm per value; the shared action in a function
        6 : weekend(&names, day),
        _ : printf("%v is a weekday\n", names[widen<usize>(day)]),
    }
}

fn is_square(u32 v) : bool
{
    match (v == 1 || v == 4 || v == 9)   // several values as one test: true and false cover it
    {
        true  : true,
        false : false,
    }
}

fn main()
{
    describe(0);
    describe(3);
    assert(is_square(4) && !is_square(5));
    array<u32, 6> small = [2, 3, 5, 7, 11, 13];                             // a longer list
    Vec<u32> primes = Vec::from_slice(&small[0 .. $]);
    assert(Vec::contains(&primes, &7) && !Vec::contains(&primes, &9));
    str cmd = "exit";
    bool quit = match (cmd)
    {
        "quit" : true,
        "exit" : true,
        _      : false,
    };
    assert(quit);
}

Sun is a weekend day
Wed is a weekday

import std;

fn main()
{
    u8 op = 2;
    i32 cycles = match (op)
    {
        1 : 3,
        2 : 5,
        1 : 4,                        // ✗ diag.unreachable-arm: 1 is taken by the first arm
        _ : 1,
    };
}

Binders and named constants

A name on its own is a pattern too. If it names a constant of integer or bool type, it is that constant's value, a literal by name (PUSH : …); if it names a variant, it is that variant; otherwise it is a new binding for the whole value, which matches anything, like _, and is usually the last arm (other : …). A binding of a resource moves it, as a payload binding does. Mistaking a constant for a binding cannot go unnoticed: a match on an integer then lacks _.

import std;

const u8 PUSH = 0x01;
const u8 POP = 0x02;

fn describe(u8 op) : i32
{
    match (op)
    {
        PUSH  : 1,
        POP   : 2,
        other : 100 + widen<i32>(other),      // every other opcode, bound to `other`
    }
}

fn main()
{
    assert(describe(1) == 1);
    assert(describe(2) == 2);
    assert(describe(9) == 109);
}

Matching through a reference

match (e) binds each payload by value: a plain one is copied, and a resource one (a String, a Vec, a Box) is moved out, which consumes the enum. To look at an enum without taking it apart, match a reference to it: match (&e) binds each payload as a shared reference, match (&mut e) as an exclusive one, through which the payload can be changed. A scrutinee that already is a reference, such as a function's ref<Expr, shared> parameter, binds in its own mode. The enum is not consumed, and the usual borrow rules apply to what is bound: nothing can replace the enum while a payload reference is still in use. This is how a tree built from Boxes (§21) is walked.

import std;

enum Expr
{
    Num(i64),
    Neg(Box<Expr>),
}

fn eval(ref<Expr, shared> e) : i64
{
    match (e)                         // e is a reference: n and x are references too
    {
        Num(n) : *n,
        Neg(x) : -eval(Box::get(x)),
    }
}

fn main()
{
    Expr e = Neg(Box::new(Neg(Box::new(Num(7)))));
    assert(eval(&e) == 7);

    Option<String> name = Some(String::from_str("ada"));
    match (&mut name)                 // change the payload in place
    {
        Some(s) : String::push_ascii(s, b'!'),
        None    : {},
    }
    usize len = match (&name)         // look without consuming
    {
        Some(s) : String::len(s),
        None    : 0,
    };
    assert(len == 4);
    String kept = Option::unwrap_or(name, String::new());   // name still owns its String
    assert(String::len(&kept) == 4);
}

A nested pattern looks through a reference payload in the same way. HashMap::get gives an Option<ref<V, shared>>; when V is an enum, Some(Num(v)) matches its variant through the reference and binds v as a reference of that mode, so a lookup is taken apart in one match. A literal compares through a reference too: Some(0) against an Option<ref<u32, shared>>. The binder borrows what the reference borrows, so the map cannot change while v is in use.

import std;

enum Cell
{
    Num(i64),
    Text(String),
    Empty,
}

fn width(Option<ref<Cell, shared>> c) : i64
{
    match (c)
    {
        Some(Num(v))  : *v,                                  // v : ref<i64, shared>
        Some(Text(t)) : narrow<i64>(widen<u64>(String::len(t))),
        Some(Empty)   : 0,
        None          : -1,
    }
}

fn main()
{
    HashMap<u32, Cell> sheet = HashMap::new();
    HashMap::insert(&mut sheet, 1, Num(12));
    HashMap::insert(&mut sheet, 2, Text(String::from_str("total")));
    assert(width(HashMap::get(&sheet, &1)) == 12 && width(HashMap::get(&sheet, &2)) == 5);
    assert(width(HashMap::get(&sheet, &9)) == -1);
    match (HashMap::get_mut(&mut sheet, &1))
    {
        Some(Num(v)) : { *v += 1; },                         // v : ref<i64, exclusive>
        _            : {},
    }
    assert(width(HashMap::get(&sheet, &1)) == 13);
}

An arm that takes the payload consumes the enum

If the enum carries a resource payload, an arm that binds that payload by value moves it into the binder and consumes the enum: if that arm ran, the scrutinee is stale afterwards. This is what makes match (Vec::pop(&mut v)) { Some(x) : …, None : … } hand you the popped element. An arm that takes nothing out — _, a payload-less variant, or Some(_) — leaves the scrutinee alone, so match (o) { None : …, _ : use(o) } is fine. To look inside and keep the enum whatever the arm, match on a reference to it (above).

import std;

enum Slot
{
    Full(Vec<i32>),
    Empty
}

fn main()
{
    Vec<i32> payload = Vec::new();
    Vec::push(&mut payload, 4);
    auto s = Slot::Full(payload);     // payload moves into the enum
    usize n = match (s)               // the Full arm consumes s
    {
        Full(v) : Vec::len(&v),       // v owns the Vec for the arm, and destroys it at the arm's end
        Empty   : 0,
    };
    assert(n == 1);

    Option<String> o = Some(String::from_str("kept"));
    match (o)
    {
        None : {},
        _    :                        // takes nothing out: o is still here
        {
            String t = Option::unwrap_or(o, String::new());
            assert(String::len(&t) == 4);
        },
    }
}

Numeric codes

An enum without payloads can carry a number per variant, for a file format, a protocol or a C interface: enum Op : u8 { Add = 1, Sub, Mul = 10 }. The type after the colon is the code type, any integer type. A variant without = n takes the previous code plus one (the first, 0). Two variants may not share a code. The enum then has two associated functions: Op::code(e) gives a variant's code, and Op::from_code(n) gives Some(variant) for a code in use and None for any other.

import std;

enum Op : u8
{
    Add = 1,
    Sub,                              // 2
    Mul = 10,
}

fn main()
{
    assert(Op::code(Sub) == 2 && Op::code(Mul) == 10);
    match (Op::from_code(10))
    {
        Some(Mul) : {},
        _         : { assert(false); },
    }
    assert(Op::from_code(3) == None);
}

Generic aggregates

struct Box<T> { T value; } and enum Maybe<T> { Just(T), Nothing } declare families of types. std's Option<T> and Result<T, E> are ordinary enums of exactly this kind (§21). Type arguments may be left off a literal when the declared type of the variable, parameter or field fixes them (§12).

Layout

Struct fields are laid out in declaration order with implementation-documented padding; arrays are contiguous with no padding; an enum is a discriminant of documented width followed by the largest payload, aligned. sizeof<T>() and alignof<T>() report the result (examples in §06, "Sizes and limits of types"). You need this mostly when talking to foreign code or managing raw memory (§20).

§17Modules and name resolution

module, export and import; re-export; private by default; a module's body may be another file; a fixed lookup order for every name.

Modules group declarations and control which names are visible where. They introduce no new semantics: ownership, borrowing and every other rule apply unchanged across module boundaries.

Declaring modules

module name { … } encloses any declarations, including nested modules. Everything is private by default: usable from its own module and the modules nested inside it. export on a declaration makes it usable from outside. An exported item inside a private module is only reachable where that module is.

Each declaration adds one qualified name (bank::fee, bank::Account::open, Shape::Circle), and a name may be added only once, so declaring fee twice in bank is diag.duplicate-item. The same simple name in two different modules is two different names. An associated function fn T::name belongs in the module that declares T; anywhere else it is diag.foreign-associated-fn, so no program can add to, or replace, the functions of std's Vec.

module bank
{
    export fn fee(i32 amount) : i32
    {
        percent(amount, 2)            // a private helper is visible inside its own module
    }

    fn percent(i32 v, i32 pct) : i32
    {
        v * pct / 100
    }

    export module audit                // nested modules; both must be exported to reach `twice`
    {
        export fn twice(i32 v) : i32
        {
            fee(v) * 2                 // the enclosing module's items are in scope
        }
    }
}

fn main()
{
    std::assert(bank::fee(1000) == 20);      // qualified with ::
    std::assert(bank::audit::twice(1000) == 40);
}

module inner
{
    fn helper() : i32                 // not exported
    {
        42
    }
}

fn main()
{
    inner::helper();                  // ✗ diag.name-not-visible
}

import

import a::b::name; lets name be used unqualified in the importing module. It creates no alias and no copy; it only extends name lookup. There is no import … as renaming: if two imports would give one name two meanings, qualify.

module maths
{
    export fn square(i32 v) : i32
    {
        v * v
    }
}

import maths::square;

fn main()
{
    std::assert(square(6) == 36);           // resolves through the import
    std::assert(maths::square(7) == 49);    // the qualified form still works
}

import m; naming a module does two things: m itself resolves, as with any import, and every item m exports, including the variants of its exported enums, can be used unqualified, except its submodules, which keep their paths (std::text) or are imported themselves. This is how programs use the standard library: import std;. A name is looked up in a fixed order: the module's own declarations first, then single-name imports, then module imports, then the enclosing modules. So a module's own printf wins over std::printf, which stays reachable by its full name. If two imported modules both export a name, using that name unqualified is diag.ambiguous-name; importing both is fine, so a module that gains an export never breaks a program that does not use it. An import acts only in the module that writes it: a nested module, or a module in a file of its own, writes its own import std;.

import std;

module shapes
{
    import std;

    export enum Shape
    {
        Square(i32),
        Dot,
    }

    export fn describe(Shape s)
    {
        match (s)
        {
            Square(_) : printf("square\n"),
            Dot       : printf("dot\n"),
        }
    }
}

import shapes;

fn printf(str s)                      // the root's own printf is found before std::printf
{
    std::printf("> ");
    std::printf("%v", s);
}

fn main()
{
    describe(Square(2));              // shapes::describe and shapes::Shape::Square, unqualified
    printf("done\n");
}

square
> done

Re-export: export import

An import can be exported like any other declaration. export import p; in a module M does what import p; does, and also passes on what p brings in as M's own items: every item the module p exports, or the one item p names. A program that imports M then finds those names as if M had declared them, and M::name works too. They are the same items, not copies: a type passed on this way is one type under two paths. This is how a library divided into modules is still used with one import, and how std itself is built (§21): import std; brings in std::text, std::io and the rest because std re-exports each of them.

import std;

module geometry
{
    export module shapes
    {
        export struct Square
        {
            export i32 side;
        }

        export fn area(Square s) : i32
        {
            s.side * s.side
        }
    }

    export module units
    {
        export fn cm(i32 n) : i32
        {
            n * 10
        }
    }

    export import geometry::shapes;   // shapes' items become geometry's
    export import geometry::units::cm;     // one item only
}

import geometry;

fn main()
{
    Square s = Square { .side = cm(2) };      // geometry::shapes::Square, through geometry
    printf("%v\n", area(s));
    geometry::shapes::Square t = geometry::Square { .side = 1 };   // one type, two paths
    printf("%v\n", area(t));
}

400
1

Only what is exported passes through: a private item never becomes reachable by being re-exported. A name the module already has for a different item is diag.duplicate-item; the same item arriving twice, or two modules re-exporting each other, is not an error.

Constants as items

A const declared at a module's top level is an item like a function: it is private unless marked export, it can be imported, and other modules name it by its path (config::LIMIT). Constants themselves, and the static_assert checks built on them, are described with declarations (§11) and with assertions (§18). The specification keeps their rules in its modules chapter (spec/17 §1a and §1b), because a constant is an item.

A module in another file

A module's body can be a separate file. module geo "./geometry.cb"; means exactly module geo { … } with the file's declarations as the body: the same visibility, the same import, the same lookup. The declaring file names the module; the other file's top level is anonymous, just as an inline body is. The path is relative to the directory of the file that writes it, so a file can itself declare file-backed modules with paths relative to its own location, and a library moves as a unit. Use forward slashes and stay inside the tree (no leading /, no ..); anything beyond that is up to the implementation.

// geometry.cb -- the body of a module. Nothing here names the module;
// the file that declares it does. Only `export` items are visible there.
export struct Rect
{
    export f64 w;
    export f64 h;
}

export fn area(Rect r) : f64
{
    r.w * r.h
}

fn scale_factor() : f64               // private to this module
{
    1.0
}

// main.cb -- run this one: `coby main.cb`
module geo "./geometry.cb";           // module geo { … } with geometry.cb's items as the body

import geo::Rect;

fn main()
{
    Rect r = Rect { .w = 3.0, .h = 4.0 };
    std::assert(geo::area(r) == 12.0);      // qualified, as with any module
    // geo::scale_factor();           // ✗ diag.name-not-visible: private, exactly as in one file
}

Three things are rejected before anything runs: a path that names no file (diag.module-file-not-found), a file whose body would load itself again through some chain of declarations (diag.module-cycle), and one file named by two declarations (diag.module-file-duplicate — it would be two distinct modules and two distinct Rect types). A fn main in a loaded file is just the item geo::main; the program's entry is the root file's main, and a program with none is diag.no-main. Both implementations report a diagnostic inside a loaded file against that file and its own line.

A library in several files

Files and re-export (above) together give a library that is split across files but used with one import. Its root file declares the parts, keeps its helpers in a private module, and passes on what users should see: here every exported item of shapes, and cm alone from units. The helpers are usable everywhere inside the library and nowhere outside it, and the files can be reorganized later without changing any program that imports the root.

// geometry.cb -- the library's root: what `import geometry;` brings in
export module shapes "shapes.cb";
export module units "units.cb";
module detail "detail.cb";            // private: the library's own helpers

export import geometry::shapes;       // every exported item of shapes
export import geometry::units::cm;    // one item; units::mm keeps its path

// shapes.cb
export struct Square
{
    export i32 side;
}

export fn Square::new(i32 side) : Square
{
    Square { .side = side }
}

export fn area(Square s) : i32
{
    detail::square(s.side)            // geometry's private module, visible inside geometry
}

// units.cb
export fn cm(i32 n) : i32
{
    n * 10
}

export fn mm(i32 n) : i32
{
    n
}

// detail.cb -- exported from a private module: reachable only inside geometry
export fn square(i32 v) : i32
{
    v * v
}

// main.cb -- run this one: `coby main.cb`
import std;

module geometry "geometry.cb";
import geometry;

fn main()
{
    Square s = Square::new(cm(2));    // shapes and units, through one import
    printf("%v\n", area(s));
    printf("%v\n", geometry::units::mm(5));     // not passed on: written in full
    // geometry::detail::square(3);   // ✗ diag.name-not-visible: detail is private
}

400
5

How a name is found

An unqualified name is first looked up as a local variable or parameter. Failing that, in this order: an item of the current module; an import in the current module whose last segment matches; an item of an enclosing module, outward to the root; finally a variant: first of the enums of this module, or else of the nearest enclosing module with one of that name, and only if there is none, of an imported enum. So your own enum Shape { …, Empty } keeps its bare Empty even though std's ParseError has an Empty too. More than one candidate at a step is diag.ambiguous-name; none at all is diag.unbound-name. A qualified name a::b::c starts by resolving a the same way and then walks into it, checking visibility at the end.

Two special cases: an associated function declared as fn Type::name(…) is addressed as Type::name (or mod::Type::name from outside), and an enum's variants are addressable as Enum::Variant as well as bare.

fn main()
{
    does_not_exist(1);                // ✗ diag.unbound-name
}

Structs and fields across modules

A struct or enum declared in a module is an item like any other: export it to use it outside. Each field has its own visibility too; write export i32 x; for fields that callers may read and write directly, and leave the rest private to give the module full control over its invariants.

module shapes
{
    export struct Rect
    {
        export i32 w;                 // visible to users of the module
        export i32 h;
        i32 cached_area;              // private: only this module's functions may touch it
    }
}

module shapes
{
    export struct Rect
    {
        export i32 w;
        i32 cached_area;
    }
}

fn main()
{
    auto r = shapes::Rect { .w = 1, .cached_area = 0 };   // ✗ diag.name-not-visible: cached_area is private
}

Naming a private field from outside its module — reading it, writing it, giving it in a struct literal, or destructuring it — is diag.name-not-visible, the same diagnostic as for a private function. Give the module a constructor function if callers need to build the struct.

There are no read-only (const) fields: in CobaltC const means a value known before the program runs (§11 constants), not "fixed once built". A field that other code may read but not change is a private field with an exported function that reads it. Only the module can then change it, which is also what keeps the module's invariant in one place.

import std;

module bank
{
    export struct Account
    {
        export u32 id;                // callers may read and write it
        i64 balance;                  // private: changed only by this module
    }

    export fn Account::open(u32 id, i64 deposit) : Account
    {
        std::assert(deposit >= 0, "an account opens with a deposit, not a debt");
        Account { .id = id, .balance = deposit }
    }

    export fn Account::balance(ref<Account, shared> a) : i64
    {
        a.balance
    }

    export fn Account::withdraw(ref<Account, exclusive> a, i64 amount) : bool
    {
        if (amount > a.balance)
        {
            return false;             // the invariant: the balance never goes below zero
        }
        a.balance -= amount;
        true
    }
}

fn main()
{
    auto acct = bank::Account::open(7, 100);
    assert(bank::Account::balance(&acct) == 100);   // read through the module
    assert(!bank::Account::withdraw(&mut acct, 500));
    assert(bank::Account::withdraw(&mut acct, 30));
    assert(bank::Account::balance(&acct) == 70);
    // acct.balance = 1000000;        // ✗ diag.name-not-visible: only bank can change it
}

§18Errors and failure

Fatal checked faults that unwind, assertions checked at run time or before the program runs, and recoverable Result values with the ? operator. Nothing in between.

There are exactly two ways for something to go wrong in CobaltC, and they never mix. A checked fault is the language catching a violated invariant (overflow, an index out of range, a stale reference, a conflicting borrow): it is fatal. An error value is your program reporting an expected failure (bad input, a full buffer) through Result or Option: it is data, and the caller decides what to do. There are no exceptions and no catch.