Rust for Humans

Rust is worth learning, but most resources explain it like you already know it. This one doesn’t. It’s built for the person who reads a chapter, feels like they get it, then forgets half of it three days later. (That’s normal. It’s how brains work. This site is designed to fight it.)

How to use this site

You learn and remember by doing, not by reading. So every lesson gives you four ways to make it stick:

1. Read the idea, slowly. Each topic is explained in plain English first — the why before the how. No wall of jargon.

2. Run the code. Every code box has a ▶ Run button. It runs real Rust in your browser. Don’t just read it — change it, break it, run it again. Seeing the compiler yell at you (and then fixing it) is how the rules move from “I read that” to “I know that.”

   fn main() {
       let name = "you";
       println!("Hello, {name}! Try changing this line and press Run.");
   }

3. Do the “Your turn” exercise. A small broken program you have to fix. If you can fix it, you understood it. If you can’t, the lesson above has the answer.

4. Take the quick check. A couple of questions at the end of each lesson. Getting them wrong is useful — the explanation tells you exactly what you missed.

Then, whenever you feel Rust slipping away, open the Review & flashcards page. It reshuffles the key questions from everything you’ve learned and shows the ones you marked “shaky” first. Ten minutes there beats rereading a whole chapter.

The path

The lessons are ordered so each one builds on the last. Start at the top of the sidebar and work down:

• Start here — install Rust, run your first program, read compiler errors without panicking.
• Language basics — variables, types, functions, structs, enums, pattern matching.
• Ownership — the part that feels hard at first and then makes everything else click.
• Abstractions — traits, generics, iterators, closures, error handling.
• Runtime & ecosystem — testing, concurrency, async, and the tools you use every day.

You don’t have to rush. Do one lesson, run every example, take the quiz. Come back tomorrow and do the next one. Slow and sticky beats fast and forgotten.

Ready? Open Rust at a glance.

Rust at a glance

Beginner · Start here

What & why

Before you learn any language, it helps to know what it’s for and what shape it has — a map before the streets. This page is that map. It tells you what Rust is good at, the one big idea that makes it different, and the order to learn things in so you don’t get lost. Read it once, don’t try to memorize it, and come back whenever you feel unsure where you are.

The idea, slowly

Rust is a language for writing programs that need to be fast and not crash. That’s the whole pitch. Big companies use it for web servers, command-line tools, game engines, operating systems, and parts of your browser. But you don’t need to build any of that. You just need to know why people reach for Rust, because that “why” explains every strange thing the language will ask of you.

The trade every language makes

Every programming language has to answer one hard question: who cleans up the memory?

When your program makes a value — a piece of text, a list of numbers, an image — the computer sets aside some memory to hold it. When you’re done with that value, the memory has to be handed back, or your program slowly eats the whole machine. There are three classic ways to handle this:

• The garbage collector way (Python, JavaScript, Java, Go). A hidden helper runs in the background, notices when you’re done with things, and cleans up for you. Comfortable — but it pauses your program at random moments and costs speed.
• The do-it-yourself way (C, C++). You clean up by hand. Total control and blazing speed — but forget once, clean up twice, or use a value after cleaning it, and you get crashes and security holes. This is where a huge share of real-world bugs come from.
• The Rust way. You don’t clean up by hand, and there’s no background helper. Instead the compiler reads your code before it ever runs and works out exactly when each value is finished. If your code is unsafe, it refuses to build and tells you why.

That third path is the entire personality of Rust. You get the speed of the do-it-yourself way with the safety of the garbage-collected way. The price is that the compiler is strict, and while you’re learning it will say “no” a lot. That’s not the compiler being mean. Think of it as a very careful coworker reading over your shoulder, catching bugs at your desk instead of letting them reach real users at 2am.

“Explicit by default” — what that means for you

Rust likes you to say what you mean. It rarely does surprising things behind your back. A tiny example:

fn main() {
    println!("Rust is explicit by default");
}

That prints one line. Nothing hidden, nothing magic. As lessons go on you’ll notice Rust makes you spell things out — whether a value can change, who owns it, what type it is when it’s unclear. It feels like extra typing at first. The payoff is that when you read Rust code later, it tells you the truth about what it does. There are far fewer “wait, how did that happen?” moments.

The one idea to fear (a little) and then love

If you remember only one word from this whole page, remember ownership. It’s Rust’s rule for who is responsible for each value and when it gets cleaned up. Ownership is why the “who cleans up memory?” question gets answered for free. It’s also the thing that confuses every beginner for a few days and then suddenly clicks, after which the rest of the language makes sense. You have a whole lesson on it later. For now just know: it’s coming, it’s the heart of Rust, and struggling with it at first is completely normal.

The order that won’t overwhelm you

Rust is a big language, but you learn a small useful slice first and grow from there. A sane path:

1. Get set up — install the tools, print “Hello, world”, learn to read the compiler’s error messages (that last skill is worth gold).
2. Language basics — variables, types, functions, if/match, loops. This is the ordinary stuff every language has.
3. Ownership and borrowing — the Rust-specific core. Go slow here.
4. Everyday building blocks — structs, enums, and the standard library’s collections and strings.
5. The ecosystem — error handling, testing, and pulling in other people’s code.

Don’t jump ahead to macros, unsafe, or async on day one. Those are advanced rooms in the house; you’ll find the doors when you’re ready.

Common mistakes

• Trying to learn everything at once. Rust has a lot of surface area, and the docs are thorough to a fault. If you read the whole official book in one sitting you’ll drown. The map above exists so you can learn one slice, use it, and only then move on.
• Starting with the hard, flashy features. Macros (the ! things), unsafe, and async look powerful and get talked about a lot online. They are not where you begin. Beginners who start there get discouraged fast. Orient with this page, then go to install and ownership.
• Reading a compiler “no” as failure. When Rust rejects your code it’s doing its job — catching a bug before it ships. The error message usually contains the fix. Treat red text as help, not punishment.

More examples

Spot the safety net

In a scripting or garbage-collected language, handing a value to a new home while still holding onto the original name is completely normal. Rust asks first — and refuses to build code that tries it.

fn main() {
    let ticket = String::from("boarding-pass-482");
    let queue = vec![ticket];       // ticket's value moves into the vector
    println!("Printing: {ticket}"); // ERROR: `ticket` was already moved
    println!("Queue: {:?}", queue);
}

A systems mindset vs. a scripting mindset

A scripting language lets you write total = sum([19.99, 4.50, 12.00]) without a second thought. Rust wants the types settled before it builds anything at all — that upfront precision is what “systems language” buys you.

fn main() {
    let prices: [f64; 3] = [19.99, 4.50, 12.00];
    let total: f64 = prices.iter().sum();
    println!("Cart total: ${total:.2}");
}

Let Cargo run the whole project

You clone someone else’s Rust project and just want to try it, without first learning how its build is wired together.

cargo run

No silent number conversions

Your quantity comes from a small counter type and your price from a bigger currency type — Rust won’t quietly mix them for you, so the conversion has to show up in the code.

fn main() {
    let quantity: u8 = 200;
    let price_cents: u32 = 350;
    let total_cents = quantity as u32 * price_cents;
    println!("Total: {} cents", total_cents);
}

Errors as values, not exceptions

Some of your input will be messy — a form field, a config line, a CSV column — and instead of an exception that can crash the program if nobody catches it, Rust hands you back a value you’re required to look at.

fn main() {
    let entries = vec!["3", "7", "oops", "12"];
    for text in entries {
        match text.parse::<i32>() {
            Ok(n) => println!("{n} is a valid number"),
            Err(_) => println!("'{text}' is not a number -- no crash, just a value"),
        }
    }
}

Your turn

You can’t really “break” a map, so here’s a hands-on task instead. Run the program below as-is and read the output. Then change the text inside the quotes to your own sentence — maybe why you want to learn Rust — and run it again. Notice that nothing surprising happens: what you typed is exactly what prints. That predictability is the point.

fn main() {
    println!("Rust is explicit by default");
}

fn main() {
    println!("I am learning Rust so my programs are fast and never crash.");
}

Quick check

Remember this

• Rust exists to make programs that are both fast and safe from memory bugs, with no garbage collector.
• The compiler checks your code before it runs and refuses to build unsafe code — strictness now saves crashes later.
• Ownership is the core idea that makes everything else make sense; it’s coming in a later lesson.
• Rust is explicit by default — it rarely does hidden things, so code tells you the truth.
• Learn in slices: setup → basics → ownership → structs/enums → ecosystem. Skip macros and unsafe for now.

Go deeper

• The Rust Book — Start with the official learning path.
• Rust by Example — Short runnable examples.

Next:

• Install Rust
• Cargo basics
• Ownership

Install Rust

Beginner · Start here

What & why

Before you can run a single line of Rust on your own machine, you need the tools installed. The good news: there’s one official installer that sets up everything and keeps it updated, so you don’t have to hunt down pieces. This lesson walks you through it slowly and shows you how to check that it worked.

The idea, slowly

To write Rust locally you need three things, and they come as a bundle:

• rustc — the compiler. It turns your Rust code into a program the computer can run.
• cargo — the project manager. You’ll actually type cargo far more than rustc. It builds, runs, tests, and pulls in other people’s code. (It has its own lesson next.)
• rustup — the installer and updater. It installs rustc and cargo, and later keeps them up to date.

Think of rustup as the app store, and rustc + cargo as the apps it installs and keeps current. You install rustup once; after that it manages the rest.

Why one installer instead of your system’s package manager

You might be tempted to run something like apt install rustc on Linux, or grab Rust from Homebrew. It usually works for a day and then hurts. Distro packages are often old, they’re hard to update on Rust’s fast release cycle, and they can’t easily switch between the stable, beta, and nightly versions of Rust. rustup is the official tool built exactly for this job. Use it unless you have a specific, known reason not to.

Installing it

Go to rustup.rs in your browser. It shows you the exact command for your operating system.

On macOS or Linux it’s a single line you paste into your terminal:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

On Windows, rustup.rs gives you a small installer to download and double-click (you’ll also want the Visual Studio C++ build tools, which the installer points you to). Either way, when it asks you to choose an option, just press Enter for the standard default install. The defaults are the right choice for beginners.

While it runs, here’s what the installer is “thinking”: download rustup, then use it to download the current stable compiler and cargo, then add them to your PATH so your terminal can find them. That last part — PATH — is the one that trips people up, so read the next section.

Making your terminal find the tools

After installing, the tools live in a folder like ~/.cargo/bin. Your terminal only runs commands it can find on its PATH (a list of folders it searches). The installer adds that folder to your PATH — but a terminal window that was already open won’t notice the change.

The fix is simple: close your terminal and open a new one (or run source "$HOME/.cargo/env"). This is the single most common “I installed it but nothing works” cause. If a command isn’t found, restart the terminal first, before you assume anything is actually broken.

Checking that it worked

Open a fresh terminal and run these three commands:

rustc --version
cargo --version
rustup --version

Each should print a version number, something like rustc 1.XX.0. If you see three version lines, you’re done — the compiler, the project manager, and the updater are all installed and reachable.

Keeping it current

Rust ships a new stable version roughly every six weeks. Updating is one command:

rustup update

That’s rustup doing its “app store” job: fetch the latest stable rustc and cargo and swap them in. Run it now and then; you don’t need to babysit it.

Common mistakes

• Installing from a distro package or Homebrew “because it’s easier.” You often get an old version that’s a pain to update and can’t switch toolchains. When a tutorial assumes a recent Rust and yours is ancient, you’ll waste an afternoon confused. Use rustup from rustup.rs.
• “Command not found” right after installing. This almost always means your open terminal hasn’t picked up the new PATH yet. Close it and open a new one (or source "$HOME/.cargo/env") before you start debugging. Restart first, panic later.
• Skipping the version check. If you don’t run rustc --version and cargo --version, you won’t know whether the install actually took until something fails mid-lesson. Confirm up front — it takes five seconds.
• On Windows, missing the C++ build tools. Rust needs a linker. The rustup installer tells you if you’re missing the Visual Studio build tools; follow its prompt rather than ignoring it, or builds will fail with a confusing linker error.

More examples

Checking exactly what’s installed

You’re on a new machine, or picking up a teammate’s laptop, and want to know if clippy or the WebAssembly target is already there before you rely on it.

rustup component list --installed

Adding a target so you can cross-compile

You’re building a CLI tool on your Mac but need to hand a binary to a colleague running Linux, or deploy it straight to a Linux server.

rustup target add x86_64-unknown-linux-gnu

Pinning one project to an older toolchain

A client’s codebase was written against an older Rust release, and upgrading it isn’t your call today — you don’t want to change your global default just for this one folder.

rustup override set 1.75.0

Refreshing a single component

rustfmt starts misbehaving after an OS update, but reinstalling your whole toolchain to fix one small piece feels like overkill.

rustup component remove rustfmt
rustup component add rustfmt

Seeing what’s active at a glance

You installed a nightly toolchain months ago to try one feature, and now you’re not sure which toolchain actually runs when you type cargo build.

rustup show

Your turn

This lesson has no code to fix — the exercise is to actually install and verify. Do this now:

1. Go to rustup.rs and run the command it gives you for your OS, accepting the standard defaults.
2. Close your terminal and open a brand-new one.
3. Run the three checks below.

rustc --version
cargo --version
rustup --version

rustc 1.79.0 (129f3b996 2024-06-10)
cargo 1.79.0 (ffa9cf99a 2024-06-03)
rustup 1.27.1 (54dd3d00f 2024-04-24)

Quick check

Remember this

• Install with rustup from rustup.rs; accept the standard defaults.
• rustup manages rustc (the compiler) and cargo (the project manager) and keeps them updated.
• After installing, open a new terminal so PATH updates — this fixes most “command not found” cases.
• Confirm with rustc --version and cargo --version; both should print version numbers.
• Update anytime with rustup update. Prefer rustup over distro/Homebrew packages.

Go deeper

• rustup — Official installer.
• Cargo Book - Getting Started — What Cargo expects from the toolchain.

Next:

• Cargo basics
• Hello, world

Cargo basics

Beginner · Start here

What & why

Cargo is the tool you’ll type more than any other in Rust. It starts new projects, builds them, runs them, runs your tests, and downloads code from other people. Learn a handful of Cargo commands now and you’ll have the everyday workflow that carries you through the whole rest of Rust. This is the practical center of your day-to-day.

The idea, slowly

You could compile Rust by calling rustc on a single file by hand. Almost nobody does. Real projects have many files, need outside libraries, want tests, and have to be built the same way on everyone’s machine. Cargo handles all of that so you don’t have to think about it. One tool, one set of commands, every project the same shape.

Making a new project

To start a project:

cargo new hello-rust
cd hello-rust

cargo new hello-rust builds a folder named hello-rust with everything a Rust project needs already in place. Here’s what it “thinks” it should give you:

hello-rust/
├── Cargo.toml       <- the project's settings and dependency list
└── src/
    └── main.rs      <- your code starts here

• src/main.rs is where your code lives. Cargo even fills it with a working “Hello, world” so the project runs immediately.
• Cargo.toml is the project’s ID card and shopping list. It holds the project’s name, its version, and — importantly — the list of outside libraries it depends on. (.toml is just a simple settings-file format; don’t worry about it beyond “this is where project settings live.”)

Building and running

From inside the project folder, the command you’ll use constantly:

cargo run

cargo run does two jobs in one: it builds your code (compiles it) and then runs the resulting program. On a brand-new project it prints Hello, world!. That single line main.rs looks like this:

fn main() {
    println!("Hello, world!");
}

If you only want to compile without running, use cargo build. If you only want to check that the code is valid without producing a finished program — which is faster — use cargo check. That last one is a beginner’s best friend: while you’re fixing compiler errors, cargo check gives you the same errors much quicker than a full build.

Debug builds vs release builds

By default Cargo builds a debug version: it compiles fast and keeps extra info to help you find bugs, but the program itself runs slower. When you want the fast, optimized version, add --release:

cargo build --release

For learning, plain cargo run (debug) is exactly what you want. Reach for --release only when you actually care about the program’s speed.

Adding someone else’s code (a dependency)

Rust’s real power shows up when you pull in libraries — called crates — that other people wrote. Say you want colored terminal text. From your project folder:

cargo add colored

cargo add writes a line into your Cargo.toml under [dependencies], and the next cargo run downloads and compiles that crate for you automatically. You can also edit Cargo.toml by hand; cargo add just does it for you safely. The huge public collection of crates lives at crates.io.

The lockfile: Cargo.lock

The first time you build, Cargo creates a file called Cargo.lock. It records the exact versions of every dependency it used. Its whole purpose is repeatability: with the lockfile, your project builds with the identical library versions on your laptop, your friend’s laptop, and a server — no “works on my machine” surprises. For an application (a program you run), commit Cargo.lock to git. You don’t edit it by hand; Cargo manages it.

The commands you’ll actually use daily

• cargo new <name> — start a project.
• cargo run — build and run it (your most-used command).
• cargo check — quickly verify it compiles, no finished program. Great while fixing errors.
• cargo build — compile it (--release for the fast, optimized version).
• cargo test — run your tests.
• cargo add <crate> — add a dependency.

That’s the core loop. Everything else you can look up when you need it.

Common mistakes

• Running Cargo from the wrong folder. Cargo commands work inside a project — the folder that has Cargo.toml. If you run cargo run and get an error about no manifest / Cargo.toml not found, you’re probably one folder too high. cd into the project first.
• Forgetting to cd after cargo new. cargo new hello-rust makes the folder but leaves you outside it. You must cd hello-rust before cargo run does anything.
• Reaching for cargo clean at the first weird error. cargo clean deletes all built files so the next build starts from scratch — slow, and rarely the actual fix. Stale-build problems are uncommon; read the real error first and only clean if you genuinely suspect leftover build junk.
• Not committing Cargo.lock for an application. Leave it out and different machines may pull different dependency versions, causing bugs that only appear “over there.” Commit it for apps so everyone builds the same thing.

More examples

Starting a library instead of an app

You’re writing a chunk of logic — say, date-parsing helpers — that other code will import, not something you run directly.

cargo new --lib date_utils

Adding a dependency and building it

Your project needs to read JSON, so you pull in a crate instead of writing a parser yourself.

cargo add serde_json
cargo build

Running just one test by name

Your test suite has grown to two hundred tests, but you’re only working on one function right now and don’t want to wait for all of them every time.

cargo test parses_positive_numbers

Fast feedback with cargo check

You’re mid-refactor, chasing compiler errors one at a time, and producing a full runnable binary after every tiny edit is wasted work.

cargo check

Running one binary out of several

Your project grew a src/bin/ folder with a couple of small helper programs alongside the main app, and you want to run just one of them.

cargo run --bin date_utils_cli

Your turn

No code to debug this time — the exercise is to run the real workflow and read what Cargo prints. In your terminal, do exactly this:

cargo new hello-rust
cd hello-rust
cargo run

Then open src/main.rs, change the text inside println! to a message of your own, and run cargo run again. Watch how the output changes.

   Compiling hello-rust v0.1.0 (/path/to/hello-rust)
    Finished dev [unoptimized + debuginfo] target(s) in 0.5s
     Running `target/debug/hello-rust`
Hello, world!

Quick check

Remember this

• cargo new <name> starts a project; then cd into it before running anything.
• cargo run builds and runs — it’s your most-used command.
• cargo check is a fast way to catch errors without a full build; great while fixing them.
• Dependencies (crates) are listed in Cargo.toml; add them with cargo add <crate> from crates.io.
• Cargo.lock pins exact dependency versions for repeatable builds — commit it for applications.

Go deeper

• Cargo Book — The full reference.
• Cargo manifest reference — How Cargo.toml is structured.

Next:

• Hello, world
• Modules and crates
• Testing

Hello, world

Beginner · Start here

What & why

Every language starts with a program that prints one line. In Rust that program teaches you the three pieces you’ll type in every program you ever write: an entry point, a macro call, and a statement. Get comfortable with these now and the rest of Rust has a lot less to be scared of.

The idea, slowly

Here is the whole program:

fn main() {
    println!("Hello, world!");
}

Let’s read it the way the compiler does, one piece at a time.

• fn main() — fn means “I’m defining a function.” main is a special name: when you run a Rust program, it starts at main. Always. If main isn’t there, there’s nothing to run. Think of main as the front door of your program — the computer walks in through it.
• () — the empty parentheses mean “this function takes no inputs.” Later your functions will take inputs and those go between the parentheses.
• { ... } — the curly braces hold the body: the list of things to do. Everything between { and } runs top to bottom.
• println!("Hello, world!") — this prints a line of text. println = “print line” (it adds a newline at the end for you). The text you want to print goes in the quotes.
• The ! — this is the surprising one. println! has an exclamation mark because it’s a macro, not a normal function. You don’t need to know how macros work yet. For now just remember: if you see ! after a name, it’s a macro, and println! is the one you’ll use constantly. Forgetting the ! is the #1 beginner error here.
• The ; — the semicolon ends the statement. It’s how you tell Rust “this instruction is finished, move to the next one.” Most lines inside { } end with ;.

That’s it. Front door (main), do one thing (println!), end the instruction (;).

Print more than one line

Each println! is its own instruction, running in order:

fn main() {
    println!("Learning Rust.");
    println!("One line at a time.");
}

Print a value with {}

The curly braces {} inside the text are a placeholder — Rust fills them in:

fn main() {
    let day = 3;
    println!("Day {} of learning Rust", day);
    // You can also name the value directly inside the braces:
    let name = "Shamirul";
    println!("Keep going, {name}!");
}

Don’t worry about let yet (that’s the next lesson). Just notice that {} is where a value gets dropped into your text.

Common mistakes

• Forgetting the !. println("hi") is wrong; println!("hi") is right. The compiler will say it can’t find a function named println — that’s your hint you dropped the !.
• Forgetting the ;. Rust will complain it “expected ;”. Add it at the end of the line.
• Mismatched quotes or braces. Every " needs a closing ", every { a closing }. The compiler points at the line where it got confused.

More examples

Printing to stderr for diagnostics

Real programs often split their output: the actual result goes to one stream, debug notes go to another, so a script piping your output doesn’t get polluted with noise.

fn main() {
    println!("Result: 42");
    eprintln!("[debug] computed via loop, took 3 steps");
}

A greeting with a hardcoded name

Setup scripts and installers love a little personal touch, even before you’ve learned how to take real input from a user.

fn main() {
    let user = "Alice";
    println!("Welcome aboard, {user}! Let's get you set up.");
}

Formatting a receipt line

A {} placeholder isn’t limited to printing a value back out untouched — you can drop in the result of a calculation too.

fn main() {
    let item = "coffee";
    let price = 4;
    let qty = 2;
    println!("{qty}x {item} = ${}", price * qty);
}

A startup banner

Command-line tools often print a little header before they get to work, so you know what’s running and that it actually started.

fn main() {
    println!("=================================");
    println!(" MyApp v1.0 -- starting up");
    println!("=================================");
}

A quick unit conversion

println! doubles as a fine one-off calculator display, long before you’ve learned functions or real user input.

fn main() {
    let celsius = 24;
    let fahrenheit = celsius * 9 / 5 + 32;
    println!("{celsius}C is {fahrenheit}F");
}

Your turn

This program is broken in two ways. Fix it so it prints Hello, Rust! on its own line. Press ▶ Run to check.

fn main() {
    println("Hello, Rust!")
}

fn main() {
    println!("Hello, Rust!");
}

Quick check

Remember this

• Executables start at fn main() — it’s the front door.
• ! means macro. println! is a macro, so it always has the !.
• Statements end with ;.
• {} inside a string is a placeholder that gets filled with a value.

Go deeper

• The Rust Book - Hello, world — The canonical first program.
• Rust by Example - Hello World — A second view of the same concept.

Next:

• Variables and mutability
• Functions

Reading compiler errors

Beginner · Start here

What & why

Rust’s compiler says “no” a lot, especially while you’re learning — and its error messages look like a wall of text with arrows and codes. Here’s the secret: those messages are some of the most helpful in all of programming. They point at the exact spot, explain the problem in English, and often hand you the fix. Learning to read them calmly is the single highest-value skill for a beginner. Get this and you stop being stuck.

The idea, slowly

When Rust rejects your code it’s not scolding you. It caught a bug at your desk instead of letting it reach real users. Every error is the compiler saying: “I found a problem here, and here’s what I think is wrong.” Your job is just to read what it tells you, in order, without panicking.

The anatomy of an error message

Let’s take a small broken program. This one moves a value and then tries to use it again (don’t worry about why that’s illegal yet — this lesson is about reading the message, not ownership):

fn main() {
    let name = String::from("Rust");
    let other = name;             // value moves out of `name` here
    println!("{}", name);         // ...and we try to use `name` anyway
}

Rust refuses to build it and prints something like this:

error[E0382]: borrow of moved value: `name`
 --> src/main.rs:4:20
  |
2 |     let name = String::from("Rust");
  |         ---- move occurs because `name` has type `String`, which does not implement the `Copy` trait
3 |     let other = name;
  |                 ---- value moved here
4 |     println!("{}", name);
  |                    ^^^^ value borrowed here after move

That looks like a lot. It isn’t. Read it in five pieces, top to bottom:

• error[E0382] — the headline. error means the build failed. E0382 is a searchable code; you can look it up (see below) for a fuller explanation.
• **borrow of moved value: name`` ** — the problem in plain English. Something used name after its value had moved away.
• --> src/main.rs:4:20 — the location. File src/main.rs, line 4, column 20. This is where Rust wants you to look first.
• The | diagram — the compiler quotes your own code and draws under it. The underlines matter:
  • ---- marks related spots — here, where the value was created and where it moved.
  • ^^^^ points at the exact thing that’s wrong — here, the name you tried to use too late.
• The notes — lines like “move occurs because name has type String, which does not implement the Copy trait.” This is the compiler explaining why, in words. It’s telling you String moves rather than copies.

Read like that, the message isn’t a wall — it’s a labeled diagram of exactly what happened.

Read the FIRST error first

When you have several errors, Rust prints them all. Start with the top one and fix only that. Often one real mistake — a missing bracket, a wrong name — confuses the compiler and produces a cascade of follow-on errors that aren’t really separate problems. Fix the first, rebuild, and watch a pile of the others vanish. Chasing the last error first usually wastes your time.

When the compiler hands you the fix

Rust frequently suggests an actual repair, marked help:. For example, a missing ! on println:

error[E0423]: expected function, found macro `println`
 --> src/main.rs:2:5
  |
2 |     println("hi");
  |     ^^^^^^^ not a function
  |
help: use `!` to invoke the macro
  |
2 |     println!("hi");
  |            +

See that help: line and the + showing where to add the !? When Rust suggests a change, try it first, before you start guessing. It’s right far more often than not. The fixed program compiles:

fn main() {
    println!("hi");
}

warning is not error

You’ll also see yellow warning messages. A warning means “this compiled and will run, but something looks off” — like a variable you created and never used. Your program still works. Warnings are worth cleaning up, but they won’t stop you. Only error blocks the build. Don’t confuse “I have warnings” with “it’s broken.”

Look up a code when you’re stuck

Every error[EXXXX] code is documented. In the terminal:

rustc --explain E0382

That prints a longer, example-filled explanation of that specific error. There’s also an online error index. Use these when the inline message isn’t enough — you’re not the first person to hit that code.

Common mistakes

• Panicking at the size of the message and not reading it. The text looks dense, so beginners skim or give up. But it’s structured — headline, location, diagram, why. Read it slowly, top to bottom, and it’s usually clear. The message almost always contains your answer.
• Fixing the last error first. One early mistake often spawns several later errors. If you fix the bottom one, you may be “fixing” a symptom of something above it. Always start at the first error and rebuild.
• Ignoring the help: suggestion and guessing instead. Rust’s suggested fix is right most of the time. Trying random changes before reading help: turns a 10-second fix into a 10-minute fight.
• Treating warnings like errors (or ignoring them forever). A warning still compiles and runs; don’t think your program is broken because you see yellow. But don’t let them pile up unread either — some warnings are pointing at real mistakes.
• Never using rustc --explain. When an inline message baffles you, the code has a fuller write-up one command away. Beginners forget it exists.

More examples

A type mismatch

You read a value from somewhere text-based — a web form, a config file, a CLI flag — and forget it arrives as text, not a number. Rust’s error[E0308]: mismatched types names the exact line and says plainly which type it expected.

fn main() {
    let count: i32 = "5"; // ERROR: expected `i32`, found `&str`
    println!("count = {count}");
}

A missing semicolon that blames the next line

Drop a ; after a let, and the error often points at the line after your mistake instead of the mistake itself — expected ;, found keyword let, aimed at line 3 even though line 2 is where the semicolon is missing.

fn main() {
    let price = 12
    let tax = 2;
    let total = price + tax;
    println!("total = {total}");
}

A borrow-checker error

You grab a reference into a vector, then try to grow the vector while that reference is still alive — something a language like C++ would quietly let you do, and quietly corrupt later.

fn main() {
    let mut scores = vec![1, 2, 3];
    let first = &scores[0];
    scores.push(4); // ERROR: cannot borrow `scores` as mutable...
    println!("{first}");
}

Wrong number of arguments

You add a parameter to a function mid-refactor and forget to update a call site somewhere else in the file — error[E0061] names the function and even suggests where to add the missing argument.

fn greet(name: &str, times: u32) {
    for _ in 0..times {
        println!("Hello, {name}!");
    }
}

fn main() {
    greet("Sam"); // ERROR: this function takes 2 arguments but 1 was supplied
}

An unused variable — a warning, not an error

Quick prototyping often leaves a variable you set up but never got around to using — the program still compiles and runs, it just gets a friendly nudge.

fn main() {
    let total = 42; // never used below -- Rust warns, but still runs
    println!("Program finished.");
}

Your turn

This program is broken, and if you press Run the compiler will complain. Read its message first — find the location it points to and the ^^^^ underline — then fix the code so it prints Score: 10.

fn main() {
    let score = 10
    println("Score: {}", score)
}

fn main() {
    let score = 10;
    println!("Score: {}", score);
}

Quick check

Remember this

• Error messages are structured: code → plain-English problem → location → code diagram → why. Read them top to bottom.
• The --> line is the location (file:line:column); ^^^^ points at the exact culprit.
• Fix the first error first, then rebuild — many later errors disappear on their own.
• When you see a help: suggestion, try it before guessing; it’s usually right.
• A warning still compiles and runs; only error stops the build.
• Stuck on a code? Run rustc --explain E0382 (with your code) for a fuller explanation.

Go deeper

• Rustc error index — Search specific compiler errors.
• Rust Book - Common Programming Concepts — Where many first errors appear.

Next:

• Variables and mutability
• Ownership

Variables and mutability

Beginner · Language basics

What & why

A variable is a name you give to a value so you can use it later. In most languages a variable can be changed whenever you like. Rust flips that default: once you name a value, it’s locked unless you explicitly ask for permission to change it. This one habit prevents a huge class of “wait, who changed this?” bugs, so it’s worth understanding early.

The idea, slowly

Naming a value with let

You create a variable with the keyword let:

fn main() {
    let name = "Rust";
    println!("Learning {name}");
}

Read let name = "Rust"; as “let the name name stand for the text Rust.” From now on, wherever you write name, Rust reads "Rust".

Notice you didn’t tell Rust that name is text. Rust figured it out from the value on the right. This is called type inference — the compiler is quietly thinking “the right-hand side is text, so name is text.” You’ll learn to add types by hand in the next lesson; for now, let Rust guess.

The surprise: variables don’t change by default

Try to change a variable and Rust stops you:

fn main() {
    let count = 1;
    count = 2;          // ERROR: cannot assign twice to immutable variable
    println!("{count}");
}

Press Run and read the error: “cannot assign twice to immutable variable count.” Immutable just means “cannot be changed.” By default, every let you write is immutable.

Why would a language do this? Think of it like writing a value in ink instead of pencil. If you know a value can never change, you can trust it everywhere. The compiler is on your side here: it’s saying “you told me count was 1, and now you’re changing it — did you mean to?”

Asking permission with mut

When you do want a value to change, add the word mut (short for “mutable,” meaning “changeable”):

fn main() {
    let mut count = 1;   // mut = "I plan to change this"
    count += 1;          // now allowed
    count += 1;
    println!("count is {count}"); // 3
}

let mut count tells both Rust and the next human who reads your code: “keep an eye on this one, it moves.” That little mut is a promise you make on purpose.

Shadowing: a new variable wearing the same name

There’s a second thing that looks like changing a value but isn’t. You can write let twice with the same name:

fn main() {
    let name = "Rust";
    let name = name.len();   // a brand-new variable, also called `name`
    println!("the name has {name} letters"); // 4
}

This is called shadowing. The second let name does not change the first one. It creates a completely new variable that happens to reuse the name name. The old one is still there underneath, just hidden (shadowed) — like a new sticky note stuck over an old one.

Here’s the part beginners love: because it’s a brand-new variable, its type can be different. The first name was text; the second name is a number (the length). You could never do that with mut, because mut changes a value in place and the type must stay the same.

So there are two different ideas:

• mut — same variable, value changes, type stays the same.
• Shadowing — new variable reusing the name, type may change.

Use mut when you’re genuinely updating one thing over time (a counter, a running total). Use shadowing when you want to transform a value into a new form and don’t need the old one anymore.

Constants (a quick mention)

If you have a value that’s fixed forever and known at compile time, you can use const instead of let. Constants are always written in SCREAMING_SNAKE_CASE and need a type:

const MAX_TRIES: u32 = 3;

fn main() {
    println!("You get {MAX_TRIES} tries");
}

You don’t need const often as a beginner. Just recognize it when you see it: “a name for a value that never, ever changes.”

Common mistakes

• Trying to reassign without mut. let x = 1; x = 2; fails with “cannot assign twice to immutable variable.” The fix is let mut x = 1;. This is the single most common early error, and the compiler even suggests adding mut.
• Thinking shadowing mutates the old value. It doesn’t. let x = 5; let x = x + 1; makes a new x. If you expected to see the old value somewhere else, you’ll be confused — nothing changed the first one, it’s just hidden.
• Adding mut you never use. If you write let mut x = 5; but never change x, Rust warns: “variable does not need to be mutable.” Drop the mut. It’s a hint that your intent and your code disagree.
• Confusing const and let. const needs an uppercase name and an explicit type, and can’t use mut. If you try const x = 5; you’ll get an error asking for the type.

More examples

Running total for a shopping cart

Ringing up items one at a time means the total genuinely changes as you go — a textbook job for mut.

fn main() {
    let mut cart_total = 0.0;
    cart_total += 12.99;
    cart_total += 4.50;
    cart_total += 7.25;
    println!("cart total: ${cart_total:.2}");
}

Shadowing to convert units step by step

User input arrives as text, but you need a number, and then you need it in a different unit. Shadowing lets you reuse one name as the value transforms.

fn main() {
    let temp = "98.6"; // raw input, as text
    let temp: f64 = temp.parse().unwrap(); // now a number
    let temp = (temp - 32.0) * 5.0 / 9.0;  // now Celsius
    println!("{temp:.1}C");
}

A const for app-wide config

Things like a retry limit or a max file size don’t change while the program runs, and every function that needs them should agree on the same value — that’s what const is for.

const MAX_LOGIN_ATTEMPTS: u32 = 3;

fn main() {
    let mut attempts = 0;
    while attempts < MAX_LOGIN_ATTEMPTS {
        attempts += 1;
        println!("attempt {attempts} of {MAX_LOGIN_ATTEMPTS}");
    }
    println!("locked out");
}

Why swapping needs a temporary variable

If you write a = b; b = a;, the first line already overwrote a, so the second line just copies b back into itself. You need somewhere to stash the original value first.

fn main() {
    let mut a = "left";
    let mut b = "right";

    let temp = a;   // hold a's value before it's overwritten
    a = b;
    b = temp;

    println!("a={a}, b={b}");
}

Shadowing only lasts inside its block

A shadowed name doesn’t leak out of the { } it was created in — once the block ends, the outer variable is back, untouched.

fn main() {
    let status = "pending";
    {
        let status = "approved"; // only shadows inside this block
        println!("inside: {status}");
    }
    println!("outside: {status}"); // original still stands
}

Your turn

This program wants to count up to 3, then relabel the result as a message. It’s broken in two places. Fix it so it prints the count going 1, 2, 3 and then a final line. Press ▶ Run.

fn main() {
    let total = 1;
    total += 1;
    total += 1;
    println!("total is {total}");

    let total = format!("final total: {total}");
    println!("{total}");
}

fn main() {
    let mut total = 1;
    total += 1;
    total += 1;
    println!("total is {total}");

    let total = format!("final total: {total}");
    println!("{total}");
}

Quick check

Remember this

• let names a value; by default that value is immutable (can’t be changed).
• Add mut when you genuinely need to reassign: let mut x = ....
• Shadowing (let x twice) makes a new variable with the same name — it can even change the type.
• mut = same variable changes in place; shadowing = new variable, old one hidden.
• Mutability is a deliberate choice you announce, not a free-for-all default.

Go deeper

• Rust Book - Variables and Mutability — Core syntax and examples.

Next:

• Data types
• Functions
• Control flow

Data types

Beginner · Language basics

What & why

Every value in Rust has a type — a label that says what kind of thing it is: a whole number, a decimal, a true/false, a piece of text. Rust cares deeply about types because knowing the shape of your data up front is how it catches mistakes before your program runs. The good news: most of the time Rust guesses the type for you, and you only spell it out when it asks.

The idea, slowly

Two big families: scalars and compounds

There are two families of built-in types:

• Scalar types hold one value: a number, a true/false, a single character.
• Compound types bundle several values together: tuples and arrays.

Let’s meet them slowly.

Numbers: integers and floats

An integer is a whole number — no decimal point. 5, -3, 1000. A float is a number with a decimal point — 3.14, -0.5.

Rust integers come with a size and a sign baked into the type name. Don’t panic, it’s a simple code:

• The letter i means signed (can be negative). The letter u means unsigned (zero or positive only).
• The number is how many bits it uses, which decides how big it can get: 8, 16, 32, 64.

So i32 is a signed 32-bit integer (the everyday default), u8 is an unsigned 8-bit integer (0 to 255), u64 is a big positive-only number, and so on.

fn main() {
    let age: u32 = 32;        // unsigned, can't be negative
    let temperature: i32 = -5; // signed, can be negative
    let pi = 3.14;            // no annotation → Rust picks f64 (a float)
    println!("{age}, {temperature}, {pi}");
}

If you don’t say which integer type you want, Rust defaults to i32. For decimals it defaults to f64. So you rarely need to write the type — let x = 5; just works and x is an i32.

Booleans and characters

A boolean (bool) is either true or false. That’s the whole type. It’s what if looks at.

A character (char) is a single letter, digit, or symbol, written in single quotes. Note: single quotes for one character, double quotes for text.

fn main() {
    let is_ready: bool = true;
    let grade: char = 'A';        // single quotes = one char
    let heart = '♥';              // even emoji-like symbols work
    println!("{is_ready}, {grade}, {heart}");
}

Tuples: a fixed group of possibly-different types

A tuple groups a fixed number of values, which can be different types, inside parentheses. Think of it as a tiny labeled box with a set number of slots.

fn main() {
    let point: (i32, i32) = (8, 13);
    let mixed = (500, 6.4, 'x');   // an integer, a float, a char

    // Get values out by position, starting at 0:
    println!("x is {}", point.0);
    println!("y is {}", point.1);

    // Or unpack all at once ("destructuring"):
    let (a, b, c) = mixed;
    println!("{a}, {b}, {c}");
}

You reach into a tuple with a dot and the position number: .0 is the first slot, .1 the second. A tuple’s size is fixed forever — a 2-tuple can never become a 3-tuple.

Arrays: many of the same type, fixed length

An array holds several values of the same type, and its length is fixed. It’s written in square brackets.

fn main() {
    let names = ["a", "b", "c"];        // 3 text values
    let zeros = [0; 5];                 // shorthand: five 0s → [0, 0, 0, 0, 0]

    println!("first: {}", names[0]);    // index into it with [ ]
    println!("how many: {}", names.len());
}

Two things to remember: every element must be the same type, and the length can’t grow or shrink. If you need a list that grows, you want a vector (Vec), which lives in the Collections lesson. Rule of thumb: fixed, known number of items → array; changing number of items → vector.

Type inference, and when you must help

Most of the time Rust reads the value and figures out the type. But sometimes it genuinely can’t decide and asks you to say. The classic case is parsing text into a number:

fn main() {
    let text = "42";
    let number: u32 = text.parse().unwrap();  // the : u32 tells parse what to make
    println!("{}", number + 1);
}

Without : u32, Rust wouldn’t know which number type to parse into, and would refuse to guess. The annotation is you stepping in to answer its question.

Common mistakes

• Mixing number types without converting. Rust won’t quietly add an i32 to a u8 for you. let a: i32 = 1; let b: u8 = 2; a + b fails with a “mismatched types” error. You must convert one, e.g. a + b as i32. Rust never does surprise conversions.
• Using double quotes for a char. 'A' is a char; "A" is text (a string). Swapping them gives a type error. Single quote = one character.
• Indexing past the end of an array. let a = [1, 2, 3]; a[5] compiles but panics (crashes) at runtime with “index out of bounds.” Arrays don’t stretch — the index must be within the length.
• Expecting an array to grow. Arrays are fixed length. If you try to “add” an item, there’s no method for it. Reach for a Vec instead when the size changes.
• Overflowing a small integer. A u8 maxes out at 255. Going past it panics in debug builds. Pick a type big enough for your values.

More examples

A tuple as a function’s multi-value return

When a function needs to hand back more than one related value — like an x/y offset — a tuple is the simplest way, no extra type required.

fn origin_offset() -> (i32, i32) {
    (3, -7)
}

fn main() {
    let (dx, dy) = origin_offset();
    println!("move right {dx}, up {dy}");
}

A fixed-size array of days

There are always exactly seven days in a week, so an array — not a growable list — is the right shape for this data.

fn main() {
    let days = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
    println!("day 3 is {}", days[2]);
    println!("week has {} days", days.len());
}

Combining u32 and i32 on purpose

Inventory counts are naturally unsigned, but a “returns” ledger can go negative. Mixing them means converting one side explicitly so both operands agree.

fn main() {
    let inventory: u32 = 40;
    let sold: i32 = -5; // sales returns can go negative in the ledger

    let total = inventory as i32 + sold; // convert explicitly, types must match
    println!("remaining: {total}");
}

A float precision surprise

Floats can’t represent every decimal exactly, so simple-looking arithmetic sometimes prints more digits than you expect. Rounding for display fixes the look, not the underlying value.

fn main() {
    let price = 0.1 + 0.2;
    println!("{price}");        // 0.30000000000000004
    println!("{:.2}", price);   // rounded for display: 0.30
}

A fixed array for pixel bytes

An image pixel always has exactly three color channels, and each one fits in a single byte — a perfect match for a small, same-typed, fixed-length array.

fn main() {
    let pixel: [u8; 3] = [255, 87, 51]; // R, G, B
    println!("red={}, green={}, blue={}", pixel[0], pixel[1], pixel[2]);
}

Your turn

This program mixes up its types in three places. Fix it so it compiles and prints the point and grade. Press ▶ Run.

fn main() {
    let grade: char = "A";
    let point: (i32, i32) = (8, 13, 21);
    let scores = [90, 85, "seventy"];

    println!("grade {grade}, point ({}, {})", point.0, point.1);
    println!("first score {}", scores[0]);
}

fn main() {
    let grade: char = 'A';
    let point: (i32, i32) = (8, 13);
    let scores = [90, 85, 70];

    println!("grade {grade}, point ({}, {})", point.0, point.1);
    println!("first score {}", scores[0]);
}

Quick check

Remember this

• Integers name their sign and size: i32 (signed) is the default, u32 is unsigned, u8/u64 are smaller/bigger.
• Decimals are floats; f64 is the default. Booleans are true/false. A char is one character in single quotes.
• Tuples group a fixed number of possibly-different types; reach in with .0, .1.
• Arrays hold many values of the same type at a fixed length; a growing list is a Vec instead.
• Rust infers types when it can, but you must annotate when it genuinely can’t decide (like parse).

Go deeper

• Rust Book - Data Types — Scalars and compound types.

Next:

• Functions
• Control flow
• Collections

Type conversion and casting

Beginner · Language basics

What & why

Rust never converts types behind your back. No language-level “42” + 1 silently becoming 43, no integer quietly widening into a float mid-expression. Every conversion is a decision you write down, and Rust gives you four different tools for four different situations: as for “just reinterpret these bits, I know what I’m doing,” From/Into for conversions that always succeed, TryFrom/TryInto for conversions that might fail, and FromStr for turning text into a typed value. Picking the right one is something you’ll do constantly, so it’s worth understanding what each one actually promises.

The idea, slowly

as: the no-questions-asked cast

as is a manual cast between primitive types. It always compiles, it never panics, and it never checks whether the result “makes sense” — it just reinterprets the bits according to fixed rules. Think of it like pouring water from a big jug into a small cup: Rust won’t stop you, it’ll just let the extra spill out.

fn main() {
    let big: i64 = 300;
    let small = big as u8; // u8 only holds 0..=255
    println!("{small}"); // 44
}

300 in binary is 1 0010 1100. A u8 only keeps the low 8 bits: 0010 1100, which is 44. That’s what “truncation” means for as — it’s not rounding or clamping, it’s chopping off the bits that don’t fit.

Casting a negative signed number to an unsigned type follows the same “keep the bit pattern” rule, which can be surprising:

fn main() {
    let n: i32 = -1;
    let u = n as u8;
    println!("{u}"); // 255
}

-1i32 is stored as all 1-bits (two’s complement). Keeping the low 8 bits gives 1111 1111, which as an unsigned u8 is 255 — not 0, not an error.

What the compiler is thinking: as is a promise from you, not a proof. The compiler checks that the cast is legal (you can’t as-cast a String to an i32), but it does zero checking on whether the value fits. That’s the whole point — it’s the fast, unchecked path.

Casting between integer widths

Going from a smaller type to a bigger one (widening) always preserves the value — for signed integers the sign bit is extended, for unsigned integers the top is filled with zeros. Going from bigger to smaller (narrowing) keeps only the low bits and can change the value entirely.

fn main() {
    let small: i16 = -5;
    let widened = small as i64; // sign-extended: still -5
    println!("{widened}");

    let n: i64 = 70_000;
    let narrowed = n as i16; // i16 only holds -32768..=32767
    println!("{narrowed}"); // 4464 — not 70000, and not an error
}

Float-to-int casts: truncation, and saturation at the edges

Casting a float to an integer with as truncates toward zero (it drops the fractional part, it doesn’t round):

fn main() {
    let x = 3.9_f64;
    println!("{}", x as i32); // 3, not 4

    let neg = -3.9_f64;
    println!("{}", neg as i32); // -3, not -4
}

What happens when the float is way out of range for the target integer? Rust saturates instead of producing garbage — the result clamps to the target type’s min or max:

fn main() {
    let huge = 1e20_f64;
    println!("{}", huge as i32); // i32::MAX (2147483647)

    let tiny = -1e20_f64;
    println!("{}", tiny as i32); // i32::MIN
}

From and Into: conversions that always succeed

From/Into are for conversions between richer types that can never fail — every input has a valid output. You implement From, and Rust hands you Into automatically: the standard library has a blanket implementation impl<T, U> Into<U> for T where U: From<T>, so writing one trait gives you both directions of API.

struct Feet(f64);
struct Meters(f64);

impl From<Feet> for Meters {
    fn from(f: Feet) -> Meters {
        Meters(f.0 * 0.3048)
    }
}

fn main() {
    let f = Feet(10.0);
    let m: Meters = Meters::from(f); // explicit direction
    println!("{:.2}", m.0);

    let f2 = Feet(10.0);
    let m2: Meters = f2.into(); // same conversion, via the free Into
    println!("{:.2}", m2.0);
}

Only implement From when the conversion is total — every possible Feet value must become a valid Meters value. If some inputs can’t be converted, From is the wrong trait.

TryFrom and TryInto: conversions that can fail

When a conversion might not be possible — like fitting a big number into a small integer type — reach for TryFrom/TryInto, which return a Result instead of an unconditional value:

use std::convert::TryFrom;

fn main() {
    let ok: i32 = 200;
    let too_big: i32 = 300;

    println!("{:?}", u8::try_from(ok));      // Ok(200)
    println!("{:?}", u8::try_from(too_big)); // Err(...) — 300 doesn't fit in a u8
}

Unlike as, u8::try_from(300) doesn’t silently wrap to 44 — it tells you the conversion was impossible and lets you decide what to do about it. This is the tool to reach for whenever an out-of-range value represents a real bug you want to catch, not a value you’re happy to truncate.

Parsing text with FromStr

Turning a string into a number (or any type that implements it) goes through the FromStr trait, called via .parse():

fn main() {
    let good: Result<i32, _> = "42".parse();
    let bad: Result<i32, _> = "abc".parse();

    println!("{good:?}"); // Ok(42)
    println!("{bad:?}");  // Err(ParseIntError { .. })

    let n: i32 = "42".parse().unwrap(); // target type inferred from the `let`
    println!("{n}");

    let m = "42".parse::<i32>().unwrap(); // or spell it out with turbofish
    println!("{m}");
}

.parse::<i32>() works because i32 implements FromStr — .parse() is really just calling FromStr::from_str for you. Since parsing text can always fail (the text might not be a valid number), it returns a Result, exactly like TryFrom.

Common mistakes

• Using as to shrink a value and being surprised later. as never panics and never warns — it truncates or wraps silently. If out-of-range input would be a bug, use TryFrom/TryInto instead.
• Assuming as clamps negative numbers to zero when casting to an unsigned type. It doesn’t — it reinterprets the bit pattern, so -1i32 as u8 is 255, not 0.
• Implementing From for a conversion that can actually fail. From promises the conversion always succeeds. If some inputs are invalid, implement TryFrom and return Err for them.
• Calling .unwrap() on .parse() or try_from() with untrusted input (user input, file contents, network data). That crashes the whole program on the first bad value instead of handling the error.

More examples

Parsing a CLI-style argument

Command-line arguments always arrive as text, even when they represent a number, so parsing with a fallback is the everyday pattern for reading them safely.

fn main() {
    let args = ["quantity", "12"];
    let quantity: i32 = args[1].parse().unwrap_or(0);
    println!("ordering {quantity} units");
}

Safely fitting a value into a pixel channel

A computed brightness value might come out too large for a single color channel, so TryFrom lets you check instead of silently corrupting the color.

use std::convert::TryFrom;

fn main() {
    let brightness: i32 = 240;
    match u8::try_from(brightness) {
        Ok(channel) => println!("pixel channel: {channel}"),
        Err(_) => println!("value doesn't fit in a byte"),
    }
}

Truncating a request ID into a small bucket

Hashing or bucketing schemes sometimes want the wraparound behavior of as — you’re deliberately keeping only the low bits to spread values across a fixed number of buckets.

fn main() {
    let request_id: u32 = 4_294_967_290; // near u32::MAX
    let bucket = request_id as u8; // wraps around, keeps only low 8 bits
    println!("bucket: {bucket}");
}

Turning an enum into its numeric score

Enums can carry an explicit numeric value, and as reads it back out — handy for things like priority levels you want to compare or sort.

enum Priority {
    Low = 1,
    Medium = 5,
    High = 10,
}

fn main() {
    let level = Priority::Medium as i32;
    println!("priority score: {level}");
}

From for a total, always-valid unit conversion

Minutes-to-seconds can never fail — every minute count has a valid seconds count — so this is exactly the kind of conversion From is meant for.

struct Seconds(u32);

impl From<u32> for Seconds {
    fn from(minutes: u32) -> Seconds {
        Seconds(minutes * 60)
    }
}

fn main() {
    let duration: Seconds = 5.into(); // 5 minutes -> seconds
    println!("{} seconds", duration.0);
}

Your turn

This function is supposed to clamp an i32 down into a u8, returning 0 for anything out of range. It doesn’t compile.

use std::convert::TryFrom;

fn to_byte(n: i32) -> u8 {
    u8::try_from(n) // forgot to handle the Result
}

fn main() {
    println!("{}", to_byte(50));
    println!("{}", to_byte(300));
}

use std::convert::TryFrom;

fn to_byte(n: i32) -> u8 {
    match u8::try_from(n) {
        Ok(b) => b,
        Err(_) => 0, // out of range: fall back instead of crashing
    }
}

fn main() {
    println!("{}", to_byte(50));  // 50
    println!("{}", to_byte(300)); // 0
}

Quick check

Remember this

• as casts numbers by keeping/extending bits — it always compiles, never panics, and can silently truncate or wrap.
• Widening (small type → big type) always preserves the value; narrowing (big type → small type) can change it.
• Float-to-int as casts truncate toward zero, and saturate to the target’s min/max instead of producing garbage for out-of-range floats.
• From/Into are for conversions that always succeed — implement From, and Into comes for free.
• TryFrom/TryInto return Result for conversions that can fail — reach for these when an out-of-range value is a real bug.
• "text".parse::<T>() converts a string into T via FromStr, returning Result<T, T::Err>.

Go deeper

• Rust Book - Type Conversions — as casting rules.
• std::convert docs — From, Into, TryFrom, TryInto.

Next:

• Formatting with format!
• Functions

Formatting with format!

Beginner · Language basics

What & why

Almost every program needs to turn data into text — a log line, an error message, a report. Rust doesn’t make you glue strings together with +; instead println!, format!, write!, and eprintln! all share one formatting mini-language, written inside {}. Learn that language once and you can print, build strings, log to stderr, and write into files with the same syntax.

The idea, slowly

The four macros: where the text goes

• println! — prints to stdout, with a trailing newline.
• print! — prints to stdout, no newline.
• eprintln! / eprint! — same, but to stderr (the channel for errors/logs, kept separate from normal output).
• format! — builds and returns a String instead of printing anything.
• write! / writeln! — write formatted text into anything that implements std::fmt::Write (like a String) or std::io::Write (like a file), returning a Result you’re expected to handle.

use std::fmt::Write;

fn main() {
    let name = "Ferris";

    println!("Hello, {name}!"); // stdout + newline
    print!("no newline here ");  // stays on the same line
    println!("<- still here");

    eprintln!("this goes to stderr, not stdout"); // for errors/logs

    let s = format!("{name} says hi"); // builds a String, prints nothing
    println!("{s}");

    let mut buf = String::new();
    write!(buf, "{name} again").unwrap(); // write! returns a Result — must be handled
    println!("{buf}");
}

{} (Display) vs {:?} / {:#?} (Debug)

{} uses the Display trait — clean, user-facing output. {:?} uses Debug — a developer-facing dump of a value’s structure, and {:#?} is the same thing “pretty-printed” across multiple lines. Most built-in types implement both; your own types get Debug for free with #[derive(Debug)], but Display has to be written by hand (more on that below).

#[derive(Debug)]
struct Point {
    x: i32,
    y: i32,
}

fn main() {
    let p = Point { x: 1, y: 2 };
    println!("{p:?}");  // Point { x: 1, y: 2 }
    println!("{p:#?}"); // pretty-printed across multiple lines

    let v = vec![1, 2, 3];
    println!("{v:?}"); // [1, 2, 3]

    // println!("{p}"); // ERROR: `Point` doesn't implement Display
}

What the compiler is thinking: {:?} isn’t “print whatever you can figure out” — it’s a real trait bound. If the type doesn’t implement Debug, {p:?} fails to compile, not fails silently at runtime. That’s why #[derive(Debug)] shows up on almost every struct in real code: it’s cheap insurance for the day you need to inspect a value.

Positional, named, and captured arguments

fn main() {
    println!("{} scored {}", "Alice", 90);          // positional, implicit order
    println!("{0} scored {1}, {0} wins", "Bob", 88); // explicit index, reused

    let name = "Ferris";
    let score = 100;
    println!("{name} scored {score}");                 // captures variables directly
    println!("{n} scored {s}", n = name, s = score);   // named arguments
}

Captured identifiers ({name}) only work for plain variable names already in scope — not expressions or field access like {player.score}. For those you still pass the value as a regular argument: println!("{}", player.score).

Format strings are checked at compile time: reference an argument that doesn’t exist, or write invalid syntax inside {}, and the build fails right there — it never becomes a runtime surprise.

Width, precision, alignment, and fill

Inside the braces, after a :, you can control exactly how a value is padded:

fn main() {
    let value = 3.14159;
    println!("[{value:>8.2}]"); // right-align, width 8, 2 decimals: [    3.14]
    println!("[{value:<8.2}]"); // left-align:                      [3.14    ]
    println!("[{value:^8.2}]"); // center-align:                    [  3.14  ]

    let n = 7;
    println!("{n:03}"); // zero-padded to width 3: 007

    println!("[{:*>10}]", "hi"); // fill char '*', right-align, width 10: [********hi]

    let long = "Hello, world!";
    println!("{long:.5}"); // precision on a string truncates it: Hello
}

The pattern is {value:fill align width.precision} — fill is the padding character (default space), align is < / > / ^ (left/right/center), width is the minimum total characters, and .precision means “decimal places” for floats but “max length” for strings.

Writing your own Display

Debug is mechanical and derived; Display is what you write by hand when you want your type to print the way an end user should see it:

use std::fmt;

struct Point {
    x: i32,
    y: i32,
}

impl fmt::Display for Point {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "({}, {})", self.x, self.y)
    }
}

fn main() {
    let p = Point { x: 3, y: 4 };
    println!("{p}"); // (3, 4) — via our Display impl
}

Inside fmt, you use write!(f, ...) — the same macro family, now writing into the formatter Rust gave you.

Common mistakes

• Printing Debug output where a user will see it. {:?} is for developers debugging; implement Display for anything a real user reads.
• Forgetting #[derive(Debug)]. {:?} on a type without it is a compile error (“the trait Debug is not implemented”), not a blank line at runtime.
• Dropping the Result from write!. write!/writeln! can fail (writing to a file, for instance), so Rust warns on an unused Result — call .unwrap(), handle it with ?, or .expect(...).
• Trying to format a field access or expression as a captured identifier, like {player.score} — only bare variable names can be captured; expressions must be passed as arguments.

More examples

Aligning a printed receipt

Left-aligning the item name and right-aligning the price inside a fixed width is what makes a loop of println! calls line up into neat columns instead of a ragged list.

fn main() {
    let items = [("Coffee", 4.50), ("Bagel", 3.25), ("Orange Juice", 2.75)];

    for (name, price) in items {
        println!("{name:<15}${price:>6.2}");
    }
}

Drawing a download progress bar

A fill character combined with left-alignment turns a plain string into a growing bar — the filled portion is real text, and the format spec pads the rest with - up to the target width.

fn main() {
    let percent = 65;
    let filled = "#".repeat((percent / 5) as usize);
    println!("[{:-<20}] {}%", filled, percent);
}

Printing a color as a CSS hex code

{:02X} formats a byte as two uppercase hex digits, zero-padded — string that together for red, green, and blue and you get exactly the #RRGGBB format a browser expects.

fn main() {
    let (r, g, b) = (255u8, 99u8, 71u8); // tomato red
    println!("#{:02X}{:02X}{:02X}", r, g, b);
}

A countdown timer’s own Display

Writing Display by hand lets Countdown decide it should always print as zero-padded MM:SS, no matter how the caller formats it — the conversion from raw seconds lives in one place.

use std::fmt;

struct Countdown {
    total_seconds: u32,
}

impl fmt::Display for Countdown {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        let minutes = self.total_seconds / 60;
        let seconds = self.total_seconds % 60;
        write!(f, "{:02}:{:02}", minutes, seconds)
    }
}

fn main() {
    let timer = Countdown { total_seconds: 125 };
    println!("time remaining: {}", timer);
}

Your turn

This program has two formatting mistakes. Find them before running it.

struct Player {
    name: String,
    score: u32,
}

fn main() {
    let p = Player { name: String::from("Ferris"), score: 42 };
    println!("{p}");
    println!("score: {p.score}");
}

use std::fmt;

struct Player {
    name: String,
    score: u32,
}

impl fmt::Display for Player {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "{} ({})", self.name, self.score)
    }
}

fn main() {
    let p = Player { name: String::from("Ferris"), score: 42 };
    println!("{p}");                // now uses our Display impl: Ferris (42)
    println!("score: {}", p.score); // field access passed as a normal argument
}

Quick check

Remember this

• println!/print! write to stdout, eprintln!/eprint! write to stderr, format! returns a String, write!/writeln! write into any fmt::Write/io::Write target.
• {} uses Display (user-facing); {:?}/{:#?} use Debug (developer-facing, derivable).
• Arguments can be positional ({}/{0}), named ({n = value}), or captured directly from a variable in scope ({name}) — but captures only work for plain identifiers, not expressions.
• {value:fill align width.precision} controls padding: alignment (</>/^), minimum width, and decimal places (floats) or max length (strings).
• Format strings are checked at compile time, so a typo in {} is a build failure, not a runtime bug.

Go deeper

• std::fmt docs — Full formatting syntax reference.

Next:

• Functions
• Derivable traits

Functions

Beginner · Language basics

What & why

A function is a named chunk of code you can run whenever you want, as many times as you want. Instead of copying the same ten lines everywhere, you put them in a function and call it by name. You’ve already met one function on day one: main. Now you’ll learn to write your own — to give them inputs and get answers back.

The idea, slowly

The shape of a function

Here’s a function that adds two numbers:

fn add(a: i32, b: i32) -> i32 {
    a + b
}

fn main() {
    let sum = add(2, 3);
    println!("sum is {sum}"); // 5
}

Let’s read the first line the way the compiler does:

• fn add — fn means “I’m defining a function,” and add is its name.
• (a: i32, b: i32) — these are the parameters: the inputs. Each one needs a name and a type. a is an i32, b is an i32. Rust never guesses parameter types — you must always write them.
• -> i32 — the arrow says “this function hands back an i32 when it’s done.” This is the return type. If a function returns nothing, you leave the arrow off entirely.
• { a + b } — the body. This function’s whole job is to compute a + b.

Then in main, add(2, 3) calls the function: it runs add with a = 2 and b = 3, and the answer comes back and lands in sum.

The big idea: expressions vs statements

This is the part that trips up newcomers, so go slow. Rust code is made of two things:

• A statement does something but produces no value. let x = 5; is a statement.
• An expression evaluates to a value. 2 + 3 is an expression — it becomes 5.

Look again at the body of add:

fn add(a: i32, b: i32) -> i32 {
    a + b       // no semicolon! this is the return value
}

fn main() {
    println!("{}", add(10, 20));
}

The last line is a + b with no semicolon. In Rust, the final expression in a function body — written without a semicolon — is what the function returns. There’s no return keyword needed. The compiler thinks: “the last thing here is a value, and the function promised to return a value, so that’s the answer.”

Now watch what a single semicolon does:

fn add(a: i32, b: i32) -> i32 {
    a + b;      // ERROR: the ; throws the value away
}

fn main() {
    println!("{}", add(1, 2));
}

Press Run. The error says something like “mismatched types: expected i32, found ().” That () (called “unit”) means “nothing.” By adding ; you turned the expression a + b into a statement — you computed the sum and then threw it away. The function now returns nothing, but you promised an i32. A trailing semicolon is the number-one function bug in Rust.

You can use return too

The no-semicolon style is the idiomatic Rust way, but return also works and is required when you want to leave early:

fn describe(n: i32) -> &'static str {
    if n < 0 {
        return "negative"; // leave early
    }
    "zero or positive"      // last expression, no semicolon
}

fn main() {
    println!("{}", describe(-4));
    println!("{}", describe(7));
}

Notice both styles appear here: an early return (with a semicolon, because it’s a statement) and the final expression without one. Both are hand back a value.

Functions that return nothing

If a function just does something (like printing) and has no answer to give, skip the arrow:

fn greet(name: &str) {
    println!("Hello, {name}!");   // just does a thing; returns nothing
}

fn main() {
    greet("Shaon");
    greet("Rust");
}

&str is the type for a borrowed piece of text — you’ll see it constantly. For now just read it as “some text.”

Order doesn’t matter

Unlike some languages, you can call a function that’s defined below where you call it. Rust reads the whole file before deciding, so main can call add even if add is written afterward. Arrange your code however reads best.

Common mistakes

• The trailing semicolon on the return value. fn f() -> i32 { x; } returns (), not x. The compiler says “expected i32, found ().” Remove the semicolon from the last line. This bites nearly everyone at first.
• Forgetting parameter types. fn add(a, b) won’t compile. Every parameter needs a type: fn add(a: i32, b: i32). Rust never infers these.
• Forgetting the return type. If your function hands back a value, you must declare it with -> Type. Without the arrow, Rust assumes the function returns nothing and complains when the body produces a value.
• Mismatched return type. If you say -> i32 but the last expression is text, you get “mismatched types.” The declared type and the actual returned value must agree.
• Adding ; after an if-expression you meant to return. fn f() -> i32 { if c { 1 } else { 2 }; } throws the value away. Drop the final ;.

More examples

A guard clause for a quick exit

When one condition makes the rest of the function pointless, return immediately instead of nesting everything else inside an else.

fn discount_price(price: f64, is_member: bool) -> f64 {
    if !is_member {
        return price; // guard clause: no discount, leave early
    }
    price * 0.9
}

fn main() {
    println!("{}", discount_price(100.0, false));
    println!("{}", discount_price(100.0, true));
}

Taking a slice instead of a Vec

Writing the parameter as &[i32] lets the function accept an array, a Vec, or any borrowed chunk of one — it doesn’t care how the caller stored the data.

fn average(scores: &[i32]) -> f64 {
    let sum: i32 = scores.iter().sum();
    sum as f64 / scores.len() as f64
}

fn main() {
    let quiz1 = [90, 85, 78];
    let quiz2 = vec![100, 95];
    println!("{:.1}", average(&quiz1)); // works on an array
    println!("{:.1}", average(&quiz2)); // and on a Vec
}

Returning several values as a tuple

Finding both the smallest and largest value in one pass means the function has two answers to hand back — a tuple lets it return them together.

fn min_max(values: &[i32]) -> (i32, i32) {
    let mut min = values[0];
    let mut max = values[0];
    for &v in values {
        if v < min { min = v; }
        if v > max { max = v; }
    }
    (min, max)
}

fn main() {
    let (lo, hi) = min_max(&[4, 9, 1, 7]);
    println!("low {lo}, high {hi}");
}

A recursive function

Factorial is naturally defined in terms of itself — 5! is 5 * 4! — so a function that calls itself is the most direct way to write it.

fn factorial(n: u64) -> u64 {
    if n == 0 {
        1
    } else {
        n * factorial(n - 1)
    }
}

fn main() {
    println!("5! = {}", factorial(5));
}

One function, reused everywhere the logic is needed

The moment you format a price in two places, you risk the two copies drifting apart. A function keeps the formatting rule in exactly one spot.

fn format_price(cents: u32) -> String {
    format!("${}.{:02}", cents / 100, cents % 100)
}

fn main() {
    let item = 1999;
    let tax = 160;
    println!("item: {}", format_price(item));
    println!("tax: {}", format_price(tax));
    println!("total: {}", format_price(item + tax));
}

Your turn

This function is meant to double a number and return it, but it doesn’t compile. Two things are wrong. Fix it. Press ▶ Run.

fn double(n) {
    n * 2;
}

fn main() {
    let result = double(21);
    println!("double is {result}");
}

fn double(n: i32) -> i32 {
    n * 2
}

fn main() {
    let result = double(21);
    println!("double is {result}"); // 42
}

Quick check

Remember this

• Define a function with fn name(params) -> ReturnType { body }.
• Every parameter needs a type; Rust never guesses them.
• The last expression with no semicolon is the return value — no return keyword needed.
• Adding a ; to that last line throws the value away and returns () (nothing) — a very common error.
• Use return to leave a function early; leave off -> Type when a function returns nothing.

Go deeper

• Rust Book - Functions — Basic function syntax.

Next:

• Control flow
• Methods and impl blocks

Control flow

Beginner · Language basics

What & why

Control flow is how your program makes decisions and repeats work: “if this is true, do that,” “keep doing this until done,” “for each item in the list, handle it.” Every useful program branches and loops. Rust’s versions are familiar if you’ve seen another language, with a couple of strict rules that will save you from bugs.

The idea, slowly

if needs a real boolean

An if runs a block only when a condition is true:

fn main() {
    let score = 81;

    if score >= 70 {
        println!("pass");
    } else {
        println!("retry");
    }
}

Here’s Rust’s first rule that surprises people coming from C or JavaScript: the condition must be an actual bool. Rust does not treat 0 as false or 1 as true. This won’t compile:

fn main() {
    let count = 3;
    if count {                 // ERROR: expected `bool`, found integer
        println!("nonzero");
    }
}

The compiler is thinking: “you gave me a number, but if only understands true/false.” Write the comparison you actually mean: if count != 0 { ... }. This forces you to be explicit, which prevents the classic “I meant to compare but wrote an assignment” family of bugs.

You can chain more conditions with else if:

fn main() {
    let n = 0;
    if n > 0 {
        println!("positive");
    } else if n < 0 {
        println!("negative");
    } else {
        println!("zero");
    }
}

if is an expression — it produces a value

In Rust, if doesn’t just do things; it can give back a value. That means you can put an if on the right of a let:

fn main() {
    let score = 81;
    let grade = if score >= 70 { "pass" } else { "retry" };
    println!("{grade}");
}

Read it as: “let grade be \"pass\" if the score is high enough, otherwise \"retry\".” Each branch is a little expression, and the whole if becomes whichever branch runs. One catch: both branches must produce the same type (here, both text). If one arm gave text and the other a number, Rust couldn’t decide what grade is, and would error.

Three ways to loop

Rust has three looping tools. Learn what each is for.

loop repeats forever until you break out. It’s the most basic:

fn main() {
    let mut n = 0;
    loop {
        n += 1;
        if n == 3 {
            break;      // jump out of the loop
        }
    }
    println!("stopped at {n}"); // 3
}

A neat trick: loop can return a value by putting it after break:

fn main() {
    let mut n = 0;
    let result = loop {
        n += 1;
        if n * n > 20 {
            break n;        // hand this value out of the loop
        }
    };
    println!("first n whose square passes 20 is {result}"); // 5
}

while repeats as long as a condition stays true. Use it when you don’t know how many times up front:

fn main() {
    let mut countdown = 3;
    while countdown > 0 {
        println!("{countdown}...");
        countdown -= 1;
    }
    println!("liftoff!");
}

for walks through each item of a collection. This is the one you’ll use most:

fn main() {
    for item in [10, 20, 30] {
        println!("{item}");
    }
}

To repeat a fixed number of times, loop over a range with ..:

fn main() {
    for i in 1..4 {          // 1, 2, 3 — the end (4) is NOT included
        println!("count {i}");
    }
}

Watch the range carefully: 1..4 gives 1, 2, 3 — the right side is excluded. If you want to include it, write 1..=4 (with the =), which gives 1, 2, 3, 4.

Why prefer for over manual indexing

You could loop by hand with a counter and index into an array, but it’s easy to get the bounds wrong and crash with “index out of bounds.” for item in list can never run off the end, because Rust hands you each item directly. Reach for for first; it’s safer and reads better.

Common mistakes

• Using a number as a condition. if count { } fails — Rust needs a bool. Write the comparison: if count != 0 { }. Same for while.
• Mismatched if branch types. When an if produces a value, every branch must return the same type. let x = if c { 1 } else { "no" }; errors because one arm is a number and the other is text.
• Off-by-one with ranges. 1..4 stops at 3, not 4. Forgetting the end is excluded leads to loops that run one time too few. Use 1..=4 when you want the last number included.
• break outside a loop. break only works inside loop, while, or for. Using it elsewhere is an error.
• Forgetting to change the while condition. If nothing inside the loop moves toward making the condition false, it runs forever. Make sure you update the variable the condition checks.

More examples

Searching until you find it, with break value

When you’re scanning for something, you often want the loop to hand back what it found, not just stop — break value does exactly that.

fn main() {
    let inventory = [3, 12, 47, 8, 47, 2];
    let mut i = 0;
    let position = loop {
        if inventory[i] == 47 {
            break i; // found it, hand back the index
        }
        i += 1;
    };
    println!("found at index {position}");
}

A labeled loop to escape two levels at once

Searching a grid means nesting a loop inside a loop. Once you find your target, a label lets you break out of both in one line instead of juggling a “found” flag.

fn main() {
    let grid = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
    let target = 5;

    'search: for row in grid {
        for cell in row {
            if cell == target {
                println!("found {target}!");
                break 'search; // stop both loops at once
            }
        }
    }
}

Draining a stack with while let

Popping items off a stack until it’s empty is a perfect fit for while let — it keeps going as long as pop() still hands back Some(value), and stops the instant it doesn’t.

fn main() {
    let mut undo_stack = vec!["type", "bold", "delete"];

    while let Some(action) = undo_stack.pop() {
        println!("undoing: {action}");
    }
    println!("nothing left to undo");
}

An if chain that picks a grade band

When there are more than two outcomes, chain else if and let the whole thing evaluate to a value — no separate variable needs reassigning afterward.

fn main() {
    let score = 84;

    let grade = if score >= 90 {
        "A"
    } else if score >= 80 {
        "B"
    } else if score >= 70 {
        "C"
    } else {
        "F"
    };
    println!("grade: {grade}");
}

Numbering items with enumerate

Printing a numbered list means pairing each item with its position. .iter().enumerate() hands you both at once, so you never have to track an index by hand.

fn main() {
    let playlist = ["Intro", "Chapter 1", "Chapter 2", "Outro"];

    for (i, track) in playlist.iter().enumerate() {
        println!("{}. {track}", i + 1);
    }
}

Your turn

This program should print pass or retry, then count 1, 2, 3. It has two problems. Fix it. Press ▶ Run.

fn main() {
    let score = 55;

    let grade = if score {
        "pass"
    } else {
        "retry"
    };
    println!("{grade}");

    for i in 1..3 {
        println!("count {i}");
    }
}

fn main() {
    let score = 55;

    let grade = if score >= 70 {
        "pass"
    } else {
        "retry"
    };
    println!("{grade}");

    for i in 1..=3 {
        println!("count {i}");
    }
}

Quick check

Remember this

• if/while conditions must be a real bool — Rust never treats numbers as true/false.
• if is an expression: it can produce a value, and all branches must share one type.
• loop runs forever until break (and break value can return a value); while runs while a condition holds; for walks a collection.
• Ranges: 1..4 excludes the end (1,2,3); 1..=4 includes it (1,2,3,4).
• Prefer for item in collection over manual indexing — it can’t run off the end.

Go deeper

• Rust Book - Control Flow — Conditionals and loops.

Next:

• Modules and crates
• Pattern matching

Comments and documentation

Beginner · Language basics

What & why

Comments are notes in your code that the compiler ignores — they’re for humans. Rust has two flavors: ordinary comments for quick notes to yourself, and doc comments, a special kind that Rust can gather up and turn into a browsable website of your API. Knowing which is which saves you from writing useless comments and helps you write the useful kind.

The idea, slowly

Ordinary comments with //

Anything after // on a line is a comment. Rust skips it entirely:

fn main() {
    // This is a note to myself. The compiler ignores it.
    let tries = 3; // you can also put a comment at the end of a line
    println!("{tries}");
}

Use these for anything: reminders, explanations, a “TODO” for later. There’s no special meaning — it’s just text the compiler throws away.

For a longer note across several lines, either start each line with //, or use the block form /* ... */:

fn main() {
    /* This is a block comment.
       It can span multiple lines
       without a // on each one. */
    println!("hello");
}

Most Rust code uses // even for multiple lines, but both work.

The real skill: comment the why, not the what

Beginners often write comments that just repeat the code:

fn main() {
    let x = 5; // set x to 5   <- useless, the code already says this
    println!("{x}");
}

That comment adds nothing — anyone can see x is 5. A good comment explains something the code can’t say: why you did it, a tricky edge case, a reason that isn’t obvious. Think of comments as answering “why is this here?” not “what does this line do?”

Doc comments with ///

Now the special kind. A comment starting with three slashes /// is a doc comment. It’s not just a note — it documents the item written right below it (a function, struct, and so on). Rust’s tool cargo doc reads these and generates a real HTML documentation website.

/// Returns the name of the currently active profile.
///
/// This is the text shown in the app's title bar.
pub fn profile_name() -> &'static str {
    "stable"
}

fn main() {
    println!("{}", profile_name());
}

Notice the doc comment sits above the function, on its own lines, outside any function body. It describes profile_name. When you run cargo doc --open, Rust builds a page for profile_name with that text as its description. This is exactly how the official Rust standard library docs are made — every description you read there came from a /// comment in the source.

The pub keyword means “public” — this function is part of your library’s public interface. Doc comments are most valuable on pub items, because those are the parts other people will actually look up.

Doc comments can hold example code that gets tested

Here’s a small piece of Rust magic. Code inside a doc comment’s example block is run as a test when you run cargo test. So your examples can never silently go stale:

/// Doubles a number.
///
/// # Examples
///
/// ```
/// let answer = my_crate::double(21);
/// assert_eq!(answer, 42);
/// ```
pub fn double(n: i32) -> i32 {
    n * 2
}

fn main() {
    println!("{}", double(21));
}

You don’t need to understand this fully yet. Just tuck away the idea: documentation examples are real, tested code, which is why Rust’s docs are so trustworthy.

A quick summary of the marks

• // — ordinary comment, for humans, one line.
• /* ... */ — ordinary comment, block form, can span lines.
• /// — doc comment, describes the item below it, feeds cargo doc.
• //! — doc comment that describes the thing it’s inside (a whole module or file) rather than what’s below it. You’ll see this at the very top of files. It’s the same idea, aimed inward.

Common mistakes

• Writing comments that repeat the code. let x = 5; // assign 5 to x wastes everyone’s time. Comment the reason, not the obvious mechanics.
• Using // when you meant ///. A two-slash comment above a function is just a private note — it will not show up in cargo doc. If you want generated documentation, you need three slashes.
• Putting a /// doc comment where there’s no item to document. A /// must sit directly above something it describes (a function, struct, etc.). Floating on its own with nothing below, or at the end of a line, it causes an error. For inner documentation use //! instead.
• Letting comments drift out of date. A comment that describes old behavior is worse than none, because it misleads. When you change code, check the comment above it.
• Over-commenting simple code. If a function is clear, it doesn’t need a paragraph. Save the words for the parts that genuinely need explaining.

More examples

A doc comment with a tested # Examples section

Showing a worked example right in the docs is one of the most useful things you can write — readers see real input and output without leaving the page.

/// Converts a Celsius temperature to Fahrenheit.
///
/// # Examples
///
/// ```
/// let f = temp::celsius_to_fahrenheit(0.0);
/// assert_eq!(f, 32.0);
/// ```
pub fn celsius_to_fahrenheit(c: f64) -> f64 {
    c * 9.0 / 5.0 + 32.0
}

fn main() {
    println!("{}", celsius_to_fahrenheit(100.0));
}

A //! comment describing the whole module

At the very top of a file, //! describes the file itself rather than the item below it — the first thing a reader (or cargo doc) sees when they open that module.

//! Utilities for working with shopping cart totals.
//!
//! This module has no real submodules here — in a real project
//! this comment would sit at the top of `cart.rs`.

fn main() {
    println!("see the module doc comment above");
}

The TODO/FIXME convention

These aren’t special to Rust — they’re just an ordinary comment with a keyword teams agree to grep for, so unfinished work doesn’t get lost.

fn main() {
    let mut price = 19.99;
    // TODO: apply loyalty discount once the rules are finalized
    // FIXME: this doesn't yet handle negative quantities
    price *= 1.0;
    println!("price: {price}");
}

A doc comment on a struct field

Fields can carry their own /// comment too, so cargo doc explains not just what a struct is, but what each piece of data inside it means.

/// A single row in the user table.
struct User {
    /// The user's display name, shown in the UI.
    name: String,
    /// Account age in days since signup.
    age_days: u32,
}

fn main() {
    let u = User { name: String::from("Ada"), age_days: 42 };
    println!("{} has been here {} days", u.name, u.age_days);
}

A # Panics section warning readers up front

Doc comments have other conventional sections besides # Examples. # Panics tells callers exactly which inputs will crash the program, before they find out the hard way.

/// Divides two numbers.
///
/// # Panics
///
/// Panics if `divisor` is zero.
pub fn divide(n: i32, divisor: i32) -> i32 {
    n / divisor
}

fn main() {
    println!("{}", divide(10, 2));
}

Your turn

This code wants a doc comment on the public function so it shows up in cargo doc, but it’s using the wrong comment style, and the doc comment is in the wrong place. Fix it so the description properly documents greeting. Press ▶ Run.

// Returns a friendly greeting for the app.
pub fn greeting() -> &'static str {
    /// this comment is in the wrong spot
    "Welcome!"
}

fn main() {
    println!("{}", greeting());
}

/// Returns a friendly greeting for the app.
pub fn greeting() -> &'static str {
    // this note is fine as an ordinary comment
    "Welcome!"
}

fn main() {
    println!("{}", greeting());
}

Quick check

Remember this

• // is an ordinary comment; /* ... */ is the block form. Both are ignored by the compiler.
• /// is a doc comment: it describes the item directly below it and feeds cargo doc.
• //! documents the thing it’s inside (a module or file), used at the top of files.
• Good comments explain why, not what — don’t just restate the code.
• Code examples inside doc comments are run as tests, which keeps docs honest.

Go deeper

• Rust by Example - Documentation — How doc comments work.

Next:

• Modules and crates
• Docs and rustfmt

Modules and crates

Beginner · Language basics

What & why

As your program grows past one file, you need a way to organize it into sensible groups and decide what’s shared and what’s private. Rust does this with modules (folders of code inside a project) and crates (whole projects that get compiled). Getting the vocabulary straight now means the “where does this code go?” question stops being scary later.

The idea, slowly

Crate: the whole package

A crate is the unit Rust compiles at once — roughly, “one project.” There are two kinds:

• A binary crate is a program you can run. It has a main function. Your hello world was a binary crate.
• A library crate is code meant to be used by other crates. It has no main; instead it offers functions and types for others to call. When you add a dependency from the internet, you’re pulling in a library crate.

You mostly don’t think about crates directly — Cargo (Rust’s build tool) handles them. Just hold the mental model: a crate is a compiled package, either a runnable program or a reusable library.

Module: a labeled drawer inside a crate

A module is a way to group related code and give it a name. Think of a crate as a filing cabinet and modules as the labeled drawers inside. You declare one with mod:

mod parser {
    pub fn parse(input: &str) -> usize {
        input.len()
    }
}

fn main() {
    // reach into the module with :: (two colons)
    let n = parser::parse("hello");
    println!("parsed length is {n}"); // 5
}

Read mod parser { ... } as “here’s a drawer named parser, and here’s what’s inside it.” To use something from the drawer, you write the module’s name, then ::, then the item’s name: parser::parse. The :: is Rust’s “reach inside” operator — a path separator, like a slash in a folder path.

Privacy: pub opens the drawer

Here’s the rule that trips people up: everything in a module is private by default. Private means “only code inside this same module (or its children) can see it.” From outside, it’s invisible.

Look again at the example. The function is written pub fn parse. That pub (public) is what lets main — which is outside the module — call it. Remove the pub and watch it break:

mod parser {
    fn parse(input: &str) -> usize {  // no pub → private
        input.len()
    }
}

fn main() {
    let n = parser::parse("hello");   // ERROR: function `parse` is private
    println!("{n}");
}

Press Run: “function parse is private.” The compiler is protecting the module’s insides. This is a feature: a module can have lots of helper functions it uses internally, and only mark the few it wants the outside world to touch with pub. That handful of pub items is the module’s public interface — its promise to everyone else.

The guiding habit: keep things as private as you can. Only add pub when something genuinely needs to be used from outside. Private code is free to change without breaking anyone.

use saves you from long paths

Writing parser::parse every time gets tiring. The use keyword brings a name into scope so you can refer to it directly:

mod parser {
    pub fn parse(input: &str) -> usize {
        input.len()
    }
}

use parser::parse;   // bring `parse` into scope

fn main() {
    let n = parse("hello");   // now no prefix needed
    println!("{n}");
}

You’ve already used use without thinking — pulling in things like use std::collections::HashMap;. It’s just “let me call this by its short name.”

Modules and files

In small examples, mod parser { ... } with the code right there in braces works fine. In real projects, you usually put a module in its own file. Writing mod parser; (with a semicolon, no braces) tells Rust: “the module parser lives in a file called parser.rs next door — go read it.” The module structure and the file structure line up, but they’re separate ideas: mod declares the module, and the file is just where its contents happen to live. You don’t need this yet; recognize it when you see it.

The standard library is a crate too

Everything you get for free — String, println!, Vec — comes from a library crate called std. When you write std::collections::HashMap, you’re reading a path: the std crate, its collections module, the HashMap inside. Same :: navigation, all the way down.

Common mistakes

• Forgetting pub. Items are private by default. Calling a module’s function from outside without marking it pub fails with “function is private.” Add pub to the things you want to expose.
• Making everything pub. The opposite mistake. If every function is public, you can never safely change your internals. Expose only what callers truly need.
• Confusing mod and use. mod declares a module (creates the drawer or points at its file). use just makes an existing name shorter to type. They are not the same; use alone won’t create a module.
• Wrong path with ::. parser.parse() (a dot) is not how you reach into a module — that’s method syntax. Use parser::parse() with the double colon for paths.
• pub on the function but not its enclosing module. If a module is private, marking an inner function pub still won’t let outside code reach it — the whole path must be reachable. Make the parent module pub too if needed.

More examples

A CLI’s flag parser gets its own drawer

Keeping argument-parsing code inside a cli module means main stays focused on running the program, not decoding strings.

mod cli {
    pub fn parse_flag(arg: &str) -> bool {
        arg == "--verbose" || arg == "-v"
    }
}

fn main() {
    let args = ["build", "--verbose"];
    let verbose = args.iter().any(|a| cli::parse_flag(a));
    println!("verbose mode: {}", verbose);
}

Nested modules for a game engine’s systems

A game engine groups unrelated systems — physics, rendering, audio — into their own nested modules so their internals don’t tangle together.

mod game {
    pub mod physics {
        pub fn apply_gravity(velocity_y: f64) -> f64 {
            velocity_y - 9.8
        }
    }
}

fn main() {
    let v = game::physics::apply_gravity(0.0);
    println!("velocity after one tick: {v}");
}

An inventory module for an online store

Stock-checking logic lives behind one pub function in an inventory module, so the rest of the store’s code doesn’t need to know how availability is calculated.

mod inventory {
    pub fn in_stock(quantity: u32) -> bool {
        quantity > 0
    }
}

fn main() {
    let quantity = 0;
    println!("in stock? {}", inventory::in_stock(quantity));
}

A config module for a web server’s defaults

Bundling default settings into a config module gives the rest of the crate one path to reach for instead of scattering constants everywhere.

mod config {
    pub const DEFAULT_PORT: u16 = 8080;

    pub fn describe() -> String {
        format!("listening on port {DEFAULT_PORT}")
    }
}

fn main() {
    println!("{}", config::describe());
    println!("port constant: {}", config::DEFAULT_PORT);
}

Your turn

This program tries to use a function from a module, but it won’t compile. Two things are wrong. Fix it so it prints the length. Press ▶ Run.

mod text_tools {
    fn word_count(input: &str) -> usize {
        input.split(' ').count()
    }
}

fn main() {
    let n = text_tools.word_count("hello there friend");
    println!("word count is {n}");
}

mod text_tools {
    pub fn word_count(input: &str) -> usize {
        input.split(' ').count()
    }
}

fn main() {
    let n = text_tools::word_count("hello there friend");
    println!("word count is {n}"); // 3
}

Quick check

Remember this

• A crate is a compiled package: a binary crate runs (main), a library crate is used by others.
• A module (mod name { ... }) groups related code inside a crate, like a labeled drawer.
• Everything is private by default; pub exposes an item to code outside its module.
• Reach into a module with :: (a path), e.g. parser::parse. Method calls use a dot.
• use brings a name into scope so you can type its short form. The standard library is the std crate.

Go deeper

• Rust Book - Modules — Module basics.

Next:

• Structs
• Enums
• Workspaces and crates

Visibility and privacy

Beginner · Language basics

What & why

Think of modules as rooms in a house. Anything you put in a room stays in that room — and in any room nested inside it — unless you put a sign on the door saying it’s open. That’s Rust’s privacy model: everything is private by default, scoped to the module that defines it and that module’s descendants. Deciding what to mark pub, and how widely, is how a crate keeps a small, stable public API while its internals stay free to change.

The idea, slowly

Private by default

mod kitchen {
    fn secret_recipe() -> &'static str {
        "garlic butter"
    }

    pub fn serve() -> &'static str {
        secret_recipe() // fine: same module can see its own private items
    }
}

fn main() {
    println!("{}", kitchen::serve()); // OK: serve is pub
    // println!("{}", kitchen::secret_recipe()); // ERROR: private
}

secret_recipe has no visibility modifier, so it’s private to kitchen — visible to code inside kitchen (like serve), invisible to everything outside it (like main). serve is marked pub, so it’s the crack in the door that lets outside code reach in.

pub: open to anyone who can reach the module

pub exposes an item to any code that can name the path to it — including, if this crate is published as a library, code outside the crate entirely. It’s the widest visibility Rust has.

pub(crate): open within your crate, closed to the outside world

mod inner {
    pub(crate) fn helper() -> i32 { 42 } // visible anywhere in this crate...
    pub fn public_api() -> i32 { helper() } // ...but only this is visible outside it
}

fn main() {
    println!("{}", inner::helper());     // OK: same crate
    println!("{}", inner::public_api()); // OK: fully public
}

If this crate were published as a library, downstream users could call public_api() but would have no way to reach helper() at all — pub(crate) is perfect for “shared internal plumbing” that different modules of your own code need to call, without it becoming part of your promised API.

pub(super): open to just the parent module

mod outer {
    pub fn from_outer() -> i32 {
        inner::only_for_outer()
    }

    mod inner {
        pub(super) fn only_for_outer() -> i32 { 7 } // visible to `outer`, no further
    }
}

fn main() {
    println!("{}", outer::from_outer());
    // outer::inner::only_for_outer(); // ERROR: not visible outside `outer`
}

pub(super) is a narrower pub(crate) — “visible one level up,” useful when a submodule needs to hand something back to its immediate parent without exposing it any further.

pub use: re-exporting so callers don’t need your internal layout

mod shapes {
    pub mod circle {
        pub fn area(r: f64) -> f64 {
            std::f64::consts::PI * r * r
        }
    }
}

pub use shapes::circle::area; // flatten the path at the crate root

fn main() {
    println!("{:.2}", area(2.0));                  // via the re-export
    println!("{:.2}", shapes::circle::area(2.0));   // the real path still works too
}

pub use re-exports an item under a new, usually shorter, path. Callers write area(...) instead of shapes::circle::area(...), and if you later reorganize your internal modules, you only need to update the pub use line — callers’ code doesn’t break.

A pub struct’s fields are still private by default

mod account {
    pub struct Account {
        pub id: u32,
        balance: f64, // private, even though Account itself is pub
    }

    impl Account {
        pub fn new(id: u32, balance: f64) -> Account {
            Account { id, balance }
        }

        pub fn balance(&self) -> f64 {
            self.balance
        }
    }
}

fn main() {
    let acc = account::Account::new(1, 100.0);
    println!("{}", acc.id);        // OK: `id` is pub
    println!("{}", acc.balance()); // OK: through a public getter
    // println!("{}", acc.balance); // ERROR: field `balance` is private
}

What the compiler is thinking: pub on a struct only answers “can code outside this module even name this type?” It says nothing about the fields — each field’s visibility is decided separately, field by field. This is what makes “public struct, private field, public getter” such a common pattern: it lets you change how balance is stored later without breaking anyone who calls .balance().

Common mistakes

• Marking a struct pub and assuming its fields come along for free. Each field needs its own pub; a pub struct with no pub fields is unconstructible and unreadable from outside its module (unless you provide public methods).
• Reaching for pub “to be safe.” Every pub item is a permanent promise to your callers — widening visibility later is easy, narrowing it is a breaking change. Start with the narrowest visibility that works (pub(crate)/pub(super)) and widen only when something genuinely needs to leave the crate.
• Forgetting pub(crate) is invisible to downstream users of a published crate. It’s for sharing across your own modules, not for exposing an API.
• Expecting privacy to be file-scoped. Privacy follows the module tree, not the filesystem — two modules can share a file, or one module can span several files, and visibility rules only ever care about the module structure.

More examples

A logging library’s public entry point

Callers only ever need info; how the timestamp is formatted is an internal detail that can change without breaking anyone who logs a message.

mod logger {
    fn timestamp() -> &'static str {
        "12:00:00" // private helper, internal detail
    }

    pub fn info(message: &str) {
        println!("[{}] INFO: {}", timestamp(), message);
    }
}

fn main() {
    logger::info("server started");
    // logger::timestamp(); // ERROR: private
}

Sharing a connection pool helper across your crate

pub(crate) is right for plumbing like a connection string builder — other modules in this crate can call it, but it never leaks out if this crate is published as a library.

mod db {
    pub(crate) fn connection_string() -> String {
        String::from("postgres://localhost/app")
    }

    pub fn connect() -> String {
        format!("connected to {}", connection_string())
    }
}

fn main() {
    println!("{}", db::connect());
    println!("{}", db::connection_string()); // OK: same crate
}

A validator reporting back to its parent module only

pub(super) fits a submodule that exists purely to serve its parent — signup needs validation’s result, but nothing else in the crate should be able to reach into it directly.

mod signup {
    pub fn register(email: &str) -> bool {
        validation::is_valid(email)
    }

    mod validation {
        pub(super) fn is_valid(email: &str) -> bool {
            email.contains('@')
        }
    }
}

fn main() {
    println!("{}", signup::register("user@example.com"));
    // signup::validation::is_valid("x"); // ERROR: not visible outside `signup`
}

Re-exporting a formatting helper at the crate root

pub use lets callers write title_case(...) directly instead of remembering that it actually lives two modules deep inside text_utils::format.

mod text_utils {
    pub mod format {
        pub fn title_case(s: &str) -> String {
            let mut chars = s.chars();
            match chars.next() {
                Some(first) => first.to_uppercase().collect::<String>() + chars.as_str(),
                None => String::new(),
            }
        }
    }
}

pub use text_utils::format::title_case;

fn main() {
    println!("{}", title_case("rust"));                       // via the re-export
    println!("{}", text_utils::format::title_case("humans")); // the real path still works
}

Your turn

This program tries to construct an item type from outside the module that defines it.

mod inventory {
    struct Item {
        name: String,
        pub price: f64,
    }

    pub fn cheapest_name() -> String {
        let item = Item { name: String::from("Widget"), price: 9.99 };
        item.name
    }
}

fn main() {
    println!("{}", inventory::cheapest_name());
    let item = inventory::Item { name: String::from("Gadget"), price: 4.5 };
    println!("{}", item.price);
}

mod inventory {
    pub struct Item {
        name: String,
        pub price: f64,
    }

    impl Item {
        pub fn new(name: &str, price: f64) -> Item {
            Item { name: name.to_string(), price }
        }
    }

    pub fn cheapest_name() -> String {
        let item = Item::new("Widget", 9.99);
        item.name
    }
}

fn main() {
    println!("{}", inventory::cheapest_name());
    let item = inventory::Item::new("Gadget", 4.5);
    println!("{}", item.price); // OK: `price` is pub
}

Quick check

Remember this

• Everything is private by default, scoped to its defining module and that module’s descendants.
• pub exposes an item to anyone who can reach the module — including, for a library crate, outside users.
• pub(crate) exposes something across your whole crate, but never to downstream users of a published crate.
• pub(super) exposes something to just the parent module, one level up.
• pub use re-exports an item under a new path, letting callers ignore your internal module layout.
• A pub struct’s fields are still private unless each one is marked pub individually.

Go deeper

• Rust Reference - Visibility and Privacy — Exact privacy rules.

Next:

• Structs
• Workspaces and crates

Structs

Beginner · Language basics

What & why

A struct lets you glue several related values together into one named type. Instead of juggling three loose variables — user_id, user_name, user_active — you bundle them into a single User value that carries all three. Structs are how you model the “things” in your program: a user, a point, a config, an order. They’re one of the two building blocks of Rust types (enums are the other).

The idea, slowly

Defining a struct

You define a struct with the struct keyword and a list of fields, each with a name and a type:

struct User {
    id: u64,
    name: String,
    active: bool,
}

fn main() {
    println!("defined a User struct");
}

Think of this as designing a form: a User always has an id, a name, and an active flag. This is just the blueprint — no actual user exists yet. It’s like a cookie cutter, not a cookie.

By convention, struct names use CamelCase (each word capitalized) and field names use snake_case (lowercase with underscores).

Creating an instance

To make an actual User, you fill in every field by name:

struct User {
    id: u64,
    name: String,
    active: bool,
}

fn main() {
    let user = User {
        id: 1,
        name: String::from("Shaon"),
        active: true,
    };

    println!("user id is {}", user.id);   // reach a field with a dot
    println!("name is {}", user.name);
}

User { id: 1, name: ..., active: true } is a struct literal: you list each field and the value it should hold. You must fill in every field — Rust won’t let you forget one. Once you have a user, you read a field with a dot: user.id, user.name. Same dot you’d use in many languages.

Changing a field needs mut

Just like plain variables, a struct is immutable unless you say mut. And it’s the whole struct that’s mutable or not — you can’t make just one field changeable:

struct User {
    id: u64,
    name: String,
    active: bool,
}

fn main() {
    let mut user = User {
        id: 1,
        name: String::from("Shaon"),
        active: true,
    };

    user.active = false;   // allowed because `user` is mut
    println!("active? {}", user.active);
}

Drop the mut and user.active = false; fails with “cannot assign to … immutable.” The mut on let covers every field of the struct.

A constructor pattern

Typing out every field each time gets old, especially when some values are always the same. A common habit is to write a function that builds the struct for you:

struct User {
    id: u64,
    name: String,
    active: bool,
}

fn new_user(id: u64, name: String) -> User {
    User {
        id,
        name,          // shorthand: field `name` gets the variable `name`
        active: true,  // sensible default
    }
}

fn main() {
    let user = new_user(7, String::from("Rust"));
    println!("{} is active? {}", user.name, user.active);
}

Two things to notice. First, active: true bakes in a default so callers don’t have to think about it. Second, the field init shorthand: when a variable has the same name as the field (id, name), you can write just id instead of id: id. Rust matches them up. It’s a small convenience you’ll see everywhere.

(Later you’ll learn to attach this constructor to the type as User::new(...) using an impl block — that’s the Methods lesson. This plain function does the same job for now.)

Tuple structs: names without field names

Sometimes you want a distinct type but the fields don’t need names. A tuple struct gives you that:

struct Point(i32, i32);   // two i32s, no field names

fn main() {
    let origin = Point(0, 0);
    println!("x = {}, y = {}", origin.0, origin.1);  // reach by position
}

Point(0, 0) looks like a tuple but it’s its own named type — a Point can’t be mixed up with some other (i32, i32). You reach into it by position (.0, .1) like a tuple. Use these sparingly; named fields are usually clearer.

Why bother, instead of loose variables?

You could track id, name, and active as three separate variables. But then nothing ties them together — you could pass the wrong name with the wrong id and Rust couldn’t help. Bundling them in a User makes “a user” a real thing the compiler understands, so you can pass one value around, and the pieces travel together and stay in sync.

Common mistakes

• Forgetting a field in the literal. User { id: 1 } when the struct also needs name and active fails with “missing fields.” You must provide every field when constructing (unless you use struct update syntax to copy the rest from another instance).
• Trying to make one field mutable. There’s no mut on individual fields. Mutability lives on the binding: let mut user = ... makes the whole struct changeable. If user isn’t mut, no field can be assigned.
• Confusing the blueprint with an instance. struct User { ... } defines the type; it does not create a user. You still need let user = User { ... } to get an actual value.
• Wrong field name or type. User { naem: ... } (typo) or putting a number where a String goes is a compile error. Fields must match the definition exactly.
• Reaching into a struct with :: instead of .. Fields use a dot: user.name. The :: is for paths and associated functions, not field access.

More examples

Modeling a game character

A Character struct keeps a player’s name, health, and level together, so taking damage is just updating one field on one value instead of juggling three variables.

struct Character {
    name: String,
    hp: u32,
    level: u32,
}

fn main() {
    let mut hero = Character {
        name: String::from("Aria"),
        hp: 100,
        level: 1,
    };

    hero.hp -= 30; // took damage
    println!("{} is at {} hp (level {})", hero.name, hero.hp, hero.level);
}

Representing an RGB color

A tuple struct is a good fit here — a color is just three numbers, and naming each one (red, green, blue) would add ceremony without adding clarity.

struct Color(u8, u8, u8);

fn main() {
    let warning = Color(255, 165, 0);
    println!("rgb({}, {}, {})", warning.0, warning.1, warning.2);
}

Building a server config with sensible defaults

A constructor function bakes in the common case — 127.0.0.1:8080 — so most callers never have to think about every field.

struct ServerConfig {
    host: String,
    port: u16,
}

fn default_config() -> ServerConfig {
    ServerConfig {
        host: String::from("127.0.0.1"),
        port: 8080,
    }
}

fn main() {
    let config = default_config();
    println!("serving on {}:{}", config.host, config.port);
}

Totaling a shopping cart line item

Bundling a cart line’s name, price, and quantity into one struct means the subtotal calculation always uses matching values, never a price from one item paired with another’s quantity.

struct CartItem {
    name: String,
    price: f64,
    quantity: u32,
}

fn main() {
    let item = CartItem {
        name: String::from("Notebook"),
        price: 4.50,
        quantity: 3,
    };

    let subtotal = item.price * item.quantity as f64;
    println!("{} x{}: ${:.2}", item.name, item.quantity, subtotal);
}

Your turn

This program defines a Book and tries to build and update one, but it won’t compile. There are two problems. Fix it so it prints the title and the updated year. Press ▶ Run.

struct Book {
    title: String,
    year: u32,
}

fn main() {
    let book = Book {
        title: String::from("Rust for Humans"),
    };

    book.year = 2026;
    println!("{} ({})", book.title, book.year);
}

struct Book {
    title: String,
    year: u32,
}

fn main() {
    let mut book = Book {
        title: String::from("Rust for Humans"),
        year: 2025,
    };

    book.year = 2026;
    println!("{} ({})", book.title, book.year);
}

Quick check

Remember this

• A struct bundles related named values (fields) into one type — a blueprint, not a value.
• Create one with a struct literal, filling in every field: User { id: 1, name: ..., active: true }.
• Read fields with a dot (user.name); mutating any field needs let mut on the whole binding.
• Field init shorthand: name instead of name: name when the variable and field share a name.
• Tuple structs (struct Point(i32, i32)) are named types with positional fields; use named fields when you can.

Go deeper

• Rust Book - Structs — How to define and instantiate structs.

Next:

• Methods and impl blocks
• Traits

Derivable traits

Beginner · Language basics

What & why

Every struct or enum you write eventually needs the same handful of boring abilities: print itself for debugging, get copied, get compared for equality, get a sensible default, get sorted. Writing those by hand for every type would be pure boilerplate — so Rust lets the compiler generate a mechanical, field-by-field implementation with one line: #[derive(...)]. It’s the single most common attribute in everyday Rust code.

The idea, slowly

#[derive(Debug)] — printable for developers

#[derive(Debug)]
struct Point {
    x: i32,
    y: i32,
}

fn main() {
    let p = Point { x: 1, y: 2 };
    println!("{p:?}"); // Point { x: 1, y: 2 }
}

This generates an implementation of std::fmt::Debug that prints the struct’s name and every field’s value. It’s the first derive most people reach for, because without it {:?} — and therefore most debugging — doesn’t compile.

#[derive(Clone)] and #[derive(Copy)]

Clone gives you an explicit .clone() method that makes a deep copy — you always have to ask for it. Copy is different: it’s a marker that changes what assignment means. Without Copy, let b = a; moves a into b (a becomes unusable). With Copy, that same line silently duplicates the value instead, and both a and b stay usable.

#[derive(Debug, Clone, Copy)]
struct Point {
    x: i32,
    y: i32,
}

fn main() {
    let a = Point { x: 1, y: 2 };
    let b = a; // copied, not moved — `a` is still valid
    println!("{a:?} {b:?}");
}

Copy only works when every field is itself Copy — no String, Vec, Box, or anything else that owns heap data, because those can’t be safely duplicated by just copying bits. And Copy requires Clone (trait Copy: Clone) — a Copy type is always also a Clone type, since “copy” is really just “the cheap, implicit version of clone.”

#[derive(PartialEq, Eq)] — equality

PartialEq gives you == and !=, comparing every field. Eq is a marker with no methods — it promises the comparison is fully reflexive (a == a is always true), which floats can’t promise because NaN != NaN. That’s why f64/f32 implement PartialEq but not Eq.

#[derive(Debug, PartialEq, Eq)]
struct Point {
    x: i32,
    y: i32,
}

fn main() {
    let a = Point { x: 1, y: 2 };
    let b = Point { x: 1, y: 2 };
    println!("{}", a == b); // true — compared field by field
}

#[derive(Hash)] — usable as a HashMap/HashSet key

use std::collections::HashSet;

#[derive(Debug, PartialEq, Eq, Hash)]
struct Point {
    x: i32,
    y: i32,
}

fn main() {
    let mut seen = HashSet::new();
    seen.insert(Point { x: 1, y: 2 });
    println!("{}", seen.contains(&Point { x: 1, y: 2 })); // true
}

HashMap/HashSet keys need both Eq and Hash — Eq so two equal keys are recognized as the same key, Hash so they land in the same bucket.

#[derive(Default)] — a sensible zero value

#[derive(Debug, Default)]
struct Config {
    verbose: bool,
    retries: u32,
    name: String,
}

fn main() {
    let c = Config::default();
    println!("{c:?}"); // Config { verbose: false, retries: 0, name: "" }

    let c2 = Config { retries: 3, ..Default::default() }; // override just one field
    println!("{c2:?}");
}

Default fills every field with its type’s default (false, 0, "", None, …). The ..Default::default() struct-update syntax is the everyday pattern for “give me the default, except for this one field.”

#[derive(PartialOrd, Ord)] — comparison and sorting

Derived ordering compares fields in declaration order, top to bottom — exactly like comparing tuples. The first field is the most significant.

#[derive(Debug, PartialEq, Eq, PartialOrd, Ord)]
struct Version {
    major: u32,
    minor: u32,
    patch: u32,
}

fn main() {
    let mut versions = vec![
        Version { major: 1, minor: 2, patch: 0 },
        Version { major: 1, minor: 0, patch: 5 },
        Version { major: 2, minor: 0, patch: 0 },
    ];
    versions.sort();
    println!("{versions:?}"); // ordered by major, then minor, then patch
}

PartialOrd gives you <, <=, >, >=; Ord (which requires Eq) is what .sort(), BTreeMap keys, and BinaryHeap actually need, because it promises every pair of values can be compared — floats can’t derive Ord for the same NaN reason they can’t derive Eq.

Why deriving fails, and when to hand-write instead

What the compiler is thinking: #[derive(Trait)] expands to “implement Trait by calling Trait’s method on every field, in order.” That only type-checks if every field’s type already implements Trait. One field without Debug blocks #[derive(Debug)] on the whole struct — the derive doesn’t skip it, it fails to compile.

Hand-write the trait instead of deriving when the mechanical, field-by-field behavior isn’t the behavior you want:

• A case-insensitive string wrapper needs custom PartialEq/Hash so "Rust" and "rust" compare and hash as equal.
• A struct with an internal cache field shouldn’t have that field affect equality.
• A priority queue often wants Ord based on just one field (or reversed), not every field in declaration order.

Common mistakes

• Deriving Copy on a struct with a String/Vec/Box field. Fails with “the trait Copy may not be implemented for this type” — those fields own heap data and can’t be bitwise-duplicated safely.
• Deriving Eq/Ord on a struct containing an f64/f32 field. Floats aren’t Eq/Ord because of NaN; you can derive PartialEq/PartialOrd on them, but not the stricter traits.
• Assuming a missing field trait gets silently skipped. It doesn’t — the whole #[derive(...)] fails to compile if any field lacks that trait.
• Assuming derived ordering compares “by importance.” It compares fields in the order you wrote them in the struct — reorder the fields to change sort priority, or hand-write Ord.

More examples

Snapshotting a game save before risking it

Clone gives a checkpoint an independent copy to fall back to — mutating current afterward can’t touch checkpoint, because they no longer share any data.

#[derive(Debug, Clone)]
struct GameSave {
    level: u32,
    hp: u32,
}

fn main() {
    let checkpoint = GameSave { level: 3, hp: 80 };
    let mut current = checkpoint.clone(); // keep the checkpoint safe before risking hp
    current.hp -= 30; // took damage

    println!("checkpoint: {:?}", checkpoint);
    println!("current: {:?}", current);
}

Deduplicating scanned badge IDs at a gate

PartialEq, Eq, and Hash together are what let a struct sit inside a HashSet — here that’s the difference between silently re-admitting a badge and catching a repeat scan.

use std::collections::HashSet;

#[derive(Debug, PartialEq, Eq, Hash, Clone, Copy)]
struct BadgeId(u32);

fn main() {
    let mut checked_in: HashSet<BadgeId> = HashSet::new();
    let scans = [BadgeId(101), BadgeId(102), BadgeId(101), BadgeId(103)];

    for badge in scans {
        if !checked_in.insert(badge) {
            println!("badge {} already checked in", badge.0);
        }
    }
    println!("{} unique badges scanned", checked_in.len());
}

Sorting a to-do list by priority

Deriving Ord on Task means .sort() just works — it compares priority first because that’s the field declared first, exactly the order a to-do list should sort by.

#[derive(Debug, PartialEq, Eq, PartialOrd, Ord)]
struct Task {
    priority: u8,
    name: String,
}

fn main() {
    let mut todos = vec![
        Task { priority: 2, name: String::from("write report") },
        Task { priority: 1, name: String::from("fix critical bug") },
        Task { priority: 3, name: String::from("reply to email") },
    ];

    todos.sort();

    for task in &todos {
        println!("[{}] {}", task.priority, task.name);
    }
}

Defaulting an API pagination request

Default plus ..Default::default() lets a request override just the fields a caller cares about — here, only the page number — while every other field falls back sensibly.

#[derive(Debug, Default)]
struct Pagination {
    page: u32,
    per_page: u32,
    sort_desc: bool,
}

fn main() {
    let default_request = Pagination::default();
    println!("{:?}", default_request);

    let page_two = Pagination { page: 2, ..Default::default() };
    println!("{:?}", page_two);
}

Your turn

This struct tries to derive Copy, but one of its fields makes that impossible.

#[derive(Debug, Clone, Copy)]
struct Player {
    name: String,
    score: u32,
}

fn main() {
    let p1 = Player { name: String::from("Ferris"), score: 10 };
    let p2 = p1; // relies on Copy
    println!("{} {}", p1.name, p2.name);
}

#[derive(Debug, Clone)]
struct Player {
    name: String,
    score: u32,
}

fn main() {
    let p1 = Player { name: String::from("Ferris"), score: 10 };
    let p2 = p1.clone(); // explicit deep copy, since Player isn't Copy
    println!("{} {}", p1.name, p2.name);
}

Quick check

Remember this

• #[derive(Debug)] enables {:?} printing; add it to nearly every type you define.
• Clone is an explicit deep copy (.clone()); Copy makes assignment implicitly duplicate — only for types where every field is itself Copy, and Copy requires Clone.
• PartialEq/Eq enable ==; PartialOrd/Ord enable < and sorting — floats can’t derive Eq/Ord because of NaN.
• Hash (together with Eq) is what lets a type be a HashMap/HashSet key.
• Default fills every field with its type’s default value; ..Default::default() overrides just some fields.
• Deriving requires every field to implement that trait — one missing field fails the whole derive.
• Hand-write a trait instead of deriving when the mechanical field-by-field behavior isn’t the behavior you actually want.

Go deeper

• Rust Book - Derivable Traits (Appendix C) — Every standard derivable trait.

Next:

• Enums
• Operator overloading

Enums

Beginner · Language basics

What & why

An enum lets you say “this value is exactly one of these few possibilities.” A traffic light is red, yellow, or green — never all three, never something else. A struct bundles values that are all present together; an enum picks one from a list of options. This “one of” idea is quietly one of Rust’s most powerful tools, and it’s the foundation for how Rust handles missing values and errors safely.

The idea, slowly

The simplest enum: a set of choices

You define an enum with the enum keyword and list the possibilities, called variants:

enum Direction {
    North,
    South,
    East,
    West,
}

fn main() {
    let heading = Direction::North;   // pick one variant
    // ... we'll do something with it below
    println!("picked a direction");
}

Direction is a type whose value can be exactly one of four things. You choose a variant with EnumName::Variant, so Direction::North. The :: reaches into the enum to grab the variant, the same path syntax you saw with modules.

A heading is always a valid Direction — there’s no way to accidentally create a fifth direction. The compiler knows the complete list, and that turns out to be incredibly useful (see pattern matching below).

The powerful part: variants can carry data

Here’s what makes Rust enums special. Each variant can hold its own data, and different variants can hold different shapes of data:

enum Message {
    Quit,                       // holds nothing
    Move { x: i32, y: i32 },    // holds two named fields, like a struct
    Write(String),              // holds a String
    ChangeColor(i32, i32, i32), // holds three numbers, like a tuple
}

fn main() {
    let a = Message::Quit;
    let b = Message::Move { x: 10, y: 20 };
    let c = Message::Write(String::from("hello"));
    let d = Message::ChangeColor(255, 0, 0);
    println!("built four different messages");
}

Read this slowly. A Message is one of four things. If it’s a Write, it carries a String. If it’s a Move, it carries an x and a y. If it’s Quit, it carries nothing at all. One type, four different possible shapes, and a value is always exactly one of them.

This is why enums are called the backbone of Rust modeling. You could try to represent this with a struct full of optional fields and a “kind” flag, but then nothing stops you from having a Write message with Move data filled in. The enum makes the illegal combinations impossible to build.

Option: the enum that replaces null

You will meet one enum constantly, and it’s built into Rust: Option. Many languages have null — a special “nothing here” value that causes crashes when you forget to check for it. Rust has no null. Instead it uses an enum:

fn find_first_even(numbers: &[i32]) -> Option<i32> {
    for &n in numbers {
        if n % 2 == 0 {
            return Some(n);   // found one: wrap it in Some
        }
    }
    None                       // found nothing
}

fn main() {
    let result = find_first_even(&[1, 3, 4, 7]);
    println!("{:?}", result);          // Some(4)
    let empty = find_first_even(&[1, 3, 5]);
    println!("{:?}", empty);           // None
}

Option<i32> means “either an i32, or nothing.” Its two variants are Some(value) (there’s a value) and None (there isn’t). Because the “nothing” case is baked into the type, Rust forces you to handle it — you can’t accidentally use a missing value like you can with null. That single design choice removes a whole category of crashes.

(The {:?} in println! is a debug print — handy for inspecting values while learning. And Result, the enum for success-or-error, works the same way; it’s in the Error handling lesson.)

Enums shine with match

An enum on its own is just a value. Where it becomes powerful is pairing it with match, which lets you handle each variant and pull the data back out:

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
}

fn describe(msg: Message) -> String {
    match msg {
        Message::Quit => String::from("quit"),
        Message::Move { x, y } => format!("move to {x}, {y}"),
        Message::Write(text) => format!("write: {text}"),
    }
}

fn main() {
    println!("{}", describe(Message::Move { x: 1, y: 2 }));
    println!("{}", describe(Message::Write(String::from("hi"))));
}

Notice how match both branches on which variant it is and unpacks the data inside (x, y, text). The next lesson (pattern matching) is entirely about this. For now, the key insight: enums and match are two halves of one idea. You design the possibilities with an enum, then handle them with match.

Common mistakes

• Forgetting the EnumName:: prefix. You write Direction::North, not just North. Without the prefix Rust doesn’t know which enum you mean (unless you brought it into scope with use).
• Treating a variant’s data as always accessible. You can’t just read the String out of Message::Write directly — the value might be a different variant. You get the data by matching, which is exactly why match exists.
• Reaching for null habits. There’s no null in Rust. “Might be missing” is Option, and you must handle the None case. Trying to skip it won’t compile.
• Overusing structs where an enum fits. If you find yourself with a “type” field and a pile of fields that are only sometimes filled in, that’s an enum trying to be born. Enums make “one of these shapes” explicit and safe.
• Non-exhaustive match. When you match an enum, you must handle every variant (or use _ for the rest). Miss one and the compiler stops you — a feature that catches bugs when you add a new variant later.

More examples

A vending machine’s possible states

The machine is always in exactly one state, and only Dispensing needs extra data — a perfect fit for an enum where each variant carries its own shape of information.

enum VendingState {
    Idle,
    Dispensing(String),
    OutOfStock,
}

fn status_message(state: VendingState) -> String {
    match state {
        VendingState::Idle => String::from("insert coin to start"),
        VendingState::Dispensing(item) => format!("dispensing {}", item),
        VendingState::OutOfStock => String::from("sold out, please choose another item"),
    }
}

fn main() {
    println!("{}", status_message(VendingState::Idle));
    println!("{}", status_message(VendingState::Dispensing(String::from("chips"))));
    println!("{}", status_message(VendingState::OutOfStock));
}

Cycling a traffic light through its phases

A match that returns a different variant for each input turns an enum into a tiny state machine — calling .next() repeatedly cycles the light through its phases forever.

#[derive(Debug)]
enum TrafficLight {
    Red,
    Yellow,
    Green,
}

impl TrafficLight {
    fn next(self) -> TrafficLight {
        match self {
            TrafficLight::Red => TrafficLight::Green,
            TrafficLight::Green => TrafficLight::Yellow,
            TrafficLight::Yellow => TrafficLight::Red,
        }
    }
}

fn main() {
    let mut light = TrafficLight::Red;
    for _ in 0..4 {
        println!("{:?}", light);
        light = light.next();
    }
}

Parsing command-line arguments

A CLI’s set of valid commands is naturally “one of a few options, one of which carries an argument” — exactly what an enum with a data-carrying variant like Run(String) was built for.

enum Command {
    Help,
    Version,
    Run(String),
}

fn execute(cmd: Command) {
    match cmd {
        Command::Help => println!("usage: app [help|version|run <task>]"),
        Command::Version => println!("app v1.0.0"),
        Command::Run(task) => println!("running task: {}", task),
    }
}

fn main() {
    execute(Command::Help);
    execute(Command::Version);
    execute(Command::Run(String::from("build")));
}

Guarding against division by zero

Returning Option<f64> instead of a plain f64 forces every caller to confront the “what if b is zero” case at compile time, instead of letting it crash or produce inf silently.

fn safe_divide(a: f64, b: f64) -> Option<f64> {
    if b == 0.0 {
        None
    } else {
        Some(a / b)
    }
}

fn main() {
    match safe_divide(10.0, 2.0) {
        Some(result) => println!("10 / 2 = {}", result),
        None => println!("cannot divide by zero"),
    }

    match safe_divide(5.0, 0.0) {
        Some(result) => println!("5 / 0 = {}", result),
        None => println!("cannot divide by zero"),
    }
}

Your turn

This program models a coin and tries to get its value, but it won’t compile. The variant is referenced without its enum name, and one variant is missing from the match. Fix it. Press ▶ Run.

enum Coin {
    Penny,
    Nickel,
    Dime,
}

fn value(coin: Coin) -> u32 {
    match coin {
        Penny => 1,
        Nickel => 5,
    }
}

fn main() {
    println!("{}", value(Coin::Dime));
}

enum Coin {
    Penny,
    Nickel,
    Dime,
}

fn value(coin: Coin) -> u32 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
    }
}

fn main() {
    println!("{}", value(Coin::Dime)); // 10
}

Quick check

Remember this

• An enum says a value is exactly one of several variants — pick one with EnumName::Variant.
• Variants can carry data, and each can carry a different shape (nothing, a tuple, or named fields).
• Enums make illegal states impossible to build, which is why they’re great for modeling.
• Option (Some(value) / None) is Rust’s built-in replacement for null — missing values are handled, not ignored.
• Enums pair with match to branch on the variant and unpack its data — that’s the next lesson.

Go deeper

• Rust Book - Enums — Variant-driven data.

Next:

• Pattern matching
• Error handling

Pattern matching

Intermediate · Language basics

What & why

Pattern matching is how you look at a value, figure out which shape it has, and pull the pieces out — all in one move. It’s the natural partner to enums: you built a value that could be one of several things, and match is how you handle each thing. Once it clicks, a lot of Rust code that looked mysterious (if let, match, destructuring) turns out to be the same simple idea wearing different clothes.

The idea, slowly

match: one value, many branches

A match compares a value against a list of patterns, top to bottom, and runs the first one that fits:

fn main() {
    let number = 3;

    match number {
        1 => println!("one"),
        2 => println!("two"),
        3 => println!("three"),
        _ => println!("something else"),
    }
}

Read each line as “if the value looks like this, do that.” The => separates the pattern (left) from the code to run (right). The compiler checks each arm in order and stops at the first match.

That last arm, _, is the catch-all — an underscore that means “anything not already handled.” It’s like the default case in other languages. It matters because of Rust’s big rule below.

The rule: match must be exhaustive

Rust insists that a match cover every possible value. If you leave a case out, it won’t compile:

fn main() {
    let flag = true;

    match flag {
        true => println!("yes"),
        // missing the `false` case!
    }
}

Press Run: “non-exhaustive patterns: false not covered.” At first this feels bossy. But it’s a gift: it means you can never forget a case. If you add a new enum variant six months from now, every match that doesn’t handle it lights up red immediately. The compiler is thinking: “you claim to handle this value — prove you handled all of it.”

You satisfy exhaustiveness either by listing every case, or by adding _ to sweep up the rest.

Matching an enum and unpacking its data

This is where match earns its keep. When you match an enum variant that carries data, the pattern names that data so you can use it:

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
}

fn main() {
    let msg = Message::Write(String::from("hello"));

    match msg {
        Message::Quit => println!("bye"),
        Message::Move { x, y } => println!("move to {x}, {y}"),
        Message::Write(text) => println!("writing: {text}"),
    }
}

Look at Message::Write(text). The text isn’t a value you already have — it’s a name you’re inventing to capture whatever String is inside this Write. Same with x and y in the Move arm. This is destructuring: the pattern mirrors the shape of the data, and Rust hands you the inner pieces under the names you chose. One construct branches and extracts, together.

if let: the shortcut for one case

Sometimes you only care about one variant and want to ignore everything else. Writing a full match with a _ => () throwaway arm is clunky. if let is the compact form:

fn main() {
    let maybe_number: Option<i32> = Some(7);

    if let Some(n) = maybe_number {
        println!("got a number: {n}");
    } else {
        println!("nothing here");
    }
}

Read if let Some(n) = maybe_number as: “if maybe_number matches the pattern Some(n), then bind that inner value to n and run the block.” It’s a match with only one interesting arm. Use if let when a full match would be overkill; use match when you genuinely handle several cases.

Patterns show up in more than match

Once you see patterns as “shapes with names,” you’ll spot them elsewhere. A let can destructure:

fn main() {
    let (a, b, c) = (1, 2, 3);      // unpack a tuple into three names
    println!("{a} {b} {c}");

    let point = (10, 20);
    let (x, y) = point;             // same idea
    println!("x={x}, y={y}");
}

let (a, b, c) = ... is a pattern too — it takes apart the tuple and binds each slot. So the destructuring you do in a match arm is the very same mechanism as a let that pulls a tuple apart. It’s all one idea.

Extra tools: multiple patterns and guards

Two handy extras. You can match several values in one arm with | (“or”), and you can add an if condition (a guard) to an arm:

fn main() {
    let n = 5;

    match n {
        1 | 2 | 3 => println!("small"),        // matches 1, 2, or 3
        x if x > 100 => println!("huge: {x}"), // matches, but only if x > 100
        _ => println!("in between"),
    }
}

The | lets one arm cover multiple patterns, and x if x > 100 only fires when both the pattern and the extra condition hold. You don’t need these often, but they’re there when a plain pattern isn’t enough.

Common mistakes

• Non-exhaustive match. Leaving out a case fails with “non-exhaustive patterns.” Handle every variant or add _. This is the whole point of match, so lean into it rather than fighting it.
• Putting _ too early. Arms are checked top to bottom, so a _ (or any broad pattern) placed above specific ones will swallow them, and Rust warns the later arms are “unreachable.” Keep the catch-all last.
• Reaching for the inner data without matching. You can’t do msg.text on an enum value — it might be a different variant. You get the inner value by matching (or if let), which is exactly what these tools are for.
• Using match when if let reads better (or vice versa). A match with one real arm and a _ => () is usually clearer as if let. Conversely, chaining many if lets where a single match would do makes code harder to follow.
• Forgetting patterns bind new names. In Some(n), n is a fresh name capturing the inner value — it does not compare against an existing variable called n. This surprises people who expect it to mean “match only if equal to n.”

More examples

Reading an HTTP status code

A web client needs to turn a raw status number into a human-readable category, and a range pattern like 500..=599 covers a whole band of codes in one arm.

fn describe_status(code: u16) -> &'static str {
    match code {
        200 => "OK",
        404 => "Not Found",
        500..=599 => "Server Error",
        _ => "Unknown",
    }
}

fn main() {
    println!("{}", describe_status(200));
    println!("{}", describe_status(503));
    println!("{}", describe_status(999));
}

Locating a point on a graph

Plotting software needs to classify a coordinate by which quadrant it falls in, and guards let each arm add its own condition on top of the tuple pattern.

fn quadrant(point: (i32, i32)) -> &'static str {
    match point {
        (0, 0) => "origin",
        (x, 0) if x > 0 => "positive x-axis",
        (x, y) if x > 0 && y > 0 => "quadrant I",
        (x, y) if x < 0 && y > 0 => "quadrant II",
        _ => "elsewhere",
    }
}

fn main() {
    println!("{}", quadrant((0, 0)));
    println!("{}", quadrant((3, 4)));
    println!("{}", quadrant((-2, 5)));
}

Applying an optional coupon code

A checkout flow only needs to handle “there’s a coupon” — if let skips the ceremony of a full match when the fallback is just “charge full price.”

fn apply_discount(price: f64, coupon: Option<u32>) -> f64 {
    if let Some(percent) = coupon {
        price - (price * percent as f64 / 100.0)
    } else {
        price
    }
}

fn main() {
    println!("{:.2}", apply_discount(100.0, Some(20)));
    println!("{:.2}", apply_discount(100.0, None));
}

Tagging log lines by severity

A log viewer destructures each (level, message) entry with a for loop, then matches on the level to decide how to display it.

fn main() {
    let entries = vec![("ERROR", "disk full"), ("INFO", "server started"), ("WARN", "low memory")];

    for (level, message) in &entries {
        match *level {
            "ERROR" => println!("[ERROR] {message}"),
            "WARN" => println!("[WARN] {message}"),
            _ => println!("[INFO] {message}"),
        }
    }
}

Your turn

This program should describe an Option, but it won’t compile. The match is missing a case, and one arm tries to reach into the value the wrong way. Fix it. Press ▶ Run.

fn describe(value: Option<i32>) -> String {
    match value {
        Some => format!("got {}", value.0),
    }
}

fn main() {
    println!("{}", describe(Some(42)));
    println!("{}", describe(None));
}

fn describe(value: Option<i32>) -> String {
    match value {
        Some(n) => format!("got {n}"),
        None => String::from("got nothing"),
    }
}

fn main() {
    println!("{}", describe(Some(42))); // got 42
    println!("{}", describe(None));     // got nothing
}

Quick check

Remember this

• match compares a value to patterns top-to-bottom and runs the first that fits; => separates pattern from action.
• A match must be exhaustive — cover every case or add _ as a catch-all (kept last).
• Patterns destructure: Some(n) or Move { x, y } both branch and bind the inner data to new names.
• if let is the compact form for handling just one variant; use it when a full match is overkill.
• Patterns also work in let bindings (let (a, b) = pair), with | for multiple patterns and if guards for extra conditions.

Go deeper

• Rust Book - Match — The core matching story.

Next:

• Methods and impl blocks
• Error handling

Methods and impl blocks

Intermediate · Language basics

What & why

A method is a function that belongs to a type. Instead of area(rectangle), you write rectangle.area() — the data and the behavior that acts on it live together. You’ve been calling methods all along: text.len(), numbers.push(5), String::from("hi"). This lesson shows you how to write your own, using impl blocks, and how to pick the right self so ownership stays happy.

The idea, slowly

The impl block: attaching behavior to a type

You define a struct (the data), then write an impl block (“implementation”) to hang methods on it:

struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

fn main() {
    let rect = Rectangle { width: 3, height: 4 };
    println!("area is {}", rect.area()); // 12
}

Read impl Rectangle { ... } as “here are the things a Rectangle can do.” Inside, area looks almost like a normal function, except its first parameter is the special word self. When you call rect.area(), Rust passes rect in as self automatically. So inside the method, self is the rectangle you called it on, and self.width reaches its field.

The dot before area is the giveaway: rect.area() is method-call syntax, and self is the value on the left of the dot.

The three receivers: &self, &mut self, self

The first parameter of a method — called the receiver — comes in three flavors, and choosing the right one is really a question about ownership (remember the Ownership lesson):

• &self — “let me look at the data.” Borrows the value immutably. Use this when the method only reads. Most methods are &self.
• &mut self — “let me change the data.” Borrows mutably. Use this when the method needs to modify a field.
• self — “give me the value; I’m taking it.” Takes ownership, consuming the value. Use this rarely — only when the method transforms the value into something else and the original shouldn’t be used afterward.

Here they are side by side:

struct Counter {
    count: u32,
}

impl Counter {
    fn get(&self) -> u32 {          // reads only → &self
        self.count
    }

    fn increment(&mut self) {       // changes a field → &mut self
        self.count += 1;
    }

    fn into_total(self) -> u32 {    // consumes self → self
        self.count
    }
}

fn main() {
    let mut c = Counter { count: 0 };
    c.increment();
    c.increment();
    println!("count is {}", c.get()); // 2

    let total = c.into_total();       // c is consumed here
    println!("final total {total}");
    // c can no longer be used — it was moved into into_total
}

Think of &self as borrowing your friend’s book to read it, &mut self as borrowing it to scribble a note, and self as them giving you the book for keeps. The compiler enforces this: to call increment, the variable must be mut, because you’re borrowing it mutably.

Associated functions: methods without a receiver

Some functions belong to a type but don’t act on an existing instance — most commonly, functions that create one. These leave off self entirely and are called associated functions. You call them with :: instead of a dot:

struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    // no self → associated function, a constructor
    fn new(width: u32, height: u32) -> Rectangle {
        Rectangle { width, height }
    }

    fn square(size: u32) -> Rectangle {
        Rectangle { width: size, height: size }
    }

    fn area(&self) -> u32 {
        self.width * self.height
    }
}

fn main() {
    let rect = Rectangle::new(3, 4);   // :: because there's no instance yet
    let sq = Rectangle::square(5);
    println!("{} and {}", rect.area(), sq.area());
}

You already know one of these: String::from("hi"). from is an associated function on String — no existing string to act on, so it uses :: and returns a fresh one. new is the conventional name for a constructor, but it’s just a regular associated function, nothing magic.

The pattern to remember: Type::function() when there’s no instance yet (creating one); value.method() when you already have one.

Methods keep code tidy

Why put behavior in an impl instead of loose functions? Because the logic that belongs to a type lives with that type. Anyone reading Rectangle sees everything it can do in one place, and calling rect.area() reads better than area(&rect). It’s the same reason you bundle data into a struct — grouping what belongs together.

Common mistakes

• Using &self when you need to mutate. If a method changes a field, it must take &mut self. With &self you’ll get “cannot assign to self.x, which is behind a & reference.” Switch the receiver to &mut self.
• Calling a &mut self method on a non-mut value. let c = Counter { ... }; c.increment(); fails because c isn’t mut. The variable must be let mut c to allow the mutable borrow.
• Mixing up . and ::. Associated functions (no self) are called with ::: Rectangle::new(...). Methods (with self) are called with a dot: rect.area(). Using the wrong one is a common early error.
• Accidentally consuming with self. A method that takes self (no &) moves the value; you can’t use the variable afterward. If you only meant to read, use &self so the caller keeps ownership.
• Forgetting self inside the method. Fields are self.width, not just width. Without self., Rust looks for a local variable named width and won’t find one.

More examples

Reading a thermostat’s setting

A smart-home app needs to display the temperature without ever letting other code accidentally change it — a perfect job for &self.

struct Thermostat {
    celsius: f64,
}

impl Thermostat {
    fn fahrenheit(&self) -> f64 {
        self.celsius * 9.0 / 5.0 + 32.0
    }
}

fn main() {
    let t = Thermostat { celsius: 22.0 };
    println!("{:.1}F", t.fahrenheit());
}

Growing a shopping cart

An online store adds items to a cart every time the shopper clicks “add to cart” — that’s a change, so it needs &mut self.

struct Cart {
    items: Vec<String>,
}

impl Cart {
    fn add_item(&mut self, item: &str) {
        self.items.push(item.to_string());
    }
}

fn main() {
    let mut cart = Cart { items: Vec::new() };
    cart.add_item("keyboard");
    cart.add_item("mouse");
    println!("{:?}", cart.items);
}

Unwrapping a sealed envelope

Once you open a sealed envelope you can’t reseal it — some methods should consume their value and hand back what’s inside, never to be used again.

struct Envelope {
    letter: String,
}

impl Envelope {
    fn open(self) -> String {
        self.letter
    }
}

fn main() {
    let envelope = Envelope { letter: String::from("You got the job!") };
    let letter = envelope.open();
    println!("{letter}");
    // envelope can't be used anymore — it was consumed by open()
}

Building a user profile from parts

A constructor gathers scattered inputs — a name, an age — into one valid struct, so callers never have to build a UserProfile field-by-field.

struct UserProfile {
    name: String,
    age: u32,
}

impl UserProfile {
    fn new(name: &str, age: u32) -> UserProfile {
        UserProfile { name: name.to_string(), age }
    }
}

fn main() {
    let user = UserProfile::new("Priya", 29);
    println!("{} is {}", user.name, user.age);
}

Configuring a server before it starts

Chaining self-consuming methods that each return Self lets you configure an object step by step, like ServerConfig::new().with_port(8080).

struct ServerConfig {
    port: u16,
    debug: bool,
}

impl ServerConfig {
    fn new() -> ServerConfig {
        ServerConfig { port: 80, debug: false }
    }

    fn with_port(mut self, port: u16) -> ServerConfig {
        self.port = port;
        self
    }

    fn with_debug(mut self, debug: bool) -> ServerConfig {
        self.debug = debug;
        self
    }
}

fn main() {
    let config = ServerConfig::new().with_port(8080).with_debug(true);
    println!("port={} debug={}", config.port, config.debug);
}

Your turn

This program defines a BankAccount with a deposit method, but it won’t compile. The deposit method can’t change the balance, and the account it’s called on isn’t declared right. Fix both. Press ▶ Run.

struct BankAccount {
    balance: u32,
}

impl BankAccount {
    fn deposit(&self, amount: u32) {
        self.balance += amount;
    }
}

fn main() {
    let account = BankAccount { balance: 100 };
    account.deposit(50);
    println!("balance is {}", account.balance);
}

struct BankAccount {
    balance: u32,
}

impl BankAccount {
    fn deposit(&mut self, amount: u32) {
        self.balance += amount;
    }
}

fn main() {
    let mut account = BankAccount { balance: 100 };
    account.deposit(50);
    println!("balance is {}", account.balance); // 150
}

Quick check

Remember this

• Methods live in an impl Type { ... } block and take a receiver as their first parameter.
• &self borrows to read (most methods), &mut self borrows to change, self consumes the value (rare).
• Calling a &mut self method requires the variable to be mut.
• Associated functions have no self (often constructors like new) and are called with Type::function().
• Method calls use a dot (value.method()); associated functions use :: (Type::func()). String::from is a familiar example.

Go deeper

• Rust Book - Methods — Receiver forms and impl blocks.

Next:

• Traits
• Generics

Ownership

Intermediate · Ownership

What & why

Ownership is the idea that makes Rust different. It’s how Rust keeps your program’s memory safe without a garbage collector and without you calling free() by hand. It feels strange for a few days, and then it clicks and the rest of the language suddenly makes sense. This is the lesson worth going slow on.

The idea, slowly

The problem every language has to solve

Your program uses memory to hold values — a string, a list, a picture. At some point that memory has to be given back, or your program leaks and slowly eats the machine. Languages solve this in different ways:

• Some (Python, JavaScript, Java) run a garbage collector: a background process that occasionally pauses your program and cleans up. Easy for you, but it costs speed and control.
• Some (C, C++) make you free memory by hand. Fast, but forget once and you get crashes and security holes.

Rust picks a third path: ownership rules that the compiler checks for you, before the program ever runs. No pauses, no manual freeing, no leaks. The catch is you have to learn the rules.

The three rules

1. Every value has exactly one owner (a variable that owns it).
2. There can only be one owner at a time.
3. When the owner goes out of scope (its { } block ends), the value is dropped — its memory is freed automatically.

Think of a value like a physical object and the owner like the person holding it. Only one person holds it at a time. When that person leaves the room, the object is thrown away.

“Move”: handing the object over

Watch what happens when you assign one variable to another:

fn main() {
    let s1 = String::from("hello");
    let s2 = s1;               // the value MOVES from s1 to s2
    println!("{}", s2);        // fine — s2 owns it now
    // println!("{}", s1);     // ERROR if you uncomment: s1 no longer owns anything
}

let s2 = s1; does not make a copy of the string. It moves ownership from s1 to s2. After the move, s1 is empty — using it is a compile error. Rust does this so two variables can never both think they own (and both try to free) the same memory.

Uncomment the s1 line and press Run. Read the error. The compiler literally says value borrowed here after move. That message is your friend — it’s Rust catching a bug for you at compile time instead of at 2am in production.

Why doesn’t this happen with numbers?

fn main() {
    let x = 5;
    let y = x;                 // x is COPIED, not moved
    println!("x = {}, y = {}", x, y);  // both work fine!
}

Small, fixed-size values like integers implement a trait called Copy. They’re so cheap to duplicate that Rust just copies them instead of moving. So x is still usable. The rule of thumb: simple stack values (numbers, bool, char) copy; things that own heap data (like String, Vec) move.

Moving into a function

Passing a value to a function moves it too, unless it’s a Copy type:

fn main() {
    let s = String::from("hi");
    takes_it(s);               // s is moved INTO the function
    // println!("{}", s);      // ERROR: s was moved away
}

fn takes_it(text: String) {
    println!("got: {}", text);
} // text goes out of scope here and the String is dropped

This is annoying at first — “I just want to use the string, not give it away!” That’s exactly what the next lesson, borrowing, is for: a way to lend a value without giving up ownership.

Common mistakes

• Thinking assignment copies. For String, Vec, and most types, let b = a; moves. a is gone afterward. Don’t assume everything behaves like a number.
• “Use after move” errors. If the compiler says a value was “moved,” you tried to use a variable after its value went somewhere else. The fix is usually to borrow (next lesson) or to .clone() if you really do want a separate copy.
• Reaching for .clone() too fast. Cloning works but makes a full copy every time. Fine while learning; later you’ll prefer borrowing to avoid the cost.

More examples

Round-tripping a string through a function

Sometimes a function needs to transform a String and hand it right back, rather than just borrowing it — useful as one step in a small text-processing pipeline.

fn shout(mut text: String) -> String {
    text.push('!');
    text.to_uppercase()
}

fn main() {
    let message = String::from("hello");
    let message = shout(message); // ownership goes in, comes back out
    println!("{message}");
}

Moving a Vec into a background thread

Spawning a worker thread to crunch a batch of numbers means handing it full ownership of that data — the main thread can’t be trusted to keep using it while another thread works on it.

use std::thread;

fn main() {
    let numbers = vec![1, 2, 3, 4, 5];

    let handle = thread::spawn(move || {
        let total: i32 = numbers.iter().sum();
        println!("sum computed on another thread: {total}");
    });

    handle.join().unwrap();
    // numbers is gone here — it was moved into the closure
}

Ownership transfer through a struct field

Placing an order takes ownership of the customer’s shipping address — the struct becomes the new home for that String, and it moves along with the order.

struct Order {
    item: String,
    shipping_address: String,
}

fn main() {
    let address = String::from("221B Baker Street");
    let order = Order {
        item: String::from("teapot"),
        shipping_address: address, // address moves into the struct
    };
    println!("Shipping {} to {}", order.item, order.shipping_address);
}

Cloning when you genuinely need two independent copies

A template config should stay untouched while you customize a copy for a specific environment — cloning gives you two Vecs that can each change independently.

fn main() {
    let template = vec![String::from("debug=false"), String::from("port=80")];
    let mut staging = template.clone();
    staging.push(String::from("env=staging"));

    println!("template: {:?}", template); // untouched
    println!("staging: {:?}", staging);   // has the extra line
}

Your turn

This program doesn’t compile — it uses s after moving it into greet. Fix it so it prints the greeting and the length 5, without removing either println!. (Hint: one small .clone(), or think about what you learned — borrowing is coming in the next lesson.)

fn main() {
    let s = String::from("hello");
    greet(s);
    println!("the word was {} letters", s.len()); // error: s was moved
}

fn greet(word: String) {
    println!("Hi, {}!", word);
}

fn main() {
    let s = String::from("hello");
    greet(s.clone());          // hand over a copy
    println!("the word was {} letters", s.len()); // s is still ours
}

fn greet(word: String) {
    println!("Hi, {}!", word);
}

Quick check

Remember this

• Each value has exactly one owner; there’s only one owner at a time.
• When the owner’s scope ends, the value is dropped (memory freed) automatically.
• Assigning or passing an owning type (String, Vec, …) moves it; the old variable can’t be used afterward.
• Simple Copy types (numbers, bool, char) are copied instead of moved.
• To use a value without giving it away, borrow it — that’s the next lesson.

Go deeper

• Rust Book - Understanding Ownership — The main ownership chapter.

Next:

• Borrowing
• References and dereference
• Slices

Borrowing

Intermediate · Ownership

What & why

The last lesson ended on a frustrating note: passing a String into a function gives it away, and then you can’t use it anymore. Borrowing is the fix. It lets you lend a value to a function so it can look at it (or even change it) and then hand it back — no giving away, no copying, no cost. This is the “lend without giving away” idea from the Ownership lesson, made real.

The idea, slowly

The problem borrowing solves

Remember this from the last lesson? Passing s into a function moved it, and the line after broke:

fn main() {
    let s = String::from("hello");
    greet(s);                         // s is MOVED into greet
    // println!("{}", s.len());       // ERROR: s was given away
}

fn greet(word: String) {
    println!("Hi, {}!", word);
}

That’s a lot of ceremony just to look at a string. In real life, if a friend wants to read your book, you don’t sign the book over to them forever — you lend it, they read it, they give it back. Rust has exactly that: a reference, written with an ampersand &.

Lending with &

A reference is a way to say “let this function use my value without taking ownership of it.” You create one by putting & in front of the value, and the function says it wants one by putting & in front of the type:

fn main() {
    let s = String::from("hello");
    greet(&s);                                    // lend s (don't give it away)
    println!("the word was {} letters", s.len()); // s is STILL OURS — works!
}

fn greet(word: &String) {                          // "word" is a reference, not owned
    println!("Hi, {}!", word);
}

Run this. It prints the greeting and the length. Nothing moved. That’s the whole point of borrowing: &s hands the function a reference to the string, s keeps ownership, and after greet finishes you can keep using s normally.

The act of making and using a reference is called borrowing. You “borrow” the value, the same way your friend borrows the book. And just like a borrowed book, there are rules about what you’re allowed to do with something you don’t own.

What the compiler is thinking

When the function takes &String, the compiler thinks: “This function is only borrowing. It does not own this string, so when the function ends, it must NOT free the memory — the real owner back in main is still using it.” When the function takes a plain String, the compiler thinks the opposite: “This function now owns it; when the function ends, drop it.” That one little & is what tells Rust which of those two stories is true.

Read-only by default: &

A plain & borrow is read-only. You can look, but you can’t change:

fn main() {
    let s = String::from("hello");
    let len = measure(&s);
    println!("{} is {} chars", s, len);
}

fn measure(word: &String) -> usize {
    word.len()          // reading is fine
    // word.push('!');  // ERROR: can't change a value you only borrowed read-only
}

This is like borrowing a library book: you may read it, but you may not scribble in it. If you try to change it, the compiler stops you with cannot borrow ... as mutable.

When you DO want to change it: &mut

Sometimes you want the function to change your value — say, add an exclamation mark. For that you need a mutable borrow, written &mut. Three things all have to line up:

1. The original variable must be declared mut (it has to be changeable in the first place).
2. You pass it with &mut.
3. The function accepts &mut.

fn main() {
    let mut s = String::from("hello");   // 1. must be mut
    add_excitement(&mut s);              // 2. lend it mutably
    println!("{}", s);                   // prints: hello!
}

fn add_excitement(word: &mut String) {   // 3. accepts &mut
    word.push('!');                      // now changing it is allowed
}

The value is still owned by main the whole time. We only lent the right to change it for the duration of the call, then took it back. This is like lending your friend a pencil-and-paper form and saying “go ahead, fill it in” — they modify your thing, but it’s still yours.

The one big rule: one writer, or many readers

Here’s the rule that trips everyone up, so read it slowly. At any given moment, for one value, you can have either:

• any number of read-only (&) borrows — many readers are fine, OR
• exactly one mutable (&mut) borrow — one writer, and nobody else.

You can never have a &mut at the same time as any other borrow. Why? Imagine one part of your code is reading a list while another part is deleting items from it — the reader would see garbage. Rust forbids that situation at compile time so it can never happen while the program runs.

fn main() {
    let mut s = String::from("hello");

    let r1 = &s;      // reader 1
    let r2 = &s;      // reader 2 — fine, many readers allowed
    println!("{} and {}", r1, r2);   // last use of r1 and r2

    let w = &mut s;   // now a writer — allowed, because r1/r2 are done being used
    w.push('!');
    println!("{}", w);
}

Think of it as a shared document: lots of people can read it at the same time, but the moment someone wants to edit, everyone else has to step away. Rust enforces this so your data can never change underneath you while you’re looking at it.

Common mistakes

• Forgetting & on both sides. If the value is &s but the function still says word: String, or vice versa, the types don’t match and you get mismatched types: expected String, found &String. The & has to be on the value and on the parameter type.
• Trying to mutate through a plain & borrow. A read-only borrow can’t call methods that change the value (like .push). The error is cannot borrow ... as mutable, as it is behind a & reference. Fix: use &mut everywhere and make the original variable mut.
• A &mut while another borrow is alive. cannot borrow ... as mutable because it is also borrowed as immutable means you still have a reader hanging around. The fix is usually to stop using the earlier reference before you start the mutable one.
• Forgetting mut on the variable itself. You can’t take a &mut of something that was never declared mut. The error points you back to the let and says to add mut.

More examples

Reading a cart’s size without taking it

A dashboard needs to show how many items are in the cart without taking the cart away from the checkout logic that still needs it.

fn summarize(items: &Vec<String>) -> usize {
    items.len()
}

fn main() {
    let cart = vec![String::from("pen"), String::from("notebook")];
    println!("{} items in cart", summarize(&cart));
    println!("still have it: {:?}", cart);
}

Restocking a shelf through a mutable borrow

A warehouse restock function needs to add new items to an existing inventory list without taking ownership of the whole warehouse.

fn restock(inventory: &mut Vec<&str>) {
    inventory.push("stapler");
}

fn main() {
    let mut inventory = vec!["paper", "pens"];
    restock(&mut inventory);
    println!("{:?}", inventory);
}

Doubling every score in place

A game engine wants to apply a 2x multiplier to every player’s score after a bonus round, editing the list it was given rather than building a new one.

fn double_all(scores: &mut Vec<i32>) {
    for score in scores.iter_mut() {
        *score *= 2;
    }
}

fn main() {
    let mut scores = vec![10, 20, 30];
    double_all(&mut scores);
    println!("{:?}", scores);
}

Why two &mut borrows can’t coexist

Imagine two parts of a program both trying to hand out edit access to the same balance at once — Rust catches that at compile time before it becomes a real bug.

fn main() {
    let mut balance = 100;

    let r1 = &mut balance;
    let r2 = &mut balance; // ERROR: second mutable borrow while r1 is still alive

    println!("{} {}", r1, r2);
}

Borrowing one field while another stays free

A player struct has a name (read for the scoreboard) and a score (updated after each round). Rust lets you borrow each field independently at the same time, since they don’t overlap.

struct Player {
    name: String,
    score: u32,
}

fn main() {
    let mut player = Player { name: String::from("Kai"), score: 0 };

    let name_ref = &player.name;       // borrow just the name field
    let score_ref = &mut player.score; // borrow just the score field, mutably
    *score_ref += 10;

    println!("{name_ref} now has {score_ref} points");
}

Your turn

This program wants to add a "." to the end of the sentence, then print it. It doesn’t compile. Fix it so it prints learning rust. (Hint: three things have to line up for a mutable borrow.)

fn main() {
    let sentence = String::from("learning rust");
    finish(sentence);
    println!("{}", sentence);
}

fn finish(text: &String) {
    text.push('.');
}

fn main() {
    let mut sentence = String::from("learning rust");  // must be mut
    finish(&mut sentence);                             // lend it mutably
    println!("{}", sentence);                          // still ours — prints: learning rust.
}

fn finish(text: &mut String) {   // accept a mutable borrow
    text.push('.');              // now allowed to change it
}

Quick check

Remember this

• A reference (&) lets a function use a value without taking ownership — it borrows, then gives it back.
• Plain & is read-only; &mut lets you change the value (and needs the original to be mut).
• The rule: at one time you may have many readers or one writer, never both.
• Borrowing costs nothing and moves nothing — reach for it before you reach for .clone().

Go deeper

• Rust Book - References and Borrowing — Borrowing rules.

Next:

• References and dereference
• Slices
• Lifetimes

References and dereference

Intermediate · Ownership

What & why

In the Borrowing lesson you used & to lend values around. This lesson slows down and looks at what a reference actually is, and introduces its partner symbol * (dereference) — the way to reach through a reference to touch the value on the other end. Once these two clicks, the & and * you see everywhere in Rust stop looking like magic.

The idea, slowly

A reference is a signpost

A reference doesn’t contain the value. It points at the value, the way a signpost doesn’t contain a town — it just points to where the town is. When you write &value, you make a signpost that says “the real thing is over there.”

fn main() {
    let x = 10;
    let r = &x;        // r is a reference — a signpost pointing at x
    println!("x is {}", x);
    println!("r points at {}", r);   // Rust follows the signpost for you when printing
}

Both lines print 10. x is the value; r is a signpost to it. Notice you didn’t need any special symbol to print through r — println! is polite and follows the signpost automatically. But not everything does, and that’s where * comes in.

* follows the signpost

* means “go to where this reference points and give me the actual value there.” It’s called dereferencing — literally “un-referencing,” reaching through the pointer.

Watch what happens with arithmetic, where Rust will not silently follow the signpost:

fn main() {
    let x = 10;
    let r = &x;

    // println!("{}", r + 1);   // ERROR: r is a signpost, not a number
    println!("{}", *r + 1);     // *r follows the signpost to get 10, then + 1 = 11
}

r by itself is a reference (a &i32), and you can’t add 1 to a signpost. *r says “follow it, get the 10,” and then + 1 works. The mental move is: & makes a reference, * follows it back to the value. They are opposites.

Changing a value through a &mut reference

Dereferencing really earns its keep with mutable references. To change the value a &mut points at, you dereference with * and assign:

fn main() {
    let mut count = 5;
    let r = &mut count;   // a mutable signpost to count

    *r += 1;              // follow the signpost, add 1 to the real value

    println!("{}", count);   // prints 6
}

*r += 1 reads as: “go to where r points (that’s count) and add 1 there.” Without the *, you’d be trying to add 1 to the signpost itself, which is meaningless — and the compiler says so.

Why do methods like .len() not need *?

You may have noticed that in the Borrowing lesson you called word.len() on a &String and never wrote a *. That’s because Rust does a helpful automatic step called deref coercion: when you call a method with ., Rust will quietly follow references for you as many times as needed to find the method. So word.len() works whether word is a String or a &String or even a &&String.

fn main() {
    let s = String::from("atlas");
    let r = &s;

    println!("{}", s.len());   // 5
    println!("{}", r.len());   // 5 — Rust auto-follows the reference for the method call
}

The rule of thumb: the dot operator (.) follows references for you automatically; bare operators like +, +=, and == do not. So you mostly need * for arithmetic and assignment through a reference, and rarely for method calls.

&str vs &String: a tiny preview

You’ll often see &str where you might expect &String. A &str is a reference to string text — a very common, lightweight “view” of characters. Because of deref coercion, a &String can be used almost anywhere a &str is wanted, so this just works:

fn main() {
    let owned = String::from("hello");
    shout(&owned);            // &String is accepted where &str is asked for
}

fn shout(text: &str) {        // prefer &str for read-only text parameters
    println!("{}!", text.to_uppercase());
}

Don’t worry about mastering &str yet — the Slices lesson (next) explains exactly what it is. For now just know: writing your read-only text parameters as &str makes your functions accept more kinds of callers, and you can pass a &String right in.

Common mistakes

• Using a reference where a value is needed. Writing r + 1 when r is &i32 gives cannot add {integer} to &{integer}. You forgot to dereference — use *r + 1.
• Adding * where the . already handles it. You rarely need (*r).len(); just write r.len(). Over-dereferencing is a common beginner habit — let the dot do its job.
• Trying *r = ... through a read-only &. You can only assign through a &mut. Assigning through a plain & gives cannot assign to ... behind a & reference. Make it &mut.
• Confusing & and * directions. & creates a reference (value → signpost); * follows one (signpost → value). If a line feels backwards, check which direction you actually want.

More examples

Comparing two prices through references

A price-comparison tool receives two prices by reference (so it doesn’t have to own them) and needs to check whether they’re equal.

fn same_price(a: &f64, b: &f64) -> bool {
    *a == *b
}

fn main() {
    let price1 = 19.99;
    let price2 = 19.99;
    println!("{}", same_price(&price1, &price2));
}

Returning a reference derived from a parameter

A leaderboard function wants to hand back a reference to the top entry without copying the whole list.

fn first_entry(scores: &Vec<i32>) -> &i32 {
    &scores[0]
}

fn main() {
    let scores = vec![99, 87, 65];
    println!("top score: {}", first_entry(&scores));
}

Auto-deref through multiple reference layers

Passing a reference to a reference around (common when values get threaded through iterators or nested calls) still lets you call methods normally — Rust peels off as many layers as it needs.

fn main() {
    let x: i32 = 5;
    let r = &x;
    let rr = &r; // rr is a &&i32

    println!("{}", rr.pow(2)); // Rust auto-derefs &&i32 -> &i32 -> i32 to find pow
}

Bumping a retry counter through a mutable reference

A network client tracks how many times it has retried a request, and the retry function only gets a &mut i32 — not ownership — so it must dereference to change it.

fn record_retry(attempts: &mut i32) {
    *attempts += 1;
}

fn main() {
    let mut attempts = 0;
    record_retry(&mut attempts);
    record_retry(&mut attempts);
    println!("retried {} times", attempts);
}

Swapping two values through mutable references

Keeping a scoreboard’s two top entries in descending order means occasionally swapping them in place, touching nothing but the two numbers themselves.

fn swap_if_out_of_order(a: &mut i32, b: &mut i32) {
    if *a < *b {
        let temp = *a;
        *a = *b;
        *b = temp;
    }
}

fn main() {
    let mut first = 10;
    let mut second = 42;
    swap_if_out_of_order(&mut first, &mut second);
    println!("{first} {second}");
}

Your turn

This program tries to double a number through a mutable reference, but it doesn’t compile. Fix it so it prints 8.

fn main() {
    let mut n = 4;
    let r = &mut n;
    r = r * 2;
    println!("{}", n);
}

fn main() {
    let mut n = 4;
    let r = &mut n;
    *r = *r * 2;      // follow the signpost on both sides: n becomes 4 * 2
    println!("{}", n); // prints 8
}

Quick check

Remember this

• A reference (&) is a signpost that points at a value; it doesn’t hold the value itself.
• * dereferences — it follows the signpost back to the actual value.
• & and * are opposites: one makes a reference, the other follows it.
• The dot operator (.) auto-follows references for method calls; bare operators like + and = need you to write * yourself.

Go deeper

• Rust by Example - Deref — Reference patterns and deref thinking.

Next:

• Slices
• Lifetimes
• Smart pointers

Slices

Intermediate · Ownership

What & why

A slice is a borrowed view into part of a collection — a piece of a string or an array — without copying it and without owning it. It’s how you say “just this middle chunk” and pass it around cheaply. Slices are everywhere in Rust, and they’re the thing the mysterious &str type actually is.

The idea, slowly

A window onto a row of boxes

Picture a String as a row of labelled boxes, one per byte of text:

 h   e   l   l   o
 0   1   2   3   4

A slice is a window you slide over that row to see just some of the boxes — say boxes 0, 1, 2. The window doesn’t copy the boxes and doesn’t own them; it just says “look here, from this box up to that box.” You make one with &thing[start..end]:

fn main() {
    let s = String::from("hello");
    let hi = &s[0..2];    // a window over boxes 0 and 1: "he"
    let lo = &s[2..5];    // boxes 2,3,4: "llo"
    println!("{} + {}", hi, lo);   // he + llo
}

The range 0..2 means start at 0, stop before 2 — so it includes 0 and 1, not 2. That “stop before the end number” rule is the one to burn into memory; it’s the same everywhere ranges appear in Rust.

The & matters: a slice is a borrow

Notice the & in &s[0..2]. A slice is a kind of reference — a borrow — so all the borrowing rules from two lessons ago still apply. The slice points into s’s memory; it does not own it. That’s why it’s cheap (nothing is copied) and why it can’t outlive s (more on that in the mistakes section).

Handy shortcuts for the ends

You can leave off a number to mean “the very start” or “the very end”:

fn main() {
    let s = String::from("hello");
    println!("{}", &s[..2]);    // from the start up to 2  -> "he"
    println!("{}", &s[2..]);    // from 2 to the end       -> "llo"
    println!("{}", &s[..]);     // the whole thing         -> "hello"
}

&s[..] (the whole string as a slice) is common when a function wants a slice and you have the whole string.

Meet &str: the string slice

Here’s the payoff. That &str type you keep seeing? A &str is a string slice — a borrowed window into string text. When you slice a String, the result is a &str. And a plain text literal like "hello" in your code is also a &str (it’s a window into text baked into your program). So these are the same type:

fn main() {
    let owned = String::from("hello world");
    let piece: &str = &owned[0..5];   // "hello", a slice of the String
    let literal: &str = "hello";      // also a &str, baked into the program

    println!("{} == {} is {}", piece, literal, piece == literal);  // true
}

This is why the last lesson said to write read-only text parameters as &str: it accepts both literals and slices of Strings (and, thanks to deref coercion, whole &Strings too). One parameter type, lots of callers.

A real reason to slice: return part of a string

Say you want the first word of a sentence. Instead of copying characters into a new String, you return a slice — a window onto the original text. No allocation, no copy:

fn main() {
    let sentence = String::from("learning rust today");
    let word = first_word(&sentence);
    println!("first word: {}", word);   // learning
}

fn first_word(s: &str) -> &str {
    for (i, ch) in s.char_indices() {
        if ch == ' ' {
            return &s[..i];    // window from start up to the first space
        }
    }
    s                          // no space found: the whole thing is one word
}

first_word returns a &str that borrows from sentence — a view, not a copy. This is the classic example of why slices exist.

Slices work on arrays too

Slices aren’t just for strings. Any array or Vec can be sliced the same way, giving a &[T] (a borrowed window over a sequence of T):

fn main() {
    let numbers = [10, 20, 30, 40, 50];
    let middle = &numbers[1..4];   // a window over 20, 30, 40
    println!("{:?}", middle);      // [20, 30, 40]
    println!("sum = {}", middle.iter().sum::<i32>());   // 90
}

Same idea, same start..end rule, same “it’s a borrow” behavior. Whenever a function only needs to read a run of items, taking a slice (&[T] or &str) is the idiomatic choice — it works whether the caller has an array, a Vec, or another slice.

Common mistakes

• Off-by-one from the exclusive end. &s[0..2] gives you indices 0 and 1, not 2. Forgetting that the end is exclusive is the #1 slice bug. [..2] = “the first two.”
• Slicing a string in the middle of a character. Rust strings are UTF-8 bytes, and some characters (like é or emoji) take more than one byte. Slicing between the bytes of one character panics at runtime with byte index ... is not a char boundary. For plain ASCII (a-z, 0-9) every character is one byte, so you’re safe; just be careful with accented or non-Latin text.
• Index out of range. &s[0..99] on a 5-byte string panics with byte index 99 is out of range. A slice can’t point past the end of what it borrows.
• Letting the owner die first. A slice borrows from a value, so it can’t outlive that value. If you drop or move the original String while a slice of it is still in use, the compiler stops you — the window would be pointing at boxes that no longer exist.

More examples

Grabbing the middle innings of a game log

A sports app stores scores for every inning but only wants to show innings 3 through 5 without copying the whole game.

fn main() {
    let innings = vec![1, 0, 2, 3, 0, 1, 4];
    let middle = &innings[2..5];
    println!("{:?}", middle);
}

A function that works with arrays and Vecs alike

A stats helper shouldn’t care whether the caller has a fixed-size array or a growable Vec — accepting a slice lets it work with both.

fn average(nums: &[f64]) -> f64 {
    nums.iter().sum::<f64>() / nums.len() as f64
}

fn main() {
    let fixed = [1.0, 2.0, 3.0];
    let growable = vec![4.0, 5.0, 6.0, 7.0];
    println!("{}", average(&fixed));
    println!("{}", average(&growable));
}

Splitting a sentence into words

A search box wants each word a user typed on its own, so it can match them individually against an index.

fn main() {
    let query = String::from("best rust books for beginners");
    let words: Vec<&str> = query.split_whitespace().collect();
    println!("{:?}", words);
}

Splitting a buffer into two mutable halves

A packet buffer needs its header and payload processed separately, in place, without copying — split_at_mut hands back two non-overlapping mutable slices.

fn main() {
    let mut buffer = [1, 2, 3, 4, 5, 6];
    let (header, payload) = buffer.split_at_mut(2);
    header[0] = 99;
    payload[0] = 42;
    println!("header: {:?}, payload: {:?}", header, payload);
}

Dealing a deck into hands

A card game needs to split a shuffled deck into equal-sized hands without allocating a new Vec for each one.

fn main() {
    let deck: Vec<i32> = (1..=10).collect();
    let hands: Vec<&[i32]> = deck.chunks(5).collect();
    for hand in &hands {
        println!("{:?}", hand);
    }
}

Your turn

This program wants to print the first three letters, rus. It doesn’t compile. Fix it.

fn main() {
    let word = String::from("rust");
    let start = word[0..3];
    println!("{}", start);
}

fn main() {
    let word = String::from("rust");
    let start = &word[0..3];    // a borrowed window: "rus"
    println!("{}", start);
}

Quick check

Remember this

• A slice is a borrowed view into part of a collection — no copy, no ownership.
• Make one with &thing[start..end]; the end index is exclusive (stops before it).
• &str is a string slice — that’s why text literals and slices of a String share the type.
• Slices work on arrays and Vecs too, giving &[T]; prefer slice parameters for read-only access.
• A slice can’t outlive the value it borrows from.

Go deeper

• Rust Book - Slices — Borrowing part of a value.

Next:

• Lifetimes
• Collections

Lifetimes

Intermediate · Ownership

What & why

A lifetime is Rust’s way of tracking how long a reference stays valid — how long the thing it points at is guaranteed to exist. Most of the time Rust figures this out silently and you never write a lifetime at all. This lesson is about the handful of times you do have to write one, so that when you meet the strange-looking 'a syntax it feels ordinary instead of terrifying.

The idea, slowly

The danger lifetimes protect against

Think back to slices and references: a reference is a signpost pointing at a value it doesn’t own. Now imagine the value gets thrown away while the signpost still exists. The signpost would point at nothing — an empty lot where the house used to be. Reading through it would be a serious bug (in C this is the infamous “dangling pointer”; it causes crashes and security holes).

Rust makes that impossible. This does not compile:

fn main() {
    let r;
    {
        let value = 42;
        r = &value;        // r points at value...
    }                      // ...but value is dropped HERE, at the end of the block
    // println!("{}", r);  // ERROR: r would point at something that no longer exists
}

The compiler says value does not live long enough. It has been tracking, for every reference, the “lifetime” of the thing it points at, and it noticed r tries to outlive value. That tracking is what lifetimes are. Usually it happens completely behind the scenes.

Lifetimes are a description, not a command

Here is the single most important sentence in this lesson: a lifetime annotation does not make anything live longer. It only describes a relationship that already exists. Writing 'a is like labelling two boxes “these go together” — it doesn’t create anything, it just tells the compiler how the pieces relate so it can check them. If you remember nothing else, remember that.

When Rust needs your help

Rust can figure lifetimes out on its own almost always. The exception is when a function returns a reference and there’s more than one reference coming in — because then Rust can’t tell which input the output borrows from. Look at this function that returns the longer of two strings:

fn main() {
    let a = String::from("short");
    let b = String::from("a longer one");
    let result = longest(&a, &b);
    println!("longest is: {}", result);
}

fn longest<'a>(left: &'a str, right: &'a str) -> &'a str {
    if left.len() > right.len() {
        left
    } else {
        right
    }
}

The returned &str borrows from either left or right — the compiler genuinely cannot tell which, because it depends on the lengths at runtime. So it asks you to spell out the relationship. That’s what the 'as do.

Reading the 'a syntax out loud

Let’s decode fn longest<'a>(left: &'a str, right: &'a str) -> &'a str slowly:

• <'a> — “I’m introducing a lifetime name called a.” The apostrophe is just Rust’s way of writing lifetime names; 'a is read “tick-a.” It’s a made-up label, like a variable name. You could call it 'thing, but everyone uses short names like 'a.
• left: &'a str — “left is a reference that lives at least as long as 'a.”
• right: &'a str — “right also lives at least as long as 'a.”
• -> &'a str — “the reference I return also lives as long as 'a.”

Put together, you’re telling the compiler: “The thing I hand back borrows from these inputs, so it’s only valid for as long as both of them are valid.” Now the compiler has enough information to check every call and reject any that would keep the result alive too long.

Seeing it catch a real bug

Because you told the compiler the result borrows from the inputs, it can now stop you from misusing it. This does not compile, and that’s a good thing:

fn main() {
    let a = String::from("short");
    let result;
    {
        let b = String::from("a longer one");
        result = longest(&a, &b);   // result might borrow from b
    }                               // b is dropped here
    // println!("{}", result);      // ERROR: result could be pointing at dropped b
}

fn longest<'a>(left: &'a str, right: &'a str) -> &'a str {
    if left.len() > right.len() { left } else { right }
}

Without the lifetime, Rust couldn’t have known result might depend on b. With it, the compiler connects the dots and refuses to let result outlive b. The 'a didn’t change how the program runs — it gave the compiler the information to catch the mistake.

Why you’ve rarely seen this before

You wrote functions with references for two whole lessons without a single 'a. That’s because Rust has built-in shortcuts (called elision rules) that fill lifetimes in automatically for the common, unambiguous cases — like a function taking one reference and returning one. You only reach for explicit 'a when the relationship is genuinely ambiguous, as with two inputs and a borrowed output. So: don’t go sprinkling 'a everywhere. Write your code normally, and add lifetimes only when the compiler asks — its error message will even suggest the annotation.

Common mistakes

• Thinking 'a extends how long data lives. It does not allocate or prolong anything. If your data is dropped too early, adding lifetimes won’t save it — you have to restructure so the data lives long enough (e.g. return an owned String instead of a borrow).
• Adding lifetimes before the compiler asks. Rust’s elision handles most cases. Annotating everything by hand is noise and often wrong. Write it plain first; add 'a only when you see missing lifetime specifier.
• Returning a reference to a local variable. A function can’t return a reference to something it created inside itself — that local is dropped when the function ends. The error is cannot return reference to local variable. The fix is usually to return the owned value (String) instead of a &str.
• Reading 'a as a type. 'a is not a type like i32; it’s a label for a duration. It goes in the <...> alongside generic type parameters but means “how long,” not “what kind.”

More examples

A struct holding two independently-lived references

A search result might pair a snippet from a document with a highlighted term from a completely separate query string — the two don’t have to share a lifespan.

struct Match<'a, 'b> {
    snippet: &'a str,
    term: &'b str,
}

fn main() {
    let document = String::from("Rust makes systems programming approachable");
    let query = String::from("systems");
    let m = Match { snippet: &document[5..], term: &query };
    println!("found '{}' in: {}", m.term, m.snippet);
}

Picking a display name, with a tie-break rule

A profile page shows the longer of a user’s nickname or real name, but on a tie it should prefer the nickname — deepening the classic “return the longer slice” example with real logic.

fn pick_display_name<'a>(nickname: &'a str, real_name: &'a str) -> &'a str {
    if nickname.len() >= real_name.len() {
        nickname
    } else {
        real_name
    }
}

fn main() {
    let nickname = String::from("Kai");
    let real_name = String::from("Kai Anderson");
    println!("{}", pick_display_name(&nickname, &real_name));
}

A generic function with a lifetime bound

Finding the largest item in a list of scores or prices works the same way regardless of the item type, as long as you can compare them — and the result still borrows from the original list.

fn largest<'a, T: PartialOrd>(items: &'a [T]) -> &'a T {
    let mut max = &items[0];
    for item in items {
        if item > max {
            max = item;
        }
    }
    max
}

fn main() {
    let prices = [12.5, 8.0, 21.75, 15.0];
    println!("highest price: {}", largest(&prices));
}

Why returning a reference to a local variable fails

This is the shape of the mistake lifetimes exist to prevent — shown here as a description, not code you can run:

#![allow(unused)]
fn main() {
fn make_greeting(name: &str) -> &str {
    let greeting = format!("Hello, {name}!"); // greeting is LOCAL to this function
    &greeting
    // ERROR: cannot return reference to local variable `greeting`.
    // `greeting` is dropped the instant this function ends, so any reference
    // to it would dangle immediately. No lifetime annotation can fix this —
    // the real fix is to return the owned `String` itself (drop the `&`).
}
}

Your turn

This function is supposed to return the first of two string slices, but it won’t compile. The compiler says it’s missing lifetime specifier. Add what it needs.

fn main() {
    let a = String::from("first");
    let b = String::from("second");
    println!("{}", pick(&a, &b));
}

fn pick(x: &str, y: &str) -> &str {
    x
}

fn main() {
    let a = String::from("first");
    let b = String::from("second");
    println!("{}", pick(&a, &b));
}

fn pick<'a>(x: &'a str, y: &'a str) -> &'a str {
    x
}

Quick check

Remember this

• A lifetime tracks how long a reference is valid — Rust uses it to forbid dangling references.
• A lifetime annotation describes a relationship; it never makes data live longer.
• You mostly need explicit 'a only when a function returns a reference and takes more than one.
• 'a is a label for a duration, written in <...>, read “tick-a.”
• Write code plainly first and add lifetimes only when the compiler asks for them.

Go deeper

• Rust Book - Validating References with Lifetimes — Where lifetime syntax is introduced.

Next:

• Smart pointers
• Traits

Lifetime elision and ’static

Advanced · Ownership

What & why

Lifetimes are the compiler’s sticky notes for references: “this borrow is only good for as long as X.” Most functions that take and return references never write one down, because three simple rules cover the shapes that show up constantly — the compiler fills in the sticky note itself. This page covers those rules, what happens when a struct needs to hold a reference, and the much-misunderstood 'static — which means “can live for the whole program,” not “is a global.”

The idea, slowly

A quick reminder of why lifetimes exist

A reference can never outlive the data it points to — that’s the core rule the borrow checker enforces. Sometimes a function’s signature needs to describe how an output reference relates to the input references it came from:

fn longest<'a>(a: &'a str, b: &'a str) -> &'a str {
    if a.len() >= b.len() { a } else { b }
}

fn main() {
    let s1 = String::from("hello");
    let s2 = String::from("hi");
    println!("{}", longest(&s1, &s2));
}

<'a> here says: “the returned reference lives no longer than the shorter of a and b’s lifetimes” — the compiler needs that written down because there are two input references, and it can’t guess which one the output borrows from.

The three elision rules

Writing <'a> everywhere would be exhausting, so the compiler applies three rules first, and only asks you to annotate when they don’t produce a complete answer:

1. Each elided (unwritten) reference in the input gets its own distinct lifetime.
2. If there’s exactly one input lifetime, it’s assigned to every elided output lifetime.
3. If one of the inputs is &self or &mut self (i.e. this is a method), self’s lifetime is assigned to every elided output lifetime.

If none of these rules pin down the output, the compiler stops and asks you to write the lifetime yourself — which is exactly what happened with longest above (two input lifetimes, no &self, so rule 2 and rule 3 both fail to apply).

fn first_word(s: &str) -> &str {
    // desugars to: fn first_word<'a>(s: &'a str) -> &'a str   (rule 2)
    s.split_whitespace().next().unwrap_or("")
}

struct Wrapper {
    text: String,
}

impl Wrapper {
    fn text(&self) -> &str {
        // desugars to: fn text<'a>(&'a self) -> &'a str        (rule 3)
        &self.text
    }
}

fn main() {
    println!("{}", first_word("hello world"));

    let w = Wrapper { text: String::from("hi there") };
    println!("{}", w.text());
}

What the compiler is thinking: elision isn’t magic — it’s a fixed, mechanical desugaring that runs before borrow checking. fn first_word(s: &str) -> &str and fn first_word<'a>(s: &'a str) -> &'a str are the exact same function as far as the compiler is concerned; the first form just lets you skip typing something rule 2 would have inferred anyway.

A struct holding a borrowed reference

A struct that stores a reference has to say how long that reference — and therefore every instance of the struct — is allowed to live:

struct Excerpt<'a> {
    text: &'a str,
}

impl<'a> Excerpt<'a> {
    fn first_sentence(&self) -> &str {
        // elided via rule 3, and self's own lifetime is tied to 'a
        self.text.split('.').next().unwrap_or("")
    }
}

fn main() {
    let novel = String::from("Call me Ishmael. Some years ago...");
    let excerpt = Excerpt { text: &novel[..] };
    println!("{}", excerpt.first_sentence());
    // `excerpt` can't outlive `novel` — the compiler enforces that at compile time.
}

Excerpt<'a> says “an Excerpt can’t outlive the string slice it borrows from.” The compiler now rejects any code that would let excerpt be used after novel is dropped — the same guarantee a single borrowed reference gets, extended to a whole struct.

'static: string literals live for the whole program

fn greeting() -> &'static str {
    "hello, world" // string literals are baked into the compiled binary
}

fn main() {
    let s: &'static str = "I live forever";
    println!("{}", greeting());
    println!("{s}");
}

String literals have type &'static str because the text is embedded directly in the binary at compile time — it’s never freed, so it’s valid for the entire run of the program. This is the “obvious” meaning of 'static, and it’s the one people usually learn first.

'static in a trait bound: not “is global”

The confusing case is a bound like T: 'static on a generic function. It does not mean the value is a global constant that lives forever — it means “T contains no references that could expire early.” A type satisfies T: 'static either by owning all its data outright, or by only borrowing data that is itself 'static.

fn print_it<T: std::fmt::Debug + 'static>(value: T) {
    println!("{value:?}");
}

fn main() {
    let owned = String::from("owned data"); // a normal, short-lived local variable
    print_it(owned); // OK: `String` owns its bytes, so it satisfies 'static trivially

    let n = 5;
    print_it(n); // OK: i32 owns its data too
}

owned is an ordinary local String that will be dropped like any other value — nothing about it is “global.” It satisfies T: 'static simply because it doesn’t borrow anything with a shorter lifetime. Contrast that with an actual borrow:

fn print_it<T: std::fmt::Debug + 'static>(value: T) {
    println!("{value:?}");
}

fn main() {
    let text = String::from("short-lived");
    let borrowed: &str = &text;
    // print_it(borrowed); // ERROR: `borrowed` doesn't satisfy 'static
    println!("{borrowed}");
}

Uncommenting print_it(borrowed) fails to compile: &text only lives as long as text does, which is nowhere near 'static, so &str here can’t satisfy the bound. Swap it for an owned String (or a genuine &'static str, like a string literal) and it compiles again.

Common mistakes

• Reading 'static as “this is a global.” It means “no borrow inside this value expires before the program theoretically could end” — an owned String or i32 satisfies it trivially, even as a completely ordinary, short-lived local variable.
• Reaching for 'static to make a lifetime error disappear. It usually just relocates the bug — now you can’t pass in a borrowed value at all where a 'static bound is required. Prefer fixing the ownership (clone the data, or store an owned type) over forcing a 'static bound.
• Expecting elision to work with two-or-more distinct input references and no &self. The compiler won’t guess which input the output borrows from; that’s exactly when you must annotate explicitly, like longest<'a> above.
• Forgetting a struct that holds a reference needs a lifetime parameter at all. struct Excerpt { text: &str } alone doesn’t compile — the compiler demands a named lifetime so it knows how long an Excerpt is allowed to live.

More examples

Two elided input lifetimes with no relation

A logging helper takes a tag and a message as separate references but never ties them together in its return type — the compiler gives each its own lifetime and never needs them to match.

fn longer_len(a: &str, b: &str) -> usize {
    // desugars to fn longer_len<'a, 'b>(a: &'a str, b: &'b str) -> usize
    // 'a and 'b never need to relate, because nothing borrows from either in the return
    a.len().max(b.len())
}

fn main() {
    let tag = "INFO";
    let message = "server started";
    println!("{}", longer_len(tag, message));
}

A 'static string constant

An app’s version string is baked into the binary and needs to be readable from anywhere, for the entire run of the program.

static APP_VERSION: &str = "2.4.0";

fn main() {
    println!("running version {APP_VERSION}");
}

A generic function with a T: 'static bound

A simple type-erased cache needs to guarantee that whatever you hand it doesn’t contain a short-lived borrow, so it can hold onto the value safely.

use std::any::Any;

fn store<T: 'static>(value: T) -> Box<dyn Any> {
    Box::new(value)
}

fn main() {
    let boxed = store(String::from("cached result"));
    if let Some(text) = boxed.downcast_ref::<String>() {
        println!("{text}");
    }
}

A struct with a lifetime parameter used across two methods

A support ticket wraps a borrowed code string and offers two different views on it — a getter and a VIP check — both tied to the same lifetime.

struct Ticket<'a> {
    code: &'a str,
}

impl<'a> Ticket<'a> {
    fn code(&self) -> &str {
        self.code
    }

    fn is_vip(&self) -> bool {
        self.code.starts_with("VIP")
    }
}

fn main() {
    let raw = String::from("VIP-1234");
    let ticket = Ticket { code: &raw };
    println!("{} vip={}", ticket.code(), ticket.is_vip());
}

Where 'static shows up for real: spawning a thread

std::thread::spawn requires everything the closure captures to be 'static, because the new thread might outlive the function that spawned it — an owned value satisfies that automatically.

use std::thread;

fn main() {
    let report = String::from("nightly build passed");
    let handle = thread::spawn(move || {
        println!("{report}");
    });
    handle.join().unwrap();
}

Your turn

This struct is supposed to hold a borrowed word, but it’s missing something.

struct Highlight {
    word: &str, // missing lifetime specifier
}

fn main() {
    let text = String::from("Rust is fun");
    let h = Highlight { word: &text[0..4] };
    println!("{}", h.word);
}

struct Highlight<'a> {
    word: &'a str, // tied to whatever it borrows from
}

fn main() {
    let text = String::from("Rust is fun");
    let h = Highlight { word: &text[0..4] };
    println!("{}", h.word); // "Rust"
}

Quick check

Remember this

• Elision rule 1: every elided input reference gets its own lifetime.
• Elision rule 2: with exactly one input lifetime, it’s assigned to all elided outputs.
• Elision rule 3: with &self/&mut self, self’s lifetime is assigned to all elided outputs.
• When none of the rules apply (e.g. two input references, no &self), you must annotate the lifetime yourself.
• A struct holding a reference needs a lifetime parameter tying the struct’s validity to the data it borrows.
• 'static means “can live for the whole program” — string literals are 'static; a T: 'static bound just means T owns its data or only borrows 'static data, not that the value itself is global.

Go deeper

• Rust Reference - Lifetime elision — The exact elision rules.

Next:

• Smart pointers
• Traits

Traits

Intermediate · Abstractions

What & why

A trait is a list of things a type promises it can do. It lets you write one function that works with any type keeping that promise, instead of writing the same function over and over for each concrete type. If you’ve ever wished you could say “I don’t care what this thing actually is, as long as it can be printed / compared / summarized,” traits are how you say exactly that.

The idea, slowly

Think of a trait as a job description, not a family tree

“Barista” is a job description: anyone who can take an order, make a coffee, and hand it over can do the job. The job description doesn’t care whether you’re tall, short, or left-handed — it only lists the behavior required. A trait works the same way: it lists behavior (methods), and any type that provides that behavior “qualifies,” no matter how unrelated the types are otherwise.

Defining a trait, and implementing it for a type

A trait is a name plus a list of method signatures — the method’s shape, without a body:

trait Summary {
    fn summarize(&self) -> String;
}

struct Article {
    headline: String,
}

struct Tweet {
    handle: String,
    text: String,
}

impl Summary for Article {
    fn summarize(&self) -> String {
        format!("ARTICLE: {}", self.headline)
    }
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("@{}: {}", self.handle, self.text)
    }
}

fn main() {
    let a = Article { headline: String::from("Rust 2.0 announced") };
    let t = Tweet { handle: String::from("rustlang"), text: String::from("ship it") };

    println!("{}", a.summarize());
    println!("{}", t.summarize());
}

Read it slowly:

• trait Summary { fn summarize(&self) -> String; } says “anything that is Summary must have a summarize method that returns a String.” The ; after the signature means there’s no body — the trait only describes the promise, not how to keep it.
• impl Summary for Article { ... } is where Article actually keeps that promise. Tweet keeps the same promise in a completely different way. Neither type knows the other exists.
• &self borrows the value the method is called on — same & you’ve seen everywhere else.

What the compiler is thinking: when it sees a.summarize(), it looks for an impl Summary for Article block. Found it, method matches, done. Delete that impl block and the error becomes no method named 'summarize' found for struct 'Article' — the compiler is telling you the promise was never kept for that type.

Default method bodies: behavior for free

A trait method can come with a body. Any type that implements the trait gets that body automatically unless it chooses to override it:

trait Summary {
    fn summarize(&self) -> String;

    // default method — built entirely out of summarize()
    fn headline(&self) -> String {
        format!("[SUMMARY] {}", self.summarize())
    }
}

struct Article {
    title: String,
}

impl Summary for Article {
    fn summarize(&self) -> String {
        self.title.clone()
    }
    // headline() is not written here — we get the default for free
}

fn main() {
    let a = Article { title: String::from("Ferris learns to fly") };
    println!("{}", a.headline()); // [SUMMARY] Ferris learns to fly
}

Article only implemented summarize, but headline came along for free because the trait already knew how to build it out of summarize. This is how a lot of the standard library works: implement one small required method, and a whole family of related methods unlock automatically (Iterator is the biggest example of this pattern — more on that later in the course).

A type can also override a default if it has a better way to do it — just write the method with a body in the impl block, same as any required method.

Trait bounds: writing a function against the promise, not the type

