Harsh

Why no braces

Here is what a brace language looks and reads like, once you notice it:

I(would, like, to, go) {
    to the market so I(could buy) {
        some groceries
    }
    to the laundromat in order to(get) {
        clothes washed
    }
}

and here is the message it was trying to convey:

I would like to go
    to the market so I could buy
        some groceries
    to the laundromat in order to get
        clothes washed

The second is already in the first — the indentation was there all along; the braces and parentheses only repeat it, in a form the eye has to skip past. That is sometimes hard to see, and because of it some very simple concepts become harder to learn than they are. Harsh weeds out the braces to let Rust shine.

Early in the work, Claude asked the author to justify removing braces from Rust at all. After a long enough exchange it put the answer in one line, and the line stayed:

Braces are for the compiler; indentation is for humans. — Claude

Rust without braces. Rust with pipes, partial application, comprehensions and linear algebra. Rust for functional programming, data science and machine learning.

What Harsh adds

Braces are where Harsh starts, not where it stops. It adds four things Rust has no syntax for — and they are the reason to use it. Each below is Harsh, then the Rust it replaces.

Pipes and partial application. Give a function fewer arguments than it takes, and you get a function waiting for the rest:

let double = 2.0 |> scale
let doubled: Vec<f64> =
    readings <- iter$
             <- map (|&x| double x)
             <- collect$

Generator comprehensions. Say what a collection holds, not how to fill it:

let triples =
    list~ (a, b, c)
        for a in 1..20
        for b in a..20
        for c in b..20 if a * a + b * b == c * c

Linear algebra, as in Julia. Julia's matrix literal, Julia's *, and Julia's X \ y, here fitting a line by least squares:

let x = m~ [1.0 1.0; 1.0 2.0; 1.0 3.0]
let y = v~ [1.0, 2.0, 2.9]
let beta = x <- solve (&y)

Chapters 14, 15 and 16 teach them properly, once closures and iterators — chapter 13 — have given you what they are built from.

Who this is for

You have programmed before — in Python, JavaScript, Elixir, anything — and you have not programmed in Rust. This book teaches you Rust, using Harsh as the notation.

That sentence has a trap in it, so here it is on page one: Harsh makes Rust quieter, not easier. Harsh is a spelling of Rust — indentation for structure, f a b for applying a function, <- for reaching into a value — and it changes nothing about what Rust means. Ownership, borrowing, lifetimes, the type system, the compiler saying no: all of it arrives on schedule, unchanged, and this book is mostly about that. The notation just gets out of the way while you learn it.

When you want practice rather than prose, Harshlings is fifty small exercises of the kind this book explains: a short program with one thing wrong, the compiler pointing at your line, and the next one when you fix it.

If you already know Rust, The Harsh Language Guide, which teaches only the Harsh superset, will onboard you faster.

How to read it

Every example is shown two ways: the Harsh you would write, and what it prints when run. Both are produced by the build from a single source file — the file is transpiled, compiled and run to make the page — so they cannot disagree. When an example is meant to fail, and learning Rust means learning what the compiler refuses and why, you see the Harsh and then the error the compiler reports, pointing at the line you wrote.

Harsh — Harsh is one spelling of Rust, and not the usual one. Rust as you will meet it in crates and in answers on the internet is written differently — the same language, the same meanings, other punctuation. Nothing in this book depends on that other spelling and none of it appears here. When you want the two set side by side, The Harsh Language Guide is where that comparison lives, and every project of yours is in the other spelling too, in its export/ folder, written there by each hrs build.

The chapters follow the order of The Rust Programming Language (the "Rust Book"), because that order has been refined over years to introduce each idea exactly when you need it; the prose and the examples here are original.

Setting up

You need the Rust toolchain and the Harsh tools:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh     # Rust, if you do not have it
cargo install harsh-lang                                               # hrs, hrs-from, hrs-remap, hrs-lsp
hrs new hello && cd hello && hrs run                              # a first project

If the last line prints Hello from Harsh, you are ready. The tools are the crate harsh-lang; for the editor, install Harsh from the VSCode Marketplace, and hrs-lsp — already on your PATH — gives it the layout-aware Enter, Tab and format-on-save the rest of this book assumes you have.

Add rust-analyzer, Rust's own language server, once — rustup component add rust-analyzer, or have VSCode's rust-analyzer extension, whose copy is used — and hrs-lsp gives the editor three more things: hover over a name to see its type and documentation, jump to where it is defined (F12 in VSCode), and completion as you type. hrs-lsp asks rust-analyzer about the Rust your file becomes and points the answer back at your Harsh, and converts the answer into Harsh — a signature reads fn adding (x: i32) (y: i32) -> i32, a path std.slice.Iter — and a definition in your project opens in its .hrs file, one in the standard library in Rust's. Hover and definition follow your last save: after you change a line, save, and they work on it again; completion works on what you are typing. Without rust-analyzer everything else works, and the editor says what to install.

1. Getting started

1.1 A first program

Every program in this book is a complete file that you could save as src/main.hrs in a project made by hrs new and run with hrs run. Here is the smallest one:

fn main$:
    println! "Hello, world!"

Hello, world!

Read the three blocks top to bottom.

• fn main$: declares a function named main. The $ says it takes no parameters; the : at the end of the line says the body follows, indented.
• println! prints a line. The ! marks it as a macro, not a function: a macro is expanded by the compiler into code before compilation proper. You do not need to know how yet; you need to know that ! means "this is a macro" so that you are not surprised by what it can do, such as checking that "{}" has exactly one argument to fill it.
• "Hello, world!" is the argument. A function or macro is applied to its arguments by writing them after it, separated by spaces: println! "…".
• main is where a program starts. Every executable has exactly one.

1.2 What hrs run did

hrs run is two steps that you will do a thousand times, so it is worth seeing them once.

1. Transpile. hrs reads src/main.hrs and writes export/src/main.rs, the same program in Rust's own spelling. export/ is the whole project as Rust: its Cargo.toml, src/ transpiled, and your other files beside them. hrs also writes a source map, which byte of the Rust came from which byte of the Harsh, into .hrs/, a folder of its own.
2. Compile and run. cargo, Rust's build tool, compiles the Rust in export/ and runs the binary. If the compiler complains, hrs uses the source map to turn every line number in the complaint into a line of your .hrs file.

You never read export/src/main.rs unless you want to; it is there when you do. hrs new tells git to ignore export/ and .hrs/, as it ignores a Rust project's target/: both are written again from your .hrs files.

1.3 Arguments

Programs take input. The simplest input is what follows the program's name on the command line, which Rust hands you through the standard library:

use std.env

fn main$:
    let words: Vec<String> = env.args$ <- collect$
    println!
        "{} argument(s), the first being the program itself"
        (words <- len$)

1 argument(s), the first being the program itself

• use std.env brings the env module of the standard library into scope. std is the standard library; . separates the parts of a path.
• env.args$ calls the function args in that module. The $ means call with no arguments, and it is the same $ that said no parameters on fn main$: without it, env.args would name the function without calling it. Hold on to that distinction; it matters in Rust more than in most languages. (() is not this. In Harsh () is a value — the empty tuple, called unit — and you will meet it in chapter 3.)
• <- collect$ is a method call on the value to its left. The arrow is how you reach into a value, and it is the token you will write most. Read <- as then: take the arguments, then collect them. It is written with a space on each side, args <- collect$; written tight it is refused, because x<-y is how a comparison with a negative would be misspelt — that is x < -y, with a space between < and -, as in Rust. And a name always follows the arrow, a field or a method: a tuple's item is reached with a dot, pair.0, never pair <- 0.
• let words: Vec<String> = … declares a variable and states its type: a vector (a growable list) of strings. Rust can usually infer types, but collect can produce many kinds of collection, so here you must say which. When this program is run with no arguments the vector holds exactly one item — the program's own name — which is why it prints 1.

Two things about let that will matter soon: a variable declared with let cannot be changed afterwards unless you say let mut, and the type after the colon is a promise the compiler will hold you to. Both are chapter 3.

1.4 Comments

// A comment runs from `//` to the end of the line.
fn main$:
    // This one explains the next line.
    let answer = 42        // and this one sits after the code
    println! "{}" answer

42

// starts a comment that runs to the end of the line. There are no block comments in this book, though they exist (/* … */). A comment on its own line, above the thing it describes, is the convention; a comment after code on the same line is fine for a short note.

You now have everything needed to read the next chapter, which builds a small program end to end before the language is explained piece by piece.

2. A small program

Before the language is taken apart piece by piece, here is one whole program: a guessing game. The computer holds a number; you type guesses; it says higher or lower until you hit it. It is fourteen lines, and it uses input, output, conversion, comparison, a loop, and Rust's way of dealing with things that can fail. Every one of those gets its own chapter later; here you meet them in the wild.

2.1 The whole thing

Reading input from the keyboard is where most languages' toy programs cheat, so this one does not. Run with the guesses 50, 25, 37:

use std.io
use std.cmp.Ordering

fn main$:
    let secret = 37

    loop:
        let mut line = String.new$
        io.stdin$ <- read_line (&mut line) <- expect "read failed"

        let guess: u32 =
            match line <- trim$ <- parse$\
                Ok n => n
                Err _ => continue

        match guess <- cmp (&secret)\
            Ordering.Less => println! "higher"
            Ordering.Greater => println! "lower"
            Ordering.Equal => do:
                println! "you have it: {}" guess
                break

lower
higher
you have it: 37

Now the same program, walked through.

2.2 Bringing a name into scope

use std.io

The standard library is large and nothing in it is in scope by default except a small prelude (println!, Vec, String, Option, and a few others). use brings a path into scope; after this line io means std.io and io.stdin$ is a valid call. You could write std.io.stdin$ everywhere instead — use is a convenience, not a requirement.

2.3 The secret

let secret = 37

No type is written and none is needed: 37 is an integer literal, and Rust infers the type i32 — a 32-bit signed integer, the default for integer literals. Chapter 3 lists the others.

Two things about this let will feel strange coming from most languages. First, secret is immutable: writing secret = 12 later is a compile error. Rust makes every variable immutable unless you ask, with let mut, and the reason is the whole of chapter 4. Second, the name is in scope from this line to the end of the enclosing block and no further, which for main means the end of the program.

2.4 Loop, read, trim, parse

loop:
    let mut line = String.new$
    io.stdin$ <- read_line (&mut line) <- expect "read failed"

loop: opens a block that repeats forever; only break leaves it. Its body is the indented lines beneath.

String.new$ calls the associated function new on the type String. It makes an empty string that can grow. The mut says this one will change: read_line is about to append to it.

The next line is a method chain, and it is worth reading slowly because you will write chains like it constantly.

• io.stdin$ gets a handle on standard input.
• <- read_line (&mut line) calls read_line on that handle, passing &mut line — a mutable reference to the string, which is how a function is allowed to change a value that belongs to you. The &mut is not decoration; without it the call does not compile. That is chapter 4 again.
• read_line does not return the line. It returns a Result — a value that is either Ok(bytes_read) or Err(some_error) — because reading can fail. <- expect "read failed" says: if it is Ok, give me what is inside; if it is Err, stop the program and print this message. It is the bluntest way to handle a Result, fine for a toy, and chapter 9 replaces it.

    let guess: u32 = match line <- trim$ <- parse$:
        Ok n => n
        Err _ => continue

The line the user typed ends in a newline, so <- trim$ removes it. <- parse$ turns the text into a number — but which kind of number? The annotation let guess: u32 tells it: an unsigned 32-bit integer. Rust reads the type you asked for and works backwards to what parse must produce. Parsing text can fail too (type hello), so parse also returns a Result, and this time the program handles both cases with match:

• Ok n => n: the parse worked; n is the number; the whole match is worth n, and that is what guess becomes.
• Err _ => continue: it failed; _ means "I do not care what the error was"; continue jumps to the next iteration of the loop, asking again. continue never produces a value, so Rust is content that this arm does not yield a u32.

match is Rust's central control structure: it takes a value, lists the shapes it can have, and refuses to compile unless every shape is covered. Result has exactly two shapes and both are here.

2.5 Compare and decide

    match guess <- cmp (&secret)\
        Ordering.Less => println! "higher"
        Ordering.Greater => println! "lower"
        Ordering.Equal => do:
            println! "you have it: {}" guess
            break

cmp compares two values and returns an Ordering, which is an enum — a type whose value is one of a fixed set of named alternatives: Less, Greater, Equal. The use std.cmp.Ordering at the top is what lets us write Ordering.Less instead of std.cmp.Ordering.Less.

The argument is &secret, a reference: cmp wants to look at the other number, not take it. You will see & on most arguments in Rust, and chapter 4 explains when you need it and when you do not.

Three arms, one per alternative, and the compiler checks that there are three. The Equal arm has two statements, so it is a block, opened by do:, indented beneath. break ends the loop, and since there is nothing after the loop in main, the program ends.

2.6 How a page of Harsh is laid out

You have now read a whole program, so this is the moment to say what the shape of it means. There is not much to say, and all of it is one idea: where a line starts is what it belongs to.

// The same function three times: one block, three spellings.

fn indented (t: bool) -> i32:
    if t:
        1
    else:
        2

fn inline (t: bool) -> i32:
    if t: 1 else: 2

fn braced (t: bool) -> i32:
    if t { 1 } else { 2 }

fn main$:
    // `do:` opens a block with nothing attached: a scope of its own
    let squared = do:
        let u = 3
        u * u

    // parameters: one group each, or bare when there is only one
    println!
        "{} {} {} {}"
        (indented true)
        (inline false)
        (braced true)
        squared

1 2 1 9

Harsh — A block opens at a : that ends its line, and its body is the lines indented beneath it; the body ends where the indentation does. That is the one form you will write nearly everywhere. The same block may be written inline, with the body after the colon on the same line, when it is one expression and fits; and it may be written in braces, on one line only, when several statements have to share a line — { let u = 3; u * u } — which is also the spelling you reach for when pasting a line written the other way. Passed as an argument, such a block is isolated like any argument, f ({ let u = 3; u * u }): braces right after a name, f { … }, are refused, since Rust would read them as a struct literal. All three produce exactly the same program. A block that belongs to nothing — a scope opened for its own sake — is do:. Two rules follow from the idea. A line ending is the end of a statement, so you never write ; at all: a block whose last value is to be discarded ends with a line (), which says this block is worth nothing (chapter 3 shows what that does). And a line indented deeper than the one above it, without a : to open a block, continues it — which is how a long line is broken.

There is one more shape on that page, and it is the one that looks least like other languages:

fn greet name: &str -> String:
    format! "hello, {name}"

fn add (a: i32) (b: i32) -> i32:
    a + b

fn nothing$ -> i32:
    42

fn main$:
    let s = greet "harsh"            // one argument: the name follows the function
    let n = add 2 3                  // two: juxtaposed, no commas, no parens
    let m = add (n * 2) (nothing$)   // an expression is one argument once it is in parens
    let z = nothing$                 // applied to nothing: `$`, never `()`
    let u = ()                       // `()` is a value -- the unit -- and only ever that

    let v = vec! 1 2 3           // a macro applies the same way
    let len = v <- len$              // `<-` reaches into a value: a method, a field
    let text = String.from "abc"     // `.` walks a path: a module, a type, an item

    // an application binds tighter than `<-`: the arrow takes the result
    let big = greet "harsh" <- to_uppercase$        // greet first, then the method on it
    let total = String.from "abc" <- len$ + len     // the same, then the operator on that
    let inner = greet (&(text <- to_uppercase$))    // the arrow *inside* an argument: isolated; `&` is an operator, so its operand is too

    println! "{s} {n} {m} {z} {u:?} {len} {text} {big} {total} {inner}"

hello, harsh 5 52 42 () 3 abc HELLO, HARSH 6 hello, ABC

Harsh — A function is applied by writing its arguments after it, separated by spaces: add 2 3. Parentheses around an argument mean this is one argument — add (n * 2) (nothing$) — and never these are the arguments; an argument that is a single token needs none. Applying a function to nothing is nothing$, because () is a value, the unit, and only ever that. The same rule declares a function: fn add (a: i32) (b: i32) is one group per parameter, and a lone parameter may drop its parentheses, fn greet name: &str. A block's opener says how its entries end, and there are only three kinds. A header that ends itself — struct Point, impl Point, mod geometry, extern "C" — needs no mark at all, since nothing but a name can follow it and what comes deeper can only be the body. A \ opens a comma-separated list — a literal's fields, or a match's arms. A : or do: opens statements. A grouping whose grammar belongs to someone else — a macro's own language — is not a block at all: it goes in the macro's braces, as Rust, and the Harsh inside is marked @: … :@ (chapter 23).

When an application meets operators, chains and pipes, it binds before any of them: add 1 2 * 10 adds, then multiplies. The appendix Precedence sets out every level. An index written tight, arr[1], is part of its atom, so f arr[1] passes the element — the same way t.0 is part of t; brackets never apply, and an array passed as an argument is isolated, f ([1, 2, 3]). Two arrows share the work of reaching into things: <- reaches into a value — a field, a method, v <- len$ — and . walks a path — a module, a type, an item, String.from. A macro applies like a function, with its ! glued to its name: vec! [1, 2, 3], println! "{s}". And when an application and an arrow meet, the application binds tighter: in greet "harsh" <- to_uppercase$ the function is applied first and the arrow takes its result, and the next arrow, or an operator, ends the arguments. The parentheses you will be tempted to write, (greet "harsh") <- to_uppercase$, are not wrong; they are not needed. Parentheses are needed the other way round — when the arrow belongs inside an argument, greet (&(text <- to_uppercase$)).

2.7 One argument, one atom

Every pair of parentheses in this chapter that was not a tuple has had the same job, and it is worth seeing the rule whole, because it explains each case at once instead of one at a time.

Harsh separates arguments with spaces: add 2 3 has two. So an argument that is itself made of several tokens — n * 2, -1, &line, s <- len$ — would be read as several arguments, and must be isolated, wrapped in parentheses that say this is one argument. An argument of one token needs nothing: that token is an atom. Atoms are names and literals, and a few shapes that stay one piece because they are written tight: a path Route.Home, a tuple's item pair.0, an index v[0], a call with no arguments now$, a turbofish parse.<i32>$, a range of atoms 0..n, and anything already isolated (n * 2).

fn add (a: i32) (b: i32) -> i32: a + b

fn main$:
    let n = 4
    let pair = (1, 2)
    let v = vec! 10 20 30
    println! "{}" (add (n * 2) (-1))
    println! "{}" (add pair.0 v[1])
    println! "{}" (add (v <- len$ as i32) n)
    let total: i32 = (0..n) <- sum$
    println! "{total}"

Each isolated argument there has several tokens: an operator, a negative number, a method step. Each bare one is an atom. The reason is always the same, so a reader never has to remember a list.

Where nothing needs separating, nothing is isolated. The parentheses exist only to tell an argument from its neighbours, so where there are no neighbours they are not needed. A function with one parameter writes it bare, however many tokens it has: fn greet name: &str, fn bump &mut n: &mut i32. After a constructor — a struct or enum variant the program declares (a record variant's fields are not constructors), or the prelude's Some, Ok, Err — a single argument is bare too: Some &x, Some mut line, Ok ref v. A constructor can only take its argument; it is never an operand of &. After any other name, f & x is bit-and, so a reference passed to a function is isolated: f (&x).

Two operators keep their parentheses everywhere. A leading - and a range whose ends are not atoms: f (-1), Celsius (-40..=0), f (a + 1..n) — because f -1 is subtraction and f a + 1..n would split at the +.

Commas separate too. Inside a tuple, items are separated by commas, and a literal brings commas of its own: (1, (Point\ x = 1, y = 2)) — isolated, or its fields would read as the tuple's items.

A tuple index applies to one atom. pair.0 indexes pair. To index what a call returns, isolate the call: let first = (f src).0 — in f src.0, the .0 is src's. That indexed group is itself several pieces, so passed as an argument it is isolated in turn: show ((f src).0). Written show (f src).0, the index would apply to show's result; Harsh refuses it and names the isolated form. An index in brackets follows the same rule: (f src)[i] indexes what f src returns.

Rust needs none of this, because it separates arguments with commas. Harsh separates them with spaces, so where spaces separate, an argument of several tokens is isolated, and nowhere else.

2.8 What you have met

Immutability by default and mut to opt out; & and &mut on arguments; Result for operations that can fail and match to take it apart; loop, break, continue; enums; type annotations that tell parse what to produce. Each has a chapter. The next one starts with the smallest pieces: variables, types, functions, and control flow.

3. Common concepts

Variables, types, functions, control flow: every language has them, and Rust's versions each have one thing that is not like the others. This chapter is those things.

3.1 Variables and mutability

A variable is immutable unless declared otherwise. This is the first Rust decision that surprises people, so here is the compiler enforcing it:

fn main$:
    let x = 5
    println! "x is {}" x
    x = 6
    println! "x is {}" x

error[E0384]: cannot assign twice to immutable variable `x`
  --> immutable.hrs:4:5
   |
 2 |     let x = 5
   |         - first assignment to `x`
 4 |     x = 6
   |     ^^^^^ cannot assign twice to immutable variable
   = help: consider making this binding mutable (hrs 2:9)

Read the error the way Rust means it. It is not "you cannot change variables"; it is "you did not say this one would change". The fix is one word:

fn main$:
    let mut x = 5
    println! "x is {}" x
    x = 6
    println! "x is {}" x

x is 5
x is 6

Why the default? Because most values in most programs are never reassigned, and a reader who sees let without mut knows — without reading further — that the value is what it was. When a value does change, mut at the declaration is the announcement. The habit pays for itself the first time you track down where something was modified and the answer is "only where it says mut".

Shadowing

You may declare a new variable with the name of an old one. The new one shadows the old for the rest of its scope:

fn main$:
    let x = 5
    let x = x + 1

    do:
        let x = x * 2
        println! "inner x is {}" x

    println! "outer x is {}" x

    // Shadowing may change the type; `mut` may not.
    let spaces = "   "
    let spaces = spaces <- len$
    println! "{} spaces" spaces

inner x is 12
outer x is 6
3 spaces

Shadowing is not mutation. Each let x is a fresh variable; the earlier one is merely hidden. That is why the inner block's x does not leak out, and why the last example is allowed to turn a string into a number under the same name — a mut variable must keep its type, but a new variable can be anything. Use shadowing when a value goes through stages under one natural name (raw text, then parsed) and mut when one value genuinely changes.

do: in that example opens a bare block — a scope with no if or loop attached. do is a keyword Rust reserved and never used, so it was free to mean this.

3.2 Scalar types

Rust is statically typed: every value has a type known at compile time. Usually the compiler infers it and you write nothing; when it cannot, or when you want a specific size, you annotate.

fn main$:
    let a: i32 = -7            // signed 32-bit, the default integer
    let b: u8 = 255            // unsigned 8-bit: 0 to 255
    let c: i64 = 9_000_000_000 // underscores are ignored, for reading
    let d = 0xff               // hex; also 0o77 octal, 0b1010 binary
    let e = 2.5                // f64, the default float
    let f: f32 = 1.0
    let t = true
    let ch = 'Z'               // a char is one Unicode scalar, in single quotes
    let heart = '❤'

    println! "{} {} {} {} {} {} {} {} {}" a b c d e f t ch heart
    println! "{}" (a + 10 * 2 - 3 / 2 % 2)
    println! "{}" (7 / 2)      // integer division truncates
    println! "{}" (7.0 / 2.0)

-7 255 9000000000 255 2.5 1 true Z ❤
12
3
3.5

Integers come in signed (i8, i16, i32, i64, i128) and unsigned (u8 … u128) widths, plus isize/usize sized to the machine — usize is what indexes and lengths use. i32 is the default when nothing constrains a literal. Floats are f64 (default) and f32. Division of integers truncates toward zero; there is no automatic promotion to float, and 7 / 2.0 is a type error, not 3.5.

What happens at the edges

Adding one to a u8 holding 255 cannot fit. In a debug build Rust panics — stops the program with a message — rather than silently wrapping, which is what most languages do. In a release build it wraps. When you mean wrapping, say so; when you want to know, ask:

fn main$:
    let big: u8 = 255
    let bigger = big <- wrapping_add 1
    let checked = big <- checked_add 1
    println! "{} {:?}" bigger checked

0 None

checked_add returns an Option: Some(value) if it fit, None if it did not — the {:?} in the format string is debug formatting, which is how you print an Option. Option is Rust's answer to null, and chapter 6 is about it.

3.3 Compound types

fn main$:
    // A tuple holds a fixed number of values of any types.
    let pair: (i32, &str) = (1, "one")
    let (n, name) = pair                 // destructure into two variables
    println! "{} is {}" n name
    println! "{} {}" pair.0 pair.1       // or index by position

    // An array holds a fixed number of values of one type, on the stack.
    let days = ["mon", "tue", "wed"]
    let zeros = [0; 4]                   // four zeros
    println! "{} {} {}" (days[0]) (days <- len$) (zeros <- len$)

1 is one
1 one
mon 3 4

A tuple is fixed-length and heterogeneous; you take it apart by destructuring or by .0, .1. An array is fixed-length and homogeneous, indexed with days[0] — and note the parentheses around (days[0]) when it is an argument: Harsh applies functions by juxtaposition, so an index expression is isolated to keep f a [0] from being read as f applied to a and to an array. An array, and its length is part of its type: [i32; 4] is a different type from [i32; 5]. Indexing past the end is checked at runtime and panics — it never reads memory it should not. For a list that grows you want Vec, in chapter 8.

3.4 Functions

fn greet name: &str:
    println! "hello, {}" name

fn add (a: i32) (b: i32) -> i32:
    a + b

fn square x: i32 -> i32:
    let y = x * x
    y

fn main$:
    greet "world"
    println! "{}" (add 2 3)
    println! "{}" (square 9)

hello, world
5
81

Three things to notice.

• Parameters are typed, always. Rust does not infer parameter types; the signature is the contract, and the compiler checks every call against it. Each parameter is written in its own group, (a: i32) (b: i32); a single parameter may drop its parentheses, name: &str.
• The return type follows ->. No annotation means the function returns (), the unit type — the empty tuple, the value that carries no information — so greet returns unit. This is the () chapter 1 promised: a value, never a call. Calling with no arguments is $.
• The last expression is the return value. square computes y and then has y as its final line, with no return. That last line is an expression, and a function's body is worth its final expression. return exists for leaving early; it is not needed at the end.

Statements and expressions

That last point has a sharp edge. A statement does something and produces no value; an expression produces a value. let y = x * x is a statement. y alone is an expression. A block's value is its final expression. To make a block worth nothing instead — (), the unit value — its last line is () itself: the line says, where the value goes, that there is none.

Here is what such a line does to a function that meant to return a value:

fn plus_one x: i32 -> i32:
    x + 1
    ()

fn main$:
    println! "{}" (plus_one 5)

error[E0308]: mismatched types
  --> statement_value.hrs:1:23
   |
 1 | fn plus_one x: i32 -> i32:
   |    -------- implicitly returns `()` as its body has no tail or `return` expression
   |                       ^^^ expected `i32`, found `()`
   = help: remove this semicolon to return this value (hrs 2:10)

The error is Rust's most-quoted: the signature promises an i32, and the body is worth (). Remove the () and it is correct — rustc's own hint speaks of a ;, which is how the Rust ends that statement. You will meet this error on purpose exactly once, and then you will know what it means forever.

And here is the () on purpose. A for body is worth (), so when its last line is a call whose value you do not want — insert answers with a bool, was it new? — the () beneath it says so:

use std.collections.HashSet

fn main$:
    let mut seen = HashSet.new$
    for word in ["a", "b", "a"]:
        seen <- insert word
        ()
    println! "{} distinct" (seen <- len$)

2 distinct

3.5 Control flow

if

fn main$:
    let n = 7

    if n % 2 == 0:
        println! "even"
    else:
        println! "odd"
    // `if` is an expression: it produces a value, and both arms must agree on its type.

    let kind = if n > 5: "big" else: "small"
    println! "{}" kind

    let sign =
        if n > 0: 1
        else
            if n < 0: -1
            else: 0

    println! "{}" sign

odd
big
1

The condition must be a bool — if n: with an integer n is a type error, not a truthiness test. And if is an expression, so it can sit on the right of a let; when it does, every arm must produce the same type, because kind has to be some one type:

fn main$:
    let n = 7
    let kind = if n > 5: "big" else: 0
    println! "{}" kind

error[E0308]: `if` and `else` have incompatible types
  --> if_mismatch.hrs:3:38
   |
 3 |     let kind = if n > 5: "big" else: 0
   |                ----------------------- `if` and `else` have incompatible types
   |                          ----- expected because of this
   |                                      ^ expected `&str`, found integer

Notice the shape of the multi-line if in the previous example: the if begins its own line after let sign =, its else stands under it, and the if inside the else indents past the else. That is the rule everywhere a construct opens in the middle of a line: a block's lines are indented past the column of the construct that opened it, not merely past the statement, and when that would push the block too far right, = ends its line instead and the opener starts its own. Every control-flow construct also has the inline shape chapter 2 showed for blocks:

fn main$:
    let n = 7

    // a construct whose body fits on the line: the colon is followed by the body
    let parity = if n % 2 == 0: "even" else: "odd"
    let size =
        match n\
            0 => "none"
            1..=5 => "few"
            _ => "many"
    let zero = match n\ 0 => true, _ => false

    // `else` answers the `if` above it, and may sit under the `if`...
    let kind =
        if n > 100:
            "huge"
        else if n > 10:
            "big"
        else:
            "small"

    // ...or under the line that holds the `if`, when it opened mid-line
    let label = if n > 10:
        "big"
    else:
        "small"

    let mut count = 0
    while count < 3: count += 1
    for i in 0..2: println! "i = {i}"

    println! "{parity} {size} {zero} {kind} {label} {count}"

i = 0
i = 1
odd many false small small 3

Harsh — Inline, the body follows the colon on the same line, and the arms of a match written on one line are separated by commas — the only place a comma separates arms, since on their own lines the line ending does that. An else answers the nearest if above it, and it may sit at the column of any line of that if: under the if itself, or under the let that holds it when the if opened on the let's line. A while or for whose body is one statement takes the inline form as readily as an if does.

Loops

fn main$:
    // `loop` repeats until `break`, and `break` can carry the loop's value.
    let mut counter = 0

    let result =
        loop:
            counter += 1

            if counter == 10:
                break counter * 2

    println! "{}" result

    // `while` repeats while a condition holds.
    let mut n = 3

    while n != 0:
        println! "{}" n
        n -= 1
    // `for` walks anything iterable: an array, a range.

    let a = [10, 20, 30]

    for x in a:
        println! "{}" x

    for i in (1..4) <- rev$:
        println! "{}" i

20
3
2
1
10
20
30
3
2
1

loop with break value is how you compute something by repetition and hand it out — the loop is an expression too. while is what you expect. for is the loop you will write most: it walks an iterator, never an index, so it cannot run off the end of the array, and 1..4 is a range (1, 2, 3 — the end is excluded; 1..=4 would include it). <- rev$ reverses it; ranges and arrays are both things you can iterate, which is chapter 13's topic.

3.6 What you have

Immutable by default, mut and shadowing; the scalar and compound types and their fixed sizes; typed parameters, the final expression as the return value, and the semicolon that discards it; if and the loops as expressions. Next: the one idea that is Rust's alone, and the reason this book exists — ownership.

4. Ownership

This is the chapter the book exists for. Ownership is the idea that is Rust's alone: the reason it needs no garbage collector and no manual free, the reason the compiler will refuse programs that every other language accepts, and the reason those programs, once accepted, do not have the bugs the others do. Harsh changes nothing here. There is no notation to learn in this chapter beyond what you have, and every example is a conversation with the compiler about who is responsible for a value. Read the errors as carefully as the programs; they are the lesson.

4.1 What ownership is

The stack, the heap, and the question

A running program keeps values in two places. The stack holds values whose size is known at compile time — an i32, a bool, a fixed array — and it is fast because it is simple: push on the way in, pop on the way out, in strict order. The heap holds values whose size is not known in advance or may change — the text of a string typed by the user, a list that grows — and it is slower because someone has to find a free region, record where it is, and later give it back.

That "give it back" is the whole problem. Give the memory back too early and something still using it reads garbage; give it back twice and the allocator's bookkeeping is corrupted; never give it back and the program leaks. Garbage-collected languages solve this by never letting you free anything and periodically finding what is unreachable. C solves it by trusting you. Rust solves it with a rule the compiler can check.

The rules

• Every value has exactly one owner: the variable that holds it.
• When the owner goes out of scope, the value is dropped — its memory is freed, immediately and deterministically.
• There is only ever one owner at a time, so a value is freed exactly once.

Scope is the ordinary thing: a variable is valid from where it is declared until the end of the block that declares it.

fn main$:
    do:
        let s = "hello"          // s is valid from here
        println! "{}" s          // and usable until the block ends
    // the block is over: s is gone, and there is nothing to free

    let t = String.from "hello"  // a String owns memory on the heap
    println! "{}" t
    // main ends here: t goes out of scope and its memory is freed

hello
hello

s holds a string literal, text baked into the program, which lives on the stack and costs nothing to drop. t holds a String, which owns a buffer on the heap. String.from allocates it; when t goes out of scope at the end of main, Rust frees it. You wrote no free, and none was needed, because the compiler knows exactly where t's scope ends and puts the call there itself. That is ownership from the value's point of view: an owner, and a drop at the end of the owner's scope.

String is the type you reach for when text is not fixed at compile time — it can grow:

fn main$:
    let mut s = String.from "hello"
    s <- push_str ", world"       // append to the heap buffer
    s <- push '!'                 // append one character
    println! "{}" s
    println! "{} bytes" (s <- len$)

hello, world!
13 bytes

push_str and push append to the buffer, reallocating if it is full. s <- len$ is isolated in parentheses because it is an argument to println! and is not a single atom — the same rule chapter 3 gave for an index expression.

Move

Now the rule bites. What happens when a String is assigned to a second variable?

fn main$:
    let s1 = String.from "hello"
    let s2 = s1                   // s1 is moved into s2
    println! "{}, world" s1       // s1 is no longer valid

error[E0382]: borrow of moved value: `s1`
  --> move.hrs:4:26
   |
 2 |     let s1 = String.from "hello"
   |         -- move occurs because `s1` has type `String`, which does not implement the `Copy` trait
 3 |     let s2 = s1                   // s1 is moved into s2
   |              -- value moved here
 4 |     println! "{}, world" s1       // s1 is no longer valid
   |                          ^^ value borrowed here after move
   = help: consider cloning the value if the performance cost is acceptable (hrs 3:16)

The line let s2 = s1 did not copy the string. A String is, on the stack, three words — a pointer to the heap buffer, a length, and a capacity — and assignment copies those three words, so that s1 and s2 would both point at the same buffer. If both were owners, both would free it when they went out of scope, and that is the double-free the rules exist to prevent. So Rust does the only safe thing: it declares that the assignment moved the value, that s2 is now the owner, and that s1 is no longer valid. Using s1 afterwards is the error you see — and read it, because it tells you where the move happened, why (String does not implement Copy), and what to do if you meant to keep both.

This is the moment people come to Rust from anywhere else and feel the floor shift: assignment is not a copy. It is a transfer of responsibility. Once you have it, most of the chapter follows from it.

Clone

When you actually want two strings, say so:

fn main$:
    let s1 = String.from "hello"
    let s2 = s1 <- clone$       // a second, independent copy of the heap data
    println! "s1 = {}, s2 = {}" s1 s2

s1 = hello, s2 = hello

clone allocates a second buffer and copies the bytes into it; now there are two owners of two values, and each will be freed once. It is a method call, so it is visible in the code, which is the point — anything that copies heap memory is expensive enough that Rust wants you to write it down. When you see <- clone$ you know something possibly costly is happening; when you do not, you know nothing is.

Copy

Integers did not behave this way in chapter 3, and they still do not:

fn main$:
    let x = 5
    let y = x                     // an integer is copied, not moved
    println! "x = {}, y = {}" x y

x = 5, y = 5

An i32 is a value that lives entirely on the stack, has no buffer to free, and is as cheap to copy as to move — the two operations are the same four bytes. Types like that implement a trait called Copy, and for a Copy type assignment copies and the original stays valid. All the scalars are Copy, and so are tuples and arrays made only of Copy types. Nothing that owns heap memory is, and a type cannot be Copy if dropping it does work. The error above named this exactly: String does not implement Copy, so assignment moved it.

Ownership and functions

Passing a value to a function is the same as assigning it to the parameter, and follows the same rule:

fn takes_ownership some_string: String:
    println! "{}" some_string
    // some_string goes out of scope here and is freed

fn makes_copy some_integer: i32:
    println! "{}" some_integer

fn main$:
    let s = String.from "hello"
    takes_ownership s             // s moves into the function…

    let x = 5
    makes_copy x                  // x is copied into the function…
    println! "{}" x               // …so x is still here
    println! "{}" s               // …but s is not

error[E0382]: borrow of moved value: `s`
  --> fn_move.hrs:15:19
   |
 9 |     let s = String.from "hello"
   |         - move occurs because `s` has type `String`, which does not implement the `Copy` trait
10 |     takes_ownership s             // s moves into the function…
   |                     - value moved here
15 |     println! "{}" s               // …but s is not
   |                   ^ value borrowed here after move
   = note: consider changing this parameter type in function `takes_ownership` to borrow instead if owning the value isn't necessary (hrs 1:33)
   = help: consider cloning the value if the performance cost is acceptable (hrs 10:22)

s moved into takes_ownership, was printed, and was dropped when that function returned — so by the time main tries to print it, it is gone, and the compiler says so. x was copied into makes_copy, so main still has it. Notice the compiler's note: it has already worked out that takes_ownership did not need to own the string, and suggests borrowing instead. That suggestion is the next section; for now, see that the rule is uniform. There is no special case for function calls. A value goes where its owner goes.

Returning a value moves it too — out of the function and into whatever receives it:

fn gives_ownership$ -> String:
    let some_string = String.from "yours"
    some_string                   // moved out to the caller

fn takes_and_gives_back a_string: String -> String:
    a_string                      // moved in, moved back out

fn main$:
    let s1 = gives_ownership$
    let s2 = String.from "hello"
    let s3 = takes_and_gives_back s2
    println! "{} {}" s1 s3

yours hello

gives_ownership creates a String and hands it to s1. s2 moves into takes_and_gives_back and comes out again as s3; s2 is gone, and the string it named now belongs to s3. The value was never copied, only passed along. Nothing was freed until main ends, when s1 and s3 go out of scope and each drops what it owns.

This is correct and it is also tedious. A function that only wants to look at a String — measure it, say — has to give it back or the caller loses it, and giving it back means returning it alongside the real answer:

fn calculate_length s: String -> (String, usize):
    let length = s <- len$
    (s, length)                   // hand the String back along with the answer

fn main$:
    let s1 = String.from "hello"
    let (s2, len) = calculate_length s1
    println! "the length of '{}' is {}" s2 len

the length of 'hello' is 5

It works. It is also nobody's idea of a good time, and Rust has a better one.

4.2 References and borrowing

A reference lets a function use a value without owning it. Write &s1 and you get a reference to s1; the function receives &String — "a reference to a String" — and when its parameter goes out of scope nothing is freed, because the parameter never owned anything:

fn calculate_length s: &String -> usize:
    s <- len$
    // s goes out of scope, but it never owned the String, so nothing is freed

fn main$:
    let s1 = String.from "hello"
    let len = calculate_length (&s1)
    println! "the length of '{}' is {}" s1 len

the length of 'hello' is 5

Creating a reference is called borrowing, and the word is chosen with care: you have the value for a while, you give it back, and the owner was the owner throughout. s1 is still valid after the call because it never left. The & appears once in the signature, s: &String, and once at the call, (&s1) — where it is isolated in parentheses because &s1 contains an operator and an argument must be one atom. Chapter 3's index rule again: if it has an operator in it, wrap it.

Mutable references

A borrowed value cannot be changed through the borrow:

fn change some_string: &String:
    some_string <- push_str ", world"

fn main$:
    let s = String.from "hello"
    change (&s)

error[E0596]: cannot borrow `*some_string` as mutable, as it is behind a `&` reference
  --> borrow_mut_err.hrs:2:5
   |
 2 |     some_string <- push_str ", world"
   |     ^^^^^^^^^^^ `some_string` is a `&` reference, so it cannot be borrowed as mutable
   = help: consider changing this to be a mutable reference (hrs 1:24)

A plain & reference is a promise to only read. To change something through a reference you need a mutable reference, &mut, and the value you borrow from has to be mut in the first place:

fn change some_string: &mut String:
    some_string <- push_str ", world"

fn main$:
    let mut s = String.from "hello"
    change (&mut s)
    println! "{}" s

hello, world

Three muts: the variable is declared mutable, the borrow is taken mutably, and the parameter's type says so. That is not redundancy; each one is a statement at a different place — the declaration, the call, the signature — and each is what its reader needs to know.

The one rule about mutable references

Here is the restriction that makes borrowing safe, and it is the compiler's most-argued-with error:

fn main$:
    let mut s = String.from "hello"
    let r1 = &mut s
    let r2 = &mut s
    println! "{}, {}" r1 r2

error[E0499]: cannot borrow `s` as mutable more than once at a time
  --> two_mut.hrs:4:14
   |
 3 |     let r1 = &mut s
   |              ------ first mutable borrow occurs here
 4 |     let r2 = &mut s
   |              ^^^^^^ second mutable borrow occurs here
 5 |     println! "{}, {}" r1 r2
   |                       -- first borrow later used here

At any one time, a value may have either one mutable reference or any number of immutable ones — never both, never two mutable. The reason is data races: two paths that can write the same memory, or one that writes while another reads, with nothing to order them. In a garbage-collected language that is a bug you find at runtime, sometimes. Rust makes it a compile error, always, by refusing to let two mutable references to one value exist at the same time.

The scope of a reference is what matters, so the borrows only conflict while both are alive. Give the first one a block of its own and the second is fine:

fn main$:
    let mut s = String.from "hello"

    do:
        let r1 = &mut s
        r1 <- push_str " there"
    // r1 is gone, so a new mutable borrow is fine

    let r2 = &mut s
    r2 <- push_str "!"
    println! "{}" s

hello there!

Mixing is refused for the same reason. Readers were promised nothing would change under them; a writer breaks that promise:

fn main$:
    let mut s = String.from "hello"
    let r1 = &s
    let r2 = &s
    let r3 = &mut s
    println! "{}, {}, and {}" r1 r2 r3

error[E0502]: cannot borrow `s` as mutable because it is also borrowed as immutable
  --> mixed_borrow.hrs:5:14
   |
 3 |     let r1 = &s
   |              -- immutable borrow occurs here
 5 |     let r3 = &mut s
   |              ^^^^^^ mutable borrow occurs here
 6 |     println! "{}, {}, and {}" r1 r2 r3
   |                               -- immutable borrow later used here

A reference's scope, though, is not its enclosing block. It runs from where the reference is created to the last place it is used. So this compiles, because r1 and r2 are not used after the first println!, and the compiler can see that:

fn main$:
    let mut s = String.from "hello"
    let r1 = &s
    let r2 = &s
    println! "{} and {}" r1 r2

    // r1 and r2 are not used after this point, so their borrow is over
    let r3 = &mut s
    r3 <- push_str "!"
    println! "{}" r3

hello and hello
hello!

The compiler tracks where each borrow ends by use, not by block, and this is what makes the rule livable rather than merely correct. When you get one of these errors, look at the last use of the earlier borrow, because that is where its scope ends, and often the fix is to reorder two lines so the borrows do not overlap.

Dangling references

In languages with pointers it is possible to hand out a pointer to memory that is then freed — a dangling pointer, the classic source of crashes and worse. Rust guarantees this cannot happen: a reference is never allowed to outlive the value it points to. Try to return a reference to a local and see:

fn dangle$ -> &String:
    let s = String.from "hello"
    &s                            // a reference to s…

fn main$:
    let reference_to_nothing = dangle$
    // …but s was freed when dangle returned

error[E0106]: missing lifetime specifier
  --> dangle.hrs:1:15
   |
 1 | fn dangle$ -> &String:
   |               ^ expected named lifetime parameter
   = help: this function's return type contains a borrowed value, but there is no value for it to be borrowed from
   = help: consider using the `'static` lifetime, but this is uncommon unless you're returning a borrowed value from a `const` or a `static` (hrs 1:16)
   = help: instead, you are more likely to want to return an owned value (hrs 1:15)

s is created inside dangle, so it is dropped when dangle returns; a reference to it would point at freed memory. The compiler's message is about lifetimes, a word chapter 10 explains in full — for now, read the first help: the return type is a borrowed value and there is nothing in this function it could be borrowed from. The fix is to return the String itself, moving it out to the caller:

fn no_dangle$ -> String:
    let s = String.from "hello"
    s                             // move the String out instead

fn main$:
    let s = no_dangle$
    println! "{}" s

hello

Ownership moves out; nothing dangles; the caller owns the string and will drop it.

To sum up this section in two lines: at any time, either one mutable reference or any number of immutable ones; and a reference must always point to a valid value. Everything the compiler said above is one of those two rules, applied.

4.3 Slices

A slice is a reference to a contiguous part of a collection rather than the whole thing. It exists to solve a problem that references alone leave open, so here is the problem first. Say we want the first word of a string. Without slices, the natural answer is an index — the position where the first word ends:

fn first_word s: &String -> usize:
    let bytes = s <- as_bytes$

    for (i, &item) in bytes <- iter$ <- enumerate$:
        if item == b' ':
            return i

    s <- len$

fn main$:
    let mut s = String.from "hello world"
    let word = first_word (&s)    // word = 5
    s <- clear$                 // s is now "", but word is still 5
    println! "{}" word            // 5 is the answer to a question nobody can ask now

5

This compiles and it prints 5, and it is wrong in a way the compiler cannot see: word is a usize, a plain number with no connection to s, so when s is cleared, word goes on holding a meaning that no longer means anything. The bug is that we have two values that must agree — the string and an offset into it — and nothing enforces the agreement.

Two things about the function itself. as_bytes gives the string's bytes, iter$ <- enumerate$ walks them with their indices, and (i, &item) in the for destructures each pair — the & in the pattern takes the byte out of the reference the iterator yields. And the if returns early with return i; the function's last line, s <- len$, is the value when no space is found.

String slices

A string slice is a reference to part of a String:

fn main$:
    let s = String.from "hello world"
    let hello = &s[0..5]
    let world = &s[6..11]
    let from_start = &s[..5]      // same as 0..5
    let to_end = &s[6..]          // same as 6..s.len()
    let whole = &s[..]
    println! "{} {} {} {} {}" hello world from_start to_end whole

hello world hello world hello world

&s[0..5] is a reference to the five bytes starting at index 0 — the range's end is excluded, as in chapter 3. Under the hood it is a pointer into s's buffer plus a length. The start may be dropped when it is 0, the end when it is the length, and both when it is the whole string. The type of every one of these is &str, pronounced "string slice", and it is the type of a string literal too: "hello" is a &str pointing into the program's own binary.

Now first_word can return the word itself, tied to the string it came from:

fn first_word s: &str -> &str:
    let bytes = s <- as_bytes$

    for (i, &item) in bytes <- iter$ <- enumerate$:
        if item == b' ':
            return &s[0..i]

    &s[..]

fn main$:
    let s = String.from "hello world"
    let word = first_word (&s)    // a &String coerces to &str
    println! "{}" word

    let literal = "hello world"   // a literal is already a &str
    println! "{}" (first_word literal)
    println! "{}" (first_word (&literal[6..]))

hello
hello
world

The signature takes &str, not &String, and that is the more useful signature: a &String converts to a &str automatically — you see it happen at first_word (&s) — so the function accepts a String, a literal, and a slice of either. Write your functions over &str and everyone can call them. (The last call slices a literal: &literal[6..] is itself a &str, and it is isolated as an argument by the usual rule.)

And now the bug from the start of the section is caught, by the borrowing rule we already have:

fn first_word s: &str -> &str:
    let bytes = s <- as_bytes$

    for (i, &item) in bytes <- iter$ <- enumerate$:
        if item == b' ':
            return &s[0..i]

    &s[..]

fn main$:
    let mut s = String.from "hello world"
    let word = first_word (&s)
    s <- clear$                 // error: word still borrows s
    println! "{}" word

error[E0502]: cannot borrow `s` as mutable because it is also borrowed as immutable
  --> slice_stale.hrs:13:5
   |
12 |     let word = first_word (&s)
   |                            -- immutable borrow occurs here
13 |     s <- clear$                 // error: word still borrows s
   |     ^^^^^^^^^^^ mutable borrow occurs here
14 |     println! "{}" word
   |                   ---- immutable borrow later used here

word is a slice of s, which is an immutable borrow of s; clear needs a mutable borrow to empty the string; the two cannot coexist while word is still used. The index version compiled and lied. The slice version does not compile, and the error names the line. This is the pattern of the whole chapter: an idea that was a bug in one form becomes a type error in another, and the compiler catches at build time what the earlier form would have caught in production, or not at all.

Other slices

Slices are not only for strings. Part of an array is &[i32], a slice of integers, and it works the same way:

fn main$:
    let a = [1, 2, 3, 4, 5]
    let middle: &[i32] = &a[1..4]
    println! "{:?}" middle
    println! "{}" (middle <- len$)

[2, 3, 4]
3

&[T] is the slice type for any element type, and it is what you take as a parameter when a function wants "some contiguous Ts" without caring whether they came from an array or a Vec.

4.4 What you have

One owner per value, dropped at the end of its scope. Assignment and function calls move unless the type is Copy; clone when you want a real copy. & borrows without owning, &mut borrows to change, and at any time there is either one &mut or any number of & — measured from creation to last use. A reference can never outlive what it refers to. And a slice is a borrow of part of something, which is why the compiler can tell when the something changes underneath it.

Nothing in this chapter was Harsh. That is the thesis: the notation was quiet, and Rust was all there was to learn. Next, a way to give your own types a shape — structs.

5. Structs

A struct is a type you define: a name for a bundle of values that belong together — a user, a rectangle, a request. Chapter 4's rules apply to a struct exactly as to a String: a struct owns its fields, is moved on assignment unless it is Copy, and is borrowed with &. This chapter is the definitions, the ways of building a value, and the methods that give a type its behaviour.

There are three forms of struct, and they are three equals, not one standard form and two odd ones. A record struct has named fields — Rust's own documentation calls this one simply "a struct", so that is what you will see it called elsewhere. A tuple struct has fields by position, with no names of their own. A unit-like struct has no fields at all. Every one of them can be declared, built and taken apart, and chapter 6 will show that each variant of an enum is one of these three.

This is also the first chapter where Harsh has a shape of its own to show. A record struct's fields are lines under the heading, one per line, with no commas and no braces, the way a function's body sits under its signature; a tuple struct's field types follow its name the way arguments follow a function; a unit-like struct is its name and nothing more. A value of a record struct is laid out as its declaration is, with a \ after the name to say that a field list follows — the one mark this chapter adds.

5.1 The three forms

// A record struct: named fields, one per line...
struct Point
    x: f64
    y: f64

// ...or on the declaration's line, after the mark
struct Size\ w: f64, h: f64

// A tuple struct: fields by position, the name applied to their types
struct Meters f64

// A unit-like struct: a name and nothing else
struct Origin

fn main$:
    let p = Point\ x = 1.0, y = 2.0
    let s =
        Size\
            w = 3.0
            h = 4.0
    let d = Meters 5.5
    let o = Origin

    println! "{} {} {} {}" (p <- x) (s <- h) (d.0) (matches! o Origin)

1 4 5.5 true

Harsh — A record struct's fields may sit beneath the name, one per line, or on the declaration's own line after a \ — struct Size\ w: f64, h: f64 — and the same choice exists for a value: Point\ x = 1.0, y = 2.0 on one line, or Size\ with a field per line beneath. Neither is the preferred form; the block reads better when the fields are many or their names long, the inline form when the type is small, and this book uses whichever the example reads best in. A tuple struct is the name applied to its field types, struct Meters f64, exactly as Meters 5.5 applies it to a value. A unit-like struct is a name, and Origin is also its only value.

Record structs

struct User
    active: bool
    username: String
    email: String
    sign_in_count: u64

fn main$:
    let mut user1 =
        User\
            active = true
            username = String.from "someusername123"
            email = String.from "someone@example.com"
            sign_in_count = 1
    user1 <- email = String.from "anotheremail@example.com"
    println!
        "{} ({}), active: {}, sign-ins: {}"
        (user1 <- username)
        (user1 <- email)
        (user1 <- active)
        (user1 <- sign_in_count)

someusername123 (anotheremail@example.com), active: true, sign-ins: 1

The definition is struct User and four indented fields, each name: Type. Nothing marks the body: only a name can follow struct, so a deeper line can only be a field. An instance is the struct's name, a \, and every field given a value with = — a line each here, or all on one line after the mark, User\ active = true, …. Order does not matter, but every field must be present, and the \ is what says the name is not finished: a bare User is already a complete expression. Inline, the field list reaches the end of its line, or the ) of the group it is written in — so Point\ x = 1, msg is one literal with the shorthand field msg, with or without parens around it, and the compiler is the one to say whether msg is a field Point has. When a literal is one element of a tuple, give it its own parens: ((Point\ x = 1), msg). A field is read with <-: user1 <- email. The whole instance is mutable or it is not — let mut user1 — and then a field is assigned with <- on the left of =. There is no way to mark a single field mutable, and this is deliberate: mutability is a property of the binding, and a reader who sees let user1 knows the entire value is fixed.

Notice the parentheses around (user1 <- username) when it is handed to println!. A field access has an operator in it, so, like every other operator expression, it is isolated when it is an argument; println! "{}" user1 <- username would read as println! applied to user1, followed by an arrow the macro does not want. The rule is chapter 3's and chapter 4's, applied again.

A literal handed to a function is an argument like any other, and an argument of several tokens is isolated: cards <- push (Card\ id = 1, …), or with the fields beneath, one unit past the literal's name, and the ) under its ( — far to the right, but clear. When that would run past the line, the ( goes on the next line, one unit past the callee, and hrs fmt does it for you. A constructor takes it the same way, Some (Card\ …), Ok (Card\ …). Written bare, cards <- push Card\, it is refused, and the message names the isolated form.

struct Card
    id: u32
    title: String

fn first (cards: &[Card]) -> Result<&Card, String>:
    cards <- first$ <- ok_or (String.from "no cards")

fn main$:
    let mut cards = Vec.new$
    cards <- push (Card\ id = 1, title = String.from "Draft")
    cards <- push (Card\ id = 2, title = String.from "Review")
    cards <- push (Card\
                       id = 3
                       title = String.from "Publish"
                  )
    let spare = Some (Card\ id = 4, title = String.from "Spare")
    match first (&cards)\
        Ok card => println! "first: {} {}" (card <- id) (card <- title)
        Err why => println! "{why}"
    println! "{} cards, spare: {}" (cards <- len$) (spare <- is_some$)

first: 1 Draft
3 cards, spare: true

Building a struct in a function

A function that returns a struct is the ordinary way to construct one with defaults:

struct User
    active: bool
    username: String
    email: String
    sign_in_count: u64

fn build_user (email: String) (username: String) -> User:
    User\
        active = true
        username            // shorthand: the field and the variable share a name
        email
        sign_in_count = 1

fn main$:
    let u =
        build_user
            (String.from "someone@example.com")
            (String.from "someusername123")
    println! "{} <{}>" (u <- username) (u <- email)

someusername123 <someone@example.com>

username, and email, inside the literal are the field init shorthand: when the variable has the same name as the field, the field name alone does both jobs. Not required, but universal in real code, and it is why parameters in constructors tend to be named after fields.

Building one instance from another

Often a new instance is an old one with a few fields changed. The struct update syntax, ..user1, says "and every field I did not mention comes from user1":

struct User
    active: bool
    username: String
    email: String
    sign_in_count: u64

fn main$:
    let user1 =
        User\
            active = true
            username = String.from "someusername123"
            email = String.from "someone@example.com"
            sign_in_count = 1
    let user2 =
        User\
            email = String.from "another@example.com"
            ..user1             // every other field comes from user1
    println!
        "{} <{}> {}"
        (user2 <- username)
        (user2 <- email)
        (user2 <- sign_in_count)
    println! "{}" (user1 <- active)

someusername123 <another@example.com> 1
true

It must be last in the literal. And it moves: ..user1 copies the Copy fields (active, sign_in_count) and moves the rest (username), exactly as let x = user1.username would. After it, user1 is partly gone — user1 <- active is still usable, user1 <- username is not:

struct User
    active: bool
    username: String
    email: String
    sign_in_count: u64

fn main$:
    let user1 =
        User\
            active = true
            username = String.from "someusername123"
            email = String.from "someone@example.com"
            sign_in_count = 1
    let user2 =
        User\
            email = String.from "another@example.com"
            ..user1
    println! "{}" (user1 <- username)    // username was moved into user2
    println! "{}" (user2 <- username)

error[E0382]: borrow of moved value: `user1.username`
  --> update_move.hrs:18:20
   |
15 |         User\
   |         ----- value moved here
18 |     println! "{}" (user1 <- username)    // username was moved into user2
   |                    ^^^^^^^^^^^^^^^^^ value borrowed here after move
   = note: move occurs because `user1.username` has type `String`, which does not implement the `Copy` trait

The compiler tracks moves per field. That is the chapter 4 rule at a finer grain, and the error says which field went where.

Tuple structs

A tuple struct has a name and positional fields with no names of their own — a tuple with a type:

struct Color i32 i32 i32
struct Point i32 i32 i32

fn main$:
    let black = Color 0 0 0
    let origin = Point 0 0 0
    println! "{} {} {}" black.0 black.1 black.2

    let Point x y z = origin
    println! "{} {} {}" x y z

0 0 0
0 0 0

struct Color i32 i32 i32 declares: the field types follow the name, juxtaposed, the way arguments follow a function. Color 0 0 0 constructs, by juxtaposition, three arguments — the same rule as a function call, because in Rust a tuple struct's name is a constructor function. Fields are black.0, black.1: a tuple index keeps its dot and is part of the name, so black.0 is an atom and needs no parentheses as an argument. And a value is taken apart with a pattern of the same shape as the constructor, let Point x y z = origin. Color and Point have the same fields and are different types; a function taking a Color will not accept a Point, which is the point of naming them.

Unit-like structs

A struct can have no fields at all:

struct AlwaysEqual

fn main$:
    let subject = AlwaysEqual
    let _ = subject
    println! "made one"

made one

struct AlwaysEqual is the whole definition — nothing after the name — and AlwaysEqual is also its only value. Such a type exists to carry behaviour (chapter 10 puts traits on one) rather than data.

Ownership of a struct's data

Every String in User is owned by the instance: when the instance is dropped, its strings are. That is why the fields were String and not &str. Try the reference:

struct User
    username: &str
    email: &str

fn main$:
    let user1 =
        User\
            username = "someusername123"
            email = "someone@example.com"
    println! "{}" (user1 <- username)

error[E0106]: missing lifetime specifier
  --> str_field.hrs:2:15
   |
 2 |     username: &str
   |               ^ expected named lifetime parameter
   = help: consider introducing a named lifetime parameter (hrs 1:12)

error[E0106]: missing lifetime specifier
  --> str_field.hrs:3:12
   |
 3 |     email: &str
   |            ^ expected named lifetime parameter
   = help: consider introducing a named lifetime parameter (hrs 1:12)

A struct holding a reference must say how long the referenced data lives — the lifetime the error asks for — so that the compiler can check the struct never outlives what it points at. That is chapter 10; until then, structs own their data, which is the common case and the one that needs no annotation.

5.2 An example program

Here is a small program built three times, to show what a struct does for readability. Compute the area of a rectangle, first with two separate variables:

fn area (width: u32) (height: u32) -> u32:
    width * height

fn main$:
    let width1 = 30
    let height1 = 50
    println!
        "The area of the rectangle is {} square pixels."
        (area width1 height1)

The area of the rectangle is 1500 square pixels.

It works, and area takes two parameters that are related — they are one rectangle's width and height — without saying so. Group them in a tuple:

fn area dimensions: (u32, u32) -> u32:
    dimensions.0 * dimensions.1

fn main$:
    let rect1 = (30, 50)
    println!
        "The area of the rectangle is {} square pixels."
        (area rect1)

The area of the rectangle is 1500 square pixels.

Now one argument, but dimensions.0 and dimensions.1 are worse than width and height: the reader has to know which is which, and so does the next person who edits it. Name them:

struct Rectangle
    width: u32
    height: u32

fn area rectangle: &Rectangle -> u32:
    rectangle <- width * rectangle <- height

fn main$:
    let rect1 = Rectangle\ width = 30, height = 50
    println!
        "The area of the rectangle is {} square pixels."
        (area (&rect1))

The area of the rectangle is 1500 square pixels.

area now takes &Rectangle — a borrow, so main keeps rect1 — and reads rectangle <- width * rectangle <- height. The code says what it means. Application binds tighter than <-, so the two accesses are the operands of * and nothing needs isolating on that line; only the call (area (&rect1)) in the println! does, twice, for the two operators in it.

Printing a struct

println! with {} knows how to print numbers and strings; it does not know how to print a Rectangle, and it says so:

struct Rectangle
    width: u32
    height: u32

fn main$:
    let rect1 = Rectangle\ width = 30, height = 50
    println! "rect1 is {:?}" rect1

error[E0277]: `Rectangle` doesn't implement `Debug`
  --> no_debug.hrs:7:30
   |
 7 |     println! "rect1 is {:?}" rect1
   |                        ---- required by this formatting parameter
   |                              ^^^^^ `Rectangle` cannot be formatted using `{:?}` because it doesn't implement `Debug`
   = help: the trait `Debug` is not implemented for `Rectangle`
   = note: add `#[derive(Debug)]` to `Rectangle` or manually `impl Debug for Rectangle`
   = help: consider annotating `Rectangle` with `#[derive(Debug)]` (hrs 1:1)

{} uses the Display trait, which is for user-facing output, and Rust will not guess what a user-facing rectangle looks like. The {:?} in the message is the debug format, which can be derived automatically — read the compiler's note, which tells you exactly what to add:

#[derive Debug]
struct Rectangle
    width: u32
    height: u32

fn main$:
    let rect1 = Rectangle\ width = 30, height = 50
    println! "rect1 is {:?}" rect1
    println! "rect1 is {:#?}" rect1

rect1 is Rectangle { width: 30, height: 50 }
rect1 is Rectangle {
    width: 30,
    height: 50,
}

#[derive Debug] is an attribute: a line above the definition that asks the compiler to generate an implementation of Debug for the type. Inside its brackets an attribute is an application like any other — derive applied to Debug, and to more, #[derive Debug Clone PartialEq]; an attribute that takes a keyed value isolates it, #[cfg (feature = "fast")]. {:?} prints on one line; {:#?} pretty-prints with each field on its own. You will derive Debug on almost every struct you write. There is also dbg!, a macro that prints an expression and its value to standard error along with the file and line, and hands the value back — dbg! (30 * scale) inside a larger expression is how you look at an intermediate result without restructuring the code.

5.3 Methods

A method is a function that belongs to a type. It is defined inside an impl block and its first parameter is self, the instance it is called on:

#[derive Debug]
struct Rectangle
    width: u32
    height: u32

impl Rectangle
    fn area (&self) -> u32:
        self <- width * self <- height

    fn width (&self) -> bool:
        self <- width > 0

fn main$:
    let rect1 = Rectangle\ width = 30, height = 50
    println!
        "The area of the rectangle is {} square pixels."
        (rect1 <- area$)

    if rect1 <- width$:
        println!
            "The rectangle has a nonzero width; it is {}"
            (rect1 <- width)

The area of the rectangle is 1500 square pixels.
The rectangle has a nonzero width; it is 30

impl Rectangle: opens the block that holds the type's methods. fn area (&self) -> u32: is area with one parameter, &self — a borrow of the instance, in its own group — and the body reads the fields through it. The call is rect1 <- area$: the arrow selects the method on rect1, $ applies it to nothing, and self is &rect1. rect1 <- area$ is the whole call, so as an argument it is isolated like any expression with operators in it.

&self is the choice you make most: read, do not consume. &mut self when the method changes the instance; plain self — taking ownership — rarely, for a method that transforms the value into something else and does not want the old one used again. The three are chapter 4's three ways of passing a value, applied to the receiver.

A method may have the same name as a field. rect1 <- width$ is the method, rect1 <- width the field; the $ tells them apart. The usual reason to do this is a getter: the field private, the method public, so the value can be read but not set from outside the module — chapter 7.

More parameters

After self, a method's parameters are groups like any function's:

#[derive Debug]
struct Rectangle
    width: u32
    height: u32

impl Rectangle
    fn area (&self) -> u32:
        self <- width * self <- height

    fn can_hold (&self) (other: &Rectangle) -> bool:
        self <- width > other <- width && self <- height > other <- height

fn main$:
    let rect1 = Rectangle\ width = 30, height = 50
    let rect2 = Rectangle\ width = 10, height = 40
    let rect3 = Rectangle\ width = 60, height = 45

    println! "Can rect1 hold rect2? {}" (rect1 <- can_hold (&rect2))
    println! "Can rect1 hold rect3? {}" (rect1 <- can_hold (&rect3))

Can rect1 hold rect2? true
Can rect1 hold rect3? false

fn can_hold (&self) (other: &Rectangle) — the receiver, then one parameter. The call, rect1 <- can_hold (&rect2), applies the method to one argument, isolated because of its &.

Associated functions

A function in an impl block that does not take self is an associated function: it belongs to the type but not to an instance. Constructors are the classic case:

#[derive Debug]
struct Rectangle
    width: u32
    height: u32

impl Rectangle
    fn square size: u32 -> Self:
        Self\ width = size, height = size

impl Rectangle
    fn area (&self) -> u32:
        self <- width * self <- height

fn main$:
    let sq = Rectangle.square 3
    println! "{:?} has area {}" sq (sq <- area$)

Rectangle { width: 3, height: 3 } has area 9

fn square size: u32 -> Self: — Self inside an impl is an alias for the type, so this returns a Rectangle. It is called with the path form, Rectangle.square 3: a dot, because this is a path into the type's namespace, not a method on a value. String.from and String.new$ are the same thing, and now you know what they are. A type may have several impl blocks, as here; there is no reason to split them in a program this size, but it is legal, and chapter 10 shows when it is useful.

5.4 What you have

A struct is named fields under a heading; an instance is the name, a \, and its fields with =, with shorthand and ..other to fill it. Tuple structs are constructed and matched by juxtaposition; a unit struct is a name alone. Structs own their data until chapter 10 says how they may borrow it. #[derive Debug] and {:?} to see one. impl holds the methods, &self reads, &mut self changes, self consumes, and rect1 <- area$ calls; a function without self is associated with the type and called through its path, Rectangle.square 3.

Next: enums — types whose value is one of several named shapes — and match, which you met in chapter 2 and can now understand.

6. Enums and pattern matching

A struct says "all of these, together". An enum says "exactly one of these". A value of an enum type is one of a fixed set of named variants, and each variant may carry data of its own — so an enum is both a set of alternatives and, when the variants have payloads, a way of saying "this value is one of several shapes, and here is which". Rust programs are built on two of them, Option and Result, and on match, the construct that takes an enum apart and refuses to let you forget a case.

6.1 Defining an enum

An IP address is version four or version six — never both, never neither. That is an enum:

#[derive Debug]
enum IpAddrKind
    V4
    V6

fn route ip_kind: IpAddrKind:
    println! "routing {:?}" ip_kind

fn main$:
    let four = IpAddrKind.V4
    let six = IpAddrKind.V6
    route four
    route six

routing V4
routing V6

enum IpAddrKind and two variants, one per line, no commas, the same layout as a struct's fields, and markless for the same reason: only a name can follow enum. A variant is named through the type, IpAddrKind.V4, with a dot, because it is a path: the variant lives inside the type's namespace. Both values have the type IpAddrKind, so one function takes either.

Variants with data

The kind alone is not much use; an address has a value. A variant can carry one:

#[derive Debug]
enum IpAddr
    V4 u8 u8 u8 u8
    V6 String

fn main$:
    let home = IpAddr.V4 127 0 0 1
    let loopback = IpAddr.V6 (String.from "::1")
    println! "{:?} {:?}" home loopback

V4(127, 0, 0, 1) V6("::1")

V4 u8 u8 u8 u8 is a variant with four fields and V6 String a variant with one — the variant applied to its payload's types, exactly as a tuple struct is declared. Constructing is application: IpAddr.V4 127 0 0 1 applies the variant to four arguments, and IpAddr.V6 (String.from "::1") to one, isolated because it is a call. Each variant is a constructor function for the enum, and the two variants may carry different types — something no struct can express.

Variants can take any shape a struct can — and that sentence is the whole of what an enum is. An enum is a union of variants, and each variant is one of chapter 5's three forms: a unit-like struct, a record struct, or a tuple struct, spelled exactly as the struct of that form is spelled, with the word struct and the name's own line taken away. (A type built this way — a choice among bundles — is what Haskell and its relatives call an algebraic data type; Rust's enums are that, with the word left out.)

#[derive Debug]
enum Message
    Quit                          // a unit-like struct

    Move                          // a record struct
        x: i32
        y: i32

    Write String                  // a tuple struct
    ChangeColor i32 i32 i32       // a tuple struct

impl Message
    fn call (&self):
        println! "calling {:?}" self

fn main$:
    let msgs =
        [
            Message.Quit,
            (Message.Move\ x = 1, y = 2),
            (Message.Write (String.from "hi")),
            (Message.ChangeColor 0 160 255),
        ]

    for m in &msgs:
        m <- call$

calling Quit
calling Move { x: 1, y: 2 }
calling Write("hi")
calling ChangeColor(0, 160, 255)

Harsh — Quit is a unit-like struct; Move with x and y beneath it is a record struct; Write String and ChangeColor i32 i32 i32 are tuple structs, the name applied to the payload's types. Each is written as chapter 5 wrote it, and each has the inline form chapter 5 had too — Move\ x: i32, y: i32 on one line — so the same enum reads either way, and which to use is the same judgement as for a struct: what the names and their lengths make clearest.

enum Message
    Quit
    Move\ x: i32, y: i32
    Write String
    ChangeColor i32 i32 i32

fn main$:
    let m = Message.Move\ x = 1, y = 2
    if let Message.Move\ x, y = m:
        println! "moved to {x},{y}"

moved to 1,2

Quit carries nothing; Move opens a record variant with named fields beneath it, exactly as a struct's are laid out; Write String and ChangeColor i32 i32 i32 are tuple variants, their payload types juxtaposed after the name. A record variant's value is a literal like any other, Message.Move\ x = 1, y = 2. Without the enum this would be four separate struct types, and no function could take "a message" — with it, impl Message: gives all four a method, and m <- call$ works on any of them. (for m in &msgs borrows the array so the messages are not moved out of it; chapter 8 makes that habit.)

Option

Rust has no null. Where another language returns a value that might be null, Rust returns a value that might be absent, and says so in the type:

fn main$:
    let some_number = Some 5
    let some_char = Some 'e'
    let absent_number: Option<i32> = None
    println! "{:?} {:?} {:?}" some_number some_char absent_number

Some(5) Some('e') None

Option<T> is an enum with two variants, Some T — there is a value, here it is — and None. It is so central that both variants are in scope without a prefix: you write Some 5 and None, not Option.Some 5. The type of absent_number has to be written, because None alone does not say what kind of value is absent.

What Option buys you is that an Option<i8> is not an i8, and the compiler will not let you treat it as one:

fn main$:
    let x: i8 = 5
    let y: Option<i8> = Some 5
    let sum = x + y
    println! "{}" sum

error[E0277]: cannot add `Option<i8>` to `i8`
  --> option_add.hrs:4:17
   |
 4 |     let sum = x + y
   |                 ^ no implementation for `i8 + Option<i8>`
   = help: the trait `Add<Option<i8>>` is not implemented for `i8`
   = help: the following other types implement trait `Add<Rhs>`

In a language with null, x + y compiles and fails at runtime when y happens to be null. Here it does not compile, because a value that might be absent cannot be added until you have said what happens when it is. To use the i8 inside, you have to take the Option apart, and handling the None case is part of taking it apart. That is the whole idea, and match is how it is done.

6.2 match

match takes a value and a list of arms, each a pattern and the code to run when the pattern fits. The first arm whose pattern matches wins:

enum Coin
    Penny
    Nickel
    Dime
    Quarter

fn value_in_cents coin: Coin -> u8:
    match coin\
        Coin.Penny => do:
            println! "Lucky penny!"
            1
        Coin.Nickel => 5
        Coin.Dime => 10
        Coin.Quarter => 25

fn main$:
    println! "{}" (value_in_cents Coin.Penny)
    println! "{}" (value_in_cents Coin.Quarter)

Lucky penny!
1
25

match coin\ opens the arms; each is pattern => expression, one per line. An arm's expression is its value, and the match is worth whichever arm ran — so value_in_cents returns the u8 from the arm that matched. An arm that needs several statements opens a block with => do:, and the block's last line is its value, as everywhere.

Harsh — One arm per line, and no comma after it: the line ending is what separates arms, and a , at the end of one is an error naming the newline. Commas separate arms only when several share a line.

Patterns that bind

When a variant carries data, the pattern names it and the arm can use it:

#[derive Debug]
enum UsState
    Alabama
    Alaska

enum Coin
    Penny
    Nickel
    Dime
    Quarter UsState

fn value_in_cents coin: Coin -> u8:
    match coin\
        Coin.Penny => 1
        Coin.Nickel => 5
        Coin.Dime => 10
        Coin.Quarter state => do:
            println! "State quarter from {:?}!" state
            25

fn main$:
    println! "{}" (value_in_cents (Coin.Quarter UsState.Alaska))

State quarter from Alaska!
25

Coin.Quarter state — the pattern has the shape of the constructor, with a variable where the value goes. When a Quarter matches, state is bound to the UsState inside it for the length of the arm. This is the same juxtaposition that constructs: Coin.Quarter UsState.Alaska builds one, Coin.Quarter state takes one apart. A pattern is an application throughout — Some n, Ok value, Circle r — and a record variant is taken apart with the same mark that builds it, Move\ x, y, as chapter 5 did for a struct.

Matching Option

Now the Option from the previous section can be used:

fn plus_one x: Option<i32> -> Option<i32>:
    match x\
        None => None
        Some i => Some (i + 1)

fn main$:
    let five = Some 5
    let six = plus_one five
    let none = plus_one None
    println! "{:?} {:?}" six none

Some(6) None

None => None and Some i => Some (i + 1): two arms, two variants, and inside the second i is the i32, so i + 1 is ordinary arithmetic; Some (i + 1) wraps the result back up, its argument isolated because of the +. Combining match and enums this way is how most Rust code handles values that might not be there; after a while you stop noticing it.

Matches are exhaustive

Leave a case out and the compiler stops you:

fn plus_one x: Option<i32> -> Option<i32>:
    match x\
        Some i => Some (i + 1)

fn main$:
    println! "{:?}" (plus_one (Some 5))

error[E0004]: non-exhaustive patterns: `None` not covered
  --> non_exhaustive.hrs:2:11
   |
 2 |     match x\
   |           ^ pattern `None` not covered
   = note: `Option<i32>` defined here
   = note: the matched value is of type `Option<i32>`
   = help: ensure that all possible cases are being handled by adding a match arm with a wildcard pattern or an explicit pattern as shown (hrs 3:31)

Every possible value must be covered by some arm. This is what makes Option safe: you cannot forget the None case, because forgetting it is a compile error. The same holds for your own enums — add a variant, and every match that does not handle it fails to build, which is exactly the list of places you needed to look.

Catch-all patterns

When only some values matter, the last arm can catch the rest:

fn add_fancy_hat$:
    println! "fancy hat"
fn remove_fancy_hat$:
    println! "no hat"
fn move_player spaces: u8:
    println! "move {} spaces" spaces

fn main$:
    for dice_roll in [3, 7, 4]:
        match dice_roll\
            3 => add_fancy_hat$
            7 => remove_fancy_hat$
            other => move_player other

    // when the value is not needed, `_` matches anything and binds nothing

    let roll = 9

    match roll\
        3 => add_fancy_hat$
        7 => remove_fancy_hat$
        _ => ()

fancy hat
no hat
move 4 spaces

other => move_player other binds whatever did not match 3 or 7 to other and uses it. When the value is not needed, _ matches anything and binds nothing, and _ => () says "and do nothing" — () is the unit value, and a match whose arms are all unit is a statement. The catch-all must be last, since arms are tried in order and nothing after it could ever run.

6.3 if let and let … else

A match with one arm that matters and a _ => () is a lot of lines for "if this is a Some, do this":

fn main$:
    let config_max = Some 3u8

    // The match way: one arm that matters, one that does nothing.
    match config_max\
        Some max => println! "The maximum is configured to be {max}"
        _ => ()

    // The `if let` way: the same, in one line.

    if let Some max = config_max:
        println! "The maximum is configured to be {max}"

The maximum is configured to be 3
The maximum is configured to be 3

if let Some max = config_max: is a condition that is also a pattern: if config_max matches Some max, bind max and run the block. It is match with one arm and no exhaustiveness check — you are choosing to ignore the other cases, and the syntax says so. Use it when one case is all you want; use match when forgetting a case would be a bug.

if let takes an else, which runs for everything the pattern did not match:

#[derive Debug]
enum UsState
    Alabama
    Alaska

enum Coin
    Penny
    Quarter UsState

fn main$:
    let coins = [Coin.Penny, (Coin.Quarter UsState.Alabama), Coin.Penny]
    let mut count = 0

    for coin in coins:
        if let Coin.Quarter state = coin:
            println! "State quarter from {:?}!" state
        else:
            count += 1

    println! "{} non-quarters" count

State quarter from Alabama!
2 non-quarters

Sometimes the pattern is a guard at the top of a function: if the value has the right shape, carry on with its contents; otherwise leave. let … else is that, without nesting the rest of the function inside an if:

#[derive Debug]
enum UsState
    Alabama
    Alaska

impl UsState
    fn existed_in (&self) (year: u16) -> bool:
        match self\
            UsState.Alabama => year >= 1819
            UsState.Alaska => year >= 1959

enum Coin
    Penny
    Quarter UsState

fn describe_state_quarter coin: Coin -> Option<String>:
    let Coin.Quarter state = coin else:
        return None

    if state <- existed_in 1900:
        Some (format! "{state:?} is pretty old, for America!")
    else:
        Some (format! "{state:?} is relatively new.")

fn main$:
    println!
        "{:?}"
        (describe_state_quarter (Coin.Quarter UsState.Alabama))
    println!
        "{:?}"
        (describe_state_quarter (Coin.Quarter UsState.Alaska))
    println! "{:?}" (describe_state_quarter Coin.Penny)

Some("Alabama is pretty old, for America!")
Some("Alaska is relatively new.")
None

let Coin.Quarter state = coin else: — if coin is a Quarter, state is bound for the rest of the function, not just for a block; if it is not, the else runs, and the else must leave (here with return), because there is no state to continue with. The happy path stays flat, which is the reason this form exists. The else block may also be inline, else: return None, when it is one expression.

6.4 What you have

An enum is one of several named variants, each carrying nothing, a tuple, or named fields; variants are constructed and matched by juxtaposition, IpAddr.V4 127 0 0 1, Coin.Quarter state. Option<T> is Some T or None and is Rust's null, made safe by the type. match takes a value apart with patterns, binds what is inside, and must cover every case; _ and other catch the rest. if let for one case, let … else to guard and continue.

Next: modules — how a program larger than one file is organised, and what pub and use actually do.

7. Packages, crates and modules

Every program so far fitted in one file. Real ones do not, and Rust's answer to "where does this code live and who may call it" has three layers: a package is what hrs new makes — a Cargo.toml and a src/ directory; a crate is what the compiler builds from it, a binary or a library; and inside a crate, modules group items and decide which of them are visible from outside. This chapter is the module system: how to declare a module, how to name a thing inside one, what pub opens, what use shortens, and how a module moves into its own file.

7.1 Packages and crates

A crate is the unit of compilation: rustc is given one file — the crate root, src/main.hrs for a binary or src/lib.hrs for a library — and everything the crate contains is reached from there through mod declarations. A package holds at most one library crate and any number of binaries, and Cargo.toml names them; hrs new hello writes a package with one binary whose root is src/main.hrs, and hrs run transpiles the tree under src/ and hands cargo the result. You met the arrangement in chapter 1; this chapter is what goes in the tree.

7.2 Modules

A module is a named scope for items — functions, structs, enums, other modules — declared with mod and a block:

mod front_of_house
    mod hosting
        fn add_to_waitlist$:
            println! "added to waitlist"

        fn seat_at_table$:
            println! "seated"

    mod serving
        fn take_order$:
            println! "order taken"

        fn serve_order$:
            println! "served"

        fn take_payment$:
            println! "paid"

fn main$:
    println! "the restaurant is open"

the restaurant is open

mod front_of_house: opens a module; mod hosting: inside it opens a nested one, and the functions sit inside that. The layout is the same as everywhere: a heading, and the contents indented beneath. The result is a module tree rooted at the crate:

crate
 └── front_of_house
     ├── hosting
     │   ├── add_to_waitlist
     │   └── seat_at_table
     └── serving
         ├── take_order
         ├── serve_order
         └── take_payment

Modules are for organising code the way directories organise files, and — the part that matters — for privacy: everything inside a module is private to that module and its descendants unless it is marked otherwise.

7.3 Paths

To call something in a module you name its path, the way you name a file in a directory. A path is either absolute, starting from crate, or relative, starting from the current module; the segments are joined with .:

mod front_of_house
    mod hosting
        fn add_to_waitlist$:
            println! "added to waitlist"

fn eat_at_restaurant$:
    crate.front_of_house.hosting.add_to_waitlist$    // absolute path
    front_of_house.hosting.add_to_waitlist$          // relative path

fn main$:
    eat_at_restaurant$

error[E0603]: module `hosting` is private
  --> private_path.hrs:7:26
   |
 7 |     crate.front_of_house.hosting.add_to_waitlist$    // absolute path
   |                          ^^^^^^^ private module
   |                                  --------------- function `add_to_waitlist` is not publicly re-exported
   = note: the module `hosting` is defined here (hrs 2:5)

error[E0603]: module `hosting` is private
  --> private_path.hrs:8:20
   |
 8 |     front_of_house.hosting.add_to_waitlist$          // relative path
   |                    ^^^^^^^ private module
   |                            --------------- function `add_to_waitlist` is not publicly re-exported
   = note: the module `hosting` is defined here (hrs 2:5)

Both paths are correctly spelled and the program does not build, because hosting is private. The rule: a child module can see everything in its ancestors, but a parent cannot see inside a child unless the child says so. eat_at_restaurant lives in the crate root, which is front_of_house's parent, so it can see front_of_house (siblings are visible); but hosting is inside front_of_house and was not made public, so the path stops there. The error names the exact segment. The reason for the default is that a module's insides are its implementation; what it chooses to expose is its interface, and changing an interface should be a decision, not an accident.

pub is that decision:

mod front_of_house
    pub mod hosting
        pub fn add_to_waitlist$:
            println! "added to waitlist"

fn eat_at_restaurant$:
    crate.front_of_house.hosting.add_to_waitlist$    // absolute path, from the crate root
    front_of_house.hosting.add_to_waitlist$          // relative path, from here

fn main$:
    eat_at_restaurant$

added to waitlist
added to waitlist

pub mod hosting lets the parent see the module; pub fn add_to_waitlist lets it call the function. Both are needed — making a module public does not make its contents public, only reachable. Now the absolute path crate.front_of_house.hosting.add_to_waitlist$ and the relative front_of_house.hosting.add_to_waitlist$ both work, and end in $ because they are calls. Prefer the absolute path when the caller and the callee are likely to move independently; prefer the relative one when they will move together.

super

A path may also start from the parent module, with super:

fn deliver_order$:
    println! "delivered"

mod back_of_house
    pub fn fix_incorrect_order$:
        cook_order$
        super.deliver_order$      // one level up: the crate root

    fn cook_order$:
        println! "cooked"

fn main$:
    back_of_house.fix_incorrect_order$

cooked
delivered

super.deliver_order$ from inside back_of_house reaches the crate root, where deliver_order lives. It is the module system's ..: use it when a child depends on something in its parent and the two will stay together, so the relation "one level up" is the stable one to write down.

Public structs and enums

pub on a struct makes the type public, and each field is still private unless it too is marked:

mod back_of_house
    pub struct Breakfast
        pub toast: String
        seasonal_fruit: String

    impl Breakfast
        pub fn summer toast: &str -> Breakfast:
            Breakfast\
                toast = String.from toast
                seasonal_fruit = String.from "peaches"

fn main$:
    // A public constructor is the only way in, since one field is private.
    let mut meal = back_of_house.Breakfast.summer "Rye"
    meal <- toast = String.from "Wheat"       // public field: readable and settable
    println! "I'd like {} toast please" (meal <- toast)

I'd like Wheat toast please

toast is public and seasonal_fruit is not, so outside back_of_house a Breakfast can be read and written through toast alone — and cannot be constructed with a literal at all, since a literal has to give every field. That is why summer exists: a public associated function is the way to build a struct that has a private field, and it is where the module gets to choose the default. Try the private field from outside:

mod back_of_house
    pub struct Breakfast
        pub toast: String
        seasonal_fruit: String

    impl Breakfast
        pub fn summer toast: &str -> Breakfast:
            Breakfast\
                toast = String.from toast
                seasonal_fruit = String.from "peaches"

fn main$:
    let mut meal = back_of_house.Breakfast.summer "Rye"
    meal <- seasonal_fruit = String.from "blueberries"

error[E0616]: field `seasonal_fruit` of struct `Breakfast` is private
  --> private_field.hrs:14:13
   |
14 |     meal <- seasonal_fruit = String.from "blueberries"
   |             ^^^^^^^^^^^^^^ private field

An enum is the opposite: pub enum makes every variant public, because an enum with hidden variants would be one you could not match on:

mod back_of_house
    #[derive Debug]
    pub enum Appetizer
        Soup
        Salad

fn main$:
    let order1 = back_of_house.Appetizer.Soup     // variants are public with the enum
    let order2 = back_of_house.Appetizer.Salad
    println! "{:?} {:?}" order1 order2

Soup Salad

7.4 use

Writing the full path at every call is tedious, and use brings a path into scope once:

mod front_of_house
    pub mod hosting
        pub fn add_to_waitlist$:
            println! "added to waitlist"

use crate.front_of_house.hosting          // bring the module in, not the function

fn eat_at_restaurant$:
    hosting.add_to_waitlist$              // the parent says where it came from

fn main$:
    eat_at_restaurant$

added to waitlist

After use crate.front_of_house.hosting, the name hosting is in scope in this module and hosting.add_to_waitlist$ works. This is also the idiomatic depth to import at for a function: bring in the parent module, not the function, so that every call says where it came from — hosting.add_to_waitlist$ reads as "hosting's", where a bare add_to_waitlist$ would look local. For structs, enums and traits the convention is the opposite — import the type itself, use std.collections.HashMap — since a type's name is meant to be used bare.

A use is scoped to the module it appears in. It does not reach into a child module:

mod front_of_house
    pub mod hosting
        pub fn add_to_waitlist$:
            println! "added to waitlist"

use crate.front_of_house.hosting

mod customer
    pub fn eat_at_restaurant$:
        hosting.add_to_waitlist$          // `use` above is in the parent, not here

fn main$:
    customer.eat_at_restaurant$

error[E0433]: cannot find module or crate `hosting` in this scope
  --> use_scope.hrs:10:9
   |
10 |         hosting.add_to_waitlist$          // `use` above is in the parent, not here
   |         ^^^^^^^ use of unresolved module or unlinked crate `hosting`
   = help: you might be missing a crate named `hosting`
   = help: consider importing this module through its public re-export (hrs 9:5)

The use is in the crate root; customer is a child; the name is not in scope there. Either move the use into customer or write super.hosting from inside it.

as

When two imports would have the same name, rename one:

use std.fmt.Result
use std.io.Result as IoResult             // two `Result`s: rename one

fn function1$ -> Result:
    Ok ()

fn function2$ -> IoResult<()>:
    Ok ()

fn main$:
    println! "{:?} {:?}" (function1$) (function2$ <- is_ok$)

Ok(()) true

Both std.fmt and std.io define a Result. use std.io.Result as IoResult brings the second in under a different name; the as is Rust's, unchanged.

Re-exporting with pub use

use brings a name in for this module. pub use brings it in and passes it on, so that users of this module see it as if it had been defined here:

mod restaurant
    mod front_of_house
        pub mod hosting
            pub fn add_to_waitlist$:
                println! "added to waitlist"

    pub use front_of_house.hosting        // re-export: visible to users of `restaurant`

fn main$:
    restaurant.hosting.add_to_waitlist$   // the internal `front_of_house` is not mentioned

added to waitlist

restaurant's user calls restaurant.hosting.add_to_waitlist$ and never learns that hosting is really inside front_of_house. Re-exporting is how a library presents a public structure different from its internal one — the way the code is organised for its authors and the way it is presented to its users need not be the same tree.

Nested paths and globs

Several imports from one place can share their prefix:

use std.(cmp.Ordering, collections.HashMap)   // two paths sharing a prefix
use std.io.(self, Write)                      // the module itself, and one item from it
use std.collections.*                         // everything: the glob, for tests and preludes

fn main$:
    let mut m: HashMap<&str, i32> = HashMap.new$
    m <- insert "a" 1

    let s: HashSet<i32> = HashSet.new$        // from the glob
    let ord = 1 <- cmp (&2)
    let mut out = io.stdout$
    writeln! out "{:?} {:?} {}" ord (m <- get "a") (s <- len$)
        <- unwrap$

    let _ = Ordering.Less

Less Some(1) 0

use std.(cmp.Ordering, collections.HashMap) is two imports; the parentheses group the branches of a use tree, which is one of the four things parentheses do in Harsh. use std.io.(self, Write) imports the module io itself and one item from it — self in a use tree means "the thing before the parentheses". And use std.collections.* imports everything the module exports: the glob. Globs make it hard to see where a name came from, so they are for two places — tests, which import everything from the module under test, and preludes, modules designed to be imported whole.

7.5 Separating modules into files

So far every module has had its body inline. As a program grows, a module goes into a file of its own, and the tree of modules becomes a tree of files:

src/main.hrs

use crate.garden.vegetables.Asparagus

pub mod garden      // the body is in src/garden.hrs

fn main$:
    let plant = Asparagus
    println! "I'm growing {plant:?}!"

src/garden.hrs

pub mod vegetables  // the body is in src/garden/vegetables.hrs

src/garden/vegetables.hrs

#[derive Debug]
pub struct Asparagus

$ cargo run
I'm growing Asparagus!

Three files. src/main.hrs declares pub mod garden with no body — just the declaration on a line — and the compiler looks for the body in src/garden.hrs. That file declares pub mod vegetables the same way, and the body of that is found in src/garden/vegetables.hrs: a module's children go in a directory named after it. The use at the top of main.hrs is then the ordinary thing, a path through the tree to the item wanted.

Only the crate root ever needs to know the tree's shape; a file that declares a child module does not say where the child's file is, because there is only one place it can be. And nothing in the calling code changes when a module moves from inline to its own file — the path crate.garden.vegetables.Asparagus is the same either way. Moving code into files is a filing decision, and the module system keeps it from being anything more.

Harsh — The file layout is not Harsh's invention and Harsh does not touch it: hrs build transpiles every file under src/ into export/src/, tree for tree and name for name, so the compiler finds each module exactly where the declaration says it is.

7.6 What you have

A package is what hrs new makes and a crate is what the compiler builds from its root. mod opens a module; everything in it is private until pub says otherwise, and pub on a struct still leaves each field private. Paths are crate. from the root, or relative, or super. from the parent, with . between segments. use shortens a path for one module — import the parent for a function, the type for a type — as renames, pub use re-exports, (…) groups, * takes all. A bodiless mod name puts the body in name.hrs, and its children in name/.

Next: the collections the standard library gives you — Vec, String and HashMap — which is where ownership starts to earn its keep in daily code.

8. Common collections

The standard library's collections hold many values on the heap, so they can grow and shrink while the program runs — unlike an array or a tuple, whose size is part of its type. This chapter is the three you will use constantly: Vec, a growable list; String, which you have been using and can now understand; and HashMap, keys to values. Each one is a place where ownership and borrowing stop being chapter 4's theory and become the ordinary texture of daily code.

8.1 Vectors

A Vec<T> is a list of values of one type, stored next to each other, growable:

fn main$:
    let v: Vec<i32> = Vec.new$          // empty: the type must be written
    let w = vec! 1 2 3              // from values: the type is inferred
    let mut u = Vec.new$

    u <- push 5                         // and now u is a Vec<i32>
    u <- push 6
    println! "{:?} {:?} {:?}" v w u

[] [1, 2, 3] [5, 6]

Vec.new$ makes an empty one, and since nothing has been put in it, its type has to be written: Vec<i32>. vec! 1 2 3 is a macro that builds one from values, applied like a function — one argument per value — and infers the type; vec! { 0; 4 } repeats one value four times, in braces because that stream is not a list. Vec.new$ followed by push also infers it, from the first thing pushed: the compiler waits to see what u holds. Pushing requires mut, as changing anything does.

Reading elements

There are two ways to read an element, and the difference is what happens when it is not there:

fn main$:
    let v = vec! 1 2 3 4 5
    let third: &i32 = &v[2]             // index: panics if out of range
    println! "The third element is {third}"

    let third: Option<&i32> = v <- get 2   // get: None if out of range

    match third\
        Some third => println! "The third element is {third}"
        None => println! "There is no third element."

    println! "{:?} {:?}" (v <- get 100) (v <- get 0)

The third element is 3
The third element is 3
None Some(1)

&v[2] is indexing: a reference to the third element, and a panic if there is no third element. v <- get 2 returns an Option<&i32>: Some with the reference, or None. Which to use is a decision about the program, not about the vector. Index when an out-of-range access is a bug in your logic and should stop the program loudly; get when it is an ordinary event — user input, say — that the code should handle. Here is the loud version:

fn main$:
    let v = vec! 1 2 3 4 5
    let does_not_exist = v <- get 100
    println! "{:?}" does_not_exist

    let does_not_exist = &v[100]        // this line panics at runtime
    println! "{}" does_not_exist

None
thread 'main' (16438) panicked at vec_index_panic.hrs:7:
index out of bounds: the len is 5 but the index is 100

The program printed None for get 100, then reached &v[100] and stopped, with the line. That is what a panic is: an unrecoverable error that ends the program with a message rather than reading memory it should not. Chapter 9 is about when to panic and when to return an Option or Result instead.

Borrowing a vector

Chapter 4's rule applies, and the vector is where it first surprises people:

fn main$:
    let mut v = vec! 1 2 3 4 5
    let first = &v[0]
    v <- push 6
    println! "The first element is: {first}"

error[E0502]: cannot borrow `v` as mutable because it is also borrowed as immutable
  --> vec_borrow.hrs:4:5
   |
 3 |     let first = &v[0]
   |                  - immutable borrow occurs here
 4 |     v <- push 6
   |     ^^^^^^^^^^^^ mutable borrow occurs here
 5 |     println! "The first element is: {first}"
   |                                      ----- immutable borrow later used here

Holding a reference to the first element and then pushing looks harmless — the first element is not moving. But it might: a Vec that runs out of room allocates a bigger buffer, copies everything across and frees the old one, and first would then point into freed memory. The compiler does not know whether this push will reallocate, and does not need to; it knows that push needs &mut v while first holds &v, and that is enough. The fix is the usual one: use first before the push, or copy the value out (let first = v[0] — an i32 is Copy).

Iterating

To visit every element, borrow the vector and loop:

fn main$:
    let v = vec! 100 32 57

    for i in &v:
        println! "{i}"

    let mut v = vec! 100 32 57

    for i in &mut v:
        *i += 50                        // dereference to reach the number

    println! "{:?}" v

100
32
57
[150, 82, 107]

for i in &v gives i a &i32 each time; for i in &mut v gives &mut i32, and *i += 50 writes through it — the * is the dereference, reaching the number inside the reference. A for over v without the & would move the vector into the loop and consume it; the borrowed forms leave it usable afterwards, and they are what you almost always want.

One vector, several types

A vector holds one type. When you need several, make the one type an enum:

#[derive Debug]
enum SpreadsheetCell
    Int i32
    Float f64
    Text String

fn main$:
    let row =
        vec!
            (SpreadsheetCell.Int 3)
            (SpreadsheetCell.Text (String.from "blue"))
            (SpreadsheetCell.Float 10.12)

    for cell in &row:
        match cell\
            SpreadsheetCell.Int n => println! "int {n}"
            SpreadsheetCell.Float x => println! "float {x}"
            SpreadsheetCell.Text s => println! "text {s}"

int 3
text blue
float 10.12

Vec<SpreadsheetCell> holds ints, floats and strings, each wrapped in the variant that says which; taking one out is a match, so every kind is handled. This is how Rust does a heterogeneous list without giving up on knowing what is in it: the set of possibilities is fixed at compile time and written down in the enum. When the set is not known ahead of time, the answer is a trait object, in chapter 21.

8.2 Strings

You have used String since chapter 1. Here is what it is: a Vec<u8> that is guaranteed to hold valid UTF-8, with methods that know it. That guarantee is the source of everything that seems awkward about strings in Rust, and also of everything that is not a bug.

fn main$:
    let mut s = String.new$
    let data = "initial contents"
    let s1 = data <- to_string$
    let s2 = "initial contents" <- to_string$    // same, on the literal
    let s3 = String.from "initial contents"      // same again

    s <- push_str "bar"
    s <- push '!'
    println! "{s} {s1} {s2} {s3}"

    let hello = String.from "Здравствуйте"       // any UTF-8
    println! "{hello} is {} bytes" (hello <- len$)

bar! initial contents initial contents initial contents
Здравствуйте is 24 bytes

String.new$ makes an empty one; to_string$ on anything that can display itself, or String.from, makes one from text; push_str appends a string slice and push a single character. Any UTF-8 is fine, and len$ is the length in bytes, which for "Здравствуйте" is 24 — twelve characters, two bytes each. Hold on to that.

Concatenation

+ joins strings, with a rule that is easy to misread:

fn main$:
    let s1 = String.from "Hello, "
    let s2 = String.from "world!"
    let s3 = s1 + &s2           // s1 is moved into s3; s2 is borrowed
    println! "{s3} / {s2}"

    let a = String.from "tic"
    let b = String.from "tac"
    let c = String.from "toe"
    let s = format! "{a}-{b}-{c}"   // borrows all three, moves none
    println! "{s} {a} {b} {c}"

Hello, world! / world!
tic-tac-toe tic tac toe

s1 + &s2 takes s1 by value — it is moved into the result, so s1 is gone after — and s2 by reference, so s2 is still here. The reason is efficiency: + appends s2's bytes to s1's buffer and hands that buffer back, rather than copying both into a third. When you would rather keep everything, format! builds a new String from a format string and borrows all its arguments, exactly as println! does; it is also easier to read once there are more than two pieces.

Why you cannot index a string

fn main$:
    let s1 = String.from "hello"
    let h = s1[0]
    println! "{}" h

error[E0277]: the type `str` cannot be indexed by `{integer}`
  --> string_index.hrs:3:16
   |
 3 |     let h = s1[0]
   |                ^ string indices are ranges of `usize`
   = help: the trait `SliceIndex<str>` is not implemented for `{integer}`
   = note: you can use `.chars().nth()` or `.bytes().nth()`
for more information, see chapter 8 in The Book: <https://doc.rust-lang.org/book/ch08-02-strings.html#indexing-into-strings>
   = help: `usize` implements trait `SliceIndex<T>`
   = note: required for `String` to implement `Index<{integer}>`

s1[0] does not compile, and the reason is the byte count above. A String is bytes; a character may be one to four of them; so "the first character" is not "byte zero", and Rust refuses to pretend it is. Indexing that returned a byte would be wrong for most of the world's text, and indexing that returned a character would have to scan from the start, which is not what [i] promises. So there is no [i].

Slicing and iterating

What there is: a byte range slice, and iterators over characters or bytes:

fn main$:
    let hello = "Здравствуйте"
    let s = &hello[0..4]          // four bytes: two Cyrillic characters
    println! "{s}"

    for c in "Зд" <- chars$:      // characters
        println! "{c}"

    for b in "Зд" <- bytes$:      // bytes
        println! "{b}"

Зд
З
д
208
151
208
180

&hello[0..4] is the first four bytes, which happen to be two whole characters. Ask for 0..1 — half a character — and the program panics, so byte slicing a string is for when you know the bytes, not for "the first n letters". For letters, chars$ yields each character in turn; bytes$ yields the raw bytes. Which one you want depends on what you mean, and Rust makes you say.

8.3 Hash maps

A HashMap<K, V> stores values under keys and finds a value by hashing its key:

use std.collections.HashMap

fn main$:
    let mut scores = HashMap.new$
    scores <- insert (String.from "Blue") 10
    scores <- insert (String.from "Yellow") 50

    let team_name = String.from "Blue"
    let score =
        scores <- get (&team_name)
               <- copied$
               <- unwrap_or 0
    println! "{score}"

    let mut pairs: Vec<_> = scores <- iter$ <- collect$
    pairs <- sort$                        // a HashMap has no order; sort to print

    for (key, value) in pairs:
        println! "{key}: {value}"

10
Blue: 10
Yellow: 50

HashMap is not in the prelude, so use std.collections.HashMap first. insert takes a key and a value; get takes a reference to a key — (&team_name), isolated because of the & — and returns Option<&V>. The chain <- copied$ <- unwrap_or 0 turns Option<&i32> into i32 with a default. Iterating with for (key, value) in &scores works, in an order that is deliberately arbitrary: a hash map has no order, and here the pairs are sorted first so the output is stable.

Ownership and keys

Insert moves what it is given:

use std.collections.HashMap

fn main$:
    let field_name = String.from "Favorite color"
    let field_value = String.from "Blue"
    let mut map = HashMap.new$

    map <- insert field_name field_value      // both moved into the map
    println! "{:?}" map
    println! "{field_name}"                   // no longer valid

error[E0382]: borrow of moved value: `field_name`
  --> map_own.hrs:10:16
   |
 4 |     let field_name = String.from "Favorite color"
   |         ---------- move occurs because `field_name` has type `String`, which does not implement the `Copy` trait
 8 |     map <- insert field_name field_value      // both moved into the map
   |                   ---------- value moved here
10 |     println! "{field_name}"                   // no longer valid
   |                ^^^^^^^^^^ value borrowed here after move
   = help: consider cloning the value if the performance cost is acceptable (hrs 8:29)

field_name and field_value are Strings, so insert takes ownership of both and the map owns them from then on. For a Copy type — an i32 key — a copy goes in and the variable is untouched. For a reference — &str keys — the map holds the reference, and the borrow checker ensures the text outlives the map.

Updating

Inserting under an existing key overwrites; sometimes that is not what you want:

use std.collections.HashMap

fn main$:
    let mut scores = HashMap.new$
    scores <- insert (String.from "Blue") 10
    scores <- insert (String.from "Blue") 25     // overwrite
    println! "{:?}" (scores <- get "Blue")
    scores <- entry (String.from "Yellow") <- or_insert 50   // insert if absent
    scores <- entry (String.from "Blue") <- or_insert 50     // leave the 25 alone
    println! "{:?} {:?}" (scores <- get "Blue") (scores <- get "Yellow")

Some(25)
Some(25) Some(50)

entry is the answer: scores <- entry key is a handle to the slot for that key, filled or not, and or_insert 50 fills it if it is empty and returns a mutable reference to whatever is there either way. So the Yellow line inserts and the Blue line does nothing, and the 25 survives. That returned reference is what makes entry the idiom for counting:

use std.collections.HashMap

fn main$:
    let text = "hello world wonderful world"
    let mut map = HashMap.new$

    for word in text <- split_whitespace$:
        let count = map <- entry word <- or_insert 0
        *count += 1

    let mut pairs: Vec<_> = map <- iter$ <- collect$
    pairs <- sort$
    println! "{pairs:?}"

[("hello", 1), ("wonderful", 1), ("world", 2)]

let count = map <- entry word <- or_insert 0 gives count a &mut i32 — zero if the word is new — and *count += 1 increments it through the reference. Three lines, no lookup-then-insert, no Option to unwrap. The words are &str slices of text, so the map borrows text rather than copying it; text lives to the end of main, so the borrow is fine. The pairs are collected and sorted only to print them in a fixed order.

8.4 What you have

Vec<T>: Vec.new$ or vec! a b c, push, &v[i] to panic or get i for an Option, for x in &v and &mut v with *x to write, and an enum when the elements differ. String: UTF-8 bytes, push_str/push, + moves its left side and format! moves nothing, no indexing, byte-range slices, chars$ or bytes$. HashMap<K, V>: insert moves, get takes &key and returns an Option, entry … or_insert for insert-or-update, no order.

Next: error handling — panic! for the bugs, Result for everything else, and the ? operator that makes the second bearable.

9. Error handling

Rust has two kinds of error and refuses to blur them. An unrecoverable error is a bug — an index past the end, an invariant broken — and the program panics: it prints a message and stops. A recoverable error is an event the program should expect — a file that is not there, text that is not a number — and it is a value, of type Result<T, E>, which the caller has to look at. There are no exceptions, and no error can be silently ignored, because an ignored Result is an unused value the compiler warns about and an unhandled one does not type-check. This chapter is the two kinds, the ? operator that makes the recoverable kind pleasant, and the judgement of which to use.

9.1 Unrecoverable errors with panic!

You can panic on purpose:

fn main$:
    println! "about to fail"
    panic! "crash and burn"

about to fail
thread 'main' (16627) panicked at panic.hrs:4:
crash and burn

The program printed its first line, reached panic!, printed the message with the file and line, and exited. That is the whole mechanism. By default the panic unwinds: it walks back up the stack dropping every value on the way, so files close and memory is freed, and then the process ends. (A backtrace — the chain of calls that led here — is available with RUST_BACKTRACE=1 in the environment; the book leaves it off.)

Most panics are not written; they are hit:

fn main$:
    let v = vec! 1 2 3
    v[99]                           // the value is discarded; the index still runs
    ()

thread 'main' (16643) panicked at panic_index.hrs:4:
index out of bounds: the len is 3 but the index is 99

Chapter 8's index rule, seen from the other side. In C this reads whatever happens to be at that address — a buffer over-read, the root of a large fraction of security holes. Rust checks, and panics, and the panic is not the bug: the index was. The panic is the report.

9.2 Recoverable errors with Result

Opening a file can fail for reasons that are nobody's bug. So File.open returns a Result:

enum Result<T, E>
    Ok T
    Err E

Ok carries the value when the operation worked, Err the error when it did not, and the caller takes it apart with match, exactly as it would an Option:

use std.fs.File

fn main$:
    let greeting_file_result = File.open "hello.txt"

    let greeting_file =
        match greeting_file_result\
            Ok file => file
            Err error => panic! "Problem opening the file: {error:?}"

    let _ = greeting_file

thread 'main' (16659) panicked at result_match.hrs:10:
Problem opening the file: Os { code: 2, kind: NotFound, message: "No such file or directory" }

There is no hello.txt, so the Err arm ran and the program panicked with the error inside it. This is a recoverable error handled by choosing not to recover — which is fine for a program that cannot do anything without the file — and the point is that the choice was made in the code, visibly, rather than by the runtime.

Matching on the kind of error

An io.Error says what went wrong, and a program can act on that:

use std.fs.File
use std.io.ErrorKind

fn main$:
    let greeting_file =
        match File.open "hello.txt"\
            Ok file => file
            Err error => match error <- kind$\
                ErrorKind.NotFound => match File.create "hello.txt"\
                    Ok fc => fc
                    Err e => panic! "Problem creating the file: {e:?}"
                _ => panic! "Problem opening the file: {error:?}"

    println!
        "{:?}"
        (greeting_file <- metadata$ <- map (|m| m <- is_file$))
    std.fs.remove_file "hello.txt" <- unwrap$

Ok(true)

error <- kind$ is an ErrorKind, an enum: on NotFound, create the file; on anything else, panic. Three matches nested, one inside the arm of the last — each => match … : opens its arms on the lines beneath, and the layout keeps them apart where braces would have been a thicket. (The last line deletes the file the example created, so the book stays tidy.)

unwrap and expect

match on every Result is verbose, and there are two shortcuts for "give me the value or panic":

use std.fs.File

fn main$:
    let f = File.open "hello.txt" <- unwrap$
    let _ = f

thread 'main' (16691) panicked at unwrap_expect.hrs:5:
called `Result::unwrap()` on an `Err` value: Os { code: 2, kind: NotFound, message: "No such file or directory" }

unwrap$ is the match above with a generic message. expect is the same with your message:

use std.fs.File

fn main$:
    let f =
        File.open "hello.txt"
            <- expect "hello.txt should be included in this project"

    let _ = f

thread 'main' (16707) panicked at expect.hrs:7:
hello.txt should be included in this project: Os { code: 2, kind: NotFound, message: "No such file or directory" }

Prefer expect: when it fires, the message says what you were assuming, and that is what you need to know first. Both are right when the Err case really cannot happen — a literal that you know parses — or in a quick program where stopping is the correct response. In library code they are a smell, since the library does not know what the caller wants done.

Propagating errors

The usual answer is that the function that hit the error is not the one that knows what to do about it; it should hand the error up. That is propagating, and written by hand it looks like this:

use std.fs.File
use std.io.(self, Read)

fn read_username_from_file$ -> Result<String, io.Error>:
    let username_file_result = File.open "hello.txt"

    let mut username_file =
        match username_file_result\
            Ok file => file
            Err e => return Err e

    let mut username = String.new$

    match username_file <- read_to_string (&mut username)\
        Ok _ => Ok username
        Err e => Err e

fn main$:
    println!
        "{:?}"
        (read_username_from_file$ <- map_err (|e| e <- kind$))

Err(NotFound)

The function returns Result<String, io.Error>; each step that can fail is matched, and on Err the function returns it. The caller then decides. This is correct and it is half match; Rust has an operator for it.

The ? operator

? after a Result means: if it is Ok, give me the value; if it is Err, return it from this function right now.

use std.fs.File
use std.io.(self, Read)

fn read_username_from_file$ -> Result<String, io.Error>:
    let mut username = String.new$
    File.open "hello.txt"? <- read_to_string (&mut username)?
    Ok username

fn main$:
    println!
        "{:?}"
        (read_username_from_file$ <- map_err (|e| e <- kind$))

Err(NotFound)

The same function in three lines. File.open "hello.txt"? is the file or an early return; <- read_to_string (&mut username)? likewise. The ? binds tighter than <-, as it does in Rust, so it applies to the open before the chain continues — and the chain runs across the ?, which reads naturally once you see it as "open, if that worked read into username, if that worked carry on". ? also converts the error on the way out, through the From trait: a function returning Result<_, MyError> can use ? on any error that MyError knows how to be made from, and chapter 10 shows From.

? works on Option too, returning None early:

fn last_char_of_first_line text: &str -> Option<char>:
    text <- lines$
         <- next$?
         <- chars$
         <- last$

fn main$:
    println!
        "{:?}"
        (last_char_of_first_line "Hello, world\nHow are you today?")
    println! "{:?}" (last_char_of_first_line "")
    println! "{:?}" (last_char_of_first_line "\nhi")

Some('d')
None
None

text <- lines$ <- next$? is the first line, or None if there are no lines; then <- chars$ <- last$ is the last character of it, or None if the line is empty. Two ways to have nothing, one expression. What ? cannot do is mix: a ? on an Option inside a function returning Result is an error, and the other way round. Convert first.

? can only be used in a function whose return type it fits — which means not in a main that returns nothing:

use std.fs.File

fn main$:
    let greeting_file = File.open "hello.txt"?
    let _ = greeting_file

error[E0277]: the `?` operator can only be used in a function that returns `Result` or `Option` (or another type that implements `FromResidual`)
  --> question_in_main.hrs:4:46
   |
 3 | fn main$:
   | -------- this function should return `Result` or `Option` to accept `?`
 4 |     let greeting_file = File.open "hello.txt"?
   |                                              ^ cannot use the `?` operator in a function that returns `()`
   = help: consider adding return type (hrs 3:9)

The compiler says exactly what is missing: main returns (), and ? needs somewhere to send the error. main may return a Result:

use std.error.Error
use std.fs.File

fn main$ -> Result<(), Box<dyn Error>>:
    let greeting_file = File.open "hello.txt"
    println! "opened: {}" (greeting_file <- is_ok$)

    let n: i32 = "42" <- parse$?
    println! "{n}"
    Ok ()

opened: false
42

fn main$ -> Result<(), Box<dyn Error>>: — a main that either succeeds with nothing or fails with some error. Box<dyn Error> is "any error at all", a trait object (chapter 21) that ? can convert any error into, so this main can use ? on a file operation and a parse in the same body. Ok () at the end is the success value — () is the unit value, and it is passed to Ok as an ordinary argument. If main returns an Err, the program prints it and exits with a nonzero code, which is what a shell expects of a failed program.

9.3 To panic or not

The rule of thumb: panic when the program has reached a state it was not written to be in — a bug — and return a Result when the failure is something the caller can be expected to handle. A few sharper edges of that rule:

• In examples, prototypes and tests, unwrap and expect are fine; a Result that you handle carefully in a ten-line demo obscures the demo. In tests, a panic is how a test fails.
• When you have information the compiler does not — you know the literal parses, you know the index is in range because you just checked the length — expect with a message saying why is the honest spelling.
• When the failure is expected in normal operation — a missing file, bad input, a network that is down — it is a Result, and the type signature is the documentation that it can happen.
• When a function's contract is broken — it was called with an argument it documented as invalid — panic. The caller has a bug, and continuing would spread it.

That last point is what types are for, and a type can carry a check so that no caller has to repeat it:

pub struct Guess
    value: i32

impl Guess
    pub fn new value: i32 -> Guess:
        if value < 1 || value > 100:
            panic! "Guess value must be between 1 and 100, got {value}."

        Guess\ value

    pub fn value (&self) -> i32:
        self <- value

fn main$:
    let g = Guess.new 50
    println! "{}" (g <- value$)

    let bad = Guess.new 200
    println! "{}" (bad <- value$)

50
thread 'main' (16801) panicked at guess_validate.hrs:9:
Guess value must be between 1 and 100, got 200.

Guess.new checks the range once; value is private, so a Guess cannot be made any other way; every function that takes a Guess can therefore trust it without checking. Making an invalid state impossible to construct is the strongest form of error handling, because the error has nowhere to occur.

9.4 What you have

panic! for bugs; a panic unwinds, prints, and stops. Result<T, E> for failures the caller should handle: match it, unwrap$ or expect "why" to panic on Err, or ? to return it up — on Result or Option, in any function whose return type it fits, including a main that returns Result<(), Box<dyn Error>>. Choose by asking whether the failure is the program's fault or the world's, and let a type's constructor make the invalid states unreachable.

Next: generics, traits and lifetimes — the three mechanisms by which one piece of code serves many types, and the chapter where the lifetime error from chapter 4 finally gets its answer.

10. Generic types, traits and lifetimes

Three mechanisms let one piece of code serve many types, and this chapter is all three. Generics are placeholders for types: a Vec<T> is one definition that is a vector of anything. Traits say what a type can do, so a generic function can require it: "any T that can be compared". And lifetimes are generics over how long a reference is valid, which is the question chapter 4 left open. They arrive together because they are used together, and because the last of them is the one people fear, unnecessarily, so it is best met right after the first two make the shape familiar.

10.1 Generics

Removing duplication

Two functions that differ only in a type:

fn largest_i32 list: &[i32] -> &i32:
    let mut largest = &list[0]

    for item in list:
        if item > largest:
            largest = item

    largest

fn largest_char list: &[char] -> &char:
    let mut largest = &list[0]

    for item in list:
        if item > largest:
            largest = item

    largest

fn main$:
    println! "{}" (largest_i32 (&[34, 50, 25, 100, 65]))
    println! "{}" (largest_char (&['y', 'm', 'a', 'q']))

100
y

Same body, twice, for i32 and for char, and there would be a third for f64. The duplication is in the type, so the fix is a parameter for the type:

fn largest<T> list: &[T] -> &T:
    let mut largest = &list[0]

    for item in list:
        if item > largest:
            largest = item

    largest

fn main$:
    println! "{}" (largest (&[34, 50, 25, 100, 65]))

error[E0369]: binary operation `>` cannot be applied to type `&T`
  --> largest_generic_err.hrs:5:17
   |
 5 |         if item > largest:
   |            ---- &T
   |                 ^
   |                   ------- &T
   = help: consider restricting type parameter `T` with trait `PartialOrd` (hrs 1:13)

fn largest<T> list: &[T] -> &T — the <T> after the name declares a type parameter, and then T is used where the type would be. It does not compile, and the error is the chapter's first lesson: > is not defined for every type, so the compiler will not let a function that takes any T compare two of them. It has to be told which Ts are allowed, and the help says how: restrict the type parameter.

fn largest<T: PartialOrd> list: &[T] -> &T:
    let mut largest = &list[0]

    for item in list:
        if item > largest:
            largest = item

    largest

fn main$:
    println! "{}" (largest (&[34, 50, 25, 100, 65]))
    println! "{}" (largest (&['y', 'm', 'a', 'q']))

100
y

<T: PartialOrd> — T may be any type that implements the trait PartialOrd, which is the trait that provides >. Now the body may compare, and the function works for i32 and char and anything else that can be ordered, with one definition. Generics in Rust are checked at the definition, not at each use: a generic function has to make sense for every type its bounds allow, which is why the unbounded version was rejected and why, once it compiles, no call can break it. (At compile time each use is monomorphized — a copy is generated per concrete type — so there is no runtime cost for the abstraction.)

Generic structs and methods

A struct's fields can be generic too:

#[derive Debug]
struct Point<T>
    x: T
    y: T

impl<T> Point<T>
    fn x (&self) -> &T:
        &self <- x

impl Point<f32>
    fn distance_from_origin (&self) -> f32:
        (self <- x <- powi 2 + self <- y <- powi 2) <- sqrt$

#[derive Debug]
struct Mixed<T, U>
    x: T
    y: U

fn main$:
    let integer = Point\ x = 5, y = 10
    let float = Point\ x = 1.0, y = 4.0
    println! "{:?} {:?} {}" integer float (integer <- x$)
    println! "{}" (float <- distance_from_origin$)

    let m = Mixed\ x = 5, y = 4.0
    println! "{m:?}"

Point { x: 5, y: 10 } Point { x: 1.0, y: 4.0 } 5
4.1231055
Mixed { x: 5, y: 4.0 }

struct Point<T> with fields of type T; Point\ x = 5, y = 10 is a Point<i32> and Point\ x = 1.0, y = 4.0 a Point<f64>, inferred. Methods on a generic type are declared in impl<T> Point<T>: — the <T> after impl says this block is generic over T — and a method for one specific type is impl Point<f32>:, so distance_from_origin exists only on Point<f32>. When two fields may differ in type, two parameters, Mixed<T, U>.

Both fields of Point<T> are the same T, and the compiler holds you to it:

struct Point<T>
    x: T
    y: T

fn main$:
    let wont_work = Point\ x = 5, y = 4.0
    let _ = wont_work

error[E0308]: mismatched types
  --> generic_mismatch.hrs:6:39
   |
 6 |     let wont_work = Point\ x = 5, y = 4.0
   |                                       ^^^ expected integer, found floating-point number

10.2 Traits

A trait is a set of methods a type may implement — an interface, a protocol, whichever word your last language used. It is defined with trait, and a type implements it with impl … for:

pub trait Summary
    fn summarize (&self) -> String

pub struct NewsArticle
    pub headline: String
    pub location: String
    pub author: String

impl Summary for NewsArticle
    fn summarize (&self) -> String:
        format!
            "{}, by {} ({})"
            (self <- headline)
            (self <- author)
            (self <- location)

pub struct Tweet
    pub username: String
    pub content: String

impl Summary for Tweet
    fn summarize (&self) -> String:
        format! "{}: {}" (self <- username) (self <- content)

fn main$:
    let tweet =
        Tweet\
            username = String.from "horse_ebooks"
            content = String.from "of course, as you probably already know, people"
    println! "1 new tweet: {}" (tweet <- summarize$)

    let article =
        NewsArticle\
            headline = String.from "Penguins win the Stanley Cup Championship!"
            location = String.from "Pittsburgh, PA, USA"
            author = String.from "Iceburgh"
    println! "New article available! {}" (article <- summarize$)

1 new tweet: horse_ebooks: of course, as you probably already know, people
New article available! Penguins win the Stanley Cup Championship!, by Iceburgh (Pittsburgh, PA, USA)

pub trait Summary: declares one method by its signature, fn summarize (&self) -> String, with no body — that line ends at the return type. impl Summary for NewsArticle: gives the body for one type, impl Summary for Tweet: for another, and after that tweet <- summarize$ and article <- summarize$ are ordinary method calls. The trait is what makes the two types interchangeable to any code that only needs summarize.

One rule to know: you may implement a trait for a type only if the trait or the type is defined in your crate. Summary for Vec<T> — fine, Summary is yours; Display for Tweet — fine, Tweet is yours; Display for Vec<T> — not allowed, since both belong to someone else and two crates could disagree. It is called the orphan rule and it is what keeps trait implementations unambiguous across the whole ecosystem.

Default implementations

A trait method may have a body, used by any type that does not supply its own:

pub trait Summary
    fn summarize_author (&self) -> String

    fn summarize (&self) -> String:
        format! "(Read more from {}...)" (self <- summarize_author$)

pub struct Tweet
    pub username: String
    pub content: String

impl Summary for Tweet
    fn summarize_author (&self) -> String:
        format! "@{}" (self <- username)

fn main$:
    let tweet =
        Tweet\
            username = String.from "horse_ebooks"
            content = String.from "of course, as you probably already know, people"
    println! "1 new tweet: {}" (tweet <- summarize$)

1 new tweet: (Read more from @horse_ebooks...)

summarize has a default that calls summarize_author, which has none; Tweet implements only the required one and gets the other free. A default may call the required methods, which is how a trait can offer a lot of behaviour and demand a little.

Traits as parameters

A function that takes "anything summarizable" has four spellings, all in this example:

use std.fmt.Display

pub trait Summary
    fn summarize (&self) -> String

pub struct Tweet
    pub username: String

impl Summary for Tweet
    fn summarize (&self) -> String:
        format! "@{}" (self <- username)

impl Display for Tweet
    fn fmt (&self) (f: &mut std.fmt.Formatter) -> std.fmt.Result:
        write! f "tweet by {}" (self <- username)

// `impl Trait` in a parameter: any type that implements Summary

pub fn notify item: &impl Summary:
    println! "Breaking news! {}" (item <- summarize$)

// The same, spelled out as a bound on a type parameter
pub fn notify2<T: Summary> item: &T:
    println! "Breaking news! {}" (item <- summarize$)

// Two bounds with `+`
pub fn notify3 item: &(impl Summary + Display):
    println! "{item} — {}" (item <- summarize$)

// A `where` clause, for when the bounds get long
pub fn notify4<T> item: &T
    [where T: Summary + Display]:
    println! "{item} — {}" (item <- summarize$)

fn main$:
    let t = Tweet\ username = String.from "horse_ebooks"
    notify (&t)
    notify2 (&t)
    notify3 (&t)
    notify4 (&t)

Breaking news! @horse_ebooks
Breaking news! @horse_ebooks
tweet by horse_ebooks — @horse_ebooks
tweet by horse_ebooks — @horse_ebooks

item: &impl Summary is the short form: a reference to some type that implements Summary. notify2<T: Summary> item: &T is the same thing with the type parameter named, which you need when two parameters must be the same type, or the name is used elsewhere. &(impl Summary + Display) requires two traits — + joins bounds, and the group is parenthesised so the + cannot be read as part of the parameter. And [where T: Summary + Display] moves the bounds out of the signature to a line of their own, which is what you do when they get long. The brackets are Harsh's: a where bound has a : in it, and the brackets keep that colon from opening a block; they are stripped on the way out.

Tweet also implements Display here, by writing fmt — that is the trait behind {}, the one chapter 5's error said Rectangle lacked. write! f "…" args writes into the formatter, and the method's two groups are (&self) and (f: &mut std.fmt.Formatter).

Harsh — A where clause on one line needs nothing: fn f<T> (x: T) -> T where T: Clone:. Over several lines it is written in brackets, [where T: Summary + Display] on its own line under the signature, because a bound's : would otherwise be read as opening a block; the brackets keep the clause part of the header and are not emitted, and the body indents as it would without them.

Returning a trait

impl Trait works in return position too:

pub trait Summary
    fn summarize (&self) -> String

pub struct Tweet
    pub username: String

impl Summary for Tweet
    fn summarize (&self) -> String:
        format! "@{}" (self <- username)

fn returns_summarizable$ -> impl Summary:
    Tweet\ username = String.from "horse_ebooks"

fn main$:
    println! "{}" (returns_summarizable$ <- summarize$)

@horse_ebooks

"This function returns some type that implements Summary" — the caller can call summarize$ and nothing else. Useful when the concrete type is long or unnameable (closures and iterators, chapter 13). One limit: the function must return one concrete type; a function that returns a Tweet on one branch and a NewsArticle on another cannot use impl Summary, and needs a trait object (chapter 21).

Conditional methods

A method can exist only when the type parameter meets a bound:

use std.fmt.Display

struct Pair<T>
    x: T
    y: T

impl<T> Pair<T>
    fn new (x: T) (y: T) -> Self:
        Self\ x, y

// Only a Pair whose T can be compared and displayed gets this method.

impl<T: Display + PartialOrd> Pair<T>
    fn cmp_display (&self):
        if self <- x >= self <- y:
            println! "The largest member is x = {}" (self <- x)
        else:
            println! "The largest member is y = {}" (self <- y)

fn main$:
    let p = Pair.new 3 7
    p <- cmp_display$

    // `to_string` exists on every type that implements Display — a blanket impl in std.
    let s: String = 42 <- to_string$
    println! "{s}"

The largest member is y = 7
42

impl<T> Pair<T>: gives every Pair a new; impl<T: Display + PartialOrd> Pair<T>: gives cmp_display only to pairs whose elements can be compared and printed. The standard library uses the same device on a larger scale: impl<T: Display> ToString for T implements ToString for every type that implements Display, which is why 42 <- to_string$ works — a blanket implementation, and a large part of why traits compose.

10.3 Lifetimes

Every reference has a lifetime: the region of the program during which it is valid. Usually the compiler works it out and you write nothing — every & so far had a lifetime you never saw. It has to be written only when the compiler cannot tell how the lifetimes of several references relate, and the classic case is a function that returns one of two borrowed arguments:

fn longest (x: &str) (y: &str) -> &str:
    if x <- len$ > y <- len$: x else: y

fn main$:
    println! "{}" (longest "abcd" "xyz")

error[E0106]: missing lifetime specifier
  --> longest_err.hrs:1:35
   |
 1 | fn longest (x: &str) (y: &str) -> &str:
   |                ----
   |                          ----
   |                                   ^ expected named lifetime parameter
   = help: this function's return type contains a borrowed value, but the signature does not say whether it is borrowed from `x` or `y`
   = help: consider introducing a named lifetime parameter (hrs 1:12)

Read the help: the return type is a borrowed value, and the signature does not say whether it is borrowed from x or from y. The compiler needs to know, because the caller's borrow checker needs to know how long the returned reference may be used — as long as x lives, as long as y lives, or only as long as both do. The signature has to say. The syntax for saying it is a lifetime parameter:

fn longest<'a> (x: &'a str) (y: &'a str) -> &'a str:
    if x <- len$ > y <- len$: x else: y

fn main$:
    let string1 = String.from "abcd"
    let string2 = "xyz"
    let result = longest (string1 <- as_str$) string2
    println! "The longest string is {result}"

The longest string is abcd

fn longest<'a> (x: &'a str) (y: &'a str) -> &'a str — 'a is declared after the name like a type parameter (the apostrophe marks it as a lifetime), and then &'a str means "a reference with lifetime 'a". Putting the same 'a on both inputs and the output says: the returned reference lives as long as the shorter of the two inputs. That is the whole meaning. Lifetime annotations do not change how long anything lives; they describe the relationship, so that the checker can verify calls against it.

And it does verify:

fn longest<'a> (x: &'a str) (y: &'a str) -> &'a str:
    if x <- len$ > y <- len$: x else: y

fn main$:
    let string1 = String.from "long string is long"
    let result

    do:
        let string2 = String.from "xyz"
        result = longest (string1 <- as_str$) (string2 <- as_str$)

    println! "The longest string is {result}"

error[E0597]: `string2` does not live long enough
  --> longest_scope.hrs:10:48
   |
 9 |         let string2 = String.from "xyz"
   |             ------- binding `string2` declared here
10 |         result = longest (string1 <- as_str$) (string2 <- as_str$)
   |                                                ^^^^^^^ borrowed value does not live long enough
12 |     println! "The longest string is {result}"
   |     - `string2` dropped here while still borrowed
   |                                      ------ borrow later used here

string2 lives only inside the do: block; result is used after it; and longest's signature says result cannot outlive the shorter of its inputs. So the compiler rejects the program, and — this is the part to appreciate — it does so at the call, from the signature alone, without looking inside longest. That is what the annotation bought: a function's borrowing behaviour is part of its interface, checked at each use.

Lifetimes in structs

Chapter 5's &str field had this error. A struct that holds a reference declares a lifetime, and the struct cannot outlive what it borrows:

#[derive Debug]
struct ImportantExcerpt<'a>
    part: &'a str

impl<'a> ImportantExcerpt<'a>
    fn level (&self) -> i32:
        3

    fn announce_and_return_part (&self) (announcement: &str) -> &str:
        println! "Attention please: {announcement}"
        self <- part

fn main$:
    let novel = String.from "Call me Ishmael. Some years ago..."
    let first_sentence =
        novel <- split '.'
              <- next$
              <- expect "Could not find a '.'"
    let i = ImportantExcerpt\ part = first_sentence

    println! "{i:?} {}" (i <- level$)
    println! "{}" (i <- announce_and_return_part "hi")

ImportantExcerpt { part: "Call me Ishmael" } 3
Attention please: hi
Call me Ishmael

struct ImportantExcerpt<'a> with part: &'a str means an ImportantExcerpt is valid only while the text it points into is. impl<'a> ImportantExcerpt<'a>: declares the lifetime for the methods, which then mostly do not mention it — level takes &self and returns an i32; announce_and_return_part returns a &str whose lifetime the compiler works out from &self, by the rules below.

Elision

If every reference needed a written lifetime the language would be unusable, so three rules fill them in when they can, and you write one only when they cannot:

// One input lifetime: the output gets it. Written out, this is
// fn first_word<'a> s: &'a str -> &'a str.
fn first_word s: &str -> &str:
    let bytes = s <- as_bytes$

    for (i, &item) in bytes <- iter$ <- enumerate$:
        if item == b' ':
            return &s[0..i]

    &s[..]

// A reference that lives for the whole program.
static GREETING: &'static str = "I have a static lifetime."

fn main$:
    println! "{}" (first_word "hello world")
    println! "{GREETING}"

hello
I have a static lifetime.

1. Each reference parameter gets its own lifetime.
2. If there is exactly one input lifetime, the output gets it — which is why chapter 4's first_word s: &str -> &str needed nothing.
3. If one of the inputs is &self, the output gets self's lifetime — which is why announce_and_return_part needed nothing.

longest had two inputs and no self, so no rule applied and the signature had to say. That is the entire theory of when you write lifetimes. 'static is the one named lifetime you will see in the wild: the whole program, which every string literal has, since the text lives in the binary.

All three at once

use std.fmt.Display

fn longest_with_an_announcement<'a, T> (x: &'a str) (y: &'a str) (ann: T) -> &'a str
    [where T: Display]:
    println! "Announcement! {ann}"
    if x <- len$ > y <- len$: x else: y

fn main$:
    println! "{}" (longest_with_an_announcement "abcd" "xyz" "today")

Announcement! today
abcd

A lifetime, a type parameter, a bound in a [where …] clause, and three parameters: everything in this chapter in one signature, and nothing in it is new.

10.4 What you have

<T> after a name makes a function, struct or impl generic; T: Trait restricts it, and the body may only do what the bounds allow. trait declares methods, with or without defaults; impl Trait for Type supplies them; &impl Trait, T: Trait, +, and [where …] take them as parameters and impl Trait returns one. The orphan rule keeps implementations unambiguous. A lifetime 'a names how long a reference is valid, is written only when elision's three rules cannot fill it in, and lets the checker verify each call from the signature alone.

Next: writing automated tests — which is the natural use of everything so far, and where panic is a feature.

11. Writing automated tests

The compiler checks a great deal — types, ownership, exhaustive matches — and none of it says whether add 2 2 is 4. That is what tests are for: functions that call your code and check what comes back, run by cargo test (or hrs test, which transpiles and then does the same), and reported. This chapter is how to write them, what the assertion macros do, and how to run some of them. Every example here is a test file, and the output shown is the test runner's report.

11.1 Anatomy of a test

A test is a function with #[test] above it. It passes if it returns, and fails if it panics:

pub fn add (left: u64) (right: u64) -> u64:
    left + right

#[cfg test]
mod tests
    use super.*

    #[test]
    fn it_works$:
        let result = add 2 2
        assert_eq! result 4

$ cargo test
running 1 test
test tests::it_works ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Everything after #[cfg test] is the conventional shape. mod tests: is an ordinary module; the attribute above it says compile this only when testing, so the tests cost nothing in the real build. use super.* brings the enclosing module's items — add — into the test module, which is a child and would otherwise see nothing. Then #[test] on a function makes it a test, and assert_eq! result 4 checks that its two arguments are equal, panicking with both values if they are not. The report names each test by its module path and tallies at the end.

Here is what failure looks like:

#[cfg test]
mod tests
    #[test]
    fn exploration$:
        assert_eq! (2 + 2) 4

    #[test]
    fn another$:
        panic! "Make this test fail"

$ cargo test
running 2 tests
test tests::another ... FAILED
test tests::exploration ... ok
failures:
---- tests::another stdout ----
thread 'tests::another' (17083) panicked at failing.hrs:11:
Make this test fail
failures:
    tests::another
test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out

another panicked, so it failed; the runner prints each failing test's output and message under failures:, then the tally. One failure fails the run — cargo test exits nonzero — which is what a build pipeline wants.

11.2 The assertion macros

assert! takes something that must be true: