Introduction

Pepper is a compiled programming language for writing fast, native programs that are safe by default. Like Rust and Swift, it aims to rule out whole classes of memory bugs without asking you to manage memory by hand. It puts three things first:

• Clarity. Code should say what it does. Pepper has a small, familiar syntax, one way to write most things, and error messages that point at the exact token you need to change.
• Simplicity. There is no inheritance, no garbage collector to tune, and no ownership annotations to learn. Structs hold data, methods and extensions add behavior, and traits describe what a type can do.
• Concurrent safety. Shared data should be safe to use from more than one thread. Only thread-safe values can be shared: numbers, async.Atomic<T>, and structs declared [Shared], whose fields the compiler checks.

Here is a complete Pepper program:

# Every program starts at main. Its return value is the process exit code.
main(): int {
    print("Hello, world!");
    return 0;
}

How Pepper manages memory

Every struct value in Pepper is a reference to an object on the heap, and the object is freed when the last reference to it goes away. The model is exactly C++’s std::shared_ptr<T> passed by value: storing a reference in a variable, a field, an array element or a parameter adds a reference, and that reference is released when the variable goes out of scope or is overwritten. There is no separate notion of a “borrowed” reference to learn. Numbers and other primitive values are copied, as in C.

Because the rules are the same everywhere, you can predict exactly when an object is freed and when its destructor runs. The chapter on memory and reference counting covers the model in detail.

How Pepper is built

The compiler is written in Pepper, and builds itself. It parses your program, checks it, and generates native code through LLVM, then links an executable with the system’s C toolchain. The same compiler powers a language server, so editors such as VS Code show Pepper’s errors as you type.

Pepper runs on Windows (x64), Linux (x64) and macOS (arm64), compiles to WebAssembly for WASI (--target wasm32-wasip1, see WebAssembly), and builds libraries that iOS and Android apps call (see iOS and Android). Each release is prebuilt for Windows (x64), Linux (x64, glibc 2.28 or newer) and macOS (arm64 and x64), and installs with one command: see Installing Pepper.

Current status

Pepper is young. The core language works and is tested: variables, functions, structs with constructors, destructors, methods and properties, value structs and enums ([Value]), derived == and hash ([Equatable]), enums (with cases that carry values, methods and computed properties) and match (as a statement or a value, on enums, integers, characters, strings and trait values, with is tests, nested and tuple patterns, guards, ranges and constants), tuples and multiple return values, array and map literals, generics (with type arguments inferred at calls, and generic methods), type aliases, traits (with default methods, and usable as types that convert back with as?), function types and closures, modules (with export * from re-exports), Result-based error handling (Result is an enum, and ? propagates errors), Optional values, iteration (with map, filter, enumerate and zip adapters), with blocks, weak references (to structs and trait values), and calling C (including C callbacks), and being called from C ([Export]ed functions in a static or shared library, with a generated header). The standard library covers strings (with a StringBuilder, StringConstant for literals’ constant bytes, to_string and a ToString trait, $"{a + b:>8}" interpolation with format specifications, and String.format), a Comparable trait for ordered types, sortable, searchable arrays with read-only slices, hash maps and sets, sorted maps and sets (Map, Set) and an insertion-ordered OrderedMap, a BitSet of small integers, a double-ended Deque and a PriorityQueue, atomics, threads, channels and mutexes, tasks (green threads that take turns on a few worker threads, parking on sockets and timeouts), file-system access (see files), text encodings (UTF-16, ASCII; see text), TCP, UDP and Unix domain sockets, TLS, an HTTP/1.1 and HTTP/2 client and server (streamed bodies, redirects, connection reuse, ALPN), URI parsing and percent-encoding, base64, form data and UUIDs, regular expressions, JSON (parsing and writing JsonValues, JSONC documents that keep their comments, and converting structs with json.encode and json.decode), TOML (parsing, writing, editing a document in place, and converting structs), gzip and zlib compression, tar archives, cryptographic hashes (SHA-256, SHA-1 and BLAKE3 in the digest module), random numbers (secure bytes from the operating system and a seedable generator), SIMD vectors (simd.Vector<T, N>), command-line arguments (main(args: String[]), parsed into options with the cli module), starting child processes, the os module (environment variables, monotonic and wall clocks with Duration, and machine and user information), the time module (dates, times of day, time zones from the system’s database, and RFC 3339, HTTP and strftime text), the debug module (stack backtraces, which a panic also prints, and the debugger), and leveled, structured logging (the log module). Unit tests are [Test] functions that pepper test runs in parallel, each in a process of its own. That is enough to write real programs, but expect gaps. pep-fmt, the code formatter, pep-profile, which profiles a program and draws a flame graph, pep-test, which runs unit tests, and pepper, the entry point that runs every tool, are themselves written in Pepper. A pep.toml project builds with pepper build alone and imports the packages it depends on by name, which pepper package fetches from GitHub, GitLab or Codeberg. Some things you will meet quickly:

• Functions are values: a named function, an extern C function, a method (p.norm, Point.norm), a constructor (Point), a generic function’s specialization (larger<int>) or a closure such as (x: int) => x * 2 can be stored, passed and called through a function type such as (int) => int (see function types and closures).
• A constructor marked [Implicit] converts a value into its struct wherever the struct is expected, so io.Path parameters accept a String (see implicit conversions).
• Free functions, methods, operators, constructors, extension methods and trait members can be overloaded.
• A static block runs in the compiler: it can list a struct’s fields and the attributes on them ([Attribute] structs of your own) and generate code for each, so one function can encode any struct (see reflection and attributes).
• -D NAME=VALUE on the command line defines a build option, which [BuildOption("NAME")] and [Target(BuildOption(NAME) >= 2)] select code by and static blocks read (see build options).
• A call can name its arguments, window("Editor", resizable = false), to skip defaulted parameters or pass them in any order (see named arguments).
• Generic parameters can require traits (<T: Shape & Named>), checked wherever the generic is used and, inside the generic, against what the traits declare (see constraints). Numbers, bool and enums whose cases carry nothing can declare traits too, for constraints, but are never trait values.
• Threads can share only thread-safe values, which the compiler checks, closure captures included. A channel hands over what it is sent without copying it (send(move(x)), or send(copy(x)) to keep x), a Select waits to receive from or send to several channels at once, and a Mutex holds any struct, with the compiler keeping each locked value apart from the rest of the program (see threads). An RwLock lets many threads read a thread-safe value at once, and Semaphore, Barrier and Latch coordinate groups of threads. A [ThreadLocal] module-scope var gives every thread its own copy, compiled to the platform’s native thread-local storage (see thread-local variables).
• Integer arithmetic that overflows panics instead of wrapping, at every optimization level; wrapping_add and its siblings wrap on purpose (see integer overflow). Bit counting, rotation, byte swapping and the floating-point functions are methods that compile to LLVM’s intrinsics, and any other intrinsic can be declared as an extern (see LLVM intrinsics).
• Reference counting does not reclaim cycles on its own: two objects that refer to each other are never freed. Break the cycle with a weak reference on one side.

Each chapter of this book says plainly what is and is not supported. When a chapter shows a feature, the example was compiled and run to check it.

How this book is organized

• Tutorial. Getting started builds the compiler and runs your first program. A tour of Pepper then walks through the main features by building a small word-counting program.
• Language guide. One chapter per part of the language, from types and variables to naming conventions. Read it in order, or jump to the topic you need.
• Tools. The pepper command, pep-run, pep-fmt, pep-profile, pep-test and debugging.
• Standard library reference. Every type and function in the runtime, generated from the runtime’s own documentation comments. Start at the overview.
• Contributing. Building this documentation.

Every complete program in this book lives in the repository’s docs/examples/ folder and is compiled and run by the test suite, so what you read is what works.

Versions of this book

This documentation is versioned with the compiler. Use the version picker in the top-right corner of each page to switch between releases; dev follows the main branch. Read the version that matches the compiler you are using.

Getting started

This chapter installs Pepper on your machine, compiles and runs a first program, and sets up your editor.

Install Pepper

Each release has the Pepper toolchain prebuilt for Linux, macOS and Windows. One command installs it:

# Linux and macOS
curl -fsSL https://raw.githubusercontent.com/justinboswell/pepper/main/scripts/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/justinboswell/pepper/main/scripts/install.ps1 | iex

It installs into ~/.pepper (%LOCALAPPDATA%\pepper on Windows), adds its bin folder to your PATH, and offers to install what linking a program needs when it is missing: clang on Linux, Xcode’s command line tools on macOS, LLVM and the Visual Studio Build Tools on Windows. Open a new terminal afterwards. Installing Pepper covers the options, what it installs, and uninstalling.

Building from source

To work on Pepper itself, or on a platform with no prebuilt binaries, build the toolchain from source: see Building Pepper from source.

Your first program

Pepper source files end in .pep. Create a file named hello.pep:

# Every program starts at main. Its return value is the process exit code.
main(): int {
    print("Hello, world!");
    return 0;
}

Every program starts at main, which here takes no arguments and returns an int (it can also take the command-line arguments; see Functions): the process’s exit code, where 0 means success. print writes a value’s text to standard output, followed by a new line. Comments start with # and run to the end of the line.

Compile and run it

Pass the source file to pepper build. It compiles and links a native executable, but does not run it, so run the result yourself:

pepper build hello.pep -o hello
./hello

Hello, world!

On Windows, name the output with .exe (-o hello.exe), since Windows will not run a file without an extension, and run it as .\hello.exe. Without -o the executable is written to the current directory, named after the source file with no extension (hello for hello.pep).

Running a program

To build and run in one step, as python hello.py does, use pepper run. It keeps the executable out of your folder, and runs it again at once when nothing changed:

pepper run hello.pep

Arguments after the file go to the program’s main; see Running a program: pep-run.

Where the compiler finds the standard library

Every program is compiled together with Pepper’s standard library, the runtime/ folder of the repository. The compiler looks for it in this order:

1. The directory named by the PEPPER_RUNTIME environment variable, if it is set. Nothing else is searched.
2. Starting from the directory you run it from: runtime/, .pep/runtime/, then ../runtime/, ../../runtime/, and so on, up to five levels up.
3. Starting from the directory that holds the compiler executable: runtime/ beside it, then in each parent directory, up to five levels up.

So an installed compiler, in ~/.pepper/bin, finds ~/.pepper/runtime, and one built in target/bin finds the runtime of the clone it was built from, wherever you run it. To use a different runtime, set PEPPER_RUNTIME or link the runtime into a project’s .pep folder:

mkdir .pep
ln -s /path/to/pepper/runtime .pep/runtime

If the compiler cannot find the runtime, it stops with an error:

error: cannot find the Pepper runtime: no runtime directory near /home/me/project or the compiler; set PEPPER_RUNTIME to its path

The compiler also writes intermediate files to .pep/build/ under the directory you run it from, and keeps a build cache in .pep/cache/: each file of the program (and the standard library) is compiled to its own object, and on the next build a file whose sources did not change reuses its object without being compiled or checked again, as long as what its imports declare did not change either: editing a function’s body recompiles that file alone, while changing a signature also recompiles the files that import it. A file that compiled with warnings is checked again, so its warnings print on every build. When nothing changed, nothing is checked or linked again. The cache also keeps the standard library checked, so a program’s own files are the only ones checked on each build. Deleting .pep/cache/ is always safe.

When something is wrong

The compiler reports errors the way clang does: the file, line and column, a message, and the source line with a caret under the exact token to fix. Store the message in a variable first, then misspell its name:

main(): int {
    var greeting = "Hello, world!";
    print(greting);
    return 0;
}

The compiler reports:

main.pep:3:11: error: use of undeclared identifier 'greting'
    3 |     print(greting);
      |           ^~~~~~~

Errors are colored when the output is a terminal; set NO_COLOR to turn color off. The chapter on compiler errors covers them in more detail.

A failed assert or a panic at run time prints its message and stops the program abnormally. For example, value() on a failed Result prints Result.value on an Err value.

Useful compiler options

The compiler: pep-build describes every option and environment variable the compiler reads.

A program can span several files: pass the entry file, and the compiler finds the files it imports on its own.

Editor support

The VS Code extension adds syntax highlighting and a language server, which reports compiler errors as you type and provides hover information, completion, go to definition, and an outline of each file.

The packaged extension is published as a .vsix file on the repository’s releases page, under the release whose tag starts with vsix-v. Download it and install it in VS Code with Extensions: Install from VSIX… from the command palette. The language server is bundled with the extension, so there is nothing else to install.

A few things are useful once it is installed:

• Pepper: Restart Language Server restarts the server on demand.
• Where a value is converted by an [Implicit] constructor, the editor shows the call it stands for as an inlay hint (Path( before "notes.txt" and ) after), and hovering the value says so. The pepper.inlayHints.implicitConversions setting turns the hints off.
• A literal passed by position shows the name of its parameter as an inlay hint (resize(width: 800, height: 600)); the pepper.inlayHints.parameterNames setting turns these off. Inside a call’s parentheses, completion offers the parameter names to name (width = ).
• Hover and go to definition also work where the compiler has not checked the code yet: in a generic function or method nothing calls, on a match arm’s case and the names it binds (Circle(r) => ...), and on the values an enum case declares.
• The pepper.lspPath setting points the extension at a language server you built yourself (pep-build -O tools/pep-lsp/main.pep -o target/pep-lsp/pep-lsp in a checkout of the repository; see The language server: pep-lsp). The server restarts whenever that file changes.

To install the extension from the branch you have checked out instead of the release, see The VS Code extension from a branch.

What to read next

• A tour of Pepper builds a small program step by step and shows the main features of the language along the way.
• The language guide covers each part of the language in depth.
• The standard library reference lists every built-in type and function.

A tour of Pepper

This chapter walks through the main features of Pepper by writing small programs, and ends with a word counter that reads a file and reports how often each word appears. It moves quickly and shows the common case of each feature; every section links to the chapter of the language guide that covers it fully.

Every program here is complete: save it to a file, compile it as shown in Getting started, and run it. Each one checks its own results with assert(condition, "message"), which stops the program with the message if the condition is false, so a program that runs to the end and returns 0 did what the comments say.

Variables and functions

# A function lists its parameters as `name: type` and gives its return
# type after the closing parenthesis.
square(x: int): int {
    return x * x;
}

# A parameter may have a default value, used when the caller leaves it out.
greet(name: String = "world"): String {
    return "Hello, " + name + "!";
}

# Adds up 1 + 2 + ... + n with a while loop.
sum_to(n: int): int {
    var total = 0;
    var i = 1;
    while i <= n {
        total += i;
        i = i + 1;
    }
    return total;
}

describe(n: int): String {
    if n > 100 {
        return "big";
    } else {
        if n > 10 {
            return "medium";
        }
    }
    return "small";
}

main(): int {
    var answer = 42;          # the type, int, comes from the value
    double ratio = 0.5;       # or write the type yourself
    var whole = (ratio * 10.0) as int;
    assert(whole == 5, "'as' converts between number types");

    assert(square(answer) == 1764, "square(42)");
    assert(greet() == "Hello, world!", "the default name");
    assert(greet("Pepper") == "Hello, Pepper!", "an explicit name");
    assert(sum_to(4) == 10, "1 + 2 + 3 + 4");

    assert(describe(answer) == "medium", "42 is medium");
    assert(describe(7) == "small", "7 is small");

    print(greet("Pepper"));
    print($"{sum_to(100)}");
    return 0;
}

A few things to notice:

• var declares a variable whose type comes from its initial value: 42 is an int. You can also name the type yourself, as in double ratio = 0.5;. as converts between types, such as from double to int. See Types and variables.
• A function is declared as name(parameters): return type, and each parameter as name: type. A parameter can have a default value, as name does in greet. A function that returns nothing leaves out the return type. See Functions.
• if and while do not need parentheses around the condition, but the body always needs braces. Chain conditions with else if. See Control flow.
• += updates a variable in place, and + joins two strings.
• print writes one value’s text on its own line. Interpolate to combine values: print($"total: {sum_to(100)}").

Structs

A struct groups related data with the methods that act on it:

struct Point {
    var x: int = 0;
    var y: int = 0;

    # `this.x = 0` as a parameter stores the argument straight into the field.
    construct(this.x = 0, this.y = 0) {}

    length_squared(): int {
        return this.x * this.x + this.y * this.y;
    }

    move_by(dx: int, dy: int) {
        this.x = this.x + dx;
        this.y = this.y + dy;
    }
}

# An extension adds methods to a struct that is declared elsewhere.
extend Point {
    swapped(): Point {
        return Point(this.y, this.x);
    }
}

main(): int {
    var p = Point(3, 4);
    assert(p.length_squared() == 25, "3*3 + 4*4");

    var origin = Point();
    assert(origin.x == 0 && origin.y == 0, "defaults from the constructor");

    # Struct values are references: q and p name the same Point.
    var q = p;
    q.move_by(1, 1);
    assert(p.x == 4 && p.y == 5, "p sees the move made through q");

    var s = p.swapped();
    assert(s.x == 5 && s.y == 4, "swapped is a new Point");
    assert(p.x == 4, "p itself is unchanged");
    return 0;
}

• Fields are declared like variables, with var name: type, and may have default values.
• The constructor is named construct. A parameter written as this.x = 0 stores its argument straight into the field x, and = 0 makes it optional, so Point() and Point(3, 4) both work.
• Methods are functions declared inside the struct. Inside a method, this is the object the method was called on.
• extend Point { ... } adds methods to a struct from outside its declaration, even to a struct from the standard library.

Struct values are references. var q = p; does not copy the point: p and q refer to the same object, so moving q moves p. Pepper frees an object when the last reference to it goes away, so you never free memory yourself. See Structs and Memory and reference counting.

Collections

The standard library provides growable arrays, strings, and hash maps. You do not need to import them:

main(): int {
    # Array<T> is a growable list. int[] is another way to write Array<int>.
    var scores = [90, 72];
    scores.append(85);
    assert(scores.count == 3, "three scores");
    assert(scores[0] == 90, "indexing starts at 0");
    scores[1] = 75;
    assert(scores.contains(85), "contains");

    var total = 0;
    for (var score in scores) {
        total += score;
    }
    assert(total == 250, "90 + 75 + 85");

    # sort orders the elements by a comparison function.
    scores.sort((a, b) => a - b);
    assert(scores[0] == 75 && scores[2] == 90, "sorted ascending");

    int[] none = Array<int>();
    assert(none.is_empty, "a new array is empty");

    # String holds UTF-8 text.
    var name = "Pepper";
    var greeting = "Hello, " + name;
    greeting += "!";
    assert(greeting == "Hello, Pepper!", "+ and += join strings");
    assert(greeting.length == 14, "length counts characters");
    assert(greeting.starts_with("Hello"), "starts_with");
    assert(greeting.substr(7, 6) == "Pepper", "substr(start, count)");
    assert(greeting.find("Pepper") == 7, "find returns an offset, or -1");
    assert(greeting[0] == "H", "s[i] is a one-character String");

    # HashMap<K, V> maps keys to values.
    var ages = ["Ada": 36];
    ages.insert("Alan", 41);
    assert(ages.count == 2, "two entries");
    assert(ages["Ada"] == 36, "look up by key");
    assert(ages.contains("Alan"), "contains");
    assert(ages["Grace"] == 0, "a missing key reads as the default value");
    assert(!ages.contains("Grace"), "reading does not insert");
    ages.remove("Ada");
    assert(ages.count == 1, "removed");

    # HashSet<K> keeps each key once.
    var seen = HashSet<String>();
    seen.insert("apple");
    seen.insert("apple");
    assert(seen.count == 1, "duplicates are ignored");
    return 0;
}

• [90, 72] and ["Ada": 36] are collection literals: a new array and a new map.
• Array<T> is a list that grows as you append. int[] is a shorter way to write the type Array<int>. Indexing is checked: reading past the end stops the program with an error rather than reading stray memory. sort takes a function that compares two elements, such as the closure (a, b) => a - b.
• String holds UTF-8 text. The length property counts characters (code points), and s[i] is the character at index i, as a one-character string. Strings compare by content with ==.
• HashMap<K, V> maps keys to values. Reading a key that is not there gives the default value of V (0 for numbers) without adding it; use contains to tell the two apart. HashSet<K> keeps each key once.
• for (var x in collection) visits each element of an array, or each character of a string, in order, and for (var i in 0..n) counts from 0 to n - 1. See Iteration.

Handling errors with Result

Pepper has no exceptions. A function that can fail returns a Result: either a value, or an error that explains what went wrong.

# Converts a string of decimal digits to an int, or explains why it cannot.
parse_number(text: String): Result<int> {
    if text.is_empty {
        return Result<int>.err(Error("expected a number, found nothing"));
    }
    var value = 0;
    for (var c in text) {
        var digit = "0123456789".find(c);
        if digit < 0 {
            return Result<int>.err(Error("'" + c + "' is not a digit"));
        }
        value = value * 10 + (digit as int);
    }
    return Result<int>.ok(value);
}

main(): int {
    var good = parse_number("2026");
    assert(good.is_ok(), "digits parse");
    assert(good.value() == 2026, "value() returns the value");

    var bad = parse_number("12x");
    assert(bad.is_err(), "x is not a digit");
    assert(bad.error().message == "'x' is not a digit", "the error explains why");
    print(bad.error().message);

    assert(parse_number("").ok_or(-1) == -1, "ok_or supplies a fallback");
    return 0;
}

• Result<int> holds either an int or an Error. Build one with Result<int>.ok(value) or Result<int>.err(Error("message")).
• is_ok() and is_err() tell you which one you have. value() and error() return what it holds; error().message is the error’s text.
• value() returns the value, and stops the program if there is none. Use it only when an error would be a bug. ok_or(fallback) returns the value, or fallback if there is none.

See Error handling with Result.

Putting it together: a word counter

The last program combines everything above. It writes a short text file, reads it back, and counts how often each word appears. It is split into two files: counter.pep defines a WordCounter struct, and main.pep uses it.

counter.pep:

# Counts how often each word occurs in some text.
export struct WordCounter {
    var counts: HashMap<String, int>;
    var order: String[];    # each distinct word, in the order first seen
    var total: int;

    construct() {
        this.counts = HashMap<String, int>();
        this.order = Array<String>();
        this.total = 0;
    }

    add(word: String) {
        if !word.is_empty {
            if !this.counts.contains(word) {
                this.order.append(word);
            }
            this.counts[word] = this.counts[word] + 1;
            this.total = this.total + 1;
        }
    }

    # Splits `text` into words at spaces and counts each one. `add` skips
    # the empty pieces that runs of spaces leave.
    add_text(text: String) {
        for (var word in text.split(" ")) {
            this.add(word);
        }
    }

    count(word: String): int {
        return this.counts[word];
    }
}

main.pep:

import [File, Directory, Path] from io;
import "counter";

# Reads the file at `path` and counts its words.
count_file(path: Path): Result<WordCounter> {
    var text = File.read_to_string(path);
    if text.is_err() {
        return Result<WordCounter>.err(Error(text.error().message));
    }
    var counter = WordCounter();
    counter.add_text(text.value());
    return Result<WordCounter>.ok(counter);
}

main(): int {
    # Write a small file to read back.
    var dir = Directory.temp().join("pepper-word-count");
    Directory.create_all(dir);
    var path = dir.join("poem.txt");
    File.write_text(path, "the cat sat on the mat and the dog sat too");

    var result = count_file(path);
    assert(result.is_ok(), "the file we just wrote can be read");
    var counter = result.value();
    for (var word in counter.order) {
        print($"{word}: {counter.count(word)}");
    }
    assert(counter.total == 11, "eleven words");
    assert(counter.count("the") == 3, "'the' appears three times");
    assert(counter.count("sat") == 2, "'sat' appears twice");
    assert(counter.count("bird") == 0, "'bird' does not appear");

    var missing = count_file(dir.join("missing.txt"));
    assert(missing.is_err(), "a missing file is an error, not a crash");
    print(missing.error().message);

    Directory.remove_all(dir);
    return 0;
}

Compile it by passing the entry file; the compiler finds counter.pep from the import:

pepper build main.pep -o word-count
./word-count

It prints each word with its count, one word per line, and then the error message for the missing file (its exact text comes from the operating system):

the: 3
cat: 1
sat: 2
...
No such file or directory

What is new here:

• Imports. import "counter"; makes the declarations that counter.pep marks with export available in main.pep. Anything not exported stays private to its file (or, in a module, to the module’s files). import [File, Directory, Path] from io; brings three names in from the standard library’s io module, which, unlike String or Array, must be imported. See Modules and imports and Visibility.
• Files. Directory.temp() is the system’s temporary directory, and join adds a name to a Path; the name can be a plain String, which converts to a Path implicitly. File has helpers that read or write a whole file at once: File.write_text and File.read_to_string.
• I/O errors are Results. File.read_to_string returns a Result whose error is an IoError, so reading a missing file is an ordinary error value, not a crash. count_file turns it into its own Result<WordCounter>.
• Splitting strings. add_text breaks the text into words with split(" "), which returns an Array<String> of the pieces between the spaces (see String).

Where to go next

You have now seen most of what you need to write everyday Pepper code. The language guide covers each topic in depth, including features this tour skipped: generics, function types and closures, traits and extensions, atomics, threads, and calling C.

Types and variables

This chapter covers the values every Pepper program is built from: numbers, booleans and strings, the variables that hold them, and the operators that combine them.

Built-in types

Integers

Pepper has signed and unsigned integers of 8, 16, 32 and 64 bits. Each width has a short name (i32) and a descriptive alias (int). The two names are the same type, so you can use whichever reads better and assign freely between them.

int is 32 bits and long is 64 bits on every platform. sizeof<T>() gives the size of a type in bytes.

Integer literals are written in decimal (42) or hexadecimal (0xFF). A literal on its own is an int when its value fits in an int, and a long otherwise, so var big = 3000000000; is a long. It takes another type when you store it in a variable of that type (u64 huge = 9000000000000000000;). A hexadecimal literal is a 64-bit bit pattern: u64 all = 0xFFFFFFFFFFFFFFFF; sets every bit.

# Integer types: widths, signedness, wraparound and conversions.
main(): int {
    # Each width has a short name and a descriptive alias.
    i8 tiny = -100;       # same type as char
    u8 octet = 200;       # same type as byte
    i16 small = -30000;   # same type as short
    u16 port = 65000;     # same type as ushort
    i32 count = 2000000;  # same type as int
    u32 mask = 4000000000; # same type as uint
    i64 big = 9000000000; # same type as long
    u64 huge = 9000000000000000000;  # same type as ulong

    assert(sizeof<char>() == 1 && sizeof<short>() == 2, "8 and 16 bits");
    assert(sizeof<int>() == 4 && sizeof<long>() == 8, "32 and 64 bits");

    # An alias names the same type, so assigning between them is lossless.
    short s = small;
    assert(s == -30000, "short and i16 are one type");

    # Storing a value that does not fit wraps around, as in C.
    u16 wrap = 65535;
    wrap = wrap + 1;
    assert(wrap == 0, "u16 wraps from 65535 to 0");
    i16 overflow = 32767;
    overflow += 1;
    assert(overflow == -32768, "i16 wraps from 32767 to -32768");

    # Widening keeps the value: signed types sign-extend, unsigned zero-extend.
    long widened = small;
    assert(widened == -30000, "i16 widens to long");
    assert((tiny as u8) == 156, "-100 as u8 is 156");
    assert((octet as i8) == -56, "200 as i8 is -56");

    # Narrowing with 'as' keeps the low bits.
    assert((70000 as u16) == 4464, "70000 as u16 keeps the low 16 bits");

    # Hexadecimal literals.
    assert(0xFF == 255, "0xFF is 255");
    assert(count + big > 0 && mask > 0 && huge > 0 && port > 0, "all in range");
    return 0;
}

Storing a value that does not fit in the destination keeps its low bits, as in C: a u16 holding 65535 becomes 0 when you add 1 and store the result, and 70000 as u16 is 4464. Arithmetic that overflows int or a wider type panics instead (see Integer overflow).

A decimal literal larger than the largest long (9223372036854775807), or a hexadecimal literal with more than 64 bits, is an error:

main.pep:2:13: error: integer literal is too large to be represented in a 64-bit integer
    2 |     var f = 99999999999999999999;
      |             ^~~~~~~~~~~~~~~~~~~~

Floating point

float is a 32-bit and double a 64-bit IEEE 754 number (f32 and f64 are aliases). A literal with a decimal point or an exponent, such as 0.25 or 1e3, is a double.

Comparisons follow IEEE 754, as in C: against NaN (0.0 / 0.0), ==, <, <=, > and >= are false and != is true, so x != x is true only for a NaN. As a condition, a float is true unless it equals zero, NaN included.

Reading numbers from text

Every number type has a static parse that reads one from a String: int.parse("42") gives an int? (see optionals), empty when the text is not a number of that type: not digits, or too big or too small for it. The integer types take a base from 2 to 36 as a second argument ("ff" in base 16 is 255), and float and double read decimal notation ("2.5", ".5", "1e-3"). Neither accepts spaces, a 0x prefix, inf or nan. Each spelling of a type is the same type, so i32.parse is int.parse:

# Reading numbers from text with each number type's static parse.

main(): int {
    # An integer type takes an optional base from 2 to 36.
    assert(int.parse("-42").value() == -42, "decimal");
    assert(byte.parse("ff", 16).value() == 255, "hexadecimal");

    # The result is empty when the text is not a number of that type.
    assert(int.parse("4 2").is_empty(), "not an integer");
    assert(byte.parse("256").is_empty(), "too big for a byte");

    # float and double read decimal notation.
    var ratio = double.parse("2.5e-1");
    if (ratio.is_value()) {
        assert(ratio.value() == 0.25, "an exponent");
    }
    return 0;
}

Booleans

bool holds true or false. Comparisons and the logical operators produce a bool. In arithmetic a bool counts as 0 or 1, and its text is true or false ($"{flag}").

Characters

A character literal is one ASCII character between single quotes: 'a', '"', '#'. Its value is the character’s code, and its type is byte (u8), the type of one byte of a UTF-8 string. Like any byte it widens to the other integer types, so it compares with, and stores into, an int or a char as well:

# Character literals are bytes.
is_lower(c: int): bool {
    return c >= 'a' and c <= 'z';
}

main(): int {
    var letter = 'a';   # a byte holding 97
    assert(letter == 97, "a character literal is its ASCII code");
    assert('"' == 34 and '\n' == 10 and '\'' == 39, "escapes work as in strings");

    # Compare the bytes of a String with character literals.
    var text = "x = 1";
    var bytes = text.c_str();
    assert(bytes[0] == 'x' and bytes[2] == '=', "compare raw bytes");
    assert(is_lower(bytes[0]), "a byte widens to int");

    # Arithmetic works as on any integer.
    int digit = bytes[4] - '0';
    assert(digit == 1, "the digit's value");

    print($"{letter}");   # 97
    return 0;
}

The escapes are the same as a string’s (see the table under Strings), plus \xHH for any byte, '\xFF' included. A character literal holds exactly one ASCII character; for anything else use a string:

main.pep:2:13: error: character literal may only contain one character; use a string for more
    2 |     var x = 'ab';
      |             ^~~~
main.pep:2:14: error: character literal must be a single ASCII character; use a string for other characters
    2 |     var x = 'é';
      |              ^

char is an 8-bit signed integer, the same type as i8, used mostly for C strings (__ptr<char>). The ASCII characters have the same value as a char and as a byte; '\xFF' is 255 as a byte but -1 read through a char. Text is a String, and a single character of it is a one-code-point String.

byte and char classify ASCII characters as C’s ctype.h does in the “C” locale: is_digit, is_hex_digit, is_alphabetic, is_alphanumeric, is_upper, is_lower, is_whitespace, is_blank, is_punctuation, is_graphic, is_printable, is_control and is_ascii, plus to_upper, to_lower and digit_value(base). The names are spelled out (is_punctuation for C’s ispunct). A byte above 127, which is a negative char, is never a letter, digit, space or punctuation. Unicode classification is not covered.

# Classify and convert ASCII characters, as C's ctype.h does.
main(): int {
    assert('7'.is_digit() and 'f'.is_hex_digit(), "digits");
    assert('q'.is_alphabetic() and 'Q'.is_upper() and 'q'.is_lower(), "letters");
    assert('\t'.is_whitespace() and '\t'.is_blank(), "whitespace");
    assert(';'.is_punctuation() and !'_'.is_alphanumeric(), "punctuation");
    assert('\n'.is_control() and !'\n'.is_printable(), "control");
    assert('a'.to_upper() == 'A' and '?'.to_upper() == '?', "case");

    # The digit's value in a base, or none when it is not a digit there.
    assert('F'.digit_value(16).value() == 15, "hexadecimal");
    assert('9'.digit_value(8).is_empty(), "not an octal digit");

    # Count the words and digits of a String, a byte at a time.
    var text = "Call 555-0100 at 9 a.m.";
    var words = 0;
    var digits = 0;
    var in_word = false;
    for (var b in text.bytes()) {
        if (b.is_digit()) {
            digits = digits + 1;
        }
        if (b.is_alphanumeric() and !in_word) {
            words = words + 1;
        }
        in_word = b.is_alphanumeric();
    }

    # A char answers the same, and bytes above 127 (negative as a char)
    # are never letters.
    char e_acute = -61;   # the first byte of "é" in UTF-8
    assert(!e_acute.is_alphabetic() and !e_acute.is_ascii(), "not ASCII");

    print($"{words} words, {digits} digits");   # 7 words, 8 digits
    return 0;
}

Strings

String is a UTF-8 string. A string literal such as "hello" is a String value wherever a String is expected, and wherever nothing asks for another type (var s = "hello"; declares a String). Where it is stored or passed as a __ptr<char>, it is the literal’s NUL-terminated bytes (see Passing strings), and where a StringConstant is expected, it is one. + joins two strings into a new one, == and != compare contents, the length property counts code points, size counts bytes, and s[i] gives the code point at index i as a one-code-point String.

# String literals are String values.
main(): int {
    var language = "Pepper";
    assert(language.length == 6, "6 code points");

    # + makes a new String; == compares contents.
    var message = "Hello, " + language;
    assert(message == "Hello, Pepper", "concatenation");
    assert(message != language, "different contents");

    # Strings are UTF-8. `length` counts code points, `size` counts bytes.
    var word = "héllo";
    assert(word.length == 5, "5 code points");
    assert(word.size == 6, "6 bytes: 'é' takes 2");
    assert(word[1] == "é", "indexing yields a one-code-point String");

    # A String is a reference: both names see an append.
    var alias = message;
    message.append("!");
    assert(alias == "Hello, Pepper!", "one object, two references");

    print(message);
    return 0;
}

A String is a reference type: var alias = message; makes a second reference to the same object rather than a copy, so a change made with append shows through both names. Memory and reference counting explains how references work, and the String reference lists every method.

Every place a literal is stored (a variable, a field, an array element, a function’s result) gets a new String, so changing it never changes the literal: after var s = "a"; s.append("b"); the next "a" is still "a". Where a literal is only read, passed to a parameter that the function neither keeps nor changes (builder.append("x"), name.contains("x")), every evaluation shares one constant object and allocates nothing.

String constants

A literal’s own type is StringConstant: a pointer to the literal’s bytes, which never change and are never freed, with their size and length. It is a [Value] type, so copying one steps no reference count, any thread may read it, and a literal stored as one allocates nothing. Its bytes always end in a NUL byte, so c_str() passes it to C as it is (a String’s c_str() does too, but a String built with no data has none).

A StringConstant has String’s read API (length, size, find, split, trim, ==, <, the indexer, for loops and so on); the methods that make new text return a String. It converts to a String wherever a String is expected, as if String had an [Implicit] constructor taking it: the conversion (and String(text)) copies the bytes, so an API that takes a String takes a StringConstant too. Where C expects a char*, it passes its own bytes, as c_str() does. Among overloads, a literal picks a StringConstant parameter over a String one, and a StringConstant value picks a String parameter last, as an implicit conversion.

# A string literal's own type is StringConstant: its constant bytes, with no
# allocation and no reference count.
extern ulong strlen(char* text);

# A `const` initialized from a literal is a StringConstant.
const GREETING = "hello";

shout(text: String): String {
    return text.upper() + "!";
}

main(): int {
    StringConstant name = "pepper";
    assert(name.length == 6, "the read API of String");
    assert(name.starts_with("pep") && name.find("p", 1) == 2, "find counts bytes");

    # Always NUL-terminated: c_str() goes to C with no copy.
    assert(strlen(GREETING.c_str()) == 5, "C reads the literal's bytes");

    # A StringConstant converts to a String wherever one is expected.
    String copy = name;
    copy.append("!");
    assert(copy == "pepper!" && name == "pepper", "the copy has its own bytes");
    print(shout(GREETING));

    # Compared with a String either way round, with no copy.
    String typed = "pepper";
    assert(name == typed && typed == name && GREETING < typed, "mixed comparisons");

    # Copying a StringConstant copies a pointer.
    var also = name;
    assert(also == name, "same text");
    return 0;
}

• Where a literal is a StringConstant: a variable, field, parameter or return value of type StringConstant, a HashMap<StringConstant, V> key, and a const with no written type (const GREETING = "hello";), so a module-scope text constant allocates nothing and any thread may read it. Everywhere else, var s = "x" included, a literal is a String, as before.
• Converting chains once: a literal reaches a type that converts from String (io.Path, Error) directly, but a StringConstant variable does not, since conversions never chain. Write String(text) or pass a literal.
• Comparing: ==, !=, <, <=, > and >= compare a StringConstant with another StringConstant (a literal included) or with a String, either way round, and copy nothing.
• A literal method call ("a,b".split(",")) calls the String method.

to_string turns any integer into its decimal text. For parsing and generating text, byte_at and substr_bytes work in bytes (the offsets find returns), compare and <, <=, >, >= order strings byte by byte (code-point order for UTF-8), lines() splits on "\n" or "\r\n", trim(), trim_start() and trim_end() drop whitespace, lower() and upper() change the case of ASCII letters, repeat(n) joins n copies, and bytes() copies the UTF-8 bytes into an array. A StringBuilder builds a long String from many pieces without recopying the text built so far on every append:

# Numbers to text, byte-level access, ordering, and building text in pieces.
main(): int {
    # to_string turns any integer into its decimal text.
    var line = 3;
    var where = to_string(line) + ":" + to_string(-7);
    assert(where == "3:-7", "to_string");

    # byte_at and substr_bytes count bytes, so they work with find's offsets.
    var setting = "indent=4";
    var eq = setting.find("=") as ulong;
    assert(setting.byte_at(eq) == '=', "byte_at compares with a character literal");
    assert(setting.substr_bytes(0, eq) == "indent", "the bytes before '='");

    # compare, <, <=, > and >= order strings byte by byte.
    assert("apple" < "banana", "ordering");
    assert("b".compare("a") > 0, "compare is negative, 0 or positive");

    # lines() splits on "\n" or "\r\n"; trim_end() drops trailing whitespace.
    var lines = "one  \r\ntwo\n".lines();
    assert(lines.count == 2, "no empty line after the final newline");
    assert(lines[0].trim_end() == "one", "trim_end");

    # trim() drops whitespace at both ends; lower() and upper() change ASCII case.
    var field = "  Content-Type ".trim();
    assert(field.lower() == "content-type", "lower");
    assert(field.upper() == "CONTENT-TYPE", "upper");

    # repeat joins copies; StringBuilder appends without recopying the text.
    var out = StringBuilder();
    for (var text in lines) {
        out.append(" ".repeat(4)).append(text.trim_end()).append("\n");
    }
    assert(out.to_string() == "    one\n    two\n", "StringBuilder");
    return 0;
}

To search and take text apart, find(needle, from) starts at a byte offset and rfind finds the last match, split(separator) cuts at every separator and split_once at the first (giving an optional pair), separator.join(parts) puts the parts back together, and replace(from, to) swaps every match (to read a number from text, see Reading numbers from text):

# Searching, splitting, joining and replacing text.

main(): int {
    # find takes a byte offset to start from; rfind finds the last match.
    var path = "src/lib/main.pep";
    var first = path.find("/");
    assert(path.find("/", (first as ulong) + 1) == 7, "the second slash");
    assert(path.rfind("/") == 7, "the last slash");

    # split cuts at every separator; split_once at the first, if any.
    var fields = "name,,age".split(",");
    assert(fields.count == 3 && fields[1] == "", "an empty field");
    var header = "Content-Type: text/plain".split_once(": ");
    if (header.is_value()) {
        var (name, value) = header.value();
        assert(name == "Content-Type" && value == "text/plain", "both halves");
    }

    # join puts the separator between the parts; replace swaps every match.
    assert(" | ".join(fields) == "name |  | age", "joined");
    assert("a\r\nb\r\n".replace("\r\n", "\n") == "a\nb\n", "line endings");
    return 0;
}

An interpolated string puts values’ text into a string literal: $"line {line + 1}: {message}". String interpolation covers which values it accepts.

A backslash in a string literal starts an escape sequence, as in C and Rust:

print("name:\t\"Pepper\"");   # name:	"Pepper"
print("caf\u{e9}");            # café

Any other character after a backslash is an error:

main.pep:2:13: error: unknown escape sequence '\q'
    2 |     print("a\qb");
      |             ^~

Other built-in types

• void means “no value”. It is the return type of a function that returns nothing.
• Array<T> is a growable array of T; int[] is shorthand for Array<int>, and int[][] for Array<Array<int>>. See Array.
• Optional<T> is a value that may be missing; int? is shorthand for Optional<int>. See Optional values.
• HashMap<K, V> and HashSet<K> are hash tables. See HashMap and HashSet.
• Result<TValue, TError> and Error describe operations that can fail. See Error handling with Result.
• async.Atomic<T> is a value that threads can update safely. See Atomics and Threads and shared data.

Raw pointers and __null

For talking to C, Pepper has raw pointers, written __ptr<T> (for example __ptr<char> or __ptr<void>), and the null pointer literal __null:

var p: __ptr<void> = __null;
assert(p == __null, "p is null");

Most programs never need them. Calling C covers pointers in full.

Naming conventions

Primitive types and keywords are lowercase: int, float, bool, var, while. Types, including the ones the runtime provides, are PascalCase: String, Array<T>, HashMap<K, V>, Result<TValue, TError>. Functions, variables and fields are snake_case, and constants are SCREAMING_CASE. Naming conventions has the full rules.

Identifiers are made of ASCII letters, digits and underscores, and cannot start with a digit. Avoid names that start with two underscores: the compiler and runtime use them for their own names, such as __ptr and __null.

Variables

Declare a variable with var and let Pepper infer its type from the initial value, or write the type yourself. Prefer var whenever the type is obvious from the value.

import async;

# Declaring variables: inferred, explicitly typed, constant, and module-level.

# Module-level variables (globals) live for the whole program. Any thread
# can reach them, so they are const and of a thread-safe type: a number, or
# an Atomic for state that changes.
const MAX_REQUESTS = 10;
const request_count = async.Atomic<int>(0);
const total_bytes = async.Atomic<long>(0);

record(bytes: int) {
    request_count.fetch_add(1);
    total_bytes.fetch_add(bytes);
}

main(): int {
    # 'var' infers the type from the initializer.
    var answer = 42;          # int: integer literals are int
    var ratio = 0.25;         # double: floating-point literals are double
    var ready = true;         # bool
    var name = "Pepper";      # String

    # Write the type first, C style...
    int width = 80;
    float scale = 1.5;

    # ...or after the name with a colon.
    var height: int = 24;
    var offset: long = 5000000000;

    # A variable declared without a value starts at zero.
    var hits: int;
    assert(hits == 0, "numbers start at zero");

    # 'const' declares a name that should not be reassigned.
    const LIMIT = 3;

    record(100);
    record(250);
    assert(request_count.load() == 2, "two requests recorded");
    assert(total_bytes.load() == 350, "350 bytes in total");
    assert(request_count.load() < MAX_REQUESTS, "globals are visible in every function");

    assert(answer + width + height == 146, "sum of ints");
    assert(ratio * 4 == 1.0 && scale == 1.5, "floating point");
    assert(ready && name == "Pepper", "bool and String");
    assert(offset > 4000000000 && LIMIT == 3, "long and const");
    return 0;
}

The three forms are:

• var name = value; infers the type from the value.
• Type name = value; is the C style, with the type first.
• var name: Type = value; puts the type after the name.

A variable declared without a value starts out as zero: 0 for numbers, false for bool, and null for a struct type such as String. Give struct variables a value before you use them.

When var infers the type of an arithmetic expression, it takes the type the arithmetic produces under C’s rules (see Arithmetic follows C): var m = 1 + 0.5; is a double holding 1.5, and with u8 small = 250;, var s = small + 10; is an int holding 260.

Constants

const declares a name that you do not intend to change:

const LIMIT = 3;
const RATIO: double = 0.5;

Assigning to a const, with =, a compound assignment, ++ or --, is an error:

main.pep:5:5: error: cannot assign to const variable 'LIMIT'
    5 |     LIMIT = 4;
      |     ^~~~~
main.pep:1:7: note: 'LIMIT' declared const here
    1 | const LIMIT = 3;
      |       ^~~~~

Module-level variables

A variable declared outside any function is a module-level (global) variable. It exists for the whole run of the program and every function in the file can read it. Its initializer can be any expression, including a function call, and runs before main. Like other top-level declarations, a global is private to its file (or module) unless you mark it export (see Visibility).

Any function can run on any thread, so every thread can reach a global. It must therefore be declared const and have a thread-safe type, such as a number, an Atomic<T>, a ThreadLocal<T>, or a [Shared] struct (see Module-scope variables). A global that changes is an Atomic<T>, or a [ThreadLocal] var, which every thread has its own copy of (see Thread-local variables):

const MAX_RETRIES = 3;
const requests = async.Atomic<long>(0);   # changed with requests.fetch_add(1)
[ThreadLocal]
var depth: int = 0;                       # one per thread

Casting with as

value as Type converts a value to another type explicitly, like static_cast in C++:

var ratio = 7.9;
var whole = ratio as int;   # 7
var wide = whole as long;

• Floating point to integer truncates toward zero: -7.9 as int is -7.
• Integer to a narrower integer keeps the low bits: 70000 as u16 is 4464.
• Integer to a wider integer sign-extends a signed source and zero-extends an unsigned one: (-1 as i16) as long is -1, and (65535 as u16) as long is 65535.
• bool and enums convert like integers: true as int is 1, and an enum converts to the integer it is stored as. An integer does not convert to an enum; name a case instead.
• A struct converts to a trait it conforms to: dog as Named. The other way, from a trait value, may fail: shape as? Square gives a Square? (see Converting a trait value back).
• A pointer converts to __ptr<void> and back: p as __ptr<void>, then v as __ptr<int>.
• A value converts to its own type.

Anything else is a compile error at the as, since it would not be a value conversion but a reinterpretation of memory:

main.pep:3:15: error: cannot cast '__ptr<int>' to 'ulong' with 'as'; use 'unsafe_cast<ulong>(...)' to reinterpret
    3 |     var a = p as ulong;
      |               ^~

Casting between unrelated struct types, or between a struct and a number or pointer, is an error with no alternative (cannot cast 'P' to 'Q').

as binds more tightly than the arithmetic operators, so x * 10 as int means x * (10 as int). Put parentheses around the expression you want to convert: (x * 10) as int. C-style casts such as (int)x do not exist.

Many conversions also happen without as: assigning or passing a number to a variable or parameter of another numeric type converts it, as in C, including narrowing conversions (int n = 2.7; stores 2).

Reinterpreting with unsafe_cast

unsafe_cast<Type>(value) reinterprets a value’s bits as another type, like reinterpret_cast in C++. It is for C interop and low-level code, and nothing checks that the result makes sense:

• A pointer to a pointer of another type: unsafe_cast<__ptr<u8>>(text.c_str()).
• A pointer to an integer, and an integer to a pointer: unsafe_cast<ulong>(p), unsafe_cast<__ptr<int>>(address).
• A number to another number of the same width, keeping its bits: unsafe_cast<uint>(1.0 as float) is 0x3F800000, and unsafe_cast<double>(bits) turns a ulong back into a double.

# `as` converts values; `unsafe_cast<T>(value)` reinterprets bits.

extern void* malloc(ulong size);
extern void free(void* p);

main(): int {
    # A float's bits, and back: the same 32 bits seen as a uint.
    var one = 1.0 as float;
    var bits = unsafe_cast<uint>(one);
    assert(bits == 0x3F800000, "1.0 is 0x3F800000");
    assert(unsafe_cast<float>(bits) == one, "the bits convert back");

    # A double's sign bit is its top bit.
    var negative = unsafe_cast<ulong>(-2.0);
    assert((negative >> 63) == 1, "the sign bit is set");

    # `as` converts a pointer to and from `__ptr<void>`.
    var memory = malloc(8);
    var words = memory as __ptr<uint>;
    words[0] = 0x01020304;
    words[1] = 0;

    # Reading the same memory as bytes reinterprets it.
    var bytes = unsafe_cast<__ptr<u8>>(words);
    assert(bytes[0] == 4 || bytes[0] == 1, "the first byte is the low or the high one");

    # An address is an integer, and an integer is an address.
    var address = unsafe_cast<ulong>(words);
    assert(unsafe_cast<__ptr<uint>>(address + 4)[0] == 0, "the address four bytes on is the second word");

    free(memory as __ptr<void>);
    return 0;
}

It never converts a struct, trait or function value, so it cannot get around reference counting. A conversion as can make is not a reinterpretation, so unsafe_cast<long>(n) on an int is an error that says to use as:

main.pep:3:13: error: 'unsafe_cast' cannot convert 'int' to 'long': the sizes differ; use 'as' to convert the value
    3 |     var w = unsafe_cast<long>(n);
      |             ^~~~~~~~~~~

Arithmetic follows C

Arithmetic on numbers behaves exactly as it does in C (the “usual arithmetic conversions”), so code ported from C gives the same results:

• Integer promotion. Types narrower than int (char, u8, short, u16, and bool) are converted to int before any arithmetic. The sum of two chars is an int, so 100 + 100 gives 200 rather than wrapping at 8 bits.
• Mixed widths use the wider type: int + long is a long.
• Signed and unsigned. When both operands have the same width and one is unsigned, the operation is unsigned: comparing int -1 with uint 1 treats -1 as 4294967295, so -1 < 1 is false for those types.
• Integer and floating point gives floating point: 3 * 0.5 is 1.5.
• Division of integers truncates toward zero (-7 / 2 is -3), and % takes the sign of the left operand (-7 % 3 is -1).
• Conditionals. c ? a : b with numeric arms of different types has their common type by the same rules (c ? 0 : s.length is a ulong), and so does a match expression over its arms. The value converts from that type wherever it goes, and a var it initializes has that type (var n = c ? 0 : s.length is a ulong, not an int).
• Shifts take the type of the (promoted) left operand. >> keeps the sign for signed types and fills with zeros for unsigned types.
• Overflow is where Pepper leaves C: it panics, for signed and unsigned types alike (see Integer overflow).

# Arithmetic follows C's rules for promotion and conversion.
main(): int {
    # Integer division truncates toward zero; % takes the sign of the left side.
    assert(7 / 2 == 3, "7 / 2 is 3");
    assert(-7 / 2 == -3, "-7 / 2 is -3");
    assert(-7 % 3 == -1, "-7 % 3 is -1");

    # Types narrower than int are promoted to int before arithmetic,
    # so the sum of two chars does not wrap at 8 bits...
    char a = 100;
    char b = 100;
    int sum = a + b;
    assert(sum == 200, "char + char is computed as int");

    # ...but storing the result back into a char does.
    char c = a + b;
    assert(c == -56, "200 does not fit in a char");

    # Mixing signed and unsigned of the same width is unsigned, as in C.
    int minus_one = -1;
    uint one = 1;
    assert(!(minus_one < one), "-1 converts to 4294967295 when compared with a uint");
    uint zero = 0;
    assert(zero.wrapping_sub(1) == 4294967295, "zero - 1 would panic; wrapping_sub wraps");

    # Mixing an integer with a floating-point value gives floating point.
    int whole = 3;
    double half = 0.5;
    double product = whole * half;
    assert(product == 1.5, "3 * 0.5 is 1.5");

    # 'as' converts explicitly. Floating point to integer truncates toward zero.
    assert((7.9 as int) == 7, "7.9 as int is 7");
    assert((-7.9 as int) == -7, "-7.9 as int is -7");
    assert(((whole as double) / 2) == 1.5, "divide as double");

    # Assignment converts implicitly, including from double to int.
    int truncated = 2.7;
    assert(truncated == 2, "2.7 stored in an int is 2");

    # Shifts: >> is arithmetic for signed types and logical for unsigned types.
    assert(-8 >> 1 == -4, "signed shift keeps the sign");
    uint bits = 0x80000000;
    assert(bits >> 31 == 1, "unsigned shift fills with zeros");
    return 0;
}

Integer overflow

Integer arithmetic whose result does not fit its type stops the program, as in Swift (and Rust’s debug builds), instead of wrapping around silently:

main.pep:3:16: panic: integer overflow in 'int' addition

The message names the operator’s location and the type the operation ran at. These operations check:

• +, -, * and **, unary -, ++ and --, and the compound assignments (+=, -=, *=). Negating the most negative value of a signed type overflows, and so does negating any nonzero unsigned value or subtracting past 0 (uint 0 - 1).
• / and % by zero (division by zero), and the most negative value of a signed type divided by -1 (MIN / -1 and MIN % -1), whose result does not fit.
• << and >> by a count of at least the type’s width, or a negative one: shift count out of range for 'int': must be from 0 to 31.

Arithmetic on types narrower than int runs at int (see above), so it overflows only past int’s range; storing the result back in the narrow type keeps its low bits, like any narrowing conversion. x++ on a u8 holding 255 leaves 0, as x += 1 does. Casts with as never check: 70000 as u16 is 4464.

When both operands are constants, an overflow is a compile error at the operator, and so is a division by a constant 0:

main.pep:2:28: error: integer overflow in 'int' multiplication
    2 |     var seconds = 100000 * 100000;
      |                          ^

Wrapping on purpose

Hashes, checksums and random number generators rely on wrapping. Each integer type has methods that say what to do on overflow instead of panicking:

# Arithmetic that overflows panics; these methods say what to do instead.
main(): int {
    int big = 2147483647;

    # big + 1 would stop the program: "integer overflow in 'int' addition".
    # wrapping_ wraps around, as C's unsigned arithmetic does.
    assert(big.wrapping_add(1) == -2147483648, "wraps to the lowest int");

    # checked_ returns none on overflow.
    assert(big.checked_add(1).is_empty(), "no int is big + 1");
    assert(big.checked_sub(1).value() == 2147483646, "big - 1 fits");

    # saturating_ clamps to the type's range.
    assert(big.saturating_mul(2) == 2147483647, "clamped to the highest int");
    byte level = 10;
    assert(level.saturating_sub(20) == 0, "a byte stops at 0");

    # overflowing_ returns the wrapped result and whether it overflowed.
    var (product, overflowed) = big.overflowing_mul(2);
    assert(product == -2 && overflowed, "wrapped, and overflowed");

    # A hash multiplies with wrapping on purpose (FNV-1a).
    ulong hash = 0xcbf29ce484222325;
    var text = "pepper";
    for (var i in 0..text.size) {
        hash = (hash ^ (text.byte_at(i) as ulong)).wrapping_mul(0x100000001b3);
    }
    assert(hash == 0xac11131d51a77079, "the FNV-1a hash of 'pepper'");
    return 0;
}

The methods work at their type’s own width: byte 200.checked_add(100) is Empty, while 200 + 100 on two bytes is 300 at int.

Removing the checks

The checks stay on at every optimization level. A build that has measured their cost and accepts the risk can remove kinds of check with --no-runtime-checks, a comma-separated list:

pepper build -O main.pep --no-runtime-checks=overflow,shift

Removing bounds or null gives up Pepper’s memory safety: an index out of range or a null reference then reads or writes arbitrary memory instead of panicking. The flag does nothing at -O0, the default, where every check stays on and the compiler warns warning: '--no-runtime-checks' has no effect at -O0. It applies from -O1 up, -g included. The setting is part of the build cache’s key, like the optimization level.

To remove checks from one function instead of a whole build, mark it [Unsafe("...")] with the same names, comma-separated in one string: [Unsafe("overflow")], [Unsafe("overflow,bounds")] or [Unsafe("all")]. It removes them from that function’s body only, at every optimization level (-O0 included), so the function behaves the same in every build. Closures written in it lose the same checks. Functions it calls keep theirs, with one exception: bounds also removes the index checks that Array and String make for it, since those run inside their indexers. [Unsafe] goes on a free function, a method or a constructor. An unknown name is an error at the string.

# `[Unsafe("...")]` removes runtime checks from one function's body.

# A hash that wraps on purpose: without the overflow check, `*` and `+`
# wrap around instead of panicking.
[Unsafe("overflow")]
hash(values: Array<int>): uint {
    uint result = 2166136261;
    for (var value in values) {
        result = (result ^ (value as uint)) * 16777619;
    }
    return result;
}

# A loop that already checked its range: the index checks of `a[i]`, made by
# `Array`'s indexer for this caller, are removed too.
[Unsafe("bounds")]
sum(values: Array<int>): long {
    long total = 0;
    ulong i = 0;
    while (i < values.count) {
        total = total + values[i];
        i = i + 1;
    }
    return total;
}

main(): int {
    var values = Array<int>();
    for (var i in 0..100) {
        values.append(i);
    }
    assert(hash(values) != 0, "a hash");
    assert(sum(values) == 4950, "0 + 1 + ... + 99");
    # Outside those functions every check stays: 2147483647 + 1 here would
    # still panic.
    return 0;
}

Bit operations and math functions

Each integer type has methods that compile to a single instruction on most CPUs, through LLVM’s intrinsics, for code that would otherwise loop over bits:

Like the overflow methods, they work at their type’s own width: byte 1.leading_zeros() is 7.

# Bit operations on integers: counting, reversing and rotating bits.
main(): int {
    uint mask = 0x00F0;
    assert(mask.trailing_zeros() == 4, "the lowest set bit is bit 4");
    assert(mask.leading_zeros() == 24, "the highest set bit is bit 7");
    assert(mask.count_ones() == 4, "four bits are set");

    # Zero has no set bit: its counts are the type's width.
    assert((0 as ulong).trailing_zeros() == 64, "no set bit");

    # The methods work at their type's own width.
    byte low = 1;
    assert(low.leading_zeros() == 7, "a byte has 8 bits");
    assert(low.rotate_right(1) == 0x80, "the bottom bit comes back at the top");

    # Byte order: swap_bytes converts between little and big endian.
    assert((0x12345678 as uint).swap_bytes() == 0x78563412, "bytes reversed");
    assert((1 as uint).reverse_bits() == 0x80000000, "bits reversed");

    # min, max and abs.
    assert((-7).abs() == 7, "without its sign");
    assert((3).min(5) == 3 && (3).max(5) == 5, "smaller and larger");
    return 0;
}

float and double have square_root(), floor(), ceiling(), truncate(), round() (halfway cases away from zero), abs(), copy_sign(sign), multiply_add(factor, addend) (this * factor + addend rounded once) and min(x) and max(x) (which ignore a NaN argument):

# Floating-point functions: square root, rounding, sign and fused
# multiply-add.
main(): int {
    var side = (2.0).square_root();
    assert(side * side > 1.999 && side * side < 2.001, "close to 2");

    assert((-1.5).floor() == -2.0, "toward negative infinity");
    assert((-1.5).ceiling() == -1.0, "toward positive infinity");
    assert((-1.5).truncate() == -1.0, "toward zero");
    assert((2.5).round() == 3.0, "halfway cases away from zero");

    assert((-4.0).abs() == 4.0, "without its sign");
    assert((4.0).copy_sign(-1.0) == -4.0, "the sign of the argument");
    assert((2.0).multiply_add(3.0, 1.0) == 7.0, "2 * 3 + 1, rounded once");
    assert((1.5).min(-2.0) == -2.0 && (1.5).max(-2.0) == 1.5, "smaller and larger");
    return 0;
}

They also have the functions of C’s <math.h>, with their names spelled out. Angles are in radians. LLVM’s intrinsics compute the ones it has, and the C math library the rest:

Powers are the ** operator: x ** 0.5, or x ** 3 with an integer exponent. The math module has the constants (math.PI, math.TAU, math.E, math.INFINITY, math.NAN, and the epsilon and limits of float and double) and math.gcd and math.lcm for integers:

# Floating-point math: trigonometry, logarithms, powers, classification,
# and the math module's constants and integer functions.
import math;

main(): int {
    var angle = math.PI / 6;
    assert((angle.sine() - 0.5).abs() < 1e-12, "sin 30 degrees is 1/2");
    assert(((1.0).arc_tangent2(1.0) - math.PI / 4).abs() < 1e-12, "45 degrees");

    assert((1024.0).logarithm2() == 10.0, "2 to the 10th is 1024");
    assert((1.0).exponential() == math.E, "e to the 1st");
    assert(2.0 ** 10 == 1024.0 && (-8.0).cube_root() == -2.0, "powers and roots");
    assert((3.0).hypotenuse(4.0) == 5.0, "a 3-4-5 triangle");

    assert(math.NAN.is_nan() && math.NAN != math.NAN, "NaN is not equal to itself");
    assert(math.INFINITY.is_infinite() && !math.INFINITY.is_finite(), "infinite");
    assert((-0.0).sign_bit() && !(-0.0 < 0), "negative zero");

    assert(math.gcd(12, 18) == 6 && math.lcm(4, 6) == 12, "integers");
    return 0;
}

Hints for the optimizer are [Likely] and [Unlikely] on a branch and the prefetches of the hint module. Any other LLVM intrinsic can be declared as an extern; see LLVM intrinsics.

Operators

# Operators on numbers and booleans.
main(): int {
    # Arithmetic.
    assert(2 + 3 * 4 == 14, "* binds tighter than +");
    assert((2 + 3) * 4 == 20, "parentheses group");
    assert(17 % 5 == 2, "remainder");
    assert(-(3) == -3, "negation");

    # Exponentiation is right-associative: 2 ** 3 ** 2 is 2 ** 9.
    assert(2 ** 10 == 1024, "power");
    assert(2 ** 3 ** 2 == 512, "right-associative");
    # With a floating-point operand, the result is floating point.
    assert(2.0 ** -2 == 0.25, "float power");
    assert(9 ** 0.5 == 3.0, "square root");

    # Comparison yields a bool.
    var small = 3 < 5;
    assert(small, "3 < 5");
    assert(5 >= 5 && 4 <= 5 && 6 > 5 && 5 == 5 && 5 != 6, "comparisons");
    # On numbers, `===` and `!==` are the same as `==` and `!=`.
    assert(5 === 5 && 5 !== 6, "identity on numbers");

    # Logical operators; 'and' and 'or' are spellings of && and ||.
    var t = true;
    var f = false;
    assert(t && !f, "and, not");
    assert(f || t, "or");
    assert(t and (f or t), "word forms");

    # Bitwise operators.
    assert((6 & 3) == 2, "and");
    assert((6 | 3) == 7, "or");
    assert((6 ^ 3) == 5, "exclusive or");
    assert(~0 == -1, "complement");
    assert(1 << 4 == 16 && 256 >> 2 == 64, "shifts");

    # Compound assignment and increment.
    var n = 5;
    n += 3;   # 8
    n -= 2;   # 6
    n *= 4;   # 24
    n /= 5;   # 4
    n %= 3;   # 1
    n <<= 3;  # 8
    n >>= 1;  # 4
    n &= 6;   # 4
    assert(n == 4, "compound assignment");
    n++;
    ++n;
    n--;
    assert(n == 5, "increment and decrement");

    # The conditional (ternary) operator.
    var sign = n > 0 ? "positive" : "not positive";
    assert(sign == "positive", "ternary");
    return 0;
}

&& and || short-circuit: the right operand is evaluated only when the left one does not decide the result, so items.count > 0 && items[0] == 1 never reads items[0] from an empty array.

Unary operators nest: -~x is -(~x), and !!x is !(!x), which turns a number into a bool. A struct can define its own operators, the truth test !! included (see Operators).

** raises a number to a power, and is right-associative: 2 ** 3 ** 2 is 2 ** 9. On two integers the result is an integer, and the exponent can be any integer expression. A negative exponent gives the truncated real result: 1 for a base of 1, 1 or -1 for a base of -1, and 0 otherwise (2 ** -1 is 0).

When either operand is a float or double, the result is floating point, by the usual conversions above: 2.0 ** 0.5 is the square root of 2, 2.0 ** -2 is 0.25, and 4 ** 0.5 is the double 2.0. An integer exponent of at most 32 bits computes by repeated multiplication (LLVM’s powi), which is fast but may differ from C’s pow in the last bit; any other exponent calls pow itself. ** on anything but numbers or a struct that defines it is an error:

main.pep:3:15: error: invalid operands to binary expression ('__ptr<int>' and 'int')
    3 |     var q = p ** 2;
      |               ^~

Operators bind in this order, tightest first:

1. Postfix: calls f(x), indexing a[i], member access a.b, x++, x--
2. **
3. as, as?
4. Unary +, -, !, ~
5. Prefix ++, --
6. *, /, %
7. +, -
8. <<, >>
9. .., ..> (ranges; not associative)
10. is
11. <, <=, >, >=
12. ==, !=, ===, !==
13. &
14. |, ^
15. &&, and
16. ||, or
17. ? :
18. = and the compound assignments (right-associative)

As in C, & binds more loosely than ==, so write (flags & mask) == mask with the parentheses.

An expression can nest at most 256 levels deep, counting each operator of a chain as one level, so a sum of more than about 250 terms is a compile error (see Compiler errors).

String interpolation

An interpolated string is a string literal with a $ before its opening quote. Inside it, an expression in braces, {name} or {a + b}, is replaced by the text of its value:

# Interpolated strings: `$"..."` with expressions in braces.
main(): int {
    var name = "Pepper";
    var count = 3;
    var ready = true;

    # Each {name} is replaced by that variable's text.
    var line = $"{name} has {count} items, ready: {ready}";
    assert(line == "Pepper has 3 items, ready: true", "integers, bool and String");

    # Any expression fits between the braces, strings included.
    var sizes = [2, 5];
    assert($"total {sizes[0] + sizes[1]}" == "total 7", "arithmetic and index");
    assert($"{name.size} letters" == "6 letters", "call");
    assert($"{count > 1 ? "many" : "one"}" == "many", "ternary with strings");

    # Doubled braces are literal braces; escapes work as in any string.
    assert($"{{count}} = {count}" == "{count} = 3", "literal braces");
    assert($"tab\t{count}\n" == "tab\t3\n", "escapes");
    return 0;
}

• {expression} holds an expression: a name (a local, a parameter, a global, or inside a method a field), a member access ({p.x}), a call ({f(x)}), an index ({items[0]}), arithmetic ({a + b}), or a ternary ({a > b ? a : b}). Spaces around it are ignored.
• The expression changes no variable: an assignment (=, +=, …), ++ or -- anywhere in it is an error, even inside a call’s arguments ({f(a = 3)}). Only a closure’s body, which does not run in place, may hold one. A function it calls may still have effects of its own.
• String literals may appear inside the braces ({greet("you")}), and so may character literals and other interpolated strings. A } inside them, or inside brackets of the expression’s own, does not end it.
• The expression fits on one line and holds no comment: a line break or a # inside the braces is an error.
• A format specification may follow the expression after a :, as in {n:>8} or {n:08x}: see below.
• {{ and }} are a literal { and }.
• Escapes (\n, \t, \", …) work as in any string literal.
• The result is a new String. An interpolated string with no braces is an ordinary string.

Which values can be interpolated

Each value is converted with to_string(value), so it can be:

• an integer of any size, signed or unsigned, which gives its decimal text;
• a float or double, which gives the shortest decimal text that reads back as the same number, as Swift prints one: 0.1, 3.0 (a whole number keeps its .0), -2.5, and an exponent outside 1e-4 to 1e16 (1e+16, 1.5e-05); nan, inf and -inf for the special values;
• a bool, which gives true or false;
• a tuple of up to eight values that can each be interpolated, which gives its elements’ text in parentheses, (1, two) (a String element without quotes);
• a String, which is used as it is;
• a value whose type has a to_string(): String method, such as a struct that implements the runtime’s ToString trait, or a value of type ToString itself;
• a value whose type has a to_string<T> override. Like hash<Point> (see overriding a generic function), an override applies to the whole program, so it serves types that have no to_string() method of their own.

# A struct is interpolated through its to_string() method.
struct Point {
    var x: int = 0;
    var y: int = 0;
    construct(this.x = 0, this.y = 0) {}
}

extend Point with ToString {
    to_string(): String {
        # Inside a method, fields are names too.
        return $"({x}, {y})";
    }
}

# A type without the method gets a to_string<T> override instead.
struct Celsius {
    var degrees: int = 0;
    construct(this.degrees = 0) {}
}

to_string<Celsius>(value: Celsius): String {
    return $"{value.degrees} C";
}

main(): int {
    var start = Point(1, 2);
    var reading = Celsius(21);
    assert($"from {start}" == "from (1, 2)", "ToString");
    assert($"it is {reading}" == "it is 21 C", "override");

    # A trait value converts through the value's own method.
    var shown: ToString = start;
    assert($"{shown}" == "(1, 2)", "trait value");
    return 0;
}

Numbers and tuples, with the format specifications below:

# Floating-point numbers and tuples have text too.
main(): int {
    var price = 4.5;
    var ratio = 1.0 / 3.0;
    assert($"{price}" == "4.5", "the shortest text that reads back");
    assert($"{2.0}" == "2.0", "a whole number keeps its point");
    assert($"{1.0e20}" == "1e+20", "large numbers use an exponent");
    assert($"{ratio:.3}" == "0.333", "a precision rounds to that many digits");
    assert($"[{price:8.2}]" == "[    4.50]", "numbers align right");
    assert($"{price:+08.2}" == "+0004.50", "with a sign and zeros");

    var point = (3, "north");
    assert($"{point}" == "(3, north)", "a tuple's elements in parentheses");
    print("{0} at {1:.1}", point, price);   # (3, north) at 4.5
    return 0;
}

Runtime types such as String, StringBuilder, io.Path, Uri and regex.Match implement ToString. An enum is interpolated through a to_string() method it declares (return name(); gives the case’s name).

A plain overload such as to_string(p: Point) is not used: the runtime’s code does not import your file, so it cannot see yours (see overloading). Write a to_string<Point> override or a method instead.

Format specifications

A : after the expression starts a format specification, which pads the value’s text, writes an integer in another base, or rounds a floating-point number to a number of digits. Its parts, all optional, come in this order:

{value:[[fill]align][+][0][width][.precision][type]}

# Format specifications: padding, signs and other bases after a `:`.
main(): int {
    var count = 42;
    var name = "Pepper";

    # Width and alignment pad any value; numbers go right by default.
    assert($"[{count:6}]" == "[    42]", "a number goes right");
    assert($"[{name:10}]" == "[Pepper    ]", "text goes left");
    assert($"[{name:>10}]" == "[    Pepper]", "right");
    assert($"[{name:*^10}]" == "[**Pepper**]", "centered with a fill");

    # Integers take a sign, zero padding and a base.
    assert($"{count:+}" == "+42", "a plus sign");
    assert($"{count:05}" == "00042", "zero padding");
    assert($"{255:x} {255:X} {5:b} {8:o}" == "ff FF 101 10", "bases");
    assert($"0x{255:08x}" == "0x000000ff", "padded hexadecimal");
    assert($"{-42:x}" == "-2a", "a negative number keeps its sign");

    # The `:` after the whole expression starts the specification.
    assert($"[{count > 1 ? "many" : "one":>5}]" == "[ many]", "a ternary");
    return 0;
}

• Padding (fill, align and width) works for any value that can be interpolated: it pads the value’s to_string text, counting characters, not bytes.
• + and 0 need a number: an integer (of any size, signed or unsigned), or a float or double given a precision ({x:+08.2}). A type needs an integer, and a precision a float or double. Using one with any other value is an error at that character, and a precision cannot be combined with a type.
• A negative number keeps its sign in every base: {-42:x} is -2a, not the bits of its two’s complement.
• The : that starts the specification is the one after the whole expression, so a ternary can be formatted as it is: {n > 1 ? "many" : "one":>5}.

Formatting by position: String.format

String.format takes a string literal whose braces name its other arguments by position, {0} for the first, each with an optional format specification, and returns the text:

# String.format: braces name the arguments by position.
main(): int {
    var a = 2;
    var b = 3;
    assert(String.format("{0} + {1} = {2}", a, b, a + b) == "2 + 3 = 5", "in order");

    # An index can repeat or come out of order, with its own specification.
    assert(String.format("{1} before {0}", "first", "second") == "second before first", "reordered");
    assert(String.format("{0} is {0:x} in hex", 255) == "255 is ff in hex", "repeated");
    assert(String.format("[{0:>4}] {{literal}}", a) == "[   2] {literal}", "padding and braces");
    return 0;
}

• The format must be a string literal: the compiler reads it, so an index out of range, an argument no brace names, or a bad specification is an error at compile time. {{ and }} are literal braces, as in an interpolated string.
• Each argument is evaluated once, from left to right, however many braces name it and in whatever order.
• An index can repeat, to show one value twice or in two forms ("{0} is {0:x} in hex").
• It is part of the compiler, not a function in the runtime: it cannot be stored in a variable or called through a function value.
• print takes the same arguments: print("{0} of {1}", done, total) prints what String.format makes of them.

Errors

A value with no conversion is reported at its braces, with a note at its type:

main.pep:5:17: error: cannot interpolate a value of type 'Foo': it has no 'to_string()' method and no 'to_string' overload
    5 |     print($"f = {f}");
      |                 ^~~
main.pep:1:8: note: declare 'to_string(): String' in 'Foo', or implement 'ToString' with 'extend Foo with ToString'
    1 | struct Foo {}
      |        ^~~

A lone brace is an error, since doubling it is how to write one, and so is anything after the expression but its }:

main.pep:2:15: error: unmatched '}' in interpolated string; write '}}' for a literal '}'
    2 |     print($"a } b");
      |               ^
main.pep:3:18: error: expected '}'
    3 |     print($"a {x b");
      |                  ^
main.pep:3:15: note: to match this '{'
    3 |     print($"a {x b");
      |               ^

Empty braces are reported where the expression should start:

main.pep:2:16: error: expected an expression after '{' in interpolated string; write '{{' for a literal '{'
    2 |     print($"a {} b");
      |                ^

An error in the expression itself, such as a name that is not declared (use of undeclared identifier 'x'), is reported like any other, at the token inside the braces.

A format specification’s errors are reported at the character in it that is wrong:

main.pep:5:16: error: unexpected 'q' in format specification; expected '[[fill]align][+][0][width][.precision][type]'
    5 |     print($"{n:q}");
      |                ^
main.pep:5:19: error: cannot format a value of type 'String' as an integer
    5 |     print($"{name:x}");
      |                   ^
main.pep:6:16: error: cannot format a value of type 'i32' with a precision; only 'float' and 'double' take one
    6 |     print($"{n:.2}");
      |                ^

String.format reports an index with no argument at the index, and an argument with no index at the argument:

main.pep:5:31: error: argument index 2 is out of range for 2 arguments
    5 |     print(String.format("{0} {2}", n, n));
      |                               ^
main.pep:5:35: error: argument 1 of 'String.format' is not used by its format string
    5 |     print(String.format("{0}", n, n + 1));
      |                                   ^~~~~

Changing a variable inside the braces is reported at the operator:

main.pep:3:16: error: an assignment cannot appear in an interpolated string
    3 |     print($"{a += 1}");
      |                ^~

How it works

The compiler turns $"({x}, {y + 1})" into "(" + to_string(x) + ", " + to_string(y + 1) + ")", resolving to_string in the runtime rather than in your file. So a struct’s own to_string() method can interpolate its fields without calling itself, and the result costs what the same + expression does. A value with a format specification goes through a runtime call that pads or converts its text instead. String.format becomes the same concatenation, with its arguments bound to hidden names first when the braces name them out of order or more than once.

Text encodings

A String always holds UTF-8. The text module converts text to and from the bytes of an encoding (u8[]), for files, network protocols and C libraries that use another one:

# Text in other encodings: encode a String to bytes, decode bytes back.
import text;

main(): int {
    var greeting = "héllo 🙂";

    # UTF-8 is what a String holds; decode checks the bytes.
    var utf8 = text.Utf8.encode(greeting);
    assert(utf8.count == 11, "é takes two bytes, 🙂 four");
    assert(text.Utf8.decode(utf8).value() == greeting, "round trip");

    # UTF-16: two bytes per unit, little-endian unless asked otherwise.
    var utf16 = text.Utf16.encode(greeting);
    assert(utf16.count == 16, "🙂 takes a surrogate pair");
    assert(text.Utf16.decode(utf16).value() == greeting, "round trip");

    # ASCII has no é: strict gives none, lossy writes '?'.
    assert(text.Ascii.encode(greeting).is_empty(), "not ASCII");
    assert(text.Ascii.encode_lossy("é").count == 1, "one '?'");

    # Code page 437, as old zip archives name entries: é is 0x82, and every
    # byte decodes, so decode gives a String.
    var dos = text.CodePage437.encode("café").value();
    assert(dos.count == 4 && dos[3] == 0x82, "one byte each");
    assert(text.CodePage437.decode(dos) == "café", "round trip");
    assert(text.CodePage437.encode(greeting).is_empty(), "no 🙂 in code page 437");

    # Strict decoding rejects invalid bytes; lossy decoding replaces them.
    var bad = Array<u8>();
    bad.append(104);
    bad.append(255);
    assert(text.Utf8.decode(bad).is_empty(), "0xFF is never UTF-8");
    assert(text.Utf8.decode_lossy(bad) == "h\u{FFFD}", "replaced");
    return 0;
}

• decode is strict: it gives Empty when the bytes are not valid in the encoding (a stray UTF-8 continuation byte, an unpaired UTF-16 surrogate, an odd UTF-16 byte count, an ASCII byte of 128 or more).
• decode_lossy always succeeds: whatever is invalid becomes U+FFFD, the replacement character.
• Ascii.encode gives Empty for text with a code point past 127, and CodePage437.encode for a character the code page lacks; encode_lossy writes ? for each instead.
• No byte-order mark is written, and one that is read stays in the text.
• io.File.read_string decodes with text.Utf8.decode, and an HTTP body’s text() with decode_lossy.

The reference lists every function.

Regular expressions

The regex module finds patterns in text: test whether text matches, find each match and its capture groups, and replace or split by a pattern.

# Regular expressions: match, capture, iterate, replace and split.
import regex;

main(): int {
    # Compile once, reuse. Backslashes are doubled inside a string literal.
    var date = regex.Regex("(?<year>\\d{4})-(\\d{2})-(\\d{2})");
    assert(date.is_match("due 2026-10-01"), "a date somewhere");

    # The first match, with its groups. Positions are byte offsets.
    var found = date.find("due 2026-10-01").value();
    assert(found.text() == "2026-10-01" && found.start() == 4, "where");
    assert(found.group(2).value() == "10", "a numbered group");
    assert(found.group("year").value() == "2026", "a named group");

    # Every match, left to right.
    var total = 0;
    for (var number in regex.Regex("\\d+").find_all("1 22 333")) {
        total += int.parse(number.text()).value();
    }
    assert(total == 356, "1 + 22 + 333");

    # Replace with group references, and split.
    var swapped = regex.Regex("(\\w+)@(\\w+)").replace_all("ann@home bob@work", "$2:$1");
    assert(swapped == "home:ann work:bob", "groups swapped");
    var parts = regex.Regex("\\s*,\\s*").split("a , b,c");
    assert(parts.count == 3 && parts[1] == "b", "three pieces");

    # Flags go inside the pattern: (?i) ignores case.
    assert(regex.Regex("(?i)^hello").is_match("HeLLo there"), "any case");

    # An invalid pattern from outside the program: parse reports it.
    var bad = regex.Regex.parse("(unclosed");
    assert(bad.is_err(), "missing ')'");
    return 0;
}

Compiling a pattern

• regex.Regex(pattern) compiles a pattern and panics when it is invalid. Use it for patterns written in the program.
• regex.Regex.parse(pattern) returns a Result<Regex> instead, whose error names the problem and its byte offset: invalid regex '(a': missing ')' at offset 0. Use it for patterns that come from input.
• Compile once and reuse the Regex; compiling costs more than a search.
• Regex.escape(text) escapes every character with a meaning in a pattern, so the result matches text literally.

A pattern is a String, so each backslash is doubled in a string literal: "\\d+" is the pattern \d+.

Searching

A Match has text(), start() and end() (byte offsets, as String.find returns, for use with substr_bytes), and group(index) or group(name), which give the group’s text or Empty when the group did not take part (as (a) in (a)|b matching b). Group 0 is the whole match; groups are numbered by their opening (. group_range(index) gives a group’s offsets.

Matching is leftmost-first, as in Perl: the match that starts earliest wins, and among those, a greedy repetition prefers more and alternation prefers its earlier branch (a|ab finds a in ab).

find_all skips an empty match that comes right after the previous match, so a* finds a twice in aba, not also an empty match between them.

In a replacement, $1 or ${1} stands for group 1, ${name} for a named group, $0 for the whole match and $$ for a $. A group that did not take part gives empty text. Use braces when a digit or letter follows: ${1}0, not $10.

Syntax

The syntax is RE2’s, the one Go’s regexp and Rust’s regex crate use.

Flags go in the pattern: (?i) makes the rest of the enclosing group case-insensitive, (?i:x) only x, and (?-i) turns a flag off.

Text

• A pattern works on code points: . and [^a] match one whole code point, such as é or 🙂, never part of one.
• \d, \w, \s, \b, the POSIX classes and case-insensitive matching are ASCII-only: \w does not match é.
• Positions are byte offsets, like String.find and substr_bytes, not the code point positions of substr.

Linear time

Matching never backtracks. The engine (a Pike VM, as in RE2) steps every possible match through the text together, so a search takes time proportional to the size of the text times the size of the pattern, whatever both are. A pattern such as (a*)*b, which takes exponential time in a backtracking engine, is safe on untrusted input.

The price is two features that need backtracking. A pattern that uses one fails to compile:

• Backreferences (\1): backreferences are not supported
• Lookaround ((?=x), (?!x), (?<=x), (?<!x)): lookaround is not supported

Groups nest at most 250 deep, and a pattern whose compiled program would exceed 100,000 instructions (from large counted repetitions such as (a{1000}){1000}) is rejected.

Threads

A Regex never changes once it is compiled, and it is [Shared]: one Regex can serve every thread at once, so a pattern the program uses often can be compiled once at module scope:

import regex;

const identifier = regex.Regex("^[A-Za-z_][A-Za-z0-9_]*$");

is_identifier(text: String): bool {
    return identifier.is_match(text);
}

Each search keeps its working state to itself, and a Match (which holds the searched String) stays on the thread that found it.

The reference lists every method.

JSON

The json module reads JSON text into a JsonValue, lets you look values up and change them, and writes them back as compact or indented text. It also converts structs to JSON and back.

# JSON: parse text, look values up, change them, and write them back.
import json;

main(): int {
    var text = "{\"name\": \"pepper\", \"server\": {\"port\": 8080}, \"tags\": [\"fast\"]}";
    var parsed = json.parse(text, path = "config.json");
    if (parsed.is_err()) {
        print(parsed.error().to_string());   # config.json:1:17: error: ...
        return 1;
    }
    var root = parsed.value();

    # Lookups chain, and a missing key gives Null instead of panicking.
    assert(root["name"].as_string().value() == "pepper", "a string");
    assert(root["server"]["port"].as_int().value_or(80) == 8080, "a number");
    assert(root["server"]["host"].as_string().value_or("localhost") == "localhost", "a default");

    # Match on the case to handle every kind.
    var described = match (root["tags"]) {
        Array(items) => $"{items.count} tag",
        Null => "no tags",
        else => "not a list",
    };
    assert(described == "1 tag", "an array");

    # Change the value in place, then write it back. Keys keep their order.
    root["tags"].append(json.JsonValue.String("safe"));
    root["debug"] = json.JsonValue.Bool(false);
    assert(root.to_string() == "{\"name\":\"pepper\",\"server\":{\"port\":8080},\"tags\":[\"fast\",\"safe\"],\"debug\":false}", "compact");

    # Build a value from scratch.
    var reply = json.JsonValue.object();
    reply["id"] = json.JsonValue.Integer(42);
    reply["ok"] = json.JsonValue.Bool(true);
    assert(reply.to_pretty_string() == "{\n  \"id\": 42,\n  \"ok\": true\n}", "indented");

    # An error names the line and column.
    var bad = json.parse("{\n  \"a\": 1\n  \"b\": 2\n}", path = "bad.json");
    assert(bad.error().to_string() == "bad.json:3:3: error: expected ',' or '}'", "where");

    # JSONC: comments and trailing commas, on request.
    var settings = json.parse("{\n  // the theme\n  \"theme\": \"dark\",\n}", comments = true);
    assert(settings.value()["theme"].as_string().value() == "dark", "JSONC");
    return 0;
}

Values

json.JsonValue is an enum whose cases carry values, so match handles each kind:

• Numbers keep their form. A number written without a fraction or an exponent is an Integer when it is within ±(2^53 − 1), the range every JSON implementation agrees on (RFC 7493). Any other number, including a larger integer, is a Number.
• Make values with the cases (JsonValue.Integer(42), JsonValue.String("a"), JsonValue.Null), and containers with JsonValue.object() and JsonValue.array(items).
• Containers are shared. An Array or Object holds its array or map by reference, so changing it through value[key] = ..., append, or the map from as_object() changes every holder of the value.

Looking values up

A lookup that finds nothing gives Null rather than panicking, so lookups chain and a default goes at the end: root["server"]["port"].as_int().value_or(8080).

Changing values

• value["key"] = member sets an object’s member. A new key goes at the end; an existing key keeps its place. It panics on a value that is not an object.
• value[index] = element replaces an array’s element, and value.append(element) adds one at the end. Both panic on a value that is not an array.
• value.remove("key") removes an object’s member and says whether it was there.

Parsing

json.parse(text) returns a Result<JsonValue, JsonError>. It is strict RFC 8259:

• The text holds one value, with only spaces, tabs and line breaks around it. A byte-order mark at the start is skipped.
• The text must be valid UTF-8; an invalid byte is an error at that byte.
• A string cannot hold a raw control character (write \n), and a \u escape of an unpaired surrogate ("\uD800") is an error.
• No comments, trailing commas, single quotes, NaN, leading zeros (01) or + signs.
• When an object repeats a key, the last value wins, in the place of the first.

parse takes optional arguments, usually passed by name:

The parser keeps its own stack rather than recursing, so deep nesting in the text cannot overflow the call stack. max_depth still bounds it, because releasing a value releases its nested values recursively. Raise it with care: Windows gives a program’s main thread a 1 MB stack, which a few thousand levels of nested objects can use up when the value is released.

Errors

A JsonError has the message, the line and column (from 1, counting bytes) and the byte offset. to_string() renders it like a compiler error:

config.json:3:3: error: expected ',' or '}'

Without a path, it starts at the line: 3:3: error: expected ',' or '}'.

Writing

• value.to_string() writes compact text, with no spaces or line breaks: {"id":42,"tags":["a","b"]}. String interpolation uses it too.
• value.to_pretty_string() puts each element and member on its own line, indented two spaces per level (to_pretty_string(indent = 4) for four), with a space after each :. An empty array or object stays [] or {}.
• Strings are written as UTF-8, escaping ", \ and the control characters. to_string(ascii_only = true) and to_pretty_string(ascii_only = true) also escape everything outside ASCII as \u, with a surrogate pair past U+FFFF.
• A Number is written as Pepper writes a double (0.5, 1000.0, 1e+16), so it reads back as a Number. NaN and the infinities, which JSON cannot spell, are written as null.
• Objects keep their keys in insertion order, so parsing a document and writing it back keeps its order.

Documents with comments

parse skips a JSONC file’s comments. To change a file people edit, such as a settings file, and write it back with its comments, read it with json.parse_document(text), which returns a Result<JsonDocument, JsonError>:

# JSON: change a JSONC settings file and write it back with its comments.
import json;

main(): int {
    var text = "{\n  // Spaces per level.\n  \"tab_size\": 4,\n  \"font\": \"Mono\", // the editor's\n  \"wrap\": true\n}";
    var parsed = json.parse_document(text, path = "settings.json");
    if (parsed.is_err()) {
        print(parsed.error().to_string());
        return 1;
    }
    var document = parsed.value();
    assert(document.to_string() == text, "unchanged text comes back as it was");

    # Change the value; each comment stays with its value.
    document.root["tab_size"] = json.JsonValue.Integer(2);
    document.set_comments("$.wrap", ["// Wrap long lines."]);
    assert(document.comments("$.tab_size")[0] == "// Spaces per level.", "by path");
    print(document.to_string());
    # {
    #   // Spaces per level.
    #   "tab_size": 2,
    #   "font": "Mono", // the editor's
    #   // Wrap long lines.
    #   "wrap": true
    # }
    return 0;
}

• document.root is the JsonValue; change it as any other.
• Each comment belongs to a value, by its path from the root $ ($.editor.tab_size, $.files[0]): the comments on the lines before it, and those on the line it ends, after its comma. Comments before a closing bracket stay at the end of their array or object, and those around the whole value stay before or after it.
• document.to_string() writes the text indented, as to_pretty_string does (to_string(indent = 4) for four spaces), with every comment back in its place. A file in that layout reads and writes back unchanged.
• A comment whose value is removed is dropped. One whose path later names another value, such as an element shifted into its index, goes with that value.
• document.comments(path) returns the comments before a value, and document.set_comments(path, ["// ..."]) replaces them.
• parse_document takes path and max_depth as parse does, and always accepts JSONC.

Structs

json.encode(value) writes a struct as JSON text, and json.decode<T>(text) reads one back. There is no code to write per type: both walk the struct’s properties with reflection while compiling, so the conversion costs what hand-written code would.

# JSON: convert structs to JSON text and back, through reflection.
import json;

enum Mode {
    Fast,
    Safe,
}

struct Tls {
    var cert: String;
}

struct ServerConfig {
    var host: String;
    [Required]
    var port: int;
    # The key is "max-connections", not the property's name.
    [Name("max-connections")]
    var max_connections: int;
    # Never written or read.
    [Ignore]
    var started_at: long;
    # `null` or missing when none.
    var tls: Tls?;
    var mode: Mode;
    var tags: Array<String>;
}

main(): int {
    var config = ServerConfig();
    config.host = "localhost";
    config.port = 8080;
    config.max_connections = 64;
    config.mode = Mode.Safe;
    config.tags = ["web"];
    var text = json.encode(config);
    assert(
        text == "{\"host\":\"localhost\",\"port\":8080,\"max-connections\":64,\"tls\":null,\"mode\":\"Safe\",\"tags\":[\"web\"]}",
        "properties in declaration order"
    );

    var decoded = json.decode<ServerConfig>("{\"port\": 443, \"tls\": {\"cert\": \"site.pem\"}}");
    if (decoded.is_err()) {
        print(decoded.error().to_string());
        return 1;
    }
    var back = decoded.value();
    assert(back.port == 443, "a number");
    assert(back.tls.value().cert == "site.pem", "a nested struct");
    assert(back.mode == Mode.Fast, "a missing key keeps its default");

    # An error names where in the document it is, by path, line and column.
    var bad = json.decode<ServerConfig>("{\"port\": 443, \"mode\": \"Slow\"}", path = "server.json");
    assert(bad.error().to_string() == "server.json:1:23: error: $.mode: 'Slow' is not a case of 'Mode'", "a path");
    var missing = json.decode<ServerConfig>("{}");
    assert(missing.error().to_string() == "1:1: error: $: missing required key 'port'", "[Required]");
    return 0;
}

A struct’s public properties become an object’s members, in declaration order. Each property’s type converts as follows, and the same rules apply at the top level (json.decode<Array<int>>("[1, 2]")):

A struct reference that holds nothing (a String, array, struct or reference enum field never assigned) is written as null, and null reads back as one, so a value round-trips. Reading a case’s value whose key is missing is an error: $.shapes[0].Circle: missing value 'radius'. null for a number, bool or enum is an error.

Attributes

The serialize module’s attributes, which json uses (they need no import of their own), change how a property is converted:

On an enum and its cases, they choose how a case is written:

# JSON: choose how an enum's cases are written with attributes.
import json;

# A tag beside the values: {"kind": "circle", "radius": 2}.
[Tag("kind")]
enum Shape {
    [Name("circle")]
    Circle(radius: int),
    Point,
}

# The values under their own key: {"type": "Click", "data": {"x": 1, "y": 2}}.
[Tag("type", content = "data")]
enum Event {
    Click(x: int, y: int),
    Close,
}

# No tag; reading takes the first case that fits.
[Untagged]
enum Size {
    Fixed(px: int),
    Auto,
}

main(): int {
    assert(json.encode(Shape.Circle(2)) == "{\"kind\":\"circle\",\"radius\":2}", "internally tagged");
    assert(json.encode(Shape.Point) == "{\"kind\":\"Point\"}", "a case with no values");
    assert(json.encode(Event.Click(1, 2)) == "{\"type\":\"Click\",\"data\":{\"x\":1,\"y\":2}}", "adjacently tagged");
    assert(json.encode(Size.Fixed(8)) == "{\"px\":8}", "untagged");
    assert(json.encode(Size.Auto) == "\"Auto\"", "untagged, no values");

    var shape = json.decode<Shape>("{\"kind\": \"circle\", \"radius\": 5}");
    if (shape.value() is Circle(radius)) {
        assert(radius == 5, "read back");
    } else {
        return 1;
    }
    var size = json.decode<Size>("\"Auto\"");
    assert(size.value() is Auto, "the first case that fits");
    var bad = json.decode<Shape>("{\"radius\": 5}");
    assert(bad.error().to_string() == "1:1: error: $: missing tag 'kind'", "a missing tag");
    return 0;
}

Reading an [Untagged] enum tries each case in order and takes the first that reads without an error (with UnknownKeys.Reject, an extra key is an error too), so a case whose values include another’s goes first. When none reads, the error says so: $: found an object, which matches no case of 'Size'. A [Tag] enum’s errors name its tag: $: missing tag 'kind', $.kind: 'Hex' is not a case of 'Shape'. A tag with the name of one of a case’s values is a compile error, since both would be written under one key.

Reading

decode makes a struct with its constructor that takes no arguments, then reads in each property it finds a key for. A missing key leaves its property at its default, unless the property is [Required]. It takes optional arguments, usually passed by name:

An error has a line and column as in Errors. One in converting a value also has its value_path, where in the document the value is as a path from the root $, and its message starts with that path. The line and column are the value’s, or the enclosing object’s for a missing key:

server.json:3:13: error: $.server.port: expected a number, found a string
server.json:7:21: error: $.tags[2]: expected a string, found null
server.json:4:24: error: $["max-connections"]: 70000 does not fit in 'u16'
server.json:1:1: error: $: missing required key 'port'

json.to_json(value) and json.from_json<T>(value) do the same conversions to and from a JsonValue rather than text (with no text, a from_json error has no line: error: $.port: ...), and json.encode(value, indent = 2) writes indented text.

Types it cannot convert

A property whose type has no JSON form, such as a pointer, a function, or a Result (a result is not a value to send over the wire), is a compile error naming the property. Notes follow the conversion back to the call that asked for it:

runtime/json/convert.pep:358:25: error: 'encode' cannot convert property 'outcome' of type 'Result<int>' to JSON
...
main.pep:10:16: note: 'encode<Job>' is used by 'main' here
   10 |     var text = json.encode(job);
      |                ^~~~~~~~~~~

Current limits

• parse skips comments; only a JsonDocument keeps them, and decode never does. A document is always written indented.
• A struct’s own conversion cannot be customized yet: a type converts as its properties do.
• Map keys must be Strings.

The reference lists every function.

TOML

The toml module reads TOML 1.0 into a TomlValue, lets you look values up and change them, writes tables back as documents, edits a document in place without disturbing its comments, and converts structs to TOML and back. The package manager reads and edits pep.toml and pep.lock with it.

# TOML: parse a document, look values up, edit it in place keeping its
# comments, and read it into a struct.
import toml;

struct Package {
    [Required]
    var name: String;
    var version: String;
}

struct Manifest {
    [Required]
    var package: Package;
}

main(): int {
    var text = "[package]\nname = \"demo\"  # the name\nversion = \"0.1.0\"\n";
    var parsed = toml.parse(text, path = "pep.toml");
    if (parsed.is_err()) {
        print(parsed.error().to_string());   # pep.toml:2:6: error: ...
        return 1;
    }
    var root = parsed.value();
    assert(root["package"]["name"].as_string().value() == "demo", "a string");
    assert(root.lookup("package.version").value().as_string().value() == "0.1.0", "a dotted lookup");
    assert(root.try_get("dependencies").is_empty(), "a missing key");

    # Change a value, then write the tables back as a document.
    var package = root["package"];
    package["edition"] = toml.TomlValue.Integer(2026);
    assert(root.to_document() == "[package]\nname = \"demo\"\nversion = \"0.1.0\"\nedition = 2026\n", "a document");

    # Edit the text in place: comments and layout stay as written.
    var document = toml.parse_document(text, path = "pep.toml").value();
    document.set(["dependencies", "yaml"], toml.TomlValue.String("0.3")).value();
    assert(
        document.to_string() == "[package]\nname = \"demo\"  # the name\nversion = \"0.1.0\"\n\n[dependencies]\nyaml = \"0.3\"\n",
        "an edit"
    );

    # Read it into a struct, with the serialize attributes json uses.
    Manifest manifest = toml.decode<Manifest>(text).value();
    assert(manifest.package.version == "0.1.0", "a struct");

    # An error names the line and column.
    var bad = toml.parse("name \"demo\"\n", path = "bad.toml");
    assert(bad.error().to_string() == "bad.toml:1:6: error: expected '=' after the key", "where");
    return 0;
}

Values

toml.TomlValue is an enum whose cases carry values:

• Look values up with value["key"] and value[index], which panic on a miss, or try_get("key") and lookup("package.name"), which give an empty Optional. The as_ methods (as_string, as_int, as_float, as_bool, as_date_time, as_array, as_table) give an empty Optional for another kind; as_float also reads an integer.
• Write a value on one line with to_string() (as after a key’s =), or a table as a whole document with to_document().
• There is no null. What json writes as null is left out, and a missing key reads as the property’s default.

Errors

toml.parse(text, path = "pep.toml") checks every rule of TOML 1.0 and gives a TomlError that renders like a compiler error: pep.toml:4:12: error: expected '=' after the key. Arrays and inline tables may nest max_depth deep (1000 by default); parsing and writing use explicit stacks, so deep nesting never overflows the stack. The module passes all 709 TOML 1.0 cases of toml-test, which its tests run.

Editing a document in place

toml.parse_document(text) gives a TomlDocument, whose set(keys, value) and remove(keys) change only the lines they must, keeping every comment and blank line, the way cargo add edits Cargo.toml. A changed value is rewritten on one line; a new key goes after the last key of its table, indented like it; a new table goes at the end as a [header] section, or as { ... } with inline = true. Edits cannot reach inside an array of tables ([[bin]]); set or remove the whole array.

Structs

toml.encode(value) and toml.decode<T>(text) (and to_toml and from_toml, which work on a TomlValue) convert structs through reflection, with the serialize attributes JSON uses: [Name("key")], [Ignore] and [Required]. unknown_keys = toml.UnknownKeys.Reject makes an unknown key an error. See the reference for every function.

YAML

YAML 1.2 is read and written by the yaml package, which has the same shape as the json and toml modules: a YamlValue to look values up in and change, clang-style errors at the line and column, documents that keep their comments when edited, and struct conversion with the serialize attributes. It is a package rather than part of the runtime because few programs need YAML; add it with pepper package add justinboswell/pepper-yaml --name yaml.

import yaml;

main(): int {
    var parsed = yaml.parse("server:\n  port: 8080\n  debug: no\n", path = "config.yaml");
    if (parsed.is_err()) {
        print(parsed.error().to_string());
        return 1;
    }
    var root = parsed.value();
    print(root["server"]["port"].as_int().value());       # 8080
    print(root["server"]["debug"].as_string().value());   # no
    root["server"]["port"] = yaml.YamlValue.Integer(9090);
    print(root.to_string());
    return 0;
}

• The core schema: yes, no, on and off are strings, not booleans, so NO (Norway) stays NO.
• Safe for untrusted text: only the core schema’s tags (!!str, !!int, …) are read, and any other tag is an error; aliases may not stand for more than max_alias_nodes nodes, which stops the “billion laughs” attack.
• Merge keys: yaml.parse(text, merge_keys = true) applies YAML 1.1’s << (<<: *defaults), which CI and compose files use to reuse a mapping; the mapping’s own keys win, and merged nodes count toward max_alias_nodes. By default << is an ordinary key, as YAML 1.2 says.
• Several documents in one stream (---) are read by yaml.parse_all and written by yaml.write_all.
• yaml.parse_document keeps comments, key order, flow or block style and scalar styles through edits, as json.parse_document keeps a JSONC file’s comments.
• yaml.encode and yaml.decode<T> convert structs exactly as json.encode and json.decode do.

The package’s README lists what it reads and its limits: a mapping’s keys are strings, and there is no streaming reader yet.

Compression and archives

The compress module compresses and decompresses DEFLATE data, plain or in its zlib and gzip framings, and the archive module reads and writes tar archives. Together they handle .gz and .tar.gz files. Both are written in Pepper, so a program that uses them links no extra library, unless it is built to use zlib (see Using zlib).

# Compress and decompress bytes in one call, or as streams.
import compress;
import io;

main(): int {
    var text = "the cat sat on the mat; ".repeat(100).bytes();

    # gzip, zlib and raw DEFLATE each have compress and decompress.
    var packed = compress.Gzip.compress(text);
    assert(packed.count < text.count / 10, "repetitive text shrinks");
    assert(compress.Gzip.decompress(packed).value() == text, "round trip");

    # Level 0 stores, 9 squeezes hardest; 6 is the default.
    var fast = compress.Zlib.compress(text, level = 1);
    assert(compress.Zlib.decompress(fast).value() == text, "any level reads back");

    # Corrupt data is an error, never a crash.
    packed[packed.count - 5] = packed[packed.count - 5] ^ 1;
    var bad = compress.Gzip.decompress(packed);
    assert(bad.is_err() && bad.error().is_invalid_input(), "the CRC-32 check fails");

    # Streams: a CompressWriter wraps any io.Writer, a DecompressReader any
    # io.Reader, such as a File. Here both are in memory.
    var sink = io.ByteWriter();
    var writer = compress.CompressWriter(sink, compress.Format.Gzip);
    writer.print_line("first line");
    writer.print_line("second line");
    writer.finish();

    var reader = compress.DecompressReader(io.ByteReader(sink.bytes), compress.Format.Gzip);
    var lines = 0;
    for (var line in reader.lines()) {
        lines += 1;
    }
    assert(lines == 2, "two lines");

    # The checksums are there on their own too.
    assert(compress.Crc32.of("123456789".bytes()) == 0xCBF43926, "CRC-32");
    return 0;
}

Formats

• compress(data, level = 6) returns the compressed bytes. The level runs from 0 (stored, no compression) to 9 (smallest, slowest). Each level searches for matches with zlib’s settings for it, so the output is about the size zlib makes at the same level, at a similar speed: on 12 MB of source text, compressing at level 6 takes about 1.2 times as long as the gzip command, and decompressing is a little faster than gzip -d.
• decompress(data) returns an io.IoResult<u8[]>. Damaged or truncated data is an error whose is_invalid_input() holds, and gzip and zlib data is checked against its CRC-32 or Adler-32 checksum.
• Gzip input may hold several members one after another (cat a.gz b.gz); they decompress to their contents joined. Bytes after the last member are an error. A gzip header’s file name and comment are skipped, and a written header has neither.
• A zlib stream made with a preset dictionary needs it to decompress; see Preset dictionaries.
• decompress puts everything in memory. Use a DecompressReader for input from outside the program, so a small file that expands hugely cannot exhaust memory.

compress.Crc32 and compress.Adler32 compute the two checksums over data given in pieces (update, then value), or in one call with of.

Streams

compress.DecompressReader(source, format) is an io.Reader that decompresses source, any io.Reader, as it is read, so lines(), chunks(size) and read_all() work on it. It holds at most about 225 KiB of input and output, however large the data.

compress.CompressWriter(sink, format, level = 6) is an io.Writer that compresses what is written and writes the result to sink. Call finish() at the end: it writes the last block and the checksum. Dropping the writer does not finish it, and finish() does not close the sink.

io.ByteReader(bytes) and io.ByteWriter() stand in for a stream when the data is in memory.

Preset dictionaries

A short message compresses poorly, since the stream has no earlier bytes to refer back to. A preset dictionary gives it some: bytes that both sides agree on beforehand, such as the keys and common values of a JSON protocol, which the compressed data can then copy from as if they came just before it.

# Compress small messages against a preset dictionary of what they share.
import compress;

main(): int {
    # Short messages with the same keys compress poorly on their own: the
    # stream has no earlier bytes to refer back to.
    var dictionary = "{\"user\": \"\", \"action\": \"login\", \"status\": \"ok\"}".bytes();
    var message = "{\"user\": \"ada\", \"action\": \"login\", \"status\": \"ok\"}".bytes();

    var plain = compress.Zlib.compress(message);
    var primed = compress.Zlib.compress(message, dictionary);
    assert(primed.count < plain.count, "the dictionary supplies the repeated text");

    # Decompressing needs the same dictionary; the stream names it by its
    # Adler-32, so a missing or different one is an error.
    assert(compress.Zlib.decompress(primed, dictionary).value() == message, "round trip");
    assert(compress.Zlib.decompress(primed).is_err(), "no dictionary given");
    print($"{plain.count} bytes alone, {primed.count} with the dictionary");
    return 0;
}

• Zlib.compress(data, dictionary, level = 6) and Zlib.decompress(data, dictionary) take one. The zlib header names the dictionary by its Adler-32, so decompress without one, or with a different one, is an is_invalid_input() error. A stream made without a dictionary decompresses as usual when one is given.
• CompressWriter(sink, format, dictionary, level = 6) and DecompressReader(source, format, dictionary) take one for Format.Zlib or Format.Raw. Raw DEFLATE data carries no sign of it, so both sides must know to use it. Gzip has no dictionary, and asking for one panics.
• Only the last 32 KiB of a dictionary can be referred to, since that is how far back DEFLATE reaches; put the most common text at its end.

Using zlib

Building with -D USE_ZLIB (see Build options) makes compress use zlib, the reference DEFLATE library, for compressing, decompressing, CRC-32 and Adler-32, in place of its Pepper code:

pep-build main.pep -D USE_ZLIB -o app

• The API is the same, and so are the errors for damaged data, worded as the Pepper code words them where zlib tells the causes apart. Compressed output can differ byte for byte (zlib’s gzip header names the operating system), but each side decompresses the other’s.
• Linux links -lz, from the development package (zlib1g-dev, zlib-devel). macOS has zlib already. Windows has none: install it (vcpkg install zlib) and name the folder holding zlib.lib with -L or PEPPER_LIBRARY_PATH.
• zlib compresses faster than the Pepper code at the same level, and makes output of about the same size.

Tar archives

# Write a .tar.gz, list it, and extract it.
import archive;
import compress;
import io;

main(): int {
    var folder = io.Directory.temp().join("pepper-compression-tar-example");
    io.Directory.remove_all(folder);
    var path = io.Directory.temp().join("pepper-compression-tar-example.tar.gz");

    # A TarWriter over a gzip CompressWriter over a File.
    var file = io.File.create(path).value();
    var gzip = compress.CompressWriter(file, compress.Format.Gzip);
    var tar = archive.TarWriter(gzip);
    tar.append_directory("app-1.0");
    tar.append_file("app-1.0/main.pep", "main(): int { return 0; }\n".bytes());
    tar.append_file("app-1.0/run.sh", "#!/bin/sh\n".bytes(), mode = 493);
    tar.finish();
    gzip.finish();
    file.close();

    # List the entries.
    var reader = archive.TarReader(compress.DecompressReader(io.File.open(path).value(), compress.Format.Gzip));
    var names = Array<String>();
    while (true) {
        var entry = reader.next_entry().value();
        if (entry.is_empty()) {
            break;
        }
        names.append(entry.value().path);
    }
    assert(names.count == 3 && names[0] == "app-1.0/", "a directory ends with '/'");

    # Extract without the top directory.
    reader = archive.TarReader(compress.DecompressReader(io.File.open(path).value(), compress.Format.Gzip));
    reader.extract(folder, strip_components = 1).value();
    assert(io.File.read_to_string(folder.join("main.pep")).value().starts_with("main"), "extracted");

    io.Directory.remove_all(folder);
    io.File.remove(path);
    return 0;
}

archive.TarReader(source) reads an archive from any io.Reader; wrap the file in a DecompressReader to read a .tar.gz.

• next_entry() moves to the next entry and returns its TarEntry: path, kind (File, Directory, Symlink, HardLink or Other), size, mode, modified (seconds since 1970) and link_target. It returns Empty at the end of the archive.
• The reader is an io.Reader of the current entry’s contents: read, read_all(), lines(). Contents not read are skipped.
• It reads ustar archives with the pax and GNU extensions for long paths, which covers GNU tar, bsdtar, and the .tar.gz snapshots that git archive, GitHub, GitLab and Codeberg make.

extract(target, strip_components = 0) writes the rest of the archive into the directory target:

• It refuses, with an is_invalid_input() error, an entry whose path is absolute or holds a .. component, a \ or a :, so an archive cannot write outside target. archive.safe_components(path) is that check, for readers of other formats: it gives the path’s components, or Empty for an unsafe path.
• strip_components drops leading path components, as tar’s --strip-components does. A GitHub snapshot puts everything under name-version/, which strip_components = 1 removes.
• Files and directories are created, replacing a file already there. A hard link becomes a copy of the file it names. Devices and FIFOs are skipped.
• Each file and directory gets the entry’s modification time and, on Linux and macOS, its permission bits less the umask, as tar does, so a script keeps its executable bit. Setuid, setgid and sticky bits are never applied. A directory gets its mode and time after its contents are written, so a read-only directory can still be filled; one that already existed keeps its own. Windows and WASI apply no permission bits.
• Symlinks are made after everything else, so no file is written through one. A link whose target is absolute or climbs out of target with .., or that would be made inside another symlink, is skipped. Windows, where making a symlink needs Developer Mode or an administrator, skips every symlink.

archive.TarWriter(sink) writes an archive: append_file(path, data), append_directory(path), append_symlink(path, target), append(entry, data) for any header, and append_stream(entry, source) to copy entry.size bytes from a stream. finish() writes the end marker. Paths longer than a ustar header holds get a pax header, so none is cut short.

Zip archives

.zip archives are read and written by the zip package, which builds on compress and archive. It is a package rather than part of the runtime because the package manager needs only .tar.gz; add it with pepper package add justinboswell/pepper-zip --name zip.

import zip;

main(): int {
    var writer = zip.Writer.create("bundle.zip").value();
    writer.add("version.txt", "1.0.0".bytes()).value();
    writer.finish().value();

    var archive = zip.Archive.open("bundle.zip").value();
    for (var entry in archive.entries()) {
        print($"{entry.name}: {entry.size} bytes");
    }
    archive.extract_all("out").value();
    return 0;
}

• It reads and writes stored and DEFLATE entries, ZIP64 (archives and entries past 4 GiB, more than 65,535 entries), and UTF-8 names; names in older archives are decoded as code page 437 (text.CodePage437).
• Entries compressed another way (bzip2, LZMA, zstd) or encrypted are listed, and reading one is an error naming the entry and the method.
• extract_all checks every name with archive.safe_components before writing anything, and each entry’s CRC-32 as it is written.

Statements and semicolons

Every simple statement ends with a ;: a variable declaration, an expression, return, break and continue. So does every declaration that does not end in a block: a module variable, a struct field, a type alias, an import, a re-export and an extern function. A statement or declaration that ends in a block (if, while, for, with, a function, a struct) needs none.

Line breaks, spaces and comments mean nothing to the grammar. A statement can span as many lines as it needs, breaking anywhere between tokens, including before an operator or a ., and several statements can share a line.

# Every simple statement ends with a `;`; line breaks mean nothing.
is_small(n: int): bool {
    return n > 0 && n < 10;
}

main(): int {
    var width = 3;
    var height = 4; var depth = 5;

    # A statement may span several lines, breaking before or after an
    # operator.
    var volume = width * height
        * depth;
    assert(volume == 60, "3 * 4 * 5");

    var in_range = is_small(width)
        && is_small(height)
        && !is_small(volume);
    assert(in_range, "3 and 4 are small; 60 is not");

    var words = Array<String>();
    words.append("line");
    words.append("breaks");
    var long_words = 0;
    # A chain of calls may break before each `.`.
    for (var word in words
        .iterate()
        .filter((w) => w.length > 4)) {  # comments are fine anywhere
        long_words += 1;
    }
    assert(long_words == 1, "one word is longer than four characters");

    # So may a call's arguments.
    assert(volume + words[0].length == 64,
        "60 + 4");
    return 0;
}

A missing ; is an error

Leaving out a ; is an error, reported right after the statement it should end, with a fix that adds it. The language server offers the fix as a quick fix:

main.pep:2:18: error: expected ';'
    2 |     var total = 1
      |                  ^
      |                  ;

Because line breaks do not end anything, a statement missing its ; would otherwise run on into the next line whenever that line can continue it:

x = y
-z

reads as x = y - z; with its ; missing, not as two statements. The error says where the ; belongs when the parse cannot go on.

Control flow

Pepper has the familiar structured control flow of C-family languages: if and else to choose, while and for to repeat, and break, continue and return to leave early.

if and else

if runs a block when its condition is true, and the optional else block when it is false. The parentheses around the condition are optional; the braces around each block are required, even for a single statement.

# Branching with if and else.
classify(n: int): String {
    if n < 0 {
        return "negative";
    } else if n == 0 {
        return "zero";
    } else {
        return "positive";
    }
}

main(): int {
    var temperature = 25;

    # Parentheses around the condition are optional; braces are required.
    if temperature > 30 {
        print("hot");
    } else {
        print("not hot");
    }

    if (temperature > 20) {
        temperature = 20;
    }
    assert(temperature == 20, "clamped to 20");

    assert(classify(-5) == "negative", "negative");
    assert(classify(0) == "zero", "zero");
    assert(classify(7) == "positive", "positive");

    # For a choice between two values, the ternary operator is shorter.
    var parity = temperature % 2 == 0 ? "even" : "odd";
    assert(parity == "even", "20 is even");

    # && and || stop at the first operand that decides the result, so the
    # count check guards the index.
    var readings = Array<int>();
    var starts_high = false;
    if (readings.count > 0 && readings[0] > 100) {
        starts_high = true;
    }
    assert(!starts_high, "an empty array does not start high");
    return 0;
}

The condition is usually a bool, but a number also works: any value other than zero counts as true, as in C. A raw pointer (__ptr<T>) or a function value counts as true when it is not null. A struct counts only if it declares the truth-test operator !!(): bool, which the condition calls; any other struct is an error, so write node !== __null to ask whether a reference is set (see Truth tests and conditions). The same holds for the condition of while and of ?:, the operands of &&, ||, and and or, and the operand of !.

Chains of conditions

else if tests another condition when the ones before it were false. The first true condition’s block runs, and the final else block, if there is one, runs when none was true:

if x > 0 {
    return 1;
} else if x < 0 {
    return -1;
} else {
    return 0;
}

For a choice between two values, the conditional operator condition ? a : b is often shorter than an if.

Guarding a check

&& and || short-circuit, as in C: the right operand is evaluated only when the left one does not already decide the result. A guard can therefore come first in the same condition:

if items.count > 0 && items[0] > 100 {
    print("starts high");
}

When items is empty, items[0] is never read.

while

while repeats its block as long as the condition is true. The condition is checked before each iteration, so the body may run zero times. As with if, the parentheses are optional and the braces are required.

var countdown = 3;
while countdown > 0 {
    countdown -= 1;
}

for

for runs its block once for each element of an Array, each code point of a String, or each value of any type that follows the iterator protocol:

for (var score in scores) {
    total += score;
}

The loop variable can be declared with var or a type (for (int score in scores), for (var score: int in scores)), and the parentheses are optional. Iteration covers the protocol behind for and how to make your own types iterable.

Pepper has no C-style for (init; condition; step) loop. To count, loop over a range: for (var i in 0..count).

with

with enters a scope object for the length of a block and binds what it hands out. The object cleans up when it is destroyed, on every way out of the block:

with (var session = Session("grace")) {
    greet(session.user);
}

Scoped blocks with with covers the protocol and the optional else block.

match

match runs the arm for the case an enum value holds, and the compiler checks that every case is handled:

match (light) {
    Red, Amber => { stop(); }
    Green => { go(); }
}

Enums and match covers patterns and the else arm.

Branch hints: [Likely] and [Unlikely]

[Likely] or [Unlikely] on the line above an if, an else if’s if or a match arm (the else arm too) says how often that branch runs. The optimizer keeps the likely path as straight-line code and moves the unlikely one, such as error handling, out of its way. A hint never changes what the program computes; a wrong one costs only speed.

# Branch hints: `[Likely]` and `[Unlikely]` say which way a branch usually
# goes, so the optimizer keeps the common path straight.
enum Reading {
    Value(celsius: double),
    Missing,
}

parse_digit(c: char): int {
    [Unlikely]
    if (c < '0' || c > '9') {
        return -1;
    } else [Likely] if (c != '0') {
        return c - '0';
    }
    return 0;
}

describe(reading: Reading): String {
    match (reading) {
        [Likely]
        Value(celsius) => {
            return $"{celsius}";
        }
        [Unlikely]
        Missing => {
            return "missing";
        }
    }
}

main(): int {
    assert(parse_digit('7') == 7, "a digit");
    assert(parse_digit('x') == -1, "not a digit");
    assert(describe(Reading.Missing) == "missing", "the rare arm still runs");
    return 0;
}

• [Likely] above an if marks its block, so its else is the unlikely side; [Unlikely] marks the block as the rare one. To mark an else, mark the if the other way.

• In an else if, the attribute goes between else and if: } else [Unlikely] if (x) {.

• A hint is an LLVM branch weight (2000 to 1, as clang gives __builtin_expect), so it matters with optimization (-O1 and up).

• Only one of them, with no arguments, can mark a branch, and no other attribute can:

  main.pep:3:5: error: 'Target' cannot mark an 'if'; only '[Likely]' or '[Unlikely]' can
      3 |     [Target(OS(Linux))]
        |     ^~~~~~~~~~~~~~~~~~~
  

while loops and the arms of a match expression take no hint yet.

break and continue

break leaves the innermost loop immediately. continue skips the rest of the current iteration and goes on with the next one; in a while loop that means checking the condition again, so update the counter before any continue.

# Looping with while and for, and leaving early with break and continue.
main(): int {
    # while repeats as long as its condition is true.
    var countdown = 3;
    var launched = false;
    while countdown > 0 {
        countdown -= 1;
    }
    launched = countdown == 0;
    assert(launched, "counted down to zero");

    # for visits each element of an Array (or any other iterable).
    var scores = Array<int>();
    scores.append(70);
    scores.append(85);
    scores.append(92);
    var total = 0;
    for (var score in scores) {
        total += score;
    }
    assert(total == 247, "sum of the scores");

    # continue skips to the next iteration; break leaves the loop.
    var odd_sum = 0;
    var i = 0;
    while (i < 100) {
        i += 1;
        if (i % 2 == 0) { continue; }
        if (i > 9) { break; }
        odd_sum += i;
    }
    assert(odd_sum == 25, "1 + 3 + 5 + 7 + 9");

    # break and continue apply to the innermost loop.
    var pairs = 0;
    for (var a in scores) {
        for (var b in scores) {
            if (b == a) { break; }
            pairs += 1;
        }
    }
    assert(pairs == 3, "(85, 70), (92, 70), (92, 85)");
    return 0;
}

Both work in while and for loops and always apply to the innermost loop. There are no labeled breaks: to leave several loops at once, set a flag and test it, or move the loops into a function and return from it.

return

return value; leaves the current function and hands value back to the caller. It works from anywhere in the function, including from inside loops. See Functions.

In a function that returns nothing, a bare return; leaves the function early.

Functions

A function is a named block of code that takes parameters and can return a value. Functions declared at the top level of a file are free functions; functions declared inside a struct are methods, covered in Structs.

Declaring a function

Write the name, the parameters in parentheses as name: Type, and the return type after a colon:

area(width: int, height: int): int {
    return width * height;
}

Pepper also accepts a C-style form, with the return type first and each parameter’s type before its name:

int perimeter(int width, int height) {
    return 2 * (width + height);
}

Both forms declare the same kind of function; pick one style and use it consistently. The first form is the one used throughout this book.

# Declaring and calling functions.

import async;

# Parameters are written 'name: Type'; the return type follows the ')'.
area(width: int, height: int): int {
    return width * height;
}

# The C-style form puts the return type first and the type before each name.
int perimeter(int width, int height) {
    return 2 * (width + height);
}

# A function that returns nothing leaves out the return type
# (or writes ': void', or 'void' in front).
# A module-scope counter: const, and changed through an Atomic.
const log_count = async.Atomic<int>(0);
log(message: String) {
    log_count.fetch_add(1);
    print("log: " + message);
}

# Functions can call themselves, and can be declared in any order.
factorial(n: int): long {
    if (n <= 1) { return 1; }
    return n * factorial(n - 1);
}

main(): int {
    assert(area(3, 4) == 12, "3 x 4");
    assert(perimeter(3, 4) == 14, "2 x (3 + 4)");
    assert(factorial(20) == 2432902008176640000, "20!");
    assert(is_even(10), "declared after main, still callable");
    # An argument converts to its parameter's type as assignment does:
    # a double passed to an int parameter truncates toward zero.
    assert(area(2.9, 3) == 6, "2.9 becomes 2");

    log("starting");
    log("done");
    assert(log_count.load() == 2, "logged twice");
    return 0;
}

is_even(n: int): bool {
    return n % 2 == 0;
}

• Order does not matter. A function can call functions declared later in the file, and can call itself.

• The program starts at main. main(): int returns the process’s exit code; return 0 for success. To receive the command-line arguments, declare it main(args: String[]): int instead. See Command-line arguments and exit.

• Calls must match the declaration. Passing the wrong number of arguments is a compile error:

  main.pep:3:12: error: too many arguments to 'add': expected 2, have 3
      3 |     return add(1, 2, 3);
        |            ^~~
  

Functions that return nothing

A function that returns no value leaves out the return type. You can also write : void, or void in front in the C-style form:

log(message: String) { print(message); }
log_line(message: String): void { print(message); }
void log_c(String message) { print(message); }

Such a function ends when it reaches the closing brace, or earlier at a bare return;:

log_positive(n: int) {
    if n <= 0 {
        return;
    }
    print($"{n}");
}

A call to such a function has no value, so it cannot be stored, passed, returned, or used as an operand or condition: var x = log("hi"); reports cannot use a value of type 'void' as variable 'x'.

In a function that returns a value, return; is an error:

main.pep:2:5: error: non-void function 'f' should return a value
    2 |     return;
      |     ^~~~~~

Inferred return types

A function without a return type gets one from its return statements. It returns void when no return has a value, and otherwise the type of the first return that has one, so half(x: double) { return x / 2; } returns a double. A generic function’s return type is inferred for each specialization, so first<T>(a: T, b: T) { return a; } returns an int for first<int>. main with no return type returns an int, and reaching its closing brace exits with 0.

Writing the return type is still clearer for a function that returns a value, and it lets the compiler check each return against it.

Parameters

Parameters are passed by value. For numbers and bool, the function receives its own copy. For a String, an Array or any other struct, the value is a reference, so the function receives another reference to the same object: it can change the object’s contents, and the caller sees the change. Assigning a new object to the parameter does not affect the caller’s variable. Memory and reference counting describes exactly how references are counted when you pass them.

Arguments convert to the parameter’s type the same way assignment does, so you can pass an int where a long or double is expected, a double where an int is expected (it truncates toward zero, like int n = 2.7;), and a String where a struct with an [Implicit] constructor from String (such as io.Path) is expected.

Default parameter values

A parameter can have a default value, written = value after its type. A call that leaves the argument out gets the default. Put parameters with defaults at the end of the list, since arguments are matched from the left.

# Default parameter values.

# Parameters with defaults come last; a call may leave them out.
greet(name: String, greeting: String = "Hello", punctuation: String = "!"): String {
    return greeting + ", " + name + punctuation;
}

# Defaults work with the C-style form too.
int clamp(int value, int low = 0, int high = 100) {
    if (value < low) { return low; }
    if (value > high) { return high; }
    return value;
}

main(): int {
    assert(greet("Ada") == "Hello, Ada!", "both defaults");
    assert(greet("Ada", "Hi") == "Hi, Ada!", "one default");
    assert(greet("Ada", "Hi", ".") == "Hi, Ada.", "no defaults");

    assert(clamp(150) == 100, "clamped to the default high");
    assert(clamp(-5) == 0, "clamped to the default low");
    assert(clamp(-5, -10) == -5, "low given");
    return 0;
}

Defaults work the same way for methods and constructors. To give a later parameter a value without passing every parameter before it, name it (see Named arguments).

Named arguments

A call can name its arguments, name = value, so it reads clearly and can set one defaulted parameter without passing the ones before it:

# Named arguments: `name = value` after the positional arguments.
window(title: String, width: int = 800, height: int = 600, resizable: bool = true): String {
    return $"{title} {width}x{height} resizable={resizable}";
}

struct Point {
    var x: int;
    var y: int;

    construct(this.x = 0, this.y = 0) {}

    moved(dx: int = 0, dy: int = 0): Point {
        return Point(x + dx, y + dy);
    }
}

# 'size = ...' works as well as 'count = ...'; 'n = ...' still works, with a
# deprecation warning.
[Alias("size", "count")]
[Rename("n", "count")]
repeat(text: String, count: int = 1): String {
    var result = "";
    for (var i in 0..count) {
        result = result + text;
    }
    return result;
}

main(): int {
    assert(window("Editor") == "Editor 800x600 resizable=true", "all defaults");
    # Skip width and height.
    assert(window("Editor", resizable = false) == "Editor 800x600 resizable=false", "skip");
    # Named arguments in any order.
    assert(window("Editor", height = 400, width = 1200) == "Editor 1200x400 resizable=true", "any order");
    # Every argument may be named.
    assert(window(title = "Editor", width = 1024) == "Editor 1024x600 resizable=true", "all named");

    # Constructors and methods take them too.
    var p = Point(y = 5);
    assert(p.moved(dy = 2).y == 7, "method");

    assert(repeat("ab", size = 3) == "ababab", "alias");
    return 0;
}

• Positional first. Positional arguments come first and match parameters from the left; named arguments follow, in any order. A positional argument after a named one is an error: positional argument cannot follow a named argument.
• Each parameter once. Naming a parameter that already has an argument is an error: argument for 'width' given twice.
• Every required parameter. A parameter without a default must get an argument: missing argument for parameter 'title' in call to 'window'. A name the function does not have is an error, with a suggestion when one is close: no parameter named 'widht' in 'window'; did you mean 'width'?.
• Order of evaluation. Arguments are evaluated in the order written, then passed to their parameters.
• Everywhere a call is. Free functions, methods, static methods, constructors (a this.x parameter is named x), extension methods, enum methods, generic functions, and calls through a trait value, which use the trait’s parameter names. A method that implements a trait should use the trait’s names, so a call names the same arguments either way: a different name is a warning (parameter 'factor' of 'area' is named 'scale' in trait 'Shape') whose fix renames the parameter.
• Overloads. A member of an overload set without a parameter of a given name is not a candidate, so names can pick between overloads.
• Not through function values. A function type carries no parameter names, so a call through a function value is positional only: cannot name arguments in a call through a function value of type '(int, int) => int'.
• Not to extern functions. Their parameter names are copied from C headers and stay free to change: cannot name arguments in a call to extern function 'CreateFileW'. Wrap the C function in a Pepper function to give it named arguments.

Other names for a parameter

Two attributes on a function give its parameters more names. In both, the declared parameter’s name comes second:

• [Alias("size", "count")] lets a call name parameter count as size too, permanently.
• [Rename("n", "count")] keeps the former name n working after the parameter was renamed to count. Each use warns, like a deprecated declaration, with a fix that renames it.

The first name must not already be a parameter or another name, and the second must be a parameter of the function. A call that names one parameter by two of its names gets argument for 'count' given twice.

Returning several values

A function returns several values as a tuple, and the caller destructures it:

divide(a: int, b: int): (int, int) {
    return (a / b, a % b);
}

var (quotient, remainder) = divide(17, 5);

Overloading

Functions can share a name when their parameter lists differ, in one file, across a module’s files, or across the modules a file imports, and each call picks the best fit for its arguments. See Overloading.

Generic functions

A function can take type parameters in angle brackets after its name, such as first<T>(items: T[]): T. Generics covers them.

Printing with print

print(value) writes a value’s text and a line break to standard output: what interpolating it, $"{value}", would make. That covers a String, numbers, bool (true or false), tuples, and any type with a to_string(). To print several values on one line, interpolate them (print($"total: {n}")), or pass a format string and its arguments, which prints what String.format makes of them (print("{0} of {1}", done, total)).

# print writes a value's text and a line break.
main(): int {
    print("Hello, world!");
    print(42);                            # any value with a text form
    print((1.5, true));                   # (1.5, true)
    var name = "Pepper";
    var count = 42;
    print($"{name} has {count} items");   # interpolate other values
    print("{0} + {1} = {2}", 3, 4, 3 + 4); # or format them: "3 + 4 = 7"
    print("{braces} alone print as written");
    return 0;
}

• With a string literal and no other arguments, the text prints as written: its braces are not a format.
• A value with no text form is an error at the argument:

main.pep:5:11: error: cannot print a value of type 'Foo': it has no 'to_string()' method and no 'to_string' overload
    5 |     print(f);
      |           ^

print writes each line out as it prints it, like Rust’s println!, so the output appears as the program runs even when standard output is a pipe or a file. Text from print and from io.File.stdout() comes out in the order the program wrote it.

A float or double prints its shortest exact text (print(0.5) prints 0.5), and a tuple its elements in parentheses ((1, two)).

Assertions and panics

For checks in your programs, the runtime provides assert(condition, message), which stops the program with message when condition is false, and panic(message), which always stops it. Each is overloaded: the message may be a String, built at run time (assert(n > 0, name + " must be positive")), or a C string, which a string literal picks, so a literal message builds nothing when the assertion holds. See Built-in functions.

A panic flushes what the program printed, writes the location of the failing call and the message to standard error, and aborts:

main.pep:12:5: panic: count must be positive

In a build without -O, a backtrace of the calls that led there follows the message. PEPPER_BACKTRACE=1 turns it on in an optimized build and PEPPER_BACKTRACE=0 turns it off (see Backtraces and the debugger).

The checks the compiler adds report the same way, at the expression that failed: an overflowing operator, a null function value, a match on a null reference enum. So do the runtime’s checking methods, which report their caller’s line, not their own: indexing an Array or String out of range, Array.pop() on an empty array, Optional.value() on an Empty optional, Result.value() on an error, and the like.

They do it with an ordinary default parameter, location: __ptr<char> = __caller_location(). A call that leaves location out gets the place of that call, as file:line:col. Write the same parameter on a function of your own that checks its arguments, and pass location on to assert or panic, so a failure names the line that passed the bad value:

# Reporting the caller's location with `__caller_location()`.

# A check that names its caller's line when it fails, the way `assert`,
# `panic`, `Array` indexing and `Optional.value()` do: the default is the
# location of the call that leaves `location` out.
check_positive(value: int, location: __ptr<char> = __caller_location()): int {
    assert(value > 0, "expected a positive value", location);
    return value;
}

# The location is a C string, `file:line:col`.
here(location: __ptr<char> = __caller_location()): String {
    return String(location);
}

main(): int {
    assert(check_positive(3) == 3, "positive");
    var at = here();
    assert(at.ends_with("functions-caller-location.pep:18:14"), "this call");
    return 0;
}

Written anywhere else, __caller_location() is its own location. A compiler-generated check with no single place to report, such as a call through a null trait value, prints the message alone.

Command-line arguments and exit

main comes in two forms. main(): int takes nothing. main(args: String[]): int receives the program’s command-line arguments: element 0 is the program as it was started, and the arguments typed after it follow in order. Declare the parameter only when the program reads it, as a Windows console program declares argc/argv only when it needs them. Any other parameter list on main is an error, and so is declaring both forms.

pepper build --entry <name> (and pepper run --entry <name>) starts the program in the top-level function name instead, which takes either form of parameter list, as main does. Every main is then left out of the program, so a file can hold several entry points, such as a benchmark beside the tool it measures.

Elsewhere, process.arguments() returns the same array, so code outside main can read the arguments without having them passed down. process.exit(code) ends the program at once with status code, from anywhere, after flushing what was printed. Both are in the process module, so the file needs import process.

import process;

# args holds the program name, then each command-line argument.
main(args: String[]): int {
    if (args.count > 2) {
        print("usage: greet [NAME]");
        process.exit(2);  # ends the program here, with status 2
    }
    var name = "world";
    if (args.count == 2) {
        name = args[1];
    }
    print("Hello, " + name + "!");
    return 0;
}

exit skips everything that would run on the way out of main: locals are not released and destructors do not run. Prefer returning from main, and keep exit for ending from deep inside a call. See Processes.

Functions as values

A function’s name used without a call is a value that you can store in a variable, pass to another function, or return, and a closure such as (x: int) => x * 2 is a function written where it is used. See Function types and closures.

Tuples and multiple return values

A tuple groups a fixed number of values, each of its own type, into one value. Its main use is returning several values from a function:

# A function returns several values as a tuple.
divide(a: int, b: int): (int, int) {
    return (a / b, a % b);
}

# Elements can be of any type, and a tuple can hold another tuple.
describe(n: int): (String, (bool, int)) {
    return ("number", (n % 2 == 0, n * n));
}

main(): int {
    # Read elements by position: t.0, t.1, ...
    var t = divide(17, 5);
    assert(t.0 == 3, "the quotient");
    assert(t.1 == 2, "the remainder");

    # Nested tuples chain: d.1.0 is element 0 of element 1.
    var d = describe(4);
    assert(d.0 == "number", "the name");
    assert(d.1.0 && d.1.1 == 16, "even, and its square");

    # A tuple type can be written out; the literal converts to it.
    var wide: (long, double) = (1, 2);
    assert(wide.0 == 1 && wide.1 == 2.0, "converted elements");
    return 0;
}

Tuple types and values

• A tuple type lists its element types in parentheses: (int, String), (bool, (int, int)). A tuple has at least two elements.
• A tuple value lists its elements the same way: (a / b, a % b). The compiler infers its type from the elements, so (1, "x") is an (int, String).
• Where a tuple type is expected (a declared variable, a parameter, a return value), each element converts to its element type, as it would on its own: var wide: (long, double) = (1, 2);.
• t.0, t.1, … read an element by position, counting from 0. t.1.0 is element 0 of element 1. An element that does not exist is a compile error.
• Elements are read-only. t.0 = 3 is a compile error; build a new tuple instead: t = (3, t.1);.
• Tuple<A, B> is another spelling of (A, B), for places where a type in angle brackets reads better.
• (int, String)? is an optional tuple, Optional<(int, String)> (see Optional values).

Labels

A tuple type can name its elements: (line: int, column: int), and so can a tuple value: (line: 3, column: 7). A label is another name for a position, so p.line and p.0 read the same element:

# Labels name a tuple's elements.
position(): (line: int, column: int) {
    return (line: 3, column: 7);
}

struct Token {
    var text: String = "";
    var at: (line: int, column: int);
}

main(): int {
    var p = position();
    assert(p.line == 3 && p.column == 7, "read by label");
    assert(p.0 == 3, "positions still work");

    # Labeled and unlabeled tuples convert to each other.
    var plain: (int, int) = p;
    assert(plain.1 == 7, "same elements");

    # A labeled value carries its labels into the variable's type.
    var end = (line: 4, column: 1);
    assert(end.line == p.line + 1, "labeled literal");

    var t = Token();
    t.at = (5, 6);
    assert(t.at.column == 6, "a labeled field");
    return 0;
}

• Labels belong to the type you write, not to the value. A labeled tuple and an unlabeled one with the same element types are the same type, so each converts to the other freely.
• Either every element has a label or none does, and labels in one tuple must differ.
• Labels do not pass through a type argument: Optional<(line: int, column: int)> is the same type as Optional<(int, int)>, so its value() returns an unlabeled tuple. Declare a labeled variable to name the elements again.
• var p = (line: 3, column: 7); gives p the labeled type (line: int, column: int). A labeled value takes at least two elements.
• A labeled value initializing or returned as a labeled type must use its labels in order: (column: 7, line: 3) where a (line: int, column: int) is expected is an error, not a swap. An unlabeled value, or a labeled one going to an unlabeled type, converts by position.
• A destructuring assignment lists places alone: (a, b) = (b, a);, never (x: a, y: b) = ....

Destructuring

var (a, b) = value; declares one variable for each element of a tuple:

struct Point {
    var x: int = 0;
    var y: int = 0;
}

min_max(values: Array<int>): (int, int) {
    var low = values[0];
    var high = values[0];
    for (var v in values) {
        if (v < low) {
            low = v;
        }
        if (v > high) {
            high = v;
        }
    }
    return (low, high);
}

main(): int {
    var values = Array<int>();
    values.append(4);
    values.append(-2);
    values.append(9);

    # Destructure the result into new variables.
    var (low, high) = min_max(values);
    assert(low == -2 && high == 9, "both ends");

    # `_` skips an element; a binding may state its type.
    var (_, top: long) = min_max(values);
    assert(top == 9, "only the maximum");

    # `const` makes every binding constant.
    const (first, last) = (values[0], values[2]);
    assert(first == 4 && last == 9, "constants");

    # Assign to existing places. The right side is evaluated first,
    # so this swaps.
    var a = 1;
    var b = 2;
    (a, b) = (b, a);
    assert(a == 2 && b == 1, "swapped");

    var p = Point();
    (p.x, p.y) = min_max(values);
    assert(p.x == -2 && p.y == 9, "fields are places too");
    return 0;
}

• The number of names must match the number of elements.
• _ skips an element.
• A name may state its type, var (_, top: long) = …; the element converts to it. Without one, the variable takes the element’s type.
• const (a, b) = … declares constants.
• Patterns nest: var (id, (name, age)) = … takes an element that is itself a tuple apart.
• A for loop destructures each element: for (var (name, count) in pairs).
• (a, b) = value; assigns to places that already exist: variables, fields (p.x) and array elements. The whole right side is evaluated before any assignment, so (a, b) = (b, a) swaps.

Tuples and references

A tuple is a value, like a number. It is not an object on the heap, and copying it copies its elements. An element that is a reference is shared, not copied, exactly as if you had assigned it to a variable:

• Building a tuple from a variable adds a reference to the object; building it from a function result takes over that result’s reference.
• A tuple holds its references until it goes out of scope or is replaced, then releases them.
• Destructuring moves each element into its variable. After var (a, b) = pair();, a holds the only reference to its object, just as it would after var a = make();.

A tuple is thread-safe when all its elements are, so a module-scope const origin: (int, long) = (0, 0); is allowed.

Collections, comparing and printing

A tuple works anywhere a type does, including as a type argument: Array<(int, String)>, HashMap<(int, int), String>. Iterating a HashMap yields (key, value) tuples:

main(): int {
    # A tuple can be a key: here, a grid position.
    var grid = HashMap<(int, int), String>();
    grid[(0, 0)] = "start";
    grid[(2, 3)] = "goal";
    assert(grid[(2, 3)] == "goal", "looked up by value");

    # Tuples compare element by element.
    assert((1, "a") == (1, "a"), "equal");
    assert((1, "a") != (1, "b"), "different");

    # A HashMap yields (key, value) tuples; destructure them in the loop.
    var ages = HashMap<String, int>();
    ages["ada"] = 36;
    ages["grace"] = 85;
    var total = 0;
    for (var (name, age) in ages) {
        total += age;
    }
    assert(total == 121, "every entry");

    # An array of tuples.
    var pairs = Array<(String, int)>();
    pairs.append(("x", 1));
    pairs.append(("y", 2));
    for (var (name, count) in pairs) {
        print($"{name}: {count}");
    }
    return 0;
}

• == and != compare element by element. Each element compares the way it would on its own: a type with an == operator (such as String) uses it, and any other struct compares by identity (the same object).
• A tuple can be a HashMap key or a HashSet member. Its hash combines the hashes of its elements, so equal tuples hash equally.
• to_string((1, "two")) is (1, two), so a tuple of up to eight values that each have a to_string can be interpolated and printed: print($"{t}").
• copy(t) (see Copying a value) copies each element: a struct element as copy would copy it on its own, anything thread-safe as is.

Matching tuples

A match over a tuple tests all of its elements at once. A tuple pattern lists a pattern for each element: (Rock, Scissors), (Number(v), 1), (4, column). Write the tuple in the match itself with double parentheses, match ((a, b)), or match a tuple value, match (at).

# `match` takes a tuple apart, testing every element at once.
enum Move {
    Rock,
    Paper,
    Scissors,
}

# Who wins: 1 for the first player, 2 for the second, 0 for a draw.
winner(first: Move, second: Move): int {
    match ((first, second)) {
        (Rock, Scissors), (Paper, Rock), (Scissors, Paper) => {
            return 1;
        }
        (Rock, Rock), (Paper, Paper), (Scissors, Scissors) => {
            return 0;
        }
        else => {
            return 2;
        }
    }
}

enum Token {
    Number(value: int),
    Word(text: String),
}

# Literals, cases with values, bound names and `_` mix in one pattern.
describe(token: Token, line: int): String {
    return match ((token, line)) {
        (Number(v), 1) => "a number on the first line",
        (Word(text), _) => text,
        (_, _) => "another number",
    };
}

main(): int {
    assert(winner(Move.Rock, Move.Scissors) == 1, "rock blunts scissors");
    assert(winner(Move.Paper, Move.Scissors) == 2, "scissors cut paper");
    assert(winner(Move.Paper, Move.Paper) == 0, "a draw");

    assert(describe(Token.Word("hi"), 3) == "hi", "a word binds its text");
    assert(describe(Token.Number(7), 1) == "a number on the first line", "a literal element");

    # A name binds its element; `is` tests one pattern.
    var at = (4, 2);
    if (at is (4, column)) {
        assert(column == 2, "bound by the pattern");
    }
    return 0;
}

• Each element takes a case of its enum (Rock, Word(text)), a literal (1, "x", true), a range or a constant (0..9, LIMIT), another tuple pattern, _ for any value, or a name.
• A name binds its element, unless it names a module-scope constant, which the element is compared with, or the element is an enum with a case of that name, which it then matches. So in (Circle, other) over two shapes, Circle is a case and other holds the second shape.
• An arm’s patterns bind the same names, each at the same element: (x, 0), (0, x) is an error, since x would mean a different element depending on which pattern matched.
• The arms must handle every value unless there is an else. A missing value is named with an example: match on '(Shape, int)' does not handle '(Line, _)'. Only enum cases and true/false can be listed in full; other literals and ranges need a pattern with _ or a name at that element.
• A pattern that the arms before it already cover is an error, and an else after arms that cover everything is a warning.
• value is (4, column) tests one tuple pattern, and binds its names as the whole condition of an if or while, as for enums.

Collection literals

A collection literal writes an array, a map or a set in one expression:

trait Shape {
    area(): int;
}

struct Square {
    int side;

    construct(side: int) {
        this.side = side;
    }
}

extend Square with Shape {
    area(): int {
        return side * side;
    }
}

total(values: long[]): long {
    long sum = 0;
    for (var value in values) {
        sum += value;
    }
    return sum;
}

main(): int {
    # An array literal is an Array of its elements' type.
    var primes = [2, 3, 5, 7];
    assert(primes.count == 4 && primes[3] == 7, "an Array<int>");

    # A trailing comma lets a long literal put one element per line.
    var operators = [
        "===",
        "!==",
        "=>",
    ];
    assert(operators[1] == "!==", "an Array<String>");

    # Where an Array type is expected, the elements convert to its element type.
    assert(total([1, 2, 3]) == 6, "an Array<long> argument");
    Shape[] shapes = [Square(2), Square(3)];
    assert(shapes[1].area() == 9, "elements convert to the trait type");

    # A map literal is a HashMap; a repeated key keeps its last value.
    var ages = ["Ada": 36, "Alan": 41];
    assert(ages["Alan"] == 41, "a HashMap<String, int>");

    # An array literal where a HashSet is expected makes a set.
    HashSet<String> keywords = ["if", "else", "if"];
    assert(keywords.count == 2, "duplicates are kept once");

    # [] and [:] are empty, where the type is declared.
    long[] none = [];
    HashMap<String, int> nobody = [:];
    assert(none.is_empty && nobody.count == 0, "empty collections");
    return 0;
}

Arrays

• [a, b, c] is a new Array<T> holding the elements in order. A trailing comma is allowed: [a, b, c,].
• With no other type to go by, T is the first element’s type, and every later element converts to it the way an argument converts to a parameter: [1, 2] is an Array<int>, and [1, "a"] is an error.
• Where an array type is expected (a declared variable, a parameter, a return value, an assignment), T is that type’s element type instead, and every element converts to it: long[] a = [1, 2];, Shape[] s = [square, circle];.
• Nested literals are typed the same way: long[][] grid = [[1], [2, 3]];.
• [] is an empty array. It needs a declared type (long[] none = [];), since it has no element to take a type from:

main.pep:2:13: error: empty array literal has no element type; declare the variable's type or write 'Array<T>()'
    2 |     var a = [];
      |             ^~

Maps

• [k1: v1, k2: v2] is a new HashMap<K, V> holding the entries. K and V come from the first entry, or from the HashMap<K, V> a declared variable, parameter or return type expects.
• A key written twice keeps its last value, as two insert calls would.
• [:] is an empty map, and needs a declared type: HashMap<String, int> none = [:];.

Sets

There is no separate set literal. An array literal where a HashSet<K> or a Set<K> is expected converts to one through the set’s implicit constructor, which keeps each element once: HashSet<String> keywords = ["if", "else"];.

Types of specializations

A literal never changes a collection’s type after it is built: Array<int> and Array<long> are different types, and neither converts to the other.

main.pep:2:21: error: cannot initialize variable 'a' of type 'Array<long>' with a value of type 'Array<int>'
    2 |     Array<long> a = Array<int>();
      |                     ^~~~~~~~~~

Arrays and slices

Array<T> is Pepper’s growable list. Beyond append, indexing and sort, it has the everyday algorithms, and slice gives a function “some of the elements” without copying them:

total(values: ArraySlice<int>): int {
    var sum = 0;
    for (var x in values) {
        sum = sum + x;
    }
    return sum;
}

main(): int {
    # Searching a sorted array.
    var sorted = [1, 3, 3, 5, 8];
    assert(sorted.is_sorted(), "sorted");
    assert(sorted.binary_search(5).value() == 3, "found at 3");
    assert(sorted.binary_search(4).is_empty(), "no 4");
    assert(sorted.upper_bound(3) - sorted.lower_bound(3) == 2, "two 3s");

    # Changing elements in place.
    var a = [4, 4, 1, 2, 2, 7];
    a.dedup();
    assert(a == [4, 1, 2, 7], "adjacent repeats removed");
    a.retain((x) => x % 2 == 0);
    assert(a == [4, 2], "odd elements removed");
    a.resize(4, 0);
    assert(a == [4, 2, 0, 0], "padded with 0");
    var tail = a.split_off(2);
    assert(a == [4, 2] && tail == [0, 0], "split in two");
    tail.fill(9);
    assert(tail == [9, 9], "filled");

    # A slice views part of an array without copying it.
    var numbers = [1, 2, 3, 4, 5];
    var middle = numbers.slice(1, 4);
    assert(middle.count == 3 && middle[0] == 2, "views [2, 3, 4]");
    assert(total(middle) == 9, "passed to a function");
    assert(middle.to_array() == [2, 3, 4], "copied out");
    return 0;
}

Searching a sorted array

• binary_search(item) returns the index of the first element equal to item as a ulong?, in O(log count). The element type must be Comparable (every number, char and String is), and the array sorted in its compare order.
• binary_search_by(order) searches with a function that says whether an element sorts before (negative), at (0) or after (positive) the target.
• lower_bound(item) and upper_bound(item) are the first and last places item could be inserted to keep the array sorted; the elements between them equal item.
• is_sorted() reports whether the array is in that order.

Changing elements in place

• fill(value) sets every element to value.
• retain(keep) removes each element keep returns false for, keeping the order of the rest. keep must not change the array; if it does, retain panics with Array modified during retain.
• dedup() removes each element equal (==) to the one before it; on a sorted array that removes every duplicate.
• resize(count, value) shortens the array, or appends copies of value.
• split_off(index) moves the elements from index on into a new array.

Each counts as modifying the array, so a for loop over it panics on its next step.

Slices

a.slice(start, end) is an ArraySlice<T>: a read-only view of the elements from start up to but not including end. It has count, is_empty, indexing, for loops, slice, to_array, find, contains and the searches above.

A slice is safe by construction:

• It holds a reference to its array, so the array lives as long as the slice does.
• It is fail-fast, like an iterator. Once the array changes (any store, append, remove_at, sort, …), every later use of the slice panics with Array modified while a slice of it is in use, so it can never read an element that moved or a buffer that was freed. Make a new slice after changing the array.

Not yet

• Slices are read-only; there is no slice that writes through to its array, and no a[1..4] syntax: write a.slice(1, 4).
• sort takes a comparer (a.sort((x, y) => x.compare(y))); a sort() with none, sort_unstable, rotate, drain, chunks and windows are not there yet.
• String has no slice type; substr copies.

Function types and closures

Functions in Pepper are values. You can store a function in a variable, a field or an array, pass it to another function, and return it. This lets you choose behavior at run time: a sort order, a callback, a step in a pipeline. A function value is a named function, a method, a constructor, or a closure: an anonymous function written where it is used.

Function types

A function type is written (parameter types) => return type:

=> is right-associative, so the last row is a function that returns a function. A function type carries no parameter names, so a call through a function value passes its arguments by position: named arguments are an error there. A function type can be used anywhere a type can: for variables, parameters, return types, struct fields, generic arguments such as Array<(int) => int>, and type aliases.

Written with shared in front, as in shared () => void, a function type is thread-safe: its values can be passed to other threads. See Sharing function values between threads.

Referring to a named function

The name of a free function, written without a call, is a value of that function’s type. Calling a function value calls the function:

# Function types and references to named functions.
square(x: int): int { return x * x; }
negate(x: int): int { return -x; }

# A parameter can take a function: its type is '(parameter types) => return type'.
apply(f: (int) => int, x: int): int {
    return f(x);
}

twice(f: (int) => int, x: int): int {
    return f(f(x));
}

# Generic functions can take function values too.
apply_twice<T>(f: (T) => T, x: T): T {
    return f(f(x));
}

main(): int {
    # A function's name without a call is a value of its function type.
    var f = square;                 # f: (int) => int
    assert(f(3) == 9, "call through a local");

    var g: (int) => int = negate;   # the type can be written out
    assert(g(4) == -4, "explicit function type");

    # Function variables can be reassigned to another function of the same type.
    f = negate;
    assert(f(6) == -6, "reassigned");

    assert(apply(square, 5) == 25, "pass a function as an argument");
    assert(twice(square, 3) == 81, "(3 * 3) * (3 * 3)");
    assert(twice(negate, 7) == 7, "negating twice");
    assert(apply_twice<int>(square, 2) == 16, "generic");
    return 0;
}

• var f = square; infers f’s type, (int) => int, from the function. An overloaded name, or an overloaded method (p.move), needs a declared type instead, which picks the member.
• An extern function is a value too, of the type its C prototype gives: var f = abs; is an (int) => int. A variadic one, such as snprintf, is not.
• A function-typed variable can be reassigned to any function of the same type.
• A parameter of function type, such as f: (int) => int, lets the caller pass in the behavior. Generic functions can take function parameters too.

Methods, constructors and generic functions

Methods, constructors and specializations of generic functions are values too:

# Methods, constructors and generic functions used as values.
struct Point {
    int x;
    int y;
    construct(this.x = 0, this.y = 0) {}

    norm(): int {
        return x + y;
    }

    shifted(dx: int): Point {
        return Point(x + dx, y);
    }

    # Inside a method, a bare method name is `this.norm`.
    norm_of_this(): () => int {
        return norm;
    }
}

struct Box<T> {
    T value;
    construct(v: T) {
        value = v;
    }

    map<U>(f: (T) => U): Box<U> {
        return Box<U>(f(value));
    }
}

larger<T>(a: T, b: T): T {
    return a > b ? a : b;
}

combine(f: (int, int) => int, a: int, b: int): int {
    return f(a, b);
}

main(): int {
    var p = Point(3, 4);

    # A bound method: the method of one object, which it keeps alive.
    var norm = p.norm;
    assert(norm() == 7, "bound method");
    assert(p.norm_of_this()() == 7, "bare method name");

    # An unbound method takes the object as its first argument.
    var norm_of: (Point) => int = Point.norm;
    assert(norm_of(Point(1, 1)) == 2, "unbound method");

    # A struct's name is its constructor.
    var make: (int, int) => Point = Point;
    assert(make(5, 6).y == 6, "constructor");

    # A generic function with its type arguments names one specialization.
    assert(combine(larger<int>, 2, 9) == 9, "generic function");

    # Where a function type is expected, it picks the specialization.
    assert(combine(larger, 4, 1) == 4, "inferred specialization");

    # A generic method, with its type arguments written or picked by the
    # function type.
    var b = Box<int>(3);
    var to_long = b.map<long>;
    assert(to_long((x: int): long => x * 2).value == 6, "generic method");
    var to_text: ((int) => String) => Box<String> = b.map;
    assert(to_text((x: int) => "three").value == "three", "inferred generic method");

    var steps = Array<(int) => Point>();
    steps.append(p.shifted);
    steps.append(Point(10, 0).shifted);
    assert(steps[1](5).x == 15, "methods in an array");
    return 0;
}

• Bound methods. p.norm keeps a reference to the object, like a closure () => p.norm() that captured p, so the object lives as long as the value does. The expression before the . is evaluated once, when the value is made. A bound method is a function value, not the value the method returns: passing p.name where a String is expected is an error. Call it, p.name(). The methods of an enum whose cases carry nothing are not values at all (see enums).

• Inside a method. A bare method name is a value too, as a bare call is a call: norm means this.norm, and a static method’s bare name means Point.origin. This works in closures, extensions and trait default methods as well. A local or parameter of the same name hides the method. Storing norm (or this.norm) in a field of this would be a reference cycle, and is an error, as for closures.

• Traits and extensions. A method declared in an extension works the same way, and so does a method of a trait-typed value (shape.area), which calls through the trait.

• Generic functions. Where a function type is expected, the generic function’s name alone is enough: the expected type picks the specialization, as a call’s arguments do. var f: (int, int) => int = larger; and combine(larger, 2, 9) both mean larger<int>, and a type parameter that appears only in the return type is bound from the expected return type. With no function type to go by, as in var f = larger;, write the type arguments:

  main.pep:3:13: error: cannot infer the type arguments of 'larger' used as a value; write them (larger<T>) or give the value a function type
  

• Generic methods. A method with type parameters of its own is a value once they are known: written (b.map<long>, Box<int>.map<long>, Box<int>.wrap<int>) or picked by the function type it flows into, as for generic functions: var m: ((int) => String) => Box<String> = b.map; is b.map<String>. Without either, var m = b.map; is an error that asks for them.

• A type with a constructor that takes no arguments. Box<int> on its own names the constructor only when the constructor needs at least one argument; otherwise it is a call, Box<int>(). The same goes for a generic function whose parameters all have defaults.

Storing and returning functions

Function values go wherever other values go: struct fields, arrays, module-level variables and return values. A type alias gives a long function type a short name, and can have type parameters of its own.

# Function values in fields, arrays, globals, and return values.

import async;

square(x: int): int { return x * x; }
negate(x: int): int { return -x; }
increment(x: int): int { return x + 1; }

struct Transform {
    var op: (int) => int;
    construct(this.op = square) {}
    run(x: int): int { return op(x); }
}

# Choose a function at run time and return it.
pick(squared: bool): (int) => int {
    if squared {
        return square;
    }
    return negate;
}

# A module-level function variable. Every module-level variable is const
# and thread-safe: an Atomic lets it change, and a function type every thread
# can reach is declared shared.
const handler = async.Atomic<shared (int) => int>(increment);

# A type alias can name a function type, even a generic one.
type Combine<T> = (T, T) => T;
add(a: int, b: int): int { return a + b; }
fold(values: int[], combine: Combine<int>, start: int): int {
    var total = start;
    for (var v in values) {
        total = combine(total, v);
    }
    return total;
}

# A function that returns nothing has the return type void.
const events = async.Atomic<int>(0);
record(n: int) { events.fetch_add(n); }

main(): int {
    var t = Transform();
    assert(t.run(4) == 16, "the default op squares");
    t.op = negate;
    assert(t.op(4) == -4, "call through a field");

    var pipeline = Array<(int) => int>();
    pipeline.append(increment);
    pipeline.append(square);
    pipeline.append(negate);
    var value = 2;
    for (var step in pipeline) {
        value = step(value);
    }
    assert(value == -9, "-((2 + 1) * (2 + 1))");
    assert(pipeline[1](5) == 25, "call an array element");

    assert(pick(true)(5) == 25, "call a returned function directly");
    var chosen = pick(false);
    assert(chosen(5) == -5, "call a stored returned function");

    assert(handler.load()(1) == 2, "global function value");
    handler.store(square);
    assert(handler.load()(3) == 9, "replaced global");

    var numbers = Array<int>();
    numbers.append(1);
    numbers.append(2);
    numbers.append(3);
    assert(fold(numbers, add, 10) == 16, "10 + 1 + 2 + 3");

    var callback: (int) => void = record;
    callback(2);
    callback(5);
    assert(events.load() == 7, "void function values");
    return 0;
}

• Fields. A field of function type is called like a method: t.op(4). Inside the struct, op(x) and this.op(x) both call it.
• Arrays. pipeline[1](5) indexes the array and calls the element.
• Module-level variables. Every module-level variable is const and thread-safe (see Module-scope variables), so one whose function changes is an Atomic of a shared function type: handler.load()(1) calls the current function and handler.store(square) replaces it.
• Return values. pick(true)(5) calls the function that pick returns.
• void results. A function without a return value has a function type ending in => void, such as (int) => void.

Closures

A closure literal is a parameter list, =>, and a body. The body is an expression or a block:

# Closure literals: anonymous functions that capture values.
struct Counter {
    int count;
    construct(this.count = 0) {}
    add(n: int) { count += n; }
}

apply(f: (int) => int, x: int): int {
    return f(x);
}

# A closure can outlive the function that made it: it keeps its own copy
# of 'n'.
make_adder(n: int): (int) => int {
    return (x) => x + n;
}

struct Scaler {
    int factor;
    construct(this.factor = 1) {}

    # Inside a method, a closure can use 'this' and the struct's members.
    scaler(): (int) => int {
        return (x) => x * factor;
    }
}

main(): int {
    # Parameter types written out: the closure's type is (int) => int.
    var double = (x: int) => x * 2;
    assert(double(21) == 42, "expression body");

    # With a function type to fill, the parameter types can be left out.
    var add: (int, int) => int = (a, b) => a + b;
    assert(add(40, 2) == 42, "types from the variable");
    assert(apply((x) => x * x, 5) == 25, "types from the parameter");

    # A block body, with the return type written after the parameters.
    var clamp = (x: int, low: int, high: int): int => {
        if x < low { return low; }
        if x > high { return high; }
        return x;
    };
    assert(clamp(7, 0, 5) == 5, "block body");

    # Captured values.
    var add_five = make_adder(5);
    assert(add_five(10) == 15, "captured parameter");
    var offset = 100;
    var shift = (x: int) => x + offset;
    assert(shift(1) == 101, "captured local");

    # A captured struct is shared, so the closure can change the object.
    var counter = Counter();
    var bump = () => counter.add(1);
    bump();
    bump();
    assert(counter.count == 2, "shared struct");

    var triple = Scaler(3).scaler();
    assert(triple(4) == 12, "captured this");

    # A closure can return a closure.
    var adder: (int) => (int) => int = (a) => (b) => a + b;
    assert(adder(2)(3) == 5, "curried");
    return 0;
}

• Parameter types. (x: int) => x * 2 writes the parameter type. When the closure goes straight into a slot of function type (a typed variable, a parameter, an assignment, a return, a field), the types come from that slot, so (a, b) => a + b is enough. A parameter of a generic function counts too: passing (x) => x + 1 to apply<T>(f: (T) => T, x: T) with x an int types the closure’s x as int (see Generics). With no slot to take them from, a parameter without a type is an error:

  main.pep:2:14: error: cannot infer the type of parameter 'x'; write it: (x: Type) => ...
  

• Return type. It is inferred from the body, or from the slot. To write it, put it after the parameters: (x: int): long => x.

• Body. An expression body is the value the closure returns. A block body uses return like a function. A closure whose type returns void can have an expression body such as () => counter.add(1); the value is discarded.

• Calling. A closure is called like any function value, and can be called where it is written: ((x: int) => x + 1)(2).

Captured values

A closure can use the local variables and parameters around it. It keeps a copy of each one it uses, made when the closure is created, so it can outlive the function that created it (make_adder above).

A captured variable must never be assigned, before or after the closure is created, inside the closure or outside it. Then the copy and the variable can never differ:

var count = 0;
var f = () => count;
count = 5;   # error

main.pep:4:5: error: cannot assign to 'count' because a closure captures it
main.pep:3:19: note: captured here; a closure keeps a copy, so the variable must not change

The rule applies to ++, -- and compound assignments too. Only the variable is fixed: a captured struct is a reference to the same object, so the closure can call its methods and change its fields (counter above). To share a changing number, capture a struct that holds it, such as a Counter or an Atomic<int>.

this in methods

A closure written in a method can use this, the struct’s fields and its methods. It captures this (one reference to the object), never a copy of the fields, so it sees the fields’ current values. In a trait’s default method, a closure can use this and the trait’s methods the same way.

Storing such a closure in a field of the same object would make the object and the closure keep each other alive forever (a reference cycle), so that direct case is an error:

main.pep:4:15: error: storing a closure that captures 'this' in field 'measure' of 'this' creates a reference cycle that is never freed

Capture a weak reference to the object instead.

Type checking

A function value must match the type it flows into exactly: the same parameter types in the same order and the same return type. The aliases of a primitive type count as the same type, so (i32) => i32 and (int) => int match. A mismatch in an initializer, an assignment, an argument or a return is a compile error, as is calling a function value with the wrong number of arguments:

square(x: int): int { return x * x; }

main(): int {
    var f: (String) => int = square;   # error
    return f(1, 2);                    # error
}

main.pep:4:30: error: cannot initialize variable 'f' of type '(String) => int' with a value of type '(int) => int'
    4 |     var f: (String) => int = square;   # error
      |                              ^~~~~~
main.pep:5:12: error: too many arguments to function of type '(String) => int': expected 1, have 2
    5 |     return f(1, 2);                    # error
      |            ^

The compiler reports one error at a time, so the second appears once the first is fixed.

Sharing function values between threads

A plain function type such as () => void can hold any function value, including a closure that captures a String or an Array. Such values stay on the thread that made them: their reference counts are plain increments, like those of a struct that is not [Shared] (see What threads can share).

A function type written with shared in front, such as shared () => void or shared (long) => void, is thread-safe. Its reference counts are atomic, and its values hold only thread-safe state, so any thread may copy, call and drop them. It goes wherever a thread-safe type is required: the body of a thread (ThreadBody is shared () => void), a field of a [Shared] struct, a module-scope variable, or async.Atomic<shared (int) => int>.

# shared function types: function values that threads can share.
import async;

const total = async.Atomic<long>(0);

# A named function holds no state, so it is always thread-safe.
add_one() {
    total.fetch_add(1);
}

# A [Shared] struct's fields must be thread-safe: a function field is shared.
[Shared]
struct Task {
    const weight: long;
    const run: shared (long) => void;
    construct(this.weight = 1, this.run = (n: long) => {}) {}
}

# A plain function type takes any function of the same signature.
apply(f: (long) => long, x: long): long {
    return f(x);
}

main(): int {
    # A closure converts to a shared type when everything it captures is
    # thread-safe: here nothing but the module-scope Atomic.
    var add: shared (long) => void = (n: long) => { total.fetch_add(n); };
    var task = Task(10, add);

    # A thread body is a shared () => void. This closure captures a
    # [Shared] struct.
    var worker = async.Thread.spawn(() => { task.run(task.weight); });
    var other = async.Thread.spawn(add_one);
    worker.join();
    other.join();
    assert(total.load() == 11, "both threads ran");

    # A shared value can be used where a plain one is expected.
    var step: long = 5;
    var add_step: shared (long) => long = (x: long) => x + step;
    assert(apply(add_step, 1) == 6, "shared value passed as plain");

    # A plain closure may capture anything, but stays on this thread.
    var name = "worker";
    var greet = () => name + " done";
    assert(greet() == "worker done", "plain closure");
    return 0;
}

• What converts to shared. A named function, which holds no state; a method, constructor or generic function value with nothing captured, such as Point.norm or Box<int>; and a closure literal (or a bound method such as p.norm) whose captured values are all thread-safe: numbers, Atomic<T> and other [Shared] structs, shared function values, and the rest of that list. The value must be written where the shared type is expected, so that it is made thread-safe from the start.

• What does not. A closure that captures a value that is not thread-safe is reported at the capture, with a note at the captured variable:

  main.pep:5:46: error: closure passed as 'shared () => void' captures 'name' of type 'String', which is not thread-safe
      5 |     var t = async.Thread.spawn(() => { print(name); });
        |                                              ^~~~
  main.pep:4:9: note: capture a thread-safe value instead, such as an 'async.Atomic<T>' or a '[Shared]' struct
      4 |     var name = "worker";
        |         ^~~~
  

  A closure in a method that uses this or a member captures this, so it is thread-safe only in a [Shared] struct. A value that already has a plain type (a variable, a parameter, a call result) never becomes shared, even when it holds nothing:

  main.pep:3:32: error: cannot initialize variable 'f' of type 'shared () => void' with a value of type '() => void'
      3 |     var f: shared () => void = g;
        |                                ^
  

• From shared to plain. A shared value converts to the plain type of the same signature anywhere: shared (long) => long can be passed to a parameter of type (long) => long. The conversion allocates a small plain function value that holds the shared one and calls it, so the plain copy counts with plain increments while the shared value keeps its atomic ones.

• Inference. A variable initialized with a closure, such as var f = () => 1;, has a plain type. Write the type to make it shared: var f: shared () => int = () => 1;.

• shared is special only directly before a function type; elsewhere it is an ordinary name.

Null function values

A function-typed variable or field that has never been assigned is null. Calling it stops the program with the message called a null function value:

var handler: (int) => int;
handler(1);   # panics: called a null function value

Names and shadowing

A local variable, parameter or field with the same name as a free function hides the function inside its scope. Inside a function with a parameter named square, square means the parameter, not the function.

Memory

A function value is a reference, like a struct value, and follows the same reference-counting rules (see Memory and reference counting). Referring to a named function allocates nothing: every reference to square shares one static function object, and so does a generic function named without its type arguments (larger as an (int, int) => int). A method, constructor or generic function value allocates one small object, like a closure; a bound method’s object holds a reference to its receiver.

Creating a closure allocates one object holding the captured values, like constructing a struct. Copying the closure adds a reference to that object, and when the last reference goes, the object releases what it captured.

A plain function value’s counts are plain increments; a shared one’s are atomic, like a [Shared] struct’s (see Sharing function values between threads).

C function pointers

A C function pointer type, extern (P...) => R, holds a bare address that C can call, not a function value: it takes a named function or a closure that captures nothing, and never a closure that captures values. That is by design; see Passing a Pepper function to C for how a callback gets the state it needs.

Overloading

Several free functions in one file can share a name when their parameter lists differ. Each call picks the one whose parameters fit its arguments best:

# Overloaded free functions: one name, several parameter lists.

import io;

describe(n: long): String { return "a number"; }
describe(x: double): String { return "a fraction"; }
describe(s: String): String { return "some text"; }
describe(s: String, times: int): String { return "text, repeated"; }

# An exact match beats a widening, which beats a conversion; an
# `[Implicit]` constructor comes last.
size(p: io.Path): int { return 1; }
size(n: long): int { return 2; }

main(): int {
    var small: int = 7;
    assert(describe(small) == "a number", "int widens to long");
    assert(describe(2.5) == "a fraction", "exact match");
    assert(describe("hi") == "some text", "a literal promotes to String");
    assert(describe("hi", 3) == "text, repeated", "picked by argument count");

    assert(size(4) == 2, "an integer literal fits a long");
    assert(size("notes.txt") == 1, "only io.Path takes a String, by its [Implicit] constructor");
    return 0;
}

The functions of one name in one file are an overload set, and each is a member of it; the files of one module may share a set, and so do the sets a file imports, the runtime’s, and its own functions of that name. Methods of one name in a struct are a set too, and so are its static methods, its operators, its constructors, and the methods its extensions add.

Declaring overloads

• The parameter lists must differ in the number or the types of the parameters. Parameter names and default values do not count (though named arguments can pick between members that differ in types), and neither does the return type:

  main.pep:2:1: error: functions that differ only in their return type cannot be overloaded
      2 | f(x: int): long { return 2; }
        | ^
  main.pep:1:1: note: previous declaration is here
      1 | f(x: int): int { return 1; }
        | ^
  

  Two functions with the same parameter types and the same return type are a redefinition of 'f'.

• A file’s own functions join imported ones. A file’s functions of a name and the functions its imports bind to that name are one set (see Imported sets merge).

Files of one module share a set

When an import or a re-export takes one name from two files of the same module, and both are functions declared under that name, it takes their union: one set of every member. Here shapes/module.pep re-exports area from two files:

# Each file adds members to `area`; the module exports one set.
export * from "square";
export * from "rect";

export area(side: int): int {
    return side * side;
}

export area(width: int, height: int): int {
    return width * height;
}

import "shapes";

main(): int {
    assert(area(3) == 9, "square.pep's member");
    assert(area(2, 5) == 10, "rect.pep's member");
    return 0;
}

A file of the module sees the members its own file and the module’s files it imports declare (see Visibility). That holds for unexported functions too: functions of one name that files of a module declare, exported or not, are one set wherever those files are imported. Members from different files must still differ in their parameters (redefinition of 'area'). Names that are not all functions, such as two structs Point, and a renaming re-export (export size as area beside an area) are still exported twice.

Imported sets merge

Sets of one name from different modules merge too, as they do in Swift: where two imports bind describe, and where the file declares describe itself, an unqualified describe(…) picks among every member. Here two modules each export one member and the file adds a third:

export describe(n: int): String {
    return "a number";
}

export describe(flag: bool): String {
    return "a flag";
}

import "numbers";
import "flags";

# The file's own `describe` joins the two modules' sets.
describe(text: String): String {
    return "some text";
}

main(): int {
    assert(describe(3) == "a number", "numbers' member");
    assert(describe(true) == "a flag", "flags' member");
    assert(describe("hi") == "some text", "this file's member");
    return 0;
}

Unlike files of one module, two modules may each export a member with the same parameters. That is no error until a call cannot tell them apart:

main.pep:3:22: error: call to 'parse' is ambiguous
    3 | main(): int { return parse(1); }
      |                      ^~~~~
a.pep:1:8: note: candidate function
    1 | export parse(x: int): int { return 1; }
      |        ^~~~~
b.pep:1:8: note: candidate function
    1 | export parse(x: int): int { return 2; }
      |        ^~~~~

A qualifier (a.parse(1)) picks one module’s set. A file’s own member hides an imported member with the same parameters, so a file can replace one member of an imported set. Only functions merge: a struct or variable of the name hides imported functions of it (or, named in an import list, is 'parse' is imported but also declared in this file).

The runtime’s sets

The prelude’s functions, such as the runtime’s print and to_string, are a set too, which a file’s own and imported functions of the name join. Here point.pep adds a print member and the file adds a to_string member, and the runtime’s members still take every other call:

export struct Point {
    var x: int;
    var y: int;

    construct(x: int, y: int) {
        this.x = x;
        this.y = y;
    }
}

# Joins the runtime's `print(String)` wherever it is imported.
export print(p: Point) {
    print($"({p.x}, {p.y})");
}

import "point";

# The file's own `to_string` joins the runtime's.
to_string(p: Point): String {
    return $"Point({p.x}, {p.y})";
}

main(): int {
    var p = Point(1, 2);
    print(p);       # point's member
    print("text");  # the runtime's member
    assert(to_string(p) == "Point(1, 2)", "this file's member");
    assert(to_string(42) == "42", "the runtime's member");
    return 0;
}

A member may not take a runtime member’s parameters, since a call could not tell the two apart. With the same return type (or one left to inference) it is a redefinition:

main.pep:1:1: error: redefinition of 'print'
    1 | print(text: String) {}
      | ^~~~~
runtime/string.pep:1850:8: note: previous definition is here
 1850 | export print(text: String) {
      |        ^~~~~

and with another return type it is the same error as for two members of one file:

main.pep:1:1: error: functions that differ only in their return type cannot be overloaded
    1 | to_string(value: int): int { return value; }
      | ^~~~~~~~~
runtime/string.pep:1621:8: note: previous declaration is here
 1621 | export to_string(value: int): String {
      |        ^~~~~~~~~

Give the function another name or other parameters instead. A struct or variable named like a runtime function hides all of its members.

Members may differ in visibility

Exported members are what other files see; a private member is a candidate only for calls in its own file, or in its module’s files. Here shapes.pep exports area(int) and keeps the two-argument form as a helper:

# One set: `area(int)` is exported; `area(int, int)` is private to this file.
export area(side: int): int {
    return area(side, side);
}

area(width: int, height: int): int {
    return width * height;
}

import "shapes";

main(): int {
    # Only the exported member is a candidate here: `area(2, 3)` would be
    # an error, since `area(int, int)` is private to shapes.pep.
    assert(area(3) == 9, "the exported member");
    return 0;
}

A call that only the private member fits is an error in another file, and its notes list only the exported members:

main.pep:2:22: error: no matching function for call to 'area'
    2 | main(): int { return area(2, 3); }
      |                      ^~~~
shapes.pep:2:8: note: candidate function not viable: requires 1 argument, but 2 were provided
    2 | export area(side: int): int {
      |        ^~~~

Importing the name (import [area] from "shapes", or the whole file) brings every exported member, and import [area as size] renames the whole set. A re-export (export area;, export * from "shapes") passes on the exported members too; a set whose members are all private is re-exported whole.

extern functions do not overload

An extern function does not overload, by design: an extern is a C function, which has one symbol, and keeping one extern per name keeps the binding to C one-to-one. To put a family of C functions such as abs and llabs behind one name, give each extern a name of its own ([Link(name = ...)] binds it to the C symbol) and overload Pepper functions that call them. With optimization on (-O2), LLVM inlines the small wrappers:

# C's `abs` and `llabs` behind one Pepper name. An extern binds one C
# symbol, so each gets its own name, and Pepper functions overload them.
[Link(name = "abs")]
extern int c_abs(int x);
[Link(name = "llabs")]
extern i64 c_llabs(i64 x);

magnitude(x: int): int { return c_abs(x); }
magnitude(x: long): long { return c_llabs(x); }

main(): int {
    assert(magnitude(-3) == 3, "int");
    var big: long = -5000000000;
    assert(magnitude(big) == 5000000000, "long");
    return 0;
}

Overloading the extern itself is an error that says so (extern 'abs' cannot be overloaded; rename it and overload Pepper functions named 'abs' that call it).

How a call picks a member

A member is viable when the call has between its required and total number of parameters and each argument converts to its parameter. For each argument, the conversion has a rank, best first:

One viable member is better than another when none of its arguments ranks worse and at least one ranks better, as in C++. Between two members whose arguments rank the same, a non-generic one is better than a generic one, and of two generic ones the more specialized is better: the one whose parameter types the other’s could take but not the reverse. So describe<A, B>(pair: (A, B)) takes a tuple argument over describe<T>(value: T), which takes anything else. The call picks the member that is better than every other viable one. When there is none, the call is an error that lists the candidates:

main.pep:3:22: error: call to 'f' is ambiguous
    3 | main(): int { return f(1); }
      |                      ^
main.pep:1:1: note: candidate function
    1 | f(x: long): int { return 1; }
      | ^
main.pep:2:1: note: candidate function
    2 | f(x: short): int { return 2; }
      | ^

An integer literal fits every integer type that holds its value equally well, so f(1) above is ambiguous; an int member would take it exactly. Two widenings to types of the same width (a ushort to long and ulong) are ambiguous too; convert the argument yourself (f(n as long)). When no member is viable, each note says why:

main.pep:5:12: error: no matching function for call to 'f'
    5 |     return f(s);
      |            ^
main.pep:1:1: note: candidate function not viable: no known conversion from 'String' to 'int' for 1st argument
    1 | f(x: int): int { return 1; }
      | ^
main.pep:2:1: note: candidate function not viable: requires 2 arguments, but 1 was provided
    2 | f(x: int, y: int): int { return 2; }
      | ^

A call with named arguments considers only the members that have a parameter of each name it uses and get every required parameter, and binds the names before ranking the arguments as above. So two overloads whose later parameters have different names can be told apart by naming one (pick(1, b = 2) against pick(a: int, b: int = 0) and pick(a: String, c: int = 0)). The members it considers must put each named argument at the same position; when they do not, the call is an error: named arguments bind differently in the overloads of 'f'.

The member picked decides the call’s type, so var x = half(9.0); is a double when half(x: double): double is picked. In the editor, hovering the call shows the member it picked and how many others the set has, and go-to-definition goes to that member.

Generic members

A set can mix generic and non-generic members. A generic member is viable when its type arguments can be inferred from the call, and ranks as an exact match for the arguments that inferred them. When a generic and a non-generic member tie, the non-generic one wins. Writing type arguments (describe<int>(7)) considers only the generic members:

# Generic and non-generic overloads, and overloads called from generic code.

# A non-generic overload wins a tie with a generic one.
describe<T>(value: T): String { return "something"; }
describe(value: int): String { return "an int"; }

# Generic overloads can differ in their number of parameters.
last<T>(a: T): T { return a; }
last<T>(a: T, b: T): T { return b; }

kind(n: int): String { return "number"; }
kind(s: String): String { return "text"; }

# Each specialization resolves `kind` for its own `T`.
label<T>(value: T): String { return kind(value); }

main(): int {
    assert(describe(7) == "an int", "non-generic wins the tie");
    assert(describe(1.5) == "something", "only the generic fits");
    assert(describe<int>(7) == "something", "type arguments pick generic overloads");

    assert(last(1) == 1, "one argument");
    assert(last(1, 2) == 2, "two arguments");

    assert(label(3) == "number", "label<int> calls kind(int)");
    assert(label("x") == "text", "label<String> calls kind(String)");
    return 0;
}

A call inside a generic function or a generic struct’s method whose argument types depend on a type parameter is resolved again for each specialization, so label<String> above calls kind(s: String).

An override such as describe<Point>(p: Point) belongs to the generic member with the same number of type parameters and parameters; it is not a member itself.

Methods and operators

A struct’s methods of one name are an overload set, and a call picks among them the same way, whether it is written m.add(x), this.add(x), or add(x) inside a method. Static methods overload among themselves (Money.of(250)), and operators are methods, so +(Money) and +(int) can coexist:

# Overloaded methods, static methods and operators.

struct Money {
    var cents: long;

    construct(long cents = 0) {
        this.cents = cents;
    }

    # Methods of one name in a struct overload like free functions.
    add(other: Money): Money { return Money(cents + other.cents); }
    add(dollars: int, cents: int): Money { return Money(this.cents + dollars * 100 + cents); }

    # Static methods overload among themselves.
    static of(cents: long): Money { return Money(cents); }
    static of(text: String): Money { return Money(text.size as long); }

    # Operators are methods, so they overload by operand type too.
    +(other: Money): Money { return add(other); }
    +(more: int): Money { return Money(cents + more); }
}

main(): int {
    var a = Money.of(250);
    var b = a.add(1, 5);                  # add(int, int)
    assert(b.cents == 355, "two ints");
    assert(a.add(b).cents == 605, "a Money");

    var c = a + b + 10;                   # +(Money), then +(int)
    assert(c.cents == 615, "operators");
    assert(Money.of("four").cents == 4, "static of(String)");

    # A method used as a value takes the member its type names.
    var plus: (Money) => Money = a.add;
    assert(plus(a).cents == 500, "method value");
    return 0;
}

• Unary and binary operators of one symbol are one set: a unary -() and a binary -(other: Money) are told apart by their number of parameters (see Unary operators).

• A static method and an instance method may not share a name, since a bare of(x) inside a method could mean either:

  main.pep:3:12: error: static method 'get' cannot share its name with an instance method of 'S'
      3 |     static get(x: String): int { return 2; }
        |            ^~~
  main.pep:2:5: note: previous declaration is here
      2 |     get(x: int): int { return 1; }
        |     ^~~
  

• In a generic struct, each specialization resolves its own calls: in Holder<int>, has(x: T) takes an int. Two members that become the same after substitution (has(x: T) and has(x: String) in Holder<String>) are only an error when a call cannot tell them apart.

• A method as a value (m.add, Money.of) picks its member from the expected function type, like a free function below; without one the error is cannot infer the type of 'f' from overloaded method 'Money.add'.

Extensions and traits

An extension’s methods join the struct’s overload set of their name, and a trait may declare several methods of one name. Each of a trait’s overloads is implemented by the conforming type’s method with the same parameter types, and a call through a value of the trait type picks among the trait’s members the same way:

struct Square {
    var side: int = 0;

    construct(this.side = 0) {}

    area(): int {
        return side * side;
    }
}

# An extension's methods join the struct's overload set of their name.
extend Square {
    area(scale: int): int {
        return area() * scale;
    }
}

# A trait may declare overloads too; each is its own member.
trait Shape {
    area(): int;
    area(scale: int): int;

    # A default joins the conforming type's set of its name.
    describe(): int {
        return area() * 100 + area(2);
    }
}

# Each trait member is implemented by the method with its parameter types.
extend Square with Shape;

total(shape: Shape): int {
    return shape.area() + shape.area(10);
}

main(): int {
    var square = Square(3);
    assert(square.area(2) == 18, "the extension's overload");
    assert(total(square) == 99, "each call through the trait takes its own member");
    assert(square.describe() == 918, "the default body calls both");
    return 0;
}

• An extension member with a body method’s parameters is redefinition of 'area', with a note at the method it repeats.
• A call sees only the extensions visible in its file (see Visibility): a private extension’s overload is never a candidate in another file, so importing a file can add candidates to a call. If an added candidate makes a call ambiguous, the error’s notes point at each candidate, the extension’s included.
• A trait’s default method is copied into a conforming type that lacks a method with its parameter types, even when the type has other methods of that name; the copy joins their set.
• A missing overload is named with its parameter types: 'Square' does not implement 'area(int)', required by trait 'Shape'.

Constructors

A struct may declare several constructors. A call Span(...) picks among them exactly as a call picks among functions:

struct Span {
    var start: int = 0;
    var length: int = 0;

    # Constructors overload like functions: each takes its own parameters.
    construct(this.length = 0) {}

    construct(start: int, end: int) {
        this.start = start;
        length = end - start;
    }

    construct(text: String) {
        length = text.length as int;
    }
}

main(): int {
    assert(Span().length == 0, "no arguments");
    assert(Span(5).length == 5, "one int");

    var middle = Span(2, 7);
    assert(middle.start == 2 && middle.length == 5, "two ints");

    assert(Span("pepper").length == 6, "a String");

    # As a value, the expected function type picks the constructor.
    var make: (int, int) => Span = Span;
    assert(make(1, 4).length == 3, "the (int, int) constructor");
    return 0;
}

• Two constructors with the same parameter types are constructor of 'Span' cannot be redeclared, with a note at the first.
• No constructor fits is no matching constructor for initialization of 'Span', and a tie is call to constructor of 'Span' is ambiguous; the notes point at each candidate constructor.
• A generic struct’s constructors resolve in each specialization: Pair<int>(1, 2) picks among Pair<int>’s constructors.
• At most one constructor may be [Implicit]: an implicit conversion needs one constructor to call.
• [Deprecated] on one constructor warns only at the calls that resolve to it.
• A constructor as a value (var make: (int, int) => Span = Span;) picks its member from the expected function type, like a function below.

Overloaded functions as values

The name of an overload set, written without a call, is a value only where the expected function type picks one member exactly: a typed variable, an argument, a return from a function with a declared return type, or an assignment. A closure whose parameters have no types, passed to an overloaded function, picks the member whose function parameter has its number of parameters:

# An overloaded function used as a value, and closures passed to overloads.

twice(n: int): int { return n * 2; }
twice(s: String): String { return s + s; }

apply(f: (int) => int, n: int): int { return f(n); }

# Overloads that differ in the type of a function parameter.
run(f: (int) => int): int { return f(10); }
run(f: (int, int) => int): int { return f(10, 20); }

main(): int {
    # The declared type picks the overload.
    var doubler: (int) => int = twice;
    assert(doubler(4) == 8, "twice(int)");

    # So does the parameter it is passed to.
    assert(apply(twice, 5) == 10, "twice(int) again");

    # A closure without parameter types picks the overload of its arity.
    assert(run((a) => a + 1) == 11, "one parameter");
    assert(run((a, b) => a + b) == 30, "two parameters");
    return 0;
}

Without an expected type, the compiler asks for one:

main.pep:4:13: error: cannot infer the type of 'g' from overloaded function 'f'
    4 |     var g = f;
      |             ^
main.pep:1:1: note: candidate function
    1 | f(x: int): int { return 1; }
      | ^
main.pep:2:1: note: candidate function
    2 | f(x: long): int { return 2; }
      | ^
main.pep:4:13: note: declare the type, for example 'var g: (int) => int = f;'
    4 |     var g = f;
      |             ^

An expected type that matches no member is address of overloaded function 'f' does not match required type '(bool) => int'.

Structs

A struct groups related values into one named type, and gives that type behavior through methods. Pepper has no classes and no inheritance: a struct holds data, methods and extensions add behavior, and traits describe what a type can do.

Every struct value is a reference to an object, so assigning a struct or passing it to a function shares the object rather than copying it. The memory chapter explains exactly when objects are created and destroyed.

Declaring a struct

Declare a struct with struct, a name, and its fields in braces. Struct names are PascalCase by convention.

# A struct groups related values into one type.
struct Point {
    var x: int = 0;
    var y: int = 0;
}

# Fields can also be declared C-style, with the type first.
struct Counter {
    int count;          # no initializer: starts at zero
    String label = "clicks";
}

main(): int {
    # Without a constructor, `Point()` makes a Point with every field
    # at its initial value.
    var p = Point();
    assert(p.x == 0 && p.y == 0, "fields start at their initializers");

    p.x = 3;
    p.y = 4;
    assert(p.x * p.x + p.y * p.y == 25, "fields can be read and written");

    var c = Counter();
    assert(c.count == 0, "a numeric field without an initializer is zero");
    assert(c.label == "clicks", "a String field can have an initializer");

    # A struct value is a reference: `q` names the same Point as `p`.
    var q = p;
    q.x = 10;
    assert(p.x == 10, "p and q are the same object");
    assert(p === q, "=== tests whether two references name the same object");
    assert(!(p === Point()), "a new Point is a different object");
    return 0;
}

Things to notice:

• A field is declared like a variable: var x: int = 0; or, C-style, int x = 0;. The initializer is optional.
• A field without an initializer starts at its type’s default: zero for numbers, false for bool, and null for a struct type such as String or another struct. Reading a field through a null reference crashes the program, so give struct-typed fields a value before you use them.
• A struct with no constructor can be created with its name and empty parentheses, Point(). There is no new keyword at the call site.
• p.x reads a field and p.x = 3 writes it.
• a === b is true when a and b refer to the same object, and a !== b when they do not. See Comparing structs for ==.

A struct can have a field whose type is a struct declared later in the file, a field of its own type, or fields that lead back to it through other structs (a Team holding a Player that holds the Team). A struct-typed field holds a reference, so a linked list or a tree is just a struct that names itself:

# A field can hold the struct's own type: each Link points at the next one.
struct Link {
    var value: int;
    var next: Link;

    construct(this.value = 0) {}
}

# Two structs can refer to each other, in either declaration order.
struct Team {
    var name: String;
    var lead: Player;

    construct(this.name = "") {}
}

struct Player {
    var name: String;
    # A weak back pointer: the team owns its lead, so the player's link
    # back to the team must not keep the team alive (see the memory chapter).
    var team: Weak<Team>;

    construct(this.name = "") {}
}

sum(first: Link): int {
    var total = 0;
    var link: Link = first;
    while (link !== __null) {
        total = total + link.value;
        link = link.next;
    }
    return total;
}

main(): int {
    var list = Link(1);
    list.next = Link(2);
    list.next.next = Link(3);
    assert(sum(list) == 6, "the list holds 1, 2 and 3");
    assert(list.next.next.next === __null, "the last link has no next");

    var team = Team("Owls");
    team.lead = Player("Ada");
    team.lead.team = Weak<Team>(team);
    with (var t = team.lead.team) {
        assert(t.name == "Owls", "the player reaches its team");
    }
    return 0;
}

Objects that refer to each other in a loop keep each other alive, so make back pointers such as a child’s parent a Weak<T> (see Cycles leak).

Constructors

A constructor sets up a new object. Declare it with construct, followed by its parameters and a body. Callers create the object by calling the struct’s name like a function.

struct Rect {
    var width: int;
    var height: int;
    var area: int;

    # `this.width = 1` declares a parameter that is stored straight into the
    # field `width`; `1` is its default when the caller leaves it out.
    construct(this.width = 1, this.height = 1) {
        area = width * height;
    }
}

struct Temperature {
    var celsius: float;

    # Ordinary parameters work too, written like a function's: `name: Type`.
    construct(fahrenheit: float = 32.0) {
        celsius = (fahrenheit - 32.0) * 5.0 / 9.0;
    }
}

main(): int {
    var r = Rect(3, 4);
    assert(r.width == 3 && r.height == 4, "arguments fill the fields");
    assert(r.area == 12, "the constructor body runs after the fields are set");

    var tall = Rect(2);
    assert(tall.width == 2 && tall.height == 1, "omitted arguments use their defaults");

    var unit = Rect();
    assert(unit.area == 1, "every parameter has a default, so Rect() works");

    var boiling = Temperature(212.0);
    assert(boiling.celsius == 100.0, "212 F is 100 C");
    assert(Temperature().celsius == 0.0, "the default is 32 F");
    return 0;
}

• A parameter written this.width = 1 stores its argument directly into the field width, before the body runs. The = 1 is required: it is the value used when the caller omits that argument.
• Ordinary parameters are written as in a function, name: Type, with an optional default: fahrenheit: float = 32.0. The C-style form, float fahrenheit = 32.0, is accepted too.
• Inside the body, fields are in scope by name. Use this.name when a parameter has the same name as a field.
• A struct may declare several constructors with different parameter lists; a call picks one by its arguments, as for any overloaded function. At most one of them may be [Implicit]. A struct has at most one destructor.

A this.field parameter must have a default. Leaving it out is an error:

struct Point {
    var x: int;
    construct(this.x) {}
}

main.pep:3:21: error: expected '='
    3 |     construct(this.x) {}
      |                     ^

A struct without a constructor accepts no arguments:

main.pep:7:13: error: too many arguments to 'Point': expected 0, have 2
    7 |     var p = Point(1, 2);
      |             ^~~~~

Note: new is the older, deprecated spelling of construct. It still compiles, with a warning that offers the fix (see Deprecations).

Implicit conversions

A constructor marked [Implicit] also converts. Wherever a value flows into a place whose type is the struct, and the value has the constructor’s parameter type, the compiler calls the constructor for you:

struct Celsius {
    var degrees: double;

    # `[Implicit]` lets a `double` become a `Celsius` wherever one is expected.
    [Implicit]
    construct(double degrees) {
        this.degrees = degrees;
    }
}

struct Label {
    var text: String;

    # Without `[Implicit]`, callers write `Label("...")` themselves.
    construct(String text) {
        this.text = text;
    }
}

describe(t: Celsius): String {
    return (t.degrees > 30.0) ? "hot" : "mild";
}

main(): int {
    assert(describe(35.0) == "hot", "an argument converts");
    var today: Celsius = 21.5;            # a typed variable converts
    assert(describe(today) == "mild", "already a Celsius");

    var label = Label("kitchen");         # no conversion: call the constructor
    assert(label.text == "kitchen", "explicit constructor call");

    var n = 12.0;                         # no slot type: stays a double
    assert(n == 12.0, "untyped local");
    return 0;
}

The standard library uses this for io.Path, which converts from a String, so dir.join("logs") and io.File.open("notes.txt") work without writing io.Path(...), and for Error, so Result<int>.err("bad input") works.

• Where it applies: a variable’s initializer when the variable’s type is written, an assignment, a function, method or constructor argument (operators and a[i] = value included), a call through a function value, and a return from a function with a declared return type.
• Where it does not: the receiver of a method call ("docs".join("x") does not turn "docs" into a Path), a var whose type is inferred (var n = 12.0; stays a double), and __null, which stays a null reference.
• One conversion per value. The value must already have the constructor’s parameter type, or reach it by a widening that loses nothing: a smaller integer to a larger one, an integer literal that fits, float to double, or a struct to a trait it declares. Conversions never chain: if Tag converts from Name and Name from String, a String does not become a Tag.
• Overloads prefer anything else. Among overloads, a member that takes the value as it is, or by any other conversion, beats one that needs an [Implicit] constructor.
• Each conversion is a constructor call, so it allocates a new object. The VS Code extension shows the call as an inlay hint around the converted value, and hovering the value names the constructor. The converted value is a temporary like any constructor call’s result: it is released after the call it was passed to (see Memory and reference counting).
• Only a constructor that can be called with one argument may be [Implicit]: one parameter, or a first parameter followed by parameters that all have defaults. It may not convert from the struct itself or, in a generic struct, from a bare type parameter (construct(T value)):

main.pep:2:5: error: 'Implicit' constructor of 'Span' must be callable with one argument
    2 |     [Implicit]
      |     ^~~~~~~~~~

Conversions are opt-in: a constructor without [Implicit] never runs on its own. When a value would fit such a constructor, the type error says so:

main.pep:6:27: error: cannot pass a value of type 'String' as argument 1 of 'show', which has type 'Label'
    6 | main(): int { return show("x"); }
      |                           ^~~
main.pep:3:5: note: 'Label' has a constructor from 'String': call 'Label(...)', or mark the constructor [Implicit]
    3 |     construct(String text) { this.text = text; }
      |     ^~~~~~~~~

Destructors

A destructor runs when an object is destroyed, which happens when the last reference to it goes away. Declare it with destruct and a body, with no parentheses. Use it to release something the object holds that Pepper does not manage for you, such as a file handle from C.

import async;

# A module-scope counter: const, and changed through an Atomic.
const closed = async.Atomic<int>(0);

struct Connection {
    var name: String;

    construct(this.name = "") {}

    # The destructor runs once, when the last reference to the object goes
    # away. Use it to release whatever the object holds.
    destruct {
        closed.fetch_add(1);
    }
}

main(): int {
    {
        var c = Connection("db");
        assert(closed.load() == 0, "still in use");
    }
    # `c` went out of scope at the closing brace.
    assert(closed.load() == 1, "the destructor ran at the end of the block");
    return 0;
}

You never call a destructor yourself. After it runs, Pepper releases the object’s fields, so a destructor can still read them. The memory chapter lists every point where an object can be destroyed.

Methods

A method is a function declared inside a struct. You call it on an object with a dot, v.length_squared(), and inside it this refers to that object.

struct Vector {
    var x: int = 0;
    var y: int = 0;

    construct(this.x = 0, this.y = 0) {}

    # A method: name, parameters, then the return type after `:`.
    length_squared(): int {
        # Fields can be named directly inside a method...
        return x * x + y * y;
    }

    # ...or through `this`, the object the method was called on.
    dot(other: Vector): int {
        return this.x * other.x + this.y * other.y;
    }

    # Methods can change fields, and can call other methods.
    scale(factor: int) {
        x = x * factor;
        y = y * factor;
    }

    # The return type can also come first, C-style.
    bool is_zero() {
        return length_squared() == 0;
    }

    # A static method belongs to the type, not to one object: there is
    # no `this`. Call it on the type name.
    static unit_x(): Vector {
        return Vector(1, 0);
    }
}

main(): int {
    var v = Vector(3, 4);
    assert(v.length_squared() == 25, "method call");
    assert(v.dot(Vector(1, 1)) == 7, "method with an argument");

    v.scale(2);
    assert(v.x == 6 && v.y == 8, "a method can modify its object");

    assert(Vector().is_zero(), "methods can be called on a temporary");
    assert(Vector.unit_x().x == 1, "static method called on the type");
    return 0;
}

• Methods are written like functions: name(parameters): ReturnType { ... }. Leave out the return type for a method that returns nothing. The C-style form, bool is_zero() { ... }, works too.
• Inside a method, the object’s fields and other methods can be named directly (x, length_squared()), or through this (this.x). A parameter or local with the same name as a field hides the field; use this. to reach the field.
• A bare call names the struct’s own method before a top-level function of the same name, unless no method by that name takes those arguments: then it calls the function. So a copy(): Buffer method can call the free function copy(label).
• A method can change the fields of its object. Because struct values are references, the caller sees the change.
• Calling a method does not copy the object or add a reference to it. The result of a method call is a new reference, like any function result.
• Several methods can share a name when their parameters differ; each call picks the best fit (see Overloading).

Static methods

A method marked static belongs to the type rather than to one object. It has no this, and you call it on the type name: Vector.unit_x(). Static methods are the usual way to offer named constructors, such as the standard library’s Result<int>.ok(42).

Inside the struct, any method, static or not, can call a static method by its bare name: unit_x() in a method of Vector means Vector.unit_x().

# Static methods belong to the type; inside it, they are called by name.
struct Vector {
    var x: double = 0.0;
    var y: double = 0.0;
    construct(this.x = 0.0, this.y = 0.0) {}

    static unit_x(): Vector {
        return Vector(1.0, 0.0);
    }

    # A static method calls another by its bare name.
    static scaled_unit_x(factor: double): Vector {
        var unit = unit_x();
        return Vector(unit.x * factor, unit.y * factor);
    }
}

main(): int {
    var v = Vector.scaled_unit_x(3.0);
    assert(v.x == 3.0 && v.y == 0.0, "called on the type name outside it");
    return 0;
}

Operators

A struct can define what the operators do for it. Declare a method whose name is the operator, written like any other method: ==(other: Money): bool. The C-style form with the return type first, bool ==(Money other), is accepted too.

struct Money {
    var cents: int = 0;

    construct(this.cents = 0) {}

    # `a == b` calls `a.==(b)`. Without this method, `==` on two structs
    # compares identity, like `===`.
    ==(other: Money): bool {
        return cents == other.cents;
    }

    # `!=` is derived from `==` when the struct does not define it.

    # `a < b` calls `a.<(b)`.
    <(other: Money): bool {
        return cents < other.cents;
    }

    # `a + b` calls `a.+(b)` and returns a new Money.
    +(other: Money): Money {
        return Money(cents + other.cents);
    }

    # `-a` calls `a.-()`: a unary operator takes no parameters.
    -(): Money {
        return Money(0 - cents);
    }

    # `a - b` calls `a.-(b)`. The unary and binary `-` overload each other,
    # told apart by their number of parameters.
    -(other: Money): Money {
        return Money(cents - other.cents);
    }

    # `a += b` needs its own method; it is not rewritten to `a = a + b`.
    +=(other: Money): Money {
        cents += other.cents;
        return this;
    }
}

struct Shelf {
    var slots: Array<String>;

    construct() {
        slots = Array<String>();
        slots.append("empty");
        slots.append("empty");
    }

    # An indexer with one parameter handles reads: `shelf[i]`.
    [](index: int): String {
        return slots[index];
    }

    # An indexer with two parameters handles writes: `shelf[i] = value`.
    [](index: int, value: String): String {
        slots[index] = value;
        return value;
    }
}

main(): int {
    var price = Money(250);
    assert(price == Money(250), "== compares cents");
    assert(price != Money(100), "!= compares cents");
    # `===` and `!==` always compare identity: equal cents, different objects.
    assert(price !== Money(250), "!== compares identity");
    var same = price;
    assert(same === price, "=== is true for the same object");

    var total = price + Money(50);
    assert(total.cents == 300, "+ makes a new value");
    assert(price.cents == 250, "+ left its operands alone");

    assert(price < total, "< compares cents");

    var refund = -price;
    assert(refund.cents == -250, "unary - calls -()");
    assert((total - price).cents == 50, "binary - calls -(other)");

    total += Money(25);
    assert(total.cents == 325, "+= updated total in place");

    var shelf = Shelf();
    shelf[1] = "books";
    assert(shelf[1] == "books", "indexer write, then read");
    assert(shelf[0] == "empty", "the other slot is unchanged");
    return 0;
}

When the left operand is a struct that declares the operator, a + b becomes the call a.+(b). The right operand is the method’s single parameter, and it can be any type. These binary operators can be defined:

Keep these rules in mind:

• An operator can be declared once per right-operand type (+(Money) and +(int)), and a + b picks by b’s type, as for any overloaded method.
• Each operator is its own method, with one exception: when a struct defines == but not !=, a != b means !(a == b). A struct that defines == and is used as a HashMap or HashSet key also needs a matching hash<T> (see Hashing and equality). += is not rewritten to a = a + b; define each one you want to use.
• Comparison operators must return bool; any other return type is an error (comparison operator '==' must return 'bool', not 'String'). Logical operators should return bool too. Arithmetic, bitwise and compound assignment operators usually return the struct’s own type; a compound assignment usually changes this and returns it.
• The left operand decides: a + b uses the method on a’s type. For a number on the left, such as 2 * v, see A number on the left.
• Operators that start with < (<, <=, <<, <<=) can only be declared in the name: Type form, <(other: V): bool: in the C-style form the parser reads bool < as the start of generic arguments.

The result of an operator has the type its method returns, so with -(other: V): int, var r = a - b; is an int.

A number on the left

2.0 * v uses the operator of the left operand’s type, double, which a struct cannot change. Declare it in an extension of the number type instead, where this is the number:

# A number on the left of an operator: `2 * v` with a struct `v`.
struct Vector {
    var x: double;
    var y: double;

    construct(this.x = 0.0, this.y = 0.0) {}

    # `v * 2.0` calls `v.*(2.0)`.
    *(scale: double): Vector {
        return Vector(x * scale, y * scale);
    }
}

# `2.0 * v` uses the operator of the left operand's type, so `double`
# declares it in an extension; `this` is the number.
extend double {
    *(v: Vector): Vector {
        return v * this;
    }
}

# `2` is an `int`, which needs its own.
extend int {
    *(v: Vector): Vector {
        return v * (this as double);
    }
}

main(): int {
    var v = Vector(1.0, 2.0);
    var a = v * 2.0;
    var b = 2.0 * v;
    var c = 2 * v;
    assert(a.x == 2.0 && b.x == 2.0 && c.y == 4.0, "both orders");
    # Numbers on both sides still use the built-in operator.
    assert(2 * 3 == 6, "built-in");
    return 0;
}

• The number type is the left operand’s own: 2 is an int and 2.0 a double, so each needs its own extension (extend int, extend double). Without one, 2 * v is invalid operands to binary expression ('int' and 'Vector').

• The operator takes one operand, which may be any type except a number, bool, enum or pointer: numbers on both sides always use the built-in operator.

  main.pep:2:14: error: operator '+' of 'int' cannot take an operand of type 'int': the built-in operator applies
      2 |     +(other: int): int { return 0; }
        |              ^~~
  

• Comparisons work the same way, and 2.0 != v means !(2.0 == v) when the extension declares only ==. Compound assignments (n *= v) do not apply, since the number cannot hold the result.

• The extension is visible like any other: where its file is imported, if it is exported.

Unary operators

A unary operator is a method with no parameters; its operand is this.

The C-style form works here too: V -(), bool !!(). ! and !! must return bool (truth-test operator '!!' must return 'bool', not 'int'), and !, ~ and !! take no parameters. -a on a number is unchanged. A struct may declare both a unary -() and a binary -(other: V): they overload each other, told apart by their number of parameters.

Truth tests and conditions

A condition asks a value “true or false?”. For bool the answer is the value, for a number it is “not zero”, and for a raw pointer (__ptr<T>) or a function value it is “not null”. A struct answers through its truth-test operator, !!(): bool, like C++’s operator bool:

# A struct that declares `!!(): bool` can be used as a condition.
struct Budget {
    var cents: int = 0;

    construct(this.cents = 0) {}

    # The truth test: `if (budget)` calls `budget.!!()`.
    !!(): bool {
        return cents > 0;
    }
}

struct Label {
    var text: String;

    construct(this.text = "") {}
}

spend(budget: Budget, amount: int): int {
    var spent = 0;
    # A condition, an operand of `&&`, and the operand of `!` all call `!!`.
    while (budget && amount > 0) {
        budget.cents -= 1;
        amount -= 1;
        spent += 1;
    }
    if (!budget) {
        print("budget used up");
    }
    return spent;
}

main(): int {
    var budget = Budget(3);
    assert(spend(budget, 2) == 2, "spent 2 of 3");
    assert(budget ? true : false, "a ternary condition calls !! too");
    assert(spend(budget, 5) == 1, "only 1 left");
    assert(!!budget == false, "!!x calls the truth test");

    # A struct without `!!` is not a condition: `if (label)` is an error.
    # Compare with `__null` to ask whether a reference is set.
    var label: Label;
    assert(label === __null, "no Label yet");
    label = Label("sale");
    assert(label !== __null, "now there is one");
    return 0;
}

These are the boolean contexts. In each, a struct value x becomes x.!!():

• the condition of if, else if and while;
• the condition of condition ? a : b;
• each operand of &&, ||, and and or (unless the struct declares && or || itself, which then takes the whole operation);
• the operand of !: without its own ! method, !x is !(x.!!()).

!!x is the truth test itself: on a struct it calls x.!!(); on a bool or a number it is still two negations. Optional declares !!, so if (found) asks whether an optional holds a value.

A struct that does not declare !! cannot be used as a condition at all:

main.pep:6:9: error: 'Node' cannot be used as a condition: declare '!!(): bool' on it, or compare with '__null'
    6 |     if (node) {
      |         ^~~~

A struct value is a reference, but a condition never tests it for null. To ask whether a reference is set, compare it with __null (node !== __null), or better, use an Optional for a value that may be missing. A trait value is treated the same way: it is a condition only when its trait declares !!.

Comparing structs

Without an == method, a == b on two structs compares identity: it is true only when both refer to the same object, exactly like a === b. The same goes for !=. Define == when two distinct objects with the same contents should count as equal, as String and Array do; != then follows from it. To compare field by field, mark the struct [Equatable], which derives == and hash together. === and !== always compare identity, whatever methods the struct declares, so "a" + "b" == "ab" is true while "a" + "b" === "ab" is false.

A struct never equals a number: unless the struct declares an == (or !=) taking one, comparing a struct value such as an Optional with an integer is an error (cannot compare 'Optional<ulong>' with an integer), since it could only ever compare the object itself. Test an optional with is_empty() (or if (found)) and read its value with value().

Indexers

An indexer lets you write object[index]. Declare it as a method named []:

• With one parameter, [](index: int): String, it handles reads: shelf[i].
• With two parameters, [](index: int, value: String): String, it handles writes: shelf[i] = value. The second parameter is the value being stored.

The C-style form, String [](int index), is accepted too. Only parameters without a default count, so either kind can end with a defaulted parameter, such as the location: __ptr<char> = __caller_location() that Array uses to report an out-of-range index at the caller’s line (see Assertions and panics).

A struct can have both. With both, compound assignment through an index (counts[i] += 1) reads with the first and writes with the second. Array and String are indexed this way.

Assignment through a chain of indexes, library["fiction"][0] = "Dune", reads with every index but the last and writes with the last, as if the value read were held in a variable first (var fiction = library["fiction"]; fiction[0] = "Dune";). Since a struct is held by reference, the write changes the object the outer struct holds. Assigning through an index whose type has only the reading indexer is an error (cannot assign through '[]': 'Shelf' declares a '[]' getter but no setter).

# A struct declaring `[]` can be indexed: one parameter reads, two write.
struct Shelf {
    var titles: Map<String, String>;
    var sections: Map<String, Shelf>;

    construct() {
        titles = Map<String, String>();
        sections = Map<String, Shelf>();
    }

    # `shelf["name"]` reads a section.
    [](name: String): Shelf {
        return sections[name];
    }

    # `shelf["name"] = section` writes one.
    [](name: String, section: Shelf): Shelf {
        sections[name] = section;
        return section;
    }

    # `shelf[slot]` and `shelf[slot] = title` overload `[]` by type.
    [](slot: ulong): String {
        return titles[$"{slot}"];
    }

    [](slot: ulong, title: String): String {
        titles[$"{slot}"] = title;
        return title;
    }
}

main(): int {
    var library = Shelf();
    library["fiction"] = Shelf();
    # A chained assignment writes into the shelf the first index reads,
    # like `var fiction = library["fiction"]; fiction[0] = ...;`.
    library["fiction"][0] = "Dune";
    library["fiction"]["classics"] = Shelf();
    library["fiction"]["classics"][0] = "Emma";
    assert(library["fiction"][0] == "Dune", "set through two indexers");
    assert(library["fiction"]["classics"][0] == "Emma", "and through three");
    return 0;
}

Properties

A property is a struct member that is read and written like a field (account.name, account.name = "Savings") but whose get and set accessors can run code. A property that needs somewhere to keep its value gets it from the compiler: its implied storage, reachable as field inside its accessors. You declare a separate private field only when you want one.

Declaring properties

A property is a field declaration followed by an accessor block instead of ;:

# A property is read and written like a field, but its `get` and `set`
# accessors can run code.
struct Account {
    # An auto property: implied storage, read and written by anyone.
    var owner: String { get; set; }

    # Read-only outside the struct: only Account's own code assigns it.
    var balance: long { get; }

    # A custom `set` over implied storage: `field` is the storage and
    # `value` is the new value.
    var name: String {
        get;
        set {
            assert(!value.is_empty, "an account name cannot be empty");
            field = value;
        }
    } = "unnamed";

    # Computed: no accessor is omitted and none uses `field`, so it takes
    # no space.
    var is_empty: bool {
        get {
            return balance == 0;
        }
    }

    # Explicit storage, when you want it.
    var _deposits: ulong;
    var deposits: ulong {
        get {
            return _deposits;
        }
    }

    # An initializer initializes the implied storage.
    var limit: long { get; set; } = 100;

    construct(this.owner = "") {}

    deposit(amount: long) {
        balance += amount;   # Account's own code may set a get-only property
        _deposits += 1;
    }
}

main(): int {
    var account = Account("Ann");
    assert(account.owner == "Ann", "a constructor parameter can set a property");
    assert(account.is_empty, "a computed property runs its get");

    account.owner = "Bob";
    account.name = "Savings";
    assert(account.name == "Savings", "the set stored the name");

    account.deposit(30);
    account.deposit(12);
    assert(account.balance == 42 && account.deposits == 2, "methods update the storage");
    assert(!account.is_empty, "the computed property follows the balance");

    # `account.balance = 0;` would not compile: 'balance' has no 'set'.

    account.limit += 50;   # a get, then a set
    assert(account.limit == 150, "compound assignment reads and writes");
    return 0;
}

• get; and set; with no body are the defaults: get returns the storage, and set stores the new value in it. Either may have a body instead.
• A property has implied storage when an accessor is omitted (get; or set;) or an accessor body uses field. Otherwise it is computed: it takes no space, and its get runs every time it is read.
• An initializer after the accessors (var limit: long { get; set; } = 100;) initializes the storage, so it needs a property that has storage. It does not run set.
• Inside an accessor, field is the storage, and inside set, value is the new value (a by-value parameter). Both are contextual: outside accessors they are ordinary names, so a local or a member called field or value elsewhere keeps working. Inside an accessor, a bare field always means the storage; reach a member of that name as this.field.
• A property must have a get: { set; } alone is an error.
• A property is declared with var and an explicit type; it cannot be const. There are no static properties.

Reading and writing

• p.count calls get, and p.count = x calls set. A default accessor is not a call at all: an auto property ({ get; set; }) compiles to the same loads and stores as a field.
• p.count += 1, p.count++ and the other compound assignments are a get and then a set. p is evaluated once.
• A constructor parameter this.name assigns the property, through its set when it has one. A field initializer and the struct’s own field initialization do not.
• Inside the struct’s methods, a property is reached by its bare name, like a field: balance += amount; is this.balance += amount;.
• A property’s accessors are ordinary method calls for reference counting: get returns a temporary that owns one reference, and value is a by-value parameter, acquired on entry and released on exit.

Read-only properties

{ get; } alone makes a property read-only outside the struct: assigning it from other code is an error at the property’s name.

main.pep:6:7: error: cannot assign to 'balance': it has no 'set' accessor
    6 |     a.balance = 3;
      |       ^~~~~~~
main.pep:2:9: note: 'balance' declared here
    2 |     var balance: long { get; }
      |         ^~~~~~~

The struct’s own constructors and methods may assign a get-only property with implied storage; that writes the storage directly. An extension’s methods are not the struct’s own code: they cannot assign it either.

Properties in traits and extensions

A trait can require a property, var area: double { get; } or { get; set; }, with no accessor bodies. A struct meets the requirement with a property of the same name and type (auto or computed), or with a plain field. Reading or writing the property through a trait value calls the struct’s accessors.

An extension can add computed properties only, since it cannot add storage to the struct:

# A trait can require a property; a struct meets it with a property of the
# same name and type.
trait Shape {
    var area: double { get; }
    var label: String { get; set; }
}

struct Square {
    var side: double { get; set; } = 1.0;
    var area: double {
        get {
            return side * side;
        }
    }
    var label: String { get; set; } = "square";
}

extend Square with Shape;

# An extension can add computed properties, which need no storage.
extend Square {
    var perimeter: double {
        get {
            return side * 4.0;
        }
    }
}

describe(shape: Shape): String {
    shape.label = "seen";
    return $"{shape.label}: {shape.area}";
}

main(): int {
    var square = Square();
    square.side = 3.0;
    assert(square.area == 9.0, "the computed area follows the side");
    assert(square.perimeter == 12.0, "an extension's property reads like any other");
    assert(describe(square) == "seen: 9.0", "a trait value reaches the struct's accessors");
    assert(square.label == "seen", "the set through the trait reached the struct");
    return 0;
}

An extension property that would need storage is an error:

main.pep:5:9: error: an extension cannot add storage: property 'y' must be computed, with accessor bodies that do not use 'field'

An enum can declare computed properties too, under the same rule, and no set, since its values never change.

Properties of [Shared] structs

The fields of a [Shared] struct are const, so the storage of its properties is too:

• A property with implied storage must be { get; }, and only the struct’s constructors assign it. A set, with or without a body, is an error at set, with a note at [Shared].
• A computed get over the struct’s const fields is allowed, as any method is.

A [Shared] struct’s properties are get only, by design: an assignment x.p = v would read as a write to a struct whose fields cannot change. To change what a thread-safe member holds (an Atomic<int>, or a value behind a Mutex), declare a method that says what it does, such as store_hits(value) or add_name(name).

How properties compile

The compiler lowers a property to plain members: a field for its storage (named after the property when its get is the default, __field_name otherwise), a getter method __get_name() and, with a set, a setter __set_name(value). Every read and write of the property becomes a storage access or an accessor call once the receiver’s type is known. The accessor methods appear in debuggers and in profiles under those names.

Value structs

A struct is normally a reference to an object on the heap. A struct marked [Value] is a value instead, like a number or a tuple: it is stored inline in whatever holds it (a local, a field, an array element), and assigning it, passing it, or returning it copies it. Creating one allocates nothing.

# A value struct is stored inline and copied like a number.
[Value]
struct Span {
    var start: int;
    var end: int;

    construct(this.start = 0, this.end = 0) {}

    length(): int {
        return end - start;
    }

    # Assigns a field of `this`, so it changes the value it is called on.
    grow(by: int) {
        end = end + by;
    }
}

# A reference struct holding a value: the span is part of the line's object.
struct Line {
    var text: String;
    var span: Span;

    construct(this.text = "") {}
}

# The parameter is a copy: growing it does not change the caller's span.
grown(span: Span, by: int): Span {
    span.grow(by);
    return span;
}

main(): int {
    var a = Span(2, 5);
    var b = a;          # a copy
    b.grow(10);
    if (a.length() != 3 || b.length() != 13) {
        return 1;
    }

    var c = grown(a, 1);
    if (a.length() != 3 || c.length() != 4) {
        return 2;
    }

    # Through a reference, the change lands in the object's own span.
    var line = Line("hello");
    var same = line;
    line.span.grow(5);
    if (same.span.length() != 5) {
        return 3;
    }

    # An element read from an array is a copy: change it, then store it back.
    var spans = Array<Span>();
    spans.append(a);
    var first = spans[0];
    first.grow(1);
    spans[0] = first;
    if (spans[0].length() != 4) {
        return 4;
    }

    # Values compare field by field.
    if (a != Span(2, 5)) {
        return 5;
    }
    return 0;
}

Use a value struct for small types that describe a value rather than an identity: a span, a point, a color. An enum can be a value too (see Value enums); Optional and Result are. Keep a reference struct for anything that is shared and changed through several names, or that is large.

Declaring one

Put [Value] on its own line above the struct. Everything else is written as for any struct: fields, constructors, methods, operators, generic parameters, and extensions.

[Value]
struct Point {
    var x: int;
    var y: int;

    construct(this.x = 0, this.y = 0) {}
}

A variable or field of a value struct type that is not given a value holds the zero value: every field zero, false, or null.

Copies

• var b = a; makes b an independent copy. Changing b leaves a as it was.
• A parameter is a copy of the argument. A function can change its parameter without the caller seeing it; return the changed value instead.
• A field of a value struct is part of whatever holds it. In a reference struct, line.span.grow(5) changes the span inside line’s object, and every reference to that object sees it.
• Reading an element of an array, or the result of any call, gives a copy. To change an element, read it into a variable, change it, and store it back (spans[0] = first;).

A field that is itself a reference (a String, an Array) is copied as a reference, so both copies share that object, as two variables holding the same String do. Its count is kept like any other reference’s: copying the value acquires it, and the copy going out of scope releases it. Use copy for a deep copy.

Methods that change this

In a method, this is the value the method was called on, not a copy, so a method that assigns a field (end = end + by;), or calls another method that does, changes that value. The compiler works out which methods change this from their bodies. Calling one on something that would only change a copy is an error, because the change would be lost:

main.pep:9:12: error: cannot call mutating method 'grow' on a temporary 'Span'
    9 |     make().grow(1);
      |            ^~~~
main.pep:9:5: note: 'make' returns a copy; store it in a variable, change it, and assign it back
    9 |     make().grow(1);
      |     ^~~~

The same holds for assigning a field of a call’s result (spans[0].end = 3;) and for changing a const variable’s value. A closure made in a method holds a copy of this, so it cannot change this either.

Comparing and hashing

== and != compare two values field by field, and hash combines the fields’ hashes, unless the struct declares its own == or hash (declare both together; see Hashing and equality). A value has no identity, so === and !== are errors on it, and it is never null: comparing one with __null is an error too.

What a value struct cannot do

Each of these is an error at the code to change:

• ===, !==, or __null on a value.
• __weak<T> or __refcount of a value: there is no object to count.
• A destruct block: nothing destroys a value. Its reference fields are still released.
• [Shared]: a value struct is thread-safe when its fields are, and needs no atomic counts.
• A field whose type is the struct itself, directly or through other value structs: the value would be infinitely large. Hold it through a reference struct or an Array instead.
• A parameter or result of an extern function: pass a pointer to C instead.

Value structs as trait values

A value struct can declare traits like any struct. Where it flows into a slot of a trait type, such as an argument of type Iterator<int>, it is boxed: copied into a new object that the trait value refers to. The box is a copy, so a mutating method called through the trait value changes the box and not the original, and two conversions of one value make two boxes. Copying the trait value shares the box, as for any trait value.

The runtime’s iterators (ArrayIterator, StringIterator, the map and set iterators, ChannelIterator, and the map, filter, enumerate and zip adapters) are value structs, so a for loop over an Array, a String or any map or set allocates no iterator.

Hashing and equality

HashMap<K, V> and HashSet<K> find a key by hashing it with hash<K> and comparing it with ==. What those two mean for a type decides which keys count as the same. OrderedMap<K, V> finds keys the same way. For maps that keep their keys in order, see Maps and sets.

Struct keys use identity by default

A struct is a reference. Unless it says otherwise, two references are the same key only when they refer to the same object. Another object with equal fields is a different key:

struct Point {
    int x;
    int y;

    construct(this.x = 0, this.y = 0) {}
}

main(): int {
    var origin = Point(0, 0);
    var visits = HashMap<Point, int>();
    visits[origin] = 1;

    # A struct key is found by identity: the same object finds its entry...
    assert(visits.contains(origin), "the stored object");

    # ...but another object with equal fields is a different key.
    assert(!visits.contains(Point(0, 0)), "an equal but distinct object");
    return 0;
}

Identity is right for objects that stand for one thing: a connection, a node in a graph, a task. It is wrong for a struct that describes a value, such as a point or a record looked up by its fields.

Deriving both with [Equatable]

Mark the struct [Equatable], and the compiler writes both halves from its fields, so they cannot drift apart. It compares and hashes like a tuple of its fields: a field of a struct type uses that struct’s == and hash, a String its content, and a null field equals only null. Mark a field [Equatable(exclude = true)], or [Equatable(include = false)], to leave it out of both; a field with neither takes part:

# `[Equatable]` derives `==` and the hash from the fields, so they always
# agree.
[Equatable]
struct Person {
    String name;
    int id;
    # Not part of the identity: two records for the same person may differ.
    [Equatable(exclude = true)]
    String nickname;

    construct(this.name = "", this.id = 0, this.nickname = "") {}
}

# An enum whose cases carry values compares the case and then its values.
[Equatable]
enum Token {
    Word(text: String),
    Number(value: int),
    End,
}

main(): int {
    HashSet<Person> people = [Person("Ada", 1, "A"), Person("Ada", 1, "Countess")];
    assert(people.count == 1, "equal people are one member");
    assert(people.contains(Person("Ada", 1)), "the nickname is ignored");
    assert(!people.contains(Person("Ada", 2)), "a different id");
    assert(Person("Ada", 1) == Person("Ada", 1, "B"), "== is derived");

    var counts = HashMap<Token, int>();
    counts[Token.Word("pepper")] = 2;
    counts[Token.End] = 1;
    assert(counts[Token.Word("pepper")] == 2, "found by case and value");
    assert(Token.Word("salt") != Token.Word("pepper"), "different values");
    assert(Token.Number(0) != Token.End, "different cases");
    return 0;
}

• An enum whose cases carry values can be [Equatable] too: two values are equal when they hold the same case and its values are equal.
• A generic struct derives both for each specialization, from the fields its type arguments give it.
• include and exclude are bools, and saying both in a way that contradicts (include = true, exclude = true) is an error. On the struct itself, [Equatable] takes no arguments.
• An [Equatable] struct cannot also declare == or override hash<T>; either is an error. To compare some other way, drop the attribute and declare both by hand (below).
• An Array field compares by its elements but hashes by its address, so it adds nothing to the hash. Equal keys still hash equally; keys that differ only in such a field share a hash, which costs speed. The same goes for an Array in a tuple.
• [Equatable] does not apply to a value struct or an enum whose cases carry nothing: they already compare and hash by content.

Keying a struct by its content

To decide yourself what counts as equal, give the struct both halves of the pair:

• an == operator that says when two keys are the same, and
• an override of hash<T> for the struct (see Overriding a generic function for one type), hash<Point>(value: Point): u64.

struct Point {
    int x;
    int y;

    construct(this.x = 0, this.y = 0) {}

    # Two points are equal when their coordinates are...
    ==(other: Point): bool {
        return x == other.x and y == other.y;
    }
}

# ...so equal points must hash equally: hash the same fields `==` compares.
# A tuple hashes each element in turn, which combines them.
hash<Point>(value: Point): u64 {
    return hash<(int, int)>((value.x, value.y));
}

struct Person {
    String name;
    int id;
    # Not part of the identity: two records for the same person may differ.
    String nickname;

    construct(this.name = "", this.id = 0, this.nickname = "") {}

    ==(other: Person): bool {
        return id == other.id and name == other.name;
    }
}

# A String field hashes by its content, through hash<String>.
hash<Person>(value: Person): u64 {
    return hash<(String, int)>((value.name, value.id));
}

main(): int {
    var visits = HashMap<Point, int>();
    visits[Point(1, 2)] = 1;
    visits[Point(1, 2)] = visits[Point(1, 2)] + 1;   # the same key
    assert(visits.count == 1, "one entry");
    assert(visits[Point(1, 2)] == 2, "found by content");
    assert(Point(1, 2) != Point(2, 1), "!= is the negation of ==");

    HashSet<Person> people = [Person("Ada", 1, "A"), Person("Ada", 1, "Countess")];
    assert(people.count == 1, "equal people are one member");
    assert(people.contains(Person("Ada", 1)), "the nickname is ignored");
    assert(!people.contains(Person("Ada", 2)), "a different id");
    return 0;
}

The two must agree: keys that are == must have the same hash. The simplest way to keep that promise is to hash exactly the fields that == compares, by hashing a tuple of them: hash<(int, int)>((value.x, value.y)). A tuple’s hash combines its elements’ hashes, and each element uses its own type’s hash, so a String field contributes its content. Unequal keys may share a hash. That costs speed, not correctness.

With == declared, != is its negation, as for any struct. The struct may also overload == for other types (==(rhs: int)); the map and set compare keys with the == that takes the struct itself.

Keep these rules in mind:

• Declare both or neither. With == but no hash<T>, two equal keys usually hash differently, so a lookup would miss an entry that is there. With hash<T> but no ==, keys would still compare by identity, so an equal object would never find another’s entry. Either is a compile error when the struct is used as a HashMap or HashSet key:

  main.pep:5:5: error: 'Point' declares '==' but no 'hash<Point>', so as a HashMap or HashSet key, equal values will not find each other
      5 |     ==(other: Point): bool {
        |     ^~
  note: declare 'hash<Point>(value: Point): u64' hashing the fields '==' compares, or remove '==' and mark 'Point' '[Equatable]' to derive both
  

  The runtime’s own structs are not checked. An Array key’s == compares elements but its hash is its address, so find it with the same Array object, not an equal one.

• Don’t change a key’s fields while it is in a map or set. The entry stays where its old hash put it, so lookups by its new or its old fields both miss it. Remove it, change it, then insert it again.

• One override per program. hash<Point> replaces hash<T> for Point everywhere, including inside HashMap, so it may be declared in only one file, and that file must declare Point or be in its module (see overriding a generic function).

• The hash is not keyed, so it does not resist keys chosen by an attacker to collide.

Value structs compare and hash by their fields

A value struct has no identity, so == and hash already compare and hash it field by field. Declare your own pair only to change what counts as equal, here to ignore case:

# A value struct compares and hashes by its fields with no code at all.
[Value]
struct Cell {
    int row;
    int column;

    construct(this.row = 0, this.column = 0) {}
}

# A value struct may still declare its own pair, here to ignore case.
[Value]
struct Tag {
    String text;

    construct(this.text = "") {}

    ==(other: Tag): bool {
        return text.lower() == other.text.lower();
    }
}

hash<Tag>(value: Tag): u64 {
    return hash<String>(value.text.lower());
}

main(): int {
    var board = HashMap<Cell, String>();
    board[Cell(0, 0)] = "rook";
    assert(board[Cell(0, 0)] == "rook", "fields decide");

    var tags = HashSet<Tag>();
    tags.insert(Tag("Pepper"));
    assert(tags.contains(Tag("PEPPER")), "case is ignored");
    return 0;
}

Ordering with Comparable

A type whose values sort in one order declares the Comparable trait. It asks for one method, compare(other), which returns a negative number, zero or a positive number as the value sorts before, with or after other, and gives the type the rest:

• the operators <, <=, > and >=;
• min(other), max(other) and clamp(low, high) (which panics when low sorts after high);
• a place as a Map key or Set element, in that order;
• the constraint T: Comparable in a generic function, whose body can then use all of the above on a T.

struct Version {
    var major: int;
    var minor: int;

    construct(this.major = 0, this.minor = 0) {}

    # The one method Comparable asks for.
    compare(other: Version): int {
        var order = major.compare(other.major);
        if (order != 0) {
            return order;
        }
        return minor.compare(other.minor);
    }
}

extend Version with Comparable;

# A generic function asks for an order with `T: Comparable`.
largest<T: Comparable>(items: Array<T>): T {
    var best = items[0];
    for (var item in items) {
        best = best.max(item);
    }
    return best;
}

main(): int {
    # `<`, `<=`, `>` and `>=` come from `compare`.
    assert(Version(1, 2) < Version(1, 10), "1.2 sorts before 1.10");
    assert(Version(2, 0).min(Version(1, 9)).major == 1, "min");
    assert(Version(3, 0).clamp(Version(1, 0), Version(2, 0)).major == 2, "clamp");

    # Numbers and strings are Comparable too.
    assert(largest([3, 9, 2]) == 9, "numbers");
    assert(largest(["pear", "apple"]) == "pear", "strings");
    assert((15).clamp(0, 10) == 10, "clamp a number");

    # A Comparable struct is a Map key, in its order.
    var releases = Map<Version, String>();
    releases[Version(2, 0)] = "second";
    releases[Version(1, 5)] = "first";
    assert(releases.first().value().1 == "first", "sorted by compare");

    # Sorting takes the order as a comparer.
    var versions = [Version(2, 1), Version(1, 5)];
    versions.sort((a, b) => a.compare(b));
    assert(versions[0].major == 1, "sorted");
    return 0;
}

A type that declares its own < (or min, or any of the others) keeps it; the trait’s version fills in only what the type leaves out.

compare must give a total, consistent order: the same two values always compare the same way, a.compare(b) has the opposite sign of b.compare(a), and if a sorts before b and b before c, a sorts before c. Map, Set and sorting depend on it.

Numbers, char and String

Every number type and char is Comparable by value, and String by content, the order of String.compare. Their compare returns -1, 0 or 1 (String.compare any negative or positive number).

float and double compare in a total order: NaN sorts after every number and with every other NaN, and -0.0 sorts with 0.0. Their <, <=, > and >= keep IEEE behavior, false whenever a NaN takes part, while compare, clamp and Map keys follow the total order, so a NaN key cannot break a map.

Not yet

• Array.sort() takes a comparer: items.sort((a, b) => a.compare(b)) sorts in the elements’ own order. A sort() with no comparer comes once the published toolchain that builds Pepper has the compiler fix this needs.
• Tuples and Optional are not Comparable, and Comparable is not derived from a struct’s fields: a struct writes its compare, as Version does above.

Maps and sets

The standard library has three kinds of map, which differ in the order they keep their keys in, and a compact set of small integers, BitSet:

All of them share one API: m[key] reads (a missing key reads as the default of V, and is not inserted) and m[key] = value writes; insert, get, try_get (an optional, Empty when the key is absent), contains, remove, count, is_empty and clear. A for loop visits a map’s entries as (key, value) tuples and a set’s members one by one. Adding or removing an entry while a loop iterates the map panics (“Map modified during iteration”), as it does for Array and HashMap; changing the value of a key that is present is allowed.

Sorted: Map and Set

Map<K, V> keeps its entries sorted by key, on a red-black tree. Besides iterating in order, it answers questions about the order:

• first() and last(): the entries with the smallest and largest key.
• lower_bound(key): the first entry whose key is at least key; upper_bound(key): the first whose key is greater.
• reversed(): iterates from the largest key down.
• range(from, to): iterates the keys from from up to, not including, to.

Each of the four queries returns an optional (key, value) tuple, Empty when there is no such entry. Set<K> is the same tree without values, and its queries return an optional member. An array converts to a Set, so an array literal can initialize one.

main(): int {
    var scores = Map<String, int>();
    scores["carol"] = 91;
    scores["alice"] = 84;
    scores["bob"] = 77;

    # Entries come out sorted by key.
    var names = "";
    for (var (name, score) in scores) {
        names = names + name + " ";
    }
    assert(names == "alice bob carol ", "key order");

    # Order queries return an optional (key, value) tuple.
    assert(scores.first().value().0 == "alice", "smallest key");
    assert(scores.lower_bound("b").value().0 == "bob", "first key >= b");
    assert(scores.upper_bound("carol").is_empty(), "nothing after carol");

    # A key range: from "a" up to, not including, "c".
    var in_range = 0;
    for (var (name, score) in scores.range("a", "c")) {
        in_range += 1;
    }
    assert(in_range == 2, "alice and bob");

    # A Set keeps sorted members; an array converts to one.
    Set<int> primes = [7, 2, 5, 3];
    var digits = 0;
    for (var p in primes.reversed()) {
        digits = digits * 10 + p;
    }
    assert(digits == 7532, "descending");
    return 0;
}

How keys are ordered

Map and Set order keys with the generic function compare<K>(a, b), which returns a negative number, zero or a positive number as a sorts before, equal to or after b. Two keys that compare equal are the same key.

• Numbers and char compare by value, and String by content (the same order as String.compare). A NaN float or double key sorts after every number (see Ordering with Comparable).
• A Comparable struct, or one that declares a < operator, sorts by it: the generic compare asks a < b and b < a.
• Any other struct declares Comparable, or overrides compare<T> for itself, as a hashed key overrides hash<T> (see Overriding a generic function for one type).

# A struct with a `<` operator sorts by it.
struct Version {
    int major;
    int minor;

    construct(this.major = 0, this.minor = 0) {}

    <(other: Version): bool {
        return major < other.major or (major == other.major and minor < other.minor);
    }
}

# A struct without one overrides `compare<T>` for itself.
struct Point {
    int x;
    int y;

    construct(this.x = 0, this.y = 0) {}
}

compare<Point>(a: Point, b: Point): int {
    return a.x != b.x ? a.x - b.x : a.y - b.y;
}

main(): int {
    var releases = Map<Version, String>();
    releases[Version(1, 10)] = "third";
    releases[Version(0, 9)] = "first";
    releases[Version(1, 2)] = "second";
    assert(releases.first().value().1 == "first", "0.9 sorts first");
    assert(releases.last().value().1 == "third", "1.10 sorts last");

    var points = Set<Point>();
    points.insert(Point(2, 1));
    points.insert(Point(1, 5));
    # An equal point (compare returns 0) is the same member.
    assert(!points.insert(Point(1, 5)), "already a member");
    assert(points.first().value().x == 1, "sorted by x");
    return 0;
}

The order must be consistent: the same two keys must always compare the same way, and if a sorts before b and b before c, a sorts before c. A struct key whose fields change while it is in a map breaks that promise.

Insertion order: OrderedMap

OrderedMap<K, V> hashes its keys like HashMap, and iterates its entries in the order their keys were first inserted, like a Python dict. Setting the value of a key that is present keeps its place; removing a key and inserting it again moves it to the end. The other entries keep their order when one is removed.

main(): int {
    var config = OrderedMap<String, String>();
    config["name"] = "pepper";
    config["version"] = "0.2";
    config["license"] = "MIT";

    # Setting a key that is present keeps its place.
    config["name"] = "Pepper";

    # Removing a key and adding it again moves it to the end.
    config.remove("version");
    config["version"] = "0.3";

    var keys = "";
    for (var (key, value) in config) {
        keys = keys + key + " ";
    }
    assert(keys == "name license version ", "insertion order");

    if (config.try_get("license") is Value(license)) {
        assert(license == "MIT", "found");
    }
    assert(config.try_get("author").is_empty(), "absent");
    return 0;
}

Use it where the order of the input matters, such as the keys of a configuration file that should be written back as they were read.

Small integers: BitSet

BitSet is a set of non-negative ints that stores one bit per possible member, so a set whose largest member is m takes about m / 8 bytes however many members it holds. It suits visited flags, masks, and sieve or liveness tables over small integers; for sparse or large integers, use a HashSet<int>.

It has the set API above (insert, contains, remove, count, is_empty, clear) and iterates its members in ascending order. insert grows the set as needed and reserve(n) makes room for 0 to n - 1 ahead of time; it never shrinks. Inserting a negative number panics, while contains and remove of one return false. Changing the set while a loop iterates it is allowed: the loop sees the members above its position as they are when it reaches them.

The set operations come in two forms: union, intersection, difference and symmetric_difference return a new set, and union_with, intersect_with, difference_with and symmetric_difference_with change the set in place. is_subset and is_disjoint compare two sets. Two sets are ==, and hash equally, when they hold the same members whatever their capacity, so a BitSet works as a HashMap or HashSet key. An array converts to a BitSet, so an array literal can initialize one.

main(): int {
    # A sieve: every number below 50 starts out as a candidate.
    var composite = BitSet(50);
    var primes = BitSet();
    for (var n in 2..50) {
        if (composite.contains(n)) {
            continue;
        }
        primes.insert(n);
        var multiple = n * n;
        while (multiple < 50) {
            composite.insert(multiple);
            multiple = multiple + n;
        }
    }
    assert(primes.count == 15, "15 primes below 50");

    # Members come out in ascending order.
    var first = "";
    for (var p in primes) {
        if (p > 11) {
            break;
        }
        first = $"{first}{p} ";
    }
    assert(first == "2 3 5 7 11 ", "ascending");

    # Set operations, by value or in place.
    BitSet odd = [1, 3, 5, 7, 9, 11];
    var odd_primes = primes.intersection(odd);
    assert(odd_primes.count == 4, "3, 5, 7 and 11");
    assert(odd_primes.is_subset(primes), "a subset");
    odd.difference_with(primes);
    assert(odd == BitSet([1, 9]), "1 and 9 are odd but not prime");
    return 0;
}

Queues: Deque and PriorityQueue

Two collections take elements out in an order other than an Array’s:

An Array can stand in for either, but removing its first element takes O(n), and keeping it sorted takes O(n) per insert.

Deque

A Deque (a double-ended queue) is a ring buffer that grows when full: push_back, push_front, pop_back and pop_front add and remove at the two ends, front() and back() read them, and d[i] reads or writes the element i places from the front. It is the queue of a breadth-first search, a sliding window, or an undo history that drops its oldest entry.

# Breadth-first search: a Deque is the queue of nodes to visit.
main(): int {
    # Each node's neighbors: 0 - 1 - 2 - 4 and 0 - 3 - 4.
    int[][] edges = [[1, 3], [0, 2], [1, 4], [0, 4], [2, 3]];
    int[] hops = [0, -1, -1, -1, -1];

    Deque<int> queue = [0];
    while (!queue.is_empty) {
        var node = queue.pop_front();
        for (var next in edges[node as ulong]) {
            if (hops[next as ulong] >= 0) {
                continue;
            }
            hops[next as ulong] = hops[node as ulong] + 1;
            queue.push_back(next);
        }
    }
    assert(hops[4] == 2, "two hops from node 0 to node 4");

    # Both ends work: a window of the last three readings.
    var window = Deque<int>();
    for (var reading in [4, 8, 15, 16, 23]) {
        window.push_back(reading);
        if (window.count > 3) {
            window.pop_front();
        }
    }
    assert(window.front() == 15 and window.back() == 23, "the last three");
    assert(window[1] == 16, "indexed from the front");
    return 0;
}

An array converts to a Deque, so an array literal can initialize one. count, is_empty, capacity, reserve and clear work as they do on an Array. A for loop visits the elements from front to back; changing the deque while a loop iterates it panics (“Deque modified during iteration”). Popping, or reading front() or back(), of an empty deque panics, as does an index past the back.

PriorityQueue

A PriorityQueue is a binary heap: push adds an element in O(log n), pop removes the greatest in O(log n), and peek() reads the greatest without removing it. It is the frontier of Dijkstra’s and A* searches, a scheduler’s run queue, or the k largest values of a stream.

# A scheduler: the job with the earliest deadline runs first.
struct Job {
    var name: String;
    var deadline: int;

    construct(name: String, deadline: int) {
        this.name = name;
        this.deadline = deadline;
    }
}

main(): int {
    # The comparer is reversed, so the smallest deadline is the greatest.
    var jobs = PriorityQueue<Job>((a, b) => b.deadline.compare(a.deadline));
    jobs.push(Job("backup", 30));
    jobs.push(Job("email", 5));
    jobs.push(Job("report", 12));
    assert(jobs.peek().name == "email", "the earliest deadline");

    var order = "";
    while (!jobs.is_empty) {
        order = $"{order}{jobs.pop().name} ";
    }
    assert(order == "email report backup ", "by deadline");

    # Comparable elements need no comparer: the greatest comes out first.
    PriorityQueue<int> scores = [72, 95, 88, 61];
    assert(scores.pop() == 95, "the top score");
    var rest = scores.into_sorted_array();
    assert(rest == [61, 72, 88], "the rest, ascending");
    return 0;
}

Elements are ordered by compare<T>, so numbers, String, and any Comparable type need nothing more. To order by something else, pass a comparer to the constructor: a function that returns a negative number, zero or a positive number as its first argument sorts before, with or after its second. For the smallest first, reverse the comparer, (a, b) => b.compare(a). Elements that sort together come out in no particular order.

An array converts to a PriorityQueue, and PriorityQueue<T>(items, compare) builds one from an array with a comparer; both take O(n), and copy the array. into_sorted_array() empties the queue and returns its elements from smallest to greatest. pop and peek of an empty queue panic.

Neither type is [Shared]: like an Array, each stays on one thread.

Enums and match

An enum is a type with a fixed set of named cases. A value of the enum holds exactly one of them. Use an enum where you would otherwise pass an integer code or a string, so the compiler checks that only the listed cases flow through, and that a match handles each one.

There are two kinds:

• In an enum whose cases carry nothing (Red, Green), each case is an integer. Such an enum is a value type, like int.
• When a case carries values (Circle(radius: int)), the enum is a reference type, like a struct. See Cases that carry values.

# An enum names a fixed set of cases; a slot of the enum type holds one.
enum Suit {
    Clubs,
    Diamonds,
    Hearts,
    Spades,
}

# A representation sets the stored integer type; a case may give its value.
enum Status: u8 {
    Ok,
    NotFound = 44,
    Failed,
}

struct Card {
    Suit suit;
    int rank = 1;
}

main(): int {
    var card = Card();
    assert(card.suit == Suit.Clubs, "a slot starts at the case whose value is 0");
    card.suit = Suit.Hearts;
    assert(card.suit != Suit.Spades, "cases compare with == and !=");

    # 'as' turns a case into its integer; the reverse is not allowed.
    assert((Suit.Hearts as int) == 2, "cases number from 0");
    assert((Status.Failed as int) == 45, "numbering continues after an explicit value");
    assert(sizeof<Status>() == 1, "Status is stored as a u8");
    return 0;
}

Declaring an enum

enum Name { ... } lists the cases, separated by commas; a comma after the last case is optional. Case names are PascalCase, like types (see naming conventions). A case may share a type’s name (String(value: String)); a string literal in the enum’s methods is still a String, and String(...) there calls the case.

Each case is an integer. The first case is 0 and each case after it is one more than the one before. A case can give its own value with = value, and numbering continues from there:

enum Status: u8 {
    Ok,             # 0
    NotFound = 44,  # 44
    Failed,         # 45
}

A value must be an integer constant: a literal such as -1 or 0x20, or a character such as 'y'. Two cases cannot have the same value.

The type after the colon is the representation, the integer type the enum is stored as. It can be any integer type (u8, short, int, long, and so on). Without one, the enum is stored as an int. Every case value must fit in the representation.

A case can carry a [Target] attribute, so a platform can have cases that others lack. A dropped case does not renumber the others.

Using enum values

This section is about enums whose cases carry nothing.

Name.Case is a value of the enum type. Such an enum is a value type, like int: it is copied, not reference counted, and it can be stored in locals, fields, arrays and module-scope constants, and passed to and returned from functions.

• == and != compare two values of the same enum. Other operators apply only when the enum declares them (see Operators and indexers).
• An enum does not mix with integers or with other enums: int x = Color.Red and Color c = 0 are errors, and so is comparing a Color with a Size.
• value as int (or any integer type) gives a case’s integer value. The reverse, 1 as Color, is an error, since the integer may not name a case; name the case, or use from_value.
• A slot of an enum type that is not given a value (a field, or a local declared without one) holds the case whose value is 0, or the first case when no case is 0.
• sizeof<Name>() is the size of the representation.
• An enum works wherever an integer does: as a HashMap key or HashSet element, in an Atomic<Name>, and in an extern function’s signature, where C sees the representation (an int unless the enum names another).

Cases that carry values

A case can carry values, declared like parameters: Circle(radius: int). An enum with such a case is a reference type: each value is an object, reference counted like a struct.

# Cases that carry values: each case is a constructor, and a `match`
# pattern binds the values of the case it matches.
enum Shape {
    Circle(radius: int),
    Rect(width: int, height: int),
    Square(side: int),
    Point,

    area(): int {
        match (this) {
            Circle(r) => { return 3 * r * r; }
            Rect(w, h) => { return w * h; }
            Square(s) => { return s * s; }
            Point => { return 0; }
        }
        return 0;
    }
}

# A generic enum can name itself: a list is empty, or a value and the rest.
enum List<T> {
    Empty,
    Cons(head: T, tail: List<T>),
}

length(list: List<String>): int {
    match (list) {
        Empty => { return 0; }
        # `_` skips a value.
        Cons(_, tail) => { return 1 + length(tail); }
    }
    return 0;
}

main(): int {
    var shapes = Array<Shape>();
    shapes.append(Shape.Circle(2));
    shapes.append(Shape.Rect(3, 4));
    shapes.append(Shape.Point);
    var total = 0;
    for (var s in shapes) {
        total += s.area();
    }
    assert(total == 24, "12 + 12 + 0");

    # Several patterns in one arm bind the same names.
    var side = 0;
    match (Shape.Square(5)) {
        Rect(w, _), Square(w) => { side = w; }
        else => {}
    }
    assert(side == 5, "a square's side");

    var names = List<String>.Cons("a", List<String>.Cons("b", List<String>.Empty));
    assert(length(names) == 2, "two names");
    assert(names.name() == "Cons", "name() spells the case");
    return 0;
}

• Name.Case(values...) makes a new value, like a constructor call, and Name.Case alone is a case that carries nothing. An enum’s values are made only by its cases: Shape(...) is an error.
• A case that carries values must be given them: Shape.Circle without (radius) is an error.
• The values are fixed once made. There is no way to change them, so a value can be shared freely. To change one, make a new value.
• Each case that carries nothing is a single object that every use shares. It is never freed and costs no allocation, however often it is used.
• A slot of the enum type that is not given a value holds null, as a struct slot does. === and !== compare identity, and so does ==, unless the enum is [Equatable].
• Mark the enum [Equatable] to derive == and hash from its cases: two values are equal when they hold the same case with equal values, so they work as HashMap and HashSet keys.
• An enum can have type parameters (enum List<T>), and its cases can hold the enum itself, directly or through other types, so lists and trees are enums.
• The enum can be [Shared] when every value its cases carry is thread-safe (see What threads can share). An enum whose cases carry nothing is stored as an integer and is always thread-safe. It can conform to a trait with extend Name with Trait, like a struct, and its methods can come from an extend block too.
• Cases cannot have explicit values (= 3), and the enum has no representation type (: u8), since its values are not integers.

Value enums

An enum whose cases carry values can be marked [Value], like a value struct. Each value is then stored inline in whatever holds it, and copied when assigned, passed or returned, instead of being an object. Making one allocates nothing, which suits small enums that are made often, such as Optional and Result, which are both value enums.

[Value]
enum Shape {
    Circle(radius: int),
    Rect(width: int, height: int),
    Point,
}

• Its cases share one storage: a value is as large as its largest case, plus the tag that says which case it holds (sizeof<Shape>() is 12: the tag, then room for Rect’s two ints, which Circle’s radius reuses).
• A value enum is never null. A slot that is not given a value holds the first case, with every value it carries zero, false, or null: an unset Shape is Circle(0).
• == compares the cases and their values; ===, !== and __null are errors.
• Its cases cannot hold the enum itself, since the value would be infinitely large. Use a reference enum for lists and trees.
• Everything else a value struct cannot do applies too, and so does boxing when it flows into a trait value.

Methods

An enum can declare methods after its cases. Inside a method, this is the value the method was called on, and a bare call of another method of the enum (next()) calls it on this. A static method is called on the enum itself (Light.first()). A method can be generic (choose<T>), with its type arguments inferred or written out (light.choose<String>(...)).

# An enum can declare methods after its cases; `this` is the value.
enum Light: u8 {
    Red,
    Amber,
    Green,

    may_go(): bool {
        return this == Light.Green;
    }

    next(): Light {
        match (this) {
            Red => { return Light.Green; }
            Amber => { return Light.Red; }
            Green => { return Light.Amber; }
        }
        return this;
    }

    # A bare call of another method acts on `this`.
    after_two(): Light {
        return next().next();
    }

    # A method can be generic, like any function.
    choose<T>(stop: T, go: T): T {
        return may_go() ? go : stop;
    }

    static first(): Light {
        return Light.Red;
    }
}

main(): int {
    var light = Light.first();
    assert(!light.may_go(), "red means stop");
    assert(light.next().may_go(), "green follows red");
    assert(light.after_two() == Light.Amber, "then amber");
    assert(light.choose("wait", "walk") == "wait" && Light.Green.choose(0, 1) == 1, "a generic method");

    # Every enum has name() and from_value().
    assert(light.name() == "Red", "name() spells the case");
    var found = Light.from_value(2);
    assert(found.is_ok() and found.value() == Light.Green, "2 is Green");
    assert(!Light.from_value(7).is_ok(), "no case has the value 7");

    # Enums key hash maps and fill atomics, like integers.
    var waits = HashMap<Light, int>();
    waits[Light.Red] = 30;
    assert(waits[Light.Red] == 30, "an enum is a hash key");
    return 0;
}

For an enum whose cases carry nothing, this is passed by value, like an int: a method cannot change the value it was called on. Return a new case instead, as next() does. Such an enum can also declare a trait with extend Light with Describe { ... }, which makes it meet the constraint T: Describe (see numbers, bool and enums); it is still never a trait value. For an enum whose cases carry values, this is the object, as in a struct’s method; its values still cannot change.

Operators and indexers

An enum can declare operators and an indexer the way a struct does: a method named after the operator (<(other: Level): bool) or []. For an enum whose cases carry nothing, a < b calls Level.< with a as this.

# An enum can declare operators and an indexer, as a struct does.
enum Level: u8 {
    Low,
    Mid,
    High,

    # `a < b` calls `Level.<`: the cases rank in order.
    <(other: Level): bool {
        return (this as int) < (other as int);
    }

    # `level + 1` moves up a level, stopping at the top.
    +(steps: int): Level {
        var next = Level.from_value((this as int + steps) as u8);
        return next.is_ok() ? next.value() : Level.High;
    }

    # `-level` mirrors it.
    -(): Level {
        return match (this) {
            Low => Level.High,
            Mid => Level.Mid,
            High => Level.Low,
        };
    }

    # `level[i]` reads, like any indexer.
    [](bit: int): bool {
        return ((this as int) >> bit) & 1 == 1;
    }
}

main(): int {
    var level = Level.Low;
    assert(level < Level.Mid && !(Level.High < level), "cases rank in order");
    assert(level + 1 == Level.Mid && level + 5 == Level.High, "a step up");
    assert(-level == Level.High, "mirrored");
    assert(Level.Mid[0] && !Level.Mid[1] && Level.High[1], "bits");
    return 0;
}

Its values never change and it already compares with == and !=, so such an enum cannot declare ==, !=, a compound assignment (+=), an indexer that assigns ([](index, value)) or the truth test !!, and its operators are not static.

Properties

An enum can also declare computed properties after its cases, var name: T { get { ... } }, which are read like fields (size.ounces). Inside the enum, a bare property name reads it on this.

# An enum can declare computed properties after its cases, read like
# fields: `size.ounces`, not `size.ounces()`.
enum Size {
    Small,
    Medium,
    Large,

    var ounces: int {
        get {
            return match (this) {
                Small => 8,
                Medium => 12,
                Large => 16,
            };
        }
    }

    # Inside the enum, a bare property name reads it on `this`.
    var cups: int {
        get { return ounces / 8; }
    }
}

# The same works for an enum whose cases carry values.
enum Shape {
    Circle(radius: int),
    Square(side: int),

    var area: int {
        get {
            return match (this) {
                Circle(r) => 3 * r * r,
                Square(s) => s * s,
            };
        }
    }
}

main(): int {
    var size = Size.Medium;
    assert(size.ounces == 12 && Size.Large.cups == 2, "value enum properties");
    assert(Shape.Square(4).area == 16 && Shape.Circle(2).area == 12, "properties that read the payload");
    return 0;
}

An enum value has nowhere to keep anything and never changes, so an enum’s property has a get with a body that does not use field, and no set:

main.pep:6:9: error: property 'n' of enum 'E' must be computed: give 'get' a body that does not use 'field'
main.pep:6:38: error: property 'n' of enum 'E' cannot have a 'set' accessor: enum values are immutable

Built-in methods

Every enum has these methods without declaring them, and cannot declare methods of the same names:

from_value is the checked way back from an integer (from a file, a C library or the network) to a case, since as only goes the other way.

match

match (value) { ... } runs the arm for the case that value holds:

# 'match' runs the arm of the case a value holds, and must handle every case.
enum Light {
    Red,
    Amber,
    Green,
}

next(light: Light): Light {
    match (light) {
        Red => { return Light.Green; }
        Amber => { return Light.Red; }
        Green => { return Light.Amber; }
    }
    return light;
}

may_go(light: Light): bool {
    match (light) {
        Green => { return true; }
        else => { return false; }
    }
    return false;
}

wait_seconds(light: Light): int {
    match (light) {
        Red, Amber => { return 30; }
        Light.Green => { return 0; }
    }
    return 0;
}

main(): int {
    var light = Light.Red;
    var changes = 0;
    while (!may_go(light)) {
        light = next(light);
        changes += 1;
    }
    assert(changes == 1, "red turns green");
    assert(wait_seconds(Light.Amber) == 30, "one arm handles two cases");
    assert(wait_seconds(light) == 0, "a pattern may name the enum");
    return 0;
}

• Each arm is one or more patterns, separated by commas, then => and a block. A pattern is a case name (Red) or the case qualified by its enum (Light.Red).
• A pattern for a case that carries values can bind them: Rect(w, h) declares w and h in its arm, holding the case’s values in order. The bindings are const. _ skips a value. A pattern lists all of its case’s values or, written without parentheses (Rect), none. Each value can also be a pattern of its own (see Nested patterns).
• Patterns that share an arm must bind the same names, with the same types (Rect(w, _), Square(w)).
• An else => { ... } arm, last, handles every case the other arms do not.
• The arms must handle every case. A missing case is an error that names it, located at match; the language server offers a quick fix that adds an empty arm for each missing case. An else that can never run, because the other arms handle every case, is a warning.
• Handling a case twice is an error.
• In a match statement, break, continue and return inside an arm act on the enclosing loop or function, as they would inside an if.

The value is evaluated once, before any arm runs. A match on a null value of an enum whose cases carry values panics with match on a null 'Name'; a value enum is never null.

match expressions, is, and literal patterns

# `match` produces a value, `is` tests one case, and a `match` on an
# integer, character, `bool` or `String` compares with literals.
enum Shape {
    Circle(radius: int),
    Rect(width: int, height: int),
    Point,
}

enum List {
    Empty,
    Cons(head: int, tail: List),
}

area(s: Shape): int {
    return match (s) {
        Circle(r) => 3 * r * r,
        Rect(w, h) => w * h,
        Point => 0,
    };
}

keyword(word: String): int {
    return match (word) {
        "import" => 1,
        "export", "extern" => 2,
        else => 0,
    };
}

# The arms' values are numbers of different types (`0` is an `int`,
# `length` a `ulong`), so the `match` has their common type, `ulong`, and
# converts to the `int` this function returns.
length_of(word: String): int {
    return match (word) {
        "" => 0,
        else => word.length,
    };
}

main(): int {
    var total = area(Shape.Rect(2, 3)) + keyword("extern");

    # `is` binds only in the block of the `if` or `while` it is the
    # condition of.
    var s = Shape.Circle(1);
    if (s is Circle(r)) {
        total += r;
    }

    var list = List.Cons(1, List.Cons(2, List.Empty));
    while (list is Cons(head, tail)) {
        total += head;
        list = tail;
    }

    var point = Shape.Point is Point;
    if (point && !(s is Rect)) {
        total += 100;
    }

    # A `match` on an integer needs an `else`: literals cannot list every
    # value.
    var size = match (total) {
        0 => "none",
        1, 2, 3 => "few",
        else => "many",
    };
    assert(size == "many", "total is past three");
    assert(length_of("four") == 4 && length_of("") == 0, "lengths convert");
    assert(total == 6 + 2 + 1 + 3 + 100, "every step adds up");
    return 0;
}

• A match that produces a value can go wherever a value can: after var x =, return, in an argument. Each arm is patterns => value, and arms are separated by commas (one after the last is allowed). It follows the rules above: a pattern binds names for its arm’s value, and the arms must handle every case unless there is an else. The value has the first arm’s type, and every other arm’s value must convert to it. When the arms are numbers of different types, the value has their common type, as C’s ? : does (int and long give long), and converts from it wherever it goes (0 or a ulong length, returned as an int). A closure in an arm’s value cannot use a name the arm binds; use a match statement there.
• value is Pattern is a bool: whether value holds that case (d is Line, !(d is Text)). It takes any one pattern. When it is the whole condition of an if or while, its bindings are declared in that block only: if (d is Text(t)) { ... } reads t inside the braces, and while (list is Cons(head, tail)) { ... } examines list again on every iteration. Anywhere else, is cannot bind names. is is a keyword only between a value and a pattern, so it stays usable as a name (token.is(text)).
• A trait value is matched by type rather than by case: Circle(c) tests for the struct Circle and binds the value as one. See Converting a trait value back.
• Literal patterns: a match on an integer, a character, a bool or a String compares with literals (1, -1, 'a', true, "import"), using ==. Literals cannot list every value, so such a match needs an else arm, except on a bool that handles both true and false. Matching the same literal twice is an error. A match on an enum takes its case names, not literals, and a match on int takes literals, not names (except constants).

Nested patterns

The values in a case’s parentheses are patterns, as a tuple pattern’s elements are, so patterns nest to any depth:

# Patterns nest: the values a case carries can be matched by patterns of
# their own, as tuple elements can.
enum Doc {
    Text(text: String),
    Line,
    Pair(left: Doc, right: Doc),
}

describe(found: Optional<Doc>): String {
    return match (found) {
        Empty => "nothing",
        # A literal compares the value: only an empty `Text`.
        Value(Text("")) => "empty text",
        # A case of the value's enum, binding its own values.
        Value(Text(t)) => t,
        Value(Line) => "a line",
        # Deeper still, with `_` for a value that does not matter.
        Value(Pair(Line, _)) => "a pair that starts with a line",
        Value(Pair) => "a pair",
    };
}

main(): int {
    assert(describe(Optional<Doc>.Empty) == "nothing", "no document");
    assert(describe(Optional<Doc>.Value(Doc.Text(""))) == "empty text", "a literal value");
    assert(describe(Optional<Doc>.Value(Doc.Text("hi"))) == "hi", "a bound value");
    assert(
        describe(Optional<Doc>.Value(Doc.Pair(Doc.Line, Doc.Text("x")))) == "a pair that starts with a line",
        "two levels deep"
    );

    # A bare name binds the value, unless the value's enum has a case of
    # that name: here `Empty` is `Optional<int>`'s case.
    var nested = Optional<Optional<int>>.Value(Optional<int>.Empty);
    var depth = match (nested) {
        Empty => 0,
        Value(Empty) => 1,
        Value(Value(n)) => 2 + n,
    };
    assert(depth == 1, "the inner Optional is empty");

    # Ranges and guards work inside too, and so does `is`.
    var count = Optional<int>.Value(7);
    var size = match (count) {
        Value(0) => "none",
        Value(1..10) => "a few",
        Value(n) if n < 0 => "negative",
        Value(_) => "many",
        Empty => "unknown",
    };
    assert(size == "a few", "a range inside a case");
    var pair = Doc.Pair(Doc.Text("left"), Doc.Line);
    if (pair is Pair(Text(word), Line)) {
        assert(word == "left", "is binds nested names");
    }
    return 0;
}

• Each value takes _, a name, a case of its enum (with patterns of its own values: Value(Pair(Line, _))), a literal, a range or constant, or a tuple pattern.
• A bare name binds the value, unless the value’s enum has a case of that name, which it then matches (Value(Empty)), or it names a module-scope constant. A name repeated in one pattern (Pair(x, x)) must be a case.
• A nested pattern handles part of its case: the arms must still handle every value. A case that only nested patterns handle is reported with the value they miss (match on 'Optional<Doc>' does not handle 'Value(Line)'), and a pattern whose values the earlier arms already match is an error.
• Patterns that share an arm bind the same names, each at the same place: Pair(Text(t), Line), Pair(Text(t), Pair) binds t from either, but Pair(Text(t), _), Pair(_, Text(t)) is an error.
• A nested test reads a value only once the case around it matched, so the tests stop at the first part that does not match.

Ranges and constants

A match on an integer or a character can compare with a range of values, and a match on an integer, a character or a bool with a module-scope constant:

# Range and constant patterns: a `match` on an integer or a character
# compares with ranges (`1..9`, `'a'..>'z'`) and module-scope constants.
const LIMIT = 100;

size(n: int): String {
    return match (n) {
        0 => "none",
        # `1..10` stops before 10; `10..>99` includes 99.
        1..10 => "a few",
        10..>99 => "many",
        LIMIT => "the limit",
        else => "out of range",
    };
}

kind(c: char): String {
    return match (c) {
        'a'..>'z', 'A'..>'Z' => "letter",
        '0'..>'9' => "digit",
        else => "other",
    };
}

# Ranges that cover every value of the type need no `else`.
half(b: u8): int {
    return match (b) {
        0..128 => 0,
        128..>255 => 1,
    };
}

main(): int {
    assert(size(0) == "none" && size(9) == "a few" && size(10) == "many", "ranges");
    assert(size(100) == "the limit" && size(-1) == "out of range", "a constant, then else");
    assert(kind('q') == "letter" && kind('7') == "digit" && kind('!') == "other", "character ranges");
    u8 high = 200;
    assert(half(3) == 0 && half(high) == 1, "every u8 is handled");

    # In a tuple pattern, a range or a constant compares its element.
    var pair = (LIMIT, true);
    var which = match (pair) {
        (0..LIMIT, _) => 1,
        (LIMIT, true) => 2,
        (_, _) => 3,
    };
    assert(which == 2, "the constant matches the first element");
    return 0;
}

• start..end matches from start up to but not including end, and start..>end includes end, as ranges do elsewhere. Each bound is a literal (-1, 'z') or a constant (MIN..MAX). Ranges match integers and characters only, not bool or String.
• A name that is a module-scope constant (const LIMIT = 100;, declared in the file or imported, or limits.MAX through a module) compares the value with it, like a literal. A local variable is not a pattern; compare with it in a guard instead (n if n == limit).
• Inside a tuple pattern, a range or a constant compares its element ((0..LIMIT, _)), and any other bare name binds it, as before.
• When every bound is a literal, the compiler knows which values a pattern matches: a pattern whose values the earlier arms already match is an error (2..>5 after 1..9), and a match whose ranges and literals cover every value of its type (0..128 and 128..>255 for a u8) needs no else. A pattern with a constant bound covers nothing for this check.
• A match on an enum takes its cases, not ranges or constants, even a constant holding one of its cases.

Guards

An arm can add a guard after its patterns, if condition: the arm runs only when one of its patterns matches and the condition holds. Otherwise the next arm is tried, as if this one had not matched.

# A guard (`if condition`) after an arm's patterns: the arm runs only when a
# pattern matches and the guard holds; otherwise the next arm is tried.
enum Shape {
    Circle(radius: int),
    Rect(width: int, height: int),
    Point,
}

describe(s: Shape): String {
    return match (s) {
        # The guard reads the names its patterns bind.
        Circle(r) if r > 10 => "a large circle",
        Circle => "a circle",
        Rect(w, h) if w == h => "a square",
        Rect => "a rectangle",
        Point => "a point",
    };
}

# A guarded arm handles nothing for the check that every value is handled,
# since its guard may fail: the `bool` match below still needs `false`.
toll(heavy: bool, axles: int): int {
    match (heavy) {
        true if axles > 4 => {
            return 30;
        }
        true => {
            return 20;
        }
        false => {
            return 10;
        }
    }
}

main(): int {
    assert(describe(Shape.Circle(20)) == "a large circle", "the guard holds");
    assert(describe(Shape.Circle(2)) == "a circle", "the guard fails, the next arm runs");
    assert(describe(Shape.Rect(3, 3)) == "a square", "equal sides");
    assert(describe(Shape.Rect(3, 4)) == "a rectangle", "unequal sides");
    assert(toll(true, 6) + toll(true, 2) + toll(false, 2) == 60, "each arm runs once");

    # Guards work on tuples too.
    var pair = (5, true);
    var kind = match (pair) {
        (n, true) if n > 3 => 1,
        (_, true) => 2,
        (_, false) => 3,
    };
    assert(kind == 1, "the first arm's guard holds");
    return 0;
}

• The guard reads the names the arm’s patterns bind (Circle(r) if r > 10). With several patterns (Word(s), Quoted(s) if s.length == 0), it applies to the arm, whichever pattern matched.
• Guards work in match statements and match expressions, over enums, literals and tuples. is takes no guard: write x is P && condition, or test the condition inside the if.
• A guarded arm handles nothing when the compiler checks that every case is handled, since its guard may fail: a match whose only arm for Circle has a guard does not handle Circle, and a later unguarded arm (or else) must. An else after guarded arms is not unreachable.
• A guarded arm for a case an earlier unguarded arm already handles is an error, like any case handled twice. Two guarded arms may name the same case.
• A closure in a guard cannot use a name the arm binds.

Current limits

• An enum whose cases carry nothing cannot be generic, by design: its value is a plain integer, so a type parameter would have nothing to describe. An enum whose cases carry values can be (enum List<T>).
• An enum whose cases carry values compares by identity with ==, as a struct does, unless it is a [Value] enum, is [Equatable], or declares == (with a matching hash<T> to be a key).
• A constant is a pattern only when it is declared at module scope.
• A match cannot examine floating-point values.
• The methods of an enum whose cases carry nothing have no value form: c.name without the call is an error (“‘name’ is a method of ‘Color’: call it as ‘name()’”), where a struct’s p.norm is a bound method. Wrap the call in a closure instead, () => c.name().
• An enum whose cases carry nothing is extended only with a trait (extend Color with Describe { ... }); declare its other methods inside it. It is never a trait value, since a trait value is a reference to an object, which such an enum’s value is not.

Memory and reference counting

Pepper frees memory for you, without a garbage collector and without ownership annotations. Every struct object keeps a count of the references to it, and the object is destroyed the moment that count drops to zero. Because the rules are simple and the same everywhere, you can always tell when an object will be destroyed and its destructor will run.

If you know C++, the whole model fits in one sentence: every struct value behaves exactly like a std::shared_ptr<T> passed by value.

Values and references

Numbers, bool, and the other primitive types are plain values: assigning one copies it, as in C. So is a tuple, whose elements are copied the way each element would be on its own, and so is a struct or enum marked [Value], such as Optional<T> and Result<T> (see value enums).

Everything else, including your own structs, String, Array, HashMap, and function values, is a reference to an object on the heap. Assigning a reference, passing it to a function, or storing it in a field or an array shares the object. Nothing is copied.

struct Account {
    var balance: int = 0;
}

# The parameter is another reference to the caller's object, so changes to
# its fields are visible to the caller.
deposit(account: Account, amount: int) {
    account.balance += amount;
}

# Rebinding the parameter itself only changes this function's reference.
replace(account: Account) {
    account = Account();
    account.balance = 999;
}

main(): int {
    var mine = Account();
    var yours = mine;               # shares the object; nothing is copied
    yours.balance = 50;
    assert(mine.balance == 50, "assignment shares the object");

    deposit(mine, 25);
    assert(mine.balance == 75, "a function can change the shared object");

    replace(mine);
    assert(mine.balance == 75, "rebinding a parameter does not affect the caller");

    # To get an independent object, make a new one and copy the fields.
    var copy = Account();
    copy.balance = mine.balance;
    copy.balance = 0;
    assert(mine.balance == 75, "the copy is a separate object");
    return 0;
}

• var yours = mine; makes a second reference to the same Account. Changes through either name are visible through both.
• A parameter is one more reference to the caller’s object. The function can change the object’s fields, but assigning a new object to the parameter only changes the function’s own reference.
• To get an independent object, create a new one. Pepper does not copy structs for you; some library types offer a method for it, such as Array’s clone().

A struct-typed variable or field that has not been given a value, such as var next: Account;, is null: it refers to no object. Reading a field or calling a method through a null reference crashes the program. Use === or !== to check whether two references name the same object, or whether one is null (next === __null). A struct is not a condition by itself, so if (next) is an error unless the struct declares the truth test !! (see Truth tests and conditions). For a value that may be absent, prefer Optional<T>, whose type says so.

When objects are destroyed

A reference is held by whatever stores it: a local variable, a parameter, a field, an element of a container, or a temporary value in the middle of an expression. Each of those releases its reference exactly once, when it goes away. When the last reference is released, the object is destroyed: its destructor runs, and then its fields release their own references, which may destroy further objects in turn.

import async;

# A module-scope counter: const, and changed through an Atomic.
const destroyed = async.Atomic<int>(0);

struct Tracked {
    var name: String;
    construct(this.name = "") {}
    destruct {
        destroyed.fetch_add(1);
    }
}

struct Holder {
    var item: Tracked;
}

make(name: String): Tracked {
    var t = Tracked(name);
    return t;                   # the caller receives the object
}

main(): int {
    # 1. A local is released when its scope ends.
    {
        var a = Tracked("a");
    }
    assert(destroyed.load() == 1, "a was destroyed at the end of its block");

    # 2. While another reference exists, the object stays alive.
    var b = Tracked("b");
    var also_b = b;
    b = Tracked("b2");          # b lets go of the first object...
    assert(destroyed.load() == 1, "...but also_b still holds it");
    also_b = b;                 # the last reference moves away
    assert(destroyed.load() == 2, "the first object is destroyed now");

    # 3. Fields and containers hold references too.
    var holder = Holder();
    {
        var c = Tracked("c");
        holder.item = c;
    }
    assert(destroyed.load() == 2, "holder.item keeps c alive after its scope");
    holder = Holder();          # the old Holder dies and releases c
    assert(destroyed.load() == 3, "releasing the holder released its field");

    var list = Array<Tracked>();
    list.append(Tracked("d"));
    assert(destroyed.load() == 3, "the array holds d");
    list.clear();
    assert(destroyed.load() == 4, "clearing the array released d");

    # 4. Returned objects belong to the caller; unused results are
    #    destroyed right away.
    var e = make("e");
    assert(destroyed.load() == 4, "e is alive in main");
    make("temporary");
    assert(destroyed.load() == 5, "a result nobody keeps is destroyed immediately");
    return 0;
}

Concretely, a reference is released when:

• A local variable goes out of scope, at the closing brace of the block that declared it, or when the function returns.
• A variable or field is overwritten. b = Tracked("b2"); releases the object b held before, after taking the new one. Assigning a variable to itself (a = a) changes nothing.
• A parameter’s function returns. The function held its parameters for as long as it ran.
• The object that holds a field is destroyed, or a container removes an element (clear(), overwriting list[i], and so on). remove_at() and pop() are the exception: they hand the container’s reference to the caller, so var x = list.remove_at(0); leaves the count unchanged.
• A temporary is no longer needed. A result that is not stored anywhere, like the one from make("temporary");, is released at the end of the statement. The same goes for a call result passed straight to another function, and for the object in make().name.

Returning a local hands its reference to the caller, so the object survives the function. Calling a method on an object does not add a reference to it: inside the method, this refers to the caller’s object.

Cycles leak

Reference counting cannot free a cycle: objects that refer to each other, directly or through a chain, keep each other’s counts above zero even after nothing else refers to them. Their destructors never run and their memory is never freed.

import async;

# A module-scope counter: const, and changed through an Atomic.
const destroyed = async.Atomic<int>(0);

struct Person {
    var name: String;
    var friends: Array<Person>;

    construct(this.name = "") {
        friends = Array<Person>();
    }

    destruct {
        destroyed.fetch_add(1);
    }
}

main(): int {
    # Two people who list each other as friends form a cycle: each keeps
    # the other alive, so neither is ever destroyed.
    {
        var ann = Person("Ann");
        var bob = Person("Bob");
        ann.friends.append(bob);
        bob.friends.append(ann);
    }
    assert(destroyed.load() == 0, "the cycle leaked both objects");

    # Break the cycle before letting go, and both are destroyed.
    {
        var cat = Person("Cat");
        var dan = Person("Dan");
        cat.friends.append(dan);
        dan.friends.append(cat);
        dan.friends.clear();    # Dan no longer holds Cat
    }
    assert(destroyed.load() == 2, "without the cycle, both were destroyed");
    return 0;
}

To avoid a cycle, make one direction of it a weak reference (next section), or break the cycle yourself before the last outside reference goes away: clear the container, or overwrite the field, that closes the loop.

A closure holds a reference to every struct it captures, including this, so a closure stored inside an object it captures closes a cycle too. The compiler reports the direct case, a method storing a closure that captures this in a field of this.

Weak references

A Weak<T> points at an object without keeping it alive. Use it for back pointers: a child’s parent, a document’s folder, an observer’s subject. The owner holds strong references down the tree, and everything that points back up holds a Weak<T>, so there is no cycle.

import async;

# A module-scope counter: const, and changed through an Atomic.
const destroyed = async.Atomic<int>(0);

struct Folder {
    var name: String;
    var files: Array<Document>;

    construct(this.name = "") {
        files = Array<Document>();
    }

    destruct {
        destroyed.fetch_add(1);
    }
}

struct Document {
    var title: String;
    # A weak back pointer: the folder owns its documents, not the other way
    # round, so there is no cycle.
    var folder: Weak<Folder>;

    construct(String title, Folder folder) {
        this.title = title;
        this.folder = Weak<Folder>(folder);
    }

    destruct {
        destroyed.fetch_add(1);
    }

    String path() {
        with (var f = folder) {
            return f.name + "/" + title;
        } else {
            return "(deleted)/" + title;
        }
        return "";
    }
}

main(): int {
    var kept = Document("draft", Folder("none"));
    {
        var home = Folder("home");
        var notes = Document("notes", home);
        home.files.append(notes);
        assert(notes.path() == "home/notes", "the folder is alive");
        kept = notes;
    }
    # The folder went away with `home`; the weak pointer did not keep it.
    assert(kept.path() == "(deleted)/notes", "the folder is gone");
    assert(kept.folder.expired(), "and the weak reference knows it");
    return 0;
}

• Weak<T>(object) makes the weak reference. It does not change the object’s reference count.
• A with block reaches the object: with (var f = folder) { ... } binds f to an ordinary strong reference for the length of the block. When the object has already been destroyed, the body is skipped and the else block runs. See Scoped blocks with with.
• expired() reports whether the object has been destroyed.
• T may be a trait: Weak<Shape> upgrades to a Shape (see Weak references and atomics).
• The object is destroyed on time. When its last strong reference goes, its destructor runs and its fields are released, even if weak references remain. Only the object’s small header stays allocated until the last weak reference is gone.

In C++ terms, a struct value is a std::shared_ptr<T> and Weak<T> wraps the built-in __weak<T>, a std::weak_ptr<T>: Weak<T>(object) is weak_ptr(object), and entering it with with is lock(). Inside a constructor, this already holds the object’s first reference, like the shared_ptr that make_shared fills in: a constructor may pass this to a function or store it, and a weak reference made from it upgrades, without the object being destroyed when those copies are dropped.

References and threads

Reference counts are plain, fast increments, so a struct’s objects must stay on one thread. A struct declared [Shared] has atomic counts instead, and its references can be copied and dropped on any thread. The compiler requires such a struct’s fields to be const and thread-safe. See What threads can share.

Function values follow the same split: a plain function type such as () => void has plain counts and stays on one thread, and a shared function type such as shared () => void has atomic counts.

Copying a value with copy

copy(value) makes a copy of a value that shares no object that is not thread-safe with the original, so the copy can go to another thread: pass copy(x) to a channel to send a value you keep using.

var names = Array<String>();
names.append("ada");
var copied = copy(names);
copied[0].append(" lovelace");   # names[0] is still "ada"

• Every struct object the value reaches is copied once. An object referenced twice is copied once and stays shared inside the copy, and a cycle becomes the same cycle among the copies.
• Thread-safe objects are not copied: a [Shared] struct or a shared function value in the original is the same object in the copy. For a thread-safe value, copy returns the value itself.
• A weak reference to an object that was copied points at its copy. A weak reference to an object outside the copied value becomes null.
• A struct is copied field by field, without running its constructor.

A struct with a destructor or a raw pointer (__ptr<T>) field is not trivially copyable: copying its fields would share what it owns, such as a buffer it frees. Such a struct says how to copy itself by implementing Copyable<T>, with a copy(): T method that builds the copy and copies each value it holds with copy(value). String, Array, HashMap and HashSet implement it. String.copy() also copies a single String; it replaces the deprecated clone(). Array.clone() is unchanged: it copies the Array but shares its elements.

# A struct with a destructor is not trivially copyable, so it implements
# `Copyable<T>` to say how `copy` copies it.
struct Buffer {
    __ptr<u8> data;
    ulong size;
    String label;

    construct(size: ulong) {
        data = _pep_malloc(size);
        this.size = size;
        label = "buffer";
    }

    destruct {
        _pep_free(data);
    }

    copy(): Buffer {
        var made = Buffer(size);
        var i: ulong = 0;
        while (i < size) {
            made.data[i] = data[i];
            i = i + 1;
        }
        # The free function `copy`: it continues the running copy.
        made.label = copy(label);
        return made;
    }
}

extend Buffer with Copyable<Buffer>;

struct Message {
    Buffer body;
    Buffer again;
}

main(): int {
    var message = Message();
    message.body = Buffer(4);
    message.body.data[0] = 9;
    message.again = message.body;

    var copied = copy(message);
    copied.body.data[0] = 1;
    copied.body.label.append(" (copy)");
    assert(message.body.data[0] == 9, "the original buffer is unchanged");
    assert(message.body.label == "buffer", "the original label is unchanged");
    # The buffer appears twice, so its copy is one object.
    assert(copied.again === copied.body, "one copy of the shared buffer");
    return 0;
}

Inside copy(), the call copy(label) is the free function, not the method: a bare call in a method names the struct’s own method only when one by that name takes those arguments. While a copy runs, copy(value) continues it rather than starting another, so an object the outer copy already made is reused and sharing is kept. That is why a Copyable value is copied with copy(x): calling x.copy() directly still works, but each copy(value) inside it is then a copy of its own. A value whose contents can lead back to it calls register_copy(this, made) before copying them, so the cycle finds the copy being built.

The copy(copies: Copies): T form of Copyable<T>, which took the copy’s context as an argument and copied with copies.copy(value), still works in this release, with a warning at Copies.

Copying a value that reaches a struct that is not trivially copyable and does not implement Copyable<T> is an error at the copy call. It names the struct, shows each field on the way to it, says why it cannot be copied, and shows a Copyable<T> to fill in (the editor offers to insert it):

main.pep:14:13: error: cannot copy 'Log' because it contains 'Handle', which is not trivially copyable
   14 |     var c = copy(log);
      |             ^~~~
main.pep:9:5: note: 'Log' reaches it through field 'out'
    9 |     Handle out;
      |     ^~~~~~
main.pep:1:8: note: 'Handle' has a destructor, so copying its fields would release what it owns twice
    1 | struct Handle {
      |        ^~~~~~
note: implement 'Copyable<Handle>' to say how to copy it:
    extend Handle with Copyable<Handle> {
        copy(): Handle {
            # Build the copy; copy each struct field with copy(field).
            panic("copying 'Handle' is not implemented");
            return this;
        }
    }

Some types cannot be copied at all: an io.File owns an operating-system handle, so the error says to send its path instead. A plain function value cannot be copied, because it may capture anything; declare it shared.

Copying trait values

copy of a trait value copies the struct behind it, as copy of that struct would, and returns the copy as the same trait type. Sharing works across the boundary: a struct reached twice, through a trait value or directly, is copied once.

# `copy` of a trait value copies the struct behind it, whichever it is.
trait Shape {
    area(): int;
    grow();
}

struct Square {
    var side: int = 1;
    construct(this.side = 1) {}
}

extend Square with Shape {
    area(): int { return side * side; }
    grow() { side = side + 1; }
}

struct Rect {
    var width: int = 1;
    var height: int = 1;
    construct(this.width = 1, this.height = 1) {}
}

extend Rect with Shape {
    area(): int { return width * height; }
    grow() { width = width + 1; }
}

main(): int {
    var shapes = Array<Shape>();
    var square = Square(2);
    shapes.append(square);
    shapes.append(Rect(2, 3));
    shapes.append(square);

    var copied = copy(shapes);
    for (var shape in copied) {
        shape.grow();
    }
    assert(shapes[0].area() == 4, "the original Square is unchanged");
    assert(shapes[1].area() == 6, "the original Rect is unchanged");

    # The Square appears twice, so its copy is one object, grown twice.
    assert(copied[0] == copied[2], "one copy of the shared Square");
    assert(copied[0].area() == 16, "the copied Square grew twice");
    assert(copied[1].area() == 9, "the copied Rect grew once");
    return 0;
}

Which struct a trait value holds is known only when the program runs, so the compiler cannot check that it can be copied. Copying a trait value that holds a struct that cannot be copied (one with a destructor and no Copyable<T>, an io.File, a MutexGuard) panics:

cannot copy the 'Owner' behind a trait value, which is not trivially copyable

Handing a reference over with move

move(x) gives up x’s reference: the call returns the same object, and x is left null. Nothing is copied and no count changes. It is how a value built in a local variable goes to a channel, a Mutex or another [Move] parameter, which takes a new value, without the cost of copy(x):

var lines = Array<String>();
lines.append("first");
var log = async.Mutex<Array<String>>(move(lines));   # lines is now null

move is an ordinary function from the prelude (runtime/copy.pep), but the compiler checks every call:

• Only a local variable can be moved (move(h.s) is an error), and only when it holds the one reference to a new value: nothing else refers to it or to anything it reaches. A parameter can be moved only when it is [Move], since the caller handed its value over.

  main.pep:8:24: error: 'a' cannot be moved: 'b' also references its value
      8 |     names.replace(move(a));
        |                        ^
  note: only a variable that holds the one reference to a new value can hand it over; pass 'copy(...)' instead
  

• A moved variable cannot be read again until it is assigned a new value, including on the next pass through a loop:

  main.pep:8:12: error: 'a' is used after its value was moved
      8 |     return a.count;
        |            ^
  main.pep:7:19: note: 'a' was moved here; assign it a new value before using it again
      7 |     names.replace(move(a));
        |                   ^~~~
  

The runtime also moves values out of raw memory (move(buffer[head])), which is a promise the compiler cannot check: only runtime files may do it. The parameter of move is marked [MoveSource], which is also only allowed in the runtime, so a hand-off always shows at the call as move(x); a function of your own that takes over its argument uses [Move].

Where objects live

Every object, String buffer and Array buffer comes from the runtime’s allocator. A block of up to 128 bytes (most objects and short strings) comes from a small block allocator: blocks are grouped by size into classes (multiples of 16 bytes up to 128, then four classes per power of two). Each class’s blocks are cut from 64 KiB spans, and a thread hands out a class’s blocks from one span at a time, so objects made one after another sit close together in memory. Allocating, and freeing on the thread that allocated, take no lock; a block freed on another thread goes back to its span with one atomic step. Larger blocks come from the C library’s calloc and go back with free. A small block’s size is rounded up to its class, so a 40-byte object takes 48 bytes.

An empty Array allocates nothing. Array<T>() makes no object until the Array is written (append, insert, reserve, …) or shared (assigned to a second variable, stored in a field or element, passed or returned): reading it (count, is_empty, contains, a for loop over it) allocates nothing. The first write or share allocates the object, so every name for the Array still sees the same appends:

struct Node {
    String name;
    # Most nodes never get children, and an empty Array costs nothing.
    Array<Node> children = Array<Node>();
    construct(name: String) {
        this.name = name;
    }
}

main(): int {
    var a = Array<int>();           # no allocation
    assert(a.count == 0 && a.is_empty, "reading allocates nothing");
    for (var x in a) {
        assert(false, "an empty Array has no elements");
    }
    var b = a;                      # allocates the Array: a and b share it
    b.append(1);                    # allocates its buffer
    assert(a.count == 1, "both names see the append");

    var leaf = Node("leaf");
    var root = Node("root");
    root.children.append(leaf);
    assert(leaf.children.is_empty && root.children.count == 1, "only root's children were allocated");
    return 0;
}

Structs that hold an Array which usually stays empty (a tree node’s children, a list of comments) cost nothing extra for it.

The environment variable PEPPER_SMALL_BLOCK_LIMIT, read when the program starts, sets the largest size the small block allocator serves, in bytes, up to 4096 (a larger value counts as 4096). 0 turns it off, and then every block comes from the C library:

PEPPER_SMALL_BLOCK_LIMIT=0 ./main      # every block from calloc
PEPPER_SMALL_BLOCK_LIMIT=512 ./main    # blocks up to 512 bytes from the classes

With it off, a program can use another C allocator, such as mimalloc, by loading it in front of the C library (LD_PRELOAD=libmimalloc.so on Linux).

Small blocks live in address space the program reserves at start (4 GiB, committed 64 KiB at a time as it is used, and never returned to the operating system); a program that fills it falls back to calloc. On WebAssembly, which cannot reserve address space, every block comes from calloc.

Summary

Generics

Generics let you write a struct or a function once and use it with many types. Add type parameters in angle brackets after the name, then use them like any other type name. The standard library’s Array<T>, HashMap<K, V>, and Result<TValue, TError> are all ordinary generic types written this way (Result is a generic enum).

Pepper generics work like C++ templates: each distinct set of type arguments, such as Stack<int> or Stack<String>, produces its own copy of the code, compiled for those exact types. There is no runtime cost for using them.

Generic structs

# `T` is a type parameter: each use such as `Stack<int>` or
# `Stack<String>` makes a separate, fully typed version of the struct.
struct Stack<T> {
    var items: Array<T>;

    construct() {
        items = Array<T>();
    }

    push(item: T) {
        items.append(item);
    }

    pop(): T {
        return items.pop();
    }

    peek(): T {
        # `top` is inferred as `T`: an `int` in `Stack<int>`, a `String`
        # in `Stack<String>`.
        var top = items.last();
        return top;
    }

    is_empty(): bool {
        return items.is_empty;
    }
}

# Several parameters are separated by commas.
struct Entry<K, V> {
    var key: K;
    var value: V;
    construct(K key, V value) {
        this.key = key;
        this.value = value;
    }
}

main(): int {
    var numbers = Stack<int>();
    numbers.push(1);
    numbers.push(2);
    assert(numbers.peek() == 2, "peek looks at the top");
    assert(numbers.pop() == 2, "last in, first out");
    assert(numbers.pop() == 1, "then the first");
    assert(numbers.is_empty(), "empty again");

    var words = Stack<String>();
    words.push("hello");
    assert(words.pop() == "hello", "the same code works for Strings");

    var e = Entry<String, int>("answer", 42);
    assert(e.key == "answer" && e.value == 42, "two type parameters");
    return 0;
}

• Name the type parameters after the struct’s name: struct Stack<T>, struct Entry<K, V>. Inside the struct, fields, parameters, return types, and locals can all use them.
• Name the type arguments whenever you use the struct: Stack<int>(), var s: Stack<String>;.
• Stack<int> and Stack<String> are different types.
• A type argument is a type. The one exception is a number, which only the lane count of a SIMD vector accepts (Vector<int, 4>); a struct of your own cannot compute with a number parameter.
• Each type argument makes a separate copy of the struct, so a struct whose copy needs a copy with a larger argument never ends: struct Foo<T> with a field var inner: Foo<Array<T>> makes Foo<int> need Foo<Array<int>>, which needs Foo<Array<Array<int>>>, and so on. The compiler stops 64 levels deep with an error at the type that asks for the next level ('Foo' is specialized 65 levels deep, past the limit of 64), with a note where the chain started.

Generic functions

A free function takes type parameters the same way:

larger<T>(a: T, b: T): T {
    if (a > b) {
        return a;
    }
    return b;
}

struct Circle {
    var radius: int = 1;
    area(): int { return 3 * radius * radius; }
}

struct Square {
    var side: int = 2;
    area(): int { return side * side; }
}

# The body can use anything the type argument provides: this works for
# any T that has an `area()` method returning a number.
total_area<T>(shapes: Array<T>): int {
    var sum = 0;
    for (var shape in shapes) {
        sum += shape.area();
    }
    return sum;
}

# `T()` calls the type argument's constructor.
fresh<T>(): Array<T> {
    var items = Array<T>();
    items.append(T());
    return items;
}

# A closure in generic code is compiled with each use too: for `T = int`
# it calls `larger<int>`.
larger_later<T>(a: T, b: T): () => T {
    return () => larger(a, b);
}

main(): int {
    # Type arguments come from the arguments, or can be written out.
    assert(larger(3, 9) == 9, "ints");
    assert(larger<float>(2.5, 1.5) == 2.5, "floats");

    var circles = Array<Circle>();
    circles.append(Circle());
    circles.append(Circle());
    assert(total_area(circles) == 6, "circles");

    var squares = Array<Square>();
    squares.append(Square());
    assert(total_area<Square>(squares) == 4, "squares");
    assert(total_area(fresh<Circle>()) == 3, "a constructed Circle");
    var pick = larger_later(4, 7);
    assert(pick() == 7, "a closure calling a generic function");
    return 0;
}

Pepper infers the type arguments from the arguments, so larger(3, 9) calls larger<int>. You can always write them out, larger<float>(2.5, 1.5), or write only the leading ones and let the arguments give the rest: pick<int>(1, "x") for pick<T, U>(a: T, b: U). You must write them when the arguments do not determine every type parameter, for example one that appears only in the return type:

main.pep:4:13: error: cannot infer the type arguments of 'make' from its arguments; write them: make<T>(...)
    4 |     var b = make();
      |             ^~~~
main.pep:1:1: note: declared here
    1 | make<T>(): Box<T> { return Box<T>(); }
      | ^~~~

A generic function used as a value, not called, takes its type arguments from the function type it is given: var f: (int, int) => int = larger; is larger<int> (see Function types).

A parameter whose type is a trait takes its type arguments from the trait the argument’s type declares: given total<T>(items: Iterator<T>), the call total(Countdown(4)) infers T = int from extend Countdown with Iterator<int>.

Inference works through closures in both directions. In transform(words, (w) => w.size), where transform<T, U>(items: Array<T>, f: (T) => U), words gives T, which types the closure’s parameter w, and the closure’s result gives U.

A closure inside a generic function or method is compiled with each use of it, so the generic calls in its body take their type arguments from that use: in larger_later<T>(a: T, b: T) above, () => larger(a, b) calls larger<int> when T is int.

Because each use is compiled for its concrete types, the body may use any operator, field, or method that the type arguments provide. total_area<T> calls shape.area(), so it works with any T that has an area() method returning a number, and using it with a type that lacks one is a compile error inside total_area. To state the requirement up front, and have the compiler report it where the function is used, give T a constraint.

That includes constructing one: T() (or T(args)) calls the type argument’s constructor, so fresh<Circle>() above makes a Circle. In a constrained generic, which offers only what its constraints declare, it is an error.

Generic methods

A method can have type parameters of its own, in a struct, a generic struct, an extension, or a trait’s default method. They are inferred at each call like a function’s, or written after the method name:

struct Box<T> {
    T value;
    construct(T v) { value = v; }

    # A method with a type parameter of its own: `U` is chosen per call.
    map<U>(f: (T) => U): Box<U> {
        return Box<U>(f(value));
    }
}

main(): int {
    var b = Box<int>(4);

    # `U` comes from what the closure returns...
    var tens = b.map((x) => x * 10);
    assert(tens.value == 40, "tens");

    var text = tens.map((x) => "forty");
    assert(text.value == "forty", "text");

    # ...or is written after the method name.
    var wide = b.map<long>((x: int): long => x + 1);
    assert(wide.value == 5, "wide");
    return 0;
}

• Write the type arguments with no space before < or after >: b.map<long>(f). With a space, a.b < c is a comparison.
• A generic method cannot be called through a trait value, since each of its uses is compiled separately. Call it on the concrete type.
• The iterator adapters map, filter, enumerate and zip are generic default methods of Iterator<T>; see Iteration.

Default type arguments

A type parameter can have a default, written Name=Type. When a use leaves that argument out, the default fills it in:

struct Measurement<TValue, TUnit=String> {
    var value: TValue;
    var unit: TUnit;
}

main(): int {
    # `Measurement<float>` fills TUnit with its default, String.
    var length = Measurement<float>();
    length.value = 2.5;
    length.unit = "m";
    assert(length.unit == "m", "TUnit defaulted to String");

    # Any argument can still be given explicitly.
    var count = Measurement<int, int>();
    count.unit = 7;
    assert(count.unit == 7, "TUnit given as int");

    # The standard library's Result uses a default the same way:
    # Result<int> means Result<int, Error>.
    var ok = Result<int>.ok(42);
    assert(ok.value() == 42, "Result with the default error type");
    return 0;
}

Arguments are matched to parameters in order, so put the parameters that have defaults last. The standard library declares enum Result<TValue, TError=Error>, so Result<int> means Result<int, Error>. See Error handling with Result.

Constraints

A type parameter can require a trait: write the trait after a colon, T: Shape. Every type argument for T must then conform to Shape. Several constraints are joined with &, and a constrained parameter can still have a default, written after them:

trait Shape {
    area(): int;
}

trait Named {
    name(): String;
}

struct Circle {
    var radius: int = 1;
    area(): int { return 3 * radius * radius; }
}

extend Circle with Shape;

struct Square {
    var side: int = 2;
    area(): int { return side * side; }
    name(): String { return "square"; }
}

extend Square with Shape;
extend Square with Named;

# Every T must conform to Shape.
total_area<T: Shape>(shapes: Array<T>): int {
    var sum = 0;
    for (var shape in shapes) {
        sum += shape.area();
    }
    return sum;
}

# Several constraints are joined with `&`.
label<T: Shape & Named>(item: T): String { return item.name(); }

# A constrained parameter can have a default, which must conform too.
struct Gallery<TTag, TShape: Shape = Square> {
    var items = Array<TShape>();
    add(item: TShape) { items.append(item); }
    total(): int { return total_area(items); }
}

main(): int {
    var circles = Array<Circle>();
    circles.append(Circle());
    circles.append(Circle());
    assert(total_area(circles) == 6, "circles");
    assert(label(Square()) == "square", "label");

    # Gallery<String> is Gallery<String, Square>.
    var gallery = Gallery<String>();
    gallery.add(Square());
    assert(gallery.total() == 4, "default");

    # A trait type conforms to its own trait.
    var shapes = Array<Shape>();
    shapes.append(Circle());
    shapes.append(Square());
    assert(total_area(shapes) == 7, "trait values");
    return 0;
}

Constraints work on generic structs, enums whose cases carry values, functions, methods, traits and type aliases. A constraint may name the parameters before it in the same list: sum<T, I: Iterator<T>>(values: I).

A type argument conforms to a trait when:

• it is a struct declared to have the trait with extend Circle with Shape. For a generic struct, extend Box<T> with Shape makes every Box<X> conform, and extend Box<int> with Shape only Box<int>. A generic trait must match exactly: extend Counter with Iterator<int> conforms to Iterator<int>, not to Iterator<long>. Having the right methods is not enough; the extension is what declares it.
• it is the trait type itself (Array<Shape> passed as Array<T> with T: Shape), as long as every member of the trait can be called through a value of the trait type (see traits as types).
• it is a type parameter constrained by that trait: inside wrap<T: Shape>, Gallery<String, T> is allowed.

A number type, char, bool or an enum whose cases carry no values conforms when it declares the trait the same way (extend int with Shape; see numbers, bool and enums), for constraints only: it never becomes a trait value. Pointers, tuples and function types conform to no trait.

The Shared constraint

T: Shared is built in: it requires a type that is safe to share between threads, by the same rule as a field of a [Shared] struct. The types that conform are listed in What threads can share; no extend can make another type conform. It gives T no methods, and it joins other constraints with & (T: Shared & Named):

import async;

[Shared]
struct Settings {
    const workers: int;
    construct(this.workers = 1) {}
}

# A cell that any thread may read: its value must be thread-safe.
[Shared]
struct Cell<T: Shared> {
    const value: T;
    construct(value: T) { this.value = value; }
}

share<T: Shared>(value: T): Cell<T> { return Cell<T>(value); }

main(): int {
    var count = share(3);
    var settings = share(Settings(4));
    assert(count.value == 3 and settings.value.workers == 4, "shared cells");

    # The runtime states the same rule: spawn<T: Shared>.
    async.run(() => {
        var task = async.spawn<Settings>(() => { return Settings(2); });
        assert(task.join().value().workers == 2, "spawned");
    });
    return 0;
}

The standard library states the rule this way where it applies: spawn<T: Shared>, run_blocking<T: Shared> and Lazy<T: Shared>, so async.spawn<String>(...) is reported at String, with a note saying why it is not thread-safe ('String' is not declared [Shared]). In a constraint, Shared always means this built-in, so a trait cannot be named Shared. A generic that passes its own T to one of these (say run_blocking<T>) needs T: Shared too.

A constraint can name another type parameter of the same declaration: count_all<T, I: Iterator<T>>(source: I). Inference reads it too: the argument gives I, and the Iterator<...> that I declares gives T. A trait’s default method may name the trait’s own parameters (put_all<I: Iterator<T>> in trait Sink<T>), which take the arguments of the conformance (extend Sum with Sink<int>).

# `I`'s constraint names `T`: the argument's type gives `I`, and the
# `Iterator<T>` it declares gives `T`.
count_all<T, I: Iterator<T>>(source: I): int {
    var count = 0;
    while (source.next()) {
        count += 1;
    }
    return count;
}

first<T, I: Iterator<T>>(source: I): T {
    source.next();
    return source.current();
}

main(): int {
    var words = Array<String>();
    words.append("pepper");
    words.append("salt");

    # Both inferred: I = ArrayIterator<String>, T = String.
    assert(count_all(words.iterate()) == 2, "count");
    assert(first(words.iterate()) == "pepper", "first");

    # Written type arguments may stop early; the rest are inferred.
    assert(count_all<String>(words.iterate()) == 2, "partial");
    return 0;
}

The compiler checks every use: a type argument you write, one it infers from a call, a default, and a concrete override. The error points at the type argument, or at the call argument the type came from:

main.pep:11:21: error: 'Circle' does not conform to trait 'Shape', required by 'T' in 'Gallery'
   11 |     var g = Gallery<Circle>();
      |                     ^~~~~~
main.pep:7:19: note: constraint declared here
    7 | struct Gallery<T: Shape> {
      |                   ^~~~~
main.pep:4:8: note: declare it with 'extend Circle with Shape'
    4 | struct Circle {
      |        ^~~~~~

A type parameter passed on to a constrained one must carry the constraint itself: wrap<T>(item: T): Gallery<String, T> is an error that suggests T: Shape. The language server offers both the extension and the constraint as quick fixes.

• A constraint must name a trait: T: Point, with Point a struct, is an error.
• An extension of a constrained struct keeps its constraints: extend Gallery<TTag, TShape> needs no TShape: Shape of its own. You may restate them as documentation, extend Gallery<TTag, TShape: Shape>. A constraint the struct does not have makes a constrained extension.
• In an overload set, a generic member whose inferred type arguments do not meet its constraints is not viable, and the error lists why.
• A constrained name is always a type parameter, never an override’s type argument: describe<Point: Shape> declares a generic function whose parameter happens to be named Point.

Inside a constrained generic

The compiler also checks the generic itself, once, whether or not anything uses it: inside largest<T: Shape & Ordered>, a value of type T offers exactly what Shape and Ordered declare. It may:

• call their instance methods and operators (item.area(), best < item),
• call their static members through the parameter (T.unit()),
• convert to one of their trait types (var shape: Shape = item;),
• be stored, passed, returned, and compared with ==, !=, === and !==.

trait Shape {
    area(): int;
    scaled(by: int): this;
    static unit(): this;
}

trait Ordered {
    <(other: this): bool;
}

struct Square {
    var side: int = 1;
    construct(this.side = 1) {}
    area(): int { return side * side; }
    scaled(by: int): Square { return Square(side * by); }
    static unit(): Square { return Square(1); }
    <(other: Square): bool { return side < other.side; }
}

extend Square with Shape;
extend Square with Ordered;

# Inside the body, a T offers what Shape and Ordered declare.
largest<T: Shape & Ordered>(items: Array<T>): T {
    var best = items[0];
    for (var item in items) {
        if (best < item) {
            best = item;
        }
    }
    return best;
}

# Static members are called through the parameter.
unit_area<T: Shape>(): int { return T.unit().area(); }

# A T converts to the trait types of its constraints.
as_shape<T: Shape>(item: T): Shape {
    var shape: Shape = item.scaled(2);
    return shape;
}

main(): int {
    var squares = Array<Square>();
    squares.append(Square(2));
    squares.append(Square(3));
    assert(largest(squares).side == 3, "largest");
    assert(unit_area<Square>() == 1, "static member");
    assert(as_shape(Square(3)).area() == 36, "conversion");
    return 0;
}

Anything else is an error at the member or operator, even before any use: a field, a method no constraint declares, a constructor T(), a call of a constraint’s method with the wrong number or types of arguments, or initializing, assigning or returning a T as another type. (Passing a T to a function that takes another type is still reported in each specialization.)

main.pep:5:45: error: no member named 'perimeter' in 'T'
    5 | total<T: Shape>(item: T): int { return item.perimeter(); }
      |                                             ^~~~~~~~~
main.pep:5:10: note: 'T' is constrained by 'Shape', which has no member 'perimeter'
    5 | total<T: Shape>(item: T): int { return item.perimeter(); }
      |          ^~~~~

A method that two constraints both declare is an error too ('name' is declared by both 'Named' and 'Titled'; call it through one of them).

Each use is still compiled for its type argument, so a call goes straight to that type’s own method, with no trait value in between. A parameter without a constraint keeps working as before: its uses are checked in each specialization. In a list that mixes the two, such as f<T: Shape, U>, only the uses of T are checked in the generic.

Constrained extensions

An extension of a generic struct can add a constraint the struct does not have: extend Box<T: Named> { ... }. Its members exist only on the specializations whose type argument meets it, so Box<Square> has label() and Box<String> does not. With with, the constraint makes a conditional conformance: after extend Box<T: Shape> with Shape, a Box<Square> is a Shape (it can be passed where T: Shape is required and converted to a Shape value), and a Box<String> is not.

trait Shape {
    area(): int;
}

trait Named {
    name(): String;
}

struct Square {
    area(): int { return 4; }
    name(): String { return "square"; }
}

extend Square with Shape;
extend Square with Named;

struct Box<T> {
    var item: T;
    construct(item: T) { this.item = item; }
}

# Only a Box of something Named has `label()`.
extend Box<T: Named> {
    label(): String { return "box of " + item.name(); }
}

# A Box of shapes is itself a shape.
extend Box<T: Shape> with Shape {
    area(): int { return item.area() * 2; }
}

main(): int {
    var box = Box<Square>(Square());
    assert(box.label() == "box of square", "constrained extension");

    Shape shape = box;
    assert(shape.area() == 8, "conditional conformance");

    # Box<String> is still a Box, without `label()` or `area()`.
    var text = Box<String>("plain");
    assert(text.item == "plain", "any Box");
    return 0;
}

• Every Box<X> keeps the struct’s own members and constraints; an extension adds to them, it never removes any.
• Inside the extension, T offers the struct’s constraints and the extension’s, as in any constrained generic.
• A call of a member the specialization does not have names the constraint it misses:

main.pep:20:9: error: no member named 'label' in 'Box<Circle>'
   20 |     box.label();
      |         ^~~~~
main.pep:15:15: note: 'label' requires 'Circle' to conform to 'Named'
   15 | extend Box<T: Named> {
      |               ^~~~~

and a type argument that misses a conditional conformance says so too ('Box<String>' conforms to 'Shape' only when 'String' conforms to 'Shape').

• Only the struct’s own parameters can carry an extension’s constraints: extend Box<int: Shape> is an error.
• A conformance that holds for every Box needs its members on every Box: extend Box<T> with Named cannot rest on a name() that only extend Box<T: Named> provides. Make the conformance conditional instead (extend Box<T: Named> with Named).
• Several extensions may declare the same trait with different constraints; a specialization conforms when it meets any of them.
• Inside another generic, a call such as b.label() on a Box<T> is checked in each specialization, like any member of a generic struct.

Overriding a generic function for one type

You can give a generic function a separate definition for a specific type argument. Write the concrete type where the type parameter would go:

# The generic version handles every type...
describe<T>(value: T): String {
    return "something";
}

# ...and these definitions replace it for two specific types.
describe<int>(value: int): String {
    return "an int";
}

describe<String>(value: String): String {
    return "a String";
}

main(): int {
    assert(describe<float>(1.5) == "something", "the generic version");
    assert(describe<int>(7) == "an int", "the int override");
    assert(describe<String>("hi") == "a String", "the String override");

    # The standard library's hash<String> is such an override: it hashes
    # a String by its content instead of by identity.
    assert(hash<String>("pepper") == hash<String>("pepper"), "content hash");
    return 0;
}

A call whose type argument matches an override, such as describe<int>(7), uses the override; every other call uses the generic version. The standard library uses this to give hash<String> a content-based hash, while hash<T> hashes other structs by identity; a struct keyed by its content overrides hash<T> the same way (see Hashing and equality).

An override can name a built-in type (int, bool, String, and so on) or a struct, such as describe<Point>. It must be declared next to the generic function or next to one of its type arguments: in the file that declares either, or in another file of the same module. Here main.pep overrides shapes.pep’s describe<T> for its own Point, and the generic code in shapes.pep uses the override too:

# A generic function, and code that calls it for any type.
export describe<T>(v: T): int {
    return 0;
}

export describe_twice<T>(v: T): int {
    return describe<T>(v) * 2;
}

import "shapes";

struct Point {
    var x: int;
    var y: int;
}

# Overrides shapes.pep's describe<T> for Point, from another file.
describe<Point>(p: Point): int {
    return p.x + p.y;
}

main(): int {
    var p = Point();
    p.x = 3;
    p.y = 4;
    assert(describe<Point>(p) == 7, "the override");
    assert(describe_twice<Point>(p) == 14, "generic code in shapes.pep uses it too");
    assert(describe<int>(5) == 0, "other types keep the generic version");

    # The standard library's generics, such as hash<T>, can be overridden
    # for a struct the same way.
    return 0;
}

A function whose type parameters all name types the file can see (its own, the ones it imports, under any name such as P after import [Point as P] from geo, and the standard library’s) is an override when the file can also see a generic function of that name and number of type parameters (its own, an imported one, or the standard library’s); otherwise a struct’s name is just the name of a type parameter. The generic may be spelled by any name the file has for it (show<Point> after import [describe as show]). A type argument must name a struct, not a type alias or a trait. A generic and another function of the same name in one file are overloads, unless they have the same parameters, or the generic’s type parameters all name structs the file can see without a generic of that name to override: either is an error, since it usually means an override whose type argument the file cannot see, or of a generic the file’s own function of that name hides.

This placement rule (Rust calls it the orphan rule) means a file that can see both the generic and the type can also see every override that applies to them, so the compiler can check each file on its own. An override that neither of them is declared beside is an error:

main.pep:2:1: error: cannot override 'hash' for 'int' here: an override must be in the file or module that declares 'hash' or one of its type arguments
    2 | hash<int>(value: int): ulong {
      | ^~~~

The standard library’s generics, such as hash<T> and to_string<T>, can be overridden for your own structs, but not for built-in types: the standard library declares both. Wrap the built-in type in a struct of your own instead.

To add methods to a generic struct from outside its declaration, use an extension.

Reflection and attributes

A program can look at its own types while it compiles: list a struct’s fields, read the attributes written on them, and generate code for each one. This is how one function can turn any struct into JSON, declare a command-line option per field, or compare two values field by field.

The work happens in the compiler, in a static block, so it costs nothing at run time and needs no type information in the program. This is the model of Zig’s comptime and C++’s static reflection, not of Java or C# runtime reflection.

struct Point {
    var x: int;
    var y: int;
    var label: String;
}

# One function describes any struct: the `static` block runs in the
# compiler, once per type `describe` is called with.
describe<T>(value: T): String {
    var out = StringBuilder();
    static (out, value) {
        out.append(reflect.name<T>());
        out.append("(");
        for (var field in reflect.properties<T>()) {
            # `field.name` is a compile-time string; `field.get(value)` reads
            # the field. Both statements use `out`, a captured runtime
            # value, so they are emitted once per field.
            out.append($"{field.name} = {field.get(value)}");
            if (!field.is_last) {
                out.append(", ");
            }
        }
    }
    out.append(")");
    return out.to_string();
}

main(): int {
    var p = Point();
    p.x = 3;
    p.y = 4;
    p.label = "corner";
    assert(describe(p) == "Point(x = 3, y = 4, label = corner)", "one line per field, in declaration order");
    return 0;
}

static blocks

A static block is written inside a function. It names, in parentheses, the runtime values it may emit code against: its capture list.

static (out, value) {
    ...
}

static { ... } with no list is pure compile-time work, such as a check with reflect.assert.

Each statement in the block either runs in the compiler or is emitted into the function:

• A statement that uses a captured name, or a runtime local the block declares, is emitted. Its compile-time parts are filled in first: out.append(field.name) emits out.append("x").
• Everything else runs in the compiler: var declarations whose value uses no captured name, if on a compile-time condition (only the branch taken is kept), for over a compile-time list, which is unrolled, one copy of its body per element, and while on a compile-time condition, which emits its body once per iteration.
• An if whose condition uses a captured name is emitted as a runtime if; its branches can still hold compile-time steps.

A var with a captured name in its value is a runtime local, and using it counts as using a capture. Using a runtime value that is not captured is an error at that name:

main.pep:9:24: error: 'total' is a runtime value; add it to the static block's capture list

Each pass of an unrolled for or while, and the branch an if keeps, is its own block, like the body of a real loop.

A closure in an emitted statement is an ordinary closure: it captures runtime locals as any closure does. Its body cannot use a compile-time value such as field.name, since the closure outlives the block’s expansion; copy the value into a runtime local first, and the closure captures that local:

static (options, calls) {
    for (var field in reflect.fields<Options>()) {
        var text = $"{field.get(options)}";
        calls.append(() => text);
    }
}

Compile-time loops

break and continue in a compile-time for or while run in the compiler: continue drops the rest of the pass, and break ends the unrolling. They cannot sit in a runtime if, whose condition the compiler does not know:

main.pep:10:17: error: 'break' in a runtime 'if' cannot leave a compile-time loop; the condition is not known while compiling

A while that runs 100,000 times is taken to be endless and stops the compile at its while.

struct Row {
    var id: int;
    var _cache: int;
    var name: String;
    var score: int;
    var notes: String;
}

# The sum of the public `int` fields of `Row` before 'notes': `continue`
# and `break` steer the unrolled `for`.
sum_leading_ints(row: Row): int {
    var total = 0;
    static (total, row) {
        for (var field in reflect.fields<Row>()) {
            if (field.name.starts_with("_")) {
                continue;
            }
            if (field.name == "notes") {
                break;
            }
            if (reflect.is_same<field.Type, int>()) {
                total += field.get(row);
            }
        }
    }
    return total;
}

# A compile-time `while` emits its body once per iteration: here, the
# first four powers of three, as four additions.
powers_of_three(): int {
    var sum = 0;
    static (sum) {
        var power = 1;
        while (power < 30) {
            sum += power;
            power = power * 3;
        }
    }
    return sum;
}

main(): int {
    var row = Row();
    row.id = 2;
    row.score = 40;
    assert(sum_leading_ints(row) == 42, "id and score; _cache is skipped");
    assert(powers_of_three() == 1 + 3 + 9 + 27, "one addition per iteration");
    return 0;
}

In generic code

In a generic function, a static block runs once for each specialization, when its type arguments are known: describe<Point> and describe<Line> each get their own expansion. Code the block emits can call other generic functions, such as describe(field.get(value)) for a field that is itself a struct, and those are specialized in turn. A mistake in a block is reported when some specialization uses it, with the pass it happened in and, when a generic asked for that specialization, a note at each use that led to it ('dump<Point>' is used by 'main' here):

main.pep:14:13: error: 'print' cannot be called at compile time
main.pep:12:27: note: in pass 1 of 2 (member 'x')
note: a 'static' block can call the 'reflect' functions and the methods of what they return; calling other functions at compile time is not supported yet
main.pep:10:1: note: in the static block of 'dump<Point>'

At module scope

A static block outside any function runs once, while compiling. It has nothing to capture and emits no code; instead, each const declared at the top of the block becomes a module-scope constant holding what the block computed. Its other vars, and anything declared in its loops and branches, stay in the compiler. export static exports its constants, and attributes written above the block ([Target(...)]) apply to them too.

export struct Pixel {
    var red: u8;
    var green: u8;
    var blue: u8;
    var alpha: u8;
}

export enum Channel {
    Red,
    Green,
    Blue,
    Alpha
}

# A module-scope `static` block runs once, while compiling. Each `const` at
# its top becomes a module-scope constant holding what the block computed;
# `export static` exports them.
export static {
    var bytes = 0;
    for (var field in reflect.properties<Pixel>()) {
        reflect.assert(reflect.is_same<field.Type, u8>(), $"'{field.name}' must be one byte");
        bytes += 1;
    }
    const PIXEL_BYTES = bytes;
    const LAST_CHANNEL = reflect.cases<Channel>()[reflect.cases<Channel>().count - 1].get();
}

import "sizes";

main(): int {
    assert(PIXEL_BYTES == 4, "one byte per field of Pixel");
    assert(LAST_CHANNEL == Channel.Alpha, "the last case of Channel");
    return 0;
}

A constant takes a number, bool, character or enum case; a module-scope variable cannot be a String, since it must be thread-safe. At module scope, a case’s get() is the case itself, and a statement that would emit code is an error:

main.pep:7:9: error: a module-scope 'static' block cannot emit code; declare a 'const' with what it computes

What the compiler can evaluate

Compile-time values are integers, floating-point numbers, bool, strings, enum cases, and what the reflect functions return: members, cases, functions, lists and attributes. Expressions can use literals, the arithmetic, comparison and logical operators, + on strings, interpolated strings ($"{field.name}: "), ?:, assignment to a compile-time var (n += 1), and indexing a list. A string has length, is_empty, starts_with, ends_with and contains; a list has count and is_empty.

Emitted code can use a compile-time number, bool, string or enum case; the compiler writes it as a literal.

Seeing what a block does

A static block runs inside the compiler, so a print in it would be emitted into the program instead of showing anything while compiling. These show what the block computes:

• reflect.print(value) writes value as a note each time the compiler runs it, on every compile, including one that succeeds. In an unrolled loop each note says which pass printed it:

  main.pep:9:17: note: static print: "describing Point"
      9 |         reflect.print($"describing {reflect.name<T>()}");
        |                 ^~~~~
  main.pep:11:21: note: static print: "x"
     11 |             reflect.print(field.name);
        |                     ^~~~~
  main.pep:10:27: note: in pass 1 of 2 (member 'x')
     10 |         for (var field in reflect.properties<T>()) {
        |                           ^~~~~~~~~~~~~~~~~~~~~~~
  

• reflect.assert(condition, message) and reflect.error(message) stop the compile at that point with message, which can be an interpolated string holding the values that matter (reflect.assert(n < 8, $"{reflect.name<T>()} has {n} fields")). Like every error in a block, it carries the pass and, in generic code, the specialization it happened in (see In generic code).

• The emitted code runs like code written by hand. Each statement a block emits keeps the source line of the statement it came from, so a runtime print it emits shows values as the program runs, and a debugger breakpoint on that line (with -g) stops there, in every pass. Stepping goes through an unrolled loop pass by pass, stopping on the for line and then on the body, and the debugger shows the compile-time variables, such as the loop’s field (see Stepping through a static block).

• --emit-static writes the program’s source with each block replaced by what it emits (see the next section).

• --emit-llvm writes the program’s LLVM IR into the build directory (.pep/build/<name>.ll), where the function a block expanded in shows exactly what it emitted, one copy per specialization (describe<Point>). --emit-ast prints the program as parsed, before any block runs, so it does not show the expansion.

Seeing what a static block emits

pepper build main.pep --emit-static writes a copy of the program with each static block replaced by the statements it emits, the way a C compiler’s -E shows the preprocessed source. Nothing is compiled; the copy goes into main.static/ (or the folder -o names) and builds into the same program. For the describe example at the top of this page, the copy keeps describe<T> as written and adds what it is for Point:

# 'describe' specialized for T = Point, with its static blocks expanded
describe<Point>(value: Point): String {
    var out = StringBuilder();
    # static (out, value) expanded from reflection-basics.pep:11:5 for T = Point
    {
        out.append("Point");
        out.append("(");
        {
            out.append($"x = {value.x}");
            {
                out.append(", ");
            }
        }
        {
            out.append($"y = {value.y}");
            {
                out.append(", ");
            }
        }
        {
            out.append($"label = {value.label}");
        }
    }
    # end static
    out.append(")");
    return out.to_string();
}

• Each pass of an unrolled for or while is a block of its own, one after another; a compile-time if leaves only the branch it took; the compile-time vars and steps are gone.
• Compile-time values are written as literals: field.name becomes "x" (inside an interpolated string, its text), field.Type the type, field.get(value) value.x, case.matches(v) v is Shape.Circle, and function.call() a call by name. A case’s value, item.get(v), becomes a match that reads it.
• Everything else in the file is copied byte for byte, comments included. --emit-static=keep also keeps each block as # comments above its expansion.
• A block in a generic function expands differently for each type, so the copy adds a concrete override per specialization the program uses, as above. A block in a method of a generic struct, or in a generic method, stays as written, with each specialization’s expansion above it as comments.
• An error in the emitted code shows when the copy is built, at the line of the copy that has it.
• To debug the program in the expanded source, build it with -g --debug-static=expanded: the copy is written beside the program as main.static.pep, and the debugger steps through it (see Stepping through a static block). In a method of a generic struct or a generic method, where the copy shows the expansion only as comments, the debugger shows the block as written.

pep-build lists the details.

The reflect functions

reflect is built in: a static block uses it without an import. The reference has an entry for each function and for the members, cases and functions they return.

fields exists for code a struct’s author writes, such as a field-by-field ==; anywhere else it is an error, which points at properties:

main.pep:4:24: error: 'fields' of 'Account' is only available in the file that declares 'Account'; use 'properties'

A member (from properties or fields) has:

• name, index, is_last, is_const, is_property
• type_name: its type as a string; field.Type is the type itself, usable wherever a type is written: var copy: field.Type = ..., reflect.is_same<field.Type, String>(), parse<field.Type>(text). This works for a compile-time var holding a member too (var first = case.values[0]; gives first.Type).
• has_attribute<A>() and attribute<A>()
• get(value) and set(value, x), which emit value.name and value.name = x

A case (from cases) has:

• name, value (its integer value, or the tag of a case that can carry values), index, is_last, has_attribute<A>(), attribute<A>()
• values: the values the case carries, as members, in order; empty for a case that carries none. A value’s get(v) reads it from v, which must hold this case; set is an error, since a case’s values are fixed.
• matches(v), which emits a test of whether v holds this case
• get(values...), which emits the case made with those values: case.get() for a case that carries none, case.get(r) for Circle(radius: int)

A function (from functions_with) has name, has_attribute<A>(), attribute<A>(), and call(arguments...), which emits a direct call.

enum Level {
    Low,
    High = 10,
}

struct Settings {
    var name: String;
    var retries: int;
    var verbose: bool;
    var level: Level;
}

# A compile-time `if` keeps only the branch it takes, so each field is
# written by the code that fits its type.
render<T>(value: T): String {
    var out = StringBuilder();
    static (out, value) {
        for (var field in reflect.properties<T>()) {
            out.append($"{field.name}=");
            if (reflect.is_same<field.Type, String>()) {
                out.append($"\"{field.get(value)}\"");
            } else if (reflect.is_enum<field.Type>()) {
                out.append(level_name(field.get(value)));
            } else {
                out.append($"{field.get(value)}");
            }
            out.append(";");
        }
    }
    return out.to_string();
}

# `reflect.cases<E>()` lists an enum's cases; `case.get()` is the case
# itself in emitted code.
level_name(level: Level): String {
    var name = "";
    static (level, name) {
        for (var case in reflect.cases<Level>()) {
            if (level == case.get()) {
                name = case.name;
            }
        }
    }
    return name;
}

# `field.set(value, x)` assigns a field.
reset_counts<T>(value: T) {
    static (value) {
        for (var field in reflect.properties<T>()) {
            if (reflect.is_same<field.Type, int>()) {
                field.set(value, 0);
            }
        }
    }
}

main(): int {
    var settings = Settings();
    settings.name = "fast";
    settings.retries = 3;
    settings.level = Level.High;
    assert(
        render(settings) == "name=\"fast\";retries=3;verbose=false;level=High;",
        "each field is written by the code for its type"
    );
    reset_counts(settings);
    assert(settings.retries == 0, "set assigns the int fields");
    return 0;
}

struct Account {
    var owner: String;
    var _balance: int;

    construct(this.owner = "", this._balance = 0) {}

    # `reflect.fields<T>()` lists private fields too, so it is available
    # only in the file that declares `T`: code its author writes, like this
    # field-by-field `==`.
    ==(other: Account): bool {
        var same = true;
        static (same, other) {
            for (var field in reflect.fields<Account>()) {
                same = same && field.get(this) == field.get(other);
            }
        }
        return same;
    }
}

main(): int {
    assert(Account("ann", 5) == Account("ann", 5), "equal fields compare equal");
    assert(!(Account("ann", 5) == Account("ann", 6)), "a private field takes part");
    return 0;
}

enum Shape {
    Circle(radius: int),
    Rect(width: int, height: int),
    Point,
}

# `case.matches(value)` tests which case a value holds, and each of the
# case's `values` reads its value with `get`.
describe<E>(value: E): String {
    var out = "";
    static (out, value) {
        for (var case in reflect.cases<E>()) {
            if (case.matches(value)) {
                out = case.name;
                for (var item in case.values) {
                    out = out + $" {item.name}={item.get(value)}";
                }
            }
        }
    }
    return out;
}

# `case.get(values...)` makes a case; here, each value is `size`.
square<E>(name: String, size: int): E {
    var out: E;
    static (out, name, size) {
        for (var case in reflect.cases<E>()) {
            if (name == case.name) {
                if (case.values.count == 0) {
                    out = case.get();
                } else if (case.values.count == 1) {
                    out = case.get(size);
                } else if (case.values.count == 2) {
                    out = case.get(size, size);
                }
            }
        }
    }
    return out;
}

main(): int {
    assert(describe(Shape.Rect(3, 4)) == "Rect width=3 height=4", "a case's values");
    assert(describe(Shape.Point) == "Point", "a case without values");
    assert(describe(square<Shape>("Rect", 5)) == "Rect width=5 height=5", "a made case");
    assert(describe(square<Shape>("Circle", 2)) == "Circle radius=2", "one value");
    return 0;
}

Attributes

An attribute is a struct marked [Attribute]. Writing it above a declaration records a compile-time value of that struct, which has_attribute<A>() tests for and attribute<A>() returns.

# An attribute is a struct marked `[Attribute]`. Its fields hold what a
# use of it says; a field with an initializer may be left out.
[Attribute]
struct Name {
    const value: String;
}

[Attribute]
struct Ignore {}

struct User {
    [Name("user_id")]
    var id: int;
    var email: String;
    [Ignore]
    var session: int;
}

# The keys a struct's fields are written under: each field's `[Name]` if
# it has one, else the field's own name, skipping `[Ignore]`d fields.
keys<T>(): String[] {
    var keys: String[] = [];
    static (keys) {
        for (var field in reflect.properties<T>()) {
            if (!field.has_attribute<Ignore>()) {
                var key = field.name;
                if (field.has_attribute<Name>()) {
                    key = field.attribute<Name>().value;
                }
                keys.append(key);
            }
        }
    }
    return keys;
}

main(): int {
    var found = keys<User>();
    assert(found.count == 2, "the [Ignore]d field is skipped");
    assert(found[0] == "user_id", "[Name] renames the key");
    assert(found[1] == "email", "a field without [Name] keeps its name");
    return 0;
}

• Fields of an attribute struct are numbers, bool, char, String, or enums whose cases carry no values.
• Arguments are constants: literals, a negated number, an enum case (Level.High), or strings joined with +. They can be named: [Check(weight = 3)].
• Without a constructor, the arguments set the fields in order, and a field with an initializer may be left out. A constructor may take this.field parameters, or parameters its body assigns to fields (this.long_name = long_name;), which is all its body may do.
• An attribute from another module can be named through it, with or without arguments: [serialize.Ignore], [serialize.Name("key")].
• An attribute that names neither a built-in attribute nor an [Attribute] struct is an error, at its name: unknown attribute 'Optoin'.
• Built-in attributes (Target, Shared, Deprecated, …) are [Attribute] structs too, declared in the runtime (attributes), so a block reads them like its own: function.attribute<Deprecated>().message. Target holds its condition as written ("!OS(Windows)"). The compiler still checks and acts on each one itself.

struct Settings {
    var width: int;
    [Deprecated("use 'width' instead", "width")]
    var size: int;
}

# Lists the deprecated fields of `T` with what replaces each, read from the
# built-in `Deprecated` attribute like any `[Attribute]` struct.
deprecated_fields<T>(): String {
    var out = "";
    static (out) {
        for (var field in reflect.properties<T>()) {
            if (field.has_attribute<Deprecated>()) {
                out = out + $"{field.name} -> {field.attribute<Deprecated>().replacement};";
            }
        }
    }
    return out;
}

main(): int {
    assert(deprecated_fields<Settings>() == "size -> width;", "one deprecated field");
    return 0;
}

Attributes can go on structs, enums and their cases, fields, functions, methods, constructors, parameters and module-scope variables.

[Attribute]
struct Check {
    const weight: int = 1;
}

[Check]
check_addition(): bool {
    return 1 + 1 == 2;
}

[Check(weight = 3)]
check_strings(): bool {
    return "ab" + "c" == "abc";
}

# `reflect.functions_with<A>()` lists every function in the program that
# carries `A`; `check.call()` calls it directly.
run_checks(): int {
    var score = 0;
    static (score) {
        for (var check in reflect.functions_with<Check>()) {
            if (check.call()) {
                score += check.attribute<Check>().weight;
            }
        }
    }
    return score;
}

main(): int {
    assert(run_checks() == 4, "each [Check] function runs once, weighted");
    return 0;
}

Not supported yet

• Calling functions other than the reflect functions at compile time.
• Reflecting methods and constructors (reflect.methods<T>()).
• Limiting where an attribute may be used ([AttributeTargets(...)]).
• Tracing the blocks the compiler runs.
• Type information at run time.

Type aliases

A type alias gives an existing type another name. Use one to shorten a long type that you write often, such as HashMap<String, Array<int>>, or to say what a value means, such as Score instead of int.

Declaring an alias

Write type, the new name, =, and the type it stands for:

# An alias is another name for an existing type.
type Score = int;
type Names = Array<String>;
type Handler = (int) => int;

struct Player {
    var name: String;
    var best: Score = 0;        # aliases work in fields...
}

type Team = Player;

double_it(x: int): int {
    return x * 2;
}

# ...and in parameters and return types.
apply(h: Handler, x: Score): Score {
    return h(x);
}

main(): int {
    var s: Score = 21;
    var plain: int = s;         # Score and int are the same type
    assert(apply(double_it, plain) == 42, "function type alias");

    var names = Names();        # construct through the alias
    names.append("Ada");
    assert(names.count == 1, "Names is Array<String>");

    var p = Team();
    p.best = s;
    var q: Player = p;          # Team and Player are the same type
    assert(q.best == 21, "struct alias");
    return 0;
}

An alias is only a spelling, not a new type. The compiler replaces every use of the alias with its target before it checks anything else, so Score and int are interchangeable: you can assign one to the other, pass one where the other is expected, and error messages name the target type.

You can use an alias anywhere a type can appear: local and module-level variables, parameters, return types, struct fields, generic arguments, and casts. An alias of a struct also works where the struct’s name would: to construct it (Team()) and to call its static methods.

Generic aliases

An alias can have type parameters of its own, including defaults, just like a generic struct:

# Generic aliases take their own type parameters.
type Predicate<T> = (T) => bool;
type Lookup<V> = HashMap<String, V>;
type Outcome<T, E=Error> = Result<T, E>;

is_even(x: int): bool {
    return x % 2 == 0;
}

count_matching(values: Array<int>, test: Predicate<int>): int {
    var n = 0;
    for (var v in values) {
        if (test(v)) {
            n += 1;
        }
    }
    return n;
}

parse_digit(text: String): Outcome<int> {
    if (text == "7") {
        return Outcome<int>.ok(7);
    }
    return Outcome<int>.err(Error("not a digit I know"));
}

main(): int {
    var values = Array<int>();
    values.append(1);
    values.append(2);
    values.append(4);
    assert(count_matching(values, is_even) == 2, "Predicate<int> is (int) => bool");

    var ages = Lookup<int>();   # HashMap<String, int>
    ages.insert("Ada", 36);
    assert(ages.contains("Ada"), "Lookup<int> is HashMap<String, int>");

    # Outcome<int> fills E with its default: Result<int, Error>.
    assert(parse_digit("7").value() == 7, "ok");
    assert(parse_digit("x").is_err(), "err");
    return 0;
}

The arguments at the use site fill the alias’s parameters in order, and omitted ones take their defaults. Outcome<int> becomes Result<int, Error>, and Lookup<int> becomes HashMap<String, int>. Aliases are especially handy for function types, which are long to write out: Predicate<int> reads better than (int) => bool.

Aliases across files

Like other top-level declarations, an alias is private to the file (or module) that declares it. Mark it export to let files that import it use it; see Visibility and Modules and imports.

Recursive aliases

An alias must not refer to itself, directly or through other aliases. The compiler reports the cycle at the alias, with a note at each alias it passes through:

type Celsius = Degrees;
type Degrees = Celsius;

main.pep:1:6: error: type alias 'Celsius' refers to itself
    1 | type Celsius = Degrees;
      |      ^~~~~~~
main.pep:2:6: note: through type alias 'Degrees', declared here
    2 | type Degrees = Celsius;
      |      ^~~~~~~

Traits and extensions

Pepper has no inheritance. Instead, you add behavior to a type with an extension, and describe a set of behavior that several types share with a trait. Extensions can be written anywhere, so you can add methods to a library type, such as String, from your own code.

A trait is also a type: a value of type Shape holds any struct, or enum whose cases carry values, that has the Shape trait, and calls its methods (see Traits as types).

Extensions

An extend block adds methods to a struct declared elsewhere, whether in the same file, another file, or the standard library:

struct Temperature {
    var celsius: float = 0.0;
    construct(this.celsius = 0.0) {}
}

# `extend` adds methods to a struct declared elsewhere.
extend Temperature {
    fahrenheit(): float {
        return celsius * 9.0 / 5.0 + 32.0;
    }

    static freezing(): Temperature {
        return Temperature(0.0);
    }

    bool ==(Temperature other) {
        return celsius == other.celsius;
    }
}

# Library types can be extended too.
extend String {
    exclaim(): String {
        var s = String();
        s.append(this);
        s.append("!");
        return s;
    }
}

# One specialization of a generic library type can be extended, and its
# methods can loop over `this`.
extend Array<int> {
    total(): int {
        var sum = 0;
        for (var x in this) {
            sum += x;
        }
        return sum;
    }
}

struct Box<T> {
    var value: T;
}

# Extending the generic struct adds the method to every Box<...>.
extend Box<T> {
    get(): T {
        return value;
    }
}

main(): int {
    var t = Temperature(100.0);
    assert(t.fahrenheit() == 212.0, "extension method");
    assert(Temperature.freezing() == Temperature(0.0), "static method and operator from an extension");

    assert("hello".exclaim() == "hello!", "String extension");

    var numbers = Array<int>();
    numbers.append(2);
    numbers.append(3);
    assert(numbers.total() == 5, "Array<int> extension loops over this");

    var b = Box<int>();
    b.value = 5;
    assert(b.get() == 5, "Box<int>");
    var s = Box<String>();
    s.value = "five";
    assert(s.get() == "five", "Box<String>");
    return 0;
}

• An extension can hold anything a struct body can hold except fields, a constructor, and a destructor: methods, static methods, operators, and indexers.
• Methods in an extension behave exactly like methods declared in the struct. They can use this and name the struct’s fields directly, and they are called the same way.
• A type can have any number of extensions.
• An extension method may share its name with the struct’s methods if its parameter types differ: it joins their overload set.
• An extension in another file is usable only where that file (or its module) is imported, and only if it is exported; the standard library’s extensions are usable everywhere. See Visibility.

Extending generic structs

extend Box<T>, using the struct’s own type parameter name, adds the methods to every specialization: Box<int>, Box<String>, and so on. The example above does this.

When Box constrains its parameter (struct Box<T: Shape>), the extension keeps the constraint without restating it; extend Box<T: Shape> may restate it as documentation (see constraints). A constraint the struct does not have limits the extension to the specializations that meet it: extend Box<T: Named> { ... } adds its methods to Box<Square> but not to Box<String>, and extend Box<T: Shape> with Shape makes a Box of shapes a shape (see constrained extensions).

extend Box<int> targets one specialization: its methods exist only on Box<int>, and calling one on a Box<String> is an error (no member named 'doubled' in 'Box<String>').

A library type’s specialization can be extended the same way. The example’s extend Array<int> adds total(), which loops over this with for.

An extension cannot add fields; declare every field in the struct itself.

Traits

A trait names a set of methods. Declare one with trait and method signatures ending in ;. Then declare that a type has the trait with extend Type with Trait, and provide the methods in that extension:

# A trait names a set of methods that a type provides.
trait Shape {
    area(): int;
    name(): String;

    # A method with a body is a default: every type with the trait gets it.
    describe(): String {
        return "a " + name();
    }
}

struct Square {
    var side: int = 1;
    construct(this.side = 1) {}
}

# `extend ... with` declares that Square has the Shape trait, and adds the
# trait's methods to it.
extend Square with Shape {
    area(): int {
        return side * side;
    }

    name(): String {
        return "square";
    }
}

# A trait can be generic, and can declare static methods; `this` as a type
# stands for the type that has the trait.
trait From<T> {
    static this from(T value);
}

extend Square with From<int> {
    static Square from(int side) {
        return Square(side);
    }
}

# A trait whose methods all have defaults needs no body: end the extension
# with `;`, the same as writing an empty `{}`.
trait Labeled {
    label(): String {
        return "shape";
    }
}

extend Square with Labeled;

main(): int {
    var sq = Square(3);
    assert(sq.area() == 9, "trait method called on the struct");
    assert(sq.name() == "square", "second trait method");
    assert(sq.describe() == "a square", "default method from the trait");
    assert(Square.from(4).area() == 16, "static method from a generic trait");
    assert(sq.label() == "shape", "default method from a bodiless extension");
    return 0;
}

• A trait can have type parameters, like From<T>.
• A trait can declare static methods. In a trait, this used as a type stands for the type that has the trait.
• extend Square with Shape, Printable { ... } attaches several traits at once.
• When the type already has every method the traits need, from its own methods or the traits’ defaults, the extension can end with ; instead of a body: extend Square with Labeled; is the same as extend Square with Labeled {}. Only an extension with a with clause can leave out its body; pep-fmt writes an empty one as ;.
• A trait can declare several methods of one name with different parameter types; the type implements each with the method whose parameter types match (see Overloading).
• The methods in the extension are ordinary methods of the struct, so you call them on a Square as usual.
• A generic parameter can require a trait, total_area<T: Shape>, so that only types declared to have it are accepted (see constraints).
• The runtime declares traits too. ToString (to_string(): String) makes a type usable in an interpolated string.

The compiler checks that the type has every method the trait declares, either in the extension or in the struct itself. A missing method is an error at the extension, with a note at the trait’s method:

main.pep:9:8: error: 'Square' does not implement 'area', required by trait 'Shape'
    9 | extend Square with Shape {
      |        ^~~~~~
main.pep:2:5: note: 'area' declared here
    2 |     area(): int;
      |     ^~~~

A method that implements a trait should name its parameters as the trait does, since a call through a value of the trait type names its arguments with the trait’s names. A different name is a warning, whose fix renames the parameter and its uses:

main.pep:8:10: warning: parameter 'factor' of 'area' is named 'scale' in trait 'Shape'
    8 |     area(factor: int): int { return side * side * factor; }
      |          ^~~~~~
main.pep:2:5: note: 'area' declared here
    2 |     area(scale: int): int;
      |     ^~~~

Default method bodies

A trait method can have a body. A type that has the trait and does not define that method gets the trait’s body as its own method; a type that defines the method keeps its own. Inside a default body, the trait’s type parameters and this stand for the types named in the with clause:

trait Shape {
    area(): int;
    sides(): int { return 4; }
}

extend Square with Shape {
    area(): int { return side * side; }
}

Here Square(3).sides() returns 4.

A default method can have type parameters of its own (see Generic methods). The runtime’s Iterator<T> uses this for its map<U> and filter adapters, which every type that declares Iterator<T> gets.

A default body sees only what its trait declares: a bare call to one of the trait’s methods calls it on this, and any other bare name means what it means where the trait is declared (a top-level function or variable), even when a conforming type happens to have a method or field of that name. Call through this explicitly only for the trait’s own methods.

A closure in a default body can use this and the trait’s methods too. Each type that gets the default gets its own copy of the closure, which captures this as that type, as a closure in one of its own methods would (see this in methods):

# A closure in a trait's default method can use `this` and the trait's
# methods.
trait Shape {
    area(): int;

    # Every type with Shape gets this method, and its own copy of the
    # closure, which captures `this`.
    scaled_area(): (int) => int {
        return (factor: int) => area() * factor;
    }
}

struct Square {
    var side: int = 1;
    construct(this.side = 1) {}
}

extend Square with Shape {
    area(): int {
        return side * side;
    }
}

main(): int {
    var square = Square(3);
    var scale = square.scaled_area();
    assert(scale(2) == 18, "closure in a default method");

    # The closure keeps the square alive and sees its current side.
    square.side = 4;
    assert(scale(2) == 32, "sees the current value");
    return 0;
}

Numbers, bool and enums

A number type (int, long, byte, char, float, double and the rest), bool, or an enum whose cases carry no values can declare a trait too, with an extension written the same way. Inside its methods, this is the value:

trait Describe {
    describe(): String;
    # A default method works for value types too.
    shout(): String { return describe() + "!"; }
}

trait Zero {
    static zero(): this;
}

# A number type conforms like a struct; `this` is the value.
extend int with Describe {
    describe(): String { return this < 0 ? "negative" : "non-negative"; }
}

extend int with Zero {
    static zero(): int { return 0; }
}

enum Light {
    Red,
    Green,
}

# An enum whose cases carry no values can conform too.
extend Light with Describe {
    describe(): String { return this == Light.Red ? "stop" : "go"; }
}

# Each call is resolved for the type argument: no trait value is made.
describe_all<T: Describe>(items: Array<T>): String {
    var text = "";
    for (var item in items) {
        text = text + item.describe() + " ";
    }
    return text;
}

zero_of<T: Zero>(): T { return T.zero(); }

main(): int {
    var numbers = Array<int>();
    numbers.append(-1);
    numbers.append(2);
    assert(describe_all(numbers) == "negative non-negative ", "numbers");
    assert(Light.Green.shout() == "go!", "enum");
    assert((5).describe() == "non-negative", "a call on a value");
    assert(zero_of<int>() == 0, "a static member through T");
    return 0;
}

• The type then meets the constraint T: Describe (see constraints), and its methods can be called on a value (x.describe()) or, for a static one, on the type (int.zero(), or T.zero() in a generic). Each call goes straight to the method: there is no object and no vtable.

• It is never a trait value. A number or such an enum cannot be stored in a Describe variable, passed as one, or added to an Array<Describe>:

  main.pep:7:15: error: 'int' cannot be converted to trait 'Doubled': only structs and enums whose cases carry values can be trait values
      7 | main(): int { Doubled d = 3; return 0; }
        |               ^~~~~~~
  main.pep:4:8: note: 'int' conforms to 'Doubled' here, which makes it meet the constraint, not a trait value
      4 | extend int with Doubled {
        |        ^~~
  

• An extension of a number type may also add methods without a trait (extend int { ... }), and operators for a number on the left of another type (extend double { *(v: Vector): Vector { ... } } makes 2.0 * v work; see A number on the left). An enum declares its methods inside the enum, so an extension of one must name a trait.

• The spellings of one type are one type: extend int is also extend i32.

Traits as types

A trait’s name is also a type. A variable, parameter, field, return value, or collection element of type Shape holds any struct, or enum whose cases carry values, that declares Shape, and calling a method on it runs that type’s own method:

# A trait used as a type holds any struct that declares the trait.
trait Shape {
    area(): int;
    name(): String;
}

struct Square {
    var side: int = 1;
    construct(this.side = 1) {}
}

extend Square with Shape {
    area(): int { return side * side; }
    name(): String { return "square"; }
}

struct Rect {
    var width: int = 1;
    var height: int = 1;
    construct(this.width = 1, this.height = 1) {}
}

extend Rect with Shape {
    area(): int { return width * height; }
    name(): String { return "rect"; }
}

# One function accepts every Shape; each call runs the value's own method.
measure(shape: Shape): int {
    return shape.area();
}

main(): int {
    # A Square converts to a Shape wherever a Shape is expected.
    var s: Shape = Square(3);
    assert(measure(s) == 9, "square through a trait parameter");
    assert(s.name() == "square", "method of the concrete type");

    # Collections can hold different types that share a trait.
    var shapes = Array<Shape>();
    shapes.append(Square(2));
    shapes.append(Rect(2, 5));
    var total = 0;
    for (var shape in shapes) {
        total = total + shape.area();
    }
    assert(total == 14, "sum of areas");

    # Two trait values are equal when they refer to the same object.
    var same: Shape = s;
    assert(same == s, "same object");
    return 0;
}

• Conversion is implicit. A Square becomes a Shape wherever a Shape is expected: an initializer, an assignment, an argument, a return value.

• Conformance is declared. Only a type that declares the trait with extend Type with Trait converts. Having the right methods is not enough:

  main.pep:11:20: error: 'Circle' does not conform to trait 'Shape'
     11 |     var s: Shape = Circle();
        |                    ^~~~~~
  main.pep:6:8: note: declare it with 'extend Circle with Shape'
      6 | struct Circle {
        |        ^~~~~~
  

• A trait value is a shared reference to the struct, like any other struct value (see Memory). When the last reference goes away, whether it was a Shape or a Square, the struct’s own destructor runs.

• Only instance methods are callable through the trait. Static methods, generic methods, and methods whose signature uses this as a type, need the concrete type; calling one through a trait value is an error.

• Methods must match the trait’s signature. An implementation with different parameter or return types is an error. The one exception is a trait method that returns a trait type: the implementation may return a struct that declares that trait, as iterate() does in Iteration.

• == and != on trait values compare identity: they are equal when they refer to the same object.

• copy copies the struct behind a trait value and returns it as the same trait type (see Copying trait values). It panics when that struct cannot be copied.

Converting a trait value back

A trait value remembers the struct it holds, so it converts back to that struct, or to another trait the struct declares. A type pattern names the type, like an enum case, and binds the value as that type:

# A trait value converts back to the struct it holds, or to another trait
# that struct declares, with `is`, `match` and `as?`.
trait Shape {
    area(): int;
}

trait Named {
    name(): String;
}

struct Square {
    var side: int = 1;
    construct(this.side = 1) {}
}

extend Square with Shape {
    area(): int { return side * side; }
}

extend Square with Named {
    name(): String { return "square"; }
}

struct Rect {
    var width: int = 1;
    var height: int = 1;
    construct(this.width = 1, this.height = 1) {}
}

extend Rect with Shape {
    area(): int { return width * height; }
}

# A type pattern tests for a struct and binds the value as that struct.
describe(shape: Shape): String {
    return match (shape) {
        Square(square) => $"a square of side {square.side}",
        Rect(rect) => $"a {rect.width} by {rect.height} rectangle",
        else => "another shape",
    };
}

main(): int {
    var shape: Shape = Square(3);
    assert(describe(shape) == "a square of side 3", "match on the struct");
    assert(describe(Rect(2, 5)) == "a 2 by 5 rectangle", "another struct");

    # `is` tests without converting; as an `if` condition it can bind.
    assert(shape is Square, "a square");
    assert(!(shape is Rect), "not a rectangle");
    if (shape is Square(square)) {
        assert(square.side == 3, "bound as a Square");
    }

    # `as?` gives an optional: Empty when the value is something else.
    var square = shape as? Square;
    assert(square.value().side == 3, "converted to Square");
    var rect = shape as? Rect;
    assert(rect.is_empty(), "not a Rect");

    # Converting to another trait works when the struct declares both.
    var named = shape as? Named;
    assert(named.value().name() == "square", "a Square is Named");
    var other: Shape = Rect(1, 1);
    assert((other as? Named).is_empty(), "a Rect is not Named");
    return 0;
}

• value is Square tests whether the value holds a Square. As the whole condition of an if or while, value is Square(square) also binds it, as for enums.

• match (value) { Square(square) => ..., Rect(rect) => ..., else => ... } picks the arm of the value’s struct. Any struct may declare a trait, so a match expression on a trait value needs an else arm.

• value as? Square converts the value, giving Square?: Empty when the value holds something else, or is null. as without the ? is an error for a trait value, since the conversion can fail.

• Another trait works the same way: value as? Named and value is Named succeed when the struct behind the value declares Named too.

• A generic struct is named with its type arguments: Cell<int>(cell).

• A value struct’s trait value holds a copy of it (see boxing), and converting back copies it out again.

• The bound value is another reference to the same object, like any copy (see Memory); a test holds no reference after it.

• Naming a struct that does not declare the trait is an error, since the value can never hold one:

  main.pep:9:18: error: 'Point' does not implement 'Shape', so a 'Shape' value never holds one
      9 |     if (shape is Point) {
        |                  ^~~~~
  

Weak references and atomics

Weak<Shape> is a weak reference to a trait value: it holds the struct’s weak reference and its vtable, and a with block upgrades it to a Shape while a strong reference is left:

# A weak reference can point at a trait value: it keeps the struct behind
# it without keeping it alive.
trait Shape {
    area(): int;
}

struct Square {
    var side: int = 1;
    construct(this.side = 1) {}
}

extend Square with Shape {
    area(): int { return side * side; }
}

main(): int {
    var shape: Shape = Square(3);
    var weak = Weak<Shape>(shape);

    # While a strong reference is left, `with` reaches the value as a Shape.
    with (var live = weak) {
        assert(live.area() == 9, "upgraded to a Shape");
    } else {
        assert(false, "still alive");
    }

    # Once the last strong reference goes, the Square is destroyed.
    shape = __null;
    assert(weak.expired(), "destroyed");
    with (var live = weak) {
        assert(false, "expired: the body is skipped");
    }
    return 0;
}

Atomic<Shape> is ruled out. Atomic<T> needs a thread-safe T, and a trait value may hold any struct, thread-safe or not; it is also two pointers wide, more than one atomic instruction swaps on every platform. The error is the one for any type that is not thread-safe:

main.pep:8:32: error: 'Shape' does not conform to 'Shared', required by 'T' in 'Atomic'
    8 |     var current = async.Atomic<Shape>();
      |                                ^~~~~

To share a trait value between threads, keep it in a Mutex<Shape> and swap it with replace, or use Atomic<Square> for one [Shared] struct type.

Iteration

A for loop visits each element of a collection in turn. You can loop over an Array, over the code points of a String, over a range of numbers (0..count), and over any type of your own that follows the iterator protocol.

Looping over an array

for (var x in source) { ... } runs the body once per element, with x bound to the element:

struct Item {
    int value;
    construct(this.value = 0) {}
}

make_items(): Array<Item> {
    var items = Array<Item>();
    items.append(Item(20));
    items.append(Item(22));
    return items;
}

main(): int {
    var nums = Array<int>();
    nums.append(1);
    nums.append(2);
    nums.append(39);

    # The basic loop: x takes each element in order.
    var total = 0;
    for (var x in nums) {
        total = total + x;
    }
    assert(total == 42, "sum of the elements");

    # The loop variable may be typed, and the parentheses are optional.
    long wide = 0;
    for (long x in nums) {
        wide = wide + x;
    }
    for var x: int in nums {
        wide = wide - x;
    }
    assert(wide == 0, "typed loop variables");

    # break and continue work as in a while loop.
    var odd = 0;
    for (var x in nums) {
        if (x % 2 == 0) {
            continue;
        }
        if (x > 10) {
            break;
        }
        odd = odd + x;
    }
    assert(odd == 1, "only 1 is odd and below 10");

    # A struct element is shared: changing a field changes the element,
    # but rebinding the loop variable does not touch the array.
    var items = make_items();
    for (var item in items) {
        item.value = item.value * 10;
        item = Item(99);
    }
    assert(items[0].value == 200, "first element was updated");
    assert(items[1].value == 220, "second element was updated");

    # Iterating a temporary keeps it alive for the whole loop.
    var sum = 0;
    for (var item in make_items()) {
        sum = sum + item.value;
    }
    assert(sum == 42, "temporary array stays alive");

    # The loop is shorthand for driving the iterator yourself.
    var it = nums.iterate();
    var manual = 0;
    while (it.next()) {
        manual = manual + it.current();
    }
    assert(manual == 42, "the same elements, by hand");

    # Modifying the array after the loop is fine.
    nums.append(100);
    assert(nums.count == 4, "appended after the loop");
    return 0;
}

The example shows each part of the loop:

• The loop variable can be declared with var or with a type: for (var x in nums), for (long x in nums), and for (var x: int in nums) all work.
• The parentheses are optional, as with if and while: for var x in nums { ... }. The braces are required.
• break and continue work as they do in a while loop.
• The loop variable is a copy, like any var. Assigning a new value to it does not change the collection. For a struct element, though, the copy is another reference to the same object (see Memory and reference counting), so item.value = ... does change the element.
• A temporary source stays alive. The loop holds a reference to what it iterates, so for (var item in make_items()) is safe.

Looping over a string

A String yields its code points one at a time. Each one is a String holding a single code point, the same value that indexing gives you (word[i]):

main(): int {
    var word = "héllo ✓";

    # A String yields one code point at a time, as a one-code-point String.
    var count = 0;
    var copy = "";
    for (var c in word) {
        assert(c.length == 1, "each piece is one code point");
        copy.append(c);
        count = count + 1;
    }
    assert(count == 7, "7 code points");
    assert(copy == word, "the pieces rebuild the string");

    # Each piece is the same value as indexing the string.
    var i = 0;
    for (var c in word) {
        assert(c == word[i], "same as word[i]");
        i = i + 1;
    }

    # An empty string runs the body zero times.
    for (var c in "") {
        assert(false, "never runs");
    }
    return 0;
}

Looping over a range

a..b is the numbers from a up to, but not including, b, and a..>b includes b. Looping over one is how you count:

main(): int {
    # `a..b` counts from a up to, but not including, b.
    var total = 0;
    for (var i in 0..5) {
        total += i;
    }
    assert(total == 10, "0 + 1 + 2 + 3 + 4");

    # `a..>b` includes b.
    var product = 1;
    for (var i in 1..>5) {
        product *= i;
    }
    assert(product == 120, "5 factorial");

    # The bounds give the type: `count` is a ulong, so i is too.
    var names = ["Ada", "Grace", "Edsger"];
    ulong letters = 0;
    for (var i in 0..names.count) {
        letters += names[i].size;
    }
    assert(letters == 14, "letters in every name");

    # A range that starts past its end is empty.
    for (var i in 3..1) {
        assert(false, "never runs");
    }

    # A range is a value: test membership, or use the iterator adapters.
    var digits = 0..10;
    assert(digits.contains(9) && !digits.contains(10), "half-open");
    var evens = 0;
    for (var even in (1..>10).filter((n) => n % 2 == 0)) {
        evens += even;
    }
    assert(evens == 30, "2 + 4 + 6 + 8 + 10");
    return 0;
}

• The bounds give the type. A range’s element type is inferred from its bounds like a generic call’s type argument, so 0..names.count counts in ulong. The bounds must be integers; anything else is an error at the operator:

  main.pep:2:22: error: range bounds must be integers, not 'String'
      2 |     for (var c in "a".."z") {
        |                      ^~
  

• Precedence. A range binds more loosely than arithmetic and shifts, and more tightly than comparisons, so 0..n + 1 is 0..(n + 1). Two range operators in a row (1..2..3) are an error; add parentheses. ... is not a range operator.

• An empty range runs no iterations. A range whose start is past its end (3..1, 5..>4) is empty, and a..a is too. A closed range ending at its type’s largest value (250..>top with a byte top of 255) stops there without overflowing.

• A range is a value, a Range<T>. It has contains(x) and the is_empty property, and it is an Iterator<T>, so it has the adapters (map, filter, enumerate, zip) and to_array(). Looping over one allocates nothing; the optimizer turns it into a plain counting loop.

The iterator protocol

The for loop is not tied to Array and String. It works with any type that has the right methods, described by two traits in the runtime (runtime/iterator.pep, documented in the Iterators reference):

export trait Iterator<T> {
    next(): bool;    # advance; true if there is a current element
    current(): T;    # the element next() just moved to
}

export trait Iterable<T> {
    iterate(): Iterator<T>;
}

• An iterator steps through elements. next() moves to the next element and returns true, or returns false when there are no more (and keeps returning false after that). current() returns the element next() moved to.
• An iterable is a collection that hands out a fresh iterator from iterate(). Array<T> returns an ArrayIterator<T>, String returns a StringIterator, and HashMap<K, V> and HashSet<K> return a HashMapIterator<K, V> and a HashSetIterator<K>.

for (var x in source) { body } behaves exactly like this:

{
    var it = source.iterate();   # or `var it = source;` when source is itself an iterator
    while (it.next()) {
        var x = it.current();
        { body }
    }
}

The loop chooses by the methods the source’s type has, like a C++ range-based for: it uses iterate() if the type has one, and otherwise uses the source itself as the iterator if it has both next() and current(). A type with neither is a compile error:

main.pep:4:19: error: type 'Foo' is not iterable: implement Iterable<T> (iterate()) or Iterator<T> (next() and current())
    4 |     for (var x in f) {
      |                   ^

HashMap<K, V> yields each entry as a tuple (K, V), so for (var (name, age) in ages) names both parts; HashSet<K> yields its members. Both visit entries in no particular order. Changing a value (ages[name] = … for a key already present) is fine while looping, but adding or removing an entry stops the program at the iterator’s next step.

Adapters

Iterator<T> has default methods that wrap an iterator in another one. Each works lazily, one element at a time as the loop asks for it:

• map(transform) yields transform(x) for each element x; its element type is whatever transform returns.
• filter(keep) yields only the elements for which keep(x) is true.
• enumerate() yields (index, x) tuples, counting from 0 in ulong; enumerate<int>() counts in int instead.
• zip(other) yields (x, y) pairs, one element from each iterator in step, and stops when either runs out.

They return iterators, so they chain, and a for loop can use the result directly; destructure a tuple to name its parts. to_array() runs an iterator to the end and collects what is left into a new Array:

struct Person {
    String name;
    int age;
    construct(this.name = "", this.age = 0) {}
}

main(): int {
    var people = Array<Person>();
    people.append(Person("Ada", 36));
    people.append(Person("Bo", 12));
    people.append(Person("Cyd", 40));

    # filter keeps the adults, map turns each one into a name.
    var names = Array<String>();
    for (var name in people.iterate().filter((p) => p.age >= 18).map((p) => p.name)) {
        names.append(name);
    }
    assert(names.count == 2, "two adults");
    assert(names[0] == "Ada", "Ada first");
    assert(names[1] == "Cyd", "then Cyd");

    # Adapters work on any Iterator, including a String's.
    var kept = 0;
    for (var c in "hello".iterate().filter((c) => c != "l")) {
        kept += 1;
    }
    assert(kept == 3, "h, e, o");

    # enumerate pairs each element with its position, and zip pairs two
    # iterators in step; destructure the tuple to name both parts.
    var ranked = "";
    for (var (i, person) in people.iterate().enumerate()) {
        ranked += $"{i}:{person.name} ";
    }
    assert(ranked == "0:Ada 1:Bo 2:Cyd ", "numbered from 0");
    var seats = ["window", "aisle"];
    var seated = 0;
    for (var (person, seat) in people.iterate().zip(seats.iterate())) {
        seated += 1;   # Cyd gets no seat: zip stops at the shorter
    }
    assert(seated == 2, "two pairs");

    # to_array collects what an iterator yields.
    var ages = people.iterate().map((p) => p.age).to_array();
    assert(ages.count == 3 && ages[2] == 40, "every age");
    return 0;
}

Every type that declares Iterator<T> gets them: ArrayIterator<T> (from Array.iterate()), StringIterator, ranges, and your own iterators once you write extend YourType with Iterator<T>;. The adapter holds its own copy of the iterator it wraps (the runtime’s iterators are value structs, boxed when they become an Iterator<T>), so a chain built from a temporary stays alive while the loop runs, and it.map(f) and it.to_array() leave it where it was. They are generic methods (see Generics), so they are not callable through an Iterator<T> trait value.

Reading files and directories

Input that can fail partway, such as a directory listing or a file read line by line, yields a Result per element: an IoResult<T> from the io module. Handle each error where it happens; there is nothing to check after the loop.

import [File, Directory, Path] from io;

main(): int {
    var dir = Directory.temp().join("pepper-iteration-streams-example");
    Directory.remove_all(dir);
    assert(Directory.create_all(dir).is_ok(), "created the folder");
    assert(File.write_text(dir.join("notes.txt"), "first\nsecond\r\nthird").is_ok(), "wrote notes");
    assert(File.write_text(dir.join("todo.txt"), "").is_ok(), "wrote todo");

    # A Directory yields its entries one at a time, each an IoResult<DirEntry>.
    var names = 0;
    for (var entry in Directory.open(dir).value()) {
        if (entry.is_err()) {
            print(entry.error().message);
            break;
        }
        assert(entry.value().is_file, "both entries are files");
        names += 1;
    }
    assert(names == 2, "two entries");

    # A File's lines() yields each line, without its line ending.
    var file = File.open(dir.join("notes.txt")).value();
    var lines = Array<String>();
    for (var line in file.lines()) {
        lines.append(line.value());
    }
    assert(lines.count == 3 && lines[1] == "second", "three lines, \\r\\n removed");

    # Adapters work on streams too: number the lines.
    var again = File.open(dir.join("notes.txt")).value();
    var last = "";
    for (var (i, line) in again.lines().enumerate()) {
        last = $"{i}: {line.value()}";
    }
    assert(last == "2: third", "the last line, numbered");

    assert(Directory.remove_all(dir).is_ok(), "cleaned up");
    return 0;
}

• A Directory is iterable. for (var entry in dir) reads the listing one entry at a time (Directory.iterate() returns a DirectoryIterator), without building an array the way dir.entries() does. Each element is an IoResult<DirEntry>. A directory that cannot be read yields one error and then ends.
• lines() yields each line of an open File, or of any other io.Reader such as a socket, from what it reads next, as an IoResult<String> without the \n or \r\n. The last line counts even without a line ending. A read error, or a line that is not valid UTF-8, is yielded as an error and ends the lines.
• chunks(size) yields the rest of a Reader in arrays of at most size bytes, one read each, as IoResult<u8[]>s.
• An error ends the sequence: after an Err element, next() returns false.
• listener.incoming() accepts connections on a TcpListener, yielding each one as an IoResult<TcpStream>. It is the exception to the rule above: a failed accept is yielded and the loop goes on, since the next connection may succeed. It ends only once the listener is closed, so a server loop breaks or returns when it is done.
• Leaving early cleans up. The listing is closed when the loop ends, including by break or return, because the iterator is released then.

Writing your own iterator

To make your own type work in a for loop, give it next() and current() (an iterator), or give it an iterate() method that returns such a type (an iterable):