The payoff of a trait is writing one function that works for anything implementing it. This is called a trait bound, and there are two equivalent-looking spellings:

trait Summary {
    fn summarize(&self) -> String;
}

struct Article {
    title: String,
}

impl Summary for Article {
    fn summarize(&self) -> String {
        self.title.clone()
    }
}

// spelling 1: impl Trait in argument position (sugar)
fn announce_a(item: &impl Summary) {
    println!("Breaking: {}", item.summarize());
}

// spelling 2: a generic type parameter with a trait bound
fn announce_b<T: Summary>(item: &T) {
    println!("Breaking: {}", item.summarize());
}

fn main() {
    let a = Article { title: String::from("Rust ships const generics") };
    announce_a(&a);
    announce_b(&a);
}

fn announce_a(item: &impl Summary) reads as “a reference to some type that implements Summary — I don’t care which one.” fn announce_b<T: Summary>(item: &T) says the same thing more explicitly: “there’s a type T, and I require T: Summary.” Both compile to the same thing. The generic spelling (<T: Summary>) is the one you need once a type has to show up more than once with the guarantee it’s the same type both times — impl Trait sugar can’t express that:

trait Summary {
    fn summarize(&self) -> String;
}

// impl Trait can't say "same T twice" — this needs the generic form
fn longer_summary<T: Summary>(a: &T, b: &T) -> String {
    // both a and b are guaranteed to be the same concrete type
    let sa = a.summarize();
    let sb = b.summarize();
    if sa.len() >= sb.len() { sa } else { sb }
}

struct Note(String);
impl Summary for Note {
    fn summarize(&self) -> String { self.0.clone() }
}

fn main() {
    let n1 = Note(String::from("short"));
    let n2 = Note(String::from("a much longer note here"));
    println!("{}", longer_summary(&n1, &n2));
}

where clauses: the same bounds, easier to read

Once a function needs several type parameters with several bounds each, cramming everything into the <...> list gets hard to read:

use std::fmt::Debug;

trait Summary {
    fn summarize(&self) -> String;
}

// hard to read: bounds crowd the signature
fn report_a<T: Summary + Clone, U: Debug + Clone>(item: &T, meta: &U) -> String {
    format!("{} ({:?})", item.summarize(), meta)
}

// same bounds, moved into a where clause — the signature stays scannable
fn report_b<T, U>(item: &T, meta: &U) -> String
where
    T: Summary + Clone,
    U: Debug + Clone,
{
    format!("{} ({:?})", item.summarize(), meta)
}

struct Note(String);
impl Summary for Note {
    fn summarize(&self) -> String { self.0.clone() }
}
impl Clone for Note {
    fn clone(&self) -> Self { Note(self.0.clone()) }
}

fn main() {
    let n = Note(String::from("meeting at 5"));
    println!("{}", report_a(&n, &"tag-1"));
    println!("{}", report_b(&n, &"tag-2"));
}

report_a and report_b are identical to the compiler — where is purely a readability tool. Reach for it once you have more than one bound, or bounds that combine multiple traits with +.

Not inheritance

If you come from Java or Python, resist “trait = base class.” A trait is not a parent that a type is a kind of. It’s a capability a type has. One type can implement many unrelated traits (Summary and Clone and Debug), and none of them is its “parent.” Think “can do,” not “is a.”

Common mistakes

• Forgetting the impl block. Writing trait Summary { ... } alone does nothing for Article. You must write impl Summary for Article. The error is the trait bound 'Article: Summary' is not satisfied or no method named 'summarize' found — both mean “you never told me how this type keeps the promise.”
• Calling a trait method with no bound on the generic type. fn f<T>(x: T) { x.summarize(); } fails with no method named 'summarize' found for type parameter 'T', because unbounded T could be literally anything — the compiler has zero information about it. The fix is always to add the bound: fn f<T: Summary>(x: T).
• Mixing up ; and a body in a trait definition. fn summarize(&self) -> String; (with ;) is a required method. fn summarize(&self) -> String { ... } (with a body) is a default method. Swapping these changes what implementers must write.
• Calling a trait method without the trait in scope. If a trait lives in another module or crate, you must use it before its methods are callable on a value, even if the type already implements it. The error is method not found, fixed with use path::to::Trait;.
• Thinking traits carry data. Traits describe behavior, not fields. If you want shared state, that’s what a struct is for — a trait can require a method that exposes the state, but it can’t hold the state itself.

More examples

Billing plans with different pricing

A subscription app needs to compute “how much does this cost per month” the same way for a free-tier plan and a per-seat plan — each with completely different math behind that one shared method.

trait Billable {
    fn monthly_cost(&self) -> f64;
}

struct Basic;
struct Pro { seats: u32 }

impl Billable for Basic {
    fn monthly_cost(&self) -> f64 { 9.99 }
}
impl Billable for Pro {
    fn monthly_cost(&self) -> f64 { 19.99 * self.seats as f64 }
}

fn main() {
    let basic = Basic;
    let pro = Pro { seats: 3 };
    println!("basic: ${:.2}", basic.monthly_cost());
    println!("pro: ${:.2}", pro.monthly_cost());
}

A default you can override

Most log lines are just “info,” but errors need different formatting. A default method covers the common case for free; one type opts out and writes its own.

trait Logger {
    fn log(&self, msg: &str) -> String {
        format!("[INFO] {}", msg)
    }
}

struct Console;
struct ErrorLogger;

impl Logger for Console {} // uses the default as-is

impl Logger for ErrorLogger {
    fn log(&self, msg: &str) -> String {
        format!("[ERROR] {}", msg)
    }
}

fn main() {
    println!("{}", Console.log("server started"));
    println!("{}", ErrorLogger.log("disk full"));
}

Requiring two abilities at once

Sometimes a function needs a type it can both print for debugging and duplicate — that’s two separate promises stacked into one bound.

use std::fmt::Debug;

fn snapshot<T: Debug + Clone>(item: T) -> (T, T) {
    println!("snapshotting: {:?}", item);
    (item.clone(), item)
}

fn main() {
    let (a, b) = snapshot(vec![1, 2, 3]);
    println!("{:?} {:?}", a, b);
}

A method that leans on another method

full_report doesn’t know how to compute a name or a salary itself — it just calls the other required methods on self and stitches the results together.

trait Employee {
    fn name(&self) -> String;
    fn salary(&self) -> f64;

    fn full_report(&self) -> String {
        format!("{} earns ${:.2}/mo", self.name(), self.salary())
    }
}

struct Contractor { name: String, rate: f64 }

impl Employee for Contractor {
    fn name(&self) -> String { self.name.clone() }
    fn salary(&self) -> f64 { self.rate * 160.0 }
}

fn main() {
    let c = Contractor { name: String::from("Dana"), rate: 45.0 };
    println!("{}", c.full_report());
}

One function, many unrelated “can-do” types

A shape and an invoice have nothing in common as types — but both can satisfy the same trait bound as long as they each keep the promise in their own way.

trait Describe {
    fn describe(&self) -> String;
}

struct Circle { r: f64 }
struct Invoice { id: u32 }

impl Describe for Circle {
    fn describe(&self) -> String { format!("circle r={}", self.r) }
}
impl Describe for Invoice {
    fn describe(&self) -> String { format!("invoice #{}", self.id) }
}

fn log_it(item: &impl Describe) {
    println!("LOG: {}", item.describe());
}

fn main() {
    log_it(&Circle { r: 2.0 });
    log_it(&Invoice { id: 4021 });
}

Your turn

This program wants announce to work for any type with a summarize method, but it doesn’t compile.

trait Summary {
    fn summarize(&self) -> String;
}

struct Article {
    title: String,
}

impl Summary for Article {
    fn summarize(&self) -> String {
        self.title.clone()
    }
}

fn announce<T>(item: &T) {
    println!("Breaking: {}", item.summarize());
}

fn main() {
    let a = Article { title: String::from("Rust turns 10") };
    announce(&a);
}

trait Summary {
    fn summarize(&self) -> String;
}

struct Article {
    title: String,
}

impl Summary for Article {
    fn summarize(&self) -> String {
        self.title.clone()
    }
}

fn announce<T: Summary>(item: &T) {
    println!("Breaking: {}", item.summarize());
}

fn main() {
    let a = Article { title: String::from("Rust turns 10") };
    announce(&a);
}

Quick check

Remember this

• A trait is a list of behavior (method signatures) a type promises to provide.
• impl TraitName for TypeName { ... } is where a type actually keeps the promise.
• fn f<T: Trait>(x: T) and fn f(x: &impl Trait) both mean “accept anything implementing Trait”; use the <T: Trait> form when the same type has to appear more than once.
• Default method bodies give implementers free behavior built on top of the required methods.
• where clauses hold the exact same bounds as <T: ...> — use them once a signature has more than one bound to keep it readable.
• Traits are “can do,” not “is a” — capabilities, not inheritance.

Go deeper

• Rust Book - Traits — Trait definitions and bounds.

Next:

• Trait objects and dyn
• Generics

Trait objects and dyn

Intermediate · Abstractions

What & why

Once you can write fn f<T: Trait>(x: T), a new problem shows up: what if you need a single collection that holds many different concrete types, as long as they all implement the same trait — a Vec of shapes where some are circles and some are squares? Generics can’t do that; each generic function is compiled separately per type, so there’s no single T that means “circle or square.” dyn Trait is Rust’s answer: a way to talk about “some type implementing Trait” at runtime, paid for with a small, explicit cost.

The idea, slowly

Static dispatch: generics become copies, not runtime checks

When you write a generic function and call it with a concrete type, the compiler doesn’t emit one flexible function — it stamps out a separate copy for every type you call it with. This is called monomorphization:

trait Shape {
    fn area(&self) -> f64;
}

struct Circle {
    r: f64,
}
struct Square {
    side: f64,
}

impl Shape for Circle {
    fn area(&self) -> f64 {
        std::f64::consts::PI * self.r * self.r
    }
}
impl Shape for Square {
    fn area(&self) -> f64 {
        self.side * self.side
    }
}

fn print_area<T: Shape>(s: &T) {
    println!("{:.2}", s.area());
}

fn main() {
    let c = Circle { r: 2.0 };
    let sq = Square { side: 3.0 };
    print_area(&c);  // compiler generates print_area::<Circle>
    print_area(&sq); // compiler generates a SEPARATE print_area::<Square>
}

Behind the scenes, this compiles as if you’d written print_area_circle and print_area_square by hand — two separate functions, each knowing its exact type at compile time. There’s no lookup at runtime; the call to s.area() jumps straight to Circle::area or Square::area because the compiler already knows which one. This is static dispatch: fast, and free of any runtime cost — but it means T is always one fixed type per call site. You cannot put a Circle and a Square in the same Vec<T>, because Vec<T> requires every element to be the same T.

The problem: mixed types, one interface

trait Shape {
    fn area(&self) -> f64;
}

struct Circle { r: f64 }
struct Square { side: f64 }
impl Shape for Circle {
    fn area(&self) -> f64 { std::f64::consts::PI * self.r * self.r }
}
impl Shape for Square {
    fn area(&self) -> f64 { self.side * self.side }
}

fn main() {
    // This does NOT compile: Circle and Square are different types,
    // and Vec<T> needs one T for every element.
    // let shapes = vec![Circle { r: 2.0 }, Square { side: 3.0 }];

    // dyn Trait is the escape hatch: "I don't know or care which
    // concrete Shape this is, only that it has .area()."
    let shapes: Vec<Box<dyn Shape>> = vec![
        Box::new(Circle { r: 2.0 }),
        Box::new(Square { side: 3.0 }),
    ];

    for s in &shapes {
        println!("{:.2}", s.area());
    }
}

Vec<Box<dyn Shape>> reads as “a growable list of boxed something-that-implements-Shape, and every element can be a different concrete type.” That’s exactly the flexibility monomorphized generics can’t offer.

Why dyn Trait needs a pointer

dyn Shape on its own is not a normal, usable type — it’s unsized (Rust calls this “dynamically sized”). A Circle is some fixed number of bytes; a Square is a different fixed number of bytes. dyn Shape means “whichever one of these it turns out to be,” and the compiler can’t reserve stack space for a value whose size it doesn’t know at compile time. That’s why dyn Shape by itself doesn’t compile as a variable or a Vec element — it has to sit behind a pointer (Box<dyn Shape>, &dyn Shape, or Rc<dyn Shape>), because a pointer is always the same fixed size (one machine word) no matter what it points to.

The pointer isn’t just an address, either — it’s a fat pointer: the address of the actual data, plus the address of a vtable (a small table of function pointers — one per trait method — generated once per concrete type). Calling s.area() through a dyn Shape looks up area in the vtable and jumps through it. That lookup is the “small runtime cost” of dynamic dispatch — one extra indirection compared to the direct call generics get for free.

What the compiler is thinking: with Box<dyn Shape>, it doesn’t need to know which Shape at compile time — it only needs to know the Box is one pointer wide and that the vtable it points to has an area slot. That’s enough to generate code that works for every current and future Shape implementer, without a single monomorphized copy per type.

Object safety: not every trait can become dyn

A trait can only become a trait object (dyn Trait) if the compiler can build that vtable — every method needs a fixed, known-in-advance shape. This property is traditionally called object safety (the compiler itself calls it dyn compatibility, the more current name for the same idea). Two common things break it:

#![allow(unused)]
fn main() {
trait Container {
    // generic method — breaks object safety.
    // A vtable would need one slot per possible T, which is unbounded.
    fn wrap<T>(&self, value: T) -> Vec<T> {
        vec![value]
    }
}
}

A method that takes a generic type parameter (fn wrap<T>(...)) can’t go in a vtable, because the vtable would need a different function pointer for every possible T — there’s no fixed list. Same problem with a method that returns Self by value: the caller side wouldn’t know how much space to reserve, since Self could be any concrete implementer.

If you try to write Box<dyn Container> for a trait like the one above, the compiler refuses with something like the trait 'Container' is not dyn compatible ... because method 'wrap' has generic type parameters. The fix is usually one of: keep the generic method but mark it where Self: Sized (which excludes it from the trait-object interface while keeping it for static-dispatch callers), split the trait into a dyn-compatible part and a generic-only part, or just accept that trait and use generics/impl Trait instead of dyn.

A third option: impl Trait in return position

Sometimes you don’t need a collection of mixed types — you just want to return “some type that implements Iterator” without writing out its long, awkward real name. impl Trait in return position does that, and it’s resolved entirely at compile time (no vtable, no Box required):

fn make_adder(n: i32) -> impl Fn(i32) -> i32 {
    move |x| x + n
}

fn main() {
    let add5 = make_adder(5);
    println!("{}", add5(10)); // 15
}

-> impl Fn(i32) -> i32 means “this returns some concrete type that implements Fn(i32) -> i32 — I’m not going to name it (closures don’t even have nameable types), but the caller can use it as if it does.” Unlike dyn Trait, every call to make_adder must return the same concrete type — you can’t have one branch return one closure type and another branch return a different one. If you need that, you’re back to Box<dyn Fn(i32) -> i32>.

Common mistakes

• Writing dyn Trait as a bare value or return type. fn make() -> dyn Shape { ... } fails with doesn't have a size known at compile-time. It needs a pointer: Box<dyn Shape> (owned, heap-allocated) or &dyn Shape (borrowed).
• Trying to put a trait with a generic method behind dyn. The error the trait '...' is not dyn compatible means the trait isn’t object-safe — usually a generic method or a method returning Self.
• Reaching for dyn Trait by default. If you always know the concrete type at each call site and never need to mix types in one collection, plain generics (T: Trait) are faster and give better compiler error messages — save dyn for when you genuinely need runtime-chosen, mixed types.
• Forgetting impl Trait return position must be one concrete type per function. if cond { return ClosureA } else { return ClosureB } from an -> impl Fn(...) function fails to compile, because the two branches are different underlying closure types even though both implement Fn. Use Box<dyn Fn(...)> if the concrete type genuinely varies.
• Confusing Box<dyn Trait> with Box<T>. Box<T> still knows exactly which T it holds and dispatches statically — only writing dyn in the type turns on dynamic dispatch.

More examples

Total area across mixed shapes

A floor-plan tool needs one number — total square footage — from a list of rooms that are circles, rectangles, and triangles all mixed together. dyn Shape is what lets one loop handle all three.

trait Shape {
    fn area(&self) -> f64;
}
struct Circle { r: f64 }
struct Rectangle { w: f64, h: f64 }
struct Triangle { base: f64, height: f64 }
impl Shape for Circle { fn area(&self) -> f64 { std::f64::consts::PI * self.r * self.r } }
impl Shape for Rectangle { fn area(&self) -> f64 { self.w * self.h } }
impl Shape for Triangle { fn area(&self) -> f64 { 0.5 * self.base * self.height } }

fn main() {
    let shapes: Vec<Box<dyn Shape>> = vec![
        Box::new(Circle { r: 1.0 }),
        Box::new(Rectangle { w: 2.0, h: 3.0 }),
        Box::new(Triangle { base: 4.0, height: 2.0 }),
    ];
    let total: f64 = shapes.iter().map(|s| s.area()).sum();
    println!("total area: {:.2}", total);
}

&dyn Trait vs impl Trait as a parameter

Both spellings accept “anything that implements Named,” but they read differently and fit different callers — impl Trait is the everyday default, &dyn Trait is what you reach for when the caller already has a trait object on hand.

trait Named {
    fn name(&self) -> &str;
}
struct Robot { label: String }
impl Named for Robot { fn name(&self) -> &str { &self.label } }

// impl Trait: compiler picks one concrete type per call site
fn greet_impl(n: &impl Named) {
    println!("hello, {} (impl Trait)", n.name());
}
// &dyn Trait: same call works through a vtable, useful when the caller
// only has a trait object handy (e.g. from a Vec<Box<dyn Named>>)
fn greet_dyn(n: &dyn Named) {
    println!("hello, {} (dyn Trait)", n.name());
}

fn main() {
    let r = Robot { label: String::from("R2") };
    greet_impl(&r);
    greet_dyn(&r);
}

A plugin-style callback list

A build tool wants to run an arbitrary list of registered steps in order, without knowing ahead of time how many there are or what each one does — Vec<Box<dyn Fn()>> is a list of “callable things,” not a list of one specific closure type.

fn main() {
    let handlers: Vec<Box<dyn Fn()>> = vec![
        Box::new(|| println!("handler 1: sending email")),
        Box::new(|| println!("handler 2: logging event")),
        Box::new(|| println!("handler 3: updating cache")),
    ];

    for handle in &handlers {
        handle();
    }
}

Storing a trait object in a struct field

An app that might notify users by email today and by SMS tomorrow doesn’t want its App struct locked to one concrete notifier type — it just stores “something that can notify.”

trait Notifier {
    fn notify(&self, msg: &str);
}
struct EmailNotifier;
impl Notifier for EmailNotifier {
    fn notify(&self, msg: &str) { println!("EMAIL: {}", msg); }
}

struct App {
    notifier: Box<dyn Notifier>,
}

fn main() {
    let app = App { notifier: Box::new(EmailNotifier) };
    app.notifier.notify("build finished");
}

Trait objects without Box: borrowed, not owned

When the concrete values already live on the stack and you just need a temporary mixed-type list, a borrowed &dyn Trait skips the heap allocation Box would need.

trait Animal {
    fn speak(&self) -> String;
}
struct Dog;
struct Cat;
impl Animal for Dog { fn speak(&self) -> String { String::from("Woof") } }
impl Animal for Cat { fn speak(&self) -> String { String::from("Meow") } }

fn main() {
    let dog = Dog;
    let cat = Cat;
    // no heap allocation needed — just borrow each one as a trait object
    let animals: Vec<&dyn Animal> = vec![&dog, &cat];

    for a in &animals {
        println!("{}", a.speak());
    }
}

Your turn

This program wants a Vec that holds both Circle and Square shapes behind one interface, but it doesn’t compile.

trait Shape {
    fn area(&self) -> f64;
}

struct Circle {
    r: f64,
}
struct Square {
    side: f64,
}

impl Shape for Circle {
    fn area(&self) -> f64 {
        std::f64::consts::PI * self.r * self.r
    }
}
impl Shape for Square {
    fn area(&self) -> f64 {
        self.side * self.side
    }
}

fn main() {
    let shapes: Vec<dyn Shape> = vec![Circle { r: 2.0 }, Square { side: 3.0 }];

    for s in &shapes {
        println!("{:.2}", s.area());
    }
}

trait Shape {
    fn area(&self) -> f64;
}

struct Circle {
    r: f64,
}
struct Square {
    side: f64,
}

impl Shape for Circle {
    fn area(&self) -> f64 {
        std::f64::consts::PI * self.r * self.r
    }
}
impl Shape for Square {
    fn area(&self) -> f64 {
        self.side * self.side
    }
}

fn main() {
    let shapes: Vec<Box<dyn Shape>> = vec![
        Box::new(Circle { r: 2.0 }),
        Box::new(Square { side: 3.0 }),
    ];

    for s in &shapes {
        println!("{:.2}", s.area());
    }
}

Quick check

Remember this

• Generics (T: Trait) use static dispatch: the compiler monomorphizes a separate copy per concrete type, so calls are direct and free — but every call site has exactly one T.
• dyn Trait uses dynamic dispatch: one shared function per method, looked up through a vtable at runtime — a small cost that buys the ability to mix concrete types.
• dyn Trait is unsized and must live behind a pointer: Box<dyn Trait> (owned), &dyn Trait (borrowed), or Rc<dyn Trait> (shared).
• A trait is object-safe only if the compiler can build a fixed vtable for it — generic methods and methods returning Self break that.
• impl Trait in return position is a third option: “some fixed concrete type, resolved at compile time” — no vtable, no pointer required, but every return path must produce the same underlying type.

Go deeper

• Rust Book - Trait Objects — When and how to use dyn Trait.

Next:

• Generics
• Smart pointers

Generics

Intermediate · Abstractions

What & why

Generics let you write a function or type once and use it with many different types, without copy-pasting a version for each. The magic word is a stand-in name (usually T) that means “some type — I’ll tell you which one when I use it.” It’s how Vec<T> can hold numbers or strings or your own structs from a single definition.

The idea, slowly

Imagine writing a “return the first item” function. Without generics you’d write one for Vec<i32>, another for Vec<String>, another for Vec<bool>… all identical except the type. That’s silly. Generics let you write it once with a placeholder.

A placeholder for a type

T is just a name — a variable, but for types instead of values:

fn first<T>(items: &[T]) -> &T {
    &items[0]
}

fn main() {
    let nums = [10, 20, 30];
    let words = ["red", "green", "blue"];

    println!("{}", first(&nums));  // works with i32
    println!("{}", first(&words)); // works with &str
}

Read fn first<T>(items: &[T]) -> &T:

• <T> right after the name means “I’m introducing a type placeholder called T.” You declare it here, like declaring a variable, before you use it.
• items: &[T] means “a slice of some type T.” (A slice &[T] is a borrowed view of a list — you saw slices earlier.)
• -> &T means “I return a reference to that same type T.”

What the compiler is thinking: when you call first(&nums), the compiler notices nums is [i32; 3], so it decides “T is i32 this time” and stamps out a version of first specialized to i32. When you call first(&words), it stamps out another for &str. You wrote one function; the compiler quietly generated the concrete ones. This is why generics are called zero-cost: at runtime there’s no guessing, just the specific machine code, as fast as if you’d hand-written each version.

Generics need bounds to do anything

Here’s the catch that trips everyone up. Inside a generic function, T could be anything, so the compiler only lets you do things that work for every possible type. You can’t add two Ts, or print a T, or compare them — unless you promise that T can do those things. You make that promise with a trait bound.

fn largest<T: PartialOrd + Copy>(items: &[T]) -> T {
    let mut biggest = items[0];
    for &item in items {
        if item > biggest {
            biggest = item;
        }
    }
    biggest
}

fn main() {
    let nums = [3, 7, 2, 9, 4];
    let chars = ['a', 'z', 'm'];
    println!("{}", largest(&nums));  // 9
    println!("{}", largest(&chars)); // z
}

<T: PartialOrd + Copy> reads as “T is some type that supports PartialOrd (can be compared with >) and Copy (can be duplicated cheaply).” Those are the two abilities the function actually uses: item > biggest needs comparison, and let mut biggest = items[0] needs a copy. The + means “and also.”

Try it: delete PartialOrd from the bound and run. The compiler says binary operation > cannot be applied to type T — because you removed the promise that T can be compared. The bound isn’t red tape; it’s you telling the compiler exactly what T is allowed to do.

Generic structs

Types can be generic too. That’s exactly how the standard library defines things like Option<T> and Vec<T>:

struct Pair<T> {
    first: T,
    second: T,
}

fn main() {
    let ints = Pair { first: 1, second: 2 };
    let words = Pair { first: "hi", second: "bye" };

    println!("{} {}", ints.first, ints.second);
    println!("{} {}", words.first, words.second);
}

One Pair definition, usable with any type. Pair<i32> and Pair<&str> are both real types the compiler builds from your single template.

Common mistakes

• Using an operation without the matching bound. Trying a > b or a + b or println!("{a}") on a bare T fails, because not every type supports it. The error names the missing trait, e.g. T doesn't implement std::fmt::Display. The fix is to add that trait to the bound: <T: Display>.
• Forgetting to declare <T> before using it. fn first(items: &[T]) (no <T>) makes the compiler think T is a real type it should already know, giving cannot find type T in this scope. Declare it: fn first<T>(...).
• Reaching for generics when one concrete type is fine. Generics earn their keep when several real types will flow through. If only i32 ever passes, a generic just adds noise. Add the placeholder when real variety shows up, not before.
• Confusing generics with trait objects (dyn). <T: Greet> picks one concrete type per call and is resolved at compile time. &dyn Greet mixes different types at runtime. For most beginner code, generics are what you want.

More examples

Finding the smallest, not the largest

The same shape of function works whether you want the max or the min — only the comparison direction changes, and the bound needed is identical.

fn smallest<T: PartialOrd + Copy>(items: &[T]) -> T {
    let mut min = items[0];
    for &item in items {
        if item < min {
            min = item;
        }
    }
    min
}

fn main() {
    let prices = [19.99, 4.50, 12.25];
    let scores = [88, 92, 71, 95];
    println!("cheapest: {}", smallest(&prices));
    println!("lowest score: {}", smallest(&scores));
}

A generic struct holding one value

Not every generic type needs two fields like Pair<T> — sometimes you just want a single value wrapped with some extra behavior, usable with whatever type shows up.

struct Wrapper<T> {
    value: T,
}

impl<T> Wrapper<T> {
    fn get(&self) -> &T {
        &self.value
    }
}

fn main() {
    let w1 = Wrapper { value: 42 };
    let w2 = Wrapper { value: String::from("hello") };
    println!("{}", w1.get());
    println!("{}", w2.get());
}

Two independent type parameters

A label and a value rarely share a type — combine accepts any two types at all, as long as both can be displayed.

use std::fmt::Display;

fn combine<T: Display, U: Display>(label: T, value: U) -> String {
    format!("{}: {}", label, value)
}

fn main() {
    println!("{}", combine("age", 30));
    println!("{}", combine('x', 3.14));
}

Constraining a generic just enough to print it

Sometimes the only thing a function does with T is print it for debugging — so the only bound it needs is Debug, nothing more.

use std::fmt::Debug;

fn dump<T: Debug>(label: &str, item: T) {
    println!("{} = {:?}", label, item);
}

fn main() {
    dump("nums", vec![1, 2, 3]);
    dump("pair", (true, "yes"));
}

Clamping a value into a range

A generic isn’t just for comparing two values — clamp_value works on any type that can be ordered, whether that’s a game score, a volume level, or a price.

fn clamp_value<T: PartialOrd>(value: T, min: T, max: T) -> T {
    if value < min {
        min
    } else if value > max {
        max
    } else {
        value
    }
}

fn main() {
    println!("{}", clamp_value(15, 0, 10));   // 10
    println!("{}", clamp_value(-5, 0, 10));   // 0
    println!("{}", clamp_value(4.5, 0.0, 10.0)); // 4.5
}

Your turn

This function is supposed to return the bigger of two values, for any comparable type. It doesn’t compile. Fix the bound so it prints 9 and z.

fn max_of<T>(a: T, b: T) -> T {
    if a > b { a } else { b }
}

fn main() {
    println!("{}", max_of(4, 9));
    println!("{}", max_of('a', 'z'));
}

fn max_of<T: PartialOrd + Copy>(a: T, b: T) -> T {
    if a > b { a } else { b }
}

fn main() {
    println!("{}", max_of(4, 9));
    println!("{}", max_of('a', 'z'));
}

Quick check

Remember this

• A generic type parameter like T is a placeholder for a type, chosen when you call the code.
• Declare it in angle brackets first: fn name<T>(...) or struct Name<T>.
• Inside a generic, you can only use abilities you promise via trait bounds: <T: PartialOrd + Copy>.
• The + in a bound means “and also this trait.”
• Generics are zero-cost: the compiler generates a specialized version per concrete type, so there’s no runtime penalty.

Go deeper

• Rust Book - Generics — The basics of generic syntax.

Next:

• Collections
• Iterators
• Smart pointers

Vectors

Beginner · Abstractions

What & why

Arrays in Rust have a size fixed at compile time — [i32; 3] is always exactly 3 integers, forever. Almost nothing in real programs works that way: shopping carts grow, search results come back with an unknown count, logs accumulate one line at a time. Vec<T> is Rust’s growable list — a row of same-typed boxes you can keep adding to (or removing from) while the program runs. It’s the collection you reach for by default.

The idea, slowly

Building one: Vec::new() vs vec![...]

fn main() {
    let mut a: Vec<i32> = Vec::new(); // empty, type must be known somehow
    a.push(1);
    a.push(2);

    let b = vec![10, 20, 30]; // vec! macro — pre-filled, type inferred

    println!("{:?}", a);
    println!("{:?}", b);
}

Vec::new() starts empty and figures out its element type either from an annotation (Vec<i32>) or from the first thing you push into it. vec![...] is a macro (note the !) that builds a Vec already holding the values you list — reach for it whenever you know the starting contents up front. {:?} is the “debug” format specifier; it can print a whole collection at once, which plain {} cannot.

push and pop

fn main() {
    let mut stack = Vec::new();
    stack.push(1);
    stack.push(2);
    stack.push(3);
    println!("{:?}", stack); // [1, 2, 3]

    // pop returns Option<T> — Some(value) if there was one, None if empty
    match stack.pop() {
        Some(top) => println!("popped {}", top), // popped 3
        None => println!("nothing to pop"),
    }
    println!("{:?}", stack); // [1, 2]
}

push adds to the end; pop removes and returns the last element. Because an empty Vec has nothing to pop, pop() hands back an Option<T> instead of just T — Some(value) if something was there, None if the vector was empty. This is the same “don’t crash, tell the caller” pattern you’ve already met with Option.

Indexing: v[i] panics, .get(i) doesn’t

fn main() {
    let nums = vec![10, 20, 30];

    println!("{}", nums[1]); // 20 — fine, index 1 exists

    match nums.get(10) {
        Some(n) => println!("found {}", n),
        None => println!("nothing at index 10"), // this runs
    }

    // nums[10]; // would PANIC: index out of bounds
}

v[i] reads by position, counting from 0, and panics (crashes the program on purpose) if i is out of range. .get(i) is the crash-free alternative — it returns Option<&T>, Some(&value) if the index exists and None if it doesn’t. Use v[i] when you already know the index is valid (e.g. you just checked v.len()); use .get(i) whenever the index comes from somewhere you don’t fully trust, like user input.

Iterating

fn main() {
    let nums = vec![1, 2, 3];

    for n in &nums {
        // n: &i32 — borrowing, nums still usable afterward
        print!("{} ", n);
    }
    println!();

    let mut mutable_nums = vec![1, 2, 3];
    for n in &mut mutable_nums {
        *n *= 10; // n: &mut i32 — modify in place
    }
    println!("{:?}", mutable_nums); // [10, 20, 30]

    for n in nums {
        // n: i32 — this CONSUMES nums; it can't be used after this loop
        print!("{} ", n);
    }
    println!();
}

for x in &v borrows and yields &T — the vector is untouched and usable afterward. for x in &mut v borrows mutably and yields &mut T — you can modify elements through it. for x in v (no &) takes ownership of the vector and hands you owned T values one at a time; after that loop, v is gone. Reach for &v by far the most often.

Sorting: sort and sort_by

fn main() {
    let mut nums = vec![5, 1, 4, 2, 3];
    nums.sort(); // ascending, uses the type's natural ordering
    println!("{:?}", nums); // [1, 2, 3, 4, 5]

    let mut words = vec!["pear", "fig", "kiwi"];
    words.sort_by(|a, b| a.len().cmp(&b.len())); // custom comparator: shortest first
    println!("{:?}", words); // ["fig", "kiwi", "pear"]

    let mut people = vec![("Bea", 41), ("Al", 30), ("Cy", 25)];
    people.sort_by_key(|p| p.1); // sort by age — often clearer than sort_by
    println!("{:?}", people); // [("Cy", 25), ("Al", 30), ("Bea", 41)]
}

sort() works for types with a natural order (numbers, strings, …). sort_by takes a closure that compares two elements and returns an Ordering — use it for custom rules. sort_by_key is the common special case “sort by this one field,” and reads more clearly than a full comparator when that’s all you need.

retain: keep only what passes a test

fn main() {
    let mut nums = vec![1, 2, 3, 4, 5, 6];
    nums.retain(|&n| n % 2 == 0); // keep only even numbers
    println!("{:?}", nums); // [2, 4, 6]
}

retain walks the vector and removes every element for which the closure returns false, in place — no separate “filter into a new vector” step needed when you just want to prune what’s already there.

dedup: only removes consecutive duplicates

fn main() {
    let mut nums = vec![1, 1, 2, 2, 2, 1, 3];
    nums.dedup();
    println!("{:?}", nums); // [1, 2, 1, 3] — NOT fully deduplicated!

    let mut nums2 = vec![1, 1, 2, 2, 2, 1, 3];
    nums2.sort();   // [1, 1, 1, 2, 2, 2, 3]
    nums2.dedup();  // now every duplicate is adjacent
    println!("{:?}", nums2); // [1, 2, 3]
}

dedup only collapses runs of adjacent equal elements — it does not scan the whole vector for duplicates anywhere. If you want every duplicate gone regardless of position, sort() first so equal elements become neighbors, then dedup().

Vec::with_capacity: avoid reallocating while you grow

fn main() {
    let mut a = Vec::new(); // capacity 0 — first few pushes reallocate
    for i in 0..5 {
        a.push(i);
    }

    let mut b: Vec<i32> = Vec::with_capacity(5); // room for 5 reserved up front
    for i in 0..5 {
        b.push(i); // none of these pushes need to reallocate
    }

    println!("{:?} {:?}", a, b);
}

A Vec is backed by one contiguous block of heap memory. When it runs out of room, push has to allocate a bigger block, copy every existing element over, and free the old block — an O(n) operation that happens occasionally as a vector grows (Rust’s standard library roughly doubles capacity each time, so this happens less and less often, but it still happens). If you know up front roughly how many elements you’ll end up with, Vec::with_capacity(n) reserves that space once, so the pushes that follow don’t trigger any reallocation at all. v.len() is how many elements are actually there; v.capacity() is how much room is reserved — they’re allowed to differ.

Common mistakes

• Forgetting mut. push, pop, sort, retain, and dedup all mutate the vector, so it must be let mut. The error is cannot borrow as mutable.
• Indexing out of bounds. v[99] on a short vector panics at runtime with index out of bounds. When the index isn’t already known to be valid, use v.get(99) and handle the Option instead.
• Treating pop() as if it returns the value directly. It returns Option<T>, because there might be nothing left to pop. let x: i32 = v.pop(); is a type error — you need v.pop().unwrap() (if you’re sure), or a match/if let.
• Expecting dedup() to remove all duplicates. It only merges adjacent equal runs. Duplicates scattered through an unsorted vector survive dedup() untouched — sort first.
• Skipping Vec::with_capacity in a hot loop. Repeatedly pushing into a Vec::new() when you already know the final size causes avoidable reallocations and copies. Not wrong, just slower than it needs to be.
• Trying to print a Vec with {}. Use {:?} (debug format) for whole vectors; plain {} only works for single values with a Display implementation.

More examples

Shopping cart total

Once prices are in a Vec, .iter().sum() turns “add up every item” into one line instead of a hand-rolled loop.

fn main() {
    let cart = vec![19.99, 5.50, 3.25, 12.00];
    let total: f64 = cart.iter().sum();
    println!("cart total: ${:.2}", total);
}

Deduplicating scraped URLs

A scraper that follows links will see the same page more than once. Sorting then dedup-ing turns a messy list of visited pages into the distinct set.

fn main() {
    let mut urls = vec![
        "site.com/a".to_string(),
        "site.com/b".to_string(),
        "site.com/a".to_string(),
        "site.com/c".to_string(),
        "site.com/b".to_string(),
    ];

    urls.sort();
    urls.dedup();

    println!("{} unique pages found", urls.len());
    println!("{:?}", urls);
}

An undo history as a stack

A text editor’s undo button always undoes the most recent action — exactly what push/pop on a Vec give you for free.

fn main() {
    let mut history: Vec<String> = Vec::new();
    history.push("typed 'hello'".to_string());
    history.push("bolded text".to_string());
    history.push("inserted image".to_string());

    if let Some(last_action) = history.pop() {
        println!("undoing: {}", last_action);
    }
    println!("remaining history: {:?}", history);
}

Chunking a list into batches

An email service that only accepts 2 recipients per request needs the full list broken into fixed-size groups first — .chunks(n) does exactly that without any manual index math.

fn main() {
    let emails = vec!["a@x.com", "b@x.com", "c@x.com", "d@x.com", "e@x.com"];

    for (i, batch) in emails.chunks(2).enumerate() {
        println!("sending batch {}: {:?}", i + 1, batch);
    }
}

Removing an item by value

Banning a user should remove every occurrence of their name from a list, not just one — retain keeps everything that doesn’t match.

fn main() {
    let mut usernames = vec!["alice", "spam_bot", "bob", "spam_bot", "carol"];
    usernames.retain(|&name| name != "spam_bot");
    println!("{:?}", usernames);
}

Your turn

This program should pop the top of a stack and print it, but it doesn’t compile.

fn main() {
    let mut stack = vec![1, 2, 3];
    let top: i32 = stack.pop();
    println!("top: {}", top);
}

fn main() {
    let mut stack = vec![1, 2, 3];

    match stack.pop() {
        Some(top) => println!("top: {}", top),
        None => println!("stack was empty"),
    }
}

Quick check

Remember this

• Vec::new() starts empty; vec![...] builds one pre-filled. Both need let mut to be modified.
• v[i] panics on an out-of-range index; v.get(i) returns Option<&T> instead — no crash.
• pop() returns Option<T>, not T, because the vector might be empty.
• for x in &v borrows (vector stays usable); for x in v consumes it.
• sort/sort_by/sort_by_key reorder in place; retain keeps only elements passing a test; dedup removes only adjacent duplicates, so sort first if you want them all gone.
• Vec::with_capacity(n) reserves space up front and avoids the reallocate-and-copy cost of growing one push at a time.

Go deeper

• std::vec::Vec docs — Full Vec API.

Next:

• HashMaps and HashSets
• Iterator basics

HashMaps and HashSets

Intermediate · Abstractions

What & why

A Vec finds things by position — index 0, 1, 2. A lot of real data doesn’t have a natural position; it has a natural name. “How many times did "the" appear?” “What’s the user with id 42?” HashMap<K, V> is Rust’s lookup table: you choose a key, and it maps that key to a value, like a real dictionary maps a word to its definition. HashSet<T> is the same idea with the values dropped — it only tracks which keys exist, for fast membership checks and de-duplication.

The idea, slowly

HashMap basics: insert, get, overwrite

use std::collections::HashMap;

fn main() {
    let mut ages: HashMap<&str, i32> = HashMap::new();
    ages.insert("Alice", 30);
    ages.insert("Bob", 25);

    // insert on an existing key OVERWRITES the old value
    ages.insert("Bob", 26);

    match ages.get("Alice") {
        Some(age) => println!("Alice is {}", age),
        None => println!("no Alice on file"),
    }

    for (name, age) in &ages {
        println!("{} is {}", name, age);
    }
}

• use std::collections::HashMap; — unlike Vec, HashMap isn’t automatically in scope. Forget this line and you get cannot find type 'HashMap' in this scope.
• .insert(key, value) adds a pair, or replaces the value if the key is already present — a map holds each key exactly once.
• .get(key) returns Option<&V> — Some(&value) if the key exists, None if it doesn’t — because a lookup by key can always miss.

The entry API: insert-or-update without a double lookup

The single most common HashMap pattern is “if this key exists, update its value; otherwise, insert a default.” Writing that with get/insert means checking the map twice. .entry(key).or_insert(default) does it in one step, and hands back a mutable reference you can modify directly:

use std::collections::HashMap;

fn main() {
    let text = "the quick fox jumps over the lazy fox";
    let mut counts: HashMap<&str, i32> = HashMap::new();

    for word in text.split_whitespace() {
        // "give me a mutable reference to word's count, inserting 0 first if missing"
        let count = counts.entry(word).or_insert(0);
        *count += 1;
    }

    let mut pairs: Vec<_> = counts.into_iter().collect();
    pairs.sort();
    println!("{:?}", pairs);
    // [("fox", 2), ("jumps", 1), ("lazy", 1), ("over", 1), ("quick", 1), ("the", 2)]
}

.entry(word) looks at the slot for word without removing it from the map. .or_insert(0) says “if that slot is empty, put 0 there first” — either way, it hands back &mut i32 pointing straight at the count for word. *count += 1 then dereferences and increments it. One line, one lookup, no separate “does it exist” branch. This is the idiomatic way to build counts, group items, or accumulate into a map — reach for entry before reaching for get + insert.

or_insert_with(|| ...) is the lazy version, for when the default is expensive to build (it only runs the closure if the key was actually missing); or_default() uses the value type’s Default implementation instead of a value you supply.

Custom key types need Eq and Hash

Any type can be a HashMap key if the compiler can hash it and compare it for equality — that’s what makes “look up this exact key” possible. Built-in types like &str and i32 already implement both. Your own struct needs to opt in explicitly:

use std::collections::HashMap;

#[derive(PartialEq, Eq, Hash, Debug)]
struct UserId(u32);

fn main() {
    let mut names: HashMap<UserId, &str> = HashMap::new();
    names.insert(UserId(1), "Alice");
    names.insert(UserId(2), "Bob");

    println!("{:?}", names.get(&UserId(1))); // Some("Alice")
}

#[derive(PartialEq, Eq, Hash)] asks the compiler to generate “compare field-by-field” and “hash field-by-field” for UserId automatically. Without it, HashMap<UserId, _> fails to compile with the trait bound 'UserId: Eq' is not satisfied (and the same for Hash) — the map genuinely cannot function as a lookup table without both. Eq is what lets it confirm “is this the same key,” and Hash is what lets it find the right bucket in the first place.

HashSet: membership and uniqueness, no values attached

A HashSet<T> is, conceptually, a HashMap<T, ()> — every key present, no values to go with them. Use it whenever the question is just “have I seen this?” or “give me only the distinct items”:

use std::collections::HashSet;

fn main() {
    let mut seen: HashSet<&str> = HashSet::new();

    for word in ["apple", "banana", "apple", "cherry", "banana"] {
        if seen.insert(word) {
            println!("new word: {}", word); // only prints on the first sighting
        }
    }

    println!("distinct count: {}", seen.len()); // 3
    println!("contains banana: {}", seen.contains("banana")); // true
}

.insert(value) returns true if the value was newly added and false if it was already present — that return value is what makes the “only print on first sighting” trick work in one line. .contains(value) is the O(1)-on-average membership check that’s the whole reason to reach for a HashSet instead of scanning a Vec with .contains() (which is O(n)).

Iteration order is not guaranteed

use std::collections::HashMap;

fn main() {
    let mut m = HashMap::new();
    m.insert("z", 1);
    m.insert("a", 2);
    m.insert("m", 3);

    for (k, _) in &m {
        print!("{} ", k); // order is unspecified — don't rely on it
    }
    println!();
}

HashMap and HashSet scatter keys across memory based on their hash, specifically so lookups are fast — there’s no relationship between insertion order and iteration order, and it can even change between runs of the same program (Rust randomizes the hash seed per-process as a security measure against denial-of-service attacks on the hashing). If you need sorted or insertion-ordered iteration, that’s not what HashMap is for — the next lesson covers BTreeMap, which keeps keys sorted by design.

Common mistakes

• Forgetting use std::collections::HashMap;. It’s in the standard library but not in the default prelude. Missing the use gives cannot find type 'HashMap' in this scope.
• Using get+insert where entry would do the job in one lookup. Not wrong, just more code and an extra map traversal — counts.entry(word).or_insert(0) replaces a multi-line if let/else almost every time.
• A custom key type missing Eq/Hash. The error is a compile-time the trait bound '...: Eq' is not satisfied (or Hash). Add #[derive(PartialEq, Eq, Hash)] to the struct — it’s a compile error, not a runtime surprise, precisely so you catch it before shipping.
• Assuming a HashMap preserves insertion order. It doesn’t, and the order can differ between runs of the same program. Don’t build logic that depends on it.
• Calling .insert() on a HashMap and expecting an error on a duplicate key. It silently overwrites the old value instead. If you need to know whether a key already existed, check the return value of .insert() — it’s Some(old_value) on overwrite, None if the key was new.

More examples

Selling from a warehouse’s stock

A sale should reduce the count for exactly one item; .get_mut(key) hands back a mutable reference straight into the map, so there’s no separate lookup-then-write step.

use std::collections::HashMap;

fn main() {
    let mut stock: HashMap<&str, u32> = HashMap::new();
    stock.insert("widget", 50);
    stock.insert("gadget", 12);

    if let Some(count) = stock.get_mut("widget") {
        *count -= 3; // sold 3 widgets
    }

    println!("widgets left: {}", stock["widget"]);
    println!("gadgets left: {}", stock["gadget"]);
}

Grouping orders by customer

A flat list of orders becomes a per-customer order history the moment you group it — entry(...).or_insert_with(Vec::new) builds each customer’s list lazily as their orders come in.

use std::collections::HashMap;

fn main() {
    let orders = [
        ("alice", "book"),
        ("bob", "pen"),
        ("alice", "lamp"),
        ("carol", "mug"),
        ("bob", "notebook"),
    ];

    let mut by_customer: HashMap<&str, Vec<&str>> = HashMap::new();
    for (customer, item) in orders {
        by_customer.entry(customer).or_insert_with(Vec::new).push(item);
    }

    let mut names: Vec<_> = by_customer.keys().collect();
    names.sort();
    for name in names {
        println!("{}: {:?}", name, by_customer[name]);
    }
}

Blocking duplicate coupon codes

A checkout should honor each coupon once; HashSet::insert returning false on a repeat is exactly the signal needed to reject a code that’s already been redeemed.

use std::collections::HashSet;

fn main() {
    let mut redeemed: HashSet<&str> = HashSet::new();
    let attempts = ["SAVE10", "WELCOME", "SAVE10", "FREESHIP"];

    for code in attempts {
        if redeemed.insert(code) {
            println!("{} accepted", code);
        } else {
            println!("{} rejected: already used", code);
        }
    }
}

Feature flags with a safe fallback

Not every flag will have been set yet, so .get(key).unwrap_or(&false) treats a missing flag as “off” instead of crashing the app.

use std::collections::HashMap;

fn main() {
    let mut flags: HashMap<&str, bool> = HashMap::new();
    flags.insert("dark_mode", true);

    let dark_mode = *flags.get("dark_mode").unwrap_or(&false);
    let beta_search = *flags.get("beta_search").unwrap_or(&false);

    println!("dark_mode: {}", dark_mode);
    println!("beta_search: {}", beta_search);
}

Your turn

This program wants to track which Points have been visited, but it doesn’t compile.

use std::collections::HashMap;

struct Point {
    x: i32,
    y: i32,
}

fn main() {
    let mut visited: HashMap<Point, bool> = HashMap::new();
    visited.insert(Point { x: 1, y: 2 }, true);

    println!("{}", visited.contains_key(&Point { x: 1, y: 2 }));
}

use std::collections::HashMap;

#[derive(PartialEq, Eq, Hash)]
struct Point {
    x: i32,
    y: i32,
}

fn main() {
    let mut visited: HashMap<Point, bool> = HashMap::new();
    visited.insert(Point { x: 1, y: 2 }, true);

    println!("{}", visited.contains_key(&Point { x: 1, y: 2 })); // true
}

Quick check

Remember this

• HashMap<K, V> looks up values by key; .insert(k, v) adds or overwrites, .get(k) returns Option<&V>.
• map.entry(key).or_insert(default) is the standard insert-or-update pattern — one lookup instead of two.
• Custom key types need #[derive(PartialEq, Eq, Hash)]; a missing derive is a compile error, not a runtime bug.
• HashSet<T> tracks membership and uniqueness only — .insert() returns false if the value was already present.
• Iteration order is unspecified and can change between runs — use BTreeMap/BTreeSet when order matters.

Go deeper

• std::collections::HashMap docs — Entry API and full method list.

Next:

• BTreeMap, VecDeque, and BinaryHeap
• Iterator basics

BTreeMap, VecDeque, and BinaryHeap

Intermediate · Abstractions

What & why

Vec and HashMap cover most everyday needs, but the standard library ships a few more collections built for specific access patterns. Picking the right one is about how you touch the data, not just what you store: do you need keys to come out sorted? Do you need to add and remove from both ends cheaply? Do you always want “the biggest one, right now”? BTreeMap/BTreeSet, VecDeque, and BinaryHeap each answer one of those questions well.

The idea, slowly

BTreeMap and BTreeSet: sorted keys, on purpose

A HashMap gives you fast lookups but scrambled iteration order. A BTreeMap<K, V> gives up a little lookup speed in exchange for keeping keys always in sorted order:

use std::collections::BTreeMap;

fn main() {
    let mut scores = BTreeMap::new();
    scores.insert("charlie", 3);
    scores.insert("alice", 9);
    scores.insert("bob", 5);

    // iterates in KEY order, every time, regardless of insertion order
    for (name, score) in &scores {
        println!("{}: {}", name, score);
    }
    // alice: 9
    // bob: 5
    // charlie: 3

    // range queries: "give me everything from bob onward"
    for (name, score) in scores.range("bob"..) {
        println!("from bob: {} = {}", name, score);
    }
}

HashMap is O(1) on average for get/insert; BTreeMap is O(log n) — technically slower, but the difference rarely matters in practice, and you get two things HashMap cannot offer: deterministic, sorted iteration, and .range(...) queries (“every key between X and Y”) which are impossible to express efficiently on a hash table. Reach for BTreeMap when you need the data in order — leaderboards, timestamps, anything you’d otherwise sort after the fact — and HashMap when you just need fast point lookups and don’t care about order.

BTreeSet<T> is to BTreeMap what HashSet is to HashMap: a sorted set of unique values, with the same .insert()/.contains() interface, iterated in ascending order.

Just like a HashMap key needs Eq + Hash, a BTreeMap key needs Ord (which itself requires Eq and PartialOrd) — the map needs to be able to say “is this key less than, equal to, or greater than that one” to keep itself sorted:

use std::collections::BTreeMap;

#[derive(PartialEq, Eq, PartialOrd, Ord, Debug)]
struct Version {
    major: u32,
    minor: u32,
}

fn main() {
    let mut releases = BTreeMap::new();
    releases.insert(Version { major: 1, minor: 2 }, "bugfix release");
    releases.insert(Version { major: 1, minor: 0 }, "initial release");
    releases.insert(Version { major: 2, minor: 0 }, "breaking release");

    for (v, note) in &releases {
        println!("{}.{}: {}", v.major, v.minor, note);
    }
    // 1.0: initial release
    // 1.2: bugfix release
    // 2.0: breaking release
}

#[derive(Ord)] compares struct fields in declaration order — major first, then minor as a tiebreaker — which is exactly the ordering you’d want for a version number.

VecDeque: cheap push/pop at both ends

Vec is fast at the back (push/pop are O(1)) but slow at the front — insert(0, x) or removing the first element has to shift every other element over, an O(n) operation. VecDeque (“double-ended queue”) is a ring buffer that makes both ends O(1):

use std::collections::VecDeque;

fn main() {
    let mut queue: VecDeque<i32> = VecDeque::new();

    queue.push_back(1);  // [1]
    queue.push_back(2);  // [1, 2]
    queue.push_front(0); // [0, 1, 2]  — O(1), unlike Vec::insert(0, _)

    println!("{:?}", queue);

    while let Some(front) = queue.pop_front() {
        print!("{} ", front); // 0 1 2 — first in, first out
    }
    println!();
}

Internally, a VecDeque is still backed by one contiguous allocation, but it’s treated as a ring: the logical “front” can start partway through the buffer and wrap around, so adding to the front never has to shift everything else. That makes it the natural fit for anything queue-shaped: a task queue processed in arrival order, a sliding window that drops old entries off the front while new ones arrive at the back, or a breadth-first-search frontier. VecDeque can also be indexed (queue[i]) and iterated like a Vec, so it isn’t purely a specialist tool — but plain Vec is still the better default when you only ever push and pop the back, since it has slightly less overhead.

BinaryHeap: always pop the biggest

A BinaryHeap<T> doesn’t keep its elements in any visible order — but calling .pop() always hands you back the largest remaining element, in O(log n):

use std::collections::BinaryHeap;

fn main() {
    let mut heap = BinaryHeap::new();
    heap.push(3);
    heap.push(7);
    heap.push(1);
    heap.push(5);

    while let Some(biggest) = heap.pop() {
        print!("{} ", biggest); // 7 5 3 1 — largest first, every time
    }
    println!();
}

This is a max-heap by default, and it’s the standard tool for a priority queue: “process the most urgent task next,” “always merge the two smallest lists first,” “keep the top-K largest values seen so far.” T needs Ord for the same reason BTreeMap keys do — the heap has to be able to compare elements to know which one is “biggest.”

A min-heap with std::cmp::Reverse

Sometimes you want the smallest element first instead — cheapest task, earliest deadline. BinaryHeap doesn’t have a separate “min mode”; instead, you flip the ordering by wrapping each value in std::cmp::Reverse, which swaps what “greater” means for that value:

use std::collections::BinaryHeap;
use std::cmp::Reverse;

fn main() {
    let mut min_heap = BinaryHeap::new();
    min_heap.push(Reverse(3));
    min_heap.push(Reverse(7));
    min_heap.push(Reverse(1));
    min_heap.push(Reverse(5));

    while let Some(Reverse(smallest)) = min_heap.pop() {
        print!("{} ", smallest); // 1 3 5 7 — smallest first
    }
    println!();
}

Reverse(x) is a thin wrapper whose Ord implementation is the opposite of x’s — so “the heap’s biggest Reverse value” is really “the smallest wrapped value.” Popping still calls the same .pop(); you just unwrap the Reverse to get the plain value back out. This is the idiomatic way to get min-heap behavior without a different collection type.

Common mistakes

• Defaulting to VecDeque everywhere. If you only ever push and pop the back, plain Vec has less overhead and is the better default — reach for VecDeque specifically when you need the front to be cheap too.
• Expecting BinaryHeap iteration to come out sorted. Only repeated .pop() guarantees largest-first order; iterating with for x in &heap (or .iter()) visits elements in unspecified internal order.
• Pushing plain values when you wanted a min-heap. BinaryHeap::push(x) always feeds the max-heap ordering. Forgetting to wrap in Reverse(x) gives you largest-first when you wanted smallest-first — a logic bug, not a compile error, so it’s easy to miss.
• Giving a BTreeMap or BinaryHeap a key/element type without Ord. The error is the trait bound '...: Ord' is not satisfied. For a custom struct, add #[derive(PartialEq, Eq, PartialOrd, Ord)] — all four are needed, since Ord itself depends on the other three.
• Choosing BTreeMap purely out of habit. If you never need sorted iteration or range queries, HashMap’s average O(1) lookups are faster than BTreeMap’s O(log n) — don’t pay for ordering you don’t use.

More examples

A sorted, deduplicated SKU catalog

BTreeSet turns a raw scan of product codes into a clean, alphabetized export in one pass — duplicates just fail to re-insert, and iteration always comes out sorted.

use std::collections::BTreeSet;

fn main() {
    let mut skus = BTreeSet::new();
    skus.insert("SKU-042");
    skus.insert("SKU-007");
    skus.insert("SKU-042"); // duplicate, ignored
    skus.insert("SKU-019");

    println!("{} unique SKUs", skus.len());
    for sku in &skus {
        println!("{}", sku);
    }
}

A rolling average over sensor readings

A VecDeque capped at a fixed size is a cheap sliding window — push a new reading onto the back, pop the oldest off the front, and the average is always over just the last few.

use std::collections::VecDeque;

fn main() {
    let mut window: VecDeque<f64> = VecDeque::new();
    let readings = [21.0, 22.5, 23.0, 19.5, 20.0];

    for reading in readings {
        window.push_back(reading);
        if window.len() > 3 {
            window.pop_front(); // keep only the last 3 readings
        }
        let avg: f64 = window.iter().sum::<f64>() / window.len() as f64;
        println!("latest: {:.1}, rolling avg: {:.2}", reading, avg);
    }
}

A support ticket priority queue

Pushing (priority, description) tuples into a BinaryHeap means .pop() always hands back the most urgent ticket first, without sorting the whole queue every time one arrives.

use std::collections::BinaryHeap;

fn main() {
    let mut tickets = BinaryHeap::new();
    tickets.push((1, "typo on homepage"));
    tickets.push((5, "payment system down"));
    tickets.push((3, "slow page load"));

    while let Some((priority, issue)) = tickets.pop() {
        println!("[P{}] {}", priority, issue);
    }
}

Building a chronological event timeline

BTreeMap combines with the entry API just like HashMap does — grouping events under their timestamp and letting the map’s sorted keys put the whole log in time order for free.

use std::collections::BTreeMap;

fn main() {
    let events = [
        (930, "server restarted"),
        (215, "deploy started"),
        (930, "cache cleared"),
        (600, "backup completed"),
    ];

    let mut timeline: BTreeMap<u32, Vec<&str>> = BTreeMap::new();
    for (minute, event) in events {
        timeline.entry(minute).or_insert_with(Vec::new).push(event);
    }

    for (minute, events_at) in &timeline {
        println!("{:04}: {:?}", minute, events_at);
    }
}

Your turn

This program wants a version-sorted release log using BTreeMap, but it doesn’t compile.

use std::collections::BTreeMap;

struct Version {
    major: u32,
    minor: u32,
}

fn main() {
    let mut releases: BTreeMap<Version, &str> = BTreeMap::new();
    releases.insert(Version { major: 1, minor: 0 }, "initial release");
    releases.insert(Version { major: 1, minor: 2 }, "bugfix release");

    for (v, note) in &releases {
        println!("{}.{}: {}", v.major, v.minor, note);
    }
}

use std::collections::BTreeMap;

#[derive(PartialEq, Eq, PartialOrd, Ord)]
struct Version {
    major: u32,
    minor: u32,
}

fn main() {
    let mut releases: BTreeMap<Version, &str> = BTreeMap::new();
    releases.insert(Version { major: 1, minor: 0 }, "initial release");
    releases.insert(Version { major: 1, minor: 2 }, "bugfix release");

    for (v, note) in &releases {
        println!("{}.{}: {}", v.major, v.minor, note);
    }
    // 1.0: initial release
    // 1.2: bugfix release
}

Quick check

Remember this

• BTreeMap/BTreeSet keep keys sorted at all times (O(log n) operations) and support range queries — pick them over HashMap/HashSet when order matters.
• Keys in a BTreeMap/BTreeSet need Ord (#[derive(PartialEq, Eq, PartialOrd, Ord)] on a custom struct).
• VecDeque gives O(1) push/pop at both the front and back, unlike Vec which is O(n) at the front — the natural fit for queues and sliding windows.
• BinaryHeap is a max-heap by default: .pop() always returns the largest remaining element.
• Wrap values in std::cmp::Reverse to get min-heap behavior out of the same BinaryHeap.

Go deeper

• std::collections module docs — A comparison table of every std collection.

Next:

• Strings and str

Strings and str

Intermediate · Abstractions

What & why

Rust has two main text types and beginners bump into both on day one: String (text your program owns and can grow) and &str (a borrowed view into some text). Once you see why there are two, the endless “expected &str, found String” errors stop being mysterious and start being obvious.

The idea, slowly

Owned vs borrowed, one more time

You already met this split in the Ownership lessons, just with different types. Text is the same story:

• String is a growable, heap-allocated buffer your variable owns. Think of it as a whiteboard you bought — it’s yours, you can write more on it, erase it, and when you’re done it gets thrown away.
• &str (say “string slice”) is a borrowed look at text that already exists somewhere. Think of it as pointing at words on someone else’s whiteboard — you can read them, but you don’t own the board and can’t grow it.

fn main() {
    let owned: String = String::from("hello"); // owns a growable buffer
    let borrowed: &str = &owned;                // borrows a view of it

    println!("owned = {}", owned);
    println!("borrowed = {}", borrowed);
}

&owned borrows the String and hands you a &str looking into it. Nothing is copied; borrowed just points at the same letters owned holds.

String literals are already &str

Every time you type text in quotes, that’s a &str — it points into your compiled program, which stays alive the whole time it runs:

fn main() {
    let greeting = "hi there"; // type is &str, no String involved
    println!("{}", greeting);
}

So "hi" is a &str, and String::from("hi") turns that borrowed text into an owned String you can grow.

Growing a String

Only String can grow, because only String owns its buffer:

fn main() {
    let mut name = String::from("Shamir");
    name.push_str("ul");     // add several chars
    name.push('!');          // add one char (note single quotes)
    println!("{}", name);    // Shamirul!
}

push_str takes a &str (a borrowed piece of text to append), and push takes a single char. Try this on a plain &str and it won’t compile — a borrowed view has nothing of its own to grow.

The function-argument rule of thumb

This is the practical payoff. When a function just needs to read text, take &str. It’s the more flexible choice because both a String and a &str can be passed to it:

fn shout(text: &str) -> String {
    text.to_uppercase()
}

fn main() {
    let owned = String::from("hello");
    println!("{}", shout(&owned));  // pass a String by reference -> &str
    println!("{}", shout("world")); // pass a literal &str directly
}

shout accepts &str, so it works for owned strings (via &owned) and literals. If you’d written fn shout(text: String), you’d force every caller to hand over an owned String and give it away. Taking &str is friendlier. Take &str to read; return String when you build new text.

Length is in bytes, not letters

This one surprises everyone. Rust text is UTF-8, where some characters take more than one byte. .len() counts bytes:

fn main() {
    let word = "café";
    println!("bytes: {}", word.len());          // 5, not 4 — é is 2 bytes
    println!("chars: {}", word.chars().count()); // 4 actual characters
}

Because of this, you also can’t index text by number — word[0] is a compile error in Rust, on purpose, because “byte 0” and “character 0” aren’t always the same thing. To walk characters, use .chars().

Common mistakes

• expected &str, found String (or vice versa). A function wanting &str won’t silently take a String. Pass &my_string to borrow it down to a &str. Going the other way, turn a &str into a String with .to_string() or String::from(...).
• Trying to grow a &str. push_str/push need an owned buffer, so they only exist on String. The fix is to start from a String, or convert with .to_string().
• Indexing text with [i]. s[0] doesn’t compile for strings because byte positions and character positions differ in UTF-8. Use .chars().nth(i) for a character, or slice by a known byte range.
• Assuming .len() is the character count. It’s the byte count. For visible characters use .chars().count().
• Taking String as a parameter when you only read it. This forces callers to give up ownership for no reason. Prefer &str for read-only text arguments.

More examples

Cleaning up user input

Form fields arrive messy — stray whitespace, inconsistent casing. Normalize them before you compare or store them.

fn main() {
    let raw_input = "   Alice@Example.com  \n";
    let clean = raw_input.trim().to_lowercase();
    println!("clean email: '{}'", clean);
}

Splitting a CSV-like line

Config files and simple data dumps are often just comma-separated fields. .split() plus .trim() handles the common case without pulling in a CSV crate.

fn main() {
    let line = "Ferris, 8, Crab";
    let fields: Vec<&str> = line.split(',').map(|f| f.trim()).collect();
    println!("{:?}", fields); // ["Ferris", "8", "Crab"]
}

Router-style path matching

A tiny web framework has to decide which handler owns a request path. starts_with/ends_with are the bread and butter of that decision.

fn main() {
    let path = "/api/users/42";

    if path.starts_with("/api/users/") {
        println!("route: get user");
    } else if path.ends_with(".json") {
        println!("route: serve json file");
    } else {
        println!("route: not found");
    }
}

Building a receipt line by line

Sometimes you don’t have all the text up front — you build it as you go, like assembling a shopping list into one printable line.

fn main() {
    let items = vec!["eggs", "milk", "bread"];
    let mut receipt = String::new();

    for item in &items {
        receipt.push_str(item);
        receipt.push_str(", ");
    }

    println!("{}", receipt); // eggs, milk, bread,
}

A helper that formats log lines

Utility functions like this get called with all kinds of text — owned Strings built at runtime, and &str literals. Taking &str parameters means one function serves both.

fn log_line(level: &str, message: &str) -> String {
    format!("[{}] {}", level.to_uppercase(), message)
}

fn main() {
    let msg = String::from("server started");
    println!("{}", log_line("info", &msg));
    println!("{}", log_line("warn", "disk almost full"));
}

Your turn

This function should return the text in uppercase, and be callable with both a String and a literal. It doesn’t compile. Fix the parameter type.

fn loud(text: String) -> String {
    text.to_uppercase()
}

fn main() {
    let name = String::from("rust");
    println!("{}", loud(&name)); // passing &name (a &str) — type mismatch
    println!("{}", loud("go"));  // passing a literal &str — type mismatch
}

fn loud(text: &str) -> String {
    text.to_uppercase()
}

fn main() {
    let name = String::from("rust");
    println!("{}", loud(&name));
    println!("{}", loud("go"));
}

Quick check

Remember this

• String owns growable text; &str borrows a view of existing text.
• String literals like "hi" are already &str.
• Only String can grow (push_str, push) — a &str has nothing of its own to grow.
• For read-only text arguments, take &str; it accepts both String (via &) and literals.
• .len() is bytes, not characters; you can’t index text by number — use .chars().

Go deeper

• Rust Book - Storing UTF-8 Encoded Text with Strings — How Rust treats text.

Next:

• Iterators
• File I/O

Iterator basics

Intermediate · Abstractions

What & why

Think of an iterator as a vending machine: you press the button (.next()) and it hands you one item, or tells you it’s out. Every for loop you’ve ever written already uses one under the hood. This lesson pulls back the curtain on the Iterator trait itself, and on the single biggest source of iterator-flavored borrow-checker errors: the difference between .iter(), .iter_mut(), and .into_iter(). Chaining transformations like .map() and .filter() — the fun part — is the next lesson; here we’re building the foundation that makes those make sense.

The idea, slowly

The Iterator trait: one method, .next()

Everything iterable implements this trait, which boils down to a single required method:

#![allow(unused)]
fn main() {
trait Iterator {
    type Item;
    fn next(&mut self) -> Option<Self::Item>;
}
}

Call .next() and you get Some(item) if there’s more, or None once it’s exhausted. That’s the whole contract. Every adaptor and every for loop you’ll ever write is built on repeated calls to this one method.

You can drive an iterator by hand:

fn main() {
    let nums = vec![10, 20, 30];
    let mut iter = nums.iter(); // must be `mut` — next() needs &mut self

    println!("{:?}", iter.next()); // Some(10)
    println!("{:?}", iter.next()); // Some(20)
    println!("{:?}", iter.next()); // Some(30)
    println!("{:?}", iter.next()); // None — exhausted
}

What the compiler is thinking: next(&mut self) takes a mutable reference to the iterator so it can update wherever it tracks “how far along am I.” That’s why iter had to be declared mut — without it, the compiler refuses with cannot borrow iter as mutable.

for loops are .next() calls in a trench coat

Nobody actually writes manual .next() loops by hand — that’s exactly what for is sugar for. This:

fn main() {
    let nums = vec![10, 20, 30];
    for n in &nums {
        println!("{n}");
    }
}

desugars to roughly this:

fn main() {
    let nums = vec![10, 20, 30];
    let mut iter = (&nums).into_iter();
    while let Some(n) = iter.next() {
        println!("{n}");
    }
}

A for loop is just a while let Some(...) = iter.next() loop with the bookkeeping hidden. That single fact unlocks the next section: the only thing that changes between for x in &v, for x in &mut v, and for x in v is which flavor of into_iter() gets called — and each one hands back something different.

.iter() vs .iter_mut() vs .into_iter()

This is just ownership again, wearing an iterator costume:

fn main() {
    let mut nums = vec![1, 2, 3];

    // .iter(): read-only borrow, nums survives
    for n in nums.iter() {
        print!("{n} ");
    }
    println!("- still have {} items", nums.len());

    // .iter_mut(): mutable borrow, change items in place
    for n in nums.iter_mut() {
        *n *= 10; // *n because n is &mut i32 — dereference to write through it
    }
    println!("{nums:?}"); // [10, 20, 30]

    // .into_iter(): takes ownership, nums is consumed
    for n in nums.into_iter() {
        print!("{n} ");
    }
    // nums.len() here would NOT compile — nums was moved
}

And the desugaring rule ties it all together: for x in &v calls .iter() under the hood, for x in &mut v calls .iter_mut(), and for x in v calls .into_iter(). That’s why for x in &v leaves v usable afterward, and for x in v doesn’t — you’re choosing the borrow mode the moment you write (or omit) the &.

Laziness: an iterator does nothing until something asks

Building an iterator — even one with a transformation attached — doesn’t run anything by itself. It’s a plan, not an action:

fn main() {
    let nums = vec![1, 2, 3];

    nums.iter().map(|n| n * 100); // just describes work — the compiler warns "unused `Map` that must be used"
    // (nothing was multiplied — nothing consumed the chain)

    let doubled: Vec<i32> = nums.iter().map(|n| n * 2).collect(); // NOW it runs
    println!("{doubled:?}"); // [2, 4, 6]
}

Nothing happens until something pulls values out — by calling .next() directly, by looping with for, or by handing the chain to a consumer like .collect(). That laziness is exactly what makes chaining .map(), .filter(), and friends cheap and composable, which is exactly what the next lesson, Iterator adaptors, covers in depth.

Common mistakes

• Using for x in v when you still need v afterward. That form calls .into_iter(), which consumes v. If you need the collection again, loop over &v instead.
• Forgetting mut on a manually-driven iterator. .next() takes &mut self; let iter = v.iter(); followed by iter.next() won’t compile without let mut iter = ....
• Assuming an iterator “ran” just because you built it. v.iter().map(...) alone does nothing — Rust warns unused iterator that must be used. You need a for loop or a consumer.
• Forgetting to dereference in .iter_mut(). The loop variable is &mut T, not T — writing n = 5 won’t compile, you need *n = 5 to write through the reference.
• Reaching for .into_iter() out of habit. If you only need to read the items, .iter() is almost always the right call — it doesn’t give up the collection.

More examples

Print a guest list without losing it

You often need to display a collection and keep using it afterward — printing a list shouldn’t be destructive.

fn main() {
    let guests = vec![String::from("Ferris"), String::from("Ada"), String::from("Grace")];

    for guest in &guests {
        println!("welcome, {guest}!");
    }

    println!("{} guests still in the list: {:?}", guests.len(), guests);
}

Shout every tag in place

Normalizing data in place — like uppercasing every tag before saving — is exactly what .iter_mut() is for: change items without rebuilding the whole collection.

fn main() {
    let mut tags = vec![String::from("rust"), String::from("wasm"), String::from("cli")];

    for tag in tags.iter_mut() {
        *tag = tag.to_uppercase();
    }

    println!("{:?}", tags); // ["RUST", "WASM", "CLI"]
}

Move pending orders into an archive

When you’re done with a collection and want to hand its contents to something else — like moving orders out of a “pending” list — .into_iter() transfers ownership instead of copying.

fn main() {
    let pending = vec![String::from("order-1"), String::from("order-2")];

    let archived: Vec<String> = pending.into_iter().collect();

    println!("{:?}", archived);
    // pending is gone now -- it was moved, not borrowed
}

Walk a HashMap of scores

Maps come up constantly for lookups — a for loop over &map gives you (key, value) pairs, one per entry.

use std::collections::HashMap;

fn main() {
    let mut scores = HashMap::new();
    scores.insert("Ferris", 92);
    scores.insert("Ada", 88);

    for (name, score) in &scores {
        println!("{name}: {score}");
    }
}

Process a job queue and stop on a signal

Driving an iterator by hand with .next() is useful when you need to react mid-loop — like bailing out the moment you see a stop signal.

fn main() {
    let jobs = vec!["resize", "compress", "STOP", "upload"];
    let mut iter = jobs.iter();

    while let Some(job) = iter.next() {
        if *job == "STOP" {
            println!("halting: stop signal received");
            break;
        }
        println!("running job: {job}");
    }
}

Your turn

This program should greet every name and then report how many names there were. It doesn’t compile.

fn main() {
    let names = vec![String::from("Ferris"), String::from("Rusty")];

    for name in names {
        println!("hello, {name}");
    }

    println!("we had {} names", names.len());
}

fn main() {
    let names = vec![String::from("Ferris"), String::from("Rusty")];

    for name in &names { // borrow: names survives the loop
        println!("hello, {name}");
    }

    println!("we had {} names", names.len()); // fine now
}

Quick check

Remember this

• The Iterator trait boils down to one method: fn next(&mut self) -> Option<Self::Item>.
• A for loop is sugar for calling .into_iter() once, then looping while let Some(x) = iter.next().
• .iter() yields &T (borrow, collection stays usable), .iter_mut() yields &mut T (mutate in place), .into_iter() yields T (owned, consumes the collection).
• for x in &v borrows (like .iter()); for x in &mut v mutably borrows (like .iter_mut()); for x in v consumes (like .into_iter()).
• An iterator does nothing on its own — it needs .next(), a for loop, or a consumer like .collect() to actually run.

Go deeper

• Rust Book - Processing a Series of Items with Iterators — Iterator fundamentals.

Next:

• Iterator adaptors
• Closures

Iterator adaptors

Intermediate · Abstractions

What & why

An adaptor is a step in an iterator pipeline that describes a transformation — “double each item,” “keep only the even ones,” “pair each item with its index.” Adaptors snap together like an assembly line, and (as the previous lesson covered) none of them actually run anything: they build up a lazy plan until a consumer — .collect(), .sum(), a for loop — pulls values through the whole chain. This is the idiomatic replacement for most hand-rolled index loops, and once you know the vocabulary, chains like .filter(...).map(...).collect() read like a sentence instead of a puzzle.

The idea, slowly

map: transform each item

.map() replaces every item with the result of a closure. It doesn’t touch anything until consumed:

fn main() {
    let nums = vec![1, 2, 3];
    let doubled: Vec<i32> = nums.iter().map(|n| n * 2).collect();
    println!("{doubled:?}"); // [2, 4, 6]
}

filter: keep only what passes a test

.filter() takes a closure returning bool and drops anything that returns false. The closure receives a reference to each item (&Item), so with .iter() on a Vec<i32> you’re comparing &i32, which usually means dereferencing:

fn main() {
    let nums = vec![1, 2, 3, 4, 5, 6];
    let evens: Vec<&i32> = nums.iter().filter(|n| **n % 2 == 0).collect();
    println!("{evens:?}"); // [2, 4, 6]
}

What the compiler is thinking: .iter() yields &i32. .filter()’s closure gets a reference to that item — &&i32 — so **n peels back both layers to reach the actual number. Forget one * and you’ll see cannot compare &i32 with integer; that error is your cue to dereference.

filter_map: filter and transform in one step

When “keep it, but also transform it” describes what you want, filter_map does both in one pass. Its closure returns Option<T> — Some(value) keeps and unwraps, None drops:

fn main() {
    let inputs = vec!["3", "seven", "12", "oops", "9"];

    let numbers: Vec<i32> = inputs
        .iter()
        .filter_map(|s| s.parse().ok()) // Ok -> Some(n), Err -> None
        .collect();

    println!("{numbers:?}"); // [3, 12, 9]
}

Without filter_map you’d need .map(|s| s.parse()) followed by .filter(...) followed by unwrapping — one adaptor instead of three.

enumerate: pair each item with its index

fn main() {
    let letters = vec!['a', 'b', 'c'];
    for (i, letter) in letters.iter().enumerate() {
        println!("{i}: {letter}");
    }
    // 0: a
    // 1: b
    // 2: c
}

zip: walk two iterators together

.zip() pairs items positionally from two iterators. It stops as soon as the shorter one runs out:

fn main() {
    let names = vec!["Ferris", "Rusty"];
    let scores = vec![100, 87, 999]; // extra item, ignored

    let paired: Vec<(&&str, &i32)> = names.iter().zip(scores.iter()).collect();
    println!("{paired:?}"); // [("Ferris", 100), ("Rusty", 87)]
}

take / skip: slice the stream by count

fn main() {
    let nums = vec![1, 2, 3, 4, 5, 6];

    let first_three: Vec<&i32> = nums.iter().take(3).collect();
    let after_three: Vec<&i32> = nums.iter().skip(3).collect();

    println!("{first_three:?}"); // [1, 2, 3]
    println!("{after_three:?}"); // [4, 5, 6]
}

fold: build up one accumulated value

.fold(initial, |accumulator, item| ...) walks the whole iterator, carrying an accumulator through each step. .sum() is really just a specialized fold:

fn main() {
    let nums = vec![1, 2, 3, 4];

    let total = nums.iter().fold(0, |acc, n| acc + n);
    let joined = nums.iter().fold(String::new(), |mut acc, n| {
        acc.push_str(&n.to_string());
        acc.push(' ');
        acc
    });

    println!("{total}");  // 10
    println!("{joined}"); // "1 2 3 4 "
}

Consumers: collect, sum, count

These are what actually run a chain. .collect() is the most flexible — and the most likely to confuse the compiler, because it can build almost any collection. Tell it what to build either with a type annotation on the binding, or with turbofish syntax:

fn main() {
    let nums = vec![1, 2, 3, 4, 5];

    // Option A: type annotation on the binding
    let doubled: Vec<i32> = nums.iter().map(|n| n * 2).collect();

    // Option B: turbofish on collect itself
    let tripled = nums.iter().map(|n| n * 3).collect::<Vec<i32>>();

    let total: i32 = nums.iter().sum();
    let how_many = nums.iter().filter(|&&n| n > 2).count();

    println!("{doubled:?} {tripled:?} sum={total} big={how_many}");
}

.sum() adds everything up (needs a type it can add into, usually inferred). .count() just tallies how many items came through, regardless of their value.

A realistic pipeline

Here’s a chain doing real work: parse a batch of raw scores, keep the valid passing ones, number them, and format a report — four adaptors plus a consumer:

fn main() {
    let raw_scores = vec!["88", "42", "oops", "95", "59", "73"];

    let report: Vec<String> = raw_scores
        .iter()
        .filter_map(|s| s.parse::<i32>().ok()) // drop anything that isn't a number
        .filter(|&score| score >= 60)          // keep only passing scores
        .enumerate()                            // pair with a rank
        .map(|(i, score)| format!("#{}: {score}", i + 1)) // format for display
        .collect();

    for line in &report {
        println!("{line}");
    }
    // #1: 88
    // #2: 95
    // #3: 73
}

When a plain for loop reads better

Adaptor chains are great until they aren’t. Once a chain grows past roughly four or five steps, or mixes in side effects like I/O or logging, a for loop with a comment is often more readable — you can name intermediate values, step through it in a debugger one line at a time, and add a print statement without restructuring the whole chain. Prefer adaptors for straightforward transform/filter/collect work; reach for a for loop when the logic branches, has side effects, or the chain is fighting you.

Common mistakes

• A chain with no consumer at the end. nums.iter().map(...) alone does nothing and the compiler warns unused Map that must be used. Add .collect(), .sum(), a for loop, or another consumer.
• collect() without a target type. The compiler doesn’t know what to build — type annotations needed. Fix it with a type annotation (let v: Vec<i32> = ...) or turbofish (.collect::<Vec<i32>>()).
• Forgetting filter/map closures receive references. Over .iter(), filter’s closure parameter is a reference to a reference (&&T) — you’ll often need *n or **n to compare or use the actual value.
• Assuming .zip() pads the shorter iterator. It doesn’t — it silently truncates to the length of the shorter side. If lengths can differ and that matters, check lengths first or use a different strategy.
• Chaining adaptors past the point of clarity. A 6-step chain that took you five minutes to write will take a teammate (or future you) five minutes to read. A for loop with a comment is not a downgrade.

More examples

Sum only the valid donations

Real input is messy — some entries won’t parse. filter_map lets you drop the bad ones and total the rest in a single pass, no intermediate Vec needed.

fn main() {
    let donations = vec!["25", "n/a", "100", "-", "40"];

    let total: i32 = donations.iter().filter_map(|d| d.parse::<i32>().ok()).sum();

    println!("total raised: ${total}"); // 165
}

Combine two shifts of readings with zip

zip isn’t just for display pairs — pairing up two same-length datasets and combining them element-wise (like adding two shifts’ sales) is a common use.

fn main() {
    let morning = vec![12, 8, 15];
    let evening = vec![5, 10, 7];

    let daily_totals: Vec<i32> = morning.iter().zip(evening.iter()).map(|(m, e)| m + e).collect();

    println!("{:?}", daily_totals); // [17, 18, 22]
}

Number the lines of a file

.enumerate() is exactly what a text editor or cat -n needs: pair each line with its position for display.

fn main() {
    let lines = vec!["fn main() {", "    println!(\"hi\");", "}"];

    for (num, line) in lines.iter().enumerate() {
        println!("{:>3} | {}", num + 1, line);
    }
}

Track the hottest reading with fold

fold isn’t limited to sums — any “carry a running answer through the whole list” problem fits, like tracking a running maximum.

fn main() {
    let temps = vec![68, 75, 71, 80, 66];

    let hottest = temps.iter().fold(i32::MIN, |max_so_far, &t| {
        if t > max_so_far { t } else { max_so_far }
    });

    println!("hottest reading: {hottest}"); // 80
}

Split a sorted list at a threshold

Given data that’s already sorted — like ages sorted ascending — take_while/skip_while split it at the first point a condition stops holding, without scanning the whole list twice by hand.

fn main() {
    let ages = vec![12, 15, 17, 18, 22, 30, 45];

    let minors: Vec<&i32> = ages.iter().take_while(|&&age| age < 18).collect();
    let adults: Vec<&i32> = ages.iter().skip_while(|&&age| age < 18).collect();

    println!("minors: {:?}", minors); // [12, 15, 17]
    println!("adults: {:?}", adults); // [18, 22, 30, 45]
}

Your turn

This should shout every name in uppercase and print the list. It doesn’t compile.

fn main() {
    let names = vec!["ferris", "rusty", "cargo"];

    let shout = names.iter().map(|s| s.to_uppercase()).collect();

    println!("{:?}", shout);
}

fn main() {
    let names = vec!["ferris", "rusty", "cargo"];

    let shout: Vec<String> = names.iter().map(|s| s.to_uppercase()).collect();
    // or equivalently:
    // let shout = names.iter().map(|s| s.to_uppercase()).collect::<Vec<String>>();

    println!("{:?}", shout); // ["FERRIS", "RUSTY", "CARGO"]
}

Quick check

Remember this

• Adaptors (map, filter, filter_map, enumerate, zip, take, skip, fold, …) are lazy — chain as many as you like before paying any cost.
• Consumers (collect, sum, count, fold, for_each, for) are what actually pull values through and run the pipeline.
• collect() needs a target type — a type annotation on the binding or turbofish, ::<Vec<_>>().
• zip stops at the shorter of its two iterators; filter/map closures over .iter() receive references, so dereference to compare or use the value.
• More than ~4-5 chained adaptors, or any side effects, often read worse than a plain for loop with a comment — clarity beats cleverness.

Go deeper

• std::iter::Iterator docs — the full list of adaptor and consumer methods.

Next:

• Closures
• Option and Result

Closures

Intermediate · Abstractions

What & why

A closure is a little function you write right where you use it, without giving it a name — and it can remember variables from the surrounding code. You’ve already seen them living inside iterator chains (.map(|n| n * 2)). This lesson slows down and explains what those |...| bars actually are.

The idea, slowly

A function with no name

Compare a normal function to a closure that does the same thing:

fn main() {
    // normal named function
    fn double_fn(x: i32) -> i32 {
        x * 2
    }

    // closure stored in a variable
    let double_cl = |x: i32| x * 2;

    println!("{}", double_fn(5)); // 10
    println!("{}", double_cl(5)); // 10
}

The closure is |x: i32| x * 2. Read it as:

• |x: i32| — the parameter list, but with pipes | | instead of parentheses. Here it takes one i32 called x.
• x * 2 — the body. A one-expression closure doesn’t need { } or a return; the last expression is the result. (You can use braces for multi-line bodies: |x| { let y = x + 1; y * 2 }.)

Rust can usually figure out the types, so you’ll often see them dropped: let double_cl = |x| x * 2;. The types get inferred from how you call it.

The superpower: capturing the environment

Here’s what makes a closure different from a plain function — it can use variables from the code around it, without you passing them in:

fn main() {
    let tax = 0.1;

    // this closure "captures" tax from the surrounding scope
    let with_tax = |price: f64| price + price * tax;

    println!("{}", with_tax(100.0)); // 110
    println!("{}", with_tax(50.0));  // 55
}

with_tax uses tax even though tax was never passed in as an argument. The closure captured it from the environment. A normal fn cannot do this — a top-level function only sees its own parameters. This is exactly why closures shine in iterator chains: .filter(|n| *n > threshold) can reach out and grab your local threshold.

What the compiler is thinking: “This closure mentions tax, which lives outside it. I need to keep tax available for the closure to use.” It quietly bundles the captured variable together with the code.

How a closure captures: borrow, or move

By default a closure captures by borrowing — it just peeks at the variable, like &:

fn main() {
    let name = String::from("Rust");

    let greet = || println!("Hello, {}", name); // borrows name
    greet();
    greet();

    println!("still have: {}", name); // name is still usable — only borrowed
}

But sometimes you need the closure to own what it captures — especially if the closure will outlive the current scope (for example, handed to a thread). You force that with the move keyword:

fn main() {
    let name = String::from("Rust");

    let greet = move || println!("Hello, {}", name); // takes ownership of name
    greet();
    // println!("{}", name); // ERROR now: name was moved into the closure
}

move tells the closure “take these captured variables with you.” After that, the original variable is gone from the outer scope — same move rules you learned in Ownership, just applied to captured values.

Passing a closure to a function

Functions can accept closures as arguments. You describe “a thing I can call” with the Fn trait family:

fn apply_twice<F: Fn(i32) -> i32>(f: F, start: i32) -> i32 {
    f(f(start))
}

fn main() {
    let add_three = |x| x + 3;
    println!("{}", apply_twice(add_three, 10)); // 10 -> 13 -> 16
}

F: Fn(i32) -> i32 reads as “F is some callable that takes an i32 and returns an i32.” That’s a trait bound (from the Generics lesson), and it lets apply_twice accept any matching closure. The three closure traits are Fn (just reads captured values), FnMut (changes them), and FnOnce (consumes them) — for most beginner code, Fn is all you need to recognize.

Common mistakes

• Pipes vs parentheses. Closure parameters go between | |, not ( ). Writing (x) x * 2 isn’t a closure. The shape is |params| body.
• Using a captured variable after move. Once you write move ||, captured owning values (like a String) are moved into the closure; touching the original afterward gives value moved. Only add move when you actually need the closure to own its captures.
• Expecting a closure to work in a place a plain fn is required. Some very low-level spots want a bare function pointer, not a capturing closure. If a closure captures nothing, it can coerce to a function pointer; if it captures, it can’t. The error mentions expected fn pointer, found closure.
• Over-stuffing a closure. A closure with twenty lines of logic is harder to read than a named function. Keep closures short and near their use; promote big logic to a real fn.
• Forgetting the return type/expression rule. In |x| x + 1, there’s no ; after x + 1 — adding one (|x| { x + 1; }) turns it into a closure that returns nothing (()), which usually breaks the caller.

More examples

Sort products by a custom key

sort_by_key takes a closure that picks the value to sort by — here, sorting a product list by price instead of name.

fn main() {
    let mut products = vec![("mouse", 25), ("keyboard", 60), ("mat", 10)];

    products.sort_by_key(|&(_, price)| price);

    println!("{:?}", products); // [("mat", 10), ("mouse", 25), ("keyboard", 60)]
}

A counter closure that remembers state

A closure that mutates a captured variable across calls — like a request counter or ID generator — needs FnMut, which is why it’s stored in a mut binding.

fn main() {
    let mut count = 0;
    let mut tick = || {
        count += 1;
        count
    };

    println!("{}", tick()); // 1
    println!("{}", tick()); // 2
    println!("{}", tick()); // 3
}

A function that builds a closure

Sometimes you want a family of closures — like discount calculators for different percentages. A function can return one, tailored by its arguments.

fn make_discounter(percent: f64) -> impl Fn(f64) -> f64 {
    move |price| price - price * percent / 100.0
}

fn main() {
    let ten_percent_off = make_discounter(10.0);
    println!("{}", ten_percent_off(200.0)); // 180
    println!("{}", ten_percent_off(50.0));  // 45
}

Pass a closure as a callback

Handing a closure into a function as “what to do with each item” is a common pattern for things like processing orders one at a time.

fn process_orders(orders: &[&str], on_each: impl Fn(&str)) {
    for order in orders {
        on_each(order);
    }
}

fn main() {
    let orders = ["order-1", "order-2", "order-3"];
    process_orders(&orders, |o| println!("shipping {o}"));
}

Filter with a captured threshold

A closure that reaches out and grabs a local variable — like a reorder threshold — is what makes .filter() so handy for one-off business rules.

fn main() {
    let inventory = vec![5, 12, 3, 20, 8];
    let low_stock_limit = 10;

    let low_stock: Vec<&i32> = inventory.iter().filter(|&&qty| qty < low_stock_limit).collect();

    println!("reorder these: {:?}", low_stock); // [5, 3, 8]
}

Your turn

This should build a closure that adds a captured bonus to any score, then apply it. It doesn’t compile — the closure syntax is wrong.

fn main() {
    let bonus = 5;

    let add_bonus = (score) score + bonus;

    println!("{}", add_bonus(10));
    println!("{}", add_bonus(20));
}

fn main() {
    let bonus = 5;

    let add_bonus = |score| score + bonus; // pipes, and it captures bonus

    println!("{}", add_bonus(10)); // 15
    println!("{}", add_bonus(20)); // 25
}

Quick check

Remember this

• A closure is an unnamed function written inline: |params| body.
• Its superpower is capturing variables from the surrounding scope — a plain fn can’t do that.
• By default closures borrow what they capture; add move to make them own it (needed when the closure outlives the scope, e.g. threads).
• Functions accept closures via the Fn / FnMut / FnOnce trait bounds.
• Keep closures small; promote big logic to a named function.

Go deeper

• Rust Book - Closures — How closures capture state.

Next:

• Error handling
• Concurrency

Option and Result

Intermediate · Abstractions

What & why

Most languages let a function secretly fail — throw an exception, return null, crash — and you find out at 2am. Rust makes failure part of the return type, so the compiler forces you to deal with it before your program runs. Option<T> says “there might not be a value”; Result<T, E> says “this might fail, and here’s why.” Once you’re comfortable with match on both, the real payoff is their combinators — .map(), .and_then(), .unwrap_or(), .ok_or() — which let you chain transformations without unwrapping early and re-wrapping by hand.

The idea, slowly

Option: maybe there’s a value, maybe not

Option<T> is Rust’s honest answer to “this might have nothing.” It has exactly two shapes: Some(value) (there’s a value) or None (there isn’t). This is what replaces null — but unlike null, you can’t accidentally use it as if a value were there, because the compiler makes you check.

fn main() {
    let names = vec!["Alice", "Bob"];

    match names.get(5) {         // .get returns Option: Some or None
        Some(name) => println!("found {}", name),
        None => println!("nobody at index 5"),
    }
}

match forces you to write both branches — the found case and the empty case. Forget one and the compiler refuses to build, saying the match isn’t exhaustive. That’s Rust removing an entire category of “I forgot to check for null” bugs.

Result: it worked, or here’s why it failed

Result<T, E> is for operations that can fail with a reason. Its two shapes are Ok(value) (success, here’s the result) and Err(problem) (failure, here’s what went wrong). Parsing text into a number is a classic example — it fails if the text isn’t a number:

fn main() {
    let good: Result<i32, _> = "42".parse();
    let bad: Result<i32, _> = "oops".parse();

    match good {
        Ok(n) => println!("parsed {}", n),
        Err(e) => println!("failed: {}", e),
    }

    match bad {
        Ok(n) => println!("parsed {}", n),
        Err(e) => println!("failed: {}", e), // this one runs
    }
}

Again match makes you handle both outcomes. The Err carries a real error value describing what happened, not just a silent false.

unwrap and expect: the “I’m sure” shortcuts (careful!)

Sometimes you just want the value and are willing to crash if it’s missing. unwrap() and expect(...) do that — they hand back the inner value on success, and panic (crash the program) on None/Err:

fn main() {
    let n: i32 = "42".parse().unwrap(); // fine: it IS a number
    println!("{}", n);

    let ok = "7".parse::<i32>().expect("should be a number");
    println!("{}", ok);
    // "oops".parse::<i32>().unwrap(); // would CRASH the program
}

These are handy in tiny examples and tests. In real programs, reaching for unwrap everywhere means “crash on any problem,” which is rarely what you want. expect is slightly better than unwrap because its message tells you which unwrap blew up — but neither is a substitute for actually handling the failure.

Combinators: transforming without unwrapping

Writing match every time you touch an Option/Result gets verbose, especially when all you want to do is “if there’s a value, transform it” or “if it failed, use a default.” Both types have methods for exactly this — you stay inside the Option/Result “container” the whole time instead of unwrapping, checking, and re-wrapping by hand.

.map() transforms the value inside Some/Ok, leaving None/Err untouched:

fn main() {
    let price: Option<i32> = Some(10);
    let with_tax = price.map(|p| p * 110 / 100);
    println!("{:?}", with_tax); // Some(11)

    let missing: Option<i32> = None;
    let still_missing = missing.map(|p| p * 110 / 100);
    println!("{:?}", still_missing); // None — map never runs the closure
}

.and_then() is for when the next step is itself fallible — the closure you pass must return an Option/Result, not a bare value. This chains fallible steps without nesting Option<Option<T>>:

fn half_if_even(n: i32) -> Option<i32> {
    if n % 2 == 0 { Some(n / 2) } else { None }
}

fn main() {
    let x = Some(8).and_then(half_if_even).and_then(half_if_even);
    println!("{:?}", x); // Some(2)  (8 -> 4 -> 2)

    let y = Some(7).and_then(half_if_even);
    println!("{:?}", y); // None — 7 is odd, chain stops
}

What the compiler is thinking: with .map(f), it expects f: T -> U and wraps the result back in Some/Ok for you. With .and_then(f), it expects f: T -> Option<U> (or Result<U, E>) and does not re-wrap — if your closure returns a bare value instead of Some(value), that’s a type mismatch, not a missing wrap.

.unwrap_or(default) and .unwrap_or_else(|| ...) get you a plain value out, no panic risk — you supply a fallback instead:

fn main() {
    let a: Option<i32> = None;
    println!("{}", a.unwrap_or(0)); // 0

    let b: Result<i32, String> = Err("bad input".to_string());
    println!("{}", b.unwrap_or_else(|_e| -1)); // -1, computed lazily from the error
}

Use .unwrap_or(x) when the fallback is cheap to compute up front; use .unwrap_or_else(|| ...) when computing it is expensive or needs the error value — the closure only runs on the failure path.

.ok_or(err) turns an Option into a Result by supplying the error to use for None. .ok() goes the other way, turning a Result into an Option and throwing away the error:

fn main() {
    let found: Option<i32> = None;
    let as_result: Result<i32, &str> = found.ok_or("not found");
    println!("{:?}", as_result); // Err("not found")

    let parsed: Result<i32, _> = "42".parse();
    let as_option: Option<i32> = parsed.ok();
    println!("{:?}", as_option); // Some(42)
}

.filter() on Option keeps Some(value) only if a predicate returns true; otherwise it becomes None:

fn parse_positive(text: &str) -> Option<i32> {
    text.parse::<i32>().ok().filter(|&n| n > 0)
}

fn main() {
    println!("{:?}", parse_positive("21")); // Some(21)
    println!("{:?}", parse_positive("-5")); // None — filtered out
    println!("{:?}", parse_positive("oops")); // None — parse failed first
}

Chained together, combinators read like a pipeline: text.parse::<i32>().ok().filter(|&n| n > 0).map(|n| n * 2).unwrap_or(0) — parse it, drop it if parsing failed or it’s not positive, double it, or fall back to 0. No match, no intermediate variables.

Common mistakes

• unwrap() in real code. It crashes the whole program on the first None/Err. Fine for a quick test; risky in anything a user runs. Prefer match, if let, a combinator, or ? (next lesson).
• Passing .and_then() a closure that returns a bare value instead of Option/Result. .and_then(|n| n + 1) doesn’t compile — the closure must return Some(n + 1) (or Ok/Err). If your closure just transforms the value, you wanted .map(), not .and_then().
• Reaching for .and_then() when .map() would do. If your closure can’t fail, .map() is simpler and doesn’t need you to wrap the result.
• Confusing Option with Result. Use Option when something is simply absent (no error to report); use Result when there’s a reason it failed you want to carry. .ok_or() and .ok() exist precisely because this choice sometimes needs to change mid-pipeline.
• Ignoring a Result entirely. Rust warns if you drop a Result on the floor (unused Result that must be used). Handle it, propagate it, or explicitly let _ = ... if you truly mean to ignore it.

More examples

Chain a parse, then a division that can also fail

Two fallible steps in a row — parsing text, then dividing (which fails on zero) — chain naturally with .and_then() instead of nested match.

fn safe_divide(a: i32, b: i32) -> Option<i32> {
    if b == 0 { None } else { Some(a / b) }
}

fn main() {
    let result = "20".parse::<i32>().ok().and_then(|n| safe_divide(n, 4));
    println!("{:?}", result); // Some(5)

    let by_zero = "20".parse::<i32>().ok().and_then(|n| safe_divide(n, 0));
    println!("{:?}", by_zero); // None
}

Fall back to a sensible default for a missing setting

When a config value is simply absent, .unwrap_or_default() grabs the type’s default (0 for numbers, "" for strings) instead of making you spell out a fallback.

fn main() {
    let raw_config: Option<u32> = None; // key was missing from the config file
    let timeout_secs: u32 = raw_config.unwrap_or_default();

    println!("timeout: {timeout_secs}s"); // 0 -- u32's default
}

Handle one special case by hand, ? for the rest

Not every fallible step deserves the same treatment — here an empty cart is handled explicitly, while everything else flows through ? normally.

fn checkout_total(cart_total: &str) -> Result<i32, String> {
    let total: i32 = match cart_total {
        "0" => return Err("cart is empty".to_string()), // one special case, by hand
        text => text.parse().map_err(|_| "bad total".to_string())?, // normal path uses ?
    };
    Ok(total + 5) // add flat shipping
}

fn main() {
    println!("{:?}", checkout_total("40"));   // Ok(45)
    println!("{:?}", checkout_total("0"));    // Err("cart is empty")
    println!("{:?}", checkout_total("oops")); // Err("bad total")
}

Reject a value that fails a format check

.filter() on Option isn’t just for numeric ranges — it works for any predicate, like rejecting a username that contains spaces.

fn main() {
    let username: Option<&str> = Some("ferris the crab");

    let valid = username.filter(|name| !name.contains(' '));

    println!("{:?}", valid); // None -- contains a space
}

Build a receipt line with chained .map()s

When each step can’t fail, chaining multiple .map() calls reads like a small pipeline — compute a price, then format it, all without unwrapping in between.

fn main() {
    let quantity: Option<i32> = Some(3);

    let receipt_line = quantity
        .map(|q| q * 25)              // price per item is $25
        .map(|total| format!("${total}"));

    println!("{:?}", receipt_line); // Some("$75")
}

Your turn

This function should parse a price string, apply a 10% discount, and fall back to 0 if parsing fails — but it doesn’t compile.

fn discounted_price(text: &str) -> i32 {
    text.parse::<i32>()
        .and_then(|n| n * 90 / 100)
        .unwrap_or(0)
}

fn main() {
    println!("{}", discounted_price("100")); // want: 90
    println!("{}", discounted_price("oops")); // want: 0
}

fn discounted_price(text: &str) -> i32 {
    text.parse::<i32>()
        .map(|n| n * 90 / 100)
        .unwrap_or(0)
}

fn main() {
    println!("{}", discounted_price("100")); // 90
    println!("{}", discounted_price("oops")); // 0
}

Quick check

Remember this

• Option<T> = Some(v) or None — a value might be missing (Rust’s safe replacement for null).
• Result<T, E> = Ok(v) or Err(e) — an operation might fail with a reason.
• match forces you to handle every case, so you can’t forget the failure path.
• .map(f) transforms the success value (f returns a plain value); .and_then(f) chains another fallible step (f returns Option/Result).
• .unwrap_or(default) / .unwrap_or_else(|| ...) get a plain value out with a fallback; .ok_or(err) and .ok() convert between Option and Result; .filter() turns Some into None when a predicate fails.
• unwrap() / expect() grab the value but panic on failure; use them sparingly, mostly in tests and quick scripts.

Go deeper

• Rust Book - Error Handling — Option, Result, and ?.

Next:

• The ? operator
• Custom error types

The ? operator

Intermediate · Abstractions

What & why

Writing a match at every fallible step — parse this, or return the error; read that, or return the error — gets tedious fast, and the boilerplate drowns out the actual logic. The ? operator is the shortcut: put it after something that returns Result (or Option), and it means “if this succeeded, give me the value; if it failed, stop and return that failure from my function right now.” It only works inside a function whose own return type is Result/Option, and — its real superpower — it can convert between different error types along the way.

The idea, slowly

? is sugar for a match

Take this function without ?:

use std::num::ParseIntError;

fn double_from_text_verbose(text: &str) -> Result<i32, ParseIntError> {
    let n = match text.parse::<i32>() {
        Ok(value) => value,
        Err(e) => return Err(e), // bail out immediately with the error
    };
    Ok(n * 2)
}

fn main() {
    println!("{:?}", double_from_text_verbose("10"));   // Ok(20)
    println!("{:?}", double_from_text_verbose("nope")); // Err(ParseIntError { .. })
}

? collapses that entire match into one character:

use std::num::ParseIntError;

fn double_from_text(text: &str) -> Result<i32, ParseIntError> {
    let n = text.parse::<i32>()?; // on error, return the Err right here
    Ok(n * 2)                     // on success, continue
}

fn main() {
    println!("{:?}", double_from_text("10"));   // Ok(20)
    println!("{:?}", double_from_text("nope")); // Err(ParseIntError { .. })
}

What the compiler is thinking: at the ?, it inserts “check: is this Err? If so, return Err(...) right now — converting the error type if needed (more on that below). Otherwise, unwrap the Ok and keep going.” Notice the success path still wraps the answer in Ok(...) — ? only handles the early-return side; the function’s normal return still needs to produce a Result.

Why ? only works in a Result/Option-returning function

?’s early return has to return something from the enclosing function — specifically, an Err (or None). If the function doesn’t return Result/Option, there’s nowhere for that early return to go, and the compiler refuses:

error[E0277]: the `?` operator can only be used in a function that returns `Result` or `Option`

The fix is always the same shape: give the function a Result<T, E> (or Option<T>) return type so ? has something to return early with.

The hidden superpower: ? converts error types via From

Real functions often call into several things that fail with different error types. ? doesn’t just return the error as-is — it calls From::from on it, converting it into whatever error type the function declares. As long as From<SourceError> for MyError exists, ? uses it automatically:

use std::error::Error;

fn parse_env_number(key: &str) -> Result<i32, Box<dyn Error>> {
    let text = std::env::var(key)?; // VarError converts into Box<dyn Error>
    let n: i32 = text.parse()?;     // ParseIntError converts into Box<dyn Error>
    Ok(n)
}

fn main() {
    match parse_env_number("PORT") {
        Ok(n) => println!("port: {n}"),
        Err(e) => println!("couldn't read PORT: {e}"),
    }
}

Here std::env::var fails with VarError and .parse() fails with ParseIntError — two unrelated types — but both ?s work because Box<dyn Error> has a blanket From impl for any type implementing std::error::Error. The function only has to declare one error type; ? does the conversion at each call site. (The next two lessons build on exactly this: writing your own error type with From impls, and letting thiserror/anyhow generate them for you.)

? works on Option too

The same operator works in a function returning Option: on Some, it unwraps; on None, it returns None immediately.

fn first_upper_char(text: &str) -> Option<char> {
    let c = text.chars().next()?; // None if text is empty — return None right here
    Some(c.to_ascii_uppercase())
}

fn main() {
    println!("{:?}", first_upper_char("rust")); // Some('R')
    println!("{:?}", first_upper_char(""));      // None
}

main can return a Result too

Because ? needs a Result/Option-returning function to work in, and you’ll often want to use ? at the top level, fn main is allowed to return Result<(), E>:

fn main() -> Result<(), std::num::ParseIntError> {
    let n: i32 = "123".parse()?;
    println!("got {}", n);
    Ok(())
}

Ok(()) means “succeeded, with no meaningful value” — () is Rust’s empty type. If a ? inside main hits an error, the program exits with a nonzero status and prints the error using its Debug output.

Common mistakes

• Using ? in a function that doesn’t return Result/Option. The error is the ? operator can only be used in a function that returns Result or Option. Change the function’s return type, or handle the error with match instead.
• Forgetting to wrap the success value in Ok(...). In a -> Result<...> function, the happy path must return Ok(value), not a bare value. ? only rewrites the error path; the normal return is still your job.
• Using ? across two error types with no From impl between them. If your function returns Result<T, ParseIntError> but you ? on something that fails with std::io::Error, the compiler can’t find a conversion and refuses to build. Either widen the return type (e.g. to Box<dyn Error>), or write the From impl yourself (next lesson).
• Expecting ? to work in a closure the same way it does in the enclosing function. ? returns from the nearest enclosing function — inside a closure, that’s the closure, not main. If the closure’s return type isn’t Result/Option too, it won’t compile.

More examples

Chain three fallible steps in one function

Real functions rarely stop at one ? — computing an order total might mean parsing a quantity, a price, and a tax figure, each of which can fail on its own.

use std::num::ParseIntError;

fn total_cost(qty_text: &str, price_text: &str, tax_text: &str) -> Result<i32, ParseIntError> {
    let qty: i32 = qty_text.parse()?;     // step 1
    let price: i32 = price_text.parse()?; // step 2
    let tax: i32 = tax_text.parse()?;     // step 3
    Ok(qty * price + tax)
}

fn main() {
    println!("{:?}", total_cost("3", "20", "5"));   // Ok(65)
    println!("{:?}", total_cost("3", "oops", "5")); // Err(...)
}

Convert a library error into your own error type

Instead of erasing everything into Box<dyn Error>, a small app-specific error enum with a From impl lets ? convert automatically while keeping a concrete, matchable type.

use std::num::ParseIntError;

#[derive(Debug)]
enum ConfigError {
    BadNumber(ParseIntError),
}

impl From<ParseIntError> for ConfigError {
    fn from(e: ParseIntError) -> Self {
        ConfigError::BadNumber(e)
    }
}

fn read_port(text: &str) -> Result<i32, ConfigError> {
    let port: i32 = text.parse()?; // ParseIntError auto-converts via From
    Ok(port)
}

fn main() {
    println!("{:?}", read_port("8080")); // Ok(8080)
    println!("{:?}", read_port("nope")); // Err(BadNumber(...))
}

? inside a helper, called from main

A helper function’s Result doesn’t stop at its own boundary — call it with ? from another Result-returning function, including main itself.

fn parse_pair(a: &str, b: &str) -> Result<(i32, i32), std::num::ParseIntError> {
    Ok((a.parse()?, b.parse()?))
}

fn main() -> Result<(), std::num::ParseIntError> {
    let (x, y) = parse_pair("4", "5")?; // helper's Result propagates into main
    println!("sum: {}", x + y);
    Ok(())
}

? on an Option, inside a function returning Option

Extracting a filename’s extension is a classic “might not exist” lookup — ? on Option bails out cleanly the moment there’s nothing to find.

fn file_extension(name: &str) -> Option<&str> {
    let dot_index = name.rfind('.')?; // None if there's no dot at all
    Some(&name[dot_index + 1..])
}

fn main() {
    println!("{:?}", file_extension("report.pdf")); // Some("pdf")
    println!("{:?}", file_extension("README"));      // None
}

Stop a batch job at the first bad value

Inside a loop, ? still bails out of the whole function on the first failure — handy for validating a batch of input where one bad value should stop everything.

fn parse_all(values: &[&str]) -> Result<Vec<i32>, std::num::ParseIntError> {
    let mut out = Vec::new();
    for v in values {
        out.push(v.parse::<i32>()?); // bails out of the whole function on the first bad value
    }
    Ok(out)
}

fn main() {
    println!("{:?}", parse_all(&["1", "2", "3"]));      // Ok([1, 2, 3])
    println!("{:?}", parse_all(&["1", "oops", "3"]));   // Err(...)
}

Your turn

This function should read a PORT environment variable and parse it as a number, but it doesn’t compile.

use std::num::ParseIntError;

fn parse_env_number(key: &str) -> Result<i32, ParseIntError> {
    let text = std::env::var(key)?; // env::var fails with VarError, not ParseIntError
    let n: i32 = text.parse()?;
    Ok(n)
}

fn main() {
    println!("{:?}", parse_env_number("PORT"));
}

use std::error::Error;

fn parse_env_number(key: &str) -> Result<i32, Box<dyn Error>> {
    let text = std::env::var(key)?; // VarError -> Box<dyn Error>
    let n: i32 = text.parse()?;     // ParseIntError -> Box<dyn Error>
    Ok(n)
}

fn main() {
    println!("{:?}", parse_env_number("PORT"));
}