Introduction

Plenty is a general-purpose programming language. Plenty is statically-typed and compiles ahead of time to native code. Plenty is most heavily influenced by Python, Rust, and Zig.

Why the name “Plenty”?

I wanted a language without trade-offs: simple syntax that is easy to learn, easy to read and write, but also produces fast code, and is safe and reliable, and with a huge standard library to reduce the need for third-party dependencies. And more! I wanted everything that is good about each programming language. The programmer’s version of “a land of plenty” where you can have it all.

Goals

There are multiple goals for Plenty:

• Convenience and safety: Could we merge the best parts of Python and Rust? This is Plenty.
• Explicit ownership: Ownership and borrowing are explicit, with compile-time checks.
• Sum types: Enums are tagged unions and are used to represent sum types. Very similar to Rust.
• Fast compilation: The compiler is designed to compile quickly, even for large codebases.
• Efficient: An optimizing compiler generating machine code (Cranelift). SIMD support. Parallel tools like Rust’s rayon. Exploit hardware features.
• No garbage collector: Deterministic memory usage patterns.
• No dynamic behaviour: Figure out as much as possible at compile time.
• Fallible memory allocation: All operations that allocate memory can report allocation failure without exceptions.
• Simple FFI interop with C: In both directions. There is an interface file format to specify lifetime information for resources from a C library so that Plenty can manage them safely.
• No inheritance: Classes and enums have fixed declarations rather than dynamic attributes or inheritance.
• Generics and Protocols: A native version of Python’s typing.Protocol. Something like Go interfaces, or a simpler version of Rust’s traits.
• Batteries included: A standard library so stuffed to the gills with awesome that many programs can be written using the standard library alone.
• Simple package management: No central package repo. Use golang-inspired git links for dependencies.

The primary influences on Plenty are:

• Python, for syntax
• Rust, for ownership and borrowing, and getting the details right
• Zig, for emphasizing fallible memory allocation

Getting Started

This book provides:

• Learn Plenty teaches the language with runnable examples. Start here.
• Reference defines language rules, built-in facilities, and compiler/runtime architecture in separate areas.

Tested examples

cargo test --test integration test_tutorial:: compiles and runs every example in Learn Plenty. It compares the output with the expected output on the page. An example that must fail must give the expected diagnostic.

Build this book

mdbook serve book --open

Learning Plenty

Plenty combines Python-shaped syntax with explicit types, ownership, and native compilation. The examples are self-contained and teach implemented features.

Start with Setting up to install a release and put plenty on your PATH. Then follow the ten core parts to build a small command-line tool:

1. Your first program: compile, run, and check.
2. Values, functions, and control flow: name values, choose types, define functions, and repeat work.
3. Absence and failure: handle missing values and errors with Option, Result, match, and ?.
4. Collections, ownership, and borrowing: keep groups of values, transfer ownership, copy, and borrow.
5. Iteration and transformation: visit values, transform them, and produce them incrementally.
6. Defining your own data: write records, methods, constructors, and enums.
7. Heterogeneous collections: combine different kinds of values with enums and anonymous sums.
8. Special-purpose data structures: choose columnar storage for calculations over selected fields.
9. Organizing a program: split a program into modules and choose its public interfaces.
10. Useful programs and resources: use command-line arguments, text, standard streams, and files in a complete application.

Then choose an optional path when your program needs it:

• Generic code and protocols reuse algorithms across different types.
• Functions as values introduce callbacks and captured state, then stored and consuming callbacks.
• Concurrent and parallel programs coordinate workers, communicate, stop work, and bound waiting.
• Working with C libraries call foreign code, own foreign resources, and export library interfaces. This path does not require concurrency.

The Reference describes detailed contracts and limits. Use the supplementary examples to look up collection methods, text operations, and advanced file usage.

Setting up

Install Plenty once, then use the plenty command throughout this tutorial. You do not need Rust, Cargo, or a copy of the compiler’s source repository.

Building from a source checkout instead? The local build recipes provide just build for the release compiler, both optional engines, and their licenses/metadata. Put that checkout’s target/release/ on PATH. These builds require Rust and native build tools and target your local system, unlike the portable binary download described here.

Check your system

Binary releases support x86-64 and ARM64 Linux with glibc 2.28 or later. This page uses the x86-64 archive names; on an ARM64 machine (uname -m prints aarch64), replace x86_64-unknown-linux-gnu with aarch64-unknown-linux-gnu in every command. Musl-based distributions such as Alpine are unsupported. Releases also include experimental macOS and Windows downloads, whose READMEs replace the Linux steps below. See the installation requirements for supported systems and troubleshooting.

Plenty also needs a C linker and development libraries to run or compile a program. Install the packages for your distribution before continuing:

# Debian or Ubuntu
sudo apt-get update && sudo apt-get install gcc libc6-dev

# Fedora, RHEL, AlmaLinux, or Rocky Linux
sudo dnf install gcc tar gzip

# Arch Linux
sudo pacman -Syu --needed gcc

Download and extract Plenty

Open Plenty’s GitHub Releases and choose a published release. Under Assets, download both:

• plenty-VERSION-x86_64-unknown-linux-gnu.tar.gz
• plenty-VERSION-x86_64-unknown-linux-gnu.tar.gz.sha256

Choose the binary archive, rather than GitHub’s Source code (zip) download. Plenty currently ships as a compressed tar archive, so extract it with tar. In every command below, replace VERSION with the version you downloaded; keep the same version in the archive name and directory name.

Assuming both files are in ~/Downloads, verify and extract them:

cd "$HOME/Downloads"
sha256sum -c plenty-VERSION-x86_64-unknown-linux-gnu.tar.gz.sha256
mkdir -p "$HOME/.local/opt"
tar -xzf plenty-VERSION-x86_64-unknown-linux-gnu.tar.gz -C "$HOME/.local/opt"

Check that the checksum command reports OK before extracting. The resulting directory contains bin/plenty and bin/plentyc. Keep the extracted directory; the shell setup below points to its bin directory.

Add Plenty to your PATH

PATH is the list of directories your shell searches for commands. Choose the instructions for your shell. These paths are quoted so they also work when your home directory contains spaces.

Bash

Add this line to ~/.bashrc, replacing VERSION:

export PATH="$HOME/.local/opt/plenty-VERSION-x86_64-unknown-linux-gnu/bin:$PATH"

Run that same line in your current terminal to use Plenty immediately. New interactive terminals read .bashrc. If you use a Bash login shell, ensure your login startup file also sources .bashrc; see Bash startup files.

Zsh

Add this line to ~/.zshrc, replacing VERSION:

export PATH="$HOME/.local/opt/plenty-VERSION-x86_64-unknown-linux-gnu/bin:$PATH"

Run that same line in your current terminal. New interactive Zsh terminals read .zshrc. If you configured ZDOTDIR, use $ZDOTDIR/.zshrc instead; see Zsh startup files.

Fish

Run this command once in Fish, replacing VERSION:

fish_add_path --universal --prepend --move "$HOME/.local/opt/plenty-VERSION-x86_64-unknown-linux-gnu/bin"

fish_add_path updates the current shell and remembers the directory for future Fish sessions. The directory must already exist, so extract the archive first. There is no need to edit config.fish for this universal setting.

Check the installation

In any of these shells, run:

command -v plenty
plenty --version
cc --version

The first command should name plenty inside your extracted archive; the second prints the installed version and target. If plenty is not found, check that the PATH entry matches the actual extracted directory. If another installation appears, put the new directory first on PATH. If cc is missing, install the linking packages above.

You are ready for Your first program. Save your programs in any working directory you choose. When installing a newer release, update the PATH entry to its new directory; see upgrading and switching versions.

Your first program

After setting up Plenty, run a complete program, then check and compile changes.

1. Run a program
2. Change and check it

Run a program

Save this as hello.plenty:

def main() -> Result[(), IoError | OverflowError[i64]]:
    print("Hello, Plenty!")?
    print(6 * 7)?
    Ok(())

Hello, Plenty!
42

In the directory where you saved the file, run:

plenty hello.plenty

A run compiles your file to a native executable and then runs it. If your shell cannot find plenty, follow Setting up first.

Plenty caches compiled code automatically. On supported Linux toolchains, unchanged runs also reuse the linked executable, so they do not link again. See the compile cache for invalidation and toolchain limits. The program still runs each time.

On Unix, you can put #!/usr/bin/env plenty before the first line, then run:

chmod +x hello.plenty
./hello.plenty

This uses the same automatic caches as plenty hello.plenty.

Execution begins at main. Indentation groups its statements; use four spaces. print prints one value followed by a newline. Put executable statements inside functions.

Printing can fail. The ? after each call continues when printing succeeds and returns an output error when it fails. Integer multiplication can overflow too, so the signature includes OverflowError[i64]. Its operands fit here, but the function still declares the arithmetic error contract. Ok(()) reports that the program finished successfully. Keep this pattern for printing; Absence and failure explains how to handle errors.

Each example is a complete program. Run it in a new file, along with any labelled companion modules shown on its page.

Change and check a program

Change the greeting or calculation, then run the file again. Each run starts a fresh process.

Use plenty --check hello.plenty to check syntax and types without running the program. A check needs no linker. A run or native compilation needs a cc-compatible linker driver installed.

To keep an executable:

plenty --compile hello.plenty -o /tmp/hello-plenty
/tmp/hello-plenty

The executable can run without Plenty installed, on a compatible host system. To ship an application directory instead:

plenty --compile hello.plenty --dist dist/hello
./dist/hello/hello

Choose a destination that does not already exist. This greeting needs only the executable. Applications reaching optional native engines also get the exact libraries and packaged notices they need, without development-machine lookup paths. This is not a static or cross-platform build; see application distributions for engine setup and platform requirements.

Parse and type errors prevent execution. A runtime error can happen after earlier effects, such as printing. Use --check when you want feedback without those effects, or print(value)? inside main to inspect a value.

Values, functions, and control flow

Name values, write typed functions, and choose or repeat work:

1. Name values
2. Choose numeric types
3. Calculate with numbers Floating-point calculations extend these rules.
4. Write text
5. Build text with f-strings
6. Define functions
7. Complete work without returning data
8. Choose between branches
9. Return early
10. Keep names in scope
11. Repeat with a range
12. Repeat while a condition holds
13. Give types descriptive names

Next: Absence and failure.

Name values

Use = to create a binding. Plenty infers the type of a local value, so you usually do not need an annotation:

def main() -> Result[(), IoError | OverflowError[i64]]:
    # Comments begin with a hash.
    price = 20
    quantity = 3
    total = price * quantity
    print(total)?
    Ok(())

60

To see inferred types without writing annotations, enable your editor’s inlay hints. For example, the Plenty language server can show : i64 after price, quantity, and total. These labels are only displayed in the editor; they are not added to your source file. Hover also shows a binding’s type.

Bindings are immutable by default:

def main() -> ():
    score = 10
    score = 11

`score` is immutable; declare it with `mut`

Use mut when a value needs to change. Write it once, at the declaration:

def main() -> Result[(), IoError | OverflowError[i64]]:
    mut score: i64 = 10
    score += 5
    print(score)?
    Ok(())

15

A mutable binding keeps its original type. score: i64 states the type explicitly; without the annotation, this integer literal also infers i64.

score += 5 adds to the current score. Numeric values also support -=, *=, /=, //=, and %=. Use //= for integer division and /= for float division; %= requires integers. These updates require an existing writable destination and keep its type. Strings and collections use their explicit operations.

Choose the width of an integer

The built-in integer names specify their sizes:

For example, i8 can hold -128 through 127, and u8 can hold 0 through 255.

A whole-number literal without a suffix, such as 42, defaults to i64 when its type is unconstrained. An annotation, parameter, return type, or arithmetic operand can supply the type instead. Append a built-in integer type to choose another width:

def main() -> Result[(), IoError]:
    small: u8 = 200u8
    offset: i32 = -12i32
    large: u64 = 1_000_000u64
    print(small)?
    print(offset)?
    print(large)?
    Ok(())

200
-12
1000000

An annotation guides an unsuffixed literal, so small: u8 = 200 works. It does not convert an already typed initializer: convert the value explicitly for that.

Underscores separate digits for readability, as in 1_000_000u64 above. Integers may also be written in hexadecimal, octal, or binary, with the same suffixes and range checks:

def main() -> Result[(), IoError]:
    mask: u8 = 0b1111_0000
    print(0xFF, 0o755, mask, 0x1F600u32)?
    Ok(())

255 493 240 128512

Calculate with numbers

Arithmetic requires matching types. Integer failures are recoverable by default: list their error types in the function’s Result return, and use Ok(...) for success. Operators themselves still produce ordinary numbers.

def main() -> Result[(), IoError]:
    small = 7u8
    print(small + 1i64)?
    Ok(())

cannot combine u8 with i64; convert with `i64(small)`

Choose a matching literal or explicitly convert a value:

def main() -> Result[(), IoError | OverflowError[u8] | OverflowError[i64]]:
    small = 7u8
    print(small + 1u8)?
    print(i64(small) + 1)?
    Ok(())

8
8

i64(small) is safe because every u8 value fits in an i64. When the target cannot hold every value of the source, use try_from. It checks the range and returns a Result: Ok with the converted value, or Err(RangeError.OutOfRange) when the value does not fit. RangeError has only this one variant; parsing text uses the separate ParseError type.

def main() -> Result[(), RangeError | IoError | OverflowError[u8]]:
    wide = 200
    small = u8.try_from(wide)?
    print(small + 1u8)?
    Ok(())

201

? takes the converted value or returns its error to the caller. The RangeError | IoError error type preserves either a conversion error or a printing error. Absence and failure explains propagation and how to recover from an error.

A cast to an integer type requires the value to fit. A literal that does not fit is rejected when the program is compiled:

def main() -> ():
    small = u8(300)

300 is out of range for u8; u8.wrapping_from keeps the low bits

A value known only when the program runs is checked then. With wide = 300, u8(wide) stops the program with error: integer cast out of range. Casts retain this trapping behavior; arithmetic errors use typed returns. The same applies to a negative value cast to an unsigned type, such as u64(-1), and to an unsigned value above the signed maximum, such as i8(200u8). Cast when the value is known to fit, and use try_from when it might not.

When discarding the high bits is the intent, say so with wrapping_from, which never fails:

def main() -> Result[(), IoError]:
    wide = 300
    negative = -1
    print(u8.wrapping_from(wide))?
    print(u64.wrapping_from(negative))?
    print(i8.wrapping_from(200u8))?
    Ok(())

44
18446744073709551615
-56

Integer overflow returns OverflowError[T], where T is the operand type. An unsigned type has no negative values, so unary minus requires a signed integer or a float:

def main() -> Result[(), IoError]:
    small = 7u8
    print(-small)?
    Ok(())

unary minus is not defined for unsigned type u8

Convert first: -i16(small) is -7.

The same rule applies to literals, including zero:

def main() -> ():
    zero: u8 = -0

unary minus is not defined for unsigned type u8

+, -, and * have their usual arithmetic precedence. // divides integers and rounds down, including for negative values:

def main() -> Result[(), IoError | OverflowError[i64] | ZeroDivisionError]:
    print(1 + 2 * 3)?
    print((1 + 2) * 3)?
    print(-7 // 3)?
    Ok(())

7
9
-3

Integer division by zero returns ZeroDivisionError. Signed division also requires OverflowError[T] for T.MIN // -1. The contract follows the operators and operand types, even with a known nonzero divisor such as 3. Use / for floating-point division.

Integers also support bitwise operations and shifts. A shift count must be nonnegative and smaller than the integer width. Signed right shifts preserve the sign; unsigned right shifts fill with zero. Left shifts discard high bits.

def main() -> Result[(), IoError]:
    bits = 5u8
    print(bits & 3)?
    print(bits | 2)?
    print(bits ^ 3)?
    print(~bits)?
    print(bits << 1)?
    print(bits >> 1)?
    print(255u8.wrapping_add(1))?
    print(0u8.wrapping_sub(1))?
    print(128u8.wrapping_mul(2))?
    Ok(())

1
7
6
250
10
2
0
255
0

Use wrapping_add, wrapping_sub, or wrapping_mul when a calculation deliberately wraps at the integer width, as in a hash or a random-number generator. Ordinary arithmetic returns a typed overflow error. Parenthesize mixed bitwise expressions when that makes the intended grouping easier to read.

rotate_left and rotate_right move bits around the ends of an integer instead of discarding them. The count has the integer’s own type. No count loses bits, so rotation never traps: a count of the full width leaves the value unchanged.

def main() -> Result[(), IoError]:
    bits = 129u8
    print(bits.rotate_left(1))?
    print(bits.rotate_right(1))?
    print(bits.rotate_left(8))?
    print(bits << 1)?
    Ok(())

3
192
129
2

pow raises a number to a power, and each integer type names its limits as MIN and MAX. As with the operators, the number and its exponent must have one type, and the result has that type:

def main() -> Result[(), IoError | OverflowError[i64] | OverflowError[u8]]:
    change = -7
    small = 200u8
    print(change.pow(2))?
    print((2).pow(10))?
    print(u8.MAX - small)?
    print(i64.MIN)?
    Ok(())

49
1024
55
-9223372036854775808

There is no ** operator. An integer literal receiver needs parentheses, as in (2).pow(10).

A result that does not fit returns the same typed overflow error as the operators. An integer power with a negative exponent still stops with negative integer exponent; convert to a float for that.

Recover from overflow

Declare the errors a calculation can produce and propagate them to its caller. An arithmetic failure returns Err immediately; otherwise explicitly return Ok with the successful value.

def average(total: u8, count: u8) -> Result[u8, OverflowError[u8] | ZeroDivisionError]:
    rounded = total + count // 2
    Ok(rounded // count)

def main() -> Result[(), OverflowError[u8] | ZeroDivisionError | IoError]:
    print(average(200, 4)?)?
    print(average(250, 20).is_err())?
    print(average(250, 0).is_err())?
    Ok(())

50
True
True

The error type lists what the function’s operators can produce: OverflowError[u8] for + on u8, and ZeroDivisionError for //. Unsigned // cannot overflow, so it adds only ZeroDivisionError. ? passes either error to the caller, as with try_from. An OverflowError holds the wrapped result in its wrapped field: 250 + 10 on a u8 wraps to 4. Keep several error types shows how to handle each error instead of passing it on.

For local recovery, use checked:. Its final expression becomes the successful value of the block’s Result; no explicit Ok is needed there:

def increment_or_zero(value: i64) -> i64:
    result = checked:
        value + 1
    match result:
        case Ok(incremented):
            incremented
        case Err(_):
            0

def main() -> Result[(), IoError]:
    print(increment_or_zero(4), increment_or_zero(i64.MAX))?
    Ok(())

5 0

Every named function and closure keeps its own declared error contract, including when defined inside checked:. Calls returning Result still need explicit handling.

Use unchecked: only where you can show the arithmetic cannot fail. It yields an ordinary value, not a Result. A failure inside it terminates the process by default, but --unchecked assume builds omit that check, so do not use the suite to reject bad input. In assume builds, list, slice-view and Bytes indexing inside the suite also requires nonnegative, in-range indices; normal negative indexing is unavailable there. Keep these suites small and justify every indexed access as well as the arithmetic. Write unchecked trap: when termination is the intent. See arithmetic modes. Integer std.math helpers return ordinary overflow results; their float variants remain infallible. Remaining std implementations and parallel reductions still need the coordinated adoption described in B14. Calls never inherit a caller’s mode.

Validate a divisor once

When a divisor comes from input, validate it with NonZero.try_from and pass the resulting value to repeated divisions. A plain integer accepts that divisor directly; the compiler omits its zero check.

def per_group(total: i64, groups: NonZero[i64]) -> Result[i64, OverflowError[i64]]:
    Ok(total // groups)

def main() -> Result[(), IoError | RangeError | OverflowError[i64]]:
    count = 3
    groups = NonZero.try_from(count)?
    print(per_group(14, groups)?, 14 % groups)?
    Ok(())

4 2

The quotient and remainder are ordinary integers and can be zero. Signed i64.MIN // -1 can still overflow, so the function’s error type includes OverflowError[i64]. A locally handled checked block can instead keep this error out of the function signature. See nonzero integers for construction and arithmetic rules.

Work with floating-point numbers

A decimal or exponent literal defaults to f64. Use an f32 suffix when you want 32-bit arithmetic. Both operands must have the same type; casts are explicit:

def main() -> Result[(), IoError]:
    distance: f64 = 7.5
    time: f64 = 2.0
    print(distance / time)?
    print(1.25f32 + 0.5f32)?
    print(2.5e-2)?
    print(f64(3) / 2.0)?
    print(i32(-2.75))?
    Ok(())

3.75
1.75
0.025
1.5
-2

Float-to-integer casts discard the fractional part toward zero. The result must fit the integer type: u8(255.9) is 255, while a 300.7, an infinity, or NaN held in a variable stops the program with error: integer cast out of range. Integer-to-float casts and f64 to f32 casts may round. There is no implicit widening or narrowing:

def main() -> ():
    small: f32 = 1.5f64

expected f32, got f64

Write 1.5f32 or f32(1.5) instead. Floats follow IEEE arithmetic: division by zero can produce infinity or NaN, and arithmetic overflow can produce infinity. NaN is unequal to everything, including itself; ordered comparisons with it are false.

def main() -> Result[(), IoError]:
    zero = 0.0
    print(1.0 / zero)?
    unknown = zero / zero
    print(unknown == unknown)?
    print(unknown != unknown)?
    Ok(())

inf
False
True

When a zero divisor is an error rather than a source of infinity, x.div_checked(y) returns an Err holding a ZeroDivisionError for a zero y and Ok(x / y) otherwise; see recover from overflow.

Floats support +, -, *, /, unary signs, and comparisons.

// and % currently require integers. Floats cannot be dictionary keys or set elements. Float literals that overflow their declared width are compile errors.

Math functions are methods on a float, and each float type provides the constants PI and E:

def main() -> Result[(), IoError]:
    radius = 2.0
    print(f64.PI * radius.pow(2.0))?
    print((9.0).sqrt())?
    print(f64.E.log())?
    print((0.0).cos())?
    print((2.5).floor())?
    print((2.5).ceil())?
    print((7.5).fmod(2.0))?
    Ok(())

12.566370614359172
3.0
1.0
1.0
2.0
3.0
1.5

log is the natural logarithm, sin and cos take radians, and exp raises e to a power. floor and ceil return floats; cast the result for an integer, as in i64(x.floor()). fmod is the float remainder. These methods never stop the program: (-1.0).sqrt() is NaN. An integer needs a cast first, as in f64(n).sqrt().

Write text

The type str represents text. Single and double quotes both make strings; triple quotes allow physical newlines. Escapes include \n, \r, \t, escaped quotes, \\, \0 for an embedded NUL, and \u{H...} for any character by its hexadecimal code point, such as "e\u{301}" for an e followed by a combining accent. See escapes.

def main() -> Result[(), IoError]:
    name = 'Plenty'
    print(name)?
    print(contains(name, "lent"))?
    print(len("hé"))?
    print("hé".byte_len())?
    Ok(())

Plenty
True
2
3

print displays text without quotes. contains(text, part) tests for a substring. len counts Unicode scalar values, so the accented character above counts once; this is not a count of visible grapheme clusters. byte_len() gives the size of the UTF-8 encoding instead, which is what a file, a buffer, or a size limit measures.

Strings are immutable. A mut binding allows replacing a string, rather than editing its bytes.

Compare strings in Unicode scalar order, inspect ASCII characters, or convert a single character to its code point:

def main() -> Result[(), AllocError | IoError | ParseError]:
    print("apple" < "pear")?
    print("abc".isalpha())?
    print("123".isdigit())?
    print(ord("é")?)?
    print(chr(233)?)?
    print("Hello".lower()?)?
    print("Straße".upper()?)?
    print("  one\t two\n".split()?)?
    Ok(())

True
True
True
233
é
hello
STRASSE
["one", "two"]

ord requires exactly one Unicode scalar; chr takes a u32 code point and rejects surrogates and values outside Unicode. Both return Result and allocate nothing. Case conversion and splitting return fallible, independently owned results. The ASCII predicates return false for empty or non-ASCII text.

Build text with f-strings

Put an f before a string to fill in values. Each {field} is replaced by its value. An f-string builds a new str, which can fail to allocate, so it returns Result[str, AllocError] like a list literal does: write ? after it.

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    name = "Ada"
    year = 1843
    scores = [90, 85]?
    print(f"{name} published in {year}."?)?
    print(f"first score: {scores[0]}, count: {len(scores)}"?)?
    print(f"all scores: {scores}, {{braces}}"?)?
    print(f"total: {scores[0] + scores[1]}, passed: {scores[1] > 80}"?)?
    print(f"{name} was {'young' if 1843 - 1815 < 30 else 'older'}"?)?
    Ok(())

Ada published in 1843.
first score: 90, count: 2
all scores: [90, 85], {braces}
total: 175, passed: True
Ada was young

A field shows its value as print would. Double the braces for literal ones. A field can be any expression. A ? inside a field returns from your function, as ? does anywhere else; the ? after the f-string handles only failure to build the text.

After a colon, a format spec chooses width, alignment, fill, sign, digit grouping, precision, and a type, as in Python:

def main() -> Result[(), AllocError | IoError]:
    item = "tea"
    price = 3.14159
    count = 1234567
    print(f"[{item:<6}] [{item:>6}] [{item:*^7}]"?)?
    print(f"{price:.2f} {price:8.3f} {price:+.1e} {0.25:.0%}"?)?
    print(f"{count:,} {count:_} {255:#x} {255:08b} {-42:05}"?)?
    Ok(())

[tea   ] [   tea] [**tea**]
3.14    3.142 +3.1e+00 25%
1,234,567 1_234_567 0xff 11111111 -0042

A spec can take its width or precision from a nested field, and its fill or alignment from a nested str field. Such a value can be invalid, such as a negative width, so the f-string’s error becomes AllocError | FormatError; FormatError needs no import:

def main() -> Result[(), AllocError | IoError | FormatError]:
    width = 8
    digits = 2
    align = "^"
    print(f"[{3.14159:{width}.{digits}f}] [{'tea':*{align}{width}}]"?)?
    Ok(())

[    3.14] [**tea***]

!r shows the value’s representation, with quotes around text, and = shows the field’s source before its value, which helps when debugging:

def main() -> Result[(), AllocError | IoError]:
    name = "Ada"
    year = 1843
    print(f"{name!r} {name=} {year=}"?)?
    Ok(())

"Ada" name="Ada" year=1843

!a is like !r but spells every non-ASCII character as an escape, so f"{'café'!a}" gives "caf\u{e9}", which you can paste back into source as the string literal "caf\u{e9}".

The compiler checks every spec against the field’s type. A precision does not apply to an integer:

def main() -> Result[(), AllocError | IoError]:
    count = 3
    print(f"{count:.2f}"?)?
    Ok(())

format spec `.2f` does not apply to i64: integers take no precision; convert with f64(...) to format a float

The reference lists every option and conversion.

An f-string suits a fixed number of pieces of any type. A field whose type has its own formatting methods also adds FormatError, since that method can fail. Combine two strings with a.concat(b)? and any number of strings from a list, set, or generator with separator.join(pieces)?.

Define functions with clear interfaces

Every parameter and return type must be declared:

def double(value: i64) -> Result[i64, OverflowError[i64]]:
    """Return twice the supplied value."""
    Ok(value * 2)

def main() -> Result[(), IoError | OverflowError[i64]]:
    print(double(21)?)?
    Ok(())

42

value: i64 declares the parameter type. The return type Result[i64, OverflowError[i64]] describes either a doubled integer or overflow. Ok(value * 2) supplies success; the multiplication returns an error from double if it cannot fit. You can also write return Ok(value * 2). The caller uses double(21)? to obtain the successful integer or pass the error onward. Parameters are immutable. See recoverable errors for handling either outcome explicitly.

Indent statements in the same block equally, using spaces. Tabs are rejected.

A string at the beginning of a function is its documentation. Triple quotes allow a docstring to span lines. When a function should immediately return a string, write return "text" so it cannot be mistaken for documentation.

Functions are known throughout the file, so one function may call a function declared later. Name arguments when that makes their meaning clearer:

def rectangle(width: i64, height: i64 = 2) -> Result[i64, OverflowError[i64]]:
    Ok(width * height)

def main() -> Result[(), IoError | OverflowError[i64]]:
    print(rectangle(height=3, width=4)?)?
    print(rectangle(4)?)?
    Ok(())

12
8

Positional arguments come first. After the first named argument, all remaining arguments must be named; their order need not match the declaration. Supplied expressions run in the order you write them. Required parameters come before parameters with defaults.

Defaults run afresh for each omitted argument. Mutable defaults never share storage between calls:

def count(values: &mut list[i64] = []?) -> Result[i64, AllocError]:
    values.append(7)?
    Ok(len(values))

def main() -> Result[(), AllocError | IoError]:
    print(count()?)?
    print(count()?)?
    mut saved = [1, 2]?
    print(count(values=&mut saved)?)?
    print(len(saved))?
    Ok(())

1
1
3
3

An omitted borrowed argument gets temporary storage that lasts for the call. Pass your own buffer to keep its changes. Defaults run after supplied arguments, in declaration order; they cannot refer to another parameter. Allocation still needs ? and a compatible Result return type. If a default fails, that call returns the error without entering the body. Callable values and builtins keep positional arguments; splat unpacking is not supported.

Complete work without returning data

A function can complete without producing data. Its return type is the unit type, (). This is different from a missing value.

def show_if(enabled: bool, value: i64) -> Result[(), IoError]:
    if not enabled:
        return Ok(())
    print(value)?
    Ok(())

def main() -> Result[(), IoError]:
    show_if(False, 10)?
    show_if(True, 42)?
    Ok(())

42

Result[(), IoError] combines unit success with a possible output error. print(value)? therefore completes without supplying data.

In a function declared -> (), a bare return returns unit. Use pass for an intentionally empty block. Unit parameters and standalone unit bindings are not supported. Use Option for absence; there is no None value.

Make decisions that produce values

A condition must have type bool. Comparisons such as ==, !=, <, <=, >, and >= produce booleans. There is no implicit conversion of zero, an empty string, or another value to False.

An if can supply a function’s result:

def maximum(first: i64, second: i64) -> i64:
    if first > second:
        first
    else:
        second

def main() -> Result[(), IoError]:
    print(maximum(7, 12))?
    Ok(())

12

Both continuing branches need the same type. Use elif for additional cases. For a short choice, use a conditional expression:

def main() -> Result[(), IoError]:
    age = 20
    category = "adult" if age >= 18 else "child"
    print(category)?
    Ok(())

adult

and and or short-circuit: the right side is evaluated only when needed. not negates a boolean. All three require boolean operands:

def main() -> Result[(), IoError | ZeroDivisionError | OverflowError[i64]]:
    divisor = 0
    safe = divisor != 0 and 10 // divisor > 1
    print(safe)?
    print(not safe)?
    Ok(())

False
True

The division is skipped here. Chained comparisons such as 0 < x < 10 are not supported yet; write 0 < x and x < 10.

Return early and continue on the other path

A guard clause handles a special case before the main computation:

def clamp_low(value: i64, minimum: i64) -> i64:
    if value < minimum:
        return minimum
    value

def main() -> Result[(), IoError]:
    print(clamp_low(3, 10))?
    print(clamp_low(12, 10))?
    Ok(())

10
12

return exits the entire function, even when it appears in nested branches. Every return must match the function’s declared result. Code after a guaranteed exit is rejected. Every path that reaches the end must also supply the declared result; handling just one branch is not enough:

def incomplete(flag: bool) -> i64:
    if flag:
        return 42

def main() -> ():
    pass

expected i64, got ()

Keep branch-local names local

Assignments to an existing mutable binding survive a branch. New names declared inside a branch belong to that branch:

def main() -> Result[(), IoError | OverflowError[i64]]:
    mut price = 100
    discounted = True
    if discounted:
        discount = 20
        price = price - discount
    print(price)?
    Ok(())

80

Declare a mutable binding before the branch when subsequent code needs the updated value. For a new selected value, bind an inline conditional when each branch is one expression. A block conditional also supports branch-local work:

def main() -> Result[(), IoError | OverflowError[i64]]:
    discounted = True
    price = if discounted:
        discount = 20
        100 - discount
    else:
        100
    print(price)?
    Ok(())

80

Only price survives the block; discount still belongs to its branch. This keeps price immutable when it is selected once. The block must be the whole right-hand side; see conditional values.

Repeat with a range

A for loop repeats its body for each integer in a range:

def main() -> Result[(), IoError | OverflowError[i64]]:
    mut total = 0
    for n in range(1, 5):
        total = total + n
    print(total)?
    for n in range(5, 0, -2):
        print(n)?
    Ok(())

10
5
3
1

range(stop) starts at zero. range(start, stop) selects the start. The stop is always excluded: range(1, 5) yields 1, 2, 3, and 4. A third argument selects the step. A negative step counts down. A zero step would never reach the stop, so the step has type NonZero[i64]: an integer that cannot be zero. A literal step converts, and range(5, 0, 0) is a compile-time error. Convert a step computed while the program runs with NonZero.try_from, which works like u8.try_from and returns Err(RangeError.OutOfRange) for zero:

def main() -> Result[(), RangeError | IoError]:
    stride = 3
    step = NonZero.try_from(stride)?
    for n in range(0, 10, step):
        print(n)?
    Ok(())

0
3
6
9

Passing stride directly is a compile-time error whose message shows this conversion. step.get() reads the integer back.

The loop evaluates the range once. Each iteration binds n to the next integer. Names declared in the body stay there; updates to an enclosing mut binding persist. A loop completes with unit.

Creating and iterating a range do not allocate a list. Ranges default to i64. Write range[u8](8) to choose another integer type. Start and stop must fit that type, even though stop is excluded. The step stays a signed NonZero[i64], so an unsigned range can count down.

A configured count that must be greater than zero can use Positive[i64]. Construct positive_count = Positive.try_from(count)? once; NonZero.from(positive_count) then uses that positive domain value as a range step without another check. NonNegative[i64] similarly states that a value may be zero but not negative.

Some standard-library parameters also have a documented ceiling. A direct call with a literal above that ceiling is a compile error; computed values still need to satisfy it when the operation runs. A positive domain checks the lower bound, not every operation’s ceiling. See invalid std arguments.

import std.sketch

def main() -> ():
    drop(std.sketch.quantiles(1048577))

above its fixed ceiling of 1048576

Repeat until a condition changes

Use while when a condition determines how long to repeat. The condition must be bool, and it is checked before every iteration, including the first:

def main() -> Result[(), IoError | OverflowError[i64]]:
    mut remaining = 3
    while remaining > 0:
        print(remaining)?
        remaining = remaining - 1
    print("go")?
    Ok(())

3
2
1
go

continue skips the rest of the current iteration. break exits the loop:

def main() -> Result[(), IoError | OverflowError[i64] | ZeroDivisionError]:
    mut n = 0
    while True:
        n = n + 1
        if n % 2 == 0:
            continue
        if n > 5:
            break
        print(n)?
    Ok(())

1
3
5

Update the condition’s inputs before a continue when needed; otherwise a while loop can repeat forever. In a for loop, continue automatically advances to the next element:

def main() -> Result[(), IoError]:
    for n in range(6):
        if n == 1:
            continue
        if n == 4:
            break
        print(n)?
    Ok(())

0
2
3

break and continue affect only the innermost loop. Use return to leave the function. break cannot carry a value, and loop else clauses are not supported.

Even after while True, a function returning data still needs a result after the loop. Statements directly after an unconditional exit are rejected:

def main() -> Result[(), IoError]:
    while True:
        break
        print("unreachable")?
    Ok(())

unreachable statement after a control-flow exit

Give types names of your own

There is no built-in int. If you want that name, choose its meaning explicitly:

type int = i32

def increment(value: int) -> Result[int, OverflowError[int]]:
    Ok(value + int(1))

def main() -> Result[(), IoError | OverflowError[i32]]:
    answer: int = increment(int(41))?
    print(answer)?
    Ok(())

42

type int = i32 makes int another name for i32, including in casts. Aliases do not change unconstrained literal defaults, but an annotation such as answer: int = 41 selects the literal’s width. Aliases are not literal suffixes: write 41i32, not 41int.

Aliases can describe a value’s purpose and refer to other aliases:

type Count = u32
type ItemCount = Count

def add_one(count: ItemCount) -> Result[ItemCount, OverflowError[ItemCount]]:
    Ok(count + 1u32)

def main() -> Result[(), IoError | OverflowError[u32]]:
    print(add_one(41u32)?)?
    Ok(())

42

Count, ItemCount, and u32 are interchangeable. An alias does not create a distinct type or enforce units of measurement.

Declare aliases at module scope; they are visible throughout the file. Alias chains must reach a concrete type: cycles and unknown targets are errors. An alias cannot redefine a built-in name, another alias, or a function name.

Absence and failure

A calculation may have no answer, or it may fail with an explanation. Make those possibilities part of its type, and let the caller choose what to do.

1. Represent absence
2. Represent a recoverable error
3. Supply a default or a typed error
4. Give constructors enough type information
5. Propagate with ?
6. Choose which error details to keep
7. Keep several error types
8. Build text with recoverable allocation

Represent absence

Use Option[T] when a function may have no value to return. It has two variants: Some(value) holds a value of type T; Nothing has no payload.

def positive(n: i64) -> Option[i64]:
    Some(n) if n > 0 else Nothing

def show(n: i64) -> Result[(), IoError]:
    match positive(n):
        case Some(value):
            print(value)?
        case Nothing:
            print("not found")?
    Ok(())

def main() -> Result[(), IoError]:
    show(-1)?
    show(42)?
    Ok(())

not found
42

In case Some(value), the pattern binds the payload to value within that branch. A match must cover both Some and Nothing.

Some and Nothing are built in and need no type prefix. Nothing belongs to one concrete option type rather than acting as a universal null. A present zero, False, or empty string is still Some(value).

When only presence matters, ask with is_some() or is_none() instead of writing a match. Both borrow the option, so it is still usable afterwards.

def main() -> Result[(), IoError]:
    found: Option[str] = Some("key")
    missing: Option[str] = Nothing
    print(found.is_some(), found.is_none())?
    print(missing.is_some(), missing.is_none())?
    print(found.unwrap_or("default"))?
    Ok(())

True False
False True
key

Represent a recoverable error

Use Result[T, E] when failure has an explanation. Ok(value) carries success data of type T; Err(error) carries a cause of type E.

def divide(left: i64, right: i64) -> Result[i64, str]:
    outcome = checked:
        left // right
    match outcome:
        case Ok(value):
            Ok(value)
        case Err(error):
            match error:
                case ZeroDivisionError():
                    Err("division by zero")
                case OverflowError(_):
                    Err("division overflow")

def show(left: i64, right: i64) -> Result[(), IoError]:
    match divide(left, right):
        case Ok(value):
            print(value)?
        case Err(message):
            print(message)?
    Ok(())

def main() -> Result[(), IoError]:
    show(8, 2)?
    show(8, 0)?
    Ok(())

4
division by zero

The local checked: block collects division failures. Matching the error distinguishes division by zero from signed overflow (i64.MIN // -1), then gives each a message. This small example deliberately uses strings as its error API; applications can preserve those distinct typed errors instead.

The caller can recover and continue, as show does here. A result does not implicitly unwrap itself or raise an exception.

When success has no data, use unit as the success type:

def validate(name: str) -> Result[(), str]:
    if len(name) == 0:
        return Err("name is empty")
    Ok(())

def show(name: str) -> Result[(), IoError]:
    match validate(name):
        case Ok(_):
            print("valid")?
        case Err(message):
            print(message)?
    Ok(())

def main() -> Result[(), IoError]:
    show("Plenty")?
    show("")?
    Ok(())

valid
name is empty

The pattern _ ignores a payload you do not need. Ok(()) represents success without data; Nothing represents absence.

is_ok() and is_err() answer whether a result succeeded without looking at its payload. They borrow the result, so it can still be matched or returned.

def divide(left: i64, right: i64) -> Result[i64, str]:
    outcome = checked:
        left // right
    match outcome:
        case Ok(value):
            Ok(value)
        case Err(error):
            match error:
                case ZeroDivisionError():
                    Err("division by zero")
                case OverflowError(_):
                    Err("division overflow")

def main() -> Result[(), IoError]:
    outcome = divide(8, 0)
    print(outcome.is_ok(), outcome.is_err())?
    print(divide(8, 2).is_ok())?
    match outcome:
        case Ok(value):
            print(value)?
        case Err(message):
            print(message)?
    Ok(())

False True
True
division by zero

Supply a default or a typed error

option.unwrap_or(default) returns a present payload or the supplied default. dictionary.get(key, default) does the same for a dictionary lookup, while dictionary.get(key) still returns an Option. Zero, False, and an empty string count as present values.

def main() -> Result[(), AllocError | IoError]:
    numbers = {"answer": 42}?
    print(numbers.get("answer", 0))?
    print(numbers.get("missing", 0))?
    missing: Option[i64] = Nothing
    print(missing.unwrap_or(9))?
    Ok(())

42
0
9

option.ok_or(error) converts absence into a typed Result. Choose an error that explains the missing value, then use ? inside a function returning a compatible Result.

enum Missing:
    Answer

def answer(numbers: &dict[str, i64]) -> Result[i64, Missing]:
    value = numbers.get("answer").ok_or(Missing.Answer)?
    Ok(value)

def main() -> Result[(), AllocError | IoError]:
    numbers = {"answer": 42}?
    match answer(&numbers):
        case Ok(value):
            print(value)?
        case Err(_):
            print("missing answer")?
    Ok(())

42

These helpers add no allocation. They evaluate their arguments eagerly, even when a value is present. The Option methods consume owned payloads and drop an unused default or error. Dictionary lookup supports copyable values; use pop to remove and take an owned value. Use match when the fallback should run only on absence, or choose a lazy helper as described below. Bare Nothing may need an Option annotation or a typed result context to determine its payload type.

Compute a default only when needed

Both Option and Result provide unwrap_or_else: it calls a fallback only for Nothing or Err. A Result fallback receives the error. Option also has ok_or_else for constructing an absence error lazily. These take function values; functions as values and closures explain callbacks in more detail.

A fallback can itself fail. In that case, map_or_else lets both branches return a Result, and ? handles that Result after selection:

def default_port() -> Result[i64, ParseError]:
    i64.parse("8080")

def port(configured: Option[i64]) -> Result[i64, ParseError]:
    Ok(configured.map_or_else(default_port, Ok)?)

def main() -> Result[(), ParseError | IoError]:
    print(port(Some(9000))?, port(Nothing)?)?
    Ok(())

9000 8080

default_port runs only for Nothing. Writing configured.unwrap_or(default_port()?) would run it even for Some(9000). A match is equally suitable when either branch needs several statements. Result.unwrap_or(default) also exists for deliberate recovery with a cheap, already available value. See defaults and recovery for ownership, evaluation order, and the Result callback’s error argument.

Give constructors enough type information

A binding annotation, parameter, or return signature supplies missing type information. Some(42) infers Option[i64] from its payload. Nothing needs an option type from context; Ok and Err each need the other variant’s type:

def main() -> Result[(), IoError]:
    found = Some(42)
    missing: Option[i64] = Nothing
    success: Result[i64, str] = Ok(42)
    failure: Result[i64, str] = Err("not ready")
    print(found == Some(42))?
    print(missing == Option[i64].Nothing)?
    match failure:
        case Ok(value):
            print(value)?
        case Err(message):
            print(message)?
    Ok(())

True
True
not ready

Qualify a constructor, such as Option[i64].Nothing, to supply its type explicitly. Otherwise, insufficient context is an error:

def main() -> ():
    answer = Ok(42)

cannot infer `Ok`

Pass a failure back with ?

Put ? after a Result expression to extract its Ok payload or return its Err immediately. The example’s main preserves allocation and printing errors in AllocError | IoError; checked_name keeps its concrete str error.

def validate(name: str) -> Result[(), str]:
    if len(name) == 0:
        return Err("name is empty")
    Ok(())

def checked_name(name: str) -> Result[str, str]:
    validate(name)?
    Ok(name)

def main() -> Result[(), AllocError | IoError]:
    print(str.repr(checked_name("Plenty"))?)?
    print(str.repr(checked_name(""))?)?
    Ok(())

Result[str, str].Ok("Plenty")
Result[str, str].Err("name is empty")

validate(name)? stops checked_name on failure, skipping Ok(name). Error propagation cleans up local values and temporaries, just as return does.

str.repr formats a result wrapper so either outcome can be printed. This example displays both results for inspection; it does not propagate the validation error out of main. In an application where validation must succeed, use ? on checked_name and include str in the enclosing function’s error type. Ordinary print requires a handled result: print(checked_name("Plenty")?)? prints only the successful name. An expression statement cannot silently discard a result:

def main() -> Result[(), AllocError | IoError]:
    print("hello")
    Ok(())

cannot implicitly discard a Result

Propagate with ?, match to recover, or use drop(result) to intentionally ignore either outcome. The discard check does not cover unused bindings or Option values.

? works with Option too: it extracts Some or immediately returns Nothing.

def positive(n: i64) -> Option[i64]:
    Some(n) if n > 0 else Nothing

def same_positive(n: i64) -> Option[i64]:
    Some(positive(n)?)

def main() -> Result[(), IoError]:
    print(same_positive(42))?
    print(same_positive(-1))?
    Ok(())

Option[i64].Some(42)
Option[i64].Nothing

This example passes the positive value through unchanged to isolate optional propagation. Arithmetic that might overflow needs a Result contract or local checked recovery; Option does not silently convert arithmetic failure to absence.

The enclosing function must return the same family: Result for a Result operand or Option for an Option operand. Success payload types can differ, but a Result error must either match the declared error type or fit within its anonymous sum. For example, Result[(), AllocError | IoError] lets the same function propagate list allocation failures and printing failures with ?. The sum retains the original error and adds no allocation. Use match when you want to recover or translate an error rather than pass it back. ? is not supported inside generators.

def read_number() -> Result[i64, str]:
    Err("not a number")

def checked() -> Result[i64, i64]:
    Ok(read_number()?)

def main() -> ():
    print(checked()).unwrap()

`?` operand error str cannot propagate as i64; the function's error type must include it

Option and Result wrappers do not allocate. Their payloads can: Some([1, 2]?) allocates the list, with no additional allocation for Some.

Choose which error details to keep

Keep a concrete error type when the caller needs the cause. For example, IoError preserves an input/output cause, while str can carry a message.

Pass an error back unchanged when the caller can use it directly. When several operations have different errors, the next lesson shows how to keep them together without losing their details.

Sometimes an API needs to add meaning to a lower-level cause. Here, ConfigError.InvalidCount identifies what was being parsed and retains the original ParseError. A Result’s map_error method changes just the error type, forwarding success unchanged:

enum ConfigError:
    InvalidCount(ParseError)

def read_count(text: &str) -> Result[i64, ConfigError]:
    i64.parse(text).map_error(ConfigError.InvalidCount)

def main() -> Result[(), IoError]:
    match read_count("many"):
        case Ok(count):
            print(count)?
        case Err(ConfigError.InvalidCount(cause)):
            print(cause == ParseError.Invalid)?
    Ok(())

True

ConfigError.InvalidCount written without arguments is a function from ParseError to ConfigError. map_error calls it once with the original error, only when parsing fails. On success, the parsed count passes through unchanged. The conversion policy is explicit, and mapping adds no allocation. read_count returns that result directly because it has no more work to do. Use ? when further work depends on the successful value. See the mapping reference for callback evaluation and ownership details.

When the new error needs more than the cause, such as a second payload or captured context, pass an anonymous function that builds it instead.

The example’s main deliberately handles a failed parse so you can see that the cause survived. In an application that cannot continue, propagate the error instead. Returning an error from main reports it on standard error and exits with status one; printing an error and returning Ok(()) reports success to the program’s caller. The command-line application puts this policy into practice.

Avoid replacing useful causes with builtin Failure: propagation into Result[T, Failure] discards the original error and keeps only Failure.Unspecified. It is a last resort, not a way to combine errors. See the reference for its exact erasure rules.

.unwrap() explicitly extracts a successful payload or terminates on Err or Nothing, without normal scope cleanup:

def main() -> Result[(), IoError]:
    found = Some(42)
    print(found.unwrap())?
    Ok(())

42

Choose .unwrap() only when termination is your intended policy.

Keep several error types

A sum keeps one complete value from a finite set of types. Use | in the error type when a function combines operations with different errors:

type SmallNumberError = ParseError | RangeError

def parse_small(text: str) -> Result[u8, SmallNumberError]:
    number = i64.parse(text)?
    u8.try_from(number)

def main() -> Result[(), IoError]:
    match parse_small("300"):
        case Ok(number):
            print(number)?
        case Err(ParseError.Invalid):
            print("not an integer")?
        case Err(ParseError.OutOfRange):
            print("outside i64 range")?
        case Err(RangeError.OutOfRange):
            print("outside u8 range")?
    Ok(())

outside u8 range

? forwards the original parse error. The direct return widens the conversion result to the declared set. Neither step creates a heap wrapper or loses the payload. Each variant pattern selects its enum member and then its variant, so the errors can be handled directly inside Err. Every variant of every member needs coverage unless you use _.

Use case name: Type: when you need one whole member and its value. The matching reference describes how whole-member patterns and variant patterns combine.

Use a module-level type alias to name a recurring group: SmallNumberError means exactly ParseError | RangeError. It introduces no wrapper or allocation, so ? and exhaustive matching still work on the original members. An alias also composes with other errors: SmallNumberError | IoError is the same sum as ParseError | RangeError | IoError.

Name the errors the function actually propagates. An operation may already wrap a lower-level error in its own enum; that does not require adding the lower-level type separately. A new wrapper enum is useful when an API wants to hide or reorganize its causes, but naming a group needs only an alias.

A checked: block returns one of these sums. Its errors are classes, values with named fields, and a class pattern matches one and binds its fields in order:

def report(total: u8, count: u8) -> Result[(), IoError]:
    result = checked:
        rounded = total + count // 2
        rounded // count
    match result:
        case Ok(mean):
            print(mean)?
        case Err(OverflowError(wrapped)):
            print("overflow, wrapped to", wrapped)?
        case Err(ZeroDivisionError()):
            print("no values")?
    Ok(())

def main() -> Result[(), IoError]:
    report(200, 4)?
    report(250, 20)?
    report(250, 0)?
    Ok(())

50
overflow, wrapped to 4
no values

OverflowError(wrapped) selects the overflow member and binds its one field. ZeroDivisionError() has no fields, so its parentheses are empty. Write _ for a field you do not need. Classes explains fields, and class patterns gives the complete rules.

Sums also work outside errors:

def describe(value: i64 | str) -> Result[(), IoError]:
    match value:
        case number: i64:
            print(number)?
        case text: str:
            print(text)?
    Ok(())

def main() -> Result[(), AllocError | IoError]:
    describe(42)?
    describe("ready")?
    Ok(())

42
ready

The parameter supplies the destination type, so either member can be passed directly. str | i64 means the same type as i64 | str; duplicate members collapse. To inspect without moving an owned payload, match &value; use &mut value to change the active payload through a mutable borrow.

Heterogeneous collections uses sums and enum wrappers to store different kinds of values in lists and dictionaries.

Keep stream errors and progress

Use std.io.typed when a transfer needs the original cause and the number of bytes delivered before failure. Its copy error distinguishes reading from writing. Existing std.io streams can enter this API through bridges:

import std.http.typed

import std.bytes
import std.io
import std.io.typed
from std.http.typed import fixed_body
from std.io.typed import CopyFailure, copy_all

def main() -> Result[(), AllocError | IoError | std.http.typed.FramingError[std.io.StreamError] | std.bytes.BytesError]:
    mut bytes = std.bytes.with_capacity(3)?
    bytes.resize(3, 65u8)?
    mut scratch = std.bytes.with_capacity(2)?
    scratch.resize(2, 0u8)?
    mut body = fixed_body(std.io.typed.reader(std.io.cursor(bytes)), 3)?
    mut output = std.io.typed.writer(std.io.cursor(std.bytes.with_capacity(3)?))
    match copy_all(&mut body, &mut output, &mut scratch):
        case Ok(count):
            print(count)?
        case Err(CopyFailure.Read(count, cause)):
            print("read failed after")?
            print(count)?
            drop(cause)
        case Err(CopyFailure.Write(count, cause)):
            print("write failed after")?
            print(count)?
            drop(cause)
    cursor = std.io.typed.unwrap_writer(output)
    print(cursor.position())?
    Ok(())

3
3

The fixed body assumes an already validated Content-Length; it does not parse HTTP. close_body instead finishes at EOF and requires a connection that will never be reused. The copy helper retries explicit interruption and preserves other transport causes. A write failure can leave unwritten data from the last chunk in scratch; the delivered count alone is not a resume token.

For an HTTP message, use typed head parsing followed by request_body or response_body. They check framing fields and select the body decoder with explicit limits. This in-memory response uses chunked framing. Keep the entire buffered reader when handing it to the body, so prefetched bytes are preserved:

import std.bytes
import std.http
import std.io
import std.io.typed
from std.http.typed import FramingError, read_response, response_body
from std.io.typed import CopyFailure, Partial, ReadFailure, copy_all

type TransportCause = ReadFailure[std.io.StreamError]
type HttpCause = FramingError[TransportCause]

def main() -> Result[(), AllocError | IoError | std.bytes.BytesError | std.io.StreamError | std.http.HttpError | Partial[HttpCause] | HttpCause | CopyFailure[HttpCause, std.io.StreamError]]:
    wire = std.bytes.from_text("HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\n\r\n3\r\nABC\r\n0\r\nX-Tag: sample\r\n\r\n")?
    limits = std.http.Limits(64, 128, 4, 1024)
    mut conn = std.io.typed.buffered_reader(std.io.typed.reader(std.io.cursor(wire)), 128)?
    head = read_response(&mut conn, &limits)?.ok_or(std.http.HttpError.Truncated)?
    # Our GET request allows keep-alive; the response must also allow it.
    mut body = response_body(conn, &head, "GET", True, &limits)?
    mut output = std.io.typed.writer(std.io.cursor(std.bytes.with_capacity(3)?))
    mut scratch = std.bytes.with_capacity(2)?
    scratch.resize(2, 0u8)?
    print(copy_all(&mut body, &mut output, &mut scratch)?)?
    print(body.is_done(), body.trailers()[0].value)?
    # finish checks completion and persistence before handing back ownership.
    recovered = body.finish()?
    drop(recovered)
    Ok(())

3
True sample

Only decoded payload contributes to the copy count. The decoder keeps partial framing state across interruption and stops after the trailers; it does not parse an HTTP head. The parsed-head constructor validates framing; finish checks whether this completed message permits recovering its connection. Dropping an unfinished or failed body drops its connection. Close-delimited, closing, upgraded and successful CONNECT connections cannot be recovered by this API. The reference describes the remaining caller responsibilities and the lower-level chunked_body adapter.

For real requests, use std.http.client, which uses these typed paths and also handles deadlines, connection ownership and reuse. typed_response(response) adapts its response to the typed reader protocol while preserving ClientError; unwrap it before client.finish. response.read_all_progress is convenient when collecting a body and retaining both its original error and the number of bytes appended before failure.

See the typed streams reference for nested error payloads and the framing reference for terminal-state rules.

Build text with recoverable allocation

Concatenating strings can need new storage, so + returns Result[str, AllocError]. Handle that result before using the new text:

def main() -> Result[(), AllocError | IoError]:
    message = ('Hello, ' + "Plenty!")?
    print(message)?
    print(contains(message, "Plenty"))?
    Ok(())

Hello, Plenty!
True

Building the string can fail with AllocError; printing can fail with IoError. The AllocError | IoError sum lets this function propagate either cause while keeping its original type and details.

Use str.from(value) to convert a scalar to text, or str.repr(value) for a representation such as quoted text or a displayed result wrapper. Both return allocation results; see the text conversion lessons.

A helper can combine construction and printing behind one result:

def greet(name: str) -> Result[(), AllocError | IoError]:
    print(("Hello, " + name)?)?
    Ok(())

def greet_if(enabled: bool, name: str) -> Result[(), AllocError | IoError]:
    if not enabled:
        return Ok(())
    greet(name)

def main() -> Result[(), AllocError | IoError]:
    greet_if(False, "Ada")?
    greet_if(True, "Ada")?
    Ok(())

Hello, Ada

String-building operations return allocation results even when a particular short string fits inline. A slice such as name[1:]? is another: it copies part of the text.

Collections, ownership, and borrowing

Store values in collections and choose when to transfer, copy, or borrow them.

1. Build and update a list
2. Transfer or copy ownership
3. Take part of a list or text
4. Borrow a collection
5. Borrow an element
6. Handle allocation failures
7. Associate keys with values Optional lookup handles missing entries explicitly.
8. Keep distinct values in a set
9. Remove values and take ownership
10. Group different types in tuples
11. Sort and reorder a list
12. Clean up owned values
13. Build singly and doubly linked lists

The collection examples provide additional operations.

Build and update a list

A list contains values of one type. Use list[T] in signatures and annotations. An empty list needs an annotation or a typed constructor such as list[i64]().

def main() -> Result[(), AllocError | IoError]:
    mut original: list[i64] = [10, 20]?
    mut changed = copy(original)?
    changed.append(30)?
    changed[0] = 99
    print(original)?
    print(changed)?
    print(changed[-1])?
    print(len(changed))?
    Ok(())

[10, 20]
[99, 20, 30]
30
3

copy(original)? makes an independent list. Updates happen in place and require a mut owner. append grows the list; indexed assignment replaces an existing element. Negative indices count from the end, and an invalid index is a runtime error.

List construction, copying, and growth return allocation results, handled here with ?.

Collections can nest. Update an inner list directly through its indices:

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut rows = [[1, 2]?, [3]?]?
    rows[0][-1] += 7
    print(rows)?
    Ok(())

[[1, 9], [3]]

Nested assignment does not copy or allocate the containing lists. Numeric elements support augmented assignment such as += too. Each target index runs once before the right side, which may read the list but cannot change or resize it during the update. A failed right-side result leaves the element unchanged. Indices can be expressions, including elements of another list:

def main() -> Result[(), AllocError | IoError]:
    mut values = [30, 10, 20]?
    order = [1, 2, 0]?
    print(values[order[0]])?
    values[order[2]] = 31
    print(values)?
    Ok(())

10
[31, 10, 20]

Transfer or copy ownership

A list has one owner responsible for its mutable contents. Assigning it to another binding transfers that responsibility:

def main() -> Result[(), AllocError | IoError]:
    original = [10, 20]?
    mut changed = original
    changed.append(30)?
    print(changed)?
    Ok(())

[10, 20, 30]

The assignment moves the list. The old binding cannot be used afterward:

def main() -> Result[(), AllocError | IoError]:
    original = [10, 20]?
    changed = original
    print(original)?
    Ok(())

use of moved binding `original`

Passing a collection to an owned parameter or returning it also transfers ownership. A move transfers the existing storage rather than duplicating it.

Use copy(value)? when you need independent contents. Copying observes the source and returns Result[T, AllocError], so the source remains usable whether copying succeeds or fails. Nested mutable contents are copied too; immutable strings may share their existing storage.

Numbers and booleans copy on assignment. Strings remain usable after assignment because their storage is immutable. Tuples containing only these values copy; tuples containing collections move.

A value that copies needs no copy(...)?: write name = original for a string. plenty --check warns about copy(x)? when the type of x already copies. Use copy for values that move, such as lists, when you need two independent owners.

A mutable owner can receive a new value after moving its previous one. The compiler checks all continuing paths: a move on one branch can cause a use of possibly moved binding diagnostic later.

Take part of a list or text

A slice copies part of a list or string into a new value. Write the start and stop positions inside the brackets, separated by :. The start is included and the stop is excluded:

def main() -> Result[(), AllocError | IoError]:
    scores = [70, 85, 90, 65, 88]?
    print(scores[1:3]?)?
    print(scores[:2]?)?
    print(scores[3:]?)?
    print(scores[-2:]?)?
    print(scores[::-1]?)?
    print(scores)?
    Ok(())

[85, 90]
[70, 85]
[65, 88]
[65, 88]
[88, 65, 90, 85, 70]
[70, 85, 90, 65, 88]

An omitted start or stop runs to that end of the list. A negative position counts from the end, so scores[-2:] takes the last two elements. A third number is the step: [::2] takes every second element and [::-1] walks backwards. The source list is unchanged.

A slice allocates its new list, so it returns a Result like a list literal and needs ?:

def main() -> Result[(), AllocError | IoError]:
    scores = [70, 85, 90]?
    top: list[i64] = scores[:2]
    Ok(())

slice returns Result[list[i64], AllocError]; use `?` to propagate allocation failure

Positions outside the list do not stop the program. They clamp to its ends, as in Python, so scores[3:100] and scores[100:] are fine; the second is empty.

Slices are copies

A slice is an explicit copy. Each selected element is copied, including nested lists, so changing the source afterwards does not change the slice:

def main() -> Result[(), AllocError | IoError]:
    mut rows = [[1, 2]?, [3]?]?
    first = rows[:1]?
    rows[0].append(99)?
    print(first)?
    print(rows)?
    Ok(())

[[1, 2]]
[[1, 2, 99], [3]]

Copying costs time and memory in proportion to the selected elements. To read elements without copying them, borrow them as a slice view, &scores[1:], which the element borrowing lesson introduces. A loop over their positions also avoids the copy:

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    scores = [70, 85, 90, 65, 88]?
    mut total = 0
    for i in range(1, len(scores)):
        total += scores[i]
    print(total)?
    Ok(())

328

Text

String slices count Unicode characters, the same positions as len and indexing, so a slice never splits a character:

def main() -> Result[(), AllocError | IoError]:
    word = "café!"
    print(word[:4]?)?
    print(word[-1:]?)?
    print(word[::-1]?)?
    Ok(())

café
!
!éfac

To read part of a string without copying it, borrow it as &word[:4], which the element borrowing lesson introduces.

The step must not be zero. A literal 0 is a compile error, and a computed step is converted with NonZero.try_from(step)?, which reports zero as an error. The slice reference covers steps, tuples, bytes, columnar lists, and views.

Borrow instead of transferring ownership

A shared reference, &T, permits observation. An exclusive reference, &mut T, permits mutation. The owner remains responsible for cleanup. Function signatures state which access is needed:

def first(values: &list[i64]) -> i64:
    values[0]

def add(values: &mut list[i64], value: i64) -> Result[(), AllocError]:
    values.append(value)?
    Ok(())

def main() -> Result[(), AllocError | IoError]:
    mut numbers = [1, 2]?
    print(first(numbers))?
    add(&mut numbers, 3)?
    print(numbers)?
    Ok(())

1
[1, 2, 3]

Collection operations such as append, indexing, and len work directly through references.

The parameter determines borrowing: first(numbers) implicitly lends numbers because first expects &list[i64]. Writing first(&numbers) also works. Use explicit &mut for mutable arguments, as in add(&mut numbers, 3). An owned parameter still takes ownership.

References can also be local bindings. &mut permits changing the target, not reassigning the reference binding. Use *reference to read or replace a scalar target:

def main() -> Result[(), IoError | OverflowError[i64]]:
    mut score = 10
    reference = &mut score
    *reference = *reference + 5
    print(*reference)?
    score = 20
    print(score)?
    Ok(())

15
20

The exclusive borrow ends after the last use of reference, so assigning to score afterward is allowed. A reference that will be used later keeps its loan live, including across branches and loop iterations:

def main() -> Result[(), AllocError | IoError]:
    mut numbers = [1, 2]?
    view = &numbers
    numbers.append(3)?
    print(view)?
    Ok(())

conflicting borrow: cannot modify or exclusively borrow `numbers` while it is borrowed

The diagnostic notes identify the borrow’s creation and the later use that keeps it live.

An exclusive reference can temporarily lend shared or exclusive access. Conflicting access through it is suspended until the child borrow’s last use. Passing an existing reference to a reference parameter reborrows it; the owner is not transferred.

When a conflict goes through a reference, the diagnostic names both the owner and the reference written at the failing use:

def main() -> Result[(), AllocError | IoError]:
    mut numbers = [1, 2]?
    reference = &mut numbers
    view = &reference
    reference.append(3)?
    print(view)?
    Ok(())

conflicting borrow: cannot modify or exclusively borrow `numbers` (through `reference`) while it is borrowed

Borrowing collection elements

Borrow an element when you want to inspect or change it without moving its owner:

def main() -> Result[(), AllocError | IoError]:
    mut counts = [1, 5]?
    value = &mut counts[0]
    *value = 2
    print(counts)?
    Ok(())

[2, 5]

The loan ends after its last use. While an element reference is live, the collection cannot grow, remove entries, or move. An out-of-range index traps. Dictionaries lend a value through get_mut, which returns an Option instead of trapping on a missing key.

Two list elements written as different number literals are different places, so both can be borrowed at once:

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut scores = [10, 20, 30]?
    first = &mut scores[0]
    last = &mut scores[2]
    *first = *first + *last
    *last = 0
    print(scores)?
    Ok(())

[40, 20, 0]

The compiler proves only this literal case. Any other index, such as i or -1, may name the same element, so its loan covers the whole list:

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut scores = [10, 20, 30]?
    i = 2
    first = &mut scores[0]
    last = &mut scores[i]
    *first = *first + *last
    Ok(())

while `scores[0]` is exclusively borrowed

Dictionary entries are never separated this way. To exchange two list elements at computed indices, swap them instead.

Borrowed loops always give references, including when the elements are numbers. Printing and comparison inspect those references directly. Use * when a function takes a value or a new collection needs the element itself:

def count_eq[T](values: &list[T], target: &T) -> Result[i64, OverflowError[i64]]:
    mut count = 0
    for value in values:
        if value == target:
            count = count + 1
    Ok(count)

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    values = [1, 2, 1]?
    target = 1
    print(count_eq(&values, &target)?)?
    for value in &values:
        print(*value)?
    Ok(())

2
1
2
1

The same body works for a list[str]. Shared dictionary items() loops likewise give &K keys and &V values; mutable views give &mut V values. A borrowed collection stays protected against changes throughout its loop.

Borrow part of a list

&values[a:b] borrows a run of elements in place. This slice view copies nothing, so unlike a copying slice it needs no ?. A function takes a view as &[T], or as &mut [T] to change the elements:

def total(values: &[i64]) -> Result[i64, OverflowError[i64]]:
    mut sum = 0
    for value in values:
        sum += *value
    Ok(sum)

def reset(values: &mut [i64]) -> ():
    for value in values:
        *value = 0

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut scores = [70, 85, 90, 65, 88]?
    print(total(&scores)?, total(&scores[1:])?)?
    reset(&mut scores[:2])
    print(scores)?
    Ok(())

398 328
[0, 0, 90, 65, 88]

The positions clamp as a copying slice’s do. A view supports len, indexing, narrower views, loops, and == with another view, and prints as a list of its elements. An exclusive view also takes indexed assignment and swap. A &[T] parameter also takes a whole list as &scores, which is a view that copies nothing. A view borrows its run of the list, and the list cannot grow while the view is live. Two exclusive views of one list can be live together when one stops where the other starts:

def main() -> Result[(), AllocError | IoError | ZeroDivisionError | OverflowError[i64]]:
    mut scores = [70, 85, 90, 65, 88]?
    half = len(scores) // 2
    low = &mut scores[:half]
    high = &mut scores[half:]
    low[0] = high[0]
    print(scores)?
    Ok(())

[90, 85, 90, 65, 88]

Views whose ranges may overlap, such as &mut scores[:3] and &scores[2:], conflict. Byte buffers have views too. A view cannot be returned or stored yet; the slice reference lists its operations and limits.

Borrow part of a string

&text[a:b] borrows part of a string the same way. Its type is &substr, and its positions count characters, as a copying string slice’s do. Loop over it, compare it with a string, or search it without copying:

def count(text: &substr, letter: &str) -> Result[i64, OverflowError[i64]]:
    mut n = 0
    for c in text:
        if c == letter:
            n += 1
    Ok(n)

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    line = "name: Ada Lovelace"
    value = &line[6:]
    print(value, len(value))?
    print(&line[:4] == "name", "Love" in value, count(&line, "a")?)?
    first = value[:3]?
    print(first)?
    Ok(())

Ada Lovelace 12
True True 3
Ada

A function takes a substring as &substr, and a whole string as &line or a literal. Copy the text with value[a:b]? when you need an owned str, for example to call a str method or keep it after the string changes. The substring view reference lists every operation.

Handle allocation failures

Collection construction returns Result[collection, AllocError]. Use ? to propagate a failure, or match to recover:

def answers() -> Result[list[i64], AllocError]:
    mut values = list[i64].with_capacity(2)?
    values.append(21)?
    values.append(42)?
    Ok(values)

def main() -> Result[(), IoError]:
    match answers():
        case Ok(values):
            print(values)?
        case Err(AllocError.OutOfMemory):
            print("not enough memory")?
        case Err(AllocError.CapacityOverflow):
            print("requested capacity is too large")?
    Ok(())

[21, 42]

list[i64].with_capacity(2)? constructs an empty list with room for at least two elements. Appending those elements needs no further list storage allocation. Use list[i64]() when you do not know the capacity ahead of time. dict[str, i64]() and set[str]() construct the other collection kinds. Displays such as [21, 42] return the same kind of allocation result; extract their collection with ? too. List displays reserve their full element count automatically. Both mutable and immutable list bindings benefit. Element expressions may still allocate.

For an existing mutable collection, values.reserve(n)? reserves room for n additional elements beyond its current length. Existing contents remain unchanged if reservation fails.

Growth also returns a result: append for lists, insert for dictionaries, and add for sets. A failed insertion keeps existing contents but consumes its arguments, cleaning up any owned argument rather than returning it.

AllocError has two payload-free variants. OutOfMemory means the allocator rejected a request. CapacityOverflow means its size cannot be represented. Neither variant needs allocation.

Use capacity and reservation to obtain storage before inserting values you want to keep if reservation fails.

Associate keys with values

A dict[K, V] maps keys of one type to values of another. Keys may be integers, booleans, strings, bytes, or tuples of supported keys; values can include collections. Named enums can also be keys when their payloads are supported key types; see heterogeneous dictionaries. The keys() and values() loops below borrow their elements: *name reads the value behind a reference. The borrowing lesson explains references in detail.

def main() -> Result[(), AllocError | IoError]:
    mut scores: dict[str, i64] = {"Ada": 10, "Grace": 20}?
    scores.insert("Ada", 12)?
    scores.insert("Lin", 30)?
    print(scores["Ada"])?
    print("Grace" in scores)?
    for name in scores.keys():
        print(*name)?
    for score in scores.values():
        print(*score)?

    Ok(())

12
True
Ada
Grace
Lin
12
20
30

insert adds a key or replaces the value of an existing one, which keeps its insertion position. Adding a key can allocate, so insert returns an allocation result. Dictionaries have no indexed assignment: scores["Ada"] = 12 is a compile error. Reading scores["Ada"] traps when the key is missing.

To change a value in place, get_mut returns Option[&mut V]: a mutable reference when the key is present, or Nothing:

def main() -> Result[(), AllocError | IoError]:
    mut groups = {"first": [10, 20]?}?
    match groups.get_mut("first"):
        case Some(group):
            group[0] = 11
            group.append(30)?
        case Nothing:
            pass
    print(groups)?
    Ok(())

{"first": [11, 20, 30]}

get_mut allocates nothing. The reference borrows the whole dictionary exclusively, so the dictionary cannot be read or changed while it is live. To change every value, loop over (&mut groups).values() instead of calling get_mut per key; dictionary key/value loops show the mutable form.

To count or group, a missing key needs a starting value. get_or_insert(key, default) inserts the default when the key is absent, then returns a mutable reference to the stored value. It finds the key with one lookup. Inserting can allocate, so it returns a Result; ? propagates the AllocError:

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut counts: dict[str, i64] = {}?
    for word in ["red", "blue", "red"]?:
        *counts.get_or_insert(word, 0)? += 1
    print(counts)?
    Ok(())

{"red": 2, "blue": 1}

The default is built before the lookup, even when the key is present. A default like 0 costs nothing; one that allocates, such as []?, allocates on every call, so use get_mut when the key is usually present.

keys() and values() borrow elements in insertion order without allocating. The references protect the dictionary from mutation while they are used. Keep a key view in a local when checking several properties:

def main() -> Result[(), AllocError | IoError]:
    scores = {"Ada": 12, "Grace": 20}?
    names = scores.keys()
    expected = {"Ada", "Grace", "Lin"}?
    print(len(names), "Ada" in names, names.issubset(&expected))?
    print(names.union(&expected)? == expected)?
    Ok(())

2 True True
True

Read-only checks return plain values. Set algebra and names.to_set() allocate an owned set and return an allocation result. The view stays local: use scores.keys_snapshot()? or scores.values_snapshot()? when an owned ordered list must outlive the borrow. For mutable payloads, copy(groups)?.values_snapshot()? requests independent copies explicitly. into_keys() and into_values() consume a dictionary into an ordered list. See the full view contract for restrictions and cost details. {} is an empty dictionary; select its types with an annotation or a constructor such as dict[str, i64]()?.

Reuse a borrowed view

Bind a shared view when several observations use the same dictionary. The view keeps the dictionary borrowed until its last use; it creates no snapshot.

def main() -> Result[(), AllocError | IoError]:
    scores = {"Ada": 10, "Grace": 20}?
    values = scores.values()
    entries = scores.items()
    print(len(values), len(entries))?
    for score in values:
        print(*score)?
    for name, score in entries:
        print(*name, *score)?
    print(iter(values).count())?
    Ok(())

2 2
10
20
Ada 10
Grace 20
2

Use iter(view) for transformations and terminals. Item-view callbacks take a key and a value parameter, just like direct items() pipelines.

Look up a value that may be absent

Missing keys in scores[key] are runtime errors. Use scores.get(key) when absence is expected. It returns an Option: Some(value) if found, or Nothing if absent. Match the two possibilities explicitly:

def main() -> Result[(), AllocError | IoError]:
    scores = {"Ada": 12, "Grace": 0}?
    match scores.get("Ada"):
        case Some(score):
            print(score)?
        case Nothing:
            print("unknown player")?
    print(scores.get("Grace"))?
    print(scores.get("Lin"))?
    print(scores["Ada"])?
    Ok(())

12
Option[i64].Some(0)
Option[i64].Nothing
12

A stored zero, False, empty string, or Nothing counts as present; looking up a stored Nothing returns Some(Nothing). Use the option match to choose a fallback; get has no default argument.

get leaves the dictionary and key available and does not allocate. It supports numbers, booleans, strings, and enums of such values. It cannot return mutable collections or classes: use pop to take ownership or &dictionary[key] to borrow an existing value. Dictionaries have no optional borrowed lookup yet; your own functions can return a borrow that may be absent.

Read a list element that might be missing

items.get(index) returns Some(value) for an existing element or Nothing for an out-of-range index. It takes one i64 index, including negative indices:

def main() -> Result[(), AllocError | IoError]:
    names = ["Ada", "Bea"]?
    print(names.get(-1))?
    match names.get(2):
        case Some(name):
            print(name)?
        case Nothing:
            print("no name at that position")?
    print(names)?
    Ok(())

Option[str].Some("Bea")
no name at that position
["Ada", "Bea"]

List get has the same element restrictions as dictionary get. For owned elements, use pop to transfer ownership, copy(items[index])? to duplicate one, or &items[index] to borrow it. Ordinary indexing still traps when the index is out of range. The report gives the source position, the index, and the length: error: main.plenty:3:11: index out of bounds: index 5, length 3.

Both forms of get leave their source unchanged. Numbers, booleans, and enums copy; strings share immutable storage. The returned value remains valid if the source is updated or dropped.

Keep distinct values in a set

A set[T] stores each distinct value once. Its elements can be integers, booleans, or strings:

def main() -> Result[(), AllocError | IoError]:
    mut names: set[str] = set()?
    names.add("Ada")?
    names.add("Ada")?
    print(len(names))?
    print("Ada" in names)?
    names.add("Grace")?
    print(names.discard("Ada"))?
    print(names.discard("Ada"))?
    print(len(names))?
    Ok(())

1
True
True
False
1

add needs mutable access and returns an allocation result. discard removes a member without allocating and returns whether it was present.

Use set[str]()? for a typed empty set, or provide an annotation as above. A display such as {"Ada", "Grace"}? builds a set directly. {} is an empty dictionary. Sets have no promised iteration order.

Dictionary and set equality compare contents independently of order.

Remove an entry and take its value

pop(key) removes a dictionary entry and returns Some(value), or Nothing when the key is absent. It requires a mutable dictionary and transfers ownership of the stored value, including nested collections:

def main() -> Result[(), AllocError | IoError]:
    mut groups = {"ready": [1, 2]?, "waiting": [3]?}?
    match groups.pop("ready"):
        case Some(items):
            mut work = items
            work.append(4)?
            print(work)?
        case Nothing:
            print("no work")?
    print(groups)?
    print(groups.pop("missing"))?
    Ok(())

[1, 2, 4]
{"waiting": [3]}
Option[list[i64]].Nothing

The returned owner remains valid if the dictionary is dropped. Discarding a successful pop result also cleans up its removed value.

Removal preserves the order of remaining entries without allocating. Reinserting a removed key puts it at the end. pop takes one key and has no default argument.

Remove list elements

Lists also have pop. With no argument it removes the last element; an i64 index selects another position. Negative indices count from the end:

def main() -> Result[(), AllocError | IoError]:
    mut tasks = [[1]?, [2]?, [3]?]?
    match tasks.pop(1):
        case Some(task):
            mut work = task
            work.append(4)?
            print(work)?
        case Nothing:
            print("no task")?
    print(tasks)?
    print(tasks.pop())?
    print(tasks.pop(-1))?
    print(tasks.pop())?
    Ok(())

[2, 4]
[[1], [3]]
Option[list[i64]].Some([3])
Option[list[i64]].Some([1])
Option[list[i64]].Nothing

List pop needs mutable access. Empty lists and out-of-range indices return Nothing. Removal retains capacity, preserves element order, and does not allocate. Removing the last element is constant time; removing an earlier one shifts subsequent elements.

Returning and unpacking tuples

A tuple groups values with different types. Write (value,) for one component; parentheses without a comma simply group an expression. Function signatures may spell a tuple as (i64, str) or tuple[i64, str]. Unpacking transfers owned components, and _ discards a component. Indices must be integer literals; as with lists, a negative index counts from the end, so pair[-1] is the last component.

def measurement() -> (i64, str):
    (42, "cm")

def main() -> Result[(), IoError]:
    value, unit = measurement()
    print(value)?
    print(unit)?
    print((3, "three"))?
    Ok(())

42
cm
(3, "three")

Creating (a, b) does not allocate a tuple, so it needs no ?. Operations that produce its components, such as the list construction below, can still fail.

Nested tuples can be unpacked in one statement. Match each tuple’s shape, using _ for a component you do not need:

def main() -> Result[(), IoError | OverflowError[i64]]:
    ((x, y), label) = ((3, 4), "point")
    print(label, x + y)?
    Ok(())

point 7

Tuples of numbers, strings, or nested tuples of those can be compared. The first differing component decides the result, just as in sort(). Comparisons leave both values available:

def main() -> Result[(), IoError]:
    first = (1, "apple")
    second = (1, "pear")
    print(first < second, first <= first)?
    print(first, second)?
    Ok(())

True True
(1, "apple") (1, "pear")

Tuple float components follow sorting’s total order: -0.0 precedes 0.0, and NaNs come last. This differs from scalar float comparison; tuple equality still uses the components’ ordinary equality.

Distinct tuple components can be borrowed and read independently. The borrow below protects component 1 while component 0 remains readable:

def main() -> Result[(), AllocError | IoError]:
    mut pair = (1, [2]?)
    items = &mut pair[1]
    first = pair[0]
    print(first)?
    print(pair[0])?
    items.append(3)?
    print(pair)?
    Ok(())

1
1
(1, [2, 3])

Copyable components can be changed through mutable references too. A saved copy has its own inline storage:

def main() -> Result[(), IoError]:
    mut pair = (1, 2)
    saved = pair
    first = &mut pair[0]
    *first = 5
    print(pair)?
    print(saved)?
    Ok(())

(5, 2)
(1, 2)

Use a reference for the write; direct pair[0] = 5 is not supported. Reading an exclusively borrowed component is rejected:

def main() -> Result[(), AllocError | IoError]:
    mut pair = (1, [2]?)
    items = &mut pair[1]
    print(pair[1])?
    items.append(3)?
    Ok(())

conflicting borrow: cannot read or borrow `pair[1]` while it is exclusively borrowed

Print, unpack, and use tuple keys

Print several values with spaces between them. Unpack an owned list when its length is known; the list must contain exactly as many elements as targets. The statement moves its elements, and _ discards an element.

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    first, second = "north east".split(" ")?
    print(first, second, 2)?
    mut visits = dict[(i64, i64), i64].new()?
    cell = (3, 4)
    *visits.get_or_insert(cell, 0)? += 1
    *visits.get_or_insert(cell, 0)? += 1
    print(visits.get(cell, 0))?
    visited = {(3, 4), (3, 4), (4, 3)}?
    print(len(visited), cell in visited)?
    Ok(())

north east 2
2
2 True

Tuple keys contain integers, booleans, strings, or further tuples of those types. Values compare by their contents; a grid coordinate needs no integer encoding or string allocation. get_or_insert starts a missing count at 0 and returns a reference to the stored count; see dictionaries.

Consume dictionary values directly when the dictionary is finished:

def main() -> Result[(), AllocError | IoError]:
    groups = {"first": [1, 2]?, "second": [3]?}?
    for group in groups.into_values()?:
        print(group)?
    Ok(())

[1, 2]
[3]

into_values() consumes the dictionary and transfers its owned values into an ordered list. Use copy(groups)? first if the original is still needed.

Keep a queue with two ends

Use std.deque.Deque for queues and breadth-first traversal. Removing the first element does not shift the remaining elements.

from std.deque import Deque

def main() -> Result[(), AllocError | IoError]:
    mut queue = Deque[(i64, i64)]()?
    queue.append((0, 0))?
    queue.append((0, 1))?
    queue.appendleft((-1, 0))?
    print(len(queue))?
    while not queue.is_empty():
        match queue.popleft():
            case Some(value):
                print(value)?
            case Nothing:
                break
    print(queue.pop())?
    Ok(())

3
(-1, 0)
(0, 0)
(0, 1)
Option[tuple[i64, i64]].Nothing

len(queue) borrows the queue and calls its shared len method, so the queue remains available for removal. The same spelling works for built-in collections and standard containers with a shared len(self) -> i64 method.

Construction and appending return Result with AllocError. End removals return Option and transfer ownership. Appending takes ownership even on failure, while the existing queue remains intact. Growth is occasional; appending within capacity and removing an end allocate nothing. clear() drops all remaining values and retains the buffer for reuse.

See the module reference for exact operations and costs. A deque is owned; it has no borrowed iterator or indexed API yet.

Sort and reorder a list

sort() puts a list in ascending order. sort(True) gives descending order. Both change the list in place, need a mut owner, and allocate nothing, so neither takes ?.

def main() -> Result[(), AllocError | IoError]:
    mut scores = [72, 95, 58, 81]?
    scores.sort()
    print(scores)?
    scores.sort(True)
    print(scores)?
    mut names = ["pear", "fig", "apple"]?
    names.sort()
    print(names)?
    Ok(())

[58, 72, 81, 95]
[95, 81, 72, 58]
["apple", "fig", "pear"]

sort orders integers, floats, strings, and tuples of those. Tuples compare their first components, then the next where the first are equal. To sort records by a key, put the key first:

def main() -> Result[(), AllocError | IoError]:
    mut ranked = [(72, "Ada"), (95, "Bea"), (72, "Abe")]?
    ranked.sort()
    print(ranked)?
    print(ranked[-1][1])?
    Ok(())

[(72, "Abe"), (72, "Ada"), (95, "Bea")]
Bea

Other element types need a key function; natural sorting rejects them:

def main() -> Result[(), AllocError | IoError]:
    mut flags = [True, False]?
    flags.sort()
    Ok(())

sort does not order bool elements; it orders integers, floats, str, and tuples of those

Exchange two elements

swap(i, j) exchanges two elements of any type. Negative indices count from the end, and a missing index is a runtime error.

def main() -> Result[(), AllocError | IoError]:
    mut rows = [[0, 1]?, [2, 3]?, [4, 5]?]?
    rows.swap(0, -1)
    print(rows)?
    Ok(())

[[4, 5], [2, 3], [0, 1]]

The rows are exchanged where they are. Nothing is copied.

An exclusive slice view has the same swap, so a function can reorder part of a list. Its indices count within the view:

def ends(values: &mut [i64]) -> ():
    values.swap(0, -1)

def main() -> Result[(), AllocError | IoError]:
    mut scores = [70, 85, 90, 65, 88]?
    ends(&mut scores[1:4])
    print(scores)?
    Ok(())

[70, 65, 90, 85, 88]

Assign several targets at once

An assignment can name several targets, separated by commas. The whole right side is evaluated first, and then each value is assigned to its target from left to right. That makes an exchange a single statement:

def main() -> Result[(), AllocError | IoError]:
    mut values = [10, 20, 30]?
    values[0], values[2] = values[2], values[0]
    print(values)?
    mut low = 9
    mut high = 4
    low, high = high, low
    print((low, high))?
    Ok(())

[30, 20, 10]
(4, 9)

The right side is a tuple written without its parentheses. Reading values[2] copies an integer. A nested list is owned by its row list and cannot be moved out by reading it, so this form does not exchange owned elements:

def main() -> Result[(), AllocError | IoError]:
    mut rows = [[0, 1]?, [2, 3]?]?
    rows[0], rows[1] = rows[1], rows[0]
    Ok(())

cannot move out of indexed storage; borrow it with &collection[index], take it with replace(collection[index], value) or collection.pop(index), or copy it with copy(collection[index])?

Use rows.swap(0, 1) instead.

Sort by a key or create a sorted copy

sort_by_key reads each element through a shared reference. Its key can be a number, string, or tuple of those, so class and collection elements can be ordered too. An optional positional True requests descending order.

class Point:
    x: i64
    y: i64

def horizontal(point: &Point) -> i64:
    point.x

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut points = [Point(3, 1), Point(1, 2), Point(2, 4)]?
    points.sort_by_key(horizontal)
    for point in &points:
        print(point.x)?
    points.sort_by_key(horizontal, True)
    print(points[0].x)?
    points.sort_by_key(def(point: &Point) -> Result[i64, OverflowError[i64]]: Ok(-point.y))?
    print(points[0].x)?
    Ok(())

1
2
3
3
2

The operation allocates no key buffer. It calls the key repeatedly, so use a consistent key without side effects. Equal keys may change relative order; include a tie breaker in a tuple key when the order matters. The key can also be an anonymous function written in place, as the last call shows, or a reusable shared-call closure.

sorted creates a copy in natural order, leaving its source available. Copying is fallible and therefore needs ?:

def main() -> Result[(), AllocError | IoError]:
    scores = [72, 95, 58]?
    print(sorted(&scores)?)?
    print(scores)?
    print(sorted(&scores, True)?)?
    Ok(())

[58, 72, 95]
[72, 95, 58]
[95, 72, 58]

For a copy ordered by a key, explicitly copy into a mut binding, then call sort_by_key. Keys may return Result; handle the sorting call with ? and include its error in the enclosing signature. On failure, elements may already be reordered. One-shot or mutable-call closures are not supported.

Clean up owned values

Owned values clean up when their scope exits, including through return, break, continue, and error propagation. A move transfers this responsibility. Borrowing lends access while leaving cleanup with the owner.

Use drop(value) to release an owner early:

def main() -> Result[(), AllocError | IoError]:
    mut numbers = [1, 2, 3]?
    drop(numbers)
    numbers = [4]?
    print(numbers)?
    Ok(())

[4]

The old contents are released and the consumed binding is unavailable until reinitialized. Borrow checking prevents dropping an owner while a reference still needs it. A borrow ending at its last use does not destroy the owner.

Dropping a string does not invalidate other strings sharing its immutable storage. Fatal runtime traps terminate without running scope cleanup.

Build singly and doubly linked lists

A linked list connects nodes rather than treating adjacent storage positions as adjacent elements. It is a useful way to see ownership and borrowing at work. For an ordinary stack, prefer list[T]; for a queue with two ends, prefer std.deque. Separate heap allocations and pointer chasing often make linked nodes more expensive than contiguous storage.

These examples preview classes: a class groups typed fields, and its generated constructor takes those fields in declaration order. node.value accesses a field. The pub declarations make the teaching modules and their fields accessible to the example programs; they are not encapsulated collection APIs.

A singly linked list owns its successors

Each node owns one value and optionally a boxed successor. Box(value) moves its argument into a heap allocation and returns a Result; Nothing ends the chain. The box gives this recursive type a finite size.

pub class Node:
    pub value: i64
    pub next: Option[Box[Node]]

pub class Linked:
    pub head: Option[Box[Node]]

pub def push(xs: &mut Linked, value: i64) -> Result[(), AllocError]:
    mut node = Box(Node(value, Nothing))?
    node.next = replace(xs.head, Nothing)
    xs.head = Some(node)
    Ok(())

pub def pop(xs: &mut Linked) -> Option[i64]:
    match replace(xs.head, Nothing):
        case Some(node):
            mut removed: Node = node
            xs.head = replace(removed.next, Nothing)
            Some(removed.value)
        case Nothing:
            Nothing

pub def bump(xs: &mut Linked) -> Result[(), OverflowError[i64]]:
    match &mut xs.head:
        case Some(head):
            mut cursor: &mut Node = head
            while True:
                cursor.value += 1
                match &mut cursor.next:
                    case Some(next):
                        cursor = next
                    case Nothing:
                        break
        case Nothing:
            pass
    Ok(())

replace(place, replacement) installs a new value and returns the old one. It lets push take the head without leaving the borrowed list uninitialized. Allocate the detached node before taking that head: if allocation fails, the caller still owns the original chain. Each successful push allocates one box; popping and walking allocate nothing.

In pop, the annotation removed: Node extracts the contents of the owned box and frees its allocation. Taking removed.next transfers the remaining chain back to the list before the removed node is destroyed.

In bump, matching &mut borrows rather than consumes each link. A borrowed box converts to a reference to its contents, so cursor can advance from one node to its successor without copying or recursion. Incrementing a value can overflow, so bump returns a Result. Earlier nodes remain changed if a later node fails; this traversal is not transactional. This is a preview of borrowed matching.

from singly import Linked, push, pop, bump

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut xs = Linked(Nothing)
    for value in range(1, 4):
        push(&mut xs, value)?
    bump(&mut xs)?
    print(pop(&mut xs))?
    print(pop(&mut xs))?
    print(pop(&mut xs))?
    print(pop(&mut xs))?
    Ok(())

Option[i64].Some(4)
Option[i64].Some(3)
Option[i64].Some(2)
Option[i64].Nothing

Push and pop operate at the head, so this example behaves as a stack. Each operation takes constant time; walking takes time proportional to the number of nodes. Dropping a remaining chain uses bounded native stack space and allocates nothing. Automatic printing, equality, and copying of recursive owners are unsupported; inspect values by traversing the chain instead.

A doubly linked list uses IDs for both directions

Adding an owning prev: Box[Node] would make neighbours own each other. Plenty does not support ownership cycles or references stored in fields. Instead, let a built-in list own every node, and use integer indices as node IDs:

pub class Node:
    pub value: i64
    pub prev: Option[i64]
    pub next: Option[i64]

pub class Linked:
    pub nodes: list[Node]
    pub head: Option[i64]
    pub tail: Option[i64]

pub def push_back(xs: &mut Linked, value: i64) -> Result[(), AllocError]:
    id = len(xs.nodes)
    xs.nodes.append(Node(value, xs.tail, Nothing))?
    match xs.tail:
        case Some(old_tail):
            xs.nodes[old_tail].next = Some(id)
        case Nothing:
            xs.head = Some(id)
    xs.tail = Some(id)
    Ok(())

The empty list has no head or tail. Appending creates a node whose prev is the old tail, connects that tail’s next, and then updates the tail ID. The first node also becomes the head. Append happens before existing links change, so allocation failure leaves them intact.

IDs borrow nothing. Updating neighbouring nodes in separate statements avoids holding simultaneous mutable references into the backing list. Growing that list may move nodes in memory, but their indices remain valid.

from doubly import Linked, push_back

def main() -> Result[(), AllocError | IoError]:
    mut xs = Linked([]?, Nothing, Nothing)
    push_back(&mut xs, 10)?
    push_back(&mut xs, 20)?
    push_back(&mut xs, 30)?

    mut cursor = xs.head
    while True:
        match cursor:
            case Some(id):
                print(xs.nodes[id].value)?
                cursor = xs.nodes[id].next
            case Nothing:
                break

    cursor = xs.tail
    while True:
        match cursor:
            case Some(id):
                print(xs.nodes[id].value)?
                cursor = xs.nodes[id].prev
            case Nothing:
                break
    Ok(())

10
20
30
30
20
10

Forward traversal follows next; backward traversal follows prev. This is a doubly linked list logically, even though links are indices rather than machine pointers. Appending is amortized constant time because the backing list can need to grow; each traversal is linear.

Keep the teaching limits explicit

This example supports append and traversal, not deletion or reusable public handles. It relies on valid IDs and consistent links; public fields let callers break those invariants. Invalid indices trap, and a cycle in the links could make traversal loop forever.

Do not remove a backing-list entry with pop(id): shifting later entries would invalidate their IDs. To support deletion, use vacant slots, for example a list[Option[Node]], and reconnect the removed node’s neighbours. If slots are reused and callers retain IDs, add a generation check to reject stale handles; handles crossing between collections also need an identity policy. This is more than adding a prev field to an owned chain.

See representation choices for trade-offs, recursive storage for ownership limits, and parent links with arena IDs for another use of index-based links. The balanced-tree examples apply the same representation to B-tree and red-black insertion, deletion, and sorted traversal. The trie example uses parent and sibling IDs for iterative prefix retrieval and pruning.

Iteration and transformation

Transform collections with loops and comprehensions. Use generators to produce values incrementally, and collect them when you need a stored result.

Count positions and pair inputs with enumerate and zip directly in loops and comprehensions.

Traverse backward with reversed.

Chain iteration steps with iter to count, test, skip, pair, and collect items without writing the loop.

Iterate over collections and text

for visits list elements, dictionary keys, set elements, range integers, or characters of a string. A character is a one-character str.

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut total = 0
    for n in range(1, 5):
        total = total + n
    print(total)?

    scores = {"Ada": 10, "Grace": 20}?
    for name in &scores:
        print(name)?
        print(scores[name])?

    print(list(range(5, 0, -2))?)?
    for character in "hé":
        print(character)?
    Ok(())

10
Ada
10
Grace
20
[5, 3, 1]
h
é

range(stop) starts at zero; the stop is excluded. A step may be negative but never zero: it is a NonZero[i64]. Ranges can be reused and do not allocate; list(range(5))? allocates the list. String iteration yields characters without allocating.

Ranges default to i64. Use range[u8](8) or a typed bound to choose another element type. Start and stop must fit it; the step remains a signed NonZero[i64].

The iterable is evaluated once. Iterating an owned collection transfers it into the loop; use for item in &values to preserve the owner. Borrowed iteration prevents conflicting mutation; owned list elements become shared references. Use &mut values for mutable element references. To iterate a snapshot while mutating the original, use for item in copy(values)?.

Dictionary key/value loops

items() borrows a dictionary in insertion order. It works directly in loops and comprehensions, without allocating item tuples or a snapshot. Keys and values are shared references. Borrow the dictionary exclusively, (&mut counts).items(), to update every value in place; keys stay shared.

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut counts = {"apple": 2, "pear": 3}?
    for fruit, count in (&mut counts).items():
        *count += 1
    for fruit, count in counts.items():
        print(fruit)?
        print(count)?
    for a, b in [(1, 2), (3, 4)]?:
        print(a + b)?
    Ok(())

apple
3
pear
4
3
7

(&mut counts).values() lends only the values. Neither loop looks a key up or copies a value, so they suit values that cannot be copied. The dictionary cannot grow, shrink, or be read through another path during a mutable loop. A shared items() or values() view can be bound to a name and reused; a mutable one is used directly as the loop source. See updating every value for the full contract.

Count positions and pair inputs

Use enumerate(iterable) to get an i64 index starting at zero beside each element. Supply a second argument to choose the first index. Use zip(left, right) to pair elements until the shorter input ends.

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    for index, letter in enumerate("ab", 10):
        print((index, letter))?
    for number, letter in zip(range(3), "xy"):
        print((number, letter))?
    print([index + value for index, value in enumerate(range(3))]?)?
    Ok(())

(10, "a")
(11, "b")
(0, "x")
(1, "y")
[0, 2, 4]

An owned list transfers its elements. Borrow a list to preserve it; its elements retain their reference types. Borrow mutably to edit them.

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut values = [10, 20]?
    for index, value in enumerate(&mut values):
        *value += index
    for value, offset in zip(&values, range(2)):
        print(*value + offset)?
    print(values)?
    Ok(())

10
22
[10, 21]

Both helpers work directly in loop and comprehension sources. They add no allocation and evaluate their input expressions once, from left to right. They do not yet produce a value you can store or pass to next. Borrowed inputs require two unpacked bindings; references cannot be placed into an item tuple. Nested helpers are supported when their inner items are owned values. To pair a dictionary’s keys, pass the dictionary itself; items() remains a separate loop form.

zip tests the left input before the right. A left generator may advance once more when the right input ends; that unmatched item is dropped. Early exit drops remaining owned inputs. An enumeration index overflows only when another element requires an index beyond i64.MAX.

Traverse backward

Use reversed directly in a loop or comprehension to visit a list, text, or range backward. Borrow a list to keep it afterward. Text yields Unicode scalars, so a multibyte character stays intact.

def main() -> Result[(), AllocError | IoError | ZeroDivisionError]:
    values = [10, 20, 30]?
    for index, value in enumerate(reversed(&values)):
        print((index, *value))?
    for letter in reversed("aé🙂"):
        print(letter)?
    print([x for x in reversed(range(5)) if x % 2 == 0]?)?
    print(values)?
    Ok(())

(0, 30)
(1, 20)
(2, 10)
🙂
é
a
[4, 2, 0]
[10, 20, 30]

reversed adds no allocation and does not change a list’s order. Use reversed(&mut values) to edit its elements in reverse order. It currently accepts only lists, text, and ranges as loop/comprehension sources and pipeline sources; it cannot be stored or passed to next.

Borrowing and unpacking while iterating

Borrow a list when a helper needs to inspect or mutate it without taking ownership:

def total(values: &list[i64]) -> Result[i64, OverflowError[i64]]:
    mut result = 0
    for value in values:
        result = result + value
    Ok(result)

def add(values: &mut list[i64], value: i64) -> Result[(), AllocError]:
    values.append(value)?
    Ok(())

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut numbers = [1, 2]?
    print(total(numbers)?)?
    add(&mut numbers, 3)?
    print(numbers)?
    Ok(())

3
[1, 2, 3]

Unpack a tuple in a loop

def measurement() -> (i64, str):
    (42, "cm")

def main() -> Result[(), AllocError | IoError]:
    value, unit = measurement()
    print(value)?
    print(unit)?
    for number, word in [(1, "one"), (2, "two")]?:
        print((number, word))?
    print((3, "three"))?
    Ok(())

42
cm
(1, "one")
(2, "two")
(3, "three")

Unpacking a borrowed list keeps the list and borrows each component of the current tuple in place: in for number, word in &pairs, number is a &i64 and word a &str. Over &mut pairs, the names are &mut references, so the loop can change the tuples:

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut pairs = [(1, "one"), (2, "two")]?
    for number, _ in &mut pairs:
        *number *= 10
    for number, word in &pairs:
        print(*number, word)?
    print(pairs)?
    Ok(())

10 one
20 two
[(10, "one"), (20, "two")]

The names borrow different components, so both can be passed as &mut arguments to one call:

def swap(a: &mut i64, b: &mut i64) -> ():
    t = *a
    *a = *b
    *b = t

def main() -> Result[(), AllocError | IoError]:
    mut pairs = [(1, 2), (3, 4)]?
    for low, high in &mut pairs:
        swap(low, high)
    print(pairs)?
    Ok(())

[(2, 1), (4, 3)]

Tuple targets can nest. Each name still borrows its own component when the source is borrowed:

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut rows = [((1, 2), "point")]?
    x = 99
    for (x, y), _ in &mut rows:
        *x += 10
        *y += 20
    print(rows)?
    print(x)?
    Ok(())

[((11, 22), "point")]
99

The loop’s x is a new binding to the borrowed component. The outer x remains available after the loop.

Borrow elements while iterating

An exclusive loop lends each element in turn for mutation:

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut numbers = [10, 20]?
    for number in &mut numbers:
        *number = *number + 2
    print(numbers)?
    mut groups = [[1]?, [2, 3]?]?
    for group in &mut groups:
        group.append(4)?
    print(groups)?
    Ok(())

[12, 22]
[[1, 4], [2, 3, 4]]

Use &items when inspection is enough. Copyable elements such as integers and strings are yielded as values; owned elements such as inner lists are shared references. Use &mut items for mutable references, including scalar elements. The outer list cannot grow, shrink, or move during either loop. Afterward, the owner is available again.

Build collections with comprehensions

A comprehension produces a new collection from an iterable and optional filters. The element expression runs only after the filters pass.

def main() -> Result[(), AllocError | IoError | ZeroDivisionError | OverflowError[i64]]:
    squares = [n * n for n in range(8) if n % 2 == 0]?
    print(squares)?
    print({n: n * n for n in [2, 3]?}?)?
    print(len({n // 2 for n in range(8)}?))?
    print([x * 10 + y for x in range(3) for y in range(x)]?)?
    Ok(())

[0, 4, 16, 36]
{2: 4, 3: 9}
4
[10, 20, 21]

Multiple clauses nest from left to right. Later iterables can use earlier variables, and you can use multiple if filters. Variables remain local to the comprehension. Parenthesize a conditional expression used as an iterable or filter. Dictionary comprehensions evaluate each key before its value.

% is modulo: the result follows the divisor’s sign, so -7 % 3 is 2. Both operands must have the same integer type.

Every element must have the same type; there is no implicit numeric widening:

def main() -> Result[(), AllocError | IoError]:
    values = [1, True]?
    Ok(())

expected list[i64]

A comprehension over a range or list with no if clause reserves its full length once; with a filter or another source it grows the output in place. The ? handles allocation failure. A comprehension with one for clause compiles to the same loop as the equivalent pipeline.

Collect a snapshot with unpacking

Unpacking works in comprehensions too. This one collects dictionary items into a list of tuples:

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut counts = {"apple": 2, "pear": 3}?
    for fruit, count in (&mut counts).items():
        *count = *count + 1
    print([(*fruit, *count) for fruit, count in counts.items()]?)?
    print([a + b for a, b in [(1, 2), (3, 4)]?]?)?
    Ok(())

[("apple", 3), ("pear", 4)]
[3, 7]

For dictionaries containing owned values, use copy(value)? when the snapshot needs independent owners. Shared item views yield references for every key and value, so the * above reads each copyable value before storing it in the snapshot tuple.

Text comprehensions collect Unicode scalars:

def main() -> Result[(), AllocError | IoError]:
    print([character for character in "hé"]?)?
    Ok(())

["h", "é"]

Produce values incrementally

A generator function declares Generator[T] and uses yield statements:

def countdown(start: i64) -> Generator[i64]:
    mut remaining = start
    while remaining > 0:
        yield remaining
        # The loop proves 1 <= remaining <= i64.MAX.
        unchecked:
            remaining -= 1

def main() -> Result[(), IoError]:
    numbers = countdown(3)
    print("created")?
    for number in numbers:
        print(number)?
    Ok(())

created
3
2
1

Calling a generator evaluates its arguments immediately but starts its body only when iteration requests a value. Each yield pauses the body, retaining its locals until the next request. A bare return or the end of the body finishes it; a generator cannot return a value.

Creating the generator needs no allocation or ?. Allocating arguments and operations in its body still need their usual error handling. A generator cannot propagate arithmetic errors to its caller. The countdown uses one small unchecked: suite: the loop proves that subtracting one stays in range. For unbounded calculations, yield Result items and let the consumer handle them, as in lazy expressions.

Comprehensions and collection constructors also consume generators:

def numbers(limit: i64) -> Generator[i64]:
    for n in range(limit):
        yield n

def main() -> Result[(), AllocError | IoError | ZeroDivisionError | OverflowError[i64]]:
    print([n * n for n in numbers(6) if n % 2 == 1]?)?
    print(list(numbers(3))?)?
    Ok(())

[1, 9, 25]
[0, 1, 2]

Call next(&mut messages) to advance a mutable generator without consuming it. The shorthand next(messages) also works. It returns Some(value) or Nothing; an exhausted generator keeps returning Nothing:

def once() -> Generator[str]:
    yield "hello"

def main() -> Result[(), IoError]:
    mut messages = once()
    print(next(&mut messages))?
    print(next(&mut messages))?
    print(next(&mut messages))?
    Ok(())

Option[str].Some("hello")
Option[str].Nothing
Option[str].Nothing

Breaking out of consuming iteration drops the generator without resuming its body. Yielding an owned value transfers ownership; to keep it, handle copy(value)’s result and yield the copy.

Generators cannot yield other generators, references, or closures. For a lazy expression producer, use a generator expression. yield from, send, and async operations are unsupported.

Pass a lazy expression to a consumer

A generator expression evaluates one element at a time, when its consumer asks for the next one:

def square(n: i64) -> Result[i64, OverflowError[i64]]:
    Ok(n * n)

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    squares = (square(n) for n in range(4) if n != 2)
    mut values: list[i64] = []?
    for outcome in squares:
        values.append(outcome?)?
    print(values)?
    words = ["tea", "", "café"]?
    print(", ".join(w for w in words if w != "")?)?
    Ok(())

[0, 1, 9]
tea, café

The square helper returns a Result because arbitrary i64 squares can overflow. The generator yields those results without unwrapping them; the loop uses ? in main before appending each value. A caller’s arithmetic mode never changes a producer’s declared contract.

separator.join accepts any iterable of str, so the selected words are joined without first collecting them into a list. A generator cannot be measured in advance, so join grows a scratch buffer as pieces arrive; a list, set, or dictionary is measured first and needs only the result’s allocation. A consumer that stops early, such as the pipeline method any, leaves the remaining elements unevaluated.

The outer source evaluates when the generator is created. Filters, elements, and inner for sources evaluate on demand. The generator owns its sources and copies or moves any enclosing local values it uses; copied captures are snapshots. Borrowed inputs are unsupported because a suspended frame cannot retain a reference into its caller. Use copy(values)? to preserve an owned list, or consume a borrowing pipeline locally instead.

Parentheses can be omitted for a sole argument. With additional arguments, write consume((n for n in source), other). Generator expressions follow the same ownership, cleanup, and yield restrictions as generator functions; they require no intermediate list or heap-allocated frame. A fallible operation in their body must be handled explicitly, since ? cannot propagate out of a suspended generator.

Transfer a generator’s progress

A generator owns a position in an advancing computation. Assignment transfers that owner instead of copying the position:

def once() -> Generator[i64]:
    yield 42

def main() -> Result[(), AllocError | IoError]:
    first = once()
    second = first
    print(list(second)?)?
    Ok(())

[42]

After a move, the old binding cannot be used:

def once() -> Generator[i64]:
    yield 42

def main() -> Result[(), AllocError | IoError]:
    first = once()
    second = first
    list(first)?
    pass
    Ok(())

use of moved binding `first`

Owned arguments, returns, and for iteration also move generators. next(&mut it) borrows a mutable generator without consuming its owner; next(it) remains a shorthand. A mutable binding can be reinitialized after moving its previous value.

The compiler checks all possible continuing paths. A move on just one branch makes later reuse unsafe, reported as use of possibly moved binding. Within a loop, an outer generator must be reinitialized before any path repeats the loop. Generators cannot be stored in collections or user-defined enum payloads yet.

See Borrow a collection for the borrowing rules.

Drop without resuming

Use drop(value) to release an owner earlier. The consumed binding becomes unavailable; a mutable binding may then receive another value:

def pending() -> Generator[i64]:
    yield 1

def main() -> Result[(), AllocError | IoError]:
    mut numbers = [1, 2, 3]?
    drop(numbers)
    numbers = [4]?
    print(numbers)?

    task = pending()
    drop(task)
    print("done")?
    Ok(())

[4]
done

Dropping a generator cleans its captured values without resuming its body. Borrow checking prevents dropping an owner while a reference still needs it. A borrow can end at its last use; that does not implicitly destroy its owner.

Passing and returning generators

Use Generator[T] to accept or return a generator:

def once(n: i64) -> Generator[i64]:
    yield n

def pair() -> Generator[i64]:
    yield 10
    yield 20

def source(n: i64) -> Generator[i64]:
    once(n)

def total(values: Generator[i64]) -> Result[i64, OverflowError[i64]]:
    mut result = 0
    for value in values:
        result = result + value
    Ok(result)

def main() -> Result[(), IoError | OverflowError[i64]]:
    print(total(source(7))?)?
    print(total(pair())?)?
    Ok(())

7
30

total accepts either producer. Passing a generator transfers ownership; use &mut Generator[T] when a helper should advance an existing owner with next. Once you know closures, Transform a stream of values shows how to filter, map and reduce a generator without writing the loop.

A factory must return the same producer on every path. Two generators yielding the same type are not interchangeable return values:

def one() -> Generator[i64]:
    yield 1

def two() -> Generator[i64]:
    yield 2
    yield 3

def choose(flag: bool) -> Generator[i64]:
    if flag:
        return one()
    two()

def main() -> ():
    drop(choose(True))

expected Generator[i64] from `one`, got Generator[i64] from `two`

Put such a branch inside one generator body instead. A generator may contain another generator, but recursive generator state is rejected: its inline storage would have no finite size.

Creating generators

An ordinary function can create and return a generator:

def numbers() -> Generator[i64]:
    yield 10
    yield 20

def source() -> Generator[i64]:
    numbers()

def total() -> Result[i64, OverflowError[i64]]:
    values = source()
    mut result = 0
    for n in values:
        result = result + n
    Ok(result)

def main() -> Result[(), IoError | OverflowError[i64]]:
    print(total()?)?
    Ok(())

30

A factory that can fail can return Result[Generator[T], E]. Write Ok(numbers()) for success and use ? at the factory’s call site. Wrapping a generator adds no allocation; dropping the wrapper releases its captures without resuming the body.

Collect results into owned collections

Return a comprehension’s Result directly when the caller should handle allocation failure:

def squares() -> Result[list[i64], AllocError | ZeroDivisionError | OverflowError[i64]]:
    [n * n for n in range(6) if n % 2 == 0]

def main() -> Result[(), AllocError | IoError | AllocError | OverflowError[i64] | ZeroDivisionError]:
    print(squares()?)?
    Ok(())

[0, 4, 16]

Collect an owned iterator with recoverable list growth:

def numbers() -> Generator[i64]:
    yield 3
    yield 6

def collect() -> Result[list[i64], AllocError]:
    source = numbers()
    list[i64].from(source)

def main() -> Result[(), AllocError | IoError]:
    print(collect()?)?
    Ok(())

[3, 6]

from consumes the source. If allocation fails, it drops the partial list and remaining iterator. Neither from nor comprehensions undo earlier effects or handle failures inside the producer’s body.

Sets provide the same constructor, removing duplicates in first-seen order:

def main() -> Result[(), AllocError | IoError]:
    print(set[i64].from([3, 1, 3, 2]?)?)?
    Ok(())

{3, 1, 2}

Dictionary sources iterate over keys. from does not support borrowed sources or string iteration.

Chain iteration steps with iter

iter(source) starts a pipeline: a chain of iteration steps that runs only when a loop or a final method such as count() consumes it. No intermediate collection is built.

def main() -> Result[(), AllocError | IoError]:
    rolls = [3, 6, 2, 6, 6, 1]?
    print(iter(&rolls).filter_value(6).count())?
    for turn, roll in iter(&rolls).enumerate(1).skip(2).take(3):
        print(turn, *roll)?
    print(len(rolls))?
    Ok(())

3
3 2
4 6
5 6
6

filter_value(6) keeps the items equal to 6, and count() counts them without building a list. enumerate(1) numbers the items from one, skip(2) discards the first two, and take(3) stops after three more. Steps apply in the order written: enumerate comes first, so the turn numbers count every roll, including skipped ones.

The source follows the ordinary iteration rules. Borrowing rolls keeps the list, and each item is a reference, so the loop reads *roll. filter_value still takes a plain i64: a borrowed item is compared by value. It also accepts a borrowed value, such as filter_value(&wanted), so a string can be matched without copying it; wanted then stays borrowed until the pipeline ends.

A pipeline is single-use. Consuming it again, or using an owned source after the pipeline has taken it, is an ownership error.

Add up and find extremes

sum(), min(), and max() are final methods that need no function either:

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    rolls = [3, 6, 2, 6, 6, 1]?
    print(iter(&rolls).sum()?, iter(&rolls).min(), iter(&rolls).skip(4).max())?
    none: list[i64] = []?
    print(iter(&none).sum()?, iter(&none).max().unwrap_or(0))?
    Ok(())

24 Option[i64].Some(1) Option[i64].Some(6)
0 0

A borrowed item is read by value, so the results are i64, not references. sum() gives zero for no items. Integer overflow returns OverflowError[i64], handled with ? here; floating-point sums retain IEEE behavior. min() and max() return an Option, Nothing for no items. They accept numbers and str and keep the first of equal items. Floats follow the IEEE 754 rules for NaN and signed zero, as std.math.min_all and max_all do; the pipeline reference gives them.

Test boolean items

any() reports whether at least one item is True, and all() whether every item is. Both stop as soon as they know the answer:

def positive(values: list[i64]) -> Generator[bool]:
    for value in values:
        yield value > 0

def main() -> Result[(), AllocError | IoError]:
    present = [True, False, True]?
    print(iter(&present).any(), iter(reversed(&present)).all())?
    print(positive([2, -1, 3]?).any(), positive([2, -1, 3]?).all())?
    none: list[bool] = []?
    print(iter(&none).any(), iter(&none).all())?
    Ok(())

True False
True False
False True

The generator computes each comparison only when advanced, so all() stops at -1 and never tests 3; its frame is cleaned up when the method returns. For no items, any() gives False and all() gives True.

Without an argument, these methods need bool items: numbers and text have no implicit truth value. To test other items, pass a predicate function; that form is taught in Reduce a borrowed collection with a pipeline.

Pair, join, and collect

zip walks two sources together, and chain continues with a second source of the same item type. collect() builds the collection named by the binding’s annotation and returns a Result for allocation failure:

def main() -> Result[(), AllocError | IoError]:
    names = ["Ada", "Bob", "Cal"]?
    present = [True, False, True]?
    for name, here in iter(&names).zip(&present):
        print(name, *here)?
    print(iter(&present).filter_value().count())?
    morning = [3, 1]?
    evening = [4, 3]?
    readings: list[i64] = iter(morning).chain(evening).collect()?
    print(readings)?
    Ok(())

Ada True
Bob False
Cal True
2
[3, 1, 4, 3]

Without an argument, filter_value() keeps True items. The two owned lists move into the chain, so their numbers move into readings without copying.

The value must have the item’s type. There is no implicit conversion, and the no-argument form works only for bool items:

def main() -> Result[(), AllocError | IoError]:
    rolls = [3, 6]?
    print(iter(&rolls).filter_value("6").count())?
    Ok(())

filter_value compares &i64 items with a str value; it requires i64 or &i64

Take one item, then continue

next takes one item from a pipeline, as it does from a generator. The pipeline keeps its place, so a loop or final method afterwards continues with the remaining items:

def main() -> Result[(), AllocError | IoError]:
    lines = ["name,score", "ada,3", "bob,5"]?
    mut rows = iter(lines)
    match next(rows):
        case Some(header):
            print("columns:", header)?
        case Nothing:
            print("no header")?
    for number, row in rows.enumerate(1):
        print(number, row)?
    Ok(())

columns: name,score
1 ada,3
2 bob,5

The binding needs mut because next advances it. next returns an owned Option, so it needs owned items: here iter(lines) moves the list into the pipeline. For a borrowed source, first map each item to an owned value. Once next returns Nothing, the pipeline stays empty.

Lend a pipeline to a function

A function can take a pipeline as &mut Iter[T] and consume part of it. The caller lends it with &mut and continues after the items the function took:

def print_header(rows: &mut Iter[str]) -> Result[(), AllocError | IoError]:
    match next(rows):
        case Some(header):
            print("columns:", header)?
        case Nothing:
            print("no header")?
    Ok(())

def main() -> Result[(), AllocError | IoError]:
    lines = ["name,score", "", "ada,3", "bob,5"]?
    mut rows = iter(lines).filter(def(line: &str) -> bool: line != "")
    print_header(&mut rows)?
    print(rows.count(), "rows")?
    Ok(())

columns: name,score
2 rows

The function can also loop over rows and break or return early; the rest stays with the caller. It cannot keep or return the pipeline.

A pipeline over a borrowed list yields references, written &mut Iter[&str] here. The function can use each item while it runs, but cannot return one, because the caller lent the list only for the call:

def greet_first(names: &mut Iter[&str]) -> Result[(), IoError]:
    for name in names:
        print("hello", name)?
        break
    Ok(())

def main() -> Result[(), AllocError | IoError]:
    names = ["ada", "bob", "ada", "cal"]?
    mut adas = iter(&names).filter_value("ada")
    greet_first(&mut adas)?
    print(adas.count(), "more")?
    print(len(names))?
    Ok(())

hello ada
1 more
4

A lent pipeline whose callbacks borrow local values needs those closures written inside the adapter calls; see Lend a pipeline whose callbacks borrow.

Generators have the same methods without iter:

def countdown(start: i64) -> Generator[i64]:
    mut remaining = start
    while remaining > 0:
        yield remaining
        # The loop proves 1 <= remaining <= i64.MAX.
        unchecked:
            remaining -= 1

def main() -> Result[(), AllocError | IoError]:
    last: list[i64] = countdown(10).skip(7).collect()?
    print(last)?
    Ok(())

[3, 2, 1]

skip still advances the generator past the first seven values; it only discards them.

Prefer a pipeline when a chain of these steps states the task directly, and a plain loop or comprehension when the work needs its own expression or several statements. Most other pipeline steps, such as map, filter, and fold, take a function. They are taught after functions as values, starting with Reduce a borrowed collection with a pipeline. The pipeline reference lists every step and its cost.

Defining your own data

Use classes for records with fields and methods, and enums for alternatives. Their fields follow the same ownership and cleanup rules as collections.

Heterogeneous collections combines classes and enums in lists and dictionary values, and explains the restrictions on sets and dictionary keys. Special-purpose data structures introduces columnar lists for scanning selected primitive fields.

Group fields and methods in a class

A class is a record with typed fields. Without __init__, its constructor takes the fields in declaration order:

class Point:
    x: i64
    y: i64

    def squared_length(self) -> Result[i64, OverflowError[i64]]:
        Ok(self.x * self.x + self.y * self.y)

    def shift(self: &mut Point, amount: i64) -> Result[(), OverflowError[i64]]:
        x = self.x + amount
        y = self.y + amount
        self.x = x
        self.y = y
        Ok(())

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut point = Point(y=4, x=3)
    print(point.squared_length()?)?
    point.shift(amount=1)?
    mut changed = copy(point)?
    changed.x = 20
    print(point)?
    print(changed)?
    Ok(())

25
Point(x=4, y=5)
Point(x=20, y=5)

Ordinary methods borrow self read-only by default: self is shorthand for self: &Point here. A method that changes fields declares self: &mut Point. Calling it requires a mut binding or an exclusive reference. shift calculates both coordinates before changing either, so overflow leaves the point unchanged. Arithmetic failure does not undo earlier assignments automatically. An explicit self: Point instead takes ownership; see consuming methods for state transitions and finalization.

Methods can share names with integer built-ins. A class receiver selects its own method, including its parameter and return types:

class Counter:
    total: i64

    def wrapping_add(self: &Counter, other: i64) -> Result[i64, OverflowError[i64]]:
        Ok(self.total + other)

def main() -> Result[(), IoError | OverflowError[i64]]:
    counter = Counter(1)
    print(counter.wrapping_add(2)?)?
    Ok(())

3

This method uses ordinary checked addition; its name does not change that.

If you forget the receiver annotation, the error names the required signature:

class Counter:
    value: i64
    def increment(self) -> Result[(), OverflowError[i64]]:
        self.value = self.value + 1
        Ok(())

def main() -> ():
    pass

declare `self: &mut Counter`

Change the parameter to self: &mut Counter, as in shift above. The lifecycle methods __init__ and __del__ give bare self exclusive access automatically.

Instances store their fields inline: Point(3, 4) needs no allocation or ?. Copying list fields can still fail to allocate.

By default, class instances move even when their fields are all integers. other = point transfers ownership; copy(point) requests an independent instance. Integer and string fields can be read directly. Owned fields such as lists or other classes must be borrowed, observed, or explicitly copied. Equality compares fields; printing shows the class name and fields.

Copy small value types

Write @copy on the line before class when instances are plain values, like integers. Assignment, argument passing, returning, and storing in a collection then copy the instance and leave the original usable:

@copy
class Money:
    cents: i64
    currency: str

def add(a: Money, b: Money) -> Result[Money, OverflowError[i64]]:
    Ok(Money(a.cents + b.cents, a.currency))

def main() -> Result[(), IoError | OverflowError[i64]]:
    price = Money(250, "EUR")
    tax = Money(50, "EUR")
    paid = add(price, tax)?
    mut discounted = price
    discounted.cents = 200
    print(price, paid, discounted)?
    Ok(())

Money(cents=250, currency="EUR") Money(cents=300, currency="EUR") Money(cents=200, currency="EUR")

Every field must itself copy: a scalar, str, another @copy class, or a tuple or enum of those. Copying duplicates the inline fields and never allocates, so it needs no ?. A field that owns storage is rejected:

@copy
class Basket:
    items: list[str]

def main() -> ():
    pass

every field of a `@copy` class must copy

A @copy class also cannot define __del__. A generic @copy class copies when its type arguments copy, so Pair[i64] copies and Pair[list[i64]] moves. Keep the default for instances that own resources or should be used only once; see copy classes.

Hide secrets when printing

Printing a class shows every field, so a password or key reaches any log that prints its holder. Write @redacted before class or enum to replace the contents with (@redacted) wherever the value is printed or formatted, however deeply it is nested:

@redacted
class Password:
    text: str

class Login:
    user: str
    password: Password

def main() -> Result[(), AllocError | IoError]:
    login = Login("ada", Password("hunter2"))
    print(login)?
    print(str.repr(login.password)?)?
    print(login.password.text == "hunter2")?
    Ok(())

Login(user="ada", password=Password(@redacted))
Password(@redacted)
True

The fields stay readable in code, so redaction prevents accidental printing rather than enforcing secrecy; see redacted types.

Limits

There is no inheritance, dynamic attribute creation, or class-variable syntax. Fields currently have no default values. Constructors and methods accept named arguments; an explicit __init__ can give its parameters defaults.

Give arithmetic meaning to your types

Use arithmetic operators when their meaning is natural for your type. A method named __add__ defines +, and __neg__ defines unary -. These are statically compiled calls, so using the operator does not introduce runtime method lookup.

The distance wrappers here demonstrate hook and forwarding mechanics. For physical calculations, use quantities: they also check the dimensions of products and quotients, which these wrappers do not.

class Distance:
    metres: i64

    def __add__(self, other: &Distance) -> Result[Distance, OverflowError[i64]]:
        Ok(Distance(self.metres + other.metres))

    def __neg__(self) -> Result[Distance, OverflowError[i64]]:
        Ok(Distance(-self.metres))

    def __mul__(self, scale: i64) -> Result[Distance, OverflowError[i64]]:
        Ok(Distance(self.metres * scale))

    def __rmul__(self, scale: i64) -> Result[Distance, OverflowError[i64]]:
        self * scale

    def add(self: &mut Distance, other: &Distance) -> Result[(), OverflowError[i64]]:
        self.metres += other.metres
        Ok(())

def main() -> Result[(), IoError | OverflowError[i64]]:
    mut walk = Distance(10)
    extra = Distance(5)
    print((walk + extra)?, (-extra)?, (3 * extra)?)?
    walk.add(&extra)?
    print(walk, extra)?
    Ok(())

Distance(metres=15) Distance(metres=-5) Distance(metres=15)
Distance(metres=15) Distance(metres=5)

The ordinary hooks borrow their operands, so extra stays usable. The reflected hook __rmul__ handles a distance on the right of 3 * extra. The named add method takes exclusive access and updates walk in place. Its integer addition can fail, so it returns a Result; the binding must be mutable.

Integer hooks declare overflow just like ordinary functions. A hook can also report a domain error; here the extra check prevents negative combined stock:

class Stock:
    amount: i64

    def __add__(self, other: &Stock) -> Result[Stock, str | OverflowError[i64]]:
        total = self.amount + other.amount
        if total < 0:
            return Err("negative stock")
        Ok(Stock(total))

def main() -> Result[(), IoError | str | OverflowError[i64]]:
    a = Stock(5)
    b = Stock(3)
    combined = (a + b)?
    print(combined.amount)?
    Ok(())

8

Parenthesize the operation before ?. Allocation errors follow the same pattern. For a fallible update, write value = (value + other)? or call a named method; += requires a unit-returning in-place hook. For large data, a named method that writes into reusable output storage can avoid intermediate allocations.

A class that only gives a distinct name to one value can forward its field’s operators instead of defining a hook for each. Annotate it @newtype:

@newtype
class Metres:
    value: i64

@newtype
class Seconds:
    value: i64

def main() -> Result[(), IoError | OverflowError[i64]]:
    run = Metres(400)
    mut total = run + run
    total += Metres(100)
    print(total, total > run)?
    lap = Seconds(70)
    print(lap * Seconds(2))?
    Ok(())

Metres(value=900) True
Seconds(value=140)

run + run adds the two value fields and wraps the sum back in Metres, and comparisons such as > return bool. Typing stays nominal: run + lap and run + 100 are compile errors, which keeps metres and seconds apart. An explicit hook such as __add__ takes over its own operator. @newtype does not make the class copy; add @copy for that.

Equality still compares fields automatically. Python special methods that Plenty never calls, such as __eq__, __hash__, __str__ and __len__, are compile errors rather than silently ignored; see equality, ordering and hashing and reserved method names. For supported hooks, exact signatures, and resolution rules, see user-defined arithmetic operators.

Return a reference to a field

A function that returns a reference borrows it from its first reference parameter; for a method, that is self. The returned value must borrow that parameter, never a later one or a local owner. The caller keeps the original value alive and borrowed until the result’s last use.

class Pair:
    left: i64
    right: i64
    def left_ref(self: &mut Pair) -> &mut i64:
        &mut self.left

def main() -> Result[(), IoError]:
    mut pair = Pair(1, 2)
    left = pair.left_ref()
    *left = 8
    print(pair.left)?
    Ok(())

8

A mutable returned reference requires the first reference parameter to be &mut. A temporary receiver cannot supply a reference that outlives it.

Later reference parameters only lend their values for the call. A lookup can take its key by reference and still return a borrow of the collection:

def score(scores: &dict[str, i64], name: &str) -> &i64:
    &scores[*name]

def main() -> Result[(), AllocError | IoError]:
    scores = {"ada": 3, "bob": 5}?
    mut name = "bob"
    points = score(&scores, &name)
    name = "eve"
    print(*points)?
    print(name)?
    Ok(())

5
eve

The key’s loan ends when score returns, so name can change while points is live. To return a borrow of name, it would have to be the first parameter.

Return a borrow that may be absent

A search may find nothing. Return Option[&T], or Option[&mut T] to let the caller change what was found. Some must borrow the first reference parameter; Nothing borrows nothing:

class Item:
    name: str
    count: i64

def find(items: &mut list[Item], name: &str) -> Option[&mut Item]:
    for item in items:
        if item.name == name:
            return Some(item)
    Nothing

def add(items: &mut list[Item], name: str) -> Result[(), AllocError | OverflowError[i64]]:
    match find(items, &name):
        case Some(item):
            item.count += 1
        case Nothing:
            items.append(Item(name, 1))?
    Ok(())

def main() -> Result[(), AllocError | IoError | AllocError | OverflowError[i64]]:
    mut items: list[Item] = []?
    add(&mut items, "ada")?
    add(&mut items, "bob")?
    add(&mut items, "ada")?
    for item in items:
        print(item.name)?
        print(item.count)?
    Ok(())

ada
2
bob
1

Match the result directly. In the Some arm, item borrows items, so the list cannot change there. The Nothing arm holds no borrow, so it can append. Result[&T, E] works the same way with Ok; its error cannot hold a reference. ? and unwrap() also produce the reference.

The result can be held in a local until it is matched, but it cannot be stored in a list, a field, or a mut binding: match it and store an owned copy or an index. The reference lists every rule.

Shared arguments can borrow temporaries, as in size("ada") for a size(s: &str) function. The temporary lives through the expression. A result borrowing it may be used immediately, but cannot be stored or returned. Mutable temporaries are unsupported.

An exclusive method can use a completed read of its receiver as an argument. This also works through an existing exclusive reference:

import std.bytes
from std.bytes import Bytes

def clear(buffer: &mut Bytes) -> ():
    buffer.fill(0, buffer.len(), 0u8)

def main() -> Result[(), AllocError | IoError]:
    mut buffer = std.bytes.from_list([1u8, 2u8]?)?
    clear(&mut buffer)
    print(buffer.to_list()?)?
    Ok(())

[0, 0]

The receiver is reserved first, arguments run left to right, and exclusive access begins when the method starts. Arguments may read the receiver, but cannot mutate or move it, or pass a reference into it that remains live during the call. For nested mutations, compute the inner result in a separate local before calling the outer method.

Control construction with init

Define __init__ to calculate or check fields during construction. It replaces the generated constructor; bare self is an exclusive reference:

class Span:
    start: i64
    end: i64

    def __init__(self, start: i64, length: i64) -> Result[(), OverflowError[i64]]:
        self.start = start
        self.end = start + length
        Ok(())

    def length(self) -> Result[i64, OverflowError[i64]]:
        Ok(self.end - self.start)

def main() -> Result[(), IoError | OverflowError[i64]]:
    span = Span(10, 5)?
    print(span)?
    print(span.length()?)?
    Ok(())

Span(start=10, end=15)
5

The initializer calculates the endpoint from a start and length. Overflow returns its declared OverflowError[i64], so Span(10, 5) returns Result[Span, OverflowError[i64]]; ? propagates failure through main. An initializer returning () instead gives an infallible constructor. Construction itself allocates nothing and adds no allocation error; see constructor contracts.

Every field must be initialized on every path out of the constructor. You may read a field already initialized, but cannot pass the whole unfinished self to another function or method. A loop might never execute, so initializing a field only inside a loop is insufficient.

class Pair:
    first: i64
    second: i64

    def __init__(self, first: i64) -> ():
        self.first = first

def main() -> ():
    pass

fields not initialized: second

Initialize fallible fields

An initializer can return Result[(), E] when setting up its fields may fail. The constructor then returns Result[Class, E]. Here, reserving list capacity can fail to allocate:

class Buffer:
    values: list[i64]

    def __init__(self: &mut Buffer, size: i64) -> Result[(), AllocError]:
        self.values = list[i64].with_capacity(size)?
        Ok(())

def main() -> Result[(), AllocError | IoError]:
    print(Buffer(8)?)?
    Ok(())

Buffer(values=[])

If initialization fails, the fields already initialized are dropped, but the incomplete instance’s __del__ is skipped. Successful initialization must fill every field and return Ok(()).

Borrow distinct fields

Borrow a field directly with & or &mut:

class Basket:
    count: i64
    items: list[str]

def main() -> Result[(), AllocError | IoError]:
    mut basket = Basket(0, []?)
    count = &mut basket.count
    *count = 2
    basket.items.append("apple")?
    basket.items.append("pear")?
    print(basket)?
    Ok(())

Basket(count=2, items=["apple", "pear"])

Distinct fields can be borrowed or changed independently. Borrowing a whole record overlaps all its fields. Collection element references such as &basket.items[0] protect the collection against changes that could invalidate the element’s address. You can replace a class-valued field by assignment, but cannot replace a whole class through *reference = new_instance yet.

class Position:
    x: i64
    y: i64

def main() -> Result[(), IoError]:
    mut position = Position(1, 2)
    x = &mut position.x
    y = &mut position.y
    *x = 10
    *y = 20
    print(*x)?
    print(*y)?
    Ok(())

10
20

Borrowing a field through a getter

A simple getter that directly returns a field preserves the field’s identity for the borrow checker. After the call, unrelated fields remain available:

class Pair:
    x: i64
    y: i64
    def x_ref(self: &mut Pair) -> &mut i64:
        &mut self.x

def main() -> Result[(), IoError]:
    mut pair = Pair(1, 2)
    x = pair.x_ref()
    pair.y = 7
    *x = 9
    print(pair)?
    Ok(())

Pair(x=9, y=7)

Getters that choose between fields borrow the whole argument. Indexed references also borrow the whole collection. The call still requires the access declared by the receiver type.

Describe alternatives with enums

An enum defines alternatives, each of which may carry typed data. Match its variants to extract that data:

enum Reading:
    Missing
    Value(i64)
    Invalid(str)

def describe(reading: Reading) -> str:
    match reading:
        case Reading.Missing:
            "no reading"
        case Reading.Value(number):
            "positive" if number > 0 else "nonpositive"
        case Reading.Invalid(reason):
            reason

def main() -> Result[(), IoError]:
    print(describe(Reading.Missing))?
    print(describe(Reading.Value(42)))?
    print(describe(Reading.Invalid("sensor offline")))?
    Ok(())

no reading
positive
sensor offline

Enum payloads are stored inline: Reading.Value(42) needs no allocation or ?. Variants without data omit parentheses. Payloads may have several positions, such as Pair(i64, str). Case bindings are immutable and local to that case. Use _ to ignore a payload position or a final case _: to cover remaining variants; case _ as name: also binds the remaining value. Duplicate or missing cases are errors:

enum Switch:
    On
    Off

def main() -> Result[(), IoError]:
    match Switch.On:
        case Switch.On:
            print("on")?
    Ok(())

non-exhaustive match; missing Switch.Off

A final match produces the function’s result; cases can also return early or break/continue a loop. A match can also be the value of a binding. Separately declared enums remain distinct types, even with identical variants.

A payload position can hold another pattern instead of a name, so one case reaches into an enum stored inside an enum. | joins patterns that share an arm; every alternative must bind the same names:

enum Shape:
    Dot
    Circle(i64)
    Rect(i64, i64)

enum Slot:
    Empty
    Full(Shape)

def width(slot: Slot) -> i64:
    match slot:
        case Slot.Full(Shape.Circle(size) | Shape.Rect(size, _)):
            size
        case Slot.Full(Shape.Dot) | Slot.Empty:
            0

def main() -> Result[(), IoError]:
    print(width(Slot.Full(Shape.Rect(3, 4))))?
    print(width(Slot.Full(Shape.Circle(5))))?
    print(width(Slot.Empty))?
    Ok(())

3
5
0

Coverage is checked through the nested patterns: leaving out Slot.Full(Shape.Dot) is an error that names it.

Payloads can contain strings, collections, and other enums. Matching an enum with mutable payloads consumes it and transfers those payloads; use match copy(value)? to preserve the owner.

An enum can keep behavior beside its variants. A method’s bare self is a shared borrow, so matching it borrows the payload. The same method can satisfy a structural protocol:

protocol Numbered:
    def number(self) -> i64:
        pass

enum Reading:
    Missing
    Value(i64)

    def number(self) -> i64:
        match self:
            case Reading.Missing:
                0
            case Reading.Value(value):
                *value

def number[T: Numbered](value: &T) -> i64:
    value.number()

def main() -> Result[(), IoError]:
    reading = Reading.Value(42)
    print(number(&reading))?
    print(reading.number())?
    Ok(())

42
42

Use pub def when callers in other modules need the method, and self: &mut Reading when it changes a payload. Variant and method names must be distinct. The formatting lesson uses an enum method to produce a message while preserving the error data.

Match combinations with tuple patterns

Match a tuple when the answer depends on several values together. Each component takes a pattern, and the cases cover combinations of components:

def combine(left: Option[i64], right: Option[i64]) -> Result[i64, OverflowError[i64]]:
    match (left, right):
        case (Some(a), Some(b)):
            Ok(a + b)
        case (Some(a), Nothing):
            Ok(a)
        case (Nothing, Some(b)):
            Ok(b)
        case (Nothing, Nothing):
            Ok(0)

def main() -> Result[(), IoError | OverflowError[i64]]:
    print(combine(Some(3), Some(4))?)?
    print(combine(Nothing, Some(5))?)?
    Ok(())

7
5

Leaving out (Nothing, Nothing) is an error: both inputs can be absent. Tuple patterns also nest inside enum payloads, such as Some((value, offset)). Write (pattern,) for a singleton tuple; (pattern) groups a pattern.

Matching an owned tuple transfers owned components into the case’s bindings and destroys ignored components. Match &value or &mut value to borrow its components, as in borrowed matching. The matching reference describes coverage and pattern limits.

Match literal values

A pattern can be an integer, string, or boolean literal. It matches a value equal to it, so match also selects on an integer, a str, or a bool directly, and on such a value inside an enum payload:

enum Command:
    Move(i64)
    Say(str)

def opcode(name: str) -> i64:
    match name:
        case "cpy":
            1
        case "inc" | "dec":
            2
        case _:
            0

def describe(command: Command) -> str:
    match command:
        case Command.Move(0):
            "stay"
        case Command.Move(_):
            "move"
        case Command.Say("" | "..."):
            "silence"
        case Command.Say(words):
            words

def main() -> Result[(), IoError]:
    print(opcode("cpy"))?
    print(opcode("dec"))?
    print(opcode("jmp"))?
    print(describe(Command.Move(0)))?
    print(describe(Command.Move(3)))?
    print(describe(Command.Say("...")))?
    print(describe(Command.Say("hello")))?
    Ok(())

1
2
0
stay
move
silence
hello

Cases are tried in order. Literals cannot name every integer or string, so such a match ends with case _:, and a payload position needs _ or a name after its literals:

def main() -> Result[(), IoError]:
    count = 3
    match count:
        case 1:
            print("one")?
    Ok(())

non-exhaustive match; cases cannot name every i64 value, so end with `case _:`

True and False together cover a bool, so no case _: follows them:

def label(enabled: bool) -> str:
    match enabled:
        case True:
            "on"
        case False:
            "off"

def main() -> Result[(), IoError]:
    print(label(True))?
    print(label(3 > 4))?
    Ok(())

on
off

An integer literal takes the type of the value it matches and must fit it: case 300: is an error for a u8. A float is not a pattern; compare floats with if. A bare name still binds only at a payload position, so the catch-all for the whole value is case _:, or case _ as name: to bind it.

Each literal case costs one comparison, tried from the top, exactly like an if/elif chain. Put the common cases first in a long match.

Bind the value a match leaves over

case _: covers the remaining values but names nothing. To handle a few variants and pass every other value on, end with case _ as name:, which binds the whole matched value:

enum Event:
    Tick
    Key(str)
    Resize(i64, i64)

def describe(event: Event) -> str:
    match event:
        case Event.Tick:
            "tick"
        case Event.Key(name):
            name
        case Event.Resize(_, _):
            "resize"

def without_ticks(event: Event) -> str:
    match event:
        case Event.Tick:
            "ignored"
        case _ as other:
            describe(other)

def main() -> Result[(), IoError]:
    print(without_ticks(Event.Tick))?
    print(without_ticks(Event.Key("enter")))?
    print(without_ticks(Event.Resize(80, 24)))?
    Ok(())

ignored
enter
resize

without_ticks keeps working when Event gains a variant; only describe must name it.

The binding follows the matched value. Matching an owned value moves it into the name; matching &value or &mut value binds a shared or exclusive reference to it:

def bump(count: &mut Option[i64]) -> Result[(), OverflowError[i64]]:
    match count:
        case Some(number):
            *number = *number + 1
        case _ as empty:
            *empty = Some(1)
    Ok(())

def main() -> Result[(), IoError | OverflowError[i64]]:
    mut count: Option[i64] = Nothing
    bump(&mut count)?
    bump(&mut count)?
    print(count)?
    Ok(())

Option[i64].Some(2)

_ as name matches every value, so it is the last case and stands alone: a case after it is unreachable, and it cannot be a | alternative. The _ as is required. A bare name is rejected, because it is usually a variant written without its enum:

enum Switch:
    On
    Off

def main() -> ():
    match Switch.On:
        case On:
            pass
        case _:
            pass

a case cannot bind the whole value to the bare name `On`; bind it with `_ as On`, match any value with `_`, or qualify a variant with its enum type

Inside a payload a name alone binds, as in Event.Key(name); _ as name is only for the whole value.

Bind the value a match selects

A match at the end of a function supplies the function’s result. To use the selected value in the middle of a function, write the match as the value of a binding. The final expression of the selected case becomes the value:

enum Shape:
    Dot
    Square(i64)
    Rect(i64, i64)

def paint_cost(shape: Shape) -> Result[i64, OverflowError[i64]]:
    area = match shape:
        case Shape.Dot:
            return Ok(1)
        case Shape.Square(side):
            side * side
        case Shape.Rect(width, height):
            width * height
    Ok(area * 10)

def main() -> Result[(), IoError | OverflowError[i64]]:
    print(paint_cost(Shape.Dot)?)?
    print(paint_cost(Shape.Square(3))?)?
    print(paint_cost(Shape.Rect(2, 5))?)?
    Ok(())

1
90
100

The cases that continue must produce one type. A case may instead leave with return, break, continue, or ?, as Shape.Dot does; it then supplies no value and nothing is bound.

The same block is the value of an assignment to a mut local, a field, or a collection element, and of return. An annotation gives every case its expected type, which Nothing needs:

def half(number: i64) -> Option[i64]:
    two: Positive[i64] = 2
    return match number % two:
        case 0:
            Some(number // two)
        case _:
            Nothing

def main() -> Result[(), AllocError | IoError]:
    mut halves = [0, 0]?
    for index in range(2):
        found: Option[i64] = match index:
            case 0:
                half(8)
            case _:
                Nothing
        halves[index] = match found:
            case Some(value):
                value
            case Nothing:
                -1
    print(halves)?
    print(half(3))?
    Ok(())

[4, -1]
Option[i64].Nothing

return match returns the final expression of the selected case, so nothing after the block runs.

The block must be the whole right-hand side. Inside a larger expression it is rejected; bind it first:

def main() -> Result[(), IoError]:
    number = 3
    doubled = 2 * match number:
        case 3:
            30
        case _:
            0
    print(doubled)?
    Ok(())

a `match` block is a value only as the whole right side of a binding, a single-target assignment, or `return`; bind its value to a name first

Cases that disagree are rejected at the case that differs:

def main() -> Result[(), IoError]:
    number = 3
    label = match number:
        case 3:
            "three"
        case _:
            0
    print(label)?
    Ok(())

expected str, got i64

The reference lists the remaining rules, including why the value cannot be a reference.

Creating enum values

Payload arguments move into the enum. Constructing it adds no allocation:

enum Message:
    Empty
    Text(str)

def main() -> Result[(), IoError]:
    print(Message.Text("hello"))?
    print(Message.Empty)?
    Ok(())

Message.Text("hello")
Message.Empty

Allocations inside argument expressions, such as building a string, still return their own Result.

Match borrowed values

Use match &value to inspect an enum while retaining its owner. Payload bindings are shared references. With match &mut value, they are exclusive references and can change the original payload.

An existing enum reference can be matched directly. A function can also return a payload reference when it comes from the function’s first reference parameter:

def number(value: &Result[i64, i64]) -> &i64:
    match value:
        case Ok(payload):
            payload
        case Err(payload):
            payload

def main() -> Result[(), IoError]:
    mut outcome: Result[i64, i64] = Err(7)
    selected = number(&outcome)
    print(*selected)?
    outcome = Ok(9)
    print(number(&outcome))?
    Ok(())

7
9

Replacing outcome is allowed after selected’s last use; doing it before that use is rejected. References cannot outlive their owner.

Assign through a mutable payload reference to change the original slot, keeping its enclosing variants:

def main() -> Result[(), IoError | OverflowError[i64]]:
    mut nested: Option[Result[i64, str]] = Some(Ok(4))
    match &mut nested:
        case Some(Ok(number)):
            *number = *number + 1
        case Some(Err(_)) | Nothing:
            pass
    print(nested)?
    Ok(())

Option[Result[i64, str]].Some(Result[i64, str].Ok(5))

match &mut works for every enum, whatever its payloads contain. A copy made before the match keeps its own payload:

enum Shape:
    Circle(i64)
    Square(i64)

def main() -> Result[(), IoError | OverflowError[i64]]:
    mut shape = Shape.Circle(3)
    before = shape
    match &mut shape:
        case Shape.Circle(radius):
            *radius = *radius + 1
        case Shape.Square(side):
            *side = *side * 2
    print(shape)?
    print(before)?
    Ok(())

Shape.Circle(4)
Shape.Circle(3)

_ ignores a payload without moving it. Borrowed matching uses the same exhaustiveness checks and qualified variant names as owned matching.

Clean up owned instances

Use __del__ for cleanup that belongs to an owned instance. It runs automatically when the instance leaves scope, is replaced, or is explicitly dropped. Its bare self is an exclusive reference, like in __init__:

class Resource:
    name: str

    def __del__(self) -> ():
        drop(print("release", self.name))

class Pair:
    first: Resource
    second: Resource

    def __del__(self) -> ():
        drop(print("release pair"))

def work() -> Result[(), IoError]:
    pair = Pair(Resource("first"), Resource("second"))
    spare = Resource("spare")
    print("working")?
    Ok(())

def main() -> Result[(), IoError]:
    work()?
    print("done")?
    Ok(())

working
release spare
release pair
release first
release second
done

Locals clean up in reverse declaration order. A class’s __del__ runs first; its fields then clean up automatically in declaration order. Moving an instance transfers cleanup responsibility without running the destructor.

Each field finishes cleaning up its children before the next field begins:

class Leaf:
    name: str
    def __del__(self) -> ():
        drop(print(self.name))
class Pair:
    first: list[Leaf]
    second: Leaf
def main() -> Result[(), AllocError]:
    pairs = [Pair([Leaf("a")]?, Leaf("b"))]?
    drop(pairs)
    Ok(())

a
b

Lifecycle methods are not called directly. A class with custom cleanup, or one containing a value with custom cleanup, cannot be copied yet. A destructor cannot yield or report a recoverable error; use an explicit closing method returning Result when failures matter. Fatal traps do not run cleanup.

The lifecycle trace uses drop(print(...)) deliberately: cleanup cannot return an error, and a failed diagnostic write must not interrupt cleanup. For output that must succeed, provide an explicit fallible operation and propagate its result before leaving the scope.

Consume a value to change its state

Use self: Class when an operation finishes an object or replaces it with a different state. The method receives ownership, so the caller cannot use the old class instance again. Bare self still borrows; self: &mut Class mutates an instance that remains available to the caller.

Here a draft must be validated before it can be finished. Separate classes make invalid operation ordering a type error. Keeping Ready’s field and constructor private prevents callers from skipping validation:

pub class Draft:
    pub text: str

    pub def validate(self: Draft) -> Result[Ready, Draft]:
        if self.text == "":
            return Err(self)
        Ok(Ready(self.text))

pub class Ready:
    text: str

    pub def finish(self: Ready) -> str:
        self.text

import workflow

def main() -> Result[(), IoError]:
    draft = workflow.Draft("report")
    ready = draft.validate().unwrap()
    print(ready.finish())?
    # An error can explicitly return the draft for correction and retry.
    match workflow.Draft("").validate():
        case Ok(ready):
            print(ready.finish())?
        case Err(retry):
            mut corrected = retry
            corrected.text = "corrected"
            print(corrected.validate().unwrap().finish())?
    Ok(())

report
corrected

The unwrap calls assert that the nonempty strings in this example pass validation. For input that might fail, recover the owner using match, as the empty-draft example does. A fallible method does not automatically restore the receiver after failure. The same rule applies to a simple finalization method:

class Message:
    text: str

    def finish(self: Message) -> str:
        self.text

def main() -> ():
    message = Message("report")
    text = message.finish()
    print(message.text).unwrap()
    drop(text)

use of moved binding `message`

Ownership moves into the method before its other arguments are evaluated. Read any needed fields into locals before making the consuming call. If a later argument returns early with ?, the pending receiver is cleaned up. Inside the method, owned self is an immutable binding; move it into a mut local if you need to change fields.

This example reads a copyable string field. A transition can also move an owned field, such as a list, out of the consumed receiver into the next state:

class Pending:
    id: i64
    items: list[str]

    def ship(self: Pending) -> Shipped:
        Shipped(self.id, self.items)

class Shipped:
    id: i64
    items: list[str]

def main() -> Result[(), AllocError | IoError]:
    order = Pending(7, ["book", "pen"]?)
    shipped = order.ship()
    print(shipped.id, len(shipped.items))?
    Ok(())

7 2

self.items transfers the list without copying it, and the rest of self is cleaned up when the method returns. After a field moves out, the object cannot be used as a whole until that field is assigned again:

class Pending:
    items: list[str]

    def ship(self: Pending) -> Pending:
        items = self.items
        drop(items)
        self

def main() -> ():
    pass

use of partly moved binding `self`: `self.items` is moved; assign `self.items` before using `self` as a whole

Fields cannot move out through a reference, or out of a class that defines __del__, because its hook receives the whole object. There, keep the field initialized with Option plus replace. See moving fields for the full rules.

Consuming a value does not require callers to finish it: they can still drop it. Normal cleanup runs exactly once unless the method transfers ownership onward. Enums also accept by-value receivers, but a copyable enum is copied according to ordinary argument rules. Use affine state types when the old state must cease to be usable. See method contracts.

Borrow records in a collection

For a list of records, &items yields shared references and &mut items yields mutable references. The list cannot grow, shrink, or move during either loop:

class Score:
    value: i64

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut scores = [Score(2), Score(5)]?
    for score in &mut scores:
        score.value = score.value + 1
    print([score.value for score in &scores]?)?
    mut numbers = [10, 20]?
    for number in &mut numbers:
        *number = *number + 2
    print(numbers)?
    Ok(())

[3, 6]
[12, 22]

For large primitive-field records scanned a few fields at a time, consider columnar storage. Ordinary lists retain the full record-borrowing interface used here.

Heterogeneous collections

A heterogeneous collection holds values of different kinds. Plenty still gives it one element type: an enum or an anonymous sum describes the alternatives. The possible types are known at compile time.

Use the classes and enums you have defined to choose a representation:

An anonymous sum, written A | B, holds one value of either type. It is not a set collection: set[T] holds distinct values. An enum gives its alternatives names and can define methods; an anonymous sum needs a match to use each member’s own interface.

These techniques do not create an open-ended collection accepting any type. Adding a new kind means extending the enum or sum and handling it wherever matching must be exhaustive. Protocols constrain generic calls; they are not runtime element types such as list[MyProtocol].

Lists of different kinds of values

A list has one element type, but that type can describe alternatives. Use a wrapper enum when the alternatives form a concept in your program and share operations. Use an anonymous sum when a local choice of whole types is enough.

Give the alternatives a shared interface

A message and a status can both appear in a feed. FeedItem names that concept and keeps the dispatch in its label method:

class Message:
    text: str

    def label(self) -> str:
        self.text

enum Status:
    Ready
    Busy

    def label(self) -> str:
        match self:
            case Status.Ready:
                "ready"
            case Status.Busy:
                "busy"

enum FeedItem:
    Message(Message)
    Status(Status)

    def label(self) -> str:
        match self:
            case FeedItem.Message(message):
                message.label()
            case FeedItem.Status(status):
                status.label()

def main() -> Result[(), AllocError | IoError]:
    mut items: list[FeedItem] = []?
    items.append(FeedItem.Message(Message("hello")))?
    items.append(FeedItem.Status(Status.Ready))?
    for item in &items:
        print(item.label())?
    Ok(())

hello
ready

The wrapper can carry class instances, enum values, or other owned data. Constructing a variant moves an affine payload into it; appending moves that wrapper into the list. The loop borrows the list, and matching self borrows the active payload, so neither operation needs a copy.

Each kind has its own implementation of label, but the wrapper’s method is what lets the loop call one interface. No protocol declaration is necessary. Adding a variant makes the compiler check that the wrapper’s match handles it.

Use an anonymous sum for a local choice

If you do not need a named wrapper or its methods, declare the alternatives in the list’s element type. The annotation lets append accept either member directly:

class Message:
    text: str

enum Status:
    Ready
    Busy

def main() -> Result[(), AllocError | IoError]:
    mut items: list[Message | Status] = []?
    items.append(Message("hello"))?
    items.append(Status.Ready)?
    for item in &items:
        match item:
            case message: Message:
                print(message.text)?
            case status: Status:
                match status:
                    case Status.Ready:
                        print("ready")?
                    case Status.Busy:
                        print("busy")?
    Ok(())

hello
ready

case message: Message: selects a whole member type. Because item is a borrow, its matched payload is borrowed too. The Status member contains any of that enum’s variants, so its own match handles both.

The sum does not automatically forward methods, even if every member has a method with the same signature. Match to select a member, or choose the wrapper pattern when several callers need the same operation.

Both forms store a tag and payload inline; wrapping adds no heap allocation. List creation and growth still return allocation results, as does constructing any payload that itself needs storage. See anonymous sums and enums for the full contracts.

For implementations supplied independently of a fixed list of alternatives, see protocol objects. Each object uses an explicit heap allocation and exposes the methods of one protocol.

Sets and different kinds of values

Sets accept named enums when every payload is a supported key type: integers, bool, str, bytes, or tuples, classes, enums and anonymous sums of those types. The variant is part of the identity, so different variants with equal payloads remain distinct.

enum Selection:
    Account(i64)
    Group(str)
    All

def main() -> Result[(), AllocError | IoError]:
    mut selected: set[Selection] = set()?
    selected.add(Selection.Account(7))?
    selected.add(Selection.Group("7"))?
    selected.add(Selection.Account(7))?
    print(len(selected))?
    print(Selection.Account(7) in selected)?
    Ok(())

2
True

This is one element type with several alternatives. Enums carrying collections, floats or boxes cannot be set elements. Anonymous sums qualify when every member is a supported key type.

Class payloads

A wrapper can also carry classes whose fields are supported keys. Ordinary classes move into the set; use a borrowed probe to keep a lookup value:

class Account:
    region: str
    number: i64

enum Selection:
    Account(Account)
    Group(str)

def main() -> Result[(), AllocError | IoError]:
    selected = {Selection.Account(Account("eu", 7)), Selection.Group("editors") }?
    probe = Selection.Account(Account("eu", 7))
    print(&probe in selected)?
    for item in &selected:
        match item:
            case Selection.Account(account):
                print(account.region, account.number)?
            case Selection.Group(group):
                print(group)?
    Ok(())

True
eu 7
editors

The lookup compares fields rather than object addresses. Borrowed iteration keeps the stored keys immutable. For keys without custom cleanup, set algebra creates independent key copies; its result can outlive either input. See sets.

Keep each kind in its own set

Suppose a selection contains numeric account IDs and textual group names. Separate sets preserve both kinds without converting IDs into strings:

def main() -> Result[(), AllocError | IoError]:
    mut account_ids: set[i64] = set()?
    mut group_names: set[str] = set()?
    account_ids.add(7)?
    account_ids.add(7)?
    group_names.add("editors")?
    group_names.add("7")?
    print(len(account_ids), len(group_names))?
    print(7 in account_ids, "7" in group_names)?
    Ok(())

1 2
True True

The integer 7 and the name "7" remain distinct identities. Each set removes its own duplicates and supports the ordinary set operations. Group the two sets in a class if they need to travel together.

Use an anonymous sum

When the types themselves express the alternatives, no wrapper is needed:

def main() -> Result[(), AllocError | IoError]:
    mut selected: set[i64 | str] = {7, "editors"}?
    selected.add("7")?
    selected.add(7)?
    print(len(selected), 7 in selected, "7" in selected)?
    Ok(())

3 True True

The member type is part of each key’s identity. Every member must support structural hashing; set[i64 | f64] is rejected because floats are not keys. Use a named enum when alternatives need different meanings despite sharing a payload type. Anonymous sums use hash sets, including sums of finite enums.

Small enums without payloads

Use ordinary sets for flags or selections too. An enum with no payloads and at most 256 variants automatically gets compact bitset storage. The compiler selects a 64-, 128-, or 256-bit mask from the number of possible values:

enum Permission:
    Read
    Write
    Execute

def main() -> Result[(), AllocError | IoError]:
    mut granted = {Permission.Read}?
    granted.add(Permission.Write)?
    required = {Permission.Read, Permission.Write}?
    print(required.issubset(&granted))?
    granted.discard(Permission.Write)
    print(Permission.Write in granted)?
    Ok(())

True
False

Keep the usual ? handling: constructing a set still allocates its owner. Adding members to this representation needs no further allocation. The same programming style works for larger enums and other payload types, which use hash sets. See small enum bitsets.

Small finite payloads

Payloads can use bitsets too when the complete type has at most 256 possible values. Booleans and nested enums or tuples of these types qualify. Here State has three values: Idle, Enabled(False), and Enabled(True).

enum State:
    Idle
    Enabled(bool)

def main() -> Result[(), AllocError | IoError]:
    mut allowed = {State.Idle, State.Enabled(False)}?
    allowed.add(State.Enabled(True))?
    print(len(allowed), State.Enabled(True) in allowed)?
    Ok(())

3 True

The limit counts all possible payload combinations, regardless of how many members the set currently contains. For example, eight boolean fields have 256 combinations; adding a separate payload-free variant makes 257 and selects a hash set. Integer and string payloads use hash sets. No special container or manual integer encoding is needed.

Keys with custom cleanup

A key may define __del__, or contain a value that does. Its fields must still be supported key types. The collection owns the inserted key and runs cleanup when that owner is removed or destroyed. Borrow keys for lookup and inspection; transfer them when a second owner cannot be created.

This example logs cleanup to make ownership visible. It unwraps diagnostic printing inside the destructor because cleanup cannot return an error:

class Ticket:
    id: i64

    def __del__(self) -> ():
        print("released", self.id).unwrap()

def main() -> Result[(), AllocError | IoError]:
    mut selected = {Ticket(7)}?
    additional = {Ticket(8)}?
    selected.update(additional)?
    print(len(selected))?
    for ticket in &selected:
        print(ticket.id)?
    # Transfer the owners out of the set before destroying them.
    for ticket in selected:
        drop(ticket)
    Ok(())

2
7
8
released 7
released 8

Iteration order is unspecified. update consumes the source set; an equal incoming key is destroyed while the stored owner is retained. Use intersection_update and difference_update to filter in place, and relationship checks such as issubset to compare without copying.

union, intersection, difference, symmetric_difference, copy(selected) and dictionary keys().to_set() require independent key copies, so they reject custom cleanup, including cleanup nested inside an enum or anonymous sum. A borrowed keys() view still works. To keep dictionary keys after consuming the dictionary, use into_keys(); see dictionary snapshots and views.

Dictionaries with different kinds of values

A dictionary has one key type and one value type. The value type can be an enum wrapper or an anonymous sum, so a string key can select any of several kinds of stored data. Keys retain the narrower key-type contract: integers, bool, str, bytes, or tuples, classes, enums and anonymous sums recursively containing those types. Keys with custom cleanup can be borrowed through keys() or transferred into an owned list with into_keys(); they cannot be copied with keys().to_set(). See cleanup-bearing keys.

Give mixed values a named wrapper

An enum makes the kinds of settings explicit. Here each value carries either a retry policy class or a mode enum:

class RetryPolicy:
    attempts: i64

enum Mode:
    Fast
    Careful

enum Setting:
    Retries(RetryPolicy)
    Mode(Mode)

def main() -> Result[(), AllocError | IoError]:
    mut settings: dict[str, Setting] = {}?
    settings.insert("network", Setting.Retries(RetryPolicy(3)))?
    settings.insert("processing", Setting.Mode(Mode.Careful))?
    for name, setting in settings.items():
        match setting:
            case Setting.Retries(policy):
                print(*name, policy.attempts)?
            case Setting.Mode(mode):
                print(*name, *mode)?
    Ok(())

network 3
processing Mode.Careful

insert adds or replaces an entry and handles possible allocation with ?. The dictionary owns each wrapper and its payload. items() borrows them in insertion order, so inspecting a class payload does not copy or remove it. A wrapper can also provide shared methods, as in the list example.

For a lookup that may miss, get requires a copyable value: this Setting contains an affine class, so get cannot return it. Use get_mut to borrow an optional value for an update, or pop to remove and take ownership of it. See dictionary lookup and removal.

Use a sum for simple values

An anonymous sum avoids declaring variants when the whole types express the choice. The annotation supplies the expected type for both a literal and later insertions:

def main() -> Result[(), AllocError | IoError]:
    mut settings: dict[str, i64 | str] = {"retries": 3}?
    settings.insert("mode", "careful")?
    for name, value in settings.items():
        match value:
            case count: i64:
                print(*name, *count)?
            case text: str:
                print(*name, *text)?
    Ok(())

retries 3
mode careful

The sum admits only the listed types. If two alternatives have the same payload type but different meanings, such as seconds and attempts both stored as i64, use separate named enum variants instead: i64 | i64 is just i64.

Different kinds of keys

An anonymous sum can combine supported key types without merging their identities:

def main() -> Result[(), AllocError | IoError]:
    labels: dict[i64 | str, str] = {7: "numeric account", "7": "named account"}?
    print(labels[7], labels["7"])?
    Ok(())

numeric account named account

A named enum can represent these distinct key domains while preserving their identity:

enum Key:
    Id(i64)
    Name(str)

def main() -> Result[(), AllocError | IoError]:
    labels: dict[Key, str] = {
        Key.Id(7): "numeric account",
        Key.Name("7"): "named account",
    }?
    print(labels[Key.Id(7)], labels[Key.Name("7")])?
    Ok(())

numeric account named account

Every enum payload must itself be a supported key type. You can also keep separate dictionaries when numeric IDs and textual names are different lookup domains:

def main() -> Result[(), AllocError | IoError]:
    by_id: dict[i64, str] = {7: "numeric account"}?
    by_name: dict[str, str] = {"7": "named account"}?
    print(by_id.get(7).unwrap(), by_name.get("7").unwrap())?
    Ok(())

numeric account named account

These lookups unwrap because the example has just inserted both keys. For external input, match the Option or supply an intentional default instead. Do not merge distinct identities by converting every key to a string.

Different kinds on both sides

Keys and values can independently use sums. Only the key alternatives must satisfy the key-type contract:

def main() -> Result[(), AllocError | IoError]:
    mut settings: dict[i64 | str, i64 | str] = {7: "paused", "retries": 3}?
    settings.insert("mode", "careful")?
    print(settings[7], settings["retries"], settings["mode"])?
    Ok(())

"paused" 3 "careful"

The annotations provide the expected types for insertion and lookup. The integer key 7 remains distinct from the string key "7". Use a named enum when domain-specific variant names make the meaning clearer.

For implementations supplied independently of a fixed list of alternatives, see protocol objects. Each object uses an explicit heap allocation and exposes the methods of one protocol.

Special-purpose data structures

Choose a data structure to suit the operations your program performs most often. This section introduces collections with specialized storage and access patterns, along with the tradeoffs that make them useful.

Start with Columnar lists: keep an ordinary class-shaped interface while storing each primitive field in its own contiguous column.

For analytical queries and Parquet datasets, use Dataframes: explicit expression plans executed by an optional Polars engine. Columnar lists remain the lightweight mutable collection.

Query dataframes with Polars

Use std.dataframe when your task is an analytical query over columns or Parquet files. Plenty describes the query; a separately compiled Polars engine optimizes and executes it. This exposes native columnar processing, parallelism and SIMD without asking you to manage vector instructions. Linux binary releases include the engine beside the compiler; no local Polars build is needed. When distributing a compiled application, follow shipping dataframe applications to include its shared library and notices. These examples require it when compiled and run.

clist[T] remains useful for lightweight mutable records, a compile-time class schema and ordinary Plenty computations. A dataframe has a runtime schema and native query semantics. It is a different tool for larger analytical operations, not the default replacement for a collection.

Build a query

Copy numeric lists into named columns, create a frame, and build expressions. An expression is a native query description, not a Plenty function called once per row. ? handles query errors, separately from null values. Borrowed parameters accept values directly, so explicit & is optional here.

import std.dataframe as df

def main() -> Result[(), df.DataFrameError | AllocError | IoError]:
    readings = [18.0, 23.0, 29.0]?
    columns = [df.column_f64("temperature", readings)?]?
    data = df.frame(columns)?
    temperature = df.col("temperature")?
    warm = temperature.gt(df.lit(20.0)?)?
    aggregates = [temperature.mean()?.alias("average")?]?
    result = data.lazy()?.filter(warm)?.select(aggregates)?.collect()?
    print(result.get_f64("average", 0)?)?
    Ok(())

Option[f64].Some(26.0)

Column construction copies values in bulk. Plans borrow and share native buffers; chaining operations does not copy the whole dataset at every step. collect() executes the plan. A getter returns Result[Option[T], ...]: Nothing means a null cell, while Err means the operation failed. Bulk values_f64 and values_i64 return ordinary Plenty lists, but reject columns containing nulls. Their _nullable variants return Option elements. Strings and booleans have matching typed APIs; see Types, nulls and schemas.

Derive columns and group

Select explicit expressions and names. Group order is unspecified, so this example prints the number of groups rather than assuming which comes first.

import std.dataframe as df

def main() -> Result[(), df.DataFrameError | AllocError | IoError]:
    stations = [1, 2, 1]?
    readings = [10.0, 20.0, 30.0]?
    columns = [df.column_i64("station", stations)?, df.column_f64("reading", readings)?]?
    data = df.frame(columns)?
    derived = [df.col("reading")?.mul(df.lit(2.0)?)?.alias("adjusted")?]?
    keys = [df.col("station")?]?
    totals = [df.col("adjusted")?.sum()?.alias("total")?]?
    result = data.lazy()?.with_columns(derived)?.group_by(keys, totals)?.collect()?
    print(result.height()?)?
    data.write_parquet("readings.parquet")?
    restored = df.scan_parquet("readings.parquet")?.collect()?
    print(restored.values_f64("reading")?)?
    Ok(())

2
[10.0, 20.0, 30.0]

For an existing Parquet file, start with scan_parquet, add filters and projections, then collect. Polars can push those operations into the scan. The write above creates or overwrites its file.

Native query semantics differ from Plenty scalar arithmetic: nulls and NaN are distinct, NaN ordering differs, integer overflow is not checked like Plenty arithmetic, and parallel floating-point reductions can change rounding. Native allocation failure can abort the process. Read the reference contracts before using these operations where those distinctions matter.

Continue with Join and rank results to combine datasets, order results inside Polars and select a row window. For cleaning text, conditional values and per-group comparisons, see Clean and compare column values. Query CSV and write Parquet adds file-backed pipelines and explains when to collect or write directly.

Types, nulls and schemas

A missing reading differs from a reading of zero. Use Option elements to preserve that distinction, and keep names and flags in their native string and boolean columns.

This example keeps enabled sensors and reads their nullable values back. The expressions run in Polars; ordinary Plenty code handles the results. It needs the dataframe engine, which Linux releases include.

import std.dataframe as df

def main() -> Result[(), df.DataFrameError | AllocError | IoError]:
    names = ["north", "café", "南"]?
    enabled = [True, False, True]?
    readings: list[Option[f64]] = [Some(18.5), Some(22.0), Nothing]?
    data = df.frame([
        df.column_str("sensor", names)?,
        df.column_bool("enabled", enabled)?,
        df.column_f64_nullable("reading", readings)?
    ]?)?
    result = data.lazy()?.filter(df.col("enabled")?)?.collect()?
    print(result.values_str("sensor")?)?
    print(result.values_f64_nullable("reading")?)?
    for field in result.schema()?:
        print(field.name, field.dtype)?
    Ok(())

["north", "南"]
[Option[f64].Some(18.5), Option[f64].Nothing]
sensor std.dataframe.DType.String
enabled std.dataframe.DType.Bool
reading std.dataframe.DType.F64

Nothing is missing data; Some(""), Some(False), zero and NaN are present values. Use values_TYPE_nullable for nullable results. The plain values_TYPE methods reject nulls rather than dropping rows. Scalar get_TYPE(name, row) returns an Option inside a Result: absence and query failure are different outcomes.

For an unfamiliar file, inspect df.scan_parquet(path)?.schema()? before choosing columns or collecting. Its ordered fields describe the native runtime schema. DType.Other(description) reports a native type that Plenty cannot yet extract, such as an unsupported nested value. Inspection reads metadata as needed; collection can still encounter errors.

Keep numeric widths and unsigned identifiers

Every Plenty numeric type has matching column constructors and getters. Choose the type your data needs: a u64 identifier can exceed i64.MAX, while f32 readings use less native column memory than f64 readings. Neither needs a conversion through the default numeric types.

import std.dataframe as df

def main() -> Result[(), df.DataFrameError | AllocError | IoError]:
    data = df.frame([
        df.column_u64("device", [u64.MAX, 42u64]?)?,
        df.column_f32("reading", [18.5f32, 22.0f32]?)?
    ]?)?
    selected = data.lazy()?.filter(df.col("device")?.eq(df.lit_u64(u64.MAX)?)?)?.collect()?
    print(selected.values_u64("device")?)?
    print(selected.values_f32("reading")?)?
    Ok(())

[18446744073709551615]
[18.5]

Use column_TYPE_nullable and values_TYPE_nullable when values may be missing. Extraction checks the exact dtype; it does not widen integers or floats implicitly. An expression or aggregation can change the result’s dtype, so inspect its schema or make a deliberate cast before extracting.

Lists are copied across the native boundary. Keep filtering, grouping and sorting inside the query, then extract only the columns and rows your Plenty code needs. See the type contracts for Unicode, ownership and conversion details, then continue with Join and rank results or Clean and compare column values. For logical calendar data, see Dates and daily reports.

Store binary payloads

Use binary columns for file contents, encoded messages, or other bytes that are not necessarily text. Values use owned Bytes buffers; there is no UTF-8 conversion at the dataframe boundary. This lesson requires the optional engine.

Keep selection inside Polars, then extract only the payloads your application needs. Here, null means missing data and an empty buffer is a present payload:

import std.dataframe as df
import std.bytes as buffers
from std.bytes import Bytes, BytesError

def main() -> Result[(), df.DataFrameError | BytesError | AllocError | IoError]:
    payloads: list[Option[Bytes]] = [
        Some(buffers.from_bytes(b"\xff\0")?),
        Nothing,
        Some(buffers.empty()?)
    ]?
    data = df.frame([df.column_binary_nullable("payload", payloads)?]?)?
    matches = data.lazy()?.filter(
        df.col("payload")?.eq(df.lit_binary(b"\xff\0")?)?
    )?.collect()?
    print(matches.height()?)?
    for payload in matches.values_binary("payload")?:
        print(payload.len(), payload[0])?
    print(data.get_binary("payload", 1)?.is_none())?
    print(data.get_binary("payload", 2)?.unwrap().len())?
    Ok(())

1
2 255
True
0

Use values_binary_nullable when the selected result may contain nulls. values_binary rejects nulls; it never silently drops rows. Both return new buffers that can outlive the dataframe and be changed independently.

write_parquet and scan_parquet preserve binary values and nulls. CSV does not support binary columns. Converting a binary expression to DType.String is explicit and checks UTF-8; it is unnecessary for writing Parquet.

Binary literals accept a byte literal or borrowed view directly, including &buffer[a:b]. Column construction packs values into a temporary Bytes buffer and copies them into Polars; extraction returns independent buffers. Prefer native filtering/projection before extraction, especially for large payloads. See binary transfer details.

Lists and records inside columns

A row can contain several values or a record of related fields. Keep these values in native columns when queries will process them. Nested columns compose with the same expressions and Parquet I/O as scalar columns.

Store a list per row

Build one flat child column and supply the boundaries between rows. In this example the rows contain [8, 5], [], and [3].

import std.dataframe as df

def main() -> Result[(), df.DataFrameError | AllocError | IoError]:
    values = df.column_i64("item", [8, 5, 3]?)?
    scores = df.column_list("scores", values, [0, 2, 2, 3]?)?
    report = scores.to_frame()?.lazy()?.select([
        df.col("scores")?.list_len()?.alias("count")?,
        df.col("scores")?.list_get(-1)?.alias("last")?
    ]?)?.collect()?
    print(report.values_i64("count")?)?
    print(report.values_i64_nullable("last")?)?
    Ok(())

[2, 0, 1]
[Option[i64].Some(5), Option[i64].Nothing, Option[i64].Some(3)]

list_get returns null for an out-of-bounds index. Use nullable extraction when an empty or null list can reach the query. A null child element also remains null; it is not replaced with zero.

column_list_nullable additionally accepts a boolean per row. False marks a null list; its offsets must describe an empty range. True with an empty range is an empty list. These states remain distinct through Parquet.

Group fields into records

A child dataframe supplies the fields of a struct column. Select a field with struct_field; it stays a native expression.

import std.dataframe as df

def main() -> Result[(), df.DataFrameError | AllocError | IoError]:
    fields = df.frame([
        df.column_str("name", ["Ada", "Lin"]?)?,
        df.column_i64("score", [8, 5]?)?
    ]?)?
    people = df.column_struct("person", fields)?.to_frame()?
    result = people.lazy()?.select([
        df.col("person")?.struct_field("name")?.alias("name")?
    ]?)?.collect()?
    print(result.values_str("name")?)?
    for node in people.schema_tree()?:
        print(node.parent, node.name, node.dtype)?
    Ok(())

["Ada", "Lin"]
-1 person std.dataframe.DType.Struct
0 name std.dataframe.DType.String
0 score std.dataframe.DType.I64

The schema tree uses parent indexes: -1 is a top-level column, and both fields above belong to node 0. Lists introduce an item child, which may itself be a struct or another list.

When Plenty needs the values, frame.column(name)?.list_parts() returns native child values plus owned offsets and parent validity. Its child column is named item: use parts.values.to_frame()?.values_i64_nullable("item") for nullable integer elements. struct_parts() similarly returns a child dataframe and the parent mask. Prefer native expressions for filtering or aggregation; extracting parts is for application code that actually needs them.

Read the nested-column contracts for ownership, null semantics, reconstruction and Polars’ Parquet map representation.

Join and rank dataframe results

An order table and a price table usually have different shapes. Join them by product, derive revenue, then group and rank the results. These operations stay inside the optional Polars engine until collect().

Methods borrow their inputs automatically, including temporary expressions. The example uses named intermediate plans to keep the steps readable; each step still belongs to one lazy query.

import std.dataframe as df

def main() -> Result[(), df.DataFrameError | AllocError | IoError]:
    orders = df.frame([df.column_i64("product", [1, 2, 1, 3]?)?, df.column_i64("units", [2, 1, 3, 5]?)?]?)?
    prices = df.frame([df.column_i64("product", [1, 2]?)?, df.column_f64("price", [10.0, 25.0]?)?]?)?
    keys = [df.col("product")?]?
    joined = orders.lazy()?.join(prices.lazy()?, keys, keys, how=df.JoinKind.Left)?
    revenue = df.col("price")?.fill_null(df.lit(0.0)?)?.mul(df.col("units")?)?.alias("revenue")?
    enriched = joined.with_columns([revenue]?)?
    totals = enriched.group_by(keys, [df.col("revenue")?.sum()?.alias("total")?]?)?
    ranking = [df.SortKey(df.col("total")?, descending=True), df.SortKey(df.col("product")?)]?
    best = totals.sort(ranking)?.limit(2)?.collect()?
    print(best.values_i64("product")?)?
    print(best.values_f64("total")?)?
    Ok(())

[1, 2]
[50.0, 25.0]

The left join keeps product 3 even though it has no price. This example deliberately treats a missing price as zero with fill_null; a real application may instead reject or separately report unpriced orders. The default inner join would drop unmatched orders.

Duplicate keys produce every matching pair. The price table here has one row per product; duplicate price rows would multiply revenue contributions. The join does not validate uniqueness. Null keys do not match unless you pass nulls_equal=True.

Both key columns survive the join. Since both are named product, the right one becomes product_right; use suffix="_price" to choose another suffix. A suffix collision is an error, never silent replacement.

The ranking sorts totals descending, then product ascending to break ties. Nulls go last by default; each SortKey can specify nulls_last=False. Sorting is stable for equal keys, but a join or group has no promised input order, so use a meaningful tie-breaking key when you need reproducible output.

For pagination, replace limit(2) with slice(2, 2) to skip two rows and take up to two more. Dataframe slicing takes an offset and count, not start/stop endpoints. Negative offsets count from the end; invalid negative lengths return an error. See the query contracts.

Continue with Membership and full joins to filter by another dataset or reconcile unmatched rows from both sides.

Membership and full joins

Use a semi join to keep rows whose keys appear in another dataset, or an anti join to find keys that are absent. Both return only the left columns. They are useful for checking allowed IDs, finding missing records and filtering against a lookup table without multiplying rows.

These examples require the optional engine.

Keep matching rows or find missing ones

import std.dataframe as df

def main() -> Result[(), df.DataFrameError | AllocError | IoError]:
    orders = df.frame([
        df.column_i64("id", [1, 2, 2, 3]?)?,
        df.column_str("order", ["one", "two-a", "two-b", "three"]?)?
    ]?)?
    allowed = df.frame([df.column_i64("id", [2, 2]?)?]?)?
    keys = [df.col("id")?]?
    order = [df.SortKey(df.col("order")?)]?
    matching = orders.lazy()?.join(
        allowed.lazy()?, keys, keys, how=df.JoinKind.Semi
    )?.sort(order)?.collect()?
    missing = orders.lazy()?.join(
        allowed.lazy()?, keys, keys, how=df.JoinKind.Anti
    )?.sort(order)?.collect()?
    print(matching.values_str("order")?)?
    print(missing.values_str("order")?)?
    Ok(())

["two-a", "two-b"]
["one", "three"]

The duplicate allowed ID does not duplicate matching orders. Each left row is kept at most once; duplicate left rows would still be separate rows. No right-side columns or suffixes appear in the result.

Null keys do not match by default, so a null left key goes into the anti result. Set nulls_equal=True only when null should be an ordinary matching key. Sorting above makes presentation deterministic.

Reconcile both sides with a full join

A full join also keeps rows found only on the right. Both key columns remain, so explicitly derive a common display key if that is what your report needs.

import std.dataframe as df

def main() -> Result[(), df.DataFrameError | AllocError | IoError]:
    before = df.frame([
        df.column_i64("id", [1, 2]?)?,
        df.column_i64("price", [10, 20]?)?
    ]?)?
    after = df.frame([
        df.column_i64("id", [2, 3]?)?,
        df.column_i64("price", [25, 30]?)?
    ]?)?
    keys = [df.col("id")?]?
    joined = before.lazy()?.join(after.lazy()?, keys, keys, how=df.JoinKind.Full)?
    display_id = df.col("id")?.fill_null(df.col("id_right")?)?.alias("item")?
    result = joined.with_columns([display_id]?)?.sort([
        df.SortKey(df.col("item")?)
    ]?)?.collect()?
    print(result.values_i64("item")?)?
    print(result.values_i64_nullable("price")?)?
    print(result.values_i64_nullable("price_right")?)?
    Ok(())

[1, 2, 3]
[Option[i64].Some(10), Option[i64].Some(20), Option[i64].Nothing]
[Option[i64].Nothing, Option[i64].Some(25), Option[i64].Some(30)]

Full joins preserve duplicate matching pairs, just like inner and left joins. They do not verify key uniqueness. The nulls above describe missing sides; they are not query failures. See the join contracts for composite keys, null matching, name collisions and ordering.

Continue with Match nearby observations when a lookup should use the most recent or nearest key rather than an identical key.

Match nearby observations

An equality join requires identical keys. An as-of join instead finds the most recent, next or nearest observation. This is useful for attaching a calibration value to sensor readings or a price to an event.

Use integer keys with a unit your application defines. Here, keys represent elapsed seconds. They are ordinary i64 values, not a date/time type. These examples require the optional dataframe engine. As-of validation materializes both inputs when the query executes, including with collect_streaming; filter and select the needed columns beforehand when working with larger data.

Use the most recent calibration

The source below is already ordered. For unsorted data, sort both query inputs by their key before joining. The engine checks ascending order rather than silently producing a misleading match.

import std.dataframe as df

def main() -> Result[(), df.DataFrameError | AllocError | IoError]:
    readings = df.frame([
        df.column_i64("second", [2, 6, 12]?)?,
        df.column_f64("reading", [10.0, 20.0, 30.0]?)?
    ]?)?
    calibration = df.frame([
        df.column_i64("second", [1, 5]?)?,
        df.column_f64("offset", [0.5, 1.5]?)?
    ]?)?
    joined = readings.lazy()?.join_asof(
        calibration.lazy()?, "second", "second", tolerance=Some(3)
    )?
    corrected = df.col("reading")?.add(df.col("offset")?)?.alias("corrected")?
    result = joined.with_columns([corrected]?)?.collect()?
    print(result.values_f64_nullable("corrected")?)?
    Ok(())

[Option[f64].Some(10.5), Option[f64].Some(21.5), Option[f64].Nothing]

Backward matching is the default: calibration at second 5 can apply to a reading at second 6, but cannot apply to a reading at second 2. The final reading has no calibration within three seconds; its null offset propagates through addition. This is missing data, not a query failure. Both original key columns remain available as second and second_right for inspection.

Choose the nearest observation

Nearest matching can look into the future. Choose it deliberately when that is meaningful for your data; do not use it for a causal lookup by accident.

import std.dataframe as df

def main() -> Result[(), df.DataFrameError | AllocError | IoError]:
    events = df.frame([df.column_i64("second", [2, 4]?)?]?)?
    samples = df.frame([
        df.column_i64("sample_second", [1, 3, 5]?)?,
        df.column_str("label", ["early", "middle", "late"]?)?
    ]?)?
    result = events.lazy()?.join_asof(
        samples.lazy()?, "second", "sample_second",
        strategy=df.AsOfStrategy.Nearest, tolerance=Some(1)
    )?.collect()?
    print(result.values_str("label")?)?
    Ok(())

["middle", "late"]

Each event is equally far from two samples; nearest matching selects the greater key. AsOfStrategy.Forward always chooses the next qualifying key. For backward/forward matching, set allow_exact_matches=False when a strictly earlier/later sample is required. See as-of join contracts for duplicate keys, nulls, limits and failure behavior.

Dates and daily reports

Parse a timestamp column once, then keep calendar calculations inside the query. The example below groups events by their UTC calendar date. This is different from splitting timestamp strings or assuming every input has an identical textual layout.

These examples need the dataframe engine, which Linux releases include. utc=True declares that the input text already represents UTC; it does not convert another timezone.

import std.dataframe as df

def main() -> Result[(), df.DataFrameError | AllocError | IoError]:
    events = df.frame([
        df.column_str("text", ["2024-02-28 09:00:00", "2024-02-29 12:30:00", "2024-02-29 14:00:00"]?)?,
        df.column_i64("amount", [10, 20, 5]?)?
    ]?)?
    stamp = df.col("text")?.str_to_datetime(
        "%Y-%m-%d %H:%M:%S", df.TimeUnit.Microseconds, utc=True
    )?.alias("stamp")?
    daily = events.lazy()?.with_columns([stamp]?)?.group_by(
        [df.col("stamp")?.dt_date()?.alias("day")?]?,
        [df.col("amount")?.sum()?.alias("total")?]?
    )?.sort([df.SortKey(df.col("day")?)]?)?.select([
        df.col("day")?.dt_format("%Y-%m-%d")?.alias("day")?,
        df.col("total")?
    ]?)?.collect()?
    print(daily.values_str("day")?)?
    print(daily.values_i64("total")?)?
    Ok(())

["2024-02-28", "2024-02-29"]
[10, 25]

dt_date() retains a logical Date while grouping and sorting; formatting happens only for presentation. The chosen unit controls stored precision. Microseconds keep six fractional decimal places; milliseconds keep three and nanoseconds keep nine. Extra fractional precision is discarded toward the earlier instant, so select the unit intentionally.

Keep invalid input visible as missing data

Parsing is strict by default. Use strict=False when invalid input should become null and your application has a policy for missing data.

import std.dataframe as df

def main() -> Result[(), df.DataFrameError | AllocError | IoError]:
    source = df.frame([
        df.column_str("text", ["1970-01-01", "1969-12-31", "2001-02-29"]?)?
    ]?)?
    dates = source.lazy()?.select([
        df.col("text")?.str_to_date(strict=False)?.alias("day")?
    ]?)?.collect()?
    print(dates.values_date_days_nullable("day")?)?
    Ok(())

[Option[i32].Some(0), Option[i32].Some(-1), Option[i32].Nothing]

The raw boundary representation is days since 1970-01-01; datetimes use integer ticks with an explicit unit. In most reports, prefer calendar expressions and formatting to manipulating these representations yourself. Getters check the logical dtype and, for datetimes, the requested unit and UTC metadata. They do not silently rescale timestamps.

Use Parquet when temporal metadata should survive file round-trips. For CSV, choose an explicit text format and parse it again on input. Named timezones, offset parsing and leap seconds are outside this foundation. See the temporal contracts for nulls, calendar bounds, overflow and conversion costs.

Clean and compare column values

Keep cleaning and derived calculations inside a query so Polars can optimize them with the rest of the plan. These examples require the optional engine.

Parse values and label missing data

The explicit non-strict cast below treats invalid numeric text as missing. That is a deliberate data-cleaning policy; omit strict=False when bad input should fail the query instead.

import std.dataframe as df

def main() -> Result[(), df.DataFrameError | AllocError | IoError]:
    data = df.frame([
        df.column_str("team", ["North", "South", "NORTH"]?)?,
        df.column_str("amount", ["12", "oops", "8"]?)?
    ]?)?
    cleaned = data.lazy()?.with_columns([
        df.col("team")?.str_lower()?,
        df.col("amount")?.cast(df.DType.I64, strict=False)?
    ]?)?
    state = df.when(
        df.col("amount")?.is_null()?,
        df.lit_str("missing")?,
        df.lit_str("ready")?
    )?.alias("state")?
    result = cleaned.with_columns([state]?)?.collect()?
    print(result.values_str("team")?)?
    print(result.values_i64_nullable("amount")?)?
    print(result.values_str("state")?)?
    Ok(())

["north", "south", "north"]
[Option[i64].Some(12), Option[i64].Nothing, Option[i64].Some(8)]
["ready", "missing", "ready"]

The second with_columns sees the parsed amount. Expressions within a single with_columns all see its input schema, so separate dependent steps. when is a native conditional expression, not a short-circuiting Plenty if: both branches must be valid. It cannot guard a failing strict cast.

For literal matching, write df.col("team")?.str_contains(df.lit_str("north")?)?. The pattern is text, not a regular expression. A column expression can also supply a different pattern per row.

Compare each row with its group

A grouped aggregate produces one row per group. A window calculation instead places the group’s result alongside each original row.

import std.dataframe as df

def main() -> Result[(), df.DataFrameError | AllocError | IoError]:
    data = df.frame([
        df.column_str("team", ["north", "south", "north", "north"]?)?,
        df.column_i64("units", [2, 4, 3, 2]?)?
    ]?)?
    teams = [df.col("team")?]?
    units = df.col("units")?
    result = data.lazy()?.with_columns([
        units.sum()?.over(teams)?.alias("team_total")?,
        units.n_unique()?.over(teams)?.alias("distinct_units")?
    ]?)?.collect()?
    print(result.values_i64("team_total")?)?
    print(result.values_i64("distinct_units")?)?
    Ok(())

[7, 4, 7, 7]
[2, 1, 2, 2]

over uses the entire partition, not a running window. It maps results back to the original rows and does not sort them. Distinct counts include null as one distinct value, whereas count() counts only present values. Read the expression contracts for casting, Unicode and null semantics.

Query CSV and write Parquet

Use a lazy CSV scan when Polars should filter, derive or aggregate file-backed data. A direct Parquet sink writes the query’s output without first returning a complete dataframe to Plenty.

This example creates a small input file so it can run by itself. With real data, begin at scan_csv. The examples need the dataframe engine; run them in an empty directory: the new output methods refuse to overwrite existing files.

import std.dataframe as df

def main() -> Result[(), df.DataFrameError | AllocError | IoError]:
    readings = df.frame([
        df.column_str("station", ["001", "002", "001"]?)?,
        df.column_f64("reading", [10.0, 20.0, 30.0]?)?
    ]?)?
    readings.write_csv("readings.csv")?
    query = df.scan_csv("readings.csv", schema_overrides=Some([
        df.Field("station", df.DType.String),
        df.Field("reading", df.DType.F64)
    ]?))?
    warm = query.filter(df.col("reading")?.gt(df.lit(15.0)?)?)?
    warm.sink_parquet("warm.parquet")?
    result = df.scan_parquet("warm.parquet")?.collect_streaming()?
    print(result.values_str("station")?)?
    print(result.values_f64("reading")?)?
    Ok(())

["002", "001"]
[20.0, 30.0]

The String override keeps leading zeros in station identifiers. CSV contains text rather than a typed schema. For unfamiliar files, inspect query.schema()?. With infer_rows=0, unspecified columns stay strings, so you can validate them and choose explicit casts. The default samples 100 rows; infer_rows=-1 scans the full file for inference.

Missing values and text

A quoted empty string and an unquoted empty field have different meanings. The default writer/reader preserves that distinction. When copying a frame through CSV, pass its schema to preserve column types too.

import std.dataframe as df

def main() -> Result[(), df.DataFrameError | AllocError | IoError]:
    notes: list[Option[str]] = [Some(""), Nothing, Some("雪, café")]?
    data = df.frame([df.column_str_nullable("note", notes)?]?)?
    data.write_csv("notes.csv", separator=";")?
    restored = df.scan_csv(
        "notes.csv",
        separator=";",
        schema_overrides=Some(data.schema()?)
    )?.collect_streaming()?
    print(restored.values_str_nullable("note")?)?
    Ok(())

[Option[str].Some(""), Option[str].Nothing, Option[str].Some("雪, café")]

A custom null token is available through write_csv(null_value="NA") and scan_csv(null_value=Some("NA")). Use it only when that token cannot be a real value: even a quoted "NA" is treated as null on reading.

Streaming execution does not imply a memory bound. collect_streaming retains all final rows, and sorts, groups, joins or windows may buffer data. Prefer sink_parquet when the desired result is a file rather than a Plenty dataframe. A failed write can leave a partial new file; existing files are never overwritten by these two new output methods. See the I/O contracts for options, error timing and execution limits.

Continue with Application: a daily sales report to combine file scans, cleaning, dates, joins and exports in a complete program.

Application: a daily sales report

The repository’s examples/sales_report/ combines dataframe operations into a command-line application. It reads order lines, joins a product catalogue, separates bad records, and exports daily sales totals. The directory includes small input files, reusable query functions, a CLI and independent output checks.

Start with the engine installation. From a source checkout with the compiler and matching engine installed:

target/release/plenty --compile examples/sales_report/main.plenty -o /tmp/sales-report
target/release/plenty --compile examples/sales_report/convert.plenty -o /tmp/sales-convert
RUN=$(mktemp -d)
mkdir "$RUN/input" "$RUN/output"
/tmp/sales-convert ingest examples/sales_report/data/orders-01.csv "$RUN/input/part-01.parquet"
/tmp/sales-convert ingest examples/sales_report/data/orders-02.csv "$RUN/input/part-02.parquet"
/tmp/sales-report parquet "$RUN/input/part-*.parquet" examples/sales_report/data/products.csv "$RUN/output"
cat "$RUN/output/daily.csv"

The application prints 12 input lines, 5 accepted lines, 7 rejected lines and 4 daily groups. The resulting CSV is:

day,category,lines,total_cents
2024-02-28,books,1,1200
2024-02-29,books,2,1000
2024-02-29,games,1,2500
2024-03-01,games,1,0

It also writes daily.parquet, retaining logical Date values, and rejected.csv, retaining the original fields with rejection reasons. For a single CSV input, use sales-report csv ORDERS.csv PRODUCTS.csv OUTPUT_DIR. Only Parquet supports the quoted glob. The converter keeps the raw String columns; it does not pre-clean or calculate the report.

Follow the query through the application

Read report.plenty in this order:

1. scan_orders selects four required String columns. CSV inference is disabled so product IDs such as 001 keep their leading zeros. Parquet input uses that same raw ingestion schema.
2. catalogue checks nonempty IDs/categories and unique product IDs before joining. Duplicate reference keys would otherwise multiply sales totals.
3. classify parses UTC timestamps and integer cents non-strictly, then performs a left join. A native conditional expression assigns each row an acceptance or rejection reason. Missing prices or dates are not silently replaced with useful-looking values.
4. daily filters accepted rows, groups by calendar date and lowercased category, counts lines and sums cents. Sorting gives stable report order.
5. run exports the report and rejected records, then prints reconciliation counts. It propagates structural/query/I/O failures through its fallible entrypoint, giving a nonzero exit status.

These functions build native expressions rather than invoking Plenty once per row. Named intermediate plans make the cleaning policy readable without copying the whole dataset at each step. The classified rows are collected once so both outputs describe the same input; that is an explicit memory cost, not a promise that streaming execution bounds memory.

Amounts are already line totals, expressed as whole cents. Zero is valid; negative amounts, missing amounts and amounts above one billion cents are rejected. Together with a 100-million-line cap before aggregation, this keeps native i64 sums in range. The row cap is checked after collection and cannot protect against running out of memory while reading. Repeated order IDs are separate lines, not automatically deduplicated transactions. This is a batch reporting example, not an accounting system.

Check and ship it

Run the independent checks with the same engine installation:

python3 -B examples/sales_report/check.py --plenty target/release/plenty -v

The checks compile the actual application, compare CSV and Parquet results with Python stdlib calculations, and exercise invalid rows, duplicate keys, empty inputs and failures. Add --benchmark-rows 100000 to measure a larger generated workload, including all output writes. Python is a development dependency of these checks, not a runtime dependency of the report.

Use a new output directory for each run. Files are not overwritten, but the three writes are not one transaction: a failure may leave partial output. Publish the directory only after the process succeeds. Rejected rows are an intentional successful outcome; inspect the reconciliation counts and file.

The application README describes the exact input schema, rejection precedence, resource costs and measurement procedure. Follow shipping dataframe applications to distribute the executable with its matching engine and license notices.

Columnar lists

clist[T] makes data-oriented performance accessible through ordinary Plenty code. Declare a class normally, then choose clist[YourClass] when a large collection of its records is usually processed one or two fields at a time. You still append ordinary objects and refer to their named fields. The collection stores each field in its own packed, contiguous column.

For example, averaging temperatures does not need the station identifier from every reading. Keeping temperatures together lets a scan bring more useful values into the CPU cache with each memory access. Column pipelines make this kind of bulk calculation natural: select a field, then use the familiar fluent operations. The storage choice belongs to this collection; it does not change how the class is stored everywhere else.

This is useful as a representation as well as a container: it makes efficient execution easier to express for the programmer and easier to recognize for the compiler. Start with the access pattern you need, rather than expecting every operation on a columnar list to become faster. Gathering a complete row requires reading separate columns. The current implementation accepts only primitive fields; use ordinary lists for strings, nested objects, or borrowed references to whole rows.

For analytical expression plans, grouping and Parquet datasets, consider dataframes. Their optional Polars engine has runtime schemas and native query semantics; clist keeps a lightweight mutable collection and Plenty’s own arithmetic and type checking.

• Build and scan columnar records: reserve capacity, append records, scan a column, and update or copy a row.
• Count matching integer values: express a filter/count calculation that the compiler can accelerate with SIMD.
• Remove rows and reuse storage: take individual records or clear a batch while retaining capacity.

Build and scan columnar records

Declare a class normally, then create a clist to store its fields in separate columns. This example reserves space for three readings, averages their temperatures, and updates and copies a row:

class Reading:
    station: i64
    temperature: f64

def add(total: f64, temperature: f64) -> f64:
    total + temperature

def main() -> Result[(), AllocError | AppendError[Reading] | IoError]:
    mut readings = clist[Reading].with_capacity(3)?
    readings.append(Reading(10, 18.0))?
    readings.append(Reading(20, 21.0))?
    readings.append(Reading(30, 24.0))?
    total = readings.column(Reading.temperature).fold(0.0, add)
    print(total / f64(len(readings)))?
    readings[0].temperature = 19.0
    match readings.copy_row(0):
        case Some(reading):
            print(reading.station, reading.temperature)?
        case Nothing:
            ()
    Ok(())

21.0
10 19.0

Reading.temperature selects that field’s column. The pipeline borrows the collection and yields scalar values, so add takes f64 directly. Reserving capacity makes the three appends allocation-free after construction. Errors from append retain the submitted reading; this example propagates that error so callers can decide whether to retry.

A column pipeline is consumed once. While it remains live, the collection cannot be changed or moved. Create a new column pipeline for another pass. copy_row gathers a row’s fields from the separate columns into an independent ordinary object. It allocates nothing, but gathering all the fields can cost more than accessing a record in an ordinary list. Changing the copy does not change the stored row. Use a column for a selected-field calculation and a row copy when you actually need the complete object.

The primitive-only restriction keeps this first version’s ownership and packed storage model simple and sound. Prefer an ordinary list for strings, nested objects, row references, or workloads that usually access whole objects. Indexed field access and row copying compile to direct scalar memory operations, with bounds checks. This avoids dispatching through a generic runtime helper for each field, but does not make every access pattern faster. Use column pipelines for repeated scans when the calculation needs selected fields.

Next, count matching integer values with an automatically optimized column pipeline. See the columnar-list reference for the allocation, borrowing and representation contracts.

Count matching integer values

Write the ordinary calculation you need. For a simple comparison over an i32 or u32 column, the default optimized profile can count matches with SIMD: the CPU compares four values together. You do not choose a vector width or handle leftover rows.

class Sample:
    score: i32

def main() -> Result[(), AppendError[Sample] | IoError]:
    mut samples = clist[Sample]()
    for score in range(9):
        samples.append(Sample(i32(score)))?
    matches = samples.column(Sample.score).filter(def(x: &i32) -> bool: *x > 5i32).count()
    print(matches)?
    Ok(())

3

Use runtime bounds

Bounds do not need to be constants. Capture their scalar values to count a range:

class Sample:
    score: i32

def count_between(samples: &clist[Sample], low: i32, high: i32) -> i64:
    samples.column(Sample.score).filter(def [low, high](x: &i32) -> bool: *x >= low and *x < high).count()

def main() -> Result[(), AppendError[Sample] | IoError]:
    mut samples = clist[Sample]()
    for score in range(9):
        samples.append(Sample(i32(score)))?
    print(count_between(&samples, 2i32, 7i32))?
    Ok(())

5

[low, high] captures copies of the bounds. They can come from function arguments or parsed input. The closure keeps those values even if an original binding later changes. Write two comparisons with and; Plenty does not use chained comparison syntax.

This is the same program in normal and optimized builds. The SIMD path recognizes one comparison, or two comparisons joined by and, against constants or up to two immutable scalar captures of the column’s type. Borrowed captures, arithmetic inside the predicate, or, and extra adapters keep scalar execution. Other calculations, including the floating-point average in the previous lesson, keep ordinary scalar execution. All scans still run on one thread. See the columnar-list reference for the precise optimization limits, allocation, borrowing and representation.

Remove rows and reuse storage

Use remove(index) when you need to take one complete record out of a columnar list. It returns Some(record) or Nothing for an out-of-bounds index. Remaining records keep their order, and negative indices count from the end.

class Reading:
    station: i64
    temperature: f64

def main() -> Result[(), AllocError | AppendError[Reading] | IoError]:
    mut readings = clist[Reading].with_capacity(3)?
    readings.append(Reading(10, 18.0))?
    readings.append(Reading(20, 21.0))?
    readings.append(Reading(30, 24.0))?
    match readings.remove(1):
        case Some(reading):
            print("removed", reading.station, reading.temperature)?
        case Nothing:
            ()
    for station in readings.column(Reading.station):
        print(station)?

    capacity = readings.capacity()
    readings.clear()
    print(len(readings), readings.capacity() == capacity)?
    readings.append(Reading(40, 19.0))?
    print(readings[0].station)?
    Ok(())

removed 20 21.0
10
30
0 True
40

Removal assembles an independent ordinary object, just like copy_row, then shifts the later values left in every column. It allocates nothing, but removing near the front of a large collection moves much more data than removing the last row. Repeated front removals are a poor way to filter a whole dataset.

clear() empties all columns in constant time and retains their allocation. This is useful when processing successive batches: clear the old batch and append the next one into the same storage. Removal also retains capacity. Appends within that capacity do not allocate, although their return type still requires error handling. Use drop(readings) when you want to release the storage instead of reusing it.

Both methods require mutable access. A live column pipeline borrows the entire collection, so finish its traversal before removing rows or clearing the owner. See the reference for the complete contract and costs.

Organizing a program

Imports divide a program into source modules. pub controls which declarations other modules may use.

Split a program into modules

An import names a source file without executing it. Modules contain declarations and imports; execution starts at the application’s main. Names are private to their module unless marked pub.

Save this companion file as geometry.plenty:

pub class Point:
    pub x: i64
    pub y: i64

    pub def squared_length(self) -> Result[i64, OverflowError[i64]]:
        Ok(self.x * self.x + self.y * self.y)

pub def make_point() -> Point:
    Point(3, 4)

Save the application beside it, for example as main.plenty:

import geometry
from geometry import Point as Position

def main() -> Result[(), IoError | OverflowError[i64]]:
    point: Position = geometry.make_point()
    print(point.squared_length()?)?
    print(point.x)?
    Ok(())

25
3

import geometry makes declarations reachable through geometry.Name. from geometry import Point as Position binds just that type under a local name. You can also write import geometry as geo, then use geo.Point. Aliases refer to the same declaration. Two modules may each define Point; those are distinct types.

Imports are absolute. import tools.geometry reads tools/geometry.plenty under the source root. Directories provide namespaces and need no __init__ file. The root defaults to the entry file’s directory. If the entry file is deeper in the tree, select the root explicitly:

plenty --module-root src src/app/main.plenty
plenty --module-root src --compile src/app/main.plenty -o app
plenty --module-root src --check-module src/tools/geometry.plenty

--check checks a complete application and requires main. --check-module checks a library and its imports without that requirement.

Choose a public API

Mark each public field and method explicitly. Without __init__, the generated field constructor is public only when the class and every field are public. To keep fields private while allowing construction, declare pub def __init__:

Save this module as counter.plenty:

pub class Counter:
    value: i64

    pub def __init__(self, start: i64) -> ():
        self.value = start

    pub def increment(self: &mut Counter) -> Result[(), OverflowError[i64]]:
        self.value = self.value + 1
        Ok(())

    pub def read(self) -> i64:
        self.value

    def __del__(self) -> ():
        drop(print("counter closed"))

Application:

from counter import Counter

def main() -> Result[(), IoError | OverflowError[i64]]:
    mut count = Counter(41)
    count.increment()?
    print(count.read())?
    Ok(())

42
counter closed

The private destructor still runs automatically. Private fields and methods are accessible throughout their module, but not from another module. Reads, writes, and borrows all enforce this. Save the next module as secret.plenty:

pub class Secret:
    value: i64

    pub def __init__(self, value: i64) -> ():
        self.value = value

from secret import Secret

def main() -> Result[(), IoError]:
    item = Secret(42)
    print(item.value)?
    Ok(())

secret.Secret.value` is private

pub also applies to functions, enums, and type aliases. A public enum exposes all its variants. Public signatures cannot mention private classes or enums, even through aliases or containers. Ordinary imports are private bindings; importing a name does not re-export it. Relative imports, wildcards, circular imports, and pub import are not supported yet.

Private fields are still included in automatic printing and equality.

The lifecycle trace uses drop(print(...)) deliberately: cleanup cannot return an error, and a failed diagnostic write must not interrupt cleanup. For output that must succeed, provide an explicit fallible operation and propagate its result before leaving the scope.

Use the standard math library

The compiler includes std.math. Import it like any other module; no companion source file or download is needed. Its floating-point API accepts f64.

import std.math as math
from std.math import pi

const half_turn: f64 = f64.PI

def main() -> Result[(), AllocError | IoError | math.MathError | OverflowError[i64]]:
    print(math.sqrt(81.0)?)?
    print(math.factorial(5)?)?
    print(math.comb(5, 2)?)?
    print(math.isclose(math.radians(180.0), pi, 1e-9, 0.0)?)?
    print(pi == half_turn)?
    print(math.sqrt(-1.0) == Result[f64, math.MathError].Err(math.MathError.Domain))?
    values = [2, 3, 4]?
    print(math.sum(&values, 0)?)?
    print(math.prod(&values, 1)?)?
    match math.min_all(&values):
        case Some(value):
            print(value)?
        case Nothing:
            print("empty input")?
    match math.max_all(&values):
        case Some(value):
            print(value)?
        case Nothing:
            print("empty input")?
    print(math.round(2.5)?)?
    print(math.round(3.5)?)?
    quotient, remainder = math.divmod(-7, 3)?
    print(quotient)?
    print(remainder)?
    interval = range(1, 5)
    print(math.sum_iter(&interval, 0)?)?
    Ok(())

9.0
120
10
True
True
True
9
24
2
4
2
4
-3
2
10

? propagates mathematical errors just like I/O errors. Match on a result when you want to recover from math.MathError.Domain or math.MathError.Overflow. Integer combinatorics return u64, reporting overflow instead of wrapping. Integer sum, sum_iter, and prod return OverflowError[T], where T is the integer type; their calls need ? too. Floating-point variants such as sum_float keep IEEE behavior. floor, ceil, trunc, and round return checked i64 results. round chooses the even integer at halfway values. divmod returns an integer floor quotient and remainder with the divisor’s sign; use divmod_float for floats. Division by zero is a recoverable Domain error.

min_all and max_all borrow a list and return Nothing for an empty list. They retain the first value on ties. Floats follow the IEEE 754 standard’s minimum and maximum: -0.0 counts as less than 0.0, and any NaN makes the result Some(NaN), regardless of its position. The two-value min and max follow the same rule. sum_iter and prod_iter also borrow ranges, sets, and dictionary keys; their explicit start supplies the numeric type and the result for an empty input. The original collections remain usable.

isclose takes both tolerances explicitly. Module constants are math.pi, math.e, math.tau, math.inf, and math.nan, all f64. Import one as a value, as the example does with pi. The type constants f64.PI, f64.E, f64.TAU, f64.INF, and f64.NAN also remain available. Low-level methods such as x.sqrt() follow IEEE arithmetic and may return NaN; the imported functions provide recoverable domain errors.

Declare your own immutable constants with const name: T = value, as with half_turn. The compiler evaluates the initializer, which can combine literals, type constants, and other constants with operators, as in const full_turn: f64 = 2.0 * half_turn. Use pub const to export one from a module. See constants for the accepted expressions, static assertions, and file contents included as constants.

See the math reference for available functions and their fixed-width and numerical limits. The standard library reference lists every module.

Work with explicit SIMD lanes

Prefer ordinary pipelines for repeated column scans: the columnar-list lessons show how Plenty can accelerate them automatically. Use std.simd when the algorithm itself is clearer as a fixed set of lanes.

This example compares four measurements with one threshold, then selects the threshold for lanes below it. The mask is a vector of logical booleans; count counts its true lanes, and select chooses between already-computed values.

import std.simd as simd

def main() -> Result[(), IoError]:
    readings = simd.f32x4.Lanes(18.0f32, 21.0f32, 16.0f32, 24.0f32)
    floor = simd.splat_f32x4(20.0f32)
    below = readings.simd_lt(floor)
    adjusted = below.select(floor, readings)
    print(below.count(), adjusted.to_tuple())?
    print(readings.to_tuple())?
    Ok(())

2 (20.0, 21.0, 20.0, 24.0)
(18.0, 21.0, 16.0, 24.0)

Vectors are copyable and allocate nothing. Operations borrow their inputs and produce new values, so the original readings remain unchanged. i32x4, u32x4 and f64x2 provide the same pattern with other lane types. Mask shapes must match the vectors they select.

Use add, sub and mul for ordinary arithmetic. Integer versions return a Result with a lane-typed overflow error; propagate it with ? or handle it with match. Integer wrapping_add, wrapping_sub and wrapping_mul explicitly choose modular arithmetic. Floating sum_ordered(initial) preserves scalar addition order. Selection is eager: compute and handle both inputs before selecting between them.

The module also provides checked list loads and stores; they require a complete vector to fit and never allocate. Handle any leftover elements with a scalar loop. Ordinary lists and these initial vector values use tagged scalar storage, so explicit lanes do not promise packed storage or faster code. The default optimized profile enables supported native SIMD operations on x86-64. AArch64 currently uses the scalar implementation, which preserves the same results. See the reference for the exact operations, bounds contracts and current limits.

Measure time and wait

Import std.time for spans, clock readings, and sleep. A Duration is a nonnegative span; an Instant is a reading of a clock that never goes backwards.

from std.time import monotonic_now, sleep, milliseconds, seconds

def main() -> Result[(), AllocError | IoError | RangeError]:
    pause = milliseconds(5)
    start = monotonic_now()
    sleep(&pause)
    elapsed = monotonic_now().duration_since(&start)?
    print(elapsed.as_milliseconds() >= pause.as_milliseconds())?
    minutes = seconds(60).checked_mul(90)?
    print(minutes.as_seconds())?
    print(seconds(1) == milliseconds(1000))?
    Ok(())

True
5400
True

sleep blocks for at least the span; a busy machine can make it longer, so the example prints a comparison, not a measurement. Unit constructors take u32 counts and never fail. Arithmetic that could leave the representable range returns Result with RangeError, including a subtraction that would be negative:

from std.time import milliseconds, seconds

def main() -> Result[(), AllocError | IoError | RangeError]:
    short = milliseconds(250)
    long = seconds(1)
    match short.checked_sub(&long):
        case Ok(span):
            print(span.as_milliseconds())?
        case Err(RangeError.OutOfRange):
            print("a span cannot be negative")?
    print(short.saturating_sub(&long).is_zero())?
    print(long.checked_sub(&short)?.as_milliseconds())?
    Ok(())

a span cannot be negative
True
750

Time values are class instances, so they move. Pass them by reference, as these calls do, and they stay usable.

Wall-clock time is a different type

wall_now() returns a Timestamp: seconds and nanoseconds since the Unix epoch. The system clock can be set backwards, so the difference between two timestamps is fallible. This example builds two readings by hand to show a clock that was stepped back by two seconds:

from std.time import Timestamp, wall_now

def main() -> Result[(), AllocError | IoError | RangeError]:
    first = Timestamp(1700000010, 0)
    second = Timestamp(1700000008, 500000000)
    match second.duration_since(&first):
        case Ok(span):
            print(span.as_milliseconds())?
        case Err(RangeError.OutOfRange):
            print("the clock moved backwards")?
    print(first.duration_since(&second)?.as_milliseconds())?
    print(wall_now().seconds > first.seconds)?
    Ok(())

the clock moved backwards
1500
True

Use instants to measure elapsed time and timestamps to record when something happened. The compiler rejects mixing them:

from std.time import monotonic_now, wall_now

def main() -> Result[(), AllocError | IoError]:
    started = monotonic_now()
    print(wall_now().duration_since(&started)?.as_seconds())?
    Ok(())

expected &std.time.Timestamp, got &std.time.Instant

The module has no calendar, time-zone, or formatting support. See the time reference for every operation, and Share one deadline across waits for timeouts.

Take the most urgent item first

Import Heap from std.collections for a priority queue. pop always removes the least element, however the elements were pushed.

from std.collections import Heap

def main() -> Result[(), AllocError | IoError]:
    mut times = Heap[i64]()?
    for time in [40, 10, 30, 20]?:
        times.push(time)?
    print(times.peek(), times.len())?
    while not times.is_empty():
        match times.pop():
            case Some(value):
                print(value)?
            case Nothing:
                break
    print(times.pop())?
    Ok(())

Option[i64].Some(10) 4
10
20
30
40
Option[i64].Nothing

Construction and push return Result with AllocError. pop returns Option and transfers the element. peek returns a copy of the first element without removing it, or Nothing when the heap is empty.

Heap orders integers, floats, and strings with <. For any other element, HeapBy takes a function that says which of two elements leaves first:

from std.collections import HeapBy

class Job:
    priority: i64
    name: str

def urgent(a: &Job, b: &Job) -> bool:
    a.priority > b.priority

def main() -> Result[(), AllocError | IoError]:
    mut jobs = HeapBy(urgent)?
    jobs.push(Job(1, "sweep"))?
    jobs.push(Job(9, "deploy"))?
    jobs.push(Job(5, "review"))?
    match jobs.peek_ref():
        case Some(job):
            print("next:", job.name)?
        case Nothing:
            pass
    while not jobs.is_empty():
        match jobs.pop():
            case Some(job):
                print(job.priority, job.name)?
            case Nothing:
                break
    Ok(())

next: deploy
9 deploy
5 review
1 sweep

The heap owns its jobs; pop moves one out without copying it. A Job cannot be copied, so peek is rejected for this heap; peek_ref borrows the first job instead, as in returning a borrow that may be absent. The heap cannot change while that borrow is in use. Elements that compare equal leave in no promised order. See the module reference for costs and limits.

Find a route through a graph

std.graph stores nodes and the edges between them. UnGraph edges join two nodes both ways; DiGraph edges run from a source to a target. Each node and edge owns a value, and adding one returns a handle that names it.

from std.graph import UnGraph, GraphError

def minutes(walk: &i64) -> f64:
    f64(*walk)

def main() -> Result[(), AllocError | IoError | GraphError]:
    mut town = UnGraph[str, i64]()?
    home = town.add_node("home")?
    shop = town.add_node("shop")?
    park = town.add_node("park")?
    school = town.add_node("school")?
    town.add_edge(home, shop, 10)?
    town.add_edge(home, park, 4)?
    town.add_edge(park, shop, 3)?
    town.add_edge(shop, school, 6)?
    paths = town.dijkstra(home, &minutes)?
    for stop in paths.path(school)?:
        print(*town.node(stop))?
    print(paths.distance(school))?
    Ok(())

home
park
shop
school
Option[f64].Some(13.0)

The graph does not know what edge values mean, so dijkstra takes a function that turns one into a non-negative weight. The result answers distance and path queries for every node reachable from the start.

Handles stay valid after removals: removing park leaves shop and school naming the same places, and the path now takes the direct road.

from std.graph import UnGraph, GraphError

def minutes(walk: &i64) -> f64:
    f64(*walk)

def main() -> Result[(), AllocError | IoError | GraphError]:
    mut town = UnGraph[str, i64]()?
    home = town.add_node("home")?
    shop = town.add_node("shop")?
    park = town.add_node("park")?
    town.add_edge(home, shop, 10)?
    town.add_edge(home, park, 4)?
    town.add_edge(park, shop, 3)?
    print(town.remove_node(park))?
    print(town.contains_node(park), town.edge_count())?
    print(town.get_node_ref(park), town.get_node_ref(shop))?
    print(town.dijkstra(home, &minutes)?.distance(shop))?
    Ok(())

Option[str].Some("park")
False 1
Option[&str].Nothing Option[&str].Some("shop")
Option[f64].Some(10.0)

Using a removed handle with node or add_edge traps. When a handle may be stale, get_node_ref and get_edge_ref return Nothing instead of trapping, and get_node_mut and get_edge_mut do the same for changes. See the module reference for traversal, topological order, components, spanning trees and costs.

Encode bytes and pack numbers

Binary formats store integers at fixed widths in a stated byte order, and text channels carry binary data as hex or base64. std.encoding does both over std.bytes buffers.

import std.bytes
import std.encoding
from std.encoding import Endian

def main() -> Result[(), AllocError | IoError | std.encoding.EncodingError | std.bytes.BytesError]:
    mut frame = std.bytes.empty()?
    std.encoding.append_u16(&mut frame, 513u16, Endian.Big)?
    std.encoding.append_u32(&mut frame, 7u32, Endian.Little)?
    frame.extend(&std.bytes.from_text("hi")?)?
    print(std.encoding.hex_text(&frame)?)?
    print(std.encoding.base64_text(&frame)?)?
    print(std.encoding.base64url_text(&frame[:7])?)?
    print(std.encoding.unpack_u16(&frame, 0, Endian.Big), std.encoding.unpack_u16(&frame, 0, Endian.Little))?
    std.encoding.pack_u32(&mut frame, 2, 8u32, Endian.Little)
    print(std.encoding.unpack_u32(&frame, 2, Endian.Little), frame.len())?
    Ok(())

0201070000006869
AgEHAAAAaGk=
AgEHAAAAaA
513 258
8 8

Every integer function names its width and takes the byte order as an argument; there is no default order. Endian.Big stores the most significant byte first. The same two bytes read as 513 or 258 depending on the order you state. append_ grows the buffer by the integer’s width. pack_ overwrites bytes that already exist and never grows it. unpack_ reads at an offset.

Mixed integer and float fields

Use f32 or f64 when the format specifies IEEE 754 binary32 or binary64. The same append, overwrite, and offset rules apply. A numeric cast to an integer changes the value; these codecs preserve its float representation:

import std.bytes
import std.encoding
from std.encoding import Endian

def main() -> Result[(), AllocError | IoError | std.encoding.EncodingError]:
    mut record = std.bytes.with_capacity(14)?
    std.encoding.append_u16(&mut record, 1u16, Endian.Big)?
    std.encoding.append_f32(&mut record, 1.5f32, Endian.Big)?
    std.encoding.append_f64(&mut record, -2.5, Endian.Little)?
    print(std.encoding.hex_text(&record)?)?
    print(std.encoding.unpack_u16(&record, 0, Endian.Big))?
    print(std.encoding.unpack_f32(&record, 2, Endian.Big))?
    print(std.encoding.unpack_f64(&record, 6, Endian.Little))?
    Ok(())

00013fc0000000000000000004c0
1
1.5
-2.5

Widths count bytes, so the fields begin at offsets 0, 2, and 6. Floats need no alignment padding. The float packing reference explains signed zero, infinities, NaNs and exact bit preservation.

The codecs take a byte view: &buffer for a whole buffer, &buffer[start:stop] for part of one, or a b"..." literal. The _text forms return a str; hex_encode, base64_encode, and base64url_encode return the encoded bytes as a new buffer. base64 uses + and / and always pads with =. base64url uses - and _ and never pads.

Ordinary decoding accepts exactly one form and reports what is wrong with anything else. Nothing is skipped or repaired, including spaces and line breaks:

import std.bytes
import std.encoding
from std.encoding import Endian

def main() -> Result[(), AllocError | IoError | std.bytes.BytesError | std.encoding.EncodingError]:
    print(std.encoding.base64_from_text("aGk=")?.to_text()?)?
    print(str.repr(std.encoding.hex_from_text("abc"))?)?
    print(str.repr(std.encoding.hex_from_text("0g"))?)?
    print(str.repr(std.encoding.base64_from_text("aGk"))?)?
    print(str.repr(std.encoding.base64_from_text("aG k"))?)?
    print(str.repr(std.encoding.base64_from_text("aGl="))?)?
    print(str.repr(std.encoding.base64url_from_text("aGk="))?)?
    Ok(())

hi
Result[std.bytes.Bytes, std.encoding.EncodingError].Err(std.encoding.EncodingError.InvalidLength)
Result[std.bytes.Bytes, std.encoding.EncodingError].Err(std.encoding.EncodingError.InvalidByte(1))
Result[std.bytes.Bytes, std.encoding.EncodingError].Err(std.encoding.EncodingError.InvalidLength)
Result[std.bytes.Bytes, std.encoding.EncodingError].Err(std.encoding.EncodingError.InvalidByte(2))
Result[std.bytes.Bytes, std.encoding.EncodingError].Err(std.encoding.EncodingError.NonCanonical(2))
Result[std.bytes.Bytes, std.encoding.EncodingError].Err(std.encoding.EncodingError.InvalidPadding(3))

The number in an error is the index of the offending byte. aGl= is NonCanonical because its last symbol carries bits that belong to no byte: aGk= is the only accepted text for hi. Reading four bytes from a three-byte buffer traps. Validate untrusted record lengths before unpacking; Cursor field reads return Truncated when input can legitimately end before a field is complete.

Decoded bytes are not text. Call to_text() on the result when you expect UTF-8; it validates and can fail on its own.

Base32 and protocol-specific forms

Choose the encoding the receiving protocol expects. Base32 uses uppercase letters and digits 2 through 7, with padding. For a protocol requiring a different alphabet or no padding, build a validated encoding once and reuse it:

import std.bytes
import std.encoding

def main() -> Result[(), IoError | AllocError | std.bytes.BytesError | std.encoding.EncodingError]:
    data = std.bytes.from_text("hello")?
    print(std.encoding.base32_text(&data)?)?
    lower = std.encoding.custom("abcdefghijklmnopqrstuvwxyz234567", Nothing)?
    text = lower.text(&data)?
    print(text, lower.from_text(&text)?.to_text()?)?
    print(std.encoding.base64mime_from_text("aG Vs\r\nbG8=")?.to_text()?)?
    Ok(())

NBSWY3DP
nbswy3dp hello
hello

base32hex offers the alternate alphabet 0–9, A–V. For email body transfer, base64mime_text wraps padded base64 at 76 columns using CRLF between lines. Only the MIME decoder skips ASCII space, tab, CR and LF; other invalid characters, incorrect padding and nonzero trailing bits still fail. It does not parse MIME headers or append a final CRLF. Ordinary base64_from_text continues to reject all whitespace.

See the encoding reference for every operation, its errors, and its costs.

Take a URL apart and build one

A URL is several components joined by delimiters, and each component has its own rules about which characters may appear. std.url splits a URL into those components and puts data into one of them safely.

import std.url

def main() -> Result[(), AllocError | IoError | std.url.UrlError]:
    url = std.url.parse("https://example.com:8443/docs/a%20b?tag=x%26y&page=2#top", 2048)?
    print(url.scheme, url.path)?
    print(str.repr(&url.host)?, str.repr(&url.port)?)?
    print(str.repr(&url.userinfo)?, str.repr(&url.fragment)?)?
    match &url.query:
        case Some(query):
            for pair in &std.url.query_pairs(query)?:
                print(pair.key, "=", pair.value)?
        case Nothing:
            pass
    print(std.url.decode(&url.path)?)?
    print(url.to_string()?)?
    Ok(())

https /docs/a%20b
Option[str].Some("example.com") Option[i64].Some(8443)
Option[str].Nothing Option[str].Some("top")
tag = x&y
page = 2
/docs/a b
https://example.com:8443/docs/a%20b?tag=x%26y&page=2#top

parse takes the text and the longest length in bytes you are willing to accept. Components come back exactly as written, still percent-encoded: nothing is lowercased, decoded, or tidied, so format returns the original text. An optional component is Nothing when its delimiter is absent.

Decode a component only after the URL has been split. %26 in the query is data, and query_pairs splits at the real & before it decodes, which is why tag holds x&y.

Put data into a URL

To build a URL, encode each piece for the component it is going into, then fill in a Url:

import std.url
from std.url import Component, Pair, Url

def main() -> Result[(), AllocError | IoError | std.url.UrlError]:
    path = "/files/".concat(&std.url.encode("a/b report.txt", Component.Segment)?)?
    mut pairs = list[Pair]()?
    pairs.append(Pair("q", "fish & chips"))?
    pairs.append(Pair("lang", "en"))?
    query = std.url.query_text(&pairs)?
    url = Url("https", Nothing, Some("example.com"), Nothing, path, Some(query), Nothing)
    print(url.to_string()?)?
    print(std.url.encode("a/b", Component.Path)?, std.url.encode("a/b", Component.Segment)?)?
    Ok(())

https://example.com/files/a%2Fb%20report.txt?q=fish%20%26%20chips&lang=en
a/b a%2Fb

The Component says where the data is going. As a Segment, the / in a file name is data and is escaped; as a Path, it is a separator and is kept. query_text encodes every key and value as a QueryPart, which escapes & and =.

What is rejected

std.url follows RFC 3986 strictly and never repairs input:

import std.url
from std.url import Url

def main() -> Result[(), AllocError | IoError]:
    print(str.repr(std.url.parse("/docs/page", 2048))?)?
    print(str.repr(std.url.parse("http://example.com/a b", 2048))?)?
    print(str.repr(std.url.parse("http://example.com/100%", 2048))?)?
    print(str.repr(std.url.parse("http://good.example@evil.example@host/", 2048))?)?
    print(str.repr(std.url.parse("http://example.com:99999/", 2048))?)?
    print(str.repr(std.url.parse("http://example.com/", 10))?)?
    forged = Url("https", Nothing, Some("example.com/x"), Nothing, "", Nothing, Nothing)
    print(str.repr(forged.to_string())?)?
    Ok(())

Result[std.url.Url, std.url.UrlError].Err(std.url.UrlError.MissingScheme)
Result[std.url.Url, std.url.UrlError].Err(std.url.UrlError.InvalidByte(20))
Result[std.url.Url, std.url.UrlError].Err(std.url.UrlError.InvalidEscape(22))
Result[std.url.Url, std.url.UrlError].Err(std.url.UrlError.InvalidByte(32))
Result[std.url.Url, std.url.UrlError].Err(std.url.UrlError.InvalidPort(19))
Result[std.url.Url, std.url.UrlError].Err(std.url.UrlError.LimitExceeded)
Result[str, std.url.UrlError].Err(std.url.UrlError.InvalidByte(19))

The number is the byte offset of the problem. A URL must start with a scheme; relative references are not parsed. A second @ is an error rather than a guess about which host was meant. format checks a Url you built yourself with the same rules, so a host containing / cannot turn into a different URL.

Non-ASCII text must be percent-encoded, which encode does for you. A Unicode host name must already be in its xn-- form.

See the URL reference for the exact syntax, every operation, its errors, and its costs.

Draw random values and make secrets

Plenty has two sources of random values, and they are not interchangeable. std.random gives repeatable sequences for simulations, games, and tests. std.secrets gives unpredictable bytes from the operating system for tokens and keys.

For record and request identifiers, see std.uuid, which builds standard UUIDs from OS entropy.

Seeded generators

A generator is a value you create from a seed and own. Nothing is seeded for you and there is no shared generator behind the scenes, so the same seed always produces the same run:

import std.random

def main() -> Result[(), AllocError | IoError | std.random.RandomError]:
    mut rng = std.random.seeded(1234567u64)
    print(rng.next_u64())?
    print(rng.between(1, 7)?, rng.between(1, 7)?, rng.between(1, 7)?)?
    print(rng.next_bool(), rng.next_f64() < 1.0)?
    mut cards = ["ace", "king", "queen", "jack", "ten"]?
    rng.shuffle(&mut cards)
    print(cards)?
    print(rng.sample_indices(10, 3)?)?
    print(cards[rng.index(len(cards))?])?
    Ok(())

3504822795582309479
5 2 1
True True
["ace", "king", "ten", "queen", "jack"]
[3, 1, 9]
king

Drawing changes the generator, so it must be a mut binding. Ranges are half-open: between(1, 7) is a die roll from 1 to 6. Every bounded draw is unbiased. shuffle reorders a list in place without copying its elements. sample_indices(10, 3) picks three different positions out of ten; index your collection with them. index(count) picks one.

Because the sequence depends only on the seed, a failing simulation can be replayed exactly. state() and from_state checkpoint a generator part-way through:

import std.random

def main() -> Result[(), AllocError | IoError | std.random.RandomError]:
    mut first = std.random.seeded(42u64)
    mut second = std.random.seeded(42u64)
    print(first.next_u64() == second.next_u64())?
    (a, b, c, d) = first.state()
    mut resumed = std.random.from_state(a, b, c, d)?
    print(first.between(0, 100)? == resumed.between(0, 100)?)?
    print(str.repr(first.between(5, 5))?)?
    print(str.repr(first.below(0u64))?)?
    Ok(())

True
True
Result[i64, std.random.RandomError].Err(std.random.RandomError.EmptyRange)
Result[u64, std.random.RandomError].Err(std.random.RandomError.EmptyRange)

An empty range is an error, never a clamped or default value, because it can come from data such as an empty list. A rejected request does not advance the generator. An argument no call could accept, such as sample_indices(3, 4) asking for four of three positions, is a bug in the caller: it stops the program with a trap report.

The sequence for a seed is part of the language’s contract and does not change between Plenty versions. It is also predictable by anyone who sees a few outputs, so never use a seeded generator for a password, token, or key.

Secrets

std.secrets asks the operating system for every byte. Its results differ on every run, so this program prints sizes rather than values:

import std.bytes
import std.secrets

def main() -> Result[(), AllocError | IoError | std.bytes.BytesError | std.secrets.SecretsError]:
    token = std.secrets.token_urlsafe(32)?
    print(len(token))?
    print(len(std.secrets.token_hex(16)?))?
    key = std.secrets.token_bytes(32)?
    print(key.len())?
    print(token != std.secrets.token_urlsafe(32)?)?
    print(std.secrets.below(6u64)? < 6u64)?
    mut nonce = std.bytes.empty()?
    nonce.resize(12, 0u8)?
    std.secrets.fill(&mut nonce, 0, 12)?
    print(nonce.len())?
    print(str.repr(std.secrets.token_hex(-1))?)?
    Ok(())

43
32
32
True
True
12
Result[str, std.secrets.SecretsError].Err(std.secrets.SecretsError.Allocation(AllocError.CapacityOverflow))

The argument is a number of secret bytes, not characters: 32 bytes become 43 base64url characters or 64 hex digits. token_urlsafe is safe to put in a URL or a file name. below is an unbiased integer, for example to pick a winner.

A negative count is a size that cannot be allocated, so it returns Allocation(AllocError.CapacityOverflow).

If the system cannot supply entropy, these functions return SecretsError.Entropy. They never fall back to a weaker source, and a failed fill leaves zeros, not a partly random buffer.

To start a simulation from an unpredictable seed, pass std.secrets.random_u64()? to std.random.seeded and print the seed so the run can be repeated.

For normal, exponential or floating uniform samples, pass that generator to a std.stat distribution. Each distribution documents its draw count, and failed sampling leaves the generator unchanged.

See the random reference for the algorithm and its stability contract, and the secrets reference for the failure policy and costs.

Summarize observations and model uncertainty

Use std.stat for small numerical datasets and probability calculations. Choose a population statistic when the observations are the complete group you want to describe; choose a sample statistic when estimating the spread of a larger population from a sample.

import std.stat as stat

def main() -> Result[(), AllocError | IoError | stat.StatError]:
    measurements = [4.0, 1.0, 3.0, 2.0]?
    print(stat.mean(&measurements)?, stat.median(&measurements)?)?
    print(stat.quantiles(&measurements)?)?
    print(measurements)?
    Ok(())

2.5 2.5
[1.75, 2.5, 3.25]
[4.0, 1.0, 3.0, 2.0]

Median and quantiles copy and sort the input; mean and standard deviation do not allocate. Quantiles interpolate between observed values with the smallest and largest at probabilities zero and one. Inputs must be finite, and sample variance needs at least two observations.

Distributions model probabilities. A uniform distribution over a two-to-six second delay has accumulated one quarter of its probability by three seconds:

import std.stat as stat
import std.random as random

def main() -> Result[(), IoError | stat.StatError]:
    delays = stat.uniform(2.0, 6.0)?
    print(delays.cdf(3.0)?, delays.inverse_cdf(0.25)?)?
    mut first = random.seeded(42u64)
    mut repeated = random.seeded(42u64)
    print(delays.sample(&mut first) == delays.sample(&mut repeated))?
    bell = stat.normal()?
    print(bell.cdf(0.0)?)?
    Ok(())

0.25 3.0
True
0.5

normal(mean, sigma) and exponential(rate) also provide density, CDF, inverse CDF and sampling. Their samples can overflow and therefore return Result; failure leaves the supplied generator unchanged. Seed explicitly to reproduce a simulation, and use std.secrets for security-sensitive randomness. Normal/exponential calculations use platform math, so their last bits may differ between math-library versions.

The reference describes numeric limits, errors, costs and sampling’s fixed draw counts.

Identify records with UUIDs

Use std.uuid when records need identifiers that can be created independently, without asking a central counter. Choose v4() for a random identifier, or v7() when placing recently created records close together in a sorted index is useful. Both use operating-system entropy and report failure through Result.

import std.uuid as uuid
from std.secrets import SecretsError

def main() -> Result[(), IoError | SecretsError | RangeError]:
    request_id = uuid.v4()?
    record_id = uuid.v7()?
    print(request_id.version(), record_id.version())?
    Ok(())

Option[u8].Some(4) Option[u8].Some(7)

The identifiers change each run, so this example prints only their versions. v7 embeds a wall-clock timestamp in milliseconds. It does not promise creation order within a millisecond, or when the clock moves backwards. Use std.secrets tokens rather than UUIDs for passwords and access credentials.

Read, store and compare

Keep identifiers as Uuid values while working with them. Convert to canonical text for display, or to 16 bytes for binary storage:

import std.uuid as uuid
from std.bytes import BytesError

def main() -> Result[(), IoError | ParseError | BytesError]:
    id = uuid.parse("017F22E2-79B0-7CC3-98C4-DC0C0C07398F")?
    print(id.to_string()?)?
    raw = id.to_bytes()?
    restored = uuid.from_bytes(&raw)?
    print(raw.len(), restored == id)?
    print(id.unix_milliseconds())?
    Ok(())

017f22e2-79b0-7cc3-98c4-dc0c0c07398f
16 True
Option[u64].Some(1645557742000)

Parsing accepts either case but requires the hyphens exactly as shown. It rejects whitespace, braces and malformed digits. Formatting always produces lowercase text. The byte representation is big-endian, matching the text’s left-to-right byte order. Use to_string() explicitly: ordinary class printing is intended for inspecting fields, not interchange.

For a sorted list, borrow each UUID and use its pair of unsigned integer halves as the key. This avoids allocating a string per comparison:

import std.uuid as uuid
from std.bytes import BytesError

def uuid_key(id: &uuid.Uuid) -> (u64, u64):
    id.as_u64_pair()

def main() -> Result[(), AllocError | IoError | ParseError | BytesError]:
    mut records = [uuid.parse("017f22e2-79b1-7000-8000-000000000000")?,
                   uuid.parse("017f22e2-79b0-7cc3-98c4-dc0c0c07398f")?]?
    records.sort_by_key(uuid_key)
    for id in records:
        print(id.to_string()?)?
    Ok(())

017f22e2-79b0-7cc3-98c4-dc0c0c07398f
017f22e2-79b1-7000-8000-000000000000

UUIDs follow ordinary class ownership rules. Their comparison, parsing and numeric sorting keys need no allocation; creating output text or byte buffers does. See the reference for allocation-free writing into existing buffers and deterministic generator testing.

Summarizing a large stream

Use std.sketch when keeping every value costs too much memory and an approximate answer is useful. Keep exact data when correctness requires exact membership or counts. A sketch’s memory budget and accuracy are part of the choice.

This example counts distinct numeric customer identities, samples latency quantiles, and tracks frequent customer identities without retaining the stream:

import std.sketch as sketch
from std.sketch import SketchError
from std.bytes import BytesError

def main() -> Result[(), AllocError | IoError | SketchError | BytesError | ZeroDivisionError]:
    mut customers = sketch.hyperloglog(10)?
    mut latency = sketch.quantiles(128, seed=42u64)?
    mut frequent = sketch.frequent_items(16)?
    for index in range(1000):
        customer = u64(index % 100)
        customers.add(customer)
        latency.add(f64(index % 50))?
        frequent.add(customer)?
    print(latency.count(), latency.retained())?
    print(latency.quantile(0.0)?, latency.quantile(1.0)?)?
    print(customers.estimate() > 80.0 and customers.estimate() < 120.0)?
    Ok(())

1000 128
0.0 49.0
True

The quantile sketch retains a uniform sample and exact extrema. Its interior quantiles are sample estimates, not guaranteed rank bounds. Frequent-item queries return lower/upper count bounds, and candidates() returns possible heavy hitters. Increase capacity for better accuracy. See the reference for the different guarantees.

Skipping unnecessary lookups

A static xor filter can cheaply rule out keys before an expensive exact lookup. A positive answer still needs that lookup:

import std.sketch.xor as xor
from std.sketch import SketchError
from std.bytes import BytesError

def main() -> Result[(), AllocError | IoError | SketchError | BytesError]:
    keys = [10u64, 20u64, 30u64]?
    filter = xor.build(&keys, max_keys=100)?
    print(filter.len(), filter.contains(20u64))?
    Ok(())

3 True

For a changing set, std.sketch.cuckoo supports bounded growth and deletion. Insertion returns a layer receipt. Keep it with the real record; deletion must use that receipt and a known live occurrence, never just a positive membership test:

import std.sketch.cuckoo as cuckoo
from std.sketch import SketchError
from std.bytes import BytesError

def main() -> Result[(), AllocError | IoError | SketchError | BytesError]:
    mut filter = cuckoo.cuckoo(initial_buckets=16, max_buckets=112)?
    layer = filter.insert(42u64)?
    print(filter.contains(42u64))?
    print(filter.remove(42u64, layer)?, filter.len())?
    Ok(())

True
True 0

All three sketches and both filters provide versioned to_bytes() checkpoints and bounded readers. Save the application’s key-hashing convention and cuckoo receipts too. See xor filters and cuckoo filters before choosing one.

Draw a chart

std.plot turns data into SVG without an external plotting program. Its names follow ggplot2: a plot combines a table, mappings from column names to visual properties, and a list of layers and styling choices.

This example renders into a memory stream so the lesson creates no files:

import std.plot as gg
import std.io
import std.bytes
from std.plot import Column, PlotError
from std.bytes import BytesError

def main() -> Result[(), AllocError | IoError | PlotError | BytesError]:
    data = gg.table([
        ("hour", Column.Num([9.0, 12.0, 15.0]?)),
        ("temperature", Column.Num([16.0, 22.0, 20.0]?)),
    ]?)?
    chart = gg.ggplot(data, gg.aes("hour", "temperature"), [
        gg.geom_line(colour="navy"),
        gg.geom_point(colour="navy", size=2),
        gg.labs(title="Afternoon temperatures", x="Hour", y="Degrees C"),
        gg.theme_minimal(),
    ]?)?
    mut output = std.io.cursor(std.bytes.empty()?)
    notes = chart.write_svg(&mut output)?
    print(notes)?
    print(output.data.to_text()?.startswith("<svg"))?
    Ok(())

[]
True

For a file, replace the cursor and write_svg with notes = chart.save("temperatures.svg")?. Open the file in a browser or include it in a document. Saving borrows the chart, so you can save it again at another size. The default is 6 by 4 inches; named width, height, and units control dimensions. Only SVG is supported currently.

The distinction between mapping and setting matters. aes(colour="kind") looks up a column and creates a colour scale and legend. geom_point(colour="navy") uses one constant colour. Unknown column names fail when the plot is constructed.

Plot your own records

Typed accessors turn lists of ordinary classes into columns. Compute derived values in these accessors, where Plenty can type-check them; aes does not evaluate strings as expressions.

import std.plot as gg
import std.io
import std.bytes
from std.plot import PlotError
from std.bytes import BytesError

class Sale:
    region: str
    amount: f64

def main() -> Result[(), AllocError | IoError | PlotError | BytesError]:
    sales = [Sale("North", 12.0), Sale("South", 18.0), Sale("North", 5.0)]?
    data = gg.rows(&sales, [
        gg.text("region", def(s: &Sale) -> str: s.region)?,
        gg.num("amount", def(s: &Sale) -> f64: s.amount)?,
    ]?)?
    base = gg.ggplot(data, gg.aes("region", "amount", fill="region"), [
        gg.geom_col(),
        gg.scale_fill_manual({"North": "navy", "South": "#D55E00"}?),
        gg.theme_minimal(),
    ]?)?
    labelled = base.plus([gg.labs(title="Sales by region", y="Sales")]?)?
    mut output = std.io.cursor(std.bytes.empty()?)
    drop(labelled.write_svg(&mut output)?)
    print(len(sales), output.data.to_text()?.startswith("<svg"))?
    Ok(())

3 True

geom_col uses supplied heights and stacks rows at the same x by default. Use geom_bar with no y mapping to count rows instead, or geom_histogram(bins=20) with a continuous x mapping to count numeric intervals. For grouped bars, position=gg.position_dodge() places groups side by side.

The named palette keeps each region’s colour stable even if the input order changes. Include every observed region; extra names are allowed. For a numeric colour mapping, use gg.scale_colour_gradient(low="#132B43", high="#56B1F7") to choose endpoints instead. The legend follows the chosen colours. See manual palettes and gradients for interpolation and validation rules.

plus leaves the original plot unchanged and shares its immutable data. rows copies selected values, so the original records also remain usable. For columns you already own, table moves the lists without copying them.

Missing and non-finite mapped values are omitted, with a note returned by the renderer. Check these notes when interpreting a chart. The final example discards them deliberately because its small, fixed dataset contains no missing values. File/stream errors and allocation failures still propagate through ?. See the reference for supported layers, layout limits, and differences from the larger plotting proposal.

Combine plot layers and control axes

A summary often has different columns and fewer rows than its observations. Give that layer its own table and mapping. Use inherit_aes=False when it should not inherit grouping or other aesthetics from the observations.

import std.plot as gg
import std.io
import std.bytes
from std.plot import Column, PlotError
from std.bytes import BytesError

def main() -> Result[(), AllocError | IoError | PlotError | BytesError]:
    observations = gg.table([
        ("dose", Column.Num([1.0, 10.0, 100.0]?)),
        ("response", Column.Num([2.0, 4.0, 8.0]?)),
        ("site", Column.Text(["North", "South", "North"]?)),
    ]?)?
    reference = gg.table([
        ("dose", Column.Num([1.0, 100.0]?)),
        ("expected", Column.Num([2.0, 7.0]?)),
    ]?)?
    chart = gg.ggplot(observations, gg.aes("dose", "response", colour="site"), [
        gg.geom_point(size=2),
        gg.geom_line(data=reference, mapping=gg.aes("dose", "expected"),
                     inherit_aes=False, colour="navy"),
        gg.scale_x_log10(breaks=Some([1.0, 10.0, 100.0]?),
                         labels=Some(["1 mg", "10 mg", "100 mg"]?)),
        gg.labs(title="Observed and expected response"),
        gg.theme_minimal(),
    ]?)?
    mut output = std.io.cursor(std.bytes.empty()?)
    notes = chart.write_svg(&mut output)?
    print(notes, output.data.to_text()?.startswith("<svg"))?
    Ok(())

[] True

The line inherits no site grouping, so it connects the two reference points. Both layers train the same axes. The logarithmic x scale gives equal horizontal spacing to each tenfold increase, while breaks and labels use original doses. The explicit labels include units without changing the data.

To override only one mapping while keeping the others, use a layer argument such as mapping=gg.aes(y="expected") with the default inherit_aes=True. Every inherited name must exist in that layer’s table.

For a categorical axis, gg.scale_x_discrete(limits=Some(["South", "North"]?)) sets the display order and excludes any unlisted categories. Its labels argument can supply display names in the same order. It requires a discrete x mapping; the dose example uses a continuous one.

Use coord_cartesian(xlim=(1.0, 10.0)) to zoom while retaining all rows for statistics. A scale’s limits instead removes values before computation, which can change histogram counts. Values outside a transformation’s domain are also omitted and reported in the renderer’s notes. Check these notes when working with real input.

Long titles and labels wrap automatically. The renderer reserves space for their text boxes and checks for overlapping ticks before writing SVG. If it reports that the chart cannot fit, increase width or height, shorten the labels, or provide fewer breaks. For example, a presentation chart can use chart.write_svg(&mut output, width=10.0, height=6.0)?. Labels are never silently dropped to make the chart fit.

See position scales for the full contracts, including square-root and reversed axes, and draw a chart for file output and record accessors.

Compare panels and show ranges

Use facets to compare the same measurements across groups. Add error bars or a ribbon when your data includes lower and upper bounds. The plot draws these supplied values; calculating a confidence interval or another statistical summary is a separate step.

This example uses illustrative measurement bounds, not fitted confidence intervals:

import std.plot as gg
import std.io
import std.bytes
from std.plot import Column, PlotError
from std.bytes import BytesError

def main() -> Result[(), AllocError | IoError | PlotError | BytesError]:
    data = gg.table([
        ("day", Column.Num([1.0, 2.0, 3.0, 1.0, 2.0, 3.0]?)),
        ("value", Column.Num([2.0, 4.0, 3.0, 3.0, 5.0, 4.0]?)),
        ("lower", Column.Num([1.0, 2.0, 1.5, 2.0, 3.0, 2.5]?)),
        ("upper", Column.Num([3.0, 6.0, 4.5, 4.0, 7.0, 5.5]?)),
        ("site", Column.Text(["North", "North", "North",
                             "South", "South", "South"]?)),
    ]?)?
    chart = gg.ggplot(data, gg.aes("day", "value", ymin="lower", ymax="upper"), [
        gg.geom_ribbon(fill="blue", alpha=0.2),
        gg.geom_errorbar(colour="navy", width=0.15),
        gg.geom_line(colour="navy"),
        gg.geom_point(colour="navy"),
        gg.facet_wrap("site", ncol=2),
        gg.labs(title="Measurement ranges by site", x="Day", y="Value"),
        gg.theme_minimal(),
    ]?)?
    mut output = std.io.cursor(std.bytes.empty()?)
    notes = chart.write_svg(&mut output, width=10.0, height=4.0)?
    print(notes, output.data.to_text()?.startswith("<svg"))?
    Ok(())

[] True

Fixed axes let you compare heights directly between sites. Choose scales=gg.Scales.FreeY when each panel needs its own vertical range, but then compare the axis values rather than the visual heights. With two grouping variables, use gg.facet_grid(rows="region", cols="period").

A reference layer whose table omits site appears in every panel. Give it its own mapping with inherit_aes=False when it should not inherit aesthetics whose columns are absent; see combine plot layers. Histogram counts and bar stacks remain independent within each panel.

Both interval endpoints contribute to the axes. Missing bounds omit an error bar and interrupt a ribbon at that x; inspect the returned notes with real data. geom_linerange draws the same interval without caps. To display horizontal intervals, add coord_flip.

The larger output size gives two panels room for their labels. All panels are checked before writing SVG, so a chart that cannot fit reports an error instead of hiding labels. See facets and uncertainty and intervals for the full contracts and current limits.

Read and write JSON

std.json decodes and encodes JSON under explicit limits. It offers two levels: a value tree for documents that fit in memory, and events for documents that should not be held whole.

Parse a document into a tree

import std.json
from std.json import Json

def main() -> Result[(), AllocError | IoError | std.json.JsonError]:
    bounds = std.json.limits()
    value = std.json.parse_text("{\"name\": \"Ada\", \"tags\": [\"x\", \"y\"], \"age\": 36, \"ratio\": 0.5}", &bounds)?
    match &value:
        case Json.Object(members):
            for member in members:
                match &member.value:
                    case Json.Text(text):
                        print(member.key, "is the text", text)?
                    case Json.Int(number):
                        print(member.key, "is the integer", *number)?
                    case Json.Float(number):
                        print(member.key, "is the float", *number)?
                    case Json.Array(items):
                        print(member.key, "has", len(items), "items")?
                    case _:
                        print(member.key, "is something else")?
            print(std.json.find(members, "age"), std.json.find(members, "email"))?
        case _:
            print("not an object")?
    print(std.json.encode_text(&value, &bounds)?)?
    Ok(())

name is the text Ada
tags has 2 items
age is the integer 36
ratio is the float 0.5
Option[i64].Some(2) Option[i64].Nothing
{"name":"Ada","tags":["x","y"],"age":36,"ratio":0.5}

parse_text returns a Json value, an enum with one variant per JSON type. match is how you find out which one you have. A number written without a fraction or exponent is Json.Int; any other number is Json.Float.

An object is a list[Member] in source order, where each member has a key and a value. find returns the index of the first member with a key. Output is compact: no spaces or line breaks, and members stay in the order of the list.

Every call takes Limits. limits() gives the defaults: 64 levels of nesting, 64 MiB of input, 64 MiB of output, and duplicate keys rejected.

Errors say where

A JsonError carries a fault, the byte offset, and a line and column that both start at 1.

import std.json
from std.json import Limits

def attempt(text: &str, bounds: &Limits) -> Result[(), AllocError | IoError | std.json.JsonError]:
    match std.json.parse_text(text, bounds):
        case Ok(value):
            print("ok", std.json.encode_text(&value, bounds)?)?
        case Err(error):
            print(error.fault, "at byte", error.offset, "line", error.line, "column", error.column)?
    Ok(())

def main() -> Result[(), AllocError | IoError | std.json.JsonError]:
    mut bounds = std.json.limits()
    attempt("[1, 2,\n  oops]", &bounds)?
    attempt("[1, 2", &bounds)?
    attempt("{\"a\": 1, \"a\": 2}", &bounds)?
    attempt("[9223372036854775808]", &bounds)?
    attempt("[1] [2]", &bounds)?
    bounds.max_depth = 2
    attempt("[[1]]", &bounds)?
    attempt("[[[1]]]", &bounds)?
    Ok(())

std.json.JsonFault.UnexpectedByte at byte 9 line 2 column 3
std.json.JsonFault.UnexpectedEnd at byte 5 line 1 column 6
std.json.JsonFault.DuplicateKey at byte 9 line 1 column 10
std.json.JsonFault.NumberOutOfRange at byte 1 line 1 column 2
std.json.JsonFault.TrailingData at byte 4 line 1 column 5
ok [[1]]
std.json.JsonFault.DepthExceeded at byte 2 line 1 column 3

The decoder accepts standard JSON and nothing else: no comments, no trailing commas, one document per input. An integer that does not fit i64 is an error in the tree, never a rounded float. max_depth counts open arrays and objects, so the limit of 2 accepts [[1]] and stops at the third [.

Stream events instead of building a tree

A Decoder reports one Event at a time, and an Encoder accepts one call per event. Neither holds the document, so memory stays bounded however long the input is.

import std.bytes
import std.io
import std.json
from std.json import Event

def main() -> Result[(), IoError | AllocError | ParseError | std.json.JsonError | std.bytes.BytesError | OverflowError[i64]]:
    bounds = std.json.limits()
    mut reader = std.io.cursor(std.bytes.from_text("[{\"id\": 7, \"ok\": true}, {\"id\": 18446744073709551615}]")?)
    mut decoder = std.json.decoder(&bounds)?
    mut ids = 0
    mut expecting_id = False
    while True:
        event = std.json.read_event(&mut decoder, &mut reader)?
        match &event:
            case Event.End:
                break
            case Event.Key(name):
                expecting_id = name == "id"
            case Event.Number(text):
                if expecting_id:
                    ids += 1
                    print("id", u64.parse(text)?)?
            case _:
                pass
    print(ids, "ids in", decoder.offset(), "bytes")?

    mut encoder = std.json.encoder(&bounds)?
    encoder.start_object()?
    encoder.key("ids")?
    encoder.integer(ids)?
    encoder.key("note")?
    encoder.text("line one\nline two")?
    encoder.end_object()?
    mut out = std.io.cursor(std.bytes.empty()?)
    std.json.write_pending(&mut encoder, &mut out)?
    print(out.data.to_text()?)?
    match encoder.null():
        case Ok(_):
            print("written")?
        case Err(error):
            print(error.fault)?
    Ok(())

id 7
id 18446744073709551615
2 ids in 53 bytes
{"ids":2,"note":"line one\nline two"}
std.json.JsonFault.InvalidState

read_event pulls bytes from any std.io reader as the decoder needs them and returns Event.End after the document. Event.Number holds the number’s text exactly as written, so the program chooses the type: here u64, which holds a value the tree’s i64 cannot.

The encoder checks call order. A key outside an object, a value where a key belongs, or a second top-level value is InvalidState, so an encoder cannot produce malformed JSON. write_pending hands the bytes produced so far to a writer; call it between events to keep the buffer small.

The std.json reference lists every fault, limit, and cost.

Rendering text templates

Use std.template when the layout of a page or message is clearer as text than as a sequence of string concatenations. Register a layout once and pass values for each render. Templates cannot call your program’s functions or read files.

import std.template
from std.template import TemplateError
from std.json import Json, Member

def main() -> Result[(), TemplateError | AllocError | IoError]:
    bounds = std.template.limits()
    mut pages = std.template.engine(&bounds)?
    pages.add("layout", "<h1>{% block title %}Report{% endblock %}</h1>{% block body %}{% endblock %}")?
    pages.add("report", "{% extends 'layout' %}{% block title %}{{ title }}{% endblock %}{% block body %}<ul>{% for name in names %}<li>{{ name }}</li>{% else %}<li>No entries</li>{% endfor %}</ul>{% endblock %}")?
    values = Json.Object([
        Member("title", Json.Text("Team & friends")),
        Member("names", Json.Array([Json.Text("Ada"), Json.Text("Grace")]?)),
    ]?)
    print(pages.render("report", &values)?)?
    Ok(())

<h1>Team &amp; friends</h1><ul><li>Ada</li><li>Grace</li></ul>

The context uses the JSON value model explicitly; no class-to-template conversion happens automatically. Fields such as {{ person.name }} look up object members. A missing field returns an error rather than silently producing an empty string. An empty array takes the loop’s else branch, which is useful for empty reports.

Interpolated text is HTML-escaped by default. Keep user text in HTML text or quoted ordinary attributes. HTML escaping does not validate links or JavaScript; do not place user values in scripts, styles or tag names. For a plain-text message, call pages.render("report", &values, html=False) with a plain-text template. The safe filter deliberately disables escaping for trusted markup.

Set limits for your application before constructing the engine: for example, lower max_output for a short notification. Registration and rendering are fallible, and the example propagates those failures to the caller. Keep the engine and render it again with different values to reuse its parsed templates.

For a small fragment assembled in your program, use std.template.escape rather than a chain of string replacements. Choose HtmlContext.Text for text children or the quote-specific attribute mode for each attribute value. For example, quotes should stay literal in text but must be escaped inside a double-quoted attribute:

from std.template import escape, HtmlContext, TemplateError

def main() -> Result[(), TemplateError | AllocError | IoError]:
    label = "Say \"hello\" & smile"
    attribute = escape(&label, HtmlContext.DoubleQuotedAttribute, max_bytes=256)?
    child = escape(&label, HtmlContext.Text, max_bytes=256)?
    print(f"<button title=\"{attribute}\">{child}</button>"?)?
    Ok(())

<button title="Say &quot;hello&quot; &amp; smile">Say "hello" &amp; smile</button>

max_bytes includes the expanded entities. The helper returns ordinary text: passing its output into a template would escape it again. Keep raw values in Json.Text when using Engine.render, and use these helpers once per original value when assembling HTML directly. The context is your choice; the library does not detect HTML positions or validate URLs, scripts, styles or names.

See the std.template reference for the supported syntax, filters, inheritance rules and precise limits.

Solve systems and factor matrices

std.linalg gives you dense matrices and column vectors of f64 values. It uses faer’s numerical algorithms through an optional native engine. Install the linear algebra engine before running these examples. Matrix construction and element access work without it.

Solve a linear system

Pass matrix entries in row order. Use solve to find x in A x = b:

import std.linalg as la

def main() -> Result[(), AllocError | IoError | la.LinalgError]:
    a = la.matrix(2, 2, &[3.0, 1.0, 1.0, 2.0]?)?
    b = la.vector(&[9.0, 8.0]?)?
    x = a.solve(&b)?
    print(x.get(0, 0)?, x.get(1, 0)?)?
    predicted = (a * x)?
    residual = (predicted - b)?
    print(residual.to_list()?)?
    Ok(())

2.0 3.0
[0.0, 0.0]

Both inputs are preserved. The result is a two-row, one-column matrix. For several right-hand sides with the same a, compute factor = a.lu()? once, then call factor.solve(&b)? for each. This reuses the expensive factorization.

a * x is a matrix product, so it also applies a matrix to a column vector. Addition and subtraction combine corresponding entries of equal-shaped matrices. The parentheses in (predicted - b)? propagate the operation’s error. A small residual is useful evidence about a solve; for general floating-point inputs, compare it with a tolerance appropriate to your data.

Scale with (2.0 * x)? or x.scale(2.0)?, and negate with (-x)?. Scalar multiplication currently puts the scalar on the left: x * 2.0 is unsupported. These operations preserve their inputs and allocate new results. There is no automatic fusion of a chain or fallible +=; use an explicit assignment such as x = (x + adjustment)? with a mutable binding.

Inspect a low-rank approximation

SVD separates a matrix into two orthogonal factors and a list of singular values. Small singular values indicate directions that contribute little:

import std.linalg as la

def main() -> Result[(), AllocError | IoError | la.LinalgError]:
    a = la.diagonal(&[4.0, 2.0, 0.01]?)?
    (u, values, v) = a.svd()?
    print(values)?
    print(u.rows(), u.cols(), v.rows(), v.cols())?
    Ok(())

[4.0, 2.0, 0.01]
3 3 3 3

To reconstruct, create d = la.diagonal(&values)? and vt = v.transpose()?, then compute scaled = (u * d)? and reconstructed = (scaled * vt)?. For rectangular inputs the factors have only min(rows, cols) columns. qr, cholesky, eigh, and eig provide other decompositions; their contracts are in the linear algebra reference.

All matrix-building operations are fallible. Check shapes and handle errors normally with ?. Floating-point calculations are approximate: compare residuals with a tolerance appropriate to your data, not exact factor entries. A successful solve does not guarantee accuracy for a nearly singular matrix.

Hash and sign bytes

std.crypto computes BLAKE3, SHA-256 and SHA-512 digests and keyed tags over std.bytes buffers, and compares secrets in constant time. For AEAD encryption and public-key signatures, see Encrypt and authenticate bytes.

Digests

A digest is a fixed-size fingerprint of some bytes. The one-shot functions take a whole buffer; a Digest takes input in pieces, which gives the same result as hashing the pieces joined together:

import std.bytes
import std.crypto
import std.encoding
from std.crypto import Algorithm

type CryptoBufferError = std.encoding.EncodingError | std.crypto.CryptoError | std.bytes.BytesError

def main() -> Result[(), AllocError | IoError | CryptoBufferError]:
    data = std.bytes.from_text("abc")?
    digest = std.crypto.sha256(&data)?
    print(digest.len())?
    print(std.encoding.hex_text(&digest)?)?
    mut hasher = std.crypto.digest(Algorithm.Sha256)?
    hasher.update_text("a")?
    hasher.update_text("bc")?
    print(std.crypto.equal(&hasher.finish()?, &digest))?
    print(str.repr(hasher.update_text("more"))?)?
    Ok(())

32
ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
True
Result[(), std.crypto.CryptoError].Err(std.crypto.CryptoError.Finished)

finish ends a digest. Feeding it afterwards is the error Finished, not a new hash; make a new Digest instead. update(data, start, stop) takes a range of a buffer, so a large input can be hashed while it is read, without first collecting it in memory.

BLAKE3

For BLAKE3, choose Algorithm.Blake3 or the one-shot blake3 function:

import std.bytes
import std.crypto
from std.crypto import Algorithm

def main() -> Result[(), IoError | AllocError | std.bytes.BytesError | std.crypto.CryptoError]:
    data = std.bytes.from_text("hello world")?
    expected = std.crypto.blake3(&data)?
    mut hasher = std.crypto.digest(Algorithm.Blake3)?
    hasher.update_text("hello ")?
    hasher.update_text("world")?
    print(expected.len(), std.crypto.equal(&hasher.finish()?, &expected))?
    Ok(())

32 True

BLAKE3 also has a native keyed hash with exactly 32 key bytes and a key derivation mode. Use blake3_keyed_hasher(key) for a Mac with the same update and verify methods used for HMAC below. It is a distinct algorithm: hmac(Algorithm.Blake3, key) reports UnsupportedAlgorithm. See the BLAKE3 reference for key derivation contexts, allocation costs and limits.

Signing with HMAC

A digest proves nothing about who made it: anyone can hash a message. An HMAC tag mixes in a secret key, so only a holder of the key can produce a tag that verifies:

import std.bytes
import std.crypto
import std.encoding
from std.bytes import Bytes
from std.crypto import Algorithm

def sign(key: &Bytes, message: &str) -> Result[Bytes, AllocError | IoError | std.crypto.CryptoError]:
    mut mac = std.crypto.hmac(Algorithm.Sha256, key)?
    mac.update_text(message)?
    Ok(mac.finish()?)

def check(key: &Bytes, message: &str, tag: &Bytes) -> Result[bool, AllocError | IoError | std.crypto.CryptoError]:
    mut mac = std.crypto.hmac(Algorithm.Sha256, key)?
    mac.update_text(message)?
    Ok(mac.verify(tag)?)

type CryptoBufferError = std.encoding.EncodingError | std.crypto.CryptoError | std.bytes.BytesError

def main() -> Result[(), AllocError | IoError | CryptoBufferError]:
    key = std.bytes.from_text("server key")?
    tag = sign(&key, "user=ada")?
    print(std.encoding.hex_text(&tag[:8])?)?
    print(check(&key, "user=ada", &tag)?)?
    print(check(&key, "user=bob", &tag)?)?
    other = std.bytes.from_text("another key")?
    print(check(&other, "user=ada", &tag)?)?
    Ok(())

8f60a639ef523af7
True
False
False

Check a tag with verify, never by finishing and comparing with ==. == stops at the first differing byte, so how long it takes reveals how much of a forged tag was right. verify and std.crypto.equal take the same time wherever the bytes differ.

A real key should be secret and random: make one with std.secrets.token_bytes(32) from Randomness and secrets rather than from text.

See the crypto reference for the guarantees, costs, and what the module does not provide.

Encrypt and authenticate bytes

std.crypto supplies authenticated encryption and public-key operations over Bytes. Use a defined protocol for exchanged messages: encryption alone does not manage identities, replays, message framing, or keys.

Encrypt one message

AEAD encryption protects both the message and associated data such as a protocol header. The associated data stays readable, but changing it makes verification fail. A recipient must have the same secret key, nonce, and associated data.

This example creates a fresh key for one message. When reusing a key, the application must ensure it never repeats a nonce, including across restarts. The API does not track that for you.

import std.bytes
import std.crypto
import std.secrets
from std.crypto import AeadAlgorithm

type BufferError = std.bytes.BytesError | std.crypto.AdvancedError | std.secrets.SecretsError

def main() -> Result[(), IoError | AllocError | BufferError]:
    key = std.secrets.token_bytes(32)?
    nonce = std.secrets.token_bytes(12)?
    header = std.bytes.from_text("example-v1")?
    mut message = std.bytes.from_text("meet at noon")?
    std.crypto.seal_in_place(AeadAlgorithm.ChaCha20Poly1305, &key, &nonce, &header, &mut message)?
    # The buffer now holds ciphertext followed by a 16-byte tag.
    print(message.len())?
    std.crypto.open_in_place(AeadAlgorithm.ChaCha20Poly1305, &key, &nonce, &header, &mut message)?
    print(message.to_text()?)?
    Ok(())

28
meet at noon

Opening returns an error and zeros the buffer if authentication fails; do not use its contents after an error. The ? above propagates that error. Reserve 16 extra bytes before sealing when the buffer needs to be reused without allocation. Opening never allocates.

Sign with a private seed

An Ed25519 signature allows someone with the public key to check a message without knowing the signing seed. The seed remains secret. A verifier also needs an authenticated source for the public key: accepting any key supplied alongside the signature proves no identity.

import std.bytes
import std.crypto
import std.secrets

type SigningError = std.bytes.BytesError | std.crypto.AdvancedError | std.secrets.SecretsError

def main() -> Result[(), IoError | AllocError | SigningError]:
    seed = std.secrets.token_bytes(32)?
    public_key = std.crypto.ed25519_public_key(&seed)?
    message = std.bytes.from_text("release manifest")?
    signature = std.crypto.ed25519_sign(&seed, &message)?
    print(std.crypto.ed25519_verify(&public_key, &message, &signature)?)?
    changed = std.bytes.from_text("modified manifest")?
    print(std.crypto.ed25519_verify(&public_key, &changed, &signature)?)?
    Ok(())

True
False

Signing can reuse its seed. Keys and signatures have fixed lengths; malformed lengths are errors, while a well-sized invalid signature returns False. A public key that anyone could sign for, one of small order, is the error SmallOrderKey.

Derive a key after an exchange

Ephemeral X25519 keys can each perform one agreement. Exchange their public keys first, authenticate the exchange through the application’s protocol, and derive an application key with HKDF. The example runs both peers locally; it demonstrates agreement and key derivation, without providing a network authentication protocol.

import std.bytes
import std.crypto

def main() -> Result[(), IoError | AllocError | std.bytes.BytesError | std.crypto.AdvancedError]:
    mut alice = std.crypto.x25519()?
    mut bob = std.crypto.x25519()?
    alice_public = alice.public_key()?
    bob_public = bob.public_key()?
    alice_shared = alice.agree(&bob_public)?
    bob_shared = bob.agree(&alice_public)?
    salt = std.bytes.empty()?
    context = std.bytes.from_text("example-v1 message key")?
    alice_key = std.crypto.hkdf_sha256(&salt, &alice_shared, &context, 32)?
    bob_key = std.crypto.hkdf_sha256(&salt, &bob_shared, &context, 32)?
    print(std.crypto.equal(&alice_key, &bob_key))?
    Ok(())

True

An agreement attempt consumes the private key even if the peer is rejected; length and allocation errors leave it usable. HKDF separates key material by purpose using context; it is not a password hashing function. None of these byte buffers is automatically scrubbed when dropped. See the key material and allocation contracts before storing secrets or designing a protocol.

Log structured events

std.log records events: a level, a message, and typed fields. Where the events go is up to the program. There is no global logger; you build one around a sink and pass it to the code that logs.

A logger and a sink

A text sink writes each event as one line of key=value pairs to any std.io writer. This one writes to standard output so the lines appear below; a command-line tool would use std.io.stderr() instead:

import std.io
import std.log
from std.log import Level, Clock

def main() -> Result[(), AllocError | IoError | std.log.LogError]:
    sink = std.log.text_sink(std.io.stdout(), 1024)?
    mut log = std.log.logger(sink, Level.Info, Clock.Off)
    log.info("listening", [std.log.integer("port", 8080), std.log.text("host", "db.local")]?)?
    log.debug("not shown", []?)?
    log.warn("slow request", [std.log.floating("seconds", 1.5), std.log.boolean("retried", True)]?)?
    print(log.emitted(), log.filtered())?
    Ok(())

level=info msg="listening" port=8080 host="db.local"
level=warn msg="slow request" seconds=1.5e0 retried=true
2 1

The threshold Level.Info drops the debug event before it reaches the sink. Text values are quoted and escaped, so one event is always one line. Clock.Off leaves out the time; Clock.Wall stamps each event with the current wall-clock time.

The fields of a dropped event were still built. When a field is costly to compute, ask first with log.enabled(&Level.Debug).

Passing a logger to a library

Code that logs takes the logger as a parameter. Making it generic over the sink lets each caller pick the destination:

import std.log
from std.log import Level, Clock, Logger

def connect[S](log: &mut Logger[S], attempts: i64) -> Result[(), AllocError | std.log.LogError | OverflowError[i64]]:
    for attempt in range(attempts):
        log.warn("retrying", [std.log.integer("attempt", attempt + 1)]?)?
    log.info("connected", []?)?
    Ok(())

def main() -> Result[(), AllocError | IoError | std.log.LogError | AllocError | OverflowError[i64]]:
    mut log = std.log.logger(std.log.memory_sink(10)?, Level.Trace, Clock.Off)
    connect(&mut log, 2)?
    for event in &log.sink.events:
        print(std.log.level_name(&event.level), event.message, len(event.fields))?
    Ok(())

warn retrying 1
warn retrying 1
info connected 0

A memory sink keeps events in a list, which suits tests. It holds at most the capacity it was given; after that, logging returns the error Full and the event is dropped.

Threads

Threads do not share one logger. Each builds its own around a channel sink, and one thread writes the queued events out. A channel sink never waits: when the queue is full, the event is dropped with Full, so slow output cannot stall the rest of the program. See the log reference for channel_sink, share, and drain.

Read and write TOML

std.toml parses TOML 1.0 documents, such as configuration files and project manifests, into a value tree, and writes a tree back as TOML text. Every call takes explicit limits.

Parse a configuration file

import std.toml
from std.toml import Entry, Toml

def show(entries: &list[Entry], indent: &str) -> Result[(), AllocError | IoError]:
    for entry in entries:
        name = (indent + entry.key)?
        match &entry.value:
            case Toml.Table(inner):
                print((name + ":")?)?
                show(inner, &(indent + "  ")?)?
            case Toml.Text(text):
                print(name, "is the text", text)?
            case Toml.Int(number):
                print(name, "is the integer", *number)?
            case Toml.Array(items):
                print(name, "has", len(items), "items")?
            case Toml.DateTime(moment):
                print(name, "is a date in", moment.year)?
            case _:
                print(name, "is something else")?
    Ok(())

def main() -> Result[(), AllocError | IoError | std.toml.TomlError]:
    bounds = std.toml.limits()
    text = "# Service settings\ntitle = \"cache\"\n\n[server]\nhost = \"0.0.0.0\"\nport = 8080\n\n[server.tls]\nenabled = true\n\n[[backend]]\nurl = \"http://a.internal\"\n\n[[backend]]\nurl = \"http://b.internal\"\n\n[release]\ndate = 2026-10-01\n"
    value = std.toml.parse_text(text, &bounds)?
    match &value:
        case Toml.Table(root):
            show(root, "")?
            print(std.toml.find(root, "server"), std.toml.find(root, "client"))?
        case _:
            print("a document is always a table")?
    Ok(())

title is the text cache
server:
  host is the text 0.0.0.0
  port is the integer 8080
  tls:
    enabled is something else
backend has 2 items
release:
  date is a date in 2026
Option[i64].Some(1) Option[i64].Nothing

A document is always a Toml.Table: a list[Entry] in source order, where each entry has a key and a value. [server] and [server.tls] become nested tables, and each [[backend]] adds one table to the array backend. find returns the index of the first entry with a key.

Toml has one variant per TOML type: Bool, Int, Float, Text, DateTime, Array, and Table. Integers are i64. A DateTime holds the date and time fields, its offset from UTC in minutes, and a kind that says which parts the text gave: an offset date-time, a local date-time, a local date, or a local time.

Errors say where

A TomlError carries a fault, the byte offset, and a line and column that both start at 1.

import std.toml
from std.toml import Limits

def attempt(text: &str, bounds: &Limits) -> Result[(), IoError]:
    match std.toml.parse_text(text, bounds):
        case Ok(_):
            print("ok")?
        case Err(error):
            print(error.fault, "at line", error.line, "column", error.column)?
    Ok(())

def main() -> Result[(), AllocError | IoError]:
    bounds = std.toml.limits()
    attempt("name = \"Tom\"\nname = \"Pradyun\"", &bounds)?
    attempt("[fruit]\na = 1\n[fruit]\nb = 2", &bounds)?
    attempt("point = { x = 1 }\npoint.y = 2", &bounds)?
    attempt("port = 08080", &bounds)?
    attempt("day = 2026-02-29", &bounds)?
    attempt("key = \"unterminated", &bounds)?
    Ok(())

std.toml.TomlFault.DuplicateKey at line 2 column 1
std.toml.TomlFault.DuplicateTable at line 3 column 1
std.toml.TomlFault.KeyConflict at line 2 column 1
std.toml.TomlFault.InvalidNumber at line 1 column 8
std.toml.TomlFault.InvalidDateTime at line 1 column 7
std.toml.TomlFault.UnexpectedEnd at line 1 column 20

TOML forbids defining a key or table twice, and an inline table such as { x = 1 } is complete as written, so point.y cannot add to it. Integers may not have leading zeros, and dates must exist. An error about a key or a table points at the start of the line that repeats it.

Write a tree as TOML

import std.toml
from std.toml import Entry, Toml

def main() -> Result[(), AllocError | IoError | std.toml.TomlError]:
    bounds = std.toml.limits()
    mut package = list[Entry]()?
    package.append(Entry("name", Toml.Text("player")))?
    package.append(Entry("version", Toml.Text("0.1.0")))?
    mut authors = list[Toml]()?
    authors.append(Toml.Text("Ada"))?
    package.append(Entry("authors", Toml.Array(authors)))?
    mut root = list[Entry]()?
    root.append(Entry("package", Toml.Table(package)))?
    root.append(Entry("manifest-version", Toml.Int(1)))?
    text = std.toml.encode_text(&Toml.Table(root), &bounds)?
    print(text.rstrip()?)?
    Ok(())

manifest-version = 1

[package]
name = "player"
version = "0.1.0"
authors = ["Ada"]

The writer puts each table’s plain keys first and its tables after them as [section] headers, because a key written after a header would belong to that header’s table. Parsing the output gives back the same values. The writer does not keep comments or the original layout, so it suits generated files rather than editing a file a person maintains.

Update a manifest while keeping comments

For a file maintained by a person, use a Document. Replacing a value keeps the surrounding spelling and comments:

import std.toml
from std.toml import Toml

def main() -> Result[(), AllocError | IoError | std.toml.TomlError]:
    source = "# release settings\n[package]\nversion = '0.1.0' # public version\n"
    mut document = std.toml.document_text(source, &std.toml.limits())?
    document.set(&["package", "version"]?, &Toml.Text("0.2.0"))?
    document.insert(&["package", "publish"]?, &Toml.Bool(False))?
    print(document.text()?.rstrip()?)?
    Ok(())

# release settings
[package]
version = "0.2.0" # public version
publish = false

Paths list decoded keys, so a key containing a dot is one list element. get reads an owned value; remove deletes a key or a whole section. Failed edits leave the document unchanged. Arrays and inline tables are replaced as whole values; this API does not edit individual array rows or inline fields. See the editing reference for the exact preservation rules and costs.

The std.toml reference lists every fault, limit, and cost.

Compress bytes and streams

std.compress reads and writes gzip, zlib, raw DEFLATE and Brotli data. Whole buffers go through compress and decompress; streams go through a Compressor writer and a Decompressor reader from std.io.

Whole buffers

compress takes a format, the data, and a level from 0 (fastest) to 9 (smallest). decompress takes a limit on the output size and fails rather than produce more:

import std.bytes
import std.compress
from std.compress import Format

def main() -> Result[(), AllocError | IoError | std.compress.CompressError | std.bytes.BytesError]:
    mut text = std.bytes.empty()?
    for _ in range(0, 100):
        text.extend(&std.bytes.from_text("to be or not to be ")?)?
    packed = std.compress.compress(Format.Gzip, &text, 6)?
    print(text.len())?
    print(packed.len())?
    plain = std.compress.decompress(Format.Gzip, &packed, 10000)?
    print(plain == text)?
    print(str.repr(std.compress.decompress(Format.Gzip, &packed, 1000))?)?
    Ok(())

1900
59
True
Result[std.bytes.Bytes, std.compress.CompressError].Err(std.compress.CompressError.LimitExceeded)

Repetitive text shrinks a lot. That is also the danger in decompressing: a small input can expand a thousandfold. Always choose the limit from the memory the program can spend, never from the size of the input.

Brotli

Use Format.Brotli for Brotli files or HTTP br bodies. It has the same functions and stream wrappers, with quality levels 0–11 instead of 0–9. Quality 5 is a useful starting point. Always choose the decoded-output limit from your application’s budget, independently of the compressed size.

import std.bytes
import std.compress
from std.compress import Format

def main() -> Result[(), IoError | AllocError | std.bytes.BytesError | std.compress.CompressError]:
    source = std.bytes.from_text("a small Brotli message")?
    packed = std.compress.compress(Format.Brotli, &source, 5)?
    restored = std.compress.decompress(Format.Brotli, &packed, 1024)?
    print(restored.to_text()?)?
    Ok(())

a small Brotli message

Brotli allocates working memory during streaming and has no checksum; the output limit does not cap all codec memory. For HTTP, check the actual Content-Encoding before decoding. The Brotli reference explains these differences and HTTP handling.

Streams

A Compressor wraps any writer and is itself a writer, so write_all and copy_all work with it. finish writes the end of the stream; without it the output is incomplete. A Decompressor wraps any reader and is itself a reader, decoding as it goes in fixed-size buffers:

import std.bytes
import std.compress
import std.io
from std.compress import Format

type CompressedStreamError = std.io.StreamError | std.io.Partial | std.compress.CompressError | std.bytes.BytesError

def main() -> Result[(), IoError | AllocError | CompressedStreamError | OverflowError[i64]]:
    line = std.bytes.from_text("one line of a log\n")?
    mut writer = std.compress.compressor(Format.Gzip, std.io.cursor(std.bytes.empty()?), 6)?
    for _ in range(0, 1000):
        std.io.write_all(&mut writer, &line)?
    writer.finish()?
    packed = writer.inner.data.copy()?
    print(packed.len())?
    mut reader = std.compress.decompressor(Format.Gzip, std.io.cursor(packed), 1000000)?
    mut buffer = std.bytes.with_capacity(4096)?
    buffer.resize(4096, 0u8)?
    mut lines = 0
    while True:
        count = reader.read(&mut buffer, 0, 4096)?
        if count == 0:
            break
        lines += buffer.count(10u8, 0, count)
    print(lines)?
    Ok(())

185
1000

The reader counts 18,000 bytes of lines while holding at most 4096 of them, so the same loop handles a file much larger than memory. To compress a file, wrap std.io.open_file(path, "w")? instead of a cursor.

Damaged input

gzip and zlib end with a checksum of the original data, so a damaged stream is caught. decompress returns only an error. A Decompressor reports it through the Reader protocol as a StreamError, and failure names the exact cause:

import std.bytes
import std.compress
import std.io
from std.compress import Format

def main() -> Result[(), AllocError | IoError | std.compress.CompressError | std.bytes.BytesError | OverflowError[i64] | OverflowError[u8]]:
    data = std.bytes.from_text("checked at the end")?
    mut packed = std.compress.compress(Format.Gzip, &data, 6)?
    last = packed.len() - 1
    packed.set(last, packed.get(last) + 1u8)
    print(str.repr(std.compress.decompress(Format.Gzip, &packed, 100))?)?
    mut reader = std.compress.decompressor(Format.Gzip, std.io.cursor(packed), 100)?
    mut out = std.bytes.empty()?
    match std.io.read_up_to(&mut reader, &mut out, 100):
        case Ok(_):
            print("read it all")?
        case Err(partial):
            print(str.repr(partial.cause)?)?
            print(str.repr(reader.failure())?)?
    Ok(())

Result[std.bytes.Bytes, std.compress.CompressError].Err(std.compress.CompressError.Checksum)
std.io.StreamError.Io(IoError.InvalidInput)
Option[std.compress.CompressError].Some(std.compress.CompressError.Checksum)

The checksum comes last, so a reader may already have returned some bytes before it finds the damage. Treat streamed output as unverified until read returns 0.

See the std.compress reference for every error, the rules for input after a stream, and memory costs.

Read and write archives

std.archive reads and writes TAR and ZIP archives over std.io streams, and extracts them safely into a new directory.

Write and list a TAR archive

A TarWriter wraps any writer. Each add_ call writes one entry, and finish writes the end of the archive. A TarReader returns the entries in order; between calls to next, it is a reader of the current entry’s content:

import std.archive
import std.bytes
import std.io
import std.path

def main() -> Result[(), IoError | AllocError | std.io.Partial | std.archive.ArchiveError | std.bytes.BytesError]:
    mut writer = std.archive.tar_writer(std.io.cursor(std.bytes.empty()?))?
    writer.add_dir(&std.path.from_text("notes")?, 493, 1700000000)?
    writer.add_file(&std.path.from_text("notes/todo.txt")?, &std.bytes.from_text("buy milk")?, 420, 1700000000)?
    writer.finish()?
    packed = writer.inner.data.copy()?
    print(packed.len())?
    mut reader = std.archive.tar_reader(std.io.cursor(packed))?
    while True:
        match reader.next()?:
            case Some(entry):
                mut content = std.bytes.empty()?
                drop(std.io.read_up_to(&mut reader, &mut content, 1000)?)
                print(decode_utf8(entry.name.as_bytes())?, entry.size)?
                if content.len() > 0:
                    print(content.to_text()?)?
            case Nothing:
                break
    Ok(())

2560
notes/ 0
notes/todo.txt 8
buy milk

TAR stores each header and each file’s content in 512-byte blocks and ends with two empty blocks, so even a tiny archive takes a few kilobytes. To compress it, wrap the writer in a std.compress Compressor.

ZIP archives

A ZIP archive keeps a directory of its entries at the end, so a ZipReader needs a stream it can seek: a file or a cursor. entries lists everything; open selects one entry to read:

import std.archive
import std.bytes
import std.io
import std.path
from std.archive import Method

def main() -> Result[(), IoError | AllocError | std.io.Partial | std.archive.ArchiveError | std.bytes.BytesError]:
    mut writer = std.archive.zip_writer(std.io.cursor(std.bytes.empty()?))?
    mut text = std.bytes.empty()?
    for _ in range(0, 50):
        text.extend(&std.bytes.from_text("all work and no play ")?)?
    writer.add_file(&std.path.from_text("story.txt")?, &text, Method.Deflate, 420, 1700000000)?
    writer.add_file(&std.path.from_text("short.txt")?, &std.bytes.from_text("hi")?, Method.Stored, 420, 1700000000)?
    writer.finish()?
    mut reader = std.archive.zip_reader(std.io.cursor(writer.inner.data.copy()?), 100)?
    entries = reader.entries()
    for entry in entries:
        print(decode_utf8(entry.name.as_bytes())?, entry.size, entry.compressed)?
    reader.open(1)?
    mut content = std.bytes.empty()?
    drop(std.io.read_up_to(&mut reader, &mut content, 100)?)
    print(content.to_text()?)?
    Ok(())

story.txt 1050 35
short.txt 2 2
hi

The reader checks each entry’s size and CRC-32 when its content ends.

Extract safely

An archive is untrusted input. Its names may point outside the target (../../.bashrc), its links may lead elsewhere, and a small archive may expand into terabytes. extract_tar and extract_zip check every entry against a Policy, write into a hidden staging directory, and rename it to the destination only when everything succeeded:

import std.archive
import std.bytes
import std.fs
import std.io
import std.path
from std.sync import CancellationToken

type ArchiveOperationError = std.archive.ArchiveError | std.bytes.BytesError | std.fs.FsError

def main() -> Result[(), AllocError | IoError | ArchiveOperationError]:
    parent = std.fs.root(&std.path.from_text(".")?)?
    mut scratch = std.fs.temporary_dir(&parent, &std.path.from_text("archive-lesson-")?, 8)?
    mut writer = std.archive.tar_writer(std.io.cursor(std.bytes.empty()?))?
    writer.add_file(&std.path.from_text("site/index.html")?, &std.bytes.from_text("<h1>hi</h1>")?, 420, 0)?
    writer.add_symlink(&std.path.from_text("site/secret")?, &std.path.from_text("/etc/passwd")?, 0)?
    writer.finish()?
    packed = writer.inner.data.copy()?

    cancel = CancellationToken()?
    mut policy = std.archive.policy()
    mut first = std.archive.tar_reader(std.io.cursor(packed.copy()?))?
    match std.archive.extract_tar(&mut first, scratch.root(), &std.path.from_text("out")?, &policy, &cancel):
        case Ok(_):
            print("extracted")?
        case Err(error):
            print(error)?
    policy.skip_links = True
    mut second = std.archive.tar_reader(std.io.cursor(packed))?
    summary = std.archive.extract_tar(&mut second, scratch.root(), &std.path.from_text("out")?, &policy, &cancel)?
    print(summary.files, summary.bytes, summary.skipped)?

    std.fs.remove_tree(scratch.root(), &std.path.from_text("out")?, 10, 4, &cancel)?
    scratch.cleanup()?
    Ok(())

std.archive.ArchiveError.Link
1 11 1

The first attempt fails on the link and leaves nothing behind. The second skips it. Extracted files get private permissions (0600); stored modes and times are not applied.

The default policy allows 10000 entries, 1 GiB per file, 4 GiB in total, and a compression ratio of 100 for large ZIP entries. Lower the limits to what your program expects.

See the std.archive reference for the format rules, every error, and memory costs.

Build a package with dependencies

A package is a directory with a plenty.toml manifest and sources under src/. plenty new hello creates one; plenty new shapes --lib creates a library. Here is a library package in shapes/:

manifest-version = 1

[package]
name = "shapes"
version = "0.1.0"

src/lib.plenty is the library: the module that other packages import.

pub class Square:
    pub side: i64

    pub def area(self) -> Result[i64, OverflowError[i64]]:
        Ok(self.side * self.side)

An application beside it declares the library as a dependency. The key under [dependencies] is the name that application code imports, and path is relative to this manifest:

manifest-version = 1

[package]
name = "app"
version = "0.1.0"

[dependencies]
geometry = { path = "../shapes" }

src/main.plenty is the executable, named after the package:

import geometry
from report import show

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    square = geometry.Square(4)
    show(square.area()?)

Other files under src/ are the package’s own modules, imported as before:

pub def show(area: i64) -> Result[(), IoError]:
    print("area:")?
    print(area)?
    Ok(())

Run plenty run anywhere inside app/:

plenty run

area:
16

plenty run compiles into target/optimized/app and runs it. Progress messages go to standard error; program arguments follow --, as in plenty run -- a b. Builds optimize by default. For shorter edit-run cycles in large projects, use plenty run --fast-compile or plenty build --fast-compile; these write to target/fast-compile/ and keep the same overflow, bounds and ownership checks. Use the default profile when measuring runtime performance. A later build with no changed source reports Fresh and reuses the executable.

The first build also writes plenty.lock, which records the resolved packages. Commit it with the manifest. --locked makes a build fail instead of changing it.

A dependency can also come from a Git repository, at a tag or a commit. The official time-zone package is one:

[dependencies]
tz = { git = "https://github.com/plentylang/tz.git", tag = "v0.3.0", version = "0.3.0" }

The first build fetches the repository into .pkg/ and records the exact commit in plenty.lock. Later builds use that commit even if the tag moves upstream, until plenty update resolves it again. The optional version checks that the dependency’s own version is compatible. plenty add writes these entries and updates the lockfile:

plenty add geometry --path ../shapes
plenty add tz --git https://github.com/plentylang/tz.git --tag v0.3.0

Several related packages can share one lockfile and target/ as a workspace.

A dependency’s name belongs only to the package that declares it. app cannot import what shapes depends on without declaring it too, and a local module named geometry would be an error. Two packages may each define Square; those are distinct types.

The dependency’s name also reaches its other modules. If shapes had src/circles.plenty, import geometry.circles would bind it beside import geometry, unless the library itself declares something named circles; modules and imports gives the rule.

Programs in tests/ are integration tests. Each one sees the package’s library under the package name, and passes when main returns exit status zero:

from shapes import Square

def main() -> Result[i32, OverflowError[i64]]:
    if Square(3).area()? == 9:
        Ok(0i32)
    else:
        Ok(1i32)

plenty test

running 1 test
test area ... ok

test result: ok. 1 passed; 0 failed

A later lesson shows test functions and std.test. plenty check type-checks every target without linking. It reaches only the files that targets import, so it warns about any other .plenty file under src/ and ends with a summary such as Checked app v0.1.0: 1 executable; 2 of 2 files in src/. Keep test fixtures and other files that are not package source outside src/. plenty clean removes target/. Single files still run with plenty FILE; the compiler is also available alone as plentyc.

Match text with regular expressions

std.regex compiles a pattern once into a Regex, then searches text with it. Matching takes time proportional to the length of the text, whatever the pattern: there is no backtracking, so no pattern can make a search run for hours. compile takes Limits, which also bound the pattern itself, so a pattern from an untrusted source is safe to compile.

Keep the compiled Regex when searching repeatedly. The library selects prefix filters and faster matching engines where the pattern permits them; captures, match ordering and resource limits keep the same meaning.

Find matches

find returns the first match as byte offsets; text copies the matched part. find_all returns every match and fails rather than return more than its limit:

import std.regex

def main() -> Result[(), AllocError | IoError | std.regex.RegexError]:
    limits = std.regex.limits()
    year = std.regex.compile("\\b(19|20)\\d\\d\\b", &limits)?
    text = "Released 1999, revised 2024, not 12345."
    match year.find(text)?:
        case Some(found):
            print(found.start, found.end, found.text(text)?)?
        case Nothing:
            print("no year")?
    print(len(year.find_all(text, 10)?))?
    print(year.is_match("in 1850")?)?
    print(str.repr(year.find_all(text, 1))?)?
    Ok(())

9 13 1999
2
False
Result[list[std.regex.Match], std.regex.RegexError].Err(std.regex.RegexError.LimitExceeded(std.regex.Limit.Matches))

A Plenty string needs \\ for each backslash in the pattern. \d, \w, \s and \b are ASCII-only; for other scripts, use properties such as \p{Alphabetic}.

Groups and replacement

Parentheses capture. (?P<name>...) names a group. captures returns every group of the first match; a group that did not take part is Nothing. In a replacement template, $1 and ${name} insert a group and $$ inserts a dollar sign:

import std.regex

def main() -> Result[(), AllocError | IoError | std.regex.RegexError]:
    limits = std.regex.limits()
    date = std.regex.compile("(?P<year>\\d{4})-(?P<month>\\d{2})", &limits)?
    text = "from 2024-05 to 1999-12"
    match date.captures(text)?:
        case Some(groups):
            match groups.name("year"):
                case Some(group):
                    print(group.text(text)?)?
                case Nothing:
                    print("group did not match")?
            match groups.get(2):
                case Some(group):
                    print(group.text(text)?)?
                case Nothing:
                    print("group did not match")?
        case Nothing:
            pass
    print(date.replace_all(text, "${month}/$1", 100)?)?
    words = std.regex.compile("\\s*,\\s*", &limits)?
    print(" | ".join(words.split("red , green,blue", 10)?)?)?
    Ok(())

2024
05
from 05/2024 to 12/1999
red | green | blue

The last argument of replace_all and split is a limit on the result size or the number of pieces. Write ${1}0 when a group number is followed by a digit. A bare $name is an error: use ${name}.

Errors and limits

A pattern error reports its byte offset. A pattern that would build too large a matcher, and a search that would do too much work, are limit errors:

import std.regex
from std.regex import Limits

def main() -> Result[(), AllocError | IoError | std.regex.RegexError]:
    limits = std.regex.limits()
    print(str.repr(std.regex.compile("total: (\\d+", &limits))?)?
    print(str.repr(std.regex.compile("(a{1000}){1000}", &limits))?)?
    tight = Limits(1000, 16, 100, 1000, 1000000, 100)
    word = std.regex.compile("\\w+!", &tight)?
    print(str.repr(word.find("no exclamation mark in this sentence"))?)?
    Ok(())

Result[std.regex.Regex, std.regex.RegexError].Err(std.regex.RegexError.Syntax(std.regex.SyntaxError(offset=7, message="unclosed group")))
Result[std.regex.Regex, std.regex.RegexError].Err(std.regex.RegexError.LimitExceeded(std.regex.Limit.Instructions))
Result[Option[std.regex.Match], std.regex.RegexError].Err(std.regex.RegexError.LimitExceeded(std.regex.Limit.Work))

The default limits suit patterns written into a program. For patterns from users, lower them to what a request may spend.

See the std.regex reference for the full syntax, every limit, and searching bytes.

Write tests with std.test

plenty test runs a package’s tests. A file in tests/ holds either one program with main, as in the packages lesson, or any number of test_ functions. Each test function runs in its own process, so a trap in one fails only that test.

Here is a small library to test:

manifest-version = 1

[package]
name = "stats"
version = "0.1.0"

from std.bytes import from_text
from std.io import Writer, Partial, write_all
from std.bytes import BytesError

pub def total(values: &list[i64]) -> Result[i64, OverflowError[i64]]:
    mut sum = 0
    for value in values:
        sum += *value
    Ok(sum)

pub def mean(values: &list[i64]) -> Result[f64, OverflowError[i64]]:
    Ok(f64(total(values)?) / f64(len(values)))

pub def save(path: &str, values: &list[i64]) -> Result[(), AllocError | IoError | OverflowError[i64]]:
    write_text(path, &str.from(total(values)?)?)?
    Ok(())

pub def report[W: Writer](out: &mut W, values: &list[i64]) -> Result[(), AllocError | BytesError | Partial | OverflowError[i64]]:
    line = from_text(&str.from(total(values)?)?)?
    write_all(out, &line)?
    Ok(())

A test function takes no parameters and returns () or Result[(), E]. std.test supplies assertions that return Result[(), TestError], so ? stops the test at the first failure:

import std.bytes
import std.test
import std.io
from stats import mean, report, save, total

def test_total() -> Result[(), AllocError | IoError | std.test.TestError | OverflowError[i64]]:
    values = [1, 2, 3]?
    std.test.equal(&total(&values)?, &6)?
    empty: list[i64] = []?
    std.test.equal(&total(&empty)?, &0)?
    Ok(())

def test_mean() -> Result[(), AllocError | IoError | std.test.TestError | OverflowError[i64]]:
    values = [1, 2]?
    std.test.close(mean(&values)?, 1.5, 0.000001)?
    Ok(())

def test_save() -> Result[(), AllocError | IoError | std.test.TestError | OverflowError[i64]]:
    scratch = std.test.scratch()?
    path = scratch.file("total.txt")?
    values = [4, 5]?
    save(&path, &values)?
    std.test.equal(&read_text(&path)?, &"9")?
    Ok(())

def test_order_does_not_matter() -> Result[(), AllocError | IoError | std.test.TestError | OverflowError[i64]]:
    mut rng = std.test.rng()?
    mut values = [1, 2, 3, 4, 5]?
    rng.shuffle(&mut values)
    std.test.equal(&total(&values)?, &15)?
    Ok(())

def test_report_survives_short_writes() -> Result[(), AllocError | std.bytes.BytesError | std.io.Partial | std.test.TestError | OverflowError[i64]]:
    mut out = std.test.fake_stream(std.bytes.empty()?)?
    out.limit(1)
    values = [9, 10]?
    report(&mut out, &values)?
    std.test.equal(&out.output.to_text()?, &"19")?
    Ok(())

def test_save_reports_a_full_disk() -> Result[(), AllocError | IoError | std.test.TestError | OverflowError[i64]]:
    scratch = std.test.scratch()?
    path = scratch.file("total.txt")?
    values = [4, 5]?
    std.test.fail_files_after(0u32, 28i32)?
    saved = save(&path, &values)
    std.test.restore_files()?
    std.test.is_err(&saved)?
    Ok(())

std.test.scratch() makes an empty directory under $TMPDIR that is removed with everything in it when the Scratch value is dropped. std.test.rng() is a generator seeded from plenty test --seed N, or from 0, so a run repeats exactly.

report takes any std.io Writer, so the test hands it a fake stream that accepts one byte per call. A file rarely takes a write in pieces, but a pipe or socket does; the fake makes that case happen every time. fail_after makes a chosen call fail, and std.test.fake_clock stands in for the clock in the same way.

A real file fails rarely, so test_save_reports_a_full_disk makes it fail: after fail_files_after(0u32, 28i32), every file call fails with error 28, the system’s code for a full disk, until restore_files. fail_allocations_after does the same for memory. plenty test enables these hooks automatically. For an integration test that launches the ordinary application, explicitly use plenty build --test-hooks and arm the budget at the operation being tested. Default builds contain no hooks. See failure injection and memory-limited runs.

plenty test

running 6 tests
test sums::test_total ... ok
test sums::test_mean ... ok
test sums::test_save ... ok
test sums::test_order_does_not_matter ... ok
test sums::test_report_survives_short_writes ... ok
test sums::test_save_reports_a_full_disk ... ok

test result: ok. 6 passed; 0 failed

Tests run in parallel, one per CPU, but are listed in the order they appear.

Each test is named FILE::FUNCTION. plenty test mean runs only the tests whose names contain mean, and plenty test --list prints the names without running anything.

A test’s output is kept and shown only if it fails. If total added one too many, plenty test test_total would print:

running 1 test
test sums::test_total ... FAILED (returned Err)

failures:

---- sums::test_total output ----
sums.plenty:7:5: assertion failed: left == right
  left: 7
 right: 6

test result: FAILED. 0 passed; 1 failed; 5 filtered out

The command exits with status 1.

The assertion writes where it was called and what it found as it fails, and returned Err says the test stopped there. A trap would read exit status 1 and show the trap’s message. plenty test --no-capture lets output through as it happens, and --timeout 10 fails any test still running after ten seconds.

A file defines either main or test_ functions, not both. Helpers that are not tests need a name without the test_ prefix, or a module in a subdirectory of tests/. See std.test for every assertion.

Compare text with std.diff

std.diff finds what changed between two versions of a text and reports it as edit operations: runs that stayed equal, were deleted, or were inserted.

Show a unified diff

std.diff.lines compares line by line. unified formats the result the way diff -u does, with the given number of unchanged lines around each change:

import std.diff

def main() -> Result[(), AllocError | IoError]:
    old = "name = \"stats\"\nversion = \"0.1.0\"\nauthors = []\nlicense = \"MIT\"\n"
    new = "name = \"stats\"\nversion = \"0.2.0\"\nauthors = []\nlicense = \"MIT\"\nreadme = \"README.md\"\n"
    changes = std.diff.lines(old, new)?
    print(changes.has_changes())?
    print(changes.unified(1, "plenty.toml", "plenty.toml (edited)")?)?
    Ok(())

True
--- plenty.toml
+++ plenty.toml (edited)
@@ -1,4 +1,5 @@
 name = "stats"
-version = "0.1.0"
+version = "0.2.0"
 authors = []
 license = "MIT"
+readme = "README.md"

A hunk header @@ -1,4 +1,5 @@ says that four lines starting at line 1 of the old text became five lines starting at line 1 of the new one. Equal texts give empty text, so check has_changes first when that matters.

Walk the operations

words splits text into runs of whitespace and runs of other characters, and chars into single characters. Each Op gives a range of old tokens and a range of new tokens; a deletion has an empty new range and an insertion an empty old range:

import std.diff
from std.diff import Kind

def main() -> Result[(), AllocError | IoError]:
    changes = std.diff.words("the quick brown fox", "the quick red fox jumps")?
    old = changes.old_tokens()
    new = changes.new_tokens()
    for op in changes.ops():
        match op.kind:
            case Kind.Equal:
                pass
            case Kind.Delete:
                for index in range(op.old_start, op.old_end):
                    print("removed", str.repr(old[index])?)?
            case Kind.Insert:
                for index in range(op.new_start, op.new_end):
                    print("added", str.repr(new[index])?)?
    Ok(())

removed "brown"
added "red"
added " "
added "jumps"

ops returns a reference, so bind the TextDiff to a name before calling it. std.diff.diff compares any two lists whose elements can be dictionary keys, and std.diff.diff_bytes compares Bytes.

The default algorithm finds the fewest deletions and insertions. Passing Algorithm.Patience as the last argument anchors the comparison on lines that occur once in each text, which often reads better for source code.

Finding the fewest edits takes time quadratic in the input size when two large inputs have little in common. For large or untrusted input, pass a cost limit such as std.diff.lines(old, new, max_cost=Some(512)): the work stays roughly linear and the operations still turn the old text into the new one, but may include more deletions and insertions than necessary. See the std.diff reference for both algorithms, the cost limit, and their costs.

Render Markdown as HTML

std.markdown reads CommonMark, the common core of Markdown, and writes HTML. Between the two it offers a stream of events, so a program can inspect or change a document before it is rendered.

Convert a document

to_html renders a whole document. Like other parsers in the standard library, it takes limits on input size, nesting depth, and output size:

import std.markdown
from std.markdown import MarkdownError

def main() -> Result[(), AllocError | IoError | MarkdownError]:
    bounds = std.markdown.limits()
    text = "# Shopping\n\n- *fresh* bread\n- [cheese](https://example.com/cheese)\n"
    print(std.markdown.to_html(text, &bounds)?)?
    Ok(())

<h1>Shopping</h1>
<ul>
<li><em>fresh</em> bread</li>
<li><a href="https://example.com/cheese">cheese</a></li>
</ul>

The HTML ends with a line ending, so print leaves a blank line after it.

Walk the events

A parser yields Start and End events around each block and inline element, with Text and other events between them. This program prints the text of every second-level heading:

import std.markdown
from std.markdown import Event, MarkdownError, Tag

def main() -> Result[(), AllocError | IoError | MarkdownError]:
    bounds = std.markdown.limits()
    text = "# Plenty\n\n## Install\n\nRun `plenty FILE`.\n\n## Learn\n\nRead the *tutorial*.\n"
    mut events = std.markdown.parser_text(text, &bounds)?
    mut in_section = False
    while True:
        event = events.next()?
        match event:
            case Event.Start(tag):
                match tag:
                    case Tag.Heading(level):
                        in_section = level == 2
                    case _:
                        pass
            case Event.End(_):
                in_section = False
            case Event.Text(words):
                if in_section:
                    print("-", words)?
            case Event.Done:
                break
            case _:
                pass
    Ok(())

- Install
- Learn

Text holds the characters to show, with escapes and entities such as & already resolved. The last event is Done.

Change events before rendering

Markdown lets raw HTML through unchanged. When the text comes from someone you do not trust, render the events yourself and turn raw HTML into text, which the renderer escapes:

import std.bytes
import std.markdown
from std.markdown import Event, MarkdownError

def main() -> Result[(), AllocError | IoError | std.bytes.BytesError | MarkdownError]:
    bounds = std.markdown.limits()
    text = "Hi <b onclick=\"steal()\">there</b>!\n\n<script>steal()</script>\n"
    mut events = std.markdown.parser_text(text, &bounds)?
    mut html = std.markdown.renderer(&bounds)?
    while True:
        event = events.next()?
        match event:
            case Event.Html(raw):
                html.event(&Event.Text(raw))?
            case Event.InlineHtml(raw):
                html.event(&Event.Text(raw))?
            case Event.Done:
                break
            case _ as other:
                html.event(&other)?
    print(html.take()?.to_text()?)?
    Ok(())

<p>Hi &lt;b onclick=&quot;steal()&quot;&gt;there&lt;/b&gt;!</p>
&lt;script&gt;steal()&lt;/script&gt;

Link destinations are not checked either: [x](javascript:steal()) is a valid link. A program that publishes untrusted Markdown should also inspect Tag.Link and Tag.Image destinations.

std.markdown.write_html renders a parser’s events straight to a writer, such as a file, without holding the whole page. See the std.markdown reference for the events, limits, errors, and exact HTML output.

Useful programs and resources

Read arguments and text, format results, and use standard streams and files. Combine these operations into a command-line application.

Command-line arguments

args() returns Result[list[str], IoError]. Index zero is the executable’s invocation name, followed by the supplied arguments. Pass arguments to a compiled binary, for example ./program first "two words"; quoted spaces remain within one argument. Each call creates an independent list and reports allocation or UTF-8 errors.

def count_arguments() -> Result[bool, IoError]:
    values = args()?
    Ok(len(values) >= 1)

def main() -> Result[(), AllocError | IoError]:
    print(count_arguments()?)?
    Ok(())

True

Parse typed arguments

Use std.cli when a tool needs options, positionals, generated help, and useful usage errors. The schema explicitly chooses each argument’s type and whether it is required or repeatable. Path values retain native bytes.

This small input-selection tool accepts a row limit and any number of paths. The fixture models finder --limit -2 first.csv -- --last.csv. Real programs use raw = args_bytes()? and parse(&schema, &raw, 1) to skip the executable name.

import std.cli

from std.cli import Spec, Kind, Value, parse

def main() -> Result[(), AllocError | IoError | std.cli.CliError]:
    schema = [
        Spec("--limit", Kind.Integer, False, False, False, "maximum rows"),
        Spec("FILE", Kind.Path, True, True, True, "input files")
    ]?
    raw = [encode_utf8("--limit")?, encode_utf8("-2")?,
           encode_utf8("first.csv")?, encode_utf8("--")?,
           encode_utf8("--last.csv")?]?
    parsed = parse(&schema, &raw, 0)?
    for entry in &parsed.entries:
        match &entry.value:
            case Value.Integer(limit):
                print("limit:", limit)?
            case Value.Path(path):
                print("file:", path.to_string()?)?
            case _:
                pass
    Ok(())

limit: -2
file: first.csv
file: --last.csv

Long options use separate values: --limit 12. A value following an option is always consumed, even if it starts with -. The standalone -- ends option recognition; subsequent tokens are positional. Missing required arguments, unknown options, duplicate nonrepeatable options, and invalid integers are typed errors. Optional specs produce no entry when absent, leaving defaults to you.

Handle help before running the tool. It is a successful result, not an error. The following complete program uses a synthetic request so the lesson can run without shell arguments. Replace raw and the start index as above in a binary.

from std.cli import Spec, Kind, parse, help, describe_for, exit_status
from std.error import Context, Subject

def run() -> Result[i32, AllocError | IoError]:
    schema = [Spec("FILE", Kind.Path, True, True, False, "input file")]?
    raw = [encode_utf8("--help")?]?
    status = match parse(&schema, &raw, 0):
        case Ok(parsed):
            if parsed.help_requested:
                match help(&schema, "finder"):
                    case Ok(text):
                        write_stdout(text)?
                    case Err(error):
                        Context("help", Subject.Absent, error).report()
                        return Ok(1i32)
            0i32
        case Err(error):
            status = exit_status(&error)
            context = Context("arguments", Subject.Absent, error)
            context.report_with(describe_for(&context.cause, &schema))
            status
    Ok(status)

def main() -> i32:
    match run():
        case Ok(status):
            status
        case Err(error):
            Context("argument setup", Subject.Absent, error).report()
            1i32

Usage: finder [--help]
  FILE <path> (required)  input file
  --help  Show this help

--help bypasses missing-required checks, but an earlier bad argument still fails. After --, or as the next token for a text/path option, --help is data. The parser validates the schema before processing either form.

The run helper propagates setup and output failures. main reports those failures and returns a nonzero exit status, just as it does for argument and help errors. std.cli lists all errors, costs, and grammar limits.

Show progress

Use std.cli.progress when a command does enough work that users need feedback. Advance a bar after each successful unit of work and finish it explicitly. The bar uses stderr only when it is a terminal, so redirected output remains clean. The library limits redraws; an update on every item does not redraw on every item.

import std.cli.progress as progress
from std.cli.progress import ProgressError

def main() -> Result[(), ProgressError | IoError | OverflowError[i64]]:
    mut bar = progress.bar(5u64)
    mut total = 0
    for value in range(1, 6):
        total += value * value
        bar.advance()?
    bar.finish()?
    print("sum of squares:", total)?
    Ok(())

sum of squares: 55

The calculation is deliberately short to keep the example runnable; a real program might count imported records or processed files. For an unknown total, use progress.spinner(): advance() counts completed units, and tick() requests an animation step without changing the count. There is no background thread, so a spinner only moves when your program updates it.

Propagate display errors as above unless your application deliberately treats progress as optional. An early failure does not automatically finish the display; finish before returning or writing diagnostics when a clean terminal line is needed. Avoid mixing another progress bar or concurrent stderr logging with the same display. The initial renderer assumes an ANSI terminal at least 80 columns wide and uses compact approximate counts; bar.position() gives the exact count.

The reference describes rates, ETA, deterministic clock inputs and plain-text rendering.

Reading integers from text

Use a sized type’s parse method for external text. It borrows the string and returns an allocation-free Result. Decimal ASCII digits and an optional sign are accepted, with surrounding Unicode whitespace ignored. Numeric prefixes, underscores, and non-ASCII digits are not accepted.

def main() -> Result[(), AllocError | IoError]:
    print(str.repr(u8.parse(" 255 "))?)?
    print(str.repr(u8.parse("256"))?)?
    print(str.repr(i64.parse("hello"))?)?
    Ok(())

Result[u8, ParseError].Ok(255)
Result[u8, ParseError].Err(ParseError.OutOfRange)
Result[i64, ParseError].Err(ParseError.Invalid)

Functions returning the same error type can propagate parsing failures with ?. try_from reports a value that does not fit with RangeError.OutOfRange. Match it explicitly to combine parsing, calculation, and narrowing in a function returning ParseError:

def shade(percent: &str) -> Result[u8, ParseError]:
    number = i64.parse(percent)?
    scaled_result = checked:
        number * 255
    product = match scaled_result:
        case Ok(value):
            value
        case Err(_):
            return Err(ParseError.OutOfRange)
    hundred: Positive[i64] = 100
    scaled = product // hundred
    match u8.try_from(scaled):
        case Ok(value):
            Ok(value)
        case Err(error):
            match error:
                case RangeError.OutOfRange:
                    Err(ParseError.OutOfRange)

def main() -> Result[(), AllocError | IoError]:
    print(str.repr(shade("50"))?)?
    print(str.repr(shade("150"))?)?
    print(str.repr(shade("half"))?)?
    Ok(())

Result[u8, ParseError].Ok(127)
Result[u8, ParseError].Err(ParseError.OutOfRange)
Result[u8, ParseError].Err(ParseError.Invalid)

The local checked multiplication maps overflow to ParseError.OutOfRange, keeping this conversion helper’s public error contract. The positive divisor proves division cannot fail. No unchecked arithmetic or lossy cast is needed.

Reading floating-point text

Floating-point parsing accepts decimal/exponent forms and surrounding whitespace. Overflow returns OutOfRange; underflow can round to zero. Explicit inf, infinity, and nan are accepted case-insensitively, with optional signs.

def main() -> Result[(), AllocError | IoError]:
    print(str.repr(f32.parse("1.25e2"))?)?
    print(str.repr(f32.parse("1e100"))?)?
    print(str.repr(f64.parse("-0.0"))?)?
    Ok(())

Result[f32, ParseError].Ok(125.0)
Result[f32, ParseError].Err(ParseError.OutOfRange)
Result[f64, ParseError].Ok(-0.0)

Convert and format values

str.from converts numbers or booleans to text, returning Result[str, AllocError]. Floats use the shortest text that parses back to the same value.

def main() -> Result[(), AllocError | IoError]:
    print(str.from(42)?)?
    print(str.from(-0.0f32)?)?
    print(str.from(True)?)?
    Ok(())

42
-0.0
True

Inspect a value with str.repr

str.repr formats a borrowed value; print writes a value and newline, reporting formatting allocation failures and output errors:

def main() -> Result[(), AllocError | IoError]:
    values = [1, 2]?
    print(str.repr(values)?)?
    print(values)?
    Ok(())

[1, 2]
[1, 2]

Formatting failure writes nothing. An output error can leave a partial write. The source remains usable; neither call copies a mutable collection.

The inner ? handles formatting; the outer ? handles printing. To inspect a Result wrapper itself, pass it to str.repr:

def main() -> Result[(), AllocError | IoError]:
    result: Result[i64, str] = Err("not ready")
    print(str.repr(result)?)?
    Ok(())

Result[i64, str].Err("not ready")

Split text into fields

Use text.split(separator) to split on an explicit, nonempty string. It returns Result[list[str], AllocError]:

def main() -> Result[(), AllocError | IoError]:
    line = "Ada::Bea::::"
    parts = line.split("::")?
    print(parts)?
    print(str.repr(" / ".join(parts)?)?)?
    print(line)?
    print("".split(",")?)?
    Ok(())

["Ada", "Bea", "", ""]
"Ada / Bea /  / "
Ada::Bea::::
[""]

Adjacent and trailing separators preserve empty fields. Matches do not overlap: "aaaaa".split("aa") succeeds with ["", "", "a"]. A separator that does not occur produces a single piece containing the whole input.

Each piece owns independent storage. Splitting borrows both inputs and leaves them unchanged, including on allocation failure.

This program cannot produce its fields if splitting fails, so ? returns the error from main. The same policy handles failures from joining, formatting, and printing. Use a match instead when you have a useful recovery action.

An empty separator causes a runtime trap, not AllocError. Check len(separator) > 0 for user-supplied separators. Whitespace splitting without a separator and a maximum-split argument are unsupported.

Splitting text that is already in memory

splitlines() returns an independent list without line endings. Pass True to keep the original endings. A final newline does not add an extra empty line, and empty text produces an empty list. Unlike file reads, this method also recognizes Unicode line/paragraph separators and the other Python-style text line boundaries.

def main() -> Result[(), AllocError | IoError]:
    print("first\r\n\nlast\n".splitlines()?)?
    print("first\r\nlast".splitlines(True)?)?
    print("".splitlines()?)?
    Ok(())

["first", "", "last"]
["first\r\n", "last"]
[]

Writing text with recoverable errors

write_stdout(text) borrows a string and writes exactly its contents, without a newline. Success returns the number of Unicode characters. An I/O error can follow a partial write, so retrying the whole string can duplicate output.

def main() -> Result[(), AllocError | IoError]:
    result = write_stdout("Hello!\n")
    print(result?)?
    Ok(())

Hello!
7

IoError.System(code) carries a native OS error code. Decoding, allocation, and stream-state errors have separate variants; the text I/O reference lists them all.

Flushing output and reporting diagnostics

Use write_stderr(text) for diagnostics. It returns the same character-count result as write_stdout. flush_stdout() and flush_stderr() return Result[(), IoError]. Flush when the caller needs to observe buffered-write errors or when displaying a prompt; a flush does not promise disk durability.

def report() -> Result[(), IoError]:
    write_stdout("ready")?
    flush_stdout()?
    Ok(())

def main() -> Result[(), IoError]:
    report()?
    print("")?
    Ok(())

ready

Reading a line

input() returns Result[Option[str], IoError]. It removes a trailing LF or CRLF. Some("") means an empty line; Nothing means end-of-file. UTF-8 errors and allocation failures return Err. A failure can consume input, so retrying does not promise to repeat the same line. Input currently requires a Unix host. For a prompt, call write_stdout and flush_stdout before input().

Call echo_line()? repeatedly until it returns False to process stdin. This example’s main does not read input.

def echo_line() -> Result[bool, IoError]:
    match input()?:
        case Some(line):
            write_stdout(line)?
            write_stdout("\n")?
            Ok(True)
        case Nothing:
            Ok(False)

def main() -> Result[(), IoError]:
    print("echo_line is ready")?
    Ok(())

echo_line is ready

Reading a UTF-8 file

read_text(path) opens, reads, and closes a file, returning Result[str, IoError]. It requires Linux and strict UTF-8, translating CRLF and bare CR to LF. Paths are relative to the process working directory. The handle closes even when reading or allocating fails.

The &str parameter borrows literals and bindings implicitly; configuration(&path) is also valid.

def configuration(path: &str) -> Result[str, IoError]:
    read_text(path)

def main() -> Result[(), IoError]:
    write_text("configuration.txt", "mode=fast\n")?
    print(configuration("configuration.txt")?)?
    path = "configuration.txt"
    print(configuration(path)?)?
    Ok(())

mode=fast

mode=fast

Writing a UTF-8 file

write_text(path, text) creates or replaces a file and returns the number of Unicode characters written. It writes exact UTF-8 bytes without translating newlines and closes the handle before returning. OS failures can leave truncated or partially written contents; this is not an atomic save.

Run this in a scratch directory: it replaces plenty-example.txt.

def save_and_read() -> Result[str, IoError]:
    write_text("plenty-example.txt", "Hello, é!\n")?
    read_text("plenty-example.txt")

def main() -> Result[(), AllocError | IoError]:
    print(str.repr(save_and_read())?)?
    Ok(())

Result[str, IoError].Ok("Hello, é!\n")

Appending text

append_text(path, text) adds exact UTF-8 bytes to the end of a file, creating it if necessary. It returns the number of characters appended. Errors can leave partial output; concurrent appends are not guaranteed to be atomic records.

Run this in a scratch directory: it replaces plenty-log.txt before appending.

def log_example() -> Result[str, IoError]:
    write_text("plenty-log.txt", "started\n")?
    append_text("plenty-log.txt", "finished\n")?
    read_text("plenty-log.txt")

def main() -> Result[(), AllocError | IoError]:
    print(str.repr(log_example())?)?
    Ok(())

Result[str, IoError].Ok("started\nfinished\n")

Open a file for a block

with open(path)? as file makes a stream available inside the indented block. It closes on exit, including on return, ?, break, or continue. The stream reference cannot escape the block.

open(path) opens an existing file for reading. open(path, "w") creates or truncates a file, and open(path, "a") creates or appends. Each returns Result[File, IoError]. Files move on assignment and cannot be copied.

read() returns text from the current position through EOF, translating CRLF and bare CR to LF and validating UTF-8. At EOF it returns an empty string.

Run this in a scratch directory: it replaces plenty-reading.txt.

def read_example() -> Result[str, IoError]:
    write_text("plenty-reading.txt", "hello\r\nworld")?
    with open("plenty-reading.txt")? as file:
        return Ok(file.read()?)

def main() -> Result[(), IoError]:
    print(read_example()?)?
    Ok(())

hello
world

The returned text owns its storage and survives closing the file. Read errors may consume input before failing. File I/O requires Linux.

Reading lines

readline() keeps the terminating newline, translating LF, CRLF, and bare CR to "\n". An empty line is "\n"; EOF is "". The last line need not have a terminating newline. Unlike input(), line reading retains that terminator.

Run this in a scratch directory: it replaces plenty-lines.txt.

def count_lines() -> Result[i64, IoError | OverflowError[i64]]:
    write_text("plenty-lines.txt", "first\r\n\rfinal")?
    mut count = 0
    with open("plenty-lines.txt")? as file:
        while True:
            line = file.readline()?
            if line == "":
                break
            count = count + 1
    Ok(count)

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    print(count_lines()?)?
    Ok(())

3

readline() and read() share newline state. Their errors may consume input; retrying is not a rollback. Direct for line in file iteration is unsupported. For size-limited reads and saved positions, see the text I/O reference.

Write through a file

Use a writable stream when several writes belong to one open file. write(text) returns the number of Unicode characters written and preserves exact UTF-8 bytes, including newlines. Mode "w" replaces a file; "a" appends to it.

Run this in a scratch directory: it replaces plenty-stream.txt.

def main() -> Result[(), IoError]:
    with open("plenty-stream.txt", "w")? as file:
        print(file.write("hello\n")?)?
        file.write("world\n")?
        file.close()?
    with open("plenty-stream.txt", "a")? as file:
        file.write("goodbye\n")?
    print(read_text("plenty-stream.txt")?)?
    Ok(())

6
hello
world
goodbye

Call close()? to report a close error; automatic cleanup cannot report it. Exiting the block can then close the already closed file harmlessly.

For flushing, disk synchronization, and other detailed contracts, see the text I/O reference.

Context managers

Define __enter__ and __exit__ to make a class usable with with. Entry supplies the as value; exit takes only a mutable receiver and returns (). No inheritance or protocol declaration is needed.

class Message:
    text: str
    def __enter__(self: &mut Message) -> str:
        drop(print("enter"))
        self.text
    def __exit__(self: &mut Message) -> ():
        drop(print("exit"))

def main() -> Result[(), IoError]:
    with Message("hello") as text:
        print(text)?
    print("after")?
    Ok(())

enter
hello
exit
after

The manager moves into the block. Body locals and the entry value clean up before __exit__; the manager drops afterward, including on early exits. An owned entry value can move out, for example through return. The as binding is local to the body; omit it for unit entry methods.

with acquire()?: propagates acquisition failure without entering the context.

The lifecycle trace uses drop(print(...)) deliberately: cleanup cannot return an error, and a failed diagnostic write must not interrupt cleanup. For output that must succeed, provide an explicit fallible operation and propagate its result before leaving the scope.

Borrow and combine context managers

To keep a manager after the block, borrow it explicitly. The original binding is exclusively borrowed until exit completes.

class Stage:
    marker: i64
    def __enter__(self: &mut Stage) -> i64:
        self.marker = 1
        self.marker
    def __exit__(self: &mut Stage) -> ():
        self.marker = 11

def main() -> Result[(), IoError]:
    mut stage = Stage(0)
    with &mut stage as n:
        print(n)?
    print(stage.marker)?
    Ok(())

1
11

Stage records lifecycle markers, not an accumulating counter: enter assigns 1 and exit assigns 11, including on repeated uses. Cleanup performs no fallible arithmetic.

Several managers can share one with statement. They enter from left to right and exit from right to left, just like nested blocks. Later manager expressions can use earlier as bindings.

class Label:
    text: str
    def __enter__(self: &mut Label) -> str:
        drop(print(self.text))
        self.text
    def __exit__(self: &mut Label) -> ():
        drop(print(self.text))

def main() -> Result[(), IoError]:
    with Label("first") as first, Label("second") as second:
        print("body")?
    Ok(())

first
second
body
second
first

Exit is infallible and cannot suppress errors. Check fallible writes or flushes explicitly. Fatal traps do not run exits, and yield inside with is not yet supported.

__enter__ can return a reference to the manager, giving the body access to its methods and fields while with keeps ownership. The reference cannot escape.

class Counter:
    count: i64
    def __enter__(self: &mut Counter) -> &mut Counter:
        &mut self
    def __exit__(self: &mut Counter) -> ():
        drop(print(self.count))

def main() -> Result[(), IoError]:
    with Counter(1) as counter:
        counter.count = 7
    Ok(())

7

The lifecycle trace uses drop(print(...)) deliberately: cleanup cannot return an error, and a failed diagnostic write must not interrupt cleanup. For output that must succeed, provide an explicit fallible operation and propagate its result before leaving the scope.

Build a small command-line application

Put one integer on each line of an input file. This program ignores blank lines, adds the integers, and writes a short report to an output file. Its two arguments are the input and output paths. Running it without arguments prints usage.

Test for EOF before stripping whitespace: a blank line should be ignored, not mistaken for the end of the file.

Save this module as report.plenty:

pub def summarize(path: &str) -> Result[str, AllocError | IoError | ParseError | OverflowError[i64]]:
    mut count = 0
    mut total = 0
    with open(path)? as file:
        while True:
            line = file.readline()?
            if line == "":
                break
            cleaned = line.strip()?
            if cleaned == "":
                continue
            total = total + i64.parse(cleaned)?
            count = count + 1
    Ok(f"count={count} total={total}\n"?)

Save this application beside it as main.plenty:

from report import summarize

enum UsageError:
    Arguments

type AppError = AllocError | IoError | ParseError | OverflowError[i64] | UsageError

def run() -> Result[(), AppError]:
    arguments = args()?
    if len(arguments) == 1:
        print("usage: number-report INPUT OUTPUT")?
        return Ok(())
    if len(arguments) != 3:
        write_stderr("usage: number-report INPUT OUTPUT\n")?
        return Err(UsageError.Arguments)
    report = summarize(arguments[1])?
    write_text(arguments[2], report)?
    print("saved report")?
    Ok(())

def main() -> Result[(), AppError]:
    run()

usage: number-report INPUT OUTPUT

Run the application with its arguments:

plenty script main.plenty numbers.txt report.txt

To make it directly executable on Unix, add #!/usr/bin/env -S plenty script as its first line, then run chmod +x main.plenty. Runner options precede the filename; everything after it belongs to your application. See single-file scripts for optional dependency metadata and locks.

For a retained native binary instead:

plenty --compile main.plenty -o number-report
./number-report numbers.txt report.txt

For an input containing 10, a blank line, and 20, the output file contains count=2 total=30 followed by a newline. write_text replaces the output file; choose a path whose contents may be replaced.

AppError preserves usage, parsing, I/O, allocation, and arithmetic errors. Returning the error from main reports its cause on standard error and exits unsuccessfully. run prints "saved report" only after writing succeeds. It propagates failures to main so a failed operation cannot accidentally become a successful exit. Values and their total must fit i64; overflow propagates as OverflowError[i64]. The output file is not opened until the whole input has been summarized successfully.

Checking the argument count directly keeps this two-path interface simple. For named options and typed argument values, use the typed command-line parser. The explicit readline loop shows EOF handling for one file. For buffered line iteration across multiple files or stdin, use std.cli.fileinput; each loop item is a Result that you handle with line?.

See the text I/O reference for file contracts and limits.

Check the application processing module

Test the processing module without command-line arguments. Save its companion as report_demo.plenty:

pub def summarize(path: &str) -> Result[str, AllocError | IoError | ParseError | OverflowError[i64]]:
    mut count = 0
    mut total = 0
    with open(path)? as file:
        while True:
            line = file.readline()?
            if line == "":
                break
            cleaned = line.strip()?
            if cleaned == "":
                continue
            total = total + i64.parse(cleaned)?
            count = count + 1
    Ok(f"count={count} total={total}\n"?)

Run this application in a scratch directory; it replaces numbers.txt and report.txt:

from report_demo import summarize

def main() -> Result[(), AllocError | IoError | ParseError | OverflowError[i64]]:
    write_text("numbers.txt", "10\r\n\r\n20\r\n")?
    report = summarize("numbers.txt")?
    write_text("report.txt", report)?
    write_stdout(read_text("report.txt")?)?
    Ok(())

count=2 total=30

Keep bytes separate from text

Use list[u8] when data may contain invalid UTF-8. Encoding text copies its exact UTF-8 bytes; decoding validates every byte. Both operations observe their input, so you can keep the original data.

def main() -> Result[(), IoError]:
    text = "é\r\n"
    bytes = encode_utf8(text)?
    print(len(bytes))?
    print(decode_utf8(&bytes)? == text)?
    print(len(bytes))?
    invalid = encode_utf8("x")?
    mut raw = invalid
    raw[0] = 255u8
    match decode_utf8(&raw):
        case Ok(_):
            print("unexpected text")?
        case Err(error):
            print(error)?
    Ok(())

4
True
4
IoError.Data(DataError.InvalidUtf8)

On Unix, filenames and executable arguments can contain arbitrary bytes except NUL. Use args_bytes() to obtain those arguments, then pass a path byte list to read_bytes(path) or write_bytes(path, contents). These helpers preserve file contents and names without text decoding or newline conversion. They currently support Linux. write_bytes creates or replaces its destination.

For supplied paths on stdin, use input_bytes(0u8). It returns one NUL-delimited record as Some(record) or Nothing at EOF. Write records with write_stdout_bytes(&record) followed by write_stdout_bytes(b"\0"). Finish with flush_stdout()?. Empty records are distinct from EOF; a final nonempty unterminated record is accepted.

CR, LF, and invalid UTF-8 remain part of the path. Keep the original bytes when opening files, even if you separately decode or format them for display. The finder experiment includes a working --null mode. Its globs match bytes in that mode, so ? matches one byte.

See the binary I/O reference for partial effects, allocation failures, and remaining library limits.

Enumerate and classify paths

Use std.path to represent a native path and std.fs to enumerate it lazily. Each generator item is a Result because advancement can fail after opening:

import std.fs as fs
import std.path as path

def main() -> Result[(), AllocError | IoError]:
    write_text("sample.txt", "abc")?
    root = path.from_text(".")?
    for result in fs.entries(fs.read_dir(&root)?):
        entry = result?
        name = entry.file_name()?
        if name.to_text()? == "sample.txt":
            print(entry.file_type()? == fs.FileType.File)?
            print(entry.metadata()?.size())?
    Ok(())

True
3

entries consumes the directory owner. Exhaustion closes it; an early break, return or propagated error drops it. Keep a named mutable ReadDir when you want manual next() calls or explicit close(). Entries own their data and remain valid after the directory closes. Enumeration includes dot-prefixed names and has unspecified order.

entry.file_type() and entry.metadata() inspect a symlink itself. fs.metadata(&path) follows its target; fs.symlink_metadata(&path) does not. A dangling link can therefore be inspected without requiring its target. Types distinguish regular files, directories, links and other native objects.

Path text conversion is checked. For arbitrary Unix filenames, use name.as_bytes() and NUL-framed transport, avoiding text decoding. These filesystem APIs currently require 64-bit Linux and statx for metadata. See the directory reference.

Use fs.symlink to create a link and fs.canonicalize when you need its resolved absolute name. Relative link targets are relative to the link’s parent:

import std.fs as fs
import std.path as path

def main() -> Result[(), IoError]:
    write_text("original.txt", "data")?
    target = path.from_text("original.txt")?
    link = path.from_text("alias.txt")?
    fs.symlink(&target, &link)?
    print(fs.read_link(&link)?.to_text()?)?
    resolved = fs.canonicalize(&link)?
    print(resolved.is_absolute(), fs.metadata(&resolved)?.size())?
    Ok(())

original.txt
True 4

Canonicalization requires existing components and can fail for dangling links or loops. Its result can become stale immediately: it does not secure a later open against replacement. For operations through a held directory, use rooted filesystem helpers. The metadata and links reference documents native path limits and error behavior.

Use temporary files and directories

Use std.tempfile when a task needs scratch storage. A with statement owns the resource until its body ends and then cleans it up, including on an early return or an error propagated with ?.

For a tool that needs a filename, use named_file. You can write through the owner and pass its path to other code while the owner is alive:

import std.tempfile
import std.io
import std.fs

def main() -> Result[(), AllocError | IoError | std.fs.FsError | std.io.Partial]:
    with std.tempfile.named_file(suffix=".txt")? as temporary:
        std.io.write_all(temporary, &b"hello")?
        print(read_text(&temporary.path().to_text()?)?)?
        temporary.close()?
    Ok(())

hello

The explicit close()? reports cleanup failures. Without it, leaving with still attempts cleanup, but cannot report an error from that attempt. For a stream with no filename, with std.tempfile.file()? as stream: lends a std.io.FileStream instead.

A temporary directory can contain an entire working tree. Cleanup removes its contents recursively; symlinks do not cause traversal outside that tree:

import std.tempfile
import std.path
import std.fs

def main() -> Result[(), AllocError | IoError | std.fs.FsError]:
    with std.tempfile.directory()? as scratch:
        note = scratch.path().join(&std.path.from_text("note.txt")?)?
        write_text(&note.to_text()?, "working copy")?
        print(read_text(&note.to_text()?)?)?
        scratch.cleanup()?
    Ok(())

working copy

To preserve a named file or directory, call keep()? before cleanup. It returns an owned path and transfers responsibility for removing it to your code. Use the parent keyword argument to choose a directory explicitly. Otherwise, the module uses the first nonempty TMPDIR, TEMP, or TMP, falling back to /tmp when none is set.

See the reference for cleanup budgets, Linux filesystem requirements, and the trusted-parent requirement. For atomic publication of a completed file, continue with filesystem staging.

Stage files and clean temporary directories

Open a std.fs.Root to anchor operations to a directory. Child names are single-component lossless paths: no slash, NUL, . or ... Child opens reject symlinks. The initial root’s ancestors remain the caller’s trust decision.

An anonymous temporary file has no name until publish succeeds. Publication refuses an existing destination. Returning early before publication closes the file and releases its partial contents without deleting a named path.

This example uses a random private directory inside the working directory:

import std.io

import std.fs as fs
import std.path as path
from std.sync import CancellationToken

def main() -> Result[(), AllocError | IoError | std.io.StreamError | fs.FsError]:
    current = path.from_text(".")?
    parent = fs.root(&current)?
    prefix = path.from_text("plenty-example-")?
    mut directory = fs.temporary_dir(&parent, &prefix, 8)?
    original = path.from_text("original.txt")?
    copied = path.from_text("copied.txt")?
    mut staged = fs.temporary_file(directory.root())?
    staged.stream.file.write("hello")?
    staged.publish(&original)?
    staged.close()?

    cancel = CancellationToken()?
    print(fs.copy_file(directory.root(), &original, &copied, 1024, &cancel, preserve=fs.CopyMetadata.PermissionsAndTimes)?)?
    pattern = path.from_text("*.txt")?
    names = fs.glob(directory.root(), &pattern, 10, 10, 1000)?
    print(len(names))?
    directory.root().remove_file(&original)?
    directory.root().remove_file(&copied)?
    directory.cleanup()?
    Ok(())

5
2

These operations require Linux, a filesystem supporting O_TMPFILE, and /proc/self/fd for publication. Unsupported environments return errors rather than using a weaker fallback. Single-file copying uses bounded scratch storage, returns errors for byte limits/cancellation, and leaves no partial destination name. To preserve ordinary permission bits and access/modification times, pass preserve=fs.CopyMetadata.PermissionsAndTimes to copy_file; ownership, ACLs, xattrs and special permission bits are excluded.

Temporary-directory cleanup removes only an empty directory. Its destructor is best-effort; call cleanup() when you need to observe failure. Other actors must not rename entries in the parent while the temporary directory is live. An identity check detects existing replacements but is not atomic with rmdir. Use explicit bounded remove_tree only when intentionally deleting contents; it can leave partial progress on cancellation or errors.

See the reference for root contracts, temporary-resource limits, and copy, deletion and glob budgets.

For a directory tree, use copy_tree with explicit entry, depth, byte and handle budgets from copy_limits(). Its default copies contents only. The destination must be new, symlinks and special files are rejected, and a failure after creation leaves partial output for the caller to inspect or remove. The recursive-copy example and recovery contract show the complete call and explain TreeCopyError.Setup versus partial-output Partial/Entry errors.

For cooperating processes that must not operate on a resource simultaneously, use std.fs.lock. Keep the returned owner alive for the protected work. acquire_now reports contention immediately; acquire_before takes a total deadline and a cancellation token. Use a stable lockfile in a trusted directory and leave that file in place after releasing the lock: removing it while another process owns it can split coordination across different inodes. Locks close automatically, and normal subprocesses do not inherit them across exec.

Create a private named file

When a file should be visible immediately and must not already exist, use Root.create_file. Its default 0600 mode prevents group and other access from creation; create_dir defaults to 0700. Both are restricted by the process umask. An existing file, directory or symlink causes an error.

import std.io
import std.fs as fs
import std.path as path

def main() -> Result[(), AllocError | IoError | std.io.StreamError]:
    parent = fs.root(&path.from_text(".")?)?
    name = path.from_text("private-state")?
    parent.create_dir(&name)?
    directory = parent.open_dir(&name)?
    token = path.from_text("token")?
    mut file = directory.create_file(&token)?
    file.file.write("secret")?
    fs.set_file_unix_mode(&file, 0o400u32)?
    file.close()?
    directory.remove_file(&token)?
    parent.remove_dir(&name)?
    Ok(())

set_file_unix_mode changes the held file, so a replacement at its old path cannot redirect the update. Root.set_unix_mode does the same for a directory. Setting a mode does not close the handle or revoke existing access. Unlike staging, a named file remains after a write failure; use the staging pattern when readers must see only complete output. See the permission contracts for custom modes, ACLs, umask and errors.

Watch a directory for changes

Use std.fs.watch when a tool should notice that files changed: a local preview, an indexer, or a configuration reloader. Watch the parent directory when another program might replace a file by renaming a new version over it.

This example watches a temporary directory, writes a file, then inspects the queued batch. It handles overflow by requesting a full rescan instead of assuming every change was delivered:

import std.fs
import std.fs.watch
import std.path
import std.tempfile

def main() -> Result[(), AllocError | IoError | std.fs.FsError | std.fs.watch.WatchError]:
    with std.tempfile.directory()? as scratch:
        mut watcher = std.fs.watch.watcher()?
        watcher.add(scratch.path())?
        note = scratch.path().join(&std.path.from_text("note.txt")?)?
        write_text(&note.to_text()?, "hello")?
        count = watcher.poll()?
        for index in range(count):
            event = watcher.event(index)?
            if event.overflowed():
                print("rescan the directory")?
            elif event.created():
                print("created", event.name.to_string()?)?
        watcher.close()?
        scratch.cleanup()?
    Ok(())

created note.txt

poll() never waits. For a long-running program, use wait(&deadline, &cancel) with a std.time deadline and cancellation token, or register the watcher with a std.ready.Selector. Consume the batch before the next call: event(index) copies its name, so saved events remain valid. The default buffer bounds each read to 4 KiB, and polling does not allocate.

A directory watch covers its immediate children, not an entire tree. Events may be coalesced and an event’s path may have changed again before you read it. Treat notifications as a reason to check the current filesystem state, rather than as a complete history. Names retain native bytes; the example uses display() so a non-UTF-8 name does not prevent reporting the change.

See the reference for rename cookies, watch lifecycle events, overflow recovery, and resource limits.

Prune before descending

The small companion files provide two fixture directories. Run the program from an empty work/ child of the directory containing these files; the root below uses .. to reach the fixture without changing the working directory:

pub const value: i64 = 1

pub const value: i64 = 2

With a top-down walker, edit its directory list before asking for another row:

import std.fs as fs
import std.path as path

def main() -> Result[(), AllocError | IoError | fs.WalkError | OverflowError[i64]]:
    root = path.from_text("../tree")?
    mut walker = fs.walk(&root, True)?
    while walker.next()?:
        print(walker.current.path.to_text()?)?
        mut index = len(walker.current.directories) - 1
        while index >= 0:
            if walker.current.directories[index].to_text()?.endswith("/pruned"):
                drop(walker.current.directories.pop(index))
            index = index - 1
    walker.close()
    print(walker.next()?)?
    Ok(())

../tree
../tree/kept
False

False passed to fs.walk requests bottom-up order. Editing a bottom-up row cannot undo descent. Child directory links appear in current.files, and are never followed; a link to an ancestor cannot make this walker loop. An explicit root may itself resolve through a link.

To continue siblings after an error, match walker.next() instead of using ?:

import std.fs as fs
import std.path as path

def main() -> Result[(), AllocError | IoError | fs.WalkError]:
    root = path.from_text("missing-root")?
    mut walker = fs.walk(&root, True)?
    match walker.next():
        case Ok(found):
            print(found)?
        case Err(error):
            match error:
                case fs.WalkError.Io(at, operation, cause):
                    print(at.to_text()?)?
                    print(operation)?
                    print(cause)?
                case fs.WalkError.Allocation(cause):
                    print(cause)?
    print(walker.next()?)?
    Ok(())

missing-root
read_dir
IoError.System(2)
False

The failed subtree is already skipped. Another call continues any pending siblings. Propagating the error stops traversal with normal cleanup. Only the current scan owns a native directory stream; retaining results does not retain directory handles. See walking contracts.

Say which operation failed

IoError.System(2) says a file was missing, but not which file or which step wanted it. std.error wraps an error in a Context holding an operation label and, optionally, a path. The original error stays inside as cause, with its type.

from std.error import Context, Subject, context, path_context, native_code
from std.path import Path, from_text

def read_limit(path: &Path) -> Result[list[u8], Context[IoError]]:
    path_context(read_bytes(path.as_bytes()), "read limit", path)

def parse_limit(text: &str) -> Result[i64, Context[ParseError]]:
    context(i64.parse(text), "parse limit")

def flush_output() -> Result[(), Context[IoError]]:
    context(flush_stdout(), "flush output")

def limit(path: &Path) -> Result[i64, AllocError | IoError | Context[ParseError]]:
    match read_limit(path):
        case Ok(bytes):
            Ok(parse_limit(&decode_utf8(bytes)?)?)
        case Err(error):
            print(error.describe()?)?
            print(native_code(error.cause))?
            Ok(10)

def run() -> Result[(), AllocError | IoError | Context[IoError] | Context[ParseError]]:
    path = from_text("limit.txt")?
    print(limit(&path)?)?
    match parse_limit("ten"):
        case Ok(value):
            print(value)?
        case Err(error):
            print(error.describe()?)?
            print(error.cause == ParseError.Invalid)?
    flush_output()?
    Ok(())

def main() -> i32:
    match run():
        case Ok(_):
            0i32
        case Err(cause):
            Context("run", Subject.Absent, cause).report()
            1i32

read limit "limit.txt": IoError.System(2)
Option[i32].Some(2)
10
parse limit: ParseError.Invalid
True

context(result, label) and path_context(result, label, &path) pass an Ok through and wrap an Err, including operations whose success is (), as flush_output shows. main uses the direct form, Context(label, Subject.Absent, cause). Nothing is wrapped implicitly: ? needs a compatible declared error, so read_limit returns Context[IoError] and callers can include that context in an error sum.

describe() builds one line: the label, the quoted path if there is one, and the cause. It allocates, so it returns a Result. error.cause is the untouched typed error; match it, compare it, or ask native_code for the OS number.

report() is for the edge of the program. It flushes standard output and writes error: plus the description to standard error. It returns nothing and does not choose an exit status, so main returns i32 and decides. If memory runs out while describing, report still writes the label with a fixed message, and a failed path copy in path_context keeps the label and cause.

Here run preserves its allocation, I/O, and contextual errors in a sum. The outer context adds the operation label without discarding the cause. Return a Context or your own enum when a failure needs more explanation. See the module reference for nesting contexts and the rules standard modules follow.

For a human-readable cause, give its type the public std.report formatting method. Contexts then format their operation labels and delegate to that cause:

from std.error import Context, Subject
from std.fmt import Formatter, FormatError
from std.report import to_string

pub enum SettingsError:
    Invalid

    pub def format[W](self, output: &mut Formatter[W]) -> Result[(), FormatError]:
        output.text("invalid setting")

def main() -> Result[(), FormatError | IoError]:
    inner = Context("parse", Subject.Absent, SettingsError.Invalid)
    outer = Context("load settings", Subject.Absent, inner)
    print(to_string(&outer, 120, 8)?)?
    print(to_string(&outer, 120, 8)?)?
    Ok(())

load settings: parse: invalid setting
load settings: parse: invalid setting

Formatting borrows both contexts and includes the cause once. Returning an Err with this context type from main selects the same wording automatically, with the entrypoint’s prefix and newline. A context whose cause has no formatting method still uses structural entrypoint reporting. The existing describe, describe_with, report and report_with methods keep their behavior.

Without a path, context formatting adds no allocation. A present path still uses fallible Path.display; failure leaves the typed cause intact and may leave part of the report already written. See bounded reports for limits and failure handling.

Pack bytes in a compact buffer

For a binary record, frame, or file body, std.bytes.Bytes provides checked byte-range operations and works with byte-oriented I/O. Its contiguous buffer stores one byte per element. A list[u8] also packs its elements into bytes; use its ordinary list operations and element references when those suit the task.

import std.bytes
from std.bytes import Bytes, BytesError

def checksum(view: &Bytes, start: i64, stop: i64) -> Result[i64, OverflowError[i64]]:
    mut total = 0
    for index in range(start, stop):
        total += i64(view.get(index))
    Ok(total)

def main() -> Result[(), AllocError | IoError | BytesError | OverflowError[i64]]:
    mut frame = std.bytes.with_capacity(8)?
    frame.push(2u8)?
    frame.extend(&std.bytes.from_text("hi")?)?
    frame.push(0u8)?
    frame.push(255u8)?
    print(frame.len(), frame.capacity(), frame)?
    print(checksum(&frame, 1, 3)?)?
    payload = frame.slice(1, 3)?
    print(payload.to_text()?)?
    print(str.repr(frame.to_text())?)?
    Ok(())

5 8 b"\x02hi\x00\xff"
209
hi
Result[str, std.bytes.BytesError].Err(std.bytes.BytesError.InvalidUtf8)

Growth and copies can fail to allocate, so they return AllocError; to_text returns BytesError. A range is start up to but not including stop, and must lie inside the buffer: there are no negative offsets and nothing is clamped. A range outside the buffer, such as checksum(&frame, 3, 9) on five bytes, is a bug in the caller, so it stops the program with a trap report naming the method, Bytes.get: index is outside 0..len(), and your calling line. Check a range that comes from input first and return your own error. slice and copy make independent buffers; nothing is copied unless you ask. to_text succeeds only for valid UTF-8, and a zero byte is ordinary data. Printing a buffer spells it as a byte literal, with \xhh for bytes that are not printable ASCII; for hex output, see printing bytes.

checksum shows how to work on part of a buffer: borrow it and pass the range. While that borrow is in use the owner cannot change, so growth can never move bytes out from under a reader:

import std.bytes

def main() -> Result[(), AllocError | IoError | std.bytes.BytesError]:
    mut frame = std.bytes.from_text("hi")?
    view = &frame
    frame.push(0u8)?
    print(view.len())?
    Ok(())

conflicting borrow: cannot modify or exclusively borrow `frame` while it is borrowed

File-reading and argument builtins still return list[u8]; from_list converts one with an explicit copy. The output builtins write_stdout_bytes, write_stderr_bytes and write_bytes take a &[u8] view, so pass a buffer or a range of it with no conversion:

import std.bytes

def main() -> Result[(), AllocError | IoError]:
    mut record = std.bytes.from_list(&encode_utf8("name=")?)?
    record.extend(b"\xff\0")?
    write_stdout_bytes(&record[0:5])?
    print(record.len(), record.find(61u8, 0, record.len()))?
    Ok(())

name=7 Option[i64].Some(4)

A parser should not call get once per byte: each call costs far more than the comparison it feeds. The scans search a whole range in one call and return an absolute index. find_in stops at any byte of a set, find_not_in at the end of a run, and matches_text compares in place without copying. to_text_range copies one range out as checked text, with no intermediate Bytes:

import std.bytes

def main() -> Result[(), AllocError | IoError | std.bytes.BytesError | OverflowError[i64]]:
    line = std.bytes.from_text("name=Ada;  role=engineer")?
    stops = std.bytes.from_text("=;")?
    blank = std.bytes.from_text(" ")?
    mut at = 0
    while at < line.len():
        match line.find_in(&stops, at, line.len()):
            case Some(index):
                print(index, line.to_text_range(at, index)?)?
                at = index + 1
            case Nothing:
                print("rest", line.to_text_range(at, line.len())?)?
                at = line.len()
    print(line.find_not_in(&blank, 9, line.len()))?
    print(line.matches_text(11, "role"), line.count(32u8, 0, line.len()))?
    Ok(())

4 name
8 Ada
15   role
rest engineer
Option[i64].Some(11)
True 2

Index syntax reads and writes single bytes, with the same rules as a list index: a negative index counts from the end, and a missing one stops the program with index out of bounds. Iterating over &buffer reads each byte without consuming the buffer:

import std.bytes

def main() -> Result[(), AllocError | IoError | std.bytes.BytesError | OverflowError[u8] | OverflowError[i64]]:
    mut word = std.bytes.from_text("plenty")?
    word[0] = 80u8
    word[-1] -= 32u8
    print(word.to_text()?, word[1])?
    mut vowels = 0
    for b in &word:
        if b == 101u8 or b == 89u8:
            vowels += 1
    print(vowels)?
    word.fill(1, 5, 46u8)
    print(word.to_text()?)?
    Ok(())

PlentY 108
2
P....Y

get and set take the same checked index without counting from the end. for b in &mut word yields &mut u8 references into the buffer, so *b = 0u8 in its body clears every byte in place. A slice such as word[1:3]? copies with the list rules, clamping its bounds. The slice method keeps the range rule instead: frame.slice(1, 3)? copies exactly that range, and a range outside the buffer traps. Both report only AllocError.

Fixed binary data, such as a file signature or a protocol delimiter, is written as a byte literal: b"..." holds ASCII characters, the string escapes, and \xHH for any other byte. Its type is bytes, an immutable value in the program’s read-only data, so it never allocates. It has a length, indexing, and iteration:

import std.bytes

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    magic = b"\x89PNG"
    print(magic, len(magic), magic[1])?
    mut total = 0
    for byte in magic:
        total += i64(byte)
    print(total)?
    Ok(())

b"\x89PNG" 4 80
366

Operations that only read another sequence of bytes, such as find_bytes, matches, find_in, and extend, take a literal as readily as a buffer. Their parameter is a &[u8] slice view: a literal, &buffer, or part of either, &buffer[a:b], converts to it, so each call reads the bytes where they are and nothing is copied. Your own functions can accept every form the same way:

import std.bytes

def starts_png(data: &[u8]) -> bool:
    len(data) >= 4 and data[0] == 137u8 and data[1] == 80u8

def main() -> Result[(), AllocError | IoError]:
    magic = b"\x89PNG"
    mut header = std.bytes.from_bytes(&magic)?
    header.extend(b"\r\n\x1a\n")?
    print(header.find_bytes(b"\r\n", 0, header.len()))?
    print(header.matches(0, &magic[:4]), header.find_in(b"\n\r", 0, header.len()))?
    print(starts_png(&header), starts_png(&header[4:]), starts_png(b"GIF8"))?
    Ok(())

Option[i64].Some(4)
True Option[i64].Some(4)
True False False

The literal is never converted into a Bytes behind your back. To change bytes, or to call a Bytes method such as find on them, copy any view with from_bytes, as header does; the copy allocates, so it returns a Result. A slice of a literal, such as b"GET /index"[4:]?, is also an owned Bytes. Stream writes in std.io accept a literal the same way, as the next lessons show.

A byte literal accepts only ASCII characters, so b"é" is an error; use from_text for the UTF-8 encoding of text. See byte literals for the full rules.

See the module reference for every operation, its costs, and what views cannot do yet.

Build and normalize bounded text

std.text offers a reusable UTF-8 builder. Its limit counts bytes: é takes two bytes and 🙂 takes four. A failed append leaves the old contents intact.

import std.text
import std.unicode

def main() -> Result[(), AllocError | IoError | std.text.TextError]:
    mut message = std.text.builder(32)?
    message.append("Hello, ")?
    message.append("é🙂")?
    print(message.to_text()?, message.byte_len())?
    message.clear()
    message.append("again")?
    print(message.finish()?)?
    words = ["one", "two", "three"]?
    print(std.text.join(&words, " / ", 32)?)?
    print(str.repr(std.text.hard_wrap("é🙂abc", 2, 32)?)?)?
    print(std.unicode.version())?
    print(std.unicode.nfc("é", 16)? == "é")?
    print(std.unicode.nfkc("ffi", 16)?)?
    Ok(())

Hello, é🙂 13
again
one / two / three
"é🙂\nab\nc"
17.0.0
True
ffi

Use to_text() for a snapshot when keeping the builder, and finish() when done. finish consumes it even if allocating the final string fails; to_text keeps it available for retry. Both currently copy the output bytes.

hard_wrap counts Unicode scalars, preserves LF, and can split a combining sequence; it does not measure terminal columns or find word boundaries. Normalization has a separate scalar limit covering the input and decomposed intermediate. For example, decomposing é needs room for two scalars even though NFC can compose them back to one. Every operation remains fallible: use ? or match TextError to handle allocation, invalid limits, and output that exceeds them.

Normalization never happens automatically. NFC treats canonically equivalent spellings consistently; NFKC also removes compatibility distinctions such as the ligature above. Choose it only when that loss is intended. Byte decoding still rejects malformed UTF-8 before normalization; embedded NUL is ordinary text. See std.text and std.unicode for costs and complete contracts.

For prose, use fill to wrap at word boundaries. shorten collapses whitespace and truncates to one line; dedent removes a common space/tab margin. These helpers use default input and output caps of 1 MiB, which you can change with max_input_bytes and max_bytes.

import std.text

def main() -> Result[(), IoError | std.text.TextError]:
    print(std.text.fill("one two three four", 9)?)?
    print(std.text.shorten("one two three four", 13)?)?
    print(std.text.indent(&std.text.dedent("    first\n      second")?, "> ")?)?
    Ok(())

one two
three
four
one two [...]
> first
>   second

Widths count scalars rather than display columns. Use a reusable TextWrapper when you need indentation, tab options, or a maximum number of lines. Wrap each paragraph separately: the default settings treat input newlines as spaces.

Read and write streams in pieces

A file, a pipe, or a terminal rarely moves all the bytes you ask for in one call. std.io makes that visible: one read or write reports how many bytes it moved, and helpers repeat the call until a range is complete.

A stream is any pub class with the right methods. This one hands out its text at most three bytes at a time, as a slow pipe would:

import std.bytes
import std.io
from std.bytes import Bytes
from std.io import StreamError

pub class Trickle:
    pub data: Bytes
    pub at: i64

    pub def read(self: &mut Trickle, buffer: &mut Bytes, start: i64, stop: i64) -> Result[i64, StreamError]:
        if start < 0 or start > stop or stop > buffer.len():
            return Err(StreamError.OutOfRange)
        if self.at < 0 or self.at > self.data.len():
            return Err(StreamError.OutOfRange)
        # Valid ranges give nonnegative differences <= i64.MAX.
        # count <= stop-start and <= data.len()-at, so both ends stay in range.
        unchecked:
            mut count = stop - start
            if count > 3:
                count = 3
            if count > self.data.len() - self.at:
                count = self.data.len() - self.at
            buffer.overwrite(start, &self.data[self.at:self.at + count])
            self.at += count
            Ok(count)

def main() -> Result[(), AllocError | IoError | StreamError | std.bytes.BytesError]:
    mut source = Trickle(std.bytes.from_text("0123456789")?, 0)
    mut buffer = std.bytes.with_capacity(8)?
    buffer.resize(8, 46u8)?
    print(source.read(&mut buffer, 0, 8)?, buffer.to_text()?)?
    print(str.repr(std.io.read_exact(&mut source, &mut buffer, 0, 4))?, buffer.to_text()?)?
    print(str.repr(std.io.read_exact(&mut source, &mut buffer, 0, 8))?)?
    print(source.read(&mut buffer, 0, 8)?)?
    Ok(())

3 012.....
Result[(), std.io.Partial].Ok(()) 3456....
Result[(), std.io.Partial].Err(std.io.Partial(completed=3, cause=std.io.StreamError.UnexpectedEof))
0

read fills part of buffer[start:stop] and returns the count. A reader checks the range itself and reports OutOfRange, as the stream contract requires; overwrite would otherwise trap on it. Three of eight bytes is a short read, not an error; zero means end of input. read_exact calls read until the range is full. When the input ends first, the error says how many bytes arrived, and they are in the buffer.

Writing has the same shape. write may accept only part of a range, and write_all continues until all of it is delivered. A BufWriter collects small writes in a fixed-size buffer and passes them on in larger pieces:

import std.bytes
import std.io

def main() -> Result[(), IoError | AllocError | std.io.Partial | std.io.StreamError | std.bytes.BytesError | OverflowError[i64]]:
    mut input = std.io.buffered_reader(std.io.cursor(std.bytes.from_text("red\ngreen\nblue")?), 4)?
    mut output = std.io.buffered_writer(std.io.stdout(), 16)?
    mut line = std.bytes.empty()?
    mut count = 0
    while input.read_until(10u8, &mut line, 64)? > 0:
        count += 1
        std.io.write_all(&mut output, b"line: ")?
        std.io.write_all(&mut output, &line)?
        line.clear()
    std.io.write_all(&mut output, b"\n")?
    output.flush()?
    print(count, output.pending(), output.capacity())?
    Ok(())

line: red
line: green
line: blue
3 0 16

write_all takes the byte literal b"line: " as readily as the buffer line: a stream’s write reads a &[u8] view in place, so it also takes part of a buffer, &line[:3]. A class of your own becomes a writer with a flush method and a write method taking source: &[u8] that returns how many bytes it accepted; the module reference shows one.

cursor turns a Bytes into a stream, which is how to test stream code without a file. read_until appends one line, including its newline, and never more than the limit of 64 bytes, so a file with no newline cannot exhaust memory. Both buffers are allocated once, with the capacity you pass, and never grow. Output reaches the terminal when the buffer fills and at flush, so flush before printing anything that must come after it.

Bytes held by a BufWriter are not written when it goes out of scope. Call flush, or close_buffered for a stream that also needs closing:

import std.bytes
import std.io
from std.io import SeekFrom

type ByteTransferError = std.io.Partial | std.bytes.BytesError | std.io.StreamError

def main() -> Result[(), AllocError | IoError | ByteTransferError]:
    mut file = std.io.buffered_writer(std.io.open_file("streams-lesson.bin", "w+")?, 8)?
    record = std.bytes.from_list(&[1u8, 0u8, 255u8, 10u8, 7u8]?)?
    std.io.write_all(&mut file, &record[:5])?
    print(file.pending(), std.io.seek_writer(&mut file, SeekFrom.Start(2))?, file.pending())?
    mut back = std.bytes.with_capacity(3)?
    back.resize(3, 0u8)?
    std.io.read_exact(&mut file.inner, &mut back, 0, 3)?
    print(back.to_list()?)?
    print(str.repr(std.io.close_buffered(&mut file))?)?
    print(str.repr(file.flush())?)?
    Ok(())

5 2 0
[255, 10, 7]
Result[(), std.io.CloseError].Ok(())
Result[(), std.io.StreamError].Err(std.io.StreamError.Io(IoError.Closed))

Five bytes wait in the buffer until seek_writer delivers them and moves the file to byte 2. File streams carry raw bytes: 255 and the newline byte come back unchanged. close_buffered flushes, closes even when the flush fails, and reports which of the two went wrong.

See the module reference for every error, the copy helper, and the standard stream adapters.

A text filter over files or stdin

For a command-line text filter, let std.cli.fileinput handle the buffered reads, UTF-8 decoding, and owned files:

import std.cli.fileinput as fileinput
from std.cli.fileinput import FileInputError

def main() -> Result[(), IoError | AllocError | FileInputError]:
    for line in fileinput.lines()?:
        write_stdout(line?)?
    flush_stdout()?
    Ok(())

After compiling, pass filenames in order, or pipe text into the executable with no arguments. A filename - selects stdin. The outer ? handles argument-list construction; line? propagates an error while opening, reading, or decoding. Use write_stdout, not print, because lines retain their endings. The final line of a file need not have a newline.

For applications that parse flags, pass the chosen list[Path] to fileinput.files(paths) instead: lines() does not parse options. Both APIs use chunked buffering, not a system call for each character, and decode strict UTF-8. Breaking out closes owned files, never stdin; any bytes read ahead into the iterator’s buffer are discarded, so do not interleave other stdin readers.

For fixed-width in-memory fields, use the binary packet cursor instead of manually tracking offsets or expecting stream reads to be atomic.

A read range must satisfy 0 <= start <= stop <= buffer.len(). Invalid buffer ranges trap before reading; see the stream contract.

Read and write binary packets

A Cursor keeps the byte position for a packet. Its typed operations read or write one complete field, with explicit byte order and no manual offset bookkeeping.

import std.bytes
import std.io
from std.encoding import Endian
from std.io import SeekFrom

def main() -> Result[(), AllocError | IoError | RangeError | std.bytes.BytesError | std.io.BinaryError | std.io.StreamError]:
    payload = b"hello"
    mut packet = std.io.cursor(std.bytes.empty()?)
    packet.write_u8(1u8)?
    # Check that a payload size fits its wire field before converting it.
    packet.write_u32(u32.try_from(len(payload))?, Endian.Big)?
    packet.write_f32(1.5f32, Endian.Big)?
    packet.write_bytes(&payload, 64)?
    drop(packet.seek(SeekFrom.Start(0))?)

    version = packet.read_u8()?
    length = i64(packet.read_u32(Endian.Big)?)
    scale = packet.read_f32(Endian.Big)?
    # A hostile length is rejected before allocating its owned payload copy.
    body = packet.read_bytes(length, 64)?
    packet.require_end()?
    print(version, scale, body.to_text()?, packet.position())?
    Ok(())

1 1.5 hello 14

The checked u32 conversion propagates RangeError if a payload length cannot fit the wire field. read_bytes returns an owned copy because borrowed views cannot escape a method. Scalar fields allocate nothing when storage already has capacity.

If a field is truncated, BinaryError.Truncated reports its position, requested width, and available bytes. The failed operation leaves the cursor in place; previous fields remain consumed. require_end detects unexpected trailing bytes. Raw stream reads and writes and seek use the same position, so they can be interleaved with typed fields when the format calls for them.

Read and write CSV records

std.csv reads a table one record at a time, so a large file never has to fit in memory. A reader sits on any byte stream and fills the same Record on every call:

import std.bytes
import std.csv
import std.io

type CsvInputError = ParseError | std.csv.CsvError | std.bytes.BytesError

def main() -> Result[(), AllocError | IoError | CsvInputError | OverflowError[i64]]:
    text = "item,price,note\r\npen,3,\"blue, fine\"\r\nbook,12,\"says \"\"read me\"\"\"\r\ncard,2,\"two\nlines\"\r\n"
    mut input = std.csv.reader(std.io.cursor(std.bytes.from_text(text)?), &std.csv.rfc4180(), 16)?
    mut record = std.csv.record()?
    input.read(&mut record)?
    print(str.repr(record.texts()?)?)?
    mut total = 0
    while input.read(&mut record)?:
        total += i64.parse(&record.text(1)?)?
        print(record.number(), record.line(), record.text(0)?, str.repr(record.text(2)?)?)?
    print(total, input.records())?
    Ok(())

["item", "price", "note"]
2 2 pen "blue, fine"
3 3 book "says \"read me\""
4 4 card "two\nlines"
17 4

read returns True while there is another record and False at the end of the input. The reader’s buffer is the 16 bytes passed to reader; records longer than that are assembled across several fills. Quoted fields may hold the delimiter, line breaks, and doubled quotes, and arrive without their quoting. The first record is not special, so the program reads the header itself.

Fields are bytes. text(index) checks one field as UTF-8 and returns a copy you own; texts() copies them all. The record itself is overwritten by the next read, which is why read takes it as &mut.

rfc4180() is the usual dialect: comma, double quote, and every record as wide as the first. A record of another width is reported, but it has been read and the reader carries on. Malformed input stops the reader for good:

import std.bytes
import std.csv
import std.io
from std.csv import CsvError

def main() -> Result[(), AllocError | IoError | CsvError | std.bytes.BytesError]:
    text = "a,b\nc\nd,e\nf,g\"h\ni,j\n"
    mut input = std.csv.reader(std.io.cursor(std.bytes.from_text(text)?), &std.csv.rfc4180(), 16)?
    mut record = std.csv.record()?
    mut more = True
    while more:
        outcome = input.read(&mut record)
        match outcome:
            case Ok(found):
                if found:
                    print(str.repr(record.texts()?)?)?
                else:
                    more = False
            case Err(cause):
                print(str.repr(&cause)?)?
                match cause:
                    case CsvError.Width(_, _, _):
                        print("skipped", str.repr(record.texts()?)?)?
                    case _:
                        more = False
    print(str.repr(input.read(&mut record))?)?
    Ok(())

["a", "b"]
std.csv.CsvError.Width(2, 2, 1)
skipped ["c"]
["d", "e"]
std.csv.CsvError.Invalid(std.csv.Fault.BareQuote, std.csv.Position(record=4, field=1, line=4, offset=13))
Result[bool, std.csv.CsvError].Err(std.csv.CsvError.Stopped)

Width(2, 2, 1) says record 2 should have two fields and has one. The Position names the record, the field index, the line, and the byte offset of the stray quote. Record i,j is never reached: after a broken quote there is no trustworthy place to resume.

A writer builds one record from fields and delivers it at end_record. texts does both for a list. Change the dialect’s public fields before creating the writer:

import std.bytes
import std.csv
import std.io
from std.csv import Newline

def main() -> Result[(), AllocError | IoError | std.bytes.BytesError | std.csv.CsvError]:
    mut dialect = std.csv.rfc4180()
    dialect.newline = Newline.Lf
    dialect.max_field = 12
    mut output = std.csv.writer(std.io.stdout(), &dialect)?
    output.texts(&["item", "note"]?)?
    output.texts(&["pen", "blue, fine"]?)?
    output.text("book")?
    output.text("says \"hi\"")?
    output.end_record()?
    print(str.repr(output.texts(&["card"]?))?)?
    print(str.repr(output.text("much too long for a field"))?)?
    raw = std.bytes.from_text("card:plain")?
    output.field(&raw[:4])?
    output.field(&raw[5:10])?
    output.end_record()?
    output.flush()?
    print(output.records())?
    Ok(())

item,note
pen,"blue, fine"
book,"says ""hi"""
Result[(), std.csv.CsvError].Err(std.csv.CsvError.Width(4, 2, 1))
Result[(), std.csv.CsvError].Err(std.csv.CsvError.Rejected(std.csv.Fault.FieldTooLong, 4, 0))
card,plain
4

Only fields that need quotes get them. The one-field record is refused by the width policy and the oversized text by max_field; neither writes anything. field adds a byte range without building a string first. Call flush when you are done: a writer does not flush or close its stream when it goes out of scope.

Limits apply to reading too. A field over max_field bytes or a record over max_record is an error at the byte that does not fit, so a file with a missing closing quote cannot consume all memory.

See the module reference for the exact grammar, every error, the borrowed data() view, and what allocates.

Process XML events

std.xml reads one bounded event at a time from a byte stream. Event text has already been checked as UTF-8 and entity references have been decoded. Match the events your application needs, and keep reading through Eof to check the complete document:

import std.bytes
import std.io
import std.xml
from std.xml import Event

def main() -> Result[(), AllocError | IoError | std.bytes.BytesError | std.xml.XmlError]:
    source = "<items><item>Tea &amp; cake</item><item>Milk</item></items>"
    mut input = std.xml.reader(std.io.cursor(std.bytes.from_text(source)?), &std.xml.limits())?
    mut output = std.xml.writer(std.io.cursor(std.bytes.empty()?), &std.xml.limits())?
    mut done = False
    while not done:
        event = input.next()?
        match &event:
            case Event.Text(text):
                print(*text)?
            case Event.Eof:
                done = True
            case _:
                pass
        output.write(&event)?
    print(output.inner.data.to_text()?)?
    Ok(())

Tea & cake
Milk
<items><item>Tea &amp; cake</item><item>Milk</item></items>

The writer escapes values and checks the element structure. Passing Eof checks that the root has closed and flushes its stream. When constructing events yourself, call finish() after the final element. Events own their strings, so retaining an event also retains its memory.

Choose limits for the input you accept. max_token bounds a complete tag, comment, or text run; max_depth bounds nesting. The reference describes all limits and errors. This example lets errors propagate so malformed input and stream failures remain visible. A failed file writer may have emitted partial output; applications that need replacement only on success should manage a temporary destination.

This reader accepts UTF-8 XML 1.0 without a DTD. It never loads external entities. Namespace prefixes remain literal names, so applications needing namespace URI resolution must supply that policy themselves.

Read the environment and run other programs

std.env reads the variables a program was started with. std.process starts another program from a list of arguments and collects what it prints:

import std.bytes

import std.io

import std.env
import std.process
from std.process import Stdio

def main() -> Result[(), AllocError | IoError | std.bytes.BytesError | std.io.StreamError]:
    print(std.env.get("PLENTY_LESSON_UNSET")?)?
    mut command = std.process.command("printf")?
    command.arg("%s\n")?
    command.arg("two words; echo $HOME | wc")?
    command.stdout(Stdio.Piped)
    mut child = command.spawn()?
    output = child.output(4096)?
    print(output.stdout.to_text()?)?
    print(output.status.success(), output.status.code())?
    Ok(())

Option[str].Nothing
two words; echo $HOME | wc

True Option[i32].Some(0)

An unset variable is Nothing, not an error. Each arg is one argument, delivered byte for byte: the semicolon, the $HOME, and the | are printed, not run, because no shell reads them. Stdio.Piped connects the child’s output to a pipe, and output collects at most 4096 bytes of it and waits for the child to end.

If a configuration supplies arguments as one string, use std.shlex.split to recognize quoted words, then pass them individually to arg. Do not quote arguments passed to arg itself; those quotes would become literal data.

import std.shlex
from std.shlex import ShlexError

def main() -> Result[(), ShlexError | AllocError | IoError]:
    arguments = std.shlex.split("--title 'Two words' --literal '$HOME'")?
    for argument in &arguments:
        print(argument)?
    Ok(())

--title
Two words
--literal
$HOME

split removes word quoting without expanding $HOME or interpreting pipes. std.shlex also provides quote for the cases where one argument must be written into a POSIX shell command string.

To find where to keep settings or caches, ask std.fs.dirs rather than reading HOME yourself: config_dir() and cache_dir() apply the XDG rules and return a Path, or Nothing when the environment names no directory.

When shell syntax is what you want, ask for it by name. shell runs /bin/sh -c with your script. communicate also feeds the child’s input:

import std.io

import std.bytes
import std.process
from std.process import Stdio

def main() -> Result[(), AllocError | IoError | std.io.StreamError | std.bytes.BytesError]:
    mut command = std.process.shell("tr a-z A-Z; echo \"mode: $MODE\" >&2; exit 3")?
    command.env("MODE", "loud")?
    command.stdin(Stdio.Piped)
    command.stdout(Stdio.Piped)
    command.stderr(Stdio.Piped)
    mut child = command.spawn()?
    output = child.communicate(b"quiet words", 4096)?
    print(output.stdout.to_text()?)?
    print(output.stderr.to_text()?)?
    print(output.status.success(), output.status.code())?
    Ok(())

QUIET WORDS
mode: loud

False Option[i32].Some(3)

env sets a variable for this child only. communicate writes the input, reads both outputs as they arrive so that no pipe fills up, and returns the exit status. A nonzero exit code is a normal result: the program ran. Never put text you did not write into a shell script; pass it as an argument or a variable.

A program that cannot be started is an error, and a child that runs too long can be stopped:

import std.time
import std.process

def main() -> Result[(), AllocError | IoError | std.process.WaitError]:
    mut missing = std.process.command("plenty-no-such-program")?
    match missing.spawn():
        case Ok(_):
            print("started")?
        case Err(error):
            print(error)?
    mut sleeper = std.process.command("sleep")?
    sleeper.arg("60")?
    mut child = sleeper.spawn()?
    cancel = CancellationToken()?
    match child.wait_timeout(&std.time.milliseconds(50u32), &cancel)?:
        case Some(_):
            print("ended")?
        case Nothing:
            print("still running")?
    child.kill()?
    status = child.wait()?
    print(status.success(), status.code(), status.signal())?
    Ok(())

IoError.System(2)
still running
False Option[i32].Nothing Option[i32].Some(9)

System(2) is the operating system’s “no such file”. wait_timeout gives up after 50 milliseconds and leaves the child running. kill stops it, and wait collects its status: ended by signal 9, with no exit code. Always wait for a child you started, even after killing it; a dropped Child is not cleaned up.

See the references for std.env and std.process, including pipes you read and write yourself.

To inspect CPU, memory, disk or process information without launching a command, continue to system information.

Read system information

std.system reads Linux’s /proc files into typed values. Open the source once, then ask for the information needed. Each query is fresh and fallible:

import std.system
from std.system import SystemError

def main() -> Result[(), IoError | SystemError]:
    source = std.system.local()?
    cpus = source.cpu_count()?
    memory = source.memory()?
    uptime = source.uptime()?
    print("CPU information available:", cpus > 0)?
    print("Memory information available:", memory.total_bytes > 0u64)?
    print("Uptime available:", uptime.seconds >= 0.0)?
    Ok(())

CPU information available: True
Memory information available: True
Uptime available: True

The example prints checks so its output stays the same on different machines. A monitor can print cpus, memory.total_bytes and uptime.seconds directly. There is no timer or background thread: another call reads another snapshot.

For memory headroom, prefer available_bytes to free_bytes: the kernel’s available estimate includes memory it expects to reclaim. The field is optional because not every source provides it. Here is how to keep absence distinct from zero, using sample values so both paths are visible:

import std.system

def show_available(memory: &std.system.Memory) -> Result[(), IoError]:
    match memory.available_bytes:
        case Some(bytes):
            print("available bytes:", bytes)?
        case Nothing:
            print("available memory is not reported")?
    Ok(())

def main() -> Result[(), IoError]:
    reported = std.system.Memory(8192u64, 1024u64, Some(4096u64), 0u64, 0u64)
    absent = std.system.Memory(8192u64, 1024u64, Nothing, 0u64, 0u64)
    show_available(&reported)?
    show_available(&absent)?
    Ok(())

available bytes: 4096
available memory is not reported

Reads have default byte limits; override them with a named argument such as source.memory(max_bytes=65536). A file that exceeds the limit produces an error, not a truncated record. open_procfs(&path) reads a different procfs mount or captured directory, useful when testing a monitoring tool.

process_ids() returns a bounded, sorted list of visible process IDs. process(pid) reads one status record. Processes can exit between those calls, and access can be denied; handle the SystemError.Io cause rather than treating the whole list as guaranteed live. Use std.process to manage children your program starts.

block_devices() reports device and partition sizes; disk_io() reports counters. Avoid summing whole disks with their partitions. Neither gives free filesystem space. CPU and memory values can describe the host even inside a container; they are not cgroup quota measurements or a recommendation for how many workers to start.

See std.system for fields, units, error variants and snapshot limitations.

Store records in SQLite

For a dedicated file of byte-keyed records without SQL, the next lesson’s std.db.kv supplies a smaller interface over this same engine. This lesson uses SQL to describe and query structured rows.

std.db.sqlite keeps data in a SQLite database: a single file, or memory. Values travel only through prepared statements, so a value is never mistaken for SQL.

Insert and query

execute runs fixed SQL such as a schema. prepare compiles one statement with ? parameters; bind each by number, from 1, and run it. A query is read a row at a time with step, and each column, numbered from 0, is read with the method for its type:

import std.db.sqlite

def main() -> Result[(), AllocError | IoError | std.db.sqlite.DbError]:
    mut db = std.db.sqlite.memory(65536)?
    db.execute("CREATE TABLE books(title TEXT NOT NULL, year INTEGER, rating REAL)")?
    mut insert = db.prepare("INSERT INTO books VALUES (?, ?, ?)")?
    insert.bind_text(1, "Dune")?
    insert.bind_integer(2, 1965)?
    insert.bind_real(3, 4.3)?
    insert.run()?
    insert.bind_text(1, "x'); DROP TABLE books; --")?
    insert.bind_null(2)?
    insert.bind_real(3, 1.0)?
    insert.run()?
    mut query = db.prepare("SELECT title, year FROM books WHERE rating > ? ORDER BY rating")?
    query.bind_real(1, 0.5)?
    while query.step()?:
        print(query.text(0)?, query.optional_integer(1)?)?
    Ok(())

x'); DROP TABLE books; -- Option[i64].Nothing
Dune Option[i64].Some(1965)

The second title looks like an attack but is stored as plain text. Reads copy each value out, so a str from text stays valid after the next step. memory(65536) sets the largest text, blob or row the connection will store or read; anything larger is TooLarge.

Types are checked

Each read requires the column’s stored type. A NULL needs optional_integer or another optional read, and a number stored as text is not an integer:

import std.db.sqlite

def main() -> Result[(), AllocError | IoError | std.db.sqlite.DbError]:
    mut db = std.db.sqlite.memory(65536)?
    mut query = db.prepare("SELECT '42', NULL")?
    query.step()?
    print(str.repr(query.integer(0))?)?
    print(str.repr(query.integer(1))?)?
    print(str.repr(query.kind(0)?)?)?
    Ok(())

Result[i64, std.db.sqlite.DbError].Err(std.db.sqlite.DbError.TypeMismatch(std.db.sqlite.ValueType.Text))
Result[i64, std.db.sqlite.DbError].Err(std.db.sqlite.DbError.TypeMismatch(std.db.sqlite.ValueType.Null))
std.db.sqlite.ValueType.Text

Transactions

begin returns a Transaction. commit keeps its changes; dropping it without commit, including by returning early with ?, rolls them back. SQLite failures carry SQLite’s own code and message:

import std.db.sqlite
from std.db.sqlite import Begin, Connection, DbError

def transfer(db: &mut Connection, amount: i64) -> Result[(), DbError | OverflowError[i64]]:
    mut tx = db.begin(Begin.Immediate)?
    mut change = db.prepare("UPDATE accounts SET balance = balance + ? WHERE name = ?")?
    change.bind_integer(1, 0 - amount)?
    change.bind_text(2, "alice")?
    change.run()?
    change.bind_integer(1, amount)?
    change.bind_text(2, "bob")?
    change.run()?
    tx.commit()

def main() -> Result[(), AllocError | IoError | DbError | OverflowError[i64]]:
    mut db = std.db.sqlite.memory(65536)?
    db.execute("CREATE TABLE accounts(name TEXT PRIMARY KEY, balance INTEGER CHECK (balance >= 0))")?
    db.execute("INSERT INTO accounts VALUES ('alice', 10), ('bob', 0)")?
    transfer(&mut db, 4)?
    match transfer(&mut db, 50):
        case Ok(_):
            print("moved")?
        case Err(DbError.Sqlite(error)):
            print(error.primary() == std.db.sqlite.constraint, error.message)?
        case Err(_):
            print("other")?
    mut query = db.prepare("SELECT name, balance FROM accounts ORDER BY name")?
    while query.step()?:
        print(query.text(0)?, query.integer(1)?)?
    Ok(())

True CHECK constraint failed: balance >= 0
alice 6
bob 4

The failed transfer left no trace: its transaction rolled back when transfer returned the error.

For a file, use std.db.sqlite.connect(path, Mode.Create, limit). Another connection holding a write lock makes a write fail at once with SQLite’s busy code; set_busy_timeout makes it wait instead. See the std.db.sqlite reference for every error, the busy policy, and how connections are shared between threads.

SQLite’s FTS5 full-text search is built in. Applications that need a native extension, such as vector search, can load a trusted shared library with Connection.load_extension(path, entrypoint=""). This runs native code in the application; SQL cannot enable extension loading. See native extensions and full-text search for the loading contract and connection lifetime.

Store byte-keyed records

Use std.db.kv when a program needs named maps of byte keys and values, and ordered scans, without writing SQL. Use std.db.sqlite when SQL queries, joins or your own database schema are part of the application.

Batch related writes in a transaction. A failed operation propagated by ? drops the unfinished transaction and rolls the batch back:

import std.db.kv as kv
import std.bytes as buffers
from std.bytes import BytesError

def main() -> Result[(), AllocError | kv.KvError | BytesError | IoError]:
    mut store = kv.memory()?
    key = buffers.from_text("user:42")?
    value = buffers.from_text("Ada")?
    mut transaction = store.begin()?
    store.put("names", &key, &value)?
    transaction.commit()?
    drop(transaction)

    match store.get("names", &key)?:
        case Some(name):
            print(name.to_text()?)?
        case Nothing:
            print("not found")?

    mut rows = store.scan_all("names", max_rows=20)?
    while True:
        match rows.next()?:
            case Some(entry):
                print(entry.key.to_text()?, entry.value.to_text()?)?
            case Nothing:
                break
    drop(rows)
    store.close()?
    Ok(())

Ada
user:42 Ada

This example uses a private in-memory store. For persistence, replace kv.memory() with kv.connect("records.db"); the default creates a new store or opens an existing KV file. It rejects a database belonging to another schema. Mode.ReadOnly opens an existing store without allowing writes.

Keys and values need not be text; the example converts them because names are UTF-8. Every returned value owns its buffers. Scans require an explicit row limit and copy one row at a time. Finish/drop a scan before modifying the same Store or ending its transaction. Use scan(table, start, stop, max_rows) for a byte range with inclusive start and exclusive stop.

The reference explains file compatibility, per-row size limits, lock conflicts and scan lifetimes. The engine comparison explains why this API uses SQLite rather than introducing a redb dependency.

Read and write HTTP messages

An HTTP/1.1 connection carries one message after another. Each message is a head, which ends at a blank line, and an optional body. A reader must find where each body ends, or it reads the next request as part of the last one. std.http does that work over any std.io stream, so you can test it with bytes in memory before any socket is involved.

import std.bytes
import std.http
import std.io

type MessageStreamError = std.http.HttpError | std.io.StreamError | std.bytes.BytesError

def main() -> Result[(), AllocError | IoError | MessageStreamError]:
    wire = "POST /notes HTTP/1.1\r\nHost: example.com\r\nContent-Length: 5\r\n\r\nhelloGET /notes HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n"
    limits = std.http.limits()
    mut conn = std.io.buffered_reader(std.io.cursor(std.bytes.from_text(wire)?), 1024)?
    while True:
        match std.http.read_request(&mut conn, &limits)?:
            case Nothing:
                break
            case Some(head):
                framing = std.http.request_framing(&head)?
                mut body = std.http.body_reader(conn, &framing, &limits)?
                mut data = std.bytes.empty()?
                std.http.read_to_end(&mut body, &mut data)?
                print(head.method, head.target, str.repr(&framing)?, str.repr(data.to_text()?)?, std.http.request_keeps_alive(&head))?
                conn = std.http.finish(&mut body)?
    Ok(())

POST /notes std.http.Framing.Length(5) "hello" True
GET /notes std.http.Framing.Empty "" False

read_request reads one head and returns Nothing when the input ends between messages. request_framing says how the body is delimited: here by Content-Length, then not at all. The body reader takes the connection, so nothing else can read from it until finish hands it back, positioned at the next request. finish fails if the body was not read to its end. Every read is bounded by limits(): line length, head size, header count, and body size.

Writing goes the other way. A chunked body is sent in pieces whose total size the writer need not know in advance:

import std.bytes
import std.http
import std.io
from std.http import Header

type MessageStreamError = std.io.StreamError | std.http.HttpError | std.bytes.BytesError

def main() -> Result[(), AllocError | IoError | MessageStreamError]:
    mut sink = std.io.cursor(std.bytes.empty()?)
    mut reply = std.http.response(200, "OK")?
    reply.add("Transfer-Encoding", "chunked")?
    std.http.write_response(&mut sink, &reply)?
    text = std.bytes.from_text("first second")?
    std.http.write_chunk(&mut sink, &text[:6])?
    std.http.write_chunk(&mut sink, &text[6:12])?
    std.http.write_last_chunk(&mut sink, &list[Header].new()?)?
    print(str.repr(sink.data.to_text()?)?)?
    mut forged = std.http.response(200, "OK")?
    forged.add("Location", "/a\r\nSet-Cookie: x=1")?
    print(str.repr(std.http.write_response(&mut sink, &forged))?)?
    smuggled = "POST / HTTP/1.1\r\nContent-Length: 4\r\nTransfer-Encoding: chunked\r\n\r\n"
    mut conn = std.io.buffered_reader(std.io.cursor(std.bytes.from_text(smuggled)?), 1024)?
    match std.http.read_request(&mut conn, &std.http.limits())?:
        case Some(head):
            print(str.repr(std.http.request_framing(&head))?)?
        case Nothing:
            print("connection ended before a request")?
    Ok(())

"HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\n\r\n6\r\nfirst \r\n6\r\nsecond\r\n0\r\n\r\n"
Result[(), std.http.HttpError].Err(std.http.HttpError.InvalidHeader)
Result[std.http.Framing, std.http.HttpError].Err(std.http.HttpError.ConflictingFraming)

The writer refuses a header value with a line break, which would let text from a request add headers of its own. The reader refuses a message with both Content-Length and Transfer-Encoding: two servers could disagree about where its body ends, which is how request smuggling works. Neither guesses.

The same functions work over a std.net stream wrapped in a BufReader. Deadlines stay with the socket calls. See the module reference for every error, response framing rules, and the body reader’s use as a std.io stream.

Formatting into a reusable writer

An f-string is the short way to build a str; it compiles to the calls below. Use std.fmt directly when output must go to a chosen byte writer, reuse storage, or stay within a byte budget. Numeric widths count bytes and include the sign. Every call is fallible, and the byte budget includes punctuation and padding.

import std.fmt

def main() -> Result[(), AllocError | IoError | std.fmt.FormatError]:
    mut out = std.fmt.string_formatter(80, 8)?
    out.text("count=")?
    out.integer(12, 4)?
    out.text(", label=")?
    out.debug_text("one\ntwo")?
    print(std.fmt.finish(&out)?)?
    Ok(())

count=  12, label="one\ntwo"

Your type chooses separate display and debug methods. Both can be generic over the output writer; callers need no trait object or format-string parser. print and f"{x}" call display; str.repr, f"{x!r}" and the elements of a printed list or other aggregate call debug. std.fmt.to_string and to_debug call the same methods within a byte budget and depth you choose.

import std.fmt
from std.fmt import Formatter

pub class Label:
    name: str

    pub def display[W](self, out: &mut Formatter[W]) -> Result[(), FormatError]:
        out.text(&self.name)

    pub def debug[W](self, out: &mut Formatter[W]) -> Result[(), FormatError]:
        out.text("Label(")?
        out.debug_text(&self.name)?
        out.text(")")

def main() -> Result[(), AllocError | IoError | FormatError]:
    label = Label("ready")
    print(label)?
    print(str.repr(label)?)?
    print([Label("a"), Label("b")]?)?
    print(std.fmt.to_debug(&label, 80, 8)?)?
    Ok(())

ready
Label("ready")
[Label("a"), Label("b")]
Label("ready")

Because these methods can fail, printing such a value returns Result[(), IoError | FormatError], and str.repr and an f-string with such a field add FormatError to AllocError. A type without display prints with its debug; one without either prints its fields.

Enums use the same methods. Match the shared receiver to format a payload without consuming it:

import std.fmt
from std.fmt import Formatter

pub enum ReadError:
    Missing
    Invalid(i64)

    pub def display[W](self, out: &mut Formatter[W]) -> Result[(), FormatError]:
        match self:
            case ReadError.Missing:
                out.text("no reading")
            case ReadError.Invalid(line):
                out.text("invalid reading on line ")?
                out.integer(*line, 0)

def main() -> Result[(), FormatError | IoError]:
    error = ReadError.Invalid(12)
    print(error)?
    print(std.fmt.to_string(&error, 80, 8)?)?
    Ok(())

invalid reading on line 12
invalid reading on line 12

Returning the enum from main does not call the method yet: the report still uses the structural entrypoint report.

Inside such a method, out.format(f"...") writes an f-string straight to the formatter, with no intermediate str. It returns Result[(), FormatError], and the formatter’s byte budget and depth limit apply:

import std.fmt
from std.fmt import Formatter

pub class Reading:
    line: i64
    value: f64

    pub def display[W](self, out: &mut Formatter[W]) -> Result[(), FormatError]:
        out.format(f"line {self.line}: {self.value:.1f}")

def main() -> Result[(), AllocError | IoError | FormatError]:
    reading = Reading(7, 21.25)
    print(f"[{reading}] [{reading:>14}]"?)?
    mut out = std.fmt.string_formatter(10, 8)?
    match out.format(f"{reading}"):
        case Err(FormatError.LimitExceeded):
            print("kept", std.fmt.finish(&out)?)?
        case _:
            print("fits")?
    Ok(())

[line 7: 21.2] [  line 7: 21.2]
kept line 7: 21

To stream, construct std.fmt.formatter(writer, scratch, max_bytes, max_depth) with a std.io writer and initialized Bytes scratch of at least 32 bytes. Provision scratch and sink capacity before entering an allocation-free section. Formatting itself then reuses that memory; user methods remain responsible for their own allocations. Flush the public out.writer explicitly when needed. On failure, out.completed() tells you how many bytes were accepted; do not blindly restart a partially written record.

The reference describes aggregate callbacks, errors, escaping, depth limits and exact costs.

Formatting a bounded report

Use std.report to give a value a human-readable spelling through a writer-generic formatter. The method borrows its receiver, so an error can be formatted again or examined afterward.

import std.fmt
import std.report
from std.fmt import Formatter, FormatError

pub enum ReadingError:
    Invalid(i64)

    pub def format[W](self, output: &mut Formatter[W]) -> Result[(), FormatError]:
        match self:
            case ReadingError.Invalid(line):
                output.text("invalid reading on line ")?
                output.integer(*line)

def main() -> Result[(), FormatError | IoError]:
    error = ReadingError.Invalid(12)
    print(std.report.to_string(&error, 80, 8)?)?
    print(std.report.to_string(&error, 80, 8)?)?
    Ok(())

invalid reading on line 12
invalid reading on line 12

The method’s [W] lets it write to a string, stderr, or another writer. The formatter supplies that type, so callers do not pass a type argument. The public enum and its public format method satisfy the structural std.fmt.Formattable protocol. A class uses the same visibility and method signature. std.report.render(&value, &mut output) counts a nesting level and restores it on success or error. Use it when a formatting method delegates to another value.

An anonymous sum supports the same reporting API when every member satisfies std.fmt.Formattable. You can keep distinct error types and let the compiler select the active member’s method:

import std.fmt
import std.report
from std.fmt import Formatter, FormatError

pub enum ReadingError:
    Invalid(i64)

    pub def format[W](self, output: &mut Formatter[W]) -> Result[(), FormatError]:
        match self:
            case ReadingError.Invalid(line):
                output.text("invalid reading on line ")?
                output.integer(*line)

pub enum ConnectionError:
    Closed

    pub def format[W](self, output: &mut Formatter[W]) -> Result[(), FormatError]:
        output.text("connection closed")

def show(error: &(ReadingError | ConnectionError)) -> Result[(), FormatError | IoError]:
    print(std.report.to_string(error, 80, 1)?)?
    Ok(())

def main() -> Result[(), FormatError | IoError]:
    reading: ReadingError | ConnectionError = ReadingError.Invalid(12)
    connection: ReadingError | ConnectionError = ConnectionError.Closed
    show(&reading)?
    show(&connection)?
    show(&reading)?
    Ok(())

invalid reading on line 12
connection closed
invalid reading on line 12

Dispatch borrows the payload without allocating; string collection still allocates. The original sum remains usable afterward. render counts one depth level for the sum, with no extra level for selecting its member. Calling error.format(&mut output) directly also dispatches, but does not count depth. All members must have the required public method, even if the value currently holds a different member. Other protocols are not automatically forwarded.

For stderr, construct std.fmt.stderr_formatter(max_bytes, max_depth) and call render explicitly. Construction and scalar writes allocate no heap memory, so simple report methods remain usable when allocation is unavailable. Add any desired "error: " prefix and final "\n" with output.text yourself; they count toward the byte limit. User methods can still allocate, so this guarantee depends on what those methods do.

The collector has the same formatting contract but allocates fallibly:

import std.fmt
import std.report
from std.fmt import FormatError

def main() -> Result[(), FormatError | IoError]:
    mut output = std.fmt.string_formatter(4, 0)?
    output.text("a")?
    match output.text("é🙂"):
        case Err(_):
            print("too long", output.completed())?
        case Ok(_):
            pass
    output.text("é")?
    print(std.fmt.finish(&output)?)?
    Ok(())

too long 1
aé

Text checks its whole UTF-8 byte length before writing. Numeric output streams digits, so a limit can leave part of a number. On stderr failure, inspect completed() and has_failed(); subsequent writes return OutputClosed without writing again. A limit error is recoverable, as the example shows.

When main returns Err, its concrete error type selects the reporting path. A type with this public format method produces a human-readable report with the prefix error: main returned and a final newline. A sum selects this path only when all its members support it; other types retain structural reporting. The automatic reporter allows 16,384 bytes and 64 nesting levels. If formatting fails after writing part of the message, it appends [report unavailable] and a newline without trying the method again. Stderr failures stop output.

Use std.fmt for floats, widths, debug escaping or an arbitrary byte writer. The reference lists the complete reporting API.

Generic code and protocols

Use type parameters when several types need the same algorithm or data shape. These lessons build on core functions, borrowing, classes, and enums. Recursive data is an optional extension at the end.

• Replace duplicated functions with a type parameter
• Infer or choose a specialization
• Requiring methods with a protocol
• Parameterize a class
• Parameterize an enum
• Parameterize a protocol
• Store different implementations of a protocol
• Give a method its own type parameters
• Keep a numeric bound in the type
• Calculate with quantities
• Build recursive data
• Use values through a box
• Store recursive children in a list
• Remove a child and clean up a recursive structure
• Traverse recursive data through a borrow
• Reborrow while following a recursive structure
• Preserve a chain when insertion fails
• Represent parent links with node IDs

Replace duplicated functions with a type parameter

Suppose the same operation is needed for two integer widths. Separate functions work, but repeat both the implementation and its interface:

def keep_small(value: u8) -> u8:
    value

def keep_large(value: i64) -> i64:
    value

def main() -> Result[(), IoError]:
    print(keep_small(7u8))?
    print(keep_large(9))?
    Ok(())

7
9

A type parameter lets one declaration accept either width while keeping the argument and result types the same.

def identity[T](value: T) -> T:
    value

def sum_to[T: IntType](stop: T) -> Result[T, OverflowError[T]]:
    mut total: T = 0
    for n in range[T](stop):
        total = total + n
    Ok(total)

def first[T](values: &list[T]) -> &T:
    &values[0]

def main() -> Result[(), AllocError | IoError | OverflowError[u16]]:
    print(sum_to(5u16)?)?
    values = identity([3, 4]?)
    print(first(&values))?
    print(values)?
    Ok(())

10
3
[3, 4]

Declare type parameters after the function name. Calls infer them from the argument types, or you can supply them explicitly before the call. Ownership still follows the concrete type: identity(values) transfers the list, while a function taking &T borrows its argument.

IntType restricts a parameter to integer types, and FloatType to f32 and f64. CopyType accepts any type whose values copy, such as numbers, str, and tuples of them, and rejects lists and other values that move; see CopyType. Unconstrained T is useful when the body only moves, borrows, or uses operations supported by the chosen concrete type. Each specialization is checked against those operations.

A type parameter can also stand for unit () inside a Result or Option. This lets one helper handle both operations that return a value and operations that only succeed or fail:

def keep_result[T, E](result: Result[T, E]) -> Result[T, E]:
    result

def main() -> Result[(), AllocError | IoError]:
    written = print("saved")
    keep_result(written)?
    Ok(())

saved

Here T is inferred as (). You can also write an explicit unit type argument, such as keep_result[(), IoError](written). Unit still cannot be a direct function parameter, so identity[()](()) is rejected.

Require collection keys

Use K: KeyType when a generic algorithm needs dictionary keys or set members. It accepts integers, booleans, strings, bytes, and supported tuples, classes, enums and anonymous sums, including custom cleanup. The compiler checks all enum payloads; no hashing method is required.

enum Label:
    Id(i64)
    Name(str)

def frequencies[K: KeyType](values: list[K]) -> Result[dict[K, i64], AllocError | OverflowError[i64]]:
    mut counts: dict[K, i64] = {}?
    for value in values:
        *counts.get_or_insert(value, 0)? += 1
    Ok(counts)

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    values = [Label.Id(7), Label.Name("7"), Label.Id(7)]?
    counts = frequencies(values)?
    print(counts[Label.Id(7)], counts[Label.Name("7")])?
    Ok(())

2 1

The loop consumes the list and moves each key into get_or_insert, which drops it when the key is already present. This also works for keys with custom cleanup, which cannot be copied. Dictionary insertion and the count’s addition remain fallible. Floats do not satisfy KeyType; see the constraint reference.

Infer or choose a specialization

Inference matches the signature against the argument types. In first(&values), the parameter is &list[T] and the argument is &list[i64], so T is i64. When multiple arguments determine the same parameter, their types must agree. Unsuffixed literals in generic positions use their normal defaults (i64 or f64); another argument does not change them. Keep explicit type arguments when you want them to guide literals: sum_to[u16](5) is equivalent to sum_to(5u16).

Types must be determined from arguments, not the expected return type. For example, this function needs empty[u8]() because it has no input mentioning T:

def empty[T]() -> Result[list[T], AllocError]:
    []

def main() -> Result[(), AllocError | IoError]:
    values = empty[u8]()?
    print(values)?
    Ok(())

[]

An annotation on the receiving binding does not change that rule:

def empty[T]() -> Result[list[T], AllocError]:
    []

def main() -> Result[(), AllocError | IoError]:
    values: list[u8] = empty()?
    Ok(())

cannot infer type parameter `T` for `empty` from its arguments

Calls with the same concrete types share one compiled specialization, including recursive calls. Independent uses can specialize many different helpers, or the same helper for many types. The compiler separately limits how deeply one new specialization requires another, how many one generic function has, and how many are created in total. These are compile-time resource limits; generic calls add no runtime allocation. See specialization limits for the current bounds.

Requiring methods with a protocol

A protocol names the methods a generic algorithm needs. A class or enum satisfies it by having matching methods; no inheritance or registration is required. Importing a protocol does not add methods to a type.

protocol Readable:
    def read(self) -> str:
        pass

class Message:
    text: str
    def read(self) -> str:
        self.text

def read_message[T: Readable](source: &T) -> str:
    source.read()

def main() -> Result[(), IoError]:
    message = Message("hello")
    print(read_message(&message))?
    Ok(())

hello

Here &message determines T = Message; the compiler then checks the Readable requirements. Writing read_message[Message](&message) explicitly also works.

self means a shared receiver. Write self: &mut ProtocolName when a required method mutates the receiver. Method parameters, return types, and receiver borrowing must match exactly. All required methods are checked at specialization, including methods the generic function does not happen to use. Across modules, the class methods must be visible to the generic function’s defining module. That means both pub class Message and pub def read, even when the caller is in Message’s own module. The caller does not lend private access to the helper. If only the class is private, the call diagnostic asks you to declare it pub class; private methods still need their own pub def.

For example, save this helper as reader.plenty:

pub protocol Readable:
    def read(self) -> str:
        pass

pub def read_message[T: Readable](source: &T) -> str:
    source.read()

This application needs pub class Message, as well as its public method:

import reader

class Message:
    pub def read(self) -> str:
        "hello"

def main() -> ():
    message = Message()
    drop(reader.read_message(&message))

class `Message` is private to its defining module; declare it `pub class`

Protocols constrain class and enum type arguments; they cannot be stored as values. Use source: &T with T: Readable, not source: Readable.

Parameterize a class

A generic class shares one declaration across concrete field types. Its methods can use the class’s type parameters.

class Cell[T]:
    value: T

    def get(self) -> T:
        self.value

    def replace(self: &mut Cell[T], value: T) -> ():
        self.value = value

def read[T](cell: &Cell[T]) -> T:
    cell.get()

def main() -> Result[(), IoError]:
    mut count = Cell(7u8)
    count.replace(9)
    print(read(&count))?
    text = Cell("hello")
    print(text.get())?
    Ok(())

9
hello

Constructors infer their parameters: Cell(7u8) and Cell[u8](7) have the same type. With Cell(7), the unsuffixed integer defaults to i64.

This get method works for integers and immutable strings, which can be read from a shared field. An owned list needs an explicit copy or a reference: returning it would move it out of a borrowed field. A Cell can hold a list, but its get cannot be called:

class Cell[T]:
    value: T

    def get(self) -> T:
        self.value

def main() -> Result[(), AllocError | IoError]:
    numbers = Cell([1, 2]?)
    first = numbers.get()
    Ok(())

lesson.plenty:9:13: `Cell[list[i64]].get` copies `T`, but `list[i64]` cannot be copied
lesson.plenty:5:9: note: in instantiation `Cell[list[i64]].get`: cannot move out of a field

A generic method is checked once for each set of type arguments it is used with, not where it is written. Without the get call, the program is accepted. The error is reported at the line of your code that first required Cell[list[i64]].get, here the method call, and names the type argument that the method cannot accept. The note below it gives the line in the definition and the reason.

That wording follows the value: here self.value is declared as T. An unrelated list created inside the method does not become a T value just because the caller also chooses a list for T. For failures without a clear parameter origin, the compiler instead reports that the instance’s definition is rejected, followed by the operation’s error. See instance diagnostics for the attribution rules.

When you write a generic class for others to use, plenty --check --check-all-methods FILE also checks the methods your program never calls, for every instance it creates of a generic type it declares. The generics reference describes the check.

Parameterize an enum

Use a type parameter when the same alternatives should carry different kinds of values. Choose the concrete payload type in brackets. Here, T: IntType accepts any supported sized integer. Omit the constraint to allow other stored types.

enum Choice[T: IntType]:
    Empty
    Value(T)

def main() -> Result[(), IoError]:
    selected = Choice[u8].Value(7)
    match selected:
        case Choice.Empty:
            print("empty")?
        case Choice.Value(value):
            print(value)?
    Ok(())

7

A constructor names the instance, as in Choice[u8].Value(7). A pattern names only the enum, as in case Choice.Value(value): the matched value already fixes T, so a pattern takes no type arguments.

Parameterize a protocol

A protocol can describe the same operation for several result types. Classes satisfy it by providing matching methods.

protocol Readable[T]:
    def read(self) -> T:
        pass

class Cell[T]:
    value: T
    def read(self) -> T:
        self.value

def read[T, R: Readable[T]](source: &R) -> T:
    source.read()

def main() -> Result[(), IoError]:
    cell = Cell(7u8)
    print(read(&cell))?
    Ok(())

7

The argument determines R = Cell[u8]; that class’s read signature determines T = u8. Its return type and receiver borrowing must match the protocol. Explicit read[u8, Cell[u8]](&cell) also works. Conflicting type evidence is an error, rather than a reason to widen integers.

Store different implementations of a protocol

An enum wrapper works well when your program knows all the alternatives. A protocol box lets implementations be added independently: the collection only names the operations it needs.

protocol Counter:
    def current(self) -> i64:
        pass

    def increment(self: &mut Counter) -> Result[(), OverflowError[i64]]:
        pass

class Count:
    value: i64

    def current(self) -> i64:
        self.value

    def increment(self: &mut Count) -> Result[(), OverflowError[i64]]:
        self.value += 1
        Ok(())

enum Flag:
    Off
    On

    def current(self) -> i64:
        match self:
            case Flag.Off:
                0
            case Flag.On:
                1

    def increment(self: &mut Flag) -> Result[(), OverflowError[i64]]:
        *self = Flag.On
        Ok(())

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut items: list[Box[Counter]] = []?
    items.append(Box[Counter](Count(10))?)?
    items.append(Box[Counter](Flag.Off)?)?
    for item in &mut items:
        item.increment()?
        print(item.current())?
    Ok(())

11
1

Each Box[Counter](value)? moves its input into one heap allocation. The list stores owners with a common interface. Its mutable loop borrows each owner, so increment and current operate on the same instance. No match or cast is needed. Use &items for a loop that only calls shared methods.

The protocol fixes each method’s contract. Count.increment can overflow, so increment returns Result[(), OverflowError[i64]], and Flag declares the same result even though it never fails.

The Box boundary is explicit: list[Counter] is not a stored value type, and Box(Count(10))? preserves the concrete Count type. Allocation failure drops the consumed input. Appending can also fail and consumes its new box under the ordinary list contract.

Dictionary values and generic readers

The same owner type works as a dictionary value and through a protocol bound:

protocol Label:
    def label(self) -> str:
        pass

class Message:
    text: str

    def label(self) -> str:
        self.text

enum Status:
    Ready

    def label(self) -> str:
        return "ready"

def read[T: Label](value: &T) -> str:
    value.label()

def main() -> Result[(), AllocError | IoError]:
    items: dict[str, Box[Label]] = {
        "message": Box[Label](Message("hello"))?,
        "status": Box[Label](Status.Ready)?,
    }?
    for name, item in items.items():
        print(name, read(item))?
    Ok(())

message hello
status ready

Borrowing avoids copying the boxes. Their concrete payloads are destroyed when their owners leave scope, including any custom cleanup.

A box exposes only its protocol’s methods. This initial interface supports shared and mutable receivers, fixed protocol arguments, ordinary parameters, and owned results. Methods with their own type parameters, consuming receivers, or returned borrows cannot be boxed. Protocol boxes cannot be copied, used as set elements or dictionary keys, or transferred to worker threads. Payloads containing channel senders or receivers also need concrete owners: erasing them would hide endpoints from the compiler’s checks for waits that could deadlock. See the reference for the complete limits.

Give a method its own type parameters

A method may declare type parameters of its own, in addition to those on its class. Arguments determine them just as they do for generic functions. A parameter that appears only in the result must be chosen explicitly:

class Number:
    value: i64

    def convert[T: IntType](self) -> T:
        T(self.value)

def main() -> Result[(), IoError]:
    number = Number(7)
    small: u8 = number.convert[u8]()
    print(small)?
    Ok(())

7

Method parameters cannot shadow class parameters. Constructors and destructors use only the class parameters. See the functions-as-values path for a generic method that accepts a callback.

Keep a numeric bound in the type

A configuration value often needs a fixed interval. Name that interval with Bounded, then validate computed input once before passing it around:

type RetryCount = Bounded[i64, 0, 8]

def describe(retries: RetryCount) -> Result[(), IoError]:
    print("Retries:", retries.get())

def main() -> Result[(), RangeError | IoError]:
    describe(3)?
    configured = 5
    retries = RetryCount.try_from(configured)?
    describe(retries)?
    print(RetryCount.try_from(9).is_err())?
    Ok(())

Retries: 3
Retries: 5
True

Both ends are included. The literal 3 is checked at compile time because the parameter expects RetryCount. A computed integer goes through try_from, which returns RangeError.OutOfRange when it does not fit. .get() extracts the integer for calculations. A literal 9 passed directly to describe would be a compile error.

Abstract over the bounds

The arguments 0 and 8 are compile-time values, not types. A generic function can keep them as const parameters:

def interval[T: IntType, const lo: T, const hi: T](value: &Bounded[T, lo, hi]) -> (T, T):
    (lo, hi)

def main() -> Result[(), IoError]:
    retries: Bounded[i64, 0, 8] = 3
    percentage: Bounded[u8, 0, 100] = 75
    print(interval(&retries), interval(&percentage))?
    Ok(())

(0, 8) (0, 100)

The argument’s type supplies T, lo and hi; no runtime integer becomes a specialization argument. const lo: T uses the earlier T: IntType, so a u8 interval has u8 bounds. The values are available inside the body without storing them alongside each integer.

User classes, enums and methods can also declare const parameters. Use them when the value belongs in type identity. A setting read from a file normally stays a runtime value: it cannot select a new type at runtime. The value-parameter reference gives argument restrictions, and bounded integers describes conversion and value behavior.

Calculate with quantities

Use Quantity[T, D] for a physical value whose dimension should be checked in arithmetic. T is its numeric storage type and D is a compile-time dimension. The std.units module provides the SI dimensions, units and constants:

import std.units as u
from std.units import Velocity, m, km, s, minute

def double[D: Dimension](value: Quantity[f64, D]) -> Quantity[f64, D]:
    value + value

def main() -> Result[(), IoError]:
    distance = 1500.0 * m
    elapsed = 2.0 * minute
    speed: Quantity[f64, Velocity] = distance / elapsed
    print(double(distance).to(km), "km")?
    print(speed, speed.to(km / u.hour), "km/h")?
    Ok(())

3.0 km
12.5 m/s 45.0 km/h

u.Length and u.Time are distinct base dimensions. Velocity is an alias for Length / Time. Dividing the distance by the elapsed time computes this dimension, so the speed annotation checks successfully. Adding a time to a length would be a compile error. When a dimension error involves Velocity, the diagnostic includes a note naming Velocity and its normal form, std.units.Length * Pow[std.units.Time, -1]. This connects the normalized dimension to the name used in your program.

Units are constants. km is a length whose stored value is 1000.0, and 2.0 * minute stores 120.0 seconds. Multiplying a number by a unit constructs a quantity, and dividing one unit by another, as in km / u.hour, gives another unit.

double infers its dimension parameter from its argument. The same function works for a length, a time or a velocity. Dimension arguments add no runtime fields: a quantity uses its numeric storage type’s native representation. Construction and get add no numeric conversion, and float to performs the same division as plain numbers. A dimension itself has no values: length: u.Length is invalid.

.to(km) divides by the unit’s stored value and returns a plain f64. .get() reads the coherent value directly. Both methods remove the dimension from the result, so keep quantities until the boundary where you need a number. Printing a quantity includes its coherent-unit symbol. The explicit "km" label accompanies the plain number returned by .to(km); printing double(distance) directly would show 3000.0 m.

Use an f-string to choose numeric precision: f"{speed:.2f}"? produces "12.50 m/s". As with other f-strings, include AllocError in the function’s error type when propagating its allocation failure.

Scalars only scale quantities. Write 0.0 * m for a zero length; `distance

• 0.0anddistance > 0.0are errors. Dividing a length by a length producesQuantity[f64, One]; use .get()` to obtain its dimensionless number.

std.units also has dimension-aware functions. u.sqrt of an area returns a length, u.sum adds a list of quantities, and u.sin takes an angle such as 30.0 * u.degree. Temperatures in Celsius or Fahrenheit convert at the boundary with u.from_celsius and u.to_celsius, because their zero is offset.

Declare your own dimensions

Declare a base dimension for a quantity outside SI, or to keep two kinds of value apart that SI would give the same dimension. Give each base its coherent-unit symbol:

dimension Pixel("px")
dimension Point("pt")
dimension PixelDensity = Pixel / Point

const px: Quantity[f64, Pixel] = Quantity[f64, Pixel](1.0)
const pt: Quantity[f64, Point] = Quantity[f64, Point](1.0)
const retina: Quantity[f64, PixelDensity] = 2.0 * px / pt

def main() -> Result[(), IoError]:
    width = 320.0 * pt
    print(width * retina)?
    Ok(())

640.0 px

Unit constants can be shared across functions or exported from a module with pub const, as std.units does. Their initializers are evaluated at compile time, including unit scaling and arithmetic between constants. The constructor takes the value in the coherent unit.

Dimension expressions also support products, integer powers and exact roots. Root[Pow[Length, 2], 2] is Length; fractional dimensions are rejected. In a generic function’s parameter types, use concrete dimensions or bare parameters. Expressions using parameters belong in return types or bodies.

See std.units for its units, constants and functions, dimensions for algebra and visibility, and quantities for integer/domain storage, conversions, checked arithmetic and current limits.

Build recursive data

Chains and trees contain values of their own type. A directly embedded value would have no finite size, so put the recursive field in a Box or collection. A box owns one value on the heap.

This chain ends with Empty. Each Link owns a value and a box holding the rest of the chain:

enum Chain[T]:
    Empty
    Link(T, Box[Chain[T]])

def total(chain: Chain[i64]) -> Result[i64, OverflowError[i64]]:
    mut remaining = chain
    mut answer = 0
    while True:
        match remaining:
            case Chain.Empty:
                break
            case Chain.Link(value, rest):
                answer = answer + value
                remaining = rest
    Ok(answer)

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut chain = Chain[i64].Empty
    for value in range(1, 4):
        chain = Chain[i64].Link(value, Box(chain)?)
    print(total(chain)?)?
    Ok(())

6

Box(value) moves the value onto the heap and returns an allocation result. Constructing the Link itself allocates nothing.

When a value of type T is required, a Box[T] moves its content out and frees the box, without allocating. Here, remaining = rest expects Chain[i64], so it unboxes rest. The conversion also works for arguments, returns, annotated bindings, constructor fields, and collection elements. total consumes its chain; the caller cannot use it afterward.

A boxed class’s fields and methods are reached as b.field and b.method(), and where a function expects &T, you can pass a &Box[T]. Where no type is required, a box stays a box: other = b moves the box itself. Operators and conditions do not convert either. Write *b there to move the content out, or &*b and &mut *b to borrow it.

Without the box, the compiler rejects the declaration:

enum Chain:
    Empty
    Link(i64, Chain)

def main() -> ():
    pass

`Chain` contains itself and would have infinite size; store the recursive field in a `Box`, list, set, or dict

Use values through a box

Call collection and string methods through a box, including nested boxes. Methods borrow its content; mutation requires a mut binding or an exclusive reference:

def main() -> Result[(), AllocError | IoError]:
    mut items = Box(Box([1, 2]?)?)?
    items.append(3)?
    match items.get(2):
        case Some(value):
            print(value)?
        case Nothing:
            print("missing item")?
    text = Box("  hello  ")?
    print(text.strip()?)?
    print(text.startswith("  "))?
    Ok(())

3
hello
True

Read-only methods also work on temporary boxes. Bind a box with mut before calling a mutating method.

The recursive-data lesson explains when a box transfers its contents and when it keeps ownership of them.

Store recursive children in a list

A list of children provides the indirection a recursive class needs; each child needs no additional box. Save this module as forest.plenty:

pub class Node[T]:
    pub value: T
    pub children: list[Node[T]]

import forest

def main() -> Result[(), AllocError | IoError]:
    mut root = forest.Node[i64](1, [forest.Node[i64](2, []?)]?)
    root.children[0].value = 9
    print(root.value)?
    print(root.children[0].value)?
    Ok(())

1
9

An empty children list terminates the tree. For a single optional child, use a field such as next: Option[Box[Node]] and terminate it with Nothing.

Remove a child and clean up a recursive structure

To take an owned child out of a mutable class, leave a replacement behind. replace(node.next, Nothing) returns the old tail without cloning or allocating:

class Link:
    value: i64
    next: Option[Box[Link]]

def main() -> Result[(), AllocError | IoError]:
    mut chain = Some(Box(Link(1, Some(Box(Link(2, Nothing))?)))?)
    while True:
        match chain:
            case Some(link):
                mut node = link
                print(node.value)?
                chain = replace(node.next, Nothing)
            case Nothing:
                break
    Ok(())

1
2

Replacing node.next with Nothing leaves that field empty when node drops. Use another tail as the replacement to relink nodes. replace requires a mutable field and evaluates the replacement before any destination indices.

Automatic cleanup can drop a deep boxed chain without growing the native stack. A recursive traversal you write can still overflow it; use a loop for unbounded depth.

To inspect a structure while keeping it, traverse it through a borrow. Moving individual owned fields out without replacing them remains unsupported. Automatic copy, equality, print, and str.repr also reject recursive data, including containers holding it. Print selected scalar fields as above, or write an explicit traversal.

Optional: traverse recursive data

Traverse a chain without consuming it by matching a borrow. Some(next) below binds next as &Box[links.Node[i64]], which can be passed where a reference to the node is expected.

pub class Node[T]:
    pub value: T
    pub next: Option[Box[Node[T]]]

import links

def total(node: &links.Node[i64]) -> Result[i64, OverflowError[i64]]:
    match &node.next:
        case Some(next):
            Ok(node.value + total(next)?)
        case Nothing:
            Ok(node.value)

def increment(node: &mut links.Node[i64]) -> Result[(), OverflowError[i64]]:
    node.value = node.value + 1
    match &mut node.next:
        case Some(next):
            return increment(next)
        case Nothing:
            pass
    Ok(())

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut chain = links.Node[i64](3, Some(Box(links.Node[i64](6, Nothing))?))
    print(total(&chain)?)?
    increment(&mut chain)?
    print(total(&chain)?)?
    print(chain.value)?
    Ok(())

9
11
4

match &mut value binds mutable payload references, allowing increment to update each node while its caller keeps the chain.

increment ends with a tail call through a reference borrowed from its parameter, so its stack does not grow. total adds after its recursive call returns, so it uses native stack space for every node.

A loop avoids that. Declare a reference binding with mut and assign it the next node. Such a binding may only be assigned a reference borrowed from itself, which next is: it comes from match &node.next.

class Node:
    value: i64
    next: Option[Box[Node]]

def total(head: &Node) -> Result[i64, OverflowError[i64]]:
    mut sum = 0
    mut node = head
    while True:
        sum = sum + node.value
        match &node.next:
            case Some(next):
                node = next
            case Nothing:
                break
    Ok(sum)

def increment(head: &mut Node) -> Result[(), OverflowError[i64]]:
    mut node = head
    while True:
        node.value = node.value + 1
        match &mut node.next:
            case Some(next):
                node = next
            case Nothing:
                break
    Ok(())

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut chain = Node(3, Some(Box(Node(6, Nothing))?))
    increment(&mut chain)?
    print(total(&chain)?)?
    Ok(())

11

The chain stays borrowed while node is used. The loop’s stack usage is independent of chain length.

Walk recursive data with a reference

A reference binding declared with mut can advance through a recursive structure by borrowing each next step from itself:

class Folder:
    name: str
    inside: list[Folder]

def innermost(top: &Folder) -> str:
    mut folder = top
    while len(folder.inside) > 0:
        folder = &folder.inside[0]
    folder.name

def main() -> Result[(), AllocError | IoError]:
    notes = Folder("notes", []?)
    work = Folder("work", [notes]?)
    home = Folder("home", [work]?)
    print(innermost(&home))?
    Ok(())

notes

folder starts at top. Each &folder.inside[0] is borrowed from folder, so the assignment is allowed. home stays borrowed until folder’s last use.

The binding can also be pointed at another place within the value it first borrowed, without going through itself. This retargets it: the old loan ends at the assignment. A search can remember its best element this way, without keeping an index:

def longest(words: &list[str]) -> &str:
    mut best = &words[0]
    for i in range(1, len(words)):
        if words[i].byte_len() > best.byte_len():
            best = &words[i]
    best

def main() -> Result[(), AllocError | IoError]:
    words = ["fig", "banana", "kiwi"]?
    print(longest(&words))?
    Ok(())

banana

best first borrows from words, so &words[i] is a valid new target. See reference binding reassignment for the full rule. Pointing it at a different value is rejected, even one of the same type:

def main() -> Result[(), AllocError | IoError]:
    first = [1, 2]?
    second = [3]?
    mut view = &first
    view = &second
    print(view)?
    Ok(())

reference binding `view` can be reassigned only to a reference into the owner it first borrowed

Matching borrowed values also leaves the owner in place while inspecting its contents.

The same descendant-cursor pattern can lend exclusive access while updating each node. See the complete mutable chain walk. For branching traversal, a stack of references is currently unsupported; an arena with a worklist of IDs is an alternative.

Preserve a chain when insertion fails

A borrowed collection should usually keep its existing contents when insertion fails. Allocate the new node before detaching the old head:

class Node:
    value: i64
    next: Option[Box[Node]]

class Chain:
    head: Option[Box[Node]]

def push(chain: &mut Chain, value: i64) -> Result[(), AllocError]:
    mut node = Box(Node(value, Nothing))?
    node.next = replace(chain.head, Nothing)
    chain.head = Some(node)
    Ok(())

def main() -> Result[(), AllocError | IoError]:
    mut chain = Chain(Nothing)
    push(&mut chain, 10)?
    push(&mut chain, 20)?
    match &chain.head:
        case Some(head):
            print(head.value)?
        case Nothing:
            print("empty")?
    Ok(())

20

The only allocation is Box(...). After it succeeds, replace transfers the old head and leaves Nothing behind; linking the nodes cannot fail or allocate. If allocation fails, the existing chain has not changed.

Putting replace(chain.head, Nothing) inside the Box argument would detach the chain first. Failed box allocation destroys its input, including that old chain. Memory safety does not imply that a failed operation preserves data. For a generic payload, also decide whether failure should destroy the incoming value or return it to the caller.

The earlier consuming construction example abandons the whole local computation on failure. This example has a stronger contract because the caller retains the collection. See the complete linked-stack operations.

Represent parent links with node IDs

When children need to identify their parent, one list can own all the nodes. Links then contain indices, not references or owning boxes. This representation is often called an arena. Moving the list’s storage during growth does not change an index.

This append-only example stores children as IDs too:

class Node:
    name: str
    parent: Option[i64]
    children: list[i64]

def main() -> Result[(), AllocError | IoError]:
    mut nodes: list[Node] = []?
    nodes.append(Node("root", Nothing, []?))?
    nodes.append(Node("leaf", Some(0), []?))?
    nodes[0].children.append(1)?

    child = nodes[0].children[0]
    match nodes[child].parent:
        case Some(parent):
            print(nodes[parent].name)?
        case Nothing:
            print("no parent")?

    mut pending = [0]?
    while True:
        match pending.pop():
            case Some(id):
                print(nodes[id].name)?
                for child_id in &nodes[id].children:
                    pending.append(*child_id)?
            case Nothing:
                break
    Ok(())

root
root
leaf

The explicit worklist avoids recursive function calls. It owns integers, so it does not need to store references, which Plenty currently rejects. Its growth is fallible and its memory use depends on the tree’s shape. A graph with cycles needs visited-node tracking as well.

Keep this list append-only while IDs are live. Removing an element from the middle, sorting, or swapping elements changes which node an index denotes. Removing a graph edge does not destroy its target: the arena owns that node until explicitly removed or the whole arena is dropped. If IDs come from outside this controlled example, check their range before indexing.

For reusable slots, tombstones preserve indices and generation checks can reject stale IDs after reuse. Those invariants belong in a reusable abstraction; raw integers do not enforce them. The arena proposal contains a tested prototype, not an available std.arena module.

This example exits and drops the arena if construction fails. An API that mutates a caller’s existing graph must reserve needed storage before changing parent/child links, or explicitly roll back partial changes. See failure-preserving insertion.

Functions as values

Pass a function when its caller should choose an operation, or store one for later. The first lessons need only the core path; generic signatures and records also use type parameters and constraints.

• Pass functions as values
• Anonymous functions
• Capture data and private state
• Accept functions and closures through one API
• Borrow in a closure
• Return a closure
• Generic function values
• Transform a cell with a generic method
• Store stateful callbacks
• Store owned closures
• Reduce a borrowed collection with a pipeline
• Transform a stream of values
• Keep callbacks in tuples and lists
• Name stored callbacks
• Store different captured callbacks
• Put a callback in an enum
• Consume a capture
• Consume a callback
• Consume owned data while borrowing local state
• Store consuming jobs

Pass functions as values

Use a function’s name without parentheses to pass it as a value. A Callable annotation specifies its parameter types and return type. The value stores only a code address. To accept a callback with captured state too, use a generic callback parameter.

def double(value: i64) -> Result[i64, OverflowError[i64]]:
    Ok(value * 2)

def apply(operation: Callable[[i64], Result[i64, OverflowError[i64]]], value: i64) -> Result[i64, OverflowError[i64]]:
    operation(value)

def main() -> Result[(), IoError | OverflowError[i64]]:
    operation = double
    print(operation(6)?)?
    print(apply(double, 9)?)?
    Ok(())

12
18

The callback’s own return type includes OverflowError[i64]; apply forwards that public Result and main propagates it with ?. A caller does not change a callback’s arithmetic contract. See checked arithmetic.

Function values can also be returned and reassigned through mut bindings. Copying a function value copies its code address; no allocation is needed.

You can call a value selected from a collection directly:

def increment(value: i64) -> Result[i64, OverflowError[i64]]:
    Ok(value + 1)

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    handlers = [increment]?
    index = 0
    print(handlers[index](41)?)?
    Ok(())

42

A callable can also borrow an argument and return a fallible unit result:

def increment(value: &mut i64) -> Result[(), OverflowError[i64]]:
    *value = *value + 1
    Ok(())

def main() -> Result[(), IoError | OverflowError[i64]]:
    update: Callable[[&mut i64], Result[(), OverflowError[i64]]] = increment
    mut value = 41
    update(&mut value)?
    print(value)?
    Ok(())

42

Class constructors and payload-bearing enum variants can be passed the same way. Use the constructor directly when a callback only wraps a value:

class Reading:
    value: i64

def main() -> Result[(), AllocError | IoError]:
    readings: list[Reading] = iter(range(3)).map(Reading).collect()?
    wrap: Callable[[i64], Option[i64]] = Some
    print(readings, wrap(7))?
    Ok(())

[Reading(value=0), Reading(value=1), Reading(value=2)] Option[i64].Some(7)

For a generic constructor, an annotation supplies the instance, as for wrap above. Without that context, name it explicitly: Option[i64].Some. Constructor values take every positional argument and retain any initializer failure in their result. See constructor rules.

Anonymous functions

Use def without a name to create a function value. Parameters and the return value need explicit types. Inside brackets, such as a call’s arguments, the body is one expression and its value is returned:

def apply(f: Callable[[i64], Result[i64, OverflowError[i64]]], value: i64) -> Result[i64, OverflowError[i64]]:
    f(value)

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    print(apply(def(x: i64) -> Result[i64, OverflowError[i64]]: Ok(x * 2), 4)?)?
    print(apply(
        def(x: i64) -> Result[i64, OverflowError[i64]]: Ok(x + 1 if x > 0 else 0),
        4,
    )?)?
    Ok(())

8
5

The body ends at the comma or closing bracket that ends the argument. Each function has type Callable[[i64], Result[i64, OverflowError[i64]]] and can be stored, returned, or passed to a callback parameter.

Outside brackets, the body is an indented block with the same rules as a named function:

def main() -> Result[(), IoError | OverflowError[i64]]:
    transform = def(value: i64) -> Result[i64, OverflowError[i64]]:
        adjusted = value * 2
        if adjusted > 10:
            return Ok(10)
        Ok(adjusted + 1)
    print(transform(3)?)?
    print(transform(8)?)?
    Ok(())

7
10

The position decides the form. A function with statements cannot be written inside brackets; give it an indented body and a name first, as transform has:

def apply(f: Callable[[i64], Result[i64, OverflowError[i64]]], value: i64) -> Result[i64, OverflowError[i64]]:
    f(value)
def main() -> ():
    apply(def(x: i64) -> Result[i64, OverflowError[i64]]: return Ok(x * 2), 4)

inside brackets an anonymous function body is one expression, and its value is returned; remove `return`

Parentheses are brackets, so a one-expression function can still be bound: double = (def(x: i64) -> Result[i64, OverflowError[i64]]: Ok(x * 2)). Python’s lambda is not available; the compiler names the def spelling instead.

Capture data and private state

When an operation needs more than its call arguments, let its function value own that extra data. Use an explicit list to capture surrounding bindings:

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    offset = 4
    values = [10, 20]?
    adjust = def [offset, values](index: i64) -> Result[i64, OverflowError[i64]]:
        Ok(values[index] + offset)
    print(adjust(0)?)?
    print(adjust(1)?)?
    Ok(())

14
24

values moves into the closure; the scalar offset copies. Each call borrows the captures, so the list remains available for subsequent calls and drops with the closure. Its environment is stored inline and has a different type from the code-only Callable. A reusable closure cannot move captures out; borrow or explicitly copy them when an independent owner is needed.

Use mut in the capture list for private state. A stateful closure also needs a mutable binding to call:

def main() -> Result[(), IoError | OverflowError[i64]]:
    count = 0
    mut next = def [mut count]() -> Result[i64, OverflowError[i64]]:
        count = count + 1
        Ok(count)
    print(next()?)?
    print(next()?)?
    print(count)?
    Ok(())

1
2
0

The captured scalar changes independently of the original count.

Accept functions and closures through one API

Constrain a type parameter by its call signature to accept named functions and captured closures through one parameter. Borrow the callback when its caller should keep it:

def apply[T, E, F: Callable[[T], Result[T, E]]](f: &F, value: T) -> Result[T, E]:
    f(value)

def double(value: i64) -> Result[i64, OverflowError[i64]]:
    Ok(value * 2)

def main() -> Result[(), IoError | OverflowError[i64] | OverflowError[u8]]:
    offset = 2u8
    add = def [offset](value: u8) -> Result[u8, OverflowError[u8]]:
        Ok(offset + value)
    print(apply(&double, 3)?)?
    print(apply(&add, 3u8)?)?
    Ok(())

6
5

A short callback can be written in the call. An anonymous function needs parentheses to be the operand of &:

def apply[T, E, F: Callable[[T], Result[T, E]]](f: &F, value: T) -> Result[T, E]:
    f(value)

def main() -> Result[(), IoError | OverflowError[i64]]:
    offset = 2
    print(apply(&(def [offset](value: i64) -> Result[i64, OverflowError[i64]]: Ok(offset + value)), 3)?)?
    print(apply(&(def(value: i64) -> Result[i64, OverflowError[i64]]: Ok(value * value)), 3)?)?
    Ok(())

5
9

F preserves the callback’s concrete environment type. Both arguments agree on T, the input and successful output type; E preserves the callback’s error type. The caller handles the returned Result normally. Use &mut F for a callback that changes its captured state. Borrowed captures stay protected throughout the call.

Borrow a named function directly with &double, or with &mut double for a &mut F parameter; a separate binding is optional. A function has no state, so each &mut borrow takes its own copy of the code address.

A concrete parameter such as f: Callable[[i64], i64] holds only a function’s code address. The constraint F: Callable[[i64], i64] instead checks whether the actual type can be called with that signature; its captured state remains inline. Adding & to the concrete Callable type does not make it accept closures. Closure[...] describes a concrete environment, chiefly when returning one from a factory.

Passing captured state to a code-only parameter explains the mismatch and suggests the generic form:

def apply(f: Callable[[i64], Result[i64, OverflowError[i64]]], value: i64) -> Result[i64, OverflowError[i64]]:
    f(value)
def main() -> ():
    offset = 3
    add = def [offset](value: i64) -> Result[i64, OverflowError[i64]]:
        Ok(value + offset)
    apply(add, 4)

for a generic callback API, use `F: Callable[[i64], Result[i64, OverflowError[i64]]]` with `callback: &F`

Let the callback determine a separate result type

The first helpers require the input and successful output to have the same type T. Give the complete result its own parameter U to allow other transformations, including infallible callbacks. The callback’s concrete signature determines U, including when it does not appear in another argument. This example uses both forms of callback through that shared interface:

def apply[T, U, F: Callable[[T], U]](callback: &F, value: T) -> U:
    callback(value)

def double(value: i64) -> Result[i64, OverflowError[i64]]:
    Ok(value * 2)

def main() -> Result[(), IoError | OverflowError[i64]]:
    offset = 7
    add = def [offset](value: i64) -> Result[i64, OverflowError[i64]]:
        Ok(offset + value)
    print(apply(&double, 10)?)?
    print(apply(&add, 10)?)?
    Ok(())

20
17

Borrow in a closure

A local callback may need to inspect data that its caller will use again. Use & in a capture list to keep ownership outside the closure:

def main() -> Result[(), AllocError | IoError]:
    mut values = [4]?
    read = def [&values]() -> i64:
        values[0]
    print(read())?
    moved = read
    print(moved())?
    values.append(5)?
    print(values)?
    Ok(())

4
4
[4, 5]

The borrow follows the closure into moved and ends after its last call. Changing the list before a later call would conflict with that borrow. Borrowing closures cannot be returned from their creating function or stored in collections or sum types. Pass them to other functions through reference parameters:

def invoke(f: &Closure[[], i64]) -> i64:
    f()

def main() -> Result[(), IoError]:
    value = 7
    read = def [&value]() -> i64:
        value
    print(invoke(read))?
    Ok(())

7

The &Closure parameter borrows read implicitly; invoke(&read) is also valid. The capture remains borrowed throughout invoke, including while its other arguments are being evaluated. A closure can also explicitly borrow another closure; the same rule protects all of their captured owners.

Use &mut to modify an existing binding rather than moving it into private state:

def main() -> Result[(), IoError | OverflowError[i64]]:
    mut count = 0
    mut increment = def [&mut count]() -> Result[(), OverflowError[i64]]:
        count = count + 1
        Ok(())
    increment()?
    increment()?
    print(count)?
    Ok(())

2

Both the source and closure bindings need mut. The original count becomes available again after the last closure call. Reading it before another call would conflict with the exclusive capture.

Return a closure

Return an owned closure to keep its captured data after its creating function returns. Closure describes the returned call signature:

def counter(start: i64) -> Closure[[], Result[i64, OverflowError[i64]]]:
    def [mut start]() -> Result[i64, OverflowError[i64]]:
        start = start + 1
        Ok(start)

def apply(f: &mut Closure[[], Result[i64, OverflowError[i64]]]) -> Result[i64, OverflowError[i64]]:
    f()

def main() -> Result[(), IoError | OverflowError[i64]]:
    mut first = counter(10)
    mut second = counter(30)
    print(apply(&mut first)?)?
    print(second()?)?
    print(first()?)?
    Ok(())

11
31
12

apply needs an exclusive borrow because calling the counter changes its state. For a read-only closure, use a shared parameter such as &Closure[[i64], Result[i64, OverflowError[i64]]].

Different anonymous expressions have different concrete environment types, even with identical signatures. A factory must return one concrete type on every path. Borrowing closures cannot escape their creating function. To return different owned shared-call environments, explicitly allocate a BoxedCallable.

An owned closure can capture another closure or be wrapped in Option or Result:

def make(offset: i64) -> Option[Closure[[i64], Result[i64, OverflowError[i64]]]]:
    inner = def [offset](value: i64) -> Result[i64, OverflowError[i64]]:
        Ok(offset + value)
    outer = def [inner](value: i64) -> Result[i64, OverflowError[i64]]:
        Ok(inner(value)? * 2)
    Some(outer)

def main() -> Result[(), IoError | OverflowError[i64]]:
    match make(3):
        case Some(calculate):
            print(calculate(4)?)?
        case Nothing:
            print("no callback")?
    Ok(())

14

Captured resources drop in reverse capture order, including nested environments.

You can call a returned closure immediately, for example counter(10)(). Its environment remains alive through the complete expression and is then dropped. ? in a later argument also cleans up that temporary. Match an optional closure before calling it, as in the example above.

Generic function values

A higher-order function can use a type parameter inside its callable signature. The compiler infers the type from the function value and the other arguments:

def increment(value: u8) -> Result[u8, OverflowError[u8]]:
    Ok(value + 1)

def apply[T, U](operation: Callable[[T], U], value: T) -> U:
    operation(value)

def main() -> Result[(), IoError | OverflowError[u8]]:
    print(apply(increment, 41u8)?)?
    Ok(())

42

Here T is u8. Passing 41i64 would conflict with increment’s signature.

To choose a generic function’s own type arguments, use brackets without calling it:

def identity[T](value: T) -> T:
    value

def main() -> Result[(), IoError]:
    keep = identity[u8]
    print(keep(42))?
    Ok(())

42

identity[u8] is a function value; identity[u8](42) calls that specialization.

A concrete callable annotation can also supply those type arguments:

def identity[T](value: T) -> T:
    value

def main() -> Result[(), IoError]:
    keep: Callable[[u8], u8] = identity
    print(keep(42))?
    Ok(())

42

This also works when a parameter or return type supplies the concrete signature. Without that context, use explicit brackets such as identity[u8].

Transform a cell with a generic method

Give a method its own type parameters to let a callback transform Cell[T] into Cell[U]:

class Cell[T]:
    value: T

    def map[U, F: Callable[[T], U]](self, transform: &F) -> Cell[U]:
        Cell(transform(self.value))

def double(value: u8) -> u16:
    # u8 is at most 255, so the doubled value is at most 510 in u16.
    unchecked:
        u16(value) * 2

def main() -> Result[(), IoError]:
    original = Cell(7u8)
    transform = double
    changed = original.map(&transform)
    print(changed.value)?
    print(original.value)?
    Ok(())

14
7

map borrows the original cell, so passing its field to the callback requires a copyable T. Here, double determines the result type U = u16.

Store stateful callbacks

Pair explicit state with a named function when a registry needs different callback bodies with the same state type and call signature:

class Handler[State]:
    state: State
    callback: Callable[[&mut State, i64], Result[i64, OverflowError[i64]]]
    def call(self: &mut Handler[State], value: i64) -> Result[i64, OverflowError[i64]]:
        self.callback(&mut self.state, value)

def accumulate(total: &mut i64, value: i64) -> Result[i64, OverflowError[i64]]:
    *total = *total + value
    Ok(*total)

def subtract(total: &mut i64, value: i64) -> Result[i64, OverflowError[i64]]:
    *total = *total - value
    Ok(*total)

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut handlers = [Handler(10, accumulate), Handler(100, subtract)]?
    for handler in &mut handlers:
        print(handler.call(3)?)?
    print(handlers[0].call(2)?)?
    Ok(())

13
97
15

Each record owns its state; call borrows it exclusively. Constructing the records needs no allocation, but storing them in a list does.

For different state shapes, use an enum and handle its variants in the callback. Owned concrete closures can also be stored when their producer types agree.

See examples/callback_registry.plenty for a registry example.

Store owned closures

A generic record can own a callback’s captured state. You do not need to name the closure’s concrete type: the constructor infers it.

class Handler[F: Callable[[i64], Result[i64, OverflowError[i64]]]]:
    callback: F
    def call(self: &mut Handler[F], amount: i64) -> Result[i64, OverflowError[i64]]:
        self.callback(amount)

def counter(total: i64) -> Closure[[i64], Result[i64, OverflowError[i64]]]:
    def [mut total](amount: i64) -> Result[i64, OverflowError[i64]]:
        total = total + amount
        Ok(total)

def main() -> Result[(), IoError | OverflowError[i64]]:
    mut first = Handler(counter(10))
    mut second = Handler(counter(100))
    print(first.call(3)?)?
    print(second.call(7)?)?
    print(first.callback(2)?)?
    Ok(())

13
107
15

The Callable constraint checks the signature without erasing the concrete environment type. Each record stores its environment inline.

Keep captured state owned when storing a callback. A closure borrowing a local cannot enter a record. Moving the record transfers ownership; dropping it cleans up captured resources. Closures do not support copy or equality.

Reduce a borrowed collection with a pipeline

iter pipelines also accept functions, so they can transform items without making an intermediate collection. Borrow the source when the caller should keep it.

class Payment:
    name: str
    cents: i64

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    payments = [Payment("bob", 120), Payment("ada", 300), Payment("bob", 80)]?
    selected = iter(&payments).filter(def(p: &Payment) -> bool: p.name == "bob")
    total = selected.map(def(p: &Payment) -> i64: p.cents).sum()?
    largest = iter(&payments).map(def(p: &Payment) -> i64: p.cents).max()
    refund = iter(&payments).any(def(p: &Payment) -> bool: p.cents < 0)
    print(total, largest, refund, len(payments))?
    Ok(())

200 Option[i64].Some(300) False 3

selected holds a loan of payments. The filter and map run when sum consumes the pipeline, in source order. A closure written directly in the chain, like the filter and map here, is compiled into that loop rather than called. The payments remain available afterwards. Trying to consume selected again is an ownership error.

sum and max work as in Chain iteration steps with iter; here they reduce mapped values, since a Payment is neither a number nor a str. Likewise, any and all take a predicate when the items are not bool. Use try_fold for a fallible accumulation, or fold for an infallible one.

A method returning a borrowed list can be used directly as the source. Its owner remains borrowed while the pipeline is in use:

class Readings:
    values: list[i64]

    def samples(self) -> &list[i64]:
        &self.values

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    readings = Readings([10, 20, 30]?)
    product = iter(readings.samples()).try_fold(1, def(acc: i64, n: &i64) -> Result[i64, OverflowError[i64]]: Ok(acc * *n))?
    print(product)?
    Ok(())

6000

try_fold starts with its first argument and passes the accumulator and each item to the callback. An Ok supplies the next accumulator; the first Err stops iteration and is returned to the caller.

Predicates borrow each item; map receives whatever the source yields. A borrowed list yields references, so the map above takes &Payment. A range yields integers by value:

def main() -> Result[(), IoError | OverflowError[i64]]:
    for square in iter(range(10)).skip(2).take(3).map(def(n: i64) -> Result[i64, OverflowError[i64]]: Ok(n * n)):
        print(square?)?
    Ok(())

4
9
16

Use try_collect when a transformation can fail and the desired result is an owned collection. The annotation chooses the collection, and ? preserves the first parsing or allocation error:

def main() -> Result[(), AllocError | ParseError | IoError]:
    lines = ["10", "20", "30"]?
    values: list[i64] = iter(&lines).map(def(line: &str) -> Result[i64, ParseError]: i64.parse(line)).try_collect()?
    print(values, len(lines))?
    Ok(())

[10, 20, 30] 3

For an infallible transformation, use collect() with the same annotation. try_fold and try_for_each propagate errors returned by their callbacks; they do not automatically unwrap Result items.

After enumerate or zip, callbacks take two item parameters. Predicates borrow both components; mapping receives the index by value and the borrowed item:

def main() -> Result[(), AllocError | IoError]:
    names = ["Ada", "Bob", "Cal"]?
    indexed = iter(&names).enumerate(1)
    selected = indexed.filter(def(i: &i64, name: &str) -> bool: *i != 2)
    labels: dict[i64, str] = selected.map(def(i: i64, name: &str) -> Result[(i64, str), AllocError]: Ok((i, copy(name)?))).try_collect()?
    print(labels[1], labels[3], len(names))?
    Ok(())

Ada Cal 3

Copying a name can fail, so try_collect propagates that error as well as dictionary allocation errors. The successful owned pairs become dictionary entries. Repeated keys keep the last value. A pair fold takes the accumulator followed by both item components; a tuple accumulator stays a single parameter. Zip stops at the shorter input, pulling the left first, so it may consume one extra left item.

Use chain to continue with a second source of the same item type, and flat_map when each item expands into a source of its own:

class Batch:
    first: i64
    stop: i64

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    morning = [3, 1]?
    evening = [4]?
    total = iter(&morning).chain(&evening).sum()?
    print(total)?
    batches = [Batch(100, 102), Batch(200, 201)]?
    for ticket in iter(&batches).flat_map(def(b: &Batch) -> range[i64]: range(b.first, b.stop)):
        print(ticket)?
    Ok(())

8
100
101
200

Both lists stay borrowed until the sum ends. The flat_map callback runs once per batch, only after the previous batch’s tickets are used up, and returns a range, so nothing is allocated. Batch stores start and stop endpoints directly; constructing the range needs no endpoint arithmetic. A callback may return any owned iterable, such as a list, range or generator; returning a list allocates one list per item.

Lend a pipeline whose callbacks borrow

A pipeline lent to a function can use a closure that borrows, when the closure is written inside the adapter call:

def first(p: &mut Iter[i64]) -> Option[i64]:
    next(p)

def main() -> Result[(), IoError]:
    limit = 3
    mut above = iter(range(9)).filter(def [&limit](x: &i64) -> bool: *x > limit)
    print(first(&mut above))?
    print(above.count())?
    Ok(())

Option[i64].Some(4)
4

Storing the same closure in a variable first and passing the variable makes the pipeline impossible to lend:

def first(p: &mut Iter[i64]) -> Option[i64]:
    next(p)

def main() -> Result[(), IoError]:
    limit = 3
    keep = def [&limit](x: &i64) -> bool:
        *x > limit
    mut above = iter(range(9)).filter(keep)
    print(first(&mut above))?
    Ok(())

it holds closure `keep`, which is stored in a variable and borrows its captures; write the closure literal inside the adapter call instead

A closure written in the chain is compiled into the pipeline, so its borrow of limit becomes one of the pipeline’s own loans, which the caller keeps while first runs. A stored closure is a value holding that reference inside it, and a function receiving a lent pipeline cannot take such a value. Without the lend, both forms work.

Keep a plain loop for several statements or error propagation, and use a comprehension when building a list is the clearest form. Pipelines are local: Transform a stream of values applies them to generators and shows how to return a stream from a function. See the pipeline reference for terminals and the current limits.

Transform a stream of values

A generator has the same pipeline methods as iter(...), so a stream of values can be filtered, mapped and reduced without an intermediate list:

def numbers(stop: i64) -> Generator[i64]:
    for n in range(stop):
        yield n

def main() -> Result[(), IoError | OverflowError[i64]]:
    two: NonZero[i64] = 2
    evens = numbers(10).filter(def [two](n: &i64) -> bool: *n % two == 0)
    for square in evens.map(def(n: i64) -> Result[i64, OverflowError[i64]]: Ok(n * n)):
        n = square?
        print(n)?
        if n > 3:
            break
    Ok(())

0
4

The generator body and callbacks run only when the loop asks for a value, and break drops the rest of the chain: numbers never makes 3. The adapters are fused into the loop, so they add no allocation or generator frame of their own.

take limits how many items are requested from a generator. Callbacks can capture values, as with any closure:

def naturals() -> Generator[i64]:
    for n in range(i64.MAX):
        yield n

def main() -> Result[(), IoError | OverflowError[i64]]:
    offset = 100
    for n in naturals().map(def [offset](n: i64) -> Result[i64, OverflowError[i64]]: Ok(n + offset)).take(3):
        print(n?)?
    Ok(())

100
101
102

naturals is bounded by the representable range rather than overflowing a manual counter. take(3) requests only its first three values. The map returns ordinary public Result items, which the loop propagates before printing.

Return a stream

A pipeline stays in the function that builds it. When a chain needs to be returned or passed to another function, end it with .generator(). This explicitly moves the source and captures into one resumable generator, with the adapters still fused inside it:

def squares(stop: i64) -> Generator[Result[i64, OverflowError[i64]]]:
    iter(range(stop)).map(def(n: i64) -> Result[i64, OverflowError[i64]]: Ok(n * n)).generator()

def total(values: Generator[Result[i64, OverflowError[i64]]]) -> Result[i64, OverflowError[i64]]:
    values.try_fold(0, def(acc: i64, n: Result[i64, OverflowError[i64]]) -> Result[i64, OverflowError[i64]]: Ok(acc + n?))

def main() -> Result[(), IoError | OverflowError[i64]]:
    print(total(squares(4))?)?
    mut values = squares(3)
    first = next(values).unwrap()?
    second = next(values).unwrap()?
    print(Some(first), Some(second))?
    Ok(())

14
Option[i64].Some(0) Option[i64].Some(1)

The two unwrap calls assert only that squares(3) has at least two items; the arithmetic Result in each item is still propagated with ?. For an unknown-length stream, match next instead. A generator cannot propagate an arithmetic error from its body: yielding Result items lets its consumer decide how to handle failure. try_fold here handles each item as well as its own addition.

Conversion does not visit any items. The returned generator owns its source and captures, so a pipeline over a borrowed list or with borrowed captures cannot be converted, even after mapping to owned values; return an owned collection instead. Dropping the generator early releases its remaining state.

Each next resumes the generator, which costs more than a fused local loop. Consume a pipeline where it is built unless a resumable stream must cross a function boundary. See the pipeline reference for the full list of adapters and terminals.

Keep callbacks in tuples and lists

A tuple can hold callbacks with different concrete types. Indexing invokes a callback in place; unpacking transfers ownership to new local bindings.

def add(offset: i64) -> Closure[[i64], Result[i64, OverflowError[i64]]]:
    def [offset](n: i64) -> Result[i64, OverflowError[i64]]:
        Ok(offset + n)

def main() -> Result[(), IoError | OverflowError[i64]]:
    pair = (add(10), add(100))
    print(pair[0](2)?)?
    first, second = pair
    print(second(3)?)?
    Ok(())

12
103

Calls to one factory also fit in a list. Each callback owns its own state.

def counter(total: i64) -> Closure[[], Result[i64, OverflowError[i64]]]:
    def [mut total]() -> Result[i64, OverflowError[i64]]:
        total = total + 1
        Ok(total)

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut callbacks = [counter(n) for n in range(3)]?
    for callback in &mut callbacks:
        print(callback()?)?
    match callbacks.pop(0):
        case Some(callback):
            mut removed = callback
            print(removed()?)?
        case Nothing:
            print("no callback")?
    print(callbacks[0]()?)?
    Ok(())

1
2
3
2
3

pop transfers the callback out of the list. A borrowed callback prevents resizing or removing entries until its borrow ends.

Name stored callbacks

A dictionary can associate names with owned callbacks from one factory. Calling a callback that changes its captured state needs a mutable borrow: use get_mut to keep the callback registered, or pop to take ownership.

def counter(total: i64) -> Closure[[], Result[i64, OverflowError[i64]]]:
    def [mut total]() -> Result[i64, OverflowError[i64]]:
        total = total + 1
        Ok(total)

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut callbacks = {"open": counter(10), "close": counter(100)}?
    match callbacks.get_mut("open"):
        case Some(callback):
            print(callback()?)?
        case Nothing:
            print("no open handler")?
    match callbacks.pop("close"):
        case Some(callback):
            mut owned = callback
            print(owned()?)?
        case Nothing:
            print("no close handler")?
    print(len(callbacks))?
    Ok(())

11
101
1

Replacing a registered callback drops the old captured state. Inserting a new key may grow the dictionary and returns Result. A live borrow of any callback protects the dictionary against replacement, removal, and growth.

The callback itself cannot be a dictionary key or a set element: closures do not define equality or hashing. The dictionary’s value type preserves its concrete factory identity, rather than accepting every callback with the same signature. Use explicit boxing to store different shared-call environments behind one signature.

Store different captured callbacks

Concrete closures remember where they were defined. To put different closures behind one signature, explicitly allocate a BoxedCallable. Its constructor consumes the callback and returns Result, so ? handles allocation failure.

def choose(k: i64) -> Result[BoxedCallable[[i64], Result[i64, OverflowError[i64]]], AllocError]:
    if k > 0:
        add = def [k](value: i64) -> Result[i64, OverflowError[i64]]:
            Ok(k + value)
        return BoxedCallable(add)
    span = range(10, 13)
    multiply = def [span](value: i64) -> Result[i64, OverflowError[i64]]:
        Ok(span[1] * value)
    BoxedCallable(multiply)

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    callbacks: dict[str, BoxedCallable[[i64], Result[i64, OverflowError[i64]]]] = {
        "add": choose(3)?,
        "multiply": choose(0)?,
    }?
    print(callbacks["add"](4)?)?
    print(callbacks["multiply"](4)?)?
    borrowed = &callbacks["add"]
    print(borrowed(5)?)?
    Ok(())

7
44
8

The factory’s branches capture different data but return the same boxed signature. Calling borrows the stored owner, so repeated calls keep it registered and require no extra allocation. Ordinary moves transfer ownership, and dropping or replacing the owner drops its captures. Named functions can also use BoxedCallable(name).

This type currently accepts reusable shared-call callbacks with owned captures. Keep mutable, one-shot, borrowed, or generator-containing closures concrete. Callbacks returning references and worker transfer are also unsupported. Boxing does not make a callback copyable or comparable; use names as registry keys.

Put a callback in an enum

An enum can also own a callback. Match a borrow when you want to leave the owner in place, or match the value to transfer its environment into an arm.

enum Job[F: Callable[[], i64]]:
    Run(F)
    Empty

def package[F: Callable[[], i64]](callback: F) -> Job[F]:
    Job[F].Run(callback)

def invoke[F: Callable[[], i64]](job: &Job[F]) -> i64:
    match &job:
        case Job.Run(callback):
            callback()
        case Job.Empty:
            0

def main() -> Result[(), IoError]:
    value = 42
    callback = def [value]() -> i64:
        value
    job = package(callback)
    print(invoke(&job))?
    Ok(())

42

Consume a capture

A reusable closure borrows its captured state on each call. Sometimes the purpose of the callback is to hand over an owned value. Mark that callback once:

def main() -> Result[(), AllocError | IoError]:
    values = [2, 3, 5]?
    take = def once [values]() -> list[i64]:
        values
    result = take()
    print(result)?
    Ok(())

[2, 3, 5]

take() consumes the callback and transfers its captured list to the result. A second call is a use-after-move error. If take is never called, dropping it cleans up the list.

Consume a callback

Use OnceCallable for a function that owns and calls its callback once. It accepts named functions, reusable closures, and one-shot closures.

pub def run[T, F: OnceCallable[[], T]](callback: F) -> T:
    mut owned = callback
    owned()

import callbacks

def defer[T](value: T) -> OnceClosure[[], T]:
    def once [value]() -> T:
        value

def main() -> Result[(), AllocError | IoError]:
    take = defer([3, 5]?)
    print(callbacks.run(take))?
    Ok(())

[3, 5]

OnceClosure describes the concrete value returned by defer. OnceCallable describes what the generic run function can accept. Passing take transfers ownership; calling it again afterward is an error. The mutable local inside run also permits reusable callbacks that update private captured state.

Consume owned data while borrowing local state

For a callback that also borrows local state, invoke it in that local scope:

def main() -> Result[(), AllocError | IoError | OverflowError[i64]]:
    mut count = 0
    values = [8]?
    take = def once [values, &mut count]() -> Result[list[i64], OverflowError[i64]]:
        count = count + 1
        Ok(values)
    result = take()?
    print(count)?
    print(result)?
    Ok(())

1
[8]

The borrow ends after the call. This callback cannot be passed to callbacks.run because a borrowing environment cannot move across function boundaries.

Store consuming jobs

A stored job may need to hand its captured resources to its caller. Use the existing def once form and extract the job before calling it.

def make_job(n: i64) -> Result[OnceClosure[[], list[i64]], AllocError]:
    values = [n]?
    job = def once [values]() -> list[i64]:
        values
    Ok(job)

def main() -> Result[(), AllocError | IoError]:
    mut jobs = [make_job(10)?, make_job(20)?]?
    match jobs.pop(0):
        case Some(job):
            print(job())?
        case Nothing:
            pass
    for job in jobs:
        print(job())?
    Ok(())

[10]
[20]

Calling jobs[0]() would try to consume a borrowed entry and is rejected. Extract an owned callback with pop, consuming iteration, consuming enum matching, or tuple unpacking.

Dropping uncalled jobs cleans up their captures. Borrowed captures and generator-containing environments cannot be stored in these heap owners.

Concurrent and parallel programs

Use scoped threads for work that borrows local data, or an executor for many owned jobs. Captured jobs use the functions-as-values lessons; generic recovery helpers also use type parameters.

• Import concurrency explicitly
• Run scoped threads
• Borrow local data for a worker
• Count with atomics
• Share mutable state with a mutex
• Choose how workers share state
• Move jobs to workers
• Run stored jobs
• Send values between threads
• Avoid waits that hang
• Handle channel backpressure
• Bound your waits
• Share one deadline across waits
• Reuse workers with an executor
• Handle executor outcomes
• Share state with pool workers
• Cancel queued work and bound a future wait
• Stop work cooperatively
• Recover a job when submission cannot proceed
• Map fallible work in parallel
• Combine values in parallel
• Receive from either channel
• Wait for I/O with a deadline
• Serve a TCP connection
• Encrypt a TCP connection
• Verify clients and choose a protocol
• Serve HTTP requests
• Stop a server on a signal
• Read forms, cookies and forwarded clients
• Serve files and sign cookies
• Send HTTP requests
• Share one HTTP client between workers
• Talk over WebSockets
• Stream events to browsers

Import concurrency explicitly

The concurrency operations in these lessons also have explicit standard-library imports. Module aliases and item aliases name the same facilities and types as the familiar prelude spellings. Existing programs continue to work.

import std.thread as threads
from std.channel import channel as bounded, Receiver as Inbox
from std.concurrent import ThreadPoolExecutor as Pool
from std.sync import CancellationToken as Stop

def receive(inbox: Inbox[str]) -> Result[str, RecvError]:
    inbox.recv()

def stopped(stop: Stop) -> bool:
    stop.wait()
    stop.is_cancelled()

type Errors = AllocError | IoError | SendError[str] | RecvError | SpawnError[()] | PoolError | FutureError | SubmitError[()]

def main() -> Result[(), Errors]:
    sender, receiver = bounded[str](1)?
    sender.send("hello")?
    drop(sender)
    with threads.spawn(receive, receiver).drop_job()? as task:
        print(task.join()?)?
    stop = Stop()?
    with Pool(1, 1)? as pool:
        future = pool.submit(stopped, stop.share()).drop_job()?
        stop.cancel()
        print(future.result()?)?
    Ok(())

hello
True

Dropping the sender before joining permits a receiving worker to finish even when it loops until disconnection. Imported names retain the same loan, worker-effect, queue-bound and hang diagnostics as prelude names. Error types can also be imported: from std.concurrent import FutureError, for example. Importing an existing builtin under its own name is allowed only when it names that exact builtin; unrelated imports still cannot replace it.

The module references list the complete surfaces: std.thread, std.channel, std.concurrent, and std.sync. Imports ship inside the compiler and need no network or separately installed Plenty sources.

A failed submission returns its unstarted job inside SubmitError; drop_job() drops it and leaves SubmitError[()], as the executor lesson explains. A spawn of a named function with owned arguments works the same way: it returns them inside SpawnError, and drop_job() leaves SpawnError[()].

Run scoped threads

Use with spawn(...) to run a function on a native thread. The current thread continues until join() waits for the result:

def squares(n: i64) -> Result[list[i64], AllocError | OverflowError[i64]]:
    [i * i for i in range(n)]

def main() -> Result[(), SpawnError[()] | AllocError | IoError | OverflowError[i64]]:
    with spawn(squares, 4).drop_job()? as first, spawn(squares, 3).drop_job()? as second:
        print(first.join()?)?
        print(second.join()?)?
    Ok(())

[0, 1, 4, 9]
[0, 1, 4]

The ? after spawn(...) handles failure to create the thread. The ? after join() handles the worker’s own Result, here allocation failure or arithmetic overflow while building its list. They are separate failures. drop_job() is explained in error types at thread start. Join consumes the task binding, so it cannot be called twice.

Every started thread finishes before its with block exits. This includes return, ?, break, and continue. If you omit join(), exit waits and drops the unused result, including any application error. Join when the result matters. A task cannot escape its block or be stored for later.

Scopes cannot forcibly cancel workers. Keep their computations finite or give them a shutdown protocol. Fatal traps terminate the process without unwinding.

Error types at thread start

A failed start reports SpawnError[F], which returns the unstarted job: here the function and its arguments. drop_job() drops that job at the start, so the error becomes SpawnError[()], one member for every start. Keep the job when you want to retry it, as owned worker jobs shows. Borrowed workers report SpawnError[()] too.

Like any ?, the start error widens into the enclosing Result’s error sum, so main lists SpawnError[()] beside the worker’s AllocError and OverflowError[i64], and the printing IoError. A sum without the start error is rejected.

Use module-level error aliases to keep longer signatures readable, as in executor jobs. Each alias names that example’s propagated errors; it does not change widening through ? or introduce an error wrapper.

Borrow local data for a worker

Borrow mutable inputs explicitly. Shared readers can coexist; an exclusive borrow prevents the parent from accessing the same data until the block ends. Join explicitly to propagate a worker’s arithmetic error:

def increment(value: &mut i64) -> Result[(), OverflowError[i64]]:
    *value = *value + 1
    Ok(())

def main() -> Result[(), SpawnError[()] | IoError | OverflowError[i64]]:
    mut count = 4
    with spawn(increment, &mut count)? as task:
        task.join()?
    print(count)?
    Ok(())

5

The borrow lasts until the block ends, even after an explicit join. Reading or modifying count inside the block conflicts with it; use a shorter block when you need access back sooner.

Reusable closures work too. Borrow the closure itself so that a failed start leaves the job available to retry:

def main() -> Result[(), SpawnError[()] | IoError | AllocError]:
    mut values = [1, 2]?
    mut job = def [&mut values]() -> Result[i64, AllocError]:
        values.append(3)?
        Ok(len(values))
    with spawn(&mut job)? as task:
        print(task.join()?)?
    print(values)?
    Ok(())

3
[1, 2, 3]

For immutable captures, spawn(&job) allows shared access. Scoped work may borrow or own its inputs, so a named worker can also receive an owned list:

def total(values: list[i64]) -> Result[i64, OverflowError[i64]]:
    mut result = 0
    for value in values:
        result = result + value
    Ok(result)

def main() -> Result[(), SpawnError[()] | IoError | AllocError | OverflowError[i64]]:
    values = [2, 3, 4]?
    with spawn(total, values).drop_job()? as task:
        print(task.join()?)?
    Ok(())

9

values moves and cannot be used again. Because every argument is owned, the start reports SpawnError, like the scoped threads lesson’s starts: without drop_job() a failed start would return values inside the error. A start that borrows reports the job-free SpawnError[()], because an error cannot hold a borrow. If such a start fails, its moved arguments drop on the parent thread.

To preserve creation error details, put the scope in a helper and match its result. SpawnError.Unavailable(job, code) contains the native error code.

The compiler checks worker helpers, captured data, and destructors. Foreign calls, File values, indirect function calls, and generators are not yet eligible. Worker code can use checked print, but output from different threads may arrive in any order.

Count with atomics

A shared borrow lets several workers read the same data, but not change it. An atomic from std.atomic is the exception: its methods update it through a shared reference, one indivisible step at a time:

from std.atomic import Atomic, Ordering

def count(hits: &Atomic[u64], rounds: i64) -> ():
    for _ in range(rounds):
        hits.fetch_add(1, Ordering.Relaxed)

def main() -> Result[(), SpawnError[()] | IoError]:
    hits = Atomic[u64](0)
    with spawn(count, &hits, 100000)?, spawn(count, &hits, 100000)?:
        pass
    print(hits.load(Ordering.Acquire))?
    Ok(())

200000

Atomic[u64](0) stores the counter inline in main’s frame; nothing is allocated. fetch_add returns the value it replaced. It stops the program on overflow, before storing anything.

Every operation names an Ordering. Relaxed only makes the update itself indivisible. Release on a store and Acquire on a load make the writes before the store visible to the thread that loads it. Use SeqCst when unsure. The compiler rejects orderings an operation cannot use:

from std.atomic import Atomic, Ordering

def main() -> ():
    ready = Atomic[bool](False)
    ready.store(True, Ordering.Acquire)

store does not accept Ordering.Acquire; use Ordering.Relaxed, Ordering.Release, or Ordering.SeqCst

A class can hold atomics as fields, so one borrow shares several of them. Atomics are not values to print or compare, so read each one with load:

from std.atomic import Atomic, Ordering

class Stats:
    seen: Atomic[u32]
    largest: Atomic[i64]

def record(stats: &Stats, start: i64) -> Result[(), OverflowError[i64]]:
    for value in range(start, start + 1000):
        stats.seen.fetch_add(1, Ordering.Relaxed)
        stats.largest.fetch_max(value, Ordering.Relaxed)
    Ok(())

def main() -> Result[(), SpawnError[()] | IoError | OverflowError[i64]]:
    stats = Stats(seen=Atomic(0), largest=Atomic(i64.MIN))
    with spawn(record, &stats, 0)? as first, spawn(record, &stats, 5000)? as second:
        first.join()?
        second.join()?
    print(stats.seen.load(Ordering.Acquire))?
    print(stats.largest.load(Ordering.Acquire))?
    Ok(())

2000
5999

compare_exchange replaces a value only if it still equals the one you expect, and returns Err with the actual value otherwise. See std.atomic for every method.

Share mutable state with a mutex

An atomic keeps one value consistent. When several values must change together, put them in a Mutex from std.sync. Only one thread at a time can hold its lock, so no worker sees count updated without total:

from std.sync import Mutex

class Stats:
    count: i64
    total: i64

def record(stats: &Mutex[Stats], value: i64, rounds: i64) -> Result[(), OverflowError[i64]]:
    for _ in range(rounds):
        with stats.lock() as data:
            count = data.count + 1
            total = data.total + value
            data.count = count
            data.total = total
    Ok(())

def main() -> Result[(), SpawnError[()] | IoError | OverflowError[i64]]:
    stats = Mutex[Stats](Stats(0, 0))
    with spawn(record, &stats, 3, 10000)? as first, spawn(record, &stats, 4, 10000)? as second:
        first.join()?
        second.join()?
    final = stats.into_inner()
    print(final.count)?
    print(final.total)?
    Ok(())

20000
70000

stats.lock() waits until no other thread holds the lock, then binds data, a &mut Stats, for the block. Leaving the block unlocks, whether by reaching its end, return, ?, break, or continue. Both new fields are computed before either is stored, so arithmetic failure cannot leave a half-updated pair. Workers share &stats without mut, because the lock, not the borrow, makes the access exclusive. After the workers finish, into_inner() takes the value back without locking. Nothing here allocates.

lock() works only as a with manager, so a lock cannot be left held by mistake. data belongs to the block: it cannot be stored, returned, or used after it.

Waiting under a lock for something that needs the same lock never finishes. The compiler rejects the waits it can see. Relocking a mutex inside its own block is one; joining a worker that can lock the same kind of mutex is another:

from std.sync import Mutex

def bump(counter: &Mutex[i64]) -> Result[(), OverflowError[i64]]:
    with counter.lock() as value:
        *value = *value + 1
    Ok(())

def main() -> Result[(), SpawnError[()]]:
    counter = Mutex(0)
    with counter.lock() as value:
        with spawn(bump, &counter)?:
            pass
    Ok(())

leaving this `with` block joins a task whose worker can lock a `Mutex[i64]` while this function holds a lock on a `Mutex[i64]`
note: the lock is acquired here; end the lock's `with` block before this one, or start the task outside it

Start the task first, then lock inside its block: the lock’s block ends, and unlocks, before the task is joined.

from std.sync import Mutex

def bump(counter: &Mutex[i64]) -> Result[(), OverflowError[i64]]:
    with counter.lock() as value:
        *value = *value + 1
    Ok(())

def main() -> Result[(), SpawnError[()] | IoError | OverflowError[i64]]:
    counter = Mutex(0)
    with spawn(bump, &counter)? as task:
        with counter.lock() as value:
            *value = *value + 10
        task.join()?
    print(counter.into_inner())?
    Ok(())

11

Nesting a lock inside the block of another mutex of the same type is also rejected when either one is reached through a reference or a computed index: two references can name one mutex. Two separately owned mutexes, such as two local names, may nest. The compiler cannot see a relock inside a called function, a join inside a function called while the lock is held, or two threads taking two locks in opposite orders. Keep lock blocks short and take nested locks in one fixed order. See std.sync and mutexes for the full rules.

Choose how workers share state

Prefer giving each worker what it needs and taking results back. Reach for shared mutable state only when workers must see each other’s changes while running.

Here each worker sums its own slice of the work and returns the result, so nothing is shared and nothing needs a lock:

def total(start: i64, end: i64) -> Result[i64, OverflowError[i64]]:
    mut sum = 0
    for value in range(start, end):
        sum = sum + value
    Ok(sum)

def main() -> Result[(), SpawnError[()] | IoError | OverflowError[i64]]:
    with spawn(total, 0, 500).drop_job()? as low, spawn(total, 500, 1000).drop_job()? as high:
        print(low.join()? + high.join()?)?
    Ok(())

499500

An atomic is the cheapest shared update, but each operation is separate: two atomics updated one after the other can be observed half-done. A mutex makes a whole block of updates appear at once, at the cost of making other threads wait.

Atomics and mutexes are shared by borrowing, so they work with scoped threads. Executor jobs must own their inputs, so they cannot borrow either one. Give each job its own owner of a Shared[Atomic[T]] or Shared[Mutex[T]] instead, or send jobs their data and collect their results.

Move jobs to workers

An owned closure can move its inputs into a worker. Use a one-shot closure when the worker also moves those inputs into its result.

def main() -> Result[(), AllocError | IoError | SpawnError[OnceClosure[[], list[i64]]]]:
    values = [3, 4]?
    with spawn(def once [values]() -> list[i64]: values)? as task:
        print(task.join())?
    Ok(())

[3, 4]

If thread creation fails, the error is SpawnError[F].Unavailable(job, code), which retains the complete job and the native error code. F is the closure’s own type. The signature writes OnceClosure[[], list[i64]], and ? fills in the concrete closure it propagates, so main returns the unstarted job unchanged.

A signature names one closure there: a second spawn of a different closure literal is rejected. When you do not need the job back, call drop_job() on each start. It drops a failed start’s job right away, and the error becomes SpawnError[()], which names no job, so one member covers every start:

def main() -> Result[(), AllocError | IoError | SpawnError[()]]:
    values = [3, 4]?
    with spawn(def once [values]() -> list[i64]: values).drop_job()? as first:
        print(first.join())?
    with spawn(def once () -> str: "done").drop_job()? as second:
        print(second.join())?
    Ok(())

[3, 4]
done

Dropping the job also drops the channel endpoints it captured, so they cannot keep a later join waiting; avoid waits that hang shows why that matters.

To keep the job, make each one with one factory function, or use a generic helper, which names the job as F. Recover the job to retry or run it locally, as this helper does:

def attempt[F: OnceCallable[[], i64]](job: F) -> Result[i64, SpawnError[F]]:
    with spawn(job)? as task:
        return Ok(task.join())

def run[F: OnceCallable[[], i64]](job: F) -> i64:
    match attempt(job):
        case Ok(value):
            value
        case Err(SpawnError.Unavailable(job, _)):
            job()

def main() -> Result[(), IoError]:
    n = 42
    job = def once [n]() -> i64:
        n
    print(run(job))?
    Ok(())

42

A reusable closure can also be moved into spawn; its captures are dropped after the worker’s single invocation.

Run stored jobs

Stored reusable callbacks can run on scoped threads. Borrow them explicitly, just as you would borrow a local closure. Distinct tuple slots have separate loans.

def counter(total: i64) -> Closure[[], Result[i64, OverflowError[i64]]]:
    def [mut total]() -> Result[i64, OverflowError[i64]]:
        total = total + 1
        Ok(total)

def main() -> Result[(), SpawnError[()] | IoError | OverflowError[i64]]:
    mut jobs = (counter(10), counter(100))
    with spawn(&mut jobs[0])? as first, spawn(&mut jobs[1])? as second:
        print(first.join()?)?
        print(second.join()?)?
    print(jobs[0]()?)?
    Ok(())

11
101
12

A failed start leaves its borrowed callback owned by the caller. Any earlier successful start is joined.

Workers can also return an owned callback through join():

def make(offset: i64) -> Closure[[i64], Result[i64, OverflowError[i64]]]:
    def [offset](n: i64) -> Result[i64, OverflowError[i64]]:
        Ok(offset + n)

def main() -> Result[(), SpawnError[()] | IoError | OverflowError[i64]]:
    with spawn(make, 10).drop_job()? as task:
        callback = task.join()
        print(callback(3)?)?
    Ok(())

13

List and dictionary entries can also supply a borrowed job. Except at distinct literal list indices, their loans protect the whole collection. Even after join(), wait until the with block ends before resizing or replacing that collection. Stored callbacks have the same thread-eligibility restrictions as local ones.

Send values between threads

A channel transfers owned messages from senders to receivers. Give it a fixed capacity to bound queued memory: a sender waits when the queue is full, and a receiver waits when it is empty.

def produce(sender: Sender[i64]) -> Result[(), SendError[i64] | OverflowError[i64]]:
    for n in range(5):
        sender.send(n * n)?
    Ok(())

def drain(inbox: &Receiver[i64]) -> Result[i64, OverflowError[i64]]:
    mut total = 0
    while True:
        match inbox.recv():
            case Ok(value):
                total = total + value
            case Err(_):
                break
    Ok(total)

def main() -> Result[(), SpawnError[()] | AllocError | IoError | OverflowError[i64]]:
    sender, receiver = channel[i64](2)?
    with spawn(produce, sender).drop_job()?, receiver as inbox:
        print(drain(inbox)?)?
    Ok(())

30

This introductory example deliberately leaves the producer result unclaimed to focus on endpoint guards; use the explicit join pattern when worker errors affect the outcome. The receiver’s accumulation error is still propagated.

spawn(produce, sender) moves the only sender into the producer. When the producer returns, its sender drops; the receiver drains the queue, then reports disconnection, which ends the loop. A blocking recv fails only on disconnection, so case Err(_) is enough here.

The receiver guard is the last manager in the with statement. Managers exit in reverse order, so however the body exits, the receiver drops before Plenty joins the producer. A producer waiting for queue space then sees disconnection instead of waiting forever.

Plenty requires this. A join reached while receiver is still alive could wait forever for a producer blocked on a full queue, so the compiler rejects it:

def produce(sender: Sender[i64]) -> Result[(), SendError[i64] | OverflowError[i64]]:
    for n in range(5):
        sender.send(n * n)?
    Ok(())

def main() -> Result[(), SpawnError[()] | AllocError | RecvError | IoError | OverflowError[i64]]:
    sender, receiver = channel[i64](2)?
    with spawn(produce, sender).drop_job()?:
        print(receiver.recv()?)?
    Ok(())

leaving this `with` block joins a task whose worker holds `Sender[i64]` while `receiver` still holds `Receiver[i64]`

The compiler compares message types rather than following each queue, so it also asks for this order in some programs that could not hang. Write the guard anyway; it costs nothing.

Wait for the producer’s result

The automatic join above drops the producer’s result. To check it with task.join(), finish with the receiver first: put its guard inside the task’s block, before any statement that can leave the block, and join after the guard ends.

def produce(sender: Sender[i64]) -> Result[(), SendError[i64] | OverflowError[i64]]:
    for n in range(5):
        sender.send(n * n)?
    Ok(())

def drain(inbox: &Receiver[i64]) -> Result[i64, OverflowError[i64]]:
    mut total = 0
    while True:
        match inbox.recv():
            case Ok(value):
                total = total + value
            case Err(_):
                break
    Ok(total)

def main() -> Result[(), SpawnError[()] | AllocError | IoError | SendError[i64] | OverflowError[i64]]:
    sender, receiver = channel[i64](2)?
    with spawn(produce, sender).drop_job()? as task:
        mut total = 0
        with receiver as inbox:
            total = drain(inbox)?
        task.join()?
        print(total)?
    Ok(())

30

total is declared before the inner guard because a binding made inside a block ends with that block. task.join()? propagates the producer’s SendError[i64] or OverflowError[i64], if any.

A ? before the guard leaves the block with the receiver still alive, so this version is rejected:

def produce(sender: Sender[i64]) -> Result[(), SendError[i64] | OverflowError[i64]]:
    for n in range(5):
        sender.send(n * n)?
    Ok(())

def drain(inbox: &Receiver[i64]) -> Result[i64, OverflowError[i64]]:
    mut total = 0
    while True:
        match inbox.recv():
            case Ok(value):
                total = total + value
            case Err(_):
                break
    Ok(total)

def main() -> Result[(), SpawnError[()] | AllocError | IoError | SendError[i64] | OverflowError[i64]]:
    sender, receiver = channel[i64](2)?
    with spawn(produce, sender).drop_job()? as task:
        print("receiving")?
        mut total = 0
        with receiver as inbox:
            total = drain(inbox)?
        task.join()?
        print(total)?
    Ok(())

leaving this `with` block joins a task whose worker holds `Sender[i64]` while `receiver` still holds `Receiver[i64]`
`?` leaves the block here

Prefer a guard to drop(receiver): a drop protects only the paths that reach it, and an earlier ? does not.

A receiving worker

The same order applies when the worker receives: an empty queue keeps it waiting while any sender survives. Guard the sender last, so every exit disconnects the queue before the join:

def consume(receiver: Receiver[i64]) -> ():
    match receiver.recv():
        case Ok(_):
            pass
        case Err(_):
            pass

def main() -> Result[(), SpawnError[()] | AllocError | SendError[i64]]:
    sender, receiver = channel[i64](1)?
    with spawn(consume, receiver).drop_job()?, sender as outbox:
        outbox.send(42)?
    Ok(())

Leaving sender alive until after this block is rejected, even if the message is already queued. For an explicit task.join(), end an inner sender guard first, as with the receiver above.

Ownership and cost

Create additional handles explicitly with sender.share() or receiver.share(). Multiple receivers compete for messages on the same queue: each message is delivered to one of them. Disconnection occurs only after the last handle on that side drops, so every handle you keep needs a guard or a drop. The wait habits lesson shows how to start several producers.

Channel construction can fail. Its positive capacity fixes the queue’s storage up front; sending and receiving introduce no further allocations. Messages still use their ordinary types: sending a list moves it, and receiving returns its ownership. A failed send returns the unsent value inside its error.

A failed start returns its owned arguments, including endpoints, inside SpawnError, as in owned worker jobs. drop_job() drops them at the start instead, so the error holds no endpoint; wait habits shows why that matters.

Avoid waits that hang

A join waits for a worker. If the worker is blocked on a channel endpoint or a lock that the waiting function still holds, or waits for a cancel that the function has not made yet, the join never returns. Plenty rejects such waits at compile time. These habits keep your programs clear of the whole class:

1. Move each endpoint into one worker as an argument: spawn(produce, sender).drop_job()?. A failed start then drops it.
2. Guard each endpoint you keep as the last manager: with spawn(produce, sender).drop_job()?, receiver as inbox:.
3. To wait inside the block, end the guard first. Open it before any statement that can leave the block, and wait after it ends.
4. Wait in a statement of its own. An endpoint moved into the same expression is still held while the wait runs.
5. Call drop_job() on a start you will not retry.
6. Start workers outside a lock block, and lock inside them.
7. Cancel a token on every exit when a worker waits for it: with spawn(serve, stop.share()).drop_job()?, stop.cancel_on_exit():.

The channel shutdown lesson showed habits 1 to 3, and the mutex lesson showed habit 6. Cooperative cancellation shows habit 7. Executor pools follow the same habits, as the future wait lesson shows. This lesson covers several producers and failed starts.

Several producers

Each producer needs its own sender, and the receiver must outlive none of them. One guard after several ? starts is not enough: when a later start fails, ? joins the earlier producers before the guard exists.

def produce(sender: Sender[i64]) -> Result[(), SendError[i64] | OverflowError[i64]]:
    for n in range(5):
        sender.send(n * n)?
    Ok(())

def drain(inbox: &Receiver[i64]) -> Result[i64, OverflowError[i64]]:
    mut total = 0
    while True:
        match inbox.recv():
            case Ok(value):
                total = total + value
            case Err(_):
                break
    Ok(total)

def main() -> Result[(), SpawnError[()] | AllocError | IoError | OverflowError[i64]]:
    sender, receiver = channel[i64](2)?
    second = sender.share()
    with spawn(produce, sender).drop_job()?, spawn(produce, second).drop_job()?, receiver as inbox:
        print(drain(inbox)?)?
    Ok(())

leaving this `with` block joins a task whose worker holds `Sender[i64]` while `receiver` still holds `Receiver[i64]`
`?` leaves the block here

Give the receiver to a consuming worker instead, and start it first. Then guard the sender and hand each producer a share of it:

def produce(sender: Sender[i64]) -> Result[(), SendError[i64] | OverflowError[i64]]:
    for n in range(5):
        sender.send(n * n)?
    Ok(())

def total(receiver: Receiver[i64]) -> Result[i64, OverflowError[i64]]:
    mut sum = 0
    while True:
        match receiver.recv():
            case Ok(value):
                sum = sum + value
            case Err(_):
                break
    Ok(sum)

def main() -> Result[(), SpawnError[()] | AllocError | IoError | OverflowError[i64]]:
    sender, receiver = channel[i64](2)?
    with spawn(total, receiver).drop_job()? as consumer:
        with sender as outbox, spawn(produce, outbox.share()).drop_job()?, spawn(produce, outbox.share()).drop_job()?:
            pass
        print(consumer.join()?)?
    Ok(())

60

Here the sender guard comes first: the producers send too, so only the consumer, joined later, needs the sender gone. The inner block joins both producers, then drops the last sender. The consumer sees disconnection and returns, so consumer.join() after the block cannot hang. If a producer fails to start, ? leaves through the same exits in the same order.

Failed starts keep their endpoints

A job that fails to start returns inside SpawnError[F], with every endpoint it captured. ? keeps that error until the function returns, which is after the block’s joins:

def report(receiver: Receiver[i64]) -> Result[(), IoError | OverflowError[i64]]:
    mut total = 0
    while True:
        match receiver.recv():
            case Ok(value):
                total = total + value
            case Err(_):
                break
    print(total)

def produce(sender: Sender[i64], count: i64) -> Result[(), SendError[i64] | OverflowError[i64]]:
    for n in range(count):
        sender.send(n * n)?
    Ok(())

type Errors = AllocError | SpawnError[()] | SpawnError[OnceClosure[[], Result[(), SendError[i64] | OverflowError[i64]]]]

def main() -> Result[(), Errors]:
    sender, receiver = channel[i64](2)?
    count = 5
    job = def once [sender, count]() -> Result[(), SendError[i64] | OverflowError[i64]]:
        produce(sender, count)
    with spawn(report, receiver).drop_job()?, spawn(job)?:
        pass
    Ok(())

leaving this `with` block joins a task whose worker holds `Receiver[i64]` while the error that `?` propagates still holds `Sender[i64]`
call `drop_job()` on the start

When you will not retry the job, call drop_job() on the start. It drops the job, and its sender, before ? leaves, and the error becomes SpawnError[()]: