by <artist>" and the total runtime 5 } ``` Solution ```rust 1 #[derive(Debug, Clone)] 2 struct Track { 3 title: String, 4 duration_secs: u32, 5 } 6 7 #[derive(Debug, Clone)] 8 struct Album { 9 title: String, 10 artist: String, 11 tracks: Vec<Track>, 12 } 13 14 fn total_runtime(album: &Album) -> u32 { 15 album.tracks.iter().map(|t| t.duration_secs).sum() 16 } 17 18 fn main() { 19 let album = Album { 20 title: String::from("Crate Sounds"), 21 artist: String::from("The Borrow Checkers"), 22 tracks: vec![ 23 Track { title: String::from("Move Semantics"), duration_secs: 210 }, 24 Track { title: String::from("Lifetime"), duration_secs: 185 }, 25 Track { title: String::from("Drop"), duration_secs: 240 }, 26 ], 27 }; 28 29 let secs = total_runtime(&album); 30 println!("{} by {}", album.title, album.artist); 31 println!("{} tracks, {}:{:02} total", album.tracks.len(), secs / 60, secs % 60); 32 } ``` Output: ```text 1 Crate Sounds by The Borrow Checkers 2 3 tracks, 10:35 total ``` *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * A Rust **struct** is the equivalent of a TypeScript `interface` + object literal, fused into one type that exists at compile time and runtime. * Every field has a **concrete type**, and **all fields must be initialized** at instantiation: there is no `undefined`. * **Mutation requires `let mut`** on the whole binding; there is no per-field `mut`. * A struct **owns its fields**: moving the struct moves the data, and you can even move a single owned field out (a partial move). * **`#[derive(Debug)]`** enables `{:?}` printing and **`#[derive(Clone)]`** gives you an explicit, deep `.clone()`: conveniences that are automatic in TypeScript but opt-in in Rust. # Tuple Structs and Unit Structs > Rust tuple structs and unit structs give primitives a nominal, zero-cost identity via the newtype pattern, where TypeScript only has erasable branded types. Beyond the named-field structs you met in [Structs](/06-data-structures/00-structs/), Rust offers two leaner shapes: **tuple structs**, which have positional fields and no names, and **unit structs**, which have no fields at all. Both enable the **newtype pattern**: a zero-cost way to give a primitive a distinct, type-checked identity. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **tuple struct** is a named type whose fields are accessed by position (`.0`, `.1`) instead of by name, and a **unit struct** is a type that holds no data at all. To a TypeScript developer they look like odd corners of the language, but they enable something TypeScript cannot do cheaply: wrapping a primitive in a brand-new nominal type (the **newtype pattern**) so the compiler rejects mixing, say, a `Meters` with a `Seconds`. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript, you usually reach for a tuple type or an object when you want a small fixed group of values, and you fake distinct primitive types with **branded types** because TypeScript is structurally typed. ```typescript 1 // A positional pair — TypeScript tuple type 2 type Rgb = [number, number, number]; 3 const red: Rgb = [255, 0, 0]; 4 console.log(red[0], red[1], red[2]); // 255 0 0 5 6 // "Distinct" primitive types via branding (a common workaround) 7 type Meters = number & { readonly __brand: "Meters" }; 8 type Seconds = number & { readonly __brand: "Seconds" }; 9 10 const meters = (n: number): Meters => n as Meters; 11 const seconds = (n: number): Seconds => n as Seconds; 12 13 function addDistance(a: Meters, b: Meters): Meters { 14 return meters(a + b); 15 } 16 17 const d = meters(5); 18 const t = seconds(2); 19 addDistance(d, t); // TS error, BUT only because of the fake brand 20 addDistance(d, 2 as Meters); // compiles — the brand is erased at runtime ``` **Key points:** * TypeScript is **structurally typed**: any `number` is interchangeable with any other `number` at runtime. * The “brand” trick (`number & { __brand }`) buys compile-time distinction, but it is erased at runtime and leaks through any `as` cast. * There is no runtime cost difference: a branded `Meters` is just a `number`. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust gives you real, **nominally distinct** types with no runtime overhead, using tuple structs. ```rust 1 // A tuple struct: positional fields, accessed by .0 / .1 / .2 2 struct Rgb(u8, u8, u8); 3 4 // Newtype pattern: one-field tuple structs that are genuinely different types 5 struct Meters(f64); 6 struct Seconds(f64); 7 8 fn add_distance(a: Meters, b: Meters) -> Meters { 9 Meters(a.0 + b.0) 10 } 11 12 fn main() { 13 let red = Rgb(255, 0, 0); 14 println!("{} {} {}", red.0, red.1, red.2); // 255 0 0 15 16 let d = Meters(5.0); 17 let t = Seconds(2.0); 18 let total = add_distance(d, Meters(2.0)); 19 println!("{}", total.0); // 7 20 // add_distance(d, t); // does not compile (error[E0308]): expected `Meters`, found `Seconds` 21 let _ = t; 22 } ``` Running it prints: ```text 1 255 0 0 2 7 ``` **Key points:** * `Rgb`, `Meters`, and `Seconds` are real types, not aliases — the compiler enforces the distinction with no `as`-style escape hatch. * A one-field tuple struct like `Meters(f64)` is the **newtype pattern** (more below). * Fields are positional: `.0`, `.1`, `.2`. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Tuple structs: tuples with a name [Section titled “Tuple structs: tuples with a name”](#tuple-structs-tuples-with-a-name) A plain tuple `(u8, u8, u8)` is anonymous: any `(u8, u8, u8)` is the same type as any other. A **tuple struct** attaches a name, turning it into its own type: ```rust 1 struct Rgb(u8, u8, u8); // declaration: a 3-field tuple struct 2 3 fn main() { 4 let red = Rgb(255, 0, 0); // construction looks like a function call 5 println!("{}", red.0); // field access by index 6 } ``` Compared with the named-field struct from [Structs](/06-data-structures/00-structs/), a tuple struct trades self-documenting field names for brevity. Use it when the meaning of each position is obvious — `Point(f64, f64)`, `Rgb(u8, u8, u8)` — and a named struct when it is not. You can destructure a tuple struct in a `let` binding, just like a tuple (full coverage in [Pattern Matching](/06-data-structures/04-pattern-matching/)): ```rust 1 struct Point(f64, f64); 2 3 fn main() { 4 let origin = Point(0.0, 0.0); 5 let Point(x, y) = origin; // bind the two fields by position 6 println!("x = {x}, y = {y}"); 7 } ``` ### Unit structs: a type with no data [Section titled “Unit structs: a type with no data”](#unit-structs-a-type-with-no-data) A **unit struct** has no fields. It is named after the *unit type* `()` (the empty tuple), and it carries no data at all: ```rust 1 struct AlwaysEqual; // no fields, no parentheses 2 3 fn main() { 4 let _subject = AlwaysEqual; // the value and the type share a name 5 } ``` Why would you want a value that holds nothing? Because in Rust, **behavior lives on types via traits** (see [impl blocks](/06-data-structures/05-impl-blocks/) and section 09). A unit struct is the perfect peg to hang a trait implementation on when there is no state to store: a strategy object, a marker, or a typestate token. It is **zero-sized**: it occupies 0 bytes. ```rust 1 fn main() { 2 struct AlwaysEqual; 3 println!("{}", std::mem::size_of::<AlwaysEqual>()); // 0 4 } ``` > **Note:** TypeScript has no real equivalent. The closest analogue to a stateless “strategy” is a function or an object literal with only methods, but those still allocate. A Rust unit struct is genuinely empty. ### The newtype pattern (teaser) [Section titled “The newtype pattern (teaser)”](#the-newtype-pattern-teaser) A tuple struct with exactly **one** field is called a **newtype**. It wraps an existing type to give it a fresh identity: ```rust 1 struct Meters(f64); // a brand-new type that happens to hold an f64 2 struct UserId(u64); // not interchangeable with a raw u64 or an OrderId ``` The newtype is the workhorse behind three big wins, each expanded in the sections below: 1. **Type-safe domain modeling**: a `Meters` cannot be passed where `Seconds` is expected. 2. **Zero runtime cost**: `Meters(f64)` has the exact same size as `f64` and is compiled away to a bare `f64` at runtime. (If you also need the *memory layout* guaranteed identical — for FFI, say — add `#[repr(transparent)]`, which makes that promise explicit; the default representation guarantees size and zero overhead but not layout.) 3. **Bypassing the orphan rule**: you can implement an external trait (like `Display`) on a newtype wrapping an external type (like `Vec<String>`). That a newtype is free is easy to confirm: ```rust 1 #[derive(Clone, Copy)] 2 struct Wrapper(u32); 3 4 fn main() { 5 println!("{}", std::mem::size_of::<u32>()); // 4 6 println!("{}", std::mem::size_of::<Wrapper>()); // 4 — identical 7 } ``` > **Tip:** Because the newtype is the same size as its inner value and carries no runtime tag, you get nominal type safety for the price of structural data. This is the opposite trade-off from TypeScript’s branded types, which are *only* compile-time and vanish entirely at runtime. ### Adding behavior with `impl` [Section titled “Adding behavior with impl”](#adding-behavior-with-impl) Tuple structs and unit structs get `impl` blocks just like named structs ([impl blocks](/06-data-structures/05-impl-blocks/), [associated functions](/06-data-structures/06-associated-functions/)): ```rust 1 #[derive(Debug, Clone, Copy)] 2 struct Celsius(f64); 3 4 impl Celsius { 5 // associated function (constructor) — see associated-functions.md 6 fn from_fahrenheit(f: f64) -> Self { 7 Celsius((f - 32.0) * 5.0 / 9.0) 8 } 9 10 // method 11 fn to_fahrenheit(&self) -> f64 { 12 self.0 * 9.0 / 5.0 + 32.0 13 } 14 } 15 16 fn main() { 17 let body = Celsius(37.0); 18 println!("{:.1}F", body.to_fahrenheit()); // 98.6F 19 let freezing = Celsius::from_fahrenheit(32.0); 20 println!("{freezing:?}"); // Celsius(0.0) 21 } ``` Output: ```text 1 98.6F 2 Celsius(0.0) ``` A unit struct most often exists *to* carry an `impl` of some trait: ```rust 1 trait Greet { 2 fn greet(&self) -> String; 3 } 4 5 struct EnglishGreeter; // holds nothing; exists only to implement Greet 6 7 impl Greet for EnglishGreeter { 8 fn greet(&self) -> String { 9 "Hello!".to_string() 10 } 11 } 12 13 fn main() { 14 let greeter = EnglishGreeter; 15 println!("{}", greeter.greet()); // Hello! 16 } ``` *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / JavaScript | Rust | | --------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------- | | Positional group | `type T = [number, string]` (anonymous, structural) | `struct T(i32, String);` (named, nominal) | | Distinct primitive | Branded type `number & { __brand }`: compile-time only, erased at runtime | Newtype `struct Meters(f64);`: real type, enforced everywhere | | Empty value-with-behavior | function / object literal of methods (allocates) | unit struct `struct Marker;` (zero-sized) | | Runtime cost of the wrapper | none (brand is erased), but no real safety | none (monomorphized away), full safety | | Field access | `t[0]`, `t[1]` | `t.0`, `t.1` | | Escape hatch | `value as Meters` defeats the brand | no implicit conversion; you must call `.0` deliberately | The headline difference: **TypeScript is structurally typed, Rust is nominally typed.** In TypeScript two types with the same shape are the same type. In Rust, `Meters(f64)` and `Seconds(f64)` have identical shape but are categorically different, and the compiler will never silently convert one to the other. > **Note:** Tuple structs vs plain tuples mirrors named structs vs object literals. A plain tuple `(f64, f64)` is structural and anonymous; the moment you write `struct Point(f64, f64);` you have minted a distinct, nominal type. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting the field is just `.0`, not arithmetic-ready [Section titled “Pitfall 1: Forgetting the field is just .0, not arithmetic-ready”](#pitfall-1-forgetting-the-field-is-just-0-not-arithmetic-ready) A newtype is **not** its inner type, so operators do not pass through automatically. ```rust 1 struct Meters(f64); 2 3 fn main() { 4 let a = Meters(5.0); 5 let b = Meters(2.0); 6 let _c = a + b; // does not compile (error[E0369]) 7 } ``` Real compiler error: ```text 1 error[E0369]: cannot add `Meters` to `Meters` 2 --> src/main.rs:6:16 3 | 4 6 | let _c = a + b; // does not compile (error[E0369]) 5 | - ^ - Meters 6 | | 7 | Meters 8 | 9 note: an implementation of `Add` might be missing for `Meters` ``` **Fix:** operate on the inner values explicitly, then re-wrap, or implement the `Add` trait (section 09) if the arithmetic is meaningful for the domain: ```rust 1 struct Meters(f64); 2 3 fn main() { 4 let a = Meters(5.0); 5 let b = Meters(2.0); 6 let c = Meters(a.0 + b.0); // unwrap, add, re-wrap 7 println!("{}", c.0); // 7 8 } ``` ### Pitfall 2: Expecting newtypes to be interchangeable with their inner type [Section titled “Pitfall 2: Expecting newtypes to be interchangeable with their inner type”](#pitfall-2-expecting-newtypes-to-be-interchangeable-with-their-inner-type) This is the *point* of the pattern, but it surprises TypeScript developers used to branded types leaking through `as`. ```rust 1 struct Meters(f64); 2 struct Seconds(f64); 3 4 fn add_distance(a: Meters, b: Meters) -> Meters { 5 Meters(a.0 + b.0) 6 } 7 8 fn main() { 9 let d = Meters(5.0); 10 let t = Seconds(2.0); 11 add_distance(d, t); // does not compile (error[E0308]) 12 } ``` Real compiler error: ```text 1 error[E0308]: mismatched types 2 --> src/main.rs:11:21 3 | 4 11 | add_distance(d, t); // does not compile (error[E0308]) 5 | ------------ ^ expected `Meters`, found `Seconds` 6 | | 7 | arguments to this function are incorrect ``` Unlike TypeScript’s `2 as Meters`, there is no cast that papers over this. You must construct a `Meters` deliberately. ### Pitfall 3: A private inner field cannot be read from outside its module [Section titled “Pitfall 3: A private inner field cannot be read from outside its module”](#pitfall-3-a-private-inner-field-cannot-be-read-from-outside-its-module) When you put a newtype in a module and keep its field private (the default), callers cannot peek at `.0`. This is usually exactly what you want — it lets the constructor enforce invariants — but it trips people up. ```rust 1 mod email { 2 #[derive(Debug)] 3 pub struct Email(String); // the field is private (no `pub`) 4 5 impl Email { 6 pub fn parse(raw: &str) -> Email { 7 Email(raw.to_string()) 8 } 9 } 10 } 11 12 use email::Email; 13 14 fn main() { 15 let e = Email::parse("a@b.com"); 16 println!("{}", e.0); // does not compile (error[E0616]) 17 } ``` Real compiler error: ```text 1 error[E0616]: field `0` of struct `Email` is private 2 --> src/main.rs:16:22 3 | 4 16 | println!("{}", e.0); // does not compile (error[E0616]) 5 | ^ private field ``` **Fix:** expose a method like `as_str(&self) -> &str` instead of the raw field. See [associated functions](/06-data-structures/06-associated-functions/) and section 12 for module visibility. ### Pitfall 4: `(5)` is not a one-element tuple [Section titled “Pitfall 4: (5) is not a one-element tuple”](#pitfall-4-5-is-not-a-one-element-tuple) This bites people coming from any language. In Rust (as in math) `(5)` is just `5` with grouping parentheses. A one-element **tuple** needs a trailing comma: `(5,)`. This matters when you build *plain* tuples; tuple *structs* are unaffected because you write the name (`Wrapper(5)`). ```rust 1 fn main() { 2 let not_a_tuple = (5,); // one-element tuple (note the comma) 3 println!("{}", not_a_tuple.0); // 5 4 } ``` > **Warning:** Writing `let x = (5);` triggers the `unused_parens` lint. The compiler warns `unnecessary parentheses around assigned value`, because it parsed `(5)` as the integer `5`, not a tuple. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Reach for a newtype to make illegal states unrepresentable [Section titled “1. Reach for a newtype to make illegal states unrepresentable”](#1-reach-for-a-newtype-to-make-illegal-states-unrepresentable) If a function takes a `u64` user ID and a `u64` order ID, nothing stops a caller from swapping them. Wrap each in a newtype and the swap becomes a compile error: ```rust 1 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] 2 struct UserId(u64); 3 4 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] 5 struct OrderId(u64); ``` Derive the traits you would otherwise lose by wrapping the primitive (`Clone`, `Copy`, `PartialEq`, `Eq`, `Hash`, `Debug`). See [Structs](/06-data-structures/00-structs/) for the `derive` mechanism. ### 2. Keep the inner field private and validate in the constructor [Section titled “2. Keep the inner field private and validate in the constructor”](#2-keep-the-inner-field-private-and-validate-in-the-constructor) A newtype whose field is private and whose only constructor validates input becomes a **smart constructor**: once you hold an `Email`, it is guaranteed valid. ```rust 1 mod email { 2 #[derive(Debug, Clone, PartialEq)] 3 pub struct Email(String); // private field 4 5 impl Email { 6 pub fn parse(raw: &str) -> Result<Email, String> { 7 if raw.contains('@') { 8 Ok(Email(raw.to_lowercase())) 9 } else { 10 Err(format!("invalid email: {raw}")) 11 } 12 } 13 14 pub fn as_str(&self) -> &str { 15 &self.0 16 } 17 } 18 } 19 20 use email::Email; 21 22 fn main() { 23 let e = Email::parse("Alice@Example.com").unwrap(); 24 println!("{}", e.as_str()); // alice@example.com 25 26 match Email::parse("not-an-email") { 27 Ok(e) => println!("ok: {}", e.as_str()), 28 Err(msg) => println!("err: {msg}"), 29 } 30 } ``` Output: ```text 1 alice@example.com 2 err: invalid email: not-an-email ``` (`Result`, `Ok`, `Err`, and `match` are covered in section 08 and [Pattern Matching](/06-data-structures/04-pattern-matching/).) ### 3. Use a unit struct for stateless strategies and markers [Section titled “3. Use a unit struct for stateless strategies and markers”](#3-use-a-unit-struct-for-stateless-strategies-and-markers) When a type exists only to carry trait behavior — a logging sink, a hashing strategy, a typestate flag — a unit struct says “no data here” loud and clear and costs nothing. ### 4. Reach for `Deref` only when the newtype really is “a kind of” the inner type [Section titled “4. Reach for Deref only when the newtype really is “a kind of” the inner type”](#4-reach-for-deref-only-when-the-newtype-really-is-a-kind-of-the-inner-type) You can make a newtype transparently expose the inner type’s methods by implementing `Deref` (a smart-pointer trait; full treatment in section 10). This is convenient for wrappers like `Username(String)`: ```rust 1 use std::ops::Deref; 2 3 struct Username(String); 4 5 impl Deref for Username { 6 type Target = String; 7 fn deref(&self) -> &String { 8 &self.0 9 } 10 } 11 12 fn main() { 13 let name = Username("alice".to_string()); 14 // Deref coercion lets String/&str methods work directly: 15 println!("{}", name.len()); // 5 16 println!("{}", name.to_uppercase()); // ALICE 17 } ``` Output: ```text 1 5 2 ALICE ``` > **Warning:** `Deref` is a double-edged sword. It dilutes the encapsulation you bought with the newtype, because all the inner type’s methods leak out. Prefer explicit accessors (`as_str`) unless the newtype is genuinely a thin pointer-like wrapper. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) Two production-flavored uses of tuple structs come together here: **type-safe domain IDs** and a **newtype that bypasses the orphan rule** so we can implement `Display` for a `Vec<String>` (which we are not allowed to do directly, because both `Display` and `Vec` are defined outside our crate). ```rust 1 use std::fmt; 2 3 // Newtype over Vec<String> so we can implement the foreign trait `Display`. 4 // (Implementing `Display` for `Vec<String>` directly is forbidden by the 5 // orphan rule, because we own neither the trait nor the type.) 6 struct CsvRow(Vec<String>); 7 8 impl fmt::Display for CsvRow { 9 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 10 write!(f, "{}", self.0.join(",")) 11 } 12 } 13 14 // Type-safe IDs: UserId and OrderId both wrap u64 but are not interchangeable. 15 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] 16 struct UserId(u64); 17 18 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] 19 struct OrderId(u64); 20 21 fn fetch_user(id: UserId) -> String { 22 format!("user #{}", id.0) 23 } 24 25 fn order_owner(order: OrderId) -> UserId { 26 // pretend we looked this up in a database 27 UserId(order.0 % 100) 28 } 29 30 fn main() { 31 let row = CsvRow(vec!["alice".into(), "30".into(), "admin".into()]); 32 println!("{row}"); 33 34 let order = OrderId(4207); 35 let owner = order_owner(order); 36 println!("{}", fetch_user(owner)); 37 } ``` Output: ```text 1 alice,30,admin 2 user #7 ``` Because `order_owner` returns a `UserId` and `fetch_user` demands a `UserId`, the pipeline is checked end to end. Passing the raw `4207` or an `OrderId` to `fetch_user` would not compile — the kind of swap bug that branded TypeScript types only *sometimes* catch (and never at runtime) is impossible here. > **Note:** The **orphan rule** says you may implement a trait for a type only if your crate defines the trait *or* the type. Wrapping the foreign `Vec<String>` in your own `CsvRow` makes `CsvRow` a local type, so the `impl Display for CsvRow` is allowed. This is one of the most common reasons to introduce a newtype. See section 09 for the full rule. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Defining and Instantiating Structs (tuple & unit structs)](https://doc.rust-lang.org/book/ch05-01-defining-structs.html#using-tuple-structs-without-named-fields-to-create-different-types) * [The Rust Book — Using the Newtype Pattern](https://doc.rust-lang.org/book/ch20-02-advanced-traits.html#using-the-newtype-pattern-to-implement-external-traits-on-external-types) * [Rust by Example — Tuple Structs](https://doc.rust-lang.org/rust-by-example/custom_types/structs.html) * [std::ops::Deref](https://doc.rust-lang.org/std/ops/trait.Deref.html) ### Related Topics in This Guide [Section titled “Related Topics in This Guide”](#related-topics-in-this-guide) * [Structs](/06-data-structures/00-structs/): named-field structs and the `derive` mechanism this file relies on * [Field Init Shorthand](/06-data-structures/08-field-init-shorthand/): shorthand and struct-update syntax for named-field structs * [impl Blocks](/06-data-structures/05-impl-blocks/): adding methods to any struct shape * [Associated Functions](/06-data-structures/06-associated-functions/): `Self::new`-style constructors and smart constructors * [Enums](/06-data-structures/02-enums/): when a value is one-of-several shapes rather than a single wrapper * [Pattern Matching](/06-data-structures/04-pattern-matching/): destructuring tuple structs with `let` and `match` * [Basic Types](/02-basics/01-types/): the primitives newtypes usually wrap, including plain tuples * [Collections](/07-collections/): the `Vec<T>` wrapped in the real-world example *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A unit-conversion newtype [Section titled “Exercise 1: A unit-conversion newtype”](#exercise-1-a-unit-conversion-newtype) **Difficulty:** Beginner **Objective:** Practice declaring a newtype and giving it a method. **Instructions:** Define two newtypes, `Kilometers(f64)` and `Miles(f64)`, that both derive `Debug`, `Clone`, `Copy`, and `PartialEq`. Add a method `to_miles(self) -> Miles` on `Kilometers` (1 km ≈ 0.621371 mi). Convert a marathon (`42.195` km) and print both values. ```rust 1 #[derive(Debug, Clone, Copy, PartialEq)] 2 struct Kilometers(f64); 3 4 // TODO: define Miles 5 6 impl Kilometers { 7 fn to_miles(self) -> Miles { 8 /* ??? */ 9 } 10 } 11 12 fn main() { 13 let marathon = Kilometers(42.195); 14 // TODO: convert and print 15 } ``` Solution ```rust 1 #[derive(Debug, Clone, Copy, PartialEq)] 2 struct Kilometers(f64); 3 4 #[derive(Debug, Clone, Copy, PartialEq)] 5 struct Miles(f64); 6 7 impl Kilometers { 8 fn to_miles(self) -> Miles { 9 Miles(self.0 * 0.621_371) 10 } 11 } 12 13 fn main() { 14 let marathon = Kilometers(42.195); 15 let in_miles = marathon.to_miles(); 16 println!("{marathon:?} = {in_miles:?}"); 17 } ``` Output: ```text 1 Kilometers(42.195) = Miles(26.218749345) ``` ### Exercise 2: A validated newtype (smart constructor) [Section titled “Exercise 2: A validated newtype (smart constructor)”](#exercise-2-a-validated-newtype-smart-constructor) **Difficulty:** Intermediate **Objective:** Use a private field plus a fallible constructor so that holding the type guarantees an invariant. **Instructions:** Build a `NonEmptyString` newtype whose inner `String` is private. Provide `new(s: impl Into<String>) -> Option<NonEmptyString>` that returns `None` when the string is empty or only whitespace, and `Some(...)` otherwise. Add `as_str(&self) -> &str`. Show that `"hello"` succeeds and `" "` fails. Solution ```rust 1 #[derive(Debug, Clone, PartialEq)] 2 pub struct NonEmptyString(String); 3 4 impl NonEmptyString { 5 pub fn new(s: impl Into<String>) -> Option<NonEmptyString> { 6 let s = s.into(); 7 if s.trim().is_empty() { 8 None 9 } else { 10 Some(NonEmptyString(s)) 11 } 12 } 13 14 pub fn as_str(&self) -> &str { 15 &self.0 16 } 17 } 18 19 fn main() { 20 let ok = NonEmptyString::new("hello"); 21 let bad = NonEmptyString::new(" "); 22 println!("{:?}", ok.map(|n| n.as_str().to_string())); // Some("hello") 23 println!("{:?}", bad.map(|n| n.as_str().to_string())); // None 24 } ``` Output: ```text 1 Some("hello") 2 None ``` > Because the field is private and `new` is the only constructor, any `NonEmptyString` you ever hold is guaranteed non-empty. (`Option`, `map`, and `Into` are covered in [Option](/06-data-structures/03-option-enum/) and section 09.) ### Exercise 3: Unit structs as a strategy via a trait [Section titled “Exercise 3: Unit structs as a strategy via a trait”](#exercise-3-unit-structs-as-a-strategy-via-a-trait) **Difficulty:** Intermediate **Objective:** Use stateless unit structs to implement the same trait with different behavior, then dispatch over them. **Instructions:** Define a `Tax` trait with `fn rate(&self) -> f64`. Implement it for two unit structs, `UsTax` (0.07) and `EuTax` (0.20). Write `fn total(price: f64, policy: &dyn Tax) -> f64` that applies the rate, and print the total of `100.0` under each policy. Solution ```rust 1 trait Tax { 2 fn rate(&self) -> f64; 3 } 4 5 struct UsTax; 6 struct EuTax; 7 8 impl Tax for UsTax { 9 fn rate(&self) -> f64 { 0.07 } 10 } 11 12 impl Tax for EuTax { 13 fn rate(&self) -> f64 { 0.20 } 14 } 15 16 fn total(price: f64, policy: &dyn Tax) -> f64 { 17 price * (1.0 + policy.rate()) 18 } 19 20 fn main() { 21 println!("US: {:.2}", total(100.0, &UsTax)); // US: 107.00 22 println!("EU: {:.2}", total(100.0, &EuTax)); // EU: 120.00 23 } ``` Output: ```text 1 US: 107.00 2 EU: 120.00 ``` > Each unit struct is zero-sized, so this strategy abstraction costs nothing in memory. `&dyn Tax` is dynamic dispatch (a trait object), covered in section 09. # Enums and Data-Carrying Variants > Rust enums model "one of several shapes" like a TypeScript discriminated union, but the variant is the tag and the compiler forces you to handle every case. Rust **enums** are the tool you reach for when a value is “one of several shapes.” If you have ever written a TypeScript **union type** or a **discriminated union**, you already understand the *idea*. But Rust’s enums are first-class, exhaustively-checked, and can carry data per variant with zero runtime tagging overhead. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A Rust `enum` defines a type that can be exactly **one** of a fixed set of **variants**, and each variant can carry its own data. This is Rust’s answer to the TypeScript union type `A | B | C`, and especially to the **discriminated union** pattern. The big payoff for a TypeScript/JavaScript developer: the compiler *forces* you to handle every variant (no forgotten `case`), and there is no separate `kind` string to keep in sync by hand. The variant *is* the tag. **In short:** In TypeScript a discriminated union is a convention you assemble out of object types plus a literal `kind` field. In Rust an enum is a built-in language construct, so the tag and the payload are one inseparable thing. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // The classic discriminated union: a `kind` field is the discriminant, 2 // and each member carries its own payload. 3 type WebEvent = 4 | { kind: "pageLoad" } 5 | { kind: "pageUnload" } 6 | { kind: "keyPress"; key: string } 7 | { kind: "paste"; text: string } 8 | { kind: "click"; x: number; y: number }; 9 10 function describe(event: WebEvent): string { 11 switch (event.kind) { 12 case "pageLoad": 13 return "page loaded"; 14 case "pageUnload": 15 return "page unloaded"; 16 case "keyPress": 17 return `pressed '${event.key}'`; 18 case "paste": 19 return `pasted "${event.text}"`; 20 case "click": 21 return `clicked at (${event.x}, ${event.y})`; 22 // Forget a case and TypeScript only complains if you opted into 23 // exhaustiveness (e.g. a `never` default). It is not automatic. 24 } 25 } 26 27 const event: WebEvent = { kind: "click", x: 20, y: 80 }; 28 console.log(describe(event)); // clicked at (20, 80) ``` **Key points:** * The union is built by hand: object types glued together with `|`. * The `kind` string literal is the discriminant; *you* invent and maintain it. * Narrowing happens via `switch (event.kind)`; inside each `case`, TypeScript narrows `event` to the matching member. * Exhaustiveness is **opt-in** (you add a `never` trick). Miss a case and, by default, you just get `undefined` at runtime. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 // One language construct. Each variant is a shape; some carry data. 2 #[derive(Debug)] 3 enum WebEvent { 4 PageLoad, // unit-like: no data 5 PageUnload, // unit-like: no data 6 KeyPress(char), // tuple-like: one positional field 7 Paste(String), // tuple-like: one positional field 8 Click { x: i64, y: i64 }, // struct-like: named fields 9 } 10 11 fn describe(event: &WebEvent) -> String { 12 match event { 13 WebEvent::PageLoad => "page loaded".to_string(), 14 WebEvent::PageUnload => "page unloaded".to_string(), 15 WebEvent::KeyPress(c) => format!("pressed '{c}'"), 16 WebEvent::Paste(s) => format!("pasted \"{s}\""), 17 WebEvent::Click { x, y } => format!("clicked at ({x}, {y})"), 18 } 19 } 20 21 fn main() { 22 let event = WebEvent::Click { x: 20, y: 80 }; 23 println!("{}", describe(&event)); // clicked at (20, 80) 24 } ``` Running it prints: ```text 1 clicked at (20, 80) ``` **Key points:** * `enum WebEvent { ... }` declares the whole closed set of shapes in one place. * Variants come in three flavors: **unit-like** (`PageLoad`), **tuple-like** (`KeyPress(char)`), and **struct-like** (`Click { x, y }`). * The variant name *is* the discriminant — there is no separate `kind` string to maintain. * `match` narrows and destructures in one step, and (as we’ll see) the compiler checks exhaustiveness for free. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The three variant shapes, line by line [Section titled “The three variant shapes, line by line”](#the-three-variant-shapes-line-by-line) ```rust 1 enum WebEvent { 2 PageLoad, // (1) unit-like variant 3 KeyPress(char), // (2) tuple-like variant, one field 4 Paste(String), // (3) tuple-like variant, owns a String 5 Click { x: i64, y: i64 }, // (4) struct-like variant, named fields 6 } ``` 1. **Unit-like** variants carry no data. They are the closest thing to a plain TypeScript string-literal member like `{ kind: "pageLoad" }`, except there is no object at all, just a tag. 2. **Tuple-like** variants hold positional data, like a [tuple struct](/06-data-structures/01-tuple-structs/). `KeyPress(char)` holds exactly one `char`. 3. `Paste(String)` *owns* its `String`. This matters: constructing `WebEvent::Paste(s)` moves `s` into the enum (see [Section 05 — Ownership](/05-ownership/)). 4. **Struct-like** variants hold named fields, mirroring a discriminated-union member with several properties (`{ kind: "click"; x; y }`). You can mix all three flavors freely in one enum, which has no clean TypeScript equivalent: there, every union member is an object type. ### Constructing a value [Section titled “Constructing a value”](#constructing-a-value) ```rust 1 let a = WebEvent::PageLoad; // unit-like 2 let b = WebEvent::KeyPress('x'); // tuple-like 3 let c = WebEvent::Paste(String::from("hello")); // tuple-like 4 let d = WebEvent::Click { x: 20, y: 80 }; // struct-like ``` Every value is namespaced under the enum type: `WebEvent::Click`, not bare `Click`. Compare this to TypeScript, where you just write an object literal `{ kind: "click", x: 20, y: 80 }` and rely on structural typing. Rust is **nominal**: the value’s type is `WebEvent`, full stop. ### Reading the data back: `match` [Section titled “Reading the data back: match”](#reading-the-data-back-match) You cannot read a variant’s payload directly (more on that in [Common Pitfalls](#common-pitfalls)). You **destructure** it, almost always with `match`: ```rust 1 match event { 2 WebEvent::KeyPress(c) => format!("pressed '{c}'"), // bind the char as `c` 3 WebEvent::Click { x, y } => format!("at ({x}, {y})"), // bind both fields 4 // ... 5 } ``` This is the same instinct as `switch (event.kind)` followed by `event.key`, but fused into one operation: matching the variant **and** pulling out its fields happen together, and the binding (`c`, `x`, `y`) only exists inside that arm where the type is known. Pattern matching gets its own page in [Pattern Matching](/06-data-structures/04-pattern-matching/). ### Memory: a tag plus the largest payload [Section titled “Memory: a tag plus the largest payload”](#memory-a-tag-plus-the-largest-payload) A TypeScript discriminated-union value is a heap-allocated object with a `kind` property string plus its other fields. A Rust enum value is laid out inline as a small integer **discriminant** (the tag) followed by enough space for the *largest* variant’s payload: no heap allocation, no string tag. The whole `WebEvent` lives on the stack. This is why Rust enums are cheap enough to use everywhere, including in hot loops. > **Note:** The compiler is clever about layout. For example `Option<&T>` (an enum!) needs no extra tag byte at all, because a reference can never be null — `None` reuses the all-zero bit pattern. This “niche optimization” means many Rust enums are as compact as the raw data they wrap. ### `Option` and `Result` are just enums [Section titled “Option and Result are just enums”](#option-and-result-are-just-enums) Two of the most important types in Rust are nothing more than enums defined in the standard library: ```rust 1 let found: Option<i32> = Some(7); 2 let missing: Option<i32> = None; 3 println!("{found:?} {missing:?}"); // Some(7) None ``` `Option<T>` is `enum Option<T> { Some(T), None }` and `Result<T, E>` is `enum Result<T, E> { Ok(T), Err(E) }`. Everything you learn here applies to them. `Option<T>` is Rust’s replacement for `null`/`undefined` and gets its own page: [The Option Type](/06-data-structures/03-option-enum/). `Result` powers error handling in [Section 08](/08-error-handling/). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript discriminated union | Rust enum | | ---------------------- | --------------------------------------------- | --------------------------------------------------------------- | | Definition | Hand-assembled: `A \| B \| C` of object types | One `enum` declaration | | Discriminant | A literal field you invent (`kind: "click"`) | The variant name, built into the language | | Payload | Each member is an object with properties | Per-variant: unit, tuple, or named fields | | Runtime representation | Heap object with a string tag + fields | Inline tag (small int) + largest payload, often stack-allocated | | Narrowing | `switch`/`if` on the tag, then read fields | `match` / `if let` destructures variant + fields together | | Exhaustiveness | Opt-in (`never` trick); otherwise silent | **Mandatory**: compiler error if a variant is missed | | Adding a variant | Misses are silent until runtime | Compiler points at every `match` you must update | | Type identity | Structural (shape-compatible counts) | Nominal (the named type is the type) | | Generics | Erased at runtime | Monomorphized (real specialized code) | ### Exhaustiveness is the headline feature [Section titled “Exhaustiveness is the headline feature”](#exhaustiveness-is-the-headline-feature) In TypeScript, adding a new union member compiles fine and your existing `switch` statements silently fall through. In Rust, adding a variant turns every `match` that doesn’t handle it into a **compile error**, with the compiler naming the exact uncovered case. This turns “did I update every place?” from a manual audit into something the type checker guarantees. ### Enums can have methods [Section titled “Enums can have methods”](#enums-can-have-methods) Like structs, enums can have `impl` blocks. The `matches!` macro is handy for a quick boolean check: ```rust 1 #[derive(Debug, Clone)] 2 enum JobState { 3 Queued, 4 Running { progress: u8 }, 5 Succeeded { output: String }, 6 Failed { code: u32, message: String }, 7 } 8 9 impl JobState { 10 fn is_terminal(&self) -> bool { 11 matches!(self, JobState::Succeeded { .. } | JobState::Failed { .. }) 12 } 13 } ``` Methods on enums are covered alongside structs in [Methods and `impl` Blocks](/06-data-structures/05-impl-blocks/); here we just note that data and behavior live together. ### C-like enums with explicit discriminants [Section titled “C-like enums with explicit discriminants”](#c-like-enums-with-explicit-discriminants) When variants carry *no* data, an enum behaves like a classic C enum, and you can pin each tag to an integer and cast to it: ```rust 1 #[derive(Debug, Clone, Copy)] 2 enum HttpStatus { 3 Ok = 200, 4 NotFound = 404, 5 ServerError = 500, 6 } 7 8 fn main() { 9 let all = [HttpStatus::Ok, HttpStatus::NotFound, HttpStatus::ServerError]; 10 for s in all { 11 println!("{s:?} = {}", s as i32); 12 } 13 } ``` This prints: ```text 1 Ok = 200 2 NotFound = 404 3 ServerError = 500 ``` > **Note:** Casting an enum to an integer with `as` only works for these data-less, “field-less” enums. Once a variant carries a payload, there is no single integer to cast to. (And `as` only goes one way: there is no built-in `404 as HttpStatus`. Reverse conversion needs a `match` or the [`num_enum`](/23-ecosystem/) crate.) *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting a variant in `match` [Section titled “Pitfall 1: Forgetting a variant in match”](#pitfall-1-forgetting-a-variant-in-match) A TypeScript `switch` will happily skip a missing case. Rust refuses to compile: ```rust 1 enum Shape { 2 Circle(f64), 3 Rectangle(f64, f64), 4 Triangle(f64, f64), 5 } 6 7 fn area(s: &Shape) -> f64 { 8 match s { // does not compile (error[E0004]: non-exhaustive patterns) 9 Shape::Circle(r) => 3.14159 * r * r, 10 Shape::Rectangle(w, h) => w * h, 11 // Triangle is missing! 12 } 13 } ``` The real compiler error: ```text 1 error[E0004]: non-exhaustive patterns: `&Shape::Triangle(_, _)` not covered 2 --> src/main.rs:8:11 3 | 4 8 | match s { 5 | ^ pattern `&Shape::Triangle(_, _)` not covered 6 | 7 note: `Shape` defined here 8 --> src/main.rs:1:6 9 | 10 1 | enum Shape { 11 | ^^^^^ 12 ... 13 4 | Triangle(f64, f64), 14 | -------- not covered 15 = note: the matched value is of type `&Shape` 16 help: ensure that all possible cases are being handled by adding a match arm with a 17 wildcard pattern or an explicit pattern as shown ``` **Fix:** add the missing arm. Reach for a catch-all `_ => ...` only when you genuinely want a default; if you use `_` everywhere, you lose the very compiler nudge that makes enums safe when you add variants later. ### Pitfall 2: Trying to read a payload like a TypeScript property [Section titled “Pitfall 2: Trying to read a payload like a TypeScript property”](#pitfall-2-trying-to-read-a-payload-like-a-typescript-property) In TypeScript, after narrowing you read `event.key`. In Rust there is no field to read until you destructure; an enum is not a struct: ```rust 1 enum Msg { 2 Text(String), 3 Quit, 4 } 5 6 fn main() { 7 let m = Msg::Text(String::from("hi")); 8 println!("{}", m.0); // does not compile (error[E0609]: no field `0` on type `Msg`) 9 } ``` The real error: ```text 1 error[E0609]: no field `0` on type `Msg` 2 --> src/main.rs:8:22 3 | 4 8 | println!("{}", m.0); 5 | ^ unknown field ``` **Fix:** match or use `if let` to bind the inner value: ```rust 1 if let Msg::Text(s) = &m { 2 println!("{s}"); 3 } ``` ### Pitfall 3: Comparing enum values with `==` before deriving `PartialEq` [Section titled “Pitfall 3: Comparing enum values with == before deriving PartialEq”](#pitfall-3-comparing-enum-values-with--before-deriving-partialeq) In JavaScript `a === b` always works. In Rust, `==` is the `PartialEq` trait, and an enum doesn’t get it automatically: ```rust 1 enum Direction { 2 North, 3 South, 4 } 5 6 fn main() { 7 let d = Direction::North; 8 if d == Direction::North { // does not compile (error[E0369]) 9 println!("going north"); 10 } 11 } ``` The real error (note the actionable hint): ```text 1 error[E0369]: binary operation `==` cannot be applied to type `Direction` 2 --> src/main.rs:8:10 3 | 4 8 | if d == Direction::North { 5 | - ^^ ---------------- Direction 6 | | 7 | Direction 8 | 9 note: an implementation of `PartialEq` might be missing for `Direction` 10 --> src/main.rs:1:1 11 | 12 1 | enum Direction { 13 | ^^^^^^^^^^^^^^ must implement `PartialEq` 14 help: consider annotating `Direction` with `#[derive(PartialEq)]` ``` **Fix:** add `#[derive(PartialEq)]` (and usually `Debug`) above the enum. Deriving traits is covered for structs in [Structs](/06-data-structures/00-structs/) and in full in [Section 09](/09-generics-traits/). ### Pitfall 4: Expecting structural typing [Section titled “Pitfall 4: Expecting structural typing”](#pitfall-4-expecting-structural-typing) Two TypeScript unions with the same members are interchangeable. In Rust two enums with identical-looking variants are **different, incompatible types** — Rust is nominal. If function `f` wants a `WebEvent`, no other enum will do, even one defined with the same variants. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Reach for an enum whenever you’d write a TypeScript union of object types.** It is the idiomatic, type-safe way to model “one of N shapes.” * **Prefer named fields for variants with 2+ pieces of data.** `Click { x: i64, y: i64 }` documents itself; `Click(i64, i64)` makes the call site guess which number is which. * **Let `match` enforce exhaustiveness; avoid a blanket `_` arm** unless a default truly is correct. The exhaustiveness error is a feature, not an obstacle. * **Derive the traits you need** (`#[derive(Debug, Clone, PartialEq)]` is a common starting set). Add `Copy` only for small, data-light enums where copying is trivially cheap. * **Put behavior on the enum with `impl`.** A `JobState::is_terminal()` method keeps the logic next to the data, the way a class method would in TypeScript. * **Use `if let` (or `matches!`) when you care about exactly one variant**; use `match` when you must handle them all. * **Model invalid states out of existence.** If a “loading” request has no response and a “loaded” one always does, encode that in the variants so an impossible combination simply cannot be constructed: something a TypeScript object with optional fields can’t guarantee. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A job/task status is a textbook case for a data-carrying enum: each state carries different information, and several states are *terminal*. In TypeScript you’d model it as a discriminated union; in Rust the enum carries the right payload per state and a method answers questions about it. ```rust 1 #[derive(Debug, Clone)] 2 enum JobState { 3 Queued, 4 Running { progress: u8 }, 5 Succeeded { output: String }, 6 Failed { code: u32, message: String }, 7 } 8 9 impl JobState { 10 /// A job is "terminal" once it can no longer change. 11 fn is_terminal(&self) -> bool { 12 matches!(self, JobState::Succeeded { .. } | JobState::Failed { .. }) 13 } 14 15 /// A human-readable one-liner for logs or a UI. 16 fn summary(&self) -> String { 17 match self { 18 JobState::Queued => "waiting to start".to_string(), 19 JobState::Running { progress } => format!("running ({progress}%)"), 20 JobState::Succeeded { output } => format!("done: {output}"), 21 JobState::Failed { code, message } => format!("failed [{code}]: {message}"), 22 } 23 } 24 } 25 26 fn main() { 27 let states = [ 28 JobState::Queued, 29 JobState::Running { progress: 42 }, 30 JobState::Succeeded { output: "report.pdf".to_string() }, 31 JobState::Failed { code: 503, message: "upstream timeout".to_string() }, 32 ]; 33 34 for s in &states { 35 println!("{:<28} terminal={}", s.summary(), s.is_terminal()); 36 } 37 } ``` Output: ```text 1 waiting to start terminal=false 2 running (42%) terminal=false 3 done: report.pdf terminal=true 4 failed [503]: upstream timeout terminal=true ``` Notice what the type system buys you: a `Failed` value *always* has a `code` and a `message`, and a `Queued` value *cannot* carry a progress number. In the TypeScript equivalent you’d typically end up with optional fields (`progress?: number`) that are technically present in every member, and nothing stops you from constructing a `{ kind: "queued", progress: 99 }`. The Rust enum makes that nonsensical state **unrepresentable**. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [The Rust Programming Language — Defining an Enum](https://doc.rust-lang.org/book/ch06-01-defining-an-enum.html) * [The Rust Programming Language — The `match` Control Flow Construct](https://doc.rust-lang.org/book/ch06-02-match.html) * [Rust by Example — Enums](https://doc.rust-lang.org/rust-by-example/custom_types/enum.html) * [`std::option::Option`](https://doc.rust-lang.org/std/option/enum.Option.html) and [`std::result::Result`](https://doc.rust-lang.org/std/result/enum.Result.html) — the standard library’s own enums * Sibling topics: [Structs](/06-data-structures/00-structs/) · [Tuple Structs and Unit Structs](/06-data-structures/01-tuple-structs/) · [The Option Type](/06-data-structures/03-option-enum/) · [Pattern Matching](/06-data-structures/04-pattern-matching/) · [Methods and `impl` Blocks](/06-data-structures/05-impl-blocks/) * Background: [Section 02 — Basic Types](/02-basics/01-types/) · [Section 05 — Ownership](/05-ownership/) * What’s next: enums are the natural element type for [Section 07 — Collections](/07-collections/) (e.g. a `Vec<WebEvent>`). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A `Shape` enum with an `area` method [Section titled “Exercise 1: A Shape enum with an area method”](#exercise-1-a-shape-enum-with-an-area-method) **Difficulty:** Beginner **Objective:** Practice declaring struct-like variants and matching on them inside a method. **Instructions:** Define an enum `Shape` with three variants — `Circle { radius: f64 }`, `Rectangle { width: f64, height: f64 }`, and `Triangle { base: f64, height: f64 }`. Add an `impl Shape` with a method `area(&self) -> f64`. In `main`, put three shapes in an array and print each one’s area. Solution ```rust 1 #[derive(Debug)] 2 enum Shape { 3 Circle { radius: f64 }, 4 Rectangle { width: f64, height: f64 }, 5 Triangle { base: f64, height: f64 }, 6 } 7 8 impl Shape { 9 fn area(&self) -> f64 { 10 match self { 11 Shape::Circle { radius } => std::f64::consts::PI * radius * radius, 12 Shape::Rectangle { width, height } => width * height, 13 Shape::Triangle { base, height } => 0.5 * base * height, 14 } 15 } 16 } 17 18 fn main() { 19 let shapes = [ 20 Shape::Circle { radius: 2.0 }, 21 Shape::Rectangle { width: 3.0, height: 4.0 }, 22 Shape::Triangle { base: 6.0, height: 2.0 }, 23 ]; 24 for s in &shapes { 25 println!("{:?} -> area {:.2}", s, s.area()); 26 } 27 } ``` Output: ```text 1 Circle { radius: 2.0 } -> area 12.57 2 Rectangle { width: 3.0, height: 4.0 } -> area 12.00 3 Triangle { base: 6.0, height: 2.0 } -> area 6.00 ``` ### Exercise 2: A recursive `Json` enum [Section titled “Exercise 2: A recursive Json enum”](#exercise-2-a-recursive-json-enum) **Difficulty:** Intermediate **Objective:** Model a value that is “one of several shapes,” including ones that contain *more* of itself, the way a TypeScript `JSONValue` union does. **Instructions:** Define an enum `Json` with variants `Null`, `Bool(bool)`, `Number(f64)`, `Str(String)`, `Array(Vec<Json>)`, and `Object(HashMap<String, Json>)`. Add a method `type_name(&self) -> &'static str` returning `"null"`, `"boolean"`, etc. In `main`, build a small object and print the type name of the whole document and of one of its fields. > **Tip:** Variants like `Array` and `Object` hold a `Vec`/`HashMap` *of `Json`*, which is fine because those collections heap-allocate their contents. (A directly self-containing variant like `Node(Json)` would need a `Box`; see the hint in the next exercise.) Solution ```rust 1 use std::collections::HashMap; 2 3 #[derive(Debug)] 4 #[allow(dead_code)] // payloads are intentionally only matched with `_` in `type_name` 5 enum Json { 6 Null, 7 Bool(bool), 8 Number(f64), 9 Str(String), 10 Array(Vec<Json>), 11 Object(HashMap<String, Json>), 12 } 13 14 impl Json { 15 fn type_name(&self) -> &'static str { 16 match self { 17 Json::Null => "null", 18 Json::Bool(_) => "boolean", 19 Json::Number(_) => "number", 20 Json::Str(_) => "string", 21 Json::Array(_) => "array", 22 Json::Object(_) => "object", 23 } 24 } 25 } 26 27 fn main() { 28 let mut obj = HashMap::new(); 29 obj.insert("name".to_string(), Json::Str("Ada".to_string())); 30 obj.insert("age".to_string(), Json::Number(36.0)); 31 obj.insert("admin".to_string(), Json::Bool(true)); 32 obj.insert( 33 "tags".to_string(), 34 Json::Array(vec![Json::Str("a".into()), Json::Null]), 35 ); 36 37 let doc = Json::Object(obj); 38 println!("top-level type: {}", doc.type_name()); 39 40 if let Json::Object(map) = &doc { 41 if let Some(name) = map.get("name") { 42 println!("name field is a {}", name.type_name()); 43 } 44 } 45 } ``` Output: ```text 1 top-level type: object 2 name field is a string ``` > **Note:** Because `type_name` only inspects each variant’s *discriminant* (matching the payloads with `_`), the compiler considers the inner data unread and would emit `dead_code` warnings. The `#[allow(dead_code)]` above silences them; in a real codebase you’d read those payloads (e.g. to serialize the value) and the warnings would disappear on their own. ### Exercise 3: A `Light` state machine [Section titled “Exercise 3: A Light state machine”](#exercise-3-a-light-state-machine) **Difficulty:** Advanced **Objective:** Combine a data-less enum, derived traits, `match`-based state transitions, and the `matches!` macro. **Instructions:** Define `enum Light { Red, Yellow, Green }` deriving `Debug, Clone, Copy, PartialEq`. Add a method `next(self) -> Light` that advances the cycle Red → Green → Yellow → Red, and a method `may_go(self) -> bool` that returns `true` only for `Green` (use `matches!`). In `main`, start at `Red` and print four steps of the cycle with whether you may go. > **Tip:** A recursive variant that contains the enum *directly* — such as a `Node(Tree, Tree)` — would have infinite size, so it must wrap the inner value in a `Box` (a heap pointer): `Node(Box<Tree>, Box<Tree>)`. You won’t need that here, but it’s the standard fix and you’ll meet `Box` in [Section 10](/10-smart-pointers/). Solution ```rust 1 #[derive(Debug, Clone, Copy, PartialEq)] 2 enum Light { 3 Red, 4 Yellow, 5 Green, 6 } 7 8 impl Light { 9 fn next(self) -> Light { 10 match self { 11 Light::Red => Light::Green, 12 Light::Green => Light::Yellow, 13 Light::Yellow => Light::Red, 14 } 15 } 16 17 fn may_go(self) -> bool { 18 matches!(self, Light::Green) 19 } 20 } 21 22 fn main() { 23 let mut light = Light::Red; 24 for _ in 0..4 { 25 println!("{light:?} (go? {})", light.may_go()); 26 light = light.next(); 27 } 28 } ``` Output: ```text 1 Red (go? false) 2 Green (go? true) 3 Yellow (go? false) 4 Red (go? false) ``` # The Option Type: Rust's Answer to null and undefined > Rust has no null or undefined; Option<T> makes absence an explicit Some/None type, so the forgotten check that crashes JavaScript becomes a compile error. Rust has no `null` and no `undefined`. Instead, the possibility of “no value” is encoded in the type system with `Option<T>` — an enum with exactly two variants, `Some(value)` and `None`. The compiler then forces you to handle the “missing” case before you can touch the value, which eliminates an entire category of runtime crashes that plague TypeScript and JavaScript. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In TypeScript, any value can secretly be `null` or `undefined`, and forgetting to check leads to the infamous `TypeError: Cannot read properties of undefined`. Rust replaces those two bottom values with a single, explicit type, **`Option<T>`**: a value is either `Some(T)` (present) or `None` (absent). Because “absent” is a distinct variant rather than a magic value any reference can hold, you cannot accidentally use a missing value. The code simply will not compile until you account for `None`. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // TypeScript - absence is expressed with null/undefined and optional fields 2 interface User { 3 id: number; 4 name: string; 5 email?: string; // optional => string | undefined 6 } 7 8 const users: User[] = [ 9 { id: 1, name: "Ada", email: "ada@corp.dev" }, 10 { id: 2, name: "Grace" }, // no email 11 ]; 12 13 function findUser(id: number): User | undefined { 14 return users.find((u) => u.id === id); 15 } 16 17 // The optional chaining + nullish coalescing dance: 18 function contactLine(id: number): string { 19 const user = findUser(id); 20 const email = user?.email ?? "no-email-on-file"; 21 return `${user?.name ?? "unknown"} <${email}>`; 22 } 23 24 console.log(contactLine(1)); // Ada <ada@corp.dev> 25 console.log(contactLine(2)); // Grace <no-email-on-file> 26 console.log(contactLine(99)); // unknown <no-email-on-file> 27 28 // The classic mistake: forgetting the check entirely 29 const u = findUser(99); 30 // console.log(u.name); // compiles only if strictNullChecks is off; crashes at runtime: 31 // TypeError: Cannot read properties of undefined (reading 'name') ``` **Key points:** * `find` returns `User | undefined`; `?.` and `??` are the tools for handling it. * With `strictNullChecks` **on**, TypeScript flags `u.name`. With it **off** (still common in legacy codebases), the bug ships and crashes at runtime. * `null` and `undefined` are two separate bottom values, and the distinction between them is a frequent source of subtle bugs. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 // Rust - absence is one explicit type: Option<T> 2 #[derive(Debug)] 3 struct User { 4 id: u64, 5 name: String, 6 email: Option<String>, // explicitly "maybe a String" 7 } 8 9 fn find_user<'a>(users: &'a [User], id: u64) -> Option<&'a User> { 10 users.iter().find(|u| u.id == id) // `find` returns Option, like Array.find 11 } 12 13 fn contact_line(users: &[User], id: u64) -> String { 14 find_user(users, id) 15 .map(|u| { 16 // as_deref turns Option<String> into Option<&str>; unwrap_or supplies a fallback 17 let email = u.email.as_deref().unwrap_or("no-email-on-file"); 18 format!("{} <{}>", u.name, email) 19 }) 20 .unwrap_or_else(|| "unknown user".to_string()) 21 } 22 23 fn main() { 24 let users = vec![ 25 User { id: 1, name: "Ada".to_string(), email: Some("ada@corp.dev".to_string()) }, 26 User { id: 2, name: "Grace".to_string(), email: None }, 27 ]; 28 29 println!("{}", contact_line(&users, 1)); // Ada <ada@corp.dev> 30 println!("{}", contact_line(&users, 2)); // Grace <no-email-on-file> 31 println!("{}", contact_line(&users, 99)); // unknown user 32 33 // The equivalent of "forgetting the check" does not compile: 34 let u = find_user(&users, 99); 35 // println!("{}", u.name); // does not compile (error[E0609]: no field `name` on Option<&User>) 36 println!("{u:?}"); // None 37 } ``` **Verified output:** ```text 1 Ada <ada@corp.dev> 2 Grace <no-email-on-file> 3 unknown user 4 None ``` **Key points:** * One type, `Option<T>`, replaces both `null` and `undefined`. * You cannot reach the inner `User` without first dealing with the `None` case. The “forgotten check” is a **compile error**, not a runtime crash. * `map` / `unwrap_or` / `as_deref` are the idiomatic counterparts to `?.` and `??`. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `Option<T>` is just an enum [Section titled “Option\<T> is just an enum”](#optiont-is-just-an-enum) There is nothing magical about `Option`. It is defined in the standard library, roughly, as: ```rust 1 // Conceptual: this is essentially how the standard library defines Option. 2 enum MyOption<T> { 3 Some(T), 4 None, 5 } 6 7 fn main() { 8 let a: MyOption<i32> = MyOption::Some(3); 9 let b: MyOption<i32> = MyOption::None; 10 11 let label = match a { 12 MyOption::Some(n) => format!("value {n}"), 13 MyOption::None => "nothing".to_string(), 14 }; 15 let label2 = match b { 16 MyOption::Some(n) => format!("value {n}"), 17 MyOption::None => "nothing".to_string(), 18 }; 19 println!("{label} / {label2}"); // value 3 / nothing 20 } ``` `Some` and `None` are **variants** of the enum, parameterized over a generic type `T`. (Enums and their data-carrying variants are covered in [Enums and Data-Carrying Variants](/06-data-structures/02-enums/); generics get full treatment in [Section 09](/09-generics-traits/).) Because `Option` is so fundamental, `Some` and `None` are in Rust’s **prelude**: you never need to write `Option::Some` or import anything. > **Note:** Unlike a TypeScript union `T | undefined`, the `Some` wrapper is a real, named variant. To get at the `T` inside, you must explicitly unwrap it; there is no implicit “the value is just there.” This is what makes the absence impossible to ignore. ### Creating and inspecting Options [Section titled “Creating and inspecting Options”](#creating-and-inspecting-options) ```rust 1 fn main() { 2 let present: Option<i32> = Some(42); 3 let absent: Option<i32> = None; 4 5 println!("{present:?}"); // Some(42) 6 println!("{absent:?}"); // None 7 8 // Quick boolean checks (rarely the best tool, but they exist) 9 println!("{} {}", present.is_some(), present.is_none()); // true false 10 println!("{} {}", absent.is_some(), absent.is_none()); // false true 11 } ``` When you write a bare `None`, Rust sometimes cannot infer `T`, so you annotate either the binding (`let absent: Option<i32> = None;`) or the value (`None::<i32>`). ### Getting the value out: pattern matching [Section titled “Getting the value out: pattern matching”](#getting-the-value-out-pattern-matching) The most fundamental way to handle an `Option` is `match`, which forces you to cover both variants: ```rust 1 fn find_user(name: &str) -> Option<&'static str> { 2 match name { 3 "alice" => Some("Alice Smith"), 4 "bob" => Some("Bob Jones"), 5 _ => None, 6 } 7 } 8 9 fn main() { 10 // `match` is exhaustive: the compiler rejects it if you forget `None`. 11 match find_user("alice") { 12 Some(full_name) => println!("found {full_name}"), 13 None => println!("no user"), 14 } 15 16 // `if let` when you only care about the Some case 17 if let Some(full_name) = find_user("bob") { 18 println!("if-let found {full_name}"); 19 } 20 21 // `let ... else` to bind-or-bail (stabilized in Rust 1.65) 22 let Some(first) = find_user("alice") else { 23 println!("no user — returning early"); 24 return; 25 }; 26 println!("let-else got {first}"); 27 } ``` `match`, `if let`, and `let ... else` are all covered in depth in [Pattern Matching](/06-data-structures/04-pattern-matching/). The key idea here: extracting the inner value is a deliberate act, and the compiler checks that you handled `None`. ### Combinators: the idiomatic alternative to unwrapping [Section titled “Combinators: the idiomatic alternative to unwrapping”](#combinators-the-idiomatic-alternative-to-unwrapping) Most real code does not `match` on every `Option`. Instead it uses **combinator methods** — small functions on `Option` that transform or unwrap it. These are the direct counterparts to TypeScript’s `?.` and `??`. ```rust 1 fn main() { 2 // map: transform the inner value if present (like x?.f()) 3 let len: Option<usize> = Some("hello").map(|s| s.len()); 4 println!("{len:?}"); // Some(5) 5 let none_len: Option<usize> = None::<&str>.map(|s| s.len()); 6 println!("{none_len:?}"); // None 7 8 // and_then: chain operations that THEMSELVES return Option (a flatMap) 9 let parsed: Option<i32> = Some("42").and_then(|s| s.parse::<i32>().ok()); 10 println!("{parsed:?}"); // Some(42) 11 let bad: Option<i32> = Some("abc").and_then(|s| s.parse::<i32>().ok()); 12 println!("{bad:?}"); // None 13 14 // unwrap_or: supply a fallback value (like ?? ) 15 let port: u16 = None.unwrap_or(8080); 16 println!("{port}"); // 8080 17 18 // unwrap_or_else: compute the fallback lazily (only runs if None) 19 let value = None.unwrap_or_else(|| expensive_default()); 20 println!("{value}"); // 99 21 22 // unwrap_or_default: use the type's Default::default() 23 let count: i32 = None.unwrap_or_default(); 24 println!("{count}"); // 0 25 26 // filter: keep Some only if a predicate holds 27 println!("{:?} {:?}", Some(4).filter(|n| n % 2 == 0), Some(3).filter(|n| n % 2 == 0)); 28 // Some(4) None 29 30 // or: fall back to another Option 31 println!("{:?}", None.or(Some("fallback"))); // Some("fallback") 32 } 33 34 fn expensive_default() -> i32 { 35 99 36 } ``` **Verified output:** ```text 1 Some(5) 2 None 3 Some(42) 4 None 5 8080 6 99 7 0 8 Some(4) None 9 Some("fallback") ``` The key pair to internalize: | You want to… | Method | TS analogue | | ------------------------------------------------------- | ---------------- | --------------------------------- | | Transform the value but stay inside `Option` | `map` | `x?.f()` | | Transform with a function that returns another `Option` | `and_then` | `x?.f()` where `f` may be nullish | | Provide a fallback value and leave `Option` | `unwrap_or` | `x ?? fallback` | | Provide a fallback computed lazily | `unwrap_or_else` | `x ?? expensiveFallback()` | > **Tip:** Reach for `unwrap_or_else` over `unwrap_or` whenever the default is expensive to build (e.g. allocates a `String` or hits the network). `unwrap_or` evaluates its argument eagerly, even when the value is `Some`. ### Chaining: a realistic pipeline [Section titled “Chaining: a realistic pipeline”](#chaining-a-realistic-pipeline) Combinators shine when chained, replacing a nest of TypeScript `?.`/`??`: ```rust 1 fn main() { 2 // Read a "port" setting that may be missing, whitespace-padded, or unparseable. 3 let cfg: Option<&str> = Some(" 9090 "); 4 let port: u16 = cfg 5 .map(|s| s.trim()) // Option<&str> with trimmed value 6 .and_then(|s| s.parse::<u16>().ok()) // Option<u16> (parse may fail) 7 .unwrap_or(8080); // final value with a default 8 println!("port: {port}"); // 9090 9 } ``` `.ok()` converts a `Result<T, E>` into an `Option<T>` (discarding the error). The reverse — `Option` to `Result` — is `.ok_or(err)`, which is how you bridge into the `?`-and-`Result` world covered in [Section 08](/08-error-handling/). ### The `?` operator with `Option` [Section titled “The ? operator with Option”](#the--operator-with-option) The `?` operator is short-circuit unwrapping: **if the value is `Some`, it pulls out the inner value; if it is `None`, it immediately returns `None` from the enclosing function.** This lets you write a chain of fallible lookups linearly, with no nesting: ```rust 1 #[derive(Debug)] 2 struct Config { 3 database: Database, 4 } 5 #[derive(Debug)] 6 struct Database { 7 url: Option<String>, 8 } 9 10 // `?` on an Option requires the function to ALSO return Option (or Result). 11 fn first_db_host(cfg: &Config) -> Option<String> { 12 let url = cfg.database.url.as_ref()?; // returns None early if url is None 13 let host = url.split('/').nth(2)?; // returns None if there's no 3rd segment 14 Some(host.to_string()) 15 } 16 17 fn main() { 18 let with_url = Config { 19 database: Database { url: Some("postgres://db.example.com/app".to_string()) }, 20 }; 21 let without_url = Config { 22 database: Database { url: None }, 23 }; 24 25 println!("{:?}", first_db_host(&with_url)); // Some("db.example.com") 26 println!("{:?}", first_db_host(&without_url)); // None 27 28 // ok_or converts Option -> Result, bridging into the ? + Result world 29 let ok: Result<i32, &str> = Some(5).ok_or("missing"); 30 let err: Result<i32, &str> = None.ok_or("missing"); 31 println!("{ok:?} / {err:?}"); // Ok(5) / Err("missing") 32 } ``` **Verified output:** ```text 1 Some("db.example.com") 2 None 3 Ok(5) / Err("missing") ``` This is the closest Rust gets to TypeScript’s optional chaining `a?.b?.c`, but it reaches further: beyond member access, `?` works on **any** expression that produces an `Option`, including function calls, parsing, and collection lookups. > **Warning:** `?` propagates the absence to the **caller**. The function that uses `?` on an `Option` must itself return an `Option` (or a `Result`, if you `?` a `Result`). You cannot use `?` in a function that returns a plain `String` or `i32`. The exact compiler error appears in [Common Pitfalls](#common-pitfalls). ### Borrowing the inner value: `as_ref` and `as_deref` [Section titled “Borrowing the inner value: as\_ref and as\_deref”](#borrowing-the-inner-value-as_ref-and-as_deref) A subtle but important point unique to Rust: calling a method like `unwrap()` on an `Option<String>` **moves** the `String` out (ownership rules from [Section 05](/05-ownership/)). Often you only want to *borrow* it. `as_ref` converts `&Option<T>` ergonomically into `Option<&T>`, and `as_deref` goes one step further to `Option<&str>` (or `Option<&[T]>`): ```rust 1 fn main() { 2 let owned: Option<String> = Some("hi".to_string()); 3 4 let borrowed: Option<&String> = owned.as_ref(); // does NOT move `owned` 5 println!("{:?}", borrowed); // Some("hi") 6 println!("{:?}", owned); // still usable: Some("hi") 7 8 let s: Option<String> = Some("deref".to_string()); 9 let d: Option<&str> = s.as_deref(); // Option<String> -> Option<&str> 10 println!("{:?}", d); // Some("deref") 11 } ``` `as_deref().unwrap_or("default")` is the idiomatic way to read an optional `String` field as a `&str` with a fallback, which is exactly what the opening example does. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript | Rust | | --------------------------------------- | --------------------------------------------------- | --------------------------------------------------- | | Absence value(s) | `null` **and** `undefined` (two bottoms) | One type: `Option<T>` with `None` | | Can any reference be absent? | Yes; every object can be `null`/`undefined` | No; only `Option<T>` can be `None` | | Using the inner value without narrowing | Runtime `TypeError` (or compile error in strict TS) | Compile error; extract via match/combinator first | | Optional chaining | `a?.b?.c` | `a.and_then(...)` / `?` operator | | Nullish coalescing | `x ?? fallback` | `x.unwrap_or(fallback)` / `unwrap_or_else` | | Default for missing | `x ?? defaultValue` | `x.unwrap_or_default()` | | Runtime cost | A value compared against `null`/`undefined` | Zero-cost: niche-optimized (often same size as `T`) | ### Why Rust does it this way [Section titled “Why Rust does it this way”](#why-rust-does-it-this-way) The deep reason is the **billion-dollar mistake**. Tony Hoare, who invented null references in 1965, later called them his billion-dollar mistake because of the countless bugs they caused. Rust’s design response is to make absence a value you *opt into* per type, rather than a hole in every reference. A `String` in Rust is *always* a valid string; if it might be missing, its type is `Option<String>` and the compiler tracks that fact everywhere. A pleasant bonus: `Option<T>` is usually **zero-overhead**. For types with a “niche” (an unused bit pattern), the compiler represents `None` using that bit pattern, so `Option<&T>`, `Option<Box<T>>`, and `Option<NonZero<u32>>` are the *same size* as the value they wrap. There is no boxing and no extra tag word in those cases. > **Note:** This contrasts sharply with TypeScript, where `string | undefined` is a compile-time-only construct. TypeScript’s union types are erased at runtime (the JS engine just sees a value that happens to be `undefined`), whereas Rust monomorphizes `Option<T>` into a concrete in-memory layout for each `T`. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Calling a method on the `Option` instead of the inner value [Section titled “Pitfall 1: Calling a method on the Option instead of the inner value”](#pitfall-1-calling-a-method-on-the-option-instead-of-the-inner-value) A TypeScript habit is to call methods directly, since `?.` short-circuits for you. In Rust, `Option<&str>` is **not** a `&str`, so its methods are not available: ```rust 1 fn main() { 2 let name: Option<&str> = Some("Bob"); 3 let shout = name.to_uppercase(); // does not compile 4 println!("{shout}"); 5 } ``` The real compiler error: ```text 1 error[E0599]: no method named `to_uppercase` found for enum `Option` in the current scope 2 --> src/main.rs:3:22 3 | 4 3 | let shout = name.to_uppercase(); // does not compile 5 | ^^^^^^^^^^^^ method not found in `Option<&str>` 6 | 7 note: the method `to_uppercase` exists on the type `&str` 8 help: consider using `Option::expect` to unwrap the `&str` value, panicking if the value is an `Option::None` ``` **Fix:** transform *inside* the `Option` with `map`: `name.map(|s| s.to_uppercase())`. ### Pitfall 2: Reaching `unwrap()` for “I know it’s there” [Section titled “Pitfall 2: Reaching unwrap() for “I know it’s there””](#pitfall-2-reaching-unwrap-for-i-know-its-there) `unwrap()` and `expect()` extract the value but **panic** (crash the thread) on `None`. They are the moral equivalent of pretending a value is non-null: ```rust 1 fn main() { 2 let maybe: Option<i32> = None; 3 let value = maybe.unwrap(); // panics at runtime 4 println!("{value}"); 5 } ``` Running it produces a real panic, not a compile error: ```text 1 thread 'main' panicked at src/main.rs:3:23: 2 called `Option::unwrap()` on a `None` value 3 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` **Fix:** use `unwrap_or`, `unwrap_or_else`, `match`, `if let`, or `?` to handle `None` explicitly. Reserve `unwrap()` for cases that are *provably* impossible, and prefer `expect("reason")` so the panic message documents your assumption. ### Pitfall 3: Using `?` in a function that doesn’t return `Option`/`Result` [Section titled “Pitfall 3: Using ? in a function that doesn’t return Option/Result”](#pitfall-3-using--in-a-function-that-doesnt-return-optionresult) ```rust 1 fn third_segment(url: &str) -> String { 2 let seg = url.split('/').nth(2)?; // does not compile 3 seg.to_string() 4 } 5 6 fn main() { 7 println!("{}", third_segment("a/b/c")); 8 } ``` The real compiler error spells out the requirement exactly: ```text 1 error[E0277]: the `?` operator can only be used in a function that returns `Result` or `Option` (or another type that implements `FromResidual`) 2 --> src/main.rs:2:36 3 | 4 1 | fn third_segment(url: &str) -> String { 5 | ------------------------------------- this function should return `Result` or `Option` to accept `?` 6 2 | let seg = url.split('/').nth(2)?; // does not compile 7 | ^ cannot use the `?` operator in a function that returns `String` ``` **Fix:** change the return type to `Option<String>` (and the caller deals with the `None`), or handle the `None` locally with `unwrap_or`. ### Pitfall 4: Assuming `None == null` for interop [Section titled “Pitfall 4: Assuming None == null for interop”](#pitfall-4-assuming-none--null-for-interop) When serializing to JSON (see [Section 15](/15-serialization/)), `None` typically maps to `null` or an *omitted* field, while `Some(x)` maps to `x`. There is no JavaScript-style distinction between `null` and `undefined` on the Rust side; that nuance has to be configured at the serialization layer (e.g. with `serde`’s `skip_serializing_if`). *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Prefer combinators to `match` for simple transforms.** `opt.map(...).unwrap_or(...)` reads more clearly than a three-line `match` when you are just transforming-or-defaulting. * **Use `?` to flatten nested optional lookups.** A chain of `let x = a()?; let y = b(x)?;` is far clearer than nested `match`/`if let`. * **Avoid `unwrap()`/`expect()` in library and production code paths.** They are fine in tests, prototypes, and genuinely-unreachable cases, and when you do use `expect`, write a message that explains *why* it cannot be `None`. * **Borrow with `as_ref`/`as_deref` instead of moving.** This keeps the original `Option` usable and avoids unnecessary clones. * **Reach for `unwrap_or_default()`** when the natural fallback is the type’s zero/empty value (`0`, `""`, `vec![]`). * **Convert at the boundary.** Use `.ok_or(err)` to turn an `Option` into a `Result` the moment “missing” should become a reportable error, then let `?` carry it upward. > **Tip:** Clippy will nudge you toward idiomatic choices. For example, it suggests `map_or` over `map(...).unwrap_or(...)` in some cases, and flags `unwrap()` patterns in lints you can opt into. Run `cargo clippy` regularly. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small in-memory user directory backed by a `HashMap` (collections are covered in [Section 07](/07-collections/)). It shows `?` chaining through genuinely-optional fields, plus `map` + `as_deref` + `unwrap_or` fallbacks: the kind of code you write constantly in a service layer. ```rust 1 use std::collections::HashMap; 2 3 /// A user profile where several fields are genuinely optional. 4 #[derive(Debug, Clone)] 5 struct User { 6 id: u64, 7 name: String, 8 email: Option<String>, // not every account verified an email 9 manager_id: Option<u64>, // the CEO has no manager 10 } 11 12 struct Directory { 13 users: HashMap<u64, User>, 14 } 15 16 impl Directory { 17 fn get(&self, id: u64) -> Option<&User> { 18 self.users.get(&id) // HashMap::get already returns Option 19 } 20 21 /// The display name of a user's manager — but only if the user exists, 22 /// has a manager, and that manager also exists. Any failure -> None. 23 fn manager_name(&self, id: u64) -> Option<&str> { 24 let user = self.get(id)?; // user must exist 25 let manager_id = user.manager_id?; // user must have a manager 26 let manager = self.get(manager_id)?; // manager must exist 27 Some(&manager.name) 28 } 29 30 /// A printable contact line, with placeholders for missing pieces. 31 fn contact_line(&self, id: u64) -> String { 32 self.get(id) 33 .map(|u| { 34 let email = u.email.as_deref().unwrap_or("no-email-on-file"); 35 format!("#{} {} <{}>", u.id, u.name, email) 36 }) 37 .unwrap_or_else(|| "unknown user".to_string()) 38 } 39 } 40 41 fn main() { 42 let mut users = HashMap::new(); 43 users.insert(1, User { id: 1, name: "Ada".into(), email: Some("ada@corp.dev".into()), manager_id: None }); 44 users.insert(2, User { id: 2, name: "Grace".into(), email: None, manager_id: Some(1) }); 45 let dir = Directory { users }; 46 47 // The ? chain in manager_name short-circuits cleanly: 48 println!("{:?}", dir.manager_name(2)); // Some("Ada") 49 println!("{:?}", dir.manager_name(1)); // None (Ada has no manager) 50 println!("{:?}", dir.manager_name(99)); // None (no such user) 51 52 // map + as_deref + unwrap_or fallbacks: 53 println!("{}", dir.contact_line(1)); // #1 Ada <ada@corp.dev> 54 println!("{}", dir.contact_line(2)); // #2 Grace <no-email-on-file> 55 println!("{}", dir.contact_line(99)); // unknown user 56 } ``` **Verified output:** ```text 1 Some("Ada") 2 None 3 None 4 #1 Ada <ada@corp.dev> 5 #2 Grace <no-email-on-file> 6 unknown user ``` Notice how `manager_name` reads like a sequence of preconditions, each guarded by `?`. The TypeScript equivalent would be a tangle of `?.` and intermediate `if` checks, and a single missed check would crash at runtime instead of being caught by the compiler. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`std::option` module documentation](https://doc.rust-lang.org/std/option/): the full list of `Option` methods. * [`Option` enum API](https://doc.rust-lang.org/std/option/enum.Option.html): `map`, `and_then`, `unwrap_or`, `as_ref`, and dozens more. * [The Rust Book, ch. 6.1: Defining an Enum](https://doc.rust-lang.org/book/ch06-01-defining-an-enum.html): where `Option` is introduced. * [The `?` operator (Rust reference)](https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operator). **Cross-links within this guide:** * [Enums and Data-Carrying Variants](/06-data-structures/02-enums/) — `Option` is an enum; this covers data-carrying variants and discriminated-union comparisons in full. * [Pattern Matching](/06-data-structures/04-pattern-matching/) — `match`, `if let`, and `let ... else` for destructuring `Option` and other types. * [Structs](/06-data-structures/00-structs/) — modeling records with optional fields (`email: Option<String>`). * [Section 05: Ownership](/05-ownership/) — why `as_ref`/`as_deref` matter (moving vs. borrowing the inner value). * [Section 07: Collections](/07-collections/) — `HashMap::get` and many iterator methods return `Option`. * [Section 08: Error Handling](/08-error-handling/) — `Result`, `?` with errors, and converting `Option` ↔ `Result`. * [Section 02: Basics](/02-basics/) and [Section 00: Introduction](/00-introduction/) for foundational context. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Safe division [Section titled “Exercise 1: Safe division”](#exercise-1-safe-division) **Difficulty:** Beginner **Objective:** Model “this operation might not produce a value” with `Option<T>`. **Instructions:** 1. Write `safe_div(a: f64, b: f64) -> Option<f64>` that returns `None` when `b` is `0.0` and `Some(a / b)` otherwise. 2. In `main`, print the results of `safe_div(10.0, 2.0)` and `safe_div(1.0, 0.0)` with `{:?}`. 3. Use `unwrap_or` to print the result of `safe_div(7.0, 0.0)` with a fallback of `f64::INFINITY`. ```rust 1 fn safe_div(a: f64, b: f64) -> Option<f64> { 2 // TODO 3 } 4 5 fn main() { 6 // TODO: print the three cases 7 } ``` Solution ```rust 1 fn safe_div(a: f64, b: f64) -> Option<f64> { 2 if b == 0.0 { 3 None 4 } else { 5 Some(a / b) 6 } 7 } 8 9 fn main() { 10 println!("{:?}", safe_div(10.0, 2.0)); // Some(5.0) 11 println!("{:?}", safe_div(1.0, 0.0)); // None 12 13 let result = safe_div(7.0, 0.0).unwrap_or(f64::INFINITY); 14 println!("{result}"); // inf 15 } ``` **Verified output:** ```text 1 Some(5.0) 2 None 3 inf ``` Returning `Option` (rather than throwing or returning a sentinel like `NaN`) makes the “no result” case impossible for callers to ignore. *** ### Exercise 2: A combinator pipeline [Section titled “Exercise 2: A combinator pipeline”](#exercise-2-a-combinator-pipeline) **Difficulty:** Intermediate **Objective:** Replace a `?.`/`??` chain with `Option` combinators. **Instructions:** 1. Write `parse_timeout(raw: Option<&str>) -> u64` that reads a timeout setting. 2. The setting may be missing (`None`), surrounded by whitespace, empty, unparseable, or zero. 3. Trim it, reject empty strings, parse it as a `u64`, reject `0`, and fall back to `30` for any failure. 4. Use a chain of `map`, `filter`, `and_then`, and `unwrap_or` — no `match` or `if`. 5. Test with `Some(" 60 ")`, `Some("abc")`, `Some("0")`, `Some("")`, and `None`. Solution ```rust 1 fn parse_timeout(raw: Option<&str>) -> u64 { 2 raw.map(|s| s.trim()) // trim whitespace 3 .filter(|s| !s.is_empty()) // reject empty 4 .and_then(|s| s.parse::<u64>().ok()) // parse, discarding the error 5 .filter(|&n| n > 0) // reject zero 6 .unwrap_or(30) // fall back to the default 7 } 8 9 fn main() { 10 println!("{}", parse_timeout(Some(" 60 "))); // 60 11 println!("{}", parse_timeout(Some("abc"))); // 30 (parse fails) 12 println!("{}", parse_timeout(Some("0"))); // 30 (filtered out) 13 println!("{}", parse_timeout(Some(""))); // 30 (empty) 14 println!("{}", parse_timeout(None)); // 30 (missing) 15 } ``` **Verified output:** ```text 1 60 2 30 3 30 4 30 5 30 ``` Each combinator handles exactly one failure mode, and a `None` anywhere in the chain flows straight through to `unwrap_or(30)`. *** ### Exercise 3: `?` through nested optional data [Section titled “Exercise 3: ? through nested optional data”](#exercise-3--through-nested-optional-data) **Difficulty:** Advanced **Objective:** Use the `?` operator to traverse deeply-optional data without nesting. **Instructions:** 1. Define three structs: `Order { customer: Option<Customer> }`, `Customer { address: Option<Address> }`, and `Address { zip: Option<String> }`. 2. Write `shipping_zip(order: &Order) -> Option<&str>` that returns the zip code only if the customer, the address, and the zip are all present. 3. Use `?` together with `as_ref` / `as_deref` so you borrow rather than move. 4. Test with a fully-populated order, an order whose customer has no address, and an order with no customer. Solution ```rust 1 #[derive(Debug)] 2 struct Order { 3 customer: Option<Customer>, 4 } 5 #[derive(Debug)] 6 struct Customer { 7 address: Option<Address>, 8 } 9 #[derive(Debug)] 10 struct Address { 11 zip: Option<String>, 12 } 13 14 fn shipping_zip(order: &Order) -> Option<&str> { 15 let customer = order.customer.as_ref()?; // Option<&Customer> 16 let address = customer.address.as_ref()?; // Option<&Address> 17 let zip = address.zip.as_deref()?; // Option<&str> 18 Some(zip) 19 } 20 21 fn main() { 22 let full = Order { 23 customer: Some(Customer { 24 address: Some(Address { zip: Some("94107".to_string()) }), 25 }), 26 }; 27 let no_addr = Order { 28 customer: Some(Customer { address: None }), 29 }; 30 let no_cust = Order { customer: None }; 31 32 println!("{:?}", shipping_zip(&full)); // Some("94107") 33 println!("{:?}", shipping_zip(&no_addr)); // None 34 println!("{:?}", shipping_zip(&no_cust)); // None 35 } ``` **Verified output:** ```text 1 Some("94107") 2 None 3 None ``` This is the Rust counterpart to `order?.customer?.address?.zip` — but `?` works on owned and borrowed `Option`s alike and explicitly propagates `None` from the enclosing function. *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * Rust has no `null`/`undefined`; absence is modeled by the `Option<T>` enum (`Some(T)` or `None`). * Reading the inner `T` requires you to account for `None` with a match, combinator, propagation, fallback, or deliberate panic; discarding the whole `Option` merely warns by default. * `map` and `and_then` are the `?.` analogues; `unwrap_or`/`unwrap_or_else`/`unwrap_or_default` are the `??` analogues. * The `?` operator unwraps `Some` or returns `None` early — flattening nested optional lookups — and requires the enclosing function to return `Option` (or `Result`). * `unwrap()`/`expect()` panic on `None`; prefer explicit handling, and use `as_ref`/`as_deref` to borrow rather than move the inner value. **The mental model:** `Option<T>` is the type that says, out loud and in the signature, “this might not be here.” TypeScript hides that possibility in every reference and hopes you remember to check; Rust makes it a visible, compiler-enforced part of the type. # Pattern Matching > Rust's match fuses destructuring, switch, and type narrowing into one exhaustive expression, catching the missing case that TypeScript's switch lets slip. Pattern matching is the feature most TypeScript/JavaScript developers come to miss the moment they go back. Rust’s `match` is array/object destructuring, a `switch` statement, type narrowing, and an exhaustiveness checker all rolled into one expression, and the compiler refuses to let you forget a case. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **pattern** describes the *shape* of a value: a literal, a range, a tuple, a struct, an enum variant, or a combination of these. Rust lets you match a value against patterns in many places: most prominently the `match` expression, but also `let`, `if let`, `let ... else`, `while let`, and function parameters. The defining feature is **exhaustiveness**: a `match` must cover every possible value, so the compiler turns “I forgot the `null` case” from a 3 a.m. production incident into a build error. > **Note:** This file focuses on the *patterns* themselves and the *places they appear*: `match`, `let`, `if let`, `let else`, `while let`, and the pattern syntax for tuples, structs, enums, ranges, guards, and bindings. The data types you match on each have their own file: [structs](/06-data-structures/00-structs/), [enums](/06-data-structures/02-enums/), and [`Option<T>`](/06-data-structures/03-option-enum/). Method syntax lives in [impl blocks](/06-data-structures/05-impl-blocks/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) TypeScript has no real pattern matching. You reach for a combination of destructuring, `switch`, and manual `if`/`else` chains on a discriminant field, and nothing forces you to handle every case. ```typescript 1 // A discriminated union — the closest TS analogue to a Rust enum. 2 type Shape = 3 | { kind: "circle"; radius: number } 4 | { kind: "rectangle"; width: number; height: number } 5 | { kind: "triangle"; base: number; height: number }; 6 7 function area(shape: Shape): number { 8 switch (shape.kind) { 9 case "circle": 10 return Math.PI * shape.radius ** 2; 11 case "rectangle": 12 return shape.width * shape.height; 13 case "triangle": 14 return 0.5 * shape.base * shape.height; 15 // With this explicit `: number` return type, TS DOES flag a missing case 16 // here (error TS2366: function lacks ending return statement) — no `never` 17 // trick required. The `never`-assignment exhaustiveness trick is only needed 18 // for side-effect (void) switches, where TS will NOT catch a missing case. 19 } 20 } 21 22 // Destructuring is separate from "matching": 23 const point = { x: 3, y: 7 }; 24 const { x, y } = point; // object destructuring 25 const [first, , third] = [1, 2, 3]; // array destructuring, skip middle 26 27 // Narrowing a value still needs hand-written conditionals: 28 function classifyStatus(code: number): string { 29 if (code === 200) return "OK"; 30 if (code === 301 || code === 302) return "Redirect"; 31 if (code >= 400 && code <= 499) return "Client error"; 32 if (code >= 500 && code <= 599) return "Server error"; 33 return "Other"; 34 } ``` In TypeScript, destructuring (pulling values *out*) and matching (deciding *which* branch) are two unrelated tools. Exhaustiveness checking is *partial*: for a value-returning `switch` with a declared or inferred return type, TypeScript flags a missing case automatically: either at the function (`error TS2366`, the explicit-return-type case shown above) or at the call site (the inferred-`number | undefined` case, `error TS2322`). But it relies on return-type flow analysis, so a side-effect (`void`) `switch` will silently *miss* a case unless you add the `never`-assignment trick by hand. Rust, as we will see, enforces exhaustiveness structurally for *every* match, no return type or assert needed. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) In Rust, destructuring and matching are **the same mechanism**. A pattern simultaneously *tests* a value’s shape and *binds* its parts to names. And `match` is exhaustive by construction. ```rust 1 #[derive(Debug)] 2 enum Shape { 3 Circle { radius: f64 }, 4 Rectangle { width: f64, height: f64 }, 5 Triangle { base: f64, height: f64 }, 6 } 7 8 fn area(shape: &Shape) -> f64 { 9 // Every variant must be handled, or this will not compile. 10 match shape { 11 Shape::Circle { radius } => std::f64::consts::PI * radius * radius, 12 Shape::Rectangle { width, height } => width * height, 13 Shape::Triangle { base, height } => 0.5 * base * height, 14 } 15 } 16 17 fn main() { 18 // `let` itself takes a pattern — this is destructuring. 19 let (name, age) = ("Alice", 30); 20 println!("{name} is {age}"); 21 22 // Struct destructuring with a `let` pattern. 23 #[derive(Debug)] 24 struct Point { x: i32, y: i32 } 25 let point = Point { x: 3, y: 7 }; 26 let Point { x, y } = point; 27 println!("x={x}, y={y}"); 28 29 let shapes = [ 30 Shape::Circle { radius: 2.0 }, 31 Shape::Rectangle { width: 3.0, height: 4.0 }, 32 Shape::Triangle { base: 6.0, height: 2.0 }, 33 ]; 34 for s in &shapes { 35 println!("{s:?} -> area {:.2}", area(s)); 36 } 37 } ``` Output (real, from `cargo run`): ```text 1 Alice is 30 2 x=3, y=7 3 Circle { radius: 2.0 } -> area 12.57 4 Rectangle { width: 3.0, height: 4.0 } -> area 12.00 5 Triangle { base: 6.0, height: 2.0 } -> area 6.00 ``` > **Note:** The `f64` literals print as `2.0`, not `2`, because Rust’s `Debug` formatting for floats always shows the decimal point. This is unlike JavaScript, where `console.log(2.0)` prints `2`. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `match` is an expression, not a statement [Section titled “match is an expression, not a statement”](#match-is-an-expression-not-a-statement) A JavaScript `switch` is a statement: it runs side effects, and you `return` or `break` out. A Rust `match` is an **expression**: it evaluates to a value you can assign or return directly. Each arm is `pattern => expression`. ```rust 1 fn main() { 2 let score = 84; 3 let grade = match score { 4 90..=100 => 'A', 5 80..=89 => 'B', 6 70..=79 => 'C', 7 _ => 'F', 8 }; 9 println!("grade = {grade}"); // grade = B 10 } ``` Because `match` is an expression, there is no fall-through and no `break`. Exactly one arm runs, and its value becomes the value of the whole `match`. (Compare to `switch`, where a forgotten `break` causes accidental fall-through, a class of bug that simply cannot exist here.) ### Patterns test *and* bind at once [Section titled “Patterns test and bind at once”](#patterns-test-and-bind-at-once) Each arm’s left side is a **pattern**. When the pattern matches, any names inside it are bound to the corresponding pieces of the value. In `Shape::Rectangle { width, height }`, the arm matches only `Rectangle` values, and on a match it binds `width` and `height` to that rectangle’s fields. There is no separate “destructure” step. ### Literal, range, and or-patterns [Section titled “Literal, range, and or-patterns”](#literal-range-and-or-patterns) Patterns can be concrete values, inclusive ranges (`..=`), or alternatives joined with `|`: ```rust 1 fn describe_status(code: u16) -> &'static str { 2 match code { 3 200 => "OK", 4 301 | 302 | 307 | 308 => "Redirect", // or-pattern 5 400..=499 => "Client error", // inclusive range 6 500..=599 => "Server error", 7 _ => "Other", // wildcard catch-all 8 } 9 } 10 11 fn main() { 12 for code in [200u16, 302, 404, 503, 100] { 13 println!("{code} -> {}", describe_status(code)); 14 } 15 } ``` Output (real): ```text 1 200 -> OK 2 302 -> Redirect 3 404 -> Client error 4 503 -> Server error 5 100 -> Other ``` The `_` wildcard matches anything and binds nothing. It is the equivalent of a `default:` case, and it is how you satisfy exhaustiveness for the “everything else” bucket. ### Match guards: a pattern plus a condition [Section titled “Match guards: a pattern plus a condition”](#match-guards-a-pattern-plus-a-condition) A pattern can be followed by `if <condition>`, called a **match guard**. The arm matches only if the pattern fits *and* the guard is true. ```rust 1 #[derive(Debug)] 2 struct Point { x: i32, y: i32 } 3 4 fn classify(point: Point) -> &'static str { 5 match point { 6 Point { x: 0, y: 0 } => "origin", 7 Point { x: 0, y } if y > 0 => "north axis", 8 Point { x: 0, y: _ } => "south axis", 9 Point { x, y: 0 } if x != 0 => "horizontal axis", 10 Point { .. } => "somewhere else", 11 } 12 } ``` Here `Point { x: 0, y }` matches any point on the y-axis and binds the y-coordinate; the guard `if y > 0` then narrows it further. The `Point { .. }` pattern uses `..` to ignore all remaining fields. ### Binding with `@` [Section titled “Binding with @”](#binding-with-) Sometimes you want to *test* a value against a range and also *keep* the value. The `@` operator binds a name to a value while also pattern-matching it: ```rust 1 fn main() { 2 let id = 42; 3 match id { 4 n @ 1..=50 => println!("{n} is in the low range"), 5 n @ 51..=100 => println!("{n} is in the high range"), 6 n => println!("{n} is out of range"), 7 } 8 // 42 is in the low range 9 } ``` Without `@`, the range pattern `1..=50` would match but give you no name for the matched value; with `n @ 1..=50` you get both. ### Reference patterns: matching without moving [Section titled “Reference patterns: matching without moving”](#reference-patterns-matching-without-moving) This is the part that trips up TypeScript developers, because JavaScript has no concept of ownership. When you `match` a value by reference (`match &thing`), the bindings inside the pattern are also references, so the original value is not consumed: ```rust 1 fn main() { 2 let owned = String::from("config.toml"); 3 let maybe = Some(owned); 4 5 // Matching `&maybe` borrows; `path` is a `&String`, not a moved String. 6 match &maybe { 7 Some(path) => println!("path is {path}"), 8 None => println!("no path"), 9 } 10 11 // We can still use `maybe` afterwards because nothing was moved out. 12 println!("still own it: {maybe:?}"); 13 } ``` Output (real): ```text 1 path is config.toml 2 still own it: Some("config.toml") ``` Modern Rust applies **match ergonomics**: when you match a reference (`&maybe`) against a non-reference pattern (`Some(path)`), the compiler automatically makes the inner bindings references for you. You rarely need to write the old `ref` keyword anymore. (See [Ownership](/05-ownership/) for the underlying move/borrow rules.) ### Tuple, slice, and nested patterns [Section titled “Tuple, slice, and nested patterns”](#tuple-slice-and-nested-patterns) Patterns nest arbitrarily, mirroring the structure of the data. ```rust 1 fn main() { 2 // Tuple destructuring, including nested tuples. 3 let record = ("Bob", (98.5, 87.0), true); 4 let (name, (math, science), active) = record; 5 println!("{name}: math={math}, science={science}, active={active}"); 6 7 // `..` ignores the middle of a tuple. 8 let numbers = (1, 2, 3, 4, 5); 9 let (first, .., last) = numbers; 10 println!("first={first}, last={last}"); 11 12 // Slice patterns match on the *shape* of a slice. 13 let parts: &[&str] = &["GET", "/index.html", "HTTP/1.1"]; 14 match parts { 15 [method, path, version] => println!("{method} {path} ({version})"), 16 [method, path] => println!("{method} {path}"), 17 [] => println!("empty request line"), 18 _ => println!("unexpected request line"), 19 } 20 21 // Bind the head and capture the rest with `tail @ ..`. 22 let words = vec!["a", "b", "c", "d"]; 23 if let [head, tail @ ..] = words.as_slice() { 24 println!("head={head}, tail={tail:?}"); 25 } 26 } ``` Output (real): ```text 1 Bob: math=98.5, science=87, active=true 2 first=1, last=5 3 GET /index.html (HTTP/1.1) 4 head=a, tail=["b", "c", "d"] ``` Slice patterns (`[head, tail @ ..]`) are the closest Rust equivalent to JavaScript’s array destructuring with rest (`const [head, ...tail] = arr`), but they also let you match on *length*, something JavaScript destructuring cannot express. ### The other `let`-based pattern forms [Section titled “The other let-based pattern forms”](#the-other-let-based-pattern-forms) `match` is the heavyweight, but four lighter forms cover the common cases: ```rust 1 fn main() { 2 // 1. `if let` — match one pattern, ignore the rest. Like a `match` with 3 // one interesting arm. Equivalent in spirit to TS `if (x !== undefined)`. 4 let config: Option<u16> = Some(8080); 5 if let Some(port) = config { 6 println!("server on port {port}"); 7 } else { 8 println!("using default port"); 9 } 10 11 // 2. `let ... else` — bind on the happy path, or diverge (return/break/panic). 12 // Great for "early return on failure" without nesting. 13 let raw = "127"; 14 let Ok(n) = raw.parse::<i32>() else { 15 println!("not a number"); 16 return; 17 }; 18 println!("parsed {n}"); // n is in scope for the rest of the function 19 20 // 3. `while let` — loop as long as the pattern keeps matching. 21 let mut stack = vec![1, 2, 3]; 22 while let Some(top) = stack.pop() { 23 println!("popped {top}"); 24 } 25 } ``` Output (real): ```text 1 server on port 8080 2 parsed 127 3 popped 3 4 popped 2 5 popped 1 ``` The fourth form is the [`matches!`](https://doc.rust-lang.org/std/macro.matches.html) macro, which returns a `bool` for “does this value match this pattern?”, handy in conditions and `.filter()` closures: ```rust 1 #[allow(dead_code)] // `Click` is never constructed in this isolated snippet 2 #[derive(Debug)] 3 enum Event { Click { x: i64, y: i64 }, Close } 4 5 fn main() { 6 let e = Event::Close; 7 println!("is close? {}", matches!(e, Event::Close)); // is close? true 8 } ``` ### Exhaustiveness: the headline feature [Section titled “Exhaustiveness: the headline feature”](#exhaustiveness-the-headline-feature) A `match` must cover every possible value of the type. This is enforced **structurally**, at compile time, for *every* match — independent of whether the match returns a value or what that value’s type is. If you add a variant to an enum later, every `match` that does not handle it stops compiling, and the compiler hands you a to-do list of every place you need to update. TypeScript does catch missing cases in a value-returning `switch` (via return-type flow analysis, as shown earlier), but that safety net disappears for side-effect (`void`) switches unless you hand-write a `never`-assignment assert. Rust needs no such opt-in: exhaustiveness is part of what `match` *is*. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript | Rust | | ------------------------ | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | Branching construct | `switch` statement (with fall-through) | `match` expression (no fall-through) | | Returns a value | No (statement) | Yes (expression) | | Destructuring | Separate from branching | Same mechanism as branching | | Exhaustiveness | Automatic for a value-returning `switch` (return-type flow analysis); needs a `never` assert for `void` switches | Mandatory and structural for every `match` | | Match on ranges | Manual `if (x >= a && x <= b)` | `a..=b` pattern | | Match on multiple values | `case a: case b:` fall-through | `a \| b` or-pattern | | Conditions in a branch | `if` inside the case body | Match guard `if cond` on the arm | | Bind while testing | Not available | `name @ pattern` | | Slice/array length match | Not expressible by destructuring | `[a, b, c]` slice patterns | | Moves a matched value? | N/A (no ownership) | Depends: match by `&value` to borrow | ### Why exhaustiveness instead of a silent default? [Section titled “Why exhaustiveness instead of a silent default?”](#why-exhaustiveness-instead-of-a-silent-default) Rust’s reasoning: a missing case is almost always a bug, and a bug the compiler can see is a bug it should refuse to ship. The `_` wildcard is always available when “everything else” is genuinely intended, but you have to *write it on purpose*, making the choice explicit rather than accidental. TypeScript gets you partway there: a value-returning `switch` with a known return type is checked, but a `void` switch is not unless you opt in with the `never` trick. Rust closes that gap — exhaustiveness applies to every `match` regardless of context, so you opt *out* (with `_`) rather than opt *in* to safety. ### Patterns are refutable or irrefutable [Section titled “Patterns are refutable or irrefutable”](#patterns-are-refutable-or-irrefutable) A pattern that can fail to match is **refutable** (`Some(x)`); one that always matches is **irrefutable** (`(a, b)`, `Point { x, y }`). `let` and function parameters require *irrefutable* patterns: `let Some(x) = opt;` is a compile error because it might fail. That is exactly why `if let`, `let else`, and `while let` exist: they are the constructs that *allow* refutable patterns by giving a fallback path. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting a case (which is the point) [Section titled “Pitfall 1: Forgetting a case (which is the point)”](#pitfall-1-forgetting-a-case-which-is-the-point) ```rust 1 enum Direction { North, South, East, West } 2 3 fn label(d: Direction) -> &'static str { 4 // does not compile (error[E0004]: non-exhaustive patterns: `Direction::West` not covered) 5 match d { 6 Direction::North => "up", 7 Direction::South => "down", 8 Direction::East => "right", 9 // forgot West! 10 } 11 } ``` The real compiler error: ```text 1 error[E0004]: non-exhaustive patterns: `Direction::West` not covered 2 --> src/main.rs:4:11 3 | 4 4 | match d { 5 | ^ pattern `Direction::West` not covered 6 | 7 note: `Direction` defined here 8 --> src/main.rs:1:6 9 | 10 1 | enum Direction { North, South, East, West } 11 | ^^^^^^^^^ ---- not covered 12 = note: the matched value is of type `Direction` 13 help: ensure that all possible cases are being handled by adding a match arm with a wildcard pattern or an explicit pattern as shown 14 | 15 7 ~ Direction::East => "right", 16 8 ~ Direction::West => todo!(), 17 | ``` This is not a problem to “fix and forget” — it is the feature working. Add the missing arm. Reach for `_ => ...` only when you truly want a catch-all, and prefer naming variants explicitly so that *adding* a variant later forces you to revisit the match. ### Pitfall 2: A catch-all arm placed too early [Section titled “Pitfall 2: A catch-all arm placed too early”](#pitfall-2-a-catch-all-arm-placed-too-early) Arms are tried top to bottom, so a `_` (or any irrefutable pattern) before more specific arms makes those later arms dead code. ```rust 1 fn describe(n: i32) -> &'static str { 2 match n { 3 _ => "anything", 4 0 => "zero", // unreachable 5 } 6 } ``` The real compiler warning (this compiles, but warns): ```text 1 warning: unreachable pattern 2 --> src/main.rs:4:9 3 | 4 3 | _ => "anything", 5 | - matches any value 6 4 | 0 => "zero", 7 | ^ no value can reach this 8 | 9 = note: `#[warn(unreachable_patterns)]` on by default ``` Put specific patterns first and the wildcard last. ### Pitfall 3: Matching against a variable instead of comparing to it [Section titled “Pitfall 3: Matching against a variable instead of comparing to it”](#pitfall-3-matching-against-a-variable-instead-of-comparing-to-it) This is the trap that surprises every TypeScript developer. In a `switch`, `case expected:` compares against the *value* of `expected`. In a Rust `match`, a bare lowercase identifier is a **new binding** that matches anything — it does *not* compare against an existing variable. ```rust 1 fn main() { 2 let expected = 3; 3 let value = 7; 4 match value { 5 expected => println!("matched expected!"), // binds a NEW `expected`, always matches 6 _ => println!("did not match"), 7 } 8 } ``` The compiler warns loudly, and even explains the underlying rule: ```text 1 warning: unreachable pattern 2 --> src/main.rs:6:9 3 | 4 5 | expected => println!("matched expected!"), // BUG: binds, doesn't compare 5 | -------- matches any value 6 6 | _ => println!("did not match"), 7 | ^ no value can reach this 8 | 9 note: there is a binding of the same name; if you meant to pattern match against the value of that binding, that is a feature of constants that is not available for `let` bindings 10 --> src/main.rs:2:9 11 | 12 2 | let expected = 3; 13 | ^^^^^^^^ 14 = note: `#[warn(unreachable_patterns)]` on by default ``` **Fix** — use a match guard, or match against a `const` (which *does* compare, because `const` names in patterns are treated as values): ```rust 1 const EXPECTED: i32 = 3; 2 3 fn main() { 4 let expected = 3; 5 let value = 3; 6 7 // Option A: a guard compares against the variable. 8 match value { 9 v if v == expected => println!("guard matched"), 10 _ => println!("no match"), 11 } 12 13 // Option B: match against a const (UPPER_SNAKE_CASE) — this DOES compare. 14 match value { 15 EXPECTED => println!("const matched"), 16 _ => println!("no match"), 17 } 18 } ``` Output (real): ```text 1 guard matched 2 const matched ``` > **Warning:** This is why Rust’s naming convention matters in patterns. `lowercase` = a fresh binding (matches anything); `UPPER_SNAKE_CASE` (a `const`) = a value comparison. The compiler relies on this casing distinction. ### Pitfall 4: Using a refutable pattern in `let` [Section titled “Pitfall 4: Using a refutable pattern in let”](#pitfall-4-using-a-refutable-pattern-in-let) ```rust 1 fn main() { 2 let opt: Option<i32> = Some(5); 3 // does not compile (error[E0005]: refutable pattern in local binding) 4 let Some(x) = opt; 5 println!("{x}"); 6 } ``` A plain `let` requires a pattern that *always* matches. `Some(x)` might be `None`, so it is refutable. Use `if let`, `let ... else`, or a full `match` instead: ```rust 1 fn main() { 2 let opt: Option<i32> = Some(5); 3 let Some(x) = opt else { 4 println!("was None"); 5 return; 6 }; 7 println!("{x}"); 8 } ``` *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Prefer explicit variant arms over `_` for enums you own.** A wildcard silences the exhaustiveness check, so adding a variant later will *not* flag the match. Use `_` for open-ended primitive matches (status codes, characters) where listing everything is impossible. * **Order arms specific-to-general.** Put literals and tight ranges first, the wildcard last, to avoid unreachable-pattern warnings. * **Use `if let` / `let else` for single-pattern checks**, and reserve full `match` for genuine multi-way branching. `let else` in particular flattens “parse-or-bail” logic that would otherwise nest deeply. * **Match by reference (`match &value`) when you do not need ownership**, so the matched value remains usable afterward. Let match ergonomics infer the reference bindings rather than sprinkling `ref`. * **Reach for `matches!(value, Pattern)`** instead of a `match` that just returns `true`/`false`. * **Use match guards for conditions that patterns cannot express** (relationships between bindings, `x == some_var`), but keep them simple — a guard is not a place for heavy logic. * **Let the compiler be your refactoring tool.** When you add an enum variant, do *not* add a `_` arm to silence errors; let each broken `match` guide you to every place that needs updating. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small HTTP-style request router driven entirely by pattern matching. It exercises tuple matching, struct and enum destructuring, reference bindings, guards, and an exhaustive response mapping: the kind of dispatch logic you would otherwise write as a tangle of `if`/`else` in Express. ```rust 1 // A tiny HTTP-style request router driven entirely by pattern matching. 2 // Demonstrates: enum + struct destructuring, tuple matching, ref bindings, 3 // guards, and exhaustiveness. 4 5 #[derive(Debug)] 6 enum Method { 7 Get, 8 Post, 9 Delete, 10 } 11 12 #[derive(Debug)] 13 struct Request { 14 method: Method, 15 path: String, 16 body: Option<String>, // Some(body) for POST, None otherwise. 17 } 18 19 #[derive(Debug)] 20 enum Response { 21 Ok(String), 22 Created(String), 23 NotFound, 24 BadRequest(String), 25 } 26 27 fn route(req: &Request) -> Response { 28 // Match on a tuple of (&method, path-as-&str, &body). `.as_str()` lets us 29 // write string-literal patterns; matching by reference avoids moving `req`. 30 match (&req.method, req.path.as_str(), &req.body) { 31 (Method::Get, "/health", _) => Response::Ok("healthy".into()), 32 33 // Path parameter extracted by hand, validated with a guard. 34 (Method::Get, path, _) if path.starts_with("/users/") => { 35 match path.trim_start_matches("/users/").parse::<u32>() { 36 Ok(id) => Response::Ok(format!("user #{id}")), 37 Err(_) => Response::BadRequest("invalid user id".into()), 38 } 39 } 40 41 // Create requires a body; bind it with `Some(b)`. 42 (Method::Post, "/users", Some(b)) => Response::Created(format!("created: {b}")), 43 (Method::Post, "/users", None) => Response::BadRequest("missing body".into()), 44 45 (Method::Delete, path, _) if path.starts_with("/users/") => { 46 Response::Ok(format!("deleted {path}")) 47 } 48 49 // Catch-all: every other (method, path) combination. 50 _ => Response::NotFound, 51 } 52 } 53 54 fn status_line(res: &Response) -> String { 55 // Exhaustive: every Response variant is mapped to a status line. 56 match res { 57 Response::Ok(msg) => format!("200 OK: {msg}"), 58 Response::Created(msg) => format!("201 Created: {msg}"), 59 Response::NotFound => "404 Not Found".to_string(), 60 Response::BadRequest(why) => format!("400 Bad Request: {why}"), 61 } 62 } 63 64 fn main() { 65 let requests = [ 66 Request { method: Method::Get, path: "/health".into(), body: None }, 67 Request { method: Method::Get, path: "/users/42".into(), body: None }, 68 Request { method: Method::Get, path: "/users/abc".into(), body: None }, 69 Request { method: Method::Post, path: "/users".into(), body: Some("Ada".into()) }, 70 Request { method: Method::Post, path: "/users".into(), body: None }, 71 Request { method: Method::Delete, path: "/users/7".into(), body: None }, 72 Request { method: Method::Get, path: "/unknown".into(), body: None }, 73 ]; 74 75 for req in &requests { 76 let res = route(req); 77 println!( 78 "{:<6} {:<12} -> {}", 79 format!("{:?}", req.method), 80 req.path, 81 status_line(&res) 82 ); 83 } 84 } ``` Output (real, from `cargo run`): ```text 1 Get /health -> 200 OK: healthy 2 Get /users/42 -> 200 OK: user #42 3 Get /users/abc -> 400 Bad Request: invalid user id 4 Post /users -> 201 Created: created: Ada 5 Post /users -> 400 Bad Request: missing body 6 Delete /users/7 -> 200 OK: deleted /users/7 7 Get /unknown -> 404 Not Found ``` The router compiles cleanly under `cargo clippy` with no warnings. Notice how matching the `(method, path, body)` tuple collapses what would be a nested `if`/`switch` mess into one flat, exhaustive decision table, and the `status_line` match guarantees you can never add a `Response` variant without giving it a status line. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — The `match` Control Flow Construct](https://doc.rust-lang.org/book/ch06-02-match.html) * [The Rust Book — Concise Control Flow with `if let` and `let ... else`](https://doc.rust-lang.org/book/ch06-03-if-let.html) * [The Rust Book — Patterns and Matching (full chapter)](https://doc.rust-lang.org/book/ch19-00-patterns.html) * [Rust Reference — Patterns](https://doc.rust-lang.org/reference/patterns.html) * [Rust by Example — Flow of Control: `match`](https://doc.rust-lang.org/rust-by-example/flow_control/match.html) * [`std::matches!` macro](https://doc.rust-lang.org/std/macro.matches.html) ### Related Topics in This Guide [Section titled “Related Topics in This Guide”](#related-topics-in-this-guide) * [Enums](/06-data-structures/02-enums/) — the data-carrying types you match on most often. * [Option Enum](/06-data-structures/03-option-enum/) — `Some`/`None` patterns and combinators that often replace a `match`. * [Structs](/06-data-structures/00-structs/) — defining the struct shapes you destructure here. * [Tuple Structs](/06-data-structures/01-tuple-structs/) — matching tuple-struct and newtype patterns. * [impl Blocks](/06-data-structures/05-impl-blocks/) — where `&self` matching commonly lives. * [Basic Types](/02-basics/01-types/): tuples and the unit type, introduced earlier. * [Ownership](/05-ownership/): why matching by reference vs. by value matters. * [Collections](/07-collections/): `while let` with iterators and slice patterns over `Vec`. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Traffic Light Action [Section titled “Exercise 1: Traffic Light Action”](#exercise-1-traffic-light-action) **Difficulty:** Easy **Objective:** Write an exhaustive `match` over an enum. **Instructions:** Given the `TrafficLight` enum below, implement `action` so that `Red` returns `"stop"`, `Yellow` returns `"slow down"`, and `Green` returns `"go"`. Do *not* use a `_` wildcard — handle each variant explicitly so a future variant would force you to revisit the match. ```rust 1 #[derive(Debug)] 2 enum TrafficLight { 3 Red, 4 Yellow, 5 Green, 6 } 7 8 fn action(light: &TrafficLight) -> &'static str { 9 // TODO: match on every variant 10 /* ??? */ 11 } 12 13 fn main() { 14 for l in [TrafficLight::Red, TrafficLight::Yellow, TrafficLight::Green] { 15 println!("{l:?} -> {}", action(&l)); 16 } 17 } ``` Solution ```rust 1 #[derive(Debug)] 2 enum TrafficLight { 3 Red, 4 Yellow, 5 Green, 6 } 7 8 fn action(light: &TrafficLight) -> &'static str { 9 match light { 10 TrafficLight::Red => "stop", 11 TrafficLight::Yellow => "slow down", 12 TrafficLight::Green => "go", 13 } 14 } 15 16 fn main() { 17 for l in [TrafficLight::Red, TrafficLight::Yellow, TrafficLight::Green] { 18 println!("{l:?} -> {}", action(&l)); 19 } 20 } ``` Output: ```text 1 Red -> stop 2 Yellow -> slow down 3 Green -> go ``` ### Exercise 2: Classify a Coordinate [Section titled “Exercise 2: Classify a Coordinate”](#exercise-2-classify-a-coordinate) **Difficulty:** Medium **Objective:** Combine struct patterns, literal patterns, and match guards. **Instructions:** Implement `quadrant` for the `Coord` struct. Return `"origin"` for `(0, 0)`, `"on y-axis"` when `x == 0`, `"on x-axis"` when `y == 0`, and `"quadrant I"`/`"II"`/`"III"`/`"IV"` for the four quadrants. Match by reference and use guards for the quadrant comparisons. ```rust 1 #[derive(Debug)] 2 struct Coord { 3 x: i32, 4 y: i32, 5 } 6 7 fn quadrant(c: &Coord) -> &'static str { 8 // TODO 9 /* ??? */ 10 } 11 12 fn main() { 13 for c in [ 14 Coord { x: 0, y: 0 }, 15 Coord { x: 0, y: 5 }, 16 Coord { x: 5, y: 0 }, 17 Coord { x: 2, y: 3 }, 18 Coord { x: -2, y: 3 }, 19 Coord { x: -2, y: -3 }, 20 Coord { x: 2, y: -3 }, 21 ] { 22 println!("{c:?} -> {}", quadrant(&c)); 23 } 24 } ``` Solution ```rust 1 #[derive(Debug)] 2 struct Coord { 3 x: i32, 4 y: i32, 5 } 6 7 fn quadrant(c: &Coord) -> &'static str { 8 match c { 9 Coord { x: 0, y: 0 } => "origin", 10 Coord { x: 0, .. } => "on y-axis", 11 Coord { y: 0, .. } => "on x-axis", 12 // When matching `&Coord`, the bindings are `&i32`, so deref in guards. 13 Coord { x, y } if *x > 0 && *y > 0 => "quadrant I", 14 Coord { x, y } if *x < 0 && *y > 0 => "quadrant II", 15 Coord { x, y } if *x < 0 && *y < 0 => "quadrant III", 16 _ => "quadrant IV", 17 } 18 } 19 20 fn main() { 21 for c in [ 22 Coord { x: 0, y: 0 }, 23 Coord { x: 0, y: 5 }, 24 Coord { x: 5, y: 0 }, 25 Coord { x: 2, y: 3 }, 26 Coord { x: -2, y: 3 }, 27 Coord { x: -2, y: -3 }, 28 Coord { x: 2, y: -3 }, 29 ] { 30 println!("{c:?} -> {}", quadrant(&c)); 31 } 32 } ``` Output: ```text 1 Coord { x: 0, y: 0 } -> origin 2 Coord { x: 0, y: 5 } -> on y-axis 3 Coord { x: 5, y: 0 } -> on x-axis 4 Coord { x: 2, y: 3 } -> quadrant I 5 Coord { x: -2, y: 3 } -> quadrant II 6 Coord { x: -2, y: -3 } -> quadrant III 7 Coord { x: 2, y: -3 } -> quadrant IV ``` ### Exercise 3: Summarize a JSON-like Value [Section titled “Exercise 3: Summarize a JSON-like Value”](#exercise-3-summarize-a-json-like-value) **Difficulty:** Hard **Objective:** Match a recursive enum with data-carrying variants, including a guard that distinguishes an empty array. **Instructions:** Given the `Json` enum, implement `summarize` so that `Null` -> `"null"`, `Bool(b)` -> `"bool(true)"`/`"bool(false)"`, `Number(n)` -> `"number(3.5)"`, `Text(s)` -> `"text(N chars)"` using the string’s length, an empty `Array` -> `"empty array"`, and a non-empty `Array` -> `"array of N"`. Match the values by reference. ```rust 1 #[derive(Debug)] 2 enum Json { 3 Null, 4 Bool(bool), 5 Number(f64), 6 Text(String), 7 Array(Vec<Json>), 8 } 9 10 fn summarize(value: &Json) -> String { 11 // TODO 12 /* ??? */ 13 } 14 15 fn main() { 16 let doc = Json::Array(vec![ 17 Json::Null, 18 Json::Bool(true), 19 Json::Number(3.5), 20 Json::Text("hi".into()), 21 Json::Array(vec![]), 22 ]); 23 if let Json::Array(items) = &doc { 24 for item in items { 25 println!("{}", summarize(item)); 26 } 27 } 28 println!("top: {}", summarize(&doc)); 29 } ``` Solution ```rust 1 #[derive(Debug)] 2 enum Json { 3 Null, 4 Bool(bool), 5 Number(f64), 6 Text(String), 7 Array(Vec<Json>), 8 } 9 10 fn summarize(value: &Json) -> String { 11 match value { 12 Json::Null => "null".to_string(), 13 Json::Bool(b) => format!("bool({b})"), 14 Json::Number(n) => format!("number({n})"), 15 Json::Text(s) => format!("text({} chars)", s.len()), 16 // A guard distinguishes the empty case before the general one. 17 Json::Array(items) if items.is_empty() => "empty array".to_string(), 18 Json::Array(items) => format!("array of {}", items.len()), 19 } 20 } 21 22 fn main() { 23 let doc = Json::Array(vec![ 24 Json::Null, 25 Json::Bool(true), 26 Json::Number(3.5), 27 Json::Text("hi".into()), 28 Json::Array(vec![]), 29 ]); 30 if let Json::Array(items) = &doc { 31 for item in items { 32 println!("{}", summarize(item)); 33 } 34 } 35 println!("top: {}", summarize(&doc)); 36 } ``` Output: ```text 1 null 2 bool(true) 3 number(3.5) 4 text(2 chars) 5 empty array 6 top: array of 5 ``` > **Tip:** The ordering of the two `Json::Array` arms matters: the guarded `is_empty()` arm must come first, because the unguarded `Json::Array(items)` arm would otherwise match every array and make the empty case unreachable. # Methods and `impl` Blocks > Rust splits data and behavior: methods live in impl blocks, and &self, &mut self, or self spells out the borrowing TypeScript hides behind an implicit this. In TypeScript you write methods *inside* the `class` body. In Rust, data and behavior are kept separate: you define a `struct` (the data) and then attach methods to it in a separate **`impl` block**. This file is about that split, and about the single most important thing the `impl` block forces you to be explicit about: how each method borrows or consumes the value it is called on. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) An **`impl` block** (short for *implementation*) is where you write the methods for a type. Every method takes an explicit first parameter — `&self`, `&mut self`, or `self` — that says exactly how much access it needs to the value: read-only, mutable, or full ownership. That single annotation is the Rust equivalent of a TypeScript method’s invisible `this`, except Rust makes the borrowing rules part of the signature so the compiler can enforce them. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Here is a small `Rectangle` class, the kind of thing you would write every day in TypeScript. Notice that the data (`width`, `height`) and the behavior (`area`, `scale`, …) all live inside one `class` body, and that every method silently has access to `this`. ```typescript 1 // TypeScript - data and methods bundled together in a class 2 class Rectangle { 3 width: number; 4 height: number; 5 6 constructor(width: number, height: number) { 7 this.width = width; 8 this.height = height; 9 } 10 11 // Reads `this`, never mutates it 12 area(): number { 13 return this.width * this.height; 14 } 15 16 isSquare(): boolean { 17 return this.width === this.height; 18 } 19 20 // Mutates `this` in place 21 scale(factor: number): void { 22 this.width *= factor; 23 this.height *= factor; 24 } 25 26 // "Consumes" the rectangle conceptually, returns a new square 27 intoSquare(): Rectangle { 28 const side = Math.max(this.width, this.height); 29 return new Rectangle(side, side); 30 } 31 } 32 33 const rect = new Rectangle(3, 4); 34 console.log(rect.area()); // 12 35 console.log(rect.isSquare()); // false 36 rect.scale(2); 37 console.log(rect); // Rectangle { width: 6, height: 8 } ``` There is no way, from the signatures alone, to tell that `area()` only *reads* while `scale()` *mutates*. TypeScript trusts you to keep that straight. Nothing stops a method from quietly mutating `this`, and nothing stops two parts of your program from holding the same object and stepping on each other. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) In Rust the data lives in a `struct` and the behavior lives in an `impl` block. Each method spells out its relationship to the value via its first parameter. ```rust 1 #[derive(Debug, Clone)] 2 struct Rectangle { 3 width: f64, 4 height: f64, 5 } 6 7 impl Rectangle { 8 // &self: read-only borrow (like a TS method that doesn't mutate) 9 fn area(&self) -> f64 { 10 self.width * self.height 11 } 12 13 fn is_square(&self) -> bool { 14 self.width == self.height 15 } 16 17 // &mut self: mutable borrow, can change fields 18 fn scale(&mut self, factor: f64) { 19 self.width *= factor; 20 self.height *= factor; 21 } 22 23 // self: takes ownership, consumes the value 24 fn into_square(self) -> Rectangle { 25 let side = self.width.max(self.height); 26 Rectangle { width: side, height: side } 27 } 28 } 29 30 fn main() { 31 let mut rect = Rectangle { width: 3.0, height: 4.0 }; 32 println!("area = {}", rect.area()); 33 println!("is_square = {}", rect.is_square()); 34 35 rect.scale(2.0); 36 println!("after scale: {:?}", rect); 37 38 let sq = rect.into_square(); 39 println!("square: {:?}", sq); 40 // `rect` was moved into `into_square`; using it here would not compile. 41 } ``` Running it prints: ```text 1 area = 12 2 is_square = false 3 after scale: Rectangle { width: 6.0, height: 8.0 } 4 square: Rectangle { width: 8.0, height: 8.0 } ``` > **Note:** `area = 12`, not `12.0`. Rust’s `Display` formatting (`{}`) prints a whole-valued `f64` without a trailing `.0`. The `Debug` formatting (`{:?}`) used in the `after scale:` line *does* show `6.0`, so you can tell it is a float. Three different methods, three different first parameters. The signature is the contract: `area` promises not to mutate, `scale` requires mutable access, and `into_square` takes the whole rectangle and never gives it back. > This file assumes you already know how to declare and instantiate a struct. If `Rectangle { width: 3.0, height: 4.0 }` is unfamiliar, read [Structs](/06-data-structures/00-structs/) first. Constructors like `Rectangle::new(...)` (associated functions with no `self`) are covered in [Associated Functions and Constructors](/06-data-structures/06-associated-functions/). *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Why the data and methods are separate [Section titled “Why the data and methods are separate”](#why-the-data-and-methods-are-separate) In TypeScript the `class` keyword fuses fields and methods into one declaration. Rust deliberately splits them: * `struct Rectangle { ... }` declares *what the data looks like*. * `impl Rectangle { ... }` declares *what you can do with it*. This split is more than stylistic. It means methods are decoupled from the type definition, which is what later lets you implement **traits** (Rust’s version of interfaces) for your type in their own `impl` blocks. See [Associated Types and Associated Constants](/06-data-structures/07-associated-types/) for a first taste and Section 09 for the full story. A `struct` with no `impl` block is perfectly valid; it is just a bag of data. ### `self` is the receiver, and it is explicit [Section titled “self is the receiver, and it is explicit”](#self-is-the-receiver-and-it-is-explicit) Every method’s first parameter is some form of `self`. This is Rust’s `this`, but unlike TypeScript’s invisible, always-present `this`, you write it out and you choose its *flavor*: | First parameter | Means | TypeScript analogy | | --------------- | -------------------------------------------- | --------------------------------------------------- | | `&self` | Borrow the value immutably (read-only) | A method that only reads `this` | | `&mut self` | Borrow the value mutably (can change fields) | A method that mutates `this` | | `self` | Take ownership of the value (consume it) | *No clean analogy* — TS objects are never “used up” | `&self` is shorthand for `self: &Self`, `&mut self` for `self: &mut Self`, and `self` for `self: Self`, where `Self` is an alias for the type the `impl` is for (`Rectangle` here). You will almost always use the shorthand. ### Method calls desugar to function calls [Section titled “Method calls desugar to function calls”](#method-calls-desugar-to-function-calls) When you write `rect.area()`, Rust desugars it to a plain function call and automatically inserts the right kind of reference. These two lines are identical: ```rust 1 #[derive(Debug)] 2 struct User { 3 name: String, 4 } 5 6 impl User { 7 fn greet(&self) -> String { 8 format!("Hi, {}!", self.name) 9 } 10 } 11 12 fn main() { 13 let user = User { name: String::from("Ada") }; 14 15 // These two calls are equivalent: method syntax desugars to the 16 // fully-qualified function call, with Rust auto-referencing `&user`. 17 println!("{}", user.greet()); 18 println!("{}", User::greet(&user)); 19 } ``` Both print `Hi, Ada!`. The dot syntax is just sugar: Rust looks at `greet`’s signature, sees `&self`, and automatically passes `&user` instead of `user`. This automatic referencing/dereferencing is why you never have to write `(&rect).area()` or `(*ptr).area()` by hand: the compiler figures out how many `&` or `*` to add. (Contrast TypeScript, where `this` is bound dynamically at call time and can be lost when a method is detached; in Rust the receiver is resolved statically at compile time.) ### `&self`: the default, read-only method [Section titled “\&self: the default, read-only method”](#self-the-default-read-only-method) `area`, `is_square`, `subtotal_cents` — anything that only *reads* — should take `&self`. An immutable borrow lets many parts of your program look at the value at once, and it guarantees the method cannot accidentally change anything. This is the most common receiver; reach for it first. ### `&mut self`: in-place mutation [Section titled “\&mut self: in-place mutation”](#mut-self-in-place-mutation) `scale` changes the rectangle’s fields, so it needs `&mut self`: a mutable (exclusive) borrow. While a `&mut self` method is running, nothing else can touch the value, which is how Rust statically prevents data races. Calling a `&mut self` method requires the variable itself to be declared `mut` (more on that in Pitfalls). ### `self`: consuming the value [Section titled “self: consuming the value”](#self-consuming-the-value) `into_square` takes `self` *by value*. The rectangle is **moved** into the method, and the original binding is no longer usable afterward. This is the receiver with no TypeScript equivalent: in JavaScript an object lives until the garbage collector decides otherwise, and a method can never “use it up.” In Rust, a `self`-taking method expresses a transformation that consumes the input. This is common when converting one type into another (the `into_*` naming convention) or when finalizing a builder. See [Associated Functions and Constructors](/06-data-structures/06-associated-functions/) for the builder pattern teaser. *** ## Multiple `impl` Blocks [Section titled “Multiple impl Blocks”](#multiple-impl-blocks) A single type can have **as many `impl` blocks as you like**. They all contribute methods to the same type; there is no requirement to put everything in one block. ```rust 1 #[derive(Debug)] 2 struct Counter { 3 count: u32, 4 step: u32, 5 } 6 7 // First impl block: construction and core behavior 8 impl Counter { 9 fn new(step: u32) -> Self { 10 Counter { count: 0, step } 11 } 12 13 fn increment(&mut self) { 14 self.count += self.step; 15 } 16 } 17 18 // Second impl block: read-only queries (could live in another module/file) 19 impl Counter { 20 fn value(&self) -> u32 { 21 self.count 22 } 23 24 fn has_reached(&self, target: u32) -> bool { 25 self.count >= target 26 } 27 } 28 29 fn main() { 30 let mut c = Counter::new(5); 31 c.increment(); 32 c.increment(); 33 println!("value = {}", c.value()); 34 println!("reached 10? {}", c.has_reached(10)); 35 println!("{c:?}"); 36 } ``` Output: ```text 1 value = 10 2 reached 10? true 3 Counter { count: 10, step: 5 } ``` For a plain struct like this, splitting into two blocks is purely organizational; the compiler treats it as one combined set of methods. So why is it allowed? * **Organization.** Group constructors in one block, queries in another, mutators in a third. Larger types stay readable. * **Conditional methods.** With generics you can add methods only when the type parameter satisfies a bound (e.g. only when `T: Display`). Each bound gets its own `impl` block. (Covered in Section 09.) * **Trait implementations.** Inherent methods go in `impl Counter`, while `impl SomeTrait for Counter` lives in its own separate block. They never mix. * **Spreading across files.** A type defined in one module can have additional `impl` blocks in other modules of the same crate. > **Tip:** For a simple type, prefer one `impl` block. Reach for multiple blocks when there is a real reason: generic bounds, trait impls, or a genuinely large API. Splitting a five-method struct into five blocks just adds noise. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / JavaScript | Rust | | ---------------------------------- | ------------------------------- | --------------------------------------------- | | Where methods live | Inside the `class` body | In a separate `impl` block | | The receiver | Implicit `this` | Explicit `self` / `&self` / `&mut self` | | Read vs. mutate | Not visible in the signature | Encoded as `&self` vs. `&mut self` | | Consuming the value | Not possible (GC owns lifetime) | `self` by value moves and consumes it | | Number of “method bodies” per type | One `class` body | Any number of `impl` blocks | | Static vs. instance methods | `static` keyword | Methods without `self` (associated functions) | | `this` rebinding | Dynamic; can be lost/rebound | Resolved statically; cannot be lost | The headline difference: **Rust puts the borrowing contract in the method signature.** A TypeScript reader cannot tell `area()` from `scale()` without reading the bodies. A Rust reader sees `&self` versus `&mut self` and knows immediately, and so does the compiler. That is what makes “this method won’t mutate my object” a *guarantee* rather than a *convention*. A second difference worth internalizing: `self` by value has no TypeScript counterpart. The idea that calling a method can *use up* the object — so that the variable is gone afterward — flows directly from [ownership](/05-ownership/). If you have not read Section 05 yet, the `self`-by-value examples here are a good motivation to. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Calling a `&mut self` method on an immutable binding [Section titled “Pitfall 1: Calling a \&mut self method on an immutable binding”](#pitfall-1-calling-a-mut-self-method-on-an-immutable-binding) You declared the variable without `mut`, then tried to call a mutating method. ```rust 1 struct BankAccount { 2 balance: u64, 3 } 4 5 impl BankAccount { 6 fn deposit(&mut self, amount: u64) { 7 self.balance += amount; 8 } 9 } 10 11 fn main() { 12 let account = BankAccount { balance: 100 }; 13 account.deposit(50); // does not compile (error[E0596]) 14 println!("{}", account.balance); 15 } ``` The real compiler error: ```text 1 error[E0596]: cannot borrow `account` as mutable, as it is not declared as mutable 2 --> src/main.rs:13:5 3 | 4 13 | account.deposit(50); // does not compile (error[E0596]) 5 | ^^^^^^^ cannot borrow as mutable 6 | 7 help: consider changing this to be mutable 8 | 9 12 | let mut account = BankAccount { balance: 100 }; 10 | +++ ``` **Fix:** declare the binding `let mut account = ...`. Mutability is a property of the *binding*, not the type, so the caller must opt in, just as `&mut self` opted in on the method side. ### Pitfall 2: Using a value after a `self`-taking method consumed it [Section titled “Pitfall 2: Using a value after a self-taking method consumed it”](#pitfall-2-using-a-value-after-a-self-taking-method-consumed-it) A method that takes `self` by value moves the value; the original binding is dead afterward. ```rust 1 #[derive(Debug)] 2 struct Order { 3 items: Vec<String>, 4 } 5 6 impl Order { 7 fn finalize(self) -> usize { 8 self.items.len() 9 } 10 } 11 12 fn main() { 13 let order = Order { items: vec![String::from("book"), String::from("pen")] }; 14 let count = order.finalize(); // consumes `order` 15 println!("count = {}", count); 16 println!("{:?}", order); // does not compile (error[E0382]): order was moved 17 } ``` The real compiler error (abridged). Note how it points right at `finalize`’s `self`: ```text 1 error[E0382]: borrow of moved value: `order` 2 --> src/main.rs:16:22 3 | 4 13 | let order = Order { items: ... }; 5 | ----- move occurs because `order` has type `Order`, which does not implement the `Copy` trait 6 14 | let count = order.finalize(); // consumes `order` 7 | ---------- `order` moved due to this method call 8 ... 9 16 | println!("{:?}", order); // order was moved 10 | ^^^^^ value borrowed here after move 11 | 12 note: `Order::finalize` takes ownership of the receiver `self`, which moves `order` ``` **Fix:** if you did not mean to consume the value, take `&self` instead of `self`. If consuming is intended (e.g. `into_*` conversions), just do everything you need with `order` *before* the consuming call, or have the method return what you still need. ### Pitfall 3: Forgetting `&mut self` and trying to mutate through `&self` [Section titled “Pitfall 3: Forgetting \&mut self and trying to mutate through \&self”](#pitfall-3-forgetting-mut-self-and-trying-to-mutate-through-self) A `&self` method gets a shared, read-only borrow, so you cannot assign to fields through it. ```rust 1 struct Counter { 2 count: u32, 3 } 4 5 impl Counter { 6 fn increment(&self) { 7 self.count += 1; // does not compile (error[E0594]) 8 } 9 } ``` The real compiler error helpfully suggests the fix: ```text 1 error[E0594]: cannot assign to `self.count`, which is behind a `&` reference 2 --> src/main.rs:7:9 3 | 4 7 | self.count += 1; // does not compile (error[E0594]) 5 | ^^^^^^^^^^^^^^^ `self` is a `&` reference, so the data it refers to cannot be written 6 | 7 help: consider changing this to be a mutable reference 8 | 9 6 | fn increment(&mut self) { 10 | +++ ``` **Fix:** change the receiver to `&mut self`. Coming from TypeScript this trips people up because *every* TS method can mutate `this`; in Rust you must ask for write access. ### Pitfall 4: Reaching for `self` by value when `&self` would do [Section titled “Pitfall 4: Reaching for self by value when \&self would do”](#pitfall-4-reaching-for-self-by-value-when-self-would-do) A subtle one: taking `self` by value when you only read makes every call consume the value, forcing the caller to clone or reconstruct it. Unless you are deliberately converting/finalizing, default to `&self`. Take `&mut self` to mutate, and `self` only when consumption is the point. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Default to `&self`.** Most methods only read. Use the least permissive receiver that does the job: `&self` over `&mut self`, and `&mut self` over `self`. * **Reserve `self` by value for transformations and finalizers.** Conversions named `into_*`, builder steps, and “this object is now spent” operations are the natural homes for `self`. * **Use the `into_` / `to_` / `as_` naming conventions.** By convention, `into_*` consumes `self` (takes ownership), `to_*` borrows and produces an owned copy (often more expensive), and `as_*` is a cheap borrow-to-borrow view. Following the convention tells callers the cost without reading the body. * **Keep mutation explicit and contained.** A small number of clearly named `&mut self` methods is easier to reason about than many methods that quietly mutate. * **Group with `impl` blocks intentionally.** One block for a simple type. Separate blocks for trait impls, for generic-bounded methods, or to keep a large API navigable, not just for the sake of splitting. * **Don’t annotate the receiver’s type by hand.** Write `&self`, not the longhand `self: &Self`. The shorthand is idiomatic; [Clippy](/01-getting-started/03-cargo-basics/)’s `needless_arbitrary_self_type` lint (warn-by-default) flags the `self: &Self` spelling and suggests `&self`. Note it only catches the `Self`-alias forms: write it out as a concrete type (`self: &Rectangle`) and Clippy stays silent, so don’t rely on the linter to catch every longhand receiver. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A shopping cart that uses all three receiver kinds the way you would in production: `&mut self` to build it up, `&self` to query it, and `self` to finalize it into an immutable receipt. It is also split across two `impl` blocks: one for mutation, one for read-only queries. ```rust 1 #[derive(Debug, Clone)] 2 struct CartItem { 3 name: String, 4 price_cents: u64, 5 quantity: u32, 6 } 7 8 #[derive(Debug, Default)] 9 struct ShoppingCart { 10 items: Vec<CartItem>, 11 } 12 13 impl ShoppingCart { 14 fn new() -> Self { 15 ShoppingCart { items: Vec::new() } 16 } 17 18 // &mut self: mutate the cart in place 19 fn add(&mut self, name: &str, price_cents: u64, quantity: u32) { 20 self.items.push(CartItem { 21 name: name.to_string(), 22 price_cents, 23 quantity, 24 }); 25 } 26 } 27 28 // A second impl block grouping the read-only "query" methods. 29 impl ShoppingCart { 30 // &self: read-only; borrows the cart without taking it 31 fn subtotal_cents(&self) -> u64 { 32 self.items 33 .iter() 34 .map(|item| item.price_cents * item.quantity as u64) 35 .sum() 36 } 37 38 fn item_count(&self) -> u32 { 39 self.items.iter().map(|item| item.quantity).sum() 40 } 41 42 fn describe(&self) -> String { 43 let lines: Vec<String> = self 44 .items 45 .iter() 46 .map(|item| format!(" {} x{}", item.name, item.quantity)) 47 .collect(); 48 lines.join("\n") 49 } 50 51 // self: consumes the cart, producing a final receipt 52 fn checkout(self) -> String { 53 format!( 54 "{}\nOrder placed: {} item(s), total ${:.2}", 55 self.describe(), 56 self.item_count(), 57 self.subtotal_cents() as f64 / 100.0 58 ) 59 } 60 } 61 62 fn main() { 63 let mut cart = ShoppingCart::new(); 64 cart.add("Rust Book", 3999, 1); 65 cart.add("Sticker", 299, 3); 66 67 println!("items in cart: {}", cart.item_count()); 68 println!("subtotal: ${:.2}", cart.subtotal_cents() as f64 / 100.0); 69 70 let receipt = cart.checkout(); // cart is consumed here; can't use `cart` afterward 71 println!("{receipt}"); 72 } ``` Output: ```text 1 items in cart: 4 2 subtotal: $48.96 3 Rust Book x1 4 Sticker x3 5 Order placed: 4 item(s), total $48.96 ``` The receiver kinds map directly onto the cart’s lifecycle: you *build* it (`&mut self`), you *inspect* it as often as you like (`&self`), and you *check out* exactly once (`self`), after which the cart is gone and only the receipt remains. The compiler enforces that lifecycle: you cannot accidentally add an item to a cart you have already checked out. ### Bonus: fluent chaining with `mut self` [Section titled “Bonus: fluent chaining with mut self”](#bonus-fluent-chaining-with-mut-self) A close cousin is the owning-builder style, where each step takes `mut self` by value, mutates, and returns `self` so calls can be chained: ```rust 1 #[derive(Debug)] 2 struct RequestBuilder { 3 url: String, 4 method: String, 5 headers: Vec<(String, String)>, 6 } 7 8 impl RequestBuilder { 9 fn new(url: &str) -> Self { 10 RequestBuilder { 11 url: url.to_string(), 12 method: "GET".to_string(), 13 headers: Vec::new(), 14 } 15 } 16 17 // Takes `mut self` by value and returns it, enabling fluent chaining. 18 fn method(mut self, method: &str) -> Self { 19 self.method = method.to_string(); 20 self 21 } 22 23 fn header(mut self, key: &str, value: &str) -> Self { 24 self.headers.push((key.to_string(), value.to_string())); 25 self 26 } 27 } 28 29 fn main() { 30 let req = RequestBuilder::new("https://api.example.com/users") 31 .method("POST") 32 .header("Content-Type", "application/json") 33 .header("Authorization", "Bearer token123"); 34 35 println!("{} {}", req.method, req.url); 36 for (k, v) in &req.headers { 37 println!(" {k}: {v}"); 38 } 39 } ``` Output: ```text 1 POST https://api.example.com/users 2 Content-Type: application/json 3 Authorization: Bearer token123 ``` > **Note:** `mut self` here is *not* a fourth receiver kind: it is still `self` by value (the value is moved in), and `mut` just makes the moved-in binding mutable so the body can reassign fields. It reads almost exactly like a TypeScript fluent API that `return this`, except each step takes ownership and hands it back. The full builder pattern, including when to prefer `&mut self` chaining instead, is teased in [Associated Functions and Constructors](/06-data-structures/06-associated-functions/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book - Method Syntax](https://doc.rust-lang.org/book/ch05-03-method-syntax.html) * [Rust by Example - Methods](https://doc.rust-lang.org/rust-by-example/fn/methods.html) * [Rust Reference - Implementations](https://doc.rust-lang.org/reference/items/implementations.html) * [Rust API Guidelines - `as_`, `to_`, `into_` conventions](https://rust-lang.github.io/api-guidelines/naming.html#ad-hoc-conversions-follow-as_-to_-into_-conventions-c-conv) ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Structs](/06-data-structures/00-structs/) — defining the data your `impl` block operates on * [Associated Functions](/06-data-structures/06-associated-functions/) — methods *without* `self` (constructors like `Self::new`) and the builder teaser * [Associated Types & Consts](/06-data-structures/07-associated-types/) — other things that live inside an `impl` block * [Enums](/06-data-structures/02-enums/) and [Pattern Matching](/06-data-structures/04-pattern-matching/) — `impl` blocks work on enums too * [Ownership](/05-ownership/) — the foundation behind `self` / `&self` / `&mut self` * [Variables and Mutability](/02-basics/00-variables/) — why a binding must be `mut` to call a `&mut self` method * [Collections](/07-collections/) — the `Vec<T>` used in the real-world example *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Temperature methods [Section titled “Exercise 1: Temperature methods”](#exercise-1-temperature-methods) **Difficulty:** Easy **Objective:** Practice choosing between `&self` and `&mut self`. **Instructions:** Given the struct below, write a `to_fahrenheit` method that returns the temperature in Fahrenheit without changing the value, and a `warm_up` method that raises the Celsius value in place. Pick the correct receiver for each. ```rust 1 #[derive(Debug)] 2 struct Temperature { 3 celsius: f64, 4 } 5 6 impl Temperature { 7 fn to_fahrenheit(/* ??? */) -> f64 { 8 // formula: C * 9/5 + 32 9 } 10 11 fn warm_up(/* ??? */, degrees: f64) { 12 // TODO: raise self.celsius by `degrees` 13 } 14 } 15 16 fn main() { 17 let mut t = Temperature { celsius: 20.0 }; 18 println!("{}F", t.to_fahrenheit()); // 68 19 t.warm_up(5.0); 20 println!("now {}C = {}F", t.celsius, t.to_fahrenheit()); // 25C = 77F 21 } ``` Solution ```rust 1 #[derive(Debug)] 2 struct Temperature { 3 celsius: f64, 4 } 5 6 impl Temperature { 7 fn to_fahrenheit(&self) -> f64 { 8 self.celsius * 9.0 / 5.0 + 32.0 9 } 10 11 fn warm_up(&mut self, degrees: f64) { 12 self.celsius += degrees; 13 } 14 } 15 16 fn main() { 17 let mut t = Temperature { celsius: 20.0 }; 18 println!("{}F", t.to_fahrenheit()); // 68 19 t.warm_up(5.0); 20 println!("now {}C = {}F", t.celsius, t.to_fahrenheit()); // 25C = 77F 21 } ``` `to_fahrenheit` only reads, so it takes `&self`. `warm_up` mutates, so it needs `&mut self`, and that is why `t` must be declared `let mut`. ### Exercise 2: A stack that can be drained [Section titled “Exercise 2: A stack that can be drained”](#exercise-2-a-stack-that-can-be-drained) **Difficulty:** Medium **Objective:** Use a `self`-by-value method to consume a value and hand back its contents. **Instructions:** Complete the `Stack` so that `push` adds a value, `sum` reports the total without consuming the stack, and `into_vec` consumes the stack and returns the underlying `Vec<i32>`. After calling `into_vec`, the stack should no longer be usable. ```rust 1 #[derive(Debug)] 2 struct Stack { 3 values: Vec<i32>, 4 } 5 6 impl Stack { 7 fn new() -> Self { 8 Stack { values: Vec::new() } 9 } 10 11 fn push(/* ??? */, value: i32) { 12 // TODO 13 } 14 15 fn sum(/* ??? */) -> i32 { 16 // TODO: total of all values 17 } 18 19 fn into_vec(/* ??? */) -> Vec<i32> { 20 // TODO: return the underlying Vec, consuming self 21 } 22 } 23 24 fn main() { 25 let mut s = Stack::new(); 26 s.push(1); 27 s.push(2); 28 s.push(3); 29 println!("sum = {}", s.sum()); // 6 30 let v = s.into_vec(); 31 println!("vec = {:?}", v); // [1, 2, 3] 32 } ``` Solution ```rust 1 #[derive(Debug)] 2 struct Stack { 3 values: Vec<i32>, 4 } 5 6 impl Stack { 7 fn new() -> Self { 8 Stack { values: Vec::new() } 9 } 10 11 fn push(&mut self, value: i32) { 12 self.values.push(value); 13 } 14 15 fn sum(&self) -> i32 { 16 self.values.iter().sum() 17 } 18 19 // Consumes the stack and hands back the underlying Vec. 20 fn into_vec(self) -> Vec<i32> { 21 self.values 22 } 23 } 24 25 fn main() { 26 let mut s = Stack::new(); 27 s.push(1); 28 s.push(2); 29 s.push(3); 30 println!("sum = {}", s.sum()); // 6 31 let v = s.into_vec(); 32 println!("vec = {:?}", v); // [1, 2, 3] 33 } ``` `into_vec` takes `self` by value so it can *move* `self.values` out and return it. Because the stack is consumed, the compiler will reject any use of `s` after `s.into_vec()`. The `into_` prefix is the conventional signal that a method takes ownership. ### Exercise 3: A chainable account across two `impl` blocks [Section titled “Exercise 3: A chainable account across two impl blocks”](#exercise-3-a-chainable-account-across-two-impl-blocks) **Difficulty:** Medium/Hard **Objective:** Combine multiple `impl` blocks with the owning-builder (`mut self`) chaining style. **Instructions:** Split `Account` into two `impl` blocks. In the first, put the constructor `new(initial: i64)`. In the second, put `deposit` and `withdraw` (each takes `mut self`, adjusts the balance, and returns `Self` so calls can be chained) plus a read-only `balance(&self) -> i64`. Then make the `main` below print `balance = 120`. ```rust 1 #[derive(Debug)] 2 struct Account { 3 balance: i64, 4 } 5 6 // impl block 1: construction 7 // impl block 2: deposit / withdraw / balance 8 9 fn main() { 10 let account = Account::new(100) 11 .deposit(50) 12 .withdraw(30); 13 println!("balance = {}", account.balance()); // 120 14 } ``` Solution ```rust 1 #[derive(Debug)] 2 struct Account { 3 balance: i64, 4 } 5 6 impl Account { 7 fn new(initial: i64) -> Self { 8 Account { balance: initial } 9 } 10 } 11 12 impl Account { 13 fn deposit(mut self, amount: i64) -> Self { 14 self.balance += amount; 15 self 16 } 17 18 fn withdraw(mut self, amount: i64) -> Self { 19 self.balance -= amount; 20 self 21 } 22 23 fn balance(&self) -> i64 { 24 self.balance 25 } 26 } 27 28 fn main() { 29 let account = Account::new(100) 30 .deposit(50) 31 .withdraw(30); 32 println!("balance = {}", account.balance()); // 120 33 } ``` `100 + 50 - 30 = 120`. Each `deposit`/`withdraw` takes `mut self`, mutates the moved-in value, and returns it so the next call in the chain receives ownership. `balance` only reads, so it takes `&self`. Splitting construction from behavior into two `impl` blocks is purely organizational here; the compiler merges them into one method set. # Associated Functions and Constructors > Rust has no constructor or static keyword; associated functions like Self::new do both jobs, returning Result for fallible construction and enabling builders. In TypeScript, a `class` gives you a built-in `constructor` and lets you mark helpers as `static`. Rust has neither keyword. Instead, both jobs are done by **associated functions**: functions that live inside an `impl` block but, unlike methods, do *not* take `self`. This file is about those functions: the `Self::new` constructors you will write constantly, named alternative constructors, and a first look at the builder pattern they enable. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) An **associated function** is a function defined in an `impl` block that has no `self` parameter. You call it on the *type* with the `::` path operator (`User::new(...)`) rather than on a value with the `.` operator. It is Rust’s equivalent of a TypeScript `static` method, and the conventional `new` associated function is as close as Rust gets to a constructor. The key thing for a TypeScript/JavaScript developer to absorb: **Rust gives you no constructor for free.** If you want `User::new(...)`, you write it yourself. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Here is a small `User` class in TypeScript. It uses the language’s built-in `constructor`, a couple of `static` factory methods that return new instances, and a `static` helper that returns a plain value rather than an instance. ```typescript 1 // TypeScript - a class with a constructor and static factory methods 2 class User { 3 id: number; 4 name: string; 5 isActive: boolean; 6 7 // The built-in constructor: called via `new User(...)` 8 constructor(id: number, name: string) { 9 this.id = id; 10 this.name = name; 11 this.isActive = true; 12 } 13 14 // A static factory: an alternative way to build a User 15 static guest(): User { 16 const u = new User(0, "guest"); 17 u.isActive = false; 18 return u; 19 } 20 21 // A static helper that does NOT return a User 22 static isValidId(id: number): boolean { 23 return Number.isInteger(id) && id >= 0; 24 } 25 26 // An ordinary (instance) method, for contrast — it uses `this` 27 label(): string { 28 return `#${this.id} ${this.name}`; 29 } 30 } 31 32 const alice = new User(1, "Alice"); 33 const visitor = User.guest(); 34 35 console.log(alice.label()); // #1 Alice 36 console.log(visitor.isActive); // false 37 console.log(User.isValidId(-3)); // false ``` Three things to notice, because each maps to a distinct Rust idea: * `new User(...)` invokes the `constructor`. The `new` keyword and the `constructor` slot are **built in**: you get them whether you write a constructor or not. * `User.guest()` and `User.isValidId(...)` are `static`: called on the *class*, not on an instance, and they have no `this`. * `label()` is an instance method: called on a value and using `this`. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust splits these into two categories. Functions with `self` are **methods** (covered in [Methods and `impl` Blocks](/06-data-structures/05-impl-blocks/)); functions *without* `self` are **associated functions**. There is no `new` keyword and no automatic constructor. You write `new` as a plain associated function that returns `Self`. ```rust 1 #[derive(Debug)] 2 struct User { 3 id: u32, 4 name: String, 5 is_active: bool, 6 } 7 8 impl User { 9 // Associated function: no `self`. Called as `User::new(...)`. 10 // `Self` is an alias for `User`, the type this `impl` block is for. 11 fn new(id: u32, name: &str) -> Self { 12 Self { 13 id, 14 name: name.to_string(), 15 is_active: true, 16 } 17 } 18 19 // Another associated function: a named alternative constructor, 20 // the equivalent of TypeScript's `static guest()`. 21 fn guest() -> Self { 22 Self { 23 id: 0, 24 name: String::from("guest"), 25 is_active: false, 26 } 27 } 28 29 // An associated function that does NOT return Self — like a 30 // TypeScript `static` helper that returns a plain value. 31 fn is_valid_id(id: u32) -> bool { 32 id != 0 33 } 34 35 // A method (takes &self), for contrast. Called as `value.label()`. 36 fn label(&self) -> String { 37 format!("#{} {}", self.id, self.name) 38 } 39 } 40 41 fn main() { 42 // Associated functions are called on the TYPE with `::`, not on a value. 43 let alice = User::new(1, "Alice"); 44 let visitor = User::guest(); 45 46 println!("{}", alice.label()); // method call, uses `.` 47 println!("{}", visitor.is_active); 48 println!("{}", User::is_valid_id(0)); // associated fn, uses `::` 49 println!("{alice:?}"); 50 } ``` Running it prints: ```text 1 #1 Alice 2 false 3 false 4 User { id: 1, name: "Alice", is_active: true } ``` The whole distinction comes down to one rule: **a function with `self` is a method (call it with `.`); a function without `self` is an associated function (call it with `::`).** `new`, `guest`, and `is_valid_id` have no `self`, so they belong to the type, not to any particular value. > **Note:** `Self` (capital S) is a type alias for the type the `impl` block is for. Writing `-> Self` and `Self { ... }` instead of `-> User` and `User { ... }` is idiomatic: it keeps the constructor working unchanged if you rename the struct, and reads clearly as “return a value of my own type.” *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `new` is a convention, not a keyword [Section titled “new is a convention, not a keyword”](#new-is-a-convention-not-a-keyword) In TypeScript, `new User(1, "Alice")` is special syntax: the `new` operator allocates an object and calls the `constructor`. In Rust there is no `new` operator and no special constructor slot. `User::new(...)` is calling a perfectly ordinary associated function that you happened to name `new`. You could name it `create`, `make`, or `from_parts` and it would work identically. `new` is simply the community convention for “the primary, no-frills constructor.” This means the *real* way to build a struct is the literal struct syntax from [Structs](/06-data-structures/00-structs/): ```rust 1 let alice = User { id: 1, name: String::from("Alice"), is_active: true }; ``` A `new` associated function is just a convenience wrapper around that literal. It earns its keep by (a) hiding boilerplate (like defaulting `is_active` to `true`), and (b) being callable from other modules even when the struct’s fields are private (see [Best Practices](#best-practices)). ### Associated functions vs. methods: the `self` test [Section titled “Associated functions vs. methods: the self test”](#associated-functions-vs-methods-the-self-test) Everything inside an `impl` block is an **associated item**. Among the functions, the dividing line is the first parameter: | First parameter | Category | Called with | TypeScript analogy | | ------------------------------- | ----------------------- | ------------------ | ----------------------------- | | `&self`, `&mut self`, or `self` | **method** | `value.method()` | instance method (uses `this`) | | *(none)* | **associated function** | `Type::function()` | `static` method (no `this`) | Because an associated function has no `self`, the word `self` is simply not in scope inside its body. There is no instance to refer to: you are constructing or computing something *for the type*, not operating on an existing value. ### `Self` and delegating between constructors [Section titled “Self and delegating between constructors”](#self-and-delegating-between-constructors) `Self` lets one constructor build on another. A named constructor can call `Self::new` to avoid repeating field logic: ```rust 1 #[derive(Debug)] 2 struct Temperature { 3 celsius: f64, 4 } 5 6 impl Temperature { 7 fn new(celsius: f64) -> Self { 8 Self { celsius } 9 } 10 11 // Delegates to `new` via `Self::new`, so the field logic lives in one place. 12 fn from_fahrenheit(f: f64) -> Self { 13 Self::new((f - 32.0) * 5.0 / 9.0) 14 } 15 16 // An associated function that returns a plain value, not Self. 17 fn absolute_zero_c() -> f64 { 18 -273.15 19 } 20 } 21 22 fn main() { 23 let t = Temperature::from_fahrenheit(212.0); 24 println!("{:.1}", t.celsius); // 100.0 25 println!("{}", Temperature::absolute_zero_c()); // -273.15 26 } ``` Output: ```text 1 100.0 2 -273.15 ``` `Self::new(...)` is the type-level counterpart of calling another method on `self`, except there is no `self`, so you reach for the function through the type alias `Self`. ### Method-call syntax is sugar; `::` is the real form [Section titled “Method-call syntax is sugar; :: is the real form”](#method-call-syntax-is-sugar--is-the-real-form) When you call a method, `value.method()` quietly desugars to `Type::method(value)` (the compiler also auto-inserts `&` or `&mut` as needed — see [Methods and `impl` Blocks](/06-data-structures/05-impl-blocks/)). Associated functions don’t get that sugar because there is no receiver value to put before the dot. So you always write the fully-qualified `Type::function()` form. That is *why* `User::new(...)` and `alice.label()` look syntactically different even though both are functions in the same `impl` block. ### `Default`: a standard-library constructor convention [Section titled “Default: a standard-library constructor convention”](#default-a-standard-library-constructor-convention) Rust’s standard library has a trait, `Default`, whose single associated function `default()` returns a “sensible zero value” of the type. You rarely write it by hand: `#[derive(Default)]` generates it for you when every field is itself `Default` (numbers default to `0`, `String` to `""`, `bool` to `false`, `Option<T>` to `None`). ```rust 1 // #[derive(Default)] writes `Settings::default()` for you. 2 #[derive(Debug, Default)] 3 struct Settings { 4 verbose: bool, 5 retries: u32, 6 label: String, 7 } 8 9 fn main() { 10 let s = Settings::default(); 11 println!("{s:?}"); 12 } ``` Output: ```text 1 Settings { verbose: false, retries: 0, label: "" } ``` `Settings::default()` is an associated function (no `self`), just like `new`. The difference is that `default()` comes from a *trait*, so it is part of a shared, well-known interface; many APIs accept “anything that has a sensible default.” Reach for `Default` when “all fields zeroed” is a meaningful starting point, and for a hand-written `new` when construction needs arguments or non-trivial defaults. Full trait coverage is in [Section 09](/09-generics-traits/). > **Tip:** `new` and `default` are not mutually exclusive. A common pattern is to derive `Default`, then have `new()` (with no arguments) just call `Self::default()`, so callers can use whichever they prefer. *** ## Fallible Constructors: returning `Result` [Section titled “Fallible Constructors: returning Result”](#fallible-constructors-returning-result) A TypeScript constructor can only `throw` on bad input, and a thrown error is invisible in the type signature. Rust associated functions return a value, so a constructor that can fail simply returns a [`Result`](/08-error-handling/) instead of `Self`. The convention is to keep `new` infallible and use a descriptive name (or `try_new`) for the checked version. ```rust 1 #[derive(Debug)] 2 struct Percentage { 3 value: u8, 4 } 5 6 impl Percentage { 7 // A validated constructor returns Result instead of panicking. 8 fn try_new(value: u8) -> Result<Self, String> { 9 if value > 100 { 10 Err(format!("{value} is greater than 100")) 11 } else { 12 Ok(Self { value }) 13 } 14 } 15 } 16 17 fn main() { 18 match Percentage::try_new(42) { 19 Ok(p) => println!("ok: {p:?}"), 20 Err(e) => println!("err: {e}"), 21 } 22 match Percentage::try_new(150) { 23 Ok(p) => println!("ok: {p:?}"), 24 Err(e) => println!("err: {e}"), 25 } 26 } ``` Output: ```text 1 ok: Percentage { value: 42 } 2 err: 150 is greater than 100 ``` The signature `try_new(value: u8) -> Result<Self, String>` tells the caller, at compile time, that construction can fail and *forces* them to handle the failure. Contrast TypeScript, where `new Percentage(150)` throwing is something you can only discover by reading the constructor body or the docs. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / JavaScript | Rust | | ----------------------------------- | ----------------------------------------- | ---------------------------------------------------------------- | | Constructor | Built-in `constructor`, called with `new` | A plain associated function you write, named `new` by convention | | Is a constructor provided for you? | Yes (implicit no-arg one if omitted) | No; you must write it | | Static helper | `static foo()` | Associated function with no `self` | | How you call it | `Type.foo()` (dot) | `Type::foo()` (path `::`) | | Distinguishing static from instance | The `static` keyword | Presence/absence of a `self` parameter | | Returning the new value | Implicit (`new` returns the instance) | Explicit `-> Self` and an explicit `Self { ... }` | | Failing construction | `throw` (invisible in the type) | Return `Result<Self, E>` (visible in the type) | | “Zero value” factory | Ad hoc | The standard `Default` trait, often derived | The conceptual headline: **TypeScript bakes construction into the language (`new` + `constructor`); Rust treats construction as just another function.** That sounds like extra work, and it is a little — but it pays off. There is no magic allocation step, fallible construction is expressed in the type system instead of via exceptions, and a type can have *as many* named constructors as it wants (`new`, `guest`, `from_fahrenheit`, …) instead of being limited to one overloaded `constructor`. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Calling an associated function on a value with `.` [Section titled “Pitfall 1: Calling an associated function on a value with .”](#pitfall-1-calling-an-associated-function-on-a-value-with-) Coming from TypeScript, where `instance.staticMethod()` sometimes “works” by accident, it is tempting to call `new` (or any associated function) on an existing value. ```rust 1 struct Point { 2 x: i32, 3 y: i32, 4 } 5 6 impl Point { 7 fn origin() -> Self { 8 Self { x: 0, y: 0 } 9 } 10 } 11 12 fn main() { 13 let p = Point::origin(); 14 // `origin` has no `self`, so it must be called on the TYPE, not a value: 15 let q = p.origin(); // does not compile (error[E0599]) 16 println!("{} {}", q.x, q.y); 17 } ``` The real compiler error points you straight at the fix: ```text 1 error[E0599]: no method named `origin` found for struct `Point` in the current scope 2 --> src/main.rs:15:15 3 | 4 1 | struct Point { 5 | ------------ method `origin` not found for this struct 6 ... 7 15 | let q = p.origin(); // does not compile (error[E0599]) 8 | --^^^^^^-- 9 | | | 10 | | this is an associated function, not a method 11 | help: use associated function syntax instead: `Point::origin()` 12 | 13 = note: found the following associated functions; to be used as methods, functions must have a `self` parameter ``` **Fix:** call it on the type, `Point::origin()`. The note even spells out the rule: to be callable as a method, a function must have a `self` parameter. ### Pitfall 2: Trying to use `self` inside an associated function [Section titled “Pitfall 2: Trying to use self inside an associated function”](#pitfall-2-trying-to-use-self-inside-an-associated-function) If you reach for `self` in a function that has no `self` parameter, there is nothing for it to refer to. ```rust 1 struct Counter { 2 count: u32, 3 } 4 5 impl Counter { 6 fn new() -> Self { 7 // An associated function has no `self` in scope. 8 Self { count: self.count } // does not compile (error[E0424]) 9 } 10 } 11 12 fn main() { 13 let _c = Counter::new(); 14 } ``` The real compiler error: ```text 1 error[E0424]: expected value, found module `self` 2 --> src/main.rs:8:23 3 | 4 6 | fn new() -> Self { 5 | --- this function doesn't have a `self` parameter 6 7 | // An associated function has no `self` in scope. 7 8 | Self { count: self.count } // does not compile (error[E0424]) 8 | ^^^^ `self` value is a keyword only available in methods with a `self` parameter ``` **Fix:** an associated function builds a value from scratch (or from its arguments): `Self { count: 0 }`. If you genuinely need access to an existing instance, you wanted a *method*, so add a `self` receiver and call it on a value. ### Pitfall 3: Assuming a `new` exists by default [Section titled “Pitfall 3: Assuming a new exists by default”](#pitfall-3-assuming-a-new-exists-by-default) There is no automatically generated constructor. If you never wrote `new`, `Type::new(...)` does not exist. ```rust 1 #[derive(Debug)] 2 struct Point { 3 x: i32, 4 y: i32, 5 } 6 7 // No `impl` block defines `new`, so `Point::new` does not exist. 8 9 fn main() { 10 let p = Point::new(1, 2); // does not compile (error[E0599]) 11 println!("{p:?}"); 12 } ``` The real compiler error: ```text 1 error[E0599]: no function or associated item named `new` found for struct `Point` in the current scope 2 --> src/main.rs:10:20 3 | 4 2 | struct Point { 5 | ------------ function or associated item `new` not found for this struct 6 ... 7 10 | let p = Point::new(1, 2); // does not compile (error[E0599]) 8 | ^^^ function or associated item not found in `Point` ``` **Fix:** either construct it with struct literal syntax — `Point { x: 1, y: 2 }` — or write your own `fn new(x: i32, y: i32) -> Self`. Unlike TypeScript, omitting a constructor gives you *no* constructor, not an implicit empty one. ### Pitfall 4: Making `new` fallible by panicking instead of returning `Result` [Section titled “Pitfall 4: Making new fallible by panicking instead of returning Result”](#pitfall-4-making-new-fallible-by-panicking-instead-of-returning-result) It is tempting to write `fn new(...) -> Self` and `panic!` on bad input, mirroring a TypeScript constructor that `throw`s. That hides the failure from the caller’s type signature and turns a recoverable problem into a crash. If construction can legitimately fail on caller-supplied data, return `Result<Self, E>` from a `try_new`/`parse`/`from_*` function instead (see [Section 08](/08-error-handling/)). Reserve panicking for cases that indicate a programmer bug, not bad input. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Name your primary constructor `new`.** It is the universal convention; readers expect `Type::new(...)` to be the no-frills way to build a value. Don’t invent `create`/`make` unless `new` would be ambiguous. * **Return `Self`, not the spelled-out type.** Write `-> Self` and `Self { ... }`. It is idiomatic and survives renames. * **Use named alternative constructors freely.** `from_fahrenheit`, `with_capacity`, `guest`, `parse` — Rust has no constructor overloading, so multiple well-named associated functions are the idiomatic substitute. Follow the `from_*` convention when building from a single other value. * **Make fallible construction return `Result`.** Express “this can fail on bad input” in the type, not via panics. Keep `new` infallible; add `try_new` (or a parse-style function) for the checked path. * **Derive `Default` for “all-zero” construction.** If a sensible empty/zero value exists, `#[derive(Default)]` gives callers `Type::default()` and plugs into the wider ecosystem. Have `new()` delegate to `Self::default()` when they coincide. * **Reach for the builder pattern when a constructor has many optional parameters.** Rust has no named or default arguments, so a six-argument `new(...)` quickly becomes unreadable. A builder (below) is the idiomatic replacement. * **Privacy makes constructors load-bearing.** When a struct’s fields are private to its module, outside code *cannot* use struct-literal syntax — your `new`/`try_new` becomes the only entry point, letting you enforce invariants. See [Section 12](/12-modules-packages/) for visibility. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) When a type has many optional settings, a single `new(...)` with a long argument list is painful. Rust has no default or named arguments, so callers must pass *everything* in order. The idiomatic answer is the **builder pattern**: an associated function returns a builder, fluent methods configure it, and a final `build()` produces the immutable value. This is the production shape of the chaining teaser from [Methods and `impl` Blocks](/06-data-structures/05-impl-blocks/). The associated function `HttpRequest::builder(...)` is the entry point; the rest of the API hangs off it. ```rust 1 #[derive(Debug)] 2 struct HttpRequest { 3 url: String, 4 method: String, 5 headers: Vec<(String, String)>, 6 body: Option<String>, 7 timeout_ms: u64, 8 } 9 10 // The builder holds the in-progress configuration. 11 #[derive(Debug)] 12 struct HttpRequestBuilder { 13 url: String, 14 method: String, 15 headers: Vec<(String, String)>, 16 body: Option<String>, 17 timeout_ms: u64, 18 } 19 20 impl HttpRequest { 21 // Associated function: the single entry point into the builder. 22 // Returns the BUILDER, not a finished HttpRequest. 23 fn builder(url: &str) -> HttpRequestBuilder { 24 HttpRequestBuilder { 25 url: url.to_string(), 26 method: String::from("GET"), 27 headers: Vec::new(), 28 body: None, 29 timeout_ms: 30_000, 30 } 31 } 32 } 33 34 impl HttpRequestBuilder { 35 // Each step takes `mut self` by value, mutates, and returns Self, 36 // so calls chain. (Ownership flows through the chain.) 37 fn method(mut self, method: &str) -> Self { 38 self.method = method.to_string(); 39 self 40 } 41 42 fn header(mut self, key: &str, value: &str) -> Self { 43 self.headers.push((key.to_string(), value.to_string())); 44 self 45 } 46 47 fn body(mut self, body: &str) -> Self { 48 self.body = Some(body.to_string()); 49 self 50 } 51 52 fn timeout_ms(mut self, ms: u64) -> Self { 53 self.timeout_ms = ms; 54 self 55 } 56 57 // Consumes the builder, producing the finished, immutable request. 58 fn build(self) -> HttpRequest { 59 HttpRequest { 60 url: self.url, 61 method: self.method, 62 headers: self.headers, 63 body: self.body, 64 timeout_ms: self.timeout_ms, 65 } 66 } 67 } 68 69 fn main() { 70 let request = HttpRequest::builder("https://api.example.com/users") 71 .method("POST") 72 .header("Content-Type", "application/json") 73 .header("Authorization", "Bearer token123") 74 .body(r#"{"name":"Alice"}"#) 75 .timeout_ms(5_000) 76 .build(); 77 78 println!("{} {}", request.method, request.url); 79 for (key, value) in &request.headers { 80 println!(" {key}: {value}"); 81 } 82 if let Some(body) = &request.body { 83 println!(" body: {body}"); 84 } 85 println!(" timeout: {}ms", request.timeout_ms); 86 } ``` Output: ```text 1 POST https://api.example.com/users 2 Content-Type: application/json 3 Authorization: Bearer token123 4 body: {"name":"Alice"} 5 timeout: 5000ms ``` This reads almost exactly like a TypeScript fluent builder that returns `this`, with one Rust twist: each step takes `self` *by value* and hands it back, so ownership flows down the chain and `build()` consumes the builder at the end; the builder cannot be reused afterward. Defaults (`GET`, empty headers, `30_000`ms) live in `builder()`, and callers only override what they care about, in any order. That is exactly the ergonomics named/default arguments give you in TypeScript, reconstructed from associated functions and ownership. > **Note:** For real builders you usually pair this with `#[derive(Default)]` on the builder and a `build()` that returns `Result` when required fields might be missing. Mature crates often generate the whole thing with the [`derive_builder`](https://docs.rs/derive_builder) or [`bon`](https://docs.rs/bon) crate. The hand-written version here shows what those macros expand to. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book - Associated Functions](https://doc.rust-lang.org/book/ch05-03-method-syntax.html#associated-functions) * [Rust by Example - Associated functions & Methods](https://doc.rust-lang.org/rust-by-example/fn/methods.html) * [`std::default::Default`](https://doc.rust-lang.org/std/default/trait.Default.html) * [Rust API Guidelines - Constructors are static, inherent methods (`new`)](https://rust-lang.github.io/api-guidelines/predictability.html#constructors-are-static-inherent-methods-c-ctor) * [Rust Design Patterns - Builder](https://rust-unofficial.github.io/patterns/patterns/creational/builder.html) ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Structs](/06-data-structures/00-structs/) — the struct-literal syntax a constructor wraps * [Methods and `impl` Blocks](/06-data-structures/05-impl-blocks/) — associated functions’ counterpart: functions *with* `self` * [Field Init Shorthand](/06-data-structures/08-field-init-shorthand/) — `Self { id, name }` shorthand and `..other` update syntax used inside constructors * [Associated Types & Consts](/06-data-structures/07-associated-types/) — other items that live inside an `impl` block * [Tuple Structs](/06-data-structures/01-tuple-structs/) — newtypes whose validated `try_new` is a classic associated function * [Ownership](/05-ownership/) — why each builder step takes and returns `self` * [Variables and Mutability](/02-basics/00-variables/) — `mut self` in builder steps * [Error Handling](/08-error-handling/) — fallible constructors returning `Result` * [Collections](/07-collections/) — `Vec::new` and `Vec::with_capacity` are associated functions you already use *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Multiple constructors for a `Duration` [Section titled “Exercise 1: Multiple constructors for a Duration”](#exercise-1-multiple-constructors-for-a-duration) **Difficulty:** Easy **Objective:** Write a primary `new` constructor plus named alternative constructors. **Instructions:** Complete the `impl` block so that `Duration::new(seconds)` stores the seconds directly, while `Duration::from_minutes` and `Duration::from_hours` convert to seconds. All three are associated functions returning `Self`. ```rust 1 #[derive(Debug)] 2 struct Duration { 3 seconds: u64, 4 } 5 6 impl Duration { 7 fn new(seconds: u64) -> Self { 8 // TODO 9 } 10 11 fn from_minutes(minutes: u64) -> Self { 12 // TODO: 1 minute = 60 seconds 13 } 14 15 fn from_hours(hours: u64) -> Self { 16 // TODO: 1 hour = 3600 seconds 17 } 18 } 19 20 fn main() { 21 let a = Duration::new(90); 22 let b = Duration::from_minutes(2); 23 let c = Duration::from_hours(1); 24 println!("{}", a.seconds); // 90 25 println!("{}", b.seconds); // 120 26 println!("{}", c.seconds); // 3600 27 } ``` Solution ```rust 1 #[derive(Debug)] 2 struct Duration { 3 seconds: u64, 4 } 5 6 impl Duration { 7 fn new(seconds: u64) -> Self { 8 Self { seconds } 9 } 10 11 fn from_minutes(minutes: u64) -> Self { 12 Self { seconds: minutes * 60 } 13 } 14 15 fn from_hours(hours: u64) -> Self { 16 Self { seconds: hours * 3600 } 17 } 18 } 19 20 fn main() { 21 let a = Duration::new(90); 22 let b = Duration::from_minutes(2); 23 let c = Duration::from_hours(1); 24 println!("{}", a.seconds); // 90 25 println!("{}", b.seconds); // 120 26 println!("{}", c.seconds); // 3600 27 } ``` None of these take `self`; they are associated functions, called on the type with `::`. Where TypeScript would force you into one overloaded `constructor` (or several `static` factories), Rust treats each named constructor as an ordinary function returning `Self`. ### Exercise 2: A validated constructor that returns `Result` [Section titled “Exercise 2: A validated constructor that returns Result”](#exercise-2-a-validated-constructor-that-returns-result) **Difficulty:** Medium **Objective:** Write a fallible constructor that rejects bad input via the type system instead of panicking. **Instructions:** Complete `Username::try_new` so it trims whitespace, rejects an empty name with `"username cannot be empty"`, rejects names longer than 20 characters with `"username too long: N chars"` (where `N` is the length), and otherwise returns `Ok(Username(...))`. ```rust 1 #[derive(Debug)] 2 struct Username(String); 3 4 impl Username { 5 fn try_new(raw: &str) -> Result<Self, String> { 6 // TODO: trim, validate, return Ok(...) or Err(...) 7 } 8 } 9 10 fn main() { 11 for raw in [" alice ", "", "this_name_is_definitely_way_too_long"] { 12 match Username::try_new(raw) { 13 Ok(u) => println!("ok: {u:?}"), 14 Err(e) => println!("rejected {raw:?}: {e}"), 15 } 16 } 17 } ``` Solution ```rust 1 #[derive(Debug)] 2 struct Username(String); 3 4 impl Username { 5 fn try_new(raw: &str) -> Result<Self, String> { 6 let trimmed = raw.trim(); 7 if trimmed.is_empty() { 8 return Err(String::from("username cannot be empty")); 9 } 10 if trimmed.len() > 20 { 11 return Err(format!("username too long: {} chars", trimmed.len())); 12 } 13 Ok(Self(trimmed.to_string())) 14 } 15 } 16 17 fn main() { 18 for raw in [" alice ", "", "this_name_is_definitely_way_too_long"] { 19 match Username::try_new(raw) { 20 Ok(u) => println!("ok: {u:?}"), 21 Err(e) => println!("rejected {raw:?}: {e}"), 22 } 23 } 24 } ``` Output: ```text 1 ok: Username("alice") 2 rejected "": username cannot be empty 3 rejected "this_name_is_definitely_way_too_long": username too long: 36 chars ``` Returning `Result<Self, String>` makes the possibility of failure part of the signature; callers cannot ignore it, unlike a TypeScript constructor that silently `throw`s. `Self(...)` is the tuple-struct construction shorthand for `Username(...)`. ### Exercise 3: A small builder [Section titled “Exercise 3: A small builder”](#exercise-3-a-small-builder) **Difficulty:** Medium/Hard **Objective:** Build the builder pattern from scratch, starting with an associated `builder()` entry point. **Instructions:** Give `Pizza` an associated function `builder(size)` that returns a `PizzaBuilder` (default: no toppings, no extra cheese). On `PizzaBuilder`, add chainable `topping(name)` (appends) and `extra_cheese()` (sets the flag), each taking `mut self` and returning `Self`, plus a `build()` that consumes the builder and returns a `Pizza`. Make the `main` below compile and run. ```rust 1 #[derive(Debug)] 2 struct Pizza { 3 size: String, 4 toppings: Vec<String>, 5 extra_cheese: bool, 6 } 7 8 #[derive(Debug)] 9 struct PizzaBuilder { 10 // TODO: same fields as Pizza 11 } 12 13 // impl Pizza { fn builder(size: &str) -> PizzaBuilder { ... } } 14 // impl PizzaBuilder { topping / extra_cheese / build } 15 16 fn main() { 17 let pizza = Pizza::builder("large") 18 .topping("mushroom") 19 .topping("olive") 20 .extra_cheese() 21 .build(); 22 23 println!("{} pizza, extra cheese: {}", pizza.size, pizza.extra_cheese); 24 println!("toppings: {:?}", pizza.toppings); 25 } ``` Solution ```rust 1 #[derive(Debug)] 2 struct Pizza { 3 size: String, 4 toppings: Vec<String>, 5 extra_cheese: bool, 6 } 7 8 #[derive(Debug)] 9 struct PizzaBuilder { 10 size: String, 11 toppings: Vec<String>, 12 extra_cheese: bool, 13 } 14 15 impl Pizza { 16 fn builder(size: &str) -> PizzaBuilder { 17 PizzaBuilder { 18 size: size.to_string(), 19 toppings: Vec::new(), 20 extra_cheese: false, 21 } 22 } 23 } 24 25 impl PizzaBuilder { 26 fn topping(mut self, name: &str) -> Self { 27 self.toppings.push(name.to_string()); 28 self 29 } 30 31 fn extra_cheese(mut self) -> Self { 32 self.extra_cheese = true; 33 self 34 } 35 36 fn build(self) -> Pizza { 37 Pizza { 38 size: self.size, 39 toppings: self.toppings, 40 extra_cheese: self.extra_cheese, 41 } 42 } 43 } 44 45 fn main() { 46 let pizza = Pizza::builder("large") 47 .topping("mushroom") 48 .topping("olive") 49 .extra_cheese() 50 .build(); 51 52 println!("{} pizza, extra cheese: {}", pizza.size, pizza.extra_cheese); 53 println!("toppings: {:?}", pizza.toppings); 54 } ``` Output: ```text 1 large pizza, extra cheese: true 2 toppings: ["mushroom", "olive"] ``` `Pizza::builder(...)` is the associated-function entry point and returns the *builder*, not a `Pizza`. Each configuration step takes `mut self` and returns it so calls chain; `build()` takes `self` by value, consuming the builder to hand back the finished `Pizza`. This is the idiomatic stand-in for TypeScript’s optional/named arguments. # Associated Types and Associated Constants > Associated types and constants let a Rust trait name one implementer-chosen type or value, a more constrained tool than the generic parameters TypeScript uses. When a trait needs to refer to a type or a constant that *the implementer gets to choose*, Rust offers two tools that have no direct TypeScript equivalent: **associated types** and **associated constants**. This file is a light, practical introduction aimed at recognizing the syntax (`type Item;`, `Self::Item`, `const NAME: ...`) and knowing why it exists. The full, deep treatment (including where associated types beat generic parameters and how they interact with bounds) lives in [Section 09 — Generics and Traits](/09-generics-traits/). *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) An **associated type** is a placeholder type declared inside a trait (`type Item;`) that each implementer fills in (`type Item = i32;`). It lets a trait talk about “some related type” without that type being a generic parameter the caller has to spell out. The most famous example is the standard library’s `Iterator`, whose `type Item` is “what each call to `next` produces.” An **associated constant** is the same idea for a value: a constant (`const MAX: Self;` or `const NAME: &'static str;`) attached to a trait or a type, where each implementer supplies the value. Rust’s own `u8::MAX`, `i32::MAX`, and friends are associated constants. **The point for a TypeScript/JavaScript developer:** TypeScript has no built-in concept of “a type the implementer chooses, named once and reused across the trait’s methods.” You normally fake it with a generic type parameter (`interface Container<Item>`). Associated types are a *different, more constrained* mechanism: there is exactly **one** choice per implementing type, and that single choice ties all of a trait’s methods together. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript, when an interface needs to refer to “the element type,” you reach for a **generic type parameter**: ```typescript 1 // TypeScript: the element type is a generic parameter on the interface. 2 interface Container<Item> { 3 get(index: number): Item | undefined; 4 first(): Item | undefined; 5 } 6 7 class IntStack implements Container<number> { 8 constructor(private items: number[]) {} 9 10 get(index: number): number | undefined { 11 return this.items[index]; 12 } 13 first(): number | undefined { 14 return this.get(0); 15 } 16 } 17 18 const s = new IntStack([10, 20, 30]); 19 console.log(s.get(0)); // 10 20 console.log(s.get(9)); // undefined ``` This works, but notice two things. First, `Item` is *open*: nothing stops you from writing a class that implements `Container<number>` **and** `Container<string>` at the same time. TypeScript is perfectly happy with `class X implements Container<number>, Container<string>`. Second, because TypeScript generics are **erased at runtime**, `Item` is purely a compile-time fiction; there is no `Item` value or type to inspect once the code runs. For a constant-shared-across-a-contract, TypeScript developers usually fall back to a `static readonly` field or a module-level `const`; there is no first-class “every implementer must provide this constant, and the trait’s methods can reference it” feature. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust offers the generic-parameter style too, but the *idiomatic* choice for “one element type per implementer” is an **associated type**: ```rust 1 trait Container { 2 type Item; // associated type: the implementer decides what this is 3 4 fn get(&self, index: usize) -> Option<&Self::Item>; 5 6 // A default method can already use Self::Item before it is known. 7 fn first(&self) -> Option<&Self::Item> { 8 self.get(0) 9 } 10 } 11 12 struct IntStack { 13 items: Vec<i32>, 14 } 15 16 impl Container for IntStack { 17 type Item = i32; // fill in the placeholder, exactly once 18 fn get(&self, index: usize) -> Option<&i32> { 19 self.items.get(index) 20 } 21 } 22 23 struct StringStack { 24 items: Vec<String>, 25 } 26 27 impl Container for StringStack { 28 type Item = String; 29 fn get(&self, index: usize) -> Option<&String> { 30 self.items.get(index) 31 } 32 } 33 34 fn main() { 35 let ints = IntStack { items: vec![10, 20, 30] }; 36 let names = StringStack { 37 items: vec!["ada".to_string(), "linus".to_string()], 38 }; 39 40 println!("{:?}", ints.first()); // Some(10) 41 println!("{:?}", names.first()); // Some("ada") 42 println!("{:?}", ints.get(5)); // None 43 } ``` Real output: ```text 1 Some(10) 2 Some("ada") 3 None ``` For the constant side, here is the associated-const counterpart: both the inherent kind (attached directly to a type via an `impl` block) and the trait kind. ```rust 1 // (1) An inherent associated const: lives on the type itself. 2 struct Circle { 3 radius: f64, 4 } 5 6 impl Circle { 7 const PI: f64 = 3.14159265358979; 8 9 fn area(&self) -> f64 { 10 Self::PI * self.radius * self.radius 11 } 12 } 13 14 // (2) An associated const declared on a trait, with a default value. 15 trait Animal { 16 const LEGS: u32 = 4; // default 17 fn legs(&self) -> u32 { 18 Self::LEGS 19 } 20 } 21 22 struct Dog; 23 struct Bird; 24 25 impl Animal for Dog {} // takes the default 4 26 impl Animal for Bird { 27 const LEGS: u32 = 2; // overrides the default 28 } 29 30 fn main() { 31 let c = Circle { radius: 2.0 }; 32 println!("area = {:.2}", c.area()); // area = 12.57 33 println!("PI = {}", Circle::PI); // reachable through the type 34 35 println!("dog legs {}", Dog.legs()); // 4 36 println!("bird legs {}", Bird.legs()); // 2 37 38 // The standard library uses associated consts heavily: 39 println!("u8::MAX = {}", u8::MAX); // 255 40 } ``` Real output: ```text 1 area = 12.57 2 PI = 3.14159265358979 3 dog legs 4 4 bird legs 2 5 u8::MAX = 255 ``` *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Associated types, line by line [Section titled “Associated types, line by line”](#associated-types-line-by-line) ```rust 1 trait Container { 2 type Item; 3 fn get(&self, index: usize) -> Option<&Self::Item>; 4 } ``` * `type Item;` declares an **associated type**, a named, implementer-chosen type. It is a *placeholder*: the trait does not know yet whether `Item` is an `i32`, a `String`, or anything else. * `Self::Item` is how the trait’s methods *refer* to that placeholder. `Self` is “whatever concrete type is implementing this trait,” and `Self::Item` is “that type’s choice of `Item`.” (Read more about `Self` in [Associated Functions](/06-data-structures/06-associated-functions/).) * In the `impl`, `type Item = i32;` is the moment the placeholder is filled in. From then on, for `IntStack`, `Self::Item` *is* `i32`, so `get` can return `Option<&i32>`. The payoff is that the method signatures stay clean. `get` returns `Option<&Self::Item>` and never has to repeat `<Item>` anywhere, and the default `first` method can already be written against `Self::Item` even though no implementer exists yet. > **Note:** You write `Self::Item` inside the trait and inside `impl` blocks. From *outside*, you name it as `<IntStack as Container>::Item` (the fully-qualified form) or, far more often, you never name it at all — you let inference do the work. ### Naming an associated type in a function bound [Section titled “Naming an associated type in a function bound”](#naming-an-associated-type-in-a-function-bound) The everyday place a TypeScript developer meets associated-type syntax is in a generic bound. To say “any `Container` whose `Item` is `i32`,” you write `Container<Item = i32>`: ```rust 1 trait Container { 2 type Item; 3 fn get(&self, index: usize) -> Option<&Self::Item>; 4 } 5 6 struct IntStack { items: Vec<i32> } 7 impl Container for IntStack { 8 type Item = i32; 9 fn get(&self, index: usize) -> Option<&i32> { self.items.get(index) } 10 } 11 12 // Accept any Container whose Item is i32. 13 fn print_first<C: Container<Item = i32>>(c: &C) { 14 match c.get(0) { 15 Some(x) => println!("first = {x}"), 16 None => println!("empty"), 17 } 18 } 19 20 // Fully generic over the Item too. 21 fn count_present<C: Container>(c: &C, upto: usize) -> usize { 22 (0..upto).filter(|&i| c.get(i).is_some()).count() 23 } 24 25 fn main() { 26 let s = IntStack { items: vec![7, 8, 9] }; 27 print_first(&s); // first = 7 28 println!("{}", count_present(&s, 10)); // 3 29 } ``` Real output: ```text 1 first = 7 2 3 ``` That `Container<Item = i32>` syntax looks like passing a generic argument, but the `Item =` part makes it clear you are *constraining the associated type*, not supplying a normal type parameter. You see it constantly with iterators. `impl Iterator<Item = i32>` means “some iterator that yields `i32`s”: ```rust 1 fn sum_doubled(it: impl Iterator<Item = i32>) -> i32 { 2 it.map(|x| x * 2).sum() 3 } 4 5 fn main() { 6 let v = vec![1, 2, 3]; 7 // v.iter() yields &i32; .copied() turns it into an i32 iterator. 8 println!("{}", sum_doubled(v.iter().copied())); // 12 9 } ``` Real output: ```text 1 12 ``` ### The canonical example: `Iterator` [Section titled “The canonical example: Iterator”](#the-canonical-example-iterator) Nearly every Rust program uses associated types, because `Iterator` is built on one: ```rust 1 struct Counter { 2 count: u32, 3 max: u32, 4 } 5 6 impl Iterator for Counter { 7 type Item = u32; // each next() yields a u32 8 9 fn next(&mut self) -> Option<Self::Item> { 10 if self.count < self.max { 11 self.count += 1; 12 Some(self.count) 13 } else { 14 None 15 } 16 } 17 } 18 19 fn main() { 20 let counter = Counter { count: 0, max: 5 }; 21 let collected: Vec<u32> = counter.collect(); 22 println!("{collected:?}"); // [1, 2, 3, 4, 5] 23 24 // Because Item is fixed, the whole adapter chain knows the element type. 25 let sum: u32 = Counter { count: 0, max: 5 }.map(|n| n * 2).sum(); 26 println!("{sum}"); // 30 27 } ``` Real output: ```text 1 [1, 2, 3, 4, 5] 2 30 ``` Why is `Item` an associated type and not a generic parameter? Because a given iterator yields **exactly one** kind of element. A `Counter` always yields `u32`; it makes no sense for it to *also* be a `u32`-or-`String` iterator. Associated types encode “there is one right answer per type,” which is exactly the situation here. (Contrast that with the `From<T>` trait, where one type can sensibly convert *from* many source types, so `From` uses a generic parameter, not an associated type.) ### Associated constants, line by line [Section titled “Associated constants, line by line”](#associated-constants-line-by-line) ```rust 1 trait Animal { 2 const LEGS: u32 = 4; // default value 3 fn legs(&self) -> u32 { Self::LEGS } 4 } ``` * `const LEGS: u32 = 4;` declares an **associated constant** with a default. Implementers may accept the default or override it with `const LEGS: u32 = 2;`. * `Self::LEGS` references the implementer’s value, the same way `Self::Item` references the implementer’s type. * An *inherent* associated const (like `Circle::PI` above) is even simpler: it is just a `const` written inside an `impl` block, namespaced under the type. It is reached as `Circle::PI`. The standard library leans on associated constants for numeric limits: `i32::MAX`, `u8::MAX`, `f64::EPSILON`, `char::MAX`, and so on are all associated consts. In TypeScript the closest analog is `Number.MAX_SAFE_INTEGER`, a static property on a built-in, but Rust’s version is generic-aware: a function bounded by a trait can write `T::MAX` and get the right constant for whatever `T` turns out to be. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript | Rust | | ------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | | ”Type the implementer picks” | Generic parameter: `interface Container<Item>` | Associated type: `type Item;` (idiomatic) **or** a generic parameter | | How many choices per implementer | Many — a class can implement `Container<number>` and `Container<string>` | Exactly **one** for an associated type; many for a generic parameter | | Caller has to name it? | Yes — `Container<number>` | No — inferred; named only when constraining, as `Container<Item = number>` | | Runtime presence | Erased; purely compile-time | Resolved at compile time via monomorphization, but the chosen type is real and concrete | | ”Constant every implementer provides” | No first-class feature; use `static readonly` / module `const` | Associated constant: `const MAX: Self;` on a trait, or `const PI` in an `impl` | | Famous standard-library use | `Array<T>`, `Map<K, V>` (generic params) | `Iterator::Item`, `i32::MAX` (associated type + const) | ### Associated type vs. generic parameter: the one-paragraph rule [Section titled “Associated type vs. generic parameter: the one-paragraph rule”](#associated-type-vs-generic-parameter-the-one-paragraph-rule) Use an **associated type** when each implementing type has a *single, canonical* answer (an iterator’s element type, a parser’s output type, a repository’s key type). Use a **generic trait parameter** when one type can reasonably implement the trait *many ways* (converting `From<i32>` and `From<&str>` into the same target). The compiler enforces this difference: an associated-type trait can be implemented for a type only once, whereas a generic trait can be implemented many times for the same type. The next two examples make that concrete. A **generic** trait — implementable many times for one type: ```rust 1 trait Producer<Output> { 2 fn produce(&self) -> Output; 3 } 4 5 struct Factory; 6 7 impl Producer<i32> for Factory { 8 fn produce(&self) -> i32 { 1 } 9 } 10 11 impl Producer<String> for Factory { 12 fn produce(&self) -> String { "x".to_string() } 13 } 14 15 fn main() { 16 let f = Factory; 17 let n: i32 = f.produce(); 18 let s: String = f.produce(); 19 println!("{n} {s}"); // 1 x 20 } ``` Real output: ```text 1 1 x ``` The equivalent **associated-type** trait *cannot* be implemented twice for `Factory`. See the first pitfall below for the exact compiler error. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Trying to implement an associated-type trait twice for one type [Section titled “Pitfall 1: Trying to implement an associated-type trait twice for one type”](#pitfall-1-trying-to-implement-an-associated-type-trait-twice-for-one-type) A TypeScript developer used to `implements A<number>, A<string>` will reach for the same trick in Rust and hit a wall: ```rust 1 trait Producer { 2 type Output; 3 fn produce(&self) -> Self::Output; 4 } 5 6 struct Factory; 7 8 impl Producer for Factory { 9 type Output = i32; 10 fn produce(&self) -> i32 { 1 } 11 } 12 13 impl Producer for Factory { // does not compile (error[E0119]) 14 type Output = String; 15 fn produce(&self) -> String { "x".to_string() } 16 } 17 18 fn main() {} ``` The real error: ```text 1 error[E0119]: conflicting implementations of trait `Producer` for type `Factory` 2 --> src/main.rs:13:1 3 | 4 8 | impl Producer for Factory { 5 | ------------------------- first implementation here 6 ... 7 13 | impl Producer for Factory { // does not compile (error[E0119]) 8 | ^^^^^^^^^^^^^^^^^^^^^^^^^ conflicting implementation for `Factory` ``` > **Tip:** If you genuinely need many implementations for the same type, you wanted a *generic* trait (`trait Producer<Output>`), not an associated type. If you only ever need one, the associated type is the right, cleaner choice. ### Pitfall 2: Forgetting to fill in the associated type in the `impl` [Section titled “Pitfall 2: Forgetting to fill in the associated type in the impl”](#pitfall-2-forgetting-to-fill-in-the-associated-type-in-the-impl) The `type Item = ...;` line is mandatory; leaving it out is the same kind of error as forgetting to implement a method: ```rust 1 trait Container { 2 type Item; 3 fn get(&self) -> Option<&Self::Item>; 4 } 5 6 struct Bag { v: Vec<i32> } 7 8 impl Container for Bag { // does not compile (error[E0046]) 9 // forgot: type Item = i32; 10 fn get(&self) -> Option<&i32> { self.v.first() } 11 } 12 13 fn main() {} ``` The real error: ```text 1 error[E0046]: not all trait items implemented, missing: `Item` 2 --> src/main.rs:8:1 3 | 4 2 | type Item; 5 | --------- `Item` from trait 6 ... 7 8 | impl Container for Bag { // does not compile (error[E0046]) 8 | ^^^^^^^^^^^^^^^^^^^^^^ missing `Item` in implementation ``` ### Pitfall 3: Using a trait with an associated type as a trait object without naming the type [Section titled “Pitfall 3: Using a trait with an associated type as a trait object without naming the type”](#pitfall-3-using-a-trait-with-an-associated-type-as-a-trait-object-without-naming-the-type) You can turn many traits into trait objects (`&dyn Trait`), but if the trait has an associated type, the object form is ambiguous until you pin the type down: ```rust 1 trait Container { 2 type Item; 3 fn get(&self) -> Option<&Self::Item>; 4 } 5 6 fn take(_c: &dyn Container) {} // does not compile (error[E0191]) 7 8 fn main() {} ``` The real error tells you exactly how to fix it: ```text 1 error[E0191]: the value of the associated type `Item` in `Container` must be specified 2 --> src/main.rs:6:18 3 | 4 2 | type Item; 5 | --------- `Item` defined here 6 ... 7 6 | fn take(_c: &dyn Container) {} // does not compile (error[E0191]) 8 | ^^^^^^^^^ help: specify the associated type: `Container<Item = Type>` ``` The fix is `&dyn Container<Item = i32>` (or whatever concrete `Item` you mean). Trait objects and `dyn` are covered in [Section 09](/09-generics-traits/) and [Section 10 — Smart Pointers](/10-smart-pointers/). ### Pitfall 4: Expecting an associated const to be mutable or computed at runtime [Section titled “Pitfall 4: Expecting an associated const to be mutable or computed at runtime”](#pitfall-4-expecting-an-associated-const-to-be-mutable-or-computed-at-runtime) `const` means *compile-time constant*, not “a field with a default.” It is the same `const` you met in [Section 02](/02-basics/00-variables/): no heap allocation, no runtime initialization, evaluated at compile time. You cannot store a `String::from("...")` in an associated `const` (use `&'static str`), and you cannot reassign it. If you need per-instance, mutable data, that is a struct *field*, not an associated const. See [Structs](/06-data-structures/00-structs/). *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Default to an associated type when the answer is unique per implementer.** Iterator element types, parser output types, key/entity types in a storage abstraction all have one obvious answer per type, so an associated type keeps signatures clean and inference smooth. * **Reach for a generic trait parameter only when multiple implementations make sense** for a single type (the `From<T>` situation). When in doubt, start with an associated type; it is the more constrained, easier-to-read default. * **Name associated types in bounds with the `Trait<Assoc = T>` form**, e.g. `impl Iterator<Item = u32>`, rather than spelling out `<Concrete as Trait>::Item` unless you really need the fully-qualified syntax. * **Use associated constants for type-level limits and labels** (`const MAX`, `const NAME`) so generic code can reference `T::MAX` or `T::NAME`. Prefer `&'static str` for string constants. * **Lean on the standard library’s conventions.** Implementing `Iterator` (with `type Item`) for your own types gives you `map`, `filter`, `collect`, `sum`, and the rest for free, exactly as shown above. * This is an intentionally light tour. For when associated types pull their full weight (generic associated types, where-clauses involving `Self::Item`, and the design trade-offs against generic parameters), see [Section 09 — Generics and Traits](/09-generics-traits/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A storage-layer abstraction is a textbook case for associated types and consts: every repository stores **one** kind of entity, keyed **one** way, in **one** named collection. Encoding those as a generic parameter would force every caller to repeat them; as associated items they are decided once, by the implementer, and generic code can stay blissfully unaware of the specifics. ```rust 1 use std::collections::HashMap; 2 3 // Each repository decides what it stores (Entity), how rows are keyed (Key), 4 // and the collection name (NAME). All three are implementer-chosen, so they 5 // are associated items rather than generic parameters. 6 trait Repository { 7 type Key; 8 type Entity; 9 10 const NAME: &'static str; // associated const: the table/collection name 11 12 fn insert(&mut self, key: Self::Key, entity: Self::Entity); 13 fn find(&self, key: &Self::Key) -> Option<&Self::Entity>; 14 fn count(&self) -> usize; 15 } 16 17 #[derive(Debug, Clone)] 18 struct User { 19 name: String, 20 email: String, 21 } 22 23 struct UserRepo { 24 rows: HashMap<u64, User>, 25 } 26 27 impl UserRepo { 28 fn new() -> Self { 29 UserRepo { rows: HashMap::new() } 30 } 31 } 32 33 impl Repository for UserRepo { 34 type Key = u64; 35 type Entity = User; 36 37 const NAME: &'static str = "users"; 38 39 fn insert(&mut self, key: u64, entity: User) { 40 self.rows.insert(key, entity); 41 } 42 fn find(&self, key: &u64) -> Option<&User> { 43 self.rows.get(key) 44 } 45 fn count(&self) -> usize { 46 self.rows.len() 47 } 48 } 49 50 // Generic over ANY repository — names no concrete type, yet can read the 51 // associated const through the bound. 52 fn summarize<R: Repository>(repo: &R) -> String { 53 format!("{} rows in '{}'", repo.count(), R::NAME) 54 } 55 56 fn main() { 57 let mut users = UserRepo::new(); 58 users.insert(1, User { name: "Ada".into(), email: "ada@x.dev".into() }); 59 users.insert(2, User { name: "Linus".into(), email: "linus@x.dev".into() }); 60 61 println!("{}", summarize(&users)); // 2 rows in 'users' 62 63 match users.find(&1) { 64 Some(u) => println!("found {} <{}>", u.name, u.email), 65 None => println!("missing"), 66 } 67 println!("missing key -> {:?}", users.find(&99)); 68 } ``` Real output: ```text 1 2 rows in 'users' 2 found Ada <ada@x.dev> 3 missing key -> None ``` The `summarize` function is the heart of the example: it works for *every* repository, present and future, without knowing the key type, the entity type, or the collection name. It reads `R::NAME` (an associated const) and calls methods whose signatures use `Self::Key` and `Self::Entity` (associated types). A `ProductRepo` keyed by `String` and storing `Product` would slot in unchanged. > **Note:** The `HashMap` used here comes from the standard collections. See [Section 07 — Collections](/07-collections/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book - Advanced Traits: Associated Types](https://doc.rust-lang.org/book/ch20-02-advanced-traits.html#specifying-placeholder-types-in-trait-definitions-with-associated-types) * [Rust by Example - Associated Types](https://doc.rust-lang.org/rust-by-example/generics/assoc_items/types.html) * [Rust by Example - Associated Constants](https://doc.rust-lang.org/rust-by-example/custom_types/constants.html) * [Rust Reference - Associated Items](https://doc.rust-lang.org/reference/items/associated-items.html) * [`std::iter::Iterator`](https://doc.rust-lang.org/std/iter/trait.Iterator.html): the canonical associated-type trait ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Methods and `impl` Blocks](/06-data-structures/05-impl-blocks/) — where associated types and consts are written * [Associated Functions](/06-data-structures/06-associated-functions/) — `Self`, and methods without a receiver * [Enums](/06-data-structures/02-enums/) and [Option Enum](/06-data-structures/03-option-enum/): the `Option<&Self::Item>` returns used throughout this file * [Structs](/06-data-structures/00-structs/) — fields (per-instance, mutable data) vs. associated consts (type-level constants) * [Generics and Traits](/09-generics-traits/) — the full treatment: associated types vs. generic parameters, GATs, and bounds * [Smart Pointers](/10-smart-pointers/) — `dyn Trait` objects, including specifying associated types on them * [Collections](/07-collections/) — `HashMap` and the iterators that rely on `type Item` * [Variables and Mutability](/02-basics/00-variables/) — what `const` means in Rust *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Give a trait an associated constant [Section titled “Exercise 1: Give a trait an associated constant”](#exercise-1-give-a-trait-an-associated-constant) **Difficulty:** Easy **Objective:** Practice declaring and reading an associated constant. **Instructions:** Add an associated constant `SIDES` to the `Shape` trait so the generic `describe` function below prints the right number of sides. Implement it for both `Triangle` (3) and `Square` (4). ```rust 1 trait Shape { 2 // TODO: declare an associated const SIDES: u32 3 fn name(&self) -> &'static str; 4 } 5 6 struct Triangle; 7 struct Square; 8 9 // TODO: impl Shape for Triangle and Square 10 11 fn describe<S: Shape>(s: &S) -> String { 12 format!("a {} has {} sides", s.name(), /* ??? */) 13 } 14 15 fn main() { 16 println!("{}", describe(&Triangle)); // a triangle has 3 sides 17 println!("{}", describe(&Square)); // a square has 4 sides 18 } ``` Solution ```rust 1 trait Shape { 2 const SIDES: u32; 3 fn name(&self) -> &'static str; 4 } 5 6 struct Triangle; 7 struct Square; 8 9 impl Shape for Triangle { 10 const SIDES: u32 = 3; 11 fn name(&self) -> &'static str { "triangle" } 12 } 13 impl Shape for Square { 14 const SIDES: u32 = 4; 15 fn name(&self) -> &'static str { "square" } 16 } 17 18 fn describe<S: Shape>(s: &S) -> String { 19 format!("a {} has {} sides", s.name(), S::SIDES) 20 } 21 22 fn main() { 23 println!("{}", describe(&Triangle)); // a triangle has 3 sides 24 println!("{}", describe(&Square)); // a square has 4 sides 25 } ``` Output: ```text 1 a triangle has 3 sides 2 a square has 4 sides ``` ### Exercise 2: Implement `Iterator` with an associated type [Section titled “Exercise 2: Implement Iterator with an associated type”](#exercise-2-implement-iterator-with-an-associated-type) **Difficulty:** Medium **Objective:** Fill in the associated type and `next` method for a real standard-library trait. **Instructions:** Make `Fib` an iterator that yields Fibonacci numbers. Set `type Item` correctly and implement `next` so that `fib.take(10).collect::<Vec<_>>()` produces the first ten Fibonacci numbers starting from 0. ```rust 1 struct Fib { 2 a: u64, 3 b: u64, 4 } 5 6 impl Iterator for Fib { 7 // TODO: type Item = ? 8 fn next(&mut self) -> Option<Self::Item> { 9 // TODO: yield self.a, then advance the pair 10 } 11 } 12 13 fn main() { 14 let fib = Fib { a: 0, b: 1 }; 15 let first10: Vec<u64> = fib.take(10).collect(); 16 println!("{first10:?}"); // [0, 1, 1, 2, 3, 5, 8, 13, 21, 34] 17 } ``` Solution ```rust 1 struct Fib { 2 a: u64, 3 b: u64, 4 } 5 6 impl Iterator for Fib { 7 type Item = u64; 8 fn next(&mut self) -> Option<u64> { 9 let current = self.a; 10 self.a = self.b; 11 self.b = current + self.b; 12 Some(current) 13 } 14 } 15 16 fn main() { 17 let fib = Fib { a: 0, b: 1 }; 18 let first10: Vec<u64> = fib.take(10).collect(); 19 println!("{first10:?}"); // [0, 1, 1, 2, 3, 5, 8, 13, 21, 34] 20 } ``` Output: ```text 1 [0, 1, 1, 2, 3, 5, 8, 13, 21, 34] ``` > **Note:** `Fib` never returns `None`, so it is an *infinite* iterator. That is fine: `take(10)` stops pulling after ten elements, which is exactly why lazy iterators are useful. ### Exercise 3: A parser trait with both an associated type and an associated const [Section titled “Exercise 3: A parser trait with both an associated type and an associated const”](#exercise-3-a-parser-trait-with-both-an-associated-type-and-an-associated-const) **Difficulty:** Medium-Hard **Objective:** Combine an associated type (the parse result) and an associated constant (a label) in one trait, then write generic code over it. **Instructions:** Define a `Parser` trait with an associated `Output` type, an associated `LABEL: &'static str`, and a `parse(&self, &str) -> Result<Self::Output, String>` method. Implement it for `IntParser` (output `i64`, label `"integer"`) and `BoolParser` (output `bool`, label `"boolean"`). Then write a generic `run` function that returns `Result<P::Output, String>`. Errors should include the label. Solution ```rust 1 trait Parser { 2 type Output; 3 const LABEL: &'static str; 4 fn parse(&self, input: &str) -> Result<Self::Output, String>; 5 } 6 7 struct IntParser; 8 struct BoolParser; 9 10 impl Parser for IntParser { 11 type Output = i64; 12 const LABEL: &'static str = "integer"; 13 fn parse(&self, input: &str) -> Result<i64, String> { 14 input 15 .trim() 16 .parse::<i64>() 17 .map_err(|e| format!("{}: {e}", Self::LABEL)) 18 } 19 } 20 21 impl Parser for BoolParser { 22 type Output = bool; 23 const LABEL: &'static str = "boolean"; 24 fn parse(&self, input: &str) -> Result<bool, String> { 25 match input.trim() { 26 "true" | "1" => Ok(true), 27 "false" | "0" => Ok(false), 28 other => Err(format!("{}: not a bool: {other:?}", Self::LABEL)), 29 } 30 } 31 } 32 33 // Works for any Parser; the Output type is decided by the impl. 34 fn run<P: Parser>(p: &P, input: &str) -> Result<P::Output, String> { 35 p.parse(input) 36 } 37 38 fn main() { 39 println!("{:?}", run(&IntParser, " 42 ")); // Ok(42) 40 println!("{:?}", run(&IntParser, "oops")); // Err("integer: ...") 41 println!("{:?}", run(&BoolParser, "true")); // Ok(true) 42 println!("{:?}", run(&BoolParser, "maybe"));// Err("boolean: ...") 43 } ``` Output: ```text 1 Ok(42) 2 Err("integer: invalid digit found in string") 3 Ok(true) 4 Err("boolean: not a bool: \"maybe\"") ``` > **Tip:** `run`’s return type is `Result<P::Output, String>` — it names the associated type through the generic parameter `P` without ever mentioning `i64` or `bool`. That is associated types doing their job: the concrete type travels with the implementer. Error handling with `Result` is covered in [Section 08](/08-error-handling/). # Field Init Shorthand and Struct Update Syntax > Rust's field init shorthand mirrors TypeScript's { username } property shorthand, and struct update syntax (..other) echoes the spread, but ..other can move fields. In TypeScript you lean on **object property shorthand** (`{ username }`) and the **spread operator** (`{ ...base, port: 9090 }`) constantly to keep object construction terse. Rust has direct, named equivalents (**field init shorthand** and **struct update syntax**) but with one rule baked in that TypeScript never enforces: ownership. This page maps both conveniences across the two languages and shows exactly where the analogy holds and where it bites. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) When a local variable has the **same name** as a struct field, Rust lets you write just the name instead of `field: field`. This is **field init shorthand**. When you want a new struct value that is “mostly like an existing one but with a few fields changed,” **struct update syntax** (`..other`) fills in the remaining fields from another instance. They look almost exactly like TypeScript’s `{ username }` shorthand and `{ ...base }` spread. The important difference is that `..other` may **move** non-`Copy` fields out of the source, where the JavaScript spread always makes an independent shallow copy. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) These two features are so habitual in TypeScript that most developers stop noticing them. Property shorthand drops the `key: key` repetition, and the spread operator builds a new object from an existing one with a few overrides. ```typescript 1 // TypeScript - property shorthand + spread are everyday tools 2 interface User { 3 id: number; 4 username: string; 5 email: string; 6 active: boolean; 7 loginCount: number; 8 } 9 10 function buildUser(username: string, email: string): User { 11 // Property shorthand: `username` means `username: username` 12 return { id: 1, username, email, active: true, loginCount: 0 }; 13 } 14 15 const user = buildUser("alice", "alice@example.com"); 16 console.log(user); 17 // { 18 // id: 1, 19 // username: 'alice', 20 // email: 'alice@example.com', 21 // active: true, 22 // loginCount: 0 23 // } 24 25 // Spread: copy `user`, then override two properties 26 const updated = { ...user, email: "alice@new.example.com", loginCount: 1 }; 27 console.log(updated); 28 // { 29 // id: 1, 30 // username: 'alice', 31 // email: 'alice@new.example.com', 32 // active: true, 33 // loginCount: 1 34 // } 35 36 // `user` is still fully usable — spread made an independent (shallow) copy 37 console.log(user.email); // 'alice@example.com' ``` **Key points:** * Property shorthand `{ username }` is pure sugar for `{ username: username }`. * The spread `{ ...user, ... }` reads every own enumerable property of `user` into a **new** object; later keys win over spread keys. * The original `user` is untouched and still usable: the spread is a **shallow copy**, not a move. * Order matters only for overrides: `{ ...user, email }` overrides, `{ email, ...user }` would let `user.email` win. > **Note:** JavaScript’s spread is **shallow**: nested objects and arrays are shared by reference between the original and the copy. Keep this in mind when we compare it to Rust’s `..`, which has its own (different) rule. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust expresses the same two ideas with dedicated syntax. Field init shorthand is the bare field name; struct update syntax is `..other` as the **last** thing inside the braces. ```rust 1 #[derive(Debug, Clone)] 2 struct User { 3 id: u64, 4 username: String, 5 email: String, 6 active: bool, 7 login_count: u32, 8 } 9 10 // Field init shorthand: the parameter names match the field names, 11 // so `username` is shorthand for `username: username`. 12 fn build_user(username: String, email: String) -> User { 13 User { 14 id: 1, 15 username, // shorthand 16 email, // shorthand 17 active: true, 18 login_count: 0, 19 } 20 } 21 22 fn main() { 23 let user = build_user(String::from("alice"), String::from("alice@example.com")); 24 println!("{:?}", user); 25 26 // Struct update syntax: take `email` and `login_count` explicitly, 27 // fill the rest from `user.clone()`. The `..source` MUST come last. 28 let updated = User { 29 email: String::from("alice@new.example.com"), 30 login_count: 1, 31 ..user.clone() 32 }; 33 println!("{:?}", updated); 34 35 // Mix shorthand and update in one expression. 36 let id = 99u64; 37 let username = String::from("bob"); 38 let bob = User { 39 id, 40 username, 41 ..updated.clone() 42 }; 43 println!("{:?}", bob); 44 } ``` Running this prints: ```text 1 User { id: 1, username: "alice", email: "alice@example.com", active: true, login_count: 0 } 2 User { id: 1, username: "alice", email: "alice@new.example.com", active: true, login_count: 1 } 3 User { id: 99, username: "bob", email: "alice@new.example.com", active: true, login_count: 1 } ``` **Key points:** * `username,` inside the literal is exactly `username: username,` — identical sugar to TypeScript. * `..source` fills in **every field you did not write explicitly**, and it must be the **last** element (no trailing comma after it). * Here we wrote `..user.clone()` deliberately: calling `.clone()` first makes an independent copy, so the original `user` stays usable. Without the `.clone()`, the update would **move** the `String` fields out of `user`. That ownership wrinkle is the whole story of the next sections. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Field init shorthand, line by line [Section titled “Field init shorthand, line by line”](#field-init-shorthand-line-by-line) ```rust 1 fn build_user(username: String, email: String) -> User { 2 User { 3 id: 1, 4 username, // (1) 5 email, // (2) 6 active: true, 7 login_count: 0, 8 } 9 } ``` 1. `username` (no colon, no value) desugars to `username: username`: the field named `username` takes the value of the in-scope variable named `username`. 2. Same for `email`. The remaining fields use the normal `field: value` form because there is no matching local variable (and `1`/`true`/`0` are literals, not variables). The rule is purely about **name matching**: shorthand is available only when an in-scope binding has the **exact** name of the field. If the names differ, you must use the long form `field: some_other_variable`. There is no “rename while shorthanding” form, unlike TypeScript’s `{ field: localName }`, which is also how you write the long form there. > **Tip:** This is why constructor parameters and helper-function parameters in idiomatic Rust are so often named after the fields they populate: it enables the shorthand and keeps the literal clean. ### Struct update syntax, line by line [Section titled “Struct update syntax, line by line”](#struct-update-syntax-line-by-line) ```rust 1 let updated = User { 2 email: String::from("alice@new.example.com"), // (1) 3 login_count: 1, // (2) 4 ..user.clone() // (3) 5 }; ``` 1. and 2. are explicit overrides; these win over whatever `..` would supply. 2. `..user.clone()` says: for **every field not listed above** (`id`, `username`, `active`), take the value from this source expression. The source must be a value of the **same struct type**. Three rules that have no TypeScript equivalent: * **`..` must be last.** `User { ..base, port: 9090 }` does not compile; the override fields come first, the `..base` comes last, and there is no comma after it. * **The source supplies the *remaining* fields, not the leading ones.** TypeScript’s spread can appear anywhere and later keys override; Rust’s `..` is strictly “everything I didn’t already name.” * **`..` can move.** This is covered in detail in [Key Differences](#key-differences) and [Common Pitfalls](#common-pitfalls). ### Why `..user.clone()` and not `..user`? [Section titled “Why ..user.clone() and not ..user?”](#why-userclone-and-not-user) `User` contains `String` fields, and `String` is **not** `Copy` (it owns a heap allocation — see [Section 05: Ownership](/05-ownership/)). When `..user` fills in `username` from `user`, it **moves** that `String` out of `user`. After that, `user` is partially moved and can no longer be used as a whole. Calling `.clone()` first gives `..` an independent copy to consume, leaving the original `user` intact, which is what we wanted here so we could keep printing it. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | TypeScript spread `{ ...base }` | Rust struct update `..base` | | ------------------- | ---------------------------------------- | ----------------------------------------------------------- | | Position in literal | Anywhere; later keys override | Must be **last**; explicit fields override | | Effect on source | Always an independent **shallow copy** | **Moves** non-`Copy` fields out (source partially consumed) | | Source type | Any object; extra/missing keys tolerated | Must be the **same struct type** | | Missing fields | Result simply lacks them | Every field must end up set (override or `..`) | | Nested data | Shared by reference (shallow) | Moved or `Copy`-copied per field; no implicit deep clone | | Adding new keys | Spread can introduce keys not on `base` | Cannot introduce fields the struct does not declare | ### The move-vs-copy split [Section titled “The move-vs-copy split”](#the-move-vs-copy-split) This is the single most important difference. Whether `..base` leaves `base` usable depends entirely on the **types of the fields it pulls in**: * If every field that `..base` supplies is `Copy` (e.g. all `i32`, `u16`, `bool`, `f64`), then `..base` **copies** those fields and `base` remains fully usable afterward. * If `..base` supplies any non-`Copy` field (e.g. a `String` or a `Vec`), then those fields are **moved** out of `base`, and `base` is partially moved. You cannot use it as a whole anymore. A fully-`Copy` struct stays usable after an update: ```rust 1 #[derive(Debug, Clone, Copy)] 2 struct Point { 3 x: i32, 4 y: i32, 5 z: i32, 6 } 7 8 fn main() { 9 let origin = Point { x: 0, y: 0, z: 0 }; 10 let shifted = Point { x: 10, ..origin }; 11 // `origin` is still usable: every field is `Copy`, so `..origin` copies. 12 println!("{:?}", origin); 13 println!("{:?}", shifted); 14 } ``` Output: ```text 1 Point { x: 0, y: 0, z: 0 } 2 Point { x: 10, y: 0, z: 0 } ``` > **Warning:** Do not assume `..base` behaves like a JavaScript spread that always leaves the source intact. With non-`Copy` fields it consumes the source. If you need the original afterward, write `..base.clone()`. ### Struct update is total, not partial [Section titled “Struct update is total, not partial”](#struct-update-is-total-not-partial) In TypeScript, `{ ...base }` produces whatever keys `base` happens to have. In Rust, a struct literal must set **every** declared field; `..base` is just a convenient way to fill the ones you did not write. You cannot use `..base` to *skip* a field; the resulting value is always a fully-initialized struct. (See [Structs](/06-data-structures/00-structs/) for why there is no partially-initialized struct in Rust.) *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Using the source after `..source` moved a non-`Copy` field [Section titled “Pitfall 1: Using the source after ..source moved a non-Copy field”](#pitfall-1-using-the-source-after-source-moved-a-non-copy-field) This is the move-vs-copy split biting in practice: ```rust 1 #[derive(Debug)] 2 struct Config { 3 host: String, 4 port: u16, 5 verbose: bool, 6 } 7 8 fn main() { 9 let base = Config { 10 host: String::from("localhost"), 11 port: 8080, 12 verbose: false, 13 }; 14 15 let custom = Config { 16 port: 9090, 17 ..base // moves `host` (a String) out of `base` 18 }; 19 20 println!("{:?}", custom); 21 println!("{:?}", base); // does not compile (error[E0382]: borrow of partially moved value: `base`) 22 } ``` The real compiler error: ```text 1 error[E0382]: borrow of partially moved value: `base` 2 --> src/main.rs:21:22 3 | 4 15 | let custom = Config { 5 | __________________- 6 16 | | port: 9090, 7 17 | | ..base 8 18 | | }; 9 | |_____- value partially moved here 10 ... 11 21 | println!("{:?}", base); 12 | ^^^^ value borrowed here after partial move 13 | 14 = note: partial move occurs because `base.host` has type `String`, which does not implement the `Copy` trait ``` **Fix:** if you need `base` afterward, clone the source: `..base.clone()`. If you do not, just delete the later use of `base`. ### Pitfall 2: Putting `..base` first, or adding a comma after it [Section titled “Pitfall 2: Putting ..base first, or adding a comma after it”](#pitfall-2-putting-base-first-or-adding-a-comma-after-it) Coming from TypeScript, the muscle memory is `{ ...base, port: 9090 }`. In Rust, `..base` is special: it goes **last**, with no trailing comma. ```rust 1 // does not compile: `..base` must be the last field, and no comma may follow it. 2 let custom = Config { ..base, port: 9090 }; ``` The real compiler error: ```text 1 error: cannot use a comma after the base struct 2 --> src/main.rs:6:27 3 | 4 6 | let custom = Config { ..base, port: 9090 }; 5 | ^^^^^^ 6 | 7 = note: the base struct must always be the last field ``` **Fix:** put the explicit overrides first and `..base` last: ```rust 1 let custom = Config { port: 9090, ..base }; ``` ### Pitfall 3: Expecting shorthand to rename a field [Section titled “Pitfall 3: Expecting shorthand to rename a field”](#pitfall-3-expecting-shorthand-to-rename-a-field) Shorthand only works when the variable name **equals** the field name. A mismatched name is not “shorthand with a rename” — it is a reference to a field that does not exist: ```rust 1 struct Point { x: i32, y: i32 } 2 3 fn main() { 4 let x = 1; 5 let height = 2; // name does NOT match field `y` 6 let p = Point { x, height }; // does not compile (error[E0560]: struct `Point` has no field named `height`) 7 println!("{} {}", p.x, p.y); 8 } ``` The real error: ```text 1 error[E0560]: struct `Point` has no field named `height` 2 --> src/main.rs:6:24 3 | 4 6 | let p = Point { x, height }; 5 | ^^^^^^ `Point` does not have this field 6 | 7 = note: available fields are: `y` ``` **Fix:** use the long form to map the variable to the right field: `Point { x, y: height }`. ### Pitfall 4: Forgetting that `..base` does not let you skip fields [Section titled “Pitfall 4: Forgetting that ..base does not let you skip fields”](#pitfall-4-forgetting-that-base-does-not-let-you-skip-fields) A struct literal must initialize every field. If you omit one and do not supply `..base`, you get a missing-field error — `..base` is the only way to fill the gaps: ```rust 1 struct User { id: u64, name: String, active: bool } 2 3 fn main() { 4 let name = String::from("alice"); 5 let u = User { id: 1, name }; // does not compile (error[E0063]: missing field `active`) 6 println!("{}", u.name); 7 } ``` The real error: ```text 1 error[E0063]: missing field `active` in initializer of `User` 2 --> src/main.rs:5:13 3 | 4 5 | let u = User { id: 1, name }; 5 | ^^^^ missing `active` ``` **Fix:** provide the field explicitly, or fill it from another instance with `..other`, or give the struct a `Default` and use `..Default::default()` (see [Best Practices](#best-practices)). *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Pair `..Default::default()` with struct update for “config with overrides” [Section titled “Pair ..Default::default() with struct update for “config with overrides””](#pair-defaultdefault-with-struct-update-for-config-with-overrides) This is the idiomatic Rust answer to the TypeScript `{ ...DEFAULTS, ...overrides }` pattern. Derive or implement `Default`, then override only the fields that differ: ```rust 1 #[derive(Debug, Clone)] 2 struct ServerConfig { 3 host: String, 4 port: u16, 5 max_connections: u32, 6 tls: bool, 7 log_level: String, 8 } 9 10 impl Default for ServerConfig { 11 fn default() -> Self { 12 ServerConfig { 13 host: String::from("127.0.0.1"), 14 port: 8080, 15 max_connections: 1024, 16 tls: false, 17 log_level: String::from("info"), 18 } 19 } 20 } 21 22 fn main() { 23 let dev = ServerConfig { 24 log_level: String::from("debug"), 25 ..Default::default() 26 }; 27 println!("{:?}", dev); 28 } ``` Output: ```text 1 ServerConfig { host: "127.0.0.1", port: 8080, max_connections: 1024, tls: false, log_level: "debug" } ``` > **Tip:** `..Default::default()` is the closest Rust gets to TypeScript’s “optional fields with defaults.” It never moves anything out of an existing value because it constructs a fresh default on the spot. ### Use field init shorthand in constructors [Section titled “Use field init shorthand in constructors”](#use-field-init-shorthand-in-constructors) When you write a `new`-style associated function (covered in [Associated Functions](/06-data-structures/06-associated-functions/)), name the parameters after the fields so shorthand applies: ```rust 1 struct Point3 { x: f64, y: f64, z: f64 } 2 3 impl Point3 { 4 fn new(x: f64, y: f64, z: f64) -> Self { 5 Point3 { x, y, z } // clean shorthand 6 } 7 } ``` ### Reach for `..` only when most fields stay the same [Section titled “Reach for .. only when most fields stay the same”](#reach-for--only-when-most-fields-stay-the-same) Struct update shines when you change one or two fields out of many. If you are overriding most of the fields anyway, an explicit literal is clearer than `..base` plus a long list of overrides. ### Clone the source deliberately, not reflexively [Section titled “Clone the source deliberately, not reflexively”](#clone-the-source-deliberately-not-reflexively) `..base.clone()` is correct when you truly need `base` afterward. If you do not, let `..base` move — that is cheaper and the borrow checker confirms you are not using the consumed value. Do not sprinkle `.clone()` everywhere just to silence the compiler; let the move happen when it is fine. See [Section 05: Ownership](/05-ownership/) for the reasoning. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production configuration layer: a `Default` baseline, a `new` constructor that uses field shorthand, an environment-specific override built with struct update, and a per-deployment tweak built from that. This is the everyday shape of config plumbing in a Rust service. ```rust 1 #[derive(Debug, Clone)] 2 struct ServerConfig { 3 host: String, 4 port: u16, 5 max_connections: u32, 6 tls: bool, 7 log_level: String, 8 } 9 10 impl Default for ServerConfig { 11 fn default() -> Self { 12 ServerConfig { 13 host: String::from("127.0.0.1"), 14 port: 8080, 15 max_connections: 1024, 16 tls: false, 17 log_level: String::from("info"), 18 } 19 } 20 } 21 22 impl ServerConfig { 23 // Field init shorthand shines here: params named like the fields. 24 fn new(host: String, port: u16) -> Self { 25 ServerConfig { 26 host, 27 port, 28 ..Default::default() 29 } 30 } 31 } 32 33 fn main() { 34 // Start from defaults, override only what differs (struct update). 35 let dev = ServerConfig { 36 log_level: String::from("debug"), 37 ..Default::default() 38 }; 39 40 // Production: from a base, flip two fields. `.clone()` keeps `dev` usable. 41 let prod = ServerConfig { 42 host: String::from("0.0.0.0"), 43 tls: true, 44 ..dev.clone() 45 }; 46 47 // Constructor uses shorthand + Default for the rest. 48 let custom = ServerConfig::new(String::from("localhost"), 3000); 49 50 println!("dev: {:?}", dev); 51 println!("prod: {:?}", prod); 52 println!("custom: {:?}", custom); 53 } ``` Output: ```text 1 dev: ServerConfig { host: "127.0.0.1", port: 8080, max_connections: 1024, tls: false, log_level: "debug" } 2 prod: ServerConfig { host: "0.0.0.0", port: 8080, max_connections: 1024, tls: true, log_level: "debug" } 3 custom: ServerConfig { host: "localhost", port: 3000, max_connections: 1024, tls: false, log_level: "info" } ``` Notice how `prod` inherits `log_level: "debug"` from `dev` (not from `Default`), because its `..dev.clone()` source was the already-overridden `dev`. Struct update chains naturally: each layer overrides the previous one’s fields. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [The Rust Programming Language — Creating Instances From Other Instances With Struct Update Syntax](https://doc.rust-lang.org/book/ch05-01-defining-structs.html#creating-instances-from-other-instances-with-struct-update-syntax): the official walkthrough of `..` and field init shorthand. * [The Rust Reference — Struct expressions](https://doc.rust-lang.org/reference/expressions/struct-expr.html) — the precise grammar, including the functional-update (`..`) form. * [`std::default::Default`](https://doc.rust-lang.org/std/default/trait.Default.html): the trait behind `..Default::default()`. * [Structs](/06-data-structures/00-structs/) — defining structs, instantiation, and field ownership (read this first if `..` field moves are surprising). * [Tuple Structs and Unit Structs](/06-data-structures/01-tuple-structs/): positional structs (struct update applies to these too, by position). * [Associated Functions](/06-data-structures/06-associated-functions/) — `Self::new` constructors where field init shorthand is most at home. * [Pattern Matching](/06-data-structures/04-pattern-matching/): the *destructuring* counterpart; `..` also appears in patterns, with a related-but-different meaning. * [Section 05: Ownership](/05-ownership/) — why `..base` can move fields and what “partially moved” means. * [Section 02: Variables](/02-basics/00-variables/) — immutability defaults that interact with struct construction. * [Section 07: Collections](/07-collections/): building `Vec`s and maps of structs once you can construct them concisely. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: From spread to struct update [Section titled “Exercise 1: From spread to struct update”](#exercise-1-from-spread-to-struct-update) **Difficulty:** Easy **Objective:** Translate a TypeScript “copy with one override” into Rust struct update syntax, keeping the original usable. **Instructions:** Given the struct below, write a `main` that creates a `base` `Theme`, then a `user_theme` that is identical except `dark_mode: true` and `font_size: 16`. Print both, and make sure `base` is still printable after creating `user_theme`. ```rust 1 #[derive(Debug, Clone)] 2 struct Theme { 3 primary: String, 4 secondary: String, 5 font_size: u8, 6 dark_mode: bool, 7 } 8 9 fn main() { 10 // 1. build `base` 11 // 2. build `user_theme` from `base` with two overrides 12 // 3. print both (base must still work) 13 } ``` Solution ```rust 1 #[derive(Debug, Clone)] 2 struct Theme { 3 primary: String, 4 secondary: String, 5 font_size: u8, 6 dark_mode: bool, 7 } 8 9 fn main() { 10 let base = Theme { 11 primary: String::from("#0066cc"), 12 secondary: String::from("#666666"), 13 font_size: 14, 14 dark_mode: false, 15 }; 16 17 let user_theme = Theme { 18 dark_mode: true, 19 font_size: 16, 20 ..base.clone() // clone so `base` stays usable below 21 }; 22 23 println!("{:?}", base); 24 println!("{:?}", user_theme); 25 } ``` Output: ```text 1 Theme { primary: "#0066cc", secondary: "#666666", font_size: 14, dark_mode: false } 2 Theme { primary: "#0066cc", secondary: "#666666", font_size: 16, dark_mode: true } ``` > If the solution did not print `base` afterward, you could drop the `.clone()` and let `..base` move the `String` fields. But because we print `base` below, the `.clone()` is required: `..base` alone would move `primary` and `secondary` out and trigger `error[E0382]`. ### Exercise 2: Defaults plus a constructor with shorthand [Section titled “Exercise 2: Defaults plus a constructor with shorthand”](#exercise-2-defaults-plus-a-constructor-with-shorthand) **Difficulty:** Medium **Objective:** Combine `Default`, field init shorthand, and `..Default::default()` in a constructor. **Instructions:** Implement `Default` for `QueryOptions` (defaults: `limit = 25`, everything else zero/false). Add an associated function `paged(limit: u32, offset: u32) -> Self` that sets those two fields using **field init shorthand** and fills the rest from `Default`. In `main`, build one value with `paged(50, 100)` and print it. ```rust 1 #[derive(Debug, Clone)] 2 struct QueryOptions { 3 limit: u32, 4 offset: u32, 5 descending: bool, 6 include_archived: bool, 7 } 8 9 // impl Default for QueryOptions { /* ??? */ } 10 // impl QueryOptions { fn paged(/* ??? */) -> Self { /* ??? */ } } 11 12 fn main() { 13 // let q = QueryOptions::paged(50, 100); 14 // println!("{:?}", q); 15 } ``` Solution ```rust 1 #[derive(Debug, Clone)] 2 struct QueryOptions { 3 limit: u32, 4 offset: u32, 5 descending: bool, 6 include_archived: bool, 7 } 8 9 impl Default for QueryOptions { 10 fn default() -> Self { 11 QueryOptions { 12 limit: 25, 13 offset: 0, 14 descending: false, 15 include_archived: false, 16 } 17 } 18 } 19 20 impl QueryOptions { 21 fn paged(limit: u32, offset: u32) -> Self { 22 QueryOptions { 23 limit, // field init shorthand 24 offset, // field init shorthand 25 ..Default::default() 26 } 27 } 28 } 29 30 fn main() { 31 let q = QueryOptions::paged(50, 100); 32 println!("{:?}", q); 33 } ``` Output: ```text 1 QueryOptions { limit: 50, offset: 100, descending: false, include_archived: false } ``` ### Exercise 3: Chained, ownership-taking “with” methods [Section titled “Exercise 3: Chained, ownership-taking “with” methods”](#exercise-3-chained-ownership-taking-with-methods) **Difficulty:** Medium-Hard **Objective:** Build a fluent override API using struct update where each method **takes `self` by value** and returns a modified copy — a tiny builder powered entirely by `..self`. **Instructions:** Derive `Default` (and `PartialEq`) for `QueryOptions`. Add two methods that consume `self`: `with_limit(self, limit: u32) -> Self` and `descending(self) -> Self`. Each should return a new `QueryOptions` that changes only its field and keeps the rest with `..self`. In `main`, chain `QueryOptions::default().with_limit(50).descending()` and assert it equals the expected value. > **Hint:** Because each method takes `self` by value, `..self` is free to move the remaining fields — there is no original to keep usable. ```rust 1 #[derive(Debug, Clone, Default, PartialEq)] 2 struct QueryOptions { 3 limit: u32, 4 offset: u32, 5 descending: bool, 6 include_archived: bool, 7 } 8 9 // impl QueryOptions { 10 // fn with_limit(self, limit: u32) -> Self { /* ??? */ } 11 // fn descending(self) -> Self { /* ??? */ } 12 // } 13 14 fn main() { 15 // chain the methods, then assert_eq! the result 16 } ``` Solution ```rust 1 #[derive(Debug, Clone, Default, PartialEq)] 2 struct QueryOptions { 3 limit: u32, 4 offset: u32, 5 descending: bool, 6 include_archived: bool, 7 } 8 9 impl QueryOptions { 10 fn with_limit(self, limit: u32) -> Self { 11 QueryOptions { limit, ..self } 12 } 13 14 fn descending(self) -> Self { 15 QueryOptions { descending: true, ..self } 16 } 17 } 18 19 fn main() { 20 let opts = QueryOptions::default() 21 .with_limit(50) 22 .descending(); 23 24 println!("{:?}", opts); 25 assert_eq!( 26 opts, 27 QueryOptions { limit: 50, offset: 0, descending: true, include_archived: false } 28 ); 29 println!("ok"); 30 } ``` Output: ```text 1 QueryOptions { limit: 50, offset: 0, descending: true, include_archived: false } 2 ok ``` > Each method consumes `self`, so `..self` moving the remaining fields is exactly what we want — the old value is gone and a new one takes its place. This consuming-builder shape is previewed further in [Associated Functions](/06-data-structures/06-associated-functions/). *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * **Field init shorthand** (`username` instead of `username: username`) is the direct analog of TypeScript’s property shorthand and works whenever a local binding shares the field’s exact name. * **Struct update syntax** (`..other`) fills every unwritten field from another instance and must appear **last** in the literal, with no trailing comma — unlike TypeScript’s spread, which can go anywhere. * The defining difference from JavaScript’s spread: `..other` **moves** non-`Copy` fields out of the source (leaving it partially moved), while a fully-`Copy` source stays usable. Use `..other.clone()` when you need the original afterward. * `..Default::default()` is the idiomatic Rust equivalent of `{ ...DEFAULTS, ...overrides }`, and field init shorthand keeps constructors clean. # Rust Collections & Iterators > JS Array, string, Map, and Set become Rust's typed Vec, String/&str, HashMap, and BTreeMap, reshaped by lazy iterators that do no work until you ask. In TypeScript you keep data in `Array`, `string`, `Object`/`Map`, and `Set`, and you reshape it with array methods like `.map()`, `.filter()`, and `.reduce()`. Rust ships the same shapes as concrete, typed standard-library collections — `Vec<T>`, `String`/`&str`, `HashMap<K, V>`, `HashSet<T>`, and the sorted `BTreeMap`/`BTreeSet` — plus a sharper tool for processing them: the **lazy iterator** system. This section maps each TypeScript habit onto its idiomatic Rust collection, then shows how iterator adaptors and consumers replace your array-method muscle memory while doing strictly less work (nothing runs until you ask for a result). *** ## What You’ll Learn [Section titled “What You’ll Learn”](#what-youll-learn) * How a JavaScript `Array` becomes a typed, growable `Vec<T>`: `push`/`pop`/`get`/indexing, iteration, the `vec!` macro, and explicit **capacity** so you can pre-allocate * Why Rust splits the one JavaScript `string` into the owned, growable **`String`** and the borrowed view **`&str`**, and what UTF-8 and byte-boundary slicing mean for “indexing” a string * The everyday `String`/`&str` methods (`split`, `trim`, `replace`, `parse`, `chars()` vs `bytes()`) and the idiomatic ways to build strings without re-allocating on every concatenation * How a plain object or `Map` becomes a **`HashMap<K, V>`** whose keys and values are typed and owned, lookups return `Option<&V>` instead of `undefined`, and updates go through the `entry` API * How a JavaScript `Set` becomes a **`HashSet<T>`** with first-class `union`/`intersection`/`difference`/`symmetric_difference` set algebra * When to reach for the **sorted** collections **`BTreeMap`**/**`BTreeSet`** — guaranteed key order and `O(log n)` range queries — instead of their hashing cousins * Why Rust’s iterator adaptors (`map`, `filter`, `take`, `skip`, `zip`, `enumerate`) are **lazy**, doing no work until a consumer pulls values through them: the opposite of eager JavaScript array methods * The **consuming adaptors** that finish a chain (`collect`, `fold`, `sum`, `count`, `find`, `any`/`all`, `min`/`max`, `reduce`) and how they line up with `reduce`/`find`/`some`/`every` * How to build your own lazy data producer by implementing the **`Iterator`** trait (one `next` method) and **`IntoIterator`** so `for` loops work on your type * How to choose a collection deliberately using its documented **Big-O** cost model, pre-allocate with `with_capacity`, and why an iterator chain compiles to essentially the same machine code as a hand-written loop *** ## Topics [Section titled “Topics”](#topics) | Topic | Description | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | [Vectors](/07-collections/00-vectors/) | `Array` → `Vec<T>`: `push`/`pop`/`get`/indexing, iteration, capacity and growth, and the `vec!` macro. | | [Strings: `String` vs `&str`](/07-collections/01-strings/) | The critical split of one JS `string` into owned `String` vs borrowed `&str`: UTF-8, ownership, and slicing on byte boundaries. | | [String Manipulation](/07-collections/02-string-manipulation/) | Common `String`/`&str` methods: `split`/`trim`/`replace`/`parse`, `chars()` vs `bytes()`, and building strings efficiently. | | [HashMaps](/07-collections/03-hashmaps/) | Object/`Map` → `HashMap<K, V>`: `insert`/`get`, the `entry` API, iteration, and ownership of keys and values. | | [Sets and HashSet](/07-collections/04-hashsets/) | `Set` → `HashSet<T>`: membership tests and the `union`/`intersection`/`difference` set operations. | | [Sorted Collections: BTreeMap and BTreeSet](/07-collections/05-btreemap-btreeset/) | The sorted collections `BTreeMap`/`BTreeSet`: guaranteed ordering, range queries, and how they compare to `HashMap`. | | [Iterators](/07-collections/06-iterators/) | Array methods → iterator adaptors: **lazy** evaluation, and `map`/`filter`/`take`/`skip`/`zip`/`enumerate`. | | [Iterator Consumers](/07-collections/07-iterator-consumers/) | The consuming adaptors that run a chain: `collect`, `fold`, `sum`, `count`, `find`, `any`/`all`, `min`/`max`, `reduce`. | | [Custom Iterators](/07-collections/08-custom-iterators/) | Implementing the `Iterator` trait, `impl Iterator` for your own type, and `IntoIterator` for `for`-loop support. | | [Collection Performance](/07-collections/09-collection-performance/) | Big-O characteristics, when to use `Vec`/`HashMap`/`BTreeMap`, capacity preallocation, and iterator vs loop. | *** ## Learning Objectives [Section titled “Learning Objectives”](#learning-objectives) By the end of this section, you will be able to: * Choose the right container for a given job — `Vec` for ordered lists, `String`/`&str` for text, `HashMap`/`HashSet` for keyed lookup and uniqueness, `BTreeMap`/`BTreeSet` when order matters — and justify the choice with its cost model * Explain the `String` vs `&str` distinction, take a `&str` parameter for cheap borrowing, and slice strings safely on UTF-8 byte boundaries * Translate JavaScript array-method chains (`.map().filter().reduce()`) into idiomatic Rust iterator pipelines, and explain why the Rust version is lazy and allocation-free until consumed * Use the `entry` API to insert-or-update map values in a single lookup, and handle missing keys through the `Option` that lookups return instead of relying on `undefined` * Pick a consumer (`collect`, `fold`, `sum`, `find`, `any`/`all`, `max`) to finish a chain, and recognize the compiler warning you get when an iterator is built but never consumed * Implement the `Iterator` and `IntoIterator` traits to make your own type loopable and inherit the entire adaptor toolbox * Pre-allocate with `with_capacity`/`reserve` where it pays off, and reason about when a manual loop and an iterator chain are equivalent *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * [Section 05: Ownership](/05-ownership/): collections **own** their elements; pushing into a `Vec` *moves* a value in, indexing *borrows*, and `into_iter()` *consumes* the collection. The `String` vs `&str` split is ownership applied to text, so be comfortable with moves, borrows, and `Clone` first. * [Section 06: Data Structures](/06-data-structures/): collections hold your `struct`s and `enum`s, lookups return [`Option<T>`](/06-data-structures/03-option-enum/), and you will pattern-match on the results. Knowing structs, enums, and `Option` makes this section click. * [Section 02: Basics](/02-basics/): concrete types (`usize`, `i64`, `f64`), immutability-by-default and `let mut`, and `{:?}` debug formatting all show up throughout. *** ## Estimated Time [Section titled “Estimated Time”](#estimated-time) * **Reading:** 5-6 hours * **Hands-on Practice:** 4-5 hours * **Exercises:** 3 hours * **Total:** 12-14 hours > **Tip:** Read the topics in order. Start with the *containers* — `Vec`, then strings, then the maps and sets — so you know what shapes hold your data. Then learn the *iterator system* (`iterators` → `iterator-consumers` → `custom-iterators`), which is how you transform every one of those containers with the same vocabulary. Finish with `collection-performance` to tie the choices together. The single biggest mental shift for a TypeScript developer is **laziness**: `arr.map(...)` in JavaScript allocates a new array immediately, but a Rust iterator adaptor does *nothing* until a consumer runs it. *** ## Frequently asked questions [Section titled “Frequently asked questions”](#frequently-asked-questions) ### What is the Rust equivalent of a JavaScript array? [Section titled “What is the Rust equivalent of a JavaScript array?”](#what-is-the-rust-equivalent-of-a-javascript-array) `Vec<T>`, a growable, heap-allocated sequence of one element type. Unlike a JS array it cannot mix types and is indexed by `usize`. A fixed-size `[T; N]` array lives on the stack. See [Vectors](/07-collections/00-vectors/). ### Why don’t my `.map()` and `.filter()` calls run? [Section titled “Why don’t my .map() and .filter() calls run?”](#why-dont-my-map-and-filter-calls-run) Iterator adaptors are lazy: they build a recipe and do nothing until a consumer drives them. Add `.collect()`, `.sum()`, or a `for` loop to pull the values through. See [Iterators](/07-collections/06-iterators/) and [Iterator Consumers](/07-collections/07-iterator-consumers/). ### What replaces a JavaScript object or `Map`? [Section titled “What replaces a JavaScript object or Map?”](#what-replaces-a-javascript-object-or-map) `HashMap<K, V>` for dynamic keys, or a `struct` for a fixed shape. `map.get(&key)` returns `Option<&V>`, so a missing key is handled at compile time instead of yielding `undefined`. See [HashMaps](/07-collections/03-hashmaps/). *** **Next:** [Section 08: Error Handling →](/08-error-handling/) — `Result`, `Option`, the `?` operator, and custom error types, replacing the `throw`/`try`/`catch` you used in TypeScript. # Vectors: From `Array` to `Vec<T>` > Rust's Vec<T> is the JS Array's counterpart: push, pop, and iterate, but with one element type, bounds-checked indexing that panics, and ownership moves. The JavaScript `Array` is the workhorse of every TypeScript codebase. Its direct Rust counterpart is `Vec<T>`: a growable, heap-allocated, contiguous list. This page maps everything you already do with arrays (`push`, `pop`, indexing, iteration) onto `Vec<T>`, and introduces two ideas JavaScript hides from you: a single **element type** and explicit **capacity**. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **`Vec<T>`** (pronounced “vector”) is Rust’s growable array: a contiguous, heap-allocated sequence of values that all share one type `T`. Unlike a JavaScript `Array`, it cannot hold mixed types, its length is a `usize`, and it exposes its memory **capacity** so you can pre-allocate and avoid reallocations. If you reach for `Array` in TypeScript, you almost always reach for `Vec<T>` in Rust. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // A small "recently viewed products" list in a web app. 2 const recentlyViewed: string[] = []; 3 4 recentlyViewed.push("keyboard"); 5 recentlyViewed.push("monitor"); 6 recentlyViewed.push("mouse"); 7 8 // Indexing — no bounds checking, returns `undefined` past the end. 9 const first = recentlyViewed[0]; // "keyboard" 10 const missing = recentlyViewed[99]; // undefined (no error!) 11 12 // Remove the most recent item. 13 const last = recentlyViewed.pop(); // "mouse" 14 15 // Iterate. 16 for (const item of recentlyViewed) { 17 console.log(item); 18 } 19 20 // Iterate with an index. 21 recentlyViewed.forEach((item, i) => { 22 console.log(`${i}: ${item}`); 23 }); 24 25 console.log(recentlyViewed.length); // 2 26 27 // JavaScript arrays can hold mixed types — TypeScript discourages it, 28 // but the runtime allows it. 29 const mixed: unknown[] = [1, "two", true]; ``` Things to notice that Rust will handle differently: indexing out of bounds returns `undefined` instead of erroring, `pop()` on an empty array returns `undefined`, and `length` is just a `number`. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 fn main() { 2 // A growable list of `String`s. The `T` here is `String`. 3 let mut recently_viewed: Vec<String> = Vec::new(); 4 5 recently_viewed.push("keyboard".to_string()); 6 recently_viewed.push("monitor".to_string()); 7 recently_viewed.push("mouse".to_string()); 8 9 // Indexing — bounds-checked. `[99]` would PANIC, so prefer `.get()`. 10 // Read the values we want to keep BEFORE mutating with `pop`, and bind 11 // them as OWNED (not references) so no borrow stays live across `pop`. 12 let first = recently_viewed[0].clone(); // owned String -> "keyboard" 13 let missing = recently_viewed.get(99).cloned(); // Option<String> -> None 14 15 // Remove the most recent item. `pop` returns `Option<String>`. 16 let last = recently_viewed.pop(); // Some("mouse") 17 18 // Iterate by shared reference (`&` borrows, does not consume). 19 for item in &recently_viewed { 20 println!("{item}"); 21 } 22 23 // Iterate with an index using the `enumerate` adaptor. 24 for (i, item) in recently_viewed.iter().enumerate() { 25 println!("{i}: {item}"); 26 } 27 28 println!("{}", recently_viewed.len()); // 2 (a usize) 29 println!("{first}, {last:?}, {missing:?}"); 30 31 // You CANNOT mix types — this would not compile: 32 // let mixed = vec![1, "two", true]; // mismatched types 33 } ``` > **Note:** `[T]` (a slice) and `Vec<T>` are different things. `Vec<T>` *owns* its heap buffer; a slice `&[T]` is a borrowed *view* into one. Most read-only functions should take `&[T]`, not `&Vec<T>`. See [Best Practices](#best-practices). *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Creating a `Vec` [Section titled “Creating a Vec”](#creating-a-vec) There are three idiomatic ways to make one, and the choice mirrors how much you know up front. ```rust 1 fn main() { 2 // 1. Empty, type annotated. Use when you'll push later. 3 let mut empty: Vec<i32> = Vec::new(); 4 empty.push(10); 5 6 // 2. The `vec!` macro — like an array literal. 7 let nums = vec![1, 2, 3, 4, 5]; 8 9 // 3. `vec![value; count]` — repeat `value`, `count` times. 10 let zeros = vec![0; 5]; // [0, 0, 0, 0, 0] 11 12 println!("{empty:?}"); 13 println!("{nums:?}"); 14 println!("{zeros:?}"); 15 } ``` Verified output: ```text 1 [10] 2 [1, 2, 3, 4, 5] 3 [0, 0, 0, 0, 0] ``` `vec!` is a **macro** (note the `!`), not a function. The `vec![value; count]` form is the one TypeScript has no clean equivalent for; `new Array(5).fill(0)` is the closest, but `vec![0; 5]` is a single allocation with no surprises (`new Array(5)` famously creates “holes”). > **Tip:** When you build a `Vec` element-by-element from another sequence, prefer `.collect()` over a manual `push` loop: `let r: Vec<i32> = (1..=5).collect();` produces `[1, 2, 3, 4, 5]`. See [Iterator Consumers](/07-collections/07-iterator-consumers/). ### `push` and `pop` [Section titled “push and pop”](#push-and-pop) ```rust 1 fn main() { 2 let mut stack = vec![1, 2, 3]; 3 stack.push(4); // append to the end (amortized O(1)) 4 let last = stack.pop(); // remove from the end -> Option<i32> 5 println!("popped {last:?}, now {stack:?}"); 6 } ``` Verified output: ```text 1 popped Some(4), now [1, 2, 3] ``` The critical difference from JavaScript: **`pop` returns `Option<T>`, not `T | undefined`.** When the vector is empty, you get `None` rather than a value you might forget to check. The compiler forces you to handle the empty case. (`Option` is covered in [Section 02 — Basics: Types](/02-basics/01-types/) and used heavily throughout [Section 08 — Error Handling](/08-error-handling/).) ### Indexing vs `.get()` [Section titled “Indexing vs .get()”](#indexing-vs-get) This is the single biggest behavioral difference from JavaScript arrays. ```rust 1 fn main() { 2 let v = vec![10, 20, 30]; 3 4 let a = v[0]; // 10 — direct indexing, PANICS if out of bounds 5 let b = v.get(10); // None — safe, returns Option<&T> 6 7 println!("a = {a}, b = {b:?}"); 8 } ``` Verified output: ```text 1 a = 10, b = None ``` * `v[i]` returns the element directly (a copy here, since `i32` is `Copy`), but **panics** if `i >= v.len()`. * `v.get(i)` returns `Option<&T>`: `Some(&value)` or `None`. No panic, ever. In JavaScript, `arr[99]` silently gives `undefined`; in Rust, `v[99]` aborts the program. Use `.get()` whenever the index might be out of range, and reserve `v[i]` for indices you have already proven valid. ### Iteration: three flavors of borrow [Section titled “Iteration: three flavors of borrow”](#iteration-three-flavors-of-borrow) JavaScript has one iteration model. Rust has three, and the difference is *ownership*: ```rust 1 fn main() { 2 let mut scores = vec![1, 2, 3]; 3 4 // `&v` -> iterate by shared reference (read-only). Vec stays usable. 5 for s in &scores { 6 print!("{s} "); 7 } 8 println!(); 9 10 // `&mut v` -> iterate by mutable reference. `s` is `&mut i32`; deref to write. 11 for s in &mut scores { 12 *s *= 10; 13 } 14 println!("{scores:?}"); 15 16 // `v` (by value) -> `into_iter()`, CONSUMES the Vec, yields owned values. 17 let owned = vec![String::from("x"), String::from("y")]; 18 for s in owned.into_iter() { 19 print!("{s} "); 20 } 21 println!(); 22 // `owned` is gone here — it was moved into the loop. 23 } ``` Verified output: ```text 1 1 2 3 2 [10, 20, 30] 3 x y ``` | You write | Method called | Item type | Vec afterwards | JS analogy | | ----------------- | ------------- | --------- | ------------------ | ---------------------- | | `for x in &v` | `iter()` | `&T` | still usable | `for...of` (read) | | `for x in &mut v` | `iter_mut()` | `&mut T` | still usable | `for...of` + mutate | | `for x in v` | `into_iter()` | `T` | **consumed/moved** | (no direct equivalent) | > **Note:** `*s *= 10` dereferences the mutable reference to write through it. In the `&mut` loop, `s` has type `&mut i32`, so `*s` is the `i32` itself. JavaScript has no concept of “iterate but you may only read.” ### Capacity and growth [Section titled “Capacity and growth”](#capacity-and-growth) A `Vec` tracks two numbers: **length** (how many elements it holds) and **capacity** (how many it *could* hold before it must allocate a bigger buffer). JavaScript hides this entirely; Rust exposes it because it directly affects performance. ```rust 1 fn main() { 2 let mut v: Vec<i32> = Vec::new(); 3 let mut last_cap = v.capacity(); 4 println!("start cap = {last_cap}"); 5 for i in 0..20 { 6 v.push(i); 7 if v.capacity() != last_cap { 8 println!("len {} triggered growth: cap {} -> {}", v.len(), last_cap, v.capacity()); 9 last_cap = v.capacity(); 10 } 11 } 12 } ``` Verified output: ```text 1 start cap = 0 2 len 1 triggered growth: cap 0 -> 4 3 len 5 triggered growth: cap 4 -> 8 4 len 9 triggered growth: cap 8 -> 16 5 len 17 triggered growth: cap 16 -> 32 ``` When `push` runs out of capacity, the `Vec` allocates a larger buffer (currently it roughly **doubles**) and copies the old elements over. That copy is why an individual `push` is *amortized* O(1) rather than strictly O(1). An empty `Vec::new()` starts with **zero** capacity and allocates lazily on the first push. If you know roughly how many elements you’ll store, pre-allocate with `Vec::with_capacity(n)` to skip the intermediate reallocations: ```rust 1 fn main() { 2 let mut c: Vec<i32> = Vec::with_capacity(10); 3 println!("len={}, cap={}", c.len(), c.capacity()); 4 for i in 0..10 { 5 c.push(i); 6 } 7 println!("len={}, cap={}", c.len(), c.capacity()); 8 c.push(99); // exceeds capacity 10 -> reallocates 9 println!("after one more: len={}, cap={}", c.len(), c.capacity()); 10 } ``` Verified output: ```text 1 len=0, cap=10 2 len=10, cap=10 3 after one more: len=11, cap=20 ``` Note that `with_capacity(10)` sets capacity to 10 while length stays 0: capacity is *room*, not *contents*. ### Other everyday methods [Section titled “Other everyday methods”](#other-everyday-methods) ```rust 1 fn main() { 2 let mut v = vec![1, 2, 3, 4, 5, 6]; 3 4 println!("contains 3? {}", v.contains(&3)); // membership (takes &T) 5 v.retain(|&x| x % 2 == 0); // keep elements matching predicate (in place) 6 println!("after retain: {v:?}"); 7 v.extend([8, 10]); // append all items from another iterable 8 println!("after extend: {v:?}"); 9 10 let mut letters = vec!['a', 'c', 'd']; 11 letters.insert(1, 'b'); // insert at index — shifts the rest, O(n) 12 println!("{letters:?}"); 13 let removed = letters.remove(0); // remove at index — shifts the rest, O(n) 14 println!("removed {removed}, now {letters:?}"); 15 16 let mut t = vec![1, 2, 3, 4]; 17 let s = t.swap_remove(0); // O(1) remove, but does NOT preserve order 18 println!("swap_remove gave {s}, now {t:?}"); 19 20 let scores = vec![10, 20, 30]; 21 let total: i32 = scores.iter().sum(); 22 println!("total={total}, first={:?}, last={:?}", scores.first(), scores.last()); 23 24 let data = vec![1, 2, 3, 4, 5]; 25 let middle = &data[1..4]; // a slice &[i32] — a borrowed view, no copy 26 println!("slice: {middle:?}"); 27 } ``` Verified output: ```text 1 contains 3? true 2 after retain: [2, 4, 6] 3 after extend: [2, 4, 6, 8, 10] 4 ['a', 'b', 'c', 'd'] 5 removed a, now ['b', 'c', 'd'] 6 swap_remove gave 1, now [4, 2, 3] 7 total=60, first=Some(10), last=Some(30) 8 slice: [2, 3, 4] ``` `first()` and `last()` return `Option<&T>` (safe), unlike `arr[0]` / `arr[arr.length - 1]` in JavaScript. `&data[1..4]` produces a **slice**, covered in depth in [Strings](/07-collections/01-strings/) (for `&str`) and [Section 05 — Ownership](/05-ownership/). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript `Array<T>` | Rust `Vec<T>` | | ------------------------ | ------------------------------- | ---------------------------------------------------- | | Element types | Can be heterogeneous at runtime | Strictly homogeneous: one `T` | | Out-of-bounds index | Returns `undefined` | `v[i]` **panics**; `v.get(i)` returns `None` | | `pop()` when empty | `undefined` | `None` (an `Option<T>`) | | Length type | `number` (f64) | `usize` | | Memory model | Engine-managed, opaque | Explicit `len` + `capacity`, heap-allocated | | Pre-allocation | Not really exposed | `Vec::with_capacity(n)` | | Copy on assignment | Reference copied (shared) | Value **moved** (ownership transfers) | | Removing from the middle | `splice` (O(n)) | `remove` (O(n), ordered) or `swap_remove` (O(1)) | | Negative indices | `arr.at(-1)` | No negative indices; use `.last()` or `v[v.len()-1]` | ### The ownership difference that bites first [Section titled “The ownership difference that bites first”](#the-ownership-difference-that-bites-first) ```typescript 1 const a = [1, 2, 3]; 2 const b = a; // b and a point at the SAME array 3 b.push(4); 4 console.log(a); // [1, 2, 3, 4] — both see the change ``` ```rust 1 let a = vec![1, 2, 3]; 2 let b = a; // ownership MOVED to b; `a` is no longer usable 3 // println!("{a:?}"); // would not compile: value borrowed after move ``` In JavaScript, `b = a` aliases the same array. In Rust, it **moves** ownership, so `a` becomes invalid. To get two independent vectors, call `a.clone()`. To share read access, borrow with `&a`. This is the core ownership story from [Section 05 — Ownership](/05-ownership/), and it is the most common surprise for TypeScript developers. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Mutating a `Vec` while iterating over it [Section titled “Pitfall 1: Mutating a Vec while iterating over it”](#pitfall-1-mutating-a-vec-while-iterating-over-it) In JavaScript you can (dangerously) `push` inside a `for...of`. Rust’s borrow checker forbids it outright, at compile time. ```rust 1 fn main() { 2 let mut v = vec![1, 2, 3]; 3 for x in &v { 4 if *x == 2 { 5 v.push(10); // does not compile (error[E0502]) 6 } 7 } 8 } ``` Real compiler error: ```text 1 error[E0502]: cannot borrow `v` as mutable because it is also borrowed as immutable 2 --> src/main.rs:5:13 3 | 4 3 | for x in &v { 5 | -- 6 | | 7 | immutable borrow occurs here 8 | immutable borrow later used here 9 4 | if *x == 2 { 10 5 | v.push(10); // does not compile (error[E0502]) 11 | ^^^^^^^^^^ mutable borrow occurs here ``` **Fix:** collect the changes first, or use `retain`/`extend`, or iterate over indices. For example, decide what to add, then push after the loop: ```rust 1 fn main() { 2 let mut v = vec![1, 2, 3]; 3 let mut to_add = Vec::new(); 4 for x in &v { 5 if *x == 2 { 6 to_add.push(10); 7 } 8 } 9 v.extend(to_add); 10 println!("{v:?}"); // [1, 2, 3, 10] 11 } ``` ### Pitfall 2: Indexing with the wrong integer type [Section titled “Pitfall 2: Indexing with the wrong integer type”](#pitfall-2-indexing-with-the-wrong-integer-type) `Vec` is indexed by `usize`, not `i32`. A plain `let i = 1;` infers `i32` by default and won’t work as an index. ```rust 1 fn main() { 2 let i: i32 = 1; 3 let v = vec![10, 20, 30]; 4 let x = v[i]; // does not compile (error[E0277]) 5 println!("{x}"); 6 } ``` Real compiler error (trimmed): ```text 1 error[E0277]: the type `[{integer}]` cannot be indexed by `i32` 2 --> src/main.rs:4:15 3 | 4 4 | let x = v[i]; // does not compile (error[E0277]) 5 | ^ slice indices are of type `usize` or ranges of `usize` ``` **Fix:** use `usize` for indices (`let i: usize = 1;`) or cast with `i as usize`. Loop counters from `0..v.len()` are already `usize`. ### Pitfall 3: Out-of-bounds indexing panics at runtime [Section titled “Pitfall 3: Out-of-bounds indexing panics at runtime”](#pitfall-3-out-of-bounds-indexing-panics-at-runtime) Because `v[i]` is bounds-checked but not type-checked against the length, an out-of-range index compiles fine and then panics when it runs. ```rust 1 fn main() { 2 let v = vec![1, 2, 3]; 3 let x = v[10]; // compiles, but PANICS at runtime 4 println!("{x}"); 5 } ``` Real runtime output: ```text 1 thread 'main' panicked at src/main.rs:3:14: 2 index out of bounds: the len is 3 but the index is 10 3 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` **Fix:** when the index might be invalid, use `.get(i)` and handle the `Option`: ```rust 1 fn main() { 2 let v = vec![1, 2, 3]; 3 match v.get(10) { 4 Some(x) => println!("got {x}"), 5 None => println!("no element at index 10"), 6 } 7 } ``` ### Pitfall 4: Using a `Vec` after moving it into a function [Section titled “Pitfall 4: Using a Vec after moving it into a function”](#pitfall-4-using-a-vec-after-moving-it-into-a-function) Passing a `Vec` by value transfers ownership; the caller can no longer use it. ```rust 1 fn total(v: Vec<i32>) -> i32 { 2 v.iter().sum() 3 } 4 5 fn main() { 6 let nums = vec![1, 2, 3]; 7 let t = total(nums); // `nums` moved into `total` 8 println!("{t}"); 9 println!("{}", nums.len()); // does not compile (error[E0382]) 10 } ``` Real compiler error (trimmed): ```text 1 error[E0382]: borrow of moved value: `nums` 2 --> src/main.rs:8:20 3 | 4 5 | let nums = vec![1, 2, 3]; 5 | ---- move occurs because `nums` has type `Vec<i32>`, which does not implement the `Copy` trait 6 6 | let t = total(nums); // nums moved here 7 | ---- value moved here 8 ... 9 8 | println!("{}", nums.len()); // use after move 10 | ^^^^ value borrowed here after move ``` **Fix:** take a slice instead (`fn total(v: &[i32]) -> i32`) and call `total(&nums)`. The function borrows, so `nums` stays usable. This is the idiomatic signature; see Best Practices below. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Accept `&[T]`, return `Vec<T>` [Section titled “1. Accept &\[T\], return Vec\<T>”](#1-accept-t-return-vect) A read-only function should take a **slice** `&[T]`, not `&Vec<T>`. Slices accept vectors, arrays, and sub-ranges alike, so your function is more reusable and avoids forcing the caller to own a `Vec`. ```rust 1 // Idiomatic: works for `&Vec<T>`, `&[T; N]`, and slices. 2 fn average(values: &[f64]) -> f64 { 3 if values.is_empty() { 4 return 0.0; 5 } 6 values.iter().sum::<f64>() / values.len() as f64 7 } 8 9 fn main() { 10 let v = vec![20.5, 22.0, 19.5]; 11 println!("{}", average(&v)); // a Vec coerces to &[f64] automatically 12 let arr = [1.0, 2.0, 3.0]; 13 println!("{}", average(&arr)); // so does an array 14 } ``` ### 2. Pre-allocate when you know the size [Section titled “2. Pre-allocate when you know the size”](#2-pre-allocate-when-you-know-the-size) If you’re about to push `n` items, call `Vec::with_capacity(n)` first to avoid repeated reallocations. Capacity tuning matters at scale; see [Collection Performance](/07-collections/09-collection-performance/). ### 3. Prefer iterators and `collect` over manual index loops [Section titled “3. Prefer iterators and collect over manual index loops”](#3-prefer-iterators-and-collect-over-manual-index-loops) Building a new `Vec` by transforming another is clearer (and often faster) with iterator adaptors than with a manual `for` + `push`: ```rust 1 fn main() { 2 let prices = vec![100, 250, 75]; 3 // idiomatic 4 let with_tax: Vec<i32> = prices.iter().map(|p| p * 110 / 100).collect(); 5 println!("{with_tax:?}"); // [110, 275, 82] 6 } ``` See [Iterators](/07-collections/06-iterators/) and [Iterator Consumers](/07-collections/07-iterator-consumers/). ### 4. Choose the right removal method [Section titled “4. Choose the right removal method”](#4-choose-the-right-removal-method) `remove(i)` preserves order but is O(n) (it shifts every later element). If order doesn’t matter, `swap_remove(i)` is O(1). Don’t pay for ordering you don’t need. ### 5. Use `.get()` / `.first()` / `.last()` at boundaries [Section titled “5. Use .get() / .first() / .last() at boundaries”](#5-use-get--first--last-at-boundaries) When an index could be out of range (user input, parsed data), use the `Option`-returning accessors so a bad index is a handled `None` rather than a panic. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A shopping cart: a `Vec` of line items with pre-allocation, predicate-based removal, and an aggregate computed with an iterator. ```rust 1 #[derive(Debug, Clone)] 2 struct CartItem { 3 name: String, 4 price_cents: u64, 5 quantity: u32, 6 } 7 8 struct Cart { 9 items: Vec<CartItem>, 10 } 11 12 impl Cart { 13 fn new() -> Self { 14 // Pre-size: most carts hold a handful of items. 15 Cart { 16 items: Vec::with_capacity(8), 17 } 18 } 19 20 fn add(&mut self, name: &str, price_cents: u64, quantity: u32) { 21 self.items.push(CartItem { 22 name: name.to_string(), 23 price_cents, 24 quantity, 25 }); 26 } 27 28 fn remove_out_of_stock(&mut self, out_of_stock: &[&str]) { 29 // retain keeps only items NOT in the out-of-stock list. 30 self.items 31 .retain(|item| !out_of_stock.contains(&item.name.as_str())); 32 } 33 34 fn subtotal_cents(&self) -> u64 { 35 self.items 36 .iter() 37 .map(|item| item.price_cents * item.quantity as u64) 38 .sum() 39 } 40 41 fn most_expensive(&self) -> Option<&CartItem> { 42 self.items.iter().max_by_key(|item| item.price_cents) 43 } 44 } 45 46 fn main() { 47 let mut cart = Cart::new(); 48 cart.add("Mechanical Keyboard", 12_900, 1); 49 cart.add("USB-C Cable", 1_200, 3); 50 cart.add("Discontinued Mouse", 4_500, 1); 51 52 cart.remove_out_of_stock(&["Discontinued Mouse"]); 53 54 for (i, item) in cart.items.iter().enumerate() { 55 println!( 56 "{}. {} x{} @ ${:.2}", 57 i + 1, 58 item.name, 59 item.quantity, 60 item.price_cents as f64 / 100.0 61 ); 62 } 63 64 println!("Subtotal: ${:.2}", cart.subtotal_cents() as f64 / 100.0); 65 66 if let Some(top) = cart.most_expensive() { 67 println!("Priciest line: {}", top.name); 68 } 69 } ``` Verified output: ```text 1 1. Mechanical Keyboard x1 @ $129.00 2 2. USB-C Cable x3 @ $12.00 3 Subtotal: $165.00 4 Priciest line: Mechanical Keyboard ``` Notice the patterns: `with_capacity` to avoid early reallocations, `retain` for in-place filtering (the equivalent of reassigning `cart = cart.filter(...)` in TypeScript, but without a second allocation), `iter().map(...).sum()` for the total, and `max_by_key` returning an `Option<&CartItem>` so an empty cart is handled safely. Money is stored as integer `u64` cents — never `f64` — to avoid floating-point rounding, exactly as you would in a careful TypeScript backend. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [`std::vec::Vec` API docs](https://doc.rust-lang.org/std/vec/struct.Vec.html): every method, with examples * [The Rust Book — Storing Lists with Vectors](https://doc.rust-lang.org/book/ch08-01-vectors.html) * [Rust by Example — Vectors](https://doc.rust-lang.org/rust-by-example/std/vec.html) * [The `vec!` macro](https://doc.rust-lang.org/std/macro.vec.html) ### Related Topics in This Guide [Section titled “Related Topics in This Guide”](#related-topics-in-this-guide) * [Strings](/07-collections/01-strings/): `String` is, internally, a `Vec<u8>` of UTF-8 bytes * [HashMaps](/07-collections/03-hashmaps/): when you need key/value lookup instead of a list * [Iterators](/07-collections/06-iterators/) and [Iterator Consumers](/07-collections/07-iterator-consumers/): the lazy adaptors that replace JS array methods * [Collection Performance](/07-collections/09-collection-performance/): Big-O, capacity tuning, `Vec` vs other collections * [Section 05 — Ownership](/05-ownership/): why `let b = a` moves a `Vec` * [Section 02 — Basics: Types](/02-basics/01-types/): `usize`, `Option`, and integer types * [Section 08 — Error Handling](/08-error-handling/): handling the `Option` that `pop`/`get` return *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Running Average [Section titled “Exercise 1: Running Average”](#exercise-1-running-average) **Difficulty:** Beginner **Objective:** Practice creating a `Vec`, pushing onto it, and computing an aggregate with an iterator. **Instructions:** Start with an empty `Vec<f64>`. Push the temperatures `20.5`, `22.0`, and `19.5`. Then compute and print their average. Watch the integer-vs-float cast for the length. ```rust 1 fn main() { 2 let mut temps: Vec<f64> = Vec::new(); 3 // TODO: push the three temperatures 4 5 // TODO: compute the average and print it 6 } ``` Solution ```rust 1 fn main() { 2 let mut temps: Vec<f64> = Vec::new(); 3 temps.push(20.5); 4 temps.push(22.0); 5 temps.push(19.5); 6 7 let sum: f64 = temps.iter().sum(); 8 let avg = sum / temps.len() as f64; // len() is usize, cast to f64 9 println!("avg = {avg}"); 10 } ``` Output: ```text 1 avg = 20.666666666666668 ``` ### Exercise 2: Safe Element Access [Section titled “Exercise 2: Safe Element Access”](#exercise-2-safe-element-access) **Difficulty:** Intermediate **Objective:** Replace panicking index access with the `Option`-returning `.get()`. **Instructions:** Given `let v = vec![10, 20, 30];`, write code that prints the element at index 5 if it exists, or `"no element at index 5"` if it does not, without ever panicking. Then read index 1 with a fallback default of `0`. ```rust 1 fn main() { 2 let v = vec![10, 20, 30]; 3 // TODO: print element at index 5, or a "not found" message 4 // TODO: read index 1, defaulting to 0 if missing 5 } ``` Solution ```rust 1 fn main() { 2 let v = vec![10, 20, 30]; 3 4 match v.get(5) { 5 Some(x) => println!("got {x}"), 6 None => println!("no element at index 5"), 7 } 8 9 // .copied() turns Option<&i32> into Option<i32>; unwrap_or supplies a default. 10 let val = v.get(1).copied().unwrap_or(0); 11 println!("val = {val}"); 12 } ``` Output: ```text 1 no element at index 5 2 val = 20 ``` ### Exercise 3: Deduplicate and Transform [Section titled “Exercise 3: Deduplicate and Transform”](#exercise-3-deduplicate-and-transform) **Difficulty:** Advanced **Objective:** Combine in-place mutation (`sort`, `dedup`) with an iterator transformation that builds a new `Vec`. **Instructions:** Given `vec![3, 1, 2, 3, 1, 2]`, produce a sorted list of the **unique** values, then build a *second* `Vec` containing each unique value doubled. Print both. (Hint: `dedup` only removes *consecutive* duplicates, so you must sort first.) ```rust 1 fn main() { 2 let mut nums = vec![3, 1, 2, 3, 1, 2]; 3 // TODO: sort, then remove consecutive duplicates 4 5 // TODO: build a new Vec of each value doubled, then print both 6 } ``` Solution ```rust 1 fn main() { 2 let mut nums = vec![3, 1, 2, 3, 1, 2]; 3 nums.sort(); // [1, 1, 2, 2, 3, 3] 4 nums.dedup(); // [1, 2, 3] — removes only CONSECUTIVE duplicates 5 6 println!("unique sorted: {nums:?}"); 7 8 let doubled: Vec<i32> = nums.iter().map(|n| n * 2).collect(); 9 println!("doubled: {doubled:?}"); 10 } ``` Output: ```text 1 unique sorted: [1, 2, 3] 2 doubled: [2, 4, 6] ``` # Strings: `String` vs `&str` > Rust splits the JavaScript string into two types: the owned, growable String and the borrowed slice &str. Learn which to use, plus UTF-8 and byte lengths. Rust splits the single JavaScript `string` into two types: the owned, growable `String` and the borrowed slice `&str`. Understanding which one to use, and why, is one of the most useful things a TypeScript/JavaScript developer can learn early. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In JavaScript a `string` is one thing: an immutable, garbage-collected sequence of UTF-16 code units. Rust has **two** core string types instead: a `String` (owned, heap-allocated, growable) and a `&str` (a borrowed, read-only view into UTF-8 bytes someone else owns). The distinction matters because it ties directly into [ownership and borrowing](/05-ownership/), and once it clicks, the rest of Rust’s string story (UTF-8, slicing, no integer indexing) follows naturally. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // TypeScript - one string type, does everything 2 let greeting: string = "Hello"; 3 4 // "Mutation" actually creates a brand-new string each time 5 greeting = greeting + ", world"; 6 greeting += "!"; 7 console.log(greeting); // "Hello, world!" 8 9 // Strings are indexable and have a .length 10 console.log(greeting.length); // 13 11 console.log(greeting[0]); // "H" 12 console.log(greeting.charAt(0)); // "H" 13 14 // Passing a string to a function is cheap — it's a reference under the hood 15 function shout(text: string): string { 16 return text.toUpperCase(); 17 } 18 console.log(shout(greeting)); // "HELLO, WORLD!" 19 20 // But .length and indexing count UTF-16 code units, not characters: 21 console.log("café".length); // 4 22 console.log("\u{1F44B}".length); // 2 (one emoji, but a surrogate pair!) 23 console.log([..."\u{1F44B}"].length); // 1 (spread iterates by code point) ``` **Key points:** * One type (`string`) for literals, fields, parameters, and return values. * Strings are immutable; `+=` allocates a new string each time. * `.length` and `s[i]` operate on UTF-16 code units, which silently lies for emoji and other astral-plane characters. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 fn main() { 2 // Two types, two jobs: 3 let literal: &str = "Hello"; // borrowed slice, baked into the binary 4 let mut owned: String = String::from("Hello"); // heap-allocated, growable 5 6 // Real in-place mutation (owned must be `mut`): 7 owned.push_str(", world"); 8 owned.push('!'); 9 println!("{owned}"); // "Hello, world!" 10 11 // No .length — `len()` is the number of UTF-8 *bytes*: 12 println!("{}", owned.len()); // 13 13 println!("{}", "café".len()); // 5 (é is two bytes) 14 println!("{}", "café".chars().count()); // 4 (count actual characters) 15 16 // Functions take `&str` so they accept BOTH a &String and a literal: 17 println!("{}", shout(&owned)); // pass a &String 18 println!("{}", shout(literal)); // pass a &str literal 19 } 20 21 fn shout(text: &str) -> String { 22 text.to_uppercase() 23 } ``` Real output: ```text 1 Hello, world! 2 13 3 5 4 4 5 HELLO, WORLD! 6 HELLO ``` **Key points:** * `&str` is the borrowed view; `String` is the owned, growable buffer. * A `String` is mutable only when bound with `let mut`; a `&str` is never mutable. * `len()` returns **bytes**, not characters. Rust never pretends UTF-8 is fixed-width. * Idiomatic functions accept `&str` parameters so callers can pass either type for free. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Two types, one mental model [Section titled “Two types, one mental model”](#two-types-one-mental-model) Picture the JavaScript string split along the **ownership** axis you learned in [Section 05](/05-ownership/): | Concept | JavaScript | Rust | | --------------------------------------- | ---------------------------- | -------- | | Owns its heap buffer, can grow | (every `string`, via the GC) | `String` | | Borrows someone else’s bytes, read-only | (not a distinct type) | `&str` | A `String` is essentially a struct of three machine words: a pointer to a heap buffer, a length, and a capacity, almost exactly like a `Vec<u8>` (see [Vectors](/07-collections/00-vectors/)) that is guaranteed to hold valid UTF-8. A `&str` is a **fat pointer**: just a pointer to some UTF-8 bytes plus a length. It does not own those bytes, so it cannot free them, cannot grow, and cannot outlive whatever it points into. String **literals** like `"Hello"` are `&'static str`: they point into the compiled binary’s read-only data and live for the entire program. ### Creating each type [Section titled “Creating each type”](#creating-each-type) ```rust 1 fn main() { 2 // &str: just write a literal 3 let a: &str = "hello"; 4 5 // String: several equivalent constructors 6 let b = String::from("hello"); 7 let c = "hello".to_string(); 8 let d = "hello".to_owned(); 9 10 println!("{a} {b} {c} {d}"); 11 } ``` Real output: ```text 1 hello hello hello hello ``` `to_string()`, `to_owned()`, and `String::from()` all heap-allocate a copy. Reach for them only when you genuinely need ownership: a value you will mutate, store in a struct, or return from a function. ### Borrowing: `&String` coerces to `&str` [Section titled “Borrowing: \&String coerces to \&str”](#borrowing-string-coerces-to-str) Rust applies **deref coercion** so that a `&String` automatically becomes a `&str` wherever one is expected. This is why a single `&str` parameter accepts every common caller: ```rust 1 fn main() { 2 let s = String::from("greetings"); 3 takes_str(&s); // &String -> &str (deref coercion) 4 takes_str("hello"); // &str literal passes directly 5 takes_str(&s[0..3]); // a sub-slice of the String 6 } 7 8 fn takes_str(s: &str) { 9 println!("got: {s}"); 10 } ``` Real output: ```text 1 got: greetings 2 got: hello 3 got: gre ``` > **Tip:** Prefer `&str` over `&String` for function parameters. `&str` accepts strictly more callers (literals, slices, and `&String`), so there is no reason to write `fn f(s: &String)`. ### UTF-8, length, and characters [Section titled “UTF-8, length, and characters”](#utf-8-length-and-characters) Every Rust string — `String` or `&str` — is guaranteed to be **valid UTF-8**. That guarantee is the root cause of the three biggest surprises for JavaScript developers. First, `len()` is bytes, and `chars().count()` is characters: ```rust 1 fn main() { 2 let cafe = "café"; // 'c' 'a' 'f' are 1 byte each; 'é' is 2 bytes 3 println!("len (bytes) = {}", cafe.len()); // 5 4 println!("chars().count() = {}", cafe.chars().count()); // 4 5 6 let wave = "\u{1F44B}"; 7 println!("emoji bytes = {}", wave.len()); // 4 8 println!("emoji chars = {}", wave.chars().count()); // 1 9 } ``` Real output: ```text 1 len (bytes) = 5 2 chars().count() = 4 3 emoji bytes = 4 4 emoji chars = 1 ``` Contrast with Node v22, where `"café".length` is `4` and `"\u{1F44B}".length` is `2` (a UTF-16 surrogate pair counted as two units). Neither language gives you “characters” from a length property — JavaScript counts UTF-16 units and Rust counts UTF-8 bytes — but Rust forces you to *say which one you mean*. > **Note:** A Rust `char` is a **Unicode scalar value** and is always 4 bytes wide, regardless of how it is encoded inside a string. The string itself stays compact UTF-8; only the standalone `char` type is fixed-width. See [Basic Types](/02-basics/01-types/) for the `char` type. ### No integer indexing — slice by byte range instead [Section titled “No integer indexing — slice by byte range instead”](#no-integer-indexing--slice-by-byte-range-instead) JavaScript lets you write `s[0]`. Rust does **not** let you index a string by an integer, because answering “what is byte 0?” versus “what is character 0?” is ambiguous in a variable-width encoding, and a single-`char` answer might require reading several bytes. Instead you slice by a **byte range**: ```rust 1 fn main() { 2 let hello = "hello"; 3 let h = &hello[0..1]; // a &str of length 1: "h" 4 println!("{h}"); 5 6 // The "nth character" comes from the chars() iterator, not indexing: 7 let third = "hello".chars().nth(2); // Some('l') 8 println!("{third:?}"); 9 } ``` Real output: ```text 1 h 2 Some('l') ``` Slicing returns a `&str` (a borrowed view): no allocation, no copy. But the byte offsets you pass **must land on character boundaries**, which is the next pitfall. ### Iterating: `chars()`, `bytes()`, `char_indices()` [Section titled “Iterating: chars(), bytes(), char\_indices()”](#iterating-chars-bytes-char_indices) ```rust 1 fn main() { 2 for (i, ch) in "café".char_indices() { 3 print!("({i},{ch}) "); 4 } 5 println!(); 6 } ``` Real output: ```text 1 (0,c) (1,a) (2,f) (3,é) ``` Notice the byte index jumps to `3` for `'é'`, then the next character (if any) would start at byte `5`. The indices are byte offsets, which is exactly what you need to slice safely. (More iteration methods — `split`, `trim`, `replace`, `parse` — are covered in [String Manipulation](/07-collections/02-string-manipulation/).) *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | JavaScript `string` | Rust `String` | Rust `&str` | | ------------------------ | -------------------------- | -------------------------------- | -------------------------------- | | Ownership | GC-managed | Owns a heap buffer | Borrows bytes it does not own | | Mutability | Immutable (re-binds) | Mutable when `let mut` | Always read-only | | Growable | n/a (new string each time) | Yes (`push`, `push_str`) | No | | Encoding | UTF-16 internally | Guaranteed valid UTF-8 | Guaranteed valid UTF-8 | | `.length` / `len()` | UTF-16 code units | UTF-8 **bytes** | UTF-8 **bytes** | | Integer indexing `s[i]` | Allowed (UTF-16 unit) | Not allowed (compile error) | Not allowed (compile error) | | Range slicing `&s[a..b]` | n/a (use `slice`) | Allowed (must hit char boundary) | Allowed (must hit char boundary) | | Typical role | everything | a value you build/own/store | a parameter or temporary view | ### Why two types? [Section titled “Why two types?”](#why-two-types) The split is not arbitrary; it is ownership applied to text: * A `&str` is a cheap, copyable **view**. Passing one moves only a pointer and a length; no heap data is touched. This is why parameters are almost always `&str`. * A `String` is what you reach for when you need to **own** the bytes: build a value piece by piece, mutate it, store it in a struct, or return freshly created text from a function. This mirrors `&[T]` vs `Vec<T>` for non-text data ([Vectors](/07-collections/00-vectors/)): a slice borrows, the `Vec`/`String` owns. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Trying to index a string with an integer [Section titled “Pitfall 1: Trying to index a string with an integer”](#pitfall-1-trying-to-index-a-string-with-an-integer) ```rust 1 fn main() { 2 let s = String::from("hello"); 3 let ch = s[0]; // does not compile (error[E0277]) — strings aren't integer-indexable 4 println!("{ch}"); 5 } ``` Real compiler error: ```text 1 error[E0277]: the type `str` cannot be indexed by `{integer}` 2 --> src/main.rs:3:16 3 | 4 3 | let ch = s[0]; // try to index by integer 5 | ^ string indices are ranges of `usize` 6 | 7 = help: the trait `SliceIndex<str>` is not implemented for `{integer}` 8 = note: you can use `.chars().nth()` or `.bytes().nth()` 9 for more information, see chapter 8 in The Book: <https://doc.rust-lang.org/book/ch08-02-strings.html#indexing-into-strings> ``` The compiler even tells you the fix: use `.chars().nth(i)` for the i-th character or `.bytes().nth(i)` for the i-th byte. ### Pitfall 2: Slicing in the middle of a multi-byte character [Section titled “Pitfall 2: Slicing in the middle of a multi-byte character”](#pitfall-2-slicing-in-the-middle-of-a-multi-byte-character) This one compiles fine but **panics at runtime**, the most dangerous kind, because the type checker can’t catch a byte offset computed at runtime: ```rust 1 fn main() { 2 let s = "café"; // 'caf' = bytes 0..3, 'é' = bytes 3..5 3 let bad = &s[0..4]; // panics: byte 4 splits 'é' in half 4 println!("{bad}"); 5 } ``` Real runtime panic: ```text 1 thread 'main' panicked at src/main.rs:3:17: 2 byte index 4 is not a char boundary; it is inside 'é' (bytes 3..5) of `café` ``` The fix is to use boundaries you got from `char_indices()`, or use the non-panicking `.get(range)` which returns an `Option` instead: ```rust 1 fn main() { 2 let s = "café"; 3 println!("{:?}", s.get(0..3)); // Some("caf") 4 println!("{:?}", s.get(0..4)); // None — not a boundary, no panic 5 println!("{}", s.is_char_boundary(3)); // true 6 println!("{}", s.is_char_boundary(4)); // false 7 } ``` Real output: ```text 1 Some("caf") 2 None 3 true 4 false ``` ### Pitfall 3: Expecting a `&str` to be mutable or growable [Section titled “Pitfall 3: Expecting a \&str to be mutable or growable”](#pitfall-3-expecting-a-str-to-be-mutable-or-growable) ```rust 1 fn main() { 2 let greeting: &str = "hello"; 3 greeting.push_str(" world"); // does not compile (error[E0599]) 4 println!("{greeting}"); 5 } ``` Real compiler error: ```text 1 error[E0599]: no method named `push_str` found for reference `&str` in the current scope 2 --> src/main.rs:3:14 3 | 4 3 | greeting.push_str(" world"); // &str has no push_str; also not mutable 5 | ^^^^^^^^ method not found in `&str` ``` To grow text, you need an owned, mutable `String`: `let mut greeting = String::from("hello");`. ### Pitfall 4: Returning a `&str` that borrows a local [Section titled “Pitfall 4: Returning a \&str that borrows a local”](#pitfall-4-returning-a-str-that-borrows-a-local) A function that builds a `String` locally cannot hand back a `&str` into it; the buffer is freed when the function returns: ```rust 1 fn make_greeting() -> &str { // does not compile (error[E0106]) 2 let s = String::from("hello"); 3 &s 4 } ``` Real compiler error (abridged): ```text 1 error[E0106]: missing lifetime specifier 2 --> src/main.rs:1:23 3 | 4 1 | fn make_greeting() -> &str { 5 | ^ expected named lifetime parameter 6 | 7 = help: this function's return type contains a borrowed value, but there is no value for it to be borrowed from 8 help: instead, you are more likely to want to return an owned value 9 | 10 1 - fn make_greeting() -> &str { 11 1 + fn make_greeting() -> String { ``` The compiler’s suggested fix is correct: return an owned `String`. You can only return a `&str` when it borrows from one of the function’s **input** references (so the caller still owns the data); see `first_word` in the Best Practices section. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Accept `&str`, return `String` (the default rule of thumb) [Section titled “Accept \&str, return String (the default rule of thumb)”](#accept-str-return-string-the-default-rule-of-thumb) ```rust 1 fn main() { 2 let owned = String::from("the quick brown fox"); 3 println!("{}", first_word(&owned)); // borrow input, return a borrowed slice 4 } 5 6 // Borrows the input; the returned &str points into the caller's data. 7 fn first_word(s: &str) -> &str { 8 match s.find(' ') { 9 Some(idx) => &s[..idx], 10 None => s, 11 } 12 } ``` Real output: ```text 1 the ``` Returning a `&str` here is fine because it borrows from the `s` parameter, which the caller owns: no dangling reference. When you *create* new text, return an owned `String` instead. ### Build strings with `push_str`/`push` or `format!`, not repeated `+` [Section titled “Build strings with push\_str/push or format!, not repeated +”](#build-strings-with-push_strpush-or-format-not-repeated-) The `+` operator on strings consumes (moves) the left-hand `String` and borrows the right-hand `&str`, which is awkward and easy to get wrong. Prefer `format!` for assembling, or `push_str` in a loop: ```rust 1 fn main() { 2 // `format!` borrows its arguments — nothing is consumed: 3 let a = String::from("foo"); 4 let b = String::from("bar"); 5 let joined = format!("{a}-{b}"); 6 println!("{joined} (a still usable: {a})"); 7 8 // The `+` operator MOVES the left operand: 9 let hello = String::from("Hello, "); 10 let world = String::from("world!"); 11 let combined = hello + &world; // `hello` is moved into `combined` 12 println!("{combined}"); 13 } ``` Real output: ```text 1 foo-bar (a still usable: foo) 2 Hello, world! ``` > **Tip:** Use inline format arguments — `format!("{a}-{b}")` — not the older positional `format!("{}-{}", a, b)`. Both work, but the inline form is the current idiom and reads better. (See [Output](/02-basics/04-output/).) ### Comparing strings is direct [Section titled “Comparing strings is direct”](#comparing-strings-is-direct) Unlike some languages, you compare string contents with `==`, and `String` compares cleanly against `&str` in either order: ```rust 1 fn main() { 2 let name = String::from("alice"); 3 println!("{}", name == "alice"); // true 4 println!("{}", "alice" == name); // true 5 } ``` Real output: ```text 1 true 2 true ``` ### Reserve capacity when building large strings [Section titled “Reserve capacity when building large strings”](#reserve-capacity-when-building-large-strings) If you know roughly how big a `String` will get, `String::with_capacity(n)` pre-allocates and avoids repeated re-allocations as it grows, the same idea as `Vec::with_capacity` (see [Collection Performance](/07-collections/09-collection-performance/)). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small text-normalization module of the kind you’d find in a web backend: canonicalizing user handles, and truncating a bio for display without ever splitting a multi-byte character. Note how every function takes `&str` (so callers pass a `String`, a `&String`, or a literal) and only allocates a `String` when it must build new text. ```rust 1 /// Normalize a user-supplied handle into a canonical form. 2 /// Takes `&str` so callers can pass a `String`, a `&String`, or a literal. 3 fn normalize_handle(raw: &str) -> String { 4 raw.trim() // drop surrounding whitespace 5 .trim_start_matches('@') // strip a leading @ if present 6 .to_lowercase() // case-insensitive handles 7 } 8 9 /// Truncate to at most `max_chars` *characters*, never splitting a 10 /// multi-byte character. Returns a borrowed slice — no allocation. 11 fn truncate_chars(s: &str, max_chars: usize) -> &str { 12 match s.char_indices().nth(max_chars) { 13 // `byte_idx` came from char_indices(), so it IS a char boundary. 14 Some((byte_idx, _)) => &s[..byte_idx], 15 None => s, // fewer than max_chars chars: return the whole thing 16 } 17 } 18 19 fn main() { 20 let from_form = String::from(" @AliceWonderland "); 21 let from_literal = "@Bob"; 22 23 // A &String and a &str both work, because the parameter is &str: 24 println!("{}", normalize_handle(&from_form)); // "alicewonderland" 25 println!("{}", normalize_handle(from_literal)); // "bob" 26 27 // Multi-byte-safe truncation: 28 let bio = "héllo wörld"; // contains 2-byte é and ö 29 println!("{:?}", truncate_chars(bio, 5)); // "héllo" 30 println!("{:?}", truncate_chars(bio, 100)); // whole string 31 32 let kanji = "日本語テスト"; // each kanji is 3 bytes 33 println!("{:?}", truncate_chars(kanji, 2)); // "日本" 34 } ``` Real output: ```text 1 alicewonderland 2 bob 3 "héllo" 4 "héllo wörld" 5 "日本" ``` This passes `cargo clippy` with no warnings. The point: `truncate_chars` returns a borrowed `&str` (zero allocation) precisely because it borrows its input, while `normalize_handle` returns an owned `String` because `to_lowercase()` produces new text that must be owned by *someone*. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [The Rust Book — Storing UTF-8 Encoded Text with Strings](https://doc.rust-lang.org/book/ch08-02-strings.html) * [`std::string::String` API docs](https://doc.rust-lang.org/std/string/struct.String.html) * [`str` primitive API docs](https://doc.rust-lang.org/std/primitive.str.html) * [Rust by Example — Strings](https://doc.rust-lang.org/rust-by-example/std/str.html) * Sibling topics: [String manipulation methods](/07-collections/02-string-manipulation/) · [Vectors (`Vec<T>`)](/07-collections/00-vectors/) · [Iterators](/07-collections/06-iterators/) * Foundations: [Ownership & Borrowing](/05-ownership/) · [Basic Types & `char`](/02-basics/01-types/) · [Output & `format!`](/02-basics/04-output/) * When string operations can fail (e.g. `parse`), see [Error Handling](/08-error-handling/). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Count the vowels [Section titled “Exercise 1: Count the vowels”](#exercise-1-count-the-vowels) **Difficulty:** Beginner **Objective:** Practice iterating over characters with `chars()` instead of reaching for an index. **Instructions:** Write a function `count_vowels(s: &str) -> usize` that returns how many vowels (`a`, `e`, `i`, `o`, `u`, case-insensitive) the string contains. It should satisfy: ```rust 1 fn count_vowels(s: &str) -> usize { 2 // TODO: iterate with .chars() and count the vowels 3 /* ??? */ 4 } 5 6 fn main() { 7 assert_eq!(count_vowels("Hello"), 2); 8 assert_eq!(count_vowels("rhythm"), 0); 9 assert_eq!(count_vowels("AEIOU"), 5); 10 println!("all good"); 11 } ``` Solution ```rust 1 fn count_vowels(s: &str) -> usize { 2 s.chars() 3 .filter(|c| matches!(c.to_ascii_lowercase(), 'a' | 'e' | 'i' | 'o' | 'u')) 4 .count() 5 } 6 7 fn main() { 8 assert_eq!(count_vowels("Hello"), 2); 9 assert_eq!(count_vowels("rhythm"), 0); 10 assert_eq!(count_vowels("AEIOU"), 5); 11 println!("all good"); 12 } ``` `chars()` yields each Unicode character; `matches!` is a compact pattern test, and `count()` consumes the filtered iterator. (Iterator adaptors like `filter` are covered in [Iterators](/07-collections/06-iterators/).) ### Exercise 2: A non-panicking prefix [Section titled “Exercise 2: A non-panicking prefix”](#exercise-2-a-non-panicking-prefix) **Difficulty:** Intermediate **Objective:** Slice by character count without ever panicking on a multi-byte boundary. **Instructions:** Write `safe_prefix(s: &str, n: usize) -> Option<&str>` that returns the first `n` *characters* as a borrowed `&str`. If the string has fewer than `n` characters, return the whole string. The result must always be a valid `&str` (never a panic), so use `char_indices()` to find a real boundary and `.get(..)` for the slice. ```rust 1 fn safe_prefix(s: &str, n: usize) -> Option<&str> { 2 // TODO 3 /* ??? */ 4 } 5 6 fn main() { 7 assert_eq!(safe_prefix("café", 3), Some("caf")); 8 assert_eq!(safe_prefix("café", 4), Some("café")); 9 assert_eq!(safe_prefix("café", 10), Some("café")); 10 assert_eq!(safe_prefix("\u{1F980}x", 1), Some("\u{1F980}")); 11 println!("all good"); 12 } ``` Solution ```rust 1 fn safe_prefix(s: &str, n: usize) -> Option<&str> { 2 match s.char_indices().nth(n) { 3 // The nth char's start byte is a guaranteed boundary. 4 Some((byte_idx, _)) => s.get(..byte_idx), 5 None => Some(s), // fewer than n chars: the whole string 6 } 7 } 8 9 fn main() { 10 assert_eq!(safe_prefix("café", 3), Some("caf")); 11 assert_eq!(safe_prefix("café", 4), Some("café")); 12 assert_eq!(safe_prefix("café", 10), Some("café")); 13 assert_eq!(safe_prefix("\u{1F980}x", 1), Some("\u{1F980}")); 14 println!("all good"); 15 } ``` `char_indices().nth(n)` gives the byte offset where the (n+1)-th character starts — always a char boundary — and `.get(..byte_idx)` slices safely. If `nth(n)` is `None`, the string was shorter than `n` chars, so we return all of it. ### Exercise 3: Title-case a sentence [Section titled “Exercise 3: Title-case a sentence”](#exercise-3-title-case-a-sentence) **Difficulty:** Advanced **Objective:** Build a new `String` from borrowed input, distinguishing where you own versus borrow. **Instructions:** Write `title_case(input: &str) -> String` that uppercases the first character of each whitespace-separated word and lowercases the rest, then joins the words with a single space. Collapse runs of whitespace (use `split_whitespace`). ```rust 1 fn title_case(input: &str) -> String { 2 // TODO 3 /* ??? */ 4 } 5 6 fn main() { 7 assert_eq!(title_case("hello world"), "Hello World"); 8 assert_eq!(title_case(" the QUICK brown "), "The Quick Brown"); 9 assert_eq!(title_case(""), ""); 10 println!("all good"); 11 } ``` Solution ```rust 1 fn title_case(input: &str) -> String { 2 input 3 .split_whitespace() 4 .map(|word| { 5 let mut chars = word.chars(); 6 match chars.next() { 7 Some(first) => { 8 // Uppercase the first char, lowercase the remaining slice. 9 first.to_uppercase().collect::<String>() 10 + &chars.as_str().to_lowercase() 11 } 12 None => String::new(), 13 } 14 }) 15 .collect::<Vec<_>>() 16 .join(" ") 17 } 18 19 fn main() { 20 assert_eq!(title_case("hello world"), "Hello World"); 21 assert_eq!(title_case(" the QUICK brown "), "The Quick Brown"); 22 assert_eq!(title_case(""), ""); 23 println!("all good"); 24 } ``` `split_whitespace()` borrows views into `input` (no allocation) and conveniently skips leading/trailing/duplicate whitespace. Each `map` closure builds an owned `String` per word — note `first.to_uppercase()` returns an iterator (one character can uppercase to several, like `ß`), so we `collect` it into a `String`. `chars.as_str()` hands back the unconsumed remainder as a `&str`. (`collect` and friends are explored in [Iterator Consumers](/07-collections/07-iterator-consumers/).) *** *Next: [String manipulation methods →](/07-collections/02-string-manipulation/)* # String Manipulation > Split, trim, replace, search, and parse text in Rust: a translation table from JavaScript's String.prototype, where many methods return lazy iterators. Splitting, trimming, replacing, searching, parsing, and building text are everyday tasks. In TypeScript these all live on the `String.prototype`; in Rust they are split across `&str` methods, the `String` type, and the iterator system. This page is your translation table. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Most of what you do with JavaScript’s `string` methods (`.split()`, `.trim()`, `.replace()`, `.toUpperCase()`, `parseInt`, building up text) has a direct Rust counterpart on `&str` and `String`. The two big surprises for a TypeScript developer: many “transforming” methods return **iterators** (lazy, zero-allocation) instead of arrays, and you **cannot index a string by integer** (`s[0]` does not compile) because Rust strings are UTF-8 byte sequences, not arrays of characters. > **Note:** This page focuses on *operations*. For the foundational distinction between `String` (owned, growable) and `&str` (a borrowed view), and why slicing happens on byte boundaries, read [Strings](/07-collections/01-strings/) first. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // A small log-line processor — the kind of code you write all the time. 2 function parseLogLine(line: string): { level: string; message: string } { 3 const trimmed = line.trim(); 4 const level = trimmed.split(/\s+/)[1] ?? "UNKNOWN"; 5 const message = trimmed.replace("ERROR", "ERR"); 6 return { level, message }; 7 } 8 9 // Splitting, joining, searching, casing 10 const csv = "name,age,city"; 11 const fields = csv.split(","); // ["name", "age", "city"] 12 const rejoined = fields.join(" | "); // "name | age | city" 13 14 const greeting = "Hello, World"; 15 greeting.toUpperCase(); // "HELLO, WORLD" 16 greeting.includes("World"); // true 17 greeting.startsWith("Hello"); // true 18 greeting.indexOf("o"); // 4 19 20 // Parsing numbers 21 const n = parseInt("42", 10); // 42 22 const f = parseFloat("3.14"); // 3.14 23 const bad = Number("not a number"); // NaN (no error!) 24 25 // Building strings 26 let buf = ""; 27 for (const w of ["a", "b", "c"]) buf += w; // "abc" 28 const bio = `${"Ada"} is ${36}`; // template literal 29 30 // Iterating characters 31 for (const ch of "héllo") console.log(ch); // h é l l o (code points) 32 "hello".length; // 5 33 "héllo".length; // 5 (UTF-16 code units!) ``` Every method above is on the single `string` type, and indexing (`csv[0]`) returns a one-character string. JavaScript hides the underlying UTF-16 representation almost entirely, until you hit emoji or surrogate pairs. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 fn main() { 2 // The same log-line processor. 3 let line = " 2026-05-31 ERROR Disk full on /dev/sda1 "; 4 5 let trimmed = line.trim(); // &str view, no allocation 6 let level = trimmed.split_whitespace().nth(1).unwrap_or("UNKNOWN"); 7 let message = trimmed.replace("ERROR", "ERR"); // allocates a new String 8 println!("level={level} message={message}"); 9 10 // Splitting, joining, searching, casing 11 let csv = "name,age,city"; 12 let fields: Vec<&str> = csv.split(',').collect(); // collect the iterator 13 let rejoined = fields.join(" | "); 14 println!("{rejoined}"); 15 16 let greeting = "Hello, World"; 17 println!("{}", greeting.to_uppercase()); // "HELLO, WORLD" (new String) 18 println!("{}", greeting.contains("World")); // true 19 println!("{}", greeting.starts_with("Hello")); // true 20 println!("{:?}", greeting.find('o')); // Some(4) (byte index) 21 22 // Parsing numbers — returns Result, never silently NaN 23 let n: i32 = "42".parse().unwrap(); // 42 24 let f: f64 = "3.14".parse().unwrap(); // 3.14 25 let bad: Result<i32, _> = "not a number".parse(); // Err(...) 26 println!("{n} {f} {}", bad.is_err()); 27 28 // Building strings 29 let mut buf = String::new(); 30 for w in ["a", "b", "c"] { buf.push_str(w); } // "abc" 31 let bio = format!("{} is {}", "Ada", 36); 32 println!("{buf} / {bio}"); 33 34 // Iterating characters (Unicode scalar values, not bytes) 35 for ch in "héllo".chars() { print!("{ch} "); } 36 println!(); 37 println!("{}", "héllo".len()); // 6 (BYTES, not chars!) 38 println!("{}", "héllo".chars().count()); // 5 (characters) 39 } ``` ```text 1 level=ERROR message=2026-05-31 ERR Disk full on /dev/sda1 2 name | age | city 3 HELLO, WORLD 4 true 5 true 6 Some(4) 7 42 3.14 true 8 abc / Ada is 36 9 h é l l o 10 6 11 5 ``` *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `trim` returns a borrowed slice, `replace` allocates [Section titled “trim returns a borrowed slice, replace allocates”](#trim-returns-a-borrowed-slice-replace-allocates) `line.trim()` returns a `&str` that points *into* the original `line`. No new memory is allocated, it just narrows the start/end. By contrast `trimmed.replace("ERROR", "ERR")` must build a brand-new `String`, because the result has different contents than the input. This split is a recurring theme: **methods that only narrow or scan return borrowed `&str`; methods that produce different text return an owned `String`.** TypeScript hides this distinction because every string is heap-allocated and immutable. ### Splitting produces a lazy iterator, not an array [Section titled “Splitting produces a lazy iterator, not an array”](#splitting-produces-a-lazy-iterator-not-an-array) `csv.split(',')` does **not** give you a `Vec`. It returns a `Split` iterator that yields each piece on demand. That is why we wrote `let fields: Vec<&str> = csv.split(',').collect();`: `.collect()` runs the iterator and gathers the results. If you only need to walk the pieces once, skip the `Vec` entirely and iterate directly: ```rust 1 fn main() { 2 for field in "name,age,city".split(',') { 3 println!("- {field}"); 4 } 5 } ``` This laziness mirrors how Rust treats all sequence transformations; see [Iterators](/07-collections/06-iterators/). ### `find` returns a *byte* index wrapped in `Option` [Section titled “find returns a byte index wrapped in Option”](#find-returns-a-byte-index-wrapped-in-option) JavaScript’s `indexOf` returns `-1` when not found. Rust’s `find` returns `Option<usize>` (`Some(index)` or `None`), so the “not found” case is part of the type and the compiler forces you to handle it. The number it returns is a **byte offset**, which matters for non-ASCII text (more below). ### `parse` returns `Result`, never a silent `NaN` [Section titled “parse returns Result, never a silent NaN”](#parse-returns-result-never-a-silent-nan) `"not a number"` in JavaScript yields `NaN`, a value that silently poisons later arithmetic. Rust’s `.parse()` returns `Result<T, E>` and you must deal with the error. The target type drives the parsing: `let n: i32 = "42".parse()...` or the turbofish form `"42".parse::<i32>()`. Error handling for `Result` is covered in [Error Handling](/08-error-handling/). ### `chars()` vs `bytes()` vs `len()` [Section titled “chars() vs bytes() vs len()”](#chars-vs-bytes-vs-len) A Rust string is UTF-8 bytes. `"héllo".len()` is `6` because `é` takes two bytes. To count **characters** (Unicode scalar values) use `.chars().count()`, which is `5`. JavaScript’s `.length` counts UTF-16 code units, so it gives `5` here but `2` for a single emoji like `"\u{1F600}".length` (a surrogate pair). None of the three languages’ counts agree in general; be explicit about whether you want bytes or characters. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Task | TypeScript/JavaScript | Rust | | ------------------- | ------------------------------- | ------------------------------------------------------- | | Split | `s.split(",")` → array | `s.split(',')` → lazy iterator (`.collect()` for `Vec`) | | Split on whitespace | `s.split(/\s+/)` (regex) | `s.split_whitespace()` (built-in, no regex) | | Split into lines | `s.split("\n")` | `s.lines()` (handles `\n` and `\r\n`) | | Trim | `s.trim()` | `s.trim()` → borrowed `&str` | | Replace all | `s.replaceAll("a","b")` | `s.replace("a", "b")` (all by default) | | Replace first | `s.replace("a","b")` | `s.replacen("a", "b", 1)` | | Uppercase | `s.toUpperCase()` | `s.to_uppercase()` → new `String` | | Contains | `s.includes(x)` | `s.contains(x)` | | Index of | `s.indexOf(x)` → `-1` if absent | `s.find(x)` → `Option<usize>` (byte index) | | Parse int | `parseInt(s)` → `NaN` on fail | `s.parse::<i32>()` → `Result` | | Char access | `s[0]` → 1-char string | `s.chars().nth(0)` → `Option<char>` | | Length | `s.length` (UTF-16 units) | `s.len()` (bytes) / `.chars().count()` (chars) | | Concatenate | `a + b`, `` `${a}${b}` `` | `format!("{a}{b}")`, `a.push_str(b)`, `a + &b` | | Join | `arr.join(", ")` | `arr.join(", ")` | | Repeat | `s.repeat(3)` | `s.repeat(3)` | > **Tip:** When a JavaScript method returns an array (`split`, `match`), the Rust analog almost always returns an **iterator**. Add `.collect::<Vec<_>>()` only when you actually need a collection. ### Why no integer indexing? [Section titled “Why no integer indexing?”](#why-no-integer-indexing) `s[0]` is rejected at compile time in Rust. UTF-8 means byte `0` might be only *half* of a character, so returning “the first character” by byte index would be a footgun. Rust makes you choose your intent: `.chars().next()` for the first character, `.bytes().next()` for the first byte, or `&s[0..n]` for a byte-range slice (which panics if the range falls inside a character). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Trying to index a string by integer [Section titled “Pitfall 1: Trying to index a string by integer”](#pitfall-1-trying-to-index-a-string-by-integer) ```rust 1 fn main() { 2 let s = String::from("hello"); 3 let first = s[0]; // does not compile (error E0277: `str` cannot be indexed by `{integer}`) 4 println!("{first}"); 5 } ``` Real compiler error: ```text 1 error[E0277]: the type `str` cannot be indexed by `{integer}` 2 --> src/main.rs:3:19 3 | 4 3 | let first = s[0]; 5 | ^ string indices are ranges of `usize` 6 | 7 = help: the trait `SliceIndex<str>` is not implemented for `{integer}` 8 = note: you can use `.chars().nth()` or `.bytes().nth()` ``` **Fix:** Use `s.chars().next()` for the first character (returns `Option<char>`), or `&s[0..1]` for a byte slice when you know the boundary is safe. ### Pitfall 2: `parse` without a target type [Section titled “Pitfall 2: parse without a target type”](#pitfall-2-parse-without-a-target-type) ```rust 1 fn main() { 2 let n = "42".parse().unwrap(); // does not compile (error E0284: type annotations needed) 3 println!("{n}"); 4 } ``` Real compiler error: ```text 1 error[E0284]: type annotations needed 2 --> src/main.rs:2:9 3 | 4 2 | let n = "42".parse().unwrap(); 5 | ^ ----- type must be known at this point 6 | 7 help: consider giving `n` an explicit type 8 | 9 2 | let n: /* Type */ = "42".parse().unwrap(); 10 | ++++++++++++ ``` `parse` is generic over *any* type that implements `FromStr`, so the compiler cannot guess. **Fix:** annotate the binding (`let n: i32 = ...`) or use the turbofish (`"42".parse::<i32>()`). ### Pitfall 3: Slicing across a character boundary [Section titled “Pitfall 3: Slicing across a character boundary”](#pitfall-3-slicing-across-a-character-boundary) Byte-range slicing compiles fine but **panics at runtime** if the boundary cuts a multi-byte character in half: ```rust 1 fn main() { 2 let s = "héllo"; // é is 2 bytes, so bytes are: h(0) é(1..3) l(3) l(4) o(5) 3 let sub = &s[0..2]; // panics at runtime: byte 2 is inside 'é' 4 println!("{sub}"); 5 } ``` Real runtime output: ```text 1 thread 'main' panicked at src/main.rs:3:17: 2 byte index 2 is not a char boundary; it is inside 'é' (bytes 1..3) of `héllo` ``` **Fix:** iterate with `.chars()` / `.char_indices()`, or use `.get(0..2)` which returns `Option<&str>` (`None` instead of panicking). ### Pitfall 4: Using a `String` after `+` consumes it [Section titled “Pitfall 4: Using a String after + consumes it”](#pitfall-4-using-a-string-after--consumes-it) The `+` operator takes the left operand **by value** (it moves it): ```rust 1 fn main() { 2 let a = String::from("foo"); 3 let b = String::from("bar"); 4 let c = a + &b; // `a` is moved into the result 5 println!("{a} {c}"); // does not compile (error E0382: borrow of moved value: `a`) 6 } ``` Real compiler error (abridged): ```text 1 error[E0382]: borrow of moved value: `a` 2 --> src/main.rs:5:16 3 | 4 4 | let c = a + &b; 5 | - value moved here 6 5 | println!("{a} {c}"); 7 | ^ value borrowed here after move 8 help: consider cloning the value if the performance cost is acceptable ``` **Fix:** prefer `format!("{a}{b}")` (borrows both, clearer intent), or clone if you genuinely need `a` afterward. Note the asymmetry: with `a + &b`, the left side must be an owned `String` and the right side must be a `&str`. ### Pitfall 5: Expecting `split` to return a `Vec` [Section titled “Pitfall 5: Expecting split to return a Vec”](#pitfall-5-expecting-split-to-return-a-vec) `let parts = "a,b".split(',');` gives you an *iterator*, not a `Vec`. Calling `.len()` on it fails because iterators have no length. **Fix:** add `.collect::<Vec<_>>()` when you need indexing or a length, or call `.count()` to consume it just for the number of items. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Prefer `&str` parameters.** A function that reads text should take `&str`, not `&String`; it accepts both `String` and string literals via deref coercion: ```rust 1 fn shout(s: &str) -> String { s.to_uppercase() } 2 3 fn main() { 4 let owned = String::from("hi"); 5 println!("{}", shout(&owned)); // String coerces to &str 6 println!("{}", shout("there")); // literal works too 7 } ``` * **Use `format!` for readable concatenation**, `push_str`/`push` in hot loops, and `String::with_capacity(n)` when you know the rough output size to avoid reallocations (see [Collection Performance](/07-collections/09-collection-performance/)). * **Reach for the right splitter:** `split_whitespace()` instead of a regex for whitespace; `lines()` instead of `split('\n')` so you get `\r\n` handling for free; `split_once(d)` when you expect exactly one delimiter (returns `Option<(&str, &str)>`). * **Build strings with iterators + `collect()`** for transformations: `text.chars().filter(..).collect::<String>()` is idiomatic and often faster than manual `push` loops. * **Be deliberate about bytes vs chars.** Use `.bytes()` / `.len()` for protocol/encoding work, `.chars()` / `.chars().count()` for user-facing text. * **Use `strip_prefix` / `strip_suffix`** (returning `Option<&str>`) instead of manual slicing to safely peel known prefixes like `"https://"`. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A URL-slug generator, the kind of helper a web backend uses to turn an article title into a clean path segment. It exercises trimming, casing, character classification, filtering, splitting, and joining. ```rust 1 /// Turn an arbitrary title into a lowercase, hyphen-separated slug. 2 /// Non-alphanumeric runs collapse to a single hyphen; edges are trimmed. 3 fn slugify(title: &str) -> String { 4 title 5 .trim() 6 .to_lowercase() 7 .chars() 8 .map(|c| if c.is_alphanumeric() { c } else { '-' }) 9 .collect::<String>() // intermediate: "hello--world---rust---ts" 10 .split('-') // split on the hyphens we inserted 11 .filter(|piece| !piece.is_empty()) // drop the empty runs 12 .collect::<Vec<_>>() 13 .join("-") // re-join with single hyphens 14 } 15 16 fn main() { 17 println!("{}", slugify(" Hello, World! Rust & TS ")); 18 println!("{}", slugify("Café del Mar")); 19 } ``` ```text 1 hello-world-rust-ts 2 café-del-mar ``` Notice how `.is_alphanumeric()` is Unicode-aware: `é` survives the filter and ends up in the slug, exactly as a TypeScript `Intl`-aware implementation would (and unlike a naive `[a-z0-9]` regex, which would strip it). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`str` method documentation](https://doc.rust-lang.org/std/primitive.str.html) — the canonical list of every `&str` method. * [`String` documentation](https://doc.rust-lang.org/std/string/struct.String.html) — owned, growable strings. * [`char` documentation](https://doc.rust-lang.org/std/primitive.char.html) — `is_alphanumeric`, `to_uppercase`, etc. * [The Book: Storing UTF-8 Text with Strings](https://doc.rust-lang.org/book/ch08-02-strings.html) — the official walkthrough. * Related sections in this guide: * [Strings](/07-collections/01-strings/) — `String` vs `&str`, UTF-8, ownership, byte-boundary slicing (read this first). * [Vectors](/07-collections/00-vectors/) — `Vec<T>`, where `split().collect()` results land. * [Iterators](/07-collections/06-iterators/) and [Iterator Consumers](/07-collections/07-iterator-consumers/) — the lazy machinery behind `split`, `chars`, `map`, and `collect`. * [Collection Performance](/07-collections/09-collection-performance/) — when to preallocate string capacity. * [Error Handling](/08-error-handling/) — handling `parse`’s `Result`. * [Output and Formatting](/02-basics/04-output/) — `format!` and `println!` formatting in depth. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Normalize whitespace [Section titled “Exercise 1: Normalize whitespace”](#exercise-1-normalize-whitespace) * **Difficulty:** Easy * **Objective:** Practice splitting and joining. * **Instructions:** Write `fn normalize_whitespace(input: &str) -> String` that collapses every run of whitespace into a single space and trims the ends. `" the quick \n brown fox "` should become `"the quick brown fox"`. ```rust 1 fn normalize_whitespace(input: &str) -> String { 2 // TODO: split on whitespace and re-join with single spaces 3 todo!() 4 } 5 6 fn main() { 7 assert_eq!(normalize_whitespace(" the quick \n brown fox "), "the quick brown fox"); 8 println!("ok"); 9 } ``` Solution ```rust 1 fn normalize_whitespace(input: &str) -> String { 2 input.split_whitespace().collect::<Vec<_>>().join(" ") 3 } 4 5 fn main() { 6 assert_eq!(normalize_whitespace(" the quick \n brown fox "), "the quick brown fox"); 7 println!("ok"); 8 } ``` `split_whitespace()` already drops empty pieces and handles all Unicode whitespace, so a single `join(" ")` finishes the job. Verified output: `ok`. ### Exercise 2: Case-insensitive word frequency [Section titled “Exercise 2: Case-insensitive word frequency”](#exercise-2-case-insensitive-word-frequency) * **Difficulty:** Medium * **Objective:** Combine character filtering, casing, splitting, and a `HashMap`. * **Instructions:** Write `fn word_count(text: &str) -> HashMap<String, usize>` that counts how often each word appears, ignoring case and stripping punctuation. `"The cat sat. The CAT ran!"` should count `cat` → 2, `the` → 2, `sat` → 1, `ran` → 1. ```rust 1 use std::collections::HashMap; 2 3 fn word_count(text: &str) -> HashMap<String, usize> { 4 // TODO: for each whitespace-separated word, strip non-alphanumeric chars, 5 // lowercase it, and bump its count 6 todo!() 7 } 8 9 fn main() { 10 let counts = word_count("The cat sat. The CAT ran!"); 11 assert_eq!(counts.get("cat"), Some(&2)); 12 assert_eq!(counts.get("the"), Some(&2)); 13 println!("ok"); 14 } ``` Solution ```rust 1 use std::collections::HashMap; 2 3 fn word_count(text: &str) -> HashMap<String, usize> { 4 let mut counts = HashMap::new(); 5 for word in text.split_whitespace() { 6 let key: String = word 7 .chars() 8 .filter(|c| c.is_alphanumeric()) 9 .collect::<String>() 10 .to_lowercase(); 11 if !key.is_empty() { 12 *counts.entry(key).or_insert(0) += 1; 13 } 14 } 15 counts 16 } 17 18 fn main() { 19 let counts = word_count("The cat sat. The CAT ran!"); 20 assert_eq!(counts.get("cat"), Some(&2)); 21 assert_eq!(counts.get("the"), Some(&2)); 22 println!("ok"); 23 } ``` The `entry(key).or_insert(0)` pattern is the idiomatic “increment-or-create”; see [HashMaps](/07-collections/03-hashmaps/) for the full entry API. Verified output: `ok`. ### Exercise 3: Mask a credit-card number [Section titled “Exercise 3: Mask a credit-card number”](#exercise-3-mask-a-credit-card-number) * **Difficulty:** Medium/Hard * **Objective:** Practice character classification, building strings, and safe slicing of the *last* N characters. * **Instructions:** Write `fn mask_card(card: &str) -> String` that keeps only the digits, then replaces every digit except the last four with `*`. `"4111 1111 1111 1234"` should become `"************1234"`. If there are four or fewer digits, return them unmasked. ```rust 1 fn mask_card(card: &str) -> String { 2 // TODO: extract digits, then mask all but the last 4 3 todo!() 4 } 5 6 fn main() { 7 assert_eq!(mask_card("4111 1111 1111 1234"), "************1234"); 8 assert_eq!(mask_card("12-34"), "1234"); 9 println!("ok"); 10 } ``` Solution ```rust 1 fn mask_card(card: &str) -> String { 2 let digits: String = card.chars().filter(|c| c.is_ascii_digit()).collect(); 3 let n = digits.len(); 4 if n <= 4 { 5 return digits; 6 } 7 let masked = "*".repeat(n - 4); 8 let last4 = &digits[n - 4..]; // safe: digits are ASCII (1 byte each) 9 format!("{masked}{last4}") 10 } 11 12 fn main() { 13 assert_eq!(mask_card("4111 1111 1111 1234"), "************1234"); 14 assert_eq!(mask_card("12-34"), "1234"); 15 println!("ok"); 16 } ``` Because we filtered to `is_ascii_digit()`, every remaining character is exactly one byte, so the byte slice `&digits[n - 4..]` can never split a character; slicing here is safe. Verified output: `ok`. # HashMaps: `HashMap<K, V>` vs JavaScript Objects and `Map` > Rust's HashMap<K, V> is the typed counterpart to JS objects and Map: get returns Option not undefined, keys and values are owned, plus the entry API. In JavaScript and TypeScript you reach for a plain **object** (`{}`) or a **`Map`** whenever you need to look something up by key. Rust’s equivalent is `std::collections::HashMap<K, V>`, a hash table that maps keys of type `K` to values of type `V`. The data structure is familiar; what’s new is that keys and values are *typed*, *owned*, and the lookup API hands you an `Option` instead of `undefined`. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **`HashMap<K, V>`** stores key→value pairs with average O(1) insert and lookup, just like a JavaScript `Map`. The two ideas a TypeScript/JavaScript developer must internalize: (1) a `HashMap` is **homogeneous**: every key is the same type `K` and every value the same type `V`, unlike a JS object whose values can be anything; and (2) lookups return `Option<&V>` (`Some(&v)` or `None`) rather than silently producing `undefined`, so a missing key is something the compiler makes you handle. In short, a JS object is really two things at once: a record with known fields *and* an ad-hoc dictionary. Rust splits those roles: use a [`struct`](/06-data-structures/00-structs/) when the keys are known at compile time, and a `HashMap` when keys are dynamic data. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // Counting how many times each word appears — a classic dictionary task. 2 function wordFrequency(text: string): Map<string, number> { 3 const freq = new Map<string, number>(); 4 for (const word of text.split(/\s+/)) { 5 // The "insert or increment" dance: read, default, write back. 6 freq.set(word, (freq.get(word) ?? 0) + 1); 7 } 8 return freq; 9 } 10 11 const counts = wordFrequency("the quick brown fox the lazy dog the"); 12 console.log(counts.get("the")); // 3 13 console.log(counts.get("cat")); // undefined ← missing key, no error 14 15 // A plain object works too, but values are typed loosely and keys 16 // are coerced to strings: 17 const config: Record<string, string> = { host: "localhost", port: "8080" }; 18 console.log(config.host); // "localhost" 19 console.log(config.scheme); // undefined ← typo? you find out at runtime 20 21 // Iteration order: a Map preserves insertion order; a plain object 22 // mostly does too (with integer-key caveats). 23 for (const [word, n] of counts) { 24 // ... 25 } ``` **Key points:** * `Map.get` returns the value or `undefined`; nothing forces you to check. * `??` supplies a default during the read-modify-write update. * A `Map` preserves **insertion order**; objects approximately do (with quirks for integer-like keys). * Object values are whatever you put in; TypeScript’s `Record<string, string>` is a *compile-time* promise that the runtime does not enforce. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 use std::collections::HashMap; 2 3 /// Counting how many times each word appears. 4 fn word_frequency(text: &str) -> HashMap<&str, u32> { 5 let mut freq: HashMap<&str, u32> = HashMap::new(); 6 for word in text.split_whitespace() { 7 // The entry API does the "insert or increment" in one step. 8 *freq.entry(word).or_insert(0) += 1; 9 } 10 freq 11 } 12 13 fn main() { 14 let counts = word_frequency("the quick brown fox the lazy dog the"); 15 16 // get returns Option<&V>: Some(&3) or None — never a silent undefined. 17 println!("the: {:?}", counts.get("the")); // Some(3) 18 println!("cat: {:?}", counts.get("cat")); // None 19 } ``` Running it prints: ```text 1 the: Some(3) 2 cat: None ``` **Key points:** * `HashMap::new()` needs a type, here inferred from the annotation `HashMap<&str, u32>`. * The values are `u32` — *every* value is a `u32`, enforced at compile time. There is no “values can be anything” mode. * `freq.entry(word).or_insert(0)` returns a `&mut u32` you can increment in place; no separate read-then-write. * `get` returns `Option<&V>`. A missing key is `None`, a real value you must deal with, not `undefined`. > **Note:** A standard-library `HashMap` does **not** preserve insertion order, and the order is intentionally randomized per program run (a defense against hash-collision DoS attacks). If you need ordering, see [Key Differences](#key-differences) and the sibling [Sorted Collections](/07-collections/05-btreemap-btreeset/). *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Creating and typing a map [Section titled “Creating and typing a map”](#creating-and-typing-a-map) ```rust 1 use std::collections::HashMap; 2 3 let mut scores: HashMap<String, u32> = HashMap::new(); ``` Unlike `Vec` and `String`, `HashMap` is **not** in the [prelude](/01-getting-started/02-hello-world/), so you must `use std::collections::HashMap;` first. The type parameters `<String, u32>` fix the key and value types for the entire map’s life. Compare this to TypeScript’s `Map<string, number>`: same shape of annotation, but in Rust it is a hard guarantee the compiler enforces, not an erasable hint. If you immediately insert values, inference can often figure the types out, so the annotation is optional: ```rust 1 let mut scores = HashMap::new(); 2 scores.insert(String::from("Blue"), 10u32); // now K = String, V = u32 ``` ### `insert`: returns the *previous* value [Section titled “insert: returns the previous value”](#insert-returns-the-previous-value) ```rust 1 let mut scores: HashMap<String, u32> = HashMap::new(); 2 scores.insert(String::from("Blue"), 10); 3 let old = scores.insert(String::from("Blue"), 25); // overwrites 4 println!("old Blue value: {old:?}"); // old Blue value: Some(10) ``` `insert` overwrites an existing key and **returns the old value as `Option<V>`** (`None` if the key was new). JavaScript’s `map.set(k, v)` returns the map itself for chaining; Rust returns the displaced value, which is occasionally handy and never a `Map` for chaining. ### `get`, `contains_key`, `remove` [Section titled “get, contains\_key, remove”](#get-contains_key-remove) ```rust 1 println!("{:?}", scores.get("Blue")); // Some(25) — note: &str key works 2 println!("{}", scores.contains_key("Red")); // false 3 let removed = scores.remove("Blue"); // Some(25), and the key is gone ``` A subtle convenience: even though the key type is `String`, you can look up with a `&str` (`"Blue"`) because `String` *borrows as* `str`. This is the `Borrow` trait at work — you don’t have to allocate a `String` just to do a lookup. The closest JS analogy is that you never need to “rebuild” a key to read; here the type system makes the cheap path the default. `get` returns `Option<&V>`, a **reference** into the map, not a copy. To get an owned value out, combine with `Option` methods (covered in [The Option Type](/06-data-structures/03-option-enum/)): ```rust 1 let config: HashMap<&str, &str> = 2 HashMap::from([("host", "localhost"), ("port", "8080")]); 3 4 // .copied() turns Option<&&str> into Option<&str>; unwrap_or supplies a default. 5 let host = config.get("host").copied().unwrap_or("0.0.0.0"); 6 let scheme = config.get("scheme").copied().unwrap_or("http"); 7 println!("host={host} scheme={scheme}"); // host=localhost scheme=http ``` This is the typed, explicit version of JavaScript’s `config.host ?? "0.0.0.0"`. ### The `entry` API: Rust’s killer feature for maps [Section titled “The entry API: Rust’s killer feature for maps”](#the-entry-api-rusts-killer-feature-for-maps) The “get the value, or insert a default, then mutate it” pattern is so common that Rust gives it a dedicated, allocation-aware API. `entry(key)` returns an `Entry`, a handle to a slot that may or may not be occupied: ```rust 1 let mut counts: HashMap<&str, i32> = HashMap::new(); 2 3 // or_insert: if absent, insert this default; either way, return &mut V. 4 counts.entry("apple").or_insert(0); 5 counts.entry("apple").or_insert(99); // already present → 99 is ignored 6 println!("{}", counts["apple"]); // 0 7 8 // The increment idiom: deref the returned &mut and add. 9 *counts.entry("apple").or_insert(0) += 1; 10 println!("{}", counts["apple"]); // 1 ``` `or_insert` returns a `&mut V` pointing at the slot, so `*entry += 1` mutates in place. In JavaScript you’d write `m.set(k, (m.get(k) ?? 0) + 1)` — two hash lookups (a `get` and a `set`) and a temporary. The Rust entry API does a **single** lookup. For richer logic, `and_modify` updates an existing value and `or_insert` provides the first one: ```rust 1 let mut hits: HashMap<&str, u32> = HashMap::new(); 2 hits.entry("/").and_modify(|c| *c += 1).or_insert(1); // first hit → 1 3 hits.entry("/").and_modify(|c| *c += 1).or_insert(1); // second hit → 2 4 println!("{}", hits["/"]); // 2 ``` When the default itself is expensive to build, use `or_insert_with(|| ...)` so the closure only runs on a miss, or `or_default()` when `V: Default`: ```rust 1 // Grouping: each new department gets a fresh Vec, then we push into it. 2 let people = [("eng", "Alice"), ("sales", "Bob"), ("eng", "Carol")]; 3 let mut by_dept: HashMap<&str, Vec<&str>> = HashMap::new(); 4 for (dept, name) in people { 5 by_dept.entry(dept).or_default().push(name); 6 } 7 // by_dept now: {"eng": ["Alice", "Carol"], "sales": ["Bob"]} ``` ### Iteration [Section titled “Iteration”](#iteration) ```rust 1 let mut roster: HashMap<String, u32> = HashMap::new(); 2 roster.insert("Alice".into(), 30); 3 roster.insert("Bob".into(), 25); 4 5 for (name, age) in &roster { // borrow: (&String, &u32) 6 println!("{name} is {age}"); 7 } 8 9 for age in roster.values_mut() { // mutable borrow of each value 10 *age += 1; // everyone has a birthday 11 } 12 13 let names: Vec<&String> = roster.keys().collect(); // just the keys 14 let ages: Vec<u32> = roster.values().copied().collect(); // just the values ``` `iter()` / `&map` yields `(&K, &V)` tuples; `keys()` and `values()` yield only one side; `values_mut()` yields `&mut V` for in-place updates; and `into_iter()` (i.e. `for (k, v) in map`) **consumes** the map and yields owned `(K, V)` pairs. The big difference from JavaScript: **iteration order is unspecified and randomized per run**, so never rely on it. To produce stable output, collect into a `Vec` and sort: ```rust 1 let mut pairs: Vec<(&String, &u32)> = roster.iter().collect(); 2 pairs.sort_by_key(|(name, _)| *name); // deterministic, alphabetical ``` ### Ownership of keys and values [Section titled “Ownership of keys and values”](#ownership-of-keys-and-values) This is where Rust departs most sharply from JavaScript. `insert(k, v)` **moves** `k` and `v` into the map: the map *owns* them: ```rust 1 let key = String::from("name"); 2 let value = String::from("Ada"); 3 let mut map = HashMap::new(); 4 map.insert(key, value); 5 // `key` and `value` are moved; using them now is a compile error (see Pitfalls). ``` For `Copy` types (`i32`, `bool`, `char`, `&str`, …), “move” is a bitwise copy and the original stays usable. For owned types like `String` or `Vec`, the map takes ownership; see [Move, Copy, and Clone](/05-ownership/06-move-copy-clone/). This is exactly the discipline that lets a `HashMap` free all its keys and values automatically when it goes out of scope, with no garbage collector. > **Tip:** A key type must implement `Eq` and `Hash`. All the obvious types do (`String`, `&str`, integers, `char`, tuples of hashable things, and any `struct`/`enum` you annotate with `#[derive(PartialEq, Eq, Hash)]`). Notably `f64` does **not** implement `Eq` (because `NaN != NaN`), so you can’t use a float as a key without extra work. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | JS object / `Map` | Rust `HashMap<K, V>` | | -------------------- | -------------------------------------------- | --------------------------------------------- | | Key types | Object: string/symbol only. `Map`: any value | Any type that is `Eq + Hash` | | Value types | Anything (heterogeneous) | Exactly one type `V` (homogeneous) | | Missing key | `undefined` (silent) | `Option<&V>` → `None` (must handle) | | Iteration order | `Map` preserves insertion order | **Unspecified & randomized** | | Read-modify-write | Two lookups (`get` + `set`) | One lookup via the `entry` API | | Ownership | GC-managed references | Map **owns** its keys and values | | Lookup by alt type | n/a | `&str` looks up a `String` key (via `Borrow`) | | Indexing missing key | `obj[k]` → `undefined` | `map[k]` → **panics** | | Default hasher | engine-defined | SipHash 1-3 (DoS-resistant, not the fastest) | ### Missing keys: `None` vs panic [Section titled “Missing keys: None vs panic”](#missing-keys-none-vs-panic) There are two ways to read a key, and they differ on what “missing” means: * `map.get(k)` → `Option<&V>`. The safe, idiomatic choice. Missing key is `None`. * `map[k]` (the `Index` operator) → `&V`, but **panics** if the key is absent. Use indexing only when you are certain the key exists; otherwise use `get`. This mirrors `Vec` indexing in [Vectors](/07-collections/00-vectors/): the convenient `[]` syntax trades safety for brevity. ### Homogeneous values [Section titled “Homogeneous values”](#homogeneous-values) A JS object happily holds `{ id: 1, name: "Ada", active: true }`. A Rust `HashMap` cannot — every value is one type. That’s a feature: if your keys are *known field names*, you want a `struct`, which is checked at compile time and has zero hashing overhead. Reach for `HashMap` when the **keys are data** (user IDs, words, SKUs) rather than a fixed schema. To store genuinely mixed value types under string keys, you’d use an `enum` as the value (see [Enums and Data-Carrying Variants](/06-data-structures/02-enums/)) — making the “anything” explicit and type-checked. ### The hasher [Section titled “The hasher”](#the-hasher) Rust’s default hasher is **SipHash 1-3**, chosen for resistance to hash-flooding denial-of-service attacks, not raw speed. For internal, untrusted-input-free maps where speed matters, you can swap in a faster hasher (e.g. the `ahash` or `rustc-hash` crates) via `HashMap::with_hasher` / a type alias. Most code never needs to; mentioned here so the analogy to JS’s opaque hashing is honest. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Using a key or value after inserting it [Section titled “Pitfall 1: Using a key or value after inserting it”](#pitfall-1-using-a-key-or-value-after-inserting-it) In JavaScript, `map.set(key, value)` leaves your `key`/`value` variables fully usable afterward. In Rust, inserting an owned value **moves** it into the map: ```rust 1 use std::collections::HashMap; 2 3 fn main() { 4 let key = String::from("name"); 5 let value = String::from("Ada"); 6 let mut map = HashMap::new(); 7 map.insert(key, value); 8 println!("{key}"); // does not compile (error[E0382]: borrow of moved value: `key`) 9 } ``` The real compiler error: ```text 1 error[E0382]: borrow of moved value: `key` 2 --> src/main.rs:8:16 3 | 4 4 | let key = String::from("name"); 5 | --- move occurs because `key` has type `String`, which does not implement the `Copy` trait 6 ... 7 7 | map.insert(key, value); 8 | --- value moved here 9 8 | println!("{key}"); // use after move 10 | ^^^ value borrowed here after move 11 | 12 help: consider cloning the value if the performance cost is acceptable 13 | 14 7 | map.insert(key.clone(), value); 15 | ++++++++ ``` **Fix:** if you still need the original, `insert(key.clone(), value)`; or store `&str` keys instead of `String` when the strings outlive the map; or simply read the value back out of the map. The compiler’s suggestion to `.clone()` is the easy escape hatch. ### Pitfall 2: Indexing a key that might not exist [Section titled “Pitfall 2: Indexing a key that might not exist”](#pitfall-2-indexing-a-key-that-might-not-exist) `obj["missing"]` in JavaScript is just `undefined`. The Rust `Index` operator panics: ```rust 1 use std::collections::HashMap; 2 3 fn main() { 4 let scores: HashMap<&str, i32> = HashMap::from([("Blue", 10)]); 5 let v = scores["Red"]; // missing key 6 println!("{v}"); 7 } ``` This compiles but panics at runtime: ```text 1 thread 'main' panicked at src/main.rs:5:19: 2 no entry found for key 3 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` **Fix:** use `get`, which returns `Option`, and decide what a miss means: ```rust 1 let v = scores.get("Red").copied().unwrap_or(0); ``` ### Pitfall 3: Trying to mutate through `get` [Section titled “Pitfall 3: Trying to mutate through get”](#pitfall-3-trying-to-mutate-through-get) `get` returns an **immutable** reference `&V`, so you cannot write through it. This trips up developers expecting `map.get(k)` to behave like a mutable JS slot: ```rust 1 use std::collections::HashMap; 2 3 fn main() { 4 let mut scores: HashMap<&str, i32> = HashMap::from([("Blue", 10)]); 5 if let Some(s) = scores.get("Blue") { 6 *s += 1; // does not compile (error[E0594]: cannot assign to `*s`, behind a `&` reference) 7 } 8 println!("{scores:?}"); 9 } ``` The core of the real error: ```text 1 error[E0594]: cannot assign to `*s`, which is behind a `&` reference 2 --> src/main.rs:6:9 3 | 4 5 | if let Some(s) = scores.get("Blue") { 5 | - consider changing this binding's type to be: `&mut i32` 6 6 | *s += 1; // s is &i32, not &mut i32 7 | ^^^^^^^ `s` is a `&` reference, so the data it refers to cannot be written ``` **Fix:** use `get_mut` (returns `Option<&mut V>`) or, better for “update or insert”, the `entry` API: ```rust 1 if let Some(s) = scores.get_mut("Blue") { 2 *s += 1; 3 } 4 // or: 5 *scores.entry("Blue").or_insert(0) += 1; ``` ### Pitfall 4: Holding a borrow from the map while modifying it [Section titled “Pitfall 4: Holding a borrow from the map while modifying it”](#pitfall-4-holding-a-borrow-from-the-map-while-modifying-it) Rust forbids reading a reference *into* the map while you also mutate the map (which might reallocate and invalidate that reference). This is the borrow checker, the same rule you meet with `Vec`: ```rust 1 use std::collections::HashMap; 2 3 fn main() { 4 let mut map: HashMap<&str, i32> = HashMap::from([("a", 1)]); 5 let first = map.get("a").unwrap(); // immutable borrow starts 6 map.insert("b", 2); // mutable borrow while `first` is live 7 println!("{first}"); 8 } ``` The real error: ```text 1 error[E0502]: cannot borrow `map` as mutable because it is also borrowed as immutable 2 --> src/main.rs:6:5 3 | 4 5 | let first = map.get("a").unwrap(); // immutable borrow starts 5 | --- immutable borrow occurs here 6 6 | map.insert("b", 2); // mutable borrow while `first` is live 7 | ^^^^^^^^^^^^^^^^^^ mutable borrow occurs here 8 7 | println!("{first}"); // immutable borrow used here 9 | ----- immutable borrow later used here ``` **Fix:** finish using the borrowed value first, or copy it out (`let first = *map.get("a").unwrap();`) before mutating. See [Borrowing and References](/05-ownership/02-borrowing/). ### Pitfall 5: Expecting deterministic iteration order [Section titled “Pitfall 5: Expecting deterministic iteration order”](#pitfall-5-expecting-deterministic-iteration-order) ```rust 1 // The order of these is NOT stable across runs — never assert on it directly. 2 for (k, v) in &map { /* ... */ } ``` If a test or output depends on order, collect into a `Vec` and `sort` (as shown earlier), or use a `BTreeMap` ([Sorted Collections](/07-collections/05-btreemap-btreeset/)) which keeps keys sorted. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Prefer `get` over indexing.** `map.get(k)` makes “absent” a value you handle; `map[k]` panics. Reserve `[]` for keys you have proven exist. * **Use the `entry` API for read-modify-write.** `*map.entry(k).or_insert(0) += 1` is one lookup, no temporaries, and reads cleanly. Avoid the `if contains_key { get } else { insert }` dance. * **Pick `or_default` / `or_insert_with` to avoid building unused defaults.** `or_insert(expensive())` always evaluates `expensive()`; `or_insert_with(|| expensive())` only does so on a miss. * **Choose key types deliberately.** `&str` keys avoid allocation when the strings live long enough; `String` keys when the map must own them. Look up with `&str` even when the key is `String`. * **Reach for a `struct` when keys are a fixed schema,** and a `HashMap` when keys are runtime data. Don’t model a known record as `HashMap<String, _>`. * **Pre-size with `HashMap::with_capacity(n)`** when you know roughly how many entries you’ll insert, to cut down on rehashing: the same idea as `Vec::with_capacity`, covered in [Collection Performance](/07-collections/09-collection-performance/). * **Derive `#[derive(PartialEq, Eq, Hash)]`** on any custom type you want to use as a key, and remember floats can’t be keys without a wrapper. * **Sort before printing** if output must be deterministic; never rely on iteration order. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) Aggregating per-key totals in a single pass is a daily task: order line items by SKU, request counts by route, error counts by type. Here we summarize an order into per-SKU units and revenue using the `entry` API, then print a sorted report. ```rust 1 use std::collections::HashMap; 2 3 /// One line of an order: which SKU and how many units at what price. 4 #[derive(Debug)] 5 struct LineItem { 6 sku: String, 7 quantity: u32, 8 unit_price_cents: u64, 9 } 10 11 /// Aggregate per-SKU totals across many line items in a single pass. 12 /// Value is a (units, revenue_cents) tuple. 13 fn summarize(items: &[LineItem]) -> HashMap<String, (u32, u64)> { 14 let mut totals: HashMap<String, (u32, u64)> = HashMap::new(); 15 for item in items { 16 // One lookup per item: get-or-create the slot, then update it. 17 let entry = totals.entry(item.sku.clone()).or_insert((0, 0)); 18 entry.0 += item.quantity; 19 entry.1 += item.quantity as u64 * item.unit_price_cents; 20 } 21 totals 22 } 23 24 fn main() { 25 let orders = vec![ 26 LineItem { sku: "WIDGET".into(), quantity: 3, unit_price_cents: 250 }, 27 LineItem { sku: "GADGET".into(), quantity: 1, unit_price_cents: 999 }, 28 LineItem { sku: "WIDGET".into(), quantity: 2, unit_price_cents: 250 }, 29 LineItem { sku: "GIZMO".into(), quantity: 5, unit_price_cents: 120 }, 30 ]; 31 32 let totals = summarize(&orders); 33 34 // HashMap order is unspecified, so collect + sort for a stable report. 35 let mut rows: Vec<(&String, &(u32, u64))> = totals.iter().collect(); 36 rows.sort_by(|a, b| b.1.1.cmp(&a.1.1)); // by revenue, descending 37 38 println!("{:<8} {:>5} {:>10}", "SKU", "UNITS", "REVENUE"); 39 for (sku, (units, revenue_cents)) in rows { 40 println!("{sku:<8} {units:>5} {:>9.2}", *revenue_cents as f64 / 100.0); 41 } 42 43 let grand: u64 = totals.values().map(|(_, rev)| rev).sum(); 44 println!("grand total: ${:.2}", grand as f64 / 100.0); 45 } ``` Output: ```text 1 SKU UNITS REVENUE 2 WIDGET 5 12.50 3 GADGET 1 9.99 4 GIZMO 5 6.00 5 grand total: $28.49 ``` The interesting line is `totals.entry(item.sku.clone()).or_insert((0, 0))`: it does a single hash lookup that either finds the existing `(units, revenue)` tuple or inserts a fresh `(0, 0)`, returning a `&mut (u32, u64)` either way. The JavaScript version of this aggregation typically does two `Map` operations per item (`get` then `set`) plus an object spread; the Rust version does one, with the types guaranteeing every value is a `(u32, u64)`. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`std::collections::HashMap`](https://doc.rust-lang.org/std/collections/struct.HashMap.html) — the full API reference * [`std::collections::hash_map::Entry`](https://doc.rust-lang.org/std/collections/hash_map/enum.Entry.html) — the entry API in detail * [The Rust Programming Language — Storing Keys with Associated Values in Hash Maps](https://doc.rust-lang.org/book/ch08-03-hash-maps.html) * [Rust by Example — HashMap](https://doc.rust-lang.org/rust-by-example/std/hash.html) * Sibling topics: [Vectors](/07-collections/00-vectors/) · [Strings](/07-collections/01-strings/) · [Sets and HashSet](/07-collections/04-hashsets/) · [Sorted Collections](/07-collections/05-btreemap-btreeset/) · [Iterators](/07-collections/06-iterators/) · [Iterator Consumers](/07-collections/07-iterator-consumers/) · [Collection Performance](/07-collections/09-collection-performance/) * Background: [Section 05 — Ownership & Move/Copy/Clone](/05-ownership/06-move-copy-clone/) · [Section 06 — Structs](/06-data-structures/00-structs/) · [Option](/06-data-structures/03-option-enum/) * What’s next: a missing key as a recoverable error in [Section 08 — Error Handling](/08-error-handling/) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Tally votes [Section titled “Exercise 1: Tally votes”](#exercise-1-tally-votes) **Difficulty:** Beginner **Objective:** Practice the `entry` API for counting. **Instructions:** Write `fn count_votes(votes: &[&str]) -> HashMap<String, u32>` that counts how many times each candidate name appears in `votes`. Use the entry API so each name is looked up once. In `main`, count `["yes", "no", "yes", "yes", "no"]` and print the totals for `"yes"` and `"no"`. Solution ```rust 1 use std::collections::HashMap; 2 3 fn count_votes(votes: &[&str]) -> HashMap<String, u32> { 4 let mut tally: HashMap<String, u32> = HashMap::new(); 5 for &v in votes { 6 *tally.entry(v.to_string()).or_insert(0) += 1; 7 } 8 tally 9 } 10 11 fn main() { 12 let votes = ["yes", "no", "yes", "yes", "no"]; 13 let tally = count_votes(&votes); 14 println!("yes={} no={}", tally["yes"], tally["no"]); 15 } ``` Output: ```text 1 yes=3 no=2 ``` ### Exercise 2: Invert a map [Section titled “Exercise 2: Invert a map”](#exercise-2-invert-a-map) **Difficulty:** Intermediate **Objective:** Iterate a map and build a new one, practicing ownership of keys/values via `clone` and `collect`. **Instructions:** Write `fn invert(map: &HashMap<String, String>) -> HashMap<String, String>` that returns a new map with keys and values swapped (assume values are unique). Build it from an iterator with `.map(...).collect()`. In `main`, invert a small phone book (`name → number`) and look up a name by number. > **Tip:** `map.iter()` yields `(&String, &String)`. Since the new map must *own* its strings, `.clone()` each side inside the closure. Solution ```rust 1 use std::collections::HashMap; 2 3 fn invert(map: &HashMap<String, String>) -> HashMap<String, String> { 4 map.iter().map(|(k, v)| (v.clone(), k.clone())).collect() 5 } 6 7 fn main() { 8 let mut phone = HashMap::new(); 9 phone.insert("Alice".to_string(), "555-1234".to_string()); 10 phone.insert("Bob".to_string(), "555-9999".to_string()); 11 12 let by_number = invert(&phone); 13 println!("{:?}", by_number.get("555-1234")); // Some("Alice") 14 } ``` Output: ```text 1 Some("Alice") ``` ### Exercise 3: Merge two maps, summing collisions [Section titled “Exercise 3: Merge two maps, summing collisions”](#exercise-3-merge-two-maps-summing-collisions) **Difficulty:** Advanced **Objective:** Combine cloning, the entry API, and deterministic sorted output. **Instructions:** Write `fn merge_sum(a: &HashMap<String, i64>, b: &HashMap<String, i64>) -> HashMap<String, i64>` that returns a new map containing every key from both inputs; when a key appears in both, its value is the **sum**. Start from a clone of `a` and fold `b` in with the entry API. In `main`, merge `{a:1, b:2}` with `{b:40, c:100}` and print the result with keys in sorted order. > **Tip:** Iteration order is unspecified, so collect the keys into a `Vec`, `sort` them, and index the map to print in a stable order. Solution ```rust 1 use std::collections::HashMap; 2 3 fn merge_sum( 4 a: &HashMap<String, i64>, 5 b: &HashMap<String, i64>, 6 ) -> HashMap<String, i64> { 7 let mut out = a.clone(); 8 for (k, v) in b { 9 *out.entry(k.clone()).or_insert(0) += v; 10 } 11 out 12 } 13 14 fn main() { 15 let mut a = HashMap::new(); 16 a.insert("a".to_string(), 1); 17 a.insert("b".to_string(), 2); 18 19 let mut b = HashMap::new(); 20 b.insert("b".to_string(), 40); 21 b.insert("c".to_string(), 100); 22 23 let merged = merge_sum(&a, &b); 24 25 let mut keys: Vec<&String> = merged.keys().collect(); 26 keys.sort(); 27 for k in keys { 28 println!("{k} => {}", merged[k]); 29 } 30 } ``` Output: ```text 1 a => 1 2 b => 42 3 c => 100 ``` # Sets and HashSet > Rust's HashSet<T> is the JS Set for unique values, with insert returning a bool and built-in union, intersection, and difference set algebra. Rust’s `HashSet<T>` is the standard hash-based collection of **unique** values: the direct counterpart to the JavaScript `Set`. If you have ever reached for `new Set()` to deduplicate an array or to answer “have I seen this before?”, you already know the use case; this page shows the idiomatic Rust version and the rich set algebra Rust gives you out of the box. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **`HashSet<T>`** stores each value at most once, with average **O(1)** insertion, removal, and membership checks. Unlike a JavaScript `Set`, a Rust `HashSet` is **homogeneous** (every element is the same type `T`), elements must be **hashable and comparable** (`T: Hash + Eq`), and iteration order is **unspecified and randomized**. Rust also ships first-class **set operations** (`union`, `intersection`, `difference`, and `symmetric_difference`) as methods and operators, which JavaScript only standardized very recently. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // Track which user IDs have already seen a feature flag, then reason about roles. 2 const seen = new Set<number>(); 3 4 const events = [10, 20, 10, 30, 20, 10]; 5 let firstTime = 0; 6 for (const id of events) { 7 if (!seen.has(id)) { 8 seen.add(id); 9 firstTime++; 10 } 11 } 12 13 console.log("unique users:", seen.size); // 3 14 console.log("first-time impressions:", firstTime); // 3 15 console.log("has user 20:", seen.has(20)); // true 16 17 // Set algebra. Native Set methods (union/intersection/difference) only landed 18 // in Node 22 / ES2024; before that everyone hand-rolled these with spreads. 19 const granted = new Set(["read", "write", "deploy"]); 20 const required = new Set(["read", "deploy", "admin"]); 21 22 const missing = required.difference(granted); // Set { 'admin' } 23 const hasAll = required.isSubsetOf(granted); // false 24 console.log([...missing], hasAll); 25 26 // The classic one-liner: deduplicate an array. 27 const unique = [...new Set(["a", "b", "a", "c", "b"])]; // ['a', 'b', 'c'] 28 console.log(unique); ``` **Key points:** * A `Set` can hold values of mixed types (`new Set([1, "a", {}])`). * `has`, `add`, and `delete` are the core operations. * Membership uses **SameValueZero** equality (reference equality for objects — two distinct `{x:1}` objects are *different* members). * Insertion order is **preserved** and iteration is deterministic. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 use std::collections::HashSet; 2 3 fn main() { 4 // Track which user IDs have already been seen. 5 let mut seen: HashSet<u64> = HashSet::new(); 6 7 let events = [10u64, 20, 10, 30, 20, 10]; 8 let mut first_time = 0; 9 for id in events { 10 // `insert` returns `true` if the value was NOT already present. 11 if seen.insert(id) { 12 first_time += 1; 13 } 14 } 15 16 println!("unique users: {}", seen.len()); // 3 17 println!("first-time impressions: {first_time}"); // 3 18 println!("has user 20: {}", seen.contains(&20)); // true 19 20 // Set algebra — built in since Rust 1.0. 21 let granted: HashSet<&str> = HashSet::from(["read", "write", "deploy"]); 22 let required: HashSet<&str> = HashSet::from(["read", "deploy", "admin"]); 23 24 let missing: Vec<&str> = required.difference(&granted).copied().collect(); 25 let has_all = required.is_subset(&granted); 26 println!("missing: {missing:?}, has_all: {has_all}"); // missing: ["admin"], has_all: false 27 28 // Deduplicate by collecting into a HashSet. 29 let unique: HashSet<&str> = ["a", "b", "a", "c", "b"].into_iter().collect(); 30 println!("unique count: {}", unique.len()); // 3 31 } ``` Running this prints (your exact ordering for `missing` will be stable here because it has one element, but multi-element sets print in random order): ```text 1 unique users: 3 2 first-time impressions: 3 3 has user 20: true 4 missing: ["admin"], has_all: false 5 unique count: 3 ``` **Key points:** * `HashSet<T>` is **homogeneous**: one element type, checked at compile time. * `insert` and `remove` return a `bool` telling you whether the set changed. * `contains` takes a **reference** (`&20`), not the value. * The element type must satisfy `Hash + Eq` (see [Key Differences](#key-differences)). *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Importing and constructing [Section titled “Importing and constructing”](#importing-and-constructing) `HashSet` lives in `std::collections`, so it always needs a `use` line. There is no `Set` in the prelude the way `Vec` and `String` are: ```rust 1 use std::collections::HashSet; 2 3 fn main() { 4 // Empty, type annotated. 5 let mut a: HashSet<String> = HashSet::new(); 6 a.insert("rust".to_string()); 7 8 // Preallocate buckets when you know roughly how many elements you'll store. 9 let mut b: HashSet<u32> = HashSet::with_capacity(100); 10 b.insert(1); 11 12 // From an array literal (Rust 1.56+). Type inferred from the elements. 13 let c = HashSet::from([1, 2, 3, 4]); 14 15 // From any iterator via `collect`. 16 let d: HashSet<i32> = (1..=5).collect(); 17 18 println!("{} {} {} {}", a.len(), b.len(), c.len(), d.len()); // 1 1 4 5 19 } ``` > **Note:** Unlike `Vec` (which has the `vec!` macro), there is no `set!` macro in the standard library. Use `HashSet::from([...])` or `.collect()`. ### `insert` and `remove` return whether the set changed [Section titled “insert and remove return whether the set changed”](#insert-and-remove-return-whether-the-set-changed) This is the single most useful difference from JavaScript’s `add`/`delete`, which return the set and a boolean respectively but are rarely used for their return value. In Rust the return value is *the* idiomatic way to do “insert if new”: ```rust 1 use std::collections::HashSet; 2 3 fn main() { 4 let mut tags: HashSet<String> = HashSet::new(); 5 6 let added = tags.insert("wasm".to_string()); // true — newly inserted 7 let again = tags.insert("wasm".to_string()); // false — already present 8 println!("added = {added}, again = {again}"); 9 10 let removed = tags.remove("wasm"); // true — it was there 11 let missing = tags.remove("nope"); // false — wasn't there 12 println!("removed = {removed}, missing = {missing}"); 13 } ``` Output: ```text 1 added = true, again = false 2 removed = true, missing = false ``` ### Membership: `contains`, `get`, and `take` [Section titled “Membership: contains, get, and take”](#membership-contains-get-and-take) ```rust 1 use std::collections::HashSet; 2 3 fn main() { 4 let words: HashSet<String> = HashSet::from(["rust".to_string()]); 5 6 // `contains` borrows the query. Thanks to the `Borrow` trait you can query a 7 // HashSet<String> with a &str — no allocation needed. 8 println!("{}", words.contains("rust")); // true 9 10 // `get` returns Option<&T> — useful when the stored value carries more than 11 // the part you compare on. 12 println!("{:?}", words.get("rust")); // Some("rust") 13 println!("{:?}", words.get("go")); // None 14 15 // `take` removes and hands you back the owned value. 16 let mut owned: HashSet<String> = HashSet::from(["a".to_string(), "b".to_string()]); 17 let taken = owned.take("a"); // Some("a") 18 println!("{:?}, len {}", taken, owned.len()); // Some("a"), len 1 19 } ``` ### Set operations return lazy iterators [Section titled “Set operations return lazy iterators”](#set-operations-return-lazy-iterators) `union`, `intersection`, `difference`, and `symmetric_difference` do **not** allocate a new set. They return an **iterator** of references (`&T`) that you consume, typically with `.collect()` or `.copied()/.cloned()` first. This is consistent with Rust’s [lazy iterator philosophy](/07-collections/06-iterators/). ```rust 1 use std::collections::HashSet; 2 3 fn main() { 4 let a: HashSet<i32> = HashSet::from([1, 2, 3, 4]); 5 let b: HashSet<i32> = HashSet::from([3, 4, 5, 6]); 6 7 // `.copied()` turns the &i32 iterator into an i32 iterator (i32 is Copy). 8 // We sort only to get deterministic output for this example. 9 let mut union: Vec<i32> = a.union(&b).copied().collect(); 10 union.sort(); 11 println!("union = {union:?}"); // [1, 2, 3, 4, 5, 6] 12 13 let mut inter: Vec<i32> = a.intersection(&b).copied().collect(); 14 inter.sort(); 15 println!("intersection = {inter:?}"); // [3, 4] 16 17 // difference is directional: a - b (in a but not in b). 18 let mut diff: Vec<i32> = a.difference(&b).copied().collect(); 19 diff.sort(); 20 println!("difference (a - b) = {diff:?}"); // [1, 2] 21 22 // symmetric_difference: in exactly one of the two. 23 let mut sym: Vec<i32> = a.symmetric_difference(&b).copied().collect(); 24 sym.sort(); 25 println!("symmetric_difference = {sym:?}"); // [1, 2, 5, 6] 26 } ``` Output: ```text 1 union = [1, 2, 3, 4, 5, 6] 2 intersection = [3, 4] 3 difference (a - b) = [1, 2] 4 symmetric_difference = [1, 2, 5, 6] ``` > **Tip:** When you want a new `HashSet` rather than a `Vec`, collect straight into one: `let u: HashSet<i32> = a.union(&b).copied().collect();`. ### Operator overloads on `&HashSet` [Section titled “Operator overloads on \&HashSet”](#operator-overloads-on-hashset) For sets of `Clone` elements, the bitwise operators are overloaded to mirror set algebra. They operate on **references** and produce an **owned** `HashSet`: ```rust 1 use std::collections::HashSet; 2 3 fn main() { 4 let a: HashSet<i32> = HashSet::from([1, 2, 3]); 5 let b: HashSet<i32> = HashSet::from([2, 3, 4]); 6 7 let union = &a | &b; // union 8 let intersection = &a & &b; // intersection 9 let difference = &a - &b; // a minus b 10 let symmetric = &a ^ &b; // symmetric difference 11 12 let mut u: Vec<i32> = union.into_iter().collect(); u.sort(); 13 let mut i: Vec<i32> = intersection.into_iter().collect(); i.sort(); 14 let mut d: Vec<i32> = difference.into_iter().collect(); d.sort(); 15 let mut s: Vec<i32> = symmetric.into_iter().collect(); s.sort(); 16 17 println!("a | b = {u:?}"); // [1, 2, 3, 4] 18 println!("a & b = {i:?}"); // [2, 3] 19 println!("a - b = {d:?}"); // [1] 20 println!("a ^ b = {s:?}"); // [1, 4] 21 } ``` ### Relationship predicates [Section titled “Relationship predicates”](#relationship-predicates) ```rust 1 use std::collections::HashSet; 2 3 fn main() { 4 let a: HashSet<i32> = HashSet::from([1, 2, 3, 4]); 5 let small: HashSet<i32> = HashSet::from([1, 2]); 6 let other: HashSet<i32> = HashSet::from([9, 10]); 7 8 println!("{}", small.is_subset(&a)); // true 9 println!("{}", a.is_superset(&small)); // true 10 println!("{}", a.is_disjoint(&other)); // true — no shared elements 11 } ``` ### In-place mutation: `extend` and `retain` [Section titled “In-place mutation: extend and retain”](#in-place-mutation-extend-and-retain) ```rust 1 use std::collections::HashSet; 2 3 fn main() { 4 // Union into an existing set without allocating a new one. 5 let mut acc: HashSet<i32> = HashSet::from([1, 2, 3]); 6 acc.extend([3, 4, 5]); // 3 already present, ignored 7 8 let mut v: Vec<i32> = acc.iter().copied().collect(); 9 v.sort(); 10 println!("after extend = {v:?}"); // [1, 2, 3, 4, 5] 11 12 // Filter in place — keep only the elements matching the predicate. 13 let mut nums: HashSet<i32> = (1..=10).collect(); 14 nums.retain(|&n| n % 2 == 0); 15 let mut evens: Vec<i32> = nums.into_iter().collect(); 16 evens.sort(); 17 println!("evens = {evens:?}"); // [2, 4, 6, 8, 10] 18 } ``` *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | JavaScript `Set` | Rust `HashSet<T>` | | --------------------- | ------------------------------------------------------ | ---------------------------------------------- | | Element types | Mixed allowed (`Set<any>`) | Homogeneous; one `T`, enforced at compile time | | Element requirements | Any value | `T: Hash + Eq` | | Object equality | Reference identity (`{}` ≠ `{}`) | **Value** equality via derived `Hash + Eq` | | Iteration order | Insertion order, deterministic | **Unspecified and randomized** per run | | `add`/`insert` return | The set itself | `bool` (was it newly inserted?) | | `has`/`contains` | `set.has(x)` | `set.contains(&x)` (takes a reference) | | Set algebra | `union`/`intersection`/`difference` (ES2024, Node 22+) | Built in since 1.0, plus \` | | Result of set ops | A new `Set` | A lazy **iterator** of `&T` you `.collect()` | ### Why `Hash + Eq`? [Section titled “Why Hash + Eq?”](#why-hash--eq) A hash set finds elements by hashing them into buckets and comparing for equality within a bucket. So `T` must be able to (a) produce a hash (`Hash`) and (b) be compared for total equality (`Eq`, which implies `PartialEq`). Most built-in types — integers, `bool`, `char`, `String`, `&str`, tuples and `Vec`s of those — already implement both. For your own structs and enums, derive them: ```rust 1 use std::collections::HashSet; 2 3 #[derive(Debug, Clone, PartialEq, Eq, Hash)] 4 struct UserId(u64); 5 6 fn main() { 7 let mut ids: HashSet<UserId> = HashSet::new(); 8 ids.insert(UserId(1)); 9 ids.insert(UserId(1)); // value-equal, ignored 10 println!("{}", ids.len()); // 1 11 } ``` > **Note:** Two structs are “the same element” when their derived `Hash` and `Eq` say so, i.e. all fields are equal. This is **value** equality, the opposite of JavaScript, where two distinct objects are always different `Set` members even if their fields match. ### Why is iteration order random? [Section titled “Why is iteration order random?”](#why-is-iteration-order-random) Rust’s default hasher (**SipHash 1-3**) is seeded with a per-process random key. This makes the collection resistant to *HashDoS* attacks, where an attacker crafts colliding keys to degrade performance. The trade-off is that you must **never** rely on iteration order. If you need ordering, use a [`BTreeSet`](/07-collections/05-btreemap-btreeset/) (sorted) or collect into a `Vec` and `sort()`. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Using a type that isn’t `Hash + Eq` [Section titled “Pitfall 1: Using a type that isn’t Hash + Eq”](#pitfall-1-using-a-type-that-isnt-hash--eq) Forgetting to derive the required traits produces a confusing error: it says `insert` “exists but its trait bounds were not satisfied.” ```rust 1 use std::collections::HashSet; 2 3 #[derive(Debug)] 4 struct Point { x: i32, y: i32 } // no Eq/Hash 5 6 fn main() { 7 let mut seen: HashSet<Point> = HashSet::new(); 8 seen.insert(Point { x: 1, y: 2 }); // does not compile (error[E0599]) 9 } ``` Real compiler output: ```text 1 error[E0599]: the method `insert` exists for struct `HashSet<Point>`, but its trait bounds were not satisfied 2 --> src/main.rs:8:10 3 | 4 4 | struct Point { x: i32, y: i32 } 5 | ------------ doesn't satisfy `Point: Eq` or `Point: Hash` 6 ... 7 8 | seen.insert(Point { x: 1, y: 2 }); 8 | ^^^^^^ 9 | 10 = note: the following trait bounds were not satisfied: 11 `Point: Eq` 12 `Point: Hash` 13 help: consider annotating `Point` with `#[derive(Eq, Hash, PartialEq)]` ``` The fix is exactly what the compiler suggests: `#[derive(PartialEq, Eq, Hash)]`. ### Pitfall 2: Floating-point elements [Section titled “Pitfall 2: Floating-point elements”](#pitfall-2-floating-point-elements) `f64`/`f32` implement `PartialEq` but **not** `Eq` (because `NaN != NaN`), and they have no `Hash`. So `HashSet<f64>` does not work: ```rust 1 use std::collections::HashSet; 2 3 fn main() { 4 let mut s: HashSet<f64> = HashSet::new(); 5 s.insert(3.14); // does not compile (error[E0599]) 6 } ``` Real compiler output: ```text 1 error[E0599]: the method `insert` exists for struct `HashSet<f64>`, but its trait bounds were not satisfied 2 --> src/main.rs:5:7 3 | 4 5 | s.insert(3.14); 5 | ^^^^^^ 6 | 7 = note: the following trait bounds were not satisfied: 8 `f64: Eq` 9 `f64: Hash` ``` Coming from JavaScript — where `new Set([3.14])` just works — this surprises people. Store an integer key, a rounded/quantized representation, or use the `ordered-float` crate’s `OrderedFloat` wrapper if you genuinely need float set membership. ### Pitfall 3: Expecting deterministic iteration order [Section titled “Pitfall 3: Expecting deterministic iteration order”](#pitfall-3-expecting-deterministic-iteration-order) ```typescript 1 // JavaScript: order is the insertion order, every time. 2 const s = new Set(["c", "a", "b"]); 3 console.log([...s]); // ['c', 'a', 'b'] — always ``` In Rust, `for x in &set` visits elements in a random order that changes between program runs. Do not write tests or output that assume an order. To compare a set to an expected sequence, sort first: ```rust 1 use std::collections::HashSet; 2 3 fn main() { 4 let s: HashSet<&str> = HashSet::from(["c", "a", "b"]); 5 let mut v: Vec<&str> = s.into_iter().collect(); 6 v.sort(); 7 assert_eq!(v, ["a", "b", "c"]); // deterministic 8 } ``` ### Pitfall 4: Passing the value instead of a reference to `contains` [Section titled “Pitfall 4: Passing the value instead of a reference to contains”](#pitfall-4-passing-the-value-instead-of-a-reference-to-contains) `contains` (and `remove`, `get`, `take`) take a **reference**. `set.contains(20)` for a `HashSet<i32>` fails to compile; write `set.contains(&20)`. For a `HashSet<String>`, you can pass a `&str` directly (`set.contains("hi")`) thanks to the `Borrow` trait; no `String` allocation required. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Reach for `HashSet` to deduplicate.** `iter.collect::<HashSet<_>>()` is the idiomatic dedup; if you also need to preserve first-seen order, keep a `Vec` and a `HashSet` together and consult the set before pushing. * **Use the `insert` return value** to express “insert if new” in one branch instead of a separate `contains` + `insert`. The two-call version also double-hashes. * **Derive `Hash, Eq, PartialEq`** (plus `Clone`/`Debug`) on any struct or enum you intend to put in a set. * **Preallocate with `with_capacity`** when the size is roughly known to avoid repeated rehashing; see [collection performance](/07-collections/09-collection-performance/). * **Choose `BTreeSet` when you need order** (sorted iteration or range queries); choose `HashSet` for the fastest membership tests. See [BTreeMap and BTreeSet](/07-collections/05-btreemap-btreeset/). * **Collect set operations directly into the type you want.** Need a set back? `a.union(&b).copied().collect::<HashSet<_>>()`. Need a list? collect into a `Vec` and `sort()`. * **Swap the hasher for non-adversarial hot paths.** SipHash is DoS-resistant but not the fastest; for trusted internal data, a crate like `ahash` or `rustc-hash` (`FxHashSet`) is materially faster. Keep the default for anything touching untrusted input. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small access-control check: given the permissions a user has been **granted** and the permissions an action **requires**, compute exactly which permissions are missing, and deduplicate an incoming audit log of accessed resources. ```rust 1 use std::collections::HashSet; 2 3 #[derive(Debug, Clone, PartialEq, Eq, Hash)] 4 struct Permission(String); 5 6 /// Returns the permissions that `required` needs but `granted` lacks. 7 fn missing_permissions(granted: &HashSet<Permission>, required: &HashSet<Permission>) -> Vec<Permission> { 8 let mut missing: Vec<Permission> = required.difference(granted).cloned().collect(); 9 missing.sort_by(|a, b| a.0.cmp(&b.0)); // stable output for logging 10 missing 11 } 12 13 fn perm(name: &str) -> Permission { 14 Permission(name.to_string()) 15 } 16 17 fn main() { 18 let granted: HashSet<Permission> = ["read", "write", "deploy"].into_iter().map(perm).collect(); 19 let required: HashSet<Permission> = ["read", "deploy", "admin"].into_iter().map(perm).collect(); 20 21 if required.is_subset(&granted) { 22 println!("access granted"); 23 } else { 24 let missing = missing_permissions(&granted, &required); 25 println!("access denied; missing: {missing:?}"); 26 } 27 28 // The action also accessed several resources, some repeatedly. How many 29 // distinct resources were touched? 30 let accessed = ["db", "cache", "db", "queue", "cache", "db"]; 31 let distinct: HashSet<&str> = accessed.into_iter().collect(); 32 println!("distinct resources touched: {}", distinct.len()); 33 34 // Which resources are "hot" (touched) but not in our known set? 35 let known: HashSet<&str> = HashSet::from(["db", "cache"]); 36 let mut unknown: Vec<&str> = distinct.difference(&known).copied().collect(); 37 unknown.sort(); 38 println!("unknown resources: {unknown:?}"); 39 } ``` Output: ```text 1 access denied; missing: [Permission("admin")] 2 distinct resources touched: 3 3 unknown resources: ["queue"] ``` This is the kind of code where Rust’s compile-time guarantees pay off: `Permission` is a distinct type (not a bare string you might mistype), the set bounds are enforced, and the set algebra reads almost like the prose specification. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`std::collections::HashSet` API docs](https://doc.rust-lang.org/std/collections/struct.HashSet.html) * [`std::collections` module overview](https://doc.rust-lang.org/std/collections/index.html): when to use which collection * [The Rust Book, Ch. 8: Common Collections](https://doc.rust-lang.org/book/ch08-00-common-collections.html) * Sibling pages in this section: * [Vectors (`Vec<T>`)](/07-collections/00-vectors/) — the growable array * [HashMaps (`HashMap<K, V>`)](/07-collections/03-hashmaps/): the key/value sibling of `HashSet`; a set is essentially a map with no values * [BTreeMap and BTreeSet](/07-collections/05-btreemap-btreeset/) — the **sorted** set when you need ordering or range queries * [Iterators](/07-collections/06-iterators/) and [Iterator consumers](/07-collections/07-iterator-consumers/) — how `union`/`difference` results are consumed * [Collection performance](/07-collections/09-collection-performance/) — Big-O and choosing the right collection * Foundational background: * [Ownership](/05-ownership/) — why `contains` borrows and set ops yield `&T` * [Data structures](/06-data-structures/) — deriving `Hash`, `Eq`, `PartialEq` * [Basic types](/02-basics/01-types/) — why `f64` can’t be a set element * Next: [Error Handling](/08-error-handling/) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Count unique words [Section titled “Exercise 1: Count unique words”](#exercise-1-count-unique-words) **Difficulty:** Beginner **Objective:** Use a `HashSet` to deduplicate, ignoring case. **Instructions:** Implement `count_unique_words(text: &str) -> usize` that returns the number of distinct words (split on whitespace), treating `"The"` and `"the"` as the same word. ```rust 1 use std::collections::HashSet; 2 3 fn count_unique_words(text: &str) -> usize { 4 // TODO: lowercase each word and collect into a HashSet 5 todo!() 6 } 7 8 fn main() { 9 assert_eq!(count_unique_words("the cat the dog The CAT"), 3); 10 println!("ok"); 11 } ``` Solution ```rust 1 use std::collections::HashSet; 2 3 fn count_unique_words(text: &str) -> usize { 4 text.split_whitespace() 5 .map(|w| w.to_lowercase()) 6 .collect::<HashSet<String>>() 7 .len() 8 } 9 10 fn main() { 11 assert_eq!(count_unique_words("the cat the dog The CAT"), 3); 12 println!("ok"); 13 } ``` ### Exercise 2: Common elements of two slices [Section titled “Exercise 2: Common elements of two slices”](#exercise-2-common-elements-of-two-slices) **Difficulty:** Intermediate **Objective:** Use set intersection to find shared elements. **Instructions:** Implement `common(a: &[i32], b: &[i32]) -> Vec<i32>` that returns the values present in both slices, **sorted ascending** with no duplicates. ```rust 1 use std::collections::HashSet; 2 3 fn common(a: &[i32], b: &[i32]) -> Vec<i32> { 4 // TODO: build two HashSets and intersect them 5 todo!() 6 } 7 8 fn main() { 9 assert_eq!(common(&[1, 2, 3, 4], &[3, 4, 5, 6]), vec![3, 4]); 10 println!("ok"); 11 } ``` Solution ```rust 1 use std::collections::HashSet; 2 3 fn common(a: &[i32], b: &[i32]) -> Vec<i32> { 4 let set_a: HashSet<i32> = a.iter().copied().collect(); 5 let set_b: HashSet<i32> = b.iter().copied().collect(); 6 let mut out: Vec<i32> = set_a.intersection(&set_b).copied().collect(); 7 out.sort(); 8 out 9 } 10 11 fn main() { 12 assert_eq!(common(&[1, 2, 3, 4], &[3, 4, 5, 6]), vec![3, 4]); 13 println!("ok"); 14 } ``` ### Exercise 3: First duplicate in a stream [Section titled “Exercise 3: First duplicate in a stream”](#exercise-3-first-duplicate-in-a-stream) **Difficulty:** Advanced **Objective:** Exploit the boolean return value of `insert` to detect repeats in a single pass. **Instructions:** Implement `first_duplicate(items: &[&str]) -> Option<String>` returning the first item that appears a second time (in input order), or `None` if all items are distinct. Iterate only once. ```rust 1 use std::collections::HashSet; 2 3 fn first_duplicate(items: &[&str]) -> Option<String> { 4 // TODO: insert each item; the first time `insert` returns false, you found it 5 todo!() 6 } 7 8 fn main() { 9 assert_eq!(first_duplicate(&["a", "b", "c", "b", "a"]), Some("b".to_string())); 10 assert_eq!(first_duplicate(&["a", "b", "c"]), None); 11 println!("ok"); 12 } ``` Solution ```rust 1 use std::collections::HashSet; 2 3 fn first_duplicate(items: &[&str]) -> Option<String> { 4 let mut seen: HashSet<&str> = HashSet::new(); 5 for &item in items { 6 // `insert` returns false when the value was already present. 7 if !seen.insert(item) { 8 return Some(item.to_string()); 9 } 10 } 11 None 12 } 13 14 fn main() { 15 assert_eq!(first_duplicate(&["a", "b", "c", "b", "a"]), Some("b".to_string())); 16 assert_eq!(first_duplicate(&["a", "b", "c"]), None); 17 println!("ok"); 18 } ``` # Sorted Collections: BTreeMap and BTreeSet > Rust's BTreeMap and BTreeSet keep keys permanently sorted, giving free in-order iteration and O(log n) range queries a JavaScript Map can't. Rust’s standard library ships two collections whose superpower is **order**: `BTreeMap<K, V>` and `BTreeSet<T>`. Where a `HashMap` gives you the fastest possible lookup but throws away ordering, a `BTreeMap` keeps its keys permanently sorted, which makes “give me everything between X and Y” and “iterate in order” cheap, built-in operations rather than something you reconstruct by sorting on every read. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In JavaScript, both plain objects and `Map` iterate in **insertion order**, and there is no built-in sorted collection at all: if you want sorted keys or a range query, you sort an array yourself, every single time. Rust’s **`BTreeMap`** stores its entries sorted by key, so iteration is always in ascending key order and you get `O(log n)` range queries for free. **`BTreeSet`** is the same idea without values: a sorted set of unique elements. The trade-off is that `BTreeMap`/`BTreeSet` are slightly slower per lookup than their hashing cousins, and their keys must be **orderable** (`Ord`) rather than merely hashable. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // TypeScript - a Map preserves INSERTION order, never sorted order. 2 const scores = new Map<string, number>(); 3 scores.set("charlie", 90); 4 scores.set("alice", 85); 5 scores.set("bob", 95); 6 7 console.log([...scores.keys()]); // [ 'charlie', 'alice', 'bob' ] <- insertion order! 8 9 // To display in sorted order, you must sort explicitly EVERY time you read. 10 const sortedByName = [...scores.entries()].sort(([a], [b]) => a.localeCompare(b)); 11 console.log(sortedByName); // [ [ 'alice', 85 ], [ 'bob', 95 ], [ 'charlie', 90 ] ] 12 13 // A "range query" — events between 10:00 and 15:00 — is a manual filter + sort. 14 const events = new Map<number, string>([ 15 [900, "standup"], 16 [1030, "design review"], 17 [1200, "lunch"], 18 [1400, "1:1"], 19 [1630, "retro"], 20 ]); 21 22 const between = [...events.entries()] 23 .filter(([time]) => time >= 1000 && time <= 1500) 24 .sort(([a], [b]) => a - b); 25 console.log(between); 26 // [ [ 1030, 'design review' ], [ 1200, 'lunch' ], [ 1400, '1:1' ] ] ``` **Key points:** * A JavaScript `Map` (and a plain object) iterates in **insertion** order, not key order. * There is no native sorted map or sorted set; you rebuild a sorted view with `[...map].sort(...)` on every read, which is `O(n log n)` each time. * A range query is “spread to an array, `filter`, then `sort`”: correct, but linear in the whole collection regardless of how small the window is. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 use std::collections::BTreeMap; 2 3 fn main() { 4 // Insert in scrambled order; BTreeMap keeps the keys sorted automatically. 5 let mut scores: BTreeMap<String, u32> = BTreeMap::new(); 6 scores.insert("charlie".to_string(), 90); 7 scores.insert("alice".to_string(), 85); 8 scores.insert("bob".to_string(), 95); 9 10 // Iteration is ALWAYS in ascending key order — no sorting step needed. 11 for (name, score) in &scores { 12 println!("{name}: {score}"); 13 } 14 15 // The smallest and largest keys are O(log n) lookups. 16 println!("first: {:?}", scores.first_key_value()); 17 println!("last: {:?}", scores.last_key_value()); 18 } ``` **Verified output:** ```text 1 alice: 85 2 bob: 95 3 charlie: 90 4 first: Some(("alice", 85)) 5 last: Some(("charlie", 90)) ``` The range query becomes a single, efficient `.range(..)` call that touches only the entries inside the window: ```rust 1 use std::collections::BTreeMap; 2 3 fn main() { 4 let mut events: BTreeMap<u32, &str> = BTreeMap::new(); 5 events.insert(900, "standup"); 6 events.insert(1030, "design review"); 7 events.insert(1200, "lunch"); 8 events.insert(1400, "1:1"); 9 events.insert(1630, "retro"); 10 11 // Inclusive range 1000..=1500 — returns entries in key order, no filter/sort. 12 println!("between 10:00 and 15:00:"); 13 for (time, name) in events.range(1000..=1500) { 14 println!(" {time}: {name}"); 15 } 16 } ``` **Verified output:** ```text 1 between 10:00 and 15:00: 2 1030: design review 3 1200: lunch 4 1400: 1:1 ``` **Key points:** * `BTreeMap` keeps entries sorted by key at all times; iteration order is guaranteed and free. * `.range(start..=end)` walks only the matching slice of the tree, in order: no full scan, no per-read sort. * The API mirrors `HashMap` (`insert`, `get`, `remove`, the `entry` API), so most code reads the same; you swap the type and gain ordering. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What “B-Tree” means and why you don’t care (much) [Section titled “What “B-Tree” means and why you don’t care (much)”](#what-b-tree-means-and-why-you-dont-care-much) A `BTreeMap` is implemented as a **B-Tree** — a balanced search tree where each node holds many keys, chosen to be cache-friendly on modern CPUs. You never interact with the tree structure directly; what matters is the behavior it buys you: * Keys are kept in **sorted order** as you insert. * `get`, `insert`, and `remove` are `O(log n)` (versus `HashMap`’s amortized `O(1)`). * Iteration visits keys smallest-to-largest. * Finding a range of keys is `O(log n + k)`, where `k` is the number of items in the range. > **Note:** The name is “B-Tree”, not “Binary Tree”. Each node stores a block of keys, which keeps the tree shallow and the memory accesses local. You will not implement or tune it; `std` does that for you. ### Keys must be `Ord`, not `Hash` [Section titled “Keys must be Ord, not Hash”](#keys-must-be-ord-not-hash) The defining requirement is right there in the method signatures: a `BTreeMap` key must implement the **`Ord`** trait (total ordering), because the collection sorts by comparing keys. A `HashMap` instead needs `Hash` + `Eq`. All the obvious primitives — integers, `char`, `bool`, `&str`/`String`, and tuples/`Vec`s of orderable things — implement `Ord` already. (`Ord` and its companions `PartialOrd`/`Eq` are part of the trait system covered in [Section 09](/09-generics-traits/).) ```rust 1 use std::collections::BTreeSet; 2 3 // Deriving Ord (plus the traits it builds on) makes a struct usable as a key. 4 // Ordering is field-by-field, top to bottom — major, then minor, then patch. 5 #[derive(Debug, PartialEq, Eq, PartialOrd, Ord)] 6 struct Version { 7 major: u32, 8 minor: u32, 9 patch: u32, 10 } 11 12 fn main() { 13 let mut releases: BTreeSet<Version> = BTreeSet::new(); 14 releases.insert(Version { major: 1, minor: 2, patch: 0 }); 15 releases.insert(Version { major: 1, minor: 0, patch: 5 }); 16 releases.insert(Version { major: 2, minor: 0, patch: 0 }); 17 releases.insert(Version { major: 1, minor: 2, patch: 0 }); // duplicate ignored 18 19 for v in &releases { 20 println!("{}.{}.{}", v.major, v.minor, v.patch); 21 } 22 println!("latest: {:?}", releases.last()); 23 } ``` **Verified output:** ```text 1 1.0.5 2 1.2.0 3 2.0.0 4 latest: Some(Version { major: 2, minor: 0, patch: 0 }) ``` The four derives matter: `#[derive(PartialEq, Eq, PartialOrd, Ord)]` generates a lexicographic comparison in field declaration order. Reorder the fields and you reorder the sort. This is more honest than JavaScript’s `Array.prototype.sort`, whose default coerces everything to strings (so `[2, 10].sort()` famously yields `[10, 2]`). ### `BTreeSet` is a `BTreeMap` with no values [Section titled “BTreeSet is a BTreeMap with no values”](#btreeset-is-a-btreemap-with-no-values) `BTreeSet<T>` is the sorted analogue of `HashSet<T>` (see [Sets and HashSet](/07-collections/04-hashsets/)): a collection of unique, ordered elements. Duplicate inserts are silently ignored, membership tests are `O(log n)`, and iteration is in sorted order. ```rust 1 use std::collections::BTreeSet; 2 3 fn main() { 4 let mut tags: BTreeSet<&str> = BTreeSet::new(); 5 tags.insert("rust"); 6 tags.insert("async"); 7 tags.insert("rust"); // duplicate ignored 8 tags.insert("web"); 9 10 let listed: Vec<&&str> = tags.iter().collect(); 11 println!("{listed:?}"); // sorted, deduped 12 println!("contains async: {}", tags.contains("async")); 13 } ``` **Verified output:** ```text 1 ["async", "rust", "web"] 2 contains async: true ``` ### Range queries in depth [Section titled “Range queries in depth”](#range-queries-in-depth) `.range(..)` accepts any of Rust’s range syntaxes, and the bounds follow the same inclusive/exclusive rules as slicing: | Range expression | Meaning | | ---------------- | --------------------------------------------- | | `start..end` | `start` inclusive, `end` **exclusive** | | `start..=end` | both ends inclusive | | `start..` | from `start` (inclusive) to the largest key | | `..end` | from the smallest key up to (excluding) `end` | | `..` | the whole map, in order (same as iterating) | ```rust 1 use std::collections::BTreeMap; 2 use std::ops::Bound::{Excluded, Unbounded}; 3 4 fn main() { 5 let mut events: BTreeMap<u32, &str> = BTreeMap::new(); 6 events.insert(900, "standup"); 7 events.insert(1030, "design review"); 8 events.insert(1200, "lunch"); 9 events.insert(1400, "1:1"); 10 events.insert(1630, "retro"); 11 12 // Everything from 1200 onward. 13 println!("from 12:00 onward:"); 14 for (time, name) in events.range(1200..) { 15 println!(" {time}: {name}"); 16 } 17 18 // For full control, pass an explicit (start, end) pair of Bound values. 19 // Here: strictly after 1200, no upper limit. 20 println!("strictly after 12:00:"); 21 for (time, name) in events.range((Excluded(1200), Unbounded)) { 22 println!(" {time}: {name}"); 23 } 24 } ``` **Verified output:** ```text 1 from 12:00 onward: 2 1200: lunch 3 1400: 1:1 4 1630: retro 5 strictly after 12:00: 6 1400: 1:1 7 1630: retro ``` The `Bound` enum (`Included`, `Excluded`, `Unbounded`) is the escape hatch when the `..` syntaxes are not expressive enough, most commonly when you need an **exclusive lower bound**, which the range operators cannot express on their own. `BTreeSet` has the same `.range(..)`: ```rust 1 use std::collections::BTreeSet; 2 3 fn main() { 4 let primes: BTreeSet<u32> = [2, 3, 5, 7, 11, 13, 17, 19].into_iter().collect(); 5 let in_range: Vec<&u32> = primes.range(5..15).collect(); 6 println!("{in_range:?}"); // 5 inclusive, 15 exclusive 7 } ``` **Verified output:** ```text 1 [5, 7, 11, 13] ``` ### The familiar map operations still apply [Section titled “The familiar map operations still apply”](#the-familiar-map-operations-still-apply) Everything you know from [HashMaps](/07-collections/03-hashmaps/) carries over (the `entry` API, `get_mut`, `remove`, set operations on sets) because both maps implement the same conceptual interface. Here is the classic word-count, which now prints alphabetically with no extra sorting: ```rust 1 use std::collections::BTreeMap; 2 3 fn main() { 4 let text = "the quick brown fox the lazy dog the end"; 5 let mut counts: BTreeMap<&str, u32> = BTreeMap::new(); 6 for word in text.split_whitespace() { 7 // entry().or_insert() works identically to HashMap. 8 *counts.entry(word).or_insert(0) += 1; 9 } 10 for (word, count) in &counts { 11 println!("{word}: {count}"); 12 } 13 } ``` **Verified output:** ```text 1 brown: 1 2 dog: 1 3 end: 1 4 fox: 1 5 lazy: 1 6 quick: 1 7 the: 3 ``` `BTreeSet` also supports the same `union`, `intersection`, and `difference` as `HashSet`, but here the results come out **sorted**: ```rust 1 use std::collections::BTreeSet; 2 3 fn main() { 4 let a: BTreeSet<i32> = [1, 2, 3, 4].into_iter().collect(); 5 let b: BTreeSet<i32> = [3, 4, 5, 6].into_iter().collect(); 6 7 let union: Vec<&i32> = a.union(&b).collect(); 8 let inter: Vec<&i32> = a.intersection(&b).collect(); 9 let diff: Vec<&i32> = a.difference(&b).collect(); 10 11 println!("union: {union:?}"); 12 println!("intersection: {inter:?}"); 13 println!("difference: {diff:?}"); 14 } ``` **Verified output:** ```text 1 union: [1, 2, 3, 4, 5, 6] 2 intersection: [3, 4] 3 difference: [1, 2] ``` ### Ordered-specific extras [Section titled “Ordered-specific extras”](#ordered-specific-extras) Because the data is sorted, `BTreeMap`/`BTreeSet` offer methods that have no `HashMap` equivalent. `pop_first`/`pop_last` remove and return the smallest/largest entry, turning a `BTreeMap` into a serviceable ordered queue or simple priority queue: ```rust 1 use std::collections::BTreeMap; 2 3 fn main() { 4 let mut tasks: BTreeMap<u8, &str> = BTreeMap::new(); 5 tasks.insert(3, "medium"); 6 tasks.insert(1, "urgent"); 7 tasks.insert(5, "low"); 8 9 // Always pull the smallest key first. 10 while let Some((priority, name)) = tasks.pop_first() { 11 println!("handling p{priority}: {name}"); 12 } 13 } ``` **Verified output:** ```text 1 handling p1: urgent 2 handling p3: medium 3 handling p5: low ``` > **Tip:** For a heavy-duty priority queue, reach for `std::collections::BinaryHeap` instead. It is purpose-built for “always give me the max” with `O(log n)` push/pop and `O(1)` peek. Use `BTreeMap::pop_first`/`pop_last` when you *also* need ordered iteration, range queries, or keyed lookup on the same data. `split_off` cuts the map in two at a key, keeping the lower part and returning the upper part as a new map: ```rust 1 use std::collections::BTreeMap; 2 3 fn main() { 4 let mut map: BTreeMap<i32, &str> = BTreeMap::new(); 5 for i in 1..=5 { 6 map.insert(i, "x"); 7 } 8 // Keys >= 3 move into `high`; `map` retains keys < 3. 9 let high = map.split_off(&3); 10 let low_keys: Vec<&i32> = map.keys().collect(); 11 let high_keys: Vec<&i32> = high.keys().collect(); 12 println!("low: {low_keys:?}"); 13 println!("high: {high_keys:?}"); 14 } ``` **Verified output:** ```text 1 low: [1, 2] 2 high: [3, 4, 5] ``` *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | JS `Map` / object | Rust `HashMap` | Rust `BTreeMap` | | ------------------------ | ------------------------- | ------------------------------ | ------------------------------------ | | Iteration order | Insertion order | **Unspecified** (randomized) | **Sorted by key** | | Lookup / insert / remove | `O(1)` average | `O(1)` amortized | `O(log n)` | | Range query | Manual `filter` + `sort` | Not supported | `O(log n + k)` via `.range(..)` | | Min / max key | Manual scan / sort | Manual scan (`O(n)`) | `O(log n)` (`first/last_key_value`) | | Key requirement | Any value (SameValueZero) | `Hash` + `Eq` | **`Ord`** | | Floats as keys | Allowed | Allowed (via `Eq` workarounds) | **Not allowed** (`f64` is not `Ord`) | ### Why iteration order differs from HashMap [Section titled “Why iteration order differs from HashMap”](#why-iteration-order-differs-from-hashmap) A `HashMap`’s order is not merely “different”: it is **deliberately randomized** per execution (its default hasher is seeded from a random value at startup) to defend against hash-flooding denial-of-service attacks. So you must never rely on `HashMap` iteration order. A `BTreeMap` makes the opposite promise: order is part of the contract. If your output must be deterministic — config files, serialized snapshots, anything diffed in tests — `BTreeMap` removes a whole class of flaky behavior. ### When to choose which [Section titled “When to choose which”](#when-to-choose-which) * **Reach for `HashMap`/`HashSet`** when you only do point lookups and inserts and never need order. They are faster per operation. * **Reach for `BTreeMap`/`BTreeSet`** when you need any of: sorted iteration, range queries, smallest/largest by key, or **deterministic output**. A detailed Big-O comparison across all the collections lives in [Collection Performance](/07-collections/09-collection-performance/). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Trying to use a type that isn’t `Ord` as a key [Section titled “Pitfall 1: Trying to use a type that isn’t Ord as a key”](#pitfall-1-trying-to-use-a-type-that-isnt-ord-as-a-key) If you forget to derive `Ord` on a struct (or try to derive it on a type containing a non-`Ord` field), the error appears at the `insert` call: ```rust 1 use std::collections::BTreeMap; 2 3 #[derive(Debug)] // only Debug — no Ord 4 struct Point { 5 x: i32, 6 y: i32, 7 } 8 9 fn main() { 10 let mut m: BTreeMap<Point, &str> = BTreeMap::new(); 11 m.insert(Point { x: 1, y: 2 }, "origin-ish"); // does not compile (error[E0277]) 12 println!("{m:?}"); 13 } ``` Real compiler output: ```text 1 error[E0277]: the trait bound `Point: Ord` is not satisfied 2 --> src/main.rs:12:7 3 | 4 12 | m.insert(Point { x: 1, y: 2 }, "origin-ish"); 5 | ^^^^^^ the trait `Ord` is not implemented for `Point` 6 | 7 note: required by a bound in `BTreeMap::<K, V, A>::insert` 8 ... 9 help: consider annotating `Point` with `#[derive(Ord)]` 10 | 11 5 + #[derive(Ord)] 12 6 | struct Point { 13 | ``` The fix is exactly what the compiler suggests, except you need the full set: `#[derive(PartialEq, Eq, PartialOrd, Ord)]` (deriving `Ord` requires `PartialOrd`, `Eq`, and `PartialEq` too). ### Pitfall 2: Floating-point keys [Section titled “Pitfall 2: Floating-point keys”](#pitfall-2-floating-point-keys) Coming from JavaScript, where `new Map().set(1.5, "x")` is fine, you may try a `BTreeMap<f64, _>`. It will not compile, because `f64` deliberately does **not** implement `Ord` (the `NaN != NaN` rule makes a total ordering impossible): ```rust 1 use std::collections::BTreeMap; 2 3 fn main() { 4 let mut m: BTreeMap<f64, &str> = BTreeMap::new(); 5 m.insert(1.5, "one and a half"); // does not compile (error[E0277]) 6 println!("{m:?}"); 7 } ``` Real compiler output (abridged): ```text 1 error[E0277]: the trait bound `f64: Ord` is not satisfied 2 --> src/main.rs:5:7 3 | 4 5 | m.insert(1.5, "one and a half"); 5 | ^^^^^^ the trait `Ord` is not implemented for `f64` 6 | 7 = help: the following other types implement trait `Ord`: 8 i128 9 i16 10 i32 11 ... ``` Workarounds: scale to an integer key (e.g. store millis or cents as `u64`/`i64`), or wrap floats in a crate like `ordered-float`’s `OrderedFloat`, which provides a total order by defining where `NaN` sorts. ### Pitfall 3: A backwards range panics at runtime [Section titled “Pitfall 3: A backwards range panics at runtime”](#pitfall-3-a-backwards-range-panics-at-runtime) Unlike a JavaScript filter that silently returns an empty array, calling `.range(start..end)` with `start > end` is a programming error and **panics**: ```rust 1 use std::collections::BTreeMap; 2 3 fn main() { 4 let mut m: BTreeMap<i32, &str> = BTreeMap::new(); 5 m.insert(1, "a"); 6 m.insert(2, "b"); 7 m.insert(3, "c"); 8 let r: Vec<_> = m.range(3..1).collect(); // start > end 9 println!("{r:?}"); 10 } ``` Real runtime output: ```text 1 thread 'main' panicked at .../alloc/src/collections/btree/search.rs:121:21: 2 range start is greater than range end in BTreeMap 3 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` Validate or `min`/`max`-clamp user-supplied bounds before passing them to `.range(..)`. (An empty *equal* range like `3..3` is fine; it just yields nothing.) ### Pitfall 4: Expecting `HashMap`-level speed [Section titled “Pitfall 4: Expecting HashMap-level speed”](#pitfall-4-expecting-hashmap-level-speed) `BTreeMap` operations are `O(log n)`, not `O(1)`. For a million-entry hot path doing nothing but point lookups, a `HashMap` will measurably win. Choose `BTreeMap` for what it *gives* you (order, ranges), not as a drop-in faster map. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Use `BTreeMap`/`BTreeSet` for deterministic output.** Anything serialized, logged, snapshot-tested, or diffed benefits from stable key order. Many teams collect into a `BTreeMap` purely so their test fixtures and config dumps stop reordering between runs. * **Build with a `HashMap`, present with a `BTreeMap`** when ordering only matters at the end. Do the hot inserts in a `HashMap`, then `.collect()` into a `BTreeMap` once for display: ```rust 1 use std::collections::{BTreeMap, HashMap}; 2 3 fn main() { 4 let mut counts: HashMap<&str, u32> = HashMap::new(); 5 for w in "b a c a b a".split_whitespace() { 6 *counts.entry(w).or_insert(0) += 1; 7 } 8 // One conversion at the end yields a sorted view. 9 let sorted: BTreeMap<_, _> = counts.into_iter().collect(); 10 for (word, count) in &sorted { 11 println!("{word}: {count}"); 12 } 13 } ``` **Verified output:** ```text 1 a: 3 2 b: 2 3 c: 1 ``` * **Prefer `.range(..)` over `.iter().filter(..)`** for windowed queries. `filter` walks the entire map; `.range(..)` jumps straight to the start of the window and stops at the end. * **Use `first_key_value`/`last_key_value` (peek) and `pop_first`/`pop_last` (remove)** instead of `.iter().next()` gymnastics when you want the min/max entry. * **Order keys by deriving in field order.** Put the most significant field first in a key struct so the derived `Ord` sorts the way you want. > **Note:** Need a custom comparison that the derived field order can’t express, for example “sort users by score descending, then name ascending”? Implement `Ord`/`PartialOrd` by hand on the key type, or store a transformed key (e.g. `std::cmp::Reverse(score)`). Hand-written `Ord` is covered alongside the other comparison traits in [Section 09](/09-generics-traits/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A time-series metric store, the kind you’d find behind a monitoring dashboard. Samples arrive keyed by timestamp; the consumer asks for windowed averages and “the latest value as of time T”. A `BTreeMap` makes every one of those a sorted range query. ```rust 1 use std::collections::BTreeMap; 2 3 /// A time-series store keyed by Unix-millisecond timestamps. Because a 4 /// `BTreeMap` keeps keys sorted, range queries ("everything in this window") 5 /// are cheap and the results come back in chronological order. 6 #[derive(Debug, Default)] 7 struct MetricSeries { 8 samples: BTreeMap<u64, f64>, 9 } 10 11 impl MetricSeries { 12 fn record(&mut self, timestamp_ms: u64, value: f64) { 13 self.samples.insert(timestamp_ms, value); 14 } 15 16 /// Average of all samples in the half-open window `[start, end)`. 17 fn average(&self, start: u64, end: u64) -> Option<f64> { 18 let window: Vec<f64> = self.samples.range(start..end).map(|(_, &v)| v).collect(); 19 if window.is_empty() { 20 return None; 21 } 22 Some(window.iter().sum::<f64>() / window.len() as f64) 23 } 24 25 /// The most recent sample at or before `timestamp_ms`. 26 /// `range(..=t).next_back()` walks to the end of the window and grabs the last entry. 27 fn latest_at(&self, timestamp_ms: u64) -> Option<(u64, f64)> { 28 self.samples 29 .range(..=timestamp_ms) 30 .next_back() 31 .map(|(&t, &v)| (t, v)) 32 } 33 } 34 35 fn main() { 36 let mut cpu = MetricSeries::default(); 37 cpu.record(1_000, 12.5); 38 cpu.record(2_000, 30.0); 39 cpu.record(3_000, 45.5); 40 cpu.record(4_000, 22.0); 41 cpu.record(5_000, 60.0); 42 43 // Average over [2000, 5000): samples at 2000, 3000, 4000. 44 println!("avg 2s..5s: {:?}", cpu.average(2_000, 5_000)); 45 46 // What was the reading as of t=3500? -> the sample at 3000. 47 println!("latest at 3500: {:?}", cpu.latest_at(3_500)); 48 49 // No samples in this window -> None, not a crash. 50 println!("avg 6s..9s: {:?}", cpu.average(6_000, 9_000)); 51 52 // Iterating yields chronological order for free. 53 println!("all samples:"); 54 for (t, v) in &cpu.samples { 55 println!(" t={t}: {v}"); 56 } 57 } ``` **Verified output:** ```text 1 avg 2s..5s: Some(32.5) 2 latest at 3500: Some((3000, 45.5)) 3 avg 6s..9s: None 4 all samples: 5 t=1000: 12.5 6 t=2000: 30 7 t=3000: 45.5 8 t=4000: 22 9 t=5000: 60 ``` Note the design choices a JavaScript version would make harder: `latest_at` uses `range(..=t).next_back()` — an `O(log n)` “floor” lookup — instead of scanning; values are floats but the **key** is an integer (`u64` millis), sidestepping the `f64: Ord` pitfall entirely; and the chronological iteration at the end needs no sort. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`std::collections::BTreeMap`](https://doc.rust-lang.org/std/collections/struct.BTreeMap.html) — full API reference, including `range`, `split_off`, and the `entry` API. * [`std::collections::BTreeSet`](https://doc.rust-lang.org/std/collections/struct.BTreeSet.html) — the sorted-set reference. * [`std::collections` module docs](https://doc.rust-lang.org/std/collections/index.html): the standard library’s own “which collection should I use?” guide. * [`std::ops::Bound`](https://doc.rust-lang.org/std/ops/enum.Bound.html): explicit range bounds for `.range(..)`. * [The `Ord` trait](https://doc.rust-lang.org/std/cmp/trait.Ord.html): what a key type must satisfy. **Related sections in this guide:** * [HashMaps](/07-collections/03-hashmaps/) — the unordered `HashMap` and the shared `entry`/`get`/`insert` API. * [Sets and HashSet](/07-collections/04-hashsets/) — `HashSet` and the set operations that `BTreeSet` shares. * [Collection Performance](/07-collections/09-collection-performance/): Big-O across all collections and when to pick each. * [Iterators](/07-collections/06-iterators/) and [Iterator Consumers](/07-collections/07-iterator-consumers/) — `.range(..)`, `.keys()`, etc. all return iterators. * [Section 09: Generics & Traits](/09-generics-traits/): implementing `Ord` by hand for custom key ordering. * [Section 08: Error Handling](/08-error-handling/): `Option` returns like `first_key_value()` and the `latest_at` example above. * [Section 05: Ownership](/05-ownership/) — why `.range(..)` yields references (`&K`, `&V`) you must dereference. * [Section 02: Basics](/02-basics/) and [Section 00: Introduction](/00-introduction/) — language fundamentals if any syntax here is unfamiliar. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: First repeated word, alphabetically [Section titled “Exercise 1: First repeated word, alphabetically”](#exercise-1-first-repeated-word-alphabetically) **Difficulty:** Easy **Objective:** Use a `BTreeMap` to find the alphabetically-first word that appears two or more times in a sentence. **Instructions:** 1. Split the input on whitespace and count occurrences with the `entry` API. 2. Because a `BTreeMap` iterates in sorted key order, iterate the counts and return the first word whose count is `>= 2`. 3. Return `Option<String>` so the “no repeats” case is `None`. ```rust 1 use std::collections::BTreeMap; 2 3 fn first_repeated(text: &str) -> Option<String> { 4 // TODO: count words, then find the first (alphabetically) with count >= 2 5 todo!() 6 } 7 8 fn main() { 9 println!("{:?}", first_repeated("zebra apple mango apple zebra")); 10 println!("{:?}", first_repeated("one two three")); 11 } ``` Solution ```rust 1 use std::collections::BTreeMap; 2 3 fn first_repeated(text: &str) -> Option<String> { 4 let mut counts: BTreeMap<&str, u32> = BTreeMap::new(); 5 for word in text.split_whitespace() { 6 *counts.entry(word).or_insert(0) += 1; 7 } 8 // Iteration is alphabetical, so `find` returns the first qualifying word. 9 counts 10 .into_iter() 11 .find(|&(_, count)| count >= 2) 12 .map(|(word, _)| word.to_string()) 13 } 14 15 fn main() { 16 println!("{:?}", first_repeated("zebra apple mango apple zebra")); 17 println!("{:?}", first_repeated("one two three")); 18 } ``` **Verified output:** ```text 1 Some("apple") 2 None ``` `apple` and `zebra` both repeat, but because the `BTreeMap` is sorted, `find` reaches `apple` first. ### Exercise 2: Score range report [Section titled “Exercise 2: Score range report”](#exercise-2-score-range-report) **Difficulty:** Medium **Objective:** Given a `BTreeMap<u32, Vec<&str>>` mapping a score to the students who earned it, list everyone whose score falls in an inclusive `[lo, hi]` band, in ascending score order. **Instructions:** 1. Use `.range(lo..=hi)` to select only the scores in the band; do not iterate the whole map. 2. For each `(score, names)` entry, produce one `"name: score"` line per student. 3. Return a `Vec<String>` of those lines. ```rust 1 use std::collections::BTreeMap; 2 3 fn report(scores: &BTreeMap<u32, Vec<&str>>, lo: u32, hi: u32) -> Vec<String> { 4 // TODO: range over [lo, hi] and flatten into "name: score" lines 5 todo!() 6 } 7 8 fn main() { 9 let mut scores: BTreeMap<u32, Vec<&str>> = BTreeMap::new(); 10 scores.insert(72, vec!["Dana"]); 11 scores.insert(85, vec!["Alice", "Eve"]); 12 scores.insert(91, vec!["Bob"]); 13 scores.insert(60, vec!["Frank"]); 14 for line in report(&scores, 70, 90) { 15 println!("{line}"); 16 } 17 } ``` Solution ```rust 1 use std::collections::BTreeMap; 2 3 fn report(scores: &BTreeMap<u32, Vec<&str>>, lo: u32, hi: u32) -> Vec<String> { 4 scores 5 .range(lo..=hi) 6 // `move` lets the inner closure capture `score` by copy for each entry. 7 .flat_map(|(score, names)| names.iter().map(move |n| format!("{n}: {score}"))) 8 .collect() 9 } 10 11 fn main() { 12 let mut scores: BTreeMap<u32, Vec<&str>> = BTreeMap::new(); 13 scores.insert(72, vec!["Dana"]); 14 scores.insert(85, vec!["Alice", "Eve"]); 15 scores.insert(91, vec!["Bob"]); 16 scores.insert(60, vec!["Frank"]); 17 for line in report(&scores, 70, 90) { 18 println!("{line}"); 19 } 20 } ``` **Verified output:** ```text 1 Dana: 72 2 Alice: 85 3 Eve: 85 ``` `60` (Frank) and `91` (Bob) fall outside `[70, 90]`, so `.range(..)` skips them entirely. `flat_map` is covered in [Iterators](/07-collections/06-iterators/). ### Exercise 3: Merge two leaderboards [Section titled “Exercise 3: Merge two leaderboards”](#exercise-3-merge-two-leaderboards) **Difficulty:** Medium **Objective:** Combine two `BTreeMap<String, u32>` leaderboards into one, summing the scores of players who appear in both. **Instructions:** 1. Start from a clone of the first map. 2. For each `(name, score)` in the second map, add the score into the merged map using the `entry` API (insert `0` if the player is new). 3. Return the merged `BTreeMap`, which is automatically sorted by player name. ```rust 1 use std::collections::BTreeMap; 2 3 fn merge( 4 a: &BTreeMap<String, u32>, 5 b: &BTreeMap<String, u32>, 6 ) -> BTreeMap<String, u32> { 7 // TODO: clone `a`, then fold `b`'s scores in with entry().or_insert(0) 8 todo!() 9 } 10 11 fn main() { 12 let mut q1: BTreeMap<String, u32> = BTreeMap::new(); 13 q1.insert("alice".into(), 10); 14 q1.insert("bob".into(), 5); 15 let mut q2: BTreeMap<String, u32> = BTreeMap::new(); 16 q2.insert("bob".into(), 7); 17 q2.insert("carol".into(), 3); 18 for (name, total) in merge(&q1, &q2) { 19 println!("{name}: {total}"); 20 } 21 } ``` Solution ```rust 1 use std::collections::BTreeMap; 2 3 fn merge( 4 a: &BTreeMap<String, u32>, 5 b: &BTreeMap<String, u32>, 6 ) -> BTreeMap<String, u32> { 7 let mut merged = a.clone(); 8 for (name, score) in b { 9 // entry() returns a mutable handle; or_insert(0) seeds new players. 10 *merged.entry(name.clone()).or_insert(0) += score; 11 } 12 merged 13 } 14 15 fn main() { 16 let mut q1: BTreeMap<String, u32> = BTreeMap::new(); 17 q1.insert("alice".into(), 10); 18 q1.insert("bob".into(), 5); 19 let mut q2: BTreeMap<String, u32> = BTreeMap::new(); 20 q2.insert("bob".into(), 7); 21 q2.insert("carol".into(), 3); 22 for (name, total) in merge(&q1, &q2) { 23 println!("{name}: {total}"); 24 } 25 } ``` **Verified output:** ```text 1 alice: 10 2 bob: 12 3 carol: 3 ``` `bob` appears in both leaderboards, so his `5 + 7 = 12` is summed; the result iterates alphabetically because it is a `BTreeMap`. *** *Previous: [HashSets](/07-collections/04-hashsets/) · Next: [Iterators](/07-collections/06-iterators/) · Up: [Section 07 Overview](/07-collections/)* # Iterators: From Array Methods to Lazy Iterator Adaptors > Map your JS .map/.filter/.slice habits onto Rust's lazy Iterator adaptors like map, filter, take, zip, and enumerate, which run no work until consumed. In TypeScript you reach for `.map()`, `.filter()`, `.slice()`, and friends without a second thought. Rust has all of these too, but they live on the **`Iterator`** trait and behave one important way differently: they are **lazy**. This page maps your array-method muscle memory onto Rust’s iterator adaptors (`map`, `filter`, `take`, `skip`, `zip`, `enumerate`) and explains the laziness that makes them both fast and, at first, slightly surprising. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) An **iterator adaptor** is a method that takes one iterator and returns a new, transformed iterator. `map`, `filter`, `take`, `skip`, `zip`, and `enumerate` are all adaptors. The big difference from JavaScript’s array methods is that adaptors are **lazy**: building the chain does *no work*. Nothing happens until a **consumer** (like `.collect()` or a `for` loop) pulls values through it. This is the opposite of JavaScript, where `arr.map(...)` allocates a brand-new array immediately, even if you throw the result away. > **Note:** This page covers the adaptors that *transform* an iterator. The methods that *finish* a chain and produce a value (`collect`, `sum`, `fold`, `find`, `any`, `count`, and so on) are **consumers**, covered in [Iterator Consumers](/07-collections/07-iterator-consumers/). Writing your own iterator type is covered in [Custom Iterators](/07-collections/08-custom-iterators/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // Processing a price list in a typical e-commerce backend. 2 const prices = [19.99, 4.5, 120.0, 9.99, 250.0]; 3 4 // Chained array methods — each call allocates a NEW array right away. 5 const discounted = prices 6 .filter((p) => p > 10.0) // [19.99, 120.0, 250.0] 7 .map((p) => p * 0.9); // [17.991, 108, 225] 8 console.log("discounted:", discounted); 9 10 // `.map` runs its callback IMMEDIATELY, even if you ignore the result: 11 [1, 2, 3].map((n) => { 12 console.log("mapping", n); 13 return n * 2; 14 }); 15 console.log("after the orphan map"); 16 17 // Index-aware iteration uses the second callback parameter. 18 const names = ["Ada", "Alan", "Grace"]; 19 names.forEach((name, i) => console.log(`${i}: ${name}`)); 20 21 // "take 5 starting at offset 20" is a slice. 22 const page = Array.from({ length: 100 }, (_, i) => i + 1).slice(20, 25); 23 console.log("page:", page); 24 25 // JavaScript has no built-in `zip`; you hand-roll it with map + index. 26 const labels = ["cpu", "mem", "disk"]; 27 const values = [80, 55, 40]; 28 const pairs = labels.map((l, i) => [l, values[i]]); 29 console.log("pairs:", pairs); ``` Running this with Node v22 prints: ```text 1 discounted: [ 17.991, 108, 225 ] 2 mapping 1 3 mapping 2 4 mapping 3 5 after the orphan map 6 0: Ada 7 1: Alan 8 2: Grace 9 page: [ 21, 22, 23, 24, 25 ] 10 pairs: [ [ 'cpu', 80 ], [ 'mem', 55 ], [ 'disk', 40 ] ] ``` The key thing to notice: `"mapping 1/2/3"` prints **even though we never use the result of that `.map`**. JavaScript array methods are *eager*: they do the work the instant you call them. Keep that in mind; Rust does the exact opposite. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 fn main() { 2 let prices = vec![19.99, 4.50, 120.0, 9.99, 250.0]; 3 4 // Build a chain of ADAPTORS. This line allocates nothing and runs 5 // no closures — it just describes the pipeline. `.collect()` is the 6 // consumer that actually drives it. 7 let discounted: Vec<f64> = prices 8 .iter() // Iterator<Item = &f64> 9 .filter(|&&p| p > 10.0) // keep p > 10.0 10 .map(|&p| p * 0.9) // apply the 10% discount 11 .collect(); // RUN it, gather into a Vec 12 println!("discounted: {discounted:?}"); 13 14 // An orphan adaptor that is never consumed does NOTHING — and the 15 // compiler warns you about it (see Common Pitfalls). 16 17 // Index-aware iteration uses the `enumerate` adaptor, not a callback arg. 18 let names = vec!["Ada", "Alan", "Grace"]; 19 for (i, name) in names.iter().enumerate() { 20 println!("{i}: {name}"); 21 } 22 23 // "take 5 starting at offset 20": skip then take. 24 let page: Vec<i32> = (1..=100).skip(20).take(5).collect(); 25 println!("page: {page:?}"); 26 27 // `zip` is built in — it pairs two iterators element by element. 28 let labels = vec!["cpu", "mem", "disk"]; 29 let values = vec![80, 55, 40]; 30 let pairs: Vec<(&str, i32)> = labels 31 .iter() 32 .copied() 33 .zip(values.iter().copied()) 34 .collect(); 35 println!("pairs: {pairs:?}"); 36 } ``` Verified output: ```text 1 discounted: [17.991, 108.0, 225.0] 2 0: Ada 3 1: Alan 4 2: Grace 5 page: [21, 22, 23, 24, 25] 6 pairs: [("cpu", 80), ("mem", 55), ("disk", 40)] ``` > **Note:** Rust prints `108.0` where Node prints `108`. Both are the same `f64` value; the difference is purely how each language’s default formatter renders a whole-number float. Rust’s `{:?}` always shows the decimal point so you can see the value is a float. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Where iterators come from [Section titled “Where iterators come from”](#where-iterators-come-from) An **iterator** is any type that implements the `Iterator` trait, which boils down to one method: `next(&mut self) -> Option<Self::Item>`. Each call to `next` hands back `Some(item)` or `None` when the sequence is exhausted. You rarely call `next` by hand; the adaptors and `for` loops do it for you. You get an iterator from a collection in one of three ways, and the choice decides whether you borrow or consume, exactly like `Vec` iteration in [Vectors](/07-collections/00-vectors/): | You write | Method | Item type | Source afterwards | | ------------------------------ | ------------- | --------- | ------------------ | | `v.iter()` | `iter()` | `&T` | still usable | | `v.iter_mut()` | `iter_mut()` | `&mut T` | still usable | | `v.into_iter()` / `for x in v` | `into_iter()` | `T` | **consumed/moved** | Ranges like `1..=100` and `0..` are *also* iterators, with no backing collection at all. That is why `(1..=100).skip(20).take(5)` works directly. ### `map` — transform every element [Section titled “map — transform every element”](#map--transform-every-element) ```rust 1 fn main() { 2 let cents = vec![100, 250, 75]; 3 let dollars: Vec<f64> = cents.iter().map(|&c| c as f64 / 100.0).collect(); 4 println!("{dollars:?}"); 5 } ``` Verified output: ```text 1 [1.0, 2.5, 0.75] ``` `map` takes a closure (Rust’s arrow-function equivalent — see [Section 03 — Functions](/03-functions/)) and returns a new iterator that yields the transformed values. It is exactly `Array.prototype.map`, except it produces an *iterator*, not an array; you choose the output container with `.collect()`. ### `filter` — keep elements matching a predicate [Section titled “filter — keep elements matching a predicate”](#filter--keep-elements-matching-a-predicate) ```rust 1 fn main() { 2 let nums = vec![1, 2, 3, 4, 5, 6]; 3 let evens: Vec<&i32> = nums.iter().filter(|&&n| n % 2 == 0).collect(); 4 println!("{evens:?}"); 5 } ``` Verified output: ```text 1 [2, 4, 6] ``` Note the `|&&n|` pattern. `nums.iter()` yields `&i32`. `filter`’s closure receives its item *by reference* (so it can decide without consuming it), so the closure gets `&&i32`. The double-`&` pattern `&&n` destructures both layers, giving you a plain `i32` named `n`. This double-reference quirk trips up newcomers constantly. See [Common Pitfalls](#common-pitfalls). ### `enumerate` — pair each element with its index [Section titled “enumerate — pair each element with its index”](#enumerate--pair-each-element-with-its-index) ```rust 1 fn main() { 2 let tasks = vec!["build", "test", "deploy"]; 3 for (i, task) in tasks.iter().enumerate() { 4 println!("step {}: {task}", i + 1); 5 } 6 } ``` Verified output: ```text 1 step 1: build 2 step 2: test 3 step 3: deploy ``` In JavaScript, the index is the *second argument* to `map`/`forEach`/`filter` callbacks. In Rust, indexing is a separate adaptor that wraps each item into a `(usize, item)` tuple. This is cleaner: the index is opt-in, always a `usize`, and composes with every other adaptor. ### `take` and `skip` — slicing without allocating [Section titled “take and skip — slicing without allocating”](#take-and-skip--slicing-without-allocating) ```rust 1 fn main() { 2 let feed = vec![10, 20, 30, 40, 50, 60, 70]; 3 4 let first_three: Vec<i32> = feed.iter().copied().take(3).collect(); 5 let after_two: Vec<i32> = feed.iter().copied().skip(2).collect(); 6 // Pagination: page 2, 3 items per page -> skip(3).take(3). 7 let page_two: Vec<i32> = feed.iter().copied().skip(3).take(3).collect(); 8 9 println!("take 3: {first_three:?}"); 10 println!("skip 2: {after_two:?}"); 11 println!("page two: {page_two:?}"); 12 } ``` Verified output: ```text 1 take 3: [10, 20, 30] 2 skip 2: [30, 40, 50, 60, 70] 3 page two: [40, 50, 60] ``` `skip(n).take(m)` is the lazy equivalent of `arr.slice(n, n + m)`, but unlike `slice`, it never allocates an intermediate array and works on *any* iterator, including infinite ranges. (`.copied()` turns the `&i32` items into owned `i32`; see the note under `zip`.) ### `zip` — walk two iterators in lockstep [Section titled “zip — walk two iterators in lockstep”](#zip--walk-two-iterators-in-lockstep) ```rust 1 fn main() { 2 let metrics = vec!["cpu", "mem", "disk"]; 3 let percentages = vec![80, 55, 40, 99]; // one extra — ignored 4 5 let report: Vec<(&str, i32)> = metrics 6 .iter() 7 .copied() 8 .zip(percentages.iter().copied()) 9 .collect(); 10 println!("{report:?}"); 11 } ``` Verified output: ```text 1 [("cpu", 80), ("mem", 55), ("disk", 40)] ``` `zip` stops at the **shorter** of the two iterators; the extra `99` is dropped silently. JavaScript has no built-in `zip`; you simulate it with `a.map((x, i) => [x, b[i]])`, which breaks if `b` is shorter (you get `undefined`). Rust’s `zip` is total and type-safe. > **Tip:** `.copied()` (and its cousin `.cloned()`) convert an iterator of `&T` into an iterator of `T`. Here `metrics.iter()` yields `&&str`; `.copied()` makes it `&str` so the tuple is `(&str, i32)` rather than `(&&str, &i32)`. Use `copied` for `Copy` types (numbers, `&str`, `char`) and `cloned` for owned types like `String`. ### The heart of it: **laziness** [Section titled “The heart of it: laziness”](#the-heart-of-it-laziness) This is the single most important difference from JavaScript. Building an adaptor chain runs **no** code. The closures fire only when a consumer pulls values through. ```rust 1 fn main() { 2 let nums = vec![1, 2, 3]; 3 4 // Building the chain runs nothing. 5 let lazy = nums.iter().map(|n| { 6 println!("mapping {n}"); 7 n * 2 8 }); 9 println!("created the iterator, nothing printed yet"); 10 11 // .collect() is the consumer — NOW the closure runs. 12 let doubled: Vec<i32> = lazy.collect(); 13 println!("doubled: {doubled:?}"); 14 } ``` Verified output: ```text 1 created the iterator, nothing printed yet 2 mapping 1 3 mapping 2 4 mapping 3 5 doubled: [2, 4, 6] ``` Compare this to the JavaScript example earlier, where `"mapping 1/2/3"` printed *before* `"after the orphan map"`, because JS ran the callback immediately. In Rust, the prints come *after* `"created the iterator..."`, because the work waits for `.collect()`. ### Laziness is also efficient: only as much work as needed [Section titled “Laziness is also efficient: only as much work as needed”](#laziness-is-also-efficient-only-as-much-work-as-needed) Because values are *pulled* one at a time, an adaptor chain only does the work the consumer actually demands. This lets Rust iterate over **infinite** sequences and stop early: ```rust 1 fn main() { 2 let result: Vec<i32> = (1..) // 1, 2, 3, ... infinite! 3 .map(|n| { 4 println!("squaring {n}"); 5 n * n 6 }) 7 .filter(|sq| sq % 2 == 1) // keep odd squares 8 .take(3) // stop after 3 9 .collect(); 10 println!("first 3 odd squares: {result:?}"); 11 } ``` Verified output: ```text 1 squaring 1 2 squaring 2 3 squaring 3 4 squaring 4 5 squaring 5 6 first 3 odd squares: [1, 9, 25] ``` Notice the interleaving: the pipeline squares `1`, checks it (odd, keep), squares `2` (even, drop), and so on, pulling *one element at a time* until `take(3)` is satisfied at `5`. It never tries to materialize the infinite range. In JavaScript, `Array.from({length: Infinity})` throws a `RangeError` outright (invalid array length); eager methods *cannot* express this. (Lazy JS iteration exists via generators, but the array methods aren’t lazy.) *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript array methods | Rust iterator adaptors | | -------------------- | --------------------------------------------- | ------------------------------------------------------- | | Evaluation | **Eager**: runs immediately on the call | **Lazy**: runs only when consumed | | Intermediate results | Each step allocates a new array | No allocation between adaptors; one pass at the end | | Index access | Callback’s second parameter `(x, i) => ...` | Separate `enumerate()` adaptor yielding `(usize, item)` | | `zip` | Not built in; hand-rolled, breaks on mismatch | Built in; stops at the shorter iterator | | Infinite sequences | Not expressible with array methods | Natural: `(0..)`, `std::iter::repeat`, etc. | | `slice(n, m)` | Allocates a new array | `skip(n).take(m)` — lazy, no allocation | | Ignoring the result | Side effects still run | Nothing runs; compiler warns about the unused iterator | | What you iterate | Always the values (copies of references) | `&T`, `&mut T`, or `T` depending on `iter`/`into_iter` | | Output type | Always an `Array` | You choose via `collect::<Vec<_>>()`, `String`, etc. | ### Why lazy? [Section titled “Why lazy?”](#why-lazy) Laziness lets the compiler **fuse** the whole chain into a single loop with no intermediate collections. A four-step chain like `iter().filter(...).map(...).take(3)` becomes, after optimization, roughly one `for` loop that breaks after three matches: typically as fast as the hand-written loop you’d write in C, and often faster than the equivalent JavaScript because there are no per-step array allocations. You get the readability of method chaining with the performance of an imperative loop. See [Collection Performance](/07-collections/09-collection-performance/) for the iterator-vs-loop comparison. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting to consume the iterator [Section titled “Pitfall 1: Forgetting to consume the iterator”](#pitfall-1-forgetting-to-consume-the-iterator) This is the number-one surprise for JavaScript developers. You write a `map` for its side effect, and nothing happens. ```rust 1 fn main() { 2 let nums = vec![1, 2, 3]; 3 nums.iter().map(|n| println!("{n}")); // adaptor created but never consumed 4 println!("done"); 5 } ``` The program prints only `done`; the `println!` inside `map` never runs. And the compiler warns you (trimmed): ```text 1 warning: unused `Map` that must be used 2 --> src/main.rs:3:5 3 | 4 3 | nums.iter().map(|n| println!("{n}")); // adaptor created but never consumed 5 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6 | 7 = note: iterators are lazy and do nothing unless consumed 8 = note: `#[warn(unused_must_use)]` on by default ``` **Fix:** if you want a side effect per element, use a `for` loop (the idiomatic choice) or the `for_each` consumer: `nums.iter().for_each(|n| println!("{n}"));`. Use `map` only when you want the *transformed values*. ### Pitfall 2: The double-reference in `filter`/`map` closures [Section titled “Pitfall 2: The double-reference in filter/map closures”](#pitfall-2-the-double-reference-in-filtermap-closures) `iter()` yields `&T`, and `filter` passes its item *by reference*, so the closure sees `&&T`. Treating it like a plain number fails to compile. ```rust 1 fn main() { 2 let nums = vec![1, 2, 3, 4]; 3 let evens: Vec<&i32> = nums.iter().filter(|n| n % 2 == 0).collect(); // does not compile (error[E0369]) 4 println!("{evens:?}"); 5 } ``` Real compiler error (trimmed): ```text 1 error[E0369]: cannot calculate the remainder of `&&{integer}` divided by `{integer}` 2 --> src/main.rs:3:53 3 | 4 3 | let evens: Vec<&i32> = nums.iter().filter(|n| n % 2 == 0).collect(); 5 | - ^ - {integer} 6 | | 7 | &&{integer} 8 | 9 help: `%` can be used on `&{integer}` if you dereference the left-hand side 10 | 11 3 | let evens: Vec<&i32> = nums.iter().filter(|n| *n % 2 == 0).collect(); 12 | + ``` **Fix:** dereference (`*n % 2`) or, more cleanly, destructure the references in the parameter pattern (`|&&n| n % 2 == 0`). For tuple items from `enumerate`, the same idea applies — `.filter(|(_, v)| **v % 2 == 0)`. ### Pitfall 3: Using a collection after `into_iter()` consumed it [Section titled “Pitfall 3: Using a collection after into\_iter() consumed it”](#pitfall-3-using-a-collection-after-into_iter-consumed-it) `into_iter()` takes ownership. Once you call it, the original is gone. This is the ownership story from [Section 05 — Ownership](/05-ownership/), surfacing in iterator form. ```rust 1 fn main() { 2 let names = vec![String::from("Ada"), String::from("Alan")]; 3 let upper: Vec<String> = names.into_iter().map(|n| n.to_uppercase()).collect(); 4 println!("{upper:?}"); 5 println!("{}", names.len()); // does not compile (error[E0382]) 6 } ``` Real compiler error (trimmed): ```text 1 error[E0382]: borrow of moved value: `names` 2 --> src/main.rs:5:20 3 | 4 2 | let names = vec![String::from("Ada"), String::from("Alan")]; 5 | ----- move occurs because `names` has type `Vec<String>`, which does not implement the `Copy` trait 6 3 | let upper: Vec<String> = names.into_iter().map(|n| n.to_uppercase()).collect(); 7 | ----------- `names` moved due to this method call 8 ... 9 5 | println!("{}", names.len()); // use after into_iter consumed it 10 | ^^^^^ value borrowed here after move 11 | 12 note: `into_iter` takes ownership of the receiver `self`, which moves `names` ``` **Fix:** use `names.iter()` (borrows, yields `&String`) if you still need `names` afterward. Use `into_iter()` only when you genuinely want to *consume* the collection and take ownership of its elements. ### Pitfall 4: Expecting `zip` to fail or pad on length mismatch [Section titled “Pitfall 4: Expecting zip to fail or pad on length mismatch”](#pitfall-4-expecting-zip-to-fail-or-pad-on-length-mismatch) A JavaScript developer used to `b[i]` returning `undefined` past the end may expect `zip` to surface mismatched lengths. It does not; it silently stops at the shorter one. ```rust 1 fn main() { 2 let keys = vec!["a", "b", "c"]; 3 let vals = vec![1, 2]; // shorter! 4 let z: Vec<(&str, i32)> = keys.iter().copied().zip(vals.iter().copied()).collect(); 5 println!("{z:?}"); // ("c", ...) is silently dropped 6 } ``` Verified output: ```text 1 [("a", 1), ("b", 2)] ``` **Fix:** if equal length is a real invariant, assert `keys.len() == vals.len()` before zipping, or look at the `itertools` crate’s `zip_eq` (panics on mismatch). Otherwise, the truncating behavior is exactly what you want. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Reach for a chain, fall back to a `for` loop for side effects [Section titled “1. Reach for a chain, fall back to a for loop for side effects”](#1-reach-for-a-chain-fall-back-to-a-for-loop-for-side-effects) Use adaptor chains to *transform data into a new value*. Use a plain `for` loop when the point is a **side effect** (printing, mutating external state, I/O). A chain that ends in `for_each` purely for side effects is usually less readable than the loop. ```rust 1 // Transforming -> use a chain ending in a consumer. 2 fn main() { 3 let prices = vec![100, 250, 75]; 4 let with_tax: Vec<i32> = prices.iter().map(|p| p * 110 / 100).collect(); 5 println!("{with_tax:?}"); // [110, 275, 82] 6 7 // Side effect -> use a for loop. 8 for p in &with_tax { 9 println!("charge {p} cents"); 10 } 11 } ``` ### 2. Let the adaptors carry the index — don’t track it manually [Section titled “2. Let the adaptors carry the index — don’t track it manually”](#2-let-the-adaptors-carry-the-index--dont-track-it-manually) Instead of a mutable counter, use `enumerate`. It is clearer and the index type (`usize`) is always correct. ```rust 1 // idiomatic 2 fn main() { 3 let items = vec!["x", "y", "z"]; 4 for (i, item) in items.iter().enumerate() { 5 println!("{i}: {item}"); 6 } 7 } ``` ### 3. Prefer `skip(n).take(m)` over manual index math for paging [Section titled “3. Prefer skip(n).take(m) over manual index math for paging”](#3-prefer-skipntakem-over-manual-index-math-for-paging) It reads as “skip a page, take a page,” handles short inputs gracefully (no panic), and allocates nothing until you `collect`. ### 4. Annotate `collect`’s target type [Section titled “4. Annotate collect’s target type”](#4-annotate-collects-target-type) `collect` is generic over its output, so the compiler needs to know what you want, either via a `let` annotation or the turbofish `::<>`: ```rust 1 fn main() { 2 let evens: Vec<i32> = (1..=10).filter(|n| n % 2 == 0).collect(); // annotate the binding 3 let odds = (1..=10).filter(|n| n % 2 == 1).collect::<Vec<i32>>(); // or turbofish 4 println!("{evens:?} {odds:?}"); 5 } ``` ### 5. Use `.copied()` / `.cloned()` to drop a layer of reference [Section titled “5. Use .copied() / .cloned() to drop a layer of reference”](#5-use-copied--cloned-to-drop-a-layer-of-reference) When chaining off `iter()` produces awkward `&&T` items or you want owned values out the other end, insert `.copied()` (for `Copy` types) or `.cloned()` (for owned types) early in the chain. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A log-processing pipeline: number raw log lines, parse them into structs, keep only warnings and errors, and cap the output at the first three problems, all in one lazy chain. This is the kind of code you’d write in a command-line tool or a server’s log scanner. ```rust 1 #[derive(Debug)] 2 struct LogLine { 3 line_no: usize, 4 level: String, 5 message: String, 6 } 7 8 fn main() { 9 // Raw log text, as you might read from a file. 10 let raw = "\ 11 INFO server started 12 DEBUG cache warmed 13 WARN high memory usage 14 ERROR db connection lost 15 INFO request handled 16 ERROR timeout on /api/users 17 DEBUG gc pause 12ms"; 18 19 // A single lazy pipeline: 20 // number the lines (enumerate) -> parse (map) -> 21 // keep WARN/ERROR (filter) -> cap at 3 (take) -> gather (collect). 22 let problems: Vec<LogLine> = raw 23 .lines() // an iterator over &str lines 24 .enumerate() // (0-based index, &str) 25 .map(|(i, line)| { 26 let (level, message) = line.split_once(' ').unwrap_or((line, "")); 27 LogLine { 28 line_no: i + 1, // humans count from 1 29 level: level.trim().to_string(), 30 message: message.trim().to_string(), 31 } 32 }) 33 .filter(|entry| entry.level == "WARN" || entry.level == "ERROR") 34 .take(3) 35 .collect(); 36 37 for p in &problems { 38 println!("line {:>2} [{}] {}", p.line_no, p.level, p.message); 39 } 40 41 // Total a severity score across the problems: map each one to a 42 // number, then let the `sum` consumer drive the chain. 43 let total: i32 = problems 44 .iter() 45 .map(|p| if p.level == "ERROR" { 10 } else { 3 }) 46 .sum(); 47 println!("total severity score: {total}"); 48 } ``` Verified output: ```text 1 line 3 [WARN] high memory usage 2 line 4 [ERROR] db connection lost 3 line 6 [ERROR] timeout on /api/users 4 total severity score: 23 ``` The pipeline never builds an intermediate `Vec` of all parsed lines; laziness fuses `enumerate -> map -> filter -> take` so the parser closure runs at most until three problems are found. `str::lines()` and `str::split_once()` are themselves iterator-friendly (covered in [String Manipulation](/07-collections/02-string-manipulation/)), and `.sum()` is a consumer from [Iterator Consumers](/07-collections/07-iterator-consumers/). The `unwrap_or` handles a malformed line without panicking, a taste of the error-handling discipline in [Section 08 — Error Handling](/08-error-handling/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [`std::iter::Iterator` API docs](https://doc.rust-lang.org/std/iter/trait.Iterator.html) — every adaptor and consumer, with examples * [The Rust Book — Processing a Series of Items with Iterators](https://doc.rust-lang.org/book/ch13-02-iterators.html) * [Rust by Example — Iterators](https://doc.rust-lang.org/rust-by-example/trait/iter.html) * [`std::iter` module docs](https://doc.rust-lang.org/std/iter/index.html) — laziness, `IntoIterator`, and free functions like `repeat`/`once` ### Related Topics in This Guide [Section titled “Related Topics in This Guide”](#related-topics-in-this-guide) * [Iterator Consumers](/07-collections/07-iterator-consumers/) — `collect`, `fold`, `sum`, `find`, `any`/`all`, `min`/`max`: how chains *end* * [Custom Iterators](/07-collections/08-custom-iterators/) — implementing the `Iterator` trait on your own types * [Vectors](/07-collections/00-vectors/) — `iter` / `iter_mut` / `into_iter` and the three borrow flavors * [String Manipulation](/07-collections/02-string-manipulation/) — `chars()`, `lines()`, `split()` return iterators too * [Collection Performance](/07-collections/09-collection-performance/) — iterator chains vs hand-written loops; when laziness pays off * [Section 03 — Functions](/03-functions/) — closures, the arrow-function analog passed to `map`/`filter` * [Section 05 — Ownership](/05-ownership/) — why `into_iter()` moves the collection * [Section 02 — Basics: Types](/02-basics/01-types/) — `usize`, `Option`, and integer types you’ll meet here *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Celsius to Fahrenheit [Section titled “Exercise 1: Celsius to Fahrenheit”](#exercise-1-celsius-to-fahrenheit) **Difficulty:** Beginner **Objective:** Practice a basic `map` chain ending in `collect`. **Instructions:** Given `let temps_c = vec![0.0, 25.0, 37.0, 100.0];`, build a new `Vec<f64>` of the same temperatures converted to Fahrenheit using the formula `f = c * 9/5 + 32`. Print the result. ```rust 1 fn main() { 2 let temps_c = vec![0.0, 25.0, 37.0, 100.0]; 3 // TODO: map each Celsius value to Fahrenheit and collect into a Vec<f64> 4 5 // TODO: print it 6 } ``` Solution ```rust 1 fn main() { 2 let temps_c = vec![0.0, 25.0, 37.0, 100.0]; 3 let temps_f: Vec<f64> = temps_c.iter().map(|c| c * 9.0 / 5.0 + 32.0).collect(); 4 println!("{temps_f:?}"); 5 } ``` Output: ```text 1 [32.0, 77.0, 98.6, 212.0] ``` ### Exercise 2: Paginated Passing Scores [Section titled “Exercise 2: Paginated Passing Scores”](#exercise-2-paginated-passing-scores) **Difficulty:** Intermediate **Objective:** Compose `enumerate`, `filter`, `skip`, and `take` in one lazy chain. **Instructions:** Given `let scores = vec![88, 42, 95, 60, 73, 31];`, produce a `Vec<(usize, i32)>` of `(original_index, score)` pairs where the score is a passing grade (`>= 60`), then skip the first passing result and take the next two. (Hint: `enumerate` *before* `filter` so the index reflects the original position.) ```rust 1 fn main() { 2 let scores = vec![88, 42, 95, 60, 73, 31]; 3 // TODO: enumerate -> filter passing -> skip(1) -> take(2) -> collect 4 } ``` Solution ```rust 1 fn main() { 2 let scores = vec![88, 42, 95, 60, 73, 31]; 3 let top_passing: Vec<(usize, i32)> = scores 4 .iter() 5 .copied() 6 .enumerate() 7 .filter(|(_, s)| *s >= 60) 8 .skip(1) 9 .take(2) 10 .collect(); 11 println!("{top_passing:?}"); 12 } ``` Output: ```text 1 [(2, 95), (3, 60)] ``` The passing scores are at indices 0, 2, 3, 4. `skip(1)` drops index 0; `take(2)` keeps indices 2 and 3. ### Exercise 3: Lazy Report Builder with `zip` [Section titled “Exercise 3: Lazy Report Builder with zip”](#exercise-3-lazy-report-builder-with-zip) **Difficulty:** Advanced **Objective:** Combine `zip`, `enumerate`, and `map` to merge two parallel iterators into formatted lines — and observe that `zip` truncates safely. **Instructions:** Given `let labels = vec!["jan", "feb", "mar"];` and `let revenue = vec![100, 150, 90];`, build a `Vec<String>` where each entry looks like `"1. jan: $100"` (a 1-based row number, the label, and the revenue). Use `zip` to pair labels with revenue and `enumerate` for the row number. Print each line. ```rust 1 fn main() { 2 let labels = vec!["jan", "feb", "mar"]; 3 let revenue = vec![100, 150, 90]; 4 // TODO: zip labels with revenue, enumerate, map to "N. label: $amount" strings 5 // TODO: print each line 6 } ``` Solution ```rust 1 fn main() { 2 let labels = vec!["jan", "feb", "mar"]; 3 let revenue = vec![100, 150, 90]; 4 let report: Vec<String> = labels 5 .iter() 6 .zip(revenue.iter()) 7 .enumerate() 8 .map(|(i, (label, amount))| format!("{}. {label}: ${amount}", i + 1)) 9 .collect(); 10 for line in &report { 11 println!("{line}"); 12 } 13 } ``` Output: ```text 1 1. jan: $100 2 2. feb: $150 3 3. mar: $90 ``` Note the destructuring `(i, (label, amount))`: `enumerate` wraps each `zip`-produced `(&&str, &i32)` tuple into `(usize, (&&str, &i32))`, and the pattern peels both layers apart. If `revenue` had only two entries, `zip` would simply produce two lines — no panic, no `undefined`. # Iterator Consumers: From Array Methods to `collect`, `fold`, and Friends > Iterator consumers run a Rust pipeline and return a value: collect, fold, sum, count, find, any, all, min, and max replace JS reduce, find, some, every. The sibling page on [iterators](/07-collections/06-iterators/) covered the **lazy** adaptors — `map`, `filter`, `take`, `zip` — that build a pipeline but compute nothing on their own. This page covers the other half: the **consuming adaptors** (or *consumers*) that actually run the pipeline and hand you a result. These are the methods that line up with `reduce`, `find`, `some`, `every`, and the implicit “now give me an array” that every JavaScript chain ends with. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **consumer** is an iterator method that takes ownership of the iterator (`self`, not `&mut self`), drives it to completion (or until it can short-circuit), and produces a final value: a number, a `bool`, an `Option`, or a whole new collection. In TypeScript an array method like `.reduce()` or `.filter()` always produces a value immediately; in Rust the lazy chain does nothing until a consumer like `collect`, `sum`, `fold`, `find`, `any`, `all`, or `max` is called at the end. **The consumer is what makes the whole pipeline run** — without one, the compiler will warn you that your iterator was never used. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Here is a realistic chunk of e-commerce analytics: given a list of orders, compute several aggregates. Notice every line produces a value eagerly, and that `.reduce()` on an empty array *throws*. ```typescript 1 interface Order { 2 id: number; 3 customer: string; 4 totalCents: number; 5 paid: boolean; 6 } 7 8 const orders: Order[] = [ 9 { id: 1, customer: "alice", totalCents: 4999, paid: true }, 10 { id: 2, customer: "bob", totalCents: 12000, paid: false }, 11 { id: 3, customer: "alice", totalCents: 8050, paid: true }, 12 { id: 4, customer: "carol", totalCents: 0, paid: true }, 13 ]; 14 15 // count → .filter(...).length 16 const paidCount = orders.filter((o) => o.paid).length; 17 18 // sum → .reduce(...) 19 const revenue = orders 20 .filter((o) => o.paid) 21 .reduce((sum, o) => sum + o.totalCents, 0); 22 23 // any / all → .some() / .every() 24 const hasUnpaid = orders.some((o) => !o.paid); 25 const allHaveCustomer = orders.every((o) => o.customer.length > 0); 26 27 // find → .find() (returns the element or undefined) 28 const firstBig = orders.find((o) => o.totalCents > 5000); 29 30 // max → .reduce() with a comparator (no built-in maxBy!) 31 const priciest = orders.reduce((best, o) => 32 o.totalCents > best.totalCents ? o : best 33 ); 34 35 // build a new array → .filter(...).map(...) 36 const paidCustomers = orders.filter((o) => o.paid).map((o) => o.customer); ``` Two things to keep in mind, because Rust handles them differently: `.find()` returns `undefined` when nothing matches (no error), and `.reduce()` with **no initial value** on an **empty** array throws a `TypeError`. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 #[derive(Debug)] 2 struct Order { 3 id: u32, 4 customer: String, 5 total_cents: u64, 6 paid: bool, 7 } 8 9 fn main() { 10 let orders = vec![ 11 Order { id: 1, customer: "alice".into(), total_cents: 4_999, paid: true }, 12 Order { id: 2, customer: "bob".into(), total_cents: 12_000, paid: false }, 13 Order { id: 3, customer: "alice".into(), total_cents: 8_050, paid: true }, 14 Order { id: 4, customer: "carol".into(), total_cents: 0, paid: true }, 15 ]; 16 17 // count: how many orders are paid? 18 let paid_count = orders.iter().filter(|o| o.paid).count(); 19 20 // sum: total revenue from paid orders, in cents. 21 let revenue: u64 = orders 22 .iter() 23 .filter(|o| o.paid) 24 .map(|o| o.total_cents) 25 .sum(); 26 27 // any / all: quick boolean checks that short-circuit. 28 let has_unpaid = orders.iter().any(|o| !o.paid); 29 let all_have_customer = orders.iter().all(|o| !o.customer.is_empty()); 30 31 // find: first matching element, as Option<&Order>. 32 let first_big = orders.iter().find(|o| o.total_cents > 5_000); 33 34 // max_by_key: the priciest order (Option, because the list could be empty). 35 let priciest = orders.iter().max_by_key(|o| o.total_cents); 36 37 // collect: build a brand-new Vec of just the paid customers' names. 38 let paid_customers: Vec<&str> = 39 orders.iter().filter(|o| o.paid).map(|o| o.customer.as_str()).collect(); 40 41 // fold: a running custom aggregation (here, a formatted receipt). 42 let receipt = orders.iter().fold(String::new(), |mut acc, o| { 43 acc.push_str(&format!("#{} ${:.2}\n", o.id, o.total_cents as f64 / 100.0)); 44 acc 45 }); 46 47 println!("paid_count = {paid_count}"); 48 println!("revenue (cents) = {revenue}"); 49 println!("has_unpaid = {has_unpaid}"); 50 println!("all_have_cust = {all_have_customer}"); 51 println!("first_big = {:?}", first_big.map(|o| o.id)); 52 println!("priciest = {:?}", priciest.map(|o| o.id)); 53 println!("paid_customers = {paid_customers:?}"); 54 print!("{receipt}"); 55 } ``` Real output: ```text 1 paid_count = 3 2 revenue (cents) = 13049 3 has_unpaid = true 4 all_have_cust = true 5 first_big = Some(2) 6 priciest = Some(2) 7 paid_customers = ["alice", "alice", "carol"] 8 #1 $49.99 9 #2 $120.00 10 #3 $80.50 11 #4 $0.00 ``` The aggregate numbers match the TypeScript version exactly (`paid_count = 3`, `revenue = 13049`). The differences are all about **types**. `find` and `max_by_key` give you an `Option`, never `undefined`; `count` returns a `usize`; and `revenue` needs an explicit `u64` annotation so `sum` knows what to add into. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `collect` — the universal “materialize” consumer [Section titled “collect — the universal “materialize” consumer”](#collect--the-universal-materialize-consumer) In TypeScript a chain *ends* in an array because the methods return arrays. In Rust the chain ends in `.collect()`, which can build **many** different collections (`Vec`, `String`, `HashMap`, `HashSet`, even `Result`) depending on the target type you ask for: ```rust 1 use std::collections::{HashMap, HashSet}; 2 3 fn main() { 4 let v: Vec<i32> = (1..=5).collect(); 5 let s: String = vec!['h', 'i', '!'].into_iter().collect(); 6 let set: HashSet<i32> = vec![1, 2, 2, 3, 3, 3].into_iter().collect(); 7 let map: HashMap<&str, i32> = vec![("a", 1), ("b", 2)].into_iter().collect(); 8 9 println!("v={v:?}"); 10 println!("s={s}"); 11 println!("set.len()={}", set.len()); 12 println!("map.get(b)={:?}", map.get("b")); 13 14 // Turbofish form: annotate the call instead of the binding. 15 let doubled = (1..=3).map(|n| n * 2).collect::<Vec<_>>(); 16 println!("doubled={doubled:?}"); 17 } ``` ```text 1 v=[1, 2, 3, 4, 5] 2 s=hi! 3 set.len()=3 4 map.get(b)=Some(2) 5 doubled=[2, 4, 6] ``` `collect` is generic over the trait `FromIterator`. Because the *same* call can produce a `Vec`, a `String`, a `HashMap`, and so on, **you must tell Rust which one you want**: either with a binding annotation (`let v: Vec<i32> =`) or with the `::<Vec<_>>` “turbofish”. This is the single biggest surprise for newcomers, and it has no TypeScript analogue, where `.map()` *always* returns an array. > **Tip:** When the element type is obvious but the container is not, use `collect::<Vec<_>>()`. The `_` lets the compiler infer the element type while you pin the container. ### `collect` into `Result` — short-circuiting validation [Section titled “collect into Result — short-circuiting validation”](#collect-into-result--short-circuiting-validation) One of the most useful tricks: an iterator of `Result`s can collect into a single `Result<Vec<_>, E>`. The first `Err` stops the process and becomes the whole result. This is the idiomatic way to “parse every item, but bail on the first failure”: ```rust 1 fn main() { 2 let good: Result<Vec<i32>, _> = 3 vec!["1", "2", "3"].iter().map(|s| s.parse::<i32>()).collect(); 4 let bad: Result<Vec<i32>, _> = 5 vec!["1", "x", "3"].iter().map(|s| s.parse::<i32>()).collect(); 6 7 println!("good={good:?}"); 8 println!("bad is_err={}", bad.is_err()); 9 } ``` ```text 1 good=Ok([1, 2, 3]) 2 bad is_err=true ``` There is no clean JavaScript equivalent. You would reach for a `for` loop with a `try/catch`, or `Promise.all` semantics if it were async. See [Section 08 — Error Handling](/08-error-handling/) for why this pattern is everywhere in Rust. ### `sum`, `product`, `count` — numeric reductions [Section titled “sum, product, count — numeric reductions”](#sum-product-count--numeric-reductions) ```rust 1 fn main() { 2 let total: i32 = (1..=5).sum(); // 1+2+3+4+5 3 let fact: u64 = (1..=5u64).product(); // 5! 4 let evens = (1..=10).filter(|n| n % 2 == 0).count(); 5 6 println!("total={total} fact={fact} evens={evens}"); 7 } ``` ```text 1 total=15 fact=120 evens=5 ``` `sum` and `product` are like `collect`: they are generic over the *output* type, so you usually annotate it (`let total: i32`). `count` always returns a `usize`, so it never needs annotating. Each replaces a `reduce` you would write by hand in JavaScript. ### `min`, `max`, and the `_by` / `_by_key` family [Section titled “min, max, and the \_by / \_by\_key family”](#min-max-and-the-_by--_by_key-family) ```rust 1 fn main() { 2 let nums = vec![3, 7, 2, 9, 4]; 3 println!("min={:?} max={:?}", nums.iter().min(), nums.iter().max()); 4 5 let words = vec!["pear", "fig", "banana"]; 6 println!("longest={:?}", words.iter().max_by_key(|w| w.len())); 7 println!("shortest={:?}", words.iter().min_by_key(|w| w.len())); 8 9 // f64 isn't `Ord`, so plain `.max()` won't compile — fold with f64::max. 10 let temps = vec![19.5_f64, 22.0, 18.0]; 11 let hottest = temps.iter().cloned().fold(f64::MIN, f64::max); 12 println!("hottest={hottest}"); 13 } ``` ```text 1 min=Some(2) max=Some(9) 2 longest=Some("banana") 3 shortest=Some("fig") 4 hottest=22 ``` JavaScript has no `Array.prototype.maxBy`; you write `.reduce()` with a comparator. Rust gives you the whole family directly: * `min` / `max`: compare elements with their natural ordering (`Ord`). * `min_by_key` / `max_by_key`: compare a derived key (cheap, computed once per element). * `min_by` / `max_by`: compare with a custom `|a, b| a.cmp(b)` closure returning `Ordering`. All of them return `Option<T>` (`None` for an empty iterator). The `f64` case is a real gotcha covered under [Common Pitfalls](#common-pitfalls): floats are not totally ordered (because of `NaN`), so `f64` does not implement `Ord`, and `.max()` won’t compile. ### `find`, `position`, `find_map` — “give me the first one that…” [Section titled “find, position, find\_map — “give me the first one that…””](#find-position-find_map--give-me-the-first-one-that) ```rust 1 fn main() { 2 let data = vec!["", " ", "hello", "world"]; 3 4 // find: first ELEMENT matching the predicate. 5 let first_nonblank = data.iter().find(|s| !s.trim().is_empty()); 6 7 // position: INDEX of the first match (like Array.prototype.findIndex). 8 let idx = data.iter().position(|s| !s.trim().is_empty()); 9 10 // find_map: first item where the closure returns Some(...). 11 let parsed = vec!["x", "12", "y"].iter().find_map(|s| s.parse::<i32>().ok()); 12 13 println!("first_nonblank={first_nonblank:?}"); 14 println!("idx={idx:?}"); 15 println!("parsed={parsed:?}"); 16 } ``` ```text 1 first_nonblank=Some("hello") 2 idx=Some(2) 3 parsed=Some(12) ``` `find` ≈ `Array.prototype.find`, `position` ≈ `findIndex`, and `find_map` has no single JS equivalent: it is `find` and `map` fused so you compute the transformed value exactly once for the first match. All of them **short-circuit**: they stop the moment they have an answer, never touching the rest of the iterator. ### `any` / `all` — the boolean short-circuiters [Section titled “any / all — the boolean short-circuiters”](#any--all--the-boolean-short-circuiters) ```rust 1 fn main() { 2 let nums = vec![2, 4, 6, 8]; 3 let has_odd = nums.iter().any(|n| n % 2 == 1); // like .some() 4 let all_even = nums.iter().all(|n| n % 2 == 0); // like .every() 5 6 // Edge cases on an EMPTY iterator — note the defaults! 7 let any_empty = std::iter::empty::<i32>().any(|n| n > 0); 8 let all_empty = std::iter::empty::<i32>().all(|n| n > 0); 9 10 println!("has_odd={has_odd} all_even={all_even}"); 11 println!("any_empty={any_empty} all_empty={all_empty}"); 12 } ``` ```text 1 has_odd=false all_even=true 2 any_empty=false all_empty=true ``` These behave exactly like JavaScript’s `some`/`every`, including the “vacuous truth” defaults: `any` on an empty iterator is `false`, `all` on an empty iterator is `true`. ### `fold` vs `reduce` — the key distinction [Section titled “fold vs reduce — the key distinction”](#fold-vs-reduce--the-key-distinction) This is where Rust splits one JavaScript method into two: ```rust 1 fn main() { 2 // fold: you SUPPLY a seed, so the result type can differ from the items. 3 let folded = (1..=4).fold(100, |acc, n| acc + n); // 100 + 1+2+3+4 4 5 // reduce: NO seed; the first item is the seed. Returns Option. 6 let reduced = (1..=4).reduce(|acc, n| acc + n); 7 8 // reduce on an EMPTY iterator returns None — it does NOT panic. 9 let empty_reduced = std::iter::empty::<i32>().reduce(|a, b| a + b); 10 11 println!("folded={folded} reduced={reduced:?} empty_reduced={empty_reduced:?}"); 12 } ``` ```text 1 folded=110 reduced=Some(10) empty_reduced=None ``` * **`fold(init, f)`** ≈ JavaScript `reduce(f, initialValue)`. The accumulator type comes from `init`, so it can be anything: a number, a `String`, a `HashMap`. This is the workhorse for building up custom aggregates (the receipt-building example earlier folds into a `String`). * **`reduce(f)`** ≈ JavaScript `reduce(f)` *without* an initial value. Because there might be zero elements, Rust returns `Option<T>` instead of throwing. This is the important safety difference: JavaScript’s seedless `[].reduce(...)` throws a `TypeError`; Rust’s `reduce` quietly gives you `None`. Reach for `fold` by default. Reach for `reduce` only when there is no sensible identity value (e.g. “combine these UI nodes into one”) and you genuinely want the `Option`. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / JavaScript | Rust | Notes | | --------------------- | ------------------------------------- | ------------------------------------------------ | ------------------------------------- | | Build a collection | implicit; methods return arrays | explicit `.collect()` | must annotate the target type | | Multiple target types | always `Array` | `Vec`, `String`, `HashMap`, `HashSet`, `Result`… | one method, many `FromIterator` impls | | Sum | `arr.reduce((a, b) => a + b, 0)` | `.sum::<T>()` | annotate the numeric type | | Count | `arr.length` after filtering | `.count()` | returns `usize` | | First match (value) | `.find()` → element \| `undefined` | `.find()` → `Option<T>` | no `undefined`/`null` | | First match (index) | `.findIndex()` → `number` (`-1` miss) | `.position()` → `Option<usize>` | `None`, not `-1` | | Some / every | `.some()` / `.every()` | `.any()` / `.all()` | identical short-circuit semantics | | Max element | `.reduce()` with comparator | `.max()`, `.max_by_key()`, `.max_by()` | built-in; returns `Option` | | Reduce with seed | `.reduce(f, init)` | `.fold(init, f)` | accumulator type = seed type | | Reduce without seed | `.reduce(f)` — **throws if empty** | `.reduce(f)` → `Option<T>` | `None` instead of a `TypeError` | | Laziness | eager, runs at each call | lazy, runs only at the consumer | the consumer drives the chain | > **Note:** The deepest difference is **laziness**. A JavaScript `.filter().map()` builds two intermediate arrays immediately. A Rust `.filter().map()` builds *nothing*. It is a description of work that only happens when a consumer like `collect`, `sum`, or `for` pulls items through. See [Iterators](/07-collections/06-iterators/) for the full story on lazy adaptors. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: `collect` (or `sum`) with no type annotation [Section titled “Pitfall 1: collect (or sum) with no type annotation”](#pitfall-1-collect-or-sum-with-no-type-annotation) The compiler cannot guess which collection or numeric type you want: ```rust 1 fn main() { 2 let doubled = (1..=3).map(|n| n * 2).collect(); // does not compile (error[E0283]) 3 println!("{doubled:?}"); 4 } ``` Real `rustc` output: ```text 1 error[E0283]: type annotations needed 2 --> src/main.rs:2:9 3 | 4 2 | let doubled = (1..=3).map(|n| n * 2).collect(); 5 | ^^^^^^^ ------- type must be known at this point 6 | 7 = note: cannot satisfy `_: FromIterator<i32>` 8 help: consider giving `doubled` an explicit type 9 | 10 2 | let doubled: Vec<_> = (1..=3).map(|n| n * 2).collect(); 11 | ++++++++ ``` The same `E0283` appears for `sum`: ```rust 1 fn main() { 2 let nums = vec![1, 2, 3]; 3 let total = nums.iter().sum(); // does not compile (error[E0283]: type annotations needed) 4 println!("{total}"); 5 } ``` ```text 1 error[E0283]: type annotations needed 2 --> src/main.rs:3:9 3 | 4 3 | let total = nums.iter().sum(); 5 | ^^^^^ --- type must be known at this point 6 | 7 = note: cannot satisfy `_: Sum<&i32>` 8 help: consider giving `total` an explicit type 9 | 10 3 | let total: /* Type */ = nums.iter().sum(); 11 | ++++++++++++ ``` **Fix:** annotate the binding (`let total: i32`) or use a turbofish (`.sum::<i32>()`, `.collect::<Vec<_>>()`). ### Pitfall 2: using an iterator after a consumer has eaten it [Section titled “Pitfall 2: using an iterator after a consumer has eaten it”](#pitfall-2-using-an-iterator-after-a-consumer-has-eaten-it) Consumers take `self` by value. Once you call one, the iterator is **moved** and gone; you cannot call a second consumer on the same iterator: ```rust 1 fn main() { 2 let nums = vec![1, 2, 3]; 3 let it = nums.iter(); 4 let count = it.count(); // count() consumes `it` 5 let total: i32 = it.sum(); // does not compile (error[E0382]: use of moved value) 6 println!("{count} {total}"); 7 } ``` Real `rustc` output (trimmed): ```text 1 error[E0382]: use of moved value: `it` 2 --> src/main.rs:5:22 3 | 4 3 | let it = nums.iter(); 5 | -- move occurs because `it` has type `std::slice::Iter<'_, i32>`, which does not implement the `Copy` trait 6 4 | let count = it.count(); // count() consumes `it` 7 | ------- `it` moved due to this method call 8 5 | let total: i32 = it.sum(); // 9 | ^^ value used here after move ``` **Fix:** make a fresh iterator each time (`nums.iter().count()` then `nums.iter().sum()`), since `iter()` only borrows the `Vec`. In TypeScript you would just call two methods on the same array; an iterator is single-use, more like a generator you have already exhausted. ### Pitfall 3: `min`/`max` on floats [Section titled “Pitfall 3: min/max on floats”](#pitfall-3-minmax-on-floats) `f64` and `f32` are **not** `Ord` (because `NaN` breaks total ordering), so `.min()` / `.max()` simply do not exist for them: ```rust 1 fn main() { 2 let temps = vec![19.5_f64, 22.0, 18.0]; 3 let hottest = temps.iter().max(); // does not compile (error[E0277]: f64: Ord not satisfied) 4 println!("{hottest:?}"); 5 } ``` ```text 1 error[E0277]: the trait bound `f64: Ord` is not satisfied 2 --> src/main.rs:3:32 3 | 4 3 | let hottest = temps.iter().max(); 5 | ^^^ the trait `Ord` is not implemented for `f64` ``` **Fix:** decide how to treat `NaN` yourself. The simplest is to fold with the partial-order-aware `f64::max`: `temps.iter().cloned().fold(f64::MIN, f64::max)`. Or use `.max_by(|a, b| a.partial_cmp(b).unwrap())` if you are certain there are no `NaN`s. This is a place where the analogy to JavaScript’s `Math.max(...arr)` (which silently returns `NaN` if any element is `NaN`) breaks down. Rust forces you to confront the ambiguity. ### Pitfall 4: forgetting the consumer entirely [Section titled “Pitfall 4: forgetting the consumer entirely”](#pitfall-4-forgetting-the-consumer-entirely) A chain of lazy adaptors with no consumer does nothing, and the compiler warns: ```rust 1 fn main() { 2 let nums = vec![1, 2, 3]; 3 nums.iter().map(|n| println!("{n}")); // runs NOTHING; warning: unused `Map` 4 } ``` Rust emits `warning: unused 'Map' that must be used` with the note `iterators are lazy and do nothing unless consumed`. If you wanted side effects, use a `for` loop or the `for_each` consumer: `nums.iter().for_each(|n| println!("{n}"));`. Coming from JavaScript, where `.map()` always executes, this is the most common “why is nothing happening?” moment. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Pick the most specific consumer.** Prefer `count()` over `.collect::<Vec<_>>().len()`, `sum()` over a hand-rolled `fold`, and `max_by_key` over `fold` with a manual comparison. They are clearer and let the compiler optimize. * **Annotate the output type at the consumer.** `let total: u64 = ...` or `.sum::<u64>()`. Decide the integer width deliberately to avoid overflow on large sums. * **Use `collect::<Result<Vec<_>, _>>()` for fallible pipelines.** It short-circuits on the first error and keeps the happy path flat — no manual loop with early returns. * **Reach for `fold` over `reduce`.** `fold` is total (always returns a value) and lets the accumulator be any type. Use `reduce` only when there is genuinely no identity element and you want the `Option`. * **`partition` splits in one pass.** When you would write two `filter`s, use `partition` instead. It walks the iterator once and returns a `(matches, rest)` tuple: ```rust 1 fn main() { 2 let nums = vec![1, 2, 3, 4, 5, 6]; 3 let (evens, odds): (Vec<i32>, Vec<i32>) = nums.iter().partition(|&&n| n % 2 == 0); 4 println!("evens={evens:?} odds={odds:?}"); 5 } ``` ```text 1 evens=[2, 4, 6] odds=[1, 3, 5] ``` * **Use `try_fold` for short-circuiting accumulation.** It stops at the first `None`/`Err`, which is perfect for checked arithmetic or validation that builds state: ```rust 1 fn main() { 2 let nums = vec![1, 2, 3, 4]; 3 let checked: Option<i32> = nums.iter().try_fold(0i32, |acc, &n| acc.checked_add(n)); 4 println!("{checked:?}"); // Some(10); None if any add overflowed 5 } ``` ```text 1 Some(10) ``` > **Tip:** Run `cargo clippy`. It will nudge you toward the idiomatic consumer — e.g. flagging a `fold` that should be a `sum` (via the default `clippy::unnecessary_fold` lint). And with the nursery lint `clippy::needless_collect` enabled (`-W clippy::needless_collect`), it suggests `.count()` instead of collecting just to call `.len()`. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small log-analysis pass: parse raw lines into structured entries, drop the malformed ones, and compute a handful of metrics, every one of them a different consumer. ```rust 1 use std::collections::HashMap; 2 3 #[derive(Debug, Clone)] 4 struct LogEntry { 5 status: u16, 6 bytes: u64, 7 path: String, 8 } 9 10 fn parse(line: &str) -> Option<LogEntry> { 11 let mut parts = line.split_whitespace(); 12 let status = parts.next()?.parse::<u16>().ok()?; 13 let bytes = parts.next()?.parse::<u64>().ok()?; 14 let path = parts.next()?.to_string(); 15 Some(LogEntry { status, bytes, path }) 16 } 17 18 fn main() { 19 let raw = "\ 20 200 1024 /home 21 404 0 /missing 22 200 2048 /home 23 500 0 /api 24 200 512 /about 25 bad line 26 301 128 /old"; 27 28 // Parse every line, silently dropping the ones that don't parse (filter_map). 29 let entries: Vec<LogEntry> = raw.lines().filter_map(parse).collect(); 30 31 // sum: total bytes served. 32 let total_bytes: u64 = entries.iter().map(|e| e.bytes).sum(); 33 34 // any: did anything 5xx happen? (short-circuits) 35 let has_5xx = entries.iter().any(|e| e.status >= 500); 36 37 // count + count: success rate. 38 let ok = entries.iter().filter(|e| (200..300).contains(&e.status)).count(); 39 let success_rate = ok as f64 / entries.len() as f64; 40 41 // fold into a HashMap, then max_by_key: the busiest path. 42 let hits = entries.iter().fold(HashMap::<&str, u32>::new(), |mut acc, e| { 43 *acc.entry(e.path.as_str()).or_insert(0) += 1; 44 acc 45 }); 46 let busiest = hits.iter().max_by_key(|(_, count)| **count); 47 48 // partition: separate redirects from everything else, in one pass. 49 let (redirects, others): (Vec<_>, Vec<_>) = 50 entries.iter().partition(|e| (300..400).contains(&e.status)); 51 52 println!("parsed entries = {}", entries.len()); 53 println!("total_bytes = {total_bytes}"); 54 println!("has_5xx = {has_5xx}"); 55 println!("success_rate = {success_rate:.2}"); 56 println!("busiest = {:?}", busiest.map(|(p, c)| (*p, *c))); 57 println!("redirects = {}", redirects.len()); 58 println!("others = {}", others.len()); 59 } ``` Real output: ```text 1 parsed entries = 6 2 total_bytes = 3712 3 has_5xx = true 4 success_rate = 0.50 5 busiest = Some(("/home", 2)) 6 redirects = 1 7 others = 5 ``` Every metric is a consumer doing one job: `filter_map(...).collect()` to materialize, `sum` for bytes, `any` for the 5xx check, `count` for the rate, `fold` + `max_by_key` for the busiest path, and `partition` for the split. In TypeScript this would be a mix of `.filter().map()`, manual `.reduce()` accumulators, and an object-as-map for the counts; and `parse` returning `Option` would instead be `null`-checks scattered through the pipeline. > **Note:** Building the frequency map with `fold` here is idiomatic, but for grouping you will often reach for the `entry` API directly in a loop — see [HashMaps](/07-collections/03-hashmaps/). And `filter_map(parse)` works because `parse` returns `Option`; that is the consumer-side payoff of returning `Option` from fallible helpers, covered in [Section 08 — Error Handling](/08-error-handling/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [`Iterator` trait — all consuming methods](https://doc.rust-lang.org/std/iter/trait.Iterator.html): `collect`, `fold`, `sum`, `find`, `any`, `all`, `max`, and the rest * [`FromIterator` trait](https://doc.rust-lang.org/std/iter/trait.FromIterator.html): what makes `collect` polymorphic over the target type * [The Rust Book — Processing a Series of Items with Iterators](https://doc.rust-lang.org/book/ch13-02-iterators.html) * [Rust by Example — Iterators](https://doc.rust-lang.org/rust-by-example/trait/iter.html) ### Related Topics in This Guide [Section titled “Related Topics in This Guide”](#related-topics-in-this-guide) * [Iterators](/07-collections/06-iterators/) — the **lazy** adaptors (`map`, `filter`, `take`, `zip`, `enumerate`) that feed these consumers * [Custom Iterators](/07-collections/08-custom-iterators/): implement `Iterator` for your own types so every consumer here works on them * [Vectors](/07-collections/00-vectors/): `Vec<T>`, the most common thing you `collect` into * [HashMaps](/07-collections/03-hashmaps/) and [HashSets](/07-collections/04-hashsets/): also valid `collect` targets * [Collection Performance](/07-collections/09-collection-performance/): when an iterator chain beats a manual loop, and pre-sizing `collect` * [Section 08 — Error Handling](/08-error-handling/): `collect::<Result<_, _>>()` and returning `Option`/`Result` from pipeline helpers * [Section 02 — Basics: Types](/02-basics/01-types/): `usize`, `Option`, and why `f64` is not `Ord` * [Section 01 — Getting Started](/01-getting-started/): setting up `cargo` to run these examples *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Order statistics [Section titled “Exercise 1: Order statistics”](#exercise-1-order-statistics) **Difficulty:** Beginner **Objective:** Combine `sum`, `max`, and `count` (via `len`) into one function, handling the empty case. **Instructions:** Write `order_stats(prices: &[u32]) -> (u32, u32, f64)` returning `(total, max, average)`. For an empty slice it must return `(0, 0, 0.0)` and must **not** panic. (Hint: `max()` returns an `Option`; use `unwrap_or(0)`.) ```rust 1 fn order_stats(prices: &[u32]) -> (u32, u32, f64) { 2 // TODO: total via sum, max via max(), average guarding against empty 3 todo!() 4 } 5 6 fn main() { 7 let (t, m, a) = order_stats(&[1200, 950, 4000, 300]); 8 println!("total={t} max={m} avg={a:.2}"); 9 assert_eq!(order_stats(&[]), (0, 0, 0.0)); 10 println!("ok"); 11 } ``` Solution ```rust 1 fn order_stats(prices: &[u32]) -> (u32, u32, f64) { 2 let count = prices.len(); 3 let total: u32 = prices.iter().sum(); 4 let max = prices.iter().copied().max().unwrap_or(0); 5 let avg = if count == 0 { 6 0.0 7 } else { 8 total as f64 / count as f64 9 }; 10 (total, max, avg) 11 } 12 13 fn main() { 14 let (t, m, a) = order_stats(&[1200, 950, 4000, 300]); 15 println!("total={t} max={m} avg={a:.2}"); 16 assert_eq!(order_stats(&[]), (0, 0, 0.0)); 17 println!("ok"); 18 } ``` Output: ```text 1 total=6450 max=4000 avg=1612.50 2 ok ``` ### Exercise 2: Validate and sum in one pass [Section titled “Exercise 2: Validate and sum in one pass”](#exercise-2-validate-and-sum-in-one-pass) **Difficulty:** Intermediate **Objective:** Use `collect` into a `Result` to parse a list of strings, bailing on the first bad one. **Instructions:** Write `parse_all(tokens: &[&str]) -> Result<i32, std::num::ParseIntError>` that parses every token as `i32` and returns their **sum**, or the first parse error. Do not write a manual loop with early returns — let `collect` do the short-circuiting. ```rust 1 fn parse_all(tokens: &[&str]) -> Result<i32, std::num::ParseIntError> { 2 // TODO: map -> collect into Result<Vec<i32>, _>, then sum 3 todo!() 4 } 5 6 fn main() { 7 assert_eq!(parse_all(&["1", "2", "3"]).unwrap(), 6); 8 assert!(parse_all(&["1", "oops", "3"]).is_err()); 9 println!("ok"); 10 } ``` Solution ```rust 1 fn parse_all(tokens: &[&str]) -> Result<i32, std::num::ParseIntError> { 2 let nums: Vec<i32> = tokens 3 .iter() 4 .map(|t| t.parse::<i32>()) 5 .collect::<Result<_, _>>()?; 6 Ok(nums.iter().sum()) 7 } 8 9 fn main() { 10 assert_eq!(parse_all(&["1", "2", "3"]).unwrap(), 6); 11 assert!(parse_all(&["1", "oops", "3"]).is_err()); 12 println!("ok"); 13 } ``` The `?` unwraps the `Result<Vec<i32>, _>` produced by `collect`; if any token failed to parse, that error is returned immediately. Output: ```text 1 ok ``` ### Exercise 3: Most common word [Section titled “Exercise 3: Most common word”](#exercise-3-most-common-word) **Difficulty:** Advanced **Objective:** Chain a transforming pipeline with a `fold`-built frequency map and a `max_by_key` consumer. **Instructions:** Write `most_common_word(text: &str) -> Option<(String, u32)>` that lowercases words, strips surrounding punctuation, ignores empty tokens, counts occurrences, and returns the most frequent `(word, count)` — or `None` for empty input. (Hints: `split_whitespace`, `trim_matches`, `to_lowercase`, `fold` into a `HashMap<String, u32>`, then `into_iter().max_by_key(...)`.) ```rust 1 use std::collections::HashMap; 2 3 fn most_common_word(text: &str) -> Option<(String, u32)> { 4 // TODO: normalize words, fold into a count map, then max_by_key 5 todo!() 6 } 7 8 fn main() { 9 let text = "The fox, the hound, and THE FOX!"; 10 println!("{:?}", most_common_word(text)); 11 assert_eq!(most_common_word(""), None); 12 println!("ok"); 13 } ``` Solution ```rust 1 use std::collections::HashMap; 2 3 fn most_common_word(text: &str) -> Option<(String, u32)> { 4 let counts = text 5 .split_whitespace() 6 .map(|w| w.trim_matches(|c: char| !c.is_alphanumeric()).to_lowercase()) 7 .filter(|w| !w.is_empty()) 8 .fold(HashMap::<String, u32>::new(), |mut acc, w| { 9 *acc.entry(w).or_insert(0) += 1; 10 acc 11 }); 12 13 counts.into_iter().max_by_key(|(_, count)| *count) 14 } 15 16 fn main() { 17 let text = "The fox, the hound, and THE FOX!"; 18 println!("{:?}", most_common_word(text)); 19 assert_eq!(most_common_word(""), None); 20 println!("ok"); 21 } ``` Output: ```text 1 Some(("the", 3)) 2 ok ``` > **Note:** `max_by_key` returns *some* maximal element when several tie; which one is unspecified for `HashMap` iteration order. If you need deterministic tie-breaking, fold into a [`BTreeMap`](/07-collections/05-btreemap-btreeset/) or sort first. # Custom Iterators: Implementing `Iterator` and `IntoIterator` > Build custom sequences in Rust: implement Iterator's next and IntoIterator instead of a JS generator, then inherit map, filter, zip, and more for free. In TypeScript you make a value iterable by writing a **generator** (`function*`) or by implementing the `[Symbol.iterator]()` protocol. In Rust you do the equivalent by implementing the **`Iterator`** trait (define one method, `next`) and, when you want `for` loops to work directly on your type, the **`IntoIterator`** trait. This page shows how to build your own lazy data producers and plug them into Rust’s entire adaptor toolbox for free. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Rust’s iteration is built on two **traits**. **`Iterator`** has a single required method, `next(&mut self) -> Option<Self::Item>`, that yields values one at a time and signals “done” with `None`, exactly like a JavaScript generator yielding values and finally `{ done: true }`. **`IntoIterator`** is what `for x in thing` actually calls; implementing it makes your own collection loopable. The huge payoff: once you implement `next`, you automatically get `map`, `filter`, `take`, `zip`, `sum`, `collect`, and every other adaptor. You write five lines and inherit a hundred methods. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript, the idiomatic way to produce a custom sequence is a generator function. To make a *class* iterable, you implement the `Symbol.iterator` protocol. ```typescript 1 // A generator that produces Fibonacci numbers lazily, forever. 2 function* fibonacci(): Generator<number> { 3 let [a, b] = [0, 1]; 4 while (true) { 5 yield a; 6 [a, b] = [b, a + b]; 7 } 8 } 9 10 // Generators are lazy: nothing runs until you pull values out. 11 const firstTen: number[] = []; 12 for (const n of fibonacci()) { 13 if (firstTen.length === 10) break; // we must stop it ourselves 14 firstTen.push(n); 15 } 16 console.log(firstTen); // [0, 1, 1, 2, 3, 5, 8, 13, 21, 34] 17 18 // Making a class iterable via the Symbol.iterator protocol. 19 class Playlist { 20 constructor(private tracks: string[]) {} 21 22 *[Symbol.iterator](): Generator<string> { 23 for (const track of this.tracks) { 24 yield track; 25 } 26 } 27 } 28 29 const playlist = new Playlist(["Intro", "Verse", "Chorus"]); 30 for (const track of playlist) { 31 console.log(track); 32 } 33 const upper = [...playlist].map((t) => t.toUpperCase()); 34 console.log(upper); // [ 'INTRO', 'VERSE', 'CHORUS' ] ``` Two things to carry into Rust: the generator is **lazy** (no values are computed until consumed), and the `for...of` loop secretly calls the object’s `[Symbol.iterator]()` method to obtain an iterator. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust splits the same job across `Iterator` (the thing that produces values) and `IntoIterator` (the thing that *hands you* a producer). First, the Fibonacci producer: ```rust 1 struct Fibonacci { 2 a: u64, 3 b: u64, 4 } 5 6 impl Iterator for Fibonacci { 7 type Item = u64; // what each `next()` yields 8 9 fn next(&mut self) -> Option<u64> { 10 let current = self.a; 11 self.a = self.b; 12 self.b = current + self.b; 13 Some(current) // never None -> this is an INFINITE iterator 14 } 15 } 16 17 fn fib() -> Fibonacci { 18 Fibonacci { a: 0, b: 1 } 19 } 20 21 fn main() { 22 // Lazy, like the JS generator. `take(10)` bounds the infinite stream. 23 let first_ten: Vec<u64> = fib().take(10).collect(); 24 println!("{first_ten:?}"); 25 26 // The whole adaptor library is available because we implemented `next`. 27 let sum: u64 = fib().take_while(|&n| n < 100).filter(|n| n % 2 == 0).sum(); 28 println!("sum of even fibs < 100: {sum}"); 29 } ``` Verified output: ```text 1 [0, 1, 1, 2, 3, 5, 8, 13, 21, 34] 2 sum of even fibs < 100: 44 ``` Now the `Playlist` equivalent. Implement `IntoIterator` so `for track in playlist` works: ```rust 1 struct Playlist { 2 tracks: Vec<String>, 3 } 4 5 impl IntoIterator for Playlist { 6 type Item = String; 7 type IntoIter = std::vec::IntoIter<String>; 8 9 fn into_iter(self) -> Self::IntoIter { 10 self.tracks.into_iter() // delegate to Vec's iterator 11 } 12 } 13 14 fn main() { 15 let playlist = Playlist { 16 tracks: vec!["Intro".into(), "Verse".into(), "Chorus".into()], 17 }; 18 for track in playlist { 19 println!("{track}"); 20 } 21 } ``` Verified output: ```text 1 Intro 2 Verse 3 Chorus ``` *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The `Iterator` trait is just one method [Section titled “The Iterator trait is just one method”](#the-iterator-trait-is-just-one-method) Here is the trait, reduced to its essence (the standard library defines dozens of additional methods, but they all have default implementations built on top of `next`): ```rust 1 // From the standard library (simplified). 2 pub trait Iterator { 3 type Item; // associated type: what you yield 4 fn next(&mut self) -> Option<Self::Item>; // the ONE method you must write 5 // ...70+ provided methods: map, filter, take, sum, collect, ... 6 } ``` * **`type Item`** is an *associated type*: the type of each yielded value. It is the rough analogue of the `T` in TypeScript’s `Generator<T>`. (Associated types are covered in [Section 06 — Associated Types](/06-data-structures/07-associated-types/).) * **`next(&mut self)`** takes `&mut self` because pulling a value mutates the iterator’s internal state (advancing the cursor). It returns `Option<Self::Item>`: `Some(value)` while values remain, `None` once exhausted. That `None` is Rust’s `{ done: true }`. Because every adaptor is built on `next`, implementing that single method gives your type `map`, `filter`, `enumerate`, `zip`, `fold`, `collect`, and the rest, for free. This is the central reason custom iterators are worth the small boilerplate. ### A minimal example, step by step [Section titled “A minimal example, step by step”](#a-minimal-example-step-by-step) ```rust 1 struct Countdown { 2 current: u32, 3 } 4 5 impl Iterator for Countdown { 6 type Item = u32; 7 8 fn next(&mut self) -> Option<Self::Item> { 9 if self.current == 0 { 10 None // exhausted: signal "done" 11 } else { 12 self.current -= 1; // mutate state for next time 13 Some(self.current + 1) // yield the pre-decrement value 14 } 15 } 16 } 17 18 fn main() { 19 let cd = Countdown { current: 3 }; 20 for n in cd { 21 print!("{n} "); 22 } 23 println!(); 24 25 let cd2 = Countdown { current: 5 }; 26 let doubled: Vec<u32> = cd2.map(|n| n * 2).collect(); 27 println!("{doubled:?}"); 28 } ``` Verified output: ```text 1 3 2 1 2 [10, 8, 6, 4, 2] ``` The loop calls `next()` repeatedly until it returns `None`. The `cd2.map(...).collect()` line proves the payoff: we never wrote `map` or `collect`, yet they work because the trait provides them on top of our `next`. ### `IntoIterator`: what `for` actually calls [Section titled “IntoIterator: what for actually calls”](#intoiterator-what-for-actually-calls) A `for` loop in Rust is **syntactic sugar**. This: ```rust 1 fn main() { 2 let v = vec![1, 2, 3]; 3 4 // This loop... 5 for x in &v { 6 print!("{x} "); 7 } 8 println!(); 9 10 // ...is exactly this, written out by hand: 11 let mut it = IntoIterator::into_iter(&v); 12 while let Some(x) = it.next() { 13 print!("{x} "); 14 } 15 println!(); 16 } ``` Verified output: ```text 1 1 2 3 2 1 2 3 ``` `for thing in expr` calls `IntoIterator::into_iter(expr)` to get an iterator, then loops on `next()`. This is the direct counterpart of JavaScript’s `for...of` calling `expr[Symbol.iterator]()`. `Iterator` and `IntoIterator` are distinct traits, but every `Iterator` also implements `IntoIterator` (its `into_iter` just returns itself), which is why you can write `for x in some_iterator` as well as `for x in some_collection`. ### Implementing `IntoIterator` three ways (by value, `&`, `&mut`) [Section titled “Implementing IntoIterator three ways (by value, &, \&mut)”](#implementing-intoiterator-three-ways-by-value--mut) Standard collections let you write `for x in v`, `for x in &v`, and `for x in &mut v`. You get the same flexibility for your own type by implementing `IntoIterator` once per ownership flavor. The trick is that you implement it for `Grid`, `&Grid`, and `&mut Grid` separately: ```rust 1 struct Grid { 2 cells: Vec<i32>, 3 } 4 5 // by value (consuming): `for c in grid` 6 impl IntoIterator for Grid { 7 type Item = i32; 8 type IntoIter = std::vec::IntoIter<i32>; 9 fn into_iter(self) -> Self::IntoIter { 10 self.cells.into_iter() 11 } 12 } 13 14 // by shared reference: `for c in &grid` 15 impl<'a> IntoIterator for &'a Grid { 16 type Item = &'a i32; 17 type IntoIter = std::slice::Iter<'a, i32>; 18 fn into_iter(self) -> Self::IntoIter { 19 self.cells.iter() 20 } 21 } 22 23 // by mutable reference: `for c in &mut grid` 24 impl<'a> IntoIterator for &'a mut Grid { 25 type Item = &'a mut i32; 26 type IntoIter = std::slice::IterMut<'a, i32>; 27 fn into_iter(self) -> Self::IntoIter { 28 self.cells.iter_mut() 29 } 30 } 31 32 fn main() { 33 let mut g = Grid { cells: vec![1, 2, 3] }; 34 35 // &mut Grid -> mutate in place 36 for c in &mut g { 37 *c *= 10; 38 } 39 40 // &Grid -> read-only 41 for c in &g { 42 print!("{c} "); 43 } 44 println!(); 45 46 // Grid (by value) -> consume 47 let total: i32 = g.into_iter().sum(); 48 println!("total = {total}"); 49 } ``` Verified output: ```text 1 10 20 30 2 total = 60 ``` > **Tip:** By convention, types that implement `IntoIterator for &T` also offer an inherent `fn iter(&self)` method (and `iter_mut` for `&mut`). That is why you write `v.iter()` on a `Vec`: it is shorthand for `(&v).into_iter()`. Provide an `iter()` method on your own type for the same ergonomic reason. The three borrow flavors map onto the same `iter()`/`iter_mut()`/`into_iter()` distinction you saw for `Vec` in [Vectors](/07-collections/00-vectors/#iteration-three-flavors-of-borrow). ### A borrowing iterator that yields references [Section titled “A borrowing iterator that yields references”](#a-borrowing-iterator-that-yields-references) The Fibonacci and `Countdown` examples yield *owned* values, so the iterator owns all its state. When you want to iterate over data that lives elsewhere and yield **references** into it, you create a separate iterator struct that *borrows* the source. This is the pattern the standard library uses for `slice::Iter`, and it requires a lifetime parameter: ```rust 1 struct Ring { 2 data: Vec<char>, 3 } 4 5 struct RingIter<'a> { 6 ring: &'a Ring, // borrows the Ring for lifetime 'a 7 pos: usize, 8 yielded: usize, 9 } 10 11 impl Ring { 12 fn iter_from(&self, start: usize) -> RingIter<'_> { 13 RingIter { ring: self, pos: start, yielded: 0 } 14 } 15 } 16 17 impl<'a> Iterator for RingIter<'a> { 18 type Item = &'a char; // we yield references, not owned chars 19 20 fn next(&mut self) -> Option<&'a char> { 21 if self.yielded == self.ring.data.len() { 22 return None; 23 } 24 let item = &self.ring.data[self.pos % self.ring.data.len()]; 25 self.pos += 1; 26 self.yielded += 1; 27 Some(item) 28 } 29 30 // Optional but recommended: lets `collect` pre-allocate exactly. 31 fn size_hint(&self) -> (usize, Option<usize>) { 32 let remaining = self.ring.data.len() - self.yielded; 33 (remaining, Some(remaining)) 34 } 35 } 36 37 fn main() { 38 let r = Ring { data: vec!['a', 'b', 'c', 'd'] }; 39 let it = r.iter_from(2); 40 println!("size_hint: {:?}", it.size_hint()); 41 42 let collected: String = r.iter_from(2).collect(); 43 println!("{collected}"); 44 45 // `r` is still usable: the iterator only borrowed it. 46 println!("ring still has {} cells", r.data.len()); 47 } ``` Verified output: ```text 1 size_hint: (4, Some(4)) 2 cdab 3 ring still has 4 cells ``` The lifetime `'a` ties each yielded `&char` to the `Ring` it came from, so the borrow checker guarantees the data outlives the iterator. JavaScript has no such concept: a generator can close over and yield anything, and the garbage collector keeps it alive. (Lifetimes are introduced in [Section 05 — Ownership](/05-ownership/).) ### `size_hint`: a free performance hint [Section titled “size\_hint: a free performance hint”](#size_hint-a-free-performance-hint) `size_hint` returns `(lower_bound, Option<upper_bound>)`. Consumers like `collect` use it to pre-allocate the right capacity. It is optional — the default returns `(0, None)` — but cheap to provide when you know the count, and it makes `collect`ing into a `Vec` allocate exactly once. It must never *over*-report the lower bound; under-reporting is always safe. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / JavaScript | Rust | | -------------------- | ----------------------------------------------- | ------------------------------------------ | | Define a producer | `function*` generator with `yield` | `impl Iterator` with `fn next` | | Make a type loopable | `[Symbol.iterator]()` method | `impl IntoIterator` | | ”Done” signal | `{ value, done: true }` | `next()` returns `None` | | Element type | `Generator<T>` (type param) | `type Item = T` (associated type) | | Pausing/resuming | Compiler rewrites to a state machine implicitly | You hold state in struct fields explicitly | | Built-in operations | A few (`.map` only on arrays, not generators) | 70+ adaptors, all from one `next` | | Yielding references | Not a distinct concept (GC keeps things alive) | Lifetime-checked `Item = &'a T` | | Infinite sequences | `while (true) { yield }` | `next` that never returns `None` | ### Generators are state machines you don’t have to write [Section titled “Generators are state machines you don’t have to write”](#generators-are-state-machines-you-dont-have-to-write) The biggest ergonomic gap: a JavaScript generator *pauses* at each `yield` and the engine remembers where to resume. Rust has no stable generator syntax for this; instead, **you** turn the logic into an explicit state machine by storing progress in struct fields and computing the next value from them in `next`. The Fibonacci example stores `a` and `b`; the `Countdown` stores `current`. What `yield` did implicitly, you do explicitly. The upside is that the state is plain data you can inspect, clone, and reason about. ### One `next`, the whole library [Section titled “One next, the whole library”](#one-next-the-whole-library) In TypeScript, generators do *not* have `.map`/`.filter`; those live only on `Array`, so you typically spread (`[...gen()]`) into an array first, losing laziness. In Rust, implementing `next` automatically gives your type every lazy adaptor. `fib().take_while(...).filter(...).sum()` never builds an intermediate array; it pulls values one at a time. See [Iterators](/07-collections/06-iterators/) for the adaptor catalog and [Iterator Consumers](/07-collections/07-iterator-consumers/) for the terminal operations. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting `type Item` [Section titled “Pitfall 1: Forgetting type Item”](#pitfall-1-forgetting-type-item) `Iterator` requires you to specify the associated type. Omitting it is a hard error, not an inference fallback. ```rust 1 struct Counter { 2 n: u32, 3 } 4 5 impl Iterator for Counter { 6 // type Item = u32; // omitted on purpose 7 fn next(&mut self) -> Option<u32> { 8 self.n += 1; 9 Some(self.n) 10 } 11 } 12 // does not compile (error[E0046]: missing `Item`) ``` Real compiler error: ```text 1 error[E0046]: not all trait items implemented, missing: `Item` 2 --> src/main.rs:6:1 3 | 4 6 | impl Iterator for Counter { 5 | ^^^^^^^^^^^^^^^^^^^^^^^^^ missing `Item` in implementation 6 | 7 = help: implement the missing item: `type Item = /* Type */;` ``` **Fix:** add `type Item = u32;` as the first line inside the `impl` block. ### Pitfall 2: Wrong `self` receiver on `next` [Section titled “Pitfall 2: Wrong self receiver on next”](#pitfall-2-wrong-self-receiver-on-next) The signature is `fn next(&mut self)`, not `fn next(self)` or `fn next(&self)`. Pulling a value mutates the cursor, so it must borrow mutably. ```rust 1 struct Counter { 2 n: u32, 3 } 4 5 impl Iterator for Counter { 6 type Item = u32; 7 fn next(self) -> Option<u32> { 8 // wrong receiver 9 Some(self.n) 10 } 11 } 12 // does not compile (error[E0053]: incompatible type for trait) ``` Real compiler error: ```text 1 error[E0053]: method `next` has an incompatible type for trait 2 --> src/main.rs:8:13 3 | 4 8 | fn next(self) -> Option<u32> { 5 | ^^^^ expected `&mut Counter`, found `Counter` 6 | 7 = note: expected signature `fn(&mut Counter) -> Option<_>` 8 found signature `fn(Counter) -> Option<_>` 9 help: change the self-receiver type to match the trait 10 | 11 8 | fn next(&mut self) -> Option<u32> { 12 | ++++ ``` **Fix:** write `fn next(&mut self) -> Option<Self::Item>` to match the trait exactly. ### Pitfall 3: An accidental infinite iterator [Section titled “Pitfall 3: An accidental infinite iterator”](#pitfall-3-an-accidental-infinite-iterator) If `next` never returns `None`, your iterator is infinite, which is fine *if* you always bound it with `take`, `take_while`, `find`, etc. But calling a consuming method like `collect`, `sum`, or `count` on an unbounded iterator loops forever and never terminates. ```rust 1 // `Counter` here never returns None. 2 let everything: Vec<u32> = counter.collect(); // hangs forever — no panic, no error ``` This is not a compile error and produces no message: the program simply never finishes (the same trap as `[...fibonacci()]` in JavaScript, which also hangs). **Fix:** bound infinite iterators before consuming them — `counter.take(100).collect()` — or make `next` return `None` at a terminal condition. Treat any custom `next` that never yields `None` as infinite by design and document it. ### Pitfall 4: Reaching for generators that Rust doesn’t have (yet) [Section titled “Pitfall 4: Reaching for generators that Rust doesn’t have (yet)”](#pitfall-4-reaching-for-generators-that-rust-doesnt-have-yet) TypeScript developers often look for a `yield` keyword. On the repository’s [pinned Rust 1.96.0 baseline](/00-introduction/05-version-policy/), stable Rust has **no generator syntax**: you cannot write `gen { yield x; }` in a normal function. You must encode the state by hand in a struct, as shown throughout this page. (An experimental `gen` block exists on nightly in that baseline; check the current tracking status before relying on it.) For the common case of “I just want to transform an existing collection,” you usually do *not* need a custom iterator at all. Chain adaptors on the collection’s built-in iterator instead (see [Iterators](/07-collections/06-iterators/)). *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Implement `Iterator` for a dedicated struct, then expose `iter()` [Section titled “1. Implement Iterator for a dedicated struct, then expose iter()”](#1-implement-iterator-for-a-dedicated-struct-then-expose-iter) For a collection, the idiomatic shape mirrors the standard library: a separate `XIter` struct implements `Iterator`, and your collection offers `iter(&self) -> XIter<'_>` plus `IntoIterator` impls for the three borrow forms. This gives callers `for x in &c`, `for x in c`, and `c.iter().map(...)` exactly as they expect from `Vec` and `HashMap`. ### 2. Return `impl Iterator<Item = T>` from functions [Section titled “2. Return impl Iterator\<Item = T> from functions”](#2-return-impl-iteratoritem--t-from-functions) When a function produces a sequence, return `impl Iterator<Item = T>` rather than a concrete type or a `Vec`. This keeps the result lazy and hides the (often unnameable) adaptor type: ```rust 1 // Returns a lazy iterator; the caller decides whether to collect, sum, etc. 2 fn evens_up_to(max: u32) -> impl Iterator<Item = u32> { 3 (0..max).filter(|n| n % 2 == 0) 4 } 5 6 fn main() { 7 let evens: Vec<u32> = evens_up_to(10).collect(); 8 println!("{evens:?}"); // [0, 2, 4, 6, 8] 9 } ``` Verified output: ```text 1 [0, 2, 4, 6, 8] ``` ### 3. Provide `size_hint` when the length is known [Section titled “3. Provide size\_hint when the length is known”](#3-provide-size_hint-when-the-length-is-known) A correct `size_hint` lets `collect` pre-allocate, avoiding reallocations. It costs a few lines and is a pure win for finite iterators. Never lie about the lower bound. ### 4. Consider the optional refinement traits [Section titled “4. Consider the optional refinement traits”](#4-consider-the-optional-refinement-traits) Once `Iterator` is implemented, you can opt into stronger guarantees that enable extra methods: * **`DoubleEndedIterator`** (add `next_back`) enables `.rev()` and `.next_back()`. * **`ExactSizeIterator`** (when `size_hint` is exact) enables `.len()`. * **`FusedIterator`** promises that once `None` is returned, it stays `None`. Implement them only when the semantics genuinely hold for your type. ### 5. Don’t write a custom iterator when an adaptor chain will do [Section titled “5. Don’t write a custom iterator when an adaptor chain will do”](#5-dont-write-a-custom-iterator-when-an-adaptor-chain-will-do) The most common mistake is over-engineering. If you only need to transform or filter an existing collection, chain `map`/`filter`/`flat_map` on its built-in iterator. Reserve a hand-written `impl Iterator` for genuinely new sequence *sources* (generators, parsers, pagination, infinite streams). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A paginating iterator over a (mocked) HTTP API. Each call to `next()` “fetches” the next page until the server reports no more pages: a stateful, lazy producer that is impossible to express as a simple adaptor chain. Because it is a real `Iterator`, the entire adaptor library applies to the result. ```rust 1 #[derive(Debug)] 2 struct User { 3 id: u32, 4 name: String, 5 } 6 7 /// Stands in for an HTTP client. Returns up to `page_size` users per page, 8 /// and reports whether more pages remain. 9 struct ApiClient { 10 total_users: u32, 11 } 12 13 impl ApiClient { 14 fn fetch_page(&self, page: u32, page_size: u32) -> (Vec<User>, bool) { 15 let start = page * page_size; 16 let end = (start + page_size).min(self.total_users); 17 let users = (start..end) 18 .map(|id| User { id, name: format!("user-{id}") }) 19 .collect(); 20 let has_more = end < self.total_users; 21 (users, has_more) 22 } 23 24 /// Hand out a lazy iterator over pages. 25 fn pages(&self, page_size: u32) -> Pages<'_> { 26 Pages { client: self, page: 0, page_size, done: false } 27 } 28 } 29 30 /// An iterator that yields one *page* (a `Vec<User>`) at a time. 31 struct Pages<'a> { 32 client: &'a ApiClient, 33 page: u32, 34 page_size: u32, 35 done: bool, 36 } 37 38 impl<'a> Iterator for Pages<'a> { 39 type Item = Vec<User>; 40 41 fn next(&mut self) -> Option<Vec<User>> { 42 if self.done { 43 return None; 44 } 45 let (users, has_more) = self.client.fetch_page(self.page, self.page_size); 46 self.page += 1; 47 if !has_more { 48 self.done = true; 49 } 50 if users.is_empty() { 51 return None; // an empty final page also terminates iteration 52 } 53 Some(users) 54 } 55 } 56 57 fn main() { 58 let client = ApiClient { total_users: 7 }; 59 60 // Flatten pages of users into a single lazy stream of users. 61 let labels: Vec<String> = client 62 .pages(3) 63 .flatten() // Vec<User> -> User 64 .map(|u| format!("#{}:{}", u.id, u.name)) 65 .collect(); 66 67 println!("fetched {} users across pages", labels.len()); 68 println!("{labels:?}"); 69 70 // Or process page-by-page, as you would when streaming into a database. 71 for (i, page) in client.pages(3).enumerate() { 72 println!("page {i}: {} users", page.len()); 73 } 74 } ``` Verified output: ```text 1 fetched 7 users across pages 2 ["#0:user-0", "#1:user-1", "#2:user-2", "#3:user-3", "#4:user-4", "#5:user-5", "#6:user-6"] 3 page 0: 3 users 4 page 1: 3 users 5 page 2: 1 users ``` The win is composability: `pages(3).flatten().map(...).collect()` reads as a clean pipeline, yet under the hood each page is fetched only when the consumer asks for it. Swapping the mock `fetch_page` for a real network call (returning a `Result`) would turn this into a production cursor-pagination helper; you would change `Item` to `Result<Vec<User>, ApiError>` and handle failures with the techniques in [Section 08 — Error Handling](/08-error-handling/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [`std::iter::Iterator`](https://doc.rust-lang.org/std/iter/trait.Iterator.html): the trait and all its provided methods * [`std::iter::IntoIterator`](https://doc.rust-lang.org/std/iter/trait.IntoIterator.html): what `for` loops call * [The Rust Book — Creating Our Own Iterators with the `Iterator` Trait](https://doc.rust-lang.org/book/ch13-02-iterators.html#creating-our-own-iterators-with-the-iterator-trait) * [`std::iter` module docs](https://doc.rust-lang.org/std/iter/index.html): the mental model for laziness and adaptors * [`DoubleEndedIterator`](https://doc.rust-lang.org/std/iter/trait.DoubleEndedIterator.html) and [`ExactSizeIterator`](https://doc.rust-lang.org/std/iter/trait.ExactSizeIterator.html): the optional refinement traits ### Related Topics in This Guide [Section titled “Related Topics in This Guide”](#related-topics-in-this-guide) * [Iterators](/07-collections/06-iterators/): the lazy adaptors (`map`, `filter`, `take`, `zip`) your `next` enables * [Iterator Consumers](/07-collections/07-iterator-consumers/): terminal operations (`collect`, `sum`, `fold`, `find`) that drive `next` * [Vectors](/07-collections/00-vectors/): the three borrow flavors of iteration (`iter`, `iter_mut`, `into_iter`) * [HashMaps](/07-collections/03-hashmaps/) and [BTreeMap / BTreeSet](/07-collections/05-btreemap-btreeset/): collections whose iterators you’ll often wrap or chain * [Collection Performance](/07-collections/09-collection-performance/): why `size_hint` and laziness matter for speed * [Section 06 — Associated Types](/06-data-structures/07-associated-types/): the `type Item` mechanism * [Section 05 — Ownership](/05-ownership/): lifetimes for reference-yielding iterators * [Section 02 — Basics: Types](/02-basics/01-types/): `Option`, `usize`, and the integer types used above *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A Stepping Range [Section titled “Exercise 1: A Stepping Range”](#exercise-1-a-stepping-range) **Difficulty:** Beginner **Objective:** Implement `Iterator` for a struct that produces numbers from a start up to (but not including) an end, advancing by a fixed step. **Instructions:** Define a `Stepper` struct holding `current`, `step`, and `end` (`i64`). Implement `Iterator` so that `stepper(0, 3, 16).collect::<Vec<_>>()` yields `[0, 3, 6, 9, 12, 15]`. Return `None` once `current >= end`. ```rust 1 struct Stepper { 2 current: i64, 3 step: i64, 4 end: i64, 5 } 6 7 impl Iterator for Stepper { 8 type Item = i64; 9 fn next(&mut self) -> Option<i64> { 10 /* ??? */ 11 todo!() 12 } 13 } 14 15 fn stepper(start: i64, step: i64, end: i64) -> Stepper { 16 Stepper { current: start, step, end } 17 } 18 19 fn main() { 20 let v: Vec<i64> = stepper(0, 3, 16).collect(); 21 println!("{v:?}"); 22 } ``` Solution ```rust 1 struct Stepper { 2 current: i64, 3 step: i64, 4 end: i64, 5 } 6 7 impl Iterator for Stepper { 8 type Item = i64; 9 fn next(&mut self) -> Option<i64> { 10 if self.current >= self.end { 11 return None; 12 } 13 let value = self.current; 14 self.current += self.step; 15 Some(value) 16 } 17 } 18 19 fn stepper(start: i64, step: i64, end: i64) -> Stepper { 20 Stepper { current: start, step, end } 21 } 22 23 fn main() { 24 let v: Vec<i64> = stepper(0, 3, 16).collect(); 25 println!("{v:?}"); 26 } ``` Output: ```text 1 [0, 3, 6, 9, 12, 15] ``` ### Exercise 2: Make a Wrapper Type Loopable [Section titled “Exercise 2: Make a Wrapper Type Loopable”](#exercise-2-make-a-wrapper-type-loopable) **Difficulty:** Intermediate **Objective:** Implement `IntoIterator` for both a value and a shared reference so a `Playlist` works in `for` loops by value and by `&`. **Instructions:** Given `struct Playlist { tracks: Vec<String> }`, implement `IntoIterator for Playlist` (yielding `String`) and `IntoIterator for &Playlist` (yielding `&String`). Then loop over `&playlist` to print each track, and consume `playlist` to build a `Vec<String>` of uppercased tracks. Delegate to `Vec`’s own iterators. ```rust 1 struct Playlist { 2 tracks: Vec<String>, 3 } 4 5 // TODO: impl IntoIterator for Playlist (by value) 6 // TODO: impl IntoIterator for &Playlist (by shared reference) 7 8 fn main() { 9 let pl = Playlist { 10 tracks: vec!["a".into(), "b".into(), "c".into()], 11 }; 12 // TODO: loop over &pl and print each track 13 // TODO: consume pl into a Vec<String> of uppercased tracks and print it 14 } ``` Solution ```rust 1 struct Playlist { 2 tracks: Vec<String>, 3 } 4 5 impl IntoIterator for Playlist { 6 type Item = String; 7 type IntoIter = std::vec::IntoIter<String>; 8 fn into_iter(self) -> Self::IntoIter { 9 self.tracks.into_iter() 10 } 11 } 12 13 impl<'a> IntoIterator for &'a Playlist { 14 type Item = &'a String; 15 type IntoIter = std::slice::Iter<'a, String>; 16 fn into_iter(self) -> Self::IntoIter { 17 self.tracks.iter() 18 } 19 } 20 21 fn main() { 22 let pl = Playlist { 23 tracks: vec!["a".into(), "b".into(), "c".into()], 24 }; 25 26 for t in &pl { 27 print!("{t} "); 28 } 29 println!(); 30 31 let upper: Vec<String> = pl.into_iter().map(|t| t.to_uppercase()).collect(); 32 println!("{upper:?}"); 33 } ``` Output: ```text 1 a b c 2 ["A", "B", "C"] ``` ### Exercise 3: A Double-Ended Iterator [Section titled “Exercise 3: A Double-Ended Iterator”](#exercise-3-a-double-ended-iterator) **Difficulty:** Advanced **Objective:** Implement both `Iterator` and `DoubleEndedIterator` so your type supports `.rev()`. **Instructions:** Define `struct Span { front: u32, back: u32 }` representing the half-open range `[front, back)`. Implement `Iterator` so `next` yields ascending values from the front, and `DoubleEndedIterator` so `next_back` yields descending values from the back. Verify that `Span { front: 0, back: 5 }.rev().collect::<Vec<_>>()` produces `[4, 3, 2, 1, 0]`. (Hint: `.rev()` is provided automatically once `DoubleEndedIterator` is implemented; it calls `next_back`.) ```rust 1 struct Span { 2 front: u32, 3 back: u32, 4 } 5 6 impl Iterator for Span { 7 type Item = u32; 8 fn next(&mut self) -> Option<u32> { 9 /* ??? */ 10 todo!() 11 } 12 } 13 14 // TODO: impl DoubleEndedIterator for Span 15 16 fn main() { 17 let s = Span { front: 0, back: 5 }; 18 let reversed: Vec<u32> = s.rev().collect(); 19 println!("{reversed:?}"); 20 } ``` Solution ```rust 1 struct Span { 2 front: u32, 3 back: u32, 4 } 5 6 impl Iterator for Span { 7 type Item = u32; 8 fn next(&mut self) -> Option<u32> { 9 if self.front >= self.back { 10 return None; 11 } 12 let v = self.front; 13 self.front += 1; 14 Some(v) 15 } 16 } 17 18 impl DoubleEndedIterator for Span { 19 fn next_back(&mut self) -> Option<u32> { 20 if self.front >= self.back { 21 return None; 22 } 23 self.back -= 1; 24 Some(self.back) 25 } 26 } 27 28 fn main() { 29 let s = Span { front: 0, back: 5 }; 30 let reversed: Vec<u32> = s.rev().collect(); 31 println!("{reversed:?}"); 32 33 // Forward still works too. 34 let forward: Vec<u32> = Span { front: 0, back: 5 }.collect(); 35 println!("{forward:?}"); 36 } ``` Output: ```text 1 [4, 3, 2, 1, 0] 2 [0, 1, 2, 3, 4] ``` # Collection Performance: Big-O, Choosing a Collection, and Capacity > Choose Rust collections by cost, not feel: Big-O for Vec, HashMap, and BTreeMap, with_capacity pre-allocation, and why iterators compile to tight loops. In JavaScript you reach for `Array`, `Object`, `Map`, and `Set` mostly by feel — the engine hides the cost model, and “it’s fast enough” usually holds. Rust gives you the same four shapes of collection (`Vec`, `HashMap`, `BTreeMap`, `HashSet`) but also hands you the cost model directly: you choose the data structure, you choose when memory is allocated, and you choose between a manual loop and a lazy iterator. This page is about making those choices deliberately. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Every standard collection has documented **Big-O** complexity, and picking the wrong one quietly turns an O(n) job into an O(n²) one. The three decisions that matter most for a TypeScript/JavaScript developer learning Rust are: (1) **which collection** to use: `Vec` for ordered lists, `HashMap` for keyed lookup, `BTreeMap` when you need sorted keys or range queries; (2) **whether to pre-allocate** with `with_capacity`/`reserve` to avoid repeated reallocations; and (3) **iterator vs hand-written loop**, which in Rust produce essentially identical machine code, so you can pick whichever reads better. Unlike a JavaScript engine, the Rust compiler will not silently switch representations behind your back, so the choice is yours and it sticks. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) A small analytics pass over web request logs. Notice how you reach for each built-in collection almost reflexively, without thinking about its cost. ```typescript 1 interface LogEntry { 2 timestamp: number; // unix seconds 3 ip: string; 4 path: string; 5 status: number; 6 } 7 8 function analyze(logs: LogEntry[]) { 9 // Object/Map as a frequency counter — keyed lookup, order irrelevant. 10 const hitsPerPath = new Map<string, number>(); 11 // Set for "have I seen this visitor?" — membership only. 12 const uniqueIps = new Set<string>(); 13 // Another Map, but here we secretly *want* sorted keys for a range query. 14 const perMinute = new Map<number, number>(); 15 16 for (const entry of logs) { 17 hitsPerPath.set(entry.path, (hitsPerPath.get(entry.path) ?? 0) + 1); 18 uniqueIps.add(entry.ip); 19 const bucket = Math.floor(entry.timestamp / 60); 20 perMinute.set(bucket, (perMinute.get(bucket) ?? 0) + 1); 21 } 22 23 // A "range query": hits in the first two minutes. With a plain Map you must 24 // iterate ALL entries and filter — there is no ordered range lookup. 25 let firstTwoMinutes = 0; 26 for (const [bucket, count] of perMinute) { 27 if (bucket < 2) firstTwoMinutes += count; 28 } 29 30 return { uniqueVisitors: uniqueIps.size, hitsPerPath, firstTwoMinutes }; 31 } ``` Two cost questions JavaScript never makes you answer: *Is `perMinute` actually sorted?* (A `Map` preserves **insertion** order, not key order, so the range scan above is O(n) and fragile.) And *how big should these structures be?* (You cannot pre-size a `Map` or `Set` at all.) *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same analysis, but each collection is chosen for its cost characteristics, and the one that needs ordered range queries uses `BTreeMap`. ```rust 1 use std::collections::{BTreeMap, HashMap, HashSet}; 2 3 #[derive(Debug)] 4 struct LogEntry { 5 timestamp: u64, 6 ip: String, 7 path: String, 8 status: u16, 9 } 10 11 struct Analytics { 12 // Count hits per path: keyed lookup, order irrelevant -> HashMap (avg O(1)). 13 hits_per_path: HashMap<String, u64>, 14 // Distinct visitors: membership only -> HashSet (avg O(1)). 15 unique_ips: HashSet<String>, 16 // Requests per 60s bucket: we want ORDER and RANGE queries -> BTreeMap (O(log n)). 17 per_minute: BTreeMap<u64, u64>, 18 errors: u64, 19 } 20 21 impl Analytics { 22 fn new(expected_paths: usize) -> Self { 23 Analytics { 24 // Pre-size the map we expect to fill the most. 25 hits_per_path: HashMap::with_capacity(expected_paths), 26 unique_ips: HashSet::new(), 27 per_minute: BTreeMap::new(), 28 errors: 0, 29 } 30 } 31 32 fn record(&mut self, entry: &LogEntry) { 33 *self.hits_per_path.entry(entry.path.clone()).or_insert(0) += 1; 34 self.unique_ips.insert(entry.ip.clone()); 35 let bucket = entry.timestamp / 60; 36 *self.per_minute.entry(bucket).or_insert(0) += 1; 37 if entry.status >= 500 { 38 self.errors += 1; 39 } 40 } 41 42 // Range query over the SORTED BTreeMap: total hits in [from, to) buckets. 43 fn hits_between(&self, from_bucket: u64, to_bucket: u64) -> u64 { 44 self.per_minute 45 .range(from_bucket..to_bucket) 46 .map(|(_, c)| *c) 47 .sum() 48 } 49 } 50 51 fn main() { 52 let logs = vec![ 53 LogEntry { timestamp: 0, ip: "1.1.1.1".into(), path: "/home".into(), status: 200 }, 54 LogEntry { timestamp: 30, ip: "2.2.2.2".into(), path: "/home".into(), status: 200 }, 55 LogEntry { timestamp: 61, ip: "1.1.1.1".into(), path: "/login".into(), status: 200 }, 56 LogEntry { timestamp: 75, ip: "3.3.3.3".into(), path: "/home".into(), status: 500 }, 57 LogEntry { timestamp: 130, ip: "1.1.1.1".into(), path: "/home".into(), status: 200 }, 58 ]; 59 60 let mut stats = Analytics::new(8); 61 for entry in &logs { 62 stats.record(entry); 63 } 64 65 println!("unique visitors: {}", stats.unique_ips.len()); 66 println!("5xx errors: {}", stats.errors); 67 // hits in the first two minutes — a true O(log n) range query, not a full scan. 68 println!("hits in first 2 minutes: {}", stats.hits_between(0, 2)); 69 } ``` Verified output: ```text 1 unique visitors: 3 2 5xx errors: 1 3 hits in first 2 minutes: 4 ``` > **Note:** `range(0..2)` walks only the matching slice of the tree, not the whole map. That single capability is the reason to pick `BTreeMap` over `HashMap` even though `HashMap` has faster individual lookups. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The cost table you should memorize [Section titled “The cost table you should memorize”](#the-cost-table-you-should-memorize) Here are the average-case complexities for the standard collections. “Amortized” means the cost averaged over many operations (a single one may occasionally be more expensive because of a reallocation). | Operation | `Vec<T>` | `HashMap<K,V>` / `HashSet<T>` | `BTreeMap<K,V>` / `BTreeSet<T>` | | ----------------------- | ---------------------- | ----------------------------- | ------------------------------- | | Insert at end / add | amortized **O(1)** | average **O(1)** | **O(log n)** | | Lookup by key | **O(n)** (scan) | average **O(1)** | **O(log n)** | | Random access by index | **O(1)** | n/a | n/a | | Membership test | **O(n)** (scan) | average **O(1)** | **O(log n)** | | Insert/remove in middle | **O(n)** (shift) | n/a | **O(log n)** | | Remove from end | **O(1)** | average **O(1)** | **O(log n)** | | Iterate all (n items) | **O(n)**, in order | **O(n)**, unordered | **O(n)**, **sorted** order | | Range / sorted query | **O(n)** (must scan) | **not supported** | **O(log n + k)** | | Min / max | **O(n)** unless sorted | **O(n)** | **O(log n)** (ends of tree) | > **Warning:** The “average O(1)” for `HashMap`/`HashSet` is *average*, not worst case. With adversarial keys a hash collision storm can degrade lookups, which is exactly why Rust’s default hasher (SipHash 1-3) is randomized and DoS-resistant; see [HashMaps](/07-collections/03-hashmaps/). For trusted internal keys you can swap in a faster hasher; for untrusted external input the default is the safe choice. Each operation here can be confirmed against [the standard library docs](https://doc.rust-lang.org/std/collections/index.html#performance), which state the complexity of every method. ### Choosing a collection: the decision flow [Section titled “Choosing a collection: the decision flow”](#choosing-a-collection-the-decision-flow) The standard-library documentation gives a concise rule of thumb, and it maps cleanly onto what you already do in TypeScript: * **You have a list and mostly append to the end or iterate it in order → `Vec<T>`.** This is your default, the way `Array` is your default in JavaScript. It is also the most cache-friendly because its elements are contiguous in memory. * **You look things up by key and don’t care about order → `HashMap<K,V>`** (or `HashSet<T>` for keys with no value). This is the `Map`/`Object`/`Set` of JavaScript, and individual lookups are the fastest of the keyed collections. * **You look things up by key AND need keys kept in sorted order, or you need range queries / min / max → `BTreeMap<K,V>`** (or `BTreeSet<T>`). JavaScript has no built-in equivalent; people fake it with a sorted array plus binary search. See [BTreeMap and BTreeSet](/07-collections/05-btreemap-btreeset/). A `Vec` of `(key, value)` pairs *can* act like a tiny map — and for a handful of entries it is actually faster than a `HashMap` because there is no hashing and the data is contiguous. But its lookup is a linear O(n) scan, so it collapses as the collection grows. The next section measures exactly that. ### Why “wrong collection” is the most expensive mistake [Section titled “Why “wrong collection” is the most expensive mistake”](#why-wrong-collection-is-the-most-expensive-mistake) Using a `Vec` and `contains()` as a stand-in for a `HashSet` is the single most common performance trap. Each `contains()` is an O(n) scan, and doing it inside a loop makes the whole thing O(n²). ```rust 1 use std::collections::HashSet; 2 3 fn main() { 4 let input = vec![3, 1, 2, 3, 1, 2, 4]; 5 6 // Accidentally O(n^2): contains() scans the whole Vec each time. 7 let mut seen: Vec<i32> = Vec::new(); 8 let mut unique_slow: Vec<i32> = Vec::new(); 9 for &x in &input { 10 if !seen.contains(&x) { // O(n) linear scan per element 11 seen.push(x); 12 unique_slow.push(x); 13 } 14 } 15 println!("slow unique = {unique_slow:?}"); 16 17 // O(n): HashSet membership is average O(1). 18 let mut set: HashSet<i32> = HashSet::new(); 19 let mut unique_fast: Vec<i32> = Vec::new(); 20 for &x in &input { 21 if set.insert(x) { // insert returns true if newly added 22 unique_fast.push(x); 23 } 24 } 25 println!("fast unique = {unique_fast:?}"); 26 } ``` Verified output: ```text 1 slow unique = [3, 1, 2, 4] 2 fast unique = [3, 1, 2, 4] ``` Both produce the same answer, but their cost diverges sharply with size. Timed on 20,000 mostly-unique values (release build): ```text 1 n = 20000 2 Vec::contains (O(n^2)) = 10.6615ms 3 HashSet (O(n)) = 542.333µs ``` > **Note:** Exact timings depend on your machine, and these were a single run; the *ratio* is what matters. At n = 20,000 the `HashSet` version was roughly 20× faster, and the gap widens as n grows because one curve is quadratic and the other linear. This is the same trap as using `Array.includes` inside a loop in JavaScript instead of a `Set`. ### Capacity: the second cost JavaScript hides [Section titled “Capacity: the second cost JavaScript hides”](#capacity-the-second-cost-javascript-hides) A `Vec` (and a `HashMap`/`HashSet`) has both a **length** (how many items it holds) and a **capacity** (how many it can hold before it must allocate a bigger buffer and copy everything over). When you `push` past capacity, the `Vec` reallocates, roughly **doubling** its buffer. Those reallocations are the “amortized” part of “amortized O(1)”. If you know roughly how many items you’ll add, tell the collection up front with `with_capacity`: ```rust 1 fn main() { 2 // Count reallocations: Vec::new() vs Vec::with_capacity(n). 3 let mut grown: Vec<u64> = Vec::new(); 4 let mut reallocs = 0; 5 let mut cap = grown.capacity(); 6 for i in 0..1_000u64 { 7 grown.push(i); 8 if grown.capacity() != cap { 9 reallocs += 1; 10 cap = grown.capacity(); 11 } 12 } 13 println!("Vec::new() -> {reallocs} reallocations to reach len {}", grown.len()); 14 15 let mut sized: Vec<u64> = Vec::with_capacity(1_000); 16 let mut reallocs2 = 0; 17 let mut cap2 = sized.capacity(); 18 for i in 0..1_000u64 { 19 sized.push(i); 20 if sized.capacity() != cap2 { 21 reallocs2 += 1; 22 cap2 = sized.capacity(); 23 } 24 } 25 println!("with_capacity() -> {reallocs2} reallocations to reach len {}", sized.len()); 26 } ``` Verified output: ```text 1 Vec::new() -> 9 reallocations to reach len 1000 2 with_capacity() -> 0 reallocations to reach len 1000 ``` Nine reallocations (each copying the entire buffer) versus zero. `HashMap` and `HashSet` work the same way: `HashMap::with_capacity(n)` and `reserve(n)` pre-size them. The deep-dive on `Vec` capacity and growth lives in [Vectors](/07-collections/00-vectors/); this page is about *when* the pre-allocation is worth it. ```rust 1 use std::collections::HashMap; 2 3 fn main() { 4 // HashMap also supports pre-allocation. 5 let mut counts: HashMap<&str, u32> = HashMap::with_capacity(16); 6 let words = ["a", "b", "a", "c", "a", "b"]; 7 for w in words { 8 *counts.entry(w).or_insert(0) += 1; 9 } 10 let mut pairs: Vec<(&str, u32)> = counts.into_iter().collect(); 11 pairs.sort(); // HashMap order is randomized; sort for stable display 12 println!("{pairs:?}"); 13 14 // reserve() grows capacity ahead of a known bulk insert. 15 let mut m: HashMap<u32, u32> = HashMap::new(); 16 m.reserve(1_000); 17 println!("capacity after reserve(1000): >= {}", m.capacity() >= 1000); 18 } ``` Verified output: ```text 1 [("a", 3), ("b", 2), ("c", 1)] 2 capacity after reserve(1000): >= true ``` When you build a collection from an iterator with `.collect()`, you usually get this for free: the iterator reports a size hint and `collect` pre-allocates accordingly, so an explicit `with_capacity` is rarely needed in that case. Reclaiming over-allocated memory is the job of `shrink_to_fit`: ```rust 1 fn main() { 2 let mut v: Vec<i32> = Vec::with_capacity(100); 3 v.extend([1, 2, 3]); 4 println!("before shrink: len={}, cap={}", v.len(), v.capacity()); 5 v.shrink_to_fit(); // hand the unused capacity back to the allocator 6 println!("after shrink: len={}, cap={}", v.len(), v.capacity()); 7 } ``` Verified output: ```text 1 before shrink: len=3, cap=100 2 after shrink: len=3, cap=3 ``` ### Iterator vs loop: a non-choice for performance [Section titled “Iterator vs loop: a non-choice for performance”](#iterator-vs-loop-a-non-choice-for-performance) In JavaScript, `arr.map().filter().reduce()` allocates one or more intermediate arrays and runs several passes, so it can be meaningfully slower than a single hand-written `for` loop on a hot path. **In Rust this trade-off essentially does not exist.** Iterator adaptors are lazy and get fused and inlined by the compiler into the same machine code a manual loop would produce. This is what “zero-cost abstraction” means. The iterator chain also drops per-element bounds checks that a manual `v[i]` would incur. ```rust 1 fn main() { 2 let data: Vec<u64> = (0..1_000_000).collect(); 3 4 // Manual index loop — every `data[i]` is bounds-checked. 5 let mut sum_loop: u64 = 0; 6 for i in 0..data.len() { 7 sum_loop += data[i]; 8 } 9 10 // Iterator chain — no manual indexing, no per-element bounds checks. 11 let sum_iter: u64 = data.iter().sum(); 12 13 // Filtered + mapped sum, the iterator way (still one pass, no intermediate Vec). 14 let even_doubled: u64 = data.iter().filter(|&&x| x % 2 == 0).map(|&x| x * 2).sum(); 15 16 println!("sum_loop = {sum_loop}"); 17 println!("sum_iter = {sum_iter}"); 18 println!("even_doubled = {even_doubled}"); 19 } ``` Verified output: ```text 1 sum_loop = 499999500000 2 sum_iter = 499999500000 3 even_doubled = 499999000000 ``` Because the iterator version compiles to equivalent (often better) code, the rule is: **write whichever is clearest, which is almost always the iterator.** The important difference from JavaScript is that `.filter().map().sum()` here makes **no intermediate `Vec`** — adaptors are lazy and only pull one element through the whole chain at a time. The mechanics of laziness are covered in [Iterators](/07-collections/06-iterators/) and [Iterator Consumers](/07-collections/07-iterator-consumers/). Pre-sizing applies to iterators too: `collect()` uses the size hint, as below. ```rust 1 fn main() { 2 // collect into a Vec sizes the allocation from the iterator's size hint. 3 let squares: Vec<u64> = (1..=5u64).map(|n| n * n).collect(); 4 println!("squares = {squares:?}"); 5 } ``` Verified output: ```text 1 squares = [1, 4, 9, 16, 25] ``` *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concern | TypeScript / JavaScript | Rust | | ------------------------------ | ------------------------------------------------- | -------------------------------------------------------------------- | | Cost model | Opaque; engine may reshape `Object`/`Array` | Explicit and documented per method | | Sorted-key map | None built in (sorted array + binary search) | `BTreeMap` / `BTreeSet`, O(log n) with range queries | | Pre-allocation | Not exposed for `Map`/`Set`; `Array(n)` is hole-y | `with_capacity(n)` / `reserve(n)` on all growable collections | | `Map`/`Object` iteration order | Insertion order (deterministic) | `HashMap` order is **randomized**; `BTreeMap` is **sorted** | | `map`/`filter` chains | Allocate intermediate arrays, multiple passes | Lazy, fused, zero intermediate allocations | | Loop vs higher-order method | Loop can be measurably faster on hot paths | Iterator ≈ loop; pick for readability | | Hash collisions / DoS | Engine-dependent | Default `HashMap` hasher is randomized + DoS-resistant | | Memory layout | Engine-managed, often pointer-chasing | `Vec` is contiguous (cache-friendly); maps/sets hash- or tree-backed | ### Why Rust exposes all of this [Section titled “Why Rust exposes all of this”](#why-rust-exposes-all-of-this) JavaScript optimizes for “don’t make the developer think.” Rust optimizes for “the developer is in control and nothing is hidden.” That means *you* pick the collection, *you* decide when memory is allocated, and the compiler guarantees the cost model won’t change underneath you. The upside is predictable, tunable performance with no surprise deopts; the cost is that choosing badly (a `Vec` scan where a `HashMap` belongs) is on you, not the runtime. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Using `Vec::contains` in a loop (accidental O(n²)) [Section titled “Pitfall 1: Using Vec::contains in a loop (accidental O(n²))”](#pitfall-1-using-veccontains-in-a-loop-accidental-on) This is the trap shown above, restated as the mistake itself. If you find yourself calling `.contains()`, `.iter().any()`, or `.iter().find()` inside a loop over the same data, you almost certainly want a `HashSet` or `HashMap`. The code compiles and is *correct*. It is just quadratic, and it will not show up until your inputs grow. There is no compiler error here; this is a design pitfall the type checker cannot catch for you. **Fix:** build a `HashSet`/`HashMap` once (O(n)) and do O(1) lookups against it, as in the `unique_fast` example above. ### Pitfall 2: Expecting `HashMap` to iterate in insertion or sorted order [Section titled “Pitfall 2: Expecting HashMap to iterate in insertion or sorted order”](#pitfall-2-expecting-hashmap-to-iterate-in-insertion-or-sorted-order) Coming from JavaScript, where `Map` and modern `Object` preserve insertion order, it is natural to assume iteration order is stable. A Rust `HashMap` iterates in an **unspecified, randomized** order that can differ between runs of the same program. ```rust 1 use std::collections::HashMap; 2 3 fn main() { 4 let mut m = HashMap::new(); 5 m.insert("a", 1); 6 m.insert("b", 2); 7 m.insert("c", 3); 8 // The order of this loop is NOT guaranteed and may change run-to-run. 9 for (k, v) in &m { 10 println!("{k} = {v}"); 11 } 12 } ``` **Fix:** if you need a deterministic order, either collect into a `Vec` and `sort()` it, or use a `BTreeMap` (always sorted by key). Relying on `HashMap` order is a latent bug, not a performance issue. ### Pitfall 3: `Vec::dedup` without sorting first [Section titled “Pitfall 3: Vec::dedup without sorting first”](#pitfall-3-vecdedup-without-sorting-first) `dedup` only removes **consecutive** duplicates; it is not a general “make unique” operation. ```rust 1 fn main() { 2 let mut v = vec![1, 2, 1, 1, 3]; 3 v.dedup(); 4 println!("{v:?}"); // the non-adjacent 1 survives 5 } ``` Verified output: ```text 1 [1, 2, 1, 3] ``` **Fix:** `v.sort(); v.dedup();` to remove all duplicates while keeping it O(n log n) and order-by-value, **or** use a `HashSet` if you don’t need sorting and want O(n). Choosing between them is a performance decision: sort+dedup keeps the result sorted; the `HashSet` route is faster but loses order. ### Pitfall 4: Pre-allocating the wrong thing (or everywhere) [Section titled “Pitfall 4: Pre-allocating the wrong thing (or everywhere)”](#pitfall-4-pre-allocating-the-wrong-thing-or-everywhere) `with_capacity` only helps when you would otherwise reallocate repeatedly while growing a single collection to a size you can estimate. Sprinkling it on every `Vec::new()` (including ones you build with `.collect()`, which already pre-sizes, or ones that stay tiny) adds noise without benefit and can even waste memory if your estimate is too high. **Fix:** pre-allocate when (a) you know the approximate final size and (b) you are growing element-by-element in a hot loop. Otherwise let `collect()` or the default growth strategy handle it, and reach for `shrink_to_fit` only if you over-allocated and the slack matters. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Default to `Vec`, escalate deliberately [Section titled “1. Default to Vec, escalate deliberately”](#1-default-to-vec-escalate-deliberately) Start with `Vec<T>`. Move to `HashMap`/`HashSet` the moment you do keyed lookups or membership tests more than occasionally. Move to `BTreeMap`/`BTreeSet` only when you genuinely need sorted iteration, range queries, or min/max — they pay O(log n) for that ordering. ### 2. Pre-allocate on hot, size-known paths [Section titled “2. Pre-allocate on hot, size-known paths”](#2-pre-allocate-on-hot-size-known-paths) When a loop pushes a predictable number of items, call `Vec::with_capacity(n)` / `HashMap::with_capacity(n)` first. It converts O(log n) reallocations (each an O(n) copy) into zero. For collections built by `.collect()`, trust the automatic size hint instead. ### 3. Prefer iterators; they are not slower [Section titled “3. Prefer iterators; they are not slower”](#3-prefer-iterators-they-are-not-slower) Write `.iter().filter(...).map(...).sum()` over manual index loops. It is clearer, it drops bounds checks, it allocates no intermediates, and it compiles to equivalent machine code. Reserve manual loops for cases the iterator genuinely cannot express cleanly. ### 4. Measure before micro-optimizing [Section titled “4. Measure before micro-optimizing”](#4-measure-before-micro-optimizing) For real performance work, use the [Criterion](https://docs.rs/criterion) benchmarking crate rather than ad-hoc `Instant::now()` timing; it handles warm-up, statistical noise, and outliers. The quick timings on this page are illustrative; Criterion is what you’d commit to a repo. See [Section 21 — Performance](/21-performance/) for the full treatment. ### 5. Pick the right hasher for the situation [Section titled “5. Pick the right hasher for the situation”](#5-pick-the-right-hasher-for-the-situation) The default `HashMap` hasher is DoS-resistant, which is right for untrusted keys (user input, network data). For trusted internal keys where speed dominates, a faster non-cryptographic hasher (e.g. the `fxhash` or `ahash` crate) can be a meaningful win. Default first; swap only after measuring. See [HashMaps](/07-collections/03-hashmaps/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) Deduplicating a large stream of IDs is a textbook “wrong collection” decision. Here both approaches are factored into functions and timed at scale so you can see the curve rather than take it on faith. ```rust 1 use std::collections::HashSet; 2 use std::time::Instant; 3 4 /// O(n^2): each `contains` linearly scans everything seen so far. 5 fn dedup_vec(input: &[u32]) -> Vec<u32> { 6 let mut seen: Vec<u32> = Vec::new(); 7 let mut out = Vec::new(); 8 for &x in input { 9 if !seen.contains(&x) { 10 seen.push(x); 11 out.push(x); 12 } 13 } 14 out 15 } 16 17 /// O(n): HashSet membership is average O(1); `insert` returns whether it was new. 18 fn dedup_set(input: &[u32]) -> Vec<u32> { 19 let mut seen: HashSet<u32> = HashSet::with_capacity(input.len()); 20 let mut out = Vec::with_capacity(input.len()); 21 for &x in input { 22 if seen.insert(x) { 23 out.push(x); 24 } 25 } 26 out 27 } 28 29 fn main() { 30 let input: Vec<u32> = (0..20_000).collect(); 31 32 let t = Instant::now(); 33 let a = dedup_vec(&input); 34 let vec_time = t.elapsed(); 35 36 let t = Instant::now(); 37 let b = dedup_set(&input); 38 let set_time = t.elapsed(); 39 40 assert_eq!(a.len(), b.len()); 41 println!("n = {}", input.len()); 42 println!("Vec::contains (O(n^2)) = {vec_time:?}"); 43 println!("HashSet (O(n)) = {set_time:?}"); 44 } ``` Verified output (single run, release build; your numbers will differ, the *ratio* is the point): ```text 1 n = 20000 2 Vec::contains (O(n^2)) = 10.6615ms 3 HashSet (O(n)) = 542.333µs ``` The `HashSet` version is both correct and roughly 20× faster here, and the gap grows with n. Note the deliberate `with_capacity(input.len())` calls in `dedup_set`: we know the upper bound on output size, so we pre-allocate and avoid all reallocation. This is the whole chapter in one example: right collection, right pre-allocation, idiomatic iteration. > **Tip:** If you don’t need to preserve first-seen order, the entire `dedup_set` body collapses to one line — `input.iter().copied().collect::<HashSet<_>>()` — and then `.into_iter().collect::<Vec<_>>()` if you want a `Vec` back. The explicit loop is shown here to make the cost visible. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [`std::collections` — module docs, including “Performance” and “Which collection?”](https://doc.rust-lang.org/std/collections/index.html): the canonical decision guide and complexity tables * [`Vec::with_capacity`](https://doc.rust-lang.org/std/vec/struct.Vec.html#method.with_capacity) and [`Vec::reserve`](https://doc.rust-lang.org/std/vec/struct.Vec.html#method.reserve) * [The Rust Performance Book](https://nnethercote.github.io/perf-book/): collections, allocations, and how to measure them * [Zero-cost abstractions (Rust Book, Iterators chapter)](https://doc.rust-lang.org/book/ch13-04-performance.html) — why iterators match hand-written loops ### Related Topics in This Guide [Section titled “Related Topics in This Guide”](#related-topics-in-this-guide) * [Vectors](/07-collections/00-vectors/): `Vec` capacity, growth, and `with_capacity` in depth * [HashMaps](/07-collections/03-hashmaps/): the entry API, key/value ownership, and the default hasher * [HashSets](/07-collections/04-hashsets/): membership and set algebra at O(1) * [BTreeMap and BTreeSet](/07-collections/05-btreemap-btreeset/): when sorted keys and range queries earn their O(log n) * [Iterators](/07-collections/06-iterators/) and [Iterator Consumers](/07-collections/07-iterator-consumers/) — lazy evaluation and why chains don’t allocate * [Section 05 — Ownership](/05-ownership/) — why moving a collection is O(1) but cloning is O(n) * [Section 21 — Performance](/21-performance/) — Criterion benchmarking and profiling *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Pick the Right Counter [Section titled “Exercise 1: Pick the Right Counter”](#exercise-1-pick-the-right-counter) **Difficulty:** Beginner **Objective:** Choose the correct collection for keyed counting and pre-size it. **Instructions:** Write `word_frequencies(text: &str) -> HashMap<String, u32>` that counts case-insensitive word frequencies (split on whitespace). Use the entry API so you never look a key up twice, and pre-size the map. Print the pairs sorted for a stable result. ```rust 1 use std::collections::HashMap; 2 3 fn word_frequencies(text: &str) -> HashMap<String, u32> { 4 // TODO: pre-size the map, then count each lowercased word with the entry API 5 todo!() 6 } 7 8 fn main() { 9 let freq = word_frequencies("the cat the dog the bird"); 10 let mut pairs: Vec<(&String, &u32)> = freq.iter().collect(); 11 pairs.sort(); 12 println!("{pairs:?}"); 13 } ``` Solution ```rust 1 use std::collections::HashMap; 2 3 fn word_frequencies(text: &str) -> HashMap<String, u32> { 4 let mut freq: HashMap<String, u32> = HashMap::with_capacity(text.len() / 5); 5 for word in text.split_whitespace() { 6 *freq.entry(word.to_lowercase()).or_insert(0) += 1; 7 } 8 freq 9 } 10 11 fn main() { 12 let freq = word_frequencies("the cat the dog the bird"); 13 let mut pairs: Vec<(&String, &u32)> = freq.iter().collect(); 14 pairs.sort(); 15 println!("{pairs:?}"); 16 } ``` Output: ```text 1 [("bird", 1), ("cat", 1), ("dog", 1), ("the", 3)] ``` The `entry(...).or_insert(0)` pattern does a single hash lookup that both finds-or-creates the slot; `*... += 1` mutates it in place. `with_capacity(text.len() / 5)` is a rough guess at the word count to avoid reallocations. ### Exercise 2: Eliminate the Reallocations [Section titled “Exercise 2: Eliminate the Reallocations”](#exercise-2-eliminate-the-reallocations) **Difficulty:** Intermediate **Objective:** Pre-allocate a `Vec` so that building it triggers zero reallocations. **Instructions:** Write `build_ids(n: usize) -> Vec<u64>` that returns the squares `0, 1, 4, 9, ...` for `0..n`. Build it with a loop (not `.collect()`) but pre-allocate so the capacity never grows mid-loop. Print the result and its capacity to prove it equals `n`. ```rust 1 fn build_ids(n: usize) -> Vec<u64> { 2 // TODO: pre-allocate, then push n squared values with no reallocation 3 todo!() 4 } 5 6 fn main() { 7 let ids = build_ids(5); 8 println!("{ids:?}, cap={}", ids.capacity()); 9 } ``` Solution ```rust 1 fn build_ids(n: usize) -> Vec<u64> { 2 let mut ids = Vec::with_capacity(n); // exact size known -> zero reallocations 3 for i in 0..n as u64 { 4 ids.push(i * i); 5 } 6 ids 7 } 8 9 fn main() { 10 let ids = build_ids(5); 11 println!("{ids:?}, cap={}", ids.capacity()); 12 } ``` Output: ```text 1 [0, 1, 4, 9, 16], cap=5 ``` Because the capacity (5) exactly matches the number of pushes, the buffer is allocated once and never copied. With `Vec::new()` this would have reallocated a few times as it grew through 4 → 8. ### Exercise 3: Range Query Needs the Right Map [Section titled “Exercise 3: Range Query Needs the Right Map”](#exercise-3-range-query-needs-the-right-map) **Difficulty:** Advanced **Objective:** Use a `BTreeMap` to answer a sorted range query that a `HashMap` cannot do efficiently. **Instructions:** Given a list of `(name, score)` pairs, build a `BTreeMap<u32, &str>` keyed by score. Then (a) print everyone whose score falls in the B band `[80, 90)` using a range query, and (b) print the top scorer by reading the last entry of the sorted map — no manual scan over all entries. ```rust 1 use std::collections::BTreeMap; 2 3 fn main() { 4 let scores = [("ana", 91), ("ben", 72), ("cy", 85), ("dee", 60), ("ed", 95)]; 5 // TODO: build a BTreeMap<u32, &str> keyed by score 6 // TODO: print the B band [80, 90) via a range query 7 // TODO: print the top scorer using the sorted order (no full scan) 8 } ``` Solution ```rust 1 use std::collections::BTreeMap; 2 3 fn main() { 4 let scores = [("ana", 91), ("ben", 72), ("cy", 85), ("dee", 60), ("ed", 95)]; 5 6 let mut by_score: BTreeMap<u32, &str> = BTreeMap::new(); 7 for (name, score) in scores { 8 by_score.insert(score, name); 9 } 10 11 // Range query: the B band, scores in [80, 90). O(log n + k), not a full scan. 12 let b_band: Vec<&str> = by_score.range(80..90).map(|(_, &name)| name).collect(); 13 println!("B band (80..90): {b_band:?}"); 14 15 // Top scorer is simply the last (highest-key) entry of the sorted map. 16 if let Some((score, name)) = by_score.iter().next_back() { 17 println!("top: {name} with {score}"); 18 } 19 } ``` Output: ```text 1 B band (80..90): ["cy"] 2 top: ed with 95 ``` `range(80..90)` walks only the matching slice of the tree, and `iter().next_back()` reads the maximum key in O(log n) — both are impossible to do efficiently on a `HashMap`, which has no order at all. (If two students could share a score you’d key by a tuple or store a `Vec` of names per score; here scores are unique.) # Rust Error Handling vs try/catch > No exceptions and no null in Rust: a tour mapping TypeScript throw/try/catch to Result, null/undefined to Option, and the ? operator that propagates failures. In TypeScript you signal failure by `throw`ing and recover with `try`/`catch`, and you represent “nothing” with `null`/`undefined`. Rust has **no exceptions and no `null`**: a fallible function returns a **`Result<T, E>`**, an optional value is an **`Option<T>`**, and the **`?` operator** propagates failures upward in one character. This section maps every TypeScript error-handling habit onto its idiomatic Rust counterpart, then goes deeper into panics, custom error types, the `std::error::Error` trait, and the two crates that make real-world error handling ergonomic: **`anyhow`** for applications and **`thiserror`** for libraries (current 1.x/2.x APIs, compile-verified). *** ## What You’ll Learn [Section titled “What You’ll Learn”](#what-youll-learn) * Why Rust replaces `throw`/`try`/`catch` with the **`Result<T, E>`** return value and `null`/`undefined` with **`Option<T>`**. Failure and absence become part of the type; extracting the success value requires an explicit choice, while discarding the whole `Result` emits an `unused_must_use` warning by default * How to choose between `Result` and `Option`, and how to extract their inner values with `match`, `if let`, `let ... else`, and combinators (`map`, `unwrap_or_else`, `ok_or_else`) * How the **`?` operator** propagates an `Err`/`None` to the caller, and how its built-in **`From`-based conversion** lets one function unify several underlying error types * The difference between a **recoverable** error (a `Result`) and an **unrecoverable** one (a `panic!`), how unwinding differs from aborting, and when reaching for `panic!` is actually the right call * When `unwrap`/`expect` are acceptable (**tests, prototypes, provable invariants**) and when they reintroduce exactly the runtime crashes `Result` was meant to prevent, plus how to write a good `expect` message * How to design **custom error types** as enums or structs, and implement **`Display`** and **`std::error::Error`** so they behave like first-class errors * What the **`Error` trait** requires (`Display` + `Debug`), how the **`source()`** cause chain works, and how **`Box<dyn Error>`** type-erases any error behind one return type * How to use **`anyhow` 1.x** (`Context`, `anyhow!`, `bail!`) in applications and **`thiserror` 2.x** (`#[derive(Error)]`, `#[from]`, `#[error("...")]`) in libraries: the current, idiomatic APIs * How to handle **multiple error types** in one function: by erasing to `Box<dyn Error>` or aggregating into an enum with `#[from]` conversions * The **design decisions** that tie it all together: libraries vs. applications, error granularity, message quality, and where recoverable handling ends and a programmer bug begins *** ## Topics [Section titled “Topics”](#topics) | Topic | Description | | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Result and Option](/08-error-handling/00-result-option/) | `try`/`catch` & `throw` → `Result<T, E>` and `null`/`undefined` → `Option<T>`: the difference between them and how to match on each. | | [The `?` Operator](/08-error-handling/01-question-mark/) | The `?` operator for propagation, `From`-based error conversion, and using `?` in a function (or `main`) that returns `Result`/`Option`. | | [Panicking](/08-error-handling/02-panic/) | `throw` → `panic!`: unwinding vs. aborting, when panics are appropriate (unrecoverable failures and bugs), and `panic!` vs. `Result`. | | [`unwrap` and `expect`](/08-error-handling/03-unwrap-expect/) | `unwrap`/`expect` and when they are acceptable (tests, prototypes, provable invariants), plus how to write a useful `expect` message. | | [Custom Error Types](/08-error-handling/04-custom-errors/) | Defining custom error types as enums or structs and implementing the `Display` and `Error` traits by hand. | | [The `Error` Trait](/08-error-handling/05-error-trait/) | `std::error::Error`: the `Display` + `Debug` requirements, the `source()` cause chain, and `Box<dyn Error>`. | | [`anyhow` & `thiserror`](/08-error-handling/06-anyhow-thiserror/) | `anyhow` 1.x for applications (`Context`, `anyhow!`) and `thiserror` 2.x for libraries (`#[derive(Error)]`, `#[from]`) — current APIs, compile-verified. | | [Handling Multiple Error Types](/08-error-handling/07-multiple-errors/) | Combining several error types in one function: `Box<dyn Error>`, enum aggregation, and `#[from]` conversions. | | [Error-Handling Best Practices](/08-error-handling/08-best-practices/) | Error design: libraries vs. applications, when to use which tool, granularity, message quality, and recoverable vs. unrecoverable. | *** ## Learning Objectives [Section titled “Learning Objectives”](#learning-objectives) By the end of this section, you will be able to: * Translate a TypeScript function that `throw`s into one that returns `Result<T, E>`, and a `User | undefined` return into `Option<T>`, then handle both with `match`, `if let`, `let ... else`, or combinators * Decide between `Result` and `Option` for a given failure, and between a `String` error, a custom enum, `Box<dyn Error>`, and `anyhow::Error` for the `E` * Use the `?` operator to write straight-line happy-path code, and add the `From` impls (by hand or via `#[from]`) that let `?` convert error types automatically * Explain why a `panic!` is not a TypeScript `throw`, and reserve panics for unrecoverable bugs while returning `Result` for anything a caller could handle * Justify each `unwrap`/`expect` in your code, replacing the rest with `?`, `match`, or the `unwrap_or_*` family, and turn on Clippy’s `unwrap_used`/`expect_used` lints where appropriate * Define a custom error type, implement `Display` and `std::error::Error` (including `source()`), and box it behind `Box<dyn Error>` when type erasure is the right trade-off * Pick `thiserror` for a library’s precise, matchable error enum and `anyhow` for an application’s “propagate-and-report” flow, and add `.context(...)` to make failures diagnosable *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * [Section 06: Data Structures](/06-data-structures/) — `Result` and `Option` are ordinary **enums**, and you handle them with **pattern matching** (`match`, `if let`, `let ... else`). Be comfortable with [enums](/06-data-structures/02-enums/), [`Option<T>`](/06-data-structures/03-option-enum/), and [`impl` blocks](/06-data-structures/05-impl-blocks/) before starting here. * [Section 05: Ownership](/05-ownership/): error values are owned and moved like any other data; `?` returns (and therefore moves) an error out of a function, and `Box<dyn Error>` is a heap-owned trait object. * [Section 02: Basics](/02-basics/): concrete types, `#[derive(Debug)]`, and `{:?}`/`{}` formatting (`Display` vs `Debug`) show up on every page. * Helpful but not required: [Section 04: Control Flow](/04-control-flow/) for `match` and early `return`. A few topics preview [Section 09: Generics and Traits](/09-generics-traits/) — the `<T, E>` and the `From`/`Error` traits behind `Result` and `?` — but each page explains what it needs as it goes. *** ## Estimated Time [Section titled “Estimated Time”](#estimated-time) * **Reading:** 4-5 hours * **Hands-on Practice:** 3-4 hours * **Exercises:** 3 hours * **Total:** 10-12 hours > **Tip:** Read the topics in order. Start with the *mechanics* — `result-option` → `question-mark` — because everything else builds on `Result`, `Option`, and `?`. Then learn the *failure modes* (`panic` → `unwrap-expect`), then how to *design error types* (`custom-errors` → `error-trait` → `anyhow-thiserror` → `multiple-errors`), and finish with `best-practices` to tie the choices together. The single biggest mental shift for a TypeScript developer is that **failure is a value, not a jump**: a thrown exception unwinds the stack invisibly, whereas a Rust `Result` is returned normally and the `?` operator makes each propagation point explicit in the source. *** ## Frequently asked questions [Section titled “Frequently asked questions”](#frequently-asked-questions) ### What is the Rust equivalent of `try`/`catch`? [Section titled “What is the Rust equivalent of try/catch?”](#what-is-the-rust-equivalent-of-trycatch) There is none, because there are no exceptions. A fallible function returns `Result<T, E>`, and `match` or the `?` operator handles or propagates the error as an ordinary value. See [Result and Option](/08-error-handling/00-result-option/). ### What does the `?` operator do? [Section titled “What does the ? operator do?”](#what-does-the--operator-do) On a `Result` or `Option`, `?` unwraps the value on success or returns early with the error on failure, in one character. It replaces repetitive `if (err) return err` plumbing and the `try`/`catch` dance. See [The `?` Operator](/08-error-handling/01-question-mark/). ### When should I use `unwrap()` or `panic!`? [Section titled “When should I use unwrap() or panic!?”](#when-should-i-use-unwrap-or-panic) Only when failure is a genuine bug, or in prototypes and tests, or after you have proven the value is present. In real code, propagate with `?` or handle with `match`; an unexpected `unwrap()` on `None`/`Err` aborts the program. See [unwrap and expect](/08-error-handling/03-unwrap-expect/). *** **Next:** [Section 09: Generics and Traits →](/09-generics-traits/) — the `<T, E>` type parameters and the `From`/`Error` traits that power `Result` and the `?` operator, generalized into Rust’s full generics-and-traits system. # Result and Option: Replacing try/catch and null > Rust has no exceptions or null: a fallible function returns Result<T, E> and a maybe-empty one returns Option<T>, keeping failure and absence visible in the type. Rust has no exceptions and no `null`. Instead, a function that can fail returns a **`Result<T, E>`** value, and a function that might have nothing to return uses **`Option<T>`**. Both are ordinary enums, so the possibility of failure or absence is written into the type. To obtain the inner value, you must match, propagate, choose a fallback, or deliberately panic. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In TypeScript/JavaScript, failure travels through a side channel: a function `throw`s and some `catch` far away (or none at all) handles it, and “missing” is represented by `null` or `undefined`. Rust folds both into the return value: * **`Result<T, E>`**: the operation either succeeded with a `T` (`Ok(T)`) or failed with an error `E` (`Err(E)`). This is the replacement for `throw`/`try`/`catch`. * **`Option<T>`**: there is either a value `Some(T)` or nothing `None`. This is the replacement for `null`/`undefined`. Because these are return values, not control-flow jumps, **the type signature tells you a function can fail**. Discarding an entire `Result` is still possible, but its `#[must_use]` annotation emits an `unused_must_use` warning by default; many projects promote that warning to an error in CI. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // Failure is signaled by throwing; "not found" is signaled by undefined/null. 2 interface User { 3 id: number; 4 name: string; 5 } 6 7 function parsePort(input: string): number { 8 const port = Number(input); 9 if (!Number.isInteger(port) || port < 0 || port > 65535) { 10 throw new Error(`'${input}' is not a valid port number`); 11 } 12 return port; 13 } 14 15 function findUser(users: User[], id: number): User | undefined { 16 return users.find((u) => u.id === id); 17 } 18 19 // The caller must REMEMBER to wrap calls in try/catch... 20 try { 21 const port = parsePort("8080"); 22 console.log(`Listening on port ${port}`); 23 } catch (err) { 24 // `err` is `unknown` in modern TypeScript — you must narrow it yourself. 25 console.error("Configuration error:", (err as Error).message); 26 } 27 28 // ...and must REMEMBER that findUser can return undefined. 29 const user = findUser([{ id: 1, name: "Ada" }], 99); 30 console.log(user.name); // TypeError at runtime: Cannot read properties of undefined ``` **The problem:** nothing forces the caller to handle the `throw`, and nothing forces a check for `undefined`. Both mistakes compile and ship; they explode at runtime. (In strict TypeScript, `user.name` above is flagged because the return type is `User | undefined`, but only if strict null checks are on, and a thrown exception is still invisible in the type.) *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 fn parse_port(input: &str) -> Result<u16, String> { 2 match input.parse::<u16>() { 3 Ok(port) => Ok(port), 4 Err(_) => Err(format!("'{input}' is not a valid port number")), 5 } 6 } 7 8 #[derive(Debug, Clone)] 9 struct User { 10 id: u32, 11 name: String, 12 } 13 14 fn find_user(users: &[User], id: u32) -> Option<&User> { 15 for user in users { 16 if user.id == id { 17 return Some(user); 18 } 19 } 20 None 21 } 22 23 fn main() { 24 // The compiler will NOT let you use the inner value without addressing failure. 25 match parse_port("8080") { 26 Ok(port) => println!("Listening on port {port}"), 27 Err(message) => println!("Configuration error: {message}"), 28 } 29 30 let users = vec![ 31 User { id: 1, name: "Ada".to_string() }, 32 User { id: 2, name: "Linus".to_string() }, 33 ]; 34 35 // `find_user` returns Option<&User>; you cannot reach `.name` without handling None. 36 match find_user(&users, 99) { 37 Some(user) => println!("Found user: {}", user.name), 38 None => println!("No user with that id"), 39 } 40 } ``` Running this prints: ```text 1 Listening on port 8080 2 No user with that id ``` > **Note:** The fallible signature is right there in `-> Result<u16, String>` and `-> Option<&User>`. A TypeScript signature like `(input: string) => number` hides the fact that the function can throw; the Rust signature cannot hide it. > **Tip:** The explicit `for` loop in `find_user` is written out so the `Some`/`None` flow is obvious. The idiomatic one-liner is `users.iter().find(|u| u.id == id)`, which returns the same `Option<&User>`; Clippy will in fact nudge you toward it. We use that combinator form in the helpers later in this file. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `Option` and `Result` are just enums [Section titled “Option and Result are just enums”](#option-and-result-are-just-enums) Neither type is built into the language as magic syntax. They are defined in the standard library, roughly like this: ```rust 1 // Already provided by std — shown here only to demystify them. 2 enum Option<T> { 3 Some(T), 4 None, 5 } 6 7 enum Result<T, E> { 8 Ok(T), 9 Err(E), 10 } ``` `T` and `E` are generic type parameters (covered in [Section 09: Generics and Traits](/09-generics-traits/)). The compiler monomorphizes them for each concrete type you use, so `Option<i32>` and `Result<u16, String>` are distinct, fully-checked types, unlike TypeScript generics, which are erased at runtime. Because they are enums, you construct and inspect them with the same tools as any other enum (see [Section 06: Enums](/06-data-structures/)): ```rust 1 fn main() { 2 let some_number: Option<i32> = Some(5); 3 let no_number: Option<i32> = None; 4 println!("{some_number:?} {no_number:?}"); // Some(5) None 5 6 let ok_value: Result<i32, String> = Ok(200); 7 let err_value: Result<i32, String> = Err("boom".to_string()); 8 println!("{ok_value:?} {err_value:?}"); // Ok(200) Err("boom") 9 } ``` Real output: ```text 1 Some(5) None 2 Ok(200) Err("boom") ``` ### Why there is no `null` [Section titled “Why there is no null”](#why-there-is-no-null) In JavaScript, *any* reference might secretly be `null` or `undefined`, which is why “Cannot read properties of undefined” is the most common runtime error in the ecosystem. Rust has no `null`. If a value might be absent, its type is `Option<T>`, and `T` and `Option<T>` are different types. You literally cannot pass a “maybe-missing” value where a “definitely-present” one is required without first unwrapping it. Indexing past the end of a slice does not return `undefined`; `Vec::get` returns `None`: ```rust 1 fn main() { 2 let names = vec!["Ada", "Linus"]; 3 let third: Option<&&str> = names.get(2); // out of bounds -> None, never a panic 4 println!("{third:?}"); // None 5 } ``` ```text 1 None ``` ### Matching to extract the value [Section titled “Matching to extract the value”](#matching-to-extract-the-value) The fundamental way to get at the inner value is `match`, which is exhaustive: you must cover every variant or the program does not compile. The two arms of a `Result` are `Ok` and `Err`; the two arms of an `Option` are `Some` and `None`: ```rust 1 fn parse_port(input: &str) -> Result<u16, String> { 2 input.parse::<u16>().map_err(|_| format!("'{input}' is not a valid port number")) 3 } 4 5 fn report_port(input: &str) { 6 match parse_port(input) { 7 Ok(port) => println!("Listening on port {port}"), 8 Err(message) => println!("Configuration error: {message}"), 9 } 10 } 11 12 fn main() { 13 report_port("8080"); 14 report_port("oops"); 15 } ``` `match` is where the safety comes from: forgetting the `Err` or `None` case is a compile error, not a latent bug. This is the headline difference from `try`/`catch`, where forgetting to catch is perfectly legal. ### Lighter-weight matching: `if let` and `let ... else` [Section titled “Lighter-weight matching: if let and let ... else”](#lighter-weight-matching-if-let-and-let--else) When you only care about one variant, `match` is verbose. `if let` matches a single pattern: ```rust 1 #[derive(Clone)] 2 struct User { 3 id: u32, 4 name: String, 5 } 6 7 fn find_user(users: &[User], id: u32) -> Option<&User> { 8 users.iter().find(|u| u.id == id) 9 } 10 11 fn main() { 12 let users = vec![User { id: 1, name: "Ada".to_string() }]; 13 14 if let Some(user) = find_user(&users, 1) { 15 println!("if let found: {}", user.name); 16 } 17 } ``` `let ... else` binds the value when the pattern matches, and runs a diverging block (one that `return`s, `break`s, or panics) when it does not. Perfect for “extract or bail”: ```rust 1 #[derive(Clone)] 2 struct User { 3 id: u32, 4 name: String, 5 } 6 7 fn find_user(users: &[User], id: u32) -> Option<&User> { 8 users.iter().find(|u| u.id == id) 9 } 10 11 fn main() { 12 let users = vec![User { id: 1, name: "Ada".to_string() }]; 13 14 let Some(found) = find_user(&users, 1) else { 15 println!("could not find user"); 16 return; 17 }; 18 // `found` is a plain &User from here on — no more Option in the way. 19 println!("let-else found: {}", found.name); 20 } ``` ### Combinators: handling without `match` [Section titled “Combinators: handling without match”](#combinators-handling-without-match) For everyday transformations you rarely write `match`. Both types carry a rich set of methods. The most useful ones: ```rust 1 fn parse_port(input: &str) -> Result<u16, String> { 2 input.parse::<u16>().map_err(|_| format!("'{input}' is not a valid port number")) 3 } 4 5 fn first_admin(names: &[&str]) -> Option<usize> { 6 names.iter().position(|&n| n == "admin") 7 } 8 9 fn main() { 10 let names = ["guest", "admin", "root"]; 11 12 // map: transform the inner value, leaving None/Err untouched. 13 let label = first_admin(&names) 14 .map(|index| format!("admin at position {index}")) 15 .unwrap_or_else(|| "no admin found".to_string()); 16 println!("{label}"); // admin at position 1 17 18 // map on Result transforms the Ok value. 19 let doubled: Result<u16, String> = parse_port("4000").map(|p| p * 2); 20 println!("{doubled:?}"); // Ok(8000) 21 22 // unwrap_or: supply a fallback value for the failure case. 23 let port = parse_port("oops").unwrap_or(3000); 24 println!("port fallback = {port}"); // 3000 25 } ``` These are conceptually close to TypeScript’s `?.` (optional chaining) and `??` (nullish coalescing): `opt.map(f)` resembles `obj?.f()`, and `opt.unwrap_or(d)` resembles `value ?? d`. But the analogy is not exact: `?.`/`??` are language operators that short-circuit on `null`/`undefined`, whereas `map`/`unwrap_or` are ordinary methods on a real enum, and they also work on the `Err` side of a `Result`, which has no JavaScript counterpart. ### Converting between `Result` and `Option` [Section titled “Converting between Result and Option”](#converting-between-result-and-option) The two types interconvert when you want to discard or supply error context: ```rust 1 #[derive(Debug, Clone)] 2 struct User { 3 id: u32, 4 name: String, 5 } 6 7 fn find_user(users: &[User], id: u32) -> Option<&User> { 8 users.iter().find(|u| u.id == id) 9 } 10 11 fn parse_port(input: &str) -> Result<u16, String> { 12 input.parse::<u16>().map_err(|_| format!("'{input}' is not a valid port number")) 13 } 14 15 fn main() { 16 let users = vec![User { id: 1, name: "Ada".to_string() }]; 17 18 // .ok() throws away the error and yields an Option. 19 let maybe: Option<u16> = parse_port("22").ok(); 20 println!("{maybe:?}"); // Some(22) 21 22 // .ok_or_else() attaches an error and yields a Result. 23 let as_result: Result<&User, String> = 24 find_user(&users, 1).ok_or_else(|| "user not found".to_string()); 25 println!("{:?}", as_result.map(|u| u.name.clone())); // Ok("Ada") 26 } ``` > **Tip:** Use `ok_or_else` (which takes a closure) rather than `ok_or` when building the error is non-trivial, so the error value is only constructed on the failure path. The same logic applies to `unwrap_or_else` vs `unwrap_or`. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript | Rust | | ----------------------- | -------------------------------------------- | ------------------------------------------------------------------------ | | Recoverable failure | `throw` + `try`/`catch` | return `Result<T, E>` | | Absent value | `null` / `undefined` | `Option<T>` (`Some`/`None`) | | Is failure in the type? | No: `throw` is invisible in the signature | Yes: `Result`/`Option` are in the return type | | Can you ignore it? | A thrown error is invisible in the signature | Discarding is explicit or warns; extracting `T` requires choosing a path | | Error value type | Anything (you can `throw 42` or a string) | A concrete `E` chosen by the function | | ”Catch all” handler | `catch (err: unknown)` | match the `Err`/`None` arm; no catch-all needed | | Cost | Stack unwinding when thrown | Just a returned enum value; no unwinding | ### `Result` vs `Option`: which one? [Section titled “Result vs Option: which one?”](#result-vs-option-which-one) This is the single most common question. The rule of thumb: * Use **`Option<T>`** when *absence is normal and carries no explanation*. “This key isn’t in the map.” “The list is empty.” “Index 5 of a 3-element slice.” There is nothing to report; the value simply isn’t there. `None` says all there is to say. * Use **`Result<T, E>`** when *failure has a reason worth communicating*. “The port string wasn’t a number.” “The file couldn’t be opened because permission was denied.” The `E` carries the *why*, which a caller may log, surface to a user, or branch on. A quick test: if you find yourself wanting to attach a message or an error code, you want `Result`. If the only sensible response to absence is “try something else” or “skip it,” `Option` is enough. > **Note:** `parse_port` returns `Result` because “not a valid port” is a reason worth reporting. `find_user` returns `Option` because “no user with that id” is just absence, though in a real API you might upgrade it to `Result` if the caller needs to distinguish “not found” from other failures. ### Failure is a value, not a jump [Section titled “Failure is a value, not a jump”](#failure-is-a-value-not-a-jump) A thrown JavaScript exception unwinds the stack until something catches it, skipping every line in between. A Rust `Result` is an ordinary value returned normally; control flow is completely linear and visible. This is why Rust error handling has essentially zero hidden cost and why you can store, collect, and transform errors like any other data. (Rust *does* have `panic!` for truly unrecoverable situations, and it can unwind — but that is a separate mechanism covered in [Panics](/08-error-handling/02-panic/), not the everyday error path.) *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Trying to use an `Option`/`Result` as if it were the inner value [Section titled “Pitfall 1: Trying to use an Option/Result as if it were the inner value”](#pitfall-1-trying-to-use-an-optionresult-as-if-it-were-the-inner-value) A TypeScript developer expects `findUser(...)` to give back a `User`. In Rust it gives back an `Option<&User>`, and you cannot use it directly: ```rust 1 fn find(v: &[i32], target: i32) -> Option<usize> { 2 v.iter().position(|&x| x == target) 3 } 4 fn main() { 5 let v = vec![10, 20, 30]; 6 let idx = find(&v, 20); // idx is Option<usize>, not usize 7 let element = v[idx]; // does not compile (error[E0277]) 8 println!("{element}"); 9 } ``` Real compiler error: ```text 1 error[E0277]: the type `[i32]` cannot be indexed by `Option<usize>` 2 --> src/bin/pitfall_a.rs:7:21 3 | 4 7 | let element = v[idx]; // does not compile (error[E0277]) 5 | ^^^ slice indices are of type `usize` or ranges of `usize` 6 | 7 = help: the trait `SliceIndex<[i32]>` is not implemented for `Option<usize>` 8 = note: required for `Vec<i32>` to implement `Index<Option<usize>>` ``` **Fix:** match, use `if let`, or use a combinator to get the `usize` out first. The compiler is reminding you that the index might not exist. ### Pitfall 2: Comparing an `Option` to a bare value [Section titled “Pitfall 2: Comparing an Option to a bare value”](#pitfall-2-comparing-an-option-to-a-bare-value) Coming from JavaScript, you might write `if (port === 80)`. In Rust, `port` is an `Option<u16>`, not a `u16`: ```rust 1 fn find_port(name: &str) -> Option<u16> { 2 if name == "http" { Some(80) } else { None } 3 } 4 fn main() { 5 let port = find_port("http"); 6 if port == 80 { // does not compile (error[E0308]) 7 println!("standard http"); 8 } 9 } ``` Real compiler error (note the helpful suggestion): ```text 1 error[E0308]: mismatched types 2 --> src/bin/pitfall_c.rs:6:16 3 | 4 6 | if port == 80 { // does not compile (error[E0308]) 5 | ---- ^^ expected `Option<u16>`, found integer 6 | | 7 | expected because this is `Option<u16>` 8 | 9 = note: expected enum `Option<u16>` 10 found type `{integer}` 11 help: try wrapping the expression in `Some` 12 | 13 6 | if port == Some(80) { // does not compile (error[E0308]) 14 | +++++ + ``` **Fix:** compare against `Some(80)`, or pattern-match with `if let Some(80) = port`. ### Pitfall 3: Ignoring a `Result` [Section titled “Pitfall 3: Ignoring a Result”](#pitfall-3-ignoring-a-result) In JavaScript you can call a throwing function and never wrap it in `try`/`catch`. In Rust, `Result` is marked `#[must_use]`, so discarding one triggers a warning: ```rust 1 fn parse_port(input: &str) -> Result<u16, String> { 2 input.parse::<u16>().map_err(|_| "bad port".to_string()) 3 } 4 fn main() { 5 parse_port("8080"); // warning: unused `Result` that must be used 6 println!("done"); 7 } ``` Real compiler warning: ```text 1 warning: unused `Result` that must be used 2 --> src/bin/pitfall_b.rs:5:5 3 | 4 5 | parse_port("8080"); // warning: unused `Result` that must be used 5 | ^^^^^^^^^^^^^^^^^^ 6 | 7 = note: this `Result` may be an `Err` variant, which should be handled 8 = note: `#[warn(unused_must_use)]` on by default 9 help: use `let _ = ...` to ignore the resulting value ``` **Fix:** handle the `Result`, propagate it with `?` (see [The `?` Operator](/08-error-handling/01-question-mark/)), or — if you genuinely mean to discard it — write `let _ = parse_port("8080");` to say so explicitly. ### Pitfall 4: A non-exhaustive `match` [Section titled “Pitfall 4: A non-exhaustive match”](#pitfall-4-a-non-exhaustive-match) `match` must cover every variant. Omitting the `Err` (or `None`) arm is a compile error, which is exactly the protection that `try`/`catch` lacks: ```rust 1 fn parse_port(input: &str) -> Result<u16, String> { 2 input.parse::<u16>().map_err(|_| "bad port".to_string()) 3 } 4 fn main() { 5 let result = parse_port("8080"); 6 match result { // does not compile (error[E0004]) 7 Ok(port) => println!("port {port}"), 8 // forgot the Err arm 9 } 10 } ``` Real compiler error (trimmed): ```text 1 error[E0004]: non-exhaustive patterns: `Err(_)` not covered 2 --> src/bin/pitfall_d.rs:6:11 3 | 4 6 | match result { 5 | ^^^^^^ pattern `Err(_)` not covered 6 ... 7 help: ensure that all possible cases are being handled by adding a match arm 8 with a wildcard pattern or an explicit pattern as shown ``` **Fix:** add the missing arm. Reach for a catch-all `_ => ...` only when you truly mean “everything else.” *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Prefer combinators and `?` over `match` for plumbing [Section titled “Prefer combinators and ? over match for plumbing”](#prefer-combinators-and--over-match-for-plumbing) A full `match` is the right tool when each variant needs genuinely different logic. For the common cases — transform the success value, supply a default, propagate the error upward — `map`, `unwrap_or_else`, `and_then`, and the `?` operator are shorter and clearer. Save `match` for branching decisions. ### Reserve `unwrap`/`expect` for provable invariants [Section titled “Reserve unwrap/expect for provable invariants”](#reserve-unwrapexpect-for-provable-invariants) `unwrap()` and `expect()` extract the inner value but **panic** on `None`/`Err`. They are fine in tests, quick prototypes, and cases where the failure is genuinely impossible, but in production logic they reintroduce exactly the kind of runtime crash that `Result` was meant to prevent. The dedicated topic [unwrap and expect](/08-error-handling/03-unwrap-expect/) covers when they are acceptable. ### Don’t `match` only to re-wrap — use `.map_err` [Section titled “Don’t match only to re-wrap — use .map\_err”](#dont-match-only-to-re-wrap--use-map_err) Beginners often write a `match` that returns `Ok(x)` in the `Ok` arm and a transformed error in the `Err` arm. That entire `match` is just `.map` (to change the `Ok` value) or `.map_err` (to change the `Err` value): ```rust 1 fn raw() -> Result<u16, std::num::ParseIntError> { "x".parse() } 2 3 // Verbose: 4 fn verbose() -> Result<u16, String> { 5 match raw() { 6 Ok(v) => Ok(v), 7 Err(_) => Err("bad number".to_string()), 8 } 9 } 10 11 // Idiomatic: 12 fn idiomatic() -> Result<u16, String> { 13 raw().map_err(|_| "bad number".to_string()) 14 } 15 16 fn main() { 17 println!("{:?}", verbose()); 18 println!("{:?}", idiomatic()); 19 } ``` ### Choose meaningful error types [Section titled “Choose meaningful error types”](#choose-meaningful-error-types) `Result<T, String>` is fine for examples and small programs, but real libraries define a dedicated error type so callers can match on specific cases. That is the subject of [Custom Errors](/08-error-handling/04-custom-errors/) and the [`thiserror`/`anyhow`](/08-error-handling/06-anyhow-thiserror/) topic. The key idea for *this* file: the moment you write `Result`, you have already made the failure visible and handleable. Refining `E` is the next step. ### Let the type encode optionality once [Section titled “Let the type encode optionality once”](#let-the-type-encode-optionality-once) If a struct field is genuinely optional, make it `Option<T>` in the struct and stop checking for absence everywhere else. This is the Rust counterpart to a `field?: T` in TypeScript, but enforced — you can never accidentally read it as if it were always present. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small configuration loader that parses `key = value` lines. It uses `Option` for “this line might not be a valid pair” and `Result` for “this whole config might be invalid, and here’s why.” Notice how `Option`’s `split_once` + `?`, `Result`’s `map_err` + `?`, and `unwrap_or` for defaults all combine. ```rust 1 #[derive(Debug)] 2 struct ServerConfig { 3 host: String, 4 port: u16, 5 max_connections: u32, 6 } 7 8 /// Parse "key=value" into a (key, value) pair, or None if malformed. 9 fn parse_pair(line: &str) -> Option<(&str, &str)> { 10 let (key, value) = line.split_once('=')?; // `?` on Option: bail with None 11 let key = key.trim(); 12 let value = value.trim(); 13 if key.is_empty() || value.is_empty() { 14 return None; 15 } 16 Some((key, value)) 17 } 18 19 /// Build a ServerConfig from raw lines. Returns the first error encountered. 20 fn load_config(lines: &[&str]) -> Result<ServerConfig, String> { 21 let mut host: Option<String> = None; 22 let mut port: Option<u16> = None; 23 let mut max_connections: Option<u32> = None; 24 25 for line in lines { 26 let line = line.trim(); 27 if line.is_empty() || line.starts_with('#') { 28 continue; // skip blanks and comments 29 } 30 31 // `let ... else`: extract the pair or report a malformed line. 32 let Some((key, value)) = parse_pair(line) else { 33 return Err(format!("malformed line: {line:?}")); 34 }; 35 36 match key { 37 "host" => host = Some(value.to_string()), 38 "port" => { 39 let parsed = value 40 .parse::<u16>() 41 .map_err(|_| format!("port must be 0-65535, got {value:?}"))?; 42 port = Some(parsed); 43 } 44 "max_connections" => { 45 let parsed = value 46 .parse::<u32>() 47 .map_err(|_| format!("max_connections must be a number, got {value:?}"))?; 48 max_connections = Some(parsed); 49 } 50 other => return Err(format!("unknown key: {other:?}")), 51 } 52 } 53 54 Ok(ServerConfig { 55 // host is required: turn None into an Err with `ok_or_else` + `?`. 56 host: host.ok_or_else(|| "missing required key: host".to_string())?, 57 // port and max_connections are optional: fall back to defaults. 58 port: port.unwrap_or(8080), 59 max_connections: max_connections.unwrap_or(256), 60 }) 61 } 62 63 fn main() { 64 let good = [ 65 "# production config", 66 "host = api.example.com", 67 "port = 443", 68 "", 69 "max_connections = 1000", 70 ]; 71 println!("{:?}", load_config(&good)); 72 73 let missing_host = ["port = 443"]; 74 println!("{:?}", load_config(&missing_host)); 75 76 let bad_port = ["host = localhost", "port = wat"]; 77 println!("{:?}", load_config(&bad_port)); 78 79 let malformed = ["host = localhost", "garbage"]; 80 println!("{:?}", load_config(&malformed)); 81 82 // Defaults apply when optional keys are absent. 83 let minimal = ["host = localhost"]; 84 println!("{:?}", load_config(&minimal)); 85 } ``` Real output: ```text 1 Ok(ServerConfig { host: "api.example.com", port: 443, max_connections: 1000 }) 2 Err("missing required key: host") 3 Err("port must be 0-65535, got \"wat\"") 4 Err("malformed line: \"garbage\"") 5 Ok(ServerConfig { host: "localhost", port: 8080, max_connections: 256 }) ``` Every failure mode — missing required key, unparseable number, malformed line — is a returned `Err` with a message, never a thrown exception, and the happy path supplies defaults through `Option`. The `?` operator doing the propagation here is the subject of the [next topic](/08-error-handling/01-question-mark/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Error Handling](https://doc.rust-lang.org/book/ch09-00-error-handling.html) * [`std::result::Result`](https://doc.rust-lang.org/std/result/enum.Result.html) (full list of combinators) * [`std::option::Option`](https://doc.rust-lang.org/std/option/enum.Option.html) * [Rust by Example — `Option`](https://doc.rust-lang.org/rust-by-example/std/option.html) and [`Result`](https://doc.rust-lang.org/rust-by-example/error/result.html) ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [The `?` Operator](/08-error-handling/01-question-mark/): propagating `Result`/`Option` upward without `match` * [Panics](/08-error-handling/02-panic/) — `panic!`, the closest thing to an unhandled exception, and when it is appropriate * [unwrap and expect](/08-error-handling/03-unwrap-expect/): extracting values when failure is impossible (and when it isn’t) * [Custom Errors](/08-error-handling/04-custom-errors/) and [`anyhow` / `thiserror`](/08-error-handling/06-anyhow-thiserror/) — designing real error types for the `E` in `Result<T, E>` * [Section 06: Data Structures](/06-data-structures/): enums and pattern matching, the machinery behind `Option`/`Result` * [Section 09: Generics and Traits](/09-generics-traits/) — the `<T>` and `<T, E>` that make these types reusable * [Section 02: Basics](/02-basics/): types and `match` fundamentals *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: From `null` to `Option` [Section titled “Exercise 1: From null to Option”](#exercise-1-from-null-to-option) **Difficulty:** Easy **Objective:** Replace a JavaScript-style “return `null` on bad input” function with an `Option`-returning Rust function. **Instructions:** Implement `safe_divide(a: f64, b: f64) -> Option<f64>` that returns `None` when `b` is `0.0` and `Some(a / b)` otherwise. Print the results of dividing `10.0 / 2.0` and `1.0 / 0.0`. ```rust 1 fn safe_divide(a: f64, b: f64) -> Option<f64> { 2 // TODO: return None when b is 0.0, otherwise Some(a / b) 3 /* ??? */ 4 } 5 6 fn main() { 7 println!("{:?}", safe_divide(10.0, 2.0)); // expected Some(5.0) 8 println!("{:?}", safe_divide(1.0, 0.0)); // expected None 9 } ``` Solution ```rust 1 fn safe_divide(a: f64, b: f64) -> Option<f64> { 2 if b == 0.0 { 3 None 4 } else { 5 Some(a / b) 6 } 7 } 8 9 fn main() { 10 println!("{:?}", safe_divide(10.0, 2.0)); // Some(5.0) 11 println!("{:?}", safe_divide(1.0, 0.0)); // None 12 } ``` Output: ```text 1 Some(5.0) 2 None ``` ### Exercise 2: Turning `throw` into `Result` with a real error type [Section titled “Exercise 2: Turning throw into Result with a real error type”](#exercise-2-turning-throw-into-result-with-a-real-error-type) **Difficulty:** Medium **Objective:** Replace a throwing checkout function with one that returns `Result<T, E>` where `E` is a descriptive enum. **Instructions:** Define an enum `CheckoutError` with variants `EmptyCart` and `InsufficientStock { item, requested, available }`. Implement `checkout(cart: &[CartItem], stock: u32) -> Result<u32, CheckoutError>` that returns `Err(EmptyCart)` for an empty cart, `Err(InsufficientStock { .. })` if any item’s quantity exceeds `stock`, and otherwise `Ok` of the total quantity. Print results for a valid cart, an empty cart, and an over-stock cart. ```rust 1 #[derive(Debug, PartialEq)] 2 enum CheckoutError { 3 EmptyCart, 4 InsufficientStock { item: String, requested: u32, available: u32 }, 5 } 6 7 struct CartItem { 8 name: String, 9 quantity: u32, 10 } 11 12 fn checkout(cart: &[CartItem], stock: u32) -> Result<u32, CheckoutError> { 13 // TODO 14 /* ??? */ 15 } 16 17 fn main() { 18 let cart = vec![CartItem { name: "widget".to_string(), quantity: 3 }]; 19 println!("{:?}", checkout(&cart, 10)); 20 println!("{:?}", checkout(&[], 10)); 21 } ``` Solution ```rust 1 #[derive(Debug, PartialEq)] 2 enum CheckoutError { 3 EmptyCart, 4 InsufficientStock { item: String, requested: u32, available: u32 }, 5 } 6 7 struct CartItem { 8 name: String, 9 quantity: u32, 10 } 11 12 fn checkout(cart: &[CartItem], stock: u32) -> Result<u32, CheckoutError> { 13 if cart.is_empty() { 14 return Err(CheckoutError::EmptyCart); 15 } 16 let mut total = 0; 17 for item in cart { 18 if item.quantity > stock { 19 return Err(CheckoutError::InsufficientStock { 20 item: item.name.clone(), 21 requested: item.quantity, 22 available: stock, 23 }); 24 } 25 total += item.quantity; 26 } 27 Ok(total) 28 } 29 30 fn main() { 31 let cart = vec![CartItem { name: "widget".to_string(), quantity: 3 }]; 32 println!("{:?}", checkout(&cart, 10)); // Ok(3) 33 println!("{:?}", checkout(&[], 10)); // Err(EmptyCart) 34 35 let big = vec![CartItem { name: "widget".to_string(), quantity: 99 }]; 36 println!("{:?}", checkout(&big, 10)); // Err(InsufficientStock { .. }) 37 } ``` Output: ```text 1 Ok(3) 2 Err(EmptyCart) 3 Err(InsufficientStock { item: "widget", requested: 99, available: 10 }) ``` > Defining `E` as an enum (rather than a `String`) lets callers `match` on `CheckoutError::EmptyCart` vs `InsufficientStock`. This is the bridge to [Custom Errors](/08-error-handling/04-custom-errors/). ### Exercise 3: Chaining `Option` and `Result` [Section titled “Exercise 3: Chaining Option and Result”](#exercise-3-chaining-option-and-result) **Difficulty:** Medium-Hard **Objective:** Build a lookup-then-parse pipeline using `ok_or_else`, `map_err`, and the `?` operator together. **Instructions:** Given `env_lookup(key) -> Option<&'static str>`, implement `config_u16(key: &str) -> Result<u16, String>` that: returns `Err("{key} is not set")` if the key is absent; otherwise parses the value as `u16`, returning `Err("{key} is not a valid number")` on a parse failure; otherwise returns `Ok(value)`. Do it without an explicit `match` — use `ok_or_else`, `?`, and `map_err`. ```rust 1 fn env_lookup(key: &str) -> Option<&'static str> { 2 match key { 3 "PORT" => Some("8080"), 4 "RETRIES" => Some("notanumber"), 5 _ => None, 6 } 7 } 8 9 fn config_u16(key: &str) -> Result<u16, String> { 10 // TODO: use ok_or_else, ?, and map_err 11 /* ??? */ 12 } 13 14 fn main() { 15 println!("{:?}", config_u16("PORT")); 16 println!("{:?}", config_u16("RETRIES")); 17 println!("{:?}", config_u16("MISSING")); 18 } ``` Solution ```rust 1 fn env_lookup(key: &str) -> Option<&'static str> { 2 match key { 3 "PORT" => Some("8080"), 4 "RETRIES" => Some("notanumber"), 5 _ => None, 6 } 7 } 8 9 fn config_u16(key: &str) -> Result<u16, String> { 10 env_lookup(key) 11 .ok_or_else(|| format!("{key} is not set"))? // Option -> Result, then unwrap or return Err 12 .parse::<u16>() 13 .map_err(|_| format!("{key} is not a valid number")) 14 } 15 16 fn main() { 17 println!("{:?}", config_u16("PORT")); // Ok(8080) 18 println!("{:?}", config_u16("RETRIES")); // Err("RETRIES is not a valid number") 19 println!("{:?}", config_u16("MISSING")); // Err("MISSING is not set") 20 } ``` Output: ```text 1 Ok(8080) 2 Err("RETRIES is not a valid number") 3 Err("MISSING is not set") ``` > The `?` here turns the `Result<&str, String>` produced by `ok_or_else` into a `&str` (or returns early with the `Err`). Read more in [The `?` Operator](/08-error-handling/01-question-mark/). # Rust's `?` Operator vs try/catch > Rust's ? operator propagates an Err or None to the caller with one early return, replacing TypeScript's invisible exception unwinding and converting errors via From. The `?` operator is Rust’s lightweight error-propagation syntax. It replaces the “let it bubble up” behavior you get for free with exceptions in TypeScript/JavaScript — but it does so explicitly, in the type system, with zero hidden control flow. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In TypeScript, a `throw` deep inside a call stack silently unwinds until something `catch`es it; the function signatures say nothing about what can go wrong. In Rust there are no exceptions — fallible functions return a [`Result<T, E>`](/08-error-handling/00-result-option/) (or an [`Option<T>`](/08-error-handling/00-result-option/)), and the **`?` operator** is the ergonomic way to say “if this is an `Err`/`None`, stop here and return it to my caller; otherwise give me the value inside.” Importantly, `?` also runs an automatic `From`-based **error conversion**, so a function can collect several different underlying error types into one declared error type. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript, propagation is implicit. A thrown error travels up the stack on its own, and the type system does not record which functions can fail: ```typescript 1 // Each step can throw; the throws are invisible in the signatures. 2 function parsePort(raw: string): number { 3 const port = Number.parseInt(raw, 10); 4 if (Number.isNaN(port)) { 5 throw new Error(`invalid port: ${raw}`); 6 } 7 return port; 8 } 9 10 function loadConfig(env: Record<string, string>): { host: string; port: number } { 11 const host = env.HOST; // could be undefined — TS won't force a check here 12 if (host === undefined) { 13 throw new Error("missing HOST"); 14 } 15 const port = parsePort(env.PORT); // if this throws, loadConfig throws too — implicitly 16 return { host, port }; 17 } 18 19 try { 20 const config = loadConfig({ HOST: "localhost", PORT: "oops" }); 21 console.log(config); 22 } catch (err) { 23 // `err` is typed `unknown` in modern TS — you must narrow it yourself. 24 console.error("failed:", (err as Error).message); // failed: invalid port: oops 25 } ``` The call `parsePort(env.PORT)` has no syntactic marker that it might throw. The failure path is real but invisible, and the only place it becomes visible is the far-away `try/catch`. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) In Rust the fallibility is in the return type, and each propagation point is marked with a single `?`: ```rust 1 use std::fmt; 2 use std::num::ParseIntError; 3 4 // A custom error enum that aggregates the two ways this code can fail. 5 #[derive(Debug)] 6 enum ConfigError { 7 Missing(String), 8 Parse(ParseIntError), 9 } 10 11 impl fmt::Display for ConfigError { 12 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 13 match self { 14 ConfigError::Missing(key) => write!(f, "missing key: {key}"), 15 ConfigError::Parse(e) => write!(f, "invalid number: {e}"), 16 } 17 } 18 } 19 20 // This is the piece that makes `?` magical: it tells `?` how to turn a 21 // ParseIntError into a ConfigError automatically. 22 impl From<ParseIntError> for ConfigError { 23 fn from(e: ParseIntError) -> Self { 24 ConfigError::Parse(e) 25 } 26 } 27 28 fn read_port(raw: Option<&str>) -> Result<u16, ConfigError> { 29 // `ok_or_else` turns the `Option` into a `Result` so `?` can propagate it. 30 let raw = raw.ok_or_else(|| ConfigError::Missing("PORT".to_string()))?; 31 // `?` here converts ParseIntError -> ConfigError via the `From` impl above. 32 let port: u16 = raw.parse()?; 33 Ok(port) 34 } 35 36 fn main() { 37 println!("{:?}", read_port(Some("8080"))); 38 match read_port(Some("notanumber")) { 39 Ok(p) => println!("port = {p}"), 40 Err(e) => println!("error: {e}"), 41 } 42 match read_port(None) { 43 Ok(p) => println!("port = {p}"), 44 Err(e) => println!("error: {e}"), 45 } 46 } ``` Real output: ```text 1 Ok(8080) 2 error: invalid number: invalid digit found in string 3 error: missing key: PORT ``` Every line that can fail ends in `?`. There is no hidden unwinding: the `?` *is* the early return, and it is right there in the source. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What `?` actually does [Section titled “What ? actually does”](#what--actually-does) When you write `expr?` and `expr` is a `Result<T, E>`: * If it is `Ok(value)`, the whole `expr?` expression **evaluates to `value`** and execution continues. * If it is `Err(e)`, the function **returns early** with `Err(e.into())`. Note the `.into()`, which performs the `From` conversion. So this single character: ```rust 1 let port: u16 = raw.parse()?; ``` is shorthand for this explicit `match` (verified equivalent): ```rust 1 use std::num::ParseIntError; 2 3 fn manual(s: &str) -> Result<i32, ParseIntError> { 4 let n = match s.parse::<i32>() { 5 Ok(v) => v, 6 Err(e) => return Err(From::from(e)), // `?` inserts this From::from conversion 7 }; 8 Ok(n * 2) 9 } ``` > **Note:** The early `return` is the key contrast with TypeScript. In TS, `throw` unwinds the stack through *every* frame until a `catch`. In Rust, `?` returns from *exactly one* function: the one it appears in. To propagate further, the caller must also use `?` (or otherwise handle the `Result`). Propagation is opt-in at every level. ### The `From` conversion is the secret sauce [Section titled “The From conversion is the secret sauce”](#the-from-conversion-is-the-secret-sauce) The `.into()` that `?` inserts is what lets a function unify *different* error types. In `read_port`, `raw.parse()` produces a `Result<u16, ParseIntError>`, but the function returns `Result<u16, ConfigError>`. Those error types differ. `?` bridges the gap by calling `ConfigError::from(parse_int_error)`, which exists because we implemented `From<ParseIntError> for ConfigError`. This means a single `?` does two jobs at once: 1. **Propagate** the error (early return on `Err`). 2. **Convert** it to the function’s declared error type. If no suitable `From` impl exists, the code does not compile; see [Common Pitfalls](#common-pitfalls). ### `?` on `Option` [Section titled “? on Option”](#-on-option) `?` is not limited to `Result`. On an `Option<T>`: * `Some(value)` evaluates to `value`. * `None` returns `None` from the enclosing function early. ```rust 1 fn first_char_upper(s: &str) -> Option<char> { 2 let first = s.chars().next()?; // returns None early if the string is empty 3 Some(first.to_ascii_uppercase()) 4 } 5 6 fn main() { 7 println!("{:?}", first_char_upper("hello")); // Some('H') 8 println!("{:?}", first_char_upper("")); // None 9 } ``` This is the closest Rust analogue to chaining JavaScript’s optional chaining (`?.`): `a?.b?.c` short-circuits to `undefined` on the first nullish hop, just as `?` short-circuits to `None` on the first `None`. ```rust 1 use std::collections::HashMap; 2 3 // Look up an outer key, then an inner key — short-circuit to None on the first miss. 4 fn nested_lookup<'a>( 5 data: &'a HashMap<String, HashMap<String, String>>, 6 outer: &str, 7 inner: &str, 8 ) -> Option<&'a str> { 9 let inner_map = data.get(outer)?; // None if `outer` missing 10 let value = inner_map.get(inner)?; // None if `inner` missing 11 Some(value.as_str()) 12 } ``` > **Tip:** `?` works in any function whose return type implements the `Try` machinery; in practice that means `Result<T, E>` and `Option<T>`. You cannot mix them implicitly: `?` on a `Result` inside an `Option`-returning function will not compile. Convert between them with `.ok()` (Result → Option) or `.ok_or(...)` / `.ok_or_else(...)` (Option → Result), shown below. ### Bridging `Option` and `Result` [Section titled “Bridging Option and Result”](#bridging-option-and-result) Because `?` demands the right “shape,” you will often convert one into the other so `?` lines up with your function’s return type: ```rust 1 use std::num::ParseIntError; 2 3 fn bridges() { 4 // Option -> Result, so `?` can propagate in a Result-returning function. 5 let some: Option<i32> = Some(5); 6 let as_result: Result<i32, &str> = some.ok_or("was none"); 7 println!("{:?}", as_result); // Ok(5) 8 9 // Result -> Option (discarding the error), for an Option-returning function. 10 let res: Result<i32, ParseIntError> = "abc".parse::<i32>(); 11 let as_option: Option<i32> = res.ok(); 12 println!("{:?}", as_option); // None 13 } ``` ### `?` in `fn main` [Section titled “? in fn main”](#-in-fn-main) `main` may itself return a `Result`, which lets you use `?` at the top level. If `main` returns `Err`, the runtime prints the error’s `Debug` representation and exits with a non-zero status code: ```rust 1 use std::error::Error; 2 3 fn parse_config(raw: &str) -> Result<i32, Box<dyn Error>> { 4 let n: i32 = raw.parse()?; // ParseIntError -> Box<dyn Error> automatically 5 Ok(n * 10) 6 } 7 8 fn main() -> Result<(), Box<dyn Error>> { 9 let value = parse_config("oops")?; // propagates; main exits with Err 10 println!("value = {value}"); 11 Ok(()) 12 } ``` Real output (and the process exits with status `1`): ```text 1 Error: ParseIntError { kind: InvalidDigit } ``` > **Note:** `Box<dyn Error>` is a trait object that can hold *any* error type, which is why `?` can absorb both a `ParseIntError` and an `std::io::Error` in the same function: the standard library provides blanket `From` impls into `Box<dyn Error>`. This is the easy-mode error type for applications and `main`; see [Box\<dyn Error>](/08-error-handling/05-error-trait/) and [handling multiple errors](/08-error-handling/07-multiple-errors/). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | TypeScript/JavaScript | Rust (`?`) | | --------------------- | ----------------------------------------- | -------------------------------------------------- | | Propagation | Implicit `throw` unwinds the whole stack | Explicit `?` returns from one function only | | Visible in signature? | No: any function may throw anything | Yes: `Result<T, E>` / `Option<T>` declares it | | What is propagated | Any value (usually `Error`, but anything) | A typed `E` (or `None`) | | Type conversion | None; you `catch` and re-`throw` manually | Automatic via the `From` trait at each `?` | | Catch site | A `try/catch` somewhere up the stack | A `match`, `if let`, or combinator on the `Result` | | Cost | Stack unwinding machinery | A plain conditional branch + early return | The headline difference: in TypeScript the *absence* of error handling is the default and propagation is free; in Rust the *presence* of an error in the type is mandatory and propagation costs you one `?`. This is more typing, but the compiler now guarantees you have not silently ignored a failure path. > **Warning:** `?` is **not** a `try/catch`. It does not *handle* an error — it *forwards* it. The actual handling (logging, retrying, mapping to an HTTP status) happens wherever you finally stop using `?` and pattern-match the `Result` instead. Think of `?` as the `await`-style ergonomics for the unhappy path, not as a recovery mechanism. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Using `?` in a function that returns a plain value [Section titled “Pitfall 1: Using ? in a function that returns a plain value”](#pitfall-1-using--in-a-function-that-returns-a-plain-value) `?` needs a `Result`- or `Option`-shaped return type. Putting it in a function that returns, say, `i32` fails to compile: ```rust 1 fn parse_double(s: &str) -> i32 { 2 let n = s.parse::<i32>()?; // does not compile (error[E0277]) 3 n * 2 4 } ``` Real compiler error: ```text 1 error[E0277]: the `?` operator can only be used in a function that returns `Result` or `Option` (or another type that implements `FromResidual`) 2 --> src/main.rs:2:29 3 | 4 1 | fn parse_double(s: &str) -> i32 { 5 | ------------------------------- this function should return `Result` or `Option` to accept `?` 6 2 | let n = s.parse::<i32>()?; // does not compile (error[E0277]) 7 | ^ cannot use the `?` operator in a function that returns `i32` ``` The fix is to change the return type to `Result<i32, ParseIntError>` (and return `Ok(n * 2)`), or to handle the error locally with `match`, `unwrap_or`, etc. ### Pitfall 2: Using `?` on a `Result` inside an `Option`-returning function [Section titled “Pitfall 2: Using ? on a Result inside an Option-returning function”](#pitfall-2-using--on-a-result-inside-an-option-returning-function) `?` will not silently change a `Result` into an `Option`. The error types and shapes must match the function’s return type: ```rust 1 fn first_num(s: &str) -> Option<i32> { 2 let n = s.parse::<i32>()?; // does not compile (error[E0277]) 3 Some(n) 4 } ``` Real compiler error: ```text 1 error[E0277]: the `?` operator can only be used on `Option`s, not `Result`s, in a function that returns `Option` 2 --> src/main.rs:2:29 3 | 4 1 | fn first_num(s: &str) -> Option<i32> { 5 | ------------------------------------ this function returns an `Option` 6 2 | let n = s.parse::<i32>()?; // does not compile (error[E0277]) 7 | ^ use `.ok()?` if you want to discard the `Result<Infallible, ParseIntError>` error information ``` The compiler even suggests the fix: `s.parse::<i32>().ok()?` turns the `Result` into an `Option` (throwing away the error detail) before applying `?`. ### Pitfall 3: No `From` impl for the function’s error type [Section titled “Pitfall 3: No From impl for the function’s error type”](#pitfall-3-no-from-impl-for-the-functions-error-type) When the error type produced by `?` cannot be converted into the function’s declared error type, the code does not compile. This is the most common surprise for people defining their own error enums: ```rust 1 #[derive(Debug)] 2 struct MyError; 3 4 fn read_number(s: &str) -> Result<i32, MyError> { 5 let n = s.parse::<i32>()?; // does not compile (error[E0277]): no From<ParseIntError> for MyError 6 Ok(n) 7 } ``` Real compiler error (trimmed): ```text 1 error[E0277]: `?` couldn't convert the error to `MyError` 2 --> src/main.rs:5:29 3 | 4 4 | fn read_number(s: &str) -> Result<i32, MyError> { 5 | -------------------- expected `MyError` because of this 6 5 | let n = s.parse::<i32>()?; // does not compile ... 7 | --------------^ the trait `From<ParseIntError>` is not implemented for `MyError` 8 ... 9 note: `MyError` needs to implement `From<ParseIntError>` 10 = note: the question mark operation (`?`) implicitly performs a conversion on the error value using the `From` trait ``` The fix is to `impl From<ParseIntError> for MyError`, or — far more commonly in real code — derive it with `thiserror`’s `#[from]` attribute (see [anyhow & thiserror](/08-error-handling/06-anyhow-thiserror/)). The compiler note spelling out “implicitly performs a conversion on the error value using the `From` trait” is your reminder that `?` and `From` are inseparable. ### Pitfall 4: Expecting `?` to “handle” the error [Section titled “Pitfall 4: Expecting ? to “handle” the error”](#pitfall-4-expecting--to-handle-the-error) A TypeScript developer sometimes reads `value?` as “try this and recover.” It does not recover — it forwards. If you want a fallback value instead of propagation, reach for `unwrap_or`, `unwrap_or_else`, `unwrap_or_default`, or a `match`. (`unwrap`/`expect` are a different, panicking story; see [unwrap & expect](/08-error-handling/03-unwrap-expect/).) *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Prefer `?` over manual `match` for pure propagation [Section titled “Prefer ? over manual match for pure propagation”](#prefer--over-manual-match-for-pure-propagation) If a `match` arm’s only job is `Err(e) => return Err(e.into())`, replace the whole thing with `?`. It is shorter, conventional, and makes the happy path readable top-to-bottom. ### Let `?` do your conversions — design error types with `From` in mind [Section titled “Let ? do your conversions — design error types with From in mind”](#let--do-your-conversions--design-error-types-with-from-in-mind) The most ergonomic custom error types implement `From` for each underlying error they wrap, so that `?` “just works” at every call site. Writing those impls by hand is tedious, so libraries should use `thiserror`’s `#[from]`: ```rust 1 // Sketch — see the anyhow & thiserror topic for the full, compile-verified version. 2 #[derive(Debug, thiserror::Error)] 3 enum ConfigError { 4 #[error("missing key: {0}")] 5 Missing(String), 6 #[error("invalid number")] 7 Parse(#[from] std::num::ParseIntError), // generates From<ParseIntError> 8 } ``` ### In applications and `main`, reach for `Box<dyn Error>` or `anyhow` [Section titled “In applications and main, reach for Box\<dyn Error> or anyhow”](#in-applications-and-main-reach-for-boxdyn-error-or-anyhow) When you do not need to *match* on specific error variants (you just want to propagate and eventually log), `Result<T, Box<dyn Error>>` or `anyhow::Result<T>` lets `?` absorb any error with no per-type `From` impls. Reserve precise enums for *library* APIs whose callers must distinguish failure modes. This application-vs-library split is covered in [best practices](/08-error-handling/08-best-practices/). ### Keep `?` chains shallow and readable [Section titled “Keep ? chains shallow and readable”](#keep--chains-shallow-and-readable) `?` lets you write straight-line code where each step assumes the previous one succeeded. Lean into that: name intermediate values, keep one fallible operation per line, and let the early returns flatten what would otherwise be deeply nested error handling. ### Use `let ... else` when you want to bail without a `?`-compatible type [Section titled “Use let ... else when you want to bail without a ?-compatible type”](#use-let--else-when-you-want-to-bail-without-a--compatible-type) When you are pattern-matching an `Option`/`Result` and want to `return` (or `continue`/`break`) on the failing case with a *custom* action rather than propagation, `let ... else` is often clearer than forcing a `?`: ```rust 1 fn describe(maybe_name: Option<&str>) -> String { 2 let Some(name) = maybe_name else { 3 return "anonymous".to_string(); 4 }; 5 format!("Hello, {name}") 6 } ``` *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small but production-flavored configuration loader. It parses a `KEY = VALUE` block, collects two distinct error kinds (missing fields and bad numbers) into one error type, and uses `?` at every fallible step. Note how `?` short-circuits on the *first* failure encountered. ```rust 1 use std::fmt; 2 use std::num::ParseIntError; 3 4 #[derive(Debug)] 5 struct ServerConfig { 6 host: String, 7 port: u16, 8 max_connections: u32, 9 } 10 11 #[derive(Debug)] 12 enum ConfigError { 13 MissingField(&'static str), 14 InvalidNumber { field: &'static str, source: ParseIntError }, 15 } 16 17 impl fmt::Display for ConfigError { 18 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 19 match self { 20 ConfigError::MissingField(name) => write!(f, "missing required field `{name}`"), 21 ConfigError::InvalidNumber { field, source } => { 22 write!(f, "field `{field}` is not a valid number: {source}") 23 } 24 } 25 } 26 } 27 28 impl std::error::Error for ConfigError {} 29 30 fn get<'a>(lines: &[(&'a str, &'a str)], key: &'static str) -> Result<&'a str, ConfigError> { 31 lines 32 .iter() 33 .find(|(k, _)| *k == key) 34 .map(|(_, v)| *v) 35 .ok_or(ConfigError::MissingField(key)) // Option -> Result so `?` can use it 36 } 37 38 fn parse_num<T: std::str::FromStr<Err = ParseIntError>>( 39 raw: &str, 40 field: &'static str, 41 ) -> Result<T, ConfigError> { 42 // Attach context (which field) while converting the error. 43 raw.parse::<T>() 44 .map_err(|source| ConfigError::InvalidNumber { field, source }) 45 } 46 47 fn load_config(input: &str) -> Result<ServerConfig, ConfigError> { 48 let lines: Vec<(&str, &str)> = input 49 .lines() 50 .filter_map(|l| l.split_once('=')) 51 .map(|(k, v)| (k.trim(), v.trim())) 52 .collect(); 53 54 // Each `?` short-circuits and returns the first error encountered. 55 let host = get(&lines, "host")?.to_string(); 56 let port = parse_num::<u16>(get(&lines, "port")?, "port")?; 57 let max_connections = parse_num::<u32>(get(&lines, "max_connections")?, "max_connections")?; 58 59 Ok(ServerConfig { host, port, max_connections }) 60 } 61 62 fn main() { 63 let good = "host = localhost\nport = 8080\nmax_connections = 256"; 64 match load_config(good) { 65 Ok(cfg) => println!("loaded: {cfg:?}"), 66 Err(e) => eprintln!("config error: {e}"), 67 } 68 69 let bad_port = "host = localhost\nport = http\nmax_connections = 256"; 70 match load_config(bad_port) { 71 Ok(cfg) => println!("loaded: {cfg:?}"), 72 Err(e) => eprintln!("config error: {e}"), 73 } 74 75 let missing = "host = localhost\nport = 8080"; 76 match load_config(missing) { 77 Ok(cfg) => println!("loaded: {cfg:?}"), 78 Err(e) => eprintln!("config error: {e}"), 79 } 80 } ``` Real output: ```text 1 loaded: ServerConfig { host: "localhost", port: 8080, max_connections: 256 } 2 config error: field `port` is not a valid number: invalid digit found in string 3 config error: missing required field `max_connections` ``` The body of `load_config` reads like the happy path — host, then port, then max connections — and the `?`s quietly guarantee that any failure stops and returns immediately. That is the same readability you get from `await`-laden async code, but for errors instead of asynchrony. > **Note:** The standard library does not provide a blanket `From` between two *different* concrete error types, but it *does* provide blanket conversions into `Box<dyn Error>`. So if you swap `ConfigError` for `Box<dyn Error>`, `?` can absorb `ParseIntError`, `std::io::Error`, and friends in the same function with no hand-written `From` impls at all: > > ```rust > 1 > use std::error::Error; > 2 > > > 3 > fn process(num: &str, path: &str) -> Result<usize, Box<dyn Error>> { > 4 > let n: i32 = num.parse()?; // ParseIntError > 5 > let contents = std::fs::read_to_string(path)?; // std::io::Error > 6 > Ok(contents.len() + n as usize) > 7 > } > ``` > > Verified: calling `process("10", "/no/such/file")` yields `No such file or directory (os error 2)`, and `process("ten", "/tmp")` yields `invalid digit found in string`: two different error types, one `?` each. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Rust Book - “A Shortcut for Propagating Errors: the `?` Operator”](https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html#a-shortcut-for-propagating-errors-the--operator) * [The Rust Reference - The question mark operator](https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operator) * [`std::convert::From`](https://doc.rust-lang.org/std/convert/trait.From.html): the conversion `?` relies on * [`Result::ok`](https://doc.rust-lang.org/std/result/enum.Result.html#method.ok) and [`Option::ok_or`](https://doc.rust-lang.org/std/option/enum.Option.html#method.ok_or): bridging the two types ### Related sections in this guide [Section titled “Related sections in this guide”](#related-sections-in-this-guide) * [Result and Option](/08-error-handling/00-result-option/) — the types `?` operates on, and how to match on them * [Custom error types](/08-error-handling/04-custom-errors/): defining the `E` your `?` will produce * [The `Error` trait & `Box<dyn Error>`](/08-error-handling/05-error-trait/) — the trait object that lets `?` absorb anything * [Handling multiple error types](/08-error-handling/07-multiple-errors/): `#[from]` and enum aggregation in depth * [anyhow & thiserror](/08-error-handling/06-anyhow-thiserror/) — deriving the `From` impls `?` needs * [Panics](/08-error-handling/02-panic/) and [unwrap & expect](/08-error-handling/03-unwrap-expect/) — what to use when you do *not* want to propagate * [Error-handling best practices](/08-error-handling/08-best-practices/) — libraries vs. applications * Background: [Why Rust](/01-getting-started/00-why-rust/), [Operators](/02-basics/02-operators/), and [the introduction](/00-introduction/) * Coming next: [Generics & Traits](/09-generics-traits/): `From` and the trait machinery behind `?` *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Sum a list of strings [Section titled “Exercise 1: Sum a list of strings”](#exercise-1-sum-a-list-of-strings) **Difficulty:** Easy **Objective:** Use `?` to propagate a parse error out of a loop. **Instructions:** Write `sum_all(inputs: &[&str]) -> Result<i32, ParseIntError>` that parses each string to an `i32` and returns their sum. The first unparseable string should make the whole function return its `Err`. Call it with `["1", "2", "3"]` and with `["1", "x", "3"]`. ```rust 1 use std::num::ParseIntError; 2 3 fn sum_all(inputs: &[&str]) -> Result<i32, ParseIntError> { 4 // TODO: loop over inputs, use `?` on each parse, accumulate the total 5 /* ??? */ 6 } 7 8 fn main() { 9 println!("{:?}", sum_all(&["1", "2", "3"])); 10 println!("{:?}", sum_all(&["1", "x", "3"])); 11 } ``` Solution ```rust 1 use std::num::ParseIntError; 2 3 fn sum_all(inputs: &[&str]) -> Result<i32, ParseIntError> { 4 let mut total = 0; 5 for s in inputs { 6 total += s.parse::<i32>()?; // `?` returns early on the first bad string 7 } 8 Ok(total) 9 } 10 11 fn main() { 12 println!("{:?}", sum_all(&["1", "2", "3"])); // Ok(6) 13 println!("{:?}", sum_all(&["1", "x", "3"])); // Err(ParseIntError { kind: InvalidDigit }) 14 } ``` Verified output: ```text 1 Ok(6) 2 Err(ParseIntError { kind: InvalidDigit }) ``` ### Exercise 2: Chained `Option` lookups [Section titled “Exercise 2: Chained Option lookups”](#exercise-2-chained-option-lookups) **Difficulty:** Medium **Objective:** Use `?` on `Option` to short-circuit a two-level lookup, mirroring TypeScript’s `?.` chaining. **Instructions:** Given a `HashMap<String, HashMap<String, String>>`, write `nested_lookup(data, outer, inner) -> Option<&str>` that returns the inner value if both keys exist, or `None` if either is missing. Use `?` (not nested `match`). Test with an existing outer+inner pair, an existing outer with a missing inner, and a missing outer. ```rust 1 use std::collections::HashMap; 2 3 fn nested_lookup<'a>( 4 data: &'a HashMap<String, HashMap<String, String>>, 5 outer: &str, 6 inner: &str, 7 ) -> Option<&'a str> { 8 // TODO: use `?` twice, then return Some(...) 9 /* ??? */ 10 } 11 12 fn main() { 13 let mut data = HashMap::new(); 14 let mut user = HashMap::new(); 15 user.insert("email".to_string(), "ada@example.com".to_string()); 16 data.insert("ada".to_string(), user); 17 18 println!("{:?}", nested_lookup(&data, "ada", "email")); 19 println!("{:?}", nested_lookup(&data, "ada", "phone")); 20 println!("{:?}", nested_lookup(&data, "bob", "email")); 21 } ``` Solution ```rust 1 use std::collections::HashMap; 2 3 fn nested_lookup<'a>( 4 data: &'a HashMap<String, HashMap<String, String>>, 5 outer: &str, 6 inner: &str, 7 ) -> Option<&'a str> { 8 let inner_map = data.get(outer)?; // None early if `outer` is missing 9 let value = inner_map.get(inner)?; // None early if `inner` is missing 10 Some(value.as_str()) 11 } 12 13 fn main() { 14 let mut data = HashMap::new(); 15 let mut user = HashMap::new(); 16 user.insert("email".to_string(), "ada@example.com".to_string()); 17 data.insert("ada".to_string(), user); 18 19 println!("{:?}", nested_lookup(&data, "ada", "email")); // Some("ada@example.com") 20 println!("{:?}", nested_lookup(&data, "ada", "phone")); // None 21 println!("{:?}", nested_lookup(&data, "bob", "email")); // None 22 } ``` Verified output: ```text 1 Some("ada@example.com") 2 None 3 None ``` ### Exercise 3: Custom error type with `From` [Section titled “Exercise 3: Custom error type with From”](#exercise-3-custom-error-type-with-from) **Difficulty:** Hard **Objective:** Make `?` perform an automatic error conversion by implementing `From`, and combine it with an early-return for a second error variant. **Instructions:** Define a `CartError` enum with two variants: `Empty` (the cart has no items) and `BadQuantity(ParseIntError)`. Implement `Display` and `From<ParseIntError> for CartError`. Then write `total_items(quantities: &[&str]) -> Result<u32, CartError>` that returns `CartError::Empty` if the slice is empty, otherwise parses and sums the quantities using `?` (relying on your `From` impl). Test with valid input, an unparseable entry, and an empty slice. ```rust 1 use std::fmt; 2 use std::num::ParseIntError; 3 4 #[derive(Debug)] 5 enum CartError { 6 Empty, 7 BadQuantity(ParseIntError), 8 } 9 10 // TODO: impl fmt::Display for CartError 11 // TODO: impl From<ParseIntError> for CartError 12 13 fn total_items(quantities: &[&str]) -> Result<u32, CartError> { 14 // TODO: return CartError::Empty if empty; otherwise sum with `?` 15 /* ??? */ 16 } 17 18 fn main() { 19 println!("{:?}", total_items(&["2", "3", "1"])); 20 // ... also test &["2", "oops"] and &[] 21 } ``` Solution ```rust 1 use std::fmt; 2 use std::num::ParseIntError; 3 4 #[derive(Debug)] 5 enum CartError { 6 Empty, 7 BadQuantity(ParseIntError), 8 } 9 10 impl fmt::Display for CartError { 11 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 12 match self { 13 CartError::Empty => write!(f, "cart is empty"), 14 CartError::BadQuantity(e) => write!(f, "bad quantity: {e}"), 15 } 16 } 17 } 18 19 // This is what lets `?` turn a ParseIntError into a CartError automatically. 20 impl From<ParseIntError> for CartError { 21 fn from(e: ParseIntError) -> Self { 22 CartError::BadQuantity(e) 23 } 24 } 25 26 fn total_items(quantities: &[&str]) -> Result<u32, CartError> { 27 if quantities.is_empty() { 28 return Err(CartError::Empty); // explicit early return for the non-parse failure 29 } 30 let mut total = 0; 31 for q in quantities { 32 total += q.parse::<u32>()?; // ParseIntError -> CartError via `From` 33 } 34 Ok(total) 35 } 36 37 fn main() { 38 println!("{:?}", total_items(&["2", "3", "1"])); 39 match total_items(&["2", "oops"]) { 40 Ok(n) => println!("total = {n}"), 41 Err(e) => println!("error: {e}"), 42 } 43 match total_items(&[]) { 44 Ok(n) => println!("total = {n}"), 45 Err(e) => println!("error: {e}"), 46 } 47 } ``` Verified output: ```text 1 Ok(6) 2 error: bad quantity: invalid digit found in string 3 error: cart is empty ``` > **Tip:** Writing `impl From<...>` by hand is fine for one or two variants, but real libraries derive it with `thiserror`’s `#[from]`. See [anyhow & thiserror](/08-error-handling/06-anyhow-thiserror/). # Panicking: `panic!` vs Recoverable Errors > Rust splits failure into recoverable Result and unrecoverable panic!, unlike JavaScript's single throw. Learn unwinding vs abort, catch_unwind, and when to crash. In TypeScript and JavaScript, `throw` is your one tool for “something went wrong,” whether it’s a missing file, bad user input, or a genuine bug. Rust deliberately splits these into two categories: **recoverable** errors (modeled with `Result<T, E>`) and **unrecoverable** errors (signalled with `panic!`). Knowing which is which, and why Rust draws the line, is the heart of writing idiomatic, solid Rust. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **panic** is Rust’s way of saying “this should never happen; the program is in a state I cannot safely continue from.” Reaching one unwinds the current thread (running destructors as it goes) and, by default, terminates the program. Unlike a JavaScript `throw`, a panic is **not** the normal way to report expected failures; those belong in a `Result`. Use `panic!` for **bugs and broken invariants**, and use `Result` for **anything a caller could reasonably handle**. > **Note:** This page focuses on `panic!`, unwinding vs. aborting, and when panicking is appropriate. The recoverable side — `Result<T, E>` and `Option<T>` — is covered in [Result and Option](/08-error-handling/00-result-option/), and the `unwrap`/`expect` shortcuts that *deliberately* turn an `Err` into a panic live in [`unwrap` and `expect`](/08-error-handling/03-unwrap-expect/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In JavaScript there is exactly one mechanism for signalling failure: `throw`. The same keyword reports user-input problems *and* programmer bugs, and a single `try/catch` can swallow both. ```typescript 1 // JavaScript/TypeScript: `throw` is used for EVERYTHING. 2 3 // (1) Expected, recoverable failure — bad user input. 4 function parsePort(raw: string): number { 5 const port = Number(raw); 6 if (!Number.isInteger(port) || port < 0 || port > 65535) { 7 throw new Error(`invalid port: ${raw}`); 8 } 9 return port; 10 } 11 12 // (2) A genuine bug / broken invariant — should "never" happen. 13 function applyDiscount(price: number, percent: number): number { 14 if (percent < 0 || percent > 100) { 15 throw new Error(`percent must be 0..100, got ${percent}`); 16 } 17 return price - (price * percent) / 100; 18 } 19 20 // Both kinds of failure are caught the same way: 21 try { 22 const port = parsePort(process.argv[2] ?? ""); 23 console.log(`listening on ${port}`); 24 } catch (err) { 25 // A bad CLI argument and an internal bug land in the same handler. 26 console.error("startup failed:", (err as Error).message); 27 process.exit(1); 28 } ``` Because `throw` and `catch` are untyped and uniform, nothing in the signature of `parsePort` or `applyDiscount` tells you whether a call *can* fail, what it fails *with*, or whether the failure represents recoverable user error or an internal bug. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust splits the two cases apart. Recoverable failure is a value (`Result`); an unrecoverable bug is a `panic!`. ```rust 1 // Rust: two distinct mechanisms. 2 3 // (1) Recoverable failure -> the type system forces the caller to deal with it. 4 fn parse_port(raw: &str) -> Result<u16, std::num::ParseIntError> { 5 raw.trim().parse::<u16>() 6 } 7 8 // (2) Broken invariant / bug -> panic. `assert!` panics with a message 9 // when its condition is false. 10 fn apply_discount(price: u32, percent: u32) -> u32 { 11 assert!(percent <= 100, "percent must be 0..=100, got {percent}"); 12 price - (price * percent / 100) 13 } 14 15 fn main() { 16 // Propagate the Result; discarding it would trigger an unused_must_use warning. 17 match parse_port("8080") { 18 Ok(p) => println!("port = {p}"), 19 Err(e) => println!("bad port: {e}"), 20 } 21 match parse_port("not-a-number") { 22 Ok(p) => println!("port = {p}"), 23 Err(e) => println!("bad port: {e}"), 24 } 25 26 println!("discounted = {}", apply_discount(200, 25)); 27 } ``` **Real output:** ```text 1 port = 8080 2 bad port: invalid digit found in string 3 discounted = 150 ``` The signature `-> Result<u16, ParseIntError>` is a *promise in the type*: this call can fail, and here is the error type. By contrast, `apply_discount` returns a plain `u32` (its signature says “this always succeeds”) and the only way it *doesn’t* is if a caller violates the documented contract, which is a bug worth crashing on. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What `panic!` actually does [Section titled “What panic! actually does”](#what-panic-actually-does) `panic!("message")` is a macro (note the `!`, like `println!`). When executed it: 1. Prints the panic message and source location to **stderr**. 2. Optionally captures a backtrace (controlled by the `RUST_BACKTRACE` environment variable). 3. **Unwinds** the current thread by default, walking back up the call stack and running each value’s destructor (`Drop`) so resources like files, locks, and heap allocations are released. 4. If the panicking thread is the main thread (and nothing catches the unwind), the process exits with a non-zero status. ```rust 1 fn main() { 2 println!("about to panic"); 3 panic!("something went terribly wrong"); 4 } ``` **Real output (default debug build):** ```text 1 about to panic 2 3 thread 'main' panicked at src/main.rs:3:5: 4 something went terribly wrong 5 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` The process exits with status code **101** (Rust’s conventional exit code for an unwinding panic). Compare this with a JavaScript uncaught exception, which prints a stack trace and exits with code `1`. ### Backtraces are opt-in [Section titled “Backtraces are opt-in”](#backtraces-are-opt-in) Notice the line `note: run with RUST_BACKTRACE=1 ...`. Unlike a Node.js exception, which always prints a full stack trace, Rust **omits** the backtrace by default for speed and noise reduction. Set the environment variable to see it: ```rust 1 fn main() { 2 let v = vec![1, 2, 3]; 3 println!("trying to access index 10"); 4 let _x = v[10]; // out-of-bounds index -> panic 5 println!("unreachable"); 6 } ``` Run with `RUST_BACKTRACE=1 cargo run`: ```text 1 trying to access index 10 2 3 thread 'main' panicked at src/main.rs:4:15: 4 index out of bounds: the len is 3 but the index is 10 5 stack backtrace: 6 0: __rustc::rust_begin_unwind 7 at /rustc/.../library/std/src/panicking.rs:697:5 8 1: core::panicking::panic_fmt 9 at /rustc/.../library/core/src/panicking.rs:75:14 10 2: core::panicking::panic_bounds_check 11 at /rustc/.../library/core/src/panicking.rs:280:5 12 ... 13 6: probe::main 14 at ./src/main.rs:4:15 15 7: core::ops::function::FnOnce::call_once 16 at /rustc/.../library/core/src/ops/function.rs:253:5 17 note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace. ``` Indexing out of bounds is one of several library operations that panic on a broken precondition. `RUST_BACKTRACE=full` shows every frame including std internals. > **Tip:** Many bugs in Rust manifest as a panic from a library function (`index out of bounds`, `called Option::unwrap() on a None value`, `attempt to divide by zero`). When you hit one, set `RUST_BACKTRACE=1` to find the exact line in *your* code that triggered it. ### Unwinding runs your destructors [Section titled “Unwinding runs your destructors”](#unwinding-runs-your-destructors) By default a panic unwinds, and unwinding is *not* a silent crash: every value on the stack is dropped in reverse order, so cleanup code runs. Rust has no `finally`; the `Drop` trait fills that role. ```rust 1 struct Guard; 2 3 impl Drop for Guard { 4 fn drop(&mut self) { 5 println!("Guard::drop ran during unwinding (cleanup happened)"); 6 } 7 } 8 9 fn risky() { 10 let _g = Guard; 11 panic!("boom in risky()"); 12 } 13 14 fn main() { 15 let result = std::panic::catch_unwind(|| { 16 risky(); 17 }); 18 19 match result { 20 Ok(_) => println!("no panic"), 21 Err(_) => println!("caught a panic, main continues"), 22 } 23 24 println!("main finished normally"); 25 } ``` **Real output:** ```text 1 thread 'main' panicked at src/main.rs:11:5: 2 boom in risky() 3 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace 4 Guard::drop ran during unwinding (cleanup happened) 5 caught a panic, main continues 6 main finished normally ``` Two things to take away. First, `Guard::drop` ran *during* the unwind: your cleanup is honored. Second, `std::panic::catch_unwind` can intercept an unwinding panic and turn it into a `Result`. That looks like `try/catch`, but it is emphatically **not** how you handle ordinary errors (see Pitfalls). It exists for narrow cases: stopping a panic from crossing a thread or a foreign-function-interface (FFI) boundary, and in test harnesses. ### A panic kills the thread, not necessarily the program [Section titled “A panic kills the thread, not necessarily the program”](#a-panic-kills-the-thread-not-necessarily-the-program) If a *spawned* thread panics, only that thread dies. The panic is stored in the thread’s `JoinHandle` and surfaces as an `Err` when you `join` it. ```rust 1 use std::thread; 2 3 fn main() { 4 let handle = thread::spawn(|| { 5 panic!("worker thread blew up"); 6 }); 7 8 let result = handle.join(); 9 match result { 10 Ok(()) => println!("worker finished cleanly"), 11 Err(_) => println!("worker panicked, but main is still alive"), 12 } 13 14 println!("main thread keeps running"); 15 } ``` **Real output:** ```text 1 thread '<unnamed>' panicked at src/main.rs:5:9: 2 worker thread blew up 3 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace 4 worker panicked, but main is still alive 5 main thread keeps running ``` This is closer to how an unhandled rejection in one async task behaves than to a process-wide crash, but it only applies to *additional* threads. A panic on the main thread that nobody catches ends the program. *** ## Key Differences [Section titled “Key Differences”](#key-differences) ### Two failure mechanisms, not one [Section titled “Two failure mechanisms, not one”](#two-failure-mechanisms-not-one) | Concept | TypeScript/JavaScript | Rust | | ---------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------ | | Expected/recoverable failure | `throw` + `try/catch` | `Result<T, E>` value (see [Result and Option](/08-error-handling/00-result-option/)) | | Bug / impossible state | `throw` (same as above) | `panic!` / `assert!` / `unreachable!` | | Shows up in the signature? | No (untyped) | Yes: `Result` is in the return type; panics are not | | Default cleanup | `finally` blocks | `Drop` destructors run during unwind | | Catching | `try/catch` (idiomatic, everywhere) | `catch_unwind` (rare, boundary-only) | | Process exit code | `1` for uncaught exception | `101` for unwinding panic, `134` (`SIGABRT`) for abort | ### Unwinding vs. aborting [Section titled “Unwinding vs. aborting”](#unwinding-vs-aborting) A panic can be handled by the runtime in one of two **panic strategies**: * **`unwind`** (the default): walk the stack, run destructors, optionally let `catch_unwind` stop the unwind. Slightly larger binaries (they carry unwinding tables) and a little runtime cost, but cleanup is guaranteed. * **`abort`**: immediately terminate the process via the platform’s abort (`SIGABRT`). No destructors run, no `catch_unwind`, smaller binaries. Common for embedded targets, some release builds, and anywhere you want a panic to be a hard, fast stop. You select `abort` per build profile in `Cargo.toml`: ```toml 1 # Cargo.toml — abort instead of unwinding on panic 2 [profile.release] 3 panic = "abort" ``` Here is the difference made concrete. Under `panic = "abort"`, the destructor does **not** run: ```rust 1 struct Guard; 2 3 impl Drop for Guard { 4 fn drop(&mut self) { 5 println!("this should NOT print under panic=abort"); 6 } 7 } 8 9 fn main() { 10 let _g = Guard; 11 println!("about to panic with abort strategy"); 12 panic!("aborting now"); 13 } ``` **Real output with `panic = "abort"`:** ```text 1 about to panic with abort strategy 2 3 thread 'main' panicked at src/main.rs:12:5: 4 aborting now 5 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` The `Guard::drop` line never prints, and the process exits with code **134** (128 + signal 6, `SIGABRT`) instead of the `101` you get when unwinding. JavaScript has no equivalent toggle: an uncaught exception always unwinds the JS call stack and runs `finally` blocks. | | `unwind` (default) | `abort` | | ---------------------------------- | ---------------------- | --------------------------------------------- | | Runs `Drop` destructors | Yes | No | | `catch_unwind` can intercept | Yes | No | | Binary size | Larger (unwind tables) | Smaller | | Exit on uncaught main-thread panic | code `101` | `SIGABRT` (code `134` on Unix) | | Typical use | apps, libraries, tests | embedded, size-/speed-critical release builds | > **Note:** Even with the default `unwind` strategy, a *second* panic that occurs *while already unwinding* (for example, a `Drop` impl that itself panics) escalates straight to an abort. Keep destructors panic-free. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Treating `panic!` like JavaScript `throw` [Section titled “Pitfall 1: Treating panic! like JavaScript throw”](#pitfall-1-treating-panic-like-javascript-throw) The single most common mistake is reaching for `panic!` (or `unwrap`/`expect`) to report an expected failure such as bad input, a missing file, or a failed network call. That is what `Result` is for. Panicking on recoverable conditions makes your library unusable as a dependency: callers cannot recover, and the panic crashes *their* program. ```rust 1 // Anti-pattern: panicking on ordinary, recoverable input failure. 2 fn parse_port(raw: &str) -> u16 { 3 raw.parse().expect("invalid port") // crashes the whole program on bad input 4 } 5 6 // Idiomatic: return a Result and let the caller decide. 7 fn parse_port_ok(raw: &str) -> Result<u16, std::num::ParseIntError> { 8 raw.parse() 9 } ``` Both compile. The first is a *design* bug: a parsing routine should never decide to terminate the process. See [`unwrap` and `expect`](/08-error-handling/03-unwrap-expect/) for the (narrow) cases where `expect` is justified. ### Pitfall 2: Using `catch_unwind` as a general `try/catch` [Section titled “Pitfall 2: Using catch\_unwind as a general try/catch”](#pitfall-2-using-catch_unwind-as-a-general-trycatch) `std::panic::catch_unwind` superficially resembles `try/catch`, so newcomers try to use it to handle ordinary errors. Resist. It is meant for *boundaries* (don’t let a panic unwind across an FFI call or take down a thread pool), not for control flow. It also requires the captured data to be `UnwindSafe`, and many ordinary types are not, so it often won’t even compile: ```rust 1 use std::cell::RefCell; 2 use std::panic; 3 4 fn main() { 5 let shared = RefCell::new(0); 6 // does not compile (error E0277: RefCell is not UnwindSafe) 7 let result = panic::catch_unwind(|| { 8 *shared.borrow_mut() += 1; 9 }); 10 println!("{result:?}"); 11 } ``` The real compiler error: ```text 1 error[E0277]: the type `UnsafeCell<i32>` may contain interior mutability and a 2 reference may not be safely transferrable across a catch_unwind boundary 3 --> src/main.rs:7:38 4 | 5 7 | let result = panic::catch_unwind(|| { 6 | __________________-------------------_^ 7 | | required by a bound introduced by this call 8 8 | | *shared.borrow_mut() += 1; 9 9 | | }); 10 | |_____^ `UnsafeCell<i32>` may contain interior mutability and a reference may 11 | not be safely transferrable across a catch_unwind boundary 12 = help: within `RefCell<i32>`, the trait `RefUnwindSafe` is not implemented ``` The `UnwindSafe` bound is the compiler steering you away from using panics for flow control: catching a panic mid-mutation could leave a value in a logically broken state. If you find yourself reaching for `catch_unwind` in business logic, you almost certainly want `Result` instead. ### Pitfall 3: Assuming `abort` still runs cleanup [Section titled “Pitfall 3: Assuming abort still runs cleanup”](#pitfall-3-assuming-abort-still-runs-cleanup) If you set `panic = "abort"` for the performance and binary-size benefits, remember that destructors **do not run** on panic. Code that relies on `Drop` for critical cleanup on the panic path (flushing a buffer, releasing an OS resource) will silently skip it. With `unwind`, that same cleanup runs. ### Pitfall 4: Expecting a panic to print a stack trace by default [Section titled “Pitfall 4: Expecting a panic to print a stack trace by default”](#pitfall-4-expecting-a-panic-to-print-a-stack-trace-by-default) Coming from Node.js, you may expect every crash to dump a stack trace. Rust does not, for performance reasons; you only get the message and source location unless `RUST_BACKTRACE=1` (or `full`) is set. In production, set it via the environment of your service so crash logs are actionable. ### Pitfall 5: Forgetting that a panicked thread does not stop `main` [Section titled “Pitfall 5: Forgetting that a panicked thread does not stop main”](#pitfall-5-forgetting-that-a-panicked-thread-does-not-stop-main) A panic in a spawned thread is captured in its `JoinHandle` and does not propagate automatically. If you `spawn` work and never `join` (or never check the result), a worker can die silently while the rest of the program carries on as though nothing happened. Always inspect `handle.join()` when a thread’s success matters. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Default to `Result`.** If a caller could plausibly want to recover — bad input, a missing file, a timeout, a failed parse — return a `Result`. Reserve panics for situations that genuinely indicate a bug. The companion pages [Result and Option](/08-error-handling/00-result-option/) and [The `?` Operator](/08-error-handling/01-question-mark/) show how to make `Result` ergonomic with the `?` operator. * **Panic on broken invariants, not on user input.** A function that receives an argument violating its documented contract (an index past the end of an array, a probability outside `0.0..=1.0`) is entitled to panic: the *caller* has a bug. Use `assert!`, `assert_eq!`, and `debug_assert!` to express these checks. Document them under a `# Panics` heading in the doc comment. * **Write good panic messages.** A panic should explain *what* invariant was violated and ideally *what value* broke it. `assert!(percent <= 100, "percent must be 0..=100, got {percent}")` is far more useful in a crash log than a bare `assert!(percent <= 100)`. * **Use the right “this should never happen” macro.** Rust ships several: | Macro | Meaning | Panics when reached? | | ---------------------- | --------------------------------- | -------------------- | | `panic!("msg")` | Explicit, unconditional crash | Always | | `assert!(cond, "msg")` | Crash if `cond` is false | Conditionally | | `unreachable!()` | ”Control flow can never get here” | Always (if it does) | | `todo!()` | Placeholder for unwritten code | Always | | `unimplemented!()` | Intentionally not implemented | Always | `todo!` and `unimplemented!` satisfy the type checker (they return `!`, the never type) so you can stub a function and keep compiling: ```rust 1 fn serialize(_d: &Direction) -> String { 2 todo!("serialization not implemented yet") 3 } ``` Reaching it panics with `not yet implemented: serialization not implemented yet`. We cover the never type and the type-level reasoning in [Generics & Traits](/09-generics-traits/). * **Choose your panic strategy deliberately.** Keep the default `unwind` for servers and libraries where graceful teardown matters; consider `panic = "abort"` for embedded targets or when you want the smallest, fastest binary and a panic is always fatal anyway. * **Test the panic paths.** Use `#[should_panic(expected = "...")]` to assert that a function panics on a contract violation, so the behavior is locked in: ```rust 1 #[test] 2 #[should_panic(expected = "whole must be non-zero")] 3 fn panics_on_zero_whole() { 4 percentage(1, 0); 5 } ``` See [Testing](/13-testing/) for the full testing story. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production service typically faces both kinds of failure during startup. User-supplied configuration is **recoverable**: report it and let the operator fix it. An internal helper called with a logically impossible argument represents a **bug** and should panic loudly. Here is a config loader that draws that line clearly. ```rust 1 use std::collections::HashMap; 2 3 /// A recoverable error: the operator can fix bad config and retry. 4 #[derive(Debug)] 5 enum ConfigError { 6 MissingKey(String), 7 InvalidNumber { key: String, value: String }, 8 } 9 10 impl std::fmt::Display for ConfigError { 11 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { 12 match self { 13 ConfigError::MissingKey(k) => write!(f, "missing required key: {k}"), 14 ConfigError::InvalidNumber { key, value } => { 15 write!(f, "key `{key}` has invalid number: {value:?}") 16 } 17 } 18 } 19 } 20 21 struct Config { 22 port: u16, 23 workers: u32, 24 } 25 26 /// Parsing operator-supplied config is RECOVERABLE -> return a Result. 27 fn load_config(raw: &HashMap<&str, &str>) -> Result<Config, ConfigError> { 28 let port_str = raw 29 .get("port") 30 .ok_or_else(|| ConfigError::MissingKey("port".into()))?; 31 let port = port_str 32 .parse::<u16>() 33 .map_err(|_| ConfigError::InvalidNumber { 34 key: "port".into(), 35 value: (*port_str).to_string(), 36 })?; 37 38 let workers_str = raw.get("workers").copied().unwrap_or("4"); 39 let workers = workers_str 40 .parse::<u32>() 41 .map_err(|_| ConfigError::InvalidNumber { 42 key: "workers".into(), 43 value: workers_str.to_string(), 44 })?; 45 46 Ok(Config { port, workers }) 47 } 48 49 /// Splits `total_jobs` evenly across `workers`. A zero worker count is a 50 /// PROGRAMMER bug at this layer (the config layer guarantees >= 1), so we 51 /// treat it as unrecoverable. 52 /// 53 /// # Panics 54 /// Panics if `workers` is zero. 55 fn chunk_size(total_jobs: u32, workers: u32) -> u32 { 56 assert!(workers > 0, "worker pool must have at least one worker"); 57 total_jobs.div_ceil(workers) 58 } 59 60 fn main() { 61 let mut raw = HashMap::new(); 62 raw.insert("port", "8080"); 63 raw.insert("workers", "3"); 64 65 match load_config(&raw) { 66 Ok(cfg) => { 67 println!("listening on port {}", cfg.port); 68 println!("chunk size = {}", chunk_size(100, cfg.workers)); 69 } 70 Err(e) => eprintln!("config error: {e}"), 71 } 72 73 // Recoverable path: a bad value is reported and the program keeps running. 74 let mut bad = HashMap::new(); 75 bad.insert("port", "70000"); // > u16::MAX 76 match load_config(&bad) { 77 Ok(_) => println!("unexpected ok"), 78 Err(e) => println!("rejected bad config: {e}"), 79 } 80 } ``` **Real output:** ```text 1 listening on port 8080 2 chunk size = 34 3 rejected bad config: key `port` has invalid number: "70000" ``` The two flavors of failure are visible in the *signatures*. `load_config` returns `Result<Config, ConfigError>`: bad config is data the caller must handle, and the program survives it. `chunk_size` returns a plain `u32` with a documented `# Panics` clause: it trusts its caller, and a zero worker count would be a contradiction the config layer already ruled out, so if it ever happens, crashing is the correct, loud response. For richer error types and the `anyhow`/`thiserror` crates that production code reaches for, see [Custom Error Types](/08-error-handling/04-custom-errors/) and [`anyhow` & `thiserror`](/08-error-handling/06-anyhow-thiserror/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [The Rust Programming Language — “To `panic!` or Not to `panic!`”](https://doc.rust-lang.org/book/ch09-03-to-panic-or-not-to-panic.html) * [The Rust Programming Language — “Unrecoverable Errors with `panic!`”](https://doc.rust-lang.org/book/ch09-01-unrecoverable-errors-with-panic.html) * [`std::panic`](https://doc.rust-lang.org/std/panic/index.html) and [`std::panic::catch_unwind`](https://doc.rust-lang.org/std/panic/fn.catch_unwind.html) * [`panic!` macro](https://doc.rust-lang.org/std/macro.panic.html), [`todo!`](https://doc.rust-lang.org/std/macro.todo.html), [`unreachable!`](https://doc.rust-lang.org/std/macro.unreachable.html) * [The Cargo Book — profile `panic` setting](https://doc.rust-lang.org/cargo/reference/profiles.html#panic) * Related sections in this guide: * [Result and Option](/08-error-handling/00-result-option/) — the recoverable counterpart to panicking * [The `?` Operator](/08-error-handling/01-question-mark/) — propagating recoverable errors with `?` * [`unwrap` and `expect`](/08-error-handling/03-unwrap-expect/) — when turning an error into a panic is acceptable * [Error-Handling Best Practices](/08-error-handling/08-best-practices/) — recoverable vs. unrecoverable error design * [Section 08 overview](/08-error-handling/) · [Section 00 — Introduction](/00-introduction/) · [Section 01 — Getting Started](/01-getting-started/) · [Section 02 — Basics](/02-basics/) · [Section 09 — Generics & Traits](/09-generics-traits/) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: From panic to `Result` [Section titled “Exercise 1: From panic to Result”](#exercise-1-from-panic-to-result) **Difficulty:** Easy **Objective:** Recognize when a panic is the wrong tool and convert it into a recoverable error. **Instructions:** The function below panics on division by zero, but division by zero is something a caller could reasonably want to handle, not a bug. Rewrite it to return a `Result<i64, MathError>` where `MathError` is your own error type. Demonstrate both the `Ok` and `Err` paths from `main`. ```rust 1 // Starting point — refactor this to return a Result. 2 fn divide(numerator: i64, denominator: i64) -> i64 { 3 if denominator == 0 { 4 panic!("division by zero"); // recoverable; shouldn't panic 5 } 6 numerator / denominator 7 } ``` Solution ```rust 1 #[derive(Debug, PartialEq)] 2 enum MathError { 3 DivideByZero, 4 } 5 6 fn safe_divide(numerator: i64, denominator: i64) -> Result<i64, MathError> { 7 if denominator == 0 { 8 return Err(MathError::DivideByZero); 9 } 10 Ok(numerator / denominator) 11 } 12 13 fn main() { 14 println!("{:?}", safe_divide(10, 2)); // Ok(5) 15 println!("{:?}", safe_divide(10, 0)); // Err(DivideByZero) 16 } ``` **Output:** ```text 1 Ok(5) 2 Err(DivideByZero) ``` The caller now decides what to do with a zero denominator instead of having the program ripped out from under it. ### Exercise 2: A justified panic with a documented invariant [Section titled “Exercise 2: A justified panic with a documented invariant”](#exercise-2-a-justified-panic-with-a-documented-invariant) **Difficulty:** Medium **Objective:** Identify a case where panicking *is* correct and express the contract clearly. **Instructions:** Write `pick_wrapping<T>(slice: &[T], index: usize) -> &T` that returns the element at `index`, wrapping around with the modulo operator so any index is valid — *except* when the slice is empty, which is a programmer error (there is nothing to return). Use `assert!` with a clear message, document the panic in a `# Panics` doc comment, and show it returning a value for an out-of-range index on a non-empty slice. Solution ```rust 1 /// Picks element `index` from `slice`, wrapping around with modulo. 2 /// 3 /// # Panics 4 /// Panics if `slice` is empty (there is nothing to pick). 5 fn pick_wrapping<T>(slice: &[T], index: usize) -> &T { 6 assert!(!slice.is_empty(), "cannot pick from an empty slice"); 7 &slice[index % slice.len()] 8 } 9 10 fn main() { 11 let colors = ["red", "green", "blue"]; 12 println!("{}", pick_wrapping(&colors, 7)); // 7 % 3 == 1 -> "green" 13 } ``` **Output:** ```text 1 green ``` The empty-slice case is genuinely impossible to serve, so panicking is the right call — and the `# Panics` clause makes the contract explicit. Pass `&[] as &[&str]` and it would panic with `cannot pick from an empty slice`. ### Exercise 3: A panic boundary with `catch_unwind` [Section titled “Exercise 3: A panic boundary with catch\_unwind”](#exercise-3-a-panic-boundary-with-catch_unwind) **Difficulty:** Hard **Objective:** Use `catch_unwind` for its legitimate purpose: isolating untrusted code so a panic in it does not take down the host. **Instructions:** Imagine a plugin host that runs third-party closures. A misbehaving plugin should not crash the host. Write `run_plugin<F: FnOnce() + UnwindSafe>(name: &str, plugin: F)` that runs the closure inside `std::panic::catch_unwind`, prints whether it succeeded or panicked, and lets the host continue. Run one well-behaved plugin and one that panics. Solution ```rust 1 fn run_plugin<F: FnOnce() + std::panic::UnwindSafe>(name: &str, plugin: F) { 2 match std::panic::catch_unwind(plugin) { 3 Ok(()) => println!("plugin `{name}` ran successfully"), 4 Err(_) => println!("plugin `{name}` panicked; host stays up"), 5 } 6 } 7 8 fn main() { 9 run_plugin("good", || println!(" doing safe work")); 10 run_plugin("bad", || panic!("plugin exploded")); 11 println!("host still running"); 12 } ``` **Output:** ```text 1 doing safe work 2 plugin `good` ran successfully 3 4 thread 'main' panicked at src/main.rs:10:26: 5 plugin exploded 6 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace 7 plugin `bad` panicked; host stays up 8 host still running ``` The panic message still prints (via the panic hook), but the unwind is *caught* at the host boundary, so the program survives and the next plugin runs. This is the legitimate use of `catch_unwind` — note it requires the closure to be `UnwindSafe`, and under `panic = "abort"` it can never actually catch anything: the process is terminated at the panic point before the catch can return `Err`. # `unwrap` and `expect`: Asserting "This Cannot Fail" > Rust's unwrap and expect pull the value out of a Result or Option or panic on failure, the loud, located answer to TypeScript's silent non-null assertion operator. When you have a `Result<T, E>` or an `Option<T>` and you are *certain* it holds the success value, `unwrap` and `expect` let you pull that value out, at the cost of a **panic** if you were wrong. They are the loud, honest cousins of TypeScript’s silent non-null assertion (`!`). *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) `unwrap` and `expect` are methods on both `Result<T, E>` and `Option<T>` that **return the inner value or crash the program** (panic) if there isn’t one. They are convenient but blunt: every `unwrap` is a place your program *can* abort. The skill is knowing the handful of situations where that is acceptable — **tests, throwaway prototypes, and provable invariants** — and reaching for `?`, `match`, or the `unwrap_or_*` family everywhere else. > **Note:** This page is about *extracting* values with a panic as the failure mode. For propagating errors instead of panicking, see [The `?` Operator](/08-error-handling/01-question-mark/); for matching on `Result`/`Option`, see [Result and Option](/08-error-handling/00-result-option/); for the mechanics of panicking itself, see [Panics](/08-error-handling/02-panic/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript, the closest analogue to `unwrap` is the **non-null assertion operator** (`!`). It tells the compiler “trust me, this is not `null`/`undefined`” — but it adds **no runtime check at all**. If you are wrong, you don’t get a crash at the assertion site; you get a silent `undefined` that corrupts data downstream. ```typescript 1 interface Config { 2 port?: number; 3 } 4 5 function startServer(config: Config): void { 6 // The `!` silences the type checker. There is NO runtime check. 7 const port: number = config.port!; 8 console.log("Listening on", port + 1); 9 } 10 11 const cfg: Config = {}; // oops, no port 12 startServer(cfg); 13 // Output: 14 // Listening on NaN 15 // -> port was `undefined`; `undefined + 1` is NaN. No error thrown. ``` Running the underlying behavior on Node v22: ```text 1 port: undefined 2 port + 1: NaN ``` A *real* throw (TypeScript/JavaScript’s exception mechanism) only happens when an API decides to throw, for example `JSON.parse` on malformed input: ```typescript 1 try { 2 JSON.parse("{ not json"); 3 } catch (e) { 4 console.log("caught:", (e as Error).constructor.name); 5 // caught: SyntaxError 6 } ``` The point: TypeScript’s `!` is **silent and unsafe**. Bad assumptions leak through as `undefined`/`NaN` and surface far from the bug. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust’s `unwrap`/`expect` make the same “trust me” claim, but they are **loud and safe**: if the claim is false, the program panics *immediately, at the exact line*, with a message. It never hands you a corrupt value. ```rust 1 fn main() { 2 // unwrap on Option: returns the value, or panics on None. 3 let nums = vec![1, 2, 3]; 4 let first = nums.first().unwrap(); // &1 5 println!("first: {first}"); 6 7 // unwrap on Result: returns Ok value, or panics on Err. 8 let n: i32 = "42".parse().unwrap(); 9 println!("parsed: {n}"); 10 11 // expect is unwrap WITH a custom panic message describing the invariant. 12 let port: Option<&str> = Some("8080"); 13 let p = port.expect("PORT must be set"); 14 println!("port: {p}"); 15 } ``` ```text 1 first: 1 2 parsed: 42 3 port: 8080 ``` When the assumption is wrong, you get an immediate, located panic instead of a silent `NaN`: ```rust 1 fn main() { 2 let value: Option<i32> = None; 3 let x = value.unwrap(); // panics at runtime 4 println!("{x}"); 5 } ``` ```text 1 thread 'main' panicked at src/main.rs:3:19: 2 called `Option::unwrap()` on a `None` value 3 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` > **Note:** This is not a *compile* error — the code compiles fine. `unwrap` is a runtime assertion. The win over TypeScript’s `!` is that the failure is **immediate and pinpointed** (`src/main.rs:3:19`), not a value that quietly poisons later computations. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What the methods actually do [Section titled “What the methods actually do”](#what-the-methods-actually-do) Both `Option` and `Result` provide these methods. We can’t re-`impl` the real `Option` from outside the standard library (Rust forbids inherent `impl`s on foreign types — that would be error `E0116`), so the snippet below mirrors it with a local `MyOption<T>` to show what the bodies actually do. It compiles and mirrors std’s real definitions: ```rust 1 // A local stand-in for std's `Option<T>`, used only to show the bodies. 2 // (Re-`impl`ing the real `Option` here would fail with E0116.) 3 enum MyOption<T> { 4 Some(T), 5 None, 6 } 7 8 impl<T> MyOption<T> { 9 fn unwrap(self) -> T { 10 match self { 11 MyOption::Some(v) => v, 12 MyOption::None => panic!("called `Option::unwrap()` on a `None` value"), 13 } 14 } 15 fn expect(self, msg: &str) -> T { 16 match self { 17 MyOption::Some(v) => v, 18 MyOption::None => panic!("{msg}"), 19 } 20 } 21 } ``` * `unwrap()`: returns the inner value, or panics with a **generic** message. * `expect("...")`: returns the inner value, or panics with **your** message. For `Result`, `unwrap` additionally prints the `Err` value using its `Debug` representation: ```rust 1 fn main() { 2 let parsed: Result<i32, std::num::ParseIntError> = "not a number".parse(); 3 let n = parsed.unwrap(); // panics 4 println!("{n}"); 5 } ``` ```text 1 thread 'main' panicked at src/main.rs:3:20: 2 called `Result::unwrap()` on an `Err` value: ParseIntError { kind: InvalidDigit } 3 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` Notice the panic message includes `ParseIntError { kind: InvalidDigit }` — the `Err` value’s `Debug` output. That is why a bare `unwrap` on a `Result` is often *good enough* for debugging, while a bare `unwrap` on an `Option<T>` (which has no error payload) tells you only “it was `None`.” ### `expect` carries the *why*, not the *what* [Section titled “expect carries the why, not the what”](#expect-carries-the-why-not-the-what) A common source of confusion: the `expect` message should describe **why you expected success**, not restate that something failed. The Rust standard library docs explicitly recommend the “should/because” phrasing. ```rust 1 fn main() { 2 // Restates the obvious; tells you nothing new when it fires. 3 // let p: i32 = "x".parse().expect("parse failed"); 4 5 // Describes the invariant you were relying on. 6 let raw = "8080"; 7 let p: i32 = raw 8 .parse() 9 .expect("PORT should be a valid integer; it comes from a validated config"); 10 println!("{p}"); 11 } ``` ```text 1 8080 ``` When this panics, the message reads as a sentence: *“PORT should be a valid integer; it comes from a validated config”*, which immediately points a maintainer at the broken assumption. ### Where `unwrap`/`expect` sit among the alternatives [Section titled “Where unwrap/expect sit among the alternatives”](#where-unwrapexpect-sit-among-the-alternatives) `unwrap`/`expect` are the **panic-on-failure** end of a spectrum. The other end recovers gracefully: ```rust 1 fn main() { 2 let maybe: Option<i32> = None; 3 4 // Panic family (this page): 5 // maybe.unwrap(); // panic with generic message 6 // maybe.expect("must be present"); // panic with your message 7 8 // Recover family (no panic): 9 println!("{}", maybe.unwrap_or(0)); // supply a fallback value 10 println!("{}", maybe.unwrap_or_else(|| 0)); // compute a fallback lazily 11 println!("{}", maybe.unwrap_or_default()); // use T::default() -> 0 for i32 12 } ``` ```text 1 0 2 0 3 0 ``` > **Tip:** If a sensible fallback exists, prefer the recover family over `unwrap`. If the caller should *decide* what to do, propagate with `?` (see [The `?` Operator](/08-error-handling/01-question-mark/)). Reserve `unwrap`/`expect` for “this genuinely cannot fail.” *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | TypeScript `value!` (non-null assertion) | Rust `value.unwrap()` / `.expect(msg)` | | --------------------- | ---------------------------------------- | ---------------------------------------------- | | Runtime check | **None** — purely a compile-time hint | **Yes** — checks at runtime | | On a wrong assumption | Silent `undefined`, corruption spreads | **Immediate panic** at the exact line | | Failure visibility | Surfaces far from the bug (or never) | Pinpointed file/line, optional backtrace | | Custom message | Not applicable | `expect("...")` lets you explain the invariant | | Recovery | N/A (no failure event) | Use `unwrap_or`, `?`, or `match` instead | | Cost of being wrong | Subtle data bugs | Process aborts (loud, debuggable) | **Why Rust does it this way.** Rust has no exceptions and no `null`. A `None`/`Err` is an ordinary value the type system *forces* you to acknowledge. `unwrap`/`expect` are the explicit, greppable escape hatch for “I am converting this possibility-of-failure into a hard assumption.” Because it is a method call (not a sigil like `!`), it is visible in code review, searchable, and lintable. > **Warning:** Unlike TypeScript, where `!` and a checked access look almost identical, in Rust the choice between `unwrap` and `?`/`match` is a real, reviewable design decision. A reviewer who sees `unwrap` in non-test code is entitled to ask: *“Prove this can’t fail.”* *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: `unwrap` on external input [Section titled “Pitfall 1: unwrap on external input”](#pitfall-1-unwrap-on-external-input) The most frequent mistake from TypeScript/JavaScript developers is treating `unwrap` like `!` and slapping it on **untrusted input**: user input, files, network, environment variables. These *can* fail, so `unwrap` turns a recoverable error into a crash. ```rust 1 use std::env; 2 3 fn main() { 4 // Panics if PORT isn't set — a perfectly ordinary, recoverable situation. 5 let port: u16 = env::var("PORT").unwrap().parse().unwrap(); 6 println!("{port}"); 7 } ``` If `PORT` is unset, this panics with the `Err` value `NotPresent` printed in the message: a perfectly ordinary, recoverable situation turned into a crash. **Fix:** propagate with `?` or supply a default: ```rust 1 use std::env; 2 3 fn main() { 4 // Sensible default instead of a crash. 5 let port: u16 = env::var("PORT") 6 .ok() 7 .and_then(|s| s.parse().ok()) 8 .unwrap_or(8080); 9 println!("{port}"); 10 } ``` ```text 1 8080 ``` ### Pitfall 2: Bare `unwrap` on `Option` gives a useless message [Section titled “Pitfall 2: Bare unwrap on Option gives a useless message”](#pitfall-2-bare-unwrap-on-option-gives-a-useless-message) When an `Option::unwrap` fires, the message is only the generic “called `Option::unwrap()` on a `None` value”: no clue *which* `unwrap` or *why*. In a function with several, you can’t tell which one blew up without a backtrace. **Fix:** use `expect` with a distinguishing message. The location (`file:line`) plus your message makes triage instant. ### Pitfall 3: `unwrap_or` evaluates its argument eagerly [Section titled “Pitfall 3: unwrap\_or evaluates its argument eagerly”](#pitfall-3-unwrap_or-evaluates-its-argument-eagerly) `unwrap_or(x)` always evaluates `x`, even when the value is `Some`/`Ok`. If the fallback is expensive (or has side effects), that’s wasted work. ```rust 1 fn expensive_default() -> String { 2 println!("(computing expensive default)"); 3 "fallback".to_string() 4 } 5 6 fn main() { 7 let present = Some("hi".to_string()); 8 9 // unwrap_or_else: closure runs ONLY on None. 10 let a = present.clone().unwrap_or_else(expensive_default); 11 println!("a = {a}"); 12 13 // unwrap_or: the argument is ALWAYS evaluated, even though we're Some. 14 let b = present.unwrap_or(expensive_default()); 15 println!("b = {b}"); 16 } ``` ```text 1 a = hi 2 (computing expensive default) 3 b = hi ``` Note `(computing expensive default)` prints for `unwrap_or` despite the value being `Some`. **Fix:** prefer `unwrap_or_else(|| ...)` when the fallback is non-trivial; reserve `unwrap_or` for cheap literals. ### Pitfall 4: Forgetting it compiles (it’s a *runtime* trap) [Section titled “Pitfall 4: Forgetting it compiles (it’s a runtime trap)”](#pitfall-4-forgetting-it-compiles-its-a-runtime-trap) `unwrap` always type-checks, so the compiler will not warn you. The failure only appears when that branch executes, which might be in production at 3 a.m. There is no fabricated compiler error to show here precisely because there isn’t one; the danger is the *silence at compile time*. That is exactly why Clippy ships an opt-in lint to flag it (next section). *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Turn on Clippy’s `unwrap_used` / `expect_used` lints in app crates [Section titled “Turn on Clippy’s unwrap\_used / expect\_used lints in app crates”](#turn-on-clippys-unwrap_used--expect_used-lints-in-app-crates) Clippy has **restriction lints** (off by default) that flag every `unwrap`/`expect`. Enabling them in application code forces a deliberate decision at each call site: ```rust 1 #![warn(clippy::unwrap_used)] 2 3 fn first_word(s: &str) -> &str { 4 s.split_whitespace().next().unwrap() 5 } 6 7 fn main() { 8 println!("{}", first_word("hello world")); 9 } ``` Running `cargo clippy`: ```text 1 warning: used `unwrap()` on an `Option` value 2 --> src/main.rs:4:5 3 | 4 4 | s.split_whitespace().next().unwrap() 5 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6 | 7 = note: if this value is `None`, it will panic 8 = help: consider using `expect()` to provide a better panic message 9 = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#unwrap_used 10 note: the lint level is defined here 11 --> src/main.rs:1:9 12 | 13 1 | #![warn(clippy::unwrap_used)] 14 | ^^^^^^^^^^^^^^^^^^^ ``` > **Tip:** Put `#![warn(clippy::unwrap_used)]` (or `expect_used`) at the crate root, or configure it in `Cargo.toml`’s `[lints.clippy]` table, then allow it locally with `#[allow(clippy::unwrap_used)]` on the rare justified call. This makes “I really mean it” explicit and reviewable. ### Prefer `expect` over `unwrap` outside tests, with a “should/because” message [Section titled “Prefer expect over unwrap outside tests, with a “should/because” message”](#prefer-expect-over-unwrap-outside-tests-with-a-shouldbecause-message) If you’ve decided a call genuinely cannot fail, document *why* with `expect`. The message is free documentation that also becomes the crash report if your reasoning was wrong. ### The three legitimate homes for `unwrap`/`expect` [Section titled “The three legitimate homes for unwrap/expect”](#the-three-legitimate-homes-for-unwrapexpect) 1. **Tests.** A failed assumption *should* fail the test. `unwrap` in test setup and assertions is idiomatic and encouraged. 2. **Prototypes / examples / scripts.** When you’re exploring and error handling is noise, `unwrap` keeps the signal clear. Just don’t ship it. 3. **Provable invariants.** When a *prior* operation guarantees success — a regex literal you wrote, an index you just bounds-checked, a value you just inserted — `unwrap`/`expect` document that the failure branch is unreachable. ### `unwrap` in tests is the right tool [Section titled “unwrap in tests is the right tool”](#unwrap-in-tests-is-the-right-tool) ```rust 1 fn parse_csv_row(row: &str) -> Vec<i32> { 2 row.split(',').map(|s| s.trim().parse().unwrap()).collect() 3 } 4 5 #[cfg(test)] 6 mod tests { 7 use super::*; 8 9 #[test] 10 fn parses_a_simple_row() { 11 // A failure here SHOULD fail the test — unwrap is exactly right. 12 assert_eq!(parse_csv_row("10, 20, 30"), vec![10, 20, 30]); 13 } 14 15 #[test] 16 fn unwrap_in_setup() { 17 let n: i32 = "7".parse().unwrap(); // panic == test failure, as intended 18 assert_eq!(n, 7); 19 } 20 } ``` ```text 1 running 2 tests 2 ... 3 4 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` > **Note:** `cargo test` runs tests in a nondeterministic order (parallel threads), so the per-test lines are elided above; only the `test result: ok.` summary is stable. Run with `cargo test -- --test-threads=1` if you want a fixed order. > **Note:** Test functions usually return `()`, so you cannot use `?` to bail out; `unwrap`/`expect` are the natural fit. (Tests *can* return `Result`, in which case `?` works too; see [Testing](/13-testing/) when you reach it.) ### Provable invariants: when the failure branch truly can’t happen [Section titled “Provable invariants: when the failure branch truly can’t happen”](#provable-invariants-when-the-failure-branch-truly-cant-happen) A regex you write yourself is a compile-time-constant pattern. After it compiles once, matching can’t produce a malformed capture group, so the inner `unwrap`s are provably infallible: > **Note:** This example uses the external `regex` crate. Add it with `cargo add regex` (this guide uses **regex 1.x**, currently `1.12.3`). ```rust 1 use regex::Regex; 2 3 /// Extracts the major version from a tag like "v1.2.3". 4 /// The pattern guarantees group 1 exists and is all ASCII digits, 5 /// so both `unwrap` calls are provably infallible. 6 fn major_version(tag: &str) -> Option<u32> { 7 let re = Regex::new(r"^v(\d+)\.\d+\.\d+$").unwrap(); // we wrote this literal 8 let caps = re.captures(tag)?; 9 let major: u32 = caps.get(1).unwrap().as_str().parse().unwrap(); 10 Some(major) 11 } 12 13 fn main() { 14 println!("{:?}", major_version("v1.2.3")); // Some(1) 15 println!("{:?}", major_version("v12.0.7")); // Some(12) 16 println!("{:?}", major_version("nope")); // None 17 } ``` ```text 1 Some(1) 2 Some(12) 3 None ``` > **Tip:** Even for “provable” cases, prefer `expect` with a note like `"version regex is a hardcoded valid pattern"`. If a future edit breaks the invariant, the panic explains the violated assumption instead of leaving the next reader guessing. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production line-parser that validates each record. A regex compiled from a **hardcoded literal** can never fail at runtime, so `expect` there is justified, and it doubles as a tripwire if someone introduces a typo. Everything that depends on *input* uses `Option`/`?`-style flow instead of `unwrap`. > **Note:** This example uses the external `regex` crate. Add it with `cargo add regex` (this guide uses **regex 1.x**, currently `1.12.3`). `OnceLock` is in the standard library and needs no dependency. ```rust 1 use std::sync::OnceLock; 2 3 // A regex compiled once and cached. The pattern is a literal we control, so 4 // `.expect(...)` can never fire at runtime; if we ever introduce a typo it 5 // fails loudly on first use with a clear message. 6 fn email_regex() -> &'static regex::Regex { 7 static RE: OnceLock<regex::Regex> = OnceLock::new(); 8 RE.get_or_init(|| { 9 regex::Regex::new(r"^[^@\s]+@[^@\s]+\.[^@\s]+$") 10 .expect("email regex is a valid, hardcoded pattern") 11 }) 12 } 13 14 #[derive(Debug)] 15 struct User { 16 name: String, 17 email: String, 18 } 19 20 // Untrusted input -> recoverable Option flow, NOT unwrap. 21 fn parse_user(line: &str) -> Option<User> { 22 let (name, email) = line.split_once(',')?; 23 let email = email.trim(); 24 if !email_regex().is_match(email) { 25 return None; 26 } 27 Some(User { 28 name: name.trim().to_string(), 29 email: email.to_string(), 30 }) 31 } 32 33 fn main() { 34 let lines = [ 35 "Ada, ada@example.com", 36 "Bad, not-an-email", 37 "Bob,bob@rust-lang.org", 38 ]; 39 for line in lines { 40 match parse_user(line) { 41 Some(u) => println!("ok: {u:?}"), 42 None => println!("skip: {line:?}"), 43 } 44 } 45 } ``` ```text 1 ok: User { name: "Ada", email: "ada@example.com" } 2 skip: "Bad, not-an-email" 3 ok: User { name: "Bob", email: "bob@rust-lang.org" } ``` The single `expect` is on data we fully control (the regex literal); every decision about *external* input flows through `Option` and `?` (`split_once(...)?`), so malformed lines are skipped, not fatal. This is the line a maintainer wants to see: panics reserved for “impossible,” recovery for “expected.” > **Note:** `OnceLock` (stable since Rust 1.70) is the current idiom for lazily-initialized statics in the standard library; no external crate needed. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [`Option::unwrap`](https://doc.rust-lang.org/std/option/enum.Option.html#method.unwrap) and [`Option::expect`](https://doc.rust-lang.org/std/option/enum.Option.html#method.expect) * [`Result::unwrap`](https://doc.rust-lang.org/std/result/enum.Result.html#method.unwrap) and [`Result::expect`](https://doc.rust-lang.org/std/result/enum.Result.html#method.expect) * [The Rust Book — “To `panic!` or Not to `panic!`”](https://doc.rust-lang.org/book/ch09-03-to-panic-or-not-to-panic.html) (the “Cases in Which You Have More Information Than the Compiler” section is exactly the provable-invariant case) * [Clippy lint: `unwrap_used`](https://rust-lang.github.io/rust-clippy/master/index.html#unwrap_used) and [`expect_used`](https://rust-lang.github.io/rust-clippy/master/index.html#expect_used) * [`std::sync::OnceLock`](https://doc.rust-lang.org/std/sync/struct.OnceLock.html) ### Related sections in this guide [Section titled “Related sections in this guide”](#related-sections-in-this-guide) * [Result and Option](/08-error-handling/00-result-option/): the types `unwrap`/`expect` live on, and how to match on them * [The `?` Operator](/08-error-handling/01-question-mark/): the propagate-don’t-panic alternative * [Panics](/08-error-handling/02-panic/): what a panic actually is (unwinding vs abort) and when panicking is appropriate * [Best Practices](/08-error-handling/08-best-practices/): choosing between panic and recovery across a whole codebase * [Why Rust](/01-getting-started/00-why-rust/): Rust’s exception-free error model in context * [Basic Types](/02-basics/01-types/): the `Option`/`Result` enums build on Rust’s type system * [Generics and Traits](/09-generics-traits/): how `Option<T>`/`Result<T, E>` and methods like `unwrap` are generic *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Replace a bare `unwrap` with a meaningful `expect` [Section titled “Exercise 1: Replace a bare unwrap with a meaningful expect”](#exercise-1-replace-a-bare-unwrap-with-a-meaningful-expect) **Difficulty:** Beginner **Objective:** Practice writing a “should/because” `expect` message that documents an invariant. **Instructions:** The function below parses a port from a string with a bare `unwrap`. Rewrite it to use `expect` with a message that explains *why* success is expected and where the value comes from. ```rust 1 fn parse_port(raw: &str) -> u16 { 2 raw.parse().unwrap() // TODO: replace with a meaningful expect 3 } 4 5 fn main() { 6 println!("{}", parse_port("8080")); 7 } ``` Solution ```rust 1 fn parse_port(raw: &str) -> u16 { 2 raw.parse() 3 .expect("PORT must be a valid u16 (set via the PORT env var)") 4 } 5 6 fn main() { 7 println!("{}", parse_port("8080")); 8 } ``` ```text 1 8080 ``` The message reads as a sentence and points a maintainer at the assumption (a validated `PORT`) if it ever fails. ### Exercise 2: Make `unwrap` provably safe [Section titled “Exercise 2: Make unwrap provably safe”](#exercise-2-make-unwrap-provably-safe) **Difficulty:** Intermediate **Objective:** Recognize a provable invariant and use `expect` to document it. **Instructions:** Write `middle_element(data: &[i32]) -> Option<i32>` that returns the middle element of a slice, or `None` when the slice is empty. After you check for emptiness, the middle index is *provably* in bounds; use `expect` (with a justifying message) to extract it from the `Option` returned by `.get(mid)`. ```rust 1 fn middle_element(data: &[i32]) -> Option<i32> { 2 // TODO: return None when empty; otherwise return the middle element. 3 // The index access should be a provable invariant after your check. 4 /* ??? */ 5 } 6 7 fn main() { 8 println!("{:?}", middle_element(&[1, 2, 3, 4, 5])); // Some(3) 9 println!("{:?}", middle_element(&[])); // None 10 } ``` Solution ```rust 1 fn middle_element(data: &[i32]) -> Option<i32> { 2 if data.is_empty() { 3 return None; 4 } 5 let mid = data.len() / 2; 6 // `mid` is in bounds because the slice is non-empty, so .get(mid) is Some. 7 Some(*data.get(mid).expect("mid is in bounds for a non-empty slice")) 8 } 9 10 fn main() { 11 println!("{:?}", middle_element(&[1, 2, 3, 4, 5])); // Some(3) 12 println!("{:?}", middle_element(&[])); // None 13 } ``` ```text 1 Some(3) 2 None ``` ### Exercise 3: `unwrap` belongs in the tests [Section titled “Exercise 3: unwrap belongs in the tests”](#exercise-3-unwrap-belongs-in-the-tests) **Difficulty:** Intermediate **Objective:** Use `unwrap` idiomatically where a failure *should* fail the run — a test module. **Instructions:** Given the `middle_element` function from Exercise 2, write a `#[cfg(test)] mod tests` with three tests: the middle of an odd-length slice equals the expected value (use `.unwrap()` on the returned `Option`), the middle of `[10, 20, 30]` is `20`, and the middle of an empty slice is `None` (use `.is_none()`). Solution ```rust 1 fn middle_element(data: &[i32]) -> Option<i32> { 2 if data.is_empty() { 3 return None; 4 } 5 let mid = data.len() / 2; 6 Some(*data.get(mid).expect("mid is in bounds for a non-empty slice")) 7 } 8 9 fn main() { 10 println!("{:?}", middle_element(&[1, 2, 3])); 11 } 12 13 #[cfg(test)] 14 mod tests { 15 use super::*; 16 17 #[test] 18 fn middle_of_odd_len() { 19 // unwrap is idiomatic in tests: a None here SHOULD fail the test. 20 assert_eq!(middle_element(&[1, 2, 3]).unwrap(), 2); 21 } 22 23 #[test] 24 fn middle_of_three() { 25 assert_eq!(middle_element(&[10, 20, 30]).unwrap(), 20); 26 } 27 28 #[test] 29 fn middle_of_empty_is_none() { 30 assert!(middle_element(&[]).is_none()); 31 } 32 } ``` Running `cargo test` (per-test lines are omitted because `cargo test` runs tests in a nondeterministic order; the summary line is the stable part): ```text 1 running 3 tests 2 ... 3 4 test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` *** ## Summary [Section titled “Summary”](#summary) * `unwrap`/`expect` return the inner value of an `Option`/`Result` or **panic** — they are Rust’s loud, located, opt-in answer to TypeScript’s silent `!`. * `expect("...")` should explain *why* you expected success (“should/because”), not restate the failure. * Legitimate uses: **tests**, **prototypes**, and **provable invariants**. Everywhere else, prefer `?` (propagate), `match`, or the `unwrap_or_*` recovery family. * Prefer `unwrap_or_else` over `unwrap_or` when the fallback is expensive — `unwrap_or` evaluates its argument eagerly. * Turn on Clippy’s `unwrap_used`/`expect_used` lints in application crates so each call is a deliberate, reviewable choice. # Custom Error Types > Instead of subclassing Error like TS, Rust models failures as an enum or struct with Display and the Error trait, for compiler-checked, exhaustive cases. In TypeScript you usually `throw new Error("...")` or subclass `Error`. Rust has no exceptions, so you instead **define a type** that lists exactly what can go wrong and return it inside `Result<T, E>`. This page is about designing those types by hand: as **enums** or **structs**, and wiring them up with the `Display` and `Error` traits so they behave like first-class errors. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **custom error type** is just a normal Rust type (an `enum` or a `struct`) that you use as the `E` in `Result<T, E>`. Two things turn an ordinary type into a real error: * **`Display`**: produces the human-readable, end-user-facing message (what `{}` prints). * **`std::error::Error`**: the marker/interop trait that lets your type flow through `Box<dyn Error>`, the `?` operator, and crates like anyhow. > **Note:** This page covers the hand-written approach so you understand what is really going on. In real libraries you will almost always derive these with the **thiserror** crate; see [`anyhow` & `thiserror`](/08-error-handling/06-anyhow-thiserror/). The mechanics here are exactly what that derive macro generates for you. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript, the idiomatic way to model distinct failures is subclassing `Error` and branching on the subclass with `instanceof`: ```typescript 1 // errors.ts — a small config loader with typed failures 2 3 class ConfigError extends Error { 4 // `name` is what shows up in stack traces and logs 5 constructor(message: string) { 6 super(message); 7 this.name = "ConfigError"; 8 } 9 } 10 11 class MissingKeyError extends ConfigError { 12 constructor(public readonly key: string) { 13 super(`missing required config key \`${key}\``); 14 this.name = "MissingKeyError"; 15 } 16 } 17 18 class OutOfRangeError extends ConfigError { 19 constructor( 20 public readonly key: string, 21 public readonly value: number, 22 public readonly min: number, 23 public readonly max: number, 24 ) { 25 super(`config key \`${key}\` = ${value} is out of range (${min}..${max})`); 26 this.name = "OutOfRangeError"; 27 } 28 } 29 30 function readPort(key: string, raw: string | undefined): number { 31 if (raw === undefined) { 32 throw new MissingKeyError(key); 33 } 34 const parsed = Number(raw); 35 if (!Number.isInteger(parsed)) { 36 throw new ConfigError(`config key \`${key}\` has non-numeric value \`${raw}\``); 37 } 38 if (parsed < 1 || parsed > 65535) { 39 throw new OutOfRangeError(key, parsed, 1, 65535); 40 } 41 return parsed; 42 } 43 44 try { 45 console.log(readPort("PORT", "70000")); 46 } catch (err) { 47 // The caller has to KNOW which subclasses exist to branch correctly 48 if (err instanceof OutOfRangeError) { 49 console.error(`bad range: ${err.message}`); 50 } else if (err instanceof ConfigError) { 51 console.error(`config problem: ${err.message}`); 52 } else { 53 throw err; // not ours — rethrow 54 } 55 } ``` Two pain points a TypeScript developer feels here: * `readPort` can throw, but its signature (`: number`) does not say so. The compiler will not stop you from forgetting the `try/catch`. * In the `catch`, `err` is typed `unknown` (or `any`), so you reach for `instanceof` checks and hope you covered every subclass. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust encodes the failure modes in the type system. The set of things that can go wrong becomes an `enum`, and the function signature (`Result<u16, ConfigError>`) keeps the possibility of failure visible to callers. Extracting the `u16` requires an explicit choice; discarding the entire `Result` emits a warning by default. ```rust 1 use std::fmt; 2 3 /// Possible failures when reading and validating a config value. 4 #[derive(Debug)] 5 enum ConfigError { 6 /// A required key was absent from the source. 7 MissingKey { key: String }, 8 /// The value was present but could not be parsed as a number. 9 InvalidNumber { key: String, value: String }, 10 /// The value parsed but fell outside the accepted range. 11 OutOfRange { key: String, value: i64, min: i64, max: i64 }, 12 } 13 14 // `Display` = the human-readable, end-user-facing message. 15 impl fmt::Display for ConfigError { 16 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 17 match self { 18 ConfigError::MissingKey { key } => { 19 write!(f, "missing required config key `{key}`") 20 } 21 ConfigError::InvalidNumber { key, value } => { 22 write!(f, "config key `{key}` has non-numeric value `{value}`") 23 } 24 ConfigError::OutOfRange { key, value, min, max } => { 25 write!(f, "config key `{key}` = {value} is out of range ({min}..={max})") 26 } 27 } 28 } 29 } 30 31 // Opting into the standard `Error` trait makes the type interoperable 32 // with `Box<dyn Error>`, the `?` operator, anyhow, and so on. 33 impl std::error::Error for ConfigError {} 34 35 /// Look up `key`, parse it as an integer, and check it is a valid port. 36 fn read_port(key: &str, raw: Option<&str>) -> Result<u16, ConfigError> { 37 let value = raw.ok_or_else(|| ConfigError::MissingKey { key: key.to_string() })?; 38 39 let parsed: i64 = value.parse().map_err(|_| ConfigError::InvalidNumber { 40 key: key.to_string(), 41 value: value.to_string(), 42 })?; 43 44 if !(1..=65535).contains(&parsed) { 45 return Err(ConfigError::OutOfRange { 46 key: key.to_string(), 47 value: parsed, 48 min: 1, 49 max: 65535, 50 }); 51 } 52 53 Ok(parsed as u16) 54 } 55 56 fn main() { 57 let cases = [ 58 ("PORT", Some("8080")), 59 ("PORT", None), 60 ("PORT", Some("eighty")), 61 ("PORT", Some("70000")), 62 ]; 63 64 for (key, raw) in cases { 65 match read_port(key, raw) { 66 Ok(port) => println!("ok: {port}"), 67 Err(e) => println!("error: {e}"), 68 } 69 } 70 } ``` Running it prints (real output): ```text 1 ok: 8080 2 error: missing required config key `PORT` 3 error: config key `PORT` has non-numeric value `eighty` 4 error: config key `PORT` = 70000 is out of range (1..=65535) ``` > **Tip:** The `match` in `main` is **exhaustive on the `Result`**, not on the error variants, but a caller who *wants* to branch on the specific variant can `match` the `ConfigError` directly, and the compiler will force them to handle every case. That is the type-checked replacement for chained `instanceof` checks. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) Let’s walk through the pieces that turn a plain `enum` into a usable error. ### `#[derive(Debug)]` is mandatory [Section titled “#\[derive(Debug)\] is mandatory”](#derivedebug-is-mandatory) ```rust 1 #[derive(Debug)] 2 enum ConfigError { /* ... */ } ``` Every error type must implement `Debug`. You almost never write it by hand; `#[derive(Debug)]` does it. It is required because the `Error` trait demands it (more below) and because `unwrap`/`expect`/test assertions print errors with `Debug`. This is the developer-facing representation; it shows the structure, e.g. `OutOfRange { key: "PORT", value: 70000, min: 1, max: 65535 }`. ### Each variant carries its own data [Section titled “Each variant carries its own data”](#each-variant-carries-its-own-data) ```rust 1 enum ConfigError { 2 MissingKey { key: String }, // struct-like variant 3 InvalidNumber { key: String, value: String }, 4 OutOfRange { key: String, value: i64, min: i64, max: i64 }, 5 } ``` Unlike a TypeScript subclass hierarchy, the variants live in one closed set. A variant can be: * **unit-like**: `Empty` (no data), * **tuple-like**: `UnknownProduct(String)`, * **struct-like**: `OutOfRange { key, value, .. }` (named fields, as above). Named fields read well when there are several pieces of context. Enums are covered in depth in [Section 06: Data Structures](/06-data-structures/); here we are just using them to enumerate failure modes. ### `impl Display` is the user-facing message [Section titled “impl Display is the user-facing message”](#impl-display-is-the-user-facing-message) ```rust 1 impl fmt::Display for ConfigError { 2 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 3 match self { /* one arm per variant */ } 4 } 5 } ``` `Display` is what `{}` in `println!`/`format!` uses, what a logger typically writes, and what `Box<dyn Error>`’s message comes from. You `match self` and `write!` the message for each variant. The `write!` macro returns `fmt::Result`, which is why the last expression in each arm doubles as the function’s return value. This is the rough analogue of setting `message` on a JavaScript `Error`, except it is computed on demand from the structured fields rather than baked in at construction time. That means the message can never drift out of sync with the data. ### `impl Error` is the interop opt-in [Section titled “impl Error is the interop opt-in”](#impl-error-is-the-interop-opt-in) ```rust 1 impl std::error::Error for ConfigError {} ``` The body is empty because `std::error::Error` has default methods for everything. Implementing it is a deliberate statement: *“this type is an error and may be used wherever an error is expected.”* It enables: * conversion into `Box<dyn Error>` (so `?` works in functions returning `Result<_, Box<dyn Error>>`), * the `source()` cause chain (see [The `Error` Trait](/08-error-handling/05-error-trait/)), * automatic acceptance by anyhow’s `Context` and `?`. The trait has a supertrait bound — `trait Error: Debug + Display` — which is precisely why you must provide both `Debug` and `Display` *before* you can implement `Error`. ### Constructing and returning errors [Section titled “Constructing and returning errors”](#constructing-and-returning-errors) ```rust 1 let value = raw.ok_or_else(|| ConfigError::MissingKey { key: key.to_string() })?; ``` `ok_or_else` converts an `Option` into a `Result`, building the error lazily only if the value is `None`. The `?` then returns early on `Err`. For converting a *different* error type (like `ParseIntError`) into yours, here we use `.map_err(...)`; the `From`-based automatic conversion that `?` can do is covered in [The `?` Operator](/08-error-handling/01-question-mark/). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript | Rust | | ---------------------------- | --------------------------------------- | ------------------------------------------------- | | Declaring failures | `class FooError extends Error` per case | one `enum` with a variant per case, or a `struct` | | Is failure in the signature? | No, any function may `throw` | Yes, `Result<T, E>` is explicit | | Branching on the case | `instanceof` chains on `unknown` | exhaustive `match` on the enum, compiler-checked | | Human message | `this.message` set in constructor | `impl Display` computed from fields | | ”This is an error” marker | implicit (it extends `Error`) | explicit `impl std::error::Error` | | Debug/developer view | `console.log(err)` / stack trace | `#[derive(Debug)]`, printed with `{:?}` | | Underlying cause | `error.cause` (ES2022) | `Error::source()` returns `Option<&dyn Error>` | | Forgetting a case | silent — runtime surprise | non-exhaustive `match` is a compile error | **The big idea:** in TypeScript an error is “a thing you throw and discover at runtime.” In Rust an error is “a value of a type the compiler tracks,” so the *set* of failures is part of your API and the compiler enforces that every one is handled. > **Note:** Unlike a TypeScript `class` hierarchy, a Rust error `enum` is **closed**: callers cannot add new variants, and you cannot subclass it. This is a feature: a `match` over the variants is provably complete. If you need an open-ended set, you reach for `Box<dyn Error>` instead (see [The `Error` Trait](/08-error-handling/05-error-trait/) and [Handling Multiple Error Types](/08-error-handling/07-multiple-errors/)). ### Enum vs struct: which to use? [Section titled “Enum vs struct: which to use?”](#enum-vs-struct-which-to-use) Use an **enum** when a function can fail in several *distinct* ways the caller might want to tell apart: ```rust 1 enum CheckoutError { 2 UnknownProduct(String), 3 InsufficientStock { product: String, requested: u32, available: u32 }, 4 PaymentDeclined { reason: String }, 5 } ``` Use a **struct** when there is essentially *one* failure mode, optionally wrapping an underlying cause: ```rust 1 use std::num::ParseIntError; 2 3 #[derive(Debug)] 4 struct ParseConfigError { 5 key: String, 6 source: ParseIntError, // the underlying error we wrap 7 } ``` The struct form shines when you want to attach context and expose a cause via `source()`: ```rust 1 use std::error::Error; 2 use std::fmt; 3 use std::num::ParseIntError; 4 5 #[derive(Debug)] 6 struct ParseConfigError { 7 key: String, 8 source: ParseIntError, 9 } 10 11 impl fmt::Display for ParseConfigError { 12 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 13 write!(f, "failed to parse config key `{}`", self.key) 14 } 15 } 16 17 impl Error for ParseConfigError { 18 // Expose the underlying error so callers can walk the cause chain. 19 fn source(&self) -> Option<&(dyn Error + 'static)> { 20 Some(&self.source) 21 } 22 } 23 24 fn parse_key(key: &str, value: &str) -> Result<i64, ParseConfigError> { 25 value.parse().map_err(|source| ParseConfigError { 26 key: key.to_string(), 27 source, 28 }) 29 } 30 31 fn main() { 32 if let Err(e) = parse_key("MAX_RETRIES", "abc") { 33 println!("error: {e}"); 34 // Walk and print each underlying cause. 35 let mut cause = e.source(); 36 while let Some(c) = cause { 37 println!(" caused by: {c}"); 38 cause = c.source(); 39 } 40 } 41 } ``` Real output: ```text 1 error: failed to parse config key `MAX_RETRIES` 2 caused by: invalid digit found in string ``` The `source()` method is the structured equivalent of JavaScript’s `error.cause`. The full cause-chain story lives in [The `Error` Trait](/08-error-handling/05-error-trait/). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: implementing `Error` before `Display` [Section titled “Pitfall 1: implementing Error before Display”](#pitfall-1-implementing-error-before-display) `Error` requires `Display` as a supertrait. Implement `Error` on a type that has no `Display` and you get a clear error: ```rust 1 use std::error::Error; 2 3 #[derive(Debug)] 4 struct MyError { 5 message: String, 6 } 7 8 impl Error for MyError {} // does not compile (error[E0277]: Display not implemented) 9 10 fn main() { 11 let _ = MyError { message: "x".into() }; 12 } ``` Real `rustc` output: ```text 1 error[E0277]: `MyError` doesn't implement `std::fmt::Display` 2 --> src/main.rs:8:16 3 | 4 8 | impl Error for MyError {} // does not compile (error[E0277]: Display not implemented) 5 | ^^^^^^^ the trait `std::fmt::Display` is not implemented for `MyError` 6 | 7 note: required by a bound in `std::error::Error` 8 --> .../library/core/src/error.rs:53:26 9 | 10 53 | pub trait Error: Debug + Display { 11 | ^^^^^^^ required by this bound in `Error` ``` The fix: implement `Display` (and `#[derive(Debug)]`) first, then `impl Error`. ### Pitfall 2: forgetting `impl Error`, then trying to use `?` into `Box<dyn Error>` [Section titled “Pitfall 2: forgetting impl Error, then trying to use ? into Box\<dyn Error>”](#pitfall-2-forgetting-impl-error-then-trying-to-use--into-boxdyn-error) Having `Debug` + `Display` is *not* enough to flow through `Box<dyn Error>`. You must also opt into `Error`: ```rust 1 use std::error::Error; 2 use std::fmt; 3 4 #[derive(Debug)] 5 struct MyError { 6 message: String, 7 } 8 9 impl fmt::Display for MyError { 10 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 11 write!(f, "{}", self.message) 12 } 13 } 14 15 // NOTE: no `impl Error for MyError {}` 16 17 fn do_work() -> Result<(), Box<dyn Error>> { 18 Err(MyError { message: "boom".into() })?; // does not compile (error[E0277]) 19 Ok(()) 20 } 21 22 fn main() { 23 let _ = do_work(); 24 } ``` Real `rustc` output (abridged): ```text 1 error[E0277]: `?` couldn't convert the error: `MyError: std::error::Error` is not satisfied 2 --> src/main.rs:18:44 3 | 4 17 | fn do_work() -> Result<(), Box<dyn Error>> { 5 | -------------------------- required `MyError: std::error::Error` because of this 6 18 | Err(MyError { message: "boom".into() })?; 7 | ---------------------------------------^ the trait `std::error::Error` is not implemented for `MyError` 8 | 9 = note: the question mark operation (`?`) implicitly performs a conversion on the error value using the `From` trait 10 = note: required for `Box<dyn std::error::Error>` to implement `From<MyError>` ``` The fix: add `impl Error for MyError {}`. ### Pitfall 3: printing with `{}` when you only derived `Debug` [Section titled “Pitfall 3: printing with {} when you only derived Debug”](#pitfall-3-printing-with--when-you-only-derived-debug) A TypeScript developer expects “I can always print an error.” In Rust, `{}` needs `Display`, which is *not* derivable: ```rust 1 #[derive(Debug)] 2 enum ValidationError { 3 Empty, 4 TooLong(usize), 5 } 6 7 fn main() { 8 let e = ValidationError::TooLong(120); 9 println!("{}", e); // does not compile (error[E0277]: Display not implemented) 10 } ``` Real `rustc` output (abridged): ```text 1 error[E0277]: `ValidationError` doesn't implement `std::fmt::Display` 2 --> src/main.rs:9:20 3 | 4 9 | println!("{}", e); // does not compile (error[E0277]: Display not implemented) 5 | -- ^ `ValidationError` cannot be formatted with the default formatter 6 | 7 = help: the trait `std::fmt::Display` is not implemented for `ValidationError` 8 = note: in format strings you may be able to use `{:?}` (or {:#?} for pretty-print) instead ``` The fix: implement `Display`, or (for quick debugging only) print with `{:?}` using the derived `Debug`. > **Warning:** Do not implement `Display` by just delegating to `Debug` to silence this error. `Debug` is for developers and may include internals; `Display` is for users and should be a clean sentence. Keeping them distinct pays off the first time an error message ends up in a log, a CLI, or an HTTP response body. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Always derive `Debug`; always implement `Display`; then implement `Error`.** That trio is the contract every error type should satisfy. If you find yourself writing all three by hand repeatedly, switch to thiserror; see [`anyhow` & `thiserror`](/08-error-handling/06-anyhow-thiserror/). * **Make `Display` a clean, lowercase, no-trailing-period sentence.** The convention in the ecosystem is `"failed to read config file"`, not `"Failed to read config file."`. Callers compose messages (`"{context}: {err}"`), so leading capitals and periods read badly when chained. * **Put the data in the variant, build the string in `Display`.** Store `OutOfRange { value, min, max }` rather than a pre-formatted `String`. Structured fields let callers `match` and react programmatically, and they keep the message in one place. * **Choose granularity to match what callers can *do*.** A variant is worth adding only if a caller might handle it differently. If everyone just logs and bails, a single variant (or `Box<dyn Error>`) is fine. Granularity is discussed further in [Error-Handling Best Practices](/08-error-handling/08-best-practices/). * **Implement `source()` whenever you wrap another error.** It preserves the cause chain for debugging and for tools that print full chains. Covered in [The `Error` Trait](/08-error-handling/05-error-trait/). * **Keep `Debug` developer-oriented and `Display` user-oriented.** They serve different audiences; do not collapse them. Here is the recommended shape, all three traits in place, with the three formatters shown side by side: ```rust 1 use std::fmt; 2 3 #[derive(Debug)] 4 enum OrderError { 5 EmptyCart, 6 ItemNotFound { sku: String }, 7 } 8 9 impl fmt::Display for OrderError { 10 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 11 match self { 12 OrderError::EmptyCart => write!(f, "cannot check out an empty cart"), 13 OrderError::ItemNotFound { sku } => write!(f, "item not found: {sku}"), 14 } 15 } 16 } 17 18 impl std::error::Error for OrderError {} 19 20 fn main() { 21 let e = OrderError::ItemNotFound { sku: "A-100".to_string() }; 22 println!("{e}"); // Display -> for users / logs 23 println!("{e:?}"); // Debug -> for developers 24 println!("{e:#?}"); // Debug pretty-printed 25 } ``` Real output: ```text 1 item not found: A-100 2 ItemNotFound { sku: "A-100" } 3 ItemNotFound { 4 sku: "A-100", 5 } ``` > **Tip:** Once you have written a hand-rolled enum like this a couple of times, the thiserror version is a near drop-in. The same `OrderError` becomes a derive with `#[error("...")]` attributes that generate exactly the `Display` impl you would have typed. See [`anyhow` & `thiserror`](/08-error-handling/06-anyhow-thiserror/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A checkout flow that can fail in three meaningfully different ways. The domain layer returns a `CheckoutError`; the “transport” layer `match`es the variant to pick an HTTP-like status code. This is the pattern you would use behind an API handler. ```rust 1 use std::collections::HashMap; 2 use std::error::Error; 3 use std::fmt; 4 5 #[derive(Debug)] 6 enum CheckoutError { 7 /// No product with this id exists. 8 UnknownProduct(String), 9 /// Requested more units than are in stock. 10 InsufficientStock { product: String, requested: u32, available: u32 }, 11 /// The card was declined by the processor. 12 PaymentDeclined { reason: String }, 13 } 14 15 impl fmt::Display for CheckoutError { 16 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 17 match self { 18 CheckoutError::UnknownProduct(id) => { 19 write!(f, "unknown product `{id}`") 20 } 21 CheckoutError::InsufficientStock { product, requested, available } => { 22 write!( 23 f, 24 "not enough `{product}` in stock: requested {requested}, only {available} available" 25 ) 26 } 27 CheckoutError::PaymentDeclined { reason } => { 28 write!(f, "payment declined: {reason}") 29 } 30 } 31 } 32 } 33 34 impl Error for CheckoutError {} 35 36 struct Inventory { 37 stock: HashMap<String, u32>, 38 } 39 40 impl Inventory { 41 fn checkout(&self, product: &str, qty: u32) -> Result<u32, CheckoutError> { 42 let available = self 43 .stock 44 .get(product) 45 .copied() 46 .ok_or_else(|| CheckoutError::UnknownProduct(product.to_string()))?; 47 48 if qty > available { 49 return Err(CheckoutError::InsufficientStock { 50 product: product.to_string(), 51 requested: qty, 52 available, 53 }); 54 } 55 56 if qty > 100 { 57 return Err(CheckoutError::PaymentDeclined { 58 reason: "amount exceeds single-order limit".to_string(), 59 }); 60 } 61 62 Ok(available - qty) 63 } 64 } 65 66 /// Map a domain error to an HTTP-like status code by matching on the variant. 67 fn status_code(err: &CheckoutError) -> u16 { 68 match err { 69 CheckoutError::UnknownProduct(_) => 404, 70 CheckoutError::InsufficientStock { .. } => 409, 71 CheckoutError::PaymentDeclined { .. } => 402, 72 } 73 } 74 75 fn main() { 76 let inv = Inventory { 77 stock: HashMap::from([("widget".to_string(), 5), ("gadget".to_string(), 200)]), 78 }; 79 80 let attempts = [("widget", 2), ("widget", 9), ("bolt", 1), ("gadget", 150)]; 81 for (product, qty) in attempts { 82 match inv.checkout(product, qty) { 83 Ok(remaining) => println!("200 OK -> {remaining} {product} left"), 84 Err(e) => println!("{} -> {e}", status_code(&e)), 85 } 86 } 87 } ``` Real output: ```text 1 200 OK -> 3 widget left 2 409 -> not enough `widget` in stock: requested 9, only 5 available 3 404 -> unknown product `bolt` 4 402 -> payment declined: amount exceeds single-order limit ``` Notice how `status_code` is an exhaustive `match`: add a fourth variant to `CheckoutError` and the compiler immediately points at this function until you decide what status it deserves. That is the safety net `instanceof` chains never give you. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Rust Book — Defining an Error Type](https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html) * [`std::error::Error`](https://doc.rust-lang.org/std/error/trait.Error.html) * [`std::fmt::Display`](https://doc.rust-lang.org/std/fmt/trait.Display.html) * [Rust by Example — Defining error types](https://doc.rust-lang.org/rust-by-example/error/multiple_error_types/define_error_type.html) ### Related sections in this guide [Section titled “Related sections in this guide”](#related-sections-in-this-guide) * [Result and Option](/08-error-handling/00-result-option/) — how `Result<T, E>` and `Option<T>` replace `try/catch`; where your custom error becomes the `E`. * [The `?` Operator](/08-error-handling/01-question-mark/) — the `?` operator and `From`-based conversion between error types. * [The `Error` Trait](/08-error-handling/05-error-trait/) — `std::error::Error` in depth: `Debug + Display` bounds, the `source()` chain, `Box<dyn Error>`. * [`anyhow` & `thiserror`](/08-error-handling/06-anyhow-thiserror/) — deriving everything on this page automatically with **thiserror 2.x** (and when to reach for anyhow instead). * [Handling Multiple Error Types](/08-error-handling/07-multiple-errors/) — aggregating several error types into one enum with `#[from]`. * [Error-Handling Best Practices](/08-error-handling/08-best-practices/) — designing errors for libraries vs applications, and choosing granularity. * [Section 06: Data Structures](/06-data-structures/) — enums and structs, the building blocks used here. * [Section 09: Generics & Traits](/09-generics-traits/) — how `Display` and `Error` fit into Rust’s trait system. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A single-failure struct error [Section titled “Exercise 1: A single-failure struct error”](#exercise-1-a-single-failure-struct-error) **Difficulty:** Easy **Objective:** Define a struct error and implement `Display` and `Error`. **Instructions:** Write a function `validate_username(name: &str) -> Result<&str, EmptyUsername>` that returns `Err` when the (trimmed) name is empty. Define `EmptyUsername` as a unit struct, derive `Debug`, implement `Display` with the message `"username must not be empty"`, and implement `std::error::Error`. ```rust 1 use std::error::Error; 2 use std::fmt; 3 4 #[derive(Debug)] 5 struct EmptyUsername; 6 7 // TODO: impl Display for EmptyUsername 8 // TODO: impl Error for EmptyUsername 9 10 fn validate_username(name: &str) -> Result<&str, EmptyUsername> { 11 // TODO 12 todo!() 13 } 14 15 fn main() { 16 println!("{:?}", validate_username("alice")); 17 match validate_username(" ") { 18 Ok(n) => println!("ok: {n}"), 19 Err(e) => println!("error: {e}"), 20 } 21 } ``` Solution ```rust 1 use std::error::Error; 2 use std::fmt; 3 4 #[derive(Debug)] 5 struct EmptyUsername; 6 7 impl fmt::Display for EmptyUsername { 8 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 9 write!(f, "username must not be empty") 10 } 11 } 12 13 impl Error for EmptyUsername {} 14 15 fn validate_username(name: &str) -> Result<&str, EmptyUsername> { 16 if name.trim().is_empty() { 17 Err(EmptyUsername) 18 } else { 19 Ok(name) 20 } 21 } 22 23 fn main() { 24 println!("{:?}", validate_username("alice")); 25 match validate_username(" ") { 26 Ok(n) => println!("ok: {n}"), 27 Err(e) => println!("error: {e}"), 28 } 29 } ``` Output: ```text 1 Ok("alice") 2 error: username must not be empty ``` ### Exercise 2: An enum error that exposes a cause [Section titled “Exercise 2: An enum error that exposes a cause”](#exercise-2-an-enum-error-that-exposes-a-cause) **Difficulty:** Medium **Objective:** Build a multi-variant error, one of whose variants wraps a standard-library error, and expose that cause via `source()`. **Instructions:** Write `parse_temp(raw: &str) -> Result<f64, TempError>` that: * returns `TempError::Empty` if `raw` is blank, * returns `TempError::NotANumber(ParseFloatError)` if it does not parse as `f64`, * returns `TempError::BelowAbsoluteZero(f64)` if the value is below `-273.15`. Implement `Display` for all three variants and implement `Error::source()` so that the `NotANumber` variant returns its inner `ParseFloatError`. ```rust 1 use std::error::Error; 2 use std::fmt; 3 use std::num::ParseFloatError; 4 5 #[derive(Debug)] 6 enum TempError { 7 Empty, 8 NotANumber(ParseFloatError), 9 BelowAbsoluteZero(f64), 10 } 11 12 // TODO: impl Display 13 // TODO: impl Error with a source() that returns the inner ParseFloatError 14 15 fn parse_temp(raw: &str) -> Result<f64, TempError> { 16 // TODO 17 todo!() 18 } 19 20 fn main() { 21 for raw in ["21.5", "", "hot", "-300"] { 22 match parse_temp(raw) { 23 Ok(c) => println!("ok: {c} C"), 24 Err(e) => { 25 print!("error: {e}"); 26 if let Some(src) = e.source() { 27 print!(" (cause: {src})"); 28 } 29 println!(); 30 } 31 } 32 } 33 } ``` Solution ```rust 1 use std::error::Error; 2 use std::fmt; 3 use std::num::ParseFloatError; 4 5 #[derive(Debug)] 6 enum TempError { 7 Empty, 8 NotANumber(ParseFloatError), 9 BelowAbsoluteZero(f64), 10 } 11 12 impl fmt::Display for TempError { 13 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 14 match self { 15 TempError::Empty => write!(f, "no temperature provided"), 16 TempError::NotANumber(_) => write!(f, "temperature is not a valid number"), 17 TempError::BelowAbsoluteZero(t) => { 18 write!(f, "{t} C is below absolute zero (-273.15 C)") 19 } 20 } 21 } 22 } 23 24 impl Error for TempError { 25 fn source(&self) -> Option<&(dyn Error + 'static)> { 26 match self { 27 TempError::NotANumber(e) => Some(e), 28 _ => None, 29 } 30 } 31 } 32 33 fn parse_temp(raw: &str) -> Result<f64, TempError> { 34 if raw.trim().is_empty() { 35 return Err(TempError::Empty); 36 } 37 let celsius: f64 = raw.trim().parse().map_err(TempError::NotANumber)?; 38 if celsius < -273.15 { 39 return Err(TempError::BelowAbsoluteZero(celsius)); 40 } 41 Ok(celsius) 42 } 43 44 fn main() { 45 for raw in ["21.5", "", "hot", "-300"] { 46 match parse_temp(raw) { 47 Ok(c) => println!("ok: {c} C"), 48 Err(e) => { 49 print!("error: {e}"); 50 if let Some(src) = e.source() { 51 print!(" (cause: {src})"); 52 } 53 println!(); 54 } 55 } 56 } 57 } ``` Output: ```text 1 ok: 21.5 C 2 error: no temperature provided 3 error: temperature is not a valid number (cause: invalid float literal) 4 error: -300 C is below absolute zero (-273.15 C) ``` ### Exercise 3: A library-grade error with a cause chain [Section titled “Exercise 3: A library-grade error with a cause chain”](#exercise-3-a-library-grade-error-with-a-cause-chain) **Difficulty:** Hard **Objective:** Design a complete, library-style error and verify the full cause chain prints correctly. **Instructions:** Build a tiny CSV column summer: * `CsvError::BadHeader { expected, found }` when the input has no rows. * `CsvError::BadCell { row, source: ParseIntError }` when a data row does not parse as an integer. Implement `Display` and `Error` (with `source()` returning the inner `ParseIntError` for `BadCell`). Then write `sum_column(lines: &[&str]) -> Result<i64, CsvError>` that treats `lines[0]` as a header and sums the rest, propagating parse failures with `?`. Finally, print the error and walk its `source()` chain. Solution ```rust 1 use std::error::Error; 2 use std::fmt; 3 use std::num::ParseIntError; 4 5 #[derive(Debug)] 6 enum CsvError { 7 BadHeader { expected: usize, found: usize }, 8 BadCell { row: usize, source: ParseIntError }, 9 } 10 11 impl fmt::Display for CsvError { 12 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 13 match self { 14 CsvError::BadHeader { expected, found } => { 15 write!(f, "bad header: expected {expected} columns, found {found}") 16 } 17 CsvError::BadCell { row, .. } => { 18 write!(f, "could not parse integer in row {row}") 19 } 20 } 21 } 22 } 23 24 impl Error for CsvError { 25 fn source(&self) -> Option<&(dyn Error + 'static)> { 26 match self { 27 CsvError::BadCell { source, .. } => Some(source), 28 CsvError::BadHeader { .. } => None, 29 } 30 } 31 } 32 33 fn parse_row(row: usize, line: &str) -> Result<i64, CsvError> { 34 line.trim() 35 .parse() 36 .map_err(|source| CsvError::BadCell { row, source }) 37 } 38 39 fn sum_column(lines: &[&str]) -> Result<i64, CsvError> { 40 if lines.is_empty() { 41 return Err(CsvError::BadHeader { expected: 1, found: 0 }); 42 } 43 let mut total = 0; 44 for (i, line) in lines.iter().enumerate().skip(1) { 45 total += parse_row(i, line)?; 46 } 47 Ok(total) 48 } 49 50 fn report(result: Result<i64, CsvError>) { 51 match result { 52 Ok(total) => println!("total = {total}"), 53 Err(e) => { 54 print!("error: {e}"); 55 let mut src = e.source(); 56 while let Some(c) = src { 57 print!(" -> {c}"); 58 src = c.source(); 59 } 60 println!(); 61 } 62 } 63 } 64 65 fn main() { 66 report(sum_column(&["amount", "10", "20", "30"])); 67 report(sum_column(&["amount", "10", "oops", "30"])); 68 report(sum_column(&[])); 69 } ``` Output: ```text 1 total = 60 2 error: could not parse integer in row 2 -> invalid digit found in string 3 error: bad header: expected 1 columns, found 0 ``` Once this compiles, try replacing the hand-written `Display` and `Error` impls with thiserror’s `#[derive(Error)]` and `#[error("...")]`/`#[source]` attributes from [`anyhow` & `thiserror`](/08-error-handling/06-anyhow-thiserror/); the behavior is identical, with far less boilerplate. # The `Error` Trait > Rust's std::error::Error is a trait, not a class like TypeScript's Error: its Debug and Display bounds, the source() cause chain, and Box<dyn Error>. In TypeScript, `Error` is a runtime class you `throw`. In Rust, `std::error::Error` is a **trait** that custom error types opt into so they can be reported uniformly, chained to their underlying cause, and boxed behind a single return type. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) The standard-library trait `std::error::Error` is Rust’s answer to “what does it mean to be an error?” Any type that implements it can be displayed to a user, inspected by a developer, and asked for the cause beneath it via `source()`. Because it is a trait, you can erase the concrete type behind `Box<dyn Error>` and let a function return *any* error, much like a TypeScript function can `throw` any value. > **Note:** This file focuses on the `Error` trait itself: its `Display + Debug` super-traits, the `source()` cause chain, and `Box<dyn Error>`. Defining your own error enums and structs is covered in [Custom Errors](/08-error-handling/04-custom-errors/); the ergonomic crates that generate these impls for you live in [anyhow & thiserror](/08-error-handling/06-anyhow-thiserror/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // TypeScript: Error is a class. Subclass it to make domain errors. 2 class ConfigError extends Error { 3 constructor( 4 public key: string, 5 message: string, 6 // `cause` standardized in ES2022 / Node 16.9+ 7 options?: { cause?: unknown }, 8 ) { 9 super(message, options); 10 this.name = "ConfigError"; 11 } 12 } 13 14 function parsePort(raw: string): number { 15 const port = Number(raw); 16 if (!Number.isInteger(port) || port < 1 || port > 65535) { 17 // Wrap the lower-level reason as `cause` so it isn't lost. 18 throw new ConfigError("PORT", `invalid port: ${raw}`, { 19 cause: new RangeError("expected 1..=65535"), 20 }); 21 } 22 return port; 23 } 24 25 try { 26 parsePort("not-a-number"); 27 } catch (e) { 28 if (e instanceof Error) { 29 console.log(e.message); // user-facing string 30 console.log(e.stack); // developer-facing detail 31 console.log(e.cause); // the wrapped underlying error 32 } 33 } ``` Three things to notice, because they map almost one-to-one onto Rust: * `Error` has a **`message`** (human-readable) and a **`stack`/`name`** (developer detail). * ES2022 added **`cause`** so a high-level error can point at the low-level one that triggered it. * You can `throw` *any* error subclass and catch it as the common `Error` base type. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 use std::error::Error; 2 use std::fmt; 3 4 // A custom error type for parsing a config value. 5 #[derive(Debug)] // Debug is REQUIRED by the Error trait. 6 struct ConfigError { 7 key: String, 8 message: String, 9 } 10 11 // Display is also REQUIRED: this is the user-facing message. 12 impl fmt::Display for ConfigError { 13 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 14 write!(f, "config error for key `{}`: {}", self.key, self.message) 15 } 16 } 17 18 // Opt in to the Error trait. With Display + Debug in place, the body is empty: 19 // the default `source()` returns None (no underlying cause yet). 20 impl Error for ConfigError {} 21 22 fn load_port() -> Result<u16, ConfigError> { 23 Err(ConfigError { 24 key: "PORT".to_string(), 25 message: "expected a number between 1 and 65535".to_string(), 26 }) 27 } 28 29 fn main() { 30 match load_port() { 31 Ok(port) => println!("listening on {port}"), 32 Err(e) => { 33 println!("Display: {e}"); // the {} / Display form 34 println!("Debug: {e:?}"); // the {:?} / Debug form 35 } 36 } 37 } ``` Real output: ```text 1 Display: config error for key `PORT`: expected a number between 1 and 65535 2 Debug: ConfigError { key: "PORT", message: "expected a number between 1 and 65535" } ``` The trait’s full definition in the standard library is essentially: ```rust 1 // From the standard library (simplified). 2 pub trait Error: Debug + Display { 3 fn source(&self) -> Option<&(dyn Error + 'static)> { 4 None // default: "I have no underlying cause" 5 } 6 // (a few more provided methods, all with defaults) 7 } ``` *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The two super-traits: `Debug` and `Display` [Section titled “The two super-traits: Debug and Display”](#the-two-super-traits-debug-and-display) The trait declaration is `pub trait Error: Debug + Display`. The `: Debug + Display` part means **you cannot implement `Error` for a type unless that type also implements `Debug` and `Display`**. These are *super-trait bounds*, and they encode two distinct audiences: | Trait | Format string | Audience | TypeScript analogy | | --------- | ------------- | --------- | ------------------------------- | | `Display` | `{}` | End user | `error.message` | | `Debug` | `{:?}` | Developer | `console.log(error)` / `.stack` | * **`Display`** is what you show a user or write to a log line. You write it by hand with `impl fmt::Display`. There is no derive for it, on purpose: a good user-facing message requires human judgment. * **`Debug`** is the developer view, almost always produced with `#[derive(Debug)]`. It prints the struct’s fields verbatim. > **Tip:** When `main` returns `Result<(), E>` and exits with an error, Rust prints the error using its **`Debug`** representation, not `Display`. That is a deliberate choice: `main` is a developer context. We’ll see this below. ### `write!` and the `Formatter` [Section titled “write! and the Formatter”](#write-and-the-formatter) The `Display` impl receives a `Formatter` and uses the `write!` macro, which behaves like `println!` but targets the formatter instead of stdout. Returning `fmt::Result` (an alias for `Result<(), fmt::Error>`) lets the `?`-style propagation inside `write!` work. You almost never construct `fmt::Error` yourself; just `write!(...)` and return its result. ### `source()`: the cause chain [Section titled “source(): the cause chain”](#source-the-cause-chain) `source()` is the Rust counterpart to ES2022’s `error.cause`. It returns `Option<&(dyn Error + 'static)>`: * `None` — “I am the root cause” (the default). * `Some(&inner)` — “I was caused by `inner`, which is itself some `dyn Error`.” By returning a *trait object* (`&dyn Error`), the chain is heterogeneous: each link can be a completely different concrete error type, yet you can walk the whole chain uniformly. Here is a high-level error that wraps a standard-library `ParseIntError`: ```rust 1 use std::error::Error; 2 use std::fmt; 3 use std::num::ParseIntError; 4 5 // High-level error that WRAPS a lower-level cause. 6 #[derive(Debug)] 7 struct ConfigError { 8 key: String, 9 source: ParseIntError, // the underlying cause 10 } 11 12 impl fmt::Display for ConfigError { 13 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 14 // NOTE: do NOT repeat the source's message here; source() exposes it. 15 write!(f, "invalid value for config key `{}`", self.key) 16 } 17 } 18 19 impl Error for ConfigError { 20 fn source(&self) -> Option<&(dyn Error + 'static)> { 21 Some(&self.source) // hand back the cause 22 } 23 } 24 25 fn parse_port(raw: &str) -> Result<u16, ConfigError> { 26 raw.parse::<u16>().map_err(|e| ConfigError { 27 key: "PORT".to_string(), 28 source: e, 29 }) 30 } 31 32 // Walk and print the full chain of causes. 33 fn print_chain(err: &dyn Error) { 34 eprintln!("error: {err}"); 35 let mut cause = err.source(); 36 while let Some(e) = cause { 37 eprintln!(" caused by: {e}"); 38 cause = e.source(); 39 } 40 } 41 42 fn main() { 43 if let Err(e) = parse_port("not-a-number") { 44 print_chain(&e); 45 } 46 } ``` Real output (written to stderr): ```text 1 error: invalid value for config key `PORT` 2 caused by: invalid digit found in string ``` The `print_chain` loop is the canonical pattern: print the top error, then follow `source()` link by link until it returns `None`. The `anyhow` crate and reporting tools like `eyre` do exactly this for you, but the trait is what makes it possible. > **Note:** Each `Display` impl should describe only **its own layer**. `ConfigError` says “invalid value for config key `PORT`”; the `ParseIntError` underneath says “invalid digit found in string”. The chain printer joins them. If every layer re-printed its source, you would get duplicated, noisy messages. ### `Box<dyn Error>`: type erasure for errors [Section titled “Box\<dyn Error>: type erasure for errors”](#boxdyn-error-type-erasure-for-errors) A function that can fail in several unrelated ways would otherwise need a single enum covering every case. `Box<dyn Error>` sidesteps that: it is a **heap-allocated trait object** that can hold *any* type implementing `Error`. This is the closest Rust gets to TypeScript’s “throw anything, catch as `Error`.” ```rust 1 use std::error::Error; 2 use std::fs; 3 4 // Box<dyn Error> = "some error type, decided at runtime". 5 // The ? operator converts each concrete error into the boxed trait object 6 // via the blanket `impl<E: Error + 'static> From<E> for Box<dyn Error>`. 7 fn read_config(path: &str) -> Result<u16, Box<dyn Error>> { 8 let contents = fs::read_to_string(path)?; // io::Error -> Box<dyn Error> 9 let port: u16 = contents.trim().parse()?; // ParseIntError -> Box<dyn Error> 10 Ok(port) 11 } 12 13 fn main() -> Result<(), Box<dyn Error>> { 14 // This path does not exist, so read_to_string fails. 15 let port = read_config("does-not-exist.toml")?; 16 println!("port = {port}"); 17 Ok(()) 18 } ``` Running this prints (and the process exits with status `1`): ```text 1 Error: Os { code: 2, kind: NotFound, message: "No such file or directory" } ``` Two things just happened automatically: 1. **`?` converted both error types** — `std::io::Error` and `std::num::ParseIntError` — into the same `Box<dyn Error>`. There is a blanket `From` impl in the standard library: any `E: Error + 'static` (and, for the thread-safe form, any `E: Error + Send + Sync + 'static`) can become a `Box<dyn Error>`. The `'static` bound is mandatory. The mechanics of that conversion are covered in [The `?` Operator](/08-error-handling/01-question-mark/). 2. **`main` printed the error with `Debug`** (note the `Os { code: 2, ... }` struct form), not `Display`, as mentioned above. ### Recovering the concrete type with `downcast` [Section titled “Recovering the concrete type with downcast”](#recovering-the-concrete-type-with-downcast) Type erasure is not a one-way door. Because `dyn Error` carries enough type information, you can attempt to recover the original concrete type with `downcast_ref` — the Rust analog of `e instanceof ConfigError`: ```rust 1 use std::error::Error; 2 use std::fmt; 3 4 #[derive(Debug)] 5 struct NotFound { 6 id: u64, 7 } 8 9 impl fmt::Display for NotFound { 10 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 11 write!(f, "user {} not found", self.id) 12 } 13 } 14 impl Error for NotFound {} 15 16 fn lookup(id: u64) -> Result<String, Box<dyn Error>> { 17 Err(Box::new(NotFound { id })) 18 } 19 20 fn main() { 21 if let Err(e) = lookup(42) { 22 // Try to recover the concrete type behind the trait object. 23 if let Some(nf) = e.downcast_ref::<NotFound>() { 24 println!("recovered: missing id = {}", nf.id); 25 } else { 26 println!("some other error: {e}"); 27 } 28 } 29 } ``` Real output: ```text 1 recovered: missing id = 42 ``` `downcast_ref::<T>()` returns `Some(&T)` if the trait object really holds a `T`, and `None` otherwise, exactly like a checked cast. There is also `downcast` (consuming, returns `Result<Box<T>, Box<dyn Error>>`) and `downcast_mut`. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / JavaScript | Rust | | --------------------- | --------------------------------------- | ---------------------------------------------------------- | | What “error” *is* | The `Error` **class** (and subclasses) | The `std::error::Error` **trait** (opt-in for any type) | | User message | `error.message` (always present) | `Display` impl (`{}`) — you write it | | Developer detail | `error.stack`, `error.name` | `Debug` impl (`{:?}`) — usually derived | | Underlying cause | `error.cause` (ES2022) | `source()` returning `Option<&dyn Error>` | | ”Throw anything” | `throw` any value | `Box<dyn Error>` (a boxed trait object) | | Recover concrete type | `e instanceof Foo` | `e.downcast_ref::<Foo>()` | | Stack trace | Captured automatically on `new Error()` | **Not** captured by `Error`; needs a backtrace (see below) | | Cost | Always allocates + captures stack | Zero-cost until you choose to `Box` or capture a backtrace | ### Why a trait and not a base class? [Section titled “Why a trait and not a base class?”](#why-a-trait-and-not-a-base-class) Rust has no inheritance. Instead of *extending* a base `Error` class, your type *implements* a trait — and it can implement many traits at once. This is closer to TypeScript’s structural `interface`, except the implementation is explicit (`impl Error for ConfigError {}`) and checked at compile time. See [Section 09: Generics & Traits](/09-generics-traits/) for the full mental model of traits vs. interfaces and inheritance. ### No automatic stack traces [Section titled “No automatic stack traces”](#no-automatic-stack-traces) The biggest surprise for TypeScript developers: constructing a Rust error does **not** capture a stack trace. JavaScript’s `new Error()` always snapshots the call stack (a cost you pay even when you catch and ignore it). Rust errors are plain values — often zero-allocation — and a backtrace is captured only if you opt in (for example, `std::backtrace::Backtrace::capture()` in a field, gated by the `RUST_BACKTRACE` env var, or via `anyhow`). The `source()` chain is Rust’s lightweight substitute for “where did this come from.” *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Implementing `Error` without `Display` and `Debug` [Section titled “Pitfall 1: Implementing Error without Display and Debug”](#pitfall-1-implementing-error-without-display-and-debug) A TypeScript developer expects `class MyError extends Error {}` to just work. In Rust, opting into `Error` *requires* the two super-traits first: ```rust 1 use std::error::Error; 2 3 struct MyError; // does not compile (E0277: missing Display + Debug) 4 5 impl Error for MyError {} 6 7 fn main() { 8 let _e = MyError; 9 } ``` The real compiler error (`cargo build`): ```text 1 error[E0277]: `MyError` doesn't implement `std::fmt::Display` 2 --> src/main.rs:5:16 3 | 4 5 | impl Error for MyError {} 5 | ^^^^^^^ the trait `std::fmt::Display` is not implemented for `MyError` 6 | 7 note: required by a bound in `std::error::Error` 8 ... 9 53 | pub trait Error: Debug + Display { 10 | ^^^^^^^ required by this bound in `Error` 11 12 error[E0277]: `MyError` doesn't implement `Debug` 13 --> src/main.rs:5:16 14 | 15 5 | impl Error for MyError {} 16 | ^^^^^^^ the trait `Debug` is not implemented for `MyError` 17 | 18 = note: add `#[derive(Debug)]` to `MyError` or manually `impl Debug for MyError` 19 ... 20 help: consider annotating `MyError` with `#[derive(Debug)]` 21 | 22 3 + #[derive(Debug)] 23 4 | struct MyError; 24 | ``` **Fix:** add `#[derive(Debug)]` and write an `impl fmt::Display`. Note how precisely the compiler points at the missing bounds. This is the norm, not the exception. ### Pitfall 2: `Box<dyn Error>` cannot cross a thread boundary [Section titled “Pitfall 2: Box\<dyn Error> cannot cross a thread boundary”](#pitfall-2-boxdyn-error-cannot-cross-a-thread-boundary) `Box<dyn Error>` is **not** `Send`, so returning it from a spawned thread fails to compile. TypeScript has no equivalent restriction because everything runs on one event loop. ```rust 1 use std::error::Error; 2 use std::thread; 3 4 fn work() -> Result<(), Box<dyn Error>> { 5 Err("boom".into()) 6 } 7 8 fn main() { 9 // does not compile (E0277: `dyn Error` cannot be sent between threads safely) 10 let handle = thread::spawn(|| -> Result<(), Box<dyn Error>> { 11 work() 12 }); 13 let _ = handle.join(); 14 } ``` The real error (`cargo build`, abridged): ```text 1 error[E0277]: `dyn std::error::Error` cannot be sent between threads safely 2 --> src/main.rs:9:18 3 | 4 9 | let handle = thread::spawn(|| -> Result<(), Box<dyn Error>> { 5 | __________________^ 6 | |______^ `dyn std::error::Error` cannot be sent between threads safely 7 | 8 = help: the trait `Send` is not implemented for `dyn std::error::Error` 9 ... 10 note: required by a bound in `spawn` ``` **Fix:** use the thread-safe alias `Box<dyn Error + Send + Sync>`: ```rust 1 use std::error::Error; 2 use std::thread; 3 4 // The thread-safe boxed error alias. 5 type BoxError = Box<dyn Error + Send + Sync>; 6 7 fn work() -> Result<(), BoxError> { 8 Err("boom".into()) // &str -> Box<dyn Error + Send + Sync> via From 9 } 10 11 fn main() { 12 let handle = thread::spawn(|| -> Result<(), BoxError> { work() }); 13 match handle.join().unwrap() { 14 Ok(()) => println!("ok"), 15 Err(e) => println!("worker failed: {e}"), 16 } 17 } ``` Real output: ```text 1 worker failed: boom ``` > **Tip:** `Box<dyn Error + Send + Sync + 'static>` is the form `anyhow::Error` uses internally and the one most application code should reach for. The `+ Send + Sync` makes it usable across threads and inside async tasks. ### Pitfall 3: duplicating the cause in your `Display` message [Section titled “Pitfall 3: duplicating the cause in your Display message”](#pitfall-3-duplicating-the-cause-in-your-display-message) Because `source()` already exposes the inner error, *also* baking it into your `Display` string produces double-printed messages once a chain printer (or `anyhow`) walks the chain. Keep each layer’s `Display` to its own concern, and let `source()` carry the rest. ### Pitfall 4: expecting a stack trace from `{:?}` [Section titled “Pitfall 4: expecting a stack trace from {:?}”](#pitfall-4-expecting-a-stack-trace-from-) `{:?}` prints the *struct fields*, not a stack trace. If you `#[derive(Debug)]` a `ConfigError`, you get `ConfigError { key: "PORT", ... }`, never a call stack. To get backtraces, add a `std::backtrace::Backtrace` field, or use `anyhow` (which captures one when `RUST_BACKTRACE=1`). *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Derive `Debug`, hand-write `Display`.** `#[derive(Debug)]` is correct for nearly every error type; the `Display` message deserves a human’s wording. * **Implement `source()` whenever you wrap a lower-level error.** It preserves the cause chain and is what reporting tooling relies on. Return `Some(&self.inner)`. * **Prefer `Box<dyn Error + Send + Sync>` over a bare `Box<dyn Error>`** in application code and anything touching threads or async. It is a one-character-heavier alias that avoids Pitfall 2 entirely. * **Reach for `Box<dyn Error>` in application/`main` code; reach for a concrete enum in libraries.** Library callers want to `match` on specific variants (which a boxed trait object hides). Applications usually just want to report and exit. This library-vs-application split is a recurring theme across this section’s error-handling topics. * **Don’t hand-roll the boilerplate in real projects.** The `thiserror` crate derives `Display`, `Error`, and `From`/`source()` wiring for you; `anyhow` provides a ready-made `Box<dyn Error + Send + Sync>` replacement with backtraces and context. See [anyhow & thiserror](/08-error-handling/06-anyhow-thiserror/). Understanding the trait first (this file) is what makes those crates feel obvious instead of magical. * **Write a small `report(&dyn Error)` chain printer** (like the one above) for binaries that don’t pull in `anyhow`. It is a dozen lines and turns one-line errors into useful diagnostics. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A price-feed loader that parses lines like `AAPL,189.95`. The domain error carries a human-readable message *and* keeps the lower-level cause reachable through `source()`, so a single reporting helper can print the full diagnostic chain. ```rust 1 use std::error::Error; 2 use std::fmt; 3 use std::num::ParseFloatError; 4 5 /// Domain error for the price-feed loader. It carries a human-readable 6 /// context AND keeps the lower-level cause reachable via `source()`. 7 #[derive(Debug)] 8 struct PriceFeedError { 9 symbol: String, 10 kind: PriceFeedErrorKind, 11 } 12 13 #[derive(Debug)] 14 enum PriceFeedErrorKind { 15 /// The raw line could not be split into the expected fields. 16 Malformed, 17 /// The price field was present but not a valid number. 18 BadPrice(ParseFloatError), 19 } 20 21 impl fmt::Display for PriceFeedError { 22 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 23 match &self.kind { 24 PriceFeedErrorKind::Malformed => { 25 write!(f, "malformed record for symbol `{}`", self.symbol) 26 } 27 PriceFeedErrorKind::BadPrice(_) => { 28 write!(f, "invalid price for symbol `{}`", self.symbol) 29 } 30 } 31 } 32 } 33 34 impl Error for PriceFeedError { 35 fn source(&self) -> Option<&(dyn Error + 'static)> { 36 match &self.kind { 37 // Only BadPrice has an underlying cause to expose. 38 PriceFeedErrorKind::BadPrice(e) => Some(e), 39 PriceFeedErrorKind::Malformed => None, 40 } 41 } 42 } 43 44 fn parse_quote(line: &str) -> Result<(String, f64), PriceFeedError> { 45 let (symbol, raw_price) = line.split_once(',').ok_or_else(|| PriceFeedError { 46 symbol: line.to_string(), 47 kind: PriceFeedErrorKind::Malformed, 48 })?; 49 50 let price = raw_price.trim().parse::<f64>().map_err(|e| PriceFeedError { 51 symbol: symbol.to_string(), 52 kind: PriceFeedErrorKind::BadPrice(e), 53 })?; 54 55 Ok((symbol.to_string(), price)) 56 } 57 58 /// Reusable helper: print an error and every cause beneath it. 59 fn report(err: &dyn Error) { 60 eprintln!("error: {err}"); 61 let mut source = err.source(); 62 while let Some(cause) = source { 63 eprintln!(" caused by: {cause}"); 64 source = cause.source(); 65 } 66 } 67 68 fn main() { 69 let inputs = ["AAPL,189.95", "TSLA,not-a-price", "BROKENLINE"]; 70 for line in inputs { 71 match parse_quote(line) { 72 Ok((symbol, price)) => println!("{symbol}: {price:.2}"), 73 Err(e) => report(&e), 74 } 75 } 76 } ``` Real output (stdout and stderr interleaved): ```text 1 AAPL: 189.95 2 error: invalid price for symbol `TSLA` 3 caused by: invalid float literal 4 error: malformed record for symbol `BROKENLINE` ``` Notice that `Malformed` returns `None` from `source()` (no inner cause to show), while `BadPrice` exposes the standard-library `ParseFloatError`: the same trait, two different shapes of chain, one reporting function that handles both. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`std::error::Error` — standard library docs](https://doc.rust-lang.org/std/error/trait.Error.html) * [`std::fmt::Display`](https://doc.rust-lang.org/std/fmt/trait.Display.html) and [`std::fmt::Debug`](https://doc.rust-lang.org/std/fmt/trait.Debug.html) * [`Box<dyn Error>` and the `From` conversion](https://doc.rust-lang.org/std/boxed/struct.Box.html#impl-From%3CE%3E-for-Box%3Cdyn+Error%3E) * [`std::backtrace::Backtrace`](https://doc.rust-lang.org/std/backtrace/struct.Backtrace.html): opt-in stack traces * [The Rust Book: “Defining an Error Type”](https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html) Related sections in this guide: * [Result & Option](/08-error-handling/00-result-option/): the values that carry these errors * [The `?` Operator](/08-error-handling/01-question-mark/): how errors get *converted* into `Box<dyn Error>` automatically * [Custom Errors](/08-error-handling/04-custom-errors/): defining error enums and structs (the impls shown here, by hand) * [Multiple Error Types](/08-error-handling/07-multiple-errors/): aggregating many error types behind one return type * [anyhow & thiserror](/08-error-handling/06-anyhow-thiserror/): crates that generate these impls for you * [Section 09: Generics & Traits](/09-generics-traits/) — traits, trait objects, and `dyn` in depth * [Section 05: Ownership](/05-ownership/) — why `Box` and lifetimes (`'static`) appear in these signatures *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1 [Section titled “Exercise 1”](#exercise-1) **Difficulty:** Beginner **Objective:** Implement the `Error` trait from scratch for a simple type. **Instructions:** Define a unit struct `EmptyInputError` and make it a valid `std::error::Error`. It must print `input was empty` via `Display`. Then write `first_char(s: &str) -> Result<char, EmptyInputError>` that returns the error when the string is empty. ```rust 1 use std::error::Error; 2 use std::fmt; 3 4 struct EmptyInputError; // TODO: derive Debug + impl Display + impl Error 5 6 fn first_char(s: &str) -> Result<char, EmptyInputError> { 7 /* ??? */ 8 } 9 10 fn main() { 11 println!("{:?}", first_char("rust")); 12 match first_char("") { 13 Ok(c) => println!("got {c}"), 14 Err(e) => println!("error: {e}"), 15 } 16 } ``` Solution ```rust 1 use std::error::Error; 2 use std::fmt; 3 4 #[derive(Debug)] 5 struct EmptyInputError; 6 7 impl fmt::Display for EmptyInputError { 8 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 9 write!(f, "input was empty") 10 } 11 } 12 13 impl Error for EmptyInputError {} 14 15 fn first_char(s: &str) -> Result<char, EmptyInputError> { 16 s.chars().next().ok_or(EmptyInputError) 17 } 18 19 fn main() { 20 println!("{:?}", first_char("rust")); 21 match first_char("") { 22 Ok(c) => println!("got {c}"), 23 Err(e) => println!("error: {e}"), 24 } 25 } ``` Output: ```text 1 Ok('r') 2 error: input was empty ``` ### Exercise 2 [Section titled “Exercise 2”](#exercise-2) **Difficulty:** Intermediate **Objective:** Wrap a lower-level error and expose it through `source()`. **Instructions:** Define `EnvError { var: String, source: ParseIntError }`. Implement `Display` (mention only the variable name, not the parse detail) and `Error` with a working `source()`. Write `read_retries(raw: &str) -> Result<u32, EnvError>` that wraps a failed `parse::<u32>()`. Finally, write a *generic* function `print_chain<E: Error>(err: &E)` that prints the error and every cause beneath it. Solution ```rust 1 use std::error::Error; 2 use std::fmt; 3 use std::num::ParseIntError; 4 5 #[derive(Debug)] 6 struct EnvError { 7 var: String, 8 source: ParseIntError, 9 } 10 11 impl fmt::Display for EnvError { 12 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 13 write!(f, "environment variable `{}` is not a valid integer", self.var) 14 } 15 } 16 17 impl Error for EnvError { 18 fn source(&self) -> Option<&(dyn Error + 'static)> { 19 Some(&self.source) 20 } 21 } 22 23 fn read_retries(raw: &str) -> Result<u32, EnvError> { 24 raw.parse::<u32>().map_err(|e| EnvError { 25 var: "MAX_RETRIES".to_string(), 26 source: e, 27 }) 28 } 29 30 // Generic over any error type. 31 fn print_chain<E: Error>(err: &E) { 32 println!("error: {err}"); 33 let mut cause: Option<&dyn Error> = err.source(); 34 while let Some(e) = cause { 35 println!(" caused by: {e}"); 36 cause = e.source(); 37 } 38 } 39 40 fn main() { 41 if let Err(e) = read_retries("five") { 42 print_chain(&e); 43 } 44 } ``` Output: ```text 1 error: environment variable `MAX_RETRIES` is not a valid integer 2 caused by: invalid digit found in string ``` ### Exercise 3 [Section titled “Exercise 3”](#exercise-3) **Difficulty:** Advanced **Objective:** Erase an error behind `Box<dyn Error>`, collect its full chain, then recover the concrete type with `downcast_ref`. **Instructions:** Reuse a wrapping error `ParseRecordError { line: usize, source: ParseIntError }` (Debug + Display + Error with `source()`). Write `chain_messages(err: &dyn Error) -> Vec<String>` that returns the top error message followed by each cause’s message. In `main`, box the error as `Box<dyn Error>`, print the collected chain, then use `downcast_ref::<ParseRecordError>()` to recover and print the offending `line` number. Solution ```rust 1 use std::error::Error; 2 use std::fmt; 3 use std::num::ParseIntError; 4 5 #[derive(Debug)] 6 struct ParseRecordError { 7 line: usize, 8 source: ParseIntError, 9 } 10 11 impl fmt::Display for ParseRecordError { 12 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 13 write!(f, "failed to parse record on line {}", self.line) 14 } 15 } 16 17 impl Error for ParseRecordError { 18 fn source(&self) -> Option<&(dyn Error + 'static)> { 19 Some(&self.source) 20 } 21 } 22 23 // Collect the full chain (top error + every cause) into owned strings. 24 fn chain_messages(err: &dyn Error) -> Vec<String> { 25 let mut msgs = vec![err.to_string()]; 26 let mut cause = err.source(); 27 while let Some(e) = cause { 28 msgs.push(e.to_string()); 29 cause = e.source(); 30 } 31 msgs 32 } 33 34 fn parse(line: usize, raw: &str) -> Result<i64, ParseRecordError> { 35 raw.parse::<i64>().map_err(|e| ParseRecordError { line, source: e }) 36 } 37 38 fn main() { 39 let err = parse(7, "1.5").unwrap_err(); 40 let boxed: Box<dyn Error> = Box::new(err); 41 42 // 1. Full chain as strings. 43 println!("{:?}", chain_messages(boxed.as_ref())); 44 45 // 2. Recover the concrete top-level type. 46 if let Some(pre) = boxed.downcast_ref::<ParseRecordError>() { 47 println!("offending line: {}", pre.line); 48 } 49 } ``` Output: ```text 1 ["failed to parse record on line 7", "invalid digit found in string"] 2 offending line: 7 ``` > **Note:** `err.to_string()` works because anything implementing `Display` automatically gets `ToString` via a blanket impl in the standard library, the same mechanism that gives `Error` types a free `.to_string()`. # `anyhow` & `thiserror` > thiserror derives Display, Error, and From for typed library errors; anyhow gives apps one error type with context, versus TS's untyped throw. Writing `Display`, `Debug`, `Error`, and `From` impls by hand for every error type gets tedious fast. The `thiserror` and `anyhow` crates are the community-standard answer: `thiserror` **derives** those impls for your library’s typed errors, and `anyhow` gives applications one ergonomic error type with rich context. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In TypeScript you `throw` anything and rarely think about error *types*; every catch block just gets an `Error` (or `unknown`). Rust pushes you to be explicit, and these two crates make that explicitness cheap. Use **`thiserror`** when you are writing a **library** and want callers to be able to `match` on specific failure variants; use **`anyhow`** when you are writing an **application** and just want to attach context and propagate any error to `main`. They are designed to work together: a library defines a `thiserror` enum, and the application that consumes it wraps everything in `anyhow`. > **Note:** This file covers the two crates and their current APIs. Defining error types *by hand* (without `thiserror`) is covered in [Custom Errors](/08-error-handling/04-custom-errors/) and [The `Error` Trait](/08-error-handling/05-error-trait/); the `?` operator that ties it all together is in [The `?` Operator](/08-error-handling/01-question-mark/); and the higher-level “which one, when?” decision lives in [Best Practices](/08-error-handling/08-best-practices/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript, distinguishing error kinds means subclassing `Error` (verbose) or, more commonly, tagging plain objects with a discriminant and checking it at the catch site. Adding context usually means re-throwing a new error whose `cause` points at the original. ```typescript 1 // A "library" module: it defines its own error kinds so callers can branch. 2 class ConfigError extends Error { 3 readonly kind: "not-found" | "invalid-port" | "missing-key"; 4 constructor(kind: ConfigError["kind"], message: string, options?: { cause?: unknown }) { 5 super(message, options); 6 this.name = "ConfigError"; 7 this.kind = kind; 8 } 9 } 10 11 function parsePort(raw: string): number { 12 const port = Number(raw); 13 if (!Number.isInteger(port)) { 14 // Re-wrap the low-level reason as `cause` so it isn't lost. 15 throw new ConfigError("invalid-port", "invalid port number", { 16 cause: new TypeError(`'${raw}' is not an integer`), 17 }); 18 } 19 return port; 20 } 21 22 // An "application" layer: it adds context and ultimately just reports. 23 function loadServerConfig(raw: string): number { 24 try { 25 return parsePort(raw); 26 } catch (e) { 27 // Attaching context = throw a new error pointing at the old one. 28 throw new Error(`while loading server config from '${raw}'`, { cause: e }); 29 } 30 } 31 32 try { 33 loadServerConfig("not-a-number"); 34 } catch (e) { 35 if (e instanceof Error) { 36 // Walk the cause chain manually. 37 let msg = e.message; 38 let cur = e.cause; 39 while (cur instanceof Error) { 40 msg += `: ${cur.message}`; 41 cur = cur.cause; 42 } 43 console.log(msg); // while loading server config from 'not-a-number': invalid port number: ... 44 } 45 // To branch on the *kind*, you must downcast manually: 46 if (e instanceof ConfigError && e.kind === "invalid-port") { 47 // handle specifically 48 } 49 } ``` Two jobs are tangled together here, and TypeScript gives you no help separating them: * **The library job:** define distinguishable error *kinds* (the `kind` discriminant). * **The application job:** add human-readable context and walk the cause chain. Rust splits these cleanly across two crates. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ### `thiserror` for the library layer [Section titled “thiserror for the library layer”](#thiserror-for-the-library-layer) ```rust 1 use thiserror::Error; 2 3 // One derive generates Display, Error, source(), and From impls. 4 #[derive(Debug, Error)] 5 pub enum ConfigError { 6 #[error("config file not found at `{0}`")] 7 NotFound(String), 8 9 // `#[from]` generates `From<ParseIntError>` AND wires up `source()`. 10 #[error("invalid port number")] 11 InvalidPort(#[from] std::num::ParseIntError), 12 13 // Named fields are interpolated by name in the message string. 14 #[error("missing required key `{key}`")] 15 MissingKey { key: String }, 16 } 17 18 fn parse_port(raw: &str) -> Result<u16, ConfigError> { 19 // `?` converts ParseIntError -> ConfigError via the derived `From`. 20 let port: u16 = raw.parse()?; 21 Ok(port) 22 } ``` ### `anyhow` for the application layer [Section titled “anyhow for the application layer”](#anyhow-for-the-application-layer) ```rust 1 use anyhow::{Context, Result}; 2 3 // `anyhow::Result<T>` is shorthand for `Result<T, anyhow::Error>`. 4 fn read_config(path: &str) -> Result<String> { 5 std::fs::read_to_string(path) 6 // `.with_context` adds a human-readable layer; the original error 7 // becomes the *source* beneath it. 8 .with_context(|| format!("could not read config file `{path}`")) 9 } 10 11 fn main() -> Result<()> { 12 let _contents = read_config("/no/such/config.toml")?; 13 Ok(()) 14 } ``` Running that `main` prints a formatted report and exits non-zero. Verified output: ```text 1 Error: could not read config file `/no/such/config.toml` 2 3 Caused by: 4 No such file or directory (os error 2) ``` The library code (`thiserror`) produces a precise enum a caller can `match` on; the application code (`anyhow`) attaches context and lets `?` and `main` do the reporting. No hand-written `impl Display`, no hand-written `impl Error`, no manual cause-chain walking. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Setting up the crates [Section titled “Setting up the crates”](#setting-up-the-crates) Both are ordinary dependencies. From your project directory: ```bash 1 cargo add anyhow thiserror ``` ```text 1 Adding anyhow v1.0.102 to dependencies 2 Adding thiserror v2.0.18 to dependencies 3 Locking 7 packages to latest Rust 1.96.0 compatible versions ``` > **Note:** `cargo add` is built into Cargo (since 1.62); you do **not** need the old `cargo-edit` crate. This guide uses **anyhow 1.x** (currently `1.0.102`) and **thiserror 2.x** (currently `2.0.18`), the latest stable releases. ### `thiserror`: a derive macro, not a runtime [Section titled “thiserror: a derive macro, not a runtime”](#thiserror-a-derive-macro-not-a-runtime) `#[derive(Error)]` is a **procedural macro** that, at compile time, writes the `impl std::fmt::Display`, `impl std::error::Error`, and any `impl From<...>` you requested. It adds **zero runtime cost and zero runtime dependency**: `thiserror` is purely a code generator. (This is unlike TypeScript decorators, which are real runtime function calls; see [Macros](/14-macros/) for why the two are fundamentally different.) The pieces of the derive: * **`#[derive(Debug, Error)]`**: `Error` requires `Debug` (the developer-facing form) and `Display` (the user-facing form). You always write `Debug` yourself via derive; `thiserror` writes `Display` for you from the `#[error(...)]` attribute. * **`#[error("...")]`**: the format string for `Display`. Positional tuple fields are `{0}`, `{1}`; named struct fields are `{field_name}`. The same `{}` formatting and inline-variable syntax you saw in [Output](/02-basics/04-output/) applies. * **`#[from]`** — on exactly one field of a variant, generates `From<ThatType> for YourError` so `?` can convert automatically, *and* makes that field the variant’s `source()`. * **`#[source]`** — marks a field as the `source()` (the underlying cause) **without** generating a `From` impl. Use it when you want the cause chain but the conversion would be ambiguous (e.g., two variants wrap the same error type). ### `anyhow`: one error type to rule the application [Section titled “anyhow: one error type to rule the application”](#anyhow-one-error-type-to-rule-the-application) `anyhow::Error` is a single, dynamically-typed error (think of it as a smarter `Box<dyn Error>`) that: * can be built from **any** type implementing `std::error::Error + Send + Sync + 'static` (via `?` or `.into()`), * carries a **chain** of contexts and causes you can iterate, * formats itself as a clean multi-line report, * can still be **downcast** back to a concrete type when you need to branch. The key trait is `Context`, which adds methods to *both* `Result` and `Option`: ```rust 1 use anyhow::{anyhow, bail, ensure, Context, Result}; 2 3 fn load_settings(raw: &str) -> Result<u16> { 4 let timeout: u16 = raw 5 .parse() 6 // `.with_context` is LAZY: the closure only runs on the error path. 7 .with_context(|| format!("failed to parse timeout from {raw:?}"))?; 8 9 // `ensure!` is like `assert!`, but returns Err instead of panicking. 10 ensure!(timeout > 0, "timeout must be greater than zero"); 11 Ok(timeout) 12 } 13 14 fn pick(raw: &str) -> Result<u16> { 15 if raw.is_empty() { 16 // `bail!` == `return Err(anyhow!(...))`. 17 bail!("no value provided"); 18 } 19 // `anyhow!` builds an ad-hoc error from a formatted message. 20 load_settings(raw).map_err(|e| anyhow!("pick failed: {e}")) 21 } ``` * **`anyhow!("...")`**: construct an error from a message (or wrap an existing error). * **`bail!("...")`**: early-return that error. * **`ensure!(cond, "...")`**: bail unless a condition holds. * **`.context(msg)`**: attach an **eager** message (computed even on the happy path; cheap for string literals). * **`.with_context(|| msg)`**: attach a **lazy** message (the closure runs only when there is actually an error; prefer this when the message requires a `format!` allocation). ### Reading the chain and recovering types [Section titled “Reading the chain and recovering types”](#reading-the-chain-and-recovering-types) `anyhow::Error` formats itself three ways, all verified: ```rust 1 use anyhow::{Context, Result}; 2 3 fn load(raw: &str) -> Result<u16> { 4 raw.parse::<u16>() 5 .with_context(|| format!("failed to parse timeout from {raw:?}")) 6 } 7 8 fn main() { 9 let e = load("abc").unwrap_err(); 10 println!("{e}"); // Display: just the top context 11 println!("{e:#}"); // alternate: single-line chain joined by ": " 12 for (i, cause) in e.chain().enumerate() { 13 println!("[{i}] {cause}"); // iterate top -> bottom 14 } 15 } ``` Output: ```text 1 failed to parse timeout from "abc" 2 failed to parse timeout from "abc": invalid digit found in string 3 [0] failed to parse timeout from "abc" 4 [1] invalid digit found in string ``` > **Tip:** `{e}` shows only the outermost message; `{e:#}` (alternate flag) shows the whole chain on one line; and when an `anyhow::Error` is returned from `main`, the `{e:?}` (Debug) form is used automatically, which is the multi-line `Caused by:` report you saw earlier. To branch on a specific concrete error after the fact, `downcast_ref`: ```rust 1 use anyhow::Result; 2 use thiserror::Error; 3 4 #[derive(Debug, Error)] 5 #[error("user {id} not found")] 6 struct UserNotFound { id: u32 } 7 8 fn find_user(id: u32) -> Result<String> { 9 if id != 42 { 10 return Err(UserNotFound { id }.into()); // typed error -> anyhow::Error 11 } 12 Ok("Ada".to_string()) 13 } 14 15 fn main() { 16 if let Err(e) = find_user(7) { 17 // Recover the original concrete type. 18 if let Some(unf) = e.downcast_ref::<UserNotFound>() { 19 println!("typed recovery: missing id {}", unf.id); 20 } 21 } 22 } ``` Output: ```text 1 typed recovery: missing id 7 ``` This is exactly the TypeScript `e instanceof ConfigError` pattern, except Rust checks the type at runtime through a real type identity, not a fragile prototype chain. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concern | TypeScript / JavaScript | `thiserror` (libraries) | `anyhow` (applications) | | ------------------------- | ---------------------------------- | ------------------------------------- | -------------------------------- | | Error type | One `Error` class (or `unknown`) | A concrete enum/struct **you** define | One opaque `anyhow::Error` | | Caller can `match`/branch | `instanceof` + manual discriminant | Yes, on enum variants | Only via `downcast_ref` | | Boilerplate | Subclass + set `name`/`cause` | `#[derive(Error)]` writes it all | Nothing to define | | Add context | `throw new Error(msg, { cause })` | (caller’s job) | `.context` / `.with_context` | | Auto-convert with `?` | `throw` accepts anything | `#[from]` generates `From` | absorbs any `Error` type | | Runtime cost | runtime classes | **zero** (compile-time codegen) | small heap allocation per error | | When to use | always (no choice) | public API surface | binaries, scripts, tests, `main` | The decision rule, in one sentence: **libraries return `thiserror` enums so their callers keep choices; applications use `anyhow` because they are the end of the line and only need to report.** > **Warning:** Do not put `anyhow::Error` in a *public library* return type. It erases the variants, so your library’s users can no longer `match` on what went wrong; they would be stuck with `downcast_ref` guesses. Reserve `anyhow` for the application that *consumes* libraries. More on this split in [Best Practices](/08-error-handling/08-best-practices/). A second key difference from TypeScript: in TS, `try { ... } catch (e) { switch (e.kind) }` is the only tool, and the compiler never checks that you covered every kind. With a `thiserror` enum, `match` is exhaustive: add a variant and every `match` that forgot it stops compiling. That is the same exhaustiveness you get from any Rust enum (see [Control Flow](/04-control-flow/)). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Trying to `match` directly on an `anyhow::Error` [Section titled “Pitfall 1: Trying to match directly on an anyhow::Error”](#pitfall-1-trying-to-match-directly-on-an-anyhowerror) Because `anyhow::Error` is opaque, you cannot pattern-match its “variants”; it has none. ```rust 1 use anyhow::{anyhow, Result}; 2 3 #[derive(Debug)] 4 enum MyError { TooBig, TooSmall } 5 6 fn check(n: i32) -> Result<()> { 7 if n > 100 { return Err(anyhow!("too big")); } 8 Ok(()) 9 } 10 11 fn main() { 12 if let Err(e) = check(200) { 13 // does not compile (error[E0308]: mismatched types) 14 match e { 15 MyError::TooBig => println!("big"), 16 MyError::TooSmall => println!("small"), 17 } 18 } 19 } ``` The real compiler error: ```text 1 error[E0308]: mismatched types 2 --> src/main.rs:15:13 3 | 4 4 | enum MyError { TooBig, TooSmall } 5 | ------ unit variant defined here 6 ... 7 14 | match e { 8 | - this expression has type `anyhow::Error` 9 15 | MyError::TooBig => println!("big"), 10 | ^^^^^^^^^^^^^^^ expected `Error`, found `MyError` ``` **Fix:** if you genuinely need to branch on kinds, your error should be a `thiserror` enum (not `anyhow`), or you recover the concrete type with `e.downcast_ref::<MyError>()`. ### Pitfall 2: Forgetting `#[from]`, then using `?` [Section titled “Pitfall 2: Forgetting #\[from\], then using ?”](#pitfall-2-forgetting-from-then-using-) A `thiserror` variant only converts automatically if you ask it to with `#[from]`. Without it, `?` has no `From` impl to use. ```rust 1 use thiserror::Error; 2 3 #[derive(Debug, Error)] 4 enum AppError { 5 #[error("parse failed")] 6 Parse(std::num::ParseIntError), // no #[from] 7 } 8 9 fn parse(s: &str) -> Result<i32, AppError> { 10 let n: i32 = s.parse()?; // tries ParseIntError -> AppError via From 11 Ok(n) 12 } ``` The real compiler error: ```text 1 error[E0271]: type mismatch resolving `<i32 as FromStr>::Err == AppError` 2 --> src/main.rs:10:20 3 | 4 10 | let n: i32 = s.parse()?; // tries ParseIntError -> AppError via From 5 | ^^^^^ expected `AppError`, found `ParseIntError` ``` **Fix:** add `#[from]` to the field — `Parse(#[from] std::num::ParseIntError)` — which generates the `From` impl that `?` needs. (The `?`/`From` relationship is the whole subject of [The `?` Operator](/08-error-handling/01-question-mark/).) ### Pitfall 3: `#[from]` on two variants wrapping the same type [Section titled “Pitfall 3: #\[from\] on two variants wrapping the same type”](#pitfall-3-from-on-two-variants-wrapping-the-same-type) You can only have **one** `From<T>` impl for a given `T`. Putting `#[from] std::io::Error` on two different variants creates conflicting impls and will not compile. **Fix:** keep `#[from]` on at most one variant per source type; mark the others with `#[source]` and construct them explicitly with `.map_err(...)`. Handling several overlapping error sources is covered in depth in [Multiple Error Types](/08-error-handling/07-multiple-errors/). ### Pitfall 4: `.context()` that allocates on the happy path [Section titled “Pitfall 4: .context() that allocates on the happy path”](#pitfall-4-context-that-allocates-on-the-happy-path) `.context(format!("..."))` builds the string **every time**, even when the `Result` is `Ok`. On a hot path that is wasted work. **Fix:** use `.with_context(|| format!("..."))` so the `format!` only runs on the error branch. Reserve the eager `.context("literal")` for cheap string literals. ### Pitfall 5: Expecting `thiserror::Error` to give you a stack trace [Section titled “Pitfall 5: Expecting thiserror::Error to give you a stack trace”](#pitfall-5-expecting-thiserrorerror-to-give-you-a-stack-trace) Unlike a JavaScript `Error`, which captures `.stack` automatically, a `thiserror` error carries only what you put in its fields: the message and its `source()`. There is no implicit backtrace. **Fix:** for backtraces in applications, enable `anyhow`’s `backtrace` feature and run with `RUST_BACKTRACE=1`; `anyhow::Error` captures one at creation. For libraries, expose the `source()` chain and let the application decide. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Libraries → `thiserror`; applications → `anyhow`.** This is the single most important rule. A crate published to crates.io should expose typed errors; a binary or service should funnel everything into `anyhow`. * **One error enum per module/layer is usually enough.** Over-splitting into dozens of tiny enums is as bad as one giant one. Granularity guidance lives in [Best Practices](/08-error-handling/08-best-practices/). * **Prefer `#[from]` for the common conversions** so `?` is frictionless, and `#[source]` when you need the cause chain without an automatic conversion. * **Add context at boundaries.** Wrap an error with `.with_context(...)` when it crosses a meaningful layer (“while reading config”, “while connecting to the database”), not on every line. * **Use `#[error(transparent)]` for pass-through variants.** It forwards `Display` and `source()` to the inner error so you do not invent a redundant message: ```rust 1 use thiserror::Error; 2 3 #[derive(Debug, Error)] 4 enum DataError { 5 #[error("record {index} is malformed")] 6 Malformed { index: usize }, 7 8 // No message of its own: delegates Display + source to the inner io::Error. 9 #[error(transparent)] 10 Io(#[from] std::io::Error), 11 } 12 13 fn first_line(path: &str) -> Result<String, DataError> { 14 let text = std::fs::read_to_string(path)?; // io::Error -> DataError::Io 15 let line = text.lines().next().ok_or(DataError::Malformed { index: 0 })?; 16 Ok(line.to_string()) 17 } 18 19 fn main() { 20 if let Err(e) = first_line("/definitely/missing.txt") { 21 println!("error: {e}"); // prints the io error's own message 22 } 23 } ``` Output: ```text 1 error: No such file or directory (os error 2) ``` * **Return `anyhow::Result<()>` from `main`** in binaries. The `?` operator then propagates anything, and Rust prints the `Caused by:` report and sets a non-zero exit code for free. * **`anyhow::Error` requires `Send + Sync + 'static`.** That is exactly what async runtimes and thread pools need (see [Async](/11-async/)), so it composes well with `tokio`. If a hand-rolled error type is not `Send + Sync`, `?` into an `anyhow::Result` will fail; derive your errors with `thiserror` and they will satisfy these bounds automatically. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A two-layer program: a `store` module is the “library” with a precise `thiserror` enum, and the application layer uses `anyhow` to add context, recover specific variants, and report the full chain. ```rust 1 // ---- "library" layer: precise, typed errors with thiserror ---- 2 mod store { 3 use thiserror::Error; 4 5 #[derive(Debug, Error)] 6 pub enum StoreError { 7 #[error("user {0} does not exist")] 8 NotFound(u32), 9 10 #[error("database is offline")] 11 Offline, 12 13 #[error("corrupt row")] 14 Corrupt(#[from] std::num::ParseIntError), 15 } 16 17 #[derive(Debug)] 18 pub struct User { 19 pub id: u32, 20 pub age: u32, 21 } 22 23 pub fn fetch(id: u32) -> Result<User, StoreError> { 24 match id { 25 0 => Err(StoreError::Offline), 26 42 => Ok(User { id, age: "thirty".parse()? }), // bad data -> Corrupt 27 7 => Ok(User { id, age: "30".parse()? }), 28 _ => Err(StoreError::NotFound(id)), 29 } 30 } 31 } 32 33 // ---- "application" layer: anyhow for ergonomic propagation + context ---- 34 use anyhow::{Context, Result}; 35 use store::StoreError; 36 37 fn greet(id: u32) -> Result<String> { 38 let user = store::fetch(id) 39 .with_context(|| format!("while greeting user {id}"))?; 40 Ok(format!("Hello user {} (age {})", user.id, user.age)) 41 } 42 43 fn run() -> Result<()> { 44 println!("{}", greet(7)?); 45 46 // Recover a specific typed variant after the fact. 47 if let Err(e) = greet(99) { 48 if let Some(StoreError::NotFound(missing)) = e.downcast_ref::<StoreError>() { 49 println!("(handled) no such user: {missing}"); 50 } 51 } 52 53 // A corrupt-row failure carries its source through the context layer. 54 if let Err(e) = greet(42) { 55 println!("chain for id 42:"); 56 for cause in e.chain() { 57 println!(" - {cause}"); 58 } 59 } 60 Ok(()) 61 } 62 63 fn main() { 64 if let Err(e) = run() { 65 eprintln!("fatal: {e:#}"); 66 std::process::exit(1); 67 } 68 } ``` Output: ```text 1 Hello user 7 (age 30) 2 (handled) no such user: 99 3 chain for id 42: 4 - while greeting user 42 5 - corrupt row 6 - invalid digit found in string ``` Notice the three-level chain for id 42: the application’s context (`while greeting user 42`), the library’s variant message (`corrupt row`), and the original standard-library cause (`invalid digit found in string`). Each layer added exactly the information it knew about, and `thiserror`’s `#[from]` stitched the `source()` together automatically. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`anyhow` crate documentation](https://docs.rs/anyhow) — `Context`, `anyhow!`, `bail!`, `ensure!`, `Error::chain`, `downcast_ref`. * [`thiserror` crate documentation](https://docs.rs/thiserror) — every attribute: `#[error]`, `#[from]`, `#[source]`, `#[error(transparent)]`. * [Rust By Example: Boxing errors](https://doc.rust-lang.org/rust-by-example/error/multiple_error_types/boxing_errors.html) — the `Box<dyn Error>` approach these crates build on. * [The `?` Operator](/08-error-handling/01-question-mark/) — the `From`-based conversion that `#[from]` generates for `?`. * [Custom Errors](/08-error-handling/04-custom-errors/) and [The `Error` Trait](/08-error-handling/05-error-trait/) — what `thiserror` writes for you, done by hand. * [Multiple Error Types](/08-error-handling/07-multiple-errors/) — aggregating several error sources, `#[from]` conflicts, and `Box<dyn Error>`. * [Best Practices](/08-error-handling/08-best-practices/) — the libraries-vs-applications design decision in full. * [Macros](/14-macros/) — why `#[derive(Error)]` is compile-time codegen, not a runtime decorator. * [Generics & Traits](/09-generics-traits/) — the `Error` trait and trait bounds (`Send + Sync + 'static`) `anyhow` relies on. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1 [Section titled “Exercise 1”](#exercise-1) **Difficulty:** Beginner **Objective:** Replace a hand-written error type with a `thiserror` enum that carries a source chain. **Instructions:** Write a function `sum_first_column(text: &str) -> Result<i64, CsvError>` that parses the first comma-separated column of each line as an `i64` and returns the sum. Define `CsvError` with `thiserror` so that (a) an I/O-style variant uses `#[from] std::io::Error`, and (b) a parse failure variant records the **1-based line number** *and* keeps the original `ParseIntError` as its `source()`. Demonstrate the `source()` chain on bad input. Solution ```rust 1 use thiserror::Error; 2 3 #[derive(Debug, Error)] 4 enum CsvError { 5 #[error("file error")] 6 Io(#[from] std::io::Error), 7 8 #[error("bad number on line {line}")] 9 Parse { 10 line: usize, 11 // #[source] keeps the cause chain WITHOUT generating a From impl 12 // (we need the line number, so we build this variant manually). 13 #[source] 14 source: std::num::ParseIntError, 15 }, 16 } 17 18 fn sum_first_column(text: &str) -> Result<i64, CsvError> { 19 let mut total = 0i64; 20 for (i, line) in text.lines().enumerate() { 21 let first = line.split(',').next().unwrap_or(""); 22 let n: i64 = first 23 .parse() 24 .map_err(|e| CsvError::Parse { line: i + 1, source: e })?; 25 total += n; 26 } 27 Ok(total) 28 } 29 30 fn main() { 31 println!("{:?}", sum_first_column("10,a\n20,b")); // Ok(30) 32 33 let e = sum_first_column("10\nxx").unwrap_err(); 34 println!("{e}"); 35 if let Some(src) = std::error::Error::source(&e) { 36 println!(" caused by: {src}"); 37 } 38 } ``` Output: ```text 1 Ok(30) 2 bad number on line 2 3 caused by: invalid digit found in string ``` ### Exercise 2 [Section titled “Exercise 2”](#exercise-2) **Difficulty:** Intermediate **Objective:** Combine a `thiserror` library error with an `anyhow` application that recovers a specific variant. **Instructions:** Define `HttpError` (a `thiserror` struct holding a `status: u16`). Write `fetch(url: &str) -> anyhow::Result<String>` that fails with a `404` `HttpError` wrapped in context. In `main` (returning `anyhow::Result<()>`), call `fetch`, and if the error downcasts to an `HttpError` with status `404`, treat it as recoverable (print a message and return `Ok(())`); otherwise propagate it. Solution ```rust 1 use anyhow::{Context, Result}; 2 use thiserror::Error; 3 4 #[derive(Debug, Error)] 5 #[error("HTTP {status}")] 6 struct HttpError { 7 status: u16, 8 } 9 10 fn fetch(url: &str) -> Result<String> { 11 if url.is_empty() { 12 return Err(HttpError { status: 400 }.into()); 13 } 14 // Simulate a 404, with a context layer describing the request. 15 Err(HttpError { status: 404 }).context(format!("requesting {url}")) 16 } 17 18 fn main() -> Result<()> { 19 match fetch("https://example.com/x") { 20 Ok(body) => println!("{body}"), 21 Err(e) => { 22 // Recover the concrete typed error to decide if it is recoverable. 23 if let Some(h) = e.downcast_ref::<HttpError>() { 24 if h.status == 404 { 25 println!("not found (recovered, status {})", h.status); 26 return Ok(()); 27 } 28 } 29 return Err(e); // any other error propagates and is reported by main 30 } 31 } 32 Ok(()) 33 } ``` Output: ```text 1 not found (recovered, status 404) ``` ### Exercise 3 [Section titled “Exercise 3”](#exercise-3) **Difficulty:** Advanced **Objective:** Use `downcast_ref` on an `anyhow::Error` to implement retry logic that depends on the underlying library error variant. **Instructions:** Build an `api` module with `thiserror` enum `ApiError` having variants `RateLimited { retry_after_secs: u64 }`, `BadRequest(#[from] std::num::ParseIntError)`, and `Server { code: u16 }`, plus `fn call(attempt: u32) -> Result<u32, ApiError>` that returns `RateLimited` on attempt 0, succeeds on attempt 1, and returns a `Server` error otherwise. In the application, write `call_with_retry() -> anyhow::Result<u32>` that loops up to 3 attempts: on each error, add context, then `downcast_ref::<ApiError>()`; if it is `RateLimited`, log and retry; otherwise propagate. On the final failure, print the full `chain()`. Solution ```rust 1 mod api { 2 use thiserror::Error; 3 4 #[derive(Debug, Error)] 5 pub enum ApiError { 6 #[error("rate limited; retry after {retry_after_secs}s")] 7 RateLimited { retry_after_secs: u64 }, 8 9 #[error("bad request")] 10 BadRequest(#[from] std::num::ParseIntError), 11 12 #[error("server error {code}")] 13 Server { code: u16 }, 14 } 15 16 pub fn call(attempt: u32) -> Result<u32, ApiError> { 17 match attempt { 18 0 => Err(ApiError::RateLimited { retry_after_secs: 2 }), 19 1 => Ok("123".parse::<u32>()?), // succeeds 20 _ => Err(ApiError::Server { code: 500 }), 21 } 22 } 23 } 24 25 use anyhow::{Context, Result}; 26 use api::ApiError; 27 28 fn call_with_retry() -> Result<u32> { 29 for attempt in 0..3 { 30 match api::call(attempt).context("calling upstream API") { 31 Ok(v) => return Ok(v), 32 Err(e) => match e.downcast_ref::<ApiError>() { 33 Some(ApiError::RateLimited { retry_after_secs }) => { 34 println!("rate limited, would sleep {retry_after_secs}s; retrying"); 35 continue; 36 } 37 _ => return Err(e), // non-retryable: propagate with context intact 38 }, 39 } 40 } 41 anyhow::bail!("exhausted retries") 42 } 43 44 fn main() { 45 match call_with_retry() { 46 Ok(v) => println!("got {v}"), 47 Err(e) => { 48 eprintln!("failed: {e:#}"); 49 for cause in e.chain() { 50 eprintln!(" - {cause}"); 51 } 52 } 53 } 54 } ``` Output: ```text 1 rate limited, would sleep 2s; retrying 2 got 123 ``` # Handling Multiple Error Types > When a Rust function fails several ways, collapse the types behind Box<dyn Error> or an aggregating enum with #[from], replacing TS's untyped catch. In TypeScript a single `try/catch` quietly absorbs *every* kind of failure — a network error, a parse error, your own validation error — because `throw` is untyped. Rust forces you to decide, up front, how a function that can fail in several different ways should report those failures. This page is about that decision: erasing all the types behind `Box<dyn Error>`, or **aggregating** them into one purpose-built enum, and using `#[from]` so the `?` operator does the conversions for you. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) When a function calls several fallible operations, each returns its *own* error type: `std::io::Error` here, `std::num::ParseIntError` there, your own validation error somewhere else. A function has a single `Result<T, E>` return type, so all of those have to collapse into one `E`. The two idiomatic answers are **`Box<dyn Error>`** (type-erase everything behind a trait object; great for applications) and **an aggregating `enum`** (one variant per source; great for libraries whose callers must tell the cases apart). The `From` trait, usually generated by `thiserror`’s `#[from]`, is the glue that lets `?` convert each underlying error into your chosen `E` automatically. > **Note:** This page assumes you already know how `Result`/`Option` work ([Result & Option](/08-error-handling/00-result-option/)), how `?` propagates and converts errors via `From` ([The `?` Operator](/08-error-handling/01-question-mark/)), and how to define a single custom error type ([Custom Errors](/08-error-handling/04-custom-errors/)). Here we focus specifically on *combining many error sources*. The full `thiserror`/`anyhow` API tour lives in [anyhow & thiserror](/08-error-handling/06-anyhow-thiserror/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript, a function that reads a value, parses it, and validates it can throw three unrelated things. The signature says nothing about any of them, and the `catch` block receives `unknown`: ```typescript 1 // A custom domain error alongside built-in ones. 2 class OutOfRangeError extends Error { 3 constructor(public port: number) { 4 super(`port ${port} is outside 1024..=65535`); 5 this.name = "OutOfRangeError"; 6 } 7 } 8 9 // Can throw: a filesystem error, a TypeError (parse), or OutOfRangeError. 10 // None of that appears in the return type `number`. 11 function loadPort(raw: string): number { 12 const trimmed = raw.trim(); 13 const port = Number(trimmed); 14 if (!Number.isInteger(port)) { 15 throw new TypeError(`config value \`${trimmed}\` is not a number`); 16 } 17 if (port < 1024) { 18 throw new OutOfRangeError(port); 19 } 20 return port; 21 } 22 23 for (const raw of ["8080", "free", "80"]) { 24 try { 25 console.log(`${raw} -> listening on ${loadPort(raw)}`); 26 } catch (e) { 27 // We must re-discover the type at runtime with instanceof. 28 if (e instanceof OutOfRangeError) { 29 console.log(`${raw} -> out of range: ${e.message}`); 30 } else if (e instanceof TypeError) { 31 console.log(`${raw} -> parse: ${e.message}`); 32 } else { 33 console.log(`${raw} -> other: ${String(e)}`); 34 } 35 } 36 } ``` Running this under Node v22 prints: ```text 1 8080 -> listening on 8080 2 free -> parse: config value `free` is not a number 3 80 -> out of range: port 80 is outside 1024..=65535 ``` Two characteristics define the TypeScript approach, and Rust pushes back on both: * **Failures are invisible in the type.** `loadPort` returns `number`; the three things it can throw are documented only by reading the body. A caller that forgets the `try/catch` compiles fine and crashes at runtime. * **The error type is recovered with `instanceof`.** Because everything is thrown as `unknown`, you re-narrow it with a chain of `instanceof` checks, and nothing forces that chain to be exhaustive. Rust makes the failure set part of the signature and gives you two ways to model “several error sources, one return type.” *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ### Option A — erase every error behind `Box<dyn Error>` [Section titled “Option A — erase every error behind Box\<dyn Error>”](#option-a--erase-every-error-behind-boxdyn-error) The quickest way to let one function surface many error types is to return `Box<dyn Error>`: a heap-allocated trait object that can hold *any* type implementing the `Error` trait. The `?` operator converts each concrete error into the box automatically. ```rust 1 use std::error::Error; 2 use std::fs; 3 4 // Three unrelated failures, one return type: 5 // - fs::read_to_string -> std::io::Error 6 // - str::parse -> std::num::ParseIntError 7 // - our own range check -> a string error 8 fn load_port(path: &str) -> Result<u16, Box<dyn Error>> { 9 let text = fs::read_to_string(path)?; // io::Error -> Box<dyn Error> 10 let port: u16 = text.trim().parse()?; // ParseIntError -> Box<dyn Error> 11 if port < 1024 { 12 // &str -> Box<dyn Error> via a standard-library From impl 13 return Err(format!("port {port} is privileged").into()); 14 } 15 Ok(port) 16 } 17 18 fn main() { 19 match load_port("config.txt") { 20 Ok(port) => println!("listening on {port}"), 21 Err(e) => eprintln!("startup failed: {e}"), 22 } 23 } ``` With no `config.txt` present, this prints: ```text 1 startup failed: No such file or directory (os error 2) ``` This is the closest Rust gets to TypeScript’s “throw anything.” But notice what the caller *loses*: a `Box<dyn Error>` is opaque, so they can report it but cannot cleanly branch on “was it the I/O failure or the range failure?” without a downcast. That trade-off motivates Option B. ### Option B — aggregate the sources into one `enum` [Section titled “Option B — aggregate the sources into one enum”](#option-b--aggregate-the-sources-into-one-enum) When callers need to tell the failure modes apart, give them a closed `enum` with one variant per source. The `thiserror` crate generates the `Display`, `Error`, `source()`, and `From` wiring: ```rust 1 use std::num::ParseIntError; 2 use thiserror::Error; 3 4 // One enum that AGGREGATES every way config loading can fail. 5 // Display, Error, source(), and the two From impls are all generated. 6 #[derive(Debug, Error)] 7 enum ConfigError { 8 #[error("could not read the config file")] 9 Io(#[from] std::io::Error), // generates From<std::io::Error> + source() 10 11 #[error("config value was not a number")] 12 Parse(#[from] ParseIntError), // generates From<ParseIntError> + source() 13 14 #[error("port {0} is outside 1024..=65535")] 15 OutOfRange(u16), // no #[from]: built by hand, no underlying cause 16 } 17 18 fn load_port(path: &str) -> Result<u16, ConfigError> { 19 let text = std::fs::read_to_string(path)?; // io::Error -> ConfigError 20 let port: u16 = text.trim().parse()?; // ParseIntError -> ConfigError 21 if port < 1024 { 22 return Err(ConfigError::OutOfRange(port)); 23 } 24 Ok(port) 25 } 26 27 fn main() { 28 if let Err(e) = load_port("missing.txt") { 29 eprintln!("error: {e}"); 30 // thiserror wired up source() automatically for the #[from] variants: 31 if let Some(cause) = std::error::Error::source(&e) { 32 eprintln!(" caused by: {cause}"); 33 } 34 } 35 } ``` Output: ```text 1 error: could not read the config file 2 caused by: No such file or directory (os error 2) ``` The signature `Result<u16, ConfigError>` now tells the caller the *exact* set of failure modes, and they can `match` on the variants: the compiler-checked equivalent of the `instanceof` chain, with exhaustiveness guaranteed. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What `Box<dyn Error>` actually is [Section titled “What Box\<dyn Error> actually is”](#what-boxdyn-error-actually-is) `dyn Error` is a **trait object**: a value whose concrete type is not known at compile time, only that it implements `std::error::Error`. Because trait objects are unsized, they must live behind a pointer, hence `Box<dyn Error>`, a pointer to a heap allocation that also carries a vtable. This is type erasure, and it is the part of Rust that most resembles dynamic dispatch in TypeScript. (Trait objects are covered in depth in [Section 09: Generics & Traits](/09-generics-traits/).) The reason `?` “just works” with it is a single **blanket implementation** in the standard library, roughly: ```rust 1 // From the standard library (simplified). 2 impl<E: Error + 'static> From<E> for Box<dyn Error> { 3 fn from(err: E) -> Box<dyn Error> { 4 Box::new(err) 5 } 6 } ``` So any error type at all can become a `Box<dyn Error>`. When `?` sees a `Result<_, std::io::Error>` inside a function returning `Result<_, Box<dyn Error>>`, it calls this `From` to box the `io::Error`. The `format!(...).into()` line uses a sibling impl (`From<String>`/`From<&str> for Box<dyn Error>`) that wraps a plain message string. You get propagation *and* conversion for free, with zero `From` impls of your own. ### Why aggregate into an enum instead [Section titled “Why aggregate into an enum instead”](#why-aggregate-into-an-enum-instead) `Box<dyn Error>` is perfect when the caller will only *report* the error (log it, return a 500, exit). It is a poor fit when the caller must *decide* something based on which failure occurred — retry on a timeout, return 404 on not-found, surface a 400 on bad input. Because the concrete type is erased, the only way to recover it is a runtime `downcast`, which is exactly the brittle `instanceof`-style narrowing Rust normally lets you avoid. An aggregating enum keeps the type information. Here is the same `ConfigError` written *by hand*, so you can see precisely what `#[from]` generates: ```rust 1 use std::error::Error; 2 use std::fmt; 3 use std::num::ParseIntError; 4 5 #[derive(Debug)] 6 enum ConfigError { 7 Io(std::io::Error), 8 Parse(ParseIntError), 9 OutOfRange(u16), 10 } 11 12 impl fmt::Display for ConfigError { 13 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 14 match self { 15 ConfigError::Io(_) => write!(f, "could not read the config file"), 16 ConfigError::Parse(_) => write!(f, "config value was not a number"), 17 ConfigError::OutOfRange(p) => write!(f, "port {p} is outside 1024..=65535"), 18 } 19 } 20 } 21 22 impl Error for ConfigError { 23 fn source(&self) -> Option<&(dyn Error + 'static)> { 24 match self { 25 ConfigError::Io(e) => Some(e), 26 ConfigError::Parse(e) => Some(e), 27 ConfigError::OutOfRange(_) => None, 28 } 29 } 30 } 31 32 // These two From impls are what let `?` convert automatically. 33 impl From<std::io::Error> for ConfigError { 34 fn from(e: std::io::Error) -> Self { 35 ConfigError::Io(e) 36 } 37 } 38 39 impl From<ParseIntError> for ConfigError { 40 fn from(e: ParseIntError) -> Self { 41 ConfigError::Parse(e) 42 } 43 } 44 45 fn load_port(path: &str) -> Result<u16, ConfigError> { 46 let text = std::fs::read_to_string(path)?; // io::Error -> ConfigError via From 47 let port: u16 = text.trim().parse()?; // ParseIntError -> ConfigError via From 48 if port < 1024 { 49 return Err(ConfigError::OutOfRange(port)); // our own variant, no conversion 50 } 51 Ok(port) 52 } 53 54 fn main() { 55 match load_port("missing.txt") { 56 Ok(port) => println!("port = {port}"), 57 Err(e) => { 58 eprintln!("error: {e}"); 59 if let Some(cause) = e.source() { 60 eprintln!(" caused by: {cause}"); 61 } 62 // The caller can also branch on the variant: 63 match e { 64 ConfigError::Io(_) => eprintln!(" -> tip: check the path"), 65 ConfigError::Parse(_) => eprintln!(" -> tip: file must contain only a number"), 66 ConfigError::OutOfRange(_) => eprintln!(" -> tip: pick a port >= 1024"), 67 } 68 } 69 } 70 } ``` Output: ```text 1 error: could not read the config file 2 caused by: No such file or directory (os error 2) 3 -> tip: check the path ``` That is roughly twenty lines of mechanical boilerplate: two `From` impls, a `source()` arm per variant, a `Display` arm per variant. Writing it once is instructive; writing it for every error type in a real codebase is tedious and error-prone. That is precisely the boilerplate `#[from]` removes. ### `#[from]` versus `#[source]` [Section titled “#\[from\] versus #\[source\]”](#from-versus-source) In the `thiserror` enum, two attributes look similar but do different jobs: * **`#[from]`** does two things at once: it makes that field the `source()` of the error *and* generates a `From<ThatType>` impl for the whole enum. Use it when “I received error X” should *be* this variant, so that `?` can convert X straight into your error with no `.map_err(...)`. * **`#[source]`** only marks the field as the cause for `source()`; it does **not** generate `From`. Use it when the variant needs *additional context* alongside the cause (a row number, a key name), so you construct it explicitly with `.map_err(...)` and there is no sensible automatic conversion. A variant can have at most one `#[from]` field, and a `#[from]` field cannot share the variant with other data — because a `From<X>` conversion only receives the `X`, it has nothing to fill the extra fields with. When you need extra context, switch to `#[source]`: ```rust 1 use std::num::ParseFloatError; 2 use thiserror::Error; 3 4 #[derive(Debug, Error)] 5 enum RowError { 6 // #[from]: the io::Error alone fully determines this variant. 7 #[error("could not read file")] 8 Read(#[from] std::io::Error), 9 10 // #[source]: we attach a row number too, so there is no automatic From; 11 // we build this variant by hand with .map_err(...). 12 #[error("row {row}: not a number")] 13 Price { 14 row: usize, 15 #[source] 16 cause: ParseFloatError, 17 }, 18 } 19 20 fn main() { 21 let e = RowError::Price { 22 row: 7, 23 cause: "x".parse::<f64>().unwrap_err(), 24 }; 25 println!("{e}"); 26 println!("caused by: {:?}", std::error::Error::source(&e).map(|c| c.to_string())); 27 } ``` Output: ```text 1 row 7: not a number 2 caused by: Some("invalid float literal") ``` ### `#[error(transparent)]`: forward an error unchanged [Section titled “#\[error(transparent)\]: forward an error unchanged”](#errortransparent-forward-an-error-unchanged) Sometimes a variant is a pure pass-through: it wraps another error and should adopt that error’s message and cause as its own, adding nothing. `#[error(transparent)]` delegates both `Display` and `source()` straight to the inner error: ```rust 1 use thiserror::Error; 2 3 #[derive(Debug, Error)] 4 enum DbError { 5 #[error("connection refused")] 6 Connection, 7 } 8 9 #[derive(Debug, Error)] 10 enum ServiceError { 11 // transparent: delegate Display and source() straight to the wrapped error. 12 #[error(transparent)] 13 Db(#[from] DbError), 14 #[error("user {0} is not authorized")] 15 Unauthorized(u64), 16 } 17 18 fn main() { 19 let e: ServiceError = DbError::Connection.into(); 20 println!("{e}"); // prints DbError's message, not a wrapper's 21 } ``` Output: ```text 1 connection refused ``` This is the idiomatic way to let a higher-level error enum absorb a lower-level one (often from another module or crate) when there is nothing useful to add at this layer. ### Recovering a concrete type from `Box<dyn Error>` [Section titled “Recovering a concrete type from Box\<dyn Error>”](#recovering-a-concrete-type-from-boxdyn-error) If you chose `Box<dyn Error>` but still occasionally need to react to a specific error, you recover the concrete type with `downcast_ref::<T>()`, Rust’s checked-cast analog of `instanceof`. It returns `Some(&T)` if the box really holds a `T`, and `None` otherwise: ```rust 1 use std::error::Error; 2 use std::io; 3 4 fn run() -> Result<(), Box<dyn Error>> { 5 // Pretend something failed with a NotFound io error. 6 Err(Box::new(io::Error::new(io::ErrorKind::NotFound, "file gone"))) 7 } 8 9 fn main() { 10 if let Err(e) = run() { 11 // You cannot `match` the variants of a boxed trait object directly. 12 // You must downcast back to the concrete type you suspect. 13 if let Some(io_err) = e.downcast_ref::<io::Error>() { 14 if io_err.kind() == io::ErrorKind::NotFound { 15 eprintln!("recovering: treating missing file as empty input"); 16 return; 17 } 18 } 19 eprintln!("unrecoverable: {e}"); 20 } 21 } ``` Output: ```text 1 recovering: treating missing file as empty input ``` If you find yourself downcasting often, that is a signal you wanted an enum, not a box. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / JavaScript | Rust | | --------------------------------- | -------------------------------------------------- | -------------------------------------------------------- | | Several failure sources | All thrown; type invisible in signature | Must collapse into one `E` in `Result<T, E>` | | ”Throw anything” | `throw` any value | `Box<dyn Error>` (boxed trait object) | | Recover the concrete type | `e instanceof Foo` | `e.downcast_ref::<Foo>()` | | Closed set of failures | A union of error classes (not enforced at `catch`) | An `enum` with a variant per source (exhaustive `match`) | | Converting one error into another | implicit; you just `throw` | explicit `From` impl, applied by `?` | | Generating that conversion | n/a | `#[from]` (via `thiserror`) | | Underlying cause | `error.cause` (ES2022) | `source()`, wired by `#[from]`/`#[source]` | | Exhaustiveness | not checked | compiler-checked on `match` | ### The central trade-off: erase vs. aggregate [Section titled “The central trade-off: erase vs. aggregate”](#the-central-trade-off-erase-vs-aggregate) | | `Box<dyn Error>` | Aggregating `enum` | | ------------------------------- | -------------------------------------------- | ---------------------------------------------------- | | Boilerplate | Almost none — `?` boxes anything | One variant + `#[from]`/`#[source]` per source | | Caller can `match` on the cause | No (must `downcast`) | Yes, exhaustively | | Adding a new error source | Free | Add a variant (a deliberate, visible change) | | Best for | Application/`main` code, scripts, prototypes | Library APIs whose callers must distinguish failures | | Carries cause chain | Yes (via `Error::source`) | Yes (via `#[from]`/`#[source]`) | The rule of thumb, expanded in [Best Practices](/08-error-handling/08-best-practices/): **applications box, libraries enumerate.** An application usually just reports and exits, so erasing the types costs nothing. A library is consumed by code that needs to make decisions, so the precise enum is part of its public contract. ### Send + Sync for threads and async [Section titled “Send + Sync for threads and async”](#send--sync-for-threads-and-async) A bare `Box<dyn Error>` is **not** `Send`, so it cannot cross a thread boundary or live in an async task that may move between threads. For anything touching `std::thread::spawn`, `tokio`, or a web handler, use the thread-safe alias: ```rust 1 // The form most application code (and anyhow internally) reaches for. 2 type BoxError = Box<dyn std::error::Error + Send + Sync + 'static>; ``` This is covered in detail in [The `Error` Trait](/08-error-handling/05-error-trait/); just remember the `+ Send + Sync` when threads or async are involved. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: two `#[from]` variants for the same source type [Section titled “Pitfall 1: two #\[from\] variants for the same source type”](#pitfall-1-two-from-variants-for-the-same-source-type) `#[from]` generates a `From<T>` impl for the whole enum. If two variants both claim `#[from]` for the *same* `T`, you get two conflicting `From<T>` impls — which Rust forbids: ```rust 1 use std::num::ParseIntError; 2 use thiserror::Error; 3 4 #[derive(Debug, Error)] 5 enum ParseError { 6 #[error("bad width")] 7 Width(#[from] ParseIntError), 8 #[error("bad height")] 9 Height(#[from] ParseIntError), // does not compile (error[E0119]) 10 } 11 12 fn main() {} ``` Real compiler error (`cargo build`): ```text 1 error[E0119]: conflicting implementations of trait `From<ParseIntError>` for type `ParseError` 2 --> src/main.rs:9:14 3 | 4 7 | Width(#[from] ParseIntError), 5 | ---- first implementation here 6 8 | #[error("bad height")] 7 9 | Height(#[from] ParseIntError), 8 | ^^^^ conflicting implementation for `ParseError` ``` **Fix:** at most one variant may auto-convert from a given type. The variant that needs to distinguish *which* field failed should use `#[source]` (no `From`) and be constructed explicitly with `.map_err(...)` so you can record `Width` vs `Height` yourself. ### Pitfall 2: trying to `match` the variants of a `Box<dyn Error>` [Section titled “Pitfall 2: trying to match the variants of a Box\<dyn Error>”](#pitfall-2-trying-to-match-the-variants-of-a-boxdyn-error) A trait object has no visible variants or fields, so you cannot pattern-match its concrete shape: ```rust 1 use std::error::Error; 2 3 fn do_work() -> Result<(), Box<dyn Error>> { 4 Err("nope".into()) 5 } 6 7 fn main() { 8 if let Err(e) = do_work() { 9 // does not compile (error[E0308]): a trait object has no variants to match. 10 match e { 11 std::io::Error { .. } => println!("io"), 12 _ => println!("other"), 13 } 14 } 15 } ``` Real compiler error (`cargo build`, abridged): ```text 1 error[E0308]: mismatched types 2 --> src/main.rs:11:13 3 | 4 10 | match e { 5 | - this expression has type `Box<dyn std::error::Error>` 6 11 | std::io::Error { .. } => println!("io"), 7 | ^^^^^^^^^^^^^^^^^^^^^ expected `Box<dyn Error>`, found `Error` ``` **Fix:** either `downcast_ref::<std::io::Error>()` to recover the concrete type, or — if branching is a recurring need — switch the return type to an aggregating enum so the variants are first-class. ### Pitfall 3: a custom enum missing a `From` for an error you `?` [Section titled “Pitfall 3: a custom enum missing a From for an error you ?”](#pitfall-3-a-custom-enum-missing-a-from-for-an-error-you-) If you write an aggregating enum by hand and forget the `From` impl (or the `#[from]` attribute), `?` cannot convert that source into your enum, and the code won’t compile. The `?`-operator page covers the exact `error[E0277]: ?couldn't convert the error...` message ([The `?` Operator → Pitfall 3](/08-error-handling/01-question-mark/)). The lesson for aggregation: **every error source you intend to `?`-propagate needs a `#[from]` variant** (or a manual `From`). Sources you build with extra context via `.map_err(...)` use `#[source]` instead and need no `From`. ### Pitfall 4: re-printing the cause in every layer’s message [Section titled “Pitfall 4: re-printing the cause in every layer’s message”](#pitfall-4-re-printing-the-cause-in-every-layers-message) When you aggregate with `#[from]`/`#[source]`, the underlying error is already reachable through `source()`. If each variant’s `#[error("...")]` *also* embeds the inner message (e.g. `#[error("io failed: {0}")]` on a `#[from]` field), a chain printer or `anyhow` will print the cause twice. Keep each layer’s message to its own concern and let `source()` carry the rest. (See [The `Error` Trait](/08-error-handling/05-error-trait/) for the cause-chain reporting pattern.) *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Applications box; libraries enumerate.** Reach for `Box<dyn Error + Send + Sync>` (or `anyhow::Error`) in binaries and `main`, where you only report. Reach for a `thiserror` enum in libraries, where callers must distinguish failures. This split is the single most useful heuristic for multi-error code. * **Let `#[from]` drive your `?` ergonomics.** Give each error *source* a `#[from]` variant so `?` converts automatically with no `.map_err(...)`. It keeps the happy path readable top to bottom. * **Use `#[source]` (not `#[from]`) when a variant carries extra context.** A row number, a file path, or a key name that accompanies the cause means there is no sensible automatic `From`; construct the variant with `.map_err(...)` and mark the cause `#[source]`. * **Use `#[error(transparent)]` to absorb another error wholesale.** When one layer wraps another layer’s error and has nothing to add, `transparent` forwards `Display` and `source()` and keeps the chain clean. * **Add `+ Send + Sync` to boxed errors used with threads or async.** `Box<dyn Error + Send + Sync + 'static>` is the safe default for anything concurrent; a bare `Box<dyn Error>` will not cross a thread boundary. * **Don’t reach for `downcast` as a habit.** Occasional downcasting from a box is fine; frequent downcasting means you actually wanted an enum. Let the type system carry the distinction instead of re-discovering it at runtime. * **Prefer `thiserror` over hand-rolled `From`/`source()`.** The hand-written version exists in this page to show what is generated; in real code, derive it. Reserve manual impls for the rare case the derive can’t express. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A price-list import pipeline. It reads a file (an `io::Error` source), parses each row’s price (a `ParseFloatError` source), and validates the row shape (its own logic). All three collapse into one `ImportError` enum: the I/O failure uses `#[from]` so `?` boxes it automatically, while the row-level errors use `#[source]` because they carry a row number. A `category()` method shows how a caller (an HTTP layer, say) can branch on the aggregated error to choose a status code. ```rust 1 use std::num::ParseFloatError; 2 use thiserror::Error; 3 4 /// Everything that can go wrong while importing a price list. 5 /// Three distinct sources are aggregated behind one type. 6 #[derive(Debug, Error)] 7 enum ImportError { 8 /// Reading the file failed (permissions, missing, etc.). 9 #[error("could not read import file")] 10 Read(#[from] std::io::Error), 11 12 /// A price column was not a valid number. 13 #[error("row {row}: price `{raw}` is not a number")] 14 Price { 15 row: usize, 16 raw: String, 17 // #[source] keeps the cause chain without generating a From impl. 18 #[source] 19 cause: ParseFloatError, 20 }, 21 22 /// The row did not have the two expected fields. 23 #[error("row {row}: expected `name,price`, got `{line}`")] 24 Malformed { row: usize, line: String }, 25 } 26 27 /// A coarse category an HTTP layer or a logger might switch on. 28 #[derive(Debug, PartialEq)] 29 enum Category { 30 Infrastructure, // retryable / our fault -> 5xx 31 BadInput, // the user's fault -> 4xx 32 } 33 34 impl ImportError { 35 fn category(&self) -> Category { 36 match self { 37 ImportError::Read(_) => Category::Infrastructure, 38 ImportError::Price { .. } | ImportError::Malformed { .. } => Category::BadInput, 39 } 40 } 41 } 42 43 struct Item { 44 name: String, 45 price: f64, 46 } 47 48 fn parse_rows(contents: &str) -> Result<Vec<Item>, ImportError> { 49 let mut items = Vec::new(); 50 for (i, line) in contents.lines().enumerate() { 51 let row = i + 1; 52 // Malformed: no automatic From, so build it explicitly. 53 let (name, raw_price) = line.split_once(',').ok_or_else(|| ImportError::Malformed { 54 row, 55 line: line.to_string(), 56 })?; 57 // Price: attach the row + raw value, mark the parse error as #[source]. 58 let price = raw_price 59 .trim() 60 .parse::<f64>() 61 .map_err(|cause| ImportError::Price { 62 row, 63 raw: raw_price.trim().to_string(), 64 cause, 65 })?; 66 items.push(Item { 67 name: name.to_string(), 68 price, 69 }); 70 } 71 Ok(items) 72 } 73 74 fn import(path: &str) -> Result<Vec<Item>, ImportError> { 75 // `?` converts the io::Error into ImportError::Read automatically (via #[from]). 76 let contents = std::fs::read_to_string(path)?; 77 parse_rows(&contents) 78 } 79 80 fn main() { 81 // Drive parse_rows directly so the example is deterministic (no real file). 82 let good = "widget,9.99\ngadget,19.50"; 83 let bad_price = "widget,free"; 84 let malformed = "just-a-name"; 85 86 for (label, data) in [("good", good), ("bad_price", bad_price), ("malformed", malformed)] { 87 println!("--- {label} ---"); 88 match parse_rows(data) { 89 Ok(items) => { 90 for item in items { 91 println!(" {} = {:.2}", item.name, item.price); 92 } 93 } 94 Err(e) => { 95 println!(" error [{:?}]: {e}", e.category()); 96 // Walk the source chain for the underlying cause, if any. 97 let mut source = std::error::Error::source(&e); 98 while let Some(cause) = source { 99 println!(" caused by: {cause}"); 100 source = cause.source(); 101 } 102 } 103 } 104 } 105 106 // `import` exists to show #[from] in action with the ? operator. 107 let _ = import("does-not-exist.csv").map_err(|e| { 108 println!("--- import (real file) ---"); 109 println!(" error [{:?}]: {e}", e.category()); 110 }); 111 } ``` Real output: ```text 1 --- good --- 2 widget = 9.99 3 gadget = 19.50 4 --- bad_price --- 5 error [BadInput]: row 1: price `free` is not a number 6 caused by: invalid float literal 7 --- malformed --- 8 error [BadInput]: row 1: expected `name,price`, got `just-a-name` 9 --- import (real file) --- 10 error [Infrastructure]: could not read import file ``` One enum, three sources, two attribute styles (`#[from]` for the context-free I/O error, `#[source]` for the row errors that carry extra data), and a `category()` method that turns the aggregated error into an actionable decision. That is the multi-error pattern most production Rust services use. > **Tip:** In a real web service you would `impl From<ImportError> for StatusCode` (or implement a framework trait like axum’s `IntoResponse`) so the handler can return the error directly and the framework maps `category()` to a status. The principle is the same: aggregate into one enum, then translate at the boundary. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`Box<dyn Error>` and its `From` conversions](https://doc.rust-lang.org/std/boxed/struct.Box.html#impl-From%3CE%3E-for-Box%3Cdyn+Error%3E): the blanket impl that makes `?` box anything * [`Error::downcast_ref`](https://doc.rust-lang.org/std/error/trait.Error.html#method.downcast_ref-1): recovering a concrete type from a trait object * [`thiserror` documentation](https://docs.rs/thiserror): the `#[from]`, `#[source]`, and `#[error(transparent)]` attributes used here * [The Rust Book: “Recoverable Errors with `Result`”](https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html) Related sections in this guide: * [Result & Option](/08-error-handling/00-result-option/): the values that carry these errors * [The `?` Operator](/08-error-handling/01-question-mark/): how `From` conversions get applied during propagation * [Custom Errors](/08-error-handling/04-custom-errors/): defining a single error enum/struct by hand * [The `Error` Trait](/08-error-handling/05-error-trait/): `Display`/`Debug`, the `source()` chain, and `Box<dyn Error + Send + Sync>` * [anyhow & thiserror](/08-error-handling/06-anyhow-thiserror/): the full current API tour of both crates * [Best Practices](/08-error-handling/08-best-practices/) — when to box vs. enumerate, granularity, and error design * [Section 09: Generics & Traits](/09-generics-traits/) — trait objects and `dyn` dispatch in depth * [Section 01: Getting Started](/01-getting-started/) and [Section 02: Basics](/02-basics/) — `cargo add`, enums, and pattern matching used throughout *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1 [Section titled “Exercise 1”](#exercise-1) **Difficulty:** Beginner **Objective:** Aggregate two error sources into one hand-written enum. **Instructions:** Define an enum `CliError` with variants `Io(std::io::Error)` and `Parse(ParseIntError)`. Give it `#[derive(Debug)]`, an `impl Display`, an `impl Error` whose `source()` returns the wrapped error, and the two `From` impls that let `?` convert into it. Then write `doubled(raw: &str) -> Result<i64, CliError>` that parses `raw` and returns it times two. ```rust 1 use std::error::Error; 2 use std::fmt; 3 use std::num::ParseIntError; 4 5 #[derive(Debug)] 6 enum CliError { 7 Io(std::io::Error), 8 Parse(ParseIntError), 9 } 10 11 // TODO: impl Display, impl Error (with source()), and two From impls. 12 13 fn doubled(raw: &str) -> Result<i64, CliError> { 14 let n: i64 = raw.trim().parse()?; // needs From<ParseIntError> for CliError 15 Ok(n * 2) 16 } 17 18 fn main() { 19 for input in ["21", "oops"] { 20 match doubled(input) { 21 Ok(n) => println!("{input} -> {n}"), 22 Err(e) => println!("{input} -> error: {e}"), 23 } 24 } 25 } ``` Solution ```rust 1 use std::error::Error; 2 use std::fmt; 3 use std::num::ParseIntError; 4 5 #[derive(Debug)] 6 enum CliError { 7 Io(std::io::Error), 8 Parse(ParseIntError), 9 } 10 11 impl fmt::Display for CliError { 12 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 13 match self { 14 CliError::Io(_) => write!(f, "failed to read input"), 15 CliError::Parse(_) => write!(f, "input was not a valid integer"), 16 } 17 } 18 } 19 20 impl Error for CliError { 21 fn source(&self) -> Option<&(dyn Error + 'static)> { 22 match self { 23 CliError::Io(e) => Some(e), 24 CliError::Parse(e) => Some(e), 25 } 26 } 27 } 28 29 impl From<std::io::Error> for CliError { 30 fn from(e: std::io::Error) -> Self { 31 CliError::Io(e) 32 } 33 } 34 35 impl From<ParseIntError> for CliError { 36 fn from(e: ParseIntError) -> Self { 37 CliError::Parse(e) 38 } 39 } 40 41 fn doubled(raw: &str) -> Result<i64, CliError> { 42 let n: i64 = raw.trim().parse()?; // ParseIntError -> CliError 43 Ok(n * 2) 44 } 45 46 fn main() { 47 for input in ["21", "oops"] { 48 match doubled(input) { 49 Ok(n) => println!("{input} -> {n}"), 50 Err(e) => println!("{input} -> error: {e}"), 51 } 52 } 53 } ``` Output: ```text 1 21 -> 42 2 oops -> error: input was not a valid integer ``` ### Exercise 2 [Section titled “Exercise 2”](#exercise-2) **Difficulty:** Intermediate **Objective:** Replace the hand-written boilerplate with `thiserror` and `#[from]`. **Instructions:** Rewrite Exercise 1’s `CliError` using `#[derive(Debug, thiserror::Error)]`. Use `#[error("...")]` for each variant’s message and `#[from]` on each wrapped field so the `From` impls and `source()` are generated. Keep `doubled` identical, and have `main` also print the underlying cause via `source()`. (Run `cargo add thiserror` first.) Solution ```rust 1 use std::num::ParseIntError; 2 use thiserror::Error; 3 4 #[derive(Debug, Error)] 5 enum CliError { 6 #[error("failed to read input")] 7 Io(#[from] std::io::Error), 8 #[error("input was not a valid integer")] 9 Parse(#[from] ParseIntError), 10 } 11 12 fn doubled(raw: &str) -> Result<i64, CliError> { 13 let n: i64 = raw.trim().parse()?; 14 Ok(n * 2) 15 } 16 17 fn main() { 18 for input in ["21", "oops"] { 19 match doubled(input) { 20 Ok(n) => println!("{input} -> {n}"), 21 Err(e) => { 22 print!("{input} -> error: {e}"); 23 if let Some(cause) = std::error::Error::source(&e) { 24 print!(" (caused by: {cause})"); 25 } 26 println!(); 27 } 28 } 29 } 30 } ``` Output: ```text 1 21 -> 42 2 oops -> error: input was not a valid integer (caused by: invalid digit found in string) ``` The whole `impl Display`, `impl Error`, and two `From` blocks from Exercise 1 collapse into four attribute lines. ### Exercise 3 [Section titled “Exercise 3”](#exercise-3) **Difficulty:** Advanced **Objective:** Use `Box<dyn Error>` to surface several error types, then `downcast` to make a decision. **Instructions:** Define two custom error types, `RateLimited { retry_after_secs: u64 }` and `NotFound`, each implementing `Debug + Display + Error`. Write `fetch(kind: &str) -> Result<String, Box<dyn Error>>` that returns `Ok` for `"ok"`, a boxed `RateLimited` for `"rate"`, and a boxed `NotFound` otherwise. Then write `should_retry(err: &(dyn Error + 'static)) -> Option<u64>` that uses `downcast_ref` to return the retry delay only when the boxed error is a `RateLimited`. In `main`, drive all three cases and print whether each will be retried. Solution ```rust 1 use std::error::Error; 2 use std::fmt; 3 4 #[derive(Debug)] 5 struct RateLimited { 6 retry_after_secs: u64, 7 } 8 9 impl fmt::Display for RateLimited { 10 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 11 write!(f, "rate limited; retry after {}s", self.retry_after_secs) 12 } 13 } 14 impl Error for RateLimited {} 15 16 #[derive(Debug)] 17 struct NotFound; 18 impl fmt::Display for NotFound { 19 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 20 write!(f, "resource not found") 21 } 22 } 23 impl Error for NotFound {} 24 25 fn fetch(kind: &str) -> Result<String, Box<dyn Error>> { 26 match kind { 27 "ok" => Ok("payload".to_string()), 28 "rate" => Err(Box::new(RateLimited { retry_after_secs: 30 })), 29 _ => Err(Box::new(NotFound)), 30 } 31 } 32 33 /// Decide whether to retry based on the concrete error behind the box. 34 fn should_retry(err: &(dyn Error + 'static)) -> Option<u64> { 35 err.downcast_ref::<RateLimited>().map(|e| e.retry_after_secs) 36 } 37 38 fn main() { 39 for kind in ["ok", "rate", "missing"] { 40 match fetch(kind) { 41 Ok(body) => println!("{kind}: got {body}"), 42 Err(e) => match should_retry(e.as_ref()) { 43 Some(secs) => println!("{kind}: will retry in {secs}s"), 44 None => println!("{kind}: giving up: {e}"), 45 }, 46 } 47 } 48 } ``` Output: ```text 1 ok: got payload 2 rate: will retry in 30s 3 missing: giving up: resource not found ``` > **Note:** `e.as_ref()` turns the `Box<dyn Error>` into the `&(dyn Error + 'static)` that `downcast_ref` needs. If you found yourself doing this for many error types, that is the signal to switch from `Box<dyn Error>` to an aggregating enum. # Error-Handling Best Practices > Choosing the right error tool in Rust: thiserror enums for libraries, anyhow with context for apps, and Result versus panic, mapped from TypeScript habits. Once you know the mechanics (`Result`, `Option`, `?`, `panic!`, custom error types, and the `anyhow`/`thiserror` crates) the next question is *design*: how do you decide **which** tool to reach for, how granular your error types should be, what your messages should say, and where a real failure ends and a programmer bug begins. This page is the decision guide that ties the rest of Section 08 together. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Good Rust error handling is mostly about a few deliberate choices: **libraries** expose precise, matchable error types (typically a `thiserror` enum) so callers can react; **applications** prioritize getting a useful message to a human and bubbling failures up (typically `anyhow` with context). On top of that, you decide what is **recoverable** (return a `Result`) versus an **unrecoverable bug** (let it `panic!`). Get these axes right and the rest of error handling falls into place. > **Note:** This file is about *strategy*. The how-to for each piece lives in its sibling page: defining error types in [Custom Error Types](/08-error-handling/04-custom-errors/), the `Error` trait in [The `Error` Trait](/08-error-handling/05-error-trait/), the crates in [`anyhow` & `thiserror`](/08-error-handling/06-anyhow-thiserror/), and propagation in [The `?` Operator](/08-error-handling/01-question-mark/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In a Node.js codebase, error-handling strategy is mostly *convention*, because the language gives you almost no help. A typical service mixes several styles, and nothing in the type system forces consistency: ```typescript 1 // orders.ts — a service module in a Node app 2 3 // Style 1: throw a generic Error with a string. Loses all structure. 4 function validateQuantity(qty: number): void { 5 if (qty <= 0) { 6 throw new Error("quantity must be positive"); // caller can only read .message 7 } 8 } 9 10 // Style 2: a custom subclass, so callers *can* branch — if they remember to. 11 class OutOfStockError extends Error { 12 constructor(public readonly sku: string, public readonly available: number) { 13 super(`SKU ${sku} has only ${available} in stock`); 14 this.name = "OutOfStockError"; 15 } 16 } 17 18 async function reserve(sku: string, qty: number): Promise<number> { 19 validateQuantity(qty); 20 const available = await lookupStock(sku); // may itself throw a DB error 21 if (qty > available) { 22 throw new OutOfStockError(sku, available); 23 } 24 return available - qty; 25 } 26 27 // The caller has to *know* what might be thrown — the signature says `Promise<number>`, 28 // not "or it might throw OutOfStockError, or a TypeError, or a DB connection error". 29 async function handleRequest(sku: string, qty: number) { 30 try { 31 const left = await reserve(sku, qty); 32 console.log(`reserved, ${left} left`); 33 } catch (err) { 34 // `err` is typed `unknown`. We guess at the shapes we care about. 35 if (err instanceof OutOfStockError) { 36 console.warn(`restock ${err.sku}`); 37 } else { 38 console.error("unexpected:", err); // everything else is a black box 39 } 40 } 41 } 42 43 declare function lookupStock(sku: string): Promise<number>; ``` The three pain points that drive every decision below: 1. **The signature hides what can fail.** `Promise<number>` says nothing about `OutOfStockError`. 2. **There’s no enforced granularity.** One function throws a bare string, another throws a structured class, and the compiler is fine with both. 3. **Bug vs. expected failure is blurred.** A `TypeError` from a typo and a legitimate “out of stock” both arrive in the same `catch` as `unknown`. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust pushes you to make those choices explicit. A **library** module returns a precise enum the caller can match on; an **application** layer consumes it, adds human context, and lets it bubble up, only matching the specific variant it actually wants to handle. ```rust 1 // Real-world: a "billing" library module exposes a typed error. 2 // The application layer (main) consumes it with anyhow + context. 3 4 mod billing { 5 use thiserror::Error; 6 7 /// Public, stable error type. Callers can match on these variants; 8 /// adding a variant later is a semver concern, so we keep it #[non_exhaustive]. 9 #[derive(Debug, Error)] 10 #[non_exhaustive] 11 pub enum ChargeError { 12 #[error("amount must be positive, got {0} cents")] 13 NonPositiveAmount(i64), 14 15 #[error("card declined: {reason}")] 16 Declined { reason: String }, 17 18 #[error("payment gateway I/O failed")] 19 Gateway(#[from] std::io::Error), 20 } 21 22 pub fn charge_cents(card: &str, amount: i64) -> Result<String, ChargeError> { 23 if amount <= 0 { 24 return Err(ChargeError::NonPositiveAmount(amount)); 25 } 26 if card == "4000000000000002" { 27 return Err(ChargeError::Declined { reason: "insufficient funds".into() }); 28 } 29 if card == "io-fail" { 30 // The `?` converts io::Error into ChargeError via #[from]. 31 return Err(std::io::Error::new(std::io::ErrorKind::TimedOut, "gateway timeout").into()); 32 } 33 Ok(format!("txn_{}", amount)) 34 } 35 } 36 37 use anyhow::{Context, Result}; 38 39 fn process_order(card: &str, amount: i64) -> Result<()> { 40 // The app doesn't care about each billing variant here; it adds context 41 // and lets the failure bubble up to a top-level handler. 42 let txn = billing::charge_cents(card, amount) 43 .with_context(|| format!( 44 "charging card ending {} for {amount}c", 45 &card[card.len().saturating_sub(4)..] 46 ))?; 47 println!("charged ok: {txn}"); 48 Ok(()) 49 } 50 51 fn main() { 52 // Where the app DOES want to react to a specific kind, it can downcast 53 // back to the concrete library error. 54 if let Err(e) = process_order("4000000000000002", 1299) { 55 println!("order failed: {e:#}"); 56 if let Some(billing::ChargeError::Declined { reason }) = 57 e.downcast_ref::<billing::ChargeError>() 58 { 59 println!(" -> declined specifically because: {reason}"); 60 } 61 } 62 63 let _ = process_order("4111111111111111", 500); 64 65 if let Err(e) = process_order("io-fail", 700) { 66 println!("order failed: {e:#}"); 67 } 68 } ``` Real output: ```text 1 order failed: charging card ending 0002 for 1299c: card declined: insufficient funds 2 -> declined specifically because: insufficient funds 3 charged ok: txn_500 4 order failed: charging card ending fail for 700c: payment gateway I/O failed: gateway timeout ``` The signature `Result<String, ChargeError>` documents the failure modes; the caller chooses between treating the error as opaque (`{e:#}`) and matching a specific variant (`downcast_ref`). *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The library half: `thiserror`, precise variants, `#[from]` [Section titled “The library half: thiserror, precise variants, #\[from\]”](#the-library-half-thiserror-precise-variants-from) * **`#[derive(Error)]`** (from [thiserror](/08-error-handling/06-anyhow-thiserror/)) generates the `Display` and `std::error::Error` impls so `ChargeError` is a fully-fledged error. The `#[error("…")]` attribute is the human message for each variant. * **Each failure mode is its own variant.** `NonPositiveAmount`, `Declined`, and `Gateway` are distinct so a caller can match exactly the one it can handle. This is the structured equivalent of the TypeScript `OutOfStockError` subclass, except the compiler *forces* the function to declare it in the return type. * **`#[from] std::io::Error`** generates `From<io::Error> for ChargeError`, which is what lets `?` convert a low-level error into our domain error (covered in [The `?` Operator](/08-error-handling/01-question-mark/) and [Handling Multiple Error Types](/08-error-handling/07-multiple-errors/)). * **`#[non_exhaustive]`** tells downstream crates “I may add variants later,” so their `match` must include a `_ =>` arm. This keeps adding a variant a non-breaking change. ### The application half: `anyhow`, context, bubble up [Section titled “The application half: anyhow, context, bubble up”](#the-application-half-anyhow-context-bubble-up) * **`fn process_order(...) -> anyhow::Result<()>`** uses `anyhow::Error`, a type-erased “any error” wrapper. The application generally does *not* want to enumerate every possible failure; it wants to attach a breadcrumb and move on. * **`.with_context(|| …)`** wraps whatever error came up with a human-readable layer. The closure form runs the `format!` *only on the error path*, so it’s free on success. * **`e.downcast_ref::<billing::ChargeError>()`** is the escape hatch: when the app genuinely needs to branch on a library variant, it can recover the concrete type from the erased `anyhow::Error`. This is the one place the app re-introduces structure. ### Where the analogy to TypeScript breaks down [Section titled “Where the analogy to TypeScript breaks down”](#where-the-analogy-to-typescript-breaks-down) In TypeScript, *throwing* is the same act whether the cause is bad user input or a bug; both unwind the stack and land in `catch (err: unknown)`. In Rust the two are different mechanisms entirely: recoverable failures are **values** (`Result`) the type system tracks, and bugs are **panics** that abort the current thread. You choose which one a given situation deserves. That choice is the heart of error-handling design and the next section covers it. *** ## Key Differences [Section titled “Key Differences”](#key-differences) ### Libraries vs. applications [Section titled “Libraries vs. applications”](#libraries-vs-applications) | Axis | Library crate | Application (binary) | | ------------------ | ------------------------------------------------- | ------------------------------------------ | | Primary goal | Let *callers* react programmatically | Get a useful message to a human; fail fast | | Typical error type | A concrete enum via `thiserror` | `anyhow::Error` (type-erased) | | Return type | `Result<T, MyError>` | `anyhow::Result<T>` | | Granularity | Fine: one variant per distinct failure | Coarse: context strings, not variants | | Stability | Public API; variant changes are semver | Internal; change freely | | Dependency cost | `thiserror` is compile-time only, no runtime type | `anyhow` adds a small runtime type | > **Tip:** A crate can be *both*. Many crates expose a `thiserror` enum publicly **and** use `anyhow` internally in their own binary/`examples`/tests. The rule is about the *boundary you expose*, not the whole project. ### Recoverable vs. unrecoverable [Section titled “Recoverable vs. unrecoverable”](#recoverable-vs-unrecoverable) | Situation | Mechanism | Why | | ------------------------------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------- | | Bad user input, missing file, network timeout, parse failure | `Result` / `Option` | Expected at runtime; the caller can reasonably handle it | | A broken invariant your code is supposed to guarantee | `panic!` / `assert!` / `expect` | It’s a *bug*; continuing would corrupt state | | ”This index is always valid because I just checked `len`” | `expect("…")` with a reason | Provable invariant; see [`unwrap` and `expect`](/08-error-handling/03-unwrap-expect/) | | Library code reacting to external conditions | almost always `Result` | A library should rarely decide to abort the caller’s process | The litmus test: **“Could a correct program, given valid inputs, still hit this?”** If yes, it’s a `Result`. If it can only happen because some code is wrong, it’s a panic. See [Panicking](/08-error-handling/02-panic/) for the full treatment. ### Error granularity [Section titled “Error granularity”](#error-granularity) The TypeScript instinct is often “one big error class with a `code` field.” In Rust, prefer **one variant per thing a caller might branch on**, but no finer. If two failures are always handled identically, merge them. If a caller will never distinguish two cases, don’t split them just because they have different messages; a single variant with a `String` detail (like `NotFound(String)`) is fine. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Using `String` (or `Box<dyn Error>`) as a library’s error type [Section titled “Pitfall 1: Using String (or Box\<dyn Error>) as a library’s error type”](#pitfall-1-using-string-or-boxdyn-error-as-a-librarys-error-type) `fn parse(...) -> Result<T, String>` compiles and feels easy, but it throws away everything a caller needs. They can `.contains("not found")` on your message, and then your next message tweak silently breaks them. For a public API, return an enum. (`Box<dyn Error>` has the same downside for *libraries*; it’s fine inside an app where you’d reach for `anyhow` anyway. See [Handling Multiple Error Types](/08-error-handling/07-multiple-errors/).) ### Pitfall 2: Trying to `?` an error your type can’t convert [Section titled “Pitfall 2: Trying to ? an error your type can’t convert”](#pitfall-2-trying-to--an-error-your-type-cant-convert) `?` only propagates an error if there is a `From` impl from the source error into your function’s error type. Forget it and you get a precise, real compiler error: ```rust 1 use thiserror::Error; 2 3 #[derive(Debug, Error)] 4 #[error("validation failed: {0}")] 5 struct ValidationError(String); 6 7 // Returns ValidationError, but tries to `?` a std::num::ParseIntError with no 8 // From<ParseIntError> for ValidationError. The ? cannot convert it. 9 fn parse_age(raw: &str) -> Result<u8, ValidationError> { 10 let age: u8 = raw.parse()?; // does not compile (error[E0271]) 11 Ok(age) 12 } ``` The real message from `cargo build`: ```text 1 error[E0271]: type mismatch resolving `<u8 as FromStr>::Err == ValidationError` 2 --> src/main.rs:10:23 3 | 4 10 | let age: u8 = raw.parse()?; // does not compile (error[E0271]) 5 | ^^^^^ expected `ValidationError`, found `ParseIntError` 6 7 For more information about this error, try `rustc --explain E0271`. ``` The fix is a `From` impl, usually `#[from]` on a variant in your `thiserror` enum, covered in [The `?` Operator](/08-error-handling/01-question-mark/). ### Pitfall 3: Fat error enums that bloat every `Result` [Section titled “Pitfall 3: Fat error enums that bloat every Result”](#pitfall-3-fat-error-enums-that-bloat-every-result) A `Result<T, E>` is as large as `T` *or* `E`, whichever is bigger, on **every** return, including the happy path. Inline a big field into one variant and you pay for it everywhere. Clippy catches both halves of this: ```rust 1 #[derive(Debug)] 2 pub enum ApiError { 3 NotFound, 4 Detailed([u8; 256]), // 256 bytes inlined into the error 5 } 6 7 pub fn find(id: u32) -> Result<u32, ApiError> { 8 if id == 0 { Err(ApiError::NotFound) } else { Ok(id) } 9 } ``` Real `cargo clippy` warnings (the snippet above placed at the top of `src/main.rs`): ```text 1 warning: large size difference between variants 2 --> src/main.rs:2:1 3 | 4 2 | / pub enum ApiError { 5 3 | | NotFound, 6 | | -------- the second-largest variant carries no data at all 7 4 | | Detailed([u8; 256]), // 256 bytes inlined into the error 8 | | ------------------- the largest variant contains at least 256 bytes 9 5 | | } 10 | |_^ the entire enum is at least 257 bytes 11 | 12 = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#large_enum_variant 13 = note: `#[warn(clippy::large_enum_variant)]` on by default 14 help: consider boxing the large fields or introducing indirection in some other way to reduce the total size of the enum 15 | 16 4 - Detailed([u8; 256]), // 256 bytes inlined into the error 17 4 + Detailed(Box<[u8; 256]>), // 256 bytes inlined into the error 18 | 19 20 warning: the `Err`-variant returned from this function is very large 21 --> src/main.rs:7:25 22 | 23 4 | Detailed([u8; 256]), // 256 bytes inlined into the error 24 | ------------------- the largest variant contains at least 256 bytes 25 ... 26 7 | pub fn find(id: u32) -> Result<u32, ApiError> { 27 | ^^^^^^^^^^^^^^^^^^^^^ 28 | 29 = help: try reducing the size of `ApiError`, for example by boxing large elements or replacing it with `Box<ApiError>` 30 = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#result_large_err 31 = note: `#[warn(clippy::result_large_err)]` on by default ``` The fix is to `Box` the large field (`Detailed(Box<[u8; 256]>)`) so the enum stays pointer-sized. ### Pitfall 4: Panicking inside a library on bad *input* [Section titled “Pitfall 4: Panicking inside a library on bad input”](#pitfall-4-panicking-inside-a-library-on-bad-input) A library function that does `let n: u32 = raw.parse().unwrap();` will abort the *caller’s* whole program when a user types garbage. Bad input is recoverable: return a `Result`. Reserve panics for violated invariants in your own code. (When `unwrap`/`expect` *are* acceptable — tests, prototypes, provable invariants — see [`unwrap` and `expect`](/08-error-handling/03-unwrap-expect/).) ### Pitfall 5: Sloppy error messages [Section titled “Pitfall 5: Sloppy error messages”](#pitfall-5-sloppy-error-messages) Rust messages compose into chains, so a message that reads fine alone can read badly in a chain. Avoid capital letters at the start, trailing periods, and the word “error:”; the framework adds the framing. “config key `port` is missing” composes into “loading config: config key `port` is missing”; “Error: Config key Port is missing.” does not. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Decide the boundary first: who consumes this error? [Section titled “1. Decide the boundary first: who consumes this error?”](#1-decide-the-boundary-first-who-consumes-this-error) If the answer is “other code that needs to branch,” design a `thiserror` enum. If it’s “a log file and a human,” use `anyhow`. Most projects are a tree: leaf library modules return enums; the binary at the root collects them with `anyhow`. ### 2. Write error messages like log lines: lowercase, no period, no “error:” [Section titled “2. Write error messages like log lines: lowercase, no period, no “error:””](#2-write-error-messages-like-log-lines-lowercase-no-period-no-error) Make each message a self-contained noun-phrase or short clause describing *what failed*, and let context layers describe *what you were doing*. The two combine cleanly: ```rust 1 use anyhow::{Context, Result}; 2 3 fn read_setting(raw: Option<&str>) -> Result<u32> { 4 // .context() takes an already-built value (cheap, eager). 5 let raw = raw.context("setting `max_retries` is required")?; 6 // .with_context() takes a closure: only runs the format! on the error path. 7 let n: u32 = raw 8 .parse() 9 .with_context(|| format!("setting `max_retries` has bad value `{raw}`"))?; 10 Ok(n) 11 } 12 13 fn main() { 14 if let Err(e) = read_setting(Some("five")) { 15 // {:#} = single-line, context chain joined with ": " 16 println!("single-line: {e:#}"); 17 // {:?} = multi-line "Caused by:" report (great for top-level logging) 18 println!("\nmulti-line:\n{e:?}"); 19 } 20 } ``` Real output: ```text 1 single-line: setting `max_retries` has bad value `five`: invalid digit found in string 2 3 multi-line: 4 setting `max_retries` has bad value `five` 5 6 Caused by: 7 invalid digit found in string ``` > **Tip:** Use `.context(value)` when the message is a constant string and `.with_context(|| …)` when building it costs a `format!`; the closure only runs on the error path. ### 3. Return `anyhow::Result<()>` from `main` in applications [Section titled “3. Return anyhow::Result<()> from main in applications”](#3-return-anyhowresult-from-main-in-applications) You get a free top-level handler: an `Err` is printed via its `Debug` impl (the full “Caused by:” chain) and the process exits non-zero. ```rust 1 use anyhow::{Context, Result}; 2 3 fn load_threshold() -> Result<u32> { 4 "abc".parse::<u32>().context("THRESHOLD must be an integer") 5 } 6 7 // A top-level Err is printed via its Debug impl and the process exits with code 1. 8 fn main() -> Result<()> { 9 let t = load_threshold()?; 10 println!("threshold = {t}"); 11 Ok(()) 12 } ``` Real output (and the shell reports exit code `1`): ```text 1 Error: THRESHOLD must be an integer 2 3 Caused by: 4 invalid digit found in string ``` ### 4. Keep public error enums `#[non_exhaustive]` [Section titled “4. Keep public error enums #\[non\_exhaustive\]”](#4-keep-public-error-enums-non_exhaustive) It lets you add variants later without a breaking change, at the small cost of requiring callers to include a `_ =>` arm. Worth it for any error type you publish. ### 5. Match granularity to caller behavior, not to message text [Section titled “5. Match granularity to caller behavior, not to message text”](#5-match-granularity-to-caller-behavior-not-to-message-text) Split a variant only when a caller would handle the two cases differently. Otherwise keep one variant and put the distinguishing detail in a field. ### 6. Panic for bugs, `Result` for conditions — and make panics loud [Section titled “6. Panic for bugs, Result for conditions — and make panics loud”](#6-panic-for-bugs-result-for-conditions--and-make-panics-loud) When you do panic, use `expect("reason this can't happen")` rather than a bare `unwrap()`, so the message explains the violated invariant. See [`unwrap` and `expect`](/08-error-handling/03-unwrap-expect/) and [Panicking](/08-error-handling/02-panic/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A common production shape: a recoverable parser that returns a precise enum, alongside a helper whose contract is enforced by a panic. The granularity is chosen so callers can recover from a *miss* but not from a *broken store*. ```rust 1 // Granularity chosen so callers can recover from one variant and not the other. 2 use thiserror::Error; 3 4 #[derive(Debug, Error)] 5 pub enum CacheError { 6 /// Caller CAN recover: treat it as a miss and recompute. 7 #[error("key `{0}` not found")] 8 NotFound(String), 9 10 /// Caller CANNOT recover here, but it's still an `Err`, not a panic: 11 /// the backing store is broken and the request should fail upward. 12 #[error("backing store unavailable: {0}")] 13 StoreUnavailable(String), 14 } 15 16 struct Cache; 17 18 impl Cache { 19 fn get(&self, key: &str) -> Result<String, CacheError> { 20 match key { 21 "user:1" => Ok("Ada".to_string()), 22 "down" => Err(CacheError::StoreUnavailable("connection refused".to_string())), 23 other => Err(CacheError::NotFound(other.to_string())), 24 } 25 } 26 } 27 28 fn lookup_or_default(cache: &Cache, key: &str) -> Result<String, CacheError> { 29 match cache.get(key) { 30 Ok(value) => Ok(value), 31 // Recover from the variant we know how to handle... 32 Err(CacheError::NotFound(_)) => Ok(format!("<default for {key}>")), 33 // ...and propagate the one we can't. 34 Err(e) => Err(e), 35 } 36 } 37 38 fn main() { 39 let cache = Cache; 40 for key in ["user:1", "user:999", "down"] { 41 match lookup_or_default(&cache, key) { 42 Ok(v) => println!("{key} -> {v}"), 43 Err(e) => println!("{key} -> ERROR: {e}"), 44 } 45 } 46 } ``` Real output: ```text 1 user:1 -> Ada 2 user:999 -> <default for user:999> 3 down -> ERROR: backing store unavailable: connection refused ``` Notice the design decisions baked in: two variants because callers treat them differently; both are `Err` (not a panic) because both are runtime conditions; the message is lowercase and chain-friendly; and `lookup_or_default` recovers from exactly one variant while propagating the rest. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [The Rust Book — Error Handling chapter](https://doc.rust-lang.org/book/ch09-00-error-handling.html): the canonical recoverable-vs-unrecoverable framing. * [The Rust Book — “To `panic!` or Not to `panic!`”](https://doc.rust-lang.org/book/ch09-03-to-panic-or-not-to-panic.html) — the official version of the decision guide on this page. * [Rust API Guidelines — Error types](https://rust-lang.github.io/api-guidelines/interoperability.html#error-types-are-meaningful-and-well-behaved-c-good-err): what a *good* public error type looks like. * [`std::error::Error`](https://doc.rust-lang.org/std/error/trait.Error.html) — the trait every error implements; see [The `Error` Trait](/08-error-handling/05-error-trait/). * [Clippy lint: `result_large_err`](https://rust-lang.github.io/rust-clippy/master/index.html#result_large_err) and [`large_enum_variant`](https://rust-lang.github.io/rust-clippy/master/index.html#large_enum_variant). ### Related sections in this guide [Section titled “Related sections in this guide”](#related-sections-in-this-guide) * [Result and Option](/08-error-handling/00-result-option/): the `Result`/`Option` types these decisions are built on. * [The `?` Operator](/08-error-handling/01-question-mark/) — `?` and `From`-based conversion. * [Panicking](/08-error-handling/02-panic/): when a panic is the right call. * [`unwrap` and `expect`](/08-error-handling/03-unwrap-expect/) — when `unwrap`/`expect` are acceptable. * [Custom Error Types](/08-error-handling/04-custom-errors/): defining the enums/structs by hand. * [The `Error` Trait](/08-error-handling/05-error-trait/) — `Display`, `Debug`, and the `source()` chain. * [`anyhow` & `thiserror`](/08-error-handling/06-anyhow-thiserror/): the crates that implement the library/app split. * [Handling Multiple Error Types](/08-error-handling/07-multiple-errors/) — aggregating several error types. * Foundations: [Section 00 — Introduction](/00-introduction/), [Section 01 — Getting Started](/01-getting-started/), [Section 02 — Basics](/02-basics/). * Next up: [Section 09 — Generics & Traits](/09-generics-traits/), which explains the trait machinery (`From`, `Display`, `Error`) these patterns rely on. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Turn a stringly-typed error into a matchable enum [Section titled “Exercise 1: Turn a stringly-typed error into a matchable enum”](#exercise-1-turn-a-stringly-typed-error-into-a-matchable-enum) **Difficulty:** Easy **Objective:** Practice choosing the right granularity for a library function’s error type. **Instructions:** 1. Start from `fn parse_celsius(raw: &str) -> Result<f64, String>` that fails on (a) empty input, (b) non-numeric input, and (c) a value below absolute zero (`-273.15`). 2. Replace the `String` error with a `thiserror` enum that has one variant per failure mode, with clear, chain-friendly messages. 3. Add `#[derive(PartialEq)]` so the cases are easy to assert on, and verify with a few assertions. Solution ```rust 1 use thiserror::Error; 2 3 #[derive(Debug, Error, PartialEq)] 4 pub enum ParseTempError { 5 #[error("empty input")] 6 Empty, 7 #[error("`{0}` is not a number")] 8 NotANumber(String), 9 #[error("{0}°C is below absolute zero (-273.15)")] 10 BelowAbsoluteZero(f64), 11 } 12 13 pub fn parse_celsius(raw: &str) -> Result<f64, ParseTempError> { 14 let raw = raw.trim(); 15 if raw.is_empty() { 16 return Err(ParseTempError::Empty); 17 } 18 let n: f64 = raw 19 .parse() 20 .map_err(|_| ParseTempError::NotANumber(raw.to_string()))?; 21 if n < -273.15 { 22 return Err(ParseTempError::BelowAbsoluteZero(n)); 23 } 24 Ok(n) 25 } 26 27 fn main() { 28 assert_eq!(parse_celsius("21.5"), Ok(21.5)); 29 assert_eq!(parse_celsius(" "), Err(ParseTempError::Empty)); 30 assert_eq!( 31 parse_celsius("hot"), 32 Err(ParseTempError::NotANumber("hot".to_string())) 33 ); 34 assert_eq!( 35 parse_celsius("-300"), 36 Err(ParseTempError::BelowAbsoluteZero(-300.0)) 37 ); 38 println!("exercise 1 ok"); 39 } ``` Each failure is a distinct variant, so a caller can branch on exactly the one it cares about. The messages are lowercase and self-contained so they compose into context chains. Output: `exercise 1 ok`. ### Exercise 2: Draw the library/application boundary [Section titled “Exercise 2: Draw the library/application boundary”](#exercise-2-draw-the-libraryapplication-boundary) **Difficulty:** Medium **Objective:** Build a small library module with a typed error and an application layer that consumes it with `anyhow`, recovering structure only where needed. **Instructions:** 1. Write a module `inventory` with `fn reserve(sku: &str, requested: u32) -> Result<u32, InventoryError>`. `InventoryError` (a `thiserror`, `#[non_exhaustive]` enum) should distinguish an unknown SKU from insufficient stock. 2. In application code, write `fn fulfill(sku: &str, qty: u32) -> anyhow::Result<()>` that calls `reserve`, adds context with `.with_context`, and propagates with `?`. 3. In `main`, when fulfilling an *unknown* SKU fails, `downcast_ref` back to `InventoryError` and print a SKU-specific suggestion. Solution ```rust 1 mod inventory { 2 use thiserror::Error; 3 4 #[derive(Debug, Error)] 5 #[non_exhaustive] 6 pub enum InventoryError { 7 #[error("no such SKU `{0}`")] 8 UnknownSku(String), 9 #[error("SKU `{sku}` has only {available} in stock, requested {requested}")] 10 Insufficient { sku: String, requested: u32, available: u32 }, 11 } 12 13 pub fn reserve(sku: &str, requested: u32) -> Result<u32, InventoryError> { 14 let available = match sku { 15 "WIDGET" => 3, 16 "GADGET" => 0, 17 other => return Err(InventoryError::UnknownSku(other.to_string())), 18 }; 19 if requested > available { 20 return Err(InventoryError::Insufficient { 21 sku: sku.to_string(), 22 requested, 23 available, 24 }); 25 } 26 Ok(available - requested) 27 } 28 } 29 30 use anyhow::{Context, Result}; 31 32 fn fulfill(sku: &str, qty: u32) -> Result<()> { 33 let remaining = inventory::reserve(sku, qty) 34 .with_context(|| format!("fulfilling order for {qty}x {sku}"))?; 35 println!("reserved {qty}x {sku}, {remaining} left"); 36 Ok(()) 37 } 38 39 fn main() { 40 let _ = fulfill("WIDGET", 2); 41 if let Err(e) = fulfill("WIDGET", 99) { 42 println!("error: {e:#}"); 43 } 44 if let Err(e) = fulfill("MYSTERY", 1) { 45 // App reacts specifically to one library variant by downcasting. 46 if let Some(inventory::InventoryError::UnknownSku(sku)) = 47 e.downcast_ref::<inventory::InventoryError>() 48 { 49 println!("please add `{sku}` to the catalog"); 50 } 51 } 52 } ``` Output: ```text 1 reserved 2x WIDGET, 1 left 2 error: fulfilling order for 99x WIDGET: SKU `WIDGET` has only 3 in stock, requested 99 3 please add `MYSTERY` to the catalog ``` The library exposes structure (`InventoryError`); the app stays coarse with `anyhow` and only re-introduces structure via `downcast_ref` where it genuinely reacts to a variant. ### Exercise 3: Choose recoverable vs. unrecoverable [Section titled “Exercise 3: Choose recoverable vs. unrecoverable”](#exercise-3-choose-recoverable-vs-unrecoverable) **Difficulty:** Medium **Objective:** Decide, for two functions, whether failure is a recoverable condition (`Result`) or a programmer bug (`panic`), and back the decision with tests. **Instructions:** 1. Write `parse_hex_byte(raw: &str) -> Result<u8, String>` (recoverable — input may be malformed) and `channel_name(index: usize) -> &'static str` mapping `0..4` to `"red"/"green"/"blue"/"alpha"`. 2. Treat an out-of-range `index` as a *bug*: let indexing panic rather than returning a `Result`. 3. Write tests proving the parser returns `Err` on bad input and that `channel_name(9)` panics (use `#[should_panic]`). Solution ```rust 1 /// Recoverable: user input may be malformed -> Result. 2 pub fn parse_hex_byte(raw: &str) -> Result<u8, String> { 3 u8::from_str_radix(raw.trim_start_matches("0x"), 16) 4 .map_err(|_| format!("`{raw}` is not a valid hex byte")) 5 } 6 7 /// Internal invariant: callers must pass an index < 4. A violation is a BUG, 8 /// so we let indexing panic rather than returning Result. 9 pub fn channel_name(index: usize) -> &'static str { 10 const CHANNELS: [&str; 4] = ["red", "green", "blue", "alpha"]; 11 CHANNELS[index] 12 } 13 14 fn main() { 15 println!("{:?}", parse_hex_byte("0xFF")); 16 println!("{:?}", parse_hex_byte("zz")); 17 println!("channel 2 = {}", channel_name(2)); 18 } 19 20 #[cfg(test)] 21 mod tests { 22 use super::*; 23 24 #[test] 25 fn parses_valid_hex() { 26 assert_eq!(parse_hex_byte("0x1A"), Ok(26)); 27 } 28 29 #[test] 30 fn rejects_invalid_hex() { 31 assert!(parse_hex_byte("nope").is_err()); 32 } 33 34 #[test] 35 #[should_panic] 36 fn channel_out_of_range_panics() { 37 let _ = channel_name(9); 38 } 39 } ``` `cargo run` prints: ```text 1 Ok(255) 2 Err("`zz` is not a valid hex byte") 3 channel 2 = blue ``` And `cargo test` reports `3 passed`. The parser returns a `Result` because malformed input is an expected runtime condition; `channel_name` panics on a bad index because only buggy calling code could produce one. # Rust Generics & Traits for TS Devs > Map TypeScript generics and interfaces onto Rust's monomorphized generics and nominal traits, with trait bounds, trait objects, and coherence rules explained. In TypeScript you reach for `<T>` generics when you want one function or class to work over many types, and `interface` when you want to describe a shared shape. Rust offers the same two ideas — **generics** and **traits** — but builds them on a different foundation. Generics are **monomorphized** into specialized machine code at compile time (not erased like TypeScript’s), traits are **nominal** contracts you opt into with explicit `impl` blocks (not structural), and the whole system is governed by **trait bounds**, **trait objects** for opt-in dynamic dispatch, and **coherence** rules that prevent two crates from clashing. This section maps each TypeScript habit onto its idiomatic Rust counterpart, so you can write polymorphic, zero-cost-abstraction code the Rust way. *** ## What You’ll Learn [Section titled “What You’ll Learn”](#what-youll-learn) * How TypeScript `<T>` generic functions become Rust `fn f<T>(...)`, and why **monomorphization** (one specialized copy per concrete type) differs from TypeScript’s **type erasure**; plus the **turbofish** `::<>` for when inference needs a hint * How to put type parameters on **structs** and **enums**, including multiple type parameters and constraints attached to `impl` blocks, with `Option<T>` and `Result<T, E>` as the canonical generic enums * How a TypeScript `interface` becomes a **trait**, written as a separate `impl Trait for Type` block, and the difference between **required** and **provided (default)** methods * How to constrain generics with **trait bounds** (`<T: Trait>`, multiple bounds with `+`, and `where` clauses), including bounds on return types * When to use **trait objects** (`&dyn Trait`, `Box<dyn Trait>`) for runtime dynamic dispatch, what **dyn compatibility** (object safety) requires, and the static-vs-dynamic dispatch trade-off * How **`impl Trait`** works in argument and return position (RPIT), with a note on return-position `impl Trait` in traits (RPITIT) * How **default method implementations** and **supertraits** (one trait requiring another) reduce boilerplate and express prerequisites * How to overload operators (`Add`, `Sub`, `Mul`, `Index`, …) by implementing the corresponding traits, and what the **marker traits** `Send`, `Sync`, `Copy`, and `Sized` signal to the compiler * Why the **orphan rule** forbids implementing a foreign trait for a foreign type, and the **newtype** pattern that works around it *** ## Topics [Section titled “Topics”](#topics) | Topic | Description | | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | [Generic Functions](/09-generics-traits/00-generic-functions/) | Generic functions `<T>`; monomorphization vs TypeScript type erasure; the turbofish `::<>`. | | [Generic Structs](/09-generics-traits/01-generic-structs/) | Generic data structures; multiple type parameters; constraints attached to `impl` blocks. | | [Generic Enums](/09-generics-traits/02-generic-enums/) | Generic enums, with `Option<T>` and `Result<T, E>` as the canonical examples. | | [Traits](/09-generics-traits/03-traits/) | Interfaces → traits: defining and implementing a trait via the `impl Trait for Type` syntax. | | [Trait Methods](/09-generics-traits/04-trait-methods/) | Required vs provided (default) methods; calling them and overriding defaults. | | [Trait Bounds](/09-generics-traits/05-trait-bounds/) | Trait bounds `<T: Trait>`, multiple bounds, `where` clauses, and bounds on return types. | | [Trait Objects](/09-generics-traits/06-trait-objects/) | Dynamic dispatch: `&dyn Trait` / `Box<dyn Trait>`, dyn compatibility, and static-vs-dynamic trade-offs. | | [`impl Trait`](/09-generics-traits/07-impl-trait/) | `impl Trait` in argument and return position (RPIT), with a brief note on RPITIT. | | [Default Implementations](/09-generics-traits/08-default-impls/) | Default method bodies and how they cut implementation boilerplate. | | [Supertraits](/09-generics-traits/09-supertraits/) | Supertraits (trait inheritance): requiring one trait as a prerequisite for another. | | [Operator Overloading](/09-generics-traits/10-operator-overloading/) | Operator traits `Add`, `Sub`, `Mul`, `Index`, and friends; implementing `+` for your own type. | | [Marker Traits](/09-generics-traits/11-marker-traits/) | Marker traits `Send`, `Sync`, `Copy`, `Sized`: what they signal, and auto traits. | | [The Orphan Rule](/09-generics-traits/12-orphan-rule/) | Coherence and the orphan rule; why you cannot impl a foreign trait for a foreign type; the newtype workaround. | *** ## Learning Objectives [Section titled “Learning Objectives”](#learning-objectives) By the end of this section, you will be able to: * Write generic functions, structs, and enums, and explain how monomorphization turns one generic source into specialized, zero-cost concrete code * Reach for the turbofish `::<>` or a binding annotation exactly when inference needs help, and not before * Define traits, implement them with `impl Trait for Type`, and distinguish required methods from provided (default) ones * Constrain a generic with the loosest trait bounds that compile, using `+` and `where` clauses for readability * Choose deliberately between static dispatch (generics / `impl Trait`) and dynamic dispatch (`dyn Trait`), and recognize when a trait is not dyn compatible * Use `impl Trait` in argument and return position, and know when a trait method that returns an `impl Trait` (RPITIT) is appropriate * Eliminate boilerplate with default method implementations and express prerequisites with supertraits * Overload operators by implementing the relevant `std::ops` traits, and read what `Send`, `Sync`, `Copy`, and `Sized` tell the compiler * Diagnose an orphan-rule error (`E0117`) and resolve it by owning the trait or applying the newtype pattern *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * [Section 06: Data Structures](/06-data-structures/) — structs, enums, `Option<T>`, pattern matching, and `impl` blocks; this section generalizes all of them with type parameters and trait contracts (and completes the light introduction to associated types started there) * [Section 05: Ownership](/05-ownership/): what `&self`, `&mut self`, and `self` receivers mean, plus moves, borrows, and `Clone`, all of which trait method signatures depend on * [Section 02: Basics](/02-basics/): concrete types (`i32`, `f64`, `String`), immutability by default, and `#[derive(...)]`-style trait derivation *** ## Estimated Time [Section titled “Estimated Time”](#estimated-time) * **Reading:** 5-6 hours * **Hands-on Practice:** 4-5 hours * **Exercises:** 3 hours * **Total:** 12-14 hours > **Tip:** Read the topics roughly in listed order. Generics (functions, structs, enums) teach you to abstract over *types*; traits, their methods, and bounds teach you to abstract over *behavior*; trait objects and `impl Trait` are the two dispatch strategies that tie them together; and operator overloading, marker traits, and the orphan rule are the practical edges you will hit in real code. The biggest mental shift for a TypeScript developer is that Rust generics are **monomorphized** (real specialized code, not erased) and traits are **nominal** (you must write an explicit `impl`, not just match a shape). *** ## Frequently asked questions [Section titled “Frequently asked questions”](#frequently-asked-questions) ### What is a trait? [Section titled “What is a trait?”](#what-is-a-trait) A set of methods a type promises to provide, like a TypeScript interface. You write `impl Trait for Type` separately from both the trait and the type, which lets you add behaviour to types you did not define and powers generics and dynamic dispatch. See [Traits](/09-generics-traits/03-traits/). ### What is the difference between `impl Trait` and `dyn Trait`? [Section titled “What is the difference between impl Trait and dyn Trait?”](#what-is-the-difference-between-impl-trait-and-dyn-trait) `impl Trait` and generics pick the concrete type at compile time and inline it (static dispatch, zero cost). `dyn Trait` is a trait object that chooses the method at runtime through a vtable, like a virtual method call. See [impl Trait](/09-generics-traits/07-impl-trait/) and [Trait Objects](/09-generics-traits/06-trait-objects/). ### How are Rust generics different from TypeScript’s? [Section titled “How are Rust generics different from TypeScript’s?”](#how-are-rust-generics-different-from-typescripts) TypeScript generics are erased and only constrain shape. Rust generics are monomorphized into specialized code per type and constrained by trait bounds like `T: Display`, so they also guarantee which operations are available. See [Generic Functions](/09-generics-traits/00-generic-functions/) and [Trait Bounds](/09-generics-traits/05-trait-bounds/). *** **Next:** [Section 10: Smart Pointers →](/10-smart-pointers/): `Box`, `Rc`/`Arc`, `RefCell`/`Mutex`, `Cow`, and `Weak`, where `Box<dyn Trait>` from this section ties generics and trait objects to heap allocation. # Generic Functions > Write one Rust function for many types, like a TypeScript generic, but monomorphized into specialized, zero-cost code at compile time, with trait bounds on T. Generic functions let you write one function that works for many types, without giving up type safety. If you have ever written `function first<T>(arr: T[]): T` in TypeScript, you already know the shape of the idea. But Rust compiles generics in a fundamentally different way, and that difference has real consequences for performance, error messages, and what you can and cannot do at runtime. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **generic function** is parameterized over one or more types written in angle brackets (`fn name<T>(...)`). The same source produces a separate, specialized machine-code copy for each concrete type it is used with: a process called **monomorphization**. This is the opposite of TypeScript, where generics are erased before the code ever runs, so a TS dev’s main adjustment is realizing that in Rust generics are a *compile-time* mechanism with *zero runtime cost*, not a runtime feature. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // TypeScript - generic functions with type parameters 2 function first<T>(items: T[]): T { 3 return items[0]; 4 } 5 6 function pair<A, B>(a: A, b: B): [A, B] { 7 return [a, b]; 8 } 9 10 // The type parameter is inferred from the arguments... 11 const n = first([10, 20, 30]); // T = number, n: number 12 const s = first(["a", "b"]); // T = string, s: string 13 const p = pair(1, "one"); // A = number, B = string 14 15 // ...or supplied explicitly with the same angle-bracket syntax: 16 const x = first<number>([1, 2, 3]); 17 18 // At RUNTIME, T is gone. This compiles and runs — and crashes: 19 function bad<T>(items: T[]): T { 20 return items[0]; 21 } 22 console.log(bad<number>([])); // undefined — no error, types were erased ``` **Key points:** * `<T>` declares a type parameter; TypeScript infers it from arguments. * Generics are a **compile-time-only** check. `tsc` erases them and emits plain JavaScript; there is no `T` left at runtime. * Because the types are gone, you cannot inspect `T`, branch on it, or `new T()`. And mistakes the types *should* have caught (like indexing an empty array) still produce `undefined` at runtime. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 // Rust - the same two functions, with type parameters in <> 2 fn first<T>(items: &[T]) -> &T { 3 &items[0] 4 } 5 6 fn pair<A, B>(a: A, b: B) -> (A, B) { 7 (a, b) 8 } 9 10 fn main() { 11 let nums = [10, 20, 30]; 12 let n = first(&nums); // T = i32, inferred from the argument 13 println!("first: {n}"); 14 15 let words = ["a", "b"]; 16 let s = first(&words); // T = &str, inferred 17 println!("first: {s}"); 18 19 let p = pair(1, "one"); // A = i32, B = &str 20 println!("pair: {p:?}"); // prints: pair: (1, "one") 21 } ``` Real output from `cargo run`: ```text 1 first: 10 2 first: a 3 pair: (1, "one") ``` **Key points:** * The syntax is strikingly similar: `fn first<T>(...)`. * Rust infers `T` from arguments just like TypeScript. * But unlike TypeScript, `first(&nums)` and `first(&words)` cause the compiler to **generate two distinct copies** of `first`: one specialized for `i32`, one for `&str`. The generic is resolved entirely at compile time, then erased into concrete, optimized code. > **Note:** Rust borrows the slice (`&[T]`) instead of taking ownership of an array. We will not dwell on borrowing here — see [Section 05: Ownership](/05-ownership/) — but notice `first` returns `&T` (a reference), so it does not have to copy the element out. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Declaring and inferring type parameters [Section titled “Declaring and inferring type parameters”](#declaring-and-inferring-type-parameters) ```rust 1 fn first<T>(items: &[T]) -> &T { 2 &items[0] 3 } ``` * `<T>` after the function name introduces the type parameter. `T` is just a name; `U`, `Item`, or `Value` work equally well, though single uppercase letters are the convention for “any type.” * Inside the body, `T` stands for whatever concrete type the caller uses. You may use `T` in the parameter list (`&[T]`), the return type (`&T`), and local bindings. * At the call site `first(&nums)`, Rust unifies `&[T]` with `&[i32; 3]` (coerced to `&[i32]`) and concludes `T = i32`. No annotation needed. ### Monomorphization: the big mental shift from TypeScript [Section titled “Monomorphization: the big mental shift from TypeScript”](#monomorphization-the-big-mental-shift-from-typescript) This is the single most important idea for a TS/JS developer. TypeScript **erases** generics; Rust **monomorphizes** them. When you call a generic function with `i32` and with `f64`, the compiler stamps out two separate functions, each with the concrete type baked in, exactly as if you had hand-written `id_i32` and `id_f64`. We can prove it. Compiling this program to LLVM IR: ```rust 1 use std::hint::black_box; 2 3 #[inline(never)] 4 pub fn id<T>(x: T) -> T { 5 x 6 } 7 8 fn main() { 9 let a = id::<i32>(black_box(5)); 10 let b = id::<f64>(black_box(2.5)); 11 println!("{} {}", black_box(a), black_box(b)); 12 } ``` …produces two distinct, fully concrete definitions of `id` in the emitted IR: one taking an `i32`, one taking a `double` (Rust’s `f64`): ```text 1 define internal i32 @_ZN4mono2id17h73ef7d59100e96ddE(i32 %x) ... 2 define internal double @_ZN4mono2id17h901c7050e1366328E(double %x) ... ``` > **Note:** Those two `define` lines are real output from `rustc --emit=llvm-ir`. The `i32` copy and the `double` (f64) copy are genuinely separate machine functions generated from one generic source. The consequences for a TypeScript developer: | Aspect | TypeScript (erasure) | Rust (monomorphization) | | ------------------------------- | ------------------------------------- | -------------------------------------------------------- | | When is `T` resolved? | Compile time, then erased | Compile time, then specialized into concrete code | | Runtime representation of `T` | None; it does not exist | None needed, every copy is concrete | | Runtime cost of generics | The code is just plain JS | **Zero**, as fast as hand-written concrete code | | Can you inspect `T` at runtime? | No (`typeof` sees the value, not `T`) | No (and you rarely need to) | | Effect on binary/output size | None (one copy) | Larger binary: one copy **per type used** (“code bloat”) | | Compile time | Fast | Slower; more code to generate and optimize | The headline win is **zero-cost abstraction**: a generic `first<T>` is exactly as fast as a `first_i32` you wrote by hand, because after monomorphization that is literally what exists. The trade-off is binary size and compile time, since each instantiation is real code. ### Inferred vs explicit type arguments — the turbofish `::<>` [Section titled “Inferred vs explicit type arguments — the turbofish ::<>”](#inferred-vs-explicit-type-arguments--the-turbofish-) Most of the time Rust infers the type parameter. When it cannot, or when you want to be explicit, you supply the type argument. In an expression, that uses the **turbofish** syntax `::<>`: ```rust 1 fn largest<T: PartialOrd + Copy>(list: &[T]) -> T { 2 let mut max = list[0]; 3 for &item in list { 4 if item > max { 5 max = item; 6 } 7 } 8 max 9 } 10 11 fn main() { 12 // Inferred from the argument: 13 let m = largest(&[3, 9, 1]); 14 println!("{m}"); 15 16 // Explicit, using the turbofish on the function name: 17 let m = largest::<i32>(&[3, 9, 1]); 18 println!("{m}"); 19 } ``` The name “turbofish” comes from the `::<>` glyph resembling a fish. Why the leading `::`? Because `largest<i32>(...)` would be ambiguous to the parser: `<` could be the less-than operator. The `::` disambiguates “this is a type argument list,” not a comparison. You will see the turbofish most often on standard-library methods whose return type the compiler cannot otherwise pin down: ```rust 1 fn main() { 2 // `parse` is generic over its return type; tell it what to produce: 3 let n = "42".parse::<i32>().unwrap(); 4 println!("{n}"); // 42 5 6 // `collect` builds "some collection" — turbofish picks which one: 7 let v = (0..3).collect::<Vec<i32>>(); 8 println!("{v:?}"); // [0, 1, 2] 9 } ``` Equivalently, you can move the type to the *binding* and let inference flow backward; these two lines are interchangeable: ```rust 1 fn main() { 2 let v = (0..3).collect::<Vec<i32>>(); // turbofish on the method 3 let v: Vec<i32> = (0..3).collect(); // annotation on the variable 4 println!("{v:?}"); 5 } ``` This “type flows backward from the annotation” behavior has no real TypeScript analog: in TS you almost always write `[...]` and the array type is concrete already. ### Generic functions usually need trait bounds [Section titled “Generic functions usually need trait bounds”](#generic-functions-usually-need-trait-bounds) In TypeScript a bare `<T>` is fully usable: you can pass it around, put it in arrays, return it. In Rust a bare `<T>` is deliberately *almost useless*: you can move it, return it, or store it, but you cannot do anything that requires a *capability*, because the compiler must guarantee the operation works for **every** possible `T`. Comparing with `>`, adding with `+`, or printing with `{}` are all capabilities you must request via **trait bounds** (`T: PartialOrd`, `T: Display`, …). That is why `largest` above is written `largest<T: PartialOrd + Copy>` rather than just `largest<T>`. Trait bounds are a topic of their own — see [Trait Bounds](/09-generics-traits/05-trait-bounds/) — but you cannot write many generic functions without at least one, so they appear here too. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript | Rust | | ---------------------- | ---------------------------------------------- | ----------------------------------------------------- | | Declaration | `function f<T>(x: T): T` | `fn f<T>(x: T) -> T` | | Inference | Yes, from arguments | Yes, from arguments | | Explicit type arg | `f<number>(x)` | `f::<i32>(x)` (turbofish in expressions) | | Compilation model | **Erasure**: one runtime copy | **Monomorphization**: one copy per concrete type | | Runtime cost | None (it is just JS) | Zero (specialized to concrete code) | | Capabilities on `T` | Anything; unsound casts via `any` slip through | Only what **trait bounds** permit; checked | | ”Empty” bound `<T>` | Fully usable | Can only move/store/return, no operations | | Inspect `T` at runtime | No | No (use enums/trait objects for runtime polymorphism) | | Binary size impact | None | Grows with number of instantiations | The conceptual core: **TypeScript generics are a type-checker feature that disappears; Rust generics are a code-generation feature.** Rust trades larger binaries and slower compiles for code that is as fast as if you had never used generics at all, and for the guarantee that every operation on `T` is provably valid for every `T` you actually use. > **Tip:** Reach for generics when you want one implementation specialized per type at compile time (the common case). When you instead need *runtime* polymorphism — a heterogeneous list of “things that implement `Draw`,” chosen at runtime — that is [trait objects](/09-generics-traits/06-trait-objects/) (`dyn Trait`), Rust’s dynamic-dispatch counterpart. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting a trait bound when you operate on `T` [Section titled “Pitfall 1: Forgetting a trait bound when you operate on T”](#pitfall-1-forgetting-a-trait-bound-when-you-operate-on-t) A TypeScript dev expects `T` to “just work” with `>` or `+`. Rust refuses, because it cannot prove those operations are valid for every `T`. ```rust 1 // does not compile (error E0369: binary operation `>` cannot be applied to type `T`) 2 fn largest<T>(list: &[T]) -> T { 3 let mut max = list[0]; 4 for &item in list { 5 if item > max { 6 max = item; 7 } 8 } 9 max 10 } ``` Real compiler output: ```text 1 error[E0369]: binary operation `>` cannot be applied to type `T` 2 --> err1.rs:4:17 3 | 4 4 | if item > max { 5 | ---- ^ --- T 6 | | 7 | T 8 | 9 help: consider restricting type parameter `T` with trait `PartialOrd` 10 | 11 1 | fn largest<T: std::cmp::PartialOrd>(list: &[T]) -> T { 12 | ++++++++++++++++++++++ ``` The compiler even writes the fix for you: add `T: PartialOrd`. (For comparing-and-copying scalars like `i32`, you typically also want `+ Copy`, as in the working version above.) The same thing happens with `+`: ```rust 1 // does not compile (error E0369: cannot add `T` to `T`) 2 fn add<T>(a: T, b: T) -> T { 3 a + b 4 } ``` ```text 1 error[E0369]: cannot add `T` to `T` 2 --> err4.rs:2:7 3 | 4 2 | a + b 5 | - ^ - T 6 | | 7 | T 8 | 9 help: consider restricting type parameter `T` with trait `Add` 10 | 11 1 | fn add<T: std::ops::Add<Output = T>>(a: T, b: T) -> T { 12 | +++++++++++++++++++++++++++ ``` ### Pitfall 2: Ambiguous return type — the compiler needs a turbofish or annotation [Section titled “Pitfall 2: Ambiguous return type — the compiler needs a turbofish or annotation”](#pitfall-2-ambiguous-return-type--the-compiler-needs-a-turbofish-or-annotation) `parse` and `collect` are generic over what they *produce*. With nothing to pin the result type, inference fails: ```rust 1 // does not compile (error E0284: type annotations needed) 2 fn main() { 3 let n = "42".parse().unwrap(); 4 println!("{n}"); 5 } ``` ```text 1 error[E0284]: type annotations needed 2 --> err2.rs:2:9 3 | 4 2 | let n = "42".parse().unwrap(); 5 | ^ ----- type must be known at this point 6 | 7 = note: cannot satisfy `<_ as FromStr>::Err == _` 8 help: consider giving `n` an explicit type 9 | 10 2 | let n: /* Type */ = "42".parse().unwrap(); 11 | ++++++++++++ ``` Fix it with the turbofish (`"42".parse::<i32>()`) or a binding annotation (`let n: i32 = ...`). `collect` gives the analogous `E0283`: ```text 1 error[E0283]: type annotations needed 2 --> err3.rs:2:9 3 | 4 2 | let v = (0..5).collect(); 5 | ^ ------- type must be known at this point 6 | 7 = note: cannot satisfy `_: FromIterator<i32>` 8 note: required by a bound in `collect` 9 --> .../library/core/src/iter/traits/iterator.rs:2014:19 10 | 11 2014 | fn collect<B: FromIterator<Self::Item>>(self) -> B 12 | ^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `Iterator::collect` 13 help: consider giving `v` an explicit type 14 | 15 2 | let v: Vec<_> = (0..5).collect(); 16 | ++++++++ ``` ### Pitfall 3: Expecting to inspect or branch on `T` at runtime [Section titled “Pitfall 3: Expecting to inspect or branch on T at runtime”](#pitfall-3-expecting-to-inspect-or-branch-on-t-at-runtime) Because generics are monomorphized and then erased into concrete code, there is no runtime “type object” to look at. There is no `typeof T`, no `if (T === Number)`, no `new T()`. If you need to make a runtime decision based on the variant, that is a job for an [`enum`](/09-generics-traits/02-generic-enums/) or a [trait object](/09-generics-traits/06-trait-objects/), not for generics. This mirrors TypeScript’s erasure (you cannot do `if (T === ...)` in TS either), but TS devs sometimes *think* they can via `instanceof` on values, which checks the runtime value, not the erased type parameter. ### Pitfall 4: Assuming generics are “free” like in TypeScript [Section titled “Pitfall 4: Assuming generics are “free” like in TypeScript”](#pitfall-4-assuming-generics-are-free-like-in-typescript) In TypeScript a generic costs nothing at runtime and nothing in output size; it is the same emitted JS. In Rust, every distinct type you instantiate a generic with generates another copy of the code. Calling `largest` with `i32`, `f64`, `char`, and `u8` produces four specialized functions. This is usually a non-issue, but for very large generic functions used with many types it can bloat the binary and slow compiles. When that matters, you can extract the type-independent work into a non-generic inner function (a technique sometimes called “outlining”). *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Let inference do the work.** Write `let n = parse_count(input);` and only add a turbofish or annotation when the compiler asks. Over-annotating reads as noise. * **Add the minimum bounds you need, no more.** Each bound is a promise the caller must keep. `T: PartialOrd` is weaker (more permissible) than `T: Ord`; pick the loosest one that compiles. See [Trait Bounds](/09-generics-traits/05-trait-bounds/). * **Name type parameters meaningfully when it aids clarity.** `T` is fine for a one-off, but `fn group_by<T, K, F>(...)` reading “item, key, function” is clearer than `<A, B, C>`. * **Prefer borrowing generic inputs (`&[T]`, `&T`)** over taking ownership when you only need to read, so callers are not forced to give up their data. * **Reach for `impl Trait` in argument position** for simple “accept any iterator / any closure” cases; it is a lighter-weight sugar over a generic parameter. See [`impl Trait`](/09-generics-traits/07-impl-trait/). * **Use generics for compile-time, same-shape-per-type code; use `dyn Trait` for runtime, heterogeneous collections.** Knowing which axis you are on prevents fighting the borrow checker later. > **Tip:** When you find yourself writing the same function body twice for `i32` and `f64`, that is the signal to make it generic. When you find yourself wanting a `Vec` holding *several different* concrete types at once, that is the signal you want a trait object instead. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small data-pipeline module: two reusable, fully generic helpers, `group_by` (bucket items by a derived key) and `max_by_key` (find the “biggest” item by a derived score). Both are parameterized over the element type *and* a closure, so they work for any data the caller throws at them. This is the kind of generic utility you would otherwise reach for Lodash to provide in TypeScript. ```rust 1 use std::collections::HashMap; 2 use std::hash::Hash; 3 4 /// Group items into buckets keyed by a value derived from each item. 5 fn group_by<T, K, F>(items: Vec<T>, key_of: F) -> HashMap<K, Vec<T>> 6 where 7 K: Eq + Hash, 8 F: Fn(&T) -> K, 9 { 10 let mut groups: HashMap<K, Vec<T>> = HashMap::new(); 11 for item in items { 12 let key = key_of(&item); 13 groups.entry(key).or_default().push(item); 14 } 15 groups 16 } 17 18 /// Return the item with the largest derived key, or `None` if empty. 19 fn max_by_key<T, K, F>(items: &[T], key_of: F) -> Option<&T> 20 where 21 K: PartialOrd, 22 F: Fn(&T) -> K, 23 { 24 let mut best: Option<&T> = None; 25 let mut best_key: Option<K> = None; 26 for item in items { 27 let k = key_of(item); 28 match &best_key { 29 Some(bk) if !(k > *bk) => {} 30 _ => { 31 best = Some(item); 32 best_key = Some(k); 33 } 34 } 35 } 36 best 37 } 38 39 #[derive(Debug)] 40 struct Order { 41 id: u32, 42 customer: &'static str, 43 total: f64, 44 } 45 46 fn main() { 47 let orders = vec![ 48 Order { id: 1, customer: "ada", total: 42.0 }, 49 Order { id: 2, customer: "linus", total: 99.5 }, 50 Order { id: 3, customer: "ada", total: 10.0 }, 51 ]; 52 53 // `max_by_key` is inferred: T = Order, K = f64, F = the closure 54 let biggest = max_by_key(&orders, |o| o.total); 55 println!("biggest order: {:?}", biggest.map(|o| o.id)); 56 57 // `group_by` consumes the Vec and buckets by customer name 58 let by_customer = group_by(orders, |o| o.customer); 59 let mut customers: Vec<_> = by_customer.keys().copied().collect(); 60 customers.sort(); 61 for c in customers { 62 println!("{c}: {} orders", by_customer[c].len()); 63 } 64 } ``` Real output from `cargo run`: ```text 1 biggest order: Some(2) 2 ada: 2 orders 3 linus: 1 orders ``` Notice that all three type parameters of each function are inferred — no turbofish needed at the call sites — because the `Vec<Order>` and the closures fully determine `T`, `K`, and `F`. The standard library’s own [`Iterator::max_by_key`](https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.max_by_key) is built on exactly this pattern; here we wrote our own to see the mechanics. > **Note:** `F: Fn(&T) -> K` is a trait bound on a *closure type*: closures in Rust each have a unique, unnameable type, so you accept them via a generic parameter bounded by the `Fn` family. The standard `HashMap` used here is covered in [Section 07: Collections](/07-collections/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [The Rust Book — Generic Data Types](https://doc.rust-lang.org/book/ch10-01-syntax.html) — the canonical introduction, including the `largest` example. * [The Rust Reference — Generic parameters](https://doc.rust-lang.org/reference/items/generics.html) — the precise grammar and rules. * [Rust by Example — Generics](https://doc.rust-lang.org/rust-by-example/generics.html) — bite-sized runnable examples. * [The Rustonomicon — Monomorphization](https://doc.rust-lang.org/nomicon/) and the Reference on codegen — for how specialization actually works under the hood. * Sibling topics in this section: * [Generic Structs](/09-generics-traits/01-generic-structs/) — putting type parameters on data structures. * [Generic Enums](/09-generics-traits/02-generic-enums/) — `Option<T>` and `Result<T, E>` as the canonical examples. * [Trait Bounds](/09-generics-traits/05-trait-bounds/) — `<T: Trait>`, `where` clauses, and bounds on return types. * [Traits](/09-generics-traits/03-traits/) — the “interfaces” that bounds refer to. * [`impl Trait`](/09-generics-traits/07-impl-trait/) — lighter-weight generics in argument and return position. * [Trait Objects](/09-generics-traits/06-trait-objects/) — `dyn Trait`, the *dynamic-dispatch* alternative to monomorphized generics. * Related earlier sections: [Section 02: Basic Types](/02-basics/01-types/), [Section 05: Ownership](/05-ownership/), [Section 07: Collections](/07-collections/). * Up next after this section: [Section 10: Smart Pointers](/10-smart-pointers/), where `Box<dyn Trait>` ties generics and trait objects together. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Swap a pair [Section titled “Exercise 1: Swap a pair”](#exercise-1-swap-a-pair) **Difficulty:** Beginner **Objective:** Get comfortable declaring multiple type parameters and returning a generic tuple. **Instructions:** Write a generic function `swap` that takes a tuple `(A, B)` and returns it with the elements swapped, as `(B, A)`. It should require no trait bounds. Verify that `swap((1, "a"))` returns `("a", 1)`. ```rust 1 fn swap<A, B>(pair: (A, B)) -> (B, A) { 2 // TODO: destructure and return swapped 3 todo!() 4 } 5 6 fn main() { 7 let result = swap((1, "a")); 8 println!("{result:?}"); // ("a", 1) 9 } ``` Solution ```rust 1 fn swap<A, B>(pair: (A, B)) -> (B, A) { 2 let (a, b) = pair; 3 (b, a) 4 } 5 6 fn main() { 7 let result = swap((1, "a")); 8 println!("{result:?}"); // ("a", 1) 9 assert_eq!(swap((1, "a")), ("a", 1)); 10 } ``` No trait bounds are needed: we only *move* the values, never operate on them, so the empty `<A, B>` is enough. This is one of the rare cases where a bound-free generic is genuinely useful. ### Exercise 2: Print any two displayable values [Section titled “Exercise 2: Print any two displayable values”](#exercise-2-print-any-two-displayable-values) **Difficulty:** Intermediate **Objective:** Apply trait bounds so the function body can actually *use* the type parameters, and observe the compiler error if you forget them. **Instructions:** Write a generic function `print_pair<T, U>(a: T, b: U)` that prints `a` and `b` in the form `"<a> and <b>"`. To use `{}` formatting on `a` and `b`, you must bound both parameters with `std::fmt::Display`. First try it *without* the bounds and read the error; then add them. ```rust 1 fn print_pair<T, U>(a: T, b: U) { 2 // TODO: add the necessary bounds in the signature, then: 3 println!("{a} and {b}"); 4 } 5 6 fn main() { 7 print_pair(1, "one"); 8 print_pair(3.14, 'x'); 9 } ``` Solution ```rust 1 use std::fmt::Display; 2 3 fn print_pair<T: Display, U: Display>(a: T, b: U) { 4 println!("{a} and {b}"); 5 } 6 7 fn main() { 8 print_pair(1, "one"); // 1 and one 9 print_pair(3.14, 'x'); // 3.14 and x 10 } ``` Without the `Display` bounds, the compiler rejects the `{}` formatting with `error[E0277]: T doesn't implement std::fmt::Display`. The bound is the promise “every type passed here can be displayed,” which the compiler then enforces at each call site. ### Exercise 3: Count matching elements with a predicate closure [Section titled “Exercise 3: Count matching elements with a predicate closure”](#exercise-3-count-matching-elements-with-a-predicate-closure) **Difficulty:** Advanced **Objective:** Combine a generic element type with a generic closure parameter, using a `where` clause. **Instructions:** Write `count_matching<T, F>(items: &[T], pred: F) -> usize` that returns how many elements satisfy the predicate `pred`. The closure parameter `F` must be bounded by `Fn(&T) -> bool`. Use a `where` clause for readability. Verify that counting the even numbers in `[1, 2, 3, 4]` yields `2`. ```rust 1 fn count_matching<T, F>(items: &[T], pred: F) -> usize 2 where 3 // TODO: bound F so it can be called as `pred(&item) -> bool` 4 { 5 // TODO: count the matches (an iterator chain works well) 6 todo!() 7 } 8 9 fn main() { 10 let evens = count_matching(&[1, 2, 3, 4], |&n| n % 2 == 0); 11 println!("evens: {evens}"); // 2 12 } ``` Solution ```rust 1 fn count_matching<T, F>(items: &[T], pred: F) -> usize 2 where 3 F: Fn(&T) -> bool, 4 { 5 items.iter().filter(|x| pred(x)).count() 6 } 7 8 fn main() { 9 let evens = count_matching(&[1, 2, 3, 4], |&n| n % 2 == 0); 10 println!("evens: {evens}"); // 2 11 assert_eq!(count_matching(&[1, 2, 3, 4], |&n| n % 2 == 0), 2); 12 13 // Works for any element type, because T is generic: 14 let words = ["hi", "hello", "yo"]; 15 assert_eq!(count_matching(&words, |s| s.len() > 2), 1); // only "hello" 16 } ``` `F: Fn(&T) -> bool` lets the function accept any closure (or function pointer) that takes a `&T` and returns a `bool`. Because the closure has a unique, unnameable type, accepting it through a generic parameter is the idiomatic way. See [Section 03: Functions](/03-functions/) for closures and [`impl Trait`](/09-generics-traits/07-impl-trait/) for the lighter-weight `pred: impl Fn(&T) -> bool` spelling of the same thing. # Generic Structs > Generic structs put type parameters on Rust data, like a generic TypeScript class. Build reusable containers, constrain impl blocks, and see monomorphization. Generic structs let one `struct` definition work with many types: the direct Rust counterpart of a generic TypeScript `class` or `interface`. They are how you build reusable containers (stacks, caches, trees) without copy-pasting a version per element type, and they are everywhere in the standard library (`Vec<T>`, `HashMap<K, V>`, `Box<T>`). *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **generic struct** is a struct parameterized by one or more **type parameters** (written in angle brackets, like `Stack<T>`). At compile time Rust **monomorphizes** each concrete usage — it stamps out a specialized copy for `Stack<i32>`, another for `Stack<String>`, and so on — so there is zero runtime cost. This is the opposite of TypeScript, where generics are **erased** before the code ever runs. In this file we focus on generic *data structures*: declaring them, using multiple type parameters, and restricting which methods exist via **constraints on `impl` blocks**. > **Note:** Generic *functions* (`fn largest<T>(...)`) live in [Generic Functions](/09-generics-traits/00-generic-functions/), generic *enums* (`Option<T>`, `Result<T, E>`) in [Generic Enums](/09-generics-traits/02-generic-enums/), and the trait bound syntax (`<T: Trait>`, `where`) gets its own chapter in [Trait Bounds](/09-generics-traits/05-trait-bounds/). This file uses bounds only as much as needed to constrain `impl` blocks. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) A reusable stack in TypeScript, plus a key/value pair type. This is the kind of generic container you write all the time: ```typescript 1 // A generic stack that works for any element type. 2 class Stack<T> { 3 private items: T[] = []; 4 5 push(item: T): void { 6 this.items.push(item); 7 } 8 9 pop(): T | undefined { 10 return this.items.pop(); 11 } 12 13 peek(): T | undefined { 14 return this.items[this.items.length - 1]; 15 } 16 17 get size(): number { 18 return this.items.length; 19 } 20 21 isEmpty(): boolean { 22 return this.items.length === 0; 23 } 24 } 25 26 const numbers = new Stack<number>(); 27 numbers.push(1); 28 numbers.push(2); 29 numbers.push(3); 30 console.log("size =", numbers.size); // size = 3 31 console.log("peek =", numbers.peek()); // peek = 3 32 console.log("pop =", numbers.pop()); // pop = 3 33 34 // An interface with TWO type parameters. 35 interface Pair<K, V> { 36 key: K; 37 value: V; 38 } 39 40 const p: Pair<string, number> = { key: "age", value: 30 }; 41 console.log(p); // { key: 'age', value: 30 } ``` Running this with Node v22 (`node --experimental-strip-types`) prints exactly: ```text 1 size = 3 2 peek = 3 3 pop = 3 4 { key: 'age', value: 30 } ``` > **Note:** `console.log(p)` prints the structured object `{ key: 'age', value: 30 }`, not `[object Object]`. The `[object Object]` string only appears when an object is coerced to a string (e.g. `"" + p`). A few things to notice about the TypeScript version, because they contrast sharply with Rust: * The `<T>` and `<K, V>` parameters exist only for the type-checker. After `tsc` (or Node’s type-stripping) runs, there is a single `Stack` whose methods accept `any`. * `pop()` returns `T | undefined`; you must check for `undefined` yourself or risk a runtime surprise. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same stack and pair, idiomatic Rust: ```rust 1 #[derive(Debug)] 2 struct Stack<T> { 3 items: Vec<T>, 4 } 5 6 impl<T> Stack<T> { 7 fn new() -> Self { 8 Stack { items: Vec::new() } 9 } 10 11 fn push(&mut self, item: T) { 12 self.items.push(item); 13 } 14 15 fn pop(&mut self) -> Option<T> { 16 self.items.pop() 17 } 18 19 fn peek(&self) -> Option<&T> { 20 self.items.last() 21 } 22 23 fn len(&self) -> usize { 24 self.items.len() 25 } 26 27 fn is_empty(&self) -> bool { 28 self.items.is_empty() 29 } 30 } 31 32 // A struct with TWO type parameters. 33 #[derive(Debug)] 34 struct Pair<K, V> { 35 key: K, 36 value: V, 37 } 38 39 fn main() { 40 let mut numbers: Stack<i32> = Stack::new(); 41 numbers.push(1); 42 numbers.push(2); 43 numbers.push(3); 44 println!("len = {}", numbers.len()); // len = 3 45 println!("peek = {:?}", numbers.peek()); // peek = Some(3) 46 println!("pop = {:?}", numbers.pop()); // pop = Some(3) 47 48 let p = Pair { key: "age", value: 30 }; 49 println!("pair = {:?}", p); // pair = Pair { key: "age", value: 30 } 50 } ``` Real output, captured from `cargo run`: ```text 1 len = 3 2 peek = Some(3) 3 pop = Some(3) 4 pair = Pair { key: "age", value: 30 } ``` > **Tip:** `Vec<T>` and `Option<T>` are themselves generic structs/enums from the standard library — building `Stack<T>` on top of `Vec<T>` means the heavy lifting (growth, bounds-checking) is already done for you. `pop()` returns `Option<T>`, the type-system-enforced version of TypeScript’s `T | undefined`. See [The Option Type](/06-data-structures/03-option-enum/). *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) Let’s walk through the Rust version line by line and contrast it with the TypeScript. ### Declaring the type parameter on the struct [Section titled “Declaring the type parameter on the struct”](#declaring-the-type-parameter-on-the-struct) ```rust 1 struct Stack<T> { 2 items: Vec<T>, 3 } ``` `<T>` introduces a **type parameter** named `T` (any identifier works; `T`, `K`, `V`, `E`, `Item` are conventions). Inside the braces, `T` stands for “whatever type the caller picks.” `Vec<T>` says: a growable vector whose elements are that same `T`. This mirrors `private items: T[]` in TypeScript, but in Rust the `T` is a genuine part of the type’s identity, not erased decoration. ### Declaring the type parameter on the `impl` block [Section titled “Declaring the type parameter on the impl block”](#declaring-the-type-parameter-on-the-impl-block) ```rust 1 impl<T> Stack<T> { 2 // methods... 3 } ``` This is the line most surprising to a TypeScript developer. You must write `<T>` **twice**: once right after `impl` to *declare* the parameter, and once in `Stack<T>` to *use* it. In TypeScript the methods live inside the `class` body, so the `<T>` from `class Stack<T>` is automatically in scope. In Rust, `impl` blocks are separate items, so each one re-declares the generics it needs. Read it as: “*For any type `T`, here are the methods on `Stack<T>`.*” > **Warning:** Forgetting the `<T>` after `impl` is the #1 beginner mistake; see [Common Pitfalls](#common-pitfalls) for the exact compiler error. ### `Self` and the constructor [Section titled “Self and the constructor”](#self-and-the-constructor) ```rust 1 fn new() -> Self { 2 Stack { items: Vec::new() } 3 } ``` `Self` is an alias for “the type this `impl` is for”: here, `Stack<T>`. Rust has no `new` keyword and no constructors; by convention you write an **associated function** called `new` (associated functions are covered in [Associated Functions and Constructors](/06-data-structures/06-associated-functions/)). The caller writes `Stack::new()` instead of TypeScript’s `new Stack<number>()`. ### Method receivers: `&self`, `&mut self`, `self` [Section titled “Method receivers: \&self, \&mut self, self”](#method-receivers-self-mut-self-self) ```rust 1 fn push(&mut self, item: T) { ... } // needs to mutate -> &mut self 2 fn peek(&self) -> Option<&T> { ... } // only reads -> &self 3 fn swap(self) -> Pair<V, K> { ... } // consumes the value -> self (by value) ``` In TypeScript every method implicitly receives a mutable `this`. In Rust you choose the **borrow** explicitly: `&self` for read-only access, `&mut self` to mutate, or `self` (by value) to consume. The compiler enforces this: calling `push` on a non-`mut` binding is a compile error. This is ownership, covered in [Section 05](/05-ownership/). Note `peek(&self) -> Option<&T>`: it returns a **borrow** of the top element (`&T`), not a copy, and wraps it in `Option` to encode “the stack might be empty.” TypeScript’s `peek(): T | undefined` is the moral equivalent, but Rust makes the borrow and the emptiness both explicit and checked. ### Multiple type parameters [Section titled “Multiple type parameters”](#multiple-type-parameters) ```rust 1 struct Pair<K, V> { 2 key: K, 3 value: V, 4 } ``` You can have as many parameters as you like, separated by commas, exactly like `interface Pair<K, V>` in TypeScript. `K` and `V` are independent: `Pair<String, i32>`, `Pair<i32, i32>`, and `Pair<bool, Vec<u8>>` are all distinct, fully separate types after monomorphization. ### Type inference fills in the parameters [Section titled “Type inference fills in the parameters”](#type-inference-fills-in-the-parameters) In `let p = Pair { key: "age", value: 30 };` we never wrote `Pair<&str, i32>`. Rust infers `K = &str` and `V = i32` from the field values, just as TypeScript infers them from the object literal. For the stack we *did* annotate (`let mut numbers: Stack<i32>`) because `Stack::new()` starts empty and gives the compiler nothing to infer from. More on that in the pitfalls. *** ## Key Differences [Section titled “Key Differences”](#key-differences) ### Monomorphization vs type erasure [Section titled “Monomorphization vs type erasure”](#monomorphization-vs-type-erasure) This is the deepest conceptual difference. When you use `Stack<i32>` and `Stack<String>`, the Rust compiler generates **two separate, specialized structs and method sets**, as if you had hand-written `StackI32` and `StackString`. Each is compiled to machine code that knows the exact size and layout of its element type. There is no boxing, no `any`, no runtime type tag. TypeScript does the opposite: after compilation, generics vanish entirely. There is one `Stack` at runtime, and `T` is effectively `any`. You cannot ask “what was `T`?” at runtime, and there is no per-instantiation code. | Aspect | TypeScript generics | Rust generics | | -------------------------- | ---------------------------------- | ------------------------------------------------------------- | | When resolved | Compile-time only, then **erased** | Compile-time, then **monomorphized** | | Runtime representation | One class; `T` ≈ `any` | A distinct specialized type per concrete `T` | | Runtime type info | None (cannot inspect `T`) | None needed; type is baked into the code | | Performance | Same as untyped JS | Zero-cost; as fast as hand-specialized code | | Code size | One copy | One copy **per concrete instantiation** (can grow the binary) | | `instanceof Stack<number>` | Not possible (no such check) | Not applicable — types are static | > **Note:** The trade-off for monomorphization’s speed is **code bloat**: using a generic struct with 20 different element types produces 20 copies of its methods in the binary. This is usually fine; when it matters, trait objects (`Box<dyn Trait>`) trade some speed for a single shared copy. See [Trait Objects and Dynamic Dispatch](/09-generics-traits/06-trait-objects/). ### `derive` is conditional on the type parameter [Section titled “derive is conditional on the type parameter”](#derive-is-conditional-on-the-type-parameter) ```rust 1 #[derive(Debug, Clone, Default, PartialEq)] 2 struct Point<T> { 3 x: T, 4 y: T, 5 } ``` When you `#[derive(...)]` on a generic struct, Rust generates an implementation that is **conditional**: `Point<T>` is `Clone` *only when `T: Clone`*, `Debug` *only when `T: Debug`*, and so on. You get exactly the capabilities your `T` supports — no more, no less. The following compiles and runs: ```rust 1 #[derive(Debug, Clone, Default, PartialEq)] 2 struct Point<T> { 3 x: T, 4 y: T, 5 } 6 7 fn main() { 8 let a = Point { x: 1, y: 2 }; 9 let b = a.clone(); 10 println!("{:?} == {:?} -> {}", a, b, a == b); 11 12 let origin: Point<f64> = Point::default(); 13 println!("origin = {:?}", origin); 14 } ``` Real output: ```text 1 Point { x: 1, y: 2 } == Point { x: 1, y: 2 } -> true 2 origin = Point { x: 0.0, y: 0.0 } ``` TypeScript has no equivalent: there is no automatic structural equality, cloning, or default-value generation tied to a type parameter. ### One type parameter means *one* type [Section titled “One type parameter means one type”](#one-type-parameter-means-one-type) `Pair<K, V>` has two parameters, so `key` and `value` can differ. But in `Pair2<T> { first: T, second: T }`, **both** fields must be the *same* type. TypeScript enforces the identical rule, but because errors there are often deferred or widened, Rust’s version tends to surface the mismatch more bluntly (see Pitfall 2). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting `<T>` after `impl` [Section titled “Pitfall 1: Forgetting \<T> after impl”](#pitfall-1-forgetting-t-after-impl) The single most common mistake. You write the struct’s `impl` but only put `<T>` in the type, not after the `impl` keyword: ```rust 1 struct Container<T> { 2 item: T, 3 } 4 5 // does not compile (error[E0412]: cannot find type `T` in this scope) 6 impl Container<T> { 7 fn get(&self) -> &T { 8 &self.item 9 } 10 } ``` The real compiler error: ```text 1 error[E0412]: cannot find type `T` in this scope 2 --> src/main.rs:6:16 3 | 4 6 | impl Container<T> { 5 | ^ not found in this scope 6 | 7 help: you might be missing a type parameter 8 | 9 6 | impl<T> Container<T> { 10 | +++ ``` **Fix:** declare the parameter after `impl`: `impl<T> Container<T> { ... }`. The compiler’s `help` even shows the exact insertion. Remember: the first `<T>` *declares*, the second *uses*. ### Pitfall 2: Expecting one type parameter to hold two types [Section titled “Pitfall 2: Expecting one type parameter to hold two types”](#pitfall-2-expecting-one-type-parameter-to-hold-two-types) ```rust 1 struct Pair<T> { 2 first: T, 3 second: T, 4 } 5 6 fn main() { 7 // does not compile (error[E0308]: mismatched types) 8 let p = Pair { first: 5, second: "hello" }; 9 let _ = p; 10 } ``` Real error: ```text 1 error[E0308]: mismatched types 2 --> src/main.rs:8:38 3 | 4 8 | let p = Pair { first: 5, second: "hello" }; 5 | ^^^^^^^ expected integer, found `&str` ``` **Fix:** if the two fields can be different types, give the struct two parameters: `struct Pair<T, U> { first: T, second: U }`. With a single `T`, both fields are locked to the same concrete type. ### Pitfall 3: The compiler can’t infer the type parameter [Section titled “Pitfall 3: The compiler can’t infer the type parameter”](#pitfall-3-the-compiler-cant-infer-the-type-parameter) A generic constructor that produces an *empty* container gives Rust nothing to infer `T` from: ```rust 1 struct Stack<T> { 2 items: Vec<T>, 3 } 4 5 impl<T> Stack<T> { 6 fn new() -> Self { 7 Stack { items: Vec::new() } 8 } 9 fn len(&self) -> usize { 10 self.items.len() 11 } 12 } 13 14 fn main() { 15 let s = Stack::new(); // does not compile (error[E0282]: type annotations needed) 16 println!("{}", s.len()); 17 } ``` Real error: ```text 1 error[E0282]: type annotations needed for `Stack<_>` 2 --> src/main.rs:15:9 3 | 4 15 | let s = Stack::new(); // nothing tells the compiler what T is 5 | ^ ------------ type must be known at this point 6 | 7 help: consider giving `s` an explicit type, where the type for type parameter `T` is specified 8 | 9 15 | let s: Stack<T> = Stack::new(); // nothing tells the compiler what T is 10 | ++++++++++ ``` **Fix:** annotate the binding (`let s: Stack<i32> = Stack::new();`), use the turbofish (`Stack::<i32>::new()`), or push an element so inference has something to work with. This is the analogue of `new Stack<number>()` in TypeScript; Rust just needs the hint at a slightly different spot. (The turbofish `::<>` is covered in [Generic Functions](/09-generics-traits/00-generic-functions/).) ### Pitfall 4: Calling a method that only exists for *some* instantiations [Section titled “Pitfall 4: Calling a method that only exists for some instantiations”](#pitfall-4-calling-a-method-that-only-exists-for-some-instantiations) If you add a method in a constrained `impl` (next section), it exists only for the matching types. Calling it on a different instantiation fails: ```rust 1 struct Stack<T> { 2 items: Vec<T>, 3 } 4 5 impl<T> Stack<T> { 6 fn new() -> Self { Stack { items: Vec::new() } } 7 fn push(&mut self, item: T) { self.items.push(item); } 8 } 9 10 // `total()` exists only for Stack<i32>. 11 impl Stack<i32> { 12 fn total(&self) -> i32 { self.items.iter().sum() } 13 } 14 15 fn main() { 16 let mut words: Stack<String> = Stack::new(); 17 words.push("hi".to_string()); 18 let _ = words.total(); // does not compile (error[E0599]: no method named `total`) 19 } ``` Real error: ```text 1 error[E0599]: no method named `total` found for struct `Stack<String>` in the current scope 2 --> src/main.rs:18:19 3 | 4 1 | struct Stack<T> { 5 | --------------- method `total` not found for this struct 6 ... 7 18 | let _ = words.total(); // total() exists only for Stack<i32> 8 | ^^^^^ method not found in `Stack<String>` 9 | 10 = note: the method was found for 11 - `Stack<i32>` ``` This is a *feature*, not a limitation: the compiler tells you the method exists, just for a different type. There is no TypeScript equivalent of “this method exists only when `T = number`” with a clean compile-time error like this. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Constrain `impl` blocks, not the struct definition [Section titled “Constrain impl blocks, not the struct definition”](#constrain-impl-blocks-not-the-struct-definition) Prefer to put trait bounds on the `impl` block (or individual methods) rather than on the `struct` itself: ```rust 1 // Idiomatic: the struct stays unconstrained... 2 struct Wrapper<T> { 3 value: T, 4 } 5 6 impl<T> Wrapper<T> { 7 fn new(value: T) -> Self { 8 Wrapper { value } 9 } 10 } 11 12 // ...and bounds gate only the methods that actually need them. 13 impl<T: std::fmt::Display + PartialOrd> Wrapper<T> { 14 fn announce_larger(&self, other: &T) { 15 if self.value >= *other { 16 println!("{} is the largest", self.value); 17 } else { 18 println!("{} is the largest", other); 19 } 20 } 21 } 22 23 fn main() { 24 let w = Wrapper::new(42); 25 w.announce_larger(&10); // 42 is the largest 26 } ``` Output: `42 is the largest`. This way you can still construct `Wrapper<SomethingNotDisplay>`; you just can’t call `announce_larger` on it. Putting `T: Display` on the `struct` would forbid the whole type for non-`Display` `T`, which is almost never what you want. > **Warning:** Rust strongly discourages bounds directly on struct definitions (e.g. `struct Wrapper<T: Display>`). They infect every `impl` and signature that mentions the struct without buying real safety, and the community lint guidance is to omit them. Keep bounds where they are used. ### Use `where` clauses when bounds get long [Section titled “Use where clauses when bounds get long”](#use-where-clauses-when-bounds-get-long) When a constrained `impl` has several bounds, a `where` clause reads better than stacking them in the angle brackets: ```rust 1 use std::collections::HashMap; 2 use std::hash::Hash; 3 4 struct Cache<K, V> { 5 store: HashMap<K, V>, 6 } 7 8 impl<K, V> Cache<K, V> 9 where 10 K: Eq + Hash + Clone, 11 V: Clone, 12 { 13 fn new() -> Self { 14 Cache { store: HashMap::new() } 15 } 16 } 17 fn main() { let _c: Cache<String, i32> = Cache::new(); } ``` The full `where`-clause story is in [Trait Bounds](/09-generics-traits/05-trait-bounds/). ### Name parameters meaningfully [Section titled “Name parameters meaningfully”](#name-parameters-meaningfully) `T` for a single “the element,” `K`/`V` for key/value, `E` for an error type, `Item`/`Output` when a descriptive name aids readability. Single uppercase letters are the convention; resist `TElement`-style Hungarian names that TypeScript codebases sometimes use. ### Reach for the standard library’s generic types first [Section titled “Reach for the standard library’s generic types first”](#reach-for-the-standard-librarys-generic-types-first) Before writing your own generic container, check whether `Vec<T>`, `VecDeque<T>`, `HashMap<K, V>`, `BTreeMap<K, V>`, or `Box<T>` already does it. Your `Stack<T>` above is a thin, type-safe wrapper over `Vec<T>`, which is exactly the right amount of code to write. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored generic cache: a bounded key/value store with eviction, reused for two completely different element types. The constrained `impl` requires `K: Eq + Hash + Clone` (so we can use a `HashMap` and clone a key to evict) and `V: Clone`. ```rust 1 use std::collections::HashMap; 2 use std::hash::Hash; 3 4 /// A bounded in-memory cache keyed by `K`, storing `V`, with a max capacity. 5 struct Cache<K, V> { 6 store: HashMap<K, V>, 7 capacity: usize, 8 } 9 10 impl<K, V> Cache<K, V> 11 where 12 K: Eq + Hash + Clone, 13 V: Clone, 14 { 15 fn new(capacity: usize) -> Self { 16 Cache { 17 store: HashMap::new(), 18 capacity, 19 } 20 } 21 22 /// Inserts a value, evicting an entry first if we are at capacity. 23 /// Returns the previous value for `key`, if any. 24 fn insert(&mut self, key: K, value: V) -> Option<V> { 25 if self.store.len() >= self.capacity && !self.store.contains_key(&key) { 26 // Evict an arbitrary existing entry to stay within capacity. 27 if let Some(victim) = self.store.keys().next().cloned() { 28 self.store.remove(&victim); 29 } 30 } 31 self.store.insert(key, value) 32 } 33 34 fn get(&self, key: &K) -> Option<&V> { 35 self.store.get(key) 36 } 37 38 fn len(&self) -> usize { 39 self.store.len() 40 } 41 } 42 43 #[derive(Debug, Clone)] 44 struct Session { 45 user_id: u64, 46 token: String, 47 } 48 49 fn main() { 50 // 1) A cache of String -> Session, capacity 2. 51 let mut sessions: Cache<String, Session> = Cache::new(2); 52 sessions.insert( 53 "alice".to_string(), 54 Session { user_id: 1, token: "tok_a".to_string() }, 55 ); 56 sessions.insert( 57 "bob".to_string(), 58 Session { user_id: 2, token: "tok_b".to_string() }, 59 ); 60 sessions.insert( 61 "carol".to_string(), 62 Session { user_id: 3, token: "tok_c".to_string() }, 63 ); 64 65 println!("cache size = {}", sessions.len()); // stays at capacity 66 if let Some(s) = sessions.get(&"carol".to_string()) { 67 println!("carol -> user {} token {}", s.user_id, s.token); 68 } 69 70 // 2) The SAME generic type, now caching u32 -> u32. No new code. 71 let mut squares: Cache<u32, u32> = Cache::new(10); 72 for n in 1..=5 { 73 squares.insert(n, n * n); 74 } 75 println!("4^2 = {:?}", squares.get(&4)); 76 } ``` Real output, captured from `cargo run`: ```text 1 cache size = 2 2 carol -> user 3 token tok_c 3 4^2 = Some(16) ``` The headline: one `Cache<K, V>` definition serves both a `String`-keyed session store and a `u32`-keyed squares table, and each is monomorphized into specialized, allocation-free-dispatch code. The bounds on the `impl` (`Eq + Hash + Clone`, `Clone`) document precisely what a key and value must support: the type system rejects, at compile time, any `K` that can’t be a `HashMap` key. > **Tip:** If you reach for an owned heap-allocated container that must be shared or have a single owner with indirection, the smart pointers in [Section 10](/10-smart-pointers/) (`Box<T>`, `Rc<T>`, `RefCell<T>`) are themselves generic structs — they compose cleanly with your own. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Generic Data Types](https://doc.rust-lang.org/book/ch10-01-syntax.html) (the “In Struct Definitions” and “In Method Definitions” subsections directly cover this file’s scope) * [Rust by Example — Generics](https://doc.rust-lang.org/rust-by-example/generics.html) * [Rust Reference — Generic parameters](https://doc.rust-lang.org/reference/items/generics.html) * [The Rust Book — Const generics / `const` parameters](https://doc.rust-lang.org/reference/items/generics.html#const-generics) (used in Exercise 3) ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Generic Functions](/09-generics-traits/00-generic-functions/): generic functions, monomorphization vs erasure, the turbofish `::<>` * [Generic Enums](/09-generics-traits/02-generic-enums/) — generic enums, with `Option<T>` and `Result<T, E>` as the canonical examples * [Trait Bounds](/09-generics-traits/05-trait-bounds/) — the full grammar of `<T: Trait>`, multiple bounds, and `where` clauses * [Traits](/09-generics-traits/03-traits/): defining and implementing traits (the “interfaces” your bounds refer to) * [Trait Objects and Dynamic Dispatch](/09-generics-traits/06-trait-objects/) — `Box<dyn Trait>` when you want one shared copy instead of monomorphization * [Structs](/06-data-structures/00-structs/) and [Methods and `impl` Blocks](/06-data-structures/05-impl-blocks/) — non-generic structs and `impl` basics * [The Option Type](/06-data-structures/03-option-enum/): `Option<T>`, returned by `pop()` and `peek()` above * [Section 05: Ownership](/05-ownership/) — why method receivers are `&self` / `&mut self` / `self` * [Section 02: Basic Types](/02-basics/01-types/) — the concrete types (`i32`, `String`, …) that fill in your parameters *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A mappable wrapper [Section titled “Exercise 1: A mappable wrapper”](#exercise-1-a-mappable-wrapper) **Difficulty:** Easy **Objective:** Practice declaring a generic struct and a generic *method* that changes the type parameter. **Instructions:** Define `Wrapper<T>` holding a single `value: T`. Give it a `new(value: T)` constructor and a `map` method that takes a closure `F: FnOnce(T) -> U` and returns a `Wrapper<U>`. Then wrap a number and `map` it into a wrapped `String`. ```rust 1 struct Wrapper<T> { 2 value: T, 3 } 4 5 impl<T> Wrapper<T> { 6 fn new(value: T) -> Self { 7 /* ??? */ 8 } 9 10 fn map</* ??? */>(self, f: F) -> Wrapper<U> { 11 /* ??? */ 12 } 13 } 14 15 fn main() { 16 let w = Wrapper::new(5); 17 let s = w.map(|n| format!("n = {n}")); 18 println!("{}", s.value); // n = 5 19 } ``` Solution ```rust 1 struct Wrapper<T> { 2 value: T, 3 } 4 5 impl<T> Wrapper<T> { 6 fn new(value: T) -> Self { 7 Wrapper { value } 8 } 9 10 // `map` introduces a NEW type parameter `U` (the closure's output) 11 // and a closure type `F`. It consumes `self` (note `self`, not `&self`) 12 // because the value is moved into the closure. 13 fn map<U, F: FnOnce(T) -> U>(self, f: F) -> Wrapper<U> { 14 Wrapper { value: f(self.value) } 15 } 16 } 17 18 fn main() { 19 let w = Wrapper::new(5); 20 let s = w.map(|n| format!("n = {n}")); 21 println!("{}", s.value); // n = 5 22 } ``` Output: `n = 5`. The method-level `<U, F>` is declared on the method, separate from the struct’s `<T>`. This is the per-`impl`/per-method generic declaration rule in action. ### Exercise 2: A key/value store with a constrained convenience method [Section titled “Exercise 2: A key/value store with a constrained convenience method”](#exercise-2-a-keyvalue-store-with-a-constrained-convenience-method) **Difficulty:** Medium **Objective:** Build a two-parameter generic struct and add a method that exists *only* when the value type supports more traits: the “constraints on impls” idea. **Instructions:** Define `Store<K, V>` wrapping a `HashMap<K, V>`. In an `impl` bounded by `K: Eq + Hash`, add `new`, `set`, and `get`. In a *second*, more constrained `impl` (`V: Clone + Default`), add `get_or_default(&self, k: &K) -> V` that returns a clone of the stored value or `V::default()` if the key is missing. ```rust 1 use std::collections::HashMap; 2 use std::hash::Hash; 3 4 struct Store<K, V> { 5 map: HashMap<K, V>, 6 } 7 8 // impl 1: basic operations 9 impl</* ??? */> Store<K, V> { 10 fn new() -> Self { /* ??? */ } 11 fn set(&mut self, k: K, v: V) { /* ??? */ } 12 fn get(&self, k: &K) -> Option<&V> { /* ??? */ } 13 } 14 15 // impl 2: only when V: Clone + Default 16 impl</* ??? */> Store<K, V> { 17 fn get_or_default(&self, k: &K) -> V { /* ??? */ } 18 } 19 20 fn main() { 21 let mut store: Store<String, i32> = Store::new(); 22 store.set("hits".to_string(), 7); 23 println!("hits = {:?}", store.get(&"hits".to_string())); // hits = Some(7) 24 println!("misses = {}", store.get_or_default(&"misses".to_string())); // misses = 0 25 } ``` Solution ```rust 1 use std::collections::HashMap; 2 use std::hash::Hash; 3 4 struct Store<K, V> { 5 map: HashMap<K, V>, 6 } 7 8 // Basic operations need K to be a valid HashMap key. 9 impl<K: Eq + Hash, V> Store<K, V> { 10 fn new() -> Self { 11 Store { map: HashMap::new() } 12 } 13 fn set(&mut self, k: K, v: V) { 14 self.map.insert(k, v); 15 } 16 fn get(&self, k: &K) -> Option<&V> { 17 self.map.get(k) 18 } 19 } 20 21 // This method exists ONLY when V is Clone + Default. 22 impl<K: Eq + Hash, V: Clone + Default> Store<K, V> { 23 fn get_or_default(&self, k: &K) -> V { 24 self.map.get(k).cloned().unwrap_or_default() 25 } 26 } 27 28 fn main() { 29 let mut store: Store<String, i32> = Store::new(); 30 store.set("hits".to_string(), 7); 31 println!("hits = {:?}", store.get(&"hits".to_string())); // hits = Some(7) 32 println!("misses = {}", store.get_or_default(&"misses".to_string())); // misses = 0 33 } ``` Output: ```text 1 hits = Some(7) 2 misses = 0 ``` `get_or_default` is available because `i32` is both `Clone` and `Default` (its default is `0`). Build a `Store` whose `V` lacks `Default` and the basic methods still work, but `get_or_default` simply isn’t there: the same constrained-`impl` behavior as Pitfall 4. ### Exercise 3: A fixed-capacity ring buffer with const generics [Section titled “Exercise 3: A fixed-capacity ring buffer with const generics”](#exercise-3-a-fixed-capacity-ring-buffer-with-const-generics) **Difficulty:** Hard **Objective:** Use a **const generic** parameter so the capacity is part of the type, with zero heap allocation. **Instructions:** Define `RingBuffer<T, const N: usize>` holding `data: [Option<T>; N]` and a `head: usize`. In an `impl` bounded by `T: Copy` (so the `[None; N]` array literal works), add `new`, `push` (wrapping with `% N`), and `capacity()` returning `N`. Const generics let the size live in the type, so `RingBuffer<i32, 3>` and `RingBuffer<i32, 8>` are distinct types whose buffers are stack-allocated. ```rust 1 struct RingBuffer<T, const N: usize> { 2 data: [Option<T>; N], 3 head: usize, 4 } 5 6 impl<T: Copy, const N: usize> RingBuffer<T, N> { 7 fn new() -> Self { /* ??? */ } 8 fn push(&mut self, item: T) { /* ??? */ } 9 fn capacity(&self) -> usize { /* ??? */ } 10 } 11 12 fn main() { 13 let mut rb: RingBuffer<i32, 3> = RingBuffer::new(); 14 rb.push(10); 15 rb.push(20); 16 println!("capacity = {}, first = {:?}", rb.capacity(), rb.data[0]); 17 // capacity = 3, first = Some(10) 18 } ``` Solution ```rust 1 struct RingBuffer<T, const N: usize> { 2 data: [Option<T>; N], 3 head: usize, 4 } 5 6 impl<T: Copy, const N: usize> RingBuffer<T, N> { 7 fn new() -> Self { 8 // `[None; N]` requires the element type (Option<T>) to be Copy, 9 // which holds because we bounded T: Copy. 10 RingBuffer { data: [None; N], head: 0 } 11 } 12 13 fn push(&mut self, item: T) { 14 self.data[self.head % N] = Some(item); 15 self.head += 1; 16 } 17 18 fn capacity(&self) -> usize { 19 N 20 } 21 } 22 23 fn main() { 24 let mut rb: RingBuffer<i32, 3> = RingBuffer::new(); 25 rb.push(10); 26 rb.push(20); 27 println!("capacity = {}, first = {:?}", rb.capacity(), rb.data[0]); 28 // capacity = 3, first = Some(10) 29 } ``` Output: `capacity = 3, first = Some(10)`. `const N: usize` is a **const generic** — a value (not a type) baked into the type signature. The whole buffer lives inline on the stack with no `Vec`, and the compiler knows its exact size. This is a capability with no TypeScript analogue: in TypeScript, array length is never part of a generic type parameter you can compute over. # Generic Enums > Generic enums power Rust's Option and Result, the typed answer to TypeScript discriminated unions, with enforced exhaustiveness, ? support, and niche layout. Enums that are parameterized over a type, like TypeScript’s discriminated unions with generics. This is where Rust’s two most important types — `Option<T>` and `Result<T, E>` — come from, so understanding generic enums is understanding the heart of the standard library. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **generic enum** is an enum with one or more **type parameters**, so the same shape (`Some`/`None`, `Ok`/`Err`, a tree node, a cache slot) can hold any type you choose. If you have ever written a TypeScript discriminated union like `type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }`, you already understand the idea. The difference is that Rust bakes this pattern into the language, makes the compiler force you to handle every case, and generates a separate, fully-optimized copy of the enum for each concrete type you use (**monomorphization**). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript you reach for a **discriminated union** (also called a tagged union) when a value can be in one of several shapes. Generics let you reuse that shape across types. A common one is a hand-rolled `Result` to avoid throwing exceptions: ```typescript 1 // A generic "result" union: success carries a T, failure carries an E. 2 type Result<T, E> = 3 | { kind: "ok"; value: T } 4 | { kind: "err"; error: E }; 5 6 interface User { 7 id: number; 8 name: string; 9 } 10 11 interface ApiError { 12 status: number; 13 message: string; 14 } 15 16 function parseUser(json: string): Result<User, ApiError> { 17 try { 18 const data = JSON.parse(json) as User; 19 return { kind: "ok", value: data }; 20 } catch { 21 return { kind: "err", error: { status: 400, message: "invalid JSON" } }; 22 } 23 } 24 25 // The consumer must check the discriminant before touching the payload. 26 const result = parseUser('{"id":1,"name":"Ada"}'); 27 if (result.kind === "ok") { 28 console.log(`Loaded ${result.value.name}`); // Loaded Ada 29 } else { 30 console.log(`Failed: ${result.error.message}`); 31 } ``` TypeScript’s union is structural and runtime-erased: the `kind` field is a real property you check at runtime, and the `<T, E>` type parameters exist only at compile time: they vanish in the emitted JavaScript. > **Note:** TypeScript and JavaScript also have a built-in optional pattern: `T | undefined` (or `T | null`). That is the closest analogue to Rust’s `Option<T>`, but as you will see, the Rust version forces you to handle the absent case. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust spells the same idea with `enum` plus angle-bracket type parameters. Here is a generic `Either<L, R>` and a generic `Cache<T>` with methods: ```rust 1 // A generic enum with two type parameters. 2 #[derive(Debug)] 3 enum Either<L, R> { 4 Left(L), 5 Right(R), 6 } 7 8 // A generic enum with one type parameter, plus an inherent impl. 9 #[derive(Debug)] 10 enum Cache<T> { 11 Empty, 12 Loaded(T), 13 } 14 15 impl<T> Cache<T> { 16 fn get(&self) -> Option<&T> { 17 match self { 18 Cache::Empty => None, 19 Cache::Loaded(value) => Some(value), 20 } 21 } 22 23 fn is_loaded(&self) -> bool { 24 matches!(self, Cache::Loaded(_)) 25 } 26 } 27 28 fn main() { 29 let a: Either<i32, String> = Either::Left(42); 30 let b: Either<i32, String> = Either::Right(String::from("oops")); 31 println!("{:?} {:?}", a, b); // Left(42) Right("oops") 32 33 let c: Cache<String> = Cache::Loaded(String::from("data")); 34 println!("loaded? {} value = {:?}", c.is_loaded(), c.get()); 35 // loaded? true value = Some("data") 36 37 let empty: Cache<String> = Cache::Empty; 38 println!("loaded? {} value = {:?}", empty.is_loaded(), empty.get()); 39 // loaded? false value = None 40 } ``` Real output: ```text 1 Left(42) Right("oops") 2 loaded? true value = Some("data") 3 loaded? false value = None ``` The standard library’s `Option<T>` and `Result<T, E>` are *exactly* this pattern: generic enums that you will use constantly: ```rust 1 // These are (essentially) how the standard library defines them: 2 enum Option<T> { 3 None, 4 Some(T), 5 } 6 7 enum Result<T, E> { 8 Ok(T), 9 Err(E), 10 } ``` You do not need to define `Option` or `Result` yourself. They are in the **prelude**, so `Some`, `None`, `Ok`, and `Err` are always in scope. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Declaring the type parameter [Section titled “Declaring the type parameter”](#declaring-the-type-parameter) ```rust 1 enum Either<L, R> { 2 Left(L), 3 Right(R), 4 } ``` The `<L, R>` after the enum name introduces two type parameters. Each variant can use them: `Left` holds an `L`, `Right` holds an `R`. The names are conventional — single uppercase letters like `T`, `E`, `K`, `V`, `L`, `R` — but you can use a descriptive name like `Payload` if it reads better. Unlike TypeScript, where you write `type Either<L, R> = ...`, Rust uses the `enum` keyword and each variant is a real constructor (`Either::Left`, `Either::Right`). ### Methods need their own `<T>` [Section titled “Methods need their own \<T>”](#methods-need-their-own-t) ```rust 1 impl<T> Cache<T> { 2 fn is_loaded(&self) -> bool { /* ... */ } 3 } ``` The `impl<T>` reads as: “for every type `T`, here are methods on `Cache<T>`.” The `<T>` right after `impl` *declares* the parameter; the `<T>` in `Cache<T>` *uses* it. Forgetting the first one is a classic beginner error (see Common Pitfalls). This is covered in depth in [Generic Structs](/09-generics-traits/01-generic-structs/), and the same rule applies to enums. ### Pattern matching destructures the payload [Section titled “Pattern matching destructures the payload”](#pattern-matching-destructures-the-payload) ```rust 1 match self { 2 Cache::Empty => None, 3 Cache::Loaded(value) => Some(value), 4 } ``` `match` is how you safely get the inner value out. In the `Cache::Loaded(value)` arm, `value` is bound to the `&T` inside (because we matched on `&self`). This is the same idea as checking `result.kind === "ok"` in TypeScript and *then* reading `result.value`, except the compiler **guarantees** you handled every variant. If you add a third variant later, every `match` that does not handle it stops compiling, a refactoring superpower TypeScript’s `switch` cannot match unless you opt in with `never` checks. See [Control Flow](/04-control-flow/) for more on `match` and `if let`. ### Monomorphization: one copy per concrete type [Section titled “Monomorphization: one copy per concrete type”](#monomorphization-one-copy-per-concrete-type) This is the deepest difference from TypeScript. When you write `Cache<String>` and `Cache<i32>`, the Rust compiler generates two *separate*, fully-specialized enums — as if you had hand-written `CacheString` and `CacheI32`. There is no boxing, no tag-dispatch overhead, and the layout is optimal for each type. You can observe the distinct layouts: ```rust 1 use std::mem::size_of; 2 3 #[derive(Debug)] 4 enum Slot<T> { 5 Empty, 6 Full(T), 7 } 8 9 fn main() { 10 println!("Slot<u8> = {} bytes", size_of::<Slot<u8>>()); 11 println!("Slot<i64> = {} bytes", size_of::<Slot<i64>>()); 12 13 let a: Slot<u8> = Slot::Full(1); 14 let b: Slot<i64> = Slot::Empty; 15 println!("{:?} {:?}", a, b); 16 } ``` Real output: ```text 1 Slot<u8> = 2 bytes 2 Slot<i64> = 16 bytes 3 Full(1) Empty ``` The two sizes are the point: `Slot<u8>` is 2 bytes (1 byte payload + 1 byte tag), while `Slot<i64>` is 16 bytes (8 bytes payload + padding + tag). TypeScript erases generics entirely, so there is only ever *one* runtime representation and the `<T>` is gone. Rust trades a little compile time and binary size for zero-cost, type-specialized code. Monomorphization is explained fully in [Generic Functions](/09-generics-traits/00-generic-functions/). ### The `?` operator works on generic enums [Section titled “The ? operator works on generic enums”](#the--operator-works-on-generic-enums) Because `Option<T>` and `Result<T, E>` are generic enums with a known shape, the `?` operator can short-circuit on them: ```rust 1 fn first_two(s: &str) -> Option<(char, char)> { 2 let mut it = s.chars(); 3 let a = it.next()?; // if None, return None from first_two 4 let b = it.next()?; 5 Some((a, b)) 6 } 7 8 fn parse_and_double(s: &str) -> Result<i32, std::num::ParseIntError> { 9 let n: i32 = s.parse()?; // if Err, return that Err 10 Ok(n * 2) 11 } 12 13 fn main() { 14 println!("{:?}", first_two("hi")); // Some(('h', 'i')) 15 println!("{:?}", first_two("x")); // None 16 println!("{:?}", parse_and_double("21")); // Ok(42) 17 println!("{:?}", parse_and_double("no")); // Err(ParseIntError { kind: InvalidDigit }) 18 } ``` Real output: ```text 1 Some(('h', 'i')) 2 None 3 Ok(42) 4 Err(ParseIntError { kind: InvalidDigit }) ``` `?` is roughly TypeScript’s optional chaining `?.` combined with early-return-on-error, but it is built on these generic enums. Error handling with `Result` and `?` is the subject of [Error Handling](/08-error-handling/). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | TypeScript discriminated union | Rust generic enum | | ------------------- | ----------------------------------------- | ---------------------------------------------------- | | Syntax | `type U<T> = { kind: "a"; ... } \| ...` | `enum U<T> { A(T), ... }` | | Discriminant | A real runtime field you choose (`kind`) | A hidden, compiler-managed tag | | Generics at runtime | Erased — one shared representation | Monomorphized — one specialized copy per type | | Exhaustiveness | Opt-in (`never` trick / `switch` default) | Enforced — non-exhaustive `match` is a compile error | | Optional value | `T \| undefined` | `Option<T>` (`Some`/`None`) | | Fallible value | hand-rolled union or `throw` | `Result<T, E>` (`Ok`/`Err`) | | Memory layout | uniform (boxed object) | sized exactly for `T`, with niche optimization | ### Null safety is a generic enum, not a special case [Section titled “Null safety is a generic enum, not a special case”](#null-safety-is-a-generic-enum-not-a-special-case) TypeScript bolts optionality onto every type with `T | undefined`, and `strictNullChecks` is what makes you check it. Rust has **no** `null`. Absence is modeled with the ordinary generic enum `Option<T>`, and the type system makes the absent case impossible to ignore: you cannot read the `T` out of an `Option<T>` without first dealing with `None`. ### Niche optimization [Section titled “Niche optimization”](#niche-optimization) Because the compiler controls the tag, it can be clever. For types that have an impossible bit pattern (a “niche”), `Option` reuses it instead of adding a separate tag. A reference or `Box` can never be null, so `Option<&T>` and `Option<Box<T>>` use the all-zero pointer as `None` and are the **same size** as the bare pointer: ```rust 1 use std::mem::size_of; 2 3 fn main() { 4 println!("&i32 = {} bytes", size_of::<&i32>()); 5 println!("Option<&i32> = {} bytes", size_of::<Option<&i32>>()); 6 println!("Box<i32> = {} bytes", size_of::<Box<i32>>()); 7 println!("Option<Box<i32>> = {} bytes", size_of::<Option<Box<i32>>>()); 8 println!("i32 = {} bytes", size_of::<i32>()); 9 println!("Option<i32> = {} bytes", size_of::<Option<i32>>()); 10 } ``` Real output: ```text 1 &i32 = 8 bytes 2 Option<&i32> = 8 bytes 3 Box<i32> = 8 bytes 4 Option<Box<i32>> = 8 bytes 5 i32 = 4 bytes 6 Option<i32> = 8 bytes ``` `Option<&i32>` costs nothing extra, while `Option<i32>` needs a separate discriminant byte (rounded up to 8 for alignment) because every `i32` bit pattern is a valid value. TypeScript’s `number | undefined` has no such trick; `undefined` is just another runtime value. `Box<T>` and other smart pointers are covered in [Smart Pointers](/10-smart-pointers/). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting the type annotation on a bare variant [Section titled “Pitfall 1: Forgetting the type annotation on a bare variant”](#pitfall-1-forgetting-the-type-annotation-on-a-bare-variant) A variant with no payload (`None`, `Cache::Empty`) gives the compiler nothing to infer `T` from: ```rust 1 fn main() { 2 let cache = None; // does not compile (error[E0282]: type annotations needed) 3 println!("{:?}", cache); 4 } ``` Real compiler error: ```text 1 error[E0282]: type annotations needed for `Option<_>` 2 --> src/main.rs:3:9 3 | 4 3 | let cache = None; // what is T? 5 | ^^^^^ ---- type must be known at this point 6 | 7 help: consider giving `cache` an explicit type, where the type for type parameter `T` is specified 8 | 9 3 | let cache: Option<T> = None; // what is T? 10 | +++++++++++ ``` **Fix:** annotate the binding (`let cache: Option<i32> = None;`) or use the **turbofish** on a function that returns it. Coming from TypeScript this surprises people, because `const x = undefined` is always fine there, but TypeScript widens it to `undefined`/`any`, whereas Rust refuses to guess `T`. ### Pitfall 2: Non-exhaustive `match` [Section titled “Pitfall 2: Non-exhaustive match”](#pitfall-2-non-exhaustive-match) Forgetting a variant is a hard error, not a warning: ```rust 1 enum Either<L, R> { 2 Left(L), 3 Right(R), 4 } 5 6 fn describe(e: Either<i32, String>) -> String { 7 match e { 8 Either::Left(n) => format!("number {}", n), 9 // does not compile (error[E0004]): forgot Either::Right 10 } 11 } ``` Real compiler error: ```text 1 error[E0004]: non-exhaustive patterns: `Either::Right(_)` not covered 2 --> src/main.rs:7:11 3 | 4 7 | match e { 5 | ^ pattern `Either::Right(_)` not covered 6 | 7 note: `Either<i32, String>` defined here 8 --> src/main.rs:1:6 9 | 10 1 | enum Either<L, R> { 11 | ^^^^^^ 12 2 | Left(L), 13 3 | Right(R), 14 | ----- not covered 15 = note: the matched value is of type `Either<i32, String>` ``` This is a feature: add a variant later and the compiler lists every place that needs updating. To intentionally ignore the rest, add `_ => ...`. ### Pitfall 3: Forgetting `<T>` after `impl` [Section titled “Pitfall 3: Forgetting \<T> after impl”](#pitfall-3-forgetting-t-after-impl) ```rust 1 enum Maybe<T> { 2 Just(T), 3 Nothing, 4 } 5 6 impl Maybe<T> { // does not compile (error[E0412]: cannot find type `T`) 7 fn is_just(&self) -> bool { 8 matches!(self, Maybe::Just(_)) 9 } 10 } ``` Real compiler error: ```text 1 error[E0412]: cannot find type `T` in this scope 2 --> src/main.rs:6:12 3 | 4 6 | impl Maybe<T> { // forgot the <T> after impl 5 | ^ not found in this scope 6 | 7 help: you might be missing a type parameter 8 | 9 6 | impl<T> Maybe<T> { // forgot the <T> after impl 10 | +++ ``` **Fix:** write `impl<T> Maybe<T>`. The first `<T>` declares the parameter, the second uses it. ### Pitfall 4: Reaching for `null`/`undefined` habits [Section titled “Pitfall 4: Reaching for null/undefined habits”](#pitfall-4-reaching-for-nullundefined-habits) TypeScript developers often look for “the empty value.” There is no `null` in safe Rust. Model absence with `Option<T>` and a missing-but-recoverable failure with `Result<T, E>`. Trying to leave a field “unset” by some other means usually means you actually wanted `Option<T>`. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Reach for `Option<T>` and `Result<T, E>` first.** Do not invent your own two-state enums for “maybe a value” or “value or error”: the standard ones come with dozens of combinators (`map`, `and_then`, `unwrap_or`, `ok_or`, `?`) and integrate with the whole ecosystem. * **Derive the traits you need.** `#[derive(Debug)]` is almost always worth adding so you can `println!("{:?}", value)`. Add `Clone`, `PartialEq`, etc. as needed. * **Name your own domain enums, even when `Either` would work.** `Either<L, R>` is generic and meaningless to a reader; a `Payment { Card(CardInfo), Cash(Money) }` enum documents intent. Use generics on enums when the *container* logic is reusable, not to avoid naming a domain concept. * **Provide constructors and combinators in an `impl<T>` block** rather than forcing callers to `match` everywhere. A `map`/`get`/`unwrap_or` method centralizes the pattern. * **Bound type parameters where the method needs it, not on the enum.** Put `where T: Clone` on the specific method’s `impl`, so that constructing the enum stays unconstrained. See [Trait Bounds](/09-generics-traits/05-trait-bounds/). * **Box recursive variants.** A self-referential enum like a tree or linked list must put the recursive part behind a pointer (`Box<Tree<T>>`); otherwise it would have infinite size. See the Real-World Example below and [Smart Pointers](/10-smart-pointers/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored use of a generic enum: a `Fetch<T, E>` state machine, the kind you would model a data-fetching hook around (idle → loading → success/failure). It is generic so the same machine works for any payload and error type. ```rust 1 use std::fmt; 2 3 /// The lifecycle of an asynchronous request, generic over its payload `T` 4 /// and error `E`. Mirrors the states a frontend data hook moves through. 5 #[derive(Debug, Clone, PartialEq)] 6 enum Fetch<T, E> { 7 Idle, 8 Loading, 9 Success(T), 10 Failure(E), 11 } 12 13 impl<T, E> Fetch<T, E> { 14 /// A request is "terminal" once it has succeeded or failed. 15 fn is_terminal(&self) -> bool { 16 matches!(self, Fetch::Success(_) | Fetch::Failure(_)) 17 } 18 19 /// Transform the success payload, leaving the other states untouched. 20 fn map<U, F: FnOnce(T) -> U>(self, f: F) -> Fetch<U, E> { 21 match self { 22 Fetch::Idle => Fetch::Idle, 23 Fetch::Loading => Fetch::Loading, 24 Fetch::Success(value) => Fetch::Success(f(value)), 25 Fetch::Failure(err) => Fetch::Failure(err), 26 } 27 } 28 } 29 30 #[derive(Debug, Clone, PartialEq)] 31 struct User { 32 id: u32, 33 name: String, 34 } 35 36 #[derive(Debug, Clone, PartialEq)] 37 struct ApiError { 38 status: u16, 39 message: String, 40 } 41 42 impl fmt::Display for ApiError { 43 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 44 write!(f, "HTTP {}: {}", self.status, self.message) 45 } 46 } 47 48 fn render(state: &Fetch<User, ApiError>) -> String { 49 match state { 50 Fetch::Idle => "Click to load".to_string(), 51 Fetch::Loading => "Loading...".to_string(), 52 Fetch::Success(user) => format!("Welcome, {} (#{})", user.name, user.id), 53 Fetch::Failure(err) => format!("Error: {}", err), 54 } 55 } 56 57 fn main() { 58 let mut state: Fetch<User, ApiError> = Fetch::Idle; 59 println!("{}", render(&state)); // Click to load 60 61 state = Fetch::Loading; 62 println!("{}", render(&state)); // Loading... 63 println!("terminal? {}", state.is_terminal()); // false 64 65 state = Fetch::Success(User { id: 7, name: "Ada".to_string() }); 66 println!("{}", render(&state)); // Welcome, Ada (#7) 67 println!("terminal? {}", state.is_terminal()); // true 68 69 // Derive a display-name view without losing the state machine's shape. 70 let display: Fetch<String, ApiError> = state.clone().map(|u| u.name.to_uppercase()); 71 println!("{:?}", display); // Success("ADA") 72 73 let failed: Fetch<User, ApiError> = 74 Fetch::Failure(ApiError { status: 404, message: "not found".to_string() }); 75 println!("{}", render(&failed)); // Error: HTTP 404: not found 76 } ``` Real output: ```text 1 Click to load 2 Loading... 3 terminal? false 4 Welcome, Ada (#7) 5 terminal? true 6 Success("ADA") 7 Error: HTTP 404: not found ``` Note the `map` method’s own type parameters `<U, F: FnOnce(T) -> U>`: it converts a `Fetch<T, E>` into a `Fetch<U, E>` while preserving the error type, the same signature shape as `Option::map` and `Result::map`. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Rust Book — Generic Data Types (enums)](https://doc.rust-lang.org/book/ch10-01-syntax.html#in-enum-definitions) * [The Rust Book — Defining an Enum (`Option`)](https://doc.rust-lang.org/book/ch06-01-defining-an-enum.html) * [`std::option::Option` API docs](https://doc.rust-lang.org/std/option/enum.Option.html) * [`std::result::Result` API docs](https://doc.rust-lang.org/std/result/enum.Result.html) * [Rust Reference — Type layout & niche optimization](https://doc.rust-lang.org/reference/type-layout.html) ### Related sections in this guide [Section titled “Related sections in this guide”](#related-sections-in-this-guide) * [Generic Functions](/09-generics-traits/00-generic-functions/): type parameters on functions, monomorphization, the turbofish `::<>` * [Generic Structs](/09-generics-traits/01-generic-structs/): the same `<T>` machinery on structs, with multiple parameters and constrained impls * [Trait Bounds](/09-generics-traits/05-trait-bounds/): restricting a type parameter with `T: Trait` and `where` clauses * [Traits](/09-generics-traits/03-traits/): TypeScript interfaces become Rust traits * [Control Flow](/04-control-flow/) — `match`, `if let`, and exhaustiveness * [Error Handling](/08-error-handling/) — `Result`, the `?` operator, and error types in depth * [Smart Pointers](/10-smart-pointers/) — `Box<T>` for recursive enums and heap allocation * [Section 09 overview](/09-generics-traits/) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A generic singly linked list [Section titled “Exercise 1: A generic singly linked list”](#exercise-1-a-generic-singly-linked-list) **Difficulty:** Easy **Objective:** Define a recursive generic enum and write methods over it. **Instructions:** 1. Define `enum List<T> { Cons(T, Box<List<T>>), Nil }`. 2. Add `impl<T> List<T>` with `new()` (returns `Nil`), `push(self, value: T) -> Self` (prepends a value), and `len(&self) -> usize` (counts elements recursively). 3. In `main`, build a list of three numbers and print its length, then build a list of `&str` to prove it is generic. ```rust 1 #[derive(Debug)] 2 enum List<T> { 3 Cons(T, Box<List<T>>), 4 Nil, 5 } 6 7 impl<T> List<T> { 8 fn new() -> Self { 9 /* ??? */ 10 } 11 fn push(self, value: T) -> Self { 12 /* ??? */ 13 } 14 fn len(&self) -> usize { 15 // TODO: match on self 16 } 17 } ``` Solution ```rust 1 #[derive(Debug)] 2 enum List<T> { 3 Cons(T, Box<List<T>>), 4 Nil, 5 } 6 7 impl<T> List<T> { 8 fn new() -> Self { 9 List::Nil 10 } 11 12 fn push(self, value: T) -> Self { 13 // Prepend by wrapping the existing list as the tail. 14 List::Cons(value, Box::new(self)) 15 } 16 17 fn len(&self) -> usize { 18 match self { 19 List::Nil => 0, 20 List::Cons(_, rest) => 1 + rest.len(), 21 } 22 } 23 } 24 25 fn main() { 26 let list = List::new().push(1).push(2).push(3); 27 println!("len = {}", list.len()); // len = 3 28 println!("{:?}", list); // Cons(3, Cons(2, Cons(1, Nil))) 29 30 let words: List<&str> = List::new().push("a").push("b"); 31 println!("len = {}", words.len()); // len = 2 32 } ``` Real output: ```text 1 len = 3 2 Cons(3, Cons(2, Cons(1, Nil))) 3 len = 2 ``` The recursive variant must be wrapped in `Box` so the enum has a known, finite size. ### Exercise 2: `Either` combinators and conversion to `Result` [Section titled “Exercise 2: Either combinators and conversion to Result”](#exercise-2-either-combinators-and-conversion-to-result) **Difficulty:** Medium **Objective:** Add `map`-style combinators to a generic two-parameter enum and convert it into a standard `Result`. **Instructions:** 1. Define `enum Either<L, R> { Left(L), Right(R) }` (derive `Debug` and `PartialEq`). 2. Add `map_right<R2, F: FnOnce(R) -> R2>(self, f: F) -> Either<L, R2>` that transforms only the `Right` payload. 3. Add `into_result(self) -> Result<R, L>` treating `Left` as the error and `Right` as success. 4. Demonstrate both in `main`. Solution ```rust 1 #[derive(Debug, PartialEq)] 2 enum Either<L, R> { 3 Left(L), 4 Right(R), 5 } 6 7 impl<L, R> Either<L, R> { 8 fn map_right<R2, F: FnOnce(R) -> R2>(self, f: F) -> Either<L, R2> { 9 match self { 10 Either::Left(l) => Either::Left(l), 11 Either::Right(r) => Either::Right(f(r)), 12 } 13 } 14 15 fn into_result(self) -> Result<R, L> { 16 match self { 17 Either::Left(l) => Err(l), 18 Either::Right(r) => Ok(r), 19 } 20 } 21 } 22 23 fn main() { 24 let ok: Either<String, i32> = Either::Right(21); 25 let mapped = ok.map_right(|n| n * 2); 26 assert_eq!(mapped, Either::Right(42)); 27 println!("{:?}", mapped); // Right(42) 28 29 let err: Either<String, i32> = Either::Left("boom".to_string()); 30 println!("{:?}", err.into_result()); // Err("boom") 31 32 let good: Either<String, i32> = Either::Right(7); 33 println!("{:?}", good.into_result()); // Ok(7) 34 } ``` Real output: ```text 1 Right(42) 2 Err("boom") 3 Ok(7) ``` Note how `map_right` changes only the second type parameter (`R` to `R2`) while leaving `L` alone, the same trick `Result::map` uses. ### Exercise 3: A mappable, summable binary tree [Section titled “Exercise 3: A mappable, summable binary tree”](#exercise-3-a-mappable-summable-binary-tree) **Difficulty:** Hard **Objective:** Write a generic recursive enum with a structure-preserving `map` and a `sum` that requires a trait bound on the method. **Instructions:** 1. Define `enum Tree<T> { Leaf(T), Node(Box<Tree<T>>, Box<Tree<T>>) }`. 2. Add `map<U, F: Fn(&T) -> U>(&self, f: &F) -> Tree<U>` producing a new tree of the same shape with every leaf transformed. 3. Add `sum(&self) -> T` that only compiles when `T: Add<Output = T> + Copy` (use a `where` clause on the method, not the enum). 4. Build a tree of `i32`, print its sum, map it to doubled values and to `String` labels. Solution ```rust 1 #[derive(Debug)] 2 enum Tree<T> { 3 Leaf(T), 4 Node(Box<Tree<T>>, Box<Tree<T>>), 5 } 6 7 impl<T> Tree<T> { 8 // Produce a new tree of the same shape with every leaf transformed. 9 fn map<U, F: Fn(&T) -> U>(&self, f: &F) -> Tree<U> { 10 match self { 11 Tree::Leaf(value) => Tree::Leaf(f(value)), 12 Tree::Node(left, right) => { 13 Tree::Node(Box::new(left.map(f)), Box::new(right.map(f))) 14 } 15 } 16 } 17 18 // The bound lives on the method, so building a Tree<String> stays unconstrained. 19 fn sum(&self) -> T 20 where 21 T: std::ops::Add<Output = T> + Copy, 22 { 23 match self { 24 Tree::Leaf(value) => *value, 25 Tree::Node(left, right) => left.sum() + right.sum(), 26 } 27 } 28 } 29 30 fn main() { 31 let tree: Tree<i32> = Tree::Node( 32 Box::new(Tree::Leaf(1)), 33 Box::new(Tree::Node(Box::new(Tree::Leaf(2)), Box::new(Tree::Leaf(3)))), 34 ); 35 println!("sum = {}", tree.sum()); // sum = 6 36 37 let doubled = tree.map(&|n| n * 2); 38 println!("{:?}", doubled); // Node(Leaf(2), Node(Leaf(4), Leaf(6))) 39 println!("doubled sum = {}", doubled.sum()); // doubled sum = 12 40 41 let labels: Tree<String> = tree.map(&|n| format!("leaf-{}", n)); 42 println!("{:?}", labels); // Node(Leaf("leaf-1"), Node(Leaf("leaf-2"), Leaf("leaf-3"))) 43 } ``` Real output: ```text 1 sum = 6 2 Node(Leaf(2), Node(Leaf(4), Leaf(6))) 3 doubled sum = 12 4 Node(Leaf("leaf-1"), Node(Leaf("leaf-2"), Leaf("leaf-3"))) ``` Putting `T: Add<Output = T> + Copy` on `sum` rather than on the enum keeps `Tree<String>` valid (strings are not summable, but we never call `sum` on them). Trait bounds are covered in [Trait Bounds](/09-generics-traits/05-trait-bounds/), and the `Add` trait in [Operator Overloading](/09-generics-traits/10-operator-overloading/). # Rust Traits vs TypeScript Interfaces > Rust traits are TypeScript interfaces with a twist: impls are written separately, are nominal not structural, and let you add behavior to foreign types. Traits are Rust’s answer to TypeScript interfaces: a named set of behaviors a type can promise to provide. If you have ever written `interface Serializable { serialize(): string }` and implemented it on a class, you already know the shape of the idea. The mechanics, though, are deliberately different, and those differences are the whole point of this file. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **trait** declares a set of methods a type must provide; an `impl Trait for Type` block provides them. It is the closest Rust feature to a TypeScript `interface`, but with one big twist: in TypeScript a class declares “I implement this interface” at its definition, while in Rust the implementation is written **separately** from both the trait and the type. That separation lets you add behavior to types you did not define, and it powers generics, dynamic dispatch, and operator overloading throughout the language. > **Note:** In Rust we say **trait**, never “interface.” This file deliberately keeps the analogy front and center, but the vocabulary you should adopt is `trait` and `impl`. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Here is a small, realistic content-feed scenario in TypeScript. We define an interface describing “things that can summarize themselves,” then implement it on two classes. ```typescript 1 // TypeScript - an interface plus two classes that implement it 2 interface Summary { 3 summarize(): string; 4 } 5 6 class Article implements Summary { 7 constructor( 8 public title: string, 9 public author: string, 10 public body: string, 11 ) {} 12 13 summarize(): string { 14 return `${this.title} by ${this.author}`; 15 } 16 } 17 18 class Tweet implements Summary { 19 constructor( 20 public username: string, 21 public content: string, 22 ) {} 23 24 summarize(): string { 25 return `@${this.username}: ${this.content}`; 26 } 27 } 28 29 const article = new Article( 30 "Rust 1.96 released", 31 "The Rust Team", 32 "Today we are happy to announce...", 33 ); 34 const tweet = new Tweet("rustlang", "We just shipped a new release!"); 35 36 console.log(`Article: ${article.summarize()}`); 37 console.log(`Tweet: ${tweet.summarize()}`); ``` **Key points:** * The interface (`Summary`) only describes a shape; it has no runtime presence (TypeScript types are erased). * Each class opts in with `implements Summary` **at its own declaration**, and the method body lives inside the class. * Structural typing means a class with a matching `summarize()` would satisfy `Summary` even without `implements`. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same scenario in idiomatic Rust. Notice that the data (`struct`) and the behavior (`impl ... for ...`) are written as separate blocks. ```rust 1 // Rust - a trait plus two structs that implement it 2 trait Summary { 3 fn summarize(&self) -> String; 4 } 5 6 struct Article { 7 title: String, 8 author: String, 9 body: String, 10 } 11 12 struct Tweet { 13 username: String, 14 content: String, 15 } 16 17 impl Summary for Article { 18 fn summarize(&self) -> String { 19 format!("{} by {}", self.title, self.author) 20 } 21 } 22 23 impl Summary for Tweet { 24 fn summarize(&self) -> String { 25 format!("@{}: {}", self.username, self.content) 26 } 27 } 28 29 fn main() { 30 let article = Article { 31 title: String::from("Rust 1.96 released"), 32 author: String::from("The Rust Team"), 33 body: String::from("Today we are happy to announce..."), 34 }; 35 36 let tweet = Tweet { 37 username: String::from("rustlang"), 38 content: String::from("We just shipped a new release!"), 39 }; 40 41 println!("Article: {}", article.summarize()); 42 println!("Tweet: {}", tweet.summarize()); 43 } ``` **Real output:** ```text 1 Article: Rust 1.96 released by The Rust Team 2 Tweet: @rustlang: We just shipped a new release! ``` > **Note:** The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the **2024 edition**. Create new projects with `cargo new` — it auto-selects the newest edition — so you never need to pin an older one. Everything in this file is verified on a 2024-edition project. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) Let’s walk through the Rust version line by line and contrast each piece with the TypeScript you already know. ### Declaring the trait [Section titled “Declaring the trait”](#declaring-the-trait) ```rust 1 trait Summary { 2 fn summarize(&self) -> String; 3 } ``` * `trait Summary { ... }` declares the contract, exactly like `interface Summary { ... }`. * Inside, `fn summarize(&self) -> String;` is a **method signature with no body**: the semicolon ends it. This is a **required method**: any type implementing `Summary` must supply it. (Traits can also provide **default** method bodies; that is the focus of the sibling files [Trait Methods](/09-generics-traits/04-trait-methods/) and [Default Method Implementations](/09-generics-traits/08-default-impls/).) * `&self` is the receiver. It is the rough equivalent of `this` in a TypeScript method, but it is an explicit parameter and it is a **borrow**: an immutable reference to the value the method is called on. Other receiver forms are `&mut self` (a mutable borrow, like a mutating method) and `self` (takes ownership, consuming the value). Borrowing is covered in [Section 05: Ownership](/05-ownership/). ### The data is separate from the behavior [Section titled “The data is separate from the behavior”](#the-data-is-separate-from-the-behavior) In TypeScript, the method body lives inside the class. In Rust, the `struct` holds only data: ```rust 1 struct Article { 2 title: String, 3 author: String, 4 body: String, 5 } ``` and the behavior is bolted on afterward in a dedicated block: ```rust 1 impl Summary for Article { 2 fn summarize(&self) -> String { 3 format!("{} by {}", self.title, self.author) 4 } 5 } ``` Read `impl Summary for Article` as “implement the `Summary` trait for the `Article` type.” This is the headline syntactic difference from TypeScript: **the implementation is a free-standing item**, not a clause on the type definition. You can put it in the same file, a different module, or even (under certain rules) apply a trait you defined to a type from the standard library. ### `self` access and `format!` [Section titled “self access and format!”](#self-access-and-format) Inside `summarize`, `self.title` and `self.author` read fields through the borrow. `format!` is Rust’s string-building macro; it works like a template literal that returns a new `String` (it does not print). We use inline interpolation (`{}` positionally here; you can also write `format!("{title}")` to capture a variable named `title` directly). ### Calling the method [Section titled “Calling the method”](#calling-the-method) ```rust 1 println!("Article: {}", article.summarize()); ``` Method-call syntax (`value.method()`) is identical to TypeScript. The compiler resolves `summarize` to the `Summary` implementation for `Article`. One catch that has no TypeScript analogue: **the trait must be in scope** at the call site (more on this in Common Pitfalls). ### Inherent methods vs trait methods [Section titled “Inherent methods vs trait methods”](#inherent-methods-vs-trait-methods) A type can also have methods that belong to *no* trait; these live in an **inherent `impl`** block. Mixing both is common: ```rust 1 trait Summary { 2 fn summarize(&self) -> String; 3 } 4 5 struct Article { 6 title: String, 7 } 8 9 // Inherent impl: methods that belong only to Article (no trait). 10 impl Article { 11 fn new(title: &str) -> Self { 12 Article { title: title.to_string() } 13 } 14 fn word_count(&self) -> usize { 15 self.title.split_whitespace().count() 16 } 17 } 18 19 // Trait impl: fulfilling the Summary contract. 20 impl Summary for Article { 21 fn summarize(&self) -> String { 22 format!("\"{}\" ({} words)", self.title, self.word_count()) 23 } 24 } 25 26 fn main() { 27 let a = Article::new("Hello Rust World"); 28 println!("{}", a.summarize()); 29 } ``` **Real output:** ```text 1 "Hello Rust World" (3 words) ``` `impl Article { ... }` (no `for`) defines methods and associated functions like `Article::new`: the rough equivalent of a class’s own methods and `static` factory. `impl Summary for Article { ... }` separately fulfills the trait contract. The two coexist, and trait methods can call inherent methods (`self.word_count()`) and vice versa. `Self` (capitalized) inside an `impl` is an alias for the type being implemented. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript `interface` | Rust `trait` | | ------------------------------ | ------------------------------------ | --------------------------------------------- | | Where the impl lives | Inside the class (`implements`) | A separate `impl Trait for Type` block | | Opt-in vs structural | Structural: matching shape is enough | Nominal: you must write an explicit `impl` | | Runtime presence | Erased at compile time | Real: drives monomorphization and dispatch | | Add behavior to a foreign type | Not really (you’d subclass/wrap) | Yes, if you own the trait (the orphan rule) | | Default method bodies | Not in plain interfaces | Yes — provided methods | | Dispatch model | Always dynamic (every object) | Static by default; dynamic via `dyn` (opt-in) | ### Nominal, not structural [Section titled “Nominal, not structural”](#nominal-not-structural) This is the difference TypeScript developers feel first. In TypeScript, a class satisfies an interface if it has the right shape, whether or not it says `implements`. In Rust, a type implements a trait **only if there is an explicit `impl` block** for that exact trait. Two traits with identical method signatures are completely distinct, and a type that satisfies one does not automatically satisfy the other. This is *nominal* typing: the name of the trait matters, not just the shape. ### Traits are real at runtime; interfaces are erased [Section titled “Traits are real at runtime; interfaces are erased”](#traits-are-real-at-runtime-interfaces-are-erased) TypeScript interfaces vanish after compilation; they exist only to type-check your source. Rust traits stay relevant all the way to the binary. When you use a trait as a bound on a generic (`fn f<T: Summary>`), the compiler **monomorphizes**: it stamps out a specialized copy of the function for each concrete type, with no runtime lookup. (Compare this to TypeScript generics, which are erased; see [Generic Functions](/09-generics-traits/00-generic-functions/).) When you use a trait object (`&dyn Summary`), the compiler builds a vtable for dynamic dispatch, covered in [Trait Objects and Dynamic Dispatch](/09-generics-traits/06-trait-objects/). ### Implementation is decoupled — within limits [Section titled “Implementation is decoupled — within limits”](#implementation-is-decoupled--within-limits) Because the `impl` is separate, you can implement *your own* trait for a type you did not define (for example, implementing a `Pluralize` trait for `&str`). What you cannot do is implement a trait you do not own for a type you do not own: the **orphan rule**. That coherence rule has its own sibling file, [The Orphan Rule and Coherence](/09-generics-traits/12-orphan-rule/), and it appears as a pitfall below. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Calling a trait method without the trait in scope [Section titled “Pitfall 1: Calling a trait method without the trait in scope”](#pitfall-1-calling-a-trait-method-without-the-trait-in-scope) The implementation can exist and still be uncallable if the trait name is not imported. TypeScript has no equivalent: once a method exists on a class, it is always callable. src/shapes.rs ```rust 1 pub trait Area { 2 fn area(&self) -> f64; 3 } 4 pub struct Square { pub side: f64 } 5 impl Area for Square { 6 fn area(&self) -> f64 { self.side * self.side } 7 } 8 9 // src/main.rs 10 mod shapes; 11 use shapes::Square; // brought in the type but NOT the `Area` trait 12 13 fn main() { 14 let s = Square { side: 3.0 }; 15 println!("{}", s.area()); // does not compile (error[E0599]) 16 } ``` Real compiler error: ```text 1 error[E0599]: no method named `area` found for struct `Square` in the current scope 2 --> src/main.rs:6:22 3 | 4 6 | println!("{}", s.area()); 5 | ^^^^ method not found in `Square` 6 | 7 ::: src/shapes.rs:2:8 8 | 9 2 | fn area(&self) -> f64; 10 | ---- the method is available for `Square` here 11 3 | } 12 4 | pub struct Square { pub side: f64 } 13 | ----------------- method `area` not found for this struct 14 | 15 = help: items from traits can only be used if the trait is in scope 16 help: trait `Area` which provides `area` is implemented but not in scope; perhaps you want to import it 17 | 18 1 + use crate::shapes::Area; 19 | ``` **Fix:** bring the trait into scope with `use crate::shapes::Area;`. The compiler even prints the exact line to add. (Modules and `use` are covered in [Section 12](/12-modules-packages/).) ### Pitfall 2: Forgetting a required method [Section titled “Pitfall 2: Forgetting a required method”](#pitfall-2-forgetting-a-required-method) Unlike a TypeScript class — where a missing interface method is flagged at the class — Rust reports it on the `impl` block, and the whole crate fails to compile. ```rust 1 trait Greet { 2 fn hello(&self) -> String; 3 fn goodbye(&self) -> String; 4 } 5 6 struct Robot; 7 8 impl Greet for Robot { 9 fn hello(&self) -> String { 10 String::from("BEEP BOOP HELLO") 11 } 12 // Forgot to implement `goodbye` 13 } // does not compile (error[E0046]: missing `goodbye` in implementation) 14 15 fn main() {} ``` Real compiler error: ```text 1 error[E0046]: not all trait items implemented, missing: `goodbye` 2 --> src/main.rs:8:1 3 | 4 3 | fn goodbye(&self) -> String; 5 | ---------------------------- `goodbye` from trait 6 ... 7 8 | impl Greet for Robot { 8 | ^^^^^^^^^^^^^^^^^^^^ missing `goodbye` in implementation ``` **Fix:** implement every required method, or give the trait a default body for it (see [Default Method Implementations](/09-generics-traits/08-default-impls/)). ### Pitfall 3: Implementing a foreign trait for a foreign type (orphan rule) [Section titled “Pitfall 3: Implementing a foreign trait for a foreign type (orphan rule)”](#pitfall-3-implementing-a-foreign-trait-for-a-foreign-type-orphan-rule) Coming from TypeScript, it is tempting to “just add `Display` to `Vec<i32>`.” Rust forbids it because neither the trait nor the type is local to your crate. ```rust 1 use std::fmt::Display; 2 3 // Both Display (std) and Vec (std) are foreign to this crate. 4 impl Display for Vec<i32> { 5 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result { 6 write!(f, "a vector") 7 } 8 } // does not compile (error[E0117]) 9 10 fn main() {} ``` Real compiler error: ```text 1 error[E0117]: only traits defined in the current crate can be implemented for types defined outside of the crate 2 --> src/main.rs:4:1 3 | 4 4 | impl Display for Vec<i32> { 5 | ^^^^^^^^^^^^^^^^^-------- 6 | | 7 | `Vec` is not defined in the current crate 8 | 9 = note: impl doesn't have any local type before any uncovered type parameters 10 = note: for more information see https://doc.rust-lang.org/reference/items/implementations.html#orphan-rules 11 = note: define and implement a trait or new type instead ``` **Fix:** either define your own trait (you own the trait, so you may implement it for `Vec<i32>`), or wrap the foreign type in a local **newtype** (`struct MyVec(Vec<i32>)`) and implement the foreign trait for the wrapper. The full treatment is in [The Orphan Rule and Coherence](/09-generics-traits/12-orphan-rule/). ### Pitfall 4: Expecting structural matching [Section titled “Pitfall 4: Expecting structural matching”](#pitfall-4-expecting-structural-matching) A type that happens to have a `summarize(&self) -> String` method does **not** implement `Summary` unless you write `impl Summary for ThatType`. There is no duck typing here. If you want polymorphism, you must declare the relationship explicitly. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Keep traits small and focused [Section titled “Keep traits small and focused”](#keep-traits-small-and-focused) Prefer narrow traits with one clear responsibility (`Summary`, `Drawable`, `Notifier`) over a single mega-trait. Small traits compose well as bounds (`T: Summary + Clone`) and are easier to implement. This mirrors the interface-segregation instinct you already have in TypeScript. ### Name traits by capability, often with `-able` or a verb-noun [Section titled “Name traits by capability, often with -able or a verb-noun”](#name-traits-by-capability-often-with--able-or-a-verb-noun) The standard library sets the tone: `Display`, `Clone`, `Iterator`, `From`, `Default`. Trait names usually describe *what the type can do*. A good smell test: “this type **is** `Summary`-able.” ### Provide default method bodies to reduce boilerplate [Section titled “Provide default method bodies to reduce boilerplate”](#provide-default-method-bodies-to-reduce-boilerplate) If most implementors would write the same method, give it a default in the trait so implementors only override when needed. See [Default Method Implementations](/09-generics-traits/08-default-impls/). ### Let generic functions take the weakest bound that works [Section titled “Let generic functions take the weakest bound that works”](#let-generic-functions-take-the-weakest-bound-that-works) When you write a function over “anything summarizable,” prefer a generic with a trait bound (static dispatch, zero-cost) and reach for `dyn` only when you genuinely need a heterogeneous collection at runtime: ```rust 1 trait Summary { 2 fn summarize(&self) -> String; 3 } 4 5 struct BlogPost { 6 title: String, 7 } 8 9 impl Summary for BlogPost { 10 fn summarize(&self) -> String { 11 format!("Post: {}", self.title) 12 } 13 } 14 15 // A generic function constrained to any T that implements Summary. 16 fn announce<T: Summary>(item: &T) { 17 println!("Breaking! {}", item.summarize()); 18 } 19 20 fn main() { 21 let post = BlogPost { 22 title: String::from("Traits in Rust for TS/JS Developers"), 23 }; 24 announce(&post); 25 } ``` **Real output:** ```text 1 Breaking! Post: Traits in Rust for TS/JS Developers ``` Trait bounds are the topic of [Trait Bounds](/09-generics-traits/05-trait-bounds/), and the `impl Trait` shorthand for arguments and return types is covered in [`impl Trait`](/09-generics-traits/07-impl-trait/). ### Group inherent methods and trait impls thoughtfully [Section titled “Group inherent methods and trait impls thoughtfully”](#group-inherent-methods-and-trait-impls-thoughtfully) Put constructors and type-specific helpers in an inherent `impl Type` block; keep each `impl Trait for Type` focused on satisfying that one trait. This keeps the “what it is” separate from “what contracts it fulfills.” *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small notification system. Each delivery channel is its own type implementing a shared `Notifier` trait, and a dispatcher broadcasts a message across a heterogeneous list of channels. This is a classic place where defining a trait and implementing it per type pays off. ```rust 1 // Each channel implements one trait; the dispatcher works over any of them. 2 trait Notifier { 3 /// Send a message; returns a short delivery receipt string. 4 fn send(&self, message: &str) -> String; 5 } 6 7 struct Email { 8 address: String, 9 } 10 11 struct Sms { 12 phone: String, 13 } 14 15 struct Slack { 16 channel: String, 17 } 18 19 impl Notifier for Email { 20 fn send(&self, message: &str) -> String { 21 format!("email -> {}: {}", self.address, message) 22 } 23 } 24 25 impl Notifier for Sms { 26 fn send(&self, message: &str) -> String { 27 format!("sms -> {}: {}", self.phone, message) 28 } 29 } 30 31 impl Notifier for Slack { 32 fn send(&self, message: &str) -> String { 33 format!("slack -> #{}: {}", self.channel, message) 34 } 35 } 36 37 /// Broadcast one message to every configured channel. 38 fn broadcast(channels: &[Box<dyn Notifier>], message: &str) { 39 for channel in channels { 40 println!("{}", channel.send(message)); 41 } 42 } 43 44 fn main() { 45 let channels: Vec<Box<dyn Notifier>> = vec![ 46 Box::new(Email { address: "ops@example.com".into() }), 47 Box::new(Sms { phone: "+1-555-0100".into() }), 48 Box::new(Slack { channel: "incidents".into() }), 49 ]; 50 51 broadcast(&channels, "Deploy finished successfully"); 52 } ``` **Real output:** ```text 1 email -> ops@example.com: Deploy finished successfully 2 sms -> +1-555-0100: Deploy finished successfully 3 slack -> #incidents: Deploy finished successfully ``` Two things worth highlighting. First, `Vec<Box<dyn Notifier>>` is a heterogeneous list (different concrete types stored behind a common trait) which requires the dynamic-dispatch trait object (`dyn`); a plain generic `Vec<T>` could only hold one concrete type. `Box` is the heap-allocating smart pointer; see [Section 10: Smart Pointers](/10-smart-pointers/). Second, adding a new channel (say, `Webhook`) is purely additive: define the struct, write one `impl Notifier for Webhook`, and the dispatcher needs no changes. > **Tip:** If every channel always exists and you do not need a runtime-variable list of mixed types, prefer a generic `fn send_all<T: Notifier>(channel: &T, ...)` for zero-cost static dispatch. Choose `dyn` specifically when you need to mix types in one collection. The static-vs-dynamic trade-off is the subject of [Trait Objects and Dynamic Dispatch](/09-generics-traits/06-trait-objects/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Rust Book — Traits: Defining Shared Behavior](https://doc.rust-lang.org/book/ch10-02-traits.html) * [Rust by Example — Traits](https://doc.rust-lang.org/rust-by-example/trait.html) * [The Rust Reference — Traits](https://doc.rust-lang.org/reference/items/traits.html) * [The Rust Reference — Implementations & coherence](https://doc.rust-lang.org/reference/items/implementations.html) ### Related sections in this guide [Section titled “Related sections in this guide”](#related-sections-in-this-guide) * [Section 09 overview](/09-generics-traits/): the full map of generics and traits * [Trait Methods](/09-generics-traits/04-trait-methods/): required vs provided methods, overriding defaults * [Default Method Implementations](/09-generics-traits/08-default-impls/): default method bodies and how they cut boilerplate * [Trait Bounds](/09-generics-traits/05-trait-bounds/): constraining generics with `<T: Trait>` and `where` * [Trait Objects and Dynamic Dispatch](/09-generics-traits/06-trait-objects/) — `&dyn Trait` / `Box<dyn Trait>`, object safety, dispatch trade-offs * [`impl Trait`](/09-generics-traits/07-impl-trait/): `impl Trait` in argument and return position * [Supertraits](/09-generics-traits/09-supertraits/): requiring one trait as a prerequisite for another * [Operator Overloading](/09-generics-traits/10-operator-overloading/) — implementing `Add`, `Index`, and friends for your types * [The Orphan Rule and Coherence](/09-generics-traits/12-orphan-rule/): coherence, the orphan rule, and the newtype workaround * [Generic Functions](/09-generics-traits/00-generic-functions/): monomorphization vs TypeScript type erasure * [Section 05: Ownership](/05-ownership/) — what `&self`, `&mut self`, and `self` receivers mean * [Section 10: Smart Pointers](/10-smart-pointers/): `Box<dyn Trait>` and heap allocation *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Define and implement a trait [Section titled “Exercise 1: Define and implement a trait”](#exercise-1-define-and-implement-a-trait) **Difficulty:** Easy **Objective:** Practice the core `trait` / `impl Trait for Type` workflow on more than one type. **Instructions:** Define a trait `Describe` with one required method `describe(&self) -> String`. Create two structs, `Dog { name: String }` and `Cat { name: String }`, and implement `Describe` for both so that a dog says “woof” and a cat says “meow.” In `main`, construct one of each and print both descriptions. ```rust 1 trait Describe { 2 // TODO: declare describe(&self) -> String 3 } 4 5 struct Dog { name: String } 6 struct Cat { name: String } 7 8 // TODO: impl Describe for Dog 9 // TODO: impl Describe for Cat 10 11 fn main() { 12 // TODO: build a Dog and a Cat, print describe() for each 13 } ``` Solution ```rust 1 trait Describe { 2 fn describe(&self) -> String; 3 } 4 5 struct Dog { 6 name: String, 7 } 8 9 struct Cat { 10 name: String, 11 } 12 13 impl Describe for Dog { 14 fn describe(&self) -> String { 15 format!("{} the dog says woof", self.name) 16 } 17 } 18 19 impl Describe for Cat { 20 fn describe(&self) -> String { 21 format!("{} the cat says meow", self.name) 22 } 23 } 24 25 fn main() { 26 let d = Dog { name: String::from("Rex") }; 27 let c = Cat { name: String::from("Lily") }; 28 println!("{}", d.describe()); 29 println!("{}", c.describe()); 30 } ``` **Output:** ```text 1 Rex the dog says woof 2 Lily the cat says meow ``` ### Exercise 2: Implement your own trait for a standard-library type [Section titled “Exercise 2: Implement your own trait for a standard-library type”](#exercise-2-implement-your-own-trait-for-a-standard-library-type) **Difficulty:** Medium **Objective:** See how the orphan rule lets you extend a foreign type as long as *you* own the trait. **Instructions:** Define a trait `Pluralize` with a method `pluralize(&self, count: usize) -> String`. Implement it for `&str` so that `"apple".pluralize(1)` produces `"1 apple"` and `"apple".pluralize(3)` produces `"3 apples"` (append an `s` whenever `count != 1`). In `main`, print both. This is allowed even though `&str` is a foreign type, because the trait is local to your crate. ```rust 1 trait Pluralize { 2 // TODO: pluralize(&self, count: usize) -> String 3 } 4 5 // TODO: impl Pluralize for &str 6 7 fn main() { 8 // TODO: print "apple".pluralize(1) and "apple".pluralize(3) 9 } ``` Solution ```rust 1 // We OWN the trait, so we may implement it for the foreign type &str. 2 trait Pluralize { 3 fn pluralize(&self, count: usize) -> String; 4 } 5 6 impl Pluralize for &str { 7 fn pluralize(&self, count: usize) -> String { 8 if count == 1 { 9 format!("{count} {self}") 10 } else { 11 format!("{count} {self}s") 12 } 13 } 14 } 15 16 fn main() { 17 println!("{}", "apple".pluralize(1)); 18 println!("{}", "apple".pluralize(3)); 19 } ``` **Output:** ```text 1 1 apple 2 3 apples ``` > If you instead tried to implement a *standard-library* trait (like `Display`) for `&str`, the compiler would reject it with `error[E0117]`; see Pitfall 3. ### Exercise 3: A trait used through trait objects [Section titled “Exercise 3: A trait used through trait objects”](#exercise-3-a-trait-used-through-trait-objects) **Difficulty:** Hard **Objective:** Combine multiple required methods, multiple implementors, and a function that operates over a heterogeneous collection of trait objects. **Instructions:** Define a trait `Shape` with two required methods: `area(&self) -> f64` and `name(&self) -> &str`. Implement it for `Circle { radius: f64 }` (area = pi r squared, name `"circle"`) and `Square { side: f64 }` (area = side squared, name `"square"`). Write a free function `total_area(shapes: &[Box<dyn Shape>]) -> f64` that sums the areas. In `main`, build a `Vec<Box<dyn Shape>>` with one of each, print each shape’s name and area to two decimals, and print the total. ```rust 1 trait Shape { 2 // TODO: area(&self) -> f64 and name(&self) -> &str 3 } 4 5 struct Circle { radius: f64 } 6 struct Square { side: f64 } 7 8 // TODO: impl Shape for Circle and Square 9 10 fn total_area(shapes: &[Box<dyn Shape>]) -> f64 { 11 // TODO: sum the areas 12 } 13 14 fn main() { 15 // TODO: build the Vec<Box<dyn Shape>>, print names/areas, print total 16 } ``` Solution ```rust 1 trait Shape { 2 fn area(&self) -> f64; 3 fn name(&self) -> &str; 4 } 5 6 struct Circle { 7 radius: f64, 8 } 9 10 struct Square { 11 side: f64, 12 } 13 14 impl Shape for Circle { 15 fn area(&self) -> f64 { 16 std::f64::consts::PI * self.radius * self.radius 17 } 18 fn name(&self) -> &str { 19 "circle" 20 } 21 } 22 23 impl Shape for Square { 24 fn area(&self) -> f64 { 25 self.side * self.side 26 } 27 fn name(&self) -> &str { 28 "square" 29 } 30 } 31 32 fn total_area(shapes: &[Box<dyn Shape>]) -> f64 { 33 shapes.iter().map(|s| s.area()).sum() 34 } 35 36 fn main() { 37 let shapes: Vec<Box<dyn Shape>> = vec![ 38 Box::new(Circle { radius: 1.0 }), 39 Box::new(Square { side: 2.0 }), 40 ]; 41 for s in &shapes { 42 println!("{}: {:.2}", s.name(), s.area()); 43 } 44 println!("total: {:.2}", total_area(&shapes)); 45 } ``` **Output:** ```text 1 circle: 3.14 2 square: 4.00 3 total: 7.14 ``` > Storing different concrete types in one `Vec` requires the `dyn` trait object: a plain `Vec<T>` holds only one concrete type. The dynamic-dispatch mechanics are covered in detail in [Trait Objects and Dynamic Dispatch](/09-generics-traits/06-trait-objects/). # Trait Methods: Required vs Provided > Rust trait methods are required (signature only) or provided (default body), like an abstract class but with no super, so one trait holds contract and defaults. A TypeScript `interface` can only declare method *signatures*; the bodies always live somewhere else (a class, an object literal). A Rust **trait** can do both: it can declare a method that every implementor *must* write (a **required method**), and it can ship a method that already has a body (a **provided**, or **default**, method). This file is about that split: how you write each kind, how you call them, and how (and whether) you can override a default. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A trait method is either **required** (just a signature followed by `;` — every implementor supplies the body) or **provided** (the trait ships a default body that implementors inherit for free and may optionally override). Provided methods are how a trait like the standard library’s `Iterator` gives you \~70 methods (`map`, `filter`, `sum`, …) after you write a single required one (`next`). The closest TypeScript analogy is an abstract class with some abstract methods and some concrete ones. But, unlike TypeScript classes, there is no `super` to reach back into the default once you override it. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript you reach for an `abstract class` when you want to mix “you must implement this” with “here’s a sensible default”. Below, every logger *must* provide `name()`, but `level()` and `log()` come with working defaults that subclasses inherit. ```typescript 1 // TypeScript - abstract class: mix of abstract and concrete methods 2 abstract class Logger { 3 // "Required": subclasses MUST implement this (no body). 4 abstract name(): string; 5 6 // "Provided": a default the subclass inherits unless it overrides. 7 level(): string { 8 return "info"; 9 } 10 11 // A provided method built on top of the other two. 12 log(message: string): void { 13 console.log(`[${this.level()}] ${this.name()}: ${message}`); 14 } 15 } 16 17 class ConsoleLogger extends Logger { 18 name(): string { 19 return "console"; 20 } 21 // Inherits level() and log() unchanged. 22 } 23 24 class AuditLogger extends Logger { 25 name(): string { 26 return "audit"; 27 } 28 // Override the default, and still reach the parent via super. 29 level(): string { 30 return "audit-" + super.level(); // -> "audit-info" 31 } 32 } 33 34 const c = new ConsoleLogger(); 35 c.log("server started"); // [info] console: server started 36 37 const a = new AuditLogger(); 38 a.log("user 42 deleted record 7"); // [audit-info] audit: ... ``` Two TypeScript abilities to keep in mind, because Rust treats them differently: * A plain `interface` cannot carry method bodies at all — you need an `abstract class` (or a mixin) to get defaults. * An overriding method can call `super.level()` to reuse the parent implementation. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) A single Rust `trait` does the job of that abstract class. A method that ends in `;` is **required**; a method with a `{ ... }` body is **provided**. ```rust 1 trait Logger { 2 // REQUIRED: no body, so every implementor must supply it. 3 fn name(&self) -> String; 4 5 // PROVIDED (default): has a body. Implementors keep it or override it. 6 fn level(&self) -> &str { 7 "info" 8 } 9 10 // PROVIDED: builds on the required + provided methods above. 11 fn log(&self, message: &str) { 12 println!("[{}] {}: {}", self.level(), self.name(), message); 13 } 14 } 15 16 struct ConsoleLogger; 17 18 impl Logger for ConsoleLogger { 19 // Only the required method is mandatory. 20 fn name(&self) -> String { 21 "console".to_string() 22 } 23 // level() and log() are inherited from the defaults. 24 } 25 26 struct AuditLogger; 27 28 impl Logger for AuditLogger { 29 fn name(&self) -> String { 30 "audit".to_string() 31 } 32 33 // Override a provided method. (Note: there is no `super` to reuse 34 // the default body — see Common Pitfalls.) 35 fn level(&self) -> &str { 36 "audit" 37 } 38 } 39 40 fn main() { 41 let c = ConsoleLogger; 42 c.log("server started"); 43 44 let a = AuditLogger; 45 a.log("user 42 deleted record 7"); 46 println!("audit level = {}", a.level()); 47 } ``` Real output: ```text 1 [info] console: server started 2 [audit] audit: user 42 deleted record 7 3 audit level = audit ``` > **Note:** This file assumes you have already met the basics of declaring and implementing a trait. If `impl Logger for ConsoleLogger` looks unfamiliar, read [Traits](/09-generics-traits/03-traits/) first. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Required methods: a signature and a semicolon [Section titled “Required methods: a signature and a semicolon”](#required-methods-a-signature-and-a-semicolon) ```rust 1 fn name(&self) -> String; ``` The `;` where a body would go is the whole story: this is a **required method**. The trait promises every type implementing `Logger` will have a `name(&self) -> String`, but it refuses to guess what that string is. This is exactly an `abstract` method or a bare `interface` member in TypeScript: a contract with no implementation. If an `impl` block forgets a required method, the program does not compile. That is the key safety difference from a TypeScript `abstract class`: there is no way to “forget for now and crash later”, because there is no runtime later. ### Provided methods: a signature and a body [Section titled “Provided methods: a signature and a body”](#provided-methods-a-signature-and-a-body) ```rust 1 fn level(&self) -> &str { 2 "info" 3 } ``` Because `level` has a body, it is a **provided method**. An `impl` block that says nothing about `level` still gets this version. That is why `ConsoleLogger`’s `impl` block contains *only* `name` yet `console_logger.level()` and `console_logger.log(...)` both work. ### Defaults can call other trait methods — including required ones [Section titled “Defaults can call other trait methods — including required ones”](#defaults-can-call-other-trait-methods--including-required-ones) ```rust 1 fn log(&self, message: &str) { 2 println!("[{}] {}: {}", self.level(), self.name(), message); 3 } ``` This is the pattern that makes provided methods pull their weight. `log` is written once, in the trait, in terms of `self.level()` and `self.name()`. When `log` runs, `self.name()` dispatches to *whatever the concrete type defined*. So the trait author writes the orchestration once, and each implementor only fills in the small required pieces. The standard library’s `Iterator` is the canonical example: you implement the one required method `next`, and dozens of provided methods (`map`, `filter`, `sum`, `collect`, …) are written in terms of it. ```rust 1 // Implement only `next`; inherit `map`, `sum`, `collect`, and friends. 2 struct CountUp { n: u32, max: u32 } 3 4 impl Iterator for CountUp { 5 type Item = u32; 6 fn next(&mut self) -> Option<u32> { // the ONE required method 7 if self.n < self.max { 8 self.n += 1; 9 Some(self.n) 10 } else { 11 None 12 } 13 } 14 } 15 16 fn main() { 17 let total: u32 = CountUp { n: 0, max: 5 }.sum(); // provided 18 let doubled: Vec<u32> = CountUp { n: 0, max: 5 } 19 .map(|x| x * 2) // provided 20 .collect(); // provided 21 println!("sum = {total}, doubled = {doubled:?}"); 22 } ``` Real output: ```text 1 sum = 15, doubled = [2, 4, 6, 8, 10] ``` ### Calling trait methods three ways [Section titled “Calling trait methods three ways”](#calling-trait-methods-three-ways) Most of the time you call a trait method with ordinary method syntax (`value.method()`), and Rust figures out which trait it belongs to. But there are two more explicit forms, useful when a name is ambiguous or you want to be precise: ```rust 1 trait Summary { 2 fn title(&self) -> String; // required 3 fn author(&self) -> String; // required 4 5 // provided default that calls TWO required methods 6 fn summarize(&self) -> String { 7 format!("{} (by {})", self.title(), self.author()) 8 } 9 } 10 11 struct Article { 12 headline: String, 13 writer: String, 14 } 15 16 impl Summary for Article { 17 fn title(&self) -> String { 18 self.headline.clone() 19 } 20 fn author(&self) -> String { 21 self.writer.clone() 22 } 23 } 24 25 fn main() { 26 let a = Article { 27 headline: "Rust 1.96 released".to_string(), 28 writer: "The Rust Team".to_string(), 29 }; 30 31 // 1. Method-call syntax (what you'll write 99% of the time) 32 println!("{}", a.summarize()); 33 34 // 2. Trait-qualified call: name the trait, pass the receiver explicitly 35 println!("{}", Summary::summarize(&a)); 36 37 // 3. Fully-qualified syntax: name both the type AND the trait 38 println!("{}", <Article as Summary>::summarize(&a)); 39 } ``` Real output (all three lines identical): ```text 1 Rust 1.96 released (by The Rust Team) 2 Rust 1.96 released (by The Rust Team) 3 Rust 1.96 released (by The Rust Team) ``` Form 1 is idiomatic. Forms 2 and 3 exist for disambiguation. For instance, when a type implements two traits that both define a method named `summarize`, `<Article as Summary>::summarize(&a)` says exactly which one you mean. (See [Traits](/09-generics-traits/03-traits/) and [Trait Bounds](/09-generics-traits/05-trait-bounds/) for more on dispatch.) ### Overriding a default [Section titled “Overriding a default”](#overriding-a-default) An `impl` block overrides a provided method simply by defining it — same name, same signature, a new body. In the `Logger` example, `AuditLogger` defines its own `level()`, so its `log()` (still the default) prints `[audit]` instead of `[info]`. The override is total: once you write your own `level`, the trait’s default body is no longer reachable from inside `AuditLogger`. There is no `super`. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript | Rust | | --------------------------------- | -------------------------------------------- | ------------------------------------------------ | | ”Must implement” method | `abstract` method, or any `interface` member | **Required** method: signature + `;` | | ”Has a default” method | concrete method on an `abstract class` | **Provided** method: signature + `{ body }` | | Pure contract (no bodies) | `interface` | A trait with only required methods | | Mix contract + defaults | `abstract class` | One trait does both | | Forgetting a required method | runtime error / `any` escape hatch | **compile error** (`error[E0046]`) | | Reuse parent body after override | `super.method()` | **Not available** — refactor instead | | Calling a specific implementation | `super`, casts | trait-qualified / fully-qualified syntax | | Where defaults are dispatched | `this` (dynamic) | `self`, statically by default; dynamic via `dyn` | The single biggest mental adjustment: **a trait is one declaration that can hold both halves**, and there is **no `super`**. In TypeScript you separate “the contract” (`interface`) from “the partial implementation” (`abstract class`); in Rust those collapse into one trait. And where TypeScript lets an override delegate back up the chain with `super.level()`, Rust gives you no built-in hook into the overridden default. The idiom is to factor the shared work into its own method (shown below) so both the default and any override can call it. > **Note:** Default trait methods do **not** create an inheritance hierarchy. A trait override replaces the default for that type only; there is no chain of parents to climb. Rust models “is-a-kind-of” relationships through composition and [supertraits](/09-generics-traits/09-supertraits/), not class inheritance. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting a required method [Section titled “Pitfall 1: Forgetting a required method”](#pitfall-1-forgetting-a-required-method) If your `impl` block leaves out a required method, the compiler stops you. There is no “implement it later” the way a partially-typed TypeScript object might slide by. ```rust 1 trait Greeter { 2 fn name(&self) -> String; // required, no default 3 fn greet(&self) -> String { // provided 4 format!("Hello, {}!", self.name()) 5 } 6 } 7 8 struct Robot; 9 10 impl Greeter for Robot { 11 // does not compile (error[E0046]): forgot to implement `name` 12 } 13 14 fn main() { 15 let r = Robot; 16 println!("{}", r.greet()); 17 } ``` The real error: ```text 1 error[E0046]: not all trait items implemented, missing: `name` 2 --> src/main.rs:10:1 3 | 4 2 | fn name(&self) -> String; // required, no default 5 | ------------------------- `name` from trait 6 ... 7 10 | impl Greeter for Robot { 8 | ^^^^^^^^^^^^^^^^^^^^^^ missing `name` in implementation ``` The fix is to add the missing method. Notice the compiler points at exactly which trait item is missing: `name` is required (no body), but `greet` is provided, so leaving `greet` out is fine. ### Pitfall 2: Reaching for `super` inside an override [Section titled “Pitfall 2: Reaching for super inside an override”](#pitfall-2-reaching-for-super-inside-an-override) Coming from TypeScript, the natural instinct is to override `render` and call the parent’s version. There is no `super` in Rust, and `self.render()` calls *the very method you are writing* — infinite recursion. ```rust 1 trait Renderer { 2 fn render(&self) -> String { 3 "<default render>".to_string() 4 } 5 } 6 7 struct Fancy; 8 9 impl Renderer for Fancy { 10 fn render(&self) -> String { 11 // This calls THIS method again, not the trait's default. 12 let base = self.render(); // unconditional recursion! 13 format!("** {} **", base) 14 } 15 } 16 17 fn main() { 18 let f = Fancy; 19 println!("{}", f.render()); 20 } ``` The compiler catches the mistake at compile time with a default-on warning (the program would otherwise overflow the stack at runtime): ```text 1 warning: function cannot return without recursing 2 --> src/main.rs:10:5 3 | 4 10 | fn render(&self) -> String { 5 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ cannot return without recursing 6 11 | // This calls THIS method again, not the trait's default. 7 12 | let base = self.render(); // unconditional recursion! 8 | ------------- recursive call site 9 | 10 = help: a `loop` may express intention better if this is on purpose 11 = note: `#[warn(unconditional_recursion)]` on by default ``` The idiomatic fix is to extract the shared logic into its own method that *both* the default and the override can call: ```rust 1 trait Renderer { 2 // The shared logic lives in its own method, so both the default 3 // and any override can reuse it without recursion. 4 fn render_inner(&self) -> String; 5 6 fn render(&self) -> String { 7 self.render_inner() 8 } 9 } 10 11 struct Plain; 12 impl Renderer for Plain { 13 fn render_inner(&self) -> String { 14 "plain content".to_string() 15 } 16 // keeps the default render() 17 } 18 19 struct Fancy; 20 impl Renderer for Fancy { 21 fn render_inner(&self) -> String { 22 "fancy content".to_string() 23 } 24 fn render(&self) -> String { 25 // reuse the shared method, then decorate 26 format!("** {} **", self.render_inner()) 27 } 28 } 29 30 fn main() { 31 println!("{}", Plain.render()); 32 println!("{}", Fancy.render()); 33 } ``` Real output: ```text 1 plain content 2 ** fancy content ** ``` ### Pitfall 3: Expecting a default to “see” a struct field [Section titled “Pitfall 3: Expecting a default to “see” a struct field”](#pitfall-3-expecting-a-default-to-see-a-struct-field) A default method can only call other trait methods and use its parameters; it has no idea what fields the implementing struct has, because different implementors have different fields. If a default needs a piece of per-type data, expose it through a *required* method (often a small getter) and have the default call that. This is precisely what `log` does with `self.name()` above. ### Pitfall 4: Changing the signature when overriding [Section titled “Pitfall 4: Changing the signature when overriding”](#pitfall-4-changing-the-signature-when-overriding) An override must match the trait method’s signature exactly — same parameters, same return type, same receiver (`&self` vs `&mut self`). Changing it does not “overload”; it fails to compile because it no longer satisfies the trait. If you want a different shape, that is a different method (or a different trait). *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Make a method *provided* when a sensible default exists; make it *required* when only the implementor can know the answer.** A getter like `name()` is required; an orchestration like `log()` or `summarize()` is provided. * **Write provided methods in terms of a small set of required ones.** This is the “implement `next`, get everything else” pattern. Keep the required surface area minimal so implementors have little to write. * **Factor shared logic into its own method instead of reaching for `super`.** When several implementors want to extend a default, give them a helper method to call (Pitfall 2’s fix). * **Don’t add a default just because you can.** A default that is wrong for most implementors is worse than a required method, because implementors might silently inherit incorrect behavior. Require it instead, and let the compiler force a decision. * **Use plain method-call syntax** (`value.method()`) unless a name is genuinely ambiguous, in which case reach for `<Type as Trait>::method(...)`. * **Document which methods are meant to be overridden.** In `///` doc comments, note when a default is “override me to customize X” versus “you shouldn’t need to touch this”. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small, production-flavored validation framework. Each rule *must* supply its core `check`, but gets a free `is_valid` boolean helper and a `validate` method that decorates errors with the rule’s name: both provided, both written once in the trait. ```rust 1 /// A validation rule applied to a string field (e.g. a form input). 2 trait Validator { 3 /// REQUIRED: the core check. Returns `Ok(())` or an error message. 4 fn check(&self, input: &str) -> Result<(), String>; 5 6 /// PROVIDED: a human-readable rule name, used in default reporting. 7 fn rule_name(&self) -> &str { 8 "rule" 9 } 10 11 /// PROVIDED: turn `check` into a yes/no answer. 12 fn is_valid(&self, input: &str) -> bool { 13 self.check(input).is_ok() 14 } 15 16 /// PROVIDED: validate and prefix any error with the rule name. 17 fn validate(&self, input: &str) -> Result<(), String> { 18 self.check(input) 19 .map_err(|e| format!("[{}] {}", self.rule_name(), e)) 20 } 21 } 22 23 struct NonEmpty; 24 impl Validator for NonEmpty { 25 fn check(&self, input: &str) -> Result<(), String> { 26 if input.trim().is_empty() { 27 Err("must not be empty".to_string()) 28 } else { 29 Ok(()) 30 } 31 } 32 fn rule_name(&self) -> &str { 33 "non-empty" 34 } 35 } 36 37 struct MaxLen(usize); 38 impl Validator for MaxLen { 39 fn check(&self, input: &str) -> Result<(), String> { 40 if input.chars().count() > self.0 { 41 Err(format!("must be at most {} chars", self.0)) 42 } else { 43 Ok(()) 44 } 45 } 46 fn rule_name(&self) -> &str { 47 "max-len" 48 } 49 // Keeps the default `validate` and `is_valid`. 50 } 51 52 /// Run every rule against `input`, stopping at the first failure. 53 fn run(rules: &[&dyn Validator], input: &str) { 54 print!("{input:?} => "); 55 for rule in rules { 56 if let Err(msg) = rule.validate(input) { 57 println!("FAIL {msg}"); 58 return; 59 } 60 } 61 println!("OK"); 62 } 63 64 fn main() { 65 let rules: Vec<&dyn Validator> = vec![&NonEmpty, &MaxLen(8)]; 66 run(&rules, "alice"); 67 run(&rules, ""); 68 run(&rules, "this-is-way-too-long"); 69 70 // `is_valid` comes for free from the default impl. 71 println!("MaxLen(8).is_valid(\"ok\") = {}", MaxLen(8).is_valid("ok")); 72 } ``` Real output: ```text 1 "alice" => OK 2 "" => FAIL [non-empty] must not be empty 3 "this-is-way-too-long" => FAIL [max-len] must be at most 8 chars 4 MaxLen(8).is_valid("ok") = true ``` Each new rule only writes `check` (and an optional `rule_name`); `is_valid` and `validate` are inherited. The `&[&dyn Validator]` slice stores different rule types behind a trait object so they can be iterated uniformly. For the details of that mechanism, see [Trait Objects](/09-generics-traits/06-trait-objects/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book - Default Implementations](https://doc.rust-lang.org/book/ch10-02-traits.html#default-implementations) * [The Rust Book - Traits: Defining Shared Behavior](https://doc.rust-lang.org/book/ch10-02-traits.html) * [Rust by Example - Traits](https://doc.rust-lang.org/rust-by-example/trait.html) * [Rust Reference - Trait items and provided methods](https://doc.rust-lang.org/reference/items/traits.html) * [`std::iter::Iterator`](https://doc.rust-lang.org/std/iter/trait.Iterator.html): the canonical “one required method, many provided” trait ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Traits](/09-generics-traits/03-traits/) — interfaces become traits; defining and implementing a trait * [Default Implementations](/09-generics-traits/08-default-impls/) — a deeper look at how provided methods cut boilerplate * [Trait Bounds](/09-generics-traits/05-trait-bounds/) — `<T: Trait>` so generic code can call these methods * [Trait Objects](/09-generics-traits/06-trait-objects/): `&dyn Trait` / `Box<dyn Trait>` and dynamic dispatch (used in the validator example) * [Supertraits](/09-generics-traits/09-supertraits/) — requiring one trait for another (Rust’s answer to “inheritance”) * [`impl` Trait](/09-generics-traits/07-impl-trait/) — returning and accepting “some type that implements this trait” * [Operator Overloading](/09-generics-traits/10-operator-overloading/): traits like `Add` whose methods you implement * [Methods and `impl` Blocks](/06-data-structures/05-impl-blocks/) — `&self` / `&mut self` / `self` receivers, the foundation for trait method signatures * [Error Handling](/08-error-handling/) — the `Result<(), String>` returned by the validator * [Smart Pointers](/10-smart-pointers/): `Box<dyn Trait>` for owning trait objects *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A provided method that calls required ones [Section titled “Exercise 1: A provided method that calls required ones”](#exercise-1-a-provided-method-that-calls-required-ones) **Difficulty:** Easy **Objective:** Practice the “required getters + provided orchestration” pattern, and override a default. **Instructions:** Complete the trait so `describe` (provided) prints `"<name> says <noise>"` using the two required methods. Implement `Animal` for `Dog` (name `"Rex"`, noise `"woof"`) keeping the default `describe`, and for `Cat` (name `"Whiskers"`, noise `"meow"`) **overriding** `describe` to print `"The cat <name> disdainfully says <noise>"`. ```rust 1 trait Animal { 2 fn name(&self) -> String; // required 3 fn noise(&self) -> String; // required 4 fn describe(&self) -> String { 5 // TODO: "<name> says <noise>" 6 /* ??? */ 7 } 8 } 9 10 struct Dog; 11 struct Cat; 12 // TODO: impl Animal for Dog and Cat 13 14 fn main() { 15 println!("{}", Dog.describe()); 16 println!("{}", Cat.describe()); 17 } ``` Solution ```rust 1 trait Animal { 2 fn name(&self) -> String; 3 fn noise(&self) -> String; 4 fn describe(&self) -> String { 5 format!("{} says {}", self.name(), self.noise()) 6 } 7 } 8 9 struct Dog; 10 impl Animal for Dog { 11 fn name(&self) -> String { "Rex".to_string() } 12 fn noise(&self) -> String { "woof".to_string() } 13 // keeps the default describe() 14 } 15 16 struct Cat; 17 impl Animal for Cat { 18 fn name(&self) -> String { "Whiskers".to_string() } 19 fn noise(&self) -> String { "meow".to_string() } 20 fn describe(&self) -> String { 21 format!("The cat {} disdainfully says {}", self.name(), self.noise()) 22 } 23 } 24 25 fn main() { 26 println!("{}", Dog.describe()); 27 println!("{}", Cat.describe()); 28 } ``` Output: ```text 1 Rex says woof 2 The cat Whiskers disdainfully says meow ``` `Dog` only writes the two required getters and inherits `describe`. `Cat` overrides `describe` with a new body — and notice there is no `super`: it rebuilds the string itself by calling `self.name()` and `self.noise()` directly. ### Exercise 2: A default value plus an override [Section titled “Exercise 2: A default value plus an override”](#exercise-2-a-default-value-plus-an-override) **Difficulty:** Medium **Objective:** Ship a provided method with a useful default constant, then override it in one implementor. **Instructions:** Build a tiny HTTP-handler trait. `body` is required. `status` is provided and defaults to `200`. `respond` is provided and returns `"HTTP <status> | <body>"`. Implement `Home` (body `"Welcome"`, default status) and `NotFound` (body `"Page not found"`, status `404`). ```rust 1 trait Handler { 2 fn body(&self) -> String; // required 3 fn status(&self) -> u16 { // provided 4 /* ??? */ 5 } 6 fn respond(&self) -> String { // provided 7 // TODO: "HTTP <status> | <body>" 8 /* ??? */ 9 } 10 } 11 12 // TODO: struct Home; struct NotFound; + impls 13 14 fn main() { 15 // expected: 16 // HTTP 200 | Welcome 17 // HTTP 404 | Page not found 18 } ``` Solution ```rust 1 trait Handler { 2 fn body(&self) -> String; 3 fn status(&self) -> u16 { 4 200 5 } 6 fn respond(&self) -> String { 7 format!("HTTP {} | {}", self.status(), self.body()) 8 } 9 } 10 11 struct Home; 12 impl Handler for Home { 13 fn body(&self) -> String { "Welcome".to_string() } 14 // inherits status() == 200 and respond() 15 } 16 17 struct NotFound; 18 impl Handler for NotFound { 19 fn body(&self) -> String { "Page not found".to_string() } 20 fn status(&self) -> u16 { 404 } // override the default 21 } 22 23 fn main() { 24 println!("{}", Home.respond()); 25 println!("{}", NotFound.respond()); 26 } ``` Output: ```text 1 HTTP 200 | Welcome 2 HTTP 404 | Page not found ``` `respond` is written once in the trait. Because it calls `self.status()`, overriding `status` in `NotFound` automatically changes what `respond` prints — without `NotFound` touching `respond` at all. ### Exercise 3: One required method powering a provided one (Iterator-style) [Section titled “Exercise 3: One required method powering a provided one (Iterator-style)”](#exercise-3-one-required-method-powering-a-provided-one-iterator-style) **Difficulty:** Medium/Hard **Objective:** Reproduce the standard library’s “implement one method, get more for free” design, and override the provided method for a fast path. **Instructions:** Define a `Counter` trait whose only required method is `next_value(&mut self) -> u64`. Provide a default `take(&mut self, n) -> Vec<u64>` that calls `next_value` `n` times. Implement `Naturals` (counts `0, 1, 2, ...`) keeping the default `take`. Implement `Evens` (counts `0, 2, 4, ...`) and **override** `take` with a closed-form computation that avoids the loop while producing the same result and advancing the counter correctly. ```rust 1 trait Counter { 2 fn next_value(&mut self) -> u64; // required 3 fn take(&mut self, n: usize) -> Vec<u64> { 4 // TODO: call next_value() n times, collect into a Vec 5 /* ??? */ 6 } 7 } 8 9 struct Naturals { current: u64 } 10 struct Evens { current: u64 } 11 // TODO: impls 12 13 fn main() { 14 let mut nats = Naturals { current: 0 }; 15 println!("{:?}", nats.take(5)); // [0, 1, 2, 3, 4] 16 17 let mut evens = Evens { current: 0 }; 18 println!("{:?}", evens.take(5)); // [0, 2, 4, 6, 8] 19 } ``` Solution ```rust 1 trait Counter { 2 fn next_value(&mut self) -> u64; 3 4 fn take(&mut self, n: usize) -> Vec<u64> { 5 let mut out = Vec::with_capacity(n); 6 for _ in 0..n { 7 out.push(self.next_value()); 8 } 9 out 10 } 11 } 12 13 struct Naturals { current: u64 } 14 impl Counter for Naturals { 15 fn next_value(&mut self) -> u64 { 16 let v = self.current; 17 self.current += 1; 18 v 19 } 20 // keeps the default take() 21 } 22 23 struct Evens { current: u64 } 24 impl Counter for Evens { 25 fn next_value(&mut self) -> u64 { 26 let v = self.current; 27 self.current += 2; 28 v 29 } 30 // Override take() with a closed form; still advances `current`. 31 fn take(&mut self, n: usize) -> Vec<u64> { 32 let start = self.current; 33 let out: Vec<u64> = (0..n as u64).map(|i| start + i * 2).collect(); 34 self.current += (n as u64) * 2; 35 out 36 } 37 } 38 39 fn main() { 40 let mut nats = Naturals { current: 0 }; 41 println!("{:?}", nats.take(5)); 42 43 let mut evens = Evens { current: 0 }; 44 println!("{:?}", evens.take(5)); 45 } ``` Output: ```text 1 [0, 1, 2, 3, 4] 2 [0, 2, 4, 6, 8] ``` `Naturals` writes only the one required method and inherits the loop-based `take`. `Evens` proves overrides are free to use a completely different algorithm, as long as the observable result and the state change match — exactly how the standard library overrides `Iterator` defaults (e.g. `size_hint`, `count`) for performance. # Trait Bounds > Rust trait bounds limit a generic to types with the abilities you need, like TypeScript's extends: <T: Trait>, multiple bounds with +, and where clauses. In TypeScript, a generic like `<T extends Comparable>` says “`T` can be any type, as long as it has these capabilities.” Rust calls that constraint a **trait bound**, and it is not optional sugar: a generic function can only call a method on `T` if a bound *proves* `T` has that method. The bound is the contract that turns a type parameter from an opaque blob into something you can actually use. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **trait bound** restricts a generic type parameter to types that implement a particular **trait** (Rust’s version of an interface). You write it as `<T: Trait>`, combine several with `+`, and, when the list gets long, move them into a `where` clause for readability. Bounds also govern what a generic function is allowed to *return*. Unlike TypeScript’s `extends` constraints, which vanish at runtime, Rust checks every bound at compile time and then generates specialized machine code for each concrete type ([monomorphization](/09-generics-traits/00-generic-functions/)). > **Note:** This page focuses on the *bounds* themselves: the `<T: Trait>` syntax, multiple bounds, `where` clauses, and bounds on return types. Defining and implementing traits is covered in [Traits](/09-generics-traits/03-traits/); writing the generic functions that carry these bounds is in [Generic Functions](/09-generics-traits/00-generic-functions/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript you constrain a generic with `extends`. The constraint tells the compiler which properties and methods are guaranteed to exist on `T`, so the body can use them. ```typescript 1 // TypeScript - a generic constrained to "things that can be compared" 2 interface Ordered { 3 compareTo(other: this): number; // negative / 0 / positive 4 } 5 6 // `T extends Ordered` is the constraint: T must have compareTo. 7 function largest<T extends Ordered>(list: T[]): T { 8 let biggest = list[0]; 9 for (const item of list) { 10 if (item.compareTo(biggest) > 0) { 11 biggest = item; 12 } 13 } 14 return biggest; 15 } 16 17 class Version implements Ordered { 18 constructor(public major: number, public minor: number) {} 19 compareTo(other: Version): number { 20 return this.major - other.major || this.minor - other.minor; 21 } 22 } 23 24 const versions = [new Version(1, 2), new Version(2, 0), new Version(1, 9)]; 25 console.log(largest(versions)); // Version { major: 2, minor: 0 } ``` **Key points:** * `extends Ordered` is the constraint; without it, `item.compareTo` would be a type error. * Multiple constraints use an intersection type: `<T extends A & B>`. * At runtime the constraint is *erased*. `largest` is one function; TypeScript checked the types and then threw the type information away. There is no per-type specialization. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust expresses the same idea with a trait bound. Here we lean on the standard library’s `PartialOrd` trait (which gives us the `>` operator) instead of inventing a `compareTo`. ```rust 1 use std::fmt::Display; 2 3 // `T: PartialOrd` is the bound: T must support `<`, `>`, etc. 4 fn largest<T: PartialOrd>(list: &[T]) -> &T { 5 let mut biggest = &list[0]; 6 for item in list { 7 if item > biggest { 8 biggest = item; 9 } 10 } 11 biggest 12 } 13 14 // Multiple bounds with `+`: T must be BOTH Display (printable) AND PartialOrd. 15 fn announce_largest<T: Display + PartialOrd>(list: &[T]) { 16 let winner = largest(list); 17 println!("The largest value is {winner}"); 18 } 19 20 fn main() { 21 let numbers = [34, 50, 25, 100, 65]; 22 let words = ["pear", "apple", "fig", "banana"]; 23 24 announce_largest(&numbers); 25 announce_largest(&words); 26 } ``` **Output (compile-verified):** ```text 1 The largest value is 100 2 The largest value is pear ``` **Key points:** * `<T: PartialOrd>` is the bound. Drop it and `item > biggest` will not compile — Rust refuses to assume `T` is comparable. * `Display + PartialOrd` requires *both* traits; the `+` reads as “and.” * Unlike TypeScript, this is **monomorphized**: the compiler stamps out a separate, optimized `largest` for `i32` and another for `&str`. The bound is checked once, at compile time, then erased into concrete code. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Why the bound is mandatory, not optional [Section titled “Why the bound is mandatory, not optional”](#why-the-bound-is-mandatory-not-optional) In TypeScript an *unconstrained* `<T>` still lets you do a lot: you can pass `T` around, put it in arrays, return it. But the moment you call a method, you need a constraint. Rust takes this further: with a bare `<T>`, the **only** things you can do with a `T` value are move it, store it, and pass it on. You cannot print it, compare it, clone it, or add it, because nothing has promised those operations exist. ```rust 1 use std::fmt::Display; 2 3 trait Summary { 4 fn summarize(&self) -> String; 5 } 6 7 struct Article { 8 headline: String, 9 word_count: u32, 10 } 11 12 impl Summary for Article { 13 fn summarize(&self) -> String { 14 format!("{} ({} words)", self.headline, self.word_count) 15 } 16 } 17 18 // The bound `T: Summary` is precisely what makes `.summarize()` callable below. 19 fn print_summary<T: Summary>(item: &T) { 20 println!("Summary: {}", item.summarize()); 21 } 22 23 fn main() { 24 let a = Article { 25 headline: "Rust 1.96 released".into(), 26 word_count: 1200, 27 }; 28 print_summary(&a); 29 } ``` **Output (compile-verified):** ```text 1 Summary: Rust 1.96 released (1200 words) ``` Without `T: Summary`, the call `item.summarize()` would fail to compile, because the compiler does not know whether an arbitrary `T` has a `summarize` method. The bound is the proof. > **Tip:** Think of a bound as a *capability passport*. Inside the function body you may use exactly the methods the bounds grant — no more. This is why generic code in Rust feels stricter than in TypeScript: every capability must be declared up front. ### Single bound: `<T: Trait>` [Section titled “Single bound: \<T: Trait>”](#single-bound-t-trait) The simplest form. `T` may be any type that implements `Trait`: ```rust 1 // Accepts any type that knows how to clone itself. 2 fn duplicate<T: Clone>(value: T) -> (T, T) { 3 (value.clone(), value) 4 } ``` ### Multiple bounds: `<T: A + B>` [Section titled “Multiple bounds: \<T: A + B>”](#multiple-bounds-t-a--b) Use `+` to require several traits at once. The order does not matter: ```rust 1 use std::fmt::Debug; 2 3 // T must be clonable AND debug-printable. 4 fn clone_and_log<T: Clone + Debug>(value: &T) -> T { 5 println!("cloning {value:?}"); 6 value.clone() 7 } ``` This mirrors TypeScript’s `<T extends A & B>`, but `+` is a bound combinator, not a runtime type intersection. ### `where` clauses: bounds without the clutter [Section titled “where clauses: bounds without the clutter”](#where-clauses-bounds-without-the-clutter) When you have several type parameters each with several bounds, the angle-bracket form becomes a wall of text. A `where` clause moves the bounds below the signature, where they read top-to-bottom: ```rust 1 use std::collections::HashMap; 2 use std::fmt::{Debug, Display}; 3 use std::hash::Hash; 4 5 // `where` clause version — identical meaning, far more readable. 6 fn summarize<K, V>(map: &HashMap<K, V>) -> String 7 where 8 K: Display + Eq + Hash, 9 V: Debug, 10 { 11 let mut parts: Vec<String> = map 12 .iter() 13 .map(|(k, v)| format!("{k} = {v:?}")) 14 .collect(); 15 parts.sort(); // deterministic output for the example 16 parts.join(", ") 17 } 18 19 fn main() { 20 let mut scores = HashMap::new(); 21 scores.insert("alice", vec![90, 85]); 22 scores.insert("bob", vec![70]); 23 24 println!("{}", summarize(&scores)); 25 } ``` **Output (compile-verified):** ```text 1 alice = [90, 85], bob = [70] ``` The inline equivalent, `fn summarize<K: Display + Eq + Hash, V: Debug>(...)`, compiles to the same thing. Pick whichever is more readable. The community convention is: one short bound inline, anything longer in a `where` clause. `where` clauses also enable bounds you *cannot* write inline, such as bounds on associated types or on `&T` rather than `T`. ### Bounds on the return type [Section titled “Bounds on the return type”](#bounds-on-the-return-type) Bounds gate what you can call and what you can *produce*. Two common patterns: **1. A bound that lets you synthesize a return value.** Here `T: Default` is what makes `T::default()` legal: ```rust 1 // `T: Default` lets us conjure a value when the Option is None. 2 fn or_default<T: Default>(opt: Option<T>) -> T { 3 match opt { 4 Some(v) => v, 5 None => T::default(), 6 } 7 } 8 9 fn main() { 10 let a: i32 = or_default(Some(42)); 11 let b: i32 = or_default(None); 12 let c: String = or_default(None); 13 println!("{a} {b} {c:?}"); 14 } ``` **Output (compile-verified):** ```text 1 42 0 "" ``` **2. Returning a *bounded* anonymous type with `impl Trait`.** Sometimes the concrete return type is unspeakable (a closure, a chained iterator). You return “some type that satisfies this bound” and let the compiler fill in the real type: ```rust 1 // The caller only learns: "this returns something that yields u32s." 2 fn evens(upto: u32) -> impl Iterator<Item = u32> { 3 (0..upto).filter(|n| n % 2 == 0) 4 } 5 6 fn main() { 7 let collected: Vec<u32> = evens(10).collect(); 8 println!("{collected:?}"); 9 } ``` **Output (compile-verified):** ```text 1 [0, 2, 4, 6, 8] ``` `impl Iterator<Item = u32>` in return position is a *return-position bound*: it promises the caller the value implements `Iterator` without naming the messy concrete type (`Filter<Range<u32>, {closure}>`). This is a distinct feature with its own subtleties; see [impl Trait](/09-generics-traits/07-impl-trait/) for the full treatment. The key idea for *this* page is that a bound can describe a return value, not only an argument. > **Warning:** `impl Trait` in return position names **one** hidden concrete type for the whole function. You cannot return a `Filter` from one branch and a `Vec`’s iterator from another, even though both implement `Iterator`. We will see the exact compiler error in [Common Pitfalls](#common-pitfalls). ### `impl Trait` in argument position is just a bound in disguise [Section titled “impl Trait in argument position is just a bound in disguise”](#impl-trait-in-argument-position-is-just-a-bound-in-disguise) This signature: ```rust 1 trait Summary { 2 fn summarize(&self) -> String; 3 } 4 5 struct Article { 6 headline: String, 7 } 8 9 impl Summary for Article { 10 fn summarize(&self) -> String { 11 self.headline.clone() 12 } 13 } 14 15 fn print_summary(item: &impl Summary) { 16 println!("{}", item.summarize()); 17 } 18 19 fn main() { 20 let a = Article { 21 headline: "Rust 1.96 released".into(), 22 }; 23 print_summary(&a); 24 } ``` is sugar for the generic form `fn print_summary<T: Summary>(item: &T)`. They generate the same code. The `&impl Summary` form is shorter when you have a single parameter and no need to name `T`; the explicit `<T: Summary>` form is required when two parameters must be the *same* type. (More on this trade-off in [impl Trait](/09-generics-traits/07-impl-trait/).) *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | TypeScript (`extends`) | Rust (trait bound) | | ---------------------------------- | --------------------------------------------------- | --------------------------------------------------------- | | Syntax | `<T extends Constraint>` | `<T: Trait>` | | Multiple constraints | `<T extends A & B>` | `<T: A + B>` | | Long constraint lists | inline only | `where` clause available | | Runtime presence | **erased**: one function for all types | **monomorphized**: one specialized copy per concrete type | | Unconstrained `<T>` | can still access `Object` methods, structural shape | can *only* move/store/pass the value | | Constraint on a method’s existence | structural (“has this shape”) | nominal (“implements this trait”) | | Return-type constraint | `: SomeInterface` return annotation | `-> impl Trait` (one hidden type) | | Numeric/operator constraints | not really expressible | `T: Add`, `T: PartialOrd`, etc. | ### Structural vs nominal [Section titled “Structural vs nominal”](#structural-vs-nominal) TypeScript constraints are **structural**: `T extends { len(): number }` is satisfied by *any* object with a `len` method, whether or not it ever heard of your interface. Rust bounds are **nominal**: `T: HasLen` is satisfied only by types that *explicitly* wrote `impl HasLen for ThatType`. This is stricter, but it means a bound is a deliberate contract, not an accident of shape. (The flip side, that you cannot retroactively bolt a foreign trait onto a foreign type, is the [orphan rule](/09-generics-traits/12-orphan-rule/).) ### Bounds enable operators [Section titled “Bounds enable operators”](#bounds-enable-operators) In TypeScript you cannot write a generic “add anything addable” function, because `+` is hardcoded to `number`/`string`. In Rust, operators *are* traits, so `T: std::ops::Add<Output = T>` is a perfectly ordinary bound. This is why generic numeric code is expressible in Rust but awkward in TypeScript. See [Operator Overloading](/09-generics-traits/10-operator-overloading/). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Using an operator or method without the bound that grants it [Section titled “Pitfall 1: Using an operator or method without the bound that grants it”](#pitfall-1-using-an-operator-or-method-without-the-bound-that-grants-it) The single most common beginner error. You write a generic function, use `>` (or `.clone()`, or `{}` formatting), and forget to declare the bound. ```rust 1 // does not compile (error[E0369]: binary operation `>` cannot be applied to type `&T`) 2 fn largest<T>(list: &[T]) -> &T { 3 let mut biggest = &list[0]; 4 for item in list { 5 if item > biggest { 6 biggest = item; 7 } 8 } 9 biggest 10 } ``` The real compiler output: ```text 1 error[E0369]: binary operation `>` cannot be applied to type `&T` 2 --> src/main.rs:5:17 3 | 4 5 | if item > biggest { 5 | ---- ^ ------- &T 6 | | 7 | &T 8 | 9 help: consider restricting type parameter `T` with trait `PartialOrd` 10 | 11 2 | fn largest<T: std::cmp::PartialOrd>(list: &[T]) -> &T { 12 | ++++++++++++++++++++++ ``` The fix is exactly what the compiler suggests: add `<T: PartialOrd>`. Rust’s diagnostics almost always tell you which bound is missing. The same thing happens with methods. Calling `.clone()` without `T: Clone`: ```rust 1 // does not compile (error[E0599]: no method named `clone` found for type parameter `T`) 2 fn duplicate<T>(value: T) -> (T, T) { 3 (value.clone(), value) 4 } ``` ```text 1 error[E0599]: no method named `clone` found for type parameter `T` in the current scope 2 --> src/main.rs:3:12 3 | 4 2 | fn duplicate<T>(value: T) -> (T, T) { 5 | - method `clone` not found for this type parameter 6 3 | (value.clone(), value) 7 | ^^^^^ method not found in `T` 8 | 9 = help: items from traits can only be used if the type parameter is bounded by the trait 10 help: the following trait defines an item `clone`, perhaps you need to restrict type parameter `T` with it: 11 | 12 2 | fn duplicate<T: Clone>(value: T) -> (T, T) { 13 | +++++++ ``` Add `<T: Clone>` and it compiles. ### Pitfall 2: Returning two different types from one `impl Trait` [Section titled “Pitfall 2: Returning two different types from one impl Trait”](#pitfall-2-returning-two-different-types-from-one-impl-trait) Coming from TypeScript, you expect that since both `Map` and `Vec`’s iterator “are iterators,” you can return either from an `-> impl Iterator` function. You cannot: `impl Trait` resolves to a *single* concrete type. ```rust 1 // does not compile (error[E0308]: `if` and `else` have incompatible types) 2 fn make_iter(flag: bool) -> impl Iterator<Item = i32> { 3 if flag { 4 (0..3).map(|n| n * 2) 5 } else { 6 vec![1, 2, 3].into_iter() 7 } 8 } ``` The real error, abridged: ```text 1 error[E0308]: `if` and `else` have incompatible types 2 --> src/main.rs:6:9 3 | 4 4 | (0..3).map(|n| n * 2) 5 | --------------------- expected because of this 6 6 | vec![1, 2, 3].into_iter() 7 | ^^^^^^^^^^^^^^^^^^^^^^^^^ expected `Map<Range<{integer}>, {closure@...}>`, found `IntoIter<{integer}>` 8 | 9 help: you could change the return type to be a boxed trait object 10 | 11 2 - fn make_iter(flag: bool) -> impl Iterator<Item = i32> { 12 2 + fn make_iter(flag: bool) -> Box<dyn Iterator<Item = i32>> { ``` The compiler even suggests the fix: when you genuinely need to return different concrete types from different branches, use a **trait object** (`Box<dyn Iterator<Item = i32>>`) and `Box::new(...)` each branch. That trades static dispatch for dynamic dispatch. See [Trait Objects](/09-generics-traits/06-trait-objects/). ### Pitfall 3: Over-constraining “just in case” [Section titled “Pitfall 3: Over-constraining “just in case””](#pitfall-3-over-constraining-just-in-case) Bounds are part of your function’s public contract. A bound you do not actually need makes the function harder to call for no benefit. Require `T: Clone + Debug + Display + PartialOrd` when the body only ever clones, and every caller is forced to satisfy three irrelevant traits. ```rust 1 // Over-constrained: only Clone is used. 2 fn make_pair<T: Clone + std::fmt::Debug + std::fmt::Display>(x: T) -> (T, T) { 3 (x.clone(), x) 4 } 5 6 // Right-sized: ask only for what the body needs. 7 fn make_pair_better<T: Clone>(x: T) -> (T, T) { 8 (x.clone(), x) 9 } ``` > **Tip:** Add a bound only when the compiler asks for it. If a method call fails to compile, *then* add the bound it names. Start minimal. ### Pitfall 4: Forgetting `Sized` is implicit (and when to relax it) [Section titled “Pitfall 4: Forgetting Sized is implicit (and when to relax it)”](#pitfall-4-forgetting-sized-is-implicit-and-when-to-relax-it) Every type parameter `<T>` carries an invisible `T: Sized` bound: the value has a known size at compile time. This is usually invisible and correct. But if you want to accept *unsized* types like `str` or `[T]` or `dyn Trait` behind a reference, you must opt out with `?Sized`: ```rust 1 use std::fmt::Display; 2 3 // `T: ?Sized` lets this accept `&str`, `&dyn Display`, etc. — not just sized types. 4 fn show<T: Display + ?Sized>(value: &T) { 5 println!("{value}"); 6 } 7 8 fn main() { 9 show("a string slice"); // str is unsized — works thanks to ?Sized 10 show(&42); 11 } ``` **Output (compile-verified):** ```text 1 a string slice 2 42 ``` `?Sized` is a *relaxation*, not an additional bound. See [Marker Traits](/09-generics-traits/11-marker-traits/) for `Sized` and friends. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Ask for the least.** Constrain a type parameter only by the traits the body actually uses. Minimal bounds = maximal callers. * **Inline one short bound; use `where` for the rest.** `fn f<T: Clone>(...)` reads fine inline. The moment you have two parameters or three-plus traits, switch to a `where` clause. * **Prefer `&str` / `&[T]` parameters over generic bounds when you only read.** A function that just reads a string slice should take `&str`, not `<S: AsRef<str>>`: simpler signature, no monomorphization bloat, identical ergonomics for the caller. * **Reach for standard-library traits.** `Clone`, `Debug`, `Display`, `Default`, `PartialOrd`/`Ord`, `From`/`Into`, `Iterator`, `Hash`, `Eq` cover the vast majority of bounds. Custom traits are for genuinely domain-specific capabilities. * **Let the compiler drive your bounds.** Write the body first; when a call fails, the error message names the exact trait to add. This avoids both under- and over-constraining. * **Use `-> impl Trait` to hide gnarly return types**, but remember it is one concrete type. If branches return different types, switch to `Box<dyn Trait>`. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A generic “save this record” helper for a persistence layer. Any type that can be serialized (via [`serde`](/15-serialization/)’s `Serialize` trait) and logged (via `Debug`) can flow through one function, with no per-type save code. The bounds `Serialize + Debug` are the whole contract. ```rust 1 use serde::Serialize; 2 use std::fmt::Debug; 3 4 /// Persists any serializable, debug-printable record and returns its JSON. 5 /// The `where` clause is the contract: callers may pass anything that is 6 /// both `Serialize` (so we can turn it into JSON) and `Debug` (so we can log it). 7 fn save_record<T>(label: &str, record: &T) -> String 8 where 9 T: Serialize + Debug, 10 { 11 let json = serde_json::to_string(record).expect("serialize"); 12 println!("[{label}] saving {record:?}"); 13 json 14 } 15 16 #[derive(Debug, Serialize)] 17 struct User { 18 id: u32, 19 name: String, 20 } 21 22 #[derive(Debug, Serialize)] 23 struct Product { 24 sku: String, 25 price_cents: u64, 26 } 27 28 fn main() { 29 let u = User { id: 1, name: "Ada".into() }; 30 let p = Product { sku: "RS-01".into(), price_cents: 4999 }; 31 32 // One generic function, two unrelated record types. 33 let user_json = save_record("users", &u); 34 let product_json = save_record("products", &p); 35 36 println!("{user_json}"); 37 println!("{product_json}"); 38 } ``` Add the dependencies with: ```bash 1 cargo add serde --features derive 2 cargo add serde_json ``` **Output (compile-verified):** ```text 1 [users] saving User { id: 1, name: "Ada" } 2 [products] saving Product { sku: "RS-01", price_cents: 4999 } 3 {"id":1,"name":"Ada"} 4 {"sku":"RS-01","price_cents":4999} ``` Because of monomorphization, the compiler generates a specialized `save_record` for `User` and another for `Product`. There is no runtime dispatch and no reflection; the `Serialize` and `Debug` bounds were resolved entirely at compile time. The TypeScript analogue, `function saveRecord<T>(label: string, record: T): string`, would lean on `JSON.stringify` and reflection at runtime; Rust bakes the serialization code in ahead of time, per type. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Traits: Defining Shared Behavior (Trait Bound Syntax)](https://doc.rust-lang.org/book/ch10-02-traits.html#traits-as-parameters) * [The Rust Book — `where` clauses for clearer code](https://doc.rust-lang.org/book/ch10-02-traits.html#clearer-trait-bounds-with-where-clauses) * [The Rust Reference — Trait and lifetime bounds](https://doc.rust-lang.org/reference/trait-bounds.html) * [Rust by Example — Bounds](https://doc.rust-lang.org/rust-by-example/generics/bounds.html) * [Rust by Example — `where` clauses](https://doc.rust-lang.org/rust-by-example/generics/where.html) ### Related Topics in This Guide [Section titled “Related Topics in This Guide”](#related-topics-in-this-guide) * [Generic Functions](/09-generics-traits/00-generic-functions/): declaring `<T>`, monomorphization, and the turbofish * [Traits](/09-generics-traits/03-traits/): defining and implementing the traits you bound against * [Trait Methods](/09-generics-traits/04-trait-methods/): what methods a bound actually grants you * [impl Trait](/09-generics-traits/07-impl-trait/) — argument- and return-position `impl Trait` in depth * [Trait Objects](/09-generics-traits/06-trait-objects/) — `Box<dyn Trait>` for when one return type is not enough * [Supertraits](/09-generics-traits/09-supertraits/): bounds *on a trait itself* * [Marker Traits](/09-generics-traits/11-marker-traits/): `Sized`, `Send`, `Sync`, and `?Sized` * [Operator Overloading](/09-generics-traits/10-operator-overloading/) — bounding on `Add`, `Mul`, etc. * [The Orphan Rule](/09-generics-traits/12-orphan-rule/): why bounds are nominal, not structural * Foundations: [Getting Started](/01-getting-started/) and [Basics](/02-basics/) * Next up after this section: [Smart Pointers](/10-smart-pointers/), where `Box<dyn Trait>` returns *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A bounded `smallest` [Section titled “Exercise 1: A bounded smallest”](#exercise-1-a-bounded-smallest) **Difficulty:** Easy **Objective:** Write a generic function with the right trait bounds to find the minimum of a slice. **Instructions:** Implement `smallest` so it returns the smallest element of a slice *by value*. You will need two bounds: one to compare elements, and one to copy small values out of the slice. Make it work for both integers and floats. ```rust 1 fn smallest<T: /* ??? */>(list: &[T]) -> T { 2 // TODO 3 /* ??? */ 4 } 5 6 fn main() { 7 println!("{}", smallest(&[5, 2, 9, 1, 7])); // 1 8 println!("{}", smallest(&[3.5, 1.1, 2.2])); // 1.1 9 } ``` Solution ```rust 1 fn smallest<T: PartialOrd + Copy>(list: &[T]) -> T { 2 let mut min = list[0]; 3 for &item in list { 4 if item < min { 5 min = item; 6 } 7 } 8 min 9 } 10 11 fn main() { 12 println!("{}", smallest(&[5, 2, 9, 1, 7])); // 1 13 println!("{}", smallest(&[3.5, 1.1, 2.2])); // 1.1 14 } ``` **Output:** ```text 1 1 2 1.1 ``` `PartialOrd` grants `<`; `Copy` lets us pull each element out of the slice by value (`for &item in list`) and return one without borrowing. Floats only implement `PartialOrd` (not `Ord`), so `PartialOrd` is the correct, more general bound here. ### Exercise 2: Convert inline bounds to a `where` clause [Section titled “Exercise 2: Convert inline bounds to a where clause”](#exercise-2-convert-inline-bounds-to-a-where-clause) **Difficulty:** Medium **Objective:** Practice multiple bounds and the `where` syntax. **Instructions:** Write `describe_extremes` that takes a slice and returns a `String` like `"min = 3, max = 22"`. The element type must be comparable, printable with `{}`, and copyable. Put all the bounds in a `where` clause rather than inline. ```rust 1 use std::fmt::Display; 2 3 fn describe_extremes<T>(list: &[T]) -> String 4 where 5 /* ??? */ 6 { 7 // TODO 8 /* ??? */ 9 } 10 11 fn main() { 12 println!("{}", describe_extremes(&[10, 4, 7, 22, 3])); 13 } ``` Solution ```rust 1 use std::fmt::Display; 2 3 fn describe_extremes<T>(list: &[T]) -> String 4 where 5 T: PartialOrd + Display + Copy, 6 { 7 let mut lo = list[0]; 8 let mut hi = list[0]; 9 for &item in list { 10 if item < lo { 11 lo = item; 12 } 13 if item > hi { 14 hi = item; 15 } 16 } 17 format!("min = {lo}, max = {hi}") 18 } 19 20 fn main() { 21 println!("{}", describe_extremes(&[10, 4, 7, 22, 3])); 22 } ``` **Output:** ```text 1 min = 3, max = 22 ``` `PartialOrd` powers the `<`/`>` comparisons, `Display` powers the `{lo}`/`{hi}` formatting, and `Copy` lets us read elements out by value. The `where` clause keeps the signature line clean; the inline form `<T: PartialOrd + Display + Copy>` compiles identically. ### Exercise 3: A bounded return type [Section titled “Exercise 3: A bounded return type”](#exercise-3-a-bounded-return-type) **Difficulty:** Medium **Objective:** Return a value described only by a trait bound, using `impl Trait`. **Instructions:** Write `repeated(value, times)` that returns an iterator yielding `value` exactly `times` times. Do not name the concrete iterator type; return `impl Iterator<Item = i32>`. (Hint: `std::iter::repeat(value).take(times)`.) ```rust 1 fn repeated(value: i32, times: usize) -> /* ??? */ { 2 // TODO 3 /* ??? */ 4 } 5 6 fn main() { 7 let v: Vec<i32> = repeated(8, 3).collect(); 8 println!("{v:?}"); // [8, 8, 8] 9 } ``` Solution ```rust 1 fn repeated(value: i32, times: usize) -> impl Iterator<Item = i32> { 2 std::iter::repeat(value).take(times) 3 } 4 5 fn main() { 6 let v: Vec<i32> = repeated(8, 3).collect(); 7 println!("{v:?}"); // [8, 8, 8] 8 } ``` **Output:** ```text 1 [8, 8, 8] ``` The real return type is `std::iter::Take<std::iter::Repeat<i32>>`, which is verbose and an implementation detail. `impl Iterator<Item = i32>` is a return-position bound: it tells callers exactly what they can do with the value (iterate `i32`s) while hiding the concrete type. See [impl Trait](/09-generics-traits/07-impl-trait/) to go deeper. # Trait Objects and Dynamic Dispatch > Trait objects bring runtime polymorphism to Rust via dyn Trait, like a TS Renderer[]. Learn Box<dyn>, vtables, dyn compatibility, and dynamic vs static. In TypeScript, when you store a `Renderer[]` and call `.render()` on each item, the JavaScript engine looks up the right method at runtime; every method call is **dynamic dispatch**. Rust gives you that same capability, but it makes it *opt-in*: you ask for it explicitly with the `dyn` keyword. A value typed as `dyn Trait` is a **trait object**, and this file is about how trait objects work, when to reach for them, and what they cost. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **trait object** lets you store and call values of *different concrete types* through a single shared trait, deciding which method to run at runtime: Rust’s **dynamic dispatch**. You write it as `&dyn Trait` (a borrowed trait object) or `Box<dyn Trait>` (an owned, heap-allocated one). This is the escape hatch from Rust’s default **static dispatch** (monomorphized generics, covered in [Generic Functions](/09-generics-traits/00-generic-functions/)): generics give you one specialized copy per type and zero runtime lookup, while `dyn` gives you one shared code path and a runtime vtable lookup. Not every trait can become a trait object: it must be **dyn-compatible** (historically called “object-safe”), and we will see exactly why. > **Note:** This page is about *dynamic dispatch* and `dyn Trait`. Defining traits is in [Traits](/09-generics-traits/03-traits/); constraining generics for static dispatch is in [Trait Bounds](/09-generics-traits/05-trait-bounds/); the `impl Trait` shorthand (a different feature entirely) is in [`impl Trait`](/09-generics-traits/07-impl-trait/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) A common UI scenario: you have several widget types, each knows how to render itself, and you keep them in one array and render them in a loop. Every TypeScript developer has written something like this. ```typescript 1 // TypeScript - a shared interface, several classes, one heterogeneous array 2 interface Renderer { 3 render(): string; 4 } 5 6 class Button implements Renderer { 7 constructor(public label: string) {} 8 render(): string { 9 return `<button>${this.label}</button>`; 10 } 11 } 12 13 class Checkbox implements Renderer { 14 constructor(public checked: boolean) {} 15 render(): string { 16 const mark = this.checked ? "x" : " "; 17 return `[${mark}] checkbox`; 18 } 19 } 20 21 // One array holds DIFFERENT concrete types behind the Renderer interface. 22 function renderAll(widgets: Renderer[]): void { 23 for (const widget of widgets) { 24 console.log(widget.render()); 25 } 26 } 27 28 const widgets: Renderer[] = [ 29 new Button("Save"), 30 new Checkbox(true), 31 new Button("Cancel"), 32 ]; 33 34 renderAll(widgets); ``` **Output (Node v22):** ```text 1 <button>Save</button> 2 [x] checkbox 3 <button>Cancel</button> ``` **Key points:** * `Renderer[]` holds a mix of `Button` and `Checkbox`. JavaScript objects carry their own method table, so `widget.render()` resolves at runtime to whichever class the object actually is. * In JavaScript this is the *only* dispatch model — every method call is a runtime property lookup. There is no compile-time specialization to opt into or out of. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same scenario in Rust. The heterogeneous array becomes `Vec<Box<dyn Renderer>>`, and `widget.render()` performs dynamic dispatch through the trait object. ```rust 1 // Rust - a shared trait, several structs, one heterogeneous Vec of trait objects 2 trait Renderer { 3 fn render(&self) -> String; 4 } 5 6 struct Button { 7 label: String, 8 } 9 10 struct Checkbox { 11 checked: bool, 12 } 13 14 impl Renderer for Button { 15 fn render(&self) -> String { 16 format!("<button>{}</button>", self.label) 17 } 18 } 19 20 impl Renderer for Checkbox { 21 fn render(&self) -> String { 22 let mark = if self.checked { "x" } else { " " }; 23 format!("[{mark}] checkbox") 24 } 25 } 26 27 // Takes a slice of trait objects: different concrete types, one interface. 28 fn render_all(widgets: &[Box<dyn Renderer>]) { 29 for widget in widgets { 30 println!("{}", widget.render()); 31 } 32 } 33 34 fn main() { 35 let widgets: Vec<Box<dyn Renderer>> = vec![ 36 Box::new(Button { label: "Save".to_string() }), 37 Box::new(Checkbox { checked: true }), 38 Box::new(Button { label: "Cancel".to_string() }), 39 ]; 40 41 render_all(&widgets); 42 } ``` **Real output:** ```text 1 <button>Save</button> 2 [x] checkbox 3 <button>Cancel</button> ``` Same result as the TypeScript version. The difference is conceptual: `Vec<Box<dyn Renderer>>` is the one place we *asked* for runtime dispatch. A plain generic `Vec<T>` could only hold one concrete type; `Box<dyn Renderer>` is what lets `Button` and `Checkbox` live in the same vector. > **Note:** All examples here target the repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) and the 2024 edition; `cargo new` selects that edition automatically. `Box` is the heap-allocating smart pointer covered in [Section 10: Smart Pointers](/10-smart-pointers/). *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What `dyn Trait` actually is [Section titled “What dyn Trait actually is”](#what-dyn-trait-actually-is) `dyn Renderer` is an **unsized type**: on its own the compiler does not know how big it is, because at compile time it could be a `Button` (one field) or a `Checkbox` (a different field). You can never hold a bare `dyn Renderer` by value; you always access it **behind a pointer**: `&dyn Renderer`, `&mut dyn Renderer`, `Box<dyn Renderer>`, `Rc<dyn Renderer>`, and so on. That pointer is special: it is a **fat pointer**, two machine words wide instead of one. The first word points at the data (the actual `Button`); the second word points at a **vtable**, a small table of function pointers for that type’s trait methods. When you call `widget.render()`, Rust reads the function pointer out of the vtable and calls it. That indirection *is* dynamic dispatch. We can see the fat pointer with `std::mem::size_of`: ```rust 1 use std::mem::size_of; 2 3 trait Shape { 4 fn area(&self) -> f64; 5 } 6 7 struct Circle { 8 radius: f64, 9 } 10 11 struct Rect { 12 w: f64, 13 h: f64, 14 } 15 16 impl Shape for Circle { 17 fn area(&self) -> f64 { 18 std::f64::consts::PI * self.radius * self.radius 19 } 20 } 21 22 impl Shape for Rect { 23 fn area(&self) -> f64 { 24 self.w * self.h 25 } 26 } 27 28 fn main() { 29 // A normal reference is one word (8 bytes on a 64-bit target). 30 println!("size of &Circle: {}", size_of::<&Circle>()); 31 // A trait-object reference is TWO words: data ptr + vtable ptr. 32 println!("size of &dyn Shape: {}", size_of::<&dyn Shape>()); 33 println!("size of Box<Circle>: {}", size_of::<Box<Circle>>()); 34 println!("size of Box<dyn Shape>: {}", size_of::<Box<dyn Shape>>()); 35 } ``` **Real output:** ```text 1 size of &Circle: 8 2 size of &dyn Shape: 16 3 size of Box<Circle>: 8 4 size of Box<dyn Shape>: 16 ``` The trait-object pointers are 16 bytes (two 8-byte words); the concrete pointers are 8. That extra word is the vtable pointer. > **Tip:** TypeScript has no “fat pointer” because every JavaScript object already carries its prototype chain (its method table) with it. Rust separates data from behavior, so when it needs runtime dispatch it bolts on a vtable pointer just for the duration the value is viewed as `dyn Trait`. ### `&dyn Trait` versus `Box<dyn Trait>` [Section titled “\&dyn Trait versus Box\<dyn Trait>”](#dyn-trait-versus-boxdyn-trait) These are the two forms you will use constantly. The difference is **ownership**, exactly the same distinction as anywhere else in Rust (see [Section 05: Ownership](/05-ownership/)): ```rust 1 trait Speak { 2 fn speak(&self) -> String; 3 } 4 5 struct Dog; 6 struct Cat; 7 8 impl Speak for Dog { 9 fn speak(&self) -> String { 10 "woof".to_string() 11 } 12 } 13 14 impl Speak for Cat { 15 fn speak(&self) -> String { 16 "meow".to_string() 17 } 18 } 19 20 // Borrows a trait object: caller keeps ownership, no allocation. 21 fn announce(s: &dyn Speak) { 22 println!("{}", s.speak()); 23 } 24 25 fn main() { 26 let d = Dog; 27 let boxed: Box<dyn Speak> = Box::new(Cat); 28 29 // A `&Dog` coerces automatically to `&dyn Speak` (an "unsized coercion"). 30 announce(&d); 31 32 // A `Box<dyn Speak>` derefs to `&dyn Speak` for the borrow. 33 announce(&*boxed); 34 announce(boxed.as_ref()); 35 } ``` **Real output:** ```text 1 woof 2 meow 3 meow ``` * **`&dyn Trait`** borrows an existing value. No heap allocation, no ownership transfer. Reach for this when a function just needs to *use* a trait object passed in. A concrete `&Dog` coerces into `&dyn Speak` automatically. * **`Box<dyn Trait>`** owns the value on the heap. Reach for this when you need to *store* trait objects (in a `Vec`, in a struct field) or *return* one from a function: anywhere the value must outlive the current scope and you cannot tie it to a borrow. ### Calling a method dispatches through the vtable [Section titled “Calling a method dispatches through the vtable”](#calling-a-method-dispatches-through-the-vtable) When `s.speak()` runs on a `&dyn Speak`, the compiler does not know (and does not need to know) whether `s` is a `Dog` or a `Cat`. It loads the `speak` function pointer from the vtable attached to `s` and calls it. This is the same runtime model as a JavaScript method call, and the opposite of a generic `fn announce<T: Speak>(s: &T)`, where the compiler monomorphizes a separate `announce` for `Dog` and for `Cat`, each calling `speak` directly with no lookup. ### Static dispatch vs dynamic dispatch, side by side [Section titled “Static dispatch vs dynamic dispatch, side by side”](#static-dispatch-vs-dynamic-dispatch-side-by-side) Here is the same capability expressed both ways: ```rust 1 trait Shape { 2 fn area(&self) -> f64; 3 } 4 5 struct Circle { 6 radius: f64, 7 } 8 9 impl Shape for Circle { 10 fn area(&self) -> f64 { 11 std::f64::consts::PI * self.radius * self.radius 12 } 13 } 14 15 // STATIC dispatch: generic + trait bound. Monomorphized per type, inlinable, 16 // zero runtime lookup. (See trait-bounds.md and generic-functions.md.) 17 fn print_area_static<T: Shape>(shape: &T) { 18 println!("{:.2}", shape.area()); 19 } 20 21 // DYNAMIC dispatch: trait object. One code path, vtable lookup at call time. 22 fn print_area_dynamic(shape: &dyn Shape) { 23 println!("{:.2}", shape.area()); 24 } 25 26 fn main() { 27 let c = Circle { radius: 2.0 }; 28 print_area_static(&c); 29 print_area_dynamic(&c); 30 } ``` **Real output:** ```text 1 12.57 2 12.57 ``` Both print the same thing; the machine code differs. `print_area_static` gets a dedicated copy stamped out for `Circle` with `area` likely inlined. `print_area_dynamic` is compiled once and reads the function pointer from the vtable at runtime. The trade-off (code size and speed vs flexibility and binary footprint) is the heart of choosing between them, summarized in the next section. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / JavaScript | Rust | | -------------------------------- | ---------------------------------------- | -------------------------------------------- | | Default dispatch | Always dynamic (runtime property lookup) | **Static** (monomorphized generics) | | Opt into dynamic dispatch | N/A (it is the only model) | Explicit: `dyn Trait` | | Heterogeneous collection | `Renderer[]`, trivial | `Vec<Box<dyn Renderer>>`, requires `dyn` | | Method-table storage | On every object (prototype chain) | Separate vtable, referenced by a fat pointer | | Pointer width for the object | N/A (objects are references) | `&dyn`/`Box<dyn>` are **two** words (fat) | | Can every type be used this way? | Yes | Only **dyn-compatible** traits | | Runtime cost | Always a lookup | Lookup only when you choose `dyn` | | Inlining the method | Never (engine may JIT-optimize) | Yes for static dispatch; not across `dyn` | ### When to choose which [Section titled “When to choose which”](#when-to-choose-which) * **Reach for static dispatch (generics) by default.** It is zero-cost: no vtable, fully inlinable, the fastest option. Use it whenever the set of types is known at compile time and a function works with *one* type per call. * **Reach for `dyn Trait` when you genuinely need runtime variety in one place:** a heterogeneous collection (`Vec<Box<dyn Trait>>`), a plugin/handler list assembled at runtime, returning different concrete types from different branches of a function, or wanting to *avoid* monomorphization bloat: one shared function instead of dozens of stamped-out copies in the binary. > **Note:** The performance gap is usually small for typical code: a vtable call is one extra pointer indirection. Do not contort your design to avoid `dyn`; reach for it when it expresses your intent. But also do not default to it out of TypeScript habit, because Rust’s static dispatch is genuinely free. ### Dyn compatibility (formerly “object safety”) [Section titled “Dyn compatibility (formerly “object safety”)”](#dyn-compatibility-formerly-object-safety) Not every trait can become a `dyn Trait`. A trait is **dyn-compatible** only if the compiler can build a single vtable for it. The two rules you will hit most often: 1. **No method may return `Self`.** The whole point of a trait object is to erase the concrete type, so a method that promises to return “the same type as the receiver” cannot be expressed. 2. **No method may have its own generic type parameters.** A vtable has one slot per method, but a generic method like `fn store<T>(&mut self, item: T)` would need a different implementation per `T` — there is no single function pointer to store. (Other rules exist, for example the trait cannot require `Sized`, but these two cause the vast majority of real-world errors.) The terminology recently changed: the compiler and docs now say **“dyn compatible”** where older material says **“object safe.”** They mean the same thing. We will see the exact compiler errors in Common Pitfalls. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Trying to put different concrete types in one collection without `dyn` [Section titled “Pitfall 1: Trying to put different concrete types in one collection without dyn”](#pitfall-1-trying-to-put-different-concrete-types-in-one-collection-without-dyn) Coming from TypeScript, `[new Button(), new Checkbox()]` “just works,” so the instinct is to write the equivalent `Vec` directly. Rust infers the element type from the first element and then rejects the second. ```rust 1 trait Renderer { fn render(&self) -> String; } 2 struct Button { label: String } 3 struct Checkbox { checked: bool } 4 impl Renderer for Button { fn render(&self) -> String { self.label.clone() } } 5 impl Renderer for Checkbox { fn render(&self) -> String { format!("{}", self.checked) } } 6 7 fn main() { 8 // does not compile (error[E0308]: mismatched types) 9 let widgets = vec![ 10 Button { label: "Save".to_string() }, 11 Checkbox { checked: true }, 12 ]; 13 let _ = widgets; 14 } ``` Real compiler error: ```text 1 error[E0308]: mismatched types 2 --> src/main.rs:11:9 3 | 4 11 | Checkbox { checked: true }, 5 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ expected `Button`, found `Checkbox` ``` **Fix:** make the element type a trait object and box each element, annotating the `Vec`: ```rust 1 trait Renderer { 2 fn render(&self) -> String; 3 } 4 5 struct Button { 6 label: String, 7 } 8 9 struct Checkbox { 10 checked: bool, 11 } 12 13 impl Renderer for Button { 14 fn render(&self) -> String { 15 self.label.clone() 16 } 17 } 18 19 impl Renderer for Checkbox { 20 fn render(&self) -> String { 21 format!("{}", self.checked) 22 } 23 } 24 25 fn main() { 26 let widgets: Vec<Box<dyn Renderer>> = vec![ 27 Box::new(Button { label: "Save".to_string() }), 28 Box::new(Checkbox { checked: true }), 29 ]; 30 let _ = widgets; 31 } ``` ### Pitfall 2: Returning a bare `dyn Trait` by value [Section titled “Pitfall 2: Returning a bare dyn Trait by value”](#pitfall-2-returning-a-bare-dyn-trait-by-value) A `dyn Trait` is unsized, so you cannot return it directly: there is no known size to put on the stack. This trips up developers who want a “factory” returning different types from different branches. ```rust 1 trait Animal { fn speak(&self) -> String; } 2 struct Dog; 3 struct Cat; 4 impl Animal for Dog { fn speak(&self) -> String { "woof".into() } } 5 impl Animal for Cat { fn speak(&self) -> String { "meow".into() } } 6 7 // does not compile (error[E0746]: return type cannot be a trait object without pointer indirection) 8 fn make(loud: bool) -> dyn Animal { 9 if loud { Dog } else { Cat } 10 } 11 12 fn main() { 13 let _ = make(true); 14 } ``` Real compiler error (abridged): ```text 1 error[E0746]: return type cannot be a trait object without pointer indirection 2 --> src/main.rs:7:24 3 | 4 7 | fn make(loud: bool) -> dyn Animal { 5 | ^^^^^^^^^^ doesn't have a size known at compile-time 6 | 7 help: consider returning an `impl Trait` instead of a `dyn Trait` 8 | 9 7 - fn make(loud: bool) -> dyn Animal { 10 7 + fn make(loud: bool) -> impl Animal { 11 | 12 help: alternatively, box the return type, and wrap all of the returned values in `Box::new` 13 | 14 7 ~ fn make(loud: bool) -> Box<dyn Animal> { 15 8 ~ if loud { Box::new(Dog) } else { Box::new(Cat) } 16 | ``` **Fix:** box it. The compiler’s second suggestion is exactly right when the branches return *different* types: ```rust 1 trait Animal { 2 fn speak(&self) -> String; 3 } 4 5 struct Dog; 6 struct Cat; 7 8 impl Animal for Dog { 9 fn speak(&self) -> String { 10 "woof".into() 11 } 12 } 13 14 impl Animal for Cat { 15 fn speak(&self) -> String { 16 "meow".into() 17 } 18 } 19 20 fn make(loud: bool) -> Box<dyn Animal> { 21 if loud { Box::new(Dog) } else { Box::new(Cat) } 22 } 23 24 fn main() { 25 println!("{}", make(true).speak()); 26 println!("{}", make(false).speak()); 27 } ``` This prints `woof` then `meow`. (The compiler’s *first* suggestion, `impl Animal`, only works when *every* branch returns the **same** concrete type; that is the static-dispatch alternative covered in [`impl Trait`](/09-generics-traits/07-impl-trait/). Here the branches differ, so `Box<dyn Animal>` is the right call.) ### Pitfall 3: A method that returns `Self` breaks dyn compatibility [Section titled “Pitfall 3: A method that returns Self breaks dyn compatibility”](#pitfall-3-a-method-that-returns-self-breaks-dyn-compatibility) You define a sensible-looking trait, then try to use it as `dyn` and the compiler refuses, not at the trait definition, but at the point you ask for the trait object. ```rust 1 // does not compile (error[E0038]: the trait `Cloneable` is not dyn compatible) 2 trait Cloneable { 3 fn duplicate(&self) -> Self; 4 } 5 6 fn main() { 7 let _x: &dyn Cloneable = todo!(); 8 } ``` Real compiler error (abridged): ```text 1 error[E0038]: the trait `Cloneable` is not dyn compatible 2 --> src/main.rs:7:18 3 | 4 7 | let _x: &dyn Cloneable = todo!(); 5 | ^^^^^^^^^ `Cloneable` is not dyn compatible 6 | 7 note: for a trait to be dyn compatible it needs to allow building a vtable 8 ... 9 3 | fn duplicate(&self) -> Self; 10 | ^^^^ ...because method `duplicate` references the `Self` type in its return type 11 = help: consider moving `duplicate` to another trait ``` **Why:** a trait object has erased the concrete type, so “return `Self`” has no meaning. **Fix:** if you only need `duplicate` on the concrete type, gate it behind `where Self: Sized` so it is excluded from the vtable but still callable on the real type (shown in Best Practices). If you need cloning *through* the trait object, the standard pattern is a `fn clone_box(&self) -> Box<dyn Trait>` method that boxes a copy. ### Pitfall 4: A generic method breaks dyn compatibility [Section titled “Pitfall 4: A generic method breaks dyn compatibility”](#pitfall-4-a-generic-method-breaks-dyn-compatibility) The other common dyn-compatibility violation: a trait method with its own type parameter. ```rust 1 // does not compile (error[E0038]: the trait `Container` is not dyn compatible) 2 trait Container { 3 fn store<T>(&mut self, item: T); 4 } 5 6 fn main() { 7 let _x: Box<dyn Container> = todo!(); 8 } ``` Real compiler error (abridged): ```text 1 error[E0038]: the trait `Container` is not dyn compatible 2 --> src/main.rs:7:21 3 | 4 7 | let _x: Box<dyn Container> = todo!(); 5 | ^^^^^^^^^ `Container` is not dyn compatible 6 ... 7 3 | fn store<T>(&mut self, item: T); 8 | ^^^^^ ...because method `store` has generic type parameters 9 = help: consider moving `store` to another trait ``` **Why:** the vtable has exactly one slot per method, but a generic method would need a distinct compiled function for every `T` it is ever called with: there is no single pointer to put in the slot. **Fix:** if the type set is small and known, replace the generic parameter with a concrete type or an enum; otherwise keep that method out of the trait object (again, `where Self: Sized`). ### Pitfall 5: Reaching for `dyn` when a generic would do [Section titled “Pitfall 5: Reaching for dyn when a generic would do”](#pitfall-5-reaching-for-dyn-when-a-generic-would-do) The mirror image of the TypeScript instinct: because dynamic dispatch is *all* you ever had in JavaScript, it is tempting to make every trait-using function take `&dyn Trait`. If a function only ever handles one concrete type per call and you do not need a heterogeneous collection, a generic is simpler *and* faster: ```rust 1 trait Shape { 2 fn area(&self) -> f64; 3 } 4 5 // Prefer this (static dispatch, zero-cost) ... 6 fn describe_generic<T: Shape>(shape: &T) -> f64 { 7 shape.area() 8 } 9 10 // ... over this, unless you specifically need runtime variety. 11 fn describe_dyn(shape: &dyn Shape) -> f64 { 12 shape.area() 13 } 14 15 struct Sq { 16 s: f64, 17 } 18 19 impl Shape for Sq { 20 fn area(&self) -> f64 { 21 self.s * self.s 22 } 23 } 24 25 fn main() { 26 let q = Sq { s: 2.0 }; 27 println!("{} {}", describe_generic(&q), describe_dyn(&q)); 28 } ``` Both compile and behave identically; the generic version is the idiomatic default. Save `dyn` for where its flexibility earns its keep. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Default to generics; reach for `dyn` deliberately [Section titled “Default to generics; reach for dyn deliberately”](#default-to-generics-reach-for-dyn-deliberately) Use a generic with a trait bound (`fn f<T: Trait>(x: &T)`) unless you have a concrete reason for dynamic dispatch: a mixed-type collection, a runtime-chosen return type, plugin registration, or a desire to shrink the binary by sharing one code path. This is the single most important habit for a TypeScript developer to build, because the JavaScript world only ever offered dynamic dispatch. ### Box trait objects to own them; borrow them to use them [Section titled “Box trait objects to own them; borrow them to use them”](#box-trait-objects-to-own-them-borrow-them-to-use-them) Store and return owned trait objects as `Box<dyn Trait>` (or `Rc<dyn Trait>` / `Arc<dyn Trait>` when you need shared ownership — see [Section 10: Smart Pointers](/10-smart-pointers/)). Accept `&dyn Trait` in functions that only *use* the value, so callers are not forced to allocate. ### Keep traits dyn-compatible when you intend to use them as objects [Section titled “Keep traits dyn-compatible when you intend to use them as objects”](#keep-traits-dyn-compatible-when-you-intend-to-use-them-as-objects) If a trait is meant to be used behind `dyn`, avoid `Self`-returning methods and generic methods in its core surface. When you *do* need such a method only on concrete types, fence it off with `where Self: Sized` so the rest of the trait stays usable as an object: ```rust 1 trait Greeter { 2 fn greet(&self) -> String; 3 4 // Excluded from the vtable, so the trait remains dyn-compatible. 5 fn duplicate(&self) -> Self 6 where 7 Self: Sized; 8 } 9 10 struct Hello; 11 12 impl Greeter for Hello { 13 fn greet(&self) -> String { 14 "hello".to_string() 15 } 16 fn duplicate(&self) -> Self { 17 Hello 18 } 19 } 20 21 fn main() { 22 // Usable as a trait object because `duplicate` is gated behind `Self: Sized`. 23 let g: Box<dyn Greeter> = Box::new(Hello); 24 println!("{}", g.greet()); 25 26 // `duplicate` is callable only on the concrete type, never through `dyn`. 27 let concrete = Hello; 28 let _copy = concrete.duplicate(); 29 println!("duplicated ok"); 30 } ``` **Real output:** ```text 1 hello 2 duplicated ok ``` ### Name the type explicitly when collecting trait objects [Section titled “Name the type explicitly when collecting trait objects”](#name-the-type-explicitly-when-collecting-trait-objects) Write `let v: Vec<Box<dyn Trait>> = vec![...]`. The annotation tells the compiler to coerce each `Box::new(Concrete)` into the trait-object type rather than inferring a single concrete element type (which causes Pitfall 1). ### Prefer enums over trait objects for a small, closed set of types [Section titled “Prefer enums over trait objects for a small, closed set of types”](#prefer-enums-over-trait-objects-for-a-small-closed-set-of-types) If the variety is *closed* — you know all the variants up front and they will not be extended by other crates — a plain `enum` with a `match` is often clearer and faster than `dyn`, with no allocation and exhaustiveness checking. Use trait objects when the set is *open* (third parties can add types) or genuinely large. Enums are covered in [Section 06: Data Structures](/06-data-structures/) and [Generic Enums](/09-generics-traits/02-generic-enums/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A middleware pipeline, the kind you would find behind an HTTP server or a CLI request handler. Each middleware is its own type implementing a shared `Middleware` trait; the pipeline stores them as a heterogeneous, runtime-assembled list of owned trait objects and runs them in order. This is a textbook use of dynamic dispatch: the set of stages is decided at runtime and they are different types living in one `Vec`. ```rust 1 #[derive(Debug)] 2 struct Request { 3 path: String, 4 user: Option<String>, 5 log: Vec<String>, 6 } 7 8 // The shared contract. `&self` and `&mut` receivers are fine for dyn compatibility; 9 // there are no `Self` returns or generic methods, so this trait is dyn-compatible. 10 trait Middleware { 11 fn name(&self) -> &str; 12 fn handle(&self, req: &mut Request); 13 } 14 15 struct Logger; 16 struct Auth { 17 required: bool, 18 } 19 struct RateLimit { 20 max_per_min: u32, 21 } 22 23 impl Middleware for Logger { 24 fn name(&self) -> &str { 25 "logger" 26 } 27 fn handle(&self, req: &mut Request) { 28 req.log.push(format!("[logger] {}", req.path)); 29 } 30 } 31 32 impl Middleware for Auth { 33 fn name(&self) -> &str { 34 "auth" 35 } 36 fn handle(&self, req: &mut Request) { 37 if self.required && req.user.is_none() { 38 req.log.push("[auth] anonymous request flagged".to_string()); 39 } else { 40 req.log.push("[auth] ok".to_string()); 41 } 42 } 43 } 44 45 impl Middleware for RateLimit { 46 fn name(&self) -> &str { 47 "rate-limit" 48 } 49 fn handle(&self, req: &mut Request) { 50 req.log 51 .push(format!("[rate-limit] budget {}/min", self.max_per_min)); 52 } 53 } 54 55 /// Holds a heterogeneous list of middleware as owned trait objects. 56 struct Pipeline { 57 stages: Vec<Box<dyn Middleware>>, 58 } 59 60 impl Pipeline { 61 fn new() -> Self { 62 Pipeline { stages: Vec::new() } 63 } 64 65 // Accepts ANY concrete middleware type, boxed as a trait object. 66 fn add(mut self, stage: Box<dyn Middleware>) -> Self { 67 self.stages.push(stage); 68 self 69 } 70 71 fn run(&self, req: &mut Request) { 72 for stage in &self.stages { 73 println!("running {}", stage.name()); // dynamic dispatch 74 stage.handle(req); // dynamic dispatch 75 } 76 } 77 } 78 79 fn main() { 80 let pipeline = Pipeline::new() 81 .add(Box::new(Logger)) 82 .add(Box::new(Auth { required: true })) 83 .add(Box::new(RateLimit { max_per_min: 60 })); 84 85 let mut req = Request { 86 path: "/dashboard".to_string(), 87 user: None, 88 log: Vec::new(), 89 }; 90 91 pipeline.run(&mut req); 92 93 println!("--- request log ---"); 94 for line in &req.log { 95 println!("{line}"); 96 } 97 } ``` **Real output:** ```text 1 running logger 2 running auth 3 running rate-limit 4 --- request log --- 5 [logger] /dashboard 6 [auth] anonymous request flagged 7 [rate-limit] budget 60/min ``` Two things make this a natural fit for trait objects. First, the pipeline is *assembled at runtime* from different concrete types, exactly what `Vec<Box<dyn Middleware>>` is for; a generic `Vec<T>` could hold only one stage type. Second, the design is open: adding a new middleware (say, `Compression`) is purely additive. Define the struct, write one `impl Middleware for Compression`, `.add(Box::new(Compression))`, and `Pipeline` needs no changes. The cost is one vtable lookup per `name()`/`handle()` call, which is negligible next to the work a real middleware does. > **Tip:** If your pipeline stages were a fixed, closed set known at compile time, an `enum Stage { Logger, Auth(Auth), RateLimit(RateLimit) }` with a `match` would avoid the allocation and the dispatch. The `dyn` approach earns its place precisely because new stage types can come from anywhere. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Rust Book — Using Trait Objects That Allow for Values of Different Types](https://doc.rust-lang.org/book/ch18-02-trait-objects.html) * [The Rust Reference — Trait objects](https://doc.rust-lang.org/reference/types/trait-object.html) * [The Rust Reference — `dyn` compatibility](https://doc.rust-lang.org/reference/items/traits.html#dyn-compatibility) * [Rust by Example — Returning Traits with `dyn`](https://doc.rust-lang.org/rust-by-example/trait/dyn.html) ### Related topics in this guide [Section titled “Related topics in this guide”](#related-topics-in-this-guide) * [Section 09 overview](/09-generics-traits/): the full map of generics and traits * [Traits](/09-generics-traits/03-traits/): defining and implementing the traits you turn into objects * [Trait Bounds](/09-generics-traits/05-trait-bounds/): `<T: Trait>` static dispatch, the default alternative to `dyn` * [Generic Functions](/09-generics-traits/00-generic-functions/): monomorphization vs TypeScript’s type erasure * [`impl Trait`](/09-generics-traits/07-impl-trait/) — `impl Trait` returns: static dispatch when every branch shares one type * [Trait Methods](/09-generics-traits/04-trait-methods/): required vs provided methods (provided methods appear in vtables too) * [Marker Traits](/09-generics-traits/11-marker-traits/): `Sized` and why `dyn Trait` is unsized * [Generic Enums](/09-generics-traits/02-generic-enums/): enums as the closed-set alternative to trait objects * [Section 05: Ownership](/05-ownership/): what `&dyn` (borrow) vs `Box<dyn>` (owned) means * [Section 06: Data Structures](/06-data-structures/): enums, the closed-set alternative * [Section 10: Smart Pointers](/10-smart-pointers/): `Box<dyn Trait>`, plus `Rc`/`Arc<dyn Trait>` for shared ownership * Foundations: [Getting Started](/01-getting-started/) and [Basics](/02-basics/) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A heterogeneous drawing list [Section titled “Exercise 1: A heterogeneous drawing list”](#exercise-1-a-heterogeneous-drawing-list) **Difficulty:** Easy **Objective:** Build and iterate a `Vec` of trait objects. **Instructions:** Define a trait `Drawable` with one required method `draw(&self) -> String`. Implement it for two unit structs, `Line` (returns `"---"`) and `Dot` (returns `"."`). Write a function `draw_all(items: &[Box<dyn Drawable>])` that prints each item’s `draw()` output. In `main`, build a `Vec<Box<dyn Drawable>>` containing a `Line`, a `Dot`, and another `Line`, then call `draw_all`. ```rust 1 trait Drawable { 2 // TODO: draw(&self) -> String 3 } 4 5 struct Line; 6 struct Dot; 7 8 // TODO: impl Drawable for Line and Dot 9 10 fn draw_all(items: &[Box<dyn Drawable>]) { 11 // TODO: print each item's draw() output 12 } 13 14 fn main() { 15 // TODO: build a Vec<Box<dyn Drawable>> and call draw_all 16 } ``` Solution ```rust 1 trait Drawable { 2 fn draw(&self) -> String; 3 } 4 5 struct Line; 6 struct Dot; 7 8 impl Drawable for Line { 9 fn draw(&self) -> String { 10 "---".to_string() 11 } 12 } 13 14 impl Drawable for Dot { 15 fn draw(&self) -> String { 16 ".".to_string() 17 } 18 } 19 20 fn draw_all(items: &[Box<dyn Drawable>]) { 21 for item in items { 22 println!("{}", item.draw()); 23 } 24 } 25 26 fn main() { 27 let items: Vec<Box<dyn Drawable>> = vec![Box::new(Line), Box::new(Dot), Box::new(Line)]; 28 draw_all(&items); 29 } ``` **Output:** ```text 1 --- 2 . 3 --- ``` The `Vec<Box<dyn Drawable>>` annotation is what lets `Line` and `Dot`, two different types, share one vector; each `Box::new(...)` coerces into the trait-object element type. ### Exercise 2: A runtime-chosen factory returning `Box<dyn Trait>` [Section titled “Exercise 2: A runtime-chosen factory returning Box\<dyn Trait>”](#exercise-2-a-runtime-chosen-factory-returning-boxdyn-trait) **Difficulty:** Medium **Objective:** Return different concrete types from one function via a boxed trait object, and accept a trait object by borrow. **Instructions:** Define a trait `Formatter` with `format(&self, value: f64) -> String`. Implement it for `Currency { symbol: String }` (e.g. `$19.50`, two decimals) and a unit struct `Percent` (e.g. `7.5%`, value times 100, one decimal). Write `formatter_for(kind: &str) -> Box<dyn Formatter>` returning a `Currency { symbol: "$" }` for `"usd"`, `Currency { symbol: "EUR " }` for `"eur"`, and `Percent` for anything else. Write `show(formatter: &dyn Formatter, value: f64)` that prints `formatter.format(value)`. In `main`, build a USD formatter and a fallback formatter and show a value with each. ```rust 1 trait Formatter { 2 // TODO: format(&self, value: f64) -> String 3 } 4 5 struct Currency { symbol: String } 6 struct Percent; 7 8 // TODO: impl Formatter for Currency and Percent 9 10 fn formatter_for(kind: &str) -> Box<dyn Formatter> { 11 // TODO: return the right boxed formatter 12 } 13 14 fn show(formatter: &dyn Formatter, value: f64) { 15 // TODO: print formatter.format(value) 16 } 17 18 fn main() { 19 // TODO: build formatters via formatter_for and call show 20 } ``` Solution ```rust 1 trait Formatter { 2 fn format(&self, value: f64) -> String; 3 } 4 5 struct Currency { 6 symbol: String, 7 } 8 9 struct Percent; 10 11 impl Formatter for Currency { 12 fn format(&self, value: f64) -> String { 13 format!("{}{:.2}", self.symbol, value) 14 } 15 } 16 17 impl Formatter for Percent { 18 fn format(&self, value: f64) -> String { 19 format!("{:.1}%", value * 100.0) 20 } 21 } 22 23 fn formatter_for(kind: &str) -> Box<dyn Formatter> { 24 match kind { 25 "usd" => Box::new(Currency { symbol: "$".to_string() }), 26 "eur" => Box::new(Currency { symbol: "EUR ".to_string() }), 27 _ => Box::new(Percent), 28 } 29 } 30 31 fn show(formatter: &dyn Formatter, value: f64) { 32 println!("{}", formatter.format(value)); 33 } 34 35 fn main() { 36 let usd = formatter_for("usd"); 37 let pct = formatter_for("rate"); // falls through to Percent 38 39 // `&Box<dyn Formatter>` derefs to `&dyn Formatter`; `as_ref()` is explicit. 40 show(usd.as_ref(), 19.5); 41 show(pct.as_ref(), 0.075); 42 } ``` **Output:** ```text 1 $19.50 2 7.5% ``` `formatter_for` returns `Box<dyn Formatter>` because the branches produce different concrete types; `impl Formatter` would not work here. `show` borrows the trait object as `&dyn Formatter`, so it never takes ownership or allocates. ### Exercise 3: A mutable event bus [Section titled “Exercise 3: A mutable event bus”](#exercise-3-a-mutable-event-bus) **Difficulty:** Hard **Objective:** Store stateful trait objects, call them through `&mut`, and confirm a `&mut self` method keeps the trait dyn-compatible. **Instructions:** Define a trait `Handler` with `on_event(&mut self, event: &str) -> String`. Implement it for `Counter { count: u32 }` — it increments `count` and returns `"counter saw '<event>' (total <n>)"` — and a unit struct `Echo` returning `"echo: <event>"`. Build a `Bus` struct holding `Vec<Box<dyn Handler>>` with `new()`, `register(&mut self, handler: Box<dyn Handler>)`, and `dispatch(&mut self, event: &str)` (which calls `on_event` on every handler and prints the result; you will need `iter_mut()` because `on_event` takes `&mut self`). In `main`, register a `Counter` and an `Echo`, then dispatch `"login"` and `"logout"`. ```rust 1 trait Handler { 2 // TODO: on_event(&mut self, event: &str) -> String 3 } 4 5 struct Counter { count: u32 } 6 struct Echo; 7 8 // TODO: impl Handler for Counter and Echo 9 10 struct Bus { 11 handlers: Vec<Box<dyn Handler>>, 12 } 13 14 impl Bus { 15 // TODO: new, register, dispatch 16 } 17 18 fn main() { 19 // TODO: register a Counter and an Echo, dispatch two events 20 } ``` Solution ```rust 1 trait Handler { 2 fn on_event(&mut self, event: &str) -> String; 3 } 4 5 struct Counter { 6 count: u32, 7 } 8 9 struct Echo; 10 11 impl Handler for Counter { 12 fn on_event(&mut self, event: &str) -> String { 13 self.count += 1; 14 format!("counter saw '{event}' (total {})", self.count) 15 } 16 } 17 18 impl Handler for Echo { 19 fn on_event(&mut self, event: &str) -> String { 20 format!("echo: {event}") 21 } 22 } 23 24 struct Bus { 25 handlers: Vec<Box<dyn Handler>>, 26 } 27 28 impl Bus { 29 fn new() -> Self { 30 Bus { handlers: Vec::new() } 31 } 32 33 fn register(&mut self, handler: Box<dyn Handler>) { 34 self.handlers.push(handler); 35 } 36 37 fn dispatch(&mut self, event: &str) { 38 // iter_mut() yields `&mut Box<dyn Handler>`, so `on_event(&mut self)` is callable. 39 for handler in self.handlers.iter_mut() { 40 println!("{}", handler.on_event(event)); 41 } 42 } 43 } 44 45 fn main() { 46 let mut bus = Bus::new(); 47 bus.register(Box::new(Counter { count: 0 })); 48 bus.register(Box::new(Echo)); 49 50 bus.dispatch("login"); 51 bus.dispatch("logout"); 52 } ``` **Output:** ```text 1 counter saw 'login' (total 1) 2 echo: login 3 counter saw 'logout' (total 2) 4 echo: logout ``` The key detail: `on_event` takes `&mut self`, which is perfectly dyn-compatible; only `Self`-returning and generic methods break dyn compatibility. Iterating with `iter_mut()` (not `iter()`) gives the mutable access each `on_event` call needs, and the `Counter`’s state persists across dispatches because the `Box<dyn Handler>` owns it inside the `Vec`. # `impl Trait`: Anonymous Types in Arguments and Returns > impl Trait names a type by capability in Rust function arguments and returns, the static-dispatch counterpart to a TypeScript interface. `impl Trait` is Rust’s shorthand for “some type that satisfies this trait, but I am not going to name it.” You meet it in two places, function arguments and function return types, and although the syntax looks identical, the two positions mean genuinely different things. This file untangles both, plus the newer return-position `impl Trait` in traits (RPITIT). *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) `impl Trait` lets you write a function signature in terms of a **capability** instead of a concrete type. In **argument position** it is concise sugar for a generic with a trait bound; in **return position** (often abbreviated **RPIT**, “return-position `impl Trait`”) it hands the caller a value of a single hidden concrete type, perfect for returning closures and iterator chains whose real type names are unwriteable. For a TypeScript developer this feels a little like annotating a parameter or return as an `interface`, but the runtime story is the opposite: there is no boxing, no vtable, and no type erasure. > **Note:** This page assumes you have met traits ([Traits](/09-generics-traits/03-traits/)) and trait bounds ([Trait Bounds](/09-generics-traits/05-trait-bounds/)). The bound `T: Trait` and the shorthand `impl Trait` are two spellings of overlapping ideas; here we focus specifically on the `impl Trait` spelling and when each position is the right tool. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Here is a familiar pattern: a function constrained to “anything that can summarize itself,” and a factory that returns such a thing. In TypeScript the natural way to express both is with an `interface`. ```typescript 1 // TypeScript - constrain a parameter and a return by an interface 2 interface Summary { 3 summarize(): string; 4 } 5 6 class Article implements Summary { 7 constructor( 8 public title: string, 9 public author: string, 10 ) {} 11 12 summarize(): string { 13 return `${this.title} by ${this.author}`; 14 } 15 } 16 17 // Parameter typed by the interface: accepts any conforming object. 18 function announce(item: Summary): void { 19 console.log(`Breaking! ${item.summarize()}`); 20 } 21 22 // Return typed by the interface: the caller sees only `Summary`, 23 // even though we hand back a concrete `Article`. 24 function defaultSummary(): Summary { 25 return new Article("Rust 1.96 released", "The Rust Team"); 26 } 27 28 announce(new Article("Rust 1.96 released", "The Rust Team")); 29 const s = defaultSummary(); 30 console.log(s.summarize()); ``` **Real output (Node v22, run with `tsx`):** ```text 1 Breaking! Rust 1.96 released by The Rust Team 2 Rust 1.96 released by The Rust Team ``` **Key points to carry into the Rust version:** * The parameter `item: Summary` accepts *any* object whose shape matches (TypeScript is structural). At runtime the object is the same heap object it always was; interface annotations are erased. * The return type `Summary` **widens** the value: callers may only call interface methods, even though an `Article` came back. TypeScript happily returns different concrete classes from different branches of one such function, because at runtime they are all just objects. Both of those behaviors differ from Rust in instructive ways, as we will see. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 trait Summary { 2 fn summarize(&self) -> String; 3 } 4 5 struct Article { 6 title: String, 7 author: String, 8 } 9 10 struct Tweet { 11 username: String, 12 content: String, 13 } 14 15 impl Summary for Article { 16 fn summarize(&self) -> String { 17 format!("{} by {}", self.title, self.author) 18 } 19 } 20 21 impl Summary for Tweet { 22 fn summarize(&self) -> String { 23 format!("@{}: {}", self.username, self.content) 24 } 25 } 26 27 // `impl Trait` in ARGUMENT position: accept any single type that is `Summary`. 28 fn announce(item: &impl Summary) { 29 println!("Breaking! {}", item.summarize()); 30 } 31 32 // `impl Trait` in RETURN position (RPIT): return *some* `Summary`, 33 // without naming the concrete type at the call site. 34 fn default_tweet() -> impl Summary { 35 Tweet { 36 username: String::from("rustlang"), 37 content: String::from("We just shipped a new release!"), 38 } 39 } 40 41 fn main() { 42 let article = Article { 43 title: String::from("Rust 1.96 released"), 44 author: String::from("The Rust Team"), 45 }; 46 announce(&article); 47 48 let t = default_tweet(); 49 announce(&t); 50 println!("{}", t.summarize()); 51 } ``` **Real output:** ```text 1 Breaking! Rust 1.96 released by The Rust Team 2 Breaking! @rustlang: We just shipped a new release! 3 @rustlang: We just shipped a new release! ``` > **Note:** The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the **2024 edition**. Create projects with `cargo new` (it auto-selects the newest edition) and never pin an older one. Everything in this file is verified on a 2024-edition project. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Argument position: `&impl Summary` is sugar for a generic [Section titled “Argument position: \&impl Summary is sugar for a generic”](#argument-position-impl-summary-is-sugar-for-a-generic) ```rust 1 fn announce(item: &impl Summary) { 2 println!("Breaking! {}", item.summarize()); 3 } ``` Read `&impl Summary` as “a borrow of some type that implements `Summary`.” This is **exactly equivalent** to the generic form: ```rust 1 fn announce<T: Summary>(item: &T) { 2 println!("Breaking! {}", item.summarize()); 3 } ``` The compiler treats both identically: each call site is **monomorphized** into a specialized copy of `announce` for the concrete type passed in. (Monomorphization — Rust stamping out one machine-code copy per concrete type — is the topic of [Generic Functions](/09-generics-traits/00-generic-functions/), and it is the deep contrast with TypeScript’s erased generics.) The `impl Trait` form is purely a convenience: it saves you from inventing a name like `T` when you only mention the type once. It is sometimes called “anonymous generic” for that reason. There is one capability you give up by using the anonymous form, which becomes the source of a common pitfall: you cannot **name** the type, so two parameters written `impl Summary` are two *independent* types, and you cannot turbofish them. More on that in [Common Pitfalls](#common-pitfalls). ### Return position (RPIT): one hidden concrete type [Section titled “Return position (RPIT): one hidden concrete type”](#return-position-rpit-one-hidden-concrete-type) ```rust 1 fn default_tweet() -> impl Summary { 2 Tweet { /* ... */ } 3 } ``` Return position is where `impl Trait` earns its keep, and it is **not** the same as the argument case. Here `impl Summary` means: “this function returns a value of *one specific, compiler-determined* concrete type, and all you, the caller, may assume is that it implements `Summary`.” The concrete type (`Tweet`) is fixed at compile time and inferred from the function body; it is just hidden from the signature. This is the central contrast with the TypeScript return-by-interface version: * In TypeScript, `function defaultSummary(): Summary` may return an `Article` from one branch and a `Tweet` from another; at runtime they are interchangeable objects. * In Rust, `-> impl Summary` locks in **a single** concrete type for the whole function. Every `return` path must produce that same type, or the program does not compile (see Pitfall 1). Why hide the type at all? Because some real return types are effectively impossible to write by hand: closures have unnameable anonymous types, and iterator adapters produce deeply nested generic types like `Map<Filter<Range<u32>, {closure}>, {closure}>`. `impl Trait` lets you describe such a value by what it *does* rather than what it *is*: ```rust 1 fn make_adder(n: i32) -> impl Fn(i32) -> i32 { 2 move |x| x + n 3 } 4 5 fn even_squares(limit: u32) -> impl Iterator<Item = u32> { 6 (0..limit).filter(|x| x % 2 == 0).map(|x| x * x) 7 } 8 9 fn main() { 10 let add5 = make_adder(5); 11 println!("{}", add5(10)); 12 13 let squares: Vec<u32> = even_squares(6).collect(); 14 println!("{:?}", squares); 15 } ``` **Real output:** ```text 1 15 2 [0, 4, 16] ``` A closure has a unique, compiler-generated type with no name you could type into a signature; `impl Fn(i32) -> i32` is how you return one. The iterator chain’s true type is `Map<Filter<Range<u32>, ...>, ...>`, and you would not want to maintain that by hand. `impl Iterator<Item = u32>` says everything the caller needs. ### Static dispatch, no boxing [Section titled “Static dispatch, no boxing”](#static-dispatch-no-boxing) Both positions produce **static dispatch**: the call goes directly to the right machine code with no runtime lookup, and the returned value lives inline (on the stack, or moved into wherever the caller puts it) with **no heap allocation and no vtable**. This is the opposite of the TypeScript story, where every interface-typed value is a heap object accessed through dynamic property lookup. When you *do* want runtime polymorphism (a heterogeneous collection, or different return types per branch), you reach for `Box<dyn Trait>` instead, which is covered in [Trait Objects and Dynamic Dispatch](/09-generics-traits/06-trait-objects/) and previewed in the next section. ### A brief note on RPITIT (`impl Trait` in trait methods) [Section titled “A brief note on RPITIT (impl Trait in trait methods)”](#a-brief-note-on-rpitit-impl-trait-in-trait-methods) Until recently you could not write `-> impl Trait` as the return type of a method *inside a trait definition*. Since **Rust 1.75** you can; the feature is called **return-position `impl Trait` in traits**, or **RPITIT**: ```rust 1 trait Container { 2 // The method returns "some iterator of i32" without naming the type. 3 fn items(&self) -> impl Iterator<Item = i32>; 4 } 5 6 struct Evens { 7 upto: i32, 8 } 9 10 impl Container for Evens { 11 fn items(&self) -> impl Iterator<Item = i32> { 12 (0..self.upto).filter(|n| n % 2 == 0) 13 } 14 } 15 16 fn main() { 17 let e = Evens { upto: 8 }; 18 let collected: Vec<i32> = e.items().collect(); 19 println!("{:?}", collected); 20 } ``` **Real output:** ```text 1 [0, 2, 4, 6] ``` Before RPITIT, this pattern required either an associated type (`type Iter: Iterator<Item = i32>;`, which forces every implementor to name a concrete iterator type) or the `async-trait`-style boxing dance. RPITIT removes that boilerplate. The one big caveat: a trait that uses RPITIT is **not `dyn`-compatible** (you cannot make a `Box<dyn Container>` from it), because the hidden return type would vary per implementor and so the compiler cannot build a single vtable. We capture that exact error in the pitfalls. > **Note:** RPITIT is closely related to native `async fn` in traits (also stable since 1.75): an `async fn` in a trait desugars to a method returning `impl Future`. That is why the modern advice is “you do not need the `async-trait` crate just to write an async method in a trait — only reach for it when you need `dyn`.” Async traits are covered in [Section 11: Async](/11-async/). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript | Rust `impl Trait` | | ----------------------------------------------- | -------------------------------- | --------------------------------------------------- | | Parameter by capability | `item: SomeInterface` | `item: impl Trait` (sugar for `<T: Trait>`) | | Return by capability | `(): SomeInterface` (widening) | `-> impl Trait` (one hidden concrete type) | | Different concrete types per branch in a return | Allowed (all are objects) | **Not** allowed for one `-> impl Trait` | | Dispatch | Always dynamic (property lookup) | Static — direct call, no vtable | | Allocation | Heap object | Inline value, no heap, no boxing | | Naming the type | The interface *is* the type | The type is anonymous/hidden | | In a struct field | Fine (`field: SomeInterface`) | **Not allowed** (use a generic param or `Box<dyn>`) | ### “Some type” (argument) versus “one hidden type” (return) [Section titled ““Some type” (argument) versus “one hidden type” (return)”](#some-type-argument-versus-one-hidden-type-return) The single most important mental model: in **argument position**, `impl Trait` means the *caller* chooses the type, so the function must work for *any* implementor. In **return position**, the *function* chooses the type, so there is *exactly one*, fixed by the body and merely hidden from the signature. The same three words flip who is in control. The TypeScript intuition — “interface in, interface out, both just shapes” — does not capture this asymmetry. ### `impl Trait` is not a trait object [Section titled “impl Trait is not a trait object”](#impl-trait-is-not-a-trait-object) A TypeScript developer often reads `-> impl Summary` as “returns a `Summary` interface value,” analogous to a polymorphic object. It is not. `impl Trait` is resolved entirely at compile time to one concrete type; it never erases the type or introduces indirection. The runtime polymorphism analog of a TypeScript interface-typed value is `Box<dyn Summary>` (heap-allocated, vtable-dispatched), not `impl Summary`. Keep the two firmly apart: confusing them is the root of most early mistakes. ### Edition 2024 captures lifetimes for you [Section titled “Edition 2024 captures lifetimes for you”](#edition-2024-captures-lifetimes-for-you) On the 2024 edition, a return-position `impl Trait` automatically captures any in-scope lifetimes, so returning an iterator that borrows an argument “just works” without the older `+ '_` annotation: ```rust 1 // On edition 2024, the returned iterator may borrow from `data` with no 2 // extra lifetime annotation needed. 3 fn first_words(data: &[String]) -> impl Iterator<Item = &str> { 4 data.iter().map(|s| s.split(' ').next().unwrap_or("")) 5 } 6 7 fn main() { 8 let lines = vec!["hello world".to_string(), "foo bar".to_string()]; 9 let firsts: Vec<&str> = first_words(&lines).collect(); 10 println!("{:?}", firsts); 11 } ``` **Real output:** ```text 1 ["hello", "foo"] ``` > **Tip:** If you read older tutorials that add `+ '_` or `+ 'a` to `impl Trait` return types to make borrowing compile, that ceremony is usually unnecessary on the 2024 edition. Use `cargo new` so you are always on the newest edition and get this behavior by default. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Returning two different concrete types from one `-> impl Trait` [Section titled “Pitfall 1: Returning two different concrete types from one -> impl Trait”](#pitfall-1-returning-two-different-concrete-types-from-one---impl-trait) This is the trap that TypeScript habits walk straight into. Because both `Rev<IntoIter<…>>` and `IntoIter<…>` “are iterators,” it feels like you should be able to return either branch, exactly as a TypeScript function returning `Summary` could return an `Article` or a `Tweet`. Rust refuses: `-> impl Trait` is *one* hidden type, not a union. ```rust 1 // does not compile (error[E0308]: `if` and `else` have incompatible types) 2 fn make_iter(reverse: bool) -> impl Iterator<Item = i32> { 3 let v = vec![1, 2, 3]; 4 if reverse { 5 v.into_iter().rev() // type: Rev<IntoIter<i32>> 6 } else { 7 v.into_iter() // type: IntoIter<i32> -- a DIFFERENT type 8 } 9 } 10 11 fn main() { 12 for x in make_iter(true) { 13 println!("{x}"); 14 } 15 } ``` Real compiler error: ```text 1 error[E0308]: `if` and `else` have incompatible types 2 --> src/main.rs:7:9 3 | 4 4 | / if reverse { 5 5 | | v.into_iter().rev() 6 | | ------------------- expected because of this 7 6 | | } else { 8 7 | | v.into_iter() 9 | | ^^^^^^^^^^^^^ expected `Rev<IntoIter<{integer}>>`, found `IntoIter<{integer}>` 10 8 | | } 11 | |_____- `if` and `else` have incompatible types 12 | 13 = note: expected struct `Rev<std::vec::IntoIter<_>>` 14 found struct `std::vec::IntoIter<_>` 15 help: you could change the return type to be a boxed trait object 16 | 17 2 - fn make_iter(reverse: bool) -> impl Iterator<Item = i32> { 18 2 + fn make_iter(reverse: bool) -> Box<dyn Iterator<Item = i32>> { 19 | 20 help: if you change the return type to expect trait objects, box the returned expressions 21 | 22 5 ~ Box::new(v.into_iter().rev()) 23 6 | } else { 24 7 ~ Box::new(v.into_iter()) 25 | ``` **Fix:** when branches genuinely return different concrete types, switch to a trait object, `Box<dyn Trait>`, which *does* allow runtime variation (at the cost of one heap allocation and dynamic dispatch). The compiler even spells out the edit: ```rust 1 fn make_iter(reverse: bool) -> Box<dyn Iterator<Item = i32>> { 2 let v = vec![1, 2, 3]; 3 if reverse { 4 Box::new(v.into_iter().rev()) 5 } else { 6 Box::new(v.into_iter()) 7 } 8 } 9 10 fn main() { 11 let collected: Vec<i32> = make_iter(true).collect(); 12 println!("{:?}", collected); 13 } ``` **Real output:** ```text 1 [3, 2, 1] ``` See [Trait Objects and Dynamic Dispatch](/09-generics-traits/06-trait-objects/) for the full static-vs-dynamic trade-off. ### Pitfall 2: Trying to turbofish or unify two `impl Trait` arguments [Section titled “Pitfall 2: Trying to turbofish or unify two impl Trait arguments”](#pitfall-2-trying-to-turbofish-or-unify-two-impl-trait-arguments) Two parameters both written `impl Trait` are two *independent* anonymous type parameters (they need not be the same type), and because the type has no name, you cannot pin it with the turbofish (`::<>`) the way you can a named generic. ```rust 1 trait Shape { fn area(&self) -> f64; } 2 struct Sq(f64); 3 impl Shape for Sq { fn area(&self) -> f64 { self.0 * self.0 } } 4 5 fn bigger(a: impl Shape, b: impl Shape) -> f64 { 6 a.area().max(b.area()) 7 } 8 9 fn main() { 10 // does not compile (error[E0107]: function takes 0 generic arguments) 11 println!("{}", bigger::<Sq>(Sq(2.0), Sq(3.0))); 12 } ``` Real compiler error: ```text 1 error[E0107]: function takes 0 generic arguments but 1 generic argument was supplied 2 --> src/main.rs:13:20 3 | 4 13 | println!("{}", bigger::<Sq>(Sq(2.0), Sq(3.0))); 5 | ^^^^^^------ help: remove the unnecessary generics 6 | | 7 | expected 0 generic arguments 8 | 9 note: function defined here, with 0 generic parameters 10 --> src/main.rs:6:4 11 | 12 6 | fn bigger(a: impl Shape, b: impl Shape) -> f64 { 13 | ^^^^^^ 14 = note: `impl Trait` cannot be explicitly specified as a generic argument ``` **Fix:** when you need to *name* the type (to turbofish it, or to require two parameters to be the **same** type), use an explicit generic parameter instead: ```rust 1 fn bigger<T: Shape>(a: T, b: T) -> f64 { 2 a.area().max(b.area()) 3 } ``` Now `a` and `b` must be the same `T`, and you can write `bigger::<Sq>(...)`. The rule of thumb: `impl Trait` arguments for one-off, name-free convenience; named generics when the type relationship matters. ### Pitfall 3: Using `impl Trait` where it is not allowed (struct fields) [Section titled “Pitfall 3: Using impl Trait where it is not allowed (struct fields)”](#pitfall-3-using-impl-trait-where-it-is-not-allowed-struct-fields) `impl Trait` is only permitted in the argument and return positions of functions and methods. It is *not* a general type you can drop into a struct field, a `let` binding’s type annotation, or a type alias. ```rust 1 struct Pipeline { 2 // does not compile (error[E0562]: `impl Trait` is not allowed in field types) 3 source: impl Iterator<Item = i32>, 4 } 5 6 fn main() { 7 let _ = Pipeline { source: (0..3) }; 8 } ``` Real compiler error: ```text 1 error[E0562]: `impl Trait` is not allowed in field types 2 --> src/main.rs:3:13 3 | 4 3 | source: impl Iterator<Item = i32>, 5 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 6 | 7 = note: `impl Trait` is only allowed in arguments and return types of functions and methods ``` **Fix:** make the struct generic over the field type (`struct Pipeline<I: Iterator<Item = i32>> { source: I }`; see [Generic Structs](/09-generics-traits/01-generic-structs/)), or store a trait object (`source: Box<dyn Iterator<Item = i32>>`). ### Pitfall 4: A trait method using `impl Trait` is not `dyn`-compatible [Section titled “Pitfall 4: A trait method using impl Trait is not dyn-compatible”](#pitfall-4-a-trait-method-using-impl-trait-is-not-dyn-compatible) RPITIT (`-> impl Trait` inside a trait) is convenient, but it makes the trait unusable as a `dyn` trait object, because each implementor’s hidden return type could differ, so no single vtable can describe it. ```rust 1 trait Container { 2 fn items(&self) -> impl Iterator<Item = i32>; 3 } 4 5 struct Evens { upto: i32 } 6 7 impl Container for Evens { 8 fn items(&self) -> impl Iterator<Item = i32> { 9 (0..self.upto).filter(|n| n % 2 == 0) 10 } 11 } 12 13 fn main() { 14 // does not compile (error[E0038]: the trait `Container` is not dyn compatible) 15 let boxed: Box<dyn Container> = Box::new(Evens { upto: 8 }); 16 let _ = boxed; 17 } ``` Real compiler error (excerpt): ```text 1 error[E0038]: the trait `Container` is not dyn compatible 2 --> src/main.rs:15:24 3 | 4 15 | let boxed: Box<dyn Container> = Box::new(Evens { upto: 8 }); 5 | ^^^^^^^^^ `Container` is not dyn compatible 6 | 7 note: for a trait to be dyn compatible it needs to allow building a vtable 8 ... 9 2 | fn items(&self) -> impl Iterator<Item = i32>; 10 | ^^^^^^^^^^^^^^^^^^^^^^^^^ ...because method `items` references an `impl Trait` type in its return type ``` **Fix:** if you need `dyn` dispatch, return a boxed trait object from the trait method instead (`fn items(&self) -> Box<dyn Iterator<Item = i32>>`), accepting the heap allocation. If you only ever use the trait through generics (static dispatch), RPITIT is fine as-is. “dyn compatibility” (formerly called “object safety”) is detailed in [Trait Objects and Dynamic Dispatch](/09-generics-traits/06-trait-objects/). *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Prefer `impl Trait` in arguments for single-use, name-free parameters [Section titled “Prefer impl Trait in arguments for single-use, name-free parameters”](#prefer-impl-trait-in-arguments-for-single-use-name-free-parameters) When a parameter’s type appears once and you do not need to refer to it elsewhere, `fn f(x: impl Trait)` reads more cleanly than `fn f<T: Trait>(x: T)`. Reach for the named generic the moment you need to: name the type, repeat it across parameters, turbofish it, or add a `where` clause that mentions it. Both compile to the same code, so the choice is purely about readability and capability. ### Use return-position `impl Trait` to hide unnameable or unstable types [Section titled “Use return-position impl Trait to hide unnameable or unstable types”](#use-return-position-impl-trait-to-hide-unnameable-or-unstable-types) Returning closures and iterator adapters is the canonical, idiomatic use of RPIT. It also gives you encapsulation: callers depend on the *capability* (`Iterator<Item = T>`), not the exact adapter chain, so you can refactor the body (swap `filter` for `take_while`, add a `map`) without changing the public signature. This is a real API-stability win that has no direct TypeScript analog. ### Reach for `Box<dyn Trait>` when you need runtime variation [Section titled “Reach for Box\<dyn Trait> when you need runtime variation”](#reach-for-boxdyn-trait-when-you-need-runtime-variation) `impl Trait` return = one type known at compile time. The moment you need different concrete types depending on runtime conditions (branches, a config flag, a plugin registry), switch to `Box<dyn Trait>`. The cost is one allocation and dynamic dispatch; the benefit is genuine runtime polymorphism. Choosing between them is the central decision covered in [Trait Objects and Dynamic Dispatch](/09-generics-traits/06-trait-objects/). ### Add explicit bounds to `impl Trait` returns when callers need them [Section titled “Add explicit bounds to impl Trait returns when callers need them”](#add-explicit-bounds-to-impl-trait-returns-when-callers-need-them) `-> impl Iterator<Item = u32>` only promises `Iterator`. If callers also need to, say, clone or debug-print the returned value, add the bound: `-> impl Iterator<Item = u32> + Clone`. The hidden type must then satisfy all listed traits, and callers may rely on every one of them. Be deliberate: the bounds you publish are the contract. ### Treat RPITIT as the default for “method returns an iterator/future” [Section titled “Treat RPITIT as the default for “method returns an iterator/future””](#treat-rpitit-as-the-default-for-method-returns-an-iteratorfuture) Since Rust 1.75, returning `impl Trait` from a trait method (including `async fn`, which desugars to `-> impl Future`) is idiomatic and avoids the old associated-type or `async-trait`-boxing boilerplate. Only fall back to associated types or boxing when you specifically need `dyn` dispatch. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small, production-flavored log-processing pipeline. `impl Trait` in **argument** position keeps the parser ergonomic (it accepts any iterator of lines), and `impl Trait` in **return** position hides both the parser’s iterator-adapter type and a generated filter closure. This is precisely the kind of code where naming the real types would be miserable. ```rust 1 #[derive(Debug)] 2 struct LogLine { 3 level: String, 4 message: String, 5 } 6 7 // Argument position: accept anything iterable yielding `&str`. 8 // Return position: hide the `FilterMap<...>` adapter type behind the capability. 9 fn parse_lines<'a>(raw: impl Iterator<Item = &'a str>) -> impl Iterator<Item = LogLine> { 10 raw.filter_map(|line| { 11 let (level, message) = line.split_once(' ')?; 12 Some(LogLine { 13 level: level.to_string(), 14 message: message.to_string(), 15 }) 16 }) 17 } 18 19 // Return position: build and return a reusable predicate closure. 20 // The closure's type is unnameable, so `impl Fn(...) -> bool` is the only way. 21 fn at_least(threshold: u8) -> impl Fn(&LogLine) -> bool { 22 let rank = |lvl: &str| match lvl { 23 "ERROR" => 3u8, 24 "WARN" => 2, 25 "INFO" => 1, 26 _ => 0, 27 }; 28 move |line| rank(&line.level) >= threshold 29 } 30 31 fn main() { 32 let raw = "INFO server started\nWARN low disk\nERROR disk full\nDEBUG noise"; 33 let important = at_least(2); 34 35 for entry in parse_lines(raw.lines()).filter(|l| important(l)) { 36 println!("[{}] {}", entry.level, entry.message); 37 } 38 } ``` **Real output:** ```text 1 [WARN] low disk 2 [ERROR] disk full ``` Things worth highlighting: * `parse_lines` takes `impl Iterator<Item = &'a str>`: it works with `raw.lines()`, a `Vec`’s iterator, or anything else yielding `&str`, with zero allocation and full inlining. That single-use argument is a textbook case for the argument-position form rather than a named generic. * Its return type, `impl Iterator<Item = LogLine>`, hides a `FilterMap<Lines, {closure}>`. We can later add a `.map(...)` or change the parsing logic without touching the signature. * `at_least` returns `impl Fn(&LogLine) -> bool`. A closure that captures `threshold` has a unique anonymous type with no name you could write down; `impl Fn(...)` is the idiomatic — and only practical — way to return it. > **Tip:** If you ever needed to choose the parser at runtime (say, JSON lines vs. plain text, selected by a flag), the two parsers would have different concrete iterator types, so you would store the chosen pipeline as `Box<dyn Iterator<Item = LogLine>>` rather than `impl Iterator<...>`. That is Pitfall 1’s lesson applied as a design decision. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Rust Book — Traits as Parameters (`impl Trait`)](https://doc.rust-lang.org/book/ch10-02-traits.html#traits-as-parameters) * [The Rust Book — Returning Types that Implement Traits](https://doc.rust-lang.org/book/ch10-02-traits.html#returning-types-that-implement-traits) * [The Rust Reference — `impl Trait`](https://doc.rust-lang.org/reference/types/impl-trait.html) * [Rust 1.75 release notes — `async fn` and RPIT in traits](https://blog.rust-lang.org/2023/12/28/Rust-1.75.0.html) * [Edition Guide — RPIT lifetime capture rules (2024)](https://doc.rust-lang.org/edition-guide/rust-2024/rpit-lifetime-capture.html) ### Related sections in this guide [Section titled “Related sections in this guide”](#related-sections-in-this-guide) * [Section 09 overview](/09-generics-traits/) — the full map of generics and traits * [Traits](/09-generics-traits/03-traits/) — defining traits and `impl Trait for Type` * [Trait Bounds](/09-generics-traits/05-trait-bounds/) — `<T: Trait>`, multiple bounds, `where`, and bounds on returns * [Generic Functions](/09-generics-traits/00-generic-functions/) — monomorphization vs. TypeScript type erasure; the turbofish `::<>` * [Generic Structs](/09-generics-traits/01-generic-structs/) — making a struct generic over a field type * [Trait Objects and Dynamic Dispatch](/09-generics-traits/06-trait-objects/) — `Box<dyn Trait>`, dyn compatibility, and static vs. dynamic dispatch * [Section 01: Getting Started](/01-getting-started/) — Cargo and editions * [Section 02: Basics](/02-basics/) — closures and iterator basics * [Section 10: Smart Pointers](/10-smart-pointers/) — `Box<T>` and heap allocation * [Section 11: Async](/11-async/) — `async fn` in traits (RPITIT for futures) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: An argument-position `impl Trait` formatter [Section titled “Exercise 1: An argument-position impl Trait formatter”](#exercise-1-an-argument-position-impl-trait-formatter) **Difficulty:** Easy **Objective:** Use `impl Trait` in argument position to write a function over “anything printable.” **Instructions:** Write a function `describe_all` that takes a slice of items, each of which implements `std::fmt::Display`, and returns a single `String` with the items joined by `", "`. Use `&[impl std::fmt::Display]` as the parameter type. In `main`, call it once with `&[1, 2, 3]` and once with `&["a", "b", "c"]`, printing each result. ```rust 1 fn describe_all(items: &[impl std::fmt::Display]) -> String { 2 // TODO: map each item to its string form and join with ", " 3 } 4 5 fn main() { 6 // TODO: call with &[1, 2, 3] and with &["a", "b", "c"] 7 } ``` Solution ```rust 1 fn describe_all(items: &[impl std::fmt::Display]) -> String { 2 items 3 .iter() 4 .map(|x| x.to_string()) 5 .collect::<Vec<_>>() 6 .join(", ") 7 } 8 9 fn main() { 10 println!("{}", describe_all(&[1, 2, 3])); 11 println!("{}", describe_all(&["a", "b", "c"])); 12 } ``` **Output:** ```text 1 1, 2, 3 2 a, b, c ``` `&[impl Display]` is the anonymous-generic form of `<T: Display>(items: &[T])`. Because each call uses a different concrete element type, the compiler monomorphizes `describe_all` once per type. ### Exercise 2: Return a stateful closure with RPIT [Section titled “Exercise 2: Return a stateful closure with RPIT”](#exercise-2-return-a-stateful-closure-with-rpit) **Difficulty:** Medium **Objective:** Return a closure whose type is unnameable, using return-position `impl Trait`, and observe that an `FnMut` closure can carry mutable state. **Instructions:** Write a function `make_counter(start: i32) -> impl FnMut() -> i32` that returns a closure. Each time the closure is called it should return the current value and then increment it (so the first call returns `start`, the next `start + 1`, and so on). In `main`, create a counter starting at `100` and call it three times, printing each result. ```rust 1 fn make_counter(start: i32) -> impl FnMut() -> i32 { 2 // TODO: capture mutable state and return it, incrementing each call 3 } 4 5 fn main() { 6 // TODO: make a counter at 100 and call it three times 7 } ``` Solution ```rust 1 fn make_counter(start: i32) -> impl FnMut() -> i32 { 2 let mut current = start; 3 move || { 4 let value = current; 5 current += 1; 6 value 7 } 8 } 9 10 fn main() { 11 let mut next_id = make_counter(100); 12 println!("{}", next_id()); 13 println!("{}", next_id()); 14 println!("{}", next_id()); 15 } ``` **Output:** ```text 1 100 2 101 3 102 ``` The closure captures `current` by value (`move`) and mutates it, so it implements `FnMut` rather than only `Fn`. Returning `impl FnMut() -> i32` is the only practical way to hand back a closure, since its type has no name. Note that the binding must be `let mut next_id` because calling an `FnMut` needs a mutable borrow of the closure. ### Exercise 3: An iterator-returning trait method (RPITIT) and a generic consumer [Section titled “Exercise 3: An iterator-returning trait method (RPITIT) and a generic consumer”](#exercise-3-an-iterator-returning-trait-method-rpitit-and-a-generic-consumer) **Difficulty:** Hard **Objective:** Use return-position `impl Trait` inside a trait, then consume it through an argument-position `impl Trait`, combining both forms in one program. **Instructions:** Define a trait `DataSource` with one method `records(&self) -> impl Iterator<Item = String>`. Implement it for a struct `StaticList { data: Vec<String> }` so that `records` yields clones of the stored strings. Write a free function `print_records(source: &impl DataSource)` that iterates the source’s records and prints each on its own line. In `main`, build a `StaticList` containing `"alpha"` and `"beta"` and pass it to `print_records`. ```rust 1 trait DataSource { 2 // TODO: records(&self) -> impl Iterator<Item = String> 3 } 4 5 struct StaticList { 6 data: Vec<String>, 7 } 8 9 // TODO: impl DataSource for StaticList 10 11 fn print_records(source: &impl DataSource) { 12 // TODO: iterate source.records() and print each 13 } 14 15 fn main() { 16 // TODO: build a StaticList and call print_records 17 } ``` Solution ```rust 1 trait DataSource { 2 fn records(&self) -> impl Iterator<Item = String>; 3 } 4 5 struct StaticList { 6 data: Vec<String>, 7 } 8 9 impl DataSource for StaticList { 10 fn records(&self) -> impl Iterator<Item = String> { 11 self.data.iter().cloned() 12 } 13 } 14 15 fn print_records(source: &impl DataSource) { 16 for r in source.records() { 17 println!("{r}"); 18 } 19 } 20 21 fn main() { 22 let src = StaticList { 23 data: vec!["alpha".to_string(), "beta".to_string()], 24 }; 25 print_records(&src); 26 } ``` **Output:** ```text 1 alpha 2 beta ``` This program uses RPITIT (the `impl Iterator` return inside the trait) and an argument-position `impl Trait` (in `print_records`) together. Because `DataSource` uses RPITIT, it is not `dyn`-compatible (you could not write `Box<dyn DataSource>`), but static dispatch through `&impl DataSource` works perfectly and allocates nothing. To support `Box<dyn DataSource>`, you would change the method to return `Box<dyn Iterator<Item = String>>` instead. # Default Method Implementations: Boilerplate Elimination > Rust default trait methods ship a body once so every implementor inherits it, like a TypeScript abstract class but extendable to types you don't own. Writing the same helper method on twenty classes is one of the quiet taxes of object-oriented TypeScript. A Rust **default method** lets a trait ship a working body *once*, so every implementor inherits it for free. This file is about that single idea taken seriously: how a well-designed trait turns *one* method you must write into a *whole API* you get for nothing, and where that advantage comes from. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **default (provided) method** is a trait method with a body. Implementors inherit it automatically and may override it. The payoff is reuse: a trait can demand one small required method and then build a dozen useful methods on top of it, all written once in the trait. The standard library’s `Iterator` is the poster child: you write `next`, and `map`, `filter`, `sum`, `collect`, and \~70 more arrive for free. The closest TypeScript analogy is a concrete method on an abstract class, but a Rust trait can hand the same defaults to types you do not own, and even to *every* type that meets a bound. > **Note:** This file focuses on **using defaults to cut boilerplate**: the design patterns and economics. For the mechanical rules (required vs provided, the three call syntaxes, why there is no `super`), read the sibling [Trait Methods](/09-generics-traits/04-trait-methods/) first; this file does not repeat them. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) A common TypeScript pattern: an `abstract class` where subclasses implement one piece and inherit a pile of concrete helpers. Here every responder must supply a `body()`, but `status()`, `contentType()`, `headers()`, and `render()` come pre-built. ```typescript 1 // TypeScript - abstract class supplying default ("concrete") methods 2 abstract class HttpResponder { 3 // The ONE thing each subclass must implement. 4 abstract body(): string; 5 6 // Concrete defaults the subclass inherits unless it overrides them. 7 status(): number { 8 return 200; 9 } 10 contentType(): string { 11 return "text/plain"; 12 } 13 headers(): [string, string][] { 14 return [ 15 ["Content-Type", this.contentType()], 16 ["Content-Length", String(this.body().length)], 17 ]; 18 } 19 render(): string { 20 const reason = { 200: "OK", 404: "Not Found" }[this.status()] ?? "Unknown"; 21 let out = `HTTP/1.1 ${this.status()} ${reason}\n`; 22 for (const [k, v] of this.headers()) out += `${k}: ${v}\n`; 23 out += "\n" + this.body(); 24 return out; 25 } 26 } 27 28 class Welcome extends HttpResponder { 29 body(): string { 30 return "Welcome!"; 31 } 32 // Inherits status, contentType, headers, render. 33 } 34 35 class NotFound extends HttpResponder { 36 body(): string { 37 return "<h1>404</h1>"; 38 } 39 status(): number { 40 return 404; 41 } 42 contentType(): string { 43 return "text/html"; 44 } 45 // Still inherits headers and render. 46 } 47 48 console.log(new Welcome().render()); 49 console.log("----"); 50 console.log(new NotFound().render()); ``` Running this under Node v22 prints: ```text 1 HTTP/1.1 200 OK 2 Content-Type: text/plain 3 Content-Length: 8 4 5 Welcome! 6 ---- 7 HTTP/1.1 404 Not Found 8 Content-Type: text/html 9 Content-Length: 12 10 11 <h1>404</h1> ``` This works, but it leans on **class inheritance**: `Welcome` and `NotFound` *are* `HttpResponder`s. You can only attach these defaults to types you define and `extends`. Keep that constraint in mind: Rust lifts it. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same design as a trait. The single required method is `body`; everything else is a default that implementors inherit. ```rust 1 trait HttpResponder { 2 // The ONE required method each responder must supply. 3 fn body(&self) -> String; 4 5 // Everything below is a provided (default) method: free boilerplate. 6 fn status(&self) -> u16 { 7 200 8 } 9 10 fn content_type(&self) -> &str { 11 "text/plain" 12 } 13 14 fn headers(&self) -> Vec<(String, String)> { 15 vec![ 16 ("Content-Type".to_string(), self.content_type().to_string()), 17 ("Content-Length".to_string(), self.body().len().to_string()), 18 ] 19 } 20 21 fn render(&self) -> String { 22 let mut out = format!("HTTP/1.1 {} {}\n", self.status(), reason(self.status())); 23 for (k, v) in self.headers() { 24 out.push_str(&format!("{k}: {v}\n")); 25 } 26 out.push('\n'); 27 out.push_str(&self.body()); 28 out 29 } 30 } 31 32 fn reason(status: u16) -> &'static str { 33 match status { 34 200 => "OK", 35 404 => "Not Found", 36 _ => "Unknown", 37 } 38 } 39 40 struct Welcome; 41 impl HttpResponder for Welcome { 42 fn body(&self) -> String { 43 "Welcome!".to_string() 44 } 45 // Inherits status (200), content_type, headers, render — all for free. 46 } 47 48 struct NotFound; 49 impl HttpResponder for NotFound { 50 fn body(&self) -> String { 51 "<h1>404</h1>".to_string() 52 } 53 fn status(&self) -> u16 { 54 404 55 } 56 fn content_type(&self) -> &str { 57 "text/html" 58 } 59 // Still inherits headers and render. 60 } 61 62 fn main() { 63 println!("{}", Welcome.render()); 64 println!("----"); 65 println!("{}", NotFound.render()); 66 } ``` Real output (identical to the TypeScript run above): ```text 1 HTTP/1.1 200 OK 2 Content-Type: text/plain 3 Content-Length: 8 4 5 Welcome! 6 ---- 7 HTTP/1.1 404 Not Found 8 Content-Type: text/html 9 Content-Length: 12 10 11 <h1>404</h1> ``` `Welcome` writes three lines of real code (`body`) and inherits four methods. `NotFound` overrides two and still inherits `headers` and `render`. The boilerplate lives in *one* place: the trait. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The leverage: defaults call the required method [Section titled “The leverage: defaults call the required method”](#the-leverage-defaults-call-the-required-method) The whole trick is that a default body may call **other trait methods**, including the required ones. `render` never knows what `body` returns or what `status` a given type uses. It calls `self.body()` and `self.status()` and lets each concrete type fill in the blanks. So the *orchestration* is written once, and each implementor supplies only the *small required pieces*. This is why a tiny required surface produces a large free API. Consider a reporting trait whose only required method is `rows`: ```rust 1 trait Report { 2 // Required: the raw rows. 3 fn rows(&self) -> Vec<String>; 4 5 // Provided defaults derived entirely from `rows`. 6 fn count(&self) -> usize { 7 self.rows().len() 8 } 9 fn is_empty(&self) -> bool { 10 self.count() == 0 11 } 12 fn first(&self) -> Option<String> { 13 self.rows().into_iter().next() 14 } 15 fn to_csv(&self) -> String { 16 self.rows().join(",") 17 } 18 fn summary(&self) -> String { 19 format!("{} row(s): {}", self.count(), self.to_csv()) 20 } 21 } 22 23 struct SalesReport { 24 entries: Vec<String>, 25 } 26 impl Report for SalesReport { 27 fn rows(&self) -> Vec<String> { 28 self.entries.clone() 29 } 30 // count, is_empty, first, to_csv, summary: all inherited. 31 } 32 33 fn main() { 34 let r = SalesReport { 35 entries: vec!["jan=10".into(), "feb=12".into(), "mar=9".into()], 36 }; 37 println!("count = {}", r.count()); 38 println!("empty = {}", r.is_empty()); 39 println!("first = {:?}", r.first()); 40 println!("csv = {}", r.to_csv()); 41 println!("summary = {}", r.summary()); 42 } ``` Real output: ```text 1 count = 3 2 empty = false 3 first = Some("jan=10") 4 csv = jan=10,feb=12,mar=9 5 summary = 3 row(s): jan=10,feb=12,mar=9 ``` `SalesReport` implements one method. It gets five. A second report type — backed by a database, a file, an HTTP call — would also implement only `rows` and inherit the identical query API. That is the boilerplate elimination this file is named for. > **Tip:** Notice `summary` calls `count` and `to_csv`, which themselves call `rows`. Defaults can layer on defaults. Keep the layering shallow and the required surface tiny. ### Defaults that build on a single comparison [Section titled “Defaults that build on a single comparison”](#defaults-that-build-on-a-single-comparison) The standard library uses this everywhere. `Ord` requires `cmp` and provides `max`, `min`, and `clamp`; `Iterator` requires `next` and provides the rest. You can mirror the pattern in your own code: define the one operation that only the implementor can know, then derive a family of conveniences. ```rust 1 use std::cmp::Ordering; 2 3 // Define ONE comparison, get a family of methods free. 4 trait Ranked { 5 // Required: how do two of these compare? 6 fn rank_cmp(&self, other: &Self) -> Ordering; 7 8 // Provided helpers derived from the single required method. 9 fn is_better_than(&self, other: &Self) -> bool { 10 self.rank_cmp(other) == Ordering::Greater 11 } 12 fn max_of<'a>(&'a self, other: &'a Self) -> &'a Self { 13 if self.rank_cmp(other) == Ordering::Less { 14 other 15 } else { 16 self 17 } 18 } 19 } 20 21 struct Player { 22 name: &'static str, 23 score: u32, 24 } 25 impl Ranked for Player { 26 fn rank_cmp(&self, other: &Self) -> Ordering { 27 self.score.cmp(&other.score) 28 } 29 } 30 31 fn main() { 32 let a = Player { name: "Ada", score: 90 }; 33 let b = Player { name: "Bo", score: 75 }; 34 println!("Ada better than Bo? {}", a.is_better_than(&b)); 35 println!("winner = {}", a.max_of(&b).name); 36 } ``` Real output: ```text 1 Ada better than Bo? true 2 winner = Ada ``` ### The move TypeScript cannot make: defaults for types you do not own [Section titled “The move TypeScript cannot make: defaults for types you do not own”](#the-move-typescript-cannot-make-defaults-for-types-you-do-not-own) This is where the analogy with abstract classes breaks down, in Rust’s favor. A TypeScript abstract class only gives its concrete methods to subclasses you write with `extends`. A Rust trait with defaults can be implemented for *any* type, including a foreign one (within the [orphan rule](/09-generics-traits/12-orphan-rule/)), and a single **blanket implementation** can hand those defaults to *every* type that meets a bound. This is the **extension trait** pattern: add methods to types you do not own. Here we bolt new methods onto every iterator of `i64` by giving an empty blanket `impl` that simply inherits all the defaults: ```rust 1 // An "extension trait" that adds methods to ANY iterator-of-numbers via defaults. 2 trait NumericExt: Iterator<Item = i64> + Sized { 3 fn sum_squares(self) -> i64 { 4 self.map(|x| x * x).sum() 5 } 6 fn average(self) -> Option<f64> { 7 let v: Vec<i64> = self.collect(); 8 if v.is_empty() { 9 None 10 } else { 11 Some(v.iter().sum::<i64>() as f64 / v.len() as f64) 12 } 13 } 14 } 15 16 // One blanket impl gives every qualifying iterator all the default methods. 17 impl<I: Iterator<Item = i64>> NumericExt for I {} 18 19 fn main() { 20 let data = [1i64, 2, 3, 4]; 21 println!("sum_squares = {}", data.iter().copied().sum_squares()); 22 println!("average = {:?}", data.iter().copied().average()); 23 let empty: [i64; 0] = []; 24 println!("empty avg = {:?}", empty.iter().copied().average()); 25 } ``` Real output: ```text 1 sum_squares = 30 2 average = Some(2.5) 3 empty avg = None ``` The `impl<I: Iterator<Item = i64>> NumericExt for I {}` body is *empty*: every method comes from the defaults. That one line of `impl` retrofits `sum_squares` and `average` onto arrays, vectors, ranges, hash-map values, anything that iterates `i64`. There is no equivalent in TypeScript short of monkey-patching `Array.prototype`, which is global, untyped, and discouraged. (The generics behind `impl<I: ...>` are covered in [Generic Functions](/09-generics-traits/00-generic-functions/) and [Trait Bounds](/09-generics-traits/05-trait-bounds/); the supertrait bound `: Iterator<...>` is explained in [Supertraits](/09-generics-traits/09-supertraits/).) ### Where the cost goes: monomorphization, not runtime dispatch [Section titled “Where the cost goes: monomorphization, not runtime dispatch”](#where-the-cost-goes-monomorphization-not-runtime-dispatch) In TypeScript, an inherited method is one function in memory; every subclass instance calls the same code via the prototype chain (dynamic dispatch). In Rust, when you call a default method on a concrete type, the compiler **monomorphizes** it: it stamps out a specialized copy as if you had written it by hand on that type, then inlines and optimizes it. So a default method is not “shared code with a virtual call”; it is a template the compiler expands per type. You get the source-level deduplication of inheritance with the runtime profile of hand-written code. (Dynamic dispatch is still available on demand via [trait objects](/09-generics-traits/06-trait-objects/); contrast the two in [Generic Functions](/09-generics-traits/00-generic-functions/).) *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concern | TypeScript (abstract class) | Rust (trait default method) | | ------------------------------------ | ---------------------------------------- | --------------------------------------------------------------------- | | Where defaults live | concrete methods on an `abstract class` | methods with a body in a `trait` | | Who can inherit them | only subclasses you write with `extends` | **any** type that `impl`s the trait, including foreign types | | Apply to many types at once | one base class per hierarchy | a single **blanket `impl`** covers every type meeting a bound | | Dispatch of an inherited method | dynamic, via the prototype chain | **static**, monomorphized + inlined per type (dynamic only via `dyn`) | | Accessing instance data in a default | `this.field` works directly | only via trait methods; defaults cannot see struct fields | | Reusing the default after overriding | `super.method()` | no `super`; factor shared logic into a helper method | | Multiple sources of defaults | single inheritance (one base class) | a type can `impl` many traits, each bringing defaults | The headline difference for boilerplate: **inheritance ties defaults to a class hierarchy; traits do not.** A type can pick up default-laden behavior from any number of traits, and one blanket `impl` can distribute defaults across an open-ended set of types. That is strictly more reach than `extends`. > **Warning:** A default method **cannot read the implementing struct’s fields** (`self.some_field`). Different implementors have different fields, so the trait has no idea they exist. Expose any per-type data the default needs through a *required* method (a getter) and have the default call that. The first pitfall below shows the exact compiler error. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: A default method reaching for a struct field [Section titled “Pitfall 1: A default method reaching for a struct field”](#pitfall-1-a-default-method-reaching-for-a-struct-field) Coming from TypeScript, where `this.name` is fair game inside an inherited method, the instinct is to write `self.name` in a default. The trait has no fields, so this does not compile. ```rust 1 trait Named { 2 fn greeting(&self) -> String { 3 // does not compile (error[E0609]): a trait default can't see fields 4 format!("Hi, {}", self.name) 5 } 6 } 7 8 struct User { 9 name: String, 10 } 11 impl Named for User {} 12 13 fn main() { 14 let u = User { name: "Sam".into() }; 15 println!("{}", u.greeting()); 16 } ``` The real error: ```text 1 error[E0609]: no field `name` on type `&Self` 2 --> src/main.rs:4:32 3 | 4 1 | trait Named { 5 | ----------- type parameter 'Self' declared here 6 ... 7 4 | format!("Hi, {}", self.name) 8 | ^^^^ unknown field 9 10 For more information about this error, try `rustc --explain E0609`. ``` The fix is to add a required getter and let the default call it: ```rust 1 trait Named { 2 fn name(&self) -> &str; // required getter 3 fn greeting(&self) -> String { 4 format!("Hi, {}", self.name()) // default calls the getter 5 } 6 } 7 8 struct User { 9 name: String, 10 } 11 impl Named for User { 12 fn name(&self) -> &str { 13 &self.name 14 } 15 } 16 17 fn main() { 18 let u = User { name: "Sam".into() }; 19 println!("{}", u.greeting()); 20 } ``` This is the single most common surprise for TypeScript developers, and it is the reason the required-getters-plus-provided-orchestration pattern shows up so often in Rust traits. ### Pitfall 2: Changing the signature when “overriding” a default [Section titled “Pitfall 2: Changing the signature when “overriding” a default”](#pitfall-2-changing-the-signature-when-overriding-a-default) An override must match the trait’s signature exactly. Tweaking the return type does not overload the method; it stops satisfying the trait. ```rust 1 trait Pricing { 2 fn base(&self) -> u32; 3 fn total(&self) -> u32 { 4 self.base() 5 } 6 } 7 8 struct Item; 9 impl Pricing for Item { 10 fn base(&self) -> u32 { 11 100 12 } 13 // does not compile (error[E0053]): return type must match the trait 14 fn total(&self) -> f64 { 15 self.base() as f64 * 1.2 16 } 17 } 18 19 fn main() { 20 println!("{}", Item.total()); 21 } ``` The real error: ```text 1 error[E0053]: method `total` has an incompatible type for trait 2 --> src/main.rs:14:24 3 | 4 14 | fn total(&self) -> f64 { 5 | ^^^ expected `u32`, found `f64` 6 | 7 note: type in trait 8 --> src/main.rs:3:24 9 | 10 3 | fn total(&self) -> u32 { 11 | ^^^ 12 = note: expected signature `fn(&Item) -> u32` 13 found signature `fn(&Item) -> f64` 14 help: change the output type to match the trait 15 | 16 14 - fn total(&self) -> f64 { 17 14 + fn total(&self) -> u32 { 18 | ``` If you genuinely want a different return shape, that is a *different* method (or a different trait), not an override. ### Pitfall 3: Adding a default whose behavior is wrong for most implementors [Section titled “Pitfall 3: Adding a default whose behavior is wrong for most implementors”](#pitfall-3-adding-a-default-whose-behavior-is-wrong-for-most-implementors) A default is silent: a type that forgets to override it still compiles and runs. That is the danger of a default that is right only sometimes. If `serialize` defaults to JSON but half your types need XML, those types will *silently* emit JSON until someone notices in production. When only the implementor can know the right answer, make the method **required** so the compiler forces a decision at `impl` time. Reserve defaults for behavior that is correct (or a deliberately sensible fallback) for essentially every implementor. ### Pitfall 4: Expecting a default to call back into an overridden version via `super` [Section titled “Pitfall 4: Expecting a default to call back into an overridden version via super”](#pitfall-4-expecting-a-default-to-call-back-into-an-overridden-version-via-super) There is no `super` in Rust. Once a type overrides a default, the trait’s original body is not reachable from inside that override; `self.method()` calls the override itself (infinite recursion). The idiom is to put the shared work in its own method that both the default and any override can call. This is covered with the real Clippy output in [Trait Methods → Common Pitfalls](/09-generics-traits/04-trait-methods/#common-pitfalls); mentioned here only so the boilerplate-reduction story is complete. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Minimize the required surface, maximize the provided surface.** Aim for the `Iterator` shape: one (or very few) required methods, with everything convenient built on top as defaults. The smaller the required set, the cheaper each new implementor. * **Write defaults purely in terms of trait methods.** A default that calls only `self`’s other trait methods (never struct fields) stays valid for every present and future implementor. Expose needed data through required getters. * **Use a blanket `impl` to distribute defaults widely.** The extension-trait pattern (`impl<T: Bound> MyTrait for T {}`) retrofits a whole default API onto every qualifying type: the boilerplate-elimination move that has no clean TypeScript analogue. * **Default only what is broadly correct; require the rest.** A wrong-by-default method causes silent bugs. When in doubt, make it required and let the compiler demand an explicit choice. * **Document the override contract.** In `///` doc comments, mark each default as “override to customize X” or “you should not need to touch this”, so implementors know which defaults are extension points. * **Prefer overriding a default for a faster path, not different behavior.** The standard library overrides defaults like `Iterator::count` or `size_hint` for performance while keeping the observable result identical. Use overrides the same way; if you need *different* semantics, reconsider the design. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A read-side repository trait. A concrete store implements one method, `all`, and inherits an entire query API: count, lookup, existence check, projection, and a generic filter. Swapping the backing store (in-memory here, but it could be SQL or a cache) requires writing only `all` again. ```rust 1 use std::collections::HashMap; 2 3 #[derive(Clone, Debug)] 4 struct Record { 5 id: u32, 6 name: String, 7 } 8 9 // A repository trait where ONE backend method (`all`) powers a whole read API. 10 trait ReadRepository { 11 // Required: the single point a concrete store must implement. 12 fn all(&self) -> Vec<Record>; 13 14 // Provided: a full query API built on top of `all`, written once. 15 fn count(&self) -> usize { 16 self.all().len() 17 } 18 fn find(&self, id: u32) -> Option<Record> { 19 self.all().into_iter().find(|r| r.id == id) 20 } 21 fn exists(&self, id: u32) -> bool { 22 self.find(id).is_some() 23 } 24 fn names(&self) -> Vec<String> { 25 self.all().into_iter().map(|r| r.name).collect() 26 } 27 fn where_<F: Fn(&Record) -> bool>(&self, pred: F) -> Vec<Record> { 28 self.all().into_iter().filter(|r| pred(r)).collect() 29 } 30 } 31 32 struct InMemory { 33 store: HashMap<u32, Record>, 34 } 35 impl ReadRepository for InMemory { 36 fn all(&self) -> Vec<Record> { 37 let mut v: Vec<Record> = self.store.values().cloned().collect(); 38 v.sort_by_key(|r| r.id); 39 v 40 } 41 // count, find, exists, names, where_ : all free. 42 } 43 44 fn main() { 45 let mut store = HashMap::new(); 46 store.insert(1, Record { id: 1, name: "alice".into() }); 47 store.insert(2, Record { id: 2, name: "bob".into() }); 48 store.insert(3, Record { id: 3, name: "carol".into() }); 49 let repo = InMemory { store }; 50 51 println!("count = {}", repo.count()); 52 println!("find(2) = {:?}", repo.find(2)); 53 println!("exists(9) = {}", repo.exists(9)); 54 println!("names = {:?}", repo.names()); 55 let long = repo.where_(|r| r.name.len() > 3); 56 println!( 57 "names > 3 = {:?}", 58 long.iter().map(|r| &r.name).collect::<Vec<_>>() 59 ); 60 } ``` Real output: ```text 1 count = 3 2 find(2) = Some(Record { id: 2, name: "bob" }) 3 exists(9) = false 4 names = ["alice", "bob", "carol"] 5 names > 3 = ["alice", "carol"] ``` Every new storage backend implements `all` and inherits the rest. In a real service, `find` backed by a naive scan of `all()` would be overridden with an indexed lookup, which is exactly Pitfall 4’s “override for a faster path, not different behavior”. The shape of the API never changes; only the one expensive method gets specialized per backend. > **Note:** `where_` takes a generic closure `F: Fn(&Record) -> bool`. A default method may be generic over its own parameters, which is part of why one default can serve so many call sites. See [Trait Bounds](/09-generics-traits/05-trait-bounds/) and [Generic Functions](/09-generics-traits/00-generic-functions/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book - Default Implementations](https://doc.rust-lang.org/book/ch10-02-traits.html#default-implementations) * [The Rust Book - Traits: Defining Shared Behavior](https://doc.rust-lang.org/book/ch10-02-traits.html) * [Rust by Example - Traits](https://doc.rust-lang.org/rust-by-example/trait.html) * [Rust Reference - Provided methods](https://doc.rust-lang.org/reference/items/traits.html#provided-methods) * [`std::iter::Iterator`](https://doc.rust-lang.org/std/iter/trait.Iterator.html) — the canonical “one required method, dozens of defaults” trait ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Trait Methods](/09-generics-traits/04-trait-methods/) — required vs provided methods, calling them, overriding, and the no-`super` rule (read first) * [Traits](/09-generics-traits/03-traits/) — defining and implementing a trait; `impl Trait for Type` * [Trait Bounds](/09-generics-traits/05-trait-bounds/) — `<T: Trait>` and the bounds that power blanket `impl`s * [Generic Functions](/09-generics-traits/00-generic-functions/) — monomorphization vs TypeScript type erasure * [Supertraits](/09-generics-traits/09-supertraits/) — the `: Iterator<...>` supertrait bound used by the extension trait * [Trait Objects](/09-generics-traits/06-trait-objects/) — dynamic dispatch with `&dyn Trait` / `Box<dyn Trait>` when you opt out of monomorphization * [The Orphan Rule](/09-generics-traits/12-orphan-rule/) — what you may and may not implement defaults *for* * [Operator Overloading](/09-generics-traits/10-operator-overloading/) — traits like `Add` that you implement to enable operators * [Getting Started](/01-getting-started/) and [Basics](/02-basics/) — toolchain and syntax foundations * [Smart Pointers](/10-smart-pointers/) — `Box<dyn Trait>` for owning trait objects built from these traits *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: One required method, defaults plus an override [Section titled “Exercise 1: One required method, defaults plus an override”](#exercise-1-one-required-method-defaults-plus-an-override) **Difficulty:** Easy **Objective:** Build a trait whose defaults compose, and override one of them. **Instructions:** Define a `Notifier` trait. `recipient(&self) -> String` is required. `channel(&self) -> &str` is provided and defaults to `"email"`. `notify(&self, msg) -> String` is provided and returns `"[<channel>] -> <recipient>: <msg>"`. Implement `EmailUser` (keeps the default channel) and `SmsUser` (overrides `channel` to `"sms"`). ```rust 1 trait Notifier { 2 fn recipient(&self) -> String; // required 3 fn channel(&self) -> &str { // provided 4 /* ??? */ 5 } 6 fn notify(&self, msg: &str) -> String { // provided 7 // TODO: "[<channel>] -> <recipient>: <msg>" 8 /* ??? */ 9 } 10 } 11 12 // TODO: struct EmailUser; struct SmsUser; + impls 13 14 fn main() { 15 // expected: 16 // [email] -> me@zeybek.dev: deploy finished 17 // [sms] -> +1-555-0100: 2FA code: 4821 18 } ``` Solution ```rust 1 trait Notifier { 2 fn recipient(&self) -> String; 3 fn channel(&self) -> &str { 4 "email" 5 } 6 fn notify(&self, msg: &str) -> String { 7 format!("[{}] -> {}: {}", self.channel(), self.recipient(), msg) 8 } 9 } 10 11 struct EmailUser { 12 addr: String, 13 } 14 impl Notifier for EmailUser { 15 fn recipient(&self) -> String { 16 self.addr.clone() 17 } 18 } 19 20 struct SmsUser { 21 phone: String, 22 } 23 impl Notifier for SmsUser { 24 fn recipient(&self) -> String { 25 self.phone.clone() 26 } 27 fn channel(&self) -> &str { 28 "sms" 29 } 30 } 31 32 fn main() { 33 let e = EmailUser { addr: "me@zeybek.dev".into() }; 34 let s = SmsUser { phone: "+1-555-0100".into() }; 35 println!("{}", e.notify("deploy finished")); 36 println!("{}", s.notify("2FA code: 4821")); 37 } ``` Output: ```text 1 [email] -> me@zeybek.dev: deploy finished 2 [sms] -> +1-555-0100: 2FA code: 4821 ``` `notify` is written once. Because it calls `self.channel()`, overriding `channel` in `SmsUser` automatically changes what `notify` produces; `notify` itself is never touched. ### Exercise 2: Defaults derived from one required getter [Section titled “Exercise 2: Defaults derived from one required getter”](#exercise-2-defaults-derived-from-one-required-getter) **Difficulty:** Medium **Objective:** Practice the required-getter-plus-provided-orchestration pattern that sidesteps Pitfall 1. **Instructions:** Define a `Shape` trait. `area(&self) -> f64` is required. `name(&self) -> &str` is provided and defaults to `"shape"`. `describe(&self) -> String` is provided and returns `"<name> with area <area, 2 decimals>"`. Implement `Circle { r: f64 }` (overrides `name` to `"circle"`) and `UnitSquare` (keeps the default name). Note that neither default reads a field directly; they go through `area()` and `name()`. ```rust 1 trait Shape { 2 fn area(&self) -> f64; // required 3 fn name(&self) -> &str { // provided 4 /* ??? */ 5 } 6 fn describe(&self) -> String { // provided 7 // TODO: "<name> with area <area:.2>" 8 /* ??? */ 9 } 10 } 11 12 // TODO: struct Circle { r: f64 }; struct UnitSquare; + impls 13 14 fn main() { 15 // expected: 16 // circle with area 12.57 17 // shape with area 1.00 18 } ``` Solution ```rust 1 trait Shape { 2 fn area(&self) -> f64; 3 fn name(&self) -> &str { 4 "shape" 5 } 6 fn describe(&self) -> String { 7 format!("{} with area {:.2}", self.name(), self.area()) 8 } 9 } 10 11 struct Circle { 12 r: f64, 13 } 14 impl Shape for Circle { 15 fn area(&self) -> f64 { 16 std::f64::consts::PI * self.r * self.r 17 } 18 fn name(&self) -> &str { 19 "circle" 20 } 21 } 22 23 struct UnitSquare; 24 impl Shape for UnitSquare { 25 fn area(&self) -> f64 { 26 1.0 27 } 28 // keeps default name() == "shape" and default describe() 29 } 30 31 fn main() { 32 println!("{}", Circle { r: 2.0 }.describe()); 33 println!("{}", UnitSquare.describe()); 34 } ``` Output: ```text 1 circle with area 12.57 2 shape with area 1.00 ``` `describe` never touches `self.r`; it calls `self.area()`. That is what keeps the default valid for `UnitSquare`, which has no radius at all. ### Exercise 3: An extension trait via a blanket impl [Section titled “Exercise 3: An extension trait via a blanket impl”](#exercise-3-an-extension-trait-via-a-blanket-impl) **Difficulty:** Medium/Hard **Objective:** Distribute a default API to many types at once with an empty blanket `impl`: the boilerplate-elimination move with no TypeScript equivalent. **Instructions:** Define a `Loggable` trait. `label(&self) -> String` is required. `log_line(&self) -> String` is provided and returns `"LOG: <label>"`. `log_with_level(&self, level) -> String` is provided and returns `"[<LEVEL uppercased>] <label>"`. Implement it for `Order { id, total }` (keeps the default `log_line`) and `Event { kind }` (overrides `log_line` to start with `"LOG* "`). ```rust 1 trait Loggable { 2 fn label(&self) -> String; // required 3 fn log_line(&self) -> String { // provided 4 /* ??? */ 5 } 6 fn log_with_level(&self, level: &str) -> String { // provided 7 /* ??? */ 8 } 9 } 10 11 // TODO: struct Order { id: u32, total: u32 }; struct Event { kind: String }; + impls 12 13 fn main() { 14 // expected: 15 // LOG: order #7 ($42) 16 // [WARN] order #7 ($42) 17 // LOG* event: login 18 // [INFO] event: login 19 } ``` Solution ```rust 1 trait Loggable { 2 // Required: the one-line label for this value. 3 fn label(&self) -> String; 4 5 // Provided defaults that compose, giving a free logging API. 6 fn log_line(&self) -> String { 7 format!("LOG: {}", self.label()) 8 } 9 fn log_with_level(&self, level: &str) -> String { 10 format!("[{}] {}", level.to_uppercase(), self.label()) 11 } 12 } 13 14 struct Order { 15 id: u32, 16 total: u32, 17 } 18 impl Loggable for Order { 19 fn label(&self) -> String { 20 format!("order #{} (${})", self.id, self.total) 21 } 22 } 23 24 struct Event { 25 kind: String, 26 } 27 impl Loggable for Event { 28 fn label(&self) -> String { 29 format!("event: {}", self.kind) 30 } 31 // override the default to add a marker 32 fn log_line(&self) -> String { 33 format!("LOG* {}", self.label()) 34 } 35 } 36 37 fn main() { 38 let o = Order { id: 7, total: 42 }; 39 let e = Event { kind: "login".into() }; 40 println!("{}", o.log_line()); 41 println!("{}", o.log_with_level("warn")); 42 println!("{}", e.log_line()); 43 println!("{}", e.log_with_level("info")); 44 } ``` Output: ```text 1 LOG: order #7 ($42) 2 [WARN] order #7 ($42) 3 LOG* event: login 4 [INFO] event: login ``` `Order` writes only `label` and inherits both logging methods; `Event` overrides one. For the *true* extension-trait move — handing these defaults to every type meeting a bound via `impl<T: SomeBound> Loggable for T {}` with an empty body — see the `NumericExt` example in the Detailed Explanation. Stretch goal: rewrite this so `Loggable` is blanket-implemented for every type that already implements `std::fmt::Display`, using `self.to_string()` as the default `label`. # Supertraits: One Trait Requiring Another > A Rust supertrait (trait Sub: Super) requires implementors to also implement another trait, echoing TypeScript's interface extends as a constraint. In TypeScript you can write `interface Admin extends User`, declaring that every `Admin` is also a `User`. Rust has a parallel idea — a **supertrait** — written `trait Admin: User`. It looks like inheritance, and the colon even reads like `extends`, but underneath it is something more precise: a *requirement*. Saying “`Plugin` has supertrait `Component`” means “you cannot implement `Plugin` for a type unless that type also implements `Component`.” *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **supertrait** is a trait that another trait depends on. When you declare `trait Sub: Super`, you are telling the compiler two things: any type that implements `Sub` *must* also implement `Super`, and the methods of `Super` are available to call from inside `Sub` (including from `Sub`’s default method bodies). It is Rust’s closest analogue to interface inheritance in TypeScript, but it expresses a **constraint on implementors**, not the copying-down of behavior you get from class `extends`. > **Note:** This page covers the supertrait relationship: the `trait A: B` syntax, why it is a requirement rather than inheritance, and how it interacts with generics and trait objects. Defining and implementing traits is in [Traits](/09-generics-traits/03-traits/); the `<T: Trait>` bounds it resembles are in [Trait Bounds](/09-generics-traits/05-trait-bounds/); default method bodies are in [Default Method Implementations](/09-generics-traits/08-default-impls/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript, one interface can extend another. The extending interface gains the parent’s members, and any implementor must satisfy both. ```typescript 1 // TypeScript - an interface that extends another interface 2 interface Component { 3 name(): string; 4 describe(): string; 5 } 6 7 // `Plugin` extends `Component`: a Plugin is also a Component. 8 interface Plugin extends Component { 9 start(): string; 10 bootLog(): string; 11 } 12 13 class Logger implements Plugin { 14 constructor(private level: string) {} 15 16 name(): string { 17 return "logger"; 18 } 19 20 describe(): string { 21 return `component '${this.name()}'`; 22 } 23 24 start(): string { 25 return `logging at level ${this.level}`; 26 } 27 28 // A Plugin method that calls a Component method (`describe`). 29 bootLog(): string { 30 return `booting ${this.describe()} -> ${this.start()}`; 31 } 32 } 33 34 const logger = new Logger("info"); 35 console.log(logger.bootLog()); 36 // booting component 'logger' -> logging at level info ``` **Key points:** * `Plugin extends Component` means `Logger` must satisfy *both* interfaces’ members. * `bootLog` (a `Plugin` member) freely calls `describe` (a `Component` member) — the compiler knows the receiver has both. * Structural typing applies: any object with all four members (`name`, `describe`, `start`, `bootLog`) is a `Plugin`, whether or not it says `implements`. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same plugin shape in idiomatic Rust. The `Component` behavior and the `Plugin` behavior are two separate traits, and `Plugin` declares `Component` as its supertrait with a colon. ```rust 1 // A small plugin system. Every Plugin is first a Component (it has a name and 2 // can describe itself); Plugin adds lifecycle behavior on top. 3 4 trait Component { 5 fn name(&self) -> &str; 6 7 // Provided (default) method using only this trait's required methods. 8 fn describe(&self) -> String { 9 format!("component '{}'", self.name()) 10 } 11 } 12 13 // `Plugin` REQUIRES `Component`: you cannot be a Plugin without being a Component. 14 trait Plugin: Component { 15 fn start(&self) -> String; 16 17 // Provided method that calls a SUPERTRAIT method (`describe`). 18 fn boot_log(&self) -> String { 19 format!("booting {} -> {}", self.describe(), self.start()) 20 } 21 } 22 23 struct Logger { 24 level: String, 25 } 26 27 // We must satisfy the supertrait with its own impl block. 28 impl Component for Logger { 29 fn name(&self) -> &str { 30 "logger" 31 } 32 } 33 34 impl Plugin for Logger { 35 fn start(&self) -> String { 36 format!("logging at level {}", self.level) 37 } 38 } 39 40 fn main() { 41 let logger = Logger { level: String::from("info") }; 42 println!("{}", logger.boot_log()); 43 } ``` **Real output:** ```text 1 booting component 'logger' -> logging at level info ``` > **Note:** The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the **2024 edition**. Create new projects with `cargo new` — it auto-selects the newest edition — so you never need to pin an older one. Everything in this file is verified on a 2024-edition project. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) Let’s walk through the Rust version and contrast each piece with the TypeScript you already know. ### The supertrait declaration [Section titled “The supertrait declaration”](#the-supertrait-declaration) ```rust 1 trait Plugin: Component { 2 fn start(&self) -> String; 3 fn boot_log(&self) -> String { /* ... */ } 4 } ``` The `: Component` after the trait name is the whole feature. Read `trait Plugin: Component` as **“`Plugin` requires `Component`”**, or, if you want the TypeScript mnemonic, “`Plugin` extends `Component`.” `Component` is the **supertrait**; `Plugin` is the **subtrait**. This is the same syntax you would use for a trait bound on a generic (`<T: Component>`). That is not a coincidence: a supertrait *is* a bound, applied to the implementing type itself. The compiler reads `trait Plugin: Component` as “for any `Self` implementing `Plugin`, `Self: Component` must also hold.” ### Two separate `impl` blocks [Section titled “Two separate impl blocks”](#two-separate-impl-blocks) In TypeScript, `class Logger implements Plugin` provides every member of `Plugin` *and* `Component` in a single class body. In Rust the two traits are filled in **separately**: ```rust 1 impl Component for Logger { /* name() ... */ } 2 impl Plugin for Logger { /* start() ... */ } ``` This is the headline difference. A supertrait does **not** fold the parent’s methods into the child trait; each trait keeps its own identity and gets its own `impl` block. You implement `Component for Logger` to satisfy the requirement, then `Plugin for Logger` to add the plugin behavior. Forgetting the first one is a compile error (see Common Pitfalls). ### Calling supertrait methods from a subtrait [Section titled “Calling supertrait methods from a subtrait”](#calling-supertrait-methods-from-a-subtrait) Inside `Plugin`’s default method, this line works: ```rust 1 fn boot_log(&self) -> String { 2 format!("booting {} -> {}", self.describe(), self.start()) 3 } ``` `self.describe()` is a `Component` method, yet we call it from a `Plugin` method. That is the *payoff* of the supertrait relationship: because every `Self: Plugin` is guaranteed to also be `Component`, the compiler lets `Plugin` rely on `Component`’s API. Without the `: Component` bound, `self.describe()` would not type-check — there would be no proof that `Self` has a `describe` method. ### Overriding a default through the chain [Section titled “Overriding a default through the chain”](#overriding-a-default-through-the-chain) Default methods still behave the way [Default Method Implementations](/09-generics-traits/08-default-impls/) describes. A type can override `Component::describe`, and `Plugin::boot_log` will pick up the override because method dispatch resolves on the concrete type: ```rust 1 trait Component { 2 fn name(&self) -> &str; 3 fn describe(&self) -> String { 4 format!("component '{}'", self.name()) 5 } 6 } 7 8 trait Plugin: Component { 9 fn start(&self) -> String; 10 fn boot_log(&self) -> String { 11 format!("booting {} -> {}", self.describe(), self.start()) 12 } 13 } 14 15 struct Metrics { 16 endpoint: String, 17 } 18 19 impl Component for Metrics { 20 fn name(&self) -> &str { 21 "metrics" 22 } 23 // Override the default describe for this type. 24 fn describe(&self) -> String { 25 format!("metrics exporter -> {}", self.endpoint) 26 } 27 } 28 29 impl Plugin for Metrics { 30 fn start(&self) -> String { 31 String::from("scraping every 15s") 32 } 33 } 34 35 fn main() { 36 let m = Metrics { endpoint: String::from("/metrics") }; 37 println!("{}", m.boot_log()); 38 } ``` **Real output:** ```text 1 booting metrics exporter -> /metrics -> scraping every 15s ``` `boot_log` never changed, but it now reports the overridden description, because `self.describe()` dispatches to the `Metrics` implementation. ### Supertraits from the standard library [Section titled “Supertraits from the standard library”](#supertraits-from-the-standard-library) The supertrait does not have to be one you wrote. A very common pattern is requiring a `std` trait like `Display` so your trait’s default methods can format `self`: ```rust 1 use std::fmt::Display; 2 3 // Every Greet type must also be Display. 4 trait Greet: Display { 5 fn greet(&self) -> String { 6 // `self` is guaranteed to be Display, so `{self}` works. 7 format!("Hi from {self}") 8 } 9 } 10 11 struct Bot(u32); 12 13 impl Display for Bot { 14 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { 15 write!(f, "bot#{}", self.0) 16 } 17 } 18 19 impl Greet for Bot {} 20 21 fn main() { 22 println!("{}", Bot(7).greet()); 23 } ``` **Real output:** ```text 1 Hi from bot#7 ``` Note the empty `impl Greet for Bot {}` block: `greet` has a default body that relies entirely on the `Display` supertrait, so there is nothing left to write. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript `interface B extends A` | Rust `trait B: A` | | -------------------------- | -------------------------------------------- | ------------------------------------------------------------------ | | What it means | `B` includes all members of `A` | A type implementing `B` *must also* implement `A` | | Where members are supplied | One class body implements all of `B` and `A` | Separate `impl A for T` and `impl B for T` blocks | | Is behavior inherited? | Members are merged into `B` | No merge — each trait stays distinct; `B` may *call* `A`’s methods | | Multiple parents | `extends A, C` (intersection) | `trait B: A + C` | | Runtime presence | Erased | Real: a `B` bound transitively proves the `A` bound | | Opt-in style | Structural (matching shape is enough) | Nominal (explicit `impl` for each trait) | ### A supertrait is a requirement, not subclassing [Section titled “A supertrait is a requirement, not subclassing”](#a-supertrait-is-a-requirement-not-subclassing) This is the single most important mental adjustment. `trait Plugin: Component` does **not** say “`Plugin` contains `Component`’s methods.” It says “any implementor of `Plugin` is obligated to also implement `Component`.” There is no shared state, no constructor chain, and no method-body copying. Rust has no class inheritance at all. Supertraits express the *only* trait-to-trait relationship there is, and it is a pure constraint plus the permission to call the supertrait’s API. ### The `Self` bound, spelled out [Section titled “The Self bound, spelled out”](#the-self-bound-spelled-out) These two declarations are equivalent in meaning: ```rust 1 trait Plugin: Component { /* ... */ } 2 3 // Same constraint, written as an explicit `where` clause on Self: 4 trait Plugin where Self: Component { /* ... */ } ``` Both say “`Self: Component`.” The colon form is the idiom you will read everywhere; the `where Self:` form occasionally appears when the bound is long or conditional. Seeing them as the same thing demystifies why a supertrait behaves exactly like a trait bound (see [Trait Bounds](/09-generics-traits/05-trait-bounds/)). ### Bounds compose transitively [Section titled “Bounds compose transitively”](#bounds-compose-transitively) If a generic function is bounded by the subtrait, it automatically gets the supertrait’s API too. You do not repeat the bound: ```rust 1 use std::fmt::Display; 2 3 trait Greet: Display { 4 fn greet(&self) -> String { 5 format!("Hi from {self}") 6 } 7 } 8 9 struct Bot(u32); 10 11 impl Display for Bot { 12 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { 13 write!(f, "bot#{}", self.0) 14 } 15 } 16 17 impl Greet for Bot {} 18 19 // One bound (`Greet`) transitively gives us Display too. 20 fn announce<T: Greet>(item: &T) { 21 println!("display: {item}"); // uses the Display supertrait 22 println!("greet: {}", item.greet()); // uses Greet itself 23 } 24 25 fn main() { 26 announce(&Bot(7)); 27 } ``` **Real output:** ```text 1 display: bot#7 2 greet: Hi from bot#7 ``` *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Implementing the subtrait but forgetting the supertrait [Section titled “Pitfall 1: Implementing the subtrait but forgetting the supertrait”](#pitfall-1-implementing-the-subtrait-but-forgetting-the-supertrait) Coming from TypeScript, you might write a single `impl` for the “child” trait and expect the parent to come along. Rust requires an `impl` for the supertrait too, and the error lands on the subtrait `impl`. ```rust 1 use std::fmt; 2 3 trait Person: fmt::Display { 4 fn full_name(&self) -> String; 5 } 6 7 struct Employee { 8 first: String, 9 last: String, 10 } 11 12 // We implement Person but NOT Display, the supertrait. 13 impl Person for Employee { 14 fn full_name(&self) -> String { 15 format!("{} {}", self.first, self.last) 16 } 17 } // does not compile (error[E0277]: `Employee` doesn't implement `Display`) 18 19 fn main() { 20 let e = Employee { first: "Ada".into(), last: "Lovelace".into() }; 21 println!("{}", e.full_name()); 22 } ``` Real compiler error (trimmed to the key lines): ```text 1 error[E0277]: `Employee` doesn't implement `std::fmt::Display` 2 --> src/main.rs:13:17 3 | 4 13 | impl Person for Employee { 5 | ^^^^^^^^ the trait `std::fmt::Display` is not implemented for `Employee` 6 | 7 note: required by a bound in `Person` 8 --> src/main.rs:3:15 9 | 10 3 | trait Person: fmt::Display { 11 | ^^^^^^^^^^^^ required by this bound in `Person` ``` **Fix:** add `impl fmt::Display for Employee { ... }`. The supertrait bound is not satisfied until that separate `impl` exists. ### Pitfall 2: Defining a supertrait method inside the subtrait’s `impl` [Section titled “Pitfall 2: Defining a supertrait method inside the subtrait’s impl”](#pitfall-2-defining-a-supertrait-method-inside-the-subtraits-impl) The biggest “this is not subclassing” trap: trying to supply the supertrait’s method from within the subtrait’s `impl` block, as if the methods had merged. ```rust 1 trait Component { 2 fn name(&self) -> &str; 3 } 4 trait Plugin: Component { 5 fn start(&self) -> String; 6 } 7 8 struct Logger; 9 10 // Only impl Plugin, putting `name` here as if Plugin "contained" it. 11 impl Plugin for Logger { 12 fn name(&self) -> &str { "logger" } // not a Plugin method! 13 fn start(&self) -> String { "go".into() } 14 } // does not compile (error[E0407] and error[E0277]) 15 16 fn main() {} ``` Real compiler error (two errors, key lines shown): ```text 1 error[E0407]: method `name` is not a member of trait `Plugin` 2 --> src/main.rs:12:5 3 | 4 12 | fn name(&self) -> &str { "logger" } // not a Plugin method! 5 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ not a member of trait `Plugin` 6 7 error[E0277]: the trait bound `Logger: Component` is not satisfied 8 --> src/main.rs:11:17 9 | 10 11 | impl Plugin for Logger { 11 | ^^^^^^ the trait `Component` is not implemented for `Logger` ``` **Fix:** put `name` in its own `impl Component for Logger { ... }` block, then keep only `start` in `impl Plugin for Logger`. Each trait gets its own `impl`. ### Pitfall 3: Assuming the supertrait must be in scope to call its methods through the subtrait [Section titled “Pitfall 3: Assuming the supertrait must be in scope to call its methods through the subtrait”](#pitfall-3-assuming-the-supertrait-must-be-in-scope-to-call-its-methods-through-the-subtrait) As with any trait, calling a method requires the trait that *declares* it to be in scope at the call site ([Traits](/09-generics-traits/03-traits/) Pitfall 1). With supertraits this surprises people: if you call a supertrait method (`item.describe()`) on a value you only know to be the subtrait, the **supertrait** must be imported too. The supertrait relationship guarantees the method *exists*, but `use` is still about which trait names are visible. When in doubt, import both traits, or let the compiler’s `help:` line tell you exactly which `use` to add. ### Pitfall 4: Reaching for supertraits when a plain bound would do [Section titled “Pitfall 4: Reaching for supertraits when a plain bound would do”](#pitfall-4-reaching-for-supertraits-when-a-plain-bound-would-do) A supertrait says “*every* implementor of `Sub` must also be `Super`, forever.” That is a strong, permanent coupling baked into the trait definition. If you only need `Super`’s capabilities in one function, prefer a local trait bound there (`fn f<T: Sub + Super>(...)`) instead of welding `Super` onto `Sub` for all time. Use a supertrait only when the relationship is genuinely intrinsic: when a `Sub` makes no sense without being a `Super`. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Use a supertrait only for a real “is-a-prerequisite” relationship [Section titled “Use a supertrait only for a real “is-a-prerequisite” relationship”](#use-a-supertrait-only-for-a-real-is-a-prerequisite-relationship) Add `: Super` when every conceivable implementor of your trait truly must also be the supertrait. For example, a `Widget` that cannot render without first being `Drawable`, or a trait whose default methods need `Display`/`Debug` to format `self`. If the dependency is incidental, keep it as a function-level bound instead. ### Require `std` formatting traits to power default methods [Section titled “Require std formatting traits to power default methods”](#require-std-formatting-traits-to-power-default-methods) Requiring `Display` or `Debug` as a supertrait is a clean, idiomatic pattern: it lets your trait’s default methods format `self` without forcing every implementor to reimplement formatting logic. Many real APIs do this (for instance, `std::error::Error: Debug + Display`). ### Combine multiple supertraits with `+` [Section titled “Combine multiple supertraits with +”](#combine-multiple-supertraits-with-) When a trait needs more than one prerequisite, list them with `+`, exactly like multiple bounds: ```rust 1 use std::fmt::{Debug, Display}; 2 3 // Multiple supertraits joined with `+`, just like multiple bounds. 4 trait Loggable: Debug + Display { 5 fn log_line(&self) -> String { 6 // Both Debug ({:?}) and Display ({}) are guaranteed available. 7 format!("[{self}] (debug: {self:?})") 8 } 9 } 10 11 #[derive(Debug)] 12 struct Order { 13 id: u32, 14 total_cents: u64, 15 } 16 17 impl Display for Order { 18 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { 19 write!(f, "Order #{} = ${:.2}", self.id, self.total_cents as f64 / 100.0) 20 } 21 } 22 23 impl Loggable for Order {} 24 25 fn main() { 26 let o = Order { id: 42, total_cents: 1599 }; 27 println!("{}", o.log_line()); 28 } ``` **Real output:** ```text 1 [Order #42 = $15.99] (debug: Order { id: 42, total_cents: 1599 }) ``` ### Keep the supertrait small [Section titled “Keep the supertrait small”](#keep-the-supertrait-small) A supertrait is a tax every implementor pays. Requiring a tiny, focused supertrait (`Named`, `Display`) is cheap; requiring a sprawling one forces a lot of boilerplate on implementors. This is the interface-segregation instinct from TypeScript, applied to the prerequisite trait. ### Prefer upcasting when you only need the supertrait view [Section titled “Prefer upcasting when you only need the supertrait view”](#prefer-upcasting-when-you-only-need-the-supertrait-view) Since Rust 1.86 (2025), you can **upcast** a trait object from a subtrait to its supertrait: a `&dyn Plugin` can be passed where a `&dyn Component` is expected. Lean on that to write functions against the narrowest trait they actually use. ```rust 1 trait Component { 2 fn name(&self) -> &str; 3 } 4 trait Plugin: Component { 5 fn start(&self) -> String; 6 } 7 8 struct Logger; 9 impl Component for Logger { 10 fn name(&self) -> &str { "logger" } 11 } 12 impl Plugin for Logger { 13 fn start(&self) -> String { "started".into() } 14 } 15 16 // This function only needs the Component view. 17 fn print_name(c: &dyn Component) { 18 println!("component: {}", c.name()); 19 } 20 21 fn main() { 22 let logger = Logger; 23 let p: &dyn Plugin = &logger; 24 print_name(p); // upcast &dyn Plugin -> &dyn Component 25 } ``` **Real output:** ```text 1 component: logger ``` > **Tip:** Before Rust 1.86 this upcast required a manual helper method (often named `as_component`). On current stable it just works. Trait objects and object safety are covered in [Trait Objects and Dynamic Dispatch](/09-generics-traits/06-trait-objects/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A configurable plugin registry, the shape you would find in a build tool or a server’s middleware system. `Component` is the base capability (identity and a self-describing line); `Plugin` builds lifecycle behavior on top. The registry stores a heterogeneous list of plugins as trait objects and boots them all. ```rust 1 // Every Plugin is first a Component; Plugin adds lifecycle on top. 2 trait Component { 3 fn name(&self) -> &str; 4 5 fn describe(&self) -> String { 6 format!("component '{}'", self.name()) 7 } 8 } 9 10 trait Plugin: Component { 11 fn start(&self) -> String; 12 13 // Default method that uses BOTH a supertrait method (`describe`) 14 // and this trait's own method (`start`). 15 fn boot_log(&self) -> String { 16 format!("booting {} -> {}", self.describe(), self.start()) 17 } 18 } 19 20 struct Logger { 21 level: String, 22 } 23 24 struct Metrics { 25 endpoint: String, 26 } 27 28 impl Component for Logger { 29 fn name(&self) -> &str { 30 "logger" 31 } 32 } 33 34 impl Plugin for Logger { 35 fn start(&self) -> String { 36 format!("logging at level {}", self.level) 37 } 38 } 39 40 impl Component for Metrics { 41 fn name(&self) -> &str { 42 "metrics" 43 } 44 // Override the default describe just for this type. 45 fn describe(&self) -> String { 46 format!("metrics exporter -> {}", self.endpoint) 47 } 48 } 49 50 impl Plugin for Metrics { 51 fn start(&self) -> String { 52 String::from("scraping every 15s") 53 } 54 } 55 56 // Works over any Plugin. The supertrait bound transitively guarantees 57 // Component, so `p.name()` (a supertrait method) is callable here. 58 fn boot_all(plugins: &[Box<dyn Plugin>]) { 59 for p in plugins { 60 println!("{:<10} | {}", p.name(), p.boot_log()); 61 } 62 } 63 64 fn main() { 65 let plugins: Vec<Box<dyn Plugin>> = vec![ 66 Box::new(Logger { level: "info".into() }), 67 Box::new(Metrics { endpoint: "/metrics".into() }), 68 ]; 69 boot_all(&plugins); 70 } ``` **Real output:** ```text 1 logger | booting component 'logger' -> logging at level info 2 metrics | booting metrics exporter -> /metrics -> scraping every 15s ``` Three things to highlight. First, `boot_all` is bounded only by `Plugin`, yet it calls `p.name()` — a `Component` method — because the supertrait relationship transitively supplies it. Second, `Metrics` overrides `describe`, and `boot_log` automatically reflects that override through dynamic dispatch. Third, `Vec<Box<dyn Plugin>>` is a heterogeneous list; `Box` is the heap-allocating smart pointer covered in [Section 10: Smart Pointers](/10-smart-pointers/), and the dynamic-dispatch trade-offs are in [Trait Objects and Dynamic Dispatch](/09-generics-traits/06-trait-objects/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Rust Book — Using Supertraits to Require One Trait’s Functionality Within Another Trait](https://doc.rust-lang.org/book/ch20-02-advanced-traits.html#using-supertraits-to-require-one-traits-functionality-within-another-trait) * [The Rust Reference — Supertraits](https://doc.rust-lang.org/reference/items/traits.html#supertraits) * [Rust by Example — Supertraits](https://doc.rust-lang.org/rust-by-example/trait/supertraits.html) * [Rust 1.86 release notes — trait upcasting](https://blog.rust-lang.org/2025/04/03/Rust-1.86.0.html) ### Related sections in this guide [Section titled “Related sections in this guide”](#related-sections-in-this-guide) * [Section 09 overview](/09-generics-traits/): the full map of generics and traits * [Traits](/09-generics-traits/03-traits/): defining and implementing a trait; the `impl Trait for Type` syntax * [Trait Bounds](/09-generics-traits/05-trait-bounds/): `<T: Trait>` bounds, multiple bounds, and `where` clauses (a supertrait *is* a bound on `Self`) * [Trait Methods](/09-generics-traits/04-trait-methods/): required vs provided methods and overriding defaults * [Default Method Implementations](/09-generics-traits/08-default-impls/): default method bodies, which supertraits frequently power * [Trait Objects and Dynamic Dispatch](/09-generics-traits/06-trait-objects/): `&dyn Trait`, object safety, and trait upcasting * [Marker Traits](/09-generics-traits/11-marker-traits/): `Send`/`Sync`/`Copy`, which often appear as supertrait bounds * [Generic Functions](/09-generics-traits/00-generic-functions/): monomorphization vs TypeScript type erasure * [Section 01: Getting Started](/01-getting-started/): `cargo new` and the toolchain * [Section 02: Basics](/02-basics/): types, output, and `format!` * [Section 05: Ownership](/05-ownership/): what `&self` borrows mean * [Section 10: Smart Pointers](/10-smart-pointers/): `Box<dyn Trait>` and heap allocation *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A subtrait that requires a supertrait [Section titled “Exercise 1: A subtrait that requires a supertrait”](#exercise-1-a-subtrait-that-requires-a-supertrait) **Difficulty:** Easy **Objective:** Practice the `trait Sub: Super` syntax and the two-`impl` workflow. **Instructions:** Define a trait `Named` with one required method `name(&self) -> String`. Define a second trait `Animal: Named` with a required method `sound(&self) -> String` and a **provided** method `speak(&self) -> String` that returns `"{name} says {sound}"` by calling both. Implement both traits for a `Dog` struct (name `"Rex"`, sound `"woof"`). In `main`, build a `Dog` and print `speak()`. ```rust 1 trait Named { 2 // TODO: name(&self) -> String 3 } 4 5 trait Animal: Named { 6 // TODO: required sound(&self) -> String 7 // TODO: provided speak(&self) -> String calling self.name() and self.sound() 8 } 9 10 struct Dog; 11 12 // TODO: impl Named for Dog 13 // TODO: impl Animal for Dog 14 15 fn main() { 16 // TODO: build a Dog, print speak() 17 } ``` Solution ```rust 1 trait Named { 2 fn name(&self) -> String; 3 } 4 5 trait Animal: Named { 6 fn sound(&self) -> String; 7 8 fn speak(&self) -> String { 9 format!("{} says {}", self.name(), self.sound()) 10 } 11 } 12 13 struct Dog; 14 15 impl Named for Dog { 16 fn name(&self) -> String { 17 String::from("Rex") 18 } 19 } 20 21 impl Animal for Dog { 22 fn sound(&self) -> String { 23 String::from("woof") 24 } 25 } 26 27 fn main() { 28 let d = Dog; 29 println!("{}", d.speak()); 30 } ``` **Output:** ```text 1 Rex says woof ``` Note that `Named` needs its own `impl` block; `Animal`’s `impl` cannot supply `name`. That separation is the heart of supertraits. ### Exercise 2: A supertrait from the standard library [Section titled “Exercise 2: A supertrait from the standard library”](#exercise-2-a-supertrait-from-the-standard-library) **Difficulty:** Medium **Objective:** Require `Display` as a supertrait so a default method can format `self`. **Instructions:** Define a trait `Priced: Display` with a required method `price_cents(&self) -> u64` and a provided method `receipt(&self) -> String` that prints `"{self}: $X.XX"` (dollars to two decimals). Implement `Display` and `Priced` for a `Coffee { size: String }` where `"small"` costs `350`, `"large"` costs `525`, and anything else costs `450`. In `main`, print the receipt for a large coffee. ```rust 1 use std::fmt::Display; 2 3 trait Priced: Display { 4 // TODO: required price_cents(&self) -> u64 5 // TODO: provided receipt(&self) -> String using "{self}" and price_cents() 6 } 7 8 struct Coffee { 9 size: String, 10 } 11 12 // TODO: impl Display for Coffee (e.g. "large coffee") 13 // TODO: impl Priced for Coffee 14 15 fn main() { 16 // TODO: print the receipt for a "large" coffee 17 } ``` Solution ```rust 1 use std::fmt::Display; 2 3 trait Priced: Display { 4 fn price_cents(&self) -> u64; 5 6 fn receipt(&self) -> String { 7 format!("{self}: ${:.2}", self.price_cents() as f64 / 100.0) 8 } 9 } 10 11 struct Coffee { 12 size: String, 13 } 14 15 impl Display for Coffee { 16 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { 17 write!(f, "{} coffee", self.size) 18 } 19 } 20 21 impl Priced for Coffee { 22 fn price_cents(&self) -> u64 { 23 match self.size.as_str() { 24 "small" => 350, 25 "large" => 525, 26 _ => 450, 27 } 28 } 29 } 30 31 fn main() { 32 let c = Coffee { size: String::from("large") }; 33 println!("{}", c.receipt()); 34 } ``` **Output:** ```text 1 large coffee: $5.25 ``` The `{self}` in `receipt` only works because `Priced: Display` guarantees every implementor is also `Display`. ### Exercise 3: Multiple supertraits behind a generic bound [Section titled “Exercise 3: Multiple supertraits behind a generic bound”](#exercise-3-multiple-supertraits-behind-a-generic-bound) **Difficulty:** Hard **Objective:** Combine multiple supertraits (`Debug + Display`) and consume the subtrait through a generic function, relying on the bound transitively supplying both supertraits. **Instructions:** Define a trait `Serialize: Debug + Display` with a provided method `to_record(&self) -> String` that returns `"{self} | {self:?}"` (Display then Debug). Implement `Display` for a `User { id: u32, handle: String }` (format `"@handle (#id)"`), derive `Debug`, and give it an empty `impl Serialize for User {}`. Write a generic function `dump<T: Serialize>(item: &T)` that prints `item.to_record()`. In `main`, dump a user. ```rust 1 use std::fmt::{Debug, Display}; 2 3 trait Serialize: Debug + Display { 4 // TODO: provided to_record(&self) -> String returning "{self} | {self:?}" 5 } 6 7 // TODO: derive Debug, define User { id: u32, handle: String } 8 // TODO: impl Display for User -> "@handle (#id)" 9 // TODO: impl Serialize for User 10 11 fn dump<T: Serialize>(item: &T) { 12 // TODO: print item.to_record() 13 } 14 15 fn main() { 16 // TODO: build a User and dump it 17 } ``` Solution ```rust 1 use std::fmt::{Debug, Display}; 2 3 trait Serialize: Debug + Display { 4 fn to_record(&self) -> String { 5 format!("{self} | {self:?}") 6 } 7 } 8 9 #[derive(Debug)] 10 struct User { 11 id: u32, 12 handle: String, 13 } 14 15 impl Display for User { 16 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { 17 write!(f, "@{} (#{})", self.handle, self.id) 18 } 19 } 20 21 impl Serialize for User {} 22 23 // Generic over any Serialize; the bound transitively guarantees Display + Debug. 24 fn dump<T: Serialize>(item: &T) { 25 println!("{}", item.to_record()); 26 } 27 28 fn main() { 29 let u = User { id: 1, handle: String::from("ada") }; 30 dump(&u); 31 } ``` **Output:** ```text 1 @ada (#1) | User { id: 1, handle: "ada" } ``` `dump` is bounded only by `Serialize`, yet `to_record` uses both `{self}` (Display) and `{self:?}` (Debug). The single `T: Serialize` bound carries both supertraits with it — no need to repeat `+ Display + Debug` on the function. # Operator Overloading > Rust operators are trait methods: a + b means a.add(b), so implementing Add, Mul, or Index opts your types into syntax JS and TS never let you touch. In TypeScript and JavaScript, `+`, `-`, `*`, and `[]` are baked into the language: you cannot teach `+` how to add two of your own objects. Rust takes the opposite stance. Every operator is sugar for a **trait method**, so `a + b` literally means `a.add(b)`, and you opt your own types into that syntax by implementing the right trait. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Rust’s arithmetic, comparison, and indexing operators are defined by traits in the standard library’s `std::ops` (and `std::cmp`) modules. Implementing `Add` for your `Vector` type makes `v1 + v2` compile; implementing `Index` makes `matrix[(row, col)]` work. This matters to a TypeScript/JavaScript developer because it removes a whole class of awkward `.add()` / `.times()` method chains and lets numeric, geometric, and money types read like the math they model, while the compiler still enforces exact types and ownership. > **Note:** Rust does **not** let you invent brand-new operators or change an operator’s precedence/associativity. You can only give existing operators (`+`, `-`, `*`, `/`, `%`, `&`, `|`, `^`, `<<`, `>>`, unary `-`, unary `!`, `[]`) new meanings for your own types. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In JavaScript there is no operator overloading. The closest you get is naming methods like `add` and `scale`, then calling them explicitly. The `+` operator on objects does something, but almost never what you want. ```typescript 1 // TypeScript - a 2D vector with explicit methods (no operator overloading) 2 class Vector2 { 3 x: number; 4 y: number; 5 6 constructor(x: number, y: number) { 7 this.x = x; 8 this.y = y; 9 } 10 11 add(other: Vector2): Vector2 { 12 return new Vector2(this.x + other.x, this.y + other.y); 13 } 14 15 scale(s: number): Vector2 { 16 return new Vector2(this.x * s, this.y * s); 17 } 18 19 toString(): string { 20 return `(${this.x}, ${this.y})`; 21 } 22 } 23 24 const a = new Vector2(1, 2); 25 const b = new Vector2(3, 4); 26 27 console.log(`a.add(b) = ${a.add(b)}`); 28 console.log(`a.scale(2) = ${a.scale(2)}`); 29 30 // What does `+` actually do to two objects? 31 console.log("a + b =", (a as unknown as number) + (b as unknown as number)); ``` Running this under Node v22 prints: ```text 1 a.add(b) = (4, 6) 2 a.scale(2) = (2, 4) 3 a + b = (1, 2)(3, 4) ``` **Key points:** * You must write and call `a.add(b)`; there is no way to make `a + b` mean vector addition. * `a + b` does not error; JavaScript coerces both objects to strings via `toString()` and **concatenates** them, giving the surprising `"(1, 2)(3, 4)"`. If `toString()` were absent you would get `"[object Object][object Object]"`. Either way it is a silent bug, not a type error. * TypeScript’s type system cannot rescue you here: `+` on two `Vector2` values is a type error, so the example above needs an `as unknown as number` cast to even compile — exactly the kind of escape hatch that hides the runtime nonsense. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) In Rust, `+` is sugar for the `Add` trait. Implement `Add` for `Vector2` and `a + b` simply works, with full type checking and zero runtime surprises. ```rust 1 // Rust - a 2D vector that supports the `+` operator 2 use std::ops::Add; 3 4 #[derive(Debug, Clone, Copy, PartialEq)] 5 struct Vector2 { 6 x: f64, 7 y: f64, 8 } 9 10 impl Add for Vector2 { 11 type Output = Vector2; // the result type of `self + rhs` 12 13 fn add(self, other: Vector2) -> Vector2 { 14 Vector2 { 15 x: self.x + other.x, 16 y: self.y + other.y, 17 } 18 } 19 } 20 21 fn main() { 22 let a = Vector2 { x: 1.0, y: 2.0 }; 23 let b = Vector2 { x: 3.0, y: 4.0 }; 24 25 let c = a + b; // desugars to Add::add(a, b) 26 println!("{:?}", c); 27 println!("equal? {}", c == Vector2 { x: 4.0, y: 6.0 }); 28 } ``` Real output from `cargo run`: ```text 1 Vector2 { x: 4.0, y: 6.0 } 2 equal? true ``` **Key points:** * `a + b` is rewritten by the compiler to `Add::add(a, b)`. The operator is just a method call with nice syntax. * `type Output = Vector2;` is an **associated type**: it names what `+` returns. It does not have to be `Self` (e.g. `Vector2 * f64` can return `Vector2`, and a dot-product could return `f64`). * The `#[derive(PartialEq)]` is what makes `==` work — comparison operators come from `std::cmp`, separate from arithmetic. More on that below. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Operators are traits [Section titled “Operators are traits”](#operators-are-traits) Every overloadable operator maps to one trait method. Here is the core table: | Operator | Trait (`std::ops` unless noted) | Method | | ------------- | ------------------------------- | ------------ | | `a + b` | `Add` | `add` | | `a - b` | `Sub` | `sub` | | `a * b` | `Mul` | `mul` | | `a / b` | `Div` | `div` | | `a % b` | `Rem` | `rem` | | `-a` | `Neg` | `neg` | | `!a` | `Not` | `not` | | `a += b` | `AddAssign` | `add_assign` | | `a -= b` | `SubAssign` | `sub_assign` | | `a & b` | `BitAnd` | `bitand` | | `a \| b` | `BitOr` | `bitor` | | `a ^ b` | `BitXor` | `bitxor` | | `a << b` | `Shl` | `shl` | | `a >> b` | `Shr` | `shr` | | `a[i]` (read) | `Index` | `index` | | `a[i] = v` | `IndexMut` | `index_mut` | | `a == b` | `PartialEq` (`std::cmp`) | `eq` | | `a < b` | `PartialOrd` (`std::cmp`) | `lt` | > The comparison operators (`<`, `>`, `<=`, `>=`) each desugar to `lt`/`gt`/`le`/`ge`. Those have default bodies built on `partial_cmp`, the trait’s single *required* method, so you normally implement only `partial_cmp` (or `#[derive(PartialOrd)]`) and get all four operators for free. When you write `a + b`, the compiler resolves it to `<TypeOfA as Add<TypeOfB>>::add(a, b)`. If no matching `Add` impl exists, you get a compile error — never a silent string concatenation. ### Walking through the `Add` impl [Section titled “Walking through the Add impl”](#walking-through-the-add-impl) ```rust 1 use std::ops::Add; 2 3 impl Add for Vector2 { 4 type Output = Vector2; 5 fn add(self, other: Vector2) -> Vector2 { /* ... */ } 6 } ``` * `impl Add for Vector2` is shorthand for `impl Add<Vector2> for Vector2`. `Add` has a generic parameter `Rhs` (the right-hand side) that **defaults to `Self`**, so for same-type addition you can omit it. * `type Output` is the associated type that the `add` method returns. * `fn add(self, other: Vector2)` takes `self` **by value**: it consumes both operands. For `Copy` types like `Vector2` (note the `#[derive(Copy)]`) this is free; for owned types like `String` or `Vec`, this means `a + b` *moves* `a` and `b`. We address that in Common Pitfalls. ### A different right-hand side: scaling by a scalar [Section titled “A different right-hand side: scaling by a scalar”](#a-different-right-hand-side-scaling-by-a-scalar) `Add` defaults `Rhs` to `Self`, but you can set `Rhs` to a different type. A common case is multiplying a vector by a scalar `f64`: ```rust 1 use std::ops::Mul; 2 3 #[derive(Debug, Clone, Copy, PartialEq)] 4 struct Vector2 { 5 x: f64, 6 y: f64, 7 } 8 9 // Vector2 * f64 -> Vector2 10 impl Mul<f64> for Vector2 { 11 type Output = Vector2; 12 fn mul(self, scalar: f64) -> Vector2 { 13 Vector2 { x: self.x * scalar, y: self.y * scalar } 14 } 15 } 16 17 // f64 * Vector2 -> Vector2 (the operands flipped) 18 impl Mul<Vector2> for f64 { 19 type Output = Vector2; 20 fn mul(self, v: Vector2) -> Vector2 { 21 Vector2 { x: self * v.x, y: self * v.y } 22 } 23 } 24 25 fn main() { 26 let v = Vector2 { x: 1.0, y: 2.0 }; 27 println!("v * 2.0 = {:?}", v * 2.0); 28 println!("2.0 * v = {:?}", 2.0 * v); 29 } ``` Output: ```text 1 v * 2.0 = Vector2 { x: 2.0, y: 4.0 } 2 2.0 * v = Vector2 { x: 2.0, y: 4.0 } ``` > **Important:** `v * 2.0` and `2.0 * v` are **two different impls**. Operators are not automatically commutative: `a * b` only resolves to `Mul::mul(a, b)`, never `Mul::mul(b, a)`. If you want both orders, you write both impls (the left-hand operand’s type owns the impl, which is why `impl Mul<Vector2> for f64` lives “on” `f64`). ### Compound assignment, negation, and indexing [Section titled “Compound assignment, negation, and indexing”](#compound-assignment-negation-and-indexing) The assignment operators take `&mut self` and return `()`. Unary `-` is `Neg`. Indexing returns a *reference* so the compiler can also support `a[i] = v` through `IndexMut`. Here they are together: ```rust 1 use std::ops::{AddAssign, Neg, Index, IndexMut}; 2 3 #[derive(Debug, Clone, Copy, PartialEq)] 4 struct Vector2 { 5 x: f64, 6 y: f64, 7 } 8 9 impl AddAssign for Vector2 { 10 fn add_assign(&mut self, rhs: Vector2) { 11 self.x += rhs.x; 12 self.y += rhs.y; 13 } 14 } 15 16 impl Neg for Vector2 { 17 type Output = Vector2; 18 fn neg(self) -> Vector2 { 19 Vector2 { x: -self.x, y: -self.y } 20 } 21 } 22 23 // Read access: `v[0]` and `v[1]` 24 impl Index<usize> for Vector2 { 25 type Output = f64; 26 fn index(&self, i: usize) -> &f64 { 27 match i { 28 0 => &self.x, 29 1 => &self.y, 30 _ => panic!("Vector2 index out of range: {i}"), 31 } 32 } 33 } 34 35 // Write access: `v[0] = ...` 36 impl IndexMut<usize> for Vector2 { 37 fn index_mut(&mut self, i: usize) -> &mut f64 { 38 match i { 39 0 => &mut self.x, 40 1 => &mut self.y, 41 _ => panic!("Vector2 index out of range: {i}"), 42 } 43 } 44 } 45 46 fn main() { 47 let mut v = Vector2 { x: 1.0, y: 2.0 }; 48 v += Vector2 { x: 10.0, y: 20.0 }; 49 println!("after += : {:?}", v); 50 println!("negated : {:?}", -v); 51 println!("v[0] = {}, v[1] = {}", v[0], v[1]); 52 v[0] = 99.0; 53 println!("after v[0] = 99: {:?}", v); 54 } ``` Output: ```text 1 after += : Vector2 { x: 11.0, y: 22.0 } 2 negated : Vector2 { x: -11.0, y: -22.0 } 3 v[0] = 11, v[1] = 22 4 after v[0] = 99: Vector2 { x: 99.0, y: 22.0 } ``` > **Note:** `Index::index` returns `&Self::Output`, not `Self::Output`. That reference is what lets `v[0]` be used both for reading and (via `IndexMut`) as the target of an assignment. This is the same machinery `Vec<T>` and `HashMap<K, V>` use — see [the collections section](/07-collections/). ### Comparison operators are a separate family [Section titled “Comparison operators are a separate family”](#comparison-operators-are-a-separate-family) `==`, `!=`, `<`, `>`, `<=`, `>=` are **not** in `std::ops`. They come from `PartialEq`/`Eq` and `PartialOrd`/`Ord` in `std::cmp`. You almost never hand-write these; you `#[derive(...)]` them: ```rust 1 #[derive(PartialEq, Eq, PartialOrd, Ord)] 2 struct Version { 3 major: u32, 4 minor: u32, 5 } ``` `#[derive(PartialEq)]` gives you `==`/`!=`; `#[derive(PartialOrd)]` gives you `<`/`>`/`<=`/`>=` using lexicographic field order. This is why the very first `Vector2` example could write `c == Vector2 { .. }` after only deriving `PartialEq`. (Floating point gets `PartialEq`/`PartialOrd` but not `Eq`/`Ord`, because `NaN != NaN`.) *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | TypeScript / JavaScript | Rust | | ------------------------ | ------------------------------------------ | ------------------------------------------------------ | | Custom `+` on your types | Impossible; use named methods (`a.add(b)`) | Implement the `Add` trait; `a + b` just works | | `+` on two objects | Silent coercion to strings (`toString`) | Compile error unless an `Add` impl exists | | What an operator *is* | Built-in syntax | Sugar for a trait method (`a + b` == `Add::add(a, b)`) | | Result type | Always whatever JS coercion produces | Chosen by you via the `Output` associated type | | Commutativity | N/A | Not automatic — `a * b` and `b * a` are separate impls | | Equality (`==`) | `===` compares references for objects | `==` uses your `PartialEq` impl (value equality) | | Invent new operators | No | No; only existing operators can be overloaded | | Where you can implement | N/A | Subject to the **orphan rule** (see below) | ### Why design it this way? [Section titled “Why design it this way?”](#why-design-it-this-way) Rust’s “operators are traits” model is the same idea as TypeScript’s “iterables implement `Symbol.iterator`,” generalized to every operator. It means the language core stays tiny, your numeric types are first-class citizens (a `BigDecimal` from a crate adds with `+` exactly like `i32` does), and generic code can be written over “anything that supports `+`” via the bound `T: Add<Output = T>`: ```rust 1 use std::ops::Add; 2 3 #[derive(Debug, Clone, Copy, PartialEq)] 4 struct Point<T> { 5 x: T, 6 y: T, 7 } 8 9 // `+` works for any component type T that itself supports `+` 10 impl<T: Add<Output = T>> Add for Point<T> { 11 type Output = Point<T>; 12 fn add(self, rhs: Point<T>) -> Point<T> { 13 Point { x: self.x + rhs.x, y: self.y + rhs.y } 14 } 15 } 16 17 fn main() { 18 println!("{:?}", Point { x: 1, y: 2 } + Point { x: 3, y: 4 }); 19 println!("{:?}", Point { x: 1.5, y: 2.5 } + Point { x: 0.5, y: 0.5 }); 20 } ``` Output: ```text 1 Point { x: 4, y: 6 } 2 Point { x: 2.0, y: 3.0 } ``` That `T: Add<Output = T>` is a **trait bound**. The broader story of bounds lives in [Trait Bounds](/09-generics-traits/05-trait-bounds/), and generic structs like `Point<T>` are covered in [Generic Structs](/09-generics-traits/01-generic-structs/). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting that `add(self, ...)` *moves* its operands [Section titled “Pitfall 1: Forgetting that add(self, ...) moves its operands”](#pitfall-1-forgetting-that-addself--moves-its-operands) For non-`Copy` types, `a + b` consumes both `a` and `b`. Reusing them afterward fails to compile. ```rust 1 use std::ops::Add; 2 3 #[derive(Debug)] 4 struct Money { 5 cents: i64, 6 } 7 8 impl Add for Money { 9 type Output = Money; 10 fn add(self, rhs: Money) -> Money { 11 Money { cents: self.cents + rhs.cents } 12 } 13 } 14 15 fn main() { 16 let a = Money { cents: 100 }; 17 let b = Money { cents: 250 }; 18 let total = a + b; 19 println!("{:?}", total); 20 println!("{:?}", a); // does not compile (error[E0382]: borrow of moved value: `a`) 21 } ``` The real compiler error: ```text 1 error[E0382]: borrow of moved value: `a` 2 --> src/main.rs:20:22 3 | 4 16 | let a = Money { cents: 100 }; 5 | - move occurs because `a` has type `Money`, which does not implement the `Copy` trait 6 ... 7 18 | let total = a + b; 8 | ----- `a` moved due to usage in operator 9 19 | println!("{:?}", total); 10 20 | println!("{:?}", a); // does not compile (error[E0382]: borrow of moved value: `a`) 11 | ^ value borrowed here after move 12 | 13 note: calling this operator moves the left-hand side ``` **Fixes:** derive `Clone`/`Copy` if the type is small and cheap, or implement the operator on **references** so it borrows instead of moves: ```rust 1 use std::ops::Add; 2 3 #[derive(Debug)] 4 struct Matrix { 5 data: Vec<f64>, 6 } 7 8 // `&Matrix + &Matrix` borrows both operands; they survive the call 9 impl Add for &Matrix { 10 type Output = Matrix; 11 fn add(self, rhs: &Matrix) -> Matrix { 12 let data = self.data.iter().zip(&rhs.data).map(|(a, b)| a + b).collect(); 13 Matrix { data } 14 } 15 } 16 17 fn main() { 18 let a = Matrix { data: vec![1.0, 2.0] }; 19 let b = Matrix { data: vec![3.0, 4.0] }; 20 let c = &a + &b; // borrow, don't move 21 println!("{:?}", c.data); 22 println!("a still usable: {:?}", a.data); 23 println!("b still usable: {:?}", b.data); 24 } ``` Output: ```text 1 [4.0, 6.0] 2 a still usable: [1.0, 2.0] 3 b still usable: [3.0, 4.0] ``` The standard library does both: it implements `Add` for `i32` (Copy, by value) *and* for `&i32`. Mirroring that for your own owned types is idiomatic. (Ownership and the move-vs-borrow distinction are the subject of [Section 05: Ownership](/05-ownership/).) ### Pitfall 2: Assuming `a * b` implies `b * a` [Section titled “Pitfall 2: Assuming a \* b implies b \* a”](#pitfall-2-assuming-a--b-implies-b--a) If you only write `impl Mul<f64> for Vector2`, then `2.0 * v` does **not** compile, because that would need `impl Mul<Vector2> for f64`: ```rust 1 use std::ops::Mul; 2 3 #[derive(Debug, Clone, Copy)] 4 struct Vector2 { x: f64, y: f64 } 5 6 impl Mul<f64> for Vector2 { 7 type Output = Vector2; 8 fn mul(self, s: f64) -> Vector2 { 9 Vector2 { x: self.x * s, y: self.y * s } 10 } 11 } 12 13 fn main() { 14 let v = Vector2 { x: 1.0, y: 2.0 }; 15 let r = 2.0 * v; // does not compile (error[E0277]: cannot multiply `{float}` by `Vector2`) 16 println!("{:?}", r); 17 } ``` Real error: ```text 1 error[E0277]: cannot multiply `{float}` by `Vector2` 2 --> src/main.rs:16:17 3 | 4 16 | let r = 2.0 * v; // scalar on the left: no impl 5 | ^ no implementation for `{float} * Vector2` 6 | 7 = help: the trait `Mul<Vector2>` is not implemented for `{float}` ``` **Fix:** add the second impl (`impl Mul<Vector2> for f64`), as shown earlier. ### Pitfall 3: Trying to implement a foreign operator trait for a foreign type (orphan rule) [Section titled “Pitfall 3: Trying to implement a foreign operator trait for a foreign type (orphan rule)”](#pitfall-3-trying-to-implement-a-foreign-operator-trait-for-a-foreign-type-orphan-rule) You cannot `impl Add for String` (or any other standard type): both `Add` and `String` belong to other crates. ```rust 1 use std::ops::Add; 2 3 impl Add<i32> for String { // does not compile (error[E0117]) 4 type Output = String; 5 fn add(self, n: i32) -> String { 6 format!("{self}{n}") 7 } 8 } 9 10 fn main() {} ``` Real error: ```text 1 error[E0117]: only traits defined in the current crate can be implemented for types defined outside of the crate 2 --> src/main.rs:3:1 3 | 4 3 | impl Add<i32> for String { 5 | ^^^^^--------^^^^^------ 6 | | | 7 | | `String` is not defined in the current crate 8 | `i32` is not defined in the current crate 9 | 10 = note: define and implement a trait or new type instead ``` **Fix:** wrap the foreign type in a **newtype** (`struct MyString(String);`) and implement the operator on *that*. The coherence rules behind this — and the newtype pattern — are covered in depth in [The Orphan Rule and Coherence](/09-generics-traits/12-orphan-rule/). ### Pitfall 4: Reaching for operator overloading when a method is clearer [Section titled “Pitfall 4: Reaching for operator overloading when a method is clearer”](#pitfall-4-reaching-for-operator-overloading-when-a-method-is-clearer) Operators should preserve their intuitive meaning. Overloading `*` to mean “repeat a task N times” or `+` to mean “merge configs” makes code unreadable; a maintainer expects arithmetic-like semantics. Use a named method (`config.merge(other)`) unless your type genuinely models something `+` already describes (vectors, money, durations, matrices, complex numbers). *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Only overload operators with their conventional meaning.** `+` should be addition-like, `*` multiplication-like. If the operator would surprise a reader, write a named method instead. * **Set the `Output` type deliberately.** It is often `Self`, but not always — a dot product `Vector · Vector` returns a scalar, so its `Output` is `f64`, not `Vector`. * **Implement both by-value and by-reference variants for owned types.** Provide `impl Add for &T` (and combinations) so callers are not forced to clone, matching how `i32`/`&i32` behave in std. * **Keep `AddAssign` and `Add` consistent.** If you offer `+`, also offer `+=` when it makes sense; users expect `a += b` to match `a = a + b`. * **Derive comparison traits; don’t hand-roll them.** `#[derive(PartialEq, Eq, PartialOrd, Ord, Hash)]` is correct and exhaustive far more often than a manual `impl`. * **Add `#[derive(Clone, Copy)]` to small value types** (vectors, points, money-as-i64) so `a + b` is cheap and ownership never gets in the way. * **Reach for crates instead of reinventing math.** For arbitrary-precision decimals use `rust_decimal`; for linear algebra use `nalgebra` or `glam`. They implement all the operator traits idiomatically. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A currency-safe `Money` type, stored as integer cents to avoid floating-point rounding errors, that supports `+`, `-`, `* quantity`, and `.sum()` over an iterator. This is the kind of value object you would put at the heart of a billing or checkout service. ```rust 1 use std::iter::Sum; 2 use std::ops::{Add, Mul, Sub}; 3 4 /// Money stored as integer cents to avoid floating-point rounding errors. 5 #[derive(Debug, Clone, Copy, PartialEq, Eq)] 6 struct Money { 7 cents: i64, 8 } 9 10 impl Money { 11 fn dollars(d: i64) -> Self { 12 Money { cents: d * 100 } 13 } 14 } 15 16 impl Add for Money { 17 type Output = Money; 18 fn add(self, rhs: Money) -> Money { 19 Money { cents: self.cents + rhs.cents } 20 } 21 } 22 23 impl Sub for Money { 24 type Output = Money; 25 fn sub(self, rhs: Money) -> Money { 26 Money { cents: self.cents - rhs.cents } 27 } 28 } 29 30 // Scale a unit price by an integer quantity: price * qty 31 impl Mul<i64> for Money { 32 type Output = Money; 33 fn mul(self, qty: i64) -> Money { 34 Money { cents: self.cents * qty } 35 } 36 } 37 38 // Lets `iter.sum()` produce a Money total 39 impl Sum for Money { 40 fn sum<I: Iterator<Item = Money>>(iter: I) -> Money { 41 iter.fold(Money { cents: 0 }, |acc, m| acc + m) 42 } 43 } 44 45 impl std::fmt::Display for Money { 46 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { 47 let sign = if self.cents < 0 { "-" } else { "" }; 48 let abs = self.cents.abs(); 49 write!(f, "{sign}${}.{:02}", abs / 100, abs % 100) 50 } 51 } 52 53 struct LineItem { 54 name: &'static str, 55 price: Money, 56 qty: i64, 57 } 58 59 impl LineItem { 60 fn subtotal(&self) -> Money { 61 self.price * self.qty // uses our Mul<i64> impl 62 } 63 } 64 65 fn main() { 66 let cart = [ 67 LineItem { name: "Keyboard", price: Money::dollars(80), qty: 1 }, 68 LineItem { name: "Cable", price: Money { cents: 1299 }, qty: 3 }, 69 ]; 70 71 for item in &cart { 72 println!( 73 "{:<10} {} x{} = {}", 74 item.name, 75 item.price, 76 item.qty, 77 item.subtotal() 78 ); 79 } 80 81 let total: Money = cart.iter().map(|i| i.subtotal()).sum(); // uses Sum 82 let discount = Money::dollars(10); 83 println!("Subtotal: {total}"); 84 println!("After {discount} discount: {}", total - discount); // uses Sub 85 } ``` Output from `cargo run`: ```text 1 Keyboard $80.00 x1 = $80.00 2 Cable $12.99 x3 = $38.97 3 Subtotal: $118.97 4 After $10.00 discount: $108.97 ``` Notice how `price * qty`, `cart.iter()...sum()`, and `total - discount` all read like ordinary arithmetic, yet `Money` can only ever be combined with other `Money` (or scaled by an `i64`) — you cannot accidentally add a `Money` to a bare `i64`, which is precisely the class of bug that floating-point dollars and untyped `number` invite. > **Tip:** In a real production service you would also consider overflow. The std arithmetic used inside these impls panics on overflow in debug builds and wraps in release builds; for money, prefer the checked variants (`self.cents.checked_add(rhs.cents)`) and return a `Result`. See [Section 08: Error Handling](/08-error-handling/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [`std::ops` module](https://doc.rust-lang.org/std/ops/index.html) — every arithmetic, bitwise, indexing, and assignment operator trait * [`std::ops::Add`](https://doc.rust-lang.org/std/ops/trait.Add.html) and [`std::ops::Index`](https://doc.rust-lang.org/std/ops/trait.Index.html) — the canonical examples, with the `Rhs`/`Output` story * [`std::cmp::PartialEq`](https://doc.rust-lang.org/std/cmp/trait.PartialEq.html) and [`std::cmp::PartialOrd`](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html) — the traits behind `==` and `<` * [The Rust Book — Operator Overloading](https://doc.rust-lang.org/book/ch10-02-traits.html#default-implementations) and [Advanced Traits: associated types & default generic params](https://doc.rust-lang.org/book/ch20-02-advanced-traits.html#default-generic-type-parameters-and-operator-overloading) * [Rust by Example — Operator Overloading](https://doc.rust-lang.org/rust-by-example/trait/ops.html) ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Traits](/09-generics-traits/03-traits/): how to define and implement a trait; the `impl Trait for Type` syntax that operator traits build on * [Trait Methods](/09-generics-traits/04-trait-methods/): required vs. provided methods (operator traits like `Add` are pure required-method traits) * [Trait Bounds](/09-generics-traits/05-trait-bounds/): the `T: Add<Output = T>` bound used in the generic `Point<T>` example * [Generic Structs](/09-generics-traits/01-generic-structs/): building generic value types like `Point<T>` that you then add operators to * [The Orphan Rule and Coherence](/09-generics-traits/12-orphan-rule/): why `impl Add for String` is rejected, and the newtype workaround * [Marker Traits](/09-generics-traits/11-marker-traits/): `Copy`, which decides whether `a + b` moves or copies its operands * [Section 02: Operators](/02-basics/02-operators/): the built-in operator behavior these traits extend * [Section 05: Ownership](/05-ownership/): why `add(self, ...)` consumes its operands, and when to implement on references * [Section 07: Collections](/07-collections/): `Vec`/`HashMap` indexing, the most common real-world `Index` users * [Section 10: Smart Pointers](/10-smart-pointers/): `Deref`/`DerefMut`, the operator-like traits behind `*` on `Box`, `Rc`, and friends *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A complex number type [Section titled “Exercise 1: A complex number type”](#exercise-1-a-complex-number-type) **Difficulty:** Beginner **Objective:** Implement `Add` and `Mul` for a complex number so `a + b` and `a * b` work. **Instructions:** Define `struct Complex { re: f64, im: f64 }`. Implement `Add` (component-wise) and `Mul` (using `(a+bi)(c+di) = (ac - bd) + (ad + bc)i`). Add a `Display` impl so `1+2i` prints nicely, then print `a + b` and `a * b` for `a = 1 + 2i` and `b = 3 - 1i`. Solution ```rust 1 use std::ops::{Add, Mul}; 2 3 #[derive(Debug, Clone, Copy, PartialEq)] 4 struct Complex { 5 re: f64, 6 im: f64, 7 } 8 9 impl Add for Complex { 10 type Output = Complex; 11 fn add(self, rhs: Complex) -> Complex { 12 Complex { re: self.re + rhs.re, im: self.im + rhs.im } 13 } 14 } 15 16 impl Mul for Complex { 17 type Output = Complex; 18 fn mul(self, rhs: Complex) -> Complex { 19 Complex { 20 re: self.re * rhs.re - self.im * rhs.im, 21 im: self.re * rhs.im + self.im * rhs.re, 22 } 23 } 24 } 25 26 impl std::fmt::Display for Complex { 27 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { 28 if self.im >= 0.0 { 29 write!(f, "{}+{}i", self.re, self.im) 30 } else { 31 write!(f, "{}{}i", self.re, self.im) 32 } 33 } 34 } 35 36 fn main() { 37 let a = Complex { re: 1.0, im: 2.0 }; 38 let b = Complex { re: 3.0, im: -1.0 }; 39 println!("a + b = {}", a + b); 40 println!("a * b = {}", a * b); 41 } ``` **Output:** ```text 1 a + b = 4+1i 2 a * b = 5+5i ``` ### Exercise 2: An accumulator with `AddAssign` [Section titled “Exercise 2: An accumulator with AddAssign”](#exercise-2-an-accumulator-with-addassign) **Difficulty:** Intermediate **Objective:** Use a non-`Self` right-hand side so `stats += sample` folds an `f64` into a running aggregate. **Instructions:** Define `struct Stats { count: u32, total: f64 }` deriving `Default`. Implement `AddAssign<f64>` so that `stats += x` increments `count` and adds `x` to `total`. Add a `mean(&self) -> f64` method (return `0.0` when empty). Feed `[10.0, 20.0, 30.0]` and print the stats and the mean. Solution ```rust 1 use std::ops::AddAssign; 2 3 #[derive(Debug, Default, Clone, Copy)] 4 struct Stats { 5 count: u32, 6 total: f64, 7 } 8 9 impl AddAssign<f64> for Stats { 10 fn add_assign(&mut self, sample: f64) { 11 self.count += 1; 12 self.total += sample; 13 } 14 } 15 16 impl Stats { 17 fn mean(&self) -> f64 { 18 if self.count == 0 { 19 0.0 20 } else { 21 self.total / self.count as f64 22 } 23 } 24 } 25 26 fn main() { 27 let mut s = Stats::default(); 28 for x in [10.0, 20.0, 30.0] { 29 s += x; 30 } 31 println!("{s:?}"); 32 println!("mean = {}", s.mean()); 33 } ``` **Output:** ```text 1 Stats { count: 3, total: 60.0 } 2 mean = 20 ``` ### Exercise 3: A 2D matrix indexed by `(row, col)` [Section titled “Exercise 3: A 2D matrix indexed by (row, col)”](#exercise-3-a-2d-matrix-indexed-by-row-col) **Difficulty:** Advanced **Objective:** Implement `Index` and `IndexMut` with a tuple index so a flat-backed matrix supports `m[(r, c)]` for both reading and writing. **Instructions:** Define `struct Matrix { rows: usize, cols: usize, data: Vec<f64> }` backed by a single `Vec<f64>` in row-major order. Add a `zeros(rows, cols)` constructor. Implement `Index<(usize, usize)>` and `IndexMut<(usize, usize)>` that map `(r, c)` to `r * cols + c`, with a bounds `assert!`. Build a 2×3 matrix, write a couple of cells, and read them back. Solution ```rust 1 use std::ops::{Index, IndexMut}; 2 3 struct Matrix { 4 rows: usize, 5 cols: usize, 6 data: Vec<f64>, 7 } 8 9 impl Matrix { 10 fn zeros(rows: usize, cols: usize) -> Self { 11 Matrix { rows, cols, data: vec![0.0; rows * cols] } 12 } 13 } 14 15 impl Index<(usize, usize)> for Matrix { 16 type Output = f64; 17 fn index(&self, (r, c): (usize, usize)) -> &f64 { 18 assert!(r < self.rows && c < self.cols, "index out of bounds"); 19 &self.data[r * self.cols + c] 20 } 21 } 22 23 impl IndexMut<(usize, usize)> for Matrix { 24 fn index_mut(&mut self, (r, c): (usize, usize)) -> &mut f64 { 25 assert!(r < self.rows && c < self.cols, "index out of bounds"); 26 &mut self.data[r * self.cols + c] 27 } 28 } 29 30 fn main() { 31 let mut m = Matrix::zeros(2, 3); 32 m[(0, 0)] = 1.0; 33 m[(1, 2)] = 9.0; 34 println!("m[(0,0)] = {}", m[(0, 0)]); 35 println!("m[(1,2)] = {}", m[(1, 2)]); 36 println!("m[(0,1)] = {}", m[(0, 1)]); 37 } ``` **Output:** ```text 1 m[(0,0)] = 1 2 m[(1,2)] = 9 3 m[(0,1)] = 0 ``` > The destructuring `(r, c): (usize, usize)` in the parameter list pattern-matches the tuple index directly. Because `index`/`index_mut` return references, the *same* `m[(r, c)]` syntax serves reads and the left side of an assignment. # Marker Traits: `Copy`, `Sized`, `Send`, and `Sync` > Rust marker traits Copy, Sized, Send, and Sync have no methods; they tell the compiler facts about a type, enabling bitwise copies and safe threading. Some Rust traits have no methods at all. They exist purely to **mark** a type with a property the compiler cares about: “this type is safe to copy bit-for-bit,” “this type has a known size,” “this type may move between threads.” TypeScript has no real equivalent: these are compile-time facts the Rust compiler tracks and enforces for you, mostly without you writing a single line. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **marker trait** is a trait with no methods or associated items; implementing it simply asserts a fact about the type. The four you will meet first are `Copy` (cheap bitwise duplication), `Sized` (the size is known at compile time), and the **auto traits** `Send` and `Sync` (the type is safe to move to, or share with, another thread). You almost never call methods on these. Instead, the compiler reads them to decide what your code is allowed to do, which is how Rust delivers data-race-free threading without a runtime. > **Note:** This file focuses on the four foundational marker traits. Bounding generics on traits in general is covered in [Trait Bounds](/09-generics-traits/05-trait-bounds/); the threading machinery (`Arc`, `Mutex`) lives under [smart pointers](/10-smart-pointers/) and the async sections. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) TypeScript has nothing that directly corresponds to a marker trait, so the closest thing is to contrast the two “facts” a TypeScript developer already reasons about informally: **assignment aliases an object** (it never copies), and **the language has no compiler-enforced thread-safety** because the main thread is single-threaded. ```typescript 1 // TypeScript / JavaScript — assignment shares a reference; nothing is copied. 2 const original = { r: 255, g: 128, b: 0 }; 3 4 const aliased = original; // `aliased` and `original` point at the SAME object 5 aliased.g = 0; 6 console.log(original.g); // 0 — the mutation is visible through both names 7 8 // To actually duplicate, you opt in explicitly: 9 const copied = { ...original }; // shallow copy (or structuredClone for deep) 10 copied.r = 10; 11 console.log(original.r, copied.r); // 255 10 — now they are independent 12 13 console.log(original); // { r: 255, g: 0, b: 0 } (this is how Node prints it) ``` **Key points for a TypeScript developer:** * Objects are always passed and assigned **by reference**. There is no concept of “this object is cheap enough to copy automatically.” * Worker threads in Node receive **structured-cloned** copies of data, and the runtime decides what is and is not transferable at runtime (e.g. a `function` cannot be cloned and throws a `DataCloneError`). Nothing is checked at compile time. * TypeScript’s type system is **erased** at runtime, so it can never enforce a property like “this value is safe to share across threads.” Rust turns each of these informal ideas into a trait the compiler enforces. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Here the marker traits do their work. `Copy` makes a small struct duplicate on assignment instead of move; the implicit `Sized` bound lets generics accept normal values; and `Send`/`Sync` are checked when we cross a thread boundary. ```rust 1 use std::sync::{Arc, Mutex}; 2 use std::thread; 3 4 // `Copy` says: duplicating this value is just a bitwise memcpy, so assignment 5 // copies instead of moving. We can only derive it because every field is Copy. 6 #[derive(Debug, Clone, Copy)] 7 struct Rgb { 8 r: u8, 9 g: u8, 10 b: u8, 11 } 12 13 fn show(color: Rgb) { 14 println!("rgb({}, {}, {})", color.r, color.g, color.b); 15 } 16 17 fn main() { 18 let orange = Rgb { r: 255, g: 128, b: 0 }; 19 show(orange); 20 show(orange); // still valid: `Copy` duplicated it instead of moving it 21 println!("original still usable: {orange:?}"); 22 23 // `Arc<Mutex<T>>` is `Send + Sync`, so the compiler lets it cross threads. 24 let counter = Arc::new(Mutex::new(0)); 25 let mut handles = Vec::new(); 26 for _ in 0..5 { 27 let counter = Arc::clone(&counter); 28 handles.push(thread::spawn(move || { 29 *counter.lock().unwrap() += 1; 30 })); 31 } 32 for handle in handles { 33 handle.join().unwrap(); 34 } 35 println!("final count = {}", *counter.lock().unwrap()); 36 } ``` Running it: ```text 1 rgb(255, 128, 0) 2 rgb(255, 128, 0) 3 original still usable: Rgb { r: 255, g: 128, b: 0 } 4 final count = 5 ``` The `show(orange)` call appears twice and compiles, because `Rgb` is `Copy`. Swap a `String` field into `Rgb` and the second call would fail to compile, because the value would have **moved**. That single trait flips the most fundamental rule of the language for a type. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `Copy` — duplicate by `memcpy`, no move [Section titled “Copy — duplicate by memcpy, no move”](#copy--duplicate-by-memcpy-no-move) By default, assigning or passing a value **moves** it (see [Section 05: Ownership](/05-ownership/)). A type that implements `Copy` opts out of move semantics: the value is duplicated with a trivial bit-for-bit copy, and the original stays valid. * `Copy` is a **supertrait** relationship away from `Clone`: every `Copy` type must also be `Clone`, which is why we derive `#[derive(Clone, Copy)]` together. `Clone` is the explicit, possibly-expensive `.clone()`; `Copy` is the implicit, always-cheap duplication the compiler inserts for you. * A type can be `Copy` only if **all of its fields are `Copy`**. Integers, floats, `bool`, `char`, shared references `&T`, and tuples/arrays of `Copy` types qualify. `String`, `Vec<T>`, `Box<T>`, and `&mut T` do **not**, because they own a resource (heap allocation, unique borrow) that cannot be meaningfully duplicated by a `memcpy`. * You implement `Copy` by deriving it; never write the body, because there is nothing to write. It is a pure marker. > **Tip:** Reach for `Copy` on small, value-like types: coordinates, IDs, flags, enums of unit variants. Skip it for anything that owns heap data; cloning those should be a visible `.clone()` call so the cost is obvious at the call site. ### `Sized` — the size is known at compile time [Section titled “Sized — the size is known at compile time”](#sized--the-size-is-known-at-compile-time) `Sized` marks types whose size is known at compile time (`i32` is 4 bytes; `Rgb` is 3 bytes). This is the most invisible marker trait, because **every generic type parameter is implicitly `Sized`**. When you write `fn first_or<T>(...)`, the compiler silently rewrites it as `fn first_or<T: Sized>(...)`. The unsized (or **dynamically sized**) types you will encounter are `str` and `[T]` (slices), plus `dyn Trait` trait objects. You never hold these by value. You hold them behind a pointer (`&str`, `Box<[T]>`, `&dyn Trait`), and the pointer is `Sized` even though the thing it points to is not. To accept an unsized type in a generic, relax the bound with `?Sized` (“may or may not be sized”): ```rust 1 // `?Sized` lets this accept `str` (unsized) behind a reference, not just `String`. 2 fn print_len<T: AsRef<str> + ?Sized>(s: &T) { 3 println!("len = {}", s.as_ref().len()); 4 } 5 6 fn main() { 7 print_len("hello"); // &str — `str` is unsized 8 print_len(&String::from("world")); // &String — sized, also fine 9 } ``` ```text 1 len = 5 2 len = 5 ``` The `?Sized` bound applies to the type behind the reference, so `T` is allowed to be `str`. Note we must take `&T`, never `T`, because an unsized `T` cannot be passed by value. ### `Send` and `Sync` — the auto traits behind fearless concurrency [Section titled “Send and Sync — the auto traits behind fearless concurrency”](#send-and-sync--the-auto-traits-behind-fearless-concurrency) `Send` and `Sync` are **auto traits**: the compiler implements them for your type *automatically* if all of its fields already implement them. You do not write `impl Send for MyType {}`; composition handles it. * **`Send`** means a value of the type can be **moved to another thread**. Almost everything is `Send`. The famous exception is `Rc<T>` (the single-threaded reference counter), whose non-atomic count would race if shared across threads. * **`Sync`** means `&T` is `Send` — i.e. a **shared reference** can be handed to another thread, so the type can be accessed from multiple threads at once. Formally, `T: Sync` if and only if `&T: Send`. `Cell<T>` and `RefCell<T>` are `Send` but **not** `Sync`, because their interior mutability is not synchronized. These are exactly the traits `std::thread::spawn` requires: ```rust 1 // std signature (abridged): the closure and its captures must be Send + 'static. 2 // pub fn spawn<F, T>(f: F) -> JoinHandle<T> where F: Send + 'static, ... ``` Because the bound is `Send`, the compiler statically rejects any attempt to capture a non-`Send` value (like `Rc`) in a thread closure. There is no runtime check and no data race: the program simply does not compile. That is what the Rust community calls **fearless concurrency**. > **Note:** `Send`/`Sync` are `unsafe` traits to implement *by hand*, precisely because getting them wrong reintroduces data races. You will essentially never implement them manually; you rely on the automatic derivation and, when you need shared mutable state across threads, you reach for `Arc<Mutex<T>>` or `Arc<RwLock<T>>` (see [smart pointers](/10-smart-pointers/)). ### Opting out [Section titled “Opting out”](#opting-out) Auto traits can be *withheld* by including a non-`Send`/non-`Sync` field. The classic device is `PhantomData<*const ()>` (raw pointers are neither `Send` nor `Sync`), which removes the auto traits from a wrapper without changing its runtime layout. You rarely need this, but it explains why some standard types are deliberately not thread-safe. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / JavaScript | Rust | | ------------------------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | Duplicating a value | Always a reference alias; you opt in to copying (`{...obj}`, `structuredClone`) | `Copy` types duplicate automatically; everything else **moves** | | Knowing a type’s size | Irrelevant: everything is a boxed reference at runtime | `Sized` is tracked and implicitly required on every generic | | Thread safety | Not expressible in the type system; runtime `DataCloneError` at worst | `Send`/`Sync` are compiler-enforced *before* the program runs | | Who implements the trait | N/A | Auto traits (`Send`/`Sync`) are derived by the compiler; `Copy`/`Sized` you derive or get for free | | Methods on the trait | N/A | None: these are pure markers read by the compiler | | Cost of getting it wrong | Runtime exception or silent data race | Compile error (`E0277`, `E0382`, `E0204`) | The headline mental shift: in TypeScript, “is this safe to share between workers?” is a question you answer at runtime (and often get wrong). In Rust it is a *property of the type*, checked at compile time, and you almost never have to think about it because the compiler tracks it for you. > **Warning:** Do not equate `Copy` with TypeScript’s spread `{...obj}`. The spread is a shallow copy you write explicitly; `Copy` is an *automatic* full duplication the compiler inserts, and it is only legal when the bytes are self-contained (no owned heap data). They solve related problems but live at opposite ends of the explicit/implicit spectrum. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Trying to derive `Copy` on a type with an owning field [Section titled “Pitfall 1: Trying to derive Copy on a type with an owning field”](#pitfall-1-trying-to-derive-copy-on-a-type-with-an-owning-field) A TypeScript developer often assumes any struct can be `Copy`. But a type is `Copy` only if every field is. ```rust 1 // does not compile (error[E0204]) 2 #[derive(Clone, Copy)] 3 struct Wrapper { 4 label: String, // String owns heap data — not Copy 5 } 6 7 fn main() { 8 let _w = Wrapper { label: "x".into() }; 9 } ``` Real compiler output: ```text 1 error[E0204]: the trait `Copy` cannot be implemented for this type 2 --> src/main.rs:2:17 3 | 4 2 | #[derive(Clone, Copy)] 5 | ^^^^ 6 3 | struct Wrapper { 7 4 | label: String, // String is not Copy 8 | ------------- this field does not implement `Copy` 9 10 For more information about this error, try `rustc --explain E0204`. ``` **Fix:** drop `Copy` and keep `Clone`. Use an explicit `.clone()` when you need a second owned copy; the cost is then visible. ### Pitfall 2: Assuming a non-`Copy` value survives being passed by value [Section titled “Pitfall 2: Assuming a non-Copy value survives being passed by value”](#pitfall-2-assuming-a-non-copy-value-survives-being-passed-by-value) Without `Copy`, passing a value into a function moves it, and the original binding is dead. ```rust 1 // does not compile (error[E0382]) 2 #[derive(Debug, Clone)] // no Copy 3 struct Config { 4 name: String, 5 } 6 7 fn consume(c: Config) { 8 println!("{c:?}"); 9 } 10 11 fn main() { 12 let cfg = Config { name: "prod".into() }; 13 consume(cfg); 14 consume(cfg); // second use after move 15 } ``` Real compiler output (trimmed): ```text 1 error[E0382]: use of moved value: `cfg` 2 --> src/main.rs:13:13 3 | 4 11 | let cfg = Config { name: "prod".into() }; 5 | --- move occurs because `cfg` has type `Config`, which does not implement the `Copy` trait 6 12 | consume(cfg); 7 | --- value moved here 8 13 | consume(cfg); // second use after move 9 | ^^^ value used here after move 10 | 11 help: consider cloning the value if the performance cost is acceptable 12 | 13 12 | consume(cfg.clone()); 14 | ++++++++ ``` **Fix:** pass a borrow (`&Config`) if `consume` only needs to read, or `.clone()` if it needs its own copy. This is the same decision you make everywhere ownership applies; `Copy` is just the special case where the compiler makes it for you. ### Pitfall 3: Capturing an `Rc` (or other non-`Send` value) in a thread [Section titled “Pitfall 3: Capturing an Rc (or other non-Send value) in a thread”](#pitfall-3-capturing-an-rc-or-other-non-send-value-in-a-thread) `Rc<T>` is the single-threaded reference counter and is deliberately **not** `Send`. Try to send it to a thread and the compiler stops you cold. ```rust 1 // does not compile (error[E0277]: `Rc<...>` cannot be sent between threads safely) 2 use std::rc::Rc; 3 use std::thread; 4 5 fn main() { 6 let shared = Rc::new(vec![1, 2, 3]); 7 let shared2 = Rc::clone(&shared); 8 thread::spawn(move || { 9 println!("{:?}", shared2); 10 }); 11 println!("{:?}", shared); 12 } ``` Real compiler output (trimmed): ```text 1 error[E0277]: `Rc<Vec<i32>>` cannot be sent between threads safely 2 --> src/main.rs:8:19 3 | 4 8 | thread::spawn(move || { 5 | ------------- ^------ 6 | | | 7 | _____|_____________within this `{closure@src/main.rs:8:19: 8:26}` 8 | | | 9 | | required by a bound introduced by this call 10 | |_____^ `Rc<Vec<i32>>` cannot be sent between threads safely 11 | 12 = help: within `{closure@...}`, the trait `Send` is not implemented for `Rc<Vec<i32>>` 13 note: required by a bound in `spawn` ``` **Fix:** use `Arc<T>` (the *atomic* reference counter), which **is** `Send + Sync`. This is the entire reason both types exist: `Rc` is cheaper but single-threaded, `Arc` pays for atomic counters and earns thread-safety. ### Pitfall 4: Forgetting `?Sized` and trying to pass an unsized value [Section titled “Pitfall 4: Forgetting ?Sized and trying to pass an unsized value”](#pitfall-4-forgetting-sized-and-trying-to-pass-an-unsized-value) If a generic implicitly requires `Sized`, you cannot pass `str` or `[T]` by value. ```rust 1 // does not compile (error[E0277]: the size for values of type `str` cannot be known) 2 fn describe<T: std::fmt::Debug>(_value: T) {} 3 4 fn main() { 5 let s: &str = "hi"; 6 describe(*s); // dereferences to `str`, which is unsized 7 } ``` Real compiler output (trimmed): ```text 1 error[E0277]: the size for values of type `str` cannot be known at compilation time 2 --> src/main.rs:6:14 3 | 4 6 | describe(*s); 5 | -------- ^^ doesn't have a size known at compile-time 6 | 7 = help: the trait `Sized` is not implemented for `str` 8 note: required by an implicit `Sized` bound in `describe` 9 help: consider relaxing the implicit `Sized` restriction 10 | 11 2 | fn describe<T: std::fmt::Debug + ?Sized>(_value: T) {} 12 | ++++++++ ``` **Fix:** add `+ ?Sized` *and* take the value behind a reference (`_value: &T`). The compiler’s own suggestion points the way. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Derive `Copy` for small, plain-data types** (coordinates, IDs, flag enums) where bitwise duplication is the natural semantics. Always pair it with `Clone`: `#[derive(Clone, Copy)]`. Skip `Copy` for anything that owns heap data so that duplication stays an explicit `.clone()`. * **Never implement `Send`/`Sync` by hand.** Let the compiler derive them. If a type is missing `Send`/`Sync`, that is a signal: find the offending field (often an `Rc`, `Cell`, or raw pointer) rather than forcing an `unsafe impl`. * **Default to `Arc<Mutex<T>>` (or `Arc<RwLock<T>>`) for shared mutable state across threads,** and `Arc<T>` for shared read-only data. Use `Rc<T>`/`RefCell<T>` only when you know the data never crosses a thread boundary. * **Add `Send + Sync + 'static` bounds when you store callbacks, handlers, or spawn work,** so the type system documents and enforces “this must be thread-safe and self-owned.” A `Box<dyn Fn() + Send + Sync + 'static>` is the canonical thread-safe handler type. * **Use `?Sized` on borrow-only generic parameters** (`fn f<T: ?Sized>(x: &T)`) to accept slices, `str`, and trait objects in addition to sized types. This is how `AsRef<str>`-style flexible APIs are built. * **Verify a type’s marker traits with a one-line compile-time assertion** when you want a guarantee documented in code: `fn assert_send_sync<T: Send + Sync>() {}` then `assert_send_sync::<MyType>();`. If it stops compiling later, you broke thread-safety. ```rust 1 // Compile-time proof that types have the marker traits you expect. 2 fn assert_send_sync<T: Send + Sync>() {} 3 fn assert_send<T: Send>() {} 4 5 use std::cell::Cell; 6 7 fn main() { 8 assert_send_sync::<i32>(); 9 assert_send_sync::<String>(); 10 assert_send_sync::<std::sync::Arc<i32>>(); 11 assert_send::<Cell<i32>>(); // Cell is Send but NOT Sync, so only assert Send 12 println!("all the asserted bounds hold"); 13 } ``` ```text 1 all the asserted bounds hold ``` *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored **thread-safe event bus**: subscribers register handler closures by topic, and `publish` fans an event out to every handler in parallel. The marker traits are the load-bearing part of the design — the handler type bound `Fn(&str) + Send + Sync + 'static` is exactly what lets handlers be stored, cloned across threads, and run concurrently, and the compiler enforces it. ```rust 1 use std::collections::HashMap; 2 use std::sync::{Arc, Mutex}; 3 use std::thread; 4 5 /// A handler is any closure that processes an event payload. The bound 6 /// `Send + Sync + 'static` is what makes it safe to share across worker 7 /// threads and store for the lifetime of the bus. 8 type Handler = Arc<dyn Fn(&str) + Send + Sync + 'static>; 9 10 /// A minimal thread-safe event bus. `Arc<Mutex<...>>` is `Send + Sync`, 11 /// so the whole bus can be cloned and shared between threads. 12 #[derive(Clone)] 13 struct EventBus { 14 handlers: Arc<Mutex<HashMap<String, Vec<Handler>>>>, 15 } 16 17 impl EventBus { 18 fn new() -> Self { 19 EventBus { 20 handlers: Arc::new(Mutex::new(HashMap::new())), 21 } 22 } 23 24 fn subscribe<F>(&self, topic: &str, handler: F) 25 where 26 F: Fn(&str) + Send + Sync + 'static, // the marker bounds, made explicit 27 { 28 let mut map = self.handlers.lock().unwrap(); 29 map.entry(topic.to_string()) 30 .or_default() 31 .push(Arc::new(handler)); 32 } 33 34 fn publish(&self, topic: &str, payload: &str) { 35 // Snapshot the handlers, then drop the lock before running them. 36 let handlers = { 37 let map = self.handlers.lock().unwrap(); 38 map.get(topic).cloned().unwrap_or_default() 39 }; 40 41 let mut threads = Vec::new(); 42 for handler in handlers { 43 let payload = payload.to_string(); 44 // Both `handler` (an Arc) and `payload` (a String) are Send, 45 // so the compiler allows this move into the thread closure. 46 threads.push(thread::spawn(move || handler(&payload))); 47 } 48 for t in threads { 49 t.join().unwrap(); 50 } 51 } 52 } 53 54 fn main() { 55 let bus = EventBus::new(); 56 let counter = Arc::new(Mutex::new(0)); 57 58 let audit_counter = Arc::clone(&counter); 59 bus.subscribe("order.created", move |payload| { 60 *audit_counter.lock().unwrap() += 1; 61 println!("audit: order event -> {payload}"); 62 }); 63 64 bus.subscribe("order.created", |payload| { 65 println!("email: confirming {payload}"); 66 }); 67 68 bus.publish("order.created", "#1042"); 69 bus.publish("order.created", "#1043"); 70 71 println!("audit handler fired {} times", *counter.lock().unwrap()); 72 } ``` One real run (handlers for a single publish run on separate threads, so the relative order of the two lines within a publish is non-deterministic): ```text 1 audit: order event -> #1042 2 email: confirming #1042 3 audit: order event -> #1043 4 email: confirming #1043 5 audit handler fired 2 times ``` If you ever change `Handler` to `Rc<dyn Fn(&str)>`, this program stops compiling at the `thread::spawn` call: the `Send` bound fails exactly as in Pitfall 3. The marker traits are doing real work: they are the difference between a compiler-guaranteed-safe concurrent bus and a latent data race. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Fearless Concurrency (`Send` and `Sync`)](https://doc.rust-lang.org/book/ch16-04-extensible-concurrency-sync-and-send.html) * [The Rust Reference — Special types and traits (`Copy`, `Sized`, `Send`, `Sync`)](https://doc.rust-lang.org/reference/special-types-and-traits.html) * [`std::marker::Copy`](https://doc.rust-lang.org/std/marker/trait.Copy.html) · [`std::marker::Sized`](https://doc.rust-lang.org/std/marker/trait.Sized.html) · [`std::marker::Send`](https://doc.rust-lang.org/std/marker/trait.Send.html) · [`std::marker::Sync`](https://doc.rust-lang.org/std/marker/trait.Sync.html) * [The Rustonomicon — Send and Sync](https://doc.rust-lang.org/nomicon/send-and-sync.html) (advanced; for when you genuinely need to reason about manual impls) * [The Rust Reference — Dynamically sized types](https://doc.rust-lang.org/reference/dynamically-sized-types.html) ### Related Topics in This Guide [Section titled “Related Topics in This Guide”](#related-topics-in-this-guide) * [Ownership](/05-ownership/) — why move semantics is the default that `Copy` opts out of * [Variables](/02-basics/00-variables/): first contact with move vs. copy at the binding level * [Traits](/09-generics-traits/03-traits/) — what a trait is and how `impl Trait for Type` works * [Trait Bounds](/09-generics-traits/05-trait-bounds/): how `Send + Sync + 'static` bounds constrain generics * [Generic Functions](/09-generics-traits/00-generic-functions/) — where the implicit `Sized` bound is added * [Operator Overloading](/09-generics-traits/10-operator-overloading/): another family of traits the compiler wires up for you * [The Orphan Rule](/09-generics-traits/12-orphan-rule/) — coherence rules that also govern auto traits * [Smart Pointers](/10-smart-pointers/): `Rc` vs. `Arc`, `RefCell` vs. `Mutex`, and where the marker traits decide which you need *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1 — Make a value type `Copy` [Section titled “Exercise 1 — Make a value type Copy”](#exercise-1--make-a-value-type-copy) **Difficulty:** Easy **Objective:** Recognize when a type qualifies for `Copy` and observe how it changes pass-by-value behavior. **Instructions:** Define an `Rgb` color struct with three `u8` fields. Derive the traits that let you (a) duplicate it on assignment without moving, (b) compare two colors with `==`, and (c) print it with `{:?}`. Add a `luminance(self) -> f64` method (use `0.299*r + 0.587*g + 0.114*b`). In `main`, bind a color, assign it to a second variable, call `luminance` on the *first* one afterward, and confirm both names still work. ```rust 1 // TODO: derive the right traits so this struct is Copy, comparable, and printable 2 struct Rgb { 3 r: u8, 4 g: u8, 5 b: u8, 6 } 7 8 fn main() { 9 let white = Rgb { r: 255, g: 255, b: 255 }; 10 let copy = white; 11 // TODO: print white.luminance() and whether white == copy 12 } ``` Solution ```rust 1 #[derive(Debug, Clone, Copy, PartialEq)] 2 struct Rgb { 3 r: u8, 4 g: u8, 5 b: u8, 6 } 7 8 impl Rgb { 9 fn luminance(self) -> f64 { 10 0.299 * self.r as f64 + 0.587 * self.g as f64 + 0.114 * self.b as f64 11 } 12 } 13 14 fn main() { 15 let white = Rgb { r: 255, g: 255, b: 255 }; 16 let copy = white; // Copy: a bitwise duplicate; `white` stays valid 17 println!("luminance = {:.1}", white.luminance()); 18 println!("equal? {}", white == copy); 19 } ``` **Output:** ```text 1 luminance = 255.0 2 equal? true ``` Because every field (`u8`) is `Copy`, the struct can derive `Copy`. The `self` receiver on `luminance` takes the value by copy, so `white` remains usable afterward. ### Exercise 2 — Accept both owned and borrowed strings with `?Sized` [Section titled “Exercise 2 — Accept both owned and borrowed strings with ?Sized”](#exercise-2--accept-both-owned-and-borrowed-strings-with-sized) **Difficulty:** Medium **Objective:** Use `?Sized` to write a function that accepts string literals, `&str`, and `&String` alike. **Instructions:** Write a generic `log_line` that takes a `prefix: &str` and a message, and prints `[prefix] message`. Bound the message type so it works for `&str`, `&String`, and a `&str` slice without separate overloads. (Hint: `AsRef<str>` plus a relaxed `Sized` bound, taken by reference.) ```rust 1 // TODO: bound T so this compiles for &str, &String, and string slices 2 fn log_line<T>(prefix: &str, message: &T) { 3 println!("[{prefix}] {}", /* ??? */); 4 } 5 6 fn main() { 7 log_line("info", "starting up"); 8 let owned = String::from("connection lost"); 9 log_line("warn", &owned); 10 log_line("warn", owned.as_str()); 11 } ``` Solution ```rust 1 // `?Sized` relaxes the implicit `Sized` bound so `T` may be `str`; 2 // `AsRef<str>` gives a uniform way to view it as a string slice. 3 fn log_line<T: AsRef<str> + ?Sized>(prefix: &str, message: &T) { 4 println!("[{prefix}] {}", message.as_ref()); 5 } 6 7 fn main() { 8 log_line("info", "starting up"); // &str literal 9 let owned = String::from("connection lost"); 10 log_line("warn", &owned); // &String 11 log_line("warn", owned.as_str()); // &str slice 12 } ``` **Output:** ```text 1 [info] starting up 2 [warn] connection lost 3 [warn] connection lost ``` Without `?Sized`, the implicit `T: Sized` bound would reject `str`. Taking `&T` and viewing it through `AsRef<str>` makes the function accept every string-shaped input. ### Exercise 3 — A generic thread-safe cache [Section titled “Exercise 3 — A generic thread-safe cache”](#exercise-3--a-generic-thread-safe-cache) **Difficulty:** Hard **Objective:** Use `Send + Sync` (plus `'static`) bounds to build a generic container that can be shared across threads, and prove it works by mutating it from a spawned thread. **Instructions:** Build a `Cache<K, V>` backed by `Arc<Mutex<HashMap<K, V>>>`. Implement `new`, `insert(&self, K, V)`, and `get(&self, &K) -> Option<V>`. Add the trait bounds on the `impl` block that the threading and the `HashMap` actually require. Make `Cache` cheap to share by implementing `Clone` so it just clones the inner `Arc`. In `main`, insert one entry on the main thread, hand a clone of the cache to a spawned thread that inserts another, join it, and print both values. ```rust 1 use std::collections::HashMap; 2 use std::sync::{Arc, Mutex}; 3 4 struct Cache<K, V> { 5 store: Arc<Mutex<HashMap<K, V>>>, 6 } 7 8 // TODO: impl block with the right bounds: new / insert / get 9 // TODO: impl Clone so sharing across threads is cheap 10 // TODO: main that inserts from two threads and prints results ``` Solution ```rust 1 use std::collections::HashMap; 2 use std::hash::Hash; 3 use std::sync::{Arc, Mutex}; 4 use std::thread; 5 6 struct Cache<K, V> { 7 store: Arc<Mutex<HashMap<K, V>>>, 8 } 9 10 impl<K, V> Cache<K, V> 11 where 12 // HashMap needs Eq + Hash on keys; threading needs Send + Sync + 'static; 13 // Clone lets `get` return an owned value out of the lock. 14 K: Eq + Hash + Send + Sync + Clone + 'static, 15 V: Send + Sync + Clone + 'static, 16 { 17 fn new() -> Self { 18 Cache { store: Arc::new(Mutex::new(HashMap::new())) } 19 } 20 21 fn insert(&self, key: K, value: V) { 22 self.store.lock().unwrap().insert(key, value); 23 } 24 25 fn get(&self, key: &K) -> Option<V> { 26 self.store.lock().unwrap().get(key).cloned() 27 } 28 } 29 30 // Cloning the cache just bumps the Arc's refcount — both handles share state. 31 impl<K, V> Clone for Cache<K, V> { 32 fn clone(&self) -> Self { 33 Cache { store: Arc::clone(&self.store) } 34 } 35 } 36 37 fn main() { 38 let cache: Cache<String, u32> = Cache::new(); 39 cache.insert("startup".to_string(), 1); 40 41 let worker = cache.clone(); // shares the same underlying map 42 let writer = thread::spawn(move || { 43 worker.insert("hits".to_string(), 7); 44 }); 45 writer.join().unwrap(); 46 47 println!("startup = {:?}", cache.get(&"startup".to_string())); 48 println!("hits = {:?}", cache.get(&"hits".to_string())); 49 } ``` **Output:** ```text 1 startup = Some(1) 2 hits = Some(7) ``` The `Send + Sync + 'static` bounds are what let the cloned `Cache` move into the spawned thread; `Arc<Mutex<...>>` provides the `Send + Sync` shared mutable state. Replace `Arc`/`Mutex` with `Rc`/`RefCell` and the `thread::spawn` call would fail to compile with the `Send` error from Pitfall 3. # The Orphan Rule and Coherence > Rust's orphan rule lets you implement a trait for a type only if you own one side, turning TypeScript's silent prototype-patching clashes into compile errors. In TypeScript you can bolt a method onto `String.prototype`, declare module augmentations, and generally graft behavior onto anything from anywhere. Rust deliberately forbids the most dangerous version of this. The **orphan rule** — one half of Rust’s **coherence** guarantee — decides *who* is allowed to write a given `impl Trait for Type`. This file explains the rule, the real compiler error you hit when you break it, and the **newtype** pattern that gets you what you wanted anyway. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) **Coherence** is the compiler’s promise that for any given (trait, type) pair there is **at most one** implementation in the entire program: no ambiguity, ever. The **orphan rule** is the concrete restriction that enforces this: you may write `impl Trait for Type` only if **either the trait or the type is local to your crate**. You cannot implement a *foreign* trait for a *foreign* type. That combination is “orphaned,” owned by neither your crate nor anyone who can see it. When the rule blocks you, the standard escape hatch is the **newtype** pattern: wrap the foreign type in a one-field local struct, which makes the type local and re-opens the door. > **Note:** This matters to a TypeScript developer because the rule has no TypeScript analogue. There is nothing stopping two npm packages from both monkey-patching `Array.prototype.flatten`, and the resulting clash is a runtime mystery. Rust converts that whole class of bug into a compile error. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In JavaScript and TypeScript, “implementing behavior on a type you don’t own” is routine, and routinely fragile. Here we add a method to the built-in `Array` and to a class from an imaginary third-party library: ```typescript 1 // TypeScript - monkey-patching foreign types is allowed (and risky) 2 3 // 1. Augment the global Array type so TypeScript knows about our method. 4 declare global { 5 interface Array<T> { 6 second(): T | undefined; 7 } 8 } 9 10 // 2. Actually attach it at runtime. 11 Array.prototype.second = function <T>(this: T[]): T | undefined { 12 return this[1]; 13 }; 14 15 const items = ["a", "b", "c"]; 16 console.log(items.second()); // "b" 17 18 // The catch: NOTHING stops another module from doing the same thing. 19 // If a dependency also defines `Array.prototype.second` with different 20 // behavior, the last one loaded silently wins. No error, no warning. 21 Array.prototype.second = function () { 22 return "hijacked"; 23 }; 24 25 console.log(items.second()); // "hijacked" — your method is gone ``` **Key points:** * You can attach `second()` to `Array.prototype` even though you defined neither `Array` nor (conceptually) the “has a second element” behavior. * Two independent definitions silently collide. Whichever module is evaluated last overwrites the other. * The failure surfaces at **runtime**, far from the code that caused it, and is notoriously hard to debug. This freedom is exactly what Rust’s orphan rule trades away, on purpose. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust lets you do the *useful* version of the above (adding a method to `Vec`) but forces you to own at least one side of the relationship. Here we define our **own** trait and implement it for the foreign `String` and `i64` types, which is allowed: ```rust 1 // Rust - implementing a LOCAL trait for FOREIGN types is fine. 2 trait Summarize { 3 fn summary(&self) -> String; 4 } 5 6 impl Summarize for String { 7 fn summary(&self) -> String { 8 format!("a string of {} bytes", self.len()) 9 } 10 } 11 12 impl Summarize for i64 { 13 fn summary(&self) -> String { 14 format!("the integer {self}") 15 } 16 } 17 18 fn main() { 19 let s = String::from("hello"); 20 let n: i64 = 42; 21 println!("{}", s.summary()); 22 println!("{}", n.summary()); 23 } ``` Real output: ```text 1 a string of 5 bytes 2 the integer 42 ``` The trait `Summarize` is **local** (we defined it in this crate), so we may implement it for any type we like, foreign or not. The orphan rule is satisfied because *one* side — the trait — belongs to us. There is no way for another crate to define a conflicting `impl Summarize for String`, because they cannot see our private trait without importing it, and even then they would have to import *our* trait to clash with *our* impl, which the rule also handles. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The two ingredients: “local” and “foreign” [Section titled “The two ingredients: “local” and “foreign””](#the-two-ingredients-local-and-foreign) A trait or type is **local** if it is defined in the crate you are currently compiling, and **foreign** if it comes from another crate, including the standard library (`std`, `core`, `alloc`). The orphan rule, stated precisely enough to use: **an `impl Trait for Type` is allowed only if `Trait` is local, or `Type` (more precisely, a type constructor in the impl’s “self” position) is local.** If *both* are foreign, the impl is orphaned and rejected. | `impl Trait for Type` | Trait | Type | Allowed? | | ------------------------------ | ------- | ------- | -------------------- | | `impl Summarize for String` | local | foreign | yes: trait is local | | `impl Display for Wrapper` | foreign | local | yes: type is local | | `impl MyTrait for MyType` | local | local | yes: both local | | `impl Display for Vec<String>` | foreign | foreign | no: orphaned | ### Why coherence needs this [Section titled “Why coherence needs this”](#why-coherence-needs-this) Coherence guarantees there is exactly one impl per (trait, type) pair across the *whole* program. Imagine the rule did not exist. Crate `A` could write `impl Display for Vec<String>` to render a comma-separated list, and crate `B` could write `impl Display for Vec<String>` to render newline-separated lines. Your binary depends on both. Now `some_vec.to_string()` has **two** valid meanings, chosen by… what? Link order? Compilation order? There is no good answer, so Rust forbids the situation from arising. Because both `Display` and `Vec` live in `std`/`alloc`, neither `A` nor `B` is allowed to add that impl — only `std` itself can. > **Tip:** Read the rule as a question of *ownership and responsibility*. If you own the trait, you are responsible for its impls and can coordinate them. If you own the type, likewise. If you own neither, you have no authority to decide how that pairing behaves, and neither should two unrelated crates fight over it. ### The error you actually get [Section titled “The error you actually get”](#the-error-you-actually-get) Trying the orphaned impl directly produces a specific, well-known error: ```rust 1 use std::fmt; 2 3 // does not compile (error[E0117]): both `Display` and `Vec<T>` are foreign. 4 impl fmt::Display for Vec<String> { 5 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 6 write!(f, "[{}]", self.join(", ")) 7 } 8 } 9 10 fn main() {} ``` Real compiler output: ```text 1 error[E0117]: only traits defined in the current crate can be implemented for types defined outside of the crate 2 --> src/main.rs:4:1 3 | 4 4 | impl fmt::Display for Vec<String> { 5 | ^^^^^^^^^^^^^^^^^^^^^^----------- 6 | | 7 | `Vec` is not defined in the current crate 8 | 9 = note: impl doesn't have any local type before any uncovered type parameters 10 = note: for more information see https://doc.rust-lang.org/reference/items/implementations.html#orphan-rules 11 = note: define and implement a trait or new type instead ``` The final note — “define and implement a trait or new type instead” — is the compiler pointing you straight at the two ways out: own the trait, or own the type (via a newtype). ### The newtype workaround [Section titled “The newtype workaround”](#the-newtype-workaround) A **newtype** is a tuple struct with a single field that wraps another type: `struct Wrapper(Vec<String>);`. The wrapper is **local to your crate**, so implementing a foreign trait for it satisfies the orphan rule. It compiles to the same layout as the inner value (no runtime overhead), and it exists purely to give you a *local* type you are allowed to add impls to. ```rust 1 use std::fmt; 2 3 // `Wrapper` is a local newtype: a tuple struct holding one foreign type. 4 struct Wrapper(Vec<String>); 5 6 // We OWN `Wrapper` (a local type), so we may implement the FOREIGN trait 7 // `Display` for it. The orphan rule is satisfied because the type is local. 8 impl fmt::Display for Wrapper { 9 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 10 write!(f, "[{}]", self.0.join(", ")) 11 } 12 } 13 14 fn main() { 15 let w = Wrapper(vec![String::from("hello"), String::from("world")]); 16 println!("w = {w}"); 17 } ``` Real output: ```text 1 w = [hello, world] ``` You reach the inner value through the tuple field `self.0`. To convert in and out ergonomically, a `From` impl is idiomatic: ```rust 1 struct Wrapper(Vec<String>); 2 3 impl From<Vec<String>> for Wrapper { 4 fn from(v: Vec<String>) -> Self { 5 Wrapper(v) 6 } 7 } 8 9 fn main() { 10 let w: Wrapper = vec![String::from("a"), String::from("b")].into(); 11 // Access the inner value through the `.0` tuple field. 12 println!("first = {}", w.0[0]); 13 println!("len = {}", w.0.len()); 14 } ``` Real output: ```text 1 first = a 2 len = 2 ``` The one inconvenience: a newtype does *not* automatically expose the inner type’s methods. The next section’s pitfalls and the Real-World Example show how `Deref` recovers them when that is what you want. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | TypeScript / JavaScript | Rust | | ---------------------------------------- | ----------------------------------------- | ----------------------------------------------------- | | Add a method to a foreign type | `Foo.prototype.bar = ...`, always allowed | Only via a **local trait** or a **local newtype** | | Two libraries define the same extension | Silent runtime clash; last load wins | **Compile error** if it could be ambiguous | | When conflicts are detected | At runtime, possibly far from the cause | At compile time, before the program runs | | Guarantee of “one meaning per method” | None | **Coherence** — at most one impl per (trait, type) | | Workaround for “I don’t own either side” | Not needed (you just patch it) | **Newtype** wrapper makes the type local | | Runtime cost of the workaround | n/a | Zero: a newtype is the same layout as its inner value | ### Coherence is global; the orphan rule is local [Section titled “Coherence is global; the orphan rule is local”](#coherence-is-global-the-orphan-rule-is-local) Coherence is the *property* (“at most one impl program-wide”). The orphan rule is the *mechanism* the compiler uses to guarantee that property while only ever looking at one crate at a time. Because the compiler cannot see every other crate that might exist now or in the future, it must reject any impl that *could* clash with one written elsewhere. The orphan rule is a conservative, decidable approximation: “if neither side is yours, someone else might also write this, so no.” ### A second coherence check: overlap within a crate [Section titled “A second coherence check: overlap within a crate”](#a-second-coherence-check-overlap-within-a-crate) Even when the orphan rule is satisfied, coherence still forbids **overlapping** impls of the same trait for the same type *inside your own crate*: ```rust 1 trait Greet { 2 fn greet(&self) -> String; 3 } 4 5 // does not compile (error[E0119]): two impls of the same trait for `i32`. 6 impl Greet for i32 { 7 fn greet(&self) -> String { 8 String::from("hi") 9 } 10 } 11 12 impl Greet for i32 { 13 fn greet(&self) -> String { 14 String::from("hello") 15 } 16 } 17 18 fn main() {} ``` Real compiler output: ```text 1 error[E0119]: conflicting implementations of trait `Greet` for type `i32` 2 --> src/main.rs:12:1 3 | 4 6 | impl Greet for i32 { 5 | ------------------ first implementation here 6 ... 7 12 | impl Greet for i32 { 8 | ^^^^^^^^^^^^^^^^^^ conflicting implementation for `i32` ``` `E0117` (orphan rule) and `E0119` (overlap) are the two faces of coherence: the first stops cross-crate ambiguity, the second stops within-crate ambiguity. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Trying to implement a `std` trait for a `std` type [Section titled “Pitfall 1: Trying to implement a std trait for a std type”](#pitfall-1-trying-to-implement-a-std-trait-for-a-std-type) The classic stumble is wanting `Display` (or `Serialize`, `FromStr`, `PartialOrd`, …) on `Vec`, `HashMap`, `String`, or another standard type. Both sides are foreign, so it is rejected with `error[E0117]` (shown above). The fix is a newtype: wrap the standard type in your own struct and implement the trait on the wrapper. ### Pitfall 2: Assuming the newtype “just works” like the inner type [Section titled “Pitfall 2: Assuming the newtype “just works” like the inner type”](#pitfall-2-assuming-the-newtype-just-works-like-the-inner-type) A newtype starts with **none** of the inner type’s methods: ```rust 1 struct Wrapper(Vec<String>); 2 3 fn main() { 4 let w = Wrapper(vec![String::from("a")]); 5 let n = w.len(); // does not compile (error[E0599]): `Wrapper` has no method `len` 6 println!("{n}"); 7 } ``` The real error is `error[E0599]: no method named `len`found for struct`Wrapper“. You either go through the field explicitly (`w.0.len()`) or implement `Deref` to forward calls (see the Real-World Example). ### Pitfall 3: Thinking a generic parameter makes the impl “local enough” [Section titled “Pitfall 3: Thinking a generic parameter makes the impl “local enough””](#pitfall-3-thinking-a-generic-parameter-makes-the-impl-local-enough) A subtlety the error message hints at (“any uncovered type parameters”): wrapping a foreign generic does not help if the *type constructor* is still foreign. `impl ForeignTrait for Vec<MyLocalType>` is **still rejected** — `Vec` itself is foreign, and `MyLocalType` appears only *inside* it, “uncovered” behind a foreign constructor. The local type must be the outermost one: `impl ForeignTrait for MyWrapper(Vec<...>)` works because `MyWrapper` is the head type and it is yours. > **Warning:** “I used my own type somewhere in there” is not the test. The orphan rule looks at the *first* (left-to-right, outermost) type constructor that is not a bare type parameter. That constructor must be local. ### Pitfall 4: Expecting structural typing to bypass the rule [Section titled “Pitfall 4: Expecting structural typing to bypass the rule”](#pitfall-4-expecting-structural-typing-to-bypass-the-rule) Coming from TypeScript’s structural typing, you might expect that if your type “looks like” the foreign one, you can share impls. Rust is **nominal**: `Wrapper(Vec<String>)` and `Vec<String>` are entirely distinct types regardless of identical layout. The wrapper does not inherit the inner type’s trait impls, and the inner type does not gain the wrapper’s. This is the price — and the point — of the rule. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Reach for a newtype the moment you need a foreign trait on a foreign type.** It is the idiomatic, zero-cost answer; do not fight the rule with `unsafe` or clever generics. * **Prefer owning the trait when you can.** If you control the trait, you can implement it for any foreign types directly, no wrapper needed. A local trait that you implement for `String`, `i64`, etc., is clean and conflict-free (the first Rust example). * **Add `Deref` to a newtype only when you want transparent method forwarding** (for example, a smart-pointer-like wrapper). For a newtype whose whole purpose is to *restrict* or *change* behavior (a validated `Email(String)`), deliberately **omit** `Deref` so callers cannot bypass your invariants. See [Smart Pointers](/10-smart-pointers/) for `Deref` in depth. * **Use `#[derive(...)]` on the newtype to recover common impls cheaply.** Deriving `Debug`, `Clone`, `PartialEq`, etc. on the wrapper is usually all you need to make it pleasant to use. * **Expose conversions with `From`/`Into`** so wrapping and unwrapping read naturally (`value.into()`), and add accessor methods or `into_inner(self) -> Inner` rather than making the `.0` field part of your public API. * **Lean on the rule, do not resent it.** When the compiler rejects an orphan impl, it is preventing a real, hard-to-debug clash. The newtype is a feature, not a tax. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A common production need: render HTTP headers in a custom format. `Display` is foreign and `HashMap` is foreign, so you cannot implement `Display for HashMap` directly. The orphan-rule-respecting solution is a `Headers` newtype, given a custom `Display` and a `Deref` so callers can still use the underlying `HashMap` API transparently. ```rust 1 use std::collections::HashMap; 2 use std::fmt; 3 use std::ops::Deref; 4 5 // Newtype around the foreign type `HashMap<String, String>`. 6 // This lets us give it a custom `Display` (a foreign trait) for rendering 7 // HTTP-style headers — something we could never do on the bare HashMap. 8 struct Headers(HashMap<String, String>); 9 10 impl Headers { 11 fn new() -> Self { 12 Headers(HashMap::new()) 13 } 14 15 fn insert(&mut self, key: &str, value: &str) { 16 self.0.insert(key.to_string(), value.to_string()); 17 } 18 } 19 20 // `Deref` forwards method calls to the inner map, so callers can use 21 // `.get`, `.len`, `.contains_key`, etc. directly on a `Headers`. 22 impl Deref for Headers { 23 type Target = HashMap<String, String>; 24 fn deref(&self) -> &Self::Target { 25 &self.0 26 } 27 } 28 29 impl fmt::Display for Headers { 30 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 31 // Sort for deterministic output. 32 let mut entries: Vec<_> = self.0.iter().collect(); 33 entries.sort_by(|a, b| a.0.cmp(b.0)); 34 for (key, value) in entries { 35 writeln!(f, "{key}: {value}")?; 36 } 37 Ok(()) 38 } 39 } 40 41 fn main() { 42 let mut headers = Headers::new(); 43 headers.insert("Content-Type", "application/json"); 44 headers.insert("X-Request-Id", "abc-123"); 45 46 // Deref lets us call HashMap methods straight through the newtype. 47 println!("header count: {}", headers.len()); 48 println!("has content-type: {}", headers.contains_key("Content-Type")); 49 50 // Our custom Display does the rendering. 51 print!("{headers}"); 52 } ``` Real output: ```text 1 header count: 2 2 has content-type: true 3 Content-Type: application/json 4 X-Request-Id: abc-123 ``` This is the same instinct as the TypeScript monkey-patch — “give this collection a nicer toString” — but Rust routes it through a type *you* own, so two crates can each have their own `Headers`-style wrapper without ever colliding. > **Note:** This is exactly why serde provides `#[serde(remote = "...")]` and why crates publish “newtype” wrapper helpers: the ecosystem builds *around* the orphan rule rather than against it, because the guarantee it buys — no surprise impl conflicts when you add a dependency — is worth far more than the convenience it costs. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Rust Book — Implementing a Trait on a Type (and the orphan rule)](https://doc.rust-lang.org/book/ch10-02-traits.html#implementing-a-trait-on-a-type) * [The Rust Book — Using the Newtype Pattern to Implement External Traits](https://doc.rust-lang.org/book/ch20-02-advanced-traits.html#using-the-newtype-pattern-to-implement-external-traits-on-external-types) * [The Rust Reference — Implementation coherence & orphan rules](https://doc.rust-lang.org/reference/items/implementations.html#orphan-rules) * [Rust error index — E0117](https://doc.rust-lang.org/error_codes/E0117.html) and [E0119](https://doc.rust-lang.org/error_codes/E0119.html) ### Related sections in this guide [Section titled “Related sections in this guide”](#related-sections-in-this-guide) * [Section 09 overview](/09-generics-traits/): the full map of generics and traits * [Traits](/09-generics-traits/03-traits/): defining and implementing a trait; the `impl Trait for Type` syntax this rule governs * [Trait Bounds](/09-generics-traits/05-trait-bounds/): why bounds are nominal, which is the same reason the orphan rule is nominal * [Trait Objects and Dynamic Dispatch](/09-generics-traits/06-trait-objects/): `Box<dyn Trait>` for heterogeneous collections * [Operator Overloading](/09-generics-traits/10-operator-overloading/) — implementing `Add`, `Index`, etc.; often combined with newtypes * [Marker Traits](/09-generics-traits/11-marker-traits/) — `Send`, `Sync`, `Copy`, `Sized`, and the auto-trait variation of these rules * [Generic Functions](/09-generics-traits/00-generic-functions/) — monomorphization vs TypeScript type erasure * [Smart Pointers](/10-smart-pointers/) — `Deref`, the trait that makes newtype forwarding ergonomic * [Section 02: Basics](/02-basics/) and [Section 01: Getting Started](/01-getting-started/) — foundational concepts (tuple structs, `struct` basics) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A `Display` newtype for a primitive [Section titled “Exercise 1: A Display newtype for a primitive”](#exercise-1-a-display-newtype-for-a-primitive) **Difficulty:** Easy **Objective:** Use the newtype pattern to attach a foreign trait (`Display`) to a wrapper around a foreign type (`f64`). **Instructions:** Define a newtype `Celsius(f64)`. Implement `std::fmt::Display` for it so that a temperature prints with one decimal place followed by `°C` (for example, `21.5°C`). In `main`, construct `Celsius(21.5)` and print it with `println!`. ```rust 1 use std::fmt; 2 3 struct Celsius(f64); 4 5 // TODO: impl fmt::Display for Celsius, printing "{:.1}°C" 6 7 fn main() { 8 // TODO: build Celsius(21.5) and print it 9 } ``` Solution ```rust 1 use std::fmt; 2 3 struct Celsius(f64); 4 5 impl fmt::Display for Celsius { 6 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 7 write!(f, "{:.1}°C", self.0) 8 } 9 } 10 11 fn main() { 12 let temp = Celsius(21.5); 13 println!("Current temperature: {temp}"); 14 } ``` **Output:** ```text 1 Current temperature: 21.5°C ``` > Both `Display` and `f64` are foreign, so this only compiles because `Celsius` is a local type. Implementing `Display` for bare `f64` would fail with `error[E0117]`. ### Exercise 2: A foreign operator trait on a wrapped collection [Section titled “Exercise 2: A foreign operator trait on a wrapped collection”](#exercise-2-a-foreign-operator-trait-on-a-wrapped-collection) **Difficulty:** Medium **Objective:** Implement the foreign `std::ops::Add` trait for a newtype around the foreign `Vec<i32>`, an impl the orphan rule would forbid on `Vec` itself. **Instructions:** Define a newtype `IntList(Vec<i32>)` and derive `Debug`. Implement `Add` so that adding two `IntList`s concatenates their inner vectors (the elements of the left list followed by the elements of the right). In `main`, add `IntList(vec![1, 2, 3])` and `IntList(vec![4, 5])` and print the result with `{:?}`. ```rust 1 use std::ops::Add; 2 3 #[derive(Debug)] 4 struct IntList(Vec<i32>); 5 6 // TODO: impl Add for IntList, concatenating the inner vectors 7 8 fn main() { 9 // TODO: add two IntLists and print the result with {:?} 10 } ``` Solution ```rust 1 use std::ops::Add; 2 3 // Newtype around the foreign type `Vec<i32>`. 4 #[derive(Debug)] 5 struct IntList(Vec<i32>); 6 7 // `Add` is foreign and `Vec<i32>` is foreign, but `IntList` is local, 8 // so this impl is allowed by the orphan rule. 9 impl Add for IntList { 10 type Output = IntList; 11 fn add(self, other: IntList) -> IntList { 12 let mut combined = self.0; 13 combined.extend(other.0); 14 IntList(combined) 15 } 16 } 17 18 fn main() { 19 let a = IntList(vec![1, 2, 3]); 20 let b = IntList(vec![4, 5]); 21 let c = a + b; 22 println!("{c:?}"); 23 } ``` **Output:** ```text 1 IntList([1, 2, 3, 4, 5]) ``` > Operator overloading lives in [Operator Overloading](/09-generics-traits/10-operator-overloading/); the orphan rule is what makes wrapping `Vec` necessary to do it here. ### Exercise 3: Newtype + `Deref` to add a foreign trait to a foreign type [Section titled “Exercise 3: Newtype + Deref to add a foreign trait to a foreign type”](#exercise-3-newtype--deref-to-add-a-foreign-trait-to-a-foreign-type) **Difficulty:** Hard **Objective:** Model the real-world bind (a trait from one crate, a type from another, neither of which you control) and resolve it with a newtype plus `Deref` for transparent field access. **Instructions:** Treat `Money { cents: u64 }` and the trait `Render { fn render(&self) -> String; }` as if they came from two different external crates you cannot edit (so `impl Render for Money` is impossible by the orphan rule). Define a local newtype `Priced(Money)`. Implement `Deref<Target = Money>` so that `priced.cents` reads through to the inner value, then implement `Render` for `Priced` to format the amount as dollars (for example, `1995` cents becomes `$19.95`; always show two cents digits). In `main`, build `Priced(Money { cents: 1995 })`, print its raw `cents` (via `Deref`), and print `render()`. ```rust 1 use std::ops::Deref; 2 3 #[derive(Clone, Copy)] 4 struct Money { 5 cents: u64, 6 } 7 8 trait Render { 9 fn render(&self) -> String; 10 } 11 12 struct Priced(Money); 13 14 // TODO: impl Deref for Priced (Target = Money) 15 // TODO: impl Render for Priced, formatting cents as "$D.CC" 16 17 fn main() { 18 // TODO: build Priced(Money { cents: 1995 }), print .cents and .render() 19 } ``` Solution ```rust 1 use std::ops::Deref; 2 3 // Imagine `Money` is a type from an external crate that we cannot edit, 4 // and `Render` is a trait from ANOTHER external crate. We cannot write 5 // `impl Render for Money` (orphan rule). The fix: wrap it. 6 7 // --- pretend these two come from different foreign crates --- 8 #[derive(Clone, Copy)] 9 struct Money { 10 cents: u64, 11 } 12 13 trait Render { 14 fn render(&self) -> String; 15 } 16 // ----------------------------------------------------------- 17 18 // Local newtype wrapper. 19 struct Priced(Money); 20 21 impl Deref for Priced { 22 type Target = Money; 23 fn deref(&self) -> &Money { 24 &self.0 25 } 26 } 27 28 // Allowed: `Priced` is local, even though both `Render` and `Money` 29 // would be foreign in the real-world scenario. 30 impl Render for Priced { 31 fn render(&self) -> String { 32 let dollars = self.cents / 100; 33 let cents = self.cents % 100; 34 format!("${dollars}.{cents:02}") 35 } 36 } 37 38 fn main() { 39 let price = Priced(Money { cents: 1995 }); 40 // Deref lets us read `.cents` straight through the wrapper. 41 println!("raw cents: {}", price.cents); 42 println!("rendered: {}", price.render()); 43 } ``` **Output:** ```text 1 raw cents: 1995 2 rendered: $19.95 ``` > `self.cents` inside `render` works because `Deref` auto-dereferences `&Priced` to `&Money` when looking up the field. The `Deref` trait and its method-resolution magic are covered in [Smart Pointers](/10-smart-pointers/). # Rust Smart Pointers > TypeScript hides every heap, sharing, and lifetime choice; Rust's smart pointers make them explicit: Box, Rc/Arc, RefCell, Cell, Cow, Weak, and Deref. In TypeScript and JavaScript every object is a garbage-collected, freely-shared, freely-mutable reference; the runtime makes every storage and lifetime decision for you. Rust hands those decisions back, and **smart pointers** are the types that encode them: `Box<T>` for heap allocation with a single owner, `Rc<T>`/`Arc<T>` for shared ownership, `RefCell<T>`/`Mutex<T>` and `Cell<T>` for **interior mutability** (mutating through a shared reference), `Cow<'_, T>` for clone-on-write, and `Weak<T>` for breaking reference cycles. The `Deref` trait is the quiet machinery that makes all of them feel like the value they wrap. This section maps each TypeScript habit — implicit boxing, aliased references, mutate-anywhere objects — onto the explicit Rust type that expresses the same intent at zero or near-zero runtime cost. *** ## What You’ll Learn [Section titled “What You’ll Learn”](#what-youll-learn) * How to put a value on the **heap** with `Box<T>`, why **recursive types** (cons lists, trees, ASTs) require it, and how `Box<dyn Trait>` owns a trait object so one container can hold many concrete types * How **shared ownership** works with `Rc<T>` (single-threaded) and `Arc<T>` (atomic, thread-safe), why `clone` is a cheap reference-count bump rather than a deep copy, and how to read the live owner count with `strong_count` * What **interior mutability** is, and how `RefCell<T>` (single-thread, runtime borrow checks that **panic** on violation) and `Mutex<T>` (thread-safe, blocking) let you mutate through a shared `&` reference * When to drop down to `Cell<T>` for `Copy` types: `get`/`set` of whole values with no references handed out and no runtime borrow tracking * How `Cow<'_, T>` holds **borrowed or owned** data behind one type and allocates only at the moment you must mutate, eliminating needless copies on the hot path * How `Weak<T>` breaks the reference **cycles** that would otherwise leak `Rc`/`Arc` memory, and how `upgrade()` safely turns a weak handle back into a strong one * How the **`Deref`/`DerefMut`** traits and **deref coercion** explain why `&String` works where `&str` is expected and why you rarely write `*` on a `Box` * A repeatable **decision procedure** (single vs. shared owner, mutated through `&` or not, one thread or many) that lands you on exactly the right smart pointer every time *** ## Topics [Section titled “Topics”](#topics) | Topic | Description | | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | | [`Box<T>`: Heap Allocation](/10-smart-pointers/00-box/) | `Box<T>` for heap allocation; recursive types (cons list, tree, AST); trait objects with `Box<dyn Trait>`. | | [Shared Ownership with `Rc`/`Arc`](/10-smart-pointers/01-rc-arc/) | `Rc<T>` (single-thread) vs `Arc<T>` (atomic, thread-safe); shared ownership; `strong_count`; why cloning is a cheap reference bump. | | [Interior Mutability: `RefCell`/`Mutex`](/10-smart-pointers/02-refcell-mutex/) | Interior mutability; `RefCell<T>` (single-thread, runtime borrow checks) vs `Mutex<T>` (thread-safe); `borrow`/`borrow_mut` panics. | | [`Cell<T>` for Copy Types](/10-smart-pointers/03-cell/) | `Cell<T>` for `Copy` types; `get`/`set` whole values without handing out references. | | [Clone-on-Write with `Cow`](/10-smart-pointers/04-cow/) | `Cow<'_, T>` clone-on-write; borrowed vs owned variants; avoiding needless allocation. | | [Weak References with `Weak<T>`](/10-smart-pointers/05-weak/) | `Weak<T>` to break reference cycles; `upgrade()`; a parent/child graph example. | | [The `Deref` Trait](/10-smart-pointers/06-deref-trait/) | `Deref`/`DerefMut`; deref coercion; why `&String` works where `&str` is expected; `Box` deref. | | [Choosing a Smart Pointer](/10-smart-pointers/07-comparison/) | Decision guide: which smart pointer when — a table mapping each need to the type that satisfies it. | *** ## Learning Objectives [Section titled “Learning Objectives”](#learning-objectives) By the end of this section, you will be able to: * Reach for `Box<T>` to break the “infinite size” cycle of a recursive type, and use `Box<dyn Trait>` when different branches must return different concrete types * Choose between `Rc<T>` and `Arc<T>` based on whether the data crosses threads, and explain why `Rc::clone` / `Arc::clone` are cheap count bumps that free deterministically when the last owner drops * Apply interior mutability deliberately: `Cell<T>` for `Copy` values, `RefCell<T>` for single-threaded shared mutation, `Mutex<T>`/`RwLock<T>` across threads; and anticipate the runtime panic a doubled `borrow_mut()` produces * Combine a pointer with a cell idiomatically (`Rc<RefCell<T>>` single-threaded, `Arc<Mutex<T>>` across threads) to model the “shared mutable object” that JavaScript gives you for free * Use `Cow<'_, str>` to design APIs that return their input untouched on the common path and allocate only when they genuinely change it * Detect a reference cycle on sight and break it with `Weak<T>`, recovering a live value through `upgrade()` * Explain deref coercion well enough to predict when `&String`, `&Box<T>`, or `&Vec<T>` will be accepted where a borrowed inner type is expected * Run the three-question decision procedure to pick the minimal correct smart pointer instead of defaulting to `Arc<Mutex<T>>` *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * [Section 05: Ownership](/05-ownership/) — moves, borrows (`&`/`&mut`), the one-writer-or-many-readers rule, `Drop`, and the [reference-counting introduction](/05-ownership/07-reference-counting/); every smart pointer in this section is a deliberate departure from plain single ownership * [Section 09: Generics & Traits](/09-generics-traits/) — traits and especially [trait objects](/09-generics-traits/06-trait-objects/), which `Box<dyn Trait>` owns, plus the marker traits `Send`/`Sync` that decide `Rc`-vs-`Arc` and `RefCell`-vs-`Mutex` *** ## Estimated Time [Section titled “Estimated Time”](#estimated-time) * **Reading:** 4-5 hours * **Hands-on Practice:** 4-5 hours * **Exercises:** 2-3 hours * **Total:** 10-12 hours > **Tip:** Read [`00_box.md`](/10-smart-pointers/00-box/) first (it is the simplest pointer and introduces deref), then `01_rc-arc.md` → `02_refcell-mutex.md` → `03_cell.md` to build up shared ownership and interior mutability, then `04_cow.md` and `05_weak.md` for the two specialized cases. Finish with [`06_deref-trait.md`](/10-smart-pointers/06-deref-trait/) for the trait that unifies them and [`07_comparison.md`](/10-smart-pointers/07-comparison/) for the decision guide that ties everything together. The biggest mental shift for a TypeScript developer is that what JavaScript does invisibly — heap-allocate, share, and mutate every object — Rust makes you spell out, and each smart pointer is the explicit word for one of those previously-hidden choices. *** **Next:** [Section 11: Async →](/11-async/) — `Future`s, `async`/`await`, and the runtimes that drive them, where `Arc<Mutex<T>>` from this section becomes the everyday shape of shared application state. # Box<T>: Heap Allocation > Box<T> is Rust's simplest smart pointer: a single owner putting one value on the heap, used for recursive types and trait objects, freed without a garbage collector. `Box<T>` is the simplest **smart pointer** in Rust: a single owner of a value that lives on the **heap** instead of the stack. It is the tool you reach for when a type’s size cannot be known at compile time (recursive types), or when you want to store a value of an unknown concrete type behind a trait. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In JavaScript and TypeScript, *every* object, array, closure, and class instance already lives on the heap behind a reference. The engine decides, and you never write the allocation. Rust flips that default: values live on the **stack** unless you explicitly ask for the heap. `Box<T>` is that explicit ask. It is a thin, owning pointer to a heap allocation that frees itself automatically when it goes out of scope — no garbage collector, no `free()`. You will use `Box<T>` mainly for three things: **recursive data structures** (linked lists, trees, ASTs), **trait objects** (`Box<dyn Trait>`), and occasionally to move a large value to the heap so it is cheap to pass around. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript, heap allocation is invisible. Every node of a linked list, every tree, every polymorphic shape is “just an object,” and the runtime quietly boxes everything onto the heap and reference-counts it for the garbage collector. ```typescript 1 // TypeScript — a recursive linked list. Heap allocation is implicit. 2 type List = 3 | { kind: "cons"; value: number; rest: List } 4 | { kind: "nil" }; 5 6 const list: List = { 7 kind: "cons", 8 value: 1, 9 rest: { 10 kind: "cons", 11 value: 2, 12 rest: { kind: "cons", value: 3, rest: { kind: "nil" } }, 13 }, 14 }; 15 16 function sum(list: List): number { 17 return list.kind === "cons" ? list.value + sum(list.rest) : 0; 18 } 19 20 console.log(sum(list)); // 6 21 22 // Polymorphism is also implicit — an array of "any Shape". 23 interface Shape { 24 area(): number; 25 name(): string; 26 } 27 28 class Circle implements Shape { 29 constructor(private radius: number) {} 30 area() { 31 return Math.PI * this.radius ** 2; 32 } 33 name() { 34 return "circle"; 35 } 36 } 37 38 const shapes: Shape[] = [new Circle(2)]; 39 console.log(shapes[0].area()); // 12.566... ``` **Key points:** * `rest: List` self-references with no special syntax; the engine stores a *pointer* to another heap object. * `Shape[]` holds heterogeneous objects; the runtime dispatches `.area()` dynamically. * You never decide stack vs. heap; the JavaScript engine always heap-allocates objects. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust requires you to opt into the heap. A self-referential `enum` would have *infinite size* on the stack, so each recursive child goes behind a `Box`. ```rust 1 // Rust — a recursive cons list. `Box` provides the heap indirection. 2 #[derive(Debug)] 3 enum List { 4 Cons(i32, Box<List>), 5 Nil, 6 } 7 8 use List::{Cons, Nil}; 9 10 fn sum(list: &List) -> i32 { 11 match list { 12 Cons(value, rest) => value + sum(rest), 13 Nil => 0, 14 } 15 } 16 17 fn main() { 18 let list = Cons(1, Box::new(Cons(2, Box::new(Cons(3, Box::new(Nil)))))); 19 println!("{list:?}"); 20 println!("sum = {}", sum(&list)); 21 } ``` **Output:** ```text 1 Cons(1, Cons(2, Cons(3, Nil))) 2 sum = 6 ``` The `Box::new(...)` call allocates on the heap and returns an owning pointer. When `list` drops at the end of `main`, the whole chain is freed recursively, deterministically, with no garbage collector. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What a `Box<T>` actually is [Section titled “What a Box\<T> actually is”](#what-a-boxt-actually-is) A `Box<T>` is a pointer-sized value (8 bytes on a 64-bit machine) stored on the stack, pointing at a `T` stored on the heap. That is the entire data structure. There is no reference count and no extra metadata (for `Sized` types). It is the lowest-overhead way to put something on the heap. ```rust 1 fn main() { 2 let boxed: Box<i32> = Box::new(42); 3 println!("boxed value = {}", *boxed); // explicit dereference 4 println!("boxed value = {}", boxed); // Box<T> forwards Display to its inner T 5 } ``` **Output:** ```text 1 boxed value = 42 2 boxed value = 42 ``` The `*boxed` syntax **dereferences** the box to reach the `i32` it owns. Because `Box<T>` implements the `Deref` trait, you rarely need the explicit `*`: method calls, field access, and most trait usage automatically “see through” the box (this is **deref coercion**, covered in the Deref trait topic of this section). ```rust 1 fn main() { 2 let boxed = Box::new(vec![1, 2, 3]); 3 println!("len = {}", boxed.len()); // auto-deref: (*boxed).len() 4 println!("first = {:?}", boxed.first()); // auto-deref 5 let total: i32 = boxed.iter().sum(); 6 println!("sum = {total}"); 7 } ``` **Output:** ```text 1 len = 3 2 first = Some(1) 3 sum = 6 ``` ### Why recursive types need a `Box` [Section titled “Why recursive types need a Box”](#why-recursive-types-need-a-box) When the Rust compiler lays out a type, it needs to know its **exact size in bytes** at compile time. Consider this naive definition: ```rust 1 enum List { 2 Cons(i32, List), // does not compile (error[E0072]: recursive type has infinite size) 3 Nil, 4 } ``` To size `List`, the compiler must size `Cons`, which contains a `List`, which contains a `Cons`, which contains a `List`… forever. The size equation has no solution. The real compiler error spells this out: ```text 1 error[E0072]: recursive type `List` has infinite size 2 --> src/main.rs:1:1 3 | 4 1 | enum List { 5 | ^^^^^^^^^ 6 2 | Cons(i32, List), // no indirection 7 | ---- recursive without indirection 8 | 9 help: insert some indirection (e.g., a `Box`, `Rc`, or `&`) to break the cycle 10 | 11 2 | Cons(i32, Box<List>), // no indirection 12 | ++++ + ``` The compiler literally suggests the fix: wrap the recursive field in a `Box`. A `Box<List>` is always one pointer wide regardless of how deep the list goes, so `List` now has a finite, known size. We can confirm it: ```rust 1 use std::mem; 2 3 enum List { 4 Cons(i32, Box<List>), 5 Nil, 6 } 7 8 fn main() { 9 println!("size of Box<List> = {}", mem::size_of::<Box<List>>()); 10 println!("size of List = {}", mem::size_of::<List>()); 11 println!("size of i32 = {}", mem::size_of::<i32>()); 12 } ``` **Output:** ```text 1 size of Box<List> = 8 2 size of List = 16 3 size of i32 = 4 ``` `List` is 16 bytes: 4 for the `i32`, 8 for the `Box` pointer, plus padding/the discriminant, and importantly *fixed*, no matter how long the actual list is. The heap holds the rest. > **Note:** Only the recursion needs a box. `Vec<T>`, `String`, `HashMap`, and similar collections *already* store their contents on the heap internally, so a `Vec<Tree>` is fine without an explicit `Box` around each element. You add a `Box` when a single field directly contains another instance of the same type. ### Trait objects in a `Box` [Section titled “Trait objects in a Box”](#trait-objects-in-a-box) The second classic use is storing a value whose concrete type you do not know at compile time, but which implements a known trait. `Box<dyn Trait>` is the owning version of a trait object. ```rust 1 trait Shape { 2 fn area(&self) -> f64; 3 fn name(&self) -> &str; 4 } 5 6 struct Circle { radius: f64 } 7 struct Rectangle { width: f64, height: f64 } 8 9 impl Shape for Circle { 10 fn area(&self) -> f64 { std::f64::consts::PI * self.radius * self.radius } 11 fn name(&self) -> &str { "circle" } 12 } 13 14 impl Shape for Rectangle { 15 fn area(&self) -> f64 { self.width * self.height } 16 fn name(&self) -> &str { "rectangle" } 17 } 18 19 // One function, two different concrete return types — only possible behind `dyn`. 20 fn make_shape(kind: &str) -> Box<dyn Shape> { 21 match kind { 22 "circle" => Box::new(Circle { radius: 2.0 }), 23 _ => Box::new(Rectangle { width: 3.0, height: 4.0 }), 24 } 25 } 26 27 fn main() { 28 let shapes: Vec<Box<dyn Shape>> = vec![ 29 make_shape("circle"), 30 make_shape("rectangle"), 31 ]; 32 33 for shape in &shapes { 34 println!("{} has area {:.2}", shape.name(), shape.area()); 35 } 36 } ``` **Output:** ```text 1 circle has area 12.57 2 rectangle has area 12.00 ``` A `Circle` and a `Rectangle` have different sizes, so `Vec<Box<dyn Shape>>` cannot store them inline — but a `Box<dyn Shape>` is a fixed-size **fat pointer** (data pointer + vtable pointer), so a `Vec` of them works. This is the closest Rust equivalent to TypeScript’s `Shape[]`. The `dyn` keyword and the full mechanics of dynamic dispatch are covered in [Trait Objects and Dynamic Dispatch](/09-generics-traits/06-trait-objects/); here the point is simply that `Box` is what *owns* the trait object. > **Tip:** A function can only return *one* concrete type with `impl Trait`. When you need to return *different* concrete types from different branches — as `make_shape` does — you must use `Box<dyn Trait>`. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / JavaScript | Rust with `Box<T>` | | --------------------- | --------------------------------- | ------------------------------------------------- | | Where objects live | Always heap (engine-managed) | Stack by default; heap only via `Box`/collections | | Who frees memory | Garbage collector, eventually | Deterministic `drop` at end of scope | | Pointer cost | Hidden reference + GC bookkeeping | One machine word, zero runtime bookkeeping | | Recursive types | `rest: List` “just works” | Must break the cycle with `Box`/`Rc`/`&` | | Polymorphic container | `Shape[]` (implicit boxing) | `Vec<Box<dyn Shape>>` (explicit) | | Ownership | Shared by default (multiple refs) | Single owner; move semantics | | Null | `null` / `undefined` allowed | No null; absence is `Option<Box<T>>` | The mental shift for a TypeScript developer: in JavaScript *everything is a `Box` you never see*. In Rust, the stack is the default and the heap is a deliberate choice. That choice is cheap (`Box` is the minimal smart pointer), but it is yours to make. ### `Box<T>` vs. the other smart pointers [Section titled “Box\<T> vs. the other smart pointers”](#boxt-vs-the-other-smart-pointers) `Box<T>` gives **single ownership** and **no extra capabilities**: it is purely “this value, but on the heap.” When you need *shared* ownership, reach for [`Rc`/`Arc`](/10-smart-pointers/01-rc-arc/). When you need to mutate through a shared pointer, reach for [`RefCell`/`Mutex`](/10-smart-pointers/02-refcell-mutex/) or [`Cell`](/10-smart-pointers/03-cell/). A decision guide on which smart pointer to pick lives in this section’s overview. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting indirection in a recursive type [Section titled “Pitfall 1: Forgetting indirection in a recursive type”](#pitfall-1-forgetting-indirection-in-a-recursive-type) The error message is friendly, but new Rustaceans still get tripped up: defining `Cons(i32, List)` fails with `error[E0072]: recursive type has infinite size`. The fix is the compiler’s own suggestion: wrap the recursive field in `Box<List>` (or `Rc`/`&`). See the verified message in the Detailed Explanation above. ### Pitfall 2: Trying to move a value out of a borrowed `Box` [Section titled “Pitfall 2: Trying to move a value out of a borrowed Box”](#pitfall-2-trying-to-move-a-value-out-of-a-borrowed-box) Coming from JavaScript, where copying a reference is free, you might try to “take” a boxed value through a shared reference: ```rust 1 fn main() { 2 let boxed = Box::new(String::from("hello")); 3 let reference = &boxed; 4 let moved = *reference; // does not compile (error[E0507]) 5 println!("{moved}"); 6 } ``` The real compiler error: ```text 1 error[E0507]: cannot move out of `*reference` which is behind a shared reference 2 --> src/main.rs:4:17 3 | 4 4 | let moved = *reference; // cannot move out of `*reference` 5 | ^^^^^^^^^^ move occurs because `*reference` has type `Box<String>`, which does not implement the `Copy` trait 6 | 7 help: consider removing the dereference here 8 | 9 4 - let moved = *reference; // cannot move out of `*reference` 10 4 + let moved = reference; // cannot move out of `*reference` 11 | 12 help: consider cloning the value if the performance cost is acceptable 13 | 14 4 - let moved = *reference; // cannot move out of `*reference` 15 4 + let moved = reference.clone(); // cannot move out of `*reference` 16 | ``` You cannot move ownership out through a *shared* `&`. Either borrow the inner value (`let moved: &String = reference;`), clone it (`reference.clone()`), or — if you own the box outright — dereference the owned box directly (next pitfall). ### Pitfall 3: Surprise — you *can* move out of an owned `Box` [Section titled “Pitfall 3: Surprise — you can move out of an owned Box”](#pitfall-3-surprise--you-can-move-out-of-an-owned-box) `Box<T>` is special: unlike most types, dereferencing an *owned* box (a “deref move”) moves the value out and frees the box. ```rust 1 fn main() { 2 let boxed = Box::new(String::from("hello")); 3 let owned: String = *boxed; // moves the String off the heap into `owned` 4 println!("{owned}"); // prints: hello 5 // `boxed` is now consumed; using it here would be a compile error. 6 } ``` This works because the compiler knows `boxed` is the unique owner. It does *not* work through a reference (Pitfall 2). If you only have a reference, clone instead. ### Pitfall 4: Reaching for `Box` when you don’t need the heap [Section titled “Pitfall 4: Reaching for Box when you don’t need the heap”](#pitfall-4-reaching-for-box-when-you-dont-need-the-heap) A common over-correction is boxing small values “to be safe.” A plain `i32`, a small struct, or a fixed-size array belongs on the stack. Boxing it just adds a pointer indirection and a heap allocation for no benefit. Use `Box` for recursion, trait objects, or genuinely large values you want to move cheaply — not as a default. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Box the recursion, not the leaves.** Put `Box` only on the field that creates the cycle. Let `Vec`, `String`, and other collections do their own heap management. * **Prefer `Option<Box<T>>` for optional children.** A tree node’s `left`/`right` are naturally `Option<Box<TreeNode>>`: `None` is the empty subtree, with no null pointer in sight. * **Use `Box<dyn Trait>` for heterogeneous collections and “factory” return types.** When branches return different concrete types, `Box<dyn Trait>` is the idiomatic answer; `impl Trait` cannot do it. * **Reach for `Box<dyn Error>` in application code.** `Box<dyn std::error::Error>` is the standard “any error” return type for `main` and glue code (see [Error Handling](/08-error-handling/)). * **Don’t box what fits on the stack.** Boxing a `Copy` scalar or a small struct usually pessimizes performance. * **Let `Drop` do the work.** Never write manual cleanup; a `Box` frees its heap allocation automatically and deterministically when it leaves scope. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored use of `Box` is an **abstract syntax tree (AST)**: for example, evaluating an arithmetic expression. Each operator node holds sub-expressions of arbitrary depth, so the children live behind `Box`. This is exactly the shape a calculator, query parser, or template engine uses internally. ```rust 1 // An arithmetic expression AST. Each operator node owns boxed sub-expressions, 2 // so an expression of any depth has a fixed-size root node. 3 #[derive(Debug)] 4 enum Expr { 5 Number(f64), 6 Add(Box<Expr>, Box<Expr>), 7 Sub(Box<Expr>, Box<Expr>), 8 Mul(Box<Expr>, Box<Expr>), 9 Div(Box<Expr>, Box<Expr>), 10 } 11 12 impl Expr { 13 fn eval(&self) -> Result<f64, String> { 14 match self { 15 Expr::Number(n) => Ok(*n), 16 Expr::Add(a, b) => Ok(a.eval()? + b.eval()?), 17 Expr::Sub(a, b) => Ok(a.eval()? - b.eval()?), 18 Expr::Mul(a, b) => Ok(a.eval()? * b.eval()?), 19 Expr::Div(a, b) => { 20 let divisor = b.eval()?; 21 if divisor == 0.0 { 22 Err("division by zero".to_string()) 23 } else { 24 Ok(a.eval()? / divisor) 25 } 26 } 27 } 28 } 29 } 30 31 // A small helper keeps tree construction readable. 32 fn num(n: f64) -> Box<Expr> { 33 Box::new(Expr::Number(n)) 34 } 35 36 fn main() { 37 // (2 + 3) * (10 - 4) => 30 38 let expr = Expr::Mul( 39 Box::new(Expr::Add(num(2.0), num(3.0))), 40 Box::new(Expr::Sub(num(10.0), num(4.0))), 41 ); 42 match expr.eval() { 43 Ok(result) => println!("result = {result}"), 44 Err(e) => println!("error: {e}"), 45 } 46 47 // 1 / 0 => error, propagated via `?` 48 let bad = Expr::Div(num(1.0), num(0.0)); 49 match bad.eval() { 50 Ok(result) => println!("result = {result}"), 51 Err(e) => println!("error: {e}"), 52 } 53 } ``` **Output:** ```text 1 result = 30 2 error: division by zero ``` The recursion in `eval` mirrors the recursion in the type, and the `?` operator threads `Result` errors up through the tree. Because each child is owned by its parent `Box`, dropping the root drops the entire tree exactly once. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Rust Book — Using `Box<T>` to Point to Data on the Heap](https://doc.rust-lang.org/book/ch15-01-box.html) * [The Rust Book — Smart Pointers (chapter 15)](https://doc.rust-lang.org/book/ch15-00-smart-pointers.html) * [`std::boxed::Box` API docs](https://doc.rust-lang.org/std/boxed/struct.Box.html) * [Rust by Example — Box, stack and heap](https://doc.rust-lang.org/rust-by-example/std/box.html) * [The Rustonomicon — “Too Many Linked Lists” (deep dive on Box-based lists)](https://rust-unofficial.github.io/too-many-lists/) ### Related topics in this guide [Section titled “Related topics in this guide”](#related-topics-in-this-guide) * [Section 10 overview](/10-smart-pointers/): the full map of smart pointers * [Shared Ownership with `Rc<T>` and `Arc<T>`](/10-smart-pointers/01-rc-arc/) — when you need *shared* ownership instead of a single owner * [Interior Mutability](/10-smart-pointers/02-refcell-mutex/): mutating through a shared pointer (interior mutability) * The `Deref` trait topic of this section — the trait that makes `*boxed` and auto-deref work (forthcoming) * This section’s overview; decision guide: which smart pointer to pick when * [Trait Objects and Dynamic Dispatch](/09-generics-traits/06-trait-objects/) — the full story on `dyn Trait` and dynamic dispatch * [Ownership](/05-ownership/): ownership and move semantics, the foundation `Box` builds on * [Async](/11-async/) — `Box::pin` and `Pin<Box<dyn Future>>` show up when working with async *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A stack as a singly linked list [Section titled “Exercise 1: A stack as a singly linked list”](#exercise-1-a-stack-as-a-singly-linked-list) **Difficulty:** Beginner **Objective:** Build a recursive data structure with `Box` and understand why the indirection is required. **Instructions:** Implement a `Stack` of `i32` backed by a singly linked list. Use an `enum Link { Empty, More(Box<Node>) }` where `Node` holds a `value` and a `next: Link`. Provide `new`, `push`, and `pop`. (Hint: `std::mem::replace(&mut self.head, Link::Empty)` lets you take ownership of the current head without leaving a hole.) ```rust 1 enum Link { 2 Empty, 3 More(Box<Node>), 4 } 5 6 struct Node { 7 value: i32, 8 next: Link, 9 } 10 11 struct Stack { 12 head: Link, 13 } 14 15 impl Stack { 16 fn new() -> Self { 17 // TODO 18 } 19 fn push(&mut self, value: i32) { 20 // TODO 21 } 22 fn pop(&mut self) -> Option<i32> { 23 // TODO 24 } 25 } 26 27 fn main() { 28 let mut stack = Stack::new(); 29 stack.push(1); 30 stack.push(2); 31 stack.push(3); 32 while let Some(v) = stack.pop() { 33 print!("{v} "); // expected: 3 2 1 34 } 35 println!(); 36 } ``` Solution ```rust 1 enum Link { 2 Empty, 3 More(Box<Node>), 4 } 5 6 struct Node { 7 value: i32, 8 next: Link, 9 } 10 11 struct Stack { 12 head: Link, 13 } 14 15 impl Stack { 16 fn new() -> Self { 17 Stack { head: Link::Empty } 18 } 19 20 fn push(&mut self, value: i32) { 21 // Take the old head out, then make a new node point at it. 22 let new_node = Box::new(Node { 23 value, 24 next: std::mem::replace(&mut self.head, Link::Empty), 25 }); 26 self.head = Link::More(new_node); 27 } 28 29 fn pop(&mut self) -> Option<i32> { 30 match std::mem::replace(&mut self.head, Link::Empty) { 31 Link::Empty => None, 32 Link::More(node) => { 33 self.head = node.next; // move the tail back into head 34 Some(node.value) 35 } 36 } 37 } 38 } 39 40 fn main() { 41 let mut stack = Stack::new(); 42 stack.push(1); 43 stack.push(2); 44 stack.push(3); 45 while let Some(v) = stack.pop() { 46 print!("{v} "); 47 } 48 println!(); 49 } ``` **Output:** ```text 1 3 2 1 ``` `std::mem::replace` is the key trick: it swaps in `Link::Empty` and hands you the previous value to own. Without it, you would be trying to move `self.head` out of a `&mut self`, which the borrow checker rejects. ### Exercise 2: A JSON-like value tree [Section titled “Exercise 2: A JSON-like value tree”](#exercise-2-a-json-like-value-tree) **Difficulty:** Intermediate **Objective:** Model a recursive document format and write a function that walks it. **Instructions:** Define an `enum Json` with variants `Null`, `Bool(bool)`, `Number(f64)`, `Str(String)`, `Array(Vec<Json>)`, and `Tagged(String, Box<Json>)` (a label wrapping one nested value — this is the variant that *requires* an explicit `Box`). Write `fn depth(value: &Json) -> usize` returning the maximum nesting depth (a scalar is depth 0; each `Array`/`Tagged` layer adds 1). Solution ```rust 1 #[derive(Debug)] 2 enum Json { 3 Null, 4 Bool(bool), 5 Number(f64), 6 Str(String), 7 Array(Vec<Json>), 8 Tagged(String, Box<Json>), 9 } 10 11 fn depth(value: &Json) -> usize { 12 match value { 13 Json::Array(items) => 1 + items.iter().map(depth).max().unwrap_or(0), 14 Json::Tagged(_, inner) => 1 + depth(inner), 15 _ => 0, // Null, Bool, Number, Str are leaves 16 } 17 } 18 19 fn main() { 20 let doc = Json::Array(vec![ 21 Json::Number(1.0), 22 Json::Tagged( 23 "nested".to_string(), 24 Box::new(Json::Array(vec![Json::Bool(true), Json::Null])), 25 ), 26 Json::Str("hi".to_string()), 27 ]); 28 println!("depth = {}", depth(&doc)); 29 println!("{doc:?}"); 30 } ``` **Output:** ```text 1 depth = 3 2 Array([Number(1.0), Tagged("nested", Array([Bool(true), Null])), Str("hi")]) ``` Note that `Array(Vec<Json>)` does *not* need a `Box`; `Vec` already heap-allocates its elements. Only `Tagged`, which holds a single nested `Json` directly, needs the `Box` to break the size cycle. ### Exercise 3: A command queue of boxed trait objects [Section titled “Exercise 3: A command queue of boxed trait objects”](#exercise-3-a-command-queue-of-boxed-trait-objects) **Difficulty:** Intermediate / Advanced **Objective:** Use `Box<dyn Trait>` to store and run a heterogeneous list of behaviors — the Rust analog of an array of polymorphic objects in TypeScript. **Instructions:** Define a trait `Command` with `fn run(&self, state: &mut i32)` and `fn describe(&self) -> String`. Implement it for three unit/tuple structs: `Add(i32)`, `Mul(i32)`, and `Reset`. Write `fn run_all(commands: &[Box<dyn Command>]) -> i32` that starts from `0`, applies each command in order, prints `"<description> -> <state>"` after each, and returns the final state. Solution ```rust 1 trait Command { 2 fn run(&self, state: &mut i32); 3 fn describe(&self) -> String; 4 } 5 6 struct Add(i32); 7 struct Mul(i32); 8 struct Reset; 9 10 impl Command for Add { 11 fn run(&self, state: &mut i32) { *state += self.0; } 12 fn describe(&self) -> String { format!("add {}", self.0) } 13 } 14 15 impl Command for Mul { 16 fn run(&self, state: &mut i32) { *state *= self.0; } 17 fn describe(&self) -> String { format!("mul {}", self.0) } 18 } 19 20 impl Command for Reset { 21 fn run(&self, state: &mut i32) { *state = 0; } 22 fn describe(&self) -> String { "reset".to_string() } 23 } 24 25 fn run_all(commands: &[Box<dyn Command>]) -> i32 { 26 let mut state = 0; 27 for command in commands { 28 command.run(&mut state); 29 println!("{:<8} -> {state}", command.describe()); 30 } 31 state 32 } 33 34 fn main() { 35 let program: Vec<Box<dyn Command>> = vec![ 36 Box::new(Add(5)), 37 Box::new(Mul(3)), 38 Box::new(Add(1)), 39 Box::new(Reset), 40 Box::new(Add(42)), 41 ]; 42 let final_state = run_all(&program); 43 println!("final = {final_state}"); 44 } ``` **Output:** ```text 1 add 5 -> 5 2 mul 3 -> 15 3 add 1 -> 16 4 reset -> 0 5 add 42 -> 42 6 final = 42 ``` The `Vec<Box<dyn Command>>` stores three different concrete types behind one fixed-size pointer type, exactly like a TypeScript `Command[]`. The difference: in Rust the boxing is explicit, ownership is single and clear, and each command is freed deterministically when the `Vec` drops. # Shared Ownership with `Rc<T>` and `Arc<T>` > Rc<T> and Arc<T> give a heap value multiple owners via reference counting, recreating JavaScript's shared references but freed deterministically at count zero. In TypeScript and JavaScript, sharing is invisible and free: assign an object to ten variables and all ten point at the same thing, with a garbage collector deciding when to clean up. Rust’s default ownership model is the opposite (one value, exactly one owner), so to get that “many references to one object” behavior on purpose you reach for a **reference-counted smart pointer**: `Rc<T>` for single-threaded code and `Arc<T>` for sharing across threads. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) `Rc<T>` (**reference counted**) and `Arc<T>` (**atomically reference counted**) are smart pointers that let a single heap-allocated value have **multiple owners**. Each pointer holds an integer count of how many owners exist; cloning the pointer bumps the count, dropping one lowers it, and when the count reaches zero the value is freed. For a TypeScript/JavaScript developer this is the closest Rust gets to “everything is a shared reference,” except the bookkeeping is a tiny counter the compiler manages deterministically, not a tracing garbage collector that runs whenever it feels like it. > **Note:** This page covers **shared ownership** specifically: `Rc` vs `Arc`, the strong count, and why cloning is cheap. The two reference-counting types are immutable on their own; to *mutate* shared data you combine them with the interior-mutability types in [Interior Mutability](/10-smart-pointers/02-refcell-mutex/). Breaking reference **cycles** (which `Rc`/`Arc` cannot do alone) is covered in [Weak References with `Weak<T>`](/10-smart-pointers/05-weak/). For heap allocation with a *single* owner, see [Box\<T>](/10-smart-pointers/00-box/). Section 05 has a gentler first introduction in [Reference Counting](/05-ownership/07-reference-counting/); this page assumes you have met the [ownership rules](/05-ownership/01-ownership-rules/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In JavaScript and TypeScript, object variables are references, and assignment shares the reference rather than copying the object. A configuration object can be handed to many parts of an application, and they all see — and reach — the same instance. ```typescript 1 // TypeScript/JavaScript: object references are shared implicitly 2 interface AppConfig { 3 serviceName: string; 4 featureFlags: string[]; 5 } 6 7 const config: AppConfig = { 8 serviceName: "checkout", 9 featureFlags: ["new-cart", "fast-pay"], 10 }; 11 12 // A handler holds the SAME config object, not a copy of it. 13 class Handler { 14 constructor( 15 public route: string, 16 public config: AppConfig, 17 ) {} 18 describe(): string { 19 return `${this.route} -> service=${this.config.serviceName}`; 20 } 21 } 22 23 const handlers = [ 24 new Handler("/cart", config), 25 new Handler("/pay", config), 26 new Handler("/health", config), 27 ]; 28 29 for (const h of handlers) { 30 console.log(h.describe()); 31 } 32 33 // You never count references and never free anything. When `config` and 34 // every `handler` become unreachable, the garbage collector reclaims the 35 // object — at some unspecified later time. ``` **Key points:** * Passing `config` into three `Handler`s does **not** copy it; all three hold a reference to one object. * There is no count you can read and no `free` to call. Cleanup is **non-deterministic**: the garbage collector decides when. * Any holder of the reference could mutate the shared object (`config.featureFlags.push(...)`) and the change would be visible to all. Rust will make that mutation explicit and opt-in. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust will not let you freely alias an owned value. That is the entire point of the [ownership rules](/05-ownership/01-ownership-rules/). To opt into shared ownership you wrap the value in `Rc<T>` and create additional owners with `Rc::clone`. Each clone is a cheap reference-count bump that hands back another owner pointing at the **same** allocation. ```rust 1 use std::rc::Rc; 2 3 // A read-only piece of shared context every request handler can see. 4 #[derive(Debug)] 5 struct AppConfig { 6 service_name: String, 7 feature_flags: Vec<String>, 8 } 9 10 struct Handler { 11 route: String, 12 config: Rc<AppConfig>, // shared ownership of the same config 13 } 14 15 impl Handler { 16 fn new(route: &str, config: &Rc<AppConfig>) -> Self { 17 Handler { 18 route: route.to_string(), 19 config: Rc::clone(config), // cheap: bump the count 20 } 21 } 22 23 fn describe(&self) -> String { 24 format!( 25 "{} -> service={}, flags={:?}", 26 self.route, self.config.service_name, self.config.feature_flags 27 ) 28 } 29 } 30 31 fn main() { 32 let config = Rc::new(AppConfig { 33 service_name: "checkout".to_string(), 34 feature_flags: vec!["new-cart".to_string(), "fast-pay".to_string()], 35 }); 36 37 let handlers = vec![ 38 Handler::new("/cart", &config), 39 Handler::new("/pay", &config), 40 Handler::new("/health", &config), 41 ]; 42 43 // 1 original + 3 handlers all sharing one allocation. 44 println!("config shared by {} owners", Rc::strong_count(&config)); 45 46 for h in &handlers { 47 println!("{}", h.describe()); 48 } 49 50 // Dropping all handlers releases their handles; only `config` remains. 51 drop(handlers); 52 println!("after handlers dropped: {} owner", Rc::strong_count(&config)); 53 } ``` **Real output:** ```text 1 config shared by 4 owners 2 /cart -> service=checkout, flags=["new-cart", "fast-pay"] 3 /pay -> service=checkout, flags=["new-cart", "fast-pay"] 4 /health -> service=checkout, flags=["new-cart", "fast-pay"] 5 after handlers dropped: 1 owner ``` The data lives once on the heap. The `Vec<Handler>` and the original `config` variable together own four handles to it; when the `Vec` is dropped, three handles go away and the count drops to one. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) Let’s walk through what each piece does and contrast it with the JavaScript version. ### `Rc::new(value)` — move the value onto the heap and start counting [Section titled “Rc::new(value) — move the value onto the heap and start counting”](#rcnewvalue--move-the-value-onto-the-heap-and-start-counting) ```rust 1 let config = Rc::new(AppConfig { /* ... */ }); ``` `Rc::new` takes ownership of the `AppConfig`, allocates it on the heap alongside a counter, and returns an `Rc<AppConfig>`, a pointer whose **strong count** starts at `1`. In JavaScript the object was already on the GC heap with no visible counter; in Rust the allocation and the counter are explicit and tied together. ### `Rc::clone(&config)` — add an owner, don’t copy the data [Section titled “Rc::clone(\&config) — add an owner, don’t copy the data”](#rccloneconfig--add-an-owner-dont-copy-the-data) ```rust 1 config: Rc::clone(config), // `config` here is the &Rc passed into `new` ``` This is the line that trips up newcomers. `Rc::clone` does **not** deep-copy the `AppConfig`. It increments the strong count and returns a new `Rc` pointing at the *same* heap allocation. That is why the output shows four owners of one allocation rather than four separate configs. It is the same sharing you got for free in JavaScript, only here it is named and counted. > **Tip:** The idiom is `Rc::clone(&x)` (fully-qualified) rather than `x.clone()`. Both do exactly the same thing — a cheap ref-count bump — but the explicit form signals to a reader “this is a shared-ownership bump, not an expensive deep clone.” The standard library and Clippy both encourage it. ### `Rc::strong_count(&config)` — read the live owner count [Section titled “Rc::strong\_count(\&config) — read the live owner count”](#rcstrong_countconfig--read-the-live-owner-count) ```rust 1 Rc::strong_count(&config) // -> 4, then 1 after the handlers drop ``` `strong_count` returns how many `Rc` handles currently point at the allocation. It is an associated function (`Rc::strong_count(&x)`), not a method, again to avoid colliding with methods on the wrapped type. There is no equivalent in JavaScript: the GC’s reference graph is not something you can query at runtime. ### `drop(handlers)` — release owners; data freed only at zero [Section titled “drop(handlers) — release owners; data freed only at zero”](#drophandlers--release-owners-data-freed-only-at-zero) When the `Vec<Handler>` is dropped, each `Handler` is dropped, each one’s `Rc<AppConfig>` field is dropped, and each drop decrements the count. The `AppConfig` itself is freed **only** when the count reaches zero, which here it never does, because `config` still holds the last handle. This is RAII reference counting: deterministic, tied to scope, and visible in the code. ### Accessing the data — `Deref` makes it transparent [Section titled “Accessing the data — Deref makes it transparent”](#accessing-the-data--deref-makes-it-transparent) Notice `self.config.service_name`: you read fields straight through the `Rc` as if it were the `AppConfig`. `Rc<T>` implements `Deref` to `T`, so `&Rc<AppConfig>` coerces to `&AppConfig` automatically (the mechanics live in [The `Deref` Trait and Deref Coercion](/10-smart-pointers/06-deref-trait/)). The catch: `Deref` gives you a **shared** `&T`, never `&mut T` — shared ownership is read-only by default, which is why mutation needs the extra tools mentioned below. *** ## `Rc` vs `Arc`: single-threaded vs thread-safe [Section titled “Rc vs Arc: single-threaded vs thread-safe”](#rc-vs-arc-single-threaded-vs-thread-safe) `Rc` and `Arc` have an almost identical API. The difference is *how the counter is updated*: * `Rc<T>` uses an ordinary integer increment/decrement. This is fast but not safe if two threads touch the count at once, so `Rc<T>` is deliberately **not** `Send`/`Sync`: the compiler refuses to let it cross a thread boundary. * `Arc<T>` updates the count with **atomic** CPU instructions, which makes sharing across threads safe. Atomics cost a little more than a plain increment, which is the only reason `Rc` still exists: don’t pay for thread-safety you don’t use. Here is `Arc<T>` shared across threads. Swap `use std::rc::Rc` for `use std::sync::Arc` and the shape is the same: ```rust 1 use std::sync::Arc; 2 use std::thread; 3 4 #[derive(Debug)] 5 struct Config { 6 base_url: String, 7 retries: u32, 8 } 9 10 fn main() { 11 // Arc = Atomically Reference Counted. Same API as Rc, but the count 12 // is updated atomically so it is safe to share across threads. 13 let config = Arc::new(Config { 14 base_url: String::from("https://api.example.com"), 15 retries: 3, 16 }); 17 18 let mut handles = Vec::new(); 19 for worker_id in 0..3 { 20 // Each thread gets its own owning handle (a cheap ref-count bump). 21 let config = Arc::clone(&config); 22 let handle = thread::spawn(move || { 23 // The thread reads the shared config without copying it. 24 println!( 25 "worker {worker_id}: {} (retries={})", 26 config.base_url, config.retries 27 ); 28 }); 29 handles.push(handle); 30 } 31 32 for handle in handles { 33 handle.join().unwrap(); 34 } 35 36 // Every worker has finished and dropped its handle, so only the 37 // original owner remains. 38 println!("final count = {}", Arc::strong_count(&config)); 39 } ``` **Real output** (worker order varies; threads race): ```text 1 worker 1: https://api.example.com (retries=3) 2 worker 2: https://api.example.com (retries=3) 3 worker 0: https://api.example.com (retries=3) 4 final count = 1 ``` Each thread `move`s its own `Arc` handle into the closure (`let config = Arc::clone(&config);` shadows the outer name with a fresh owner). After all threads `join`, their handles have been dropped and the count is back to `1`. > **Note:** JavaScript has no real shared-memory threading for plain objects. Web Workers and Node `worker_threads` communicate by *copying* messages (structured clone) or via the low-level `SharedArrayBuffer`. `Arc<T>` is genuine shared memory across OS threads, with the borrow checker guaranteeing there are no data races. Threads themselves are covered more in [Section 11: Async and Concurrency](/11-async/). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript | Rust `Rc<T>` / `Arc<T>` | | -------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | How sharing happens | Implicit: every object variable is a shared reference | Explicit: wrap in `Rc`/`Arc`, share with `::clone` | | Cleanup timing | Non-deterministic (tracing GC) | Deterministic: freed the instant the count hits zero | | Can you read the count? | No | Yes: `Rc::strong_count(&x)` / `Arc::strong_count(&x)` | | Cost of “copying” a handle | Reference assignment | Count increment (atomic for `Arc`); data not copied | | Mutation through a shared handle | Allowed by default | **Not** allowed by default; needs `RefCell`/`Mutex` ([Interior Mutability](/10-smart-pointers/02-refcell-mutex/)) | | Cross-thread sharing | Workers copy messages; `SharedArrayBuffer` for bytes | `Arc<T>` is real shared memory, race-free at compile time | | Reference cycles | Collected by tracing GC | **Leak**: must break with `Weak<T>` ([Weak References with `Weak<T>`](/10-smart-pointers/05-weak/)) | ### Why two types instead of one? [Section titled “Why two types instead of one?”](#why-two-types-instead-of-one) A common question: why not always use `Arc` and forget `Rc`? Because atomic operations have a real (if small) cost, and the *common* case — sharing within one thread — does not need them. Rust’s philosophy is “zero-cost abstractions”: you opt into thread-safety only when you actually share across threads. The compiler enforces the boundary, so you cannot accidentally use the cheaper `Rc` where `Arc` was required (see the first pitfall below). ### Shared ownership is read-only [Section titled “Shared ownership is read-only”](#shared-ownership-is-read-only) This is the biggest surprise coming from JavaScript, where you can freely mutate a shared object. Both `Rc<T>` and `Arc<T>` only hand out shared (`&T`) access. That is a direct consequence of the borrow checker’s one-mutable-XOR-many-shared rule: if many owners can read the data, none may mutate it through the pointer. To mutate shared data you wrap the inner value in a cell type — `Rc<RefCell<T>>` (single-thread) or `Arc<Mutex<T>>` (multi-thread) — which moves the borrow check to runtime. That combination is the subject of [Interior Mutability](/10-smart-pointers/02-refcell-mutex/). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Trying to send an `Rc` across threads [Section titled “Pitfall 1: Trying to send an Rc across threads”](#pitfall-1-trying-to-send-an-rc-across-threads) A natural mistake is to share an `Rc` with a spawned thread. The compiler stops you, because `Rc`’s non-atomic counter is not thread-safe. ```rust 1 use std::rc::Rc; 2 use std::thread; 3 4 fn main() { 5 let data = Rc::new(vec![1, 2, 3]); 6 let data2 = Rc::clone(&data); 7 8 // does not compile (error[E0277]: `Rc<Vec<i32>>` cannot be sent between threads safely) 9 let handle = thread::spawn(move || { 10 println!("{:?}", data2); 11 }); 12 13 handle.join().unwrap(); 14 println!("{:?}", data); 15 } ``` **Real compiler error (abridged):** ```text 1 error[E0277]: `Rc<Vec<i32>>` cannot be sent between threads safely 2 --> src/main.rs:9:32 3 | 4 9 | let handle = thread::spawn(move || { 5 | ------------- ^------ 6 | | | 7 | __________________|_____________within this `{closure@src/main.rs:9:32: 9:39}` 8 | | | 9 | | required by a bound introduced by this call 10 ... 11 = help: within `{closure@src/main.rs:9:32: 9:39}`, the trait `Send` is not implemented for `Rc<Vec<i32>>` 12 note: required by a bound in `spawn` ``` **Fix:** swap `Rc` for `Arc` (and `std::rc::Rc` for `std::sync::Arc`). The error literally points at the missing `Send` bound; the cure is the thread-safe variant. ### Pitfall 2: Expecting `.clone()` to copy the data [Section titled “Pitfall 2: Expecting .clone() to copy the data”](#pitfall-2-expecting-clone-to-copy-the-data) ```rust 1 let original = Rc::new(vec![1, 2, 3]); 2 let alias = Rc::clone(&original); 3 // `alias` is NOT an independent Vec — it points at the SAME one. ``` If you genuinely want a separate copy of the inner data, clone the inner value, not the `Rc`: `let independent = (*original).clone();` (or `original.as_ref().clone()`). Reflexively writing `original.clone()` and expecting a deep copy is a TypeScript-shaped assumption: `Rc`’s clone is the cheap, sharing kind. ### Pitfall 3: Trying to mutate through an `Rc` [Section titled “Pitfall 3: Trying to mutate through an Rc”](#pitfall-3-trying-to-mutate-through-an-rc) ```rust 1 use std::rc::Rc; 2 3 fn main() { 4 let counter = Rc::new(0_i32); 5 let _other = Rc::clone(&counter); 6 7 // does not compile (error[E0594]: cannot assign to data in an `Rc`) 8 *counter += 1; 9 } ``` **Real compiler error:** ```text 1 error[E0594]: cannot assign to data in an `Rc` 2 --> src/main.rs:8:5 3 | 4 8 | *counter += 1; 5 | ^^^^^^^^^^^^^ cannot assign 6 | 7 = help: trait `DerefMut` is required to modify through a dereference, but it is not implemented for `Rc<i32>` ``` **Fix:** shared ownership is read-only. For a mutable shared counter use `Rc<RefCell<i32>>` (single-thread) or `Arc<Mutex<i32>>` / an atomic type (multi-thread). See [Interior Mutability](/10-smart-pointers/02-refcell-mutex/). ### Pitfall 4: Creating a reference cycle (a silent memory leak) [Section titled “Pitfall 4: Creating a reference cycle (a silent memory leak)”](#pitfall-4-creating-a-reference-cycle-a-silent-memory-leak) `Rc`/`Arc` are reference counters, **not** a tracing garbage collector. If two `Rc`s point at each other — a parent holding a child that holds the parent back — neither count ever reaches zero and the memory leaks, even though both are unreachable. JavaScript’s GC handles cycles automatically; Rust’s counter cannot. ```rust 1 // Conceptual: A owns B, B owns A. Both strong counts stay >= 1 forever. 2 // The cure is to make one direction a Weak<T> (a non-owning handle). ``` This is important enough to have its own page: [Weak References with `Weak<T>`](/10-smart-pointers/05-weak/) shows how `Weak<T>` and `upgrade()` break cycles in a parent/child graph. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Prefer borrowing first.** Reach for `Rc`/`Arc` only when a value genuinely has *no single owner*: a node shared by many edges, an immutable config many components hold. If one part of the code can own the data and everyone else can borrow `&T`, that is simpler and faster. Don’t sprinkle `Arc` everywhere to “make the borrow checker happy.” * **Use `Rc::clone(&x)` / `Arc::clone(&x)`, not `x.clone()`.** Functionally identical, but the explicit form reads as “cheap ref-count bump” rather than a potentially expensive deep clone. (The Clippy lint `clippy::clone_on_ref_ptr` enforces this; it is allow-by-default, so enable it if your team wants the discipline.) * **Default to `Rc`; upgrade to `Arc` only when crossing threads.** Don’t pay for atomics you don’t need. The compiler forces the upgrade when you actually share across threads, so starting with `Rc` is safe: you’ll get a clear error if it ever needs to be `Arc`. * **`Rc<RefCell<T>>` and `Arc<Mutex<T>>` are the standard “shared *and* mutable” combos.** When you see one of these patterns, read it as “many owners, with interior mutability.” Keep `Arc<Mutex<_>>` for threads and `Rc<RefCell<_>>` for single-threaded code: they don’t mix. * **Watch for cycles in graph-shaped data.** Any time an `Rc`/`Arc` can transitively point back at itself (trees with parent pointers, doubly linked lists, observer graphs), make the back-edge a `Weak<T>`. See [Weak References with `Weak<T>`](/10-smart-pointers/05-weak/). * **`strong_count` is for understanding and debugging, not control flow.** It is great in tests and `println!` debugging; avoid branching on it in production logic, especially with `Arc`, where the count can change between the read and your next line. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A practical, single-threaded scenario: a small interpreter or template engine where many evaluation nodes need read access to one shared, immutable environment (interned strings, built-in functions, configuration). Cloning the whole environment per node would be wasteful; borrowing would tangle lifetimes through the whole tree. Shared ownership via `Rc` is the clean fit, and `Drop` lets us *see* the deterministic cleanup. ```rust 1 use std::rc::Rc; 2 3 /// Read-only environment shared by every node in an evaluation tree. 4 #[derive(Debug)] 5 struct Environment { 6 name: String, 7 builtins: Vec<String>, 8 } 9 10 impl Drop for Environment { 11 fn drop(&mut self) { 12 // Proves the allocation is freed exactly once, at count zero. 13 println!("[freed] Environment({})", self.name); 14 } 15 } 16 17 /// A node that evaluates against the shared environment. 18 struct Node { 19 label: String, 20 env: Rc<Environment>, 21 } 22 23 impl Node { 24 fn new(label: &str, env: &Rc<Environment>) -> Self { 25 Node { 26 label: label.to_string(), 27 env: Rc::clone(env), 28 } 29 } 30 31 fn eval(&self) { 32 println!( 33 "node {:>6} can call {} builtins from env '{}'", 34 self.label, 35 self.env.builtins.len(), 36 self.env.name 37 ); 38 } 39 } 40 41 fn main() { 42 let env = Rc::new(Environment { 43 name: "global".to_string(), 44 builtins: vec!["len".to_string(), "print".to_string(), "map".to_string()], 45 }); 46 47 // Build a little tree of nodes, all sharing the one environment. 48 let nodes = vec![ 49 Node::new("expr-1", &env), 50 Node::new("expr-2", &env), 51 Node::new("expr-3", &env), 52 ]; 53 54 println!("env owners: {}", Rc::strong_count(&env)); // 1 + 3 = 4 55 56 for node in &nodes { 57 node.eval(); 58 } 59 60 // Drop the original handle: count goes 4 -> 3. NOT freed yet, 61 // because the nodes still own handles. 62 drop(env); 63 println!("dropped original handle; tree still holds the env"); 64 65 // When `nodes` goes out of scope at the end of main, the last three 66 // handles drop, the count hits zero, and Environment::drop runs once. 67 println!("end of main: nodes about to drop..."); 68 } ``` **Real output:** ```text 1 env owners: 4 2 node expr-1 can call 3 builtins from env 'global' 3 node expr-2 can call 3 builtins from env 'global' 4 node expr-3 can call 3 builtins from env 'global' 5 dropped original handle; tree still holds the env 6 end of main: nodes about to drop... 7 [freed] Environment(global) ``` The `[freed]` line printing **last** — after `drop(env)`, not at it — is the whole point: dropping one owner only lowers the count. The `Environment` is freed exactly once, deterministically, when the final owner (inside `nodes`) goes away at the end of `main`. No garbage collector, no double-free, no leak. > **Tip:** For the multi-threaded version of this exact pattern — say worker threads sharing one immutable lookup table — change `Rc` to `Arc` and `std::rc::Rc` to `std::sync::Arc`. Everything else stays the same; that symmetry is deliberate. *** ## Further Reading [Section titled “Further Reading”](#further-reading) **Official documentation** * [`std::rc::Rc`](https://doc.rust-lang.org/std/rc/struct.Rc.html) — the single-threaded reference-counted pointer * [`std::sync::Arc`](https://doc.rust-lang.org/std/sync/struct.Arc.html) — the atomic, thread-safe variant * [The Rust Book, ch. 15.4 — `Rc<T>`, the Reference Counted Smart Pointer](https://doc.rust-lang.org/book/ch15-04-rc.html) * [The Rust Book, ch. 16.3 — Shared-State Concurrency](https://doc.rust-lang.org/book/ch16-03-shared-state.html) (where `Arc<Mutex<T>>` appears) * [`Send` and `Sync`](https://doc.rust-lang.org/std/marker/trait.Send.html) — the marker traits that decide what may cross threads **Related sections in this guide** * [Box\<T>](/10-smart-pointers/00-box/) — `Box<T>` for single-owner heap allocation (the contrast to shared ownership) * [Interior Mutability](/10-smart-pointers/02-refcell-mutex/) — adding interior mutability: `Rc<RefCell<T>>` and `Arc<Mutex<T>>` * [Weak References with `Weak<T>`](/10-smart-pointers/05-weak/) — `Weak<T>` to break the reference cycles `Rc`/`Arc` cannot * [The `Deref` Trait and Deref Coercion](/10-smart-pointers/06-deref-trait/) — why you can read fields straight through an `Rc` * [Choosing a Smart Pointer](/10-smart-pointers/07-comparison/) — a decision table for choosing among all the smart pointers * [Section 05 — Reference Counting](/05-ownership/07-reference-counting/) — the first, gentler introduction * [Section 05 — The Ownership Rules](/05-ownership/01-ownership-rules/) and [Move, Copy, and Clone](/05-ownership/06-move-copy-clone/) — the foundation this builds on * [Section 11 — Async and Concurrency](/11-async/) — where `Arc` is used heavily *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Share a dictionary among readers [Section titled “Exercise 1: Share a dictionary among readers”](#exercise-1-share-a-dictionary-among-readers) **Difficulty:** Easy **Objective:** Get comfortable with `Rc::new`, `Rc::clone`, and `Rc::strong_count`. **Instructions:** 1. Create an `Rc<Vec<String>>` holding a few words (a shared dictionary). 2. Create two additional reader handles with `Rc::clone`. 3. Print the strong count (it should be `3`), then read an element through each reader. 4. `drop` one reader and print the count again (it should be `2`). Solution ```rust 1 use std::rc::Rc; 2 3 fn main() { 4 let dictionary = Rc::new(vec![ 5 "alpha".to_string(), 6 "bravo".to_string(), 7 "charlie".to_string(), 8 ]); 9 10 let reader_a = Rc::clone(&dictionary); 11 let reader_b = Rc::clone(&dictionary); 12 13 println!("count = {}", Rc::strong_count(&dictionary)); // 3 14 println!("a[0] = {}", reader_a[0]); 15 println!("b[2] = {}", reader_b[2]); 16 17 drop(reader_a); 18 println!("count after one drop = {}", Rc::strong_count(&dictionary)); // 2 19 // reader_b is still owned here and lives to the end of `main`, keeping the 20 // count at 2. (Binding it to `_` would drop it immediately, so we don't.) 21 } ``` **Output:** ```text 1 count = 3 2 a[0] = alpha 3 b[2] = charlie 4 count after one drop = 2 ``` ### Exercise 2: Observe deterministic cleanup [Section titled “Exercise 2: Observe deterministic cleanup”](#exercise-2-observe-deterministic-cleanup) **Difficulty:** Medium **Objective:** Prove to yourself that the inner value is freed exactly once, at the moment the count reaches zero, not before. **Instructions:** 1. Define a `struct Resource { label: String }` and implement `Drop` for it so that dropping prints `dropping Resource(<label>)`. 2. Wrap one `Resource` in an `Rc` and make a second handle with `Rc::clone`. 3. `drop` the first handle and print a line afterward. Confirm (by output order) that the `Resource` is **not** dropped yet. 4. `drop` the second handle and confirm the `Resource` is dropped only now. Solution ```rust 1 use std::rc::Rc; 2 3 struct Resource { 4 label: String, 5 } 6 7 impl Drop for Resource { 8 fn drop(&mut self) { 9 println!("dropping Resource({})", self.label); 10 } 11 } 12 13 fn main() { 14 let a = Rc::new(Resource { label: "db-pool".into() }); 15 println!("count = {}", Rc::strong_count(&a)); // 1 16 17 let b = Rc::clone(&a); 18 println!("count = {}", Rc::strong_count(&a)); // 2 19 20 drop(a); // count -> 1, Resource NOT dropped yet 21 println!("after drop(a): still alive, count via b = {}", Rc::strong_count(&b)); 22 23 drop(b); // count -> 0, NOW the Resource is dropped 24 println!("after drop(b): done"); 25 } ``` **Output:** ```text 1 count = 1 2 count = 2 3 after drop(a): still alive, count via b = 1 4 dropping Resource(db-pool) 5 after drop(b): done ``` The `dropping Resource(db-pool)` line appears between `drop(b)` and the final print, proving cleanup happened exactly at count zero. ### Exercise 3: Parallel sum over a shared dataset [Section titled “Exercise 3: Parallel sum over a shared dataset”](#exercise-3-parallel-sum-over-a-shared-dataset) **Difficulty:** Hard **Objective:** Share one immutable dataset across multiple threads with `Arc`, and confirm the count returns to `1` after the threads finish. **Instructions:** 1. Build an `Arc<Vec<u64>>` containing the numbers `1..=1000`. 2. Spawn 4 threads. Give each its own `Arc::clone` and a distinct slice range of the data. 3. Each thread sums its slice and returns the partial sum from the closure. 4. `join` all threads, add the partial sums (expected total: `500500`), and print the final strong count (should be `1`). > **Hint:** `Arc::clone(&data)` inside the loop, then `move` the clone into the closure. Index the slice with `data[start..end]`. Solution ```rust 1 use std::sync::Arc; 2 use std::thread; 3 4 fn main() { 5 let data: Arc<Vec<u64>> = Arc::new((1..=1000).collect()); 6 let chunk = data.len() / 4; 7 8 let mut handles = Vec::new(); 9 for i in 0..4 { 10 let data = Arc::clone(&data); // each thread's own owning handle 11 let start = i * chunk; 12 let end = if i == 3 { data.len() } else { start + chunk }; 13 handles.push(thread::spawn(move || { 14 let partial: u64 = data[start..end].iter().sum(); 15 partial 16 })); 17 } 18 19 let total: u64 = handles.into_iter().map(|h| h.join().unwrap()).sum(); 20 println!("total = {total}"); 21 println!("owners remaining = {}", Arc::strong_count(&data)); 22 } ``` **Output:** ```text 1 total = 500500 2 owners remaining = 1 ``` After every thread joins, its `Arc` handle has been dropped, so only the original owner remains, and the count is back to `1`. # Interior Mutability: `RefCell<T>` and `Mutex<T>` > RefCell<T> and Mutex<T> let Rust mutate through a shared reference by moving the borrow check to runtime: RefCell panics, Mutex blocks across threads. In TypeScript every object is freely mutable through any reference you hold — aliasing and mutation coexist without comment. Rust forbids that at compile time: you may have *many* shared `&` references **or** *one* exclusive `&mut`, never both. **Interior mutability** is the escape hatch that lets you mutate data through a shared reference anyway, by moving the “one writer, many readers” check from compile time to runtime. `RefCell<T>` does this on a single thread; `Mutex<T>` does it across threads. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) `RefCell<T>` and `Mutex<T>` both let you mutate data you only hold a shared reference to (`&self` rather than `&mut self`). They enforce the same rule the borrow checker enforces statically — no aliased mutation — but they enforce it **dynamically**. `RefCell` checks on the current thread and **panics** if you break the rule; `Mutex` is thread-safe and **blocks** until the data is free. For a TypeScript developer the mental model is: these types give you back the casual “mutate through any handle” feeling of JavaScript objects, but with a guardrail that fails loudly instead of silently corrupting data. > **Note:** This file covers the two *checked* interior-mutability containers. Its single-threaded sibling for `Copy` values, [`Cell<T>`](/10-smart-pointers/03-cell/), needs no runtime flag at all. For *sharing* the same data between owners (the thing you almost always combine `RefCell`/`Mutex` with) see [`Rc<T>` / `Arc<T>`](/10-smart-pointers/01-rc-arc/). When you cannot decide which container to reach for, jump to the [decision guide](/10-smart-pointers/07-comparison/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript, a shared mutable object is the default. Here a `MetricsCollector` is handed to several subsystems; each holds the *same* object and mutates it freely. Nothing in the type system stops two code paths from writing at “the same time.” JavaScript’s single-threaded event loop makes that mostly safe, and TypeScript never asks you to think about it. ```typescript 1 // TypeScript/JavaScript - shared mutable state is the default 2 class MetricsCollector { 3 private counts = new Map<string, number>(); 4 5 // `increment` mutates internal state, but callers never see a difference 6 // between a "read" method and a "write" method — both just take `this`. 7 increment(event: string): void { 8 this.counts.set(event, (this.counts.get(event) ?? 0) + 1); 9 } 10 11 total(): number { 12 let sum = 0; 13 for (const n of this.counts.values()) sum += n; 14 return sum; 15 } 16 } 17 18 const metrics = new MetricsCollector(); 19 20 // Two unrelated subsystems share the SAME collector via aliasing. 21 const auth = metrics; 22 const api = metrics; 23 24 auth.increment("login"); 25 api.increment("request"); 26 api.increment("request"); 27 28 console.log(metrics.total()); // 3 ``` Under Node v22 this prints `3`. Note three things a Rust developer will care about: the two aliases (`auth`, `api`) point at one object, `increment` mutates through a plain shared reference, and nobody had to declare the object “mutable.” *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The naive port fails: if `record` takes `&self`, you cannot assign to `self.hits`. Wrapping the field in `RefCell<T>` restores the ability to mutate through a shared reference: `borrow_mut()` hands you a temporary exclusive handle, checked at runtime. ```rust 1 use std::cell::RefCell; 2 3 #[derive(Debug)] 4 struct Counter { 5 hits: RefCell<u32>, 6 } 7 8 impl Counter { 9 fn new() -> Self { 10 Counter { hits: RefCell::new(0) } 11 } 12 13 // Note: &self, NOT &mut self — the mutation happens "inside" the cell. 14 fn record(&self) { 15 *self.hits.borrow_mut() += 1; 16 } 17 18 fn total(&self) -> u32 { 19 *self.hits.borrow() 20 } 21 } 22 23 fn main() { 24 let counter = Counter::new(); 25 counter.record(); 26 counter.record(); 27 counter.record(); 28 println!("total hits = {}", counter.total()); 29 } ``` Running it prints: ```text 1 total hits = 3 ``` The signature `fn record(&self)` is the whole point. The method takes a *shared* reference, yet mutates, exactly the TypeScript ergonomics, but the mutation is funneled through `RefCell`’s runtime check rather than being a free-for-all. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Why the compiler refuses plain mutation through `&self` [Section titled “Why the compiler refuses plain mutation through \&self”](#why-the-compiler-refuses-plain-mutation-through-self) Rust’s borrowing rules are not a style guide; they are how the language guarantees memory safety without a garbage collector (see [Section 05 — Ownership](/05-ownership/)). The rule: at any instant a value has either **one** `&mut` reference or **any number** of `&` references. A method taking `&self` only has a shared reference, so writing to a field is rejected: ```rust 1 struct Logger { 2 count: u32, // plain field, no interior mutability 3 } 4 5 impl Logger { 6 fn log(&self, msg: &str) { 7 println!("{msg}"); 8 self.count += 1; // does not compile (error[E0594]): cannot assign through &self 9 } 10 } 11 12 fn main() { 13 let logger = Logger { count: 0 }; 14 logger.log("hi"); 15 } ``` The real compiler output: ```text 1 error[E0594]: cannot assign to `self.count`, which is behind a `&` reference 2 --> src/main.rs:8:9 3 | 4 8 | self.count += 1; // does not compile (error[E0594]): cannot assign through &self 5 | ^^^^^^^^^^^^^^^ `self` is a `&` reference, so the data it refers to cannot be written 6 | 7 help: consider changing this to be a mutable reference 8 | 9 6 | fn log(&mut self, msg: &str) { 10 | +++ ``` Sometimes `&mut self` *is* the right fix. But it is contagious: every caller now needs exclusive access, which is impossible the moment the value is shared (behind an `Rc`, stored in a `Vec` you are iterating, captured by two closures). `RefCell` is the answer when you need the mutation but cannot get exclusive access at compile time. ### What `borrow` and `borrow_mut` actually return [Section titled “What borrow and borrow\_mut actually return”](#what-borrow-and-borrow_mut-actually-return) `RefCell<T>` is a struct holding your `T` plus a small integer “borrow flag.” Two methods read and update that flag: * `borrow() -> Ref<'_, T>`: registers a *shared* borrow and returns a smart-pointer guard that derefs to `&T`. * `borrow_mut() -> RefMut<'_, T>`: registers an *exclusive* borrow and returns a guard that derefs to `&mut T`. The guard’s `Drop` releases the borrow. So the flag tracks “how many `Ref`s and whether a `RefMut` is alive” exactly the way the compiler’s static analysis would, just at runtime. The `*self.hits.borrow_mut() += 1` line creates a `RefMut`, dereferences it to a `&mut u32`, increments, and drops the guard at the end of the statement (the temporary’s lifetime ends at the `;`). ### Runtime checking means runtime *panics* [Section titled “Runtime checking means runtime panics”](#runtime-checking-means-runtime-panics) If you violate the one-writer rule, `RefCell` does not return an error by default; it panics, the same way an out-of-bounds array index does. Holding a read borrow and then asking for a write borrow: ```rust 1 use std::cell::RefCell; 2 3 fn main() { 4 let cell = RefCell::new(vec![1, 2, 3]); 5 6 let reader = cell.borrow(); // Ref<Vec<i32>>, a shared read borrow 7 println!("len is {}", reader.len()); 8 cell.borrow_mut().push(4); // panics: reader is still alive 9 } ``` The real output: ```text 1 len is 3 2 3 thread 'main' panicked at src/main.rs:8:10: 4 already borrowed: BorrowMutError 5 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` `reader` is still in scope when `borrow_mut()` runs, so the borrow flag says “a shared borrow is active” and the write request panics. The fix is to end the read borrow first: drop `reader` or scope it in a `{ }` block. ### `Mutex<T>`: the same idea, made thread-safe [Section titled “Mutex\<T>: the same idea, made thread-safe”](#mutext-the-same-idea-made-thread-safe) `RefCell` is **not** thread-safe (it is `!Sync`), so the compiler will not let you share one across threads. When you need interior mutability *across* threads, reach for `std::sync::Mutex<T>`. It enforces the identical rule — one writer at a time — but instead of panicking when the data is busy, `lock()` **blocks** the calling thread until the lock is free. ```rust 1 use std::sync::{Arc, Mutex}; 2 use std::thread; 3 4 fn main() { 5 let counter = Arc::new(Mutex::new(0u64)); 6 let mut handles = Vec::new(); 7 8 for _ in 0..8 { 9 let counter = Arc::clone(&counter); 10 let handle = thread::spawn(move || { 11 for _ in 0..1000 { 12 // lock() blocks until the mutex is free, returns a guard. 13 let mut n = counter.lock().unwrap(); 14 *n += 1; 15 } // guard dropped here -> lock released each iteration 16 }); 17 handles.push(handle); 18 } 19 20 for h in handles { 21 h.join().unwrap(); 22 } 23 24 println!("final count = {}", *counter.lock().unwrap()); 25 } ``` Running it prints: ```text 1 final count = 8000 ``` Eight threads each increment 1000 times; the `Mutex` serializes every `*n += 1`, so the result is exactly `8000` with no lost updates. The `Arc` (atomic reference count) is what lets all eight threads *own* the same mutex. `Mutex` provides the mutation, `Arc` provides the sharing. This `Arc<Mutex<T>>` pair is to multithreaded Rust what a plain shared object is to JavaScript. > **Tip:** `lock()` returns a `Result` because the mutex can be *poisoned* (see Pitfalls). In application code, `.unwrap()` (or `.expect("lock poisoned")`) is the common, accepted choice: a poisoned lock usually means another thread already crashed. ### Holding the guard for as little time as possible [Section titled “Holding the guard for as little time as possible”](#holding-the-guard-for-as-little-time-as-possible) A `MutexGuard` (and a `RefMut`) keeps the lock until it is dropped. Wrapping the locked work in a block releases it early, before any expensive non-locked work runs: ```rust 1 use std::sync::Mutex; 2 3 fn main() { 4 let data = Mutex::new(vec![10, 20, 30]); 5 6 let sum: i32 = { 7 let guard = data.lock().unwrap(); 8 guard.iter().sum() 9 }; // guard dropped here, before the println formatting below 10 11 println!("sum = {}", sum); 12 } ``` Output: ```text 1 sum = 60 ``` ### When you *do* have exclusive access, skip the lock [Section titled “When you do have exclusive access, skip the lock”](#when-you-do-have-exclusive-access-skip-the-lock) If you own a `Mutex<T>` by `&mut` (or by value), the compiler has already proven no other thread can touch it, so locking is pure overhead. `get_mut()` (borrow) and `into_inner()` (by value) reach the data without any locking: ```rust 1 use std::sync::Mutex; 2 3 fn main() { 4 let mut m = Mutex::new(0); 5 // We own `m` mutably, so the compiler proves no other thread can race. 6 *m.get_mut().unwrap() += 100; 7 println!("value = {}", m.into_inner().unwrap()); 8 } ``` Output: ```text 1 value = 100 ``` This mirrors `RefCell::get_mut`, and it is a good signal of intent: it tells the reader “no contention is possible here.” *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / JavaScript | `RefCell<T>` (Rust) | `Mutex<T>` (Rust) | | ---------------------------- | ----------------------- | --------------------------- | --------------------------- | | Mutate via shared handle | Always allowed | Allowed, runtime-checked | Allowed, runtime-checked | | Aliased mutation rule | None enforced | One writer XOR many readers | One writer at a time | | When the rule is broken | Possible silent bug | **Panics** immediately | (Cannot — it blocks) | | Thread-safe? | N/A (single event loop) | No (`!Sync`) | Yes (`Send + Sync`) | | Cost when uncontended | n/a | A few integer ops | An atomic compare-and-swap | | Get exclusive access cheaply | n/a | `get_mut()` | `get_mut()`, `into_inner()` | | Typical pairing for sharing | just alias the object | `Rc<RefCell<T>>` | `Arc<Mutex<T>>` | A few conceptual contrasts worth internalizing: * **Compile-time vs runtime.** Rust’s default borrow checking is static and free. `RefCell` and `Mutex` *opt into* a runtime check, paying a little performance and (for `RefCell`) the risk of a panic, in exchange for flexibility the static checker cannot express. * **Panic vs block.** This is the headline difference between the two types. A second `borrow_mut` on a busy `RefCell` is a *bug* and panics. A second `lock` on a busy `Mutex` is *normal contention* and waits. They feel similar but model opposite situations. * **`Mutex<T>` wraps the data, it is not a separate object.** Unlike a Java `synchronized` block or a free-standing lock variable, a Rust `Mutex` *contains* the data it protects. You literally cannot read the value without locking: the type system makes “forgot to take the lock” impossible. * **Unlike TypeScript,** sharing and mutating are separate concerns with separate tools. JavaScript gives you both in one move (alias an object). Rust makes you pick a *sharer* (`Rc`/`Arc`) and a *mutator* (`RefCell`/`Mutex`) and compose them. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Two live `borrow_mut`s on the same thread [Section titled “Pitfall 1: Two live borrow\_muts on the same thread”](#pitfall-1-two-live-borrow_muts-on-the-same-thread) The single most common `RefCell` mistake, taking a second mutable borrow while the first is alive: ```rust 1 use std::cell::RefCell; 2 3 fn main() { 4 let cell = RefCell::new(5); 5 6 let mut first = cell.borrow_mut(); 7 let mut second = cell.borrow_mut(); // panics: already mutably borrowed 8 *first += 1; 9 *second += 1; 10 } ``` Real output: ```text 1 thread 'main' panicked at src/main.rs:7:27: 2 already borrowed: BorrowMutError 3 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` The opposite ordering (a read while a write is held) panics with a slightly different message — `already mutably borrowed: BorrowError` — but it is the same class of bug. **Fix:** never hold two borrows that overlap. Finish with the first guard (let it drop, or scope it) before taking the second, and prefer one short `borrow_mut()` per statement over long-lived guard variables. ### Pitfall 2: Trying to send a `RefCell` across threads [Section titled “Pitfall 2: Trying to send a RefCell across threads”](#pitfall-2-trying-to-send-a-refcell-across-threads) A `RefCell` looks like it should work in a thread, but it is `!Sync` and the compiler rejects sharing it: exactly the protection that pushes you toward `Mutex`: ```rust 1 use std::cell::RefCell; 2 use std::sync::Arc; 3 use std::thread; 4 5 fn main() { 6 let shared = Arc::new(RefCell::new(0)); 7 8 let s = Arc::clone(&shared); 9 let handle = thread::spawn(move || { 10 *s.borrow_mut() += 1; // does not compile: RefCell is not Sync 11 }); 12 13 handle.join().unwrap(); 14 println!("{}", shared.borrow()); 15 } ``` The real error (abridged): ```text 1 error[E0277]: `RefCell<i32>` cannot be shared between threads safely 2 --> src/main.rs:9:32 3 | 4 9 | let handle = thread::spawn(move || { 5 | __________________-------------_^ 6 ... 7 | |_____^ `RefCell<i32>` cannot be shared between threads safely 8 | 9 = help: the trait `Sync` is not implemented for `RefCell<i32>` 10 = note: if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` instead 11 = note: required for `Arc<RefCell<i32>>` to implement `Send` ``` **Fix:** swap `RefCell` for `Mutex` (or `RwLock` if reads vastly outnumber writes) and `Rc` for `Arc`: `Arc<Mutex<i32>>`. The compiler error is doing you a favor: it caught a data race before it could exist. ### Pitfall 3: Locking the same `Mutex` twice on one thread (deadlock) [Section titled “Pitfall 3: Locking the same Mutex twice on one thread (deadlock)”](#pitfall-3-locking-the-same-mutex-twice-on-one-thread-deadlock) Because `lock()` *blocks* rather than panicking, locking a non-reentrant `Mutex` you already hold on the same thread deadlocks the thread forever: ```rust 1 // Conceptual — do NOT run; this hangs: 2 // let m = Mutex::new(0); 3 // let g1 = m.lock().unwrap(); 4 // let g2 = m.lock().unwrap(); // thread blocks forever waiting for itself ``` There is no compiler error and no panic: the program simply hangs. **Fix:** never call `lock()` while you still hold a guard from the same mutex. Keep critical sections small, and if a helper needs the data, pass it `&mut T` from the already-acquired guard rather than re-locking. > **Warning:** Rust’s `Mutex` is **not reentrant**. Unlike some languages’ recursive locks, taking the same lock twice on one thread is undefined-time hang, not a no-op. ### Pitfall 4: Forgetting that a long-lived guard blocks others [Section titled “Pitfall 4: Forgetting that a long-lived guard blocks others”](#pitfall-4-forgetting-that-a-long-lived-guard-blocks-others) A `MutexGuard` held across an `.await` or a slow I/O call keeps every other thread (or task) waiting. In synchronous code this just hurts throughput; in async code it can stall an entire runtime (`std::sync::Mutex` should generally not be held across `.await`; see [Section 11 — Async](/11-async/)). **Fix:** copy or move what you need out of the guard, drop it, then do the slow work. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Reach for the borrow checker first.** Interior mutability is a deliberate exception, not a default. If `&mut self` or restructuring the data threads cleanly, prefer it: you keep compile-time guarantees and zero runtime cost. * **Keep borrows and locks short.** One `borrow_mut()`/`lock()` per statement when you can. Scope guards in `{ }` blocks so they drop early. Long-lived guards are how both panics (`RefCell`) and deadlocks (`Mutex`) happen. * **Pick the container by thread-boundary, not by habit.** Single thread → `RefCell` (cheaper, no atomics). Crossing threads → `Mutex` (or `RwLock` for read-heavy workloads). The compiler enforces this for you via `Send`/`Sync`. * **Compose intentionally:** `Rc<RefCell<T>>` for a shared, mutable, single-threaded graph; `Arc<Mutex<T>>` for the multithreaded version. Document *why* the shared mutability is needed. * **Use `try_borrow_mut()` / `try_lock()` when contention is expected and recoverable.** They return a `Result` instead of panicking/blocking, so you can fall back gracefully: ```rust 1 use std::cell::RefCell; 2 3 fn main() { 4 let cell = RefCell::new(String::from("hello")); 5 let _read = cell.borrow(); 6 match cell.try_borrow_mut() { 7 Ok(mut w) => w.push_str(" world"), 8 Err(_) => println!("already borrowed; skipping mutation"), 9 } 10 } ``` Output: `already borrowed; skipping mutation`. * **Prefer the unlocked accessors when you own the data.** `get_mut()` and `into_inner()` skip the runtime check entirely and signal “no contention here” to the next reader of your code. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A **memoizing cache** is interior mutability’s sweet spot: the *interface* is a read-only “look up a value,” but the *implementation* must mutate a cache on a miss. With `RefCell` the public `get` method takes `&self`, so the memoizer composes like any other read-only service. Callers never need `&mut`. ```rust 1 use std::cell::RefCell; 2 use std::collections::HashMap; 3 4 /// A memoizing wrapper around an expensive pure function. 5 /// The cache mutates on a miss, yet `get` takes `&self` — callers 6 /// never need a `&mut Memoizer`, so the type composes like a read-only service. 7 struct Memoizer<F> { 8 compute: F, 9 cache: RefCell<HashMap<u64, u64>>, 10 calls: RefCell<u64>, // how many times we actually ran `compute` 11 } 12 13 impl<F: Fn(u64) -> u64> Memoizer<F> { 14 fn new(compute: F) -> Self { 15 Memoizer { 16 compute, 17 cache: RefCell::new(HashMap::new()), 18 calls: RefCell::new(0), 19 } 20 } 21 22 fn get(&self, key: u64) -> u64 { 23 // Fast path: check the cache, and release the borrow before recomputing. 24 if let Some(&hit) = self.cache.borrow().get(&key) { 25 return hit; 26 } 27 // Miss: no borrow of `cache` is held while we run the real computation. 28 *self.calls.borrow_mut() += 1; 29 let value = (self.compute)(key); 30 self.cache.borrow_mut().insert(key, value); 31 value 32 } 33 34 fn compute_calls(&self) -> u64 { 35 *self.calls.borrow() 36 } 37 } 38 39 fn main() { 40 // Pretend this is an expensive call (DB hit, hashing, etc.). 41 let memo = Memoizer::new(|n: u64| n * n); 42 43 let inputs = [4, 4, 7, 4, 7, 9]; 44 let results: Vec<u64> = inputs.iter().map(|&n| memo.get(n)).collect(); 45 46 println!("results = {results:?}"); 47 println!("inputs = {inputs:?}"); 48 println!( 49 "compute calls = {} (vs {} lookups)", 50 memo.compute_calls(), 51 inputs.len() 52 ); 53 } ``` Running it prints: ```text 1 results = [16, 16, 49, 16, 49, 81] 2 inputs = [4, 4, 7, 4, 7, 9] 3 compute calls = 3 (vs 6 lookups) ``` Six lookups, only three real computations: the three distinct inputs `4`, `7`, `9`. The important detail is in `get`: the `if let Some(&hit) = self.cache.borrow()...` borrow ends at the end of that `if`’s condition expression, so when we later call `self.cache.borrow_mut().insert(...)` there is no overlapping borrow to panic on. Sequencing borrows like this — read, drop, then write — is the discipline that keeps `RefCell` panic-free. > **Note:** To make this cache thread-safe, change both `RefCell` to `Mutex`, wrap the whole `Memoizer` in an [`Arc`](/10-smart-pointers/01-rc-arc/), and lock instead of borrow. The structure is identical; only the runtime-check strategy changes. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`std::cell::RefCell` — standard library docs](https://doc.rust-lang.org/std/cell/struct.RefCell.html) * [`std::sync::Mutex` — standard library docs](https://doc.rust-lang.org/std/sync/struct.Mutex.html) * [The Rust Book — `RefCell<T>` and the Interior Mutability Pattern](https://doc.rust-lang.org/book/ch15-05-interior-mutability.html) * [The Rust Book — Shared-State Concurrency (`Mutex`/`Arc`)](https://doc.rust-lang.org/book/ch16-03-shared-state.html) * Sibling topics: [`Cell<T>`](/10-smart-pointers/03-cell/) (unchecked, `Copy`-only interior mutability) · [`Rc<T>` / `Arc<T>`](/10-smart-pointers/01-rc-arc/) (shared ownership you compose these with) · [`Weak<T>`](/10-smart-pointers/05-weak/) (breaking cycles in `Rc<RefCell<…>>` graphs) · [Smart-pointer decision guide](/10-smart-pointers/07-comparison/) * Foundations: [Section 05 — Ownership](/05-ownership/) (the borrow rules these types relax) · [Section 11 — Async](/11-async/) (why `std::sync::Mutex` should not be held across `.await`) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A rate limiter that counts down through `&self` [Section titled “Exercise 1: A rate limiter that counts down through \&self”](#exercise-1-a-rate-limiter-that-counts-down-through-self) **Difficulty:** Easy **Objective:** Get comfortable mutating state behind a shared reference with `RefCell`. **Instructions:** Implement a `RateLimiter` with a `try_acquire(&self) -> bool` method. It starts with a quota and returns `true` (consuming one unit) while units remain, and `false` once exhausted. Note that `try_acquire` must take `&self`, not `&mut self`. ```rust 1 use std::cell::RefCell; 2 3 struct RateLimiter { 4 remaining: RefCell<u32>, 5 } 6 7 impl RateLimiter { 8 fn new(quota: u32) -> Self { 9 /* ??? */ 10 } 11 fn try_acquire(&self) -> bool { 12 /* ??? */ 13 } 14 } 15 16 fn main() { 17 let limiter = RateLimiter::new(2); 18 // Expected: true true false 19 println!("{} {} {}", limiter.try_acquire(), limiter.try_acquire(), limiter.try_acquire()); 20 } ``` Solution ```rust 1 use std::cell::RefCell; 2 3 struct RateLimiter { 4 remaining: RefCell<u32>, 5 } 6 7 impl RateLimiter { 8 fn new(quota: u32) -> Self { 9 RateLimiter { remaining: RefCell::new(quota) } 10 } 11 12 fn try_acquire(&self) -> bool { 13 let mut r = self.remaining.borrow_mut(); 14 if *r == 0 { 15 false 16 } else { 17 *r -= 1; 18 true 19 } 20 } 21 } 22 23 fn main() { 24 let limiter = RateLimiter::new(2); 25 println!( 26 "{} {} {}", 27 limiter.try_acquire(), 28 limiter.try_acquire(), 29 limiter.try_acquire() 30 ); 31 } ``` Output: ```text 1 true true false ``` The single `borrow_mut()` at the top of `try_acquire` is dropped when the method returns, so consecutive calls never overlap and never panic. ### Exercise 2: A shared event log written by two closures [Section titled “Exercise 2: A shared event log written by two closures”](#exercise-2-a-shared-event-log-written-by-two-closures) **Difficulty:** Medium **Objective:** Combine `Rc` (sharing) with `RefCell` (mutation): the single-threaded shared-mutable-state idiom. **Instructions:** Build a `Vec<String>` event log that two independent logging closures both append to. Each closure should tag its messages with a name (e.g. `"auth"`, `"db"`). After running a few events, print the whole log in order. Hint: the log’s type is `Rc<RefCell<Vec<String>>>`, and each closure should hold its own `Rc::clone`. Solution ```rust 1 use std::cell::RefCell; 2 use std::rc::Rc; 3 4 type Log = Rc<RefCell<Vec<String>>>; 5 6 fn make_logger(log: &Log, name: &'static str) -> impl Fn(&str) { 7 let log = Rc::clone(log); 8 move |msg: &str| log.borrow_mut().push(format!("{name}: {msg}")) 9 } 10 11 fn main() { 12 let log: Log = Rc::new(RefCell::new(Vec::new())); 13 let auth = make_logger(&log, "auth"); 14 let db = make_logger(&log, "db"); 15 16 auth("login ok"); 17 db("query 1"); 18 auth("logout"); 19 20 for line in log.borrow().iter() { 21 println!("{line}"); 22 } 23 } ``` Output: ```text 1 auth: login ok 2 db: query 1 3 auth: logout ``` Each `make_logger` call takes its own `Rc::clone`, so both closures own the same heap-allocated `RefCell<Vec<String>>`. The `borrow_mut()` inside each closure is short-lived (one `push` then dropped), so the appends never collide. ### Exercise 3: Make a registry thread-safe [Section titled “Exercise 3: Make a registry thread-safe”](#exercise-3-make-a-registry-thread-safe) **Difficulty:** Hard **Objective:** Convert a single-threaded interior-mutability pattern to a thread-safe one — `RefCell` → `Mutex`, `Rc` → `Arc` — and have several threads write to a shared collection. **Instructions:** Spawn four threads, each of which pushes a value (`id * 10`) into a shared `Vec<u64>`. Join all threads, then print the collected values sorted ascending. You should reach for `Arc<Mutex<Vec<u64>>>`. (Why not `Rc<RefCell<…>>`? Try it and read the compiler error — it is Pitfall 2.) Solution ```rust 1 use std::sync::{Arc, Mutex}; 2 use std::thread; 3 4 fn main() { 5 let registry: Arc<Mutex<Vec<u64>>> = Arc::new(Mutex::new(Vec::new())); 6 let mut handles = Vec::new(); 7 8 for id in 0..4u64 { 9 let registry = Arc::clone(®istry); 10 handles.push(thread::spawn(move || { 11 registry.lock().unwrap().push(id * 10); 12 })); 13 } 14 15 for h in handles { 16 h.join().unwrap(); 17 } 18 19 let mut final_ids = registry.lock().unwrap().clone(); 20 final_ids.sort_unstable(); 21 println!("{final_ids:?}"); 22 } ``` Output: ```text 1 [0, 10, 20, 30] ``` Each thread takes its own `Arc::clone` (cheap reference-count bump, see [`Rc<T>`/`Arc<T>`](/10-smart-pointers/01-rc-arc/)) so all four own the same `Mutex`. The `lock()` serializes the four `push` calls, so no update is lost. We sort at the end because thread completion order — and therefore insertion order — is nondeterministic. # Cell<T>: Cheap Interior Mutability for Copy Types > Cell<T> gives zero-cost interior mutability for Copy types, moving whole values in and out with get and set so a &self method can change a field without panicking. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) `Cell<T>` is Rust’s lightest-weight tool for **interior mutability**: it lets you mutate a value through a shared `&` reference, with **zero runtime cost** and no borrow tracking. The trade-off is that you can never get a reference *into* a `Cell`. You only ever **move whole values in and out** with `get` and `set`, which is why it shines for small `Copy` types like counters, flags, and IDs. For a TypeScript/JavaScript developer, the surprising part is not the mutation (everything mutates in JS) but *why you’d need a special type for it at all*. In Rust, a `&self` method normally cannot change anything; `Cell<T>` is the escape hatch that keeps the method signature `&self` while still letting a field change. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In JavaScript, an object method can freely mutate its own fields. There is no concept of a “read-only reference” enforced at the language level, so a `render()` method that bumps a private counter is completely ordinary: ```typescript 1 // widget.ts — a render counter on an otherwise "read-only" object 2 class Widget { 3 label: string; 4 private renderCount: number; 5 6 constructor(label: string) { 7 this.label = label; 8 this.renderCount = 0; 9 } 10 11 // Looks like a read-only accessor, but it quietly mutates state. 12 render(): string { 13 this.renderCount += 1; 14 return `${this.label} (rendered ${this.renderCount} times)`; 15 } 16 } 17 18 const w = new Widget("Button"); 19 console.log(w.render()); 20 console.log(w.render()); 21 console.log(w.render()); ``` Running it with Node v22 (`node --experimental-strip-types widget.ts`) prints: ```text 1 Button (rendered 1 times) 2 Button (rendered 2 times) 3 Button (rendered 3 times) ``` JavaScript does not care that `render` “reads like” an accessor; there is no compile-time notion of immutability to violate. Even a `const w` only freezes the *binding*, not the object’s fields (`w.renderCount` could still change). Rust draws that line much more strictly, and `Cell<T>` is how you cross it on purpose. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The naive Rust translation — a `render(&self)` that does `self.render_count += 1` — does **not** compile, because `&self` is a shared (read-only) reference. Wrapping the field in `Cell<u32>` makes it work while keeping the `&self` signature: ```rust 1 use std::cell::Cell; 2 3 struct Widget { 4 label: String, 5 render_count: Cell<u32>, // interior mutability for a Copy field 6 } 7 8 impl Widget { 9 fn render(&self) -> String { 10 // get() copies the value out, set() stores a new value back in. 11 self.render_count.set(self.render_count.get() + 1); 12 format!("{} (rendered {} times)", self.label, self.render_count.get()) 13 } 14 } 15 16 fn main() { 17 let w = Widget { 18 label: "Button".to_string(), 19 render_count: Cell::new(0), 20 }; 21 println!("{}", w.render()); 22 println!("{}", w.render()); 23 println!("{}", w.render()); 24 } ``` This compiles and prints exactly the same output as the TypeScript version: ```text 1 Button (rendered 1 times) 2 Button (rendered 2 times) 3 Button (rendered 3 times) ``` > **Note:** `w` is **not** declared `mut`. That is the whole point: `Cell<T>` lets the inner value change even though the binding and the `&self` reference are immutable. The mutability is “interior” to the `Cell`. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The problem `Cell` solves [Section titled “The problem Cell solves”](#the-problem-cell-solves) Rust’s borrow rules can be summed up as: at any moment a value may have **either** many shared `&` references **or** exactly one mutable `&mut` reference, never both. Methods that take `&self` therefore promise “I will not mutate.” That promise is enforced by the compiler: ```rust 1 struct Widget { 2 render_count: u32, 3 } 4 impl Widget { 5 fn render(&self) { 6 self.render_count += 1; // does not compile (error[E0594]) 7 } 8 } 9 fn main() { 10 let w = Widget { render_count: 0 }; 11 w.render(); 12 } ``` The real compiler error is: ```text 1 error[E0594]: cannot assign to `self.render_count`, which is behind a `&` reference 2 --> src/main.rs:6:9 3 | 4 6 | self.render_count += 1; // does not compile (error[E0594]) 5 | ^^^^^^^^^^^^^^^^^^^^^^ `self` is a `&` reference, so the data it refers to cannot be written 6 | 7 help: consider changing this to be a mutable reference 8 | 9 5 | fn render(&mut self) { 10 | +++ ``` Changing to `&mut self` is one fix, but it forces *every caller* to hold a unique mutable handle, impossible when the widget is shared (behind an `Rc`, inside a `Vec` you’re iterating over, or used by multiple callbacks). `Cell<T>` lets you keep `&self` and still mutate. This is called **interior mutability**: from the outside the value looks immutable, but it carries a sanctioned mutable interior. ### `get` and `set`: move values, never borrow [Section titled “get and set: move values, never borrow”](#get-and-set-move-values-never-borrow) `Cell<T>` deliberately exposes a tiny surface: ```rust 1 use std::cell::Cell; 2 3 fn main() { 4 let counter = Cell::new(0); 5 counter.set(counter.get() + 1); // read out, compute, store back 6 counter.set(counter.get() + 1); 7 println!("counter = {}", counter.get()); 8 9 // A shared &reference is enough to mutate — no `mut` anywhere. 10 let c = &counter; 11 c.set(42); 12 println!("via shared ref = {}", counter.get()); 13 } ``` Output: ```text 1 counter = 2 2 via shared ref = 42 ``` * **`get(&self) -> T`** returns a **copy** of the inner value. It is only available when `T: Copy`, which is why `Cell` is a fit for numbers, `bool`, `char`, small `enum`s, and other `Copy` data. * **`set(&self, value: T)`** overwrites the inner value, dropping the old one. Importantly, neither method ever hands out a `&T` or `&mut T` pointing *inside* the `Cell`. Because no reference into the cell can exist, there is no way to observe a half-written value or to alias it, so no borrow checking is needed, and `Cell` is sound with literally zero bookkeeping. That is the deep reason `get` requires `Copy`: handing you a copy means you walk away with your *own* value, not a borrow of the cell’s. ### Other useful methods [Section titled “Other useful methods”](#other-useful-methods) `Cell<T>` has a few more move-in/move-out helpers. These all take `&self`: ```rust 1 use std::cell::Cell; 2 3 fn main() { 4 let a = Cell::new(10); 5 6 let old = a.replace(20); // set new, return the old value 7 println!("replace: old={}, new={}", old, a.get()); 8 9 let taken = a.take(); // available when T: Default; leaves T::default() 10 println!("take: taken={}, now={}", taken, a.get()); 11 12 let x = Cell::new(1); 13 let y = Cell::new(2); 14 x.swap(&y); // swap the contents of two cells 15 println!("swap: x={}, y={}", x.get(), y.get()); 16 } ``` Output: ```text 1 replace: old=10, new=20 2 take: taken=20, now=0 3 swap: x=2, y=1 ``` There is also `update`, stabilized in Rust 1.88, which reads, applies a closure, and stores the result. Handy for the very common “increment” pattern: ```rust 1 use std::cell::Cell; 2 3 fn main() { 4 let c = Cell::new(5); 5 c.update(|x| x + 1); // equivalent to c.set(c.get() + 1) 6 println!("{}", c.get()); 7 } ``` Output: ```text 1 6 ``` ### When you *do* have `&mut`, the overhead vanishes [Section titled “When you do have \&mut, the overhead vanishes”](#when-you-do-have-mut-the-overhead-vanishes) If you happen to hold a `&mut Cell<T>`, the cell stops being necessary, and Rust gives you direct, free access to the inside: ```rust 1 use std::cell::Cell; 2 3 fn main() { 4 let mut c = Cell::new(5); 5 6 // get_mut requires &mut self and returns a real &mut T into the cell. 7 let inner: &mut i32 = c.get_mut(); 8 *inner += 10; 9 println!("after get_mut: {}", c.get()); 10 11 // into_inner consumes the Cell and returns the owned value. 12 let owned = c.into_inner(); 13 println!("into_inner: {}", owned); 14 15 // Cell<T> is exactly the same size as T — no tag, no flag, no overhead. 16 println!("size_of::<i32>() = {}", std::mem::size_of::<i32>()); 17 println!("size_of::<Cell<i32>>() = {}", std::mem::size_of::<Cell<i32>>()); 18 } ``` Output: ```text 1 after get_mut: 15 2 into_inner: 15 3 size_of::<i32>() = 4 4 size_of::<Cell<i32>>() = 4 ``` `get_mut` is safe precisely because `&mut self` proves no other reference to the cell exists, so a real `&mut T` cannot alias anything. And as the last two lines show, `Cell<i32>` occupies the same 4 bytes as a bare `i32`: wrapping a field in `Cell` costs nothing in memory. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript | Rust `Cell<T>` | | ------------------ | --------------------------------------------- | ------------------------------------------------------------------ | | Default mutability | Everything mutable; no read-only references | `&self` is read-only; `Cell` is an explicit opt-in to mutate | | How you read | `obj.field` returns the live value | `cell.get()` returns a **copy** (requires `T: Copy`) | | How you write | `obj.field = x` | `cell.set(x)` | | References into it | You always get a live reference to the object | **Never**: you cannot borrow inside a `Cell` | | Runtime cost | N/A | **Zero**: no flags, locks, or counters | | Thread safety | Single-threaded event loop by default | `!Sync`, single-thread only (use `Atomic*`/`Mutex` across threads) | | Failure mode | Runtime `undefined`/exceptions | None — `Cell` cannot panic | ### `Cell` versus its siblings [Section titled “Cell versus its siblings”](#cell-versus-its-siblings) The smart-pointer family splits the job of “mutate through a shared reference” along two axes: *what you store* and *single- vs multi-threaded*: | Need | Reach for | | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | | Mutate a small `Copy` value, single thread, no overhead | **`Cell<T>`** (this file) | | Mutate a non-`Copy` value (e.g. `String`, `Vec`) and hand out borrows, single thread | [`RefCell<T>`](/10-smart-pointers/02-refcell-mutex/) | | Mutate shared state across threads | [`Mutex<T>` / `RwLock<T>`](/10-smart-pointers/02-refcell-mutex/) or `std::sync::atomic::*` | | Share ownership of the cell among many holders | [`Rc<Cell<T>>`](/10-smart-pointers/01-rc-arc/) (single thread) | The mental rule: **if `T: Copy` and you never need a borrow into it, prefer `Cell`**. It is the cheapest tool and it can never panic, unlike `RefCell`, which trades a runtime borrow check (and possible panic) for the ability to hand out references. > **Tip:** A common idiom is a counter shared across closures or graph nodes: `Rc<Cell<u32>>`. The `Rc` shares ownership; the `Cell` provides the cheap mutation. You almost never want `Rc<RefCell<u32>>` for a plain integer. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Trying to use `Cell` with a non-`Copy` type and calling `get` [Section titled “Pitfall 1: Trying to use Cell with a non-Copy type and calling get”](#pitfall-1-trying-to-use-cell-with-a-non-copy-type-and-calling-get) `get` clones the value out by copying, so it is gated on `T: Copy`. A `Cell<String>` compiles, but `.get()` on it does not: ```rust 1 use std::cell::Cell; 2 3 fn main() { 4 let c = Cell::new(String::from("hi")); 5 let s = c.get(); // does not compile (error[E0599]): String is not Copy 6 println!("{}", s); 7 } ``` Real compiler error: ```text 1 error[E0599]: the method `get` exists for struct `Cell<String>`, but its trait bounds were not satisfied 2 --> src/main.rs:5:15 3 | 4 5 | let s = c.get(); // does not compile (error[E0599]): String is not Copy 5 | ^^^ 6 | 7 ::: .../library/alloc/src/string.rs:360:1 8 | 9 | pub struct String { 10 | ----------------- doesn't satisfy `String: Copy` 11 | 12 = note: the following trait bounds were not satisfied: 13 `String: Copy` ``` **Fix:** For non-`Copy` data you want to mutate behind `&self`, use [`RefCell<T>`](/10-smart-pointers/02-refcell-mutex/) (which hands out borrows), or use `Cell`’s move-only methods like `take`/`replace` that do not require `Copy`. For example `c.take()` works on `Cell<String>` because it moves the `String` out and leaves an empty `String` (`Default`) behind. ### Pitfall 2: Expecting to borrow the value inside a `Cell` [Section titled “Pitfall 2: Expecting to borrow the value inside a Cell”](#pitfall-2-expecting-to-borrow-the-value-inside-a-cell) There is intentionally **no** `&self` method that returns a reference into a `Cell`. If you find yourself wanting `&cell.contents` to, say, iterate over a `Vec` stored inside, `Cell` is the wrong tool. You would have to `get()` a whole copy out (impossible for a `Vec` since it is not `Copy`) or `take()` it, mutate the owned copy, and `set()` it back. That is awkward by design. **Fix:** Reach for [`RefCell<T>`](/10-smart-pointers/02-refcell-mutex/), whose `borrow()` / `borrow_mut()` give you references into the contents (at the cost of a runtime borrow check that can panic). ### Pitfall 3: Sharing a `Cell` across threads [Section titled “Pitfall 3: Sharing a Cell across threads”](#pitfall-3-sharing-a-cell-across-threads) `Cell<T>` is `!Sync`: a `&Cell<T>` may not be sent to another thread, because two threads writing to the same cell with no synchronization is a data race. The compiler stops you: ```rust 1 use std::cell::Cell; 2 use std::thread; 3 4 fn main() { 5 let counter = Cell::new(0); 6 thread::scope(|s| { 7 s.spawn(|| { 8 counter.set(counter.get() + 1); // does not compile (error[E0277]) 9 }); 10 }); 11 println!("{}", counter.get()); 12 } ``` Real compiler error (abbreviated): ```text 1 error[E0277]: `Cell<i32>` cannot be shared between threads safely 2 --> src/main.rs:7:17 3 | 4 7 | s.spawn(|| { 5 | ^^ `Cell<i32>` cannot be shared between threads safely 6 | 7 = help: the trait `Sync` is not implemented for `Cell<i32>` 8 = note: if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicI32` instead 9 = note: required for `&Cell<i32>` to implement `Send` ``` **Fix:** As the compiler itself suggests, use an atomic such as `std::sync::atomic::AtomicI32` for a shared counter, or a `Mutex`/`RwLock` for larger state. See [RefCell vs Mutex](/10-smart-pointers/02-refcell-mutex/) and the [async section](/11-async/) for shared-state patterns across tasks. ### Pitfall 4: Reaching for `Cell` (or `RefCell`) too early [Section titled “Pitfall 4: Reaching for Cell (or RefCell) too early”](#pitfall-4-reaching-for-cell-or-refcell-too-early) Coming from JavaScript, interior mutability feels natural and you may sprinkle `Cell` everywhere. In idiomatic Rust it is the *exception*, not the rule. If a plain `&mut self` works — and it usually does — prefer it: the compiler then guarantees no aliasing for free. **Fix:** Default to ordinary ownership and `&mut`. Reach for `Cell` only when you genuinely need to mutate through a shared reference (shared graph nodes, observer counters, flags inside an `Rc`, caches keyed by `&self`). *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Use `Cell` for small `Copy` state mutated behind `&self`:** counters, version numbers, generation IDs, dirty/visited flags, cached `Option<T>` of a `Copy` value. * **Prefer `Cell` over `RefCell` when `T: Copy`:** it is cheaper and *cannot panic*. Only step up to `RefCell` when you need to borrow into a non-`Copy` value. * **Reach for `update` for read-modify-write:** `c.update(|n| n + 1)` is clearer than `c.set(c.get() + 1)` and avoids repeating the binding. * **Pair with `Rc` for shared, mutable, single-threaded state:** `Rc<Cell<T>>` is the canonical “shared counter” type; see [Rc/Arc](/10-smart-pointers/01-rc-arc/). * **Switch to atomics across threads:** `Cell` is single-threaded by design. The thread-safe analogues are `AtomicUsize`, `AtomicBool`, etc., or a `Mutex` for larger data. * **Keep the `Cell` private:** expose intent-revealing methods (`record`, `next_id`) rather than leaking the `Cell` field, so callers cannot accidentally `set` arbitrary values. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A request-metrics recorder is a perfect fit: handlers usually receive `&self` (the metrics object is shared), the tracked values are all `Copy`, and you never need to borrow *into* them: just bump counters and read totals. ```rust 1 use std::cell::Cell; 2 3 /// Tracks request statistics while exposing only `&self` methods, so it can 4 /// live behind a shared reference (e.g. inside an `Rc` or a handler struct). 5 #[derive(Debug)] 6 struct RequestMetrics { 7 total: Cell<u64>, 8 errors: Cell<u64>, 9 last_status: Cell<u16>, 10 } 11 12 impl RequestMetrics { 13 fn new() -> Self { 14 RequestMetrics { 15 total: Cell::new(0), 16 errors: Cell::new(0), 17 last_status: Cell::new(0), 18 } 19 } 20 21 /// Note: `&self`, not `&mut self`. Callers do not need a mutable handle. 22 fn record(&self, status: u16) { 23 self.total.update(|t| t + 1); 24 if status >= 500 { 25 self.errors.update(|e| e + 1); 26 } 27 self.last_status.set(status); 28 } 29 30 fn error_rate(&self) -> f64 { 31 let total = self.total.get(); 32 if total == 0 { 33 0.0 34 } else { 35 self.errors.get() as f64 / total as f64 36 } 37 } 38 } 39 40 fn main() { 41 let metrics = RequestMetrics::new(); 42 43 for status in [200, 200, 500, 404, 503, 200] { 44 metrics.record(status); // shared &self call, no `mut metrics` needed 45 } 46 47 println!("total requests: {}", metrics.total.get()); 48 println!("server errors: {}", metrics.errors.get()); 49 println!("last status: {}", metrics.last_status.get()); 50 println!("error rate: {:.1}%", metrics.error_rate() * 100.0); 51 } ``` Output: ```text 1 total requests: 6 2 server errors: 2 3 last status: 200 4 error rate: 33.3% ``` Notice that `metrics` is never `mut`, yet every call to `record` mutates three fields. If `RequestMetrics` lived inside an `Rc` shared among several handlers (see [Rc/Arc](/10-smart-pointers/01-rc-arc/)), this exact code would still work. That is the payoff of choosing `Cell` over `&mut self`. If you needed thread-safe metrics, you would swap each `Cell` for an `AtomicU64`/`AtomicU16` and the API would barely change. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [`std::cell::Cell` API docs](https://doc.rust-lang.org/std/cell/struct.Cell.html) * [`std::cell` module overview](https://doc.rust-lang.org/std/cell/index.html): the canonical explanation of interior mutability * [The Rust Book — `RefCell<T>` and the Interior Mutability Pattern](https://doc.rust-lang.org/book/ch15-05-interior-mutability.html) * [`std::sync::atomic`](https://doc.rust-lang.org/std/sync/atomic/index.html): the thread-safe counterparts to `Cell` ### Related Topics [Section titled “Related Topics”](#related-topics) * [RefCell and Mutex](/10-smart-pointers/02-refcell-mutex/): interior mutability for non-`Copy` data and across threads * [Rc and Arc](/10-smart-pointers/01-rc-arc/) — shared ownership; pairs with `Cell` as `Rc<Cell<T>>` * [Box](/10-smart-pointers/00-box/): heap allocation, the simplest smart pointer * [Weak](/10-smart-pointers/05-weak/) — breaking reference cycles in shared graphs * [Cow](/10-smart-pointers/04-cow/) — clone-on-write, another “avoid needless work” pattern * [Smart Pointer Comparison](/10-smart-pointers/07-comparison/) — a decision guide for which pointer to use when * [Variables and Mutability](/02-basics/00-variables/): why `&self` is read-only in the first place * [Ownership](/05-ownership/) — the borrow rules `Cell` carefully sidesteps * [Getting Started](/01-getting-started/) and [Introduction](/00-introduction/) — if you are new to the guide * [Async](/11-async/) — shared-state patterns across tasks (where `Cell` does *not* apply) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1 [Section titled “Exercise 1”](#exercise-1) **Difficulty:** Beginner **Objective:** Use `Cell` to mutate a field through a `&self` method. **Instructions:** The following code does not compile because `redraw` tries to mutate `redraws` through `&self`. Change the field type so it compiles, without changing the method signatures or adding `mut` to the binding in `main`. ```rust 1 struct View { 2 redraws: u32, // change me 3 } 4 impl View { 5 fn redraw(&self) { 6 self.redraws += 1; // must keep &self 7 } 8 } 9 fn main() { 10 let v = View { redraws: 0 }; // must stay non-mut 11 v.redraw(); 12 v.redraw(); 13 println!("redraws = {}", v.redraws); 14 } ``` Solution ```rust 1 use std::cell::Cell; 2 3 struct View { 4 redraws: Cell<u32>, 5 } 6 impl View { 7 fn redraw(&self) { 8 self.redraws.set(self.redraws.get() + 1); 9 } 10 } 11 fn main() { 12 let v = View { redraws: Cell::new(0) }; 13 v.redraw(); 14 v.redraw(); 15 println!("redraws = {}", v.redraws.get()); 16 } ``` Output: ```text 1 redraws = 2 ``` ### Exercise 2 [Section titled “Exercise 2”](#exercise-2) **Difficulty:** Intermediate **Objective:** Build a monotonic ID generator that hands out unique IDs through a shared reference. **Instructions:** Implement `IdGenerator` so that `next_id(&self)` returns `1`, then `2`, then `3`, … on successive calls. The generator must work through `&self` (no `&mut`). Try to use a single `Cell` method for the read-and-bump. ```rust 1 struct IdGenerator { 2 // TODO 3 } 4 impl IdGenerator { 5 fn new() -> Self { 6 // TODO 7 } 8 fn next_id(&self) -> u64 { 9 // TODO: return current value, then increment 10 } 11 } 12 fn main() { 13 let id_gen = IdGenerator::new(); 14 println!("{} {} {}", id_gen.next_id(), id_gen.next_id(), id_gen.next_id()); 15 // expected: 1 2 3 16 } ``` Solution ```rust 1 use std::cell::Cell; 2 3 struct IdGenerator { 4 next: Cell<u64>, 5 } 6 impl IdGenerator { 7 fn new() -> Self { 8 IdGenerator { next: Cell::new(1) } 9 } 10 fn next_id(&self) -> u64 { 11 // replace stores `current + 1` and returns the previous value. 12 self.next.replace(self.next.get() + 1) 13 } 14 } 15 fn main() { 16 let id_gen = IdGenerator::new(); 17 println!("{} {} {}", id_gen.next_id(), id_gen.next_id(), id_gen.next_id()); 18 } ``` Output: ```text 1 1 2 3 ``` > Note: `next` is the variable name here, not `gen`; in the latest stable edition (2024), `gen` is a reserved keyword (for `gen` blocks) and cannot be used as a plain identifier. ### Exercise 3 [Section titled “Exercise 3”](#exercise-3) **Difficulty:** Advanced **Objective:** Share a single counter across multiple closures using `Rc<Cell<T>>`. **Instructions:** Write `make_clicker()` that returns a shared counter handle plus a closure. Each call to the closure increments the counter; reading the returned handle reflects every click. This mirrors a UI event handler holding a shared counter. (Hint: clone the `Rc` so the closure owns its own handle.) ```rust 1 use std::cell::Cell; 2 use std::rc::Rc; 3 4 fn make_clicker() -> (Rc<Cell<u32>>, impl Fn()) { 5 // TODO 6 } 7 8 fn main() { 9 let (count, click) = make_clicker(); 10 click(); 11 click(); 12 click(); 13 println!("clicks = {}", count.get()); // expected: 3 14 } ``` Solution ```rust 1 use std::cell::Cell; 2 use std::rc::Rc; 3 4 fn make_clicker() -> (Rc<Cell<u32>>, impl Fn()) { 5 let count = Rc::new(Cell::new(0)); 6 let count_for_closure = Rc::clone(&count); 7 let on_click = move || { 8 count_for_closure.set(count_for_closure.get() + 1); 9 }; 10 (count, on_click) 11 } 12 13 fn main() { 14 let (count, click) = make_clicker(); 15 click(); 16 click(); 17 click(); 18 println!("clicks = {}", count.get()); 19 } ``` Output: ```text 1 clicks = 3 ``` The `Rc` gives both the returned handle and the closure shared ownership of the same `Cell`; the `Cell` provides the cheap, panic-free mutation. For a non-`Copy` payload you would instead use `Rc<RefCell<T>>`; see [Rc/Arc](/10-smart-pointers/01-rc-arc/) and [RefCell/Mutex](/10-smart-pointers/02-refcell-mutex/). # Clone-on-Write with `Cow<'_, T>` > Cow<'_, T> holds borrowed or owned data behind one type and clones only when you mutate, letting transform-if-needed functions skip allocation on the common path. `Cow` (“clone on write”) is a smart pointer that holds **either** borrowed **or** owned data behind a single type, and only allocates a fresh copy at the exact moment you need to mutate or keep it. It is Rust’s idiomatic tool for functions that *usually* return their input unchanged but *occasionally* need to produce a modified version — letting you skip an allocation on the common path. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) `Cow<'a, T>` (in `std::borrow`) is an enum with two variants: `Borrowed(&'a T)` and `Owned(<T as ToOwned>::Owned)`. For strings that means it wraps either a `&str` *or* a `String`; for slices, either a `&[T]` *or* a `Vec<T>`. Because it derefs to the borrowed form, you read through it like a plain reference, and you only pay for an allocation when you actually have to change the data. For a TypeScript/JavaScript developer, the closest mental hook is a function that returns “the same string I was given, or a new one if I had to edit it.” In JavaScript strings are immutable and copies are invisible, whereas `Cow` makes the borrow-versus-allocate decision explicit and free of charge on the hot path. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In JavaScript, strings are immutable, so “modify if needed” functions either return the original reference or build a brand-new string. The allocation is implicit and you have no way to express “I borrowed the caller’s data and changed nothing.” ```typescript 1 // Normalize a URL to https, only producing a new string when we must change it. 2 function ensureHttps(url: string): string { 3 if (url.startsWith("https://")) { 4 return url; // returns the SAME reference — no copy 5 } 6 if (url.startsWith("http://")) { 7 return "https://" + url.slice("http://".length); // brand-new string 8 } 9 return "https://" + url; // brand-new string 10 } 11 12 const already = ensureHttps("https://example.com"); // same reference back 13 const upgraded = ensureHttps("http://example.com"); // freshly allocated 14 15 console.log(already); // https://example.com 16 console.log(upgraded); // https://example.com 17 18 // In JS you cannot tell, from the outside, whether `already` is the original 19 // string or a copy — and you cannot prevent the engine from copying internally. ``` This pattern is everywhere: HTML escaping, input sanitizing, path normalization, config defaulting. In each case the *typical* input needs no change, but the type system gives you no way to say “borrowed, untouched” versus “owned, rebuilt.” *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) `Cow<'_, str>` expresses exactly that distinction, and the compiler guarantees the borrow is valid: ```rust 1 use std::borrow::Cow; 2 3 fn ensure_https(url: &str) -> Cow<'_, str> { 4 if url.starts_with("https://") { 5 Cow::Borrowed(url) // no allocation: the input was already fine 6 } else if let Some(rest) = url.strip_prefix("http://") { 7 Cow::Owned(format!("https://{rest}")) // allocate only when we must change it 8 } else { 9 Cow::Owned(format!("https://{url}")) 10 } 11 } 12 13 fn main() { 14 let already = ensure_https("https://example.com"); 15 let upgraded = ensure_https("http://example.com"); 16 let bare = ensure_https("example.com"); 17 18 println!("{already}"); 19 println!("{upgraded}"); 20 println!("{bare}"); 21 22 // Inspect which variant we got: 23 println!("already is borrowed: {}", matches!(already, Cow::Borrowed(_))); 24 println!("upgraded is owned: {}", matches!(upgraded, Cow::Owned(_))); 25 } ``` **Output (verified with `cargo run`):** ```text 1 https://example.com 2 https://example.com 3 https://example.com 4 already is borrowed: true 5 upgraded is owned: true ``` The `already` case returns a `Cow::Borrowed` pointing straight at the caller’s string slice — **zero heap allocation**. Only the `http://` and bare-host cases build a new `String`. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The shape of `Cow` [Section titled “The shape of Cow”](#the-shape-of-cow) `Cow` is a plain enum in the standard library, roughly: ```rust 1 // From std::borrow (simplified) 2 pub enum Cow<'a, B> 3 where 4 B: ToOwned + ?Sized, 5 { 6 Borrowed(&'a B), 7 Owned(<B as ToOwned>::Owned), 8 } ``` The `B: ToOwned` bound is what makes the two halves line up. `ToOwned` is the trait that knows how to turn a borrowed value into an owned one: | Borrowed form `B` | Owned form `<B as ToOwned>::Owned` | | ----------------- | ---------------------------------- | | `str` | `String` | | `[T]` | `Vec<T>` | | `Path` | `PathBuf` | | `CStr` | `CString` | | any `T: Clone` | `T` | So `Cow<'a, str>` is “either a `&'a str` or a `String`,” and `Cow<'a, [i32]>` is “either a `&'a [i32]` or a `Vec<i32>`.” (The lifetime `'a` only constrains the `Borrowed` variant; an `Owned` value has no borrow to track.) ### Reading through `Cow` (`Deref`) [Section titled “Reading through Cow (Deref)”](#reading-through-cow-deref) `Cow<'_, B>` implements `Deref<Target = B>`, so every read-only method of the borrowed type is available directly — you do not match on the variant just to call `.len()`: ```rust 1 use std::borrow::Cow; 2 3 fn main() { 4 let c: Cow<'_, str> = Cow::Borrowed("Hello, Cow"); 5 // All of these are &str methods, reached through Deref: 6 println!("{}", c.len()); 7 println!("{}", c.to_uppercase()); 8 println!("{}", c.starts_with("Hello")); 9 10 // Cow<'_, str> can be compared to &str directly: 11 println!("{}", c == "Hello, Cow"); 12 13 // From conversions: 14 let from_str: Cow<'_, str> = "literal".into(); // -> Borrowed 15 let from_string: Cow<'_, str> = String::from("owned").into(); // -> Owned 16 println!( 17 "{} {}", 18 matches!(from_str, Cow::Borrowed(_)), 19 matches!(from_string, Cow::Owned(_)) 20 ); 21 } ``` **Output (verified):** ```text 1 10 2 HELLO, COW 3 true 4 true 5 true true ``` The `Deref` coercion here is the same machinery that makes `&String` work where `&str` is expected — covered in depth in [The `Deref` Trait and Deref Coercion](/10-smart-pointers/06-deref-trait/). Notice also the `From` impls: a `&str` becomes `Cow::Borrowed`, a `String` becomes `Cow::Owned`, so `.into()` does the right thing. ### Writing through `Cow` (`to_mut` and `into_owned`) [Section titled “Writing through Cow (to\_mut and into\_owned)”](#writing-through-cow-to_mut-and-into_owned) The “clone on write” name comes from two methods: * **`to_mut(&mut self) -> &mut <B as ToOwned>::Owned`** — gives you a mutable handle to the owned form. If the `Cow` is currently `Borrowed`, it clones the data into an owned value *first* (that is the “write” that triggers the “clone”), switches the variant to `Owned`, and hands you `&mut` to it. If it was already `Owned`, no clone happens. * **`into_owned(self) -> <B as ToOwned>::Owned`** — unconditionally consumes the `Cow` and returns the owned value, cloning only if it was borrowed. ```rust 1 use std::borrow::Cow; 2 3 fn main() { 4 // to_mut(): get a &mut to the owned data, cloning lazily on first call. 5 let mut data: Cow<'_, str> = Cow::Borrowed("hello"); 6 println!("before: borrowed = {}", matches!(data, Cow::Borrowed(_))); 7 data.to_mut().push_str(", world"); // clones "hello" into a String here 8 println!("after: borrowed = {}", matches!(data, Cow::Borrowed(_))); 9 println!("value: {data}"); 10 11 // into_owned(): unconditionally produce the owned type. 12 let s: Cow<'_, str> = Cow::Borrowed("owned me"); 13 let owned: String = s.into_owned(); 14 println!("owned: {owned}"); 15 } ``` **Output (verified):** ```text 1 before: borrowed = true 2 after: borrowed = false 3 value: hello, world 4 owned: owned me ``` The `push_str` call works because `to_mut()` returns `&mut String`, and `String` *does* have `push_str`. Before that call, `data` was a `Cow::Borrowed`; after it, it is `Cow::Owned` — the clone happened exactly once, on first mutation. ### Why this matters: the allocation you avoid [Section titled “Why this matters: the allocation you avoid”](#why-this-matters-the-allocation-you-avoid) Imagine a sanitizer applied to every field of every request. If 99% of inputs are already clean, eagerly calling `.to_string()` allocates a `String` for every single one. `Cow` lets the clean path stay a borrow: ```rust 1 use std::borrow::Cow; 2 3 // Replace any control chars; only allocate if there is something to replace. 4 fn sanitize(input: &str) -> Cow<'_, str> { 5 if input.chars().any(|c| c.is_control()) { 6 // We must build a new String -> Owned variant. 7 let cleaned: String = input.chars().filter(|c| !c.is_control()).collect(); 8 Cow::Owned(cleaned) 9 } else { 10 Cow::Borrowed(input) // hot path: clean input, zero allocation 11 } 12 } 13 14 fn main() { 15 let clean = sanitize("normal text"); 16 let dirty = sanitize("bad\u{7}text"); // contains a BEL control char 17 18 println!("clean borrowed: {}", matches!(clean, Cow::Borrowed(_))); 19 println!("dirty owned: {}", matches!(dirty, Cow::Owned(_))); 20 println!("dirty value: {dirty:?}"); 21 } ``` **Output (verified):** ```text 1 clean borrowed: true 2 dirty owned: true 3 dirty value: "badtext" ``` > **Tip:** The standard library uses this pattern in its own API. For example, `str::from_utf8_lossy` returns `Cow<'_, str>`: if the bytes are already valid UTF-8 it borrows them unchanged, and only allocates when it has to substitute the replacement character `�`. *** ## Key Differences [Section titled “Key Differences”](#key-differences) ### `Cow` is not just for strings [Section titled “Cow is not just for strings”](#cow-is-not-just-for-strings) `Cow<'_, [T]>` works for any slice whose element is `Clone`. The decision and the deref behavior are identical: ```rust 1 use std::borrow::Cow; 2 3 // Cow works for any [T] where T: Clone, not just str. 4 fn drop_negatives(nums: &[i32]) -> Cow<'_, [i32]> { 5 if nums.iter().any(|&n| n < 0) { 6 Cow::Owned(nums.iter().copied().filter(|&n| n >= 0).collect()) 7 } else { 8 Cow::Borrowed(nums) 9 } 10 } 11 12 fn main() { 13 let already = drop_negatives(&[1, 2, 3]); 14 let filtered = drop_negatives(&[1, -2, 3]); 15 16 println!("already borrowed: {}", matches!(already, Cow::Borrowed(_))); 17 println!("filtered owned: {}", matches!(filtered, Cow::Owned(_))); 18 println!("filtered: {filtered:?}"); 19 println!("len via deref: {}", filtered.len()); // read through Deref to &[i32] 20 } ``` **Output (verified):** ```text 1 already borrowed: true 2 filtered owned: true 3 filtered: [1, 3] 4 len via deref: 2 ``` ### `Cow` versus the other smart pointers [Section titled “Cow versus the other smart pointers”](#cow-versus-the-other-smart-pointers) | Need | Reach for | Why not `Cow` | | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | | Heap-allocate one value, always owned | [`Box<T>`](/10-smart-pointers/00-box/) | `Cow` is about *avoiding* the allocation when possible | | Share ownership across many holders | [`Rc<T>`/`Arc<T>`](/10-smart-pointers/01-rc-arc/) | `Cow` has a single logical owner; it does not refcount | | Mutate shared data behind a shared reference | [`RefCell`/`Mutex`](/10-smart-pointers/02-refcell-mutex/), [`Cell`](/10-smart-pointers/03-cell/) | `Cow` mutation always produces a *private* owned copy | | ”Maybe borrow, maybe own, decide at runtime, allocate lazily” | **`Cow<'_, T>`** | — | `Cow` is the only one of these focused on *deferring* an allocation. The full decision matrix lives in [Choosing a Smart Pointer](/10-smart-pointers/07-comparison/). ### Mental model versus TypeScript [Section titled “Mental model versus TypeScript”](#mental-model-versus-typescript) * **JavaScript strings:** always immutable; “return original or new” is invisible to you, and the engine may copy freely. `Cow` makes the borrow/own choice a value you can inspect and a cost the compiler tracks. * **TypeScript types are erased** at runtime; a `string` is just a `string`. Rust monomorphizes `Cow<'a, str>` into a concrete two-variant enum with a discriminant, so “is this borrowed or owned?” is a real, checkable runtime fact (`matches!(x, Cow::Borrowed(_))`). * Unlike JavaScript’s structural typing, the lifetime `'a` ties a `Cow::Borrowed` to the data it points at. You cannot return a `Cow` that borrows something the function is about to drop (see Pitfalls). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: borrowing a local into `Cow::Borrowed` [Section titled “Pitfall 1: borrowing a local into Cow::Borrowed”](#pitfall-1-borrowing-a-local-into-cowborrowed) A natural mistake is to build an owned value, then wrap a reference *to it* in `Cow::Borrowed`. The local is dropped at the end of the function, so the borrow would dangle — Rust rejects it. ```rust 1 use std::borrow::Cow; 2 3 fn shout(input: &str) -> Cow<'_, str> { 4 let upper = input.to_uppercase(); // local String 5 Cow::Borrowed(&upper) // does not compile (error[E0515]) 6 } ``` Real compiler output (`cargo build`): ```text 1 error[E0515]: cannot return value referencing local variable `upper` 2 --> src/main.rs:5:5 3 | 4 5 | Cow::Borrowed(&upper) // does not compile (error[E0515]) 5 | ^^^^^^^^^^^^^^------^ 6 | | | 7 | | `upper` is borrowed here 8 | returns a value referencing data owned by the current function ``` **Fix:** if you built a new value, it is *owned*, so use `Cow::Owned(upper)` (move the `String` in, no `&`). Use `Cow::Borrowed` only for data the caller owns (the `&str` parameter) or `'static` literals. ### Pitfall 2: trying to mutate a `Cow` directly [Section titled “Pitfall 2: trying to mutate a Cow directly”](#pitfall-2-trying-to-mutate-a-cow-directly) `Cow<'_, str>` derefs to `&str`, which is immutable, so methods like `push_str` are not in scope on the `Cow` itself. ```rust 1 use std::borrow::Cow; 2 3 fn main() { 4 let mut data: Cow<'_, str> = Cow::Borrowed("hello"); 5 data.push_str("!"); // does not compile (error[E0599]) 6 println!("{data}"); 7 } ``` Real compiler output (`cargo build`): ```text 1 error[E0599]: no method named `push_str` found for enum `Cow<'_, str>` in the current scope 2 --> src/main.rs:5:10 3 | 4 5 | data.push_str("!"); // does not compile (error[E0599]) 5 | ^^^^^^^^ method not found in `Cow<'_, str>` ``` **Fix:** go through `to_mut()` to get the underlying `&mut String`: `data.to_mut().push_str("!")`. That is the “write” that triggers the lazy clone. ### Pitfall 3: using `Cow` when you always allocate anyway [Section titled “Pitfall 3: using Cow when you always allocate anyway”](#pitfall-3-using-cow-when-you-always-allocate-anyway) If *every* code path produces an owned value, `Cow` buys you nothing but ceremony — just return `String`. `Cow` pays off only when at least one common path can stay borrowed. ```rust 1 // Anti-pattern: both arms are Owned, so Cow adds no value. 2 // fn f(s: &str) -> Cow<'_, str> { Cow::Owned(s.to_uppercase()) } 3 // Prefer: 4 fn f(s: &str) -> String { 5 s.to_uppercase() 6 } 7 8 fn main() { 9 println!("{}", f("hi")); 10 } ``` ### Pitfall 4: assuming `Cow::Owned` from a `String` is free to compare [Section titled “Pitfall 4: assuming Cow::Owned from a String is free to compare”](#pitfall-4-assuming-cowowned-from-a-string-is-free-to-compare) Comparisons and most reads work via `Deref`, so they are fine — but remember that putting a `Cow` into a struct adds a lifetime parameter to that struct when the `Borrowed` variant can occur. That can ripple through your API (see Best Practices). *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Return `Cow<'a, str>` (or `Cow<'a, [T]>`) from “transform-if-needed” functions:** escapers, sanitizers, normalizers, defaulters. This is the canonical, idiomatic use. * **Prefer `strip_prefix`/`trim`/slicing in the borrowed arm.** These return sub-slices of the input, which stay `Cow::Borrowed` with no allocation. Reach for `format!`/`replace`/`collect` only in the owned arm. * **Use `into_owned()` at the boundary where you need to store the value past the borrow’s lifetime** (e.g. before putting it in a long-lived struct without a lifetime parameter, or sending it across threads). `into_owned` is cheaper than `to_string()` when the value is already `Owned`. * **Let `.into()` pick the variant.** `let c: Cow<str> = some_string.into();` becomes `Owned`; `let c: Cow<str> = "x".into();` becomes `Borrowed`. This reads cleanly when the source type already makes the choice obvious. * **Be deliberate about adding a lifetime to a struct.** A field of type `Cow<'a, str>` forces `struct Config<'a>`. If most instances are built at runtime and stored long-term, a plain `String` field may be simpler; use `Cow` in the field when you genuinely want to hold borrowed literals without copying. * **Run Clippy.** It flags some redundant allocations and can suggest `Cow` patterns; the examples in this file are Clippy-clean on stable 1.96.0. > **Note:** `Cow` deliberately favors *correctness and zero-copy on the common path* over micro-optimizing the rare path. The owned arm still allocates exactly as a hand-written `String` would; you have simply moved that cost off the hot path. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small templating layer that HTML-escapes interpolated values. The vast majority of values are plain text needing no escaping, so we keep those borrowed and only allocate for values that contain `<`, `>`, `&`, or `"`. ```rust 1 use std::borrow::Cow; 2 use std::collections::HashMap; 3 4 /// Escape the HTML-significant characters in `input`. 5 /// Returns a borrow when nothing needs escaping (the common case for plain text), 6 /// and only allocates a new String when an unsafe character is present. 7 fn escape_html(input: &str) -> Cow<'_, str> { 8 // Fast scan: is there anything to escape at all? 9 if !input.bytes().any(|b| matches!(b, b'<' | b'>' | b'&' | b'"')) { 10 return Cow::Borrowed(input); 11 } 12 13 let mut escaped = String::with_capacity(input.len() + 16); 14 for ch in input.chars() { 15 match ch { 16 '<' => escaped.push_str("<"), 17 '>' => escaped.push_str(">"), 18 '&' => escaped.push_str("&"), 19 '"' => escaped.push_str("""), 20 other => escaped.push(other), 21 } 22 } 23 Cow::Owned(escaped) 24 } 25 26 /// Render a tiny template row, escaping each interpolated value. 27 fn render_row(fields: &HashMap<&str, &str>) -> String { 28 let name = escape_html(fields.get("name").copied().unwrap_or("")); 29 let bio = escape_html(fields.get("bio").copied().unwrap_or("")); 30 // `name` / `bio` are Cow<str>; they Deref to &str inside format!. 31 format!("<tr><td>{name}</td><td>{bio}</td></tr>") 32 } 33 34 fn main() { 35 let mut row = HashMap::new(); 36 row.insert("name", "Ada Lovelace"); // safe -> borrowed, no allocation 37 row.insert("bio", "Wrote the first <algorithm> & more"); // unsafe -> owned 38 println!("{}", render_row(&row)); 39 40 // Confirm the allocation decision: 41 let safe = escape_html("plain"); 42 let unsafe_ = escape_html("a & b"); 43 println!("safe borrowed: {}", matches!(safe, Cow::Borrowed(_))); 44 println!("unsafe owned: {}", matches!(unsafe_, Cow::Owned(_))); 45 } ``` **Output (verified with `cargo run`, and `cargo clippy` clean):** ```text 1 <tr><td>Ada Lovelace</td><td>Wrote the first <algorithm> & more</td></tr> 2 safe borrowed: true 3 unsafe owned: true ``` In a request handler processing thousands of fields per second, the `Cow::Borrowed` fast path means the overwhelmingly common “no escaping needed” case touches the heap zero times — exactly the kind of needless-allocation savings `Cow` exists to provide. > **Tip:** Holding the result as a `Cow` also lets the *caller* decide whether to keep it borrowed (cheap) or call `.into_owned()` to detach it. You preserve the choice instead of forcing an allocation on everyone. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [`std::borrow::Cow`](https://doc.rust-lang.org/std/borrow/enum.Cow.html): the type, its variants, and methods (`to_mut`, `into_owned`) * [`std::borrow::ToOwned`](https://doc.rust-lang.org/std/borrow/trait.ToOwned.html): the trait that links borrowed and owned forms * [`str::from_utf8_lossy`](https://doc.rust-lang.org/std/str/fn.from_utf8_lossy.html): a real standard-library API returning `Cow<'_, str>` * [Rust by Example — `Box`, stack and heap](https://doc.rust-lang.org/rust-by-example/std/box.html): background on heap allocation ### Related sections in this guide [Section titled “Related sections in this guide”](#related-sections-in-this-guide) * [Section 10 overview](/10-smart-pointers/): the full map of smart pointers * [Box\<T>](/10-smart-pointers/00-box/): `Box<T>` when you always want a single owned heap allocation * [Shared Ownership with `Rc<T>` and `Arc<T>`](/10-smart-pointers/01-rc-arc/): `Rc`/`Arc` for *shared* ownership (the opposite axis from `Cow`) * [Interior Mutability](/10-smart-pointers/02-refcell-mutex/) and [Cell\<T>](/10-smart-pointers/03-cell/): interior mutability of shared data * [The `Deref` Trait and Deref Coercion](/10-smart-pointers/06-deref-trait/): the `Deref` coercion that makes reading through a `Cow` feel like a plain reference * [Choosing a Smart Pointer](/10-smart-pointers/07-comparison/) — decision guide: which smart pointer for which need * [Section 05: Ownership](/05-ownership/): borrowing, lifetimes, and why `Cow::Borrowed` carries a `'a` * [Section 02: Basic Types](/02-basics/01-types/): `str` versus `String`, the borrowed/owned pair `Cow` is built on * [Section 11: Async](/11-async/): when crossing thread/`.await` boundaries, prefer `into_owned()` to detach a borrow *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Trim only when needed [Section titled “Exercise 1: Trim only when needed”](#exercise-1-trim-only-when-needed) **Difficulty:** Beginner **Objective:** Write a function that trims surrounding whitespace but stays `Cow::Borrowed` even when it does trim — proving that sub-slicing does not allocate. **Instructions:** Implement `trim_if_needed(input: &str) -> Cow<'_, str>`. If the trimmed string equals the input length, return the input untouched; otherwise return the trimmed sub-slice. Both arms should be `Cow::Borrowed`. Verify with inputs `"clean"` and `" spaced "`. ```rust 1 use std::borrow::Cow; 2 3 fn trim_if_needed(input: &str) -> Cow<'_, str> { 4 // TODO: return Cow::Borrowed in both cases (hint: trim() returns a sub-slice) 5 todo!() 6 } 7 8 fn main() { 9 let a = trim_if_needed("clean"); 10 let b = trim_if_needed(" spaced "); 11 println!("{a:?} borrowed={}", matches!(a, Cow::Borrowed(_))); 12 println!("{b:?} borrowed={}", matches!(b, Cow::Borrowed(_))); 13 } ``` Solution ```rust 1 use std::borrow::Cow; 2 3 fn trim_if_needed(input: &str) -> Cow<'_, str> { 4 let trimmed = input.trim(); 5 if trimmed.len() == input.len() { 6 Cow::Borrowed(input) 7 } else { 8 Cow::Borrowed(trimmed) // still a borrow! trim returns a sub-slice of input 9 } 10 } 11 12 fn main() { 13 let a = trim_if_needed("clean"); 14 let b = trim_if_needed(" spaced "); 15 println!("{a:?} borrowed={}", matches!(a, Cow::Borrowed(_))); 16 println!("{b:?} borrowed={}", matches!(b, Cow::Borrowed(_))); 17 } ``` **Output:** ```text 1 "clean" borrowed=true 2 "spaced" borrowed=true ``` The key insight: `trim()` returns a slice *into* the original string, so no allocation occurs even when characters are removed. `Cow` carries the same lifetime, so the borrow stays valid. *** ### Exercise 2: Normalize line endings [Section titled “Exercise 2: Normalize line endings”](#exercise-2-normalize-line-endings) **Difficulty:** Intermediate **Objective:** Avoid allocating for text that is already in Unix line-ending form. **Instructions:** Implement `normalize_newlines(text: &str) -> Cow<'_, str>` that converts `\r\n` and lone `\r` to `\n`. If the text contains no `\r`, return it borrowed; otherwise build the normalized `String` and return it owned. Verify with `"a\nb\nc"` (borrowed) and `"a\r\nb\r\nc"` (owned). ```rust 1 use std::borrow::Cow; 2 3 fn normalize_newlines(text: &str) -> Cow<'_, str> { 4 // TODO: borrow if there is no '\r'; otherwise replace and own 5 todo!() 6 } 7 8 fn main() { 9 let unix = normalize_newlines("a\nb\nc"); 10 let win = normalize_newlines("a\r\nb\r\nc"); 11 println!("unix borrowed: {}", matches!(unix, Cow::Borrowed(_))); 12 println!("win owned: {}", matches!(win, Cow::Owned(_))); 13 println!("win value: {win:?}"); 14 } ``` Solution ```rust 1 use std::borrow::Cow; 2 3 fn normalize_newlines(text: &str) -> Cow<'_, str> { 4 if text.contains('\r') { 5 // Replace CRLF first, then any remaining lone CR. 6 Cow::Owned(text.replace("\r\n", "\n").replace('\r', "\n")) 7 } else { 8 Cow::Borrowed(text) 9 } 10 } 11 12 fn main() { 13 let unix = normalize_newlines("a\nb\nc"); 14 let win = normalize_newlines("a\r\nb\r\nc"); 15 println!("unix borrowed: {}", matches!(unix, Cow::Borrowed(_))); 16 println!("win owned: {}", matches!(win, Cow::Owned(_))); 17 println!("win value: {win:?}"); 18 } ``` **Output:** ```text 1 unix borrowed: true 2 win owned: true 3 win value: "a\nb\nc" ``` `str::replace` always allocates a `String`, which is why we only call it inside the owned arm — files that are already LF-only never touch the heap. *** ### Exercise 3: Store borrowed-or-owned in a struct [Section titled “Exercise 3: Store borrowed-or-owned in a struct”](#exercise-3-store-borrowed-or-owned-in-a-struct) **Difficulty:** Advanced **Objective:** Use `Cow` as a struct field so the same type can hold a `'static` literal *without copying* or a runtime-generated `String`, and write a function returning `Cow<'a, str>` that conditionally appends a default file extension. **Instructions:** (a) Define `struct Config<'a> { name: Cow<'a, str> }` with constructors `from_static(name: &'a str)` (borrowed) and `generated(n: u32)` (owned, e.g. `format!("node-{n}")`). (b) Implement `with_extension<'a>(path: &'a str, ext: &str) -> Cow<'a, str>` that returns the path borrowed if it already has an extension, otherwise appends `.{ext}` and owns it. Use `std::path::Path::new(path).extension()` to detect an existing extension. ```rust 1 use std::borrow::Cow; 2 3 struct Config<'a> { 4 name: Cow<'a, str>, 5 } 6 7 impl<'a> Config<'a> { 8 fn from_static(name: &'a str) -> Self { 9 todo!() 10 } 11 fn generated(n: u32) -> Self { 12 todo!() 13 } 14 } 15 16 fn with_extension<'a>(path: &'a str, ext: &str) -> Cow<'a, str> { 17 todo!() 18 } 19 20 fn main() { 21 let a = Config::from_static("default"); 22 let b = Config::generated(7); 23 println!("a.name = {}, len {}", a.name, a.name.len()); 24 println!("b.name = {}", b.name); 25 26 let p1 = with_extension("report.pdf", "txt"); 27 let p2 = with_extension("report", "txt"); 28 println!("{p1} borrowed={}", matches!(p1, Cow::Borrowed(_))); 29 println!("{p2} owned={}", matches!(p2, Cow::Owned(_))); 30 } ``` Solution ```rust 1 use std::borrow::Cow; 2 3 #[derive(Debug)] 4 struct Config<'a> { 5 name: Cow<'a, str>, 6 } 7 8 impl<'a> Config<'a> { 9 // Zero-copy when the caller passes a literal (or any &'a str). 10 fn from_static(name: &'a str) -> Self { 11 Config { name: Cow::Borrowed(name) } 12 } 13 // Owned when built at runtime. 14 fn generated(n: u32) -> Self { 15 Config { name: Cow::Owned(format!("node-{n}")) } 16 } 17 } 18 19 fn with_extension<'a>(path: &'a str, ext: &str) -> Cow<'a, str> { 20 if std::path::Path::new(path).extension().is_some() { 21 Cow::Borrowed(path) 22 } else { 23 Cow::Owned(format!("{path}.{ext}")) 24 } 25 } 26 27 fn main() { 28 let a = Config::from_static("default"); 29 let b = Config::generated(7); 30 // .name derefs to &str 31 println!("a.name = {}, len {}", a.name, a.name.len()); 32 println!("b.name = {}", b.name); 33 34 let p1 = with_extension("report.pdf", "txt"); 35 let p2 = with_extension("report", "txt"); 36 println!("{p1} borrowed={}", matches!(p1, Cow::Borrowed(_))); 37 println!("{p2} owned={}", matches!(p2, Cow::Owned(_))); 38 } ``` **Output:** ```text 1 a.name = default, len 7 2 b.name = node-7 3 report.pdf borrowed=true 4 report.txt owned=true ``` Adding `Cow<'a, str>` as a field forces the lifetime parameter `'a` onto `Config`. That is the price of holding borrowed data, and the reward is that `from_static("default")` stores the literal with no heap allocation, while `generated` still owns its runtime string in the very same type. # Weak References with `Weak<T>` > Rc/Arc cycles leak in Rust with no garbage collector. Weak<T> is the non-owning back-reference you upgrade() to access, mirroring JavaScript's WeakRef. `Rc<T>` and `Arc<T>` give you shared ownership, but two values that own each other form a **reference cycle** that never reaches a count of zero: a genuine memory leak even in safe Rust. `Weak<T>` is the non-owning reference that lets you point *back* into a graph (child to parent, observer to subject) without keeping the target alive. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **`Weak<T>`** is a reference to data managed by an `Rc<T>` (or `Arc<T>`) that **does not contribute to the strong count**, so it never keeps the value alive. Because the data behind a `Weak` can disappear at any time, you cannot read it directly: you call **`upgrade()`**, which returns an `Option<Rc<T>>`: `Some` if the value is still alive, `None` if it has already been dropped. This is the closest Rust analog to JavaScript’s `WeakRef`, and it exists for exactly the same reason: to reference something without preventing it from being reclaimed. > **Note:** If you have not read it yet, start with [`01_rc-arc.md`](/10-smart-pointers/01-rc-arc/). `Weak<T>` only makes sense once you understand strong reference counting. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In JavaScript you almost never think about reference cycles, because the garbage collector traces reachability and reclaims cycles automatically. A parent/child tree where children point back at their parents “just works”: ```typescript 1 // TypeScript — a tree where children link back to their parents. 2 class TreeNode { 3 value: string; 4 parent: TreeNode | null = null; // strong reference back to parent 5 children: TreeNode[] = []; 6 7 constructor(value: string) { 8 this.value = value; 9 } 10 11 appendChild(child: TreeNode): void { 12 child.parent = this; // child -> parent 13 this.children.push(child); // parent -> child (a cycle!) 14 } 15 16 path(): string { 17 return this.parent ? `${this.parent.path()}/${this.value}` : this.value; 18 } 19 } 20 21 const html = new TreeNode("html"); 22 const body = new TreeNode("body"); 23 const p = new TreeNode("p"); 24 html.appendChild(body); 25 body.appendChild(p); 26 27 console.log(p.path()); // "html/body/p" 28 console.log(`body has ${body.children.length} child(ren)`); // 1 ``` The `parent` and `children` fields form a cycle (`body` references `p`, and `p` references `body`), yet the V8 garbage collector reclaims the whole tree once it is unreachable from the roots. JavaScript also has an explicit **`WeakRef`** for cases where you want to reference an object *without* keeping it alive: ```typescript 1 // JavaScript WeakRef — the closest analog to Rust's Weak<T>. 2 let strong: { value: number } | null = { value: 42 }; 3 const weak = new WeakRef(strong); 4 5 console.log(weak.deref()); // { value: 42 } — still reachable 6 strong = null; // drop the only strong reference 7 // Once the GC runs, weak.deref() *may* return undefined. 8 // (Timing is non-deterministic — the GC decides when.) ``` > **Note:** `WeakRef.prototype.deref()` returns the object **or `undefined`**, never an error. Rust’s `Weak::upgrade()` returns the value wrapped in an `Rc`, **or `None`**. The shapes line up almost exactly. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust has **no garbage collector**, so a reference cycle built from `Rc<T>` is a real leak: the strong counts prop each other up and never hit zero. The fix is to make the “back pointer” a `Weak<T>` so it does not count toward ownership. ```rust 1 // Rust — a tree where children link back to their parents via Weak. 2 use std::cell::RefCell; 3 use std::rc::{Rc, Weak}; 4 5 type ElementRef = Rc<Element>; 6 7 struct Element { 8 tag: String, 9 // Strong: a parent OWNS its children. 10 children: RefCell<Vec<ElementRef>>, 11 // Weak: a child REFERENCES its parent without owning it. 12 parent: RefCell<Weak<Element>>, 13 } 14 15 impl Element { 16 fn new(tag: &str) -> ElementRef { 17 Rc::new(Element { 18 tag: tag.to_string(), 19 children: RefCell::new(Vec::new()), 20 parent: RefCell::new(Weak::new()), // no parent yet 21 }) 22 } 23 24 fn append_child(parent: &ElementRef, child: ElementRef) { 25 // Rc::downgrade turns a strong Rc into a non-owning Weak. 26 *child.parent.borrow_mut() = Rc::downgrade(parent); 27 parent.children.borrow_mut().push(child); 28 } 29 30 fn path(&self) -> String { 31 // upgrade() returns Option<Rc<Element>>: Some if the parent is alive. 32 match self.parent.borrow().upgrade() { 33 Some(parent) => format!("{}/{}", parent.path(), self.tag), 34 None => self.tag.clone(), 35 } 36 } 37 } 38 39 fn main() { 40 let html = Element::new("html"); 41 let body = Element::new("body"); 42 let para = Element::new("p"); 43 44 Element::append_child(&html, Rc::clone(&body)); 45 Element::append_child(&body, Rc::clone(¶)); 46 47 println!("{}", para.path()); // "html/body/p" 48 println!("body has {} child(ren)", body.children.borrow().len()); // 1 49 } ``` Real output: ```text 1 html/body/p 2 body has 1 child(ren) ``` The shape mirrors the TypeScript tree: children point down with strong references and back up with weak ones. The important difference is that in Rust the *direction* of ownership is something you choose and the compiler/runtime enforces, whereas in JavaScript every reference is equally “strong” and the GC sorts it out. > **Note:** `RefCell` provides interior mutability so we can rewrite `parent`/`children` through a shared `&` reference. See [`02_refcell-mutex.md`](/10-smart-pointers/02-refcell-mutex/) for why that wrapper is needed here. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Why a cycle of `Rc` leaks [Section titled “Why a cycle of Rc leaks”](#why-a-cycle-of-rc-leaks) Every `Rc<T>` allocation carries two counts in its heap header: a **strong count** and a **weak count**. The value `T` is dropped when the strong count reaches `0`; the allocation itself is freed when *both* counts reach `0`. If two `Rc`s own each other, their strong counts can never fall to zero: ```rust 1 // This LEAKS: a strong cycle whose Drop never runs. 2 use std::cell::RefCell; 3 use std::rc::Rc; 4 5 struct Node { 6 name: String, 7 parent: RefCell<Option<Rc<Node>>>, // STRONG back-pointer — the bug 8 children: RefCell<Vec<Rc<Node>>>, 9 } 10 11 impl Drop for Node { 12 fn drop(&mut self) { 13 println!("Dropping node {}", self.name); 14 } 15 } 16 17 fn main() { 18 let parent = Rc::new(Node { 19 name: "parent".to_string(), 20 parent: RefCell::new(None), 21 children: RefCell::new(vec![]), 22 }); 23 let child = Rc::new(Node { 24 name: "child".to_string(), 25 parent: RefCell::new(None), 26 children: RefCell::new(vec![]), 27 }); 28 29 parent.children.borrow_mut().push(Rc::clone(&child)); // parent -> child (strong) 30 *child.parent.borrow_mut() = Some(Rc::clone(&parent)); // child -> parent (strong) 31 32 println!("parent strong = {}", Rc::strong_count(&parent)); 33 println!("child strong = {}", Rc::strong_count(&child)); 34 } ``` Real output: ```text 1 parent strong = 2 2 child strong = 2 ``` Notice what is **missing**: there are no `Dropping node ...` lines. When `main` ends, `parent`’s strong count drops from 2 to 1 (the `child.parent` field still holds one) and `child`’s drops from 2 to 1 (the `parent.children` field still holds one). Both stall at 1, neither destructor runs, and the memory is leaked. This compiles and runs without a single warning: the leak is logically wrong but not *unsafe*, which is why the borrow checker does not catch it. ### The fix: make the back-pointer `Weak` [Section titled “The fix: make the back-pointer Weak”](#the-fix-make-the-back-pointer-weak) Change `parent` from `Rc<Node>` to `Weak<Node>` and the cycle is broken, because a `Weak` does not raise the strong count. ```rust 1 use std::cell::RefCell; 2 use std::rc::{Rc, Weak}; 3 4 struct Node { 5 name: String, 6 parent: RefCell<Weak<Node>>, // Weak — does NOT keep parent alive 7 children: RefCell<Vec<Rc<Node>>>, // Strong — parent owns its children 8 } 9 10 impl Drop for Node { 11 fn drop(&mut self) { 12 println!("Dropping node {}", self.name); 13 } 14 } 15 16 fn main() { 17 let parent = Rc::new(Node { 18 name: "parent".to_string(), 19 parent: RefCell::new(Weak::new()), 20 children: RefCell::new(vec![]), 21 }); 22 let child = Rc::new(Node { 23 name: "child".to_string(), 24 parent: RefCell::new(Weak::new()), 25 children: RefCell::new(vec![]), 26 }); 27 28 parent.children.borrow_mut().push(Rc::clone(&child)); 29 *child.parent.borrow_mut() = Rc::downgrade(&parent); // strong -> weak 30 31 println!( 32 "parent strong = {}, weak = {}", 33 Rc::strong_count(&parent), 34 Rc::weak_count(&parent) 35 ); 36 println!( 37 "child strong = {}, weak = {}", 38 Rc::strong_count(&child), 39 Rc::weak_count(&child) 40 ); 41 42 if let Some(p) = child.parent.borrow().upgrade() { 43 println!("child's parent is {}", p.name); 44 } 45 } ``` Real output: ```text 1 parent strong = 1, weak = 1 2 child strong = 2, weak = 0 3 child's parent is parent 4 Dropping node parent 5 Dropping node child ``` Now both destructors run. The `parent` has `strong = 1` (the local `parent` binding) and `weak = 1` (the `child.parent` field). When `main` ends, `parent`’s strong count goes to `0`, its `Node` is dropped, which drops the `children` vector, which drops the last strong reference to `child`, which then drops too. No leak. ### `downgrade` and `upgrade` [Section titled “downgrade and upgrade”](#downgrade-and-upgrade) These two functions are the whole API: | Operation | Signature | Meaning | | -------------------- | --------------------------- | ------------------------------------------------------------------------- | | `Rc::downgrade(&rc)` | `&Rc<T> -> Weak<T>` | Create a non-owning handle; bumps the **weak** count | | `weak.upgrade()` | `&Weak<T> -> Option<Rc<T>>` | Try to get a real, owning `Rc`; bumps the **strong** count if it succeeds | | `Weak::new()` | `() -> Weak<T>` | An empty `Weak` that points at nothing (always upgrades to `None`) | `upgrade()` is the safety valve. Because the data may already be gone, you are *forced* to handle the `None` case; there is no way to dereference a `Weak` directly: ```rust 1 use std::rc::{Rc, Weak}; 2 3 fn main() { 4 let weak: Weak<i32>; 5 { 6 let strong = Rc::new(42); 7 weak = Rc::downgrade(&strong); 8 println!("inside scope: upgrade() = {:?}", weak.upgrade()); // Some(42) 9 } // `strong` dropped here -> value deallocated 10 11 println!("after scope: upgrade() = {:?}", weak.upgrade()); // None 12 13 let empty: Weak<i32> = Weak::new(); 14 println!("empty: upgrade() = {:?}", empty.upgrade()); // None 15 } ``` Real output: ```text 1 inside scope: upgrade() = Some(42) 2 after scope: upgrade() = None 3 empty: upgrade() = None ``` This is exactly the discipline JavaScript’s `WeakRef.deref()` asks of you (it may return `undefined`), except Rust encodes the possibility in the type system: `Option<Rc<T>>` cannot be ignored without the compiler complaining. ### `strong_count` vs `weak_count` [Section titled “strong\_count vs weak\_count”](#strong_count-vs-weak_count) `Rc::strong_count` and `Rc::weak_count` let you inspect the header counts, which is invaluable when debugging “why didn’t this drop?” issues. A live `Weak` raises `weak_count` but never `strong_count`; only `upgrade()` (while it succeeds) momentarily raises the strong count for the lifetime of the returned `Rc`. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / JavaScript | Rust | | ----------------------------- | ---------------------------------------- | ------------------------------------------------------------- | | Reclaiming cycles | Automatic: the GC traces reachability | Manual design: you must break cycles with `Weak<T>` | | Default reference strength | Every reference is “strong” | You choose `Rc`/`Arc` (strong) or `Weak` (weak) per field | | Non-owning reference | `WeakRef<T>` | `Weak<T>` | | Reading through a weak ref | `weak.deref()` -> `T \| undefined` | `weak.upgrade()` -> `Option<Rc<T>>` | | What happens on a leak | Effectively impossible with the GC | `Rc` cycles silently leak (safe, but wrong) | | When the value drops | When the GC decides nothing is reachable | Deterministically, when the last `Rc` strong count hits 0 | | Single-thread vs multi-thread | One model | `std::rc::Weak` (with `Rc`) or `std::sync::Weak` (with `Arc`) | ### Rust’s reasoning [Section titled “Rust’s reasoning”](#rusts-reasoning) Rust’s ownership model is built on **deterministic destruction**: you know *exactly* when a value is freed (when its owning scope ends or its last strong owner is dropped). A GC would undermine that guarantee. The trade-off is that *you* are responsible for not constructing ownership cycles, and `Weak<T>` is the tool the standard library gives you to express “I want to look at this, but I don’t own it.” The mental model that maps cleanly from JavaScript is: > **strong reference (`Rc`/`Arc`) = “keep this alive”; weak reference (`Weak`) = “let me peek if it’s still around.”** ### Two `Weak` types [Section titled “Two Weak types”](#two-weak-types) There are two distinct `Weak` types, and they are *not* interchangeable: * `std::rc::Weak<T>` pairs with `Rc<T>` — single-threaded, cheaper. * `std::sync::Weak<T>` pairs with `Arc<T>` — thread-safe, atomic counts. ```rust 1 // The thread-safe analog: Arc::downgrade produces a std::sync::Weak. 2 use std::sync::{Arc, Weak}; 3 4 fn main() { 5 let strong = Arc::new("shared".to_string()); 6 let weak: Weak<String> = Arc::downgrade(&strong); 7 8 println!( 9 "strong = {}, weak = {}", 10 Arc::strong_count(&strong), 11 Arc::weak_count(&strong) 12 ); 13 println!("upgrade = {:?}", weak.upgrade()); 14 15 drop(strong); 16 println!("after drop, upgrade = {:?}", weak.upgrade()); 17 } ``` Real output: ```text 1 strong = 1, weak = 1 2 upgrade = Some("shared") 3 after drop, upgrade = None ``` The API is identical; only the import (`std::sync` vs `std::rc`) and the partner type (`Arc` vs `Rc`) change. See [`01_rc-arc.md`](/10-smart-pointers/01-rc-arc/) for the strong-pointer differences. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Trying to use a `Weak` as if it were the value [Section titled “Pitfall 1: Trying to use a Weak as if it were the value”](#pitfall-1-trying-to-use-a-weak-as-if-it-were-the-value) A `Weak<T>` does **not** implement `Deref`, so you cannot read fields or call methods on it directly. You must `upgrade()` first. ```rust 1 use std::rc::{Rc, Weak}; 2 3 struct Node { 4 value: i32, 5 } 6 7 fn main() { 8 let strong = Rc::new(Node { value: 10 }); 9 let weak: Weak<Node> = Rc::downgrade(&strong); 10 11 // does not compile (error[E0609]: no field `value` on type `std::rc::Weak<Node>`) 12 println!("{}", weak.value); 13 } ``` Real compiler error: ```text 1 error[E0609]: no field `value` on type `std::rc::Weak<Node>` 2 --> src/main.rs:12:25 3 | 4 12 | println!("{}", weak.value); 5 | ^^^^^ unknown field ``` The fix is to upgrade and handle the `Option`: `if let Some(node) = weak.upgrade() { println!("{}", node.value); }`. ### Pitfall 2: Forgetting that `upgrade()` returns an `Option` [Section titled “Pitfall 2: Forgetting that upgrade() returns an Option”](#pitfall-2-forgetting-that-upgrade-returns-an-option) Even after you remember to call `upgrade()`, the result is `Option<Rc<T>>`, not `Rc<T>`. You still have to unwrap or pattern-match it. ```rust 1 use std::rc::{Rc, Weak}; 2 3 struct Node { 4 value: i32, 5 } 6 7 fn main() { 8 let strong = Rc::new(Node { value: 10 }); 9 let weak: Weak<Node> = Rc::downgrade(&strong); 10 11 // does not compile (error[E0609]: no field `value` on type `Option<Rc<Node>>`) 12 let node = weak.upgrade(); 13 println!("{}", node.value); 14 } ``` Real compiler error: ```text 1 error[E0609]: no field `value` on type `Option<Rc<Node>>` 2 --> src/main.rs:13:25 3 | 4 13 | println!("{}", node.value); 5 | ^^^^^ unknown field 6 | 7 help: one of the expressions' fields has a field of the same name 8 | 9 13 | println!("{}", node.unwrap().value); 10 | +++++++++ ``` > **Tip:** The compiler suggests `.unwrap()`, but in real code prefer `if let Some(node) = weak.upgrade()` or `weak.upgrade()?` so a dropped target turns into a graceful `None` rather than a panic. ### Pitfall 3: Making the child-to-parent link strong “for convenience” [Section titled “Pitfall 3: Making the child-to-parent link strong “for convenience””](#pitfall-3-making-the-child-to-parent-link-strong-for-convenience) This is the original leak. If both directions are `Rc`, nothing is ever freed. The rule of thumb that prevents it: **in a hierarchy, the owner direction is `Rc`/`Arc`; the back-reference is `Weak`.** A parent owns its children; a child merely *knows* its parent. ### Pitfall 4: Expecting an `upgraded` `Rc` to “stay” weak [Section titled “Pitfall 4: Expecting an upgraded Rc to “stay” weak”](#pitfall-4-expecting-an-upgraded-rc-to-stay-weak) `upgrade()` returns a genuine strong `Rc`. While you hold that `Rc`, the value is guaranteed alive and the strong count is raised. That is the point (it lets you safely use the value), but if you stash that upgraded `Rc` into a long-lived field, you have just re-created a strong reference (and possibly a cycle). Upgrade, use, and let the temporary `Rc` drop. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Encode ownership direction deliberately [Section titled “1. Encode ownership direction deliberately”](#1-encode-ownership-direction-deliberately) Decide which way ownership flows and stick to it: **strong down the tree, weak back up**. This single rule eliminates the vast majority of `Rc` cycles before they happen. ### 2. Initialize back-pointers with `Weak::new()` [Section titled “2. Initialize back-pointers with Weak::new()”](#2-initialize-back-pointers-with-weaknew) When constructing a node before its parent exists, seed the field with `Weak::new()`. It upgrades to `None`, which correctly models “no parent yet” (a root node), and you fill it in with `Rc::downgrade` once the parent is known. ### 3. Always handle the `None` from `upgrade()` [Section titled “3. Always handle the None from upgrade()”](#3-always-handle-the-none-from-upgrade) Treat `upgrade()` like any other fallible operation. Use `if let`, `match`, or the `?` operator. Reaching for `.unwrap()` defeats the purpose of `Weak`: the whole reason the value is weak is that it might be gone. ### 4. Use `Weak` for caches and observers, not just trees [Section titled “4. Use Weak for caches and observers, not just trees”](#4-use-weak-for-caches-and-observers-not-just-trees) A registry of `Weak` handles is a clean way to build a cache or an observer list that does **not** keep its entries alive: dead entries simply fail to upgrade and can be pruned. (See Exercise 3.) ### 5. Reach for `Weak` only when you actually need shared ownership [Section titled “5. Reach for Weak only when you actually need shared ownership”](#5-reach-for-weak-only-when-you-actually-need-shared-ownership) Most parent/child relationships in Rust are better modeled with plain references and lifetimes, an arena/index-based graph (e.g. storing nodes in a `Vec` and referring to them by `usize` index), or an ownership tree without back-pointers. `Rc`/`Weak` is the right tool when you genuinely need *shared* ownership with back-references and the graph shape is dynamic. > **Tip:** Index-based graphs (a `Vec<Node>` plus `usize` “handles”) sidestep both reference counting and `Weak` entirely, and are often the idiomatic choice for performance-sensitive graph and ECS code. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A DOM-like element tree is the canonical case: rendering walks *down* into children, while event bubbling and selector matching walk *up* to parents and the document root. The downward links own the nodes; the upward links must not, or the document would never free. ```rust 1 // Real-world: a DOM-like element tree with safe upward navigation. 2 use std::cell::RefCell; 3 use std::rc::{Rc, Weak}; 4 5 type ElementRef = Rc<Element>; 6 7 struct Element { 8 tag: String, 9 children: RefCell<Vec<ElementRef>>, // strong: parent owns children 10 parent: RefCell<Weak<Element>>, // weak: child references parent 11 } 12 13 impl Element { 14 fn new(tag: &str) -> ElementRef { 15 Rc::new(Element { 16 tag: tag.to_string(), 17 children: RefCell::new(Vec::new()), 18 parent: RefCell::new(Weak::new()), 19 }) 20 } 21 22 fn append_child(parent: &ElementRef, child: ElementRef) { 23 *child.parent.borrow_mut() = Rc::downgrade(parent); 24 parent.children.borrow_mut().push(child); 25 } 26 27 /// Build a `/html/body/p`-style path by walking weak parent links up. 28 fn path(&self) -> String { 29 match self.parent.borrow().upgrade() { 30 Some(parent) => format!("{}/{}", parent.path(), self.tag), 31 None => self.tag.clone(), 32 } 33 } 34 } 35 36 impl Drop for Element { 37 fn drop(&mut self) { 38 println!("freeing <{}>", self.tag); 39 } 40 } 41 42 fn main() { 43 let html = Element::new("html"); 44 let body = Element::new("body"); 45 let para = Element::new("p"); 46 47 Element::append_child(&html, Rc::clone(&body)); 48 Element::append_child(&body, Rc::clone(¶)); 49 50 // Navigate downward (strong) and upward (weak). 51 println!("path to <p>: {}", para.path()); 52 println!("<body> has {} child(ren)", body.children.borrow().len()); 53 println!( 54 "<html> strong={}, weak={}", 55 Rc::strong_count(&html), 56 Rc::weak_count(&html) 57 ); 58 59 drop(para); 60 drop(body); 61 println!("-- dropping document root --"); 62 drop(html); 63 } ``` Real output: ```text 1 path to <p>: html/body/p 2 <body> has 1 child(ren) 3 <html> strong=1, weak=1 4 -- dropping document root -- 5 freeing <html> 6 freeing <body> 7 freeing <p> ``` The `<html>` node has `strong=1` (the `html` binding) and `weak=1` (the back-pointer from `<body>`). When we drop the document root, the entire tree is reclaimed in order — no leak, fully deterministic. Swap `Rc`/`std::rc::Weak` for `Arc`/`std::sync::Weak` and the same structure works across threads. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [`std::rc::Weak`](https://doc.rust-lang.org/std/rc/struct.Weak.html) — the single-threaded weak pointer * [`std::sync::Weak`](https://doc.rust-lang.org/std/sync/struct.Weak.html) — the thread-safe weak pointer * [The Rust Book: Reference Cycles Can Leak Memory](https://doc.rust-lang.org/book/ch15-06-reference-cycles.html) * [`Rc::downgrade`](https://doc.rust-lang.org/std/rc/struct.Rc.html#method.downgrade) and [`Weak::upgrade`](https://doc.rust-lang.org/std/rc/struct.Weak.html#method.upgrade) ### Related Topics [Section titled “Related Topics”](#related-topics) * [`01_rc-arc.md`](/10-smart-pointers/01-rc-arc/): strong shared ownership; `Weak` is its non-owning counterpart * [`02_refcell-mutex.md`](/10-smart-pointers/02-refcell-mutex/) — interior mutability, used here to mutate `parent`/`children` * [`00_box.md`](/10-smart-pointers/00-box/): single-owner heap allocation and recursive types * [`07_comparison.md`](/10-smart-pointers/07-comparison/) — decision guide for choosing a smart pointer * [Section 05: Ownership](/05-ownership/) — the model that makes all of this necessary * [Section 02: Basics](/02-basics/) — types and ownership fundamentals * [Section 11: Async](/11-async/): where `Arc`/`Weak` show up in shared concurrent state *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Count the Living [Section titled “Exercise 1: Count the Living”](#exercise-1-count-the-living) **Difficulty:** Beginner **Objective:** Practice `downgrade` and `upgrade` and observe how a `Weak` reflects whether its target is alive. **Instructions:** Given a `Vec<Weak<i32>>`, write code that returns how many of the weak references still point to a live value. Construct a scenario where at least one target has been dropped, and verify the count. ```rust 1 use std::rc::{Rc, Weak}; 2 3 fn count_living(weaks: &[Weak<i32>]) -> usize { 4 // TODO: count how many entries still upgrade to Some 5 /* ??? */ 6 } 7 8 fn main() { 9 // TODO: build some Rc<i32>, downgrade them, drop one, then count. 10 } ``` Solution ```rust 1 use std::rc::{Rc, Weak}; 2 3 fn count_living(weaks: &[Weak<i32>]) -> usize { 4 weaks.iter().filter(|w| w.upgrade().is_some()).count() 5 } 6 7 fn main() { 8 let a = Rc::new(1); 9 let mut all: Vec<Weak<i32>> = vec![Rc::downgrade(&a), Rc::downgrade(&a)]; 10 11 let b = Rc::new(2); 12 all.push(Rc::downgrade(&b)); 13 14 drop(b); // invalidate the third weak 15 16 println!("living = {}", count_living(&all)); // 2 17 } ``` Real output: ```text 1 living = 2 ``` ### Exercise 2: Walk the Ancestors [Section titled “Exercise 2: Walk the Ancestors”](#exercise-2-walk-the-ancestors) **Difficulty:** Intermediate **Objective:** Build a parent/child tree with weak back-pointers and traverse upward without leaking. **Instructions:** Implement a `TreeNode` with a strong `children` vector and a `Weak` `parent`. Add an `ancestors(&self) -> Vec<i32>` method that returns the values of every ancestor from the immediate parent up to the root, by following the weak links. ```rust 1 use std::cell::RefCell; 2 use std::rc::{Rc, Weak}; 3 4 struct TreeNode { 5 value: i32, 6 parent: RefCell<Weak<TreeNode>>, 7 children: RefCell<Vec<Rc<TreeNode>>>, 8 } 9 10 impl TreeNode { 11 fn new(value: i32) -> Rc<TreeNode> { /* ??? */ } 12 fn add_child(parent: &Rc<TreeNode>, child: Rc<TreeNode>) { /* ??? */ } 13 fn ancestors(&self) -> Vec<i32> { 14 // TODO: walk parent links upward, collecting values 15 /* ??? */ 16 } 17 } 18 19 fn main() { 20 // Build root(1) -> mid(2) -> leaf(3); print leaf.ancestors() 21 } ``` Solution ```rust 1 use std::cell::RefCell; 2 use std::rc::{Rc, Weak}; 3 4 struct TreeNode { 5 value: i32, 6 parent: RefCell<Weak<TreeNode>>, 7 children: RefCell<Vec<Rc<TreeNode>>>, 8 } 9 10 impl TreeNode { 11 fn new(value: i32) -> Rc<TreeNode> { 12 Rc::new(TreeNode { 13 value, 14 parent: RefCell::new(Weak::new()), 15 children: RefCell::new(Vec::new()), 16 }) 17 } 18 19 fn add_child(parent: &Rc<TreeNode>, child: Rc<TreeNode>) { 20 *child.parent.borrow_mut() = Rc::downgrade(parent); 21 parent.children.borrow_mut().push(child); 22 } 23 24 fn ancestors(&self) -> Vec<i32> { 25 let mut out = Vec::new(); 26 let mut current = self.parent.borrow().upgrade(); 27 while let Some(node) = current { 28 out.push(node.value); 29 current = node.parent.borrow().upgrade(); 30 } 31 out 32 } 33 } 34 35 fn main() { 36 let root = TreeNode::new(1); 37 let mid = TreeNode::new(2); 38 let leaf = TreeNode::new(3); 39 TreeNode::add_child(&root, Rc::clone(&mid)); 40 TreeNode::add_child(&mid, Rc::clone(&leaf)); 41 42 println!("ancestors of leaf: {:?}", leaf.ancestors()); // [2, 1] 43 } ``` Real output: ```text 1 ancestors of leaf: [2, 1] ``` ### Exercise 3: A Weak-Valued Cache [Section titled “Exercise 3: A Weak-Valued Cache”](#exercise-3-a-weak-valued-cache) **Difficulty:** Advanced **Objective:** Use `Weak` to build a cache that does **not** keep its values alive; entries vanish automatically once the last strong owner is dropped. **Instructions:** Implement a `Cache` storing `HashMap<String, Weak<String>>`. The method `get_or_insert(key, make)` should return a live `Rc<String>` if the cached `Weak` still upgrades, otherwise build a new value with `make`, cache a `Weak` to it, and return the strong `Rc`. Demonstrate that a second call with both owners still alive hits the cache, but after dropping all strong owners the next call rebuilds. ```rust 1 use std::collections::HashMap; 2 use std::rc::{Rc, Weak}; 3 4 struct Cache { 5 map: HashMap<String, Weak<String>>, 6 } 7 8 impl Cache { 9 fn new() -> Self { /* ??? */ } 10 fn get_or_insert(&mut self, key: &str, make: impl FnOnce() -> String) -> Rc<String> { 11 // TODO: return the cached value if it still upgrades, else build+cache 12 /* ??? */ 13 } 14 } 15 16 fn main() { 17 // Show a cache hit, then drop all owners and show a rebuild. 18 } ``` Solution ```rust 1 use std::collections::HashMap; 2 use std::rc::{Rc, Weak}; 3 4 struct Cache { 5 map: HashMap<String, Weak<String>>, 6 } 7 8 impl Cache { 9 fn new() -> Self { 10 Cache { map: HashMap::new() } 11 } 12 13 fn get_or_insert(&mut self, key: &str, make: impl FnOnce() -> String) -> Rc<String> { 14 if let Some(existing) = self.map.get(key).and_then(Weak::upgrade) { 15 return existing; 16 } 17 let value = Rc::new(make()); 18 self.map.insert(key.to_string(), Rc::downgrade(&value)); 19 value 20 } 21 } 22 23 fn main() { 24 let mut cache = Cache::new(); 25 26 let a = cache.get_or_insert("k", || { 27 println!("building k"); 28 "value".to_string() 29 }); 30 // Both owners alive -> cache hit, no "building k". 31 let b = cache.get_or_insert("k", || { 32 println!("building k"); 33 "value".to_string() 34 }); 35 println!("same allocation: {}", Rc::ptr_eq(&a, &b)); 36 37 drop(a); 38 drop(b); // last strong owner gone -> cached Weak is now dead 39 40 // Rebuilds: "building k" prints again. 41 let _c = cache.get_or_insert("k", || { 42 println!("building k"); 43 "value".to_string() 44 }); 45 } ``` Real output: ```text 1 building k 2 same allocation: true 3 building k ``` The first call builds and caches a `Weak`; the second upgrades the live `Weak` (same allocation, no rebuild). After both strong owners drop, the cached `Weak` can no longer upgrade, so the third call rebuilds. This is precisely how a memory-sensitive cache avoids keeping objects alive purely for caching. *** ## Summary [Section titled “Summary”](#summary) * A cycle of `Rc<T>`/`Arc<T>` **leaks** in Rust — there is no GC to reclaim it. The strong counts hold each other above zero forever. * **`Weak<T>`** is a non-owning reference: it raises the *weak* count, never the *strong* count, so it never keeps a value alive. * Create one with **`Rc::downgrade(&rc)`** (or `Arc::downgrade`), and access the data with **`upgrade()`**, which returns **`Option<Rc<T>>`** — `Some` if alive, `None` if dropped. * The idiomatic rule: **own downward with strong references, point back upward with weak ones.** * `std::rc::Weak` pairs with `Rc` (single-threaded); `std::sync::Weak` pairs with `Arc` (thread-safe). The API is otherwise identical. # The `Deref` Trait and Deref Coercion > The Deref trait lets a Rust smart pointer act like the value it wraps. It explains why &String works where &str is expected and why you rarely write * on a Box. The `Deref` trait is the mechanism that lets a smart pointer behave like the value it points to. It is also the quiet machinery behind one of the first “magic” things a TypeScript developer notices in Rust: why a `&String` works where a `&str` is expected, and why you almost never have to write `*` to call a method on a `Box`. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In JavaScript and TypeScript there is no concept of dereferencing: a variable that holds an object *is* the reference, and `obj.method()` always reaches the object directly. Rust separates a value from a pointer to that value, so it needs a rule for “follow the pointer.” The **`Deref`** trait defines that rule, and the compiler uses it to perform **deref coercion**: automatically converting `&Wrapper` into `&Inner` (and `&Inner` into `&InnerInner`, as deep as needed) at method-call and argument-passing sites. For a working TypeScript developer, the payoff is concrete: `Deref` is why `Box<T>`, `Rc<T>`, `String`, and `Vec<T>` all let you call the inner type’s methods directly, and why passing `&my_string` to a `fn(&str)` “just works.” *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) TypeScript has no dereference operator and no user-definable “act like the thing I wrap” hook. The closest everyday experiences are: (1) accessing a wrapped value works transparently because there is no wrapper to see through, and (2) string primitives auto-box to `String` objects so you can call methods on them. ```typescript 1 // In TypeScript a "wrapper" has to expose the inner API by hand — 2 // there is no language hook that says "treat me as my inner value." 3 class Username { 4 constructor(private readonly value: string) {} 5 6 // You must manually re-expose every method you want callers to use... 7 get length(): number { 8 return this.value.length; 9 } 10 toUpperCase(): string { 11 return this.value.toUpperCase(); 12 } 13 // ...or expose the raw string and make callers reach in: 14 unwrap(): string { 15 return this.value; 16 } 17 } 18 19 function logLine(label: string, value: string): void { 20 console.log(`${label}: ${value}`); 21 } 22 23 const user = new Username("ada_lovelace"); 24 25 // A `Username` is NOT a `string`, so this is a type error in TS: 26 // logLine("user", user); // Argument of type 'Username' is not assignable to 'string' 27 logLine("user", user.unwrap()); // you must unwrap explicitly 28 console.log(user.length); // 12 — only works because we hand-wrote a getter 29 console.log(user.toUpperCase()); // works only because we re-implemented it 30 31 // Separately: JS string *primitives* auto-box to String objects, 32 // which is the one place JS does something "deref-like" for you. 33 const s = "hello"; 34 console.log(s.toUpperCase()); // HELLO — the primitive is boxed transiently ``` **Key points:** * A `Username` wrapper has to manually forward every method, or force callers to `unwrap()`. * There is no way to say “a `Username` can be used anywhere a `string` is expected.” * The only built-in “transparent” behavior is primitive auto-boxing (`"hello".toUpperCase()`), and you cannot extend it to your own types. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust lets your wrapper opt into “act like my inner value” by implementing `Deref`. After that, the inner type’s methods are callable directly, and a `&Wrapper` coerces into a `&Inner` at call sites. No manual forwarding, no `unwrap()`. ```rust 1 use std::ops::Deref; 2 3 /// A newtype guaranteeing the wrapped string is non-empty and trimmed. 4 #[derive(Debug, Clone)] 5 struct Username(String); 6 7 impl Username { 8 fn new(raw: &str) -> Result<Username, String> { 9 let trimmed = raw.trim(); 10 if trimmed.is_empty() { 11 Err("username must not be empty".to_string()) 12 } else { 13 Ok(Username(trimmed.to_string())) 14 } 15 } 16 } 17 18 // Deref to `str` exposes the entire string-slice API for free. 19 impl Deref for Username { 20 type Target = str; 21 fn deref(&self) -> &str { 22 &self.0 23 } 24 } 25 26 fn log_line(label: &str, value: &str) { 27 println!("{label}: {value}"); 28 } 29 30 fn main() { 31 let user = Username::new(" ada_lovelace ").expect("valid"); 32 33 log_line("user", &user); // &Username coerces to &str — no unwrap 34 println!("len = {}", user.len()); // str::len, straight through 35 println!("upper = {}", user.to_uppercase()); // str::to_uppercase, straight through 36 println!("ada? = {}", user.starts_with("ada")); 37 } ``` **Output:** ```text 1 user: ada_lovelace 2 len = 12 3 upper = ADA_LOVELACE 4 ada? = true ``` The single `impl Deref` replaces all the hand-written forwarding the TypeScript version needed. The validating constructor still guarantees the invariant; `Deref` only governs *read* access to the inner `str`. > **Note:** Implementing `Deref` to expose an inner API is acceptable for thin **newtype** wrappers like this, but it is *not* a general inheritance mechanism. See [Common Pitfalls](#common-pitfalls) and [Best Practices](#best-practices). Use it deliberately. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What `Deref` actually is [Section titled “What Deref actually is”](#what-deref-actually-is) `Deref` is a trait from `std::ops` with one associated type and one method: ```rust 1 // (Definition from the standard library, shown for reference.) 2 pub trait Deref { 3 type Target: ?Sized; 4 fn deref(&self) -> &Self::Target; 5 } ``` * `Target` is the type you “become” when dereferenced. * `deref(&self) -> &Target` returns a **reference** to the inner value (never a moved/owned value; that is important for the borrow checker). When you write `*value` and `value` is not a plain reference, the compiler rewrites it as `*(value.deref())`. That is: call `deref()` to get a `&Target`, then apply the built-in `*` to that reference. So `*boxed_string` means `*(boxed_string.deref())`. ### Deref coercion: the automatic part [Section titled “Deref coercion: the automatic part”](#deref-coercion-the-automatic-part) The genuinely useful behavior is **deref coercion**. In two specific situations the compiler will *automatically* insert `.deref()` calls, as many as needed, to make types line up: 1. **Argument passing / reference site:** if you have a `&T` and a function wants `&U`, and `T: Deref<Target = U>` (transitively), the compiler inserts the coercion. 2. **Method receiver resolution:** when you call `value.method()`, the compiler tries `value`, then `*value`, then `**value`, and so on, following `Deref` impls, until it finds a type that has `method`. This is why all of the following work without a single explicit `*`: ```rust 1 use std::rc::Rc; 2 3 fn main() { 4 // Box<T> implements Deref<Target = T>, so String's methods are reachable. 5 let boxed = Box::new(String::from("hello")); 6 println!("len via box = {}", boxed.len()); // String::len through Box 7 println!("upper = {}", boxed.to_uppercase()); // String::to_uppercase through Box 8 9 // Rc<T> also implements Deref (read-only). 10 let shared = Rc::new(vec![10, 20, 30]); 11 println!("first = {:?}", shared.first()); // <[i32]>::first through Rc -> Vec -> slice 12 println!("sum = {}", shared.iter().sum::<i32>()); 13 14 // Three different smart pointers, all coerce to &str for one &str function: 15 fn shout(s: &str) -> String { 16 s.to_uppercase() 17 } 18 let a = String::from("box"); 19 let b = Box::new(String::from("rc")); 20 let c = Rc::new(String::from("string")); 21 println!("{} {} {}", shout(&a), shout(&b), shout(&c)); 22 } ``` **Output:** ```text 1 len via box = 5 2 upper = HELLO 3 first = Some(10) 4 sum = 60 5 BOX RC STRING ``` Notice the `shared.first()` case chains coercions: `Rc<Vec<i32>>` → `Vec<i32>` → `[i32]` (a slice), and `first` lives on the slice. The compiler walks the whole `Deref` chain for you. ### Why `&String` works where `&str` is expected [Section titled “Why \&String works where \&str is expected”](#why-string-works-where-str-is-expected) This is the canonical example, and it is pure deref coercion. The standard library implements `impl Deref for String { type Target = str; ... }`. So when you call a `fn greet(name: &str)` with a `&String`, the compiler sees the mismatch, finds `String: Deref<Target = str>`, and inserts the coercion automatically. ```rust 1 fn greet(name: &str) { 2 println!("Hello, {name}!"); 3 } 4 5 fn main() { 6 let owned: String = String::from("Ada"); 7 8 greet(&owned); // &String -> &str, coercion inserted by the compiler 9 greet("Grace"); // a literal is already &str 10 11 // Box<String> -> &String -> &str (two coercions in a row): 12 let boxed: Box<String> = Box::new(String::from("Linus")); 13 greet(&boxed); 14 15 // The hand-written equivalents the compiler is sparing you: 16 greet(owned.as_str()); // explicit &str 17 greet(&owned[..]); // explicit full-range slice 18 } ``` **Output:** ```text 1 Hello, Ada! 2 Hello, Grace! 3 Hello, Linus! 4 Hello, Ada! 5 Hello, Ada! ``` > **Tip:** Prefer `&str` over `&String` for function parameters *because* of this coercion. A `fn(&str)` accepts string literals, `&String`, `&Box<String>`, and slices; a `fn(&String)` accepts only an owned `String` behind a reference. This is covered more in [Functions](/03-functions/). ### `DerefMut`: the mutable counterpart [Section titled “DerefMut: the mutable counterpart”](#derefmut-the-mutable-counterpart) `Deref` gives `&Target`. To get `&mut Target` (for mutation through the wrapper, or to mutate behind a `Box`), implement `DerefMut`: ```rust 1 use std::ops::{Deref, DerefMut}; 2 3 struct MyBox<T>(T); 4 5 impl<T> MyBox<T> { 6 fn new(x: T) -> MyBox<T> { 7 MyBox(x) 8 } 9 } 10 11 impl<T> Deref for MyBox<T> { 12 type Target = T; 13 fn deref(&self) -> &T { 14 &self.0 15 } 16 } 17 18 impl<T> DerefMut for MyBox<T> { 19 fn deref_mut(&mut self) -> &mut T { 20 &mut self.0 21 } 22 } 23 24 fn main() { 25 let b = MyBox::new(5); 26 println!("*b = {}", *b); // Deref: *(b.deref()) 27 28 let mut words = MyBox::new(vec!["a", "b"]); 29 words.push("c"); // DerefMut coercion: (*words).push("c") 30 println!("len = {}", words.len()); // Deref coercion: (*words).len() 31 println!("{:?}", *words); 32 } ``` **Output:** ```text 1 *b = 5 2 len = 3 3 ["a", "b", "c"] ``` `DerefMut` requires `Deref` as a supertrait (you must have both), and coercion of mutable references (`&mut T` → `&mut U`) follows the same rules through `DerefMut`. ### How `Box` deref differs slightly [Section titled “How Box deref differs slightly”](#how-box-deref-differs-slightly) `Box<T>` participates in deref coercion exactly like the examples above, so `boxed.method()` and `greet(&boxed)` work. `Box<T>` has one extra power the others lack: because the compiler knows a `Box` is the *unique* owner, dereferencing an **owned** box (`let inner = *boxed;`) can *move* the value out of the heap. That is a special compiler rule for `Box`, not something `Deref` itself provides; `deref()` only ever returns a `&Target`. The owning-move behavior is covered in [Box\<T>](/10-smart-pointers/00-box/); here, focus on the shared-reference coercion that all smart pointers share. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / JavaScript | Rust with `Deref` | | ---------------------------- | ------------------------------------------ | ------------------------------------------------------------------ | | Dereferencing | No concept; a variable is the reference | `*value` follows the pointer (sugar for `*value.deref()`) | | “Act like inner value” | Manual method forwarding or `.unwrap()` | One `impl Deref` exposes the inner API | | `&String` vs `&str` | n/a (one `string` type) | Coercion makes `&String` usable as `&str` | | Auto-conversion at call site | Only primitive auto-boxing, not extensible | Deref coercion, user-extensible per type | | Mutable access | Always available on the object | Separate `DerefMut` trait, opt-in | | Method lookup | Single prototype chain | Compiler walks the `Deref` chain (`value`, `*value`, `**value`, …) | | Where it triggers | n/a | Method receivers and `&`/`&mut` argument sites only | The mental shift: in TypeScript “transparency” is the default and you *can’t* customize it. In Rust, transparency is opt-in (`impl Deref`), explicit about read vs. write (`Deref` vs `DerefMut`), and applies only in the two well-defined coercion situations: never to operators like `==`, never to generic trait bounds. ### Where the `&String`/`&str` analogy breaks down [Section titled “Where the \&String/\&str analogy breaks down”](#where-the-stringstr-analogy-breaks-down) Unlike TypeScript’s single `string`, Rust deliberately has two types: `String` (owned, growable, heap) and `str` / `&str` (a borrowed view). `Deref<Target = str>` is the bridge that makes them interoperate smoothly, but they remain distinct types. You cannot, for example, push to a `&str` (it is a read-only view), and a function returning `&str` is promising not to allocate. The coercion smooths the ergonomics; it does not erase the distinction the way TypeScript’s single type does. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Expecting deref coercion to satisfy a generic trait bound [Section titled “Pitfall 1: Expecting deref coercion to satisfy a generic trait bound”](#pitfall-1-expecting-deref-coercion-to-satisfy-a-generic-trait-bound) Coercion happens for **references at call sites** and **method receivers** — *not* for generic type parameters. A `Box<String>` does **not** implement a trait just because `String` does. ```rust 1 trait Greet { 2 fn greet(&self) -> String; 3 } 4 5 impl Greet for String { 6 fn greet(&self) -> String { 7 format!("hi {self}") 8 } 9 } 10 11 fn run<T: Greet>(t: T) -> String { 12 t.greet() 13 } 14 15 fn main() { 16 let boxed = Box::new(String::from("ada")); 17 println!("{}", run(boxed)); // does not compile (error[E0277]: Box<String>: Greet not satisfied) 18 } ``` The real compiler error: ```text 1 error[E0277]: the trait bound `Box<String>: Greet` is not satisfied 2 --> src/main.rs:19:24 3 | 4 19 | println!("{}", run(boxed)); 5 | --- ^^^^^ the trait `Greet` is not implemented for `Box<String>` 6 | | 7 | required by a bound introduced by this call 8 | 9 note: required by a bound in `run` 10 --> src/main.rs:11:11 11 | 12 11 | fn run<T: Greet>(t: T) -> String { 13 | ^^^^^ required by this bound in `run` 14 help: consider dereferencing here 15 | 16 19 | println!("{}", run(*boxed)); 17 | + ``` The fix is in the help text: dereference explicitly (`run(*boxed)`) so you pass a real `String`. Deref coercion will not do this for you across a generic bound. ### Pitfall 2: Mutating through a wrapper that only implements `Deref` [Section titled “Pitfall 2: Mutating through a wrapper that only implements Deref”](#pitfall-2-mutating-through-a-wrapper-that-only-implements-deref) If you implement `Deref` but forget `DerefMut`, you get read access but not write access through the wrapper. ```rust 1 use std::ops::Deref; 2 3 struct Wrapper(Vec<i32>); 4 5 impl Deref for Wrapper { 6 type Target = Vec<i32>; 7 fn deref(&self) -> &Vec<i32> { 8 &self.0 9 } 10 } 11 12 fn main() { 13 let mut w = Wrapper(vec![1, 2, 3]); 14 println!("len = {}", w.len()); // ok: Deref gives &Vec 15 w.push(4); // does not compile (error[E0596]: needs DerefMut) 16 println!("{:?}", *w); 17 } ``` The real compiler error (trimmed): ```text 1 error[E0596]: cannot borrow data in dereference of `Wrapper` as mutable 2 --> src/main.rs:15:5 3 | 4 15 | w.push(4); // needs DerefMut, which is not implemented 5 | ^ cannot borrow as mutable 6 | 7 = help: trait `DerefMut` is required to modify through a dereference, but it is not implemented for `Wrapper` ``` The error message names the exact fix: implement `DerefMut for Wrapper`. ### Pitfall 3: Assuming operators like `==` use deref coercion [Section titled “Pitfall 3: Assuming operators like == use deref coercion”](#pitfall-3-assuming-operators-like--use-deref-coercion) Deref coercion applies to method calls and reference arguments — **not** to binary operators. `==` is governed by the `PartialEq` trait, which is not subject to coercion. ```rust 1 use std::ops::Deref; 2 3 struct MyBox<T>(T); 4 5 impl<T> Deref for MyBox<T> { 6 type Target = T; 7 fn deref(&self) -> &T { 8 &self.0 9 } 10 } 11 12 fn main() { 13 let b = MyBox(String::from("hi")); 14 let same = b == String::from("hi"); // does not compile (error[E0369]) 15 println!("{same}"); 16 } ``` The real compiler error: ```text 1 error[E0369]: binary operation `==` cannot be applied to type `MyBox<String>` 2 --> src/main.rs:10:18 3 | 4 10 | let same = b == String::from("hi"); 5 | - ^^ ------------------ String 6 | | 7 | MyBox<String> 8 | 9 note: an implementation of `PartialEq<String>` might be missing for `MyBox<String>` ``` To compare, dereference explicitly (`*b == String::from("hi")`) or derive/implement `PartialEq` on the wrapper. ### Pitfall 4: Using `Deref` as a substitute for inheritance [Section titled “Pitfall 4: Using Deref as a substitute for inheritance”](#pitfall-4-using-deref-as-a-substitute-for-inheritance) It is tempting, coming from class-based TypeScript, to give a “subclass-like” struct a `Deref` to a “base” struct so the base’s methods leak through. The Rust community considers this an **anti-pattern**: it confuses method resolution, surprises readers (`self_type.some_method()` may belong to the target), and breaks down because traits are not inherited via `Deref`. `Deref` is for smart pointers and thin newtypes whose `Target` genuinely “is” the value — not for modeling “is-a” relationships. Prefer composition with explicit delegation, or traits, instead. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Implement `Deref` only for smart-pointer-like types and thin newtypes.** Good targets: a guard that wraps one value, a validated newtype that should behave like its inner `str`/slice. Bad target: a domain struct you want to “inherit” from another. * **Choose the most useful `Target`.** For a string newtype, `Deref<Target = str>` (not `String`) exposes the slice API and coerces further to `&str`. For a `Vec` newtype, `Deref<Target = [T]>` gives the slice API while hiding mutating `Vec` methods. * **Implement `DerefMut` only when mutation through the wrapper is genuinely intended**, and remember it requires `Deref` as a supertrait. * **Prefer `&str` and `&[T]` parameters over `&String`/`&Vec<T>`.** Deref coercion makes the slice forms strictly more flexible callers-side. (See [Functions](/03-functions/).) * **Never return an owned value from `deref`.** The signature is `&self -> &Target`; trying to compute and return a fresh value each call is a sign you want a method or a `From`/`Into` conversion instead. * **Reach for `AsRef<T>` / `Into<T>` for explicit conversions.** If you only need a one-off conversion (not transparent pointer-like behavior), `AsRef`/`From`/`Into` express intent more honestly than `Deref`. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A common production pattern is a **bounded stack**: a collection with its own `push`/`pop` policy that nonetheless wants to offer the full read-only slice API (`len`, `iter`, `first`, `contains`, …) without re-implementing each method. `Deref<Target = [T]>` delivers exactly that: the wrapper controls mutation, while reads flow through to the slice. ```rust 1 use std::ops::Deref; 2 3 /// A stack with a fixed capacity. It owns its `push`/`pop` policy, but 4 /// `Deref`s to `[T]` so every read-only slice method is available for free. 5 struct BoundedStack<T> { 6 items: Vec<T>, 7 capacity: usize, 8 } 9 10 impl<T> BoundedStack<T> { 11 fn new(capacity: usize) -> Self { 12 BoundedStack { items: Vec::new(), capacity } 13 } 14 15 /// Push, or hand the rejected item back if the stack is full. 16 fn push(&mut self, item: T) -> Result<(), T> { 17 if self.items.len() == self.capacity { 18 Err(item) 19 } else { 20 self.items.push(item); 21 Ok(()) 22 } 23 } 24 25 fn pop(&mut self) -> Option<T> { 26 self.items.pop() 27 } 28 } 29 30 // Deref to a slice: the whole read-only `[T]` API, for free. 31 impl<T> Deref for BoundedStack<T> { 32 type Target = [T]; 33 fn deref(&self) -> &[T] { 34 &self.items 35 } 36 } 37 38 fn main() { 39 let mut stack: BoundedStack<i32> = BoundedStack::new(2); 40 println!("push 1: {:?}", stack.push(1)); 41 println!("push 2: {:?}", stack.push(2)); 42 println!("push 3: {:?}", stack.push(3)); // full -> Err(3) 43 44 // Everything below comes from `[T]` via deref coercion: 45 println!("len = {}", stack.len()); 46 println!("is_empty = {}", stack.is_empty()); 47 println!("first = {:?}", stack.first()); 48 println!("contains = {}", stack.contains(&2)); 49 let total: i32 = stack.iter().sum(); 50 println!("sum = {total}"); 51 52 println!("pop = {:?}", stack.pop()); 53 println!("len = {}", stack.len()); 54 } ``` **Output:** ```text 1 push 1: Ok(()) 2 push 2: Ok(()) 3 push 3: Err(3) 4 len = 2 5 is_empty = false 6 first = Some(1) 7 contains = true 8 sum = 3 9 pop = Some(2) 10 len = 1 ``` The `BoundedStack` exposes a deliberately small *mutating* surface (`push` enforces the capacity, `pop` is the only other writer) while inheriting the entire read API of a slice. Because the `Target` is `[T]` rather than `Vec<T>`, callers cannot bypass the policy by calling `Vec::push` through the wrapper: the slice type has no such method. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Rust Book — Treating Smart Pointers Like Regular References with `Deref`](https://doc.rust-lang.org/book/ch15-02-deref.html) * [`std::ops::Deref` API docs](https://doc.rust-lang.org/std/ops/trait.Deref.html) * [`std::ops::DerefMut` API docs](https://doc.rust-lang.org/std/ops/trait.DerefMut.html) * [Rust by Example — `Deref`](https://doc.rust-lang.org/rust-by-example/trait/deref.html) * [Rust API Guidelines — Smart pointers do not add inherent methods (C-SMART-PTR)](https://rust-lang.github.io/api-guidelines/predictability.html#smart-pointers-do-not-add-inherent-methods-c-smart-ptr) ### Related topics in this guide [Section titled “Related topics in this guide”](#related-topics-in-this-guide) * [Section 10 overview](/10-smart-pointers/): the full map of smart pointers * [Box\<T>](/10-smart-pointers/00-box/): `Box<T>` and its special owned-deref move * [Shared Ownership with `Rc<T>` and `Arc<T>`](/10-smart-pointers/01-rc-arc/): `Rc`/`Arc` also implement `Deref` for read access * [Interior Mutability](/10-smart-pointers/02-refcell-mutex/): interior mutability; `borrow()`/`lock()` return deref-able guards * [Clone-on-Write with `Cow<'_, T>`](/10-smart-pointers/04-cow/) — `Cow` implements `Deref` to its borrowed/owned target * [Choosing a Smart Pointer](/10-smart-pointers/07-comparison/) — decision guide: which smart pointer to pick when * [Functions](/03-functions/) — why `&str` parameters beat `&String` (deref coercion in action) * [Ownership](/05-ownership/) — references and borrowing, the foundation `Deref` builds on * [Generics & Traits](/09-generics-traits/) — traits and trait bounds (and why coercion does not satisfy them) * [Async](/11-async/) — `Pin` and deref show up together when working with futures *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A sentence newtype that acts like a `str` [Section titled “Exercise 1: A sentence newtype that acts like a str”](#exercise-1-a-sentence-newtype-that-acts-like-a-str) **Difficulty:** Beginner **Objective:** Implement `Deref` so a wrapper type can be used wherever a `&str` is expected and can call `str` methods directly. **Instructions:** Define `struct Sentence(String)`. Implement `Deref<Target = str>` for it. Then write a free function `fn word_count(s: &str) -> usize` and call it by passing `&sentence` (relying on deref coercion). Also call `to_uppercase()` and `len()` directly on the `Sentence` value. ```rust 1 use std::ops::Deref; 2 3 struct Sentence(String); 4 5 impl Deref for Sentence { 6 type Target = str; 7 fn deref(&self) -> &str { 8 /* ??? */ 9 } 10 } 11 12 fn word_count(s: &str) -> usize { 13 // TODO: count whitespace-separated words 14 } 15 16 fn main() { 17 let s = Sentence(String::from("the quick brown fox")); 18 println!("words = {}", word_count(&s)); // expect 4 19 println!("upper = {}", s.to_uppercase()); 20 println!("len = {}", s.len()); 21 } ``` Solution ```rust 1 use std::ops::Deref; 2 3 struct Sentence(String); 4 5 impl Deref for Sentence { 6 type Target = str; 7 fn deref(&self) -> &str { 8 &self.0 9 } 10 } 11 12 fn word_count(s: &str) -> usize { 13 s.split_whitespace().count() 14 } 15 16 fn main() { 17 let s = Sentence(String::from("the quick brown fox")); 18 // Deref coercion: &Sentence -> &str 19 println!("words = {}", word_count(&s)); 20 // str methods straight through the wrapper: 21 println!("upper = {}", s.to_uppercase()); 22 println!("len = {}", s.len()); 23 } ``` **Output:** ```text 1 words = 4 2 upper = THE QUICK BROWN FOX 3 len = 19 ``` The single `impl Deref` is all it takes: `&Sentence` coerces to `&str` for `word_count`, and `to_uppercase`/`len` resolve onto the `str` target via method-receiver deref. ### Exercise 2: A read-counting smart pointer with `Deref` and `DerefMut` [Section titled “Exercise 2: A read-counting smart pointer with Deref and DerefMut”](#exercise-2-a-read-counting-smart-pointer-with-deref-and-derefmut) **Difficulty:** Intermediate **Objective:** Build a real smart pointer that observes how often its inner value is read, demonstrating both `Deref` and `DerefMut`. **Instructions:** Define `struct Logged<T>` holding the value and a read counter. Implement `Deref` so each call to `deref` bumps the counter, and `DerefMut` so the value can be mutated. Use `std::cell::Cell<u32>` for the counter so you can mutate it from `&self` (see [Cell\<T>](/10-smart-pointers/03-cell/)). Add a `read_count(&self) -> u32` method. Show that calling `.len()`, `.first()`, and `.iter()` on a wrapped `Vec` each count as a read, and that `*counter += 1` works via `DerefMut`. Solution ```rust 1 use std::cell::Cell; 2 use std::ops::{Deref, DerefMut}; 3 4 struct Logged<T> { 5 value: T, 6 reads: Cell<u32>, 7 } 8 9 impl<T> Logged<T> { 10 fn new(value: T) -> Self { 11 Logged { value, reads: Cell::new(0) } 12 } 13 fn read_count(&self) -> u32 { 14 self.reads.get() 15 } 16 } 17 18 impl<T> Deref for Logged<T> { 19 type Target = T; 20 fn deref(&self) -> &T { 21 self.reads.set(self.reads.get() + 1); // Cell lets us mutate from &self 22 &self.value 23 } 24 } 25 26 impl<T> DerefMut for Logged<T> { 27 fn deref_mut(&mut self) -> &mut T { 28 &mut self.value 29 } 30 } 31 32 fn main() { 33 let logged = Logged::new(vec![1, 2, 3]); 34 println!("len = {}", logged.len()); // deref #1 35 println!("first = {:?}", logged.first()); // deref #2 36 let _sum: i32 = logged.iter().sum(); // deref #3 37 println!("reads = {}", logged.read_count()); 38 39 let mut counter = Logged::new(0u32); 40 *counter += 1; // DerefMut 41 *counter += 1; // DerefMut 42 println!("counter = {}", *counter); 43 } ``` **Output:** ```text 1 len = 3 2 first = Some(1) 3 reads = 3 4 counter = 2 ``` Each method call on `logged` goes through `deref` once, so the counter lands on `3`. `DerefMut` is what makes `*counter += 1` legal — without it you would hit `error[E0594]`/`E0596`. Using `Cell` for the counter is the idiomatic way to mutate bookkeeping state from the `&self` signature `deref` requires. ### Exercise 3: A guard that deref-coerces to its protected value [Section titled “Exercise 3: A guard that deref-coerces to its protected value”](#exercise-3-a-guard-that-deref-coerces-to-its-protected-value) **Difficulty:** Intermediate / Advanced **Objective:** Model the “RAII guard” shape (like `MutexGuard` or `Ref`) where a wrapper grants temporary access to an inner value via `Deref`/`DerefMut` and runs cleanup on drop. **Instructions:** Define `struct Resource { name: String, data: Vec<i32> }`. Define `struct Guard<'a>(&'a mut Resource)` that borrows it. Implement `Deref<Target = Resource>` and `DerefMut` for `Guard` so callers can read and mutate the `Resource` through the guard. Implement `Drop` for `Guard` to print `"released <name>"`. In `main`, acquire a guard, push to `data` through it (`guard.data.push(...)` works via `DerefMut`), read `data.len()`, then let the guard drop and observe the cleanup message. Solution ```rust 1 use std::ops::{Deref, DerefMut}; 2 3 struct Resource { 4 name: String, 5 data: Vec<i32>, 6 } 7 8 struct Guard<'a>(&'a mut Resource); 9 10 impl<'a> Deref for Guard<'a> { 11 type Target = Resource; 12 fn deref(&self) -> &Resource { 13 self.0 14 } 15 } 16 17 impl<'a> DerefMut for Guard<'a> { 18 fn deref_mut(&mut self) -> &mut Resource { 19 self.0 20 } 21 } 22 23 impl<'a> Drop for Guard<'a> { 24 fn drop(&mut self) { 25 println!("released {}", self.0.name); 26 } 27 } 28 29 impl Resource { 30 fn acquire(&mut self) -> Guard<'_> { 31 println!("acquired {}", self.name); 32 Guard(self) 33 } 34 } 35 36 fn main() { 37 let mut resource = Resource { 38 name: "db-pool".to_string(), 39 data: vec![1, 2], 40 }; 41 42 { 43 let mut guard = resource.acquire(); 44 // DerefMut: reach Resource.data through the guard and mutate it. 45 guard.data.push(3); 46 guard.data.push(4); 47 // Deref: read through the guard. 48 println!("len while held = {}", guard.data.len()); 49 } // guard drops here -> "released db-pool" 50 51 println!("final data = {:?}", resource.data); 52 } ``` **Output:** ```text 1 acquired db-pool 2 len while held = 4 3 released db-pool 4 final data = [1, 2, 3, 4] ``` This is the exact shape of `std::sync::MutexGuard` and `std::cell::RefMut`: a short-lived handle that `Deref`s to the protected value and cleans up in `Drop`. The lifetime `'a` ties the guard to the borrow of `Resource`, so the borrow checker guarantees the guard cannot outlive what it protects. Compare this with the guards returned by `RefCell::borrow_mut` and `Mutex::lock` in [Interior Mutability](/10-smart-pointers/02-refcell-mutex/). # Choosing a Smart Pointer: A Decision Guide > A decision table mapping each need to one Rust smart pointer. Three questions (single or shared owner, mutate through &, one thread or many) pick the type. This page is the map for the rest of Section 10. The other files each go deep on one smart pointer; this one steps back and answers the question you will actually ask on the job: **“I have this situation — which type do I reach for?”** It is built around a single decision table that maps a *need* to a *type*, plus the reasoning that gets you there. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Rust’s standard library ships a handful of **smart pointers**: types that wrap a value, own (or borrow) the heap allocation behind it, and add a behavior such as shared ownership, interior mutability, or clone-on-write. In TypeScript and JavaScript you never choose any of this: every object is a garbage-collected, freely-shared, freely-mutable reference, and the runtime sorts out lifetime and aliasing for you. Rust hands those decisions back to you, so the skill this page teaches is **diagnosis**: given “shared or single owner?”, “do I need to mutate it?”, and “across threads or not?”, you land on exactly one correct type. > **Note:** This is the decision-guide companion to the per-type deep dives. Once the table points you at a type, follow the link to its dedicated page: [`00_box.md`](/10-smart-pointers/00-box/), [`01_rc-arc.md`](/10-smart-pointers/01-rc-arc/), [`02_refcell-mutex.md`](/10-smart-pointers/02-refcell-mutex/), [`03_cell.md`](/10-smart-pointers/03-cell/), [`04_cow.md`](/10-smart-pointers/04-cow/), [`05_weak.md`](/10-smart-pointers/05-weak/), and [`06_deref-trait.md`](/10-smart-pointers/06-deref-trait/) (the trait that makes all of them feel like the value they wrap). The whole section rests on the [ownership rules](/05-ownership/01-ownership-rules/) from Section 05. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript, there is only one storage model and you never pick it. An object is a heap value reached through a reference; assignment copies the reference, not the object; any holder can mutate it; and the garbage collector decides when it dies. Sharing, mutation, and lifetime are all implicit and all free at the type level. ```typescript 1 // One model for everything. No decisions to make. 2 interface Account { 3 id: string; 4 balance: number; 5 } 6 7 const account: Account = { id: "acc-1", balance: 100 }; 8 9 // "Shared ownership": just alias the reference. Both see the same object. 10 const ledgerView = account; 11 const auditView = account; 12 13 // "Interior mutability": mutate through any alias, any time. 14 ledgerView.balance += 50; 15 16 // "Cross-thread sharing": Web Workers get a *structured clone* (a copy), 17 // not the same object — so true shared mutable state is the exception, not 18 // the default, and you reach for SharedArrayBuffer + Atomics for it. 19 20 console.log(auditView.balance); // 150 — the mutation is visible everywhere 21 console.log(account === ledgerView); // true — same underlying object ``` **Key points:** * There is exactly **one** way objects are stored and shared, so there is nothing to choose. * Sharing (`ledgerView = account`), mutation (`ledgerView.balance += 50`), and cleanup (the GC) are all implicit. * The cost is invisibility: you cannot tell from a type whether a value is uniquely owned, shared, or being mutated behind your back: exactly the information Rust forces into the open. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust makes you state your intent, and each intent maps to a specific wrapper. The same scenario (a uniquely owned value, a shared read-only value, a shared *mutable* single-threaded value, and a shared mutable *cross-thread* value) uses four different types, and the type *is* the documentation. ```rust 1 use std::cell::RefCell; 2 use std::rc::Rc; 3 use std::sync::{Arc, Mutex}; 4 use std::thread; 5 6 #[derive(Debug)] 7 struct Account { 8 id: String, 9 balance: u64, 10 } 11 12 fn main() { 13 // 1. Single owner, no sharing — just own the value (no smart pointer needed). 14 let owned = Account { id: "acc-1".into(), balance: 100 }; 15 println!("owned: {} = {}", owned.id, owned.balance); 16 17 // 2. Shared, read-only, single-threaded -> Rc<T>. 18 let shared = Rc::new(Account { id: "acc-2".into(), balance: 100 }); 19 let ledger_view = Rc::clone(&shared); // cheap: bump the count 20 println!("rc: owners={} balance={}", Rc::strong_count(&shared), ledger_view.balance); 21 22 // 3. Shared AND mutable, single-threaded -> Rc<RefCell<T>>. 23 let mutable = Rc::new(RefCell::new(Account { id: "acc-3".into(), balance: 100 })); 24 let audit_view = Rc::clone(&mutable); 25 mutable.borrow_mut().balance += 50; // interior mutability through a shared handle 26 println!("rc<refcell>: balance={}", audit_view.borrow().balance); 27 28 // 4. Shared AND mutable AND cross-thread -> Arc<Mutex<T>>. 29 let across = Arc::new(Mutex::new(Account { id: "acc-4".into(), balance: 100 })); 30 let mut handles = Vec::new(); 31 for _ in 0..4 { 32 let across = Arc::clone(&across); 33 handles.push(thread::spawn(move || { 34 across.lock().unwrap().balance += 25; 35 })); 36 } 37 for h in handles { 38 h.join().unwrap(); 39 } 40 println!("arc<mutex>: balance={}", across.lock().unwrap().balance); 41 } ``` ```text 1 owned: acc-1 = 100 2 rc: owners=2 balance=100 3 rc<refcell>: balance=150 4 arc<mutex>: balance=200 ``` Each line of intent picked a different type. That is the discipline this page systematizes. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) The four cases above are not arbitrary: they fall out of **three yes/no questions** you ask in order. Answering them mechanically lands you on the right type every time. ### Question 1: Do I need more than one owner? [Section titled “Question 1: Do I need more than one owner?”](#question-1-do-i-need-more-than-one-owner) * **No (single owner).** You usually need *nothing* — a plain owned value (`Account`, `String`, `Vec<T>`) lives on the stack or owns its own heap data and is freed when it goes out of scope. You only reach for [`Box<T>`](/10-smart-pointers/00-box/) when you need the value specifically *on the heap*: a recursive type that would otherwise be infinitely sized, a large value you want to move cheaply, or a [trait object](/09-generics-traits/06-trait-objects/) (`Box<dyn Trait>`) to store different concrete types behind one pointer. * **Yes (multiple owners).** You need a reference-counted pointer — [`Rc<T>`](/10-smart-pointers/01-rc-arc/) single-threaded, [`Arc<T>`](/10-smart-pointers/01-rc-arc/) cross-thread. Go to Question 3. ### Question 2: Do I need to mutate it through a shared/`&` handle? [Section titled “Question 2: Do I need to mutate it through a shared/& handle?”](#question-2-do-i-need-to-mutate-it-through-a-shared-handle) Rust’s borrow checker normally forbids mutation through a shared reference. **Interior mutability** types move that check from compile time to run time so you *can* mutate behind a `&`: * **[`Cell<T>`](/10-smart-pointers/03-cell/)** — for `Copy` types (numbers, `bool`, small enums). No references handed out; you `get()` a copy and `set()` a new value. Zero runtime borrow tracking, so it cannot panic. * **[`RefCell<T>`](/10-smart-pointers/02-refcell-mutex/)** — for non-`Copy` types. Hands out `Ref`/`RefMut` guards and enforces the borrow rules *at run time* (`borrow()` / `borrow_mut()`), **panicking** if you break them. Single-threaded only. * **[`Mutex<T>`](/10-smart-pointers/02-refcell-mutex/)** / `RwLock<T>` — the thread-safe equivalents. `lock()` blocks until exclusive access is available and returns a guard. ### Question 3: Does the sharing cross threads? [Section titled “Question 3: Does the sharing cross threads?”](#question-3-does-the-sharing-cross-threads) This is the single most important branch, because the compiler enforces it for you via the `Send`/`Sync` marker traits: * **Single-threaded** → `Rc<T>` and `RefCell<T>`/`Cell<T>`. Their counters and borrow flags are *not* synchronized, which makes them fast, and the compiler will refuse to send them between threads (you will see the real error in [Common Pitfalls](#common-pitfalls)). * **Cross-thread** → `Arc<T>` and `Mutex<T>`/`RwLock<T>` (or an `Atomic*` type for a single `Copy` value). `Arc` uses *atomic* count updates; `Mutex` synchronizes access. They cost a little more, so you do not pay for them unless you actually share across threads. ### Putting it together [Section titled “Putting it together”](#putting-it-together) The combinations you will write in real code are predictable: * `Rc<RefCell<T>>`: the single-threaded “shared mutable object”, the closest thing to a plain JavaScript object reference. * `Arc<Mutex<T>>`: the cross-thread version, ubiquitous in async servers (see [Section 11](/11-async/)). * `Arc<T>` alone: shared *immutable* data across threads (config, lookup tables), no lock needed. * `Weak<T>`: a non-owning handle that breaks the reference *cycles* `Rc`/`Arc` would otherwise leak (a child pointing back at its parent). Covered in [`05_weak.md`](/10-smart-pointers/05-weak/). *** ## Key Differences [Section titled “Key Differences”](#key-differences) ### The master decision table [Section titled “The master decision table”](#the-master-decision-table) This is the heart of the page. Read left to right: pin down your three answers, then read off the type. | Your need | Reach for | Why | | ------------------------------------------------------------ | ---------------------------------------------------- | -------------------------------------------------------------- | | One owner; value on the **stack** is fine | plain `T` (no wrapper) | Ownership already gives you this for free | | One owner; need it on the **heap** | [`Box<T>`](/10-smart-pointers/00-box/) | Heap allocation, single owner, fixed pointer size | | A **recursive** type (tree, linked list, AST) | [`Box<T>`](/10-smart-pointers/00-box/) | Breaks the “infinite size” cycle so the type has a known size | | Store **different concrete types** behind one type | `Box<dyn Trait>` | An owned [trait object](/09-generics-traits/06-trait-objects/) | | **Multiple owners**, read-only, single thread | [`Rc<T>`](/10-smart-pointers/01-rc-arc/) | Reference counting; `clone` is a cheap count bump | | **Multiple owners**, read-only, across threads | [`Arc<T>`](/10-smart-pointers/01-rc-arc/) | Atomic reference counting; `Send + Sync` | | Mutate a **`Copy`** value through `&self` | [`Cell<T>`](/10-smart-pointers/03-cell/) | `get`/`set` with no references, no runtime borrow tracking | | Mutate a **non-`Copy`** value through `&self`, single thread | [`RefCell<T>`](/10-smart-pointers/02-refcell-mutex/) | Runtime-checked `borrow`/`borrow_mut` (panics on violation) | | Mutate through `&self`, **across threads** | [`Mutex<T>`](/10-smart-pointers/02-refcell-mutex/) | Locking grants exclusive access; `Sync` when `T: Send` | | Across threads, **many readers / few writers** | `RwLock<T>` | Concurrent shared reads, exclusive writes | | Across threads, a **single `Copy` counter/flag** | `AtomicUsize`, `AtomicBool`, … | Lock-free; cheaper than `Mutex<u64>` for one number | | Shared **mutable object**, single thread | `Rc<RefCell<T>>` | The combo: shared ownership + interior mutability | | Shared **mutable object**, across threads | `Arc<Mutex<T>>` | The thread-safe combo; the default for async shared state | | Break a reference **cycle** (parent ↔ child) | [`Weak<T>`](/10-smart-pointers/05-weak/) | Non-owning; does not keep the target alive | | ”Borrowed *or* owned”, avoid copying on the hot path | [`Cow<'_, T>`](/10-smart-pointers/04-cow/) | Clone-on-write: allocate only when you must mutate/keep | > **Tip:** Start at the top and stop at the first row that matches. The rows are ordered cheapest-and-simplest first, which mirrors the idiomatic instinct: do not reach for `Arc<Mutex<T>>` when a plain `Vec<T>` would do. ### Decision flow in one breath [Section titled “Decision flow in one breath”](#decision-flow-in-one-breath) > 1. **More than one owner?** No → plain value or `Box`. Yes → reference counting. > 2. **Across threads?** No → `Rc` / `RefCell` / `Cell`. Yes → `Arc` / `Mutex` / `RwLock` / atomics. > 3. **Mutate through a shared handle?** No → the bare pointer. Yes → wrap the inner type in an interior-mutability cell. ### How this maps to your TypeScript mental model [Section titled “How this maps to your TypeScript mental model”](#how-this-maps-to-your-typescript-mental-model) | TypeScript/JavaScript reality | Rust equivalent and what changed | | -------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | `const b = a` aliases the same object | `Rc::clone(&a)` / `Arc::clone(&a)`: explicit, and you can read the count | | Mutate any object through any alias, any time | `RefCell`/`Mutex`: allowed but explicit; `RefCell` panics if you break the rules | | GC frees objects “eventually” | `Rc`/`Arc` free **deterministically** when the last owner drops (count hits zero) | | Web Worker `postMessage` deep-copies | `Arc` shares the *same* allocation across threads; the compiler proves it is safe | | Circular references are fine (the GC handles them) | `Rc` cycles **leak**; you break them with [`Weak<T>`](/10-smart-pointers/05-weak/) | | `string` is immutable; copies are invisible | [`Cow<'_, str>`](/10-smart-pointers/04-cow/) makes “borrowed vs freshly allocated” an explicit type | *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Reaching for `Arc<Mutex<T>>` by reflex [Section titled “Pitfall 1: Reaching for Arc\<Mutex\<T>> by reflex”](#pitfall-1-reaching-for-arcmutext-by-reflex) Coming from a world where everything is shared and mutable, it is tempting to wrap *everything* in `Arc<Mutex<T>>` “to be safe.” This is the most common over-engineering mistake. If a value has one owner, use it plainly. If it is shared but never mutated across threads, `Arc<T>` alone is enough, no lock. If it never leaves one thread, `Rc`/`RefCell` are faster. Every layer you add costs allocation, indirection, and (for `Mutex`) lock contention. > **Warning:** `Arc<Mutex<T>>` is the *last* row of the table for a reason. Earn it by answering the three questions. Do not start there. ### Pitfall 2: Using `Rc` where the data crosses threads [Section titled “Pitfall 2: Using Rc where the data crosses threads”](#pitfall-2-using-rc-where-the-data-crosses-threads) `Rc` is single-threaded on purpose, and the compiler enforces it. If you try to move an `Rc` into a spawned thread, you get a compile error, not a crash later: ```rust 1 use std::rc::Rc; 2 use std::thread; 3 4 fn main() { 5 let shared = Rc::new(5); 6 let s2 = Rc::clone(&shared); 7 thread::spawn(move || { // does not compile (error[E0277]: `Rc<i32>` cannot be sent between threads safely) 8 println!("{}", s2); 9 }); 10 } ``` The real error from `cargo build`: ```text 1 error[E0277]: `Rc<i32>` cannot be sent between threads safely 2 --> src/main.rs:7:19 3 | 4 7 | thread::spawn(move || { 5 | ------------- ^------ 6 | | | 7 | _____|_____________within this `{closure@src/main.rs:7:19: 7:26}` 8 | | | 9 | | required by a bound introduced by this call 10 8 | | println!("{}", s2); 11 9 | | }); 12 | |_____^ `Rc<i32>` cannot be sent between threads safely 13 | 14 = help: within `{closure@src/main.rs:7:19: 7:26}`, the trait `Send` is not implemented for `Rc<i32>` ``` The fix is exactly what the table says: swap `Rc` for `Arc`. The compiler turned a whole class of data-race bugs into a single, named, before-it-runs error. ### Pitfall 3: Forgetting that `RefCell` moves the check to *run time* [Section titled “Pitfall 3: Forgetting that RefCell moves the check to run time”](#pitfall-3-forgetting-that-refcell-moves-the-check-to-run-time) Choosing `RefCell` (or its multi-threaded sibling `Mutex`) does not turn off the borrow rules; it defers them. Two simultaneous `borrow_mut()`s compile fine but **panic** at run time: ```rust 1 use std::cell::RefCell; 2 3 fn main() { 4 let cell = RefCell::new(vec![1, 2, 3]); 5 let a = cell.borrow_mut(); 6 let b = cell.borrow_mut(); // second active mutable borrow 7 println!("{:?} {:?}", a, b); 8 } ``` ```text 1 thread 'main' panicked at src/main.rs:6:18: 2 already borrowed: BorrowMutError 3 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` If you want the rule enforced at *compile* time instead, you did not need interior mutability; you needed a plain `&mut`. Reach for `RefCell` only when shared structure genuinely forces the check to run time. ### Pitfall 4: Building an `Rc` cycle and leaking memory [Section titled “Pitfall 4: Building an Rc cycle and leaking memory”](#pitfall-4-building-an-rc-cycle-and-leaking-memory) `Rc`/`Arc` count *strong* owners. If two values own each other strongly (a parent owning its children, each child owning its parent), the count never reaches zero and the memory leaks, even in Rust. The fix is to make one direction a non-owning [`Weak<T>`](/10-smart-pointers/05-weak/). This is the one place where Rust’s deterministic cleanup can still let memory escape, so the decision table routes you to `Weak` the moment you see a back-pointer. ### Pitfall 5: Cloning the inner value instead of the pointer [Section titled “Pitfall 5: Cloning the inner value instead of the pointer”](#pitfall-5-cloning-the-inner-value-instead-of-the-pointer) `Rc::clone(&x)` and `x.clone()` look interchangeable, and for an `Rc` they do the same cheap count bump. But idiomatic code writes `Rc::clone(&x)` (fully-qualified) precisely so a reader can tell at a glance “this is a cheap pointer clone,” not a deep copy of the wrapped value. Clippy will not force this, but the convention keeps the cost obvious. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Default to the simplest thing that compiles.** Plain ownership first; add a wrapper only when a real requirement (sharing, heap, interior mutation, threads) forces it. Walk *down* the table, not up. * **Let the three questions drive the type, not habit.** “Multiple owners? Across threads? Mutated through `&`?” — answer those and the type is determined. * **Pair the pointer with the right inner cell.** Shared mutation is always *pointer + cell*: `Rc<RefCell<T>>` single-threaded, `Arc<Mutex<T>>` (or `Arc<RwLock<T>>`) cross-thread. You rarely use `RefCell`/`Mutex` without an `Rc`/`Arc` around them, because a value you can reach from only one place can just use `&mut`. * **Prefer an atomic to `Mutex<one number>`.** For a single shared `Copy` counter or flag across threads, `AtomicUsize`/`AtomicBool` are lock-free and clearer than `Arc<Mutex<u64>>`. * **Use `Cow` for “usually unchanged” APIs.** Functions that normally return their input untouched — escaping, normalizing, defaulting — return [`Cow<'_, str>`](/10-smart-pointers/04-cow/) to skip the allocation on the common path. * **Write `Rc::clone(&x)` / `Arc::clone(&x)` explicitly** so cheap pointer clones never read like deep copies. * **Reach for `Weak` the instant you see a cycle.** Any “child knows its parent” or graph back-edge is a `Weak`, by default. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small in-memory job registry that several worker threads share and mutate. Walking the three questions: multiple owners (every worker holds the store) → reference counting; across threads → `Arc`; mutated through a shared handle → `Mutex`. The table lands us squarely on `Arc<Mutex<HashMap<...>>>`. ```rust 1 use std::collections::HashMap; 2 use std::sync::{Arc, Mutex}; 3 use std::thread; 4 5 #[derive(Debug, Clone)] 6 struct Job { 7 id: u64, 8 title: String, 9 done: bool, 10 } 11 12 // Shared, mutable, cross-thread state -> Arc<Mutex<...>>. 13 type JobStore = Arc<Mutex<HashMap<u64, Job>>>; 14 15 fn add_job(store: &JobStore, id: u64, title: &str) { 16 let mut map = store.lock().unwrap(); 17 map.insert(id, Job { id, title: title.to_string(), done: false }); 18 } 19 20 fn complete_job(store: &JobStore, id: u64) { 21 let mut map = store.lock().unwrap(); 22 if let Some(job) = map.get_mut(&id) { 23 job.done = true; 24 } 25 } 26 27 fn main() { 28 let store: JobStore = Arc::new(Mutex::new(HashMap::new())); 29 30 add_job(&store, 1, "index documents"); 31 add_job(&store, 2, "send emails"); 32 33 // Workers share the same store via Arc clones. 34 let mut handles = Vec::new(); 35 for id in [1u64, 2] { 36 let store = Arc::clone(&store); 37 handles.push(thread::spawn(move || complete_job(&store, id))); 38 } 39 for h in handles { 40 h.join().unwrap(); 41 } 42 43 let map = store.lock().unwrap(); 44 let mut ids: Vec<&u64> = map.keys().collect(); 45 ids.sort(); 46 for id in ids { 47 let job = &map[id]; 48 println!("job {} \"{}\" done={}", job.id, job.title, job.done); 49 } 50 } ``` ```text 1 job 1 "index documents" done=true 2 job 2 "send emails" done=true ``` Note what we did **not** reach for: the `Job` values inside are plain owned structs (single owner, the map), the `id` keys are plain `u64`, and there is exactly one lock guarding the whole map. The decision guide kept the design as small as the requirements allow. This is the same shape you will see holding application state in an async web server in [Section 11](/11-async/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Smart Pointers (Chapter 15)](https://doc.rust-lang.org/book/ch15-00-smart-pointers.html): the canonical overview * [`std::boxed::Box`](https://doc.rust-lang.org/std/boxed/struct.Box.html), [`std::rc::Rc`](https://doc.rust-lang.org/std/rc/struct.Rc.html), [`std::sync::Arc`](https://doc.rust-lang.org/std/sync/struct.Arc.html) * [`std::cell`](https://doc.rust-lang.org/std/cell/index.html) — `Cell` and `RefCell`, with an excellent module-level discussion of interior mutability * [`std::sync::Mutex`](https://doc.rust-lang.org/std/sync/struct.Mutex.html), [`std::sync::RwLock`](https://doc.rust-lang.org/std/sync/struct.RwLock.html), [`std::sync::atomic`](https://doc.rust-lang.org/std/sync/atomic/index.html) * [`std::borrow::Cow`](https://doc.rust-lang.org/std/borrow/enum.Cow.html) ### Related Topics [Section titled “Related Topics”](#related-topics) * [`00_box.md`](/10-smart-pointers/00-box/) — heap allocation, recursive types, and `Box<dyn Trait>` * [`01_rc-arc.md`](/10-smart-pointers/01-rc-arc/) — shared ownership and reference counting in depth * [`02_refcell-mutex.md`](/10-smart-pointers/02-refcell-mutex/) — interior mutability, runtime borrow checks, lock guards * [`03_cell.md`](/10-smart-pointers/03-cell/) — the lightweight `Cell<T>` for `Copy` types * [`04_cow.md`](/10-smart-pointers/04-cow/) — clone-on-write and avoiding needless allocation * [`05_weak.md`](/10-smart-pointers/05-weak/) — breaking reference cycles * [`06_deref-trait.md`](/10-smart-pointers/06-deref-trait/) — why every smart pointer feels like the value it wraps * [Section 05: Ownership](/05-ownership/) — the model that makes these choices necessary * [Section 09: Generics & Traits](/09-generics-traits/) — trait objects, the partner of `Box<dyn Trait>` * [Section 11: Async](/11-async/) — where `Arc<Mutex<T>>` becomes everyday shared state *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Borrowed or owned? [Section titled “Exercise 1: Borrowed or owned?”](#exercise-1-borrowed-or-owned) **Difficulty:** Beginner **Objective:** Pick the right wrapper for a “usually unchanged” function and observe when it allocates. **Instructions:** Write `strip_comment(line: &str)` that removes a trailing `# ...` comment (and the whitespace before it) from a config line. If there is no `#`, the input is returned untouched with **no allocation**; otherwise a new trimmed string is produced. Choose the type the decision table recommends for “borrowed *or* owned”, then verify which branch each call took. ```rust 1 use std::borrow::Cow; 2 3 fn strip_comment(line: &str) -> Cow<'_, str> { 4 // TODO: borrow when there's no '#', allocate only when trimming a comment. 5 /* ??? */ 6 } 7 8 fn main() { 9 // TODO: call it with a clean line and a commented line; print which variant you got. 10 } ``` Solution ```rust 1 use std::borrow::Cow; 2 3 fn strip_comment(line: &str) -> Cow<'_, str> { 4 match line.find('#') { 5 Some(idx) => Cow::Owned(line[..idx].trim_end().to_string()), 6 None => Cow::Borrowed(line), 7 } 8 } 9 10 fn main() { 11 let a = strip_comment("value = 42"); 12 let b = strip_comment("value = 42 # the answer"); 13 println!("a={a:?} ({})", if matches!(a, Cow::Borrowed(_)) { "borrowed" } else { "owned" }); 14 println!("b={b:?} ({})", if matches!(b, Cow::Borrowed(_)) { "borrowed" } else { "owned" }); 15 } ``` Real output: ```text 1 a="value = 42" (borrowed) 2 b="value = 42" (owned) ``` The clean line is handed straight back (no allocation); only the commented line produces an owned `String`. This is the [`Cow`](/10-smart-pointers/04-cow/) row of the table in action. ### Exercise 2: A shared, mutable, single-threaded cache [Section titled “Exercise 2: A shared, mutable, single-threaded cache”](#exercise-2-a-shared-mutable-single-threaded-cache) **Difficulty:** Intermediate **Objective:** Combine the pointer and the cell the table prescribes for “shared mutable object, single thread.” **Instructions:** Build a `Cache` holding a `HashMap<String, u64>` of counts. It must be `Clone`-able so several parts of one (single-threaded) program can hold a handle to the **same** underlying map, and `bump(&self, key)` must increment and return the count *through a shared `&self`*. Answer the three questions to choose the type, then prove the clones share state by reading the owner count. Solution ```rust 1 use std::cell::RefCell; 2 use std::collections::HashMap; 3 use std::rc::Rc; 4 5 #[derive(Clone)] 6 struct Cache { 7 // Multiple owners (Rc) + mutation through &self (RefCell), single-threaded. 8 inner: Rc<RefCell<HashMap<String, u64>>>, 9 } 10 11 impl Cache { 12 fn new() -> Self { 13 Cache { inner: Rc::new(RefCell::new(HashMap::new())) } 14 } 15 16 fn bump(&self, key: &str) -> u64 { 17 let mut map = self.inner.borrow_mut(); 18 let entry = map.entry(key.to_string()).or_insert(0); 19 *entry += 1; 20 *entry 21 } 22 } 23 24 fn main() { 25 let cache = Cache::new(); 26 let alias = cache.clone(); // cheap Rc bump: same underlying map 27 cache.bump("a"); 28 alias.bump("a"); 29 let n = cache.bump("b"); 30 println!("a={}", cache.bump("a")); // 3 31 println!("b={n}"); // 1 32 println!("owners={}", Rc::strong_count(&cache.inner)); 33 } ``` Real output: ```text 1 a=3 2 b=1 3 owners=2 ``` `cache` and `alias` share one map (three bumps of `"a"` across two handles → 3), and the strong count of `2` confirms they own the same allocation. This is the `Rc<RefCell<T>>` row, the closest Rust gets to a plain JavaScript object reference. See [`02_refcell-mutex.md`](/10-smart-pointers/02-refcell-mutex/) and [`01_rc-arc.md`](/10-smart-pointers/01-rc-arc/). ### Exercise 3: Promote it to threads — and skip the lock [Section titled “Exercise 3: Promote it to threads — and skip the lock”](#exercise-3-promote-it-to-threads--and-skip-the-lock) **Difficulty:** Advanced **Objective:** Move a shared counter across threads and recognize when the table’s last rows (`Arc` + atomic) beat `Arc<Mutex<T>>`. **Instructions:** Eight threads each increment a shared counter 1000 times (expected total `8000`). The shared value is a single `Copy` integer, so instead of `Arc<Mutex<u64>>`, use the cheaper lock-free option the table recommends for “a single `Copy` counter across threads.” Share it with `Arc`, increment with the atomic’s own method, and print the final total. > **Hint:** `Arc<AtomicU64>`, then `fetch_add(1, Ordering::Relaxed)` inside each thread; read the result with `load(Ordering::Relaxed)`. Solution ```rust 1 use std::sync::atomic::{AtomicU64, Ordering}; 2 use std::sync::Arc; 3 use std::thread; 4 5 fn main() { 6 // A single Copy counter shared across threads: an atomic beats Mutex<u64>. 7 let hits = Arc::new(AtomicU64::new(0)); 8 let mut handles = Vec::new(); 9 for _ in 0..8 { 10 let hits = Arc::clone(&hits); 11 handles.push(thread::spawn(move || { 12 for _ in 0..1000 { 13 hits.fetch_add(1, Ordering::Relaxed); 14 } 15 })); 16 } 17 for h in handles { 18 h.join().unwrap(); 19 } 20 println!("hits = {}", hits.load(Ordering::Relaxed)); 21 } ``` Real output: ```text 1 hits = 8000 ``` `Arc` provides the shared ownership across threads; the `AtomicU64` provides synchronized mutation with **no lock** to acquire or release. For a single number this is both faster and clearer than `Arc<Mutex<u64>>`, which is exactly why the decision table lists atomics as their own row. See [`02_refcell-mutex.md`](/10-smart-pointers/02-refcell-mutex/) for the locking alternatives and [`01_rc-arc.md`](/10-smart-pointers/01-rc-arc/) for `Arc` itself. # Async Rust for JavaScript Developers > Map every TypeScript async habit to Rust: a Promise is eager, but a Future is lazy and runs nothing until awaited on a runtime like Tokio. In TypeScript you reach for `async`/`await` and `Promise` constantly, and the Node.js event loop runs them for you, invisibly, on a single thread. Rust has the same `async`/`await` *syntax*, but the model underneath differs in one decisive way: a Rust **`Future` is lazy**. Where a JavaScript `Promise` starts running the moment you create it, a Rust future does *nothing* until you `.await` it (or hand it to a runtime), and Rust ships **no built-in runtime**: you choose one, almost always **Tokio**. This section maps every async habit you have — `Promise.all`, `Promise.race`, async iterators, shared mutable state — onto its idiomatic, compile-verified Rust counterpart, and is careful to flag exactly where the analogy with JavaScript breaks down. *** ## What You’ll Learn [Section titled “What You’ll Learn”](#what-youll-learn) * The single most important shift: a `Promise` is **eager** (runs on creation) while a `Future` is **lazy** (runs only when awaited/polled), and why that means Rust needs an explicit runtime * How `async`/`await` syntax maps over: an `async fn` returns `impl Future`, `.await` replaces `await`, and `?` still propagates errors * Why Node’s single-threaded event loop becomes the **Tokio** runtime, and the difference between the multi-thread and current-thread schedulers * How to set up a Tokio project (`#[tokio::main]`, `features = ["full"]`); all examples compile-verified against current Tokio * That **`async fn` in traits is native and stable** (since Rust 1.75) — you only need the `async-trait` crate for `dyn Trait` (dynamic dispatch) * How `AsyncIterator` becomes the **`Stream`** trait, and how to consume one with `StreamExt`/`while let` * How `Promise.race`/`Promise.all` become `tokio::select!` / `join!` / `try_join!` * The async channel family (`mpsc`, `oneshot`, `broadcast`, `watch`) for moving data between tasks * How `tokio::spawn` relates to firing off a `Promise`, what a `JoinHandle` is, and when to use `spawn_blocking` * Concurrency vs parallelism, tasks vs OS threads, and the **`Arc<Mutex<T>>`** pattern for shared mutable state across tasks * When async is the wrong tool — CPU-bound work, the “function coloring” problem, and choosing threads instead *** ## Topics [Section titled “Topics”](#topics) | Topic | Description | | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | [Promises vs Futures](/11-async/00-promises-vs-futures/) | The key difference: eager JS `Promise` vs **lazy** Rust `Future`, which does nothing until awaited and needs a runtime. | | [Async/Await](/11-async/01-async-await/) | `async`/`await` syntax: an `async fn` returns `impl Future`, `.await`, and error handling with `?`. | | [Tokio Intro](/11-async/02-tokio-intro/) | Node’s event loop → the Tokio runtime; why Rust needs an explicit runtime; multi-thread vs current-thread schedulers. | | [Tokio Setup](/11-async/03-tokio-setup/) | Adding Tokio (`features = ["full"]`), `#[tokio::main]`, and the runtime builder. | | [Async Functions & Blocks](/11-async/04-async-functions/) | `async fn` and `async` blocks, capturing, returning futures, and lifetimes in async code. | | [Async in Traits](/11-async/05-async-trait/) | Native `async fn` in traits (stable since 1.75) and when you still need the `async-trait` crate (for `dyn`). | | [Streams](/11-async/06-streams/) | `AsyncIterator` → the `Stream` trait; consuming with `StreamExt` / `while let`. | | [select! and join!](/11-async/07-select-join/) | `Promise.race`/`Promise.all` → `tokio::select!` / `join!` / `try_join!`. | | [Channels](/11-async/08-channels/) | Async channels: `mpsc` / `oneshot` / `broadcast` / `watch`, and how they differ from `std::sync::mpsc`. | | [Spawning Tasks](/11-async/09-spawning-tasks/) | `tokio::spawn`, `JoinHandle`, tasks vs OS threads, and `spawn_blocking` for blocking work. | | [Concurrency](/11-async/10-concurrency/) | Concurrency vs parallelism, tasks vs threads, structured patterns, and cancellation. | | [Synchronization Primitives](/11-async/11-sync-primitives/) | Tokio `Mutex`/`RwLock`/`Semaphore` vs their `std` versions, and the danger of holding a lock across `.await`. | | [The Arc\<Mutex\<T>> Pattern](/11-async/12-arc-mutex-pattern/) | Sharing mutable state across tasks with `Arc<Mutex<T>>` / `Arc<RwLock<T>>`. | | [Async vs Sync](/11-async/13-async-vs-sync/) | When to use async vs threads vs blocking: CPU-bound vs IO-bound, and the “function coloring” issue. | *** ## Learning Objectives [Section titled “Learning Objectives”](#learning-objectives) By the end of this section, you will be able to: * Explain why a Rust `Future` does nothing until awaited, and contrast that with an eager JavaScript `Promise` * Set up and run a Tokio application, choosing the right scheduler and feature flags * Write `async fn`s, await them, propagate errors with `?`, and put async methods in traits without reaching for a crate unless you need `dyn` * Run work concurrently with `join!`/`try_join!`, race with `select!`, and move data between tasks over the right kind of channel * Spawn tasks, await their `JoinHandle`s, and offload blocking/CPU-bound work with `spawn_blocking` or a thread * Share mutable state safely across tasks with `Arc<Mutex<T>>`, and avoid holding a lock across an `.await` * Decide deliberately between async, threads, and plain blocking code for a given workload *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * [Section 08: Error Handling](/08-error-handling/). Async code is full of `Result` and `?`; fallible `.await`s propagate errors exactly like synchronous ones. * [Section 09: Generics & Traits](/09-generics-traits/) — a `Future` is a trait, `async fn` returns `impl Future`, and `Send`/`Sync` bounds decide what can cross task boundaries. * [Section 10: Smart Pointers](/10-smart-pointers/). Shared async state is built from `Arc` plus a `Mutex`/`RwLock`, so be comfortable with reference counting and interior mutability first. *** ## Estimated Time [Section titled “Estimated Time”](#estimated-time) * **Reading:** 6-7 hours * **Hands-on Practice:** 5-6 hours * **Exercises:** 3 hours * **Total:** 14-16 hours > **Tip:** Read in order. Start with `promises-vs-futures` and `async-await` to internalize **laziness** — the one idea that trips up every JavaScript developer — then set up Tokio before moving on to streams, `select!`/`join!`, channels, and shared state. Save `async-vs-sync` for last: once you understand the machinery, you can judge when *not* to use it. *** ## Frequently asked questions [Section titled “Frequently asked questions”](#frequently-asked-questions) ### Is a Rust `Future` the same as a Promise? [Section titled “Is a Rust Future the same as a Promise?”](#is-a-rust-future-the-same-as-a-promise) Almost. Both represent a value that arrives later, but a `Promise` starts running the moment it is created, while a `Future` is lazy and does nothing until you `.await` it or hand it to a runtime. See [Promises vs Futures](/11-async/00-promises-vs-futures/). ### Why do I need Tokio? [Section titled “Why do I need Tokio?”](#why-do-i-need-tokio) Rust ships no built-in event loop, so a future needs a runtime to poll it to completion. Tokio is the common choice, started with `#[tokio::main]`. This is the main setup difference from Node, where the loop is always running. See [Tokio Intro](/11-async/02-tokio-intro/). ### What replaces `Promise.all` and `Promise.race`? [Section titled “What replaces Promise.all and Promise.race?”](#what-replaces-promiseall-and-promiserace) `tokio::join!(a, b)` runs futures concurrently and waits for all of them, like `Promise.all`. `tokio::select!` returns as soon as the first one finishes, like `Promise.race`. See [select and join](/11-async/07-select-join/). *** **Next:** [Section 12: Modules & Packages →](/12-modules-packages/). Organizing code with modules and managing dependencies with Cargo, the equivalents of ES modules and npm. # Rust Futures vs JavaScript Promises > A JavaScript Promise is eager and runs on creation; a Rust Future is lazy until awaited. Rust ships no runtime, so you bring your own (Tokio). If you know JavaScript `Promise`s, you already understand 80% of Rust’s async model, and the remaining 20% is exactly where most TypeScript/JavaScript developers get burned. This page is about that 20%: the single most important difference is that a JavaScript **Promise is eager** (it starts doing work the moment it is created), while a Rust **`Future` is lazy** (it does *nothing at all* until you `.await` it or hand it to a runtime). *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **`Future`** is Rust’s equivalent of a JavaScript `Promise`: a value that represents an asynchronous computation that will produce a result later. The key difference is timing: a `Promise` begins executing the instant you create it, whereas a `Future` is an inert description of work that runs only when something *polls* it. On top of that, Rust ships with **no built-in async runtime**: there is no event loop hiding in the language, so you must bring your own executor (almost always [Tokio](/11-async/02-tokio-intro/)). > **Note:** This page focuses on the *concept*: eager vs lazy, and the runtime requirement. The mechanics of `async`/`await` syntax live in [Async/Await Syntax](/11-async/01-async-await/), and runtime setup lives in [Setting Up Tokio](/11-async/03-tokio-setup/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In JavaScript, calling an `async` function (or constructing a `Promise`) starts the work **immediately**. The `await` only controls when you *wait for the result*, not when the work *begins*. ```typescript 1 // TypeScript / JavaScript (Node v22) — Promises are EAGER 2 3 function makeRequest(id: number): Promise<number> { 4 console.log(` -> running request ${id}`); 5 return Promise.resolve(id * 10); 6 } 7 8 console.log("Before creating the promise"); 9 const p = makeRequest(1); // the body runs RIGHT NOW, before the next line 10 console.log("After creating the promise"); 11 12 const result = await p; // we only WAIT here; work already happened 13 console.log(`Got result: ${result}`); ``` Running this with Node v22 prints: ```plaintext 1 Before creating the promise 2 -> running request 1 3 After creating the promise 4 Got result: 10 ``` Notice the `-> running request 1` line appears **before** `After creating the promise`. The work started at creation. The same is true for the `Promise` constructor itself: the executor callback runs synchronously the moment you write `new Promise(...)`. ```typescript 1 // The executor runs immediately, even with no .then/.await 2 console.log("before new Promise"); 3 const eager = new Promise<number>((resolve) => { 4 console.log(" executor running immediately"); 5 resolve(42); 6 }); 7 console.log("after new Promise"); ``` Output (Node v22): ```plaintext 1 before new Promise 2 executor running immediately 3 after new Promise ``` *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same shape of code in Rust behaves differently: building the future runs **none** of its body. Only `.await` triggers execution. ```rust 1 // Rust — Futures are LAZY 2 3 async fn make_request(id: u32) -> u32 { 4 println!(" -> running request {id}"); 5 id * 10 6 } 7 8 #[tokio::main] 9 async fn main() { 10 println!("Before creating the future"); 11 let fut = make_request(1); // nothing printed yet — body has NOT run 12 println!("After creating the future (nothing ran yet)"); 13 14 let result = fut.await; // NOW the body runs 15 println!("Got result: {result}"); 16 } ``` Real output (Rust 1.96.0, Tokio 1.x): ```plaintext 1 Before creating the future 2 After creating the future (nothing ran yet) 3 -> running request 1 4 Got result: 10 ``` Look at the order: `-> running request 1` appears **after** `After creating the future`, the exact opposite of JavaScript. Creating `fut` produced an inert value; the body only ran at `.await`. > **Note:** `#[tokio::main]` is a macro that sets up a Tokio runtime and runs your `async fn main` on it. We use it here so the example is complete; it is covered in depth in [Setting Up Tokio](/11-async/03-tokio-setup/). Without *some* runtime, there is nothing to drive the future at all. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What `async fn` actually returns [Section titled “What async fn actually returns”](#what-async-fn-actually-returns) When you write `async fn make_request(id: u32) -> u32`, Rust does **not** create a function that returns `u32`. It creates a function that returns an anonymous type implementing the `Future` trait, conceptually `impl Future<Output = u32>`. The function body is compiled into a **state machine** that knows how to make progress one step at a time. You can see this by writing the future-returning function explicitly: ```rust 1 use std::future::Future; 2 3 fn build_task(n: u32) -> impl Future<Output = u32> { 4 // The async block evaluates to a Future; the body runs only when awaited. 5 async move { 6 println!(" computing for {n}"); 7 n + 1 8 } 9 } 10 11 #[tokio::main] 12 async fn main() { 13 let task = build_task(10); // nothing computed yet 14 println!("task built"); 15 let out = task.await; 16 println!("out = {out}"); 17 } ``` Output: ```plaintext 1 task built 2 computing for 10 3 out = 11 ``` `build_task(10)` returns a value. The `println!(" computing for {n}")` inside it does not run until `task.await`. An `async fn` is sugar for “a function whose body is an `async` block.” ### Lazy means “polled to completion” [Section titled “Lazy means “polled to completion””](#lazy-means-polled-to-completion) A `Future` is defined by one method, `poll`. The runtime calls `poll`; the future does a chunk of work and returns either `Poll::Ready(value)` (done) or `Poll::Pending` (not done yet, wake me later). Nothing happens until *someone calls `poll`*, and `.await` is the syntax that arranges for that to happen. Here is a hand-written future so you can see `poll` directly: ```rust 1 use std::future::Future; 2 use std::pin::Pin; 3 use std::task::{Context, Poll}; 4 5 // A future that is "ready" the first time it is polled. 6 struct ReadyValue(u32); 7 8 impl Future for ReadyValue { 9 type Output = u32; 10 11 fn poll(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Self::Output> { 12 println!(" poll() called"); 13 Poll::Ready(self.0) 14 } 15 } 16 17 #[tokio::main] 18 async fn main() { 19 let fut = ReadyValue(99); // constructing it does NOT call poll() 20 println!("future built, poll not called yet"); 21 let value = fut.await; // .await drives poll() for us 22 println!("value = {value}"); 23 } ``` Output: ```plaintext 1 future built, poll not called yet 2 poll() called 3 value = 99 ``` Constructing `ReadyValue(99)` does nothing. The `poll() called` line proves the body of a future only executes when an executor drives it. > **Tip:** You will almost never implement `Future` by hand. `async`/`await` generates the state machine and the `poll` implementation for you. This example exists purely to make “lazy” concrete. ### The eager/lazy difference is visible in concurrency [Section titled “The eager/lazy difference is visible in concurrency”](#the-eagerlazy-difference-is-visible-in-concurrency) Because JavaScript Promises are already running, `Promise.all([a, b])` runs `a` and `b` concurrently for free; they both started when you created them. In Rust, two futures awaited one after another run **sequentially**, because the first does not even begin until you `.await` it. To get concurrency you must combine them with something like [`join!`](/11-async/07-select-join/). ```rust 1 use std::time::Instant; 2 use tokio::time::{sleep, Duration}; 3 4 async fn fetch(id: u32, ms: u64) -> u32 { 5 sleep(Duration::from_millis(ms)).await; 6 println!(" fetched {id}"); 7 id 8 } 9 10 #[tokio::main] 11 async fn main() { 12 // Sequential: each .await waits for the previous to finish. 13 let start = Instant::now(); 14 let a = fetch(1, 100).await; 15 let b = fetch(2, 100).await; 16 println!("sequential took ~{} ms (a={a}, b={b})", start.elapsed().as_millis()); 17 18 // Concurrent: join! polls both on the same task, interleaving them. 19 let start = Instant::now(); 20 let (a, b) = tokio::join!(fetch(3, 100), fetch(4, 100)); 21 println!("join! took ~{} ms (a={a}, b={b})", start.elapsed().as_millis()); 22 } ``` Real output: ```plaintext 1 fetched 1 2 fetched 2 3 sequential took ~204 ms (a=1, b=2) 4 fetched 4 5 fetched 3 6 join! took ~102 ms (a=3, b=4) ``` The sequential version takes \~200 ms (100 + 100); `join!` takes \~100 ms because both futures make progress together. In JavaScript the result depends on when the promises are *created*: `await fetch1(); await fetch2();` takes \~200 ms just like Rust, but `const a = fetch1(); const b = fetch2(); await a; await b;` finishes in \~100 ms, because each promise eagerly starts its work the moment it is created. Rust has no such hidden head start: a future does nothing until polled. The key Rust takeaway: **awaiting in sequence is sequential, and there is no hidden concurrency.** ### There is no built-in executor [Section titled “There is no built-in executor”](#there-is-no-built-in-executor) This is the second half of the story. JavaScript has a built-in event loop (in the browser, and libuv in Node). It is always there; you never “start” it. Rust deliberately ships **no** runtime in its standard library. The `Future` trait and `async`/`await` are in `std`, but the thing that *drives* futures — the executor — is a library you choose. The most common is [Tokio](/11-async/02-tokio-intro/). But any executor works; here is the same idea using a minimal one from the `futures` crate, with no Tokio at all: ```rust 1 use futures::executor::block_on; 2 3 async fn greet(name: &str) -> String { 4 format!("Hello, {name}!") 5 } 6 7 fn main() { 8 // `block_on` is an executor: it drives the future to completion on this thread. 9 let message = block_on(greet("Rust")); 10 println!("{message}"); 11 } ``` Output: ```plaintext 1 Hello, Rust! ``` `block_on` is the executor: it repeatedly polls the future until it returns `Poll::Ready`, blocking the current thread in the meantime. The point is that *something* — `block_on`, `#[tokio::main]`, a runtime you build by hand — must call `poll`. Futures cannot run themselves. ### Building a runtime explicitly [Section titled “Building a runtime explicitly”](#building-a-runtime-explicitly) `#[tokio::main]` is convenient, but it is only a macro that expands to “build a runtime and call `block_on`.” You can do it yourself, which makes the “you supply the runtime” point unmistakable: ```rust 1 use tokio::time::{sleep, Duration}; 2 3 async fn do_work() -> &'static str { 4 sleep(Duration::from_millis(50)).await; 5 "work complete" 6 } 7 8 fn main() { 9 // The runtime is something YOU build — there is no implicit global executor. 10 let runtime = tokio::runtime::Runtime::new().expect("failed to build runtime"); 11 let result = runtime.block_on(do_work()); 12 println!("{result}"); 13 } ``` Output: ```plaintext 1 work complete ``` *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | JavaScript `Promise` | Rust `Future` | | -------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | **Execution start** | Eager: runs on creation | Lazy: runs only when `.await`ed/polled | | **What creation does** | Starts the work, returns a handle | Builds an inert state machine, runs nothing | | **Runtime / event loop** | Built in (browser / Node libuv) | None in `std`; you choose one (Tokio, `futures`, …) | | **Core mechanism** | Microtask queue managed by the engine | `poll` returning `Ready`/`Pending`, driven by an executor | | **Re-running** | Cannot re-run; a settled Promise is final | Re-buildable: a closure can produce a fresh future each call | | **Cancellation** | Hard: a started Promise keeps going | Drop an *unspawned* future and its work stops (a `tokio::spawn`ed task keeps running if you drop only its `JoinHandle` — use `.abort()`) | | **Concurrency for free** | `Promise.all` of already-running promises | None; combine with `join!`/`select!` or spawn tasks | | **Overhead of unused one** | Work already happened (wasted) | Zero — an unawaited future never ran | ### Why lazy is a feature, not a quirk [Section titled “Why lazy is a feature, not a quirk”](#why-lazy-is-a-feature-not-a-quirk) Laziness gives Rust three things JavaScript cannot offer easily: 1. **Zero-cost composition.** You can build a big tree of combined futures (`join!`, `select!`, adapters) and the work only happens when the *whole* thing is awaited. There is no partial, wasted execution. 2. **Real cancellation.** Because a future is just a value, dropping it before it finishes stops its work cleanly. A JavaScript Promise, once started, runs to completion even if nobody is listening; there is no built-in `.cancel()`. (One caveat: once you hand a future to `tokio::spawn`, the *runtime* owns it — dropping the returned `JoinHandle` detaches the task rather than cancelling it; call `handle.abort()` to cancel. See [select! and join!](/11-async/07-select-join/).) 3. **Backpressure and control.** The executor decides *when* and *how often* to poll, enabling sophisticated scheduling that an always-running model can’t express. > **Warning:** The flip side is the classic beginner trap: if you build a future and never `.await` it, **none of its code runs**. In JavaScript a “fire-and-forget” Promise still executes; in Rust it silently does nothing. The compiler warns you about this (see Pitfalls). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting `.await` — the future never runs [Section titled “Pitfall 1: Forgetting .await — the future never runs”](#pitfall-1-forgetting-await--the-future-never-runs) This is the number one mistake for JavaScript developers. In JavaScript, dropping the `await` still runs the work (you just don’t wait for it). In Rust, dropping `.await` means the work **never happens**. ```rust 1 async fn save_to_db(name: &str) { 2 println!("saving {name}"); 3 } 4 5 #[tokio::main] 6 async fn main() { 7 save_to_db("Alice"); // forgot .await — body never runs 8 println!("done"); 9 } ``` The compiler catches this with a warning (it does not stop compilation, so watch for it): ```plaintext 1 warning: unused implementer of `Future` that must be used 2 --> src/main.rs:7:5 3 | 4 7 | save_to_db("Alice"); // forgot .await — body never runs 5 | ^^^^^^^^^^^^^^^^^^^ 6 | 7 = note: futures do nothing unless you `.await` or poll them 8 = note: `#[warn(unused_must_use)]` on by default ``` The note — *“futures do nothing unless you `.await` or poll them”* — is the lazy model spelled out. The fix is to add `.await` (or [spawn a task](/11-async/09-spawning-tasks/) if you genuinely want fire-and-forget): ```rust 1 async fn save_to_db(name: &str) { 2 println!("saving {name}"); 3 } 4 5 #[tokio::main] 6 async fn main() { 7 save_to_db("Alice").await; // now the body runs 8 println!("done"); 9 } ``` `cargo clippy` reports the same thing, so a linted CI will not let this slip through: ```plaintext 1 warning: unused implementer of `std::future::Future` that must be used 2 --> src/main.rs:7:5 3 | 4 7 | save_to_db("Alice"); // forgot .await — body never runs 5 | ^^^^^^^^^^^^^^^^^^^ 6 | 7 = note: futures do nothing unless you `.await` or poll them 8 = note: `#[warn(unused_must_use)]` on by default ``` ### Pitfall 2: Using `.await` outside an async context [Section titled “Pitfall 2: Using .await outside an async context”](#pitfall-2-using-await-outside-an-async-context) You can only `.await` inside an `async fn` or `async` block. Trying to await in a plain `fn` (including a non-async `main`) is a hard error. ```rust 1 async fn fetch() -> u32 { 2 42 3 } 4 5 fn main() { 6 let x = fetch().await; // does not compile (error[E0728]) 7 println!("{x}"); 8 } ``` Real compiler error: ```plaintext 1 error[E0728]: `await` is only allowed inside `async` functions and blocks 2 --> src/main.rs:6:21 3 | 4 5 | fn main() { 5 | --------- this is not `async` 6 6 | let x = fetch().await; // await outside async 7 | ^^^^^ only allowed inside `async` functions and blocks ``` The fix is to enter an async context: add `#[tokio::main]` to make `main` async, or drive the future with an executor like `runtime.block_on(...)` / `futures::executor::block_on(...)` as shown earlier. ### Pitfall 3: Expecting work to start before `.await` [Section titled “Pitfall 3: Expecting work to start before .await”](#pitfall-3-expecting-work-to-start-before-await) Because of eager Promises, JavaScript developers often write code assuming a “kick off now, await later” pattern: ```rust 1 use tokio::time::{sleep, Duration}; 2 3 async fn slow(label: &str) -> &str { 4 sleep(Duration::from_millis(100)).await; 5 label 6 } 7 8 #[tokio::main] 9 async fn main() { 10 // This does NOT start both timers — `b` hasn't begun yet. 11 let a = slow("a"); 12 let b = slow("b"); 13 // Total wait is ~200 ms, not ~100 ms: 14 let (ra, rb) = (a.await, b.await); 15 println!("{ra} {rb}"); 16 } ``` The two `slow(...)` calls just build futures; neither timer starts. By the time you `a.await`, only `a` is running; `b` doesn’t begin until `a` finishes. If you wanted them concurrent, use [`tokio::join!`](/11-async/07-select-join/) or [spawn tasks](/11-async/09-spawning-tasks/). This compiles and runs fine. It’s a *correctness/performance* trap, not a compile error, which makes it especially sneaky. ### Pitfall 4: Thinking there’s a default runtime [Section titled “Pitfall 4: Thinking there’s a default runtime”](#pitfall-4-thinking-theres-a-default-runtime) Coming from Node, it is tempting to assume “async just works.” It does not: without a runtime, `.await` has nothing to drive it. Calling `block_on` from inside an already-running Tokio runtime, or forgetting the runtime entirely, leads to panics or the “await outside async” error from Pitfall 2. The mental model to internalize: **`async`/`await` is syntax; the runtime is a dependency you add.** See [Setting Up Tokio](/11-async/03-tokio-setup/). *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Always `.await` (or deliberately spawn).** Treat the “unused `Future`” warning as an error in CI. If you truly want background work, use [`tokio::spawn`](/11-async/09-spawning-tasks/); that is the explicit, intentional way to “fire and forget.” * **Reach for combinators to recover JavaScript-style concurrency.** Use [`join!`/`try_join!`](/11-async/07-select-join/) for the `Promise.all` pattern and [`select!`](/11-async/07-select-join/) for `Promise.race`. Don’t fake concurrency with sequential `.await`s. * **Let `async fn` write the `Future` for you.** Return `impl Future<Output = T>` only when you need to (e.g., conditionally choosing between futures); otherwise just write `async fn`. Never hand-implement the `Future` trait unless you are writing a low-level primitive. * **Pick one runtime and stick to it.** Mixing executors (e.g., `futures::executor::block_on` inside a Tokio task) causes confusing behavior. For applications, standardize on Tokio; see [The Tokio Runtime](/11-async/02-tokio-intro/). * **Exploit laziness for retries and timeouts.** Because a future is a re-buildable value, a closure `|| do_work()` can produce a fresh future on each attempt, impossible with an already-settled Promise. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A retry helper shows why laziness is a genuine advantage. In JavaScript, once you call an `async` function you get a `Promise` that is already running and can only be awaited once. Retrying means *calling the function again*. Rust makes this explicit and clean: you pass a closure that builds a **fresh future** for each attempt. ```rust 1 use std::future::Future; 2 use tokio::time::{sleep, Duration}; 3 4 /// Runs an async operation, retrying up to `max_attempts` times. 5 /// `op` is a closure that builds a FRESH future each call — possible only 6 /// because Rust futures are lazy and can be created on demand. 7 async fn with_retry<F, Fut, T, E>(max_attempts: u32, mut op: F) -> Result<T, E> 8 where 9 F: FnMut() -> Fut, 10 Fut: Future<Output = Result<T, E>>, 11 { 12 let mut attempt = 1; 13 loop { 14 match op().await { 15 Ok(value) => return Ok(value), 16 Err(_) if attempt < max_attempts => { 17 println!(" attempt {attempt} failed, retrying..."); 18 attempt += 1; 19 sleep(Duration::from_millis(20)).await; 20 } 21 Err(err) => return Err(err), 22 } 23 } 24 } 25 26 // A flaky "API call" that succeeds on the 3rd try. 27 async fn flaky_fetch(counter: &std::cell::Cell<u32>) -> Result<String, String> { 28 let n = counter.get() + 1; 29 counter.set(n); 30 if n < 3 { 31 Err(format!("network error (call {n})")) 32 } else { 33 Ok(format!("payload from call {n}")) 34 } 35 } 36 37 #[tokio::main] 38 async fn main() { 39 let counter = std::cell::Cell::new(0); 40 let result = with_retry(5, || flaky_fetch(&counter)).await; 41 match result { 42 Ok(body) => println!("success: {body}"), 43 Err(e) => println!("gave up: {e}"), 44 } 45 } ``` Real output: ```plaintext 1 attempt 1 failed, retrying... 2 attempt 2 failed, retrying... 3 success: payload from call 3 ``` Each call to `op()` builds a brand-new future; `with_retry` polls it to completion via `.await`, and on failure simply builds the next one. Because the future is lazy and re-buildable, the retry logic is just an ordinary loop: no `Promise` juggling, no double-execution. > **Note:** Error handling here uses `Result<T, E>` rather than thrown exceptions. The `?` operator integrates with `.await` to make this ergonomic; that is covered in [Async/Await Syntax](/11-async/01-async-await/) and builds on [Section 08: Error Handling](/08-error-handling/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Futures and the Async Syntax](https://doc.rust-lang.org/book/ch17-01-futures-and-syntax.html) * [`std::future::Future`](https://doc.rust-lang.org/std/future/trait.Future.html) — the trait at the heart of all this * [Asynchronous Programming in Rust (the “async book”)](https://rust-lang.github.io/async-book/) — especially the chapter on why futures are lazy * [Tokio Tutorial](https://tokio.rs/tokio/tutorial) — the de facto runtime ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Async/Await Syntax](/11-async/01-async-await/) — the `async`/`await` syntax, `?` error handling * [The Tokio Runtime](/11-async/02-tokio-intro/) — why Rust needs an explicit runtime; Node’s event loop compared * [Setting Up Tokio](/11-async/03-tokio-setup/) — adding Tokio, `#[tokio::main]`, the runtime builder * [Async Functions and Async Blocks](/11-async/04-async-functions/) — `async` blocks, capturing, returning futures * [Concurrent Awaiting](/11-async/07-select-join/) — `Promise.all`/`Promise.race` → `join!`/`select!` * [Spawning Tasks](/11-async/09-spawning-tasks/) — `tokio::spawn` for intentional fire-and-forget * [Async vs Sync](/11-async/13-async-vs-sync/) — when async is the right tool at all * [Section 00: Introduction](/00-introduction/) and [Section 01: Getting Started](/01-getting-started/) — setting up Rust * [Section 02: Basics](/02-basics/) — variables, types, the fundamentals these examples assume * [Section 12: Modules & Packages](/12-modules-packages/) — how `tokio`/`futures` crates are added and imported *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Make the work actually happen [Section titled “Exercise 1: Make the work actually happen”](#exercise-1-make-the-work-actually-happen) **Difficulty:** Beginner **Objective:** Internalize that a future does nothing until `.await`ed. **Instructions:** The program below compiles with a warning and prints only `done`. Fix it so it also logs the event. Do not change the body of `log_event`. ```rust 1 use tokio::time::{sleep, Duration}; 2 3 async fn log_event(name: &str) { 4 sleep(Duration::from_millis(10)).await; 5 println!("logged: {name}"); 6 } 7 8 #[tokio::main] 9 async fn main() { 10 log_event("startup"); // TODO: why doesn't this print anything? 11 println!("done"); 12 } ``` Solution The future returned by `log_event(...)` is never polled, so its body never runs. Add `.await`: ```rust 1 use tokio::time::{sleep, Duration}; 2 3 async fn log_event(name: &str) { 4 sleep(Duration::from_millis(10)).await; 5 println!("logged: {name}"); 6 } 7 8 #[tokio::main] 9 async fn main() { 10 log_event("startup").await; // the fix: add .await 11 println!("done"); 12 } ``` Output: ```plaintext 1 logged: startup 2 done ``` ### Exercise 2: From sequential to concurrent [Section titled “Exercise 2: From sequential to concurrent”](#exercise-2-from-sequential-to-concurrent) **Difficulty:** Intermediate **Objective:** See that two futures only run concurrently when you combine them; building them is not enough. **Instructions:** This program fetches two prices sequentially, taking \~160 ms. Rewrite it so both fetches run concurrently and the total wait is \~80 ms. Keep both results. ```rust 1 use std::time::Instant; 2 use tokio::time::{sleep, Duration}; 3 4 async fn fetch_price(symbol: &str, ms: u64) -> f64 { 5 sleep(Duration::from_millis(ms)).await; 6 println!("got price for {symbol}"); 7 100.0 8 } 9 10 #[tokio::main] 11 async fn main() { 12 let start = Instant::now(); 13 let apple = fetch_price("AAPL", 80).await; // TODO: make these 14 let google = fetch_price("GOOG", 80).await; // TODO: concurrent 15 println!( 16 "total {:.1} in ~{} ms", 17 apple + google, 18 start.elapsed().as_millis() 19 ); 20 } ``` Solution Build both futures and drive them together with `tokio::join!`. (Awaiting them one at a time is sequential precisely because the second future hasn’t started yet.) ```rust 1 use std::time::Instant; 2 use tokio::time::{sleep, Duration}; 3 4 async fn fetch_price(symbol: &str, ms: u64) -> f64 { 5 sleep(Duration::from_millis(ms)).await; 6 println!("got price for {symbol}"); 7 100.0 8 } 9 10 #[tokio::main] 11 async fn main() { 12 let start = Instant::now(); 13 // Concurrent: build both futures, then join! drives them together. 14 let (apple, google) = tokio::join!( 15 fetch_price("AAPL", 80), 16 fetch_price("GOOG", 80), 17 ); 18 println!( 19 "total {:.1} in ~{} ms", 20 apple + google, 21 start.elapsed().as_millis() 22 ); 23 } ``` Output (the two “got price” lines may appear in either order): ```plaintext 1 got price for GOOG 2 got price for AAPL 3 total 200.0 in ~82 ms ``` `join!` is the `Promise.all` analogue; see [Concurrent Awaiting](/11-async/07-select-join/). ### Exercise 3: Implement `Future` by hand [Section titled “Exercise 3: Implement Future by hand”](#exercise-3-implement-future-by-hand) **Difficulty:** Advanced **Objective:** Prove to yourself that “lazy” means “polled,” by writing a `Future` whose `poll` you control. **Instructions:** Implement a `PendingOnce` future that returns `Poll::Pending` the first time it is polled and `Poll::Ready("ready now")` the second time. Remember to wake the task before returning `Pending`, or the executor will never poll you again. Await it from `main` and print the result. ```rust 1 use std::future::Future; 2 use std::pin::Pin; 3 use std::task::{Context, Poll}; 4 5 struct PendingOnce { 6 polled_before: bool, 7 } 8 9 impl Future for PendingOnce { 10 type Output = &'static str; 11 12 fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> { 13 // TODO: Pending first, Ready second; wake before returning Pending. 14 todo!() 15 } 16 } 17 18 #[tokio::main] 19 async fn main() { 20 let result = PendingOnce { polled_before: false }.await; 21 println!("{result}"); 22 } ``` Solution ```rust 1 use std::future::Future; 2 use std::pin::Pin; 3 use std::task::{Context, Poll}; 4 5 // Returns Pending the first poll, Ready the second. Demonstrates the poll loop. 6 struct PendingOnce { 7 polled_before: bool, 8 } 9 10 impl Future for PendingOnce { 11 type Output = &'static str; 12 13 fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> { 14 if self.polled_before { 15 Poll::Ready("ready now") 16 } else { 17 self.polled_before = true; 18 cx.waker().wake_by_ref(); // ask the executor to poll us again 19 Poll::Pending 20 } 21 } 22 } 23 24 #[tokio::main] 25 async fn main() { 26 let result = PendingOnce { polled_before: false }.await; 27 println!("{result}"); 28 } ``` Output: ```plaintext 1 ready now ``` The `cx.waker().wake_by_ref()` call is essential: returning `Poll::Pending` tells the runtime “not done,” and the waker is how you signal “poll me again.” Without it, the task would sleep forever. This is the machinery `async`/`await` generates for you automatically, which is why you should almost never write it by hand. # Rust async/await vs JavaScript > Rust's async/await mirrors JavaScript's, but .await is postfix, an async fn returns a lazy Future that runs nothing until awaited, and ? Rust borrowed the `async`/`await` keywords from the same family of languages that gave them to JavaScript, so the surface syntax will feel familiar. The semantics underneath are different in one decisive way: an `async fn` in Rust does not start running when you call it. It hands you a **lazy value** (a `Future`) that does nothing until you `.await` it. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In Rust you mark a function `async`, and inside it you write `some_future.await` (a postfix keyword, not a `await some_future` prefix). An `async fn` is not a normal function that returns its result. It is sugar for a function that returns an anonymous type implementing the `Future` trait. The `?` operator works inside `async fn` exactly as it does in synchronous code, propagating errors out of the future. This page is about the **syntax and mechanics** of `async`/`await`; the deeper “why are futures lazy and what is a runtime” story lives in [Promises vs Futures](/11-async/00-promises-vs-futures/) and [Tokio Intro](/11-async/02-tokio-intro/). > **Note:** Every runnable Rust snippet on this page was compiled and executed with `rustc`/`cargo` 1.96.0 (the recorded verification toolchain; 2024 edition). The async examples use the `tokio` runtime (`tokio = { version = "1.52", features = ["full"] }`) because Rust ships **no built-in executor** (see [Tokio Setup](/11-async/03-tokio-setup/)). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript, `async`/`await` is a thin layer over Promises. An `async function` always returns a `Promise<T>`, and `await` suspends the surrounding async function until that Promise settles. Critically, the work **starts the moment you call the function**, even if you never `await` the returned Promise. ```typescript 1 // Each async function returns a Promise<T>. 2 async function fetchUser(id: number): Promise<string> { 3 // Simulate a network round-trip. 4 await new Promise((resolve) => setTimeout(resolve, 50)); 5 return `user-${id}`; 6 } 7 8 async function greet(id: number): Promise<string> { 9 // `await` unwraps the resolved value of the Promise. 10 const name = await fetchUser(id); 11 return `Hello, ${name}!`; 12 } 13 14 // Error propagation: a thrown error rejects the Promise; `await` re-throws it. 15 async function fetchScore(id: number): Promise<number> { 16 const body = await fetchUser(id); // "user-3" 17 const score = Number.parseInt(body.replace("user-", ""), 10); 18 if (Number.isNaN(score)) { 19 throw new Error("bad score"); 20 } 21 return score * 2; 22 } 23 24 const msg = await greet(7); 25 console.log(msg); // Hello, user-7! 26 27 // EAGER: calling fetchUser starts the timer immediately, even unawaited. 28 fetchUser(99); // the setTimeout is already ticking ``` Two things to fix firmly in mind before the Rust version: * `await` is a **prefix** operator in JavaScript: `await expr`. * Calling `fetchUser(99)` **eagerly** kicks off the work; the returned Promise is “hot” whether or not you await it. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same shape in Rust. Note the **postfix** `.await`, the `async fn`, and that the work only happens at the `.await` point. ```rust 1 use std::time::Duration; 2 use tokio::time::sleep; 3 4 // An `async fn` returns an `impl Future`; calling it does NOTHING yet. 5 async fn fetch_user(id: u32) -> String { 6 // Simulate a network round-trip without an external server. 7 sleep(Duration::from_millis(50)).await; 8 format!("user-{id}") 9 } 10 11 async fn greet(id: u32) -> String { 12 // `.await` drives the future to completion and unwraps its output. 13 let name = fetch_user(id).await; 14 format!("Hello, {name}!") 15 } 16 17 #[tokio::main] 18 async fn main() { 19 let msg = greet(7).await; 20 println!("{msg}"); 21 } ``` Real output: ```text 1 Hello, user-7! ``` The `#[tokio::main]` attribute sets up the runtime that actually polls these futures (covered in [Tokio Setup](/11-async/03-tokio-setup/)). Without a runtime, none of this code would run: there is nothing in the language itself that drives a future forward. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `await` is postfix, and that is on purpose [Section titled “await is postfix, and that is on purpose”](#await-is-postfix-and-that-is-on-purpose) In JavaScript you write `await foo()`. In Rust you write `foo().await`. The postfix form chains cleanly with the `?` operator and method calls: ```rust 1 // Rust: reads left-to-right, like a pipeline. 2 // let body = fetch().await?.text().await?; 3 4 // The JavaScript prefix form forces awkward parentheses for the same chain: 5 // const body = await (await fetch()).text(); ``` > **Tip:** Read `x.await` as “wait for `x`, then give me its value.” It is a real keyword, not a field access — `x.await` is special syntax, even though it looks like reading a field named `await`. ### `async fn` returns `impl Future`, not the value [Section titled “async fn returns impl Future, not the value”](#async-fn-returns-impl-future-not-the-value) This is the heart of the matter. When you write: ```rust 1 async fn double_async(n: u64) -> u64 { 2 n * 2 3 } ``` the compiler rewrites it to roughly: ```rust 1 use std::future::Future; 2 3 fn double_desugared(n: u64) -> impl Future<Output = u64> { 4 // An `async` block is itself a value of an anonymous Future type. 5 async move { n * 2 } 6 } ``` Both are equivalent and both compile. Awaiting either gives `42`: ```rust 1 use std::future::Future; 2 3 async fn double_async(n: u64) -> u64 { 4 n * 2 5 } 6 7 fn double_desugared(n: u64) -> impl Future<Output = u64> { 8 async move { n * 2 } 9 } 10 11 #[tokio::main] 12 async fn main() { 13 println!("{}", double_async(21).await); 14 println!("{}", double_desugared(21).await); 15 16 // An async block can be stored in a variable and awaited later. 17 let lazy = async { 10 + 5 }; 18 println!("{}", lazy.await); 19 } ``` Real output: ```text 1 42 2 42 3 15 ``` The declared return type of an `async fn` is its **`Output`**, not its actual return type. `async fn double_async(n: u64) -> u64` really returns `impl Future<Output = u64>`. The `-> u64` describes what you get *after* awaiting. (`async` blocks and returning futures are explored further in [Async Functions](/11-async/04-async-functions/).) > **Note:** Because the returned type is an anonymous, compiler-generated state machine, you write `impl Future<Output = T>` rather than naming it. There is no `Future<u64>` you can spell directly the way you write `Promise<number>` in TypeScript. ### Futures are lazy — calling does not run [Section titled “Futures are lazy — calling does not run”](#futures-are-lazy--calling-does-not-run) In JavaScript, `fetchUser(99)` starts immediately. In Rust, building a future runs **none** of its body. The body only advances when a runtime polls it, which happens because you `.await` it (or hand it to `tokio::spawn`). If you call an `async fn` and ignore the result, the compiler warns you that nothing happened: ```rust 1 use std::time::Duration; 2 use tokio::time::sleep; 3 4 async fn fetch_user(id: u32) -> String { 5 sleep(Duration::from_millis(10)).await; 6 format!("user-{id}") 7 } 8 9 #[tokio::main] 10 async fn main() { 11 // Forgetting `.await`: the future is created but never driven. 12 let _fut = fetch_user(1); 13 fetch_user(2); 14 println!("done"); 15 } ``` Real compiler warning: ```text 1 warning: unused implementer of `Future` that must be used 2 --> src/main.rs:13:5 3 | 4 13 | fetch_user(2); 5 | ^^^^^^^^^^^^^ 6 | 7 = note: futures do nothing unless you `.await` or poll them 8 = note: `#[warn(unused_must_use)]` on by default ``` That phrase, “futures do nothing unless you `.await` or poll them,” is the single most important sentence on this page. It is the exact opposite of a JavaScript Promise. The full eager-vs-lazy contrast is in [Promises vs Futures](/11-async/00-promises-vs-futures/). ### Sequential `.await` runs one after another [Section titled “Sequential .await runs one after another”](#sequential-await-runs-one-after-another) Two `.await`s in a row behave like `await a; await b` in JavaScript: the second future does not begin until the first resolves. The total time is roughly the **sum**: ```rust 1 use std::time::{Duration, Instant}; 2 use tokio::time::sleep; 3 4 async fn step(label: &str, ms: u64) -> &str { 5 sleep(Duration::from_millis(ms)).await; 6 label 7 } 8 9 #[tokio::main] 10 async fn main() { 11 let start = Instant::now(); 12 // Two sequential `.await`s: the second does not begin until the first 13 // resolves. Total time is roughly the SUM (~150ms), like `await a; await b`. 14 let a = step("a", 75).await; 15 let b = step("b", 75).await; 16 println!("got {a} then {b} in ~{}ms", start.elapsed().as_millis()); 17 } ``` Real output (timing varies slightly): ```text 1 got a then b in ~150ms ``` To run them **concurrently** (the equivalent of `Promise.all([a, b])`, \~75ms total), you reach for `tokio::join!` or `select!`; see [Select & Join](/11-async/07-select-join/). This page deliberately keeps to sequential awaiting; concurrency is its own topic. ### Error handling with `?` inside `async fn` [Section titled “Error handling with ? inside async fn”](#error-handling-with--inside-async-fn) The `?` operator works inside an `async fn` the same way it works in any function: if the value is `Err`, the future short-circuits and resolves to that `Err`. You typically `.await` first to get a `Result`, then apply `?`: ```rust 1 use std::num::ParseIntError; 2 use std::time::Duration; 3 use tokio::time::sleep; 4 5 // Simulates an async I/O fetch that yields a raw string body. 6 async fn fetch_body(id: u32) -> String { 7 sleep(Duration::from_millis(10)).await; 8 if id == 0 { "not-a-number".to_string() } else { (id * 100).to_string() } 9 } 10 11 // `?` works inside `async fn` exactly like in a sync fn: it short-circuits 12 // on `Err` and returns it from the future's output type. 13 async fn fetch_score(id: u32) -> Result<u32, ParseIntError> { 14 let body = fetch_body(id).await; // .await first ... 15 let score: u32 = body.parse()?; // ... then `?` on the Result 16 Ok(score * 2) 17 } 18 19 #[tokio::main] 20 async fn main() { 21 match fetch_score(3).await { 22 Ok(score) => println!("score = {score}"), 23 Err(e) => println!("error: {e}"), 24 } 25 match fetch_score(0).await { 26 Ok(score) => println!("score = {score}"), 27 Err(e) => println!("error: {e}"), 28 } 29 } ``` Real output: ```text 1 score = 600 2 error: invalid digit found in string ``` The `Output` of `fetch_score` is `Result<u32, ParseIntError>`. The `?` returns early *from the future*, resolving it to the `Err`. The mental model is: an `async fn -> Result<T, E>` is “a future that resolves to a `Result`.” Everything you know about `?`, `From`-based error conversion, and `Result` from [The `?` Operator](/08-error-handling/01-question-mark/) carries over unchanged. The only new wrinkle is remembering to `.await` before you `?` on something that is itself a future. > **Tip:** The order matters: `fetch().await?` means “await the future, then `?` the `Result` it produced.” Writing `fetch()?.await` is usually wrong: a bare future is not a `Result`, so there is nothing for `?` to act on. ### `?` in `async fn main` [Section titled “? in async fn main”](#-in-async-fn-main) Just like a synchronous `fn main`, an async `main` can return a `Result` so `?` works at the top level. `#[tokio::main] async fn main() -> Result<(), E>` is valid: ```rust 1 async fn load() -> Result<u32, std::num::ParseIntError> { 2 "42".parse() 3 } 4 5 #[tokio::main] 6 async fn main() -> Result<(), Box<dyn std::error::Error>> { 7 let n = load().await?; // `?` is fine: main returns a Result 8 println!("loaded {n}"); 9 Ok(()) 10 } ``` *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | TypeScript/JavaScript | Rust | | ------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------- | | `await` position | Prefix: `await expr` | Postfix: `expr.await` | | What `async fn` returns | `Promise<T>` (a concrete, awaitable object) | `impl Future<Output = T>` (an anonymous lazy type) | | When work starts | **Eagerly**, on call | **Lazily**, only when polled/`.await`ed | | Needs a runtime? | No; the JS engine has a built-in event loop | Yes; you choose one (Tokio), none is built in | | Error propagation | `throw` / `try`/`catch`; `await` re-throws | `Result<T, E>` + `?`; no exceptions | | Cancellation | Hard; a started Promise generally runs to completion | Dropping a future cancels it (it just stops being polled) | | Multiple awaits in series | `await a; await b` runs sequentially | `a.await; b.await` runs sequentially (same) | | Concurrency primitive | `Promise.all` / `Promise.race` | `tokio::join!` / `tokio::select!` (see [Select & Join](/11-async/07-select-join/)) | The deepest divergence is the runtime + laziness pair. In Node, the event loop is always there and Promises are hot. In Rust, you opt into a runtime and futures are cold until driven. Treat that as the load-bearing difference; most async bugs that trip up TypeScript developers trace back to it. > **Warning:** Do not describe Rust futures as “eager Promises with different syntax.” They are the **opposite** — lazy, and inert without an executor. Internalizing this prevents a whole class of “why didn’t my code run?” surprises. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting `.await` and using the future as its value [Section titled “Pitfall 1: Forgetting .await and using the future as its value”](#pitfall-1-forgetting-await-and-using-the-future-as-its-value) A TypeScript habit is to treat the return of an async call as the value. In Rust that is a future, not the value, so you get a type error: ```rust 1 async fn fetch_user(id: u32) -> String { 2 format!("user-{id}") 3 } 4 5 #[tokio::main] 6 async fn main() { 7 // does not compile (error[E0308]): using the future as if it were a String. 8 let name: String = fetch_user(1); 9 println!("{}", name.len()); 10 } ``` Real compiler error: ```text 1 error[E0308]: mismatched types 2 --> src/main.rs:8:24 3 | 4 8 | let name: String = fetch_user(1); 5 | ------ ^^^^^^^^^^^^^ expected `String`, found future 6 | | 7 | expected due to this 8 | 9 note: calling an async function returns a future 10 --> src/main.rs:8:24 11 | 12 8 | let name: String = fetch_user(1); 13 | ^^^^^^^^^^^^^ 14 help: consider `await`ing on the `Future` 15 | 16 8 | let name: String = fetch_user(1).await; 17 | ++++++ ``` The fix is exactly what the compiler suggests: add `.await`. (When you ignore the future entirely instead of binding it, you get the `must_use` warning shown earlier rather than a hard error.) ### Pitfall 2: Trying to `.await` outside an async context [Section titled “Pitfall 2: Trying to .await outside an async context”](#pitfall-2-trying-to-await-outside-an-async-context) `.await` is only legal inside an `async fn` or `async` block. A plain synchronous function cannot await: ```rust 1 async fn load() -> Result<u32, std::num::ParseIntError> { 2 "42".parse() 3 } 4 5 // does not compile (error[E0728]): a non-async fn cannot use `.await`. 6 fn helper() { 7 let _ = load().await; 8 } 9 10 fn main() { 11 helper(); 12 } ``` Real compiler error: ```text 1 error[E0728]: `await` is only allowed inside `async` functions and blocks 2 --> src/main.rs:7:20 3 | 4 6 | fn helper() { 5 | ----------- this is not `async` 6 7 | let _ = load().await; 7 | ^^^^^ only allowed inside `async` functions and blocks ``` Fixes: make `helper` itself `async`, or if you must call async code from synchronous code, enter the runtime explicitly with something like `Runtime::block_on` (see [Tokio Setup](/11-async/03-tokio-setup/)). You cannot simply “await from anywhere,” which is the **function coloring** problem also present in JavaScript, discussed in [Concurrency vs Parallelism](/11-async/10-concurrency/). ### Pitfall 3: Expecting the body to run on call [Section titled “Pitfall 3: Expecting the body to run on call”](#pitfall-3-expecting-the-body-to-run-on-call) ```typescript 1 // JavaScript: this logs "side effect!" immediately, even unawaited. 2 async function doWork() { 3 console.log("side effect!"); 4 } 5 doWork(); ``` ```rust 1 async fn do_work() { 2 println!("side effect!"); // does NOT print on call 3 } 4 5 #[tokio::main] 6 async fn main() { 7 do_work(); // builds a future, runs nothing (and warns must_use) 8 do_work().await; // NOW "side effect!" prints 9 } ``` If you ported the JavaScript expecting the first call to print, you would be surprised by silence. Always `.await` (or `spawn`) the future. ### Pitfall 4: `?` before `.await` [Section titled “Pitfall 4: ? before .await”](#pitfall-4--before-await) ```rust 1 // Wrong shape: a future is not a Result, so `?` has nothing to operate on. 2 // let n = load()?.await; // type error 3 4 // Right shape: await first, then propagate the Result. 5 // let n = load().await?; // ``` Remember the pipeline order: `.await` turns the future into its `Output`; only then does `?` act on that `Output` (which must be a `Result` or `Option`). *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Await at the edges, pass futures sparingly [Section titled “Await at the edges, pass futures sparingly”](#await-at-the-edges-pass-futures-sparingly) Prefer writing straightforward `let x = thing().await?;` sequences. Only return `impl Future` from a synchronous function when you have a concrete reason (e.g., building combinators). For ordinary code, `async fn` reads best. ### Use `?` for propagation, reserve `match` for handling [Section titled “Use ? for propagation, reserve match for handling”](#use--for-propagation-reserve-match-for-handling) Inside async functions, lean on `?` the same way you do in sync code. Only `match`/`if let` on a `Result` where you actually handle the error (logging, fallback, returning a different value). This keeps the happy path linear and readable. ### Keep the runtime at the top [Section titled “Keep the runtime at the top”](#keep-the-runtime-at-the-top) Put `#[tokio::main]` on `main` (or construct the runtime once at startup) and let `async fn`s call each other freely below it. Avoid sprinkling `block_on` deep in your code; that re-enters the runtime and is a common source of “Cannot start a runtime from within a runtime” panics. ### Name your error type, then `?` everything [Section titled “Name your error type, then ? everything”](#name-your-error-type-then--everything) Define one error type for a module (often with `thiserror`) so that `?` can convert each underlying error via `From`. This is identical to the synchronous pattern in [Multiple Error Types](/08-error-handling/07-multiple-errors/); async changes nothing about it. ### Do not block inside async [Section titled “Do not block inside async”](#do-not-block-inside-async) Calling synchronous blocking APIs (a long CPU loop, `std::thread::sleep`, blocking file I/O) inside an `async fn` stalls the runtime’s worker. Use the async equivalents (`tokio::time::sleep`, async I/O) or move the work to `spawn_blocking`; see [Spawning Tasks](/11-async/09-spawning-tasks/) and [Concurrency vs Parallelism](/11-async/10-concurrency/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small production-flavored slice of a service: load a user and their orders, then build a summary. It shows `async fn`, `.await`, `?` propagation through several layers, a real error type, and an async `main` returning `Result`. (It also previews `tokio::join!` for concurrency, fully covered in [Select & Join](/11-async/07-select-join/).) ```rust 1 use std::time::Duration; 2 use tokio::time::sleep; 3 4 #[derive(Debug)] 5 struct User { 6 id: u32, 7 name: String, 8 } 9 10 #[derive(Debug)] 11 struct Order { 12 id: u32, 13 total_cents: u64, 14 } 15 16 // A simulated repository error. 17 #[derive(Debug)] 18 enum RepoError { 19 NotFound(u32), 20 } 21 22 impl std::fmt::Display for RepoError { 23 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { 24 match self { 25 RepoError::NotFound(id) => write!(f, "record {id} not found"), 26 } 27 } 28 } 29 impl std::error::Error for RepoError {} 30 31 async fn load_user(id: u32) -> Result<User, RepoError> { 32 sleep(Duration::from_millis(40)).await; // simulate DB latency 33 if id == 0 { 34 return Err(RepoError::NotFound(id)); 35 } 36 Ok(User { id, name: format!("Ada-{id}") }) 37 } 38 39 async fn load_orders(user_id: u32) -> Result<Vec<Order>, RepoError> { 40 sleep(Duration::from_millis(40)).await; 41 Ok(vec![ 42 Order { id: user_id * 10 + 1, total_cents: 1299 }, 43 Order { id: user_id * 10 + 2, total_cents: 4900 }, 44 ]) 45 } 46 47 // Build a per-user summary. The `?` propagates the first RepoError it sees. 48 async fn build_summary(user_id: u32) -> Result<String, RepoError> { 49 // `join!` polls both futures on the same task concurrently and waits 50 // for both. (Covered in depth in select-join.md.) 51 let (user, orders) = tokio::join!(load_user(user_id), load_orders(user_id)); 52 let user = user?; // `?` on the Result returned by load_user 53 let orders = orders?; // `?` on the Result returned by load_orders 54 55 let total: u64 = orders.iter().map(|o| o.total_cents).sum(); 56 let first_order_id = orders.first().map(|o| o.id).unwrap_or(0); 57 Ok(format!( 58 "user #{} ({}) has {} orders (first #{}) totaling ${}.{:02}", 59 user.id, 60 user.name, 61 orders.len(), 62 first_order_id, 63 total / 100, 64 total % 100 65 )) 66 } 67 68 #[tokio::main] 69 async fn main() -> Result<(), Box<dyn std::error::Error>> { 70 // `?` in `main` works because main returns a Result. 71 let summary = build_summary(42).await?; 72 println!("{summary}"); 73 74 // The error path: 75 match build_summary(0).await { 76 Ok(s) => println!("{s}"), 77 Err(e) => println!("failed: {e}"), 78 } 79 Ok(()) 80 } ``` Real output: ```text 1 user #42 (Ada-42) has 2 orders (first #421) totaling $61.99 2 failed: record 0 not found ``` The equivalent TypeScript would look almost identical structurally (`async function`, `await`, `try/catch` or rejected Promises), but every `load_*` call here is a lazy future that only advances inside the Tokio runtime started by `#[tokio::main]`. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Async and Await](https://doc.rust-lang.org/book/ch17-01-futures-and-syntax.html) * [Asynchronous Programming in Rust (the async book)](https://rust-lang.github.io/async-book/) * [`std::future::Future`](https://doc.rust-lang.org/std/future/trait.Future.html) * [Reference — `await` expressions](https://doc.rust-lang.org/reference/expressions/await-expr.html) * [Tokio tutorial](https://tokio.rs/tokio/tutorial) ### Related Topics in This Guide [Section titled “Related Topics in This Guide”](#related-topics-in-this-guide) * [Promises vs Futures](/11-async/00-promises-vs-futures/) — the eager-vs-lazy difference in depth * [Tokio Intro](/11-async/02-tokio-intro/) — why Rust needs an explicit runtime * [Tokio Setup](/11-async/03-tokio-setup/) — `#[tokio::main]`, the runtime builder, `block_on` * [Async Functions](/11-async/04-async-functions/) — `async` blocks, capturing, returning futures, lifetimes * [Async Traits](/11-async/05-async-trait/) — native async fn in traits (stable since 1.75) * [Select & Join](/11-async/07-select-join/) — `tokio::join!` / `select!` for concurrency * [Spawning Tasks](/11-async/09-spawning-tasks/) — `tokio::spawn`, `spawn_blocking` * [Concurrency vs Parallelism](/11-async/10-concurrency/) — when to use async at all; the function-coloring issue * [The `?` Operator](/08-error-handling/01-question-mark/) — the foundation `?` builds on * [Multiple Error Types](/08-error-handling/07-multiple-errors/) — one error type + `From` conversions * [Functions](/03-functions/) — function fundamentals * Next up: [Section 12 — Modules & Packages](/12-modules-packages/) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1 [Section titled “Exercise 1”](#exercise-1) **Difficulty:** Beginner **Objective:** Convert a synchronous fallible function into an `async fn` and propagate the error with `?`. **Instructions:** Write `async fn parse_and_double(raw: &str) -> Result<i64, std::num::ParseIntError>` that (1) `.await`s a short `tokio::time::sleep` to simulate I/O, (2) parses `raw` into an `i64` using `?`, and (3) returns the value doubled. In `main`, print the results of `parse_and_double("21")` and `parse_and_double("oops")`. Solution ```rust 1 use std::time::Duration; 2 use tokio::time::sleep; 3 4 async fn parse_and_double(raw: &str) -> Result<i64, std::num::ParseIntError> { 5 sleep(Duration::from_millis(5)).await; 6 let n: i64 = raw.parse()?; 7 Ok(n * 2) 8 } 9 10 #[tokio::main] 11 async fn main() { 12 println!("{:?}", parse_and_double("21").await); 13 println!("{:?}", parse_and_double("oops").await); 14 } ``` Real output: ```text 1 Ok(42) 2 Err(ParseIntError { kind: InvalidDigit }) ``` ### Exercise 2 [Section titled “Exercise 2”](#exercise-2) **Difficulty:** Intermediate **Objective:** Chain two dependent async steps where the second depends on the first, propagating errors with `?`. **Instructions:** Given `async fn fetch_name(id: u32) -> Result<String, String>` (returns `Err` for `id == 0`) and `async fn fetch_bio(name: &str) -> Result<String, String>`, write `async fn build_profile(id: u32) -> Result<Profile, String>` that fetches the name, then uses it to fetch the bio, then returns a `Profile { id, bio }`. The two steps must run sequentially because the second needs the first’s result. Print `build_profile(7)` and `build_profile(0)`. Solution ```rust 1 use std::time::Duration; 2 use tokio::time::sleep; 3 4 #[derive(Debug)] 5 struct Profile { 6 id: u32, 7 bio: String, 8 } 9 10 async fn fetch_name(id: u32) -> Result<String, String> { 11 sleep(Duration::from_millis(5)).await; 12 if id == 0 { 13 Err("no such user".to_string()) 14 } else { 15 Ok(format!("name-{id}")) 16 } 17 } 18 19 async fn fetch_bio(name: &str) -> Result<String, String> { 20 sleep(Duration::from_millis(5)).await; 21 Ok(format!("bio of {name}")) 22 } 23 24 async fn build_profile(id: u32) -> Result<Profile, String> { 25 let name = fetch_name(id).await?; // step 1, may short-circuit 26 let bio = fetch_bio(&name).await?; // step 2 depends on step 1 27 Ok(Profile { id, bio }) 28 } 29 30 #[tokio::main] 31 async fn main() { 32 println!("{:?}", build_profile(7).await); 33 println!("{:?}", build_profile(0).await); 34 } ``` Real output: ```text 1 Ok(Profile { id: 7, bio: "bio of name-7" }) 2 Err("no such user") ``` ### Exercise 3 [Section titled “Exercise 3”](#exercise-3) **Difficulty:** Intermediate **Objective:** Demonstrate that a future is lazy by returning one from a *synchronous* function and awaiting it later. **Instructions:** Write a synchronous `fn make_adder(base: i32) -> impl Future<Output = i32>` that returns an `async` block computing `base + 100`. In `main`, call `make_adder(5)`, print a line proving nothing has run yet, then `.await` it and print the result. Confirm from the output that the “not yet awaited” line prints before the future runs. Solution ```rust 1 use std::future::Future; 2 3 fn make_adder(base: i32) -> impl Future<Output = i32> { 4 async move { base + 100 } 5 } 6 7 #[tokio::main] 8 async fn main() { 9 let fut = make_adder(5); // nothing has run yet 10 println!("future built, not yet awaited"); 11 let result = fut.await; // now it runs 12 println!("result = {result}"); 13 } ``` Real output: ```text 1 future built, not yet awaited 2 result = 105 ``` > **Note:** `make_adder` is not `async`, yet it returns a future — proof that `async fn` is just sugar for “a function returning `impl Future`,” and that building the future does not run its body. # The Tokio Runtime: Rust's Async Engine > Node's event loop is always running; Rust ships no runtime, so Tokio drives your futures. Compare its current-thread and multi-thread schedulers. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In Node.js, the **event loop** that drives your `async` code is built into the runtime; you never install it or start it. In Rust, there is **no built-in async runtime**: `async` is just language syntax, and you must bring your own executor to actually run futures. **Tokio** is the de-facto standard async runtime, and this page explains what it is, why Rust needs it, and how its **current-thread** and **multi-thread** schedulers compare to Node’s single-threaded event loop. > **Note:** This page focuses on the runtime itself. The *language-level* difference between eager Promises and lazy futures lives in [Promises vs Futures](/11-async/00-promises-vs-futures/), and the practical “how do I add and start Tokio” steps live in [Tokio Setup](/11-async/03-tokio-setup/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In Node.js, the runtime is the environment. You write `async`/`await`, and V8 plus libuv provide a single-threaded event loop that schedules your callbacks, timers, and I/O. There is nothing to install or initialize: ```typescript 1 // node app.ts — the event loop already exists; you just use it. 2 3 async function callService(name: string, ms: number): Promise<string> { 4 await new Promise((resolve) => setTimeout(resolve, ms)); 5 return `${name} responded after ${ms}ms`; 6 } 7 8 async function main(): Promise<void> { 9 const start = Date.now(); 10 11 // Promise.all runs these concurrently on the single event-loop thread. 12 const results = await Promise.all([ 13 callService("auth", 120), 14 callService("inventory", 90), 15 callService("pricing", 150), 16 ]); 17 18 for (const r of results) console.log(r); 19 // ~150ms total (the slowest call), NOT 360ms — the loop interleaves the waits. 20 console.log(`all done in ${Date.now() - start}ms`); 21 } 22 23 main(); ``` Key facts about the Node model that a TypeScript/JavaScript developer relies on every day: * There is exactly **one** JavaScript thread. Your code never runs in parallel with other JS code. * The event loop is **always on**. Calling `main()` and forgetting to `await` it still “works” because the loop keeps running until the queue drains. * Concurrency comes from **not blocking** the loop: timers and I/O happen off-thread (in libuv’s thread pool or the kernel) and resume your code via callbacks. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust gives you the same `async`/`await` syntax, but **no event loop is running unless you start one**. Tokio provides that loop. The most common way to start it is the `#[tokio::main]` attribute, which wraps your `async fn main` in a runtime: ```rust 1 use std::time::{Duration, Instant}; 2 use tokio::time::sleep; 3 4 /// Simulates calling a downstream service that takes `ms` milliseconds. 5 async fn call_service(name: &str, ms: u64) -> String { 6 sleep(Duration::from_millis(ms)).await; 7 format!("{name} responded after {ms}ms") 8 } 9 10 #[tokio::main] // <-- starts a Tokio runtime and runs the async body on it 11 async fn main() { 12 let start = Instant::now(); 13 14 // Spawn three independent tasks. The runtime drives them concurrently. 15 let h1 = tokio::spawn(call_service("auth", 120)); 16 let h2 = tokio::spawn(call_service("inventory", 90)); 17 let h3 = tokio::spawn(call_service("pricing", 150)); 18 19 // JoinHandle::await yields Result<T, JoinError>. 20 let results = [ 21 h1.await.unwrap(), 22 h2.await.unwrap(), 23 h3.await.unwrap(), 24 ]; 25 26 for r in &results { 27 println!("{r}"); 28 } 29 // Total ~= the SLOWEST call, not the sum. 30 println!("all done in {}ms", start.elapsed().as_millis()); 31 } ``` Real output (compile-verified with Tokio 1.52 on Rust 1.96): ```text 1 auth responded after 120ms 2 inventory responded after 90ms 3 pricing responded after 150ms 4 all done in 152ms ``` The 152ms result is the whole point: three “150ms-ish” calls finished in roughly the time of the slowest one, because the runtime interleaved their waits, exactly like Node’s `Promise.all`. The important difference is the `#[tokio::main]` line. Remove it, and there is no engine to drive any of this. > **Note:** This snippet needs Tokio in `Cargo.toml` (`tokio = { version = "1", features = ["full"] }`). The exact `cargo add` invocation is covered in [Tokio Setup](/11-async/03-tokio-setup/). *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Why does Rust need an explicit runtime at all? [Section titled “Why does Rust need an explicit runtime at all?”](#why-does-rust-need-an-explicit-runtime-at-all) In JavaScript, `async`/`await` and the event loop are inseparable: the loop ships inside V8/Node. In Rust, the language team made a deliberate, different choice: 1. **`async fn` is pure syntax sugar.** When you write `async fn f() -> T`, the compiler rewrites it into a state machine that implements the `Future` trait. Calling `f()` does **not** run anything; it just *constructs* that state machine. (This laziness is the headline difference from JS Promises — see [Promises vs Futures](/11-async/00-promises-vs-futures/).) 2. **A future only makes progress when something `poll`s it.** A `poll` either returns `Poll::Ready(value)` or `Poll::Pending`. The thing that repeatedly calls `poll`, parks pending tasks, and wakes them when their I/O is ready is called an **executor** (or **runtime**). 3. **The standard library ships the `Future` trait and `async`/`await`, but no executor.** This keeps `std` small and lets Rust run on environments with wildly different needs: a Linux server, an embedded microcontroller with no heap, a browser via WebAssembly. Each picks a runtime that fits (Tokio for servers, Embassy for embedded, etc.). So in Rust the “event loop” is a library you choose, not a built-in you inherit. **Tokio** is that library for the vast majority of networked and server-side code. ### What is in a Tokio runtime? [Section titled “What is in a Tokio runtime?”](#what-is-in-a-tokio-runtime) A Tokio runtime bundles three things that Node fuses into one opaque “event loop”: * A **scheduler** (also called the executor): decides which ready task to poll next, and on which thread. * An **I/O driver / reactor**: registers sockets, timers, and other OS resources with the operating system (via `epoll`/`kqueue`/IOCP) and wakes the corresponding task when they become ready. * A **timer** and a **blocking thread pool** (for `spawn_blocking`, covered in [Spawning Tasks](/11-async/09-spawning-tasks/)). When you write `#[tokio::main]`, the macro expands to roughly this: ```rust 1 // What `#[tokio::main]` generates (conceptually) — not something you type by hand. 2 fn main() { 3 tokio::runtime::Runtime::new() 4 .unwrap() 5 .block_on(async { 6 // ... your async main body ... 7 }); 8 } ``` `Runtime::new()` builds the multi-thread scheduler, and `block_on` blocks the **current** thread and drives the given future to completion, returning its output (spawned tasks may run on the runtime’s worker threads). `block_on` is the bridge from the ordinary synchronous world (`fn main`) into async-land. ### Building a runtime by hand [Section titled “Building a runtime by hand”](#building-a-runtime-by-hand) The attribute is convenience; the `Builder` is the real API and is worth seeing once, because it makes the “you must start a runtime” point concrete: ```rust 1 fn main() { 2 // Build a CURRENT-THREAD runtime: one OS thread runs the event loop, 3 // exactly like Node's single-threaded model. 4 let rt = tokio::runtime::Builder::new_current_thread() 5 .enable_all() 6 .build() 7 .unwrap(); 8 9 rt.block_on(async { 10 let handle = tokio::spawn(async { 21 * 2 }); 11 let answer = handle.await.unwrap(); 12 println!("current-thread runtime computed: {answer}"); 13 }); 14 } ``` Real output: ```text 1 current-thread runtime computed: 42 ``` `enable_all()` turns on both the I/O and timer drivers; without it, things like `tokio::net` sockets and `tokio::time::sleep` would panic at runtime. `block_on` then drives the async block on this thread until it finishes. ### The two schedulers [Section titled “The two schedulers”](#the-two-schedulers) Tokio ships two scheduler “flavors”: ```rust 1 // 1) Multi-thread (the default for #[tokio::main]): 2 let rt = tokio::runtime::Builder::new_multi_thread() 3 .worker_threads(4) // optional; defaults to the number of CPU cores 4 .enable_all() 5 .build() 6 .unwrap(); 7 8 // 2) Current-thread (one OS thread; closest to Node's model): 9 let rt = tokio::runtime::Builder::new_current_thread() 10 .enable_all() 11 .build() 12 .unwrap(); ``` You can also select the flavor on the attribute: ```rust 1 #[tokio::main(flavor = "current_thread")] 2 async fn main() { /* ... */ } 3 4 #[tokio::main(flavor = "multi_thread", worker_threads = 4)] 5 async fn main() { /* ... */ } ``` The **multi-thread** scheduler runs a pool of worker threads and uses **work-stealing**: an idle worker can pull tasks from a busy worker’s queue. This is genuine parallelism: two of your tasks can be executing Rust code *at the same instant* on different cores. The **current-thread** scheduler runs everything on the one thread that called `block_on`, interleaving tasks at `.await` points, just like Node. > **Tip:** “Concurrency” (making progress on many things by interleaving) and “parallelism” (literally running at the same time) are different. The multi-thread scheduler gives you both; the current-thread scheduler gives you concurrency only. [Concurrency](/11-async/10-concurrency/) dives into this distinction. ### Seeing the single-thread model bite [Section titled “Seeing the single-thread model bite”](#seeing-the-single-thread-model-bite) Because the current-thread scheduler has exactly one thread, blocking that thread blocks *everything*, and this is where TypeScript/JavaScript intuition transfers directly (you already know not to run a `while(true)` loop on the event loop). The following compares a blocking sleep against an async sleep on a current-thread runtime: ```rust 1 use std::time::{Duration, Instant}; 2 3 #[tokio::main(flavor = "current_thread")] 4 async fn main() { 5 let start = Instant::now(); 6 7 // std::thread::sleep BLOCKS the OS thread the runtime is on. 8 let a = tokio::spawn(async { 9 std::thread::sleep(Duration::from_millis(100)); // blocks the whole runtime 10 "a" 11 }); 12 let b = tokio::spawn(async { 13 std::thread::sleep(Duration::from_millis(100)); 14 "b" 15 }); 16 17 let _ = a.await.unwrap(); 18 let _ = b.await.unwrap(); 19 println!("blocking sleeps took {}ms", start.elapsed().as_millis()); 20 } ``` Real output: ```text 1 blocking sleeps took 209ms ``` The two 100ms sleeps could **not** overlap. They ran one after another (\~200ms total) because each one held the single runtime thread hostage. Swap in Tokio’s async timer, which yields control back to the runtime instead of blocking the thread: ```rust 1 use std::time::{Duration, Instant}; 2 3 #[tokio::main(flavor = "current_thread")] 4 async fn main() { 5 let start = Instant::now(); 6 7 let a = tokio::spawn(async { 8 tokio::time::sleep(Duration::from_millis(100)).await; // yields to runtime 9 "a" 10 }); 11 let b = tokio::spawn(async { 12 tokio::time::sleep(Duration::from_millis(100)).await; 13 "b" 14 }); 15 16 let _ = a.await.unwrap(); 17 let _ = b.await.unwrap(); 18 println!("async sleeps took {}ms", start.elapsed().as_millis()); 19 } ``` Real output: ```text 1 async sleeps took 102ms ``` Now both timers overlap on a single thread (\~100ms), because `.await` on `tokio::time::sleep` hands the thread back to the scheduler so the other task can run. This is the Rust equivalent of “don’t do blocking work on the Node event loop.” *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | Node.js (TypeScript/JavaScript) | Rust + Tokio | | ------------------------- | ------------------------------------------ | ------------------------------------------------------------------ | | Event loop / runtime | Built in (libuv + V8); always running | **Not built in**; you choose and start one (e.g. Tokio) | | How async code starts | Implicit; calling an async fn schedules it | Explicit; a future does nothing until a runtime polls it | | Threads running your code | Exactly one JS thread | One (`current_thread`) or many (`multi_thread`) worker threads | | Parallelism of your code | None; single-threaded | Yes, on the multi-thread scheduler (work-stealing) | | Entry point | Top-level `await` / `main()` | `#[tokio::main]` or `Runtime::block_on` | | Choosing the runtime | Not a choice (it’s Node) | A real decision: Tokio, `async-std`, `smol`, Embassy, … | | Blocking the loop | Freezes everything | Freezes the current worker (and the whole app on `current_thread`) | ### The mental-model shift [Section titled “The mental-model shift”](#the-mental-model-shift) The single biggest adjustment for a TypeScript/JavaScript developer is this: **in Node the runtime owns your program; in Rust your program owns the runtime.** You decide when it starts, how many threads it has, and when it shuts down. `block_on` is the seam between sync `main` and the async world; there is no async code without a runtime underneath it. > **Note:** Unlike Node, where every `async function` runs on the same single loop, Tokio’s default (`multi_thread`) can run your tasks truly in parallel. That means shared mutable state needs synchronization — see [Arc + Mutex Pattern](/11-async/12-arc-mutex-pattern/) and [Sync Primitives](/11-async/11-sync-primitives/). This is the “fearless concurrency” payoff: the compiler forces you to handle it. ### Why two schedulers? [Section titled “Why two schedulers?”](#why-two-schedulers) * Use **`multi_thread`** (the default) for servers and anything that benefits from using all cores; it is what `#[tokio::main]` gives you by default. * Use **`current_thread`** for lightweight CLIs, tests, single-core/embedded-ish contexts, or when your futures are not `Send` and you want to avoid the overhead and constraints of a thread pool. It is also the closest 1:1 analogue to the Node model, which can make reasoning about ordering simpler. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Using `.await` in a non-async `fn main` [Section titled “Pitfall 1: Using .await in a non-async fn main”](#pitfall-1-using-await-in-a-non-async-fn-main) A `Future`’s `.await` is only legal inside an `async` context. Forgetting `#[tokio::main]` (or otherwise making `main` async) is the most common first mistake: ```rust 1 use std::time::Duration; 2 3 fn main() { 4 // does not compile (error[E0728]): `await` outside an async fn/block 5 tokio::time::sleep(Duration::from_millis(1)).await; 6 } ``` Real compiler error: ```text 1 error[E0728]: `await` is only allowed inside `async` functions and blocks 2 --> src/main.rs:5:50 3 | 4 3 | fn main() { 5 | --------- this is not `async` 6 4 | // does not compile (error[E0728]): `await` outside an async fn/block 7 5 | tokio::time::sleep(Duration::from_millis(1)).await; 8 | ^^^^^ only allowed inside `async` functions and blocks ``` **Fix:** add `#[tokio::main]` and make `main` async, or wrap the work in `rt.block_on(async { ... })`. ### Pitfall 2: Using Tokio resources with no runtime active [Section titled “Pitfall 2: Using Tokio resources with no runtime active”](#pitfall-2-using-tokio-resources-with-no-runtime-active) Even in a `fn main`, if you build a future that needs the runtime (a timer, a socket, `tokio::spawn`) and try to run it without an active runtime, you get a **runtime panic**, not a compile error, because the type system can’t see that a runtime is missing: ```rust 1 fn main() { 2 // panics at runtime: no active Tokio runtime to register the task with. 3 tokio::spawn(async { println!("hi"); }); 4 } ``` Real panic: ```text 1 thread 'main' panicked at src/main.rs:3:5: 2 there is no reactor running, must be called from the context of a Tokio 1.x runtime ``` **Fix:** start a runtime first (`#[tokio::main]`, or build one and call `block_on`). “There is no reactor running” is the message to memorize; it almost always means “you forgot to start (or you already dropped) the runtime.” ### Pitfall 3: Assuming “async” means “another thread” [Section titled “Pitfall 3: Assuming “async” means “another thread””](#pitfall-3-assuming-async-means-another-thread) Coming from Node, you might assume async work always happens “somewhere else.” On the `current_thread` scheduler it does not; see the 209ms blocking example above. A long synchronous computation or a `std::thread::sleep` in an async task starves every other task on that worker. For CPU-bound work, offload it (see [Spawning Tasks](/11-async/09-spawning-tasks/)’s `spawn_blocking`, or the exercises below). ### Pitfall 4: Creating a runtime inside a runtime [Section titled “Pitfall 4: Creating a runtime inside a runtime”](#pitfall-4-creating-a-runtime-inside-a-runtime) Calling `Runtime::new().block_on(...)` from *inside* an already-running Tokio context (for example, inside an `async fn`) panics with “Cannot start a runtime from within a runtime.” Build the runtime once, at the top of `main`. If you genuinely need to block on async code from a sync callback running on the runtime, use `tokio::task::block_in_place` or a dedicated thread instead. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Prefer the `#[tokio::main]` attribute** for binaries. Reach for `runtime::Builder` only when you need to tune `worker_threads`, name threads, set a custom thread stack size, or own the runtime’s lifetime explicitly. * **Default to the multi-thread scheduler** for servers; choose `current_thread` deliberately (lightweight CLIs, tests, `!Send` futures). Make the choice consciously rather than copy-pasting. * **Never block a worker thread.** Avoid `std::thread::sleep`, large synchronous CPU loops, and blocking file/database calls inside async tasks. Use async equivalents (`tokio::time::sleep`, `tokio::fs`) or `tokio::task::spawn_blocking` for unavoidably blocking code. * **Create exactly one runtime per process** in normal applications. Multiple runtimes are an advanced, rare need. * **Add Tokio with the features you actually use.** `features = ["full"]` is fine while learning; trim it later (`["rt-multi-thread", "macros", "net", "time"]`, etc.) to cut compile time. See [Tokio Setup](/11-async/03-tokio-setup/). * **Use a current compatible Tokio 1.x release.** This guide records the dependency version beside each complete example and checks against the repository’s [pinned Rust toolchain](/00-introduction/05-version-policy/) on the 2024 edition. Avoid copying pre-1.0 or pre-`axum 0.8` tutorials whose runtime/server APIs have since changed. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small task-runner that fans out work across the multi-thread scheduler. Each task records which OS worker thread executed it, illustrating that the runtime spreads work across the pool (true parallelism), unlike Node’s single thread: ```rust 1 use std::collections::HashSet; 2 use std::sync::{Arc, Mutex}; 3 use std::time::Duration; 4 5 #[tokio::main(flavor = "multi_thread", worker_threads = 4)] 6 async fn main() { 7 // Shared, thread-safe set of the worker thread IDs we observed. 8 let seen: Arc<Mutex<HashSet<std::thread::ThreadId>>> = 9 Arc::new(Mutex::new(HashSet::new())); 10 11 let mut handles = Vec::new(); 12 for _ in 0..32 { 13 let seen = Arc::clone(&seen); 14 handles.push(tokio::spawn(async move { 15 // Yield at an .await point so the scheduler can balance work 16 // across the pool rather than finishing each task instantly. 17 tokio::time::sleep(Duration::from_millis(5)).await; 18 seen.lock().unwrap().insert(std::thread::current().id()); 19 })); 20 } 21 22 for h in handles { 23 h.await.unwrap(); 24 } 25 26 let count = seen.lock().unwrap().len(); 27 println!("distinct worker threads used: {count}"); 28 } ``` Example output (the exact count is nondeterministic and depends on the scheduler and machine; on a multi-core box it will be greater than 1): ```text 1 distinct worker threads used: 2 ``` The `Arc<Mutex<...>>` is required precisely *because* the runtime may run those closures on different threads simultaneously — something the Node model never forces you to think about. The compiler would reject sharing a plain `HashSet` across tasks, which is “fearless concurrency” in action. The full pattern is covered in [Arc + Mutex Pattern](/11-async/12-arc-mutex-pattern/). > **Warning:** Holding a `std::sync::Mutex` guard across an `.await` is a footgun. It is fine here because we lock and immediately drop the guard within one synchronous statement. When a lock must stay held across `.await`, use Tokio’s async-aware [Sync Primitives](/11-async/11-sync-primitives/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [Tokio Tutorial — Hello Tokio & Setup](https://tokio.rs/tokio/tutorial) — the official getting-started walkthrough. * [Tokio `runtime` module docs](https://docs.rs/tokio/latest/tokio/runtime/index.html) — `Runtime`, `Builder`, and scheduler details. * [The `async`/`await` chapter of the Rust Book](https://doc.rust-lang.org/book/ch17-00-async-await.html) — language-level treatment of futures. * [The Async Book](https://rust-lang.github.io/async-book/) — deeper coverage of futures, executors, and `poll`. Related sections in this guide: * [Promises vs Futures](/11-async/00-promises-vs-futures/) — eager Promises vs lazy futures; *why* a runtime is even needed. * [Async/Await Syntax](/11-async/01-async-await/) — `async fn`, `impl Future`, `.await`, and `?` in async code. * [Tokio Setup](/11-async/03-tokio-setup/) — adding Tokio, features, and `#[tokio::main]` in detail. * [Spawning Tasks](/11-async/09-spawning-tasks/) — `tokio::spawn`, `JoinHandle`, and `spawn_blocking`. * [Concurrency vs Parallelism](/11-async/10-concurrency/) — tasks vs threads, structured patterns, cancellation. * [Async vs Sync](/11-async/13-async-vs-sync/) — when async is the wrong tool (CPU-bound work) and the “function coloring” problem. * Foundations: [Getting Started](/01-getting-started/) and [Basics](/02-basics/). Once you understand runtimes, [Modules & Packages](/12-modules-packages/) shows how to structure a larger async crate. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Start a runtime by hand [Section titled “Exercise 1: Start a runtime by hand”](#exercise-1-start-a-runtime-by-hand) **Difficulty:** Easy **Objective:** Run async code without the `#[tokio::main]` attribute, proving you understand what the macro does. **Instructions:** 1. Start from a plain, synchronous `fn main`. 2. Build a **current-thread** runtime with `tokio::runtime::Builder`. 3. Use `block_on` to run three `tick(n)` futures concurrently with `tokio::join!`, where `tick(n)` sleeps for `10 * n` ms and then prints `tick {n}`. 4. Confirm they print in ascending order (`1`, `2`, `3`) because of the staggered delays. Solution ```rust 1 use std::time::Duration; 2 use tokio::time::sleep; 3 4 async fn tick(n: u32) { 5 sleep(Duration::from_millis(10 * n as u64)).await; 6 println!("tick {n}"); 7 } 8 9 fn main() { 10 let rt = tokio::runtime::Builder::new_current_thread() 11 .enable_all() // turn on the timer driver so sleep() works 12 .build() 13 .expect("failed to build runtime"); 14 15 rt.block_on(async { 16 // All three are driven concurrently on the single runtime thread. 17 tokio::join!(tick(3), tick(1), tick(2)); 18 }); 19 } ``` Real output: ```text 1 tick 1 2 tick 2 3 tick 3 ``` `enable_all()` is what makes `sleep` work; without it the timer would panic. The futures finish in delay order even though they were listed `3, 1, 2`. ### Exercise 2: Keep the runtime responsive during CPU-bound work [Section titled “Exercise 2: Keep the runtime responsive during CPU-bound work”](#exercise-2-keep-the-runtime-responsive-during-cpu-bound-work) **Difficulty:** Medium **Objective:** Use `spawn_blocking` so a heavy synchronous computation does not stall the single-threaded runtime. **Instructions:** 1. Write a synchronous `heavy_sum(n)` that sums `0..n` (a CPU-bound loop with no `.await`). 2. On a **current-thread** runtime, offload `heavy_sum(50_000_000)` with `tokio::task::spawn_blocking`. 3. At the same time, spawn an I/O task that sleeps 10ms and returns a message. 4. Await both and print the message and the sum, demonstrating the timer task still made progress. Solution ```rust 1 fn heavy_sum(n: u64) -> u64 { 2 // CPU-bound: no .await points, so it must NOT run on a runtime worker. 3 (0..n).fold(0u64, |acc, x| acc.wrapping_add(x)) 4 } 5 6 #[tokio::main(flavor = "current_thread")] 7 async fn main() { 8 // Offload to the blocking thread pool so the single runtime thread 9 // stays free to drive other tasks. 10 let handle = tokio::task::spawn_blocking(|| heavy_sum(50_000_000)); 11 12 let timer = tokio::spawn(async { 13 tokio::time::sleep(std::time::Duration::from_millis(10)).await; 14 "timer fired" 15 }); 16 17 let total = handle.await.unwrap(); 18 let msg = timer.await.unwrap(); 19 println!("{msg}; sum = {total}"); 20 } ``` Real output (built with `--release`): ```text 1 timer fired; sum = 1249999975000000 ``` If you ran `heavy_sum` directly inside an async task instead of `spawn_blocking`, it would monopolize the only runtime thread and the timer could not fire until it finished. `spawn_blocking` moves it to a dedicated blocking pool. (See [Spawning Tasks](/11-async/09-spawning-tasks/).) ### Exercise 3: Observe the multi-thread scheduler [Section titled “Exercise 3: Observe the multi-thread scheduler”](#exercise-3-observe-the-multi-thread-scheduler) **Difficulty:** Hard **Objective:** Demonstrate that the multi-thread scheduler runs tasks on more than one OS thread. **Instructions:** 1. Use `#[tokio::main(flavor = "multi_thread", worker_threads = 4)]`. 2. Spawn 32 tasks. Each one `.await`s a short `tokio::time::sleep`, then records `std::thread::current().id()` into a shared `Arc<Mutex<HashSet<ThreadId>>>`. 3. Await all tasks, then print how many distinct worker thread IDs were seen. 4. Run it a few times and note the count varies but is greater than 1 on a multi-core machine: proof of real parallelism. Explain why an `Arc<Mutex<...>>` is required here but would be unnecessary in Node. Solution ```rust 1 use std::collections::HashSet; 2 use std::sync::{Arc, Mutex}; 3 use std::time::Duration; 4 5 #[tokio::main(flavor = "multi_thread", worker_threads = 4)] 6 async fn main() { 7 let seen: Arc<Mutex<HashSet<std::thread::ThreadId>>> = 8 Arc::new(Mutex::new(HashSet::new())); 9 10 let mut handles = Vec::new(); 11 for _ in 0..32 { 12 let seen = Arc::clone(&seen); 13 handles.push(tokio::spawn(async move { 14 // The .await lets the scheduler move/spread work across workers. 15 tokio::time::sleep(Duration::from_millis(5)).await; 16 seen.lock().unwrap().insert(std::thread::current().id()); 17 })); 18 } 19 20 for h in handles { 21 h.await.unwrap(); 22 } 23 24 println!("distinct worker threads used: {}", seen.lock().unwrap().len()); 25 } ``` Example output (nondeterministic; greater than 1 on multi-core hardware): ```text 1 distinct worker threads used: 2 ``` `Arc` lets multiple tasks share ownership of the set; `Mutex` guards the concurrent mutation. They are required because, unlike Node’s single JS thread, two of these closures can run on different OS threads at the same instant. The Rust compiler enforces this: a plain shared `HashSet` would not satisfy `Send`/`Sync` and would be rejected at compile time. That is “fearless concurrency” — the runtime gives you parallelism, and the type system makes sure you handle it safely. # Setting Up Tokio > Rust ships no async runtime, so .await does nothing until you add one. Wire up Tokio: the dependency, #[tokio::main], and building a runtime by hand. Rust has no built-in async runtime, so before any `.await` does anything you must add one. **Tokio** is the de-facto standard. This page is about the mechanics of *wiring it up*: adding the crate with the right features, the `#[tokio::main]` attribute, and building a runtime by hand. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In JavaScript the async runtime is invisible: the engine (V8) and its event loop are always present, so `async`/`await` “just works”. In Rust, **futures are lazy** (they do nothing until polled) and there is **no executor in the standard library**. You bring your own runtime, and 95% of the time that runtime is **Tokio**. This topic covers the three things you need to get async code running: * Adding `tokio` to `Cargo.toml` with `features = ["full"]`. * The `#[tokio::main]` attribute that turns an `async fn main` into a normal `main`. * Building a runtime manually with `tokio::runtime::Builder` when you need more control. > **Note:** *Why* Rust needs an explicit runtime at all is covered in [The Tokio Runtime](/11-async/02-tokio-intro/), and *why* futures are lazy in [Promises vs Futures](/11-async/00-promises-vs-futures/). This page assumes you accept that and want to set it up. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In Node.js there is nothing to install or configure. The runtime ships with the engine, and `async`/`await` is part of the language. You write an entry point and call async functions directly: ```typescript 1 // index.ts — no runtime setup required; Node already has an event loop. 2 3 async function fetchData(): Promise<string> { 4 // Simulate a 50 ms network call. 5 await new Promise((resolve) => setTimeout(resolve, 50)); 6 return "data from the network"; 7 } 8 9 async function main(): Promise<void> { 10 console.log("Server starting..."); 11 const result = await fetchData(); 12 console.log(`Got: ${result}`); 13 } 14 15 // Top-level await also works in modern modules, but a main() is common. 16 main(); ``` ```bash 1 # You just run it. The runtime is built in. 2 node index.ts ``` There is no concept of “choosing a runtime” or “starting the event loop”; `setTimeout`, `fetch`, and `Promise` are all backed by libuv/V8 automatically. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) In Rust you add the runtime as a dependency and annotate `main` so Tokio sets up the event loop for you: ```bash 1 cargo new async_demo 2 cd async_demo 3 cargo add tokio --features full ``` src/main.rs ```rust 1 use std::time::Duration; 2 use tokio::time::sleep; 3 4 #[tokio::main] // sets up the Tokio runtime and runs the async body to completion 5 async fn main() { 6 println!("Server starting..."); 7 let result = fetch_data().await; 8 println!("Got: {result}"); 9 } 10 11 async fn fetch_data() -> String { 12 // Tokio's async sleep — NOT std::thread::sleep, which would block the runtime. 13 sleep(Duration::from_millis(50)).await; 14 "data from the network".to_string() 15 } ``` ```bash 1 cargo run ``` Real output: ```plaintext 1 Server starting... 2 Got: data from the network ``` The `#[tokio::main]` attribute is the entire difference from JavaScript: it is the line that says “create an event loop and drive my futures to completion.” *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Adding the dependency [Section titled “Adding the dependency”](#adding-the-dependency) `cargo add tokio --features full` writes this into `Cargo.toml`: ```toml 1 [dependencies] 2 tokio = { version = "1.52.3", features = ["full"] } ``` > **Note:** `cargo add` is built into Cargo (since 1.62); you do **not** need `cargo-edit`. The examples use the repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) and the **2024 edition**, which `cargo new` selects automatically. The `features = ["full"]` part is the one you must not skip while learning. Tokio is heavily **feature-gated**: by default almost nothing is enabled, so individual capabilities (timers, TCP, the multi-thread scheduler, the `#[tokio::main]` macro) each live behind a feature flag. `"full"` turns them all on, which is exactly what you want while you are getting started. Compare to how Node bundles everything: there is no `--features` equivalent because the JS runtime is monolithic. Tokio’s à la carte design lets a production binary shrink to only what it uses, but that optimization comes *later*. (More on trimming features under [Best Practices](#best-practices).) ### What `#[tokio::main]` actually does [Section titled “What #\[tokio::main\] actually does”](#what-tokiomain-actually-does) `#[tokio::main]` is a **procedural macro**, not magic syntax. Rust does not allow `main` itself to be `async` (you will see the exact error in [Common Pitfalls](#common-pitfalls)). The macro rewrites your `async fn main` into a normal synchronous `main` that builds a runtime and blocks on your async body. Roughly, this: ```rust 1 #[tokio::main] 2 async fn main() { 3 println!("hello"); 4 } ``` expands into something equivalent to this, which compiles and runs on its own: ```rust 1 fn main() { 2 tokio::runtime::Builder::new_multi_thread() 3 .enable_all() 4 .build() 5 .unwrap() 6 .block_on(async { 7 println!("this is roughly what #[tokio::main] expands to"); 8 }); 9 } ``` ```plaintext 1 this is roughly what #[tokio::main] expands to ``` So the macro is pure convenience: it hides the `Builder`/`block_on` boilerplate. Understanding the expansion is what makes the manual `Builder` approach (below) feel familiar instead of mysterious. > **Tip:** Run `cargo expand` (install with `cargo install cargo-expand`) on a file using `#[tokio::main]` to see the *real* generated code for your version of Tokio. ### `block_on`: the bridge between sync and async [Section titled “block\_on: the bridge between sync and async”](#block_on-the-bridge-between-sync-and-async) `block_on` is the one function that crosses from the synchronous world into the asynchronous one. It takes a future, drives it to completion on the current thread, and returns its output. Every async program has exactly one such bridge at the top: either written by `#[tokio::main]` for you, or written by hand. This is the inverse of JavaScript: there, the whole program runs *inside* the event loop and you can `await` anywhere. In Rust, the program starts synchronous and you explicitly *enter* async via `block_on`. ### `enable_all` [Section titled “enable\_all”](#enable_all) `.enable_all()` turns on Tokio’s **I/O driver** (for sockets, files) and **time driver** (for `sleep`, `timeout`, `interval`). Without it, timer- and I/O-based APIs will panic at runtime even though the code compiles. `#[tokio::main]` calls `enable_all()` for you; when you build a runtime manually you must call it yourself. *** ## Building a Runtime Manually [Section titled “Building a Runtime Manually”](#building-a-runtime-manually) `#[tokio::main]` is great for binaries, but sometimes you need to construct the runtime yourself: * A **synchronous** `main` (or library code) that needs to run *some* async work. * Fine control over thread count, thread names, or the scheduler flavor. * Running async code inside a context you do not own (a test harness, an FFI callback, a plugin). ### The two scheduler flavors [Section titled “The two scheduler flavors”](#the-two-scheduler-flavors) ```rust 1 use tokio::runtime::Builder; 2 3 fn main() { 4 // Current-thread: a single-threaded scheduler. Closest to Node's model. 5 let runtime = Builder::new_current_thread() 6 .enable_all() 7 .build() 8 .unwrap(); 9 10 runtime.block_on(async { 11 println!("current-thread runtime is running"); 12 }); 13 14 // Multi-thread: a work-stealing thread pool (the default for #[tokio::main]). 15 let pool = Builder::new_multi_thread() 16 .worker_threads(4) 17 .thread_name("api-worker") 18 .enable_all() 19 .build() 20 .unwrap(); 21 22 pool.block_on(async { 23 println!("multi-thread runtime with 4 workers is running"); 24 }); 25 } ``` ```plaintext 1 current-thread runtime is running 2 multi-thread runtime with 4 workers is running ``` The difference between these schedulers — and which to choose — is the subject of [The Tokio Runtime](/11-async/02-tokio-intro/). Here the point is purely *how* to build each one. ### The simplest manual form [Section titled “The simplest manual form”](#the-simplest-manual-form) If you do not need any custom options, `Runtime::new()` gives you a default multi-thread runtime (equivalent to `Builder::new_multi_thread().enable_all().build()`): ```rust 1 fn main() { 2 let runtime = tokio::runtime::Runtime::new().unwrap(); 3 runtime.block_on(async { 4 println!("Running inside a manually built runtime"); 5 let n = compute().await; 6 println!("computed = {n}"); 7 }); 8 } 9 10 async fn compute() -> u32 { 11 40 + 2 12 } ``` ```plaintext 1 Running inside a manually built runtime 2 computed = 42 ``` ### Configuring `#[tokio::main]` without the builder [Section titled “Configuring #\[tokio::main\] without the builder”](#configuring-tokiomain-without-the-builder) The attribute accepts arguments that map onto the builder, so you often do not need the manual form even when you want a non-default scheduler: ```rust 1 // A single-threaded runtime, the lightweight choice for simple CLIs. 2 #[tokio::main(flavor = "current_thread")] 3 async fn main() { 4 println!("single-threaded tokio runtime"); 5 } ``` ```plaintext 1 single-threaded tokio runtime ``` ```rust 1 // Multi-thread with a fixed worker count. 2 #[tokio::main(flavor = "multi_thread", worker_threads = 2)] 3 async fn main() { 4 println!("multi-threaded runtime, 2 workers"); 5 } ``` ```plaintext 1 multi-threaded runtime, 2 workers ``` ### Returning a `Result` from `main` [Section titled “Returning a Result from main”](#returning-a-result-from-main) Because `#[tokio::main]` produces an ordinary `main`, your async `main` can return a `Result`, which lets you use the `?` operator at the top level, handy for prototypes and CLIs: ```rust 1 use std::time::Duration; 2 use tokio::time::{sleep, timeout}; 3 4 #[tokio::main] 5 async fn main() -> Result<(), Box<dyn std::error::Error>> { 6 // `?` works here because main returns a Result. 7 let value = timeout(Duration::from_millis(100), slow_task()).await?; 8 println!("task returned: {value}"); 9 Ok(()) 10 } 11 12 async fn slow_task() -> u32 { 13 sleep(Duration::from_millis(10)).await; 14 7 15 } ``` ```plaintext 1 task returned: 7 ``` > **Note:** Error handling with `?` inside async functions is covered fully in [Async/Await Syntax](/11-async/01-async-await/). The takeaway *here* is that the setup (`#[tokio::main]`) does not get in the way of returning errors. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | JavaScript / Node.js | Rust + Tokio | | --------------------- | --------------------------------------------- | --------------------------------------------------------- | | Runtime source | Built into the engine (V8 + libuv) | A crate you add (`tokio`) | | Starting the loop | Automatic, invisible | Explicit: `#[tokio::main]` or `block_on` | | Where you can `await` | Anywhere inside `async`; top-level in modules | Only inside `async`; the top is sync until `block_on` | | Choosing threads | Single-threaded event loop, fixed | Pick `current_thread` or `multi_thread`, set worker count | | Enabling features | All capabilities always present | Feature-gated; use `features = ["full"]` to start | | Multiple runtimes | One event loop per process | You may build several runtimes (rarely needed) | | Cost of “no runtime” | Impossible state | Compiles fine, then **panics at runtime** | The single most important row is the last one. In JavaScript “no runtime” cannot happen. In Rust, code that uses Tokio APIs *compiles* without a runtime present and only fails when it runs — a class of bug that does not exist in Node. The setup step exists precisely to avoid it. > **Warning:** Unlike Node’s single fixed event loop, a multi-thread Tokio runtime runs your tasks across several OS threads by default. This means values shared between tasks must be `Send`/`Sync`, and shared mutable state needs `Arc<Mutex<...>>` rather than a bare variable. See [The `Arc<Mutex<T>>` Pattern](/11-async/12-arc-mutex-pattern/). Rust’s concurrency is opt-in and compiler-checked; it is *not* “multi-threaded by default” in the sense of unguarded shared memory. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: `async fn main` without the attribute [Section titled “Pitfall 1: async fn main without the attribute”](#pitfall-1-async-fn-main-without-the-attribute) If you forget `#[tokio::main]`, Rust rejects an `async` main outright: `main` is special and may not be async: ```rust 1 async fn main() { // does not compile (error[E0752]) 2 println!("hi"); 3 } ``` Real compiler output: ```plaintext 1 error[E0752]: `main` function is not allowed to be `async` 2 --> src/main.rs:1:1 3 | 4 1 | async fn main() { 5 | ^^^^^^^^^^^^^^^ `main` function is not allowed to be `async` 6 7 For more information about this error, try `rustc --explain E0752`. 8 error: could not compile `probe` (bin "probe") due to 1 previous error ``` **Fix:** add `#[tokio::main]` above the function (or build a runtime manually). ### Pitfall 2: Using a Tokio API with no runtime present [Section titled “Pitfall 2: Using a Tokio API with no runtime present”](#pitfall-2-using-a-tokio-api-with-no-runtime-present) This is the bug that has no JavaScript analogue. The code compiles, but at runtime there is no event loop to register the task with, so it **panics**: ```rust 1 fn main() { 2 // compiles, but panics at runtime: no runtime in scope. 3 tokio::spawn(async { 4 println!("never runs"); 5 }); 6 } ``` Real output when run: ```plaintext 1 thread 'main' panicked at src/main.rs:3:5: 2 there is no reactor running, must be called from the context of a Tokio 1.x runtime 3 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` **Fix:** call the Tokio API from inside `#[tokio::main]`, inside a `block_on`, or inside a task spawned on a runtime. (`tokio::spawn` is covered in [Spawning Tasks](/11-async/09-spawning-tasks/).) ### Pitfall 3: Calling `block_on` inside an async context [Section titled “Pitfall 3: Calling block\_on inside an async context”](#pitfall-3-calling-block_on-inside-an-async-context) `block_on` blocks the current thread until the future finishes. Calling it from *within* a task that is already being driven by the runtime would deadlock the worker thread, so Tokio detects it and panics: ```rust 1 #[tokio::main] 2 async fn main() { 3 let rt = tokio::runtime::Handle::current(); 4 // compiles, but panics at runtime: block_on inside a runtime. 5 rt.block_on(async { 6 println!("never reached"); 7 }); 8 } ``` Real output when run: ```plaintext 1 thread 'main' panicked at src/main.rs:5:8: 2 Cannot start a runtime from within a runtime. This happens because a function (like `block_on`) attempted to block the current thread while the thread is being used to drive asynchronous tasks. 3 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` **Fix:** inside async code, use `.await`, not `block_on`. `block_on` belongs only at the synchronous boundary (the top of your program or a sync helper). ### Pitfall 4: Forgetting `features = ["full"]` (or `enable_all`) [Section titled “Pitfall 4: Forgetting features = \["full"\] (or enable\_all)”](#pitfall-4-forgetting-features--full-or-enable_all) If you add Tokio with a trimmed feature set and then reach for an API that lives behind a feature you did not enable, you get a *compile* error, not a runtime one. Here Tokio was added with `default-features = false, features = ["rt", "macros", "rt-multi-thread"]`, no `time` feature: ```rust 1 use std::time::Duration; 2 3 #[tokio::main] 4 async fn main() { 5 // does not compile: the `time` module is gated behind the "time" feature. 6 tokio::time::sleep(Duration::from_millis(10)).await; 7 println!("done"); 8 } ``` Real compiler output: ```plaintext 1 error[E0433]: failed to resolve: could not find `time` in `tokio` 2 --> src/main.rs:6:12 3 | 4 6 | tokio::time::sleep(Duration::from_millis(10)).await; 5 | ^^^^ could not find `time` in `tokio` 6 | 7 note: found an item that was configured out 8 --> .../tokio-1.52.3/src/lib.rs:566:13 9 | 10 565 | / cfg_time! { 11 566 | | pub mod time; 12 | | ^^^^ 13 567 | | } 14 | |_- the item is gated behind the `time` feature ``` **Fix while learning:** use `features = ["full"]`. The error message conveniently names the missing feature (`time`) when you are ready to trim. > **Warning:** A separate but related trap is enabling the feature but forgetting `.enable_all()` on a manually built runtime; then timer/I/O APIs panic at runtime with a message about the driver not being enabled. `#[tokio::main]` calls `enable_all()` for you; manual builders must do it explicitly. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Start with `features = ["full"]`, trim later [Section titled “Start with features = \["full"\], trim later”](#start-with-features--full-trim-later) While learning and prototyping, `features = ["full"]` removes a whole category of “which feature was that behind?” friction. Once your binary is stable and you care about compile time and binary size, trim to exactly what you use: ```toml 1 [dependencies] 2 # Production: only what this service actually needs. 3 tokio = { version = "1", features = ["rt-multi-thread", "macros", "net", "time"] } ``` > **Tip:** A bare version string like `"1"` is a **caret** requirement (`>=1.0.0, <2.0.0`), not an exact pin. That is what you want for Tokio: you get compatible bug-fix and minor releases automatically. Use `"=1.52.3"` only if you truly need to freeze the exact version. ### Use `#[tokio::main]` for binaries, manual builders for libraries [Section titled “Use #\[tokio::main\] for binaries, manual builders for libraries”](#use-tokiomain-for-binaries-manual-builders-for-libraries) Application entry points should use `#[tokio::main]` — it is clear and idiomatic. **Libraries should not pick a runtime for the caller**; expose `async fn`s and let the binary supply the runtime. Build a runtime by hand only when you are the one running the show (a CLI bridging into async, a test, an FFI boundary). ### Pick `current_thread` for simple, mostly-I/O CLIs [Section titled “Pick current\_thread for simple, mostly-I/O CLIs”](#pick-current_thread-for-simple-mostly-io-clis) A single-threaded runtime has lower overhead and avoids `Send` bounds on your futures. For a CLI that makes a few network calls, `#[tokio::main(flavor = "current_thread")]` is often the better default; reach for `multi_thread` when you have many concurrent tasks or CPU-bound work spread across `spawn_blocking`. The trade-offs are explored in [Async vs Sync](/11-async/13-async-vs-sync/). ### Build the runtime once and reuse it [Section titled “Build the runtime once and reuse it”](#build-the-runtime-once-and-reuse-it) Constructing a runtime allocates threads and drivers; do not create one per operation. Build it once, then call `block_on` (or spawn tasks) as many times as you like: ```rust 1 use tokio::runtime::Builder; 2 3 async fn square(n: u64) -> u64 { 4 n * n 5 } 6 7 fn main() { 8 // One runtime, reused for several independent operations. 9 let rt = Builder::new_current_thread() 10 .enable_all() 11 .max_blocking_threads(8) // cap the blocking thread pool 12 .build() 13 .unwrap(); 14 15 for n in 1..=4 { 16 let result = rt.block_on(square(n)); 17 println!("{n}^2 = {result}"); 18 } 19 } ``` ```plaintext 1 1^2 = 1 2 2^2 = 4 3 3^2 = 9 4 4^2 = 16 ``` ### Use `#[tokio::test]` for async tests [Section titled “Use #\[tokio::test\] for async tests”](#use-tokiotest-for-async-tests) The plain `#[test]` attribute cannot run an `async fn`. Tokio ships `#[tokio::test]`, which builds a runtime around each test (it accepts the same `flavor`/`worker_threads` arguments as `#[tokio::main]`): ```rust 1 use std::time::Duration; 2 use tokio::time::sleep; 3 4 async fn double(n: u32) -> u32 { 5 sleep(Duration::from_millis(5)).await; 6 n * 2 7 } 8 9 #[cfg(test)] 10 mod tests { 11 use super::*; 12 13 #[tokio::test] 14 async fn doubles_the_input() { 15 assert_eq!(double(21).await, 42); 16 } 17 18 #[tokio::test(flavor = "multi_thread", worker_threads = 2)] 19 async fn runs_on_multi_thread() { 20 assert_eq!(double(5).await, 10); 21 } 22 } ``` ```plaintext 1 running 2 tests 2 test tests::doubles_the_input ... ok 3 test tests::runs_on_multi_thread ... ok 4 5 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s ``` *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A common production pattern: a service starts a Tokio runtime *explicitly* (rather than via `#[tokio::main]`) so it can name threads for observability and pin a worker count, then runs concurrent I/O on it. Here we fetch several pages of a paginated API concurrently and gather the results. ```rust 1 use std::time::Duration; 2 use tokio::runtime::Builder; 3 use tokio::time::sleep; 4 5 /// Simulates fetching one page of results from a paginated API. 6 async fn fetch_page(page: u32) -> Vec<String> { 7 sleep(Duration::from_millis(20)).await; // stands in for a network round-trip 8 (0..3).map(|i| format!("page {page} item {i}")).collect() 9 } 10 11 fn main() { 12 // Build the runtime explicitly: named threads show up in profilers/crash 13 // dumps, and a fixed worker count keeps resource use predictable. 14 let runtime = Builder::new_multi_thread() 15 .worker_threads(4) 16 .thread_name("fetch-worker") 17 .enable_all() 18 .build() 19 .expect("failed to build Tokio runtime"); 20 21 let all_items = runtime.block_on(async { 22 // Fetch three pages concurrently; join! awaits all of them together. 23 let (a, b, c) = tokio::join!(fetch_page(1), fetch_page(2), fetch_page(3)); 24 let mut items = Vec::new(); 25 items.extend(a); 26 items.extend(b); 27 items.extend(c); 28 items 29 }); 30 31 println!("fetched {} items", all_items.len()); 32 for item in &all_items { 33 println!(" - {item}"); 34 } 35 } ``` ```plaintext 1 fetched 9 items 2 - page 1 item 0 3 - page 1 item 1 4 - page 1 item 2 5 - page 2 item 0 6 - page 2 item 1 7 - page 2 item 2 8 - page 3 item 0 9 - page 3 item 1 10 - page 3 item 2 ``` Because all three pages sleep 20 ms *concurrently*, the whole block finishes in roughly 20 ms rather than 60 ms, the same intuition as `Promise.all`. (`join!` and friends are covered in [Concurrent Awaiting](/11-async/07-select-join/).) *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [Tokio Tutorial — Setup](https://tokio.rs/tokio/tutorial/setup) — official getting-started guide. * [`#[tokio::main]` macro docs](https://docs.rs/tokio/latest/tokio/attr.main.html) — every attribute argument. * [`tokio::runtime::Builder` docs](https://docs.rs/tokio/latest/tokio/runtime/struct.Builder.html): all configuration options. * [Tokio feature flags](https://docs.rs/tokio/latest/tokio/index.html#feature-flags) — what each feature enables, for trimming `"full"`. * [The Async Book](https://rust-lang.github.io/async-book/) — runtime-agnostic foundations. Related sections of this guide: * [Promises vs Futures](/11-async/00-promises-vs-futures/) — why Rust futures are lazy and need a runtime at all. * [The Tokio Runtime](/11-async/02-tokio-intro/) — Node’s event loop vs Tokio; current-thread vs multi-thread schedulers in depth. * [Async/Await Syntax](/11-async/01-async-await/): `async`/`await` syntax and `?` inside async. * [Spawning Tasks](/11-async/09-spawning-tasks/) — `tokio::spawn`, `JoinHandle`, and `spawn_blocking`. * [Async vs Sync](/11-async/13-async-vs-sync/) — choosing a scheduler flavor and when to go async at all. * [Understanding Cargo](/01-getting-started/03-cargo-basics/) — `cargo add`, features, and `Cargo.toml`. * [Basics](/02-basics/): Rust fundamentals if you need a refresher. * Next section: [Modules & Packages](/12-modules-packages/) — organizing crates and modules. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: First Tokio program [Section titled “Exercise 1: First Tokio program”](#exercise-1-first-tokio-program) **Difficulty:** Easy **Objective:** Wire up Tokio from scratch and confirm an async function runs. **Instructions:** 1. Run `cargo new tokio_hello` and `cargo add tokio --features full`. 2. Write an `async fn greet(name: &str) -> String` that returns `"Hello, {name}!"`. 3. In an `async` `main`, `.await` it and print the result. 4. Make `main` use the Tokio runtime so it compiles and runs. Solution src/main.rs ```rust 1 #[tokio::main] 2 async fn main() { 3 let message = greet("Ada").await; 4 println!("{message}"); 5 } 6 7 async fn greet(name: &str) -> String { 8 format!("Hello, {name}!") 9 } ``` Output: ```plaintext 1 Hello, Ada! ``` `#[tokio::main]` builds the runtime and drives the async body; without it the `async fn main` would fail to compile with `error[E0752]`. ### Exercise 2: Bridge sync code into async [Section titled “Exercise 2: Bridge sync code into async”](#exercise-2-bridge-sync-code-into-async) **Difficulty:** Medium **Objective:** Run an async function from a **synchronous** `main` by building the runtime by hand. **Instructions:** 1. Keep `main` as a plain (non-async) `fn`. 2. Write `fn get_greeting(name: &str) -> String` that builds a runtime, runs an `async` helper to completion, and returns the `String`. 3. Call it from the synchronous `main` and print the result. 4. Use `tokio::runtime::Runtime::new()` and `block_on`. Solution src/main.rs ```rust 1 use tokio::runtime::Runtime; 2 3 /// A synchronous function that needs one async result. 4 fn get_greeting(name: &str) -> String { 5 let rt = Runtime::new().expect("failed to create runtime"); 6 rt.block_on(async { build_greeting(name).await }) 7 } 8 9 async fn build_greeting(name: &str) -> String { 10 format!("Hello, {name}!") 11 } 12 13 fn main() { 14 // main itself is fully synchronous. 15 let msg = get_greeting("Ada"); 16 println!("{msg}"); 17 } ``` Output: ```plaintext 1 Hello, Ada! ``` `block_on` is the bridge from sync to async. Note it is called from a *synchronous* context — calling it from inside async code would panic (see Pitfall 3). ### Exercise 3: Configure a custom runtime and run an async test [Section titled “Exercise 3: Configure a custom runtime and run an async test”](#exercise-3-configure-a-custom-runtime-and-run-an-async-test) **Difficulty:** Medium–Hard **Objective:** Build a `current_thread` runtime with custom options via `Builder`, reuse it for several operations, and verify behavior with `#[tokio::test]`. **Instructions:** 1. Write `async fn square(n: u64) -> u64`. 2. In `main`, build a **current-thread** runtime with `enable_all()` and `max_blocking_threads(8)`, then loop over `1..=4` calling `block_on(square(n))` and printing each result. Build the runtime once, outside the loop. 3. Add a `#[tokio::test]` asserting `square(9).await == 81`. Solution src/main.rs ```rust 1 use tokio::runtime::Builder; 2 3 async fn square(n: u64) -> u64 { 4 n * n 5 } 6 7 fn main() { 8 // Build ONE runtime and reuse it for every operation. 9 let rt = Builder::new_current_thread() 10 .enable_all() 11 .max_blocking_threads(8) 12 .build() 13 .unwrap(); 14 15 for n in 1..=4 { 16 let result = rt.block_on(square(n)); 17 println!("{n}^2 = {result}"); 18 } 19 } 20 21 #[cfg(test)] 22 mod tests { 23 use super::*; 24 25 #[tokio::test] 26 async fn squares_correctly() { 27 assert_eq!(square(9).await, 81); 28 } 29 } ``` `cargo run` output: ```plaintext 1 1^2 = 1 2 2^2 = 4 3 3^2 = 9 4 4^2 = 16 ``` `cargo test` output: ```plaintext 1 running 1 test 2 test tests::squares_correctly ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` Building the runtime once (rather than per loop iteration) avoids repeatedly allocating threads and drivers, the practice from [Best Practices](#best-practices). `#[tokio::test]` supplies a fresh runtime for the test so you do not build one yourself there. # Async Functions and Async Blocks > Calling a TypeScript async function starts work immediately; Rust's async fn just builds a lazy future. Learn capturing, async move blocks, and lifetimes. In TypeScript, `async function` is the workhorse of asynchronous code: call it and the body starts running immediately. Rust’s `async fn` looks almost identical, but it behaves differently in one important way: calling it runs *nothing*. This page covers how `async fn` and `async {}` blocks work, how they capture data, what they actually return, and the lifetime rules that trip up every TypeScript/JavaScript developer. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) An **`async fn`** in Rust is a function whose body is compiled into a state machine that implements the `Future` trait. Calling an `async fn` does **not** run the body. It builds a `Future` value that does nothing until you `.await` it (or hand it to a runtime). An **`async {}` block** is the same idea inline: an expression that evaluates to an anonymous `Future`. Understanding *capturing* (what data the future holds) and *lifetimes* (how long that data must live) is the key to writing async Rust that compiles. > **Note:** This page focuses on the *shape* of async functions and blocks. For *why* futures are lazy, see [Promises vs Futures](/11-async/00-promises-vs-futures/); for the `.await` syntax and `?` error handling, see [async/await](/11-async/01-async-await/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Here is a typical async data layer in TypeScript: small async functions, one that composes others, and an inline async arrow function. data-layer.ts ```typescript 1 interface User { 2 id: number; 3 name: string; 4 } 5 6 interface Profile { 7 user: User; 8 postCount: number; 9 } 10 11 // A basic async function. Calling it STARTS the work immediately. 12 async function fetchUser(id: number): Promise<User> { 13 const res = await fetch(`/api/users/${id}`); 14 return res.json(); 15 } 16 17 async function fetchPostCount(id: number): Promise<number> { 18 const res = await fetch(`/api/users/${id}/posts/count`); 19 const { count } = await res.json(); 20 return count; 21 } 22 23 // An async function that COMPOSES other async functions. 24 async function buildProfile(id: number): Promise<Profile> { 25 // Promise.all runs both concurrently. 26 const [user, postCount] = await Promise.all([ 27 fetchUser(id), 28 fetchPostCount(id), 29 ]); 30 return { user, postCount }; 31 } 32 33 // An inline async arrow function that CAPTURES `name` from its scope. 34 const makeGreeter = (name: string) => async (): Promise<string> => { 35 return `Hello, ${name}!`; 36 }; 37 38 const greet = makeGreeter("Ada"); 39 greet().then(console.log); // "Hello, Ada!" ``` Two things to internalize before we cross over to Rust: 1. **Calling `fetchUser(id)` starts the network request right away.** The returned `Promise` is already “hot”: it is running in the background. 2. **The arrow function captures `name` by reference** to the closure environment. JavaScript’s garbage collector keeps `name` alive as long as the closure exists. You never think about it. Rust changes *both* of these facts. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 use std::future::Future; 2 3 // 1. A basic async fn. Calling it builds a Future; the body does NOT run yet. 4 async fn fetch_count() -> u32 { 5 // pretend this hits the network 6 tokio::time::sleep(std::time::Duration::from_millis(10)).await; 7 42 8 } 9 10 // 2. An async fn with parameters and a Result return type. 11 async fn parse_port(s: &str) -> Result<u16, std::num::ParseIntError> { 12 let n: u16 = s.parse()?; 13 Ok(n) 14 } 15 16 // 3. Returning a future explicitly via `-> impl Future`. 17 // `async fn double_async` desugars to almost exactly this. 18 fn double_async(x: u32) -> impl Future<Output = u32> { 19 async move { x * 2 } 20 } 21 22 // 4. Capturing: an `async move` block takes OWNERSHIP of `name`. 23 async fn build_greeting(name: String) -> String { 24 let block = async move { 25 // `name` is moved INTO the async block and lives inside the future. 26 format!("Hello, {name}!") 27 }; 28 block.await 29 } 30 31 // 5. Lifetimes: the returned future borrows `data`, so it cannot outlive it. 32 async fn first_word(data: &str) -> &str { 33 data.split(' ').next().unwrap_or("") 34 } 35 36 #[tokio::main] 37 async fn main() { 38 let count = fetch_count().await; 39 println!("count = {count}"); 40 41 match parse_port("8080").await { 42 Ok(p) => println!("port = {p}"), 43 Err(e) => println!("bad port: {e}"), 44 } 45 46 let d = double_async(21).await; 47 println!("double = {d}"); 48 49 let greeting = build_greeting(String::from("Ada")).await; 50 println!("{greeting}"); 51 52 let sentence = String::from("rust is fun"); 53 let w = first_word(&sentence).await; 54 println!("first word = {w}"); 55 } ``` Real output (`cargo run`, Rust 1.96.0): ```text 1 count = 42 2 port = 8080 3 double = 42 4 Hello, Ada! 5 first word = rust ``` > **Note:** The examples here use [Tokio](/11-async/02-tokio-intro/) only to *run* the futures (the `#[tokio::main]` attribute and `tokio::time::sleep`). The `async fn` / `async {}` mechanics themselves are part of the language and need no crate. See [Tokio Setup](/11-async/03-tokio-setup/) for the `Cargo.toml`. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `async fn` is sugar for “a function that returns a future” [Section titled “async fn is sugar for “a function that returns a future””](#async-fn-is-sugar-for-a-function-that-returns-a-future) When you write: ```rust 1 async fn double_async(x: u32) -> u32 { 2 x * 2 3 } ``` the compiler rewrites it to roughly: ```rust 1 use std::future::Future; 2 3 fn double_async(x: u32) -> impl Future<Output = u32> { 4 async move { x * 2 } 5 } ``` The declared return type (`u32`) becomes the future’s **`Output`** type. The `-> impl Future<Output = u32>` form means “this returns *some* concrete type that implements `Future` and yields a `u32`” — the compiler generates an anonymous state-machine type for you. These two definitions are interchangeable; both compile and both print `2`: ```rust 1 use std::future::Future; 2 3 async fn add_one_sugar(x: i32) -> i32 { x + 1 } 4 5 fn add_one_desugar(x: i32) -> impl Future<Output = i32> { 6 async move { x + 1 } 7 } 8 9 #[tokio::main] 10 async fn main() { 11 println!("{}", add_one_sugar(1).await); // 2 12 println!("{}", add_one_desugar(1).await); // 2 13 } ``` Real output: ```text 1 2 2 2 ``` > **Tip:** Use the plain `async fn` form 99% of the time. Reach for the explicit `-> impl Future` form only when you need to add bounds (like `+ Send` or a lifetime) that the sugar cannot express, or when the function body is *not itself* async but returns a future built elsewhere. ### Calling an `async fn` runs nothing [Section titled “Calling an async fn runs nothing”](#calling-an-async-fn-runs-nothing) This is the single most important difference from TypeScript. In JavaScript, `fetchUser(1)` *starts* the request. In Rust, `fetch_count()` just *constructs a value*: ```rust 1 async fn do_work() -> u32 { 2 println!("working..."); 3 42 4 } 5 6 #[tokio::main] 7 async fn main() { 8 // Creating the future does NOT run the body. 9 let fut = do_work(); 10 println!("future created, body has not run yet"); 11 let result = fut.await; // NOW the body runs. 12 println!("result = {result}"); 13 } ``` Real output: ```text 1 future created, body has not run yet 2 working... 3 result = 42 ``` Notice `working...` prints *after* `future created...`, even though `do_work()` was called first. The body of an `async fn` only executes when the future is `.await`ed (or spawned onto a runtime, which polls it). This is covered in depth in [Promises vs Futures](/11-async/00-promises-vs-futures/). ### `async {}` blocks: inline futures [Section titled “async {} blocks: inline futures”](#async--blocks-inline-futures) An `async {}` block is an expression that evaluates to an anonymous future, just like an `async fn` but without a name. The block’s final expression is the future’s `Output`: ```rust 1 let fut = async { 1 + 2 }; // type: impl Future<Output = i32> 2 let three = fut.await; // 3 ``` You will use async blocks constantly: to spawn ad-hoc work, to build a future inside a `match` arm, or to wrap a sequence of `.await`s you want to pass to `tokio::select!` or `join!` (see [select/join](/11-async/07-select-join/)). ### Capturing: `async {}` vs `async move {}` [Section titled “Capturing: async {} vs async move {}”](#capturing-async--vs-async-move-) A bare `async {}` block captures variables from the enclosing scope **by reference** (the least it needs), exactly like a closure does. An `async move {}` block captures **by value** (moves ownership in): ```rust 1 #[tokio::main] 2 async fn main() { 3 let name = String::from("Grace"); 4 5 // Borrows `name` by default — fine because we await before `name` is dropped. 6 let borrows = async { 7 println!("borrowed: {}", name.len()); 8 }; 9 borrows.await; 10 println!("still usable here: {name}"); 11 12 // `async move` takes ownership of `name`. 13 let owns = async move { 14 format!("owned: {name}") 15 }; 16 println!("{}", owns.await); 17 // `name` is no longer accessible here — it was moved into `owns`. 18 } ``` Real output: ```text 1 borrowed: 5 2 still usable here: Grace 3 owned: Grace ``` The rule of thumb mirrors closures (see [Closures](/03-functions/) if you have read Section 03): use `async move` whenever the future may outlive the current scope, which is *always* the case when you hand it to `tokio::spawn` or store it somewhere. ### Lifetimes in async functions [Section titled “Lifetimes in async functions”](#lifetimes-in-async-functions) When an `async fn` takes a reference parameter and the future holds onto it, the future is implicitly bounded by that reference’s lifetime. Consider: ```rust 1 async fn first_word(data: &str) -> &str { 2 data.split(' ').next().unwrap_or("") 3 } ``` This desugars (conceptually) to: ```rust 1 use std::future::Future; 2 3 fn first_word<'a>(data: &'a str) -> impl Future<Output = &'a str> + 'a { 4 async move { data.split(' ').next().unwrap_or("") } 5 } ``` The returned future borrows `data`, so the future **cannot outlive** `data`. You must `.await` it (and finish using the result) before `data` is dropped. This is why holding a future around longer than its borrowed inputs is a compile error, and why moving owned data into the future (the `String` version) is the fix when a task needs to live independently. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript `async function` | Rust `async fn` | | ------------------------- | --------------------------------------- | ------------------------------------------------------------------------- | | What calling it does | **Starts** the work immediately (eager) | **Builds a future**; body runs on `.await` (lazy) | | Return type | Always `Promise<T>` | `impl Future<Output = T>` (anonymous type) | | Needs a runtime? | No: the JS event loop is built in | **Yes**: futures need an executor like Tokio | | Capturing variables | By reference, GC keeps them alive | By borrow (`async {}`) or by move (`async move {}`) | | Lifetime of captured refs | Irrelevant (garbage collected) | Future must not outlive borrowed data | | Concurrency primitive | `Promise.all` / `Promise.race` | `join!` / `tokio::select!` (see [select/join](/11-async/07-select-join/)) | | Cancellation | Generally not cancellable once started | Drop the future to cancel it (it never ran past the last `.await`) | The deepest conceptual gap is **laziness plus runtime**. A TypeScript developer is used to “call it and forget it — the event loop does the rest.” In Rust there is no ambient event loop; a future is an inert value until something polls it. Forgetting to `.await` is a common bug, and the compiler warns you about it (see Pitfalls). > **Note:** Because Rust futures are lazy and droppable, **cancellation is built in for free**: dropping a future before it completes simply stops it. In JavaScript you need `AbortController` plumbing to approximate this. See [Concurrency](/11-async/10-concurrency/) for cancellation patterns. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting to `.await` (the future never runs) [Section titled “Pitfall 1: Forgetting to .await (the future never runs)”](#pitfall-1-forgetting-to-await-the-future-never-runs) Calling an `async fn` and discarding the result silently does nothing, but the compiler catches it with a `must_use` warning: ```rust 1 async fn do_work() -> u32 { 2 42 3 } 4 5 #[tokio::main] 6 async fn main() { 7 do_work(); // future created but never awaited — body never runs 8 println!("done"); 9 } ``` Real `cargo build` warning: ```text 1 warning: unused implementer of `Future` that must be used 2 --> src/main.rs:7:5 3 | 4 7 | do_work(); // future created but never awaited — body never runs 5 | ^^^^^^^^^ 6 | 7 = note: futures do nothing unless you `.await` or poll them 8 = note: `#[warn(unused_must_use)]` on by default ``` The fix is to `.await` it (or `tokio::spawn` it). The note — *“futures do nothing unless you `.await` or poll them”* — is the laziness rule stated by the compiler itself. ### Pitfall 2: A spawned task borrowing local data (`'static` required) [Section titled “Pitfall 2: A spawned task borrowing local data ('static required)”](#pitfall-2-a-spawned-task-borrowing-local-data-static-required) `tokio::spawn` requires its future to be `'static`: it may run after the current function returns, so it cannot borrow local variables. This is the most common lifetime error TypeScript developers hit, because in JavaScript closures keep data alive automatically. ```rust 1 async fn print_len(data: &str) { 2 println!("len = {}", data.len()); 3 } 4 5 #[tokio::main] 6 async fn main() { 7 let owned = String::from("hello"); 8 // does not compile (error[E0597]): `owned` does not live long enough 9 tokio::spawn(print_len(&owned)); 10 } ``` Real `cargo build` error: ```text 1 error[E0597]: `owned` does not live long enough 2 --> src/main.rs:9:28 3 | 4 7 | let owned = String::from("hello"); 5 | ----- binding `owned` declared here 6 8 | // does not compile (error[E0597]): `owned` does not live long enough 7 9 | tokio::spawn(print_len(&owned)); 8 | -----------------------^^^^^^-- 9 | | | 10 | | borrowed value does not live long enough 11 | argument requires that `owned` is borrowed for `'static` 12 10 | } 13 | - `owned` dropped here while still borrowed ``` The fix is to give the task **owned** data so its future is `'static`: ```rust 1 async fn print_len(data: String) { 2 println!("len = {}", data.len()); 3 } 4 5 #[tokio::main] 6 async fn main() { 7 let owned = String::from("hello"); 8 let handle = tokio::spawn(print_len(owned)); // ownership moved in 9 handle.await.unwrap(); 10 } ``` Real output: ```text 1 len = 5 ``` For sharing the *same* data across multiple tasks instead of moving it, see [Arc + Mutex](/11-async/12-arc-mutex-pattern/). ### Pitfall 3: Using `?` inside an async block whose `Output` is not a `Result` [Section titled “Pitfall 3: Using ? inside an async block whose Output is not a Result”](#pitfall-3-using--inside-an-async-block-whose-output-is-not-a-result) The `?` operator needs the surrounding async block to return `Result` (or `Option`). If the block’s value is a bare `u16`, you get a type error: ```rust 1 #[tokio::main] 2 async fn main() { 3 let fut = async { 4 let n: u16 = "8080".parse()?; // does not compile (error[E0277]) 5 n 6 }; 7 let _ = fut.await; 8 } ``` Real `cargo build` error: ```text 1 error[E0277]: the `?` operator can only be used in an async block that returns `Result` or `Option` (or another type that implements `FromResidual`) 2 --> src/main.rs:4:36 3 | 4 3 | let fut = async { 5 | ----- this function should return `Result` or `Option` to accept `?` 6 4 | let n: u16 = "8080".parse()?; // does not compile (error[E0277]) 7 | ^ cannot use the `?` operator in an async block that returns `u16` ``` The fix is to make the block yield a `Result`, annotating the type so inference knows the error variant: ```rust 1 #[tokio::main] 2 async fn main() { 3 let fut = async { 4 let n: u16 = "8080".parse()?; 5 Ok::<u16, std::num::ParseIntError>(n) 6 }; 7 match fut.await { 8 Ok(n) => println!("port = {n}"), 9 Err(e) => println!("bad: {e}"), 10 } 11 } ``` Real output: ```text 1 port = 8080 ``` > **Tip:** Inside an `async fn` you rarely hit this, because the function’s declared return type (e.g. `-> Result<u16, ParseIntError>`) gives `?` a target. The annotation trick is only needed for *standalone async blocks*. More on `?` in [async/await](/11-async/01-async-await/). *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Prefer `async fn` over `-> impl Future`.** The sugar is clearer and produces the same machine code. Drop to the explicit form only to add bounds (`+ Send`, lifetimes) the sugar cannot express. * **Use `async move` when handing a future to `spawn` or storing it.** If the future may outlive the current scope, it must own its data. Moving owned values in is almost always what you want for spawned tasks. * **Pass owned data (`String`, `Vec<T>`) to `'static` tasks; share with `Arc` when many tasks need the same value.** See [Arc + Mutex](/11-async/12-arc-mutex-pattern/). * **Keep `async fn` bodies focused on `.await`-driven I/O.** CPU-heavy loops inside an async fn block the executor thread; use `spawn_blocking` (see [Spawning Tasks](/11-async/09-spawning-tasks/)) or rethink with threads (see [Async vs Sync](/11-async/13-async-vs-sync/)). * **Let lifetimes guide you.** If the compiler says a future does not live long enough, the question is “does this task need to outlive the borrowed data?” If yes, switch to owned data or `Arc`; if no, ensure you `.await` before the data is dropped. * **Do not annotate the return type as `Future` by hand unless you must.** `async fn name() -> T` is the idiom; spelling out `Box<dyn Future<...>>` is only needed for `dyn` dispatch (see [Async Traits](/11-async/05-async-trait/)). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small profile service: independent `async fn`s for each I/O step, composed by a higher-level `async fn` that drives them **concurrently** with `join!`. This is the Rust analogue of the `buildProfile` + `Promise.all` pattern from the TypeScript example. (The network calls are simulated with `sleep` so the snippet runs without a server.) ```rust 1 use std::time::Duration; 2 use tokio::time::sleep; 3 4 #[derive(Debug)] 5 struct User { 6 id: u32, 7 name: String, 8 } 9 10 #[derive(Debug)] 11 struct Profile { 12 user: User, 13 post_count: usize, 14 } 15 16 // Each async fn is an independent I/O step (here simulated with sleep). 17 async fn fetch_user(id: u32) -> User { 18 sleep(Duration::from_millis(50)).await; // pretend: HTTP GET /users/{id} 19 User { id, name: format!("user{id}") } 20 } 21 22 async fn fetch_post_count(id: u32) -> usize { 23 sleep(Duration::from_millis(50)).await; // pretend: HTTP GET /users/{id}/posts 24 (id as usize) * 3 25 } 26 27 // Compose async fns. `build_profile` is itself an async fn — its returned 28 // future drives the two inner futures CONCURRENTLY via join!. 29 async fn build_profile(id: u32) -> Profile { 30 let (user, post_count) = tokio::join!(fetch_user(id), fetch_post_count(id)); 31 Profile { user, post_count } 32 } 33 34 #[tokio::main] 35 async fn main() { 36 let start = std::time::Instant::now(); 37 let profile = build_profile(7).await; 38 println!("{profile:?}"); 39 // Two 50ms steps ran concurrently, so total is ~50ms, not ~100ms. 40 println!("elapsed: {} ms (concurrent)", start.elapsed().as_millis()); 41 } ``` Real output (timing will vary slightly): ```text 1 Profile { user: User { id: 7, name: "user7" }, post_count: 21 } 2 elapsed: 51 ms (concurrent) ``` The two `fetch_*` futures are constructed *lazily* and only start making progress when `join!` polls them. Yet because `join!` polls both, they overlap, finishing in \~50ms rather than \~100ms. This is the same concurrency `Promise.all` gives you, but achieved by *one* task polling two futures, not by two background promises. See [select/join](/11-async/07-select-join/) for the full toolkit. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [The Async Book — `async`/`.await`](https://rust-lang.github.io/async-book/03_async_await/01_chapter.html): official explanation of the desugaring and state machine. * [`std::future::Future`](https://doc.rust-lang.org/std/future/trait.Future.html): the trait every `async fn` returns. * [Rust Reference — Async blocks and functions](https://doc.rust-lang.org/reference/expressions/block-expr.html#async-blocks): the precise capturing and lifetime rules. * [Tokio Tutorial — Spawning](https://tokio.rs/tokio/tutorial/spawning): why spawned tasks need `'static`. * Sibling pages in this section: * [Promises vs Futures](/11-async/00-promises-vs-futures/): eager vs lazy, the core mental shift. * [async/await](/11-async/01-async-await/): the `.await` operator and `?` error handling. * [Tokio Intro](/11-async/02-tokio-intro/) and [Tokio Setup](/11-async/03-tokio-setup/): getting a runtime. * [Async Traits](/11-async/05-async-trait/): `async fn` in traits and `dyn` dispatch. * [Spawning Tasks](/11-async/09-spawning-tasks/): `tokio::spawn`, `JoinHandle`, `spawn_blocking`. * [select/join](/11-async/07-select-join/): concurrent awaiting. * [Arc + Mutex](/11-async/12-arc-mutex-pattern/): sharing data across `'static` tasks. * Related earlier sections: [Functions](/03-functions/), [Ownership](/05-ownership/), [Error Handling](/08-error-handling/). * Next up after async: [Modules and Packages](/12-modules-packages/). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Convert a sync function to async [Section titled “Exercise 1: Convert a sync function to async”](#exercise-1-convert-a-sync-function-to-async) **Difficulty:** Easy **Objective:** Get comfortable writing an `async fn` and `.await`ing it. **Instructions:** Write an `async fn fetch_temperature(city: &str) -> f64` that “looks up” a temperature (simulate the I/O with `tokio::time::sleep` for 20ms, then return a hard-coded value per city). Call it from `#[tokio::main] async fn main` and print the result for `"Cairo"`. Solution ```rust 1 use std::time::Duration; 2 use tokio::time::sleep; 3 4 async fn fetch_temperature(city: &str) -> f64 { 5 sleep(Duration::from_millis(20)).await; // simulated network call 6 match city { 7 "Berlin" => 18.5, 8 "Cairo" => 31.0, 9 _ => 20.0, 10 } 11 } 12 13 #[tokio::main] 14 async fn main() { 15 let t = fetch_temperature("Cairo").await; 16 println!("Cairo: {t} C"); 17 } ``` Real output: ```text 1 Cairo: 31 C ``` ### Exercise 2: An async function that returns a borrow [Section titled “Exercise 2: An async function that returns a borrow”](#exercise-2-an-async-function-that-returns-a-borrow) **Difficulty:** Medium **Objective:** See how a borrowed return value ties the future’s lifetime to its input. **Instructions:** Write an `async fn longest_line(text: &str) -> &str` that returns the longest line of `text` (split on `\n`). The returned `&str` must borrow from `text`. Call it on a multi-line `String` and print the result. Observe that you must keep the `String` alive until after the `.await`. Solution ```rust 1 // Returns a slice borrowed from the input; the future's lifetime is tied to `text`. 2 async fn longest_line(text: &str) -> &str { 3 text.lines().max_by_key(|line| line.len()).unwrap_or("") 4 } 5 6 #[tokio::main] 7 async fn main() { 8 let doc = String::from("short\na much longer line\nmid"); 9 let line = longest_line(&doc).await; 10 println!("longest: {line:?}"); 11 } ``` Real output: ```text 1 longest: "a much longer line" ``` > The future returned by `longest_line(&doc)` borrows `doc`. Because we `.await` it (and finish using `line`) before `doc` goes out of scope, the borrow checker is satisfied. ### Exercise 3: Fix a spawn lifetime error and run two tasks concurrently [Section titled “Exercise 3: Fix a spawn lifetime error and run two tasks concurrently”](#exercise-3-fix-a-spawn-lifetime-error-and-run-two-tasks-concurrently) **Difficulty:** Hard **Objective:** Resolve the `'static` requirement of `tokio::spawn` and combine results with `join!`. **Instructions:** You have an `async fn process(label: String, ms: u64) -> String` that sleeps for `ms` milliseconds and returns `"<label> done in <ms>ms"`. Spawn two tasks (labels `"A"` at 30ms and `"B"` at 10ms), then await both with `tokio::join!` and print each result. Make sure the futures are `'static` (hint: move owned `String`s in — do not pass borrows). Solution ```rust 1 use std::time::Duration; 2 use tokio::time::sleep; 3 4 async fn process(label: String, ms: u64) -> String { 5 sleep(Duration::from_millis(ms)).await; 6 format!("{label} done in {ms}ms") 7 } 8 9 #[tokio::main] 10 async fn main() { 11 // Move owned Strings into each task so the futures are 'static. 12 let h1 = tokio::spawn(process(String::from("A"), 30)); 13 let h2 = tokio::spawn(process(String::from("B"), 10)); 14 15 // join! awaits both JoinHandles concurrently. 16 let (r1, r2) = tokio::join!(h1, h2); 17 println!("{}", r1.unwrap()); 18 println!("{}", r2.unwrap()); 19 } ``` Real output: ```text 1 A done in 30ms 2 B done in 10ms ``` > Passing owned `String`s (not `&str`) makes each future `'static`, satisfying `tokio::spawn`. The two tasks run concurrently; `join!` waits for both `JoinHandle`s and yields their results. See [Spawning Tasks](/11-async/09-spawning-tasks/) and [select/join](/11-async/07-select-join/) for more. # Async Functions in Traits > Async fn in traits is stable since Rust 1.75, no crate needed, but it is not dyn-compatible. When to reach for async-trait, plus the RPITIT desugaring. In TypeScript, putting an `async` method on an interface is unremarkable. An interface method that returns `Promise<T>` is just a method that returns an object. Rust took years to reach the same place, and the result has a few sharp edges that every TypeScript/JavaScript developer hits. This page explains **native `async fn` in traits** (stable since Rust 1.75, no crate required), when you still reach for the **`async-trait`** crate, and the desugaring (**RPITIT**) that explains why. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) You can write `async fn` directly in a **trait** (Rust’s version of an interface) since Rust 1.75; no external crate needed. The catch: a trait with a native `async fn` is **not `dyn`-compatible**, so you cannot put it behind `Box<dyn Trait>`. When you need that (heterogeneous collections, plugin systems, dependency injection), you reach for the `async-trait` crate, which boxes the returned future. This is the opposite of TypeScript, where async interface methods “just work” behind any reference because every object is already heap-allocated and dynamically dispatched. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript, an interface with `async` methods is completely ordinary. The methods just return `Promise<T>`, and you can use the interface as a type, store implementations in arrays, and pass them around freely. ```typescript 1 // A repository interface with async methods — totally routine in TypeScript. 2 interface UserRepository { 3 find(id: number): Promise<User | null>; 4 save(user: User): Promise<void>; 5 } 6 7 interface User { 8 id: number; 9 name: string; 10 } 11 12 class InMemoryRepo implements UserRepository { 13 private users = new Map<number, User>(); 14 15 async find(id: number): Promise<User | null> { 16 return this.users.get(id) ?? null; 17 } 18 19 async save(user: User): Promise<void> { 20 this.users.set(user.id, user); 21 } 22 } 23 24 class SqlRepo implements UserRepository { 25 async find(id: number): Promise<User | null> { 26 // imagine: await this.pool.query(...) 27 return { id, name: `db-user-${id}` }; 28 } 29 async save(_user: User): Promise<void> {} 30 } 31 32 // Store DIFFERENT implementations behind the interface type — no ceremony. 33 const repos: UserRepository[] = [new InMemoryRepo(), new SqlRepo()]; 34 35 // Pass the interface around; the caller never knows the concrete class. 36 async function rename(repo: UserRepository, id: number, name: string) { 37 const user = await repo.find(id); 38 if (!user) throw new Error("not found"); 39 user.name = name; 40 await repo.save(user); 41 return user; 42 } ``` Two things are happening that you never think about: 1. `UserRepository[]` holds different concrete classes side by side — **dynamic dispatch** through the prototype chain. 2. Every method returns a `Promise`, which is a heap object the engine manages. Rust supports both ideas, but it makes the trade-offs explicit. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The idiomatic, **crate-free** way to write an async method on a trait: ```rust 1 // Native async fn in traits — stable since Rust 1.75, NO crate needed. 2 use std::collections::HashMap; 3 4 trait DataStore { 5 async fn get(&self, key: &str) -> Option<String>; 6 async fn set(&mut self, key: String, value: String); 7 } 8 9 struct MemoryStore { 10 data: HashMap<String, String>, 11 } 12 13 impl DataStore for MemoryStore { 14 async fn get(&self, key: &str) -> Option<String> { 15 self.data.get(key).cloned() 16 } 17 18 async fn set(&mut self, key: String, value: String) { 19 self.data.insert(key, value); 20 } 21 } 22 23 #[tokio::main] 24 async fn main() { 25 let mut store = MemoryStore { data: HashMap::new() }; 26 store.set("greeting".to_string(), "hello".to_string()).await; 27 let value = store.get("greeting").await; 28 println!("{value:?}"); 29 } ``` Running it prints the real output: ```text 1 Some("hello") ``` > **Note:** This requires no `async-trait` in `Cargo.toml`. The only dependency here is Tokio, which provides the **runtime** that actually drives the futures. Recall that [Rust futures are lazy](/11-async/00-promises-vs-futures/) and do nothing until polled. This compiles and runs on stable Rust. But notice we called `store.get(...)` on a **concrete** `MemoryStore`, not through a `dyn DataStore`. That distinction is the whole story of this page. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `async fn` in a trait is real, and crate-free [Section titled “async fn in a trait is real, and crate-free”](#async-fn-in-a-trait-is-real-and-crate-free) Before Rust 1.75, writing `async fn` in a trait was a compile error, and the entire ecosystem used the `async-trait` macro. Since 1.75, this is built into the language. On the repository’s [pinned verification baseline](/00-introduction/05-version-policy/) and the 2024 edition, the example above needs nothing but the trait and the impl. Line by line: * `trait DataStore { async fn get(...) -> Option<String>; }` declares an async method. The trait is Rust’s analog of a TypeScript `interface`. (See [Traits](/09-generics-traits/03-traits/).) * `impl DataStore for MemoryStore { async fn get(...) {...} }` provides the body. Just like the TypeScript class implementing the interface. * `store.get("greeting").await` — calling the method returns a **future**, and `.await` drives it to completion. ### What `async fn` desugars to: RPITIT [Section titled “What async fn desugars to: RPITIT”](#what-async-fn-desugars-to-rpitit) An `async fn` in a trait is **syntax sugar**. The compiler rewrites it into a normal method that returns `impl Future`. This feature is called **RPITIT** — *return-position `impl Trait` in trait*. These two trait definitions are equivalent: ```rust 1 // What `async fn` in a trait desugars to: RPITIT (return-position impl Trait in trait). 2 use std::future::Future; 3 4 // These two trait definitions are equivalent to the compiler. 5 trait FetcherSugar { 6 async fn fetch(&self, url: &str) -> String; 7 } 8 9 trait FetcherDesugared { 10 // `async fn` is sugar for a method returning `impl Future`. 11 fn fetch(&self, url: &str) -> impl Future<Output = String>; 12 } 13 14 struct StubFetcher; 15 16 // Implement the desugared form by hand: return an async block. 17 impl FetcherDesugared for StubFetcher { 18 fn fetch(&self, url: &str) -> impl Future<Output = String> { 19 let url = url.to_string(); 20 async move { format!("body of {url}") } 21 } 22 } 23 24 // You can also satisfy the sugared trait with plain `async fn`. 25 impl FetcherSugar for StubFetcher { 26 async fn fetch(&self, url: &str) -> String { 27 format!("body of {url}") 28 } 29 } 30 31 #[tokio::main] 32 async fn main() { 33 let f = StubFetcher; 34 let a = FetcherDesugared::fetch(&f, "https://a.example").await; 35 let b = FetcherSugar::fetch(&f, "https://b.example").await; 36 println!("{a}"); 37 println!("{b}"); 38 } ``` Real output: ```text 1 body of https://a.example 2 body of https://b.example ``` This desugaring is exactly why `dyn` does not work (next section). The returned future type is **anonymous** and **different for every impl**: there is no single, named type the compiler can put in a vtable. Contrast this with TypeScript: `Promise<T>` is one concrete runtime type regardless of which method produced it, so an interface array `UserRepository[]` is trivial. > **Tip:** You can mix the two forms freely. If you need the `impl Future` signature for some reason (for example, to add a `+ Send` bound — see Common Pitfalls), write the desugared form. Otherwise, `async fn` reads better. ### Why does the compiler monomorphize this? [Section titled “Why does the compiler monomorphize this?”](#why-does-the-compiler-monomorphize-this) When you call the method through a concrete type or a generic type parameter (`<C: DataStore>`), the compiler knows the exact future type and **monomorphizes** the code: generates a specialized copy, zero-cost, no allocation. This is the same machinery as [generics](/09-generics-traits/00-generic-functions/). TypeScript erases generics at runtime; Rust specializes them at compile time. The price is that monomorphization needs a *concrete* type, which `dyn` deliberately throws away. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript | Rust | | ---------------------------- | ----------------------------------------------------- | ----------------------------------------------------- | | Async interface/trait method | Returns `Promise<T>`, always works | `async fn` in trait, stable since 1.75 | | Return type | `Promise<T>` — one concrete runtime type | Anonymous `impl Future` — different per impl | | Behind `interface`/`dyn` | Free (everything is a heap object + dynamic dispatch) | **Not allowed** for native async trait methods | | Static dispatch | Not really a concept (always dynamic) | Default; monomorphized, zero-cost | | Heterogeneous collection | `UserRepository[]` just works | Needs `Vec<Box<dyn Trait>>` + `async-trait` crate | | Eager vs lazy | Promise **starts running** when created | Future does **nothing** until `.await`/polled | | Cost of dynamic dispatch | Always paid (it is the only mode) | Opt-in; `async-trait` adds a heap allocation per call | The headline difference: **TypeScript only has dynamic dispatch, so async interface methods are free. Rust defaults to static dispatch, which is free *only* when the concrete type is known, and `dyn` (the dynamic mode) is where async traits get awkward.** > **Warning:** Do not assume `Vec<Box<dyn MyAsyncTrait>>` will compile with a native `async fn`. It will not. See the next section for the exact error and the fix. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: `Box<dyn Trait>` with a native async method [Section titled “Pitfall 1: Box\<dyn Trait> with a native async method”](#pitfall-1-boxdyn-trait-with-a-native-async-method) This is the single most common surprise. A TypeScript developer reaches for `Box<dyn Trait>` expecting it to behave like a `UserRepository[]` element: ```rust 1 // does not compile (error[E0038]: the trait `Notifier` is not dyn compatible) 2 trait Notifier { 3 async fn notify(&self, msg: &str); 4 } 5 6 struct EmailNotifier; 7 8 impl Notifier for EmailNotifier { 9 async fn notify(&self, msg: &str) { 10 println!("email: {msg}"); 11 } 12 } 13 14 fn make_notifier() -> Box<dyn Notifier> { 15 Box::new(EmailNotifier) 16 } ``` The real compiler error: ```text 1 error[E0038]: the trait `Notifier` is not dyn compatible 2 --> src/main.rs:14:27 3 | 4 14 | fn make_notifier() -> Box<dyn Notifier> { 5 | ^^^^^^^^^^^^ `Notifier` is not dyn compatible 6 | 7 note: for a trait to be dyn compatible it needs to allow building a vtable 8 for more information, visit <https://doc.rust-lang.org/reference/items/traits.html#dyn-compatibility> 9 --> src/main.rs:3:14 10 | 11 2 | trait Notifier { 12 | -------- this trait is not dyn compatible... 13 3 | async fn notify(&self, msg: &str); 14 | ^^^^^^ ...because method `notify` is `async` 15 = help: consider moving `notify` to another trait ``` The phrase **“not dyn compatible”** (older Rust called this “not object safe”) means: the method returns an anonymous future type that differs per impl, so the compiler cannot build a vtable. **Fix:** use the `async-trait` crate (see Best Practices), or restructure to use generics/static dispatch. ### Pitfall 2: spawning a trait future fails with “future cannot be sent between threads” [Section titled “Pitfall 2: spawning a trait future fails with “future cannot be sent between threads””](#pitfall-2-spawning-a-trait-future-fails-with-future-cannot-be-sent-between-threads) Native async-trait futures are **not guaranteed to be `Send`**. The moment you try to move one into `tokio::spawn` (which runs it on the multi-threaded scheduler and therefore requires `Send`), it breaks: ```rust 1 // does not compile (future created by async block is not `Send`) 2 trait Worker { 3 async fn run(&self) -> u32; 4 } 5 6 async fn run_on_task<W: Worker + Send + Sync + 'static>(worker: W) -> u32 { 7 let handle = tokio::spawn(async move { worker.run().await }); 8 handle.await.unwrap() 9 } ``` The real error (abridged), and note the compiler even suggests the fix: ```text 1 error: future cannot be sent between threads safely 2 --> src/main.rs:8:18 3 | 4 8 | let handle = tokio::spawn(async move { worker.run().await }); 5 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ future created by async block is not `Send` 6 | 7 note: future is not `Send` as it awaits another future which is not `Send` 8 note: required by a bound in `tokio::spawn` 9 help: `Send` can be made part of the associated future's guarantees for all implementations of `Worker::run` 10 | 11 4 - async fn run(&self) -> u32; 12 4 + fn run(&self) -> impl std::future::Future<Output = u32> + Send; 13 | ``` **Fix:** write the desugared form with an explicit `+ Send` bound on the returned future: ```rust 1 // Fix: require the returned future to be Send by writing the desugared form. 2 use std::future::Future; 3 4 trait Worker { 5 fn run(&self) -> impl Future<Output = u32> + Send; 6 } 7 8 async fn run_on_task<W: Worker + Send + Sync + 'static>(worker: W) -> u32 { 9 let handle = tokio::spawn(async move { worker.run().await }); 10 handle.await.unwrap() 11 } 12 13 struct Counter; 14 15 impl Worker for Counter { 16 fn run(&self) -> impl Future<Output = u32> + Send { 17 async { 7 } 18 } 19 } 20 21 #[tokio::main] 22 async fn main() { 23 let total = run_on_task(Counter).await; 24 println!("{total}"); 25 } ``` This prints `7`. (More on `tokio::spawn` and `Send` in [Spawning Tasks](/11-async/09-spawning-tasks/).) ### Pitfall 3: assuming you “need the async-trait crate” like the old days [Section titled “Pitfall 3: assuming you “need the async-trait crate” like the old days”](#pitfall-3-assuming-you-need-the-async-trait-crate-like-the-old-days) A lot of older blog posts and Stack Overflow answers say you *must* use `async-trait`. That advice is **outdated**. For the common case — a trait used through generics or concrete types — native `async fn` is correct and faster. Only reach for the crate when you genuinely need `dyn`. (Contrast with the equally common myth that you need the `async-trait` crate for *all* async traits: you do not.) ### Pitfall 4: expecting the future to start when the method is called [Section titled “Pitfall 4: expecting the future to start when the method is called”](#pitfall-4-expecting-the-future-to-start-when-the-method-is-called) Calling `store.get("k")` does **not** run anything; it builds a future. In TypeScript, `repo.find(id)` starts the async work immediately (Promises are **eager**). In Rust, nothing happens until `.await`. Forgetting the `.await` on a trait method gives you an unused-future warning, not a running task. See [Promises vs Futures](/11-async/00-promises-vs-futures/). *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Prefer native `async fn` in traits (no crate) [Section titled “Prefer native async fn in traits (no crate)”](#prefer-native-async-fn-in-traits-no-crate) For traits consumed via concrete types or generic bounds, use plain `async fn`. It is built in, monomorphized, and allocation-free: ```rust 1 // Static dispatch with native async fn in traits — no crate, no boxing. 2 trait Cache { 3 async fn lookup(&self, key: &str) -> Option<u64>; 4 } 5 6 struct AlwaysHit; 7 struct AlwaysMiss; 8 9 impl Cache for AlwaysHit { 10 async fn lookup(&self, _key: &str) -> Option<u64> { 11 Some(42) 12 } 13 } 14 15 impl Cache for AlwaysMiss { 16 async fn lookup(&self, _key: &str) -> Option<u64> { 17 None 18 } 19 } 20 21 // Generic over the concrete cache type: monomorphized, zero-cost, no boxing. 22 async fn report<C: Cache>(cache: &C, key: &str) { 23 match cache.lookup(key).await { 24 Some(v) => println!("{key} -> {v}"), 25 None => println!("{key} -> miss"), 26 } 27 } 28 29 #[tokio::main] 30 async fn main() { 31 report(&AlwaysHit, "user:1").await; 32 report(&AlwaysMiss, "user:2").await; 33 } ``` Output: ```text 1 user:1 -> 42 2 user:2 -> miss ``` ### Use the `async-trait` crate when you need `dyn` [Section titled “Use the async-trait crate when you need dyn”](#use-the-async-trait-crate-when-you-need-dyn) When you genuinely need trait objects — heterogeneous collections, plugin registries, dependency injection where the concrete type is chosen at runtime — add `async-trait` and annotate the trait and every impl: ```bash 1 cargo add async-trait ``` ```rust 1 // async-trait crate — makes the trait dyn-compatible by boxing the returned future. 2 use async_trait::async_trait; 3 4 #[async_trait] 5 trait Notifier { 6 async fn notify(&self, msg: &str); 7 } 8 9 struct EmailNotifier; 10 struct SmsNotifier; 11 12 #[async_trait] 13 impl Notifier for EmailNotifier { 14 async fn notify(&self, msg: &str) { 15 println!("email: {msg}"); 16 } 17 } 18 19 #[async_trait] 20 impl Notifier for SmsNotifier { 21 async fn notify(&self, msg: &str) { 22 println!("sms: {msg}"); 23 } 24 } 25 26 #[tokio::main] 27 async fn main() { 28 // A heterogeneous collection of trait objects — now possible. 29 let notifiers: Vec<Box<dyn Notifier>> = 30 vec![Box::new(EmailNotifier), Box::new(SmsNotifier)]; 31 32 for n in ¬ifiers { 33 n.notify("server is down").await; 34 } 35 } ``` Output: ```text 1 email: server is down 2 sms: server is down ``` Under the hood, `#[async_trait]` rewrites each method to return `Pin<Box<dyn Future + Send + '_>>`. That is: it **boxes the future** (one heap allocation per call) so there *is* a single concrete return type the vtable can hold. This is exactly what TypeScript does implicitly for every Promise. Rust just makes the cost visible and opt-in. > **Note:** `#[async_trait]` adds a `Send` bound by default, which fixes Pitfall 2 for free. If you need a non-`Send` variant (for example, a single-threaded runtime holding `Rc`), write `#[async_trait(?Send)]`. ### For `Send` bounds without `dyn`, consider `trait-variant` [Section titled “For Send bounds without dyn, consider trait-variant”](#for-send-bounds-without-dyn-consider-trait-variant) If you want native (non-boxed) async traits *and* `Send` futures for spawning, the `trait-variant` crate generates a `Send`-bounded variant so you can keep writing plain `async fn`: ```bash 1 cargo add trait-variant ``` ```rust 1 // `trait-variant` generates a Send-bounded variant of an async trait. 2 #[trait_variant::make(HttpService: Send)] 3 trait LocalHttpService { 4 async fn fetch(&self, url: &str) -> String; 5 } 6 7 struct Client; 8 9 impl HttpService for Client { 10 async fn fetch(&self, url: &str) -> String { 11 format!("200 OK {url}") 12 } 13 } 14 15 async fn run_on_task<S: HttpService + Send + Sync + 'static>(svc: S) -> String { 16 tokio::spawn(async move { svc.fetch("https://api.example.com").await }) 17 .await 18 .unwrap() 19 } 20 21 #[tokio::main] 22 async fn main() { 23 println!("{}", run_on_task(Client).await); 24 } ``` Output: ```text 1 200 OK https://api.example.com ``` The macro generates a `Send`-bounded `HttpService` from the base `LocalHttpService`. You implement `HttpService` with ordinary `async fn`, and its futures are `Send`, so `tokio::spawn` accepts them. ### Decision guide [Section titled “Decision guide”](#decision-guide) | Your situation | Use | | --------------------------------------------------------------- | ------------------------------------------- | | Trait used via concrete types or `<T: Trait>` generics | Native `async fn` (no crate) | | Need `Box<dyn Trait>` / `Vec<Box<dyn Trait>>` / trait object | `async-trait` crate | | Need native (unboxed) traits whose futures are `Send` | `+ Send` desugared form, or `trait-variant` | | Single-threaded runtime, want `dyn`, futures need not be `Send` | `#[async_trait(?Send)]` | *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A repository pattern, the Rust equivalent of the opening TypeScript example. The service layer depends on a `dyn UserRepository` so it is decoupled from the concrete backend (in-memory for tests, SQL in production). Because we need `dyn`, this uses the `async-trait` crate. ```rust 1 // Real-world: a `Repository` trait with two backends, used behind a `dyn` trait 2 // object so the service layer is decoupled from the concrete database. 3 use async_trait::async_trait; 4 use std::collections::HashMap; 5 use std::sync::Mutex; 6 7 #[derive(Debug, Clone)] 8 struct User { 9 id: u64, 10 name: String, 11 } 12 13 // We want `dyn UserRepository`, so we use the async-trait crate. 14 #[async_trait] 15 trait UserRepository: Send + Sync { 16 async fn find(&self, id: u64) -> Option<User>; 17 async fn save(&self, user: User) -> Result<(), String>; 18 } 19 20 // Backend 1: an in-memory store (great for tests). 21 struct InMemoryRepo { 22 users: Mutex<HashMap<u64, User>>, 23 } 24 25 #[async_trait] 26 impl UserRepository for InMemoryRepo { 27 async fn find(&self, id: u64) -> Option<User> { 28 self.users.lock().unwrap().get(&id).cloned() 29 } 30 31 async fn save(&self, user: User) -> Result<(), String> { 32 self.users.lock().unwrap().insert(user.id, user); 33 Ok(()) 34 } 35 } 36 37 // Backend 2: a stand-in for a real database client. 38 struct SqlRepo; 39 40 #[async_trait] 41 impl UserRepository for SqlRepo { 42 async fn find(&self, id: u64) -> Option<User> { 43 // Imagine an `sqlx::query!(...).fetch_optional(&pool).await` here. 44 Some(User { id, name: format!("db-user-{id}") }) 45 } 46 47 async fn save(&self, _user: User) -> Result<(), String> { 48 Ok(()) 49 } 50 } 51 52 // The service holds a trait object — it does not care which backend it got. 53 struct UserService { 54 repo: Box<dyn UserRepository>, 55 } 56 57 impl UserService { 58 async fn rename(&self, id: u64, new_name: &str) -> Result<User, String> { 59 let mut user = self.repo.find(id).await.ok_or("not found")?; 60 user.name = new_name.to_string(); 61 self.repo.save(user.clone()).await?; 62 Ok(user) 63 } 64 } 65 66 #[tokio::main] 67 async fn main() { 68 // Swap backends without touching UserService. 69 let mem = InMemoryRepo { users: Mutex::new(HashMap::new()) }; 70 mem.save(User { id: 1, name: "Ada".into() }).await.unwrap(); 71 let svc = UserService { repo: Box::new(mem) }; 72 println!("{:?}", svc.rename(1, "Ada Lovelace").await); 73 74 let svc2 = UserService { repo: Box::new(SqlRepo) }; 75 println!("{:?}", svc2.rename(7, "Grace").await); 76 } ``` Real output: ```text 1 Ok(User { id: 1, name: "Ada Lovelace" }) 2 Ok(User { id: 7, name: "Grace" }) ``` A few production notes: * `UserRepository: Send + Sync` is the **supertrait** bound (see [Supertraits](/09-generics-traits/09-supertraits/)) you almost always want on a `dyn` service trait, so the boxed repository can be shared across tasks. * The `?` operator works inside async trait methods just like in any `async fn` (see [Async/Await](/11-async/01-async-await/)). * For an even more decoupled design, store `Arc<dyn UserRepository>` so the repo can be cloned cheaply across spawned tasks. See [Arc + Mutex Pattern](/11-async/12-arc-mutex-pattern/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [Async fn in traits (Rust 1.75 release notes)](https://blog.rust-lang.org/2023/12/21/async-fn-rpit-in-traits/): the official announcement and rationale. * [The Async Book: async in traits](https://rust-lang.github.io/async-book/) — broader async patterns. * [`async-trait` crate docs](https://docs.rs/async-trait/): the macro, including `?Send`. * [`trait-variant` crate docs](https://docs.rs/trait-variant/) — generating `Send` variants. * [dyn compatibility reference](https://doc.rust-lang.org/reference/items/traits.html#dyn-compatibility): the rules for trait objects. * Related sections in this guide: * [Promises vs Futures](/11-async/00-promises-vs-futures/) — why Rust futures are lazy. * [Async/Await](/11-async/01-async-await/): `async fn`, `.await`, and `?`. * [Async Functions](/11-async/04-async-functions/) — async blocks, capturing, lifetimes. * [Spawning Tasks](/11-async/09-spawning-tasks/): `tokio::spawn` and the `Send` requirement. * [Tokio Intro](/11-async/02-tokio-intro/) and [Tokio Setup](/11-async/03-tokio-setup/) — the runtime. * [Traits](/09-generics-traits/03-traits/), [Trait Objects](/09-generics-traits/06-trait-objects/), and [`impl Trait`](/09-generics-traits/07-impl-trait/) — the non-async foundations. * Next up, organizing all this code into [Modules & Packages](/12-modules-packages/). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Native async trait with a default method [Section titled “Exercise 1: Native async trait with a default method”](#exercise-1-native-async-trait-with-a-default-method) **Difficulty:** Easy **Objective:** Confirm you can declare an async trait and provide a default async method, with no crate. **Instructions:** 1. Define a trait `HealthCheck` with `async fn ping(&self) -> bool`. 2. Add a **default** `async fn is_healthy(&self) -> &'static str` that calls `self.ping().await` and returns `"ok"` or `"down"`. 3. Implement it for two structs, one whose `ping` returns `true` and one `false`. 4. Print the result of `is_healthy().await` for each. ```rust 1 trait HealthCheck { 2 async fn ping(&self) -> bool; 3 4 async fn is_healthy(&self) -> &'static str { 5 // TODO: call self.ping().await and return "ok" / "down" 6 /* ??? */ 7 } 8 } 9 // TODO: ServiceA (true), ServiceB (false), and a #[tokio::main] main ``` Solution ```rust 1 trait HealthCheck { 2 async fn ping(&self) -> bool; 3 4 // Default method calls another async method on the trait. 5 async fn is_healthy(&self) -> &'static str { 6 if self.ping().await { 7 "ok" 8 } else { 9 "down" 10 } 11 } 12 } 13 14 struct ServiceA; 15 struct ServiceB; 16 17 impl HealthCheck for ServiceA { 18 async fn ping(&self) -> bool { 19 true 20 } 21 } 22 23 impl HealthCheck for ServiceB { 24 async fn ping(&self) -> bool { 25 false 26 } 27 } 28 29 #[tokio::main] 30 async fn main() { 31 println!("A: {}", ServiceA.is_healthy().await); 32 println!("B: {}", ServiceB.is_healthy().await); 33 } ``` Output: ```text 1 A: ok 2 B: down ``` ### Exercise 2: Make a plugin trait `dyn`-compatible [Section titled “Exercise 2: Make a plugin trait dyn-compatible”](#exercise-2-make-a-plugin-trait-dyn-compatible) **Difficulty:** Medium **Objective:** Build a plugin pipeline where different plugins are stored in `Vec<Box<dyn Plugin>>` — which forces you to use the `async-trait` crate. **Instructions:** 1. Run `cargo add async-trait`. 2. Define `#[async_trait] trait Plugin: Send + Sync { async fn execute(&self, payload: &str) -> String; }`. 3. Implement two plugins: one uppercases its input, one reverses it. 4. Write `run_pipeline(plugins: &[Box<dyn Plugin>], input: &str) -> String` that feeds each plugin’s output into the next. 5. Run uppercase then reverse on `"rust"`. Solution ```rust 1 use async_trait::async_trait; 2 3 #[async_trait] 4 trait Plugin: Send + Sync { 5 async fn execute(&self, payload: &str) -> String; 6 } 7 8 struct UppercasePlugin; 9 struct ReversePlugin; 10 11 #[async_trait] 12 impl Plugin for UppercasePlugin { 13 async fn execute(&self, payload: &str) -> String { 14 payload.to_uppercase() 15 } 16 } 17 18 #[async_trait] 19 impl Plugin for ReversePlugin { 20 async fn execute(&self, payload: &str) -> String { 21 payload.chars().rev().collect() 22 } 23 } 24 25 async fn run_pipeline(plugins: &[Box<dyn Plugin>], input: &str) -> String { 26 let mut current = input.to_string(); 27 for plugin in plugins { 28 current = plugin.execute(¤t).await; 29 } 30 current 31 } 32 33 #[tokio::main] 34 async fn main() { 35 let plugins: Vec<Box<dyn Plugin>> = 36 vec![Box::new(UppercasePlugin), Box::new(ReversePlugin)]; 37 println!("{}", run_pipeline(&plugins, "rust").await); 38 } ``` Output (`"rust"` → `"RUST"` → reversed): ```text 1 TSUR ``` ### Exercise 3: A spawnable native async trait [Section titled “Exercise 3: A spawnable native async trait”](#exercise-3-a-spawnable-native-async-trait) **Difficulty:** Hard **Objective:** Write a **native** (unboxed) async trait whose futures are `Send`, then run its work across tasks with `tokio::spawn`. **Instructions:** 1. Define `trait Transform: Send + Sync + 'static` with a method `fn apply(&self, input: u64) -> impl Future<Output = u64> + Send;` (the desugared `+ Send` form — a plain `async fn` here would fail to spawn). 2. Implement `Doubler`, which doubles its input. 3. Write `run_parallel<T: Transform>(transform: T, inputs: Vec<u64>) -> Vec<u64>` that wraps the transform in an `Arc`, `tokio::spawn`s one task per input, and collects the results. 4. Run it on `vec![1, 2, 3, 4]`. **Hint:** Wrap the transform in `Arc` and `clone` the `Arc` into each spawned task. Solution ```rust 1 use std::future::Future; 2 use std::sync::Arc; 3 4 trait Transform: Send + Sync + 'static { 5 fn apply(&self, input: u64) -> impl Future<Output = u64> + Send; 6 } 7 8 struct Doubler; 9 10 impl Transform for Doubler { 11 fn apply(&self, input: u64) -> impl Future<Output = u64> + Send { 12 async move { input * 2 } 13 } 14 } 15 16 // Spawns the work on separate tasks; requires the future to be Send. 17 async fn run_parallel<T: Transform>(transform: T, inputs: Vec<u64>) -> Vec<u64> { 18 let transform = Arc::new(transform); 19 let mut handles = Vec::new(); 20 for input in inputs { 21 let t = transform.clone(); 22 handles.push(tokio::spawn(async move { t.apply(input).await })); 23 } 24 let mut out = Vec::new(); 25 for h in handles { 26 out.push(h.await.unwrap()); 27 } 28 out 29 } 30 31 #[tokio::main] 32 async fn main() { 33 let results = run_parallel(Doubler, vec![1, 2, 3, 4]).await; 34 println!("{results:?}"); 35 } ``` Output: ```text 1 [2, 4, 6, 8] ``` > Note: the task order is deterministic here because we collect `handles` in order and `await` them sequentially; the *execution* may interleave across threads. # Streams: Async Iterators in Rust > A Stream is Rust's async iterator, the cousin of TypeScript's for await...of. Build streams, use StreamExt combinators, pin them, and consume with while let. A **stream** is the asynchronous cousin of an iterator: a sequence of values produced over time, where pulling the next value is an `.await` rather than a blocking call. If you have reached for `for await...of` over an `AsyncIterable` in TypeScript — paging through an API, reading lines from a socket, draining a queue — a Rust `Stream` is the tool you want. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **`Stream`** yields items one at a time, and obtaining each item may require waiting (for I/O, a timer, a channel message). It is exactly `Iterator`, but every `next` is asynchronous. JavaScript spells this `AsyncIterator`/`AsyncIterable` and consumes it with `for await...of`; Rust has the `Stream` trait, the `.next().await` method, and the `while let Some(x) = s.next().await` loop. This page covers the `Stream` trait, how to get a stream (`tokio_stream::iter`, the `async-stream` crate, channel wrappers), the iterator-style combinators on `StreamExt`, and the consumption patterns. > **Note:** `Stream` is **not** in the standard library’s prelude the way `Iterator` is. On the repository’s [pinned Rust 1.96.0 baseline](/00-introduction/05-version-policy/), `std::async_iter::AsyncIterator` is nightly-only and unstable; production code uses the `Stream` trait from the [`futures`](https://docs.rs/futures) crate, re-exported by [`tokio-stream`](https://docs.rs/tokio-stream). The recorded dependency set is Tokio 1.52, `tokio-stream` 0.1, `futures` 0.3, and `async-stream` 0.3 on the 2024 edition. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript, an `async function*` (async generator) produces an `AsyncIterableIterator`. Each `yield` hands back a value; `await` points inside the generator suspend it until work completes. You consume it with `for await...of`, which calls the iterator’s `next()` and awaits each promised result. ```typescript 1 // An async generator: each `yield` is a value that arrives over time. 2 async function* fetchPages(total: number): AsyncGenerator<string[]> { 3 for (let page = 1; page <= total; page++) { 4 // Simulate a network round-trip per page. 5 await new Promise((resolve) => setTimeout(resolve, 10)); 6 yield [`p${page}-item0`, `p${page}-item1`, `p${page}-item2`]; 7 } 8 } 9 10 async function main(): Promise<void> { 11 const allItems: string[] = []; 12 13 // `for await...of` pulls one page at a time, awaiting each. 14 for await (const items of fetchPages(3)) { 15 console.log(`fetched a page with ${items.length} items`); 16 allItems.push(...items); 17 } 18 19 console.log(`total items: ${allItems.length}`); 20 } 21 22 await main(); ``` Key properties of the JavaScript model, to contrast against Rust: * The generator is **lazy** in the sense that it only advances when the consumer asks for the next value; already similar to Rust here. * But the *consumer* drives it via the built-in event loop; there is no separate runtime to install. * `for await...of` is the one canonical consumption form. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same paginated fetch as a Rust `Stream`, consumed with `while let`: ```rust 1 use std::time::Duration; 2 use tokio::time::sleep; 3 use tokio_stream::StreamExt; 4 5 #[derive(Debug)] 6 struct Page { 7 number: u32, 8 items: Vec<String>, 9 } 10 11 // Fetching one page costs an async round-trip. 12 async fn fetch_page(number: u32) -> Page { 13 sleep(Duration::from_millis(10)).await; // simulate network latency 14 let items = (0..3) 15 .map(|i| format!("p{number}-item{i}")) 16 .collect::<Vec<_>>(); 17 Page { number, items } 18 } 19 20 // Expose pages 1..=total as a `Stream<Item = Page>`, fetched lazily. 21 fn page_stream(total: u32) -> impl tokio_stream::Stream<Item = Page> { 22 // `then` maps each page number to a future and awaits it in order. 23 tokio_stream::iter(1..=total).then(fetch_page) 24 } 25 26 #[tokio::main] 27 async fn main() { 28 let mut all_items = Vec::new(); 29 30 // A `then`-based stream holds a future and is not `Unpin`, so pin it. 31 let pages = page_stream(3); 32 tokio::pin!(pages); 33 34 // `while let Some(x) = s.next().await` is Rust's `for await...of`. 35 while let Some(page) = pages.next().await { 36 println!("fetched page {} with {} items", page.number, page.items.len()); 37 all_items.extend(page.items); 38 } 39 40 println!("total items: {}", all_items.len()); 41 } ``` Real output: ```text 1 fetched page 1 with 3 items 2 fetched page 2 with 3 items 3 fetched page 3 with 3 items 4 total items: 9 ``` The shape mirrors the TypeScript: produce a sequence asynchronously, consume one item at a time. The differences are the explicit runtime (`#[tokio::main]`), the `StreamExt` import that enables `.next()`/`.then()`, and the `tokio::pin!`; all explained below. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The `Stream` trait is `Iterator` with `poll_next` [Section titled “The Stream trait is Iterator with poll\_next”](#the-stream-trait-is-iterator-with-poll_next) A synchronous iterator has one required method: ```rust 1 // From the standard library (simplified). 2 // trait Iterator { 3 // type Item; 4 // fn next(&mut self) -> Option<Self::Item>; 5 // } ``` A `Stream` has the async analogue. Instead of returning `Option<Item>` immediately, it returns a `Poll` so the runtime can be told “not ready yet, suspend me”: ```rust 1 // From the `futures`/`tokio-stream` crates (simplified). 2 // trait Stream { 3 // type Item; 4 // fn poll_next( 5 // self: Pin<&mut Self>, 6 // cx: &mut Context<'_>, 7 // ) -> Poll<Option<Self::Item>>; 8 // } ``` The `Poll<Option<Item>>` return type encodes three states: * `Poll::Ready(Some(item))`: here is the next value. * `Poll::Ready(None)` — the stream is finished, forever. * `Poll::Pending`: no value yet; the runtime will poll again when progress is possible. You rarely write `poll_next` by hand, just as you rarely write a manual `Iterator`. But seeing it makes the model concrete: a stream is a thing the runtime polls repeatedly until it yields `None`. ```rust 1 use std::pin::Pin; 2 use std::task::{Context, Poll}; 3 use tokio_stream::{Stream, StreamExt}; 4 5 // A hand-written Stream that counts up to `max`, one value per poll. 6 struct Counter { 7 current: u32, 8 max: u32, 9 } 10 11 impl Stream for Counter { 12 type Item = u32; 13 14 fn poll_next(mut self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Option<u32>> { 15 if self.current < self.max { 16 self.current += 1; 17 Poll::Ready(Some(self.current)) 18 } else { 19 Poll::Ready(None) 20 } 21 } 22 } 23 24 #[tokio::main] 25 async fn main() { 26 let counter = Counter { current: 0, max: 3 }; 27 // `collect()` drains the stream into a collection. 28 let collected: Vec<u32> = counter.collect().await; 29 println!("{collected:?}"); 30 } ``` Real output: ```text 1 [1, 2, 3] ``` > **Note:** Implementing `Stream` by hand is the rare case. This `Counter` never returns `Pending` because it always has a value ready. It is effectively a synchronous iterator wearing a stream’s clothes. Real `poll_next` implementations that wait on I/O are subtle (they must register the `Context`’s waker), which is exactly why you normally use a generator macro or a channel wrapper instead. See [Custom Iterators](/07-collections/08-custom-iterators/) for the synchronous counterpart. ### `StreamExt` provides `.next()` and the combinators [Section titled “StreamExt provides .next() and the combinators”](#streamext-provides-next-and-the-combinators) The `Stream` trait deliberately has *only* `poll_next`. All the ergonomic methods — `next`, `map`, `filter`, `take`, `collect`, `fold` — live on an **extension trait** called `StreamExt`, mirroring how `Iterator`’s adapters are inherent but its async equivalents are bolted on separately. You must bring `StreamExt` into scope to use them: ```rust 1 use tokio_stream::StreamExt; 2 3 #[tokio::main] 4 async fn main() { 5 // Iterator-style adapters are lazy: nothing runs until consumed. 6 let mut stream = tokio_stream::iter(1..=10) 7 .filter(|n| n % 2 == 0) // keep evens 8 .map(|n| n * n) // square them 9 .take(3); // stop after 3 items 10 11 while let Some(x) = stream.next().await { 12 println!("{x}"); 13 } 14 15 // `fold` consumes the whole stream into one accumulated value. 16 let total = tokio_stream::iter(1..=5).fold(0, |acc, n| acc + n).await; 17 println!("sum = {total}"); 18 } ``` Real output: ```text 1 4 2 16 3 36 4 sum = 15 ``` > **Tip:** `tokio_stream::iter(...)` is the bridge from any `IntoIterator` to a `Stream`. It is handy for tests and for feeding fixed data through stream-shaped code, just like `Promise.resolve` wraps a plain value in a promise. There are **two** `StreamExt` traits in the ecosystem: `futures::StreamExt` and `tokio_stream::StreamExt`. They overlap heavily but are not identical. For instance, `enumerate` lives on `futures::StreamExt`, not the tokio one: ```rust 1 // `enumerate` is provided by the `futures` crate's StreamExt. 2 use futures::StreamExt; 3 4 #[tokio::main] 5 async fn main() { 6 let labels = futures::stream::iter(["a", "b", "c"]); 7 let mut numbered = labels.enumerate(); 8 while let Some((i, label)) = numbered.next().await { 9 println!("{i} => {label}"); 10 } 11 } ``` Real output: ```text 1 0 => a 2 1 => b 3 2 => c ``` > **Warning:** Importing both `futures::StreamExt` and `tokio_stream::StreamExt` in the same module makes calls like `.next()` ambiguous and fails to compile. Pick one per module. A common convention: use `tokio_stream` when you want its tokio-specific extras (`timeout`, `throttle`, `chunks_timeout`, the channel wrappers), and `futures` otherwise. ### `while let` is the `for await...of` of Rust [Section titled “while let is the for await...of of Rust”](#while-let-is-the-for-awaitof-of-rust) There is no `for await` loop in Rust. The idiomatic consumption form is: ```rust 1 // while let Some(item) = stream.next().await { 2 // // use item 3 // } ``` This reads as “repeatedly: await the next item; if it is `Some`, run the body; when it is `None`, stop.” A plain `for item in stream` does **not** work — `for` requires `Iterator`, and a `Stream` is not one. (`tokio_stream::iter` returns a stream, not an iterator, precisely so you can `.next().await` it.) ### Generators: the `async-stream` crate replaces `async function*` [Section titled “Generators: the async-stream crate replaces async function\*”](#generators-the-async-stream-crate-replaces-async-function) Writing `poll_next` by hand is painful, and the standard library has no stable equivalent of JavaScript’s `async function*` with `yield`. The [`async-stream`](https://docs.rs/async-stream) crate fills that gap with a `stream!` macro where you can `yield` and `.await` freely: ```rust 1 use std::time::Duration; 2 use tokio::time::sleep; 3 use tokio_stream::StreamExt; 4 5 #[tokio::main] 6 async fn main() { 7 // Like a JavaScript `async function*`: `yield x` emits, `.await` suspends. 8 let stream = async_stream::stream! { 9 for i in 1..=3 { 10 sleep(Duration::from_millis(10)).await; // async work between yields 11 yield i * 10; 12 } 13 }; 14 15 // A `stream!` value is not `Unpin`; pin it on the stack to iterate. 16 tokio::pin!(stream); 17 while let Some(item) = stream.next().await { 18 println!("yielded {item}"); 19 } 20 } ``` Real output: ```text 1 yielded 10 2 yielded 20 3 yielded 30 ``` This is the closest analogue to the TypeScript `async function*` at the top of the page, and for most “produce a sequence with some async work in between” cases it is the right tool. ### Pinning: the one genuinely new concept [Section titled “Pinning: the one genuinely new concept”](#pinning-the-one-genuinely-new-concept) You saw `tokio::pin!` twice already. Here is why. To poll a stream, the runtime needs a `Pin<&mut Stream>`, a guarantee that the stream will not be moved in memory while it is being polled. Streams produced by `async-stream` or by the `.then()` adapter are *self-referential state machines* (they hold a suspended future that may point into their own data), so they are **not `Unpin`** and cannot be polled until they are pinned to a fixed location. `tokio::pin!(name)` pins the value on the stack and shadows the binding so subsequent `.next()` calls work. Streams that are *not* self-referential — like `tokio_stream::iter(...)` or a `ReceiverStream` — are `Unpin` and need no pinning. There is no JavaScript equivalent of this; the JS engine manages all of it for you. Pinning is covered more broadly in [Async Functions](/11-async/04-async-functions/). ### Channels are streams: `ReceiverStream` [Section titled “Channels are streams: ReceiverStream”](#channels-are-streams-receiverstream) A frequent real-world source of a stream is “values arriving on a channel.” `tokio-stream` wraps an mpsc receiver into a `Stream` so you can apply combinators and `while let`: ```rust 1 use std::time::Duration; 2 use tokio::sync::mpsc; 3 use tokio::time::sleep; 4 use tokio_stream::wrappers::ReceiverStream; 5 use tokio_stream::StreamExt; 6 7 #[tokio::main] 8 async fn main() { 9 let (tx, rx) = mpsc::channel::<u32>(16); 10 11 // A producer task pushes values over time, then drops `tx`. 12 tokio::spawn(async move { 13 for i in 1..=3 { 14 sleep(Duration::from_millis(10)).await; 15 let _ = tx.send(i * 100).await; 16 } 17 // Dropping `tx` ends the stream (next() yields None). 18 }); 19 20 // Wrap the Receiver as a Stream we can iterate. 21 let mut stream = ReceiverStream::new(rx); 22 while let Some(value) = stream.next().await { 23 println!("received {value}"); 24 } 25 println!("channel closed, stream ended"); 26 } ``` Real output: ```text 1 received 100 2 received 200 3 received 300 4 channel closed, stream ended ``` The stream ends exactly when the last sender is dropped: the natural “the producer is done” signal. Channels themselves are covered in [Channels](/11-async/08-channels/). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | TypeScript/JavaScript | Rust | | ----------------------------- | ------------------------------------------- | ------------------------------------------------- | | The abstraction | `AsyncIterator` / `AsyncIterable` | `Stream` trait (from `futures` / `tokio-stream`) | | Producer syntax | `async function*` with `yield` | `async_stream::stream! { ... yield ... }` | | Consumption loop | `for await (const x of s)` | `while let Some(x) = s.next().await` | | Get next item | `await s.next()` → `{ value, done }` | `s.next().await` → `Option<Item>` | | In the standard library? | Yes (`Symbol.asyncIterator`) | No. `AsyncIterator` is nightly-only; use a crate | | Adapters (`map`, `filter`, …) | Not built in (use a library or manual loop) | On `StreamExt` (must be imported) | | Needs a runtime? | No: built-in event loop | Yes: Tokio (or another executor) | | Self-referential producers | Engine-managed | Must be **pinned** (`tokio::pin!`) before polling | | Backpressure | Manual (the consumer’s pace) | Built into bounded channels and `poll_next` | > **Note:** The deepest conceptual gap is the same one that defines all of Rust async: a stream does nothing until a runtime polls it, and you supply the runtime. A JavaScript async generator advances on the engine’s event loop with no setup. See [Promises vs Futures](/11-async/00-promises-vs-futures/) for the full eager-vs-lazy story; a stream is just “a future that resolves many times.” ### Streams compose like iterators, lazily [Section titled “Streams compose like iterators, lazily”](#streams-compose-like-iterators-lazily) Just like `Iterator` adapters, `Stream` adapters (`map`, `filter`, `take`, `then`, `merge`, …) build a new lazy stream and run nothing until consumed. `merge` interleaves two same-typed streams, yielding from whichever is ready: ```rust 1 use tokio_stream::StreamExt; 2 3 #[tokio::main] 4 async fn main() { 5 let a = tokio_stream::iter(vec![1, 2, 3]); 6 let b = tokio_stream::iter(vec![10, 20, 30]); 7 // `merge` yields from whichever stream is ready next. 8 let mut merged = a.merge(b); 9 let mut out = Vec::new(); 10 while let Some(x) = merged.next().await { 11 out.push(x); 12 } 13 println!("{out:?}"); 14 } ``` Real output: ```text 1 [1, 10, 2, 20, 3, 30] ``` If you already think in `Array.prototype.map`/`filter` and Rust’s [iterator adapters](/07-collections/06-iterators/), stream adapters are the async version of the same mental model. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting to import `StreamExt` [Section titled “Pitfall 1: Forgetting to import StreamExt”](#pitfall-1-forgetting-to-import-streamext) The `Stream` trait gives you `poll_next`, but `.next()` lives on `StreamExt`. Without the import, `.next()` does not exist: ```rust 1 // Note: no `use tokio_stream::StreamExt;` — so `.next()` is not in scope. 2 3 #[tokio::main] 4 async fn main() { 5 let mut stream = tokio_stream::iter(vec![1, 2, 3]); 6 // does not compile (error[E0599]): `next` not found without StreamExt. 7 while let Some(value) = stream.next().await { 8 println!("{value}"); 9 } 10 } ``` Real compiler error (trimmed): ```text 1 error[E0599]: no method named `next` found for struct `tokio_stream::Iter` in the current scope 2 --> src/main.rs:6:36 3 | 4 6 | while let Some(value) = stream.next().await { 5 | ^^^^ 6 | 7 = help: items from traits can only be used if the trait is in scope 8 help: trait `StreamExt` which provides `next` is implemented but not in scope; perhaps you want to import it 9 | 10 3 + use tokio_stream::StreamExt; 11 | ``` The compiler tells you the exact fix: `use tokio_stream::StreamExt;`. This is the single most common stream error for newcomers. ### Pitfall 2: Polling an unpinned self-referential stream [Section titled “Pitfall 2: Polling an unpinned self-referential stream”](#pitfall-2-polling-an-unpinned-self-referential-stream) A `stream!` block or a `.then()` stream is not `Unpin`. Calling `.next()` on it without pinning fails: ```rust 1 use tokio_stream::StreamExt; 2 3 #[tokio::main] 4 async fn main() { 5 let stream = async_stream::stream! { 6 for i in 1..=3 { 7 yield i; 8 } 9 }; 10 11 // does not compile (error[E0277]): the stream is not `Unpin`. 12 let mut stream = stream; 13 while let Some(item) = stream.next().await { 14 println!("{item}"); 15 } 16 } ``` The real `rustc` error is `error[E0277]: ... cannot be unpinned`, with the note `consider using the pin! macro`, and points at `StreamExt::next`’s `Self: Unpin` bound. The fix is to pin before iterating: ```rust 1 use tokio_stream::StreamExt; 2 3 #[tokio::main] 4 async fn main() { 5 let stream = async_stream::stream! { 6 for i in 1..=3 { 7 yield i; 8 } 9 }; 10 11 tokio::pin!(stream); // pin on the stack; `stream` is now pollable 12 while let Some(item) = stream.next().await { 13 println!("{item}"); 14 } 15 } ``` Real output: ```text 1 1 2 2 3 3 ``` > **Tip:** If you need to store the stream in a struct field or return it as `Box<dyn Stream<...>>`, use `Box::pin(stream)` instead of `tokio::pin!`, which pins on the heap and can be moved around. ### Pitfall 3: Reaching for `for` instead of `while let` [Section titled “Pitfall 3: Reaching for for instead of while let”](#pitfall-3-reaching-for-for-instead-of-while-let) A `Stream` is not an `Iterator`, so `for item in stream` does not compile — `for` desugars to `Iterator::next`, which a stream does not have. There is no `for await` in Rust. Always use `while let Some(item) = stream.next().await`. If you genuinely have an `Iterator` (not a stream), use a normal `for`; the two are different traits with different loops. ### Pitfall 4: Mixing the two `StreamExt` traits [Section titled “Pitfall 4: Mixing the two StreamExt traits”](#pitfall-4-mixing-the-two-streamext-traits) Importing both `futures::StreamExt` and `tokio_stream::StreamExt` makes shared methods like `.next()` and `.map()` ambiguous, producing an `error[E0034]: multiple applicable items in scope`. Choose one `StreamExt` per module. If you need a method that only one of them has (for example, `enumerate` from `futures`, or `timeout` from `tokio_stream`), import just that one in that module. ### Pitfall 5: Expecting `collect` on an infinite stream to terminate [Section titled “Pitfall 5: Expecting collect on an infinite stream to terminate”](#pitfall-5-expecting-collect-on-an-infinite-stream-to-terminate) Adapters do not magically bound an infinite stream. Calling `.collect().await` on a stream that never returns `None` (like the `Fib` example below without `.take(...)`) will run forever and exhaust memory. Bound it with `.take(n)`, `.take_while(...)`, or `.timeout(...)` first: the same discipline as a synchronous infinite iterator. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Prefer `async-stream` over hand-written `poll_next` [Section titled “Prefer async-stream over hand-written poll\_next”](#prefer-async-stream-over-hand-written-poll_next) Unless you are building a low-level library primitive, write producers with the `stream!` macro. It is readable, supports `.await` and `yield` naturally, and sidesteps the subtle waker-registration logic that manual `poll_next` requires. Reserve a hand-written `Stream` impl for cases where you need zero dependencies or maximal control. ### Wrap channels with `ReceiverStream`/`BroadcastStream` [Section titled “Wrap channels with ReceiverStream/BroadcastStream”](#wrap-channels-with-receiverstreambroadcaststream) When the data source is “messages on a channel,” use the `tokio_stream::wrappers` types rather than writing a loop that calls `recv().await`. You gain the full combinator vocabulary (`filter`, `map`, `timeout`, `chunks_timeout`) for free. ### Bound and rate-limit explicitly [Section titled “Bound and rate-limit explicitly”](#bound-and-rate-limit-explicitly) For network or queue-backed streams, lean on adapters that bound behavior: `take`, `take_while`, `timeout`, and `tokio_stream`’s `throttle` (minimum delay between items) and `chunks_timeout` (batch up to N items or until a deadline). These make backpressure and resource limits visible in the code. ### Pick one `StreamExt` per module and stick to it [Section titled “Pick one StreamExt per module and stick to it”](#pick-one-streamext-per-module-and-stick-to-it) Decide up front whether a module uses `futures::StreamExt` or `tokio_stream::StreamExt`, and keep it consistent to avoid ambiguity errors. In a Tokio-centric codebase, `tokio_stream::StreamExt` plus the wrapper types is the path of least resistance. ### Don’t block inside a stream’s producer [Section titled “Don’t block inside a stream’s producer”](#dont-block-inside-a-streams-producer) The same rule as any async code: do not call blocking APIs (`std::thread::sleep`, blocking file reads, long CPU loops) inside a `stream!` block or `poll_next` — it stalls the runtime worker. Use async equivalents or move the work to `spawn_blocking`. See [Async vs Sync](/11-async/13-async-vs-sync/) and [Spawning Tasks](/11-async/09-spawning-tasks/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A telemetry ingester: a producer task emits sensor readings onto a bounded channel, and a consumer treats the receiver as a stream: filtering out invalid readings, throttling is unnecessary here because the channel already provides backpressure, and accumulating a running summary. This is a common production shape: one side produces, the other consumes a `Stream` with combinators. ```rust 1 use std::time::Duration; 2 use tokio::sync::mpsc; 3 use tokio::time::sleep; 4 use tokio_stream::wrappers::ReceiverStream; 5 use tokio_stream::StreamExt; 6 7 #[derive(Debug, Clone)] 8 struct Reading { 9 sensor: u32, 10 celsius: f64, 11 } 12 13 #[tokio::main] 14 async fn main() { 15 let (tx, rx) = mpsc::channel::<Reading>(64); 16 17 // Producer task: emit readings over time, including one bogus value, 18 // then drop `tx` to signal completion. 19 tokio::spawn(async move { 20 let samples = [ 21 Reading { sensor: 1, celsius: 21.5 }, 22 Reading { sensor: 2, celsius: -999.0 }, // sentinel: hardware fault 23 Reading { sensor: 1, celsius: 22.1 }, 24 Reading { sensor: 3, celsius: 19.8 }, 25 ]; 26 for r in samples { 27 sleep(Duration::from_millis(5)).await; 28 if tx.send(r).await.is_err() { 29 break; // consumer gone 30 } 31 } 32 }); 33 34 // Consumer: receiver-as-stream + combinators. 35 let mut readings = ReceiverStream::new(rx) 36 // Drop physically impossible readings. 37 .filter(|r| r.celsius > -100.0 && r.celsius < 150.0) 38 // Convert to Fahrenheit, keeping the sensor id. 39 .map(|r| (r.sensor, r.celsius * 9.0 / 5.0 + 32.0)); 40 41 let mut count = 0u32; 42 let mut sum_f = 0.0; 43 while let Some((sensor, fahrenheit)) = readings.next().await { 44 count += 1; 45 sum_f += fahrenheit; 46 println!("sensor {sensor}: {fahrenheit:.1}F"); 47 } 48 49 if count > 0 { 50 println!("accepted {count} readings, avg {:.1}F", sum_f / count as f64); 51 } else { 52 println!("no valid readings"); 53 } 54 } ``` Real output: ```text 1 sensor 1: 70.7F 2 sensor 1: 71.8F 3 sensor 3: 67.6F 4 accepted 3 readings, avg 70.0F ``` The bogus `-999.0` reading is filtered out before it reaches the summary, the valid ones are converted and averaged, and the loop ends cleanly when the producer drops its sender. The equivalent TypeScript would be an `async function*` feeding a `for await...of` loop with manual `.filter`/`.map` inside it; the Rust version expresses the pipeline declaratively and runs on the Tokio runtime you opted into. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [`futures::Stream` trait](https://docs.rs/futures/latest/futures/stream/trait.Stream.html) * [`tokio-stream` crate docs](https://docs.rs/tokio-stream/latest/tokio_stream/) * [Tokio tutorial — Streams](https://tokio.rs/tokio/tutorial/streams) * [`async-stream` crate docs](https://docs.rs/async-stream/latest/async_stream/) * [The async book — Streams](https://rust-lang.github.io/async-book/05_streams/01_chapter.html) * [`std::pin` — pinning](https://doc.rust-lang.org/std/pin/index.html) ### Related Topics in This Guide [Section titled “Related Topics in This Guide”](#related-topics-in-this-guide) * [Promises vs Futures](/11-async/00-promises-vs-futures/): why a stream, like a future, is lazy and needs a runtime * [Async/Await Syntax](/11-async/01-async-await/) — `async`/`await`, `.await`, `?` propagation * [Async Functions](/11-async/04-async-functions/): `async` blocks, returning futures, pinning in depth * [Tokio Intro](/11-async/02-tokio-intro/): the runtime that polls your streams * [Channels](/11-async/08-channels/) — mpsc/broadcast/watch, the most common stream sources * [Select & Join](/11-async/07-select-join/): racing and combining futures and streams * [Spawning Tasks](/11-async/09-spawning-tasks/): `tokio::spawn`, `spawn_blocking` * [Async vs Sync](/11-async/13-async-vs-sync/) — when to use async at all * [Iterators](/07-collections/06-iterators/): the synchronous mental model streams build on * [Iterator Consumers](/07-collections/07-iterator-consumers/) — `collect`, `fold`, and friends * [Custom Iterators](/07-collections/08-custom-iterators/): implementing `Iterator` by hand, the sync sibling of a manual `Stream` * Next up: [Section 12 — Modules & Packages](/12-modules-packages/) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1 [Section titled “Exercise 1”](#exercise-1) **Difficulty:** Beginner **Objective:** Build a stream from a range and process it with adapters. **Instructions:** Using `tokio_stream::iter(1..=20)` and `StreamExt`, build a stream that keeps only multiples of 3, doubles each kept value, and sums the result with `.fold(...)`. Print the sum. (Expected: the multiples of 3 in 1..=20 are 3, 6, 9, 12, 15, 18; doubled they are 6, 12, 18, 24, 30, 36.) Solution ```rust 1 use tokio_stream::StreamExt; 2 3 #[tokio::main] 4 async fn main() { 5 let sum: u32 = tokio_stream::iter(1..=20) 6 .filter(|n| n % 3 == 0) 7 .map(|n| n * 2) 8 .fold(0, |acc, n| acc + n) 9 .await; 10 println!("sum = {sum}"); 11 } ``` Real output: ```text 1 sum = 126 ``` ### Exercise 2 [Section titled “Exercise 2”](#exercise-2) **Difficulty:** Intermediate **Objective:** Implement the `Stream` trait by hand for an infinite sequence, then bound it. **Instructions:** Implement `Stream for Fib` where `Fib { a, b }` yields the Fibonacci sequence (`type Item = u64`). Each `poll_next` should return the current value and advance the state. In `main`, build `Fib { a: 0, b: 1 }`, take the first 10 values with `.take(10)`, `collect` them into a `Vec<u64>`, and print it. Remember the stream is infinite, so the `.take(10)` is what makes it terminate. Solution ```rust 1 use std::pin::Pin; 2 use std::task::{Context, Poll}; 3 use tokio_stream::{Stream, StreamExt}; 4 5 struct Fib { 6 a: u64, 7 b: u64, 8 } 9 10 impl Stream for Fib { 11 type Item = u64; 12 13 fn poll_next(mut self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Option<u64>> { 14 let next = self.a; 15 self.a = self.b; 16 self.b = next + self.b; 17 Poll::Ready(Some(next)) 18 } 19 } 20 21 #[tokio::main] 22 async fn main() { 23 let fib = Fib { a: 0, b: 1 }; 24 // This stream is infinite; `take` bounds it. 25 let first_ten: Vec<u64> = fib.take(10).collect().await; 26 println!("{first_ten:?}"); 27 } ``` Real output: ```text 1 [0, 1, 1, 2, 3, 5, 8, 13, 21, 34] ``` > **Note:** `Fib` is `Unpin` (it has no self-referential async state), so no pinning is needed even though it implements `Stream` directly. ### Exercise 3 [Section titled “Exercise 3”](#exercise-3) **Difficulty:** Intermediate **Objective:** Bridge a producer task and a consumer using a channel-as-stream. **Instructions:** Create a bounded `mpsc::channel::<i64>(32)`. Spawn a producer task that sends `1..=10` over the channel (with a tiny `sleep` between sends) and then drops the sender. In `main`, wrap the receiver with `ReceiverStream`, keep only multiples of 3 with `.filter(...)`, take the first 2 with `.take(2)`, and print each kept value with a `while let` loop. Solution ```rust 1 use std::time::Duration; 2 use tokio::sync::mpsc; 3 use tokio::time::sleep; 4 use tokio_stream::wrappers::ReceiverStream; 5 use tokio_stream::StreamExt; 6 7 #[tokio::main] 8 async fn main() { 9 let (tx, rx) = mpsc::channel::<i64>(32); 10 11 // Producer: emit 1..=10, then drop the sender. 12 tokio::spawn(async move { 13 for n in 1..=10 { 14 sleep(Duration::from_millis(5)).await; 15 if tx.send(n).await.is_err() { 16 break; // receiver dropped 17 } 18 } 19 }); 20 21 // Consumer: receiver-as-stream + combinators. 22 let mut stream = ReceiverStream::new(rx) 23 .filter(|n| n % 3 == 0) 24 .take(2); 25 26 while let Some(n) = stream.next().await { 27 println!("kept {n}"); 28 } 29 println!("done"); 30 } ``` Real output: ```text 1 kept 3 2 kept 6 3 done ``` > **Note:** Because of `.take(2)`, the consumer stops after two matching values and drops the `ReceiverStream`; the producer’s next `send` then fails and its `break` ends the task cleanly. # Concurrent Awaiting: `join!`, `try_join!`, and `select!` > Rust's join!, try_join!, and select! map to Promise.all and Promise.race, but futures are lazy and select! cancels the losers instead of letting them run. In JavaScript you reach for `Promise.all` to wait for several async operations at once and `Promise.race` to take whichever finishes first. Rust gives you the same shapes — `tokio::join!`, `tokio::try_join!`, and `tokio::select!` — but because Rust **futures are lazy**, *building* the futures is not enough. These macros are what actually drive several futures forward on the same task. This page maps each JavaScript combinator to its Rust equivalent and shows where the analogy breaks down. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Awaiting futures one after another is **sequential** in Rust: the second future does not even start until the first finishes (see [Promises vs Futures](/11-async/00-promises-vs-futures/)). To run multiple operations *concurrently on one task*, you combine their futures with a macro: **`join!`** waits for all of them (like `Promise.all`), **`try_join!`** waits for all but short-circuits on the first error (like `Promise.all` with rejection), and **`select!`** returns as soon as the *first* one finishes and **cancels the rest** (like `Promise.race`). These run concurrently *without* spawning tasks or threads: a single task interleaves the futures. > **Note:** This page is about combining futures *on the current task*. If you want them to run on *separate* tasks (true parallelism on a multi-thread runtime, fire-and-forget, `JoinHandle`s), that is [`tokio::spawn`](/11-async/09-spawning-tasks/). For the eager-vs-lazy foundation this all rests on, read [Promises vs Futures](/11-async/00-promises-vs-futures/) first. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) A typical “load everything a page needs” function fans out several requests and waits for all of them with `Promise.all`. To guard a slow call, you `Promise.race` it against a timeout. ```typescript 1 // TypeScript / JavaScript (Node v22) 2 3 const slow = (ms: number, label: string): Promise<string> => 4 new Promise((resolve) => setTimeout(() => resolve(label), ms)); 5 6 // Promise.all: run all concurrently, wait for ALL, get an array in order. 7 const all = await Promise.all([ 8 slow(120, "user"), 9 slow(90, "posts"), 10 slow(150, "profile"), 11 ]); 12 console.log("all:", all); 13 14 // Promise.race: first to SETTLE (resolve OR reject) wins; the others keep running. 15 const winner = await Promise.race([ 16 slow(150, "primary"), 17 slow(80, "replica"), 18 ]); 19 console.log("race winner:", winner); ``` Real output (Node v22): ```plaintext 1 all: [ 'user', 'posts', 'profile' ] 2 race winner: replica ``` Two JavaScript subtleties to keep in mind, because they differ in Rust: * `Promise.all` rejects on the **first** rejection (fail-fast), but the other promises **keep running** in the background; JavaScript has no built-in cancellation. ```typescript 1 // Promise.all is fail-fast on rejection: 2 try { 3 await Promise.all([slow(120, "ok"), reject(40, "boom"), slow(150, "ok2")]); 4 } catch (e) { 5 console.log("all rejected with:", e); // -> "boom" 6 } ``` * `Promise.race` settles on the first *settled* promise; the losers are **not** cancelled — their timers and side effects continue. This is the single biggest behavioral difference from Rust’s `select!`, which **drops** (cancels) the losing futures. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same fan-out in Rust uses `tokio::join!`. Each `fetch_*` call builds a lazy future; `join!` polls all of them concurrently on the current task and hands back a **tuple** (not an array; the results can have different types). ```rust 1 use std::time::Instant; 2 use tokio::time::{sleep, Duration}; 3 4 #[derive(Debug)] 5 struct User { id: u64, name: String } 6 #[derive(Debug)] 7 struct Posts { count: u32 } 8 #[derive(Debug)] 9 struct Profile { bio: String } 10 11 async fn fetch_user(id: u64) -> User { 12 sleep(Duration::from_millis(120)).await; 13 User { id, name: format!("user-{id}") } 14 } 15 16 async fn fetch_posts(_id: u64) -> Posts { 17 sleep(Duration::from_millis(90)).await; 18 Posts { count: 7 } 19 } 20 21 async fn fetch_profile(_id: u64) -> Profile { 22 sleep(Duration::from_millis(150)).await; 23 Profile { bio: "Rustacean".to_string() } 24 } 25 26 #[tokio::main] 27 async fn main() { 28 let start = Instant::now(); 29 30 // Like Promise.all: run all three concurrently, wait for ALL, get a tuple. 31 let (user, posts, profile) = tokio::join!( 32 fetch_user(42), 33 fetch_posts(42), 34 fetch_profile(42), 35 ); 36 37 println!("user: {} (id {})", user.name, user.id); 38 println!("posts: {}", posts.count); 39 println!("profile: {}", profile.bio); 40 println!("all done in ~{} ms", start.elapsed().as_millis()); 41 } ``` Real output (compiled with Rust 1.96, Tokio 1.52): ```plaintext 1 user: user-42 (id 42) 2 posts: 7 3 profile: Rustacean 4 all done in ~152 ms ``` The total is \~150 ms — the duration of the *slowest* branch — not 120 + 90 + 150. That is concurrency: all three timers count down together. And for `Promise.race`, the Rust analogue is `tokio::select!`: ```rust 1 use tokio::time::{sleep, Duration}; 2 3 async fn primary() -> &'static str { 4 sleep(Duration::from_millis(150)).await; 5 "primary" 6 } 7 8 async fn replica() -> &'static str { 9 sleep(Duration::from_millis(80)).await; 10 "replica" 11 } 12 13 #[tokio::main] 14 async fn main() { 15 // Like Promise.race: whichever finishes FIRST wins; the loser is DROPPED. 16 let winner = tokio::select! { 17 v = primary() => v, 18 v = replica() => v, 19 }; 20 println!("answered by: {winner}"); 21 } ``` Real output: ```plaintext 1 answered by: replica ``` > **Note:** These examples use the repository’s [pinned verification toolchain](/00-introduction/05-version-policy/), the 2024 edition (selected automatically by `cargo new`), and Tokio 1.x: `cargo add tokio --features full`. See [Setting Up Tokio](/11-async/03-tokio-setup/). *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `join!` — wait for all, keep every result [Section titled “join! — wait for all, keep every result”](#join--wait-for-all-keep-every-result) `tokio::join!(a, b, c)` takes one or more futures, polls them concurrently on the current task, and completes when **all** have finished, returning a tuple `(A, B, C)` of their outputs in argument order. ```rust 1 async fn a() -> i32 { 1 } 2 async fn b() -> String { "two".to_string() } 3 async fn c() -> bool { true } 4 5 #[tokio::main] 6 async fn main() { 7 // Heterogeneous results come back as a typed tuple, not an array. 8 let (x, y, z): (i32, String, bool) = tokio::join!(a(), b(), c()); 9 println!("{x} {y} {z}"); 10 } ``` Real output: ```plaintext 1 1 two true ``` This is the first place the JavaScript analogy bends. `Promise.all([a, b, c])` returns an **array**, and TypeScript leans on tuple types to track the (possibly different) element types. Rust’s `join!` returns an honest, statically-typed **tuple**: no casting, no `as const`. > **Tip:** `join!` interleaves futures on *one* task. It does **not** use multiple threads, so it will not speed up CPU-bound work — only IO-bound work where each future spends most of its time waiting. For CPU parallelism, spawn tasks (`tokio::spawn`) on a multi-thread runtime or use threads. See [Async vs Sync](/11-async/13-async-vs-sync/). ### `try_join!` — wait for all, but short-circuit on the first error [Section titled “try\_join! — wait for all, but short-circuit on the first error”](#try_join--wait-for-all-but-short-circuit-on-the-first-error) When every future returns `Result<T, E>`, `tokio::try_join!` waits for all of them to succeed and gives you `Ok((T1, T2, ...))`. But the moment any future returns `Err`, it stops and returns that error immediately. This is the `Promise.all`-with-rejection pattern, made explicit by Rust’s `Result` type. ```rust 1 use std::time::Instant; 2 use tokio::time::{sleep, Duration}; 3 4 async fn fetch_user(id: u64) -> Result<String, String> { 5 sleep(Duration::from_millis(120)).await; 6 Ok(format!("user-{id}")) 7 } 8 9 async fn fetch_posts(_id: u64) -> Result<u32, String> { 10 sleep(Duration::from_millis(40)).await; 11 Err("posts service is down".to_string()) // fails fast 12 } 13 14 async fn fetch_profile(_id: u64) -> Result<String, String> { 15 sleep(Duration::from_millis(150)).await; 16 Ok("Rustacean".to_string()) 17 } 18 19 #[tokio::main] 20 async fn main() { 21 let start = Instant::now(); 22 23 // Short-circuits on the FIRST Err — does not wait for the slow profile fetch. 24 let result = tokio::try_join!( 25 fetch_user(42), 26 fetch_posts(42), 27 fetch_profile(42), 28 ); 29 30 match result { 31 Ok((user, posts, profile)) => println!("ok: {user}, {posts} posts, {profile}"), 32 Err(e) => println!("failed after ~{} ms: {e}", start.elapsed().as_millis()), 33 } 34 } ``` Real output: ```plaintext 1 failed after ~41 ms: posts service is down ``` It returned after \~40 ms (the moment `fetch_posts` failed) without waiting for the 150 ms profile fetch. **Importantly, the still-running futures are dropped (cancelled).** Unlike JavaScript, where the other promises in a rejected `Promise.all` keep executing, Rust cancels them because `try_join!` simply stops polling them and they go out of scope. All branches must share the **same error type `E`** (or one that the others convert into via `?`/`From`), which is exactly the discipline Rust’s `Result` already enforces. See [Section 08: Error Handling](/08-error-handling/). ### `select!` — first to finish wins, the rest are cancelled [Section titled “select! — first to finish wins, the rest are cancelled”](#select--first-to-finish-wins-the-rest-are-cancelled) `tokio::select!` polls several futures and runs the body of **whichever finishes first**, then **drops all the other futures**. Each arm is `pattern = future => expression`, and `select!` evaluates to the chosen arm’s expression, so all arms must produce a compatible type. ```rust 1 use tokio::time::{sleep, Duration}; 2 3 async fn from_cache() -> Option<String> { 4 sleep(Duration::from_millis(120)).await; 5 Some("cached value".to_string()) 6 } 7 8 async fn from_origin() -> Option<String> { 9 sleep(Duration::from_millis(50)).await; 10 Some("origin value".to_string()) 11 } 12 13 #[tokio::main] 14 async fn main() { 15 // First arm to complete provides the value; the other future is dropped. 16 let value = tokio::select! { 17 v = from_cache() => v, 18 v = from_origin() => v, 19 }; 20 println!("served: {value:?}"); 21 } ``` Real output: ```plaintext 1 served: Some("origin value") ``` The pattern position (`v = ...`) can destructure, which lets a `select!` arm fire only on a *matching* result. A common idiom is `Some(x) = stream_or_channel.recv() => { ... }`, which simply skips that arm (and considers it permanently disabled if all arms become disabled) when the future yields a non-matching value. ### `select!` actually *cancels* the losers — and that has consequences [Section titled “select! actually cancels the losers — and that has consequences”](#select-actually-cancels-the-losers--and-that-has-consequences) This is the headline difference from `Promise.race`. When a `select!` arm wins, the other futures are **dropped mid-flight**: any work they had not yet completed never runs. The following makes that visible. Each branch logs every step it completes: ```rust 1 use tokio::time::{sleep, Duration}; 2 3 async fn step_writer(label: &str, steps: u32) -> &str { 4 for i in 1..=steps { 5 sleep(Duration::from_millis(40)).await; 6 println!(" {label}: step {i}"); 7 } 8 label 9 } 10 11 #[tokio::main] 12 async fn main() { 13 let winner = tokio::select! { 14 v = step_writer("fast", 2) => v, 15 v = step_writer("slow", 10) => v, 16 }; 17 // The "slow" future is DROPPED partway through — steps 3..=10 never run. 18 println!("winner: {winner}"); 19 } ``` Real output: ```plaintext 1 slow: step 1 2 fast: step 1 3 slow: step 2 4 fast: step 2 5 winner: fast ``` `slow` got through step 2, then `fast` finished and won, and `slow`’s remaining eight steps **never executed**. In JavaScript, the losing promise would have run all ten “steps” to completion regardless. This cancellation is a feature (it is how timeouts and graceful shutdown work) but it means a `select!` branch can be interrupted at any `.await` point. That property is called **cancellation safety**; not every future is safe to cancel mid-operation, so consult a type’s docs before racing it. ### `select!` in a loop — the async event loop [Section titled “select! in a loop — the async event loop”](#select-in-a-loop--the-async-event-loop) Because `select!` returns after a single event, it is almost always used inside a `loop` to build an event-driven task that reacts to whichever source is ready: a channel message, a timer tick, a shutdown signal. This is the closest Rust comes to Node’s “one event loop handling many sources.” ```rust 1 use tokio::sync::{mpsc, oneshot}; 2 use tokio::time::{sleep, Duration}; 3 4 #[tokio::main] 5 async fn main() { 6 let (work_tx, mut work_rx) = mpsc::channel::<u32>(8); 7 let (shutdown_tx, mut shutdown_rx) = oneshot::channel::<()>(); 8 9 // Producer: send three jobs, then signal shutdown. 10 tokio::spawn(async move { 11 for i in 1..=3 { 12 work_tx.send(i).await.unwrap(); 13 sleep(Duration::from_millis(20)).await; 14 } 15 sleep(Duration::from_millis(20)).await; 16 let _ = shutdown_tx.send(()); 17 }); 18 19 let mut processed = 0u32; 20 loop { 21 tokio::select! { 22 // Fires when a job arrives; the `Some(...)` pattern disables this 23 // arm if the channel closes (recv() returns None). 24 Some(job) = work_rx.recv() => { 25 processed += 1; 26 println!("processing job {job}"); 27 } 28 // Fires once, when the shutdown signal is sent. 29 _ = &mut shutdown_rx => { 30 println!("shutdown signal received; processed {processed} jobs"); 31 break; 32 } 33 } 34 } 35 } ``` Real output: ```plaintext 1 processing job 1 2 processing job 2 3 processing job 3 4 shutdown signal received; processed 3 jobs ``` Note `&mut shutdown_rx`: the `oneshot::Receiver` is awaited *by mutable reference* so it survives across loop iterations rather than being moved (and dropped) on the first poll. The channels here are covered in [Async Channels](/11-async/08-channels/). ### `biased` — opt out of random polling order [Section titled “biased — opt out of random polling order”](#biased--opt-out-of-random-polling-order) By default, `select!` checks its arms in a **random** order on each poll to avoid starving any branch. When you want a deterministic priority (for example, “always drain pending work before checking the timer”), add `biased;` as the first line; arms are then polled top-to-bottom. ```rust 1 use tokio::sync::mpsc; 2 3 #[tokio::main] 4 async fn main() { 5 let (tx, mut rx) = mpsc::unbounded_channel::<u32>(); 6 for i in 1..=3 { tx.send(i).unwrap(); } 7 drop(tx); 8 9 let mut count = 0; 10 loop { 11 tokio::select! { 12 biased; // poll arms in written order, not randomly 13 14 maybe = rx.recv() => match maybe { 15 Some(n) => { count += 1; println!("drained {n}"); } 16 None => break, 17 } 18 } 19 } 20 println!("drained {count} items"); 21 } ``` Real output: ```plaintext 1 drained 1 2 drained 2 3 drained 3 4 drained 3 items ``` ### `join_all` / `try_join_all` — when the count is dynamic [Section titled “join\_all / try\_join\_all — when the count is dynamic”](#join_all--try_join_all--when-the-count-is-dynamic) `join!` and `try_join!` are macros with a *fixed* number of arms known at compile time. When you have a **`Vec` of futures** whose length is decided at runtime (the most common real-world case), use the `futures` crate’s `join_all` / `try_join_all`, which take an iterator of futures and return a `Vec` of results. ```rust 1 use futures::future::join_all; 2 use tokio::time::{sleep, Duration}; 3 4 async fn fetch(id: u32) -> u32 { 5 sleep(Duration::from_millis(50)).await; 6 id * 10 7 } 8 9 #[tokio::main] 10 async fn main() { 11 let ids = vec![1, 2, 3, 4, 5]; 12 13 // Promise.all over a dynamic array: build a Vec of futures, drive them together. 14 let futures = ids.into_iter().map(fetch); 15 let results: Vec<u32> = join_all(futures).await; 16 17 println!("{results:?}"); 18 } ``` Real output: ```plaintext 1 [10, 20, 30, 40, 50] ``` `try_join_all` is the fail-fast variant: it returns `Result<Vec<T>, E>`, short-circuiting on the first `Err` just like `try_join!`. ```rust 1 use futures::future::try_join_all; 2 use tokio::time::{sleep, Duration}; 3 4 async fn fetch(id: u32) -> Result<u32, String> { 5 sleep(Duration::from_millis(30)).await; 6 if id == 3 { Err(format!("id {id} not found")) } else { Ok(id * 10) } 7 } 8 9 #[tokio::main] 10 async fn main() { 11 let ids = vec![1, 2, 3, 4]; 12 let result: Result<Vec<u32>, String> = try_join_all(ids.into_iter().map(fetch)).await; 13 println!("{result:?}"); 14 } ``` Real output: ```plaintext 1 Err("id 3 not found") ``` > **Tip:** `join_all` runs everything concurrently *but still on one task* and unboundedly. If you have 10,000 futures you usually want bounded concurrency instead. Reach for [`futures::stream::StreamExt::buffer_unordered`](/11-async/06-streams/) (limit in-flight futures) or spawn a bounded number of [tasks](/11-async/09-spawning-tasks/) guarded by a [`Semaphore`](/11-async/11-sync-primitives/). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | JavaScript | Rust (Tokio) | Notes | | ----------------------- | -------------------------------- | ---------------------------------------------- | ------------------------------------------------------------ | | Wait for all | `Promise.all([...])` → array | `join!(a, b)` → tuple; `join_all(vec)` → `Vec` | Tuple keeps distinct types; macro arms are fixed-count | | Wait for all, fail fast | `Promise.all` (rejects on first) | `try_join!` / `try_join_all` | All arms share one error type `E` | | First to finish | `Promise.race([...])` | `select! { ... }` | `select!` **cancels losers**; `race` does not | | First to *succeed* | `Promise.any([...])` | no direct macro; loop/`select!` or `select_ok` | See pitfalls | | All settled (no fail) | `Promise.allSettled([...])` | `join!` of `Result`-returning futures | Each tuple slot is its own `Result` | | Losers after winner | keep running | **dropped / cancelled** | The defining difference | | Concurrency model | built-in event loop, microtasks | one task interleaves futures via `poll` | No threads unless you spawn | | Eager vs lazy | promises already running | futures do nothing until the macro polls them | See [Promises vs Futures](/11-async/00-promises-vs-futures/) | ### Why these are macros, not functions [Section titled “Why these are macros, not functions”](#why-these-are-macros-not-functions) `join!`, `try_join!`, and `select!` are **macros** because they need to expand into a single state machine that owns and polls every branch *in place*, on the current task, without heap allocation or boxing. A plain function could not accept a variable list of differently-typed futures and unwrap them into a tuple while polling them together. The macro generates the `poll` loop that drives all branches and wakes correctly when any one of them is ready. ### `select!` is not `Promise.race` — it cancels [Section titled “select! is not Promise.race — it cancels”](#select-is-not-promiserace--it-cancels) Internalize this: **`Promise.race` lets the losers run; `select!` drops them.** That makes `select!` the right tool for timeouts and cancellation (the loser *should* stop), but a hazard when a losing branch was halfway through something that must not be abandoned (a partial database write, a half-consumed message). If a branch is not cancellation-safe, do its work on a [spawned task](/11-async/09-spawning-tasks/) and `select!` on the task’s `JoinHandle` instead, so the work continues even if `select!` moves on. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Reusing a future after it was moved into `select!`/`join!` [Section titled “Pitfall 1: Reusing a future after it was moved into select!/join!”](#pitfall-1-reusing-a-future-after-it-was-moved-into-selectjoin) These macros **take ownership** of the futures you pass in. A future is not `Copy`, so you cannot use it again afterward: the loser of a `select!` is gone. ```rust 1 use tokio::time::{sleep, Duration}; 2 3 async fn work(label: &str) -> &str { 4 sleep(Duration::from_millis(50)).await; 5 label 6 } 7 8 #[tokio::main] 9 async fn main() { 10 let a = work("a"); 11 let b = work("b"); 12 13 let first = tokio::select! { 14 v = a => v, 15 v = b => v, 16 }; 17 println!("first: {first}"); 18 19 let second = b.await; // does not compile (error[E0382]: use of moved value: `b`) 20 println!("second: {second}"); 21 } ``` Real compiler error: ```plaintext 1 error[E0382]: use of moved value: `b` 2 --> src/main.rs:20:18 3 | 4 11 | let b = work("b"); 5 | - move occurs because `b` has type `impl Future<Output = &str>`, which does not implement the `Copy` trait 6 ... 7 15 | v = b => v, 8 | - value moved here 9 ... 10 20 | let second = b.await; 11 | ^ value used here after move ``` If you genuinely need to keep awaiting a branch across iterations (the event-loop case), pass it **by mutable reference** — `v = &mut b => ...` — and ensure it is `Unpin` or pinned (e.g. `tokio::pin!(b)`), as shown with `&mut shutdown_rx` earlier. ### Pitfall 2: Expecting `select!`’s losers to keep running (the `Promise.race` mental model) [Section titled “Pitfall 2: Expecting select!’s losers to keep running (the Promise.race mental model)”](#pitfall-2-expecting-selects-losers-to-keep-running-the-promiserace-mental-model) A JavaScript developer naturally assumes the slow branch finishes “in the background.” It does not — it is cancelled. If you wrote a `select!` to *kick off* two operations and only *report* the first, but you actually needed both to complete, `select!` is the wrong tool. ```rust 1 // Compiles and runs, but the slow branch is CANCELLED, not backgrounded. 2 let _first = tokio::select! { 3 v = important_write_then_value() => v, // if this loses, the write never happens! 4 v = fast_value() => v, 5 }; ``` If both operations matter, spawn them as tasks and either `join!` their handles or `select!` on the handles (so the loser keeps making progress on its own task). See [Spawning Tasks](/11-async/09-spawning-tasks/). ### Pitfall 3: Blocking inside a branch stalls *every* branch [Section titled “Pitfall 3: Blocking inside a branch stalls every branch”](#pitfall-3-blocking-inside-a-branch-stalls-every-branch) `join!`/`select!` interleave futures on **one** task, so a synchronous, blocking call inside any arm (a `std::thread::sleep`, a CPU-heavy loop, blocking file IO) freezes *all* the concurrent branches, and on a current-thread runtime, the whole runtime. The fix is to keep arms `.await`-friendly and offload blocking work with [`tokio::task::spawn_blocking`](/11-async/09-spawning-tasks/), or use the async timer `tokio::time::sleep` rather than `std::thread::sleep`. This is a *runtime-stall* trap, not a compile error, which makes it easy to miss. See [Async vs Sync](/11-async/13-async-vs-sync/). ### Pitfall 4: There is no built-in `Promise.any`/`Promise.allSettled` macro [Section titled “Pitfall 4: There is no built-in Promise.any/Promise.allSettled macro”](#pitfall-4-there-is-no-built-in-promiseanypromiseallsettled-macro) Rust’s three macros do not cover *every* JavaScript combinator one-to-one: * **`Promise.any`** (first to *succeed*, ignore failures): there is no `try_any!` macro. Use `futures::future::select_ok` for a collection, or a `select!`/loop that keeps going until an arm yields `Ok`. * **`Promise.allSettled`** (wait for all, never fail, collect every outcome): use `join!`/`join_all` over futures that each return `Result<T, E>`; you get a tuple/`Vec` of `Result`s, each independently `Ok` or `Err`. Reaching for a non-existent macro and then assuming `try_join!` “ignores errors” (it does the opposite: it fails fast) is a common early mistake. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Use `join!` for “all of these, keep going on success.”** When every branch returns a plain value (or you want every outcome regardless of error), `join!` is clearest. Use `try_join!` only when a single failure should abort the whole group. * **Prefer `tokio::time::timeout(dur, fut)` over hand-rolling a `select!` timeout.** It is the idiomatic, readable way to bound a single future and returns `Result<T, Elapsed>`. Reserve a `select!` timeout branch for when you are already racing multiple things. * **Wrap `select!` in a `loop` for long-lived, event-driven tasks** (servers, supervisors), and add a dedicated shutdown branch (a `oneshot`/`watch` channel) so the loop can exit cleanly. See [Async Channels](/11-async/08-channels/). * **Reach for `join_all`/`try_join_all` when the future count is dynamic**, and bound the concurrency (`buffer_unordered`, a `Semaphore`) when the count can be large. * **Know your cancellation safety.** Before putting a future in a `select!` arm, ask “is it OK if this is dropped at an `.await`?” If not, move it onto a spawned task and select on the `JoinHandle`. * **Don’t fake concurrency with sequential `.await`s.** Two `fut_a.await; fut_b.await;` run one after another. If you wanted them concurrent, that is precisely what these macros are for. See [Promises vs Futures](/11-async/00-promises-vs-futures/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A pricing service queries several regional mirrors and uses the **fastest** response (a `select!` race with an overall deadline), while *simultaneously* fetching the current FX rate it needs to convert the price (a `join!` of the race against the rate fetch). This combines `select!` and `join!` in one realistic flow. ```rust 1 use std::time::Instant; 2 use tokio::time::{sleep, Duration}; 3 4 #[derive(Debug)] 5 struct Quote { mirror: &'static str, price_cents: u64 } 6 #[derive(Debug)] 7 struct ExchangeRate { usd_to_eur: f64 } 8 9 /// One mirror's quote; different regions have different latencies. 10 async fn quote_from(mirror: &'static str, latency_ms: u64, price: u64) -> Quote { 11 sleep(Duration::from_millis(latency_ms)).await; 12 Quote { mirror, price_cents: price } 13 } 14 15 /// A separate dependency we also need. 16 async fn fetch_rate() -> ExchangeRate { 17 sleep(Duration::from_millis(70)).await; 18 ExchangeRate { usd_to_eur: 0.92 } 19 } 20 21 /// Race the mirrors (Promise.race style) but cap the whole thing with a deadline. 22 async fn fastest_quote() -> Option<Quote> { 23 tokio::select! { 24 q = quote_from("us-east", 130, 19_900) => Some(q), 25 q = quote_from("eu-west", 60, 20_050) => Some(q), 26 q = quote_from("ap-south", 200, 19_800) => Some(q), 27 _ = sleep(Duration::from_millis(150)) => None, // deadline arm 28 } 29 } 30 31 #[tokio::main] 32 async fn main() { 33 let start = Instant::now(); 34 35 // Promise.all style: race the mirrors AND fetch the FX rate concurrently. 36 let (quote, rate) = tokio::join!(fastest_quote(), fetch_rate()); 37 38 match quote { 39 Some(q) => { 40 let eur = q.price_cents as f64 / 100.0 * rate.usd_to_eur; 41 println!( 42 "best quote ${:.2} from {} -> {:.2} EUR (in ~{} ms)", 43 q.price_cents as f64 / 100.0, 44 q.mirror, 45 eur, 46 start.elapsed().as_millis() 47 ); 48 } 49 None => println!("all mirrors missed the 150 ms deadline"), 50 } 51 } ``` Real output: ```plaintext 1 best quote $200.50 from eu-west -> 184.46 EUR (in ~72 ms) ``` The fastest mirror (`eu-west`, 60 ms) won the `select!` race; the slower mirrors were cancelled by the deadline-aware race; and because the rate fetch (70 ms) ran concurrently via `join!`, the whole operation finished in \~72 ms instead of 60 + 70 = 130 ms. This is exactly the kind of layered concurrency `Promise.race` inside `Promise.all` gives you in JavaScript, but with cancellation of the losing mirrors thrown in for free. > **Note:** Real network calls would return `Result`, so you would likely use `try_join!` for the combine step and propagate errors with `?` (see [Async/Await Syntax](/11-async/01-async-await/) and [Section 08: Error Handling](/08-error-handling/)). Sleeps stand in for IO here to keep the example self-contained. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [`tokio::join!`](https://docs.rs/tokio/latest/tokio/macro.join.html): wait for all * [`tokio::try_join!`](https://docs.rs/tokio/latest/tokio/macro.try_join.html) — wait for all, fail fast * [`tokio::select!`](https://docs.rs/tokio/latest/tokio/macro.select.html): first to finish wins, the rest are cancelled * [Tokio Tutorial — `select`](https://tokio.rs/tokio/tutorial/select) — cancellation safety, the `loop { select! }` pattern * [`futures::future::join_all`](https://docs.rs/futures/latest/futures/future/fn.join_all.html) / [`try_join_all`](https://docs.rs/futures/latest/futures/future/fn.try_join_all.html): dynamic collections of futures * [`tokio::time::timeout`](https://docs.rs/tokio/latest/tokio/time/fn.timeout.html) — the idiomatic single-future timeout ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Promises vs Futures](/11-async/00-promises-vs-futures/): eager vs lazy; why building futures isn’t enough * [Async/Await Syntax](/11-async/01-async-await/) — `async`/`await` syntax and `?` error handling * [The Tokio Runtime](/11-async/02-tokio-intro/) and [Setting Up Tokio](/11-async/03-tokio-setup/): adding and configuring the runtime * [Streams](/11-async/06-streams/) — `buffer_unordered` for bounded concurrency over many futures * [Async Channels](/11-async/08-channels/): `mpsc`/`oneshot`/`watch`, the sources you `select!` on * [Spawning Tasks](/11-async/09-spawning-tasks/) — `tokio::spawn`, `JoinHandle`, `spawn_blocking`; run branches on separate tasks * [Concurrency vs Parallelism](/11-async/10-concurrency/): concurrency vs parallelism; structured patterns; cancellation * [Async vs Sync](/11-async/13-async-vs-sync/) — why blocking inside a branch stalls everything * [Section 00: Introduction](/00-introduction/), [Section 01: Getting Started](/01-getting-started/), [Section 02: Basics](/02-basics/) * [Section 08: Error Handling](/08-error-handling/): the `Result`/`?` model `try_join!` relies on * [Section 12: Modules & Packages](/12-modules-packages/) — how `tokio` and `futures` crates are added *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: From sequential to concurrent with `join!` [Section titled “Exercise 1: From sequential to concurrent with join!”](#exercise-1-from-sequential-to-concurrent-with-join) **Difficulty:** Beginner **Objective:** Replace two sequential `.await`s with a `join!` so both run concurrently. **Instructions:** The program below fetches weather and news one after another, taking \~200 ms. Rewrite it so both run concurrently (\~100 ms total) and keep both results. Do not change the two `async fn`s. ```rust 1 use std::time::Instant; 2 use tokio::time::{sleep, Duration}; 3 4 async fn fetch_weather(city: &str) -> String { 5 sleep(Duration::from_millis(100)).await; 6 format!("{city}: sunny") 7 } 8 9 async fn fetch_news(city: &str) -> String { 10 sleep(Duration::from_millis(100)).await; 11 format!("{city}: all quiet") 12 } 13 14 #[tokio::main] 15 async fn main() { 16 let start = Instant::now(); 17 let weather = fetch_weather("Berlin").await; // TODO: make these 18 let news = fetch_news("Berlin").await; // TODO: concurrent 19 println!("{weather}"); 20 println!("{news}"); 21 println!("done in ~{} ms", start.elapsed().as_millis()); 22 } ``` Solution Combine the two futures with `tokio::join!`. Building them is not enough. The macro is what drives them together. ```rust 1 use std::time::Instant; 2 use tokio::time::{sleep, Duration}; 3 4 async fn fetch_weather(city: &str) -> String { 5 sleep(Duration::from_millis(100)).await; 6 format!("{city}: sunny") 7 } 8 9 async fn fetch_news(city: &str) -> String { 10 sleep(Duration::from_millis(100)).await; 11 format!("{city}: all quiet") 12 } 13 14 #[tokio::main] 15 async fn main() { 16 let start = Instant::now(); 17 let (weather, news) = tokio::join!( 18 fetch_weather("Berlin"), 19 fetch_news("Berlin"), 20 ); 21 println!("{weather}"); 22 println!("{news}"); 23 println!("done in ~{} ms", start.elapsed().as_millis()); 24 } ``` Output: ```plaintext 1 Berlin: sunny 2 Berlin: all quiet 3 done in ~102 ms ``` ### Exercise 2: Bound a slow operation with a timeout [Section titled “Exercise 2: Bound a slow operation with a timeout”](#exercise-2-bound-a-slow-operation-with-a-timeout) **Difficulty:** Intermediate **Objective:** Use `select!` to race work against a timer so a slow operation cannot hang forever. **Instructions:** `build_report` takes 300 ms. Use a `tokio::select!` with a 150 ms timer branch so that if the report is not ready in time, the program prints `report timed out` instead of waiting. Then, in the solution, note the idiomatic one-liner alternative. ```rust 1 use tokio::time::{sleep, Duration}; 2 3 async fn build_report() -> String { 4 sleep(Duration::from_millis(300)).await; 5 "report ready".to_string() 6 } 7 8 #[tokio::main] 9 async fn main() { 10 // TODO: race build_report() against a 150 ms timer with select! 11 let report = build_report().await; 12 println!("{report}"); 13 } ``` Solution Add a timer arm; whichever finishes first wins, and the loser is cancelled. ```rust 1 use tokio::time::{sleep, Duration}; 2 3 async fn build_report() -> String { 4 sleep(Duration::from_millis(300)).await; 5 "report ready".to_string() 6 } 7 8 #[tokio::main] 9 async fn main() { 10 let result = tokio::select! { 11 report = build_report() => Ok(report), 12 _ = sleep(Duration::from_millis(150)) => Err("report timed out"), 13 }; 14 15 match result { 16 Ok(r) => println!("{r}"), 17 Err(e) => println!("{e}"), 18 } 19 } ``` Output: ```plaintext 1 report timed out ``` The idiomatic shortcut for “bound a single future with a timeout” is `tokio::time::timeout`, which does exactly this and returns `Result<T, Elapsed>`: ```rust 1 use tokio::time::{sleep, timeout, Duration}; 2 3 async fn build_report() -> String { 4 sleep(Duration::from_millis(300)).await; 5 "report ready".to_string() 6 } 7 8 #[tokio::main] 9 async fn main() { 10 match timeout(Duration::from_millis(150), build_report()).await { 11 Ok(report) => println!("{report}"), 12 Err(_elapsed) => println!("report timed out"), 13 } 14 } ``` Output: ```plaintext 1 report timed out ``` ### Exercise 3: A `select!` loop with graceful shutdown [Section titled “Exercise 3: A select! loop with graceful shutdown”](#exercise-3-a-select-loop-with-graceful-shutdown) **Difficulty:** Advanced **Objective:** Build an event-driven task that processes jobs from a channel and stops cleanly on a shutdown signal. **Instructions:** A producer sends three jobs on an `mpsc` channel, then fires a `oneshot` shutdown signal. Write a `loop { tokio::select! { ... } }` that processes each job as it arrives and `break`s when the shutdown signal fires, printing how many jobs it processed. Remember that the `oneshot` receiver must be awaited by `&mut` so it survives across iterations. ```rust 1 use tokio::sync::{mpsc, oneshot}; 2 use tokio::time::{sleep, Duration}; 3 4 #[tokio::main] 5 async fn main() { 6 let (work_tx, mut work_rx) = mpsc::channel::<u32>(8); 7 let (shutdown_tx, mut shutdown_rx) = oneshot::channel::<()>(); 8 9 tokio::spawn(async move { 10 for i in 1..=3 { 11 work_tx.send(i).await.unwrap(); 12 sleep(Duration::from_millis(20)).await; 13 } 14 sleep(Duration::from_millis(20)).await; 15 let _ = shutdown_tx.send(()); 16 }); 17 18 let mut processed = 0u32; 19 // TODO: loop { select! { job arm; shutdown arm } } 20 } ``` Solution ```rust 1 use tokio::sync::{mpsc, oneshot}; 2 use tokio::time::{sleep, Duration}; 3 4 #[tokio::main] 5 async fn main() { 6 let (work_tx, mut work_rx) = mpsc::channel::<u32>(8); 7 let (shutdown_tx, mut shutdown_rx) = oneshot::channel::<()>(); 8 9 tokio::spawn(async move { 10 for i in 1..=3 { 11 work_tx.send(i).await.unwrap(); 12 sleep(Duration::from_millis(20)).await; 13 } 14 sleep(Duration::from_millis(20)).await; 15 let _ = shutdown_tx.send(()); 16 }); 17 18 let mut processed = 0u32; 19 loop { 20 tokio::select! { 21 // `Some(...)` pattern: this arm disables itself if the channel closes. 22 Some(job) = work_rx.recv() => { 23 processed += 1; 24 println!("processing job {job}"); 25 } 26 // `&mut` so the receiver isn't moved/dropped on the first poll. 27 _ = &mut shutdown_rx => { 28 println!("shutdown signal received; processed {processed} jobs"); 29 break; 30 } 31 } 32 } 33 } ``` Output: ```plaintext 1 processing job 1 2 processing job 2 3 processing job 3 4 shutdown signal received; processed 3 jobs ``` This is the canonical long-lived async task: react to whichever source is ready, and exit cleanly on a shutdown channel. The channel types are covered in [Async Channels](/11-async/08-channels/). # Async Channels > Tokio's mpsc, oneshot, broadcast, and watch channels let async tasks talk without shared memory, replacing EventEmitter and queues with compile-time guarantees. Channels are how independent async tasks talk to each other without sharing memory directly. If you have reached for `EventEmitter`, a `MessageChannel`, an RxJS `Subject`, or a hand-rolled queue in Node.js, Tokio’s channel family covers the same ground, but with compile-time guarantees about who can send, who can receive, and what happens on shutdown. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **channel** is a typed pipe: one or more producers push values in, one or more consumers pull them out. Tokio ships four flavors: **`mpsc`** (multi-producer, single-consumer queue), **`oneshot`** (a single value, once), **`broadcast`** (every subscriber sees every message), and **`watch`** (subscribers see only the latest value). They are the idiomatic way to coordinate tasks, because passing ownership of a value through a channel sidesteps the shared-mutable-state problems that `Arc<Mutex<T>>` solves at a higher cost. The important contrast for a JavaScript developer: these are **async** channels whose `recv`/`send` operations `.await` and yield to the runtime instead of blocking a thread. The standard library’s `std::sync::mpsc` looks similar but **blocks the OS thread**, which would stall a Tokio worker, so inside async code you almost always want the Tokio versions. > **Note:** Every runnable Rust snippet on this page was compiled and executed with `rustc`/`cargo` 1.96.0 (the recorded verification toolchain; 2024 edition). Examples use `tokio = { version = "1.52", features = ["full"] }`. Rust ships **no built-in async runtime** — see [Tokio Setup](/11-async/03-tokio-setup/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) JavaScript has no single “channel” primitive, so the same job is done with a grab-bag of tools. A common pattern is an async queue built on Promises, or an `EventEmitter` for fan-out. Here is a producer/consumer queue and a pub/sub emitter, the two shapes you will most want to translate: ```typescript 1 import { EventEmitter } from "node:events"; 2 3 // --- Producer/consumer: a hand-rolled async queue (mpsc-ish) --- 4 class AsyncQueue<T> { 5 private items: T[] = []; 6 private resolvers: Array<(value: T | null) => void> = []; 7 private closed = false; 8 9 send(item: T): void { 10 if (this.closed) throw new Error("queue closed"); 11 const resolve = this.resolvers.shift(); 12 if (resolve) resolve(item); 13 else this.items.push(item); 14 } 15 16 close(): void { 17 this.closed = true; 18 // Wake any pending consumers with `null` to signal end-of-stream. 19 for (const resolve of this.resolvers) resolve(null); 20 this.resolvers = []; 21 } 22 23 // Resolves to the next item, or null once closed and drained. 24 recv(): Promise<T | null> { 25 const item = this.items.shift(); 26 if (item !== undefined) return Promise.resolve(item); 27 if (this.closed) return Promise.resolve(null); 28 return new Promise((resolve) => this.resolvers.push(resolve)); 29 } 30 } 31 32 // --- Pub/sub fan-out: every listener sees every event (broadcast-ish) --- 33 const bus = new EventEmitter(); 34 bus.on("user.created", (id: number) => console.log(`audit log: ${id}`)); 35 bus.on("user.created", (id: number) => console.log(`send welcome email: ${id}`)); 36 bus.emit("user.created", 42); ``` Notice what JavaScript does *not* give you: there is no static guarantee that exactly one consumer drains the queue, no automatic “the channel is closed because every producer went away,” and `EventEmitter` is untyped (any payload, any event name). Rust’s channels encode all of that in the type system. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The `mpsc` channel is the workhorse and maps directly onto the producer/consumer queue above: ```rust 1 use tokio::sync::mpsc; 2 3 #[derive(Debug)] 4 struct Job { 5 id: u32, 6 payload: String, 7 } 8 9 #[tokio::main] 10 async fn main() { 11 // Bounded channel: at most 8 messages buffered before send() awaits. 12 let (tx, mut rx) = mpsc::channel::<Job>(8); 13 14 // Producer task. 15 let producer = tokio::spawn(async move { 16 for id in 1..=3 { 17 let job = Job { 18 id, 19 payload: format!("data-{id}"), 20 }; 21 // send() is async: it waits if the buffer is full (backpressure). 22 if tx.send(job).await.is_err() { 23 eprintln!("receiver dropped, stopping producer"); 24 break; 25 } 26 } 27 // tx dropped here when the task ends -> channel closes. 28 }); 29 30 // Consumer: recv() yields None once all senders are dropped and the buffer drains. 31 while let Some(job) = rx.recv().await { 32 println!("processing job {} with {}", job.id, job.payload); 33 } 34 println!("channel closed, all jobs done"); 35 36 producer.await.unwrap(); 37 } ``` Real output: ```plaintext 1 processing job 1 with data-1 2 processing job 2 with data-2 3 processing job 3 with data-3 4 channel closed, all jobs done ``` Two structural facts fall out of the type system for free: `mpsc::Receiver` is **not** `Clone`, so the compiler guarantees a single consumer; and when the last `Sender` is dropped, `recv()` returns `None`, so the `while let` loop ends on its own. No `closed` flag, no sentinel `null`. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `mpsc`: multi-producer, single-consumer [Section titled “mpsc: multi-producer, single-consumer”](#mpsc-multi-producer-single-consumer) `mpsc::channel::<T>(capacity)` returns a `(Sender<T>, Receiver<T>)` pair. The name encodes the contract: the **Sender is `Clone`** (many producers), the **Receiver is not** (one consumer). * `tx.send(value).await` moves `value` into the channel. On a **bounded** channel it `.await`s when the buffer is full. This is **backpressure**, a built-in flow-control mechanism that JavaScript queues lack by default. It returns `Result<(), SendError<T>>`; the `Err` arm hands your value back if the receiver is gone. * `rx.recv().await` returns `Option<T>`: `Some(value)` for each message, then `None` once **all** senders are dropped and the buffer is empty. To get multiple producers, clone the sender, but remember to drop the original so the channel can actually close: ```rust 1 use tokio::sync::mpsc; 2 3 #[tokio::main] 4 async fn main() { 5 let (tx, mut rx) = mpsc::channel::<String>(32); 6 7 // Spawn 3 producers, each gets its own clone of the sender. 8 for worker_id in 1..=3 { 9 let tx = tx.clone(); 10 tokio::spawn(async move { 11 tx.send(format!("worker {worker_id} reporting in")) 12 .await 13 .unwrap(); 14 }); 15 } 16 17 // Drop the original sender so the channel can close once the clones finish. 18 drop(tx); 19 20 let mut received = Vec::new(); 21 while let Some(msg) = rx.recv().await { 22 received.push(msg); 23 } 24 25 received.sort(); // task ordering is nondeterministic; sort for a stable print. 26 for msg in received { 27 println!("{msg}"); 28 } 29 } ``` Real output: ```plaintext 1 worker 1 reporting in 2 worker 2 reporting in 3 worker 3 reporting in ``` > **Tip:** There is also `mpsc::unbounded_channel()`. Its `send()` is **synchronous** (no `.await`, never waits) because the buffer is unlimited, but that means no backpressure, so a fast producer can grow the queue until you run out of memory. Prefer the bounded `channel(capacity)` unless you have a specific reason not to. ### `oneshot`: exactly one value, once [Section titled “oneshot: exactly one value, once”](#oneshot-exactly-one-value-once) `oneshot::channel::<T>()` is for a single reply. The `Sender::send` method **takes `self` by value**, so it can only ever be called once. The type system enforces “exactly one message.” ```rust 1 use tokio::sync::oneshot; 2 3 #[tokio::main] 4 async fn main() { 5 let (tx, rx) = oneshot::channel::<u64>(); 6 7 // Worker computes a single value and sends it back. 8 tokio::spawn(async move { 9 let result = (1..=100).sum::<u64>(); 10 // send() takes self by value -> can only be called once. Not async. 11 let _ = tx.send(result); 12 }); 13 14 // Await the single reply. Errors only if the sender was dropped without sending. 15 match rx.await { 16 Ok(value) => println!("computed sum = {value}"), 17 Err(_) => println!("worker dropped the sender without replying"), 18 } 19 } ``` Real output: ```plaintext 1 computed sum = 5050 ``` Note that the **`Receiver` is itself a future**: you `rx.await` it directly rather than calling `.recv()`. A `oneshot` is the Rust analogue of a single `Promise` whose `resolve` you hand to another task. Its most useful application is embedding the reply channel *inside* a request message, which gives you request/response over an `mpsc` (see the actor pattern below). ### `broadcast`: every subscriber sees every message [Section titled “broadcast: every subscriber sees every message”](#broadcast-every-subscriber-sees-every-message) `broadcast::channel::<T>(capacity)` is fan-out. Clone-free subscription via `tx.subscribe()`, and **each** receiver gets a copy of **every** value sent after it subscribed. The value type must be `Clone`. ```rust 1 use tokio::sync::broadcast; 2 3 #[tokio::main] 4 async fn main() { 5 // Capacity 16: each receiver has its own 16-slot ring buffer. 6 let (tx, _rx) = broadcast::channel::<String>(16); 7 8 // Two independent subscribers. Each gets EVERY message sent after it subscribed. 9 let mut rx1 = tx.subscribe(); 10 let mut rx2 = tx.subscribe(); 11 12 let sub1 = tokio::spawn(async move { 13 while let Ok(event) = rx1.recv().await { 14 println!("sub1 saw: {event}"); 15 } 16 }); 17 let sub2 = tokio::spawn(async move { 18 while let Ok(event) = rx2.recv().await { 19 println!("sub2 saw: {event}"); 20 } 21 }); 22 23 // send() returns the number of currently-subscribed receivers. 24 tx.send("user.created".to_string()).unwrap(); 25 tx.send("user.updated".to_string()).unwrap(); 26 27 // Dropping the sender closes the channel; receivers then get RecvError::Closed. 28 drop(tx); 29 30 sub1.await.unwrap(); 31 sub2.await.unwrap(); 32 } ``` Real output: ```plaintext 1 sub1 saw: user.created 2 sub1 saw: user.updated 3 sub2 saw: user.created 4 sub2 saw: user.updated ``` This is the typed, ownership-aware replacement for `EventEmitter`. The capacity matters: `broadcast` uses a **ring buffer per receiver**, so a slow consumer that falls more than `capacity` messages behind will *lag* and skip the oldest messages (covered under Common Pitfalls). ### `watch`: only the latest value matters [Section titled “watch: only the latest value matters”](#watch-only-the-latest-value-matters) `watch::channel(initial)` is for state that changes over time where consumers only care about the **current** value, not the history: config reloads, a “current health” flag, the latest sensor reading. The sender overwrites; receivers `borrow()` the newest value. ```rust 1 use tokio::sync::watch; 2 use tokio::time::{Duration, sleep}; 3 4 #[derive(Clone, Debug, PartialEq)] 5 struct Config { 6 log_level: String, 7 } 8 9 #[tokio::main] 10 async fn main() { 11 // watch holds a single latest value; receivers see the most recent one. 12 let (tx, mut rx) = watch::channel(Config { 13 log_level: "info".to_string(), 14 }); 15 16 let watcher = tokio::spawn(async move { 17 loop { 18 // changed() resolves when the value is updated since the last observation. 19 if rx.changed().await.is_err() { 20 println!("config sender dropped, watcher exiting"); 21 break; 22 } 23 // borrow() gives a read guard to the latest value. 24 let cfg = rx.borrow(); 25 println!("config changed -> log_level = {}", cfg.log_level); 26 } 27 }); 28 29 sleep(Duration::from_millis(20)).await; 30 tx.send(Config { log_level: "debug".to_string() }).unwrap(); 31 sleep(Duration::from_millis(20)).await; 32 tx.send(Config { log_level: "trace".to_string() }).unwrap(); 33 sleep(Duration::from_millis(20)).await; 34 35 drop(tx); // closes the channel; watcher's changed() returns Err and it exits. 36 watcher.await.unwrap(); 37 } ``` Real output: ```plaintext 1 config changed -> log_level = debug 2 config changed -> log_level = trace 3 config sender dropped, watcher exiting ``` If you `send` three times before a watcher calls `changed()`, it only ever sees the *last* value; intermediate values are coalesced. That is the defining difference from `broadcast`, which delivers every message. > **Warning:** Do not hold the guard returned by `watch::Receiver::borrow()` across an `.await`. It is a read lock; keeping it alive while suspended can block senders. Copy out what you need, drop the guard, then await. The same hazard applies to `tokio::sync::RwLock` — see [Async Synchronization Primitives](/11-async/11-sync-primitives/). ### Request/response: `oneshot` inside an `mpsc` message (the actor pattern) [Section titled “Request/response: oneshot inside an mpsc message (the actor pattern)”](#requestresponse-oneshot-inside-an-mpsc-message-the-actor-pattern) This is the single most useful composition. One task owns some state; everyone else talks to it by sending a request that carries its own private `oneshot` reply channel: ```rust 1 use tokio::sync::{mpsc, oneshot}; 2 3 /// A request carries a oneshot sender for its individual reply. 4 struct Request { 5 key: String, 6 reply_to: oneshot::Sender<Option<String>>, 7 } 8 9 #[tokio::main] 10 async fn main() { 11 let (tx, mut rx) = mpsc::channel::<Request>(32); 12 13 // The "actor": owns the state, processes requests one at a time. 14 let actor = tokio::spawn(async move { 15 let store = std::collections::HashMap::from([ 16 ("alice".to_string(), "admin".to_string()), 17 ("bob".to_string(), "user".to_string()), 18 ]); 19 while let Some(req) = rx.recv().await { 20 let answer = store.get(&req.key).cloned(); 21 // Reply on this request's private oneshot channel. 22 let _ = req.reply_to.send(answer); 23 } 24 }); 25 26 // A client sends a request and awaits its dedicated reply. 27 let role = lookup(&tx, "alice").await; 28 println!("alice -> {role:?}"); 29 let missing = lookup(&tx, "carol").await; 30 println!("carol -> {missing:?}"); 31 32 drop(tx); 33 actor.await.unwrap(); 34 } 35 36 async fn lookup(tx: &mpsc::Sender<Request>, key: &str) -> Option<String> { 37 let (reply_to, reply_rx) = oneshot::channel(); 38 tx.send(Request { 39 key: key.to_string(), 40 reply_to, 41 }) 42 .await 43 .expect("actor is alive"); 44 reply_rx.await.expect("actor replied") 45 } ``` Real output: ```plaintext 1 alice -> Some("admin") 2 carol -> None ``` Because the actor is the *only* task that touches `store`, there is no lock and no data race: the channel serializes access. This is how you replace `Arc<Mutex<HashMap<..>>>` with message passing. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concern | JavaScript | Rust / Tokio | | ----------------------- | ---------------------------------- | ---------------------------------------------------------------- | | Producer/consumer queue | hand-rolled, or a userland library | `tokio::sync::mpsc` (built in) | | One-shot reply | a single `Promise` you resolve | `tokio::sync::oneshot` | | Pub/sub fan-out | `EventEmitter`, RxJS `Subject` | `tokio::sync::broadcast` | | ”Latest value” state | a variable + manual notify | `tokio::sync::watch` | | Type safety of payloads | none (`any`) | fully typed `T`, checked at compile time | | Who can receive | not enforced | `mpsc::Receiver` is **not `Clone`** → single consumer guaranteed | | Backpressure | manual | bounded `mpsc::send().await` waits when full | | ”Channel closed” signal | manual flag / sentinel | automatic when all senders or the receiver drop | | Blocking vs async | event loop never blocks | Tokio channels `.await`; `std::sync::mpsc` **blocks the thread** | ### `std::sync::mpsc` vs `tokio::sync::mpsc` [Section titled “std::sync::mpsc vs tokio::sync::mpsc”](#stdsyncmpsc-vs-tokiosyncmpsc) The standard library has its own `mpsc` that *looks* like Tokio’s, and reaching for it inside async code is a classic mistake. ```rust 1 use std::sync::mpsc; // standard library, NOT tokio 2 use std::thread; 3 4 fn main() { 5 // std channel: multi-producer, single-consumer, BLOCKING (no async). 6 let (tx, rx) = mpsc::channel::<i32>(); 7 8 for n in 0..3 { 9 let tx = tx.clone(); 10 thread::spawn(move || { 11 tx.send(n * 10).unwrap(); // blocks the OS thread if needed 12 }); 13 } 14 drop(tx); 15 16 let mut total = 0; 17 // recv() blocks the thread until a value arrives or all senders drop. 18 for value in rx { 19 total += value; 20 } 21 println!("total = {total}"); 22 } ``` Real output: ```plaintext 1 total = 30 ``` The decision rule: | | `std::sync::mpsc` | `tokio::sync::mpsc` | | -------------------- | -------------------------------------------------------- | -------------------------------------- | | `recv` | **blocks the OS thread** | `.await`s, yields to the runtime | | `send` | synchronous | `.await` on bounded; sync on unbounded | | Use it for | plain threads ([05-ownership](/05-ownership/) territory) | async tasks under a runtime | | Inside a Tokio task? | **no** — it stalls a worker thread | **yes** | > **Note:** If you genuinely must call a blocking `std` channel from async (e.g. bridging a synchronous library), do it on a thread that is allowed to block via `tokio::task::spawn_blocking` — see [Spawning Tasks](/11-async/09-spawning-tasks/). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### 1. Forgetting to drop the extra `Sender`, so `recv()` never returns `None` [Section titled “1. Forgetting to drop the extra Sender, so recv() never returns None”](#1-forgetting-to-drop-the-extra-sender-so-recv-never-returns-none) `recv()` returns `None` only when **every** sender is dropped. If you clone a sender for workers but keep the original alive in scope, the consumer loop hangs forever waiting for more. The fix is the explicit `drop(tx)` shown in the multi-producer example above (or letting the original go out of scope before the loop). ### 2. Trying to clone the `mpsc::Receiver` [Section titled “2. Trying to clone the mpsc::Receiver”](#2-trying-to-clone-the-mpscreceiver) `mpsc` is single-consumer by design. Cloning the receiver to fan work out to several tasks does not compile: ```rust 1 use tokio::sync::mpsc; 2 3 #[tokio::main] 4 async fn main() { 5 let (_tx, rx) = mpsc::channel::<i32>(8); 6 // mpsc is multi-producer, SINGLE-consumer: the Receiver is not Clone. 7 let rx2 = rx.clone(); // does not compile (error[E0599]: no method named `clone`) 8 drop((rx, rx2)); 9 } ``` Real compiler error: ```plaintext 1 error[E0599]: no method named `clone` found for struct `tokio::sync::mpsc::Receiver` in the current scope 2 --> src/bin/err_clone_rx.rs:7:18 3 | 4 7 | let rx2 = rx.clone(); 5 | ^^^^^ 6 | 7 help: there is a method `close` with a similar name ``` To share one receiver across several worker tasks, wrap it in `Arc<tokio::sync::Mutex<Receiver<T>>>` (the worker pool below does exactly that), or restructure so each worker has its own channel. ### 3. Calling `oneshot::Sender::send` twice [Section titled “3. Calling oneshot::Sender::send twice”](#3-calling-oneshotsendersend-twice) `send` consumes the sender, so a second call references a moved value: ```rust 1 use tokio::sync::oneshot; 2 3 #[tokio::main] 4 async fn main() { 5 let (tx, _rx) = oneshot::channel::<i32>(); 6 tx.send(1).unwrap(); // send consumes `tx` by value 7 tx.send(2).unwrap(); // does not compile (error[E0382]: use of moved value) 8 } ``` Real compiler error (abridged): ```plaintext 1 error[E0382]: use of moved value: `tx` 2 --> src/bin/err_send_twice.rs:7:5 3 | 4 5 | let (tx, _rx) = oneshot::channel::<i32>(); 5 | -- move occurs because `tx` has type `tokio::sync::oneshot::Sender<i32>`, which does not implement the `Copy` trait 6 6 | tx.send(1).unwrap(); // send consumes `tx` by value 7 | ------- `tx` moved due to this method call 8 7 | tx.send(2).unwrap(); // ERROR: tx already moved 9 | ^^ value used here after move 10 | 11 note: `tokio::sync::oneshot::Sender::<T>::send` takes ownership of the receiver `self`, which moves `tx` ``` If you need to send more than once, you wanted `mpsc` (a stream of messages) or `watch` (the latest value), not `oneshot`. ### 4. A slow `broadcast` receiver lagging and skipping messages [Section titled “4. A slow broadcast receiver lagging and skipping messages”](#4-a-slow-broadcast-receiver-lagging-and-skipping-messages) `broadcast` keeps a fixed-size ring buffer per receiver. A consumer that falls behind by more than the capacity loses the oldest messages and `recv()` returns `Err(RecvError::Lagged(n))`. Unlike a closed channel, **lag is recoverable**: you keep receiving after it: ```rust 1 use tokio::sync::broadcast::{self, error::RecvError}; 2 3 #[tokio::main] 4 async fn main() { 5 // Tiny capacity of 2 to force lag. 6 let (tx, mut rx) = broadcast::channel::<u32>(2); 7 8 // Send 4 values before the slow receiver reads anything. 9 for n in 1..=4 { 10 tx.send(n).unwrap(); 11 } 12 13 // The first two values were overwritten in the ring buffer -> Lagged(2). 14 loop { 15 match rx.recv().await { 16 Ok(value) => println!("received {value}"), 17 Err(RecvError::Lagged(skipped)) => { 18 println!("lagged: skipped {skipped} messages"); 19 } 20 Err(RecvError::Closed) => { 21 println!("channel closed"); 22 break; 23 } 24 } 25 } 26 } ``` Real output: ```plaintext 1 lagged: skipped 2 messages 2 received 3 3 received 4 ``` Always handle `Lagged` explicitly: log it, increase the capacity, or speed up the consumer. Treating it as a fatal error is usually wrong. ### 5. Using `std::sync::mpsc::recv()` inside an async task [Section titled “5. Using std::sync::mpsc::recv() inside an async task”](#5-using-stdsyncmpscrecv-inside-an-async-task) Because `std::sync::mpsc::recv()` blocks the calling OS thread, calling it directly in a Tokio task parks one of the runtime’s worker threads. On a single-threaded runtime this **deadlocks**; on a multi-threaded runtime it silently degrades throughput. There is no compiler error — it just behaves badly. Use `tokio::sync::mpsc` in async code, or hop to `spawn_blocking` for genuinely blocking work. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Pick the channel by communication shape, not habit.** Stream of work → `mpsc`; single reply → `oneshot`; fan-out events → `broadcast`; latest-value state → `watch`. * **Prefer bounded `mpsc`.** Backpressure protects you from unbounded memory growth. Choose a capacity, and treat a full channel as a real signal about load. * **Drop senders you do not need.** A lingering `Sender` clone keeps the channel open and hangs the consumer. Let clones move into tasks; `drop` the original explicitly when the borrow checker keeps it alive. * **Always handle `broadcast`’s `Lagged`.** A slow subscriber should degrade gracefully, not crash. * **Use message passing instead of shared state when you can.** The actor pattern (an `mpsc` of requests, each carrying a `oneshot` reply) replaces `Arc<Mutex<T>>` and removes a whole class of locking bugs. When you *do* need shared state, see [The `Arc<Mutex<T>>` Pattern](/11-async/12-arc-mutex-pattern/). * **Keep `std::sync::mpsc` for plain threads.** Inside `async`, default to the Tokio family. * **Combine channels with `select!` for shutdown.** A `watch<bool>` shutdown flag plus `tokio::select!` lets a task react to either work or a stop signal — see [Concurrent Awaiting](/11-async/07-select-join/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production graceful-shutdown worker pool brings the whole family together: an `mpsc` carries jobs (with backpressure), each job carries a `oneshot` for its individual reply, and a `watch<bool>` broadcasts the shutdown signal to every worker. The single `mpsc::Receiver` is shared across workers behind an `Arc<tokio::sync::Mutex<_>>`, and `tokio::select!` lets each worker react to *either* a new job *or* the shutdown flag. ```rust 1 use tokio::sync::{mpsc, oneshot, watch}; 2 use tokio::time::{Duration, sleep}; 3 4 /// A unit of work submitted to the pool, carrying a private reply channel. 5 struct Task { 6 id: u32, 7 reply: oneshot::Sender<String>, 8 } 9 10 #[tokio::main] 11 async fn main() { 12 // Jobs flow worker-ward over a bounded mpsc (backpressure at 64). 13 let (job_tx, job_rx) = mpsc::channel::<Task>(64); 14 // A single shutdown flag broadcast to every worker via watch. 15 let (shutdown_tx, shutdown_rx) = watch::channel(false); 16 17 // Spawn a small pool. mpsc is single-consumer, so we share the Receiver 18 // behind an async Mutex; each worker pulls the next available job. 19 let job_rx = std::sync::Arc::new(tokio::sync::Mutex::new(job_rx)); 20 let mut workers = Vec::new(); 21 for worker_id in 0..3 { 22 let job_rx = job_rx.clone(); 23 let mut shutdown_rx = shutdown_rx.clone(); 24 workers.push(tokio::spawn(async move { 25 loop { 26 let task = { 27 let mut guard = job_rx.lock().await; 28 tokio::select! { 29 // Stop promptly when the shutdown flag flips to true. 30 _ = shutdown_rx.changed() => { 31 if *shutdown_rx.borrow() { break; } 32 continue; 33 } 34 maybe = guard.recv() => match maybe { 35 Some(task) => task, 36 None => break, // all senders dropped 37 }, 38 } 39 }; 40 // Simulate work, then answer this task's private oneshot. 41 sleep(Duration::from_millis(5)).await; 42 let _ = task 43 .reply 44 .send(format!("task {} handled by worker {worker_id}", task.id)); 45 } 46 })); 47 } 48 49 // Submit 5 jobs and collect their individual replies. 50 let mut replies = Vec::new(); 51 for id in 0..5 { 52 let (reply, reply_rx) = oneshot::channel(); 53 job_tx.send(Task { id, reply }).await.unwrap(); 54 replies.push(reply_rx); 55 } 56 57 let mut results = Vec::new(); 58 for rx in replies { 59 results.push(rx.await.unwrap()); 60 } 61 results.sort(); 62 for line in &results { 63 println!("{line}"); 64 } 65 66 // Graceful shutdown: stop accepting work, signal workers, await them. 67 drop(job_tx); 68 shutdown_tx.send(true).unwrap(); 69 for w in workers { 70 w.await.unwrap(); 71 } 72 println!("pool drained and shut down cleanly"); 73 } ``` Real output (one representative run — which worker handles which task varies between runs, but the task ordering is deterministic because we sort by task id): ```plaintext 1 task 0 handled by worker 0 2 task 1 handled by worker 1 3 task 2 handled by worker 2 4 task 3 handled by worker 2 5 task 4 handled by worker 0 6 pool drained and shut down cleanly ``` > **Note:** This pattern — bounded `mpsc` for work, `oneshot` for replies, `watch` for shutdown, `select!` to combine them — is the backbone of countless Rust services. It composes from small, independently testable pieces and never touches a shared lock for the business data. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [Tokio Tutorial — Channels](https://tokio.rs/tokio/tutorial/channels): the official walkthrough this page parallels. * [`tokio::sync` module docs](https://docs.rs/tokio/latest/tokio/sync/index.html): overview of all four channels and when to use each. * [`tokio::sync::mpsc`](https://docs.rs/tokio/latest/tokio/sync/mpsc/index.html) · [`oneshot`](https://docs.rs/tokio/latest/tokio/sync/oneshot/index.html) · [`broadcast`](https://docs.rs/tokio/latest/tokio/sync/broadcast/index.html) · [`watch`](https://docs.rs/tokio/latest/tokio/sync/watch/index.html): per-channel API references. * [`std::sync::mpsc`](https://doc.rust-lang.org/std/sync/mpsc/index.html): the blocking standard-library channel, for plain threads. * [Actors with Tokio](https://ryhl.io/blog/actors-with-tokio/): Alice Ryhl’s canonical write-up of the request/response actor pattern. Related sections of this guide: * [Promises vs Futures](/11-async/00-promises-vs-futures/): why Rust futures are lazy and need a runtime at all. * [Async/Await Syntax](/11-async/01-async-await/): `async`/`await` syntax and `?` inside async, which `recv().await` builds on. * [Setting Up Tokio](/11-async/03-tokio-setup/): adding `tokio` with `features = ["full"]` and `#[tokio::main]`. * [Spawning Tasks](/11-async/09-spawning-tasks/) — `tokio::spawn`, `JoinHandle`, and `spawn_blocking` for the producer/consumer tasks here. * [Concurrent Awaiting](/11-async/07-select-join/) — `tokio::select!` and `join!`, used in the worker pool for shutdown. * [Streams](/11-async/06-streams/) — turning a channel into a `Stream` you can iterate with `while let`. * [Async Synchronization Primitives](/11-async/11-sync-primitives/) — the async `Mutex`/`RwLock` used to share an `mpsc::Receiver`. * [The `Arc<Mutex<T>>` Pattern](/11-async/12-arc-mutex-pattern/) — when shared state beats message passing, and how to do it safely. * [Ownership](/05-ownership/) — move semantics, which explain why senders/receivers behave as they do. * [Basics](/02-basics/) — Rust fundamentals if you need a refresher. * Next section: [Modules & Packages](/12-modules-packages/) — organizing crates and modules. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Sum over an `mpsc` [Section titled “Exercise 1: Sum over an mpsc”](#exercise-1-sum-over-an-mpsc) **Difficulty:** Easy **Objective:** Wire up a basic producer/consumer with a bounded `mpsc` channel. **Instructions:** 1. Create a bounded `mpsc::channel::<i32>(16)`. 2. Spawn a producer task that sends the numbers `1..=5`. 3. In `main`, drain the receiver with `while let Some(n) = rx.recv().await` and accumulate a sum. 4. Make sure the consumer loop actually terminates, then print the total. Solution ```rust 1 use tokio::sync::mpsc; 2 3 #[tokio::main] 4 async fn main() { 5 let (tx, mut rx) = mpsc::channel::<i32>(16); 6 7 let producer = tokio::spawn(async move { 8 for n in 1..=5 { 9 tx.send(n).await.unwrap(); 10 } 11 // tx moved into the task and dropped here -> channel closes, 12 // so rx.recv() will return None and the loop below ends. 13 }); 14 15 let mut sum = 0; 16 while let Some(n) = rx.recv().await { 17 sum += n; 18 } 19 producer.await.unwrap(); 20 println!("sum = {sum}"); 21 } ``` Output: ```plaintext 1 sum = 15 ``` The key insight: the producer task *owns* `tx` after the `async move`, so when the task finishes the sender is dropped and `recv()` returns `None`. ### Exercise 2: One-shot square [Section titled “Exercise 2: One-shot square”](#exercise-2-one-shot-square) **Difficulty:** Medium **Objective:** Use `oneshot` to get a single computed value back from a spawned task, wrapped in a reusable async function. **Instructions:** 1. Write `async fn compute(input: u64) -> u64`. 2. Inside it, create a `oneshot` channel, spawn a task that computes `input * input` and sends it, and `.await` the receiver. 3. Call `compute(9)` from `main` and print the result. Solution ```rust 1 use tokio::sync::oneshot; 2 3 async fn compute(input: u64) -> u64 { 4 let (tx, rx) = oneshot::channel(); 5 tokio::spawn(async move { 6 let _ = tx.send(input * input); 7 }); 8 // The Receiver is itself a Future; await it directly (no .recv()). 9 rx.await.expect("worker replied") 10 } 11 12 #[tokio::main] 13 async fn main() { 14 let result = compute(9).await; 15 println!("9 squared = {result}"); 16 } ``` Output: ```plaintext 1 9 squared = 81 ``` `rx.await` yields `Result<T, RecvError>`; `expect` is fine here because we know the task always sends before dropping its sender. ### Exercise 3: Fan-out with `broadcast` [Section titled “Exercise 3: Fan-out with broadcast”](#exercise-3-fan-out-with-broadcast) **Difficulty:** Medium–Hard **Objective:** Build a pub/sub where two independent subscribers each collect every message, then verify they saw the same sequence. **Instructions:** 1. Create a `broadcast::channel::<i32>(8)`. 2. Subscribe twice (`tx.subscribe()`), and spawn a task per subscriber that loops on `recv().await`, pushing each value into a `Vec` until the channel closes. 3. From `main`, send `1..=3`, then drop the sender. 4. Await both tasks and print each subscriber’s collected `Vec`. Both must be `[1, 2, 3]`. Solution ```rust 1 use tokio::sync::broadcast; 2 3 #[tokio::main] 4 async fn main() { 5 let (tx, _) = broadcast::channel::<i32>(8); 6 let mut a = tx.subscribe(); 7 let mut b = tx.subscribe(); 8 9 let ta = tokio::spawn(async move { 10 let mut seen = Vec::new(); 11 // recv() returns Err(Closed) once the sender is dropped -> loop ends. 12 while let Ok(v) = a.recv().await { 13 seen.push(v); 14 } 15 seen 16 }); 17 let tb = tokio::spawn(async move { 18 let mut seen = Vec::new(); 19 while let Ok(v) = b.recv().await { 20 seen.push(v); 21 } 22 seen 23 }); 24 25 for n in 1..=3 { 26 tx.send(n).unwrap(); 27 } 28 drop(tx); // close the channel so both receivers stop 29 30 println!("a saw {:?}", ta.await.unwrap()); 31 println!("b saw {:?}", tb.await.unwrap()); 32 } ``` Output: ```plaintext 1 a saw [1, 2, 3] 2 b saw [1, 2, 3] ``` Both subscribers must subscribe *before* any message is sent — `broadcast` only delivers messages sent after a receiver subscribes. With capacity 8 and only three messages, no lag occurs. # Spawning Tasks > JavaScript never spawns; Rust's tokio::spawn runs a future as an independent task on a thread pool. Use JoinHandle, abort, and spawn_blocking for real parallelism. In JavaScript you never “spawn” anything — every async operation runs on the one event loop, and “concurrency” is just interleaving on a single thread. Rust’s Tokio gives you `tokio::spawn`, which hands a future to the runtime as an independent **task** that can run *in parallel* on a thread pool. This page is about spawning those tasks, awaiting their results through a `JoinHandle`, how tasks differ from OS threads, and when to reach for `spawn_blocking`. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **task** is Tokio’s unit of concurrency: a future that the runtime owns and drives independently, like a green thread. `tokio::spawn` starts one immediately and returns a `JoinHandle<T>` you can `.await` to get its result. Tasks are far cheaper than OS threads and, on a multi-thread runtime, can run truly in parallel, but CPU-heavy or blocking synchronous work must go to `spawn_blocking` so it does not stall the async workers. > **Note:** This page assumes you already have a runtime wired up. If `#[tokio::main]` and the laziness of futures are new to you, read [Setting Up Tokio](/11-async/03-tokio-setup/) and [Promises vs Futures](/11-async/00-promises-vs-futures/) first. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In Node.js there is no spawning. You start async operations and they run concurrently on the single event loop; you compose their results with `Promise.all` or by awaiting them. “Background work” is just a promise you do not await yet: ```typescript 1 // A "background task" in Node is just an un-awaited promise. 2 async function fetchUser(id: number): Promise<string> { 3 // Stand-in for a DB/network call. 4 await new Promise((resolve) => setTimeout(resolve, 50)); 5 return `user-${id}`; 6 } 7 8 async function main(): Promise<void> { 9 // Kick off five fetches "concurrently". They interleave on ONE thread — 10 // the event loop. There is no parallelism here; CPU work would block them all. 11 const promises = [1, 2, 3, 4, 5].map((id) => fetchUser(id)); 12 13 console.log("all fetches kicked off, event loop continues"); 14 15 // Promise.all gathers the results. 16 const users = await Promise.all(promises); 17 console.log(users); 18 } 19 20 main(); ``` There is one important limitation hiding here: because Node runs your JavaScript on a single thread, a CPU-bound function (say, hashing a megabyte synchronously) **blocks the entire event loop**: every other “concurrent” promise stalls until it returns. Node’s answer is `worker_threads`, a separate, heavier mechanism. Keep that distinction in mind; Rust splits the same problem into `tokio::spawn` (concurrency) and `spawn_blocking` (offloading blocking work). *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) `tokio::spawn` takes a future and hands it to the runtime as a task. It returns a `JoinHandle<T>`, roughly the analogue of the `Promise` you would have gotten back from an async call, except the work is now an independently scheduled task: ```rust 1 use tokio::task::JoinHandle; 2 3 #[tokio::main] 4 async fn main() { 5 // spawn returns a JoinHandle<u64> immediately; the task starts running 6 // concurrently right away (unlike a bare future, which is lazy). 7 let handle: JoinHandle<u64> = tokio::spawn(async { 8 // pretend this is a network call or heavy async work 9 let mut total = 0u64; 10 for i in 1..=100 { 11 total += i; 12 } 13 total 14 }); 15 16 // Do other work here while the task runs... 17 println!("task spawned, main continues"); 18 19 // .await on the handle yields the task's output, wrapped in Result. 20 let sum = handle.await.expect("the task panicked"); 21 println!("sum = {sum}"); 22 } ``` Real output: ```plaintext 1 task spawned, main continues 2 sum = 5050 ``` The shape mirrors `const p = fetchUser(1); const u = await p;` in JavaScript — but with two differences that matter: spawning a task makes it eligible to run on **any** worker thread (real parallelism), and `handle.await` returns a `Result`, because the task could have panicked. We will unpack both below. To fetch many things concurrently, spawn in a loop and collect the handles: ```rust 1 use std::time::Duration; 2 use tokio::time::sleep; 3 4 async fn fetch_user(id: u32) -> String { 5 sleep(Duration::from_millis(50)).await; // stands in for a DB/network call 6 format!("user-{id}") 7 } 8 9 #[tokio::main] 10 async fn main() { 11 let mut handles = Vec::new(); 12 for id in 1..=5 { 13 // Each spawned task runs concurrently. The loop does not block. 14 handles.push(tokio::spawn(fetch_user(id))); 15 } 16 17 // Await each handle to collect the results. 18 let mut users = Vec::new(); 19 for handle in handles { 20 users.push(handle.await.unwrap()); 21 } 22 23 println!("{users:?}"); 24 } ``` Real output: ```plaintext 1 ["user-1", "user-2", "user-3", "user-4", "user-5"] ``` This is the rough equivalent of the `Promise.all` example above — five 50 ms sleeps overlap, so the whole thing finishes in about 50 ms. > **Tip:** For “fetch a fixed set of things and await all of them,” [`join!`/`try_join!`](/11-async/07-select-join/) are often cleaner than spawning, because they run the futures concurrently *without* requiring `Send + 'static`. Reach for `spawn` when you need tasks to outlive the current scope, run on other threads, or be cancellable independently. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What `tokio::spawn` returns and when the task starts [Section titled “What tokio::spawn returns and when the task starts”](#what-tokiospawn-returns-and-when-the-task-starts) `tokio::spawn(future)` does two things synchronously: it registers the future with the current runtime as a task, and it returns a `JoinHandle<T>` where `T` is the future’s output type. Importantly, **the task is now scheduled and will make progress on its own**, even before you await the handle. This is a subtle but important contrast with a bare future. A plain `async { ... }` block does nothing until something polls it (see [Promises vs Futures](/11-async/00-promises-vs-futures/)). Once you `spawn` it, the runtime is the thing polling it, so a spawned task behaves much more like an eager JavaScript promise. You can think of `tokio::spawn` as the operation that converts a lazy future into an actively-running task. ### Awaiting the handle yields a `Result` [Section titled “Awaiting the handle yields a Result”](#awaiting-the-handle-yields-a-result) `handle.await` produces a `Result<T, JoinError>`, not just `T`. The `Err` case exists because a task is isolated: if its future panics, the runtime catches the panic and reports it back through the handle instead of unwinding your whole program. ```rust 1 #[tokio::main] 2 async fn main() { 3 let handle = tokio::spawn(async { 4 panic!("something broke inside the task"); 5 }); 6 7 match handle.await { 8 Ok(()) => println!("task finished cleanly"), 9 Err(join_err) => { 10 // The runtime catches the panic; the rest of the program survives. 11 println!("task failed: is_panic = {}", join_err.is_panic()); 12 } 13 } 14 15 println!("main is still alive"); 16 } ``` Real output: ```plaintext 1 thread 'tokio-rt-worker' panicked at src/main.rs:4:9: 2 something broke inside the task 3 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace 4 task failed: is_panic = true 5 main is still alive ``` Note the panic message is still printed (Rust’s default panic hook runs), but `main` keeps going because the panic was contained in the task. In JavaScript, an unhandled rejection in one promise does not crash unrelated promises either — but the *mechanism* is different: here a thread genuinely panicked and the runtime turned that into a `JoinError`. ### The `'static` and `Send` bounds [Section titled “The 'static and Send bounds”](#the-static-and-send-bounds) The signature of `tokio::spawn` is, simplified: ```rust 1 pub fn spawn<F>(future: F) -> JoinHandle<F::Output> 2 where 3 F: Future + Send + 'static, 4 F::Output: Send + 'static, ``` Two bounds drive almost every error you will hit: * **`'static`**: a spawned task may outlive the function that created it, so it cannot borrow local variables. You must move owned data in (with `async move`) or share it via `Arc`. * **`Send`**: on a multi-thread runtime, a task can be moved between worker threads, so its future (and every value held across an `.await`) must be safe to send across threads. These are the compile-time price of real parallelism. JavaScript needs neither because everything lives on one thread and the closure captures by reference into the same heap. Both bounds are shown as real compiler errors under [Common Pitfalls](#common-pitfalls). ### Detaching: dropping the handle does *not* cancel the task [Section titled “Detaching: dropping the handle does not cancel the task”](#detaching-dropping-the-handle-does-not-cancel-the-task) Unlike some task systems, dropping a `JoinHandle` does **not** stop the task; it simply detaches it, and the task runs to completion in the background. You just lose the ability to await its result. ```rust 1 use tokio::sync::oneshot; 2 3 #[tokio::main] 4 async fn main() { 5 let (tx, rx) = oneshot::channel(); 6 7 // We spawn and immediately drop the JoinHandle (the `_` discards it). 8 let _ = tokio::spawn(async move { 9 // This still runs to completion despite no handle being held. 10 let _ = tx.send("background work finished"); 11 }); 12 13 // Prove the task ran by receiving its message. 14 let msg = rx.await.expect("sender dropped"); 15 println!("{msg}"); 16 } ``` Real output: ```plaintext 1 background work finished ``` > **Warning:** Detached tasks are the Rust equivalent of “fire and forget” promises. They keep running, but they are *not* awaited at shutdown. If `main` (or the runtime) ends first, in-flight detached tasks are dropped mid-flight. Keep handles (or use a [`JoinSet`](#use-a-joinset-for-dynamic-groups-of-tasks)) when you need to wait for completion. ### Cancelling with `abort` [Section titled “Cancelling with abort”](#cancelling-with-abort) To actually stop a task, call `abort()` on its handle. The task is cancelled at its next `.await` point, and awaiting the handle then returns a `JoinError` for which `is_cancelled()` is true: ```rust 1 use std::time::Duration; 2 use tokio::time::sleep; 3 4 #[tokio::main] 5 async fn main() { 6 let handle = tokio::spawn(async { 7 sleep(Duration::from_secs(60)).await; // long-running 8 "done" 9 }); 10 11 // Decide we no longer need the result and cancel the task. 12 handle.abort(); 13 14 match handle.await { 15 Ok(value) => println!("completed: {value}"), 16 Err(e) if e.is_cancelled() => println!("task was cancelled"), 17 Err(e) => println!("task failed: {e}"), 18 } 19 } ``` Real output: ```plaintext 1 task was cancelled ``` JavaScript has no built-in promise cancellation (you reach for `AbortController`); Tokio bakes cancellation into the handle. Cancellation semantics in depth — what “cancel at an await point” really means — live in [Concurrency vs Parallelism](/11-async/10-concurrency/). ### `spawn_blocking`: the escape hatch for synchronous work [Section titled “spawn\_blocking: the escape hatch for synchronous work”](#spawn_blocking-the-escape-hatch-for-synchronous-work) Async tasks are **cooperative**: a task only yields control at an `.await`. If a task runs a long synchronous computation or calls a blocking API (a CPU-bound loop, `std::thread::sleep`, a synchronous file or database call), it never yields, and it starves every other task sharing that worker thread. This is the same failure mode as blocking Node’s event loop, but Tokio gives you a first-class fix. `tokio::task::spawn_blocking` moves a synchronous closure onto a **separate, dedicated thread pool** reserved for blocking work, so the async workers stay free: ```rust 1 use tokio::task; 2 3 // A CPU-bound, synchronous function. It blocks the thread it runs on. 4 fn fibonacci(n: u64) -> u64 { 5 if n < 2 { n } else { fibonacci(n - 1) + fibonacci(n - 2) } 6 } 7 8 #[tokio::main] 9 async fn main() { 10 // spawn_blocking moves this work to a dedicated blocking-thread pool, 11 // so it does NOT stall the async worker threads. 12 let handle = task::spawn_blocking(|| { 13 // Heavy synchronous computation lives here. 14 fibonacci(35) 15 }); 16 17 // Meanwhile, async work on the runtime keeps making progress. 18 println!("computing fib(35) on a blocking thread..."); 19 20 let result = handle.await.unwrap(); 21 println!("fib(35) = {result}"); 22 } ``` Real output: ```plaintext 1 computing fib(35) on a blocking thread... 2 fib(35) = 9227465 ``` `spawn_blocking` returns a `JoinHandle<T>` just like `spawn`, so you `.await` it the same way. The closure is `FnOnce` and runs once on a blocking thread. This is the analogue of offloading work to a Node `worker_thread`, but with far less ceremony. > **Note:** `spawn_blocking` is for *blocking* work (CPU-bound loops, synchronous I/O), not for parallelizing async work. For genuine CPU-bound parallelism across cores, a thread pool like [`rayon`](https://docs.rs/rayon) is often the better tool. See [Async vs Sync](/11-async/13-async-vs-sync/). *** ## Tasks vs OS Threads [Section titled “Tasks vs OS Threads”](#tasks-vs-os-threads) It is worth being precise, because “task” and “thread” are casually conflated. Rust gives you both: `std::thread::spawn` for OS threads and `tokio::spawn` for async tasks. An OS thread: ```rust 1 use std::thread; 2 3 fn main() { 4 // An OS thread: ~megabytes of stack, scheduled by the kernel. 5 let handle = thread::spawn(|| { 6 let mut sum = 0u64; 7 for i in 1..=100 { sum += i; } 8 sum 9 }); 10 11 // join() blocks the current thread until the spawned one finishes. 12 let result = handle.join().expect("thread panicked"); 13 println!("sum = {result}"); 14 } ``` Real output: ```plaintext 1 sum = 5050 ``` The APIs look almost identical (`spawn` → handle → `join`/`await`), but the machinery underneath is very different: | Aspect | OS thread (`std::thread::spawn`) | Async task (`tokio::spawn`) | | ----------------- | ---------------------------------- | ---------------------------------------------------- | | Created by | The operating system kernel | The Tokio runtime (in user space) | | Stack | Large, fixed (often \~2–8 MB) | Tiny; grows from the heap as the state machine needs | | Cost to create | Relatively expensive (syscall) | Very cheap (an allocation + queue push) | | How many feasible | Thousands | Hundreds of thousands to millions | | Scheduling | Pre-emptive, by the kernel | Cooperative, at `.await` points, by Tokio | | Blocking is fine? | Yes — that is what threads are for | No — blocks the worker; use `spawn_blocking` | | Get the result | `handle.join()` (blocks) | `handle.await` (yields) | | Best for | CPU-bound work, blocking calls | I/O-bound concurrency at scale | The mental model: a task is a lightweight, cooperatively-scheduled job that the runtime multiplexes onto a small pool of OS threads. You can have a million tasks running on, say, eight threads. You cannot have a million OS threads; you would exhaust memory on stacks alone. This is exactly why network servers (which juggle huge numbers of mostly-idle connections) are built on tasks, not threads. > **Tip:** Choosing between async tasks, OS threads, and `spawn_blocking` is the central decision of [Async vs Sync](/11-async/13-async-vs-sync/). The short version: I/O-bound and high-concurrency → tasks; CPU-bound → threads / `rayon` / `spawn_blocking`. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | JavaScript / Node.js | Rust + Tokio | | ---------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | | Unit of concurrency | A promise on the single event loop | A task on a (possibly multi-thread) runtime | | Parallelism | None for JS code (one thread); `worker_threads` for parallel | Real parallelism across worker threads by default | | Starting work | Calling an async fn (eager) | `tokio::spawn` (a bare future is lazy until spawned/awaited) | | Handle to the result | The returned `Promise` | `JoinHandle<T>` | | Result type | `T` (or a rejection) | `Result<T, JoinError>` | | A panic / throw in one job | Unhandled rejection; isolated | Caught by runtime → `JoinError`; rest of program survives | | Cancellation | Manual via `AbortController` | `handle.abort()` (cancels at next `.await`) | | Offloading blocking/CPU work | `worker_threads` | `tokio::task::spawn_blocking` (or threads / `rayon`) | | Capturing outside data | Closure captures by reference, same heap | Must be `Send + 'static`: `async move`, `Arc`, owned data | The two rows that trip up TypeScript developers most are **“Result type”** and **“capturing outside data.”** A `JoinHandle` is not a transparent `Promise<T>`; you must handle the `JoinError`. And you cannot casually close over a local `let` the way a JS arrow function does — the `'static`/`Send` bounds force you to move or share ownership. > **Note:** “Concurrency” and “parallelism” are not the same thing, and Tokio gives you both depending on the scheduler. The distinction (and why a single-thread runtime is still concurrent) is covered in [Concurrency vs Parallelism](/11-async/10-concurrency/). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Borrowing a local into a spawned task (missing `move`) [Section titled “Pitfall 1: Borrowing a local into a spawned task (missing move)”](#pitfall-1-borrowing-a-local-into-a-spawned-task-missing-move) A spawned task is `'static`, so it cannot borrow `main`’s local variables; the task might outlive the stack frame they live in: ```rust 1 #[tokio::main] 2 async fn main() { 3 let name = String::from("Ada"); 4 5 let handle = tokio::spawn(async { 6 // does not compile (error[E0373]): borrows `name`, but the task 7 // may outlive main's stack frame. 8 println!("hello, {name}"); 9 }); 10 11 handle.await.unwrap(); 12 } ``` Real compiler output: ```plaintext 1 error[E0373]: async block may outlive the current function, but it borrows `name`, which is owned by the current function 2 --> src/main.rs:5:31 3 | 4 5 | let handle = tokio::spawn(async { 5 | ^^^^^ may outlive borrowed value `name` 6 6 | // does not compile (error[E0373]): borrows `name`, but the task 7 7 | println!("hello, {name}"); 8 | ---- `name` is borrowed here 9 | 10 = note: async blocks are not executed immediately and must either take a reference or ownership of outside variables they use 11 help: to force the async block to take ownership of `name` (and any other referenced variables), use the `move` keyword 12 | 13 5 | let handle = tokio::spawn(async move { 14 | ++++ ``` **Fix:** the compiler tells you exactly what to do. Add `move` so the task takes ownership: `tokio::spawn(async move { println!("hello, {name}"); })`. To share data across several tasks instead of moving it into one, wrap it in `Arc` and clone the `Arc` per task (see [The `Arc<Mutex<T>>` Pattern](/11-async/12-arc-mutex-pattern/)). ### Pitfall 2: Holding a non-`Send` value across an `.await` in a spawned task [Section titled “Pitfall 2: Holding a non-Send value across an .await in a spawned task”](#pitfall-2-holding-a-non-send-value-across-an-await-in-a-spawned-task) A spawned future must be `Send`. If you hold a non-`Send` type — `Rc`, `RefCell`, a `MutexGuard` from `std::sync` — across an `.await`, the future becomes non-`Send` and `spawn` rejects it: ```rust 1 use std::rc::Rc; 2 use std::time::Duration; 3 use tokio::time::sleep; 4 5 #[tokio::main] 6 async fn main() { 7 let handle = tokio::spawn(async { 8 // does not compile: Rc is not Send; held across .await. 9 let data = Rc::new(vec![1, 2, 3]); 10 sleep(Duration::from_millis(10)).await; 11 println!("{:?}", data); 12 }); 13 14 handle.await.unwrap(); 15 } ``` Real compiler output (trimmed): ```plaintext 1 error: future cannot be sent between threads safely 2 --> src/main.rs:7:18 3 | 4 7 | let handle = tokio::spawn(async { 5 | __________________^ 6 | |______^ future created by async block is not `Send` 7 | 8 = help: within `{async block@src/main.rs:7:31: 7:36}`, the trait `Send` is not implemented for `Rc<Vec<i32>>` 9 note: future is not `Send` as this value is used across an await 10 --> src/main.rs:10:42 11 | 12 9 | let data = Rc::new(vec![1, 2, 3]); 13 | ---- has type `Rc<Vec<i32>>` which is not `Send` 14 10 | sleep(Duration::from_millis(10)).await; 15 | ^^^^^ await occurs here, with `data` maybe used later 16 note: required by a bound in `tokio::spawn` ``` **Fix:** use a `Send` equivalent: `Arc` instead of `Rc`, the async-aware `tokio::sync::Mutex` instead of `std::sync::Mutex` if a guard must cross an `.await` (see [Async Synchronization Primitives](/11-async/11-sync-primitives/)). Or restructure so the non-`Send` value is dropped *before* the `.await`. (TypeScript has no analogue to this error class; single-threaded JS never asks whether a value is thread-safe.) ### Pitfall 3: Blocking the runtime with synchronous work [Section titled “Pitfall 3: Blocking the runtime with synchronous work”](#pitfall-3-blocking-the-runtime-with-synchronous-work) This one compiles and runs, so the compiler will not save you. A spawned task that runs a long synchronous loop or calls `std::thread::sleep` does not yield; it pins a worker thread and starves other tasks: ```rust 1 // Conceptual anti-pattern (compiles, but misbehaves): 2 // std::thread::sleep blocks the WHOLE worker thread, not just this task. 3 tokio::spawn(async { 4 std::thread::sleep(std::time::Duration::from_secs(5)); // blocks the worker! 5 // ... other tasks on this thread cannot run for 5 seconds. 6 }); ``` **Fix:** for async waiting, use `tokio::time::sleep(...).await` (yields the worker). For genuinely blocking or CPU-bound code, use `tokio::task::spawn_blocking`. This is the same lesson as “never block the Node event loop,” but Tokio gives you `spawn_blocking` as a clean offload. (Tokio can detect *some* long blocking stalls and log a warning, but it cannot fix them for you.) ### Pitfall 4: Spawning a future and forgetting it does nothing without a runtime, or expecting `T` instead of `Result<T, _>` [Section titled “Pitfall 4: Spawning a future and forgetting it does nothing without a runtime, or expecting T instead of Result\<T, \_>”](#pitfall-4-spawning-a-future-and-forgetting-it-does-nothing-without-a-runtime-or-expecting-t-instead-of-resultt-_) Two smaller traps: * Calling `tokio::spawn` outside any runtime **panics at runtime** (`there is no reactor running...`), covered in [Setting Up Tokio](/11-async/03-tokio-setup/#common-pitfalls). * `handle.await` gives a `Result`, so `let x: u64 = handle.await;` fails to compile (you get `Result<u64, JoinError>`). Use `handle.await?` (if your function returns a compatible error) or `handle.await.unwrap()` / `.expect(...)` while prototyping. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Reach for `join!` before `spawn` when awaiting a fixed set [Section titled “Reach for join! before spawn when awaiting a fixed set”](#reach-for-join-before-spawn-when-awaiting-a-fixed-set) If you simply want to run a known set of futures concurrently and wait for all of them, [`tokio::join!`](/11-async/07-select-join/) is lighter than spawning: it runs them on the *current* task with no `Send + 'static` requirement and no extra task allocation. Use `spawn` when a task must outlive the current scope, run on another thread, or be cancelled independently. ### Use a `JoinSet` for dynamic groups of tasks [Section titled “Use a JoinSet for dynamic groups of tasks”](#use-a-joinset-for-dynamic-groups-of-tasks) When you spawn a variable number of tasks and want to collect results as they finish, `tokio::task::JoinSet` is cleaner than a `Vec<JoinHandle<_>>`. It owns the handles, hands you results in completion order, and can abort the whole group at once: ```rust 1 use tokio::task::JoinSet; 2 3 async fn work(id: u32) -> u32 { 4 id * id 5 } 6 7 #[tokio::main] 8 async fn main() { 9 let mut set = JoinSet::new(); 10 for id in 1..=5 { 11 set.spawn(work(id)); 12 } 13 14 let mut total = 0; 15 // join_next yields results as tasks finish, in completion order. 16 while let Some(res) = set.join_next().await { 17 total += res.expect("task panicked"); 18 } 19 println!("total = {total}"); 20 } ``` Real output: ```plaintext 1 total = 55 ``` Dropping a `JoinSet` aborts all its tasks, which makes it a good fit for structured, scoped concurrency. ### Always decide what a `JoinError` means [Section titled “Always decide what a JoinError means”](#always-decide-what-a-joinerror-means) Do not reflexively `.unwrap()` every handle in production. Decide deliberately: propagate with `?`, retry, log and continue, or treat a panicked worker as fatal. The `Result<T, JoinError>` is there so you make that choice explicitly. ### Share state with `Arc`, not by capturing references [Section titled “Share state with Arc, not by capturing references”](#share-state-with-arc-not-by-capturing-references) Because tasks are `'static`, share read-only data with `Arc<T>` (clone the `Arc` into each task) and shared mutable state with `Arc<Mutex<T>>` / `Arc<RwLock<T>>`. See [The `Arc<Mutex<T>>` Pattern](/11-async/12-arc-mutex-pattern/) for the full pattern and [Async Synchronization Primitives](/11-async/11-sync-primitives/) for choosing std vs Tokio locks. ### Keep `spawn_blocking` closures genuinely blocking-only [Section titled “Keep spawn\_blocking closures genuinely blocking-only”](#keep-spawn_blocking-closures-genuinely-blocking-only) Put only synchronous, blocking code inside `spawn_blocking`. Do not call `.await` inside it (it is not an async context) and do not use it to “parallelize” async work; that is what `spawn` and `join!` are for. Bound the blocking pool with `max_blocking_threads` if you offload a lot. ### Name long-lived tasks for observability [Section titled “Name long-lived tasks for observability”](#name-long-lived-tasks-for-observability) The unstable `tokio::task::Builder` can name tasks (under `tokio_unstable`), and the [`tracing`](https://docs.rs/tracing) crate is the idiomatic way to instrument tasks in production. Even without that, prefer holding handles (or a `JoinSet`) for important background work so failures surface instead of vanishing into a detached task. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored pattern: a small concurrent crawler. We spawn one task per URL, cap how many run at once with a `Semaphore` (like a connection-pool limit), fetch the body asynchronously, and offload the CPU-bound checksum to `spawn_blocking`. Each task returns its result through a `JoinHandle`. ```rust 1 use std::sync::Arc; 2 use std::time::Duration; 3 use tokio::sync::Semaphore; 4 use tokio::task::JoinHandle; 5 use tokio::time::sleep; 6 7 /// Simulates fetching a URL (I/O-bound, async). 8 async fn fetch(url: &str) -> String { 9 sleep(Duration::from_millis(20)).await; 10 format!("<html>{url}</html>") 11 } 12 13 /// Simulates parsing/hashing the body (CPU-bound, synchronous). 14 fn checksum(body: &str) -> u64 { 15 body.bytes().fold(0u64, |acc, b| acc.wrapping_mul(31).wrapping_add(b as u64)) 16 } 17 18 #[tokio::main] 19 async fn main() { 20 let urls = vec![ 21 "https://a.example", "https://b.example", 22 "https://c.example", "https://d.example", 23 ]; 24 25 // Limit how many fetches run at once (like a connection-pool cap). 26 let limit = Arc::new(Semaphore::new(2)); 27 28 let mut handles: Vec<JoinHandle<(String, u64)>> = Vec::new(); 29 for url in urls { 30 let limit = Arc::clone(&limit); 31 let url = url.to_string(); 32 handles.push(tokio::spawn(async move { 33 // Hold a permit for the duration of the fetch. 34 let _permit = limit.acquire().await.expect("semaphore closed"); 35 let body = fetch(&url).await; 36 37 // Offload the CPU-bound hashing to the blocking pool. 38 let hash = tokio::task::spawn_blocking(move || checksum(&body)) 39 .await 40 .expect("blocking task panicked"); 41 42 (url, hash) 43 })); 44 } 45 46 let mut results = Vec::new(); 47 for handle in handles { 48 results.push(handle.await.expect("worker panicked")); 49 } 50 results.sort(); 51 52 for (url, hash) in results { 53 println!("{url} -> {hash}"); 54 } 55 } ``` Real output: ```plaintext 1 https://a.example -> 5843935939460435433 2 https://b.example -> 6847466025596709832 3 https://c.example -> 7850996111732984231 4 https://d.example -> 8854526197869258630 ``` This one example exercises every idea on the page: independent tasks via `spawn`, shared state via `Arc`, bounded concurrency via a `Semaphore`, CPU offload via `spawn_blocking`, and result collection via `JoinHandle`. The `Semaphore` is covered in [Async Synchronization Primitives](/11-async/11-sync-primitives/). > **Note:** In a real crawler you would use [`reqwest`](https://docs.rs/reqwest) for HTTP and propagate errors with `Result` and `?` rather than `expect`. Error handling inside async is covered in [Async/Await Syntax](/11-async/01-async-await/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [Tokio Tutorial — Spawning](https://tokio.rs/tokio/tutorial/spawning): the official walkthrough of `tokio::spawn`. * [`tokio::spawn` docs](https://docs.rs/tokio/latest/tokio/task/fn.spawn.html) — the function, its bounds, and detach behavior. * [`tokio::task::spawn_blocking` docs](https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html) — when and how to offload blocking work. * [`JoinHandle` docs](https://docs.rs/tokio/latest/tokio/task/struct.JoinHandle.html) and [`JoinSet` docs](https://docs.rs/tokio/latest/tokio/task/struct.JoinSet.html). * [Tokio Tutorial — Bridging with sync code](https://tokio.rs/tokio/topics/bridging): runtimes, blocking, and `spawn_blocking` in context. * [`std::thread` docs](https://doc.rust-lang.org/std/thread/): OS threads, for the comparison above. Related sections of this guide: * [Promises vs Futures](/11-async/00-promises-vs-futures/) — why a bare future is lazy and `spawn` makes it run. * [Setting Up Tokio](/11-async/03-tokio-setup/) — wiring up the runtime that `spawn` needs. * [Async/Await Syntax](/11-async/01-async-await/): `async`/`await` syntax and `?` inside async. * [Concurrent Awaiting](/11-async/07-select-join/) — `join!`/`try_join!`/`select!`, the lighter alternative to spawning. * [Async Channels](/11-async/08-channels/): passing results out of tasks with mpsc/oneshot channels. * [Concurrency vs Parallelism](/11-async/10-concurrency/): concurrency vs parallelism, structured patterns, cancellation. * [Async Synchronization Primitives](/11-async/11-sync-primitives/) and [The `Arc<Mutex<T>>` Pattern](/11-async/12-arc-mutex-pattern/) — sharing state across tasks. * [Async vs Sync](/11-async/13-async-vs-sync/) — tasks vs threads vs `spawn_blocking`, CPU-bound vs I/O-bound. * [Understanding Cargo](/01-getting-started/03-cargo-basics/): `cargo add` and `Cargo.toml`. * [Basics](/02-basics/) — Rust fundamentals refresher. * Next section: [Modules & Packages](/12-modules-packages/): organizing crates and modules. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Spawn and sum [Section titled “Exercise 1: Spawn and sum”](#exercise-1-spawn-and-sum) **Difficulty:** Easy **Objective:** Spawn a batch of tasks, collect their results through `JoinHandle`s, and combine them. **Instructions:** 1. In an `async` `main`, spawn one task per `n` in `1..=10`; each task should compute `n * n`. 2. Push each `JoinHandle` into a `Vec`. 3. Await every handle, summing the results, and print the total. 4. Remember you will need `async move` to capture `n` by value. Solution ```rust 1 #[tokio::main] 2 async fn main() { 3 let mut handles = Vec::new(); 4 for n in 1..=10u64 { 5 handles.push(tokio::spawn(async move { n * n })); 6 } 7 8 let mut total = 0u64; 9 for handle in handles { 10 total += handle.await.expect("task panicked"); 11 } 12 13 println!("sum of squares 1..=10 = {total}"); 14 } ``` Output: ```plaintext 1 sum of squares 1..=10 = 385 ``` `async move` is required because the task is `'static` and must own `n` (Pitfall 1). `handle.await` returns `Result<u64, JoinError>`, so we `.expect(...)` to get the `u64`. ### Exercise 2: Offload CPU work with `spawn_blocking` [Section titled “Exercise 2: Offload CPU work with spawn\_blocking”](#exercise-2-offload-cpu-work-with-spawn_blocking) **Difficulty:** Medium **Objective:** Move a synchronous, CPU-bound computation off the async workers and await its result. **Instructions:** 1. Write a **synchronous** `fn count_primes(n: u64) -> u64` that counts primes below `n` (a deliberately naive loop is fine). 2. In `async` `main`, run `count_primes(10_000)` via `tokio::task::spawn_blocking`. 3. Print a message *before* awaiting (to show the runtime is free), then await the handle and print the count. Solution ```rust 1 use tokio::task; 2 3 /// Synchronous, CPU-bound: count primes up to n (a stand-in for heavy work). 4 fn count_primes(n: u64) -> u64 { 5 (2..n).filter(|&x| (2..x).all(|d| x % d != 0)).count() as u64 6 } 7 8 #[tokio::main] 9 async fn main() { 10 let handle = task::spawn_blocking(|| count_primes(10_000)); 11 12 println!("counting primes on the blocking pool..."); 13 let primes = handle.await.expect("blocking task panicked"); 14 println!("primes below 10000 = {primes}"); 15 } ``` Output: ```plaintext 1 counting primes on the blocking pool... 2 primes below 10000 = 1229 ``` Running this loop inside a plain `tokio::spawn` would pin an async worker for the whole computation. `spawn_blocking` puts it on the dedicated blocking pool so the async workers stay responsive. ### Exercise 3: Bounded batch with a deadline [Section titled “Exercise 3: Bounded batch with a deadline”](#exercise-3-bounded-batch-with-a-deadline) **Difficulty:** Medium–Hard **Objective:** Spawn a group of tasks into a `JoinSet`, collect whatever finishes within a time budget, and cancel the rest. **Instructions:** 1. Write `async fn process(id: u32) -> String` that sleeps 200 ms for even `id`s and 20 ms for odd ones, then returns `format!("job-{id}")`. 2. Spawn `process(1..=4)` into a `tokio::task::JoinSet`. 3. Use `tokio::select!` with a 100 ms `sleep` deadline: drain `join_next()` until either all tasks finish or the deadline fires. 4. On deadline, call `abort_all()` and drain the set. Print the jobs that completed within budget (sorted). Solution ```rust 1 use std::time::Duration; 2 use tokio::task::JoinSet; 3 use tokio::time::sleep; 4 5 async fn process(id: u32) -> String { 6 // Tasks 2 and 4 are "slow"; the rest are quick. 7 let delay = if id % 2 == 0 { 200 } else { 20 }; 8 sleep(Duration::from_millis(delay)).await; 9 format!("job-{id}") 10 } 11 12 #[tokio::main] 13 async fn main() { 14 let mut set = JoinSet::new(); 15 for id in 1..=4 { 16 set.spawn(process(id)); 17 } 18 19 // Give the whole batch a 100 ms budget; cancel whatever is left. 20 let mut done = Vec::new(); 21 let deadline = sleep(Duration::from_millis(100)); 22 tokio::pin!(deadline); 23 24 loop { 25 tokio::select! { 26 maybe = set.join_next() => { 27 match maybe { 28 Some(res) => done.push(res.expect("task panicked")), 29 None => break, // all tasks finished 30 } 31 } 32 _ = &mut deadline => { 33 set.abort_all(); // cancel the unfinished slow tasks 34 while set.join_next().await.is_some() {} // drain 35 break; 36 } 37 } 38 } 39 40 done.sort(); 41 println!("completed within budget: {done:?}"); 42 } ``` Output: ```plaintext 1 completed within budget: ["job-1", "job-3"] ``` The two fast (odd) jobs finish well under 100 ms; the slow (even) ones are cancelled by `abort_all()` when the deadline fires. `tokio::pin!` is needed because we poll the same `deadline` future across multiple `select!` iterations. `select!` is covered in [Concurrent Awaiting](/11-async/07-select-join/). # Concurrency vs Parallelism > Where Node interleaves tasks on one thread, Rust splits concurrency from parallelism: cheap M:N Tokio tasks, real parallel threads, and futures you can cancel. Coming from Node.js, you have lived your whole career inside a single-threaded event loop: lots of things happen “at once,” but only one line of your JavaScript ever executes at a time. Rust forces you to be precise about a distinction Node mostly hides — the difference between **concurrency** (juggling many tasks) and **parallelism** (actually running them simultaneously on multiple cores) — and gives you safe tools for both. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) **Concurrency** is dealing with many things at once (structure); **parallelism** is doing many things at once (execution). Node.js gives you concurrency on one thread via the event loop; Rust gives you concurrency *and* opt-in, compiler-checked parallelism. This page covers how Rust’s async **tasks** relate to OS **threads**, how to structure groups of tasks so they don’t leak, and how to **cancel** work cleanly, something that is genuinely hard in JavaScript. > **Note:** This page is about the *concepts and patterns* of concurrency. The mechanics live in sibling pages: [spawning tasks](/11-async/09-spawning-tasks/), [`select!`/`join!`](/11-async/07-select-join/), [channels](/11-async/08-channels/), and [sync primitives](/11-async/11-sync-primitives/). The deeper “async vs threads vs blocking” decision is its own page: [Async vs Sync](/11-async/13-async-vs-sync/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In Node.js, you achieve concurrency by kicking off multiple promises and awaiting them together. This *looks* parallel, but the JavaScript callbacks never run simultaneously: the event loop interleaves them on one thread. The waiting (I/O, timers) happens off-thread; your code does not. ```typescript 1 // TypeScript / JavaScript (Node v22) 2 // Concurrency on one thread: three "downloads" overlap because the WAITING 3 // is offloaded to libuv, but our JS code runs one statement at a time. 4 5 function fetchUser(id: number): Promise<string> { 6 return new Promise((resolve) => { 7 setTimeout(() => resolve(`user-${id}`), 100); // simulated network latency 8 }); 9 } 10 11 async function main() { 12 const start = Date.now(); 13 14 // Promise.all runs all three concurrently — total ~100ms, not ~300ms. 15 const users = await Promise.all([fetchUser(1), fetchUser(2), fetchUser(3)]); 16 17 console.log(`fetched ${JSON.stringify(users)} in ~${Date.now() - start} ms`); 18 } 19 20 main(); 21 // fetched ["user-1","user-2","user-3"] in ~10X ms ``` For **CPU-bound** work, Node cannot help you with `Promise.all`: a heavy `for` loop blocks the event loop and everything else stalls. To get real parallelism you must reach for **Worker Threads** (or child processes) and pass messages across a serialization boundary: ```typescript 1 // CPU-bound parallelism in Node requires Worker Threads — a separate V8 isolate. 2 import { Worker } from "node:worker_threads"; 3 4 function countPrimes(maxN: number): Promise<number> { 5 return new Promise((resolve, reject) => { 6 const worker = new Worker("./prime-worker.js", { workerData: maxN }); 7 worker.on("message", resolve); 8 worker.on("error", reject); 9 }); 10 } 11 12 // Each worker is a heavyweight thread with its OWN heap; data is copied, not shared. ``` *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust draws the same picture, but the pieces are explicit. A **task** (`tokio::spawn`) is the lightweight, async analogue of “kick off a promise.” On Tokio’s default multi-thread runtime, those tasks are scheduled across a pool of worker threads, so I/O-bound tasks run **concurrently** and CPU work spread across them can run **in parallel**: no Worker-Thread ceremony, no copying. ```rust 1 // Rust + Tokio 1.52 — concurrency via tasks. 2 use std::time::Instant; 3 use tokio::time::{sleep, Duration}; 4 5 // Simulated I/O-bound work: fetch a user record from a remote service. 6 async fn fetch_user(id: u32) -> String { 7 sleep(Duration::from_millis(100)).await; // pretend this is a network round-trip 8 format!("user-{id}") 9 } 10 11 #[tokio::main] 12 async fn main() { 13 let start = Instant::now(); 14 15 // Spawn three tasks. Each runs CONCURRENTLY on the runtime. 16 // On the multi-thread scheduler they may also run in PARALLEL. 17 let handles: Vec<_> = (1..=3) 18 .map(|id| tokio::spawn(fetch_user(id))) 19 .collect(); 20 21 // Await all of them (like Promise.all). 22 let mut users = Vec::new(); 23 for handle in handles { 24 users.push(handle.await.unwrap()); 25 } 26 27 println!("fetched {:?} in ~{} ms", users, start.elapsed().as_millis()); 28 } ``` Real output (Rust 1.96, Tokio 1.52): ```plaintext 1 fetched ["user-1", "user-2", "user-3"] in ~102 ms ``` For **CPU-bound** parallelism Rust does not need a separate isolate or message passing. You can use plain OS threads with shared, borrow-checked memory: ```rust 1 use std::thread; 2 3 // CPU-bound work split across OS threads — true parallelism, no async needed. 4 fn sum_range(lo: u64, hi: u64) -> u64 { 5 (lo..hi).fold(0u64, |a, x| a.wrapping_add(x.wrapping_mul(x))) 6 } 7 8 fn main() { 9 // thread::scope lets borrowed data cross into threads safely (stable since 1.63). 10 let total = thread::scope(|s| { 11 let h1 = s.spawn(|| sum_range(0, 50_000_000)); 12 let h2 = s.spawn(|| sum_range(50_000_000, 100_000_000)); 13 h1.join().unwrap().wrapping_add(h2.join().unwrap()) 14 }); 15 println!("sum = {total}"); 16 } ``` > **Note:** Mixing the two is also fine and idiomatic: run CPU-bound work on threads via [`spawn_blocking`](/11-async/09-spawning-tasks/) *from inside* async code, so it does not stall the event loop. More on that choice in [Async vs Sync](/11-async/13-async-vs-sync/). *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Concurrency is structure; parallelism is execution [Section titled “Concurrency is structure; parallelism is execution”](#concurrency-is-structure-parallelism-is-execution) The canonical phrasing (from Rob Pike) is: *“Concurrency is about dealing with lots of things at once. Parallelism is about doing lots of things at once.”* Concurrency is how you **structure** a program as independently-progressing tasks; parallelism is a **runtime property**: whether those tasks happen to execute at the same instant on different cores. * A Node.js server is **concurrent** (thousands of in-flight requests) but **not parallel** (one thread runs your JS). * A Rust `tokio` server on the multi-thread runtime is **both**: thousands of concurrent tasks, executing across N worker threads in parallel. * A single-threaded `tokio` runtime (`flavor = "current_thread"`) is concurrent but **not** parallel, the closest match to Node’s model. You write the *same* `async` code either way; the runtime flavor decides whether parallelism is on the table. That separation is the whole point: you express concurrency once, and choose the execution strategy separately. ### Tasks are not threads [Section titled “Tasks are not threads”](#tasks-are-not-threads) A `tokio::spawn`ed **task** is *not* an OS thread. It is a future that the runtime schedules cooperatively onto a small pool of worker threads (by default, one per CPU core). This is “M:N” scheduling: M tasks multiplexed onto N threads. The practical consequence is that tasks are *cheap*. Spawning a hundred thousand of them is routine; spawning a hundred thousand OS threads would exhaust memory because each thread reserves megabytes of stack. ```rust 1 use std::sync::atomic::{AtomicU64, Ordering}; 2 use std::sync::Arc; 3 4 // Tasks are cheap: spawning 100,000 of them is fine. 100,000 OS THREADS 5 // would exhaust memory (each thread reserves ~MBs of stack). 6 #[tokio::main] 7 async fn main() { 8 let counter = Arc::new(AtomicU64::new(0)); 9 let mut handles = Vec::with_capacity(100_000); 10 11 for _ in 0..100_000 { 12 let counter = Arc::clone(&counter); 13 handles.push(tokio::spawn(async move { 14 counter.fetch_add(1, Ordering::Relaxed); 15 })); 16 } 17 for h in handles { 18 h.await.unwrap(); 19 } 20 21 println!("100,000 tasks all ran: counter = {}", counter.load(Ordering::Relaxed)); 22 } ``` Real output: ```plaintext 1 100,000 tasks all ran: counter = 100000 ``` > **Tip:** Use a **task** for I/O-bound concurrency (waiting on sockets, timers, databases). Use a **thread** (or [`spawn_blocking`](/11-async/09-spawning-tasks/)) for CPU-bound or blocking work. The litmus test: does it spend its time *waiting*, or *computing*? Waiting → task; computing → thread. See [Async vs Sync](/11-async/13-async-vs-sync/). ### The runtime flavor decides parallelism [Section titled “The runtime flavor decides parallelism”](#the-runtime-flavor-decides-parallelism) Tasks only run in parallel if the runtime has more than one worker thread. Compare the two flavors by counting the distinct OS threads that actually execute the tasks. On the **multi-thread** runtime (the default for `#[tokio::main]`), tasks spread across worker threads: ```rust 1 use std::collections::HashSet; 2 use std::sync::{Arc, Mutex}; 3 4 #[tokio::main] // multi-thread: one worker per CPU core by default 5 async fn main() { 6 let threads = Arc::new(Mutex::new(HashSet::new())); 7 let mut handles = Vec::new(); 8 9 for _ in 0..8 { 10 let threads = Arc::clone(&threads); 11 handles.push(tokio::spawn(async move { 12 // A CPU loop so a worker stays busy long enough to spread the load. 13 let mut acc = 0u64; 14 for i in 0..20_000_000u64 { 15 acc = acc.wrapping_add(i); 16 } 17 threads.lock().unwrap().insert(format!("{:?}", std::thread::current().id())); 18 acc 19 })); 20 } 21 for h in handles { 22 h.await.unwrap(); 23 } 24 25 let count = threads.lock().unwrap().len(); 26 println!("8 tasks ran across {count} distinct OS threads"); 27 } ``` Real output on an 8+ core machine: ```plaintext 1 8 tasks ran across 8 distinct OS threads ``` > **Note:** That `8` is the worker-thread count, which equals the number of CPU cores on the test machine. On a 4-core box you would see `4`; the exact number is hardware-dependent. The point is **more than one**: real parallelism. The **current-thread** runtime (`flavor = "current_thread"`) runs everything on one thread: concurrent, never parallel, exactly like Node’s event loop: ```rust 1 use std::collections::HashSet; 2 use std::sync::{Arc, Mutex}; 3 4 // current_thread flavor: everything runs on ONE thread (like Node's event loop). 5 // Tasks are CONCURRENT (interleaved) but never PARALLEL. 6 #[tokio::main(flavor = "current_thread")] 7 async fn main() { 8 let threads = Arc::new(Mutex::new(HashSet::new())); 9 let mut handles = Vec::new(); 10 11 for _ in 0..8 { 12 let threads = Arc::clone(&threads); 13 handles.push(tokio::spawn(async move { 14 tokio::task::yield_now().await; // let the single thread interleave tasks 15 threads.lock().unwrap().insert(format!("{:?}", std::thread::current().id())); 16 })); 17 } 18 for h in handles { 19 h.await.unwrap(); 20 } 21 22 let count = threads.lock().unwrap().len(); 23 println!("8 tasks ran across {count} distinct OS thread(s)"); 24 } ``` Real output: ```plaintext 1 8 tasks ran across 1 distinct OS thread(s) ``` This is why the multi-thread runtime requires your tasks to be `Send`: a task may be moved to a different worker thread at an `.await` point. The single-thread runtime has no such requirement. (See the Pitfalls section for the `!Send` error this produces.) Runtime flavors are covered in depth in [The Tokio Runtime](/11-async/02-tokio-intro/). ### Concurrency on one thread is still a win for I/O [Section titled “Concurrency on one thread is still a win for I/O”](#concurrency-on-one-thread-is-still-a-win-for-io) Even with no parallelism, concurrency speeds up I/O-bound work, because waiting overlaps. Here three async sleeps run on a single thread and still finish in \~100ms, not \~300ms; the thread is free to advance other tasks while each one waits: ```rust 1 use std::time::Instant; 2 3 // tokio::time::sleep yields to the runtime, so other tasks run during the wait. 4 async fn good_task(id: u32) { 5 tokio::time::sleep(std::time::Duration::from_millis(100)).await; 6 println!(" good_task {id} done"); 7 } 8 9 #[tokio::main(flavor = "current_thread")] 10 async fn main() { 11 let start = Instant::now(); 12 tokio::join!(good_task(1), good_task(2), good_task(3)); 13 println!("non-blocking version took ~{} ms", start.elapsed().as_millis()); 14 } ``` Real output (ordering of the “done” lines varies): ```plaintext 1 good_task 2 done 2 good_task 3 done 3 good_task 1 done 4 non-blocking version took ~102 ms ``` This is the heart of why async exists: a single thread can serve thousands of waiting connections. Parallelism adds throughput on top; concurrency alone already wins for I/O. ### Structured concurrency: don’t leak tasks [Section titled “Structured concurrency: don’t leak tasks”](#structured-concurrency-dont-leak-tasks) A loose `tokio::spawn` is fire-and-forget: if the parent finishes, the child may be silently abandoned, and errors inside it vanish. **Structured concurrency** keeps a group of tasks tied to a scope: you spawn them into a container, await them together, and when the container is dropped any stragglers are cancelled. Tokio’s [`JoinSet`](https://docs.rs/tokio/latest/tokio/task/struct.JoinSet.html) is the workhorse: ```rust 1 use tokio::task::JoinSet; 2 3 async fn process(item: u32) -> u32 { 4 tokio::time::sleep(tokio::time::Duration::from_millis(50)).await; 5 item * item 6 } 7 8 #[tokio::main] 9 async fn main() { 10 let mut set = JoinSet::new(); 11 12 // Spawn a dynamic number of tasks into a structured set. 13 for item in 1..=5 { 14 set.spawn(process(item)); 15 } 16 17 // join_next waits for the next task to finish, in completion order. 18 // When `set` is dropped, any still-running tasks are aborted automatically. 19 let mut total = 0; 20 while let Some(res) = set.join_next().await { 21 total += res.unwrap(); 22 } 23 24 println!("sum of squares = {total}"); 25 } ``` Real output: ```plaintext 1 sum of squares = 55 ``` The key safety property: `JoinSet` owns the tasks. If `main` returns early, panics, or you `break` out of the loop, the set’s `Drop` aborts the unfinished tasks. There are no orphaned, still-running tasks logging into the void: the failure mode you get with bare `spawn`. This is the Rust answer to a JavaScript codebase littered with un-awaited promises. ### Cancellation: a first-class concept [Section titled “Cancellation: a first-class concept”](#cancellation-a-first-class-concept) This is where Rust pulls decisively ahead of JavaScript. A `Promise`, once started, runs to completion even if nobody is listening; there is no built-in `.cancel()`. (The `AbortController`/`AbortSignal` API helps, but only for APIs that explicitly opt in, like `fetch`.) In Rust, a future is just a value, so **dropping it stops its work**, and its destructors run for clean teardown. Three layers, from coarse to fine: 1. **Drop the future** → its `poll` is never called again; its `Drop` impls run. 2. **`JoinHandle::abort()` / `JoinSet::abort_all()`** → ask the runtime to stop a spawned task at its next `.await`. 3. **Cooperative cancellation** with a [`CancellationToken`](https://docs.rs/tokio-util/latest/tokio_util/sync/struct.CancellationToken.html) → the task checks a signal and winds down gracefully. The simplest form is a timeout, which drops the loser: ```rust 1 use tokio::time::{timeout, sleep, Duration}; 2 3 async fn slow_query() -> &'static str { 4 sleep(Duration::from_millis(500)).await; 5 "query result" 6 } 7 8 #[tokio::main] 9 async fn main() { 10 // Like Promise.race([query, timer]) — but the losing future is actually 11 // DROPPED (cancelled), not left running in the background. 12 match timeout(Duration::from_millis(100), slow_query()).await { 13 Ok(value) => println!("got: {value}"), 14 Err(_elapsed) => println!("timed out — the query future was dropped/cancelled"), 15 } 16 } ``` Real output: ```plaintext 1 timed out — the query future was dropped/cancelled ``` Because cancellation runs destructors, you get RAII-style cleanup for free. A guard’s `Drop` fires whether the task completes or is aborted: ```rust 1 use tokio::time::{sleep, Duration}; 2 3 // A guard whose Drop runs even when the future is cancelled (dropped). 4 struct CleanupGuard; 5 impl Drop for CleanupGuard { 6 fn drop(&mut self) { 7 println!(" cleanup: releasing resources"); 8 } 9 } 10 11 async fn job() { 12 let _guard = CleanupGuard; // Drop runs if the future is cancelled mid-flight 13 println!(" job started"); 14 sleep(Duration::from_secs(10)).await; // never completes in this demo 15 println!(" job finished"); // unreachable here 16 } 17 18 #[tokio::main] 19 async fn main() { 20 let handle = tokio::spawn(job()); 21 sleep(Duration::from_millis(50)).await; // let the job start 22 23 handle.abort(); // request cancellation 24 let result = handle.await; 25 println!("task was cancelled: {}", result.unwrap_err().is_cancelled()); 26 } ``` Real output: ```plaintext 1 job started 2 cleanup: releasing resources 3 task was cancelled: true ``` Notice the `CleanupGuard::drop` ran even though the job never reached its own end: that is the cancellation path executing your teardown. In JavaScript there is no equivalent: a Promise that “loses” a `Promise.race` keeps executing, and any cleanup you wrote after its `await` simply never fires. > **Warning:** Cancellation in Rust happens **only at `.await` points**. A task that enters a long synchronous CPU loop with no `.await` cannot be aborted until it next yields: the `abort` is recorded but only takes effect at the next suspension. This is why CPU-bound work belongs on a thread / [`spawn_blocking`](/11-async/09-spawning-tasks/), not inline in a task. ### Cooperative cancellation with `CancellationToken` [Section titled “Cooperative cancellation with CancellationToken”](#cooperative-cancellation-with-cancellationtoken) For graceful shutdown — letting a worker finish its current unit and clean up — use a `CancellationToken` from `tokio-util`. Cloning the token shares one cancellation state, so a single `.cancel()` signals every holder at once. This is the idiomatic shape for a long-lived worker loop, combining it with [`select!`](/11-async/07-select-join/): ```rust 1 use tokio::time::{sleep, Duration}; 2 use tokio_util::sync::CancellationToken; 3 use tokio::task::JoinSet; 4 5 // Three workers that share one CancellationToken. When the token fires, 6 // they all wind down — structured, parent-driven cancellation. 7 async fn worker(id: u32, token: CancellationToken) { 8 let mut done = 0; 9 loop { 10 tokio::select! { 11 // Branch 1: cancellation requested — exit the loop cleanly. 12 _ = token.cancelled() => { 13 println!(" worker {id}: stopping (did {done} units)"); 14 return; 15 } 16 // Branch 2: do one unit of work. 17 _ = sleep(Duration::from_millis(30)) => { 18 done += 1; 19 } 20 } 21 } 22 } 23 24 #[tokio::main] 25 async fn main() { 26 let token = CancellationToken::new(); 27 let mut set = JoinSet::new(); 28 for id in 1..=3 { 29 set.spawn(worker(id, token.clone())); // clones share one cancellation state 30 } 31 32 // Run for a bit, then signal shutdown to all workers at once. 33 sleep(Duration::from_millis(100)).await; 34 println!("main: broadcasting shutdown"); 35 token.cancel(); 36 37 // Wait for every worker to finish its cleanup before exiting. 38 while set.join_next().await.is_some() {} 39 println!("main: all workers stopped cleanly"); 40 } ``` Real output: ```plaintext 1 main: broadcasting shutdown 2 worker 1: stopping (did 3 units) 3 worker 2: stopping (did 3 units) 4 worker 3: stopping (did 3 units) 5 main: all workers stopped cleanly ``` This is the difference between *forced* cancellation (`abort`: stop at the next `.await`, no chance to react) and *cooperative* cancellation (the worker observes the token and decides how to wind down). For graceful shutdown you almost always want the cooperative version, because the worker controls its own teardown. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | Node.js / TypeScript | Rust + Tokio | | ------------------------------- | --------------------------------------------- | -------------------------------------------------- | | **Concurrency unit** | Promise on the event loop | Task (`tokio::spawn`) or future | | **Parallelism unit** | Worker Thread (separate isolate) | OS thread / multi-thread runtime workers | | **Threads under the hood** | One JS thread + libuv pool | M:N, many tasks over N worker threads | | **Default execution** | Concurrent, single-threaded | Concurrent + parallel (multi-thread runtime) | | **Single-threaded mode** | The only mode for JS code | Opt-in (`flavor = "current_thread"`) | | **Sharing data across workers** | Copy / structured clone / `SharedArrayBuffer` | Borrow-checked shared memory (`Arc`, `Mutex`) | | **Task cost** | Promise is cheap; Worker is heavy | Task is very cheap; thread is heavy | | **Cancellation** | No built-in cancel; `AbortController` opt-in | Drop the future, `abort()`, or `CancellationToken` | | **Cleanup on cancel** | Code after a lost `await` never runs | `Drop` impls run on cancellation | | **Leak protection** | Un-awaited promises run unsupervised | `JoinSet` cancels stragglers on drop | ### Why Rust makes you choose [Section titled “Why Rust makes you choose”](#why-rust-makes-you-choose) Node’s “everything is one thread” model is simpler but limiting: CPU-bound work blocks everything, and parallelism means crossing a serialization boundary into a Worker. Rust separates the two axes — you write concurrent `async` code, then pick a runtime flavor for the parallelism you want — and the borrow checker lets parallel threads share memory *safely* (data races are a compile error). This is “fearless concurrency”: the cost is that the compiler insists you make `Send`/`Sync` correct up front, which can feel strict at first. ### The “cancellation gap” closed [Section titled “The “cancellation gap” closed”](#the-cancellation-gap-closed) The most underappreciated win is cancellation. In JavaScript, “stop this in-flight work” ranges from awkward to impossible. In Rust it is the *default consequence of dropping a value*, with destructors guaranteeing cleanup. This makes timeouts, “race and discard the loser,” and graceful shutdown straightforward and correct, patterns that are perennially buggy in Node services. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Non-`Send` data held across `.await` in a spawned task [Section titled “Pitfall 1: Non-Send data held across .await in a spawned task”](#pitfall-1-non-send-data-held-across-await-in-a-spawned-task) The multi-thread runtime may move a task between worker threads at any `.await`, so spawned futures must be `Send`. Holding a `!Send` type (like `Rc`, the non-atomic reference counter; see [Section 05: reference counting](/05-ownership/07-reference-counting/)) across an `.await` makes the whole future `!Send`, and `tokio::spawn` rejects it. ```rust 1 use std::rc::Rc; 2 3 #[tokio::main] 4 async fn main() { 5 tokio::spawn(async { 6 let data = Rc::new(5); // Rc is !Send 7 tokio::time::sleep(tokio::time::Duration::from_millis(1)).await; 8 println!("{}", data); // data held across .await -> future is !Send 9 }); 10 } ``` Real compiler error (`cargo build`): ```plaintext 1 error: future cannot be sent between threads safely 2 --> src/main.rs:5:5 3 | 4 5 | / tokio::spawn(async { 5 6 | | let data = Rc::new(5); // Rc is !Send 6 7 | | tokio::time::sleep(tokio::time::Duration::from_millis(1)).await; 7 8 | | println!("{}", data); // data held across .await -> future is !Send 8 9 | | }); 9 | |______^ future created by async block is not `Send` 10 | 11 = help: within `{async block@src/main.rs:5:18: 5:23}`, the trait `Send` is not implemented for `Rc<i32>` 12 note: future is not `Send` as this value is used across an await 13 --> src/main.rs:7:67 14 | 15 6 | let data = Rc::new(5); // Rc is !Send 16 | ---- has type `Rc<i32>` which is not `Send` 17 7 | tokio::time::sleep(tokio::time::Duration::from_millis(1)).await; 18 | ^^^^^ await occurs here, with `data` maybe used later 19 note: required by a bound in `tokio::spawn` ``` The fixes: use `Arc` instead of `Rc` (it is the atomic, `Send` reference counter), or restructure so the `!Send` value is dropped *before* the `.await` (e.g., enclose it in a `{ }` block that ends first). If the work genuinely must stay on one thread, use a `LocalSet` or the `current_thread` runtime. ### Pitfall 2: Blocking the runtime with synchronous waits [Section titled “Pitfall 2: Blocking the runtime with synchronous waits”](#pitfall-2-blocking-the-runtime-with-synchronous-waits) The number-one async footgun for Node developers: calling a *blocking* function (`std::thread::sleep`, synchronous file/network I/O, a tight CPU loop) directly inside a task. It does not yield, so it freezes the worker thread, starving every other task scheduled there. This compiles and runs; it is a performance bug, which makes it sneaky. ```rust 1 use std::time::Instant; 2 3 // Anti-pattern: std::thread::sleep BLOCKS the worker thread, so other tasks 4 // on that thread cannot make progress. 5 async fn bad_task(id: u32) { 6 std::thread::sleep(std::time::Duration::from_millis(100)); // blocks the thread! 7 println!(" bad_task {id} done"); 8 } 9 10 #[tokio::main(flavor = "current_thread")] 11 async fn main() { 12 let start = Instant::now(); 13 // Even though we "join" them, on a single-threaded runtime they run serially 14 // because each one monopolizes the only worker thread. 15 tokio::join!(bad_task(1), bad_task(2), bad_task(3)); 16 println!("blocking version took ~{} ms", start.elapsed().as_millis()); 17 } ``` Real output, \~300ms (serial) instead of \~100ms (overlapping): ```plaintext 1 bad_task 1 done 2 bad_task 2 done 3 bad_task 3 done 4 blocking version took ~306 ms ``` The fix for waiting is the async equivalent (`tokio::time::sleep(...).await`, async I/O). The fix for genuine blocking/CPU work is [`tokio::task::spawn_blocking`](/11-async/09-spawning-tasks/), which moves it onto a dedicated blocking-thread pool so the async workers stay free. ### Pitfall 3: Confusing “concurrent” with “parallel” [Section titled “Pitfall 3: Confusing “concurrent” with “parallel””](#pitfall-3-confusing-concurrent-with-parallel) Two sequential `.await`s are *not* concurrent: the second future has not even started while the first runs (Rust futures are lazy; see [Promises vs Futures](/11-async/00-promises-vs-futures/)). And concurrent is not the same as parallel: on a `current_thread` runtime, `join!`/`select!` interleave tasks on one thread with zero parallelism. If you measured `join!` of CPU-bound tasks on the single-thread runtime expecting a speedup, you would get none — there is only one core in play. Match the tool to the goal: `join!` for overlapping *waiting*, the multi-thread runtime or threads for overlapping *computing*. ### Pitfall 4: Assuming a Promise-style “cancel” cancels nothing [Section titled “Pitfall 4: Assuming a Promise-style “cancel” cancels nothing”](#pitfall-4-assuming-a-promise-style-cancel-cancels-nothing) Because JavaScript Promises cannot really be cancelled, developers sometimes assume Rust’s are the same and leave work running. The opposite is true: in Rust, *forgetting* to keep a future alive cancels it. If you `tokio::spawn` a task and drop the `JoinHandle` without awaiting it, the task keeps running (spawn detaches it). But if you build a future and never spawn or `.await` it, it never runs at all. And dropping a `JoinSet` aborts everything inside. The rule of thumb: a future’s lifetime *is* its work’s lifetime, unless you explicitly `spawn` to detach it. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Pick the runtime flavor deliberately.** Default `#[tokio::main]` (multi-thread) for servers and parallel workloads; `flavor = "current_thread"` for CLIs, tests, or when every task is `!Send` and you want Node-like single-threaded semantics. See [Setting Up Tokio](/11-async/03-tokio-setup/). * **Prefer structured concurrency.** Reach for [`JoinSet`](/11-async/09-spawning-tasks/) (or `join!`/`try_join!`) over scattered `tokio::spawn` so tasks are owned, awaited, and cancelled together. A bare `spawn` is “detach this from supervision”; use it intentionally. * **Keep tasks non-blocking.** Never call blocking code inside a task. Use async APIs for I/O and `spawn_blocking` for CPU/blocking work, so the scheduler can keep the event loop responsive. * **Bound your concurrency.** Unbounded `spawn` can overwhelm a database or remote API. Gate in-flight work with a [`Semaphore`](/11-async/11-sync-primitives/) (shown below): the safe analogue of a connection pool. * **Design for cancellation from the start.** Thread a `CancellationToken` through long-lived workers and select on it, so graceful shutdown is built in rather than bolted on. Let `Drop` handle resource cleanup. * **Use `Arc<Mutex<T>>` for shared mutable state across tasks**, and `Arc` alone for shared read-only data. The pattern is detailed in [The `Arc<Mutex<T>>` Pattern](/11-async/12-arc-mutex-pattern/); when to use the async-aware `tokio::sync::Mutex` vs `std::sync::Mutex` is in [Async Synchronization Primitives](/11-async/11-sync-primitives/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A concurrent fetcher that processes a list of URLs with **bounded concurrency**: the bread-and-butter of crawlers, batch importers, and fan-out API clients. It combines everything on this page: tasks for concurrency, a `Semaphore` to cap in-flight work (like a connection pool), and a `JoinSet` for structured collection so nothing leaks. ```rust 1 use std::sync::Arc; 2 use std::time::Instant; 3 use tokio::sync::Semaphore; 4 use tokio::task::JoinSet; 5 use tokio::time::{sleep, Duration}; 6 7 /// Fetch one URL (simulated). Returns (url, byte length). 8 async fn fetch(url: String) -> (String, usize) { 9 sleep(Duration::from_millis(100)).await; // simulated network latency 10 (url.clone(), url.len() * 10) 11 } 12 13 #[tokio::main] 14 async fn main() { 15 let urls: Vec<String> = (1..=10) 16 .map(|i| format!("https://example.com/page/{i}")) 17 .collect(); 18 19 // Limit concurrency to 3 in-flight requests at a time (like a connection pool). 20 let limit = Arc::new(Semaphore::new(3)); 21 let mut set: JoinSet<(String, usize)> = JoinSet::new(); 22 let start = Instant::now(); 23 24 for url in urls { 25 let limit = Arc::clone(&limit); 26 set.spawn(async move { 27 // Acquire a permit; this await blocks until a slot is free. 28 let _permit = limit.acquire_owned().await.unwrap(); 29 fetch(url).await 30 // _permit dropped here -> slot returned to the pool 31 }); 32 } 33 34 // Collect results as tasks finish. Dropping `set` would abort any stragglers. 35 let mut total_bytes = 0; 36 let mut count = 0; 37 while let Some(res) = set.join_next().await { 38 let (_url, bytes) = res.unwrap(); 39 total_bytes += bytes; 40 count += 1; 41 } 42 43 println!( 44 "fetched {count} pages ({total_bytes} bytes) in ~{} ms with max 3 concurrent", 45 start.elapsed().as_millis() 46 ); 47 } ``` Real output (10 pages, 3 at a time, \~100ms each → \~4 batches): ```plaintext 1 fetched 10 pages (2610 bytes) in ~411 ms with max 3 concurrent ``` The timing tells the story: 10 requests at 100ms each, run three-wide, take roughly `ceil(10 / 3) × 100 ≈ 400 ms` rather than 1000ms (fully serial) or 100ms (fully unbounded). The `Semaphore` is the throttle, the `JoinSet` is the structure, and dropping either cleanly cancels everything in flight. > **Note:** In real code, `fetch` would use an HTTP client like `reqwest` and return a `Result`, which you would collect with `try_join!` or by matching in the loop. See [Concurrent Awaiting](/11-async/07-select-join/) for the error-aware combinators and [Async Channels](/11-async/08-channels/) for streaming results back as they arrive rather than collecting at the end. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Fearless Concurrency](https://doc.rust-lang.org/book/ch16-00-concurrency.html) — threads, message passing, shared state * [The Rust Book — Async, Tasks, and Futures](https://doc.rust-lang.org/book/ch17-00-async-await.html) * [Tokio Tutorial](https://tokio.rs/tokio/tutorial) — especially [Spawning](https://tokio.rs/tokio/tutorial/spawning) and [Graceful Shutdown](https://tokio.rs/tokio/topics/shutdown) * [`tokio::task::JoinSet`](https://docs.rs/tokio/latest/tokio/task/struct.JoinSet.html) and [`tokio_util::sync::CancellationToken`](https://docs.rs/tokio-util/latest/tokio_util/sync/struct.CancellationToken.html) * [`std::thread::scope`](https://doc.rust-lang.org/std/thread/fn.scope.html) — scoped threads for CPU parallelism ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Promises vs Futures](/11-async/00-promises-vs-futures/) — eager Promises vs lazy futures (read this first) * [Async/Await Syntax](/11-async/01-async-await/) — the `async`/`await` syntax and `?` error handling * [The Tokio Runtime](/11-async/02-tokio-intro/) — Node’s event loop vs the Tokio runtime; multi-thread vs current-thread * [Setting Up Tokio](/11-async/03-tokio-setup/) — adding Tokio, `#[tokio::main]`, the runtime builder * [Spawning Tasks](/11-async/09-spawning-tasks/) — `tokio::spawn`, `JoinHandle`, `spawn_blocking`, tasks vs threads * [Concurrent Awaiting](/11-async/07-select-join/) — `Promise.all`/`Promise.race` → `join!`/`try_join!`/`select!` * [Async Channels](/11-async/08-channels/) — moving data between tasks with `mpsc`/`oneshot`/`broadcast`/`watch` * [Async Synchronization Primitives](/11-async/11-sync-primitives/) — async vs `std` `Mutex`/`RwLock`/`Semaphore` * [The `Arc<Mutex<T>>` Pattern](/11-async/12-arc-mutex-pattern/) — shared mutable state across tasks * [Async vs Sync](/11-async/13-async-vs-sync/) — CPU-bound vs I/O-bound; when to use async, threads, or blocking * [Section 05: Ownership](/05-ownership/) and [reference counting](/05-ownership/07-reference-counting/) — `Arc` vs `Rc`, `Send`/`Sync` foundations * [Section 01: Getting Started](/01-getting-started/) and [Section 02: Basics](/02-basics/) — the fundamentals these examples assume * [Section 12: Modules & Packages](/12-modules-packages/) — adding `tokio`/`tokio-util` and bringing them into scope *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Concurrent, not sequential [Section titled “Exercise 1: Concurrent, not sequential”](#exercise-1-concurrent-not-sequential) **Difficulty:** Beginner **Objective:** Turn a sequential set of I/O-bound calls into concurrent tasks and observe the timing collapse. **Instructions:** The program below checks three services one after another, taking \~250ms. Rewrite it to run all three checks concurrently using `tokio::spawn` (or `JoinSet`), so the total time drops to roughly the slowest single check (\~120ms). Print how many of the three are “healthy” (latency under 100ms). ```rust 1 use std::time::Instant; 2 use tokio::time::{sleep, Duration}; 3 4 async fn check_health(service: &str, ms: u64) -> (String, bool) { 5 sleep(Duration::from_millis(ms)).await; 6 (service.to_string(), ms < 100) 7 } 8 9 #[tokio::main] 10 async fn main() { 11 let start = Instant::now(); 12 // TODO: run these three concurrently instead of awaiting one at a time. 13 let a = check_health("auth", 50).await; 14 let b = check_health("db", 80).await; 15 let c = check_health("cache", 120).await; 16 let healthy = [a, b, c].iter().filter(|(_, ok)| *ok).count(); 17 println!("{healthy}/3 healthy in ~{} ms", start.elapsed().as_millis()); 18 } ``` Solution Spawn each check into a `JoinSet` so they overlap; collect as they complete. (You could also use `tokio::join!` since the count is fixed.) ```rust 1 use std::time::Instant; 2 use tokio::task::JoinSet; 3 use tokio::time::{sleep, Duration}; 4 5 async fn check_health(service: &str, ms: u64) -> (String, bool) { 6 sleep(Duration::from_millis(ms)).await; 7 (service.to_string(), ms < 100) 8 } 9 10 #[tokio::main] 11 async fn main() { 12 let start = Instant::now(); 13 let services = [("auth", 50u64), ("db", 80), ("cache", 120)]; 14 15 let mut set = JoinSet::new(); 16 for (name, ms) in services { 17 set.spawn(check_health(name, ms)); 18 } 19 20 let mut healthy = 0; 21 let mut total = 0; 22 while let Some(res) = set.join_next().await { 23 let (name, ok) = res.unwrap(); 24 total += 1; 25 if ok { healthy += 1; } 26 println!(" {name}: {}", if ok { "healthy" } else { "DEGRADED" }); 27 } 28 println!("{healthy}/{total} healthy in ~{} ms", start.elapsed().as_millis()); 29 } ``` Real output (the per-service lines arrive in completion order, \~123ms total: the slowest check, not the sum): ```plaintext 1 auth: healthy 2 db: healthy 3 cache: DEGRADED 4 2/3 healthy in ~123 ms ``` The three checks overlap, so the total is governed by the slowest one (\~120ms), not their sum (\~250ms). See [Concurrent Awaiting](/11-async/07-select-join/) for the `join!` alternative. ### Exercise 2: Fail fast and cancel the rest [Section titled “Exercise 2: Fail fast and cancel the rest”](#exercise-2-fail-fast-and-cancel-the-rest) **Difficulty:** Intermediate **Objective:** Use structured concurrency to abort outstanding tasks the moment one fails. **Instructions:** Three downloads run concurrently; one of them (`id == 3`) fails fast. Complete the program so that, on the first error, it prints the error, **aborts the remaining in-flight downloads**, and stops. Use a `JoinSet` and its `abort_all()` method. ```rust 1 use tokio::task::JoinSet; 2 use tokio::time::{sleep, Duration}; 3 4 async fn download(id: u32, ms: u64) -> Result<String, String> { 5 sleep(Duration::from_millis(ms)).await; 6 if id == 3 { 7 Err(format!("download {id} failed")) 8 } else { 9 Ok(format!("file-{id}")) 10 } 11 } 12 13 #[tokio::main] 14 async fn main() { 15 let mut set = JoinSet::new(); 16 set.spawn(download(1, 80)); 17 set.spawn(download(2, 40)); 18 set.spawn(download(3, 20)); // fails fastest 19 20 // TODO: collect results; on the first Err, abort the rest and stop. 21 while let Some(joined) = set.join_next().await { 22 let _ = joined; // replace with real handling 23 } 24 println!("done"); 25 } ``` Solution ```rust 1 use tokio::task::JoinSet; 2 use tokio::time::{sleep, Duration}; 3 4 async fn download(id: u32, ms: u64) -> Result<String, String> { 5 sleep(Duration::from_millis(ms)).await; 6 if id == 3 { 7 Err(format!("download {id} failed")) 8 } else { 9 Ok(format!("file-{id}")) 10 } 11 } 12 13 #[tokio::main] 14 async fn main() { 15 let mut set = JoinSet::new(); 16 set.spawn(download(1, 80)); 17 set.spawn(download(2, 40)); 18 set.spawn(download(3, 20)); // this one fails fastest 19 20 // Stop at the first error; abort the remaining tasks. 21 while let Some(joined) = set.join_next().await { 22 match joined.unwrap() { 23 Ok(file) => println!("ok: {file}"), 24 Err(e) => { 25 println!("error: {e} -> aborting remaining downloads"); 26 set.abort_all(); 27 break; 28 } 29 } 30 } 31 println!("done"); 32 } ``` Real output (the fastest task fails first, so the others are aborted before they print): ```plaintext 1 error: download 3 failed -> aborting remaining downloads 2 done ``` This is the `try_join!` philosophy generalized to a dynamic set: the first failure short-circuits the group. `abort_all()` plus `break` ensures no orphaned tasks survive. Compare with [Concurrent Awaiting](/11-async/07-select-join/)’s `try_join!`. ### Exercise 3: Graceful shutdown with a cancellation token [Section titled “Exercise 3: Graceful shutdown with a cancellation token”](#exercise-3-graceful-shutdown-with-a-cancellation-token) **Difficulty:** Advanced **Objective:** Build a long-running worker that shuts down cooperatively, finishing cleanly rather than being killed mid-step. **Instructions:** Spawn a worker that processes “jobs” every 30ms in a loop. From `main`, let it run \~100ms, then signal a `CancellationToken`. The worker must detect the signal, print how many jobs it completed, and return. `main` should wait for the worker to finish before exiting. Add `tokio-util` to your `Cargo.toml` (`cargo add tokio-util`). ```rust 1 use tokio::time::{sleep, Duration}; 2 use tokio_util::sync::CancellationToken; 3 4 async fn worker(token: CancellationToken) { 5 let mut jobs = 0; 6 loop { 7 // TODO: select between the cancellation signal and doing one job. 8 // On cancellation: print the job count and return. 9 todo!() 10 } 11 } 12 13 #[tokio::main] 14 async fn main() { 15 let token = CancellationToken::new(); 16 let handle = tokio::spawn(worker(token.clone())); 17 sleep(Duration::from_millis(100)).await; 18 // TODO: request shutdown, then wait for the worker to finish. 19 todo!() 20 } ``` Solution ```rust 1 use tokio::time::{sleep, Duration}; 2 use tokio_util::sync::CancellationToken; 3 4 async fn worker(token: CancellationToken) { 5 let mut jobs = 0; 6 loop { 7 tokio::select! { 8 // Cancellation requested: report progress and exit cleanly. 9 _ = token.cancelled() => { 10 println!("worker: shutting down after {jobs} jobs"); 11 return; 12 } 13 // Otherwise, do one unit of work. 14 _ = sleep(Duration::from_millis(30)) => { 15 jobs += 1; 16 } 17 } 18 } 19 } 20 21 #[tokio::main] 22 async fn main() { 23 let token = CancellationToken::new(); 24 let handle = tokio::spawn(worker(token.clone())); 25 26 sleep(Duration::from_millis(100)).await; 27 println!("main: requesting shutdown"); 28 token.cancel(); // cooperative signal 29 handle.await.unwrap(); // wait for clean teardown 30 println!("main: worker stopped"); 31 } ``` Real output (about three 30ms jobs fit into the 100ms window): ```plaintext 1 main: requesting shutdown 2 worker: shutting down after 3 jobs 3 main: worker stopped ``` The important detail is the `select!` between `token.cancelled()` and the work branch: the worker chooses *when* to stop (after the current job), so cleanup is graceful, not forced. This is the production pattern for shutting down servers on `SIGTERM`/Ctrl+C; you would replace the timer in `main` with `tokio::signal::ctrl_c().await`. See [Concurrent Awaiting](/11-async/07-select-join/) and the Tokio graceful-shutdown guide linked above. # Async Synchronization Primitives > JavaScript never makes you pick a lock; Rust does. Choose std's blocking Mutex/RwLock or Tokio's async ones by one rule: do you hold the guard across an .await? When several Rust tasks share mutable state, you reach for a lock, but in async code you have a choice JavaScript never forces on you: a *blocking* lock from the standard library, or an *async-aware* lock from Tokio. Picking the wrong one leads to subtle deadlocks, performance cliffs, or a confusing `future cannot be sent between threads safely` error. This page explains the difference and the one rule that drives the whole decision. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Tokio provides async-aware versions of the standard library’s synchronization types: **`tokio::sync::Mutex`**, **`tokio::sync::RwLock`**, and **`tokio::sync::Semaphore`**. Unlike their `std::sync` counterparts, their locking methods are `async` (you write `lock().await`), so a task that cannot acquire the lock *yields* to the runtime instead of blocking the OS thread. The decisive question is whether you need to **hold a lock across an `.await` point**: if you do, you usually need the Tokio version; if you do not, the plain `std::sync` lock is faster and simpler. > **Note:** Every Rust snippet on this page was compiled and run with `cargo`/`rustc` 1.96.0 (the recorded verification toolchain; 2024 edition). Async examples use `tokio = { version = "1.52", features = ["full"] }`. Rust ships **no built-in async runtime**, so the runtime is always explicit. See [Tokio Setup](/11-async/03-tokio-setup/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) JavaScript has no concept of a lock, because Node runs your code on a **single thread** with a cooperative event loop. Two `async` functions can interleave at `await` points, but they never *truly* run at the same instant, so there is no data race on a plain object. Developers instead reach for ad-hoc concurrency control like a “mutex” promise chain, or a `p-limit`-style semaphore to cap concurrent I/O. ```typescript 1 // TypeScript / JavaScript (Node v22) 2 // There is no real shared-memory race here: the event loop is single-threaded. 3 // But we DO need to limit concurrency, and to serialize a read-modify-write 4 // that spans multiple awaits. 5 6 // A hand-rolled async mutex: each acquire() waits for the previous release(). 7 class AsyncMutex { 8 private tail: Promise<void> = Promise.resolve(); 9 10 async runExclusive<T>(fn: () => Promise<T>): Promise<T> { 11 const prev = this.tail; 12 let release!: () => void; 13 this.tail = new Promise((resolve) => (release = resolve)); 14 await prev; // wait our turn 15 try { 16 return await fn(); 17 } finally { 18 release(); // let the next waiter proceed 19 } 20 } 21 } 22 23 // A semaphore: at most `max` operations run concurrently. 24 class Semaphore { 25 private permits: number; 26 private waiters: Array<() => void> = []; 27 constructor(max: number) { 28 this.permits = max; 29 } 30 async acquire(): Promise<void> { 31 if (this.permits > 0) { 32 this.permits--; 33 return; 34 } 35 await new Promise<void>((resolve) => this.waiters.push(resolve)); 36 this.permits--; 37 } 38 release(): void { 39 this.permits++; 40 this.waiters.shift()?.(); 41 } 42 } 43 44 const stats = { completed: 0, bytes: 0 }; 45 const lock = new AsyncMutex(); 46 const limit = new Semaphore(2); 47 48 async function download(id: number): Promise<number> { 49 await new Promise((r) => setTimeout(r, 20)); 50 return id * 1000; 51 } 52 53 async function worker(id: number): Promise<void> { 54 await limit.acquire(); 55 try { 56 const bytes = await download(id); 57 // A read-modify-write that crosses an await must be serialized. 58 await lock.runExclusive(async () => { 59 stats.completed += 1; 60 stats.bytes += bytes; 61 }); 62 } finally { 63 limit.release(); 64 } 65 } 66 67 await Promise.all([1, 2, 3, 4, 5].map(worker)); 68 console.log(stats); // { completed: 5, bytes: 15000 } ``` Two things to notice, because they map directly onto the Rust version: * The `AsyncMutex` exists to serialize an operation that **spans `await`s**, not to prevent a CPU-level data race (Node’s single thread already prevents those). * The `Semaphore` exists to **cap concurrency**: limit how many downloads are in flight. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust gives you these primitives as battle-tested library types instead of hand-rolled classes. Because tasks can run on **different OS threads** under Tokio’s multi-thread scheduler, the lock does real memory-safety work here, beyond just ordering. ```rust 1 // Rust — tokio::sync primitives for shared async state 2 use std::sync::Arc; 3 use tokio::sync::{Mutex, Semaphore}; 4 use tokio::time::{sleep, Duration}; 5 6 /// Shared, mutable counters updated by every worker. 7 struct Stats { 8 completed: u32, 9 bytes: u64, 10 } 11 12 async fn download(id: u32) -> u64 { 13 sleep(Duration::from_millis(20)).await; // pretend this is a network call 14 (id as u64) * 1000 15 } 16 17 #[tokio::main] 18 async fn main() { 19 // At most 2 downloads may run at the same time (like the JS Semaphore). 20 let limit = Arc::new(Semaphore::new(2)); 21 // Shared mutable state guarded by an async-aware Mutex. 22 let stats = Arc::new(Mutex::new(Stats { completed: 0, bytes: 0 })); 23 24 let mut handles = Vec::new(); 25 for id in 1..=5 { 26 let limit = Arc::clone(&limit); 27 let stats = Arc::clone(&stats); 28 handles.push(tokio::spawn(async move { 29 // Acquire a permit; this future waits if 2 are already running. 30 let _permit = limit.acquire().await.unwrap(); 31 32 let bytes = download(id).await; 33 34 // Lock the stats just long enough to update them. 35 let mut s = stats.lock().await; 36 s.completed += 1; 37 s.bytes += bytes; 38 })); 39 } 40 41 for h in handles { 42 h.await.unwrap(); 43 } 44 45 let s = stats.lock().await; 46 println!("completed = {}, bytes = {}", s.completed, s.bytes); 47 } ``` Real output (Rust 1.96.0, Tokio 1.52.3): ```text 1 completed = 5, bytes = 15000 ``` The `Arc<...>` wrapping is what lets multiple tasks own a handle to the same value. That pattern has its own page, [Arc + Mutex pattern](/11-async/12-arc-mutex-pattern/). Here we focus on *which lock* goes inside the `Arc`. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The `std` vs `tokio` lock families [Section titled “The std vs tokio lock families”](#the-std-vs-tokio-lock-families) For every common lock, there are two implementations: | Job | `std::sync` (blocking) | `tokio::sync` (async-aware) | | ------------------------- | ---------------------- | --------------------------- | | Exclusive access | `std::sync::Mutex<T>` | `tokio::sync::Mutex<T>` | | Many readers / one writer | `std::sync::RwLock<T>` | `tokio::sync::RwLock<T>` | | Cap concurrency | *(none in std)* | `tokio::sync::Semaphore` | The standard library’s `Mutex::lock()` returns a `LockGuard` directly and **blocks the current OS thread** if the lock is taken. Tokio’s `Mutex::lock()` is an `async fn` returning a future; awaiting it **suspends only the current task** and lets the runtime schedule other tasks on that thread while it waits. ```rust 1 // std: synchronous, blocks the thread 2 let guard = std_mutex.lock().unwrap(); // .unwrap() because std locks can be "poisoned" 3 4 // tokio: asynchronous, yields the task 5 let guard = tokio_mutex.lock().await; // no Result — tokio locks are not poisoned ``` > **Tip:** A small but real ergonomic difference: `std::sync::Mutex::lock()` returns a `Result` because a `std` lock becomes *poisoned* if a thread panics while holding it. `tokio::sync::Mutex::lock()` returns the guard directly — Tokio locks are not poisonable — so there is no `.unwrap()`. ### The one rule: holding a guard across `.await` [Section titled “The one rule: holding a guard across .await”](#the-one-rule-holding-a-guard-across-await) This is the heart of the page. A `std::sync::MutexGuard` is **not `Send`** — it cannot be moved to another thread. A Tokio task may be paused at an `.await` and resumed **on a different worker thread**. So if you hold a `std` guard across an `.await`, the compiler refuses to let that future be spawned, with a `future cannot be sent between threads safely` error (shown in [Common Pitfalls](#common-pitfalls)). The decision tree is therefore: * **Do you keep the lock locked while you `.await` something?** → use `tokio::sync::Mutex` / `RwLock`. * **Do you only lock, touch the data, and unlock, with no `.await` in between?** → use `std::sync::Mutex`. It is faster and avoids dragging async machinery into a tiny critical section. ### Why `std` locks are often the *better* choice [Section titled “Why std locks are often the better choice”](#why-std-locks-are-often-the-better-choice) It is a common misconception that “async code must use async locks everywhere.” In fact, for a short critical section that does no `.await`, `std::sync::Mutex` is the idiomatic and faster choice; even Tokio’s own documentation recommends it. The async `Mutex` carries extra bookkeeping (a wait queue of tasks) and lets the task yield, which is pure overhead if you never actually need to yield while holding the lock. ```rust 1 // std: drop the guard in a tight scope BEFORE any .await 2 use std::sync::{Arc, Mutex}; 3 use tokio::time::{sleep, Duration}; 4 5 #[tokio::main] 6 async fn main() { 7 let data = Arc::new(Mutex::new(0_u32)); 8 let d = Arc::clone(&data); 9 let handle = tokio::spawn(async move { 10 // Compute under the lock, then release it before awaiting. 11 { 12 let mut guard = d.lock().unwrap(); 13 *guard += 1; 14 } // guard dropped here — lock released 15 16 sleep(Duration::from_millis(10)).await; // no lock held across await 17 }); 18 handle.await.unwrap(); 19 println!("{}", *data.lock().unwrap()); 20 } ``` Real output: ```text 1 1 ``` The explicit `{ ... }` scope is the workhorse pattern: it forces the guard’s `Drop` (which releases the lock) to run *before* the `.await`, keeping the future `Send`. ### `RwLock`: many readers, one writer [Section titled “RwLock: many readers, one writer”](#rwlock-many-readers-one-writer) When reads vastly outnumber writes (a config map, a cache index), an `RwLock` lets many readers proceed concurrently and only serializes writers. ```rust 1 use std::sync::Arc; 2 use tokio::sync::RwLock; 3 4 #[tokio::main] 5 async fn main() { 6 let config = Arc::new(RwLock::new(vec!["a".to_string()])); 7 8 // Many readers can hold the read lock at once. 9 let r1 = Arc::clone(&config); 10 let reader = tokio::spawn(async move { 11 let guard = r1.read().await; 12 guard.len() 13 }); 14 15 // A single writer needs exclusive access. 16 { 17 let mut guard = config.write().await; 18 guard.push("b".to_string()); 19 } 20 21 println!("reader saw len in [1,2]: {}", reader.await.unwrap()); 22 println!("final len = {}", config.read().await.len()); 23 } ``` Real output: ```text 1 reader saw len in [1,2]: 2 2 final len = 2 ``` > **Note:** The reader’s result is `1` or `2` depending on whether it ran before or after the writer — both are correct. The point is that `read().await` and `write().await` coordinate access; you never observe a torn, half-written `Vec`. ### `Semaphore`: capping concurrency [Section titled “Semaphore: capping concurrency”](#semaphore-capping-concurrency) A `Semaphore` hands out a fixed number of *permits*. A task calls `acquire().await`; if no permit is free, the task waits. When the returned permit is dropped, a permit is returned to the pool. This is the direct analog of the JavaScript `p-limit` / hand-rolled semaphore above, and `std` has no equivalent. ```rust 1 use std::sync::Arc; 2 use tokio::sync::Semaphore; 3 use tokio::time::{sleep, Duration}; 4 5 #[tokio::main] 6 async fn main() { 7 let sem = Arc::new(Semaphore::new(2)); // 2 concurrent permits 8 let mut handles = Vec::new(); 9 for id in 1..=4 { 10 let sem = Arc::clone(&sem); 11 handles.push(tokio::spawn(async move { 12 let _permit = sem.acquire().await.unwrap(); 13 println!("task {id} acquired permit"); 14 sleep(Duration::from_millis(10)).await; 15 println!("task {id} releasing permit"); 16 // _permit dropped at end of scope -> permit returned 17 })); 18 } 19 for h in handles { 20 h.await.unwrap(); 21 } 22 } ``` Real output (one possible interleaving): ```text 1 task 1 acquired permit 2 task 2 acquired permit 3 task 2 releasing permit 4 task 1 releasing permit 5 task 3 acquired permit 6 task 4 acquired permit 7 task 4 releasing permit 8 task 3 releasing permit ``` Notice that tasks 3 and 4 do not even start their work until 1 and 2 release their permits — exactly two run at a time. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / JavaScript (Node) | Rust + Tokio | | ---------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------- | | Need for locks at all | No data races (single-threaded event loop); locks only *order* async ops | Real shared-memory concurrency across worker threads; locks enforce safety | | Built-in mutex | None (hand-rolled or `async-mutex` / `p-limit` npm packages) | `std::sync::Mutex` and `tokio::sync::Mutex` in the standard toolset | | Acquire semantics | `await` a promise chain | `.lock().await` (async) or `.lock().unwrap()` (blocking) | | Holding across `await` | Always fine — same thread | Fine with `tokio` lock; a compile error with `std` lock (`!Send` guard) | | Releasing the lock | Manual `release()` in a `finally` | Automatic — the guard’s `Drop` releases it (RAII), no `finally` needed | | Read/write split | Not built in | `tokio::sync::RwLock` (and `std::sync::RwLock`) | | Concurrency cap | `p-limit` / hand-rolled | `tokio::sync::Semaphore` | | Poisoning | N/A | `std` locks poison on panic (returns `Result`); `tokio` locks do not | The deepest conceptual difference is **RAII release**: there is no `release()` to forget. The lock is tied to the lifetime of the guard value. When the guard goes out of scope, the lock is freed — which is precisely why “scope the guard” is the fix for the across-`await` problem. > **Warning:** “Use `tokio::sync::Mutex` because I’m in async code” is a reflex worth resisting. The right reflex is: *do I `.await` while holding it?* If not, `std::sync::Mutex` is the leaner, faster, idiomatic choice. See [async vs sync](/11-async/13-async-vs-sync/) for the broader “when is async even the right tool” discussion. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Holding a `std` guard across `.await` [Section titled “Pitfall 1: Holding a std guard across .await”](#pitfall-1-holding-a-std-guard-across-await) This is the error nearly every TypeScript/JavaScript developer hits first. It looks innocent: ```rust 1 // does not compile (future cannot be sent between threads safely) 2 use std::sync::{Arc, Mutex}; 3 use tokio::time::{sleep, Duration}; 4 5 #[tokio::main] 6 async fn main() { 7 let data = Arc::new(Mutex::new(0_u32)); 8 let d = Arc::clone(&data); 9 let handle = tokio::spawn(async move { 10 let mut guard = d.lock().unwrap(); // std::sync::MutexGuard 11 sleep(Duration::from_millis(10)).await; // held across .await — !Send 12 *guard += 1; 13 }); 14 handle.await.unwrap(); 15 println!("{}", *data.lock().unwrap()); 16 } ``` The real `cargo build` error: ```text 1 error: future cannot be sent between threads safely 2 --> src/bin/std_across_await.rs:9:18 3 | 4 9 | let handle = tokio::spawn(async move { 5 | __________________^ 6 10 | | let mut guard = d.lock().unwrap(); // std::sync::MutexGuard 7 11 | | sleep(Duration::from_millis(10)).await; // hold the guard across .await 8 12 | | *guard += 1; 9 13 | | }); 10 | |______^ future created by async block is not `Send` 11 | 12 = help: within `{async block@src/bin/std_across_await.rs:9:31: 9:41}`, the trait `Send` is not implemented for `std::sync::MutexGuard<'_, u32>` 13 note: future is not `Send` as this value is used across an await 14 --> src/bin/std_across_await.rs:11:42 15 | 16 10 | let mut guard = d.lock().unwrap(); 17 | --------- has type `std::sync::MutexGuard<'_, u32>` which is not `Send` 18 11 | sleep(Duration::from_millis(10)).await; 19 | ^^^^^ await occurs here, with `mut guard` maybe used later 20 note: required by a bound in `tokio::spawn` ``` **Two valid fixes:** 1. Drop the guard before the `.await` by scoping it (shown earlier) — keeps the cheap `std` lock. 2. Switch to `tokio::sync::Mutex`, whose guard *is* `Send`, when you genuinely must stay locked across the `.await`: ```rust 1 // tokio::sync::Mutex guard is Send, so holding across .await compiles 2 use std::sync::Arc; 3 use tokio::sync::Mutex; 4 use tokio::time::{sleep, Duration}; 5 6 #[tokio::main] 7 async fn main() { 8 let data = Arc::new(Mutex::new(0_u32)); 9 let d = Arc::clone(&data); 10 let handle = tokio::spawn(async move { 11 let mut guard = d.lock().await; // tokio MutexGuard IS Send 12 sleep(Duration::from_millis(10)).await; // OK to hold across .await 13 *guard += 1; 14 }); 15 handle.await.unwrap(); 16 println!("{}", *data.lock().await); 17 } ``` Real output: `1`. ### Pitfall 2: Locking the same lock twice in one task (self-deadlock) [Section titled “Pitfall 2: Locking the same lock twice in one task (self-deadlock)”](#pitfall-2-locking-the-same-lock-twice-in-one-task-self-deadlock) Unlike Node, where there is no real lock to deadlock on, a Tokio `Mutex` is **not reentrant**. If a task holds the guard and then tries to lock the same mutex again, it waits forever — the permit it is waiting for is held by itself. ```rust 1 use tokio::sync::Mutex; 2 use tokio::time::{timeout, Duration}; 3 4 #[tokio::main] 5 async fn main() { 6 let m = Mutex::new(0); 7 let _g1 = m.lock().await; 8 // Second lock on the SAME mutex while _g1 is alive -> blocks forever. 9 // The timeout wrapper lets the demo terminate instead of hanging. 10 let res = timeout(Duration::from_millis(50), m.lock()).await; 11 match res { 12 Ok(_) => println!("acquired again (unexpected)"), 13 Err(_) => println!("timed out: second lock() never succeeded (self-deadlock)"), 14 } 15 } ``` Real output: ```text 1 timed out: second lock() never succeeded (self-deadlock) ``` The fix is to restructure so the lock is acquired once, or release the first guard (`drop(_g1)`) before locking again. ### Pitfall 3: Trusting the compiler to catch *every* across-`await` hold [Section titled “Pitfall 3: Trusting the compiler to catch every across-await hold”](#pitfall-3-trusting-the-compiler-to-catch-every-across-await-hold) The `!Send` error only fires when the future must be `Send` — for example when you `tokio::spawn` it. On a current-thread runtime, or for a future that never crosses a thread boundary, holding a `std` guard across `.await` **compiles** but is still a latent deadlock risk and almost always a bug. Clippy’s `await_holding_lock` lint catches it regardless: ```rust 1 use std::sync::Mutex; 2 use tokio::time::{sleep, Duration}; 3 4 async fn bump(m: &Mutex<u32>) { 5 let mut g = m.lock().unwrap(); 6 sleep(Duration::from_millis(1)).await; // holding std guard across await 7 *g += 1; 8 } ``` Real `cargo clippy` warning: ```text 1 warning: this `MutexGuard` is held across an await point 2 --> src/bin/clippy_hold.rs:5:9 3 | 4 5 | let mut g = m.lock().unwrap(); 5 | ^^^^^ 6 | 7 = help: consider using an async-aware `Mutex` type or ensuring the `MutexGuard` is dropped before calling `await` 8 note: these are all the await points this lock is held through 9 --> src/bin/clippy_hold.rs:6:37 10 | 11 6 | sleep(Duration::from_millis(1)).await; // holding std guard across await 12 | ^^^^^ 13 = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#await_holding_lock 14 = note: `#[warn(clippy::await_holding_lock)]` on by default ``` > **Tip:** Run `cargo clippy` in CI. The `await_holding_lock` lint is on by default and is your best defense against the latent (non-spawned) version of Pitfall 1. ### Pitfall 4: Reaching for a lock when an atomic or channel is simpler [Section titled “Pitfall 4: Reaching for a lock when an atomic or channel is simpler”](#pitfall-4-reaching-for-a-lock-when-an-atomic-or-channel-is-simpler) A `Mutex<u64>` counter incremented under a lock works, but for a single integer an `AtomicU64` (no lock at all) or a `tokio::sync::mpsc` channel (no shared mutable state at all) is often clearer and faster. Locks are not the only tool — see [Channels](/11-async/08-channels/) for the “share by communicating” alternative. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Default to `std::sync::Mutex`/`RwLock` for non-`await` critical sections.** Only reach for `tokio::sync` locks when you must hold the guard across an `.await`. This is Tokio’s own recommendation. * **Keep critical sections tiny.** Compute outside the lock; lock only to read or commit the result. A long critical section serializes your tasks and erases the benefit of async. * **Use an explicit `{ }` scope (or `drop(guard)`)** to release a guard before an `.await` when using a `std` lock. * **Prefer `RwLock` only when reads dominate and writes are rare.** For balanced or write-heavy access, a plain `Mutex` is simpler and frequently faster (an `RwLock` has more bookkeeping). * **Use `Semaphore` for backpressure / concurrency limits**, e.g. capping simultaneous outbound HTTP requests or database connections. * **For spawned tasks, prefer the `owned` variants** — `Mutex::lock_owned`, `Semaphore::acquire_owned` — to sidestep guard-lifetime issues with `'static` futures: ```rust 1 use std::sync::Arc; 2 use tokio::sync::Semaphore; 3 4 #[tokio::main] 5 async fn main() { 6 let sem = Arc::new(Semaphore::new(1)); 7 let sem2 = Arc::clone(&sem); 8 let handle = tokio::spawn(async move { 9 // acquire_owned consumes the Arc clone -> an owned permit with no borrow. 10 let _permit = sem2.acquire_owned().await.unwrap(); 11 "did work" 12 }); 13 println!("{}", handle.await.unwrap()); 14 println!("available permits = {}", sem.available_permits()); 15 } ``` Real output: ```text 1 did work 2 available permits = 1 ``` * **Run `cargo clippy`** to catch held-across-`await` guards that the type checker lets slip on current-thread runtimes. * **Never hold two locks in different orders across tasks** — that is the classic lock-ordering deadlock, identical to the threaded-Rust case. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small client that fetches user records from a slow “API”, **caches** them behind an `RwLock` (many concurrent readers, occasional writers), and **throttles** outbound calls with a `Semaphore` so it never makes more than `MAX_INFLIGHT` requests at once. This is the production-flavored combination of all three primitives. ```rust 1 use std::collections::HashMap; 2 use std::sync::Arc; 3 use tokio::sync::{RwLock, Semaphore}; 4 use tokio::time::{sleep, Duration}; 5 6 /// Fetches user records, caches them, and rate-limits concurrent requests. 7 #[derive(Clone)] 8 struct UserClient { 9 cache: Arc<RwLock<HashMap<u32, String>>>, 10 limiter: Arc<Semaphore>, 11 } 12 13 const MAX_INFLIGHT: usize = 3; 14 15 impl UserClient { 16 fn new() -> Self { 17 UserClient { 18 cache: Arc::new(RwLock::new(HashMap::new())), 19 limiter: Arc::new(Semaphore::new(MAX_INFLIGHT)), 20 } 21 } 22 23 async fn fetch_remote(id: u32) -> String { 24 sleep(Duration::from_millis(20)).await; // simulate network latency 25 format!("user#{id}") 26 } 27 28 async fn get(&self, id: u32) -> String { 29 // Fast path: a read lock lets many tasks check the cache concurrently. 30 if let Some(name) = self.cache.read().await.get(&id) { 31 return name.clone(); 32 } 33 34 // Slow path: throttle concurrent network calls with the semaphore. 35 let _permit = self.limiter.acquire().await.unwrap(); 36 let name = Self::fetch_remote(id).await; 37 38 // Take the write lock only briefly to insert the result. 39 self.cache.write().await.insert(id, name.clone()); 40 name 41 } 42 } 43 44 #[tokio::main] 45 async fn main() { 46 let client = UserClient::new(); 47 48 // Ten concurrent lookups over four distinct ids. 49 let mut handles = Vec::new(); 50 for i in 0..10 { 51 let client = client.clone(); 52 let id = (i % 4) + 1; 53 handles.push(tokio::spawn(async move { client.get(id).await })); 54 } 55 56 let mut results: Vec<String> = Vec::new(); 57 for h in handles { 58 results.push(h.await.unwrap()); 59 } 60 results.sort(); 61 results.dedup(); 62 println!("distinct users fetched: {:?}", results); 63 println!("cache size: {}", client.cache.read().await.len()); 64 } ``` Real output: ```text 1 distinct users fetched: ["user#1", "user#2", "user#3", "user#4"] 2 cache size: 4 ``` Note how the locks are held across `.await` here (the read lock spans the `.get()`, the write lock spans the `.insert()`) — which is exactly why these are `tokio::sync` locks and not `std` ones. The `Semaphore` guarantees at most three `fetch_remote` calls overlap, regardless of how many of the ten tasks miss the cache. > **Note:** A subtle real-world refinement (omitted for clarity) is the “double-check after acquiring the permit”: between the cache miss and getting the permit, another task may have populated the cache. Production code often re-reads the cache after `acquire().await` to avoid duplicate fetches — an instance of the classic check-then-act race. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [Tokio `sync` module docs](https://docs.rs/tokio/latest/tokio/sync/index.html): the authoritative reference for `Mutex`, `RwLock`, `Semaphore`, and more. * [`tokio::sync::Mutex` docs](https://docs.rs/tokio/latest/tokio/sync/struct.Mutex.html): includes Tokio’s own guidance on when to prefer `std::sync::Mutex`. * [`std::sync::Mutex` docs](https://doc.rust-lang.org/std/sync/struct.Mutex.html): poisoning, `lock`, `try_lock`. * [Clippy `await_holding_lock` lint](https://rust-lang.github.io/rust-clippy/master/index.html#await_holding_lock): the lint behind Pitfall 3. * [The Tokio Tutorial: Shared State](https://tokio.rs/tokio/tutorial/shared-state): `Arc<Mutex<T>>` in context. Related pages in this guide: * [Arc + Mutex pattern](/11-async/12-arc-mutex-pattern/): how `Arc` lets multiple tasks share one lock. * [Channels](/11-async/08-channels/): “share by communicating” as an alternative to shared-state locks. * [Spawning tasks](/11-async/09-spawning-tasks/): the `tokio::spawn` and `Send` requirements that drive the across-`await` rule. * [select / join](/11-async/07-select-join/) — concurrent awaiting that often replaces manual locking. * [async vs sync](/11-async/13-async-vs-sync/): when async (and therefore async locks) is the right tool at all. * [Tokio Intro](/11-async/02-tokio-intro/) and [Tokio Setup](/11-async/03-tokio-setup/) — the runtime these primitives need. * [Ownership: reference counting](/05-ownership/07-reference-counting/): the `Arc` mechanics underlying shared locks. * [Smart Pointers section](/10-smart-pointers/): `Arc`, `Rc`, and interior mutability in depth. * Next up after async: [Modules & Packages](/12-modules-packages/). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1 [Section titled “Exercise 1”](#exercise-1) **Difficulty:** Beginner **Objective:** Use a `std::sync::Mutex` correctly inside spawned async tasks by keeping the lock out of any `.await`. **Instructions:** Create an `Arc<Mutex<u64>>` total. Spawn four tasks; each first `sleep`s (an `.await`), then adds its own number (1 through 4) to the total. Make sure the program compiles (no across-`await` hold) and prints `total = 10`. Solution ```rust 1 use std::sync::{Arc, Mutex}; 2 use tokio::time::{sleep, Duration}; 3 4 #[tokio::main] 5 async fn main() { 6 let total = Arc::new(Mutex::new(0_u64)); 7 let mut handles = Vec::new(); 8 for i in 1..=4 { 9 let total = Arc::clone(&total); 10 handles.push(tokio::spawn(async move { 11 sleep(Duration::from_millis(5)).await; // await BEFORE locking 12 let mut g = total.lock().unwrap(); // lock, no await while held 13 *g += i; // guard dropped at scope end 14 })); 15 } 16 for h in handles { 17 h.await.unwrap(); 18 } 19 println!("total = {}", *total.lock().unwrap()); 20 } ``` Real output: ```text 1 total = 10 ``` The `.await` happens *before* the lock is taken, so the `std` `MutexGuard` never lives across an await point — the future stays `Send` and `tokio::spawn` accepts it. ### Exercise 2 [Section titled “Exercise 2”](#exercise-2) **Difficulty:** Intermediate **Objective:** Use a `tokio::sync::RwLock` to coordinate concurrent writers and readers over a shared counter. **Instructions:** Create an `Arc<RwLock<u64>>` hit counter. Spawn five writer tasks that each take the write lock and increment by 1. After they all finish, spawn three reader tasks that take the read lock and return the value; assert each reads `5`. Print the final value. Solution ```rust 1 use std::sync::Arc; 2 use tokio::sync::RwLock; 3 4 #[tokio::main] 5 async fn main() { 6 let hits = Arc::new(RwLock::new(0_u64)); 7 8 // Five concurrent writers each increment once. 9 let mut writers = Vec::new(); 10 for _ in 0..5 { 11 let hits = Arc::clone(&hits); 12 writers.push(tokio::spawn(async move { 13 let mut w = hits.write().await; 14 *w += 1; 15 })); 16 } 17 for w in writers { 18 w.await.unwrap(); 19 } 20 21 // Three concurrent readers all share the read lock. 22 let mut readers = Vec::new(); 23 for _ in 0..3 { 24 let hits = Arc::clone(&hits); 25 readers.push(tokio::spawn(async move { *hits.read().await })); 26 } 27 for r in readers { 28 assert_eq!(r.await.unwrap(), 5); 29 } 30 println!("final hits = {}", *hits.read().await); 31 } ``` Real output: ```text 1 final hits = 5 ``` The writers serialize (each needs exclusive `write()` access), so all five increments land. The readers run *after* the writers and can share the read lock, all observing the final value. ### Exercise 3 [Section titled “Exercise 3”](#exercise-3) **Difficulty:** Advanced **Objective:** Use a `tokio::sync::Semaphore` to cap concurrency, and *prove* the cap holds by tracking the maximum number of simultaneously running tasks. **Instructions:** With a semaphore of limit 2, spawn six tasks. Each acquires an owned permit (`acquire_owned`), increments a shared `AtomicUsize` “current” counter, updates an `AtomicUsize` “max seen” with `fetch_max`, sleeps briefly, then decrements “current”. After all tasks finish, print the maximum concurrency observed and assert it never exceeded 2. Solution ```rust 1 use std::sync::atomic::{AtomicUsize, Ordering}; 2 use std::sync::Arc; 3 use tokio::sync::Semaphore; 4 use tokio::time::{sleep, Duration}; 5 6 #[tokio::main] 7 async fn main() { 8 const LIMIT: usize = 2; 9 let sem = Arc::new(Semaphore::new(LIMIT)); 10 let current = Arc::new(AtomicUsize::new(0)); 11 let max_seen = Arc::new(AtomicUsize::new(0)); 12 13 let mut handles = Vec::new(); 14 for _ in 0..6 { 15 let sem = Arc::clone(&sem); 16 let current = Arc::clone(¤t); 17 let max_seen = Arc::clone(&max_seen); 18 handles.push(tokio::spawn(async move { 19 let _permit = sem.acquire_owned().await.unwrap(); 20 let now = current.fetch_add(1, Ordering::SeqCst) + 1; 21 max_seen.fetch_max(now, Ordering::SeqCst); 22 sleep(Duration::from_millis(10)).await; 23 current.fetch_sub(1, Ordering::SeqCst); 24 // _permit dropped here -> a permit is returned 25 })); 26 } 27 for h in handles { 28 h.await.unwrap(); 29 } 30 println!("max concurrent = {}", max_seen.load(Ordering::SeqCst)); 31 println!( 32 "never exceeded limit: {}", 33 max_seen.load(Ordering::SeqCst) <= LIMIT 34 ); 35 } ``` Real output: ```text 1 max concurrent = 2 2 never exceeded limit: true ``` `acquire_owned` returns a permit that owns its slice of the semaphore with no borrow lifetime, so it can live inside a `'static` spawned task. The `AtomicUsize` counters (no lock needed for a single integer) record that at most two tasks ever held a permit at once. # The `Arc<Mutex<T>>` Pattern > JavaScript shares state across async work for free; Rust makes you opt in. Arc<Mutex<T>> gives several Tokio tasks one shared, compiler-checked, race-free value. In JavaScript you never think twice about sharing state between async operations — every callback closes over the same variables and they all run on one thread, so a plain object *is* your shared state. Rust will not let you do that: sharing mutable data across tasks requires you to opt in, with a combination of `Arc` (shared ownership) and `Mutex`/`RwLock` (synchronized mutation). This page is about that combination: the single most common way to hold mutable state that several Tokio tasks touch at once. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) `Arc<Mutex<T>>` is Rust’s answer to “a shared, mutable variable that more than one task can read and write.” **`Arc<T>`** (Atomically Reference-Counted) gives several owners a handle to the same heap value; **`Mutex<T>`** ensures only one of them mutates it at a time. Where JavaScript’s single-threaded event loop makes shared state “safe” by accident, Rust makes the sharing explicit and compiler-checked, so you trade a little ceremony for a guarantee that you can never have a data race. > **Note:** This page focuses on `std::sync::Mutex`/`RwLock`: the *blocking* locks you use for short, non-`await` critical sections. Tokio’s async-aware `tokio::sync::Mutex` exists for the rarer case of holding a lock across an `.await`, and is covered in [Async Synchronization Primitives](/11-async/11-sync-primitives/). `Arc` itself is a smart pointer; see [Smart Pointers](/10-smart-pointers/) for the wider family (`Box`, `Rc`, `Arc`). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In Node.js, shared mutable state between concurrent async operations is invisible plumbing. Every async function closes over the same variables, and because there is exactly one thread running your JavaScript, two callbacks can never *truly* run at the same instant. A shared counter is just a `let`: ```typescript 1 // A "shared" counter touched by many concurrent async operations. 2 let counter = 0; 3 4 async function bumpManyTimes(): Promise<void> { 5 for (let i = 0; i < 1000; i++) { 6 // Read-modify-write. On Node this is safe because no other code 7 // can run between these statements unless we `await`. 8 counter += 1; 9 } 10 } 11 12 async function main(): Promise<void> { 13 // Kick off 10 "concurrent" operations. 14 const ops = Array.from({ length: 10 }, () => bumpManyTimes()); 15 await Promise.all(ops); 16 17 // Always 10000 — there is no parallelism, so no interleaving mid-statement. 18 console.log(`final count: ${counter}`); 19 } 20 21 main(); ``` This “just works” because of two assumptions that **do not hold in Rust + Tokio**: 1. There is only one OS thread, so `counter += 1` is effectively atomic from JavaScript’s point of view. 2. Closures freely capture and mutate outer variables; the language never asks who “owns” `counter`. If you reached for `worker_threads` to get real parallelism, you would immediately discover that those assumptions break: workers do not share `let counter` at all; you would need `SharedArrayBuffer` and `Atomics`. Rust’s `Arc<Mutex<T>>` is the everyday tool that `SharedArrayBuffer` + `Atomics` only hints at. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same counter, shared across 10 Tokio tasks that genuinely may run on different threads: ```rust 1 use std::sync::{Arc, Mutex}; 2 3 #[tokio::main] 4 async fn main() { 5 // The counter starts at 0, wrapped so it can be shared and mutated. 6 let counter = Arc::new(Mutex::new(0u64)); 7 8 let mut handles = Vec::new(); 9 for _ in 0..10 { 10 // Clone the Arc: a cheap pointer copy that bumps the reference count. 11 // Each task gets its own handle to the SAME underlying Mutex<u64>. 12 let counter = Arc::clone(&counter); 13 14 let handle = tokio::spawn(async move { 15 for _ in 0..1_000 { 16 // Lock to get exclusive access. The guard unlocks on drop. 17 let mut n = counter.lock().unwrap(); 18 *n += 1; 19 } // <- guard dropped here each iteration, so other tasks can proceed 20 }); 21 handles.push(handle); 22 } 23 24 // Wait for every task to finish. 25 for handle in handles { 26 handle.await.unwrap(); 27 } 28 29 // 10 tasks * 1000 increments = 10000, every time, with no data races. 30 println!("final count: {}", *counter.lock().unwrap()); 31 } ``` Real output: ```plaintext 1 final count: 10000 ``` The result is just as deterministic as the JavaScript version — `10000` every run — but for a *stronger* reason. In Node it is deterministic because nothing ever runs in parallel. In Rust it is deterministic because the `Mutex` serializes the read-modify-write, even though the tasks really can be running on different cores at the same time. Remove the `Mutex` and the program would not compile at all, which is exactly the point: Rust refuses to let you write the racy version. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) Let us walk the pattern apart, because each layer is doing a distinct job. ### `Arc<T>`: shared ownership [Section titled “Arc\<T>: shared ownership”](#arct-shared-ownership) ```rust 1 let counter = Arc::new(Mutex::new(0u64)); ``` Rust’s ownership rule is “exactly one owner.” A spawned task needs to *own* whatever it captures (it might outlive the function that spawned it), so 10 tasks cannot all own the same `Mutex<u64>` directly. **`Arc`** breaks the tie: it is a reference-counted pointer where every clone is a co-owner of one heap allocation. The value is dropped only when the last `Arc` goes away. ```rust 1 let counter = Arc::clone(&counter); // NOT a deep copy — bumps a counter, returns a new handle ``` > **Tip:** `Arc::clone(&x)` and `x.clone()` do the same thing, but the explicit `Arc::clone(&x)` form is idiomatic here: it signals to the reader “this is a cheap refcount bump, not a deep clone of the data.” Clippy and the Rust API guidelines both endorse it for `Arc`/`Rc`. The “A” in `Arc` stands for **Atomic**: the reference count is updated with atomic CPU instructions, so cloning and dropping handles is safe across threads. Its non-atomic cousin `Rc` is faster but single-threaded only — we will see exactly how the compiler enforces that in [Common Pitfalls](#common-pitfalls). ### `Mutex<T>`: synchronized mutation [Section titled “Mutex\<T>: synchronized mutation”](#mutext-synchronized-mutation) `Arc` alone gives you *shared read-only* access. `Arc<u64>` would let all 10 tasks read the number, but none could change it, because shared references (`&T`) are immutable. To mutate shared data you need **interior mutability** plus **synchronization** — that is `Mutex`. ```rust 1 let mut n = counter.lock().unwrap(); // blocks until this task holds the lock 2 *n += 1; // `n` is a guard that derefs to the inner u64 ``` `lock()` returns a `Result<MutexGuard<T>, _>` (the `Err` case is *poisoning*, covered below). The **`MutexGuard`** is a smart pointer: deref it with `*` to reach the `u64`. Importantly, the guard releases the lock automatically when it is dropped: there is no `unlock()` to forget. This is RAII, the same mechanism that frees memory; see [Ownership](/05-ownership/). ### Why the inner scope matters [Section titled “Why the inner scope matters”](#why-the-inner-scope-matters) In the counter loop the guard is created and dropped on every iteration. That tight scope is deliberate: the lock is held for as little time as possible, so other tasks spend less time waiting. The general rule — **hold the lock for the shortest critical section you can** — matters far more in Rust than the equivalent ever did in single-threaded JavaScript, where there was no lock to hold. ### `unwrap()` on the lock [Section titled “unwrap() on the lock”](#unwrap-on-the-lock) `counter.lock().unwrap()` unwraps the `Result`. We will explain *when* this can be `Err` (poisoning) and how to handle it gracefully in [Common Pitfalls](#common-pitfalls). For now, read `.unwrap()` as “give me the guard, and panic if a previous holder panicked mid-lock.” *** ## `Arc<RwLock<T>>`: many readers, occasional writer [Section titled “Arc\<RwLock\<T>>: many readers, occasional writer”](#arcrwlockt-many-readers-occasional-writer) When the data is **read far more often than it is written**, a `Mutex` is wasteful: it forces readers to queue even though concurrent reads cannot conflict. **`RwLock`** (read-write lock) splits locking into two modes: any number of readers may hold a *shared* lock simultaneously, but a writer needs an *exclusive* lock and waits for all readers to leave. ```rust 1 use std::collections::HashMap; 2 use std::sync::{Arc, RwLock}; 3 4 #[tokio::main] 5 async fn main() { 6 // A shared read-mostly config map. Many readers, occasional writer. 7 let config: Arc<RwLock<HashMap<String, String>>> = 8 Arc::new(RwLock::new(HashMap::new())); 9 10 // One writer task seeds the map. 11 { 12 let config = Arc::clone(&config); 13 tokio::spawn(async move { 14 let mut map = config.write().unwrap(); // exclusive write lock 15 map.insert("region".to_string(), "us-east-1".to_string()); 16 map.insert("tier".to_string(), "premium".to_string()); 17 }) 18 .await 19 .unwrap(); 20 } 21 22 // Many reader tasks share the lock simultaneously. 23 let mut handles = Vec::new(); 24 for id in 0..4 { 25 let config = Arc::clone(&config); 26 handles.push(tokio::spawn(async move { 27 let map = config.read().unwrap(); // shared read lock 28 let region = map.get("region").cloned().unwrap_or_default(); 29 format!("reader {id} sees region={region}") 30 })); 31 } 32 33 for h in handles { 34 println!("{}", h.await.unwrap()); 35 } 36 } ``` Real output: ```plaintext 1 reader 0 sees region=us-east-1 2 reader 1 sees region=us-east-1 3 reader 2 sees region=us-east-1 4 reader 3 sees region=us-east-1 ``` `read()` returns a shared `RwLockReadGuard` (deref to read the map); `write()` returns an exclusive `RwLockWriteGuard` (deref-mut to modify it). The API mirrors `Mutex` almost exactly — you are just choosing which kind of access you need each time. > **Warning:** `RwLock` is not automatically faster than `Mutex`. Acquiring a read lock still does atomic bookkeeping, and a constant stream of writers can *starve* readers (or vice versa, depending on the platform’s policy). Use `RwLock` when reads genuinely dominate and the critical sections are non-trivial; otherwise a plain `Mutex` is simpler and often just as fast. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript | Rust (`Arc<Mutex<T>>`) | | ----------------------------- | ------------------------------------------------ | ------------------------------------------------- | | Sharing mutable state | A captured `let`; implicit | Explicit: wrap in `Arc<Mutex<T>>` | | Concurrency model | One thread; statements never interleave mid-line | Tasks may run on multiple threads in parallel | | Data races | Impossible by construction (single thread) | Prevented by the compiler + the lock, not by luck | | Releasing a lock | No locks to release | Automatic when the guard is dropped (RAII) | | Copying the handle | Reference assignment shares the object | `Arc::clone` bumps an atomic refcount | | Read-only vs read-write split | No distinction | `Mutex` (one writer) vs `RwLock` (many readers) | | Forgetting synchronization | Silently fine on one thread | Won’t compile across tasks | The deepest difference is **who guarantees safety**. In JavaScript, the runtime guarantees it by never running two pieces of your code at once. In Rust, the *type system* guarantees it: the `Send` and `Sync` marker traits decide what may cross a thread boundary, and `Arc<Mutex<T>>` is the building block that makes ordinary data satisfy those bounds. You are not asked to be careful — you are asked to encode your sharing in the type, after which the compiler is careful for you. > **Note:** `Send` means “safe to move to another thread”; `Sync` means “safe to share by reference between threads.” `Mutex<T>` is `Sync` (it adds the synchronization), and `Arc<T>` is `Send + Sync` when `T` is. `Rc` is neither, which is why the next section’s pitfall fails to compile. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting to clone the `Arc` (moving it instead) [Section titled “Pitfall 1: Forgetting to clone the Arc (moving it instead)”](#pitfall-1-forgetting-to-clone-the-arc-moving-it-instead) A task that captures `counter` directly *moves* it, so it is gone for the next task: ```rust 1 use std::sync::{Arc, Mutex}; 2 3 #[tokio::main] 4 async fn main() { 5 let counter = Arc::new(Mutex::new(0)); 6 7 let h1 = tokio::spawn(async move { 8 *counter.lock().unwrap() += 1; // `counter` MOVED into this task 9 }); 10 11 let h2 = tokio::spawn(async move { 12 *counter.lock().unwrap() += 1; // does not compile (error[E0382]: use of moved value) 13 }); 14 15 h1.await.unwrap(); 16 h2.await.unwrap(); 17 } ``` The real compiler error: ```text 1 error[E0382]: use of moved value: `counter` 2 --> src/main.rs:11:27 3 | 4 5 | let counter = Arc::new(Mutex::new(0)); 5 | ------- move occurs because `counter` has type `Arc<std::sync::Mutex<i32>>`, which does not implement the `Copy` trait 6 6 | 7 7 | let h1 = tokio::spawn(async move { 8 | ---------- value moved here 9 8 | *counter.lock().unwrap() += 1; // `counter` MOVED into this task 10 | ------- variable moved due to use in coroutine 11 ... 12 11 | let h2 = tokio::spawn(async move { 13 | ^^^^^^^^^^ value used here after move 14 12 | *counter.lock().unwrap() += 1; // counter already moved above 15 | ------- use occurs due to use in coroutine 16 | 17 help: consider cloning the value before moving it into the closure ``` **Fix:** create a fresh `Arc::clone(&counter)` *before* each `tokio::spawn`, exactly as the working example does. This is the single most common stumbling block for newcomers; the compiler even suggests the fix. ### Pitfall 2: Holding a `std::sync::MutexGuard` across an `.await` [Section titled “Pitfall 2: Holding a std::sync::MutexGuard across an .await”](#pitfall-2-holding-a-stdsyncmutexguard-across-an-await) This is the big one, and it is unique to async Rust. If you take a `std::sync::Mutex` lock and then `.await` while still holding the guard, the future stops being `Send` and `tokio::spawn` rejects it: ```rust 1 use std::sync::{Arc, Mutex}; 2 use std::time::Duration; 3 4 async fn bump(counter: Arc<Mutex<i32>>) { 5 let mut n = counter.lock().unwrap(); 6 *n += 1; 7 // does not compile when spawned: holding a std MutexGuard across .await 8 tokio::time::sleep(Duration::from_millis(10)).await; 9 *n += 1; 10 } 11 12 #[tokio::main] 13 async fn main() { 14 let c = Arc::new(Mutex::new(0)); 15 tokio::spawn(bump(c)).await.unwrap(); 16 } ``` The real error: ```text 1 error: future cannot be sent between threads safely 2 --> src/main.rs:15:18 3 | 4 15 | tokio::spawn(bump(c)).await.unwrap(); 5 | ^^^^^^^ future returned by `bump` is not `Send` 6 | 7 = help: within `impl Future<Output = ()>`, the trait `Send` is not implemented for `std::sync::MutexGuard<'_, i32>` 8 note: future is not `Send` as this value is used across an await 9 --> src/main.rs:8:51 10 | 11 5 | let mut n = counter.lock().unwrap(); 12 | ----- has type `std::sync::MutexGuard<'_, i32>` which is not `Send` 13 ... 14 8 | tokio::time::sleep(Duration::from_millis(10)).await; 15 | ^^^^^ await occurs here, with `mut n` maybe used later ``` **Why:** a guard pins the lock to the thread that took it, but `.await` may resume the task on a *different* worker thread. Tokio’s multi-thread scheduler refuses that. **Fix A (preferred):** release the lock *before* you await. Put the critical section in its own scope so the guard drops: ```rust 1 use std::sync::{Arc, Mutex}; 2 use std::time::Duration; 3 4 async fn bump(counter: Arc<Mutex<i32>>) { 5 // Open a small scope: compute and release the lock BEFORE awaiting. 6 { 7 let mut n = counter.lock().unwrap(); 8 *n += 1; 9 } // guard dropped here -> the future no longer holds a non-Send value 10 tokio::time::sleep(Duration::from_millis(10)).await; 11 *counter.lock().unwrap() += 1; 12 } 13 14 #[tokio::main] 15 async fn main() { 16 let c = Arc::new(Mutex::new(0)); 17 tokio::spawn(bump(Arc::clone(&c))).await.unwrap(); 18 println!("value = {}", *c.lock().unwrap()); 19 } ``` Real output: ```text 1 value = 2 ``` **Fix B (only if you must hold the lock across the await):** switch to `tokio::sync::Mutex`, whose guard *is* `Send` and which yields the task instead of blocking the thread. That is the subject of [Async Synchronization Primitives](/11-async/11-sync-primitives/). For the vast majority of code, Fix A is correct and cheaper: keep critical sections short and synchronous. ### Pitfall 3: Deadlocking yourself by locking twice [Section titled “Pitfall 3: Deadlocking yourself by locking twice”](#pitfall-3-deadlocking-yourself-by-locking-twice) `std::sync::Mutex` is **not reentrant**. If a task locks it and then tries to lock the *same* mutex again before releasing the first guard, it blocks forever waiting for itself: ```rust 1 // Pseudocode — this would HANG at runtime, so it is described, not run. 2 let guard1 = data.lock().unwrap(); 3 let guard2 = data.lock().unwrap(); // deadlock: the lock is already held by us ``` This compiles fine — the compiler cannot see it — so it is a *runtime* hang, not a compile error. The usual culprit is calling a helper that also locks while you already hold the guard. **Fix:** drop the first guard before calling code that re-locks, or refactor so only one place locks. The cache exercise at the end shows the disciplined “lock, copy out, unlock, then work” pattern that avoids this. ### Pitfall 4: Panicking with the lock held (poisoning) [Section titled “Pitfall 4: Panicking with the lock held (poisoning)”](#pitfall-4-panicking-with-the-lock-held-poisoning) If a thread panics while holding a `std::sync::Mutex`, the lock becomes **poisoned**: subsequent `lock()` calls return `Err(PoisonError)` so other threads know the protected data might be in a broken, half-updated state. Blindly `.unwrap()`-ing then turns one panic into many. ```rust 1 use std::sync::{Arc, Mutex}; 2 3 #[tokio::main] 4 async fn main() { 5 let data = Arc::new(Mutex::new(vec![1, 2, 3])); 6 7 // This task panics WHILE holding the lock -> the Mutex becomes "poisoned". 8 let d = Arc::clone(&data); 9 let _ = tokio::spawn(async move { 10 let _guard = d.lock().unwrap(); 11 panic!("boom inside critical section"); 12 }) 13 .await; 14 15 // Any later lock() returns Err(PoisonError); unwrap() then panics. 16 match data.lock() { 17 Ok(_) => println!("lock acquired cleanly"), 18 Err(poisoned) => { 19 // You can still recover the data via into_inner(). 20 let guard = poisoned.into_inner(); 21 println!("recovered from poison: {:?}", *guard); 22 } 23 } 24 } ``` Real output: ```text 1 thread 'tokio-rt-worker' panicked at src/main.rs:11:9: 2 boom inside critical section 3 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace 4 recovered from poison: [1, 2, 3] ``` Most code keeps the `.unwrap()` (a poisoned lock usually means a bug already happened and you *want* the cascade), but for resilient services you can match on the error and call `into_inner()` to recover. JavaScript has no equivalent because a single-threaded model never has a “half-updated by another thread” hazard. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Reach for `std::sync::Mutex` first, `tokio::sync::Mutex` only when you must hold a lock across `.await`.** The std lock is faster and the borrow checker will tell you (Pitfall 2) the moment you actually need the async one. * **Keep critical sections tiny.** Lock, do the minimum read/modify/write, drop the guard. Compute expensive things and do I/O *outside* the lock. * **Use `Arc::clone(&x)` explicitly** rather than `x.clone()` for `Arc`, so readers see it is a refcount bump, not a deep copy. * **Prefer `RwLock` only for genuinely read-heavy data**; otherwise `Mutex` is simpler and avoids reader/writer starvation surprises. * **Wrap the pattern in a domain type.** Instead of passing `Arc<Mutex<HashMap<K, V>>>` around, define a `struct Store { inner: Arc<Mutex<...>> }`, derive `Clone`, and expose intention-revealing methods (`get`, `insert`). This localizes the locking discipline and keeps call sites clean; the real-world example below does exactly this. * **Consider atomics for single numbers.** A bare counter is better served by `Arc<AtomicU64>` (`std::sync::atomic`) than `Arc<Mutex<u64>>`: no locking at all. Use `Mutex`/`RwLock` when you must protect a *compound* invariant across several fields. * **Let the guard’s `Drop` release the lock.** There is no manual `unlock`; if you want to release early, call `drop(guard)` or use a `{ }` scope. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small in-memory metrics registry — the kind a web service keeps to count requests per route. Many request-handling tasks increment counters concurrently; a background task or `/metrics` endpoint reads snapshots. It is read-and-write heavy with short critical sections, and it wraps the locking inside a tidy `Metrics` type that is cheap to `Clone` (it only clones the inner `Arc`). ```rust 1 use std::collections::HashMap; 2 use std::sync::{Arc, RwLock}; 3 use std::time::Duration; 4 use tokio::time::sleep; 5 6 /// A small in-memory metrics registry shared across worker tasks. 7 /// Reads (snapshots) are frequent and cheap; writes (increments) are short. 8 #[derive(Clone)] 9 struct Metrics { 10 // Arc makes the handle cloneable & shareable; RwLock guards the map. 11 counters: Arc<RwLock<HashMap<String, u64>>>, 12 } 13 14 impl Metrics { 15 fn new() -> Self { 16 Self { 17 counters: Arc::new(RwLock::new(HashMap::new())), 18 } 19 } 20 21 /// Increment a named counter. Takes a brief write lock. 22 fn incr(&self, name: &str, by: u64) { 23 let mut map = self.counters.write().expect("metrics lock poisoned"); 24 *map.entry(name.to_string()).or_insert(0) += by; 25 } 26 27 /// Take a read-only snapshot. Multiple readers can do this at once. 28 fn snapshot(&self) -> HashMap<String, u64> { 29 self.counters.read().expect("metrics lock poisoned").clone() 30 } 31 } 32 33 async fn handle_request(metrics: Metrics, route: &'static str) { 34 sleep(Duration::from_millis(5)).await; // simulate I/O 35 metrics.incr("requests_total", 1); 36 metrics.incr(route, 1); 37 } 38 39 #[tokio::main] 40 async fn main() { 41 // `Metrics` is Clone (just clones the inner Arc), so each task gets a handle. 42 let metrics = Metrics::new(); 43 let routes = ["/login", "/login", "/checkout", "/login", "/checkout"]; 44 45 let mut handles = Vec::new(); 46 for route in routes { 47 let metrics = metrics.clone(); 48 handles.push(tokio::spawn(handle_request(metrics, route))); 49 } 50 51 for h in handles { 52 h.await.unwrap(); 53 } 54 55 // Stable iteration order for deterministic output. 56 let snap = metrics.snapshot(); 57 let mut pairs: Vec<_> = snap.into_iter().collect(); 58 pairs.sort(); 59 for (name, count) in pairs { 60 println!("{name} = {count}"); 61 } 62 } ``` Real output: ```text 1 /checkout = 2 2 /login = 3 3 requests_total = 5 ``` Two things make this idiomatic. First, the `Metrics` wrapper hides `Arc<RwLock<...>>` so callers just see `metrics.incr(...)` and `metrics.snapshot()`: the locking discipline lives in one place. Second, every critical section is synchronous and short (`incr` holds the write lock just long enough to bump one entry; `snapshot` clones the map under a read lock and lets readers go), so no lock is ever held across the `.await` in `handle_request`. This is the shape you will reuse for shared caches, connection pools, in-memory session stores, and rate limiters. > **Tip:** In a real Axum/Tokio service you would store this `Metrics` in the application state and clone it into each handler, the same `Arc`-clone-per-task pattern, just supplied by the framework. See [Web APIs](/16-web-apis/) for shared application state. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`std::sync::Arc` — official docs](https://doc.rust-lang.org/std/sync/struct.Arc.html) * [`std::sync::Mutex` — official docs](https://doc.rust-lang.org/std/sync/struct.Mutex.html) * [`std::sync::RwLock` — official docs](https://doc.rust-lang.org/std/sync/struct.RwLock.html) * [The Rust Book, Ch. 16.3 — Shared-State Concurrency](https://doc.rust-lang.org/book/ch16-03-shared-state.html) * [Tokio tutorial — Shared state](https://tokio.rs/tokio/tutorial/shared-state) * Related in this guide: * [Async Synchronization Primitives](/11-async/11-sync-primitives/): `tokio::sync::Mutex`/`RwLock`/`Semaphore`, and when async-aware locks are required * [Spawning Tasks](/11-async/09-spawning-tasks/) — `tokio::spawn`, `JoinHandle`, and the `Send + 'static` bound that drives this pattern * [Async Channels](/11-async/08-channels/): message passing, the *other* way to coordinate tasks (often preferable to shared state) * [Promises vs Futures](/11-async/00-promises-vs-futures/) — why Rust futures are lazy and need a runtime at all * [Ownership](/05-ownership/) — ownership, borrowing, and RAII (the foundation of guards) * [Smart Pointers](/10-smart-pointers/): `Box`, `Rc`, `Arc`, and interior mutability * [Modules & Packages](/12-modules-packages/) — organizing the types you build around shared state *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A shared running total [Section titled “Exercise 1: A shared running total”](#exercise-1-a-shared-running-total) **Difficulty:** Beginner **Objective:** Get comfortable with the `Arc::clone`-per-task ritual and a `Mutex`-guarded number. **Instructions:** Spawn 5 tasks, numbered `0..5`. Each task should add *its own id* to a shared `Arc<Mutex<u64>>`, 100 times. After all tasks finish, print the total. (With ids 0..4 each added 100 times, the total should be `1000`.) ```rust 1 use std::sync::{Arc, Mutex}; 2 3 #[tokio::main] 4 async fn main() { 5 let total = Arc::new(Mutex::new(0u64)); 6 // TODO: spawn 5 tasks, each adds its id 100 times, then print the total. 7 } ``` Solution ```rust 1 use std::sync::{Arc, Mutex}; 2 3 #[tokio::main] 4 async fn main() { 5 let total = Arc::new(Mutex::new(0u64)); 6 let mut handles = Vec::new(); 7 8 for worker in 0..5u64 { 9 let total = Arc::clone(&total); 10 handles.push(tokio::spawn(async move { 11 // Each worker adds its own id, 100 times. 12 for _ in 0..100 { 13 *total.lock().unwrap() += worker; 14 } 15 })); 16 } 17 18 for h in handles { 19 h.await.unwrap(); 20 } 21 22 // (0+1+2+3+4) * 100 = 1000 23 println!("total = {}", *total.lock().unwrap()); 24 } ``` Output: ```text 1 total = 1000 ``` The key habit: a fresh `Arc::clone(&total)` *before* each `tokio::spawn`, so each task owns its own handle to the one shared `Mutex`. ### Exercise 2: Readers and a writer with `RwLock` [Section titled “Exercise 2: Readers and a writer with RwLock”](#exercise-2-readers-and-a-writer-with-rwlock) **Difficulty:** Intermediate **Objective:** Use `Arc<RwLock<Vec<String>>>` with one writer task and several reader tasks, and observe that the final state is deterministic even though the readers’ mid-flight observations are not. **Instructions:** Create an `Arc<RwLock<Vec<String>>>`. Spawn one writer task that pushes `"event-1"`, `"event-2"`, `"event-3"` with a short `sleep` between each. Spawn 3 reader tasks that each sleep briefly, then read the current length. After everything finishes, print the final vector (which must be all three events). ```rust 1 use std::sync::{Arc, RwLock}; 2 use std::time::Duration; 3 use tokio::time::sleep; 4 5 #[tokio::main] 6 async fn main() { 7 let log: Arc<RwLock<Vec<String>>> = Arc::new(RwLock::new(Vec::new())); 8 // TODO: one writer task (write lock), three reader tasks (read lock), 9 // then print the final log. 10 } ``` Solution ```rust 1 use std::sync::{Arc, RwLock}; 2 use std::time::Duration; 3 use tokio::time::sleep; 4 5 #[tokio::main] 6 async fn main() { 7 let log: Arc<RwLock<Vec<String>>> = Arc::new(RwLock::new(Vec::new())); 8 9 // Writer task: appends entries over time. 10 let writer = { 11 let log = Arc::clone(&log); 12 tokio::spawn(async move { 13 for i in 1..=3 { 14 sleep(Duration::from_millis(10)).await; 15 log.write().unwrap().push(format!("event-{i}")); 16 } 17 }) 18 }; 19 20 // Reader tasks: each reports how many entries it currently sees. 21 // (The exact counts depend on timing and will vary between runs.) 22 let mut readers = Vec::new(); 23 for id in 0..3 { 24 let log = Arc::clone(&log); 25 readers.push(tokio::spawn(async move { 26 sleep(Duration::from_millis(15)).await; 27 let len = log.read().unwrap().len(); 28 (id, len) 29 })); 30 } 31 32 writer.await.unwrap(); 33 for r in readers { 34 let (id, len) = r.await.unwrap(); 35 println!("reader {id} saw {len} entries (varies by run)"); 36 } 37 // This line is deterministic: all writes have completed. 38 println!("final log: {:?}", *log.read().unwrap()); 39 } ``` The reader lines depend on timing and differ between runs, but the last line is always: ```text 1 final log: ["event-1", "event-2", "event-3"] ``` Note how `write()` takes the exclusive lock and `read()` takes the shared one, and that the writer holding the write lock briefly blocks readers, which is exactly the synchronization you want. ### Exercise 3: A concurrent memoization cache [Section titled “Exercise 3: A concurrent memoization cache”](#exercise-3-a-concurrent-memoization-cache) **Difficulty:** Advanced **Objective:** Build a thread-safe cache wrapped in a clean type, holding the lock for the shortest possible time and computing *outside* the lock (the discipline that avoids Pitfall 3). **Instructions:** Define a `Cache` struct around `Arc<Mutex<HashMap<u64, u64>>>` that derives `Clone` and `Default`. Give it a method `get_or_compute(&self, key: u64) -> u64` that returns the cached value if present, otherwise computes `key * key`, stores it, and returns it. **Compute the value with the lock released**, then re-lock to insert using `entry(..).or_insert(..)` so a racing task’s value is kept. Spawn 6 tasks requesting the overlapping keys `[2, 3, 2, 4, 3, 2]`, collect `(key, value)` results, and print the de-duplicated results plus the final cache size (which should be `3`). ```rust 1 use std::collections::HashMap; 2 use std::sync::{Arc, Mutex}; 3 4 #[derive(Clone, Default)] 5 struct Cache { 6 inner: Arc<Mutex<HashMap<u64, u64>>>, 7 } 8 9 impl Cache { 10 fn get_or_compute(&self, key: u64) -> u64 { 11 // TODO: fast-path lock-check, compute outside the lock, 12 // then re-lock to insert with entry().or_insert(). 13 todo!() 14 } 15 } 16 17 #[tokio::main] 18 async fn main() { 19 let cache = Cache::default(); 20 // TODO: spawn 6 tasks for keys [2, 3, 2, 4, 3, 2], collect & print results. 21 } ``` Solution ```rust 1 use std::collections::HashMap; 2 use std::sync::{Arc, Mutex}; 3 4 #[derive(Clone, Default)] 5 struct Cache { 6 inner: Arc<Mutex<HashMap<u64, u64>>>, 7 } 8 9 impl Cache { 10 /// Return the cached value, or compute it, store it, and return it. 11 /// Note: the lock is released BEFORE the (pretend-expensive) compute, 12 /// so other tasks are not blocked while we work. 13 fn get_or_compute(&self, key: u64) -> u64 { 14 // 1. Fast path: take the lock, check, release immediately. 15 if let Some(v) = self.inner.lock().unwrap().get(&key) { 16 return *v; 17 } 18 // 2. Compute outside the lock. 19 let value = key * key; 20 // 3. Re-lock to insert. Another task may have inserted meanwhile; 21 // entry().or_insert keeps the first writer's value. 22 *self.inner.lock().unwrap().entry(key).or_insert(value) 23 } 24 } 25 26 #[tokio::main] 27 async fn main() { 28 let cache = Cache::default(); 29 let mut handles = Vec::new(); 30 31 // 6 tasks request overlapping keys concurrently. 32 for key in [2u64, 3, 2, 4, 3, 2] { 33 let cache = cache.clone(); 34 handles.push(tokio::spawn(async move { (key, cache.get_or_compute(key)) })); 35 } 36 37 let mut results: Vec<_> = Vec::new(); 38 for h in handles { 39 results.push(h.await.unwrap()); 40 } 41 results.sort(); 42 results.dedup(); 43 println!("{:?}", results); 44 println!("cache size = {}", cache.inner.lock().unwrap().len()); 45 } ``` Output: ```text 1 [(2, 4), (3, 9), (4, 16)] 2 cache size = 3 ``` The pattern “lock → check → unlock → compute → lock → insert” keeps each critical section tiny and never holds the lock during the (here trivial, but in real life expensive) computation. Because two tasks could compute the same key concurrently, `entry(key).or_insert(value)` makes the insert idempotent: the first writer wins and both tasks return a consistent value. > **Note:** In production you would reach for a purpose-built concurrent map like the `dashcache`/`dashmap` family or `moka` before hand-rolling this; the exercise is about understanding the mechanics underneath them. # Async vs Sync: Choosing the Right Concurrency Model > Node makes everything async; Rust lets you choose. Match the workload: async Tokio tasks for I/O, threads or rayon for CPU, plain sync when nothing overlaps. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In Node.js you rarely choose: almost everything is `async`, because the single-threaded event loop punishes any code that blocks it. Rust gives you a genuine menu: **async tasks** for I/O-bound concurrency, **OS threads** (or [`rayon`](https://docs.rs/rayon)) for CPU-bound parallelism, and **plain synchronous code** when there is nothing to overlap. This page is about making that choice deliberately, the I/O-bound-versus-CPU-bound distinction that drives it, and the “function coloring” problem that `async` introduces in both languages. > **Note:** This page assumes you have met Rust’s lazy futures and the Tokio runtime. If not, read [Promises vs Futures](/11-async/00-promises-vs-futures/) and [The Tokio Runtime](/11-async/02-tokio-intro/) first. The mechanics of `tokio::spawn`, `spawn_blocking`, and OS threads live in [Spawning Tasks](/11-async/09-spawning-tasks/); this page is about *when* to reach for each. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) A typical Node.js service mixes two kinds of work: waiting on the network or disk (**I/O-bound**) and crunching numbers (**CPU-bound**). The event loop handles the first beautifully and the second terribly: ```typescript 1 import { createHash } from "node:crypto"; 2 3 // I/O-bound: mostly waiting. async/await + the event loop excels here. 4 async function fetchUser(id: number): Promise<{ id: number; name: string }> { 5 const res = await fetch(`https://api.example.com/users/${id}`); 6 return res.json(); 7 } 8 9 // I/O-bound work overlaps perfectly: three "requests" take as long as one. 10 async function loadUsers(): Promise<unknown[]> { 11 return Promise.all([fetchUser(1), fetchUser(2), fetchUser(3)]); 12 } 13 14 // CPU-bound: a synchronous hash loop. This BLOCKS the single event-loop thread. 15 function hashPasswords(passwords: string[]): string[] { 16 // While this runs, NO other callback, timer, or awaited promise can proceed. 17 return passwords.map((p) => { 18 let h = createHash("sha256"); 19 for (let i = 0; i < 200_000; i++) h.update(p); // deliberately heavy 20 return h.digest("hex"); 21 }); 22 } ``` The hidden trap: because Node runs your JavaScript on one thread, `hashPasswords` freezes the entire process: every pending request, timer, and `await` stalls until it returns. We can demonstrate the freeze precisely with a busy loop and a timer that should fire at 50 ms: coloring.mjs ```javascript 1 const start = Date.now(); 2 setTimeout(() => { 3 console.log(`timer fired at ${Date.now() - start} ms (wanted 50)`); 4 }, 50); 5 6 // Busy-loop the single thread for ~300 ms. 7 const spinUntil = start + 300; 8 while (Date.now() < spinUntil) { 9 /* burn CPU */ 10 } 11 console.log(`busy loop done at ${Date.now() - start} ms`); ``` Running it under Node v22: ```plaintext 1 busy loop done at 309 ms 2 timer fired at 316 ms (wanted 50) ``` The timer was due at 50 ms but did not fire until 316 ms; the CPU loop held the thread hostage. Node’s only escape hatch for CPU work is `worker_threads`, a separate, heavier mechanism with message-passing serialization. Rust faces the *same* physics but hands you cleaner, first-class tools for both halves of the problem. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust makes you pick the tool that matches the workload. For **I/O-bound** work, async tasks on a runtime overlap waits exactly like the event loop: three 100 ms “requests” finish in about 100 ms total. This example uses two crates, the `tokio` runtime and `futures` (for `join_all`), so add them first with `cargo add tokio --features full` and `cargo add futures`: ```rust 1 use std::time::{Duration, Instant}; 2 use tokio::time::sleep; 3 4 /// I/O-bound: mostly waiting. async + a runtime is the right tool. 5 async fn fetch(url: &str) -> usize { 6 sleep(Duration::from_millis(100)).await; // stands in for a network round-trip 7 url.len() 8 } 9 10 #[tokio::main] 11 async fn main() { 12 let urls = ["https://a.example", "https://b.example", "https://c.example"]; 13 let start = Instant::now(); 14 15 // Run all three "requests" concurrently. They overlap because each .await 16 // yields the worker while it waits — so total time ~= one request, not three. 17 let results = futures::future::join_all(urls.iter().map(|u| fetch(u))).await; 18 19 println!("results = {results:?}"); 20 println!("elapsed = {} ms", start.elapsed().as_millis()); 21 } ``` Real output: ```plaintext 1 results = [17, 17, 17] 2 elapsed = 101 ms ``` For **CPU-bound** work, async does *nothing*: there is no waiting to overlap, only computation to spread across cores. That is a job for threads. The data-parallel crate [`rayon`](https://docs.rs/rayon) turns a sequential iterator into a parallel one with a one-word change, and on a multi-core machine the speedup is real: ```rust 1 use std::time::Instant; 2 use rayon::prelude::*; 3 4 /// CPU-bound: a deliberately heavy, purely synchronous computation. 5 fn heavy(seed: u64) -> u64 { 6 let mut acc = seed; 7 for _ in 0..50_000_000u64 { 8 acc = acc.wrapping_mul(6364136223846793005).wrapping_add(1442695040888963407); 9 } 10 acc 11 } 12 13 fn main() { 14 let inputs: Vec<u64> = (0..8).collect(); 15 16 // Sequential baseline. 17 let start = Instant::now(); 18 let seq: Vec<u64> = inputs.iter().map(|&s| heavy(s)).collect(); 19 println!("sequential: {} ms", start.elapsed().as_millis()); 20 21 // Rayon: a parallel iterator spreads the work across CPU cores. 22 let start = Instant::now(); 23 let par: Vec<u64> = inputs.par_iter().map(|&s| heavy(s)).collect(); 24 println!("rayon par: {} ms", start.elapsed().as_millis()); 25 26 assert_eq!(seq, par); 27 println!("results match: {}", seq == par); 28 } ``` Real output (on an 8-core machine, `--release`): ```plaintext 1 sequential: 830 ms 2 rayon par: 83 ms 3 results match: true ``` That is roughly a 10× speedup, and notice there is no `async`, no `.await`, and no Tokio anywhere. CPU-bound work wants cores, not an event loop. The art is knowing which world you are in. > **Tip:** `rayon` needs no runtime and no `Cargo.toml` features beyond `rayon = "1"`. It manages its own thread pool sized to your CPU. Tokio is for *concurrency over I/O*; rayon is for *parallelism over data*. They compose; see the Real-World Example. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Two axes: concurrency vs parallelism, I/O-bound vs CPU-bound [Section titled “Two axes: concurrency vs parallelism, I/O-bound vs CPU-bound”](#two-axes-concurrency-vs-parallelism-io-bound-vs-cpu-bound) Two independent distinctions drive every decision here. **Concurrency vs parallelism.** *Concurrency* is dealing with many things at once by interleaving them (one cook juggling several pans). *Parallelism* is doing many things at literally the same instant (several cooks). Async gives you concurrency cheaply; whether it also gives you parallelism depends on the runtime’s scheduler (the multi-thread vs current-thread choice in [The Tokio Runtime](/11-async/02-tokio-intro/)). JavaScript gives you concurrency but *never* parallelism for your own JS code: one thread, always. The deeper treatment is in [Concurrency vs Parallelism](/11-async/10-concurrency/); here we care only about its consequence for *choosing a tool*. **I/O-bound vs CPU-bound.** This is the question to ask first about any task: * **I/O-bound**: the task spends most of its time *waiting*, on a socket, a disk, a database, a timer. The CPU is idle during the wait. Overlapping the waits is the whole win. * **CPU-bound**: the task spends most of its time *computing*: hashing, parsing, compressing, rendering, number-crunching. There is nothing to overlap; you only win by using more cores. Async is built to overlap waits. It does not — cannot — make computation faster. Pointing async at a CPU-bound problem is like hiring a faster waiter to cook the food. ### Why async wins for I/O and loses for CPU [Section titled “Why async wins for I/O and loses for CPU”](#why-async-wins-for-io-and-loses-for-cpu) When an async task hits `.await` on something that is not ready (a socket with no data yet), it *yields* the worker thread back to the runtime, which runs other tasks meanwhile. Thousands of mostly-idle connections can therefore share a handful of threads. That is exactly the I/O-bound sweet spot. A CPU-bound loop never hits an `.await`; it just computes. So it never yields. On the multi-thread runtime it merely pins one worker (wasting the runtime’s lightweight scheduling); on the single-thread runtime it freezes everything, just like Node. The yield points that make async efficient simply do not exist in a tight compute loop. ### The runtime starvation trap (the Rust mirror of blocking the event loop) [Section titled “The runtime starvation trap (the Rust mirror of blocking the event loop)”](#the-runtime-starvation-trap-the-rust-mirror-of-blocking-the-event-loop) This is the single most important practical consequence. A blocking or CPU-heavy synchronous call inside an async task starves its sibling tasks, because cooperative scheduling only hands off control at `.await`. On a single-thread runtime it is dramatic and deterministic: ```rust 1 use std::time::Duration; 2 use tokio::time::{sleep, Instant}; 3 4 // A blocking wait that NEVER yields the async worker: it sleeps the OS thread. 5 // (A long CPU loop would behave the same way — neither hits an .await.) 6 fn blocking_work() { 7 std::thread::sleep(Duration::from_millis(300)); 8 } 9 10 // Single-thread runtime so the starvation is deterministic and easy to see. 11 #[tokio::main(flavor = "current_thread")] 12 async fn main() { 13 let start = Instant::now(); 14 15 // A "heartbeat" task that SHOULD tick every 50 ms. 16 let heartbeat = tokio::spawn(async move { 17 for n in 1..=3 { 18 sleep(Duration::from_millis(50)).await; 19 println!("heartbeat {n} at {} ms", start.elapsed().as_millis()); 20 } 21 }); 22 23 // This blocking call hogs the single worker thread for 300 ms. The heartbeat 24 // cannot run until this returns — its timers all fire late, bunched up. 25 blocking_work(); 26 println!("blocking work done at {} ms", start.elapsed().as_millis()); 27 28 heartbeat.await.unwrap(); 29 } ``` Real output: ```plaintext 1 blocking work done at 305 ms 2 heartbeat 1 at 356 ms 3 heartbeat 2 at 409 ms 4 heartbeat 3 at 461 ms ``` The heartbeat was supposed to tick at 50, 100, and 150 ms. Instead it does not fire at all until 356 ms, fully blocked until the 300 ms call returns, then it catches up. This is byte-for-byte the same failure as the Node busy-loop above; cooperative scheduling has the same Achilles’ heel everywhere. The fix is to move the blocking work off the async workers with `tokio::task::spawn_blocking`, which runs it on a dedicated blocking-thread pool: ```rust 1 use std::time::Duration; 2 use tokio::time::{sleep, Instant}; 3 4 fn blocking_work() { 5 std::thread::sleep(Duration::from_millis(300)); 6 } 7 8 #[tokio::main(flavor = "current_thread")] 9 async fn main() { 10 let start = Instant::now(); 11 12 let heartbeat = tokio::spawn(async move { 13 for n in 1..=3 { 14 sleep(Duration::from_millis(50)).await; 15 println!("heartbeat {n} at {} ms", start.elapsed().as_millis()); 16 } 17 }); 18 19 // spawn_blocking moves the blocking call to a dedicated thread pool, so the 20 // async worker stays free and the heartbeat ticks on time. 21 let work = tokio::task::spawn_blocking(blocking_work); 22 23 work.await.unwrap(); 24 println!("blocking work done at {} ms", start.elapsed().as_millis()); 25 26 heartbeat.await.unwrap(); 27 } ``` Real output: ```plaintext 1 heartbeat 1 at 54 ms 2 heartbeat 2 at 108 ms 3 heartbeat 3 at 161 ms 4 blocking work done at 302 ms ``` Now the heartbeat ticks on time (54 / 108 / 161 ms) while the blocking work runs concurrently on its own thread. `spawn_blocking` is the moral equivalent of Node’s `worker_threads`, but far lighter to use. The full mechanics are in [Spawning Tasks](/11-async/09-spawning-tasks/). ### When you do not need async at all [Section titled “When you do not need async at all”](#when-you-do-not-need-async-at-all) A point that surprises Node developers: lots of excellent Rust programs use *no* async whatsoever. A CLI that reads a file, transforms it, and writes it out has nothing to overlap: synchronous `std::fs` is simpler, faster to compile, and easier to reason about. A CPU-bound batch job wants threads, not a runtime. Reaching for `#[tokio::main]` reflexively (because that is what Node trained you to do) often adds a dependency and a layer of complexity you will never use. For CPU-bound parallelism with no I/O, plain OS threads need no runtime at all: ```rust 1 use std::thread; 2 use std::time::Instant; 3 4 /// CPU-bound work: count primes below n with a naive trial-division loop. 5 fn count_primes(n: u64) -> u64 { 6 (2..n).filter(|&x| (2..x).all(|d| x % d != 0)).count() as u64 7 } 8 9 fn main() { 10 let ranges = [50_000u64, 50_000, 50_000, 50_000]; 11 let start = Instant::now(); 12 13 // Plain OS threads: no async, no runtime. Each thread runs on its own core. 14 let handles: Vec<_> = ranges 15 .into_iter() 16 .map(|n| thread::spawn(move || count_primes(n))) 17 .collect(); 18 19 let total: u64 = handles.into_iter().map(|h| h.join().unwrap()).sum(); 20 21 println!("total primes = {total}"); 22 println!("elapsed = {} ms", start.elapsed().as_millis()); 23 } ``` Real output (`--release`): ```plaintext 1 total primes = 20532 2 elapsed = 682 ms ``` No `async`, no Tokio, no `.await`, just threads doing CPU work in parallel. For real data-parallel pipelines, prefer `rayon` (it handles work-stealing and pool sizing for you); use raw `std::thread` for a handful of long-lived, distinct jobs. ### Function coloring: the cost async imposes [Section titled “Function coloring: the cost async imposes”](#function-coloring-the-cost-async-imposes) There is a famous essay, *“What Color is Your Function?”*, describing how `async` splits a language’s functions into two **colors**: async functions and sync functions. The rules are asymmetric and infectious: 1. An async function can call a sync function freely. 2. A sync function *cannot* simply call an async function and get its value; it must drive the future through a runtime. 3. Calling an async function gives you a future; you must `.await` it (only legal inside another async function), so async-ness propagates up the call stack. JavaScript has exactly this problem: `await` is only legal inside `async function`, so one `await` deep in your code tends to turn every caller `async`. Rust has it too, but with a sharper edge: the boundary is enforced by the type system, and a bare future does nothing until polled. In Rust, calling `.await` outside an async context is a hard compile error: ```rust 1 async fn fetch_count() -> u32 { 2 42 3 } 4 5 // A plain synchronous function trying to call an async one. 6 fn summarize() -> u32 { 7 // does not compile (error[E0728]): `.await` is only allowed inside 8 // async fn / async block. 9 let count = fetch_count().await; 10 count * 2 11 } 12 13 fn main() { 14 println!("{}", summarize()); 15 } ``` Real compiler output: ```plaintext 1 error[E0728]: `await` is only allowed inside `async` functions and blocks 2 --> src/main.rs:8:31 3 | 4 6 | fn summarize() -> u32 { 5 | --------------------- this is not `async` 6 7 | // does not compile (error[E0728]): `.await` is only allowed inside 7 8 | let count = fetch_count().await; 8 | ^^^^^ only allowed inside `async` functions and blocks ``` The error names the cure: make `summarize` async too (and the coloring spreads), or bridge into the async world explicitly. Bridging from a synchronous function uses a runtime’s `block_on`, which runs a future to completion on the current thread and returns its value: ```rust 1 use std::time::Duration; 2 use tokio::runtime::Runtime; 3 use tokio::time::sleep; 4 5 async fn fetch_count() -> u32 { 6 sleep(Duration::from_millis(10)).await; 7 42 8 } 9 10 // A plain synchronous main — no #[tokio::main]. We build a runtime by hand and 11 // use block_on as the bridge from the sync world into the async world. 12 fn main() { 13 let rt = Runtime::new().expect("failed to build runtime"); 14 15 // block_on runs the future to completion on this thread and returns its value. 16 let count = rt.block_on(fetch_count()); 17 18 println!("count = {count}"); 19 } ``` Real output: ```plaintext 1 count = 42 ``` `#[tokio::main]` is just sugar that builds a runtime and calls `block_on(main())` for you. Knowing the desugaring matters when you must call async code from a context you do not control — a `Drop` impl, a synchronous trait method, an FFI callback — where `block_on` is your bridge. > **Warning:** Never call `block_on` (or any blocking call) from *inside* an async task; it blocks the worker and can deadlock the runtime. `block_on` is for crossing *into* async from genuinely synchronous code, not for nesting. If you are already async and just need to wait, use `.await`. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Question | JavaScript / Node.js | Rust | | ----------------------- | --------------------------------------------- | ------------------------------------------------------------------ | | Default model | Async everything (one event loop) | You choose: sync, threads, or async | | I/O-bound concurrency | `async`/`await` on the event loop | async tasks on a runtime (Tokio) | | CPU-bound parallelism | `worker_threads` (heavy, serialized messages) | OS threads / `rayon` (shared memory, cheap) | | “No concurrency needed” | Still usually async out of habit | Plain synchronous code; no runtime | | Blocking the worker | Freezes the whole event loop | Freezes the runtime’s worker(s); use `spawn_blocking` | | Offloading CPU work | `worker_threads` | `tokio::task::spawn_blocking`, threads, or `rayon` | | Function coloring | Yes (`await` only in `async`) | Yes, type-enforced; futures are lazy | | Sync→async bridge | Top-level `await` / an async IIFE | `Runtime::block_on` / `#[tokio::main]` | | Cost of choosing wrong | Event-loop stalls; jank | Same stall, plus you may have pulled in a runtime you never needed | The mental shift for a TypeScript developer is this: **async is not the default in Rust, it is a tool for I/O concurrency.** In Node you make everything async because the platform gives you no real alternative. In Rust, slapping `async` on a CPU-bound or do-one-thing program is often a mistake: it adds a runtime and the `Send + 'static` constraints of [Spawning Tasks](/11-async/09-spawning-tasks/) without buying you anything. > **Note:** A handy decision rule. *Are you mostly waiting on many things at once?* → async (Tokio). *Are you mostly computing, and want more cores?* → threads / `rayon`. *Just doing one thing, or computing in sequence?* → plain synchronous code. *A bit of blocking inside an otherwise-async program?* → `spawn_blocking`. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Using async for CPU-bound work and expecting a speedup [Section titled “Pitfall 1: Using async for CPU-bound work and expecting a speedup”](#pitfall-1-using-async-for-cpu-bound-work-and-expecting-a-speedup) The most common reflex from Node: wrapping a heavy computation in `async fn` and `tokio::spawn`, expecting it to “run in the background faster.” It does not. Async adds yield points for *waiting*; a compute loop has none, so it just pins a worker. Worse, on a single-thread runtime it starves everything (shown above). Async never makes computation faster; only more cores do. **Fix:** for CPU-bound work use `rayon` (data parallelism) or `std::thread` / `spawn_blocking` (to offload from the async workers). Reserve async for I/O. ### Pitfall 2: Calling a blocking API inside an async task [Section titled “Pitfall 2: Calling a blocking API inside an async task”](#pitfall-2-calling-a-blocking-api-inside-an-async-task) This compiles and runs, so the compiler will not save you, which makes it especially dangerous: ```rust 1 // Anti-pattern (compiles, but misbehaves): 2 // std::thread::sleep, std::fs, reqwest::blocking, a synchronous DB driver, or a 3 // long CPU loop inside an async task all block the worker thread — no yield. 4 tokio::spawn(async { 5 std::thread::sleep(std::time::Duration::from_secs(5)); // blocks the worker! 6 // Every other task on this worker stalls for 5 seconds. 7 }); ``` **Fix:** use the async-aware equivalent (`tokio::time::sleep(...).await`, `tokio::fs`, an async DB driver like `sqlx`), or offload the genuinely-blocking call with `tokio::task::spawn_blocking`. The earlier heartbeat experiment shows both the failure and the fix. Tokio can detect *some* long stalls and log a warning, but it cannot fix them for you. ### Pitfall 3: Calling `block_on` from inside the runtime [Section titled “Pitfall 3: Calling block\_on from inside the runtime”](#pitfall-3-calling-block_on-from-inside-the-runtime) Bridging is one-directional. `block_on` enters the async world from sync code; calling it while you are *already* on a runtime thread blocks that worker and can panic or deadlock: ```rust 1 // Anti-pattern: block_on inside an async context. 2 #[tokio::main] 3 async fn main() { 4 let rt = tokio::runtime::Handle::current(); 5 // Calling block_on on the current runtime from within it panics: 6 // "Cannot start a runtime from within a runtime." 7 rt.block_on(async { 1 + 1 }); // panics at runtime 8 } ``` Running it produces a real panic (`Cannot start a runtime from within a runtime. This happens because a function (like 'block_on') attempted to block the current thread while the thread is being used to drive asynchronous tasks.`). **Fix:** if you are already async, just `.await`. Use `block_on` only from genuinely synchronous entry points. ### Pitfall 4: Adding `#[tokio::main]` to a program with no I/O concurrency [Section titled “Pitfall 4: Adding #\[tokio::main\] to a program with no I/O concurrency”](#pitfall-4-adding-tokiomain-to-a-program-with-no-io-concurrency) A CLI that processes one file, or a batch job that crunches numbers, gains nothing from a runtime, but pays for it in a dependency, slower compiles, and the `Send + 'static` rules that async-ness forces on spawned work. New Rustaceans coming from Node often async-ify everything by habit. **Fix:** start synchronous. Add Tokio only when you have *concurrent I/O* to overlap. For CPU parallelism, reach for `rayon`, which needs no runtime at all. ### Pitfall 5: Forgetting `.await` and getting a `Future` instead of a value [Section titled “Pitfall 5: Forgetting .await and getting a Future instead of a value”](#pitfall-5-forgetting-await-and-getting-a-future-instead-of-a-value) A coloring side effect: a bare async call returns a lazy future, so forgetting `.await` is a type error, not a silent no-op (unlike JS, where a forgotten `await` gives you a `Promise` that may still run): ```rust 1 async fn fetch_count() -> u32 { 2 42 3 } 4 5 #[tokio::main] 6 async fn main() { 7 // does not compile (error[E0308]): forgot `.await`, so this is a Future. 8 let count: u32 = fetch_count(); 9 println!("{count}"); 10 } ``` Real compiler output (trimmed): ```plaintext 1 error[E0308]: mismatched types 2 --> src/main.rs:8:22 3 | 4 8 | let count: u32 = fetch_count(); 5 | --- ^^^^^^^^^^^^^ expected `u32`, found future 6 | | 7 | expected due to this 8 | 9 note: calling an async function returns a future 10 help: consider `await`ing on the `Future` 11 | 12 8 | let count: u32 = fetch_count().await; 13 | ++++++ ``` **Fix:** add `.await`. The compiler even suggests it. Because Rust futures are *lazy* (see [Promises vs Futures](/11-async/00-promises-vs-futures/)), a forgotten `.await` means the work never even starts, but the type system catches it long before that becomes a runtime mystery. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Classify the workload before choosing a tool [Section titled “Classify the workload before choosing a tool”](#classify-the-workload-before-choosing-a-tool) Ask “I/O-bound or CPU-bound?” first, every time. I/O-bound and many-at-once → async. CPU-bound → threads / `rayon`. One sequential thing → plain sync. This single question prevents the majority of mismatched-tool mistakes. ### Keep async functions free of blocking and heavy CPU work [Section titled “Keep async functions free of blocking and heavy CPU work”](#keep-async-functions-free-of-blocking-and-heavy-cpu-work) Treat an async task like the Node event loop: anything that does not yield is a liability. Use async-aware I/O (`tokio::fs`, `tokio::net`, `sqlx`, `reqwest` non-blocking), and push blocking calls and CPU loops to `spawn_blocking` or a thread pool. A good rule: every code path in an `async fn` should reach an `.await` “soon.” ### Use `rayon` for data parallelism, Tokio for I/O concurrency — and compose them [Section titled “Use rayon for data parallelism, Tokio for I/O concurrency — and compose them”](#use-rayon-for-data-parallelism-tokio-for-io-concurrency--and-compose-them) These are not competitors. A server can accept connections with Tokio (I/O concurrency) and, inside a `spawn_blocking` closure, use `rayon` to parallelize a CPU-heavy transform across cores. Keep the two pools distinct: Tokio’s workers for I/O, the blocking/`rayon` pool for computation. ### Do not reach for a runtime you do not need [Section titled “Do not reach for a runtime you do not need”](#do-not-reach-for-a-runtime-you-do-not-need) Synchronous Rust is a feature, not a limitation. Libraries especially should think hard before becoming async-only; it colors every caller. Where practical, expose a sync core and let callers choose; or offer both, gated behind a [feature flag](/12-modules-packages/09-feature-flags/). ### Bridge sync↔async at the edges, deliberately [Section titled “Bridge sync↔async at the edges, deliberately”](#bridge-syncasync-at-the-edges-deliberately) Use `block_on` (or `#[tokio::main]`) at the boundary where synchronous code must enter async: `main`, a sync trait impl, an FFI callback. Never nest `block_on` inside async. Within async, propagate with `.await` and `?` (see [Async/Await Syntax](/11-async/01-async-await/)). ### Right-size the parallelism to the cores [Section titled “Right-size the parallelism to the cores”](#right-size-the-parallelism-to-the-cores) Spawning a million async tasks for I/O is fine; they are cheap and mostly idle. Spawning a million *threads* for CPU work is not; it thrashes the scheduler and exhausts memory on stacks. For CPU work, parallelism should track core count, which is exactly what `rayon`’s pool does by default. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored pipeline that mixes both worlds: a batch image service that **downloads** images (I/O-bound → async, overlapped) and then **processes** each one (CPU-bound → offloaded with `spawn_blocking` so it never stalls the downloads). This is the canonical “concurrent I/O feeding parallel compute” shape. ```rust 1 use std::time::{Duration, Instant}; 2 use tokio::task::JoinSet; 3 use tokio::time::sleep; 4 5 /// I/O-bound: download an image. Mostly waiting on the network → async. 6 async fn download(id: u32) -> Vec<u8> { 7 sleep(Duration::from_millis(80)).await; // network round-trip 8 vec![(id % 256) as u8; 1_000_000] // pretend this is a 1 MB image 9 } 10 11 /// CPU-bound: a synchronous transform (resize + checksum). No .await here. 12 fn process(bytes: &[u8]) -> u64 { 13 // Stand-in for real image work: a heavy fold over every byte. 14 bytes 15 .iter() 16 .fold(0u64, |acc, &b| acc.wrapping_mul(1099511628211).wrapping_add(b as u64)) 17 } 18 19 #[tokio::main] 20 async fn main() { 21 let start = Instant::now(); 22 let mut set = JoinSet::new(); 23 24 for id in 0..4u32 { 25 set.spawn(async move { 26 // 1. Await the I/O concurrently with the other tasks. 27 let bytes = download(id).await; 28 29 // 2. Offload the CPU-bound transform to the blocking pool so it does 30 // not stall the async workers driving the other downloads. 31 let checksum = tokio::task::spawn_blocking(move || process(&bytes)) 32 .await 33 .expect("processing task panicked"); 34 35 (id, checksum) 36 }); 37 } 38 39 let mut results = Vec::new(); 40 while let Some(joined) = set.join_next().await { 41 results.push(joined.expect("worker panicked")); 42 } 43 results.sort(); 44 45 for (id, checksum) in results { 46 println!("image {id}: checksum {checksum}"); 47 } 48 println!("elapsed = {} ms", start.elapsed().as_millis()); 49 } ``` Real output (`--release`): ```plaintext 1 image 0: checksum 0 2 image 1: checksum 15279771427360356480 3 image 2: checksum 12112798781011161344 4 image 3: checksum 8945826134661966208 5 elapsed = 91 ms ``` Four 80 ms downloads overlap (so they cost \~80 ms together, not 320 ms), and each CPU-bound `process` runs on the blocking pool without freezing the async workers: total \~91 ms. The same pipeline written as “async everything” would block a worker during each `process`; written as “threads everything” it would waste threads sitting idle during each download. Matching the tool to the workload-half is the whole point. > **Note:** In production you would download with [`reqwest`](https://docs.rs/reqwest), and if `process` were itself data-parallel you could use `rayon` *inside* the `spawn_blocking` closure. Sharing state across the tasks (a counter, a cache) uses the `Arc<Mutex<_>>` pattern in [The `Arc<Mutex<T>>` Pattern](/11-async/12-arc-mutex-pattern/). Error handling with `?` across async boundaries is covered in [Async/Await Syntax](/11-async/01-async-await/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [Tokio Tutorial — Bridging with sync code](https://tokio.rs/tokio/topics/bridging) — `block_on`, `spawn_blocking`, and mixing sync/async. * [Tokio — CPU-bound tasks and blocking code](https://docs.rs/tokio/latest/tokio/index.html#cpu-bound-tasks-and-blocking-code) — the official guidance on what *not* to run on the runtime. * [The `rayon` crate](https://docs.rs/rayon) — data parallelism with parallel iterators, the go-to for CPU-bound work. * [“What Color is Your Function?”](https://journal.stuffwithstuff.com/2015/02/01/what-color-is-your-function/) — the essay that named the function-coloring problem. * [`std::thread` documentation](https://doc.rust-lang.org/std/thread/) — OS threads, the right tool when async is overkill. * [`tokio::runtime::Runtime::block_on`](https://docs.rs/tokio/latest/tokio/runtime/struct.Runtime.html#method.block_on) — the sync→async bridge. Related sections of this guide: * [Promises vs Futures](/11-async/00-promises-vs-futures/) — why Rust futures are lazy and need a runtime. * [The Tokio Runtime](/11-async/02-tokio-intro/) — single-thread vs multi-thread schedulers (concurrency vs parallelism in the runtime). * [Async/Await Syntax](/11-async/01-async-await/) — `async`/`await` syntax and `?` inside async. * [Spawning Tasks](/11-async/09-spawning-tasks/) — `tokio::spawn`, `spawn_blocking`, and tasks-vs-threads mechanics. * [Concurrency vs Parallelism](/11-async/10-concurrency/) — concurrency vs parallelism in depth, structured patterns, cancellation. * [The `Arc<Mutex<T>>` Pattern](/11-async/12-arc-mutex-pattern/) — sharing state across tasks and threads. * [Async Synchronization Primitives](/11-async/11-sync-primitives/) — std vs Tokio locks, and holding locks across `.await`. * [Understanding Cargo](/01-getting-started/03-cargo-basics/) — `cargo add` and dependencies. * [Basics](/02-basics/) — Rust fundamentals refresher. * [Feature Flags and Conditional Compilation](/12-modules-packages/09-feature-flags/) — exposing sync and async APIs behind features. * Next section: [Modules & Packages](/12-modules-packages/) — organizing crates and modules. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Recognize and parallelize CPU-bound work [Section titled “Exercise 1: Recognize and parallelize CPU-bound work”](#exercise-1-recognize-and-parallelize-cpu-bound-work) **Difficulty:** Easy **Objective:** Identify a workload as CPU-bound and reach for data parallelism instead of async. **Instructions:** 1. Write a synchronous `fn collatz_steps(n: u64) -> u64` that counts how many steps the Collatz sequence takes to reach 1 (even → `n/2`, odd → `3n+1`). 2. Over the range `1..100_000`, find the number with the longest chain. 3. Use `rayon`’s parallel iterator (`into_par_iter`) — *not* async — to spread the work across cores. Print the winning number and its step count. 4. In a comment, state why async would not help here. Solution ```rust 1 use rayon::prelude::*; 2 3 /// CPU-bound: count Collatz steps to reach 1. Pure computation, no waiting. 4 fn collatz_steps(mut n: u64) -> u64 { 5 let mut steps = 0; 6 while n != 1 { 7 n = if n % 2 == 0 { n / 2 } else { 3 * n + 1 }; 8 steps += 1; 9 } 10 steps 11 } 12 13 fn main() { 14 // CPU-bound: there is no I/O to overlap, so async buys nothing. Only more 15 // cores help — that is exactly what rayon's parallel iterator gives us. 16 let (best_n, best_steps) = (1..100_000u64) 17 .into_par_iter() 18 .map(|n| (n, collatz_steps(n))) 19 .max_by_key(|&(_, steps)| steps) 20 .unwrap(); 21 22 println!("n = {best_n} has {best_steps} steps"); 23 } ``` Output (`--release`): ```plaintext 1 n = 77031 has 350 steps ``` The computation is pure CPU work with no waiting, so `async`/Tokio would add overhead without speeding anything up. `rayon` parallelizes across cores with a one-word change from `into_iter` to `into_par_iter`. ### Exercise 2: Keep the runtime responsive by offloading a blocking call [Section titled “Exercise 2: Keep the runtime responsive by offloading a blocking call”](#exercise-2-keep-the-runtime-responsive-by-offloading-a-blocking-call) **Difficulty:** Medium **Objective:** Fix a blocking call inside an async program so other tasks stay responsive. **Instructions:** 1. Write a synchronous `fn slow_hash(password: &str) -> u64` that calls `std::thread::sleep` for 150 ms (standing in for a deliberately slow password hash) and then folds the bytes into a `u64`. 2. In a `current_thread` Tokio runtime, spawn a “heartbeat” task that prints twice, 50 ms apart. 3. Compute the hash *without* starving the heartbeat — offload it with `spawn_blocking` — then await both. 4. Verify from the timing that the heartbeat ticked on schedule. Solution ```rust 1 use std::time::Duration; 2 use tokio::time::{sleep, Instant}; 3 4 /// A synchronous, blocking "hash" of a password (stands in for bcrypt/argon2). 5 fn slow_hash(password: &str) -> u64 { 6 std::thread::sleep(Duration::from_millis(150)); // CPU-bound + blocking 7 password.bytes().fold(0u64, |a, b| a.wrapping_mul(31).wrapping_add(b as u64)) 8 } 9 10 #[tokio::main(flavor = "current_thread")] 11 async fn main() { 12 let start = Instant::now(); 13 14 // A heartbeat proving the runtime stays responsive. 15 let heartbeat = tokio::spawn(async move { 16 for n in 1..=2 { 17 sleep(Duration::from_millis(50)).await; 18 println!("heartbeat {n} at {} ms", start.elapsed().as_millis()); 19 } 20 }); 21 22 let password = String::from("hunter2"); 23 // Offload the blocking hash so it does not stall the single async worker. 24 let hash = tokio::task::spawn_blocking(move || slow_hash(&password)) 25 .await 26 .expect("hashing task panicked"); 27 28 println!("hash = {hash} at {} ms", start.elapsed().as_millis()); 29 heartbeat.await.unwrap(); 30 } ``` Output: ```plaintext 1 heartbeat 1 at 52 ms 2 heartbeat 2 at 104 ms 3 hash = 95755137202 at 152 ms ``` The heartbeat ticks at 52 and 104 ms — right on time — because `spawn_blocking` moved the 150 ms blocking call to a separate thread pool. Calling `slow_hash(...)` directly in `main` (without `spawn_blocking`) would have frozen the single worker and pushed the first heartbeat past 150 ms. ### Exercise 3: A mixed pipeline — concurrent I/O feeding parallel compute [Section titled “Exercise 3: A mixed pipeline — concurrent I/O feeding parallel compute”](#exercise-3-a-mixed-pipeline--concurrent-io-feeding-parallel-compute) **Difficulty:** Medium–Hard **Objective:** Combine async I/O concurrency with `rayon` CPU parallelism in one program, putting each tool where it belongs. **Instructions:** 1. Write `async fn fetch_shard(id: u64) -> Vec<u64>` that sleeps 50 ms (I/O) then returns 250,000 numbers. 2. Write a synchronous `fn sum_of_squares(data: &[u64]) -> u64` that uses `rayon`’s `par_iter` to sum the squares (CPU-bound). 3. In `async main`, fetch four shards *concurrently*, flatten them, then offload the CPU-bound reduction to the blocking pool (where `rayon` parallelizes it). Print the total and elapsed time. 4. The downloads should overlap (≈50 ms, not 200 ms) and the reduction should not stall the runtime. Solution ```rust 1 use std::time::{Duration, Instant}; 2 use rayon::prelude::*; 3 use tokio::time::sleep; 4 5 /// I/O-bound: fetch a "shard" of numbers (async). 6 async fn fetch_shard(id: u64) -> Vec<u64> { 7 sleep(Duration::from_millis(50)).await; // network wait 8 (0..250_000).map(|x| x + id * 250_000).collect() 9 } 10 11 /// CPU-bound: sum the squares of a slice (synchronous, parallelizable). 12 fn sum_of_squares(data: &[u64]) -> u64 { 13 data.par_iter().map(|&x| x.wrapping_mul(x)).sum() 14 } 15 16 #[tokio::main] 17 async fn main() { 18 let start = Instant::now(); 19 20 // 1. Fetch four shards concurrently (I/O overlaps → ~50 ms, not 200). 21 let shards = futures::future::join_all((0..4u64).map(fetch_shard)).await; 22 23 // 2. Flatten, then offload the CPU-bound reduction to the blocking pool, 24 // where rayon spreads it across cores. 25 let all: Vec<u64> = shards.into_iter().flatten().collect(); 26 let total = tokio::task::spawn_blocking(move || sum_of_squares(&all)) 27 .await 28 .expect("compute task panicked"); 29 30 println!("sum of squares = {total}"); 31 println!("elapsed = {} ms", start.elapsed().as_millis()); 32 } ``` Output (`--release`): ```plaintext 1 sum of squares = 333332833333500000 2 elapsed = 62 ms ``` The four 50 ms fetches overlap via `join_all` (I/O concurrency, \~50 ms total), and the CPU-bound reduction runs on the blocking pool with `rayon` spreading it across cores, so the async runtime never stalls. This is the production shape: Tokio for the waiting, `rayon`/threads for the computing, `spawn_blocking` as the seam between them. `join_all` comes from the `futures` crate (`futures = "0.3"`); for a fixed, small set you could equally use [`tokio::join!`](/11-async/07-select-join/). # Rust Modules, Packages & Cargo > Map TypeScript's import/export and npm onto Rust: mod, use and pub for code inside a crate, and Cargo for dependencies, builds, tests, features, and publishing. In TypeScript you split code across files and pull pieces in with `import`/`export`, and you manage third-party code with npm and a `package.json`. Rust covers the same ground with two distinct systems: **modules** (`mod`, `use`, `pub`) organize code *within* a crate, and **Cargo** (`Cargo.toml`, `cargo add`, workspaces) manages packages, dependencies, and builds. The biggest surprises for a TypeScript developer are that modules are **not** one-file-equals-one-module by default, that *everything is private until you say `pub`*, and that Cargo is far more than npm: it is also your build tool, test runner, formatter, linter, and doc generator rolled into one. *** ## What You’ll Learn [Section titled “What You’ll Learn”](#what-youll-learn) * How ES modules map onto Rust’s `mod` system — inline modules, file-based modules, and the mental model that a crate is a *tree* of modules rooted at `lib.rs`/`main.rs` * How to navigate that tree with paths: `crate::`, `super::`, `self::`, and absolute vs relative paths * How `import` becomes `use`, including re-exporting with `pub use` and renaming with `as` * Why Rust items are **private by default** and how `pub`, `pub(crate)`, and `pub(super)` give you precise visibility control that `export` never offered * How `package.json` becomes `Cargo.toml`, what `Cargo.lock` is for, and how build profiles work * The everyday `cargo` commands (`build`/`run`/`test`/`check`/`fmt`/`clippy`/`doc`/`add`) and how they replace your npm-script muscle memory * How `npm install` becomes `cargo add`, how semver requirements (caret/tilde/exact) work, and how to enable optional crate **features** * The difference between `[dependencies]`, `[dev-dependencies]`, and `[build-dependencies]` * How a monorepo becomes a **Cargo workspace** with a shared lockfile and `workspace` dependency inheritance * How **feature flags** drive conditional compilation with `#[cfg(...)]`, and why features must be *additive* * What a `build.rs` **build script** does, and how to publish a crate to **crates.io** *** ## Topics [Section titled “Topics”](#topics) | Topic | Description | | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | [Modules](/12-modules-packages/00-modules/) | ES modules → `mod`: inline modules and file-based modules, and the module-system mental model. | | [The Module Tree](/12-modules-packages/01-module-tree/) | Paths through the tree: `crate::` / `super::` / `self::`, and absolute vs relative paths. | | [The `use` Keyword](/12-modules-packages/02-use-keyword/) | `import` → `use`: bringing items into scope, re-exporting with `pub use`, and renaming with `as`. | | [Visibility with `pub`](/12-modules-packages/03-pub-visibility/) | `export` → `pub`: private-by-default, and `pub(crate)`/`pub(super)`/`pub(in path)` for precise control. | | [Cargo & Cargo.toml](/12-modules-packages/04-cargo/) | `package.json` → `Cargo.toml`: `[package]`/`[dependencies]`, `Cargo.lock`, and build profiles. | | [Cargo Commands](/12-modules-packages/05-cargo-commands/) | The common `cargo` commands (`build`/`run`/`test`/`check`/`fmt`/`clippy`/`doc`/`add`) and `new` vs `init`. | | [Dependencies](/12-modules-packages/06-dependencies/) | `npm install` → `cargo add`: semver requirements, features, and git/path dependencies. | | [Dev & Build Dependencies](/12-modules-packages/07-dev-dependencies/) | `devDependencies` → `[dev-dependencies]`, plus `[build-dependencies]` and optional deps. | | [Workspaces](/12-modules-packages/08-workspaces/) | Monorepos → Cargo workspaces: `[workspace]`, members, the shared lockfile, and workspace deps. | | [Feature Flags](/12-modules-packages/09-feature-flags/) | Conditional compilation: `[features]`, `#[cfg(feature = "...")]`, default features, and additive design. | | [Build Scripts](/12-modules-packages/10-build-scripts/) | `build.rs`: code generation, linking native libraries, and `cargo::rerun-if-*` directives. | | [Publishing](/12-modules-packages/11-publishing/) | Publishing to crates.io: `cargo publish`, metadata, versioning, and yanking. | *** ## Learning Objectives [Section titled “Learning Objectives”](#learning-objectives) By the end of this section, you will be able to: * Split a crate into modules across files and navigate it with `crate::`/`super::`/`self::` paths * Control exactly what is public with `pub` and its scoped variants, and design a clean public API with `pub use` re-exports * Read and write a `Cargo.toml`, understand `Cargo.lock`, and pick the right command for build/test/lint/doc tasks * Add, rename, and feature-gate dependencies, and place them in the correct dependency table * Structure a multi-crate project as a workspace with shared dependencies and a single lockfile * Use feature flags for conditional compilation in an additive way, write a basic `build.rs`, and publish a crate to crates.io *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * [Section 01: Getting Started](/01-getting-started/). You should already be comfortable running `cargo new`, `cargo build`, and `cargo run`; this section explains what those commands and the generated files actually do. * Helpful but not required: [Section 09: Generics & Traits](/09-generics-traits/) for understanding what you are exporting, and any earlier section whose code you would like to reorganize into modules. > **Note:** Some examples in this section deliberately span **multiple files** (e.g. `mod auth;` plus a sibling `auth.rs`) or a `Cargo.toml`, so a single snippet won’t compile on its own — the surrounding prose shows the full file layout. *** ## Estimated Time [Section titled “Estimated Time”](#estimated-time) * **Reading:** 4-5 hours * **Hands-on Practice:** 3 hours * **Exercises:** 2 hours * **Total:** 8-10 hours > **Tip:** Read the *modules* half (`modules` → `module-tree` → `use-keyword` → `pub-visibility`) and the *Cargo* half (`cargo` → `cargo-commands` → `dependencies` → …) as two related but separable tracks. If you just want to ship code, the Cargo half is the higher-leverage place to start. *** ## Frequently asked questions [Section titled “Frequently asked questions”](#frequently-asked-questions) ### What is Cargo, and how does it map to npm? [Section titled “What is Cargo, and how does it map to npm?”](#what-is-cargo-and-how-does-it-map-to-npm) Cargo is Rust’s build tool and package manager. `cargo add` is `npm install`, `cargo build --release` is `npm run build`, `cargo test` is `npm test`, and `Cargo.toml` is `package.json`. It also bundles the linter, formatter, and docs generator. See [Cargo](/12-modules-packages/04-cargo/). ### How do `mod` and `use` relate to `import`/`export`? [Section titled “How do mod and use relate to import/export?”](#how-do-mod-and-use-relate-to-importexport) `mod` declares a module (a file or an inline block), `pub` exports an item, and `use` brings a path into scope like `import`. Paths are rooted at `crate`, so you write `use crate::auth::login;`. See [The Module Tree](/12-modules-packages/01-module-tree/) and [The `use` Keyword](/12-modules-packages/02-use-keyword/). ### Why is an item “private” by default? [Section titled “Why is an item “private” by default?”](#why-is-an-item-private-by-default) Everything is private to its module unless you mark it `pub`. This is stricter than JavaScript’s file-level exports and makes a crate’s public API an explicit, deliberate surface rather than whatever you happened to export. See [Visibility](/12-modules-packages/03-pub-visibility/). *** **Next:** [Section 13: Testing →](/13-testing/) — Rust’s built-in test framework and the ecosystem around it, replacing Jest/Vitest. # Modules: From ES Modules to `mod` > In TypeScript every file is a module; in Rust a file does nothing until you attach it with mod. Build one explicit module tree per crate, private by default. Coming from TypeScript, you organize code with files and `import`/`export`. Rust has files too, but its code-organization unit is the **module**, declared with the `mod` keyword. The mental shift is real: in Rust, **a file is not automatically a module**, and `mod` is not an import. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A Rust **module** is a named container for functions, types, constants, and other modules. You build a single tree of modules per **crate** (compilation unit), starting at a **crate root** (`src/main.rs` or `src/lib.rs`). Where ES modules treat every file as an independent module that you wire together with `import`, Rust requires you to *explicitly attach* each file into the tree with a `mod` declaration before any of its code is compiled or reachable. > **Tip:** Read `mod foo;` as “the module `foo` lives in another file — go load it,” and `mod foo { ... }` as “here is the module `foo`, inline.” Neither one *imports* anything into scope; that is the job of `use` (covered in [The `use` Keyword](/12-modules-packages/02-use-keyword/)). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In ES modules (the system Node v22 and modern TypeScript use), **the file *is* the module**. There is no separate declaration step: every file you create is automatically a module, and you connect them by importing the file path. src/auth/session.ts ```typescript 1 export function create(user: string): string { 2 return `session-for-${user}`; 3 } 4 5 // src/auth.ts 6 import { create } from "./auth/session.js"; 7 8 function verify(user: string): boolean { 9 // Not exported -> private to this file/module. 10 return user.length > 0; 11 } 12 13 export function login(user: string): boolean { 14 console.log(`Logging in ${user}`); 15 return verify(user); 16 } 17 export { create as createSession }; 18 19 // src/main.ts 20 import { login, createSession } from "./auth.js"; 21 22 const ok = login("alice"); 23 const token = createSession("alice"); 24 console.log(`ok=${ok}, token=${token}`); ``` **Key points about the ES module model:** * Each file is a module the moment it exists; no declaration needed. * `export` makes a binding visible; anything not exported is module-private. * `import` pulls bindings into scope, using the *file path* as the module identity. * The dependency graph is discovered by *following imports* from the entry file. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Here is the same `auth` / `session` structure in Rust, written **inline** (everything in one file) so you can see the whole module tree at a glance. ```rust 1 // src/main.rs — the crate root. 2 3 // `mod auth { ... }` defines a module named `auth` right here, inline. 4 mod auth { 5 // `pub` exports this item out of `auth` (like TS `export`). 6 pub fn login(user: &str) -> bool { 7 println!("Logging in {user}"); 8 verify(user) // siblings call each other directly, no path needed 9 } 10 11 // No `pub` -> private to `auth`. Callers outside cannot reach it. 12 fn verify(user: &str) -> bool { 13 !user.is_empty() 14 } 15 16 // A child module, also inline. `pub mod` exports the module itself. 17 pub mod session { 18 pub fn create(user: &str) -> String { 19 format!("session-for-{user}") 20 } 21 } 22 } 23 24 fn main() { 25 // Reach into the tree with `::` paths. No `import`/`use` required — 26 // a fully qualified path works on its own. 27 let ok = auth::login("alice"); 28 let token = auth::session::create("alice"); 29 println!("ok={ok}, token={token}"); 30 } ``` **Real output** (verified with `cargo run`): ```text 1 Logging in alice 2 ok=true, token=session-for-alice ``` When the tree grows, you split it across files. The next section shows exactly how. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### A crate has one module tree, rooted at the crate root [Section titled “A crate has one module tree, rooted at the crate root”](#a-crate-has-one-module-tree-rooted-at-the-crate-root) Every Rust crate is compiled as a single unit and has exactly one **crate root** file: * A **binary** crate roots at `src/main.rs`. * A **library** crate roots at `src/lib.rs`. That root file is the implicit module called `crate`. Everything else hangs beneath it. So in the inline example above, the full paths are `crate::auth`, `crate::auth::login`, and `crate::auth::session::create`. (Path syntax — `crate::`, `super::`, `self::` — is the subject of [Paths in the Module Tree](/12-modules-packages/01-module-tree/).) > **Note:** This is a big contrast with ES modules, where there is no single tree. Each file is its own module root and the “shape” of your code is just whatever graph the `import` statements happen to form. Rust always has one explicit, hierarchical tree per crate. ### `mod` declares, it does not import [Section titled “mod declares, it does not import”](#mod-declares-it-does-not-import) This is the single most important sentence in this whole section: > `mod foo;` tells the compiler **where the module `foo`’s code lives** and attaches it to the tree. It does **not** bring any of `foo`’s names into the current scope. There are two forms: ```rust 1 mod auth { /* ... body of the module ... */ } // inline: body is right here 2 mod auth; // out-of-line: body is in another file ``` In TypeScript there is no equivalent of `mod`. A TS file becomes part of your program simply by being imported. In Rust, a `.rs` file that no one declares with `mod` is **completely ignored**: it is not even compiled. ### File-based modules: the modern layout [Section titled “File-based modules: the modern layout”](#file-based-modules-the-modern-layout) When you write `mod auth;` (no body), the compiler looks for the module’s code in one of two places: 1. `src/auth.rs` (preferred, modern layout), or 2. `src/auth/mod.rs` (older layout, still valid). A module’s **child** modules go in a directory named after the parent. Here is the same `auth`/`session` example, split into files: ```rust 1 // src/main.rs — crate root. 2 // Attach the `auth` module; its code lives in src/auth.rs. 3 mod auth; 4 5 fn main() { 6 let ok = auth::login("alice"); 7 let token = auth::session::create("alice"); 8 println!("ok={ok}, token={token}"); 9 } ``` ```rust 1 // src/auth.rs — the body of module `auth`. 2 // `auth` declares its own child module `session`, 3 // whose code lives in src/auth/session.rs. 4 pub mod session; 5 6 pub fn login(user: &str) -> bool { 7 println!("Logging in {user}"); 8 verify(user) 9 } 10 11 fn verify(user: &str) -> bool { 12 !user.is_empty() 13 } ``` ```rust 1 // src/auth/session.rs — the body of module `auth::session`. 2 pub fn create(user: &str) -> String { 3 format!("session-for-{user}") 4 } ``` The resulting file tree: ```text 1 src 2 ├── auth 3 │ └── session.rs // module crate::auth::session 4 ├── auth.rs // module crate::auth 5 └── main.rs // crate root ``` **Real output** (verified with `cargo run` on exactly this layout): ```text 1 Logging in alice 2 ok=true, token=session-for-alice ``` Notice what the file paths do **not** dictate: the *module path* is `crate::auth::session`, which mirrors the declarations (`mod auth;` then `pub mod session;`), and it just so happens to line up with the directory structure. The directory layout follows the module tree, not the other way around. > **Warning:** Older tutorials (pre-2018-edition) tell you to name every module file `mod.rs` and put it in a folder, e.g. `src/auth/mod.rs`. That still works, but the flat `src/auth.rs` + `src/auth/` layout is the current idiom and avoids a directory full of identical `mod.rs` files in your editor tabs. Use `cargo new` (which selects the latest stable edition, 2024) and prefer `auth.rs`. ### Inline vs file-based: same tree, different physical storage [Section titled “Inline vs file-based: same tree, different physical storage”](#inline-vs-file-based-same-tree-different-physical-storage) The inline and file-based versions above produce an **identical** module tree. They are interchangeable; you choose based on size: * **Inline** (`mod foo { ... }`) keeps small, closely related code together. It is also the standard place for unit tests: `#[cfg(test)] mod tests { ... }` (see [Testing](/13-testing/)). * **File-based** (`mod foo;` + `foo.rs`) keeps large modules in their own files. You can freely nest the two: an inline module can declare a file-based child and vice versa. ### Privacy is per-module and defaults to private [Section titled “Privacy is per-module and defaults to private”](#privacy-is-per-module-and-defaults-to-private) Every item (function, struct, module, etc.) is **private by default** and visible only within its own module and that module’s descendants. `pub` opens it up one boundary at a time. In the example, `verify` has no `pub`, so `auth::login` can call it but `main` cannot. This is the inverse of TypeScript, where a top-level binding is module-private until you `export` it. Same idea, but Rust applies it at *every* nesting level, the file boundary being just one of them. Visibility levels (`pub`, `pub(crate)`, `pub(super)`) get full treatment in [Visibility and the `pub` Keyword](/12-modules-packages/03-pub-visibility/). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / ES Modules | Rust | | ---------------------------- | -------------------------------- | ------------------------------------------------------------------------------------- | | Unit of organization | The file | The **module** (`mod`) | | How a file joins the program | Automatically, when imported | Only when declared with `mod` | | What `mod` does | (no equivalent) | Declares a module + attaches it to the tree | | Bringing names into scope | `import { x } from "..."` | `use crate::path::x;` (see [The `use` Keyword](/12-modules-packages/02-use-keyword/)) | | Module identity | The file path | The position in the crate’s module tree | | Number of roots | One module per file (many roots) | One tree per crate, single root | | Default visibility | Private until `export` | Private until `pub`, at *every* level | | Nested modules | Folders + re-export files | First-class: `mod a { mod b { ... } }` | | Cross-package boundary | npm package name | crate name (see [Cargo.toml](/12-modules-packages/04-cargo/)) | ### The mental model in one picture [Section titled “The mental model in one picture”](#the-mental-model-in-one-picture) ```text 1 ES modules (TypeScript): Rust: 2 crate (= src/main.rs or src/lib.rs) 3 file ─import→ file ─import→ file └── mod auth 4 (a graph discovered by imports) ├── fn login (pub) 5 ├── fn verify (private) 6 └── mod session 7 └── fn create (pub) 8 (one explicit tree, built by `mod`) ``` > **Note:** A useful analogy: Rust’s `mod` is closer to a TypeScript **namespace** (`namespace Foo { export function bar() {} }`) than to a file: both create an explicit named scope and use a path (`Foo.bar` / `auth::session::create`) to reach inside. But TS namespaces are discouraged in modern code, while Rust modules are *the* idiom. Don’t lean on the analogy too hard. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Expecting a `.rs` file to load itself (the ES-module reflex) [Section titled “Pitfall 1: Expecting a .rs file to load itself (the ES-module reflex)”](#pitfall-1-expecting-a-rs-file-to-load-itself-the-es-module-reflex) You create `src/utils.rs` and try to use it directly, the way you’d just `import` a TS file: src/main.rs ```rust 1 fn main() { 2 // does not compile (error[E0433]): `utils` was never declared. 3 let s = utils::shout("hi"); 4 println!("{s}"); 5 } ``` src/utils.rs ```rust 1 pub fn shout(s: &str) -> String { 2 s.to_uppercase() 3 } ``` **Real compiler error:** ```text 1 error[E0433]: failed to resolve: use of unresolved module or unlinked crate `utils` 2 --> src/main.rs:3:13 3 | 4 3 | let s = utils::shout("hi"); 5 | ^^^^^ use of unresolved module or unlinked crate `utils` 6 | 7 help: to make use of source file src/utils.rs, use `mod utils` in this file to declare the module 8 | 9 2 + mod utils; 10 | ``` **Fix:** add `mod utils;` to `src/main.rs`. The file exists on disk, but until it is *declared* it is invisible to the compiler. ### Pitfall 2: Declaring a module whose file does not exist [Section titled “Pitfall 2: Declaring a module whose file does not exist”](#pitfall-2-declaring-a-module-whose-file-does-not-exist) The mirror image of Pitfall 1: you write `mod widgets;` but never create `src/widgets.rs`. src/main.rs ```rust 1 mod widgets; // does not compile (error[E0583]): no src/widgets.rs 2 3 fn main() { 4 println!("{}", widgets::render()); 5 } ``` **Real compiler error:** ```text 1 error[E0583]: file not found for module `widgets` 2 --> src/main.rs:2:1 3 | 4 2 | mod widgets; 5 | ^^^^^^^^^^^^ 6 | 7 = help: to create the module `widgets`, create file "src/widgets.rs" or "src/widgets/mod.rs" 8 = note: if there is a `mod widgets` elsewhere in the crate already, import it with `use crate::...` instead ``` **Fix:** create `src/widgets.rs` (or `src/widgets/mod.rs`), or remove the declaration. ### Pitfall 3: Forgetting that `pub` is per-boundary, not “public to the whole program” [Section titled “Pitfall 3: Forgetting that pub is per-boundary, not “public to the whole program””](#pitfall-3-forgetting-that-pub-is-per-boundary-not-public-to-the-whole-program) A `pub` item is only reachable if **every** module on the path to it is also reachable. Here `compute` is private to `bank`, so even though `bank` is reachable from `main`, the function is not: ```rust 1 mod bank { 2 pub fn balance() -> u64 { 3 compute() // fine: same module 4 } 5 fn compute() -> u64 { 6 100 7 } 8 } 9 10 fn main() { 11 // does not compile (error[E0603]): compute() is private to `bank`. 12 let raw = bank::compute(); 13 println!("{raw}"); 14 } ``` **Real compiler error:** ```text 1 error[E0603]: function `compute` is private 2 --> src/main.rs:12:21 3 | 4 12 | let raw = bank::compute(); 5 | ^^^^^^^ private function 6 | 7 note: the function `compute` is defined here 8 --> src/main.rs:5:5 9 | 10 5 | fn compute() -> u64 { 11 | ^^^^^^^^^^^^^^^^^^^ ``` **Fix:** call the public API (`bank::balance()`), or add `pub` to `compute` if it genuinely belongs in the public surface. See [Visibility and the `pub` Keyword](/12-modules-packages/03-pub-visibility/) for the finer-grained `pub(crate)` and `pub(super)`. ### Pitfall 4: Declaring the same module twice or expecting “barrel files” [Section titled “Pitfall 4: Declaring the same module twice or expecting “barrel files””](#pitfall-4-declaring-the-same-module-twice-or-expecting-barrel-files) In TypeScript you often write a barrel `index.ts` that re-exports a folder. In Rust, declaring `mod foo;` more than once in the same parent is an error, and there is no implicit `index.rs`. To create a curated public surface, declare the modules once and **re-export** their items with `pub use` (covered in [The `use` Keyword](/12-modules-packages/02-use-keyword/)). That is the idiomatic “barrel.” *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Let the module tree mirror your domain, not your file count [Section titled “1. Let the module tree mirror your domain, not your file count”](#1-let-the-module-tree-mirror-your-domain-not-your-file-count) Group by concept (`auth`, `orders`, `catalog`), not by mechanical type buckets (`functions`, `structs`). Start inline; promote a module to its own file only when it grows. ```rust 1 // Good: small helper stays inline next to what it serves. 2 mod metrics { 3 pub fn record(name: &str) { /* ... */ } 4 } ``` ### 2. Keep the crate root thin [Section titled “2. Keep the crate root thin”](#2-keep-the-crate-root-thin) A `main.rs` or `lib.rs` that is mostly `mod` declarations plus a small `main`/public API is easy to scan: it is your table of contents. src/lib.rs ```rust 1 pub mod catalog; 2 pub mod orders; 3 mod pricing; // private implementation detail, not part of the public API ``` ### 3. Prefer `foo.rs` over `foo/mod.rs` [Section titled “3. Prefer foo.rs over foo/mod.rs”](#3-prefer-foors-over-foomodrs) The flat layout is the current idiom and avoids many same-named tabs. Reserve `mod.rs` only when working in a codebase that already uses it. ### 4. Make modules private by default; widen deliberately [Section titled “4. Make modules private by default; widen deliberately”](#4-make-modules-private-by-default-widen-deliberately) Start every module and item private. Add `pub` (or the narrower `pub(crate)`) only when something genuinely crosses the boundary. This keeps your public API small and your refactors local: exactly the discipline that the [Visibility and the `pub` Keyword](/12-modules-packages/03-pub-visibility/) section formalizes. ### 5. Use inline `#[cfg(test)] mod tests` for unit tests [Section titled “5. Use inline #\[cfg(test)\] mod tests for unit tests”](#5-use-inline-cfgtest-mod-tests-for-unit-tests) Co-locating tests with the code they exercise is the Rust convention; the `#[cfg(test)]` attribute means the module is compiled only during `cargo test`. See [Testing](/13-testing/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small order-processing **library crate**, organized into a realistic module tree: a public `catalog` and `orders` API, plus a *private* `pricing` module that is an implementation detail and never leaves the crate. ```rust 1 // src/lib.rs — the crate root (library crate). 2 //! A tiny order-processing library, organized into modules. 3 4 pub mod catalog; 5 pub mod orders; 6 7 // Private module: an internal detail, NOT exported from the crate. 8 mod pricing; 9 10 #[cfg(test)] 11 mod tests { 12 use super::*; // bring the crate root's items into the test module 13 14 #[test] 15 fn totals_apply_tax() { 16 let cart = vec![ 17 orders::LineItem { sku: "BOOK".into(), qty: 2 }, 18 orders::LineItem { sku: "PEN".into(), qty: 5 }, 19 ]; 20 let total = orders::total_cents(&cart); 21 // 2 * 1200 + 5 * 150 = 3150, +8% tax = 3402 22 assert_eq!(total, 3402); 23 } 24 } ``` ```rust 1 // src/catalog.rs — module crate::catalog (public). 2 //! Product catalog lookups. 3 4 /// Returns the unit price in cents for a known SKU. 5 pub fn unit_price_cents(sku: &str) -> u32 { 6 match sku { 7 "BOOK" => 1200, 8 "PEN" => 150, 9 _ => 0, 10 } 11 } ``` ```rust 1 // src/orders.rs — module crate::orders (public). 2 //! Order modeling and totals. 3 4 use crate::catalog; 5 use crate::pricing; // reach a *private* sibling via an absolute path 6 7 pub struct LineItem { 8 pub sku: String, 9 pub qty: u32, 10 } 11 12 /// Sum the cart, then apply tax. Uses the private `pricing` module. 13 pub fn total_cents(items: &[LineItem]) -> u32 { 14 let subtotal: u32 = items 15 .iter() 16 .map(|item| catalog::unit_price_cents(&item.sku) * item.qty) 17 .sum(); 18 pricing::with_tax(subtotal) 19 } ``` ```rust 1 // src/pricing.rs — module crate::pricing (private to the crate). 2 //! Internal pricing rules — not part of the public API. 3 4 const TAX_PERCENT: u32 = 8; 5 6 // `pub(crate)` = visible everywhere in THIS crate, but not to consumers. 7 pub(crate) fn with_tax(subtotal_cents: u32) -> u32 { 8 subtotal_cents + subtotal_cents * TAX_PERCENT / 100 9 } ``` File tree: ```text 1 src 2 ├── catalog.rs // pub mod catalog 3 ├── lib.rs // crate root 4 ├── orders.rs // pub mod orders 5 └── pricing.rs // mod pricing (private) ``` **Real output** (verified with `cargo test`): ```text 1 running 1 test 2 test tests::totals_apply_tax ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` The takeaway: `orders` depends on `catalog` and `pricing`, but a *consumer* of this library can only see `catalog` and `orders`. The `pricing` module — even though `orders` calls into it — stays sealed inside the crate because it was declared `mod pricing;` without `pub`, and its function is `pub(crate)`. That is the module system doing exactly the API-shaping job that TypeScript leaves to convention and barrel files. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Defining Modules to Control Scope and Privacy](https://doc.rust-lang.org/book/ch07-02-defining-modules-to-control-scope-and-privacy.html) * [The Rust Book — Separating Modules into Different Files](https://doc.rust-lang.org/book/ch07-05-separating-modules-into-different-files.html) * [The Rust Reference — Modules](https://doc.rust-lang.org/reference/items/modules.html) * [Rust by Example — Modules](https://doc.rust-lang.org/rust-by-example/mod.html) ### Related Topics in This Guide [Section titled “Related Topics in This Guide”](#related-topics-in-this-guide) * [Paths: `crate::`, `super::`, `self::`](/12-modules-packages/01-module-tree/): how to address items in the tree. * [The `use` keyword](/12-modules-packages/02-use-keyword/) — bringing names into scope, re-exports, glob. * [Visibility with `pub`](/12-modules-packages/03-pub-visibility/): `pub`, `pub(crate)`, `pub(super)`, field visibility. * [Cargo and `Cargo.toml`](/12-modules-packages/04-cargo/) — how crates (the next boundary up from modules) are configured. * [Cargo commands](/12-modules-packages/05-cargo-commands/): `cargo new`, `build`, `run`, `test`. * [Testing](/13-testing/) — `#[cfg(test)] mod tests` in depth. ### Foundations [Section titled “Foundations”](#foundations) * [Getting Started](/01-getting-started/): crates, Cargo, and the `main.rs` entry point. * [Basics](/02-basics/) — the syntax used in these examples. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Build an inline module tree [Section titled “Exercise 1: Build an inline module tree”](#exercise-1-build-an-inline-module-tree) **Difficulty:** Beginner **Objective:** Practice declaring nested inline modules and reaching into them with `::` paths. **Instructions:** Create a `geometry` module with a child module `shapes`. `shapes` should expose a public `describe()` that returns `"circle, square, triangle"`. `geometry` should expose a public `summary()` that calls `shapes::describe()` and returns `"Shapes: circle, square, triangle"`. From `main`, print both `geometry::summary()` and `geometry::shapes::describe()`. ```rust 1 fn main() { 2 // TODO: build the geometry / shapes module tree above this, 3 // then print summary() and shapes::describe(). 4 } ``` Solution ```rust 1 mod geometry { 2 pub mod shapes { 3 pub fn describe() -> &'static str { 4 "circle, square, triangle" 5 } 6 } 7 8 pub fn summary() -> String { 9 format!("Shapes: {}", shapes::describe()) 10 } 11 } 12 13 fn main() { 14 println!("{}", geometry::summary()); 15 println!("{}", geometry::shapes::describe()); 16 } ``` **Output:** ```text 1 Shapes: circle, square, triangle 2 circle, square, triangle ``` ### Exercise 2: Split a struct module into its own file [Section titled “Exercise 2: Split a struct module into its own file”](#exercise-2-split-a-struct-module-into-its-own-file) **Difficulty:** Intermediate **Objective:** Convert an idea into a file-based module that owns a type with a private field and a public API. **Instructions:** In a fresh `cargo new` project, declare `mod inventory;` from `main.rs`. In `src/inventory.rs`, define a `pub struct Store` that holds a *private* `HashMap<String, u32>` field. Give it `pub fn new()`, `pub fn add(&mut self, name: &str, qty: u32)` (which accumulates), and `pub fn count(&self, name: &str) -> u32` (which returns 0 for missing items). From `main`, add a few items and print the counts. Solution src/main.rs ```rust 1 mod inventory; 2 3 fn main() { 4 let mut store = inventory::Store::new(); 5 store.add("apple", 3); 6 store.add("apple", 2); 7 store.add("pear", 1); 8 println!("apples: {}", store.count("apple")); 9 println!("pears: {}", store.count("pear")); 10 println!("missing: {}", store.count("kiwi")); 11 } ``` src/inventory.rs ```rust 1 use std::collections::HashMap; 2 3 pub struct Store { 4 items: HashMap<String, u32>, // private field — only `Store`'s methods touch it 5 } 6 7 impl Store { 8 pub fn new() -> Self { 9 Store { items: HashMap::new() } 10 } 11 12 pub fn add(&mut self, name: &str, qty: u32) { 13 let entry = self.items.entry(name.to_string()).or_insert(0); 14 *entry += qty; 15 } 16 17 pub fn count(&self, name: &str) -> u32 { 18 self.items.get(name).copied().unwrap_or(0) 19 } 20 } ``` **Output:** ```text 1 apples: 5 2 pears: 1 3 missing: 0 ``` ### Exercise 3: A two-level file-based module tree [Section titled “Exercise 3: A two-level file-based module tree”](#exercise-3-a-two-level-file-based-module-tree) **Difficulty:** Intermediate **Objective:** Lay out a parent module file plus a child module in a subdirectory, with the child as a shared private-ish helper. **Instructions:** Declare `mod temperature;` from `main.rs`. Module `temperature` (in `src/temperature.rs`) exposes `pub fn celsius_to_fahrenheit(c: f64) -> f64` and `pub fn fahrenheit_to_celsius(f: f64) -> f64`. It has a child module `conversions` (in `src/temperature/conversions.rs`) with a `pub fn scale_and_shift(value, factor, offset)` helper that both public functions call. From `main`, convert 100 C and 32 F and print the results. Solution src/main.rs ```rust 1 mod temperature; 2 3 fn main() { 4 let f = temperature::celsius_to_fahrenheit(100.0); 5 println!("100C = {f}F"); 6 let c = temperature::fahrenheit_to_celsius(32.0); 7 println!("32F = {c}C"); 8 } ``` src/temperature.rs ```rust 1 pub mod conversions; 2 3 pub fn celsius_to_fahrenheit(c: f64) -> f64 { 4 conversions::scale_and_shift(c, 9.0 / 5.0, 32.0) 5 } 6 7 pub fn fahrenheit_to_celsius(f: f64) -> f64 { 8 conversions::scale_and_shift(f - 32.0, 5.0 / 9.0, 0.0) 9 } ``` src/temperature/conversions.rs ```rust 1 pub fn scale_and_shift(value: f64, factor: f64, offset: f64) -> f64 { 2 value * factor + offset 3 } ``` File tree: ```text 1 src 2 ├── main.rs 3 ├── temperature 4 │ └── conversions.rs 5 └── temperature.rs ``` **Output:** ```text 1 100C = 212F 2 32F = 0C ``` # Paths in the Module Tree > TypeScript imports point at files on disk; Rust paths point at nodes in the module tree with ::. Learn crate::, super::, self::, and absolute vs relative paths. In TypeScript you reach another file’s exports with a string path like `import { x } from "../utils/math"`. Rust has no such file-path strings in its source: instead, everything you can name lives in a single **module tree**, and you address items with `::`-separated **paths** rooted in that tree. This file is about how to write those paths — `crate::`, `super::`, `self::`, and the absolute-versus-relative choice. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A Rust crate is one big tree of modules, with the crate root (`src/main.rs` or `src/lib.rs`) as the trunk. Every function, struct, constant, and submodule has a **path** through that tree, written with `::` between segments — the way `/` separates folders in a TypeScript import. The key skill is choosing between an **absolute path** (starts at `crate::`) and a **relative path** (starts at `self::`, `super::`, or a name in the current module), and knowing what each `::` segment means. > **Note:** This file covers *how to write paths*. The mechanics of declaring modules (`mod`, inline vs file-based) live in [Modules](/12-modules-packages/00-modules/), bringing paths into scope with `use` lives in [The `use` Keyword](/12-modules-packages/02-use-keyword/), and making items reachable with `pub` lives in [Visibility and the `pub` Keyword](/12-modules-packages/03-pub-visibility/). You will see all three here in passing because paths only resolve to *visible* items. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In a TypeScript project, you locate code in *other files* with a string path, and code in the *same file* just by name. The string is relative to the current file’s location on disk. src/store/checkout.ts ```typescript 1 // Relative path: "../" walks up one directory on disk, "./" stays here. 2 import { TAX_RATE } from "../store/config"; 3 import { findItem } from "./inventory"; 4 5 // Bare specifier (no "./" or "../"): resolved from node_modules — an external package. 6 import { randomUUID } from "crypto"; 7 8 export function total(itemName: string): number { 9 const item = findItem(itemName); 10 return item.price * (1 + TAX_RATE); 11 } 12 13 export function describe(itemName: string): string { 14 // Something defined in THIS file is referenced by bare name. 15 const cost = total(itemName); 16 return `${itemName} costs $${cost.toFixed(2)} (receipt ${randomUUID()})`; 17 } ``` **Key points:** * `./` and `../` are **relative to the file on disk**. * A bare specifier (`"crypto"`, `"lodash"`) means “look in `node_modules`”: an external package. * Same-file references need no path at all, just the identifier. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust expresses the same relationships, but the “coordinates” are positions in the **module tree**, not directories on disk. The separator is `::`, not `/`. ```rust 1 mod store { 2 // A constant living at `crate::store::TAX_RATE`. 3 pub const TAX_RATE: f64 = 0.08; 4 5 pub mod inventory { 6 #[derive(Debug)] 7 pub struct Item { 8 pub name: String, 9 pub price: f64, 10 } 11 12 pub fn find(name: &str) -> Item { 13 Item { name: name.to_string(), price: 9.99 } 14 } 15 } 16 17 pub mod checkout { 18 // RELATIVE path: `inventory` is a sibling of `checkout` under `store`, 19 // so we go up one level with `super::`. 20 use super::inventory::{self, Item}; 21 22 // ABSOLUTE path: starts at the crate root with `crate::`. 23 use crate::store::TAX_RATE; 24 25 pub fn describe(item_name: &str) -> String { 26 let item: Item = inventory::find(item_name); 27 let cost = item.price * (1.0 + TAX_RATE); 28 format!("{} costs ${:.2} with tax", item.name, cost) 29 } 30 } 31 } 32 33 // At the crate root we reach into the tree with an absolute path. 34 use crate::store::checkout; 35 36 fn main() { 37 println!("{}", checkout::describe("Coffee Mug")); 38 // A fully-qualified absolute path also works inline: 39 println!("Tax rate: {}", crate::store::TAX_RATE); 40 } ``` **Real output** (compiled and run with `cargo run`): ```text 1 Coffee Mug costs $10.79 with tax 2 Tax rate: 0.08 ``` **Key points:** * `crate::` is the absolute root, like an import path anchored at the project root. * `super::` is “go up one parent module,” the rough analog of `../`, but it climbs the *module* tree, not the *directory* tree. * `self::` is “the current module” — the rough analog of `./`. * Items in the same module are reachable by bare name, just like same-file references in TypeScript. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The module tree, and what a “path” addresses [Section titled “The module tree, and what a “path” addresses”](#the-module-tree-and-what-a-path-addresses) Every crate has exactly one **crate root**: `src/main.rs` for a binary, `src/lib.rs` for a library. That root *is* the module named `crate`. Everything declared inside it, and inside its submodules, forms a tree: ```text 1 crate 2 └── store 3 ├── TAX_RATE (a constant) 4 ├── inventory 5 │ ├── Item (a struct) 6 │ └── find (a function) 7 └── checkout 8 └── describe (a function) ``` A **path** is the sequence of names you walk to reach a node, joined by `::`. The path to `find` from the crate root is `crate::store::inventory::find`. This is the direct counterpart of `store/inventory#find` — except the tree is built from `mod` declarations and `pub` visibility, **not** from the filesystem layout. (Files *do* map onto the tree, but that mapping is a separate topic; see [Modules](/12-modules-packages/00-modules/).) > **Tip:** Compared with TypeScript, the load-bearing difference is this: a TypeScript import path points at a *file*; a Rust path points at a *node in the module tree*. Renaming a file in TypeScript breaks the import string. In Rust, paths are stated in terms of module names, so moving code between files changes nothing as long as the module structure is preserved. ### Absolute paths: `crate::` [Section titled “Absolute paths: crate::”](#absolute-paths-crate) An **absolute path** starts at the crate root with the keyword `crate`, then walks down. It reads the same no matter which module you write it in: ```rust 1 mod store { 2 pub const TAX_RATE: f64 = 0.08; 3 pub mod checkout { 4 // Identical text would work from anywhere in this crate. 5 use crate::store::TAX_RATE; 6 pub fn rate() -> f64 { TAX_RATE } 7 } 8 } 9 10 fn main() { 11 println!("{}", store::checkout::rate()); // prints 0.08 12 } ``` `crate` is *this crate’s* root specifically. To name an **external** crate, you use its name as the first segment instead (`std::collections::HashMap`, `serde::Serialize`). You can force “this is an external crate, not a local module” by prefixing a leading `::`: ```rust 1 fn main() { 2 // Leading `::` forces the path to start at the EXTERNAL crate root — 3 // the crate named `rand`, never a local module that happens to be `rand`. 4 let n: u8 = ::rand::random(); 5 println!("got a byte: {n}"); 6 } ``` This compiles and runs against `rand` 0.9 (`rand::random()` is the current idiom; the old `rand::thread_rng().gen()` from 0.8 is gone). The leading `::` is rarely needed in everyday code, but it disambiguates when a local module shadows a crate name. ### Relative paths: `self::` and `super::` [Section titled “Relative paths: self:: and super::”](#relative-paths-self-and-super) A **relative path** starts from where you are: * `self::` means “starting in the current module.” `self::total` is the `total` function declared alongside the caller. * `super::` means “starting in the parent module.” Each `super::` climbs one level toward the root. This is the closest thing Rust has to `../`. ```rust 1 fn deliver_order() {} 2 3 mod back_of_house { 4 fn fix_incorrect_order() { 5 cook_order(); 6 // `super::` goes up to the crate root (the parent of `back_of_house`), 7 // where `deliver_order` lives. 8 super::deliver_order(); 9 } 10 11 fn cook_order() {} 12 13 pub mod prep { 14 pub fn season() { 15 // Two levels up: prep -> back_of_house -> crate root. 16 super::super::deliver_order(); 17 } 18 } 19 } 20 21 fn main() { 22 back_of_house::prep::season(); 23 println!("seasoned and delivered"); 24 } ``` **Real output:** ```text 1 seasoned and delivered ``` Note `super::super::` to climb two levels. There is no `super::super::super::...` shorthand — you repeat `super::` once per level, which is exactly why deep trees usually read more clearly with an absolute `crate::` path. ### Bare names: items in the current module [Section titled “Bare names: items in the current module”](#bare-names-items-in-the-current-module) If an item lives in the *same* module (or has been brought into scope with `use`), you name it directly with no prefix, exactly like referencing a same-file function in TypeScript. `self::` is optional in front of a same-module item; you only *need* it to disambiguate when a name has been imported that would otherwise win: ```rust 1 mod metrics { 2 pub fn record(event: &str) { 3 println!("recorded: {event}"); 4 } 5 } 6 7 mod handler { 8 // Bring the crate-level `metrics` into scope. 9 use crate::metrics; 10 11 pub fn handle() { 12 self::log("request received"); // `self::` makes "local" explicit 13 metrics::record("request"); // the imported `crate::metrics` 14 } 15 16 fn log(msg: &str) { 17 println!("[handler] {msg}"); 18 } 19 } 20 21 fn main() { 22 handler::handle(); 23 } ``` **Real output:** ```text 1 [handler] request received 2 recorded: request ``` ### Paths span files unchanged [Section titled “Paths span files unchanged”](#paths-span-files-unchanged) Because paths are module-tree coordinates, splitting a crate across files does not change a single path. Here is the same idea in a four-file crate (`mod foo;` tells the compiler “the module `foo` lives in another file” — covered in [Modules](/12-modules-packages/00-modules/)): src/main.rs ```rust 1 mod config; 2 mod auth; 3 4 fn main() { 5 let token = auth::login("alice", "hunter2"); 6 println!("issued token: {token}"); 7 println!("base url: {}", config::base_url()); 8 } ``` src/config.rs ```rust 1 pub fn base_url() -> &'static str { 2 "https://api.example.com" 3 } 4 5 pub const SESSION_SECONDS: u64 = 3600; ``` src/auth.rs ```rust 1 mod session; 2 3 pub fn login(user: &str, _password: &str) -> String { 4 // `session` is a child module of `auth` (lives in src/auth/session.rs). 5 session::issue(user) 6 } ``` src/auth/session.rs ```rust 1 // ABSOLUTE path from the crate root, crossing back up the tree: 2 use crate::config::SESSION_SECONDS; 3 4 pub fn issue(user: &str) -> String { 5 format!("{user}:valid-for-{SESSION_SECONDS}s") 6 } ``` **Real output:** ```text 1 issued token: alice:valid-for-3600s 2 base url: https://api.example.com ``` `crate::config::SESSION_SECONDS` is written from deep inside `src/auth/session.rs`, yet the path knows nothing about directories — it is purely the tree position of `config`. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / JavaScript | Rust | | --------------------- | -------------------------------------------- | -------------------------------------------------- | | What a path points at | A **file** on disk | A **node in the module tree** | | Separator | `/` in the import string | `::` in source | | Absolute root | Anchored at project/`node_modules` config | `crate::` (this crate) or a crate name | | Go up a level | `../` (one directory) | `super::` (one parent module) | | Stay here | `./` (same directory) | `self::` (same module) | | Same scope | Bare identifier (same file) | Bare identifier (same module) | | External package | Bare specifier (`"lodash"`) → `node_modules` | Crate name first segment (`rand::`), or `::rand::` | | Survives file moves? | No: string breaks | Yes: path is tree-based, not file-based | ### Why a module tree instead of file paths? [Section titled “Why a module tree instead of file paths?”](#why-a-module-tree-instead-of-file-paths) TypeScript resolves imports against the filesystem (plus `tsconfig` `paths` and bundler config). Rust deliberately decouples the *name* of an item from the *file* it sits in. Benefits a TypeScript developer feels immediately: 1. **No fragile relative strings.** You never write `../../../utils`; you write `crate::utils` or `super::utils`, which says *what you mean* in the tree. 2. **Visibility is part of addressing.** A path only resolves if every segment is visible from the caller (see [Visibility and the `pub` Keyword](/12-modules-packages/03-pub-visibility/)). There is no “it imported fine but the symbol is internal” surprise. 3. **Refactor-friendly.** Moving a function to a different file does not touch any path, as long as its module position is unchanged. ### `super::` is not exactly `../` [Section titled “super:: is not exactly ../”](#super-is-not-exactly-) `../` walks the *directory* containing the current file. `super::` walks the *parent module*. These usually coincide, but not always — a parent module can be inline (`mod foo { ... }`) with no directory of its own, and a single file can hold several nested modules. Always think “parent in the tree,” not “parent folder.” *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: A path segment is private [Section titled “Pitfall 1: A path segment is private”](#pitfall-1-a-path-segment-is-private) A path only works if **every** segment along it is visible. Forgetting `pub` on an intermediate module is the most common path failure for newcomers. ```rust 1 mod front_of_house { 2 mod hosting { // not `pub` — invisible from outside 3 fn add_to_waitlist() {} // also not `pub` 4 } 5 } 6 7 fn main() { 8 // does not compile (error[E0603]: module `hosting` is private) 9 crate::front_of_house::hosting::add_to_waitlist(); 10 front_of_house::hosting::add_to_waitlist(); 11 } ``` **Real compiler error** (`cargo build`): ```text 1 error[E0603]: module `hosting` is private 2 --> src/main.rs:9:28 3 | 4 9 | crate::front_of_house::hosting::add_to_waitlist(); 5 | ^^^^^^^ --------------- function `add_to_waitlist` is not publicly re-exported 6 | | 7 | private module 8 | 9 note: the module `hosting` is defined here 10 --> src/main.rs:2:5 11 | 12 2 | mod hosting { 13 | ^^^^^^^^^^^ ``` The fix is to mark each segment you need to traverse with `pub` (here, `pub mod hosting` and `pub fn add_to_waitlist`). Note the error fires on the path itself, not the declaration: Rust checks visibility at the *use site*. Visibility rules in full are in [Visibility and the `pub` Keyword](/12-modules-packages/03-pub-visibility/). ### Pitfall 2: Writing a sibling name as if it were a child [Section titled “Pitfall 2: Writing a sibling name as if it were a child”](#pitfall-2-writing-a-sibling-name-as-if-it-were-a-child) Because TypeScript imports are filesystem-relative, it is tempting to assume a bare name refers to “anything in the crate.” It does not: a bare leading segment is resolved **relative to the current module**, so a top-level sibling module is *not* in scope by its bare name from inside another module. ```rust 1 mod network { 2 pub fn connect() {} 3 } 4 5 mod client { 6 pub fn run() { 7 // does not compile (error[E0433]): tries to find `network` 8 // as a child of `client`, but it is a sibling at the crate root. 9 network::connect(); 10 } 11 } 12 13 fn main() { 14 client::run(); 15 } ``` **Real compiler error:** ```text 1 error[E0433]: failed to resolve: use of unresolved module or unlinked crate `network` 2 --> src/main.rs:9:9 3 | 4 9 | network::connect(); 5 | ^^^^^^^ use of unresolved module or unlinked crate `network` 6 | 7 = help: if you wanted to use a crate named `network`, use `cargo add network` to add it to your `Cargo.toml` 8 help: consider importing this module 9 | 10 6 + use crate::network; 11 | ``` Fix with an absolute path (`crate::network::connect()`), a relative one (`super::network::connect()` since `network` is a sibling), or the `use crate::network;` the compiler suggests. ### Pitfall 3: Confusing `super::` levels with directory levels [Section titled “Pitfall 3: Confusing super:: levels with directory levels”](#pitfall-3-confusing-super-levels-with-directory-levels) ```rust 1 mod a { 2 pub mod b { 3 pub mod c { 4 pub fn deep() { 5 // c -> b -> a -> crate root is THREE supers, 6 // regardless of how the files are arranged on disk. 7 super::super::super::top(); 8 } 9 } 10 } 11 } 12 13 fn top() {} ``` Count parents in the **tree**, not folders. When the count climbs past two, prefer an absolute `crate::` path; it is both shorter and immune to later re-nesting. ### Pitfall 4: Expecting `self` to mean “this crate” [Section titled “Pitfall 4: Expecting self to mean “this crate””](#pitfall-4-expecting-self-to-mean-this-crate) In TypeScript there is no single keyword for “the package root”; you reach for `./` or a configured alias. In Rust, `self::` means **this module**, and `crate::` means **this crate’s root**; they are not interchangeable. Using `self::` where you meant `crate::` will look for the item one level too shallow and fail to resolve. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Prefer absolute `crate::` paths for distant items [Section titled “Prefer absolute crate:: paths for distant items”](#prefer-absolute-crate-paths-for-distant-items) The Rust community leans toward absolute paths for anything not in the immediate neighborhood, because the path stays correct when the *caller* later moves. Use relative `super::`/`self::` for tightly coupled items that you expect to move together. ```rust 1 // Good: distant item, absolute path is stable. 2 use crate::store::TAX_RATE; 3 4 // Good: closely-related sibling, relative path documents the coupling. 5 use super::inventory; ``` ### Resolve a path once with `use`, then use the short name [Section titled “Resolve a path once with use, then use the short name”](#resolve-a-path-once-with-use-then-use-the-short-name) A long path repeated inline is noise. Bring it into scope once with `use` (see [The `use` Keyword](/12-modules-packages/02-use-keyword/)) and call it by the short name afterward. The path-resolution rules in this file are exactly what `use` is built on. ```rust 1 use crate::store::inventory::Item; // resolve the path once 2 // ... then write `Item` everywhere instead of the full path. ``` ### Reach for `self::` only when you must disambiguate [Section titled “Reach for self:: only when you must disambiguate”](#reach-for-self-only-when-you-must-disambiguate) A bare same-module name is the idiomatic default. Spell out `self::name` only when a `use` import would otherwise shadow it (as in the `metrics`/`handler` example above). Gratuitous `self::` prefixes add clutter without changing meaning. ### Let the compiler write the path for you [Section titled “Let the compiler write the path for you”](#let-the-compiler-write-the-path-for-you) When you get `E0433` or `E0603`, read the `help:` lines; Rust frequently prints the exact `use crate::...;` line to paste in. Running `cargo check` (see [Cargo Commands](/12-modules-packages/05-cargo-commands/)) on every save turns path mistakes into instant, well-explained feedback. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small order-processing pipeline laid out as a module tree, exercising absolute and relative paths together the way a real service would. `money` is a shared utility reached absolutely from anywhere; `catalog` and `orders` are siblings that talk to each other relatively; `receipt` is a child module of `orders`. ```rust 1 //! A tiny order-processing pipeline organized as a module tree. 2 3 mod money { 4 pub const CURRENCY: &str = "USD"; 5 6 pub fn format(cents: u64) -> String { 7 format!("{}.{:02} {}", cents / 100, cents % 100, CURRENCY) 8 } 9 } 10 11 mod catalog { 12 pub struct Product { 13 pub sku: &'static str, 14 pub price_cents: u64, 15 } 16 17 pub fn lookup(sku: &str) -> Option<Product> { 18 match sku { 19 "BOOK-01" => Some(Product { sku: "BOOK-01", price_cents: 1999 }), 20 "MUG-07" => Some(Product { sku: "MUG-07", price_cents: 1250 }), 21 _ => None, 22 } 23 } 24 } 25 26 mod orders { 27 // RELATIVE: `super::catalog` is a sibling of `orders`. 28 use super::catalog::{self, Product}; 29 30 pub mod receipt { 31 // ABSOLUTE: jump straight to `crate::money` regardless of nesting. 32 use crate::money; 33 34 pub fn line(sku: &str, price_cents: u64) -> String { 35 format!(" {sku:<8} {}", money::format(price_cents)) 36 } 37 } 38 39 pub fn checkout(skus: &[&str]) -> String { 40 let mut lines = String::from("RECEIPT\n"); 41 let mut total = 0; 42 43 for sku in skus { 44 if let Some(Product { sku, price_cents }) = catalog::lookup(sku) { 45 // `self::receipt` is a child of THIS module. 46 lines.push_str(&self::receipt::line(sku, price_cents)); 47 lines.push('\n'); 48 total += price_cents; 49 } 50 } 51 52 // Absolute path again, used inline. 53 lines.push_str(&format!(" TOTAL {}", crate::money::format(total))); 54 lines 55 } 56 } 57 58 fn main() { 59 let receipt = orders::checkout(&["BOOK-01", "MUG-07", "MISSING"]); 60 println!("{receipt}"); 61 } ``` **Real output:** ```text 1 RECEIPT 2 BOOK-01 19.99 USD 3 MUG-07 12.50 USD 4 TOTAL 32.49 USD ``` Notice how each path choice tells the reader something: `crate::money` signals “shared utility, lives far away and stays put,” while `super::catalog` and `self::receipt` document the local relationships inside `orders`. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Rust Book — Paths for Referring to an Item in the Module Tree](https://doc.rust-lang.org/book/ch07-03-paths-for-referring-to-an-item-in-the-module-tree.html) * [The Rust Reference — Paths](https://doc.rust-lang.org/reference/paths.html) * [Rust by Example — Modules: `super` and `self`](https://doc.rust-lang.org/rust-by-example/mod/super.html) ### Related sections in this guide [Section titled “Related sections in this guide”](#related-sections-in-this-guide) * [Modules: ES modules → `mod`](/12-modules-packages/00-modules/): how the tree is *built* (this file is about navigating it) * [The `use` keyword](/12-modules-packages/02-use-keyword/): resolve a path once and use the short name * [Visibility with `pub`](/12-modules-packages/03-pub-visibility/) — why a path segment may be unreachable * [Cargo and `Cargo.toml`](/12-modules-packages/04-cargo/): where the crate (the root of `crate::`) is defined * [Cargo commands](/12-modules-packages/05-cargo-commands/): `cargo check` for instant path feedback * [Variables and Mutability](/02-basics/00-variables/): `const` items (like `TAX_RATE`) live on the tree too * [Functions](/03-functions/) — the items you most often address by path * [Testing](/13-testing/): `#[cfg(test)] mod tests` is itself a child module reached with `super::*` *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Make the paths resolve [Section titled “Exercise 1: Make the paths resolve”](#exercise-1-make-the-paths-resolve) **Difficulty:** Easy **Objective:** Practice marking every segment of a path visible so both an absolute and a relative call compile. **Instructions:** This program does not compile because the module and function are private. Add the minimum `pub` keywords so both calls in `main` work. Do not change the call sites. ```rust 1 mod garden { 2 mod vegetables { 3 fn plant() -> &'static str { 4 "planted a carrot" 5 } 6 } 7 } 8 9 fn main() { 10 // Absolute path 11 println!("{}", crate::garden::vegetables::plant()); 12 // Relative path 13 println!("{}", garden::vegetables::plant()); 14 } ``` Solution Each traversed segment needs `pub`: the inner module and the function (the outer `garden` is reachable from the crate root because `main` is also at the root, so it does not strictly need `pub` for these two calls, but `vegetables` and `plant` do). ```rust 1 mod garden { 2 pub mod vegetables { 3 pub fn plant() -> &'static str { 4 "planted a carrot" 5 } 6 } 7 } 8 9 fn main() { 10 // Absolute path 11 println!("{}", crate::garden::vegetables::plant()); 12 // Relative path 13 println!("{}", garden::vegetables::plant()); 14 } ``` **Output:** ```text 1 planted a carrot 2 planted a carrot ``` ### Exercise 2: Reach a parent’s sibling with `super::` [Section titled “Exercise 2: Reach a parent’s sibling with super::”](#exercise-2-reach-a-parents-sibling-with-super) **Difficulty:** Medium **Objective:** Use a relative path to call a function that lives in the parent module. **Instructions:** Implement `ui::header` so it returns `"MyApp v1.0.0"` by calling `version()`, which lives in the *parent* module `app`. Use a relative path (`super::`), not an absolute one. ```rust 1 mod app { 2 pub fn version() -> &'static str { 3 "1.0.0" 4 } 5 6 pub mod ui { 7 pub fn header() -> String { 8 // TODO: build "MyApp v1.0.0" by calling the parent's `version()` 9 todo!() 10 } 11 } 12 } 13 14 fn main() { 15 println!("{}", app::ui::header()); 16 } ``` Solution ```rust 1 mod app { 2 pub fn version() -> &'static str { 3 "1.0.0" 4 } 5 6 pub mod ui { 7 pub fn header() -> String { 8 // Reach the sibling-of-parent `version` with `super::`. 9 format!("MyApp v{}", super::version()) 10 } 11 } 12 } 13 14 fn main() { 15 println!("{}", app::ui::header()); 16 } ``` **Output:** ```text 1 MyApp v1.0.0 ``` ### Exercise 3: Call across a deep tree two ways [Section titled “Exercise 3: Call across a deep tree two ways”](#exercise-3-call-across-a-deep-tree-two-ways) **Difficulty:** Hard **Objective:** Reach a top-level utility from deep inside the tree, first with an absolute path and then with the equivalent relative path, and decide which reads better. **Instructions:** Inside `service::worker::task::run`, log two lines using `crate::logging::write`. Make the **first** call with an absolute `crate::` path and the **second** call with the fully relative `super::super::super::` path so they target the same function. The program should print both log lines. ```rust 1 mod logging { 2 pub fn write(line: &str) { 3 println!("LOG: {line}"); 4 } 5 } 6 7 mod service { 8 pub mod worker { 9 pub mod task { 10 pub fn run() { 11 // TODO: log "task started" via an absolute path 12 // TODO: log "task finished" via the relative super::super::super:: path 13 } 14 } 15 } 16 } 17 18 fn main() { 19 service::worker::task::run(); 20 } ``` Solution ```rust 1 mod logging { 2 pub fn write(line: &str) { 3 println!("LOG: {line}"); 4 } 5 } 6 7 mod service { 8 pub mod worker { 9 pub mod task { 10 // Absolute path brought into scope once — clearest from deep inside. 11 use crate::logging; 12 13 pub fn run() { 14 logging::write("task started"); 15 // The relative equivalent: task -> worker -> service -> crate root. 16 super::super::super::logging::write("task finished"); 17 } 18 } 19 } 20 } 21 22 fn main() { 23 service::worker::task::run(); 24 } ``` **Output:** ```text 1 LOG: task started 2 LOG: task finished ``` Both reach the same `crate::logging::write`. At this depth the absolute `crate::` form (or a `use`) is far more readable than three stacked `super::`, and it survives later re-nesting of `task` — which is why absolute paths are the idiomatic default for distant items. # The `use` Keyword: Bringing Items Into Scope > use brings a path into scope as a short alias, like a JavaScript import, but loads nothing and runs no code. Covers pub use re-exports, as renaming, and globs. In TypeScript/JavaScript you reach for another file’s exports with `import`. In Rust the equivalent is `use`, but with an important twist: `use` does **not** load or run anything, it only creates a **shorter local name** for a path that is already part of your crate’s module tree. This page covers bringing items into scope, re-exporting with `pub use`, renaming with `as`, and glob imports. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) The `use` keyword brings a path into the current scope so you can refer to it by a short name instead of writing the full path every time. Unlike a JavaScript `import`, `use` performs **no file loading and no side effects**. Modules are wired together separately (with `mod`, covered in [Modules](/12-modules-packages/00-modules/)), and `use` is purely a convenience alias. Mastering `use`, `pub use`, and `as` is what makes a Rust crate pleasant to consume. **In short:** `import` ≈ `use`, but `use` is just an *alias for a path*: it never executes code and never decides what gets compiled. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) services/users.ts ```typescript 1 export interface User { 2 id: number; 3 name: string; 4 } 5 6 export function findUser(id: number): User { 7 return { id, name: "Ada" }; 8 } 9 10 export function createUser(name: string): User { 11 return { id: Date.now(), name }; 12 } ``` ```typescript 1 // app.ts — pulling those exports into scope 2 import { User, findUser } from "./services/users"; 3 4 // Rename on import to avoid a clash with a local `createUser` 5 import { createUser as createDbUser } from "./services/users"; 6 7 // Namespace (glob) import: everything under one object 8 import * as users from "./services/users"; 9 10 // Re-export so consumers of THIS module can import from here 11 export { User } from "./services/users"; 12 13 const a: User = findUser(1); 14 const b = createDbUser("Grace"); 15 const c = users.findUser(2); 16 17 console.log(a); // { id: 1, name: 'Ada' } 18 console.log(b); // { id: <timestamp>, name: 'Grace' } 19 console.log(c); // { id: 2, name: 'Ada' } ``` **Key points:** * `import { x }` brings a named export into scope. * `import { x as y }` renames on the way in. * `import * as ns` is a namespace (glob) import. * `export { x } from "..."` re-exports: it forwards another module’s export through yours. * Each `import` of a module **runs that module’s top-level code** the first time it is evaluated. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 // src/services/users.rs (a module — see modules.md for how `mod` wires this in) 2 #[derive(Debug)] 3 pub struct User { 4 pub id: u32, 5 pub name: String, 6 } 7 8 pub fn find_user(id: u32) -> User { 9 User { id, name: "Ada".to_string() } 10 } 11 12 pub fn create_user(name: &str) -> User { 13 User { id: 999, name: name.to_string() } 14 } ``` src/main.rs ```rust 1 mod services; // declares the module tree; `use` below only makes names shorter 2 3 // Bring named items into scope (like `import { User, find_user }`) 4 use services::users::{User, find_user}; 5 6 // Rename with `as` (like `import { create_user as create_db_user }`) 7 use services::users::create_user as create_db_user; 8 9 fn main() { 10 let a: User = find_user(1); 11 let b = create_db_user("Grace"); 12 println!("{a:?}"); // User { id: 1, name: "Ada" } 13 println!("{b:?}"); // User { id: 999, name: "Grace" } 14 } ``` **Key points:** * `use path::{A, B}` brings several names into scope from one path (like a named import list). * `use path::Item as Alias` renames, exactly like `import { Item as Alias }`. * `use` is just an alias: writing the full path `services::users::find_user(1)` would work without any `use` at all. * There is **no namespace-object import** like `import * as users`. The closest thing, `use services::users;`, brings the *module name* into scope so you can write `users::find_user(...)`, but `users` is a path segment, not a runtime object you can pass around. > **Note:** `use` and `mod` are different jobs. `mod services;` is what actually attaches `services/users.rs` to your crate’s module tree (and the file is compiled because it is *reachable*, not because something imported it). `use` only shortens the name. See [Modules](/12-modules-packages/00-modules/) and [Paths in the Module Tree](/12-modules-packages/01-module-tree/). *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `use` is an alias, not a loader [Section titled “use is an alias, not a loader”](#use-is-an-alias-not-a-loader) This is the single most important mental-model shift. In JavaScript, `import "./logger"` can have **side effects**: the first time the module is evaluated, its top-level code runs (it might register a global, open a connection, etc.). Tree-shaking aside, the import drives what gets included. In Rust, **what gets compiled is decided by `mod`** (reachability in the module tree), not by `use`. A `use` line is closer to a TypeScript `type` alias or a local `const Foo = SomeNamespace.Foo`; it just gives you a shorter handle. Removing a `use` never changes *whether* code is compiled; it only forces you to spell out the full path. ```rust 1 // These two are exactly equivalent in behavior: 2 use std::collections::HashMap; 3 let m: HashMap<String, u32> = HashMap::new(); 4 5 // ...vs writing the full path inline, with no `use` at all: 6 let m: std::collections::HashMap<String, u32> = std::collections::HashMap::new(); ``` ### Bringing items into scope [Section titled “Bringing items into scope”](#bringing-items-into-scope) A real example using two standard-library types: ```rust 1 use std::collections::HashMap; 2 use std::collections::HashSet; 3 4 fn main() { 5 let mut scores: HashMap<String, u32> = HashMap::new(); 6 scores.insert("Alice".to_string(), 10); 7 scores.insert("Bob".to_string(), 7); 8 9 let mut seen: HashSet<&str> = HashSet::new(); 10 seen.insert("a"); 11 seen.insert("a"); 12 13 println!("{:?}", scores.get("Alice")); 14 println!("unique = {}", seen.len()); 15 } ``` **Output (verified):** ```plaintext 1 Some(10) 2 unique = 1 ``` ### Nested paths and `self` [Section titled “Nested paths and self”](#nested-paths-and-self) When several `use` lines share a prefix, collapse them with braces. This is the idiomatic equivalent of a multi-name JavaScript import list: ```rust 1 // Instead of two lines sharing `std::collections::` 2 use std::collections::{HashMap, BTreeMap}; 3 4 // `self` inside the braces means "the module itself", so you get BOTH 5 // the `io` module name AND the `Write` trait in one line: 6 use std::io::{self, Write}; 7 // ^^^^ brings `io` into scope (so you can write `io::stdout()`) 8 // ^^^^^ brings the `Write` trait into scope ``` ### Renaming with `as` [Section titled “Renaming with as”](#renaming-with-as) `as` exists for the same reason as JavaScript’s `import { x as y }`: avoiding name collisions. The classic case is two different `Result` types: ```rust 1 use std::fmt::Result as FmtResult; 2 use std::io::Result as IoResult; 3 4 fn make_fmt_result() -> FmtResult { Ok(()) } 5 fn make_io_result() -> IoResult<()> { Ok(()) } ``` There is also a special form, `as _`, which brings a **trait** into scope so you can call its methods, *without* binding a usable name. This is handy when you only need the trait’s methods and want to avoid a name clash entirely: ```rust 1 use std::fmt::Write as _; // `write!` on a String works; the name `Write` stays unbound ``` ### Glob imports (`*`) [Section titled “Glob imports (\*)”](#glob-imports-) The `*` glob brings **everything public** from a path into scope, like `import * as ns` but flattened directly into your namespace (no `ns.` prefix): ```rust 1 use std::collections::*; // HashMap, BTreeMap, HashSet, VecDeque, ... ``` Globs are discouraged in everyday code because they hide *where* a name came from, but they are idiomatic in exactly two places: 1. **Test modules:** `use super::*;` to pull the module under test into the test scope (see [Testing](/13-testing/)). 2. **Preludes:** `use some_crate::prelude::*;` to grab a crate’s curated “starter set” of items. ### Re-exporting with `pub use` [Section titled “Re-exporting with pub use”](#re-exporting-with-pub-use) A plain `use` is private to its module. A `pub use` re-exports the name, making it part of *your* module’s public surface, exactly like `export { x } from "./other"` in TypeScript. This is the foundation of the **facade pattern**: organize code into deep modules internally, but expose a flat, friendly public path. src/models/mod.rs ```rust 1 pub mod user; 2 pub mod order; 3 4 // Re-export the most-used types one level up, so callers can write 5 // `models::User` instead of the longer `models::user::User`. 6 pub use user::User; 7 pub use order::Order; ``` src/main.rs ```rust 1 mod models; 2 3 // Thanks to `pub use`, the short, flat path works: 4 use models::{User, Order}; 5 6 fn main() { 7 let u = User { id: 1, name: "Ada".to_string() }; 8 let o = Order { id: 42, total_cents: 1999 }; 9 println!("{u:?}"); 10 println!("{o:?}"); 11 } ``` **Output (verified):** ```plaintext 1 User { id: 1, name: "Ada" } 2 Order { id: 42, total_cents: 1999 } ``` > **Tip:** `pub use` is how published crates give you ergonomic imports. When you write `use serde::{Serialize, Deserialize}`, those names are re-exported by `serde` from deeper internal modules. You never have to know where they actually live. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript | Rust | | ----------------------------- | ------------------------------- | -------------------------------------------- | | Bring item into scope | `import { x } from "./m"` | `use m::x;` | | Rename | `import { x as y }` | `use m::x as y;` | | Import many | `import { a, b, c }` | `use m::{a, b, c};` | | Namespace import | `import * as m` (real object) | `use m;` then `m::x` (path, not object) | | Glob into scope | (no direct equivalent) | `use m::*;` | | Re-export | `export { x } from "./m"` | `pub use m::x;` | | Side effects on import | Yes: top-level code runs | None: `use` never executes code | | Decides what’s compiled | Yes (with bundler/tree-shaking) | No: `mod` + reachability does | | Default visibility of imports | export must be explicit | a plain `use` is private; `pub use` to share | ### Why `use` is “just an alias” [Section titled “Why use is “just an alias””](#why-use-is-just-an-alias) Rust separates two concerns that JavaScript blends into `import`: 1. **“Does this code exist in my program?”** → answered by `mod` and reachability. 2. **“What short name do I type to reach it?”** → answered by `use`. Because of this split, the standard library is always available *without* any dependency declaration: `use std::collections::HashMap;` works in any project. The `std` crate is implicitly linked; `use` just names a path inside it. (Contrast with Node, where even built-ins like `node:fs` must be imported to be referenced.) ### The prelude: why some things need no `use` [Section titled “The prelude: why some things need no use”](#the-prelude-why-some-things-need-no-use) You can call `Vec::new()`, `String::from(...)`, use `Option`, `Result`, `Box`, and `println!` without ever importing them. That is because Rust automatically brings the **standard prelude** into every module; conceptually `use std::prelude::rust_2024::*;` is injected for you. Everything else needs an explicit `use` or a full path. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Calling a trait method without importing the trait [Section titled “Pitfall 1: Calling a trait method without importing the trait”](#pitfall-1-calling-a-trait-method-without-importing-the-trait) This is the number-one `use`-related surprise for newcomers. In Rust, a method that comes from a **trait** is only callable when that trait is **in scope**. The data type can be right there, the method can be implemented, and it *still* won’t resolve. ```rust 1 fn main() { 2 let mut buf: Vec<u8> = Vec::new(); 3 buf.write_all(b"log line\n").unwrap(); // does not compile (error[E0599]) 4 println!("wrote {} bytes", buf.len()); 5 } ``` **Compiler error (abridged):** ```plaintext 1 error[E0599]: no method named `write_all` found for struct `Vec<u8>` in the current scope 2 --> src/main.rs:3:9 3 | 4 3 | buf.write_all(b"log line\n").unwrap(); // does not compile (error[E0599]) 5 | ^^^^^^^^^ 6 | 7 ::: .../library/std/src/io/mod.rs:1835:8 8 | 9 1835 | fn write_all(&mut self, mut buf: &[u8]) -> Result<()> { 10 | --------- the method is available for `Vec<u8>` here 11 | 12 = help: items from traits can only be used if the trait is in scope 13 help: trait `Write` which provides `write_all` is implemented but not in scope; perhaps you want to import it 14 | 15 1 + use std::io::Write; 16 | 17 help: there is a method `write` with a similar name 18 | 19 3 - buf.write_all(b"log line\n").unwrap(); // does not compile (error[E0599]) 20 3 + buf.write(b"log line\n").unwrap(); // does not compile (error[E0599]) 21 | ``` **Fix:** bring the trait into scope. The compiler even tells you which `use` line to add. ```rust 1 use std::io::Write; // needed for the `write_all` / `flush` methods 2 3 fn main() { 4 let mut buf: Vec<u8> = Vec::new(); 5 buf.write_all(b"log line\n").unwrap(); 6 buf.flush().unwrap(); 7 println!("wrote {} bytes", buf.len()); 8 } ``` **Output (verified):** `wrote 9 bytes` > **Note:** This has no TypeScript analogue. In TS, methods belong to the object’s type; in Rust, trait methods are gated on the trait being imported. When a method “should exist but doesn’t,” the missing `use` for a trait is the usual culprit. ### Pitfall 2: Two imports with the same name [Section titled “Pitfall 2: Two imports with the same name”](#pitfall-2-two-imports-with-the-same-name) Importing two items that share a final name is a hard error. Rust will not silently shadow one with the other. ```rust 1 use std::fmt::Result; 2 use std::io::Result; // does not compile (error[E0252]) ``` **Compiler error (abridged — two trailing `unused import` warnings omitted):** ```plaintext 1 error[E0252]: the name `Result` is defined multiple times 2 --> src/main.rs:2:5 3 | 4 1 | use std::fmt::Result; 5 | ---------------- previous import of the type `Result` here 6 2 | use std::io::Result; // does not compile (error[E0252]) 7 | ^^^^^^^^^^^^^^^ `Result` reimported here 8 | 9 = note: `Result` must be defined only once in the type namespace of this module 10 help: you can use `as` to change the binding name of the import 11 | 12 2 | use std::io::Result as OtherResult; // does not compile (error[E0252]) 13 | ++++++++++++++ ``` **Fix:** rename one (or both) with `as`, exactly as the compiler suggests: ```rust 1 use std::fmt::Result as FmtResult; 2 use std::io::Result as IoResult; ``` ### Pitfall 3: Expecting `use` to “load” or run a file [Section titled “Pitfall 3: Expecting use to “load” or run a file”](#pitfall-3-expecting-use-to-load-or-run-a-file) Coming from JavaScript, it is tempting to think `use crate::logger;` will execute `logger`’s setup code or “include” the file. It does neither. If your module isn’t part of the tree (declared with `mod`), no `use` will conjure it into existence: you’ll get an “unresolved import” error. Wiring files in is the `mod` keyword’s job; see [Modules](/12-modules-packages/00-modules/). ### Pitfall 4: Reaching for glob imports everywhere [Section titled “Pitfall 4: Reaching for glob imports everywhere”](#pitfall-4-reaching-for-glob-imports-everywhere) `use foo::*;` feels familiar (it looks like a barrel import), but in normal code it makes review harder. A reader can no longer tell where `Widget` came from, and adding an item to `foo` can suddenly collide with a local name. Reserve globs for preludes and test modules (Best Practices below). *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Group imports and let the formatter organize them [Section titled “1. Group imports and let the formatter organize them”](#1-group-imports-and-let-the-formatter-organize-them) `rustfmt` (run via `cargo fmt`, see [Cargo Commands](/12-modules-packages/05-cargo-commands/)) sorts and merges `use` lines for you. The conventional grouping is: standard library, then external crates, then your own crate. ```rust 1 // Standard library 2 use std::collections::HashMap; 3 use std::fmt; 4 5 // External crates 6 use serde::{Deserialize, Serialize}; 7 8 // This crate 9 use crate::models::User; ``` ### 2. Prefer explicit names over globs [Section titled “2. Prefer explicit names over globs”](#2-prefer-explicit-names-over-globs) ```rust 1 // Clear where each name comes from 2 use std::collections::{HashMap, HashSet}; 3 4 // Hides origins; reserve for preludes/tests 5 use std::collections::*; ``` ### 3. Import the parent module for functions, the item itself for types [Section titled “3. Import the parent module for functions, the item itself for types”](#3-import-the-parent-module-for-functions-the-item-itself-for-types) Idiomatic Rust often imports the **module** for free functions (so call sites read `io::stdout()`, signaling origin) but imports **types/traits directly** (so you write `HashMap`, not `collections::HashMap`). ```rust 1 use std::io::{self, Write}; // call `io::stdout()`, but `Write` used bare ``` ### 4. Build a facade with `pub use` [Section titled “4. Build a facade with pub use”](#4-build-a-facade-with-pub-use) Keep your internal module layout free to evolve while presenting a stable, flat public API: src/lib.rs ```rust 1 mod parser; // internal modules can be reorganized freely 2 mod renderer; 3 4 pub use parser::parse; // public callers see `your_crate::parse` 5 pub use renderer::Renderer; // and `your_crate::Renderer` ``` This is exactly how mature crates expose their API; visibility rules behind it are covered in [Visibility and the `pub` Keyword](/12-modules-packages/03-pub-visibility/). ### 5. Use `as _` to import a trait you only call methods on [Section titled “5. Use as \_ to import a trait you only call methods on”](#5-use-as-_-to-import-a-trait-you-only-call-methods-on) When you need a trait’s methods but never name the trait, `use Trait as _;` keeps the trait out of the namespace and silences “unused import” pedantry while still enabling the methods. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored pattern: a crate organizes its domain types across modules but offers a **prelude** that callers pull in with one glob. This mirrors how `tokio`, `rayon`, and many others ship a `prelude`. ```rust 1 mod domain { 2 #[derive(Debug, Clone)] 3 pub struct Money { pub cents: i64 } 4 5 impl Money { 6 pub fn dollars(d: i64) -> Self { Money { cents: d * 100 } } 7 } 8 9 #[derive(Debug)] 10 pub struct Invoice { 11 pub id: u32, 12 pub amount: Money, 13 } 14 15 pub trait Summarize { 16 fn summary(&self) -> String; 17 } 18 19 impl Summarize for Invoice { 20 fn summary(&self) -> String { 21 format!( 22 "Invoice #{} for ${}.{:02}", 23 self.id, 24 self.amount.cents / 100, 25 self.amount.cents % 100 26 ) 27 } 28 } 29 } 30 31 // A `prelude` gathers the items most callers want behind one path. 32 mod prelude { 33 pub use crate::domain::{Invoice, Money, Summarize}; 34 } 35 36 // One glob import pulls in the whole curated prelude. 37 use prelude::*; 38 39 fn main() { 40 let invoice = Invoice { id: 7, amount: Money::dollars(42) }; 41 // `summary()` only resolves because `Summarize` is in scope via the prelude. 42 println!("{}", invoice.summary()); 43 } ``` **Output (verified):** ```plaintext 1 Invoice #7 for $42.00 ``` **Why this is good design:** * Internal layout (`domain`) can be split, renamed, or reorganized without breaking callers; only `prelude` is the public contract. * The `Summarize` trait being re-exported is essential: without it in scope, `invoice.summary()` would hit the E0599 error from Pitfall 1. * Callers opt into one glob (`use crate::prelude::*;`) instead of memorizing a dozen paths: the legitimate, intentional use of `*`. A realistic external-crate example, using `serde` (see [Specifying Dependencies](/12-modules-packages/06-dependencies/) for adding it): ```rust 1 // Bring traits + derive macros into scope from an external crate. 2 use serde::{Deserialize, Serialize}; 3 use std::collections::HashMap; 4 5 #[derive(Debug, Serialize, Deserialize)] 6 struct ServiceConfig { 7 name: String, 8 port: u16, 9 #[serde(default)] 10 env: HashMap<String, String>, 11 } 12 13 fn main() { 14 let raw = r#"{ "name": "api", "port": 8080, "env": { "LOG": "info" } }"#; 15 let cfg: ServiceConfig = serde_json::from_str(raw).expect("valid config"); 16 println!("{} listening on :{}", cfg.name, cfg.port); 17 println!("env = {:?}", cfg.env); 18 19 let back = serde_json::to_string(&cfg).unwrap(); 20 println!("{back}"); 21 } ``` **Output (verified):** ```plaintext 1 api listening on :8080 2 env = {"LOG": "info"} 3 {"name":"api","port":8080,"env":{"LOG":"info"}} ``` Notice that `serde_json::from_str` is called by its full path with no `use`. `use` is optional, and for a one-off call the qualified path can be clearer. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Bringing Paths into Scope with `use`](https://doc.rust-lang.org/book/ch07-04-bringing-paths-into-scope-with-the-use-keyword.html) * [The Rust Book — Re-exporting Names with `pub use`](https://doc.rust-lang.org/book/ch07-04-bringing-paths-into-scope-with-the-use-keyword.html#re-exporting-names-with-pub-use) * [Rust Reference — Use declarations](https://doc.rust-lang.org/reference/items/use-declarations.html) * [Rust by Example — `use` declaration](https://doc.rust-lang.org/rust-by-example/mod/use.html) * [`std::prelude` documentation](https://doc.rust-lang.org/std/prelude/index.html) ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Modules: ES modules → `mod`](/12-modules-packages/00-modules/) — how files get attached to the module tree (the `mod` half of the story). * [Module Tree & Paths](/12-modules-packages/01-module-tree/) — `crate::`, `super::`, `self::`, absolute vs relative paths used by `use`. * [Visibility with `pub`](/12-modules-packages/03-pub-visibility/) — why a plain `use` is private and how `pub use` exposes it; `pub(crate)`/`pub(super)`. * [Dependencies](/12-modules-packages/06-dependencies/) — adding external crates so you have something to `use`. * [Cargo commands](/12-modules-packages/05-cargo-commands/) — `cargo fmt` (organizes imports), `cargo clippy`. * [Section 13: Testing](/13-testing/) — where `use super::*;` is the idiomatic glob. * [Getting Started: Cargo Basics](/01-getting-started/03-cargo-basics/) and [Basics: Output](/02-basics/04-output/) — foundations referenced above. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Import the right things [Section titled “Exercise 1: Import the right things”](#exercise-1-import-the-right-things) **Difficulty:** Easy **Objective:** Practice bringing a type and a trait into scope. **Instructions:** This program counts letter frequencies and builds a small report string using the `write!` macro. It is missing its imports; add the two `use` lines so it compiles. (Hint: `write!` writing into a `String` needs a trait in scope.) ```rust 1 // TODO: add the necessary `use` lines 2 3 fn main() { 4 let mut counts: HashMap<char, u32> = HashMap::new(); 5 for c in "hello".chars() { 6 *counts.entry(c).or_insert(0) += 1; 7 } 8 9 let mut report = String::new(); 10 write!(report, "letters: {}", counts.len()).unwrap(); 11 println!("{report}"); 12 } ``` Solution ```rust 1 use std::collections::HashMap; 2 use std::fmt::Write as _; // brings the trait in for `write!`; `as _` keeps the name unbound 3 4 fn main() { 5 let mut counts: HashMap<char, u32> = HashMap::new(); 6 for c in "hello".chars() { 7 *counts.entry(c).or_insert(0) += 1; 8 } 9 10 let mut report = String::new(); 11 write!(report, "letters: {}", counts.len()).unwrap(); 12 println!("{report}"); 13 } ``` **Output:** `letters: 4` `HashMap` lives in `std::collections`. The `write!` macro requires `std::fmt::Write` to be in scope to write into a `String`; using `as _` brings the trait’s methods in without binding the name `Write`. ### Exercise 2: Resolve a name clash with `as` [Section titled “Exercise 2: Resolve a name clash with as”](#exercise-2-resolve-a-name-clash-with-as) **Difficulty:** Medium **Objective:** Use `as` to import two same-named functions. **Instructions:** The crate has `parser::json::parse` and `parser::csv::parse`. Both are named `parse`, so you cannot import both directly. Add two `use` lines that rename them to `parse_json` and `parse_csv`, then call each in `main`. ```rust 1 mod parser { 2 pub mod json { 3 pub fn parse(input: &str) -> usize { input.len() } 4 } 5 pub mod csv { 6 pub fn parse(input: &str) -> usize { input.split(',').count() } 7 } 8 } 9 10 // TODO: import both `parse` functions under distinct names 11 12 fn main() { 13 // TODO: call parse_json("{\"a\":1}") and parse_csv("a,b,c"), printing each result 14 } ``` Solution ```rust 1 mod parser { 2 pub mod json { 3 pub fn parse(input: &str) -> usize { input.len() } 4 } 5 pub mod csv { 6 pub fn parse(input: &str) -> usize { input.split(',').count() } 7 } 8 } 9 10 use parser::json::parse as parse_json; 11 use parser::csv::parse as parse_csv; 12 13 fn main() { 14 println!("json bytes: {}", parse_json("{\"a\":1}")); 15 println!("csv fields: {}", parse_csv("a,b,c")); 16 } ``` **Output:** ```plaintext 1 json bytes: 7 2 csv fields: 3 ``` Without `as`, the second `use parser::...::parse;` would trigger `error[E0252]: the name 'parse' is defined multiple times`. ### Exercise 3: Build a facade with `pub use` [Section titled “Exercise 3: Build a facade with pub use”](#exercise-3-build-a-facade-with-pub-use) **Difficulty:** Medium **Objective:** Flatten a deep path using `pub use` so the crate root can import items directly. **Instructions:** The `auth` module nests `issue` inside `auth::tokens`. Add a `pub use` inside `auth` so that `issue` is reachable as `auth::issue`. Then at the crate root, import `Session` and `issue` together in one `use` line and use them in `main`. ```rust 1 mod auth { 2 #[derive(Debug)] 3 pub struct Session { pub user: String } 4 5 pub mod tokens { 6 pub fn issue(user: &str) -> String { format!("tok-{user}") } 7 } 8 9 // TODO: re-export `tokens::issue` so it is reachable as `auth::issue` 10 } 11 12 // TODO: import Session and issue from `auth` in one line 13 14 fn main() { 15 // TODO: create a Session for "ada", issue a token for its user, and print both 16 } ``` Solution ```rust 1 mod auth { 2 #[derive(Debug)] 3 pub struct Session { pub user: String } 4 5 pub mod tokens { 6 pub fn issue(user: &str) -> String { format!("tok-{user}") } 7 } 8 9 // Facade: re-export the deeper item so the crate root sees `auth::issue`. 10 pub use tokens::issue; 11 } 12 13 use auth::{Session, issue}; 14 15 fn main() { 16 let s = Session { user: "ada".into() }; 17 let token = issue(&s.user); 18 println!("{s:?} -> {token}"); 19 } ``` **Output:** ```plaintext 1 Session { user: "ada" } -> tok-ada ``` The `pub use tokens::issue;` line is the facade: callers no longer need to know `issue` lives in the `tokens` submodule. This is the same mechanism crates like `serde` use to expose deeply-nested items at a friendly top-level path. *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * `use` brings a path into scope as a shorter alias — it does **not** load files or run code (that’s `mod`’s job). * `use path::{A, B}` groups names; `use path::{self, X}` brings in a module *and* an item. * `as` renames imports to dodge collisions; `as _` imports a trait for its methods without binding a name. * Glob `use path::*` flattens everything in; reserve it for preludes and test modules. * `pub use` re-exports, enabling the facade pattern that gives crates clean public APIs. * Trait methods require the trait to be in scope (the E0599 trap with no TypeScript equivalent). **Mental model:** `import` ≈ `use`, but in Rust the questions “is this compiled?” and “what do I call it?” are answered by *different* keywords — `mod` and `use`, respectively. # Visibility and the `pub` Keyword > Rust makes every item private by default, like an un-exported declaration, then adds pub, pub(crate), pub(super), and per-field control JavaScript modules lack. In JavaScript and TypeScript modules, **nothing leaves a file unless you `export` it**, and once exported, it is fully public to anyone who imports it. Rust takes the same “private by default” stance but gives you a far richer dial: `pub`, `pub(crate)`, `pub(super)`, and `pub(in path)` let you say *exactly how far* an item is allowed to travel. This page is about that dial. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Every item in Rust — functions, structs, enums, modules, constants, and even individual struct fields — is **private by default**, visible only within the module that defines it (and that module’s children). You opt items into wider visibility with the **`pub`** keyword and its restricted variants. For a TypeScript/JavaScript developer the mental model is: Rust’s `pub` is like `export`, but Rust adds a graduated scale between “totally private” and “totally public” that JavaScript modules simply do not have. > **Note:** This page focuses on *visibility*: who is allowed to see an item. How items are organized into modules is covered in [Modules](/12-modules-packages/00-modules/), how you name paths to reach them in [Paths in the Module Tree](/12-modules-packages/01-module-tree/), and how you bring them into scope with `use` (including re-exporting with `pub use`) in [The `use` Keyword](/12-modules-packages/02-use-keyword/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In an ES module, a declaration is private to its file until you `export` it. There is no in-between: an exported symbol is reachable by *any* file that imports it, whether that file lives in the same folder, the same package, or a completely different `npm` package that depends on yours. billing.ts ```typescript 1 // Private to this file — no `export`, so nobody outside can see it. 2 function internalTaxRate(): number { 3 return 0.08; 4 } 5 6 // Exported — now PUBLIC to every importer, in this package or another. 7 export function totalWithTax(amount: number): number { 8 return amount + amount * internalTaxRate(); 9 } 10 11 // A class whose fields are public unless marked `private`/`#`. 12 export class User { 13 id: number; 14 name: string; 15 #email: string; // truly private (ES `#` field) 16 17 constructor(id: number, name: string, email: string) { 18 this.id = id; 19 this.name = name; 20 this.#email = email; 21 } 22 23 get email(): string { 24 return this.#email; 25 } 26 } ``` app.ts ```typescript 1 import { totalWithTax, User } from "./billing"; 2 3 console.log(totalWithTax(100)); // 108 4 // internalTaxRate(); // not exported, not importable 5 6 const user = new User(1, "Ada", "ada@example.com"); 7 user.name = "Ada Lovelace"; // public field, freely writable 8 // user.#email; // SyntaxError: private field outside class ``` TypeScript’s `private`/`protected` keywords add compile-time field access control, but they are erased at runtime; nothing stops a `(user as any).email` cast. The ES `#` prefix is the only *runtime*-enforced privacy. The key point for the comparison: at the **module** level, JavaScript offers a binary switch — exported or not. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 mod billing { 2 // Private by default — visible only inside `billing`. 3 fn internal_tax_rate() -> f64 { 4 0.08 5 } 6 7 // `pub` exposes this to the parent module (the crate root, here). 8 pub fn total_with_tax(amount: f64) -> f64 { 9 amount + amount * internal_tax_rate() 10 } 11 } 12 13 mod model { 14 #[derive(Debug)] 15 pub struct User { 16 pub id: u64, // public field 17 pub name: String, // public field 18 email: String, // private field — protected by the type's methods 19 } 20 21 impl User { 22 pub fn new(id: u64, name: &str, email: &str) -> Self { 23 User { 24 id, 25 name: name.to_string(), 26 email: email.to_string(), 27 } 28 } 29 30 pub fn email(&self) -> &str { 31 &self.email 32 } 33 } 34 } 35 36 fn main() { 37 let total = billing::total_with_tax(100.0); 38 println!("Total: {total}"); 39 40 let mut user = model::User::new(1, "Ada", "ada@example.com"); 41 user.name = "Ada Lovelace".to_string(); // public field, writable 42 println!("id={}, name={}", user.id, user.name); 43 println!("email={}", user.email()); // private field, via getter 44 } ``` **Real output:** ```plaintext 1 Total: 108 2 id=1, name=Ada Lovelace 3 email=ada@example.com ``` Notice the new dimension compared to JavaScript: `pub` is applied **per field**, not just per type. A `pub struct` can still hide some of its data, which is the foundation of encapsulation in Rust. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Private by default, like an un-`export`ed declaration [Section titled “Private by default, like an un-exported declaration”](#private-by-default-like-an-un-exported-declaration) When you write a plain `fn`, `struct`, `enum`, `const`, `static`, `trait`, or `mod` with no visibility keyword, it is **private**. “Private” in Rust means: visible inside the defining module and any of that module’s **descendant** modules, but invisible to the **parent** module and to siblings. ```rust 1 mod billing { 2 fn internal_tax_rate() -> f64 { 0.08 } // private to `billing` 3 } 4 5 fn main() { 6 let r = billing::internal_tax_rate(); // does not compile (error[E0603]: private function) 7 println!("{r}"); 8 } ``` The real compiler error: ```plaintext 1 error[E0603]: function `internal_tax_rate` is private 2 --> src/main.rs:8:22 3 | 4 8 | let r = billing::internal_tax_rate(); 5 | ^^^^^^^^^^^^^^^^^ private function 6 | 7 note: the function `internal_tax_rate` is defined here 8 --> src/main.rs:2:5 9 | 10 2 | fn internal_tax_rate() -> f64 { 11 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``` > **Note:** A subtle but important asymmetry: child modules can always see *into* their parents’ private items, but parents cannot see *into* their children’s private items. Privacy in Rust flows *outward*: you publish to ancestors, you never hide from descendants. This is the opposite of how many object systems think about “private.” ### `pub` — export to the parent (and beyond) [Section titled “pub — export to the parent (and beyond)”](#pub--export-to-the-parent-and-beyond) Adding `pub` makes an item visible to the module that *contains* it. That is the literal meaning of `pub`, and it is why a `pub` item in a module that is itself private is still not reachable from far away: visibility composes along the whole path. The general rule: > An item is reachable from some location only if **every** segment of the path to it — each enclosing module *and* the item itself — is visible from that location. So to expose `billing::total_with_tax` to code *outside* your crate, both `total_with_tax` **and** the `billing` module would need to be `pub` (`pub mod billing`). ### Field visibility: the part JavaScript modules don’t have [Section titled “Field visibility: the part JavaScript modules don’t have”](#field-visibility-the-part-javascript-modules-dont-have) In TypeScript, marking a class public exports the class; field-level privacy is a separate, class-scoped feature (`private`, `#`). In Rust, **fields have their own visibility, independent of the struct’s**: ```rust 1 pub struct User { 2 pub id: u64, // anyone who can see `User` can read/write this 3 email: String, // only code in this module can touch it 4 } ``` A field with no `pub` is private even when the struct is `pub`. Reading it from outside is an `error[E0616]`: ```plaintext 1 error[E0616]: field `email` of struct `User` is private 2 --> src/main.rs:16:25 3 | 4 16 | println!("{}", user.email); 5 | ^^^^^ private field ``` And — a detail that surprises newcomers — if a struct has *any* private field, you **cannot build it with a struct literal from outside the module at all**, even if you only set the public fields: ```rust 1 mod model { 2 pub struct User { 3 pub id: u64, 4 email: String, // private 5 } 6 } 7 8 fn main() { 9 let user = model::User { 10 id: 1, 11 email: "ada@example.com".to_string(), // does not compile (error[E0451]) 12 }; 13 println!("{}", user.id); 14 } ``` ```plaintext 1 error[E0451]: field `email` of struct `User` is private 2 --> src/main.rs:12:9 3 | 4 10 | let user = model::User { 5 | ----------- in this type 6 11 | id: 1, 7 12 | email: "ada@example.com".to_string(), 8 | ^^^^^ private field ``` This is intentional: by hiding even one field, the type *forces* outside callers through a constructor (`User::new`), which is how Rust guarantees invariants. It is the equivalent of a TypeScript class that hides its backing fields behind a constructor and getters, but enforced at compile time across the whole crate boundary. ### The graduated scale: `pub(crate)`, `pub(super)`, `pub(in path)` [Section titled “The graduated scale: pub(crate), pub(super), pub(in path)”](#the-graduated-scale-pubcrate-pubsuper-pubin-path) This is where Rust goes beyond `export`. Between “private” and “fully public” sit three restricted forms: | Form | Reachable from… | | -------------------- | ------------------------------------------------------------------------ | | `pub` | Everywhere the path is visible — including **other crates** | | `pub(crate)` | Anywhere in **this crate**, but never from a crate that depends on yours | | `pub(super)` | The **parent** module and everything nested under that parent | | `pub(in some::path)` | Only within the named ancestor module (and its descendants) | ```rust 1 mod network { 2 // Visible anywhere in THIS crate, but NOT to external crates. 3 pub(crate) fn connection_id() -> u64 { 4 42 5 } 6 7 pub mod tcp { 8 // Visible only to the parent module `network` (and its descendants). 9 pub(super) fn raw_handshake() -> &'static str { 10 "SYN/ACK" 11 } 12 13 // Visible only within the `network` module subtree. 14 pub(in crate::network) fn buffer_size() -> usize { 15 8192 16 } 17 18 pub fn open() -> &'static str { 19 let _ = buffer_size(); // same module: always fine 20 "tcp-open" 21 } 22 } 23 24 pub fn diagnostics() -> String { 25 let hs = tcp::raw_handshake(); // `network` can see `pub(super)` of its child 26 let bs = tcp::buffer_size(); // and `pub(in crate::network)` items too 27 format!("handshake={hs}, buffer={bs}") 28 } 29 } 30 31 fn main() { 32 println!("conn id = {}", network::connection_id()); // pub(crate): visible at crate root 33 println!("{}", network::tcp::open()); // pub: visible everywhere 34 println!("{}", network::diagnostics()); 35 } ``` **Real output:** ```plaintext 1 conn id = 42 2 tcp-open 3 handshake=SYN/ACK, buffer=8192 ``` > **Tip:** `pub(crate)` is the workhorse. Most “this is public to my own code but I never want to commit to it as part of my library’s API” items should be `pub(crate)`. It is the closest thing Rust has to “internal” in C# or “package-private” in Java, a level JavaScript modules cannot express at all. The mental model for `pub(super)` deserves care. It means “visible to my parent module.” Because privacy flows outward and descendants always inherit access, anything *nested under that parent* can also reach the item. So `pub(super)` is not “visible only to the immediate parent and nothing else”; it is “visible to the parent subtree.” We will see exactly where this trips people up in [Common Pitfalls](#common-pitfalls). ### Enums: variants inherit the enum’s visibility [Section titled “Enums: variants inherit the enum’s visibility”](#enums-variants-inherit-the-enums-visibility) Unlike struct fields, **enum variants and their fields are automatically as public as the enum itself**. You do not (and cannot) write `pub` on a variant: ```rust 1 mod payments { 2 pub enum Status { 3 Pending, 4 Settled { amount: u64 }, // variant fields are public automatically 5 Failed, 6 } 7 8 pub fn describe(s: &Status) -> String { 9 match s { 10 Status::Pending => "pending".to_string(), 11 Status::Settled { amount } => format!("settled: {amount}"), 12 Status::Failed => "failed".to_string(), 13 } 14 } 15 } 16 17 fn main() { 18 let s = payments::Status::Settled { amount: 500 }; 19 if let payments::Status::Settled { amount } = &s { 20 println!("amount = {amount}"); 21 } 22 println!("{}", payments::describe(&s)); 23 } ``` **Real output:** ```plaintext 1 amount = 500 2 settled: 500 ``` This makes sense: an enum’s whole purpose is for callers to match on its variants, so hiding individual variants would defeat the point. If you need a “closed” enum that callers can’t exhaustively match or construct, you reach for other patterns (a private struct wrapper, or the `#[non_exhaustive]` attribute), not field visibility. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript | Rust | | ------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------- | | Default for a top-level item | Private to the file until `export`ed | Private to the module (visible to descendants) | | Granularity | Binary: exported or not | Graduated: `pub`, `pub(crate)`, `pub(super)`, `pub(in path)` | | ”Internal to my package” level | None (an `export` is reachable cross-package) | `pub(crate)` | | Field visibility | `private`/`#` on class members (class-scoped) | Per-field `pub` (independent of the struct) | | Enforcement | `private`/`protected` erased at runtime; `#` enforced | Always enforced at compile time, across crate boundaries | | Constructing a type with hidden state | Allowed via `as any` casts | Impossible from outside if any field is private (`E0451`) | | Direction of privacy | Members hidden from outside the class | Items hidden from *ancestors*; descendants always have access | **Why the extra knobs?** Rust libraries publish a stable public API to *other crates* via [crates.io](https://crates.io) (see [Publishing to crates.io](/12-modules-packages/11-publishing/)). Everything that is merely `pub` becomes part of that semver contract; changing or removing it is a breaking change. `pub(crate)` lets you write code that is shared freely *inside* your crate without ever leaking into your public API. JavaScript packages have no language-level equivalent: the convention is fragile (underscore prefixes, `internal/` folders, an `exports` map in `package.json`), and none of it is checked by the compiler. > **Note:** The visibility of an item also interacts with `use`-based re-exports. You can keep an item defined deep inside a private module and surface it at the crate root with `pub use`, decoupling your *file layout* from your *public API*. That technique lives in [The `use` Keyword](/12-modules-packages/02-use-keyword/#re-exporting-with-pub-use). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Assuming a `pub struct` makes its fields public [Section titled “Pitfall 1: Assuming a pub struct makes its fields public”](#pitfall-1-assuming-a-pub-struct-makes-its-fields-public) Coming from JavaScript, where exporting a class exposes its public fields, it is easy to expect `pub struct` to do the same. It does not: fields are private unless individually marked `pub`. ```rust 1 mod model { 2 pub struct User { 3 pub id: u64, 4 email: String, // forgot `pub` 5 } 6 impl User { 7 pub fn new(id: u64, email: &str) -> Self { 8 User { id, email: email.to_string() } 9 } 10 } 11 } 12 13 fn main() { 14 let user = model::User::new(1, "ada@example.com"); 15 println!("{}", user.email); // does not compile (error[E0616]: private field) 16 } ``` ```plaintext 1 error[E0616]: field `email` of struct `User` is private 2 --> src/main.rs:16:25 3 | 4 16 | println!("{}", user.email); 5 | ^^^^^ private field ``` **Fix:** add `pub` to the field, or expose a getter method (`pub fn email(&self) -> &str`). Prefer the getter when the field has invariants to protect. ### Pitfall 2: Leaking a private type through a public function [Section titled “Pitfall 2: Leaking a private type through a public function”](#pitfall-2-leaking-a-private-type-through-a-public-function) If a `pub` (or `pub(crate)`) function returns or accepts a type that is *less* visible than the function itself, the function’s signature would expose a name callers cannot otherwise reach. Rust warns about this (lint `private_interfaces`) and the type is unusable at the call site: ```rust 1 mod config { 2 struct Secret { // private type 3 token: String, 4 } 5 pub fn load() -> Secret { // public fn returning a private type 6 Secret { token: "abc".to_string() } 7 } 8 } 9 10 fn main() { 11 let _s = config::load(); // does not compile (the returned type is private) 12 } ``` ```plaintext 1 warning: type `Secret` is more private than the item `load` 2 --> src/main.rs:8:5 3 | 4 8 | pub fn load() -> Secret { 5 | ^^^^^^^^^^^^^^^^^^^^^^^ function `load` is reachable at visibility `pub(crate)` 6 | 7 note: but type `Secret` is only usable at visibility `pub(self)` 8 ... 9 error: type `Secret` is private 10 --> src/main.rs:14:14 11 | 12 14 | let _s = config::load(); 13 | ^^^^^^^^^^^^^^ private type ``` **Fix:** make `Secret` at least as visible as `load` (`pub(crate) struct Secret`), or lower `load`’s visibility to match the type. The rule is: an item’s public surface may not be more visible than the types it mentions. ### Pitfall 3: Misreading `pub(super)` as “only the immediate parent” [Section titled “Pitfall 3: Misreading pub(super) as “only the immediate parent””](#pitfall-3-misreading-pubsuper-as-only-the-immediate-parent) `pub(super)` means “visible to my parent module,” and because descendants inherit ancestor access, that includes **everything nested under the parent** — not just the parent’s own body. Reaching the item from a *cousin* under the same parent succeeds, which surprises people who expected a tighter restriction: ```rust 1 mod app { 2 pub mod inner { 3 pub(super) fn helper() -> u32 { 1 } // visible to `app` and all of `app`'s descendants 4 } 5 pub mod other { 6 pub fn call_it() -> u32 { 7 super::inner::helper() // compiles — `other` is inside `app` 8 } 9 } 10 } ``` But step **outside** the parent subtree (here, the crate root is not inside `app`) and it is private again: ```rust 1 mod app { 2 pub mod inner { 3 pub(super) fn helper() -> u32 { 1 } 4 } 5 } 6 7 fn main() { 8 println!("{}", app::inner::helper()); // does not compile (error[E0603]: private function) 9 } ``` ```plaintext 1 error[E0603]: function `helper` is private 2 --> src/main.rs:10:32 3 | 4 10 | println!("{}", app::inner::helper()); 5 | ^^^^^^ private function ``` **Fix:** if you truly want only one specific ancestor module to have access (and nothing else), name it explicitly with `pub(in crate::app)`. If you want crate-wide access, use `pub(crate)`. ### Pitfall 4: Reaching for `pub` when `pub(crate)` is what you mean [Section titled “Pitfall 4: Reaching for pub when pub(crate) is what you mean”](#pitfall-4-reaching-for-pub-when-pubcrate-is-what-you-mean) Marking helpers `pub` “so my other modules can use them” silently enlarges your crate’s public API. Once published, those items are part of your semver contract and you cannot remove them without a major version bump. There is no compiler *error* here; that is exactly why it is dangerous. **Fix:** default to `pub(crate)` for anything that is shared internally but not meant for external consumers. Reserve plain `pub` for the genuine public surface of a library. (See [Publishing to crates.io](/12-modules-packages/11-publishing/) for why this matters at release time.) *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Start private, widen only when forced.** Write items with no visibility keyword first; add `pub`/`pub(crate)` when a real consumer appears. The compiler error tells you precisely when. * **Use `pub(crate)` as your default for shared internals.** It is the idiomatic “internal but not public API” level and keeps your published surface small and stable. * **Hide struct fields and expose behavior.** Make fields private and offer constructors plus getter/setter methods when there are invariants to protect; expose fields with `pub` only for plain data holders (configuration structs, DTOs) that have no invariants. * **Keep public APIs free of private types.** Heed the `private_interfaces` lint; if a function is `pub`, every type in its signature must be at least as visible. * **Prefer explicit `pub(in path)` over loose `pub(super)`** when you want a single, named module to be the only privileged caller; it documents intent and survives refactors that move modules around. * **Decouple file layout from public API with `pub use`.** Organize code into private submodules for your own sanity, then re-export the curated public items at a stable path. (Details in [The `use` Keyword](/12-modules-packages/02-use-keyword/).) * **Run `cargo doc --no-deps --open`** to see exactly what your crate exposes — only `pub` items reachable from the crate root show up, which is the truest picture of your public API. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored event store that uses field visibility to enforce an invariant: every stored event gets a store-assigned sequence number, and the internal index is kept in sync with the event list. Callers can never corrupt either because the fields are private: the only way in is through `push`. ```rust 1 mod store { 2 use std::collections::HashMap; 3 4 /// An append-only event log. The internal storage is hidden so the 5 /// `events` vec and the `index` map can never drift out of sync. 6 pub struct EventStore { 7 events: Vec<Event>, // private: callers must use `push` 8 index: HashMap<String, usize>, // private: maintained internally 9 } 10 11 #[derive(Clone, Debug)] 12 pub struct Event { 13 pub id: String, // public: callers read this freely 14 pub payload: String, // public 15 seq: u64, // private: assigned by the store, never the caller 16 } 17 18 impl Event { 19 /// Read-only access to the store-assigned sequence number. 20 pub fn seq(&self) -> u64 { 21 self.seq 22 } 23 } 24 25 impl EventStore { 26 pub fn new() -> Self { 27 EventStore { 28 events: Vec::new(), 29 index: HashMap::new(), 30 } 31 } 32 33 /// The single, invariant-preserving way to add an event. 34 pub fn push(&mut self, id: &str, payload: &str) { 35 let seq = self.events.len() as u64; 36 self.index.insert(id.to_string(), self.events.len()); 37 self.events.push(Event { 38 id: id.to_string(), 39 payload: payload.to_string(), 40 seq, 41 }); 42 } 43 44 pub fn get(&self, id: &str) -> Option<&Event> { 45 let pos = *self.index.get(id)?; 46 self.events.get(pos) 47 } 48 49 /// Crate-internal metric: other modules in this crate may read the 50 /// count, but external crates cannot rely on it. 51 pub(crate) fn len(&self) -> usize { 52 self.events.len() 53 } 54 } 55 } 56 57 // Surface the public types at the crate root, independent of file layout. 58 pub use store::{Event, EventStore}; 59 60 fn main() { 61 let mut es = EventStore::new(); 62 es.push("user.created", "{\"id\":1}"); 63 es.push("user.renamed", "{\"id\":1,\"name\":\"Ada\"}"); 64 65 if let Some(ev) = es.get("user.renamed") { 66 println!("id={}, seq={}, payload={}", ev.id, ev.seq(), ev.payload); 67 } 68 69 println!("total events (crate-internal): {}", es.len()); 70 } ``` **Real output:** ```plaintext 1 id=user.renamed, seq=1, payload={"id":1,"name":"Ada"} 2 total events (crate-internal): 2 ``` Note the layered design: `id` and `payload` are `pub` because they are plain data the caller supplied; `seq` is private with a read-only getter because *the store owns it*; the `EventStore` internals are fully private; and `len` is `pub(crate)` because internal tooling may want it but it is not part of the library’s public promise. This is the kind of fine-grained control that JavaScript’s binary `export` cannot express. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Controlling Visibility with `pub`](https://doc.rust-lang.org/book/ch07-03-paths-for-referring-to-an-item-in-the-module-tree.html#exposing-paths-with-the-pub-keyword) * [The Rust Reference — Visibility and Privacy](https://doc.rust-lang.org/reference/visibility-and-privacy.html) * [Rust by Example — Visibility](https://doc.rust-lang.org/rust-by-example/mod/visibility.html) * [The `non_exhaustive` attribute](https://doc.rust-lang.org/reference/attributes/type_system.html#the-non_exhaustive-attribute) — for evolving enums and structs without breaking callers ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Modules](/12-modules-packages/00-modules/): how `mod` defines the tree that visibility is measured against * [The Module Tree and Paths](/12-modules-packages/01-module-tree/) — `crate::`, `super::`, `self::`, and absolute vs relative paths * [The `use` Keyword](/12-modules-packages/02-use-keyword/): bringing items into scope and re-exporting with `pub use` * [Cargo and `Cargo.toml`](/12-modules-packages/04-cargo/) — the crate that `pub(crate)` refers to * [Publishing to crates.io](/12-modules-packages/11-publishing/) — why your `pub` surface is a semver contract * [Variables and Mutability](/02-basics/00-variables/) — the broader “private/immutable by default” philosophy * [Writing Tests](/13-testing/): how `#[cfg(test)]` modules access private items via `use super::*` *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Expose the right function [Section titled “Exercise 1: Expose the right function”](#exercise-1-expose-the-right-function) **Difficulty:** Easy **Objective:** Practice the difference between a private helper and a public entry point. **Instructions:** Make `area` callable from `main`, while keeping `scale_factor` private to the module. Fill in the visibility keywords so the program compiles and prints `6`. ```rust 1 mod geometry { 2 fn area(width: f64, height: f64) -> f64 { 3 scale_factor() * width * height 4 } 5 6 fn scale_factor() -> f64 { 7 1.0 8 } 9 } 10 11 fn main() { 12 println!("{}", geometry::area(2.0, 3.0)); // should print 6 13 } ``` Solution Only `area` needs to be public; `scale_factor` stays private and remains reachable from inside the module. ```rust 1 mod geometry { 2 pub fn area(width: f64, height: f64) -> f64 { 3 scale_factor() * width * height 4 } 5 6 fn scale_factor() -> f64 { 7 1.0 8 } 9 } 10 11 fn main() { 12 println!("{}", geometry::area(2.0, 3.0)); 13 } ``` **Output:** ```plaintext 1 6 ``` ### Exercise 2: Encapsulate an invariant with field visibility [Section titled “Exercise 2: Encapsulate an invariant with field visibility”](#exercise-2-encapsulate-an-invariant-with-field-visibility) **Difficulty:** Medium **Objective:** Use a private field to force callers through methods that protect a balance from going negative. **Instructions:** Complete the `Account` type so that `owner` is a public field, `balance` is private, and the balance can only change through `deposit` and `withdraw`. A withdrawal larger than the balance must return an `Err`. ```rust 1 mod bank { 2 pub struct Account { 3 // owner should be a public field 4 // balance should be private 5 } 6 7 impl Account { 8 pub fn open(owner: &str) -> Self { 9 /* ??? */ 10 } 11 12 pub fn deposit(&mut self, amount: u64) { 13 /* ??? */ 14 } 15 16 pub fn withdraw(&mut self, amount: u64) -> Result<(), String> { 17 /* ??? */ 18 } 19 20 pub fn balance(&self) -> u64 { 21 /* ??? */ 22 } 23 } 24 } 25 26 fn main() { 27 let mut acct = bank::Account::open("Ada"); 28 acct.deposit(100); 29 acct.withdraw(30).unwrap(); 30 println!("{} has {}", acct.owner, acct.balance()); 31 println!("{:?}", acct.withdraw(1000)); 32 } ``` Solution ```rust 1 mod bank { 2 pub struct Account { 3 pub owner: String, // public: freely readable/writable 4 balance: u64, // private: protected by deposit/withdraw 5 } 6 7 impl Account { 8 pub fn open(owner: &str) -> Self { 9 Account { owner: owner.to_string(), balance: 0 } 10 } 11 12 pub fn deposit(&mut self, amount: u64) { 13 self.balance += amount; 14 } 15 16 pub fn withdraw(&mut self, amount: u64) -> Result<(), String> { 17 if amount > self.balance { 18 return Err("insufficient funds".to_string()); 19 } 20 self.balance -= amount; 21 Ok(()) 22 } 23 24 pub fn balance(&self) -> u64 { 25 self.balance 26 } 27 } 28 } 29 30 fn main() { 31 let mut acct = bank::Account::open("Ada"); 32 acct.deposit(100); 33 acct.withdraw(30).unwrap(); 34 println!("{} has {}", acct.owner, acct.balance()); 35 println!("{:?}", acct.withdraw(1000)); 36 } ``` **Output:** ```plaintext 1 Ada has 70 2 Err("insufficient funds") ``` Because `balance` is private and the struct has a private field, no caller outside `bank` can build an `Account` literal or set the balance directly; they must go through the methods. ### Exercise 3: Pick the tightest restricted visibility [Section titled “Exercise 3: Pick the tightest restricted visibility”](#exercise-3-pick-the-tightest-restricted-visibility) **Difficulty:** Hard **Objective:** Wire up `pub(crate)`, `pub(super)`, and `pub(in path)` so the program compiles with the narrowest visibility that still works. **Instructions:** `engine::run` must be callable from `main` (it is internal to this crate, never an external API). `scheduler::tick` should be reachable only from within `engine`. `scheduler::next_id` should be reachable only from within the `engine` subtree. Choose the most restrictive keyword for each. ```rust 1 mod engine { 2 pub mod scheduler { 3 fn tick() -> u64 { 4 next_id() 5 } 6 7 fn next_id() -> u64 { 8 7 9 } 10 } 11 12 fn run() -> u64 { 13 scheduler::tick() 14 } 15 } 16 17 fn main() { 18 println!("{}", engine::run()); // should print 7 19 } ``` Solution * `run` is internal-to-the-crate API called from `main` (which is outside `engine`), so `pub(crate)` is the tightest fit. * `tick` must be visible to `engine` (its grandparent module), so `pub(super)` exposes it to `engine` and everything nested under it. * `next_id` should be confined to the `engine` subtree, which `pub(in crate::engine)` states explicitly. ```rust 1 mod engine { 2 pub mod scheduler { 3 // Visible to the parent (`engine`) and its descendants. 4 pub(super) fn tick() -> u64 { 5 next_id() 6 } 7 8 // Visible only within the `engine` module subtree. 9 pub(in crate::engine) fn next_id() -> u64 { 10 7 11 } 12 } 13 14 // Visible across the whole crate, but not to external crates. 15 pub(crate) fn run() -> u64 { 16 scheduler::tick() 17 } 18 } 19 20 fn main() { 21 println!("{}", engine::run()); 22 } ``` **Output:** ```plaintext 1 7 ``` > **Tip:** `engine::run` could have been plain `pub` and the program would still compile, but for a binary crate there is no “external crate” to expose it to, and using `pub` on a genuinely internal item is the habit Pitfall 4 warns against. `pub(crate)` documents the intent precisely. # Cargo.toml: The Manifest, Dependencies, Lockfile, and Profiles > Cargo.toml is Rust's package.json, but one TOML file holds metadata, dependencies, and build tuning. Covers the manifest, the Cargo.lock twin, and [profile.*]. `Cargo.toml` is Rust’s answer to `package.json`. It declares **who your crate is** (`[package]`), **what it depends on** (`[dependencies]`), and **how it should be built** (`[profile.*]`). This page covers the manifest itself, the `Cargo.lock` file it generates, and build profiles. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Every Rust **crate** has a `Cargo.toml` manifest at its root, just as every Node project has a `package.json`. The big mental shift for a TypeScript/JavaScript developer is that Cargo folds build configuration, dependency declarations, and release-tuning knobs into **one TOML file** with no `scripts` section and no separate `tsconfig.json`; the standard `cargo` subcommands replace your npm scripts, and **build profiles** replace your bundler config. This page focuses on the manifest’s `[package]` and `[dependencies]` tables, the auto-generated `Cargo.lock`, and `[profile.*]`; sibling pages cover the commands, the dependency-spec syntax, workspaces, and features in detail. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) A realistic `package.json` for a small CLI tool, plus its companion `tsconfig.json`: package.json ```json 1 { 2 "name": "task-cli", 3 "version": "0.2.1", 4 "description": "A tiny task tracker CLI", 5 "license": "MIT", 6 "type": "module", 7 "main": "dist/index.js", 8 "bin": { "task-cli": "dist/index.js" }, 9 "engines": { "node": ">=22" }, 10 "scripts": { 11 "build": "tsc", 12 "start": "node dist/index.js", 13 "dev": "tsx src/index.ts", 14 "test": "vitest" 15 }, 16 "dependencies": { 17 "zod": "^3.23.0" 18 }, 19 "devDependencies": { 20 "typescript": "^5.5.0", 21 "tsx": "^4.0.0", 22 "vitest": "^2.0.0" 23 } 24 } ``` ```jsonc 1 // tsconfig.json — build/output configuration lives in a SEPARATE file 2 { 3 "compilerOptions": { 4 "target": "ES2022", 5 "module": "ESNext", 6 "outDir": "dist", 7 "strict": true 8 } 9 } ``` The dependency tree is pinned in `package-lock.json` (generated, committed), and `node_modules/` is downloaded per-project. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same project as a Rust crate. **One** file holds metadata, dependencies, *and* build tuning: Cargo.toml ```toml 1 [package] 2 name = "taskcli" 3 version = "0.2.1" 4 edition = "2024" 5 rust-version = "1.85" 6 authors = ["Ada Zeybek <me@zeybek.dev>"] 7 description = "A tiny task tracker CLI" 8 license = "MIT OR Apache-2.0" 9 repository = "https://github.com/ada/taskcli" 10 keywords = ["cli", "tasks", "productivity"] 11 categories = ["command-line-utilities"] 12 13 [dependencies] 14 serde = { version = "1.0", features = ["derive"] } 15 serde_json = "1.0" 16 anyhow = "1" 17 18 [dev-dependencies] 19 tempfile = "3" 20 21 # Build tuning lives RIGHT HERE — no separate tsconfig/bundler file. 22 [profile.release] 23 opt-level = 3 24 lto = true 25 codegen-units = 1 26 strip = true ``` A matching `src/main.rs` that uses those dependencies: src/main.rs ```rust 1 use anyhow::{Context, Result}; 2 use serde::{Deserialize, Serialize}; 3 4 #[derive(Debug, Serialize, Deserialize)] 5 struct Task { 6 id: u32, 7 title: String, 8 done: bool, 9 } 10 11 fn load_tasks(json: &str) -> Result<Vec<Task>> { 12 let tasks: Vec<Task> = 13 serde_json::from_str(json).context("failed to parse tasks JSON")?; 14 Ok(tasks) 15 } 16 17 fn main() -> Result<()> { 18 let data = r#"[ 19 { "id": 1, "title": "Write Cargo guide", "done": false }, 20 { "id": 2, "title": "Verify snippets", "done": true } 21 ]"#; 22 23 let tasks = load_tasks(data)?; 24 for task in &tasks { 25 let mark = if task.done { "x" } else { " " }; 26 println!("[{mark}] #{} {}", task.id, task.title); 27 } 28 println!("{} task(s) loaded", tasks.len()); 29 Ok(()) 30 } ``` Running it produces real output: ```text 1 $ cargo run --quiet 2 [ ] #1 Write Cargo guide 3 [x] #2 Verify snippets 4 2 task(s) loaded ``` > **Note:** The package `name` is `taskcli`, not `task-cli`. Cargo accepts hyphens in names but the *crate* identifier in code becomes `taskcli` (hyphens map to underscores). Many crates use hyphenated names like `serde_json` vs `serde-json`; the underscore form is what you `use` in code. We use a hyphen-free name here to keep things simple. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `[package]` — your crate’s identity card [Section titled “\[package\] — your crate’s identity card”](#package--your-crates-identity-card) This table is the direct analogue of the top-level fields in `package.json`. Field by field: ```toml 1 [package] 2 name = "taskcli" # like package.json "name" 3 version = "0.2.1" # like "version"; SemVer, and Cargo ENFORCES it 4 edition = "2024" # NO package.json equivalent — see below 5 rust-version = "1.85" # like "engines.node": minimum compiler (MSRV) 6 authors = ["Ada Zeybek <me@zeybek.dev>"] 7 description = "A tiny task tracker CLI" 8 license = "MIT OR Apache-2.0" # an SPDX expression, not free text 9 repository = "https://github.com/ada/taskcli" 10 keywords = ["cli", "tasks", "productivity"] # max 5, for crates.io search 11 categories = ["command-line-utilities"] # from a fixed crates.io list ``` * **`name` + `version`** are the only strictly-required fields. `cargo new` fills them in. * **`edition`** has no `package.json` counterpart. An **edition** (`2015`, `2018`, `2021`, `2024`) is an opt-in revision of the *language surface* — new keywords, lints, defaults — without breaking older code. It is **not** a compiler version. `cargo new` writes the newest edition your toolchain supports; on current stable that is `"2024"`, the latest stable edition. Crates of different editions link together fine. * **`rust-version`** (the **MSRV**, Minimum Supported Rust Version) is the closest thing to `engines.node`. Unlike `engines`, which Node only *warns* about, Cargo will *refuse* to build if your toolchain is older than the stated `rust-version`. * **`license`** is an SPDX expression. `"MIT OR Apache-2.0"` (the conventional Rust dual-license) means downstream users may pick either. This is metadata for crates.io, like `package.json`’s `"license"`. * **`description`, `keywords`, `categories`, `repository`** are crates.io discoverability metadata, relevant only when you publish. See [Publishing to crates.io](/12-modules-packages/11-publishing/). > **Note:** Notice there is **no `main` field**. Cargo finds your entry point by convention: `src/main.rs` for a binary, `src/lib.rs` for a library. There is also **no `scripts` table**: the standard `cargo build`/`run`/`test`/`fmt`/`clippy` subcommands replace npm scripts. See [Cargo Commands](/12-modules-packages/05-cargo-commands/). ### `[dependencies]` — what you pull in [Section titled “\[dependencies\] — what you pull in”](#dependencies--what-you-pull-in) The simplest form maps one-to-one onto a `package.json` `dependencies` entry: ```toml 1 [dependencies] 2 anyhow = "1" # like "anyhow": "^1" in package.json 3 serde_json = "1.0" # like "serde_json": "^1.0" ``` A bare version string is a **caret requirement** by default, exactly like npm’s leading `^`. `"1.0"` means `>=1.0.0, <2.0.0`. This trips up TypeScript developers who read `"1.0"` as “pinned to 1.0”. It is *not* pinned. (For the full grammar — caret, tilde, `=` exact, wildcards, git/path sources — see [Specifying Dependencies](/12-modules-packages/06-dependencies/).) When you need to enable optional **features** or other knobs, the value becomes an inline table: ```toml 1 [dependencies] 2 serde = { version = "1.0", features = ["derive"] } ``` This is roughly like installing a package *and* flipping on an opt-in capability. npm has no real equivalent; the closest analogy is a peer/optional dependency you choose to wire up. The `features` array turns on conditionally-compiled parts of the crate; `serde`’s `"derive"` feature is what makes `#[derive(Serialize)]` work. Forgetting it is the single most common Cargo mistake for newcomers (see Common Pitfalls). Features are covered fully in [Feature Flags and Conditional Compilation](/12-modules-packages/09-feature-flags/). ### `[dev-dependencies]` — test-and-build-only deps [Section titled “\[dev-dependencies\] — test-and-build-only deps”](#dev-dependencies--test-and-build-only-deps) ```toml 1 [dev-dependencies] 2 tempfile = "3" ``` This is the exact analogue of `devDependencies`: crates used by tests, examples, and benchmarks but **not** compiled into your published library or shipped binary. Details and the related `[build-dependencies]` live in [Dev-Dependencies, Build-Dependencies, and Optional Dependencies](/12-modules-packages/07-dev-dependencies/). ### `Cargo.lock` — the generated lockfile [Section titled “Cargo.lock — the generated lockfile”](#cargolock--the-generated-lockfile) The first time you build, Cargo resolves every version requirement to a concrete version and records the full graph (with checksums) in `Cargo.lock`. This is `package-lock.json`’s twin. The top of a real one: ```toml 1 # This file is automatically @generated by Cargo. 2 # It is not intended for manual editing. 3 version = 4 4 5 [[package]] 6 name = "anyhow" 7 version = "1.0.102" 8 source = "registry+https://github.com/rust-lang/crates.io-index" 9 checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c" 10 11 [[package]] 12 name = "serde" 13 version = "1.0.228" 14 source = "registry+https://github.com/rust-lang/crates.io-index" 15 checksum = "..." ``` Key facts: * It is **TOML**, not JSON, and far more readable than `package-lock.json`. * It is **auto-generated**; never hand-edit it. To change a locked version, run `cargo update` (see [Cargo Commands](/12-modules-packages/05-cargo-commands/)). * **Commit it for applications/binaries; do not commit it for libraries.** Same rule as npm in spirit: an app wants byte-reproducible builds, while a library wants to be tested against the latest compatible versions of its dependents. `cargo new` writes the **same** `.gitignore` (just `/target`) for both binaries and libraries; neither variant ignores `Cargo.lock`. The convention is a decision **you** make: commit `Cargo.lock` for applications/binaries; for a library you publish, add `Cargo.lock` to `.gitignore` yourself. > **Note:** Unlike `node_modules/`, resolved crates are **downloaded once** to a shared cache in `~/.cargo/registry/` and **compiled** into your project’s `target/` directory. There is no per-project copy of source. That is why Rust projects do not carry a giant `node_modules/`-style folder, only the `target/` build cache, which `cargo clean` can wipe. ### `[profile.*]` — build tuning (the part with no `package.json` analogue) [Section titled “\[profile.\*\] — build tuning (the part with no package.json analogue)”](#profile--build-tuning-the-part-with-no-packagejson-analogue) This is where Cargo’s “one file” philosophy diverges most sharply from the Node world. In TypeScript, compile/output settings live in `tsconfig.json` and bundling/minification in a bundler config (webpack/esbuild/vite). In Rust, all of that is **build profiles** right in `Cargo.toml`: ```toml 1 [profile.release] 2 opt-level = 3 # optimization level 0–3 (3 = max); "s"/"z" optimize for size 3 lto = true # link-time optimization across crates (smaller, faster, slower to build) 4 codegen-units = 1 # 1 = best optimization, slowest compile; default 16 trades speed for parallelism 5 strip = true # strip debug symbols from the binary (smaller file) ``` Cargo ships **four built-in profiles**, and you can override any field: | Profile | Used by | Default `opt-level` | Default `debug` | | --------- | -------------------------- | ------------------- | --------------- | | `dev` | `cargo build`, `cargo run` | `0` | full | | `release` | `cargo build --release` | `3` | none | | `test` | `cargo test` | `0` | full | | `bench` | `cargo bench` | `3` | none | You rarely set a `[profile.dev]`; the defaults (fast compile, no optimization) are what you want while iterating. You *do* tune `[profile.release]` for shipping. The effect is real and reproducible in *direction*: building the example above with the tuned `release` profile produces a noticeably **smaller** binary than the default `dev` profile, while incremental `dev` rebuilds finish **dramatically faster**: ```text 1 $ cargo build --release 2 Finished `release` profile [optimized] target(s) in ... 3 # target/release/taskcli -> smaller binary (stripped + LTO) 4 5 $ cargo build 6 Finished `dev` profile [unoptimized + debuginfo] target(s) in ... 7 # target/debug/taskcli -> larger binary (with debug info) ``` > **Note:** Exact byte counts and build times vary heavily by platform and toolchain, so they are omitted here. On one macOS arm64 / Rust 1.96 run the debug binary was roughly 2-3x the size of the stripped release binary. Build *times* are even more variable: a clean build is dominated by compiling dependencies (tens of seconds either way), while a cached rebuild of just this crate finishes in a fraction of a second for `dev` and a few seconds for `release` (where `lto` and `codegen-units = 1` deliberately trade compile speed for a tighter artifact). The takeaway holds regardless of the exact numbers: the `dev` profile optimizes for fast iteration, the `release` profile for a smaller, faster output. That trade-off is exactly the dev-vs-prod distinction you manage with bundler modes in Node, but it is first-class and built in. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/Node (`package.json`) | Rust (`Cargo.toml`) | | ------------------------- | ---------------------------------- | ------------------------------------------------ | | Format | JSON | TOML | | Build config location | Separate `tsconfig.json` + bundler | Same file (`[profile.*]`) | | Task runner | `scripts` table (`npm run x`) | No scripts; standard `cargo` subcommands | | Entry point | `"main"` / `"bin"` fields | Convention: `src/main.rs` / `src/lib.rs` | | Default version semantics | `^` must be written explicitly | Bare `"1.0"` is already caret (`^`) | | Language revisions | None (TS version is the compiler) | `edition` (opt-in, decoupled from compiler) | | Min runtime/compiler | `engines` (advisory warning) | `rust-version` / MSRV (build-time error) | | Lockfile | `package-lock.json` (JSON) | `Cargo.lock` (TOML) | | Dependency storage | `node_modules/` per project | Shared `~/.cargo/registry/` + compiled `target/` | | Optional capabilities | (no real equivalent) | `features` per dependency | The deepest difference: **`Cargo.toml` is declarative and converges on conventions, while `package.json` is imperative and configurable.** You will write far less configuration in Rust because the toolchain assumes sensible defaults (entry points, test discovery, formatting, linting) that you would have to wire up manually in a Node project. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting a dependency’s feature flag [Section titled “Pitfall 1: Forgetting a dependency’s feature flag”](#pitfall-1-forgetting-a-dependencys-feature-flag) This is *the* classic Cargo mistake for newcomers. You add `serde`, write `#[derive(Serialize)]`, and it does not compile, because the derive macro lives behind the `derive` feature, which is off by default. ```toml 1 # Cargo.toml — missing the "derive" feature 2 [dependencies] 3 serde = "1.0" 4 serde_json = "1.0" ``` ```rust 1 use serde::Serialize; // imports the TRAIT, not the derive macro 2 3 #[derive(Serialize)] // does not compile 4 struct Task { 5 id: u32, 6 } 7 8 fn main() { 9 let t = Task { id: 1 }; 10 println!("{}", serde_json::to_string(&t).unwrap()); 11 } ``` The real error from `cargo build`: ```text 1 error: cannot find derive macro `Serialize` in this scope 2 --> src/main.rs:3:10 3 | 4 3 | #[derive(Serialize)] 5 | ^^^^^^^^^ 6 | 7 note: `Serialize` is imported here, but it is only a trait, without a derive macro 8 --> src/main.rs:1:5 9 | 10 1 | use serde::Serialize; 11 | ^^^^^^^^^^^^^^^^ 12 13 error[E0277]: the trait bound `Task: serde::Serialize` is not satisfied ``` **Fix:** enable the feature — `serde = { version = "1.0", features = ["derive"] }` — or run `cargo add serde --features derive`. See [Feature Flags and Conditional Compilation](/12-modules-packages/09-feature-flags/). ### Pitfall 2: Reading a bare version as “pinned” [Section titled “Pitfall 2: Reading a bare version as “pinned””](#pitfall-2-reading-a-bare-version-as-pinned) ```toml 1 [dependencies] 2 tokio = "1.45.0" # NOT pinned — this is ^1.45.0 == >=1.45.0, <2.0.0 ``` Coming from `package.json`, where `"1.45.0"` (no `^`) means *exactly* `1.45.0`, you will assume Cargo pins it too. It does not: a bare string is a caret range. To pin exactly, prefix with `=`: ```toml 1 tokio = "=1.45.0" # exactly 1.45.0 ``` The `Cargo.lock` still pins the *resolved* version for reproducibility, but the *requirement* in `Cargo.toml` stays a range. Full grammar in [Specifying Dependencies](/12-modules-packages/06-dependencies/). ### Pitfall 3: Hand-editing `Cargo.lock` [Section titled “Pitfall 3: Hand-editing Cargo.lock”](#pitfall-3-hand-editing-cargolock) `Cargo.lock` starts with `# It is not intended for manual editing.` for a reason. Bumping a version there by hand will be overwritten or cause a checksum mismatch. To change a locked dependency, edit the *requirement* in `Cargo.toml` and/or run `cargo update`. ### Pitfall 4: Expecting an `engines`-style warning, getting a hard error [Section titled “Pitfall 4: Expecting an engines-style warning, getting a hard error”](#pitfall-4-expecting-an-engines-style-warning-getting-a-hard-error) If you set `rust-version = "1.85"` and build on an older toolchain, Cargo does not warn-and-continue the way `npm` does for `engines.node`. It errors out before compiling. That is usually what you want, but it surprises people who treat MSRV as advisory. ### Pitfall 5: Putting build settings in the wrong place [Section titled “Pitfall 5: Putting build settings in the wrong place”](#pitfall-5-putting-build-settings-in-the-wrong-place) There is no `tsconfig.json` to reach for. If you want optimizations, debug symbols, or smaller binaries, those go in `[profile.*]` inside `Cargo.toml` — not in a separate config file, and not as command-line flags you have to remember every time. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Let `cargo new` / `cargo add` write the manifest.** `cargo add serde --features derive` edits `[dependencies]` correctly and picks the latest version; you rarely need to type version strings by hand. See [Cargo Commands](/12-modules-packages/05-cargo-commands/) and [Specifying Dependencies](/12-modules-packages/06-dependencies/). * **Set `rust-version` (MSRV) on anything you publish or share.** It documents the minimum compiler and turns “works on my machine” into a checkable contract. * **Commit `Cargo.lock` for binaries/applications; omit it for libraries.** This mirrors the npm convention and is the single most-asked lockfile question. * **Tune `[profile.release]` deliberately, not by reflex.** `opt-level = 3` is already the release default. `lto = true` + `codegen-units = 1` give smaller, faster binaries at the cost of compile time: great for CI release builds, painful for local iteration. `strip = true` shrinks the binary by dropping symbols. * **Keep build tuning in the manifest, not in shell aliases.** A profile is reproducible and shared; a forgotten `--flag` is not. * **Use a real SPDX `license` expression** (`"MIT OR Apache-2.0"` is the Rust default convention), not prose, so tooling and crates.io can parse it. * **Don’t over-specify versions.** Bare caret requirements (`"1"`, `"1.0"`) are idiomatic; reach for `=` exact pins only when you genuinely need them. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored manifest for a CLI that reads/writes JSON, with separated dev dependencies and a tuned release profile. Both the manifest and the program below were compiled and run as-is. Cargo.toml ```toml 1 [package] 2 name = "taskcli" 3 version = "0.2.1" 4 edition = "2024" 5 rust-version = "1.85" 6 description = "A tiny task tracker CLI" 7 license = "MIT OR Apache-2.0" 8 repository = "https://github.com/ada/taskcli" 9 10 [dependencies] 11 serde = { version = "1.0", features = ["derive"] } 12 serde_json = "1.0" 13 anyhow = "1" 14 15 [dev-dependencies] 16 tempfile = "3" 17 18 [profile.release] 19 opt-level = 3 20 lto = true 21 codegen-units = 1 22 strip = true ``` src/main.rs ```rust 1 use anyhow::{Context, Result}; 2 use serde::{Deserialize, Serialize}; 3 4 #[derive(Debug, Serialize, Deserialize)] 5 struct Task { 6 id: u32, 7 title: String, 8 done: bool, 9 } 10 11 /// Parse a JSON array of tasks, attaching context on failure. 12 fn load_tasks(json: &str) -> Result<Vec<Task>> { 13 let tasks: Vec<Task> = 14 serde_json::from_str(json).context("failed to parse tasks JSON")?; 15 Ok(tasks) 16 } 17 18 fn main() -> Result<()> { 19 let data = r#"[ 20 { "id": 1, "title": "Write Cargo guide", "done": false }, 21 { "id": 2, "title": "Verify snippets", "done": true } 22 ]"#; 23 24 let tasks = load_tasks(data)?; 25 for task in &tasks { 26 let mark = if task.done { "x" } else { " " }; 27 println!("[{mark}] #{} {}", task.id, task.title); 28 } 29 println!("{} task(s) loaded", tasks.len()); 30 Ok(()) 31 } ``` Real `cargo run` output: ```text 1 [ ] #1 Write Cargo guide 2 [x] #2 Verify snippets 3 2 task(s) loaded ``` You can inspect the resolved dependency graph that Cargo recorded in `Cargo.lock` with the built-in `cargo tree` (real output, trimmed): ```text 1 $ cargo tree 2 taskcli v0.2.1 (/path/to/taskcli) 3 ├── anyhow v1.0.102 4 ├── serde v1.0.228 5 │ ├── serde_core v1.0.228 6 │ └── serde_derive v1.0.228 (proc-macro) 7 │ ├── proc-macro2 v1.0.106 8 │ ├── quote v1.0.45 9 │ └── syn v2.0.117 10 └── serde_json v1.0.150 11 ├── itoa v1.0.18 12 ├── memchr v2.8.1 13 ├── serde_core v1.0.228 14 └── zmij v1.0.21 ``` That tree — three direct dependencies fanning out to a handful of transitive ones — is the Rust counterpart to running `npm ls`. The `(proc-macro)` tag marks crates that run at compile time to generate code (here, the machinery behind `#[derive(Serialize)]`). > **Tip:** Run `cargo metadata --format-version 1` to get the manifest and resolved graph as machine-readable JSON, handy for scripts, the way you might parse `package.json` with `jq`. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Cargo Book — The Manifest Format](https://doc.rust-lang.org/cargo/reference/manifest.html): every `[package]` field. * [The Cargo Book — Specifying Dependencies](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html) * [The Cargo Book — Cargo.lock vs Cargo.toml](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html) * [The Cargo Book — Profiles](https://doc.rust-lang.org/cargo/reference/profiles.html) * [The Rust Edition Guide](https://doc.rust-lang.org/edition-guide/): what editions are and why `2024`. ### Cross-links in this guide [Section titled “Cross-links in this guide”](#cross-links-in-this-guide) * [Modules: ES modules → `mod`](/12-modules-packages/00-modules/): the in-language module system that lives *inside* a crate. * [The module tree & paths](/12-modules-packages/01-module-tree/) * [`use` & re-exports](/12-modules-packages/02-use-keyword/) and [`pub` visibility](/12-modules-packages/03-pub-visibility/) * [Cargo commands](/12-modules-packages/05-cargo-commands/) — `build`, `run`, `add`, `update`, and friends. * [Specifying dependencies](/12-modules-packages/06-dependencies/): SemVer grammar, git/path deps, features-on-deps. * [Dev & build dependencies](/12-modules-packages/07-dev-dependencies/) * [Workspaces](/12-modules-packages/08-workspaces/) — multi-crate monorepos and a shared `Cargo.lock`. * [Feature flags](/12-modules-packages/09-feature-flags/): `[features]` and `#[cfg(feature = "...")]`. * [Build scripts](/12-modules-packages/10-build-scripts/) and [Publishing to crates.io](/12-modules-packages/11-publishing/). * Foundations: [Why Rust](/00-introduction/) · [Understanding Cargo (intro)](/01-getting-started/03-cargo-basics/) · [Basics](/02-basics/). * Next up after modules: [Testing](/13-testing/) — where `[dev-dependencies]` and the `test` profile come into play. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: From `package.json` to `Cargo.toml` [Section titled “Exercise 1: From package.json to Cargo.toml”](#exercise-1-from-packagejson-to-cargotoml) **Difficulty:** Beginner **Objective:** Translate a Node manifest into a Cargo manifest. **Instructions:** Given this `package.json`, write the equivalent `[package]` table. Pick the appropriate fields and a valid SPDX `license`. Ignore `scripts` (Cargo has no equivalent). ```json 1 { 2 "name": "url-shortener", 3 "version": "1.4.0", 4 "description": "Shorten and expand URLs", 5 "license": "MIT", 6 "engines": { "node": ">=22" } 7 } ``` Solution Cargo.toml ```toml 1 [package] 2 name = "url-shortener" # hyphens are allowed in the package name 3 version = "1.4.0" 4 edition = "2024" # cargo new fills in the newest edition 5 rust-version = "1.85" # the analogue of engines.node — a MINIMUM compiler 6 description = "Shorten and expand URLs" 7 license = "MIT" # a valid SPDX expression 8 9 [dependencies] ``` Notes: there is no `main`/`scripts`/`type` to translate; those are handled by convention and by the `cargo` subcommands. `engines.node` maps conceptually to `rust-version` (MSRV), though one is advisory in Node and the other is enforced by Cargo. This manifest compiles with an empty `src/main.rs` containing `fn main() {}`. ### Exercise 2: Add a dependency with a feature and use it [Section titled “Exercise 2: Add a dependency with a feature and use it”](#exercise-2-add-a-dependency-with-a-feature-and-use-it) **Difficulty:** Intermediate **Objective:** Practice the `[dependencies]` inline-table form and the most common feature flag. **Instructions:** Starting from a fresh `cargo new`, add `serde` (with the `derive` feature) and `serde_json`, then make this program compile and print the JSON. Fill in the `/* ??? */` placeholders. ```rust 1 use serde::Serialize; 2 3 #[derive(/* ??? */)] 4 struct Point { 5 x: i32, 6 y: i32, 7 } 8 9 fn main() { 10 let p = Point { x: 3, y: 4 }; 11 let json = /* ??? */; // serialize p to a JSON string 12 println!("{json}"); 13 } ``` Solution `Cargo.toml`: ```toml 1 [dependencies] 2 serde = { version = "1.0", features = ["derive"] } 3 serde_json = "1.0" ``` (Equivalently: `cargo add serde --features derive` then `cargo add serde_json`.) `src/main.rs`: ```rust 1 use serde::Serialize; 2 3 #[derive(Serialize)] 4 struct Point { 5 x: i32, 6 y: i32, 7 } 8 9 fn main() { 10 let p = Point { x: 3, y: 4 }; 11 let json = serde_json::to_string(&p).unwrap(); 12 println!("{json}"); 13 } ``` Real output: ```text 1 {"x":3,"y":4} ``` Without `features = ["derive"]`, this fails with `error: cannot find derive macro \`Serialize\` in this scope\`, exactly Pitfall 1. ### Exercise 3: Tune a release profile for a small, fast binary [Section titled “Exercise 3: Tune a release profile for a small, fast binary”](#exercise-3-tune-a-release-profile-for-a-small-fast-binary) **Difficulty:** Advanced **Objective:** Use `[profile.release]` to trade compile time for a smaller, optimized binary, and observe the difference. **Instructions:** Take any binary crate (e.g. the `taskcli` example) and add a `[profile.release]` that maximizes optimization, enables link-time optimization, uses a single codegen unit, and strips symbols. Build with `cargo build` and `cargo build --release` and compare the file sizes of `target/debug/<name>` and `target/release/<name>`. Explain *why* you would not put these settings in `[profile.dev]`. Solution Cargo.toml ```toml 1 [profile.release] 2 opt-level = 3 # maximum optimization (the release default already) 3 lto = true # link-time optimization across all crates 4 codegen-units = 1 # one unit -> best optimization, slowest/least-parallel compile 5 strip = true # remove debug symbols from the final binary ``` Compare the builds: ```bash 1 cargo build 2 cargo build --release 3 ls -l target/debug/taskcli target/release/taskcli ``` With the `taskcli` example, the stripped+LTO release binary comes out **noticeably smaller** than the debug binary (on one macOS arm64 / Rust 1.96 run, roughly 2-3x smaller; your exact byte counts will differ). Build times are platform- and cache-dependent: a clean build of either profile is dominated by compiling dependencies, and a cached rebuild of just this crate finishes far faster for `dev` than for the optimization-heavy `release`. Why not in `[profile.dev]`? `dev` is your edit-compile-run loop. `lto = true` and `codegen-units = 1` disable parallel codegen and cross-crate optimization passes, which can multiply local compile times for no runtime benefit you care about while debugging. You want fast feedback in `dev` and a tuned artifact only in `release` (typically built once in CI). Stripping symbols in `dev` would also hurt debugging. Keep optimization aggression in `release`, keep `dev` fast. # Cargo Commands > One cargo CLI replaces npm, tsc, eslint, prettier, and jest: build, run, check, test, fmt, clippy, doc, add, plus new vs init, identical in every Rust project. Cargo is the command you will type hundreds of times a day. It is Rust’s build tool, test runner, formatter front-end, linter front-end, documentation generator, and package manager, all behind one consistent CLI. This file is your reference for the everyday commands and the difference between `cargo new` and `cargo init`. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Where a Node.js project juggles `npm`, `tsc`, `jest`, `prettier`, `eslint`, and `typedoc`, Rust uses a single tool: **Cargo**. The same handful of subcommands work in every Rust project with zero configuration, because the conventions (where source lives, how tests are written, how the binary is named) are baked into the language and toolchain. This page focuses on the commands themselves; the [Cargo.toml manifest](/12-modules-packages/04-cargo/) and [dependency management](/12-modules-packages/06-dependencies/) live in sibling files. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) A typical Node.js/TypeScript project wires up its workflow through `package.json` scripts, each delegating to a different tool you installed separately: ```json 1 { 2 "name": "user-service", 3 "version": "1.0.0", 4 "scripts": { 5 "build": "tsc", 6 "start": "node dist/index.js", 7 "dev": "tsx src/index.ts", 8 "test": "vitest run", 9 "lint": "eslint .", 10 "format": "prettier --write .", 11 "docs": "typedoc" 12 }, 13 "devDependencies": { 14 "typescript": "^5.6.0", 15 "tsx": "^4.19.0", 16 "vitest": "^2.1.0", 17 "eslint": "^9.0.0", 18 "prettier": "^3.3.0", 19 "typedoc": "^0.26.0" 20 } 21 } ``` A new contributor has to read `package.json` to learn that “run the app” is `npm run dev`, “test” is `npm test`, and “format” is `npm run format`. Every project invents its own script names. ```bash 1 npm install # Install dependencies 2 npm run dev # Run in watch mode 3 npm test # Run tests 4 npm run lint # Lint 5 npm run format # Format 6 npm run build # Compile to dist/ ``` *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) In Rust, the same workflow uses standard Cargo subcommands that are identical across every project. There is no `scripts` table to define or memorize: ```bash 1 # Create a new binary project (the equivalent of `npm init` + scaffolding) 2 cargo new user-service 3 cd user-service 4 5 # Add dependencies (writes to Cargo.toml, like `npm install <pkg>`) 6 cargo add serde --features derive 7 cargo add --dev assert_cmd # a dev-only dependency 8 9 cargo check # Type-check without producing a binary (fastest feedback loop) 10 cargo run # Build + run the binary 11 cargo test # Run all tests (unit, integration, and doctests) 12 cargo clippy # Lint (the eslint equivalent) 13 cargo fmt # Format (the prettier equivalent) 14 cargo doc --open # Generate HTML docs and open them (the typedoc equivalent) 15 cargo build --release # Optimized production build ``` > **Tip:** Because these commands are universal, you can clone any Rust project and immediately know that `cargo run` runs it, `cargo test` tests it, and `cargo build --release` produces the optimized artifact. No per-project script archaeology required. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `cargo new` — scaffold a brand-new project [Section titled “cargo new — scaffold a brand-new project”](#cargo-new--scaffold-a-brand-new-project) `cargo new <name>` creates a new directory, lays out the standard structure, and initializes a Git repository. Here is the real output and resulting tree: ```bash 1 $ cargo new hello 2 Creating binary (application) `hello` package 3 note: see more `Cargo.toml` keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html ``` ```text 1 hello 2 ├── .git/ 3 ├── .gitignore # contains just `/target` 4 ├── Cargo.toml # the manifest (like package.json) 5 └── src/ 6 └── main.rs # entry point with a `fn main` that prints "Hello, world!" ``` By default you get a **binary** (executable) crate. Pass `--lib` for a **library** crate, which produces `src/lib.rs` instead of `src/main.rs`: ```bash 1 cargo new my_app # binary -> src/main.rs 2 cargo new my_lib --lib # library -> src/lib.rs ``` The `edition` field in the generated `Cargo.toml` is filled in for you with the newest edition your toolchain supports. On a current stable toolchain that is `"2024"` (the latest stable edition). You never pick an edition by hand for a new project. > **Note:** The crate name in `Cargo.toml` follows Rust’s `snake_case` convention. If you write `cargo new my-service`, the directory is `my-service` but the crate name becomes `my_service` (hyphens are not valid in Rust identifiers). This is unlike npm, where `@scope/my-service` is a perfectly normal package name. ### `cargo init` — adopt an existing directory [Section titled “cargo init — adopt an existing directory”](#cargo-init--adopt-an-existing-directory) `cargo init` does the same scaffolding as `cargo new`, but **in the current (already-existing) directory** instead of creating a new one. This is the analog of running `npm init` inside a folder you already have: ```bash 1 $ mkdir existing_app && cd existing_app 2 $ cargo init 3 Creating binary (application) package 4 note: see more `Cargo.toml` keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html ``` ```text 1 existing_app/ 2 ├── .git/ 3 ├── .gitignore 4 ├── Cargo.toml 5 └── src/ 6 └── main.rs ``` `cargo init` is what you reach for when you have a directory with, say, a `README.md` and a `.git` already (perhaps from `git clone`) and you want to turn it into a Cargo project without nesting another folder inside it. Like `cargo new`, it accepts `--lib`. > **Note:** `cargo init` will **not** clobber an existing `src/main.rs` or `Cargo.toml`; it only adds what is missing. If the directory is already a Git repo, it skips Git initialization rather than re-running it. ### `cargo check` — fastest feedback [Section titled “cargo check — fastest feedback”](#cargo-check--fastest-feedback) `cargo check` runs the full compiler front-end — parsing, type checking, borrow checking — but stops **before** code generation and linking. It catches every type error and borrow error without spending time producing a runnable binary, so it is dramatically faster than a full build. Use it as your inner loop; it is the closest thing to `tsc --noEmit`. ```bash 1 $ cargo check 2 Checking greeter v0.1.0 (/path/to/greeter) 3 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.11s ``` ### `cargo build` — compile to an artifact [Section titled “cargo build — compile to an artifact”](#cargo-build--compile-to-an-artifact) `cargo build` compiles your crate and all its dependencies into an actual binary (or `.rlib` for a library). Debug builds land in `target/debug/`; release builds in `target/release/`. ```bash 1 $ cargo build 2 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.21s 3 4 $ cargo build --release 5 Compiling args_demo v0.1.0 (/path/to/args_demo) 6 Finished `release` profile [optimized] target(s) in 0.17s ``` The default **debug** profile compiles fast and includes debug info but does little optimization. The `--release` profile turns on optimizations (`opt-level = 3` by default), producing a much faster binary at the cost of a slower compile. Use debug while developing, `--release` for benchmarks and production. Profile configuration is covered in [Cargo.toml](/12-modules-packages/04-cargo/). ### `cargo run` — build and execute [Section titled “cargo run — build and execute”](#cargo-run--build-and-execute) `cargo run` builds the binary (if needed) and then runs it. If nothing changed since the last build, it skips straight to running: ```bash 1 $ cargo run 2 Compiling args_demo v0.1.0 (/path/to/args_demo) 3 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.21s 4 Running `target/debug/args_demo` 5 No arguments given. ``` To pass arguments **to your program** (rather than to Cargo), put them after a `--` separator. Everything before `--` is a Cargo flag; everything after goes to your binary’s `std::env::args()`: ```bash 1 $ cargo run -- alice bob 2 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.00s 3 Running `target/debug/args_demo alice bob` 4 You passed 2 argument(s): ["alice", "bob"] ``` This `--` convention matches `npm run <script> -- <args>` in spirit. The `--release` flag goes *before* `--`, because it is a Cargo flag: ```bash 1 cargo run --release -- --config prod.toml ``` If your project has more than one binary, Cargo cannot guess which to run and tells you so: ```bash 1 $ cargo run 2 error: `cargo run` could not determine which binary to run. Use the `--bin` option to specify a binary, or the `default-run` manifest key. 3 available binaries: seed, toolbox ``` Pick one with `--bin`: ```bash 1 $ cargo run --bin seed 2 Compiling toolbox v0.1.0 (/path/to/toolbox) 3 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.14s 4 Running `target/debug/seed` 5 seeding database... ``` ### `cargo test` — run every kind of test [Section titled “cargo test — run every kind of test”](#cargo-test--run-every-kind-of-test) `cargo test` compiles your code in test mode and runs all `#[test]` functions, integration tests in `tests/`, and **doctests** (the runnable examples in your `///` doc comments). No test runner to install or configure. For a library crate with three unit tests: ```bash 1 $ cargo test 2 Compiling calc v0.1.0 (/path/to/calc) 3 Finished `test` profile [unoptimized + debuginfo] target(s) in 0.16s 4 Running unittests src/lib.rs (target/debug/deps/calc-9612d1c07b9ca2bd) 5 6 running 3 tests 7 test tests::test_add ... ok 8 test tests::test_multiply ... ok 9 test tests::test_add_negative ... ok 10 11 test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s 12 13 Doc-tests calc 14 15 running 0 tests 16 17 test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` You can run a subset by passing a substring filter; every test whose full path contains it runs: ```bash 1 $ cargo test add 2 Running unittests src/lib.rs (target/debug/deps/calc-9612d1c07b9ca2bd) 3 4 running 2 tests 5 test tests::test_add_negative ... ok 6 test tests::test_add ... ok 7 8 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out; finished in 0.00s ``` Notice the `1 filtered out`: `test_multiply` did not match the `add` filter. To see `println!` output from passing tests (Cargo captures it by default), pass `-- --nocapture` (everything after `--` goes to the test harness, not Cargo). Testing gets a whole section of its own; see [Section 13: Testing](/13-testing/). ### `cargo fmt` — format code [Section titled “cargo fmt — format code”](#cargo-fmt--format-code) `cargo fmt` runs `rustfmt` over your whole crate, rewriting files in place to the canonical Rust style. It is the `prettier --write` equivalent, but the style is community-standard and essentially non-configurable, which ends bikeshedding. To check formatting without modifying files (for CI), use `--check`: ```bash 1 $ cargo fmt --check 2 Diff in /path/to/fmt_demo/src/main.rs:1: 3 fn main() { 4 -let name="world"; 5 + let name = "world"; 6 println!("Hello, {name}!"); 7 } ``` `cargo fmt --check` exits with a non-zero status (`1`) when reformatting is needed, which is exactly what you want in a CI gate. ### `cargo clippy` — lint [Section titled “cargo clippy — lint”](#cargo-clippy--lint) `cargo clippy` is Rust’s linter, the `eslint` equivalent, with hundreds of built-in lints that catch bugs, non-idiomatic code, and performance footguns. Given this code: ```rust 1 fn main() { 2 let ready = true; 3 if ready == true { 4 println!("Starting up..."); 5 } 6 } ``` Clippy produces a real, actionable warning: ```bash 1 $ cargo clippy 2 Checking lint_demo v0.1.0 (/path/to/lint_demo) 3 warning: equality checks against true are unnecessary 4 --> src/main.rs:3:8 5 | 6 3 | if ready == true { 7 | ^^^^^^^^^^^^^ help: try simplifying it as shown: `ready` 8 | 9 = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#bool_comparison 10 = note: `#[warn(clippy::bool_comparison)]` on by default 11 12 warning: `lint_demo` (bin "lint_demo") generated 1 warning (run `cargo clippy --fix --bin "lint_demo"` to apply 1 suggestion) 13 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.09s ``` In CI you typically promote warnings to errors with `-- -D warnings`, which makes any lint fail the build: ```bash 1 $ cargo clippy -- -D warnings 2 ... 3 = note: `-D clippy::bool-comparison` implied by `-D warnings` 4 = help: to override `-D warnings` add `#[allow(clippy::bool_comparison)]` 5 6 error: could not compile `lint_demo` (bin "lint_demo") due to 1 previous error ``` Many lints carry machine-applicable fixes; `cargo clippy --fix` rewrites your code to apply them automatically. ### `cargo doc` — generate documentation [Section titled “cargo doc — generate documentation”](#cargo-doc--generate-documentation) `cargo doc` builds HTML documentation from your `///` doc comments. `--open` launches it in your browser; `--no-deps` skips documenting your dependencies (faster, and usually what you want locally): ```bash 1 $ cargo doc --no-deps 2 Documenting docgen v0.1.0 (/path/to/docgen) 3 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.40s 4 Generated /path/to/docgen/target/doc/docgen/index.html ``` The generated docs include cross-linked types, source links, and rendered examples: the same machinery that produces [docs.rs](https://docs.rs). Importantly, the examples in your doc comments are *tested* by `cargo test`, so your documentation cannot silently rot. ### `cargo add` — manage dependencies from the CLI [Section titled “cargo add — manage dependencies from the CLI”](#cargo-add--manage-dependencies-from-the-cli) `cargo add <crate>` resolves the latest compatible version, writes it into `Cargo.toml`, and updates `Cargo.lock`. It is the `npm install <pkg>` equivalent and has been **built into Cargo since 1.62**: you do *not* need to install `cargo-edit` first, despite what older tutorials claim. ```bash 1 $ cargo add serde --features derive 2 Adding serde v1.0.228 to dependencies 3 Features: 4 + derive 5 + serde_derive 6 + std 7 - alloc 8 - rc 9 - unstable 10 Locking 7 packages to latest Rust 1.96.0 compatible versions ``` The resulting `Cargo.toml`: ```toml 1 [dependencies] 2 serde = { version = "1.0.228", features = ["derive"] } ``` Add to `[dev-dependencies]` with `--dev`: ```bash 1 $ cargo add --dev criterion 2 Adding criterion v0.8.2 to dev-dependencies ``` The full story of version requirements, feature flags, and git/path dependencies lives in [Dependencies](/12-modules-packages/06-dependencies/) and [Dev Dependencies](/12-modules-packages/07-dev-dependencies/). ### Discovering commands [Section titled “Discovering commands”](#discovering-commands) `cargo --list` prints every available subcommand, including aliases (`b` = `build`, `c` = `check`, `r` = `run`, `d` = `doc`) and any third-party subcommands you have installed: ```bash 1 $ cargo --list 2 Installed Commands: 3 add Add dependencies to a Cargo.toml manifest file 4 b alias: build 5 bench Execute all benchmarks of a local package 6 build Compile a local package and all of its dependencies 7 c alias: check 8 check Check a local package and all of its dependencies for errors 9 clean Remove artifacts that cargo has generated in the past 10 clippy Checks a package to catch common mistakes and improve your Rust code. 11 ... 12 new Create a new cargo package at <path> 13 ... 14 run Run a binary or example of the local package ``` *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Task | Node.js / TypeScript | Rust (Cargo) | | ------------------------- | ---------------------------------------------- | ----------------------------------------------- | | Scaffold new project | `npm init -y` + manual `src/`, `tsconfig.json` | `cargo new <name>` (one command) | | Initialize in current dir | `npm init` | `cargo init` | | Install a dependency | `npm install <pkg>` | `cargo add <crate>` | | Install a dev dependency | `npm install -D <pkg>` | `cargo add --dev <crate>` | | Type-check only | `tsc --noEmit` | `cargo check` | | Build | `tsc` / `webpack` / `vite build` | `cargo build` (debug) / `cargo build --release` | | Run | `node dist/index.js` / `tsx src/index.ts` | `cargo run` | | Test | `jest` / `vitest` (separate install) | `cargo test` (built in) | | Format | `prettier --write .` (separate install) | `cargo fmt` | | Lint | `eslint .` (separate install) | `cargo clippy` | | Docs | `typedoc` (separate install) | `cargo doc` | | Pass args to program | `npm start -- <args>` | `cargo run -- <args>` | ### Conventions over configuration [Section titled “Conventions over configuration”](#conventions-over-configuration) The biggest mental shift is that Cargo commands are **universal**. In Node.js, “test” might be `jest`, `vitest`, `mocha`, `npm test`, or `npm run test:unit`. It depends entirely on what each project’s `package.json` declares. In Rust, `cargo test` always means the same thing because the entry point (`src/main.rs` or `src/lib.rs`), the test attribute (`#[test]`), and the build profiles are part of the toolchain, not per-project config. ### `check` vs `build` — a tool TypeScript doesn’t separate [Section titled “check vs build — a tool TypeScript doesn’t separate”](#check-vs-build--a-tool-typescript-doesnt-separate) `cargo check` has no everyday TypeScript equivalent that most developers use. It skips code generation entirely, so it is the right command for “does my code compile?” while you iterate. Reach for `cargo build` only when you actually need the artifact, and `cargo run` when you want to execute it. This three-way split (`check` / `build` / `run`) is finer-grained than the typical `tsc` → `node` two-step. ### One lockfile philosophy difference [Section titled “One lockfile philosophy difference”](#one-lockfile-philosophy-difference) `cargo add` and `cargo build` write `Cargo.lock`, analogous to `package-lock.json`. The convention differs from npm’s “always commit it”: you commit `Cargo.lock` for **binaries** (reproducible deployments) but conventionally omit it for **libraries** (so downstream users resolve their own compatible versions). See [Cargo.toml](/12-modules-packages/04-cargo/) for details. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting the `--` separator [Section titled “Pitfall 1: Forgetting the -- separator”](#pitfall-1-forgetting-the----separator) A TypeScript developer used to `node dist/index.js --port 8080` may write: ```bash 1 cargo run --port 8080 ``` Cargo interprets `--port` as one of *its own* flags and errors out (`cargo run` has no `--port` option). The fix is to separate your program’s arguments with `--`: ```bash 1 cargo run -- --port 8080 ``` Everything after `--` is handed to your binary untouched. ### Pitfall 2: Running `cargo run` in a library crate [Section titled “Pitfall 2: Running cargo run in a library crate”](#pitfall-2-running-cargo-run-in-a-library-crate) If you create a project with `cargo new my_lib --lib`, there is no binary to run, and `cargo run` fails: ```bash 1 $ cargo run 2 error: a bin target must be available for `cargo run` ``` Libraries are *consumed* by other crates and tested with `cargo test`; they are not executed directly. If you want a runnable entry point, add a `src/main.rs` (or a `src/bin/*.rs`) so the crate also produces a binary. ### Pitfall 3: Assuming `cargo new` runs in the current directory [Section titled “Pitfall 3: Assuming cargo new runs in the current directory”](#pitfall-3-assuming-cargo-new-runs-in-the-current-directory) `cargo new my_app` *creates a new subdirectory* called `my_app`. If you have already `cd`’d into the folder you want to use, `cargo new my_app` nests `./my_app/my_app/`. Use `cargo init` to scaffold *in place*: ```bash 1 mkdir my_app && cd my_app 2 cargo init # initializes the current directory 3 # cargo new my_app # would create my_app/my_app ``` ### Pitfall 4: Expecting `cargo build` to be the inner loop [Section titled “Pitfall 4: Expecting cargo build to be the inner loop”](#pitfall-4-expecting-cargo-build-to-be-the-inner-loop) Coming from `tsc`, you might run `cargo build` constantly. It works, but it spends time on code generation and linking you do not need while merely checking for errors. `cargo check` is several times faster for that purpose. Save `cargo build`/`cargo run` for when you actually need to execute the result. ### Pitfall 5: Thinking `cargo add` needs `cargo-edit` [Section titled “Pitfall 5: Thinking cargo add needs cargo-edit”](#pitfall-5-thinking-cargo-add-needs-cargo-edit) Older blog posts and Stack Overflow answers say “first `cargo install cargo-edit`, then `cargo add`.” That has not been necessary since Cargo 1.62 (June 2022). `cargo add` and `cargo remove` ship with Cargo. (`cargo-edit` still provides extras like `cargo upgrade`, but not the basic add/remove.) *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Use `cargo check` as your default inner loop.** Switch to `cargo run` only when you need to see the program execute. Pair it with an editor running rust-analyzer for instant feedback. * **Gate CI on formatting and lints.** Run `cargo fmt --check` and `cargo clippy -- -D warnings` in CI so that unformatted or lint-dirty code cannot merge. Both exit non-zero on failure, which CI systems treat as a failed step. * **Build `--release` only when it matters.** Release builds are slow to compile. Use them for production artifacts, benchmarks, and performance testing, not for routine development. * **Prefer `cargo add` over hand-editing `Cargo.toml`** for adding dependencies: it picks a current version, sorts features, and updates `Cargo.lock` in one step. Hand-edit only when you need something unusual. * **Learn the one-letter aliases** (`cargo c`, `cargo b`, `cargo r`, `cargo t` is *not* built in but `cargo test` is short anyway) to shave keystrokes, but write the full names in scripts and docs for clarity. * **Reach for `cargo new --lib`** when starting reusable code, and `cargo new` (binary) for applications. You can always add a `src/lib.rs` later to make a binary crate also expose a library. > **Tip:** A clean pre-commit/CI sequence for a Rust project is: `cargo fmt --check && cargo clippy -- -D warnings && cargo test`. It mirrors the `prettier --check && eslint && vitest run` you’d run in a TypeScript repo, but with zero tooling to install. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) Here is the complete lifecycle of a small library crate, `slugify`, from scaffolding through the full quality-gate sequence you’d run locally and in CI. Every command below produces the real output shown. **1. Scaffold a library crate:** ```bash 1 $ cargo new slugify --lib 2 Creating library `slugify` package 3 note: see more `Cargo.toml` keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html ``` **2. Write the library (`src/lib.rs`):** ````rust 1 //! Turn arbitrary titles into URL-friendly slugs. 2 3 /// Converts a title into a lowercase, hyphen-separated slug. 4 /// 5 /// # Examples 6 /// 7 /// ``` 8 /// use slugify::slugify; 9 /// assert_eq!(slugify("Hello, World!"), "hello-world"); 10 /// ``` 11 pub fn slugify(title: &str) -> String { 12 title 13 .chars() 14 .map(|c| { 15 if c.is_alphanumeric() { 16 c.to_ascii_lowercase() 17 } else { 18 ' ' 19 } 20 }) 21 .collect::<String>() 22 .split_whitespace() 23 .collect::<Vec<_>>() 24 .join("-") 25 } 26 27 #[cfg(test)] 28 mod tests { 29 use super::*; 30 31 #[test] 32 fn collapses_whitespace_and_punctuation() { 33 assert_eq!(slugify(" Rust for TS devs! "), "rust-for-ts-devs"); 34 } 35 36 #[test] 37 fn lowercases() { 38 assert_eq!(slugify("CamelCase"), "camelcase"); 39 } 40 } ```` **3. Run the quality gate** (`fmt`, `clippy`, `test`), the same commands you’d put in CI: ```bash 1 $ cargo fmt --check # exits 0: already formatted 2 $ cargo clippy -- -D warnings 3 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.08s 4 $ cargo test 5 running 2 tests 6 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s 7 running 1 test 8 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` Note the **two** test groups: the first `2 passed` is the unit tests in the `tests` module; the second `1 passed` is the **doctest** from the `# Examples` block in the doc comment. The example in your docs is verified to be correct, for free. **4. Generate the docs:** ```bash 1 $ cargo doc --no-deps --open # builds HTML and opens it in the browser ``` For a production-flavored CI configuration, this maps directly onto a GitHub Actions job: .github/workflows/ci.yml ```yaml 1 jobs: 2 check: 3 runs-on: ubuntu-latest 4 steps: 5 - uses: actions/checkout@v4 6 - run: cargo fmt --check 7 - run: cargo clippy -- -D warnings 8 - run: cargo test ``` This is the same set of standard commands working unchanged, which is exactly the point: no per-project script names to invent. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Cargo Book](https://doc.rust-lang.org/cargo/) — the complete reference * [Cargo Commands Index](https://doc.rust-lang.org/cargo/commands/index.html) — every subcommand documented * [`cargo new` / `cargo init`](https://doc.rust-lang.org/cargo/commands/cargo-init.html) * [Clippy lint list](https://rust-lang.github.io/rust-clippy/master/index.html) — searchable catalog of every lint * [rustfmt configuration](https://rust-lang.github.io/rustfmt/) — the formatter’s (rarely needed) options ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Understanding Cargo](/01-getting-started/03-cargo-basics/) — the gentle introduction in Section 01 * [Hello World](/01-getting-started/02-hello-world/) — your first `cargo run` * [Cargo.toml](/12-modules-packages/04-cargo/) — the manifest, profiles, and `Cargo.lock` * [Dependencies](/12-modules-packages/06-dependencies/) — semver requirements, features, git/path deps * [Dev Dependencies](/12-modules-packages/07-dev-dependencies/) — `[dev-dependencies]` and `[build-dependencies]` * [Workspaces](/12-modules-packages/08-workspaces/) — running Cargo commands across a monorepo * [Feature Flags](/12-modules-packages/09-feature-flags/) — building with `--features` * [Publishing](/12-modules-packages/11-publishing/) — `cargo publish` and crates.io * [Section 13: Testing](/13-testing/) — everything `cargo test` can do *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Scaffold and run [Section titled “Exercise 1: Scaffold and run”](#exercise-1-scaffold-and-run) **Difficulty:** Easy **Objective:** Get comfortable with `cargo new` and the `--` argument separator. **Instructions:** 1. Create a new binary project named `greeter` with one command. 2. Edit `src/main.rs` so it reads command-line arguments and prints `Hello, <name>!` for each name passed, or `Hello, world!` if none are given. 3. Run it with no arguments, then run it with `cargo run -- Ada Grace` and confirm both names print. Solution ```bash 1 cargo new greeter 2 cd greeter ``` src/main.rs ```rust 1 use std::env; 2 3 fn main() { 4 let names: Vec<String> = env::args().skip(1).collect(); 5 if names.is_empty() { 6 println!("Hello, world!"); 7 } else { 8 for name in names { 9 println!("Hello, {name}!"); 10 } 11 } 12 } ``` ```bash 1 $ cargo run 2 Running `target/debug/greeter` 3 Hello, world! 4 5 $ cargo run -- Ada Grace 6 Running `target/debug/greeter Ada Grace` 7 Hello, Ada! 8 Hello, Grace! ``` `env::args()` yields the program name as the first element, so `.skip(1)` drops it. The `--` separator is what makes `Ada` and `Grace` reach your program instead of being parsed as Cargo flags. ### Exercise 2: `init` an existing directory and add a dependency [Section titled “Exercise 2: init an existing directory and add a dependency”](#exercise-2-init-an-existing-directory-and-add-a-dependency) **Difficulty:** Medium **Objective:** Practice `cargo init` (vs `cargo new`) and `cargo add`. **Instructions:** 1. Create an empty directory `dice` and `cd` into it. 2. Turn it into a Cargo binary project *in place* (do not create a nested folder). 3. Add the `rand` crate as a dependency from the command line. 4. Make `main` print a random dice roll between 1 and 6 inclusive, then run it. Solution ```bash 1 mkdir dice 2 cd dice 3 cargo init # initializes the CURRENT directory 4 cargo add rand # writes rand to [dependencies] and updates Cargo.lock ``` src/main.rs ```rust 1 use rand::RngExt; 2 3 fn main() { 4 let roll = rand::rng().random_range(1..=6); 5 println!("You rolled a {roll}"); 6 } ``` ```bash 1 $ cargo run 2 Compiling dice v0.1.0 (/path/to/dice) 3 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.9s 4 Running `target/debug/dice` 5 You rolled a 4 ``` > **Note:** This uses current rand 0.10 idioms: `rand::rng()` (not the old 0.8 `thread_rng()`) and `random_range()` via the `RngExt` trait (not the old `gen_range()`). In rand 0.10 the range-sampling method lives on `RngExt`, so you import `rand::RngExt` rather than `rand::Rng`. Using `cargo init` instead of `cargo new dice` keeps everything in the directory you already created rather than nesting `dice/dice/`. ### Exercise 3: A full quality gate on a library [Section titled “Exercise 3: A full quality gate on a library”](#exercise-3-a-full-quality-gate-on-a-library) **Difficulty:** Medium **Objective:** Run the same `fmt` / `clippy` / `test` sequence used in CI, and use the `cargo test` filter. **Instructions:** 1. Create a *library* crate named `mathkit`. 2. Add two public functions, `is_even(n: i64) -> bool` and `factorial(n: u64) -> u64`, each with a unit test, plus one doctest example on `factorial`. 3. Run `cargo fmt --check`, then `cargo clippy -- -D warnings`, then `cargo test`. Fix anything the first two report. 4. Run only the factorial-related tests using a `cargo test` filter, and confirm the even-number test is reported as filtered out. Solution ```bash 1 cargo new mathkit --lib 2 cd mathkit ``` src/lib.rs ````rust 1 /// Returns `true` if `n` is even. 2 pub fn is_even(n: i64) -> bool { 3 n % 2 == 0 4 } 5 6 /// Computes `n!` (factorial). 7 /// 8 /// # Examples 9 /// 10 /// ``` 11 /// use mathkit::factorial; 12 /// assert_eq!(factorial(5), 120); 13 /// ``` 14 pub fn factorial(n: u64) -> u64 { 15 (1..=n).product() 16 } 17 18 #[cfg(test)] 19 mod tests { 20 use super::*; 21 22 #[test] 23 fn test_is_even() { 24 assert!(is_even(4)); 25 assert!(!is_even(7)); 26 } 27 28 #[test] 29 fn test_factorial() { 30 assert_eq!(factorial(0), 1); 31 assert_eq!(factorial(4), 24); 32 } 33 } ```` Run the gate: ```bash 1 $ cargo fmt --check # exits 0 if formatted 2 $ cargo clippy -- -D warnings # exits 0 if no lints 3 $ cargo test 4 running 2 tests 5 test tests::test_is_even ... ok 6 test tests::test_factorial ... ok 7 8 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s 9 ... 10 Doc-tests mathkit 11 running 1 test 12 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` Filter to just the factorial tests: ```bash 1 $ cargo test factorial 2 running 1 test 3 test tests::test_factorial ... ok 4 5 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out; finished in 0.00s ``` The `1 filtered out` confirms `test_is_even` was skipped because its name does not contain `factorial`. The doctest on `factorial` runs as part of `cargo test`, so the example in the documentation is guaranteed correct. # Specifying Dependencies: `cargo add`, SemVer, Features, and Git/Path Sources > cargo add is npm install, but a bare version is already a caret range. Covers SemVer grammar, features, default-features, and git, path, and registry sources. `cargo add` is `npm install`, and a line in `[dependencies]` is a line in `package.json`’s `dependencies`. But the resemblance hides important differences: a bare version string in Cargo is already a caret range, features replace npm’s “install the optional thing” guesswork, and you can pull a crate straight from a git repository or a folder on disk. This page is the practical grammar of declaring what your crate depends on. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In Rust you add a **crate** (Rust’s word for a package) with `cargo add <name>`, which edits `[dependencies]` in `Cargo.toml` and re-resolves the lockfile, exactly like `npm install <name>` editing `package.json` and `package-lock.json`. The two ideas with no clean npm analogue are **features** (opt-in, compile-time capabilities a crate exposes) and the fact that Cargo can resolve a dependency from **crates.io**, a **git repository**, or a **local path** with the same uniform syntax. This page covers `cargo add`, the full SemVer requirement grammar (caret, tilde, exact, comparison, wildcard), enabling features, and git/path sources; the manifest’s overall shape lives in [Cargo.toml](/12-modules-packages/04-cargo/), and feature *design* is covered in [Feature Flags and Conditional Compilation](/12-modules-packages/09-feature-flags/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In a Node project you install dependencies with npm, which writes them into `package.json` and pins the full tree in `package-lock.json`: ```bash 1 # Add runtime deps; npm writes a caret range like "^1.0.0" by default 2 npm install zod 3 npm install chalk@5.3.0 # a specific version 4 npm install some-fork --save # from the default registry 5 6 # You can also depend on a git repo or a local folder: 7 npm install github:colinhacks/zod # straight from GitHub 8 npm install ../shared-utils # a sibling folder on disk ``` The resulting `package.json`: ```jsonc 1 { 2 "dependencies": { 3 "zod": "^3.23.0", // caret: >=3.23.0 <4.0.0 4 "chalk": "5.3.0", // NO caret -> exactly 5.3.0 5 "shared-utils": "file:../shared-utils", // local path 6 "fork": "github:colinhacks/zod" // git source 7 } 8 } ``` To enable an optional capability there is no first-class mechanism: you either install an extra companion package, or a library reads an environment variable / config flag at runtime. npm has no concept of “compile this part of the dependency in, leave that part out.” *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same set of moves with Cargo. `cargo add` (built into Cargo since 1.62; **no `cargo-edit` install needed**) edits the manifest for you: ```bash 1 # Add from crates.io; Cargo writes the resolved version, treated as a CARET range 2 cargo add serde --features derive # add a crate AND turn on a feature 3 cargo add serde_json 4 cargo add regex@1.10 # constrain to a SemVer requirement 5 6 # From a local folder (a sibling crate on disk): 7 cargo add geometry --path ../geometry 8 9 # Straight from a git repository: 10 cargo add anyhow --git https://github.com/dtolnay/anyhow ``` Running `cargo add serde --features derive` prints the real output below; note how Cargo lists every feature and marks which are on (`+`) and off (`-`): ```text 1 Updating crates.io index 2 Adding serde v1.0.228 to dependencies 3 Features: 4 + derive 5 + serde_derive 6 + std 7 - alloc 8 - rc 9 - unstable 10 Updating crates.io index 11 Locking 7 packages to latest Rust 1.96.0 compatible versions ``` The resulting `Cargo.toml`: ```toml 1 [dependencies] 2 serde = { version = "1.0.228", features = ["derive"] } 3 serde_json = "1.0.150" 4 regex = "1.10" 5 geometry = { version = "0.1.0", path = "../geometry" } 6 anyhow = { git = "https://github.com/dtolnay/anyhow", version = "1.0.102" } ``` > **Note:** Cargo writes the **full resolved version** (`"1.0.228"`), but that string is still a *caret* requirement, not an exact pin; see the next section. The byte-exact tree is pinned separately in `Cargo.lock`, the twin of `package-lock.json`. A small program that exercises the crates.io dependencies above (compile-verified): src/main.rs ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 struct ServerConfig { 5 host: String, 6 port: u16, 7 #[serde(default)] 8 tls: bool, 9 } 10 11 fn main() { 12 let raw = r#"{ "host": "0.0.0.0", "port": 8080 }"#; 13 let cfg: ServerConfig = serde_json::from_str(raw).expect("valid config"); 14 println!("parsed: {cfg:?}"); 15 println!("re-serialized: {}", serde_json::to_string(&cfg).unwrap()); 16 } ``` Real output: ```text 1 parsed: ServerConfig { host: "0.0.0.0", port: 8080, tls: false } 2 re-serialized: {"host":"0.0.0.0","port":8080,"tls":false} ``` *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `cargo add` vs `npm install` [Section titled “cargo add vs npm install”](#cargo-add-vs-npm-install) `cargo add <crate>` does three things, just like `npm install <pkg>`: 1. Contacts the registry (crates.io by default) to find the latest compatible version. 2. Writes a line into `[dependencies]` in `Cargo.toml`. 3. Updates `Cargo.lock` with the resolved version and a checksum. Unlike `npm install` with no arguments (which installs everything already listed), there is no `cargo install` for project dependencies. That command installs *binaries* globally, like `npm install -g`. To download/build what’s already in your manifest, you just run `cargo build`; Cargo fetches missing crates automatically. There is no `node_modules/`: crate *sources* are cached once in `~/.cargo/registry/` and compiled into your project’s `target/` directory. ### SemVer requirements: the part TypeScript developers misread [Section titled “SemVer requirements: the part TypeScript developers misread”](#semver-requirements-the-part-typescript-developers-misread) This is the single biggest gotcha. In `package.json`, a version with **no prefix** means *exactly that version*: ```jsonc 1 "chalk": "5.3.0" // npm: EXACTLY 5.3.0 ``` In `Cargo.toml`, a bare version string is a **caret requirement**, the same as if you’d written `^` in npm: ```toml 1 regex = "1.10" // Cargo: ^1.10 == >=1.10.0, <2.0.0 ``` Cargo supports five requirement operators. Each row below was verified by resolving it against the live crates.io index: | Requirement | Meaning | Verified resolution (latest available) | | -------------------- | ---------------------------------------- | --------------------------------------------------------------- | | `"1.0"` (caret) | `>=1.0.0, <2.0.0`, any compatible 1.x | `serde_json = "1.0"` → resolved **1.0.150** | | `"~1.10.0"` (tilde) | `>=1.10.0, <1.11.0` — patch updates only | `regex = "~1.10.0"` → resolved **1.10.6** (while 1.12.3 exists) | | `"=1.0.100"` (exact) | exactly that version | `serde_json = "=1.0.100"` → resolved **1.0.100** | | `">=1.5, <1.11"` | a comparison range (comma = AND) | `regex = ">=1.5, <1.11"` → resolved **1.10.6** | | `"1.*"` (wildcard) | any 1.x (`*` matches any value) | `regex = "1.*"` → resolved **1.12.3** | The key insights for a TypeScript/JavaScript developer: * **Caret is the default and the idiom.** Writing `"1"`, `"1.0"`, or `"1.0.150"` all mean “any 1.x at or above this”. Prefer the shortest form that expresses your floor; `"1"` is common and perfectly idiomatic. * **Caret on a `0.x` version is special.** Just like npm, `^0.3` means `>=0.3.0, <0.4.0`: for pre-1.0 crates, the *minor* number acts as the breaking-change boundary. So `tokio = "0.3"` would not auto-upgrade to `0.4`. * **Tilde pins the minor.** `~1.10.0` accepts patch releases (`1.10.x`) but not `1.11`. The table above proves it: it picked `1.10.6` even though `1.12.3` was available. * **Exact (`=`) is what npm’s bare version does.** Reach for it only when you truly must (a known-bad later release, byte-reproducibility outside the lockfile). * **Wildcard `*` is discouraged** and crates.io **rejects a bare `*`** when you publish (it cannot be resolved reproducibly downstream). > **Warning:** The lockfile, not the requirement, controls *exactly* which version a build uses. A caret `"1"` plus a committed `Cargo.lock` already gives you reproducible builds. You do **not** need to pin with `=` to get determinism. Pinning with `=` mostly *removes* flexibility for downstream users of a library. ### Features: opt-in capabilities [Section titled “Features: opt-in capabilities”](#features-opt-in-capabilities) A **feature** is a named, conditionally-compiled chunk of a crate. Enabling one can switch on extra modules, derive macros, trait implementations, or transitive dependencies. There is no real npm equivalent; the closest mental model is “this package ships several builds and you pick which parts compile in.” ```toml 1 [dependencies] 2 serde = { version = "1.0", features = ["derive"] } # turn on the derive macros 3 tokio = { version = "1", features = ["full"] } # "full" = the umbrella feature ``` `cargo add` shows you the feature menu. Adding `tokio` with the `full` feature prints (real output, trimmed): ```text 1 Adding tokio v1.52.3 to dependencies 2 Features: 3 + bytes 4 + fs 5 + full 6 + io-util 7 + macros 8 + net 9 + rt 10 + rt-multi-thread 11 + sync 12 + time 13 ... 14 - test-util 15 - tracing ``` The `+` lines are enabled, the `-` lines are available-but-off. Most crates ship a set of **default features** that are on unless you opt out with `default-features = false`: ```toml 1 [dependencies] 2 # Disable the defaults, then opt back into only what you need (smaller build): 3 uuid = { version = "1", default-features = false, features = ["v4"] } ``` > **Tip:** Features are **additive** by design: enabling a feature should only *add* capability, never remove or change existing behavior. Cargo unifies features across your whole dependency graph: if crate A enables `serde/std` and crate B does not, the unified build still has `std` on. Design and `#[cfg(feature = "...")]` are covered in [Feature Flags and Conditional Compilation](/12-modules-packages/09-feature-flags/). ### Path dependencies: a folder on disk [Section titled “Path dependencies: a folder on disk”](#path-dependencies-a-folder-on-disk) A **path dependency** points at a crate in your filesystem: ideal for local development, examples, or splitting a project into crates before publishing. It mirrors npm’s `file:../shared-utils`. ```toml 1 [dependencies] 2 geometry = { version = "0.1.0", path = "../geometry" } ``` Given a library crate at `../geometry` exposing `pub fn rectangle_area(...)`, the dependent crate uses it like any other (compile-verified — prints `area = 12`): ```rust 1 // src/main.rs in the dependent crate 2 use geometry::rectangle_area; 3 4 fn main() { 5 let area = rectangle_area(3.0, 4.0); 6 println!("area = {area}"); 7 } ``` The `version` is optional for purely local use but recommended: if you later publish, Cargo uses `version` for crates.io and `path` only for local builds. Multiple path-linked crates in one repository are usually better modeled as a **workspace**; see [Cargo Workspaces](/12-modules-packages/08-workspaces/). ### Git dependencies: straight from a repository [Section titled “Git dependencies: straight from a repository”](#git-dependencies-straight-from-a-repository) A **git dependency** fetches the crate from a repository, like npm’s `github:owner/repo`. Useful for unreleased fixes, private forks, or crates not on crates.io. ```toml 1 [dependencies] 2 # Track the default branch (re-resolves to its latest commit on `cargo update`): 3 anyhow = { git = "https://github.com/dtolnay/anyhow" } 4 5 # Pin to a branch, a tag, or an exact commit: 6 anyhow = { git = "https://github.com/dtolnay/anyhow", branch = "master" } 7 anyhow = { git = "https://github.com/dtolnay/anyhow", tag = "1.0.102" } 8 anyhow = { git = "https://github.com/dtolnay/anyhow", rev = "841522b" } ``` `cargo add anyhow --git https://github.com/dtolnay/anyhow` produces this real output and manifest entry: ```text 1 Updating git repository `https://github.com/dtolnay/anyhow` 2 Adding anyhow (git) to dependencies 3 Features: 4 + std 5 - backtrace 6 Updating git repository `https://github.com/dtolnay/anyhow` 7 Locking 1 package to latest Rust 1.96.0 compatible version ``` Whatever commit Cargo resolves is recorded in `Cargo.lock`, so a git dependency is still reproducible. The lockfile entry looks like: ```toml 1 [[package]] 2 name = "anyhow" 3 version = "1.0.102" 4 source = "git+https://github.com/dtolnay/anyhow#841522b2aa09732fecee40804440d2c35c68c480" ``` > **Note:** Without `branch`/`tag`/`rev`, a git dependency tracks the default branch’s HEAD *at the time it was first locked*. It does not silently float on every build; `cargo update` is what advances it, just as `npm update` advances a git dep. ### Renaming a dependency [Section titled “Renaming a dependency”](#renaming-a-dependency) If you want to refer to a crate under a different name in code (or depend on two majors of the same crate), use the `package` key. This is the manifest equivalent of npm aliases (`npm install json@npm:serde_json`): ```toml 1 [dependencies] 2 json = { package = "serde_json", version = "1.0" } ``` Now the crate is reachable as `json` in your code (compile-verified — prints `true`): ```rust 1 fn main() { 2 let v: json::Value = json::from_str(r#"{"ok":true}"#).unwrap(); 3 println!("{}", v["ok"]); 4 } ``` *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | npm / `package.json` | Cargo / `Cargo.toml` | | ----------------------- | ---------------------------------- | ----------------------------------------------------- | | Add a dependency | `npm install <pkg>` | `cargo add <crate>` (built in since 1.62) | | Bare version string | **Exact** (`"5.3.0"` = only 5.3.0) | **Caret** (`"1.0"` = `>=1.0.0, <2.0.0`) | | Explicit caret | `"^5.3.0"` | Default; can also write `"^1"` explicitly | | Tilde | `"~5.3.0"` (≈ patch-level) | `"~1.10.0"` (`>=1.10.0, <1.11.0`) | | Exact pin | bare version, or `"5.3.0"` | `"=1.0.100"` | | Optional capabilities | (no real equivalent) | **features** (`features = [...]`, `default-features`) | | Local folder | `"file:../x"` | `{ path = "../x" }` | | Git source | `"github:owner/repo"` | `{ git = "url", branch/tag/rev = ... }` | | Alias / rename | `npm:real-name` | `{ package = "real-name" }` | | Two majors side by side | dedup’d; awkward | Allowed natively (e.g. `rand` 0.8 *and* 0.9) | | Stored on disk | `node_modules/` per project | shared `~/.cargo/registry/`, compiled into `target/` | The deepest difference is the **caret default**. A TypeScript developer reads `regex = "1.10"` as “locked to 1.10” and is surprised when `cargo update` jumps to `1.12`. It is the opposite of npm’s bare-version behavior. The second is **features**: Cargo bakes “which optional parts to compile” into the dependency declaration, so a single crate can be lean in one project and full-featured in another without a different package. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Reading a bare version as a pin [Section titled “Pitfall 1: Reading a bare version as a pin”](#pitfall-1-reading-a-bare-version-as-a-pin) ```toml 1 [dependencies] 2 tokio = "1.45.0" # This is ^1.45.0, NOT a pin to exactly 1.45.0 ``` A `package.json`-trained eye reads this as “exactly 1.45.0”. It is `>=1.45.0, <2.0.0`. If you genuinely need exactly one version, write `tokio = "=1.45.0"`. But for reproducibility you almost never need to: commit `Cargo.lock` and the *resolved* version is fixed regardless of the caret range. ### Pitfall 2: Forgetting a feature, then hitting a “method not found” error [Section titled “Pitfall 2: Forgetting a feature, then hitting a “method not found” error”](#pitfall-2-forgetting-a-feature-then-hitting-a-method-not-found-error) The most common feature mistake: the function you want lives behind a non-default feature. For example, `Uuid::new_v4()` requires the `v4` feature. With `uuid` added but `v4` *off*: ```toml 1 [dependencies] 2 uuid = "1" # missing features = ["v4"] ``` ```rust 1 use uuid::Uuid; 2 3 fn main() { 4 let id = Uuid::new_v4(); // does not compile (error[E0599]) — needs the "v4" feature 5 println!("{id}"); 6 } ``` The real error from `cargo build`: ```text 1 error[E0599]: no function or associated item named `new_v4` found for struct `Uuid` in the current scope 2 --> src/main.rs:4:20 3 | 4 4 | let id = Uuid::new_v4(); // does not compile (error[E0599]) — needs the "v4" feature 5 | ^^^^^^ function or associated item not found in `Uuid` 6 | 7 note: if you're trying to build a new `Uuid` consider using one of the following associated functions: 8 uuid::builder::<impl Uuid>::nil 9 uuid::builder::<impl Uuid>::max 10 ... 11 For more information about this error, try `rustc --explain E0599`. ``` The message points at the type but not always at the missing feature, which makes this confusing. **Fix:** enable the feature. `uuid = { version = "1", features = ["v4"] }`, or `cargo add uuid --features v4`. When a function is “documented but missing,” suspect a feature flag and check the crate’s docs.rs feature list. (See also the analogous `serde` derive trap in [Feature Flags and Conditional Compilation](/12-modules-packages/09-feature-flags/).) ### Pitfall 3: Requiring a version that doesn’t exist [Section titled “Pitfall 3: Requiring a version that doesn’t exist”](#pitfall-3-requiring-a-version-that-doesnt-exist) ```toml 1 [dependencies] 2 serde_json = "=1.0.99999" # no such version ``` ```text 1 error: failed to select a version for the requirement `serde_json = "=1.0.99999"` 2 candidate versions found which didn't match: 1.0.150, 1.0.149, 1.0.148, ... 3 location searched: crates.io index 4 required by package `conflictprobe v0.1.0 (...)` ``` This happens when you pin too aggressively or typo a version. Cargo lists the candidates it *did* find. **Fix:** widen the requirement (drop the `=`) or pick a real version from the list. ### Pitfall 4: Expecting `*` to work, or to behave like a lazy “latest” [Section titled “Pitfall 4: Expecting \* to work, or to behave like a lazy “latest””](#pitfall-4-expecting--to-work-or-to-behave-like-a-lazy-latest) A bare `regex = "*"` resolves locally but crates.io **refuses to publish** a crate that depends on `"*"`, because it is not reproducible for downstream users. Even `"1.*"` is discouraged. Prefer a caret floor like `"1"`. Cargo’s caret already means “latest compatible,” so wildcards buy you nothing but trouble. ### Pitfall 5: Assuming git deps auto-update on every build [Section titled “Pitfall 5: Assuming git deps auto-update on every build”](#pitfall-5-assuming-git-deps-auto-update-on-every-build) Adding `{ git = "..." }` does not mean “always the newest commit.” Cargo locks the resolved commit into `Cargo.lock` and reuses it. To advance to a newer commit you must run `cargo update` (or change the `branch`/`tag`/`rev`). This surprises people expecting npm-style behavior, though npm git deps behave the same way once locked. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Let `cargo add` write the manifest.** `cargo add serde --features derive` finds the latest version, writes the correct inline table, and updates the lockfile. Hand-typing version strings invites typos and stale versions. * **Prefer short caret requirements.** `"1"` or `"1.0"` is idiomatic. Reach for `"=x.y.z"` only when you have a concrete reason (a regression in a later release, a strict reproducibility requirement outside the lockfile). * **Commit `Cargo.lock` for binaries/applications; omit it for libraries.** Reproducible app builds want a committed lockfile; libraries want to be tested against the newest compatible deps. This is the same convention as npm. * **Enable only the features you use; consider `default-features = false`** for leaner builds and faster compiles when you don’t need a crate’s defaults, then opt back into the specific features you need. * **Use path deps for local multi-crate work, and graduate to a workspace** once you have more than two crates in one repository. See [Cargo Workspaces](/12-modules-packages/08-workspaces/). * **Pin git deps with `tag` or `rev` for anything shipping.** A floating branch is fine for experiments but a tagged/`rev`-pinned commit is auditable and reproducible. * **Audit and update intentionally.** `cargo update` advances within your SemVer ranges; `cargo outdated` (a popular plugin) and `cargo audit` (security advisories) are the analogues of `npm outdated` / `npm audit`. See [Cargo Commands](/12-modules-packages/05-cargo-commands/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored configuration loader: it depends on `serde` (with the `derive` feature) and `toml` from crates.io, and parses a service config with sensible defaults. Both the manifest and the program were compiled and run as-is. Cargo.toml ```toml 1 [dependencies] 2 serde = { version = "1.0", features = ["derive"] } 3 toml = "1" ``` src/main.rs ```rust 1 use serde::Deserialize; 2 3 /// Application config, parsed from a TOML string (inlined here for the demo). 4 #[derive(Debug, Deserialize)] 5 struct Config { 6 name: String, 7 #[serde(default = "default_workers")] 8 workers: u32, 9 database: Database, 10 } 11 12 #[derive(Debug, Deserialize)] 13 struct Database { 14 url: String, 15 #[serde(default)] 16 pool_size: u32, 17 } 18 19 fn default_workers() -> u32 { 20 4 21 } 22 23 fn main() -> Result<(), toml::de::Error> { 24 let raw = r#" 25 name = "billing-service" 26 27 [database] 28 url = "postgres://localhost/billing" 29 pool_size = 16 30 "#; 31 32 let cfg: Config = toml::from_str(raw)?; 33 println!("service: {}", cfg.name); 34 println!("workers: {} (defaulted)", cfg.workers); 35 println!("db url: {}", cfg.database.url); 36 println!("pool: {}", cfg.database.pool_size); 37 Ok(()) 38 } ``` Real `cargo run` output: ```text 1 service: billing-service 2 workers: 4 (defaulted) 3 db url: postgres://localhost/billing 4 pool: 16 ``` This is the everyday shape of a Rust dependency story: a crate (`serde`) you enable a feature on, a sibling crate (`toml`) that integrates with it through that feature, and zero manual wiring. The `#[serde(default)]` attributes work *only because* the `derive` feature is on, the same opt-in mechanism we covered above. Inspect the resolved graph with `cargo tree` (the analogue of `npm ls`): ```text 1 $ cargo tree 2 billing-service v0.1.0 (/path/to/billing-service) 3 ├── serde v1.0.228 4 │ ├── serde_core v1.0.228 5 │ └── serde_derive v1.0.228 (proc-macro) 6 │ ├── proc-macro2 v1.0.106 7 │ │ └── unicode-ident v1.0.24 8 │ ├── quote v1.0.45 9 │ │ └── proc-macro2 v1.0.106 (*) 10 │ └── syn v2.0.117 11 │ ├── proc-macro2 v1.0.106 (*) 12 │ ├── quote v1.0.45 (*) 13 │ └── unicode-ident v1.0.24 14 └── toml v1.1.2+spec-1.1.0 15 ├── serde_core v1.0.228 16 ├── serde_spanned v1.1.1 17 │ └── serde_core v1.0.228 18 ├── toml_datetime v1.1.1+spec-1.1.0 19 │ └── serde_core v1.0.228 20 ├── toml_parser v1.1.2+spec-1.1.0 21 │ └── winnow v1.0.3 22 ├── toml_writer v1.1.1+spec-1.1.0 23 └── winnow v1.0.3 ``` *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Cargo Book — Specifying Dependencies](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html) — caret/tilde/exact/wildcard grammar, git and path sources. * [The Cargo Book — `cargo add`](https://doc.rust-lang.org/cargo/commands/cargo-add.html) * [The Cargo Book — Features](https://doc.rust-lang.org/cargo/reference/features.html) * [The SemVer specification](https://semver.org/) — what major/minor/patch actually promise. ### Cross-links in this guide [Section titled “Cross-links in this guide”](#cross-links-in-this-guide) * [Cargo.toml: the manifest, lockfile & profiles](/12-modules-packages/04-cargo/) — the file these dependencies live in. * [Cargo commands](/12-modules-packages/05-cargo-commands/) — `add`, `build`, `update`, and friends. * [Dev & build dependencies](/12-modules-packages/07-dev-dependencies/) — `[dev-dependencies]`, `[build-dependencies]`, and optional deps. * [Feature flags](/12-modules-packages/09-feature-flags/) — designing `[features]` and `#[cfg(feature = "...")]`. * [Workspaces](/12-modules-packages/08-workspaces/) — when path deps grow into a monorepo with a shared lockfile. * [Publishing to crates.io](/12-modules-packages/11-publishing/) — why `*` requirements are rejected, and how versioning works for publishers. * [Modules: ES modules → `mod`](/12-modules-packages/00-modules/) and [`use` & re-exports](/12-modules-packages/02-use-keyword/) — organizing code *within* a crate once a dependency is in scope. * Foundations: [Why Rust](/00-introduction/) · [Understanding Cargo (intro)](/01-getting-started/03-cargo-basics/) · [Basics](/02-basics/). * Next section: [Testing](/13-testing/) — where `[dev-dependencies]` like `proptest` and `mockall` come into play. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Translate npm installs into Cargo declarations [Section titled “Exercise 1: Translate npm installs into Cargo declarations”](#exercise-1-translate-npm-installs-into-cargo-declarations) **Difficulty:** Beginner **Objective:** Build the right `[dependencies]` table and understand caret-by-default. **Instructions:** A teammate ran these npm commands. Write the equivalent `[dependencies]` lines (or `cargo add` commands), keeping the version semantics correct. Note where the bare-version meaning differs between npm and Cargo. ```bash 1 npm install zod # latest 3.x acceptable 2 npm install chalk@5.3.0 # they want EXACTLY 5.3.0 3 npm install ../shared # a sibling folder on disk ``` Solution ```toml 1 [dependencies] 2 # "latest 3.x" — a bare caret string IS that in Cargo (unlike npm, where bare = exact): 3 serde = "1" # (zod has no Rust twin; serde stands in) 4 # "exactly 5.3.0" — npm's bare version == Cargo's `=` operator: 5 some_crate = "=5.3.0" 6 # a sibling folder on disk -> a path dependency: 7 shared = { path = "../shared" } ``` Equivalently with the CLI: ```bash 1 cargo add serde 2 cargo add some_crate@=5.3.0 3 cargo add shared --path ../shared ``` The teachable point: npm’s `chalk@5.3.0` (no caret) is an **exact** request, so it maps to Cargo’s `=5.3.0`, *not* a bare `"5.3.0"` (which would be a caret range `>=5.3.0, <6.0.0`). ### Exercise 2: Add a crate with a feature and use it [Section titled “Exercise 2: Add a crate with a feature and use it”](#exercise-2-add-a-crate-with-a-feature-and-use-it) **Difficulty:** Intermediate **Objective:** Practice enabling a feature and confirm the program runs. **Instructions:** Starting from a fresh `cargo new`, add the `rand` crate and make this program compile and print a random dice roll. Fill in the `/* ??? */`. ```rust 1 fn main() { 2 let roll: u32 = /* ??? */; // a random number in 1..=6 3 println!("you rolled a {roll}"); 4 } ``` Solution ```bash 1 cargo add rand ``` `Cargo.toml` ends up with `rand = "0.10.1"` (the current release at the time of writing — yours may be newer; a caret range, so `0.10.x` is fine). ```rust 1 fn main() { 2 // rand 0.10 exposes a `random_range` free function (no trait import needed): 3 let roll: u32 = rand::random_range(1..=6); 4 println!("you rolled a {roll}"); 5 } ``` Real output (nondeterministic — your number will differ): ```text 1 you rolled a 6 ``` > **Note:** This uses the current `rand` 0.10 API. The free `rand::random_range` used here needs no import. If you instead reach for the method form, `rand::rng()` returns an explicit generator whose `random_range` method needs `use rand::RngExt;` in scope — the familiar `use rand::Rng;` no longer provides it and produces `error[E0599]`. Older guides show rand 0.8’s `thread_rng()` / `gen_range()`; that API is gone, do not copy it. ### Exercise 3: Choose the right SemVer requirement [Section titled “Exercise 3: Choose the right SemVer requirement”](#exercise-3-choose-the-right-semver-requirement) **Difficulty:** Advanced **Objective:** Reason about caret vs tilde vs exact, and predict what Cargo resolves. **Instructions:** You depend on a crate `widget` that has published `1.4.0`, `1.4.7`, `1.5.2`, and `2.0.0`. For each requirement string, state (a) the version range it allows and (b) which of those four versions Cargo would pick. Then say which requirement you’d choose if you want bug-fix updates but want to avoid any new `1.x` features, and why. 1. `widget = "1.4"` 2. `widget = "~1.4.0"` 3. `widget = "=1.4.0"` 4. `widget = "1"` Solution | Requirement | Allowed range | Picks (of 1.4.0 / 1.4.7 / 1.5.2 / 2.0.0) | | ------------------ | ----------------- | ---------------------------------------- | | `"1.4"` (caret) | `>=1.4.0, <2.0.0` | **1.5.2** (highest <2.0.0) | | `"~1.4.0"` (tilde) | `>=1.4.0, <1.5.0` | **1.4.7** (highest 1.4.x) | | `"=1.4.0"` (exact) | exactly 1.4.0 | **1.4.0** | | `"1"` (caret) | `>=1.0.0, <2.0.0` | **1.5.2** (highest <2.0.0) | > **Note:** A bare `"1.4"` is a *caret*, so it allows the whole `1.x` line; it does **not** lock you to `1.4.*`. That is exactly the npm-vs-Cargo trap. **Best choice for “bug fixes only, no new minor features”:** `widget = "~1.4.0"`. The tilde operator accepts patch releases within `1.4.x` (so you get `1.4.7`’s fixes) but refuses `1.5.2`, which under SemVer may introduce new (additive) features you want to avoid for now. Caret (`"1.4"` / `"1"`) would happily jump to `1.5.2`; exact (`"=1.4.0"`) would freeze you on the buggy `1.4.0` and miss the patch fixes. This guide verified the tilde behavior live: `regex = "~1.10.0"` resolves to `1.10.6` even though `1.12.3` is available; the tilde holds the minor at `1.10`. # Dev-Dependencies, Build-Dependencies, and Optional Dependencies > Cargo splits runtime, dev, and build-time dependencies, plus optional feature-gated ones, enforcing each boundary at compile time, unlike npm's devDependencies. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In `package.json` you split packages into `dependencies` and `devDependencies` so test runners and bundlers don’t ship to production. Cargo makes the same split — and adds a third bucket for code that runs *at build time* — through three manifest tables: **`[dependencies]`**, **`[dev-dependencies]`**, and **`[build-dependencies]`**. On top of that, any normal dependency can be marked **`optional`** so it is only pulled in when a [feature flag](/12-modules-packages/09-feature-flags/) turns it on. This page is about *which bucket a crate belongs in* and *when each one is compiled*, a distinction Cargo enforces far more strictly than npm. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) A typical `package.json` separates runtime code from tooling. The `dependencies` ship; the `devDependencies` are for building and testing only: package.json ```json 1 { 2 "name": "id-gen", 3 "version": "0.1.0", 4 "type": "module", 5 "dependencies": { 6 "nanoid": "^5.0.0" 7 }, 8 "devDependencies": { 9 "vitest": "^2.0.0", 10 "fast-check": "^3.0.0", 11 "typescript": "^5.5.0" 12 }, 13 "optionalDependencies": { 14 "fsevents": "^2.3.0" 15 } 16 } ``` How Node and npm treat these: ```typescript 1 // src/index.ts — runtime code can import a `dependency` 2 import { nanoid } from "nanoid"; 3 4 export function makeId(prefix: string): string { 5 return `${prefix}-${nanoid(6)}`; 6 } ``` ```typescript 1 // test/id.test.ts — test code reaches for devDependencies 2 import { test, expect } from "vitest"; 3 import * as fc from "fast-check"; 4 import { makeId } from "../src/index.js"; 5 6 test("ids start with the prefix", () => { 7 fc.assert(fc.property(fc.string(), (p) => makeId(p).startsWith(p))); 8 }); ``` Three things to notice, because Rust will mirror two of them and tighten the third: * `npm install --production` (or `npm ci --omit=dev`) skips `devDependencies`, but **nothing stops** your `src/index.ts` from importing `vitest`. The boundary is a *convention* enforced only by what you choose to import. * `optionalDependencies` may fail to install without failing the whole install (e.g. `fsevents` is macOS-only). * There is no separate bucket for “code that runs during the build”: bundler plugins just live in `devDependencies`. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same project as a Rust crate. Each kind of dependency lives in its own table, and Cargo *enforces* the boundaries: Cargo.toml ```toml 1 [package] 2 name = "idgen" 3 version = "0.1.0" 4 edition = "2024" 5 6 # Ships to production. Available to src/ and everything else. 7 [dependencies] 8 serde_json = { version = "1", optional = true } # only compiled when a feature turns it on 9 10 # Compiled ONLY for `cargo test`/`cargo bench`/`cargo run --example`. 11 # Never compiled into your library or binary, never seen by downstream crates. 12 [dev-dependencies] 13 proptest = "1.11.0" 14 criterion = "0.8.2" 15 16 # Compiled and run on the BUILD machine, for build.rs only. Not linked into your program. 17 [build-dependencies] 18 chrono = "0.4" 19 20 [features] 21 # Turn the optional dependency on with `--features json`. 22 json = ["dep:serde_json"] ``` The library and its property test, where the dev-dependency is only reachable from the `tests/` directory: ```rust 1 // src/lib.rs — only `[dependencies]` are in scope here 2 /// Generate a zero-padded id, e.g. `"user-000042"`. 3 pub fn make_id(prefix: &str, n: u64) -> String { 4 format!("{prefix}-{n:06}") 5 } ``` ```rust 1 // tests/properties.rs — an integration test; `[dev-dependencies]` ARE in scope here 2 use idgen::make_id; 3 use proptest::prelude::*; 4 5 proptest! { 6 #[test] 7 fn id_always_starts_with_prefix(prefix in "[a-z]{1,8}", n in 0u64..1_000_000) { 8 let id = make_id(&prefix, n); 9 prop_assert!(id.starts_with(&prefix)); 10 prop_assert!(id.contains('-')); 11 } 12 } ``` Running the suite compiles `proptest` *only now*, not during a normal build: ```text 1 Running tests/properties.rs (target/debug/deps/properties-8252496bc40fbcfe) 2 3 running 1 test 4 test id_always_starts_with_prefix ... ok 5 6 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.02s ``` > **Note:** Add dependencies to the right table without hand-editing TOML: `cargo add proptest --dev`, `cargo add cc --build`, and `cargo add serde_json --optional`. The `--dev`, `--build`, and `--optional` flags have been built into `cargo add` since Cargo 1.62. No `cargo-edit` install needed. See [Cargo Commands](/12-modules-packages/05-cargo-commands/) and [Specifying Dependencies](/12-modules-packages/06-dependencies/). *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `[dev-dependencies]`: the direct analog of `devDependencies` [Section titled “\[dev-dependencies\]: the direct analog of devDependencies”](#dev-dependencies-the-direct-analog-of-devdependencies) A **dev-dependency** is compiled only when Cargo builds your tests, benchmarks, examples, or doc-tests. It is *not* compiled when someone runs `cargo build`, `cargo build --release`, or depends on your crate from their own project. The important difference from npm is **scope enforcement** rather than installation alone. In Node, `import "vitest"` from `src/` works fine on your machine (it only breaks in production where dev-deps weren’t installed). In Rust, a dev-dependency simply does not exist as far as `src/` is concerned — referencing it from library or binary code is a *compile error*, caught immediately on your own machine. We hit that error on purpose in [Common Pitfalls](#common-pitfalls). Where dev-dependencies *are* in scope: | Location | Purpose | Dev-deps in scope? | | -------------------------------------- | ---------------------- | ---------------------------- | | `src/lib.rs`, `src/main.rs` | Your shipped code | No | | `tests/*.rs` | Integration tests | Yes | | `benches/*.rs` | Benchmarks | Yes | | `examples/*.rs` | Runnable examples | Yes | | `#[cfg(test)] mod tests` inside `src/` | Unit tests | Yes (only under `cfg(test)`) | | Doc-tests in `///` comments | Documentation examples | Yes | > **Tip:** A unit test module guarded by `#[cfg(test)]` inside `src/lib.rs` *can* use dev-dependencies, because that module is compiled only in the test build. But the surrounding non-test code in the same file still cannot. The `#[cfg(test)]` attribute is the switch. See [Testing](/13-testing/) for the full testing story. The payoff is visible in what ships. A normal release build compiles only your crate, no `criterion`, no `proptest`: ```text 1 $ cargo build --release 2 Compiling idgen v0.1.0 (/private/tmp/idgen_probe/idgen) 3 Finished `release` profile [optimized] target(s) in 0.22s ``` And a downstream consumer’s dependency graph (`cargo tree -e no-dev`, the edges they actually pull) contains none of your dev-dependencies: ```text 1 $ cargo tree -e no-dev 2 idgen v0.1.0 (/private/tmp/idgen_probe/idgen) ``` ### Benchmarks: the most common reason to reach for a dev-dependency [Section titled “Benchmarks: the most common reason to reach for a dev-dependency”](#benchmarks-the-most-common-reason-to-reach-for-a-dev-dependency) `criterion` is the de-facto statistical benchmarking crate, and it is *always* a dev-dependency. A benchmark lives in `benches/` and is declared in the manifest with `harness = false` so Cargo hands control to Criterion’s runner instead of the built-in test harness: Cargo.toml ```toml 1 [[bench]] 2 name = "id_bench" 3 harness = false ``` benches/id\_bench.rs ```rust 1 use criterion::{criterion_group, criterion_main, Criterion}; 2 use idgen::{checksum, make_id}; 3 use std::hint::black_box; 4 5 fn bench_make_id(c: &mut Criterion) { 6 c.bench_function("make_id", |b| { 7 b.iter(|| make_id(black_box("user"), black_box(42))) 8 }); 9 } 10 11 criterion_group!(benches, bench_make_id); 12 criterion_main!(benches); ``` `cargo bench` compiles Criterion (a dev-dependency) and runs the measurement: ```text 1 make_id time: [73.714 ns 76.545 ns 81.134 ns] 2 Found 11 outliers among 100 measurements (11.00%) 3 5 (5.00%) high mild 4 6 (6.00%) high severe ``` > **Note:** `std::hint::black_box` (stabilized in Rust 1.66) stops the optimizer from deleting code whose result you ignore, the Rust equivalent of the tricks JS micro-benchmark libraries use to defeat dead-code elimination. ### `[build-dependencies]`: a bucket npm doesn’t have [Section titled “\[build-dependencies\]: a bucket npm doesn’t have”](#build-dependencies-a-bucket-npm-doesnt-have) There is no `package.json` equivalent of `[build-dependencies]`. These are crates used by **`build.rs`**, a build script that compiles and runs *on the build machine before your crate compiles*. Build-dependencies are linked into the build script, never into your program, and — like dev-dependencies — are invisible to `src/`. A common, dependency-light use is **code generation**: the build script writes a `.rs` file into the `OUT_DIR` Cargo provides, and `src/` pulls it in with `include!`. ```rust 1 // build.rs — runs at build time; `[build-dependencies]` are in scope here 2 use std::{env, fs, path::Path}; 3 4 fn main() { 5 // `chrono` is a BUILD-dependency: usable here, NOT in src/. 6 let now = chrono::Utc::now().format("%Y-%m-%d").to_string(); 7 let out_dir = env::var("OUT_DIR").unwrap(); 8 let dest = Path::new(&out_dir).join("build_info.rs"); 9 fs::write(&dest, format!("pub const BUILD_DATE: &str = \"{now}\";\n")).unwrap(); 10 11 // Re-run this script only when build.rs itself changes (not on every build). 12 println!("cargo:rerun-if-changed=build.rs"); 13 } ``` ```rust 1 // src/main.rs — splices in the file build.rs generated 2 include!(concat!(env!("OUT_DIR"), "/build_info.rs")); 3 4 fn main() { 5 println!("greeter built on {BUILD_DATE}"); 6 } ``` ```text 1 $ cargo run 2 Compiling greeter v0.1.0 (/private/tmp/build_probe/greeter) 3 Finished `dev` profile [unoptimized + debuginfo] target(s) in 3.25s 4 Running `target/debug/greeter` 5 greeter built on 2026-05-31 ``` This page stays in the manifest lane: *what* `[build-dependencies]` is and *when* it compiles. For the build-script API itself — `cargo::rerun-if-changed`, linking native C libraries, more code-generation patterns — see [Build Scripts](/12-modules-packages/10-build-scripts/). ### Optional dependencies: `dependencies` that only appear behind a feature [Section titled “Optional dependencies: dependencies that only appear behind a feature”](#optional-dependencies-dependencies-that-only-appear-behind-a-feature) Marking a dependency `optional = true` means it is **not compiled by default**; a [feature](/12-modules-packages/09-feature-flags/) must request it. This is how crates offer “pay for what you use” integrations (a `serde` impl, a `tokio` runtime, JSON support) without forcing every user to compile them. Cargo.toml ```toml 1 [dependencies] 2 serde_json = { version = "1", optional = true } 3 4 [features] 5 # `dep:serde_json` activates the optional dependency without leaking its name as a feature. 6 json = ["dep:serde_json"] ``` src/main.rs ```rust 1 fn plain_report(name: &str, count: u64) -> String { 2 format!("{name}: {count}") 3 } 4 5 // Compiled only when the `json` feature (and thus serde_json) is enabled. 6 #[cfg(feature = "json")] 7 fn json_report(name: &str, count: u64) -> String { 8 serde_json::json!({ "name": name, "count": count }).to_string() 9 } 10 11 fn main() { 12 println!("{}", plain_report("requests", 7)); 13 14 #[cfg(feature = "json")] 15 println!("{}", json_report("requests", 7)); 16 17 #[cfg(not(feature = "json"))] 18 println!("(build with --features json for JSON output)"); 19 } ``` The default build never touches `serde_json`; opting in pulls it in and compiles the gated code: ```text 1 $ cargo run 2 requests: 7 3 (build with --features json for JSON output) 4 5 $ cargo run --features json 6 requests: 7 7 {"count":7,"name":"requests"} ``` This is a genuinely sharper tool than npm’s `optionalDependencies`, which is about *install failures being non-fatal* (platform-specific native modules). Rust’s `optional` is about *compile-time presence controlled by features*, a different mechanism for a different goal. There is no `optionalDependencies`-style “try to install, shrug if it fails” in Cargo, because Cargo resolves a complete, reproducible graph up front (see `Cargo.lock` in [Cargo.toml](/12-modules-packages/04-cargo/)). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / npm | Rust / Cargo | | ------------------------- | -------------------------------------------------- | ---------------------------------------------------------- | | Runtime deps | `dependencies` | `[dependencies]` | | Test/tooling deps | `devDependencies` | `[dev-dependencies]` | | Build-time-only deps | (none — live in `devDependencies`) | `[build-dependencies]` (for `build.rs`) | | Conditional/optional deps | `optionalDependencies` (install may fail silently) | `optional = true` + a feature (compile-time gate) | | Boundary enforcement | Convention; `src/` *can* import a devDependency | Compiler error if `src/` uses a dev/build dependency | | Omitting dev deps | `npm ci --omit=dev` | Automatic: `cargo build` never compiles them | | What downstream users get | Your `dependencies` (transitively) | Your `[dependencies]` only; dev/build deps never propagate | Three mental-model shifts for a TypeScript developer: 1. **The buckets are enforced by the compiler, not by which files you happen to import.** You cannot “accidentally ship a test dependency” by importing it from production code. It won’t compile. 2. **`[build-dependencies]` is a third, distinct kind.** Build-time tooling that *runs* (code generators, native-lib probing) is separated from test tooling. In npm both would be `devDependencies`. 3. **Optional means “feature-gated at compile time,” not “best-effort install.”** It is the dependency arm of the feature system, covered in [Feature Flags and Conditional Compilation](/12-modules-packages/09-feature-flags/). > **Note:** The same crate can appear in more than one table: e.g. `serde` as a normal dependency *and* `serde_json` as a dev-dependency. Cargo de-duplicates by version in the lockfile, so listing a crate in both `[dependencies]` and `[dev-dependencies]` is fine and sometimes necessary (a normal-dep feature you only need in tests). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Using a dev-dependency from `src/` [Section titled “Pitfall 1: Using a dev-dependency from src/”](#pitfall-1-using-a-dev-dependency-from-src) The single most common mistake. You add `proptest` as a dev-dependency, then reach for it in `src/lib.rs`: src/lib.rs ```rust 1 use proptest::prelude::*; // does not compile (error[E0433]): proptest is a dev-dependency 2 3 pub fn make_id(prefix: &str, n: u64) -> String { 4 format!("{prefix}-{n:06}") 5 } ``` The real compiler output: ```text 1 error[E0433]: failed to resolve: use of unresolved module or unlinked crate `proptest` 2 --> src/lib.rs:1:5 3 | 4 1 | use proptest::prelude::*; // does not compile (error[E0433]): proptest is a dev-dependency 5 | ^^^^^^^^ use of unresolved module or unlinked crate `proptest` 6 | 7 = help: if you wanted to use a crate named `proptest`, use `cargo add proptest` to add it to your `Cargo.toml` 8 9 error: could not compile `idgen` (lib) due to 1 previous error ``` **Fix:** if the crate is genuinely needed by shipping code, move it to `[dependencies]` (`cargo add proptest`). If it is only for tests, keep the usage in `tests/`, `benches/`, or a `#[cfg(test)]` module. ### Pitfall 2: Using a build-dependency from `src/` [Section titled “Pitfall 2: Using a build-dependency from src/”](#pitfall-2-using-a-build-dependency-from-src) `build.rs` and `src/` have *separate* dependency graphs. A crate in `[build-dependencies]` is not available to your program: src/main.rs ```rust 1 fn main() { 2 let now = chrono::Utc::now(); // does not compile (error[E0433]): chrono is a build-dependency 3 println!("now is {now}"); 4 } ``` ```text 1 error[E0433]: failed to resolve: use of unresolved module or unlinked crate `chrono` 2 --> src/main.rs:4:15 3 | 4 4 | let now = chrono::Utc::now(); // does not compile (error[E0433]): chrono is a build-dependency 5 | ^^^^^^ use of unresolved module or unlinked crate `chrono` 6 | 7 = help: if you wanted to use a crate named `chrono`, use `cargo add chrono` to add it to your `Cargo.toml` ``` **Fix:** if `build.rs` needs it, keep it in `[build-dependencies]`; if your program needs it at runtime, add it to `[dependencies]` as well (the build script’s copy and the runtime copy are independent). ### Pitfall 3: An optional dependency silently becomes a feature name [Section titled “Pitfall 3: An optional dependency silently becomes a feature name”](#pitfall-3-an-optional-dependency-silently-becomes-a-feature-name) If you mark a dependency `optional = true` but never reference it via `dep:` in any feature, Cargo creates an **implicit feature with the same name as the dependency**. That sometimes surprises people: ```toml 1 # Cargo.toml — no [features] table at all 2 [dependencies] 3 serde_json = { version = "1", optional = true } ``` ```text 1 $ cargo run # default: implicit feature off 2 json feature off 3 4 $ cargo run --features serde_json # an implicit feature named after the optional dep 5 json feature on: {"ok":true} ``` This compiles and works, but it leaks the dependency’s name into your public feature surface, a breaking change if you later rename or drop the dep. **Best practice:** give the dependency a deliberate feature using the `dep:` prefix (`json = ["dep:serde_json"]`), which *suppresses* the implicit feature so only your chosen name is public. The `dep:` syntax has been available since Cargo 1.60. ### Pitfall 4: Expecting `cargo tree` to hide dev-dependencies [Section titled “Pitfall 4: Expecting cargo tree to hide dev-dependencies”](#pitfall-4-expecting-cargo-tree-to-hide-dev-dependencies) Unlike a release *build*, the default `cargo tree` view *does* list your own crate’s dev-dependencies (under a `[dev-dependencies]` heading) because it shows the whole local graph: ```text 1 $ cargo tree 2 idgen v0.1.0 (/private/tmp/idgen_probe/idgen) 3 [dev-dependencies] 4 ├── criterion v0.8.2 5 │ ├── alloca v0.4.0 6 ... ``` That is expected — it does **not** mean those crates ship. To see exactly what propagates to consumers (the deps that actually build into your artifact), use `cargo tree -e no-dev`. Don’t conflate “appears in `cargo tree`” with “compiled into the binary.” *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Put benchmarking and property/test crates in `[dev-dependencies]`.** `criterion`, `proptest`, `mockall`, `assert_cmd`, `tempfile`-for-tests — all dev-dependencies. They never bloat your release artifact. * **Reserve `[build-dependencies]` for crates `build.rs` actually calls.** If you don’t have a `build.rs`, you don’t need this table. Keep build scripts (and their dependency trees) small. They sit on every clean build’s critical path. * **Make optional dependencies explicit features with `dep:`.** Write `json = ["dep:serde_json"]` rather than relying on the implicit feature, so your public feature names are intentional. See [Feature Flags and Conditional Compilation](/12-modules-packages/09-feature-flags/) for additive feature design. * **Use `cargo add` with the right flag** (`--dev`, `--build`, `--optional`) instead of editing TOML by hand. It places the entry in the correct table and resolves the latest compatible version. * **Declare benchmarks with `harness = false`** when using Criterion, and keep each bench file focused. Run them with `cargo bench`, never as part of `cargo test`. * **Don’t fear duplicating a crate across tables.** Listing `serde` in `[dependencies]` and again (perhaps with extra features) in `[dev-dependencies]` is idiomatic when tests need capabilities production doesn’t. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small library crate that exposes an optional JSON-export feature, is property-tested, and is benchmarked — using all three dependency tables at once. Cargo.toml ```toml 1 [package] 2 name = "idgen" 3 version = "0.1.0" 4 edition = "2024" 5 6 [dependencies] 7 serde_json = { version = "1", optional = true } 8 9 [dev-dependencies] 10 proptest = "1.11.0" 11 criterion = "0.8.2" 12 13 [features] 14 json = ["dep:serde_json"] 15 16 [[bench]] 17 name = "id_bench" 18 harness = false ``` ```rust 1 // src/lib.rs — production code: only [dependencies] (and feature-gated optional ones) 2 /// Generate a zero-padded id, e.g. `"user-000042"`. 3 pub fn make_id(prefix: &str, n: u64) -> String { 4 format!("{prefix}-{n:06}") 5 } 6 7 /// Sum the numeric suffixes of a slice of ids. 8 pub fn checksum(ids: &[String]) -> u64 { 9 ids.iter() 10 .filter_map(|s| s.rsplit('-').next()) 11 .filter_map(|num| num.parse::<u64>().ok()) 12 .sum() 13 } 14 15 /// JSON export — compiled only with `--features json`. 16 #[cfg(feature = "json")] 17 pub fn ids_to_json(ids: &[String]) -> String { 18 serde_json::to_string(ids).expect("ids serialize") 19 } ``` ```rust 1 // benches/id_bench.rs — uses the criterion dev-dependency 2 use criterion::{criterion_group, criterion_main, Criterion}; 3 use idgen::{checksum, make_id}; 4 use std::hint::black_box; 5 6 fn bench_checksum(c: &mut Criterion) { 7 let ids: Vec<String> = (0..1000).map(|n| make_id("u", n)).collect(); 8 c.bench_function("checksum_1000", |b| b.iter(|| checksum(black_box(&ids)))); 9 } 10 11 criterion_group!(benches, bench_checksum); 12 criterion_main!(benches); ``` ```rust 1 // tests/properties.rs — uses the proptest dev-dependency 2 use idgen::make_id; 3 use proptest::prelude::*; 4 5 proptest! { 6 #[test] 7 fn checksum_components_are_numeric(prefix in "[a-z]{1,8}", n in 0u64..1_000_000) { 8 let id = make_id(&prefix, n); 9 let suffix = id.rsplit('-').next().unwrap(); 10 prop_assert!(suffix.parse::<u64>().is_ok()); 11 } 12 } ``` Each command compiles only the relevant tables: ```text 1 $ cargo build # [dependencies] only; serde_json off, no criterion/proptest 2 $ cargo test # + [dev-dependencies]; runs the proptest integration test 3 $ cargo bench # + criterion; runs benchmarks 4 $ cargo build --features json # pulls in the optional serde_json ``` Verified benchmark output for `checksum_1000`: ```text 1 checksum_1000 time: [15.281 µs 17.581 µs 20.611 µs] 2 Found 18 outliers among 100 measurements (18.00%) 3 6 (6.00%) high mild 4 12 (12.00%) high severe ``` The release artifact a consumer receives contains only `idgen` (plus `serde_json` *if* they enable `json`), never `proptest` or `criterion`. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [The Cargo Book: Specifying Dependencies](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html) — dev/build/optional dependency syntax. * [The Cargo Book: Build Scripts](https://doc.rust-lang.org/cargo/reference/build-scripts.html) — `build.rs` and `[build-dependencies]`. * [The Cargo Book: Features](https://doc.rust-lang.org/cargo/reference/features.html) — optional dependencies and the `dep:` syntax. * [The Criterion.rs User Guide](https://bheisler.github.io/criterion.rs/book/) — statistical benchmarking. * Sibling pages: [Cargo.toml](/12-modules-packages/04-cargo/) (the manifest and `Cargo.lock`) · [Specifying Dependencies](/12-modules-packages/06-dependencies/) (version requirements, `cargo add`, git/path deps) · [Feature Flags and Conditional Compilation](/12-modules-packages/09-feature-flags/) (conditional compilation) · [Build Scripts](/12-modules-packages/10-build-scripts/) (the `build.rs` API) · [Cargo Commands](/12-modules-packages/05-cargo-commands/) · [Cargo Workspaces](/12-modules-packages/08-workspaces/) (sharing dev-deps across a monorepo). * Foundations: [Introduction](/00-introduction/) · [Understanding Cargo](/01-getting-started/03-cargo-basics/) · [Basics](/02-basics/) · testing details in [Testing](/13-testing/). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Sort a crate into the right table [Section titled “Exercise 1: Sort a crate into the right table”](#exercise-1-sort-a-crate-into-the-right-table) **Difficulty:** Beginner **Objective:** Build the correct mental model for which dependency goes where. **Instructions:** You are writing a library crate that (a) parses JSON config at runtime, (b) generates a Rust constants file from a `.txt` data file during the build, and (c) is fuzz-tested. For each of `serde_json`, a hypothetical `txt-to-rs` code generator used by `build.rs`, and `proptest`, write the `cargo add` command that places it in the correct table. Then state which table each lands in. Solution ```bash 1 cargo add serde_json # runtime parsing -> [dependencies] 2 cargo add txt-to-rs --build # used by build.rs -> [build-dependencies] 3 cargo add proptest --dev # testing only -> [dev-dependencies] ``` Resulting manifest tables: ```toml 1 [dependencies] 2 serde_json = "1" 3 4 [build-dependencies] 5 txt-to-rs = "..." # only build.rs may use this 6 7 [dev-dependencies] 8 proptest = "1.11.0" # only tests/benches/examples may use this ``` `serde_json` ships and is reachable from `src/`. `txt-to-rs` runs on the build machine and is reachable only from `build.rs`. `proptest` is compiled only for `cargo test`/`cargo bench` and is reachable only from test code. ### Exercise 2: Add a property test that uses a dev-dependency [Section titled “Exercise 2: Add a property test that uses a dev-dependency”](#exercise-2-add-a-property-test-that-uses-a-dev-dependency) **Difficulty:** Intermediate **Objective:** Wire up a dev-dependency and prove it is *not* visible to `src/`. **Instructions:** Start from a library with `pub fn double(n: u32) -> u32 { n * 2 }` in `src/lib.rs`. Add `proptest` as a dev-dependency and write an integration test in `tests/` asserting that `double(n)` is always even for `n` in `0..1000`. Then try adding `use proptest::prelude::*;` to the top of `src/lib.rs` and run `cargo build`. Explain the error. Solution ```bash 1 cargo add proptest --dev ``` src/lib.rs ```rust 1 pub fn double(n: u32) -> u32 { 2 n * 2 3 } ``` tests/even.rs ```rust 1 use mylib::double; // replace `mylib` with your crate name 2 use proptest::prelude::*; 3 4 proptest! { 5 #[test] 6 fn double_is_even(n in 0u32..1000) { 7 prop_assert_eq!(double(n) % 2, 0); 8 } 9 } ``` `cargo test` compiles `proptest` and passes. But adding `use proptest::prelude::*;` to `src/lib.rs` fails to build with: ```text 1 error[E0433]: failed to resolve: use of unresolved module or unlinked crate `proptest` ``` because `src/` only sees `[dependencies]`, never `[dev-dependencies]`. The boundary is enforced by the compiler, not by convention. That is the central difference from npm’s `devDependencies`. ### Exercise 3: Gate an optional dependency behind a feature [Section titled “Exercise 3: Gate an optional dependency behind a feature”](#exercise-3-gate-an-optional-dependency-behind-a-feature) **Difficulty:** Advanced **Objective:** Turn a normal dependency into an opt-in one and verify both build paths, avoiding the implicit-feature pitfall. **Instructions:** Take a binary crate that prints a report. Make `serde_json` an optional dependency, expose a `json` feature using the `dep:` syntax, and add a `json_report` function compiled only under that feature. Verify `cargo run` (no JSON) and `cargo run --features json` (JSON) both work. Explain why `json = ["dep:serde_json"]` is preferable to leaving the feature implicit. Solution Cargo.toml ```toml 1 [dependencies] 2 serde_json = { version = "1", optional = true } 3 4 [features] 5 json = ["dep:serde_json"] ``` src/main.rs ```rust 1 fn plain_report(name: &str, count: u64) -> String { 2 format!("{name}: {count}") 3 } 4 5 #[cfg(feature = "json")] 6 fn json_report(name: &str, count: u64) -> String { 7 serde_json::json!({ "name": name, "count": count }).to_string() 8 } 9 10 fn main() { 11 println!("{}", plain_report("requests", 7)); 12 13 #[cfg(feature = "json")] 14 println!("{}", json_report("requests", 7)); 15 16 #[cfg(not(feature = "json"))] 17 println!("(build with --features json for JSON output)"); 18 } ``` Verified output: ```text 1 $ cargo run 2 requests: 7 3 (build with --features json for JSON output) 4 5 $ cargo run --features json 6 requests: 7 7 {"count":7,"name":"requests"} ``` Using `dep:serde_json` is preferable because it *suppresses* the implicit feature that Cargo would otherwise create from the optional dependency’s name. Without it, both `--features json` *and* `--features serde_json` would work, leaking the dependency’s name into your public feature surface — a future breaking change if you rename or drop the dependency. The `dep:` prefix keeps `json` as the only public knob. # Cargo Workspaces: Monorepos in Rust > A Cargo workspace is Rust's built-in monorepo: many crates share one Cargo.lock and target/, depend by path, and inherit versions, no Turborepo or Nx required. A **Cargo workspace** lets several related crates live in one repository, share a single `Cargo.lock` and `target/` directory, and be built/tested together. It is Rust’s answer to the npm workspaces / Lerna / Nx / Turborepo monorepo you have probably wrestled with in the JavaScript world, but it is built into the toolchain, with no extra dependency. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) When a project outgrows a single crate (say a shared core library, a command-line interface, and a web server that all reuse the same domain types), you reach for a **workspace**. You declare it with a `[workspace]` table in a top-level `Cargo.toml` that lists its **members**. Every member is a normal crate with its own `Cargo.toml`, but they share one resolved dependency graph (`Cargo.lock`), one build cache (`target/`), and can depend on each other by **path**. For a TypeScript/JavaScript developer this is exactly the monorepo pattern (`"workspaces": ["packages/*"]` in a root `package.json`), and the payoff is the same: atomic cross-package changes, one install/build, and no version-skew between internal packages. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) A typical npm-workspaces monorepo for a task tracker has a private root `package.json` that lists the packages, plus one `package.json` per package. Local packages depend on each other by name: ```json 1 // package.json (the repo root — private, not published) 2 { 3 "name": "taskhub", 4 "private": true, 5 "workspaces": ["packages/*"] 6 } ``` ```json 1 // packages/core/package.json — the shared library 2 { 3 "name": "@taskhub/core", 4 "version": "0.3.0", 5 "main": "index.js" 6 } ``` ```json 1 // packages/cli/package.json — depends on the local @taskhub/core 2 { 3 "name": "@taskhub/cli", 4 "version": "0.3.0", 5 "dependencies": { "@taskhub/core": "0.3.0" } 6 } ``` A single `npm install` at the root resolves everything into **one** root `package-lock.json` and symlinks the local packages into the root `node_modules/`: ```text 1 $ npm install 2 $ find . -name package-lock.json 3 ./package-lock.json # one lockfile at the root 4 $ ls -la node_modules/@taskhub 5 core -> ../../packages/core # local packages symlinked, not copied 6 cli -> ../../packages/cli ``` That single shared lockfile and the symlinked local packages are the two defining traits of a JavaScript monorepo. Cargo workspaces give you both, by design, not by convention. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same project as a Cargo workspace. The repo root holds a `Cargo.toml` with **no `[package]`**, only a `[workspace]` table (this is called a **virtual manifest**). Each member crate lives in its own directory with its own manifest. The layout: ```text 1 taskhub/ 2 ├── Cargo.toml # the workspace root (virtual manifest — no [package]) 3 ├── Cargo.lock # ONE shared lockfile for the whole workspace 4 ├── target/ # ONE shared build cache for the whole workspace 5 └── crates/ 6 ├── core/ # taskhub-core: the shared library crate 7 │ ├── Cargo.toml 8 │ └── src/lib.rs 9 └── cli/ # taskhub-cli: a binary that depends on core 10 ├── Cargo.toml 11 └── src/main.rs ``` The root manifest: ```toml 1 # taskhub/Cargo.toml — the workspace root 2 [workspace] 3 resolver = "3" 4 members = ["crates/core", "crates/cli"] 5 6 # Fields every member can inherit, declared once. 7 [workspace.package] 8 version = "0.3.0" 9 edition = "2024" 10 license = "MIT OR Apache-2.0" 11 authors = ["Ada Zeybek <me@zeybek.dev>"] 12 13 # Dependency versions declared once, used by every member. 14 [workspace.dependencies] 15 serde = { version = "1.0", features = ["derive"] } 16 serde_json = "1.0" 17 anyhow = "1" 18 taskhub-core = { path = "crates/core" } ``` The shared library member: crates/core/Cargo.toml ```toml 1 [package] 2 name = "taskhub-core" 3 version.workspace = true # inherit from [workspace.package] 4 edition.workspace = true 5 license.workspace = true 6 authors.workspace = true 7 8 [dependencies] 9 serde = { workspace = true } # inherit the version + features from the root ``` crates/core/src/lib.rs ```rust 1 use serde::{Deserialize, Serialize}; 2 3 /// A single task tracked by the hub. 4 #[derive(Debug, Clone, Serialize, Deserialize)] 5 pub struct Task { 6 pub id: u32, 7 pub title: String, 8 pub done: bool, 9 } 10 11 impl Task { 12 pub fn new(id: u32, title: impl Into<String>) -> Self { 13 Task { id, title: title.into(), done: false } 14 } 15 } 16 17 /// Count how many tasks are still open. 18 pub fn open_count(tasks: &[Task]) -> usize { 19 tasks.iter().filter(|t| !t.done).count() 20 } ``` The binary member that depends on the library: crates/cli/Cargo.toml ```toml 1 [package] 2 name = "taskhub-cli" 3 version.workspace = true 4 edition.workspace = true 5 license.workspace = true 6 authors.workspace = true 7 8 [dependencies] 9 taskhub-core = { workspace = true } # the local path dep, declared at the root 10 serde_json = { workspace = true } 11 anyhow = { workspace = true } ``` crates/cli/src/main.rs ```rust 1 use anyhow::{Context, Result}; 2 use taskhub_core::{open_count, Task}; 3 4 fn main() -> Result<()> { 5 let mut tasks = vec![ 6 Task::new(1, "Write workspaces guide"), 7 Task::new(2, "Verify every snippet"), 8 ]; 9 tasks[1].done = true; 10 11 let json = serde_json::to_string_pretty(&tasks) 12 .context("failed to serialize tasks")?; 13 println!("{json}"); 14 println!("{} task(s) still open", open_count(&tasks)); 15 Ok(()) 16 } ``` Running the CLI member from the workspace root produces real output: ```text 1 $ cargo run -p taskhub-cli --quiet 2 [ 3 { 4 "id": 1, 5 "title": "Write workspaces guide", 6 "done": false 7 }, 8 { 9 "id": 2, 10 "title": "Verify every snippet", 11 "done": true 12 } 13 ] 14 1 task(s) still open ``` > **Note:** The package is named `taskhub-core` (with a hyphen) but the crate you `use` in code is `taskhub_core` (with an underscore). Cargo maps hyphens in package names to underscores in the language. This mirrors how `serde_json` the crate corresponds to the `serde_json` import name. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The `[workspace]` table and members [Section titled “The \[workspace\] table and members”](#the-workspace-table-and-members) ```toml 1 [workspace] 2 resolver = "3" 3 members = ["crates/core", "crates/cli"] ``` * **`members`** is a list of directory paths (relative to the root). Each must contain a crate with its own `Cargo.toml`. Glob patterns work too: `members = ["crates/*"]` picks up every crate under `crates/`. * **`resolver = "3"`** opts into the version-3 feature resolver, which is the default for edition-2024 crates. In a workspace you set it once at the root because the resolver is workspace-wide; you cannot let individual members disagree. (Resolver 2 fixed long-standing issues where a build-time feature would leak into your runtime build; resolver 3 is its successor and the current default.) A root `Cargo.toml` that contains **only** `[workspace]` (no `[package]`) is a **virtual manifest**. The root is not itself a crate; it is just the coordinator. You can also make the root *both* a package and a workspace by including a `[package]` table alongside `[workspace]` (a “root package”), but for monorepos the virtual-manifest style keeps responsibilities clean. ### One `Cargo.lock`, one `target/` [Section titled “One Cargo.lock, one target/”](#one-cargolock-one-target) This is the heart of why workspaces exist. Run any build command anywhere in the tree and Cargo produces exactly one lockfile and one build directory at the root: ```text 1 $ cargo build --quiet 2 $ find . -name Cargo.lock -not -path './target/*' 3 ./Cargo.lock # exactly one, at the workspace root ``` Because every member resolves against the *same* `Cargo.lock`, two members can never accidentally pull in two different versions of `serde`. This is the version-skew problem that plagues JavaScript monorepos (where each package can hoist or nest a different copy in `node_modules/`); a Cargo workspace makes it structurally impossible. The shared `target/` also means a dependency compiled for one member is reused by every other member: no rebuild per package. ### Path dependencies between members [Section titled “Path dependencies between members”](#path-dependencies-between-members) `crates/cli` depends on `crates/core` through a **path dependency**: ```toml 1 # declared once at the root: 2 [workspace.dependencies] 3 taskhub-core = { path = "crates/core" } ``` ```toml 1 # used by the cli member: 2 [dependencies] 3 taskhub-core = { workspace = true } ``` A path dependency points at a sibling crate on disk rather than a registry. This is the direct analogue of a local package symlinked into `node_modules/` by npm workspaces. Because it is a path (not a version range), edits to `taskhub-core` are picked up immediately by `taskhub-cli`: no publish, no `npm link`, no rebuild step you have to remember. ### Workspace inheritance: `[workspace.package]` and `[workspace.dependencies]` [Section titled “Workspace inheritance: \[workspace.package\] and \[workspace.dependencies\]”](#workspace-inheritance-workspacepackage-and-workspacedependencies) Two tables let you declare shared settings once and inherit them with `.workspace = true`: * **`[workspace.package]`** holds package metadata (`version`, `edition`, `license`, `authors`, `repository`, `rust-version`, …) that members opt into with `version.workspace = true`, `edition.workspace = true`, and so on. Bump the version once at the root and every member moves together. * **`[workspace.dependencies]`** centralizes dependency *versions and features*. A member writes `serde = { workspace = true }` and inherits the `version = "1.0"` and `features = ["derive"]` from the root. A member can still add *extra* features on top: `serde = { workspace = true, features = ["rc"] }`. This solves a real JavaScript-monorepo pain point: keeping the version of a third-party dependency identical across every package. In npm you reach for tooling (syncpack, Nx constraints) to enforce it; in Cargo it is a first-class manifest feature. ### Workspace-wide lints [Section titled “Workspace-wide lints”](#workspace-wide-lints) You can also share lint configuration. Declare lints once at the root and have members opt in: ```toml 1 # root Cargo.toml 2 [workspace.lints.clippy] 3 unwrap_used = "warn" ``` ```toml 1 # each member Cargo.toml 2 [lints] 3 workspace = true ``` With that in place, running Clippy on any member that calls `.unwrap()` surfaces the shared rule (real output, trimmed to the lint note): ```text 1 warning: used `unwrap()` on an `Option` value 2 = note: if this value is `None`, it will panic 3 = help: consider using `expect()` to provide a better panic message 4 = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#unwrap_used ``` This is the Rust equivalent of a single root `.eslintrc` that every package extends. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | npm workspaces (JavaScript) | Cargo workspaces (Rust) | | --------------------------- | --------------------------------------------- | ---------------------------------------------------- | | Declared in | `"workspaces"` array in root `package.json` | `[workspace]` table in root `Cargo.toml` | | Root is a package? | Yes (usually `"private": true`) | Often a **virtual manifest** (no `[package]` at all) | | Local package linkage | Symlink into `node_modules/` | **Path dependency** (`{ path = "..." }`) | | Lockfile | One root `package-lock.json` | One root `Cargo.lock` (enforced, not optional) | | Build/output cache | Per-package, plus hoisting heuristics | One shared `target/` for the whole workspace | | Version skew of shared deps | Possible (different copies can be nested) | Impossible — single resolved graph | | Shared dependency versions | External tooling (syncpack, Nx) | Built-in `[workspace.dependencies]` | | Shared metadata | Manual or tooling | Built-in `[workspace.package]` inheritance | | Run a task in one package | `npm run build -w @taskhub/cli` | `cargo build -p taskhub-cli` | | Run a task everywhere | `npm run build --workspaces` | `cargo build --workspace` | | Task orchestration | Turborepo / Nx / Lerna for caching + ordering | Cargo computes the build DAG itself; no extra tool | The biggest conceptual shift: **a JavaScript monorepo is an opt-in pattern layered on top of npm with help from extra tooling, whereas a Cargo workspace is a native concept the compiler and build system understand directly.** There is no Rust equivalent of Turborepo because Cargo already knows the dependency graph between your crates and builds them in the right order with shared caching out of the box. > **Tip:** Selecting members on the command line uses `-p` / `--package` (one crate) or `--workspace` / `--all` (every member). The flags mirror npm’s `-w <name>` and `--workspaces`. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Putting `[profile.*]` in a member crate [Section titled “Pitfall 1: Putting \[profile.\*\] in a member crate”](#pitfall-1-putting-profile-in-a-member-crate) Profiles (`[profile.release]`, etc.) are **workspace-wide** and may only live in the root manifest. Add one to a member and Cargo ignores it with a warning. Adding `[profile.release]` to `crates/core/Cargo.toml` and building produces this real warning: ```text 1 warning: profiles for the non root package will be ignored, specify profiles at the workspace root: 2 package: /path/to/taskhub/crates/core/Cargo.toml 3 workspace: /path/to/taskhub/Cargo.toml ``` **Fix:** move every `[profile.*]` table to the root `Cargo.toml`. The same rule applies to the `[patch]` and `[replace]` tables; they are workspace-global. ### Pitfall 2: Inheriting a dependency that the root never declared [Section titled “Pitfall 2: Inheriting a dependency that the root never declared”](#pitfall-2-inheriting-a-dependency-that-the-root-never-declared) If a member writes `regex = { workspace = true }` but the root `[workspace.dependencies]` has no `regex` entry, the workspace fails to load. The real error: ```text 1 error: failed to load manifest for workspace member `/path/to/taskhub/crates/cli` 2 referenced by workspace at `/path/to/taskhub/Cargo.toml` 3 4 Caused by: 5 failed to parse manifest at `/path/to/taskhub/crates/cli/Cargo.toml` 6 7 Caused by: 8 error inheriting `regex` from workspace root manifest's `workspace.dependencies.regex` 9 10 Caused by: 11 `dependency.regex` was not found in `workspace.dependencies` ``` **Fix:** add `regex = "1"` to `[workspace.dependencies]` at the root first, then inherit it in the member with `regex = { workspace = true }`. ### Pitfall 3: Listing a member that does not exist yet [Section titled “Pitfall 3: Listing a member that does not exist yet”](#pitfall-3-listing-a-member-that-does-not-exist-yet) The root manifest validates *every* listed member before any command runs. If `members = ["crates/core", "crates/cli"]` but `crates/cli/` has no `Cargo.toml` yet, **every** cargo command in the workspace fails: ```text 1 failed to load manifest for workspace member `/path/to/taskhub/crates/cli` 2 referenced by workspace at `/path/to/taskhub/Cargo.toml` 3 4 Caused by: 5 failed to read `/path/to/taskhub/crates/cli/Cargo.toml` 6 7 Caused by: 8 No such file or directory (os error 2) ``` **Fix:** create the member crate before adding it to `members`, or use a glob (`members = ["crates/*"]`) so only existing directories are picked up. When scaffolding with `cargo new`, create the crate first; Cargo writes the new package without a `[workspace]` table because it detects it sits inside an existing workspace. ### Pitfall 4: `cargo run` in a workspace with several binaries [Section titled “Pitfall 4: cargo run in a workspace with several binaries”](#pitfall-4-cargo-run-in-a-workspace-with-several-binaries) In a single-crate project `cargo run` “just works.” In a workspace with more than one runnable binary it cannot guess which one you mean: ```text 1 $ cargo run 2 error: `cargo run` could not determine which binary to run. Use the `--bin` option to specify a binary, or the `default-run` manifest key. 3 available binaries: taskhub-cli, taskhub-web ``` **Fix:** disambiguate with `cargo run -p taskhub-cli`, or set `default-members = ["crates/cli"]` in the root `[workspace]` so bare `cargo run`/`cargo test` target your usual crate. ### Pitfall 5: Expecting `cargo new mypkg` to “add to the workspace” loudly [Section titled “Pitfall 5: Expecting cargo new mypkg to “add to the workspace” loudly”](#pitfall-5-expecting-cargo-new-mypkg-to-add-to-the-workspace-loudly) Coming from `npm init -w packages/foo`, you might expect explicit confirmation. `cargo new crates/foo` inside a workspace simply creates the crate and relies on your `members` list (or a glob) to include it — it does not print an “added to workspace” notice, and it deliberately omits a `[workspace]` table from the new child. If you used an explicit `members = [...]` list, remember to append the new path yourself. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Use a virtual manifest for monorepos.** A root `Cargo.toml` with only `[workspace]` keeps the root from accidentally becoming a publishable crate and makes the “this directory coordinates crates” intent obvious. * **Centralize versions in `[workspace.dependencies]`.** Declare every third-party crate’s version once at the root and inherit it everywhere with `{ workspace = true }`. This is the single most valuable workspace feature for avoiding version drift. * **Inherit shared metadata via `[workspace.package]`.** Put `version`, `edition`, `license`, and `rust-version` at the root and use `.workspace = true` in members so a single edit moves the whole workspace. * **Prefer glob members (`crates/*`) for fast-growing repos**, and an explicit list when you want tight control over what builds. * **Set `default-members`** to the crate(s) you run most so bare `cargo run`/`cargo test` do the obvious thing. * **Keep `[profile.*]`, `[patch]`, and `[replace]` at the root only.** They are workspace-global by definition. * **Commit the single root `Cargo.lock`.** For a workspace that ships applications/binaries this is the right call (reproducible builds); a workspace that publishes only libraries follows the usual library lockfile convention. See [Cargo.toml](/12-modules-packages/04-cargo/). * **Reach for a workspace when crates share code or ship together:** a CLI plus its library, a server plus shared domain types, a proc-macro crate plus the crate that uses it. Do not split a single cohesive crate into a workspace prematurely. > **Warning:** All members compile against one feature-unified dependency graph. If member A enables a heavy feature of a shared dependency, member B is built with that feature too (resolver 3 mitigates *build-vs-normal* leakage, not enabling-across-members). Keep heavyweight optional features behind crates that not every member depends on. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored three-crate workspace: a shared `taskhub-core` library, a `taskhub-cli` binary, and a `taskhub-web` binary stub. Because there are two binaries, `default-members` points bare commands at the CLI. Everything below was compiled and run as-is. ```toml 1 # taskhub/Cargo.toml — workspace root (virtual manifest) 2 [workspace] 3 resolver = "3" 4 members = ["crates/core", "crates/cli", "crates/web"] 5 default-members = ["crates/cli"] 6 7 [workspace.package] 8 version = "0.3.0" 9 edition = "2024" 10 license = "MIT OR Apache-2.0" 11 authors = ["Ada Zeybek <me@zeybek.dev>"] 12 13 [workspace.dependencies] 14 serde = { version = "1.0", features = ["derive"] } 15 serde_json = "1.0" 16 anyhow = "1" 17 taskhub-core = { path = "crates/core" } ``` Build the entire workspace at once: ```text 1 $ cargo build --workspace 2 Compiling taskhub-cli v0.3.0 (/path/to/taskhub/crates/cli) 3 Compiling taskhub-web v0.3.0 (/path/to/taskhub/crates/web) 4 Finished `dev` profile [unoptimized + debuginfo] target(s) in 4.92s ``` Test every member in one shot: ```text 1 $ cargo test --workspace 2 Compiling taskhub-core v0.3.0 (/path/to/taskhub/crates/core) 3 Compiling taskhub-cli v0.3.0 (/path/to/taskhub/crates/cli) 4 Compiling taskhub-web v0.3.0 (/path/to/taskhub/crates/web) 5 Running unittests src/lib.rs (target/debug/deps/taskhub_core-...) 6 test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s 7 Running unittests src/main.rs (target/debug/deps/taskhub_cli-...) 8 test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s 9 Running unittests src/main.rs (target/debug/deps/taskhub_web-...) 10 test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` Inspect the unified dependency graph with `cargo tree`. Note that `taskhub-core` appears as a path dependency of the CLI, exactly like a symlinked local package would in `node_modules/` (real output, trimmed): ```text 1 $ cargo tree -p taskhub-cli 2 taskhub-cli v0.3.0 (/path/to/taskhub/crates/cli) 3 ├── anyhow v1.0.102 4 ├── serde_json v1.0.150 5 │ ├── itoa v1.0.18 6 │ ├── memchr v2.8.1 7 │ ├── serde_core v1.0.228 8 │ └── zmij v1.0.21 9 └── taskhub-core v0.3.0 (/path/to/taskhub/crates/core) 10 └── serde v1.0.228 11 ├── serde_core v1.0.228 12 └── serde_derive v1.0.228 (proc-macro) ``` Because the entire graph resolves once into the root `Cargo.lock`, `taskhub-cli` and `taskhub-web` are guaranteed to use the *same* `serde` build: the version-skew problem simply cannot occur. > **Tip:** `cargo metadata --format-version 1` reports `workspace_root` and `workspace_members` as machine-readable JSON: the analogue of parsing a root `package.json`’s `workspaces` field with `jq`, but with the full resolved graph included. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Cargo Book — Workspaces](https://doc.rust-lang.org/cargo/reference/workspaces.html) — the authoritative reference for `[workspace]`, members, default-members, and inheritance. * [The Cargo Book — Dependency inheritance (`workspace = true`)](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#inheriting-a-dependency-from-a-workspace) * [The Cargo Book — The `[lints]` and `[workspace.lints]` tables](https://doc.rust-lang.org/cargo/reference/manifest.html#the-lints-section) * [The Cargo Book — Feature resolver versions](https://doc.rust-lang.org/cargo/reference/resolver.html#feature-resolver-version-2) — background on `resolver = "3"`. ### Cross-links in this guide [Section titled “Cross-links in this guide”](#cross-links-in-this-guide) * [Cargo.toml: the manifest, lockfile & profiles](/12-modules-packages/04-cargo/) — `[package]`, `Cargo.lock`, and the `[profile.*]` tables a workspace shares. * [Specifying dependencies](/12-modules-packages/06-dependencies/) — path/git deps and SemVer grammar that `[workspace.dependencies]` builds on. * [Dev & build dependencies](/12-modules-packages/07-dev-dependencies/) — `[dev-dependencies]` can also be inherited from the workspace. * [Feature flags](/12-modules-packages/09-feature-flags/) — how features unify across workspace members and why `resolver = "3"` matters. * [Cargo commands](/12-modules-packages/05-cargo-commands/) — `-p`/`--package`, `--workspace`, `cargo new`, `cargo tree`. * [Publishing to crates.io](/12-modules-packages/11-publishing/) — publishing individual members of a workspace. * The in-language module system that lives *inside* each crate: [Modules](/12-modules-packages/00-modules/) · [The module tree & paths](/12-modules-packages/01-module-tree/) · [`use` & re-exports](/12-modules-packages/02-use-keyword/) · [`pub` visibility](/12-modules-packages/03-pub-visibility/). * Foundations: [Why Rust](/00-introduction/) · [Understanding Cargo (intro)](/01-getting-started/03-cargo-basics/) · [Basics](/02-basics/). * Next up after modules: [Testing](/13-testing/) — `cargo test --workspace` runs every member’s tests together. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Turn two crates into a workspace [Section titled “Exercise 1: Turn two crates into a workspace”](#exercise-1-turn-two-crates-into-a-workspace) **Difficulty:** Beginner **Objective:** Create a virtual-manifest workspace whose binary depends on its sibling library by path. **Instructions:** Make a `taskhub/` directory with a root `Cargo.toml` (no `[package]`) listing two members, `crates/core` (a library) and `crates/cli` (a binary). Have `cli` call a function exported from `core`. Run `cargo run -p taskhub-cli` and confirm there is exactly one `Cargo.lock` at the root. Solution taskhub/Cargo.toml ```toml 1 [workspace] 2 resolver = "3" 3 members = ["crates/core", "crates/cli"] ``` crates/core/Cargo.toml ```toml 1 [package] 2 name = "taskhub-core" 3 version = "0.1.0" 4 edition = "2024" ``` crates/core/src/lib.rs ```rust 1 pub fn greeting(who: &str) -> String { 2 format!("hello from {who}") 3 } ``` crates/cli/Cargo.toml ```toml 1 [package] 2 name = "taskhub-cli" 3 version = "0.1.0" 4 edition = "2024" 5 6 [dependencies] 7 taskhub-core = { path = "../core" } ``` crates/cli/src/main.rs ```rust 1 fn main() { 2 println!("{}", taskhub_core::greeting("workspace")); 3 } ``` Build and verify the single lockfile: ```text 1 $ cargo run -p taskhub-cli --quiet 2 hello from workspace 3 $ find . -name Cargo.lock -not -path './target/*' 4 ./Cargo.lock ``` One `Cargo.lock` at the root is the proof that both members share a single resolved dependency graph. ### Exercise 2: Centralize versions with `[workspace.dependencies]` [Section titled “Exercise 2: Centralize versions with \[workspace.dependencies\]”](#exercise-2-centralize-versions-with-workspacedependencies) **Difficulty:** Intermediate **Objective:** Declare a third-party crate’s version once at the root and inherit it in two members, plus inherit shared package metadata. **Instructions:** Extend the workspace so the root declares `serde` (with the `derive` feature) and the shared `version`/`edition` in `[workspace.package]`. Both members inherit them with `{ workspace = true }` / `.workspace = true`. Make `core` derive `Serialize` on a struct and `cli` serialize it. Fill in the `/* ??? */` placeholders. taskhub/Cargo.toml ```toml 1 [workspace] 2 resolver = "3" 3 members = ["crates/core", "crates/cli"] 4 5 [workspace.package] 6 version = "0.2.0" 7 edition = "2024" 8 9 [workspace.dependencies] 10 serde = /* ??? */ # version "1.0" with the "derive" feature 11 serde_json = "1.0" 12 taskhub-core = { path = "crates/core" } ``` crates/core/Cargo.toml ```toml 1 [package] 2 name = "taskhub-core" 3 version.workspace = true 4 edition.workspace = true 5 6 [dependencies] 7 serde = /* ??? */ # inherit from the workspace ``` crates/core/src/lib.rs ```rust 1 use serde::Serialize; 2 3 #[derive(/* ??? */)] 4 pub struct Task { 5 pub id: u32, 6 pub title: String, 7 } ``` Solution taskhub/Cargo.toml ```toml 1 [workspace] 2 resolver = "3" 3 members = ["crates/core", "crates/cli"] 4 5 [workspace.package] 6 version = "0.2.0" 7 edition = "2024" 8 9 [workspace.dependencies] 10 serde = { version = "1.0", features = ["derive"] } 11 serde_json = "1.0" 12 taskhub-core = { path = "crates/core" } ``` crates/core/Cargo.toml ```toml 1 [package] 2 name = "taskhub-core" 3 version.workspace = true 4 edition.workspace = true 5 6 [dependencies] 7 serde = { workspace = true } ``` crates/core/src/lib.rs ```rust 1 use serde::Serialize; 2 3 #[derive(Debug, Serialize)] 4 pub struct Task { 5 pub id: u32, 6 pub title: String, 7 } ``` crates/cli/Cargo.toml ```toml 1 [package] 2 name = "taskhub-cli" 3 version.workspace = true 4 edition.workspace = true 5 6 [dependencies] 7 taskhub-core = { workspace = true } 8 serde_json = { workspace = true } ``` crates/cli/src/main.rs ```rust 1 use taskhub_core::Task; 2 3 fn main() { 4 let task = Task { id: 1, title: "Centralize versions".into() }; 5 println!("{}", serde_json::to_string(&task).unwrap()); 6 } ``` Real output: ```text 1 $ cargo run -p taskhub-cli --quiet 2 {"id":1,"title":"Centralize versions"} ``` The win: `serde`’s version and the `derive` feature are declared in exactly one place. Add a third member that needs `serde` and it inherits the same line: no chance of one crate using `serde` 1.0 and another a different copy. ### Exercise 3: Share lints and run the whole workspace’s tests [Section titled “Exercise 3: Share lints and run the whole workspace’s tests”](#exercise-3-share-lints-and-run-the-whole-workspaces-tests) **Difficulty:** Advanced **Objective:** Configure a workspace-wide Clippy lint that every member opts into, add a unit test to the library, and run all members’ tests together. **Instructions:** Add a `[workspace.lints.clippy]` table at the root that sets `unwrap_used = "warn"`, and have each member opt in with `[lints] workspace = true`. Add a `#[test]` to the library crate. Run `cargo test --workspace`, then run `cargo clippy --workspace` and observe the shared lint fire on a deliberate `.unwrap()`. Solution ```toml 1 # Cargo.toml (root) 2 [workspace] 3 resolver = "3" 4 members = ["crates/mathlib", "crates/calc"] 5 6 [workspace.package] 7 version = "0.1.0" 8 edition = "2024" 9 10 [workspace.dependencies] 11 mathlib = { path = "crates/mathlib" } 12 13 [workspace.lints.clippy] 14 unwrap_used = "warn" ``` crates/mathlib/Cargo.toml ```toml 1 [package] 2 name = "mathlib" 3 version.workspace = true 4 edition.workspace = true 5 6 [lints] 7 workspace = true ``` crates/mathlib/src/lib.rs ```rust 1 pub fn add(a: i64, b: i64) -> i64 { 2 a + b 3 } 4 5 #[cfg(test)] 6 mod tests { 7 use super::*; 8 9 #[test] 10 fn adds() { 11 assert_eq!(add(2, 3), 5); 12 } 13 } ``` crates/calc/Cargo.toml ```toml 1 [package] 2 name = "calc" 3 version.workspace = true 4 edition.workspace = true 5 6 [dependencies] 7 mathlib = { workspace = true } 8 9 [lints] 10 workspace = true ``` ```rust 1 // crates/calc/src/main.rs — deliberately uses unwrap() to trip the shared lint 2 fn first_word(s: &str) -> Option<&str> { 3 s.split_whitespace().next() 4 } 5 6 fn main() { 7 let _ = mathlib::add(2, 3); 8 let w = first_word("hello world"); 9 println!("{}", w.unwrap()); 10 } ``` Run the whole workspace’s tests (real output, compile lines trimmed): ```text 1 $ cargo test --workspace 2 Running unittests src/main.rs (target/debug/deps/calc-...) 3 4 running 0 tests 5 6 test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s 7 8 Running unittests src/lib.rs (target/debug/deps/mathlib-...) 9 10 running 1 test 11 test tests::adds ... ok 12 13 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s 14 15 Doc-tests mathlib 16 17 running 0 tests 18 19 test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` Run Clippy and watch the shared lint fire on the `.unwrap()` in `calc` (real output, trimmed): ```text 1 $ cargo clippy --workspace 2 warning: used `unwrap()` on an `Option` value 3 --> crates/calc/src/main.rs:8:20 4 | 5 8 | println!("{}", w.unwrap()); 6 | ^^^^^^^^^^ 7 | 8 = note: if this value is `None`, it will panic 9 = help: consider using `expect()` to provide a better panic message 10 = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#unwrap_used 11 = note: requested on the command line with `-W clippy::unwrap-used` ``` The single `[workspace.lints.clippy]` table is the Rust analogue of one root `.eslintrc` that every package extends: change the rule once and it applies across the monorepo. # Feature Flags and Conditional Compilation > Cargo features and #[cfg(...)] decide at compile time which code and optional dependencies ship, replacing the runtime process.env and tree-shaking tricks JS uses. Cargo **features** let one crate ship multiple optional capabilities behind named switches, and `#[cfg(...)]` lets the compiler include or exclude code *before it is ever compiled*. Together they replace the runtime `if (process.env.FEATURE)` and `package.json` `optionalDependencies` juggling that TypeScript/JavaScript developers reach for. But the decision happens at **compile time**, not at runtime. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **feature** is a named flag declared in `Cargo.toml` under `[features]`. Enabling a feature can pull in **optional dependencies** and turn on `#[cfg(feature = "...")]`-gated code. Because the gating happens at compile time, code behind a disabled feature is **not compiled at all**: it adds zero bytes to your binary and zero startup cost. For a TypeScript/JavaScript developer, the closest mental model is *bundler dead-code elimination driven by build flags* (think `process.env.NODE_ENV === "production"` checks that a bundler strips) combined with *optional peer dependencies*. The key differences: Rust does this in the language and the compiler (no bundler plugin needed), features are **additive** (turning one on never turns another off), and feature unification across your whole dependency graph is handled by Cargo. > **Note:** This page covers the language and manifest mechanics of features and `#[cfg]`. The dependency-spec syntax for enabling a *dependency’s* features (`features = [...]`, `default-features = false`) lives in [Specifying Dependencies](/12-modules-packages/06-dependencies/), and how features interact with `[dev-dependencies]`/`[build-dependencies]` and `optional = true` is in [Dev-Dependencies, Build-Dependencies, and Optional Dependencies](/12-modules-packages/07-dev-dependencies/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript/JavaScript there is no built-in compile-time feature system, so teams improvise. The two common approaches are **runtime environment checks** and **optional dependencies loaded dynamically**: ```typescript 1 // reporter.ts — runtime feature flags via environment variables 2 3 // Optional dependency: may or may not be installed (declared in 4 // package.json "optionalDependencies"). We must guard the require. 5 type YamlModule = { dump(value: unknown): string }; 6 7 interface Report { 8 name: string; 9 passed: number; 10 failed: number; 11 } 12 13 const FEATURES = { 14 json: process.env.FEATURE_JSON !== "0", // on by default 15 yaml: process.env.FEATURE_YAML === "1", // off by default 16 metrics: process.env.FEATURE_METRICS === "1", 17 }; 18 19 async function render(report: Report): Promise<string> { 20 if (FEATURES.json) { 21 return JSON.stringify(report, null, 2); 22 } 23 24 if (FEATURES.yaml) { 25 // The yaml package might not be installed; this throws at RUNTIME if missing. 26 const yaml = (await import("js-yaml")) as unknown as YamlModule; 27 return yaml.dump(report); 28 } 29 30 return `${report.name} - ${report.passed} passed, ${report.failed} failed`; 31 } 32 33 if (FEATURES.metrics) { 34 // Dead code is still shipped in the bundle even when this is false. 35 console.error("[metrics] reporter initialized"); 36 } 37 38 export { render, FEATURES }; ``` The problems a TypeScript/JavaScript developer lives with here: * **Everything ships anyway.** The `yaml` branch and the `metrics` code are in the bundle even when the flags are off. Tree-shaking helps only if the bundler can statically prove the branch is dead. * **Failures are at runtime.** A missing optional dependency or a typo in a flag name explodes when the code runs, possibly in production. * **No type-level guarantee** that you only call code that is actually enabled. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) In Rust, features are declared in the manifest and the compiler removes disabled code entirely. Here is the same reporter as a Cargo crate. Cargo.toml ```toml 1 [package] 2 name = "reporter" 3 version = "0.1.0" 4 edition = "2024" 5 6 [features] 7 # `default` lists the features that are on unless the user opts out. 8 default = ["json"] 9 # A feature can pull in OPTIONAL dependencies via the `dep:` syntax. 10 json = ["dep:serde", "dep:serde_json"] 11 yaml = ["dep:serde", "dep:serde_norway"] 12 # A pure code flag with no dependencies of its own. 13 metrics = [] 14 15 [dependencies] 16 serde = { version = "1", features = ["derive"], optional = true } 17 serde_json = { version = "1", optional = true } 18 serde_norway = { version = "0.9", optional = true } ``` src/main.rs ```rust 1 // Add the `Serialize` derive ONLY when a serializing format is enabled. 2 #[cfg_attr(any(feature = "json", feature = "yaml"), derive(serde::Serialize))] 3 struct Report { 4 name: String, 5 passed: u32, 6 failed: u32, 7 } 8 9 impl Report { 10 /// Render in whatever format the build was compiled with. 11 fn render(&self) -> String { 12 #[cfg(feature = "json")] 13 { 14 return serde_json::to_string_pretty(self).expect("serialize json"); 15 } 16 #[cfg(all(feature = "yaml", not(feature = "json")))] 17 { 18 return serde_norway::to_string(self).expect("serialize yaml"); 19 } 20 #[cfg(not(any(feature = "json", feature = "yaml")))] 21 { 22 format!("{} - {} passed, {} failed", self.name, self.passed, self.failed) 23 } 24 } 25 } 26 27 fn main() { 28 let report = Report { name: "build-42".into(), passed: 128, failed: 3 }; 29 println!("{}", report.render()); 30 } ``` Building with the default features (`json`) produces: ```plaintext 1 { 2 "name": "build-42", 3 "passed": 128, 4 "failed": 3 5 } ``` Building with `cargo run --no-default-features --features yaml`: ```plaintext 1 name: build-42 2 passed: 128 3 failed: 3 ``` Building with `cargo run --no-default-features` (no format at all): ```plaintext 1 build-42 - 128 passed, 3 failed ``` The `serde_norway` crate (the maintained successor to the deprecated `serde_yaml`; see [Beyond JSON](/15-serialization/06-other-formats/)) is **never downloaded, compiled, or linked** unless someone turns on the `yaml` feature. Disabled branches contribute nothing to the binary. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The `[features]` table [Section titled “The \[features\] table”](#the-features-table) Each entry maps a **feature name** to a list of things it enables. Those “things” come in three flavors: ```toml 1 [features] 2 default = ["json"] # 1. other features (the default set) 3 json = ["dep:serde_json"] # 2. an optional dependency, via `dep:` 4 full = ["json", "yaml", "metrics"] # 3. a bundle that enables several features ``` * **Enabling other features** lets you build convenience bundles. `full = ["json", "yaml", "metrics"]` turns on three features at once. * **`dep:<name>`** turns on an optional dependency declared with `optional = true`. The `dep:` prefix (stable since Rust 1.60) keeps the dependency out of the implicit feature namespace, so adding an optional dependency does not silently create a same-named public feature. * The special **`default`** feature is the set Cargo enables when nobody says otherwise. ### `#[cfg(feature = "...")]` — the attribute form [Section titled “#\[cfg(feature = "...")\] — the attribute form”](#cfgfeature----the-attribute-form) `#[cfg(...)]` is an **attribute** that conditionally includes the item it is attached to. If the predicate is false, the compiler behaves as if the item *does not exist in the source*: ```rust 1 #[cfg(feature = "metrics")] 2 fn report_metrics() { 3 println!("metrics: 1 export performed"); 4 } 5 6 // A fallback with the SAME name for when the feature is off, so callers 7 // always have a `report_metrics` to call. 8 #[cfg(not(feature = "metrics"))] 9 fn report_metrics() { 10 // No-op when the `metrics` feature is off. 11 } ``` You can attach `#[cfg]` to almost anything: functions, structs, enum variants, `impl` blocks, modules, `use` statements, even individual struct fields. A common pattern is gating a whole module: ```rust 1 #[cfg(feature = "compression")] 2 pub mod compress { 3 pub fn level() -> u32 { 4 6 5 } 6 } ``` ### `cfg!(...)` — the expression form [Section titled “cfg!(...) — the expression form”](#cfg--the-expression-form) `cfg!(...)` is a **macro** that evaluates to a `bool` at compile time. The key difference from `#[cfg]`: **both branches of the surrounding `if` must still type-check and compile**, because `cfg!` only chooses a value, it does not delete code: ```rust 1 fn main() { 2 // Both arms must compile; only the VALUE is decided at compile time. 3 let level = if cfg!(feature = "verbose") { "verbose" } else { "quiet" }; 4 println!("log level: {level}"); 5 } ``` Use `cfg!` when both branches are valid regardless of the flag (e.g. choosing a string). Use `#[cfg]` when the disabled branch references items that only exist under the feature; those would fail to compile if you used `cfg!`. ### `#[cfg_attr(...)]` — conditional attributes [Section titled “#\[cfg\_attr(...)\] — conditional attributes”](#cfg_attr--conditional-attributes) `#[cfg_attr(predicate, attribute)]` applies *another attribute* only when the predicate holds. This is how you conditionally derive a trait: ```rust 1 // Adds `#[derive(serde::Serialize)]` only when `serde` is enabled. 2 #[cfg_attr(feature = "serde", derive(serde::Serialize))] 3 #[derive(Debug)] 4 struct Config { 5 retries: u32, 6 endpoint: String, 7 } ``` When the `serde` feature is off, the type still derives `Debug` but not `Serialize`, and the `serde` crate is never pulled in. ### `cfg` predicates beyond features [Section titled “cfg predicates beyond features”](#cfg-predicates-beyond-features) `#[cfg]` is not limited to features. It is the same mechanism Rust uses for platform-specific code, which needs **no `[features]` entry at all**: ```rust 1 fn main() { 2 if cfg!(target_os = "macos") { 3 println!("running on macOS"); 4 } else { 5 println!("running on a non-macOS platform"); 6 } 7 } ``` Common predicates include `target_os`, `target_arch`, `target_pointer_width`, `unix`, `windows`, `debug_assertions` (true in debug builds), and `test` (true under `cargo test`). They combine with `all(...)`, `any(...)`, and `not(...)`: ```rust 1 #[cfg(all(feature = "yaml", not(feature = "json")))] ``` ### Where features come from at build time [Section titled “Where features come from at build time”](#where-features-come-from-at-build-time) Cargo passes the enabled features to `rustc` as `--cfg feature="json"` flags. The relevant command-line knobs: | Flag | Effect | | ----------------------- | -------------------------------------------------------- | | `--features "a b"` | Enable features `a` and `b` (space- or comma-separated). | | `--no-default-features` | Do **not** enable the `default` set. | | `--all-features` | Enable every feature the crate declares. | These work on `cargo build`, `cargo run`, `cargo test`, `cargo check`, and friends. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | TypeScript/JavaScript | Rust features + `#[cfg]` | | --------------------------------------- | --------------------------------------------------- | --------------------------------------------------------- | | When the decision happens | Runtime (`process.env`) or bundler build step | **Compile time**, by the compiler itself | | Disabled code | Usually still shipped; tree-shaking is best-effort | **Not compiled at all**: zero bytes, zero cost | | Optional dependency | `optionalDependencies` + guarded dynamic `import()` | `optional = true` dep pulled in by a feature via `dep:` | | Failure mode for a missing optional dep | Throws at runtime when reached | Won’t compile if you call code whose feature is off | | Combining flags | Ad-hoc booleans | `all(...)` / `any(...)` / `not(...)` predicates | | Cross-package coordination | None built in | **Feature unification** across the whole dependency graph | | Intended semantics | Anything goes | **Additive** — features only add, never remove | ### Feature unification [Section titled “Feature unification”](#feature-unification) This has no TypeScript/JavaScript equivalent and trips up newcomers. If crate `A` depends on `serde` with `features = ["derive"]` and crate `B` (in the same build) depends on `serde` with `features = ["rc"]`, Cargo compiles **one** copy of `serde` with the **union** `["derive", "rc"]`. Features are unified across the entire graph so that a single build of each crate satisfies everyone. The direct consequence: **enabling a feature anywhere can enable it everywhere**, which is precisely why features must be *additive*. You can inspect the resolved feature graph with: ```bash 1 cargo tree -e features ``` > **Note:** Unlike npm, which can install multiple versions of the same package in nested `node_modules`, Cargo compiles one build of a crate per *semver-compatible* version with all requested features merged. There is no per-consumer feature isolation. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Calling an item that is gated behind a disabled feature [Section titled “Pitfall 1: Calling an item that is gated behind a disabled feature”](#pitfall-1-calling-an-item-that-is-gated-behind-a-disabled-feature) If you reference a function that only exists under a feature, and that feature is off, the item is “configured out” and the call fails to compile: ```rust 1 #[cfg(feature = "advanced")] 2 fn turbo() -> u32 { 3 9000 4 } 5 6 fn main() { 7 // does not compile (error[E0425]) when `advanced` is OFF. 8 println!("{}", turbo()); 9 } ``` Building with the feature off produces a real, helpful error: ```plaintext 1 error[E0425]: cannot find function `turbo` in this scope 2 --> src/main.rs:8:20 3 | 4 8 | println!("{}", turbo()); 5 | ^^^^^ not found in this scope 6 | 7 note: found an item that was configured out 8 --> src/main.rs:2:4 9 | 10 1 | #[cfg(feature = "advanced")] 11 | -------------------- the item is gated behind the `advanced` feature 12 2 | fn turbo() -> u32 { 13 | ^^^^^ 14 15 For more information about this error, try `rustc --explain E0425`. ``` The fix: either provide a `#[cfg(not(feature = "advanced"))]` fallback with the same signature, or wrap the **call site** in `#[cfg(feature = "advanced")]` too. ### Pitfall 2: Using `cfg!` where you needed `#[cfg]` [Section titled “Pitfall 2: Using cfg! where you needed #\[cfg\]”](#pitfall-2-using-cfg-where-you-needed-cfg) `cfg!` does not remove code; both arms must compile. This bites when the disabled arm uses a feature-gated item: ```rust 1 // If `serde_json` only exists under a feature, this still tries to compile 2 // the call in BOTH arms, so it fails when the feature is off. 3 let out = if cfg!(feature = "json") { 4 serde_json::to_string(&value).unwrap() // referenced even when off! 5 } else { 6 String::new() 7 }; ``` Use the attribute form so the disabled branch is genuinely deleted: ```rust 1 #[cfg(feature = "json")] 2 let out = serde_json::to_string(&value).unwrap(); 3 #[cfg(not(feature = "json"))] 4 let out = String::new(); ``` ### Pitfall 3: Designing non-additive (mutually exclusive) features [Section titled “Pitfall 3: Designing non-additive (mutually exclusive) features”](#pitfall-3-designing-non-additive-mutually-exclusive-features) Because of feature unification, a feature that *removes* or *changes* behavior is dangerous: some other crate in the graph might turn it on, breaking your build in surprising ways. Anti-pattern: ```toml 1 [features] 2 fast = [] 3 small = [] # "fast" and "small" are meant to be mutually exclusive — BAD design ``` If you truly cannot avoid a conflict, fail **loudly** at compile time with `compile_error!` rather than silently miscompiling: ```rust 1 #[cfg(all(feature = "fast", feature = "small"))] 2 compile_error!("features `fast` and `small` are mutually exclusive; enable only one"); ``` Enabling both then yields a clear error instead of a subtle bug: ```plaintext 1 error: features `fast` and `small` are mutually exclusive; enable only one 2 --> src/main.rs:4:1 3 | 4 4 | compile_error!("features `fast` and `small` are mutually exclusive; enable only one"); 5 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``` The better fix is almost always to redesign so the two paths are additive (e.g. pick at runtime, or split into two crates). ### Pitfall 4: Forgetting your crate compiles with `--no-default-features` [Section titled “Pitfall 4: Forgetting your crate compiles with --no-default-features”](#pitfall-4-forgetting-your-crate-compiles-with---no-default-features) Downstream users routinely disable default features to trim builds. If your default-on code is the only thing that makes the crate usable, a `--no-default-features` build can break or do nothing useful. Test it in CI: ```bash 1 cargo check --no-default-features 2 cargo check --all-features ``` ### Pitfall 5: Dead-code warnings when a field is only used by a gated derive [Section titled “Pitfall 5: Dead-code warnings when a field is only used by a gated derive”](#pitfall-5-dead-code-warnings-when-a-field-is-only-used-by-a-gated-derive) A struct field read *only* by a `#[cfg_attr(..., derive(Serialize))]` will warn as dead code when the feature is off, because the serialize impl that reads it no longer exists. Either read the field in some always-compiled path, or annotate it (`#[allow(dead_code)]`) deliberately. The compiler message is the standard `field is never read` / `#[warn(dead_code)]`. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Keep features additive.** Enabling a feature should only *add* capability. Never make one feature turn another off or change a function’s meaning. * **Make `default` a sensible, minimal “it just works” set.** Put heavy or niche capabilities behind opt-in features so cost-conscious users can strip them with `--no-default-features`. * **Use `dep:` to gate optional dependencies** instead of relying on the old implicit “dependency name becomes a feature” behavior. It keeps your public feature surface intentional. * **Document every feature** in your crate docs and `README`, and consider a doc-comment table. Hidden features are a support burden. * **Test the feature matrix in CI.** At minimum run `cargo check --no-default-features` and `cargo check --all-features`. The [cargo-hack](https://github.com/taiki-e/cargo-hack) tool can test each feature in isolation with `cargo hack check --feature-powerset`. * **Prefer `#[cfg]` (attribute) for code that only exists under a feature**, and `cfg!` (macro) only when both branches genuinely compile. * **Name features after capabilities, not implementations** (`compression`, not `flate2`), so you can swap the implementation later without a breaking change. * **Re-enable docs for hidden features.** When publishing, [docs.rs](https://docs.rs) can be told which features to document via `[package.metadata.docs.rs]` in `Cargo.toml`; see [Publishing to crates.io](/12-modules-packages/11-publishing/). > **Tip:** Use `cargo tree -e features` to see exactly which features the resolver turned on and *why*. It is the single most useful command for debugging “why is this dependency being built?”. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small library crate that gates an entire module and an optional dependency behind features: the shape of a typical published crate. Cargo.toml ```toml 1 [package] 2 name = "archive" 3 version = "0.1.0" 4 edition = "2024" 5 6 [features] 7 default = ["compression"] 8 compression = ["dep:flate2"] 9 logging = [] 10 11 [dependencies] 12 flate2 = { version = "1", optional = true } ``` src/lib.rs ```rust 1 //! A tiny library that gates an entire module behind a feature. 2 3 pub fn version() -> &'static str { 4 "0.1.0" 5 } 6 7 /// Compiled only when the `compression` feature is enabled (it is, by default). 8 #[cfg(feature = "compression")] 9 pub mod compress { 10 /// The default zlib compression level. 11 pub fn level() -> u32 { 12 6 13 } 14 } 15 16 /// An optional, zero-dependency logging hook. 17 #[cfg(feature = "logging")] 18 pub fn log(msg: &str) { 19 eprintln!("[log] {msg}"); 20 } ``` A downstream consumer that depends on this crate writes, in *its* `Cargo.toml`: ```toml 1 [dependencies] 2 # Take only what we need: no compression, but turn on logging. 3 archive = { version = "0.1", default-features = false, features = ["logging"] } ``` With the default features on, `cargo tree` shows `flate2` and its transitive dependencies being built: ```plaintext 1 archive v0.1.0 (/path/to/archive) 2 └── flate2 v1.1.9 3 ├── crc32fast v1.5.0 4 │ └── cfg-if v1.0.4 5 └── miniz_oxide v0.8.9 6 ├── adler2 v2.0.1 7 └── simd-adler32 v0.3.9 ``` Building the same crate with `cargo build --no-default-features` drops `flate2` and everything under it from the build graph entirely. The `compress` module simply does not exist in that build, so nothing references the compression dependency. > **Note:** This is a real strength over the TypeScript/JavaScript optional-dependency story: the dependency is not merely *unused at runtime*, it is **never fetched or compiled**, which shrinks build times, binary size, and the audited dependency surface. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [The Cargo Book — Features](https://doc.rust-lang.org/cargo/reference/features.html) — the authoritative reference for `[features]`, `dep:`, and unification. * [The Cargo Book — Features Examples](https://doc.rust-lang.org/cargo/reference/features-examples.html) — patterns for default features, optional deps, and feature bundles. * [The Rust Reference — Conditional compilation](https://doc.rust-lang.org/reference/conditional-compilation.html) — the full grammar of `cfg`, `cfg_attr`, and every built-in predicate. * [`std::cfg!` macro docs](https://doc.rust-lang.org/std/macro.cfg.html) — the expression form. * Related pages in this section: [Specifying Dependencies](/12-modules-packages/06-dependencies/) (enabling a dependency’s features), [Dev-Dependencies, Build-Dependencies, and Optional Dependencies](/12-modules-packages/07-dev-dependencies/) (`optional = true` and build/dev deps), [Cargo.toml](/12-modules-packages/04-cargo/) (the manifest as a whole), [Cargo Workspaces](/12-modules-packages/08-workspaces/) (features across a workspace), and [Publishing to crates.io](/12-modules-packages/11-publishing/) (documenting features on docs.rs). * Foundations: [Section 00 — Introduction](/00-introduction/), [Section 01 — Getting Started](/01-getting-started/), and [Section 02 — Basics](/02-basics/). * Features pair naturally with conditional tests; see [Section 13 — Testing](/13-testing/) for `#[cfg(test)]` and feature-gated test suites. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Add a feature-gated function [Section titled “Exercise 1: Add a feature-gated function”](#exercise-1-add-a-feature-gated-function) **Difficulty:** Easy **Objective:** Declare a feature and gate a function behind it so the crate builds both with and without the feature. **Instructions:** Starting from a fresh `cargo new feat-ex1`, add a `pretty` feature to `Cargo.toml`. Write a `greeting()` function that returns `"=== Hello ==="` when `pretty` is on and `"Hello"` when it is off. Print it from `main`. Verify both `cargo run` and `cargo run --features pretty`. Cargo.toml ```toml 1 [package] 2 name = "feat-ex1" 3 version = "0.1.0" 4 edition = "2024" 5 6 [features] 7 # TODO: declare the `pretty` feature ``` src/main.rs ```rust 1 // TODO: write two cfg-gated `greeting` functions and call one from main. 2 fn main() { 3 println!("{}", greeting()); 4 } ``` Solution Cargo.toml ```toml 1 [package] 2 name = "feat-ex1" 3 version = "0.1.0" 4 edition = "2024" 5 6 [features] 7 default = [] 8 pretty = [] ``` src/main.rs ```rust 1 #[cfg(feature = "pretty")] 2 fn greeting() -> &'static str { 3 "=== Hello ===" 4 } 5 6 #[cfg(not(feature = "pretty"))] 7 fn greeting() -> &'static str { 8 "Hello" 9 } 10 11 fn main() { 12 println!("{}", greeting()); 13 } ``` **Output of `cargo run`:** ```plaintext 1 Hello ``` **Output of `cargo run --features pretty`:** ```plaintext 1 === Hello === ``` Providing both a `#[cfg(feature = "pretty")]` and a `#[cfg(not(feature = "pretty"))]` definition means `greeting` always exists, so the call site never needs its own `#[cfg]`. *** ### Exercise 2: A feature that enables other features [Section titled “Exercise 2: A feature that enables other features”](#exercise-2-a-feature-that-enables-other-features) **Difficulty:** Medium **Objective:** Build a `full` “bundle” feature that turns on two other features, and report which are active at runtime. **Instructions:** Declare features `std` (in the default set), `extras`, and `full` such that enabling `full` enables both `std` and `extras`. In `main`, use `cfg!` to collect the active feature names into a `Vec<&str>` and print them joined by `", "`. Verify the output for the default build, `--features full`, and `--no-default-features`. Solution Cargo.toml ```toml 1 [package] 2 name = "feat-ex2" 3 version = "0.1.0" 4 edition = "2024" 5 6 [features] 7 default = ["std"] 8 std = [] 9 # `full` turns on everything; a feature can enable other features. 10 full = ["std", "extras"] 11 extras = [] ``` src/main.rs ```rust 1 fn main() { 2 let mut enabled: Vec<&str> = Vec::new(); 3 if cfg!(feature = "std") { 4 enabled.push("std"); 5 } 6 if cfg!(feature = "extras") { 7 enabled.push("extras"); 8 } 9 10 if enabled.is_empty() { 11 println!("features: <none>"); 12 } else { 13 println!("features: {}", enabled.join(", ")); 14 } 15 } ``` **Outputs:** ```plaintext 1 # cargo run (default) 2 features: std 3 4 # cargo run --features full 5 features: std, extras 6 7 # cargo run --no-default-features --features full 8 features: std, extras 9 10 # cargo run --no-default-features 11 features: <none> ``` Note that `cfg!` is the right tool here because both arms of each `if` compile no matter which features are on: we are only branching on a `bool`, not deleting code. *** ### Exercise 3: Mutually exclusive features done safely [Section titled “Exercise 3: Mutually exclusive features done safely”](#exercise-3-mutually-exclusive-features-done-safely) **Difficulty:** Hard **Objective:** Model two conflicting build modes and make the *conflict* a compile error instead of a silent bug, while keeping a sensible default. **Instructions:** Declare features `fast` and `small`. The program should print `"optimized for speed"` under `fast`, `"optimized for size"` under `small`, and `"balanced defaults"` under neither. Enabling **both** at once must fail to compile with a clear message. Verify: default build prints the balanced message, `--features fast` prints the speed message, and `--features "fast small"` fails with your message. Solution Cargo.toml ```toml 1 [package] 2 name = "feat-ex3" 3 version = "0.1.0" 4 edition = "2024" 5 6 [features] 7 default = [] 8 fast = [] 9 small = [] ``` src/main.rs ```rust 1 // Non-additive features are an anti-pattern; if a conflict is truly 2 // unavoidable, fail LOUDLY at compile time instead of miscompiling. 3 #[cfg(all(feature = "fast", feature = "small"))] 4 compile_error!("features `fast` and `small` are mutually exclusive; enable only one"); 5 6 fn main() { 7 if cfg!(feature = "fast") { 8 println!("optimized for speed"); 9 } else if cfg!(feature = "small") { 10 println!("optimized for size"); 11 } else { 12 println!("balanced defaults"); 13 } 14 } ``` **Outputs:** ```plaintext 1 # cargo run (default) 2 balanced defaults 3 4 # cargo run --features fast 5 optimized for speed 6 7 # cargo build --features "fast small" 8 error: features `fast` and `small` are mutually exclusive; enable only one 9 --> src/main.rs:4:1 10 | 11 4 | compile_error!("features `fast` and `small` are mutually exclusive; enable only one"); 12 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``` > **Tip:** The “correct” production answer is usually to redesign so the two modes are additive (decide at runtime, or split into two crates), because feature unification means *some other crate in the graph* could enable both: the `compile_error!` guard is your safety net, not your design. # Build Scripts: Code Generation and Native Linking with `build.rs` > build.rs is Rust's compile-time hook, like an npm prebuild or node-gyp: generate code into OUT_DIR, link C with the cc crate, and control reruns with cargo:: lines. A **build script** (`build.rs`) is Rust code that Cargo compiles and runs *before* it builds your crate. It is the closest thing Rust has to a `prebuild`/`postinstall` npm hook or a `node-gyp` step, but it is plain Rust, it talks to Cargo over `stdout`, and it is sandboxed to a private output directory. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In the Node.js world, anything you need to happen before your code runs (generating files, compiling a native addon, downloading a binary) lives in a `scripts` hook (`prebuild`, `postinstall`) or a tool like `node-gyp`. Rust folds all of that into a single optional file named `build.rs` at the crate root: Cargo compiles it, runs it once per build, and listens to special `cargo::` lines it prints to decide what to compile, what native libraries to link, and when to re-run. This page focuses on the three jobs build scripts do most: **generating Rust source code**, **compiling and linking native (C/C++) libraries**, and **controlling re-runs** with `cargo::rerun-if-*` directives. > **Note:** A build script is *not* a place to run your app’s logic. It runs at compile time on the *build* machine, not at runtime. Think `tsc` plugin or `node-gyp`, not `node index.js`. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In a Node project, build-time work is wired through `package.json` lifecycle scripts and sometimes a helper script that generates code: package.json ```json 1 { 2 "name": "status-lib", 3 "version": "1.0.0", 4 "type": "module", 5 "scripts": { 6 "generate": "node scripts/generate-status.mjs", 7 "prebuild": "npm run generate", 8 "build": "tsc" 9 }, 10 "devDependencies": { 11 "typescript": "^5.5.0" 12 } 13 } ``` ```javascript 1 // scripts/generate-status.mjs — run before `tsc` to emit a TS file from data 2 import { readFile, writeFile } from "node:fs/promises"; 3 4 const raw = await readFile(new URL("../status_codes.json", import.meta.url), "utf8"); 5 const map = JSON.parse(raw); 6 7 let out = "// AUTO-GENERATED — do not edit\n"; 8 out += "export function reasonPhrase(code: number): string | undefined {\n"; 9 out += " switch (code) {\n"; 10 for (const [code, reason] of Object.entries(map)) { 11 out += ` case ${code}: return ${JSON.stringify(reason)};\n`; 12 } 13 out += " default: return undefined;\n }\n}\n"; 14 15 await writeFile(new URL("../src/status.generated.ts", import.meta.url), out); ``` This works, but notice the friction: the script writes *into your source tree* (`src/status.generated.ts`), you must remember to `.gitignore` it, and `prebuild` runs every single time regardless of whether the input changed. For native addons you would reach for an entirely separate toolchain (`node-gyp` + a `binding.gyp` file). *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same code-generation task as a Cargo build script. The generated file goes into a Cargo-managed scratch directory (`OUT_DIR`), never your source tree: Cargo.toml ```toml 1 [package] 2 name = "status-lib" 3 version = "1.0.0" 4 edition = "2024" 5 6 [build-dependencies] 7 serde_json = "1" ``` ```rust 1 // build.rs — Cargo compiles and runs this before building the crate 2 use std::collections::BTreeMap; 3 use std::env; 4 use std::fmt::Write as _; 5 use std::fs; 6 use std::path::Path; 7 8 fn main() { 9 // Cargo hands every build script a private scratch directory via OUT_DIR. 10 let out_dir = env::var("OUT_DIR").unwrap(); 11 let dest = Path::new(&out_dir).join("status.rs"); 12 13 let raw = fs::read_to_string("status_codes.json").expect("status_codes.json"); 14 let map: BTreeMap<u16, String> = 15 serde_json::from_str(&raw).expect("valid JSON object of code->reason"); 16 17 // Build a `match`-based lookup function as a String of Rust source. 18 let mut code = String::from( 19 "pub fn reason_phrase(code: u16) -> Option<&'static str> {\n match code {\n", 20 ); 21 for (status, reason) in &map { 22 // {reason:?} prints the &str with quotes + escaping — valid Rust literal. 23 writeln!(code, " {status} => Some({reason:?}),").unwrap(); 24 } 25 code.push_str(" _ => None,\n }\n}\n"); 26 fs::write(&dest, code).unwrap(); 27 28 // Re-run ONLY when these inputs change (see the directives section below). 29 println!("cargo::rerun-if-changed=status_codes.json"); 30 println!("cargo::rerun-if-changed=build.rs"); 31 } ``` ```rust 1 // src/lib.rs — pull the generated file in at compile time 2 include!(concat!(env!("OUT_DIR"), "/status.rs")); 3 4 #[cfg(test)] 5 mod tests { 6 #[test] 7 fn known_code() { 8 assert_eq!(super::reason_phrase(404), Some("Not Found")); 9 } 10 } ``` Running `cargo build` produces (real output from a `cargo run` driver of this exact code): ```text 1 Compiling status-lib v1.0.0 (/private/tmp/.../status-lib) 2 Finished `dev` profile [unoptimized + debuginfo] target(s) in 3.03s 3 200 => Some("OK") 4 404 => Some("Not Found") 5 418 => None ``` The generated `status.rs` lives under `target/`, so it is gitignored automatically and never pollutes your source tree. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) A build script is **convention over configuration**: if a file named `build.rs` exists at the crate root, Cargo automatically compiles it as a separate tiny binary and runs it before compiling your crate. There is no manifest entry to add (though you can point at a different file with `build = "path/to/build.rs"` under `[package]`). Walking through the moving parts: * **`[build-dependencies]`** is a separate dependency table just for the build script. Crates listed here are compiled for the *host* (build) machine and are **not** linked into your final binary. `serde_json` here is used only during the build. This is distinct from `[dependencies]` and `[dev-dependencies]`; see [Dev & Build Dependencies](/12-modules-packages/07-dev-dependencies/). * **`OUT_DIR`** is an environment variable Cargo sets for the build script, pointing at a unique per-crate directory like `target/debug/build/status-lib-<hash>/out`. You write generated files *there*, never into `src/`. The `unwrap()` is safe because Cargo always sets it. * **Communication is via `stdout`.** The build script does not return data through a function. Instead it *prints* lines beginning with `cargo::` (note the **double colon** — the modern syntax). Cargo parses those lines and acts on them. Lines that do not start with `cargo::` are treated as ordinary log output. * **`include!(concat!(env!("OUT_DIR"), "/status.rs"))`** is the bridge back into your crate. Here `env!` is a *compile-time* macro (it reads the env var while `rustc` runs, not at program startup), `concat!` builds the path literal, and `include!` textually pastes the generated tokens into your module, exactly as if you had typed them. This is the standard pattern for consuming generated code. * **`{reason:?}`** in the `writeln!` uses Rust’s `Debug` formatting for `&str`, which emits a properly quoted and escaped string literal. Generating source as text means you must produce *syntactically valid Rust*; `Debug` formatting of strings does the escaping for you. Contrast with the Node version: there is no `prebuild` hook to wire up, the output never touches your source tree, and, most importantly, the `cargo::rerun-if-changed` lines let Cargo *skip* the script entirely when nothing relevant changed. The Node `prebuild` runs unconditionally. > **Tip:** The build script is just Rust. You can unit-test the generation logic by factoring it into a function, and you get the full standard library plus any `[build-dependencies]`. *** ## Compiling and Linking Native Libraries [Section titled “Compiling and Linking Native Libraries”](#compiling-and-linking-native-libraries) The second major job of build scripts is building and linking C/C++ code: Rust’s answer to `node-gyp`. The community standard is the [`cc`](https://docs.rs/cc) crate, which locates a C compiler, compiles your sources into a static library, and emits the correct link directives automatically. Cargo.toml ```toml 1 [package] 2 name = "native_math" 3 version = "0.1.0" 4 edition = "2024" 5 6 [build-dependencies] 7 cc = "1.2" ``` ```c 1 /* csrc/checksum.c — a small Fletcher-16 checksum in C */ 2 #include <stddef.h> 3 #include <stdint.h> 4 5 uint16_t fletcher16(const uint8_t *data, size_t len) { 6 uint16_t sum1 = 0, sum2 = 0; 7 for (size_t i = 0; i < len; i++) { 8 sum1 = (sum1 + data[i]) % 255; 9 sum2 = (sum2 + sum1) % 255; 10 } 11 return (sum2 << 8) | sum1; 12 } ``` build.rs ```rust 1 fn main() { 2 // cc finds a C compiler, builds the source into a static lib, AND emits 3 // the cargo::rustc-link-* directives for you. No manual linking needed. 4 cc::Build::new() 5 .file("csrc/checksum.c") 6 .compile("checksum"); 7 8 // Recompile the C only when the C source changes. 9 println!("cargo::rerun-if-changed=csrc/checksum.c"); 10 } ``` ```rust 1 // src/main.rs — call the C function through an FFI declaration 2 // In edition 2024, `extern` blocks MUST be marked `unsafe`. 3 unsafe extern "C" { 4 fn fletcher16(data: *const u8, len: usize) -> u16; 5 } 6 7 fn checksum(bytes: &[u8]) -> u16 { 8 // SAFETY: we pass a valid pointer + matching length from a live slice. 9 unsafe { fletcher16(bytes.as_ptr(), bytes.len()) } 10 } 11 12 fn main() { 13 let sum = checksum(b"abcde"); 14 println!("fletcher16(\"abcde\") = {sum:#06x}"); 15 } ``` Real output from `cargo run`: ```text 1 Compiling cc v1.2.63 2 Compiling native_math v0.1.0 (/private/tmp/.../native_math) 3 Finished `dev` profile [unoptimized + debuginfo] target(s) in 3.11s 4 Running `target/debug/native_math` 5 fletcher16("abcde") = 0xc8f0 ``` Under `cargo build -vv` (very verbose) you can see the directives `cc` emits on the build script’s behalf. These are the real lines from this build: ```text 1 [native_math 0.1.0] cargo:rustc-link-lib=static=checksum 2 [native_math 0.1.0] cargo:rustc-link-search=native=.../build/native_math-<hash>/out ``` If you are linking against a *pre-installed* system library rather than compiling your own C, you skip `cc` and print the directives yourself: ```rust 1 // build.rs — link against a system-installed library (e.g. libz) 2 fn main() { 3 // Tell the linker to link `libz` dynamically. 4 println!("cargo::rustc-link-lib=dylib=z"); 5 // Add a directory to the linker's search path if it is non-standard. 6 println!("cargo::rustc-link-search=native=/usr/local/lib"); 7 } ``` > **Note:** FFI, `unsafe`, and raw pointers are a large topic in their own right, covered in depth in section [20 — Unsafe & FFI](/20-unsafe-ffi/). The build-script side is just the link wiring; this page stays in that lane. *** ## The `cargo::rerun-if-*` Directives [Section titled “The cargo::rerun-if-\* Directives”](#the-cargorerun-if--directives) By default, **a build script re-runs whenever any file in the package changes**. That is rarely what you want — it makes builds slower and can re-run expensive code generation needlessly. The moment you print *any* `cargo::rerun-if-*` line, you switch off the default and take explicit control: Cargo re-runs the script only if one of the conditions you listed is met. | Directive | Re-run when… | TS/JS analogy | | --------------------------------- | ------------------------------------------------------ | ------------------------------------------ | | `cargo::rerun-if-changed=PATH` | the file or directory at `PATH` changes | a watched input in a `chokidar` glob | | `cargo::rerun-if-env-changed=VAR` | the value of env var `VAR` differs from the last build | reading `process.env.X` and reacting to it | ```rust 1 // build.rs — explicit, minimal re-run triggers 2 use std::env; 3 4 fn main() { 5 // Read configuration from the environment, with a default. 6 let api_base = env::var("API_BASE_URL") 7 .unwrap_or_else(|_| "https://api.example.com".to_string()); 8 9 // Expose it to the crate as a compile-time env var read with env!(). 10 println!("cargo::rustc-env=API_BASE_URL={api_base}"); 11 12 // Re-run if the env var changes between builds... 13 println!("cargo::rerun-if-env-changed=API_BASE_URL"); 14 // ...and if the build script itself changes. 15 println!("cargo::rerun-if-changed=build.rs"); 16 } ``` src/main.rs ```rust 1 fn main() { 2 println!("API base: {}", env!("API_BASE_URL")); 3 } ``` Real output across two builds: ```text 1 --- default --- 2 API base: https://api.example.com 3 --- overridden --- 4 API base: https://staging.internal ``` > **Warning:** Once you print **one** `rerun-if-changed`, the *blanket* “re-run on any file change” behavior is disabled. If your script reads three input files, you must list **all three** `rerun-if-changed` lines, or edits to the unlisted files will be silently ignored until something else triggers a rebuild. Two more directives round out the common set: * **`cargo::rustc-env=KEY=VALUE`** sets an env var that your crate reads with the `env!("KEY")` macro at compile time. This is the cleanest way to embed small values like a git hash or build timestamp without writing a file. * **`cargo::warning=MESSAGE`** surfaces a warning in the build output, useful for nudging users about missing optional tooling. ```rust 1 // build.rs — embed the git commit hash, no file generation needed 2 use std::process::Command; 3 4 fn main() { 5 let git_hash = Command::new("git") 6 .args(["rev-parse", "--short", "HEAD"]) 7 .output() 8 .ok() 9 .filter(|out| out.status.success()) 10 .map(|out| String::from_utf8_lossy(&out.stdout).trim().to_string()) 11 .unwrap_or_else(|| "unknown".to_string()); 12 13 println!("cargo::rustc-env=GIT_HASH={git_hash}"); 14 println!("cargo::rerun-if-changed=.git/HEAD"); // re-run when HEAD moves 15 } ``` src/main.rs ```rust 1 fn main() { 2 println!("version {} (commit {})", 3 env!("CARGO_PKG_VERSION"), // Cargo sets this one for you 4 env!("GIT_HASH")); // we set this one in build.rs 5 } ``` Real output: `version 0.1.0 (commit c530f7d)`. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | Node.js / TypeScript | Rust (`build.rs`) | | ------------------------- | -------------------------------------------------- | ------------------------------------------------------------ | | Where build logic lives | `scripts` in `package.json` + helper `.mjs` files | a single `build.rs` at the crate root (auto-detected) | | Language | JavaScript / shell | plain Rust, with `[build-dependencies]` | | When it runs | on the lifecycle event (`prebuild`, `postinstall`) | once before each crate build, *if* re-run conditions are met | | Incremental skipping | none built in (runs every time) | `cargo::rerun-if-*` lets Cargo skip it | | Output location | wherever your script writes (often into `src/`) | the Cargo-managed `OUT_DIR` under `target/` | | Native addons | `node-gyp` + `binding.gyp` (separate toolchain) | the `cc` crate (or your own link directives) | | Talking to the build tool | exit code / writing files | printing `cargo::...` lines to `stdout` | | Consuming generated code | `import` the emitted file | `include!(concat!(env!("OUT_DIR"), "/file.rs"))` | The deepest difference is **integration**. In Node, `prebuild` is a string of shell that npm runs blindly; it has no idea what your script reads or produces, so it cannot skip work. Cargo’s build script is a first-class citizen: it declares its inputs (`rerun-if-changed`), its outputs go to a directory Cargo owns and cleans, and its effect on the *real* compile (link flags, cfg flags, env vars) is communicated through a typed protocol. The build graph stays correct and incremental. > **Note:** The directive syntax changed from a single colon (`cargo:rustc-env=...`) to a double colon (`cargo::rustc-env=...`) when the new form stabilized in Rust 1.77. The single-colon form still works for backward compatibility, but **prefer the double colon** in new code, and use it consistently. This guide targets the repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) and the 2024 edition. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Writing generated files into `src/` [Section titled “Pitfall 1: Writing generated files into src/”](#pitfall-1-writing-generated-files-into-src) Coming from the Node `prebuild` habit of writing `src/status.generated.ts`, it is tempting to write generated Rust into your source tree. Don’t. Always write to `OUT_DIR`. Files in `src/` get committed, fight with formatting/linting, and break reproducible builds. Files in `OUT_DIR` live under `target/`, are gitignored by default, and are regenerated cleanly. ### Pitfall 2: Forgetting that one `rerun-if-changed` disables the blanket re-run [Section titled “Pitfall 2: Forgetting that one rerun-if-changed disables the blanket re-run”](#pitfall-2-forgetting-that-one-rerun-if-changed-disables-the-blanket-re-run) If your script reads `data/a.csv` and `data/b.csv` but only prints `cargo::rerun-if-changed=data/a.csv`, then editing `b.csv` will **not** trigger a rebuild. List every input, or point at the directory: `cargo::rerun-if-changed=data`. ### Pitfall 3: Mistyping a directive key [Section titled “Pitfall 3: Mistyping a directive key”](#pitfall-3-mistyping-a-directive-key) Cargo validates `cargo::` keys. A typo produces a hard error, not a silent no-op. This is the real message for an unknown key: build.rs ```rust 1 fn main() { 2 println!("cargo::rerun-if-changed=build.rs"); 3 println!("cargo::totally-made-up-key=oops"); // does not compile/build 4 } ``` ```text 1 error: invalid output in build script of `buildgen v0.1.0 (...)`: `cargo::totally-made-up-key=oops` 2 Unknown key: `totally-made-up-key`. 3 See https://doc.rust-lang.org/cargo/reference/build-scripts.html#outputs-of-the-build-script for more information about build script outputs. ``` ### Pitfall 4: Forgetting `unsafe` on `extern` blocks in edition 2024 [Section titled “Pitfall 4: Forgetting unsafe on extern blocks in edition 2024”](#pitfall-4-forgetting-unsafe-on-extern-blocks-in-edition-2024) In the 2024 edition, FFI declaration blocks must be marked `unsafe extern "C"`. Writing a plain `extern "C"` block is a compile error. This is the real `rustc` message: ```rust 1 // does not compile in edition 2024 — needs `unsafe extern "C"` 2 extern "C" { 3 fn fletcher16(data: *const u8, len: usize) -> u16; 4 } ``` ```text 1 error: extern blocks must be unsafe 2 --> src/main.rs:1:1 3 | 4 1 | / extern "C" { 5 2 | | fn fletcher16(data: *const u8, len: usize) -> u16; 6 3 | | } 7 | |_^ ``` The fix is to write `unsafe extern "C" { ... }`. Note that *declaring* the block `unsafe` is separate from the `unsafe { ... }` block you still need at each *call* site. ### Pitfall 5: Expecting `build.rs` to run at program runtime [Section titled “Pitfall 5: Expecting build.rs to run at program runtime”](#pitfall-5-expecting-buildrs-to-run-at-program-runtime) A build script runs at compile time on the build machine. It cannot read your end user’s environment, cannot make runtime network calls for your app, and its `println!` output is build-log noise, not your program’s output. If you need runtime behavior, that belongs in `src/`, not `build.rs`. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Reach for a crate before hand-rolling.** Use `cc` for C/C++, `bindgen` for generating Rust FFI bindings from C headers, `pkg-config` for discovering system libraries, and `prost-build`/`tonic-build` for Protocol Buffers. They emit the correct directives for you and handle cross-platform quirks. * **Always write to `OUT_DIR`.** Never generate into `src/`. * **Be specific about re-runs.** List exactly the files and env vars your script depends on with `cargo::rerun-if-changed` / `cargo::rerun-if-env-changed`. This keeps incremental builds fast and correct. * **Prefer `cargo::rustc-env` over file generation for scalar values.** A git hash or build timestamp does not need a generated `.rs` file; one `rustc-env` line plus `env!()` is cleaner. * **Keep build scripts cheap and deterministic.** They run on every fresh build and on CI. Avoid slow network calls; if you must fetch, cache into `OUT_DIR` and guard with re-run directives. * **Add only build-time crates to `[build-dependencies]`.** They are compiled for the host and excluded from your final binary; keep your runtime dependency tree lean. * **Emit a friendly `cargo::warning`** when an optional native dependency is missing, so users get a clear message instead of a cryptic linker error. > **Tip:** Reserve build scripts for things that genuinely must happen at build time. If a problem can be solved with a regular function, a `const`, a [feature flag](/12-modules-packages/09-feature-flags/), or a procedural macro (see [14 — Macros](/14-macros/)), prefer that — build scripts add a compile step and a maintenance surface. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A common production need: turn a checked-in data file into a fast, allocation-free, compile-time lookup table. Here we generate a `match`-based function from a CSV of color names: no runtime parsing, no `HashMap` allocation, and a hard compile error if the data file is malformed. Cargo.toml ```toml 1 [package] 2 name = "color_codes" 3 version = "0.1.0" 4 edition = "2024" 5 # No [build-dependencies] needed — std is enough for CSV this simple. ``` ```text 1 # colors.csv (checked into the repo) 2 red,#ff0000 3 green,#00ff00 4 blue,#0000ff 5 slate,#708090 ``` build.rs ```rust 1 use std::env; 2 use std::fmt::Write as _; 3 use std::fs; 4 use std::path::Path; 5 6 fn main() { 7 let out_dir = env::var("OUT_DIR").unwrap(); 8 let dest = Path::new(&out_dir).join("colors.rs"); 9 10 let csv = fs::read_to_string("colors.csv").expect("colors.csv must exist"); 11 12 // Generate a `match`-based lookup function from the rows. 13 let mut code = String::from( 14 "/// Look up a hex code for a named color (generated from colors.csv).\n\ 15 pub fn hex_for(name: &str) -> Option<&'static str> {\n match name {\n", 16 ); 17 for line in csv.lines().filter(|l| !l.trim().is_empty()) { 18 let (name, hex) = line.split_once(',').expect("each row is name,hex"); 19 writeln!( 20 code, 21 " {name:?} => Some({hex:?}),", 22 name = name.trim(), 23 hex = hex.trim() 24 ) 25 .unwrap(); 26 } 27 code.push_str(" _ => None,\n }\n}\n"); 28 fs::write(&dest, code).unwrap(); 29 30 // Regenerate only when the data or the generator changes. 31 println!("cargo::rerun-if-changed=colors.csv"); 32 println!("cargo::rerun-if-changed=build.rs"); 33 } ``` src/main.rs ```rust 1 include!(concat!(env!("OUT_DIR"), "/colors.rs")); 2 3 fn main() { 4 for name in ["slate", "blue", "chartreuse"] { 5 match hex_for(name) { 6 Some(hex) => println!("{name:>10} -> {hex}"), 7 None => println!("{name:>10} -> (unknown)"), 8 } 9 } 10 } ``` Real output from `cargo run`: ```text 1 Compiling color_codes v0.1.0 (/private/tmp/.../color_codes) 2 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.69s 3 Running `target/debug/color_codes` 4 slate -> #708090 5 blue -> #0000ff 6 chartreuse -> (unknown) ``` The payoff over a runtime approach: the lookup compiles to a jump table, there is zero startup cost, and a malformed `colors.csv` fails the *build* (via the `expect` panics in `build.rs`) rather than crashing at runtime. Edit `colors.csv` and `cargo build` regenerates and recompiles automatically; edit an unrelated file and the script is skipped. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [The Cargo Book — Build Scripts](https://doc.rust-lang.org/cargo/reference/build-scripts.html): the authoritative reference for `build.rs` and every `cargo::` directive. * [The Cargo Book — Build Script Examples](https://doc.rust-lang.org/cargo/reference/build-script-examples.html): code generation, linking, and conditional compilation recipes. * [`cc` crate docs](https://docs.rs/cc): compiling C/C++ from a build script. * [`bindgen` User Guide](https://rust-lang.github.io/rust-bindgen/): generating Rust FFI bindings from C headers in `build.rs`. * Related pages in this section: * [Cargo.toml: The Manifest](/12-modules-packages/04-cargo/): where `[build-dependencies]` and `build = "..."` are declared. * [Dev & Build Dependencies](/12-modules-packages/07-dev-dependencies/): how `[build-dependencies]` differs from `[dependencies]` and `[dev-dependencies]`. * [Dependencies](/12-modules-packages/06-dependencies/): adding crates like `cc` and `serde_json` with `cargo add`. * [Feature Flags & Conditional Compilation](/12-modules-packages/09-feature-flags/): `#[cfg(...)]` and an often-better alternative to build-script logic. * [Cargo Commands](/12-modules-packages/05-cargo-commands/): `cargo build -vv` to inspect build-script output. * Cross-section links: * [01 — Getting Started](/01-getting-started/) and [Understanding Cargo](/01-getting-started/03-cargo-basics/) for Cargo fundamentals. * [02 — Basics](/02-basics/) for the `println!`/`format!` macros used to emit generated code. * [20 — Unsafe & FFI](/20-unsafe-ffi/) for the `unsafe extern "C"` and raw-pointer details behind native linking. * [13 — Testing](/13-testing/) for testing the code your build script generates. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Embed a build timestamp [Section titled “Exercise 1: Embed a build timestamp”](#exercise-1-embed-a-build-timestamp) **Difficulty:** Easy **Objective:** Use a build script to bake the build’s Unix timestamp into the binary, with no generated file. **Instructions:** 1. Create a binary crate. 2. In `build.rs`, compute the current time as seconds since the Unix epoch. 3. Expose it to the crate via `cargo::rustc-env=BUILD_UNIX_TIME=...`. 4. In `main`, print it using the `env!` macro. Solution build.rs ```rust 1 use std::time::{SystemTime, UNIX_EPOCH}; 2 3 fn main() { 4 let secs = SystemTime::now() 5 .duration_since(UNIX_EPOCH) 6 .unwrap() 7 .as_secs(); 8 println!("cargo::rustc-env=BUILD_UNIX_TIME={secs}"); 9 println!("cargo::rerun-if-changed=build.rs"); 10 } ``` src/main.rs ```rust 1 fn main() { 2 println!("built at unix time {}", env!("BUILD_UNIX_TIME")); 3 } ``` Real output: `built at unix time 1780203193`. ### Exercise 2: Configurable API base URL with re-run control [Section titled “Exercise 2: Configurable API base URL with re-run control”](#exercise-2-configurable-api-base-url-with-re-run-control) **Difficulty:** Medium **Objective:** Read an environment variable in `build.rs`, fall back to a default, and make Cargo re-run the script when that variable changes. **Instructions:** 1. In `build.rs`, read `API_BASE_URL` from the environment, defaulting to `https://api.example.com`. 2. Expose it via `cargo::rustc-env`. 3. Print `cargo::rerun-if-env-changed=API_BASE_URL` so changing it triggers a rebuild. 4. Verify that `cargo run` uses the default and `API_BASE_URL=... cargo run` uses the override. Solution build.rs ```rust 1 use std::env; 2 3 fn main() { 4 let api_base = env::var("API_BASE_URL") 5 .unwrap_or_else(|_| "https://api.example.com".to_string()); 6 println!("cargo::rustc-env=API_BASE_URL={api_base}"); 7 println!("cargo::rerun-if-env-changed=API_BASE_URL"); 8 println!("cargo::rerun-if-changed=build.rs"); 9 } ``` src/main.rs ```rust 1 fn main() { 2 println!("API base: {}", env!("API_BASE_URL")); 3 } ``` Real output: ```text 1 --- default --- 2 API base: https://api.example.com 3 --- overridden --- 4 API base: https://staging.internal ``` ### Exercise 3: Generate a lookup table from a JSON data file [Section titled “Exercise 3: Generate a lookup table from a JSON data file”](#exercise-3-generate-a-lookup-table-from-a-json-data-file) **Difficulty:** Hard **Objective:** Use a `[build-dependencies]` crate (`serde_json`) to parse a JSON file and generate a `match`-based lookup function written into `OUT_DIR`. **Instructions:** 1. Add `serde_json` to `[build-dependencies]` with `cargo add --build serde_json`. 2. Create `status_codes.json` mapping HTTP codes (as string keys) to reason phrases. 3. In `build.rs`, parse it into a `BTreeMap<u16, String>`, generate `fn reason_phrase(code: u16) -> Option<&'static str>`, and write it to `OUT_DIR/status.rs`. 4. `include!` the generated file and look up a few codes (including one not in the file). 5. Add `cargo::rerun-if-changed` for both the JSON and `build.rs`. Solution Cargo.toml ```toml 1 [build-dependencies] 2 serde_json = "1" ``` build.rs ```rust 1 use std::collections::BTreeMap; 2 use std::env; 3 use std::fmt::Write as _; 4 use std::fs; 5 use std::path::Path; 6 7 fn main() { 8 let out_dir = env::var("OUT_DIR").unwrap(); 9 let dest = Path::new(&out_dir).join("status.rs"); 10 11 let raw = fs::read_to_string("status_codes.json").expect("status_codes.json"); 12 let map: BTreeMap<u16, String> = 13 serde_json::from_str(&raw).expect("valid JSON object of code->reason"); 14 15 let mut code = String::from( 16 "pub fn reason_phrase(code: u16) -> Option<&'static str> {\n match code {\n", 17 ); 18 for (status, reason) in &map { 19 writeln!(code, " {status} => Some({reason:?}),").unwrap(); 20 } 21 code.push_str(" _ => None,\n }\n}\n"); 22 fs::write(&dest, code).unwrap(); 23 24 println!("cargo::rerun-if-changed=status_codes.json"); 25 println!("cargo::rerun-if-changed=build.rs"); 26 } ``` status\_codes.json ```json 1 { "200": "OK", "404": "Not Found", "500": "Internal Server Error" } ``` src/main.rs ```rust 1 include!(concat!(env!("OUT_DIR"), "/status.rs")); 2 3 fn main() { 4 for code in [200u16, 404, 418] { 5 println!("{code} => {:?}", reason_phrase(code)); 6 } 7 } ``` Real output: ```text 1 200 => Some("OK") 2 404 => Some("Not Found") 3 418 => None ``` # Publishing to crates.io > Publish a Rust crate to crates.io like npm publish, but permanent: cargo publish, required metadata, enforced SemVer, and cargo yank instead of unpublish. Once your crate is useful to more than just you, you publish it to **crates.io** — Rust’s central registry, the equivalent of the public npm registry. This page covers the full publishing workflow: preparing manifest metadata, the `cargo publish` command, SemVer-based versioning, and what to do when a release goes wrong (`cargo yank`). *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Publishing a Rust crate is conceptually the same as running `npm publish`: you push a versioned, immutable artifact to a shared registry that everyone can depend on. The mechanics differ in ways that matter to a TypeScript/JavaScript developer: crates.io publishes are **permanent and append-only** (you can never `unpublish` and reuse a version the way `npm unpublish` allows within 72 hours), versions must follow **strict Semantic Versioning** that Cargo enforces in resolution, and a rich set of `[package]` metadata fields is expected before the registry will accept your crate. This page focuses on the publish workflow itself; the [manifest](/12-modules-packages/04-cargo/), [dependency specs](/12-modules-packages/06-dependencies/), and [workspaces](/12-modules-packages/08-workspaces/) are covered in sibling files. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Publishing a small library to the npm registry. You authenticate once, bump the version, and run `npm publish`: ```jsonc 1 // package.json — the metadata npm uses for the registry listing 2 { 3 "name": "@ada/slugify", 4 "version": "0.1.0", 5 "description": "Convert arbitrary text into clean, URL-safe slugs", 6 "license": "MIT", 7 "author": "Ada Zeybek <me@zeybek.dev>", 8 "homepage": "https://github.com/ada/slugify#readme", 9 "repository": { "type": "git", "url": "https://github.com/ada/slugify.git" }, 10 "keywords": ["slug", "url", "text", "string"], 11 "main": "dist/index.js", 12 "types": "dist/index.d.ts", 13 "files": ["dist"], // allow-list of what gets shipped in the tarball 14 "publishConfig": { "access": "public" } 15 } ``` ```bash 1 npm login # authenticate (writes a token to ~/.npmrc) 2 npm version patch # 0.1.0 -> 0.1.1, also creates a git tag 3 npm publish --access public # upload the tarball to the registry ``` npm lets you *undo* a recent mistake: within 72 hours you can `npm unpublish @ada/slugify@0.1.1` and then re-publish that same version. npm also lets you `npm deprecate` a version to warn installers without removing it. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same library as a crate published to crates.io. Metadata lives in `Cargo.toml`, and the workflow is `login` -> bump version -> `publish`: Cargo.toml ```toml 1 [package] 2 name = "slugify-rs" 3 version = "0.1.0" 4 edition = "2024" 5 rust-version = "1.85" 6 description = "Convert arbitrary text into clean, URL-safe slugs" 7 license = "MIT OR Apache-2.0" 8 repository = "https://github.com/ada/slugify-rs" 9 homepage = "https://github.com/ada/slugify-rs" 10 documentation = "https://docs.rs/slugify-rs" 11 readme = "README.md" 12 keywords = ["slug", "url", "text", "string", "web"] 13 categories = ["text-processing", "web-programming"] 14 exclude = ["/.github", "/benches", "*.png"] 15 16 [dependencies] ``` src/lib.rs ````rust 1 //! Convert arbitrary text into clean, URL-safe slugs. 2 3 /// Turn an arbitrary string into a lowercase, hyphen-separated slug. 4 /// 5 /// ``` 6 /// assert_eq!(slugify_rs::slugify("Hello, World!"), "hello-world"); 7 /// ``` 8 pub fn slugify(input: &str) -> String { 9 let mut out = String::with_capacity(input.len()); 10 let mut prev_dash = false; 11 for ch in input.chars() { 12 if ch.is_ascii_alphanumeric() { 13 out.extend(ch.to_lowercase()); 14 prev_dash = false; 15 } else if !prev_dash && !out.is_empty() { 16 out.push('-'); 17 prev_dash = true; 18 } 19 } 20 out.trim_end_matches('-').to_string() 21 } ```` ```bash 1 cargo login # authenticate (paste a token from crates.io/me) 2 cargo publish --dry-run # rehearse: package + build, but do NOT upload 3 cargo publish # upload the .crate tarball to crates.io ``` > **Warning:** Unlike `npm unpublish`, there is **no** way to remove `slugify-rs 0.1.0` and re-upload different bytes under that same version. crates.io publishes are permanent. The closest tool is `cargo yank` (below), which only hides a version from *new* dependency resolution; it does not delete anything. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Authenticating with `cargo login` [Section titled “Authenticating with cargo login”](#authenticating-with-cargo-login) Before your first publish, create an account at [crates.io](https://crates.io) (sign in with GitHub), then generate an API token under **Account Settings → API Tokens**. Run: ```bash 1 cargo login ``` Cargo prompts you to paste the token and stores it in `~/.cargo/credentials.toml`. This is the analogue of `npm login` writing an auth token to `~/.npmrc`. Modern tokens are **scoped**: when you create one on crates.io you choose which crates and which actions (publish-new, publish-update, yank) it may perform, much like a fine-grained npm automation token. > **Tip:** For CI, do not run interactive `cargo login`. Pass the token directly: `cargo publish --token "$CRATES_IO_TOKEN"`, with the token stored as a CI secret. ### Required metadata [Section titled “Required metadata”](#required-metadata) crates.io refuses to accept a crate that has no `description` and no `license` (or `license-file`). The `cargo publish --dry-run` step warns you about missing fields. Here is the **real** warning for a freshly-generated crate with no metadata: ```text 1 warning: manifest has no description, license, license-file, documentation, homepage or repository. 2 See https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata for more info. ``` The fields that matter, and their npm `package.json` cousins: | `Cargo.toml` field | npm `package.json` field | Purpose | | --------------------- | ------------------------ | ------------------------------------------------------------------ | | `name` | `name` | Globally unique on the registry; reserved on first publish | | `version` | `version` | SemVer triple; each value is published once, forever | | `description` | `description` | **Required** by crates.io; one-line summary | | `license` | `license` | **Required** (or `license-file`); SPDX expression | | `repository` | `repository.url` | Source link shown on the crate page | | `homepage` | `homepage` | Project landing page | | `documentation` | (no direct equiv) | Usually `https://docs.rs/<crate>` | | `readme` | (implicit `README.md`) | Rendered on the crate page | | `keywords` | `keywords` | Up to 5; max 20 chars each | | `categories` | (no equiv) | Must match the [fixed slug list](https://crates.io/category_slugs) | | `exclude` / `include` | `files` | Controls what goes in the tarball | > **Note:** `license = "MIT OR Apache-2.0"` is the de-facto standard for the Rust ecosystem. Dual-licensing under MIT and Apache-2.0 is what the standard library and most popular crates use. It is a single SPDX expression, not two separate fields. ### What gets uploaded: `cargo package` [Section titled “What gets uploaded: cargo package”](#what-gets-uploaded-cargo-package) `cargo publish` first runs the equivalent of `cargo package`: it collects your source into a `.crate` tarball, then **builds that tarball from scratch in an isolated directory** to verify it compiles standalone. This catches files you forgot to include. You can inspect the file list without uploading: ```bash 1 cargo package --list ``` By default Cargo includes everything tracked by git, minus your `.gitignore`d files, and always injects a normalized `Cargo.toml` plus the `Cargo.lock`. Use `exclude` to drop large fixtures, screenshots, or benchmark data the consumer does not need (as in the example’s `exclude = ["/.github", "/benches", "*.png"]`), or `include` for an explicit allow-list (the analogue of npm’s `files`). ### The `--dry-run` rehearsal [Section titled “The --dry-run rehearsal”](#the---dry-run-rehearsal) Always run `cargo publish --dry-run` first. It performs every step except the final upload. Here is the **real** tail of a successful dry run for the `slugify-rs` example: ```text 1 Packaging slugify-rs v0.1.0 (/tmp/.../slugify-rs) 2 Packaged 7 files, 2.7KiB (1.5KiB compressed) 3 Verifying slugify-rs v0.1.0 (/tmp/.../slugify-rs) 4 Compiling slugify-rs v0.1.0 (/tmp/.../slugify-rs/target/package/slugify-rs-0.1.0) 5 Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.00s 6 Uploading slugify-rs v0.1.0 (/tmp/.../slugify-rs) 7 warning: aborting upload due to dry run ``` The `warning: aborting upload due to dry run` line confirms nothing was sent. Drop `--dry-run` to actually publish. ### After publishing [Section titled “After publishing”](#after-publishing) Within minutes, your crate appears at `https://crates.io/crates/slugify-rs`, and [docs.rs](https://docs.rs) automatically builds and hosts your API documentation at `https://docs.rs/slugify-rs`. There is no separate “publish the docs” step, which is a pleasant contrast to wiring up TypeDoc and a hosting provider yourself. *** ## Key Differences [Section titled “Key Differences”](#key-differences) ### Versioning is SemVer, and Cargo enforces it [Section titled “Versioning is SemVer, and Cargo enforces it”](#versioning-is-semver-and-cargo-enforces-it) In npm, SemVer is a convention that the registry mostly trusts you to follow. In Rust, SemVer is woven into **dependency resolution**: a caret requirement like `serde = "1.0"` means “any `1.x` ≥ `1.0.0`”, and the compiler/registry expectation is that a minor or patch bump never breaks downstream code. Choosing the right bump is therefore a contract: ```rust 1 use semver::Version; 2 3 /// Demonstrate which part of MAJOR.MINOR.PATCH to bump. 4 pub fn classify(old: &str, new: &str) -> &'static str { 5 let o = Version::parse(old).unwrap(); 6 let n = Version::parse(new).unwrap(); 7 if n.major > o.major { 8 "breaking change -> bump MAJOR" 9 } else if n.minor > o.minor { 10 "new backward-compatible feature -> bump MINOR" 11 } else if n.patch > o.patch { 12 "backward-compatible bug fix -> bump PATCH" 13 } else { 14 "no change" 15 } 16 } ``` The accompanying tests (using the `semver` crate, the same SemVer engine Cargo uses internally) pass: ```text 1 running 1 test 2 test tests::bumps ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` | Change you made | Version bump | Why | | -------------------------------------------------- | ------------------------- | ----------------------------- | | Fixed a bug, no API change | PATCH (`1.4.2` → `1.4.3`) | Existing callers keep working | | Added a public function/type | MINOR (`1.4.2` → `1.5.0`) | Additive, backward-compatible | | Removed/renamed a public item, changed a signature | MAJOR (`1.4.2` → `2.0.0`) | Breaks existing callers | > **Note:** For `0.x` crates the rules shift left: under SemVer, `0.y.z` treats the **`y`** as the breaking-change component. Cargo follows this, so `0.1` and `0.2` are considered *incompatible*, and `version = "0.1"` resolves to `>=0.1.0, <0.2.0`. This is why pre-`1.0` crates can break you on a “minor” bump. The pre-release ordering also follows SemVer precisely: `1.0.0-alpha.1 < 1.0.0`. Verified with the `semver` crate: ```text 1 major=1 minor=4 patch=2 2 1.4.2 matches ^1.2: true 3 2.0.0 matches ^1.2: false 4 1.0.0-alpha.1 < 1.0.0: true ``` ### Immutability: published versions are forever [Section titled “Immutability: published versions are forever”](#immutability-published-versions-are-forever) | Scenario | npm | crates.io | | ----------------------------------------- | --------------------------------------- | ----------------------------------------------- | | Reuse a version number | `unpublish` within 72h, then re-publish | **Never** — the version is burned permanently | | Remove a broken version from new installs | `unpublish` (with limits) | `cargo yank` (hides, does not delete) | | Warn users off a version | `npm deprecate` | `cargo yank` + a note in the changelog/README | | Fully delete a package | possible within limits | only crates.io admins, for legal/policy reasons | The mental model shift: **treat every `cargo publish` as irreversible.** The `--dry-run` step exists precisely because there is no undo. ### Names are claimed on first publish [Section titled “Names are claimed on first publish”](#names-are-claimed-on-first-publish) The first person to publish `foo` owns `foo`. crates.io has a single flat namespace with **no scopes**: there is no `@ada/slugify` equivalent. This is why crate names often carry suffixes like `-rs` or `-rust` to disambiguate. Names are normalized so that `slugify_rs` and `slugify-rs` are considered the same and cannot both be claimed. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Publishing a crate that depends on a `path` dependency [Section titled “Pitfall 1: Publishing a crate that depends on a path dependency”](#pitfall-1-publishing-a-crate-that-depends-on-a-path-dependency) A very common mistake when extracting a crate from a workspace: you depend on a sibling crate by `path`, but that sibling is not on crates.io. crates.io rejects path-only dependencies because consumers downloading from the registry cannot see your local filesystem. ```toml 1 # Cargo.toml — app_crate depends on an unpublished sibling 2 [dependencies] 3 util_lib = { version = "0.1.0", path = "../util_lib" } ``` Running `cargo publish` on `app_crate` produces this **real** error (`util_lib` is not on crates.io): ```text 1 Packaging app_crate v0.1.0 (/tmp/.../app_crate) 2 Updating crates.io index 3 error: failed to prepare local package for uploading 4 5 Caused by: 6 no matching package named `util_lib` found 7 location searched: crates.io index 8 required by package `app_crate v0.1.0 (/tmp/.../app_crate)` ``` > **Tip:** During the publish, Cargo uses the `version` field of a `{ version = "...", path = "..." }` dependency and **ignores** the `path` (path is for local development only). So the fix is to **publish `util_lib` first**, then publish `app_crate`. Publish workspace members in dependency order, bottom-up. ### Pitfall 2: Missing `description` or `license` [Section titled “Pitfall 2: Missing description or license”](#pitfall-2-missing-description-or-license) If you skip the metadata, the dry run only *warns*, but the real crates.io upload **rejects** the crate. Add at minimum: ```toml 1 [package] 2 description = "One concise sentence about what this crate does" 3 license = "MIT OR Apache-2.0" ``` ### Pitfall 3: Assuming you can unpublish like npm [Section titled “Pitfall 3: Assuming you can unpublish like npm”](#pitfall-3-assuming-you-can-unpublish-like-npm) There is no `cargo unpublish`. If you ship a broken `1.2.0`, you cannot replace its bytes — you must publish a fixed `1.2.1` and `cargo yank` the broken `1.2.0`. Plan releases accordingly, and lean on `--dry-run` plus a tag-based CI release flow. ### Pitfall 4: Forgetting that `version` is the source of truth [Section titled “Pitfall 4: Forgetting that version is the source of truth”](#pitfall-4-forgetting-that-version-is-the-source-of-truth) Cargo does not auto-increment for you the way `npm version patch` does (which also creates a git tag). You must edit the `version` field in `Cargo.toml` yourself (or use a helper like `cargo release` / `cargo-edit`’s `cargo set-version`). Trying to `cargo publish` a `version` that already exists on the registry fails: the registry rejects duplicates. ### Pitfall 5: Treating a minor bump as “safe” for `0.x` crates [Section titled “Pitfall 5: Treating a minor bump as “safe” for 0.x crates”](#pitfall-5-treating-a-minor-bump-as-safe-for-0x-crates) As noted above, `0.1.x` → `0.2.0` is a **breaking** change under SemVer. If you are still pre-`1.0`, communicate breaking changes by bumping the second number, and do not be surprised when downstream `version = "0.1"` requirements do *not* pick up your `0.2`. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Rehearse with `cargo publish --dry-run`** every time. It packages and compiles the tarball in isolation, catching missing files and standalone-build failures before they become permanent. * **Inspect the tarball** with `cargo package --list` to confirm you are not shipping secrets, fixtures, or multi-megabyte test data. Use `exclude`/`include` to trim it. * **Fill in `repository`, `documentation`, `keywords`, and `categories`.** They power discovery on crates.io and make your crate page look professional. `documentation = "https://docs.rs/<crate>"` is conventional even though docs.rs builds automatically. * **Add `rust-version`** (the Minimum Supported Rust Version, MSRV). Cargo errors early if a consumer’s toolchain is too old, which is friendlier than a cryptic build failure deep in compilation. * **Keep a `CHANGELOG.md`** and tag each release in git (`git tag v0.1.0`). crates.io itself does not store release notes, so the changelog is your record. * **Automate releases in CI.** A common pattern: a workflow that triggers on a `v*` git tag, runs `cargo publish --token "$CRATES_IO_TOKEN"`. Trusted Publishing (OIDC, no long-lived token) is also supported by crates.io for GitHub Actions. * **Dual-license `MIT OR Apache-2.0`** unless you have a specific reason not to — it matches ecosystem norms and maximizes who can depend on you. * **Yank, do not panic.** If a release is broken, publish a fix and yank the bad one. Do not assume there is any way to delete it. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A realistic release procedure for a small library crate, end to end. Assume the working tree is clean and committed. Cargo.toml ```toml 1 [package] 2 name = "slugify-rs" 3 version = "0.2.0" # bumped from 0.1.x: we added a public `Options` API (MINOR) 4 edition = "2024" 5 rust-version = "1.85" 6 description = "Convert arbitrary text into clean, URL-safe slugs" 7 license = "MIT OR Apache-2.0" 8 repository = "https://github.com/ada/slugify-rs" 9 documentation = "https://docs.rs/slugify-rs" 10 readme = "README.md" 11 keywords = ["slug", "url", "text", "string", "web"] 12 categories = ["text-processing", "web-programming"] 13 exclude = ["/.github", "/benches", "*.png"] 14 15 [dependencies] ``` src/lib.rs ````rust 1 //! Convert arbitrary text into clean, URL-safe slugs. 2 3 /// Configuration for slug generation. 4 #[derive(Debug, Clone, Copy)] 5 pub struct Options { 6 /// The character inserted between words. 7 pub separator: char, 8 /// Cap the slug length (in characters); `None` means no limit. 9 pub max_len: Option<usize>, 10 } 11 12 impl Default for Options { 13 fn default() -> Self { 14 Options { separator: '-', max_len: None } 15 } 16 } 17 18 /// Slugify with default options (`-` separator, no length cap). 19 /// 20 /// ``` 21 /// assert_eq!(slugify_rs::slugify("Hello, World!"), "hello-world"); 22 /// ``` 23 pub fn slugify(input: &str) -> String { 24 slugify_with(input, Options::default()) 25 } 26 27 /// Slugify with explicit [`Options`]. 28 /// 29 /// ``` 30 /// use slugify_rs::{slugify_with, Options}; 31 /// let opts = Options { separator: '_', max_len: Some(7) }; 32 /// assert_eq!(slugify_with("Hello, World!", opts), "hello_w"); 33 /// ``` 34 pub fn slugify_with(input: &str, opts: Options) -> String { 35 let mut out = String::with_capacity(input.len()); 36 let mut prev_sep = false; 37 for ch in input.chars() { 38 if let Some(max) = opts.max_len { 39 if out.chars().count() >= max { 40 break; 41 } 42 } 43 if ch.is_ascii_alphanumeric() { 44 out.extend(ch.to_lowercase()); 45 prev_sep = false; 46 } else if !prev_sep && !out.is_empty() { 47 out.push(opts.separator); 48 prev_sep = true; 49 } 50 } 51 out.trim_end_matches(opts.separator).to_string() 52 } ```` The release run, with **real** doctest output verifying both examples compile and pass: ```text 1 running 2 tests 2 test src/lib.rs - slugify (line 21) ... ok 3 test src/lib.rs - slugify_with (line 30) ... ok 4 5 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s ``` ```bash 1 # 1. Verify everything (tests + doctests + lints) 2 cargo test 3 cargo clippy -- -D warnings 4 5 # 2. Rehearse the package and standalone build 6 cargo publish --dry-run 7 8 # 3. Tag the release in git so the changelog and registry stay in sync 9 git tag v0.2.0 10 git push origin v0.2.0 11 12 # 4. Publish for real 13 cargo publish ``` If a consumer later reports that `0.2.0` panics on certain Unicode input, the recovery flow is: ```bash 1 # Ship the fix as a new PATCH version... 2 # (edit Cargo.toml: version = "0.2.1", then) 3 cargo publish 4 5 # ...and discourage new installs of the broken version. 6 cargo yank --version 0.2.0 ``` `cargo yank --version 0.2.0` removes `0.2.0` from the index for **new** resolution, while existing `Cargo.lock` files that already pin `0.2.0` keep building (so you do not break people mid-deploy). If it turns out the yank was a mistake, undo it: ```bash 1 cargo yank --version 0.2.0 --undo ``` > **Note:** Yanking is not deletion. The `0.2.0` `.crate` tarball stays downloadable so existing lockfiles still resolve; it just stops being chosen for *new* requirements unless a lockfile explicitly pins it. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [The Cargo Book — Publishing on crates.io](https://doc.rust-lang.org/cargo/reference/publishing.html): the authoritative workflow reference. * [The Cargo Book — The Manifest Format](https://doc.rust-lang.org/cargo/reference/manifest.html): every `[package]` metadata field. * [`cargo yank` reference](https://doc.rust-lang.org/cargo/commands/cargo-yank.html): yanking and un-yanking. * [SemVer Compatibility chapter](https://doc.rust-lang.org/cargo/reference/semver.html): exactly which changes are breaking vs. compatible in Rust. * [crates.io category slugs](https://crates.io/category_slugs): the fixed list valid for `categories`. * [docs.rs about page](https://docs.rs/about): how automatic documentation hosting works. * Sibling pages in this section: [Cargo.toml manifest](/12-modules-packages/04-cargo/), [dependencies](/12-modules-packages/06-dependencies/), [workspaces](/12-modules-packages/08-workspaces/), [feature flags](/12-modules-packages/09-feature-flags/), [cargo commands](/12-modules-packages/05-cargo-commands/). * Related guide sections: [01 — Getting Started](/01-getting-started/) for installing the toolchain, [02 — Basics](/02-basics/), and [13 — Testing](/13-testing/) for the `cargo test` step in your release checklist. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Make a minimal crate publishable [Section titled “Exercise 1: Make a minimal crate publishable”](#exercise-1-make-a-minimal-crate-publishable) **Difficulty:** Easy **Objective:** Take a default `cargo new --lib` crate and add exactly the metadata crates.io requires, then confirm with a dry run. **Instructions:** Create a library crate, add the smallest set of fields that removes the “manifest has no description, license…” warning, and run `cargo publish --dry-run` (use `--allow-dirty` if you have not committed). List which two fields are strictly required. Solution The two strictly-required fields are `description` and `license` (or `license-file`). Cargo.toml ```toml 1 [package] 2 name = "tinytool" 3 version = "0.1.0" 4 edition = "2024" 5 description = "A tiny demonstration crate" 6 license = "MIT OR Apache-2.0" 7 8 [dependencies] ``` ```bash 1 cargo publish --dry-run --allow-dirty ``` With both fields present, the metadata warning disappears and the dry run ends with the real line `warning: aborting upload due to dry run`, confirming the crate is ready to publish. (Adding `repository`, `keywords`, and `categories` is recommended but not required.) ### Exercise 2: Pick the right version bump [Section titled “Exercise 2: Pick the right version bump”](#exercise-2-pick-the-right-version-bump) **Difficulty:** Medium **Objective:** Apply SemVer rules to a sequence of API changes. **Instructions:** Your crate is at `1.4.2`. For each change below, give the next version: (a) you fixed a typo in a doc comment; (b) you added a new public function `parse_strict`; (c) you removed the deprecated public function `parse_loose`. Then explain what version a downstream `version = "1.4"` requirement would resolve to after each release. Solution You can verify the classification mechanically with the same `semver` engine Cargo uses: ```rust 1 use semver::Version; 2 3 fn classify(old: &str, new: &str) -> &'static str { 4 let o = Version::parse(old).unwrap(); 5 let n = Version::parse(new).unwrap(); 6 if n.major > o.major { 7 "MAJOR (breaking)" 8 } else if n.minor > o.minor { 9 "MINOR (additive)" 10 } else if n.patch > o.patch { 11 "PATCH (fix)" 12 } else { 13 "no change" 14 } 15 } 16 17 fn main() { 18 println!("(a) {}", classify("1.4.2", "1.4.3")); // doc-only fix 19 println!("(b) {}", classify("1.4.2", "1.5.0")); // new public fn 20 println!("(c) {}", classify("1.4.2", "2.0.0")); // removed public fn 21 } ``` Real output: ```text 1 (a) PATCH (fix) 2 (b) MINOR (additive) 3 (c) MAJOR (breaking) ``` * **(a)** `1.4.3` — a doc-only change is backward compatible: PATCH. * **(b)** `1.5.0` — adding a public item is backward compatible: MINOR. * **(c)** `2.0.0` — removing a public item breaks callers: MAJOR. A downstream `version = "1.4"` requirement (which means `>=1.4.0, <2.0.0`) would automatically pick up `1.4.3` and `1.5.0`. That is the whole point of compatible bumps. It would **not** pick up `2.0.0`; the consumer must opt in by changing their requirement to `"2"`. ### Exercise 3: Recover from a bad release [Section titled “Exercise 3: Recover from a bad release”](#exercise-3-recover-from-a-bad-release) **Difficulty:** Hard **Objective:** Walk through the correct recovery procedure when a published version is broken, and explain precisely what `cargo yank` does and does not do. **Instructions:** You published `data-parser 0.3.0`, and it panics on empty input. A teammate suggests “just unpublish 0.3.0 and re-publish a fixed 0.3.0.” Explain why that is impossible on crates.io, give the exact commands you would run instead, and describe what happens to (1) a brand-new project that runs `cargo add data-parser` and (2) an existing project whose `Cargo.lock` already pins `0.3.0`. Solution crates.io publishes are **permanent and immutable**: there is no `cargo unpublish`, and a version number, once used, can never be reused with different bytes. So you cannot “re-publish a fixed 0.3.0.” The correct flow is to ship a fix under a new version and yank the broken one: ```bash 1 # Edit Cargo.toml: version = "0.3.1", commit the fix, then: 2 cargo test # confirm the panic is gone 3 cargo publish --dry-run # rehearse 4 cargo publish # ship 0.3.1 5 6 cargo yank --version 0.3.0 # hide the broken 0.3.0 from NEW resolution ``` What `cargo yank` does: 1. **A brand-new project running `cargo add data-parser`** gets `0.3.1`: the yanked `0.3.0` is excluded from new dependency resolution, so it will never be freshly selected (unless explicitly pinned). 2. **An existing project whose `Cargo.lock` already pins `0.3.0`** keeps building exactly as before. Yanking does **not** delete the tarball; the `0.3.0` `.crate` remains downloadable so locked builds are not broken mid-flight. That project’s maintainer should run `cargo update -p data-parser` (or `cargo update`) to move to `0.3.1`. If you yanked by mistake, restore it with `cargo yank --version 0.3.0 --undo`. The point: yanking is a soft “stop offering this for new installs” signal, not a delete button. # Rust Testing with Cargo > Rust bakes testing into Cargo: annotate #[test], run cargo test, no Jest or Vitest setup. Covers assertions, integration and doc tests, mocking, proptest, coverage. In TypeScript, testing means reaching for a third-party framework — Jest, Vitest, Mocha — plus config, a runner, and assertion libraries. Rust bakes testing into the language and Cargo: you annotate a function with `#[test]`, run `cargo test`, and you are done. This section maps your Jest/Vitest habits onto Rust’s built-in `#[test]`, integration tests in `tests/`, and **documentation tests** (your doc examples are compiled and run!), then covers the ecosystem you reach for when the built-ins aren’t enough: **mocking** with mockall, **property-based testing** with proptest, **benchmarking** with criterion, and **coverage** with cargo-llvm-cov. *** ## What You’ll Learn [Section titled “What You’ll Learn”](#what-youll-learn) * How a Jest/Vitest test becomes a `#[test]` function inside a `#[cfg(test)] mod tests`, run with `cargo test` * The conventions for *where* tests live — co-located unit tests vs the top-level `tests/` directory — and why Rust lets unit tests reach private items * The assertion macros `assert!`, `assert_eq!`, `assert_ne!`, and how to attach custom failure messages * How to test that code panics with `#[should_panic(expected = "...")]`, and how to write tests that return `Result` so you can use `?` * How black-box **integration tests** in `tests/` exercise only your public API, and how to share helper code between them * Patterns for setup/teardown without a `beforeEach` — helper constructors, `LazyLock`/`once_cell` for shared state, and RAII guards * How to mock dependencies by programming to traits and generating test doubles with **mockall** (`#[automock]`) * How **property-based testing** with **proptest** checks invariants across hundreds of generated inputs and shrinks failures to a minimal case * How to write statistically rigorous **benchmarks** with **criterion** (stable), and why the built-in `#[bench]` is still nightly-only * How **doc tests** turn the examples in your `///` comments into tests that must keep compiling * How to measure **coverage** with cargo-llvm-cov and speed up runs with cargo-nextest, plus a practical TDD loop in Rust *** ## Topics [Section titled “Topics”](#topics) | Topic | Description | | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | [Unit Tests](/13-testing/00-unit-tests/) | Jest/Vitest → `#[test]` + `#[cfg(test)] mod tests`, run with `cargo test`. | | [Test Organization](/13-testing/01-test-organization/) | Where tests live, the `tests` submodule convention, and testing private vs public items. | | [Assertions](/13-testing/02-assertions/) | `assert!`/`assert_eq!`/`assert_ne!`, custom messages, and comparing with `Debug`. | | [Testing Panics](/13-testing/03-should-panic/) | `#[should_panic(expected = "...")]` and tests that return `Result<(), E>` so you can use `?`. | | [Integration Tests](/13-testing/04-integration-tests/) | The `tests/` directory: black-box testing of the public API and shared helper modules. | | [Test Fixtures](/13-testing/05-test-fixtures/) | Setup/teardown patterns: helper constructors, `LazyLock`/`once_cell` shared state, and RAII guards. | | [Mocking](/13-testing/06-mocking/) | Mocking strategies, trait-based test doubles, and mockall’s `#[automock]`. | | [Property Testing](/13-testing/07-property-testing/) | Property-based testing with proptest: the `proptest!` macro, shrinking, and vs example-based tests. | | [Benchmarking](/13-testing/08-benchmarking/) | Statistically driven benchmarks with criterion, and why `#[bench]` is nightly-only. | | [Doc Tests](/13-testing/09-doc-tests/) | Documentation tests: how `///` code blocks run as tests, `pub` items in scope, and `ignore`/`no_run`/`should_panic`. | | [Coverage](/13-testing/10-coverage/) | Code coverage with cargo-llvm-cov and faster runs with cargo-nextest. | | [TDD Workflow](/13-testing/11-tdd-workflow/) | A red-green-refactor loop in Rust, with `cargo watch` for fast feedback. | *** ## Learning Objectives [Section titled “Learning Objectives”](#learning-objectives) By the end of this section, you will be able to: * Write and run unit tests with `#[test]`/`cargo test`, and decide whether a test belongs co-located or in `tests/` * Assert with the right macro, write clear failure messages, and test both panics and `Result`-returning code * Structure integration tests against your public API and share setup code between them * Replace `beforeEach`/`afterEach` with idiomatic fixtures, lazy statics, and RAII cleanup guards * Mock collaborators by depending on traits and generating doubles with mockall * Cover whole input ranges with proptest, benchmark hot paths with criterion, and keep your documentation honest with doc tests * Measure coverage, run tests faster with nextest, and drive a feature with a TDD loop *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * [Section 12: Modules & Packages](/12-modules-packages/): tests live inside the module tree (`#[cfg(test)] mod tests`) and in the `tests/` directory, and the testing crates are added through Cargo, so the module/Cargo model from Section 12 comes first. * [Section 08: Error Handling](/08-error-handling/): many tests return `Result<(), E>` and use `?`, and you will assert on `Ok`/`Err` values. * [Section 09: Generics & Traits](/09-generics-traits/): mocking works by programming to traits, so trait basics make the mocking topic land. *** ## Estimated Time [Section titled “Estimated Time”](#estimated-time) * **Reading:** 5 hours * **Hands-on Practice:** 4 hours * **Exercises:** 2-3 hours * **Total:** 10-12 hours > **Tip:** Start with `unit-tests`, `assertions`, and `should-panic`. That trio covers 90% of day-to-day testing. Add `integration-tests` and `doc-tests` next. Treat `mocking`, `property-testing`, `benchmarking`, and `coverage` as a toolbox to pull from when a specific need arises, rather than something to master up front. *** **Next:** [Section 14: Macros →](/14-macros/) — declarative and procedural macros, Rust’s compile-time code generation. # Unit Tests > Unlike Jest or Vitest, Rust unit tests are #[test] functions in a #[cfg(test)] mod beside the code, run by cargo test with no config, and can reach private items. Coming from Jest or Vitest, you are used to a separate test runner, a config file, and `*.test.ts` files living somewhere in your project. Rust folds all of that into the language and the build tool: tests are ordinary functions marked with `#[test]`, the test runner ships with `cargo`, and there is nothing to install or configure. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **unit test** in Rust is a normal function annotated with the `#[test]` attribute, almost always grouped inside a `#[cfg(test)] mod tests` module that sits in the *same file* as the code it exercises. You run the whole suite with `cargo test`: no `package.json` script, no `jest.config.js`, no extra dependency. Because the tests live next to the code, they can reach **private** functions, which is the single biggest difference from the black-box habits most JavaScript test suites fall into. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Here is a small pricing module and a Vitest suite for it, the kind of thing you would write every day. cart.ts ```typescript 1 export function cartTotalCents( 2 items: { unitPriceCents: number; quantity: number }[], 3 discountPercent: number, 4 ): number { 5 const subtotal = items.reduce( 6 (acc, it) => acc + it.unitPriceCents * it.quantity, 7 0, 8 ); 9 const percent = Math.min(discountPercent, 100); 10 // Integer-cents math: truncate the discount, never carry fractional cents. 11 return subtotal - Math.trunc((subtotal * percent) / 100); 12 } ``` cart.test.ts ```typescript 1 import { describe, it, expect } from "vitest"; 2 import { cartTotalCents } from "./cart"; 3 4 const cart = [ 5 { unitPriceCents: 4999, quantity: 1 }, 6 { unitPriceCents: 999, quantity: 3 }, 7 ]; 8 9 describe("cartTotalCents", () => { 10 it("sums all lines with no discount", () => { 11 expect(cartTotalCents(cart, 0)).toBe(7996); 12 }); 13 14 it("applies a whole-cart discount", () => { 15 expect(cartTotalCents(cart, 10)).toBe(7197); 16 }); 17 18 it("clamps a discount over 100%", () => { 19 expect(cartTotalCents(cart, 250)).toBe(0); 20 }); 21 }); ``` Run it with `npx vitest run`: ```text 1 RUN v4.1.7 2 3 Test Files 1 passed (1) 4 Tests 3 passed (3) ``` Key things a JavaScript developer takes for granted here: * Tests live in a **separate file** (`cart.test.ts`) and import the module’s **public** exports. * A **test runner** (Vitest/Jest) is a dependency you add and configure. * `describe`/`it`/`expect` are functions that the runner provides. Every one of those assumptions changes in Rust. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same module and its tests, in one file. The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically, so nothing below needs an explicit edition. src/lib.rs ```rust 1 /// Computes the cart total in cents after applying a whole-cart 2 /// percentage discount (clamped to 0..=100). 3 pub fn cart_total_cents(items: &[(u64, u32)], discount_percent: u8) -> u64 { 4 // Each tuple is (unit_price_cents, quantity). 5 let subtotal: u64 = items.iter().map(|(price, qty)| price * *qty as u64).sum(); 6 let percent = discount_percent.min(100) as u64; 7 subtotal - (subtotal * percent) / 100 8 } 9 10 #[cfg(test)] 11 mod tests { 12 use super::*; 13 14 fn sample_cart() -> Vec<(u64, u32)> { 15 vec![(4_999, 1), (999, 3)] 16 } 17 18 #[test] 19 fn sums_all_lines_with_no_discount() { 20 assert_eq!(cart_total_cents(&sample_cart(), 0), 7_996); 21 } 22 23 #[test] 24 fn applies_a_whole_cart_discount() { 25 assert_eq!(cart_total_cents(&sample_cart(), 10), 7_197); 26 } 27 28 #[test] 29 fn clamps_a_discount_over_100_percent() { 30 assert_eq!(cart_total_cents(&sample_cart(), 250), 0); 31 } 32 } ``` Run it with `cargo test`: ```text 1 running 3 tests 2 test tests::applies_a_whole_cart_discount ... ok 3 test tests::clamps_a_discount_over_100_percent ... ok 4 test tests::sums_all_lines_with_no_discount ... ok 5 6 test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` > **Note:** Rust’s integer division truncates *the division*, so `(7996 * 10) / 100` is `799`, giving `7996 - 799 = 7197`. The TypeScript version above uses `Math.trunc` on the inner division to match. If you wrote the JavaScript without that `Math.trunc`, the inner division yields `799.6` and the final result would be `7196.4` (a non-integer), a genuinely different answer. This is a recurring theme: when porting numeric code, the *order* of truncation matters. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) Let’s walk through the Rust test block line by line and contrast each piece with the Vitest version. ### `#[cfg(test)]` — conditional compilation [Section titled “#\[cfg(test)\] — conditional compilation”](#cfgtest--conditional-compilation) ```rust 1 #[cfg(test)] 2 mod tests { 3 // ... 4 } ``` `#[cfg(test)]` is an **attribute** that tells the compiler: only compile this module when building in *test mode* (`cargo test`). During a normal `cargo build` or `cargo build --release`, the entire `tests` module (and anything it imports) is stripped out. There is **zero cost** to your production binary. This is the conceptual equivalent of Jest/Vitest only loading `*.test.ts` files when the runner is invoked, except Rust does it at compile time rather than by file-name convention. There is no separate test file to forget to exclude from your bundle. > **Note:** The module is named `tests` purely by convention. The name is not magic; `#[cfg(test)] mod whatever { ... }` works identically. The community standard is `tests`, and following it makes your code instantly readable to other Rustaceans. ### `mod tests` — a child module [Section titled “mod tests — a child module”](#mod-tests--a-child-module) ```rust 1 mod tests { 2 use super::*; 3 // ... 4 } ``` `mod tests` declares a child module. Because it is a *child* of the module that defines `cart_total_cents`, it can see that module’s **private** items too. `use super::*;` pulls everything from the parent module (`super`) into scope so you can call `cart_total_cents` directly instead of writing `super::cart_total_cents` every time. This is the superpower JavaScript test suites lack. In Vitest you can only test what a module `export`s; to test an unexported helper you must either export it (polluting the public surface) or reach in with a tool like `rewire`. In Rust, a `#[cfg(test)] mod tests` inside the file sees the private helpers for free. (More on where to put tests in [Test Organization](/13-testing/01-test-organization/).) ### `#[test]` — marking a test function [Section titled “#\[test\] — marking a test function”](#test--marking-a-test-function) ```rust 1 #[test] 2 fn sums_all_lines_with_no_discount() { 3 assert_eq!(cart_total_cents(&sample_cart(), 0), 7_996); 4 } ``` `#[test]` marks a function as a test. The function must take **no arguments** and (in the simplest case) return **no value** — it is just a `fn name() { ... }`. There is no `it("...", () => {})` wrapper: the test’s *name* is the function’s name, and the test “passes” if the function returns normally and “fails” if it **panics**. That is the core mental model: | Vitest/Jest | Rust | | ------------------------------------ | ------------------------------------- | | `it("name", () => { ... })` | `#[test] fn name() { ... }` | | test fails if an `expect` throws | test fails if the function **panics** | | `describe("group", ...)` for nesting | a `mod` for nesting | ### `assert_eq!` — the assertion [Section titled “assert\_eq! — the assertion”](#assert_eq--the-assertion) ```rust 1 assert_eq!(cart_total_cents(&sample_cart(), 0), 7_996); ``` `assert_eq!(left, right)` panics if the two values are not equal, which is exactly what makes a `#[test]` fail. It is the rough analogue of `expect(actual).toBe(expected)`. Rust ships a small family (`assert!`, `assert_eq!`, `assert_ne!`) covered in detail in [Assertions](/13-testing/02-assertions/). For now, the important point is that an assertion failure is just a panic with a nicely formatted message. ### `sample_cart()` — a plain helper [Section titled “sample\_cart() — a plain helper”](#sample_cart--a-plain-helper) ```rust 1 fn sample_cart() -> Vec<(u64, u32)> { 2 vec![(4_999, 1), (999, 3)] 3 } ``` There is no `beforeEach`. To share setup between tests you write an ordinary function and call it. This keeps data flow explicit — each test constructs exactly what it needs. Richer setup/teardown patterns (and the rare cases where you *do* want shared state) live in [Test Fixtures](/13-testing/05-test-fixtures/). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | Jest / Vitest | Rust | | -------------------- | ---------------------------------------- | ------------------------------------------------ | | Test runner | Separate dependency (`jest`, `vitest`) | Built into `cargo`; nothing to install | | Config | `jest.config.js` / `vitest.config.ts` | None required | | Where tests live | Usually a separate `*.test.ts` file | Same file, in a `#[cfg(test)] mod tests` | | Declaring a test | `it("...", () => {})` | `#[test] fn ...() {}` | | Grouping | `describe(...)` | nested `mod` | | Pass / fail signal | assertion throws an exception | function **panics** | | Setup | `beforeEach` / `beforeAll` | a helper function you call | | Access to internals | only `export`ed items (without hacks) | private items visible to the in-file test module | | Excluded from builds | by file-name convention / bundler config | by `#[cfg(test)]` at compile time | | Parallelism | configurable, file-level by default | tests run **in parallel threads** by default | Two differences deserve emphasis: **Tests run in parallel by default.** Vitest parallelizes across files; Rust runs *individual test functions* on multiple threads at once. That is great for speed but means tests must not depend on shared mutable global state or on each other’s ordering. If you need serial execution, run `cargo test -- --test-threads=1`. **A test passes by *not panicking*.** There is no “expected 0 assertions” concept. A `#[test] fn` with an empty body passes. A test that calls `.unwrap()` on a `None` fails because `.unwrap()` panics. Once you internalize “failure == panic,” the rest of Rust testing clicks into place. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Giving a `#[test]` function parameters [Section titled “Pitfall 1: Giving a #\[test\] function parameters”](#pitfall-1-giving-a-test-function-parameters) JavaScript test callbacks sometimes take a `done` argument or a fixture. A Rust test takes none. ```rust 1 pub fn double(n: i32) -> i32 { 2 n * 2 3 } 4 5 #[cfg(test)] 6 mod tests { 7 use super::*; 8 9 #[test] 10 fn doubles(n: i32) { 11 // does not compile: functions used as tests can not have any arguments 12 assert_eq!(double(n), n * 2); 13 } 14 } ``` Real output from `cargo test`: ```text 1 error: functions used as tests can not have any arguments 2 --> src/lib.rs:10:5 3 | 4 10 | / fn doubles(n: i32) { 5 11 | | assert_eq!(double(n), n * 2); 6 12 | | } 7 | |_____^ ``` The fix is to pick the inputs inside the test body. If you genuinely want to test many inputs, that is what [property testing](/13-testing/07-property-testing/) (proptest) is for. ### Pitfall 2: Trying to reach a private item across module boundaries [Section titled “Pitfall 2: Trying to reach a private item across module boundaries”](#pitfall-2-trying-to-reach-a-private-item-across-module-boundaries) The in-file test module can see private items of *its parent*, but not private items of an *unrelated* module. ```rust 1 mod math { 2 // private (no `pub`) 3 fn double(n: i32) -> i32 { 4 n * 2 5 } 6 } 7 8 #[cfg(test)] 9 mod tests { 10 #[test] 11 fn doubles() { 12 // does not compile (error[E0603]): `double` is private to `math` 13 assert_eq!(crate::math::double(21), 42); 14 } 15 } ``` Real error: ```text 1 error[E0603]: function `double` is private 2 --> src/lib.rs:13:33 3 | 4 13 | assert_eq!(crate::math::double(21), 42); 5 | ^^^^^^ private function 6 | 7 note: the function `double` is defined here 8 --> src/lib.rs:3:5 9 | 10 3 | fn double(n: i32) -> i32 { 11 | ^^^^^^^^^^^^^^^^^^^^^^^^ ``` The fix is to put the test module *inside* `mod math` (so it becomes a child and inherits visibility), or make `double` public if it is genuinely part of the API. This visibility-vs-location trade-off is the heart of [Test Organization](/13-testing/01-test-organization/). ### Pitfall 3: Forgetting `#[cfg(test)]` [Section titled “Pitfall 3: Forgetting #\[cfg(test)\]”](#pitfall-3-forgetting-cfgtest) If you write `mod tests` without the `#[cfg(test)]` attribute, the test code is compiled into your normal build. At best you get dead-code warnings; at worst, a test-only dependency leaks into your release binary. Always pair the two: ```rust 1 #[cfg(test)] // <- do not omit this 2 mod tests { 3 // ... 4 } ``` ### Pitfall 4: Expecting `--exact` to match a bare name [Section titled “Pitfall 4: Expecting --exact to match a bare name”](#pitfall-4-expecting---exact-to-match-a-bare-name) `cargo test some_name` filters by **substring** of the *full path*. The exact-match flag matches the full path, not the bare function name: ```bash 1 # Test is `tests::discount_full`. This matches NOTHING, because the full 2 # path is "tests::discount_full", not "discount_full": 3 cargo test discount_full -- --exact # 0 tests run 4 5 # Use the full module path: 6 cargo test tests::discount_full -- --exact # 1 test runs ``` Real output of the working form: ```text 1 running 1 test 2 test tests::discount_full ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 3 filtered out; finished in 0.00s ``` Without `--exact`, `cargo test discount` happily runs *every* test whose path contains `discount`. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Keep unit tests in the file, next to the code [Section titled “Keep unit tests in the file, next to the code”](#keep-unit-tests-in-the-file-next-to-the-code) The idiomatic place for unit tests is a `#[cfg(test)] mod tests` at the bottom of the same file. This keeps a function and its tests within scrolling distance and grants access to private helpers. Reserve the separate `tests/` directory for black-box [integration tests](/13-testing/04-integration-tests/). ### Name tests after the behavior they assert [Section titled “Name tests after the behavior they assert”](#name-tests-after-the-behavior-they-assert) Because the function name *is* the test name in the output, descriptive names pay off: ```rust 1 // reads like a spec in the test report 2 #[test] 3 fn clamps_a_discount_over_100_percent() { /* ... */ } 4 5 // tells you nothing when it fails 6 #[test] 7 fn test1() { /* ... */ } ``` The `tests::` prefix and `snake_case` give you sentence-like output: `test tests::clamps_a_discount_over_100_percent ... ok`. ### Use `#[ignore]` for expensive tests, not commenting-out [Section titled “Use #\[ignore\] for expensive tests, not commenting-out”](#use-ignore-for-expensive-tests-not-commenting-out) Mark slow or environment-dependent tests with `#[ignore]` and a reason. They are skipped by default and run on demand. ```rust 1 #[test] 2 #[ignore = "slow: only run on demand"] 3 fn expensive_property_sweep() { 4 for a in 0..1000 { 5 assert_eq!(a + 0, a); 6 } 7 } ``` A normal `cargo test` reports it as skipped: ```text 1 test tests::expensive_property_sweep ... ignored, slow: only run on demand ``` Run only the ignored ones with `cargo test -- --ignored`, or everything with `cargo test -- --include-ignored`. ### Know the everyday `cargo test` flags [Section titled “Know the everyday cargo test flags”](#know-the-everyday-cargo-test-flags) * `cargo test name_substring`: run only tests whose path contains the substring. * `cargo test -- --show-output`: print stdout even from **passing** tests (by default it is captured). * `cargo test -- --nocapture`: let `println!` stream to the terminal live. * `cargo test -- --test-threads=1`: run serially (useful for debugging order-dependent flakiness). * `cargo test -- --list`: list the tests without running them. By default Rust **captures** stdout from passing tests and only shows it on failure. With `--show-output`, a passing test that does `println!("about to add 2 + 2")` reports: ```text 1 running 3 tests 2 test tests::adds_small_numbers ... ok 3 test tests::ten_percent_off ... ok 4 test tests::prints_while_testing ... ok 5 6 successes: 7 8 ---- tests::prints_while_testing stdout ---- 9 about to add 2 + 2 ``` *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored pricing module with a typed `LineItem`, a **private** helper, and a unit-test module that exercises both the public function and the private one. This is the full, compile-verified file. src/lib.rs ```rust 1 //! A small shopping-cart pricing module. 2 3 /// A line item in a shopping cart. 4 #[derive(Debug, Clone, PartialEq)] 5 pub struct LineItem { 6 pub name: String, 7 pub unit_price_cents: u64, 8 pub quantity: u32, 9 } 10 11 impl LineItem { 12 pub fn new(name: &str, unit_price_cents: u64, quantity: u32) -> Self { 13 LineItem { 14 name: name.to_string(), 15 unit_price_cents, 16 quantity, 17 } 18 } 19 } 20 21 /// Private helper: subtotal for a single line, in cents. 22 fn line_subtotal(item: &LineItem) -> u64 { 23 item.unit_price_cents * item.quantity as u64 24 } 25 26 /// Computes the cart total in cents after applying a whole-cart 27 /// percentage discount (clamped to 0..=100). 28 pub fn cart_total_cents(items: &[LineItem], discount_percent: u8) -> u64 { 29 let subtotal: u64 = items.iter().map(line_subtotal).sum(); 30 let percent = discount_percent.min(100) as u64; 31 subtotal - (subtotal * percent) / 100 32 } 33 34 #[cfg(test)] 35 mod tests { 36 use super::*; 37 38 fn sample_cart() -> Vec<LineItem> { 39 vec![ 40 LineItem::new("Keyboard", 4_999, 1), 41 LineItem::new("Cable", 999, 3), 42 ] 43 } 44 45 #[test] 46 fn subtotal_of_a_line_multiplies_quantity() { 47 // `line_subtotal` is private, but the test module sees it via `super`. 48 let item = LineItem::new("Cable", 999, 3); 49 assert_eq!(line_subtotal(&item), 2_997); 50 } 51 52 #[test] 53 fn total_without_discount_sums_all_lines() { 54 assert_eq!(cart_total_cents(&sample_cart(), 0), 4_999 + 2_997); 55 } 56 57 #[test] 58 fn discount_is_applied_to_the_whole_cart() { 59 // 10% off 7996 -> 7996 - 799 = 7197 (integer division truncates). 60 assert_eq!(cart_total_cents(&sample_cart(), 10), 7_197); 61 } 62 63 #[test] 64 fn discount_over_100_is_clamped() { 65 assert_eq!(cart_total_cents(&sample_cart(), 250), 0); 66 } 67 68 #[test] 69 fn empty_cart_is_free() { 70 assert_eq!(cart_total_cents(&[], 0), 0); 71 } 72 } ``` Running `cargo test` produces real output: ```text 1 running 5 tests 2 test tests::discount_is_applied_to_the_whole_cart ... ok 3 test tests::discount_over_100_is_clamped ... ok 4 test tests::empty_cart_is_free ... ok 5 test tests::subtotal_of_a_line_multiplies_quantity ... ok 6 test tests::total_without_discount_sums_all_lines ... ok 7 8 test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` When a test fails (say someone changes the discount formula and `discount_is_applied_to_the_whole_cart` now returns `900` instead of the expected `950`), the report tells you exactly what diverged: ```text 1 running 3 tests 2 test tests::adds_small_numbers ... ok 3 test tests::prints_while_testing ... ok 4 test tests::ten_percent_off ... FAILED 5 6 failures: 7 8 ---- tests::ten_percent_off stdout ---- 9 10 thread 'tests::ten_percent_off' panicked at src/lib.rs:17:9: 11 assertion `left == right` failed 12 left: 900 13 right: 950 14 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace 15 16 17 failures: 18 tests::ten_percent_off 19 20 test result: FAILED. 2 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` The `left`/`right` labels come from `assert_eq!`: `left` is your computed value, `right` is the expected one. `cargo test` exits with a non-zero status (`101`) when any test fails, so CI catches it automatically. > **Tip:** The exact same suite would run as black-box [integration tests](/13-testing/04-integration-tests/) by moving the test functions into a file under `tests/` and importing the crate, but then they could only call the **public** `cart_total_cents`, not the private `line_subtotal`. Choosing between the two is exactly the topic of [Test Organization](/13-testing/01-test-organization/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [The Rust Book — How to Write Tests](https://doc.rust-lang.org/book/ch11-01-writing-tests.html) * [The Rust Book — Running Tests](https://doc.rust-lang.org/book/ch11-02-running-tests.html) * [Rust by Example — Unit Testing](https://doc.rust-lang.org/rust-by-example/testing/unit_testing.html) * [`cargo test` reference](https://doc.rust-lang.org/cargo/commands/cargo-test.html) * Sibling topics in this section: * [Test Organization](/13-testing/01-test-organization/): where tests live; private vs public testing. * [Assertions](/13-testing/02-assertions/): `assert!`, `assert_eq!`, `assert_ne!`, and custom messages. * [`#[should_panic]` and `Result` tests](/13-testing/03-should-panic/): testing failure paths and using `?` in tests. * [Integration Tests](/13-testing/04-integration-tests/): the `tests/` directory and black-box testing. * [Test Fixtures](/13-testing/05-test-fixtures/): setup/teardown patterns. * [Mocking](/13-testing/06-mocking/), [Property Testing](/13-testing/07-property-testing/), [Benchmarking](/13-testing/08-benchmarking/), [Doc Tests](/13-testing/09-doc-tests/), [Coverage](/13-testing/10-coverage/), [TDD Workflow](/13-testing/11-tdd-workflow/). * Foundations used above: * [Cargo Basics](/01-getting-started/03-cargo-basics/): `cargo` is the test runner, too. * [Modules and Packages](/12-modules-packages/): how `mod`, `super`, and visibility work. * [Result and Option](/08-error-handling/00-result-option/): `.unwrap()` panics, which is how those panics surface in tests. * [Macros](/14-macros/): `#[test]`, `assert_eq!`, and friends are macros/attributes; this section explains how that machinery works. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Your first `#[test]` [Section titled “Exercise 1: Your first #\[test\]”](#exercise-1-your-first-test) **Difficulty:** Easy **Objective:** Add a unit-test module to an existing function. **Instructions:** Given the `fizzbuzz` function below, add a `#[cfg(test)] mod tests` module with one `#[test]` that checks the four interesting cases: `1 -> "1"`, `3 -> "Fizz"`, `5 -> "Buzz"`, `15 -> "FizzBuzz"`. Run `cargo test` and confirm it passes. ```rust 1 pub fn fizzbuzz(n: u32) -> String { 2 match (n % 3, n % 5) { 3 (0, 0) => "FizzBuzz".to_string(), 4 (0, _) => "Fizz".to_string(), 5 (_, 0) => "Buzz".to_string(), 6 _ => n.to_string(), 7 } 8 } 9 10 // TODO: add a #[cfg(test)] mod tests here ``` Solution ```rust 1 pub fn fizzbuzz(n: u32) -> String { 2 match (n % 3, n % 5) { 3 (0, 0) => "FizzBuzz".to_string(), 4 (0, _) => "Fizz".to_string(), 5 (_, 0) => "Buzz".to_string(), 6 _ => n.to_string(), 7 } 8 } 9 10 #[cfg(test)] 11 mod tests { 12 use super::*; 13 14 #[test] 15 fn fizzbuzz_basics() { 16 assert_eq!(fizzbuzz(1), "1"); 17 assert_eq!(fizzbuzz(3), "Fizz"); 18 assert_eq!(fizzbuzz(5), "Buzz"); 19 assert_eq!(fizzbuzz(15), "FizzBuzz"); 20 } 21 } ``` `cargo test` output: ```text 1 running 1 test 2 test tests::fizzbuzz_basics ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` ### Exercise 2: Test a generic type’s behavior [Section titled “Exercise 2: Test a generic type’s behavior”](#exercise-2-test-a-generic-types-behavior) **Difficulty:** Medium **Objective:** Write multiple focused tests for a small data structure. **Instructions:** Implement a generic `Stack<T>` with `new`, `push`, `pop`, `len`, and `is_empty`. Then write tests verifying that (a) a new stack is empty, and (b) pushing two items and popping returns them last-in-first-out, ending in `None`. ```rust 1 #[derive(Default)] 2 pub struct Stack<T> { 3 items: Vec<T>, 4 } 5 6 impl<T> Stack<T> { 7 // TODO: new, push, pop, len, is_empty 8 } 9 10 // TODO: add tests ``` Solution ```rust 1 #[derive(Default)] 2 pub struct Stack<T> { 3 items: Vec<T>, 4 } 5 6 impl<T> Stack<T> { 7 pub fn new() -> Self { 8 Stack { items: Vec::new() } 9 } 10 pub fn push(&mut self, item: T) { 11 self.items.push(item); 12 } 13 pub fn pop(&mut self) -> Option<T> { 14 self.items.pop() 15 } 16 pub fn len(&self) -> usize { 17 self.items.len() 18 } 19 pub fn is_empty(&self) -> bool { 20 self.items.is_empty() 21 } 22 } 23 24 #[cfg(test)] 25 mod tests { 26 use super::*; 27 28 #[test] 29 fn new_stack_is_empty() { 30 let stack: Stack<i32> = Stack::new(); 31 assert!(stack.is_empty()); 32 assert_eq!(stack.len(), 0); 33 } 34 35 #[test] 36 fn push_then_pop_is_lifo() { 37 let mut stack = Stack::new(); 38 stack.push(1); 39 stack.push(2); 40 assert_eq!(stack.pop(), Some(2)); 41 assert_eq!(stack.pop(), Some(1)); 42 assert_eq!(stack.pop(), None); 43 } 44 } ``` `cargo test` output: ```text 1 running 2 tests 2 test tests::new_stack_is_empty ... ok 3 test tests::push_then_pop_is_lifo ... ok 4 5 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` ### Exercise 3: Test a private helper through the test module [Section titled “Exercise 3: Test a private helper through the test module”](#exercise-3-test-a-private-helper-through-the-test-module) **Difficulty:** Medium **Objective:** Exploit the in-file test module’s access to private items, something a Vitest black-box suite cannot do without exporting internals. **Instructions:** Write a **private** `collapse_whitespace(&str) -> String` that turns any run of whitespace into a single space, and a **public** `slugify(&str) -> String` that collapses whitespace, lowercases, and replaces spaces with hyphens. Write tests that check `slugify` *and* that call the private `collapse_whitespace` directly. ```rust 1 // TODO: a private collapse_whitespace and a public slugify, plus tests ``` Solution ```rust 1 fn collapse_whitespace(s: &str) -> String { 2 s.split_whitespace().collect::<Vec<_>>().join(" ") 3 } 4 5 pub fn slugify(title: &str) -> String { 6 collapse_whitespace(title) 7 .to_lowercase() 8 .replace(' ', "-") 9 } 10 11 #[cfg(test)] 12 mod tests { 13 use super::*; 14 15 #[test] 16 fn slugify_collapses_and_lowercases() { 17 assert_eq!(slugify(" Hello Rust World "), "hello-rust-world"); 18 } 19 20 #[test] 21 fn collapse_whitespace_is_testable_directly() { 22 // Reaching a private fn — only possible because tests live in-file. 23 assert_eq!(collapse_whitespace("a b\tc"), "a b c"); 24 } 25 } ``` `cargo test` output: ```text 1 running 2 tests 2 test tests::collapse_whitespace_is_testable_directly ... ok 3 test tests::slugify_collapses_and_lowercases ... ok 4 5 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` # Test Organization > Rust puts unit tests in a #[cfg(test)] mod tests beside the code so they reach private items, while tests/ integration files, like Jest, see only the public API. In TypeScript and JavaScript, tests almost always live in separate files that import the code under test. Rust takes a different default: small unit tests live *inside* the same file as the code they exercise, in a dedicated `tests` submodule. This file explains where Rust tests go, why the `#[cfg(test)] mod tests` convention exists, and how it enables something Jest and Vitest cannot easily do: testing private functions directly. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Rust recognizes two kinds of tests and gives each a home: * **Unit tests** live in the same file as the code, in a `#[cfg(test)] mod tests` submodule. Because they are *inside* the crate, they can reach **private** functions and types. * **Integration tests** live in a top-level `tests/` directory. Each file there is compiled as a separate crate that links your library from the outside, so it can only touch the **public** API. > **Note:** This file focuses on *where tests live* and *what they can see*: the module layout and the private-versus-public distinction. The mechanics of writing a `#[test]` and running `cargo test` are covered in [Unit Tests](/13-testing/00-unit-tests/), and the `tests/` directory gets a full treatment in [Integration Tests](/13-testing/04-integration-tests/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In a TypeScript project using Jest or Vitest, tests live in their own files. The two most common conventions are co-located test files next to the source, or a parallel `__tests__` directory. ```typescript 1 // src/username.ts — the code under test 2 export class UsernameError extends Error {} 3 4 // Exported: part of the public API. 5 export function parseUsername(raw: string): string { 6 const trimmed = raw.trim(); 7 checkLength(trimmed); 8 const bad = firstInvalidChar(trimmed); 9 if (bad !== null) { 10 throw new UsernameError(`invalid character: '${bad}'`); 11 } 12 return trimmed.toLowerCase(); 13 } 14 15 // NOT exported: a private helper, invisible outside this module. 16 function checkLength(s: string): void { 17 if (s.length < 3) throw new UsernameError("too short"); 18 if (s.length > 20) throw new UsernameError("too long"); 19 } 20 21 function firstInvalidChar(s: string): string | null { 22 for (const c of s) { 23 if (!/[a-z0-9_]/i.test(c)) return c; 24 } 25 return null; 26 } ``` ```typescript 1 // src/username.test.ts — the test file, a SEPARATE module 2 import { parseUsername, UsernameError } from "./username"; 3 4 describe("parseUsername", () => { 5 it("normalizes valid input", () => { 6 expect(parseUsername(" AdaLovelace ")).toBe("adalovelace"); 7 }); 8 9 it("rejects bad characters", () => { 10 expect(() => parseUsername("ada lovelace")).toThrow(UsernameError); 11 }); 12 }); 13 14 // You CANNOT test `checkLength` or `firstInvalidChar` here: 15 // they are not exported, so `import` cannot reach them. To test them 16 // you would either export them (widening your public API for tests' 17 // sake) or reach for a hack like `rewire` / `babel-plugin-rewire`. ``` **Key points about the TypeScript layout:** * Tests are a separate file/module that `import`s the code. * The test file can only see **exported** (`export`) members. * Private functions are genuinely unreachable from tests unless you export them or use a module-internals hack. * The test runner (Jest/Vitest) discovers files by a glob like `**/*.test.ts` configured in `jest.config.js` / `vitest.config.ts`. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) In Rust, the unit tests for `username.rs` live *in the same file*, inside a child module annotated with `#[cfg(test)]`. That module can reach the private helpers directly via `use super::*`. ```rust 1 // src/lib.rs — code and its unit tests in ONE file 2 3 /// A validated, normalized username. 4 #[derive(Debug, PartialEq, Eq)] 5 pub struct Username(String); 6 7 /// Errors that can occur while validating a username. 8 #[derive(Debug, PartialEq, Eq)] 9 pub enum UsernameError { 10 TooShort, 11 TooLong, 12 InvalidChar(char), 13 } 14 15 impl Username { 16 /// Build a `Username` from raw input, enforcing the rules. (public API) 17 pub fn parse(raw: &str) -> Result<Username, UsernameError> { 18 let trimmed = raw.trim(); 19 check_length(trimmed)?; 20 if let Some(bad) = first_invalid_char(trimmed) { 21 return Err(UsernameError::InvalidChar(bad)); 22 } 23 Ok(Username(trimmed.to_lowercase())) 24 } 25 26 /// Borrow the normalized value. (public API) 27 pub fn as_str(&self) -> &str { 28 &self.0 29 } 30 } 31 32 // --- Private helpers: implementation details, not part of the public API. --- 33 34 fn check_length(s: &str) -> Result<(), UsernameError> { 35 match s.chars().count() { 36 0..=2 => Err(UsernameError::TooShort), 37 3..=20 => Ok(()), 38 _ => Err(UsernameError::TooLong), 39 } 40 } 41 42 fn first_invalid_char(s: &str) -> Option<char> { 43 s.chars().find(|c| !(c.is_ascii_alphanumeric() || *c == '_')) 44 } 45 46 #[cfg(test)] 47 mod tests { 48 // Pull the PARENT module's items into scope — including private ones. 49 use super::*; 50 51 #[test] 52 fn accepts_and_normalizes_valid_input() { 53 let name = Username::parse(" AdaLovelace ").unwrap(); 54 assert_eq!(name.as_str(), "adalovelace"); 55 } 56 57 #[test] 58 fn rejects_bad_characters() { 59 assert_eq!( 60 Username::parse("ada lovelace"), 61 Err(UsernameError::InvalidChar(' ')), 62 ); 63 } 64 65 // Testing a PRIVATE helper directly — no need to make it public. 66 #[test] 67 fn length_boundaries() { 68 assert_eq!(check_length("ab"), Err(UsernameError::TooShort)); 69 assert_eq!(check_length("abc"), Ok(())); 70 assert_eq!(check_length(&"x".repeat(21)), Err(UsernameError::TooLong)); 71 } 72 73 #[test] 74 fn finds_first_invalid_char() { 75 assert_eq!(first_invalid_char("ok_name"), None); 76 assert_eq!(first_invalid_char("no!"), Some('!')); 77 } 78 } ``` Running `cargo test` produces: ```text 1 running 4 tests 2 test tests::rejects_bad_characters ... ok 3 test tests::length_boundaries ... ok 4 test tests::finds_first_invalid_char ... ok 5 test tests::accepts_and_normalizes_valid_input ... ok 6 7 test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` Notice that `check_length` and `first_invalid_char` are private (no `pub`), yet the tests call them. This is the headline difference from TypeScript: **co-located unit tests can test private code without weakening your public API.** *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The `tests` submodule, line by line [Section titled “The tests submodule, line by line”](#the-tests-submodule-line-by-line) ```rust 1 #[cfg(test)] 2 mod tests { 3 use super::*; 4 5 #[test] 6 fn accepts_and_normalizes_valid_input() { /* ... */ } 7 } ``` * **`mod tests { ... }`** declares a child module. The name `tests` is a strong convention, not a keyword. The compiler does not care what you call it, but every Rust project you read will use `tests`. Because it is a child module, it sits *below* the code in the module tree, which is what gives it access to the parent’s private items. * **`#[cfg(test)]`** is a **conditional compilation** attribute. `cfg` means “configuration”, and `test` is a flag Cargo sets only when building the test harness. So the module (and everything in it) is compiled *only* during `cargo test` and completely vanishes from `cargo build` and `cargo run`. Your release binary carries zero test code and zero test dependencies. * **`use super::*;`** imports everything from the **parent** module (`super` = “one level up”) into the test module. Without it, you would have to write `super::Username::parse(...)` and `super::check_length(...)` on every line. The glob `*` is idiomatic *here specifically* because test modules are small and tightly coupled to their parent. In normal application code, glob imports are discouraged. * **`#[test]`** marks a function as a test case. See [Unit Tests](/13-testing/00-unit-tests/) for the full story on `#[test]`. ### Why “inside the file” instead of “next to it”? [Section titled “Why “inside the file” instead of “next to it”?”](#why-inside-the-file-instead-of-next-to-it) This is the part that feels backwards coming from TypeScript. Rust’s module system makes child modules privileged: **a child module can see all of its ancestors’ private items, but not vice versa.** By placing tests in a child module, you grant them access to internals *for free*, without exporting anything. > **Tip:** Think of `#[cfg(test)] mod tests` as a private workshop bolted onto each source file. It is part of the crate, so it sees everything, but it is sealed off (`cfg(test)`) so it never ships. ### Visibility recap: who can see what [Section titled “Visibility recap: who can see what”](#visibility-recap-who-can-see-what) | Item visibility | Unit test (`#[cfg(test)] mod tests`) | Integration test (`tests/` dir) | | --------------- | ------------------------------------ | ------------------------------- | | `fn foo` | Yes (it is an ancestor’s item) | No — private | | `pub(crate) fn` | Yes | No — not visible outside crate | | `pub fn foo` | Yes | Yes | The `pub(crate)` row matters: an item that is public *within* the crate is reachable by unit tests (same crate) but invisible to integration tests (separate crate). For more on `pub`, `pub(crate)`, and the module tree, see [Modules](/12-modules-packages/00-modules/). ### Where tests physically live [Section titled “Where tests physically live”](#where-tests-physically-live) | Test kind | Location | Compiled as | Sees private code? | | ------------------- | -------------------------------------- | --------------------- | ------------------ | | Unit tests | same file, in `#[cfg(test)] mod tests` | part of your crate | Yes | | Integration tests | `tests/*.rs` (top-level `tests/` dir) | one crate per file | Public API only | | Documentation tests | inside `///` doc comments | one crate per example | Public API only | This file is about the first row; [Integration Tests](/13-testing/04-integration-tests/) and [Documentation Tests](/13-testing/09-doc-tests/) cover the others. *** ## Key Differences [Section titled “Key Differences”](#key-differences) ### 1. Co-location vs. separate files [Section titled “1. Co-location vs. separate files”](#1-co-location-vs-separate-files) | Aspect | TypeScript (Jest/Vitest) | Rust | | ------------------------ | ------------------------------------------ | ------------------------------------------- | | Default unit-test home | Separate file (`*.test.ts` / `__tests__/`) | Same file, in `#[cfg(test)] mod tests` | | Test discovery | Config glob (`testMatch` / `include`) | Built into `cargo`; no config needed | | Stripped from prod build | Bundler/`tsconfig` excludes test files | `#[cfg(test)]` excludes at compile time | | Reaches private members | No (unless exported or a rewire hack) | Yes (child module sees ancestor’s privates) | ### 2. The compiler enforces the prod/test split [Section titled “2. The compiler enforces the prod/test split”](#2-the-compiler-enforces-the-prodtest-split) In TypeScript, keeping test code out of your shipped bundle is a *build configuration* concern: forget to exclude `*.test.ts` and it ships. In Rust, `#[cfg(test)]` is a *compiler* feature: code behind it does not exist in non-test builds, so it cannot accidentally leak into production. Test-only dependencies go in `[dev-dependencies]` in `Cargo.toml` and are likewise absent from release builds. ### 3. Tests follow the module tree [Section titled “3. Tests follow the module tree”](#3-tests-follow-the-module-tree) Because each source file is (or contains) a module, your tests naturally organize themselves the same way your code does. A crate split into `money` and `cart` modules ends up with `money::tests` and `cart::tests`, and the test names in the output reflect that path: src/lib.rs ```rust 1 pub mod money; 2 pub mod cart; ``` src/money.rs ```rust 1 #[derive(Debug, Clone, Copy, PartialEq, Eq)] 2 pub struct Cents(pub u64); 3 4 impl Cents { 5 /// Apply a whole-percent discount, rounding down. 6 pub fn discounted(self, percent: u8) -> Cents { 7 let kept = 100u64.saturating_sub(percent as u64); 8 Cents(self.0 * kept / 100) 9 } 10 } 11 12 #[cfg(test)] 13 mod tests { 14 use super::*; 15 16 #[test] 17 fn ten_percent_off() { 18 assert_eq!(Cents(1000).discounted(10), Cents(900)); 19 } 20 21 #[test] 22 fn rounds_down() { 23 assert_eq!(Cents(999).discounted(10), Cents(899)); 24 } 25 } ``` src/cart.rs ```rust 1 use crate::money::Cents; 2 3 /// Sum the line items in a cart. 4 pub fn subtotal(line_items: &[Cents]) -> Cents { 5 Cents(line_items.iter().map(|c| c.0).sum()) 6 } 7 8 #[cfg(test)] 9 mod tests { 10 use super::*; 11 12 #[test] 13 fn sums_line_items() { 14 let items = [Cents(500), Cents(250), Cents(125)]; 15 assert_eq!(subtotal(&items), Cents(875)); 16 } 17 18 #[test] 19 fn empty_cart_is_zero() { 20 assert_eq!(subtotal(&[]), Cents(0)); 21 } 22 } ``` `cargo test` reports each test under its module path, so you always know where a failing test lives: ```text 1 running 4 tests 2 test cart::tests::empty_cart_is_zero ... ok 3 test cart::tests::sums_line_items ... ok 4 test money::tests::rounds_down ... ok 5 test money::tests::ten_percent_off ... ok 6 7 test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` > **Tip:** You can run just one module’s tests with a filter: `cargo test money::` runs only `money::tests::*`. The filter is a substring match against the full test path. ### 4. Binary crates test the same way [Section titled “4. Binary crates test the same way”](#4-binary-crates-test-the-same-way) A binary crate (`src/main.rs`) uses the identical pattern — a `#[cfg(test)] mod tests` with `use super::*` works in `main.rs` just as it does in `lib.rs`: src/main.rs ```rust 1 fn celsius_to_fahrenheit(c: f64) -> f64 { 2 c * 9.0 / 5.0 + 32.0 3 } 4 5 fn main() { 6 println!("{}", celsius_to_fahrenheit(100.0)); 7 } 8 9 #[cfg(test)] 10 mod tests { 11 use super::*; 12 13 #[test] 14 fn boiling_point() { 15 assert_eq!(celsius_to_fahrenheit(100.0), 212.0); 16 } 17 18 #[test] 19 fn freezing_point() { 20 assert_eq!(celsius_to_fahrenheit(0.0), 32.0); 21 } 22 } ``` ```text 1 running 2 tests 2 test tests::boiling_point ... ok 3 test tests::freezing_point ... ok 4 5 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` > **Note:** Integration tests in `tests/` can only link a **library** crate (`src/lib.rs`), not a binary’s internals. A common production layout is to keep all logic in `src/lib.rs` and make `src/main.rs` a thin wrapper that calls into it. That way both unit tests *and* integration tests can exercise the real code. See [Integration Tests](/13-testing/04-integration-tests/). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Trying to test a private function from `tests/` [Section titled “Pitfall 1: Trying to test a private function from tests/”](#pitfall-1-trying-to-test-a-private-function-from-tests) A TypeScript developer’s instinct is “tests go in a separate place.” If you put a test that needs internals into the `tests/` directory, it is a separate crate and can only see your public API. ```rust 1 // tests/api.rs — an EXTERNAL crate linking your library 2 #[test] 3 fn cannot_reach_private_helper() { 4 // does not compile (error[E0603]: function `collapse_separators` is private) 5 let _ = my_crate::collapse_separators("a b"); 6 } ``` The real error from `cargo test --test api`: ```text 1 error[E0603]: function `collapse_separators` is private 2 --> tests/api.rs:8:20 3 | 4 8 | let _ = probe::collapse_separators("a b"); 5 | ^^^^^^^^^^^^^^^^^^^ private function 6 | 7 note: the function `collapse_separators` is defined here 8 --> src/lib.rs:10:1 9 | 10 10 | fn collapse_separators(input: &str) -> String { 11 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``` **Fix:** put tests that need internals in a `#[cfg(test)] mod tests` *inside* the source file. Keep `tests/` for black-box testing of the public API. ### Pitfall 2: Forgetting `use super::*` [Section titled “Pitfall 2: Forgetting use super::\*”](#pitfall-2-forgetting-use-super) The test module is a *child*; it does not automatically see the parent’s items. Omit the import and you get unresolved-name errors: ```rust 1 pub fn double(n: i32) -> i32 { 2 n * 2 3 } 4 5 #[cfg(test)] 6 mod tests { 7 // Missing: use super::*; 8 #[test] 9 fn doubles() { 10 // does not compile (error[E0425]: cannot find function `double` in this scope) 11 assert_eq!(double(21), 42); 12 } 13 } ``` **Fix:** add `use super::*;` as the first line inside `mod tests`. ### Pitfall 3: A test helper placed outside `#[cfg(test)]` [Section titled “Pitfall 3: A test helper placed outside #\[cfg(test)\]”](#pitfall-3-a-test-helper-placed-outside-cfgtest) If you write a helper function used *only* by tests but forget to gate it behind `#[cfg(test)]`, the compiler includes it in normal builds and warns that it is unused dead code: ```rust 1 pub fn double(n: i32) -> i32 { 2 n * 2 3 } 4 5 // Helper only used by tests, but NOT gated behind #[cfg(test)]. 6 fn test_input() -> i32 { 7 21 8 } 9 10 #[cfg(test)] 11 mod tests { 12 use super::*; 13 #[test] 14 fn doubles() { 15 assert_eq!(double(test_input()), 42); 16 } 17 } ``` A plain `cargo build` (not `cargo test`) reports: ```text 1 warning: function `test_input` is never used 2 --> src/lib.rs:6:4 3 | 4 6 | fn test_input() -> i32 { 5 | ^^^^^^^^^^ 6 | 7 = note: `#[warn(dead_code)]` on by default 8 9 warning: `probe` (lib) generated 1 warning ``` **Fix:** put test-only helpers *inside* the `#[cfg(test)] mod tests` block (or in another `#[cfg(test)]`-gated module). Anything inside the test module is automatically excluded from non-test builds, so it never triggers a dead-code warning. ### Pitfall 4: Expecting Jest-style config and file globs [Section titled “Pitfall 4: Expecting Jest-style config and file globs”](#pitfall-4-expecting-jest-style-config-and-file-globs) There is no `cargo` equivalent of `jest.config.js` or `testMatch`. Cargo discovers tests by convention: `#[test]` functions anywhere in the crate, every file in `tests/`, and doc examples. You do not register them or configure a glob. If a test is not running, the cause is almost always a missing `#[test]` attribute or a `mod` that is not declared, not a misconfigured matcher. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Default to a `#[cfg(test)] mod tests` at the bottom of each source file.** Keep the tests next to the code they verify so they move, rename, and get deleted together. * **Always start the module with `use super::*;`.** It is the one place a glob import is idiomatic in Rust. * **Test private functions where it pays off.** You *can* reach internals — use that to test tricky helpers in isolation. But prefer testing through the public API when you can, so tests survive internal refactors. * **Keep test-only code inside the `cfg(test)` boundary.** Helpers, fixtures, fake data builders — all of it goes behind `#[cfg(test)]` so it never bloats your release build. For shared setup, see [Test Fixtures](/13-testing/05-test-fixtures/). * **Mirror your module structure.** Let each module own its own `tests` submodule rather than collecting everything into one giant test file. The module-path test names keep failures easy to locate. * **Push logic into `src/lib.rs` and keep `src/main.rs` thin.** This lets both unit tests and `tests/` integration tests exercise the same code. See [Integration Tests](/13-testing/04-integration-tests/). * **Put test-only dependencies in `[dev-dependencies]`.** Crates like `proptest` or `mockall` belong there, not in `[dependencies]`, so they are absent from production builds. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A common production pattern: a library crate where each module carries its own unit tests for private invariants, plus a `tests/` directory that exercises only the public API. Here is the full layout of an `inventory` crate. ```text 1 inventory/ 2 ├── Cargo.toml 3 ├── src/ 4 │ ├── lib.rs # module declarations + public re-exports 5 │ ├── sku.rs # SKU validation (private parser + unit tests) 6 │ └── warehouse.rs # stock logic (unit tests for private helpers) 7 └── tests/ 8 └── public_api.rs # black-box tests against the public API only ``` src/lib.rs ```rust 1 //! Inventory management. 2 3 pub mod sku; 4 pub mod warehouse; 5 6 // Re-export the headline types so callers write `inventory::Sku`. 7 pub use sku::Sku; 8 pub use warehouse::Warehouse; ``` src/sku.rs ```rust 1 /// A validated stock-keeping unit, e.g. "ABC-12345". 2 #[derive(Debug, Clone, PartialEq, Eq)] 3 pub struct Sku(String); 4 5 impl Sku { 6 /// Parse a raw SKU string. (public API) 7 pub fn parse(raw: &str) -> Option<Sku> { 8 let normalized = raw.trim().to_uppercase(); 9 if is_well_formed(&normalized) { 10 Some(Sku(normalized)) 11 } else { 12 None 13 } 14 } 15 16 pub fn as_str(&self) -> &str { 17 &self.0 18 } 19 } 20 21 // Private: the SKU grammar. Tested directly below. 22 fn is_well_formed(s: &str) -> bool { 23 let (prefix, digits) = match s.split_once('-') { 24 Some(parts) => parts, 25 None => return false, 26 }; 27 prefix.len() == 3 28 && prefix.chars().all(|c| c.is_ascii_uppercase()) 29 && digits.len() == 5 30 && digits.chars().all(|c| c.is_ascii_digit()) 31 } 32 33 #[cfg(test)] 34 mod tests { 35 use super::*; 36 37 #[test] 38 fn parse_normalizes_case_and_whitespace() { 39 let sku = Sku::parse(" abc-12345 ").unwrap(); 40 assert_eq!(sku.as_str(), "ABC-12345"); 41 } 42 43 #[test] 44 fn parse_rejects_malformed_input() { 45 assert_eq!(Sku::parse("AB-12345"), None); // prefix too short 46 assert_eq!(Sku::parse("ABC-1234"), None); // too few digits 47 assert_eq!(Sku::parse("ABCD12345"), None); // missing dash 48 } 49 50 // Unit-test the PRIVATE grammar directly. 51 #[test] 52 fn well_formed_grammar() { 53 assert!(is_well_formed("XYZ-00001")); 54 assert!(!is_well_formed("xyz-00001")); // lowercase rejected pre-normalization 55 assert!(!is_well_formed("XYZ-0000A")); // non-digit 56 } 57 } ``` src/warehouse.rs ```rust 1 use crate::sku::Sku; 2 use std::collections::HashMap; 3 4 /// Tracks on-hand quantity per SKU. 5 #[derive(Debug, Default)] 6 pub struct Warehouse { 7 stock: HashMap<String, u32>, 8 } 9 10 impl Warehouse { 11 pub fn new() -> Warehouse { 12 Warehouse::default() 13 } 14 15 /// Add `qty` units of `sku`. (public API) 16 pub fn receive(&mut self, sku: &Sku, qty: u32) { 17 let entry = self.stock.entry(sku.as_str().to_string()).or_insert(0); 18 *entry = saturating_total(*entry, qty); 19 } 20 21 /// Current quantity on hand. (public API) 22 pub fn quantity(&self, sku: &Sku) -> u32 { 23 self.stock.get(sku.as_str()).copied().unwrap_or(0) 24 } 25 } 26 27 // Private helper: total that never overflows u32. 28 fn saturating_total(current: u32, added: u32) -> u32 { 29 current.saturating_add(added) 30 } 31 32 #[cfg(test)] 33 mod tests { 34 use super::*; 35 36 fn sku(s: &str) -> Sku { 37 Sku::parse(s).expect("test SKU should be valid") 38 } 39 40 #[test] 41 fn receiving_accumulates() { 42 let mut wh = Warehouse::new(); 43 let item = sku("ABC-12345"); 44 wh.receive(&item, 10); 45 wh.receive(&item, 5); 46 assert_eq!(wh.quantity(&item), 15); 47 } 48 49 #[test] 50 fn private_total_saturates() { 51 assert_eq!(saturating_total(u32::MAX, 1), u32::MAX); 52 } 53 } ``` ```rust 1 // tests/public_api.rs — separate crate; PUBLIC API only. 2 use inventory::{Sku, Warehouse}; 3 4 #[test] 5 fn end_to_end_receiving_flow() { 6 let mut wh = Warehouse::new(); 7 let widget = Sku::parse("WID-00042").expect("valid SKU"); 8 9 wh.receive(&widget, 3); 10 wh.receive(&widget, 7); 11 12 assert_eq!(wh.quantity(&widget), 10); 13 14 // `is_well_formed` and `saturating_total` are private and simply 15 // do not exist from out here — this crate cannot name them. 16 } ``` The unit tests in `sku.rs` and `warehouse.rs` lock down the private parsing grammar and the saturating arithmetic: internal invariants a black-box test could never reach. The `tests/public_api.rs` file verifies the *contract* a consumer of the crate sees. Together they give you fine-grained coverage of internals and confidence that the public surface behaves, without ever widening the API for the sake of testability. > **Note:** The helper `fn sku(...)` inside `warehouse::tests` is a fixture-style constructor. Because it lives inside the `#[cfg(test)]` module, it is compiled only for tests and never warns as unused. Setup and teardown patterns like this are explored further in [Test Fixtures](/13-testing/05-test-fixtures/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [The Rust Book — Test Organization](https://doc.rust-lang.org/book/ch11-03-test-organization.html) — the canonical explanation of unit vs. integration tests. * [The Rust Book — How to Write Tests](https://doc.rust-lang.org/book/ch11-01-writing-tests.html) — the `#[test]` and `#[cfg(test)]` basics. * [The Rust Reference — Conditional compilation (`cfg`)](https://doc.rust-lang.org/reference/conditional-compilation.html) — what `#[cfg(test)]` actually does. * [Cargo Book — Tests](https://doc.rust-lang.org/cargo/reference/cargo-targets.html#tests) — how Cargo discovers and builds test targets. **Related sections of this guide:** * [Unit Tests](/13-testing/00-unit-tests/): writing `#[test]` functions and running `cargo test`. * [Integration Tests](/13-testing/04-integration-tests/): the `tests/` directory and black-box testing. * [Documentation Tests](/13-testing/09-doc-tests/): runnable examples in `///` comments. * [Test Fixtures](/13-testing/05-test-fixtures/): setup/teardown and shared test state. * [Modules](/12-modules-packages/00-modules/): visibility, `pub`/`pub(crate)`, and the module tree that this whole convention rests on. * [Cargo and Crates](/12-modules-packages/04-cargo/): `[dev-dependencies]` and crate structure. * [Macros](/14-macros/): how attributes like `#[test]` and `#[cfg(...)]` fit into Rust’s macro and attribute system. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Move tests into a `tests` submodule [Section titled “Exercise 1: Move tests into a tests submodule”](#exercise-1-move-tests-into-a-tests-submodule) **Difficulty:** Easy **Objective:** Practice the basic `#[cfg(test)] mod tests` layout and the `use super::*` import. **Instructions:** You are given a function and a loose `#[test]` function. Wrap the test in a proper `#[cfg(test)] mod tests` submodule so it is excluded from non-test builds and follows convention. ```rust 1 pub fn is_palindrome(s: &str) -> bool { 2 let cleaned: String = s.chars().filter(|c| c.is_alphanumeric()).collect(); 3 let lowered = cleaned.to_lowercase(); 4 lowered.chars().eq(lowered.chars().rev()) 5 } 6 7 // TODO: move this into a proper `#[cfg(test)] mod tests` submodule. 8 #[test] 9 fn detects_palindrome() { 10 assert!(is_palindrome("Race car")); 11 } ``` Solution ```rust 1 pub fn is_palindrome(s: &str) -> bool { 2 let cleaned: String = s.chars().filter(|c| c.is_alphanumeric()).collect(); 3 let lowered = cleaned.to_lowercase(); 4 lowered.chars().eq(lowered.chars().rev()) 5 } 6 7 #[cfg(test)] 8 mod tests { 9 use super::*; 10 11 #[test] 12 fn detects_palindrome() { 13 assert!(is_palindrome("Race car")); 14 } 15 16 #[test] 17 fn rejects_non_palindrome() { 18 assert!(!is_palindrome("hello")); 19 } 20 } ``` Running `cargo test`: ```text 1 running 2 tests 2 test tests::detects_palindrome ... ok 3 test tests::rejects_non_palindrome ... ok 4 5 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` ### Exercise 2: Test a private function [Section titled “Exercise 2: Test a private function”](#exercise-2-test-a-private-function) **Difficulty:** Medium **Objective:** Exploit the child-module privilege to test an internal helper that is *not* part of the public API. **Instructions:** The crate exposes `public fn normalize_phone` but the digit-extraction logic lives in a private `digits_only` helper. Add a `#[cfg(test)] mod tests` that tests **both** the public function and the private `digits_only` helper directly. Do **not** add `pub` to `digits_only`. ```rust 1 /// Strip a phone number down to its digits and format it. (public API) 2 pub fn normalize_phone(raw: &str) -> Option<String> { 3 let digits = digits_only(raw); 4 if digits.len() == 10 { 5 Some(format!( 6 "({}) {}-{}", 7 &digits[0..3], 8 &digits[3..6], 9 &digits[6..10] 10 )) 11 } else { 12 None 13 } 14 } 15 16 // Private helper. 17 fn digits_only(raw: &str) -> String { 18 raw.chars().filter(|c| c.is_ascii_digit()).collect() 19 } 20 21 // TODO: add a tests submodule that tests BOTH functions. ``` Solution ```rust 1 /// Strip a phone number down to its digits and format it. (public API) 2 pub fn normalize_phone(raw: &str) -> Option<String> { 3 let digits = digits_only(raw); 4 if digits.len() == 10 { 5 Some(format!( 6 "({}) {}-{}", 7 &digits[0..3], 8 &digits[3..6], 9 &digits[6..10] 10 )) 11 } else { 12 None 13 } 14 } 15 16 fn digits_only(raw: &str) -> String { 17 raw.chars().filter(|c| c.is_ascii_digit()).collect() 18 } 19 20 #[cfg(test)] 21 mod tests { 22 use super::*; 23 24 #[test] 25 fn formats_valid_number() { 26 assert_eq!( 27 normalize_phone("415-867-5309"), 28 Some("(415) 867-5309".to_string()) 29 ); 30 } 31 32 #[test] 33 fn rejects_wrong_length() { 34 assert_eq!(normalize_phone("12345"), None); 35 } 36 37 // Testing the PRIVATE helper directly — only possible from inside the crate. 38 #[test] 39 fn digits_only_strips_punctuation() { 40 assert_eq!(digits_only("(415) 867-5309"), "4158675309"); 41 assert_eq!(digits_only("no digits here"), ""); 42 } 43 } ``` Running `cargo test`: ```text 1 running 3 tests 2 test tests::digits_only_strips_punctuation ... ok 3 test tests::formats_valid_number ... ok 4 test tests::rejects_wrong_length ... ok 5 6 test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` ### Exercise 3: Split unit tests and integration tests [Section titled “Exercise 3: Split unit tests and integration tests”](#exercise-3-split-unit-tests-and-integration-tests) **Difficulty:** Hard **Objective:** Decide which test belongs where, given the public/private boundary, and lay out a crate accordingly. **Instructions:** Build a `temperature` library crate with: 1. A public `c_to_f(celsius: f64) -> f64`. 2. A **private** `round1(x: f64) -> f64` that rounds to one decimal place. 3. A public `c_to_f_rounded(celsius: f64) -> f64` that combines them. Then write: * **Unit tests** (in `src/lib.rs`) that cover `c_to_f` *and* the private `round1`. * An **integration test** (in `tests/public_api.rs`) that exercises `c_to_f_rounded` from the outside. Confirm the integration test cannot name `round1`. Solution src/lib.rs ```rust 1 //! Temperature conversion library. 2 3 /// Convert Celsius to Fahrenheit. (public API) 4 pub fn c_to_f(celsius: f64) -> f64 { 5 celsius * 9.0 / 5.0 + 32.0 6 } 7 8 /// Round to one decimal place. (private helper) 9 fn round1(x: f64) -> f64 { 10 (x * 10.0).round() / 10.0 11 } 12 13 /// Convert and round in one step. (public API) 14 pub fn c_to_f_rounded(celsius: f64) -> f64 { 15 round1(c_to_f(celsius)) 16 } 17 18 #[cfg(test)] 19 mod tests { 20 use super::*; 21 22 #[test] 23 fn boiling() { 24 assert_eq!(c_to_f(100.0), 212.0); 25 } 26 27 // Testing the PRIVATE helper directly. 28 #[test] 29 fn rounds_to_one_place() { 30 assert_eq!(round1(98.347), 98.3); 31 } 32 } ``` ```rust 1 // tests/public_api.rs — separate crate, PUBLIC API only. 2 #[test] 3 fn rounded_conversion_via_public_api() { 4 assert_eq!(temperature::c_to_f_rounded(37.0), 98.6); 5 } 6 7 // Uncommenting the next line fails to compile with 8 // error[E0603]: function `round1` is private — the integration crate 9 // cannot see private items. 10 // let _ = temperature::round1(1.23); ``` Running `cargo test` runs both the unit tests and the integration test: ```text 1 running 2 tests 2 test tests::boiling ... ok 3 test tests::rounds_to_one_place ... ok 4 5 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s 6 7 running 1 test 8 test rounded_conversion_via_public_api ... ok 9 10 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s ``` The private `round1` is verified by a unit test inside the crate, while the public `c_to_f_rounded` is verified by a black-box integration test. That is the canonical division of labor: **unit tests for internals, integration tests for the contract.** # Assertions: `assert!`, `assert_eq!`, and `assert_ne!` > Rust's assert!, assert_eq! and assert_ne! replace Jest's expect matchers: a failure panics with both values, needs no import, and relies on Debug and PartialEq. Assertions are the checks inside your tests that decide pass or fail. Rust ships three built-in assertion macros that cover almost everything you reach for `expect(...).toBe(...)` for in Jest or Vitest, with a key twist: when an assertion fails, Rust **panics** and prints a precise, value-rich report instead of throwing a JavaScript exception. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Rust’s standard library provides `assert!`, `assert_eq!`, and `assert_ne!`: no matcher library, no `import`, no setup. They are available everywhere because they live in the prelude. A failing assertion panics with the file, line, and the actual values involved, which is how a `#[test]` function is marked as failed. The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically, and these macros have been stable since Rust 1.0. > **Note:** This page covers the assertion macros themselves and how their failure output reads. For writing and running the surrounding tests, see [Unit Tests](/13-testing/00-unit-tests/); for asserting that code *panics on purpose*, see [Testing for Panics](/13-testing/03-should-panic/); for returning `Result` from a test and using `?`, also see [Testing for Panics](/13-testing/03-should-panic/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In Jest or Vitest you assert through a fluent **matcher** API: `expect(value)` returns an object, and you chain a matcher like `.toBe`, `.toEqual`, or `.toBeTruthy`. The matcher both performs the comparison and formats the diff when it fails. cart.ts ```typescript 1 export interface LineItem { 2 sku: string; 3 quantity: number; 4 } 5 6 export function slugify(title: string): string { 7 return title 8 .trim() 9 .toLowerCase() 10 .replace(/[^a-z0-9]+/g, "-") 11 .replace(/^-+|-+$/g, ""); 12 } 13 14 export function parsePort(raw: string): number | null { 15 const n = Number(raw.trim()); 16 return Number.isInteger(n) && n > 0 && n <= 65535 ? n : null; 17 } ``` ```typescript 1 // cart.test.ts (Vitest / Jest share this API) 2 import { describe, it, expect } from "vitest"; 3 import { slugify, parsePort } from "./cart"; 4 5 describe("slugify", () => { 6 it("lowercases and collapses separators", () => { 7 expect(slugify(" Rust & TS ")).toBe("rust-ts"); 8 }); 9 10 it("rejects port 0", () => { 11 expect(parsePort("0")).toBeNull(); 12 // A custom message is the optional second arg to the matcher in Vitest: 13 expect(parsePort("8080"), "8080 should be a valid port").not.toBeNull(); 14 }); 15 }); ``` Key things to notice for the comparison below: * `expect(...).toBe(x)` is **reference/`Object.is` equality**; `expect(...).toEqual(x)` is **deep structural** equality. JavaScript devs constantly choose between them. * A failing matcher **throws**, which the test runner catches and reports. * Custom failure messages are matcher-specific second arguments (and not all matchers accept them). *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust collapses all of this into three macros. There is no `expect()` wrapper and no `.toBe` vs `.toEqual` distinction. `assert_eq!` always compares **by value** (via the `PartialEq` trait), which is the structural comparison you almost always want. src/lib.rs ```rust 1 pub fn slugify(title: &str) -> String { 2 title 3 .trim() 4 .to_lowercase() 5 .chars() 6 .map(|c| if c.is_alphanumeric() { c } else { '-' }) 7 .collect::<String>() 8 .split('-') 9 .filter(|s| !s.is_empty()) 10 .collect::<Vec<_>>() 11 .join("-") 12 } 13 14 pub fn parse_port(raw: &str) -> Option<u16> { 15 raw.trim().parse::<u16>().ok().filter(|&p| p > 0) 16 } 17 18 #[cfg(test)] 19 mod tests { 20 use super::*; 21 22 #[test] 23 fn slug_lowercases_and_collapses() { 24 assert_eq!(slugify(" Rust & TS "), "rust-ts"); 25 } 26 27 #[test] 28 fn port_rejects_zero() { 29 assert!(parse_port("0").is_none()); 30 // assert_ne! with an optional custom message (note the trailing args). 31 assert_ne!(parse_port("8080"), None, "8080 should be a valid port"); 32 } 33 } ``` Running `cargo test` reports each `#[test]` function: ```text 1 running 2 tests 2 test tests::port_rejects_zero ... ok 3 test tests::slug_lowercases_and_collapses ... ok 4 5 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` The three macros, at a glance: | Macro | Checks | Jest/Vitest analogue | | ------------------ | ---------------- | ---------------------------------------- | | `assert!(expr)` | `expr` is `true` | `expect(x).toBe(true)` / `.toBeTruthy()` | | `assert_eq!(a, b)` | `a == b` | `expect(a).toEqual(b)` | | `assert_ne!(a, b)` | `a != b` | `expect(a).not.toEqual(b)` | *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `assert!` takes a `bool`, not a “truthy” value [Section titled “assert! takes a bool, not a “truthy” value”](#assert-takes-a-bool-not-a-truthy-value) `assert!(cond)` panics unless `cond` is exactly the boolean `true`. This is the biggest mental shift from JavaScript: there is **no truthiness**. You cannot write `assert!(items.len())` hoping that a non-zero length counts as true. `items.len()` is a `usize`, and Rust will reject it at compile time: ```rust 1 #[cfg(test)] 2 mod tests { 3 #[test] 4 fn non_bool_assert() { 5 let count = 3; 6 assert!(count); // does not compile (error[E0308]: mismatched types) 7 } 8 } ``` The real compiler error: ```text 1 error[E0308]: mismatched types 2 --> src/lib.rs:6:9 3 | 4 6 | assert!(count); // does not compile (error[E0308]: mismatched types) 5 | ^^^^^^^^^^^^^^ expected `bool`, found integer 6 7 For more information about this error, try `rustc --explain E0308`. ``` You must write an explicit comparison: `assert!(count > 0)` or `assert!(count == 3)`. Unlike a JavaScript `if (count)`, this forces you to state what “true” means, which catches a whole category of “I meant `=== 0`” bugs. ### `assert_eq!` / `assert_ne!` print both sides on failure [Section titled “assert\_eq! / assert\_ne! print both sides on failure”](#assert_eq--assert_ne-print-both-sides-on-failure) The reason to prefer `assert_eq!(a, b)` over `assert!(a == b)` is the failure message. `assert!(a == b)` can only tell you “the expression was false.” `assert_eq!` knows both operands, so it prints them: ```rust 1 pub fn slugify(title: &str) -> String { 2 // BUG (intentional): does not collapse repeated separators. 3 title 4 .trim() 5 .to_lowercase() 6 .replace(|c: char| !c.is_alphanumeric(), "-") 7 } 8 9 #[cfg(test)] 10 mod tests { 11 use super::*; 12 13 #[test] 14 fn slug_collapses_separators() { 15 assert_eq!(slugify("Hello, World!"), "hello-world"); // fails at runtime 16 } 17 } ``` The real output from `cargo test`: ```text 1 running 1 test 2 test tests::slug_collapses_separators ... FAILED 3 4 failures: 5 6 ---- tests::slug_collapses_separators stdout ---- 7 8 thread 'tests::slug_collapses_separators' panicked at src/lib.rs:12:9: 9 assertion `left == right` failed 10 left: "hello--world-" 11 right: "hello-world" 12 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace 13 14 test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` `left` is the first argument (your computed value), `right` is the second (your expected value). The convention is **actual on the left, expected on the right**, mirroring `assert_eq!(got, want)`. Rust does not enforce this (the labels are literally `left`/`right`, not “actual”/“expected”), but staying consistent makes failures readable. ### A failed assertion is a panic, which is how a test fails [Section titled “A failed assertion is a panic, which is how a test fails”](#a-failed-assertion-is-a-panic-which-is-how-a-test-fails) There is no `throw`/`catch` here. `assert_eq!` expands to roughly “if the values differ, call `panic!` with this message.” The test harness runs each `#[test]` function, catches the panic via the unwinding machinery, and records the test as `FAILED`. That is the entire mechanism: assertions and `#[test]` are decoupled. You can even call these macros in non-test code (e.g. to enforce an invariant at startup), where a failure aborts the program. See [Panics](/08-error-handling/02-panic/) for how panicking works in general. ### Comparing requires `PartialEq`; printing the failure requires `Debug` [Section titled “Comparing requires PartialEq; printing the failure requires Debug”](#comparing-requires-partialeq-printing-the-failure-requires-debug) `assert_eq!(a, b)` needs to do two things when it fails: 1. **Compare** `a` and `b`, so both must implement the [`PartialEq`](https://doc.rust-lang.org/std/cmp/trait.PartialEq.html) trait (that is what the `==` operator dispatches to). 2. **Print** `a` and `b` in the failure message, so both must implement [`Debug`](https://doc.rust-lang.org/std/fmt/trait.Debug.html), the formatter used by `{:?}`. For your own structs and enums, you get both with a one-line derive. This is the single most important habit for testing custom types in Rust: ```rust 1 #[derive(Debug, PartialEq)] 2 pub struct LineItem { 3 pub sku: String, 4 pub quantity: u32, 5 } 6 7 pub fn parse_line(raw: &str) -> Option<LineItem> { 8 let (sku, qty) = raw.split_once('x')?; 9 Some(LineItem { 10 sku: sku.trim().to_string(), 11 quantity: qty.trim().parse().ok()?, 12 }) 13 } 14 15 #[cfg(test)] 16 mod tests { 17 use super::*; 18 19 #[test] 20 fn parses_line_item() { 21 let got = parse_line("WIDGET x 3").unwrap(); 22 // Expected quantity is wrong on purpose to show the diff. 23 assert_eq!( 24 got, 25 LineItem { sku: "WIDGET".to_string(), quantity: 5 } 26 ); // fails at runtime 27 } 28 } ``` Because `LineItem` derives `Debug`, the failure prints the full structures, not just “not equal”: ```text 1 thread 'tests::parses_line_item' panicked at src/lib.rs:23:9: 2 assertion `left == right` failed 3 left: LineItem { sku: "WIDGET", quantity: 3 } 4 right: LineItem { sku: "WIDGET", quantity: 5 } ``` This is the equivalent of Jest’s structural diff for objects, except you opt into it explicitly with `#[derive(Debug)]`. Unlike TypeScript, where `console.log(obj)` and matcher diffs work on any value reflectively, Rust has no runtime reflection: the `Debug` impl is generated at compile time, and a type without it simply cannot be auto-printed. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript (Jest/Vitest) | Rust | | ------------------------- | ------------------------------------------ | -------------------------------------------------------- | | API shape | Fluent `expect(x).matcher(y)` | Macros `assert_eq!(x, y)` (no wrapper object) | | Import needed | `import { expect } from "vitest"` | None — in the prelude, always available | | Equality kinds | `toBe` (Object.is) vs `toEqual` (deep) | One `assert_eq!`, always by value via `PartialEq` | | Truthiness | `expect(x).toBeTruthy()` accepts any value | `assert!` requires a real `bool` (no truthiness) | | Failure mechanism | Throws an `Error` the runner catches | Panics; the harness records the panic as a failure | | Printing values | Reflective, automatic for any object | Needs `Debug` (usually `#[derive(Debug)]`) | | Comparing custom types | Automatic deep compare | Needs `PartialEq` (usually `#[derive(PartialEq)]`) | | Custom message | Matcher-specific extra argument | Trailing `format!`-style args on any of the three macros | | Approximate float compare | `expect(x).toBeCloseTo(y)` | No built-in; compare `(x - y).abs() < eps` yourself | The deepest conceptual difference: in JavaScript the matcher library does the heavy lifting at runtime, inspecting arbitrary values reflectively. In Rust the work is split between **traits resolved at compile time** (`PartialEq` for comparing, `Debug` for printing) and a tiny macro that wires them into a `panic!`. If a type doesn’t implement those traits, the test does not compile: the failure moves from runtime to compile time, which is the recurring Rust theme. *** ## Custom Failure Messages [Section titled “Custom Failure Messages”](#custom-failure-messages) All three macros accept optional trailing arguments after the values, using the exact same syntax as [`println!`](/02-basics/04-output/) — a format string plus interpolated values. This is the analogue of a Jest custom matcher message, and it is appended to the standard report rather than replacing it. ```rust 1 pub fn discount_price(price: f64, percent_off: f64) -> f64 { 2 price * (1.0 - percent_off / 100.0) 3 } 4 5 #[cfg(test)] 6 mod tests { 7 use super::*; 8 9 #[test] 10 fn plain_assert_fails() { 11 let total = discount_price(100.0, 25.0); 12 assert!(total < 50.0); // false: total is 75.0 13 } 14 15 #[test] 16 fn custom_message_assert() { 17 let total = discount_price(100.0, 25.0); 18 assert!( 19 total < 50.0, 20 "expected discounted total under 50, got {total}" 21 ); // fails with the custom message 22 } 23 24 #[test] 25 fn custom_message_eq() { 26 let users = vec!["alice", "bob"]; 27 assert_eq!( 28 users.len(), 29 3, 30 "roster should have 3 members but had {}: {:?}", 31 users.len(), 32 users 33 ); // fails with the custom message 34 } 35 } ``` The real output shows how a bare `assert!` is the *least* informative, and how the custom message rides along with `assert_eq!`’s automatic `left`/`right` dump: ```text 1 ---- tests::custom_message_eq stdout ---- 2 thread 'tests::custom_message_eq' panicked at src/lib.rs:27:9: 3 assertion `left == right` failed: roster should have 3 members but had 2: ["alice", "bob"] 4 left: 2 5 right: 3 6 7 ---- tests::custom_message_assert stdout ---- 8 thread 'tests::custom_message_assert' panicked at src/lib.rs:18:9: 9 expected discounted total under 50, got 75 10 11 ---- tests::plain_assert_fails stdout ---- 12 thread 'tests::plain_assert_fails' panicked at src/lib.rs:12:9: 13 assertion failed: total < 50.0 ``` Notice that the bare `assert!(total < 50.0)` can only echo the *source text* of the condition (`total < 50.0`); it cannot show that `total` was `75`. That is exactly when a custom message earns its keep: for `assert!`, include the runtime value in the message so a failure is debuggable. > **Tip:** The format string uses inline captures like `{total}` for variables in scope (stable since Rust 1.58). Use `{:?}` (Debug) for collections and structs, and positional `{}` for values you pass explicitly. Avoid the old redundant `format!("{x}", x = x)` style. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Forgetting `#[derive(PartialEq)]` on a compared type [Section titled “Forgetting #\[derive(PartialEq)\] on a compared type”](#forgetting-derivepartialeq-on-a-compared-type) If you `assert_eq!` two values of a type that can’t be compared with `==`, the error is about the missing trait, not about the assertion: ```rust 1 #[derive(Debug)] // has Debug, but NO PartialEq 2 pub struct Point { 3 pub x: i32, 4 pub y: i32, 5 } 6 7 #[cfg(test)] 8 mod tests { 9 use super::*; 10 11 #[test] 12 fn points_equal() { 13 let a = Point { x: 1, y: 2 }; 14 let b = Point { x: 1, y: 2 }; 15 assert_eq!(a, b); // does not compile (error[E0369]) 16 } 17 } ``` The real compiler error tells you precisely what to add: ```text 1 error[E0369]: binary operation `==` cannot be applied to type `Point` 2 --> src/lib.rs:15:9 3 | 4 15 | assert_eq!(a, b); // does not compile (error[E0369]) 5 | ^^^^^^^^^^^^^^^^ 6 | | 7 | Point 8 | Point 9 | 10 note: an implementation of `PartialEq` might be missing for `Point` 11 help: consider annotating `Point` with `#[derive(PartialEq)]` ``` ### Forgetting `#[derive(Debug)]` (so the failure can’t be printed) [Section titled “Forgetting #\[derive(Debug)\] (so the failure can’t be printed)”](#forgetting-derivedebug-so-the-failure-cant-be-printed) This is the more confusing one, because the type compares fine; the error only appears because the *failure message* needs to print the values. If `Point` derives `PartialEq` but not `Debug`: ```text 1 error[E0277]: `Point` doesn't implement `Debug` 2 --> src/lib.rs:15:9 3 | 4 15 | assert_eq!(a, b); // does not compile (error[E0277]) 5 | ^^^^^^^^^^^^^^^^ the trait `Debug` is not implemented for `Point` 6 | 7 = note: add `#[derive(Debug)]` to `Point` or manually `impl Debug for Point` 8 help: consider annotating `Point` with `#[derive(Debug)]` ``` The fix for both pitfalls is the same single line you should make a reflex on any type you test: `#[derive(Debug, PartialEq)]`. ### Comparing floats with `assert_eq!` [Section titled “Comparing floats with assert\_eq!”](#comparing-floats-with-assert_eq) JavaScript devs know `0.1 + 0.2 !== 0.3`, but it is easy to forget when reaching for `assert_eq!`. Rust uses the same IEEE-754 `f64`, so exact equality fails the same way: ```rust 1 pub fn add(a: f64, b: f64) -> f64 { 2 a + b 3 } 4 5 #[cfg(test)] 6 mod tests { 7 use super::*; 8 9 #[test] 10 fn naive_float_eq() { 11 assert_eq!(add(0.1, 0.2), 0.3); // fails: not exactly 0.3 12 } 13 14 #[test] 15 fn epsilon_compare() { 16 let got = add(0.1, 0.2); 17 let want = 0.3; 18 assert!( 19 (got - want).abs() < 1e-10, 20 "expected ~{want}, got {got} (diff {})", 21 (got - want).abs() 22 ); 23 } 24 } ``` The naive test fails exactly as it would in Node, and the epsilon test passes: ```text 1 running 2 tests 2 test tests::epsilon_compare ... ok 3 test tests::naive_float_eq ... FAILED 4 5 ---- tests::naive_float_eq stdout ---- 6 thread 'tests::naive_float_eq' panicked at src/lib.rs:12:9: 7 assertion `left == right` failed 8 left: 0.30000000000000004 9 right: 0.3 ``` Rust’s standard library deliberately has no `assert_approx_eq!`: compare against an epsilon yourself, or pull in a crate (see Best Practices). This is Jest’s `toBeCloseTo`, hand-rolled. ### Putting a stray comma where a custom message goes [Section titled “Putting a stray comma where a custom message goes”](#putting-a-stray-comma-where-a-custom-message-goes) `assert!(a == b,)` or `assert_eq!(a, b,)` with a trailing comma is fine, but `assert_eq!(a, b, c)` treats `c` as the **format string** of a custom message. If `c` isn’t a string literal you’ll get a format-string error, not the comparison you intended. The third positional argument is always the message, never a third value to compare. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Default to `assert_eq!`/`assert_ne!` over `assert!` for equality.** They print both operands; `assert!(a == b)` cannot. Reserve bare `assert!` for genuine boolean predicates (`assert!(cart.is_empty())`, `assert!(result.is_ok())`). * **Derive `Debug` and `PartialEq` on every type you assert on.** `#[derive(Debug, PartialEq)]` is idiomatic and free; without it your tests won’t compile. * **Order arguments as `(got, want)`** — actual first, expected second. The labels are only `left`/`right`, so consistency is on you, but it makes every failure read the same way. * **Put runtime values in `assert!` messages.** Since `assert!` can’t introspect operands, `assert!(n > 0, "n was {n}")` turns an opaque failure into an obvious one. * **For structs with many fields, consider the [`pretty_assertions`](https://crates.io/crates/pretty_assertions) crate** as a drop-in replacement. It overrides `assert_eq!`/`assert_ne!` to print a colored, line-by-line diff — much easier to scan than two long one-line `Debug` dumps. Add it as a dev-dependency: ```bash 1 cargo add pretty_assertions --dev ``` ```rust 1 #[derive(Debug, PartialEq)] 2 pub struct Config { 3 pub host: String, 4 pub port: u16, 5 pub tls: bool, 6 } 7 8 pub fn default_config() -> Config { 9 Config { host: "localhost".to_string(), port: 8080, tls: false } 10 } 11 12 #[cfg(test)] 13 mod tests { 14 use super::*; 15 use pretty_assertions::assert_eq; // shadow std's macro in this module only 16 17 #[test] 18 fn config_matches() { 19 assert_eq!( 20 default_config(), 21 Config { host: "localhost".to_string(), port: 9090, tls: true } 22 ); // fails with a diff 23 } 24 } ``` The failure highlights only the fields that differ (colors shown here as `<`/`>` markers): ```text 1 thread 'tests::config_matches' panicked at src/lib.rs:19:9: 2 assertion failed: `(left == right)` 3 4 Diff < left / right > : 5 Config { 6 host: "localhost", 7 < port: 8080, 8 < tls: false, 9 > port: 9090, 10 > tls: true, 11 } ``` * **There’s also `debug_assert!` / `debug_assert_eq!` / `debug_assert_ne!`.** These are identical but compile to nothing in release builds (`cargo build --release`). They are for invariants in *library code* that you don’t want to pay for in production, not generally for tests, since tests run in debug mode anyway. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small shopping-cart module with a test suite that uses all three macros, a custom message, and the `Debug, PartialEq` derive habit. This is the shape of a typical unit-test module living alongside the code it tests. ```rust 1 //! A tiny shopping-cart module demonstrating the assertion macros. 2 3 #[derive(Debug, Clone, PartialEq)] 4 pub struct LineItem { 5 pub sku: String, 6 pub unit_price_cents: u64, 7 pub quantity: u32, 8 } 9 10 #[derive(Debug, Default)] 11 pub struct Cart { 12 items: Vec<LineItem>, 13 } 14 15 impl Cart { 16 pub fn new() -> Self { 17 Cart::default() 18 } 19 20 /// Adds an item; merges quantity if the SKU already exists. 21 pub fn add(&mut self, sku: &str, unit_price_cents: u64, quantity: u32) { 22 if let Some(existing) = self.items.iter_mut().find(|i| i.sku == sku) { 23 existing.quantity += quantity; 24 } else { 25 self.items.push(LineItem { 26 sku: sku.to_string(), 27 unit_price_cents, 28 quantity, 29 }); 30 } 31 } 32 33 pub fn items(&self) -> &[LineItem] { 34 &self.items 35 } 36 37 pub fn total_cents(&self) -> u64 { 38 self.items 39 .iter() 40 .map(|i| i.unit_price_cents * i.quantity as u64) 41 .sum() 42 } 43 44 pub fn is_empty(&self) -> bool { 45 self.items.is_empty() 46 } 47 } 48 49 #[cfg(test)] 50 mod tests { 51 use super::*; 52 53 #[test] 54 fn new_cart_is_empty() { 55 let cart = Cart::new(); 56 assert!(cart.is_empty(), "a freshly constructed cart must be empty"); 57 assert_eq!(cart.total_cents(), 0); 58 } 59 60 #[test] 61 fn adding_distinct_items_keeps_them_separate() { 62 let mut cart = Cart::new(); 63 cart.add("APPLE", 50, 3); 64 cart.add("BREAD", 200, 1); 65 66 assert_eq!(cart.items().len(), 2); 67 assert_eq!(cart.total_cents(), 50 * 3 + 200); 68 } 69 70 #[test] 71 fn adding_same_sku_merges_quantity() { 72 let mut cart = Cart::new(); 73 cart.add("APPLE", 50, 3); 74 cart.add("APPLE", 50, 2); 75 76 assert_eq!( 77 cart.items().len(), 78 1, 79 "same SKU should merge into one line, got {:#?}", 80 cart.items() 81 ); 82 assert_eq!(cart.items()[0].quantity, 5); 83 assert_ne!(cart.total_cents(), 0); 84 } 85 } ``` All three tests pass: ```text 1 running 3 tests 2 test tests::adding_distinct_items_keeps_them_separate ... ok 3 test tests::adding_same_sku_merges_quantity ... ok 4 test tests::new_cart_is_empty ... ok 5 6 test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` Two details worth copying: `LineItem` derives `Debug, PartialEq` so it can appear in `assert_eq!`, and the merge test uses `{:#?}` (pretty Debug) in its custom message so that if the merge logic ever regresses, the failure dumps the full item list on multiple lines for easy reading. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`assert!` macro](https://doc.rust-lang.org/std/macro.assert.html) — official std documentation * [`assert_eq!` macro](https://doc.rust-lang.org/std/macro.assert_eq.html) and [`assert_ne!` macro](https://doc.rust-lang.org/std/macro.assert_ne.html) * [`debug_assert!` macro](https://doc.rust-lang.org/std/macro.debug_assert.html) — the release-stripped variants * [`PartialEq` trait](https://doc.rust-lang.org/std/cmp/trait.PartialEq.html) and [`Debug` trait](https://doc.rust-lang.org/std/fmt/trait.Debug.html) — the two traits assertions rely on * [The Rust Book: How to Write Tests](https://doc.rust-lang.org/book/ch11-01-writing-tests.html) * [`pretty_assertions` crate](https://crates.io/crates/pretty_assertions) — colored diffs for `assert_eq!` * Related sections in this guide: * [Unit Tests](/13-testing/00-unit-tests/) — the `#[test]` and `#[cfg(test)]` machinery these assertions live inside * [Testing for Panics](/13-testing/03-should-panic/) — `#[should_panic]` and `Result`-returning tests with `?` * [Test Organization](/13-testing/01-test-organization/) — where test modules belong * [Integration Tests](/13-testing/04-integration-tests/) — assertions in `tests/` against the public API * [Property Testing](/13-testing/07-property-testing/) — generating assertion inputs automatically with proptest * [Panics](/08-error-handling/02-panic/) — the panic mechanism a failing assertion uses * [Output and Formatting](/02-basics/04-output/) — the `{}`/`{:?}`/`{:#?}` format syntax custom messages share * [Macros](/14-macros/) — how `assert_eq!` and friends are implemented as macros *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Convert and compare [Section titled “Exercise 1: Convert and compare”](#exercise-1-convert-and-compare) **Difficulty:** Easy **Objective:** Practice all three macros, including an approximate float comparison. **Instructions:** 1. Write `celsius_to_fahrenheit(c: f64) -> f64` using the formula `c * 9/5 + 32`. 2. In a `#[cfg(test)] mod tests`, write one test that: * uses `assert_eq!` to check that `0.0 C` is exactly `32.0 F`, * uses `assert!` with an epsilon (`< 1e-9`) to check that `100.0 C` is about `212.0 F`, including a custom message that prints the actual value, * uses `assert_ne!` to confirm `37.0 C` is not `0.0 F`. Solution ```rust 1 pub fn celsius_to_fahrenheit(c: f64) -> f64 { 2 c * 9.0 / 5.0 + 32.0 3 } 4 5 #[cfg(test)] 6 mod tests { 7 use super::*; 8 9 #[test] 10 fn freezing_and_boiling() { 11 assert_eq!(celsius_to_fahrenheit(0.0), 32.0); 12 13 let boiling = celsius_to_fahrenheit(100.0); 14 assert!( 15 (boiling - 212.0).abs() < 1e-9, 16 "100C should be ~212F, got {boiling}" 17 ); 18 19 assert_ne!(celsius_to_fahrenheit(37.0), 0.0); 20 } 21 } ``` `0.0` and `100.0` happen to convert to values representable exactly, so `assert_eq!` is safe for freezing; in general prefer the epsilon form for float results, as the boiling check shows. ### Exercise 2: Assert on a custom type [Section titled “Exercise 2: Assert on a custom type”](#exercise-2-assert-on-a-custom-type) **Difficulty:** Medium **Objective:** Experience the `Debug` + `PartialEq` requirement firsthand and write a custom failure message. **Instructions:** 1. Define `struct Rgb { r: u8, g: u8, b: u8 }` and derive whatever traits you need to compare it in `assert_eq!`. 2. Write `parse_hex(code: &str) -> Option<Rgb>` that parses `"#RRGGBB"` (return `None` for a missing `#`, wrong length, or non-hex digits). 3. Write tests: one asserting `parse_hex("#FF8000")` equals `Some(Rgb { r: 255, g: 128, b: 0 })`, and one asserting several malformed inputs return `None`, each with a custom message saying which input failed. Solution ```rust 1 #[derive(Debug, PartialEq)] 2 pub struct Rgb { 3 pub r: u8, 4 pub g: u8, 5 pub b: u8, 6 } 7 8 pub fn parse_hex(code: &str) -> Option<Rgb> { 9 let hex = code.strip_prefix('#')?; 10 if hex.len() != 6 { 11 return None; 12 } 13 let r = u8::from_str_radix(&hex[0..2], 16).ok()?; 14 let g = u8::from_str_radix(&hex[2..4], 16).ok()?; 15 let b = u8::from_str_radix(&hex[4..6], 16).ok()?; 16 Some(Rgb { r, g, b }) 17 } 18 19 #[cfg(test)] 20 mod tests { 21 use super::*; 22 23 #[test] 24 fn parses_valid_hex() { 25 assert_eq!(parse_hex("#FF8000"), Some(Rgb { r: 255, g: 128, b: 0 })); 26 } 27 28 #[test] 29 fn rejects_bad_input() { 30 assert_eq!(parse_hex("FF8000"), None, "missing # should be rejected"); 31 assert_eq!(parse_hex("#FFF"), None, "wrong length should be rejected"); 32 assert!(parse_hex("#GG0000").is_none()); 33 } 34 } ``` Without `#[derive(Debug, PartialEq)]` on `Rgb`, the `assert_eq!` lines fail to compile (E0369 for the missing `PartialEq`, E0277 for the missing `Debug`). ### Exercise 3: Summary statistics with a structural assertion [Section titled “Exercise 3: Summary statistics with a structural assertion”](#exercise-3-summary-statistics-with-a-structural-assertion) **Difficulty:** Medium-Hard **Objective:** Combine `Option`, a derived struct, and a `{:#?}`-style failure message. **Instructions:** 1. Define `struct Stats { count: usize, sum: i64, max: i64 }` with the right derives. 2. Write `summarize(values: &[i64]) -> Option<Stats>` that returns `None` for an empty slice and otherwise computes count, sum, and max. 3. Write tests that: assert the fields for `&[3, 7, 2, 9]`, and assert that an empty slice yields `None` with a custom message explaining the expectation. Use `.expect(...)` to unwrap the non-empty case. Solution ```rust 1 #[derive(Debug, PartialEq)] 2 pub struct Stats { 3 pub count: usize, 4 pub sum: i64, 5 pub max: i64, 6 } 7 8 pub fn summarize(values: &[i64]) -> Option<Stats> { 9 if values.is_empty() { 10 return None; 11 } 12 Some(Stats { 13 count: values.len(), 14 sum: values.iter().sum(), 15 max: *values.iter().max().unwrap(), // safe: slice is non-empty here 16 }) 17 } 18 19 #[cfg(test)] 20 mod tests { 21 use super::*; 22 23 #[test] 24 fn summarizes_values() { 25 let stats = summarize(&[3, 7, 2, 9]).expect("non-empty slice should summarize"); 26 assert_eq!(stats.count, 4); 27 assert_eq!(stats.sum, 21); 28 assert_eq!(stats.max, 9); 29 } 30 31 #[test] 32 fn empty_slice_is_none() { 33 assert_eq!( 34 summarize(&[]), 35 None, 36 "empty input must produce None, not a zeroed Stats" 37 ); 38 } 39 } ``` You could also assert the whole struct at once with `assert_eq!(stats, Stats { count: 4, sum: 21, max: 9 })`. Thanks to the `PartialEq` derive, comparing the entire value in one assertion is idiomatic and gives the clearest diff on failure. # Testing Panics and Returning `Result` from Tests > Rust's #[should_panic(expected=...)] asserts a panic like Jest's toThrow, while Result-returning tests let ? propagate errors. Not every test is a simple “given input, assert output.” Sometimes the *correct* behavior is to fail loudly, and sometimes the test body itself is full of fallible steps. Rust gives you two dedicated tools for these cases: the `#[should_panic]` attribute and tests that return `Result<(), E>` so you can use the `?` operator. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In Jest or Vitest you assert that code throws with `expect(fn).toThrow(...)`, and you write fallible test bodies as `async` functions that `await` and let rejections bubble up. Rust splits these into two distinct mechanisms: a test marked **`#[should_panic(expected = "...")]`** passes only if its body **panics** with a message containing the expected substring, and a test whose signature is **`-> Result<(), E>`** lets you use the **`?` operator** so any `Err` cleanly fails the test instead of forcing a sea of `.unwrap()` calls. Knowing which to reach for is the difference between a test that documents a real invariant and one that quietly passes for the wrong reason. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In a Jest/Vitest suite, asserting that something throws and writing a fallible test body look like this: banking.ts ```typescript 1 export function withdraw(balance: number, amount: number): number { 2 if (amount > balance) { 3 throw new Error( 4 `insufficient funds: balance is ${balance}, tried to withdraw ${amount}`, 5 ); 6 } 7 return balance - amount; 8 } 9 10 // banking.test.ts 11 import { describe, it, expect } from "vitest"; 12 import { withdraw } from "./banking"; 13 14 describe("withdraw", () => { 15 // Asserting a throw. The matcher wraps the call in a try/catch for you. 16 it("rejects overdrafts", () => { 17 expect(() => withdraw(100, 150)).toThrow("insufficient funds"); 18 }); 19 20 it("succeeds within balance", () => { 21 expect(withdraw(100, 30)).toBe(70); 22 }); 23 24 // A fallible test body: the function is `async`, and any rejected promise 25 // (or thrown error) automatically fails the test. 26 it("loads and parses config", async () => { 27 const raw = await readFile("config.json", "utf8"); // may reject 28 const config = JSON.parse(raw); // may throw 29 expect(config.port).toBe(8080); 30 }); 31 }); ``` Two things are happening here. `expect(() => ...).toThrow(...)` passes the *function* (not its result) so the matcher can catch the throw itself, and it matches the error message as a substring. Separately, the `async` test body lets a rejected `await` or a thrown `JSON.parse` fail the test without any explicit error plumbing; the test runner treats a rejected promise as a failure. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust expresses the first case with the `#[should_panic]` attribute and the second with a `Result`-returning test signature: ```rust 1 use std::num::ParseIntError; 2 3 /// Withdraw `amount` from `balance`, panicking if it would overdraw. 4 pub fn withdraw(balance: u32, amount: u32) -> u32 { 5 if amount > balance { 6 panic!("insufficient funds: balance is {balance}, tried to withdraw {amount}"); 7 } 8 balance - amount 9 } 10 11 #[derive(Debug, PartialEq)] 12 pub struct Rgb { 13 pub r: u8, 14 pub g: u8, 15 pub b: u8, 16 } 17 18 /// Parse a `#rrggbb` hex color string. 19 pub fn parse_hex_color(s: &str) -> Result<Rgb, ParseIntError> { 20 let s = s.trim_start_matches('#'); 21 let r = u8::from_str_radix(&s[0..2], 16)?; 22 let g = u8::from_str_radix(&s[2..4], 16)?; 23 let b = u8::from_str_radix(&s[4..6], 16)?; 24 Ok(Rgb { r, g, b }) 25 } 26 27 #[cfg(test)] 28 mod tests { 29 use super::*; 30 31 // Asserting a panic, matching part of the message. 32 #[test] 33 #[should_panic(expected = "insufficient funds")] 34 fn overdraw_panics() { 35 withdraw(100, 150); 36 } 37 38 #[test] 39 fn withdraw_succeeds() { 40 assert_eq!(withdraw(100, 30), 70); 41 } 42 43 // A fallible test body: `?` propagates any `Err`, failing the test. 44 #[test] 45 fn parses_white() -> Result<(), ParseIntError> { 46 let color = parse_hex_color("#ffffff")?; 47 assert_eq!(color, Rgb { r: 255, g: 255, b: 255 }); 48 Ok(()) 49 } 50 } ``` Running `cargo test` produces: ```text 1 running 3 tests 2 test tests::parses_white ... ok 3 test tests::withdraw_succeeds ... ok 4 test tests::overdraw_panics - should panic ... ok 5 6 test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` The `- should panic` annotation in the runner output tells you the test was expected to panic and did. The `?` in `parses_white` is the direct analog of `await` in an async Jest test: if `parse_hex_color` returns an `Err`, the `?` returns it from the test function, and the runner marks the test failed. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `#[should_panic]` inverts the pass/fail condition [Section titled “#\[should\_panic\] inverts the pass/fail condition”](#should_panic-inverts-the-passfail-condition) A normal `#[test]` passes when its body runs to completion without panicking. Adding `#[should_panic]` **inverts** that contract: the test passes *only if* the body panics, and **fails if it returns normally**. The attribute is stacked below `#[test]`: ```rust 1 #[test] 2 #[should_panic] 3 fn overdraw_panics() { 4 withdraw(100, 150); // must panic, or the test fails 5 } ``` This is the analog of Jest’s `expect(fn).toThrow()` with no argument — “I don’t care about the message, just that it throws.” ### `expected` matches a substring, not the whole message [Section titled “expected matches a substring, not the whole message”](#expected-matches-a-substring-not-the-whole-message) The bare `#[should_panic]` is blunt: it passes if the body panics *for any reason at all*, which is dangerous (see Common Pitfalls). Add `expected = "..."` to require that the panic message **contains** that substring: ```rust 1 #[test] 2 #[should_panic(expected = "insufficient funds")] 3 fn overdraw_panics() { 4 withdraw(100, 150); 5 } ``` The check is a substring match (via `str::contains`), not an exact-equality or regex match, exactly like Jest’s `toThrow("...")` with a string argument. If the actual panic message does not contain the expected substring, the test fails and the runner prints both strings so you can see the mismatch. With our `withdraw` panicking on a `"account frozen"` expectation, the failure looks like this: ```text 1 thread 'tests::wrong_expected_substring' panicked at src/lib.rs:3:9: 2 insufficient funds: balance is 100, tried to withdraw 150 3 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace 4 note: panic did not contain expected string 5 panic message: "insufficient funds: balance is 100, tried to withdraw 150" 6 expected substring: "account frozen" ``` > **Tip:** Always prefer `#[should_panic(expected = "...")]` over the bare form. The expected string nails down *why* the code panicked, so the test cannot pass because of an unrelated panic (a typo’d array index, a different `unwrap` failing, and so on). ### `#[should_panic]` catches any panic, including `assert!` and overflow [Section titled “#\[should\_panic\] catches any panic, including assert! and overflow”](#should_panic-catches-any-panic-including-assert-and-overflow) The body just needs to panic. It does not matter whether the panic came from an explicit `panic!`, from a failed `assert!`/`assert_eq!`, from an `.unwrap()` on `None`, or from an arithmetic overflow in a debug build. For example, a panic raised by `assert!` is caught the same way: ```rust 1 pub fn checked_div(a: i32, b: i32) -> i32 { 2 assert!(b != 0, "division by zero is undefined"); 3 a / b 4 } 5 6 #[cfg(test)] 7 mod tests { 8 use super::*; 9 10 #[test] 11 #[should_panic(expected = "division by zero")] 12 fn divide_by_zero_panics() { 13 checked_div(10, 0); 14 } 15 } ``` ```text 1 running 1 test 2 test tests::divide_by_zero_panics - should panic ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` ### Tests can return `Result<(), E>` to use `?` [Section titled “Tests can return Result<(), E> to use ?”](#tests-can-return-result-e-to-use-) A test function may return `Result<(), E>` for any error type `E` that implements `Debug`. The runner treats `Ok(())` as a pass and any `Err(e)` as a failure, printing the error with its `Debug` representation. This lets you use the `?` operator inside the test body: ```rust 1 #[test] 2 fn parses_white() -> Result<(), ParseIntError> { 3 let color = parse_hex_color("#ffffff")?; // `?` returns Err on failure 4 assert_eq!(color, Rgb { r: 255, g: 255, b: 255 }); 5 Ok(()) // explicit success value is required 6 } ``` Without this feature you would have to write `parse_hex_color("#ffffff").unwrap()` on every fallible line. The `Result` return type lets you write the same straight-line “happy path” code you would write in the library itself. See [The `?` Operator](/08-error-handling/01-question-mark/) for the full mechanics of `?`. The error type can be anything `Debug`: a concrete error like `ParseIntError`, a custom enum, or the catch-all `Box<dyn std::error::Error>` when several different errors flow through one test. When such a test does fail, the `Debug` of the returned error is shown under the test’s name. A test that propagates a `ParseIntError` from invalid hex prints: ```text 1 running 1 test 2 test tests::rejects_garbage ... FAILED 3 4 failures: 5 6 ---- tests::rejects_garbage stdout ---- 7 Error: ParseIntError { kind: InvalidDigit } 8 9 10 failures: 11 tests::rejects_garbage 12 13 test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` > **Note:** `Result`-returning tests cannot be combined with `#[should_panic]`. The two model opposite outcomes: `#[should_panic]` says “this must panic,” while a `Result` test says “this must finish and return `Ok`.” A test that needs to assert an `Err` value should return `Result` *and* check the error explicitly (shown below), not use `#[should_panic]`. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concern | TypeScript (Jest/Vitest) | Rust | | ------------------------------ | --------------------------------------------------------- | ------------------------------------------------------------- | | Assert that code throws/panics | `expect(() => fn()).toThrow("msg")` | `#[should_panic(expected = "msg")]` on the test | | Pass a callback vs. run inline | Must wrap in `() => ...` so the matcher catches the throw | Body runs inline; the attribute inverts pass/fail | | Message matching | Substring (string arg) or regex (`/.../ `) | Substring only (`str::contains`); no regex | | Fallible test body | `async` test; rejected `await`/throw fails it | `-> Result<(), E>` lets `?` propagate `Err` | | Explicit success value | Implicit (test returns `undefined`) | Must end with `Ok(())` | | Assert on the error *value* | `try { ... } catch (e) { expect(e).toEqual(...) }` | Return `Result` and check `.unwrap_err()`, or `match` | | What “panic” / “throw” means | Any thrown value unwinds the stack | A `panic!` is an *unrecoverable* bug signal, not control flow | The single most important conceptual difference: in TypeScript, `throw` is an ordinary, expected control-flow mechanism — you `throw` to signal validation failures and `catch` to recover. In Rust, a **panic** signals an *unrecoverable bug* and is **not** how you report expected failures; recoverable failures return [`Result`](/08-error-handling/00-result-option/). So `#[should_panic]` is for testing genuine “this should be impossible” invariants (a precondition violation, an index out of bounds), whereas testing an *expected* failure (bad user input, a missing file) means asserting on a returned `Err`, not on a panic. See [Panicking](/08-error-handling/02-panic/) for the panic-vs-`Result` decision. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: bare `#[should_panic]` passing for the wrong reason [Section titled “Pitfall 1: bare #\[should\_panic\] passing for the wrong reason”](#pitfall-1-bare-should_panic-passing-for-the-wrong-reason) A test marked with the bare attribute passes if the body panics *for any reason*. If you later introduce a bug — say, an out-of-bounds index *before* the line you meant to test — the test still passes, hiding the regression. ```rust 1 #[test] 2 #[should_panic] // passes if ANY panic occurs, even an unrelated one 3 fn overdraw_panics() { 4 let accounts = vec![100u32]; 5 let _ = accounts[5]; // this panics first — test "passes" for the wrong reason! 6 withdraw(accounts[0], 150); 7 } ``` **Fix:** always pin the message with `expected`, so an unrelated panic (here, the slice-index panic `index out of bounds`) fails the substring check instead of silently satisfying it. ### Pitfall 2: a `#[should_panic]` test that does not panic [Section titled “Pitfall 2: a #\[should\_panic\] test that does not panic”](#pitfall-2-a-should_panic-test-that-does-not-panic) If the body completes normally, the test fails. This is the failure mode you *want* (it tells you the panic you expected never happened), but the message surprises newcomers: ```rust 1 #[test] 2 #[should_panic] 3 fn does_not_actually_panic() { 4 let _ = 2 + 2; // no panic — so the test fails 5 } ``` ```text 1 running 1 test 2 test tests::does_not_actually_panic - should panic ... FAILED 3 4 failures: 5 6 ---- tests::does_not_actually_panic stdout ---- 7 note: test did not panic as expected at src/lib.rs:9:8 8 9 failures: 10 tests::does_not_actually_panic 11 12 test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` ### Pitfall 3: using `?` in a test that does not return `Result` [Section titled “Pitfall 3: using ? in a test that does not return Result”](#pitfall-3-using--in-a-test-that-does-not-return-result) The `?` operator only works in a function whose return type can carry the error. A default test returns `()`, so `?` will not compile: ```rust 1 #[test] 2 fn parses_ff() { // returns () — no place for `?` to send the Err 3 let value = parse_hex_byte("ff")?; // does not compile (E0277) 4 assert_eq!(value, 255); 5 } ``` The real compiler error: ```text 1 error[E0277]: the `?` operator can only be used in a function that returns `Result` or `Option` (or another type that implements `FromResidual`) 2 --> src/lib.rs:14:41 3 | 4 13 | fn parses_ff() { 5 | -------------- this function should return `Result` or `Option` to accept `?` 6 14 | let value = parse_hex_byte("ff")?; 7 | ^ cannot use the `?` operator in a function that returns `()` 8 | 9 help: consider adding return type 10 | 11 13 ~ fn parses_ff() -> Result<(), Box<dyn std::error::Error>> { 12 14 | let value = parse_hex_byte("ff")?; 13 15 | assert_eq!(value, 255); 14 16 ~ Ok(()) 15 17 ~ } ``` **Fix:** add the return type the compiler suggests (`-> Result<(), Box<dyn std::error::Error>>` or a concrete error type) and end the body with `Ok(())`. ### Pitfall 4: trying to assert an `Err` *value* with `#[should_panic]` [Section titled “Pitfall 4: trying to assert an Err value with #\[should\_panic\]”](#pitfall-4-trying-to-assert-an-err-value-with-should_panic) A returned `Err` is not a panic, so `#[should_panic]` will never trigger on it; the test would fail with “did not panic.” To assert that a function returns a specific error, return `Result` from the test and inspect the error directly: ```rust 1 #[test] 2 fn missing_key_is_reported() { 3 // `unwrap_err` extracts the Err; it panics only if the call unexpectedly succeeds. 4 let err = parse_hex_color("nothex").unwrap_err(); 5 assert_eq!(err.to_string(), "invalid digit found in string"); 6 } ``` This is the idiomatic way to test the “expected failure” cases that you would write as `expect(...).toThrow(...)` in Jest but which in Rust are *recoverable* `Result` errors, not panics. ### Pitfall 5: forgetting `Ok(())` at the end [Section titled “Pitfall 5: forgetting Ok(()) at the end”](#pitfall-5-forgetting-ok-at-the-end) A `Result`-returning test must yield a value on the success path. Ending the body with the last `assert!` is not enough, because `assert!` evaluates to `()`, not `Result`. Add an explicit `Ok(())` as the final expression. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Always use `expected = "..."`** with `#[should_panic]`. The bare form is a foot-gun that passes on any panic. Pick a substring stable enough to survive small wording changes but specific enough to pin the cause. * **Reserve `#[should_panic]` for genuine invariants** — preconditions, “unreachable” branches, index bounds — i.e. the things that *should* panic in production because they represent a bug. Do not use it to test ordinary input validation; that belongs in a `Result` return and an `assert_eq!` on the error. * **Return `Result<(), E>` whenever a test body has more than one fallible step**, so `?` keeps the happy path readable. Use a concrete error type (`ParseIntError`, your domain enum) when one error flows through, and `Box<dyn std::error::Error>` when several different errors do. * **Assert error *values* by returning `Result` and inspecting `.unwrap_err()`** (or `match`/`matches!`), not by catching a panic. * **Keep `Ok(())` at the very end** of a `Result` test; treat it as the test’s “I reached the end successfully” marker. * **A `Result` test that itself fails on the success path can still use `.unwrap()` for the *negative* check**: e.g. `unwrap_err()` is fine because a precondition guarantees it. Reserve unconditional `unwrap()` for tests; in library code, prefer `?` (see [`unwrap` and `expect`](/08-error-handling/03-unwrap-expect/)). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small configuration store that reads typed settings. The error type uses [`thiserror`](/08-error-handling/06-anyhow-thiserror/) (add it with `cargo add thiserror`; this pulls in `thiserror = "2"`). The test module mixes all three styles: a `Result`-returning happy-path test that uses `?`, a negative test that asserts on the returned `Err` value, and a test that exercises the `Display` impl. ```rust 1 use std::collections::HashMap; 2 use thiserror::Error; 3 4 /// Errors that can occur while reading a typed setting from the config. 5 #[derive(Debug, Error, PartialEq)] 6 pub enum ConfigError { 7 #[error("missing required key: {0}")] 8 Missing(String), 9 #[error("key `{key}` is not a valid integer: {value:?}")] 10 NotAnInt { key: String, value: String }, 11 } 12 13 /// A tiny string-keyed configuration store. 14 pub struct Config { 15 values: HashMap<String, String>, 16 } 17 18 impl Config { 19 pub fn from_pairs(pairs: &[(&str, &str)]) -> Self { 20 let values = pairs 21 .iter() 22 .map(|(k, v)| (k.to_string(), v.to_string())) 23 .collect(); 24 Config { values } 25 } 26 27 /// Read a required `u16` setting, failing if it is missing or malformed. 28 pub fn require_u16(&self, key: &str) -> Result<u16, ConfigError> { 29 let raw = self 30 .values 31 .get(key) 32 .ok_or_else(|| ConfigError::Missing(key.to_string()))?; 33 raw.parse::<u16>().map_err(|_| ConfigError::NotAnInt { 34 key: key.to_string(), 35 value: raw.clone(), 36 }) 37 } 38 } 39 40 #[cfg(test)] 41 mod tests { 42 use super::*; 43 44 // A Result-returning test: every `?` either gives us the value or fails 45 // the test by returning the Err. No `.unwrap()` noise on the happy path. 46 #[test] 47 fn reads_valid_port() -> Result<(), ConfigError> { 48 let config = Config::from_pairs(&[("port", "8080"), ("host", "localhost")]); 49 let port = config.require_u16("port")?; 50 assert_eq!(port, 8080); 51 Ok(()) 52 } 53 54 // For the *failure* paths we assert on the returned Err directly, 55 // rather than using `?` (which would abort the test). 56 #[test] 57 fn missing_key_is_reported() { 58 let config = Config::from_pairs(&[("host", "localhost")]); 59 let err = config.require_u16("port").unwrap_err(); 60 assert_eq!(err, ConfigError::Missing("port".to_string())); 61 } 62 63 #[test] 64 fn malformed_int_is_reported() -> Result<(), Box<dyn std::error::Error>> { 65 let config = Config::from_pairs(&[("port", "not-a-number")]); 66 let err = config.require_u16("port").unwrap_err(); 67 // `to_string()` exercises the `#[error(...)]` Display impl. 68 assert!(err.to_string().contains("not a valid integer")); 69 Ok(()) 70 } 71 } ``` Running `cargo test` for this module: ```text 1 running 3 tests 2 test tests::malformed_int_is_reported ... ok 3 test tests::missing_key_is_reported ... ok 4 test tests::reads_valid_port ... ok 5 6 test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` Notice the division of labor: the success path uses `?` for clean propagation, the failure paths use `unwrap_err()` and assert on the `ConfigError` value, and none of them uses `#[should_panic]`, because *none of these are bugs*, they are recoverable errors. That is the idiomatic Rust split. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [The Rust Programming Language — How to Write Tests (Checking for Panics with `should_panic`)](https://doc.rust-lang.org/book/ch11-01-writing-tests.html#checking-for-panics-with-should_panic) * [The Rust Programming Language — Using `Result<T, E>` in Tests](https://doc.rust-lang.org/book/ch11-01-writing-tests.html#using-resultt-e-in-tests) * [Rust By Example — Testing](https://doc.rust-lang.org/rust-by-example/testing.html) * Related sections in this guide: * [Unit Tests](/13-testing/00-unit-tests/): the `#[test]` and `#[cfg(test)] mod tests` basics these tests build on * [Assertions](/13-testing/02-assertions/): `assert!`/`assert_eq!`/`assert_ne!` and custom messages, which trigger the panics `#[should_panic]` catches * [Integration Tests](/13-testing/04-integration-tests/): `Result`-returning tests also work in the `tests/` directory * [Doc Tests](/13-testing/09-doc-tests/): doc tests support a `should_panic` attribute and can also return `Result` * [Test Organization](/13-testing/01-test-organization/): where these tests live and the `tests` submodule convention * [The `?` Operator](/08-error-handling/01-question-mark/): the mechanics of `?` that `Result`-returning tests rely on * [Panicking](/08-error-handling/02-panic/) — when a panic is the right signal versus returning a `Result` * [`unwrap` and `expect`](/08-error-handling/03-unwrap-expect/) — acceptable in tests, including the `unwrap_err()` pattern above * [Section 14: Macros](/14-macros/): `#[test]`, `#[should_panic]`, and `assert!` are all built on Rust’s attribute and macro system *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: assert a precondition panic [Section titled “Exercise 1: assert a precondition panic”](#exercise-1-assert-a-precondition-panic) **Difficulty:** Easy **Objective:** Use `#[should_panic(expected = "...")]` to verify that a method panics when called on an invalid state. **Instructions:** 1. Given the `Stack<T>` below, whose `pop` panics on an empty stack, write a test that confirms calling `pop` on a fresh stack panics with a message containing `"empty stack"`. 2. Add a second, ordinary test that pushes two values and asserts `pop` returns them in last-in-first-out order. ```rust 1 pub struct Stack<T> { 2 items: Vec<T>, 3 } 4 5 impl<T> Stack<T> { 6 pub fn new() -> Self { 7 Stack { items: Vec::new() } 8 } 9 pub fn push(&mut self, item: T) { 10 self.items.push(item); 11 } 12 /// Remove and return the top item, panicking if the stack is empty. 13 pub fn pop(&mut self) -> T { 14 self.items.pop().expect("pop called on an empty stack") 15 } 16 } 17 18 #[cfg(test)] 19 mod tests { 20 use super::*; 21 // TODO: write the two tests 22 } ``` Solution ```rust 1 pub struct Stack<T> { 2 items: Vec<T>, 3 } 4 5 impl<T> Stack<T> { 6 pub fn new() -> Self { 7 Stack { items: Vec::new() } 8 } 9 pub fn push(&mut self, item: T) { 10 self.items.push(item); 11 } 12 pub fn pop(&mut self) -> T { 13 self.items.pop().expect("pop called on an empty stack") 14 } 15 } 16 17 #[cfg(test)] 18 mod tests { 19 use super::*; 20 21 #[test] 22 #[should_panic(expected = "empty stack")] 23 fn pop_on_empty_panics() { 24 let mut stack: Stack<i32> = Stack::new(); 25 stack.pop(); 26 } 27 28 #[test] 29 fn push_then_pop() { 30 let mut stack = Stack::new(); 31 stack.push(1); 32 stack.push(2); 33 assert_eq!(stack.pop(), 2); 34 assert_eq!(stack.pop(), 1); 35 } 36 } ``` The `expected` substring matches the message inside `.expect(...)`. Running `cargo test` reports `pop_on_empty_panics - should panic ... ok` and `push_then_pop ... ok`. ### Exercise 2: convert an `unwrap`-heavy test to a `Result` test [Section titled “Exercise 2: convert an unwrap-heavy test to a Result test”](#exercise-2-convert-an-unwrap-heavy-test-to-a-result-test) **Difficulty:** Medium **Objective:** Replace `.unwrap()` calls in a test body with the `?` operator by giving the test a `Result` return type. **Instructions:** 1. The parser below turns a `"x,y"` row into a `Point`. Write a test `parses_a_point` that parses `"3, 4"` and asserts it equals `Point { x: 3, y: 4 }`. 2. Use `?` rather than `.unwrap()`, which means the test must return `Result<(), ParseError>` and end with `Ok(())`. ```rust 1 use std::num::ParseIntError; 2 3 #[derive(Debug, PartialEq)] 4 pub struct Point { 5 pub x: i32, 6 pub y: i32, 7 } 8 9 #[derive(Debug, PartialEq)] 10 pub enum ParseError { 11 WrongFieldCount(usize), 12 BadInt(ParseIntError), 13 } 14 15 impl From<ParseIntError> for ParseError { 16 fn from(e: ParseIntError) -> Self { 17 ParseError::BadInt(e) 18 } 19 } 20 21 pub fn parse_point(row: &str) -> Result<Point, ParseError> { 22 let fields: Vec<&str> = row.split(',').collect(); 23 if fields.len() != 2 { 24 return Err(ParseError::WrongFieldCount(fields.len())); 25 } 26 let x = fields[0].trim().parse::<i32>()?; 27 let y = fields[1].trim().parse::<i32>()?; 28 Ok(Point { x, y }) 29 } 30 31 #[cfg(test)] 32 mod tests { 33 use super::*; 34 // TODO: write `parses_a_point` using `?` 35 } ``` Solution ```rust 1 use std::num::ParseIntError; 2 3 #[derive(Debug, PartialEq)] 4 pub struct Point { 5 pub x: i32, 6 pub y: i32, 7 } 8 9 #[derive(Debug, PartialEq)] 10 pub enum ParseError { 11 WrongFieldCount(usize), 12 BadInt(ParseIntError), 13 } 14 15 impl From<ParseIntError> for ParseError { 16 fn from(e: ParseIntError) -> Self { 17 ParseError::BadInt(e) 18 } 19 } 20 21 pub fn parse_point(row: &str) -> Result<Point, ParseError> { 22 let fields: Vec<&str> = row.split(',').collect(); 23 if fields.len() != 2 { 24 return Err(ParseError::WrongFieldCount(fields.len())); 25 } 26 let x = fields[0].trim().parse::<i32>()?; 27 let y = fields[1].trim().parse::<i32>()?; 28 Ok(Point { x, y }) 29 } 30 31 #[cfg(test)] 32 mod tests { 33 use super::*; 34 35 #[test] 36 fn parses_a_point() -> Result<(), ParseError> { 37 let point = parse_point("3, 4")?; 38 assert_eq!(point, Point { x: 3, y: 4 }); 39 Ok(()) 40 } 41 } ``` Because the test returns `Result<(), ParseError>`, the `?` on `parse_point` propagates any `Err` as a test failure, and the happy path stays free of `.unwrap()`. The test reports `parses_a_point ... ok`. ### Exercise 3: test both the success and the two failure modes [Section titled “Exercise 3: test both the success and the two failure modes”](#exercise-3-test-both-the-success-and-the-two-failure-modes) **Difficulty:** Medium-Hard **Objective:** Cover one function with a `Result` test for success and `Err`-value assertions for each failure path — *without* `#[should_panic]`, because these are recoverable errors, not bugs. **Instructions:** Using the same `parse_point` from Exercise 2, write three tests: 1. `wrong_field_count_is_an_error`: parsing `"1,2,3"` returns `Err(ParseError::WrongFieldCount(3))`. 2. `bad_int_is_an_error`: parsing a valid `"10,-7"` succeeds via `?`, and parsing `"x,2"` returns a `ParseError::BadInt(_)`. 3. Decide for each whether the test should return `Result` and explain (in a comment) why you did *not* use `#[should_panic]`. Solution ```rust 1 use std::num::ParseIntError; 2 3 #[derive(Debug, PartialEq)] 4 pub struct Point { 5 pub x: i32, 6 pub y: i32, 7 } 8 9 #[derive(Debug, PartialEq)] 10 pub enum ParseError { 11 WrongFieldCount(usize), 12 BadInt(ParseIntError), 13 } 14 15 impl From<ParseIntError> for ParseError { 16 fn from(e: ParseIntError) -> Self { 17 ParseError::BadInt(e) 18 } 19 } 20 21 pub fn parse_point(row: &str) -> Result<Point, ParseError> { 22 let fields: Vec<&str> = row.split(',').collect(); 23 if fields.len() != 2 { 24 return Err(ParseError::WrongFieldCount(fields.len())); 25 } 26 let x = fields[0].trim().parse::<i32>()?; 27 let y = fields[1].trim().parse::<i32>()?; 28 Ok(Point { x, y }) 29 } 30 31 #[cfg(test)] 32 mod tests { 33 use super::*; 34 35 // A wrong field count is a recoverable, *expected* failure — not a bug — 36 // so we assert on the returned Err value rather than expecting a panic. 37 #[test] 38 fn wrong_field_count_is_an_error() { 39 let err = parse_point("1,2,3").unwrap_err(); 40 assert_eq!(err, ParseError::WrongFieldCount(3)); 41 } 42 43 // Same reasoning: a malformed integer returns Err, it does not panic. 44 // This test returns Result so the *valid* row can use `?` on the happy path. 45 #[test] 46 fn bad_int_is_an_error() -> Result<(), ParseError> { 47 let ok = parse_point("10,-7")?; 48 assert_eq!(ok, Point { x: 10, y: -7 }); 49 assert!(matches!(parse_point("x,2"), Err(ParseError::BadInt(_)))); 50 Ok(()) 51 } 52 } ``` Both failures are returned as `Err` values, so `#[should_panic]` would be wrong here — it would only catch a *panic*, and `parse_point` never panics. `matches!` is a concise way to assert the *variant* of an error without comparing the inner `ParseIntError`, which does not have a convenient literal. The suite reports `wrong_field_count_is_an_error ... ok` and `bad_int_is_an_error ... ok`. # Integration Tests: The `tests/` Directory and Black-Box Testing > Rust integration tests live in tests/, compile as separate crates, and reach only your public API. Compare Jest's free imports, plus shared setup. Integration tests in Rust live in a top-level `tests/` directory, get compiled as separate crates, and can only see your crate’s **public API**: exactly the way a real consumer would `use` it. This page covers how that directory works, how to test the public surface as a black box, and how to share setup code across test files without confusing Cargo. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In TypeScript/JavaScript you usually drop every test under a `tests/` or `__tests__` folder and let Jest or Vitest run the lot, regardless of whether a test pokes at internals or only the exported API. Rust draws a sharper line: **unit tests** live *inside* your source files and can reach private items, while **integration tests** live in a sibling `tests/` directory, are compiled as independent crates, and are forced to go through your `pub` interface. That separation makes integration tests a faithful black-box check of what your users will actually be able to call. This page is about the `tests/` directory specifically; the [unit-tests](/13-testing/00-unit-tests/) and [test-organization](/13-testing/01-test-organization/) pages cover the in-source side. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Here is a small shopping-cart module and a Vitest suite that exercises it end to end. In a typical Node project the tests sit next to (or under) `src/` and import the module like any other consumer. ```typescript 1 // src/cart.ts — the module under test 2 export interface Item { 3 sku: string; 4 priceCents: number; 5 } 6 7 export class Cart { 8 private lines = new Map<string, { item: Item; qty: number }>(); 9 10 add(item: Item, qty: number): void { 11 if (item.sku === "") throw new Error("SKU must not be empty"); 12 const line = this.lines.get(item.sku); 13 if (line) line.qty += qty; 14 else this.lines.set(item.sku, { item, qty }); 15 } 16 17 quantity(sku: string): number { 18 return this.lines.get(sku)?.qty ?? 0; 19 } 20 21 totalCents(): number { 22 let sum = 0; 23 for (const { item, qty } of this.lines.values()) sum += item.priceCents * qty; 24 return sum; 25 } 26 } 27 28 export function applyDiscount(totalCents: number, percent: number): number { 29 const p = Math.min(percent, 100); 30 return totalCents - Math.floor((totalCents * p) / 100); 31 } ``` ```typescript 1 // tests/cart.test.ts — Vitest integration-style test 2 import { describe, it, expect } from "vitest"; 3 import { Cart, applyDiscount } from "../src/cart"; 4 5 // A shared helper used by several tests. 6 function sampleCart(): Cart { 7 const cart = new Cart(); 8 cart.add({ sku: "BOOK-01", priceCents: 1299 }, 2); 9 cart.add({ sku: "PEN-07", priceCents: 250 }, 4); 10 return cart; 11 } 12 13 describe("cart checkout", () => { 14 it("totals prices times quantities", () => { 15 expect(sampleCart().totalCents()).toBe(3598); 16 }); 17 18 it("applies a percentage discount", () => { 19 expect(applyDiscount(sampleCart().totalCents(), 10)).toBe(3239); 20 }); 21 }); ``` Note two things a TypeScript developer takes for granted: the test imports from a **relative path** (`../src/cart`), and the helper `sampleCart` is just a function defined in the same file. Nothing stops a Vitest test from reaching into internals either — `private` is only enforced by the type-checker, not at runtime, so a determined test could still poke at `(cart as any).lines`. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same library as a Rust crate. Integration tests go in `tests/`, `use` the crate **by its package name** (not by a relative path), and the compiler refuses to let them touch private fields like `lines`. ```text 1 cart/ 2 ├── Cargo.toml 3 ├── src/ 4 │ └── lib.rs # the library crate 5 └── tests/ # each .rs file here is its OWN test crate 6 ├── cart_checkout.rs 7 ├── cart_lifecycle.rs 8 └── common/ 9 └── mod.rs # shared helpers (subdir, so it is NOT a test crate) ``` ```rust 1 // src/lib.rs — the library under test 2 use std::collections::HashMap; 3 4 #[derive(Debug, Clone, PartialEq)] 5 pub struct Item { 6 pub sku: String, 7 pub price_cents: u32, 8 } 9 10 impl Item { 11 pub fn new(sku: &str, price_cents: u32) -> Self { 12 Item { sku: sku.to_string(), price_cents } 13 } 14 } 15 16 #[derive(Debug, PartialEq)] 17 pub enum CartError { 18 EmptySku, 19 UnknownSku(String), 20 } 21 22 impl std::fmt::Display for CartError { 23 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { 24 match self { 25 CartError::EmptySku => write!(f, "SKU must not be empty"), 26 CartError::UnknownSku(s) => write!(f, "unknown SKU: {s}"), 27 } 28 } 29 } 30 31 impl std::error::Error for CartError {} 32 33 #[derive(Debug, Default)] 34 pub struct Cart { 35 lines: HashMap<String, (Item, u32)>, // PRIVATE field 36 } 37 38 impl Cart { 39 pub fn new() -> Self { 40 Cart::default() 41 } 42 43 pub fn add(&mut self, item: Item, qty: u32) -> Result<(), CartError> { 44 if item.sku.is_empty() { 45 return Err(CartError::EmptySku); 46 } 47 let entry = self.lines.entry(item.sku.clone()).or_insert((item, 0)); 48 entry.1 += qty; 49 Ok(()) 50 } 51 52 pub fn quantity(&self, sku: &str) -> u32 { 53 self.lines.get(sku).map(|(_, q)| *q).unwrap_or(0) 54 } 55 56 pub fn remove(&mut self, sku: &str) -> Result<(), CartError> { 57 self.lines 58 .remove(sku) 59 .map(|_| ()) 60 .ok_or_else(|| CartError::UnknownSku(sku.to_string())) 61 } 62 63 pub fn total_cents(&self) -> u32 { 64 self.lines.values().map(|(item, qty)| item.price_cents * qty).sum() 65 } 66 67 pub fn is_empty(&self) -> bool { 68 self.lines.is_empty() 69 } 70 } 71 72 pub fn apply_discount(total_cents: u32, percent: u8) -> u32 { 73 let percent = percent.min(100) as u32; 74 total_cents - (total_cents * percent / 100) 75 } ``` ```rust 1 // tests/common/mod.rs — shared helpers, NOT a test crate of its own 2 use cart::{Cart, Item}; 3 4 pub fn sample_cart() -> Cart { 5 let mut cart = Cart::new(); 6 cart.add(Item::new("BOOK-01", 1299), 2).unwrap(); 7 cart.add(Item::new("PEN-07", 250), 4).unwrap(); 8 cart 9 } ``` ```rust 1 // tests/cart_checkout.rs — an integration test crate 2 use cart::{apply_discount, Cart, CartError, Item}; 3 4 mod common; // pulls in tests/common/mod.rs 5 6 #[test] 7 fn building_a_cart_accumulates_quantities() { 8 let mut cart = Cart::new(); 9 cart.add(Item::new("BOOK-01", 1299), 1).unwrap(); 10 cart.add(Item::new("BOOK-01", 1299), 2).unwrap(); 11 assert_eq!(cart.quantity("BOOK-01"), 3); 12 } 13 14 #[test] 15 fn total_reflects_prices_and_quantities() { 16 let cart = common::sample_cart(); 17 assert_eq!(cart.total_cents(), 3598); 18 } 19 20 #[test] 21 fn discount_is_applied_to_the_total() { 22 let cart = common::sample_cart(); 23 let discounted = apply_discount(cart.total_cents(), 10); 24 assert_eq!(discounted, 3239); 25 } 26 27 #[test] 28 fn adding_an_empty_sku_is_rejected() { 29 let mut cart = Cart::new(); 30 let err = cart.add(Item::new("", 100), 1).unwrap_err(); 31 assert_eq!(err, CartError::EmptySku); 32 } 33 34 // A test can return `Result` and use `?` instead of `.unwrap()`. 35 #[test] 36 fn removing_a_missing_line_returns_a_result() -> Result<(), CartError> { 37 let mut cart = common::sample_cart(); 38 cart.remove("BOOK-01")?; 39 assert_eq!(cart.quantity("BOOK-01"), 0); 40 Ok(()) 41 } ``` ```rust 1 // tests/cart_lifecycle.rs — a SECOND, independent test crate 2 use cart::Cart; 3 4 mod common; 5 6 #[test] 7 fn a_fresh_cart_is_empty() { 8 let cart = Cart::new(); 9 assert!(cart.is_empty()); 10 } 11 12 #[test] 13 fn removing_every_line_empties_the_cart() { 14 let mut cart = common::sample_cart(); 15 cart.remove("BOOK-01").unwrap(); 16 cart.remove("PEN-07").unwrap(); 17 assert!(cart.is_empty()); 18 } ``` Running `cargo test` compiles the library, each `tests/*.rs` file, and the doc-tests, then runs them all. This is the real, unedited output: ```text 1 Compiling cart v0.1.0 (/private/tmp/ts_rust_inttest/cart) 2 Finished `test` profile [unoptimized + debuginfo] target(s) in 0.75s 3 Running unittests src/lib.rs (target/debug/deps/cart-1e951a69f9a013e1) 4 5 running 0 tests 6 7 test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s 8 9 Running tests/cart_checkout.rs (target/debug/deps/cart_checkout-830e111353aebe70) 10 11 running 5 tests 12 test adding_an_empty_sku_is_rejected ... ok 13 test building_a_cart_accumulates_quantities ... ok 14 test discount_is_applied_to_the_total ... ok 15 test removing_a_missing_line_returns_a_result ... ok 16 test total_reflects_prices_and_quantities ... ok 17 18 test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s 19 20 Running tests/cart_lifecycle.rs (target/debug/deps/cart_lifecycle-d63887261d751300) 21 22 running 2 tests 23 test a_fresh_cart_is_empty ... ok 24 test removing_every_line_empties_the_cart ... ok 25 26 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s 27 28 Doc-tests cart 29 30 running 0 tests 31 32 test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` > **Note:** The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects the newest edition automatically, so the layout above is what you get out of the box. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) **One `tests/` file = one crate.** Cargo treats every `.rs` file directly inside `tests/` as a *separate* integration-test crate. That is why the output above lists `tests/cart_checkout.rs` and `tests/cart_lifecycle.rs` under their own `Running ...` headers, each compiled into its own binary in `target/debug/deps/`. There is no equivalent in Jest/Vitest, where every test file shares one module graph and one process. The upside in Rust is strong isolation: a crash or a global-state mutation in one file cannot leak into another. **Integration tests see only `pub`.** Each test crate links against your library exactly as an external user would: `use cart::Cart;`. The crate name comes from the `name` field in `[package]` (with dashes turned into underscores), **not** from a relative path. Because the test is an outside consumer, it can call `Cart::new`, `add`, `total_cents`, and the free function `apply_discount`, but it cannot read the private `lines` field. This is the black-box guarantee: if a type or method is not reachable from an integration test, your real users cannot reach it either. **`#[test]` and assertions work identically to unit tests.** The `#[test]` attribute marks a function as a test; `assert_eq!`/`assert!` do the checking; a test that returns `Result<(), E>` may use `?` and is considered passing when it returns `Ok`. Those mechanics are shared with unit tests and are covered in depth in [assertions](/13-testing/02-assertions/) and [should-panic](/13-testing/03-should-panic/). **The `unittests src/lib.rs` line with `0 tests`** appears because the library itself has no `#[cfg(test)]` module here. Cargo always *offers* to run the crate’s own unit tests; when there are none you simply see a zero count. That is normal, not an error. **Shared helpers go in a subdirectory.** The helper `sample_cart` lives in `tests/common/mod.rs`, and each test file pulls it in with `mod common;`. Putting it in a `common/` *subdirectory* (with a `mod.rs`) is the key: files in subdirectories are **not** compiled as their own test crates, so the helper is shared rather than executed as a test target. We will see what happens if you forget this in the Pitfalls section. **Why the test calls `.unwrap()` in helpers but `?` in a test body.** Inside `sample_cart`, `.unwrap()` is fine — if setup fails, the test should abort loudly. Inside a `#[test] -> Result<...>` body, returning the error via `?` produces a clean failure report instead of a panic backtrace. Both are idiomatic; choose based on whether the failing call is *setup* or the *thing under test*. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | TypeScript (Jest/Vitest) | Rust integration tests | | -------------------------- | -------------------------------------------- | --------------------------------------------------------- | | Location | Anywhere; commonly `tests/` or `__tests__/` | A top-level `tests/` directory only | | Compilation unit | One shared module graph, one process | Each `tests/*.rs` is its own crate + binary | | What’s visible | Everything (privates reachable via `as any`) | The crate’s **public API only** | | How the module is imported | Relative path: `../src/cart` | Crate name: `use cart::...` | | Shared setup file | A regular imported file | A `tests/common/mod.rs` in a subdirectory | | Isolation between files | Shared globals/mocks unless reset | Hard process/crate isolation by default | | Parallelism | Per-file workers (configurable) | Tests run in parallel threads by default | | Library vs binary | No distinction | Only **library crates** are integration-testable directly | The most consequential difference is the **public-API constraint**. In TypeScript, `private` is advisory and erased at runtime, so a test can reach internals when it wants to. Rust’s integration tests are compiled against the crate boundary, so the visibility rules are enforced by the compiler. If you need to test a private function, that belongs in a unit test inside the module (see [test-organization](/13-testing/01-test-organization/)). > **Note:** Integration tests can only target a **library** crate. A crate with just `src/main.rs` exposes no library API, so `use yourbin::...` will not resolve. The common production pattern is a thin `src/main.rs` that calls into a `src/lib.rs`; the library is integration-tested, and the binary is tested by *running it* (shown in the Real-World Example below). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: A flat helper file in `tests/` gets run as a test [Section titled “Pitfall 1: A flat helper file in tests/ gets run as a test”](#pitfall-1-a-flat-helper-file-in-tests-gets-run-as-a-test) If you put shared helpers in `tests/helpers.rs` (a flat file, not a subdirectory), Cargo compiles it as its own integration-test crate. It contains no `#[test]` functions, so you get a confusing empty run: ```rust 1 // tests/helpers.rs — WRONG place for a shared helper 2 use cart::{Cart, Item}; 3 4 pub fn sample_cart() -> Cart { 5 let mut cart = Cart::new(); 6 cart.add(Item::new("BOOK-01", 1299), 2).unwrap(); 7 cart 8 } ``` Running it shows the helper file masquerading as a test target with nothing to run: ```text 1 Running tests/helpers.rs (target/debug/deps/helpers-58b7202b39b88064) 2 3 running 0 tests 4 5 test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` **Fix:** move the helper to `tests/common/mod.rs` and pull it in with `mod common;`. Files in subdirectories are not treated as test crates. ### Pitfall 2: Trying to reach a private item [Section titled “Pitfall 2: Trying to reach a private item”](#pitfall-2-trying-to-reach-a-private-item) Coming from TypeScript, you might expect a test to touch internals “just this once.” Add a private function to the library and call it from an integration test: ```rust 1 // in src/lib.rs 2 fn round_to_nearest_dollar(cents: u32) -> u32 { // private! 3 ((cents + 50) / 100) * 100 4 } ``` tests/private\_probe.rs ```rust 1 #[test] 2 fn cannot_reach_private_fn() { 3 // does not compile (error[E0603]: function is private) 4 let _ = cart::round_to_nearest_dollar(1250); 5 } ``` The compiler stops you with the real error: ```text 1 error[E0603]: function `round_to_nearest_dollar` is private 2 --> tests/private_probe.rs:4:19 3 | 4 4 | let _ = cart::round_to_nearest_dollar(1250); 5 | ^^^^^^^^^^^^^^^^^^^^^^^ private function 6 | 7 note: the function `round_to_nearest_dollar` is defined here 8 --> src/lib.rs:79:1 9 | 10 79 | fn round_to_nearest_dollar(cents: u32) -> u32 { 11 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``` **Fix:** either make the item `pub` (if it truly is part of the API), or test it from a unit test inside the module where private access is allowed. ### Pitfall 3: Importing by relative path instead of crate name [Section titled “Pitfall 3: Importing by relative path instead of crate name”](#pitfall-3-importing-by-relative-path-instead-of-crate-name) There is no `use crate::...` or `use super::...` reaching out of `tests/` into `src/`: an integration test is a *separate crate*. Write `use cart::Cart;` (the package name), the same way an external dependency would. Newcomers often try `use super::cart::Cart;` or a `mod` pointing at `../src`, both of which fail to resolve. ### Pitfall 4: Expecting `console.log`-style output by default [Section titled “Pitfall 4: Expecting console.log-style output by default”](#pitfall-4-expecting-consolelog-style-output-by-default) Just like Vitest hides logs from passing tests, Rust **captures** stdout/stderr and only shows it for failing tests. If you want to see prints from passing tests, run `cargo test -- --nocapture`. (The `--` separates Cargo’s arguments from the test harness’s.) ### Pitfall 5: Forgetting that integration tests need a library target [Section titled “Pitfall 5: Forgetting that integration tests need a library target”](#pitfall-5-forgetting-that-integration-tests-need-a-library-target) If your crate is binary-only, `cargo test` will still run the binary’s *unit* tests, but `use yourbin::...` in `tests/` won’t compile because there is no library to link. The fix is to extract logic into `src/lib.rs`. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Group by feature, not by function.** One file per user-facing workflow (`tests/cart_checkout.rs`, `tests/auth_flow.rs`) reads better than one giant `tests/lib.rs`. Because each file is its own crate, this also improves parallelism. * **Keep shared setup in `tests/common/mod.rs`.** Expose small `pub fn` constructors there. For heavier setup (temp directories, fixtures, RAII teardown), see [test-fixtures](/13-testing/05-test-fixtures/). * **Treat integration tests as your API’s first real consumer.** If a test is awkward to write because the public API is clumsy, that is feedback about the API, not the test. * **Use `Result`-returning tests with `?`** for flows that involve fallible setup steps; reserve `.unwrap()` for “this must succeed or the test is meaningless” setup. * **Pin dev-only crates under `[dev-dependencies]`.** Things like `assert_cmd`, `predicates`, or `tempfile` should never end up in your published dependency graph. Add them with `cargo add --dev <crate>` (the `add` subcommand has been built into Cargo since 1.62, no `cargo-edit` needed). * **Select a single file with `--test`.** `cargo test --test cart_checkout` runs only that integration-test crate; append a name substring to filter further, e.g. `cargo test --test cart_checkout total`. * **Do not duplicate unit-test coverage.** Integration tests verify the *contract*; private-logic edge cases belong in unit tests. See [test-organization](/13-testing/01-test-organization/) for where each kind lives. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production crate usually ships a **library** plus a thin **binary**. The library is integration-tested through its public API; the binary is integration-tested by *running the compiled program* and asserting on its exit code and output. The `assert_cmd` and `predicates` crates make the latter ergonomic; they are the Rust analog of spawning your CLI in a Jest test and checking `stdout`. Cargo.toml ```toml 1 [package] 2 name = "greet" 3 version = "0.1.0" 4 edition = "2024" 5 6 [dev-dependencies] 7 assert_cmd = "2.2.2" 8 predicates = "3.1.4" ``` ```rust 1 // src/main.rs — the binary under test 2 use std::env; 3 use std::process::ExitCode; 4 5 fn main() -> ExitCode { 6 let args: Vec<String> = env::args().skip(1).collect(); 7 match args.first().map(String::as_str) { 8 Some(name) if !name.is_empty() => { 9 println!("Hello, {name}!"); 10 ExitCode::SUCCESS 11 } 12 _ => { 13 eprintln!("error: expected a name argument"); 14 ExitCode::from(2) 15 } 16 } 17 } ``` ```rust 1 // tests/cli.rs — black-box test of the actual binary 2 use assert_cmd::Command; 3 use predicates::prelude::*; 4 5 #[test] 6 fn greets_a_named_user() { 7 let mut cmd = Command::cargo_bin("greet").unwrap(); 8 cmd.arg("Ada") 9 .assert() 10 .success() 11 .stdout(predicate::str::contains("Hello, Ada!")); 12 } 13 14 #[test] 15 fn fails_without_a_name() { 16 let mut cmd = Command::cargo_bin("greet").unwrap(); 17 cmd.assert() 18 .failure() 19 .code(2) 20 .stderr(predicate::str::contains("expected a name")); 21 } ``` `Command::cargo_bin("greet")` locates and runs the freshly compiled binary; the `.assert()` builder then checks the exit status and matches `stdout`/`stderr` against `predicates` combinators. Running `cargo test --test cli` produces this real output: ```text 1 Compiling greet v0.1.0 (/private/tmp/ts_rust_clitest/greet) 2 Finished `test` profile [unoptimized + debuginfo] target(s) in 6.63s 3 Running tests/cli.rs (target/debug/deps/cli-cd6dde0ca03346ee) 4 5 running 2 tests 6 test greets_a_named_user ... ok 7 test fails_without_a_name ... ok 8 9 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.18s ``` This is genuine black-box testing: the test knows nothing about the program’s internals, only its command-line contract, the closest Rust equivalent to spawning your built CLI in a Jest/Vitest test and asserting on its output. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * The Rust Book — [Integration Tests](https://doc.rust-lang.org/book/ch11-03-test-organization.html#integration-tests) * Cargo Book — [Tests and the `tests/` directory](https://doc.rust-lang.org/cargo/guide/tests.html) and [Target auto-discovery](https://doc.rust-lang.org/cargo/reference/cargo-targets.html#integration-tests) * [`assert_cmd` documentation](https://docs.rs/assert_cmd) and [`predicates` documentation](https://docs.rs/predicates) for CLI black-box testing * Related pages in this section: * [Unit Tests](/13-testing/00-unit-tests/): in-source `#[test]` and `#[cfg(test)] mod tests` * [Test Organization](/13-testing/01-test-organization/): where each kind of test lives; private vs public testing * [Assertions](/13-testing/02-assertions/) — `assert!`, `assert_eq!`, custom messages * [should\_panic and Result tests](/13-testing/03-should-panic/) — testing failures and `?` in tests * [Test Fixtures](/13-testing/05-test-fixtures/) — setup/teardown, `LazyLock`, RAII guards for shared state * [Mocking](/13-testing/06-mocking/) — trait-based test doubles and `mockall` * Earlier sections: [Modules and the crate tree](/12-modules-packages/00-modules/) explains why `tests/` sees only `pub` items; [Cargo.toml and dev-dependencies](/12-modules-packages/04-cargo/) covers `[dev-dependencies]`. New to the project layout? Start at [Getting Started](/01-getting-started/) and [Basics](/02-basics/). * Next up after testing: [Section 14 — Macros](/14-macros/), where attributes like `#[test]` and derives are explained from the inside. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Your first integration test [Section titled “Exercise 1: Your first integration test”](#exercise-1-your-first-integration-test) **Difficulty:** Beginner **Objective:** Create a library crate and verify its public API from `tests/`. **Instructions:** Run `cargo new --lib slugify`. In `src/lib.rs`, write `pub fn slugify(input: &str) -> String` that lowercases the text, replaces every run of non-alphanumeric characters with a single `-`, and trims leading/trailing `-`. Add `tests/slugify.rs` with at least two `#[test]` functions that call `slugify::slugify(...)` and assert on the results. Run `cargo test`. Solution src/lib.rs ```rust 1 pub fn slugify(input: &str) -> String { 2 let mut out = String::new(); 3 let mut prev_dash = true; // start "true" so leading separators are dropped 4 for ch in input.chars() { 5 if ch.is_ascii_alphanumeric() { 6 out.extend(ch.to_lowercase()); 7 prev_dash = false; 8 } else if !prev_dash { 9 out.push('-'); 10 prev_dash = true; 11 } 12 } 13 while out.ends_with('-') { 14 out.pop(); 15 } 16 out 17 } ``` tests/slugify.rs ```rust 1 use slugify::slugify; 2 3 #[test] 4 fn collapses_separators_and_lowercases() { 5 assert_eq!(slugify("Hello, World!"), "hello-world"); 6 } 7 8 #[test] 9 fn trims_edges_and_runs() { 10 assert_eq!(slugify(" ***Rust & TS*** "), "rust-ts"); 11 } ``` **Output:** ```text 1 running 2 tests 2 test collapses_separators_and_lowercases ... ok 3 test trims_edges_and_runs ... ok 4 5 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` ### Exercise 2: Share setup across two test files [Section titled “Exercise 2: Share setup across two test files”](#exercise-2-share-setup-across-two-test-files) **Difficulty:** Intermediate **Objective:** Use a `tests/common/mod.rs` helper from more than one integration-test file without it being run as a test. **Instructions:** Starting from a `cargo new --lib kv` crate, implement a tiny `pub struct Store` backed by a `HashMap<String, String>` with `pub fn new()`, `pub fn set(&mut self, k: &str, v: &str)`, and `pub fn get(&self, k: &str) -> Option<&str>`. Add `tests/common/mod.rs` exposing `pub fn seeded() -> Store` that inserts two known keys. Then write **two** test files (`tests/reads.rs` and `tests/writes.rs`), each declaring `mod common;` and using `common::seeded()`. Confirm `cargo test` lists two separate test crates and zero stray empty ones. Solution src/lib.rs ```rust 1 use std::collections::HashMap; 2 3 #[derive(Debug, Default)] 4 pub struct Store { 5 map: HashMap<String, String>, 6 } 7 8 impl Store { 9 pub fn new() -> Self { 10 Store::default() 11 } 12 13 pub fn set(&mut self, k: &str, v: &str) { 14 self.map.insert(k.to_string(), v.to_string()); 15 } 16 17 pub fn get(&self, k: &str) -> Option<&str> { 18 self.map.get(k).map(String::as_str) 19 } 20 } ``` tests/common/mod.rs ```rust 1 use kv::Store; 2 3 pub fn seeded() -> Store { 4 let mut s = Store::new(); 5 s.set("lang", "rust"); 6 s.set("year", "2026"); 7 s 8 } ``` tests/reads.rs ```rust 1 mod common; 2 3 #[test] 4 fn reads_seeded_values() { 5 let s = common::seeded(); 6 assert_eq!(s.get("lang"), Some("rust")); 7 assert_eq!(s.get("missing"), None); 8 } ``` tests/writes.rs ```rust 1 use kv::Store; 2 3 mod common; 4 5 #[test] 6 fn writes_override_existing_values() { 7 let mut s = common::seeded(); 8 s.set("lang", "ferris"); 9 assert_eq!(s.get("lang"), Some("ferris")); 10 } 11 12 #[test] 13 fn fresh_store_is_distinct_from_seeded() { 14 let empty = Store::new(); 15 assert_eq!(empty.get("lang"), None); 16 } ``` **Output (test-crate headers only):** ```text 1 Running tests/reads.rs (target/debug/deps/reads-...) 2 running 1 test 3 test reads_seeded_values ... ok 4 5 Running tests/writes.rs (target/debug/deps/writes-...) 6 running 2 tests 7 test fresh_store_is_distinct_from_seeded ... ok 8 test writes_override_existing_values ... ok ``` Because `common` lives in a subdirectory, there is **no** `Running tests/common/mod.rs` line, exactly what we want. ### Exercise 3: Black-box test a binary’s exit code [Section titled “Exercise 3: Black-box test a binary’s exit code”](#exercise-3-black-box-test-a-binarys-exit-code) **Difficulty:** Advanced **Objective:** Test a compiled binary end-to-end with `assert_cmd`, asserting on both success and failure paths. **Instructions:** Create `cargo new adder`. The program reads two integer arguments, prints their sum on success, and exits with code `2` plus a stderr message if an argument is missing or not a number. Add `assert_cmd` and `predicates` as dev-dependencies (`cargo add --dev assert_cmd predicates`) and write `tests/cli.rs` with one test for a valid sum and one for a parse failure. Solution src/main.rs ```rust 1 use std::env; 2 use std::process::ExitCode; 3 4 fn main() -> ExitCode { 5 let nums: Vec<String> = env::args().skip(1).collect(); 6 if nums.len() != 2 { 7 eprintln!("error: expected exactly two integers"); 8 return ExitCode::from(2); 9 } 10 let mut sum: i64 = 0; 11 for n in &nums { 12 match n.parse::<i64>() { 13 Ok(v) => sum += v, 14 Err(_) => { 15 eprintln!("error: '{n}' is not an integer"); 16 return ExitCode::from(2); 17 } 18 } 19 } 20 println!("{sum}"); 21 ExitCode::SUCCESS 22 } ``` ```toml 1 # Cargo.toml (the relevant part) 2 [dev-dependencies] 3 assert_cmd = "2.2.2" 4 predicates = "3.1.4" ``` tests/cli.rs ```rust 1 use assert_cmd::Command; 2 use predicates::prelude::*; 3 4 #[test] 5 fn adds_two_integers() { 6 Command::cargo_bin("adder") 7 .unwrap() 8 .args(["19", "23"]) 9 .assert() 10 .success() 11 .stdout(predicate::str::contains("42")); 12 } 13 14 #[test] 15 fn rejects_non_integer_input() { 16 Command::cargo_bin("adder") 17 .unwrap() 18 .args(["19", "oops"]) 19 .assert() 20 .failure() 21 .code(2) 22 .stderr(predicate::str::contains("not an integer")); 23 } ``` **Output:** ```text 1 running 2 tests 2 test adds_two_integers ... ok 3 test rejects_non_integer_input ... ok 4 5 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.13s ``` # Test Fixtures: Setup, Teardown, and Shared State > Rust has no beforeEach/afterEach. Build fixtures with helper functions, Drop for RAII teardown, and LazyLock for shared state, mapped from Jest and Vitest habits. In Jest or Vitest you reach for `beforeEach`, `afterEach`, and shared module-level constants to prepare the world your tests run in. Rust has **no lifecycle hooks**. Instead it gives you plain functions, the `Drop` trait, and a couple of lazy-initialization types. This topic maps each fixture habit you already have onto its idiomatic Rust counterpart. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **fixture** is the prepared state a test runs against: a seeded database, a temp directory, a configured client, a couple of sample records. Rust has no `beforeEach`/`afterEach` decorators, so you build fixtures with ordinary **helper functions** (setup), the **`Drop` trait** (RAII teardown that runs even on panic), and **`LazyLock`** / the **`once_cell`** crate for read-only state computed once and shared across tests. The mental shift for a TypeScript developer is that teardown is tied to a value’s *scope*, not to a hook the runner calls for you. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // user-store.test.ts (Vitest / Jest — the API is nearly identical) 2 import { beforeEach, afterEach, describe, expect, it } from "vitest"; 3 import { mkdtempSync, rmSync, writeFileSync, readFileSync } from "node:fs"; 4 import { tmpdir } from "node:os"; 5 import { join } from "node:path"; 6 7 interface User { 8 id: number; 9 name: string; 10 email: string; 11 active: boolean; 12 } 13 14 // A helper constructor: sensible defaults, override what matters. 15 function makeUser(overrides: Partial<User> = {}): User { 16 return { 17 id: 1, 18 name: "Alice", 19 email: "alice@example.com", 20 active: true, 21 ...overrides, 22 }; 23 } 24 25 // Read-only data computed once and shared by every test in the file. 26 const TEST_CONFIG = { baseUrl: "http://localhost:0", timeoutMs: 250 }; 27 28 describe("temp-dir fixture", () => { 29 let dir: string; 30 31 beforeEach(() => { 32 // SETUP: runs before every test 33 dir = mkdtempSync(join(tmpdir(), "store-")); 34 }); 35 36 afterEach(() => { 37 // TEARDOWN: runs after every test, even if it threw 38 rmSync(dir, { recursive: true, force: true }); 39 }); 40 41 it("writes and reads a file", () => { 42 const file = join(dir, "note.txt"); 43 writeFileSync(file, "persisted"); 44 expect(readFileSync(file, "utf8")).toBe("persisted"); 45 }); 46 47 it("uses the shared config", () => { 48 expect(TEST_CONFIG.timeoutMs).toBe(250); 49 }); 50 51 it("builds a customized user", () => { 52 const u = makeUser({ id: 42, active: false }); 53 expect(u.name).toBe("Alice"); // default kept 54 expect(u.active).toBe(false); // override applied 55 }); 56 }); ``` **Key points:** * `beforeEach`/`afterEach` are **lifecycle hooks** the test runner calls for you. * `afterEach` is where you clean up; the runner guarantees it runs even when the test body throws. * `makeUser(overrides)` is a **factory** that fills in defaults: the workhorse fixture pattern. * `TEST_CONFIG` is a module constant, evaluated once when the file is imported. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 // src/lib.rs — the code under test 2 use std::collections::HashMap; 3 4 #[derive(Debug, Clone, PartialEq)] 5 pub struct User { 6 pub id: u32, 7 pub name: String, 8 pub email: String, 9 pub active: bool, 10 } 11 12 impl User { 13 /// A test-friendly constructor: sensible defaults, override what matters. 14 pub fn new(id: u32, name: &str) -> Self { 15 User { 16 id, 17 name: name.to_string(), 18 email: format!("{}@example.com", name.to_lowercase()), 19 active: true, 20 } 21 } 22 } 23 24 #[derive(Debug, Default)] 25 pub struct UserStore { 26 users: HashMap<u32, User>, 27 } 28 29 impl UserStore { 30 pub fn new() -> Self { 31 UserStore { users: HashMap::new() } 32 } 33 pub fn insert(&mut self, user: User) { 34 self.users.insert(user.id, user); 35 } 36 pub fn get(&self, id: u32) -> Option<&User> { 37 self.users.get(&id) 38 } 39 pub fn active_count(&self) -> usize { 40 self.users.values().filter(|u| u.active).count() 41 } 42 } 43 44 #[cfg(test)] 45 mod tests { 46 use super::*; 47 48 // SETUP as a plain helper function — call it from each test that needs it. 49 fn store_with_two_users() -> UserStore { 50 let mut store = UserStore::new(); 51 store.insert(User::new(1, "Alice")); 52 store.insert(User::new(2, "Bob")); 53 store 54 } 55 56 #[test] 57 fn finds_an_existing_user() { 58 let store = store_with_two_users(); 59 let alice = store.get(1).expect("user 1 should exist"); 60 assert_eq!(alice.name, "Alice"); 61 assert_eq!(alice.email, "alice@example.com"); 62 } 63 64 #[test] 65 fn counts_active_users() { 66 let mut store = store_with_two_users(); 67 let mut carol = User::new(3, "Carol"); 68 carol.active = false; 69 store.insert(carol); 70 assert_eq!(store.active_count(), 2); 71 } 72 73 #[test] 74 fn override_a_single_field() { 75 // Start from the constructor, tweak one field — the `makeUser` pattern. 76 let mut user = User::new(42, "Dave"); 77 user.email = "dave@corp.internal".to_string(); 78 assert_eq!(user.id, 42); 79 assert!(user.active); 80 } 81 } ``` Running it produces real output (here, the helper-function tests plus the rest of this topic’s examples in one crate): ```text 1 running 12 tests 2 test more::tests::appends_to_shared_log ... ok 3 test shared::tests::reads_once_cell_lazy ... ok 4 test shared::tests::reads_shared_config_a ... ok 5 test shared::tests::reads_shared_config_b ... ok 6 test more::tests::env_var_is_restored_after_the_test ... ok 7 test tests::counts_active_users ... ok 8 test tests::finds_an_existing_user ... ok 9 test tests::override_a_single_field ... ok 10 test realworld::tests::parses_explicit_values ... ok 11 test realworld::tests::falls_back_to_defaults ... ok 12 test more::tests::teardown_runs_even_when_the_test_panics - should panic ... ok 13 test shared::tests::writes_and_reads_inside_a_temp_dir ... ok 14 15 test result: ok. 12 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` > **Note:** This uses the repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) using the 2024 edition. `cargo new` selects the newest edition automatically, so the snippets here run as-is. `LazyLock` (used below) has been part of the standard library since Rust 1.80. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Setup is a function, not a hook [Section titled “Setup is a function, not a hook”](#setup-is-a-function-not-a-hook) There is no `#[before_each]` attribute. The idiomatic replacement is a **helper function** that builds and returns the fixture: ```rust 1 fn store_with_two_users() -> UserStore { /* ... */ } ``` Each test calls it explicitly: `let store = store_with_two_users();`. This is *more* verbose than `beforeEach` by one line per test, but it is also more honest: you can see exactly which fixture each test uses, and a test that needs a different setup just calls a different helper. There is no hidden, file-wide `beforeEach` quietly running before every case. Because each `#[test]` gets a fresh call to the helper, you also get **fresh state per test for free**, the equivalent of `beforeEach` (not `beforeAll`). Rust runs tests in **parallel threads by default**, so isolated per-test state is required for correctness, not just convenient (more on this under Common Pitfalls). ### Helper constructors replace `makeUser(overrides)` [Section titled “Helper constructors replace makeUser(overrides)”](#helper-constructors-replace-makeuseroverrides) TypeScript’s spread-with-defaults trick (`{ ...defaults, ...overrides }`) has no direct syntax twin, but Rust offers two idioms: 1. **A constructor with the common arguments**, like `User::new(id, name)`, then mutate the one or two fields a test cares about. 2. **Struct update syntax** (`..`) when you have a default value to start from: ```rust 1 #[derive(Debug, Clone, PartialEq)] 2 struct User { 3 id: u32, 4 name: String, 5 email: String, 6 active: bool, 7 } 8 9 impl Default for User { 10 fn default() -> Self { 11 User { 12 id: 1, 13 name: "Alice".into(), 14 email: "alice@example.com".into(), 15 active: true, 16 } 17 } 18 } 19 20 fn main() { 21 // The closest analog to `makeUser({ id: 42, active: false })`: 22 let u = User { id: 42, active: false, ..User::default() }; 23 println!("{u:?}"); 24 } ``` The `..User::default()` fills in every field you did not name — the same role as `...defaults` in a TypeScript object literal. ### `Drop` is your `afterEach` [Section titled “Drop is your afterEach”](#drop-is-your-aftereach) Rust ties cleanup to a value’s **scope** instead of to a runner hook. When a value goes out of scope, Rust calls its `drop` method (if it has one). Implement `Drop` and the cleanup runs automatically at the end of the test, and, importantly, **during unwinding if the test panics** (an `assert!` failure panics). That is exactly the guarantee `afterEach` gives you, but enforced by the language rather than the runner: ```rust 1 struct TempDir { 2 path: std::path::PathBuf, 3 } 4 5 impl TempDir { 6 fn new(label: &str) -> std::io::Result<Self> { 7 let mut path = std::env::temp_dir(); 8 path.push(format!("rs4ts_test_{label}_{}", std::process::id())); 9 std::fs::create_dir_all(&path)?; 10 Ok(TempDir { path }) // SETUP 11 } 12 fn path(&self) -> &std::path::Path { 13 &self.path 14 } 15 } 16 17 impl Drop for TempDir { 18 fn drop(&mut self) { 19 // TEARDOWN — runs at end of scope, even on panic. 20 let _ = std::fs::remove_dir_all(&self.path); 21 } 22 } 23 24 fn demo() -> std::io::Result<()> { 25 let dir = TempDir::new("rw")?; // setup 26 let file = dir.path().join("note.txt"); 27 std::fs::write(&file, b"persisted")?; 28 assert_eq!(std::fs::read_to_string(&file)?, "persisted"); 29 Ok(()) 30 // `dir` drops here -> directory removed. No explicit cleanup call. 31 } ``` This `Drop`-on-scope-exit pattern is called **RAII** (Resource Acquisition Is Initialization): acquiring the resource and binding its lifetime are the same act. You hold the guard in a `let` binding; when the binding dies, the resource is released. ### `LazyLock` and `once_cell` for shared, read-only state [Section titled “LazyLock and once\_cell for shared, read-only state”](#lazylock-and-once_cell-for-shared-read-only-state) TypeScript’s module-level `const TEST_CONFIG = ...` runs once and is visible everywhere in the file. Rust `static` items must be initialized with a *constant expression*, so you cannot write `static CONFIG: HashMap<...> = { ... }` with runtime work. The fix is a lazily-initialized static, initialized the first time it is touched, then shared: ```rust 1 use std::collections::HashMap; 2 use std::sync::LazyLock; 3 4 // Computed once, on first access; shared across every test. Read-only. 5 static TEST_CONFIG: LazyLock<HashMap<&'static str, &'static str>> = LazyLock::new(|| { 6 let mut m = HashMap::new(); 7 m.insert("base_url", "http://localhost:0"); 8 m.insert("timeout_ms", "250"); 9 m 10 }); 11 12 fn main() { 13 assert_eq!(TEST_CONFIG["base_url"], "http://localhost:0"); 14 assert_eq!(TEST_CONFIG["timeout_ms"], "250"); 15 } ``` `LazyLock<T>` is thread-safe: even though tests run on many threads, the closure runs **exactly once** and all threads see the same value. This is the *shared-across-tests* behavior of a module constant, plus the parallel-safety Rust’s test harness needs. Before `LazyLock` was stabilized, the community crate **`once_cell`** filled this role, and you will still see it everywhere. Its `Lazy<T>` type is a drop-in equivalent: Cargo.toml ```toml 1 [dependencies] 2 once_cell = "1" ``` ```rust 1 use once_cell::sync::Lazy; 2 3 static GREETING: Lazy<String> = Lazy::new(|| format!("hello, {}", "world")); 4 5 fn main() { 6 assert_eq!(&*GREETING, "hello, world"); 7 } ``` > **Tip:** On a current toolchain, prefer the standard library’s `LazyLock` for new code; no dependency required. Reach for `once_cell` only when you must support a Rust version older than 1.80, or when you need its richer API (such as `OnceCell`/`Lazy` in non-`'static` positions). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concern | Jest / Vitest | Rust | | ---------------------- | ------------------------------------------------ | ------------------------------------------------------- | | Per-test setup | `beforeEach(fn)` | Call a helper function from each test | | One-time setup | `beforeAll(fn)` | `LazyLock` / `once_cell` static (lazy, once) | | Teardown | `afterEach(fn)` | `impl Drop` on a guard value (RAII) | | Teardown on failure | Runner guarantees `afterEach` runs | Language runs `drop` during unwinding | | Default-with-overrides | `{ ...defaults, ...overrides }` | Constructor + mutate, or `..Default::default()` | | Shared module constant | top-level `const` | `static` + `LazyLock` (runtime init needs laziness) | | Test isolation | Opt-in; files isolated, cases share module scope | Each `#[test]` is a fresh function; parallel by default | | Ordering of cleanups | Registration order, reversed | Reverse declaration order of `let` bindings | A few of these deserve emphasis: * **No magic ordering.** With `beforeEach` the runner decides when your setup fires. In Rust the setup runs exactly where you call it, and teardown runs exactly when the binding goes out of scope — in **reverse order** of declaration, like a stack. This is predictable and visible in the source. * **Teardown can fail loudly or be ignored.** `Drop::drop` returns `()` and cannot return a `Result`. So you typically *ignore* cleanup errors (`let _ = std::fs::remove_dir_all(...)`), because panicking inside `drop` during an already-unwinding panic aborts the whole process. Jest’s `afterEach` can `throw` and surface a second failure; Rust cannot, by design. * **Parallelism is the default, not an option.** Vitest isolates files but runs cases within a file sequentially. Rust runs `#[test]` functions across a thread pool. Fixtures that touch shared, *mutable* global state must synchronize (see Pitfalls). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Dropping the guard immediately with `let _` [Section titled “Pitfall 1: Dropping the guard immediately with let \_”](#pitfall-1-dropping-the-guard-immediately-with-let-_) The single most common RAII mistake: binding a guard to `_` (a bare underscore) instead of a named variable. `let _ = expr;` evaluates `expr` and **drops the result at the end of that statement**: your fixture is torn down before the test body even starts. ```rust 1 struct Guard(&'static str); 2 impl Drop for Guard { 3 fn drop(&mut self) { 4 println!("dropping {}", self.0); 5 } 6 } 7 8 fn main() { 9 let _ = Guard("temp_a"); // drops IMMEDIATELY (end of this statement) 10 println!("after let _"); 11 12 let _guard = Guard("temp_b"); // lives until end of scope 13 println!("after let _guard"); 14 } ``` Real output, note that `temp_a` is destroyed *before* “after let \_” prints: ```text 1 dropping temp_a 2 after let _ 3 after let _guard 4 dropping temp_b ``` A name beginning with an underscore (`_guard`) still binds and keeps the value alive; a bare `_` does not. The compiler will not warn you here — this is a logic bug, not a type error — so train your eye for it. > **Warning:** `let _guard = TempDir::new()?;` is correct; `let _ = TempDir::new()?;` deletes the temp dir on the very next line. Always bind RAII guards to a named variable. ### Pitfall 2: Putting non-`Sync` state in a `static` [Section titled “Pitfall 2: Putting non-Sync state in a static”](#pitfall-2-putting-non-sync-state-in-a-static) Coming from JavaScript’s single-threaded model, it is tempting to keep mutable shared state in a `static RefCell`. Because Rust runs tests in parallel, the compiler refuses: a `static` must be `Sync`, and `RefCell` is not. ```rust 1 use std::cell::RefCell; 2 use std::sync::LazyLock; 3 4 // does not compile (error[E0277]: `RefCell<u32>` cannot be shared between threads safely) 5 static COUNTER: LazyLock<RefCell<u32>> = LazyLock::new(|| RefCell::new(0)); 6 7 fn main() { 8 *COUNTER.borrow_mut() += 1; 9 } ``` The real error from `rustc`: ```text 1 error[E0277]: `RefCell<u32>` cannot be shared between threads safely 2 --> src/main.rs:5:17 3 | 4 5 | static COUNTER: LazyLock<RefCell<u32>> = LazyLock::new(|| RefCell::new(0)); 5 | ^^^^^^^^^^^^^^^^^^^^^^ `RefCell<u32>` cannot be shared between threads safely 6 | 7 = help: the trait `Sync` is not implemented for `RefCell<u32>` 8 = note: if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` instead 9 = note: required for `LazyLock<RefCell<u32>>` to implement `Sync` 10 = note: shared static variables must have a type that implements `Sync` ``` The fix is to use a thread-safe interior-mutability type: `Mutex`, `RwLock`, or an atomic such as `AtomicU32`. (Smart pointers and interior mutability are covered in [Section 10 — Smart Pointers](/10-smart-pointers/).) ```rust 1 use std::sync::{LazyLock, Mutex}; 2 3 static CALL_LOG: LazyLock<Mutex<Vec<String>>> = LazyLock::new(|| Mutex::new(Vec::new())); 4 5 fn main() { 6 CALL_LOG.lock().unwrap().push("event".to_string()); 7 assert_eq!(CALL_LOG.lock().unwrap().len(), 1); 8 } ``` ### Pitfall 3: Expecting `beforeEach`-style isolation from shared mutable statics [Section titled “Pitfall 3: Expecting beforeEach-style isolation from shared mutable statics”](#pitfall-3-expecting-beforeeach-style-isolation-from-shared-mutable-statics) If two tests both push into one global `Mutex<Vec<_>>`, they see each other’s data; there is no per-test reset. With parallel execution, the *order* is nondeterministic too. Prefer fresh per-test fixtures (a helper that returns a brand-new value). Reserve shared mutable statics for things that are genuinely process-wide and either append-only or order-independent. If you truly need a test to run alone, gate the shared resource behind a `Mutex` and hold the lock for the whole test, or run with `cargo test -- --test-threads=1` to force sequential execution. ### Pitfall 4: Forgetting `Drop` does not run on `std::process::exit` [Section titled “Pitfall 4: Forgetting Drop does not run on std::process::exit”](#pitfall-4-forgetting-drop-does-not-run-on-stdprocessexit) `Drop` runs on normal scope exit and during a panic *unwind*. It does **not** run if the process is killed with `std::process::exit`, or if a panic is configured to `abort` instead of unwind (`panic = "abort"`). Test teardown relies on unwinding, which is the default in the test profile, so this rarely bites in tests — but do not put critical, must-happen cleanup solely in `Drop` if your binary might `exit` mid-test-helper. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Prefer a small helper function over a clever macro** for setup. `fn store_with_two_users() -> UserStore` reads clearly and composes; call several helpers in one test if needed. * **Return the fixture; do not stash it in a global.** Returning a value gives each test its own copy and keeps parallel runs correct. * **Use the `tempfile` crate for temp files and directories.** It generates collision-free names and deletes on drop, so you get the RAII guard for free without hand-rolling `TempDir`. Cargo.toml ```toml 1 [dev-dependencies] 2 tempfile = "3" ``` * **Make teardown idempotent and error-tolerant.** Because `drop` cannot return `Result`, swallow cleanup errors with `let _ = ...` rather than `unwrap()`, which would risk a double-panic. * **Bind guards to named variables**, even when unused, with a leading-underscore name (`_guard`) to silence the unused-variable warning while still keeping the value alive. * **Reach for `LazyLock` (std) first**, falling back to `once_cell` only for compatibility or its extra API surface. * **Keep shared statics read-only when you can.** Read-only `LazyLock` data is trivially safe across threads; mutable shared state always needs a `Mutex`/`RwLock`/atomic and careful thought about isolation. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A configuration loader, tested against a *real* file in a real temp directory. The fixture creates a temp dir, writes a config file into it, and returns both the `TempDir` guard and the file path. The test binds the guard, so the directory survives for the whole test and is deleted automatically when the guard drops — even if an assertion fails. src/lib.rs ```rust 1 use std::path::Path; 2 3 #[derive(Debug, PartialEq)] 4 pub struct Config { 5 pub port: u16, 6 pub verbose: bool, 7 } 8 9 /// Parses a tiny `key=value` config file. 10 pub fn load_config(path: &Path) -> std::io::Result<Config> { 11 let text = std::fs::read_to_string(path)?; 12 let mut port = 8080; 13 let mut verbose = false; 14 for line in text.lines() { 15 let Some((key, value)) = line.split_once('=') else { continue }; 16 match key.trim() { 17 "port" => port = value.trim().parse().unwrap_or(8080), 18 "verbose" => verbose = value.trim() == "true", 19 _ => {} 20 } 21 } 22 Ok(Config { port, verbose }) 23 } 24 25 #[cfg(test)] 26 mod tests { 27 use super::*; 28 use std::io::Write; 29 use tempfile::TempDir; // dev-dependency: tempfile = "3" 30 31 // Fixture: a temp dir holding a config file with the given body. 32 // The returned `TempDir` is the RAII guard; the caller binds it so the 33 // directory lives for the whole test and is deleted on drop. 34 fn config_fixture(body: &str) -> (TempDir, std::path::PathBuf) { 35 let dir = TempDir::new().expect("create temp dir"); 36 let path = dir.path().join("app.conf"); 37 let mut file = std::fs::File::create(&path).expect("create file"); 38 file.write_all(body.as_bytes()).expect("write body"); 39 (dir, path) 40 } 41 42 #[test] 43 fn parses_explicit_values() { 44 let (_dir, path) = config_fixture("port = 9000\nverbose = true\n"); 45 let cfg = load_config(&path).unwrap(); 46 assert_eq!(cfg, Config { port: 9000, verbose: true }); 47 } 48 49 #[test] 50 fn falls_back_to_defaults() { 51 let (_dir, path) = config_fixture("# empty file\n"); 52 let cfg = load_config(&path).unwrap(); 53 assert_eq!(cfg, Config { port: 8080, verbose: false }); 54 } 55 } ``` Real output: ```text 1 running 2 tests 2 test realworld::tests::parses_explicit_values ... ok 3 test realworld::tests::falls_back_to_defaults ... ok 4 5 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` Notice the binding `let (_dir, path) = config_fixture(...)`. The `_dir` part keeps the `TempDir` guard alive for the body of the test; if you had written `let (_, path) = ...`, the temp directory would be deleted *before* `load_config` ran (Pitfall 1). The leading underscore silences the unused-variable warning without dropping the value. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`std::sync::LazyLock`](https://doc.rust-lang.org/std/sync/struct.LazyLock.html): standard-library lazy static initialization. * [The `Drop` trait](https://doc.rust-lang.org/std/ops/trait.Drop.html) and [the Drop chapter of the Book](https://doc.rust-lang.org/book/ch15-03-drop.html): RAII and deterministic destruction. * [The `once_cell` crate](https://docs.rs/once_cell/): `Lazy`/`OnceCell` for older toolchains and richer use cases. * [The `tempfile` crate](https://docs.rs/tempfile/) — temp files and directories that clean themselves up on drop. * [`std::sync::Mutex`](https://doc.rust-lang.org/std/sync/struct.Mutex.html) — thread-safe interior mutability for shared fixtures. * Within this section: [Unit Tests](/13-testing/00-unit-tests/) for the `#[test]` and `#[cfg(test)]` basics, [Test Organization](/13-testing/01-test-organization/) for where fixtures live, [Should Panic & Result tests](/13-testing/03-should-panic/) for `Result`-returning tests with `?`, [Integration Tests](/13-testing/04-integration-tests/) for shared helper modules under `tests/`, and [Mocking](/13-testing/06-mocking/) for trait-based test doubles. * Related guide sections: [Section 10 — Smart Pointers](/10-smart-pointers/) for `Mutex`/`RwLock`/interior mutability, and [Section 14 — Macros](/14-macros/) if you eventually want to abstract repetitive fixture boilerplate. * New to Rust testing? Start at [Section 00 — Introduction](/00-introduction/), [Section 01 — Getting Started](/01-getting-started/), and [Section 02 — Basics](/02-basics/). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A builder-style fixture [Section titled “Exercise 1: A builder-style fixture”](#exercise-1-a-builder-style-fixture) **Difficulty:** Easy **Objective:** Replace TypeScript’s `makeUser(overrides)` with an idiomatic Rust test builder. **Instructions:** Given this struct, write a `UserBuilder` inside a `#[cfg(test)] mod tests` that starts from sensible defaults and lets a test override fields fluently (`.id(7).name("Eve").inactive().build()`). Write two tests: one that overrides several fields, and one that relies entirely on the defaults. ```rust 1 #[derive(Debug, PartialEq, Clone)] 2 pub struct User { 3 pub id: u32, 4 pub name: String, 5 pub active: bool, 6 } 7 8 #[cfg(test)] 9 mod tests { 10 use super::*; 11 12 struct UserBuilder { 13 user: User, 14 } 15 impl UserBuilder { 16 fn new() -> Self { /* ??? */ } 17 // TODO: id(...), name(...), inactive(), build() 18 } 19 20 #[test] 21 fn builder_defaults_then_overrides() { 22 // TODO 23 } 24 } ``` Solution ```rust 1 #[derive(Debug, PartialEq, Clone)] 2 pub struct User { 3 pub id: u32, 4 pub name: String, 5 pub active: bool, 6 } 7 8 #[cfg(test)] 9 mod tests { 10 use super::*; 11 12 // A test builder: start from a default user, override fields fluently. 13 struct UserBuilder { 14 user: User, 15 } 16 impl UserBuilder { 17 fn new() -> Self { 18 UserBuilder { 19 user: User { id: 1, name: "Default".into(), active: true }, 20 } 21 } 22 fn id(mut self, id: u32) -> Self { 23 self.user.id = id; 24 self 25 } 26 fn name(mut self, name: &str) -> Self { 27 self.user.name = name.into(); 28 self 29 } 30 fn inactive(mut self) -> Self { 31 self.user.active = false; 32 self 33 } 34 fn build(self) -> User { 35 self.user 36 } 37 } 38 39 #[test] 40 fn builder_defaults_then_overrides() { 41 let u = UserBuilder::new().id(7).name("Eve").inactive().build(); 42 assert_eq!(u, User { id: 7, name: "Eve".into(), active: false }); 43 } 44 45 #[test] 46 fn builder_uses_defaults_when_untouched() { 47 let u = UserBuilder::new().build(); 48 assert_eq!(u.id, 1); 49 assert!(u.active); 50 } 51 } ``` Each setter takes `self` by value, mutates, and returns `self`, so calls chain. `build()` consumes the builder and hands back the finished `User`. This output is verified: both tests pass with `cargo test`. ### Exercise 2: An environment-variable RAII guard [Section titled “Exercise 2: An environment-variable RAII guard”](#exercise-2-an-environment-variable-raii-guard) **Difficulty:** Medium **Objective:** Build a guard that sets an environment variable on creation and restores the previous value on drop — Rust’s answer to a `beforeEach`/`afterEach` pair around `process.env`. **Instructions:** Write an `EnvGuard` with `EnvGuard::set(key, value)` that records the prior value, sets the new one, and restores (or removes) the original in its `Drop` impl. Then write a test proving the variable is gone again once the guard’s scope ends. > **Note:** As of recent Rust editions, `std::env::set_var` / `remove_var` are `unsafe` because mutating the environment is not thread-safe. Wrap the calls in `unsafe { ... }` and keep the test single-threaded around that variable. Solution ```rust 1 #[cfg(test)] 2 mod tests { 3 struct EnvGuard { 4 key: String, 5 previous: Option<String>, 6 } 7 8 impl EnvGuard { 9 fn set(key: &str, value: &str) -> Self { 10 let previous = std::env::var(key).ok(); 11 // SAFETY: this test does not spawn threads that touch the env. 12 unsafe { std::env::set_var(key, value) }; 13 EnvGuard { key: key.to_string(), previous } 14 } 15 } 16 17 impl Drop for EnvGuard { 18 fn drop(&mut self) { 19 unsafe { 20 match &self.previous { 21 Some(v) => std::env::set_var(&self.key, v), 22 None => std::env::remove_var(&self.key), 23 } 24 } 25 } 26 } 27 28 #[test] 29 fn env_var_is_restored_after_the_test() { 30 assert!(std::env::var("APP_FIXTURE_MODE").is_err()); 31 { 32 let _guard = EnvGuard::set("APP_FIXTURE_MODE", "test"); 33 assert_eq!(std::env::var("APP_FIXTURE_MODE").unwrap(), "test"); 34 } // guard drops here -> var removed 35 assert!(std::env::var("APP_FIXTURE_MODE").is_err()); 36 } 37 } ``` The guard captures the previous value in `set`, applies the new one, and restores it in `drop`. Binding it to `_guard` (named, not bare `_`) keeps it alive for the inner block. This test passes; verified with `cargo test`. ### Exercise 3: A unique-ID fixture for parallel tests [Section titled “Exercise 3: A unique-ID fixture for parallel tests”](#exercise-3-a-unique-id-fixture-for-parallel-tests) **Difficulty:** Medium **Objective:** Provide a shared, thread-safe fixture that hands out a unique ID per call so that tests running in parallel never collide. **Instructions:** Inside a test module, create a `static` counter and a `fresh_id()` helper that returns a new value each call. It must be safe to call from multiple threads (remember: Rust runs tests in parallel). Write two tests that each grab two IDs and assert they differ. Solution ```rust 1 #[cfg(test)] 2 mod tests { 3 use std::sync::atomic::{AtomicU32, Ordering}; 4 5 // Fixture helper: hand out a fresh, unique id per call so parallel 6 // tests never collide on the same record. 7 static NEXT_ID: AtomicU32 = AtomicU32::new(1); 8 9 fn fresh_id() -> u32 { 10 NEXT_ID.fetch_add(1, Ordering::Relaxed) 11 } 12 13 #[test] 14 fn ids_are_unique_1() { 15 let a = fresh_id(); 16 let b = fresh_id(); 17 assert_ne!(a, b); 18 } 19 20 #[test] 21 fn ids_are_unique_2() { 22 let a = fresh_id(); 23 let b = fresh_id(); 24 assert_ne!(a, b); 25 } 26 } ``` `AtomicU32::fetch_add` atomically increments and returns the previous value, so every caller — on any thread — gets a distinct number. No `Mutex` is needed for a simple counter, and no lazy initialization is required because `AtomicU32::new` is a `const fn` usable directly in a `static`. Both tests pass; verified with `cargo test`. # Mocking > Rust replaces vi.fn() and jest.mock() with trait-based dependency injection and mockall's #[automock]. Mocks self-verify on drop and are checked by the compiler. In Jest or Vitest you reach for `vi.fn()`, `jest.mock()`, or a manual fake whenever a unit under test depends on a database, an HTTP call, or the clock. Rust has no module-level monkey-patching: there is no `jest.mock("./db")` that rewrites imports at load time. Instead, Rust pushes you toward a cleaner pattern you already know from TypeScript: **program against a trait (interface), inject the dependency, and substitute a test double**. For the boilerplate-heavy cases, the [`mockall`](https://docs.rs/mockall) crate generates the double for you. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **mock** is a stand-in for a real dependency that lets a test run fast, deterministically, and offline, and lets you assert *how* the dependency was used. In Rust the idiomatic foundation is **dependency injection through a trait**: your code accepts something that implements a trait, and tests pass either a small hand-written struct or a `mockall`-generated `Mock…` type. Unlike Vitest’s `vi.mock`, nothing is patched at runtime; the substitution happens through Rust’s ordinary type system, which means the compiler checks your test doubles just like production code. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) A `WelcomeService` that looks up a user’s email and sends a welcome message. The two collaborators (the repository and the mailer) are described by interfaces, then mocked with Vitest’s `vi.fn()`. welcome.ts ```typescript 1 export interface EmailSender { 2 send(to: string, subject: string, body: string): Promise<string>; 3 } 4 5 export interface UserRepo { 6 findEmail(userId: number): Promise<string | null>; 7 } 8 9 export class WelcomeService { 10 constructor( 11 private readonly repo: UserRepo, 12 private readonly mailer: EmailSender, 13 ) {} 14 15 async welcome(userId: number): Promise<string> { 16 const email = await this.repo.findEmail(userId); 17 if (email === null) { 18 throw new Error(`no email for user ${userId}`); 19 } 20 return this.mailer.send(email, "Welcome!", "Thanks for joining."); 21 } 22 } ``` welcome.test.ts ```typescript 1 import { describe, it, expect, vi } from "vitest"; 2 import { WelcomeService, type EmailSender, type UserRepo } from "./welcome"; 3 4 describe("WelcomeService", () => { 5 it("emails a known user", async () => { 6 const repo: UserRepo = { findEmail: vi.fn().mockResolvedValue("ada@x.com") }; 7 const mailer: EmailSender = { send: vi.fn().mockResolvedValue("msg-1") }; 8 9 const svc = new WelcomeService(repo, mailer); 10 const id = await svc.welcome(42); 11 12 expect(id).toBe("msg-1"); 13 expect(mailer.send).toHaveBeenCalledWith( 14 "ada@x.com", 15 "Welcome!", 16 "Thanks for joining.", 17 ); 18 expect(mailer.send).toHaveBeenCalledTimes(1); 19 }); 20 21 it("does not send when the user is unknown", async () => { 22 const repo: UserRepo = { findEmail: vi.fn().mockResolvedValue(null) }; 23 const mailer: EmailSender = { send: vi.fn() }; 24 25 const svc = new WelcomeService(repo, mailer); 26 await expect(svc.welcome(7)).rejects.toThrow("no email for user 7"); 27 expect(mailer.send).not.toHaveBeenCalled(); 28 }); 29 }); ``` Running `npx vitest run`: ```text 1 RUN v4.1.7 2 3 Test Files 1 passed (1) 4 Tests 2 passed (2) ``` Three things a JavaScript developer leans on here: * **Interfaces** describe the collaborators (`EmailSender`, `UserRepo`). * `vi.fn()` builds a fake function with a canned return value (`mockResolvedValue`). * The same fake **records calls**, so `toHaveBeenCalledWith` / `toHaveBeenCalledTimes` / `not.toHaveBeenCalled` verify the interaction. Rust keeps the first idea wholesale, replaces `vi.fn()` with a generated mock, and, importantly, checks expectations at compile time and at the moment the mock is dropped. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same service, with `EmailSender` and `UserRepo` as **traits** and the mocks generated by `mockall`’s `#[automock]`. Add the crate as a **dev-dependency** so it never ships in your release binary: ```bash 1 cargo add mockall --dev ``` Cargo.toml ```toml 1 [dev-dependencies] 2 mockall = "0.14.0" ``` src/lib.rs ```rust 1 //! A welcome-email service with two injected dependencies, mocked in tests. 2 3 /// Sends transactional email. The real implementation talks to a provider. 4 #[cfg_attr(test, mockall::automock)] 5 pub trait EmailSender { 6 /// Returns the provider's message id on success. 7 fn send(&self, to: &str, subject: &str, body: &str) -> Result<String, String>; 8 } 9 10 /// Reads user contact details from storage. 11 #[cfg_attr(test, mockall::automock)] 12 pub trait UserRepo { 13 fn find_email(&self, user_id: u64) -> Result<Option<String>, String>; 14 } 15 16 /// Orchestrates the welcome flow. Generic over its dependencies so the 17 /// concrete types (real or mock) are chosen by the caller. 18 pub struct WelcomeService<R, S> { 19 repo: R, 20 mailer: S, 21 } 22 23 impl<R: UserRepo, S: EmailSender> WelcomeService<R, S> { 24 pub fn new(repo: R, mailer: S) -> Self { 25 WelcomeService { repo, mailer } 26 } 27 28 /// Look up the user's email and send the welcome message. 29 pub fn welcome(&self, user_id: u64) -> Result<String, String> { 30 let email = self 31 .repo 32 .find_email(user_id)? 33 .ok_or_else(|| format!("no email for user {user_id}"))?; 34 35 self.mailer.send(&email, "Welcome!", "Thanks for joining.") 36 } 37 } 38 39 #[cfg(test)] 40 mod tests { 41 use super::*; 42 use mockall::predicate::*; 43 44 #[test] 45 fn emails_a_known_user() { 46 let mut repo = MockUserRepo::new(); 47 repo.expect_find_email() 48 .with(eq(42u64)) 49 .times(1) 50 .returning(|_| Ok(Some("ada@example.com".to_string()))); 51 52 let mut mailer = MockEmailSender::new(); 53 mailer 54 .expect_send() 55 .with( 56 eq("ada@example.com"), 57 eq("Welcome!"), 58 eq("Thanks for joining."), 59 ) 60 .times(1) 61 .returning(|_, _, _| Ok("msg-1".to_string())); 62 63 let svc = WelcomeService::new(repo, mailer); 64 assert_eq!(svc.welcome(42), Ok("msg-1".to_string())); 65 } 66 67 #[test] 68 fn does_not_send_when_user_is_unknown() { 69 let mut repo = MockUserRepo::new(); 70 repo.expect_find_email().returning(|_| Ok(None)); 71 72 let mut mailer = MockEmailSender::new(); 73 // No call expected; `never()` makes the intent explicit and fails loudly. 74 mailer.expect_send().never(); 75 76 let svc = WelcomeService::new(repo, mailer); 77 assert_eq!(svc.welcome(7), Err("no email for user 7".to_string())); 78 } 79 } ``` Running `cargo test`: ```text 1 running 2 tests 2 test tests::does_not_send_when_user_is_unknown ... ok 3 test tests::emails_a_known_user ... ok 4 5 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` The shape mirrors the Vitest version almost line for line: `with(...)` is `toHaveBeenCalledWith`, `times(1)` is `toHaveBeenCalledTimes(1)`, `never()` is `not.toHaveBeenCalled()`, and `returning(...)` is `mockResolvedValue`. The big difference is *when* mismatches are caught. See [Detailed Explanation](#detailed-explanation). *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `#[cfg_attr(test, mockall::automock)]` — generate a mock, only in test builds [Section titled “#\[cfg\_attr(test, mockall::automock)\] — generate a mock, only in test builds”](#cfg_attrtest-mockallautomock--generate-a-mock-only-in-test-builds) ```rust 1 #[cfg_attr(test, mockall::automock)] 2 pub trait EmailSender { 3 fn send(&self, to: &str, subject: &str, body: &str) -> Result<String, String>; 4 } ``` `#[automock]` is a procedural macro that reads a trait and emits a struct named `Mock<TraitName>` (here `MockEmailSender`) that implements the trait. Wrapping it in `#[cfg_attr(test, ...)]` means “apply this attribute **only** when compiling tests.” In a normal `cargo build`, the macro does not run, the `MockEmailSender` type does not exist, and `mockall` is not linked, which is exactly why it belongs in `[dev-dependencies]`. (`#[cfg_attr]` and `#[cfg(test)]` are the same conditional-compilation machinery introduced in [Unit Tests](/13-testing/00-unit-tests/); attributes themselves are covered in [Macros](/14-macros/).) > **Note:** `#[automock]` is the closest Rust gets to Jest’s “auto-mock a whole module.” But it operates on **one trait**, not a file of exports, and it generates a concrete type you instantiate explicitly: there is no hidden module rewriting. ### `MockEmailSender::new()` and `expect_*` — programming the double [Section titled “MockEmailSender::new() and expect\_\* — programming the double”](#mockemailsendernew-and-expect_--programming-the-double) ```rust 1 let mut mailer = MockEmailSender::new(); 2 mailer 3 .expect_send() 4 .with(eq("ada@example.com"), eq("Welcome!"), eq("Thanks for joining.")) 5 .times(1) 6 .returning(|_, _, _| Ok("msg-1".to_string())); ``` For every trait method `send`, `#[automock]` generates a matching `expect_send()` builder. Each call to `expect_send()` creates one **expectation**: a rule describing what arguments to match, how many times it may be called, and what to return: * **`.with(...)`** sets argument matchers, one per parameter, using **predicates** from `mockall::predicate` (`eq`, `gt`, `ge`, `function`, `always`, …). It is the analogue of `toHaveBeenCalledWith`, except it is enforced *as the call happens*. * **`.times(1)`** sets the call-count expectation (also `.times(0..=3)`, `.never()`, `.once()`). * **`.returning(closure)`** supplies the canned result. The closure receives the same arguments the method was called with, so the return value can depend on the input. The mock must be `mut` because each `expect_*` mutates its internal expectation list. ### `eq(42u64)` — predicates and the `u64` suffix [Section titled “eq(42u64) — predicates and the u64 suffix”](#eq42u64--predicates-and-the-u64-suffix) ```rust 1 repo.expect_find_email().with(eq(42u64)).times(1).returning(|_| Ok(Some("ada@example.com".to_string()))); ``` `eq` builds a predicate that matches by `==`. The `u64` suffix on `42` is not decorative: `find_email` takes a `u64`, and without the suffix Rust would default the literal to `i32`, so `eq(42)` would be `eq(42i32)` and fail to type-check against a `u64` parameter. This is the kind of static check that has no equivalent in `vi.fn()`, where a number is just a number. ### `returning(|_, _, _| ...)` — closures stand in for the implementation [Section titled “returning(|\_, \_, \_| ...) — closures stand in for the implementation”](#returning_-_-_---closures-stand-in-for-the-implementation) The closure passed to `.returning` takes one parameter per method argument; here we ignore all three with `_`. The closure must satisfy `Send` because `mockall` mocks are thread-safe by default (so they work in Rust’s parallel test harness). If you try to capture a non-`Send` type like `Rc<…>`, the compiler rejects it: reach for `Arc` and an atomic instead (shown in [Best Practices](#best-practices)). ### Verification happens at **drop**, not at an explicit assert [Section titled “Verification happens at drop, not at an explicit assert”](#verification-happens-at-drop-not-at-an-explicit-assert) This is the single most important mental-model shift from Jest/Vitest. In Vitest you *pull* facts out of a spy after the fact: `expect(mailer.send).toHaveBeenCalledTimes(1)`. In `mockall`, the count is part of the expectation, and it is checked automatically when the mock value goes out of scope (its `Drop` runs). If `times(1)` was set but `send` was never called, the *destructor* panics and the test fails, even though there is no assertion line. There is nothing to remember to write; conversely, a mock you build but never use will still verify itself. > **Tip:** Because verification is tied to drop, keep mocks owned by the test (or by the service the test owns). The `WelcomeService::new(repo, mailer)` call moves both mocks into the service, and when the service drops at the end of the test, the mocks drop with it and verify. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | Jest / Vitest | Rust (`mockall`) | | ------------------------- | ----------------------------------------------------- | --------------------------------------------------------- | | What you mock | a module, function, or object via `vi.mock` / `vi.fn` | a **trait**, via `#[automock]` or `mock!` | | Substitution mechanism | runtime monkey-patching of imports | the type system: you pass a different concrete type | | Build cost in production | the test framework is a dependency | `[dev-dependencies]`; zero code in release builds | | Canned return | `mockFn.mockResolvedValue(x)` | \`.returning( | | Argument check | `expect(fn).toHaveBeenCalledWith(a)` (after the fact) | `.with(eq(a))` (enforced at call time) | | Call-count check | `toHaveBeenCalledTimes(n)` (after the fact) | `.times(n)` (verified on **drop**) | | Call ordering | manual / `mock.calls` inspection | `Sequence` makes ordering a first-class expectation | | Unexpected call | returns `undefined`, test may pass silently | **panics** immediately: “No matching expectation found” | | Type safety of the double | the fake can drift from the interface | the mock *implements the trait*; drift is a compile error | Two consequences stand out. **Mocks are strict by default.** A Vitest `vi.fn()` with no implementation returns `undefined` and the test often limps on. A `mockall` mock with no matching expectation **panics**. That strictness catches “my code called the dependency in a way I did not anticipate” bugs that silently pass in JavaScript. **You design for mocking up front.** Because there is no runtime patching, code that hard-codes `reqwest::get(...)` or `SystemTime::now()` is hard to mock. The Rust answer is to depend on a trait and inject it, which is exactly the dependency-inversion discipline good TypeScript already follows, now enforced by the language. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: An unfulfilled `times` expectation fails at drop, not at the call site [Section titled “Pitfall 1: An unfulfilled times expectation fails at drop, not at the call site”](#pitfall-1-an-unfulfilled-times-expectation-fails-at-drop-not-at-the-call-site) If you declare `times(1)` but never invoke the method, the failure surfaces when the mock is dropped, with a message that points at the trait, not at any line you wrote: ```rust 1 #[cfg_attr(test, mockall::automock)] 2 pub trait Repo { 3 fn save(&self, id: u64) -> Result<(), String>; 4 } 5 6 #[cfg(test)] 7 mod tests { 8 use super::*; 9 10 #[test] 11 fn missing_expected_call_fails() { 12 let mut repo = MockRepo::new(); 13 repo.expect_save().times(1).returning(|_| Ok(())); 14 // We never call repo.save(...), so the `times(1)` is violated. test fails 15 } 16 } ``` Real output from `cargo test`: ```text 1 thread 'tests::missing_expected_call_fails' panicked at src/lib.rs:1:18: 2 MockRepo::save: Expectation(<anything>) called 0 time(s) which is fewer than expected 1 3 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` The `src/lib.rs:1:18` location is the `#[automock]` attribute, because that is where the generated `Drop` code lives. Read the message, not the line: it names the method (`MockRepo::save`) and the count mismatch. ### Pitfall 2: Calling a method with no matching expectation [Section titled “Pitfall 2: Calling a method with no matching expectation”](#pitfall-2-calling-a-method-with-no-matching-expectation) A `mockall` mock will not improvise. Call a method you did not set up — or call it with arguments your `.with` predicate rejects — and it panics: ```rust 1 #[cfg_attr(test, mockall::automock)] 2 pub trait Repo { 3 fn save(&self, id: u64) -> Result<(), String>; 4 } 5 6 #[cfg(test)] 7 mod tests { 8 use super::*; 9 10 #[test] 11 fn calling_with_no_expectation_set() { 12 let repo = MockRepo::new(); 13 let _ = repo.save(1); // no expect_save() was set up 14 } 15 } ``` Real output: ```text 1 thread 'tests::calling_with_no_expectation_set' panicked at src/lib.rs:1:18: 2 MockRepo::save(1): No matching expectation found ``` The same `No matching expectation found` appears when you set `expect_save().with(eq(1u64))` but the code calls `save(999)`. Coming from Vitest — where an un-stubbed `vi.fn()` quietly returns `undefined` — this strictness is a feature: it tells you precisely which interaction you forgot to model. ### Pitfall 3: Putting `#[automock]` on the trait unconditionally [Section titled “Pitfall 3: Putting #\[automock\] on the trait unconditionally”](#pitfall-3-putting-automock-on-the-trait-unconditionally) It is tempting to write a bare `#[mockall::automock]`. That generates `MockRepo` in *every* build, links `mockall` into your release binary, and adds `Mock…` types to your public API: ```rust 1 #[mockall::automock] // generated even in `cargo build --release` 2 pub trait Repo { 3 fn save(&self, id: u64) -> Result<(), String>; 4 } ``` Gate it with `#[cfg_attr(test, mockall::automock)]` so the mock exists only under `cargo test`, matching the `[dev-dependencies]` placement. (If a downstream *crate’s* tests need your mock, that is the one case for an unconditional `#[automock]` plus a normal dependency, but it is the exception.) ### Pitfall 4: Trying to mock a concrete type or an external trait with `#[automock]` [Section titled “Pitfall 4: Trying to mock a concrete type or an external trait with #\[automock\]”](#pitfall-4-trying-to-mock-a-concrete-type-or-an-external-trait-with-automock) `#[automock]` only works on a trait *you* are defining (you have to put the attribute on it). You cannot annotate `reqwest::Client` or a trait from another crate. For those, use `mockall`’s `mock!` macro, which generates a mock for a struct you describe inline (shown in [Best Practices](#best-practices)). The general lesson: if a dependency is a concrete type with no trait, introduce a trait of your own and depend on that: your code becomes both testable and decoupled from the vendor. ### Pitfall 5: Capturing a non-`Send` value in `returning` [Section titled “Pitfall 5: Capturing a non-Send value in returning”](#pitfall-5-capturing-a-non-send-value-in-returning) ```rust 1 // inside a test 2 use std::rc::Rc; 3 use std::cell::Cell; 4 let calls = Rc::new(Cell::new(0)); 5 let c = Rc::clone(&calls); 6 gw.expect_charge().returning(move |_, _| { c.set(c.get() + 1); Ok(()) }); 7 // does not compile (error[E0277]): `Rc<Cell<i32>>` is not `Send` ``` The real error names the bound directly: ```text 1 error[E0277]: `Rc<Cell<u32>>` cannot be shared between threads safely 2 = help: within `{closure@src/lib.rs:...}`, the trait `Send` is not implemented for `Rc<Cell<u32>>` 3 note: required by a bound in `__charge::Expectation::returning` ``` `mockall` requires the closure to be `Send` so mocks can be used across the test harness’s threads. Swap `Rc<Cell<T>>` for `Arc<AtomicU32>` (or `Arc<Mutex<T>>`), the thread-safe versions covered in [Concurrency](/11-async/10-concurrency/). *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Prefer a hand-written test double for simple traits [Section titled “Prefer a hand-written test double for simple traits”](#prefer-a-hand-written-test-double-for-simple-traits) You do not need `mockall` for everything. When a trait has one or two methods and you only need a canned answer, a plain struct is clearer and adds no dependency. This is the direct equivalent of writing a small fake object literal in TypeScript instead of reaching for `vi.fn()`. src/lib.rs ```rust 1 /// Anything that can tell the current Unix time. Abstracting the clock 2 /// makes time-dependent logic testable without sleeping or freezing. 3 pub trait Clock { 4 fn now_unix(&self) -> u64; 5 } 6 7 /// Production implementation reads the real system clock. 8 pub struct SystemClock; 9 10 impl Clock for SystemClock { 11 fn now_unix(&self) -> u64 { 12 std::time::SystemTime::now() 13 .duration_since(std::time::UNIX_EPOCH) 14 .unwrap() 15 .as_secs() 16 } 17 } 18 19 /// A token is valid until `issued_at + ttl_secs`. 20 pub fn token_is_valid(clock: &impl Clock, issued_at: u64, ttl_secs: u64) -> bool { 21 clock.now_unix() <= issued_at + ttl_secs 22 } 23 24 #[cfg(test)] 25 mod tests { 26 use super::*; 27 28 /// Hand-written stub: a clock frozen at a fixed instant. 29 struct FixedClock { 30 now: u64, 31 } 32 33 impl Clock for FixedClock { 34 fn now_unix(&self) -> u64 { 35 self.now 36 } 37 } 38 39 #[test] 40 fn token_within_ttl_is_valid() { 41 let clock = FixedClock { now: 1_000 }; 42 assert!(token_is_valid(&clock, 900, 200)); // expires at 1100 43 } 44 45 #[test] 46 fn expired_token_is_invalid() { 47 let clock = FixedClock { now: 2_000 }; 48 assert!(!token_is_valid(&clock, 900, 200)); 49 } 50 } ``` ```text 1 running 2 tests 2 test tests::expired_token_is_invalid ... ok 3 test tests::token_within_ttl_is_valid ... ok 4 5 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` > **Tip:** The terminology is worth knowing. A **stub** returns canned data and asserts nothing about how it was called (like `FixedClock`). A **spy** records calls so the test can verify them. A **mock** has built-in expectations that self-verify (like the `mockall` types). `mockall` gives you mocks; a hand-written struct can be any of the three. ### Use a spy when you only need to count calls [Section titled “Use a spy when you only need to count calls”](#use-a-spy-when-you-only-need-to-count-calls) When the interesting fact is “was this called, and how often,” a small spy with interior mutability beats a full mock framework: ```rust 1 use std::cell::RefCell; 2 3 pub trait Clock { 4 fn now_unix(&self) -> u64; 5 } 6 7 pub fn token_is_valid(clock: &impl Clock, issued_at: u64, ttl_secs: u64) -> bool { 8 clock.now_unix() <= issued_at + ttl_secs 9 } 10 11 #[cfg(test)] 12 mod tests { 13 use super::*; 14 15 /// Hand-written spy: counts how many times the clock was read. 16 #[derive(Default)] 17 struct SpyClock { 18 calls: RefCell<u32>, 19 fixed: u64, 20 } 21 22 impl Clock for SpyClock { 23 fn now_unix(&self) -> u64 { 24 *self.calls.borrow_mut() += 1; 25 self.fixed 26 } 27 } 28 29 #[test] 30 fn clock_is_read_exactly_once() { 31 let clock = SpyClock { calls: RefCell::new(0), fixed: 500 }; 32 let _ = token_is_valid(&clock, 400, 200); 33 assert_eq!(*clock.calls.borrow(), 1); 34 } 35 } ``` ```text 1 running 1 test 2 test tests::clock_is_read_exactly_once ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` `RefCell` provides interior mutability so the spy can mutate its counter through a shared `&self` reference. See [`RefCell` and `Mutex`](/10-smart-pointers/02-refcell-mutex/). (In a multithreaded test, use `Arc<AtomicU32>` instead, as in the capturing example below.) ### Reach for `mock!` when you do not own the trait [Section titled “Reach for mock! when you do not own the trait”](#reach-for-mock-when-you-do-not-own-the-trait) `#[automock]` must be attached to the trait, so for a third-party trait (or a concrete struct) use the `mock!` macro to describe the mock inline: src/lib.rs ```rust 1 /// Pretend this trait comes from a third-party crate, so you cannot add 2 /// `#[automock]` to its definition. 3 pub trait HttpClient { 4 fn get(&self, url: &str) -> Result<String, String>; 5 } 6 7 pub struct WeatherService<C: HttpClient> { 8 client: C, 9 } 10 11 impl<C: HttpClient> WeatherService<C> { 12 pub fn new(client: C) -> Self { 13 WeatherService { client } 14 } 15 pub fn temperature(&self, city: &str) -> Result<i32, String> { 16 let body = self.client.get(&format!("https://api/weather/{city}"))?; 17 body.trim().parse::<i32>().map_err(|e| e.to_string()) 18 } 19 } 20 21 #[cfg(test)] 22 mod tests { 23 use super::*; 24 use mockall::{mock, predicate::*}; 25 26 // `mock!` generates `MockExternalHttp` implementing `HttpClient`. 27 mock! { 28 ExternalHttp {} 29 impl HttpClient for ExternalHttp { 30 fn get(&self, url: &str) -> Result<String, String>; 31 } 32 } 33 34 #[test] 35 fn parses_temperature_from_response() { 36 let mut client = MockExternalHttp::new(); 37 client 38 .expect_get() 39 .with(eq("https://api/weather/oslo")) 40 .returning(|_| Ok(" -3 ".to_string())); 41 42 let svc = WeatherService::new(client); 43 assert_eq!(svc.temperature("oslo"), Ok(-3)); 44 } 45 } ``` ```text 1 running 1 test 2 test tests::parses_temperature_from_response ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` ### Use `withf` for logic that `eq` can’t express, and `Arc` + atomics to capture state [Section titled “Use withf for logic that eq can’t express, and Arc + atomics to capture state”](#use-withf-for-logic-that-eq-cant-express-and-arc--atomics-to-capture-state) `.with(eq(...))` matches by equality; `.withf(closure)` matches with arbitrary logic (the analogue of an `expect.objectContaining` / custom matcher). And when you need a spy-like counter inside a `mockall` mock, capture an `Arc<AtomicU32>`, which is `Send`: ```rust 1 use std::sync::Arc; 2 3 #[cfg_attr(test, mockall::automock)] 4 pub trait PaymentGateway { 5 fn charge(&self, cents: u64, currency: &str) -> Result<String, String>; 6 } 7 8 #[cfg(test)] 9 mod tests { 10 use super::*; 11 use std::sync::atomic::{AtomicU32, Ordering}; 12 13 #[test] 14 fn withf_custom_matcher() { 15 let mut gw = MockPaymentGateway::new(); 16 gw.expect_charge() 17 .withf(|cents, currency| *cents > 0 && currency == "USD") 18 .returning(|_, _| Ok("ch_1".to_string())); 19 assert_eq!(gw.charge(500, "USD"), Ok("ch_1".to_string())); 20 } 21 22 #[test] 23 fn returning_can_capture_and_count() { 24 let calls = Arc::new(AtomicU32::new(0)); 25 let calls_in_mock = Arc::clone(&calls); 26 27 let mut gw = MockPaymentGateway::new(); 28 gw.expect_charge().returning(move |_, _| { 29 calls_in_mock.fetch_add(1, Ordering::SeqCst); 30 Ok("ch".to_string()) 31 }); 32 33 let _ = gw.charge(1, "USD"); 34 let _ = gw.charge(2, "USD"); 35 assert_eq!(calls.load(Ordering::SeqCst), 2); 36 } 37 } ``` ```text 1 running 2 tests 2 test tests::returning_can_capture_and_count ... ok 3 test tests::withf_custom_matcher ... ok 4 5 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` ### Inject the trait — generics for static dispatch, `dyn` for runtime choice [Section titled “Inject the trait — generics for static dispatch, dyn for runtime choice”](#inject-the-trait--generics-for-static-dispatch-dyn-for-runtime-choice) Two idioms make code mockable, both seen above: * **Generic parameter** (`WelcomeService<R, S>`): monomorphized, zero-cost, the default. The compiler stamps out one version per concrete type, so a mock and the real type are distinct types. * **Trait object** (`Arc<dyn PaymentGateway>`): one type regardless of the implementation, chosen at runtime. Use it when the dependency is selected dynamically or when generics would over-parameterize a large struct. Both accept a `Mock…` exactly where they accept the real implementation: the substitution is just Rust’s polymorphism. See [Trait Objects](/09-generics-traits/06-trait-objects/) and [Trait Bounds](/09-generics-traits/05-trait-bounds/) for the trade-offs. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A complete order-processing service whose two collaborators — a repository and an audit log — are mocked. It exercises argument matching, call counts, ordering via `Sequence`, the `never()` guard, and a typed error enum. This is the full, compile-verified file. src/lib.rs ```rust 1 //! An order-fulfillment service with injected, mockable collaborators. 2 3 /// Reads and writes orders. The real impl hits a database. 4 #[cfg_attr(test, mockall::automock)] 5 pub trait OrderRepo { 6 fn find_total_cents(&self, order_id: u64) -> Result<Option<u64>, String>; 7 fn mark_paid(&self, order_id: u64) -> Result<(), String>; 8 } 9 10 /// Charges a payment method. 11 #[cfg_attr(test, mockall::automock)] 12 pub trait PaymentGateway { 13 fn charge(&self, cents: u64) -> Result<String, String>; 14 } 15 16 /// Domain error for the checkout flow. 17 #[derive(Debug, PartialEq)] 18 pub enum CheckoutError { 19 UnknownOrder(u64), 20 Repo(String), 21 Payment(String), 22 } 23 24 /// Orchestrates: look up the order total, charge it, then mark it paid. 25 pub struct Checkout<R, P> { 26 repo: R, 27 gateway: P, 28 } 29 30 impl<R: OrderRepo, P: PaymentGateway> Checkout<R, P> { 31 pub fn new(repo: R, gateway: P) -> Self { 32 Checkout { repo, gateway } 33 } 34 35 /// Returns the payment's charge id on success. 36 pub fn pay(&self, order_id: u64) -> Result<String, CheckoutError> { 37 let total = self 38 .repo 39 .find_total_cents(order_id) 40 .map_err(CheckoutError::Repo)? 41 .ok_or(CheckoutError::UnknownOrder(order_id))?; 42 43 let charge_id = self 44 .gateway 45 .charge(total) 46 .map_err(CheckoutError::Payment)?; 47 48 self.repo.mark_paid(order_id).map_err(CheckoutError::Repo)?; 49 Ok(charge_id) 50 } 51 } 52 53 #[cfg(test)] 54 mod tests { 55 use super::*; 56 use mockall::{predicate::*, Sequence}; 57 58 #[test] 59 fn charges_then_marks_paid_in_order() { 60 // A Sequence asserts the calls happen in this exact order. 61 let mut seq = Sequence::new(); 62 63 let mut repo = MockOrderRepo::new(); 64 repo.expect_find_total_cents() 65 .with(eq(10u64)) 66 .times(1) 67 .in_sequence(&mut seq) 68 .returning(|_| Ok(Some(4_999))); 69 70 let mut gateway = MockPaymentGateway::new(); 71 gateway 72 .expect_charge() 73 .with(eq(4_999u64)) 74 .times(1) 75 .in_sequence(&mut seq) 76 .returning(|_| Ok("ch_777".to_string())); 77 78 repo.expect_mark_paid() 79 .with(eq(10u64)) 80 .times(1) 81 .in_sequence(&mut seq) 82 .returning(|_| Ok(())); 83 84 let checkout = Checkout::new(repo, gateway); 85 assert_eq!(checkout.pay(10), Ok("ch_777".to_string())); 86 } 87 88 #[test] 89 fn unknown_order_never_charges() { 90 let mut repo = MockOrderRepo::new(); 91 repo.expect_find_total_cents().returning(|_| Ok(None)); 92 repo.expect_mark_paid().never(); 93 94 let mut gateway = MockPaymentGateway::new(); 95 gateway.expect_charge().never(); // must not charge a missing order 96 97 let checkout = Checkout::new(repo, gateway); 98 assert_eq!(checkout.pay(404), Err(CheckoutError::UnknownOrder(404))); 99 } 100 101 #[test] 102 fn payment_failure_does_not_mark_paid() { 103 let mut repo = MockOrderRepo::new(); 104 repo.expect_find_total_cents().returning(|_| Ok(Some(1_500))); 105 repo.expect_mark_paid().never(); // crucial: do not record a failed payment 106 107 let mut gateway = MockPaymentGateway::new(); 108 gateway 109 .expect_charge() 110 .returning(|_| Err("card declined".to_string())); 111 112 let checkout = Checkout::new(repo, gateway); 113 assert_eq!( 114 checkout.pay(10), 115 Err(CheckoutError::Payment("card declined".to_string())) 116 ); 117 } 118 } ``` Running `cargo test`: ```text 1 running 3 tests 2 test tests::charges_then_marks_paid_in_order ... ok 3 test tests::payment_failure_does_not_mark_paid ... ok 4 test tests::unknown_order_never_charges ... ok 5 6 test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` What this buys you that a naive Vitest suite often misses: * **`Sequence`** turns “charge before marking paid” into an enforced expectation. Reorder the production logic and the test fails: no manual `mock.calls` index juggling. * **`never()`** documents and enforces the safety-critical invariants (“do not charge a missing order,” “do not mark a failed payment as paid”). An unexpected call panics rather than slipping through. * The mocks **self-verify on drop**: every `times(1)` is checked when `checkout` (which owns them) goes out of scope, with no trailing assertion lines. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`mockall` crate documentation](https://docs.rs/mockall/latest/mockall/): the authoritative reference for `#[automock]`, `mock!`, predicates, and `Sequence`. * [`mockall::predicate` module](https://docs.rs/mockall/latest/mockall/predicate/index.html): `eq`, `function`, `gt`, `always`, and friends. * [The Rust Book — Test Organization](https://doc.rust-lang.org/book/ch11-03-test-organization.html) — where mocks fit among unit and integration tests. * Sibling topics in this section: * [Unit Tests](/13-testing/00-unit-tests/): `#[test]`, `#[cfg(test)]`, and the test harness the mocks run in. * [Test Organization](/13-testing/01-test-organization/) — private vs public testing; where to keep mocks. * [Assertions](/13-testing/02-assertions/) — `assert_eq!` / `assert!` used alongside expectations. * [`#[should_panic]` and `Result` tests](/13-testing/03-should-panic/) — testing the error paths the mocks simulate. * [Integration Tests](/13-testing/04-integration-tests/) — black-box testing where you usually do *not* mock. * [Test Fixtures](/13-testing/05-test-fixtures/) — building reusable mock setups and shared state. * [Property Testing](/13-testing/07-property-testing/), [Benchmarking](/13-testing/08-benchmarking/), [Doc Tests](/13-testing/09-doc-tests/), [Coverage](/13-testing/10-coverage/), [TDD Workflow](/13-testing/11-tdd-workflow/). * Foundations used above: * [Traits](/09-generics-traits/03-traits/), [Trait Bounds](/09-generics-traits/05-trait-bounds/), [Trait Objects](/09-generics-traits/06-trait-objects/): the dependency-injection mechanism. * [`RefCell` and `Mutex`](/10-smart-pointers/02-refcell-mutex/) — interior mutability for hand-written spies. * [Concurrency](/11-async/10-concurrency/) — `Arc` and atomics for `Send`-safe captured state. * [Macros](/14-macros/) — how attribute macros like `#[automock]` generate code. * [Cargo Basics](/01-getting-started/03-cargo-basics/): `cargo add --dev` and `[dev-dependencies]`. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A hand-written stub [Section titled “Exercise 1: A hand-written stub”](#exercise-1-a-hand-written-stub) **Difficulty:** Easy **Objective:** Mock a dependency without any crate, using a small struct that implements a trait. **Instructions:** Given the `FeatureFlags` trait and `banner_text` function below, write a `#[cfg(test)] mod tests` containing a stub `StubFlags` (holding a single `bool`) and two tests: one where the flag is on (expect `"New and improved!"`) and one where it is off (expect `"Welcome back."`). No `mockall` needed. ```rust 1 pub trait FeatureFlags { 2 fn is_enabled(&self, flag: &str) -> bool; 3 } 4 5 pub fn banner_text(flags: &impl FeatureFlags) -> &'static str { 6 if flags.is_enabled("new_banner") { 7 "New and improved!" 8 } else { 9 "Welcome back." 10 } 11 } 12 13 // TODO: add a #[cfg(test)] mod tests with a StubFlags and two tests ``` Solution ```rust 1 pub trait FeatureFlags { 2 fn is_enabled(&self, flag: &str) -> bool; 3 } 4 5 pub fn banner_text(flags: &impl FeatureFlags) -> &'static str { 6 if flags.is_enabled("new_banner") { 7 "New and improved!" 8 } else { 9 "Welcome back." 10 } 11 } 12 13 #[cfg(test)] 14 mod tests { 15 use super::*; 16 17 struct StubFlags { 18 on: bool, 19 } 20 21 impl FeatureFlags for StubFlags { 22 fn is_enabled(&self, _flag: &str) -> bool { 23 self.on 24 } 25 } 26 27 #[test] 28 fn banner_respects_flag() { 29 assert_eq!(banner_text(&StubFlags { on: true }), "New and improved!"); 30 assert_eq!(banner_text(&StubFlags { on: false }), "Welcome back."); 31 } 32 } ``` ```text 1 running 1 test 2 test tests::banner_respects_flag ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` ### Exercise 2: `#[automock]` with a call-count expectation [Section titled “Exercise 2: #\[automock\] with a call-count expectation”](#exercise-2-automock-with-a-call-count-expectation) **Difficulty:** Medium **Objective:** Generate a mock with `#[automock]` and verify both the argument and the number of calls. **Instructions:** Add `mockall` as a dev-dependency. Given the `AuditLog` trait and `Account` type below, write a test that mocks `AuditLog`, expects `record` to be called **exactly once** with `"deposit 500"`, and then calls `account.deposit(500)`. (Remember: the count is verified when the mock drops, so you do not write a final assertion for it.) ```rust 1 #[cfg_attr(test, mockall::automock)] 2 pub trait AuditLog { 3 fn record(&self, action: &str) -> Result<(), String>; 4 } 5 6 pub struct Account<L> { 7 log: L, 8 balance: i64, 9 } 10 11 impl<L: AuditLog> Account<L> { 12 pub fn new(log: L) -> Self { 13 Account { log, balance: 0 } 14 } 15 pub fn deposit(&mut self, cents: i64) -> Result<(), String> { 16 self.balance += cents; 17 self.log.record(&format!("deposit {cents}")) 18 } 19 } 20 21 // TODO: add a #[cfg(test)] mod tests ``` Solution ```rust 1 #[cfg_attr(test, mockall::automock)] 2 pub trait AuditLog { 3 fn record(&self, action: &str) -> Result<(), String>; 4 } 5 6 pub struct Account<L> { 7 log: L, 8 balance: i64, 9 } 10 11 impl<L: AuditLog> Account<L> { 12 pub fn new(log: L) -> Self { 13 Account { log, balance: 0 } 14 } 15 pub fn deposit(&mut self, cents: i64) -> Result<(), String> { 16 self.balance += cents; 17 self.log.record(&format!("deposit {cents}")) 18 } 19 } 20 21 #[cfg(test)] 22 mod tests { 23 use super::*; 24 use mockall::predicate::*; 25 26 #[test] 27 fn deposit_is_audited_once() { 28 let mut log = MockAuditLog::new(); 29 log.expect_record() 30 .with(eq("deposit 500")) 31 .times(1) 32 .returning(|_| Ok(())); 33 34 let mut account = Account::new(log); 35 account.deposit(500).unwrap(); 36 // `times(1)` is verified when `account` (and its `log`) drop here. 37 } 38 } ``` ```text 1 running 1 test 2 test tests::deposit_is_audited_once ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` ### Exercise 3: A read-through cache with ordered expectations [Section titled “Exercise 3: A read-through cache with ordered expectations”](#exercise-3-a-read-through-cache-with-ordered-expectations) **Difficulty:** Hard **Objective:** Mock two collaborators and assert the *order* of calls with `Sequence`, plus a `never()` guard on the happy path. **Instructions:** Implement a `ReadThrough<C, O>` that, on `read(key)`: returns the cached value on a hit; on a miss, fetches from the origin, writes it back with `put`, and returns it. Then write two tests: 1. **Miss:** `get` returns `None`, then `fetch` returns `"Ada"`, then `put` is called with the key and `"Ada"`, in that order (use `Sequence`). 2. **Hit:** `get` returns `Some("Grace")`; assert `fetch` and `put` are **never** called. ```rust 1 #[cfg_attr(test, mockall::automock)] 2 pub trait Cache { 3 fn get(&self, key: &str) -> Option<String>; 4 fn put(&self, key: &str, value: &str); 5 } 6 7 #[cfg_attr(test, mockall::automock)] 8 pub trait Origin { 9 fn fetch(&self, key: &str) -> String; 10 } 11 12 pub struct ReadThrough<C, O> { 13 cache: C, 14 origin: O, 15 } 16 17 impl<C: Cache, O: Origin> ReadThrough<C, O> { 18 // TODO: new() and read() 19 } 20 21 // TODO: add tests ``` Solution ```rust 1 #[cfg_attr(test, mockall::automock)] 2 pub trait Cache { 3 fn get(&self, key: &str) -> Option<String>; 4 fn put(&self, key: &str, value: &str); 5 } 6 7 #[cfg_attr(test, mockall::automock)] 8 pub trait Origin { 9 fn fetch(&self, key: &str) -> String; 10 } 11 12 pub struct ReadThrough<C, O> { 13 cache: C, 14 origin: O, 15 } 16 17 impl<C: Cache, O: Origin> ReadThrough<C, O> { 18 pub fn new(cache: C, origin: O) -> Self { 19 ReadThrough { cache, origin } 20 } 21 pub fn read(&self, key: &str) -> String { 22 if let Some(hit) = self.cache.get(key) { 23 return hit; 24 } 25 let value = self.origin.fetch(key); 26 self.cache.put(key, &value); 27 value 28 } 29 } 30 31 #[cfg(test)] 32 mod tests { 33 use super::*; 34 use mockall::{predicate::*, Sequence}; 35 36 #[test] 37 fn miss_fetches_then_populates_cache() { 38 let mut seq = Sequence::new(); 39 40 let mut cache = MockCache::new(); 41 cache 42 .expect_get() 43 .with(eq("user:1")) 44 .times(1) 45 .in_sequence(&mut seq) 46 .returning(|_| None); 47 48 let mut origin = MockOrigin::new(); 49 origin 50 .expect_fetch() 51 .with(eq("user:1")) 52 .times(1) 53 .in_sequence(&mut seq) 54 .returning(|_| "Ada".to_string()); 55 56 cache 57 .expect_put() 58 .with(eq("user:1"), eq("Ada")) 59 .times(1) 60 .in_sequence(&mut seq) 61 .returning(|_, _| ()); 62 63 let rt = ReadThrough::new(cache, origin); 64 assert_eq!(rt.read("user:1"), "Ada"); 65 } 66 67 #[test] 68 fn hit_skips_origin() { 69 let mut cache = MockCache::new(); 70 cache 71 .expect_get() 72 .with(eq("user:2")) 73 .returning(|_| Some("Grace".to_string())); 74 cache.expect_put().never(); 75 76 let mut origin = MockOrigin::new(); 77 origin.expect_fetch().never(); 78 79 let rt = ReadThrough::new(cache, origin); 80 assert_eq!(rt.read("user:2"), "Grace"); 81 } 82 } ``` ```text 1 running 2 tests 2 test tests::hit_skips_origin ... ok 3 test tests::miss_fetches_then_populates_cache ... ok 4 5 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` # Property-Based Testing > Rust's proptest asserts invariants over hundreds of random inputs and shrinks failures to a minimal case, like fast-check but with auto-saved cases. Most of the tests you write in Jest or Vitest are **example tests**: you pick a handful of inputs, compute the expected output by hand, and assert. Property-based testing flips that around: you state a *rule* that must hold for **every** input, and the framework generates hundreds of random inputs trying to break it. In Rust, the `proptest` crate brings this style to `cargo test`, complete with automatic **shrinking** that boils a wild failing input down to the smallest one that still fails. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **property test** asserts an invariant (`decode(encode(x)) == x`, “the output is always sorted”, “addition is commutative”) and lets the framework throw randomized inputs at it. When it finds a counterexample, **proptest** *shrinks* it, repeatedly simplifying the input while the test keeps failing, so you get the minimal reproduction instead of a 40-element vector of noise. If you have reached for [fast-check](https://github.com/dubzzz/fast-check) in TypeScript, proptest is the direct equivalent; if you have not, think of it as “fuzzing with assertions and a built-in minimizer.” This complements the example-based [unit tests](/13-testing/00-unit-tests/); it does not replace them. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In the JavaScript world, property testing is not built in; the standard tool is **fast-check**, usually driven by Jest or Vitest. Here is a realistic pair of properties for a `reverse` helper and a (buggy) `mergeSorted`. merge.test.ts ```typescript 1 import { test } from "vitest"; 2 import fc from "fast-check"; 3 4 function reverse(s: string): string { 5 return [...s].reverse().join(""); 6 } 7 8 // BUG: when both fronts are equal it advances *both* cursors, 9 // silently dropping one of the duplicates. 10 function mergeSorted(a: number[], b: number[]): number[] { 11 const out: number[] = []; 12 let i = 0; 13 let j = 0; 14 while (i < a.length && j < b.length) { 15 if (a[i] < b[j]) out.push(a[i++]); 16 else if (a[i] > b[j]) out.push(b[j++]); 17 else { 18 out.push(a[i]); 19 i++; 20 j++; // <- drops a duplicate 21 } 22 } 23 return out.concat(a.slice(i), b.slice(j)); 24 } 25 26 test("reversing twice is the identity", () => { 27 fc.assert(fc.property(fc.string(), (s) => reverse(reverse(s)) === s)); 28 }); 29 30 test("merge preserves total length", () => { 31 fc.assert( 32 fc.property( 33 fc.array(fc.integer({ min: 0, max: 9 })), 34 fc.array(fc.integer({ min: 0, max: 9 })), 35 (a, b) => { 36 a.sort((x, y) => x - y); 37 b.sort((x, y) => x - y); 38 return mergeSorted(a, b).length === a.length + b.length; 39 }, 40 ), 41 ); 42 }); ``` Running this against the buggy `mergeSorted` (here driven directly through Node, `node merge.mjs`) produces a *shrunk* counterexample: ```text 1 reverse roundtrip: ok 2 Property failed after 2 tests 3 { seed: -1021748401, path: "1:1:1:1:1:3", endOnFailure: true } 4 Counterexample: [[0],[0]] 5 Shrunk 5 time(s) ``` The key moves to notice — and that Rust mirrors almost exactly: * You add a **dependency** (`fast-check`) and wire it into your existing runner. * `fc.property(...generators, predicate)` declares the rule; `fc.assert` runs \~100 random cases. * On failure, fast-check **shrinks** the random `[[3,7,7],[1,7,9]]`-style input down to the minimal `[[0],[0]]`. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same two properties with `proptest`. Add the dependency to a project’s dev-dependencies (it is only needed for tests): Cargo.toml ```toml 1 [dev-dependencies] 2 proptest = "1.11" ``` > **Tip:** `cargo add proptest --dev` does this for you. The `cargo add` subcommand is built into Cargo (since 1.62); there is no `cargo-edit` to install. The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition, and `cargo new` selects that edition automatically. src/lib.rs ```rust 1 /// Returns the input string reversed (by Unicode scalar value). 2 pub fn reverse(s: &str) -> String { 3 s.chars().rev().collect() 4 } 5 6 /// Merges two already-sorted slices into one sorted `Vec`. 7 /// BUG: when the two fronts are equal it advances *both* cursors, 8 /// silently dropping one of the duplicates. 9 pub fn merge_sorted(a: &[i32], b: &[i32]) -> Vec<i32> { 10 let mut out = Vec::with_capacity(a.len() + b.len()); 11 let (mut i, mut j) = (0, 0); 12 while i < a.len() && j < b.len() { 13 if a[i] < b[j] { 14 out.push(a[i]); 15 i += 1; 16 } else if a[i] > b[j] { 17 out.push(b[j]); 18 j += 1; 19 } else { 20 out.push(a[i]); // BUG: keeps one, advances both 21 i += 1; 22 j += 1; 23 } 24 } 25 out.extend_from_slice(&a[i..]); 26 out.extend_from_slice(&b[j..]); 27 out 28 } 29 30 #[cfg(test)] 31 mod tests { 32 use super::*; 33 use proptest::prelude::*; 34 35 proptest! { 36 #[test] 37 fn reversing_twice_is_identity(s in ".*") { 38 prop_assert_eq!(reverse(&reverse(&s)), s); 39 } 40 41 #[test] 42 fn merge_preserves_total_length( 43 mut a in prop::collection::vec(0i32..10, 0..20), 44 mut b in prop::collection::vec(0i32..10, 0..20), 45 ) { 46 a.sort(); 47 b.sort(); 48 let merged = merge_sorted(&a, &b); 49 prop_assert_eq!(merged.len(), a.len() + b.len()); 50 } 51 } 52 } ``` Running `cargo test` finds the bug and shrinks it to the minimal failing pair: ```text 1 running 2 tests 2 test tests::reversing_twice_is_identity ... ok 3 test tests::merge_preserves_total_length ... FAILED 4 5 failures: 6 7 ---- tests::merge_preserves_total_length stdout ---- 8 proptest: Saving this and future failures in .../proptest-regressions/lib.txt 9 proptest: If this test was run on a CI system, you may wish to add the following line to your copy of the file. (You may need to create it.) 10 cc f79f5196ae6f4bf6e635c36ee5c9fea44d5939fe632a2f66faaae07b209bfe5e 11 12 thread 'tests::merge_preserves_total_length' panicked at src/lib.rs:31:5: 13 Test failed: assertion failed: `(left == right)` 14 left: `1`, 15 right: `2` at src/lib.rs:40. 16 minimal failing input: mut a = [ 17 1, 18 ], mut b = [ 19 1, 20 ] 21 successes: 0 22 local rejects: 0 23 global rejects: 0 24 25 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace 26 27 28 failures: 29 tests::merge_preserves_total_length 30 31 test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` Just like fast-check, proptest shrank a randomly-generated pair of vectors down to the irreducible counterexample `a = [1], b = [1]`, the smallest input that exposes the dropped-duplicate bug. Unlike fast-check, it also wrote a **regression file** that will re-run this exact case on every future `cargo test`. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The `proptest!` macro and the `x in strategy` syntax [Section titled “The proptest! macro and the x in strategy syntax”](#the-proptest-macro-and-the-x-in-strategy-syntax) ```rust 1 use proptest::prelude::*; 2 3 proptest! { 4 #[test] 5 fn reversing_twice_is_identity(s in ".*") { 6 prop_assert_eq!(reverse(&reverse(&s)), s); 7 } 8 } ``` `proptest!` is a macro that wraps one or more `#[test]` functions. Where a plain unit test takes **no arguments** (see [Unit Tests](/13-testing/00-unit-tests/)), a proptest test takes *parameters* whose values proptest will generate. Each parameter uses the special `name in strategy` syntax: a **strategy** is a recipe for producing-and-shrinking values of a type. * `s in ".*"` — a string literal is interpreted as a **regular expression**; proptest generates random strings matching it. `".*"` means “any string.” (This is a proptest convenience; it is not a normal Rust pattern.) * `prop::collection::vec(0i32..10, 0..20)`: a `Vec<i32>` of length `0..20`, each element drawn from `0..10`. * `any::<u8>()`: the “natural” strategy for a type, here every possible `u8`. The macro expands each function into a real `#[test]` that loops over generated cases (256 by default), so `cargo test` discovers and runs them with no extra runner, exactly like the built-in `#[test]` machinery described in [Unit Tests](/13-testing/00-unit-tests/). ### `prop_assert!` / `prop_assert_eq!` vs `assert!` [Section titled “prop\_assert! / prop\_assert\_eq! vs assert!”](#prop_assert--prop_assert_eq-vs-assert) ```rust 1 prop_assert_eq!(reverse(&reverse(&s)), s); ``` Inside `proptest!`, prefer `prop_assert!`, `prop_assert_eq!`, and `prop_assert_ne!` over the standard [`assert!` family](/13-testing/02-assertions/). The reason is *shrinking*: a `prop_assert*` failure returns an error that proptest catches and uses to drive shrinking, rather than unwinding through a panic. A plain `assert_eq!` still *works* (proptest catches the panic too), but `prop_assert*` integrates more cleanly and lets the harness keep running the shrink loop. ### Shrinking: the headline feature [Section titled “Shrinking: the headline feature”](#shrinking-the-headline-feature) When a property fails, proptest does **not** report the random input it happened to find. Instead it enters a shrink loop: it tries “smaller” variants of the failing input (shorter vectors, smaller numbers, characters closer to `'a'`) and keeps any variant that *still fails*. It repeats until it cannot shrink further. The `minimal failing input` line is the result of that search. This is why the merge bug reported `a = [1], b = [1]` instead of something like `a = [2, 5, 5, 8], b = [1, 5, 9]`. Both fail, but the shrunk version tells you instantly: “two single-element lists with the same value.” Shrinking is the single biggest reason property testing is worth the upfront cost. ### The regression file [Section titled “The regression file”](#the-regression-file) ```text 1 proptest: Saving this and future failures in .../proptest-regressions/lib.txt ``` The first time a property fails, proptest writes the failing seed to a `proptest-regressions/` directory next to your source: ```text 1 # Seeds for failure cases proptest has generated in the past. It is 2 # automatically read and these particular cases re-run before any 3 # novel cases are generated. 4 cc f79f5196ae6f4bf6e635c36ee5c9fea44d5939fe632a2f66faaae07b209bfe5e # shrinks to mut a = [1], mut b = [1] ``` On every subsequent run, proptest replays these seeds *first*. That turns a flaky, probabilistic failure into a deterministic one. Once a bug is found, it stays found until you fix it. **Check this file into version control** (the file itself says so). It is the property-testing analogue of a fast-check `seed`/`path`, but persisted automatically. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | fast-check (TypeScript) | proptest (Rust) | | ----------------------- | ---------------------------------------------- | ---------------------------------------------------- | | Installation | `npm i -D fast-check`, plus a runner | `cargo add proptest --dev`; runner is built in | | Declaring a property | `fc.assert(fc.property(gen, pred))` | `proptest! { #[test] fn p(x in strat) { ... } }` | | Generators / strategies | `fc.string()`, `fc.integer()`, `fc.array(...)` | `".*"`, `any::<i32>()`, `prop::collection::vec(...)` | | Assertion | return a `boolean`, or `expect`/throw | `prop_assert!` / `prop_assert_eq!` | | Default case count | \~100 | 256 (`ProptestConfig::cases`) | | Shrinking | yes, automatic | yes, automatic | | Reproducing a failure | copy the printed `seed`/`path` | auto-saved to `proptest-regressions/` | | Type information | erased at runtime; generators are values | strategies are values; types are monomorphized | > **Note:** A TypeScript predicate can return a `boolean` *or* throw. Rust has no exceptions, so a proptest body signals failure by returning an `Err` from a `prop_assert*` macro (the macro does `return Err(...)` for you); the body’s real return type is `Result<(), TestCaseError>`, which the `proptest!` macro supplies. This is the same explicit-error philosophy you saw in [Error Handling](/08-error-handling/), applied to tests. ### Property tests vs example tests [Section titled “Property tests vs example tests”](#property-tests-vs-example-tests) They answer different questions and you want **both**: | | Example test (`#[test]`) | Property test (`proptest!`) | | --------------- | -------------------------------- | ------------------------------------------- | | You provide | specific input + expected output | an invariant over *all* inputs | | Catches | the cases you thought of | the cases you *didn’t* think of | | Reads like | a worked example / regression | a specification | | Best for | known edge cases, exact values | round-trips, algebraic laws, “never panics” | | Failure clarity | exact, by construction | excellent, thanks to shrinking | A healthy suite uses example tests to pin down the cases that matter to humans (`encode("a b") == "a%20b"`) and property tests to patrol the infinite space of inputs you would never enumerate by hand. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Importing the macro but not the prelude [Section titled “Pitfall 1: Importing the macro but not the prelude”](#pitfall-1-importing-the-macro-but-not-the-prelude) The `proptest!` macro relies on `prop_assert_eq!` and the strategy combinators being in scope. Bringing in just the macro is a frequent first mistake: ```rust 1 pub fn double(n: i32) -> i32 { 2 n * 2 3 } 4 5 #[cfg(test)] 6 mod tests { 7 use super::*; 8 use proptest::proptest; // only the macro, NOT the prelude 9 10 proptest! { 11 #[test] 12 fn doubling_is_even(n in 0i32..1000) { 13 prop_assert_eq!(double(n) % 2, 0); // does not compile 14 } 15 } 16 } ``` Real `cargo test` output: ```text 1 error: cannot find macro `prop_assert_eq` in this scope 2 --> src/lib.rs:11:13 3 | 4 11 | prop_assert_eq!(double(n) % 2, 0); 5 | ^^^^^^^^^^^^^^ 6 | 7 help: consider importing this macro 8 | 9 5 + use proptest::prop_assert_eq; 10 | ``` The fix is the idiomatic glob: `use proptest::prelude::*;`, which brings in the macro, the assertions, `any`, and the `prop` module together. ### Pitfall 2: Asserting exact equality on floating-point [Section titled “Pitfall 2: Asserting exact equality on floating-point”](#pitfall-2-asserting-exact-equality-on-floating-point) A property like “addition is associative” feels obviously true, but IEEE-754 `f64` (the same representation as a JavaScript `number`) is **not** associative because of rounding: ```rust 1 #[cfg(test)] 2 mod tests { 3 use proptest::prelude::*; 4 5 proptest! { 6 #[test] 7 fn addition_is_associative(a in -1e6f64..1e6, b in -1e6f64..1e6, c in -1e6f64..1e6) { 8 // fails: floating point addition is not associative 9 prop_assert_eq!((a + b) + c, a + (b + c)); 10 } 11 } 12 } ``` Real output (abridged): ```text 1 thread 'tests::addition_is_associative' panicked at src/lib.rs:5:5: 2 Test failed: assertion failed: `(left == right)` 3 left: `-25968.140341530205`, 4 right: `-25968.140341530176` at src/lib.rs:9. 5 minimal failing input: a = 168661.21983607815, b = -947504.2093726996, c = 752874.8491950913 ``` The values differ in the last few bits. This is not a proptest quirk; the identical predicate fails in JavaScript too. The fix is to assert *approximate* equality: `prop_assert!(((a + b) + c - (a + (b + c))).abs() < 1e-6)`, or test an exact-arithmetic type. Property testing is excellent at surfacing this class of “I assumed math worked the way I learned in school” bug. ### Pitfall 3: Over-filtering inputs with `prop_assume!` [Section titled “Pitfall 3: Over-filtering inputs with prop\_assume!”](#pitfall-3-over-filtering-inputs-with-prop_assume) `prop_assume!(condition)` *rejects* a generated case that does not satisfy a precondition (the analogue of fast-check’s `fc.pre`). It is fine when most inputs pass, but if you filter out almost everything, proptest cannot find enough valid cases and aborts: ```rust 1 #[cfg(test)] 2 mod tests { 3 use proptest::prelude::*; 4 5 proptest! { 6 #[test] 7 fn rarely_satisfiable(n in any::<u64>()) { 8 prop_assume!(n == 42); // rejects essentially every input 9 prop_assert_eq!(n, 42); 10 } 11 } 12 } ``` Real output: ```text 1 thread 'tests::rarely_satisfiable' panicked at src/lib.rs:5:5: 2 Test aborted: Too many global rejects 3 successes: 0 4 local rejects: 0 5 global rejects: 1024 6 1024 times at src/lib.rs:9:13: n == 42 ``` The fix is to **generate** the constrained value directly instead of filtering for it: narrow the strategy (`n in 40u64..=44`) or build a custom strategy with `prop_map`. Reserve `prop_assume!` for preconditions that the *majority* of inputs satisfy, such as `prop_assume!(lo <= hi)` where you generate `lo` and `hi` independently. ### Pitfall 4: Tautological properties [Section titled “Pitfall 4: Tautological properties”](#pitfall-4-tautological-properties) A property that restates the implementation proves nothing: ```rust 1 // useless: this just re-runs the function and compares to itself 2 proptest! { 3 #[test] 4 fn double_equals_double(n in any::<i32>()) { 5 prop_assert_eq!(n.wrapping_mul(2), n.wrapping_mul(2)); 6 } 7 } ``` Good properties are *independent* of the implementation: round-trips (`decode(encode(x)) == x`), relations to a slower-but-obviously-correct reference (a naive sort), or universal invariants (“output length equals input length”, “result is sorted”, “never panics”). If you cannot state the property without copying the function body, you probably want an [example test](/13-testing/00-unit-tests/) with a hand-computed answer instead. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Look for round-trips, invariants, and oracles [Section titled “Look for round-trips, invariants, and oracles”](#look-for-round-trips-invariants-and-oracles) The three most productive property shapes: * **Round-trip:** `decode(encode(x)) == x`, `from_str(to_string(x)) == Ok(x)`, `deserialize(serialize(x)) == x`. These catch asymmetric encode/decode bugs instantly. * **Invariant:** something always true of the output regardless of input: “the result is sorted”, “length is preserved”, “the function does not panic”. * **Oracle (model-based):** compare your fast implementation against a simple, obviously-correct reference. Your optimized parser vs. a naive one; your custom collection vs. `std`. ### Tune the case count and shrink iterations with `ProptestConfig` [Section titled “Tune the case count and shrink iterations with ProptestConfig”](#tune-the-case-count-and-shrink-iterations-with-proptestconfig) Per-block configuration goes in an inner attribute at the top of the `proptest!` block: ```rust 1 #[cfg(test)] 2 mod tests { 3 use proptest::prelude::*; 4 5 proptest! { 6 #![proptest_config(ProptestConfig::with_cases(1000))] 7 8 #[test] 9 fn runs_a_thousand_cases(n in 0i32..1000) { 10 prop_assert!(n >= 0 && n < 1000); 11 } 12 } 13 } ``` `with_cases(1000)` runs more inputs (default is 256); `ProptestConfig { cases: 1000, max_shrink_iters: 10_000, ..Default::default() }` tunes more. You can also override globally with the `PROPTEST_CASES` environment variable, which is handy for a heavier nightly CI run without touching code. ### Build reusable strategies with `prop_compose!` [Section titled “Build reusable strategies with prop\_compose!”](#build-reusable-strategies-with-prop_compose) For domain types, factor the generator into a named strategy so multiple properties can share it: ```rust 1 #[derive(Debug, Clone, PartialEq)] 2 pub struct Money { 3 pub cents: u64, 4 } 5 6 impl Money { 7 pub fn add(&self, other: &Money) -> Money { 8 Money { cents: self.cents + other.cents } 9 } 10 } 11 12 #[cfg(test)] 13 mod tests { 14 use super::*; 15 use proptest::prelude::*; 16 17 // A reusable strategy producing a bounded `Money`. 18 prop_compose! { 19 fn arb_money()(cents in 0u64..1_000_000) -> Money { 20 Money { cents } 21 } 22 } 23 24 proptest! { 25 #[test] 26 fn addition_is_commutative(a in arb_money(), b in arb_money()) { 27 prop_assert_eq!(a.add(&b), b.add(&a)); 28 } 29 30 #[test] 31 fn adding_zero_is_identity(a in arb_money()) { 32 prop_assert_eq!(a.add(&Money { cents: 0 }), a); 33 } 34 } 35 } ``` This passes cleanly: ```text 1 running 2 tests 2 test tests::adding_zero_is_identity ... ok 3 test tests::addition_is_commutative ... ok 4 5 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.05s ``` > **Tip:** `prop_compose!` is sugar for combining strategies. The double-parens `fn arb_money()(cents in ...)` read as “no outer arguments, then generate `cents` from this strategy, then map to a `Money`.” For one-off mapping you can also write `(0u64..1_000_000).prop_map(|cents| Money { cents })` inline. ### Commit the regression directory [Section titled “Commit the regression directory”](#commit-the-regression-directory) Add `proptest-regressions/` to source control. Each saved seed is a discovered bug; replaying them turns probabilistic coverage into a deterministic guard. Pair property tests with the example-based [unit tests](/13-testing/00-unit-tests/) and [assertions](/13-testing/02-assertions/) you already write: property testing widens coverage, it does not replace targeted regression cases. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored percent-encoder for URL query values, validated with two properties (a round-trip and an output invariant) plus one example test for a human-meaningful edge case. This is the full, compile-verified file. src/lib.rs ```rust 1 //! A tiny URL-safe percent-encoder/decoder for query-string values. 2 3 /// Percent-encodes a string: every byte that is not an unreserved 4 /// character (`A-Z a-z 0-9 - _ . ~`) becomes `%XX` with uppercase hex. 5 pub fn encode(input: &str) -> String { 6 let mut out = String::new(); 7 for &byte in input.as_bytes() { 8 match byte { 9 b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => { 10 out.push(byte as char); 11 } 12 _ => out.push_str(&format!("%{byte:02X}")), 13 } 14 } 15 out 16 } 17 18 /// Decodes a percent-encoded string back into the original string, 19 /// returning `None` on malformed input. 20 pub fn decode(input: &str) -> Option<String> { 21 let bytes = input.as_bytes(); 22 let mut out: Vec<u8> = Vec::with_capacity(bytes.len()); 23 let mut i = 0; 24 while i < bytes.len() { 25 match bytes[i] { 26 b'%' => { 27 if i + 2 >= bytes.len() { 28 return None; 29 } 30 let hex = std::str::from_utf8(&bytes[i + 1..i + 3]).ok()?; 31 out.push(u8::from_str_radix(hex, 16).ok()?); 32 i += 3; 33 } 34 other => { 35 out.push(other); 36 i += 1; 37 } 38 } 39 } 40 String::from_utf8(out).ok() 41 } 42 43 #[cfg(test)] 44 mod tests { 45 use super::*; 46 use proptest::prelude::*; 47 48 proptest! { 49 // The central round-trip property: decode(encode(s)) == s for ANY string. 50 #[test] 51 fn encode_then_decode_roundtrips(s in ".*") { 52 let restored = decode(&encode(&s)); 53 prop_assert_eq!(restored.as_deref(), Some(s.as_str())); 54 } 55 56 // Output invariant: an encoded string contains only URL-safe bytes. 57 #[test] 58 fn encoded_output_is_url_safe(s in ".*") { 59 let encoded = encode(&s); 60 for c in encoded.chars() { 61 prop_assert!( 62 c.is_ascii_alphanumeric() 63 || matches!(c, '-' | '_' | '.' | '~' | '%') 64 || c.is_ascii_hexdigit(), 65 "unexpected char {:?} in encoded output", 66 c 67 ); 68 } 69 } 70 } 71 72 // A classic example test still earns its place for a known edge case. 73 #[test] 74 fn encodes_a_space_as_percent_20() { 75 assert_eq!(encode("a b"), "a%20b"); 76 } 77 } ``` Running `cargo test` produces real output: ```text 1 running 3 tests 2 test tests::encodes_a_space_as_percent_20 ... ok 3 test tests::encoded_output_is_url_safe ... ok 4 test tests::encode_then_decode_roundtrips ... ok 5 6 test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.04s ``` The round-trip property is doing real work here: it generates Unicode strings with embedded spaces, control characters, multi-byte UTF-8, and percent signs — inputs you would rarely enumerate by hand — and verifies that every one of them survives the encode/decode cycle. If a future “optimization” forgot to encode some byte, or mishandled a multi-byte character boundary, the property would fail and shrink to the shortest offending string. Meanwhile, the one example test documents the single most important human-readable fact: a space becomes `%20`. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [The `proptest` book](https://proptest-rs.github.io/proptest/intro.html) — the official guide to strategies, shrinking, and configuration. * [`proptest` on docs.rs](https://docs.rs/proptest/latest/proptest/) — API reference for the prelude, `prop_compose!`, and `ProptestConfig`. * [`proptest` on crates.io](https://crates.io/crates/proptest) — current version and changelog. * [QuickCheck](https://github.com/BurntSushi/quickcheck) — the other major Rust property-testing crate, modeled on Haskell’s QuickCheck (lighter, fewer strategy combinators). * [fast-check](https://github.com/dubzzz/fast-check) — the TypeScript/JavaScript tool this chapter compares against. * Sibling topics in this section: * [Unit Tests](/13-testing/00-unit-tests/) — example-based `#[test]` functions; property tests build on the same harness. * [Assertions](/13-testing/02-assertions/) — `assert!`/`assert_eq!` and how `prop_assert!` differs. * [`#[should_panic]` and `Result` tests](/13-testing/03-should-panic/) — other ways tests signal failure. * [Mocking](/13-testing/06-mocking/) — trait-based test doubles with `mockall`. * [Benchmarking](/13-testing/08-benchmarking/) — measuring performance with `criterion`. * [Test Organization](/13-testing/01-test-organization/) and [Integration Tests](/13-testing/04-integration-tests/) — where these tests live. * Foundations used above: * [Cargo Basics](/01-getting-started/03-cargo-basics/): `cargo add --dev` and `cargo test`. * [Types](/02-basics/01-types/) — why `f64` equality is brittle (it is JavaScript’s `number`). * [Error Handling](/08-error-handling/): the `Result`-returning model behind `prop_assert!`. * [Macros](/14-macros/): how `proptest!` and `prop_compose!` expand at compile time. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Your first property [Section titled “Exercise 1: Your first property”](#exercise-1-your-first-property) **Difficulty:** Easy **Objective:** Write a property test for a symmetric function. **Instructions:** Given `abs_diff` below, write a `proptest!` block asserting that the absolute difference is **symmetric** — `abs_diff(a, b) == abs_diff(b, a)` — for any two `i32` values. Use `any::<i32>()` as the strategy. Run `cargo test` and confirm it passes. ```rust 1 pub fn abs_diff(a: i32, b: i32) -> u32 { 2 a.abs_diff(b) 3 } 4 5 // TODO: add a #[cfg(test)] mod tests with a proptest! property ``` Solution ```rust 1 pub fn abs_diff(a: i32, b: i32) -> u32 { 2 a.abs_diff(b) 3 } 4 5 #[cfg(test)] 6 mod tests { 7 use super::*; 8 use proptest::prelude::*; 9 10 proptest! { 11 #[test] 12 fn abs_diff_is_symmetric(a in any::<i32>(), b in any::<i32>()) { 13 prop_assert_eq!(abs_diff(a, b), abs_diff(b, a)); 14 } 15 } 16 } ``` `cargo test` output: ```text 1 running 1 test 2 test tests::abs_diff_is_symmetric ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.02s ``` ### Exercise 2: Invariants of a sort [Section titled “Exercise 2: Invariants of a sort”](#exercise-2-invariants-of-a-sort) **Difficulty:** Medium **Objective:** Assert *multiple* invariants about a function’s output, not a single exact value. **Instructions:** Write `my_sort(v: Vec<i32>) -> Vec<i32>` that returns the input sorted ascending. Then write one property over a generated `Vec<i32>` (use `prop::collection::vec(any::<i32>(), 0..50)`) that checks **two** invariants: (a) the output length equals the input length, and (b) the output is non-decreasing. Why is “length is preserved” worth asserting even though you only called `.sort()`? ```rust 1 pub fn my_sort(v: Vec<i32>) -> Vec<i32> { 2 // TODO 3 } 4 5 // TODO: add a #[cfg(test)] mod tests with a proptest! property ``` Solution ```rust 1 pub fn my_sort(mut v: Vec<i32>) -> Vec<i32> { 2 v.sort(); 3 v 4 } 5 6 #[cfg(test)] 7 mod tests { 8 use super::*; 9 use proptest::prelude::*; 10 11 proptest! { 12 #[test] 13 fn sort_keeps_len_and_orders(v in prop::collection::vec(any::<i32>(), 0..50)) { 14 let original_len = v.len(); 15 let sorted = my_sort(v); 16 // (a) sorting must not add or drop elements 17 prop_assert_eq!(sorted.len(), original_len); 18 // (b) the result is non-decreasing 19 prop_assert!(sorted.windows(2).all(|w| w[0] <= w[1])); 20 } 21 } 22 } ``` `cargo test` output: ```text 1 running 1 test 2 test tests::sort_keeps_len_and_orders ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.02s ``` The length invariant matters for *other* sort implementations you might write: a hand-rolled merge sort (like the buggy `merge_sorted` earlier) can easily drop or duplicate elements while still producing a sorted-looking result. “Output is sorted” alone would not catch that; “output is sorted **and** same length” gets much closer (a multiset comparison would be airtight). ### Exercise 3: A precondition with `prop_assume!` [Section titled “Exercise 3: A precondition with prop\_assume!”](#exercise-3-a-precondition-with-prop_assume) **Difficulty:** Medium **Objective:** Generate three independent values, discard the cases that violate a precondition, and assert a bounded-output property. **Instructions:** Write `clamp(value, lo, hi)` that returns `value` clamped to the range `lo..=hi`. Write a property over three independent `i32` strategies. Because `lo` and `hi` are generated separately, use `prop_assume!(lo <= hi)` to discard the inconsistent cases, then assert the result is always within `lo..=hi`. (This is a *good* use of `prop_assume!` — roughly half of all `(lo, hi)` pairs pass, so proptest finds plenty of valid cases.) ```rust 1 pub fn clamp(value: i32, lo: i32, hi: i32) -> i32 { 2 // TODO 3 } 4 5 // TODO: add a #[cfg(test)] mod tests with a proptest! property ``` Solution ```rust 1 pub fn clamp(value: i32, lo: i32, hi: i32) -> i32 { 2 value.max(lo).min(hi) 3 } 4 5 #[cfg(test)] 6 mod tests { 7 use super::*; 8 use proptest::prelude::*; 9 10 proptest! { 11 #[test] 12 fn clamp_result_is_within_bounds( 13 value in any::<i32>(), 14 lo in any::<i32>(), 15 hi in any::<i32>(), 16 ) { 17 prop_assume!(lo <= hi); // discard inconsistent ranges 18 let c = clamp(value, lo, hi); 19 prop_assert!(c >= lo && c <= hi); 20 } 21 } 22 } ``` `cargo test` output: ```text 1 running 1 test 2 test tests::clamp_result_is_within_bounds ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.02s ``` > **Tip:** A more efficient alternative avoids rejection entirely by generating an *ordered* pair with a custom strategy, for example `(any::<i32>(), any::<i32>()).prop_map(|(a, b)| if a <= b { (a, b) } else { (b, a) })`. Generating valid inputs directly is almost always better than filtering for them. # Benchmarking > Benchmark Rust with criterion: confidence intervals, baselines, and black_box to defeat the optimizer. Compared to Vitest bench; #[bench] needs nightly. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **benchmark** measures how *fast* code runs, as opposed to a [unit test](/13-testing/00-unit-tests/), which checks whether it is *correct*. Coming from JavaScript you have probably reached for `console.time`, `tinybench`, or Vitest’s experimental `bench` API; in Rust the community-standard tool is the **criterion** crate, which runs your code thousands of times, applies statistics, detects regressions against a saved baseline, and (optionally) renders HTML plots. This page covers writing and interpreting criterion 0.8 benchmarks on stable Rust, and why the built-in `#[bench]` attribute is *not* an option unless you switch to nightly. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Vitest ships an experimental `bench` API (built on `tinybench`) that mirrors its `describe`/`it` structure. Here are two implementations of Fibonacci — a naive recursive one and a linear iterative one — with a benchmark suite. fib.ts ```typescript 1 export function fibRecursive(n: number): number { 2 return n < 2 ? n : fibRecursive(n - 1) + fibRecursive(n - 2); 3 } 4 5 export function fibIterative(n: number): number { 6 let a = 0, 7 b = 1; 8 for (let i = 0; i < n; i++) [a, b] = [b, a + b]; 9 return a; 10 } ``` fib.bench.ts ```typescript 1 import { bench, describe } from "vitest"; 2 import { fibRecursive, fibIterative } from "./fib"; 3 4 describe("fib", () => { 5 bench("recursive", () => { 6 fibRecursive(20); 7 }); 8 bench("iterative", () => { 9 fibIterative(20); 10 }); 11 }); ``` Run it with `npx vitest bench --run`: ```text 1 fib.bench.ts > fib 5186ms 2 name hz min max mean p75 p99 p995 p999 rme samples 3 · recursive 9,615.15 0.0611 30.5918 0.1040 0.0654 0.3849 1.2592 10.5596 ±18.66% 4808 4 · iterative 10,822,983.33 0.0000 49.2998 0.0001 0.0001 0.0002 0.0002 0.0003 ±22.48% 5411492 5 6 BENCH Summary 7 8 iterative - fib.bench.ts > fib 9 1125.62x faster than recursive ``` Vitest reports throughput (`hz`, operations per second), percentiles, and a relative-margin-of-error (`rme`). Notice the **±18.66%** and **±22.48%** error bars: micro-benchmarks on a multitasking OS are inherently noisy, and a good tool tells you *how* noisy. Criterion takes the same idea much further. > **Note:** Vitest prints `Benchmarking is an experimental feature`. The JavaScript ecosystem still treats benchmarking as a bolt-on. Criterion has been the de-facto Rust standard for years and is stable. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Criterion benchmarks do **not** live in `src/` next to unit tests. They go in a top-level `benches/` directory (a sibling of `src/` and `tests/`), each file is a separate benchmark target, and you must register it in `Cargo.toml` so cargo knows to use criterion’s harness instead of the built-in one. First, the library code under test. The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically. src/lib.rs ```rust 1 /// Naive recursive Fibonacci — exponential time. 2 pub fn fib_recursive(n: u64) -> u64 { 3 match n { 4 0 => 0, 5 1 => 1, 6 _ => fib_recursive(n - 1) + fib_recursive(n - 2), 7 } 8 } 9 10 /// Iterative Fibonacci — linear time. 11 pub fn fib_iterative(n: u64) -> u64 { 12 let (mut a, mut b) = (0u64, 1u64); 13 for _ in 0..n { 14 (a, b) = (b, a + b); 15 } 16 a 17 } ``` Add criterion as a development dependency: ```bash 1 cargo add --dev criterion --features html_reports ``` That writes the following to `Cargo.toml`. The `[[bench]]` table and `harness = false` are **mandatory** (more on why in Common Pitfalls): Cargo.toml ```toml 1 [dev-dependencies] 2 criterion = { version = "0.8.2", features = ["html_reports"] } 3 4 [[bench]] 5 name = "fib" # matches benches/fib.rs 6 harness = false # disable libtest's harness; criterion provides its own main() ``` Now the benchmark itself: benches/fib.rs ```rust 1 use criterion::{criterion_group, criterion_main, Criterion}; 2 use std::hint::black_box; 3 4 use perf::{fib_iterative, fib_recursive}; 5 6 fn bench_fib(c: &mut Criterion) { 7 c.bench_function("fib_recursive 20", |b| { 8 b.iter(|| fib_recursive(black_box(20))) 9 }); 10 c.bench_function("fib_iterative 20", |b| { 11 b.iter(|| fib_iterative(black_box(20))) 12 }); 13 } 14 15 criterion_group!(benches, bench_fib); 16 criterion_main!(benches); ``` Run it with `cargo bench`: ```text 1 fib_recursive 20 time: [27.921 µs 33.765 µs 42.311 µs] 2 Found 17 outliers among 100 measurements (17.00%) 3 7 (7.00%) high mild 4 10 (10.00%) high severe 5 6 fib_iterative 20 time: [7.3826 ns 7.9508 ns 8.8231 ns] 7 Found 13 outliers among 100 measurements (13.00%) 8 1 (1.00%) high mild 9 12 (12.00%) high severe ``` The iterative version runs in *nanoseconds*; the recursive one in *microseconds* — roughly a 4000x gap for `n = 20`, far more dramatic than the JavaScript numbers because both are running as optimized native code with no interpreter overhead to mask the algorithmic difference. > **Note:** `cargo bench` always compiles in **release mode** (optimizations on). This is the opposite of `cargo test`, which defaults to debug. Benchmarking a debug build measures the wrong thing entirely. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) Let’s walk through the moving parts and contrast each with the Vitest version. ### The `benches/` directory and the `[[bench]]` target [Section titled “The benches/ directory and the \[\[bench\]\] target”](#the-benches-directory-and-the-bench-target) Vitest discovers `*.bench.ts` files by glob. Cargo is explicit: each file in `benches/` is a separate compiled binary, and the `[[bench]]` table in `Cargo.toml` declares it. The `name = "fib"` must match the filename `benches/fib.rs` (without the extension). `harness = false` tells cargo: *do not* link the built-in libtest test harness into this target. Criterion supplies its own `main()` (via the `criterion_main!` macro), and it would clash with libtest’s. Forgetting this line is the single most common criterion mistake; see Common Pitfalls. ### `use perf::{...}` — benchmarks are external consumers [Section titled “use perf::{...} — benchmarks are external consumers”](#use-perf--benchmarks-are-external-consumers) The benchmark binary depends on your crate the same way an [integration test](/13-testing/04-integration-tests/) does: it is a separate crate that `use`s your library’s **public** API by crate name (here `perf`). It cannot see private items. If you need to benchmark a private function, either make it `pub` or write the benchmark inside `src/` behind `#[cfg(test)]`. But the `benches/` convention is overwhelmingly the norm. ### `c.bench_function("name", |b| b.iter(closure))` [Section titled “c.bench\_function("name", |b| b.iter(closure))”](#cbench_functionname-b-biterclosure) This is the core of criterion: * `c: &mut Criterion` is the benchmark context, handed to you by the harness. * `bench_function` registers one named benchmark, the analogue of Vitest’s `bench("name", ...)`. * The closure receives a `Bencher` (`b`), and `b.iter(|| ...)` is the part criterion times. **Criterion decides how many times to call your closure** — it warms up for 3 seconds, then collects 100 samples over \~5 seconds, automatically scaling the iteration count to the speed of the code. You do not write a loop; that is the harness’s job. This is an important difference from a hand-rolled `console.time` / `Date.now()` loop in JavaScript, where *you* pick an iteration count and hope it’s enough. Criterion picks it for you based on the measured speed, which is why a nanosecond function gets billions of iterations and a microsecond function gets fewer. ### `std::hint::black_box` — defeating the optimizer [Section titled “std::hint::black\_box — defeating the optimizer”](#stdhintblack_box--defeating-the-optimizer) ```rust 1 b.iter(|| fib_recursive(black_box(20))) ``` `black_box` is the most important — and most Rust-specific — piece here. Rust’s optimizer is aggressive: if it can see that `fib_recursive(20)` is called with a constant and its result is thrown away, it may compute the answer *at compile time* (constant-folding) or delete the call entirely (dead-code elimination). Your benchmark would then measure *nothing*. `std::hint::black_box(x)` is a compiler hint that means “pretend this value is used in an opaque way you can’t reason about.” Wrapping the input prevents constant-folding the argument; the value `b.iter` returns from the closure is itself black-boxed by criterion so the result isn’t eliminated. There is no JavaScript equivalent because V8 doesn’t constant-fold across a function boundary the way an ahead-of-time native optimizer does. > **Warning:** `black_box` lives in `std::hint`. Criterion 0.8 still re-exports `criterion::black_box`, but it is **deprecated**: using it produces `warning: use of deprecated function 'criterion::black_box': use 'std::hint::black_box()' instead`. Always import `std::hint::black_box`. ### `criterion_group!` and `criterion_main!` [Section titled “criterion\_group! and criterion\_main!”](#criterion_group-and-criterion_main) ```rust 1 criterion_group!(benches, bench_fib); 2 criterion_main!(benches); ``` `criterion_group!` bundles one or more benchmark functions under a group name. `criterion_main!` generates the `fn main()` for the binary, runs the listed groups, parses CLI arguments, and writes results to `target/criterion/`. Together they replace the `main` that `harness = false` removed. (These are macros, like much of Rust’s testing machinery; see [Macros](/14-macros/).) *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | JavaScript (Vitest `bench` / tinybench) | Rust (criterion) | | ---------------------- | ------------------------------------------- | ------------------------------------------------------- | | Maturity | Experimental, may break SemVer | Stable, de-facto standard for years | | Where benchmarks live | `*.bench.ts`, discovered by glob | `benches/*.rs`, declared in `Cargo.toml` as `[[bench]]` | | Build profile | Whatever your dev build is (JIT-warmed) | Always **release** (optimized) | | Iteration count | Tool picks, or you set `time`/`iterations` | Criterion auto-scales to hit \~5s of samples | | Defeating the compiler | Rarely needed (JIT won’t fold across calls) | Essential: wrap inputs in `std::hint::black_box` | | Statistics | hz, percentiles, rme | confidence interval `[lower estimate upper]`, outliers | | Regression detection | Manual / external | Built in: compares to last run or a named **baseline** | | Output artifacts | Terminal table | Terminal + `target/criterion/` HTML plots | Two differences deserve emphasis: **Criterion is statistical, not a single number.** Each line like `time: [27.921 µs 33.765 µs 42.311 µs]` is a **confidence interval**: lower bound, best estimate (the middle), upper bound. A single `Date.now()` delta is one noisy sample; criterion reports the *distribution* and warns you when it’s too wide to trust. **Regression detection is automatic.** Run a benchmark twice and the second run compares itself against the first, printing `change: [...]` and a verdict like `Performance has improved.` or `Performance has regressed.` with a p-value. This is how teams catch accidental slowdowns in CI. There is no built-in JavaScript equivalent. *** ## Interpreting the Results [Section titled “Interpreting the Results”](#interpreting-the-results) A criterion line has three numbers and they are *not* min/mean/max — they are the bounds of a 95% confidence interval for the **mean** time per iteration: ```text 1 fib_recursive 20 time: [27.921 µs 33.765 µs 42.311 µs] 2 └ lower └ estimate └ upper ``` Read it as: “criterion is 95% confident the true average time is between 27.9 µs and 42.3 µs, with 33.8 µs as the best single guess.” The **wider** that interval, the **noisier** the measurement and the less you should trust a small difference. A tight interval like `[7.3826 ns 7.9508 ns 8.8231 ns]` is more believable than a 1.5x-wide one. The outlier report tells you how stable the run was: ```text 1 Found 17 outliers among 100 measurements (17.00%) 2 7 (7.00%) high mild 3 10 (10.00%) high severe ``` “High” outliers are samples that took *longer* than expected: usually the OS scheduler, another process, or a CPU frequency change interrupting your benchmark. A handful of mild outliers is normal; a large fraction of severe ones means your machine was busy and you should re-run on an idle system before drawing conclusions. ### Comparing against a previous run [Section titled “Comparing against a previous run”](#comparing-against-a-previous-run) On the *second* `cargo bench`, criterion compares against what it saved last time: ```text 1 fib_recursive 20 time: [21.305 µs 21.890 µs 22.751 µs] 2 change: [−49.998% −42.701% −34.154%] (p = 0.00 < 0.05) 3 Performance has improved. 4 5 fib_iterative 20 time: [7.1465 ns 7.2095 ns 7.2894 ns] 6 change: [−67.420% −58.014% −44.336%] (p = 0.00 < 0.05) 7 Performance has improved. ``` (The “improvement” here is largely the first run having been measured on a busier machine, a reminder that the absolute numbers are environment-dependent.) The `change:` line is itself a confidence interval, and the `p = 0.00 < 0.05` means the difference is statistically significant. When `p` is *above* the threshold criterion prints `No change in performance detected.` instead — a noise-induced wobble it deliberately refuses to call a regression. ### Named baselines for CI [Section titled “Named baselines for CI”](#named-baselines-for-ci) For reproducible comparisons (e.g., “this PR vs `main`”), save a named baseline and compare against it later: ```bash 1 # On the main branch: 2 cargo bench -- --save-baseline main 3 4 # After switching to your feature branch: 5 cargo bench -- --baseline main ``` Other useful arguments (everything after `--` goes to criterion, not cargo): * `cargo bench -- --sample-size 50`: fewer samples for a quicker, rougher run. * `cargo bench -- --measurement-time 10`: collect samples over 10 seconds for tighter intervals. * `cargo bench -- --noplot`: skip plot generation. * `cargo bench -- fib_iterative`: run only benchmarks whose name contains the filter string. ### The HTML report [Section titled “The HTML report”](#the-html-report) With the `html_reports` feature enabled, criterion writes `target/criterion/report/index.html` plus per-benchmark plots (PDF of the timing distribution, regression line, comparison with the previous run). Open it in a browser for a visual view; install `gnuplot` for nicer charts, otherwise criterion falls back to the `plotters` crate automatically. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting `harness = false` [Section titled “Pitfall 1: Forgetting harness = false”](#pitfall-1-forgetting-harness--false) If you omit `harness = false` from the `[[bench]]` table, cargo links the **built-in libtest harness** into your benchmark binary. That harness ignores criterion’s `main()`, looks for `#[bench]`/`#[test]` functions (there are none), and reports: ```text 1 running 0 tests 2 3 test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` No error, no benchmark: it just silently does nothing. If `cargo bench` finishes instantly and says `running 0 tests`, this is almost always the cause. The fix is the one line: ```toml 1 [[bench]] 2 name = "fib" 3 harness = false # <- do not omit ``` ### Pitfall 2: Not using `black_box`, so the optimizer deletes your code [Section titled “Pitfall 2: Not using black\_box, so the optimizer deletes your code”](#pitfall-2-not-using-black_box-so-the-optimizer-deletes-your-code) Writing `b.iter(|| fib_iterative(20))` without `black_box` lets the optimizer constant-fold `fib_iterative(20)` to a literal and time an empty loop. You’d see a suspiciously flat result like `time: [0.0000 ns ...]` or a number far smaller than physically plausible. Wrap inputs (and trust criterion to black-box the return value): ```rust 1 use std::hint::black_box; 2 // ... 3 b.iter(|| fib_iterative(black_box(20))) ``` If a benchmark reports a function taking essentially zero time, suspect a missing `black_box` before believing your code is infinitely fast. ### Pitfall 3: Reaching for `#[bench]` (it’s nightly-only) [Section titled “Pitfall 3: Reaching for #\[bench\] (it’s nightly-only)”](#pitfall-3-reaching-for-bench-its-nightly-only) Rust *does* have a built-in `#[bench]` attribute, and old blog posts use it: ```rust 1 // does not compile on stable (error[E0554]) 2 #![feature(test)] 3 extern crate test; 4 use test::Bencher; 5 6 #[bench] 7 fn bench_add(b: &mut Bencher) { 8 b.iter(|| 1 + 1); 9 } ``` On stable `rustc` this fails immediately: ```text 1 error[E0554]: `#![feature]` may not be used on the stable release channel 2 --> src/lib.rs:1:1 3 | 4 1 | #![feature(test)] 5 | ^^^^^^^^^^^^^^^^^ ``` The `test` crate and `#[bench]` have been “about to stabilize” for a decade and remain **nightly-only**. Do not use them on stable. Criterion is the stable answer and is more capable anyway (statistics, baselines, plots). The other actively maintained alternative is the **divan** crate, which offers a lighter, attribute-style API — also stable — if you prefer it. ### Pitfall 4: Including setup inside the timed closure [Section titled “Pitfall 4: Including setup inside the timed closure”](#pitfall-4-including-setup-inside-the-timed-closure) Anything inside the `b.iter(|| ...)` closure is measured *every iteration*. If you build a large input there, you benchmark the setup, not the function. Build inputs **outside** the closure, or use the input-aware forms (`iter_batched`, `bench_with_input`) shown below. ```rust 1 // measures String allocation on every iteration 2 b.iter(|| { 3 let data = "1,2,3,4,5".to_string(); 4 sum_csv_line(black_box(&data)) 5 }); 6 7 // build once, measure only the call 8 let data = "1,2,3,4,5".to_string(); 9 b.iter(|| sum_csv_line(black_box(&data))); ``` ### Pitfall 5: Trusting numbers from a busy machine [Section titled “Pitfall 5: Trusting numbers from a busy machine”](#pitfall-5-trusting-numbers-from-a-busy-machine) A large fraction of “high severe” outliers, or wildly different numbers between runs, means the environment is noisy. Close other programs, disable CPU turbo/throttling if you can, run on an idle machine, and prefer the `change:` verdict (which accounts for variance) over eyeballing raw nanoseconds. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Benchmark realistic inputs across sizes [Section titled “Benchmark realistic inputs across sizes”](#benchmark-realistic-inputs-across-sizes) A single input size hides how an algorithm scales. Use a `BenchmarkGroup` with `bench_with_input` to sweep sizes, and `Throughput` so criterion reports bytes/elements per second: benches/csv.rs ```rust 1 use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion, Throughput}; 2 use std::hint::black_box; 3 4 use perf::sum_csv_line; 5 6 fn make_line(n: usize) -> String { 7 (1..=n).map(|i| i.to_string()).collect::<Vec<_>>().join(",") 8 } 9 10 fn bench_sum_csv(c: &mut Criterion) { 11 let mut group = c.benchmark_group("sum_csv_line"); 12 for size in [10usize, 100, 1_000] { 13 let line = make_line(size); 14 group.throughput(Throughput::Bytes(line.len() as u64)); 15 group.bench_with_input(BenchmarkId::from_parameter(size), &line, |b, line| { 16 b.iter(|| sum_csv_line(black_box(line))) 17 }); 18 } 19 group.finish(); 20 } 21 22 criterion_group!(benches, bench_sum_csv); 23 criterion_main!(benches); ``` Real `cargo bench` output (the `thrpt:` line is the throughput interval): ```text 1 sum_csv_line/10 time: [106.39 ns 129.57 ns 157.18 ns] 2 thrpt: [121.35 MiB/s 147.20 MiB/s 179.28 MiB/s] 3 sum_csv_line/100 time: [1.0096 µs 1.1391 µs 1.3095 µs] 4 thrpt: [211.92 MiB/s 243.64 MiB/s 274.88 MiB/s] 5 sum_csv_line/1000 time: [9.8442 µs 9.9936 µs 10.168 µs] 6 thrpt: [365.03 MiB/s 371.41 MiB/s 377.04 MiB/s] ``` Throughput *rising* with input size (here \~121 → \~371 MiB/s) tells you the per-call fixed overhead is being amortized over more work, a signal you couldn’t read off a single timing number. ### Benchmark correct code [Section titled “Benchmark correct code”](#benchmark-correct-code) A fast wrong answer is worthless. Keep [unit tests](/13-testing/00-unit-tests/) green first; benchmark only code you trust. Criterion and `cargo test` are independent; benchmarks do not assert correctness. ### Keep benchmarks in `benches/`, commit baselines deliberately [Section titled “Keep benchmarks in benches/, commit baselines deliberately”](#keep-benchmarks-in-benches-commit-baselines-deliberately) Treat `benches/` like `tests/`: version-controlled, reviewed. The `target/criterion/` data is a build artifact; leave it out of git (the default `.gitignore` for `target/` handles this). For CI regression-gating, save a baseline from your main branch and compare PRs against it. ### Use `iter_batched` when each iteration needs fresh, consumed input [Section titled “Use iter\_batched when each iteration needs fresh, consumed input”](#use-iter_batched-when-each-iteration-needs-fresh-consumed-input) If the code under test *consumes* or *mutates* its input (e.g., sorting a `Vec` in place), build a fresh copy per batch so you don’t measure an already-sorted vector on the second iteration: ```rust 1 use criterion::{BatchSize, Criterion}; 2 3 fn bench_sort(c: &mut Criterion) { 4 c.bench_function("sort 1000", |b| { 5 b.iter_batched( 6 || (0..1000u32).rev().collect::<Vec<_>>(), // setup: NOT timed 7 |mut data| data.sort(), // routine: timed 8 BatchSize::SmallInput, 9 ) 10 }); 11 } ``` The setup closure runs outside the timer; only the routine is measured. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored scenario: you maintain a parser that sums integers from a CSV-style line, and you want to compare your current iterator-based implementation against a hand-written byte-scanning version to decide whether the rewrite is worth it. This is exactly the kind of decision criterion is built for. src/lib.rs ```rust 1 /// Iterator-based: split on commas, trim, parse, sum. 2 pub fn sum_csv_iter(line: &str) -> i64 { 3 line.split(',') 4 .filter_map(|tok| tok.trim().parse::<i64>().ok()) 5 .sum() 6 } 7 8 /// Hand-written byte scanner: one pass, no intermediate &str allocations. 9 pub fn sum_csv_scan(line: &str) -> i64 { 10 let mut total: i64 = 0; 11 let mut current: i64 = 0; 12 let mut in_number = false; 13 let mut negative = false; 14 for &byte in line.as_bytes() { 15 match byte { 16 b'0'..=b'9' => { 17 current = current * 10 + (byte - b'0') as i64; 18 in_number = true; 19 } 20 b'-' if !in_number => negative = true, 21 b',' => { 22 total += if negative { -current } else { current }; 23 current = 0; 24 in_number = false; 25 negative = false; 26 } 27 _ => {} // skip whitespace and anything else 28 } 29 } 30 total + if negative { -current } else { current } 31 } 32 33 #[cfg(test)] 34 mod tests { 35 use super::*; 36 37 #[test] 38 fn both_implementations_agree() { 39 let line = " 1, 22 ,-3,,44 "; 40 assert_eq!(sum_csv_iter(line), 64); 41 assert_eq!(sum_csv_scan(line), 64); 42 } 43 } ``` The benchmark compares both on the same input inside one group, so the report puts them side by side: benches/csv\_compare.rs ```rust 1 use criterion::{criterion_group, criterion_main, Criterion, Throughput}; 2 use std::hint::black_box; 3 4 use perf::{sum_csv_iter, sum_csv_scan}; 5 6 fn make_line(n: usize) -> String { 7 (1..=n).map(|i| i.to_string()).collect::<Vec<_>>().join(",") 8 } 9 10 fn bench_compare(c: &mut Criterion) { 11 let line = make_line(1_000); 12 let mut group = c.benchmark_group("sum_csv 1000 fields"); 13 group.throughput(Throughput::Bytes(line.len() as u64)); 14 15 group.bench_function("iter", |b| { 16 b.iter(|| sum_csv_iter(black_box(&line))) 17 }); 18 group.bench_function("scan", |b| { 19 b.iter(|| sum_csv_scan(black_box(&line))) 20 }); 21 22 group.finish(); 23 } 24 25 criterion_group!(benches, bench_compare); 26 criterion_main!(benches); ``` Cargo.toml ```toml 1 [dev-dependencies] 2 criterion = { version = "0.8.2", features = ["html_reports"] } 3 4 [[bench]] 5 name = "csv_compare" 6 harness = false ``` Running `cargo bench` first confirms correctness via `cargo test` (run separately), then produces a side-by-side timing for the two strategies under the `sum_csv 1000 fields/iter` and `sum_csv 1000 fields/scan` names. You read the two confidence intervals, check that they don’t overlap, glance at the `change:` line if you’ve benchmarked before, and only then decide whether the byte-scanner’s extra complexity earns its keep. That data-driven loop — measure, change, measure again, let criterion judge the difference — is the entire point. > **Tip:** Pair benchmarking with [coverage](/13-testing/10-coverage/) and a fast runner like `cargo nextest` for everyday testing; reach for criterion only when a *performance* question (not a correctness one) is on the table. Premature micro-benchmarking is as wasteful as premature optimization. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [Criterion.rs User Guide](https://bheisler.github.io/criterion.rs/book/index.html) — the authoritative manual: groups, throughput, baselines, plotting. * [`criterion` on crates.io](https://crates.io/crates/criterion) and [docs.rs](https://docs.rs/criterion/latest/criterion/): current API reference. * [`std::hint::black_box`](https://doc.rust-lang.org/std/hint/fn.black_box.html): why and how it defeats the optimizer. * [`cargo bench` reference](https://doc.rust-lang.org/cargo/commands/cargo-bench.html): the cargo side of running benchmarks. * [The unstable `test` crate / `#[bench]`](https://doc.rust-lang.org/unstable-book/library-features/test.html): the nightly-only built-in, for context. * [`divan`](https://crates.io/crates/divan): a stable, attribute-style alternative to criterion. * Sibling topics in this section: * [Unit Tests](/13-testing/00-unit-tests/) — correctness with `#[test]`; benchmarks measure speed, not correctness. * [Integration Tests](/13-testing/04-integration-tests/) — like `benches/`, these are external crates that see only your public API. * [Property Testing](/13-testing/07-property-testing/): for exploring input *spaces* rather than timing. * [Coverage](/13-testing/10-coverage/): `cargo-llvm-cov` and the faster `cargo nextest` runner. * [Mocking](/13-testing/06-mocking/), [Test Fixtures](/13-testing/05-test-fixtures/), [Doc Tests](/13-testing/09-doc-tests/), [TDD Workflow](/13-testing/11-tdd-workflow/). * Foundations used above: * [Cargo Basics](/01-getting-started/03-cargo-basics/) — `cargo bench`, profiles, and `dev-dependencies`. * [Basics: Types](/02-basics/01-types/) — the `u64`/`i64` integer types these benchmarks use. * [Macros](/14-macros/) — `criterion_group!`/`criterion_main!` and `#[bench]` are macros/attributes. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Your first criterion benchmark [Section titled “Exercise 1: Your first criterion benchmark”](#exercise-1-your-first-criterion-benchmark) **Difficulty:** Easy **Objective:** Set up criterion from scratch and benchmark a single function. **Instructions:** Given a `pub fn factorial(n: u64) -> u64` (iterative), create a `benches/factorial.rs` that benchmarks `factorial(10)`. Add the `[dev-dependencies]` and `[[bench]]` entries to `Cargo.toml` (don’t forget `harness = false`), wrap the input in `black_box`, and run `cargo bench`. src/lib.rs ```rust 1 pub fn factorial(n: u64) -> u64 { 2 (1..=n).product() 3 } 4 5 // TODO: write benches/factorial.rs and the Cargo.toml entries ``` Solution Cargo.toml ```toml 1 [dev-dependencies] 2 criterion = { version = "0.8.2", features = ["html_reports"] } 3 4 [[bench]] 5 name = "factorial" 6 harness = false ``` benches/factorial.rs ```rust 1 use criterion::{criterion_group, criterion_main, Criterion}; 2 use std::hint::black_box; 3 4 use my_crate::factorial; // replace `my_crate` with your crate name 5 6 fn bench_factorial(c: &mut Criterion) { 7 c.bench_function("factorial 10", |b| { 8 b.iter(|| factorial(black_box(10))) 9 }); 10 } 11 12 criterion_group!(benches, bench_factorial); 13 criterion_main!(benches); ``` `cargo bench` prints a line like: ```text 1 factorial 10 time: [4.1 ns 4.3 ns 4.6 ns] ``` (The exact nanoseconds depend on your machine; what matters is that you get a three-number confidence interval, not `running 0 tests`.) ### Exercise 2: Compare two implementations across input sizes [Section titled “Exercise 2: Compare two implementations across input sizes”](#exercise-2-compare-two-implementations-across-input-sizes) **Difficulty:** Medium **Objective:** Use a `BenchmarkGroup` with `bench_with_input` to compare two functions over several sizes. **Instructions:** Write two functions that compute the sum `1 + 2 + ... + n`: a `sum_loop(n: u64) -> u64` using a `for` loop, and a `sum_formula(n: u64) -> u64` using `n * (n + 1) / 2`. Benchmark both for `n` in `[100, 10_000, 1_000_000]` inside a single group, so the report shows them side by side. Remember to `black_box` the input. Solution src/lib.rs ```rust 1 pub fn sum_loop(n: u64) -> u64 { 2 let mut total = 0u64; 3 for i in 1..=n { 4 total += i; 5 } 6 total 7 } 8 9 pub fn sum_formula(n: u64) -> u64 { 10 n * (n + 1) / 2 11 } ``` benches/sums.rs ```rust 1 use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion}; 2 use std::hint::black_box; 3 4 use my_crate::{sum_formula, sum_loop}; 5 6 fn bench_sums(c: &mut Criterion) { 7 let mut group = c.benchmark_group("sum 1..=n"); 8 for n in [100u64, 10_000, 1_000_000] { 9 group.bench_with_input(BenchmarkId::new("loop", n), &n, |b, &n| { 10 b.iter(|| sum_loop(black_box(n))) 11 }); 12 group.bench_with_input(BenchmarkId::new("formula", n), &n, |b, &n| { 13 b.iter(|| sum_formula(black_box(n))) 14 }); 15 } 16 group.finish(); 17 } 18 19 criterion_group!(benches, bench_sums); 20 criterion_main!(benches); ``` `cargo bench` produces six benchmarks (`sum 1..=n/loop/100`, `sum 1..=n/formula/100`, and so on). The formula stays in single-digit nanoseconds for *every* `n` because it’s O(1), while the loop’s time grows linearly with `n` — the constant-time line is flat while the loop line climbs, which is the whole point of sweeping sizes. ### Exercise 3: Save a baseline and detect a regression [Section titled “Exercise 3: Save a baseline and detect a regression”](#exercise-3-save-a-baseline-and-detect-a-regression) **Difficulty:** Medium **Objective:** Use criterion’s baseline machinery to prove a change made code slower. **Instructions:** Start with an efficient `pub fn contains(haystack: &[i32], needle: i32) -> bool` that uses the standard library’s `.contains()`. Benchmark it, save the result as a baseline named `fast`. Then rewrite `contains` to be deliberately slower (e.g., sort a clone on every call before scanning), and run the benchmark again comparing against the `fast` baseline. Observe criterion report `Performance has regressed.` Solution Step 1 — the fast version: src/lib.rs ```rust 1 pub fn contains(haystack: &[i32], needle: i32) -> bool { 2 haystack.contains(&needle) 3 } ``` benches/search.rs ```rust 1 use criterion::{criterion_group, criterion_main, Criterion}; 2 use std::hint::black_box; 3 4 use my_crate::contains; 5 6 fn bench_contains(c: &mut Criterion) { 7 let data: Vec<i32> = (0..1_000).collect(); 8 c.bench_function("contains worst case", |b| { 9 // 1_001 is absent: forces a full scan. 10 b.iter(|| contains(black_box(&data), black_box(1_001))) 11 }); 12 } 13 14 criterion_group!(benches, bench_contains); 15 criterion_main!(benches); ``` Save the baseline: ```bash 1 cargo bench -- --save-baseline fast ``` Step 2 — make it slower (pointless extra work each call): src/lib.rs ```rust 1 pub fn contains(haystack: &[i32], needle: i32) -> bool { 2 let mut sorted = haystack.to_vec(); // clone on every call 3 sorted.sort(); // O(n log n) work we don't need 4 sorted.binary_search(&needle).is_ok() 5 } ``` Step 3 — compare against the saved baseline: ```bash 1 cargo bench -- --baseline fast ``` Criterion prints something like: ```text 1 contains worst case time: [12.4 µs 12.6 µs 12.9 µs] 2 change: [+900% +1200% +1500%] (p = 0.00 < 0.05) 3 Performance has regressed. ``` The `change:` interval is positive and `p < 0.05`, so criterion flags a statistically significant regression. (Exact percentages depend on your machine.) This is the workflow CI uses to fail a build that accidentally slows a hot path. # Documentation Tests > Rust compiles and runs the examples in /// doc comments via cargo test, so they cannot rot like an inert JSDoc @example. Covers hidden lines, ? In TypeScript you might put a usage example in a JSDoc `@example` block, but that text is never executed — it can rot the moment you rename a parameter. Rust takes the opposite stance: the code examples you write in `///` doc comments are *compiled and run* by `cargo test`. Your documentation and your tests become the same artifact, and an out-of-date example is a build failure. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **documentation test** (or **doc test**) is a fenced code block written inside a Rust documentation comment (`///` on an item, or `//!` at the top of a module). When you run `cargo test`, `rustdoc` extracts each block, wraps it in a hidden `fn main`, compiles it as a tiny standalone program, and runs it. This guarantees that every example in your published docs actually works against the current public Application Programming Interface (API). There is no equivalent in Jest or Vitest — a JSDoc `@example` is inert prose. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) A common JavaScript pattern is to document a function with a JSDoc `@example`. It looks helpful, but nothing checks it. money.ts ```typescript 1 /** 2 * Formats an amount given in integer cents as a currency string. 3 * 4 * @example 5 * formatCents(199); // => "$1.99" <-- this comment is NEVER executed 6 */ 7 export function formatCents(cents: number): string { 8 const dollars = Math.floor(cents / 100); 9 const remainder = String(cents % 100).padStart(2, "0"); 10 return `$${dollars}.${remainder}`; 11 } ``` The `@example` block is just text inside a comment. If you later change `formatCents` to take a `{ cents }` object, the example still *says* `formatCents(199)` and nobody is warned. The only way to verify documentation in the JavaScript world is to write a *separate* test that happens to mirror the docs: money.test.ts ```typescript 1 import { describe, it, expect } from "vitest"; 2 import { formatCents } from "./money"; 3 4 describe("formatCents", () => { 5 it("matches the documented example", () => { 6 expect(formatCents(199)).toBe("$1.99"); 7 }); 8 }); ``` Now you maintain the truth in two places — the doc comment and the test — and they can silently drift apart. Tools like `eslint-plugin-jsdoc` or `tsdoc` can lint the *shape* of a JSDoc comment, but they do not run the code inside `@example`. > **Note:** Running `money.ts` directly prints `$1.99` and `$123.00` from real `console.log` calls — but the `@example` line in the comment contributes nothing to that output. It is documentation, not behavior. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) In Rust, the example *is* the test. Here is the same function as a library crate. The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically. src/lib.rs ````rust 1 /// Formats an amount given in integer cents as a currency string. 2 /// 3 /// The amount is always rendered with exactly two decimal places. 4 /// 5 /// # Examples 6 /// 7 /// ``` 8 /// use doctest_probe::format_cents; 9 /// 10 /// assert_eq!(format_cents(1_99), "$1.99"); 11 /// assert_eq!(format_cents(0), "$0.00"); 12 /// assert_eq!(format_cents(12_300), "$123.00"); 13 /// ``` 14 pub fn format_cents(cents: u64) -> String { 15 format!("${}.{:02}", cents / 100, cents % 100) 16 } ```` Run `cargo test` and the example runs as a test. (The crate here is named `doctest_probe`; substitute your own crate name in the `use` line.) ```text 1 Doc-tests doctest_probe 2 3 running 1 test 4 test src/lib.rs - format_cents (line 9) ... ok 5 6 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s ``` The test name — `src/lib.rs - format_cents (line 9)` — points straight at the file and line of the doc comment. If you renamed `format_cents` or changed its output, this block would fail to compile or assert, and `cargo test` would go red. The documentation can no longer lie. > **Tip:** Doc tests only run for **library** targets. A binary-only crate (`src/main.rs`) has no public API to document, so `cargo test` skips doc tests there. If you want doc-tested examples in a binary project, move the logic into a `lib.rs` (a `src/lib.rs` alongside `src/main.rs`) — the common “thin binary, fat library” layout covered in [Modules and Packages](/12-modules-packages/). *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) Let’s unpack exactly what `rustdoc` does with that fenced block, contrasting each step with the JavaScript mental model. ### The fence with no language is treated as Rust [Section titled “The fence with no language is treated as Rust”](#the-fence-with-no-language-is-treated-as-rust) ````text 1 /// ``` 2 /// use doctest_probe::format_cents; 3 /// assert_eq!(format_cents(1_99), "$1.99"); 4 /// ``` ```` Inside a doc comment, a bare ` ``` ` fence defaults to Rust. (You can write ` ```rust ` explicitly, and you should when the doc is rendered somewhere that does not assume Rust.) A fence tagged with another language — ` ```json ` or ` ```text ` — is shown in the rendered docs but **not** compiled or run. So only Rust blocks become tests. ### `rustdoc` auto-wraps the block in `fn main` [Section titled “rustdoc auto-wraps the block in fn main”](#rustdoc-auto-wraps-the-block-in-fn-main) The single most surprising thing for a newcomer: the snippet above has no `fn main`, yet it runs. Before compiling, `rustdoc` wraps the block in a generated `fn main` and adds `extern crate` glue, roughly like this: ```rust 1 fn main() { 2 use doctest_probe::format_cents; 3 assert_eq!(format_cents(1_99), "$1.99"); 4 } ``` That is why a doc test reads like the *body* of a function. You almost never write `fn main` yourself; if you do (because you need a custom signature), `rustdoc` detects it and uses yours instead. ### Your crate is in scope, but not auto-imported [Section titled “Your crate is in scope, but not auto-imported”](#your-crate-is-in-scope-but-not-auto-imported) A doc test is compiled as if it were an *external* user of your crate. That means: * You refer to your items through the crate path: `use doctest_probe::format_cents;` (or the full path `doctest_probe::format_cents(...)`). * Only **public** (`pub`) items are reachable — exactly like a downstream consumer. A doc test cannot see private functions, which makes it a genuine black-box check of your public surface. This is the opposite of the in-file `#[cfg(test)] mod tests` from [Unit Tests](/13-testing/00-unit-tests/), which *can* reach private items. Doc tests document and verify the public API; unit tests probe the internals. ### A doc test passes by not panicking [Section titled “A doc test passes by not panicking”](#a-doc-test-passes-by-not-panicking) Just like a `#[test]` function (see [Unit Tests](/13-testing/00-unit-tests/)), a doc test “passes” if its generated `main` returns normally and “fails” if it **panics**. The `assert_eq!` macro panics on mismatch, which is how the example doubles as an assertion. There is no `expect(...).toBe(...)` — you use the same `assert!`/`assert_eq!` macros described in [Assertions](/13-testing/02-assertions/). ### Numeric literals: `1_99` is just `199` [Section titled “Numeric literals: 1\_99 is just 199”](#numeric-literals-1_99-is-just-199) The underscore in `1_99` is a digit separator (Rust allows `_` anywhere in a numeric literal). It is written `1_99` purely to read as “1 dollar, 99 cents”; the compiler sees `199`. This mirrors a JavaScript habit but is a real language feature here, not a string trick. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | JSDoc `@example` (TypeScript/JavaScript) | Rust doc test | | ------------------------------- | ---------------------------------------- | -------------------------------------------------- | | Is the example executed? | No — it is inert text | **Yes** — compiled and run by `cargo test` | | What enforces correctness? | A separate, hand-written test (if any) | The example *is* the test | | Where it lives | A comment above the function | A ` ``` ` block in a `///` / `//!` comment | | Visibility scope | n/a | Public API only (compiled as an external consumer) | | Boilerplate needed | n/a | None — `rustdoc` wraps it in `fn main` | | How failures surface | Never (drift is silent) | Compile error or panic during `cargo test` | | Hiding setup from rendered docs | n/a | Lines prefixed with `# `in the comment | The deeper point is a philosophy difference. JavaScript treats documentation and tests as separate concerns that you keep in sync by discipline. Rust fuses them so that *drift is impossible*: an example that no longer compiles is a failing build, not a stale comment. This is why high-quality crates like `serde` and `std` itself are saturated with runnable examples — the examples cost nothing to keep honest. > **Note:** Doc tests are slower to compile than unit tests because each block becomes its own tiny crate. On modern toolchains `rustdoc` *merges* doc tests from the same crate into a single compilation (you can see “merged doctests compilation took …” in the output), which has made them dramatically faster than they once were. Still, for a function with dozens of micro-examples, prefer a handful of meaningful ones plus a `#[cfg(test)]` module. *** ## Hidden lines, `?`, and the doc-test attributes [Section titled “Hidden lines, ?, and the doc-test attributes”](#hidden-lines--and-the-doc-test-attributes) Doc tests have a few conventions that have no JavaScript analogue. Each is a small `rustdoc` feature you control from inside the comment. ### Hidden setup lines with `#` [Section titled “Hidden setup lines with # ”](#hidden-setup-lines-with-) Sometimes a runnable example needs setup that would clutter the rendered documentation — an import, a helper value, or a trailing `Ok(())`. Prefix such a line *inside the doc comment* with `# `(hash-space) and `rustdoc` will **compile and run it but hide it from the published HTML**. This is the one and only place the `# `prefix is meaningful in Rust source. src/lib.rs ````rust 1 use std::num::ParseIntError; 2 3 /// Doubles a number parsed from a string. 4 /// 5 /// The setup line is hidden from the rendered docs but still runs: 6 /// 7 /// ``` 8 /// # use hidden_probe::double_str; 9 /// let result = double_str("21")?; 10 /// assert_eq!(result, 42); 11 /// # Ok::<(), std::num::ParseIntError>(()) 12 /// ``` 13 pub fn double_str(s: &str) -> Result<i32, ParseIntError> { 14 Ok(s.parse::<i32>()? * 2) 15 } ```` The reader of your HTML docs sees only the two interesting lines: ```rust 1 let result = double_str("21")?; 2 assert_eq!(result, 42); ``` …while `rustdoc` actually compiles all four. Two things to notice: * **The `?` operator works** because the hidden final line `# Ok::<(), ParseIntError>(())` gives the generated `main` a `Result` return type. Without it, you cannot use `?` in a doc test, just as you cannot in a normal `fn main` that returns `()`. (Returning `Result` from tests is covered for `#[test]` functions in [`#[should_panic]` and `Result` tests](/13-testing/03-should-panic/); the same idea applies here.) * The `# `prefix is purely a `rustdoc` directive. **Do not** confuse it with anything you would write in ordinary Rust code. > **Warning:** This `# `hidden-line syntax is specific to doc comments inside `.rs` files. In plain Markdown like this guide, a line starting with `# `is just a heading or literal text — never use it to “hide” lines in a Markdown code block, because there is no `rustdoc` to interpret it. ### `should_panic` — assert the example *does* panic [Section titled “should\_panic — assert the example does panic”](#should_panic--assert-the-example-does-panic) Attach `should_panic` to the fence to assert the example panics (rather than runs cleanly). This documents the failure contract of a function right next to it. src/lib.rs ````rust 1 /// Divides `total` evenly across `people`, returning cents per person. 2 /// 3 /// # Panics 4 /// 5 /// Panics if `people` is zero: 6 /// 7 /// ```should_panic 8 /// use doctest_probe::split_evenly; 9 /// 10 /// split_evenly(1000, 0); // division by zero -> panic 11 /// ``` 12 pub fn split_evenly(total: u64, people: u64) -> u64 { 13 total / people 14 } ```` `cargo test` reports it with a `- should panic` suffix: ```text 1 test src/lib.rs - split_evenly (line 52) - should panic ... ok ``` It is “ok” precisely because the example panicked as promised. (For the full semantics, including matching a specific message, see [`#[should_panic]`](/13-testing/03-should-panic/).) ### `no_run` — compile but do not execute [Section titled “no\_run — compile but do not execute”](#no_run--compile-but-do-not-execute) Some examples must *type-check* but cannot *run* in a test harness — a live HTTP request, an infinite loop, or anything touching the network or filesystem. Tag the fence `no_run`: `rustdoc` still compiles it (so it cannot rot), but skips execution. src/lib.rs ````rust 1 /// Pretends to perform a network request. 2 /// 3 /// This example compiles but is not executed, because running it would 4 /// require a live server: 5 /// 6 /// ```no_run 7 /// use hidden_probe::fetch_title; 8 /// 9 /// let title = fetch_title("https://example.com")?; 10 /// println!("{title}"); 11 /// # Ok::<(), Box<dyn std::error::Error>>(()) 12 /// ``` 13 pub fn fetch_title(_url: &str) -> Result<String, Box<dyn std::error::Error>> { 14 Ok("Example Domain".to_string()) 15 } ```` In the output, `no_run` blocks are marked `- compile`: ```text 1 test src/lib.rs - fetch_title (line 24) - compile ... ok ``` ### `ignore` — neither compile nor run [Section titled “ignore — neither compile nor run”](#ignore--neither-compile-nor-run) `ignore` is the escape hatch: the block is shown in docs but completely skipped — not even compiled. Use it sparingly, for pseudocode or examples that depend on a type that does not exist yet. Prefer `no_run` whenever the code can at least be type-checked, because `ignore` lets the example rot. src/lib.rs ````rust 1 /// A documented idea that is not yet implemented. 2 /// 3 /// ```ignore 4 /// // This snippet is neither compiled nor run. 5 /// let result = hidden_probe::not_done_yet(3); 6 /// ``` 7 pub fn placeholder() {} ```` ```text 1 test src/lib.rs - placeholder (line 38) ... ignored ``` ### `compile_fail` — assert the example *fails to compile* [Section titled “compile\_fail — assert the example fails to compile”](#compile_fail--assert-the-example-fails-to-compile) Occasionally you want to prove that something is *rejected* by the compiler — for example, that a private field cannot be mutated from outside the crate. `compile_fail` makes the doc test pass when the block fails to compile. src/lib.rs ````rust 1 /// A counter whose internal field is private. 2 /// 3 /// This example asserts at doc-test time that you CANNOT mutate the 4 /// private field from outside the crate: 5 /// 6 /// ```compile_fail 7 /// use cf_probe::Counter; 8 /// let mut c = Counter::new(); 9 /// c.count = 99; // private field -> compile error, which is expected 10 /// ``` 11 pub struct Counter { 12 count: u32, 13 } 14 15 impl Counter { 16 pub fn new() -> Self { 17 Counter { count: 0 } 18 } 19 pub fn get(&self) -> u32 { 20 self.count 21 } 22 } ```` ```text 1 test src/lib.rs - Counter (line 8) - compile fail ... ok ``` > **Tip:** All of these — `should_panic`, `no_run`, `ignore`, `compile_fail` — are written directly after the opening fence (` `no\_run `), and you can combine some of them (e.g. ``ignore,no_run `). Plain Rust (no attribute) means “compile and run.” *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting to import the item under test [Section titled “Pitfall 1: Forgetting to import the item under test”](#pitfall-1-forgetting-to-import-the-item-under-test) Because a doc test is compiled as an *external* consumer, you must bring your item into scope. Omit the `use` and the block fails to compile — which is a feature, but a confusing one the first time. ````rust 1 /// Greets a name. 2 /// 3 /// ``` 4 /// // Forgot: use cf_probe::greet; 5 /// assert_eq!(greet("Ada"), "Hello, Ada!"); 6 /// ``` 7 pub fn greet(name: &str) -> String { 8 format!("Hello, {name}!") 9 } ```` Real output from `cargo test --doc`: ```text 1 running 1 test 2 test src/lib.rs - greet (line 5) ... FAILED 3 4 failures: 5 6 ---- src/lib.rs - greet (line 5) stdout ---- 7 error[E0425]: cannot find function `greet` in this scope 8 --> src/lib.rs:7:12 9 | 10 4 | assert_eq!(greet("Ada"), "Hello, Ada!"); 11 | ^^^^^ not found in this scope 12 | 13 help: consider importing this function 14 | 15 2 + use cf_probe::greet; 16 | 17 18 error: aborting due to 1 previous error 19 20 For more information about this error, try `rustc --explain E0425`. 21 Couldn't compile the test. 22 23 failures: 24 src/lib.rs - greet (line 5) 25 26 test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.06s ``` The fix is to add the `use`. If the import is noise you would rather not show readers, hide it with the `# `prefix described above. ### Pitfall 2: A stale example silently becoming wrong [Section titled “Pitfall 2: A stale example silently becoming wrong”](#pitfall-2-a-stale-example-silently-becoming-wrong) This is the pitfall doc tests *prevent*, and it is worth seeing fail. If the documented expected value drifts from the real output, `cargo test` catches it: ````rust 1 /// Adds one. The doc example below has a WRONG expected value on purpose. 2 /// 3 /// ``` 4 /// use fail_probe::add_one; 5 /// assert_eq!(add_one(1), 3); 6 /// ``` 7 pub fn add_one(n: i32) -> i32 { 8 n + 1 9 } ```` Real failure output: ```text 1 running 1 test 2 test src/lib.rs - add_one (line 5) ... FAILED 3 4 failures: 5 6 ---- src/lib.rs - add_one (line 5) stdout ---- 7 Test executable failed (exit status: 101). 8 9 stderr: 10 11 thread 'main' panicked at /tmp/.../doctest_bundle_2024.rs:7:1: 12 assertion `left == right` failed 13 left: 2 14 right: 3 15 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace 16 17 18 failures: 19 src/lib.rs - add_one (line 5) 20 21 test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` Note the panic points at a generated file (`doctest_bundle_2024.rs`) rather than your source — that file is the merged wrapper `rustdoc` built. The test *name* (`src/lib.rs - add_one (line 5)`) is what tells you where to look in your own code. ### Pitfall 3: Trying to use `?` without a `Result`-returning wrapper [Section titled “Pitfall 3: Trying to use ? without a Result-returning wrapper”](#pitfall-3-trying-to-use--without-a-result-returning-wrapper) The generated `main` returns `()` by default. Using `?` then fails, because `?` needs a function whose return type implements `FromResidual` (i.e. a `Result` or `Option`). The fix is the hidden trailing line `# Ok::<(), SomeError>(())`, which retypes the generated `main`: ````rust 1 /// ``` 2 /// use temperature::Celsius; 3 /// let t = Celsius::parse("37C")?; // needs the line below to compile 4 /// assert_eq!(t, Celsius::new(37.0)); 5 /// # Ok::<(), temperature::ParseTempError>(()) 6 /// ``` ```` Without that last line you would get an error that `?` cannot be used in a function returning `()`. This is the same constraint as a real `fn main` and is explained alongside `Result`-returning tests in [`#[should_panic]` and `Result` tests](/13-testing/03-should-panic/). ### Pitfall 4: Reaching for a private item [Section titled “Pitfall 4: Reaching for a private item”](#pitfall-4-reaching-for-a-private-item) A doc test cannot see non-`pub` items — it is an external consumer. If you find yourself wanting to doc-test a private helper, that is a signal to test it with an in-file `#[cfg(test)] mod tests` instead (see [Test Organization](/13-testing/01-test-organization/)). Doc tests are for the public, documented surface. ### Pitfall 5: Putting `# `lines in plain Markdown [Section titled “Pitfall 5: Putting # lines in plain Markdown”](#pitfall-5-putting---lines-in-plain-markdown) The `# `hidden-line feature exists *only* inside `///`/`//!` comments in `.rs` files, where `rustdoc` processes it. If you copy a doc-test snippet into a Markdown file (like a README that is **not** run through `rustdoc`’s `--test` mode), those `# `lines render literally. When sharing examples in plain Markdown, write the full, visible code. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Lead with a `# Examples` section [Section titled “Lead with a # Examples section”](#lead-with-a--examples-section) By convention, public items get an `# Examples` heading in their doc comment, followed by one or more runnable blocks. This is what `rustdoc` renders on docs.rs and what readers expect: ````rust 1 /// Returns the underlying value. 2 /// 3 /// # Examples 4 /// 5 /// ``` 6 /// use temperature::Celsius; 7 /// assert_eq!(Celsius::new(37.0).value(), 37.0); 8 /// ``` 9 pub fn example_placeholder() {} ```` ### Write examples a reader would actually copy [Section titled “Write examples a reader would actually copy”](#write-examples-a-reader-would-actually-copy) A doc test is dual-purpose: a test *and* the example a user will paste into their own code. Favor realistic, copyable snippets over contrived ones. If a block needs setup that distracts from the point, hide it with `# `, but keep the visible part something a reader can run. ### Prefer `no_run` over `ignore` [Section titled “Prefer no\_run over ignore”](#prefer-no_run-over-ignore) `no_run` still type-checks, so it catches API drift (a renamed method, a changed signature). `ignore` catches nothing. Reach for `ignore` only when the code genuinely cannot compile in isolation. ### Run doc tests in CI, and know the commands [Section titled “Run doc tests in CI, and know the commands”](#run-doc-tests-in-ci-and-know-the-commands) * `cargo test` — runs unit tests, integration tests, **and** doc tests. * `cargo test --doc` — runs *only* the doc tests (fast feedback while editing docs). * `cargo test --doc <substring>` — filters doc tests by name. For example, `cargo test --doc format_cents` runs just that one and reports the rest as filtered out: ```text 1 Doc-tests doctest_probe 2 3 running 1 test 4 test src/lib.rs - format_cents (line 9) ... ok 5 6 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 3 filtered out; finished in 0.06s ``` > **Note:** Doc tests are *not* run by `cargo nextest`, the faster runner discussed in [Coverage](/13-testing/10-coverage/). If you rely on nextest, add a separate `cargo test --doc` step so your examples are still verified. ### Keep heavy logic out of doc tests [Section titled “Keep heavy logic out of doc tests”](#keep-heavy-logic-out-of-doc-tests) A doc test should illustrate usage in a few lines. Exhaustive case coverage, edge cases, and private-internals checks belong in `#[cfg(test)]` modules ([Unit Tests](/13-testing/00-unit-tests/)) or [property tests](/13-testing/07-property-testing/). One or two crisp examples per public item is the sweet spot. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small temperature-conversion library where every public item carries a runnable example. It shows a crate-level `//!` example, examples on methods, a `?`-using example with a hidden setup line, and an error path — all compile-verified. src/lib.rs ````rust 1 //! A small temperature-conversion library. 2 //! 3 //! Every public item carries runnable examples. Because the crate root has 4 //! its own `//!` doc comment, you can even put a top-level example here: 5 //! 6 //! ``` 7 //! use temperature::Celsius; 8 //! 9 //! let boiling = Celsius::new(100.0); 10 //! assert_eq!(boiling.to_fahrenheit(), 212.0); 11 //! ``` 12 13 /// An error returned when parsing a temperature string fails. 14 #[derive(Debug, PartialEq)] 15 pub struct ParseTempError(pub String); 16 17 impl std::fmt::Display for ParseTempError { 18 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { 19 write!(f, "invalid temperature: {}", self.0) 20 } 21 } 22 23 impl std::error::Error for ParseTempError {} 24 25 /// A temperature in degrees Celsius. 26 #[derive(Debug, Clone, Copy, PartialEq)] 27 pub struct Celsius(f64); 28 29 impl Celsius { 30 /// Creates a new `Celsius` value. 31 /// 32 /// ``` 33 /// use temperature::Celsius; 34 /// 35 /// let body = Celsius::new(37.0); 36 /// assert_eq!(body.value(), 37.0); 37 /// ``` 38 pub fn new(degrees: f64) -> Self { 39 Celsius(degrees) 40 } 41 42 /// Returns the underlying value. 43 pub fn value(self) -> f64 { 44 self.0 45 } 46 47 /// Converts to degrees Fahrenheit. 48 /// 49 /// ``` 50 /// use temperature::Celsius; 51 /// 52 /// assert_eq!(Celsius::new(0.0).to_fahrenheit(), 32.0); 53 /// assert_eq!(Celsius::new(100.0).to_fahrenheit(), 212.0); 54 /// ``` 55 pub fn to_fahrenheit(self) -> f64 { 56 self.0 * 9.0 / 5.0 + 32.0 57 } 58 59 /// Parses a string like `"37C"` into a `Celsius`. 60 /// 61 /// The `?` operator works because the hidden last line gives the 62 /// example a `Result` return type: 63 /// 64 /// ``` 65 /// use temperature::Celsius; 66 /// 67 /// let t = Celsius::parse("37C")?; 68 /// assert_eq!(t, Celsius::new(37.0)); 69 /// # Ok::<(), temperature::ParseTempError>(()) 70 /// ``` 71 /// 72 /// Bad input is reported as an error rather than panicking: 73 /// 74 /// ``` 75 /// use temperature::Celsius; 76 /// 77 /// assert!(Celsius::parse("warm").is_err()); 78 /// ``` 79 pub fn parse(s: &str) -> Result<Celsius, ParseTempError> { 80 let number = s 81 .strip_suffix('C') 82 .ok_or_else(|| ParseTempError(s.to_string()))?; 83 let degrees: f64 = number 84 .parse() 85 .map_err(|_| ParseTempError(s.to_string()))?; 86 Ok(Celsius(degrees)) 87 } 88 } 89 90 #[cfg(test)] 91 mod tests { 92 use super::*; 93 94 #[test] 95 fn parse_round_trips() { 96 assert_eq!(Celsius::parse("21C"), Ok(Celsius::new(21.0))); 97 } 98 } ```` Running `cargo test` exercises the in-file unit test *and* all five doc tests in one command — real output: ```text 1 Running unittests src/lib.rs (target/debug/deps/temperature-57d02ff4a26d2f96) 2 3 running 1 test 4 test tests::parse_round_trips ... ok 5 6 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s 7 8 Doc-tests temperature 9 10 running 5 tests 11 test src/lib.rs - (line 6) ... ok 12 test src/lib.rs - Celsius::parse (line 64) ... ok 13 test src/lib.rs - Celsius::new (line 32) ... ok 14 test src/lib.rs - Celsius::to_fahrenheit (line 49) ... ok 15 test src/lib.rs - Celsius::parse (line 74) ... ok 16 17 test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.03s ``` A few things to read out of that output: * The crate-level `//!` example shows up as `src/lib.rs - (line 6)` — the module root has no item name. * `Celsius::parse` appears **twice** (lines 64 and 74) because it has two separate fenced blocks, and each block is its own test. * The float comparisons (`32.0`, `212.0`) are exact here because these specific conversions land on representable values; for fuzzy float math you would assert within a tolerance rather than with `assert_eq!`. Running `cargo doc --no-deps` then renders this into browsable HTML where every example is displayed exactly as written — minus the `# Ok::<(), ParseTempError>(())` line, which `rustdoc` hides. The documentation a user reads is, byte for byte, code that passed your test suite. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [The Rust Book — Documentation Comments as Tests](https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#documentation-comments-as-tests) * [The `rustdoc` Book — Documentation tests](https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html) * [The `rustdoc` Book — Hiding portions of the example](https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html#hiding-portions-of-the-example) * [Rust by Example — Documentation testing](https://doc.rust-lang.org/rust-by-example/testing/doc_testing.html) * Sibling topics in this section: * [Unit Tests](/13-testing/00-unit-tests/) — `#[test]` and the in-file `#[cfg(test)] mod tests`; the “passes by not panicking” model doc tests share. * [Assertions](/13-testing/02-assertions/) — the `assert!`/`assert_eq!`/`assert_ne!` macros you use inside doc tests. * [`#[should_panic]` and `Result` tests](/13-testing/03-should-panic/) — the `should_panic` attribute and the `?`/`Result` pattern, shown here for doc tests. * [Test Organization](/13-testing/01-test-organization/) — when to use a doc test (public API) versus an in-file test (private internals). * [Integration Tests](/13-testing/04-integration-tests/) — black-box testing in `tests/`, the closest sibling to doc tests in spirit. * [Coverage](/13-testing/10-coverage/) — `cargo-llvm-cov` and why `cargo nextest` does not run doc tests. * Foundations used above: * [Cargo Basics](/01-getting-started/03-cargo-basics/) — `cargo test` and `cargo doc`. * [Modules and Packages](/12-modules-packages/) — `pub` visibility and the library-vs-binary split that determines what gets doc-tested. * [Result and Option](/08-error-handling/00-result-option/) — why `?` needs a `Result`-returning wrapper. * [Macros](/14-macros/) — `#[derive(...)]`, `assert_eq!`, and the attribute machinery behind tests. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Your first doc test [Section titled “Exercise 1: Your first doc test”](#exercise-1-your-first-doc-test) **Difficulty:** Easy **Objective:** Turn a usage comment into a runnable, verified example. **Instructions:** Given the `count_vowels` function below, add an `# Examples` doc comment with a single fenced block that asserts the vowel counts for `"hello"` (2), `"XYZ"` (0), and `"AEIOU"` (5). Remember to `use` the function. Run `cargo test --doc` and confirm it passes. ```rust 1 pub fn count_vowels(s: &str) -> usize { 2 s.chars() 3 .filter(|c| "aeiou".contains(c.to_ascii_lowercase())) 4 .count() 5 } 6 7 // TODO: add an /// # Examples doc test above the function ``` Solution ````rust 1 /// Returns the number of vowels in `s` (ASCII, case-insensitive). 2 /// 3 /// # Examples 4 /// 5 /// ``` 6 /// use ex_probe::count_vowels; 7 /// 8 /// assert_eq!(count_vowels("hello"), 2); 9 /// assert_eq!(count_vowels("XYZ"), 0); 10 /// assert_eq!(count_vowels("AEIOU"), 5); 11 /// ``` 12 pub fn count_vowels(s: &str) -> usize { 13 s.chars() 14 .filter(|c| "aeiou".contains(c.to_ascii_lowercase())) 15 .count() 16 } ```` `cargo test --doc` output: ```text 1 running 1 test 2 test src/lib.rs - count_vowels (line 6) ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s ``` ### Exercise 2: A doc test that uses `?` [Section titled “Exercise 2: A doc test that uses ?”](#exercise-2-a-doc-test-that-uses-) **Difficulty:** Medium **Objective:** Write a doc test for a fallible function, using a hidden line so the `?` operator compiles. **Instructions:** Write a `sum_csv(row: &str) -> Result<i64, ParseIntError>` that parses a comma-separated row of integers (trimming whitespace) and sums them. Add a doc test that parses `"1,2,3,4"` with `?`, asserts the total is `10`, and uses a hidden trailing line so the example’s generated `main` returns `Result`. ```rust 1 pub fn sum_csv(row: &str) -> Result<i64, std::num::ParseIntError> { 2 // TODO: split on ',', trim, parse, sum 3 todo!() 4 } 5 6 // TODO: add a doc test that uses `?` and a hidden Ok(()) line ``` Solution ````rust 1 /// Parses a CSV row of integers and sums them. 2 /// 3 /// ``` 4 /// use ex_probe::sum_csv; 5 /// 6 /// let total = sum_csv("1,2,3,4")?; 7 /// assert_eq!(total, 10); 8 /// # Ok::<(), std::num::ParseIntError>(()) 9 /// ``` 10 pub fn sum_csv(row: &str) -> Result<i64, std::num::ParseIntError> { 11 row.split(',').map(|n| n.trim().parse::<i64>()).sum() 12 } ```` The visible example shows only the two meaningful lines; the hidden `# Ok::<(), ParseIntError>(())` retypes the generated `main` so `?` is legal. `cargo test --doc` output: ```text 1 running 1 test 2 test src/lib.rs - sum_csv (line 22) ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s ``` > **Tip:** `Iterator::sum` over `Result` items short-circuits: the first parse error becomes the overall error, and `?` propagates it. That is why the whole body fits on one line. ### Exercise 3: Document a panic with `should_panic` [Section titled “Exercise 3: Document a panic with should\_panic”](#exercise-3-document-a-panic-with-should_panic) **Difficulty:** Medium **Objective:** Use the `should_panic` attribute to make the panic contract part of the documentation. **Instructions:** Write `nth(slice: &[i32], index: usize) -> i32` that indexes into the slice (panicking on out-of-bounds, which is the default for slice indexing). Add a `# Panics` doc section with a `should_panic` example that indexes past the end of a 3-element vector. ````rust 1 pub fn nth(slice: &[i32], index: usize) -> i32 { 2 // TODO: index into the slice 3 todo!() 4 } 5 6 // TODO: add a /// # Panics doc test using ```should_panic ```` Solution ````rust 1 /// Returns the element at `index`, panicking if out of bounds. 2 /// 3 /// # Panics 4 /// 5 /// ```should_panic 6 /// use ex_probe::nth; 7 /// 8 /// let data = vec![10, 20, 30]; 9 /// nth(&data, 5); // out of bounds -> panic 10 /// ``` 11 pub fn nth(slice: &[i32], index: usize) -> i32 { 12 slice[index] 13 } ```` `cargo test --doc` output — the block “passes” because it panicked as documented: ```text 1 running 1 test 2 test src/lib.rs - nth (line 5) - should panic ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s ``` # Code Coverage and Faster Test Runs > There is no cargo test --coverage flag: install cargo-llvm-cov for LLVM source-based coverage and cargo-nextest for faster, process-per-test runs, like Vitest. In the JavaScript world you reach for `jest --coverage` or `vitest --coverage` to see which lines your tests actually exercised, and you might lean on tools like Turborepo to keep test runs fast. Rust has direct equivalents: **`cargo-llvm-cov`** measures coverage using the compiler’s own instrumentation, and **`cargo-nextest`** is a drop-in faster test runner. Neither ships in the box, but both install with a single `cargo install`. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) **Code coverage** answers the question “which lines of my code ran during the test suite?” It is a way to find untested branches, not a proof of correctness. In Rust the de-facto tool is `cargo-llvm-cov`, a `cargo` subcommand that drives LLVM’s source-based coverage (the same engine Clang uses for C++), so the numbers are precise rather than estimated. Separately, **`cargo-nextest`** is a next-generation test *runner* that compiles your tests the same way `cargo test` does but executes them in a smarter, faster, process-per-test model with cleaner output. The two compose: `cargo llvm-cov nextest` collects coverage *while* running under nextest. > **Note:** The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically. The commands below work on any recent stable toolchain. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) With Vitest, coverage is a flag plus a tiny bit of config. Given a library and its tests: src/temperature.ts ```typescript 1 export function celsiusToFahrenheit(c: number): number { 2 return (c * 9) / 5 + 32; 3 } 4 5 export function classify(c: number): string { 6 if (c < 0) return "freezing"; 7 if (c < 15) return "cold"; 8 if (c < 30) return "mild"; 9 return "hot"; 10 } ``` src/temperature.test.ts ```typescript 1 import { describe, it, expect } from "vitest"; 2 import { celsiusToFahrenheit, classify } from "./temperature"; 3 4 describe("temperature", () => { 5 it("converts boiling point", () => { 6 expect(celsiusToFahrenheit(100)).toBe(212); 7 }); 8 9 it("classifies the middle bands", () => { 10 expect(classify(5)).toBe("cold"); 11 expect(classify(20)).toBe("mild"); 12 }); 13 }); ``` You enable coverage in `vitest.config.ts` and run it: vitest.config.ts ```typescript 1 import { defineConfig } from "vitest/config"; 2 3 export default defineConfig({ 4 test: { 5 coverage: { 6 provider: "v8", // V8's built-in coverage 7 reporter: ["text", "html", "lcov"], 8 }, 9 }, 10 }); ``` ```bash 1 npx vitest run --coverage ``` Vitest prints a per-file table and writes an HTML report you open in a browser. The numbers come from V8’s runtime coverage counters (or, with `provider: "istanbul"`, from source instrumentation). Notice that the two tests above never hit the `"freezing"` or `"hot"` branches; a coverage report makes that gap visible. Things a JavaScript developer takes for granted here: * Coverage is a **flag on the test runner**, configured in a project file. * You pick a **provider** (`v8` or `istanbul`) and a set of **reporters**. * The output includes `lcov.info`, which Codecov, Coveralls, and editors understand. Every one of those maps cleanly onto a Rust tool. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) `cargo test` itself has no `--coverage` flag. Instead you install a subcommand once: ```bash 1 # One-time install. cargo has had `add`/`install` built in since 1.62 — 2 # no cargo-edit or extra tooling needed. 3 cargo install cargo-llvm-cov ``` `cargo-llvm-cov` needs the LLVM tools that ship with the toolchain. On a `rustup`-managed install it adds them automatically; if you manage Rust another way, run `rustup component add llvm-tools-preview` once. Here is the same library and test suite in Rust: src/lib.rs ```rust 1 //! Temperature conversion and classification. 2 3 /// Converts Celsius to Fahrenheit. 4 pub fn celsius_to_fahrenheit(c: f64) -> f64 { 5 c * 9.0 / 5.0 + 32.0 6 } 7 8 /// Converts Fahrenheit to Celsius. 9 pub fn fahrenheit_to_celsius(f: f64) -> f64 { 10 (f - 32.0) * 5.0 / 9.0 11 } 12 13 /// Classifies a Celsius temperature into a human-readable band. 14 pub fn classify(c: f64) -> &'static str { 15 if c < 0.0 { 16 "freezing" 17 } else if c < 15.0 { 18 "cold" 19 } else if c < 30.0 { 20 "mild" 21 } else { 22 "hot" 23 } 24 } 25 26 #[cfg(test)] 27 mod tests { 28 use super::*; 29 30 #[test] 31 fn boiling_point_converts() { 32 assert_eq!(celsius_to_fahrenheit(100.0), 212.0); 33 } 34 35 #[test] 36 fn freezing_point_converts_back() { 37 assert_eq!(fahrenheit_to_celsius(32.0), 0.0); 38 } 39 40 #[test] 41 fn classifies_cold_and_mild() { 42 assert_eq!(classify(5.0), "cold"); 43 assert_eq!(classify(20.0), "mild"); 44 } 45 } ``` Run the coverage report with one command: ```bash 1 cargo llvm-cov ``` Real output (trimmed to the table; the test run is printed first, then the summary): ```text 1 running 3 tests 2 test tests::boiling_point_converts ... ok 3 test tests::freezing_point_converts_back ... ok 4 test tests::classifies_cold_and_mild ... ok 5 6 test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s 7 8 Filename Regions Missed Regions Cover Functions Missed Functions Executed Lines Missed Lines Cover Branches Missed Branches Cover 9 ------------------------------------------------------------------------------------------------------------------------------------------------------------ 10 src/lib.rs 29 2 93.10% 6 0 100.00% 25 2 92.00% 0 0 - 11 ------------------------------------------------------------------------------------------------------------------------------------------------------------ 12 TOTAL 29 2 93.10% 6 0 100.00% 25 2 92.00% 0 0 - ``` > **Note:** The real column header is wider than shown; it has been compressed here to fit the page. The numbers are exact output from `cargo llvm-cov`. The report shows **92.00% line coverage** with two missed lines: exactly the `"freezing"` and `"hot"` branches the tests never reach, mirroring the Vitest example. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What `cargo llvm-cov` actually does [Section titled “What cargo llvm-cov actually does”](#what-cargo-llvm-cov-actually-does) Under the hood, `cargo llvm-cov`: 1. Recompiles your crate and tests with `-C instrument-coverage`, the same source-based coverage that Clang uses for C and C++. This inserts counters into the generated machine code. 2. Runs the test binaries, which write raw `.profraw` counter files to disk. 3. Merges those into a `.profdata` file with `llvm-profdata`. 4. Renders a report with `llvm-cov` (the table you saw, or HTML/LCOV/JSON). You do not run any of those steps by hand; the subcommand orchestrates them. This is **source-based** coverage: it knows about every region, function, line, and branch the compiler emitted, so the counts are precise. That is closer to Vitest’s `istanbul` provider than to the sampling-flavored `v8` provider. ### Reading the columns [Section titled “Reading the columns”](#reading-the-columns) The table has several coverage dimensions, each more granular than the last: * **Functions** — did every function get called at least once? Here all 6 functions ran (the three test functions plus the three public functions they call), so 100%. * **Lines** — what fraction of source lines executed. 92% here: 23 of 25 ran. * **Regions** — LLVM “regions” are sub-line spans (the two arms of an `if`, for example). This is the most precise metric and the one to watch. 93.10% here. * **Branches** — true/false outcomes of conditions. It shows `-` because branch coverage is off by default; enable it with `--branch`. > **Tip:** Prefer **region** coverage over line coverage as your headline number. A single line like `if a { x } else { y }` is “covered” the moment it executes once, even if `else` never ran, but region coverage will mark the untaken arm as missed. ### Finding the untested lines [Section titled “Finding the untested lines”](#finding-the-untested-lines) The table tells you *how much* is uncovered; `--show-missing-lines` tells you *where*: ```bash 1 cargo llvm-cov --show-missing-lines ``` Real output appends this after the table: ```text 1 Uncovered Lines: 2 src/lib.rs: 16, 22 ``` Lines 16 and 22 are the `"freezing"` and `"hot"` string literals: the two branches no test exercised. That is the actionable signal: write a test that passes `-5.0` and `35.0` to `classify`. ### Generating an HTML report [Section titled “Generating an HTML report”](#generating-an-html-report) For a clickable, line-by-line view like Vitest’s HTML reporter: ```bash 1 cargo llvm-cov --html # writes target/llvm-cov/html/index.html 2 cargo llvm-cov --open # same, and opens it in your browser ``` Real tail of the `--html` run: ```text 1 test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s 2 3 4 Finished report saved to /.../target/llvm-cov/html ``` ### Generating machine-readable reports for CI [Section titled “Generating machine-readable reports for CI”](#generating-machine-readable-reports-for-ci) For uploading to Codecov, Coveralls, or an editor gutter plugin, emit LCOV, the same format Vitest’s `lcov` reporter produces: ```bash 1 cargo llvm-cov --lcov --output-path lcov.info ``` The first lines of the resulting `lcov.info` are standard LCOV records: ```text 1 SF:/.../src/lib.rs 2 FN:4,_RNvCs..._21celsius_to_fahrenheit 3 FN:9,_RNvCs..._21fahrenheit_to_celsius 4 FN:14,_RNvCs..._8classify 5 ... 6 FNF:6 7 FNH:6 ``` `cargo-llvm-cov` can also emit `--cobertura`, `--json`, and `--codecov` formats. Because the output is plain LCOV, the same Codecov GitHub Action you might already use for a TypeScript repo works unchanged. ### `cargo-nextest`: the faster runner [Section titled “cargo-nextest: the faster runner”](#cargo-nextest-the-faster-runner) `cargo test` runs all tests in one binary, on a thread pool, sharing one process. `cargo-nextest` instead runs **each test in its own process**, which gives it cleaner isolation, a tidy live progress UI, and — on large suites — a real speed win. Install it once: ```bash 1 cargo install cargo-nextest --locked ``` Then run your suite: ```bash 1 cargo nextest run ``` Real output: ```text 1 ──────────── 2 Nextest run ID 79bddfe4-64ef-428c-a75a-96856227ac64 with nextest profile: default 3 Starting 3 tests across 1 binary 4 PASS [ 0.024s] (1/3) temperature_lib tests::classifies_cold_and_mild 5 PASS [ 0.026s] (2/3) temperature_lib tests::boiling_point_converts 6 PASS [ 0.030s] (3/3) temperature_lib tests::freezing_point_converts_back 7 ──────────── 8 Summary [ 0.031s] 3 tests run: 3 passed, 0 skipped ``` Each test reports its own wall-clock time, and the per-test process model means one test that segfaults or calls `std::process::abort()` cannot take the others down with it; `cargo test` would lose the whole binary. ### Coverage *under* nextest [Section titled “Coverage under nextest”](#coverage-under-nextest) The two tools compose. To collect coverage while running under nextest’s runner: ```bash 1 cargo llvm-cov nextest ``` Real output (nextest run, then the same coverage table): ```text 1 ──────────── 2 Nextest run ID 87e23b61-a061-4b3f-88e4-4082637a21cb with nextest profile: default 3 Starting 3 tests across 1 binary 4 PASS [ 0.010s] (1/3) temperature_lib tests::boiling_point_converts 5 PASS [ 0.010s] (2/3) temperature_lib tests::freezing_point_converts_back 6 PASS [ 0.012s] (3/3) temperature_lib tests::classifies_cold_and_mild 7 ──────────── 8 Summary [ 0.012s] 3 tests run: 3 passed, 0 skipped 9 Filename Regions Missed Regions Cover ... Lines Missed Lines Cover ... 10 src/lib.rs 29 2 93.10% ... 25 2 92.00% ... 11 TOTAL 29 2 93.10% ... 25 2 92.00% ... ``` > **Warning:** Nextest does **not** run doc tests; it only sees `#[test]` functions in unit and integration binaries. `cargo test` runs doc tests too. If you rely on [doc tests](/13-testing/09-doc-tests/) for coverage or correctness, run them separately with `cargo test --doc` (or `cargo llvm-cov --doctests`, which is a nightly-only feature at the time of writing). This is the single most common surprise when switching runners. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | Jest / Vitest | Rust | | -------------------- | --------------------------------------- | -------------------------------------------------------------------------- | | Coverage entry point | `--coverage` flag on the runner | separate `cargo llvm-cov` subcommand | | Engine | V8 counters or Istanbul instrumentation | LLVM source-based instrumentation | | Configuration | `coverage` block in config file | command-line flags (or `[env]`/CI scripts) | | Reporters | `text`, `html`, `lcov`, … | `--summary-only`, `--html`, `--lcov`, `--cobertura`, `--json`, `--codecov` | | Faster runner | parallel workers (built in) | `cargo-nextest` (separate install) | | Test isolation | one process, many workers | nextest: **one process per test** | | Doc tests | n/a (no such concept) | run by `cargo test`, **skipped by nextest** | | CI gate | `coverage.thresholds` in config | `--fail-under-lines`, `--fail-under-regions`, … | Two differences deserve emphasis. **Coverage is a separate tool, not a runner flag.** There is no `cargo test --coverage`. This feels like a missing battery at first, but it keeps the core toolchain small and lets the coverage tooling evolve independently. The install is a one-liner and only needed once per machine. **Source-based, not sampled.** `cargo-llvm-cov` instruments the actual compiled code, so its region counts are exact: there is no statistical estimation as with V8’s sampling mode. The trade-off is that a coverage build recompiles your crate with instrumentation, so it is slower than a plain `cargo test` and uses a separate `target/llvm-cov-target` directory (your normal `cargo build` cache is untouched). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Expecting `cargo test --coverage` to exist [Section titled “Pitfall 1: Expecting cargo test --coverage to exist”](#pitfall-1-expecting-cargo-test---coverage-to-exist) Coming from `jest --coverage`, the instinct is to pass a flag: ```bash 1 cargo test --coverage ``` Real error: ```text 1 error: unexpected argument '--coverage' found 2 3 tip: to pass '--coverage' as a value, use '-- --coverage' 4 5 Usage: cargo test [OPTIONS] [TESTNAME] [-- [ARGS]...] ``` There is no such flag. Coverage lives in the `cargo llvm-cov` subcommand you install separately. ### Pitfall 2: Forgetting the LLVM tools component [Section titled “Pitfall 2: Forgetting the LLVM tools component”](#pitfall-2-forgetting-the-llvm-tools-component) On a non-`rustup` toolchain (or a stripped CI image), `cargo llvm-cov` fails because `llvm-profdata`/`llvm-cov` are missing. The fix is a one-time component install: ```bash 1 rustup component add llvm-tools-preview ``` With `rustup`, `cargo install cargo-llvm-cov` typically pulls this in for you, so you only hit this on minimal CI images. Add the line to your CI setup step to be safe. ### Pitfall 3: Comparing coverage-build timings to normal builds [Section titled “Pitfall 3: Comparing coverage-build timings to normal builds”](#pitfall-3-comparing-coverage-build-timings-to-normal-builds) A coverage run recompiles everything with instrumentation into `target/llvm-cov-target`, so the *first* `cargo llvm-cov` after a normal `cargo build` looks alarmingly slow. It is not your tests getting slower; it is a separate, instrumented build. Subsequent coverage runs reuse that cache. Keep coverage as its own CI job rather than gating every `cargo test`. ### Pitfall 4: Assuming nextest runs your doc tests [Section titled “Pitfall 4: Assuming nextest runs your doc tests”](#pitfall-4-assuming-nextest-runs-your-doc-tests) If your suite relies on doc tests and you switch CI from `cargo test` to `cargo nextest run`, those tests silently stop running; nextest reports green while skipping them entirely. Run doc tests explicitly: ```bash 1 cargo nextest run # unit + integration tests 2 cargo test --doc # doc tests, which nextest does not execute ``` ### Pitfall 5: Nextest filter syntax is not identical to `cargo test` [Section titled “Pitfall 5: Nextest filter syntax is not identical to cargo test”](#pitfall-5-nextest-filter-syntax-is-not-identical-to-cargo-test) A positional substring works like `cargo test`: ```bash 1 cargo nextest run classifies # runs every test whose name contains "classifies" ``` Real output: ```text 1 ──────────── 2 Nextest run ID 964d01ee-2b3c-4d94-af2e-fd02f4a6b8b4 with nextest profile: default 3 Starting 2 tests across 1 binary (2 tests skipped) 4 PASS [ 0.009s] (1/2) temperature_lib edge_tests::classifies_freezing_and_hot 5 PASS [ 0.009s] (2/2) temperature_lib tests::classifies_cold_and_mild 6 ──────────── 7 Summary [ 0.014s] 2 tests run: 2 passed, 2 skipped ``` For anything more precise, nextest has its own **filterset** DSL behind `-E`, which is far more expressive than `cargo test`’s substring match; for example `-E 'test(/classif/)'` runs tests matching a regex: ```text 1 Starting 2 tests across 1 binary (2 tests skipped) 2 PASS [ 0.010s] (1/2) temperature_lib tests::classifies_cold_and_mild 3 PASS [ 0.010s] (2/2) temperature_lib edge_tests::classifies_freezing_and_hot 4 Summary [ 0.012s] 2 tests run: 2 passed, 2 skipped ``` Do not assume every `cargo test -- <flag>` argument has the same meaning under nextest; consult `cargo nextest run --help`. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Treat coverage as a flashlight, not a finish line [Section titled “Treat coverage as a flashlight, not a finish line”](#treat-coverage-as-a-flashlight-not-a-finish-line) A high coverage number means “these lines executed,” not “these lines are correct.” It is excellent at surfacing *untested* code (an `else` branch nobody hit, an error path nobody triggered) and useless as a measure of test quality. Use it to ask “why did no test reach this branch?”, and consider [property testing](/13-testing/07-property-testing/) for branches that are hard to cover with hand-written examples. ### Pick region coverage as your CI gate [Section titled “Pick region coverage as your CI gate”](#pick-region-coverage-as-your-ci-gate) When you want CI to fail on a coverage regression, gate on region (or line) coverage with `--fail-under-*`: ```bash 1 cargo llvm-cov --summary-only --fail-under-lines 90 ``` That run exits `0` because the suite is at 92% lines. Tighten the bar to a level the suite does not meet: ```bash 1 cargo llvm-cov --summary-only --fail-under-lines 95 ``` The table prints, then the command exits with status `1`, failing the CI step: ```text 1 src/lib.rs 29 2 93.10% ... 25 2 92.00% ... 2 TOTAL 29 2 93.10% ... 25 2 92.00% ... ``` ```bash 1 echo $? # => 1 ``` Set the threshold a little *below* current coverage so it catches regressions without blocking unrelated PRs over rounding noise. ### Exclude generated or untestable code [Section titled “Exclude generated or untestable code”](#exclude-generated-or-untestable-code) Mark code you intentionally do not test (generated bindings, `unreachable!()` arms, debug-only helpers) so it does not drag your number down. The standard attribute is recognized by `cargo-llvm-cov`: ```rust 1 #[coverage(off)] 2 fn debug_dump() { 3 println!("internal state"); 4 } ``` > **Note:** `#[coverage(off)]` is itself stabilizing; on stable today the portable approach is the `// cov-ignore`-style comments or per-file `--ignore-filename-regex` flag. Check `cargo llvm-cov --help` for the exact mechanism on your toolchain. You can also drop whole paths with a regex: ```bash 1 cargo llvm-cov --ignore-filename-regex '(tests|benches)/' ``` ### Use nextest locally and in CI for large suites [Section titled “Use nextest locally and in CI for large suites”](#use-nextest-locally-and-in-ci-for-large-suites) For a tiny crate the runners are equally fast, but as a workspace grows, nextest’s parallel process model and its ability to **retry flaky tests** (`--retries N`) and **partition** tests across CI machines (`--partition count:1/3`) pay off. A common setup: `cargo nextest run` for the fast feedback loop and `cargo test --doc` alongside it for the doc tests nextest skips. ### Generate LCOV in CI and let a service track trends [Section titled “Generate LCOV in CI and let a service track trends”](#generate-lcov-in-ci-and-let-a-service-track-trends) Emit `lcov.info` and upload it to Codecov/Coveralls so coverage trends are tracked over time and shown on PRs, the same workflow you would use for a TypeScript repo: ```bash 1 cargo llvm-cov --lcov --output-path lcov.info 2 # then upload lcov.info with the Codecov action, exactly as in a JS repo ``` *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production CI pipeline typically: runs tests fast (nextest), separately collects coverage, gates on a threshold, and uploads an LCOV report. Here is the library extended with full coverage so the suite reaches 100%, plus the commands a GitHub Actions job would run. src/lib.rs ```rust 1 //! Temperature conversion and classification. 2 3 /// Converts Celsius to Fahrenheit. 4 pub fn celsius_to_fahrenheit(c: f64) -> f64 { 5 c * 9.0 / 5.0 + 32.0 6 } 7 8 /// Converts Fahrenheit to Celsius. 9 pub fn fahrenheit_to_celsius(f: f64) -> f64 { 10 (f - 32.0) * 5.0 / 9.0 11 } 12 13 /// Classifies a Celsius temperature into a human-readable band. 14 pub fn classify(c: f64) -> &'static str { 15 if c < 0.0 { 16 "freezing" 17 } else if c < 15.0 { 18 "cold" 19 } else if c < 30.0 { 20 "mild" 21 } else { 22 "hot" 23 } 24 } 25 26 #[cfg(test)] 27 mod tests { 28 use super::*; 29 30 #[test] 31 fn boiling_point_converts() { 32 assert_eq!(celsius_to_fahrenheit(100.0), 212.0); 33 } 34 35 #[test] 36 fn freezing_point_converts_back() { 37 assert_eq!(fahrenheit_to_celsius(32.0), 0.0); 38 } 39 40 #[test] 41 fn classifies_cold_and_mild() { 42 assert_eq!(classify(5.0), "cold"); 43 assert_eq!(classify(20.0), "mild"); 44 } 45 46 // The branches the coverage report flagged as missed: -5.0 and 35.0. 47 #[test] 48 fn classifies_freezing_and_hot() { 49 assert_eq!(classify(-5.0), "freezing"); 50 assert_eq!(classify(35.0), "hot"); 51 } 52 } ``` With the two edge-case branches now exercised, `cargo llvm-cov --summary-only` reports a clean sheet: ```text 1 Filename Regions Missed Regions Cover Functions Missed Functions Executed Lines Missed Lines Cover ... 2 ----------------------------------------------------------------------------------------------------------------------------------- 3 src/lib.rs 35 0 100.00% 7 0 100.00% 29 0 100.00% ... 4 ----------------------------------------------------------------------------------------------------------------------------------- 5 TOTAL 35 0 100.00% 7 0 100.00% 29 0 100.00% ... ``` Region, function, and line coverage are all 100%. A matching CI workflow: .github/workflows/ci.yml ```yaml 1 name: CI 2 on: [push, pull_request] 3 4 jobs: 5 test: 6 runs-on: ubuntu-latest 7 steps: 8 - uses: actions/checkout@v4 9 - uses: dtolnay/rust-toolchain@stable 10 with: 11 components: llvm-tools-preview 12 13 # Fast test feedback (skips doc tests; run them separately below). 14 - uses: taiki-e/install-action@cargo-nextest 15 - run: cargo nextest run 16 - run: cargo test --doc 17 18 # Coverage, gated, then uploaded. 19 - uses: taiki-e/install-action@cargo-llvm-cov 20 - run: cargo llvm-cov --lcov --output-path lcov.info --fail-under-lines 90 21 - uses: codecov/codecov-action@v5 22 with: 23 files: lcov.info ``` This pipeline gives the same guarantees a `vitest run --coverage` + Codecov setup would in a TypeScript project: fast tests, a coverage gate that fails the build on a regression, and a trend-tracking report on every PR. ### What a failing run looks like [Section titled “What a failing run looks like”](#what-a-failing-run-looks-like) Nextest’s failure reporting is more structured than `cargo test`’s. If `classifies_cold_and_mild` were broken so that `classify(5.0)` was expected to be `"warm"`, `cargo nextest run` prints: ```text 1 ──────────── 2 Nextest run ID 3c8b89eb-c99b-43af-a462-5353a50fa212 with nextest profile: default 3 Starting 1 test across 1 binary (3 tests skipped) 4 FAIL [ 0.010s] (1/1) temperature_lib tests::classifies_cold_and_mild 5 stdout ─── 6 7 running 1 test 8 test tests::classifies_cold_and_mild ... FAILED 9 10 failures: 11 tests::classifies_cold_and_mild 12 13 test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 3 filtered out; finished in 0.00s 14 15 stderr ─── 16 17 thread 'tests::classifies_cold_and_mild' panicked at src/lib.rs:42:9: 18 assertion `left == right` failed 19 left: "cold" 20 right: "warm" 21 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace 22 23 Cancelling due to test failure: 24 ──────────── 25 Summary [ 0.011s] 1 test run: 0 passed, 1 failed, 3 skipped 26 FAIL [ 0.010s] (1/1) temperature_lib tests::classifies_cold_and_mild 27 error: test run failed ``` Nextest groups each failure’s captured stdout and stderr under clear headers and repeats the failing test name in the summary, and the process exits non-zero, so CI catches it. The `left`/`right` labels come from `assert_eq!` (see [Assertions](/13-testing/02-assertions/)). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`cargo-llvm-cov` README](https://github.com/taiki-e/cargo-llvm-cov): full flag reference and CI recipes. * [`cargo-nextest` book](https://nexte.st/): the runner’s docs, including the filterset DSL and CI partitioning. * [Rustc Book — Instrumentation-based Code Coverage](https://doc.rust-lang.org/rustc/instrument-coverage.html): the compiler feature underneath. * [The Rust Book — Writing Automated Tests](https://doc.rust-lang.org/book/ch11-00-testing.html): the testing chapter that frames all of this. * Sibling topics in this section: * [Unit Tests](/13-testing/00-unit-tests/): `#[test]` and `#[cfg(test)] mod tests`, the input to any coverage run. * [Integration Tests](/13-testing/04-integration-tests/): the `tests/` directory; coverage spans these too. * [Doc Tests](/13-testing/09-doc-tests/) — run by `cargo test` but **skipped by nextest**. * [Assertions](/13-testing/02-assertions/) — where the `left`/`right` failure output comes from. * [Property Testing](/13-testing/07-property-testing/) — a way to cover branches example tests miss. * [Benchmarking](/13-testing/08-benchmarking/), [Mocking](/13-testing/06-mocking/), [Test Fixtures](/13-testing/05-test-fixtures/), [Test Organization](/13-testing/01-test-organization/), [`#[should_panic]` and `Result` tests](/13-testing/03-should-panic/), [TDD Workflow](/13-testing/11-tdd-workflow/). * Foundations used above: * [Cargo Basics](/01-getting-started/03-cargo-basics/) — `cargo install` and subcommands. * [Installation](/01-getting-started/01-installation/) — `rustup` and toolchain components. * [Modules and Packages](/12-modules-packages/) — how `#[cfg(test)]` modules fit into a crate. * [Macros](/14-macros/) — `#[test]` and `assert_eq!` are macros/attributes; this explains the machinery. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Install the tools and read your first report [Section titled “Exercise 1: Install the tools and read your first report”](#exercise-1-install-the-tools-and-read-your-first-report) **Difficulty:** Easy **Objective:** Get a coverage number on a real crate. **Instructions:** Create a new library with `cargo new --lib temps`, paste the `temperature` module and its first three tests from the “Rust Equivalent” section above (the version *without* `classifies_freezing_and_hot`). Install `cargo-llvm-cov` if you have not, run `cargo llvm-cov`, and read off the line-coverage percentage. Then run `cargo llvm-cov --show-missing-lines` and identify which two source lines are uncovered. Solution ```bash 1 cargo install cargo-llvm-cov # one-time 2 cargo new --lib temps 3 # paste the module + the three-test `mod tests` into src/lib.rs 4 cargo llvm-cov 5 cargo llvm-cov --show-missing-lines ``` `cargo llvm-cov` reports **92.00%** line coverage. `--show-missing-lines` ends with: ```text 1 Uncovered Lines: 2 src/lib.rs: 16, 22 ``` Those are the `"freezing"` (line 16) and `"hot"` (line 22) arms of `classify`: the two branches no test reaches. ### Exercise 2: Close the gap and gate CI [Section titled “Exercise 2: Close the gap and gate CI”](#exercise-2-close-the-gap-and-gate-ci) **Difficulty:** Medium **Objective:** Reach 100% region coverage and add a threshold that would fail CI on a regression. **Instructions:** Add a test that exercises the two missing branches of `classify` (pass `-5.0` and `35.0`). Confirm `cargo llvm-cov` now reports 100%. Then run `cargo llvm-cov --summary-only --fail-under-lines 90` and check the exit code with `echo $?`. Finally, raise the bar to `--fail-under-lines 101` and confirm the command now exits non-zero. Solution ```rust 1 // add inside `mod tests` 2 #[test] 3 fn classifies_freezing_and_hot() { 4 assert_eq!(classify(-5.0), "freezing"); 5 assert_eq!(classify(35.0), "hot"); 6 } ``` ```bash 1 cargo llvm-cov --summary-only 2 # TOTAL ... 100.00% ... 100.00% ... 3 4 cargo llvm-cov --summary-only --fail-under-lines 90 5 echo $? # => 0 (100% >= 90%) 6 7 cargo llvm-cov --summary-only --fail-under-lines 101 8 echo $? # => 1 (no suite can reach 101%, so the gate fails) ``` The threshold flag makes coverage a hard CI gate: pick a number just under your current coverage so genuine regressions fail the build. ### Exercise 3: Switch the runner to nextest and keep doc tests [Section titled “Exercise 3: Switch the runner to nextest and keep doc tests”](#exercise-3-switch-the-runner-to-nextest-and-keep-doc-tests) **Difficulty:** Medium **Objective:** Replace `cargo test` with `cargo nextest run` without silently dropping doc tests. **Instructions:** Add a documentation example to `celsius_to_fahrenheit` (a ` ```rust ` block in its `///` doc comment that asserts `celsius_to_fahrenheit(0.0) == 32.0`). Install `cargo-nextest`. Run `cargo nextest run` and observe that the doc test does **not** appear in the output. Then run the doc tests explicitly and confirm the example passes. Explain in one sentence why a CI job needs both commands. Solution ````rust 1 /// Converts Celsius to Fahrenheit. 2 /// 3 /// ``` 4 /// use temps::celsius_to_fahrenheit; 5 /// assert_eq!(celsius_to_fahrenheit(0.0), 32.0); 6 /// ``` 7 pub fn celsius_to_fahrenheit(c: f64) -> f64 { 8 c * 9.0 / 5.0 + 32.0 9 } ```` ```bash 1 cargo install cargo-nextest --locked # one-time 2 3 cargo nextest run # runs unit/integration tests only — no doc test listed 4 cargo test --doc # runs the doc test ``` `cargo test --doc` runs the example as a test, naming it after the file and the line the code block starts on (the exact line number depends on your layout): ```text 1 running 1 test 2 test src/lib.rs - celsius_to_fahrenheit (line N) ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` A CI job needs both because **nextest does not execute doc tests**: running only `cargo nextest run` would leave that documented example unverified, so a separate `cargo test --doc` step keeps the docs honest. See [Doc Tests](/13-testing/09-doc-tests/). # TDD Workflow in Rust > Run red-green-refactor in Rust, where your first failure is often a compile error. Stub with todo!(), read assert_eq! diffs, and add cargo watch or bacon. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Test-driven development (TDD) is the **red → green → refactor** loop: write a failing test, write the minimum code to pass it, then clean up with the test as a safety net. The mechanics you know from Jest or Vitest carry straight over, but Rust adds one twist worth internalizing up front. Because Rust is compiled and statically typed, your *first* “red” is often a **compile error**, not a failing assertion. This file shows how to run that loop comfortably in Rust, including how to get Vitest-style instant re-runs on save. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) A typical TDD session with Vitest. You start the runner in watch mode, and it re-runs the relevant tests every time you save. slugify.test.ts ```typescript 1 import { describe, it, expect } from "vitest"; 2 import { slugify } from "./slugify"; 3 4 describe("slugify", () => { 5 it("lowercases and hyphenates", () => { 6 expect(slugify("Hello World")).toBe("hello-world"); 7 }); 8 }); ``` ```typescript 1 // slugify.ts — the very first stub, written to make the test *compile* but fail 2 export function slugify(title: string): string { 3 return ""; 4 } ``` You launch the watcher once and leave it running: ```bash 1 npx vitest # watch mode by default in a TTY; `vitest run` is single-shot ``` The watcher reports a failure, you flesh out `slugify`, save, and within milliseconds it flips to green. The feedback loop is the product: you almost never type `npx vitest` a second time. A few things a JavaScript developer relies on here: * A **watch mode** built into the runner (`vitest`, `jest --watch`). * Tests and code in **separate files** that the runner re-runs on change. * A failing test means an `expect` **threw**; there is no compile step that could fail first. Rust keeps the first two ideas (with different tools) and changes the third. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same `slugify`, grown test-first. The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically, so nothing below pins an edition. We will walk the loop in stages. **Stage 0** is the failing-on-purpose starting point: a stub that compiles but does not work yet, using the `todo!()` macro: src/lib.rs ```rust 1 /// Turns a human title into a URL slug. 2 pub fn slugify(title: &str) -> String { 3 todo!("not implemented yet") 4 } 5 6 #[cfg(test)] 7 mod tests { 8 use super::*; 9 10 #[test] 11 fn lowercases_and_hyphenates() { 12 assert_eq!(slugify("Hello World"), "hello-world"); 13 } 14 } ``` `cargo test` gives us our **red**, a real, run-it-yourself failure: ```text 1 running 1 test 2 test tests::lowercases_and_hyphenates ... FAILED 3 4 failures: 5 6 ---- tests::lowercases_and_hyphenates stdout ---- 7 8 thread 'tests::lowercases_and_hyphenates' panicked at src/lib.rs:3:5: 9 not yet implemented: not implemented yet 10 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace 11 12 13 failures: 14 tests::lowercases_and_hyphenates 15 16 test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s ``` > **Tip:** `todo!()` (and its sibling `unimplemented!()`) are the idiomatic way to stub a function during TDD. They type-check as *any* return type — so `fn slugify(..) -> String { todo!() }` compiles — but **panic** when reached, which is exactly what makes the test fail. This is much cleaner than returning a dummy `String::new()` that might accidentally pass a weak test. **Stage 1 — green.** Write the least code that satisfies the one test: src/lib.rs ```rust 1 /// Turns a human title into a URL slug. 2 pub fn slugify(title: &str) -> String { 3 title.to_lowercase().replace(' ', "-") 4 } 5 6 #[cfg(test)] 7 mod tests { 8 use super::*; 9 10 #[test] 11 fn lowercases_and_hyphenates() { 12 assert_eq!(slugify("Hello World"), "hello-world"); 13 } 14 } ``` ```text 1 running 1 test 2 test tests::lowercases_and_hyphenates ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` **Stage 2: drive out a bug with a new red.** Add a test for messy whitespace. The naive `replace(' ', "-")` mishandles runs of spaces: ```rust 1 #[test] 2 fn collapses_runs_of_whitespace() { 3 assert_eq!(slugify(" Rust is Great "), "rust-is-great"); 4 } ``` `assert_eq!` prints a precise diff of what diverged: ```text 1 running 2 tests 2 test tests::lowercases_and_hyphenates ... ok 3 test tests::collapses_runs_of_whitespace ... FAILED 4 5 failures: 6 7 ---- tests::collapses_runs_of_whitespace stdout ---- 8 9 thread 'tests::collapses_runs_of_whitespace' panicked at src/lib.rs:17:9: 10 assertion `left == right` failed 11 left: "--rust---is---great--" 12 right: "rust-is-great" 13 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace 14 15 16 failures: 17 tests::collapses_runs_of_whitespace 18 19 test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` **Stage 2 — green.** Switch to `split_whitespace`, which collapses any run of whitespace and trims the ends: ```rust 1 /// Turns a human title into a URL slug. 2 pub fn slugify(title: &str) -> String { 3 title 4 .to_lowercase() 5 .split_whitespace() 6 .collect::<Vec<_>>() 7 .join("-") 8 } ``` ```text 1 running 2 tests 2 test tests::collapses_runs_of_whitespace ... ok 3 test tests::lowercases_and_hyphenates ... ok 4 5 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` **Stage 3: refactor under green.** With two passing tests pinning the behavior, we can restructure freely: extract a private `normalize_word` helper and also strip punctuation (driven by one more test, omitted here for brevity; see the [Real-World Example](#real-world-example) for the full final file). The point of TDD is that the green bar tells you the refactor preserved behavior. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The loop, step by step [Section titled “The loop, step by step”](#the-loop-step-by-step) | Step | What you do | Rust signal you watch for | | ------------ | --------------------------------------------- | --------------------------------------------------- | | **Red** | Write a test for behavior that does not exist | a test that **panics** (or, first, a compile error) | | **Green** | Write the minimum code to pass | `test result: ok` | | **Refactor** | Improve the code, keep tests passing | the bar stays green | This is identical to the Vitest loop in spirit. The differences are all in the *signals*. ### Your first “red” is frequently a compile error [Section titled “Your first “red” is frequently a compile error”](#your-first-red-is-frequently-a-compile-error) This is the single biggest mental adjustment for a TypeScript/JavaScript developer. In Vitest, if you reference a function that does not exist, the test file simply throws a `ReferenceError` at runtime and shows up as a red test. In Rust, the test **binary will not build at all**. `cargo test` stops at the compiler: ```rust 1 #[cfg(test)] 2 mod tests { 3 #[test] 4 fn slug_works() { 5 // slugify does not exist yet 6 assert_eq!(slugify("Hello World"), "hello-world"); 7 } 8 } ``` ```text 1 error[E0425]: cannot find function `slugify` in this scope 2 --> src/lib.rs:6:20 3 | 4 6 | assert_eq!(slugify("Hello World"), "hello-world"); 5 | ^^^^^^^ not found in this scope 6 7 For more information about this error, try `rustc --explain E0425`. 8 error: could not compile `slugify_probe` (lib test) due to 1 previous error ``` That is still a perfectly good red: it tells you exactly what to build next. The disciplined Rust TDD habit is: write the test, then write a *stub* (`fn slugify(_: &str) -> String { todo!() }`) so the code **compiles** and you get a genuine *test* failure rather than a *build* failure. From there the loop feels just like Vitest. > **Note:** Because the compiler runs first, Rust gives you a second, free layer of red. A test that calls your function with the wrong argument types, or expects a `u32` where you return a `String`, fails *at compile time*. You can never ship a test that lies about your types. TypeScript’s `tsc` offers something similar, but Vitest by default transpiles each file independently and will happily run code that `tsc` would reject. ### `todo!()` vs returning a dummy value [Section titled “todo!() vs returning a dummy value”](#todo-vs-returning-a-dummy-value) `todo!()` expands to a panic, so it is never mistaken for a real implementation, and it satisfies *any* return type so the surrounding code type-checks. Compare: ```rust 1 fn slugify(title: &str) -> String { 2 String::new() // bad stub: an under-specified test ("non-empty?") could pass by accident 3 } ``` ```rust 1 fn slugify(title: &str) -> String { 2 todo!() // good stub: compiles, but every test that calls it fails loudly 3 } ``` ### Why `assert_eq!` output is your fastest debugger [Section titled “Why assert\_eq! output is your fastest debugger”](#why-assert_eq-output-is-your-fastest-debugger) When the whitespace test failed, the report showed `left: "--rust---is---great--"` next to `right: "rust-is-great"`. The `left` value is what your code produced; `right` is what you expected. Seeing the *actual* wrong output (leading hyphens, tripled hyphens) points straight at the bug: `replace` substitutes each space one-for-one instead of collapsing. This is the same information `expect(a).toBe(b)` gives you in Vitest, formatted for the terminal. Assertions and their messages are covered in depth in [Assertions](/13-testing/02-assertions/). ### Keeping the loop fast [Section titled “Keeping the loop fast”](#keeping-the-loop-fast) The reason TDD is pleasant in JavaScript is the sub-second watch loop. Rust needs a watcher too, because typing `cargo test` by hand after every edit kills the rhythm. The next two sections cover the tools. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | Vitest / Jest | Rust | | -------------------------- | ---------------------------------------- | ------------------------------------------------------------ | | First failure for new code | runtime `ReferenceError` → red test | **compile error** → fix with a `todo!()` stub | | Stub a not-yet-written fn | return `null`, throw, or leave undefined | `todo!()` / `unimplemented!()`: panics, type-checks anywhere | | Built-in watch mode | `vitest` (default), `jest --watch` | none built in; add `cargo watch` or `bacon` | | Re-run only affected tests | smart, file-graph based | `cargo test <substring>`; runners like nextest help | | Failure signal | an `expect` throws | the test function **panics** | | Type mistakes in tests | caught only if you also run `tsc` | caught by `cargo test` itself, every time | The headline: **Rust has no watch mode out of the box.** This surprises people coming from `vitest`/`jest --watch`. The compiler/borrow-checker safety net is excellent, but the instant-rerun ergonomics are something you install. Two community tools fill the gap. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Expecting a runtime failure when you actually get a compile error [Section titled “Pitfall 1: Expecting a runtime failure when you actually get a compile error”](#pitfall-1-expecting-a-runtime-failure-when-you-actually-get-a-compile-error) A TypeScript developer writes the test first, runs `cargo test`, and is briefly confused that there is no “1 failed” line, just an `error[E0425]`. That *is* the red. Do not fight it: add the stub so the code compiles, and then you will see the familiar `FAILED` test line. Treat “it does not compile” as the zeroth red of every cycle. ### Pitfall 2: A stub that accidentally passes a weak test [Section titled “Pitfall 2: A stub that accidentally passes a weak test”](#pitfall-2-a-stub-that-accidentally-passes-a-weak-test) If you stub with `String::new()` and your first test only checks `assert!(!slugify("x").is_empty())` — wait, that would fail — but a test like `assert_eq!(slugify(""), "")` would *pass* against the empty-string stub, giving a false green. `todo!()` cannot do this: it panics on every call, so a green bar always means real code ran. ### Pitfall 3: Forgetting tests run in parallel, so watch-mode reruns are non-deterministic in order [Section titled “Pitfall 3: Forgetting tests run in parallel, so watch-mode reruns are non-deterministic in order”](#pitfall-3-forgetting-tests-run-in-parallel-so-watch-mode-reruns-are-non-deterministic-in-order) `cargo test` runs test functions on multiple threads. With a watcher firing on every save, output ordering shifts run to run. That is fine for independent tests, but if a test depends on shared mutable global state it will flake intermittently under the watcher. Keep tests independent (see [Test Fixtures](/13-testing/05-test-fixtures/)), or force serial execution while debugging with `cargo test -- --test-threads=1`. ### Pitfall 4: Recompiling the whole world on every keystroke [Section titled “Pitfall 4: Recompiling the whole world on every keystroke”](#pitfall-4-recompiling-the-whole-world-on-every-keystroke) A naive watch setup that runs `cargo test` on *any* file change (including `Cargo.toml` or generated files) can trigger full rebuilds and ruin the fast loop. Scope the watcher to source files and prefer `cargo test` (debug) over `--release` during TDD; release builds optimize and are far slower to compile. Also consider narrowing to the module you are working on with a name filter: ```bash 1 cargo test slugify # runs only tests whose path contains "slugify" ``` ```text 1 running 1 test 2 test tests::strips_punctuation ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 4 filtered out; finished in 0.00s ``` The `4 filtered out` line confirms the other tests were skipped, a real speed win on a large suite. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Install a watcher for a Vitest-like loop [Section titled “Install a watcher for a Vitest-like loop”](#install-a-watcher-for-a-vitest-like-loop) Rust does not ship a watch mode, so install one. Two good choices, both fetched from crates.io: ```bash 1 cargo install cargo-watch # adds the `cargo watch` subcommand 2 # or, the more actively maintained modern option: 3 cargo install bacon ``` **`cargo-watch`** wraps any cargo command and reruns it when files under the project change. The canonical TDD invocation: ```bash 1 cargo watch -x test # rerun `cargo test` on every save 2 cargo watch -x check # even faster: just type-check, no test run 3 cargo watch -x 'test slugify' # rerun only matching tests 4 cargo watch -c -x test # `-c` clears the screen before each run ``` `-x` (“execute”) takes the cargo subcommand to run; `cargo watch -x check -x test` chains them, so you get a fast `check` first and only run tests if it compiles. **`bacon`** is a background code checker built for exactly this loop. You run it once: ```bash 1 bacon test # live test results; press `t`/`c`/`l` to switch jobs ``` and it stays open in a side terminal, recompiling and re-testing on save, showing a compact pass/fail summary and jumping you to the first error. Many Rustaceans keep `bacon` running in a split pane the way they kept `vitest` open. > **Tip:** Whichever you pick, `cargo watch -x check` (or `bacon`’s default `check` job) is the *fastest* possible inner loop: `cargo check` skips code generation and linking, so it confirms your code type-checks and borrow-checks in a fraction of the time a full `cargo test` takes. Many people TDD with `check` running continuously and run the full test suite less often. ### Lean on `cargo check` and `cargo clippy` as part of red-green [Section titled “Lean on cargo check and cargo clippy as part of red-green”](#lean-on-cargo-check-and-cargo-clippy-as-part-of-red-green) Rust’s compiler is a participant in your TDD loop, not an obstacle. A quick `cargo check` after writing a test confirms the test *compiles* (catching type-level mistakes) before you have written any implementation. After going green, a `cargo clippy` pass during the refactor step catches non-idiomatic code while the safety net is up: ```bash 1 cargo clippy --all-targets ``` ```text 1 Checking slugify_probe v0.1.0 (...) 2 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.36s ``` (No warnings means clean.) ### Refactor only when green [Section titled “Refactor only when green”](#refactor-only-when-green) The discipline that makes TDD safe: never refactor and add behavior at the same time. Go green first, *then* restructure with the passing tests guarding you. Rust’s ownership and type guarantees make many refactors mechanical, but they cannot tell you that you changed an *observable behavior*; only your tests can. ### Use a faster runner on big suites [Section titled “Use a faster runner on big suites”](#use-a-faster-runner-on-big-suites) As the suite grows, compile-and-link time dominates the loop. `cargo nextest` runs the test binaries with a faster, more parallel harness and clearer output; pairing it with a watcher (`cargo watch -x 'nextest run'`) keeps the loop snappy. See [Coverage](/13-testing/10-coverage/) for installing and using nextest. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) Here is the full, compile-verified end state of the `slugify` TDD session: a public function, a private `normalize_word` helper extracted during the refactor step, a doc test (which also runs under `cargo test`; see [Doc Tests](/13-testing/09-doc-tests/)), and the unit-test module that grew one test at a time. src/lib.rs ````rust 1 //! A tiny URL-slug builder, grown test-first. 2 3 /// Turns a human title into a URL slug: 4 /// lowercased, ASCII-alphanumeric words joined by single hyphens. 5 /// 6 /// ``` 7 /// assert_eq!(slugify_probe::slugify("Rust: A Language!"), "rust-a-language"); 8 /// ``` 9 pub fn slugify(title: &str) -> String { 10 title 11 .split_whitespace() 12 .map(normalize_word) 13 .filter(|word| !word.is_empty()) 14 .collect::<Vec<_>>() 15 .join("-") 16 } 17 18 /// Lowercases a single word and drops everything that is not 19 /// an ASCII letter or digit. 20 fn normalize_word(word: &str) -> String { 21 word.chars() 22 .filter(|c| c.is_ascii_alphanumeric()) 23 .map(|c| c.to_ascii_lowercase()) 24 .collect() 25 } 26 27 #[cfg(test)] 28 mod tests { 29 use super::*; 30 31 #[test] 32 fn lowercases_and_hyphenates() { 33 assert_eq!(slugify("Hello World"), "hello-world"); 34 } 35 36 #[test] 37 fn collapses_runs_of_whitespace() { 38 assert_eq!(slugify(" Rust is Great "), "rust-is-great"); 39 } 40 41 #[test] 42 fn strips_punctuation() { 43 assert_eq!(slugify("Rust: A Language!"), "rust-a-language"); 44 } 45 46 #[test] 47 fn empty_input_is_empty_slug() { 48 assert_eq!(slugify(""), ""); 49 } 50 51 #[test] 52 fn normalize_word_is_testable_directly() { 53 // Private helper, reachable from the in-file test module. 54 assert_eq!(normalize_word("C++!?"), "c"); 55 } 56 } ```` A full `cargo test` run exercises both the unit tests and the doc test: ```text 1 running 5 tests 2 test tests::collapses_runs_of_whitespace ... ok 3 test tests::empty_input_is_empty_slug ... ok 4 test tests::lowercases_and_hyphenates ... ok 5 test tests::normalize_word_is_testable_directly ... ok 6 test tests::strips_punctuation ... ok 7 8 test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s ``` ```text 1 Doc-tests slugify_probe 2 3 running 1 test 4 test src/lib.rs - slugify (line 6) ... ok 5 6 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s ``` The whole session — five tests and a doc test — was built by repeating red → green → refactor. In practice you would have had `cargo watch -x test` (or `bacon`) open the entire time, watching each save flip the bar. The refactor that introduced `normalize_word` (which both strips punctuation *and* let us delete the separate `to_lowercase()` call) was done with the bar green; the moment any test had gone red, the watcher would have told you instantly. > **Note:** Notice the private `normalize_word` is tested directly from the in-file `#[cfg(test)] mod tests`. TDD on internal helpers is one of the places Rust shines compared to black-box Vitest suites: you can test-drive a private function into existence without exporting it. Where to put these tests, and the trade-off versus black-box [Integration Tests](/13-testing/04-integration-tests/), is the subject of [Test Organization](/13-testing/01-test-organization/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [The Rust Book — Writing Automated Tests](https://doc.rust-lang.org/book/ch11-00-testing.html) * [The Rust Book — Test-Driven Development of a Library’s Functionality](https://doc.rust-lang.org/book/ch12-04-testing-the-librarys-functionality.html): a worked TDD example in the `minigrep` project * [`cargo-watch` on crates.io](https://crates.io/crates/cargo-watch) * [`bacon` — background rust code checker](https://dystroy.org/bacon/) * [`todo!` macro documentation](https://doc.rust-lang.org/std/macro.todo.html) and [`unimplemented!`](https://doc.rust-lang.org/std/macro.unimplemented.html) * Sibling topics in this section: * [Unit Tests](/13-testing/00-unit-tests/): `#[test]`, `#[cfg(test)] mod tests`, and `cargo test`. * [Assertions](/13-testing/02-assertions/): reading `assert_eq!` failure output, your fastest debugger in the loop. * [`#[should_panic]` and `Result` tests](/13-testing/03-should-panic/) — driving out error paths test-first. * [Test Organization](/13-testing/01-test-organization/): where the tests you write in the loop should live. * [Test Fixtures](/13-testing/05-test-fixtures/) — keeping tests independent so watch-mode reruns stay deterministic. * [Integration Tests](/13-testing/04-integration-tests/), [Mocking](/13-testing/06-mocking/), [Property Testing](/13-testing/07-property-testing/), [Doc Tests](/13-testing/09-doc-tests/), [Coverage](/13-testing/10-coverage/) (`cargo nextest` for a faster loop). * Foundations used above: * [Cargo Basics](/01-getting-started/03-cargo-basics/): `cargo` is the test runner you are looping on. * [Hello World](/01-getting-started/02-hello-world/): the `cargo new` / project layout these examples assume. * [Macros](/14-macros/) — `todo!`, `assert_eq!`, and `#[test]` are the macro/attribute machinery powering the loop. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Run a full red-green-refactor cycle [Section titled “Exercise 1: Run a full red-green-refactor cycle”](#exercise-1-run-a-full-red-green-refactor-cycle) **Difficulty:** Easy **Objective:** Internalize the loop by building one function entirely test-first. **Instructions:** Starting from an empty `lib.rs`, write a test for `is_palindrome(&str) -> bool` *before* the function exists. Get a compile error, add a `todo!()` stub to turn it into a real red, implement the simplest passing version, then add tests that drive out case-insensitivity and punctuation-stripping (so `"A man, a plan, a canal: Panama"` is a palindrome). Run `cargo test` after each step. ```rust 1 // Write the test first; add `pub fn is_palindrome(s: &str) -> bool { todo!() }` 2 // to make it compile, then implement and grow the tests. ``` Solution src/lib.rs ```rust 1 pub fn is_palindrome(s: &str) -> bool { 2 let cleaned: Vec<char> = s 3 .chars() 4 .filter(|c| c.is_alphanumeric()) 5 .map(|c| c.to_ascii_lowercase()) 6 .collect(); 7 let reversed: Vec<char> = cleaned.iter().rev().copied().collect(); 8 cleaned == reversed 9 } 10 11 #[cfg(test)] 12 mod tests { 13 use super::*; 14 15 #[test] 16 fn plain_palindrome() { 17 assert!(is_palindrome("racecar")); 18 } 19 20 #[test] 21 fn ignores_case_and_punctuation() { 22 assert!(is_palindrome("A man, a plan, a canal: Panama")); 23 } 24 25 #[test] 26 fn rejects_non_palindrome() { 27 assert!(!is_palindrome("rust")); 28 } 29 } ``` `cargo test` output: ```text 1 running 3 tests 2 test tests::ignores_case_and_punctuation ... ok 3 test tests::plain_palindrome ... ok 4 test tests::rejects_non_palindrome ... ok 5 6 test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` ### Exercise 2: TDD a small stateful type [Section titled “Exercise 2: TDD a small stateful type”](#exercise-2-tdd-a-small-stateful-type) **Difficulty:** Medium **Objective:** Drive an `Option`-returning method into existence with tests, mirroring how `??`/`?.` callers in TypeScript expect a “no data yet” case. **Instructions:** Build a `RunningAverage` struct test-first. Start with a test asserting that a brand-new average reports `None` (no data). Make it pass, then add a test that adds `2.0`, `4.0`, `6.0` and expects `Some(4.0)`. Implement `new`, `add`, and `mean` so both pass. The `mean()` method must return `Option<f64>` so the empty case is encoded in the type, not a sentinel like `NaN`. ```rust 1 #[derive(Default)] 2 pub struct RunningAverage { 3 // TODO: fields 4 } 5 6 impl RunningAverage { 7 // TODO: new, add, mean -> Option<f64> 8 } 9 10 // TODO: tests, written first ``` Solution src/lib.rs ```rust 1 #[derive(Default)] 2 pub struct RunningAverage { 3 count: u64, 4 sum: f64, 5 } 6 7 impl RunningAverage { 8 pub fn new() -> Self { 9 RunningAverage::default() 10 } 11 12 pub fn add(&mut self, value: f64) { 13 self.count += 1; 14 self.sum += value; 15 } 16 17 /// Returns `None` until at least one value has been added. 18 pub fn mean(&self) -> Option<f64> { 19 if self.count == 0 { 20 None 21 } else { 22 Some(self.sum / self.count as f64) 23 } 24 } 25 } 26 27 #[cfg(test)] 28 mod tests { 29 use super::*; 30 31 #[test] 32 fn empty_average_is_none() { 33 let avg = RunningAverage::new(); 34 assert_eq!(avg.mean(), None); 35 } 36 37 #[test] 38 fn averages_added_values() { 39 let mut avg = RunningAverage::new(); 40 avg.add(2.0); 41 avg.add(4.0); 42 avg.add(6.0); 43 assert_eq!(avg.mean(), Some(4.0)); 44 } 45 } ``` `cargo test` output: ```text 1 running 2 tests 2 test tests::averages_added_values ... ok 3 test tests::empty_average_is_none ... ok 4 5 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` ### Exercise 3: TDD a fallible parser with `Result`-returning tests [Section titled “Exercise 3: TDD a fallible parser with Result-returning tests”](#exercise-3-tdd-a-fallible-parser-with-result-returning-tests) **Difficulty:** Hard **Objective:** Combine the red-green loop with error-path testing, using tests that return `Result<(), E>` and the `?` operator (see [`#[should_panic]` and `Result` tests](/13-testing/03-should-panic/)). **Instructions:** Test-drive `parse_hex_color(&str) -> Result<Rgb, ParseError>` that parses `"#rrggbb"`. Grow it one test at a time: a valid color, a missing `#`, a wrong length, and a non-hex digit, with a distinct `ParseError` variant for each. Write the happy-path test as a function that returns `Result<(), ParseError>` and uses `?` instead of `unwrap`, so a parse failure surfaces as a test failure automatically. ```rust 1 #[derive(Debug, PartialEq)] 2 pub struct Rgb { /* r, g, b: u8 */ } 3 4 #[derive(Debug, PartialEq)] 5 pub enum ParseError { /* MissingHash, WrongLength, BadDigit */ } 6 7 pub fn parse_hex_color(input: &str) -> Result<Rgb, ParseError> { 8 todo!() 9 } 10 11 // TODO: tests, written first — one per behavior ``` Solution src/lib.rs ```rust 1 #[derive(Debug, PartialEq)] 2 pub struct Rgb { 3 pub r: u8, 4 pub g: u8, 5 pub b: u8, 6 } 7 8 #[derive(Debug, PartialEq)] 9 pub enum ParseError { 10 MissingHash, 11 WrongLength, 12 BadDigit, 13 } 14 15 /// Parses `#rrggbb` into an `Rgb`. 16 pub fn parse_hex_color(input: &str) -> Result<Rgb, ParseError> { 17 let body = input.strip_prefix('#').ok_or(ParseError::MissingHash)?; 18 if body.len() != 6 { 19 return Err(ParseError::WrongLength); 20 } 21 let component = |range| { 22 u8::from_str_radix(&body[range], 16).map_err(|_| ParseError::BadDigit) 23 }; 24 Ok(Rgb { 25 r: component(0..2)?, 26 g: component(2..4)?, 27 b: component(4..6)?, 28 }) 29 } 30 31 #[cfg(test)] 32 mod tests { 33 use super::*; 34 35 // A test that returns Result so it can use `?` instead of unwrap. 36 #[test] 37 fn parses_a_valid_color() -> Result<(), ParseError> { 38 let color = parse_hex_color("#ff8800")?; 39 assert_eq!(color, Rgb { r: 255, g: 136, b: 0 }); 40 Ok(()) 41 } 42 43 #[test] 44 fn rejects_missing_hash() { 45 assert_eq!(parse_hex_color("ff8800"), Err(ParseError::MissingHash)); 46 } 47 48 #[test] 49 fn rejects_bad_length() { 50 assert_eq!(parse_hex_color("#fff"), Err(ParseError::WrongLength)); 51 } 52 53 #[test] 54 fn rejects_non_hex_digits() { 55 assert_eq!(parse_hex_color("#gggggg"), Err(ParseError::BadDigit)); 56 } 57 } ``` `cargo test` output: ```text 1 running 4 tests 2 test tests::parses_a_valid_color ... ok 3 test tests::rejects_bad_length ... ok 4 test tests::rejects_missing_hash ... ok 5 test tests::rejects_non_hex_digits ... ok 6 7 test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` # Rust Macros > Rust macros are compile-time code generation with zero runtime cost, unlike TS decorators and Babel: macro_rules!, derive, attribute, and proc macros. In TypeScript you have no real compile-time metaprogramming: the closest things are runtime functions, decorators, and build-step AST transformers like Babel. Rust takes the opposite approach with **macros** — compile-time code generation that expands *before* type checking and leaves **no runtime cost** behind. This section covers both families: **declarative macros** (`macro_rules!`, pattern-matching over your source tokens) and **procedural macros** (the derive, attribute, and function-like flavors written with `syn` 2 + `quote`), plus the standard-library macros you will use every single day. *** ## What You’ll Learn [Section titled “What You’ll Learn”](#what-youll-learn) * Why a Rust macro is **not** a function and **not** a decorator — it operates on *tokens* at compile time, is gone by runtime, and is protected by **hygiene** so its temporaries cannot clash with yours * How to write `macro_rules!` declarative macros: matchers, transcribers, and how to inspect the generated code with `cargo expand` * The full set of **fragment specifiers** (`$x:expr`, `:ident`, `:ty`, `:pat`, `:tt`, `:literal`, `:block`, …) and how multiple rules give you overload-like dispatch on the *shape* of the input * How **repetition** (`$(...),*`, `$(...);*`, `$(...)+`, `$(...)?`) builds variadic macros, including a faithful `vec!`-style clone * What `#[derive(...)]` actually generates (`Debug`, `Clone`, `PartialEq`, `Hash`, `Default`, …) and how a custom derive looks from the user’s side * How **attribute macros** (`#[name]`) inspect and rewrite a whole item — the compile-time, type-safe counterpart to a TypeScript decorator * How **function-like procedural macros** (`foo!(...)`) run arbitrary Rust at compile time to parse a custom DSL and *validate* input into a compiler error * How to *write* procedural macros end to end: the `proc-macro` crate type, `TokenStream`, and the `syn` 2 + `quote` + `proc-macro2` toolchain, with a compile-verified custom derive * The standard-library macros — `vec!`, `println!`, `format!`, `write!`, `matches!`, the `assert*!` family, `todo!`, `dbg!`, `include_str!`, and more *** ## Topics [Section titled “Topics”](#topics) | Topic | Description | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | [Macro Basics](/14-macros/00-macro-basics/) | What macros are and are **not** (not decorators, not functions); compile-time expansion; hygiene; when to reach for a macro. | | [Declarative Macros](/14-macros/01-declarative-macros/) | `macro_rules!`: basic matchers, a simple example expanded, and inspecting output with `cargo expand`. | | [Macro Patterns](/14-macros/02-macro-patterns/) | Fragment specifiers (`$x:expr`, `:ident`, `:ty`, `:tt`, `:pat`, …) and multiple rules for shape-based dispatch. | | [Repetition](/14-macros/03-repetition/) | Repetition operators `$(...),*` / `$(...);*` / `$(...)+`, and building a `vec!`-like macro. | | [Derive Macros](/14-macros/04-derive-macros/) | `#[derive(...)]`: what the std derives generate (`Debug`/`Clone`/`PartialEq`…) plus a custom-derive overview. | | [Attribute Macros](/14-macros/05-attribute-macros/) | Custom attribute macros (`#[name]`): the concept and a minimal logging/route example. | | [Function-like Macros](/14-macros/06-function-like-macros/) | Function-like procedural macros `foo!(...)` versus declarative ones, and when to use each. | | [Procedural Macros](/14-macros/07-proc-macros/) | Writing proc macros: the `proc-macro` crate type, `TokenStream`, `syn` 2 + `quote` + `proc-macro2`, and a compile-verified custom derive. | | [Common Macros](/14-macros/08-common-macros/) | The std macros: `vec!`/`println!`/`format!`/`write!`/`matches!`/`assert*!`/`todo!`/`unimplemented!`/`dbg!`/`include_str!`. | *** ## Learning Objectives [Section titled “Learning Objectives”](#learning-objectives) By the end of this section, you will be able to: * Explain why macros are compile-time, token-based, and hygienic, and correct the common (wrong) mental model that they are decorators or functions * Write `macro_rules!` macros with the right fragment specifiers, multiple rules ordered specific-to-general, and repetition with an optional trailing comma * Read a macro’s expansion with `cargo expand` and debug why a call fails to match * Choose the correct standard derives for a type and read the compiler errors when a field doesn’t support a derived trait * Distinguish the three procedural-macro flavors (derive, attribute, function-like) by their entry-point attribute and signature, and set up a `proc-macro = true` crate * Write a custom derive with `syn` 2 + `quote`, preserve generics with `split_for_impl`, and emit located compile errors instead of panicking * Decide *declarative-first, procedural-only-when-needed*, and reach for a plain function before either when values (not syntax) are all you need * Use the standard-library macros idiomatically, including inline format captures and the `assert!`-panics-vs-`Result` distinction *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * [Section 09: Generics & Traits](/09-generics-traits/) — derive macros generate trait `impl`s, custom derives must preserve trait bounds and generics, and the orphan rule explains why you can only `#[derive(...)]` on types you own. The trait vocabulary from Section 09 makes this whole section land. * [Section 02: Basics](/02-basics/) — you have already been calling `println!` and `format!`; this section explains what those macro invocations actually are. * [Section 12: Modules & Packages](/12-modules-packages/) — `#[macro_export]`, importing macros across modules, and the separate `proc-macro` crate all build on the module and Cargo model from Section 12. *** ## Estimated Time [Section titled “Estimated Time”](#estimated-time) * **Reading:** 4-5 hours * **Hands-on Practice:** 3 hours * **Exercises:** 1-2 hours * **Total:** 8-10 hours > **Tip:** Read in listed order. The first four topics (`macro-basics`, `declarative-macros`, `macro-patterns`, `repetition`) build a complete picture of `macro_rules!` and cover the macros you will *write* most often. The middle three (`derive-macros`, `attribute-macros`, `function-like-macros`) introduce the procedural flavors conceptually; `proc-macros` then shows the full `syn` + `quote` machinery behind all three. Finish with `common-macros` for the standard-library toolbox you will *use* daily. The biggest mental shift for a TypeScript developer is that a macro is **gone by runtime** — it is a program that writes a program, not a decorator that wraps a value. *** **Next:** [Section 15: Serialization →](/15-serialization/) — `serde`’s `#[derive(Serialize, Deserialize)]` and the `serde_json::json!` DSL put the derive and declarative macros from this section to work. # Macro Basics: What Macros Are (and Are Not) > Rust macros write code at compile time before type-checking. They are not functions or TypeScript decorators: they take tokens, expand inline, and stay hygienic. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A Rust **macro** is code that writes code: at compile time, the compiler expands a macro invocation like `vec![1, 2, 3]` into ordinary Rust before type-checking begins. Macros are how Rust gets variadic, type-generic constructs like `println!`, `vec!`, and `#[derive(...)]` without runtime reflection or a garbage-collected `arguments` object. This page is about the *mental model*: what macros are, what they are emphatically **not** (they are not functions and not decorators), how compile-time expansion and **hygiene** work, and when reaching for a macro is the right call. > **Note:** The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects the newest edition automatically. Every Rust snippet here was compiled and run on stable. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript/JavaScript there is no compile-time code generation in the language itself. The two things that *feel* closest to macros are **functions** (especially variadic ones) and **decorators**. Both run at *runtime*, and both are fundamentally different from a Rust macro. ```typescript 1 // 1. A variadic helper — runs at runtime, fixed behavior, types erased. 2 function sum(...nums: number[]): number { 3 return nums.reduce((acc, n) => acc + n, 0); 4 } 5 console.log(sum(1, 2, 3)); // 6 — a real call happens at runtime 6 7 // 2. A "constructor helper" — also a runtime function call. 8 function dict<V>(...pairs: [string, V][]): Record<string, V> { 9 return Object.fromEntries(pairs); 10 } 11 const scores = dict(["alice", 95], ["bob", 87]); 12 console.log(scores); // { alice: 95, bob: 87 } 13 14 // 3. A decorator — the thing people WRONGLY compare to Rust attributes. 15 // It is a runtime function that receives and may replace the target. 16 function logged(value: Function, ctx: ClassMethodDecoratorContext) { 17 return function (this: unknown, ...args: unknown[]) { 18 console.log(`calling ${String(ctx.name)}`); 19 return value.apply(this, args); // wraps and calls at runtime 20 }; 21 } 22 23 class Api { 24 @logged 25 fetchUser(id: number) { 26 return { id }; 27 } 28 } 29 new Api().fetchUser(1); // logs "calling fetchUser", then runs ``` Three things to hold onto: the variadic `sum`/`dict` are **runtime function calls**, the generic `<V>` is **erased** before the code runs, and the `@logged` **decorator is a runtime wrapper function**. None of them generate new source code that the compiler then checks. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The Rust counterparts look superficially similar but happen entirely at **compile time**, before type checking, and produce real, checked Rust code. ```rust 1 use std::collections::HashMap; 2 3 // A variadic, type-GENERIC constructor macro. A plain function cannot do this: 4 // a function has a fixed arity and a single concrete element type. 5 macro_rules! hashmap { 6 // Match zero or more `key => value` pairs, allowing a trailing comma. 7 ( $( $key:expr => $val:expr ),* $(,)? ) => {{ 8 let mut map = HashMap::new(); 9 $( map.insert($key, $val); )* 10 map 11 }}; 12 } 13 14 fn main() { 15 // Expands at compile time into: a `let mut map`, three `insert` calls, etc. 16 let scores = hashmap! { 17 "alice" => 95, 18 "bob" => 87, 19 "carol" => 91, 20 }; 21 22 let mut entries: Vec<_> = scores.iter().collect(); 23 entries.sort(); 24 println!("{entries:?}"); 25 26 // The SAME macro with a totally different value type — no overloads needed, 27 // because the macro is expanded and type-checked fresh at each call site. 28 let flags = hashmap! { "debug" => true, "verbose" => false }; 29 println!("debug = {:?}", flags.get("debug")); 30 } ``` Real output: ```text 1 [("alice", 95), ("bob", 87), ("carol", 91)] 2 debug = Some(true) ``` The `hashmap!` invocation is *replaced* by the compiler with the block of code on the right-hand side of the rule. There is no `hashmap` function in the binary, only the `HashMap::new()` and `insert` calls it generated. > **Note:** The standard library does not ship a `hashmap!` macro (only `vec!`). We build one here precisely because it shows what a macro can do that a function cannot. The popular [`maplit`](https://crates.io/crates/maplit) crate provides a real one. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Macros run at compile time, functions run at runtime [Section titled “Macros run at compile time, functions run at runtime”](#macros-run-at-compile-time-functions-run-at-runtime) When you write `square!(5)` with this macro: ```rust 1 macro_rules! square { 2 ($x:expr) => { 3 $x * $x 4 }; 5 } 6 7 fn main() { 8 let n = 5; 9 println!("square = {}", square!(n)); // prints: square = 25 10 } ``` the compiler does **not** emit a call instruction. It textually-but-structurally substitutes the body, so `square!(n)` becomes `n * n` *in the source* before anything is type-checked. There is no `square` symbol in the compiled binary; the generated `n * n` is. This is **zero runtime cost** for the abstraction: a macro never adds a function call, a heap allocation, or a vtable lookup of its own. Contrast with TypeScript’s `square(n)`, which compiles to a genuine function call that the JavaScript engine executes (and may or may not inline) at runtime. ### Macros are NOT functions [Section titled “Macros are NOT functions”](#macros-are-not-functions) This is the single most important correction for a TypeScript/JavaScript developer: * A function receives **values**; a macro receives **tokens** (pieces of source code) and produces **tokens**. * A function has a fixed **arity** and **types**; a macro can accept a variable number of arguments of arbitrary, mixed shapes (that is how `println!("{}", x)` and `vec![1, 2, 3]` and `hashmap!{ a => b }` all work). * A function call exists in the running program; a macro is gone by runtime, replaced by what it generated. The trailing `!` is the syntactic flag that says “this is a macro invocation, not a function call”: `println!`, `vec!`, `assert_eq!`. (Attribute and derive macros use `#[...]` instead, covered in the sibling pages.) ### Because macros take *tokens*, they preserve grouping [Section titled “Because macros take tokens, they preserve grouping”](#because-macros-take-tokens-they-preserve-grouping) A famous footgun in C’s textual macros does **not** happen with `macro_rules!` fragment matchers. Consider: ```rust 1 macro_rules! square { 2 ($x:expr) => { $x * $x }; 3 } 4 5 fn main() { 6 let n = 4; 7 let r = square!(n + 1); // captured as ONE expression: (n + 1) 8 println!("square!(n + 1) = {r}"); 9 println!("manual n + 1 * n + 1 = {}", n + 1 * n + 1); 10 } ``` Real output: ```text 1 square!(n + 1) = 25 2 manual n + 1 * n + 1 = 9 ``` A C-style textual macro would paste `n + 1 * n + 1` and print `9`. Rust’s `:expr` **fragment specifier** captures `n + 1` as a single, already-parsed expression node, so it expands as if parenthesized and prints `25`. Rust macros operate on the parsed token tree, not raw text; they are structurally aware. (The full menu of fragment specifiers like `:expr`, `:ident`, `:ty`, `:tt` lives in [Macro Patterns](/14-macros/02-macro-patterns/).) ### Hygiene: macro-introduced names cannot collide with yours [Section titled “Hygiene: macro-introduced names cannot collide with yours”](#hygiene-macro-introduced-names-cannot-collide-with-yours) This is the property that makes `macro_rules!` safe to use and is unlike anything in TypeScript/JavaScript text- or AST-based code generation. Identifiers a macro *creates* live in their own syntactic context and will not capture or be captured by identifiers at the call site: ```rust 1 // A macro that introduces a temporary binding `tmp` internally. 2 macro_rules! swap { 3 ($a:expr, $b:expr) => {{ 4 let tmp = $a; // this `tmp` belongs to the macro, NOT the caller 5 $a = $b; 6 $b = tmp; 7 }}; 8 } 9 10 fn main() { 11 let mut tmp = 1; // the caller has its OWN `tmp` 12 let mut other = 2; 13 swap!(tmp, other); // works correctly despite the name clash 14 println!("tmp = {tmp}, other = {other}"); 15 } ``` Real output: ```text 1 tmp = 2, other = 1 ``` Even though both the macro and the caller use the name `tmp`, they refer to different variables. The compiler tracks where each identifier was *written* (the macro definition vs. the call site) and keeps them separate. In JavaScript, a naive string-template code generator that emitted `let tmp = ...` would silently clobber a caller’s `tmp`. Rust’s macro hygiene prevents that class of bug entirely. > **Note:** Hygiene applies to identifiers the macro *invents*. Identifiers you *pass in* (here `$a` and `$b`) deliberately resolve at the call site; that is what lets `swap!` touch the caller’s variables. Hygiene is about accidental capture, not about blocking intentional access. ### Macros are NOT decorators [Section titled “Macros are NOT decorators”](#macros-are-not-decorators) TypeScript decorators (`@logged`) are runtime functions that observe or wrap a target *after* the program starts. Rust’s `#[derive(Debug)]` and other attribute macros *look* similar but are compile-time code generators: `#[derive(Debug)]` literally writes a `Debug` implementation into your binary at compile time; there is no runtime wrapping and no reflection. Saying “Rust attributes are like decorators” is a common but misleading analogy. See [Derive Macros](/14-macros/04-derive-macros/) and [Attribute Macros](/14-macros/05-attribute-macros/) for the real picture. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript | Rust macro | | ------------------- | ------------------------------- | ------------------------------------------ | | When it runs | Runtime (functions, decorators) | Compile time, before type checking | | What it operates on | Values (and erased types) | Tokens / parsed syntax | | Runtime cost | A real call / wrapper exists | None — expands to inline code | | Arity & types | Fixed per function | Variadic, mixed, type-generic | | Name collisions | Possible in string codegen | Prevented by hygiene | | Invocation marker | `f(...)`, `@dec` | `name!(...)`, `#[name]`, `#[derive(Name)]` | | Generics | Erased at runtime | Monomorphized at compile time | | Closest TS analogy | none is exact | decorators ≈ attributes (but compile-time) | ### Why Rust has macros at all [Section titled “Why Rust has macros at all”](#why-rust-has-macros-at-all) Rust’s type system is strict and there is no runtime reflection (unlike, say, decorators inspecting metadata). Macros fill the gap that dynamic languages fill with runtime metaprogramming: removing boilerplate, building domain-specific syntax, and producing variadic constructs, all without paying a runtime price and without weakening type safety, because the *generated* code is type-checked exactly like hand-written code. ### Two families of macros [Section titled “Two families of macros”](#two-families-of-macros) You will meet two kinds in this section: 1. **Declarative macros** (`macro_rules!`) — pattern-match on token trees and substitute. Great for “this expands to that” templates. Covered in [Declarative Macros](/14-macros/01-declarative-macros/), [Macro Patterns](/14-macros/02-macro-patterns/), and [Repetition](/14-macros/03-repetition/). 2. **Procedural macros** — small compiler plugins written in Rust that take a `TokenStream` and return one, typically using the `syn` and `quote` crates. These power custom `#[derive(...)]`, attribute macros, and function-like `foo!(...)` procedural macros. Covered in [Derive Macros](/14-macros/04-derive-macros/), [Attribute Macros](/14-macros/05-attribute-macros/), [Function-like Macros](/14-macros/06-function-like-macros/), and [Procedural Macros](/14-macros/07-proc-macros/). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting the `!` [Section titled “Pitfall 1: Forgetting the !”](#pitfall-1-forgetting-the-) A macro invocation needs the bang. Without it, the compiler tries to parse a function call or expression and fails: ```rust 1 fn main() { 2 let v = vec[1, 2, 3]; // does not compile — forgot the `!` 3 println!("{v:?}"); 4 } ``` Real compiler error: ```text 1 error: expected one of `.`, `?`, `]`, or an operator, found `,` 2 --> src/main.rs:2:18 3 | 4 2 | let v = vec[1, 2, 3]; // forgot the ! 5 | ^ expected one of `.`, `?`, `]`, or an operator ``` The fix is `vec![1, 2, 3]`. The compiler saw `vec[...]` and tried to parse it as indexing into a thing named `vec`, hence the confusing message. A good reminder that *without the bang it is not a macro at all*. ### Pitfall 2: Expecting a runtime function to exist [Section titled “Pitfall 2: Expecting a runtime function to exist”](#pitfall-2-expecting-a-runtime-function-to-exist) Because a macro is gone after expansion, you cannot pass it as a value, store it in a variable, or use it as a callback the way you can a JavaScript function: ```rust 1 // does not compile — there is no `println` value to pass around. 2 // let f = println; // error[E0423]: expected value, found macro `println` ``` A macro name on its own is not an expression. If you need first-class behavior, wrap the macro in a closure or function: `let f = |s: &str| println!("{s}");`. ### Pitfall 3: Assuming format/argument errors are caught at runtime [Section titled “Pitfall 3: Assuming format/argument errors are caught at runtime”](#pitfall-3-assuming-formatargument-errors-are-caught-at-runtime) `println!` and friends validate their format string at **compile time**, a genuine advantage over `console.log` template strings: ```rust 1 fn main() { 2 println!("{} and {}", 42); // does not compile — 2 placeholders, 1 argument 3 } ``` Real compiler error: ```text 1 error: 2 positional arguments in format string, but there is 1 argument 2 --> src/main.rs:2:15 3 | 4 2 | println!("{} and {}", 42); // 2 placeholders, 1 argument 5 | ^^ ^^ -- ``` In TypeScript, a malformed template only misbehaves at runtime, if at all. ### Pitfall 4: Typos surface as “cannot find macro” [Section titled “Pitfall 4: Typos surface as “cannot find macro””](#pitfall-4-typos-surface-as-cannot-find-macro) Because macros are resolved by name during expansion, a typo gives a clear (and helpfully suggestive) error: ```rust 1 fn main() { 2 primtln!("hello"); // does not compile — typo 3 } ``` Real compiler error: ```text 1 error: cannot find macro `primtln` in this scope 2 --> src/main.rs:2:5 3 | 4 2 | primtln!("hello"); // typo 5 | ^^^^^^^ help: a macro with a similar name exists: `println` ``` ### Pitfall 5: Reaching for a macro when a function would do [Section titled “Pitfall 5: Reaching for a macro when a function would do”](#pitfall-5-reaching-for-a-macro-when-a-function-would-do) Macros are harder to read, harder to document, and produce worse IDE and error experiences than plain functions. The biggest *conceptual* mistake is treating them as the default tool. See Best Practices below. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Prefer a function unless you truly need a macro [Section titled “Prefer a function unless you truly need a macro”](#prefer-a-function-unless-you-truly-need-a-macro) If a regular function (possibly generic, possibly with a trait bound) can express it, use the function. Reach for a macro only when you need one of these things a function genuinely cannot provide: 1. **Variadic arguments** with mixed types — e.g. `println!`, `vec!`, `hashmap!`. 2. **New syntax / a mini-DSL** — e.g. building a routing table or a SQL-ish query block. 3. **Operating on the source itself** — capturing the *text* of an expression (`stringify!`), the current file and line (`file!`, `line!`), or generating trait `impl`s from a type definition (`#[derive(...)]`). 4. **Eliminating boilerplate** that would otherwise be copy-pasted across many types. If none of those apply, a function is clearer, faster to compile, and friendlier to tooling. ### Keep macros small and well-documented [Section titled “Keep macros small and well-documented”](#keep-macros-small-and-well-documented) A macro’s expansion is invisible at the call site, so document what it generates and give a worked example. When debugging, inspect the expansion with [`cargo expand`](https://github.com/dtolnay/cargo-expand) (`cargo install cargo-expand`, then `cargo expand`), which prints your code with all macros expanded — covered further in [Declarative Macros](/14-macros/01-declarative-macros/). ### Lean on the standard library’s macros first [Section titled “Lean on the standard library’s macros first”](#lean-on-the-standard-librarys-macros-first) You rarely need to write a macro at all. `vec!`, `format!`, `assert_eq!`, `matches!`, `todo!`, `dbg!`, `include_str!`, and the rest cover a huge amount of ground; see [Common Macros](/14-macros/08-common-macros/) before writing your own. ### Trust hygiene, but pass identifiers explicitly when you need access [Section titled “Trust hygiene, but pass identifiers explicitly when you need access”](#trust-hygiene-but-pass-identifiers-explicitly-when-you-need-access) Let the macro invent its own temporaries freely; hygiene keeps them safe. When the macro must touch a caller’s binding, take it as an argument (`$a:expr` / `$name:ident`) rather than hard-coding a name and hoping it matches. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small, production-flavored logging macro that captures the *expression source* and the *current location* — two things a function literally cannot do, because by the time a function runs, the original source text and call site are gone. This mirrors the standard `dbg!` macro. ```rust 1 /// Logs an expression's source text, its file:line, and its value, 2 /// then returns the value so it can be used inline. Like a typed `console.log` 3 /// that also tells you WHERE and WHAT it logged — checked at compile time. 4 macro_rules! trace { 5 ($e:expr) => {{ 6 let value = $e; // hygienic temporary; cannot clash with caller code 7 eprintln!("[{}:{}] {} = {:?}", file!(), line!(), stringify!($e), &value); 8 value 9 }}; 10 } 11 12 fn parse_port(raw: &str) -> u16 { 13 // We can drop `trace!` around any sub-expression without changing behavior. 14 trace!(raw.trim().parse::<u16>().unwrap_or(8080)) 15 } 16 17 fn main() { 18 let port = parse_port(" 9000 "); 19 println!("listening on port {port}"); 20 } ``` Real output (the `trace!` line goes to stderr, the result to stdout): ```text 1 [src/main.rs:14] raw.trim().parse::<u16>().unwrap_or(8080) = 9000 2 listening on port 9000 ``` The macro recorded the literal text `raw.trim().parse::<u16>().unwrap_or(8080)` via `stringify!`, the exact `file!`/`line!`, and the computed value, all resolved at compile time, with the temporary `value` kept hygienically separate from anything in `parse_port`. The standard library ships exactly this idea as `dbg!`: ```rust 1 fn main() { 2 let n = 5; 3 let doubled = dbg!(n * 2); // prints to stderr, returns the value 4 println!("doubled = {doubled}"); 5 } ``` Real output: ```text 1 [src/main.rs:3:19] n * 2 = 10 2 doubled = 10 ``` Reach for `dbg!` (see [Common Macros](/14-macros/08-common-macros/)) before hand-rolling your own; the example above exists to show *why* this can only be a macro. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Rust Book — Macros](https://doc.rust-lang.org/book/ch20-05-macros.html): declarative vs. procedural macros. * [The Little Book of Rust Macros](https://veykril.github.io/tlborm/): the definitive in-depth guide to `macro_rules!`, hygiene, and patterns. * [Reference — Macros](https://doc.rust-lang.org/reference/macros.html) and [Macro hygiene](https://doc.rust-lang.org/reference/macros-by-example.html#hygiene). * [`std::dbg!`](https://doc.rust-lang.org/std/macro.dbg.html) and [`std::stringify!`](https://doc.rust-lang.org/std/macro.stringify.html). ### Related sections in this guide [Section titled “Related sections in this guide”](#related-sections-in-this-guide) * Next: [Declarative Macros](/14-macros/01-declarative-macros/): write your first `macro_rules!`. * [Macro Patterns](/14-macros/02-macro-patterns/) — fragment specifiers (`:expr`, `:ident`, `:ty`, `:tt`, …). * [Repetition](/14-macros/03-repetition/) — `$(...),*` and building a `vec!`-like macro. * [Derive Macros](/14-macros/04-derive-macros/) and [Attribute Macros](/14-macros/05-attribute-macros/) — why these are *not* decorators. * [Procedural Macros](/14-macros/07-proc-macros/): `syn` 2 + `quote` and a real custom derive. * [Common Macros](/14-macros/08-common-macros/) — the standard-library macros you will use daily. * Background: [Output and Formatting](/02-basics/04-output/) introduced `println!`; [Getting Started](/01-getting-started/) and the [Introduction](/00-introduction/) set the stage. * Looking ahead: derive macros power [Serialization](/15-serialization/) via `#[derive(Serialize, Deserialize)]`. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1 [Section titled “Exercise 1”](#exercise-1) **Difficulty:** Easy **Objective:** Confirm for yourself that a macro substitutes code rather than calling a function, and that fragment specifiers preserve grouping. **Instructions:** Write a declarative macro `max2!` that takes two expressions and evaluates to the larger one. Invoke it as `max2!(3 + 4, 10)` and print the result. Predict the output before running. ```rust 1 macro_rules! max2 { 2 // TODO: match two expressions and expand to an `if`/`else` 3 } 4 5 fn main() { 6 println!("max2 = {}", max2!(3 + 4, 10)); 7 } ``` Solution ```rust 1 macro_rules! max2 { 2 ($a:expr, $b:expr) => { 3 if $a >= $b { $a } else { $b } 4 }; 5 } 6 7 fn main() { 8 // `3 + 4` is captured as one expression, so this compares 7 vs 10. 9 println!("max2 = {}", max2!(3 + 4, 10)); // max2 = 10 10 } ``` Output: ```text 1 max2 = 10 ``` ### Exercise 2 [Section titled “Exercise 2”](#exercise-2) **Difficulty:** Medium **Objective:** Use `stringify!` to capture an expression’s *source text* — something only a macro can do — and observe hygiene in action. **Instructions:** Write a macro `show!` that takes one expression, prints it as `<source> = <value>` using `stringify!` and `{:?}`, and then *returns* the value so it can be used inline. Internally bind the value to a temporary named `val`; call `show!` from a `main` that also has its own `val` to prove the names do not collide. ```rust 1 macro_rules! show { 2 // TODO: bind to a temporary, print `stringify!` of the expr, return the value 3 } 4 5 fn main() { 6 let val = "untouched"; 7 let x = show!(2 * 21); 8 println!("returned {x}, caller val = {val}"); 9 } ``` Solution ```rust 1 macro_rules! show { 2 ($e:expr) => {{ 3 let val = $e; // hygienic: does NOT clash with the caller's `val` 4 println!("{} = {:?}", stringify!($e), val); 5 val 6 }}; 7 } 8 9 fn main() { 10 let val = "untouched"; 11 let x = show!(2 * 21); 12 println!("returned {x}, caller val = {val}"); 13 } ``` Output: ```text 1 2 * 21 = 42 2 returned 42, caller val = untouched ``` The macro’s `val` and the caller’s `val` are independent, demonstrating hygiene. ### Exercise 3 [Section titled “Exercise 3”](#exercise-3) **Difficulty:** Hard **Objective:** Build a variadic, compile-time construct that no single Rust function could express, using recursion and repetition. **Instructions:** Write a macro `count!` that accepts any number of comma-separated expressions and expands to the number of arguments as a `usize`, fully at compile time. Handle the empty case `count!()` and a non-empty list. Verify `count!(10, 20, 30, 40)` is `4`. > **Tip:** Define two rules: one for the empty input, one that peels off a head argument and recurses on the tail. Repetition syntax is detailed in [Repetition](/14-macros/03-repetition/). ```rust 1 macro_rules! count { 2 // TODO: base case for `()` 3 // TODO: recursive case `$head:expr $(, $tail:expr)*` 4 } 5 6 fn main() { 7 println!("count = {}", count!(10, 20, 30, 40)); 8 println!("empty = {}", count!()); 9 } ``` Solution ```rust 1 macro_rules! count { 2 () => { 0usize }; 3 ($head:expr $(, $tail:expr)*) => { 4 1usize + count!($($tail),*) 5 }; 6 } 7 8 fn main() { 9 println!("count = {}", count!(10, 20, 30, 40)); // 4 10 println!("empty = {}", count!()); // 0 11 } ``` Output: ```text 1 count = 4 2 empty = 0 ``` Each expansion strips one argument and adds `1usize`, recursing until the empty rule terminates the chain. The entire count is computed during compilation; the binary just contains the constant. # Declarative Macros with `macro_rules!` > Write macro_rules! macros that match Rust tokens and stamp out code at compile time, with hygiene and trailing commas, then view expansions with cargo expand. A practical tour of Rust’s declarative macros: how `macro_rules!` matches the tokens you pass it, how it stamps out code at compile time, and how to actually *see* what your macro expands into with `cargo expand`. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **declarative macro** is a compile-time pattern-matcher over Rust source tokens: you give it patterns to match (matchers) and the code to generate for each (transcribers), and the compiler expands every call site before type checking and code generation. The result is real, type-checked Rust with **zero runtime cost**: there is no interpreter, no reflection, and nothing left over at runtime. For a TypeScript/JavaScript developer the closest mental hook is a code generator or a tagged template that produces source, except it runs *inside the compiler* and the output is fully checked. > **Note:** This file covers the everyday `macro_rules!` form. The companion pages go deeper: see [Macro Patterns](/14-macros/02-macro-patterns/) for the full set of fragment specifiers, [Macro Repetition](/14-macros/03-repetition/) for the repetition operators, and [Macro Basics](/14-macros/00-macro-basics/) for the conceptual “what macros are and are NOT”. The fundamentally different *procedural* macros (custom `#[derive]`, attributes) live in [Procedural Macros](/14-macros/07-proc-macros/). ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) TypeScript/JavaScript has no language-level macro system. When you need to avoid repeating yourself, you reach for runtime helper functions, builder objects, or, at the extreme, code generation as a build step. Here is the kind of boilerplate a macro would later replace, written the way you would actually write it in TypeScript: ```typescript 1 // A small helper that builds a Map from key/value pairs. 2 // This is a *runtime* function: it runs every time the program executes. 3 function makeMap<K, V>(pairs: Array<[K, V]>): Map<K, V> { 4 const map = new Map<K, V>(); 5 for (const [key, value] of pairs) { 6 map.set(key, value); 7 } 8 return map; 9 } 10 11 const scores = makeMap<string, number>([ 12 ["alice", 95], 13 ["bob", 87], 14 ["carol", 92], 15 ]); 16 17 // A logging wrapper — also a runtime function call. 18 function logInfo(...args: unknown[]): void { 19 console.log("[INFO] ", ...args); 20 } 21 22 const user = "alice"; 23 logInfo(`user ${user} signed in`); // [INFO] user alice signed in ``` Two things to notice, because they are exactly where Rust macros differ: 1. `makeMap` and `logInfo` are ordinary functions. They exist at runtime, take values, and return values. 2. The `[...]` literal and the template string `` `user ${user}...` `` are the only *syntactic* shortcuts the language gives you, and they are fixed. You cannot define your own `myliteral { ... }` syntax. ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) A declarative macro lets you define new *syntax* that expands into code. Below, `hashmap!` accepts `key => value` pairs and expands — at compile time — into a sequence of `insert` calls. The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically, and `macro_rules!` works on every edition. ```rust 1 use std::collections::HashMap; 2 3 // Define a macro that builds a HashMap from `key => value` pairs. 4 macro_rules! hashmap { 5 // One matcher: a comma-separated list of `key => value` pairs. 6 // `$(,)?` allows an optional trailing comma, just like a Rust array literal. 7 ( $( $key:expr => $value:expr ),* $(,)? ) => {{ 8 let mut map = HashMap::new(); 9 $( 10 map.insert($key, $value); 11 )* 12 map 13 }}; 14 } 15 16 fn main() { 17 let scores = hashmap! { 18 "alice" => 95, 19 "bob" => 87, 20 "carol" => 92, 21 }; 22 23 let mut keys: Vec<_> = scores.keys().collect(); 24 keys.sort(); 25 for k in keys { 26 println!("{k}: {}", scores[k]); 27 } 28 } ``` Running it: ```plaintext 1 alice: 95 2 bob: 87 3 carol: 92 ``` The `!` after `hashmap` is the giveaway that you are calling a macro, not a function: the same `!` you already use with `println!` and `vec!`. Unlike the TypeScript `makeMap`, there is **no `makeMap` left in the compiled binary**: by the time the program runs, `hashmap! { ... }` has already become three `map.insert(...)` lines. ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) A `macro_rules!` definition is a set of **rules**, each of the form `(matcher) => {transcriber};`. The compiler tries the rules top to bottom; the first matcher whose pattern fits the tokens at the call site wins, and its transcriber is substituted in place of the call. ### Anatomy of the simplest macro [Section titled “Anatomy of the simplest macro”](#anatomy-of-the-simplest-macro) ```rust 1 // A macro with no arguments: it always expands to the same fixed block. 2 macro_rules! greet { 3 () => { 4 println!("Hello from a macro!"); 5 }; 6 } 7 8 // A macro that captures one expression. 9 macro_rules! square { 10 ($x:expr) => { 11 $x * $x 12 }; 13 } 14 15 fn main() { 16 greet!(); // expands to: println!("Hello from a macro!"); 17 18 let n = 5; 19 println!("{}", square!(n)); // expands to: n * n -> 25 20 println!("{}", square!(2 + 1)); // expands to: (2 + 1) * (2 + 1) -> 9 21 } ``` Output: ```plaintext 1 Hello from a macro! 2 25 3 9 ``` Walking through the pieces: * **`macro_rules! square { ... }`** declares a macro named `square`. * **`($x:expr)`** is the matcher. `$x` is a **metavariable** (the `$` marks it), and `:expr` is its **fragment specifier**, meaning “match a complete Rust expression here”. When you call `square!(2 + 1)`, the metavariable `$x` is bound to the expression `2 + 1`. * **`=> { $x * $x }`** is the transcriber. Every occurrence of `$x` is replaced by the matched fragment, so the call expands to `$x * $x`. > **Note:** The `2 + 1` result of `9` (not `5`) is important and surprising if you come from C-style text macros. A fragment captured as `:expr` is stored as a **single parsed expression node**, not as loose tokens. When it is substituted back in it behaves as if parenthesized, so `square!(2 + 1)` is `(2 + 1) * (2 + 1)`, never `2 + 1 * 2 + 1`. Rust macros operate on the abstract syntax tree, not on raw text. This is one of the biggest differences from C’s preprocessor. ### The repetition in `hashmap!` [Section titled “The repetition in hashmap!”](#the-repetition-in-hashmap) The `hashmap!` macro used two repetition constructs: * **In the matcher:** `$( $key:expr => $value:expr ),*` means “match zero or more `key => value` groups, separated by commas”. The `*` is the repetition count (zero-or-more). * **In the transcriber:** `$( map.insert($key, $value); )*` repeats the `insert` line once per group that was matched, reusing the `$key` and `$value` captured each time. So the input ```rust 1 hashmap! { "alice" => 95, "bob" => 87 } ``` expands to roughly: ```rust 1 { 2 let mut map = HashMap::new(); 3 map.insert("alice", 95); 4 map.insert("bob", 87); 5 map 6 } ``` Repetition has its own dedicated page — see [Macro Repetition](/14-macros/03-repetition/) for `*`, `+`, `?`, and the different separators — so this file keeps to the minimum needed to read the examples. ### Why the doubled braces `{{ ... }}`? [Section titled “Why the doubled braces {{ ... }}?”](#why-the-doubled-braces---) In `hashmap!` the transcriber is wrapped in `{{ ... }}`. The outer braces are macro-syntax punctuation; the inner braces make the expansion a **block expression** that evaluates to a value (the `map`). Without the inner block, `let scores = hashmap! { ... };` would not have a single expression to bind. This is the standard idiom for a macro that “returns” something. ### Hygiene: macro-introduced names do not leak [Section titled “Hygiene: macro-introduced names do not leak”](#hygiene-macro-introduced-names-do-not-leak) Rust macros are **hygienic**: identifiers a macro introduces internally live in their own syntactic context and cannot accidentally collide with the caller’s variables. ```rust 1 macro_rules! double_it { 2 ($x:expr) => {{ 3 let result = $x * 2; // `result` here is the macro's own, hygienic binding 4 result 5 }}; 6 } 7 8 fn main() { 9 let result = 100; // the caller has a variable *also* named `result` 10 let doubled = double_it!(21); 11 // The macro's internal `result` did NOT overwrite the caller's `result`: 12 println!("caller result = {result}, doubled = {doubled}"); 13 } ``` Output: ```plaintext 1 caller result = 100, doubled = 42 ``` In a C-style textual macro this would be a classic bug (variable capture). In Rust the two `result`s are genuinely distinct. Hygiene is covered more fully in [Macro Basics](/14-macros/00-macro-basics/). ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | TypeScript/JavaScript helper | Rust `macro_rules!` | | --------------------- | ----------------------------------------------- | ---------------------------------------------- | | When it runs | At runtime, every call | At compile time, expanded once per call site | | What it operates on | Runtime values | Source tokens / AST fragments | | Cost in the binary | A real function in the bundle | Nothing — only the expanded code remains | | Can it invent syntax? | No (only literals/template strings) | Yes: `mymacro! { a => b, ... }` | | Type checking | At runtime (or via TypeScript before transpile) | After expansion, by the normal Rust compiler | | Variable capture | Possible if you reuse names | Prevented by hygiene | | Argument arity | Fixed (or `...rest`) | Patterns can match variable shapes and counts | | Error timing | Mostly runtime | Compile time (a malformed call fails to build) | The headline difference: a TypeScript helper is a *value-level* abstraction; a Rust macro is a *syntax-level* abstraction. A macro can do things a function cannot (accept a variable number of differently-typed arguments, take a block of code, or generate `let` bindings) precisely because it works on syntax before types exist. > **Warning:** A macro is *not* a decorator, and `macro_rules!` is *not* a function with weird syntax. If you only need to abstract over values, write a function. It is simpler, easier to read, and gives better error messages. Reach for a macro only when you genuinely need new syntax, variadic/heterogeneous arguments, or compile-time code generation. The “when to reach for a macro” decision is discussed in [Macro Basics](/14-macros/00-macro-basics/). ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Calling a macro before it is defined [Section titled “Pitfall 1: Calling a macro before it is defined”](#pitfall-1-calling-a-macro-before-it-is-defined) Unlike functions, `macro_rules!` macros are **textually scoped**: a call only sees macros defined *earlier* in the source (or imported). This trips up developers used to JavaScript function hoisting. ```rust 1 fn main() { 2 greet!(); // does not compile: macro used before its definition 3 } 4 5 macro_rules! greet { 6 () => { println!("hi"); }; 7 } ``` The real compiler error: ```plaintext 1 error: cannot find macro `greet` in this scope 2 --> src/main.rs:2:5 3 | 4 2 | greet!(); // does not compile: macro used before its definition 5 | ^^^^^ consider moving the definition of `greet` before this call 6 | 7 note: a macro with the same name exists, but it appears later 8 --> src/main.rs:5:14 9 | 10 5 | macro_rules! greet { 11 | ^^^^^ ``` **Fix:** move the `macro_rules!` definition above its first use. To use a macro from other modules or crates, annotate it with `#[macro_export]` (which lifts it to the crate root) and import it like any other item — see [Modules & Packages](/12-modules-packages/). ### Pitfall 2: Passing tokens that do not match the fragment specifier [Section titled “Pitfall 2: Passing tokens that do not match the fragment specifier”](#pitfall-2-passing-tokens-that-do-not-match-the-fragment-specifier) If the call site does not match any matcher, you get a compile error pointing at the exact token that broke the match. ```rust 1 macro_rules! only_ident { 2 ($name:ident) => { 3 let $name = 1; 4 }; 5 } 6 7 fn main() { 8 only_ident!(x); // fine: `x` is an identifier 9 only_ident!(1 + 2); // does not compile: `1 + 2` is not an `ident` 10 } ``` The real compiler error: ```plaintext 1 error: no rules expected `1` 2 --> src/main.rs:9:17 3 | 4 1 | macro_rules! only_ident { 5 | ----------------------- when calling this macro 6 ... 7 9 | only_ident!(1 + 2); // does not compile: `1 + 2` is not an `ident` 8 | ^ no rules expected this token in macro call 9 | 10 note: while trying to match meta-variable `$name:ident` 11 --> src/main.rs:2:6 12 | 13 2 | ($name:ident) => { 14 | ^^^^^^^^^^^ ``` **Fix:** pick the fragment specifier that matches what callers will actually pass (`:expr` for arbitrary expressions, `:ident` only for plain names). The full list is in [Macro Patterns](/14-macros/02-macro-patterns/). ### Pitfall 3: Reaching for a macro when a function would do [Section titled “Pitfall 3: Reaching for a macro when a function would do”](#pitfall-3-reaching-for-a-macro-when-a-function-would-do) ```rust 1 // Over-engineered: a macro that only ever forwards two values. 2 macro_rules! add { 3 ($a:expr, $b:expr) => { $a + $b }; 4 } 5 6 // A plain generic function is clearer, type-checked at definition, and 7 // shows up in IDE autocompletion and docs. 8 fn add<T: std::ops::Add<Output = T>>(a: T, b: T) -> T { 9 a + b 10 } ``` Both compile, but the function is the right tool. Macros sacrifice readability and tooling support; only pay that price when you need syntax a function cannot express. ### Pitfall 4: Forgetting that `expr` fragments are atomic, then “fixing” it the wrong way [Section titled “Pitfall 4: Forgetting that expr fragments are atomic, then “fixing” it the wrong way”](#pitfall-4-forgetting-that-expr-fragments-are-atomic-then-fixing-it-the-wrong-way) Because `:expr` fragments behave as if parenthesized, you do **not** need to wrap them defensively for precedence the way you would in a C macro. Adding `($x)` is harmless but redundant for `:expr`. The trap is assuming the *opposite* (that `square!(2 + 1)` is `5`) and writing tests against the wrong expected value. It is `9`. ## Best Practices [Section titled “Best Practices”](#best-practices) * **Prefer a function unless you need syntax.** This is the single most important rule. Macros are a last resort, not a first reach. * **Support an optional trailing comma** with `$(,)?` in list-like macros, so callers can format multi-line invocations the way `vec!`, arrays, and struct literals allow. * **Wrap value-producing expansions in a block** (`{{ ... }}`) so the macro can be used wherever an expression is expected. * **Name fragments descriptively** (`$key`, `$value`, `$body`) rather than `$x`, `$y`. The matcher is documentation. * **Forward formatting macros transparently** with `$($arg:tt)*`. A logging wrapper should accept exactly what `println!` accepts: ```rust 1 macro_rules! log_info { 2 ($($arg:tt)*) => {{ 3 print!("[INFO] "); 4 println!($($arg)*); 5 }}; 6 } 7 8 fn main() { 9 let user = "alice"; 10 log_info!("user {user} signed in"); // inline capture works 11 log_info!("retried {} times", 3); // positional args work 12 } ``` Output: ```plaintext 1 [INFO] user alice signed in 2 [INFO] retried 3 times ``` * **Inspect expansions with `cargo expand`** while developing; see the next section. It turns “what does this even generate?” into a one-command answer. * **Export deliberately.** Only add `#[macro_export]` when a macro is part of your crate’s public surface; otherwise keep it module-local. ### Seeing the expansion with `cargo expand` [Section titled “Seeing the expansion with cargo expand”](#seeing-the-expansion-with-cargo-expand) `cargo expand` is a developer tool (a Cargo subcommand) that prints your code *after* all macros have been expanded. It is the macro author’s best friend. Install it once and run it from any project: ```bash 1 # Install the subcommand (built on top of cargo; network access required). 2 cargo install cargo-expand 3 4 # Print the whole crate, fully macro-expanded. 5 cargo expand ``` > **Tip:** `cargo expand` invokes the nightly compiler’s unstable pretty-printer under the hood, so it needs a nightly toolchain available (`rustup toolchain install nightly`). Your *project* still builds on stable; only the expansion view uses nightly. Given the `main` from earlier, `cargo expand` shows it desugar to (prelude header kept for context): ```rust 1 #![feature(prelude_import)] 2 #[macro_use] 3 extern crate std; 4 #[prelude_import] 5 use std::prelude::rust_2024::*; 6 fn main() { 7 { 8 ::std::io::_print(format_args!("Hello from a macro!\n")); 9 }; 10 let n = 5; 11 { 12 ::std::io::_print(format_args!("{0}\n", n * n)); 13 }; 14 { 15 ::std::io::_print(format_args!("{0}\n", (2 + 1) * (2 + 1))); 16 }; 17 } ``` Two lessons jump out. First, `square!(2 + 1)` expanded to `(2 + 1) * (2 + 1)`: concrete proof that the `:expr` fragment was treated as one parenthesized unit. Second, even `println!` is itself a macro: it expanded into a `format_args!` call routed through `::std::io::_print`. Macros expand recursively until only plain Rust remains. (The built-in standard-library macros, including `println!`, `format!`, and `vec!`, are catalogued in [Common Standard-Library Macros](/14-macros/08-common-macros/).) For the `hashmap!` macro, the body of `main` expands to exactly the unrolled inserts: ```rust 1 fn main() { 2 let scores = { 3 let mut map = HashMap::new(); 4 map.insert("alice", 95); 5 map.insert("bob", 87); 6 map 7 }; 8 { 9 ::std::io::_print(format_args!("{0}\n", scores.len())); 10 }; 11 } ``` ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A common production need is lightweight instrumentation: log a message at a level, and time how long a block of work takes. In TypeScript you would write helper functions and pass a callback. In Rust a small set of declarative macros gives you cleaner call sites and zero indirection: the timing code is inlined directly where you use it. ```rust 1 use std::time::Instant; 2 3 // Structured logging macros. `$($arg:tt)*` captures *all* the remaining tokens, 4 // so these forward the full `println!`/`eprintln!` argument syntax unchanged. 5 macro_rules! log_info { 6 ($($arg:tt)*) => {{ 7 print!("[INFO] "); 8 println!($($arg)*); 9 }}; 10 } 11 12 macro_rules! log_error { 13 ($($arg:tt)*) => {{ 14 eprint!("[ERROR] "); 15 eprintln!($($arg)*); 16 }}; 17 } 18 19 // `time_it!` takes a label and a *block*, runs the block, reports the elapsed 20 // time, and evaluates to the block's value. A function cannot take a block of 21 // statements as an argument the way this matcher (`$body:block`) can. 22 macro_rules! time_it { 23 ($label:expr, $body:block) => {{ 24 let start = Instant::now(); 25 let result = $body; 26 log_info!("{} took {:?}", $label, start.elapsed()); 27 result 28 }}; 29 } 30 31 fn main() { 32 let user = "alice"; 33 log_info!("user {user} signed in"); 34 log_error!("failed after {} retries", 3); 35 36 // `time_it!` evaluates to whatever the block returns. 37 let sum = time_it!("summation", { 38 (1..=1_000u64).sum::<u64>() 39 }); 40 41 log_info!("sum = {sum}"); 42 } ``` Output (the exact timing varies run to run): ```plaintext 1 [INFO] user alice signed in 2 [ERROR] failed after 3 retries 3 [INFO] summation took 7.333µs 4 [INFO] sum = 500500 ``` This is the legitimate use case for declarative macros: `time_it!` needs to *wrap a block of code* and reuse it, which no function signature can express, and the logging macros need to forward arbitrary format arguments. The expansions are inlined, so there is no closure allocation or call overhead at the timed site. > **Note:** For real applications, prefer the ecosystem’s [`log`](https://docs.rs/log) or [`tracing`](https://docs.rs/tracing) crates rather than hand-rolled logging macros; they handle levels, filtering, and structured fields. The example above is to demonstrate the macro mechanics, not to reinvent logging. ## Further Reading [Section titled “Further Reading”](#further-reading) * [Macros chapter — *The Rust Programming Language*](https://doc.rust-lang.org/book/ch20-05-macros.html) — the official book’s macro overview. * [Macros By Example — *The Rust Reference*](https://doc.rust-lang.org/reference/macros-by-example.html) — the precise grammar of `macro_rules!`, matchers, and repetition. * [*The Little Book of Rust Macros*](https://veykril.github.io/tlborm/) — a community deep look at declarative-macro techniques. * [`cargo expand` on crates.io](https://crates.io/crates/cargo-expand) — the expansion-viewing subcommand used above. * Sibling pages in this section: [Macro Basics](/14-macros/00-macro-basics/) (what macros are and are not, hygiene, when to use them), [Macro Patterns](/14-macros/02-macro-patterns/) (fragment specifiers and multiple rules), [Macro Repetition](/14-macros/03-repetition/) (the repetition operators and a `vec!`-style macro), and [Common Standard-Library Macros](/14-macros/08-common-macros/) (the standard-library macros). * For *procedural* macros — custom `#[derive]`, attribute, and function-like macros built with `syn` and `quote` — see [Procedural Macros](/14-macros/07-proc-macros/), [Derive Macros](/14-macros/04-derive-macros/), [Attribute Macros](/14-macros/05-attribute-macros/), and [Function-Like Procedural Macros](/14-macros/06-function-like-macros/). * Foundations referenced here: [output and the `println!` family](/02-basics/04-output/), [getting started](/01-getting-started/), [the introduction](/00-introduction/), and — for how derive macros power serialization with `serde` — [Serialization](/15-serialization/). ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A `triple!` macro [Section titled “Exercise 1: A triple! macro”](#exercise-1-a-triple-macro) **Difficulty:** Easy **Objective:** Write your first single-rule macro and confirm you understand that `:expr` fragments are atomic. **Instructions:** Define a macro `triple!` that takes one expression and produces three times its value. Verify that `triple!(4)` is `12` and that `triple!(2 + 1)` is `9` (not `7`), proving the fragment is treated as a unit. ```rust 1 macro_rules! triple { 2 // TODO: match one expression and multiply it by 3 3 } 4 5 fn main() { 6 assert_eq!(triple!(4), 12); 7 assert_eq!(triple!(2 + 1), 9); 8 println!("ok"); 9 } ``` Solution ```rust 1 macro_rules! triple { 2 ($x:expr) => { 3 ($x) * 3 4 }; 5 } 6 7 fn main() { 8 assert_eq!(triple!(4), 12); 9 assert_eq!(triple!(2 + 1), 9); // (2 + 1) * 3 == 9 10 println!("ok"); 11 } ``` The parentheses around `$x` are not strictly required here because `:expr` fragments are already atomic, but they make the precedence obvious to a reader. This compiles and prints `ok`. ### Exercise 2: A `max_of!` macro [Section titled “Exercise 2: A max\_of! macro”](#exercise-2-a-max_of-macro) **Difficulty:** Medium **Objective:** Practice matching two metavariables and generating an expression that uses both. **Instructions:** Define `max_of!(a, b)` that expands to an expression evaluating to the larger of the two values. It should work for any type that supports `>=`. Confirm `max_of!(3, 7) == 7` and `max_of!(10, -4) == 10`. ```rust 1 macro_rules! max_of { 2 // TODO: match two expressions; expand to the larger one 3 } 4 5 fn main() { 6 assert_eq!(max_of!(3, 7), 7); 7 assert_eq!(max_of!(10, -4), 10); 8 println!("ok"); 9 } ``` Solution ```rust 1 macro_rules! max_of { 2 ($a:expr, $b:expr) => { 3 if $a >= $b { $a } else { $b } 4 }; 5 } 6 7 fn main() { 8 assert_eq!(max_of!(3, 7), 7); 9 assert_eq!(max_of!(10, -4), 10); 10 println!("ok"); 11 } ``` This compiles and prints `ok`. Note that because `$a` and `$b` are substituted directly into both branches of the `if`, an argument with side effects would be evaluated more than once — a real consideration for macros (and a reason `std::cmp::max` exists as a function for the common case). ### Exercise 3: A `debug_vars!` macro using repetition and `stringify!` [Section titled “Exercise 3: A debug\_vars! macro using repetition and stringify!”](#exercise-3-a-debug_vars-macro-using-repetition-and-stringify) **Difficulty:** Hard **Objective:** Combine repetition with the built-in `stringify!` macro to print a variable number of variables as `name = value` lines. **Instructions:** Define `debug_vars!` that accepts a comma-separated list of identifiers (with an optional trailing comma) and, for each one, prints `name = value` where `value` uses debug formatting (`{:?}`). Each variable must already be in scope. Calling `debug_vars!(count, label, ratio)` should print one line per variable. ```rust 1 macro_rules! debug_vars { 2 // TODO: match zero-or-more identifiers, allow a trailing comma, 3 // and println! each as "name = value" 4 } 5 6 fn main() { 7 let count = 42; 8 let label = "active"; 9 let ratio = 0.75; 10 debug_vars!(count, label, ratio); 11 } ``` Solution ```rust 1 macro_rules! debug_vars { 2 ( $( $name:ident ),* $(,)? ) => { 3 $( 4 println!("{} = {:?}", stringify!($name), $name); 5 )* 6 }; 7 } 8 9 fn main() { 10 let count = 42; 11 let label = "active"; 12 let ratio = 0.75; 13 debug_vars!(count, label, ratio); 14 } ``` Output: ```plaintext 1 count = 42 2 label = "active" 3 ratio = 0.75 ``` The key trick is `stringify!($name)`, a built-in macro that turns the *identifier token* `count` into the string literal `"count"` at compile time. There is no runtime reflection involved. The `$( ... ),*` repetition matches the list, and the matching `$( println!(...); )*` emits one line per identifier. See [Common Standard-Library Macros](/14-macros/08-common-macros/) for `stringify!` and friends, and [Macro Repetition](/14-macros/03-repetition/) for more on the repetition operators. # Macro Patterns: Fragment Specifiers and Multiple Rules > Match meaningfully in macro_rules! with fragment specifiers like :expr, :ident, :ty, and :tt, plus multiple rules for shape-based overloading. Once you can write a basic `macro_rules!` macro, the next step is matching *meaningfully* on what the caller passed. This page is about the two tools that do the heavy lifting in `macro_rules!`: **fragment specifiers** (telling Rust *what kind* of syntax each captured piece is) and **multiple rules** (overload-like dispatch on the shape of the input). *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A `macro_rules!` macro is a set of pattern-matching rules over Rust **syntax**, not over runtime values. Each rule has a **matcher** (the pattern) and a **transcriber** (the code it expands to). Inside a matcher you capture pieces of input into **metavariables** like `$x`, and you must tell the compiler what *category* of syntax each one is using a **fragment specifier** such as `:expr`, `:ident`, `:ty`, `:pat`, or `:tt`. A single macro can hold several rules and tries them top-to-bottom, which gives you arity- and shape-based overloading that ordinary Rust functions cannot express. > **Note:** This page covers matchers in detail. For *what a macro is* (and is not — it is **not** a decorator or a function), see [Macro Basics](/14-macros/00-macro-basics/). For the `macro_rules!` syntax itself, see [Declarative Macros](/14-macros/01-declarative-macros/). For the `$(...)*` repetition operator that pairs with these specifiers, see [Repetition](/14-macros/03-repetition/). The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) TypeScript and JavaScript have **no compile-time macro system**. There is nothing that inspects your *syntax* and rewrites it before compilation. When a JS/TS developer wants “the same call to behave differently depending on its arguments,” they reach for one of three runtime tricks: variadic functions with `arguments`/rest params, runtime branching on `typeof`/`arguments.length`, or — the closest *syntactic* analog — **tagged template literals**. ```javascript 1 // macro-like-helpers.mjs — the JS toolbox that stands in for "macros" 2 3 // 1. Variadic + runtime branching on argument count/type. 4 // This is "overloading" but it happens at RUNTIME, with type checks. 5 function min(...nums) { 6 return nums.reduce((a, b) => (a < b ? a : b)); 7 } 8 9 // 2. A factory that builds a config value at RUNTIME. There is no static 10 // type attached to the result — TypeScript types are erased before this runs. 11 function makeConfig(key, fallback) { 12 const raw = process.env[key]; 13 const parsed = raw === undefined ? fallback : Number(raw); 14 return Number.isFinite(parsed) ? parsed : fallback; 15 } 16 17 // 3. A tagged template literal — the nearest JS thing to "macro-ish syntax". 18 // `strings` and `values` are pulled apart by the runtime, then recombined. 19 function sql(strings, ...values) { 20 return strings.reduce( 21 (acc, s, i) => acc + s + (i < values.length ? `$${i + 1}` : ""), 22 "", 23 ); 24 } 25 26 console.log("min =", min(8, 3, 5, 1, 9)); 27 console.log("port =", makeConfig("PORT", 8080)); 28 const table = "users", 29 id = 7; 30 console.log(sql`SELECT * FROM ${table} WHERE id = ${id}`); ``` Running this under Node v22 prints: ```text 1 min = 1 2 port = 8080 3 SELECT * FROM $1 WHERE id = $2 ``` Every one of these dispatches happens **while the program runs**. `min` re-checks `arguments` on each call; `makeConfig` parses strings at runtime; the `sql` tag receives already-evaluated values. By the time any of this executes, the TypeScript types are gone; generics are erased. A Rust macro does the *opposite*: it dispatches on syntax categories *before* the program is compiled, and produces real, type-checked code with zero runtime dispatch cost. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Here is a small request-router builder. It uses two **rules** (overloading on shape) and four different **fragment specifiers**: `:literal`, `:expr`, and `:ident`, plus the `stringify!` helper. ```rust 1 // A small request-routing macro showing several fragment specifiers and 2 // multiple rules selected by the SHAPE of the input. 3 macro_rules! route { 4 // Rule 1: a literal `GET` keyword, a string-literal path, then a handler expression. 5 (GET $path:literal => $handler:expr) => { 6 Route { method: "GET", path: $path, handler: $handler } 7 }; 8 // Rule 2: any method captured as an identifier (POST, PUT, DELETE, ...). 9 ($method:ident $path:literal => $handler:expr) => { 10 Route { method: stringify!($method), path: $path, handler: $handler } 11 }; 12 } 13 14 struct Route { 15 method: &'static str, 16 path: &'static str, 17 handler: fn() -> String, 18 } 19 20 fn list_users() -> String { "200 OK: users".to_string() } 21 fn create_user() -> String { "201 Created".to_string() } 22 23 fn main() { 24 let routes = [ 25 route!(GET "/users" => list_users), 26 route!(POST "/users" => create_user), 27 ]; 28 for r in &routes { 29 println!("{} {} -> {}", r.method, r.path, (r.handler)()); 30 } 31 } ``` Output: ```text 1 GET /users -> 200 OK: users 2 POST /users -> 201 Created ``` The compiler picks Rule 1 for `route!(GET ...)` because the bare token `GET` matches the literal `GET` in the first matcher. For `route!(POST ...)` the first rule fails (the token is not literally `GET`), so it falls through to Rule 2, which captures `POST` as an `:ident` and turns it into the string `"POST"` with `stringify!`. No runtime dispatch happens: by the time `main` runs, each `route!(...)` is already a plain `Route { .. }` struct literal. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Why specifiers exist at all [Section titled “Why specifiers exist at all”](#why-specifiers-exist-at-all) Rust parses your program into an abstract syntax tree. A macro matcher does not see characters — it sees a stream of **token trees**. When you write `$x` in a matcher, the compiler needs to know how much of the token stream to consume and how to validate it. That is the job of the fragment specifier after the colon: `$x:expr` says “parse one *expression* here,” `$name:ident` says “parse one *identifier* here,” and so on. This is fundamentally different from a C-style textual macro, which just pastes characters. A captured fragment is treated as a **single opaque syntax node** in the output. This is the property that makes `:expr` safe: ```rust 1 macro_rules! square_expr { 2 ($x:expr) => { $x * $x }; 3 } 4 5 fn main() { 6 // `2 + 3` is captured as ONE expression node, so this is (2+3)*(2+3) = 25, 7 // NOT 2 + 3 * 2 + 3 = 11 (which is what a C-style textual macro would give). 8 println!("square_expr!(2 + 3) = {}", square_expr!(2 + 3)); 9 } ``` Output: ```text 1 square_expr!(2 + 3) = 25 ``` Even better: a macro **invocation in expression position is itself a single node**. So when you embed a macro call inside a larger expression, the whole expansion is grouped: ```rust 1 macro_rules! add_expr { 2 ($x:expr) => { $x + 1 }; 3 } 4 5 fn main() { 6 // `add_expr!(2)` expands to the single node `(2 + 1)`, so this is 3 * 3 = 9, 7 // NOT the textual `3 * 2 + 1` = 7. 8 println!("{}", 3 * add_expr!(2)); 9 } ``` Output: ```text 1 9 ``` > **Tip:** Because `:expr` and macro-invocation-in-expression-position are atomic, you rarely need to add parentheses for the *captured* fragments. You still might choose to parenthesize the *whole transcriber* (`{ ($x * $x) }`) for defensive clarity, but the `9` above shows Rust already groups the invocation for you. ### The fragment specifiers you will actually use [Section titled “The fragment specifiers you will actually use”](#the-fragment-specifiers-you-will-actually-use) | Specifier | Captures | Example input | | ----------- | --------------------------------------- | -------------------------------- | | `:expr` | An expression | `2 + 3`, `foo()`, `vec![1]` | | `:ident` | An identifier or keyword | `count`, `String`, `GET` | | `:ty` | A type | `u32`, `Vec<String>`, `&str` | | `:pat` | A pattern (as in `match`/`let`) | `Some(x)`, `1..=10`, `_` | | `:literal` | A literal value | `42`, `"hi"`, `3.14`, `true` | | `:path` | A path | `std::cmp::max`, `Option::None` | | `:block` | A brace-delimited block | `{ let x = 1; x + 1 }` | | `:stmt` | A statement | `let x = 1`, `foo()` | | `:tt` | A single **token tree** (most flexible) | `+`, `foo`, `(a, b)`, `{ .. }` | | `:meta` | The contents of an attribute | `derive(Debug)`, `cfg(test)` | | `:vis` | A visibility qualifier (may be empty) | `pub`, `pub(crate)`, *(nothing)* | | `:lifetime` | A lifetime | `'a`, `'static` | | `:item` | A whole item | `fn f() {}`, `struct S;` | > **Note:** `:pat` in the 2021 and 2024 editions also matches *or-patterns* like `A | B`. The older, single-alternative form is available as `:pat_param` when you need to forbid top-level `|`. For everyday macros, `:pat` is what you want. Here are the most common ones exercised in one program: ```rust 1 use std::collections::HashMap; 2 3 // :ident + :ty + :expr together — declare a typed constant. 4 macro_rules! declare_const { 5 ($name:ident: $ty:ty = $value:expr) => { 6 const $name: $ty = $value; 7 }; 8 } 9 declare_const!(MAX_RETRIES: u32 = 5); 10 11 // :pat — build a `matches!`-style check. 12 macro_rules! is_some_of { 13 ($value:expr, $pat:pat) => { 14 matches!($value, Some($pat)) 15 }; 16 } 17 18 // :literal — only accepts literals, never variables or expressions. 19 macro_rules! describe_literal { 20 ($l:literal) => { format!("literal: {}", $l) }; 21 } 22 23 // :tt — captures any single token tree; used here to count tokens recursively. 24 macro_rules! count_tts { 25 () => { 0 }; 26 ($head:tt $($rest:tt)*) => { 1 + count_tts!($($rest)*) }; 27 } 28 29 // :block — captures a `{ ... }` block and runs it twice. 30 macro_rules! run_twice { 31 ($b:block) => {{ $b $b }}; 32 } 33 34 // :path — captures a path and calls it. 35 macro_rules! call_path { 36 ($p:path, $arg:expr) => { $p($arg) }; 37 } 38 39 fn double(n: i32) -> i32 { n * 2 } 40 41 fn main() { 42 println!("MAX_RETRIES = {}", MAX_RETRIES); 43 println!("is_some_of(Some(7), 1..=10) = {}", is_some_of!(Some(7i32), 1..=10)); 44 println!("{}", describe_literal!(42)); 45 println!("{}", describe_literal!("hi")); 46 println!("count_tts!(a b c) = {}", count_tts!(a b c)); 47 48 let mut counter = 0; 49 run_twice!({ counter += 1; }); 50 println!("counter after run_twice = {}", counter); 51 52 println!("call_path double(21) = {}", call_path!(double, 21)); 53 54 // Avoid an unused-variable warning by reading the HashMap import in scope. 55 let _seen: HashMap<&str, i32> = HashMap::new(); 56 } ``` Output: ```text 1 MAX_RETRIES = 5 2 is_some_of(Some(7), 1..=10) = true 3 literal: 42 4 literal: hi 5 count_tts!(a b c) = 3 6 counter after run_twice = 2 7 call_path double(21) = 42 ``` ### `:expr` vs `:tt` — the central trade-off [Section titled “:expr vs :tt — the central trade-off”](#expr-vs-tt--the-central-trade-off) `:expr` is **strict**: it parses and validates a full expression, and the result is opaque. `:tt` is **maximally permissive**: it grabs a single token tree (one token, or a balanced `(...)`/`[...]`/`{...}` group) without interpreting it. You reach for `:tt` when you need to: * accept syntax that does not fit a single fragment category (e.g. arbitrary tokens to forward elsewhere), * recurse over an unknown token stream (the `count_tts!` example above), or * forward tokens verbatim to another macro. The cost of `:tt` is that you lose the parser’s help: nothing checks that the tokens form a valid expression until the *expansion* is re-parsed. For anything that *is* an expression, prefer `:expr`. You get better error messages and grouping for free. ### Multiple rules: overloading by shape [Section titled “Multiple rules: overloading by shape”](#multiple-rules-overloading-by-shape) A `macro_rules!` macro is an ordered list of `(matcher) => { transcriber };` arms. The compiler tries them **top to bottom** and uses the **first** matcher that fits the entire input. This is how you emulate function overloading, something Rust functions cannot do: ```rust 1 macro_rules! greet { 2 () => { 3 String::from("Hello, world!") 4 }; 5 ($name:expr) => { 6 format!("Hello, {}!", $name) 7 }; 8 ($greeting:expr, $name:expr) => { 9 format!("{}, {}!", $greeting, $name) 10 }; 11 } 12 13 fn main() { 14 println!("{}", greet!()); 15 println!("{}", greet!("Ada")); 16 println!("{}", greet!("Hi there", "Ada")); 17 } ``` Output: ```text 1 Hello, world! 2 Hello, Ada! 3 Hi there, Ada! ``` Because order matters, put **more specific** rules first. In the `route!` example, the `GET` literal rule must come before the general `$method:ident` rule. If the `:ident` rule were first, it would happily capture `GET` as an identifier and the specific rule would never fire. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript | Rust `macro_rules!` | | --------------------- | ----------------------------------------------- | --------------------------------------------------- | | When dispatch happens | Runtime (`typeof`, `arguments.length`) | Compile time, on syntax categories | | What is matched | Runtime values | Token trees / syntax fragments | | ”Overloading” | Not real; one function body branches at runtime | Multiple rules, first match wins, zero runtime cost | | Type information | Erased before execution | Fully present; expansion is type-checked normally | | Grouping/precedence | N/A (values already evaluated) | Each `:expr` / invocation is one atomic node | | Closest syntactic kin | Tagged template literals | Fragment specifiers + matchers | | Failure mode | Throws at runtime, or silently wrong | Compile error before the program ever runs | **Unlike TypeScript**, where a “polymorphic” function inspects its arguments while running, a Rust macro has *already chosen* a rule and produced concrete code by the time compilation finishes. There is no `arguments` object, no runtime type check, and no per-call overhead. The macro is gone after expansion. **Unlike a JavaScript variadic function**, Rust macro rules can require *categories* of syntax. `declare_const!` literally cannot be called with `1 + 1` where it expects an `:ident`; the compiler rejects it. JavaScript would accept anything and fail (or misbehave) later. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: A fragment is followed by a disallowed token [Section titled “Pitfall 1: A fragment is followed by a disallowed token”](#pitfall-1-a-fragment-is-followed-by-a-disallowed-token) After certain fragment specifiers, only specific tokens may appear. In particular, an `:expr` fragment may only be followed by `=>`, `,`, or `;`. This **follow-set** rule prevents ambiguous parsing. Writing `[` after an `:expr` is a hard error: ```rust 1 macro_rules! bad_follow { 2 ($e:expr [ $i:expr ]) => { $e[$i] }; // does not compile 3 } 4 5 fn main() { 6 let arr = [10, 20, 30]; 7 println!("{}", bad_follow!(arr [1])); 8 } ``` The real compiler error: ```text 1 error: `$e:expr` is followed by `[`, which is not allowed for `expr` fragments 2 --> src/main.rs:2:14 3 | 4 2 | ($e:expr [ $i:expr ]) => { $e[$i] }; 5 | ^ not allowed after `expr` fragments 6 | 7 = note: allowed there are: `=>`, `,` or `;` ``` **Fix:** Capture the indexable thing as a `:tt` (or restructure the matcher to separate the pieces with an allowed delimiter such as a comma), then build the index expression in the transcriber. Here `:tt` accepts the single identifier `arr` and the parser is satisfied: ```rust 1 macro_rules! index { 2 ($container:tt [ $i:expr ]) => { $container[$i] }; 3 } 4 5 fn main() { 6 let arr = [10, 20, 30]; 7 println!("{}", index!(arr[1])); // prints 20 8 } ``` ### Pitfall 2: Passing the wrong category of syntax [Section titled “Pitfall 2: Passing the wrong category of syntax”](#pitfall-2-passing-the-wrong-category-of-syntax) If the caller hands a macro the wrong kind of token for a specifier, the matcher simply fails to match, and because there is no other rule, you get a “no rules expected this token” error that points at the metavariable it was trying to match: ```rust 1 macro_rules! declare_const { 2 ($name:ident: $ty:ty = $value:expr) => { 3 const $name: $ty = $value; 4 }; 5 } 6 7 fn main() { 8 declare_const!(1 + 1: u32 = 5); // does not compile: `1` is not an :ident 9 println!("done"); 10 } ``` The real compiler error: ```text 1 error: no rules expected `1` 2 --> src/main.rs:9:20 3 | 4 1 | macro_rules! declare_const { 5 | -------------------------- when calling this macro 6 ... 7 9 | declare_const!(1 + 1: u32 = 5); 8 | ^ no rules expected this token in macro call 9 | 10 note: while trying to match meta-variable `$name:ident` 11 --> src/main.rs:2:6 12 | 13 2 | ($name:ident: $ty:ty = $value:expr) => { ``` **Fix:** Pass an actual identifier: `declare_const!(MAX: u32 = 5);`. The `note:` line telling you *which metavariable* failed to match is your most useful clue when debugging a stubborn macro call. ### Pitfall 3: Rule order — the general rule shadows the specific one [Section titled “Pitfall 3: Rule order — the general rule shadows the specific one”](#pitfall-3-rule-order--the-general-rule-shadows-the-specific-one) The first matching rule wins, so a too-general rule placed first will swallow inputs you meant for a specific rule: ```rust 1 // BUG: the :ident rule is first, so `route!(GET ...)` never reaches the GET rule. 2 macro_rules! route { 3 ($method:ident $path:literal => $handler:expr) => { /* always taken */ "general" }; 4 (GET $path:literal => $handler:expr) => { "specific GET" }; // unreachable in practice 5 } ``` This usually compiles but quietly does the wrong thing (`route!(GET ...)` produces `"general"`). **Fix:** Order rules from most specific to least specific, exactly as in the working `route!` example above. ### Pitfall 4: A captured `:expr` re-used multiple times is evaluated multiple times [Section titled “Pitfall 4: A captured :expr re-used multiple times is evaluated multiple times”](#pitfall-4-a-captured-expr-re-used-multiple-times-is-evaluated-multiple-times) A metavariable substitutes the *syntax*, not a cached value. If you mention `$x` twice and the caller passes a side-effecting expression, it runs twice: ```rust 1 macro_rules! square { 2 ($x:expr) => { $x * $x }; 3 } 4 5 fn main() { 6 let mut calls = 0; 7 let mut next = || { calls += 1; 3 }; 8 let result = square!(next()); // expands to `next() * next()` 9 println!("result = {result}, calls = {calls}"); // result = 9, calls = 2 10 } ``` **Fix:** Bind once with a `let` inside a block-transcriber so the expression is evaluated a single time: ```rust 1 macro_rules! square { 2 ($x:expr) => {{ 3 let v = $x; 4 v * v 5 }}; 6 } ``` *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Choose the most specific specifier that fits.** Prefer `:expr`, `:ident`, `:ty`, or `:pat` over `:tt`. The stricter the specifier, the earlier and clearer the error the caller gets, and the better the grouping guarantees. * **Reserve `:tt` for forwarding and recursion.** Use it when you genuinely need raw, uninterpreted tokens, for example to count items or to pass a token stream on to another macro. * **Order rules specific → general.** Literal/keyword-anchored rules first, catch-all rules last, so the right arm fires. * **Evaluate side-effecting `:expr` arguments exactly once.** Bind them to a `let` in a `{{ ... }}` block before reusing them. * **Use `stringify!`, `concat!`, and `$crate` to keep expansions reliable.** `stringify!($x)` turns captured syntax into a string literal; `$crate` makes a macro callable from other crates without the caller needing your crate in scope. * **Reach for a function first.** A macro is the right tool only when you need to operate on *syntax* (variadic shapes, generating items, capturing identifiers/types). If a generic function would do, write the function; see [Generics and Traits](/09-generics-traits/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A common production need is reading typed configuration from environment variables with optional defaults — the Rust analog of the JavaScript `makeConfig` helper above, but type-checked at compile time. This macro uses `:ident`, `:ty`, `:literal`, and `:expr`, plus two rules (required vs. defaulted): ```rust 1 use std::collections::HashMap; 2 3 // Read a typed env var into a local binding. 4 // config_field!(name: Type = env "KEY"); // required 5 // config_field!(name: Type = env "KEY", default expr); // optional with default 6 macro_rules! config_field { 7 ($name:ident: $ty:ty = env $key:literal) => { 8 let $name: $ty = std::env::var($key) 9 .ok() 10 .and_then(|v| v.parse::<$ty>().ok()) 11 .unwrap_or_else(|| panic!("missing/invalid env var {}", $key)); 12 }; 13 ($name:ident: $ty:ty = env $key:literal, default $default:expr) => { 14 let $name: $ty = std::env::var($key) 15 .ok() 16 .and_then(|v| v.parse::<$ty>().ok()) 17 .unwrap_or($default); 18 }; 19 } 20 21 // A tiny map literal: zero pairs, or one `key => value` pair. 22 macro_rules! map { 23 () => { HashMap::new() }; 24 ($k:expr => $v:expr) => {{ 25 let mut m = HashMap::new(); 26 m.insert($k, $v); 27 m 28 }}; 29 } 30 31 fn main() { 32 // No env vars set here, so both fall back to their defaults. 33 config_field!(port: u16 = env "PORT", default 8080u16); 34 config_field!(workers: usize = env "WORKERS", default 4usize); 35 println!("port={port} workers={workers}"); 36 37 let single: HashMap<&str, i32> = map!("answer" => 42); 38 println!("single = {single:?}"); 39 let empty: HashMap<&str, i32> = map!(); 40 println!("empty = {empty:?}"); 41 } ``` Output: ```text 1 port=8080 workers=4 2 single = {"answer": 42} 3 empty = {} ``` The `config_field!` macro picks the second rule when a `default ...` clause is present and the first rule otherwise: a clean shape-based dispatch. Each invocation expands to an ordinary `let` binding with a known static type, so the rest of `main` type-checks exactly as if you had written the bindings by hand. The `map!` macro previews the repetition you will build out fully in [Repetition](/14-macros/03-repetition/) (a real `vec!`-style macro that takes *any* number of pairs). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [Macros by Example — The Rust Reference](https://doc.rust-lang.org/reference/macros-by-example.html): the authoritative list of fragment specifiers and follow-set rules * [The Rust Book: Macros](https://doc.rust-lang.org/book/ch20-05-macros.html) — gentle introduction with `vec!` worked out * [The Little Book of Rust Macros](https://veykril.github.io/tlborm/): the definitive community guide to `macro_rules!` patterns * [`stringify!`](https://doc.rust-lang.org/std/macro.stringify.html) and [`matches!`](https://doc.rust-lang.org/std/macro.matches.html) — std macros used on this page * Related sections in this guide: * [Macro Basics](/14-macros/00-macro-basics/): what macros are and are *not* (not decorators, not functions) * [Declarative Macros](/14-macros/01-declarative-macros/) — the `macro_rules!` syntax and a first example expanded * [Repetition](/14-macros/03-repetition/): the `$(...)*` / `$(...),*` operator that consumes these specifiers in bulk * [Common Macros](/14-macros/08-common-macros/) — `vec!`, `println!`, `matches!`, `assert!` and friends * [Procedural Macros](/14-macros/07-proc-macros/): when `macro_rules!` is not enough and you reach for `syn` + `quote` * [Function-like Macros](/14-macros/06-function-like-macros/) — procedural `foo!(...)` macros versus declarative ones * [Pattern Matching with `match`](/04-control-flow/02-match/): the `:pat` fragments you capture mirror real `match` patterns * [Generics and Traits](/09-generics-traits/) — prefer these when a function would do * [Serialization](/15-serialization/): `serde` leans on derive macros built from these same building blocks *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A variadic `min!` [Section titled “Exercise 1: A variadic min!”](#exercise-1-a-variadic-min) **Difficulty:** Easy **Objective:** Combine multiple rules with the `:expr` specifier and recursion. **Instructions:** 1. Write a macro `min!` that returns the smallest of its arguments. 2. It must accept a single expression (`min!(5)` returns `5`) and any number of comma-separated expressions (`min!(8, 3, 5, 1, 9)` returns `1`). 3. Accept an optional trailing comma. Use a recursive rule that peels off the first argument and calls `min!` on the rest. 4. Print `min!(8, 3, 5, 1, 9)`. Solution ```rust 1 macro_rules! min { 2 ($a:expr) => { $a }; 3 ($a:expr, $($rest:expr),+ $(,)?) => {{ 4 let a = $a; 5 let b = min!($($rest),+); 6 if a < b { a } else { b } 7 }}; 8 } 9 10 fn main() { 11 println!("min = {}", min!(8, 3, 5, 1, 9)); // min = 1 12 println!("single = {}", min!(42)); // single = 42 13 } ``` The first rule is the recursion base case (one expression). The second rule binds the head, recurses on the tail with the `$(...),+` repetition, and compares. The `$(,)?` allows a trailing comma. Output: `min = 1` then `single = 42`. ### Exercise 2: A `getter!` method generator [Section titled “Exercise 2: A getter! method generator”](#exercise-2-a-getter-method-generator) **Difficulty:** Medium **Objective:** Use the `:ident` and `:ty` specifiers together to generate code (a method), not just a value. **Instructions:** 1. Write a macro `getter!(field: Type)` that expands to a method named after `field` returning `&Type`, reading `self.field`. 2. Define `struct Account { owner: String, balance: u64 }`. 3. Inside `impl Account`, invoke `getter!` twice to generate `owner()` and `balance()` accessors. 4. Construct an `Account` and print both accessor results. Solution ```rust 1 macro_rules! getter { 2 ($field:ident : $ty:ty) => { 3 fn $field(&self) -> &$ty { 4 &self.$field 5 } 6 }; 7 } 8 9 struct Account { 10 owner: String, 11 balance: u64, 12 } 13 14 impl Account { 15 getter!(owner: String); 16 getter!(balance: u64); 17 } 18 19 fn main() { 20 let acc = Account { owner: String::from("Ada"), balance: 100 }; 21 println!("owner={} balance={}", acc.owner(), acc.balance()); 22 } ``` `$field:ident` becomes both the method name and the field name accessed via `self.$field`; `$ty` becomes the return type. Output: `owner=Ada balance=100`. ### Exercise 3: A `match_or!` expression [Section titled “Exercise 3: A match\_or! expression”](#exercise-3-a-match_or-expression) **Difficulty:** Medium-Hard **Objective:** Use the `:pat` specifier alongside `:expr` to build a control-flow construct. **Instructions:** 1. Write a macro `match_or!(value, PATTERN => RESULT, _ => DEFAULT)` that expands to a `match` returning `RESULT` when `value` matches `PATTERN` (binding any captured variables for use in `RESULT`), and `DEFAULT` otherwise. 2. Use it on `Some(42)` with the pattern `Some(n)` to produce `"got 42"`, and confirm `None` falls through to a default. Solution ```rust 1 macro_rules! match_or { 2 ($value:expr, $pat:pat => $result:expr, _ => $default:expr) => { 3 match $value { 4 $pat => $result, 5 _ => $default, 6 } 7 }; 8 } 9 10 fn main() { 11 let hit = match_or!(Some(42), Some(n) => format!("got {n}"), _ => "none".to_string()); 12 println!("{hit}"); 13 14 let miss: Option<i32> = None; 15 let label = match_or!(miss, Some(n) => format!("got {n}"), _ => "none".to_string()); 16 println!("{label}"); 17 } ``` The `$pat:pat` fragment captures `Some(n)` as a real pattern, so the binding `n` is in scope inside the `$result` expression. Output: `got 42` then `none`. # Macro Repetition: Building Variadic Macros > How macro_rules! repeats a chunk of code once per matched item, and how to use that to build your own vec!-style variadic macros. How `macro_rules!` repeats a chunk of code once per matched item, and how to use that to build your own `vec!`-style variadic macros. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Macro **repetition** is the feature that lets a single `macro_rules!` rule accept *any number* of arguments and emit one piece of code per argument. It is written `$( ... )sep rep`, where `sep` is an optional separator token (like `,` or `;`) and `rep` is `*`, `+`, or `?`. This is how the built-in `vec![1, 2, 3]` accepts a comma-separated list of any length, and it is the closest macro-level analog to TypeScript’s **rest parameters** (`...args`), except it happens entirely at compile time and generates real, monomorphized code rather than iterating over a runtime array. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript, “accept any number of arguments” is a runtime concept: you collect them into an array with a rest parameter and loop over that array. ```typescript 1 // A variadic builder: collect any number of items into an array of strings. 2 function makeList(...items: unknown[]): string[] { 3 const out: string[] = []; 4 for (const item of items) { 5 out.push(String(item)); 6 } 7 return out; 8 } 9 10 const names = makeList("Alice", "Bob", "Charlie"); 11 console.log(names); // [ 'Alice', 'Bob', 'Charlie' ] 12 13 // A nested example: a "grid" is a list of rows, each row a list of cells. 14 function grid(...rows: number[][]): number[][] { 15 return rows.map((row) => [...row]); 16 } 17 18 console.log(grid([1, 2, 3], [4, 5, 6])); // [ [ 1, 2, 3 ], [ 4, 5, 6 ] ] ``` The key traits to keep in mind: * `...items` is **runtime**: `items` is a real array that exists while the program runs. * The loop body runs once per element **at runtime**. * The arguments are all the same statically-known type (`unknown[]` here), and generics are erased: there is no per-call specialization. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) In Rust, the equivalent variadic behavior is resolved at **compile time** by a macro. The `$( ... ),*` syntax means “match a comma-separated list, and stamp out the body once per match.” ```rust 1 // A variadic builder macro: turn any number of expressions into a Vec<String>. 2 macro_rules! string_list { 3 // $( $x:expr ),* matches zero-or-more comma-separated expressions. 4 // $(,)? allows an optional trailing comma. 5 ( $( $x:expr ),* $(,)? ) => {{ 6 let mut out: Vec<String> = Vec::new(); 7 // The body inside $( ... )* is emitted once per matched $x. 8 $( 9 out.push($x.to_string()); 10 )* 11 out 12 }}; 13 } 14 15 fn main() { 16 let names = string_list!["Alice", "Bob", "Charlie"]; 17 println!("{:?}", names); // ["Alice", "Bob", "Charlie"] 18 19 // Trailing comma is fine: 20 let more = string_list!["x", "y",]; 21 println!("{:?}", more); // ["x", "y"] 22 23 // Zero items also works because we used `*` (zero-or-more): 24 let empty: Vec<String> = string_list![]; 25 println!("{:?}", empty); // [] 26 } ``` Running this prints: ```text 1 ["Alice", "Bob", "Charlie"] 2 ["x", "y"] 3 [] ``` > **Note:** Unlike the TypeScript version, no array of arguments ever exists at runtime. The macro **expands** at compile time into three literal `out.push(...)` statements before the compiler even type-checks the program. > **Tip:** The empty invocation `string_list![]` expands to a `let mut out` that is never pushed to, so it emits a benign `warning: variable does not need to be mutable` (the `unused_mut` lint). It is harmless here; a production macro would add a separate `() => { Vec::new() }` rule to handle the empty case cleanly. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Anatomy of a repetition [Section titled “Anatomy of a repetition”](#anatomy-of-a-repetition) A repetition has three parts: ```text 1 $( ... ) sep rep 2 ^^^^^^^ ^^^ ^^ 3 body separator (optional) repetition operator ``` * **`$( ... )`**: the *repeated fragment*. Whatever is inside is matched (in the matcher) or emitted (in the body) once per iteration. * **`sep`**: an *optional* single token that must appear *between* repetitions (commonly `,` or `;`). It does **not** appear after the last item. * **`rep`**: the repetition operator: | Operator | Meaning | TypeScript analog | | -------- | ------------ | ------------------------------------------ | | `*` | zero or more | `...args` where `args` may be empty | | `+` | one or more | a function requiring at least one argument | | `?` | zero or one | an optional parameter `arg?` | > **Note:** `?` is the *optional* operator and never takes a separator (there is at most one item, so there is nothing to separate). `*` and `+` may or may not have a separator. ### Matcher vs. transcriber [Section titled “Matcher vs. transcriber”](#matcher-vs-transcriber) Repetition appears in **two** places, and they must agree: ```rust 1 macro_rules! demo { 2 // v-- matcher: how we PARSE the input 3 ( $( $x:expr ),* ) => { 4 // v-- transcriber (body): what we EMIT, once per $x 5 vec![ $( $x * 2 ),* ] 6 }; 7 } 8 9 fn main() { 10 println!("{:?}", demo!(1, 2, 3)); // [2, 4, 6] 11 } ``` The compiler binds `$x` to each matched expression in the matcher, then walks the body’s `$( ... )*` once per binding, substituting that iteration’s `$x`. Because `$x` is named *inside* the repetition, you must also *use* it inside a repetition in the body; referencing `$x` outside any `$( ... )` is an error. ### The three separators in practice [Section titled “The three separators in practice”](#the-three-separators-in-practice) ```rust 1 fn main() { 2 // Comma-separated (the most common): 3 let a = comma_list!(1, 2, 3); 4 // Semicolon-separated: 5 let b = semi_list!(1; 2; 3); 6 // No separator at all (whitespace only) — valid but unusual: 7 let c = space_list!(1 2 3); 8 9 println!("{:?} {:?} {:?}", a, b, c); 10 } 11 12 macro_rules! comma_list { ( $( $x:expr ),* ) => { vec![ $( $x ),* ] }; } 13 macro_rules! semi_list { ( $( $x:expr );* ) => { vec![ $( $x ),* ] }; } 14 macro_rules! space_list { ( $( $x:expr )* ) => { vec![ $( $x ),* ] }; } ``` This prints: ```text 1 [1, 2, 3] [1, 2, 3] [1, 2, 3] ``` The separator in the **matcher** controls how callers must punctuate the input. The separator in the **body** (here always `,`) controls how the emitted output is punctuated; they are independent. ### Building a faithful `vec!` clone [Section titled “Building a faithful vec! clone”](#building-a-faithful-vec-clone) The real `vec!` macro has *two* rules: one for the list form `vec![a, b, c]` and one for the repeat form `vec![value; count]`. Here is a working re-implementation that mirrors how the standard library defines it: ```rust 1 macro_rules! myvec { 2 // Repeat form: [elem; count] 3 ( $elem:expr ; $count:expr ) => { 4 ::std::vec::from_elem($elem, $count) 5 }; 6 // List form: [a, b, c] with an optional trailing comma 7 ( $( $x:expr ),* $(,)? ) => { 8 <[_]>::into_vec(::std::boxed::Box::new([ $( $x ),* ])) 9 }; 10 } 11 12 fn main() { 13 let a = myvec![1, 2, 3]; 14 let b = myvec![0u8; 4]; 15 println!("a = {:?}", a); // a = [1, 2, 3] 16 println!("b = {:?}", b); // b = [0, 0, 0, 0] 17 } ``` Output: ```text 1 a = [1, 2, 3] 2 b = [0, 0, 0, 0] ``` A few things worth unpacking: * **Order of rules matters.** `macro_rules!` tries rules top to bottom. The repeat form (`$elem:expr ; $count:expr`) is listed first; if the input does not contain a `;`, that rule fails to match and Rust falls through to the list form. * **`::std::...` paths** make the macro reliable no matter what the caller has (or hasn’t) imported. This is good hygiene for a reusable macro, covered more in [Macro Basics](/14-macros/00-macro-basics/). * The list form expands `vec![1, 2, 3]` into `[1, 2, 3]` (an array), boxes it, and turns it into a `Vec`: exactly the strategy the standard library uses so the elements are placed directly into the allocation. ### Nested repetition [Section titled “Nested repetition”](#nested-repetition) Repetitions can nest, which is how you express “a list of lists.” Each `$( ... )` level corresponds to one level of grouping: ```rust 1 // A grid: rows separated by `;`, cells within a row separated by `,`. 2 macro_rules! grid { 3 ( $( $( $cell:expr ),+ );+ $(,)? ) => { 4 vec![ $( vec![ $( $cell ),+ ] ),+ ] 5 }; 6 } 7 8 fn main() { 9 let g = grid![ 10 1, 2, 3; 11 4, 5, 6; 12 7, 8, 9 13 ]; 14 println!("{:?}", g); 15 } ``` Output: ```text 1 [[1, 2, 3], [4, 5, 6], [7, 8, 9]] ``` The outer `$( ... );+` iterates over rows; the inner `$( $cell:expr ),+` iterates over cells within the row currently being expanded. Note both use `+` (one-or-more), so an empty grid or an empty row is rejected at compile time. ### Pairing two repetitions of the same length [Section titled “Pairing two repetitions of the same length”](#pairing-two-repetitions-of-the-same-length) When the body expands two metavariables together inside one `$( ... )`, Rust steps through them **in lockstep**: they must have the same number of items: ```rust 1 macro_rules! zip_print { 2 ( [ $( $a:expr ),* ] , [ $( $b:expr ),* ] ) => { 3 $( 4 println!("{} -> {}", $a, $b); 5 )* 6 }; 7 } 8 9 fn main() { 10 zip_print!(["a", "b", "c"], [1, 2, 3]); 11 } ``` Output: ```text 1 a -> 1 2 b -> 2 3 c -> 3 ``` This is the macro-level equivalent of zipping two arrays, but the “zip” happens at compile time, and a length mismatch is a *compile error*, not a runtime surprise (see [Common Pitfalls](#common-pitfalls)). *** ## Key Differences [Section titled “Key Differences”](#key-differences) ### Compile time vs. runtime [Section titled “Compile time vs. runtime”](#compile-time-vs-runtime) | Aspect | TypeScript `...args` | Rust `$( ... )*` repetition | | -------------- | ----------------------------------------- | ---------------------------------------------- | | When it runs | Runtime: builds a real array, loops | Compile time: stamps out code, no loop emitted | | Per-item cost | One loop iteration each call | Zero — the code is generated inline | | Argument types | All collected into one array type | Each `$x:expr` can be a *different* type | | Empty case | Empty array, fine | `*` allows empty; `+` rejects it at compile | | Wrong arity | Silent (extra args ignored / `undefined`) | Compile error | | Trailing comma | Allowed by the parser | Only if you write `$(,)?` explicitly | ### Each item can be a different type [Section titled “Each item can be a different type”](#each-item-can-be-a-different-type) Because the macro generates separate code for each item *before* type checking, a single call can mix types as long as the generated code type-checks. With `string_list!`, every `$x.to_string()` only requires that `$x` implement `Display`/`ToString`, so `&str`, `i32`, and `bool` can all appear in the same call. TypeScript’s rest parameter, by contrast, forces a single element type (or a union) on the whole array. ### `*` is not a runtime loop [Section titled “\* is not a runtime loop”](#-is-not-a-runtime-loop) This is the mental-model shift that trips up TypeScript developers most. `$( out.push($x); )*` is **not** a `for` loop. It is a *template* the compiler unrolls. `string_list!["a", "b", "c"]` literally becomes: ```rust 1 { 2 let mut out: Vec<String> = Vec::new(); 3 out.push("a".to_string()); 4 out.push("b".to_string()); 5 out.push("c".to_string()); 6 out 7 } ``` There is no iterator, no closure, and no array of arguments at runtime: just three statements. ### Counting items at compile time [Section titled “Counting items at compile time”](#counting-items-at-compile-time) There is no built-in “length of repetition” operator, but a common idiom expands each item into a `1usize` and sums them, letting you pre-size a `Vec`: ```rust 1 // Count metavariables by mapping each to `1usize` and summing. 2 macro_rules! count { 3 () => (0usize); 4 ( $head:expr $(, $tail:expr )* ) => (1usize + count!( $( $tail ),* )); 5 } 6 7 macro_rules! sized_vec { 8 ( $( $x:expr ),* $(,)? ) => {{ 9 let mut v = Vec::with_capacity(count!( $( $x ),* )); 10 $( v.push($x); )* 11 v 12 }}; 13 } 14 15 fn main() { 16 let v = sized_vec![10, 20, 30]; 17 println!("len={} cap={} {:?}", v.len(), v.capacity(), v); 18 } ``` Output: ```text 1 len=3 cap=3 [10, 20, 30] ``` The recursive `count!` is itself a small macro. Recursion is a standard `macro_rules!` technique, and the patterns behind it (the `:expr` fragment specifier, multiple rules) live in [Macro Patterns](/14-macros/02-macro-patterns/). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Mismatched repetition lengths [Section titled “Pitfall 1: Mismatched repetition lengths”](#pitfall-1-mismatched-repetition-lengths) When two metavariables are expanded together in one repetition, they must have equal counts. This does **not** compile: ```rust 1 macro_rules! zip_bad { 2 ( [ $( $a:expr ),* ] , [ $( $b:expr ),* ] ) => { 3 // does not compile: $a and $b expanded together but differ in length 4 $( println!("{} {}", $a, $b); )* 5 }; 6 } 7 8 fn main() { 9 zip_bad!(["a", "b"], [1, 2, 3]); 10 } ``` The compiler reports the exact mismatch: ```text 1 error: meta-variable `a` repeats 2 times, but `b` repeats 3 times 2 --> src/main.rs:4:10 3 | 4 4 | $( println!("{} {}", $a, $b); )* 5 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``` The fix is to ensure both lists carry the same number of items at the call site, or to expand them in separate `$( ... )` groups if they are genuinely independent. ### Pitfall 2: Using `+` then passing zero items [Section titled “Pitfall 2: Using + then passing zero items”](#pitfall-2-using--then-passing-zero-items) `+` means *one or more*. Calling such a macro with nothing produces a real error: ```rust 1 macro_rules! at_least_one { 2 ( $( $x:expr ),+ ) => { 3 vec![ $( $x ),+ ] 4 }; 5 } 6 7 fn main() { 8 let v: Vec<i32> = at_least_one![]; // does not compile 9 println!("{:?}", v); 10 } ``` The actual message: ```text 1 error: unexpected end of macro invocation 2 --> src/main.rs:8:23 3 | 4 1 | macro_rules! at_least_one { 5 | ------------------------- when calling this macro 6 ... 7 8 | let v: Vec<i32> = at_least_one![]; 8 | ^^^^^^^^^^^^^^^ missing tokens in macro arguments 9 | 10 note: while trying to match meta-variable `$x:expr` 11 --> src/main.rs:2:10 12 | 13 2 | ( $( $x:expr ),+ ) => { 14 | ^^^^^^^ ``` If an empty invocation should be legal, use `*` instead of `+`. ### Pitfall 3: Wrong separator at the call site [Section titled “Pitfall 3: Wrong separator at the call site”](#pitfall-3-wrong-separator-at-the-call-site) The matcher’s separator is mandatory and exact. A macro that matches commas will reject semicolons: ```rust 1 macro_rules! commas { 2 ( $( $x:expr ),* ) => { vec![ $( $x ),* ] }; 3 } 4 5 fn main() { 6 let v = commas!(1; 2; 3); // does not compile: wrong separator 7 println!("{:?}", v); 8 } ``` Real error: ```text 1 error: no rules expected `;` 2 --> src/main.rs:5:22 3 | 4 1 | macro_rules! commas { 5 | ------------------- when calling this macro 6 ... 7 5 | let v = commas!(1; 2; 3); // wrong separator 8 | ^ no rules expected this token in macro call 9 | 10 = note: while trying to match `,` ``` ### Pitfall 4: Forgetting the optional trailing comma [Section titled “Pitfall 4: Forgetting the optional trailing comma”](#pitfall-4-forgetting-the-optional-trailing-comma) Rust does **not** accept a trailing comma in a repetition unless you allow it. `string_list!["a", "b",]` only works because the matcher ends with `$(,)?`. Without that, the trailing comma is an unexpected token. Adding `$(,)?` after the repetition is cheap and matches what callers expect from `vec!`, so most production macros include it. ### Pitfall 5: Referencing a metavariable outside its repetition [Section titled “Pitfall 5: Referencing a metavariable outside its repetition”](#pitfall-5-referencing-a-metavariable-outside-its-repetition) If `$x` is bound *inside* `$( ... )`, you can only use it *inside* a matching `$( ... )` in the body. Writing `$x` at the top level produces an error like ``variable `x` is still repeating at this depth``. Keep the depth of use equal to the depth of binding. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Always support a trailing comma [Section titled “Always support a trailing comma”](#always-support-a-trailing-comma) Match `vec!`’s ergonomics by ending list-style matchers with `$(,)?`: ```rust 1 macro_rules! list { 2 ( $( $x:expr ),* $(,)? ) => { vec![ $( $x ),* ] }; 3 } ``` This makes multi-line invocations diff-friendly: adding a line never forces editing the previous line’s punctuation. ### Choose `*` vs. `+` by intent [Section titled “Choose \* vs. + by intent”](#choose--vs--by-intent) Use `*` when an empty invocation is meaningful (an empty collection). Use `+` only when “at least one” is a genuine requirement and an empty call should be a *compile error*, not a silent empty result. ### Prefer separators over no separator [Section titled “Prefer separators over no separator”](#prefer-separators-over-no-separator) Although `$( $x:expr )*` (whitespace-only) compiles, it reads poorly and is fragile. Real DSLs read far better with explicit `,` or `;` separators that match how a human would write the data. ### Use fully-qualified paths in reusable macros [Section titled “Use fully-qualified paths in reusable macros”](#use-fully-qualified-paths-in-reusable-macros) Macros are expanded wherever they are called, so they should not assume the caller imported anything. Write `::std::collections::HashMap` rather than `HashMap`, `::std::vec::Vec`, and so on. (Macro hygiene and path resolution are covered in [Macro Basics](/14-macros/00-macro-basics/).) ### Reach for a declarative macro only when a function won’t do [Section titled “Reach for a declarative macro only when a function won’t do”](#reach-for-a-declarative-macro-only-when-a-function-wont-do) Repetition macros shine for *variadic* construction and *literal* DSLs. If your arguments are uniform and runtime-known, a function taking a slice (`&[T]`) or an `IntoIterator` is simpler, easier to debug, and just as fast. Macros earn their keep when you need a different *number* or *kind* of arguments than a function signature allows. See [Macro Basics](/14-macros/00-macro-basics/) for the “when to reach for a macro” checklist. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A genuinely useful application of repetition is generating **table-driven tests**. In TypeScript you might loop over an array of cases inside a single `it.each(...)`. In Rust, a small macro can stamp out a *separate* `#[test]` function per row, so each case shows up individually in the test runner with its own name. ```rust 1 // A slug generator we want to test thoroughly. 2 fn slugify(s: &str) -> String { 3 s.trim() 4 .to_lowercase() 5 .chars() 6 .map(|c| if c.is_alphanumeric() { c } else { '-' }) 7 .collect::<String>() 8 .split('-') 9 .filter(|p| !p.is_empty()) 10 .collect::<Vec<_>>() 11 .join("-") 12 } 13 14 // Generate one #[test] fn per row: `name: input => expected`. 15 macro_rules! slug_tests { 16 ( $( $name:ident : $input:expr => $expected:expr ),+ $(,)? ) => { 17 $( 18 #[test] 19 fn $name() { 20 assert_eq!(slugify($input), $expected); 21 } 22 )+ 23 }; 24 } 25 26 slug_tests! { 27 basic: "Hello World" => "hello-world", 28 punctuation: "Rust & TypeScript!" => "rust-typescript", 29 trim_edges: " spaced out " => "spaced-out", 30 } 31 32 fn main() { 33 println!("{}", slugify("Hello, Reader!")); // hello-reader 34 } ``` Running `cargo test` produces three independently-named tests: ```text 1 running 3 tests 2 test basic ... ok 3 test punctuation ... ok 4 test trim_edges ... ok 5 6 test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` Why this is better than a runtime loop: * Each case is its own test, so a failure names exactly which row broke and the others still run. * The `name: input => expected` shape is a tiny DSL — `=>` is just a literal token the matcher consumes between two `$expr` fragments. * `$name:ident` binds an identifier used as a function name; `$( ... ),+ $(,)?` accepts one-or-more rows with an optional trailing comma. > **Tip:** This pattern is exactly what crates like `test-case` and `rstest` formalize. For everyday testing it is often enough to hand-roll a small macro like this. See [Testing](/13-testing/) for the broader testing toolkit. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Reference — Macros By Example (repetitions)](https://doc.rust-lang.org/reference/macros-by-example.html#repetitions) * [The Rust Book — Ch. 20.5: Macros](https://doc.rust-lang.org/book/ch20-05-macros.html) * [The Little Book of Rust Macros — Repetition](https://veykril.github.io/tlborm/decl-macros/macros-methodical.html#repetitions) * [`std::vec!` macro source and docs](https://doc.rust-lang.org/std/macro.vec.html) ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Macro Basics](/14-macros/00-macro-basics/) — what macros are (and are *not*), compile-time expansion, hygiene. * [Declarative Macros with `macro_rules!`](/14-macros/01-declarative-macros/) — `macro_rules!` fundamentals and `cargo expand`. * [Macro Patterns](/14-macros/02-macro-patterns/) — fragment specifiers (`:expr`, `:ident`, `:ty`, `:tt`) and multiple rules. * [Function-Like Procedural Macros](/14-macros/06-function-like-macros/) — invocation-style macros like `vec!` and `println!` and when to reach for them. * [Output and Formatting](/02-basics/04-output/) — `println!`/`format!`, your first taste of macro invocation syntax. * [Serialization](/15-serialization/) — `serde_json::json!` builds JSON with a similar repetition-based DSL. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1 [Section titled “Exercise 1”](#exercise-1) **Difficulty:** Easy **Objective:** Write a comma-separated repetition with a trailing comma. **Instructions:** Implement a macro `set!` that takes zero-or-more comma-separated expressions and builds a `std::collections::HashSet`, deduplicating values. Support an optional trailing comma. Calling `set![1, 2, 2, 3, 3, 3]` should yield a set containing `{1, 2, 3}`. ```rust 1 macro_rules! set { 2 // TODO: match zero-or-more comma-separated exprs with optional trailing comma, 3 // insert each into a HashSet. 4 } 5 6 fn main() { 7 let s = set![1, 2, 2, 3, 3, 3]; 8 let mut sorted: Vec<_> = s.into_iter().collect(); 9 sorted.sort(); 10 println!("{:?}", sorted); // [1, 2, 3] 11 } ``` Solution ```rust 1 macro_rules! set { 2 ( $( $x:expr ),* $(,)? ) => {{ 3 let mut s = ::std::collections::HashSet::new(); 4 $( s.insert($x); )* 5 s 6 }}; 7 } 8 9 fn main() { 10 let s = set![1, 2, 2, 3, 3, 3]; 11 let mut sorted: Vec<_> = s.into_iter().collect(); 12 sorted.sort(); 13 println!("{:?}", sorted); // [1, 2, 3] 14 } ``` The `$( ... ),*` matches the list, `$(,)?` permits the trailing comma, and the fully-qualified `::std::collections::HashSet` keeps the macro usable without an import. Running it prints `[1, 2, 3]`. ### Exercise 2 [Section titled “Exercise 2”](#exercise-2) **Difficulty:** Medium **Objective:** Use `=>` as a literal separator token inside a repetition to build a key/value DSL. **Instructions:** Implement a macro `hashmap!` that accepts entries written as `key => value`, comma-separated, with an optional trailing comma, and produces a `std::collections::HashMap`. Calling `hashmap!{ "alice" => 95, "bob" => 87 }` should build a map where `"alice"` maps to `95`. ```rust 1 macro_rules! hashmap { 2 // TODO: match `$key:expr => $val:expr` entries, comma-separated, optional trailing comma. 3 } 4 5 fn main() { 6 let scores = hashmap!{ "alice" => 95, "bob" => 87 }; 7 println!("{}", scores["alice"]); // 95 8 } ``` Solution ```rust 1 macro_rules! hashmap { 2 ( $( $key:expr => $val:expr ),* $(,)? ) => {{ 3 let mut map = ::std::collections::HashMap::new(); 4 $( map.insert($key, $val); )* 5 map 6 }}; 7 } 8 9 fn main() { 10 let scores = hashmap!{ "alice" => 95, "bob" => 87 }; 11 println!("{}", scores["alice"]); // 95 12 } ``` `=>` is not special here; it is simply a literal token the matcher requires between the two `$expr` fragments of each entry. The repetition then iterates over entries, emitting one `map.insert(key, val);` per pair. Running it prints `95`. ### Exercise 3 [Section titled “Exercise 3”](#exercise-3) **Difficulty:** Hard **Objective:** Combine nested repetition with the count idiom to build and pre-size a structure. **Instructions:** Implement a macro `matrix!` that takes rows separated by `;`, each row a `,`-separated list of `i32`, and returns a `Vec<Vec<i32>>` where each inner row is pre-allocated with the correct capacity. Use a `count!` helper macro to size each row’s `Vec`. Both rows and cells must require at least one element (`+`). Calling `matrix![1, 2, 3; 4, 5, 6]` should produce `[[1, 2, 3], [4, 5, 6]]`, and each inner `Vec` should have `capacity == 3`. ```rust 1 macro_rules! count { 2 // TODO: recursively count items, mapping each to 1usize. 3 } 4 5 macro_rules! matrix { 6 // TODO: nested repetition; use count! to pre-size each row. 7 } 8 9 fn main() { 10 let m = matrix![1, 2, 3; 4, 5, 6]; 11 println!("{:?}", m); 12 println!("row0 cap = {}", m[0].capacity()); // 3 13 } ``` Solution ```rust 1 macro_rules! count { 2 () => (0usize); 3 ( $head:expr $(, $tail:expr )* ) => (1usize + count!( $( $tail ),* )); 4 } 5 6 macro_rules! matrix { 7 ( $( $( $cell:expr ),+ );+ $(,)? ) => { 8 vec![ 9 $( 10 { 11 let mut row = Vec::with_capacity(count!( $( $cell ),+ )); 12 $( row.push($cell); )+ 13 row 14 } 15 ),+ 16 ] 17 }; 18 } 19 20 fn main() { 21 let m = matrix![1, 2, 3; 4, 5, 6]; 22 println!("{:?}", m); // [[1, 2, 3], [4, 5, 6]] 23 println!("row0 cap = {}", m[0].capacity()); // 3 24 } ``` The outer `$( ... );+` iterates over rows, the inner `$( $cell:expr ),+` iterates over cells. Inside each row’s block, `count!( $( $cell ),+ )` recounts just *that* row’s cells (the inner repetition expands per-row), so `Vec::with_capacity` is sized exactly. Running it prints `[[1, 2, 3], [4, 5, 6]]` followed by `row0 cap = 3`. # Derive Macros > #[derive(...)] generates trait impls at compile time: Debug, Clone, PartialEq, Hash, Default and serde, replacing the per-type helpers you hand-write in TypeScript. The `#[derive(...)]` attribute tells the compiler to **generate trait implementations for you** at compile time. Instead of hand-writing equality, cloning, debug-printing, or hashing for every struct and enum, you list the traits you want and Rust writes the boilerplate. This is the single most common macro a TypeScript/JavaScript developer will meet on day one of writing Rust. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **derive macro** is a procedural macro that reads your `struct` or `enum` definition and emits a complete `impl` block for a trait. The result is real, monomorphized code with **zero runtime cost**: the same as if you had typed the implementation yourself. For a TypeScript/JavaScript developer, `#[derive(Clone)]` is roughly “the compiler generates `structuredClone` for this exact shape,” and `#[derive(PartialEq)]` is “the compiler generates a correct deep-equality function” — except both are checked and specialized at compile time, not improvised at runtime. > **Note:** `#[derive(...)]` is **not** a decorator. It does not wrap or modify your type at runtime; it generates *additional* code (trait impls) alongside your definition. See [Macro Basics](/14-macros/00-macro-basics/) for why “macro ≈ decorator” is a misleading analogy. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript/JavaScript, the behaviors that Rust derives correspond to things you either get for free, write by hand, or reach for a helper to do. ```typescript 1 // TypeScript/JavaScript: behaviors you implement or improvise per type 2 3 interface User { 4 id: number; 5 name: string; 6 active: boolean; 7 } 8 9 const alice: User = { id: 1, name: "Alice", active: true }; 10 11 // "Debug printing" — console.log understands object shapes already: 12 console.log(alice); // { id: 1, name: 'Alice', active: true } 13 14 // "Cloning" — you must pick a strategy; structuredClone is the modern deep copy: 15 const bob = structuredClone(alice); 16 17 // "Equality" — === is reference identity for objects, so you hand-roll it: 18 function usersEqual(a: User, b: User): boolean { 19 return a.id === b.id && a.name === b.name && a.active === b.active; 20 } 21 console.log(alice === bob); // false (different references!) 22 console.log(usersEqual(alice, bob)); // true (manual structural compare) 23 24 // "Default value" — there is no language-level default; you write a factory: 25 function defaultUser(): User { 26 return { id: 0, name: "", active: false }; 27 } 28 29 // "Hashing for use as a key" — objects can't be Map/Set keys by value, 30 // so people serialize to a string key: 31 const seen = new Set<string>(); 32 seen.add(JSON.stringify(alice)); ``` Notice the pattern: each capability (printing, copying, comparing, defaulting, keying) is either built into the runtime in a loose, dynamic way, or you write a one-off function per type. Nothing ties these helpers to the `User` shape — if you add a field, `usersEqual` silently goes stale. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) In Rust you declare the capabilities you want in one line, and the compiler generates correct, shape-aware implementations that **cannot go stale**: add a field and the generated code updates automatically. ```rust 1 use std::collections::HashSet; 2 3 #[derive(Debug, Clone, PartialEq, Eq, Hash, Default)] 4 struct User { 5 id: u32, 6 name: String, 7 active: bool, 8 } 9 10 fn main() { 11 let alice = User { 12 id: 1, 13 name: String::from("Alice"), 14 active: true, 15 }; 16 17 // Debug: {:?} compact, {:#?} pretty-printed 18 println!("{alice:?}"); 19 println!("{alice:#?}"); 20 21 // Clone: an explicit, independent deep copy 22 let bob = alice.clone(); 23 println!("clone equal? {}", alice == bob); 24 25 // PartialEq / Eq: structural comparison, field by field 26 let carol = User { id: 2, name: String::from("Carol"), active: false }; 27 println!("alice == carol? {}", alice == carol); 28 29 // Default: every field takes its own type's default 30 let blank = User::default(); 31 println!("{blank:?}"); 32 33 // Hash + Eq: the type can be a HashSet / HashMap key by value 34 let mut set = HashSet::new(); 35 set.insert(alice.clone()); 36 set.insert(bob); // equal to alice -> not stored twice 37 set.insert(carol); 38 println!("unique users: {}", set.len()); 39 } ``` Real output from `cargo run`: ```text 1 User { id: 1, name: "Alice", active: true } 2 User { 3 id: 1, 4 name: "Alice", 5 active: true, 6 } 7 clone equal? true 8 alice == carol? false 9 User { id: 0, name: "", active: false } 10 unique users: 2 ``` One `#[derive(...)]` line replaced the debug formatter, the deep-clone, the equality function, the default factory, and the hashing-for-keys logic from the TypeScript version, and the compiler keeps them all in sync with the struct’s fields. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What “derive” literally does [Section titled “What “derive” literally does”](#what-derive-literally-does) When the compiler sees `#[derive(Clone)]` above a type, it runs the `Clone` derive macro. That macro receives the **tokens** of your type definition and produces an `impl` block. Conceptually, `#[derive(Clone)]` on `User` expands to something like this, which you could also write by hand: ```rust 1 // This is (approximately) what #[derive(Clone)] generates for you. 2 struct User { 3 id: u32, 4 name: String, 5 active: bool, 6 } 7 8 impl Clone for User { 9 fn clone(&self) -> Self { 10 User { 11 id: self.id.clone(), 12 name: self.name.clone(), 13 active: self.active.clone(), 14 } 15 } 16 } 17 18 fn main() { 19 let a = User { id: 1, name: "A".into(), active: true }; 20 let b = a.clone(); 21 println!("{}", b.id); 22 } ``` The derive simply clones each field in turn. To see the *exact* expansion for any derive, install the `cargo-expand` tool (`cargo install cargo-expand`) and run `cargo expand`; it prints your crate with all macros — including derives — fully expanded. [Declarative Macros with `macro_rules!`](/14-macros/01-declarative-macros/) covers `cargo expand` in more depth. > **Tip:** Because the generated code is ordinary `impl` blocks, there is no hidden runtime machinery, no reflection, and no per-call overhead. Rust monomorphizes generic code, so a derived `Clone` for `User` is as fast as one you wrote by hand. This contrasts with TypeScript generics, which are **erased** at runtime. ### The most common standard-library derives [Section titled “The most common standard-library derives”](#the-most-common-standard-library-derives) | Trait | What the generated impl gives you | Closest TypeScript/JavaScript analogy | | -------------------- | --------------------------------------------------- | ------------------------------------------ | | `Debug` | `{:?}` / `{:#?}` formatting for logs and tests | `console.log(obj)` printing the shape | | `Clone` | An explicit deep `.clone()` | `structuredClone(obj)` | | `Copy` | Implicit bitwise copy on assignment (no `.clone()`) | primitive value-copy semantics | | `PartialEq` / `Eq` | `==` and `!=` by structural comparison | a hand-written `deepEqual(a, b)` | | `PartialOrd` / `Ord` | `<`, `>`, `.sort()`, `.max()` | a hand-written comparator for `Array.sort` | | `Hash` | Use as a `HashMap` / `HashSet` key | a stable key for a `Map` / `Set` | | `Default` | A `T::default()` constructor | a `defaultX()` factory function | These are detailed below. (`Serialize` / `Deserialize` are *not* in this list because they come from the `serde` crate, not std — see [Custom derive overview](#custom-derive-overview).) ### `Debug` [Section titled “Debug”](#debug) `Debug` powers the `{:?}` and `{:#?}` format specifiers, which is what you use in `println!`, `dbg!`, and test assertions. The plain `{:?}` is compact; `{:#?}` is multi-line and indented. Almost every type you define should derive `Debug`; it costs nothing and makes debugging and test failures readable. ### `Clone` and `Copy` [Section titled “Clone and Copy”](#clone-and-copy) `Clone` gives you an explicit `.clone()` method that produces an independent copy. It is opt-in and visible precisely because copying can be expensive (cloning a `String` allocates new heap memory). `Copy` is a *marker* for types that are cheap to duplicate by copying their bytes — like `i32` or a small `struct` of integers. When a type is `Copy`, assigning or passing it makes a copy automatically instead of moving it (ownership and moves are covered in [05-ownership](/05-ownership/)). A type can only be `Copy` if **all of its fields are `Copy`**, and `Copy` always requires `Clone`. ```rust 1 // Copy: every field is Copy, so the whole struct can be Copy. 2 #[derive(Debug, Clone, Copy, PartialEq)] 3 struct Point { 4 x: i32, 5 y: i32, 6 } 7 8 // Ordering derives compare fields in declaration order (lexicographic). 9 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] 10 struct Version { 11 major: u32, 12 minor: u32, 13 patch: u32, 14 } 15 16 // Derives work on enums too. Unit-variant order = discriminant order. 17 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] 18 enum Priority { 19 Low, // discriminant 0 -> smallest 20 Medium, // 1 21 High, // 2 -> largest 22 } 23 24 fn main() { 25 let a = Point { x: 1, y: 2 }; 26 let b = a; // Copy: `a` is NOT moved, still usable below 27 println!("{a:?} {b:?}"); 28 29 let mut versions = vec![ 30 Version { major: 1, minor: 2, patch: 0 }, 31 Version { major: 1, minor: 0, patch: 5 }, 32 Version { major: 2, minor: 0, patch: 0 }, 33 ]; 34 versions.sort(); // uses the derived Ord 35 println!("{versions:?}"); 36 37 println!("Low < High? {}", Priority::Low < Priority::High); 38 let mut ps = vec![Priority::High, Priority::Low, Priority::Medium]; 39 ps.sort(); 40 println!("{ps:?}"); 41 } ``` Real output: ```text 1 Point { x: 1, y: 2 } Point { x: 1, y: 2 } 2 [Version { major: 1, minor: 0, patch: 5 }, Version { major: 1, minor: 2, patch: 0 }, Version { major: 2, minor: 0, patch: 0 }] 3 Low < High? true 4 [Low, Medium, High] ``` ### `PartialEq`, `Eq`, `PartialOrd`, `Ord` [Section titled “PartialEq, Eq, PartialOrd, Ord”](#partialeq-eq-partialord-ord) `PartialEq` generates `==`/`!=` as a field-by-field structural comparison. `Eq` is a marker that adds the promise “equality is reflexive” (every value equals itself). Floats are deliberately **not** `Eq` because `NaN != NaN`, which is why a struct containing an `f64` can derive `PartialEq` but not `Eq`. `PartialOrd` and `Ord` generate comparison operators and enable `.sort()`, `.min()`, `.max()`, and ordered collections like `BTreeMap`. As shown above, the derived ordering is **lexicographic by field declaration order** for structs, and by **variant declaration order** for enums. ### `Hash` [Section titled “Hash”](#hash) `Hash` lets a value be used as a key in a `HashMap` or `HashSet`. There is a contract: if `a == b` then `a` and `b` must hash to the same value. Because of that contract, a type used as a hash key should derive both `Hash` and `Eq` together; the standard library bounds `HashMap`/`HashSet` keys on both. ### `Default` [Section titled “Default”](#default) `Default` generates a `T::default()` constructor. For a struct, each field is set to its own type’s default (`0` for integers, `false` for `bool`, `""` for `String`, an empty `Vec`, and so on). Combined with **struct update syntax** (`..Default::default()`), this gives you concise “set a few fields, default the rest” construction: the idiomatic Rust answer to optional fields in a TypeScript object literal. ```rust 1 // `Default` on an enum needs one unit variant marked #[default]. 2 #[derive(Debug, Default, PartialEq)] 3 enum Status { 4 #[default] 5 Pending, 6 Active, 7 Closed, 8 } 9 10 #[derive(Debug, Default)] 11 struct Settings { 12 retries: u32, 13 verbose: bool, 14 label: String, 15 status: Status, 16 } 17 18 fn main() { 19 println!("{:?}", Status::default()); 20 // Set one field, default the rest via struct update syntax: 21 let s = Settings { retries: 3, ..Default::default() }; 22 println!("{s:?}"); 23 println!("settings status is Pending? {}", s.status == Status::Pending); 24 } ``` Real output: ```text 1 Pending 2 Settings { retries: 3, verbose: false, label: "", status: Pending } 3 settings status is Pending? true ``` ### Custom derive overview [Section titled “Custom derive overview”](#custom-derive-overview) `#[derive(...)]` is not limited to standard-library traits. Library authors can write their own **custom derive macros** (also called *procedural derive macros*), and you import and use them exactly like the built-in ones. The most famous example is `serde`: deriving `Serialize` and `Deserialize` generates all the code needed to turn your type into JSON (or many other formats) and back. ```toml 1 # Cargo.toml — enable serde's derive feature plus a JSON backend 2 [dependencies] 3 serde = { version = "1", features = ["derive"] } 4 serde_json = "1" ``` You can add both with `cargo add serde --features derive` and `cargo add serde_json` (no extra plugin needed — `cargo add` is built into Cargo). ```rust 1 use serde::{Serialize, Deserialize}; 2 3 // Serialize / Deserialize are CUSTOM derive macros from the serde crate, 4 // not std derives. They generate (de)serialization code for this exact shape. 5 #[derive(Debug, Serialize, Deserialize, PartialEq)] 6 struct Config { 7 host: String, 8 port: u16, 9 #[serde(default)] // a "helper attribute" the derive understands 10 verbose: bool, 11 } 12 13 fn main() -> Result<(), Box<dyn std::error::Error>> { 14 let cfg = Config { host: "localhost".into(), port: 8080, verbose: true }; 15 16 let json = serde_json::to_string(&cfg)?; 17 println!("{json}"); 18 19 // `verbose` is absent in the input -> #[serde(default)] fills it in. 20 let parsed: Config = serde_json::from_str(r#"{"host":"example.com","port":443}"#)?; 21 println!("{parsed:?}"); 22 Ok(()) 23 } ``` Real output (verified with serde 1.0.228 and serde\_json 1.0.150): ```text 1 {"host":"localhost","port":8080,"verbose":true} 2 Config { host: "example.com", port: 443, verbose: false } ``` Two things to notice. First, a custom derive can define **helper attributes** like `#[serde(default)]` that further configure the generated code; these are only valid inside a type that derives the matching macro. Second, from the *user’s* side a custom derive looks identical to a std one: list it in `#[derive(...)]` and the code appears. *Writing* such a macro is a separate skill, covered in [Procedural Macros](/14-macros/07-proc-macros/) (the `syn` 2 + `quote` toolchain). Serialization itself is the subject of [15-serialization](/15-serialization/). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concern | TypeScript/JavaScript | Rust `#[derive(...)]` | | ------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------- | | Printing a value | `console.log` reads the live object shape at runtime | `#[derive(Debug)]` generates a formatter at compile time | | Copying | `structuredClone` (deep) or spread (shallow), chosen per call | `#[derive(Clone)]` generates `.clone()`; `Copy` for cheap implicit copies | | Equality | `===` is reference identity; structural equality is hand-rolled | `#[derive(PartialEq)]` generates correct structural `==` | | Sorting | pass a comparator to `Array.prototype.sort` | `#[derive(Ord)]` enables `.sort()` directly | | Using as a map key | objects coerce to keys oddly; people `JSON.stringify` | `#[derive(Hash, Eq)]` makes the type a real key by value | | Defaults | a hand-written factory function | `#[derive(Default)]` generates `T::default()` | | When it runs | at runtime, dynamically, per value | at compile time, once, generating specialized code | | Staleness | helpers drift out of sync as fields change | generated code always matches the current fields | The deepest conceptual difference: in TypeScript/JavaScript these behaviors are **runtime conveniences** that operate on whatever object you hand them. In Rust they are **compile-time code generation** tied to a specific type. If your type can’t legitimately support a behavior — say, comparing a field that has no notion of equality — the program **does not compile**, rather than misbehaving at runtime. > **Note:** Derive only works on `struct` and `enum` definitions you control. You cannot `#[derive(...)]` for a type defined in another crate — that runs into Rust’s coherence (“orphan”) rules, discussed in [09-generics-traits](/09-generics-traits/). For external types you write a manual `impl` or use the newtype pattern. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Deriving `Copy` on a type with a heap field [Section titled “Pitfall 1: Deriving Copy on a type with a heap field”](#pitfall-1-deriving-copy-on-a-type-with-a-heap-field) `Copy` requires every field to be `Copy`. `String` owns a heap allocation and is not `Copy`, so this fails. ```rust 1 #[derive(Clone, Copy)] // does not compile (error[E0204]) 2 struct Wrapper { 3 name: String, 4 } 5 6 fn main() { 7 let _ = Wrapper { name: String::from("x") }; 8 } ``` Real compiler error: ```text 1 error[E0204]: the trait `Copy` cannot be implemented for this type 2 --> src/main.rs:1:17 3 | 4 1 | #[derive(Clone, Copy)] 5 | ^^^^ 6 2 | struct Wrapper { 7 3 | name: String, 8 | ------------ this field does not implement `Copy` 9 10 For more information about this error, try `rustc --explain E0204`. ``` **Fix:** drop `Copy` and keep `Clone`. Use explicit `.clone()` when you need a copy. Reserve `Copy` for small, all-`Copy` types like `Point { x: i32, y: i32 }`. ### Pitfall 2: Deriving a trait whose requirement a field doesn’t meet [Section titled “Pitfall 2: Deriving a trait whose requirement a field doesn’t meet”](#pitfall-2-deriving-a-trait-whose-requirement-a-field-doesnt-meet) A derived trait is only valid if every field also implements it. Deriving `PartialEq` on a struct whose field type isn’t comparable fails, and the error points at the field, not the derive name. ```rust 1 struct NotComparable; 2 3 #[derive(PartialEq)] // does not compile (error[E0369]) 4 struct Holder { 5 inner: NotComparable, 6 } 7 8 fn main() {} ``` Real compiler error (abridged): ```text 1 error[E0369]: binary operation `==` cannot be applied to type `NotComparable` 2 --> src/main.rs:5:5 3 | 4 3 | #[derive(PartialEq)] 5 | --------- in this derive macro expansion 6 4 | struct Holder { 7 5 | inner: NotComparable, 8 | ^^^^^^^^^^^^^^^^^^^^ 9 ... 10 help: consider annotating `NotComparable` with `#[derive(PartialEq)]` ``` **Fix:** derive (or implement) the trait on the inner type too, as the compiler suggests. ### Pitfall 3: Deriving a trait *and* implementing it by hand [Section titled “Pitfall 3: Deriving a trait and implementing it by hand”](#pitfall-3-deriving-a-trait-and-implementing-it-by-hand) If you both `#[derive(PartialEq)]` and write `impl PartialEq`, you have declared the trait twice: a conflicting implementation. ```rust 1 #[derive(PartialEq)] // does not compile (error[E0119]): conflicts with the manual impl below 2 struct Celsius(f64); 3 4 impl PartialEq for Celsius { 5 fn eq(&self, other: &Self) -> bool { 6 (self.0 - other.0).abs() < 0.001 7 } 8 } 9 10 fn main() {} ``` Real compiler error (abridged): ```text 1 error[E0119]: conflicting implementations of trait `PartialEq` for type `Celsius` 2 --> src/main.rs:1:10 3 | 4 1 | #[derive(PartialEq)] 5 | ^^^^^^^^^ conflicting implementation for `Celsius` 6 ... 7 4 | impl PartialEq for Celsius { 8 | -------------------------- first implementation here ``` **Fix:** pick one. If you need custom logic (like the tolerance-based equality above), remove that trait from `#[derive(...)]` and keep only your manual `impl`. ### Pitfall 4: Forgetting to derive `Debug` before logging or asserting [Section titled “Pitfall 4: Forgetting to derive Debug before logging or asserting”](#pitfall-4-forgetting-to-derive-debug-before-logging-or-asserting) `{:?}`, `dbg!`, and `assert_eq!` all require `Debug`. A type without it can’t be printed that way. ```rust 1 struct User { 2 id: u32, 3 } 4 5 fn main() { 6 let u = User { id: 1 }; 7 println!("{u:?}"); // does not compile (error[E0277]): User doesn't implement Debug 8 } ``` Real compiler error (abridged): ```text 1 error[E0277]: `User` doesn't implement `Debug` 2 --> src/main.rs:7:16 3 | 4 7 | println!("{u:?}"); 5 | -^--- 6 | || 7 | |`User` cannot be formatted using `{:?}` because it doesn't implement `Debug` 8 ... 9 help: consider annotating `User` with `#[derive(Debug)]` ``` **Fix:** add `#[derive(Debug)]`. Note `assert_eq!` needs both `Debug` (to print the mismatch) and `PartialEq` (to compare) — see [13-testing](/13-testing/). ### Pitfall 5: The “derive adds a `T:` bound” surprise on generics [Section titled “Pitfall 5: The “derive adds a T: bound” surprise on generics”](#pitfall-5-the-derive-adds-a-t-bound-surprise-on-generics) For a generic type, a derive generates a *conditional* impl: `#[derive(Clone)] struct Pair<T>` produces `impl<T: Clone> Clone for Pair<T>`. So `Pair<T>` is `Clone` **only when `T` is `Clone`**, which is usually what you want, but the error appears at the call site, not the definition. ```rust 1 #[derive(Clone)] 2 struct Pair<T> { 3 first: T, 4 second: T, 5 } 6 7 struct NotClone; 8 9 fn main() { 10 let ints = Pair { first: 1, second: 2 }; 11 let _copy = ints.clone(); // i32 is Clone -> fine 12 13 let stuck = Pair { first: NotClone, second: NotClone }; 14 let _bad = stuck.clone(); // does not compile (error[E0599]): NotClone is not Clone 15 } ``` Real compiler error (abridged): ```text 1 error[E0599]: the method `clone` exists for struct `Pair<NotClone>`, but its trait bounds were not satisfied 2 --> src/main.rs:16:22 3 | 4 4 | struct Pair<T> { 5 | -------------- method `clone` not found for this struct because it doesn't satisfy `Pair<NotClone>: Clone` 6 ... 7 note: trait bound `NotClone: Clone` was not satisfied 8 --> src/main.rs:3:10 9 | 10 3 | #[derive(Clone)] 11 | ^^^^^ unsatisfied trait bound introduced in this `derive` macro ``` **Fix:** make the inner type `Clone` too, or, if the type parameter shouldn’t need the bound (a `PhantomData<T>` marker is the classic case), write a manual `impl` without it. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Default every type to `#[derive(Debug)]`.** It is free, aids debugging, and is required by `assert_eq!`. Many teams treat a missing `Debug` as a code-smell. * **Derive the common quartet when it makes sense:** `#[derive(Debug, Clone, PartialEq, Eq)]` is a sensible baseline for plain data types. Add `Hash` when the value will be a map/set key, `PartialOrd, Ord` when it needs sorting, and `Default` when “empty/zero” is meaningful. * **Prefer derive over hand-written impls** for these traits. The generated code is correct by construction and stays in sync as you add fields. Reserve manual impls for genuinely custom semantics (like tolerance-based float equality). * **Don’t derive `Copy` reflexively.** Add it only to small, all-`Copy` value types. If a struct grows a `String` or `Vec` later, a previously-`Copy` type stops being `Copy` and downstream code may break, so add `Copy` deliberately. * **Keep `Eq` and `Hash` together** for keys, and remember floats can’t be `Eq`. If a struct contains an `f64`, it can derive `PartialEq` but not `Eq`/`Hash`. * **Use `Default` + struct update syntax** (`Foo { a, ..Default::default() }`) instead of writing constructors that just fill in zeros. It is the idiomatic substitute for optional object fields. * The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the **2024 edition**; `cargo new` selects the newest edition automatically. All derives shown here are stable across recent editions. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small banking/domain model that leans on derives the way production code does: an `enum` used as a `HashMap` key, a money type that sorts, and an account record that has a meaningful default and is cloned for snapshots. ```rust 1 use std::collections::HashMap; 2 3 // Eq + Hash -> usable as a HashMap key by value. 4 #[derive(Debug, Clone, PartialEq, Eq, Hash)] 5 enum Currency { 6 Usd, 7 Eur, 8 Gbp, 9 } 10 11 // Ord -> sortable amounts (store money as integer cents, never floats). 12 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] 13 struct Money { 14 cents: u64, 15 } 16 17 // Default -> an "empty" account; Clone -> cheap snapshots; PartialEq -> change detection. 18 #[derive(Debug, Clone, PartialEq, Default)] 19 struct Account { 20 id: u32, 21 owner: String, 22 balance_cents: u64, 23 } 24 25 fn main() { 26 // Currency as a HashMap key: 27 let mut rates: HashMap<Currency, f64> = HashMap::new(); 28 rates.insert(Currency::Usd, 1.0); 29 rates.insert(Currency::Eur, 1.08); 30 rates.insert(Currency::Gbp, 1.27); 31 println!("EUR rate: {}", rates[&Currency::Eur]); 32 33 // Sorting money via the derived Ord: 34 let mut amounts = vec![ 35 Money { cents: 999 }, 36 Money { cents: 50 }, 37 Money { cents: 1200 }, 38 ]; 39 amounts.sort(); 40 println!("{amounts:?}"); 41 42 // Default + struct update syntax for construction: 43 let base = Account::default(); 44 let acct = Account { id: 7, owner: "Dana".into(), ..base.clone() }; 45 println!("{acct:?}"); 46 println!("base unchanged: {base:?}"); 47 48 // Clone for an independent snapshot, PartialEq to detect changes: 49 let mut snapshot = acct.clone(); 50 snapshot.balance_cents = 5000; 51 println!("changed snapshot? {}", snapshot != acct); 52 } ``` Real output: ```text 1 EUR rate: 1.08 2 [Money { cents: 50 }, Money { cents: 999 }, Money { cents: 1200 }] 3 Account { id: 7, owner: "Dana", balance_cents: 0 } 4 base unchanged: Account { id: 0, owner: "", balance_cents: 0 } 5 changed snapshot? true ``` Every capability here — keying a map, sorting, defaulting, cloning, comparing — came from one-line `#[derive(...)]` declarations, and all of it is checked and specialized at compile time. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Rust Book — Derivable Traits (Appendix C)](https://doc.rust-lang.org/book/appendix-03-derivable-traits.html) * [Rust Reference — Derive macros](https://doc.rust-lang.org/reference/attributes/derive.html) * [`std::default::Default`](https://doc.rust-lang.org/std/default/trait.Default.html), [`std::cmp::PartialEq`](https://doc.rust-lang.org/std/cmp/trait.PartialEq.html), [`std::fmt::Debug`](https://doc.rust-lang.org/std/fmt/trait.Debug.html) * [`cargo-expand`](https://github.com/dtolnay/cargo-expand) — see what a derive generates * [serde — derive macros](https://serde.rs/derive.html) ### Related sections in this guide [Section titled “Related sections in this guide”](#related-sections-in-this-guide) * [Macro Basics](/14-macros/00-macro-basics/): why a macro is **not** a decorator or a function * [Declarative Macros with `macro_rules!`](/14-macros/01-declarative-macros/): `macro_rules!` and inspecting expansions with `cargo expand` * [Attribute Macros](/14-macros/05-attribute-macros/): the other procedural-macro form * [Function-Like Procedural Macros](/14-macros/06-function-like-macros/): `foo!(...)` procedural macros * [Procedural Macros](/14-macros/07-proc-macros/): **writing** a custom derive with `syn` 2 + `quote` * [Common Standard-Library Macros](/14-macros/08-common-macros/): std macros like `assert_eq!` (which needs `Debug` + `PartialEq`) * [09-generics-traits](/09-generics-traits/): traits, bounds, and the orphan rule * [05-ownership](/05-ownership/): moves vs. `Clone` vs. `Copy` * [13-testing](/13-testing/): `assert_eq!` and the `Debug` requirement * [15-serialization](/15-serialization/): `serde`’s `Serialize` / `Deserialize` derives in depth *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1 [Section titled “Exercise 1”](#exercise-1) **Difficulty:** Beginner **Objective:** Pick the right derives so a type can be printed, copied, and compared. **Instructions:** Add the correct `#[derive(...)]` line to `Temperature` so that the `main` below compiles and prints whether two clones are equal. The struct holds an `f64`, so think about which equality trait is and isn’t available. ```rust 1 struct Temperature { 2 celsius: f64, 3 } 4 5 fn main() { 6 let a = Temperature { celsius: 20.0 }; 7 let b = a.clone(); 8 println!("{a:?} == {b:?}? {}", a == b); 9 } ``` Solution `f64` is `PartialEq` but not `Eq` (because of `NaN`), so derive `PartialEq` — not `Eq`. You also need `Debug` for `{:?}` and `Clone` for `.clone()`. ```rust 1 #[derive(Debug, Clone, PartialEq)] 2 struct Temperature { 3 celsius: f64, 4 } 5 6 fn main() { 7 let a = Temperature { celsius: 20.0 }; 8 let b = a.clone(); 9 println!("{a:?} == {b:?}? {}", a == b); 10 } ``` Output: ```text 1 Temperature { celsius: 20.0 } == Temperature { celsius: 20.0 }? true ``` ### Exercise 2 [Section titled “Exercise 2”](#exercise-2) **Difficulty:** Intermediate **Objective:** Understand what a derive generates by writing the equivalent impl by hand. **Instructions:** `PointManual` below deliberately does **not** derive `PartialEq`. Write the `impl PartialEq for PointManual` block by hand so that `p == q` works and matches what `#[derive(PartialEq)]` would have produced (field-by-field comparison). Keep `#[derive(Debug)]`. ```rust 1 #[derive(Debug)] 2 struct PointManual { 3 x: i32, 4 y: i32, 5 } 6 7 // TODO: impl PartialEq for PointManual { ... } 8 9 fn main() { 10 let p = PointManual { x: 1, y: 2 }; 11 let q = PointManual { x: 1, y: 2 }; 12 println!("{}", p == q); // should print true 13 } ``` Solution The derived `PartialEq` compares every field with `==` and combines them with `&&`. Writing it by hand makes the generated code concrete: ```rust 1 #[derive(Debug)] 2 struct PointManual { 3 x: i32, 4 y: i32, 5 } 6 7 impl PartialEq for PointManual { 8 fn eq(&self, other: &Self) -> bool { 9 self.x == other.x && self.y == other.y 10 } 11 } 12 13 fn main() { 14 let p = PointManual { x: 1, y: 2 }; 15 let q = PointManual { x: 1, y: 2 }; 16 println!("{}", p == q); // true 17 } ``` Output: ```text 1 true ``` In real code you would simply add `PartialEq` to the derive list — this exercise just shows there is no magic: the derive writes exactly this. ### Exercise 3 [Section titled “Exercise 3”](#exercise-3) **Difficulty:** Intermediate **Objective:** Combine `Default` with struct update syntax to build a “set a few fields, default the rest” configuration. **Instructions:** Add derives to `ServerConfig` so that `Default::default()` works, then construct a value that sets only `host` and `port` and defaults the remaining fields. Print the result with `{:?}`. ```rust 1 struct ServerConfig { 2 host: String, 3 port: u16, 4 max_conns: u32, 5 tls: bool, 6 } 7 8 fn main() { 9 let cfg = /* TODO: host "0.0.0.0", port 8080, defaults for the rest */; 10 println!("{cfg:?}"); 11 } ``` Solution Derive `Default` (and `Debug` to print it). Then use `..Default::default()` to fill in `max_conns` and `tls`: ```rust 1 #[derive(Debug, Default)] 2 struct ServerConfig { 3 host: String, 4 port: u16, 5 max_conns: u32, 6 tls: bool, 7 } 8 9 fn main() { 10 let cfg = ServerConfig { 11 host: "0.0.0.0".into(), 12 port: 8080, 13 ..Default::default() 14 }; 15 println!("{cfg:?}"); 16 } ``` Output: ```text 1 ServerConfig { host: "0.0.0.0", port: 8080, max_conns: 0, tls: false } ``` This is the idiomatic Rust counterpart to a partially-specified object literal in TypeScript — concise, and the compiler guarantees every field has a value. # Attribute Macros > Rust's #[attribute] macros echo TypeScript decorators, but rewrite a function or struct's source at compile time, with zero runtime cost, using syn and quote. If you have ever written `@Component`, `@Injectable`, or a custom method decorator in TypeScript, you already know the *shape* of an **attribute macro**: a name you attach above a declaration that transforms or augments it. Rust’s `#[attribute]` syntax looks almost identical, but it runs at compile time and rewrites your code into entirely new source before the compiler ever type-checks it. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) An **attribute macro** is a kind of **procedural macro** that you place *in front of* an item (usually a function, but also a struct, module, or `impl` block) to inspect and rewrite that item. The annotated item is handed to your macro as a stream of tokens, and whatever tokens you return *replace* it. Frameworks use this for things like `#[tokio::main]`, web routes (`#[get("/users")]`), and test harnesses (`#[test]`). This page covers the *concept* and a minimal, hand-written example; the mechanics of the `proc-macro` crate, `syn`, and `quote` are covered in depth in [Procedural Macros](/14-macros/07-proc-macros/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) The closest TypeScript analogue is a **decorator**. Here is a standard (TC39 stage-3) method decorator that wraps a method so it logs when it is entered and how long it took, a pattern you have probably seen in logging or tracing libraries. It works in TypeScript 5.x and runs on Node v22 after compilation. deco.ts ```typescript 1 // Standard (TC39 stage-3) decorators, supported in TypeScript 5.x and Node v22. 2 function logCalls<This, Args extends unknown[], Return>( 3 target: (this: This, ...args: Args) => Return, 4 context: ClassMethodDecoratorContext, 5 ) { 6 const name = String(context.name); 7 // The decorator REPLACES the method with this wrapper at runtime. 8 return function (this: This, ...args: Args): Return { 9 console.log(`-> entering ${name}`); 10 const start = performance.now(); 11 const result = target.call(this, ...args); 12 console.log(`<- leaving ${name} after ${(performance.now() - start).toFixed(3)}ms`); 13 return result; 14 }; 15 } 16 17 class OrderService { 18 @logCalls 19 orderTotal(itemCents: number, qty: number): number { 20 return itemCents * qty + 500; // items plus a flat $5.00 shipping fee 21 } 22 } 23 24 const svc = new OrderService(); 25 console.log("total =", svc.orderTotal(1299, 3)); ``` Compiling with `tsc --target ES2022 deco.ts` and running `node deco.js` prints: ```text 1 -> entering orderTotal 2 <- leaving orderTotal after 0.007ms 3 total = 4397 ``` The decorator runs **at runtime**: every time `orderTotal` is invoked, the wrapper function executes. The original method is still a real value being passed around and called through `target.call(...)`. There is per-call indirection, and the wrapping happens while your program is running. > **Note:** A TypeScript decorator is a *runtime* function that receives the thing it decorates as a value. A Rust attribute macro is a *compile-time* function that receives the thing it annotates as **source code (tokens)** and emits new source code. This difference drives almost everything else on this page. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) In Rust, the same “log on entry and exit” behavior is an attribute macro named `log_calls`. Attribute macros must live in their own crate of type `proc-macro`, so this is a two-crate setup: a macro crate that defines the attribute, and an application crate that uses it. The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically. The macro crate (`log_attr/Cargo.toml`) must opt in to being a proc-macro crate and depends on `syn` and `quote`: log\_attr/Cargo.toml ```toml 1 [package] 2 name = "log_attr" 3 version = "0.1.0" 4 edition = "2024" 5 6 [lib] 7 proc-macro = true # REQUIRED — this is what makes #[proc_macro_attribute] legal 8 9 [dependencies] 10 syn = { version = "2", features = ["full"] } 11 quote = "1" 12 proc-macro2 = "1" ``` The macro itself (`log_attr/src/lib.rs`) parses the annotated function, then re-emits it with a wrapped body: log\_attr/src/lib.rs ```rust 1 use proc_macro::TokenStream; 2 use quote::quote; 3 use syn::{parse_macro_input, ItemFn}; 4 5 /// An attribute macro that wraps a function so it logs when it is entered 6 /// and when it returns, including how long the body took. 7 #[proc_macro_attribute] 8 pub fn log_calls(_attr: TokenStream, item: TokenStream) -> TokenStream { 9 // Parse the annotated item as a complete function definition. 10 let input = parse_macro_input!(item as ItemFn); 11 12 // Pull apart the pieces of the original function. 13 let vis = &input.vis; // pub / pub(crate) / (nothing) 14 let sig = &input.sig; // fn name(args) -> Ret 15 let block = &input.block; // the original { ... } body 16 let name = &sig.ident; // just the function name, e.g. `order_total` 17 18 // Re-emit the function with the same signature, but a new body that 19 // wraps the original block with logging on either side. 20 let expanded = quote! { 21 #vis #sig { 22 println!("-> entering `{}`", stringify!(#name)); 23 let __started = std::time::Instant::now(); 24 let __result = (|| #block)(); 25 println!("<- leaving `{}` after {:?}", stringify!(#name), __started.elapsed()); 26 __result 27 } 28 }; 29 30 expanded.into() 31 } ``` The application crate (`app/Cargo.toml`) depends on the macro crate by path: app/Cargo.toml ```toml 1 [package] 2 name = "app" 3 version = "0.1.0" 4 edition = "2024" 5 6 [dependencies] 7 log_attr = { path = "../log_attr" } ``` And uses the attribute exactly like a decorator; you place it above the function: app/src/main.rs ```rust 1 use log_attr::log_calls; 2 3 /// Compute the total price in cents, including a flat $5.00 shipping fee. 4 #[log_calls] 5 fn order_total(item_cents: u32, qty: u32) -> u32 { 6 let shipping = 500; 7 item_cents * qty + shipping 8 } 9 10 #[log_calls] 11 fn greet(name: &str) { 12 println!("Hello, {name}!"); 13 } 14 15 fn main() { 16 let total = order_total(1299, 3); 17 println!("total = {total} cents"); 18 greet("Ada"); 19 } ``` Running `cargo run -p app` prints: ```text 1 -> entering `order_total` 2 <- leaving `order_total` after 42ns 3 total = 4397 cents 4 -> entering `greet` 5 Hello, Ada! 6 <- leaving `greet` after 500ns ``` > **Note:** Notice `log_calls` works on *both* `order_total` (returns a `u32`) and `greet` (returns `()`), with no generics or trait bounds. That is because the macro never sees types; it manipulates tokens. The wrapped body just forwards whatever the original returned. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The attribute macro signature [Section titled “The attribute macro signature”](#the-attribute-macro-signature) Every attribute macro has the exact same signature: ```rust 1 // Signature shape — both parameters are token streams, the return is tokens. 2 #[proc_macro_attribute] 3 pub fn log_calls(_attr: TokenStream, item: TokenStream) -> TokenStream { /* ... */ } ``` * `attr` is the tokens *inside the parentheses of the attribute itself*. For `#[log_calls]` it is empty; for `#[get("/users")]` it would be the tokens `"/users"`. * `item` is the tokens of *the thing the attribute is attached to*: here, the entire `fn order_total(...) { ... }`. * The returned `TokenStream` **completely replaces** the original item. If you return `item` unchanged, the function is untouched. If you return nothing, the function disappears. This is fundamentally different from a TypeScript decorator, which receives the method as a callable *value* and returns a replacement *value* at runtime. ### Parsing with `syn` [Section titled “Parsing with syn”](#parsing-with-syn) `parse_macro_input!(item as ItemFn)` turns the raw token stream into a structured syntax tree. `ItemFn` is `syn`’s representation of a free function, exposing fields like `.vis` (visibility), `.sig` (the signature: name, generics, parameters, return type), and `.block` (the body). Working with this tree is far safer than string manipulation: you get the real Rust grammar, not a regex. ### Generating with `quote` [Section titled “Generating with quote”](#generating-with-quote) The `quote! { ... }` macro is the inverse of parsing: it builds a new token stream from a template. Inside it, `#vis`, `#sig`, `#block`, and `#name` **interpolate** the pieces we extracted (the `#` is `quote`’s splice operator, unrelated to a comment). So we reconstruct the original function header, then write a brand-new body. A few details in the generated body matter: * `stringify!(#name)` turns the identifier into a string literal *at compile time*, so the log shows the function’s actual name. * `let __result = (|| #block)();` wraps the original body in an immediately-invoked closure. This lets the body `return` early without skipping the “leaving” log, and gives us a single value to log around. (For functions that themselves return early, this preserves correct control flow.) * The underscore-prefixed names (`__started`, `__result`) are an intentional, low-collision choice. Rust’s macro hygiene handles most identifier clashes, but `#[proc_macro_attribute]` macros are *less* hygienic than `macro_rules!` for identifiers that appear in the user’s body, so distinctive names are a sensible habit. Hygiene is covered in [Macro Basics](/14-macros/00-macro-basics/). ### Seeing the expansion [Section titled “Seeing the expansion”](#seeing-the-expansion) You never have to imagine what an attribute macro produces. The `cargo expand` tool (install with `cargo install cargo-expand`) prints your code *after* macro expansion. For the `order_total` example above, `cargo expand --bin app` shows the rewritten function: ```rust 1 // Output of `cargo expand` (lightly trimmed): the macro replaced the function body. 2 fn order_total(item_cents: u32, qty: u32) -> u32 { 3 { 4 ::std::io::_print(format_args!("-> entering `{0}`\n", "order_total")); 5 }; 6 let __started = std::time::Instant::now(); 7 let __result = (|| { item_cents * qty + 500 })(); 8 { 9 ::std::io::_print( 10 format_args!( 11 "<- leaving `{0}` after {1:?}\n", 12 "order_total", 13 __started.elapsed(), 14 ), 15 ); 16 }; 17 __result 18 } ``` This is the key insight: by the time the program runs, there *is no macro*, only ordinary, fully-monomorphized Rust. There is no decorator object, no per-call lookup, no wrapper allocation. The cost is paid once, during compilation. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | TypeScript decorator | Rust attribute macro | | ----------------- | ----------------------------------------------------------- | ---------------------------------------------------- | | When it runs | At **runtime** (and once at class-definition time) | At **compile time**, before type-checking the result | | What it receives | The decorated value (a function/class) and a context object | The annotated item as **tokens** (source code) | | What it returns | A replacement value, or `void` | A `TokenStream` that **replaces** the item’s source | | Runtime cost | Wrapper indirection on every call | Zero — the generated code *is* the code | | Where it can live | Any module | A dedicated `proc-macro = true` crate | | Can read types? | Yes, via reflection/metadata at runtime | No — it sees syntax only, never resolved types | | Failure mode | Throws at runtime | Emits a **compiler error**; program never builds | The mental-model shift for a TypeScript developer: a decorator is *a function that wraps a value*; an attribute macro is *a program that writes a program*. Because the macro emits plain source code that the compiler then checks normally, a mistake in your generated code surfaces as an ordinary type error pointing into the expanded code, not a runtime exception. > **Tip:** The three flavors of procedural macro are attribute macros (`#[name]`, this page), [derive macros](/14-macros/04-derive-macros/) (`#[derive(Name)]`), and [function-like macros](/14-macros/06-function-like-macros/) (`name!(...)`). They share the same `proc-macro` crate plumbing but differ in how they are triggered. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting `proc-macro = true` [Section titled “Pitfall 1: Forgetting proc-macro = true”](#pitfall-1-forgetting-proc-macro--true) Attribute macros are only legal in a crate that declares itself a proc-macro crate. Leave out the `[lib] proc-macro = true` line and the compiler rejects the attribute: ```rust 1 // log_attr/src/lib.rs — in a crate WITHOUT `proc-macro = true` in Cargo.toml 2 use proc_macro::TokenStream; 3 4 #[proc_macro_attribute] // does not compile 5 pub fn noop(_attr: TokenStream, item: TokenStream) -> TokenStream { 6 item 7 } ``` The real error from `cargo build`: ```text 1 error: the `#[proc_macro_attribute]` attribute is only usable with crates of the `proc-macro` crate type 2 --> src/lib.rs:3:1 3 | 4 3 | #[proc_macro_attribute] 5 | ^^^^^^^^^^^^^^^^^^^^^^^ ``` The fix is the `[lib] proc-macro = true` stanza shown in the Rust Equivalent section. ### Pitfall 2: Applying the attribute to the wrong kind of item [Section titled “Pitfall 2: Applying the attribute to the wrong kind of item”](#pitfall-2-applying-the-attribute-to-the-wrong-kind-of-item) Our macro parses its input `as ItemFn`. If you put `#[log_calls]` on a struct instead of a function, `parse_macro_input!` cannot match the `fn` grammar and produces a precise error: app/src/main.rs ```rust 1 use log_attr::log_calls; 2 3 #[log_calls] // does not compile — log_calls expects a function, not a struct 4 struct Order { 5 total: u32, 6 } ``` The real error from `cargo build`: ```text 1 error: expected `fn` 2 --> app2/src/main.rs:4:1 3 | 4 4 | struct Order { 5 | ^^^^^^ ``` > **Warning:** Coming from TypeScript, it is tempting to assume an attribute “just adds metadata” and is harmless anywhere. It is not: an attribute macro *replaces* the item, so it must understand what it was given. A well-written macro either accepts multiple item kinds or fails with a clear message. ### Pitfall 3: Expecting the macro to inspect types [Section titled “Pitfall 3: Expecting the macro to inspect types”](#pitfall-3-expecting-the-macro-to-inspect-types) A decorator in TypeScript can read parameter types via `reflect-metadata` at runtime. An attribute macro cannot. Inside `log_calls`, `input.sig` knows the parameter is *written* as `u32`, but it has no idea whether `u32` is an alias, what trait it implements, or whether it equals some other type. That information does not exist yet at macro-expansion time. If your design needs resolved type information, an attribute macro is the wrong tool; consider generics and traits (see [Generics & Traits](/09-generics-traits/)) instead. ### Pitfall 4: Generating code that does not compile [Section titled “Pitfall 4: Generating code that does not compile”](#pitfall-4-generating-code-that-does-not-compile) Because the macro emits source, a bug in your template becomes a compiler error *in the expanded code*. If you forget to handle the function’s return value and drop `__result`, the wrapped function silently changes its return type to `()` and every caller fails to type-check. Run `cargo expand` whenever the error message is confusing; it shows you the exact code the compiler is complaining about. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Reach for an attribute macro only when simpler tools fall short.** A higher-order function, a generic wrapper, or a `macro_rules!` ([Declarative Macros](/14-macros/01-declarative-macros/)) is far less machinery. Attribute macros shine when you must *rewrite a declaration’s shape* — adding fields, generating sibling functions, registering routes — which ordinary code cannot do. * **Parse into the most specific `syn` type you support.** `ItemFn` for functions, `ItemStruct` for structs, or `syn::Item` if you genuinely accept several kinds and want to branch. Specific types give better error messages. * **Preserve everything you do not intend to change.** Re-emit the original visibility, generics, where-clauses, and attributes. The simplest faithful pattern is to interpolate the *whole* parsed item (`#input`) and only *add* around it, rather than reconstructing it field by field. * **Emit real `compile_error!` diagnostics for misuse.** Returning `syn::Error::new_spanned(item, "message").to_compile_error()` points the error at the user’s code with a message you control, much friendlier than a parse failure. This is detailed in [Procedural Macros](/14-macros/07-proc-macros/). * **Keep the generated code minimal and predictable.** Smaller expansions compile faster and are easier to debug with `cargo expand`. * **Pin `syn` with the `full` feature** when you parse function bodies or full items; the default feature set does not include the full grammar. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) Web frameworks like Actix and Rocket let you annotate a handler with its HTTP route. Here is a minimal version of that idea: a `#[get("/path")]` attribute that keeps your handler intact *and* generates a sibling function describing where it is mounted. This demonstrates an attribute macro that **reads its own arguments** (the path literal): the `attr` parameter we ignored earlier. The macro (added to `log_attr/src/lib.rs`): log\_attr/src/lib.rs ```rust 1 use proc_macro::TokenStream; 2 use quote::quote; 3 use syn::{parse_macro_input, ItemFn, LitStr}; 4 5 /// A route-style attribute that takes a path literal, e.g. `#[get("/users")]`. 6 /// It keeps the original handler unchanged and generates a sibling function 7 /// `<name>_route()` returning the (method, path) the handler is mounted at. 8 #[proc_macro_attribute] 9 pub fn get(attr: TokenStream, item: TokenStream) -> TokenStream { 10 // The attribute's OWN tokens: parse them as a string literal. 11 let path = parse_macro_input!(attr as LitStr); 12 let input = parse_macro_input!(item as ItemFn); 13 14 let name = &input.sig.ident; 15 // Build a new identifier `<name>_route` for the generated helper. 16 let route_fn = quote::format_ident!("{}_route", name); 17 18 let expanded = quote! { 19 // Emit the original handler unchanged... 20 #input 21 22 // ...plus a generated helper describing its mount point. 23 pub fn #route_fn() -> (&'static str, &'static str) { 24 ("GET", #path) 25 } 26 }; 27 28 expanded.into() 29 } ``` The handler in the application crate: app/src/main.rs ```rust 1 use log_attr::get; 2 3 #[get("/users")] 4 fn list_users() -> String { 5 "[\"ada\", \"linus\"]".to_string() 6 } 7 8 fn main() { 9 // `list_users` still exists and behaves normally... 10 // ...and `list_users_route` was generated for us by the macro. 11 let (method, path) = list_users_route(); 12 println!("mounted {method} {path} -> {}", list_users()); 13 } ``` Running `cargo run -p app` prints: ```text 1 mounted GET /users -> ["ada", "linus"] ``` This is exactly the trick real frameworks use: the attribute does not change your handler, but it generates extra registration code beside it that the framework later collects. The `attr` parameter — empty for `#[log_calls]` — carries the `"/users"` literal here, parsed as a `syn::LitStr`. For the full machinery behind `proc-macro2`, custom parsing, and richer argument syntax, see [Procedural Macros](/14-macros/07-proc-macros/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [The Rust Reference: Attribute macros](https://doc.rust-lang.org/reference/procedural-macros.html#attribute-macros), the authoritative specification. * [The Rust Programming Language, Ch. 20: Macros](https://doc.rust-lang.org/book/ch20-05-macros.html), the book’s overview of declarative and procedural macros. * [`syn` crate documentation](https://docs.rs/syn/latest/syn/) and [`quote` crate documentation](https://docs.rs/quote/latest/quote/), parsing and generating tokens. * [The Little Book of Rust Macros](https://veykril.github.io/tlborm/), a deep, community-maintained guide. * Related sections in this guide: * [Macro Basics](/14-macros/00-macro-basics/) — what macros are and are *not*, hygiene, and when to reach for one. * [Declarative Macros](/14-macros/01-declarative-macros/) — `macro_rules!`, the simpler alternative. * [Derive Macros](/14-macros/04-derive-macros/) — `#[derive(...)]`, the sibling flavor for generating trait impls. * [Function-like Macros](/14-macros/06-function-like-macros/) — `name!(...)` procedural macros. * [Procedural Macros](/14-macros/07-proc-macros/) — the full `proc-macro` crate, `syn` 2.0, and `quote` mechanics. * [Generics & Traits](/09-generics-traits/) — often the better tool when you think you need a macro. * [Getting Started](/01-getting-started/) and [Basics](/02-basics/) — `cargo`, crates, and project layout. * [Serialization](/15-serialization/) — where `#[derive(Serialize)]` and field attributes appear constantly in practice. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A `#[timed]` attribute [Section titled “Exercise 1: A #\[timed\] attribute”](#exercise-1-a-timed-attribute) **Difficulty:** Easy **Objective:** Write an attribute macro that prints only how long a function took, leaving its return value and behavior unchanged. **Instructions:** 1. In your `proc-macro` crate, add a `#[proc_macro_attribute] pub fn timed(...)`. 2. Parse the item as an `ItemFn`, wrap the original body so you measure elapsed time around it, and print the elapsed `Duration` to standard error using the function’s name. 3. Apply `#[timed]` to a function such as `fn sum_to(n: u64) -> u64 { (1..=n).sum() }` and confirm the return value is unchanged. Solution log\_attr/src/lib.rs ```rust 1 use proc_macro::TokenStream; 2 use quote::quote; 3 use syn::{parse_macro_input, ItemFn}; 4 5 /// `#[timed]` prints how long a function took, to standard error. 6 #[proc_macro_attribute] 7 pub fn timed(_attr: TokenStream, item: TokenStream) -> TokenStream { 8 let input = parse_macro_input!(item as ItemFn); 9 let vis = &input.vis; 10 let sig = &input.sig; 11 let block = &input.block; 12 let name = &sig.ident; 13 14 quote! { 15 #vis #sig { 16 let __start = std::time::Instant::now(); 17 let __out = (|| #block)(); 18 eprintln!("[timed] {} took {:?}", stringify!(#name), __start.elapsed()); 19 __out 20 } 21 } 22 .into() 23 } ``` app/src/main.rs ```rust 1 use log_attr::timed; 2 3 #[timed] 4 fn sum_to(n: u64) -> u64 { 5 (1..=n).sum() 6 } 7 8 fn main() { 9 println!("sum = {}", sum_to(1_000)); 10 } ``` Running `cargo run -p app` prints (the exact duration varies): ```text 1 [timed] sum_to took 6.917µs 2 sum = 500500 ``` ### Exercise 2: An attribute that reads an argument [Section titled “Exercise 2: An attribute that reads an argument”](#exercise-2-an-attribute-that-reads-an-argument) **Difficulty:** Medium **Objective:** Write `#[warn_deprecated("message")]` that prints a warning before the function body runs. This exercises the `attr` parameter. **Instructions:** 1. Add `#[proc_macro_attribute] pub fn warn_deprecated(...)`. 2. Parse `attr` as a `syn::LitStr` to capture the message, and parse `item` as an `ItemFn`. 3. Re-emit the function with a body that first prints `WARNING: <name> is deprecated: <message>` to standard error, then runs the original block. Solution log\_attr/src/lib.rs ```rust 1 use proc_macro::TokenStream; 2 use quote::quote; 3 use syn::{parse_macro_input, ItemFn, LitStr}; 4 5 /// `#[warn_deprecated("use X instead")]` warns before running the body. 6 #[proc_macro_attribute] 7 pub fn warn_deprecated(attr: TokenStream, item: TokenStream) -> TokenStream { 8 let message = parse_macro_input!(attr as LitStr); 9 let input = parse_macro_input!(item as ItemFn); 10 let vis = &input.vis; 11 let sig = &input.sig; 12 let block = &input.block; 13 let name = &sig.ident; 14 15 quote! { 16 #vis #sig { 17 eprintln!("WARNING: `{}` is deprecated: {}", stringify!(#name), #message); 18 #block 19 } 20 } 21 .into() 22 } ``` app/src/main.rs ```rust 1 use log_attr::warn_deprecated; 2 3 #[warn_deprecated("call `checkout_v2` instead")] 4 fn checkout() -> &'static str { 5 "ok" 6 } 7 8 fn main() { 9 println!("checkout = {}", checkout()); 10 } ``` Running `cargo run -p app` prints: ```text 1 WARNING: `checkout` is deprecated: call `checkout_v2` instead 2 checkout = ok ``` ### Exercise 3: A route attribute that generates a sibling function [Section titled “Exercise 3: A route attribute that generates a sibling function”](#exercise-3-a-route-attribute-that-generates-a-sibling-function) **Difficulty:** Hard **Objective:** Recreate the `#[get("/path")]` attribute from the Real-World Example: keep the handler intact and generate a `<name>_route()` helper returning `("GET", path)`. **Instructions:** 1. Parse `attr` as a `LitStr` (the path) and `item` as an `ItemFn` (the handler). 2. Build a new identifier `<name>_route` with `quote::format_ident!`. 3. Emit the original function unchanged (interpolate the whole `#input`) plus the generated helper. 4. Call both the handler and its generated `_route` function from `main`. Solution log\_attr/src/lib.rs ```rust 1 use proc_macro::TokenStream; 2 use quote::quote; 3 use syn::{parse_macro_input, ItemFn, LitStr}; 4 5 /// `#[get("/path")]` keeps the handler and generates `<name>_route()`. 6 #[proc_macro_attribute] 7 pub fn get(attr: TokenStream, item: TokenStream) -> TokenStream { 8 let path = parse_macro_input!(attr as LitStr); 9 let input = parse_macro_input!(item as ItemFn); 10 11 let name = &input.sig.ident; 12 let route_fn = quote::format_ident!("{}_route", name); 13 14 quote! { 15 #input 16 17 pub fn #route_fn() -> (&'static str, &'static str) { 18 ("GET", #path) 19 } 20 } 21 .into() 22 } ``` app/src/main.rs ```rust 1 use log_attr::get; 2 3 #[get("/users")] 4 fn list_users() -> String { 5 "[\"ada\", \"linus\"]".to_string() 6 } 7 8 fn main() { 9 let (method, path) = list_users_route(); 10 println!("mounted {method} {path} -> {}", list_users()); 11 } ``` Running `cargo run -p app` prints: ```text 1 mounted GET /users -> ["ada", "linus"] ``` # Function-Like Procedural Macros > Unlike a TypeScript runtime function, a Rust foo!(...) procedural macro runs real code at compile time to parse a custom DSL and turn bad input into compiler errors. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **function-like procedural macro** is invoked exactly like the macros you already know — `foo!(...)` — but instead of pattern-matching tokens the way `macro_rules!` does, it is an actual Rust function that receives a `TokenStream`, runs *real Rust code* at compile time, and returns the `TokenStream` it generated. That extra power lets a function-like macro do things a declarative macro cannot: parse a custom mini-language, talk to the file system, and **validate its arguments at compile time** so a bad input becomes a compiler error rather than a runtime exception. This page is about *when* to reach for a function-like proc macro versus a `macro_rules!` one. The mechanics of writing them live in [Procedural Macros](/14-macros/07-proc-macros/). > **Note:** The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects the newest edition automatically. The procedural-macro examples here were compiled and run with `syn` 2.0, `quote` 1.0, and `proc-macro2` 1.0. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) There is no compile-time code generation in TypeScript or JavaScript, so the closest analog to “call a thing with `name(...)` and have it process arbitrary input and validate it” is an ordinary **runtime function**. The catch is in the word *runtime*: any validation it performs only happens when the program actually executes that line. ```typescript 1 // A runtime "route registry" — the nearest JavaScript/TypeScript analog to a function-like macro. 2 type Handler = () => string; 3 4 function makeRoute(method: string, path: string, handler: Handler) { 5 // Validation can ONLY happen at runtime — when this code actually executes. 6 if (!path.startsWith("/")) { 7 throw new Error(`route path must start with '/': got ${path}`); 8 } 9 return { key: `${method.toUpperCase()} ${path}`, handler }; 10 } 11 12 const ok = makeRoute("get", "/users", () => "users"); 13 console.log(ok.key); // GET /users 14 15 try { 16 makeRoute("get", "users", () => "oops"); // bad path — no leading slash 17 } catch (e) { 18 console.log("caught at runtime:", (e as Error).message); 19 } ``` Running it (Node v22, via `tsx`) prints: ```text 1 GET /users 2 caught at runtime: route path must start with '/': got users ``` The bad path is *accepted by the compiler* and only blows up when that branch runs. If `makeRoute("get", "users")` sits behind a rarely-hit code path, it can ship to production undetected. Hold onto that: a function-like proc macro turns exactly this kind of check into a **compile error**. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) A function-like procedural macro lives in its own crate (a crate with `proc-macro = true`). Here is the macro definition, then how a consumer calls it. The macro parses two string literals and rejects a path that does not start with `/`, **at compile time**. ```rust 1 // ===== crate `mymacros` (lib.rs) — must be a proc-macro crate ===== 2 use proc_macro::TokenStream; 3 use quote::quote; 4 use syn::parse::{Parse, ParseStream}; 5 use syn::{parse_macro_input, LitStr, Token}; 6 7 // We teach `syn` how to parse our input: two string literals separated by a comma. 8 struct Route { 9 method: LitStr, 10 _comma: Token![,], 11 path: LitStr, 12 } 13 14 impl Parse for Route { 15 fn parse(input: ParseStream) -> syn::Result<Self> { 16 Ok(Route { 17 method: input.parse()?, 18 _comma: input.parse()?, 19 path: input.parse()?, 20 }) 21 } 22 } 23 24 #[proc_macro] 25 pub fn route(input: TokenStream) -> TokenStream { 26 let Route { method, path, .. } = parse_macro_input!(input as Route); 27 let path_value = path.value(); 28 29 // Real Rust code, running in the compiler: validate the literal. 30 if !path_value.starts_with('/') { 31 return syn::Error::new(path.span(), "route path must start with '/'") 32 .to_compile_error() 33 .into(); 34 } 35 36 let combined = format!("{} {}", method.value().to_uppercase(), path_value); 37 quote! { #combined }.into() // emit a &'static str literal 38 } ``` ```rust 1 // ===== crate `app` (main.rs) — depends on `mymacros` ===== 2 use mymacros::route; 3 4 fn main() { 5 // Each call is parsed, validated, and replaced by a string literal — at compile time. 6 let users: &str = route!("get", "/users"); 7 let health: &str = route!("POST", "/health"); 8 println!("{users}"); 9 println!("{health}"); 10 } ``` Real output: ```text 1 GET /users 2 POST /health ``` And the payoff: give it a bad path and the program **does not compile**: ```rust 1 // does not compile — path has no leading '/' 2 use mymacros::route; 3 4 fn main() { 5 let bad: &str = route!("get", "users"); 6 println!("{bad}"); 7 } ``` Real compiler error: ```text 1 error: route path must start with '/' 2 --> src/main.rs:4:35 3 | 4 4 | let bad: &str = route!("get", "users"); 5 | ^^^^^^^ ``` The error points straight at the offending literal, with our own message. The runtime exception from the TypeScript version is now impossible: the broken route never makes it into a binary. > **Note:** Function-like proc macros must be defined in a dedicated `proc-macro` crate; the consumer crate adds it as a dependency. The boilerplate of setting that up, and the full `syn`/`quote` story, is covered in [Procedural Macros](/14-macros/07-proc-macros/). To follow along, `cargo add syn --features full`, `cargo add quote`, and `cargo add proc-macro2` in the macro crate. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The shape of a function-like proc macro [Section titled “The shape of a function-like proc macro”](#the-shape-of-a-function-like-proc-macro) Every function-like procedural macro has the same signature: ```rust 1 #[proc_macro] 2 pub fn my_macro(input: proc_macro::TokenStream) -> proc_macro::TokenStream { 3 // ... 4 } ``` * The `#[proc_macro]` attribute marks it as a function-like macro (as opposed to `#[proc_macro_derive(...)]` for derives or `#[proc_macro_attribute]` for attribute macros; see [Derive Macros](/14-macros/04-derive-macros/) and [Attribute Macros](/14-macros/05-attribute-macros/)). * It takes one `TokenStream` (everything inside the `( )`, `[ ]`, or `{ }` of the call) and returns one `TokenStream` (the code that replaces the call). * It is a genuine Rust function that runs inside `rustc` during compilation. It can use loops, `if`, the standard library, helper crates, anything. The caller writes `route!("get", "/users")` and the compiler hands the tokens `"get" , "/users"` to your function. Whatever tokens you return are spliced back in where the call appeared. ### `syn` parses, `quote` generates [Section titled “syn parses, quote generates”](#syn-parses-quote-generates) The two workhorse crates: * **`syn`** turns the raw `TokenStream` into structured data. `parse_macro_input!(input as Route)` runs the `Parse` implementation we wrote and either produces a `Route` or emits a parse error for us. `syn` already knows how to parse `LitStr` (a string literal), `Ident`, `LitInt`, punctuation tokens like `Token![,]`, and full Rust syntax. * **`quote`** is the inverse: the `quote! { ... }` macro is a templating language for *building* a `TokenStream`. Inside it, `#combined` interpolates the value of the variable `combined`. This split (parse with `syn`, generate with `quote`) is the standard structure of essentially every procedural macro. ### Why this is “more power” than `macro_rules!` [Section titled “Why this is “more power” than macro\_rules!”](#why-this-is-more-power-than-macro_rules) A `macro_rules!` macro matches token patterns and substitutes; it can *see* tokens but it cannot *compute* with their contents. It cannot ask “does this string literal start with a slash?” because it has no way to inspect the characters inside a literal. A function-like proc macro can, because by the time your function runs you have the literal’s value as a normal Rust `String`: ```rust 1 let path_value = path.value(); // a real String we can call .starts_with('/') on ``` That single capability, running arbitrary logic over the parsed input, is the line between the two macro families. ### Function-like proc macros can validate, count, and even read files [Section titled “Function-like proc macros can validate, count, and even read files”](#function-like-proc-macros-can-validate-count-and-even-read-files) Because the body is ordinary Rust, a function-like macro can: * **Validate** input and emit a custom compile error (the `route!` example). * **Compute** values at compile time (parse and re-emit, fold constants, build lookup tables). * **Read the file system at build time.** This is exactly how the standard `include_str!` and `include_bytes!` work, and how SQL crates like `sqlx`’s `query!` validate your SQL against a real database schema during compilation. None of these are possible with a declarative macro alone. ### A small DSL: `config!` [Section titled “A small DSL: config!”](#a-small-dsl-config) Function-like macros shine at parsing a *custom* syntax that is not valid expression-grammar Rust. Here a `config!` macro reads `key = value` pairs and emits a struct literal: ```rust 1 // ===== in the proc-macro crate ===== 2 use proc_macro::TokenStream; 3 use quote::quote; 4 use syn::parse::{Parse, ParseStream}; 5 use syn::punctuated::Punctuated; 6 use syn::{parse_macro_input, Ident, LitInt, LitStr, Token}; 7 8 struct Setting { 9 key: Ident, 10 value: SettingValue, 11 } 12 13 enum SettingValue { 14 Str(LitStr), 15 Int(LitInt), 16 } 17 18 impl Parse for Setting { 19 fn parse(input: ParseStream) -> syn::Result<Self> { 20 let key: Ident = input.parse()?; 21 input.parse::<Token![=]>()?; 22 let value = if input.peek(LitStr) { 23 SettingValue::Str(input.parse()?) 24 } else { 25 SettingValue::Int(input.parse()?) 26 }; 27 Ok(Setting { key, value }) 28 } 29 } 30 31 struct ConfigInput { 32 settings: Punctuated<Setting, Token![,]>, 33 } 34 35 impl Parse for ConfigInput { 36 fn parse(input: ParseStream) -> syn::Result<Self> { 37 Ok(ConfigInput { 38 settings: Punctuated::parse_terminated(input)?, 39 }) 40 } 41 } 42 43 #[proc_macro] 44 pub fn config(input: TokenStream) -> TokenStream { 45 let parsed = parse_macro_input!(input as ConfigInput); 46 let fields = parsed.settings.iter().map(|s| { 47 let key = &s.key; 48 match &s.value { 49 SettingValue::Str(lit) => quote! { #key: #lit.to_string() }, 50 SettingValue::Int(lit) => quote! { #key: #lit }, 51 } 52 }); 53 quote! { 54 Config { #( #fields ),* } 55 } 56 .into() 57 } ``` ```rust 1 // ===== in the consumer crate ===== 2 use mymacros::config; 3 4 #[derive(Debug)] 5 struct Config { 6 host: String, 7 port: u16, 8 } 9 10 fn main() { 11 let cfg = config! { 12 host = "localhost", 13 port = 8080, 14 }; 15 println!("listening on {}:{}", cfg.host, cfg.port); 16 } ``` Real output: ```text 1 listening on localhost:8080 ``` The `config! { ... }` block is *not* a Rust expression you could write by hand: `host = "localhost"` is not valid in an expression position. The macro defines its own grammar, parses it with `syn`, and emits a normal `Config { .. }` literal. This is the kind of mini-DSL that function-like proc macros power, for instance `sqlx`’s `query!` (which type-checks SQL against a real schema at compile time) or the `html!`/`view!` macros in web frameworks like Yew and Leptos. (Note that not every DSL needs a proc macro: `serde_json::json!`, despite its rich syntax, is a *declarative* `macro_rules!` macro, a reminder that the declarative family is more capable than it first appears.) *** ## Key Differences [Section titled “Key Differences”](#key-differences) ### Function-like proc macro vs. declarative `macro_rules!` [Section titled “Function-like proc macro vs. declarative macro\_rules!”](#function-like-proc-macro-vs-declarative-macro_rules) | Aspect | `macro_rules!` (declarative) | `#[proc_macro]` (function-like procedural) | | ------------------------------ | --------------------------------------- | ---------------------------------------------------- | | How it works | Pattern-match token trees, substitute | A Rust function: `TokenStream` in, `TokenStream` out | | Where it lives | Anywhere (inline in any module) | A separate `proc-macro = true` crate | | Can run arbitrary logic | No — match and emit only | Yes — full Rust, loops, std, helper crates | | Inspect a literal’s contents | No | Yes (`lit.value()` gives a `String`/number) | | Validate input at compile time | Only structural shape | Arbitrary checks → custom `compile_error!` | | Read files at build time | No | Yes (like `include_str!`) | | Compile-time cost | Cheap, fast | Compiles a whole crate + `syn`; slower builds | | Best for | Variadic construction, simple templates | Custom DSLs, validation, codegen from input | ### Function-like proc macro vs. derive vs. attribute [Section titled “Function-like proc macro vs. derive vs. attribute”](#function-like-proc-macro-vs-derive-vs-attribute) All three are procedural macros (real functions in a `proc-macro` crate), distinguished by *how they are invoked*: | Kind | Invoked as | Attribute on the definition | Typical job | | ------------- | ---------------------------- | --------------------------- | ------------------------------------ | | Function-like | `foo!(...)` / `foo! { ... }` | `#[proc_macro]` | Parse a call’s arguments, emit code | | Derive | `#[derive(Foo)]` on a type | `#[proc_macro_derive(Foo)]` | Generate `impl`s for a struct/enum | | Attribute | `#[foo]` on an item | `#[proc_macro_attribute]` | Transform/wrap the item it decorates | This page is about the first row; the other two are in [Derive Macros](/14-macros/04-derive-macros/) and [Attribute Macros](/14-macros/05-attribute-macros/). ### Function-like macros can appear in many positions [Section titled “Function-like macros can appear in many positions”](#function-like-macros-can-appear-in-many-positions) Like `macro_rules!` macros, a function-like proc macro call can stand wherever its output is valid: in **expression** position (`let x = foo!();`), **statement** position, or **item** position (generating whole functions, structs, or `impl`s at module level). The `config!` example produced an expression; the `routes!` macro below produces an entire function. A plain function call can only ever be an expression. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Defining a `#[proc_macro]` in a normal crate [Section titled “Pitfall 1: Defining a #\[proc\_macro\] in a normal crate”](#pitfall-1-defining-a-proc_macro-in-a-normal-crate) Function-like procedural macros *must* live in a crate whose `Cargo.toml` declares `[lib] proc-macro = true`. Putting `#[proc_macro]` in a regular binary or library crate fails: ```rust 1 // does not compile — this is a normal binary crate, not a proc-macro crate 2 use proc_macro::TokenStream; 3 4 #[proc_macro] 5 pub fn noop(_input: TokenStream) -> TokenStream { 6 TokenStream::new() 7 } 8 9 fn main() {} ``` Real compiler error: ```text 1 error: the `#[proc_macro]` attribute is only usable with crates of the `proc-macro` crate type 2 --> src/main.rs:3:1 3 | 4 3 | #[proc_macro] 5 | ^^^^^^^^^^^^^ 6 7 error[E0432]: unresolved import `proc_macro` 8 --> src/main.rs:1:5 9 | 10 1 | use proc_macro::TokenStream; 11 | ^^^^^^^^^^ use of unresolved module or unlinked crate `proc_macro` ``` The fix is to create a dedicated crate (often named `yourcrate-macros`) with `proc-macro = true`, and depend on it from your application crate. See [Procedural Macros](/14-macros/07-proc-macros/) for the full workspace layout. ### Pitfall 2: Expecting it to accept runtime values [Section titled “Pitfall 2: Expecting it to accept runtime values”](#pitfall-2-expecting-it-to-accept-runtime-values) A function-like macro receives **source tokens**, not values. If your `Parse` impl expects string *literals*, you cannot pass a variable: ```rust 1 // does not compile — `route!` parses string LITERALS, not runtime variables 2 use mymacros::route; 3 4 fn main() { 5 let method = "get"; 6 let r: &str = route!(method, "/users"); 7 println!("{r}"); 8 } ``` Real compiler error: ```text 1 error: expected string literal 2 --> app/src/main.rs:6:26 3 | 4 6 | let r: &str = route!(method, "/users"); 5 | ^^^^^^ ``` This is the deepest mental-model shift for a TypeScript/JavaScript developer: the macro runs *before* there is any such thing as the value of `method`. It sees the *identifier token* `method` and your parser rejects it because it wanted a literal. If you need a runtime value, use a function, not a macro. ### Pitfall 3: Assuming it is zero-cost to compile [Section titled “Pitfall 3: Assuming it is zero-cost to compile”](#pitfall-3-assuming-it-is-zero-cost-to-compile) A declarative macro is essentially free at build time. A function-like proc macro drags in `syn`, `quote`, and `proc-macro2`, all of which must compile, and the macro crate compiles as its own unit. For a one-off “build this string” task that `macro_rules!` could handle, the proc-macro overhead is rarely worth it. (The expansion itself is still zero *runtime* cost; only build time is affected.) ### Pitfall 4: Forgetting `--features full` on `syn` [Section titled “Pitfall 4: Forgetting --features full on syn”](#pitfall-4-forgetting---features-full-on-syn) `syn`’s default features only parse a subset of Rust. If you parse expressions, items, or use `Punctuated`, you typically need the `full` feature; otherwise you get confusing “cannot find type” or “no method” errors at compile time of the macro crate. Add it explicitly: ```toml 1 [dependencies] 2 syn = { version = "2", features = ["full"] } 3 quote = "1" 4 proc-macro2 = "1" ``` ### Pitfall 5: Reaching for a proc macro when `macro_rules!` suffices [Section titled “Pitfall 5: Reaching for a proc macro when macro\_rules! suffices”](#pitfall-5-reaching-for-a-proc-macro-when-macro_rules-suffices) The single most common design mistake is jumping to a procedural macro for something declarative macros do cleanly. If you only need variadic construction or a “this expands to that” template, write a `macro_rules!`: it is simpler, faster to compile, and needs no extra crate. Use the decision rule in Best Practices below. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Decide declarative-first, procedural-only-when-needed [Section titled “Decide declarative-first, procedural-only-when-needed”](#decide-declarative-first-procedural-only-when-needed) Use this checklist before writing a function-like proc macro: 1. **Can a plain function do it?** If the inputs are runtime values, use a function. Stop. 2. **Can `macro_rules!` do it?** If you only need variadic args, simple repetition, or a fixed “expands to that” template, write a declarative macro (see [Declarative Macros](/14-macros/01-declarative-macros/) and [Repetition](/14-macros/03-repetition/)). Stop. 3. **Do you need to *inspect or validate* the input’s contents, parse a *custom grammar*, or *read files* at build time?** Now a function-like procedural macro earns its keep. ### Emit good compile errors with spans [Section titled “Emit good compile errors with spans”](#emit-good-compile-errors-with-spans) When you reject input, build the error with `syn::Error::new(span, message)` and return `.to_compile_error()`. Attaching the right `span` (here `path.span()`) makes the caret point at the exact token, just like a built-in error. Vague errors with the wrong span are a frequent source of user frustration. ### Keep the macro crate thin [Section titled “Keep the macro crate thin”](#keep-the-macro-crate-thin) Put as little logic as possible directly in the `#[proc_macro]` function; factor parsing and generation into helper functions and types so you can unit-test them. Procedural-macro code that returns a `proc_macro2::TokenStream` from a helper is far easier to test than one tangled with `proc_macro::TokenStream` (which only exists inside the compiler). ### Name the crate by convention [Section titled “Name the crate by convention”](#name-the-crate-by-convention) The community convention is to name the proc-macro crate `<yourcrate>-macros` (or `<yourcrate>-derive`) and re-export its macros from your main crate so users see a single dependency. Many crates you already use — `serde`, `tokio`, `clap` — do exactly this. ### Pin the standard toolset [Section titled “Pin the standard toolset”](#pin-the-standard-toolset) Use `syn` 2.x, `quote` 1.x, and `proc-macro2` 1.x: the current, stable, near-universal stack. (`syn` 1.x is legacy; new code should target 2.x.) *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored routing-table DSL. The macro reads entries of the form `METHOD "/path" => handler`, validates every path at compile time, and generates a `dispatch` function, an *item*, not just an expression. This is the same idea behind web-framework route macros, distilled. ```rust 1 // ===== crate `mymacros` (lib.rs) ===== 2 use proc_macro::TokenStream; 3 use quote::quote; 4 use syn::parse::{Parse, ParseStream}; 5 use syn::punctuated::Punctuated; 6 use syn::{parse_macro_input, Ident, LitStr, Token}; 7 8 struct RouteEntry { 9 method: Ident, 10 path: LitStr, 11 handler: Ident, 12 } 13 14 impl Parse for RouteEntry { 15 fn parse(input: ParseStream) -> syn::Result<Self> { 16 let method: Ident = input.parse()?; 17 let path: LitStr = input.parse()?; 18 input.parse::<Token![=>]>()?; 19 let handler: Ident = input.parse()?; 20 Ok(RouteEntry { method, path, handler }) 21 } 22 } 23 24 struct RoutesInput { 25 entries: Punctuated<RouteEntry, Token![,]>, 26 } 27 28 impl Parse for RoutesInput { 29 fn parse(input: ParseStream) -> syn::Result<Self> { 30 Ok(RoutesInput { 31 entries: Punctuated::parse_terminated(input)?, 32 }) 33 } 34 } 35 36 #[proc_macro] 37 pub fn routes(input: TokenStream) -> TokenStream { 38 let parsed = parse_macro_input!(input as RoutesInput); 39 40 let mut arms = Vec::new(); 41 for entry in parsed.entries.iter() { 42 let path_value = entry.path.value(); 43 // Compile-time validation, once per route. 44 if !path_value.starts_with('/') { 45 return syn::Error::new(entry.path.span(), "route path must start with '/'") 46 .to_compile_error() 47 .into(); 48 } 49 let method = entry.method.to_string().to_uppercase(); 50 let path = &entry.path; 51 let handler_name = entry.handler.to_string(); 52 arms.push(quote! { 53 (#method, #path) => #handler_name, 54 }); 55 } 56 57 quote! { 58 fn dispatch(method: &str, path: &str) -> &'static str { 59 match (method, path) { 60 #( #arms )* 61 _ => "404 Not Found", 62 } 63 } 64 } 65 .into() 66 } ``` ```rust 1 // ===== crate `app` (main.rs) ===== 2 use mymacros::routes; 3 4 // Expands into a whole `fn dispatch(..)` at module level (item position). 5 routes! { 6 GET "/users" => list_users, 7 POST "/users" => create_user, 8 GET "/health" => health_check, 9 } 10 11 fn main() { 12 println!("{}", dispatch("GET", "/users")); 13 println!("{}", dispatch("POST", "/users")); 14 println!("{}", dispatch("DELETE", "/users")); 15 } ``` Real output: ```text 1 list_users 2 create_user 3 404 Not Found ``` Three things to notice. First, the macro runs a *loop* over the parsed entries; declarative macros cannot do arbitrary iteration with logic in the body like this. Second, every path is validated during compilation; a typo’d `"users"` would be a compiler error before the program ever runs, unlike the TypeScript registry that only threw at runtime. Third, the macro emitted an entire function definition, demonstrating that function-like proc macros work in item position, not just as expressions. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Rust Reference — Function-like procedural macros](https://doc.rust-lang.org/reference/procedural-macros.html#function-like-procedural-macros) * [The Rust Book — Macros](https://doc.rust-lang.org/book/ch20-05-macros.html) * [`syn` documentation](https://docs.rs/syn/latest/syn/) and [`quote` documentation](https://docs.rs/quote/latest/quote/) * [`proc_macro` standard module](https://doc.rust-lang.org/proc_macro/): the `TokenStream` API the compiler hands you. * [`std::include_str!`](https://doc.rust-lang.org/std/macro.include_str.html): a built-in example of build-time file reading. ### Related sections in this guide [Section titled “Related sections in this guide”](#related-sections-in-this-guide) * [Procedural Macros](/14-macros/07-proc-macros/) — the full proc-macro crate setup, `TokenStream`, `syn` 2 + `quote`, and a compile-verified custom derive. * [Macro Basics](/14-macros/00-macro-basics/): what macros are and are *not* (not decorators, not functions); compile-time expansion and hygiene. * [Declarative Macros](/14-macros/01-declarative-macros/) and [Repetition](/14-macros/03-repetition/) — the simpler `macro_rules!` family you should try first. * [Macro Patterns](/14-macros/02-macro-patterns/): fragment specifiers (`:expr`, `:ident`, `:ty`, `:tt`), which `syn` mirrors at the parser level. * [Derive Macros](/14-macros/04-derive-macros/) and [Attribute Macros](/14-macros/05-attribute-macros/) — the other two procedural-macro shapes. * [Common Macros](/14-macros/08-common-macros/): `include_str!`, `format!`, and the rest of the standard library’s macros. * Background: [Output and Formatting](/02-basics/04-output/) introduced macro-call syntax; the [Introduction](/00-introduction/) and [Getting Started](/01-getting-started/) set the stage. * Applied: [Serialization](/15-serialization/) leans on `serde`’s derive and the `serde_json::json!` DSL; table-driven tests appear in [Testing](/13-testing/). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1 [Section titled “Exercise 1”](#exercise-1) **Difficulty:** Easy **Objective:** Write your first function-like procedural macro that processes its input with real Rust code. **Instructions:** In a `proc-macro` crate, write a `shout!` macro that takes a single string literal and expands to the same string uppercased at compile time. `shout!("hello")` should evaluate to the `&'static str` `"HELLO"`. (Use `parse_macro_input!(input as LitStr)`, then `.value().to_uppercase()`, then `quote!`.) ```rust 1 // in the proc-macro crate 2 use proc_macro::TokenStream; 3 use quote::quote; 4 use syn::{parse_macro_input, LitStr}; 5 6 #[proc_macro] 7 pub fn shout(input: TokenStream) -> TokenStream { 8 // TODO: parse a LitStr, uppercase its value, emit it 9 } ``` Solution ```rust 1 // in the proc-macro crate (lib.rs) 2 use proc_macro::TokenStream; 3 use quote::quote; 4 use syn::{parse_macro_input, LitStr}; 5 6 #[proc_macro] 7 pub fn shout(input: TokenStream) -> TokenStream { 8 let lit = parse_macro_input!(input as LitStr); 9 let shouted = lit.value().to_uppercase(); 10 quote! { #shouted }.into() 11 } ``` ```rust 1 // in the consumer crate (main.rs) 2 use mymacros::shout; 3 4 fn main() { 5 let s: &str = shout!("hello"); 6 println!("{s}"); 7 } ``` Output: ```text 1 HELLO ``` The uppercasing runs in the compiler; the binary just contains the literal `"HELLO"`. ### Exercise 2 [Section titled “Exercise 2”](#exercise-2) **Difficulty:** Medium **Objective:** Parse two arguments of different kinds and compute a result at compile time. **Instructions:** Write a `repeat_str!` macro that takes a string literal and an integer literal, and expands to the string repeated that many times. `repeat_str!("ab", 3)` should evaluate to `"ababab"`. Define a `Parse` impl that reads `LitStr , LitInt`, convert the count with `count.base10_parse::<usize>()`, and use `str::repeat`. ```rust 1 // in the proc-macro crate 2 use proc_macro::TokenStream; 3 use quote::quote; 4 use syn::parse::{Parse, ParseStream}; 5 use syn::{parse_macro_input, LitInt, LitStr, Token}; 6 7 struct RepeatInput { 8 text: LitStr, 9 _comma: Token![,], 10 count: LitInt, 11 } 12 13 impl Parse for RepeatInput { 14 fn parse(input: ParseStream) -> syn::Result<Self> { 15 // TODO: parse text, comma, count 16 } 17 } 18 19 #[proc_macro] 20 pub fn repeat_str(input: TokenStream) -> TokenStream { 21 // TODO: parse, compute the repeated string, emit it 22 } ``` Solution ```rust 1 // in the proc-macro crate (lib.rs) 2 use proc_macro::TokenStream; 3 use quote::quote; 4 use syn::parse::{Parse, ParseStream}; 5 use syn::{parse_macro_input, LitInt, LitStr, Token}; 6 7 struct RepeatInput { 8 text: LitStr, 9 _comma: Token![,], 10 count: LitInt, 11 } 12 13 impl Parse for RepeatInput { 14 fn parse(input: ParseStream) -> syn::Result<Self> { 15 Ok(RepeatInput { 16 text: input.parse()?, 17 _comma: input.parse()?, 18 count: input.parse()?, 19 }) 20 } 21 } 22 23 #[proc_macro] 24 pub fn repeat_str(input: TokenStream) -> TokenStream { 25 let RepeatInput { text, count, .. } = parse_macro_input!(input as RepeatInput); 26 let n: usize = match count.base10_parse() { 27 Ok(n) => n, 28 Err(e) => return e.to_compile_error().into(), 29 }; 30 let repeated = text.value().repeat(n); 31 quote! { #repeated }.into() 32 } ``` ```rust 1 // in the consumer crate (main.rs) 2 use mymacros::repeat_str; 3 4 fn main() { 5 let r: &str = repeat_str!("ab", 3); 6 println!("{r}"); 7 } ``` Output: ```text 1 ababab ``` Returning `e.to_compile_error()` means a count that overflows `usize` (a literal too large to fit, like `repeat_str!("ab", 99999999999999999999999999999999)`) produces a clean compiler error instead of a panic inside the macro. A non-numeric token is rejected even earlier, by the `count: LitInt` parse step, which expects an integer literal. ### Exercise 3 [Section titled “Exercise 3”](#exercise-3) **Difficulty:** Hard **Objective:** Validate the *contents* of a literal and emit a custom compile error: the capability that sets function-like proc macros apart from `macro_rules!`. **Instructions:** Write a `hex_color!` macro that takes a string literal like `"#ff8800"` and expands to a `(u8, u8, u8)` RGB tuple, parsed at compile time. It must accept an optional leading `#`, require exactly six hex digits, and emit a compile error (via `syn::Error::new(span, msg).to_compile_error()`) for anything else. `hex_color!("#ff8800")` should evaluate to `(255, 136, 0)`, while `hex_color!("#zz0011")` should fail to compile. ```rust 1 // in the proc-macro crate 2 use proc_macro::TokenStream; 3 use quote::quote; 4 use syn::{parse_macro_input, LitStr}; 5 6 #[proc_macro] 7 pub fn hex_color(input: TokenStream) -> TokenStream { 8 // TODO: parse a LitStr, strip optional '#', validate 6 hex digits, 9 // parse each pair with u8::from_str_radix(.., 16), emit (r, g, b) 10 } ``` Solution ```rust 1 // in the proc-macro crate (lib.rs) 2 use proc_macro::TokenStream; 3 use quote::quote; 4 use syn::{parse_macro_input, LitStr}; 5 6 #[proc_macro] 7 pub fn hex_color(input: TokenStream) -> TokenStream { 8 let lit = parse_macro_input!(input as LitStr); 9 let s = lit.value(); 10 let hex = s.strip_prefix('#').unwrap_or(&s); 11 12 if hex.len() != 6 || !hex.chars().all(|c| c.is_ascii_hexdigit()) { 13 return syn::Error::new(lit.span(), "expected a 6-digit hex color like \"#ff8800\"") 14 .to_compile_error() 15 .into(); 16 } 17 18 let r = u8::from_str_radix(&hex[0..2], 16).unwrap(); 19 let g = u8::from_str_radix(&hex[2..4], 16).unwrap(); 20 let b = u8::from_str_radix(&hex[4..6], 16).unwrap(); 21 quote! { (#r, #g, #b) }.into() 22 } ``` ```rust 1 // in the consumer crate (main.rs) 2 use mymacros::hex_color; 3 4 fn main() { 5 let (red, green, blue): (u8, u8, u8) = hex_color!("#ff8800"); 6 println!("rgb({red}, {green}, {blue})"); 7 } ``` Output: ```text 1 rgb(255, 136, 0) ``` Feeding it an invalid color — `hex_color!("#zz0011")` — produces a compile error instead. With this consumer file: ```rust 1 // does not compile — "#zz0011" is not valid hex 2 use mymacros::hex_color; 3 4 fn main() { 5 let _c: (u8, u8, u8) = hex_color!("#zz0011"); 6 } ``` the compiler reports: ```text 1 error: expected a 6-digit hex color like "#ff8800" 2 --> src/main.rs:4:39 3 | 4 4 | let _c: (u8, u8, u8) = hex_color!("#zz0011"); 5 | ^^^^^^^^^ ``` The validation runs entirely in the compiler, so an invalid color literal can never reach a running program, the kind of guarantee no runtime JavaScript validator can give you. # Procedural Macros: Writing Compiler Plugins with syn and quote > Write Rust procedural macros that run inside the compiler: parse tokens with syn, generate code with quote, type-safe and zero-cost where TS uses Babel. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **procedural macro** is a small Rust program that runs *inside the compiler*: it receives your code as a stream of tokens, transforms it with ordinary Rust logic, and hands back new tokens that the compiler then type-checks like anything else. This is how `#[derive(Serialize)]`, `#[tokio::main]`, and `sqlx::query!` work, and writing your own is the closest Rust gets to TypeScript’s transformer plugins or Babel macros, except it is type-safe, hygienic, and has zero runtime cost. This page covers the mechanics: the special `proc-macro` crate type, the `TokenStream` type, and the `syn` 2 + `quote` + `proc-macro2` trio you will use for every nontrivial proc macro, ending with a full compile-verified custom `derive`. > **Note:** The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects the newest edition automatically. Every Rust snippet here was compiled and run on stable with `syn` 2.0.117, `quote` 1.0.45, and `proc-macro2` 1.0.106. > **Tip:** If you have not read [Macro Basics](/14-macros/00-macro-basics/) and [Derive Macros](/14-macros/04-derive-macros/) yet, do so first. This page assumes you know that macros are compile-time, token-based, and hygienic, and that `#[derive(...)]` is one of the three procedural-macro flavors. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) There is nothing in plain TypeScript that operates on your code the way a proc macro does. The nearest cousins are **AST transformers** — a TypeScript compiler transform, a Babel plugin, or a tool like `babel-plugin-macros`. They parse source into an Abstract Syntax Tree, walk and rewrite nodes, and print code back out. Here is a hand-written Babel-style transform that auto-generates a `describe()` method onto a class: ```typescript 1 // babel-style transformer (runs in the BUILD step, on the AST). 2 import type { PluginObj, types as BabelTypes } from "@babel/core"; 3 4 export default function addDescribe({ types: t }: { types: typeof BabelTypes }): PluginObj { 5 return { 6 name: "add-describe", 7 visitor: { 8 ClassDeclaration(path) { 9 const className = path.node.id?.name ?? "Anonymous"; 10 11 // Collect the names of class fields from the AST. 12 const fieldNames = path.node.body.body 13 .filter((m) => t.isClassProperty(m) && t.isIdentifier(m.key)) 14 .map((m) => ((m as BabelTypes.ClassProperty).key as BabelTypes.Identifier).name); 15 16 // Build the body of a `describe()` method as a template string. 17 const lines = fieldNames 18 .map((f) => `lines.push(\` ${f} = \${JSON.stringify(this.${f})}\`);`) 19 .join("\n"); 20 const methodSrc = ` 21 describe() { 22 const lines = ["${className} {"]; 23 ${lines} 24 lines.push("}"); 25 return lines.join("\\n"); 26 }`; 27 28 // Parse that string and splice the new method into the class. 29 const method = t.classMethod(/* ...build from methodSrc... */); 30 path.node.body.body.push(method); 31 }, 32 }, 33 }; 34 } ``` A user of the plugin writes a normal class and the build step injects the method: ```typescript 1 class User { 2 id = 0; 3 name = ""; 4 active = false; 5 } 6 // After transform, `new User().describe()` exists at runtime. ``` Two things to hold onto. First, the transform manipulates an **AST** (`ClassDeclaration`, `ClassProperty`, `Identifier`) — exactly what `syn` gives you in Rust. Second, when this Babel plugin builds new code it does it by **string concatenation** (`methodSrc`), which is fragile: a stray brace or an unescaped value silently produces broken output, and nothing checks the result until runtime. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The Rust version is a separate crate of the special `proc-macro` type. It parses the input with `syn`, builds output with `quote!` (structured token interpolation, *not* string concatenation), and the compiler type-checks the generated code immediately. The macro crate, `describe_derive/src/lib.rs`: ```rust 1 use proc_macro::TokenStream; 2 use quote::quote; 3 use syn::{parse_macro_input, Data, DeriveInput, Fields}; 4 5 /// Derives a `describe(&self) -> String` method that lists each field 6 /// name and its `Debug` value — the Rust analogue of the Babel plugin. 7 #[proc_macro_derive(Describe)] 8 pub fn derive_describe(input: TokenStream) -> TokenStream { 9 // 1. PARSE the incoming tokens into a typed syntax tree. 10 let ast = parse_macro_input!(input as DeriveInput); 11 let name = &ast.ident; 12 13 // 2. INSPECT: require a struct with named fields, or emit a real error. 14 let fields = match &ast.data { 15 Data::Struct(data) => match &data.fields { 16 Fields::Named(named) => &named.named, 17 _ => { 18 return syn::Error::new_spanned( 19 &ast.ident, 20 "Describe only supports structs with named fields", 21 ) 22 .to_compile_error() 23 .into(); 24 } 25 }, 26 _ => { 27 return syn::Error::new_spanned( 28 &ast.ident, 29 "Describe can only be derived for structs", 30 ) 31 .to_compile_error() 32 .into(); 33 } 34 }; 35 36 // 3. BUILD one push_str line per field. `quote!` interpolates with `#`. 37 let field_lines = fields.iter().map(|field| { 38 let field_name = field.ident.as_ref().unwrap(); 39 let field_label = field_name.to_string(); 40 quote! { 41 out.push_str(&format!(" {} = {:?}\n", #field_label, &self.#field_name)); 42 } 43 }); 44 45 let type_label = name.to_string(); 46 47 // 4. EMIT a complete `impl` block as new tokens. 48 let expanded = quote! { 49 impl #name { 50 pub fn describe(&self) -> String { 51 let mut out = String::new(); 52 out.push_str(&format!("{} {{\n", #type_label)); 53 #( #field_lines )* 54 out.push('}'); 55 out 56 } 57 } 58 }; 59 60 expanded.into() 61 } ``` Its `Cargo.toml`. Note the `proc-macro = true` flag, which makes this a compiler-plugin crate: ```toml 1 [package] 2 name = "describe_derive" 3 version = "0.1.0" 4 edition = "2024" 5 6 [lib] 7 proc-macro = true 8 9 [dependencies] 10 syn = "2" 11 quote = "1" 12 proc-macro2 = "1" ``` A separate consumer crate uses it like any built-in derive: ```rust 1 use describe_derive::Describe; 2 3 #[derive(Describe)] 4 struct User { 5 id: u64, 6 name: String, 7 active: bool, 8 } 9 10 fn main() { 11 let u = User { id: 7, name: "Ada".to_string(), active: true }; 12 println!("{}", u.describe()); 13 } ``` Real output: ```text 1 User { 2 id = 7 3 name = "Ada" 4 active = true 5 } ``` Unlike the Babel plugin’s `methodSrc` string, the `quote! { ... }` block is parsed by the `quote` crate into structured tokens; a malformed interpolation is a compile error in the *macro* crate, and the generated `impl` is type-checked in the *consumer* crate. Nothing reaches runtime unchecked. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The three crates: proc-macro, proc-macro2, and the syn/quote pair [Section titled “The three crates: proc-macro, proc-macro2, and the syn/quote pair”](#the-three-crates-proc-macro-proc-macro2-and-the-synquote-pair) Proc macros are built on three layers. Getting them straight removes most of the early confusion: * **`proc_macro`** is a crate baked into the compiler (no `cargo add` needed). It defines `proc_macro::TokenStream`, the type your macro functions must take and return. It *only* exists while the compiler is running, so you cannot use it in a regular binary, a test, or a build script. * **`proc-macro2`** ([crates.io](https://crates.io/crates/proc-macro2)) is a mirror of that API that works **anywhere**: in unit tests, build scripts, and on the host. Its `proc_macro2::TokenStream` is what `syn` and `quote` actually speak. You convert between the two with `.into()`. * **`syn`** parses a `TokenStream` into a typed syntax tree (`DeriveInput`, `ItemFn`, `Expr`, …), and **`quote`** does the reverse: it turns a template with `#interpolation` into a `TokenStream`. They are by the same author (dtolnay) and are the de-facto standard. The data flow of every proc macro is the same pipeline: ```text 1 proc_macro::TokenStream --.into()--> proc_macro2::TokenStream 2 (compiler) | 3 syn::parse2 / parse_macro_input! 4 v 5 typed AST (DeriveInput, ...) 6 | 7 your Rust logic 8 v 9 quote! { ... } --> proc_macro2::TokenStream 10 | 11 proc_macro::TokenStream <--.into()-----------' 12 (back to compiler) ``` ### What a `TokenStream` actually is [Section titled “What a TokenStream actually is”](#what-a-tokenstream-actually-is) A `TokenStream` is a flat sequence of **token trees**: identifiers, literals, punctuation, and *delimited groups* (`(...)`, `[...]`, `{...}`) which nest. It is **not** a string and **not** a fully parsed AST; it sits between the two. For `struct User { id: u64 }` the stream is roughly the tokens `struct`, `User`, and a brace-group containing `id`, `:`, `u64`. Importantly, every token carries a **span**: a record of where it came from in the source, which drives both error messages and hygiene (see [Macro Basics](/14-macros/00-macro-basics/)). Because the input is already tokenized — not raw text — `quote!` cannot accidentally glue two identifiers together, and `:expr`-style grouping is preserved automatically. You can build and inspect a `proc_macro2::TokenStream` entirely on the host, which is why the standalone demo below runs as a normal binary: ```rust 1 use proc_macro2::TokenStream; 2 use quote::quote; 3 use syn::DeriveInput; 4 5 fn main() { 6 // `quote!` builds a proc_macro2::TokenStream from a template. 7 let source: TokenStream = quote! { 8 struct Point { x: i32, y: i32 } 9 }; 10 11 // `syn::parse2` parses tokens into a typed AST node. 12 let ast: DeriveInput = syn::parse2(source).expect("valid struct"); 13 println!("parsed type name: {}", ast.ident); 14 15 // Build new tokens and render them back to a string. 16 let name = ast.ident; 17 let generated: TokenStream = quote! { 18 impl #name { 19 fn type_name() -> &'static str { stringify!(#name) } 20 } 21 }; 22 println!("generated tokens: {generated}"); 23 } ``` Run as an ordinary binary (dependencies: `syn` with the `full` feature, `quote`, `proc-macro2`). Real output: ```text 1 parsed type name: Point 2 generated tokens: impl Point { fn type_name () -> & 'static str { stringify ! (Point) } } ``` Notice the `Display` of a `TokenStream` re-inserts spaces between every token; it is for debugging, not for pretty source. (For readable output, pipe through [`cargo expand`](https://github.com/dtolnay/cargo-expand).) ### Walking the `Describe` derive line by line [Section titled “Walking the Describe derive line by line”](#walking-the-describe-derive-line-by-line) **`#[proc_macro_derive(Describe)]`** registers a derive macro named `Describe`. The function it decorates must have the signature `fn(TokenStream) -> TokenStream` and live at the crate root of a `proc-macro` crate. The function name (`derive_describe`) is irrelevant to users; the `Describe` in the attribute is what they write in `#[derive(Describe)]`. **`parse_macro_input!(input as DeriveInput)`** parses the token stream into `syn`’s `DeriveInput`, the catch-all node for “the thing a derive is attached to” (a struct, enum, or union). Unlike `syn::parse2`, this macro is purpose-built for proc-macro entry points: on a parse error it *returns* a `compile_error!` invocation from your function automatically, so you never hand back garbage tokens. **Matching on `ast.data`** distinguishes `Data::Struct`, `Data::Enum`, and `Data::Union`. We only support named-field structs, so every other shape produces a deliberate error via `syn::Error::new_spanned(&ast.ident, "...").to_compile_error()`. Passing `&ast.ident` as the span means the error underlines *the type name in the user’s code*, not some location inside our macro. **Building `field_lines`** maps over each field to produce a small `TokenStream` fragment. Inside `quote!`, `#field_label` interpolates the field’s name as a string literal and `#field_name` interpolates the identifier so `self.#field_name` becomes e.g. `self.id`. These fragments are themselves tokens, so they compose. **The final `quote!`** assembles the `impl` block. The repetition `#( #field_lines )*` — analogous to `macro_rules!` repetition from [Repetition](/14-macros/03-repetition/) — splices every fragment in sequence. Then `.into()` converts the `proc_macro2::TokenStream` that `quote!` produced back into the `proc_macro::TokenStream` the compiler expects. ### Seeing the generated code with `cargo expand` [Section titled “Seeing the generated code with cargo expand”](#seeing-the-generated-code-with-cargo-expand) You never have to guess what your macro emits. `cargo install cargo-expand`, then `cargo expand` prints the post-expansion source. For the `User` above, the relevant portion is: ```rust 1 impl User { 2 pub fn describe(&self) -> String { 3 let mut out = String::new(); 4 out.push_str(&format!("{} {{\n", "User")); 5 out.push_str(&format!(" {} = {:?}\n", "id", &self.id)); 6 out.push_str(&format!(" {} = {:?}\n", "name", &self.name)); 7 out.push_str(&format!(" {} = {:?}\n", "active", &self.active)); 8 out.push('}'); 9 out 10 } 11 } ``` (In the raw `cargo expand` output the `format!` calls are themselves further expanded into `::alloc::fmt::format(format_args!(...))`, because *every* macro is expanded, `format!` included. The shape above is the meaningful part.) *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript AST transform (Babel/ts plugin) | Rust procedural macro | | ------------------- | ------------------------------------------ | ------------------------------------------ | | When it runs | Build step, as a separate Node process | Inside `rustc`, during compilation | | Input | AST nodes from the parser | `TokenStream` (token trees, not full AST) | | Parsing | Done for you by the compiler | You call `syn` to parse tokens into an AST | | Output construction | String templating or AST builders | `quote!` structured interpolation | | Output checking | Re-parsed; type errors surface at runtime | Type-checked immediately as real Rust | | Hygiene | Manual; name clashes are your problem | Span-based hygiene built in | | Distribution | An npm package + build config | A crate with `proc-macro = true` | | Runtime cost | The generated JS runs at runtime | Zero — only generated code remains | ### Three flavors share one foundation [Section titled “Three flavors share one foundation”](#three-flavors-share-one-foundation) All procedural macros use `syn`/`quote`/`proc-macro2`; they differ only in their entry-point attribute and signature: | Flavor | Attribute | Signature | Invoked as | Covered in | | ------------- | ---------------------------- | --------------------------------------------- | ----------------- | ----------------------------------------------------------- | | Custom derive | `#[proc_macro_derive(Name)]` | `fn(TokenStream) -> TokenStream` | `#[derive(Name)]` | [Derive Macros](/14-macros/04-derive-macros/) | | Attribute | `#[proc_macro_attribute]` | `fn(TokenStream, TokenStream) -> TokenStream` | `#[name(args)]` | [Attribute Macros](/14-macros/05-attribute-macros/) | | Function-like | `#[proc_macro]` | `fn(TokenStream) -> TokenStream` | `name!(...)` | [Function-like Macros](/14-macros/06-function-like-macros/) | A derive macro **adds** code alongside the item it annotates (it never sees the item replaced). An attribute macro receives both its arguments and the *entire* annotated item, and returns whatever should replace it. A function-like macro receives only the tokens between its delimiters. ### Why a separate crate? [Section titled “Why a separate crate?”](#why-a-separate-crate) A `proc-macro` crate is compiled *for the compiler’s own host* and loaded as a plugin while it compiles your other crates. That is a fundamentally different compilation target from your application, so the macro logic must live in its own crate that *only* exports macros (this is enforced; see the pitfalls). The common pattern in published libraries is a pair: a `foo_derive` proc-macro crate and a `foo` crate that re-exports it, so users only depend on `foo`. `serde` does exactly this with `serde` and `serde_derive`. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Putting a proc macro in a normal crate [Section titled “Pitfall 1: Putting a proc macro in a normal crate”](#pitfall-1-putting-a-proc-macro-in-a-normal-crate) The `#[proc_macro_derive]` family is only legal in a crate with `proc-macro = true`. Forget the flag and you get two errors at once: ```rust 1 // in a crate WITHOUT `proc-macro = true` in Cargo.toml 2 use proc_macro::TokenStream; // does not compile (error E0432) 3 4 #[proc_macro_derive(Oops)] // does not compile 5 pub fn derive_oops(_input: TokenStream) -> TokenStream { 6 TokenStream::new() 7 } ``` Real compiler errors: ```text 1 error: the `#[proc_macro_derive]` attribute is only usable with crates of the `proc-macro` crate type 2 --> src/lib.rs:3:1 3 | 4 3 | #[proc_macro_derive(Oops)] 5 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ 6 7 error[E0432]: unresolved import `proc_macro` 8 --> src/lib.rs:1:5 9 | 10 1 | use proc_macro::TokenStream; 11 | ^^^^^^^^^^ use of unresolved module or unlinked crate `proc_macro` ``` The fix is to add `[lib]` with `proc-macro = true` to the crate’s `Cargo.toml`. The `proc_macro` crate only becomes importable once that flag is set. ### Pitfall 2: Confusing `proc_macro::TokenStream` with `proc_macro2::TokenStream` [Section titled “Pitfall 2: Confusing proc\_macro::TokenStream with proc\_macro2::TokenStream”](#pitfall-2-confusing-proc_macrotokenstream-with-proc_macro2tokenstream) These are two distinct types with the same name. `syn` and `quote` produce `proc_macro2::TokenStream`, but your entry point must return `proc_macro::TokenStream`. Forget the `.into()` and: ```rust 1 // inside #[proc_macro_derive], returning the quote! result directly: 2 let expanded = quote! { /* ... */ }; 3 expanded // does not compile (error E0308) — missing `.into()` ``` Real compiler error (excerpt): ```text 1 error[E0308]: mismatched types 2 --> describe_derive/src/lib.rs:54:5 3 | 4 6 | pub fn derive_describe(input: TokenStream) -> TokenStream { 5 | ----------- expected `proc_macro::TokenStream` because of return type 6 ... 7 54 | expanded 8 | ^^^^^^^^ expected `proc_macro::TokenStream`, found `proc_macro2::TokenStream` 9 | 10 = note: `proc_macro2::TokenStream` and `proc_macro::TokenStream` have similar names, but are actually distinct types 11 help: call `Into::into` on this expression to convert `proc_macro2::TokenStream` into `proc_macro::TokenStream` 12 | 13 54 | expanded.into() 14 | +++++++ ``` The compiler even suggests the fix: `expanded.into()`. A clean convention is to keep all internal logic in `proc_macro2` and only convert at the very edges of the entry function. ### Pitfall 3: Returning a parse error as a panic instead of `compile_error!` [Section titled “Pitfall 3: Returning a parse error as a panic instead of compile\_error!”](#pitfall-3-returning-a-parse-error-as-a-panic-instead-of-compile_error) A tempting but bad habit is `let ast = syn::parse2(input).unwrap();`. If parsing fails, your macro *panics*, and the user sees an opaque “proc-macro panicked” message with no useful span. Instead, return errors as tokens: `syn::Error` has `.to_compile_error()` (one error) and `.into_compile_error()` (consuming form), and `parse_macro_input!` does this for you automatically. Always propagate errors through the token stream so the user gets a real, located diagnostic pointing at *their* code, as the `Describe` derive does for enums (see Pitfall 4). ### Pitfall 4: Forgetting to handle struct shapes (and emitting a vague error) [Section titled “Pitfall 4: Forgetting to handle struct shapes (and emitting a vague error)”](#pitfall-4-forgetting-to-handle-struct-shapes-and-emitting-a-vague-error) If you only handle named-field structs, decide what happens for everything else. The `Describe` derive returns a clear `compile_error!` for enums. With it applied to an enum: ```rust 1 #[derive(Describe)] // does not compile — Describe rejects enums on purpose 2 enum Shape { 3 Circle, 4 Square, 5 } ``` Real compiler error: ```text 1 error: Describe can only be derived for structs 2 --> consumer/src/main.rs:4:6 3 | 4 4 | enum Shape { 5 | ^^^^^ ``` Because we built the error with `new_spanned(&ast.ident, ...)`, it underlines `Shape` — the user’s type — instead of something inside the macro. Compare that to an unwrapped panic, which would point nowhere useful. ### Pitfall 5: Slow iteration and forgetting the `full` feature [Section titled “Pitfall 5: Slow iteration and forgetting the full feature”](#pitfall-5-slow-iteration-and-forgetting-the-full-feature) `syn` is feature-gated to keep compile times down. The default features parse derive inputs and types; parsing whole function bodies, expressions, or statements needs `features = ["full"]`. If `syn::parse2::<ItemFn>(...)` fails to resolve or behaves oddly, check that you enabled `full`. And because every edit to a proc-macro crate recompiles `syn`, keep the macro crate small and test the pure logic with `proc-macro2` (next section) rather than recompiling the whole consumer each time. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Split a testable core from the thin entry point [Section titled “Split a testable core from the thin entry point”](#split-a-testable-core-from-the-thin-entry-point) The `proc_macro` types cannot be used outside the compiler, so wrap them at the boundary and put all real logic in a function over `proc_macro2::TokenStream`. That core is unit-testable like any function: ```rust 1 use proc_macro::TokenStream; 2 use proc_macro2::TokenStream as TokenStream2; 3 use quote::quote; 4 use syn::{parse2, DeriveInput}; 5 6 // Thin shim: convert, delegate, convert back. The only `proc_macro` contact. 7 #[proc_macro_derive(Named)] 8 pub fn derive_named(input: TokenStream) -> TokenStream { 9 expand(input.into()) 10 .unwrap_or_else(syn::Error::into_compile_error) 11 .into() 12 } 13 14 // Pure core: uses only proc_macro2, so it runs on the host and in tests. 15 fn expand(input: TokenStream2) -> syn::Result<TokenStream2> { 16 let ast: DeriveInput = parse2(input)?; 17 let name = &ast.ident; 18 let label = name.to_string(); 19 Ok(quote! { 20 impl #name { 21 pub fn type_name(&self) -> &'static str { #label } 22 } 23 }) 24 } 25 26 #[cfg(test)] 27 mod tests { 28 use super::expand; 29 use quote::quote; 30 31 #[test] 32 fn generates_type_name_impl() { 33 let input = quote! { struct Widget { id: u32 } }; 34 let output = expand(input).unwrap().to_string(); 35 assert!(output.contains("impl Widget")); 36 assert!(output.contains("\"Widget\"")); 37 } 38 } ``` Real output of `cargo test -p` on this crate: ```text 1 running 1 test 2 test tests::generates_type_name_impl ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out ``` Note how `expand` returns `syn::Result<TokenStream2>` and the shim funnels any error into `into_compile_error()`. This is the idiomatic shape used across the ecosystem. (For end-to-end tests that check the macro produces a *compile error* on bad input, reach for [`trybuild`](https://crates.io/crates/trybuild); see [Testing](/13-testing/).) ### Always preserve generics [Section titled “Always preserve generics”](#always-preserve-generics) A derive that assumes the type has no generics breaks the moment someone writes `struct Wrapper<T>`. `syn` makes this trivial with `split_for_impl`, which yields the three pieces an `impl` needs: ```rust 1 let (impl_generics, ty_generics, where_clause) = ast.generics.split_for_impl(); 2 let expanded = quote! { 3 impl #impl_generics #name #ty_generics #where_clause { 4 // ... 5 } 6 }; ``` This expands to `impl<T> Wrapper<T> where ... { ... }` automatically. If your impl requires a bound on each type parameter (e.g. `T: Debug`), add it to `ast.generics` before splitting. ### Use helper attributes instead of magic conventions [Section titled “Use helper attributes instead of magic conventions”](#use-helper-attributes-instead-of-magic-conventions) When a derive needs per-field configuration, declare **inert helper attributes** in the `attributes(...)` list rather than inventing naming conventions. This is exactly how `serde` offers `#[serde(rename = "...")]`. The Real-World Example below shows the full pattern with `attr.parse_nested_meta`. ### Point spans at the user’s code, and prefer `quote_spanned!` for generated bounds [Section titled “Point spans at the user’s code, and prefer quote\_spanned! for generated bounds”](#point-spans-at-the-users-code-and-prefer-quote_spanned-for-generated-bounds) Every diagnostic your macro emits should underline something in *their* source. Use `syn::Error::new_spanned(&offending_node, msg)` so the squiggle lands on the right token. When generated code itself can fail to compile (a missing trait bound, say), `quote_spanned!` lets you attribute that failure to a meaningful user span instead of an opaque macro location. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored custom derive, `Report`, that turns a struct into a human-readable report and supports two **helper attributes**: `#[report(label = "...")]` to rename a field and `#[report(skip)]` to omit a sensitive field. This mirrors how real derives (`serde`, `clap`) are configured per field. The macro crate, `report_derive/src/lib.rs` (with `proc-macro = true` and the same `syn`/`quote`/`proc-macro2` dependencies): ```rust 1 use proc_macro::TokenStream; 2 use quote::quote; 3 use syn::{parse_macro_input, Data, DeriveInput, Fields, LitStr}; 4 5 /// Derives `report(&self) -> String`. Configure per field with 6 /// `#[report(label = "Nice Name")]` and `#[report(skip)]`. 7 #[proc_macro_derive(Report, attributes(report))] 8 pub fn derive_report(input: TokenStream) -> TokenStream { 9 let ast = parse_macro_input!(input as DeriveInput); 10 let name = &ast.ident; 11 12 // let-else gives a clean early exit with a real compile error. 13 let Data::Struct(data) = &ast.data else { 14 return syn::Error::new_spanned(name, "Report can only be derived for structs") 15 .to_compile_error() 16 .into(); 17 }; 18 let Fields::Named(fields) = &data.fields else { 19 return syn::Error::new_spanned(name, "Report needs named fields") 20 .to_compile_error() 21 .into(); 22 }; 23 24 let mut lines = Vec::new(); 25 for field in &fields.named { 26 let ident = field.ident.as_ref().unwrap(); 27 let mut label = ident.to_string(); 28 let mut skip = false; 29 30 // Parse each `#[report(...)]` helper attribute on this field. 31 for attr in &field.attrs { 32 if !attr.path().is_ident("report") { 33 continue; 34 } 35 let parsed = attr.parse_nested_meta(|meta| { 36 if meta.path.is_ident("skip") { 37 skip = true; 38 Ok(()) 39 } else if meta.path.is_ident("label") { 40 let value: LitStr = meta.value()?.parse()?; 41 label = value.value(); 42 Ok(()) 43 } else { 44 Err(meta.error("unknown `report` option")) 45 } 46 }); 47 if let Err(e) = parsed { 48 return e.to_compile_error().into(); 49 } 50 } 51 52 if skip { 53 continue; 54 } 55 lines.push(quote! { 56 rows.push(format!("{}: {:?}", #label, &self.#ident)); 57 }); 58 } 59 60 let expanded = quote! { 61 impl #name { 62 pub fn report(&self) -> String { 63 let mut rows: Vec<String> = Vec::new(); 64 #( #lines )* 65 rows.join("\n") 66 } 67 } 68 }; 69 expanded.into() 70 } ``` The consumer crate: ```rust 1 use report_derive::Report; 2 3 #[derive(Report)] 4 struct Account { 5 #[report(label = "Account ID")] 6 id: u64, 7 #[report(label = "Owner")] 8 owner: String, 9 #[report(skip)] 10 #[allow(dead_code)] // never read because `report` skips it 11 password_hash: String, 12 } 13 14 fn main() { 15 let acct = Account { 16 id: 42, 17 owner: "Grace".to_string(), 18 password_hash: "do-not-print".to_string(), 19 }; 20 println!("{}", acct.report()); 21 } ``` Real output: ```text 1 Account ID: 42 2 Owner: "Grace" ``` The `password_hash` field is omitted entirely because of `#[report(skip)]`, and the two visible fields use their custom labels. The key API is `attr.parse_nested_meta`, the `syn` 2 way to walk the comma-separated options inside `#[report(...)]`: `meta.path.is_ident("skip")` matches a bare flag, while `meta.value()?.parse::<LitStr>()?` reads the right-hand side of `label = "..."`. Anything unrecognized returns `meta.error(...)`, which surfaces as a located compile error on the user’s attribute, never a panic. > **Note:** `syn` 2.0 replaced the older 1.x `Attribute::parse_meta` / `NestedMeta` API with `Meta` plus `parse_nested_meta`. If you find a tutorial using `NestedMeta` or `AttributeArgs`, it targets `syn` 1 and will not compile against `syn` 2. Always check the version. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Rust Reference — Procedural Macros](https://doc.rust-lang.org/reference/procedural-macros.html): the authoritative spec for derive, attribute, and function-like proc macros. * [The Rust Book — Macros](https://doc.rust-lang.org/book/ch20-05-macros.html): includes a worked custom-derive walkthrough. * [`syn` documentation](https://docs.rs/syn) and the [`syn` examples directory](https://github.com/dtolnay/syn/tree/master/examples): a full `derive(HeapSize)` example among others. * [`quote` documentation](https://docs.rs/quote) — interpolation and repetition with `#(...)*`. * [`proc-macro2` documentation](https://docs.rs/proc-macro2) — the host-usable `TokenStream`. * [`cargo-expand`](https://github.com/dtolnay/cargo-expand) and [`trybuild`](https://crates.io/crates/trybuild): inspect expansions and test compile-fail cases. ### Related sections in this guide [Section titled “Related sections in this guide”](#related-sections-in-this-guide) * Foundation: [Macro Basics](/14-macros/00-macro-basics/): why macros are compile-time, token-based, and hygienic. * [Derive Macros](/14-macros/04-derive-macros/) — what `#[derive(...)]` generates and a custom-derive overview. * [Attribute Macros](/14-macros/05-attribute-macros/): the `#[proc_macro_attribute]` flavor. * [Function-like Macros](/14-macros/06-function-like-macros/) — the `#[proc_macro]` `name!(...)` flavor. * Contrast: [Declarative Macros](/14-macros/01-declarative-macros/), [Macro Patterns](/14-macros/02-macro-patterns/), and [Repetition](/14-macros/03-repetition/) cover `macro_rules!`, which needs no extra crates. * [Common Macros](/14-macros/08-common-macros/) — the standard-library macros you will use daily. * Testing your macros: [Section 13 — Testing](/13-testing/). * The payoff in practice: [Serialization](/15-serialization/) is built on the `#[derive(Serialize, Deserialize)]` proc macros. * Background: [Getting Started](/01-getting-started/) (crates and `cargo`), [Basics](/02-basics/), and the [Introduction](/00-introduction/). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1 [Section titled “Exercise 1”](#exercise-1) **Difficulty:** Easy **Objective:** Get a proc-macro crate building and prove the entry-point conversion to yourself. **Instructions:** Create a `proc-macro` crate that exposes a `#[proc_macro_derive(TypeName)]` macro generating a `type_name(&self) -> &'static str` method returning the struct’s name as a string literal. You do not need to inspect fields. Apply it to a struct in a consumer crate and print the result. Remember the `[lib] proc-macro = true` flag and the final `.into()`. type\_name\_derive/src/lib.rs ```rust 1 use proc_macro::TokenStream; 2 use quote::quote; 3 use syn::{parse_macro_input, DeriveInput}; 4 5 #[proc_macro_derive(TypeName)] 6 pub fn derive_type_name(input: TokenStream) -> TokenStream { 7 // TODO: parse, grab the ident, emit an impl with a type_name method 8 todo!() 9 } ``` Solution ```rust 1 // type_name_derive/src/lib.rs (crate has `proc-macro = true`, deps: syn 2, quote 1) 2 use proc_macro::TokenStream; 3 use quote::quote; 4 use syn::{parse_macro_input, DeriveInput}; 5 6 #[proc_macro_derive(TypeName)] 7 pub fn derive_type_name(input: TokenStream) -> TokenStream { 8 let ast = parse_macro_input!(input as DeriveInput); 9 let name = &ast.ident; 10 let label = name.to_string(); 11 let expanded = quote! { 12 impl #name { 13 pub fn type_name(&self) -> &'static str { #label } 14 } 15 }; 16 expanded.into() 17 } ``` consumer/src/main.rs ```rust 1 use type_name_derive::TypeName; 2 3 #[derive(TypeName)] 4 struct Widget { 5 #[allow(dead_code)] 6 id: u32, 7 } 8 9 fn main() { 10 let w = Widget { id: 1 }; 11 println!("{}", w.type_name()); 12 } ``` Output: ```text 1 Widget ``` The `#label` interpolates the type name as a string literal; `.into()` converts the `quote!` result to the `proc_macro::TokenStream` the signature demands. ### Exercise 2 [Section titled “Exercise 2”](#exercise-2) **Difficulty:** Medium **Objective:** Write a *function-like* procedural macro and parse a literal from its input, a different entry point from a derive. **Instructions:** Add a `#[proc_macro]` function `stars` so that `stars!(5)` expands to the `&str` literal `"*****"`, computed at compile time. Parse the input as a `syn::LitInt`, read it with `base10_parse::<usize>()`, build the string, and emit it as a literal with `quote!`. Verify `stars!(5)` prints five stars. ```rust 1 use proc_macro::TokenStream; 2 use quote::quote; 3 use syn::{parse_macro_input, LitInt}; 4 5 #[proc_macro] 6 pub fn stars(input: TokenStream) -> TokenStream { 7 // TODO: parse a LitInt, repeat "*", emit the &str literal 8 todo!() 9 } ``` Solution ```rust 1 // in a `proc-macro = true` crate (deps: syn 2, quote 1, proc-macro2 1) 2 use proc_macro::TokenStream; 3 use quote::quote; 4 use syn::{parse_macro_input, LitInt}; 5 6 #[proc_macro] 7 pub fn stars(input: TokenStream) -> TokenStream { 8 let n = parse_macro_input!(input as LitInt); 9 let count: usize = n.base10_parse().unwrap(); 10 let s = "*".repeat(count); 11 quote! { #s }.into() 12 } ``` ```rust 1 // consumer 2 use star_macro::stars; 3 4 fn main() { 5 const BANNER: &str = stars!(5); 6 println!("banner = {BANNER}"); 7 } ``` Output: ```text 1 banner = ***** ``` Because the string is built during compilation, `BANNER` is a genuine `&'static str` constant — there is no runtime work. See [Function-like Macros](/14-macros/06-function-like-macros/) for more on this flavor. ### Exercise 3 [Section titled “Exercise 3”](#exercise-3) **Difficulty:** Hard **Objective:** Inspect fields *and* handle generics correctly with `split_for_impl`. **Instructions:** Write a `#[proc_macro_derive(FieldCount)]` that adds an associated constant `FIELD_COUNT: usize` equal to the number of fields, and that works for generic structs such as `Pair<T>`. Count named, unnamed (tuple-struct), and unit shapes. Use `ast.generics.split_for_impl()` so the generated `impl` carries the type parameters. Verify `Pair::<i32>::FIELD_COUNT == 2`. ```rust 1 use proc_macro::TokenStream; 2 use quote::quote; 3 use syn::{parse_macro_input, Data, DeriveInput, Fields}; 4 5 #[proc_macro_derive(FieldCount)] 6 pub fn derive_field_count(input: TokenStream) -> TokenStream { 7 // TODO: count fields by shape, split generics, emit `const FIELD_COUNT` 8 todo!() 9 } ``` Solution ```rust 1 // in a `proc-macro = true` crate (deps: syn 2, quote 1, proc-macro2 1) 2 use proc_macro::TokenStream; 3 use quote::quote; 4 use syn::{parse_macro_input, Data, DeriveInput, Fields}; 5 6 #[proc_macro_derive(FieldCount)] 7 pub fn derive_field_count(input: TokenStream) -> TokenStream { 8 let ast = parse_macro_input!(input as DeriveInput); 9 let name = &ast.ident; 10 let (impl_generics, ty_generics, where_clause) = ast.generics.split_for_impl(); 11 12 let count = match &ast.data { 13 Data::Struct(d) => match &d.fields { 14 Fields::Named(f) => f.named.len(), 15 Fields::Unnamed(f) => f.unnamed.len(), 16 Fields::Unit => 0, 17 }, 18 _ => 0, 19 }; 20 21 quote! { 22 impl #impl_generics #name #ty_generics #where_clause { 23 pub const FIELD_COUNT: usize = #count; 24 } 25 } 26 .into() 27 } ``` ```rust 1 // consumer 2 use field_count_derive::FieldCount; 3 4 #[derive(FieldCount)] 5 struct Pair<T> { 6 #[allow(dead_code)] 7 first: T, 8 #[allow(dead_code)] 9 second: T, 10 } 11 12 fn main() { 13 println!("Pair<i32> has {} fields", Pair::<i32>::FIELD_COUNT); 14 } ``` Output: ```text 1 Pair<i32> has 2 fields ``` `split_for_impl` produces the three fragments that expand to `impl<T> Pair<T> { ... }`. Without it, the generated `impl Pair { ... }` would fail to compile for any generic type, because `Pair` alone is not a complete type. The field count is a compile-time `usize` constant baked into the binary. # Common Standard-Library Macros > Rust's everyday macros (vec!, println!, format!, write!, matches!, assert!, dbg!, todo!, include_str!) mapped to the TS and JS features you already know. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Rust’s standard library ships a small toolbox of **built-in macros** — `vec!`, `println!`, `format!`, `write!`, `matches!`, the `assert*!` family, `todo!`, `unimplemented!`, `dbg!`, `include_str!`, and friends — that you will reach for constantly. They look like function calls but are expanded at compile time, which is exactly why they can do things ordinary functions cannot: take a variable number of typed arguments, check format strings at compile time, build a `Vec` of any element type, or read a file into your binary before the program ever runs. This page is a practical tour of the ones a TypeScript/JavaScript developer meets in the first week of writing Rust. > **Note:** The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects the newest edition automatically. Every Rust snippet here was compiled and run on stable. > **Tip:** These are *uses* of macros, not lessons in *writing* them. For the mental model of what a macro is (and is not), see [Macro Basics](/14-macros/00-macro-basics/); to write your own, see [Declarative Macros with `macro_rules!`](/14-macros/01-declarative-macros/) and [Procedural Macros](/14-macros/07-proc-macros/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript/JavaScript the equivalents are scattered across language features and standard library functions, none of which run at compile time. You build arrays with literals, format with template literals or helpers, accumulate strings by concatenation, test shapes with `typeof`/`instanceof`, and assert with `console.assert` (which famously does **not** throw). ```typescript 1 // Build a list — an array literal. 2 const evens: number[] = [2, 4, 6, 8]; 3 const zeros: number[] = new Array(4).fill(0); 4 5 // Format / print — template literals + console.log, and a returned string. 6 const name = "Ada"; 7 const score = 0.8137; 8 console.log(`Hello, ${name}!`); 9 console.log(score.toFixed(2)); // "0.81" 10 console.log("right".padStart(8)); // " right" 11 const pct = (score * 100).toFixed(0); 12 const summary = `${name} scored ${pct}%`; // build a string, don't print it 13 14 // Accumulate text into a buffer — string concatenation. 15 let report = ""; 16 ["Berlin", "Lyon"].forEach((city, i) => { 17 report += `${i}: ${city}\n`; 18 }); 19 20 // Test the shape of a value — typeof / instanceof / a discriminant check. 21 type Event = 22 | { kind: "click"; x: number; y: number } 23 | { kind: "key"; code: string } 24 | { kind: "close" }; 25 const e: Event = { kind: "key", code: "q" }; 26 const isQuit = e.kind === "key" && e.code === "q"; 27 28 // Assert an invariant — console.assert does NOT throw; it just logs and continues. 29 console.assert(evens.length > 0, "expected non-empty"); 30 31 // "Not done yet" — throw a placeholder. 32 function render(width: number): string { 33 throw new Error("not implemented"); 34 } 35 36 // Quick debug print — console.log returns undefined, so you can't inline it cleanly. 37 const doubled = evens.map((n) => n * 2); 38 console.log("doubled", doubled); ``` Three things to carry into Rust. First, `console.assert` **logs and keeps running** — it is not a hard stop. Second, `console.log(obj)` prints a structured view like `{ name: 'Bob' }`, not `[object Object]`. Third, none of this happens at compile time: a template literal, a `.fill()`, a `throw` — all run when the program runs. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same jobs map onto standard macros. Each one is expanded into ordinary, fully type-checked Rust at compile time. ```rust 1 use std::fmt::Write as _; // brings the write!/writeln! target trait into scope 2 3 fn main() { 4 // vec! — build a Vec. Two forms: a list, or "value; count". 5 let evens: Vec<i32> = vec![2, 4, 6, 8]; 6 let zeros = vec![0u8; 4]; // [0, 0, 0, 0] 7 println!("evens = {evens:?}"); 8 println!("zeros = {zeros:?}"); 9 10 // println! / format! — formatted output. format! returns a String instead of printing. 11 let name = "Ada"; 12 let score = 0.8137; 13 println!("Hello, {name}!"); // inline capture of `name` 14 println!("{score:.2}"); // 0.81 — two decimals 15 println!("{:>8}", "right"); // right-aligned in 8 columns 16 let pct = score * 100.0; 17 let summary = format!("{name} scored {pct:.0}%"); // build, don't print 18 println!("built string = {summary}"); 19 20 // writeln! — like println! but writes into a buffer (here, a String). 21 let mut report = String::new(); 22 for (i, city) in ["Berlin", "Lyon"].iter().enumerate() { 23 writeln!(report, "{i}: {city}").unwrap(); 24 } 25 print!("{report}"); 26 27 // matches! — test whether a value matches a pattern, returns bool. 28 let e = Event::Key('q'); 29 let is_quit = matches!(e, Event::Key('q')); 30 println!("is_quit = {is_quit}"); 31 32 // assert! family — panics (aborts the thread) if the condition is false. 33 assert!(!evens.is_empty(), "expected non-empty"); 34 assert_eq!(evens.len(), 4); 35 36 // dbg! — print "file:line = value" to stderr AND return the value, so it inlines. 37 let doubled: Vec<i32> = evens.iter().map(|n| dbg!(n * 2)).collect(); 38 println!("doubled = {doubled:?}"); 39 } 40 41 #[derive(Debug)] 42 enum Event { 43 Click { x: i32, y: i32 }, 44 Key(char), 45 Close, 46 } ``` Real output (stdout and stderr interleaved): ```text 1 evens = [2, 4, 6, 8] 2 zeros = [0, 0, 0, 0] 3 Hello, Ada! 4 0.81 5 right 6 built string = Ada scored 81% 7 0: Berlin 8 1: Lyon 9 is_quit = true 10 [src/main.rs:37:50] n * 2 = 4 11 [src/main.rs:37:50] n * 2 = 8 12 [src/main.rs:37:50] n * 2 = 12 13 [src/main.rs:37:50] n * 2 = 16 14 doubled = [4, 8, 12, 16] ``` The big behavioral contrast jumps out immediately: Rust’s `assert!` **panics** (a hard stop), unlike `console.assert` which merely logs. And `dbg!` returns its argument, so you can wrap any subexpression without restructuring your code. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `vec!` — make a `Vec` [Section titled “vec! — make a Vec”](#vec--make-a-vec) `vec![]` has two forms, both expanded at compile time: * `vec![a, b, c]` — a comma list of elements (trailing comma allowed). * `vec![value; count]` — `count` copies of `value` (the value must be `Clone`). A plain function could not provide both forms with a single name and arbitrary arity; the macro can, because it expands to different code per call site. There is nothing magic about the element type; it is inferred or annotated like any other value. (For how a `vec!`-style macro is built from repetition, see [Macro Repetition](/14-macros/03-repetition/).) ### `println!` / `print!` / `eprintln!` / `format!` — formatting [Section titled “println! / print! / eprintln! / format! — formatting”](#println--print--eprintln--format--formatting) These share one **format string** mini-language. The key rules: * The first argument **must be a string literal**; it is parsed at compile time. You cannot pass a `String` variable as the format string. * `{}` uses the `Display` trait (human-readable); `{:?}` uses `Debug` (developer-readable); `{:#?}` is pretty-printed `Debug`. * **Inline captures**: `{name}` reads a variable named `name` in scope. This is the modern, preferred style (stable since Rust 1.58) and replaces the older `"{}", name` positional form for simple cases. * **Format specs** go after a colon: `{score:.2}` (2 decimals), `{:>8}` (right-align, width 8), `{:08.3}` (zero-pad to width 8 with 3 decimals), `{n:b}` (binary), `{n:x}` (hex). * `format!` returns a `String`; `println!`/`print!` write to stdout; `eprintln!`/`eprint!` write to stderr; `panic!` uses the same syntax to build its message. This is the rough analogue of template literals, but checked at compile time: a `{}` with no matching argument is a compile error, not a silent `undefined`. ### `write!` / `writeln!` — formatted output into a target [Section titled “write! / writeln! — formatted output into a target”](#write--writeln--formatted-output-into-a-target) `write!(target, "...", ...)` uses the same format language but writes into a `target` instead of stdout. The target is anything implementing `std::fmt::Write` (e.g. `String`) or `std::io::Write` (e.g. `Vec<u8>`, a `File`, a socket). Because the write can fail (a file might error), these macros **return a `Result`**, which is why you see `.unwrap()` or `?` after them. This is the idiomatic way to build up text efficiently without repeated `+ "..."` allocations. ### `matches!` — pattern test as a boolean [Section titled “matches! — pattern test as a boolean”](#matches--pattern-test-as-a-boolean) `matches!(value, PATTERN)` expands to a `match` that returns `true` for the pattern and `false` otherwise. It supports the full pattern grammar — bindings, `|` alternatives, ranges, and `if` guards — so it is far more expressive than a single `===` check. It is the cleanest way to ask “is this value one of these shapes?” without writing a full `match`. ### `assert!`, `assert_eq!`, `assert_ne!` — invariants [Section titled “assert!, assert\_eq!, assert\_ne! — invariants”](#assert-assert_eq-assert_ne--invariants) * `assert!(cond)` panics if `cond` is false; you may add a custom message: `assert!(cond, "msg {x}", x = x)` (or inline-capture form). * `assert_eq!(a, b)` / `assert_ne!(a, b)` compare and, on failure, **print both values**. They require the operands to implement `PartialEq` (to compare) and `Debug` (to print on failure). * `debug_assert!` / `debug_assert_eq!` compile to nothing in release builds. Use them for expensive checks you only want in debug mode. Unlike `console.assert`, a failed Rust assertion **panics**: it unwinds the current thread (the process exits with a nonzero code unless caught). Assertions are for *bugs* (broken invariants), not for expected runtime errors; those use `Result` (see [08-error-handling](/08-error-handling/)). ### `todo!` / `unimplemented!` / `unreachable!` / `panic!` [Section titled “todo! / unimplemented! / unreachable! / panic!”](#todo--unimplemented--unreachable--panic) These all panic, but communicate different intents: * `todo!()`: “I will implement this later.” Panics with `not yet implemented`. * `unimplemented!()` — “This is intentionally not supported here.” Panics with `not implemented`. * `unreachable!()`: “Control flow can never reach this point.” Panics if it somehow does. * `panic!("msg")` — unconditional abort with your message. Importantly, all four **return the never type `!`**, which coerces to *any* type. That is why `todo!()` type-checks as the body of a function that is supposed to return a `String`: the compiler accepts the stub so the rest of your code compiles while you fill in the real logic. A `throw` in TypeScript does not give you that type-level convenience. ### `dbg!` — inspect-and-return debugging [Section titled “dbg! — inspect-and-return debugging”](#dbg--inspect-and-return-debugging) `dbg!(expr)` prints `[file:line:col] expr = value` to **stderr** using `Debug`, then **returns the value**. Because it returns the value, you can wrap any subexpression in place — `let x = dbg!(a + b);` — without breaking the data flow. One gotcha: `dbg!(x)` takes `x` **by value** (it moves non-`Copy` types). Use `dbg!(&x)` to borrow instead. Remove `dbg!` calls before committing; `println!`/`tracing` are for permanent output. ### `include_str!` / `include_bytes!` / `env!` / `concat!` / `stringify!` [Section titled “include\_str! / include\_bytes! / env! / concat! / stringify!”](#include_str--include_bytes--env--concat--stringify) These do compile-time work that has no TypeScript equivalent in the language itself: * `include_str!("path")` reads a file **at compile time** and embeds its contents as a `&'static str` baked into the binary. `include_bytes!` does the same as `&'static [u8]`. Paths are relative to the current source file. * `env!("VAR")` reads an environment variable **at compile time** (compile error if missing). `option_env!` yields `Option` instead. * `concat!("a", "b")` joins literals into one `&'static str` at compile time. * `stringify!(tokens)` turns the literal source tokens into a string **without evaluating them**: `stringify!(1 + 2)` is `"1 + 2"`, not `"3"`. ```rust 1 fn main() { 2 // include_str! bakes a file's contents into the binary at compile time. 3 const BANNER: &str = include_str!("../banner.txt"); 4 print!("{BANNER}"); 5 6 let label = stringify!(1 + 2 * 3); // tokens, not the result 7 println!("label = {label}"); 8 9 println!("built crate: {}", env!("CARGO_PKG_NAME")); 10 const GREETING: &str = concat!("Hello", ", ", "world!"); 11 println!("{GREETING}"); 12 } ``` With a `banner.txt` next to the binary’s source containing `== ACME CLI v1.0 ==` followed by a trailing newline (the only newline `print!` emits here comes from the file itself), this prints: ```text 1 == ACME CLI v1.0 == 2 label = 1 + 2 * 3 3 built crate: probe 4 Hello, world! ``` *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Task | TypeScript/JavaScript | Rust macro | When it happens | | ---------------- | -------------------------------------- | --------------------------------- | ------------------------------------- | | Build a list | `[2, 4, 6, 8]` array literal | `vec![2, 4, 6, 8]` | compile-time expansion | | `n` copies | `new Array(4).fill(0)` | `vec![0u8; 4]` | compile-time expansion | | Print formatted | `console.log(\`${name}\`)\` | `println!("{name}")` | format string checked at compile time | | Build a string | template literal | `format!("{name}")` | compile-time-checked, runtime-built | | Append to buffer | `s += "..."` | `write!(&mut s, "...")` | returns `Result` | | Shape test | `e.kind === "key"` | `matches!(e, Event::Key(_))` | full pattern grammar | | Assert invariant | `console.assert` (logs, continues) | `assert!` (**panics**) | runtime panic on failure | | Placeholder | `throw new Error("todo")` | `todo!()` (type `!`) | coerces to any return type | | Inline debug | `console.log(x)` (returns `undefined`) | `dbg!(x)` (**returns x**) | inlines anywhere | | Embed a file | read at runtime (`fs.readFileSync`) | `include_str!` (**compile time**) | baked into binary | Three differences are worth internalizing: 1. **Format strings are checked at compile time.** `println!("{a} {b}", a = 1)` with no `b` is a compile error, not a runtime `undefined`. This is closer to a typed `printf` than to a template literal. 2. **Assertions panic.** A failed `assert!` aborts the thread; it is for catching *bugs*, whereas TypeScript’s `console.assert` is a soft log. Recoverable conditions belong in `Result`, not assertions. 3. **`include_str!`/`env!` run during compilation.** The data is in the binary; there is no file read or environment lookup at runtime. Node has nothing equivalent at the language level. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: passing a variable as the format string [Section titled “Pitfall 1: passing a variable as the format string”](#pitfall-1-passing-a-variable-as-the-format-string) The first argument to `println!`/`format!` must be a **string literal** so the compiler can parse it. ```rust 1 fn main() { 2 let msg = String::from("hello {name}"); 3 let name = "world"; 4 println!(msg); // does not compile 5 let _ = name; 6 } ``` Real compiler error: ```text 1 error: format argument must be a string literal 2 --> src/main.rs:4:14 3 | 4 4 | println!(msg); // does not compile 5 | ^^^ 6 | 7 help: you might be missing a string literal to format with 8 | 9 4 | println!("{}", msg); // does not compile 10 | +++++ ``` Fix: `println!("{msg}")` (or `println!("{}", msg)`). If you genuinely need a runtime-chosen format, that is not what `println!` does; build the string yourself. ### Pitfall 2: `dbg!` moves its argument [Section titled “Pitfall 2: dbg! moves its argument”](#pitfall-2-dbg-moves-its-argument) `dbg!(x)` takes ownership of `x` (it returns the value). For a non-`Copy` type, that moves it. ```rust 1 fn main() { 2 let v = vec![1, 2, 3]; 3 dbg!(v); 4 println!("{}", v.len()); // does not compile 5 } ``` Real compiler error (abridged): ```text 1 error[E0382]: borrow of moved value: `v` 2 --> src/main.rs:4:20 3 | 4 2 | let v = vec![1, 2, 3]; 5 | - move occurs because `v` has type `Vec<i32>`, which does not implement the `Copy` trait 6 3 | dbg!(v); 7 | ------- value moved here 8 4 | println!("{}", v.len()); // does not compile 9 | ^ value borrowed here after move 10 | 11 help: consider borrowing instead of transferring ownership 12 | 13 3 | dbg!(&v); 14 | + ``` Fix: borrow with `dbg!(&v)`, or use the value `dbg!` returns (`let v = dbg!(v);`). ### Pitfall 3: `assert_eq!` needs `PartialEq` and `Debug` [Section titled “Pitfall 3: assert\_eq! needs PartialEq and Debug”](#pitfall-3-assert_eq-needs-partialeq-and-debug) `assert_eq!` compares with `==` (needs `PartialEq`) and prints both sides on failure (needs `Debug`). ```rust 1 struct Point { 2 x: i32, 3 y: i32, 4 } 5 6 fn main() { 7 let a = Point { x: 1, y: 2 }; 8 let b = Point { x: 1, y: 2 }; 9 assert_eq!(a, b); // does not compile: Point implements neither trait 10 } ``` Real compiler errors (abridged): ```text 1 error[E0369]: binary operation `==` cannot be applied to type `Point` 2 --> src/main.rs:9:5 3 | 4 9 | assert_eq!(a, b); // does not compile: Point implements neither trait 5 | ^^^^^^^^^^^^^^^^ 6 ... 7 help: consider annotating `Point` with `#[derive(PartialEq)]` 8 9 error[E0277]: `Point` doesn't implement `Debug` 10 --> src/main.rs:9:5 11 ... 12 help: consider annotating `Point` with `#[derive(Debug)]` ``` Fix: `#[derive(Debug, PartialEq)]` on `Point`. This is the same trait requirement you hit when printing with `{:?}`; see [Derive Macros](/14-macros/04-derive-macros/). ### Pitfall 4: expecting `assert!` to behave like `console.assert` [Section titled “Pitfall 4: expecting assert! to behave like console.assert”](#pitfall-4-expecting-assert-to-behave-like-consoleassert) In Node, a failed `console.assert` logs `Assertion failed: ...` and the program keeps running. In Rust, a failed `assert!` **panics** and unwinds the thread. Do not use assertions for input validation or recoverable errors; reach for `Result` / `?` instead (see [08-error-handling](/08-error-handling/)). Reserve `assert!` for internal invariants that, if violated, mean your code has a bug. ### Pitfall 5: forgetting the `Write` trait import for `write!` [Section titled “Pitfall 5: forgetting the Write trait import for write!”](#pitfall-5-forgetting-the-write-trait-import-for-write) `write!(my_string, ...)` will not compile unless `std::fmt::Write` is in scope, even though `String` is built in. The macro calls the trait’s `write_str`/`write_fmt` methods, and trait methods require the trait to be imported. The compiler error says ``no method named `write_fmt` found``. Fix: `use std::fmt::Write;` (for `String`) or `use std::io::Write;` (for `Vec<u8>`/files). *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Prefer inline captures.** `println!("{name} = {value:?}")` is clearer than `println!("{} = {:?}", name, value)`. Use positional/named args only when an argument is a complex expression. * **Use `format!` to build, the `print` family to emit.** Do not `println!` into the void and then reconstruct; build a `String` with `format!`/`write!`, then print or return it. * **Use `write!`/`writeln!` for loops.** Accumulating with `s += &format!(...)` allocates repeatedly; `write!(&mut s, ...)` writes in place. * **`matches!` for boolean shape checks; full `match` when you need the bound data.** If you immediately want the inner values, write a `match` or `if let`. * **Assertions are for bugs.** Use `assert!`/`assert_eq!` for invariants and in tests; use `Result` for anything a caller could reasonably hit at runtime. Use `debug_assert!` for checks too expensive for release builds. * **`todo!()` over `unimplemented!()` while iterating.** Both panic, but `todo!()` signals “coming soon” and pairs naturally with the `!` type so stubs compile. Reach for `unimplemented!()` only when a branch is intentionally unsupported. * **Strip `dbg!` before committing.** It writes to stderr and is meant to be transient. For lasting, structured diagnostics use the `tracing` crate or `eprintln!`. * **`include_str!` for embedding assets, not config that should be editable at runtime.** It bakes the file into the binary; changing the file requires a rebuild. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small trade-report builder that exercises the macros together: `include_str!` bakes in a header, `writeln!` accumulates lines into a `String`, `format!`-style specs align columns, `matches!` classifies a value, `assert!` guards an invariant, and `eprintln!` emits a diagnostic to stderr. ```rust 1 use std::fmt::Write as _; 2 3 #[derive(Debug, Clone)] 4 struct Trade { 5 symbol: String, 6 qty: i64, 7 price_cents: i64, 8 } 9 10 /// Build a plain-text report, accumulating into one String with writeln!. 11 fn build_report(trades: &[Trade]) -> String { 12 let mut out = String::new(); 13 14 // Header template is embedded into the binary at compile time. 15 out.push_str(include_str!("../report_header.txt")); 16 17 let mut total_cents: i64 = 0; 18 for t in trades { 19 let line_cents = t.qty * t.price_cents; 20 total_cents += line_cents; 21 writeln!( 22 out, 23 "{symbol:<6} {qty:>5} @ {price:>8.2} = {line:>10.2}", 24 symbol = t.symbol, 25 qty = t.qty, 26 price = t.price_cents as f64 / 100.0, 27 line = line_cents as f64 / 100.0, 28 ) 29 .expect("writing to a String never fails"); 30 } 31 32 writeln!(out, "{:-<33}", "").unwrap(); 33 writeln!(out, "TOTAL {:>26.2}", total_cents as f64 / 100.0).unwrap(); 34 out 35 } 36 37 fn classify(qty: i64) -> &'static str { 38 // matches! reads cleanly as a series of boolean range tests. 39 if matches!(qty, i64::MIN..=0) { 40 "non-positive" 41 } else if matches!(qty, 1..=100) { 42 "small" 43 } else { 44 "large" 45 } 46 } 47 48 fn main() { 49 let trades = vec![ 50 Trade { symbol: "AAPL".into(), qty: 10, price_cents: 19042 }, 51 Trade { symbol: "MSFT".into(), qty: 4, price_cents: 41310 }, 52 ]; 53 54 // Guard an invariant: a positive quantity. A violation here means a bug upstream. 55 for t in &trades { 56 assert!(t.qty > 0, "qty must be positive for {}, got {}", t.symbol, t.qty); 57 } 58 59 let report = build_report(&trades); 60 print!("{report}"); 61 62 println!("\nfirst order is {}", classify(trades[0].qty)); 63 64 // Diagnostics go to stderr so they never pollute the report on stdout. 65 eprintln!("[debug] processed {} trades", trades.len()); 66 } ``` With a `report_header.txt` (next to the source) containing `=== Trade Report ===` followed by a trailing newline (the header is `push_str`-ed verbatim, so its line break comes from that newline in the file), the program prints to stdout, then the diagnostic to stderr: ```text 1 === Trade Report === 2 AAPL 10 @ 190.42 = 1904.20 3 MSFT 4 @ 413.10 = 1652.40 4 --------------------------------- 5 TOTAL 3556.60 6 7 first order is small 8 [debug] processed 2 trades ``` Every column alignment, the dashed separator (`{:-<33}` means “pad with `-` to width 33, left-aligned”), and the totals are produced purely by format specs: no manual string padding. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Rust Book — `println!` and formatting](https://doc.rust-lang.org/book/ch05-02-example-structs.html#adding-useful-functionality-with-derived-traits) * [`std::fmt`](https://doc.rust-lang.org/std/fmt/): the full format-string syntax (fill, align, width, precision, `{:?}`, `{:#?}`, `{:b}`, `{:x}`) * [`std::macro` index](https://doc.rust-lang.org/std/#macros): every standard macro: `vec!`, `format!`, `write!`, `matches!`, `assert!`, `dbg!`, `todo!`, `include_str!`, and more * [`vec!`](https://doc.rust-lang.org/std/macro.vec.html), [`matches!`](https://doc.rust-lang.org/std/macro.matches.html), [`dbg!`](https://doc.rust-lang.org/std/macro.dbg.html), [`todo!`](https://doc.rust-lang.org/std/macro.todo.html), [`include_str!`](https://doc.rust-lang.org/std/macro.include_str.html) ### Related sections in this guide [Section titled “Related sections in this guide”](#related-sections-in-this-guide) * [Macro Basics](/14-macros/00-macro-basics/): what a macro is, and why it is **not** a function or a decorator * [Declarative Macros with `macro_rules!`](/14-macros/01-declarative-macros/): writing your own `macro_rules!` (and `cargo expand`) * [Macro Repetition](/14-macros/03-repetition/): how a `vec!`-style macro is built from repetition * [Derive Macros](/14-macros/04-derive-macros/) — `#[derive(Debug, PartialEq)]`, the traits `assert_eq!` and `{:?}` need * [Function-Like Procedural Macros](/14-macros/06-function-like-macros/) — `foo!(...)` procedural macros vs. these built-ins * [Procedural Macros](/14-macros/07-proc-macros/) — writing a custom derive with `syn` 2 + `quote` * [02-basics](/02-basics/): `println!` and formatting basics * [08-error-handling](/08-error-handling/) — `Result`/`?` for recoverable errors vs. `assert!`/`panic!` for bugs * [13-testing](/13-testing/): `assert_eq!` and the `Debug` requirement in tests * [15-serialization](/15-serialization/) — `serde`’s derives for turning structs into JSON *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1 [Section titled “Exercise 1”](#exercise-1) **Difficulty:** Beginner **Objective:** Use `format!` with alignment and precision specs to build (not print) a labeled row. **Instructions:** Implement `row(label, value)` so it returns a `String` where the label is left-aligned in 10 columns and the value is right-aligned in 8 columns with exactly 2 decimal places. For example, `row("balance", 1234.5)` should equal `"balance : 1234.50"`. ```rust 1 fn row(label: &str, value: f64) -> String { 2 /* ??? */ 3 } 4 5 fn main() { 6 println!("[{}]", row("balance", 1234.5)); 7 println!("[{}]", row("fees", 9.0)); 8 } ``` Solution Use `{label:<10}` for left-align width 10 and `{value:>8.2}` for right-align width 8, precision 2: ```rust 1 fn row(label: &str, value: f64) -> String { 2 format!("{label:<10}: {value:>8.2}") 3 } 4 5 fn main() { 6 println!("[{}]", row("balance", 1234.5)); 7 println!("[{}]", row("fees", 9.0)); 8 } ``` Output: ```text 1 [balance : 1234.50] 2 [fees : 9.00] ``` `<` is left-align, `>` is right-align, the number after each is the minimum width, and `.2` is the precision. The brackets in `main` just show that the padding is real. ### Exercise 2 [Section titled “Exercise 2”](#exercise-2) **Difficulty:** Intermediate **Objective:** Use `matches!` with `|` alternatives and a struct pattern to write a boolean classifier. **Instructions:** Implement `is_visible(&Status) -> bool` so that a `Status::Active` and any `Status::Suspended { .. }` are visible, but `Status::Deleted` is not. Use a single `matches!` call. Then make the three assertions in `main` pass. ```rust 1 #[derive(Debug)] 2 enum Status { 3 Active, 4 Suspended { reason: String }, 5 Deleted, 6 } 7 8 fn is_visible(s: &Status) -> bool { 9 /* ??? */ 10 } 11 12 fn main() { 13 assert!(is_visible(&Status::Active)); 14 assert!(is_visible(&Status::Suspended { reason: "late payment".into() })); 15 assert!(!is_visible(&Status::Deleted)); 16 println!("visibility checks passed"); 17 } ``` Solution `matches!` accepts the full pattern grammar, so a `|` alternative with a struct pattern (`{ .. }` ignores the fields) does the whole job: ```rust 1 #[derive(Debug)] 2 enum Status { 3 Active, 4 Suspended { reason: String }, 5 Deleted, 6 } 7 8 fn is_visible(s: &Status) -> bool { 9 matches!(s, Status::Active | Status::Suspended { .. }) 10 } 11 12 fn main() { 13 assert!(is_visible(&Status::Active)); 14 assert!(is_visible(&Status::Suspended { reason: "late payment".into() })); 15 assert!(!is_visible(&Status::Deleted)); 16 println!("visibility checks passed"); 17 } ``` Output: ```text 1 visibility checks passed ``` `Status::Suspended { .. }` matches the variant regardless of its `reason` field. If you wanted to *use* the `reason`, you would write a `match` or `if let` instead; `matches!` only yields a `bool`. ### Exercise 3 [Section titled “Exercise 3”](#exercise-3) **Difficulty:** Intermediate **Objective:** Combine `writeln!`, `format!` specs, and `assert_eq!` to build and verify a small CSV in memory. **Instructions:** Implement `to_csv(rows)` so it returns a `String` with a `name,count` header line followed by one `name,count` line per row. Then complete the `assert_eq!` in `main` so it checks that the result has exactly 3 lines for the given input (header + 2 rows). Remember to bring the right trait into scope for `writeln!`. ```rust 1 // TODO: a use statement is needed here 2 3 fn to_csv(rows: &[(&str, u32)]) -> String { 4 /* ??? */ 5 } 6 7 fn main() { 8 let csv = to_csv(&[("apples", 3), ("pears", 7)]); 9 print!("{csv}"); 10 assert_eq!(/* number of lines */, 3); 11 println!("csv has the expected number of lines"); 12 } ``` Solution `writeln!` into a `String` requires `use std::fmt::Write`. Build the header, loop the rows, then count lines with `.lines().count()`: ```rust 1 use std::fmt::Write as _; 2 3 fn to_csv(rows: &[(&str, u32)]) -> String { 4 let mut out = String::new(); 5 writeln!(out, "name,count").unwrap(); 6 for (name, count) in rows { 7 writeln!(out, "{name},{count}").unwrap(); 8 } 9 out 10 } 11 12 fn main() { 13 let csv = to_csv(&[("apples", 3), ("pears", 7)]); 14 print!("{csv}"); 15 assert_eq!(csv.lines().count(), 3); 16 println!("csv has the expected number of lines"); 17 } ``` Output: ```text 1 name,count 2 apples,3 3 pears,7 4 csv has the expected number of lines ``` `writeln!` returns a `Result` because the underlying write can fail; for a `String` it never does, so `.unwrap()` is fine here. The `as _` in the import brings the trait’s methods into scope without binding the name `Write` (handy when you only need the trait for its methods). # Rust Serialization with Serde > TypeScript ships JSON.parse and JSON.stringify; Rust uses Serde, splitting data types from formats so one annotated struct targets JSON, TOML, YAML, and more. In TypeScript, turning data into JSON and back is built into the language: `JSON.parse` and `JSON.stringify` are always there. Rust takes a different route: serialization lives in a single, dominant framework called **Serde** (a contraction of **ser**ialize/**de**serialize). Instead of one hard-coded JSON object, Serde splits the problem into **data types** (your structs and enums, which implement the `Serialize`/`Deserialize` traits) and **data formats** (JSON, TOML, YAML, MessagePack, …, each a separate crate) that meet through a shared **data model**. The payoff: you annotate a type once and get every format for free. And unlike `JSON.parse`, deserialization validates against a real type and returns a `Result` instead of an unchecked `any`. This section takes you from that mental model through derive macros, attributes, dynamic JSON, alternative formats, fully hand-written (de)serialization, and performance. *** ## What You’ll Learn [Section titled “What You’ll Learn”](#what-youll-learn) * How `JSON.parse`/`JSON.stringify` map onto Serde’s `Serialize`/`Deserialize` traits, and the **data-model architecture** that lets one type target every format * How to set up `serde` (with `features = ["derive"]`) and `serde_json`, and round-trip values with `to_string`/`from_str` * What `#[derive(Serialize, Deserialize)]` actually generates for structs and enums * How structs map to JSON, including nested types, `Vec`/`HashMap`, `Option` fields, and the four enum representations (externally/internally/adjacently tagged and untagged) * How to work with dynamic, schema-less JSON via `serde_json::Value` and the `json!` macro — and when to prefer typed structs instead * The common Serde attributes — `rename`, `rename_all`, `skip`, `skip_serializing_if`, `default`, `flatten`, `tag`, `with` — and what each controls * How the same derived type serializes to TOML, YAML, MessagePack, bincode, and CSV through the Serde ecosystem * How to hand-write `Serialize`/`Deserialize`, use `serialize_with`/`deserialize_with`, and apply remote derive for types you do not own * How to make serialization fast: borrowing (`&str`, `#[serde(borrow)]`), zero-copy parsing, streaming, avoiding `Value`, and reusing buffers *** ## Topics [Section titled “Topics”](#topics) | Topic | Description | | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | | [Serde Intro](/15-serialization/00-serde-intro/) | `JSON.parse`/`JSON.stringify` → Serde; the `Serialize`/`Deserialize` traits and the data-model architecture (data types ↔ formats). | | [Serde Basics](/15-serialization/01-serde-basics/) | Setting up `serde` (`features = ["derive"]`) and `serde_json`; the `to_string`/`from_str` round-trip, compile-verified. | | [Deriving Serialize/Deserialize](/15-serialization/02-derive-serialize/) | `#[derive(Serialize, Deserialize)]` on structs and enums, and what the macros generate. | | [Structs and JSON](/15-serialization/03-json/) | Structs ↔ JSON: nested types, `Vec`/`HashMap`, `Option` fields, and the four enum representations. | | [Dynamic JSON](/15-serialization/04-json-manipulation/) | Schema-less JSON with `serde_json::Value`, the `json!` macro, indexing, and when to use `Value` vs typed structs. | | [Serde Attributes](/15-serialization/05-attributes/) | `#[serde(rename, rename_all, skip, skip_serializing_if, default, flatten, tag, with)]` and the other everyday attributes. | | [Other Formats](/15-serialization/06-other-formats/) | The same data in other formats: TOML, YAML (`serde_norway`), MessagePack (`rmp-serde`), bincode, and CSV. | | [Custom Serialization](/15-serialization/07-custom-serialization/) | Hand-written `Serialize`/`Deserialize`, `serialize_with`/`deserialize_with`, and remote derive. | | [Performance](/15-serialization/08-performance/) | Borrowing (`&str`, `#[serde(borrow)]`), zero-copy, streaming, avoiding `Value`, and buffer reuse. | *** ## Learning Objectives [Section titled “Learning Objectives”](#learning-objectives) By the end of this section, you will be able to: * Explain how Serde’s data-type/data-format split differs from TypeScript’s single built-in `JSON` object, and why it makes types format-agnostic * Add and configure `serde` and `serde_json`, and round-trip your own types with `to_string`, `to_string_pretty`, and `from_str` * Derive `Serialize`/`Deserialize` for structs and enums and reason about the code the macros emit * Map realistic API payloads — nested objects, collections, optional fields, and discriminated unions — to Rust types and back * Manipulate untyped JSON with `Value` and the `json!` macro, and decide deliberately when typed structs are the better tool * Reshape the wire format with Serde attributes without changing your idiomatic Rust field names * Serialize the same type to TOML, YAML, MessagePack, bincode, and CSV by swapping the format crate * Write `Serialize`/`Deserialize` by hand when the derive is not enough, including for types you do not own * Profile and tune serialization with borrowing, zero-copy, streaming, and buffer reuse *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * [Section 08: Error Handling](/08-error-handling/): Serde’s `from_str`/`to_string` return `Result`, and deserialization errors are values you handle with `?`, `match`, or anyhow/thiserror. The error-handling vocabulary from Section 08 is assumed throughout. * Helpful but not required: [Section 09: Generics & Traits](/09-generics-traits/): `Serialize`/`Deserialize` are traits, and the derive vs. hand-written distinction lands better once trait basics and the orphan rule are familiar. *** ## Estimated Time [Section titled “Estimated Time”](#estimated-time) * **Reading:** 4-5 hours * **Hands-on Practice:** 3 hours * **Exercises:** 2 hours * **Total:** 8-10 hours > **Tip:** Read `serde-intro` → `serde-basics` → `derive-serialize` → `json` as a single connected track. That covers the 90% case of typed JSON. Pull in `json-manipulation` when you need untyped JSON and `attributes` when the wire format and your Rust names diverge. Treat `other-formats`, `custom-serialization`, and `performance` as a toolbox to reach for when a specific need arises, rather than something to master up front. *** ## Frequently asked questions [Section titled “Frequently asked questions”](#frequently-asked-questions) ### How do I parse and produce JSON in Rust? [Section titled “How do I parse and produce JSON in Rust?”](#how-do-i-parse-and-produce-json-in-rust) With Serde. Derive `Serialize` and `Deserialize` on a struct, then `serde_json::from_str` parses and `serde_json::to_string` produces JSON, type-checked against your struct instead of `any`. See [JSON with Serde](/15-serialization/03-json/) and [Serde Basics](/15-serialization/01-serde-basics/). ### How do I match JavaScript’s camelCase keys? [Section titled “How do I match JavaScript’s camelCase keys?”](#how-do-i-match-javascripts-camelcase-keys) Rust fields are snake\_case, so add `#[serde(rename_all = "camelCase")]` to the struct, or `#[serde(rename = "…")]` on a single field, to bridge Rust naming and your JSON contract. See [Serde Attributes](/15-serialization/05-attributes/). ### Can Serde handle formats other than JSON? [Section titled “Can Serde handle formats other than JSON?”](#can-serde-handle-formats-other-than-json) Yes. The same derives work with `serde_norway` (the maintained YAML crate, since `serde_yaml` is deprecated), `toml`, `bincode`, and `rmp-serde` (MessagePack) by swapping the format crate; the struct definition stays the same. See [Other Formats](/15-serialization/06-other-formats/). *** **Next:** [Section 16: Web APIs →](/16-web-apis/) — building HTTP clients and servers, where Serde does the request/response (de)serialization you just learned. # Serde: From `JSON.parse`/`JSON.stringify` to a Universal Data Model > Serde is Rust's answer to JSON.parse and JSON.stringify, but type-checked and format-agnostic: one struct serializes to JSON, TOML, YAML, and more. In TypeScript you reach for `JSON.parse` and `JSON.stringify` so often they feel like part of the language. Rust’s answer is **Serde**, a serialization framework that does the same job but with two important upgrades: it is **type-checked** (you parse *into* a known type, not into `any`) and it is **format-agnostic** (the same type serializes to JSON, TOML, YAML, MessagePack, and more). This page maps your `JSON.parse`/`JSON.stringify` instincts onto Serde’s **`Serialize`** and **`Deserialize`** traits and explains the **data-model architecture** that makes one type work with every format. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) **Serde** (a contraction of **ser**ialize/**de**serialize) is the de-facto serialization framework for Rust. Instead of one built-in `JSON` object, Serde splits the problem into two halves that meet in the middle: your **data types** (structs and enums that implement the `Serialize`/`Deserialize` traits) on one side, and **data formats** (JSON, TOML, YAML, …, each a separate crate) on the other. Because both sides talk through a shared **data model**, you write your types once and get every format for free. And unlike `JSON.parse`, deserialization validates against a real type and returns a `Result` instead of handing you an unchecked `any`. > **Note:** This page is the conceptual on-ramp. The mechanics (adding the crates, the exact `to_string`/`from_str` calls, the derive macro, attributes, and other formats) are covered in detail by the sibling pages linked throughout and in [Further Reading](#further-reading). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript, `JSON` is a global object with two methods. You typically `parse` into a value typed as `any` (or, more honestly, `unknown`) and then *assert* its shape: blog.ts ```typescript 1 interface BlogPost { 2 id: number; 3 title: string; 4 tags: string[]; 5 published: boolean; 6 } 7 8 // Serialize: an object -> a JSON string 9 const post: BlogPost = { 10 id: 42, 11 title: "Rust for TS/JS Developers", 12 tags: ["rust", "serde"], 13 published: true, 14 }; 15 16 const json: string = JSON.stringify(post); 17 console.log(json); 18 // {"id":42,"title":"Rust for TS/JS Developers","tags":["rust","serde"],"published":true} 19 20 const pretty: string = JSON.stringify(post, null, 2); // 2-space indent 21 console.log(pretty); 22 23 // Deserialize: a JSON string -> a value 24 const input = '{"id":7,"title":"Hello","tags":["intro"],"published":false}'; 25 const parsed = JSON.parse(input) as BlogPost; // <- a *cast*, not a check 26 console.log(parsed.title); // "Hello" ``` There are three things to notice, because Rust changes all three: 1. **`JSON.parse` returns `any`.** The `as BlogPost` is a compile-time *promise*, not a runtime *check*. If the JSON is the wrong shape, you find out later, somewhere else, with a confusing error. 2. **`JSON.parse` does not validate.** It happily accepts extra fields, the wrong types, or missing fields: ```typescript 1 const wrong = JSON.parse('{"id":"oops","extra":true}') as BlogPost; 2 console.log(wrong, typeof wrong.id); // { id: 'oops', extra: true } 'string' ``` No error — `id` is a string and `title` is missing, but TypeScript’s cast hides it. 3. **`JSON.stringify` is JSON-only.** Want TOML for a config file or MessagePack on the wire? That is a different library with a different API. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) In Rust, you describe the shape **once** as a struct, derive the two traits, and parse *into that type*. The format lives in a separate crate (`serde_json` here): ```toml 1 [dependencies] 2 serde = { version = "1", features = ["derive"] } 3 serde_json = "1" ``` ```rust 1 use serde::{Deserialize, Serialize}; 2 3 // The same shape as the TypeScript `interface BlogPost`. 4 #[derive(Debug, Serialize, Deserialize)] 5 struct BlogPost { 6 id: u32, 7 title: String, 8 tags: Vec<String>, 9 published: bool, 10 } 11 12 fn main() { 13 // Serialize: a value -> a JSON string (like JSON.stringify) 14 let post = BlogPost { 15 id: 42, 16 title: "Rust for TS/JS Developers".to_string(), 17 tags: vec!["rust".to_string(), "serde".to_string()], 18 published: true, 19 }; 20 21 let json: String = serde_json::to_string(&post).unwrap(); 22 println!("{json}"); 23 24 let pretty: String = serde_json::to_string_pretty(&post).unwrap(); 25 println!("{pretty}"); 26 27 // Deserialize: a JSON string -> a value (like JSON.parse, but type-checked) 28 let input = r#"{"id":7,"title":"Hello","tags":["intro"],"published":false}"#; 29 let parsed: BlogPost = serde_json::from_str(input).unwrap(); 30 println!("{parsed:?}"); 31 println!("title = {}", parsed.title); 32 } ``` Real output: ```text 1 {"id":42,"title":"Rust for TS/JS Developers","tags":["rust","serde"],"published":true} 2 { 3 "id": 42, 4 "title": "Rust for TS/JS Developers", 5 "tags": [ 6 "rust", 7 "serde" 8 ], 9 "published": true 10 } 11 BlogPost { id: 7, title: "Hello", tags: ["intro"], published: false } 12 title = Hello ``` The shapes line up almost word-for-word with the TypeScript. The differences are the important part: `serde_json::from_str` returns a **`Result`** (we `.unwrap()`ed it for brevity; see the next section), and the type it produces is a real `BlogPost`, not an `any` you have to trust. > **Note:** The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects the newest edition automatically. `cargo add serde --features derive` and `cargo add serde_json` add the dependencies above. `cargo add` has been built into Cargo since 1.62, so no extra tooling is required. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The two traits: `Serialize` and `Deserialize` [Section titled “The two traits: Serialize and Deserialize”](#the-two-traits-serialize-and-deserialize) `JSON.stringify` and `JSON.parse` are two functions. Serde splits the same idea into two **traits** (Rust’s version of interfaces) that a *type* implements: | TypeScript | Serde | | ------------------------------------------- | --------------------------------------------------------------------- | | `JSON.stringify(value)` works on any object | a type implements **`Serialize`** to say “I can be turned into data” | | `JSON.parse(text)` produces an object | a type implements **`Deserialize`** to say “I can be built from data” | When `BlogPost` derives both, the macro generates the code that walks its fields. (What that generated code looks like is covered in [Deriving `Serialize` and `Deserialize`](/15-serialization/02-derive-serialize/).) You almost never implement these traits by hand; the [`derive` macro](/15-serialization/02-derive-serialize/) does it, the same way you’d let the compiler derive `Debug`. Hand-written impls are reserved for unusual cases; see [Custom Serialization](/15-serialization/07-custom-serialization/). > **Note:** The `features = ["derive"]` part of the `serde` dependency is what enables `#[derive(Serialize, Deserialize)]`. Forgetting it is the single most common setup mistake; see [Common Pitfalls](#common-pitfalls). ### Why the function call is `serde_json::to_string`, not `BlogPost::to_string` [Section titled “Why the function call is serde\_json::to\_string, not BlogPost::to\_string”](#why-the-function-call-is-serde_jsonto_string-not-blogpostto_string) This is the architectural twist. In JavaScript, `JSON.stringify` *is* the JSON encoder. In Rust, the trait (`Serialize`) describes *what your type can do*, while the **format crate** (`serde_json`) provides the *function that drives it*. The call `serde_json::to_string(&post)` reads as: “JSON crate, please serialize this value.” Swap `serde_json` for `toml` and the very same `post` becomes TOML. We’ll see that in the [Real-World Example](#real-world-example) and in [Beyond JSON](/15-serialization/06-other-formats/). ### Parsing returns a `Result`, not an `any` [Section titled “Parsing returns a Result, not an any”](#parsing-returns-a-result-not-an-any) The signature of `serde_json::from_str` is, in spirit: ```text 1 fn from_str<T: Deserialize>(s: &str) -> Result<T, serde_json::Error> ``` Two things follow. First, the type `T` you want out is part of the call — usually supplied by the binding’s type annotation (`let parsed: BlogPost = ...`) or a turbofish (`from_str::<BlogPost>(...)`). Second, the return is a **`Result`** (covered in [Section 08: Error Handling](/08-error-handling/)). Where `JSON.parse` throws, and where its `as BlogPost` cast lies about validation, Serde forces you to acknowledge that parsing can fail: ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 struct Config { 5 port: u16, 6 host: String, 7 } 8 9 // Returns a Result instead of throwing, and the `?` propagates failures. 10 fn load_config(raw: &str) -> Result<Config, serde_json::Error> { 11 let config: Config = serde_json::from_str(raw)?; 12 Ok(config) 13 } 14 15 fn main() { 16 // A valid document. 17 match load_config(r#"{"port":8080,"host":"localhost"}"#) { 18 Ok(cfg) => println!("listening on {}:{}", cfg.host, cfg.port), 19 Err(e) => println!("config error: {e}"), 20 } 21 22 // Malformed JSON (syntax error). 23 match load_config(r#"{"port":8080,"host":}"#) { 24 Ok(cfg) => println!("listening on {}:{}", cfg.host, cfg.port), 25 Err(e) => println!("config error: {e}"), 26 } 27 28 // Well-formed JSON, wrong shape: `port` should be a number. 29 match load_config(r#"{"port":"oops"}"#) { 30 Ok(cfg) => println!("listening on {}:{}", cfg.host, cfg.port), 31 Err(e) => println!("config error: {e}"), 32 } 33 } ``` Real output: ```text 1 listening on localhost:8080 2 config error: expected value at line 1 column 21 3 config error: invalid type: string "oops", expected u16 at line 1 column 14 ``` Look at the third line: `invalid type: string "oops", expected u16`. This is the validation TypeScript’s cast silently skipped. Serde checked the shape *and the types* against `Config` and told you exactly where and why it failed: line, column, and the type mismatch. The `?` operator (see [the `?` operator](/08-error-handling/01-question-mark/)) is Serde’s answer to letting an error bubble up the way an uncaught `throw` would in JavaScript, but explicitly and on the function’s return type. ### How Serde handles fields you didn’t model [Section titled “How Serde handles fields you didn’t model”](#how-serde-handles-fields-you-didnt-model) By default Serde is forgiving about *extra* fields and strict about *missing* ones, the opposite of `JSON.parse`’s “anything goes”: ```rust 1 use serde::Deserialize; 2 3 #[derive(Debug, Deserialize)] 4 struct User { 5 id: u32, 6 name: String, 7 } 8 9 fn main() { 10 // An unknown field ("extra") is ignored by default. 11 let u: User = serde_json::from_str(r#"{"id":1,"name":"Ada","extra":true}"#).unwrap(); 12 println!("unknown field ignored: {u:?}"); 13 14 // A missing required field ("name") is an error. 15 match serde_json::from_str::<User>(r#"{"id":1}"#) { 16 Ok(u) => println!("{u:?}"), 17 Err(e) => println!("missing field error: {e}"), 18 } 19 } ``` Real output: ```text 1 unknown field ignored: User { id: 1, name: "Ada" } 2 missing field error: missing field `name` at line 1 column 8 ``` Both behaviors are configurable with attributes (`#[serde(deny_unknown_fields)]`, `#[serde(default)]`, `Option<T>` fields, …), which is the subject of [Serde Attributes](/15-serialization/05-attributes/). *** ## Key Differences [Section titled “Key Differences”](#key-differences) ### The data-model architecture [Section titled “The data-model architecture”](#the-data-model-architecture) This is the mental model worth internalizing. JavaScript’s `JSON` is a monolith: object in, string out, JSON only. Serde is shaped like an **hourglass** with a thin waist in the middle: ```text 1 YOUR TYPES SERDE DATA MODEL FORMATS 2 (Serialize/Deserialize) (~29 primitives: (one crate each) 3 bool, i32, str, seq, 4 struct BlogPost ─┐ map, struct, enum, …) ┌─► serde_json (JSON) 5 struct Config ─┤ ├─► toml (TOML) 6 enum Event ─┼──────► [ the thin waist ] ────┼─► serde_norway (YAML) 7 Vec<T>, HashMap ─┤ ├─► rmp-serde (MessagePack) 8 Option<T>, … ─┘ └─► bincode (binary) ``` Your type’s `Serialize` impl describes itself in terms of the **data model** (“I am a struct with four fields named …”). A format crate’s serializer translates those data-model calls into bytes. Because the two halves only ever talk through the waist, **`N` data types and `M` formats need `N + M` pieces of code, not `N × M`.** Add a new struct and every format already supports it; add a new format crate and every struct you’ve ever written already serializes to it. `JSON.parse`/`JSON.stringify` give you `1` data model (whatever JavaScript objects are) and `1` format (JSON). Serde generalizes both axes. ### `any` versus a real type [Section titled “any versus a real type”](#any-versus-a-real-type) | Aspect | TypeScript `JSON` | Rust Serde | | --------------------- | ------------------------------------------------------------- | -------------------------------------------------------- | | Parse result | `any` (cast to a type you hope is right) | a concrete `T`, validated against its definition | | Type checking | none at runtime; the `as` cast is a no-op | full: wrong type/missing field → `Err` | | Failure mode | `throw` on bad syntax; *silent* on bad shape | `Result` for both bad syntax and bad shape | | Number precision | every number is IEEE-754 `f64`; large integers lose precision | you choose `u64`, `i32`, `f64`, … and get the exact type | | Formats | JSON only | JSON, TOML, YAML, MessagePack, bincode, CSV, … | | Extra fields | kept on the object | ignored by default (configurable) | | Where the logic lives | the `JSON` global | split: traits on your type + a format crate | > **Warning:** That number-precision row bites real programs. In JavaScript, `JSON.parse('{"id":12345678901234567890}')` yields `12345678901234567000`: the integer is silently rounded because every JS `number` is a 64-bit float. It does **not** wrap; it loses precision. In Rust you would model that field as `u64` (or `u128`) and Serde would preserve every digit, or return an error if the value doesn’t fit. ### Serialization is explicit, not reflective [Section titled “Serialization is explicit, not reflective”](#serialization-is-explicit-not-reflective) `JSON.stringify` uses runtime reflection: it walks whatever properties happen to exist on the object, drops `undefined` and functions, and turns `Date` into a string via `toJSON`. Rust has no runtime reflection; instead, the `#[derive(Serialize)]` macro generates the field-walking code **at compile time** based on the struct definition. The upshot: what gets serialized is fixed by the type, knowable by reading the source, and has zero reflection overhead at runtime. The trade-off is that “serialize this arbitrary value” isn’t a thing: a value’s type must implement `Serialize`, and the compiler enforces it (see the second pitfall below). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting `features = ["derive"]` [Section titled “Pitfall 1: Forgetting features = \["derive"\]”](#pitfall-1-forgetting-features--derive) The `#[derive(Serialize, Deserialize)]` macros live behind an opt-in feature of the `serde` crate. If you add plain `serde = "1"` (for example via `cargo add serde` without `--features derive`), the *traits* are in scope but the *derive macros* are not: ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Serialize, Deserialize)] // does not compile: derive macros not enabled 4 struct Point { 5 x: i32, 6 y: i32, 7 } 8 9 fn main() { 10 let p = Point { x: 1, y: 2 }; 11 println!("{}", serde_json::to_string(&p).unwrap()); 12 } ``` The real error is unusually helpful here: ```text 1 error: cannot find derive macro `Serialize` in this scope 2 --> src/main.rs:3:10 3 | 4 3 | #[derive(Serialize, Deserialize)] 5 | ^^^^^^^^^ 6 | 7 note: `Serialize` is imported here, but it is only a trait, without a derive macro 8 --> src/main.rs:1:26 9 | 10 1 | use serde::{Deserialize, Serialize}; 11 | ^^^^^^^^^ ``` The fix is in `Cargo.toml`: ```toml 1 [dependencies] 2 serde = { version = "1", features = ["derive"] } ``` The full setup walkthrough lives in [Serde Basics](/15-serialization/01-serde-basics/). ### Pitfall 2: A field whose type isn’t serializable [Section titled “Pitfall 2: A field whose type isn’t serializable”](#pitfall-2-a-field-whose-type-isnt-serializable) Because Serde has no reflection, *every* field of a struct you derive `Serialize` on must itself implement `Serialize`. Put a non-serializable type in a field and the compiler stops you, at compile time, not at runtime like a `JSON.stringify` surprise: ```rust 1 use serde::{Deserialize, Serialize}; 2 use std::time::Instant; 3 4 #[derive(Serialize, Deserialize)] // does not compile (error E0277) 5 struct Session { 6 user: String, 7 started: Instant, // Instant does not implement Serialize 8 } 9 10 fn main() { 11 let s = Session { user: "bob".to_string(), started: Instant::now() }; 12 println!("{}", serde_json::to_string(&s).unwrap()); 13 } ``` The real error, trimmed: ```text 1 error[E0277]: the trait bound `Instant: serde::Serialize` is not satisfied 2 --> src/main.rs:4:10 3 | 4 4 | #[derive(Serialize, Deserialize)] 5 | ^^^^^^^^^ the trait `Serialize` is not implemented for `Instant` 6 ... 7 7 | started: Instant, 8 | ------- required by a bound introduced by this call 9 | 10 = note: for types from other crates check whether the crate offers a `serde` feature flag ``` The note points at the fix: many crates ship their own `serde` support behind a feature (for time, `chrono` with `features = ["serde"]`), or you serialize a serializable representation instead (e.g. a `u64` of seconds), or you tell Serde to skip the field with `#[serde(skip)]`. Skipping and custom field handling are covered in [Serde Attributes](/15-serialization/05-attributes/) and [Custom Serialization](/15-serialization/07-custom-serialization/). ### Pitfall 3: Treating `from_str` like `JSON.parse` and ignoring the `Result` [Section titled “Pitfall 3: Treating from\_str like JSON.parse and ignoring the Result”](#pitfall-3-treating-from_str-like-jsonparse-and-ignoring-the-result) Coming from JavaScript, it is tempting to `.unwrap()` every `from_str` because `JSON.parse` “just returns the value.” In a real program that turns a malformed network payload into a **panic** that aborts the thread. `serde_json::from_str` returns a `Result` precisely so you can decide what to do; match on it, propagate it with `?`, or convert it with the `Result` combinators from [Section 08](/08-error-handling/00-result-option/). Reserve `.unwrap()` for tests and for data you constructed yourself and *know* is valid. ### Pitfall 4: Expecting `JSON.parse`’s silent shape-mismatch behavior [Section titled “Pitfall 4: Expecting JSON.parse’s silent shape-mismatch behavior”](#pitfall-4-expecting-jsonparses-silent-shape-mismatch-behavior) A subtle one: TypeScript’s `JSON.parse(...) as Config` *accepts* `{"port":"oops"}` and only blows up later when something tries to use `port` as a number. Serde rejects it immediately with `invalid type: string "oops", expected u16`. This is a feature, not friction: the failure happens at the boundary, with a precise location, instead of leaking a wrong-typed value deep into your program. If you genuinely want to accept loosely-typed input, that is an explicit choice (e.g. deserialize into `serde_json::Value` first — see [Dynamic JSON with `serde_json::Value`](/15-serialization/04-json-manipulation/)). *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Model the shape with a struct and derive the traits.** Reach for `#[derive(Serialize, Deserialize)]` on a real type before reaching for the dynamic `serde_json::Value`. A typed model gives you validation, autocompletion, and a single source of truth; see the typed-vs-`Value` discussion in [Dynamic JSON with `serde_json::Value`](/15-serialization/04-json-manipulation/). * **Derive `Debug` alongside `Serialize`/`Deserialize`.** `#[derive(Debug, Serialize, Deserialize)]` costs nothing and makes `println!("{value:?}")` and test failures readable. * **Let the binding’s type drive deserialization.** Prefer `let cfg: Config = serde_json::from_str(s)?;` over a turbofish; it reads cleanly and the annotation documents intent. Use `from_str::<Config>(s)?` only when there is no binding to annotate. * **Propagate, don’t panic.** Return `Result<_, serde_json::Error>` (or a unified app error via [`anyhow`/`thiserror`](/08-error-handling/06-anyhow-thiserror/)) and use `?`. Save `.unwrap()`/`.expect()` for tests and provable invariants. * **Choose precise field types.** Use `u32`/`u64`/`i64` for integers you care about and `f64` only for genuine floats. This is where Rust beats JavaScript’s one-`number`-fits-all model: model the data accurately and Serde enforces it. * **Keep types format-neutral.** Don’t bake JSON assumptions into your structs. The whole point of the data model is that the same type also serializes to TOML/YAML/MessagePack; attributes like `#[serde(rename_all = "camelCase")]` ([Serde Attributes](/15-serialization/05-attributes/)) adapt naming per need without coupling the type to one format. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A common task: consume a JSON API response into typed Rust, then re-emit the same value in a *different* format: exactly the scenario where Serde’s data model pays off. Here we parse a GitHub-style repository payload into nested structs and serialize the result to both JSON and TOML, with **no per-format code in the types**. ```toml 1 [dependencies] 2 serde = { version = "1", features = ["derive"] } 3 serde_json = "1" 4 toml = "1" ``` ```rust 1 use serde::{Deserialize, Serialize}; 2 3 // One set of types. They implement Serialize + Deserialize, so they can travel 4 // to/from ANY format whose crate plugs into Serde. 5 #[derive(Debug, Serialize, Deserialize)] 6 struct Repository { 7 name: String, 8 full_name: String, 9 stargazers_count: u32, 10 private: bool, 11 owner: Owner, // nested struct — Serde recurses automatically 12 topics: Vec<String>, 13 } 14 15 #[derive(Debug, Serialize, Deserialize)] 16 struct Owner { 17 login: String, 18 id: u64, // a real 64-bit integer, not a lossy f64 19 } 20 21 fn main() -> Result<(), Box<dyn std::error::Error>> { 22 // Pretend this came back from an HTTP GET. 23 let body = r#" 24 { 25 "name": "serde", 26 "full_name": "serde-rs/serde", 27 "stargazers_count": 9123, 28 "private": false, 29 "owner": { "login": "serde-rs", "id": 4144980 }, 30 "topics": ["serialization", "rust"] 31 }"#; 32 33 // Deserialize JSON -> typed Rust (validated against the structs above). 34 let repo: Repository = serde_json::from_str(body)?; 35 println!( 36 "{}/{} has {} stars", 37 repo.owner.login, repo.name, repo.stargazers_count 38 ); 39 40 // Serialize the SAME value to two different formats. 41 let as_json = serde_json::to_string(&repo)?; 42 let as_toml = toml::to_string(&repo)?; 43 println!("--- JSON ---\n{as_json}"); 44 println!("--- TOML ---\n{as_toml}"); 45 46 Ok(()) 47 } ``` Real output: ```text 1 serde-rs/serde has 9123 stars 2 --- JSON --- 3 {"name":"serde","full_name":"serde-rs/serde","stargazers_count":9123,"private":false,"owner":{"login":"serde-rs","id":4144980},"topics":["serialization","rust"]} 4 --- TOML --- 5 name = "serde" 6 full_name = "serde-rs/serde" 7 stargazers_count = 9123 8 private = false 9 topics = ["serialization", "rust"] 10 11 [owner] 12 login = "serde-rs" 13 id = 4144980 ``` The `Repository` and `Owner` types never mention JSON or TOML. The nesting (`owner`, the `Vec<String>` of topics) is handled automatically because Serde recurses through fields that are themselves `Serialize`/`Deserialize`. Swapping in YAML or MessagePack would change only the format crate, never the types. In a web service you’d wire this same `Repository` straight into a handler; see [Section 16: Web APIs](/16-web-apis/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [Serde — official site and guide](https://serde.rs/) — the data model, the traits, and the attribute reference. * [Understanding Serde’s data model](https://serde.rs/data-model.html) — the \~29 primitives that form the “thin waist.” * [`serde` crate on docs.rs](https://docs.rs/serde/latest/serde/) — the `Serialize` and `Deserialize` trait docs. * [`serde_json` crate on docs.rs](https://docs.rs/serde_json/latest/serde_json/) — `to_string`, `from_str`, and friends. * [MDN: `JSON.parse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) and [`JSON.stringify`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) — the TypeScript/JavaScript starting points this page maps from. ### Related sections in this guide [Section titled “Related sections in this guide”](#related-sections-in-this-guide) * [Serde Basics](/15-serialization/01-serde-basics/) — the exact setup, `to_string`/`from_str`, and your first round-trip. * [Deriving `Serialize` and `Deserialize`](/15-serialization/02-derive-serialize/) — what `#[derive(Serialize, Deserialize)]` generates and how it works on enums. * [Structs and JSON](/15-serialization/03-json/) — structs ↔ JSON in depth: nested types, `Vec`/`HashMap`, `Option` fields, enum representations. * [Dynamic JSON with `serde_json::Value`](/15-serialization/04-json-manipulation/) — dynamic JSON with `serde_json::Value` and the `json!` macro, and when to prefer it over a typed model. * [Serde Attributes](/15-serialization/05-attributes/) — `rename`, `rename_all`, `skip`, `default`, `flatten`, `tag`, and more. * [Beyond JSON](/15-serialization/06-other-formats/) — the same data as TOML, YAML, MessagePack, bincode, and CSV. * [Custom Serialization](/15-serialization/07-custom-serialization/) — hand-written `Serialize`/`Deserialize` and `serialize_with`/`deserialize_with`. * [Serde Performance](/15-serialization/08-performance/) — borrowing, zero-copy, streaming, and avoiding `Value`. * [Section 08: Error Handling](/08-error-handling/) — `Result`, the [`?` operator](/08-error-handling/01-question-mark/), and `anyhow`/`thiserror`, all of which appear in real Serde code. * [Section 09: Generics and Traits](/09-generics-traits/) — `Serialize`/`Deserialize` are traits; this is the background on what that means. * [Section 02: Basics](/02-basics/) — the concrete number types (`u32`, `u64`, `f64`) you’ll model JSON numbers with. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: First round-trip [Section titled “Exercise 1: First round-trip”](#exercise-1-first-round-trip) **Difficulty:** Easy **Objective:** Confirm you can take a struct to JSON and back. **Instructions:** Define a `Movie` struct with `title: String`, `year: u16`, and `rating: f64`. Derive `Debug`, `Serialize`, and `Deserialize`. In `main`, build a `Movie`, serialize it with `serde_json::to_string_pretty`, print the JSON, then deserialize that JSON back into a `Movie` and print it with `{:?}`. Solution ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 struct Movie { 5 title: String, 6 year: u16, 7 rating: f64, 8 } 9 10 fn main() { 11 let m = Movie { 12 title: "Arrival".to_string(), 13 year: 2016, 14 rating: 8.0, 15 }; 16 17 let json = serde_json::to_string_pretty(&m).unwrap(); 18 println!("{json}"); 19 20 let back: Movie = serde_json::from_str(&json).unwrap(); 21 println!("{back:?}"); 22 } ``` Real output: ```text 1 { 2 "title": "Arrival", 3 "year": 2016, 4 "rating": 8.0 5 } 6 Movie { title: "Arrival", year: 2016, rating: 8.0 } ``` ### Exercise 2: Parse without panicking [Section titled “Exercise 2: Parse without panicking”](#exercise-2-parse-without-panicking) **Difficulty:** Medium **Objective:** Replace `JSON.parse`-style “just trust it” with a `Result`-returning function that reports type mismatches. **Instructions:** Write `fn parse_movie(raw: &str) -> Result<Movie, serde_json::Error>` that deserializes a `Movie` (reuse the struct from Exercise 1). In `main`, call it twice: once with valid JSON and once with `{"title":"Dune","year":"twenty"}` (note `year` is a string). Print the parsed movie on `Ok` and the error on `Err`. Do not use `.unwrap()` on the parse result. Solution ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 struct Movie { 5 title: String, 6 year: u16, 7 rating: f64, 8 } 9 10 fn parse_movie(raw: &str) -> Result<Movie, serde_json::Error> { 11 serde_json::from_str(raw) 12 } 13 14 fn main() { 15 match parse_movie(r#"{"title":"Dune","year":2021,"rating":8.0}"#) { 16 Ok(movie) => println!("parsed {} ({})", movie.title, movie.year), 17 Err(e) => eprintln!("bad movie json: {e}"), 18 } 19 20 // `year` is a string here — Serde validates and returns an Err. 21 match parse_movie(r#"{"title":"Dune","year":"twenty"}"#) { 22 Ok(movie) => println!("parsed {} ({})", movie.title, movie.year), 23 Err(e) => eprintln!("bad movie json: {e}"), 24 } 25 } ``` Real output (the error line goes to stderr): ```text 1 parsed Dune (2021) 2 bad movie json: invalid type: string "twenty", expected u16 at line 1 column 31 ``` Note how Serde reported the precise type mismatch: the validation `JSON.parse` would have skipped. ### Exercise 3: One type, two formats [Section titled “Exercise 3: One type, two formats”](#exercise-3-one-type-two-formats) **Difficulty:** Medium **Objective:** Experience the data-model architecture directly: serialize a single value to two formats with zero format-specific code in the type. **Instructions:** Add the `toml` crate (`cargo add toml`). Define an `AppSettings` struct with `theme: String`, `autosave: bool`, and `max_recent_files: u8`. Serialize one `AppSettings` value to **both** JSON (with `serde_json::to_string`) and TOML (with `toml::to_string`) and print each. Then deserialize a TOML string back into `AppSettings` and print it with `{:?}`. Solution `Cargo.toml`: ```toml 1 [dependencies] 2 serde = { version = "1", features = ["derive"] } 3 serde_json = "1" 4 toml = "1" ``` ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 struct AppSettings { 5 theme: String, 6 autosave: bool, 7 max_recent_files: u8, 8 } 9 10 fn main() { 11 let settings = AppSettings { 12 theme: "dark".to_string(), 13 autosave: true, 14 max_recent_files: 10, 15 }; 16 17 // Same value, two formats — no per-format code in AppSettings. 18 println!("{}", serde_json::to_string(&settings).unwrap()); 19 println!("{}", toml::to_string(&settings).unwrap()); 20 21 // And back from a TOML config file. 22 let loaded: AppSettings = 23 toml::from_str("theme = \"light\"\nautosave = false\nmax_recent_files = 5\n").unwrap(); 24 println!("{loaded:?}"); 25 } ``` Real output: ```text 1 {"theme":"dark","autosave":true,"max_recent_files":10} 2 theme = "dark" 3 autosave = true 4 max_recent_files = 10 5 6 AppSettings { theme: "light", autosave: false, max_recent_files: 5 } ``` The `AppSettings` type never mentions JSON or TOML; that is the whole point of Serde’s data model. Continue to [Beyond JSON](/15-serialization/06-other-formats/) to add YAML and MessagePack the same way. # Serde Basics: Setup and the to_string / from_str Round-Trip > Set up Serde and run the JSON round-trip you know from JavaScript: to_string and from_str replace JSON.stringify and JSON.parse, into a typed struct. In JavaScript, `JSON.stringify` and `JSON.parse` are built into the language and always available. Rust ships no JSON support in the standard library; instead the ecosystem standardized on **Serde**, a small set of crates you add to your project. This page is the hands-on starting point: how to add Serde to a project, and how to perform the two operations you do every day in TypeScript: turn a value into a JSON string, and parse a JSON string back into a value. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) **Serde** (“**ser**ialize / **de**serialize”) is the de-facto serialization framework for Rust. To use it for JSON you add two crates, `serde` (with the `derive` feature) and `serde_json`, then call `serde_json::to_string(&value)` to produce JSON and `serde_json::from_str::<T>(text)` to parse it. The closest mental model for a TypeScript developer is `JSON.stringify` / `JSON.parse`, but unlike those, Serde is fully type-directed: you tell it the exact type you expect, and parsing fails loudly with a precise error if the JSON does not match. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In a Node.js or browser project, JSON is always there. A typical round-trip looks like this: ```typescript 1 interface Article { 2 id: number; 3 title: string; 4 tags: string[]; 5 published: boolean; 6 } 7 8 const article: Article = { 9 id: 7, 10 title: "Serde in 5 minutes", 11 tags: ["rust", "json"], 12 published: true, 13 }; 14 15 // Value -> JSON string 16 const json = JSON.stringify(article); 17 console.log(json); 18 // {"id":7,"title":"Serde in 5 minutes","tags":["rust","json"],"published":true} 19 20 // Pretty-printed (2-space indent) 21 console.log(JSON.stringify(article, null, 2)); 22 23 // JSON string -> value 24 const input = '{"id":42,"title":"Parsed back","tags":["a","b"],"published":false}'; 25 const parsed = JSON.parse(input) as Article; 26 console.log(parsed); // { id: 42, title: 'Parsed back', tags: [ 'a', 'b' ], published: false } ``` Two things are worth noticing, because they are exactly where Rust diverges. First, `JSON.parse` returns `any`: the `as Article` cast is a compile-time fiction that is **never checked at runtime**. If the JSON is missing `title` or has `id: "oops"`, `JSON.parse` happily hands you a malformed object and the bug surfaces later. Second, there is nothing to install: JSON support is part of the runtime. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) First, create a project and add the two crates. `cargo new` selects the newest stable edition automatically (the repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition): ```bash 1 cargo new article_demo 2 cd article_demo 3 cargo add serde --features derive 4 cargo add serde_json ``` > **Note:** `cargo add` is built into Cargo (since 1.62); you do **not** need the separate `cargo-edit` tool that older tutorials mention. That writes the following into `Cargo.toml`: ```toml 1 [dependencies] 2 serde = { version = "1.0.228", features = ["derive"] } 3 serde_json = "1.0.150" ``` The `features = ["derive"]` part is the piece TypeScript developers most often miss. Without it the `#[derive(Serialize, Deserialize)]` macros do not exist and your code will not compile. We cover that error in [Common Pitfalls](#common-pitfalls). Now the equivalent round-trip in `src/main.rs`: ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 struct Article { 5 id: u32, 6 title: String, 7 tags: Vec<String>, 8 published: bool, 9 } 10 11 fn main() -> Result<(), serde_json::Error> { 12 let article = Article { 13 id: 7, 14 title: String::from("Serde in 5 minutes"), 15 tags: vec![String::from("rust"), String::from("json")], 16 published: true, 17 }; 18 19 // Serialize: struct -> compact JSON string 20 let json = serde_json::to_string(&article)?; 21 println!("{json}"); 22 23 // Pretty-printed JSON (two-space indent) 24 let pretty = serde_json::to_string_pretty(&article)?; 25 println!("{pretty}"); 26 27 // Deserialize: JSON string -> struct 28 let input = r#"{"id":42,"title":"Parsed back","tags":["a","b"],"published":false}"#; 29 let parsed: Article = serde_json::from_str(input)?; 30 println!("{parsed:?}"); 31 println!("title = {}", parsed.title); 32 33 Ok(()) 34 } ``` Running it with `cargo run` produces this real output: ```text 1 {"id":7,"title":"Serde in 5 minutes","tags":["rust","json"],"published":true} 2 { 3 "id": 7, 4 "title": "Serde in 5 minutes", 5 "tags": [ 6 "rust", 7 "json" 8 ], 9 "published": true 10 } 11 Article { id: 42, title: "Parsed back", tags: ["a", "b"], published: false } 12 title = Parsed back ``` The compact output matches `JSON.stringify` byte-for-byte, and `to_string_pretty` matches `JSON.stringify(x, null, 2)`. The key win is the last two lines: `parsed` is a real, fully-typed `Article`, not an `any` you have to trust. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) Let’s walk through the Rust version line by line and contrast each piece with the TypeScript. * **`use serde::{Deserialize, Serialize};`** brings the two **traits** into scope. A trait is Rust’s version of an interface (a shared contract); `Serialize` means “this type knows how to write itself out”, `Deserialize` means “this type knows how to build itself from input”. This single `use` line imports *both* the traits and the derive macros of the same name, which is why you write `Serialize` once but it does double duty. * **`#[derive(Debug, Serialize, Deserialize)]`** is the heart of Serde’s ergonomics. `derive` is a macro that **generates code at compile time**. Here it auto-writes the `Serialize` and `Deserialize` implementations for `Article` based on its fields, so you never hand-write the mapping. (`Debug` is unrelated to Serde — it just enables the `{:?}` printing used by `println!`.) This is *not* like a TypeScript decorator: decorators run at runtime and wrap behavior, whereas a Rust derive macro expands into ordinary source code before the program is even compiled. The full mechanics of what gets generated are covered in [Deriving `Serialize` and `Deserialize`](/15-serialization/02-derive-serialize/). * **The field types matter.** `id: u32` is an unsigned 32-bit integer; `title: String` is an owned, growable UTF-8 string; `tags: Vec<String>` is a growable array (TypeScript’s `string[]`); `published: bool` is a boolean. Serde uses these types to *drive* both serialization and parsing. When you ask it to parse into `Article`, it knows `id` must be a number that fits in a `u32`, and it will reject anything else. * **`fn main() -> Result<(), serde_json::Error>`**: Serde’s operations return a `Result`, Rust’s type for “this might fail”. Returning `Result` from `main` lets us use the `?` operator. See [Section 08: Error Handling](/08-error-handling/) if `Result` and `?` are new to you. * **`serde_json::to_string(&article)?`** serializes a *borrow* of `article` (the `&`) into a `String`. The `?` says “if this returns an error, return it from `main`”. Serialization of well-formed Rust values essentially never fails for JSON, but the API is still fallible because some types (or custom serializers) can error. * **`serde_json::from_str(input)?`** parses the string. Note the annotation `let parsed: Article = ...`. Serde is **type-directed**: it needs to know the target type to parse into. You can also write it turbofish-style as `serde_json::from_str::<Article>(input)?`. This is the precise opposite of `JSON.parse`, which returns `any` and ignores the type entirely. * **`r#"..."#`** is a **raw string literal** — like a backtick template literal in JavaScript minus interpolation. It lets the JSON’s double quotes appear literally without escaping every `"` as `\"`. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | TypeScript / JavaScript | Rust + Serde | | --------------------- | ------------------------------------------------------- | ---------------------------------------------- | | Availability | Built into the runtime | Add `serde` + `serde_json` crates | | Stringify | `JSON.stringify(x)` | `serde_json::to_string(&x)?` | | Pretty print | `JSON.stringify(x, null, 2)` | `serde_json::to_string_pretty(&x)?` | | Parse | `JSON.parse(s)` → `any` | `serde_json::from_str::<T>(s)?` → `T` | | Runtime type checking | None: the `as T` cast is erased | Full: shape is validated against `T` | | Failure mode | Returns malformed objects; throws only on syntax errors | Returns `Err` on syntax **and** shape mismatch | | Numbers | All `number` (IEEE-754 f64) | You choose: `u8`, `i32`, `u64`, `f64`, … | A few of these deserve emphasis: * **Parsing is checked.** Because `from_str` knows the target type, a missing required field or a wrong type is a hard error, not a silent `undefined`. This moves a whole class of “the API changed and now `x.title` is undefined three functions later” bugs to the parse boundary. * **You pick the numeric type.** JavaScript has one numeric type, `number`, which is always an IEEE-754 double. That means it silently **loses precision** on integers beyond 2^53 (it does *not* wrap around — it rounds). In Rust you declare exactly `u32`, `i64`, `f64`, and so on, and Serde enforces the range while parsing. A JSON `99999` will refuse to fit into a `u16` field. * **Tuple structs and arrays.** Serde maps Rust shapes to natural JSON shapes. A named struct becomes a JSON object; a tuple struct becomes a JSON array. For example, `struct Rgb(u8, u8, u8)` with `Rgb(255, 128, 0)` serializes to `[255,128,0]`, not an object. That mirrors how the data is shaped, and it surprises people who expect every struct to become an object. > **Note:** This page deals only with JSON via `serde_json`. The same `to_string` / `from_str` muscle memory transfers to TOML, YAML, and binary formats; see [Beyond JSON](/15-serialization/06-other-formats/). The architecture that makes one set of derives work across every format is explained in [Serde](/15-serialization/00-serde-intro/). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Forgetting the `derive` feature [Section titled “Forgetting the derive feature”](#forgetting-the-derive-feature) This is the single most common stumble. If you run `cargo add serde` (without `--features derive`) and then write `#[derive(Serialize, Deserialize)]`, the build fails. Here is the **real** compiler output: ```rust 1 // does not compile — `serde` was added WITHOUT features = ["derive"] 2 use serde::{Deserialize, Serialize}; 3 4 #[derive(Serialize, Deserialize)] 5 struct Point { 6 x: i32, 7 y: i32, 8 } ``` ```text 1 error: cannot find derive macro `Serialize` in this scope 2 --> src/main.rs:3:10 3 | 4 3 | #[derive(Serialize, Deserialize)] 5 | ^^^^^^^^^ 6 | 7 note: `Serialize` is imported here, but it is only a trait, without a derive macro 8 --> src/main.rs:1:26 9 | 10 1 | use serde::{Deserialize, Serialize}; 11 | ^^^^^^^^^^^ ``` The fix is to enable the feature, either with `cargo add serde --features derive` or by editing `Cargo.toml`: ```toml 1 serde = { version = "1.0.228", features = ["derive"] } ``` > **Tip:** The note “it is only a trait, without a derive macro” is the compiler’s hint that the trait imported fine but the *macro* of the same name is gated behind the feature flag. ### Expecting `from_str` to infer the type [Section titled “Expecting from\_str to infer the type”](#expecting-from_str-to-infer-the-type) Unlike `JSON.parse`, `from_str` cannot guess what you want. You must give it a target type, either with a `let` annotation or turbofish: ```rust 1 // Both forms work: 2 let parsed: Article = serde_json::from_str(input)?; 3 let parsed = serde_json::from_str::<Article>(input)?; ``` Omit the type and you get a `type annotations needed` error, because Rust has no way to choose `T`. ### Forgetting `Deserialize` when you only added `Serialize` [Section titled “Forgetting Deserialize when you only added Serialize”](#forgetting-deserialize-when-you-only-added-serialize) The two traits are independent. A type that only derives `Serialize` can be turned *into* JSON but cannot be parsed *from* it (and vice versa). If you call `from_str` on a type that only derives `Serialize`, the compiler reports that the trait bound `Article: Deserialize` is not satisfied. Derive both unless you genuinely only need one direction. ### Assuming a bad shape will “just parse” like JavaScript [Section titled “Assuming a bad shape will “just parse” like JavaScript”](#assuming-a-bad-shape-will-just-parse-like-javascript) In JavaScript, `JSON.parse('{"host":"localhost","port":8080}')` succeeds even if your code expects a `retries` field; you find out later when something is `undefined`. Serde fails at the boundary. Given: ```rust 1 #[derive(Debug, serde::Serialize, serde::Deserialize)] 2 struct Config { 3 host: String, 4 port: u16, 5 retries: u8, 6 } ``` these four inputs each produce a real, descriptive `Err` (printed via the error’s `Display`): ```text 1 missing-field error: missing field `retries` at line 1 column 32 2 type error: invalid type: string "oops", expected u16 at line 1 column 33 3 range error: invalid value: integer `99999`, expected u16 at line 1 column 32 4 syntax error: trailing comma at line 1 column 33 ``` The first is a missing field, the second a type mismatch, the third a number that overflows `u16`, the fourth malformed JSON. All four are caught for you, with a line and column, instead of becoming a silent runtime surprise. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Always add `serde` with the `derive` feature** and add `serde_json` alongside it. `cargo add serde --features derive && cargo add serde_json` is the standard incantation. * **Derive both `Serialize` and `Deserialize`** on data-transfer types unless you have a clear reason not to. It costs nothing extra and saves you a recompile when you later need the other direction. * **Prefer the most specific numeric type.** Use `u16` for a port, `u8` for a percentage, `i64` for a database id. Letting Serde enforce the range at parse time is free validation you would otherwise hand-roll. * **Use `to_string` for wire/storage and `to_string_pretty` for human-facing output** (config files you expect people to read, debug logs). The compact form is smaller; the pretty form is diff-friendly. * **Propagate the error with `?` rather than `.unwrap()`** in real code. `serde_json::Error` carries the line and column; throwing it away with `.unwrap()` turns a helpful message into a bare panic. See [Section 08: Error Handling](/08-error-handling/). * **Know that unknown fields are ignored by default.** Parsing `{"id":1,"name":"Ada","role":"admin"}` into a struct with only `id` and `name` succeeds and drops `role`. This is convenient for forward-compatible APIs but can hide typos. To make unexpected fields a hard error, use `#[serde(deny_unknown_fields)]` — covered in [Serde Attributes](/15-serialization/05-attributes/). * **For byte input, use `from_slice`.** When you have raw bytes (e.g. an HTTP request body as `&[u8]`), `serde_json::from_slice(&bytes)` avoids an intermediate `String` allocation. There are also `from_reader` / `to_writer` for streaming I/O. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A common first task is loading and saving a service’s configuration as JSON. This `ServerConfig` loader reads a file, parses it into a typed struct, writes a pretty default back out, and also shows parsing directly from a byte buffer (as you would from an HTTP body). It is a complete, runnable `src/main.rs` using only `serde` (with `derive`) and `serde_json`: ```rust 1 use serde::{Deserialize, Serialize}; 2 use std::fs; 3 4 #[derive(Debug, Serialize, Deserialize)] 5 struct ServerConfig { 6 bind_address: String, 7 port: u16, 8 max_connections: u32, 9 log_level: String, 10 } 11 12 fn load_config(path: &str) -> Result<ServerConfig, Box<dyn std::error::Error>> { 13 let text = fs::read_to_string(path)?; 14 let config: ServerConfig = serde_json::from_str(&text)?; 15 Ok(config) 16 } 17 18 fn save_config(path: &str, config: &ServerConfig) -> Result<(), Box<dyn std::error::Error>> { 19 let json = serde_json::to_string_pretty(config)?; 20 fs::write(path, json)?; 21 Ok(()) 22 } 23 24 fn main() -> Result<(), Box<dyn std::error::Error>> { 25 let default = ServerConfig { 26 bind_address: "0.0.0.0".to_string(), 27 port: 8080, 28 max_connections: 1024, 29 log_level: "info".to_string(), 30 }; 31 32 let path = "config.json"; 33 save_config(path, &default)?; 34 35 let loaded = load_config(path)?; 36 println!("Loaded config: {loaded:?}"); 37 println!("Listening on {}:{}", loaded.bind_address, loaded.port); 38 39 // from_slice: parse straight from raw bytes (e.g. an HTTP request body) 40 let bytes: &[u8] = 41 br#"{"bind_address":"127.0.0.1","port":3000,"max_connections":256,"log_level":"debug"}"#; 42 let from_bytes: ServerConfig = serde_json::from_slice(bytes)?; 43 println!("From bytes: port={}", from_bytes.port); 44 45 fs::remove_file(path).ok(); 46 Ok(()) 47 } ``` Real output from `cargo run`: ```text 1 Loaded config: ServerConfig { bind_address: "0.0.0.0", port: 8080, max_connections: 1024, log_level: "info" } 2 Listening on 0.0.0.0:8080 3 From bytes: port=3000 ``` The `Box<dyn std::error::Error>` return type lets both the file-I/O errors (from `fs::read_to_string` / `fs::write`) and the JSON errors (from `from_str` / `from_slice`) flow through the same `?` — a single, uniform error channel for two unrelated failure sources. This same struct, with no changes, would also load from TOML or YAML once you add the matching crate; see [Beyond JSON](/15-serialization/06-other-formats/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [Serde official site](https://serde.rs/) — the canonical guide; start with “Overview” and “Using derive”. * [`serde_json` API docs](https://docs.rs/serde_json/): every function (`to_string`, `to_string_pretty`, `from_str`, `from_slice`, `from_reader`, `to_writer`). * [The `serde` crate features](https://docs.rs/serde/latest/serde/#feature-flags) — what `derive` and other features enable. * [Serde](/15-serialization/00-serde-intro/). The bigger picture: how Serde’s data model decouples types from formats. * [Deriving `Serialize` and `Deserialize`](/15-serialization/02-derive-serialize/) — what `#[derive(Serialize, Deserialize)]` actually generates. * [Structs and JSON](/15-serialization/03-json/): mapping nested structs, `Vec`, `HashMap`, `Option`, and enums to JSON. * [Dynamic JSON with `serde_json::Value`](/15-serialization/04-json-manipulation/) — dynamic JSON with `serde_json::Value` and the `json!` macro. * [Serde Attributes](/15-serialization/05-attributes/): `rename`, `default`, `skip`, `deny_unknown_fields`, and friends. * [Section 01: Getting Started](/01-getting-started/) — `cargo new`, `cargo add`, and project layout. * [Section 08: Error Handling](/08-error-handling/): `Result`, `?`, and `Box<dyn Error>`. * [Section 16: Web APIs](/16-web-apis/) — where serialized structs meet HTTP request and response bodies. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Round-trip a struct [Section titled “Exercise 1: Round-trip a struct”](#exercise-1-round-trip-a-struct) **Difficulty:** Easy **Objective:** Confirm that serializing then deserializing yields an equal value. **Instructions:** In a fresh project (`cargo new`, then `cargo add serde --features derive` and `cargo add serde_json`), define a `Todo` struct with `id: u32`, `text: String`, and `done: bool`. Serialize an instance with `to_string`, parse it back with `from_str`, and `assert_eq!` that the original equals the parsed value. (You will need to derive `PartialEq` so the two values can be compared.) ```rust 1 use serde::{Deserialize, Serialize}; 2 3 // TODO: derive the traits needed to serialize, deserialize, AND compare with assert_eq! 4 struct Todo { 5 id: u32, 6 text: String, 7 done: bool, 8 } 9 10 fn main() -> Result<(), serde_json::Error> { 11 let todo = Todo { id: 1, text: "Learn Serde".into(), done: false }; 12 // TODO: serialize -> deserialize -> assert_eq! 13 Ok(()) 14 } ``` Solution ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, PartialEq, Serialize, Deserialize)] 4 struct Todo { 5 id: u32, 6 text: String, 7 done: bool, 8 } 9 10 fn main() -> Result<(), serde_json::Error> { 11 let todo = Todo { 12 id: 1, 13 text: "Learn Serde".into(), 14 done: false, 15 }; 16 17 let json = serde_json::to_string(&todo)?; 18 let back: Todo = serde_json::from_str(&json)?; 19 20 assert_eq!(todo, back); 21 println!("round-trip ok: {json}"); 22 Ok(()) 23 } ``` Real output from `cargo run`: ```text 1 round-trip ok: {"id":1,"text":"Learn Serde","done":false} ``` `PartialEq` is what makes `assert_eq!` work; without it the compiler would reject the comparison. The `Debug` derive is needed so `assert_eq!` can print the values if they ever differ. ### Exercise 2: Parse nested JSON with a collection [Section titled “Exercise 2: Parse nested JSON with a collection”](#exercise-2-parse-nested-json-with-a-collection) **Difficulty:** Medium **Objective:** Deserialize a JSON object that contains an array of nested objects. **Instructions:** Define `Author { name: String, email: String }` and `Book { title: String, year: u16, authors: Vec<Author> }`. Parse the JSON literal below into a `Book` and print the title, year, and each author. Note how `Vec<Author>` and the nested struct require no extra wiring — Serde recurses automatically. ```rust 1 use serde::{Deserialize, Serialize}; 2 3 // TODO: define Author and Book with the right derives 4 5 fn main() -> Result<(), serde_json::Error> { 6 let input = r#"{ 7 "title": "Programming Rust", 8 "year": 2021, 9 "authors": [ 10 {"name": "Jim Blandy", "email": "jim@example.com"}, 11 {"name": "Jason Orendorff", "email": "jason@example.com"} 12 ] 13 }"#; 14 // TODO: parse into a Book and print its contents 15 Ok(()) 16 } ``` Solution ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 struct Author { 5 name: String, 6 email: String, 7 } 8 9 #[derive(Debug, Serialize, Deserialize)] 10 struct Book { 11 title: String, 12 year: u16, 13 authors: Vec<Author>, 14 } 15 16 fn main() -> Result<(), serde_json::Error> { 17 let input = r#"{ 18 "title": "Programming Rust", 19 "year": 2021, 20 "authors": [ 21 {"name": "Jim Blandy", "email": "jim@example.com"}, 22 {"name": "Jason Orendorff", "email": "jason@example.com"} 23 ] 24 }"#; 25 26 let book: Book = serde_json::from_str(input)?; 27 println!( 28 "{} ({}) by {} authors", 29 book.title, 30 book.year, 31 book.authors.len() 32 ); 33 for author in &book.authors { 34 println!(" - {} <{}>", author.name, author.email); 35 } 36 Ok(()) 37 } ``` Real output from `cargo run`: ```text 1 Programming Rust (2021) by 2 authors 2 - Jim Blandy <jim@example.com> 3 - Jason Orendorff <jason@example.com> ``` `Vec<Author>` deserializes a JSON array, and each element is parsed as an `Author`. Serde handles arbitrarily deep nesting this way — you only describe the shape with types. ### Exercise 3: Read the error on a shape mismatch [Section titled “Exercise 3: Read the error on a shape mismatch”](#exercise-3-read-the-error-on-a-shape-mismatch) **Difficulty:** Medium **Objective:** Observe that Serde rejects JSON that does not match your type, and inspect the error message. **Instructions:** Reuse the `Book` type from Exercise 2. Try to parse JSON where `year` is the *string* `"2021"` instead of a number. Match on the `Result`: print the parsed book on `Ok`, and the error’s message on `Err`. Confirm you get a descriptive type-mismatch error rather than a silently wrong value. ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 struct Book { 5 title: String, 6 year: u16, 7 } 8 9 fn main() { 10 let bad = r#"{"title":"Mistyped","year":"2021"}"#; 11 // TODO: match on serde_json::from_str::<Book>(bad) and print Ok or the Err message 12 } ``` Solution ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 struct Book { 5 title: String, 6 year: u16, 7 } 8 9 fn main() { 10 let bad = r#"{"title":"Mistyped","year":"2021"}"#; 11 match serde_json::from_str::<Book>(bad) { 12 Ok(book) => println!("parsed: {book:?}"), 13 Err(e) => println!("could not parse: {e}"), 14 } 15 } ``` Real output from `cargo run`: ```text 1 could not parse: invalid type: string "2021", expected u16 at line 1 column 33 ``` In TypeScript, `JSON.parse` would have returned `{ title: "Mistyped", year: "2021" }` and the wrong type would slip through unnoticed. Serde caught it at the boundary with a line and column. Matching on `Result` instead of calling `.unwrap()` is how you turn that into graceful handling — for example, returning a 400 response from a web handler. # Deriving `Serialize` and `Deserialize` > JSON.stringify serializes any object via runtime reflection; Rust has none, so #[derive(Serialize, Deserialize)] generates type-checked, compile-time impls instead. In TypeScript, any object is serializable to JSON for free: `JSON.stringify` walks its enumerable properties at runtime. Rust has no runtime reflection, so a type can only be serialized if it explicitly implements the **`Serialize`** trait (and deserialized only if it implements **`Deserialize`**). The `#[derive(Serialize, Deserialize)]` attribute makes the Serde derive macro write those implementations for you at compile time, so your `struct`s and `enum`s round-trip to JSON, TOML, YAML, and dozens of other formats with one line. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) * **What it is:** A derive macro from the [`serde`](https://serde.rs) crate that generates `Serialize` and/or `Deserialize` trait implementations for your `struct`s and `enum`s. * **Why it matters:** It is the Rust equivalent of “this object is JSON-ready.” Without it, `serde_json::to_string(&value)` will not even compile, because the compiler cannot find a `Serialize` impl for your type. * **The mental shift:** Unlike `JSON.stringify`, which works on *any* value at runtime, Rust decides *at compile time* exactly which types can be serialized. The derive macro is how you opt a type in. > **Note:** This page focuses on the derive macro itself: where you put it, what it generates, and how it behaves on every kind of `struct` and `enum`. Setting up the dependency is covered in [Serde Basics](/15-serialization/01-serde-basics/), the trait architecture in [Serde](/15-serialization/00-serde-intro/), and the many `#[serde(...)]` field attributes in [Serde Attributes](/15-serialization/05-attributes/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript you never *declare* a type serializable. Every plain object is fair game for `JSON.stringify`, and `JSON.parse` hands you back an untyped `any` that you assert into a shape: ```typescript 1 // TypeScript - serialization is implicit and works on any object 2 interface User { 3 id: number; 4 username: string; 5 email: string; 6 isActive: boolean; 7 } 8 9 const user: User = { 10 id: 42, 11 username: "ada", 12 email: "ada@example.com", 13 isActive: true, 14 }; 15 16 // Object -> JSON string. No declaration needed; structural and runtime-driven. 17 const json = JSON.stringify(user); 18 console.log(json); 19 // {"id":42,"username":"ada","email":"ada@example.com","isActive":true} 20 21 // JSON string -> object. The cast is a lie the compiler trusts blindly. 22 const parsed = JSON.parse(json) as User; 23 console.log(parsed.username); // "ada" ``` There are two hidden costs that Rust will make explicit: ```typescript 1 // 1. Methods and prototype are silently dropped — only data survives. 2 class Account { 3 constructor(public id: number, public name: string) {} 4 greet() { 5 return `Hi ${this.name}`; 6 } 7 } 8 9 const acct = new Account(7, "Grace"); 10 const restored = JSON.parse(JSON.stringify(acct)); 11 console.log(restored instanceof Account); // false 12 console.log(typeof restored.greet); // "undefined" 13 14 // 2. `as User` is unchecked. If the JSON is missing `email`, you get 15 // `undefined` at runtime with zero warning at the boundary. ``` *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) In Rust you annotate the type once. The derive macro generates the trait implementations the serializer needs: ```rust 1 // Cargo.toml: 2 // [dependencies] 3 // serde = { version = "1", features = ["derive"] } 4 // serde_json = "1" 5 use serde::{Deserialize, Serialize}; 6 7 #[derive(Debug, Serialize, Deserialize)] 8 struct User { 9 id: u64, 10 username: String, 11 email: String, 12 is_active: bool, 13 } 14 15 fn main() { 16 let user = User { 17 id: 42, 18 username: String::from("ada"), 19 email: String::from("ada@example.com"), 20 is_active: true, 21 }; 22 23 // Struct -> JSON string (serialize). 24 let json = serde_json::to_string(&user).unwrap(); 25 println!("{json}"); 26 27 // Pretty-printed JSON. 28 let pretty = serde_json::to_string_pretty(&user).unwrap(); 29 println!("{pretty}"); 30 31 // JSON string -> struct (deserialize). The type annotation tells Serde 32 // exactly which shape to build, and it is *checked*. 33 let parsed: User = serde_json::from_str(&json).unwrap(); 34 println!("{parsed:?}"); 35 } ``` Real output: ```text 1 {"id":42,"username":"ada","email":"ada@example.com","is_active":true} 2 { 3 "id": 42, 4 "username": "ada", 5 "email": "ada@example.com", 6 "is_active": true 7 } 8 User { id: 42, username: "ada", email: "ada@example.com", is_active: true } ``` The single `#[derive(Serialize, Deserialize)]` line replaces both `JSON.stringify` *capability* and the unchecked `as User` cast. Unlike the cast, deserialization actually validates that every required field is present and correctly typed. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What `derive` is, and why it is needed [Section titled “What derive is, and why it is needed”](#what-derive-is-and-why-it-is-needed) `Serialize` and `Deserialize` are **traits** (Rust’s version of interfaces — see [section 09](/09-generics-traits/)). A function like `serde_json::to_string` is generic over `T: Serialize`, so you can only pass it a value whose type implements `Serialize`. Rust has no runtime reflection, so there is no way to “just walk the fields” the way `JSON.stringify` does. Someone has to write the field-by-field code, and `#[derive(...)]` is that someone. `#[derive(Trait)]` runs a **procedural macro** at compile time that reads your type’s definition and emits an `impl Trait for YourType { ... }` block. (Macros are covered in depth in [section 14](/14-macros/).) It is *not* a runtime annotation or decorator; by the time your program runs, the generated code is indistinguishable from code you typed by hand. ### What the derive actually generates [Section titled “What the derive actually generates”](#what-the-derive-actually-generates) For a struct, the generated `Serialize` impl visits each field in declaration order. You rarely look at it, but it helps to see that it is plain, ordinary Rust. Here is a hand-written `Serialize` that is effectively what the derive produces: ```rust 1 use serde::ser::{Serialize, SerializeStruct, Serializer}; 2 3 struct User { 4 id: u64, 5 username: String, 6 is_active: bool, 7 } 8 9 // This is roughly what `#[derive(Serialize)]` writes for you. 10 impl Serialize for User { 11 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> 12 where 13 S: Serializer, 14 { 15 // Announce "I am a struct named User with 3 fields". 16 let mut state = serializer.serialize_struct("User", 3)?; 17 state.serialize_field("id", &self.id)?; 18 state.serialize_field("username", &self.username)?; 19 state.serialize_field("is_active", &self.is_active)?; 20 state.end() 21 } 22 } 23 24 fn main() { 25 let user = User { id: 42, username: "ada".into(), is_active: true }; 26 println!("{}", serde_json::to_string(&user).unwrap()); 27 // {"id":42,"username":"ada","is_active":true} 28 } ``` Real output: ```text 1 {"id":42,"username":"ada","is_active":true} ``` Two things to notice: * The impl is **format-agnostic**. It talks to an abstract `Serializer` (`serialize_struct`, `serialize_field`), not to JSON specifically. That is why the *same* derived type can also produce TOML or MessagePack — see [Beyond JSON](/15-serialization/06-other-formats/). * It is **recursive by composition**. `serialize_field("id", &self.id)` only works because `u64` itself implements `Serialize`. Serde ships impls for all the standard types (`String`, `Vec<T>`, `Option<T>`, `HashMap<K, V>`, etc.), and your derived impl reuses them. `Deserialize` is generated the same way but is considerably more code: it builds a “visitor” state machine that can accept fields in any order, report missing fields, and ignore unknown ones. It is verbose enough that you almost never want to write it by hand; that is the whole point of the derive. ([Custom Serialization](/15-serialization/07-custom-serialization/) covers the rare cases where you do.) ### `Serialize` and `Deserialize` are independent [Section titled “Serialize and Deserialize are independent”](#serialize-and-deserialize-are-independent) They are two separate traits, and you derive only what you need: * `#[derive(Serialize)]`: the type can be turned *into* a format (write-only). Common for response/output types. * `#[derive(Deserialize)]`: the type can be built *from* a format (read-only). Common for request/config types. * `#[derive(Serialize, Deserialize)]` — both directions, for types that round-trip. This is finer-grained than TypeScript, where every shape is implicitly both directions. ### Every field’s type must also implement the trait [Section titled “Every field’s type must also implement the trait”](#every-fields-type-must-also-implement-the-trait) This is the rule that trips up everyone coming from TypeScript. Because the generated code calls `serialize_field("address", &self.address)`, the type of `address` must *itself* implement `Serialize`. There is no “deep stringify everything” fallback. If a nested type lacks the derive, your code will not compile (see Common Pitfalls). ### It works on enums too [Section titled “It works on enums too”](#it-works-on-enums-too) Enums are where Serde shines compared to TypeScript’s hand-rolled discriminated unions. Each variant kind serializes to a distinct, predictable JSON shape: ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 enum Event { 5 // Unit variant: no data. 6 Logout, 7 // Newtype variant: one unnamed field. 8 PageView(String), 9 // Tuple variant: multiple unnamed fields. 10 Click(u32, u32), 11 // Struct variant: named fields. 12 Purchase { item_id: u64, quantity: u32 }, 13 } 14 15 fn main() { 16 let events = vec![ 17 Event::Logout, 18 Event::PageView(String::from("/home")), 19 Event::Click(120, 45), 20 Event::Purchase { item_id: 7, quantity: 2 }, 21 ]; 22 23 for event in &events { 24 println!("{}", serde_json::to_string(event).unwrap()); 25 } 26 } ``` Real output: ```text 1 "Logout" 2 {"PageView":"/home"} 3 {"Click":[120,45]} 4 {"Purchase":{"item_id":7,"quantity":2}} ``` This is the **externally tagged** representation, the default. The variant name becomes a JSON key (or, for a unit variant, a bare string). In TypeScript you would model this as a tagged union (`{ type: "purchase"; itemId: number }`) and check `e.type` by hand; Serde derives both the encode *and* the validated decode for you. You can switch to internally tagged, adjacently tagged, or untagged representations with `#[serde(tag = "...")]` and friends; those are covered in [Serde Attributes](/15-serialization/05-attributes/) and [Structs and JSON](/15-serialization/03-json/). ### Struct kinds and their JSON shapes [Section titled “Struct kinds and their JSON shapes”](#struct-kinds-and-their-json-shapes) The derive handles every shape of struct Rust allows, and each maps to a sensible JSON value: ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 struct Meters(f64); // newtype struct (one field) 5 6 #[derive(Debug, Serialize, Deserialize)] 7 struct Point(i32, i32); // tuple struct 8 9 #[derive(Debug, Serialize, Deserialize)] 10 struct Marker; // unit struct (no fields) 11 12 #[derive(Debug, Serialize, Deserialize)] 13 struct Wrapper<T> { 14 value: T, 15 label: String, 16 } 17 18 fn main() { 19 println!("{}", serde_json::to_string(&Meters(3.5)).unwrap()); 20 println!("{}", serde_json::to_string(&Point(1, 2)).unwrap()); 21 println!("{}", serde_json::to_string(&Marker).unwrap()); 22 23 let w = Wrapper { value: vec![1, 2, 3], label: "nums".into() }; 24 println!("{}", serde_json::to_string(&w).unwrap()); 25 } ``` Real output: ```text 1 3.5 2 [1,2] 3 null 4 {"value":[1,2,3],"label":"nums"} ``` * A **newtype struct** is transparent: it serializes as its single inner value (`3.5`, not `{"0":3.5}`). * A **tuple struct** serializes as a JSON array. * A **unit struct** serializes as `null`. * A **generic struct** works too: the derive automatically adds a `T: Serialize` (or `T: Deserialize`) bound to the generated impl, so `Wrapper<T>` is serializable exactly when its `T` is. This is one place the macro is smarter than a copy-paste impl would be. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | TypeScript / JavaScript | Rust + Serde derive | | ---------------------- | ------------------------------------- | ------------------------------------------------------ | | Who can be serialized | Any value, implicitly | Only types that implement `Serialize` | | When that is decided | At runtime, by walking properties | At compile time, by the derive macro | | Direction control | Always both ways | `Serialize` and `Deserialize` are separate, opt-in | | Nested types | Recursively walked automatically | Each field type must *also* implement the trait | | Deserialization safety | `JSON.parse(...) as T` is unchecked | Missing/mismatched fields are real, recoverable errors | | Methods/behavior | Silently dropped (only data survives) | N/A: only the data fields exist; no methods to lose | | Generics | Erased at runtime | Monomorphized; derive adds bounds like `T: Serialize` | | Cost | Reflection on every call | Zero runtime reflection; code is generated once | > **Tip:** The most useful one-sentence summary for a TypeScript developer: *`#[derive(Serialize, Deserialize)]` is how you make a type “JSON-ready,” and the compiler enforces that everything it contains is ready too.* ### Why Rust does it this way [Section titled “Why Rust does it this way”](#why-rust-does-it-this-way) Rust has no runtime type information by design — generics are monomorphized away (the opposite of TypeScript’s type erasure), and there is no prototype chain to walk. Pushing serialization into compile-time generated code means it is **fast** (no reflection), **type-checked** (you cannot serialize something half-defined), and **format-agnostic** (the same impl drives JSON, YAML, binary formats, and more). The trade-off is the one line of `#[derive(...)]` you must remember to write. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: A nested field type forgot the derive [Section titled “Pitfall 1: A nested field type forgot the derive”](#pitfall-1-a-nested-field-type-forgot-the-derive) This is the number-one error. You derive `Serialize` on the outer struct but forget it on a type it contains: ```rust 1 use serde::{Deserialize, Serialize}; 2 3 struct Address { 4 city: String, 5 } // no derive here 6 7 #[derive(Serialize, Deserialize)] 8 struct Person { 9 name: String, 10 address: Address, // requires Address: Serialize + Deserialize 11 } 12 13 fn main() { 14 let p = Person { name: "Ada".into(), address: Address { city: "London".into() } }; 15 let _ = serde_json::to_string(&p); 16 } ``` The real compiler error (`cargo build`): ```text 1 error[E0277]: the trait bound `Address: serde::Serialize` is not satisfied 2 --> src/main.rs:7:10 3 | 4 7 | #[derive(Serialize, Deserialize)] 5 | ^^^^^^^^^ the trait `Serialize` is not implemented for `Address` 6 ... 7 10 | address: Address, 8 | ------- required by a bound introduced by this call 9 | 10 = note: for local types consider adding `#[derive(serde::Serialize)]` to your `Address` type 11 = note: for types from other crates check whether the crate offers a `serde` feature flag ``` **Fix:** add `#[derive(Serialize, Deserialize)]` to `Address` too. The compiler note spells out both cases: derive it yourself for your own types, or enable the dependency’s `serde` feature for third-party types (for example `uuid = { version = "1", features = ["serde"] }`). ### Pitfall 2: Borrowing `&str` fields that outlive the source bytes [Section titled “Pitfall 2: Borrowing \&str fields that outlive the source bytes”](#pitfall-2-borrowing-str-fields-that-outlive-the-source-bytes) It is tempting to deserialize into a struct that *borrows* from the input (`&str` instead of `String`) for speed. That works, but the borrowed data cannot outlive the buffer it points into: ```rust 1 use serde::Deserialize; 2 3 #[derive(Debug, Deserialize)] 4 struct Config<'a> { 5 name: &'a str, 6 } 7 8 fn parse_config() -> Config<'static> { 9 let data = String::from(r#"{"name":"prod"}"#); 10 let cfg: Config = serde_json::from_str(&data).unwrap(); 11 cfg // does not compile (error0515): `data` is dropped at end of fn 12 } 13 14 fn main() { 15 println!("{:?}", parse_config()); 16 } ``` The real compiler error: ```text 1 error[E0515]: cannot return value referencing local variable `data` 2 --> src/main.rs:11:5 3 | 4 10 | let cfg: Config = serde_json::from_str(&data).unwrap(); 5 | ----- `data` is borrowed here 6 11 | cfg 7 | ^^^ returns a value referencing data owned by the current function ``` **Fix:** if you need the data to live independently, use owned fields (`name: String`). Use borrowed fields only when the input buffer clearly outlives the struct. Zero-copy deserialization and `#[serde(borrow)]` are explored in [Serde Performance](/15-serialization/08-performance/). ### Pitfall 3: Importing the wrong `Serialize`/`Deserialize` [Section titled “Pitfall 3: Importing the wrong Serialize/Deserialize”](#pitfall-3-importing-the-wrong-serializedeserialize) The names you derive must be in scope and must be Serde’s. A common mistake is to write `#[derive(Serialize)]` without `use serde::Serialize;`, or to confuse the *derive macro* (used in `#[derive(...)]`) with the *trait* (used in `T: Serialize` bounds). With the `derive` feature enabled, a single `use serde::{Deserialize, Serialize};` brings both the traits and the same-named derive macros into scope, which is why that import line appears at the top of nearly every Serde example. ### Pitfall 4: Expecting `Debug` and `Serialize` to be the same thing [Section titled “Pitfall 4: Expecting Debug and Serialize to be the same thing”](#pitfall-4-expecting-debug-and-serialize-to-be-the-same-thing) `#[derive(Debug)]` gives you `{:?}` formatting for logs; it is *not* serialization. They are separate derives. You will frequently see them together (`#[derive(Debug, Serialize, Deserialize)]`) but each does its own job: `Debug` output is for humans and is not guaranteed stable, while `Serialize` output is a real data format you can parse back. ### Pitfall 5: Assuming unknown JSON fields cause an error [Section titled “Pitfall 5: Assuming unknown JSON fields cause an error”](#pitfall-5-assuming-unknown-json-fields-cause-an-error) By default, deserialization **ignores** fields in the input that your struct does not declare. This is usually what you want for forward-compatible APIs, but it can hide typos: ```rust 1 use serde::Deserialize; 2 3 #[derive(Debug, Deserialize)] 4 struct Temperature { 5 celsius: f64, 6 } 7 8 fn main() { 9 // The extra "humidity" key is silently ignored. 10 let json = r#"{"celsius":21.5,"humidity":40}"#; 11 let parsed: Temperature = serde_json::from_str(json).unwrap(); 12 println!("{parsed:?}"); // Temperature { celsius: 21.5 } 13 } ``` Real output: ```text 1 Temperature { celsius: 21.5 } ``` **Fix:** if you want unknown fields to be a hard error, add `#[serde(deny_unknown_fields)]` to the struct (see [Serde Attributes](/15-serialization/05-attributes/)). Conversely, a *missing required* field is always an error — that asymmetry is what makes deserialization safer than a bare `as T` cast. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Put the derive on the data type, once.** Keep `#[derive(Serialize, Deserialize)]` on the plain data struct/enum and let it propagate through composition. Do not scatter manual impls unless you genuinely need custom behavior. * **Derive only the direction you use.** Output-only DTOs need just `Serialize`; config/request types that you only read need just `Deserialize`. It keeps intent clear and compile times marginally lower. * **Pair with `Debug`.** `#[derive(Debug, Serialize, Deserialize)]` is the workhorse combination: `Debug` for logging, the Serde pair for the wire. * **Prefer owned fields (`String`, `Vec<T>`) by default.** Reach for borrowed `&str` / `#[serde(borrow)]` only when profiling shows it matters; the ownership headaches (Pitfall 2) are rarely worth it up front. * **Keep field names matching the wire format, or use attributes — not a second struct.** If your API uses `camelCase`, add `#[serde(rename_all = "camelCase")]` rather than maintaining a parallel type. See [Serde Attributes](/15-serialization/05-attributes/). * **Enable the `serde` feature on third-party crates** (e.g. `chrono`, `uuid`, `rust_decimal`) instead of writing wrapper types, so their inner types implement the traits directly. * **Let the derive add generic bounds for you.** For generic types, write the derive normally; Serde inserts `T: Serialize`/`T: Deserialize` automatically. Override with `#[serde(bound = "...")]` only in advanced cases. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A typical domain model for an e-commerce order: nested structs, an enum with data-carrying variants, a `Vec`, and a `HashMap`, all serializable from a single derive on each type, and verified to round-trip. ```rust 1 // Cargo.toml: 2 // [dependencies] 3 // serde = { version = "1", features = ["derive"] } 4 // serde_json = "1" 5 use serde::{Deserialize, Serialize}; 6 use std::collections::HashMap; 7 8 #[derive(Debug, Serialize, Deserialize)] 9 struct Money { 10 amount_cents: u64, 11 currency: String, 12 } 13 14 #[derive(Debug, Serialize, Deserialize)] 15 enum OrderStatus { 16 Pending, 17 Shipped { tracking_number: String }, 18 Cancelled, 19 } 20 21 #[derive(Debug, Serialize, Deserialize)] 22 struct LineItem { 23 sku: String, 24 quantity: u32, 25 unit_price: Money, // nested type — also derives the traits 26 } 27 28 #[derive(Debug, Serialize, Deserialize)] 29 struct Order { 30 order_id: String, 31 status: OrderStatus, // enum field 32 items: Vec<LineItem>, // collection of nested structs 33 metadata: HashMap<String, String>, 34 } 35 36 fn main() { 37 let mut metadata = HashMap::new(); 38 metadata.insert("source".to_string(), "web".to_string()); 39 40 let order = Order { 41 order_id: "ord_1001".into(), 42 status: OrderStatus::Shipped { tracking_number: "TRK-9".into() }, 43 items: vec![LineItem { 44 sku: "BOOK-42".into(), 45 quantity: 2, 46 unit_price: Money { amount_cents: 1599, currency: "USD".into() }, 47 }], 48 metadata, 49 }; 50 51 // Serialize the whole graph in one call. 52 let json = serde_json::to_string_pretty(&order).unwrap(); 53 println!("{json}"); 54 55 // Deserialize it straight back into the typed model. 56 let round_tripped: Order = serde_json::from_str(&json).unwrap(); 57 assert_eq!(round_tripped.order_id, order.order_id); 58 println!("round-trip OK"); 59 } ``` Real output: ```text 1 { 2 "order_id": "ord_1001", 3 "status": { 4 "Shipped": { 5 "tracking_number": "TRK-9" 6 } 7 }, 8 "items": [ 9 { 10 "sku": "BOOK-42", 11 "quantity": 2, 12 "unit_price": { 13 "amount_cents": 1599, 14 "currency": "USD" 15 } 16 } 17 ], 18 "metadata": { 19 "source": "web" 20 } 21 } 22 round-trip OK ``` One derive per type and the entire nested graph — struct inside struct inside `Vec`, plus an enum and a map — serializes and deserializes with full type checking. This same `Order` type is exactly what you would return from a web handler; see how it plugs into HTTP responses in [section 16](/16-web-apis/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [Serde derive — official documentation](https://serde.rs/derive.html): the canonical reference for what the derive generates. * [Serde data model](https://serde.rs/data-model.html) — the 29 types that sit between your structs and every format. * [Enum representations](https://serde.rs/enum-representations.html) — externally/internally/adjacently tagged and untagged. * [`serde_json` crate docs](https://docs.rs/serde_json/) — `to_string`, `from_str`, and friends. * This guide: * [Serde](/15-serialization/00-serde-intro/) — the `Serialize`/`Deserialize` traits and the data-model architecture. * [Serde Basics](/15-serialization/01-serde-basics/) — adding the dependency with `features = ["derive"]` and the basic API. * [Structs and JSON](/15-serialization/03-json/): structs and enums to JSON in depth, including `Option` and collection fields. * [Serde Attributes](/15-serialization/05-attributes/) — `rename`, `rename_all`, `skip`, `default`, `flatten`, `tag`, and more. * [Custom Serialization](/15-serialization/07-custom-serialization/): hand-writing `Serialize`/`Deserialize` when the derive is not enough. * [Beyond JSON](/15-serialization/06-other-formats/) — the *same* derived types as TOML, YAML, MessagePack, and binary. * [Serde Performance](/15-serialization/08-performance/): borrowing, zero-copy, and avoiding `Value`. * [Section 09: Generics & Traits](/09-generics-traits/) — what traits are and how trait bounds work. * [Section 14: Macros](/14-macros/): how derive macros generate code at compile time. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Make a type round-trip [Section titled “Exercise 1: Make a type round-trip”](#exercise-1-make-a-type-round-trip) **Difficulty:** Easy **Objective:** Get comfortable adding the derive and round-tripping a value through JSON. **Instructions:** 1. Define a `BlogPost` struct with fields `title: String`, `author: String`, `tags: Vec<String>`, and `published: bool`. 2. Make it both serializable and deserializable. 3. In `main`, construct a value, serialize it to a JSON string, print it, then deserialize it back and print the resulting struct with `{:?}`. ```rust 1 use serde::{Deserialize, Serialize}; 2 3 // TODO: add the right derive(s) 4 struct BlogPost { 5 title: String, 6 author: String, 7 tags: Vec<String>, 8 published: bool, 9 } 10 11 fn main() { 12 // TODO: build, serialize, print, deserialize, print 13 } ``` Solution ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 struct BlogPost { 5 title: String, 6 author: String, 7 tags: Vec<String>, 8 published: bool, 9 } 10 11 fn main() { 12 let post = BlogPost { 13 title: "Rust for TS devs".into(), 14 author: "ada".into(), 15 tags: vec!["rust".into(), "serde".into()], 16 published: true, 17 }; 18 19 let json = serde_json::to_string(&post).unwrap(); 20 println!("{json}"); 21 // {"title":"Rust for TS devs","author":"ada","tags":["rust","serde"],"published":true} 22 23 let back: BlogPost = serde_json::from_str(&json).unwrap(); 24 println!("{back:?}"); 25 // BlogPost { title: "Rust for TS devs", author: "ada", tags: ["rust", "serde"], published: true } 26 } ``` ### Exercise 2: A data-carrying enum and a deserialization error [Section titled “Exercise 2: A data-carrying enum and a deserialization error”](#exercise-2-a-data-carrying-enum-and-a-deserialization-error) **Difficulty:** Medium **Objective:** Observe how struct-variant enums serialize, and see a *real* error when a required field is missing. **Instructions:** 1. Define an enum `Shape` with three struct variants: `Circle { radius: f64 }`, `Rectangle { width: f64, height: f64 }`, and `Triangle { base: f64, height: f64 }`. Derive both Serde traits. 2. Write a function `area(&Shape) -> f64` that `match`es each variant. 3. Serialize one of each variant and print the JSON alongside its area. 4. Then attempt to deserialize the *invalid* JSON `{"Circle":{}}` (missing `radius`) into a `Shape`, and print the error message instead of unwrapping. Solution ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 enum Shape { 5 Circle { radius: f64 }, 6 Rectangle { width: f64, height: f64 }, 7 Triangle { base: f64, height: f64 }, 8 } 9 10 fn area(shape: &Shape) -> f64 { 11 match shape { 12 Shape::Circle { radius } => std::f64::consts::PI * radius * radius, 13 Shape::Rectangle { width, height } => width * height, 14 Shape::Triangle { base, height } => 0.5 * base * height, 15 } 16 } 17 18 fn main() { 19 let shapes = vec![ 20 Shape::Circle { radius: 2.0 }, 21 Shape::Rectangle { width: 3.0, height: 4.0 }, 22 Shape::Triangle { base: 6.0, height: 2.0 }, 23 ]; 24 25 for s in &shapes { 26 println!("{} -> area {:.2}", serde_json::to_string(s).unwrap(), area(s)); 27 } 28 29 // A missing required field is a real, recoverable error. 30 let bad = r#"{"Circle":{}}"#; 31 let result: Result<Shape, _> = serde_json::from_str(bad); 32 println!("{:?}", result.err().map(|e| e.to_string())); 33 } ``` Real output: ```text 1 {"Circle":{"radius":2.0}} -> area 12.57 2 {"Rectangle":{"width":3.0,"height":4.0}} -> area 12.00 3 {"Triangle":{"base":6.0,"height":2.0}} -> area 6.00 4 Some("missing field `radius` at line 1 column 12") ``` ### Exercise 3: Hand-write what the derive generates [Section titled “Exercise 3: Hand-write what the derive generates”](#exercise-3-hand-write-what-the-derive-generates) **Difficulty:** Hard **Objective:** Prove to yourself that `#[derive(Serialize)]` produces ordinary code by writing an equivalent `impl` and confirming it yields byte-identical JSON. **Instructions:** 1. Define a `Temperature` struct with one field `celsius: f64`. Derive only `Deserialize` on it. 2. Hand-write `impl Serialize for Temperature` using `serialize_struct` / `serialize_field` / `end`, matching the field name `"celsius"` exactly. 3. Define a second struct `TemperatureDerived` with the same field but `#[derive(Serialize)]`. 4. Serialize one value of each and `assert_eq!` that the two JSON strings are identical. Solution ```rust 1 use serde::ser::{Serialize, SerializeStruct, Serializer}; 2 use serde::Deserialize; 3 4 #[derive(Debug, Deserialize)] 5 struct Temperature { 6 celsius: f64, 7 } 8 9 // Hand-written Serialize that mirrors the derive output exactly. 10 impl Serialize for Temperature { 11 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> 12 where 13 S: Serializer, 14 { 15 let mut state = serializer.serialize_struct("Temperature", 1)?; 16 state.serialize_field("celsius", &self.celsius)?; 17 state.end() 18 } 19 } 20 21 #[derive(Debug, serde::Serialize)] 22 struct TemperatureDerived { 23 celsius: f64, 24 } 25 26 fn main() { 27 let manual = Temperature { celsius: 21.5 }; 28 let derived = TemperatureDerived { celsius: 21.5 }; 29 30 let a = serde_json::to_string(&manual).unwrap(); 31 let b = serde_json::to_string(&derived).unwrap(); 32 println!("manual: {a}"); 33 println!("derived: {b}"); 34 35 assert_eq!(a, b); 36 println!("identical: {}", a == b); 37 } ``` Real output: ```text 1 manual: {"celsius":21.5} 2 derived: {"celsius":21.5} 3 identical: true ``` # Structs and JSON > TypeScript's JSON.parse as User is an unchecked cast; Rust maps JSON onto typed structs and enums with serde_json, validating every field, Option, and tagged union. In TypeScript you reach for `JSON.parse` / `JSON.stringify` and trust that the bytes match your `interface`. In Rust, you map JSON onto strongly typed **structs** and **enums** with Serde, and the compiler — plus the deserializer — guarantees the shape really matches before you ever touch a field. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) This page is about mapping JSON documents onto Rust **structs** and **enums**: nested objects, arrays (`Vec<T>`), dynamically keyed objects (`HashMap<K, V>`), optional/`null` fields (`Option<T>`), and the four ways Serde can represent an enum (tagged unions) in JSON. You will use [`serde_json`](https://docs.rs/serde_json) to turn typed values into JSON and back, with the same `#[derive(Serialize, Deserialize)]` you met in [Serde Basics](/15-serialization/01-serde-basics/) and [Deriving `Serialize` and `Deserialize`](/15-serialization/02-derive-serialize/). The big shift from TypeScript: the structure is checked at deserialization time, not merely asserted at compile time and then ignored at runtime. > **Note:** The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects the newest edition automatically. The examples here use `serde` 1.x (with the `derive` feature) and `serde_json` 1.x. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // TypeScript: an interface describes the shape, JSON.* moves bytes <-> objects. 2 interface Address { 3 street: string; 4 city: string; 5 zip: string; 6 } 7 8 interface User { 9 id: number; 10 name: string; 11 email: string; 12 address: Address; // nested object 13 roles: string[]; // JSON array 14 settings: Record<string, boolean>; // object with dynamic keys 15 nickname: string | null; // may be absent or null 16 } 17 18 const user: User = { 19 id: 7, 20 name: "Ada Lovelace", 21 email: "ada@example.com", 22 address: { street: "12 Analytical Ave", city: "London", zip: "EC1A" }, 23 roles: ["admin", "author"], 24 settings: { dark_mode: true }, 25 nickname: null, 26 }; 27 28 const json = JSON.stringify(user); 29 const parsed = JSON.parse(json) as User; // <- a cast, NOT a check 30 console.log(parsed.address.city); // "London" ``` The catch: `JSON.parse(json) as User` is a **lie the compiler believes**. TypeScript types are erased at runtime, so if the server sends `{ "id": "7" }` or omits `address`, `parsed` still has type `User` and you crash later, far from the parse site. The `as` cast performs zero validation. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 use serde::{Deserialize, Serialize}; 2 use std::collections::HashMap; 3 4 #[derive(Debug, Serialize, Deserialize)] 5 struct Address { 6 street: String, 7 city: String, 8 zip: String, 9 } 10 11 #[derive(Debug, Serialize, Deserialize)] 12 struct User { 13 id: u32, 14 name: String, 15 email: String, 16 address: Address, // nested struct 17 roles: Vec<String>, // JSON array 18 settings: HashMap<String, bool>, // JSON object with dynamic keys 19 nickname: Option<String>, // may be absent / null 20 } 21 22 fn main() { 23 let mut settings = HashMap::new(); 24 settings.insert("dark_mode".to_string(), true); 25 26 let user = User { 27 id: 7, 28 name: "Ada Lovelace".to_string(), 29 email: "ada@example.com".to_string(), 30 address: Address { 31 street: "12 Analytical Ave".to_string(), 32 city: "London".to_string(), 33 zip: "EC1A".to_string(), 34 }, 35 roles: vec!["admin".to_string(), "author".to_string()], 36 settings, 37 nickname: None, 38 }; 39 40 // Serialize to a compact JSON string. 41 let json = serde_json::to_string(&user).unwrap(); 42 println!("compact: {json}"); 43 44 // Pretty-printed (two-space indent). 45 let pretty = serde_json::to_string_pretty(&user).unwrap(); 46 println!("pretty:\n{pretty}"); 47 48 // Round-trip: parse it back into a typed value. This VALIDATES the shape. 49 let parsed: User = serde_json::from_str(&json).unwrap(); 50 println!("parsed city: {}", parsed.address.city); 51 println!("nickname is none: {}", parsed.nickname.is_none()); 52 } ``` Real output: ```text 1 compact: {"id":7,"name":"Ada Lovelace","email":"ada@example.com","address":{"street":"12 Analytical Ave","city":"London","zip":"EC1A"},"roles":["admin","author"],"settings":{"dark_mode":true},"nickname":null} 2 pretty: 3 { 4 "id": 7, 5 "name": "Ada Lovelace", 6 "email": "ada@example.com", 7 "address": { 8 "street": "12 Analytical Ave", 9 "city": "London", 10 "zip": "EC1A" 11 }, 12 "roles": [ 13 "admin", 14 "author" 15 ], 16 "settings": { 17 "dark_mode": true 18 }, 19 "nickname": null 20 } 21 parsed city: London 22 nickname is none: true ``` Unlike TypeScript’s `as User`, `serde_json::from_str::<User>(...)` actually inspects the JSON. If `id` is a string, or `address` is missing, you get an `Err`, not a time bomb. We’ll see those exact error messages in [Common Pitfalls](#common-pitfalls). *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The two-step model: data type, then format [Section titled “The two-step model: data type, then format”](#the-two-step-model-data-type-then-format) Serde splits the work cleanly. `#[derive(Serialize, Deserialize)]` teaches your **type** how to describe itself as a stream of generic data-model events (“a struct with field `id` of value `7`…”). `serde_json` is the **format** crate that turns those events into JSON bytes and back. The same derived `User` works with TOML, YAML, MessagePack, and more (see [Beyond JSON](/15-serialization/06-other-formats/)) without changing the struct. This architecture is covered in [Serde](/15-serialization/00-serde-intro/). ### Field mapping, one line at a time [Section titled “Field mapping, one line at a time”](#field-mapping-one-line-at-a-time) * `id: u32` ↔ a JSON number. Rust’s many integer types ([Section 02: Basic Types](/02-basics/01-types/)) all map to JSON numbers, but they round-trip with their full range — unlike JavaScript, where every `number` is an IEEE-754 `f64` and integers past 2^53 silently lose precision. A `u64` in Rust keeps every bit. * `name: String` ↔ a JSON string. (`String` is the owned, growable string; `&str` borrows. See [Serde Performance](/15-serialization/08-performance/) for borrowing JSON without copying.) * `address: Address` ↔ a nested JSON object. Serde recurses: as long as `Address` also derives the traits, nesting “just works” to any depth. * `roles: Vec<String>` ↔ a JSON array. Any `Vec<T>` where `T` is (de)serializable becomes an array; a `Vec<Address>` becomes an array of objects. * `settings: HashMap<String, bool>` ↔ a JSON object with arbitrary keys. Use a `HashMap` (or `BTreeMap` for sorted, deterministic key order) when the keys are data you don’t know at compile time. Use a `struct` when the keys are a fixed, known set. * `nickname: Option<String>` ↔ a value that may be `null` or absent. `Some("x")` serializes to `"x"`, `None` serializes to `null`. On the way in, both `null` **and a missing key** become `None`. ### Serializing: `to_string`, `to_string_pretty`, `to_vec` [Section titled “Serializing: to\_string, to\_string\_pretty, to\_vec”](#serializing-to_string-to_string_pretty-to_vec) `serde_json::to_string(&value)` returns a compact `String`. `to_string_pretty` adds newlines and two-space indentation for human-readable output (logs, config files, debugging). When you’re writing bytes to a socket or file, `serde_json::to_vec(&value)` skips the UTF-8 `String` step and hands you a `Vec<u8>` directly. All three return `Result` because a custom `Serialize` impl can fail; for plain derived structs it effectively never does, so `.unwrap()` is fine in examples (use `?` in real code — see [Section 08: The `?` Operator](/08-error-handling/01-question-mark/)). ### Deserializing validates the shape [Section titled “Deserializing validates the shape”](#deserializing-validates-the-shape) `serde_json::from_str::<T>(s)` parses the text and builds a `T`, returning `Result<T, serde_json::Error>`. Every field is checked: types must match, non-optional fields must be present. This is the single most important difference from `JSON.parse(...) as T`. The cost of a typo or a schema drift is paid **at the boundary**, as an `Err` you handle, rather than as an `undefined` that detonates three function calls later. ### Top-level arrays and maps [Section titled “Top-level arrays and maps”](#top-level-arrays-and-maps) You don’t need a wrapper struct for everything. A JSON array of objects deserializes straight into a `Vec<T>`: ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 struct Point { 5 x: i32, 6 y: i32, 7 } 8 9 fn main() { 10 let points: Vec<Point> = 11 serde_json::from_str(r#"[{"x":1,"y":2},{"x":3,"y":4}]"#).unwrap(); 12 println!("points: {points:?}"); 13 } ``` Output: `points: [Point { x: 1, y: 2 }, Point { x: 3, y: 4 }]`. ### Enums: tagged unions, four ways [Section titled “Enums: tagged unions, four ways”](#enums-tagged-unions-four-ways) A TypeScript discriminated union like `{ kind: "circle"; radius: number } | { kind: "rect"; w: number; h: number }` maps onto a Rust `enum`. Serde offers four JSON **representations**, chosen with attributes. Given: ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 enum Shape { 5 Circle { radius: f64 }, 6 Rectangle { width: f64, height: f64 }, 7 Unit, 8 } ``` the **default (externally tagged)** form wraps each value in an object keyed by the variant name (and a bare string for a unit variant): ```text 1 [{"Circle":{"radius":1.5}},{"Rectangle":{"width":2.0,"height":3.0}},"Unit"] ``` Add `#[serde(tag = "type")]` for the **internally tagged** form: the variant name lives in a field alongside the data, which is what most web APIs use: ```rust 1 #[derive(Debug, Serialize, Deserialize)] 2 #[serde(tag = "type")] 3 enum Event { 4 Click { x: i32, y: i32 }, 5 KeyPress { key: String }, 6 } ``` ```text 1 [{"type":"Click","x":10,"y":20},{"type":"KeyPress","key":"Enter"}] ``` `#[serde(tag = "kind", content = "data")]` gives the **adjacently tagged** form (tag and payload in two sibling fields): ```rust 1 #[derive(Debug, Serialize, Deserialize)] 2 #[serde(tag = "kind", content = "data")] 3 enum Message { 4 Text(String), 5 Ping, 6 } ``` ```text 1 [{"kind":"Text","data":"hi"},{"kind":"Ping"}] ``` Finally, `#[serde(untagged)]` produces **untagged** values that carry no discriminator at all. Serde tries each variant in order and keeps the first that fits: ```rust 1 #[derive(Debug, Serialize, Deserialize)] 2 #[serde(untagged)] 3 enum Scalar { 4 Num(i64), 5 Text(String), 6 } ``` ```text 1 [42,"abc"] ``` Serializing one value of each enum side by side makes the four shapes easy to compare: ```text 1 external: [{"Circle":{"radius":1.5}},{"Rectangle":{"width":2.0,"height":3.0}},"Unit"] 2 internal: [{"type":"Click","x":10,"y":20},{"type":"KeyPress","key":"Enter"}] 3 adjacent: [{"kind":"Text","data":"hi"},{"kind":"Ping"}] 4 untagged: [42,"abc"] ``` > **Note:** Adjacent and external tagging both accept a newtype variant such as `Message::Text(String)`, because the payload lives in its own slot (the `data` field, or the value behind the variant key). Internal tagging is the exception: a newtype variant works with `#[serde(tag = "...")]` only if it wraps a struct or map, since the tag field has to be merged into the payload object. The `tag`/`content`/`untagged` attributes are part of the broader attribute toolkit covered in [Serde Attributes](/15-serialization/05-attributes/). ### Option fields: missing vs. `null` [Section titled “Option fields: missing vs. null”](#option-fields-missing-vs-null) This trips up everyone, so it’s worth a dedicated demonstration: ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 struct Profile { 5 name: String, 6 bio: Option<String>, 7 } 8 9 fn main() { 10 // Field present with a value. 11 let a: Profile = serde_json::from_str(r#"{"name":"A","bio":"hello"}"#).unwrap(); 12 println!("with value: {:?}", a.bio); 13 14 // Field present but null. 15 let b: Profile = serde_json::from_str(r#"{"name":"B","bio":null}"#).unwrap(); 16 println!("explicit null: {:?}", b.bio); 17 18 // Field entirely missing -> also None. 19 let c: Profile = serde_json::from_str(r#"{"name":"C"}"#).unwrap(); 20 println!("missing field: {:?}", c.bio); 21 22 // Serializing None emits null by default. 23 let p = Profile { name: "D".into(), bio: None }; 24 println!("serialized None: {}", serde_json::to_string(&p).unwrap()); 25 } ``` Output: ```text 1 with value: Some("hello") 2 explicit null: None 3 missing field: None 4 serialized None: {"name":"D","bio":null} ``` Two takeaways: an `Option<T>` field makes the key optional on the way in (both `null` and “absent” deserialize to `None`), and `None` serializes to `null` on the way out. If you’d rather **omit** the key entirely when it’s `None`, add `#[serde(skip_serializing_if = "Option::is_none")]`. See [Serde Attributes](/15-serialization/05-attributes/). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concern | TypeScript (`JSON.*`) | Rust (Serde + `serde_json`) | | -------------------- | ---------------------------------------------------------- | --------------------------------------------------------------- | | Validation on parse | None; `as T` is an unchecked cast, types erased at runtime | Full: types and required fields checked; mismatch → `Err` | | Integer precision | All numbers are `f64`; integers > 2^53 lose precision | Each integer type keeps its full range (`u64` is exact) | | Optional fields | `field?: T` or \`T | undefined\`; runtime presence unknown | | Dynamic-keyed object | `Record<string, V>` | `HashMap<String, V>` / `BTreeMap<String, V>` | | Discriminated union | \`{ kind: “a” } | { kind: “b” }\` | | Unknown extra fields | Silently kept on the object | Silently **ignored** by default; opt into `deny_unknown_fields` | | Where errors surface | Late, deep in your code | At the parse boundary, as a value | The mental shift: in TypeScript, JSON validation is *your* job (or a library like Zod’s). In Rust, the deserializer **is** the validator, generated from the type definition. You describe the shape once, in the struct, and get parsing, validation, and serialization for free. > **Tip:** Serde does not invent a runtime schema validator. It generates exact (de)serialization code per type at compile time via monomorphization, the same way Rust handles generics generally (TypeScript erases generics; Rust specializes them). There is no reflection and no per-call schema lookup. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Assuming a missing field is harmless [Section titled “Pitfall 1: Assuming a missing field is harmless”](#pitfall-1-assuming-a-missing-field-is-harmless) A non-`Option` field is **required**. Leave it out and deserialization fails, which is usually what you want, but it surprises developers coming from `JSON.parse`’s permissiveness. ```rust 1 use serde::Deserialize; 2 3 #[derive(Debug, Deserialize)] 4 struct Config { 5 host: String, 6 port: u16, 7 } 8 9 fn main() { 10 // "port" is missing from the JSON. 11 let result: Result<Config, _> = serde_json::from_str(r#"{"host":"localhost"}"#); 12 match result { 13 Ok(c) => println!("ok: {}:{}", c.host, c.port), 14 Err(e) => println!("error: {e}"), 15 } 16 17 // Wrong type: port is a string, not a number. 18 let result2: Result<Config, _> = 19 serde_json::from_str(r#"{"host":"localhost","port":"8080"}"#); 20 match result2 { 21 Ok(c) => println!("ok: {}:{}", c.host, c.port), 22 Err(e) => println!("error: {e}"), 23 } 24 } ``` Real output: ```text 1 error: missing field `port` at line 1 column 20 2 error: invalid type: string "8080", expected u16 at line 1 column 33 ``` The fix is intentional: make the field `Option<u16>`, or add `#[serde(default)]` to fall back to `u16::default()` (which is `0`) when absent. Both are covered in [Serde Attributes](/15-serialization/05-attributes/). The second error is the precision/type guarantee in action: `"8080"` (a string) is *not* accepted where a `u16` is expected, even though JavaScript’s `+"8080"` would coerce. ### Pitfall 2: Expecting unknown fields to be rejected [Section titled “Pitfall 2: Expecting unknown fields to be rejected”](#pitfall-2-expecting-unknown-fields-to-be-rejected) By default, Serde **ignores** JSON keys that don’t map to a struct field. This is forgiving (good for evolving APIs) but can hide typos in your data. ```rust 1 use serde::Deserialize; 2 3 // Unknown fields are silently ignored by default. 4 #[derive(Debug, Deserialize)] 5 struct Lenient { 6 name: String, 7 } 8 9 // deny_unknown_fields makes extra keys an error. 10 #[derive(Debug, Deserialize)] 11 #[serde(deny_unknown_fields)] 12 struct Strict { 13 name: String, 14 } 15 16 fn main() { 17 let json = r#"{"name":"Grace","extra":true,"another":42}"#; 18 19 let lenient: Lenient = serde_json::from_str(json).unwrap(); 20 println!("lenient ok: {}", lenient.name); 21 22 let strict: Result<Strict, _> = serde_json::from_str(json); 23 match strict { 24 Ok(s) => println!("strict ok: {}", s.name), 25 Err(e) => println!("strict error: {e}"), 26 } 27 } ``` Real output: ```text 1 lenient ok: Grace 2 strict error: unknown field `extra`, expected `name` at line 1 column 23 ``` ### Pitfall 3: Untagged enum variant order [Section titled “Pitfall 3: Untagged enum variant order”](#pitfall-3-untagged-enum-variant-order) With `#[serde(untagged)]`, Serde tries variants **top to bottom** and accepts the first that parses. Put a broad variant first and it will swallow inputs meant for a stricter one. A JSON `42` is a valid `f64`, so a `Float`-first enum never reaches `Int`: ```rust 1 use serde::{Deserialize, Serialize}; 2 3 // WRONG order: Float matches integers too, so 42 deserializes as Float(42.0). 4 #[derive(Debug, Serialize, Deserialize)] 5 #[serde(untagged)] 6 enum NumWrong { 7 Float(f64), 8 Int(i64), 9 } 10 11 // RIGHT order: try the stricter Int variant first. 12 #[derive(Debug, Serialize, Deserialize)] 13 #[serde(untagged)] 14 enum NumRight { 15 Int(i64), 16 Float(f64), 17 } 18 19 fn main() { 20 let w: NumWrong = serde_json::from_str("42").unwrap(); 21 println!("wrong order, input 42 -> {w:?}"); 22 23 let r: NumRight = serde_json::from_str("42").unwrap(); 24 println!("right order, input 42 -> {r:?}"); 25 26 let r2: NumRight = serde_json::from_str("3.5").unwrap(); 27 println!("right order, input 3.5 -> {r2:?}"); 28 } ``` Real output: ```text 1 wrong order, input 42 -> Float(42.0) 2 right order, input 42 -> Int(42) 3 right order, input 3.5 -> Float(3.5) ``` > **Warning:** Untagged enums also produce vaguer error messages (“data did not match any variant…”) because Serde can only report that *nothing* matched, not *why* each variant failed. Prefer an internally or adjacently tagged enum whenever the JSON has (or can carry) a discriminator field. Reserve `untagged` for genuinely tagless inputs like “an ID is either a number or a string”. ### Pitfall 4: Reaching for `serde_json::Value` too early [Section titled “Pitfall 4: Reaching for serde\_json::Value too early”](#pitfall-4-reaching-for-serde_jsonvalue-too-early) Coming from JavaScript, it’s tempting to deserialize into `serde_json::Value` (a dynamic JSON tree) and index it like a JS object. That throws away the type checking that is the whole point — and is slower. Use a typed struct whenever the shape is known. `Value` is for genuinely dynamic JSON; that’s the topic of [Dynamic JSON with `serde_json::Value`](/15-serialization/04-json-manipulation/). *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Model the known shape as a `struct`/`enum`; reach for `HashMap`/`Value` only for genuinely dynamic data.** Typed deserialization is your validation layer; lean on it. * **Always derive `Debug`** alongside `Serialize`/`Deserialize`. It costs nothing and makes `{:?}` printing and test assertions painless. * **Use `Option<T>` for fields that may be absent**, and combine it with `#[serde(skip_serializing_if = "Option::is_none")]` when you want absent-means-omitted on the way out. Use `#[serde(default)]` for fields that should fall back to a sensible value. * **Prefer internally tagged enums (`#[serde(tag = "...")]`)** for API payloads: they read naturally as JSON and give precise error messages. Save `untagged` for tagless inputs, and order its variants strictest-first. * **Match JSON’s `camelCase` with `#[serde(rename_all = "camelCase")]`** at the struct level instead of renaming each field; keep your Rust fields idiomatic `snake_case`. (Details in [Serde Attributes](/15-serialization/05-attributes/).) * **Use `BTreeMap` instead of `HashMap`** when you need deterministic, sorted key ordering in the output (e.g. for stable snapshots or signatures). * **Propagate errors with `?`** instead of `.unwrap()` outside of examples and tests. `serde_json::Error` implements `std::error::Error`, so it composes with `Box<dyn Error>`, `anyhow`, and `thiserror` (see [Section 08: Error Handling](/08-error-handling/)). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A paginated API response: a wrapper with pagination metadata, a `Vec` of nested `Order` objects, a `HashMap` of feature flags, an `Option` field that only appears once an order ships, and an internally tagged status enum: exactly the kind of payload a Rust service receives from another service or returns to a client. ```rust 1 use serde::{Deserialize, Serialize}; 2 use std::collections::HashMap; 3 4 #[derive(Debug, Serialize, Deserialize)] 5 struct ApiResponse { 6 page: u32, 7 per_page: u32, 8 total: u64, 9 items: Vec<Order>, 10 // Server-supplied feature flags keyed by name. 11 flags: HashMap<String, bool>, 12 } 13 14 #[derive(Debug, Serialize, Deserialize)] 15 struct Order { 16 id: u64, 17 customer: Customer, 18 lines: Vec<LineItem>, 19 status: OrderStatus, 20 // Present only once the order ships. 21 tracking_number: Option<String>, 22 } 23 24 #[derive(Debug, Serialize, Deserialize)] 25 struct Customer { 26 name: String, 27 email: String, 28 } 29 30 #[derive(Debug, Serialize, Deserialize)] 31 struct LineItem { 32 sku: String, 33 quantity: u32, 34 unit_price_cents: u64, 35 } 36 37 // An internally tagged enum models a discriminated union, just like a 38 // TypeScript `{ status: "shipped"; carrier: string } | ...`. 39 #[derive(Debug, Serialize, Deserialize)] 40 #[serde(tag = "status", rename_all = "snake_case")] 41 enum OrderStatus { 42 Pending, 43 Shipped { carrier: String }, 44 Cancelled { reason: String }, 45 } 46 47 fn handle_payload(raw: &str) -> Result<ApiResponse, serde_json::Error> { 48 let response: ApiResponse = serde_json::from_str(raw)?; 49 Ok(response) 50 } 51 52 fn main() { 53 let raw = r#" 54 { 55 "page": 1, 56 "per_page": 20, 57 "total": 137, 58 "flags": { "new_checkout": true, "promo_banner": false }, 59 "items": [ 60 { 61 "id": 1001, 62 "customer": { "name": "Ada", "email": "ada@example.com" }, 63 "lines": [ 64 { "sku": "BOOK-1", "quantity": 2, "unit_price_cents": 1599 } 65 ], 66 "status": { "status": "shipped", "carrier": "DHL" }, 67 "tracking_number": "1Z999" 68 }, 69 { 70 "id": 1002, 71 "customer": { "name": "Linus", "email": "linus@example.com" }, 72 "lines": [ 73 { "sku": "MUG-7", "quantity": 1, "unit_price_cents": 899 } 74 ], 75 "status": { "status": "pending" } 76 } 77 ] 78 }"#; 79 80 let response = handle_payload(raw).expect("valid payload"); 81 82 println!("page {} of {} total orders", response.page, response.total); 83 println!("new_checkout flag = {}", response.flags["new_checkout"]); 84 85 for order in &response.items { 86 let total_cents: u64 = order 87 .lines 88 .iter() 89 .map(|l| l.quantity as u64 * l.unit_price_cents) 90 .sum(); 91 let summary = match &order.status { 92 OrderStatus::Pending => "pending".to_string(), 93 OrderStatus::Shipped { carrier } => { 94 let tracking = order.tracking_number.as_deref().unwrap_or("n/a"); 95 format!("shipped via {carrier} (tracking {tracking})") 96 } 97 OrderStatus::Cancelled { reason } => format!("cancelled: {reason}"), 98 }; 99 println!( 100 "order {} for {} -> {} | total ${:.2}", 101 order.id, 102 order.customer.name, 103 summary, 104 total_cents as f64 / 100.0 105 ); 106 } 107 108 // Re-serialize one order to forward to another service. 109 let echo = serde_json::to_string(&response.items[0]).unwrap(); 110 println!("echo: {echo}"); 111 } ``` Real output: ```text 1 page 1 of 137 total orders 2 new_checkout flag = true 3 order 1001 for Ada -> shipped via DHL (tracking 1Z999) | total $31.98 4 order 1002 for Linus -> pending | total $8.99 5 echo: {"id":1001,"customer":{"name":"Ada","email":"ada@example.com"},"lines":[{"sku":"BOOK-1","quantity":2,"unit_price_cents":1599}],"status":{"status":"shipped","carrier":"DHL"},"tracking_number":"1Z999"} ``` Notice what the type system bought you: the `match` on `order.status` is **exhaustive** — add a `Refunded` variant later and the compiler forces you to handle it everywhere. Prices are kept in integer cents (`u64`), sidestepping the float-rounding bugs you’d risk in JavaScript, and only formatted as a float for display. And `handle_payload` returns a `Result`, so a malformed payload is a caught error, not a thrown exception that escapes the function. When this struct backs an HTTP handler, the same derives plug straight into a web framework. See [Section 16: Web APIs](/16-web-apis/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [Serde — Overview](https://serde.rs/): the official guide to the data-model and derive macros. * [Serde — Enum representations](https://serde.rs/enum-representations.html): externally/internally/adjacently tagged and untagged, with examples. * [`serde_json` API docs](https://docs.rs/serde_json): `to_string`, `to_vec`, `from_str`, `from_slice`, and the `Value` type. * [Serde — Examples](https://serde.rs/examples.html): struct, enum, and collection recipes. Related sections in this guide: * [Serde](/15-serialization/00-serde-intro/) — the `Serialize`/`Deserialize` traits and the data-model-vs-format architecture. * [Serde Basics](/15-serialization/01-serde-basics/) — adding `serde` + `serde_json` and your first `to_string`/`from_str`. * [Deriving `Serialize` and `Deserialize`](/15-serialization/02-derive-serialize/) — what `#[derive(Serialize, Deserialize)]` generates. * [Serde Attributes](/15-serialization/05-attributes/) — `rename`, `rename_all`, `skip_serializing_if`, `default`, `flatten`, `tag`, `deny_unknown_fields`, and more. * [Dynamic JSON with `serde_json::Value`](/15-serialization/04-json-manipulation/) — dynamic JSON with `serde_json::Value` and the `json!` macro. * [Beyond JSON](/15-serialization/06-other-formats/) — the same structs serialized as TOML, YAML, MessagePack, and CSV. * [Custom Serialization](/15-serialization/07-custom-serialization/) — hand-written `Serialize`/`Deserialize` and `with`/`serialize_with`. * [Serde Performance](/15-serialization/08-performance/) — borrowing with `&str`/`#[serde(borrow)]` and zero-copy deserialization. * Foundations: [Section 02: Basic Types](/02-basics/01-types/) for the numeric types JSON maps onto, and [Section 08: Error Handling](/08-error-handling/) for handling `serde_json::Error` with `?`. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Round-trip a blog post [Section titled “Exercise 1: Round-trip a blog post”](#exercise-1-round-trip-a-blog-post) **Difficulty:** Easy **Objective:** Define a struct that mixes a string, an array, and a boolean, then serialize and deserialize it. **Instructions:** Create a `BlogPost` struct with `title: String`, `tags: Vec<String>`, and `published: bool`. Build one, serialize it to a JSON string with `serde_json::to_string`, print it, then deserialize it back and print the recovered title. Remember the `derive` feature and the `Serialize`/`Deserialize` derives. ```rust 1 use serde::{Deserialize, Serialize}; 2 3 // TODO: derive Serialize + Deserialize (and Debug) 4 struct BlogPost { 5 title: String, 6 tags: Vec<String>, 7 published: bool, 8 } 9 10 fn main() { 11 let post = BlogPost { 12 title: "Hello".into(), 13 tags: vec!["rust".into(), "serde".into()], 14 published: true, 15 }; 16 // TODO: serialize, print, deserialize, print the title 17 } ``` Solution ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 struct BlogPost { 5 title: String, 6 tags: Vec<String>, 7 published: bool, 8 } 9 10 fn main() { 11 let post = BlogPost { 12 title: "Hello".into(), 13 tags: vec!["rust".into(), "serde".into()], 14 published: true, 15 }; 16 17 let s = serde_json::to_string(&post).unwrap(); 18 println!("serialized: {s}"); 19 20 let back: BlogPost = serde_json::from_str(&s).unwrap(); 21 println!("recovered title: {}", back.title); 22 } ``` Output: ```text 1 serialized: {"title":"Hello","tags":["rust","serde"],"published":true} 2 recovered title: Hello ``` ### Exercise 2: Nested structs, a map, and an optional field [Section titled “Exercise 2: Nested structs, a map, and an optional field”](#exercise-2-nested-structs-a-map-and-an-optional-field) **Difficulty:** Medium **Objective:** Combine nesting, `Vec<Struct>`, `HashMap`, and `Option` in one type. **Instructions:** Model a `Team` with `name: String`, `members: Vec<Member>`, and `scores: HashMap<String, u32>`. A `Member` has `handle: String` and an optional `captain: Option<bool>`. Construct a team where one member has `captain: Some(true)` and another has `None`, then serialize it. Confirm in the output that the `None` captain becomes `null` while the map and the nested array serialize correctly. Solution ```rust 1 use serde::{Deserialize, Serialize}; 2 use std::collections::HashMap; 3 4 #[derive(Debug, Serialize, Deserialize)] 5 struct Team { 6 name: String, 7 members: Vec<Member>, 8 scores: HashMap<String, u32>, 9 } 10 11 #[derive(Debug, Serialize, Deserialize)] 12 struct Member { 13 handle: String, 14 captain: Option<bool>, 15 } 16 17 fn main() { 18 let mut scores = HashMap::new(); 19 scores.insert("round1".to_string(), 42u32); 20 21 let team = Team { 22 name: "Crustaceans".into(), 23 members: vec![ 24 Member { handle: "ferris".into(), captain: Some(true) }, 25 Member { handle: "gopher".into(), captain: None }, 26 ], 27 scores, 28 }; 29 30 println!("{}", serde_json::to_string(&team).unwrap()); 31 } ``` Output: ```text 1 {"name":"Crustaceans","members":[{"handle":"ferris","captain":true},{"handle":"gopher","captain":null}],"scores":{"round1":42}} ``` The `None` captain rendered as `null`. To omit it instead, you’d add `#[serde(skip_serializing_if = "Option::is_none")]`. See [Serde Attributes](/15-serialization/05-attributes/). ### Exercise 3: A tagged command protocol [Section titled “Exercise 3: A tagged command protocol”](#exercise-3-a-tagged-command-protocol) **Difficulty:** Hard **Objective:** Use an internally tagged enum to parse a JSON command stream and re-serialize it. **Instructions:** Define a `Command` enum with variants `Move { x: i32, y: i32 }`, `Say { text: String }`, and `Quit`. Use `#[serde(tag = "op", rename_all = "lowercase")]` so the discriminator is the `op` field and variant names appear lowercased. Deserialize the array `[{"op":"move","x":1,"y":2},{"op":"say","text":"hi"},{"op":"quit"}]` into a `Vec<Command>`, print it with `{:?}`, then serialize it back and confirm the JSON matches. Solution ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 #[serde(tag = "op", rename_all = "lowercase")] 5 enum Command { 6 Move { x: i32, y: i32 }, 7 Say { text: String }, 8 Quit, 9 } 10 11 fn main() { 12 let input = r#"[{"op":"move","x":1,"y":2},{"op":"say","text":"hi"},{"op":"quit"}]"#; 13 14 let cmds: Vec<Command> = serde_json::from_str(input).unwrap(); 15 println!("parsed: {cmds:?}"); 16 17 let json = serde_json::to_string(&cmds).unwrap(); 18 println!("reserialized: {json}"); 19 } ``` Output: ```text 1 parsed: [Move { x: 1, y: 2 }, Say { text: "hi" }, Quit] 2 reserialized: [{"op":"move","x":1,"y":2},{"op":"say","text":"hi"},{"op":"quit"}] ``` The round-trip is lossless: `rename_all = "lowercase"` controls the variant names, and `tag = "op"` places the discriminator inline. Internal tagging like this is the idiomatic way to model a JSON discriminated union in Rust. # Dynamic JSON with `serde_json::Value` > serde_json::Value is Rust's answer to JS's any JSON blob: a typed enum you build with json!, index dynamically, and convert to and from typed structs. In TypeScript, `JSON.parse` hands you an `any`-typed blob you can poke at freely: `data.users[0].name`. Rust’s equivalent is `serde_json::Value`, a tree-shaped enum you build with the `json!` macro, navigate with indexing, and convert to and from typed structs when you’re ready to lock things down. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) `serde_json::Value` is Rust’s representation of “arbitrary JSON whose shape I don’t know (or don’t care about) at compile time.” It is an enum with one variant per JSON type (null, bool, number, string, array, object) and it gives you the dynamic, `data["key"][0]` style of access that TypeScript developers reach for by default. This matters because not all JSON is worth a dedicated struct: webhook payloads, partial config overrides, and pass-through proxies are often easier to handle as a `Value` than as a fully typed model. > **Tip:** Reach for typed structs (`#[derive(Deserialize)]`) when you know and rely on the shape; reach for `Value` when the shape is genuinely unknown, partial, or irrelevant. This page is about the second case. The first case is covered in [Structs and JSON](/15-serialization/03-json/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In JavaScript, `JSON.parse` returns an untyped value, and you navigate it directly. This is ergonomic but unsafe: a typo or a missing field surfaces only at runtime, often as `undefined` propagating somewhere far away. ```typescript 1 // A webhook payload whose exact shape we don't model. 2 const raw = `{ 3 "event": "order.created", 4 "data": { 5 "id": 42, 6 "customer": { "name": "Ada Lovelace" }, 7 "items": [ 8 { "sku": "A1", "qty": 2 }, 9 { "sku": "B2", "qty": 1 } 10 ] 11 } 12 }`; 13 14 const payload = JSON.parse(raw); // type is `any` 15 16 // Dynamic navigation — no compile-time checks 17 console.log(payload.event); // "order.created" 18 console.log(payload.data.customer.name); // "Ada Lovelace" 19 console.log(payload.data.items[0].sku); // "A1" 20 21 // Missing keys are `undefined`, not errors 22 console.log(payload.data.shipping); // undefined 23 24 // Building JSON dynamically is just object literals 25 const response = { 26 ok: true, 27 receivedAt: Date.now(), 28 echo: payload.event, 29 }; 30 console.log(JSON.stringify(response)); ``` > **Warning:** JavaScript’s `number` is always an IEEE-754 double. `JSON.parse('{"id": 9007199254740993}')` silently rounds the id to `9007199254740992`. The integer is *quietly corrupted* during parsing. It does not throw and it does not wrap; it loses precision. Keep this in mind as we compare with Rust below. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) `serde_json::Value` gives you the same dynamic feel, but it is a real, typed enum value, and it preserves large integers exactly. First, the dependencies. The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically. Add `serde_json` (and `serde` if you also want typed conversion): ```bash 1 cargo add serde_json 2 cargo add serde --features derive ``` ```rust 1 use serde_json::{json, Value}; 2 3 fn main() { 4 let raw = r#"{ 5 "event": "order.created", 6 "data": { 7 "id": 42, 8 "customer": { "name": "Ada Lovelace" }, 9 "items": [ 10 { "sku": "A1", "qty": 2 }, 11 { "sku": "B2", "qty": 1 } 12 ] 13 } 14 }"#; 15 16 // Parse into a dynamic Value tree. 17 let payload: Value = serde_json::from_str(raw).expect("valid JSON"); 18 19 // Dynamic navigation via indexing. 20 println!("{}", payload["event"]); // "order.created" 21 println!("{}", payload["data"]["customer"]["name"]); // "Ada Lovelace" 22 println!("{}", payload["data"]["items"][0]["sku"]); // "A1" 23 24 // Missing keys are Value::Null, never a panic. 25 println!("{}", payload["data"]["shipping"]); // null 26 27 // Building JSON dynamically with the json! macro. 28 let response = json!({ 29 "ok": true, 30 "received_at": 1_717_000_000, 31 "echo": payload["event"], 32 }); 33 println!("{}", response); 34 } ``` Running this prints (note the quotes around string values — explained below): ```text 1 "order.created" 2 "Ada Lovelace" 3 "A1" 4 null 5 {"echo":"order.created","ok":true,"received_at":1717000000} ``` *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What `Value` actually is [Section titled “What Value actually is”](#what-value-actually-is) `serde_json::Value` is a plain Rust enum. Knowing its definition demystifies everything else: ```rust 1 // (from the serde_json crate — shown for understanding, you don't write this) 2 pub enum Value { 3 Null, 4 Bool(bool), 5 Number(Number), // holds u64, i64, or f64 internally 6 String(String), 7 Array(Vec<Value>), 8 Object(Map<String, Value>), // sorted (BTreeMap) by default; insertion-ordered with the preserve_order feature 9 } ``` This is the same idea as TypeScript’s structural `JSONValue` union: ```typescript 1 type JSONValue = 2 | null 3 | boolean 4 | number 5 | string 6 | JSONValue[] 7 | { [key: string]: JSONValue }; ``` The difference: TypeScript’s version is erased at runtime, so the compiler can’t actually stop you from doing `payload.data.nope.boom`. Rust’s `Value` is a concrete value you pattern-match on, so navigation is checked operations on a real data structure, not blind property access. ### Why printed strings have quotes [Section titled “Why printed strings have quotes”](#why-printed-strings-have-quotes) When you write `println!("{}", payload["event"])`, you are printing a `Value` through its `Display` implementation, and a `Value::String` displays itself as valid JSON, *including the surrounding quotes*. That is why the output was `"order.created"` and not `order.created`. To get the bare Rust `&str`, extract it: ```rust 1 use serde_json::json; 2 3 fn main() { 4 let payload = json!({ "event": "order.created" }); 5 6 println!("{}", payload["event"]); // "order.created" (JSON form) 7 8 let event: &str = payload["event"].as_str().unwrap(); 9 println!("{event}"); // order.created (bare string) 10 } ``` This is a frequent surprise. `Display` on a `Value` always yields JSON text; the `as_*` accessors give you native Rust types. ### Indexing with `[]` [Section titled “Indexing with \[\]”](#indexing-with-) `Value` implements `Index` for both `&str` (object keys) and `usize` (array positions), which is what enables the `payload["data"]["items"][0]` chain. Two properties make this pleasant *and* dangerous: * **Reading a missing key or out-of-range index returns `Value::Null`** instead of panicking. So `payload["nope"]["deeper"]` is `Null`, not a crash, exactly like JavaScript returning `undefined`, except Rust gives you a real `Null` value you can match on. * **Mutably indexing the wrong *type* panics.** `value["key"] = ...` on a `Value` that is a string or number panics, because there is nowhere to put the key. (See [Common Pitfalls](#common-pitfalls).) ### Extracting typed data: the `as_*` accessors [Section titled “Extracting typed data: the as\_\* accessors”](#extracting-typed-data-the-as_-accessors) To pull a Rust value out of a `Value`, use the `as_*` family. Each returns an `Option` because the variant might not match; there is **no coercion**: ```rust 1 use serde_json::json; 2 3 fn main() { 4 let v = json!({ "id": 42, "name": "Ada", "active": true }); 5 6 let id: Option<i64> = v["id"].as_i64(); // Some(42) 7 let name: Option<&str> = v["name"].as_str(); // Some("Ada") 8 let active: Option<bool> = v["active"].as_bool(); // Some(true) 9 10 // No coercion: a number is NOT a string. 11 let id_as_str: Option<&str> = v["id"].as_str(); // None 12 13 println!("{id:?} {name:?} {active:?} {id_as_str:?}"); 14 // Some(42) Some("Ada") Some(true) None 15 } ``` Unlike JavaScript, where `String(payload.id)` or `payload.id + ""` happily coerces, `as_str()` on a number returns `None`. This is the `??`/`?.` mental model from TypeScript made explicit: every access that might fail hands you an `Option` you must deal with. The common accessors: | Accessor | Returns | Matches `Value` variant | | ------------- | ----------------------------- | ----------------------- | | `as_str()` | `Option<&str>` | `String` | | `as_i64()` | `Option<i64>` | `Number` (integer) | | `as_u64()` | `Option<u64>` | `Number` (non-negative) | | `as_f64()` | `Option<f64>` | `Number` (any) | | `as_bool()` | `Option<bool>` | `Bool` | | `as_array()` | `Option<&Vec<Value>>` | `Array` | | `as_object()` | `Option<&Map<String, Value>>` | `Object` | | `as_null()` | `Option<()>` | `Null` | ### `get` vs `[]` [Section titled “get vs \[\]”](#get-vs-) `[]` is concise but yields `Null` for misses. `.get("key")` / `.get(index)` returns `Option<&Value>`, which composes with `?` for clean early-returns: ```rust 1 use serde_json::{json, Value}; 2 3 fn city_of(doc: &Value) -> Option<&str> { 4 // Each ? bails out to None on the first missing/wrong-typed step. 5 doc.get("address")?.get("city")?.as_str() 6 } 7 8 fn main() { 9 let a = json!({ "address": { "city": "Berlin" } }); 10 let b = json!({ "address": {} }); 11 println!("{:?}", city_of(&a)); // Some("Berlin") 12 println!("{:?}", city_of(&b)); // None 13 } ``` Use `[]` for quick reads where `Null` is an acceptable “miss”, and `get(...)?` when you want to distinguish “absent” cleanly and short-circuit. ### The `json!` macro [Section titled “The json! macro”](#the-json-macro) `json!` lets you write JSON-shaped literals directly in Rust, and, importantly, interpolate Rust variables and expressions: ```rust 1 use serde_json::json; 2 3 fn main() { 4 let name = "Ada"; 5 let scores = vec![90, 85, 100]; 6 7 let doc = json!({ 8 "name": name, // a &str variable 9 "scores": scores, // a Vec<i32> -> JSON array 10 "total": scores.iter().sum::<i32>(),// any expression 11 "meta": { "active": true, "tags": ["a", "b"] }, 12 }); 13 14 println!("{doc}"); // {"meta":{"active":true,"tags":["a","b"]},"name":"Ada","scores":[90,85,100],"total":275} 15 } ``` Any type that implements `Serialize` can be interpolated into `json!`, so `Vec`, `HashMap`, and your own derived structs all drop straight in. This is far closer to a JS object literal than the manual `Map::insert` approach, though that exists too when you need to build objects programmatically. ### Numbers stay exact [Section titled “Numbers stay exact”](#numbers-stay-exact) This is where Rust beats JavaScript outright. `serde_json` stores integers as `i64`/`u64` internally, so a 53-bit-plus integer survives a parse round trip unharmed: ```rust 1 use serde_json::{json, Value}; 2 3 fn main() { 4 let big = json!({ "n": 9_007_199_254_740_993_i64 }); 5 println!("{}", big["n"]); // 9007199254740993 (exact) 6 println!("{:?}", big["n"].as_i64()); // Some(9007199254740993) 7 } ``` The same value parsed by Node’s `JSON.parse` becomes `9007199254740992`, silently off by one. If you proxy or transform JSON that carries large integer IDs (Twitter/X snowflake IDs, database bigints), `serde_json::Value` preserves them; JavaScript does not. ### Mutation [Section titled “Mutation”](#mutation) A `Value` is just data, so a `mut` binding lets you edit the tree in place: ```rust 1 use serde_json::{json, Value}; 2 3 fn main() { 4 let mut config = json!({ "debug": false, "level": 1 }); 5 6 // Overwrite an existing key. 7 config["debug"] = json!(true); 8 9 // Read-modify-write. 10 let next = config["level"].as_i64().unwrap() + 1; 11 config["level"] = json!(next); 12 13 // Insert a brand-new key via the underlying Map. 14 if let Some(obj) = config.as_object_mut() { 15 obj.insert("name".to_string(), json!("server")); 16 } 17 18 println!("{config}"); // {"debug":true,"level":2,"name":"server"} 19 } ``` `as_object_mut()` (and `as_array_mut()`) hand you `&mut` access to the underlying `Map`/`Vec` for inserts, removals, and entry-API tricks. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript (`JSON.parse`) | Rust (`serde_json::Value`) | | ----------------- | --------------------------------------- | --------------------------------------------------------- | | Result type | `any` (effectively untyped) | A concrete `Value` enum | | Missing key | `undefined` (and `.deeper` then throws) | `Value::Null` (chaining stays `Null`) | | Type coercion | Implicit (`+ ""`, `String(x)`) | None; `as_str()` on a number is `None` | | Large integers | Lossy (IEEE-754 f64) | Exact (`i64`/`u64`) | | Building literals | Object literal `{ a: 1 }` | `json!({ "a": 1 })` macro | | Object key order | Insertion order | Insertion order (with `preserve_order` feature) or sorted | | Failure mode | Runtime `undefined`/`TypeError` | Compile-time `Option` you must handle | ### Object key ordering [Section titled “Object key ordering”](#object-key-ordering) By default, `serde_json`’s `Map` is backed by a `BTreeMap`, so object keys serialize in **sorted** order (that is why our examples printed `debug`, `level`, `name` alphabetically). If you need to preserve **insertion order** like a JavaScript object, enable the feature: ```bash 1 cargo add serde_json --features preserve_order ``` This swaps the backing store to `indexmap`, matching JavaScript’s order-preserving semantics. It’s worth turning on for round-tripping config files where humans care about key order. ### `Value` is owned data, not a view [Section titled “Value is owned data, not a view”](#value-is-owned-data-not-a-view) A `Value` owns its strings and nested values. There is no concept of “live” navigation against the original text buffer (that is what zero-copy deserialization with `&str` is for; see [Serde Performance](/15-serialization/08-performance/)). When you clone a sub-tree out of a `Value`, you get an independent copy. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting that `Display` adds quotes [Section titled “Pitfall 1: Forgetting that Display adds quotes”](#pitfall-1-forgetting-that-display-adds-quotes) ```rust 1 use serde_json::json; 2 3 fn main() { 4 let v = json!({ "name": "Ada" }); 5 let greeting = format!("Hello, {}!", v["name"]); 6 println!("{greeting}"); // Hello, "Ada"! <- note the stray quotes 7 } ``` The quotes are not a bug: `v["name"]` is printed as JSON. Extract the bare string with `.as_str()`: ```rust 1 use serde_json::json; 2 3 fn main() { 4 let v = json!({ "name": "Ada" }); 5 let greeting = format!("Hello, {}!", v["name"].as_str().unwrap_or("guest")); 6 println!("{greeting}"); // Hello, Ada! 7 } ``` ### Pitfall 2: Mutably indexing the wrong type panics [Section titled “Pitfall 2: Mutably indexing the wrong type panics”](#pitfall-2-mutably-indexing-the-wrong-type-panics) Reading a missing key is safe (`Null`), but *writing* a key into something that isn’t an object cannot work, so it panics: ```rust 1 use serde_json::{json, Value}; 2 3 fn main() { 4 let mut v: Value = json!("just a string"); 5 v["key"] = json!(1); // panics at runtime 6 println!("{v}"); 7 } ``` The real runtime panic: ```text 1 thread 'main' panicked at .../serde_json-1.0.150/src/value/index.rs:102:18: 2 cannot access key "key" in JSON string ``` Guard the type first (`if let Some(obj) = v.as_object_mut()`) or ensure `v` is an object before assigning into it. ### Pitfall 3: Assuming `as_i64()` coerces [Section titled “Pitfall 3: Assuming as\_i64() coerces”](#pitfall-3-assuming-as_i64-coerces) ```rust 1 use serde_json::json; 2 3 fn main() { 4 // The JSON number was written as a float... 5 let v = json!({ "qty": 2.0 }); 6 println!("{:?}", v["qty"].as_i64()); // None! 2.0 is not an integer to serde_json 7 println!("{:?}", v["qty"].as_f64()); // Some(2.0) 8 } ``` `as_i64()` only succeeds for values serde\_json classifies as integers. If the source might write `2.0`, read with `as_f64()` (then convert), or accept that `as_i64()` returns `None`. There is no silent float-to-int rounding. ### Pitfall 4: Comparing a `Value` and expecting deep numeric equality [Section titled “Pitfall 4: Comparing a Value and expecting deep numeric equality”](#pitfall-4-comparing-a-value-and-expecting-deep-numeric-equality) `serde_json` implements `PartialEq` between `Value` and many Rust primitives, which is convenient, but integer and float JSON numbers are **distinct**: ```rust 1 use serde_json::json; 2 3 fn main() { 4 let v = json!({ "event": "click", "x": 10 }); 5 6 // Comparing Value to a primitive works (no .as_* needed): 7 println!("{}", v["event"] == "click"); // true 8 println!("{}", v["x"] == 10); // true (i32) 9 println!("{}", v["x"] == 10.0); // true (f64 compares equal here) 10 11 // But two Values of different numeric kinds are NOT equal: 12 println!("{}", json!(10) == json!(10.0)); // false — int vs float 13 } ``` If you need numeric equality regardless of integer/float representation, compare via `as_f64()` rather than comparing `Value`s directly. ### Pitfall 5: Treating a parse error like JavaScript’s silent `undefined` [Section titled “Pitfall 5: Treating a parse error like JavaScript’s silent undefined”](#pitfall-5-treating-a-parse-error-like-javascripts-silent-undefined) `serde_json::from_str::<Value>` returns a `Result`, and malformed JSON is a real error you must handle; there is no `undefined`: ```rust 1 use serde_json::Value; 2 3 fn main() { 4 let bad = r#"{ "name": "Ada", }"#; // trailing comma is invalid JSON 5 match serde_json::from_str::<Value>(bad) { 6 Ok(v) => println!("ok: {v}"), 7 Err(e) => println!("error: {e}"), 8 } 9 } ``` Real output (serde\_json reports line and column): ```text 1 error: trailing comma at line 1 column 18 ``` > **Note:** Unlike `JSON.parse` (which throws), Rust forces you to acknowledge the `Result`. Use `?` to propagate, `match` to branch, or `.unwrap_or_default()` if an empty/`Null` fallback is acceptable. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Prefer typed structs at the boundary, `Value` for the unknown middle [Section titled “Prefer typed structs at the boundary, Value for the unknown middle”](#prefer-typed-structs-at-the-boundary-value-for-the-unknown-middle) `Value` is the right tool for genuinely dynamic JSON. But if you find yourself writing `payload["data"]["id"].as_i64().unwrap()` repeatedly, that field’s shape *is* known — model it. You can even mix the two: derive a struct for the part you understand and keep a `Value` for the free-form remainder. ```rust 1 use serde::Deserialize; 2 use serde_json::Value; 3 4 #[derive(Debug, Deserialize)] 5 struct Webhook { 6 event: String, 7 // Keep the unmodeled payload as dynamic JSON. 8 data: Value, 9 } 10 11 fn main() { 12 let raw = r#"{ "event": "ping", "data": { "anything": [1, 2, 3] } }"#; 13 let hook: Webhook = serde_json::from_str(raw).unwrap(); 14 println!("event = {}", hook.event); 15 println!("first = {}", hook.data["anything"][0]); // dynamic from here 16 } ``` ### Convert between `Value` and typed with `from_value` / `to_value` [Section titled “Convert between Value and typed with from\_value / to\_value”](#convert-between-value-and-typed-with-from_value--to_value) When you do know the shape, `serde_json::from_value` turns a `Value` into a struct, and `to_value` goes the other way; no string round trip needed: ```rust 1 use serde::{Deserialize, Serialize}; 2 use serde_json::{json, Value}; 3 4 #[derive(Debug, Serialize, Deserialize)] 5 struct User { 6 id: u64, 7 name: String, 8 } 9 10 fn main() { 11 let v = json!({ "id": 7, "name": "Grace" }); 12 13 let user: User = serde_json::from_value(v).unwrap(); // Value -> struct 14 println!("{user:?}"); // User { id: 7, name: "Grace" } 15 16 let back: Value = serde_json::to_value(&user).unwrap(); // struct -> Value 17 println!("{back}"); // {"id":7,"name":"Grace"} 18 } ``` ### Use `pointer()` for deep, configurable paths [Section titled “Use pointer() for deep, configurable paths”](#use-pointer-for-deep-configurable-paths) When the path to a value is itself data (e.g. comes from config), JSON Pointer syntax (RFC 6901) beats hand-written indexing: ```rust 1 use serde_json::{json, Value}; 2 3 fn main() { 4 let doc = json!({ 5 "data": { "items": [ { "sku": "A1" }, { "sku": "B2" } ] } 6 }); 7 8 let sku = doc.pointer("/data/items/1/sku").and_then(Value::as_str); 9 println!("{sku:?}"); // Some("B2") 10 } ``` ### Don’t pay for `Value` when you don’t need dynamism [Section titled “Don’t pay for Value when you don’t need dynamism”](#dont-pay-for-value-when-you-dont-need-dynamism) Parsing into `Value` allocates a node for every element and box every string into the tree. For hot paths and known shapes, deserializing straight into a struct is faster and lighter. The trade-off (and how to avoid `Value` for performance) is covered in [Serde Performance](/15-serialization/08-performance/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A common production task: layering configuration. You have a base config and a set of overrides (from a file, environment, or CLI), and you want a deep merge where nested objects combine key-by-key but scalars and arrays are replaced. With `Value`, this is a short recursive function: ```rust 1 use serde_json::{json, Map, Value}; 2 3 /// Recursively merge `patch` into `base`. 4 /// Two objects merge key-by-key; anything else overwrites. 5 fn merge(base: &mut Value, patch: &Value) { 6 match (base, patch) { 7 (Value::Object(base_map), Value::Object(patch_map)) => { 8 for (key, patch_val) in patch_map { 9 // `entry` inserts Null if the key is new, then we recurse into it. 10 merge(base_map.entry(key.clone()).or_insert(Value::Null), patch_val); 11 } 12 } 13 // Non-object on either side: the patch wins. 14 (base_slot, patch_val) => { 15 *base_slot = patch_val.clone(); 16 } 17 } 18 } 19 20 fn main() { 21 let mut config = json!({ 22 "server": { "host": "localhost", "port": 8080 }, 23 "logging": { "level": "info" }, 24 "features": ["a", "b"] 25 }); 26 27 let overrides = json!({ 28 "server": { "port": 9090 }, 29 "logging": { "level": "debug", "json": true }, 30 "features": ["a", "b", "c"] 31 }); 32 33 merge(&mut config, &overrides); 34 35 // Pull a final, typed value out once merging is done. 36 let port = config["server"]["port"].as_u64().unwrap_or(8080); 37 println!("effective port: {port}"); 38 39 println!("{}", serde_json::to_string_pretty(&config).unwrap()); 40 41 // You can also assemble objects from scratch with Map when json! is awkward. 42 let mut summary = Map::new(); 43 summary.insert("merged".into(), Value::Bool(true)); 44 summary.insert("port".into(), json!(port)); 45 println!("{}", Value::Object(summary)); 46 } ``` Output: ```text 1 effective port: 9090 2 { 3 "features": [ 4 "a", 5 "b", 6 "c" 7 ], 8 "logging": { 9 "json": true, 10 "level": "debug" 11 }, 12 "server": { 13 "host": "localhost", 14 "port": 9090 15 } 16 } 17 {"merged":true,"port":9090} ``` Notice the host (`localhost`) survived from the base because `overrides` only touched `port`, while `features` was wholesale replaced because arrays aren’t merged. This is exactly the kind of shape-agnostic transformation where `Value` shines and a fixed struct would get in the way. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [`serde_json::Value` API docs](https://docs.rs/serde_json/latest/serde_json/enum.Value.html) — every variant and `as_*` accessor * [`json!` macro](https://docs.rs/serde_json/latest/serde_json/macro.json.html) — building values inline * [`serde_json::Map`](https://docs.rs/serde_json/latest/serde_json/struct.Map.html) — the object type, including the `preserve_order` feature * [`Value::pointer`](https://docs.rs/serde_json/latest/serde_json/enum.Value.html#method.pointer) — JSON Pointer (RFC 6901) access * [serde\_json README — “Operating on untyped JSON values”](https://github.com/serde-rs/json#operating-on-untyped-json-values) ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Serde: The Big Picture](/15-serialization/00-serde-intro/) — how `JSON.parse`/`stringify` map onto Serde’s data model * [Serde Basics](/15-serialization/01-serde-basics/) — project setup, `to_string`/`from_str` * [Deriving Serialize and Deserialize](/15-serialization/02-derive-serialize/) — what `#[derive(Serialize, Deserialize)]` generates * [Structs and JSON](/15-serialization/03-json/) — the typed counterpart to this page (when you *do* know the shape) * [Serde Attributes](/15-serialization/05-attributes/) — `rename`, `flatten`, `default`, and friends for typed models * [Other Formats](/15-serialization/06-other-formats/) — TOML, YAML, MessagePack: the same dynamic value idea in other encodings * [Custom Serialization](/15-serialization/07-custom-serialization/) — hand-written `Serialize`/`Deserialize` * [Serde Performance](/15-serialization/08-performance/) — why to *avoid* `Value` on hot paths, and zero-copy alternatives * [Web APIs and HTTP](/16-web-apis/) — handling dynamic JSON request/response bodies * [Enums and Pattern Matching](/06-data-structures/) — `Value` is an enum; matching on it builds on these fundamentals * [Basic Types](/02-basics/01-types/) — why Rust’s exact `i64`/`u64` beats JavaScript’s lossy `number` *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Safe nested extraction [Section titled “Exercise 1: Safe nested extraction”](#exercise-1-safe-nested-extraction) **Difficulty:** Easy **Objective:** Navigate a dynamic `Value` without panicking. **Instructions:** Write `fn first_tag(doc: &Value) -> Option<&str>` that returns the first element of the `"tags"` array as a string, or `None` if `"tags"` is missing, isn’t an array, is empty, or its first element isn’t a string. Use `get`, `as_array`/indexing, and `as_str` with the `?` operator — do not call `.unwrap()`. ```rust 1 use serde_json::{json, Value}; 2 3 fn first_tag(doc: &Value) -> Option<&str> { 4 // TODO: return the first tag as &str, or None 5 todo!() 6 } 7 8 fn main() { 9 let a = json!({ "tags": ["rust", "json"] }); 10 let b = json!({ "tags": [] }); 11 let c = json!({ "other": 1 }); 12 println!("{:?}", first_tag(&a)); // Some("rust") 13 println!("{:?}", first_tag(&b)); // None 14 println!("{:?}", first_tag(&c)); // None 15 } ``` Solution ```rust 1 use serde_json::{json, Value}; 2 3 fn first_tag(doc: &Value) -> Option<&str> { 4 // `get(0)` on a Value indexes the array; each ? bails to None on failure. 5 doc.get("tags")?.get(0)?.as_str() 6 } 7 8 fn main() { 9 let a = json!({ "tags": ["rust", "json"] }); 10 let b = json!({ "tags": [] }); 11 let c = json!({ "other": 1 }); 12 println!("{:?}", first_tag(&a)); // Some("rust") 13 println!("{:?}", first_tag(&b)); // None 14 println!("{:?}", first_tag(&c)); // None 15 } ``` `Value::get` accepts both `&str` keys and `usize` indices, so the whole path is one `?`-chained expression. Because every step returns `Option<&Value>`, a missing key, an empty array, or a non-string first element all collapse cleanly to `None`. ### Exercise 2: Sum numeric fields across an array [Section titled “Exercise 2: Sum numeric fields across an array”](#exercise-2-sum-numeric-fields-across-an-array) **Difficulty:** Medium **Objective:** Iterate a dynamic JSON array and aggregate, tolerating missing/odd entries. **Instructions:** Write `fn total_amount(orders: &Value) -> f64` that sums the `"amount"` field of every object in an `orders` array. Skip any element that lacks `"amount"` or whose `"amount"` isn’t numeric. Return `0.0` if `orders` isn’t an array. Use `as_array`, an iterator, `filter_map`, and `as_f64`. ```rust 1 use serde_json::{json, Value}; 2 3 fn total_amount(orders: &Value) -> f64 { 4 // TODO 5 todo!() 6 } 7 8 fn main() { 9 let orders = json!([ 10 { "id": 1, "amount": 9.99 }, 11 { "id": 2, "amount": 5.01 }, 12 { "id": 3 }, // no amount -> skipped 13 { "id": 4, "amount": "free" } // non-numeric -> skipped 14 ]); 15 println!("{}", total_amount(&orders)); // 15 16 println!("{}", total_amount(&json!({}))); // 0 17 } ``` Solution ```rust 1 use serde_json::{json, Value}; 2 3 fn total_amount(orders: &Value) -> f64 { 4 orders 5 .as_array() 6 .map(|arr| { 7 arr.iter() 8 // filter_map keeps only entries with a numeric "amount". 9 .filter_map(|o| o.get("amount").and_then(Value::as_f64)) 10 .sum() 11 }) 12 .unwrap_or(0.0) 13 } 14 15 fn main() { 16 let orders = json!([ 17 { "id": 1, "amount": 9.99 }, 18 { "id": 2, "amount": 5.01 }, 19 { "id": 3 }, 20 { "id": 4, "amount": "free" } 21 ]); 22 println!("{}", total_amount(&orders)); // 15 23 println!("{}", total_amount(&json!({}))); // 0 24 } ``` `as_array()` yields `None` for non-arrays, so `unwrap_or(0.0)` covers the “not an array” case. Inside, `filter_map` discards every element where `get("amount")` is absent or `as_f64` returns `None`, so missing and non-numeric amounts are both skipped silently. (`15.0` prints as `15` because `f64`’s `Display` omits a trailing `.0`.) ### Exercise 3: Recursive redaction [Section titled “Exercise 3: Recursive redaction”](#exercise-3-recursive-redaction) **Difficulty:** Hard **Objective:** Mutate a `Value` tree in place, recursing into nested objects and arrays. **Instructions:** Write `fn redact(value: &mut Value, keys: &[&str])` that walks the entire tree and replaces the value of any object key listed in `keys` with the JSON string `"***"`. It must descend into nested objects and into arrays of objects. Keys not in the list keep their value but are still recursed into. Use `as_object_mut` / `as_array_mut` or a `match` over `&mut Value`. ```rust 1 use serde_json::{json, Value}; 2 3 fn redact(value: &mut Value, keys: &[&str]) { 4 // TODO: replace matching keys' values with json!("***"), recursively 5 todo!() 6 } 7 8 fn main() { 9 let mut payload = json!({ 10 "user": "ada", 11 "password": "hunter2", 12 "nested": { "token": "abc", "ok": true }, 13 "list": [ { "token": "xyz" }, { "safe": 1 } ] 14 }); 15 redact(&mut payload, &["password", "token"]); 16 println!("{}", serde_json::to_string(&payload).unwrap()); 17 // {"list":[{"token":"***"},{"safe":1}],"nested":{"ok":true,"token":"***"}, 18 // "password":"***","user":"ada"} 19 } ``` Solution ```rust 1 use serde_json::{json, Value}; 2 3 fn redact(value: &mut Value, keys: &[&str]) { 4 match value { 5 Value::Object(map) => { 6 for (k, v) in map.iter_mut() { 7 if keys.contains(&k.as_str()) { 8 *v = json!("***"); // redact this key's value 9 } else { 10 redact(v, keys); // otherwise keep descending 11 } 12 } 13 } 14 Value::Array(arr) => { 15 for v in arr.iter_mut() { 16 redact(v, keys); 17 } 18 } 19 // Scalars (null/bool/number/string) are leaves: nothing to do. 20 _ => {} 21 } 22 } 23 24 fn main() { 25 let mut payload = json!({ 26 "user": "ada", 27 "password": "hunter2", 28 "nested": { "token": "abc", "ok": true }, 29 "list": [ { "token": "xyz" }, { "safe": 1 } ] 30 }); 31 redact(&mut payload, &["password", "token"]); 32 println!("{}", serde_json::to_string(&payload).unwrap()); 33 } ``` Matching on `&mut Value` gives mutable access to the inner `Map`/`Vec`, and `iter_mut()` lets us either overwrite `*v` for a matched key or recurse into it. Because matched keys are overwritten rather than recursed into, you avoid descending into data you’re about to discard. Real output: ```text 1 {"list":[{"token":"***"},{"safe":1}],"nested":{"ok":true,"token":"***"},"password":"***","user":"ada"} ``` (Keys print sorted because the default `Map` is a `BTreeMap`; enable `serde_json`’s `preserve_order` feature for insertion order.) # Serde Attributes > Serde's #[serde(...)] attributes rename keys, set casing, skip secrets, supply defaults, flatten, and tag enums, replacing TypeScript's ad-hoc toJSON and ?? Serde’s `#[serde(...)]` attributes are how you bend a Rust type to match a real-world JSON contract without hand-writing any (de)serialization code. They are the bridge between idiomatic Rust naming (`snake_case`, `Option`, enums) and the messy keys, casing, and shapes that external APIs actually use. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) When you `#[derive(Serialize, Deserialize)]`, the generated code maps each field one-to-one to a key with the same name. **Serde attributes** let you override that mapping: rename keys, change casing, hide fields, supply defaults, inline nested structs, and control how enums are tagged. If you have ever reached for a custom `toJSON()` method, a `class-transformer` decorator, or a Zod `.transform()` in TypeScript, attributes are Serde’s far more powerful equivalent: applied declaratively, checked at compile time, and shared by both directions (serialize and deserialize). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript there is no single built-in mechanism for this. You typically combine several ad-hoc techniques: a custom `toJSON()`, manual `??` defaults on parse, and hand-written discriminated-union narrowing. ```typescript 1 // TypeScript: matching a camelCase JSON API with hand-written glue. 2 3 interface ApiUser { 4 userId: number; 5 firstName: string; 6 emailAddress: string; // wire name differs from our internal "email" 7 } 8 9 class Account { 10 constructor( 11 public username: string, 12 private passwordHash: string, // must NEVER be serialized 13 public nickname: string | null, 14 ) {} 15 16 // The closest JS analogue to Serde attributes: a custom toJSON(). 17 toJSON() { 18 const out: Record<string, unknown> = { username: this.username }; 19 // skip_serializing_if: omit nickname when absent 20 if (this.nickname != null) out.nickname = this.nickname; 21 // passwordHash is simply never added -> "skip" 22 return out; 23 } 24 } 25 26 // "default" on the way in is manual with ?? : 27 function parseConfig(raw: any) { 28 return { 29 host: raw.host as string, 30 port: (raw.port ?? 8080) as number, // default = 8080 31 tlsEnabled: (raw.tlsEnabled ?? false) as boolean, 32 }; 33 } 34 35 // Discriminated union ("internally tagged" enum) checked by hand: 36 type Shape = 37 | { type: "circle"; radius: number } 38 | { type: "rectangle"; width: number; height: number }; 39 40 console.log(JSON.stringify(new Account("ada", "secret", null))); 41 // {"username":"ada"} 42 console.log(parseConfig({ host: "localhost" })); 43 // { host: 'localhost', port: 8080, tlsEnabled: false } ``` Every concern — renaming, casing, skipping, defaults, tagging — is solved with a *different* mechanism, and none of them are type-checked against the actual JSON. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) In Rust, every one of those concerns is a declarative attribute on the type, and the same declaration governs both directions. ```rust 1 use serde::{Deserialize, Serialize}; 2 3 // rename_all renames EVERY field; rename overrides a single one. 4 #[derive(Debug, Serialize, Deserialize)] 5 #[serde(rename_all = "camelCase")] 6 struct User { 7 user_id: u64, // -> "userId" 8 first_name: String, // -> "firstName" 9 last_name: String, // -> "lastName" 10 #[serde(rename = "emailAddress")] 11 email: String, // -> "emailAddress" (overrides camelCase) 12 } 13 14 #[derive(Debug, Serialize, Deserialize)] 15 #[serde(rename_all = "camelCase")] 16 struct Account { 17 username: String, 18 #[serde(skip)] // never serialized, never deserialized 19 password_hash: String, 20 #[serde(skip_serializing_if = "Option::is_none")] 21 nickname: Option<String>, // omitted from output when None 22 #[serde(default)] // missing input -> Default::default() 23 is_active: bool, 24 #[serde(default = "default_role")] 25 role: String, // missing input -> default_role() 26 } 27 28 fn default_role() -> String { 29 "member".to_string() 30 } 31 32 // Internally tagged enum == a TypeScript discriminated union. 33 #[derive(Debug, Serialize, Deserialize)] 34 #[serde(tag = "type", rename_all = "snake_case")] 35 enum Shape { 36 Circle { radius: f64 }, // {"type":"circle","radius":...} 37 Rectangle { width: f64, height: f64 }, 38 } 39 40 fn main() { 41 let account = Account { 42 username: "ada".into(), 43 password_hash: "secret-hash".into(), 44 nickname: None, 45 is_active: true, 46 role: "admin".into(), 47 }; 48 println!("{}", serde_json::to_string(&account).unwrap()); 49 // {"username":"ada","isActive":true,"role":"admin"} 50 51 let shape = Shape::Circle { radius: 2.5 }; 52 println!("{}", serde_json::to_string(&shape).unwrap()); 53 // {"type":"circle","radius":2.5} 54 } ``` > **Note:** This assumes a project set up per [Serde Basics](/15-serialization/01-serde-basics/): `serde = { version = "1", features = ["derive"] }` and `serde_json = "1"` in `Cargo.toml`. The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) Attributes come in two scopes. A **container attribute** sits on the `struct`/`enum` itself and affects the whole type (`#[serde(rename_all = ...)]`, `#[serde(tag = ...)]`). A **field attribute** sits on a single field and affects only that field (`#[serde(rename = ...)]`, `#[serde(skip)]`, `#[serde(default)]`). Variant attributes sit on enum variants. The same attributes drive both `Serialize` and `Deserialize` unless you scope them with `_serializing`/`_deserializing` suffixes. ### `rename` and `rename_all` [Section titled “rename and rename\_all”](#rename-and-rename_all) `rename` changes the key for one field. `rename_all` applies a casing convention to *every* field (or every variant) in the container. The accepted casings are `"lowercase"`, `"UPPERCASE"`, `"PascalCase"`, `"camelCase"`, `"snake_case"`, `"SCREAMING_SNAKE_CASE"`, `"kebab-case"`, and `"SCREAMING-KEBAB-CASE"`. A field-level `rename` always wins over the container-level `rename_all`, which is exactly what the `email -> "emailAddress"` case above demonstrates. This is the single most common attribute, because Rust style is `snake_case` while most JSON APIs are `camelCase`. Without `rename_all` you would otherwise repeat `#[serde(rename = "...")]` on every field. > **Tip:** You can split serialize and deserialize names with `#[serde(rename(serialize = "out", deserialize = "in"))]` when an API reads one key but writes another. ### `skip`, `skip_serializing`, `skip_deserializing`, and `skip_serializing_if` [Section titled “skip, skip\_serializing, skip\_deserializing, and skip\_serializing\_if”](#skip-skip_serializing-skip_deserializing-and-skip_serializing_if) * `#[serde(skip)]` removes the field from *both* directions. On deserialize the field is filled with `Default::default()`, so the field’s type must implement `Default` (or you must also provide `default = "..."`). * `#[serde(skip_serializing)]` / `#[serde(skip_deserializing)]` skip only one direction. * `#[serde(skip_serializing_if = "path")]` skips the field on output only when the named predicate returns `true`. The value is a **string path to a function** taking `&FieldType -> bool`, most commonly `"Option::is_none"`, `"Vec::is_empty"`, `"str::is_empty"`, or `"<[_]>::is_empty"`. In the `Account` example, `password_hash` vanishes entirely (a secret that must never hit the wire), while `nickname` only disappears when it is `None`. That is why the serialized output is `{"username":"ada","isActive":true,"role":"admin"}`: both `password_hash` and the `None` nickname are gone. ### `default` and `default = "path"` [Section titled “default and default = "path"”](#default-and-default--path) When the input JSON is missing a field, deserialization normally fails. `#[serde(default)]` instead fills it with `Default::default()` for that type. `#[serde(default = "path")]` calls the named function (with signature `fn() -> FieldType`) to produce the value. This is the declarative equivalent of `raw.port ?? 8080`. Deserializing `{ "username": "grace" }` into the `Account` above succeeds and produces: ```text 1 Account { username: "grace", password_hash: "", nickname: None, is_active: false, role: "member" } ``` `password_hash` is `""` (skip’s `Default`), `is_active` is `false` (`bool::default()`), and `role` is `"member"` (our `default_role()`). ### `flatten` [Section titled “flatten”](#flatten) `#[serde(flatten)]` inlines the keys of a nested struct (or a map) into the parent object instead of nesting them. It serves two distinct purposes: 1. **Composition**: share a common block (pagination, metadata) across many response types without nesting it. 2. **Capture** — flatten a `HashMap<String, Value>` to absorb any extra, unknown keys. ```rust 1 use serde::{Deserialize, Serialize}; 2 use std::collections::HashMap; 3 4 #[derive(Debug, Serialize, Deserialize)] 5 struct Pagination { 6 page: u32, 7 per_page: u32, 8 } 9 10 #[derive(Debug, Serialize, Deserialize)] 11 struct UserListResponse { 12 users: Vec<String>, 13 #[serde(flatten)] 14 pagination: Pagination, 15 } 16 17 #[derive(Debug, Serialize, Deserialize)] 18 struct Event { 19 name: String, 20 #[serde(flatten)] 21 extra: HashMap<String, serde_json::Value>, 22 } 23 24 fn main() { 25 let resp = UserListResponse { 26 users: vec!["ada".into(), "grace".into()], 27 pagination: Pagination { page: 1, per_page: 20 }, 28 }; 29 println!("{}", serde_json::to_string(&resp).unwrap()); 30 // {"users":["ada","grace"],"page":1,"per_page":20} 31 32 let event: Event = 33 serde_json::from_str(r#"{ "name": "click", "x": 10, "y": 20, "button": "left" }"#).unwrap(); 34 println!("{event:?}"); 35 // Event { name: "click", extra: {"button": String("left"), "y": Number(20), "x": Number(10)} } 36 } ``` Notice `page` and `per_page` appear at the top level alongside `users`, not nested under a `"pagination"` key. And `Event.extra` swept up `x`, `y`, and `button` even though they were not declared fields. (Map ordering in the `extra` output is not stable — `HashMap` is unordered.) ### `tag`, `content`, and `untagged` (enum representations) [Section titled “tag, content, and untagged (enum representations)”](#tag-content-and-untagged-enum-representations) By default, an externally tagged enum serializes as `{"VariantName": <data>}`. The container attributes change that representation: | Attribute | Representation | JSON for `Circle { radius: 2.5 }` | | ------------------------------------ | ----------------- | ----------------------------------- | | *(none)* | externally tagged | `{"Circle":{"radius":2.5}}` | | `#[serde(tag = "type")]` | internally tagged | `{"type":"Circle","radius":2.5}` | | `#[serde(tag = "k", content = "c")]` | adjacently tagged | `{"k":"Circle","c":{"radius":2.5}}` | | `#[serde(untagged)]` | untagged | `{"radius":2.5}` | **Internally tagged** (`tag = "type"`) is the direct analogue of a TypeScript discriminated union and the most common choice for APIs. **Adjacently tagged** keeps the tag and payload in separate, named keys. **Untagged** has no discriminant at all: Serde tries each variant in declaration order and keeps the first that deserializes successfully. ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 #[serde(tag = "kind", content = "data", rename_all = "snake_case")] 5 enum Message { 6 Text(String), 7 Move { x: i32, y: i32 }, 8 } 9 10 #[derive(Debug, Serialize, Deserialize)] 11 #[serde(untagged)] 12 enum StringOrNumber { 13 Number(i64), 14 Text(String), 15 } 16 17 fn main() { 18 println!("{}", serde_json::to_string(&Message::Move { x: 1, y: 2 }).unwrap()); 19 // {"kind":"move","data":{"x":1,"y":2}} 20 21 let a: StringOrNumber = serde_json::from_str("42").unwrap(); 22 let b: StringOrNumber = serde_json::from_str(r#""hello""#).unwrap(); 23 println!("{a:?} {b:?}"); 24 // Number(42) Text("hello") 25 } ``` > **Note:** Enum representations are covered more deeply in [Structs and JSON](/15-serialization/03-json/). This file focuses on the `tag`/`content`/`untagged` *attributes* that select them. ### `with`, `serialize_with`, and `deserialize_with` [Section titled “with, serialize\_with, and deserialize\_with”](#with-serialize_with-and-deserialize_with) When a field’s natural Rust type does not match its wire format — a `u64` timestamp stored as a JSON string, a date in a custom format, bytes as base64 — `#[serde(with = "module")]` delegates that one field to a module that provides `serialize` and `deserialize` functions. `serialize_with`/`deserialize_with` do the same with a single function each, when you only need one direction or prefer not to write a module. ```rust 1 use serde::{Deserialize, Serialize}; 2 3 // A module exposing `serialize` and `deserialize` for a u64 stored as a 4 // JSON string (some APIs send 64-bit integers as strings to dodge the 5 // JavaScript number-precision problem). 6 mod epoch_seconds { 7 use serde::{self, Deserialize, Deserializer, Serializer}; 8 9 pub fn serialize<S>(secs: &u64, serializer: S) -> Result<S::Ok, S::Error> 10 where 11 S: Serializer, 12 { 13 serializer.serialize_str(&secs.to_string()) 14 } 15 16 pub fn deserialize<'de, D>(deserializer: D) -> Result<u64, D::Error> 17 where 18 D: Deserializer<'de>, 19 { 20 let s = String::deserialize(deserializer)?; 21 s.parse::<u64>().map_err(serde::de::Error::custom) 22 } 23 } 24 25 #[derive(Debug, Serialize, Deserialize)] 26 struct LogEntry { 27 message: String, 28 #[serde(with = "epoch_seconds")] 29 timestamp: u64, 30 } 31 32 fn main() { 33 let entry = LogEntry { message: "started".into(), timestamp: 1717200000 }; 34 println!("{}", serde_json::to_string(&entry).unwrap()); 35 // {"message":"started","timestamp":"1717200000"} 36 37 let back: LogEntry = 38 serde_json::from_str(r#"{"message":"ok","timestamp":"1717200001"}"#).unwrap(); 39 println!("{back:?}"); 40 // LogEntry { message: "ok", timestamp: 1717200001 } 41 } ``` The `timestamp` is a real `u64` in Rust but a quoted string on the wire. The `with` module is the seam. The hand-written-trait version of this technique, plus `remote` derive, lives in [Custom Serialization](/15-serialization/07-custom-serialization/). > **Tip:** This precision issue is a real cross-language trap. JavaScript’s `number` is always an IEEE-754 `f64`, so any integer above `2^53 - 1` (`Number.MAX_SAFE_INTEGER`) silently loses precision. It does *not* wrap. Sending big 64-bit IDs as JSON strings, then mapping them with `with`, sidesteps that entirely. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concern | TypeScript/JavaScript | Rust + Serde | | -------------------- | ------------------------------------------------------------ | --------------------------------------------------- | | Rename a key | Manual in `toJSON()` / `class-transformer` `@Expose({name})` | `#[serde(rename = "...")]` | | Bulk casing | Library config (e.g. `camelcase-keys`) | `#[serde(rename_all = "camelCase")]` | | Hide a field | `toJSON()` omits it; nothing enforces it | `#[serde(skip)]`, compile-checked | | Omit if empty | `if (x != null) out.x = x` | `#[serde(skip_serializing_if = "Option::is_none")]` | | Default on parse | `value ?? fallback` | `#[serde(default)]` / `default = "fn"` | | Inline nested object | Spread `{...base, ...extra}` | `#[serde(flatten)]` | | Discriminated union | `type` literal property, narrowed by hand | `#[serde(tag = "type")]` enum | | Custom field codec | Custom getter/setter or transformer | `#[serde(with = "module")]` | | Symmetry | Serialize and parse are separate code paths | One attribute drives both directions | The deepest conceptual difference is **symmetry and verification**. In TypeScript, `JSON.stringify`/`JSON.parse` are unaware of your types; a `toJSON()` method shapes output but nothing checks that `JSON.parse` produces the inverse, and the casts (`as User`) are erased at runtime. In Rust, a single set of attributes generates *both* directions of compile-checked code at build time (monomorphized, not reflective), so an output you produce can be parsed back, and a missing or mistyped attribute is a build error, not a 2 a.m. runtime surprise. A second difference: TypeScript generics and interfaces are erased at runtime, so a “type” is only a compile-time fiction during (de)serialization. Serde generates concrete code per type, which is why attributes like `skip` can enforce that a secret never serializes — there is real code, not a hopeful annotation. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: `skip` on a type that is not `Default` [Section titled “Pitfall 1: skip on a type that is not Default”](#pitfall-1-skip-on-a-type-that-is-not-default) `#[serde(skip)]` needs *some* value to put in the field when deserializing. By default it calls `Default::default()`, so the field’s type must implement `Default`. ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 struct Connection { 5 host: String, 6 } 7 8 #[derive(Debug, Serialize, Deserialize)] 9 struct Server { 10 name: String, 11 #[serde(skip)] // does not compile (error[E0277]: Connection: Default not satisfied) 12 connection: Connection, 13 } 14 15 fn main() { 16 let _s: Server = serde_json::from_str(r#"{ "name": "web-1" }"#).unwrap(); 17 } ``` The real compiler error is: ```text 1 error[E0277]: the trait bound `Connection: Default` is not satisfied 2 --> src/main.rs:8:28 3 | 4 8 | #[derive(Debug, Serialize, Deserialize)] 5 | ^^^^^^^^^^^ the trait `Default` is not implemented for `Connection` 6 | 7 = note: this error originates in the derive macro `Deserialize` (in Nightly builds, run with -Z macro-backtrace for more info) 8 help: consider annotating `Connection` with `#[derive(Default)]` 9 | 10 4 + #[derive(Default)] 11 5 | struct Connection { ``` **Fix:** add `#[derive(Default)]` to `Connection`, or pair the skip with an explicit factory: `#[serde(skip, default = "make_connection")]`. ### Pitfall 2: `skip_serializing_if` value must be a string path [Section titled “Pitfall 2: skip\_serializing\_if value must be a string path”](#pitfall-2-skip_serializing_if-value-must-be-a-string-path) The predicate is a string literal naming a function, not a bare expression or closure. Writing it without quotes is a hard error. ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 struct Item { 5 name: String, 6 #[serde(skip_serializing_if = Vec::is_empty)] // does not compile (must be a string) 7 tags: Vec<String>, 8 } 9 10 fn main() { 11 let item = Item { name: "x".into(), tags: vec![] }; 12 println!("{}", serde_json::to_string(&item).unwrap()); 13 } ``` The real error is: ```text 1 error: expected serde skip_serializing_if attribute to be a string: `skip_serializing_if = "..."` 2 --> src/main.rs:6:35 3 | 4 6 | #[serde(skip_serializing_if = Vec::is_empty)] 5 | ^^^^^^^^^^^^^ ``` **Fix:** quote it — `#[serde(skip_serializing_if = "Vec::is_empty")]`. ### Pitfall 3: Internally tagged enums and newtype primitives [Section titled “Pitfall 3: Internally tagged enums and newtype primitives”](#pitfall-3-internally-tagged-enums-and-newtype-primitives) An internally tagged enum (`#[serde(tag = "...")]`) injects the tag key *into the variant’s object*. A newtype variant wrapping a primitive (like `i64`) has no object to inject into, so it compiles but fails at **runtime**. ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 #[serde(tag = "type")] 5 enum Token { 6 Number(i64), // a primitive newtype variant 7 Word { text: String }, 8 } 9 10 fn main() { 11 let t = Token::Number(42); 12 match serde_json::to_string(&t) { 13 Ok(s) => println!("ok: {s}"), 14 Err(e) => println!("error: {e}"), 15 } 16 } ``` This prints the genuine runtime error message: ```text 1 error: cannot serialize tagged newtype variant Token::Number containing an integer ``` **Fix:** internally tagged enums require struct-like or unit variants (or newtype variants wrapping a struct/map). Use a struct variant — `Number { value: i64 }` — or switch to an adjacently tagged (`tag` + `content`) or untagged representation. ### Pitfall 4: `default` does not rescue an explicit `null` [Section titled “Pitfall 4: default does not rescue an explicit null”](#pitfall-4-default-does-not-rescue-an-explicit-null) `#[serde(default)]` fills a value only when the key is **absent**. A present `null` is a real value and is deserialized as such. For a non-`Option` field, `"role": null` will error rather than fall back to the default. `default` is about missing keys, not null ones. To accept either, use `Option<T>` (or combine `default` with a `deserialize_with` that maps null to the default). ### Pitfall 5: Two flattened fields claiming the same key [Section titled “Pitfall 5: Two flattened fields claiming the same key”](#pitfall-5-two-flattened-fields-claiming-the-same-key) If you flatten two structs that share a key (e.g. both expose `id`), or flatten a map alongside an explicit field of the same name, behavior is ambiguous and the round trip silently misbehaves. Keep flattened key namespaces disjoint, and reserve a flattened catch-all `HashMap` strictly for *unknown* extras. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Set `rename_all` once at the container level** rather than renaming each field. Reach for field-level `rename` only for the genuine exceptions. * **Use `skip` for true secrets** (password hashes, internal tokens). Unlike a TypeScript `toJSON()` omission, this is enforced by the compiler: the field has no serialization code at all. * **Prefer `skip_serializing_if = "Option::is_none"` over emitting `null`.** Most APIs treat “absent” and “null” differently; omitting keeps payloads small and intentions clear. * **Pair `default` with `Option`/`Vec`/`bool` for forgiving deserialization** of optional config: it makes adding new fields backward-compatible. * **Use internally tagged enums (`tag = "type"`) to mirror TypeScript discriminated unions.** It is the most ergonomic and the most familiar to API consumers. * **Add `#[serde(deny_unknown_fields)]` on strict inputs** (config files, internal RPC) to catch typos; leave it off and use a flattened `HashMap` when you must tolerate forward-compatible extras. * **Reach for `with` only when the wire type genuinely differs** from the Rust type (timestamps-as-strings, base64 bytes). For mechanical casing/renaming, the simpler attributes are enough. * **Keep the same attribute set on both sides of a round trip.** Because one declaration drives serialize and deserialize, asymmetric `_serializing`/`_deserializing` attributes should be a deliberate, documented choice. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A typical API resource: a Rust-idiomatic struct mapped to a `camelCase` JSON contract, hiding internal fields, omitting empty optionals, filling defaults for forward compatibility, and carrying a polymorphic status as an internally tagged enum. ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 #[serde(rename_all = "camelCase")] 5 struct ApiUser { 6 id: u64, 7 display_name: String, 8 9 // The wire contract uses "email_address" regardless of camelCase. 10 #[serde(rename = "email_address")] 11 email: String, 12 13 // Internal-only; never crosses the wire. 14 #[serde(skip)] 15 internal_notes: String, 16 17 // Omit entirely when there is no avatar, rather than sending null. 18 #[serde(skip_serializing_if = "Option::is_none")] 19 avatar_url: Option<String>, 20 21 // Missing in the payload? Fall back to a sensible value. 22 #[serde(default = "default_locale")] 23 locale: String, 24 25 // Missing array? Treat it as empty. 26 #[serde(default)] 27 roles: Vec<String>, 28 29 // Polymorphic, self-describing status. 30 status: AccountStatus, 31 } 32 33 fn default_locale() -> String { 34 "en-US".to_string() 35 } 36 37 #[derive(Debug, Serialize, Deserialize)] 38 #[serde(tag = "state", rename_all = "snake_case")] 39 enum AccountStatus { 40 Active, 41 Suspended { reason: String }, 42 PendingReview { since: String }, 43 } 44 45 fn main() -> Result<(), serde_json::Error> { 46 let user = ApiUser { 47 id: 1001, 48 display_name: "Grace Hopper".into(), 49 email: "grace@example.com".into(), 50 internal_notes: "VIP - do not expose".into(), 51 avatar_url: None, 52 locale: "en-US".into(), 53 roles: vec!["admin".into(), "auditor".into()], 54 status: AccountStatus::Suspended { reason: "policy violation".into() }, 55 }; 56 println!("--- outgoing response ---\n{}", serde_json::to_string_pretty(&user)?); 57 58 // A minimal request: missing locale, roles, and avatar. 59 let incoming = r#"{ 60 "id": 2002, 61 "displayName": "Alan Turing", 62 "email_address": "alan@example.com", 63 "status": { "state": "active" } 64 }"#; 65 let parsed: ApiUser = serde_json::from_str(incoming)?; 66 println!("\n--- parsed request ---\n{parsed:?}"); 67 68 Ok(()) 69 } ``` Running it prints the real output below. Note that `internalNotes` is absent (skipped), `avatarUrl` is absent (`None`), `email_address` keeps its overridden name, and the parsed request received `locale: "en-US"`, `roles: []`, and `internal_notes: ""` from defaults: ```text 1 --- outgoing response --- 2 { 3 "id": 1001, 4 "displayName": "Grace Hopper", 5 "email_address": "grace@example.com", 6 "locale": "en-US", 7 "roles": [ 8 "admin", 9 "auditor" 10 ], 11 "status": { 12 "state": "suspended", 13 "reason": "policy violation" 14 } 15 } 16 17 --- parsed request --- 18 ApiUser { id: 2002, display_name: "Alan Turing", email: "alan@example.com", internal_notes: "", avatar_url: None, locale: "en-US", roles: [], status: Active } ``` This is the kind of struct you would hand to a web framework like Axum to (de)serialize request and response bodies automatically — see [Web APIs](/16-web-apis/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [Serde attributes overview](https://serde.rs/attributes.html) * [Container attributes](https://serde.rs/container-attrs.html) (including `rename_all`, `tag`, `content`, `untagged`, `deny_unknown_fields`) * [Field attributes](https://serde.rs/field-attrs.html) (`rename`, `skip`, `skip_serializing_if`, `default`, `flatten`, `with`) * [Variant attributes](https://serde.rs/variant-attrs.html) * [Enum representations](https://serde.rs/enum-representations.html) ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Serde Introduction](/15-serialization/00-serde-intro/): the data model and the `Serialize`/`Deserialize` traits * [Serde Basics](/15-serialization/01-serde-basics/): project setup and `to_string`/`from_str` * [Derive Serialize/Deserialize](/15-serialization/02-derive-serialize/) — what the derive macro generates * [Structs and JSON](/15-serialization/03-json/) — nested types, `Option`, and enum representations in depth * [Dynamic JSON](/15-serialization/04-json-manipulation/) — `serde_json::Value` and the `json!` macro (the type behind a flattened catch-all map) * [Custom Serialization](/15-serialization/07-custom-serialization/) — hand-written impls, `serialize_with`/`deserialize_with`, and remote derive * [Other Formats](/15-serialization/06-other-formats/) — the same attributes applied to TOML, YAML, and MessagePack * [Performance](/15-serialization/08-performance/) — borrowing and zero-copy considerations * Foundations: [enums and structs](/06-data-structures/), [`Option`/`Result`](/08-error-handling/), and [basic types](/02-basics/) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Match a camelCase product API [Section titled “Exercise 1: Match a camelCase product API”](#exercise-1-match-a-camelcase-product-api) **Difficulty:** Easy **Objective:** Use `rename_all` and `skip_serializing_if` to match a JSON contract. **Instructions:** Define a `Product` struct with `product_id: u32`, `display_name: String`, and `discount_code: Option<String>`. The JSON API uses `camelCase` keys, and the discount code must be omitted entirely when there is none. Serialize a product with no discount code and confirm `discountCode` is absent. ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 struct Product { 5 product_id: u32, 6 display_name: String, 7 discount_code: Option<String>, // TODO: add attributes 8 } 9 10 fn main() { 11 let p = Product { 12 product_id: 9, 13 display_name: "Widget".into(), 14 discount_code: None, 15 }; 16 println!("{}", serde_json::to_string(&p).unwrap()); 17 // target: {"productId":9,"displayName":"Widget"} 18 } ``` Solution ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 #[serde(rename_all = "camelCase")] 5 struct Product { 6 product_id: u32, 7 display_name: String, 8 #[serde(skip_serializing_if = "Option::is_none")] 9 discount_code: Option<String>, 10 } 11 12 fn main() { 13 let p = Product { 14 product_id: 9, 15 display_name: "Widget".into(), 16 discount_code: None, 17 }; 18 println!("{}", serde_json::to_string(&p).unwrap()); 19 // {"productId":9,"displayName":"Widget"} 20 } ``` ### Exercise 2: Forgiving configuration with defaults [Section titled “Exercise 2: Forgiving configuration with defaults”](#exercise-2-forgiving-configuration-with-defaults) **Difficulty:** Medium **Objective:** Use `default` and `default = "fn"` so a minimal config still parses. **Instructions:** Define `ServerConfig` with `host: String`, `port: u16` (default `8080`), `tls_enabled: bool` (default `false`), and `allowed_origins: Vec<String>` (default empty). Deserialize the JSON `{ "host": "localhost" }` and confirm the missing fields receive their defaults. ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 struct ServerConfig { 5 host: String, 6 port: u16, // TODO: default 8080 7 tls_enabled: bool, // TODO: default false 8 allowed_origins: Vec<String>, // TODO: default empty 9 } 10 11 fn main() { 12 let cfg: ServerConfig = 13 serde_json::from_str(r#"{ "host": "localhost" }"#).unwrap(); 14 println!("{cfg:?}"); 15 } ``` Solution ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 #[serde(rename_all = "snake_case")] 5 struct ServerConfig { 6 host: String, 7 #[serde(default = "default_port")] 8 port: u16, 9 #[serde(default)] 10 tls_enabled: bool, 11 #[serde(default)] 12 allowed_origins: Vec<String>, 13 } 14 15 fn default_port() -> u16 { 16 8080 17 } 18 19 fn main() { 20 let cfg: ServerConfig = 21 serde_json::from_str(r#"{ "host": "localhost" }"#).unwrap(); 22 println!("{cfg:?}"); 23 // ServerConfig { host: "localhost", port: 8080, tls_enabled: false, allowed_origins: [] } 24 } ``` `#[serde(default)]` uses each type’s `Default` (`false`, empty `Vec`), while `default = "default_port"` calls a function for the non-trivial `8080`. ### Exercise 3: Comma-separated list via `with` [Section titled “Exercise 3: Comma-separated list via with”](#exercise-3-comma-separated-list-via-with) **Difficulty:** Hard **Objective:** Write a `with` module so a `Vec<String>` field is stored on the wire as a single comma-separated string. **Instructions:** Define `CsvRow { id: u32, labels: Vec<String> }`. Build a module `comma_list` exposing `serialize` and `deserialize` so that `labels` serializes as `"red,urgent"` and parses `"a, b, c"` back into a trimmed `Vec`. Wire it with `#[serde(with = "comma_list")]`. ```rust 1 use serde::{Deserialize, Serialize}; 2 3 mod comma_list { 4 // TODO: serialize<S>(items: &[String], s: S) -> Result<S::Ok, S::Error> 5 // TODO: deserialize<'de, D>(d: D) -> Result<Vec<String>, D::Error> 6 } 7 8 #[derive(Debug, Serialize, Deserialize)] 9 struct CsvRow { 10 id: u32, 11 labels: Vec<String>, // TODO: #[serde(with = "comma_list")] 12 } 13 14 fn main() { 15 let row = CsvRow { id: 1, labels: vec!["red".into(), "urgent".into()] }; 16 println!("{}", serde_json::to_string(&row).unwrap()); 17 let back: CsvRow = 18 serde_json::from_str(r#"{"id":2,"labels":"a, b, c"}"#).unwrap(); 19 println!("{back:?}"); 20 } ``` Solution ```rust 1 use serde::{Deserialize, Serialize}; 2 3 mod comma_list { 4 use serde::{Deserialize, Deserializer, Serializer}; 5 6 pub fn serialize<S>(items: &[String], serializer: S) -> Result<S::Ok, S::Error> 7 where 8 S: Serializer, 9 { 10 serializer.serialize_str(&items.join(",")) 11 } 12 13 pub fn deserialize<'de, D>(deserializer: D) -> Result<Vec<String>, D::Error> 14 where 15 D: Deserializer<'de>, 16 { 17 let s = String::deserialize(deserializer)?; 18 if s.is_empty() { 19 return Ok(Vec::new()); 20 } 21 Ok(s.split(',').map(|p| p.trim().to_string()).collect()) 22 } 23 } 24 25 #[derive(Debug, Serialize, Deserialize)] 26 struct CsvRow { 27 id: u32, 28 #[serde(with = "comma_list")] 29 labels: Vec<String>, 30 } 31 32 fn main() { 33 let row = CsvRow { id: 1, labels: vec!["red".into(), "urgent".into()] }; 34 println!("{}", serde_json::to_string(&row).unwrap()); 35 // {"id":1,"labels":"red,urgent"} 36 37 let back: CsvRow = 38 serde_json::from_str(r#"{"id":2,"labels":"a, b, c"}"#).unwrap(); 39 println!("{back:?}"); 40 // CsvRow { id: 2, labels: ["a", "b", "c"] } 41 } ``` The `with` module names two functions Serde wires up automatically. This is the gateway to fully hand-written impls covered in [Custom Serialization](/15-serialization/07-custom-serialization/). # Beyond JSON: TOML, YAML, MessagePack, bincode, and CSV with Serde > Node needs a separate library per format; in Rust you derive Serialize once, then swap a crate to read TOML, YAML, MessagePack, bincode, or CSV from the same struct. In the Node.js world, JSON is the default and everything else needs a separate library: `js-yaml` for YAML, `@iarna/toml` for TOML, `csv-parse` for CSV, `@msgpack/msgpack` for MessagePack. Each ships its own API, its own type story, and its own quirks. Serde flips this: you derive `Serialize` and `Deserialize` **once**, then plug in a different format crate to read or write the same data as TOML, YAML, MessagePack, a binary blob, or CSV rows. This page shows the same struct travelling through all five formats. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Serde separates your **data types** from the **wire format**. Your structs implement the `Serialize` and `Deserialize` traits via `#[derive]`; a *format crate* (`toml`, `serde_norway`, `rmp-serde`, `bincode`, `csv`) knows how to turn that trait-driven description into bytes and back. Adding a new format to your program means adding a crate and calling its `to_string` / `from_str` (or `to_vec` / `from_slice`). Your type definitions do not change at all. For a TypeScript developer this is the payoff: one set of annotations, every format for free. > **Note:** This page assumes you already know the JSON basics from [Serde Basics](/15-serialization/01-serde-basics/) and how `#[derive(Serialize, Deserialize)]` works from [Deriving `Serialize` and `Deserialize`](/15-serialization/02-derive-serialize/). The architecture that makes one derive work across all formats is explained in [Serde](/15-serialization/00-serde-intro/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In Node.js, each format is a different package with a different shape. Here is the same configuration object serialized to four text formats and one binary format, the way you would actually do it: ```typescript 1 // npm install js-yaml @iarna/toml @msgpack/msgpack 2 import * as YAML from "js-yaml"; 3 import * as TOML from "@iarna/toml"; 4 import { encode, decode } from "@msgpack/msgpack"; 5 6 interface ServerConfig { 7 name: string; 8 port: number; 9 workers: number; 10 tls: boolean; 11 allowedOrigins: string[]; 12 } 13 14 const config: ServerConfig = { 15 name: "api-gateway", 16 port: 8443, 17 workers: 8, 18 tls: true, 19 allowedOrigins: ["https://app.example.com", "https://admin.example.com"], 20 }; 21 22 // JSON — built in 23 const json: string = JSON.stringify(config); 24 25 // YAML — js-yaml: returns `any` on load, no type checking 26 const yamlText: string = YAML.dump(config); 27 const fromYaml = YAML.load(yamlText) as ServerConfig; // cast is unchecked 28 29 // TOML — @iarna/toml: again `any`, again an unchecked cast 30 const tomlText: string = TOML.stringify(config as any); 31 const fromToml = TOML.parse(tomlText) as unknown as ServerConfig; 32 33 // MessagePack — binary, returns Uint8Array; decode() is `unknown` 34 const packed: Uint8Array = encode(config); 35 const fromMsgpack = decode(packed) as ServerConfig; // cast is unchecked ``` Notice the recurring pattern: each library has a different method name (`dump`/`load`, `stringify`/`parse`, `encode`/`decode`), and every `load`/`parse`/`decode` hands you `any` or `unknown` that you cast with `as`. That cast is a compile-time fiction — **nothing validates that the parsed bytes actually match `ServerConfig` at runtime**. CSV is worse still: most Node CSV libraries give you arrays of strings and you convert each field by hand. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) First, add the format crates. `cargo new` selects the newest stable edition automatically (the repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition): ```bash 1 cargo new config_formats 2 cd config_formats 3 cargo add serde --features derive 4 cargo add serde_json 5 cargo add toml 6 cargo add serde_norway # maintained successor to the deprecated serde_yaml 7 cargo add rmp-serde # MessagePack 8 cargo add bincode@2 --features serde 9 cargo add csv ``` That produces these dependencies in `Cargo.toml`: ```toml 1 [dependencies] 2 bincode = { version = "2", features = ["serde"] } 3 csv = "1.4.0" 4 rmp-serde = "1.3.1" 5 serde = { version = "1.0.228", features = ["derive"] } 6 serde_json = "1.0.150" 7 serde_norway = "0.9.42" 8 toml = "1.1.2" ``` Now define the struct **once** and run it through every format in `src/main.rs`: ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize, PartialEq)] 4 struct ServerConfig { 5 name: String, 6 port: u16, 7 workers: u32, 8 tls: bool, 9 allowed_origins: Vec<String>, 10 } 11 12 fn main() { 13 let cfg = ServerConfig { 14 name: "api-gateway".to_string(), 15 port: 8443, 16 workers: 8, 17 tls: true, 18 allowed_origins: vec![ 19 "https://app.example.com".to_string(), 20 "https://admin.example.com".to_string(), 21 ], 22 }; 23 24 // --- TOML (text) --- 25 let toml_text = toml::to_string(&cfg).unwrap(); 26 println!("=== TOML ==="); 27 print!("{toml_text}"); 28 let toml_back: ServerConfig = toml::from_str(&toml_text).unwrap(); 29 println!("toml round-trip equal: {}", toml_back == cfg); 30 31 // --- YAML (text) --- 32 let yaml_text = serde_norway::to_string(&cfg).unwrap(); 33 println!("=== YAML ==="); 34 print!("{yaml_text}"); 35 let yaml_back: ServerConfig = serde_norway::from_str(&yaml_text).unwrap(); 36 println!("yaml round-trip equal: {}", yaml_back == cfg); 37 38 // --- MessagePack (binary) --- 39 let mp: Vec<u8> = rmp_serde::to_vec(&cfg).unwrap(); 40 println!("=== MessagePack ==="); 41 println!("msgpack bytes: {}", mp.len()); 42 let mp_back: ServerConfig = rmp_serde::from_slice(&mp).unwrap(); 43 println!("msgpack round-trip equal: {}", mp_back == cfg); 44 45 // --- bincode (binary) --- 46 let config = bincode::config::standard(); 47 let bin: Vec<u8> = bincode::serde::encode_to_vec(&cfg, config).unwrap(); 48 println!("=== bincode ==="); 49 println!("bincode bytes: {}", bin.len()); 50 let (bin_back, _consumed): (ServerConfig, usize) = 51 bincode::serde::decode_from_slice(&bin, config).unwrap(); 52 println!("bincode round-trip equal: {}", bin_back == cfg); 53 } ``` Real output from `cargo run`: ```text 1 === TOML === 2 name = "api-gateway" 3 port = 8443 4 workers = 8 5 tls = true 6 allowed_origins = ["https://app.example.com", "https://admin.example.com"] 7 toml round-trip equal: true 8 === YAML === 9 name: api-gateway 10 port: 8443 11 workers: 8 12 tls: true 13 allowed_origins: 14 - https://app.example.com 15 - https://admin.example.com 16 yaml round-trip equal: true 17 === MessagePack === 18 msgpack bytes: 69 19 msgpack round-trip equal: true 20 === bincode === 21 bincode bytes: 68 22 bincode round-trip equal: true ``` The struct never changed. Each format crate exposes the same two-verb vocabulary — text formats use `to_string` / `from_str`, binary formats use `to_vec` / `from_slice` — and every `from_*` returns a fully-typed `ServerConfig`, not an `any` you have to trust. The `round-trip equal: true` lines come from `PartialEq`, proving the data survived the trip intact. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) Let’s unpack each format and the one or two lines that drive it. * **TOML, `toml::to_string(&cfg)` / `toml::from_str(&text)`.** TOML (“Tom’s Obvious Minimal Language”) is the format Rust itself uses for `Cargo.toml`, so it is the natural choice for human-edited config. The API mirrors `serde_json` exactly: `to_string`, `to_string_pretty`, `from_str`. Scalars become `key = value`; a `Vec` becomes an inline array; a nested struct becomes a `[table]` section. One structural rule matters: the **top level of a TOML document must be a table** (a struct or map), never a bare array or scalar; see [Common Pitfalls](#common-pitfalls). * **YAML, `serde_norway::to_string(&cfg)` / `serde_norway::from_str(&text)`.** YAML is whitespace-significant and common in Kubernetes, CI pipelines, and Docker Compose. The widely-cited `serde_yaml` crate was **deprecated and archived by its author in 2024**; `serde_norway` is a drop-in maintained fork with the identical API, which is why this guide uses it. The output starts directly with `name:` — by default it emits no `---` document-start marker. * **MessagePack, `rmp_serde::to_vec(&cfg)` / `rmp_serde::from_slice(&bytes)`.** MessagePack is a compact binary format (“like JSON, but fast and small”). Because it is binary, you serialize to `Vec<u8>` (not `String`) and deserialize from `&[u8]`. Here the same data is 69 bytes versus JSON’s 131, roughly half. `rmp-serde` is the Serde-integrated implementation; the crate name comes from “**r**ust **m**ess**p**ack”. * **bincode — `bincode::serde::encode_to_vec(&cfg, config)` / `bincode::serde::decode_from_slice(&bin, config)`.** bincode is a Rust-native binary format optimized for Rust-to-Rust communication (caches, IPC, on-disk snapshots). Version 2.x takes an explicit **configuration** value (`bincode::config::standard()`) that fixes the integer encoding and byte order, and its `decode_from_slice` returns a tuple `(value, bytes_consumed)`. The `bincode::serde::` path is what bridges bincode to Serde-derived types; it is gated behind the `serde` feature you enabled with `cargo add bincode@2 --features serde`. * **`PartialEq` in the derive.** Adding `PartialEq` lets us write `toml_back == cfg`. It has nothing to do with Serde; it is just how we assert each round-trip preserved the value. Every format above reads the *same* `#[derive(Serialize, Deserialize)]`. That is the whole point of Serde’s design: the format crate and your type never know about each other directly: they meet through Serde’s data model. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Format | Crate | Text/Binary | Serialize / Deserialize | Typical use | | ----------- | -------------- | ----------- | ------------------------------------------- | ---------------------------------- | | JSON | `serde_json` | text | `to_string` / `from_str` | HTTP APIs, config, logs | | TOML | `toml` | text | `to_string` / `from_str` | Human-edited config (`Cargo.toml`) | | YAML | `serde_norway` | text | `to_string` / `from_str` | Kubernetes, CI, Compose | | MessagePack | `rmp-serde` | binary | `to_vec` / `from_slice` | Compact wire transfer, caches | | bincode | `bincode` (v2) | binary | `encode_to_vec` / `decode_from_slice` | Rust↔Rust IPC, snapshots | | CSV | `csv` | text | `Writer::serialize` / `Reader::deserialize` | Tabular data, spreadsheets | A few conceptual points a TypeScript developer should internalize: * **One derive, every format.** In Node you reach for a different library per format, each with its own type-erased `any`. In Rust the *type* carries the serialization logic, and formats are interchangeable consumers of it. Swapping JSON for MessagePack in a function is often a one-line change. * **Binary formats use bytes, not strings.** `to_vec`/`encode_to_vec` return `Vec<u8>`; you cannot `println!("{}")` a MessagePack blob as text. This is a hard type-level distinction Rust enforces, unlike JavaScript where a `Uint8Array` and a `string` blur together at the edges. * **Self-describing vs. schema-coupled.** JSON, TOML, YAML, and MessagePack are *self-describing*: the bytes contain field names (or at least structure), so a slightly different reader can still parse them. bincode’s compact form is *positional*: it stores values in field order with no names, which is smaller but means producer and consumer must agree on the exact layout. MessagePack offers both modes (see Pitfalls). * **CSV is row-shaped, not tree-shaped.** JSON/TOML/YAML/MessagePack represent arbitrary nested trees. CSV represents a flat table: a header row plus data rows. A struct maps cleanly to a row only when all its fields are scalars — nesting a struct inside another and writing it as CSV is an error, not silent flattening. * **TOML and YAML are not interchangeable for everything.** TOML insists the root is a table and has no concept of a top-level array document; YAML is happy with a top-level sequence. Pick the format to fit the data shape, not the other way around. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Reaching for the deprecated `serde_yaml` [Section titled “Reaching for the deprecated serde\_yaml”](#reaching-for-the-deprecated-serde_yaml) Most YAML tutorials and older answers tell you to `cargo add serde_yaml`. That crate was deprecated and archived by its maintainer in 2024 and no longer receives fixes. Use **`serde_norway`** instead — it is a maintained fork with the same module-level functions (`to_string`, `from_str`, `to_writer`, `from_reader`), so existing examples work after a rename: ```rust 1 // Old (deprecated, unmaintained): 2 // let text = serde_yaml::to_string(&cfg).unwrap(); 3 4 // Current: 5 let text = serde_norway::to_string(&cfg).unwrap(); ``` ### TOML’s top level must be a table [Section titled “TOML’s top level must be a table”](#tomls-top-level-must-be-a-table) TOML documents are key/value tables at the root. Trying to serialize a bare `Vec` (or any non-map) at the top level fails. This compiles but errors at runtime: ```rust 1 use serde::Serialize; 2 3 #[derive(Serialize)] 4 struct Item { 5 id: u32, 6 label: String, 7 } 8 9 fn main() { 10 let items = vec![ 11 Item { id: 1, label: "a".into() }, 12 Item { id: 2, label: "b".into() }, 13 ]; 14 // runtime error: TOML's root must be a table, not an array 15 match toml::to_string(&items) { 16 Ok(s) => println!("{s}"), 17 Err(e) => println!("error: {e}"), 18 } 19 } ``` The real output from `cargo run`: ```text 1 error: unsupported array type ``` The fix is to wrap the array in a struct field, e.g. `struct Catalog { items: Vec<Item> }`, which serializes the array under an `[[items]]` array-of-tables. JSON and YAML have no such restriction — only TOML requires a table at the root. ### CSV cannot represent nested structs [Section titled “CSV cannot represent nested structs”](#csv-cannot-represent-nested-structs) CSV is flat. If a struct field is itself a struct (or a `Vec`/`HashMap`), the `csv` crate cannot lay it out as columns and refuses when it tries to write the header. This compiles but errors at runtime: ```rust 1 use serde::Serialize; 2 3 #[derive(Serialize)] 4 struct Address { 5 city: String, 6 zip: String, 7 } 8 9 #[derive(Serialize)] 10 struct Person { 11 name: String, 12 address: Address, // nested struct: CSV has no column layout for this 13 } 14 15 fn main() { 16 let p = Person { 17 name: "Ada".into(), 18 address: Address { city: "London".into(), zip: "EC1A".into() }, 19 }; 20 let mut wtr = csv::Writer::from_writer(vec![]); 21 match wtr.serialize(&p) { 22 Ok(()) => println!("ok"), 23 Err(e) => println!("error: {e}"), 24 } 25 } ``` The real output from `cargo run`: ```text 1 error: CSV write error: cannot serialize Address container inside struct when writing headers from structs ``` Keep CSV records flat: use only scalar fields (`String`, numbers, `bool`). If you need nesting, flatten it manually (e.g. `city: String`, `zip: String` directly on `Person`) or choose a tree format like JSON. ### MessagePack: compact (array) form drops field names [Section titled “MessagePack: compact (array) form drops field names”](#messagepack-compact-array-form-drops-field-names) `rmp_serde::to_vec` produces the *compact* encoding, which stores struct fields **positionally as an array**. Field names are not written. That is smaller, but it means the decoder must use the exact same field order. `to_vec_named` writes a *map* with field names, which is larger but order-independent and interoperable with other MessagePack libraries that expect named fields. Mixing them silently scrambles data rather than erroring: ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Serialize)] 4 struct V1 { 5 a: u32, 6 b: u32, 7 c: u32, 8 } 9 10 // Same fields, declared in a DIFFERENT order: 11 #[derive(Debug, Deserialize)] 12 struct V2 { 13 c: u32, 14 b: u32, 15 a: u32, 16 } 17 18 fn main() { 19 let v1 = V1 { a: 1, b: 2, c: 3 }; 20 21 // Compact: positions are matched, names ignored -> WRONG mapping 22 let compact = rmp_serde::to_vec(&v1).unwrap(); 23 let from_compact: V2 = rmp_serde::from_slice(&compact).unwrap(); 24 println!("compact -> {from_compact:?}"); 25 26 // Named: fields matched by name -> correct 27 let named = rmp_serde::to_vec_named(&v1).unwrap(); 28 let from_named: V2 = rmp_serde::from_slice(&named).unwrap(); 29 println!("named -> {from_named:?}"); 30 } ``` The real output from `cargo run`: ```text 1 compact -> V2 { c: 1, b: 2, a: 3 } 2 named -> V2 { c: 3, b: 2, a: 1 } ``` The compact decode put `1` into `c` purely by position — no error, just wrong data. Use `to_vec_named` whenever the reader and writer might disagree on field order, or when talking to a non-Rust MessagePack consumer. ### bincode: decode with the same config you encoded with [Section titled “bincode: decode with the same config you encoded with”](#bincode-decode-with-the-same-config-you-encoded-with) bincode 2.x makes the configuration explicit, and it is **not** stored in the bytes. If you encode with `standard()` (variable-length integers) and decode with `with_fixed_int_encoding()`, the bytes are misinterpreted. Always thread the same `config` value through both calls: ```rust 1 let config = bincode::config::standard(); 2 let bytes = bincode::serde::encode_to_vec(&value, config).unwrap(); 3 // Must decode with the SAME config: 4 let (decoded, _len): (MyType, usize) = 5 bincode::serde::decode_from_slice(&bytes, config).unwrap(); ``` This is also why bincode is best for Rust-to-Rust links you control end to end, not as a public interchange format. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Match the format to the job.** Human-edited config → TOML (or YAML if your platform expects it). Public/browser-facing APIs → JSON. Bandwidth-sensitive service-to-service traffic → MessagePack. Rust-only caches, snapshots, or IPC where you own both ends → bincode. Tabular exports for spreadsheets → CSV. * **Use `serde_norway`, not `serde_yaml`.** The latter is deprecated; the former is the maintained drop-in replacement with the same API. * **Prefer `to_vec_named` for MessagePack across boundaries.** The few extra bytes buy field-name interoperability and immunity to field-reordering bugs. Reserve the compact `to_vec` for internal, version-locked links. * **Pin bincode to 2.x with the `serde` feature.** That is the established, maintained release line for Serde integration (`cargo add bincode@2 --features serde`). Store the `config` value once and reuse it for both encode and decode. * **Keep CSV records flat.** Use scalar fields only. For optional columns, prefer `Option<T>` plus the `csv` reader’s flexible handling, and lean on Serde attributes like `#[serde(rename)]` to match header names — see [Serde Attributes](/15-serialization/05-attributes/). * **Read from bytes/readers for large inputs.** Text crates offer `from_reader`/`to_writer` and the binary crates work directly on `&[u8]`; streaming avoids buffering a whole file as a `String`. Performance trade-offs (borrowing, zero-copy, buffer reuse) are covered in [Serde Performance](/15-serialization/08-performance/). * **Let the same struct serve every format.** Define your data types once and switch formats at the call site. Resist duplicating types per format; that defeats Serde’s central advantage. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A common production need is a config loader that accepts the same settings as JSON, TOML, or YAML and picks the parser by file extension, so ops can write `config.yaml` while a test fixture uses `config.json`, all loading into one typed struct. This complete `src/main.rs` writes the config in three formats, loads each back, and returns a typed error for an unsupported extension: ```rust 1 use serde::{Deserialize, Serialize}; 2 use std::fs; 3 use std::path::Path; 4 5 #[derive(Debug, Serialize, Deserialize, PartialEq)] 6 struct AppConfig { 7 service_name: String, 8 port: u16, 9 log_level: String, 10 features: Vec<String>, 11 } 12 13 #[derive(Debug)] 14 enum ConfigError { 15 Io(std::io::Error), 16 UnknownFormat(String), 17 Parse(String), 18 } 19 20 impl std::fmt::Display for ConfigError { 21 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { 22 match self { 23 ConfigError::Io(e) => write!(f, "io error: {e}"), 24 ConfigError::UnknownFormat(ext) => write!(f, "unsupported config extension: .{ext}"), 25 ConfigError::Parse(msg) => write!(f, "parse error: {msg}"), 26 } 27 } 28 } 29 impl std::error::Error for ConfigError {} 30 impl From<std::io::Error> for ConfigError { 31 fn from(e: std::io::Error) -> Self { 32 ConfigError::Io(e) 33 } 34 } 35 36 /// Load a config file, choosing the parser from its extension. 37 fn load_config(path: &Path) -> Result<AppConfig, ConfigError> { 38 let text = fs::read_to_string(path)?; 39 let ext = path 40 .extension() 41 .and_then(|e| e.to_str()) 42 .unwrap_or("") 43 .to_lowercase(); 44 45 match ext.as_str() { 46 "json" => serde_json::from_str(&text).map_err(|e| ConfigError::Parse(e.to_string())), 47 "toml" => toml::from_str(&text).map_err(|e| ConfigError::Parse(e.to_string())), 48 "yaml" | "yml" => { 49 serde_norway::from_str(&text).map_err(|e| ConfigError::Parse(e.to_string())) 50 } 51 other => Err(ConfigError::UnknownFormat(other.to_string())), 52 } 53 } 54 55 fn main() -> Result<(), Box<dyn std::error::Error>> { 56 let dir = std::env::temp_dir(); 57 let default = AppConfig { 58 service_name: "billing".into(), 59 port: 9000, 60 log_level: "info".into(), 61 features: vec!["metrics".into(), "tracing".into()], 62 }; 63 64 // Write the SAME config in three formats from one struct. 65 let json_path = dir.join("cfg.json"); 66 let toml_path = dir.join("cfg.toml"); 67 let yaml_path = dir.join("cfg.yaml"); 68 fs::write(&json_path, serde_json::to_string_pretty(&default)?)?; 69 fs::write(&toml_path, toml::to_string(&default)?)?; 70 fs::write(&yaml_path, serde_norway::to_string(&default)?)?; 71 72 // Load each back -- all yield an identical, fully-typed AppConfig. 73 for path in [&json_path, &toml_path, &yaml_path] { 74 let loaded = load_config(path)?; 75 println!( 76 "{:<4} -> service={} port={} (matches default: {})", 77 path.extension().unwrap().to_str().unwrap(), 78 loaded.service_name, 79 loaded.port, 80 loaded == default 81 ); 82 } 83 84 // An unsupported extension is a clean typed error, not a panic. 85 let bad = dir.join("cfg.ini"); 86 fs::write(&bad, "x=1")?; 87 if let Err(e) = load_config(&bad) { 88 println!("expected failure: {e}"); 89 } 90 91 for p in [json_path, toml_path, yaml_path, bad] { 92 fs::remove_file(p).ok(); 93 } 94 Ok(()) 95 } ``` Real output from `cargo run`: ```text 1 json -> service=billing port=9000 (matches default: true) 2 toml -> service=billing port=9000 (matches default: true) 3 yaml -> service=billing port=9000 (matches default: true) 4 expected failure: unsupported config extension: .ini ``` One `AppConfig` type, three text formats, and a single `load_config` that dispatches on the extension. Each parser converts its own error into the unified `ConfigError`, so the `?` operator in `load_config` flows file-I/O and parse failures through one channel — and an unknown extension produces a descriptive, typed error instead of a crash. The struct definition is the only schema; the format is just a detail at the edge. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [TOML format spec](https://toml.io/) and the [`toml` crate docs](https://docs.rs/toml/): the format Rust itself uses for `Cargo.toml`. * [`serde_norway` crate docs](https://docs.rs/serde_norway/): maintained YAML support (the successor to the deprecated `serde_yaml`). * [`rmp-serde` crate docs](https://docs.rs/rmp-serde/): MessagePack via Serde, including `to_vec` vs `to_vec_named`. * [`bincode` crate docs](https://docs.rs/bincode/): Rust-native binary format; see `config` and the `serde` module. * [`csv` crate docs](https://docs.rs/csv/) and [the csv crate tutorial](https://docs.rs/csv/latest/csv/tutorial/index.html): reading and writing tabular data with Serde. * [Serde data formats list](https://serde.rs/#data-formats): every format crate that plugs into Serde. * [Serde](/15-serialization/00-serde-intro/): the data-model architecture that decouples types from formats. * [Serde Basics](/15-serialization/01-serde-basics/): the `to_string` / `from_str` round-trip with JSON. * [Structs and JSON](/15-serialization/03-json/): mapping nested structs, `Vec`, `HashMap`, `Option`, and enums. * [Serde Attributes](/15-serialization/05-attributes/): `rename`, `default`, `flatten`, and other attributes that also apply to these formats. * [Serde Performance](/15-serialization/08-performance/): borrowing, zero-copy, streaming, and buffer reuse across formats. * [Section 01: Getting Started](/01-getting-started/) — `cargo new`, `cargo add`, project layout. * [Section 02: Basics](/02-basics/) — the scalar and collection types these structs are built from. * [Section 16: Web APIs](/16-web-apis/) — where these serialized payloads meet HTTP request and response bodies. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: One struct, five formats [Section titled “Exercise 1: One struct, five formats”](#exercise-1-one-struct-five-formats) **Difficulty:** Easy **Objective:** Confirm a single type round-trips correctly through four formats. **Instructions:** In a fresh project (`cargo new`, then add `serde --features derive`, `serde_json`, `toml`, `serde_norway`, and `rmp-serde`), define `Point { x: i32, y: i32, label: String }` deriving `Serialize`, `Deserialize`, `Debug`, and `PartialEq`. Serialize one `Point` to JSON, TOML, YAML, and MessagePack (use `to_vec_named` for MessagePack), deserialize each back, and `assert!` that all four parsed values equal the original. ```rust 1 use serde::{Deserialize, Serialize}; 2 3 // TODO: derive Serialize, Deserialize, Debug, PartialEq 4 struct Point { 5 x: i32, 6 y: i32, 7 label: String, 8 } 9 10 fn main() -> Result<(), Box<dyn std::error::Error>> { 11 let p = Point { x: 3, y: -7, label: "origin-ish".into() }; 12 // TODO: round-trip through JSON, TOML, YAML, MessagePack and assert equality 13 Ok(()) 14 } ``` Solution ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize, PartialEq)] 4 struct Point { 5 x: i32, 6 y: i32, 7 label: String, 8 } 9 10 fn main() -> Result<(), Box<dyn std::error::Error>> { 11 let p = Point { 12 x: 3, 13 y: -7, 14 label: "origin-ish".into(), 15 }; 16 17 let from_json: Point = serde_json::from_str(&serde_json::to_string(&p)?)?; 18 let from_toml: Point = toml::from_str(&toml::to_string(&p)?)?; 19 let from_yaml: Point = serde_norway::from_str(&serde_norway::to_string(&p)?)?; 20 let from_mp: Point = rmp_serde::from_slice(&rmp_serde::to_vec_named(&p)?)?; 21 22 assert_eq!(from_json, p); 23 assert_eq!(from_toml, p); 24 assert_eq!(from_yaml, p); 25 assert_eq!(from_mp, p); 26 27 println!("all four formats round-tripped equal"); 28 Ok(()) 29 } ``` Real output from `cargo run`: ```text 1 all four formats round-tripped equal ``` The `Box<dyn std::error::Error>` return type lets the different error types from each format crate flow through the same `?`. `PartialEq` is what makes the four `assert_eq!` calls compile and pass. ### Exercise 2: Parse a TOML config with a nested table [Section titled “Exercise 2: Parse a TOML config with a nested table”](#exercise-2-parse-a-toml-config-with-a-nested-table) **Difficulty:** Medium **Objective:** Read a real-world-shaped TOML config that includes a `[table]` section, then re-serialize it. **Instructions:** Define `Server { host: String, port: u16 }` and `Settings { title: String, server: Server }` (derive `Serialize`, `Deserialize`, `Debug`). Parse the TOML literal below into a `Settings`, print the host and port, then serialize it back to TOML and print the result. Observe how the nested struct becomes a `[server]` table. ```rust 1 use serde::{Deserialize, Serialize}; 2 3 // TODO: define Server and Settings with the right derives 4 5 fn main() -> Result<(), Box<dyn std::error::Error>> { 6 let toml_in = r#" 7 title = "prod" 8 9 [server] 10 host = "0.0.0.0" 11 port = 8080 12 "#; 13 // TODO: parse into Settings, print host:port, re-serialize to TOML 14 Ok(()) 15 } ``` Solution ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Debug, Serialize, Deserialize)] 4 struct Server { 5 host: String, 6 port: u16, 7 } 8 9 #[derive(Debug, Serialize, Deserialize)] 10 struct Settings { 11 title: String, 12 server: Server, 13 } 14 15 fn main() -> Result<(), Box<dyn std::error::Error>> { 16 let toml_in = r#" 17 title = "prod" 18 19 [server] 20 host = "0.0.0.0" 21 port = 8080 22 "#; 23 24 let settings: Settings = toml::from_str(toml_in)?; 25 println!( 26 "{} -> {}:{}", 27 settings.title, settings.server.host, settings.server.port 28 ); 29 30 let back = toml::to_string(&settings)?; 31 println!("reserialized:\n{back}"); 32 Ok(()) 33 } ``` Real output from `cargo run`: ```text 1 prod -> 0.0.0.0:8080 2 reserialized: 3 title = "prod" 4 5 [server] 6 host = "0.0.0.0" 7 port = 8080 ``` The nested `Server` struct maps to TOML’s `[server]` table both ways. Notice that the scalar `title` is emitted before the table — the `toml` crate orders output so that all top-level keys precede any tables, which is required by the TOML grammar. ### Exercise 3: Summarize a CSV file [Section titled “Exercise 3: Summarize a CSV file”](#exercise-3-summarize-a-csv-file) **Difficulty:** Medium **Objective:** Deserialize CSV rows into typed records and compute a summary. **Instructions:** Define `Sale { product: String, units: u32, revenue: f64 }` deriving `Deserialize` and `Debug`. Using `csv::Reader::from_reader`, deserialize the CSV string below into `Sale` records, then print the total revenue and the single product with the highest revenue. Each row deserializes into a fully-typed `Sale`, no manual string-to-number parsing. ```rust 1 use serde::Deserialize; 2 3 // TODO: define Sale with derive(Deserialize, Debug) 4 5 fn main() -> Result<(), Box<dyn std::error::Error>> { 6 let csv_in = "\ 7 product,units,revenue 8 widget,120,2400.0 9 gadget,80,3200.0 10 gizmo,45,900.0 11 "; 12 // TODO: deserialize rows, print total revenue and the top product 13 Ok(()) 14 } ``` Solution ```rust 1 use serde::Deserialize; 2 3 #[derive(Debug, Deserialize)] 4 struct Sale { 5 product: String, 6 units: u32, 7 revenue: f64, 8 } 9 10 fn main() -> Result<(), Box<dyn std::error::Error>> { 11 let csv_in = "\ 12 product,units,revenue 13 widget,120,2400.0 14 gadget,80,3200.0 15 gizmo,45,900.0 16 "; 17 18 let mut rdr = csv::Reader::from_reader(csv_in.as_bytes()); 19 let mut total = 0.0; 20 let mut best: Option<(String, f64)> = None; 21 22 for record in rdr.deserialize() { 23 let sale: Sale = record?; 24 total += sale.revenue; 25 if best.as_ref().map_or(true, |(_, r)| sale.revenue > *r) { 26 best = Some((sale.product.clone(), sale.revenue)); 27 } 28 let _ = sale.units; // available if you want a per-unit figure 29 } 30 31 let (top_product, top_revenue) = best.expect("at least one row"); 32 println!("total revenue = {total}"); 33 println!("top product = {top_product} ({top_revenue})"); 34 Ok(()) 35 } ``` Real output from `cargo run`: ```text 1 total revenue = 6500 2 top product = gadget (3200) ``` `csv::Reader` reads the header row to map columns to the `Sale` fields by name, and each `record?` yields a typed `Sale` with `units` already parsed as `u32` and `revenue` as `f64`. The `map_or(true, ...)` keeps the first row as the initial “best” and then updates it whenever a higher-revenue row appears. # Custom Serialization: Hand-Written `Serialize` / `Deserialize` > When wire format and your type diverge, hand-write Serialize/Deserialize, retarget a field with serialize_with, or mirror foreign types via remote derive. Most of the time `#[derive(Serialize, Deserialize)]` is all you need: the field names and shapes you write in Rust become the JSON you get out. But sometimes the wire format and your in-memory type are *deliberately different*: a color stored as three bytes but exchanged as `"#1a2b3c"`, money kept as integer cents but sent as `"49.99"`, or a type from a third-party crate that does not implement Serde at all. This page covers the three escape hatches for those cases: hand-writing the `Serialize`/`Deserialize` traits, retargeting a single field with `serialize_with`/`deserialize_with`, and `#[serde(remote = "...")]` for foreign types. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) * **What it is:** Three levels of control over how a value maps to its serialized form, from “swap the codec for one field” up to “write the whole trait by hand.” * **Why it matters to a TypeScript/JavaScript developer:** This is the disciplined, compile-checked version of JavaScript’s `toJSON()` method and the `JSON.parse` *reviver* callback: the tools you reach for when the JSON shape and the object shape diverge. * **The mental shift:** In JavaScript, custom (de)serialization is a runtime callback that can return anything. In Rust it is a *trait implementation* the compiler verifies, and it stays **format-agnostic**: the same custom code drives JSON, YAML, MessagePack, and every other Serde format. > **Note:** Reach for these tools only when the derive (covered in [Deriving `Serialize` and `Deserialize`](/15-serialization/02-derive-serialize/)) and the field attributes in [Serde Attributes](/15-serialization/05-attributes/) genuinely cannot express what you need. The `#[serde(with = ...)]`, `rename`, `default`, and `skip_serializing_if` attributes solve the common cases without any hand-written code. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) JavaScript gives you two runtime hooks for custom (de)serialization. On the way *out*, an object’s `toJSON()` method controls what `JSON.stringify` emits. On the way *in*, a **reviver** callback passed to `JSON.parse` can rebuild rich objects from primitive JSON: ```typescript 1 // Custom serialization in TypeScript/JavaScript: toJSON + a reviver 2 class Color { 3 constructor(public r: number, public g: number, public b: number) {} 4 5 // Called automatically by JSON.stringify. We emit a hex string, 6 // not the { r, g, b } object. 7 toJSON(): string { 8 const h = (n: number) => n.toString(16).padStart(2, "0"); 9 return `#${h(this.r)}${h(this.g)}${h(this.b)}`; 10 } 11 } 12 13 const c = new Color(26, 43, 60); 14 console.log(JSON.stringify({ accent: c })); 15 // {"accent":"#1a2b3c"} 16 17 // On the way back, a reviver reconstructs the Color from the hex string. 18 const parsed = JSON.parse('{"accent":"#1a2b3c"}', (key, value) => { 19 if (key === "accent" && typeof value === "string" && value.startsWith("#")) { 20 const r = parseInt(value.slice(1, 3), 16); 21 const g = parseInt(value.slice(3, 5), 16); 22 const b = parseInt(value.slice(5, 7), 16); 23 return new Color(r, g, b); 24 } 25 return value; 26 }); 27 28 console.log(parsed.accent instanceof Color, parsed.accent); 29 // true Color { r: 26, g: 43, b: 60 } ``` This works, but notice the weaknesses Rust will close. `toJSON` is invoked by reflection on whatever object happens to be there — nothing checks its return type. The reviver is a stringly-typed `(key, value) => any` callback: you match keys by hand, the matching is easy to get subtly wrong, and a malformed `"#zz"` silently produces `NaN` channels rather than an error. There is also no symmetry: the encode logic lives in a class method and the decode logic lives in a separate callback, and nothing guarantees they agree. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) In Rust you implement the `Serialize` and `Deserialize` traits directly. The two impls sit next to each other, both are type-checked, and a bad input becomes a real, recoverable error instead of a silent `NaN`: ```rust 1 // Cargo.toml: 2 // [dependencies] 3 // serde = { version = "1", features = ["derive"] } 4 // serde_json = "1" 5 use serde::de::{self, Deserialize, Deserializer, Visitor}; 6 use serde::ser::{Serialize, Serializer}; 7 use std::fmt; 8 9 struct Color { 10 r: u8, 11 g: u8, 12 b: u8, 13 } 14 15 // Encode: RGB -> "#rrggbb". We talk to an abstract `Serializer`, not to JSON. 16 impl Serialize for Color { 17 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> 18 where 19 S: Serializer, 20 { 21 let hex = format!("#{:02x}{:02x}{:02x}", self.r, self.g, self.b); 22 serializer.serialize_str(&hex) 23 } 24 } 25 26 // Decode: "#rrggbb" -> RGB, via a Visitor (Serde's pull-based callback). 27 impl<'de> Deserialize<'de> for Color { 28 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> 29 where 30 D: Deserializer<'de>, 31 { 32 struct ColorVisitor; 33 34 impl<'de> Visitor<'de> for ColorVisitor { 35 type Value = Color; 36 37 fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result { 38 f.write_str("a hex color string like \"#1a2b3c\"") 39 } 40 41 fn visit_str<E>(self, value: &str) -> Result<Color, E> 42 where 43 E: de::Error, 44 { 45 let s = value 46 .strip_prefix('#') 47 .ok_or_else(|| E::custom(format!("missing leading '#' in {value:?}")))?; 48 if s.len() != 6 { 49 return Err(E::custom(format!("expected 6 hex digits, got {}", s.len()))); 50 } 51 let parse = |range: std::ops::Range<usize>| { 52 u8::from_str_radix(&s[range], 16) 53 .map_err(|e| E::custom(format!("invalid hex: {e}"))) 54 }; 55 Ok(Color { 56 r: parse(0..2)?, 57 g: parse(2..4)?, 58 b: parse(4..6)?, 59 }) 60 } 61 } 62 63 deserializer.deserialize_str(ColorVisitor) 64 } 65 } 66 67 fn main() { 68 let c = Color { r: 26, g: 43, b: 60 }; 69 let json = serde_json::to_string(&c).unwrap(); 70 println!("serialized: {json}"); 71 72 let back: Color = serde_json::from_str(&json).unwrap(); 73 println!("deserialized: r={} g={} b={}", back.r, back.g, back.b); 74 75 // Bad inputs are real errors, not silent NaN. 76 let bad: Result<Color, _> = serde_json::from_str(r#""1a2b3c""#); 77 println!("bad input -> {:?}", bad.err().map(|e| e.to_string())); 78 79 let bad2: Result<Color, _> = serde_json::from_str(r##""#zzzzzz""##); 80 println!("bad hex -> {:?}", bad2.err().map(|e| e.to_string())); 81 } ``` Real output: ```text 1 serialized: "#1a2b3c" 2 deserialized: r=26 g=43 b=60 3 bad input -> Some("missing leading '#' in \"1a2b3c\" at line 1 column 8") 4 bad hex -> Some("invalid hex: invalid digit found in string at line 1 column 9") ``` The hex shape, the `#` prefix, and the digit-count check are all enforced on the way in. The closest JavaScript reviver would have happily returned a `Color` with `NaN` channels. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The `Serialize` trait [Section titled “The Serialize trait”](#the-serialize-trait) `Serialize` has exactly one method: ```rust 1 // From the serde crate (shown for reference). 2 pub trait Serialize { 3 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> 4 where 5 S: Serializer; 6 } ``` `serializer` is a value implementing the `Serializer` trait: `serde_json` provides one, `serde_yaml` another, and so on. Your job is to call methods on it describing your data: `serialize_str`, `serialize_u64`, `serialize_struct`, `serialize_seq`, and roughly two dozen more (one per type in the [Serde data model](https://serde.rs/data-model.html)). You never mention JSON; the `Serializer` decides what bytes those calls produce. That is why one hand-written `Serialize` impl works for *every* format — the same indirection the derive relies on (see [Serde](/15-serialization/00-serde-intro/) for the data-model architecture). In the `Color` example, the entire encode is a single `serialize_str` call, because the *external* form is just a string. Internally `Color` is three `u8`s; externally it is one string. That asymmetry is the whole reason to hand-write it. ### The `Deserialize` trait and the Visitor pattern [Section titled “The Deserialize trait and the Visitor pattern”](#the-deserialize-trait-and-the-visitor-pattern) Deserialization is the harder direction, and the reason is structural. A `Serializer` is *push-based*: you hand it values. A `Deserializer` is *pull-based and format-driven*: it reads tokens from the input and calls **you** back. That callback target is the `Visitor` trait. The flow in the `Color` example: 1. `deserialize` calls `deserializer.deserialize_str(ColorVisitor)`. This is a **hint**: “I expect a string; here is who to call when you have one.” 2. The deserializer (for JSON) reads a string token and calls `visitor.visit_str(self, "#1a2b3c")`. 3. `visit_str` does the parsing and either returns a `Color` or returns `E::custom(...)` for a bad input. A `Visitor` can implement many `visit_*` methods (`visit_str`, `visit_u64`, `visit_map`, `visit_seq`, …). You only implement the ones you accept; the default for the rest is “produce a type error.” The `expecting` method supplies the human-readable description that appears in those error messages. > **Tip:** The lifetime `'de` is the lifetime of the data being borrowed *from* the input. You almost always just write `impl<'de> Deserialize<'de>` and `impl<'de> Visitor<'de>` verbatim and move on; it only becomes interesting for zero-copy borrowing, which [Serde Performance](/15-serialization/08-performance/) covers. ### Why a string `Visitor` is simpler than a struct one [Section titled “Why a string Visitor is simpler than a struct one”](#why-a-string-visitor-is-simpler-than-a-struct-one) The `Color` decode only handles `visit_str`. When your external form is a JSON *object* with several keys, you instead implement `visit_map`, walk the keys with `map.next_key()` / `map.next_value()`, and assemble the fields yourself. Here is that fuller pattern — a `Rectangle` that emits a *computed* `area` field on the way out (which the derive cannot do) and ignores it on the way in: ```rust 1 // Cargo.toml: 2 // [dependencies] 3 // serde = { version = "1", features = ["derive"] } 4 // serde_json = "1" 5 use serde::de::{self, Deserializer, MapAccess, Visitor}; 6 use serde::ser::{Serialize, SerializeStruct, Serializer}; 7 use serde::Deserialize; 8 use std::fmt; 9 10 #[derive(Debug)] 11 struct Rectangle { 12 width: f64, 13 height: f64, 14 } 15 16 impl Serialize for Rectangle { 17 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> 18 where 19 S: Serializer, 20 { 21 // Announce a struct with THREE fields, including a computed one. 22 let mut s = serializer.serialize_struct("Rectangle", 3)?; 23 s.serialize_field("w", &self.width)?; 24 s.serialize_field("h", &self.height)?; 25 s.serialize_field("area", &(self.width * self.height))?; 26 s.end() 27 } 28 } 29 30 impl<'de> Deserialize<'de> for Rectangle { 31 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> 32 where 33 D: Deserializer<'de>, 34 { 35 // A small derived enum gives us validated, fast key matching. 36 #[derive(Deserialize)] 37 #[serde(field_identifier, rename_all = "lowercase")] 38 enum Field { 39 W, 40 H, 41 Area, // accepted on input but ignored (it is computed) 42 } 43 44 struct RectVisitor; 45 46 impl<'de> Visitor<'de> for RectVisitor { 47 type Value = Rectangle; 48 49 fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result { 50 f.write_str("a rectangle object with `w` and `h`") 51 } 52 53 fn visit_map<M>(self, mut map: M) -> Result<Rectangle, M::Error> 54 where 55 M: MapAccess<'de>, 56 { 57 let mut width = None; 58 let mut height = None; 59 while let Some(key) = map.next_key()? { 60 match key { 61 Field::W => { 62 if width.is_some() { 63 return Err(de::Error::duplicate_field("w")); 64 } 65 width = Some(map.next_value()?); 66 } 67 Field::H => { 68 if height.is_some() { 69 return Err(de::Error::duplicate_field("h")); 70 } 71 height = Some(map.next_value()?); 72 } 73 Field::Area => { 74 let _: f64 = map.next_value()?; // read and discard 75 } 76 } 77 } 78 let width = width.ok_or_else(|| de::Error::missing_field("w"))?; 79 let height = height.ok_or_else(|| de::Error::missing_field("h"))?; 80 Ok(Rectangle { width, height }) 81 } 82 } 83 84 const FIELDS: &[&str] = &["w", "h", "area"]; 85 deserializer.deserialize_struct("Rectangle", FIELDS, RectVisitor) 86 } 87 } 88 89 fn main() { 90 let r = Rectangle { width: 3.0, height: 4.0 }; 91 let json = serde_json::to_string(&r).unwrap(); 92 println!("{json}"); 93 94 let back: Rectangle = serde_json::from_str(&json).unwrap(); 95 println!("{back:?}"); 96 97 let bad: Result<Rectangle, _> = serde_json::from_str(r#"{"w":3.0}"#); 98 println!("{:?}", bad.err().map(|e| e.to_string())); 99 } ``` Real output: ```text 1 {"w":3.0,"h":4.0,"area":12.0} 2 Rectangle { width: 3.0, height: 4.0 } 3 Some("missing field `h` at line 1 column 9") ``` This is exactly what `#[derive(Deserialize)]` generates internally; the derive writes this visitor for you. Seeing it once explains *why* deserialization “just works” with fields in any order and reports precise missing-field errors: there is a state machine doing it. ### `serialize_with` / `deserialize_with`: customize one field, keep the derive [Section titled “serialize\_with / deserialize\_with: customize one field, keep the derive”](#serialize_with--deserialize_with-customize-one-field-keep-the-derive) Hand-writing the full traits for a whole struct just to special-case one field is overkill. The `serialize_with` and `deserialize_with` attributes let you keep `#[derive(Serialize, Deserialize)]` on the struct and point a single field at standalone functions. Those functions have the *same signatures* as the trait methods, but they are free functions, not impls: ```rust 1 // Cargo.toml: 2 // [dependencies] 3 // serde = { version = "1", features = ["derive"] } 4 // serde_json = "1" 5 use serde::{Deserialize, Deserializer, Serialize, Serializer}; 6 7 // Stored as seconds; exchanged as milliseconds. 8 fn serialize_epoch_millis<S>(secs: &u64, serializer: S) -> Result<S::Ok, S::Error> 9 where 10 S: Serializer, 11 { 12 serializer.serialize_u64(secs * 1000) 13 } 14 15 fn deserialize_epoch_millis<'de, D>(deserializer: D) -> Result<u64, D::Error> 16 where 17 D: Deserializer<'de>, 18 { 19 let millis = u64::deserialize(deserializer)?; 20 Ok(millis / 1000) 21 } 22 23 // Stored as Vec<String>; exchanged as one comma-separated string. 24 fn serialize_csv<S>(tags: &[String], serializer: S) -> Result<S::Ok, S::Error> 25 where 26 S: Serializer, 27 { 28 serializer.serialize_str(&tags.join(",")) 29 } 30 31 fn deserialize_csv<'de, D>(deserializer: D) -> Result<Vec<String>, D::Error> 32 where 33 D: Deserializer<'de>, 34 { 35 let s = String::deserialize(deserializer)?; 36 if s.is_empty() { 37 return Ok(Vec::new()); 38 } 39 Ok(s.split(',').map(|t| t.trim().to_string()).collect()) 40 } 41 42 #[derive(Debug, Serialize, Deserialize)] 43 struct Event { 44 name: String, 45 #[serde( 46 serialize_with = "serialize_epoch_millis", 47 deserialize_with = "deserialize_epoch_millis" 48 )] 49 timestamp_secs: u64, 50 #[serde(serialize_with = "serialize_csv", deserialize_with = "deserialize_csv")] 51 tags: Vec<String>, 52 } 53 54 fn main() { 55 let ev = Event { 56 name: "login".into(), 57 timestamp_secs: 1_700_000_000, 58 tags: vec!["auth".into(), "web".into()], 59 }; 60 61 let json = serde_json::to_string_pretty(&ev).unwrap(); 62 println!("{json}"); 63 64 let wire = r#"{"name":"logout","timestamp_secs":1700000123000,"tags":"auth,mobile"}"#; 65 let back: Event = serde_json::from_str(wire).unwrap(); 66 println!("{back:?}"); 67 } ``` Real output: ```text 1 { 2 "name": "login", 3 "timestamp_secs": 1700000000000, 4 "tags": "auth,web" 5 } 6 Event { name: "logout", timestamp_secs: 1700000123, tags: ["auth", "mobile"] } ``` A few mechanics worth internalizing: * The `serialize_with` function takes `&T` (a reference to the field), the `deserialize_with` function returns `Result<T, _>` (the field’s type). The compiler enforces both. * The argument is a string *path* to a function, e.g. `"serialize_epoch_millis"` or `"crate::codecs::serialize_csv"`. It is resolved at macro-expansion time, so a typo is a real “cannot find function” error, not a runtime miss. * If you have *both* directions and they belong together, group them in a module with `serialize`/`deserialize` functions and use the single `#[serde(with = "module_path")]` attribute instead. That is the form the Real-World Example below uses, and the same form documented in [Serde Attributes](/15-serialization/05-attributes/). ### `#[serde(remote = "...")]`: serializing a foreign type [Section titled “#\[serde(remote = "...")\]: serializing a foreign type”](#serderemote---serializing-a-foreign-type) The hardest case is a type you do not own and cannot annotate: Rust’s **orphan rule** (see [section 09](/09-generics-traits/12-orphan-rule/)) forbids implementing `Serialize` for a type from another crate. Serde’s answer is **remote derive**: you declare a *local mirror* struct with identical fields, tie it to the foreign type with `#[serde(remote = "...")]`, and Serde generates the impls, but emits them as associated functions on your mirror, which you then attach to fields with `#[serde(with = "...")]`: ```rust 1 // Cargo.toml: 2 // [dependencies] 3 // serde = { version = "1", features = ["derive"] } 4 // serde_json = "1" 5 use serde::{Deserialize, Serialize}; 6 7 // Pretend this comes from a third-party crate we cannot edit; it has NO 8 // Serde derives. (In real code this would be `other_crate::Duration`.) 9 mod other_crate { 10 #[derive(Debug)] 11 pub struct Duration { 12 pub secs: u64, 13 pub nanos: u32, 14 } 15 16 impl Duration { 17 pub fn new(secs: u64, nanos: u32) -> Self { 18 Duration { secs, nanos } 19 } 20 } 21 } 22 23 use other_crate::Duration; 24 25 // A local mirror with the SAME fields, tied to the remote type. 26 // Serde generates Serialize/Deserialize *for Duration* from this definition. 27 #[derive(Serialize, Deserialize)] 28 #[serde(remote = "Duration")] 29 struct DurationDef { 30 secs: u64, 31 nanos: u32, 32 } 33 34 #[derive(Serialize, Deserialize, Debug)] 35 struct Timer { 36 label: String, 37 // Route this field through the generated remote impl. 38 #[serde(with = "DurationDef")] 39 interval: Duration, 40 } 41 42 fn main() { 43 let timer = Timer { 44 label: "heartbeat".into(), 45 interval: Duration::new(30, 500_000), 46 }; 47 48 let json = serde_json::to_string(&timer).unwrap(); 49 println!("{json}"); 50 51 let back: Timer = serde_json::from_str(&json).unwrap(); 52 println!("{back:?}"); 53 } ``` Real output: ```text 1 {"label":"heartbeat","interval":{"secs":30,"nanos":500000}} 2 Timer { label: "heartbeat", interval: Duration { secs: 30, nanos: 500000 } } ``` The mirror’s fields must match the remote type’s fields (name and type) so the generated code can construct it. If the remote type has private fields, you supply a `#[serde(getter = "...")]` for serialization and the remote type must expose a constructor or `From` for deserialization. This is the mechanism crates like `chrono` use under the hood, though in practice you should prefer a crate’s own `serde` feature (e.g. `chrono = { version = "0.4", features = ["serde"] }`) over rolling your own mirror; see [Beyond JSON](/15-serialization/06-other-formats/) and the ecosystem note in Best Practices. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | TypeScript / JavaScript | Rust + Serde | | ---------------------- | ------------------------------------------------------ | ------------------------------------------------------------- | | Encode hook | `toJSON()` method, invoked by reflection | `Serialize` trait impl, resolved at compile time | | Decode hook | `JSON.parse` reviver, a `(key, value) => any` callback | `Deserialize` trait + a `Visitor` state machine | | Type checking | None — `toJSON` may return anything | Return types enforced by the compiler | | Bad input | Often silent (`NaN`, `undefined`) | A real `Result::Err` with a precise message | | Format coupling | Tied to JSON specifically | Format-agnostic; same impl drives every format | | One-field tweak | Re-implement `toJSON` for the whole object | `#[serde(serialize_with/deserialize_with/with)]` on one field | | Foreign types | Patch the prototype, or wrap | `#[serde(remote = "...")]` mirror struct | | Encode/decode symmetry | Two unrelated places (method vs. callback) | Two traits, conventionally written side by side | ### Why Rust splits it into traits and a Visitor [Section titled “Why Rust splits it into traits and a Visitor”](#why-rust-splits-it-into-traits-and-a-visitor) JavaScript can afford a single `(key, value) => any` reviver because everything is dynamically typed and the JSON parser already produced generic objects. Rust has no runtime reflection and monomorphizes generics away, so the parser cannot “just build an object”: it does not know the target shape. The `Visitor` is how the *type* tells the *format* what tokens it can accept, decoupling the two so that any `Deserializer` (JSON, YAML, binary) can drive any `Deserialize` type. It is more ceremony than a reviver, but it is the ceremony that makes the result fast and type-safe. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Using a remote type on a field without `#[serde(with = ...)]` [Section titled “Pitfall 1: Using a remote type on a field without #\[serde(with = ...)\]”](#pitfall-1-using-a-remote-type-on-a-field-without-serdewith--) Declaring the `#[serde(remote = "...")]` mirror is only half the job: it generates functions, it does **not** implement the trait *for* the remote type. You must still route each field through it. Forgetting that yields the standard “trait not implemented” error: ```rust 1 use serde::{Deserialize, Serialize}; 2 3 mod other_crate { 4 #[derive(Debug)] 5 pub struct Duration { 6 pub secs: u64, 7 pub nanos: u32, 8 } 9 } 10 use other_crate::Duration; 11 12 #[derive(Serialize, Deserialize)] 13 #[serde(remote = "Duration")] 14 struct DurationDef { 15 secs: u64, 16 nanos: u32, 17 } 18 19 #[derive(Serialize, Deserialize, Debug)] // does not compile (error0277) 20 struct Timer { 21 label: String, 22 interval: Duration, // forgot #[serde(with = "DurationDef")] 23 } 24 25 fn main() { 26 let _ = Timer { label: "x".into(), interval: Duration { secs: 1, nanos: 0 } }; 27 } ``` The real compiler error (`cargo build`): ```text 1 error[E0277]: the trait bound `other_crate::Duration: serde::Serialize` is not satisfied 2 --> src/main.rs:19:10 3 | 4 19 | #[derive(Serialize, Deserialize, Debug)] 5 | ^^^^^^^^^ the trait `Serialize` is not implemented for `other_crate::Duration` 6 ... 7 22 | interval: Duration, // forgot #[serde(with = "DurationDef")] 8 | -------- required by a bound introduced by this call 9 | 10 = note: for local types consider adding `#[derive(serde::Serialize)]` to your `other_crate::Duration` type 11 = note: for types from other crates check whether the crate offers a `serde` feature flag ``` **Fix:** add `#[serde(with = "DurationDef")]` to the `interval` field. The compiler note’s second line is also the better long-term advice: check whether the crate has a `serde` feature before writing a mirror at all. ### Pitfall 2: A `serialize_with` / `deserialize_with` function with the wrong signature [Section titled “Pitfall 2: A serialize\_with / deserialize\_with function with the wrong signature”](#pitfall-2-a-serialize_with--deserialize_with-function-with-the-wrong-signature) The attribute points at a string path, so a wrong *signature* is not caught until the macro-generated call site tries to use it. The two signatures are easy to confuse — `serialize_with` takes `&T`, `deserialize_with` returns `Result<T, _>`. Passing the field by value to `serialize_with`, returning the wrong type, or mixing up `Serializer`/`Deserializer` all produce mismatch errors at compile time. Copy a known-good pair (like the ones above) and edit the body; do not hand-type the generic bounds from memory. > **Warning:** The function path is a string, so a *misspelled* name like `"serialize_epoc_millis"` produces a “cannot find function” error pointing at the `#[derive]` line, not the field; read past the derive to find the real cause. ### Pitfall 3: Mismatched field count in `serialize_struct` [Section titled “Pitfall 3: Mismatched field count in serialize\_struct”](#pitfall-3-mismatched-field-count-in-serialize_struct) `serializer.serialize_struct("Name", N)?` declares that exactly `N` fields follow. The count is an optimization hint that some formats (notably binary ones and `serde_json`’s map machinery) rely on. If you pass `2` but call `serialize_field` three times — or vice versa — formats that pre-allocate by the count can misbehave or panic. Always make the number match the number of `serialize_field` calls. The same applies to `serialize_seq(Some(len))` and `serialize_map(Some(len))`; pass `None` if you genuinely do not know the length up front. ### Pitfall 4: Forgetting `visit_str` (or implementing the wrong `visit_*`) [Section titled “Pitfall 4: Forgetting visit\_str (or implementing the wrong visit\_\*)”](#pitfall-4-forgetting-visit_str-or-implementing-the-wrong-visit_) A `Visitor` only handles the `visit_*` methods you implement; every other input type falls through to a default that returns a type error. If your `deserialize` method hints `deserialize_str` but you implemented `visit_string` instead of `visit_str` (or omitted it entirely), valid input is rejected with an “invalid type” error. Match the `visit_*` method to the token the deserializer will actually produce: JSON strings arrive at `visit_str`, JSON numbers at `visit_u64`/`visit_i64`/`visit_f64`, JSON objects at `visit_map`, arrays at `visit_seq`. ### Pitfall 5: Trying to implement Serde traits on a foreign type directly [Section titled “Pitfall 5: Trying to implement Serde traits on a foreign type directly”](#pitfall-5-trying-to-implement-serde-traits-on-a-foreign-type-directly) The instinct from other languages is to write `impl Serialize for chrono::DateTime<Utc>`. Rust’s orphan rule rejects this: you may implement a trait for a type only if you own the trait *or* the type. The error is `E0117` (“only traits defined in the current crate can be implemented for types defined outside of the crate”). Remote derive exists precisely to work around this without violating the rule: the impl is generated for *your* mirror, and the `with` attribute wires it in. See [section 09’s orphan rule page](/09-generics-traits/12-orphan-rule/) for the underlying reasoning. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Prefer attributes over hand-written traits.** `#[serde(with = ...)]`, `rename`, `default`, and `skip_serializing_if` (in [Serde Attributes](/15-serialization/05-attributes/)) cover most divergence between wire and memory. Hand-write the full trait only when no attribute fits. * **Prefer a crate’s `serde` feature over remote derive.** Before mirroring a foreign type, check for a feature flag: `uuid = { version = "1", features = ["serde"] }`, `chrono = { version = "0.4", features = ["serde"] }`, `rust_decimal = { version = "1", features = ["serde"] }`. Remote derive is the fallback for crates that offer none. * **Group a `with` pair into a module.** When a field needs both custom directions, put `serialize` and `deserialize` functions in a module and use `#[serde(with = "module")]` once, rather than two separate attributes. It keeps the encode/decode logic provably adjacent. * **Always return `E::custom(...)` for bad input, never `panic!` or `unwrap`.** Deserialization is a fallible boundary; a hand-written `Deserialize` that panics turns malformed input into a crash. Return a descriptive error so the caller can handle it. * **Write a round-trip test.** The single most valuable test for custom (de)serialization is `assert_eq!(value, from_str(&to_string(&value)))`. It catches encode/decode drift immediately. See [section 13](/13-testing/). * **Keep `serialize_with`/`deserialize_with` functions pure and small.** They run inside the serializer; doing I/O or allocating heavily there is a smell. Transform data only. * **Make `expecting` describe the *accepted* form, not the type name.** “a hex color string like `#1a2b3c`” produces far better error messages than “a Color”. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A payment record exchanged with an external API. Three divergences from a naive derive: money is stored as integer **cents** (never floats — JavaScript’s IEEE-754 `number` famously loses precision on money) but exchanged as a `"49.99"` decimal string; the upstream service sends statuses in `SCREAMING_SNAKE_CASE`; and the money codec lives in a reusable module wired in with a single `#[serde(with = "money")]`. ```rust 1 // Cargo.toml: 2 // [dependencies] 3 // serde = { version = "1", features = ["derive"] } 4 // serde_json = "1" 5 use serde::de::Error as DeError; 6 use serde::{Deserialize, Deserializer, Serialize, Serializer}; 7 8 // A reusable codec module: cents <-> "NN.cc" decimal string. 9 mod money { 10 use super::*; 11 12 pub fn serialize<S>(cents: &i64, serializer: S) -> Result<S::Ok, S::Error> 13 where 14 S: Serializer, 15 { 16 let sign = if *cents < 0 { "-" } else { "" }; 17 let abs = cents.unsigned_abs(); 18 let formatted = format!("{sign}{}.{:02}", abs / 100, abs % 100); 19 serializer.serialize_str(&formatted) 20 } 21 22 pub fn deserialize<'de, D>(deserializer: D) -> Result<i64, D::Error> 23 where 24 D: Deserializer<'de>, 25 { 26 let s = String::deserialize(deserializer)?; 27 let (sign, digits) = match s.strip_prefix('-') { 28 Some(rest) => (-1, rest), 29 None => (1, s.as_str()), 30 }; 31 let (whole, frac) = digits.split_once('.').unwrap_or((digits, "0")); 32 let whole: i64 = whole.parse().map_err(D::Error::custom)?; 33 let frac_padded = format!("{frac:0<2}"); 34 let cents: i64 = frac_padded[..2].parse().map_err(D::Error::custom)?; 35 Ok(sign * (whole * 100 + cents)) 36 } 37 } 38 39 #[derive(Debug, Serialize, Deserialize)] 40 #[serde(rename_all = "SCREAMING_SNAKE_CASE")] 41 enum PaymentStatus { 42 Pending, 43 Settled, 44 Refunded, 45 } 46 47 #[derive(Debug, Serialize, Deserialize)] 48 struct Payment { 49 id: String, 50 #[serde(with = "money")] 51 amount_cents: i64, 52 currency: String, 53 status: PaymentStatus, 54 } 55 56 fn main() { 57 let payment = Payment { 58 id: "pay_88".into(), 59 amount_cents: 4999, 60 currency: "USD".into(), 61 status: PaymentStatus::Settled, 62 }; 63 64 let json = serde_json::to_string_pretty(&payment).unwrap(); 65 println!("{json}"); 66 67 // Parse an inbound payload from the upstream service. 68 let wire = r#"{"id":"pay_99","amount_cents":"12.05","currency":"EUR","status":"REFUNDED"}"#; 69 let parsed: Payment = serde_json::from_str(wire).unwrap(); 70 println!("{parsed:?}"); 71 println!("stored cents = {}", parsed.amount_cents); 72 } ``` Real output: ```text 1 { 2 "id": "pay_88", 3 "amount_cents": "49.99", 4 "currency": "USD", 5 "status": "SETTLED" 6 } 7 Payment { id: "pay_99", amount_cents: 1205, currency: "EUR", status: Refunded } 8 stored cents = 1205 ``` Internally `amount_cents` is always an exact integer — arithmetic on it cannot lose a penny — while the wire stays in the decimal string the external API expects. The `money` module is reusable across every type that carries money, and the `#[serde(rename_all = "SCREAMING_SNAKE_CASE")]` attribute handles the status casing without any custom code. This `Payment` is the kind of type a web handler would accept and return; see how typed payloads flow through HTTP in [section 16](/16-web-apis/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [Implementing `Serialize`](https://serde.rs/impl-serialize.html): the official walkthrough of hand-writing the trait. * [Implementing `Deserialize`](https://serde.rs/impl-deserialize.html): visitors, `MapAccess`/`SeqAccess`, and the field-identifier pattern. * [Custom date format with `serialize_with` / `deserialize_with`](https://serde.rs/custom-date-format.html): the canonical `with`-module example. * [Deriving `De/Serialize` for remote crate types](https://serde.rs/remote-derive.html): the full rules for `#[serde(remote = "...")]`, including `getter`. * [`serde::de::Visitor`](https://docs.rs/serde/latest/serde/de/trait.Visitor.html) and [`serde::Serializer`](https://docs.rs/serde/latest/serde/trait.Serializer.html): the method-by-method API reference. * This guide: * [Serde](/15-serialization/00-serde-intro/) — the trait architecture and the data model these impls target. * [Deriving `Serialize` and `Deserialize`](/15-serialization/02-derive-serialize/) — what `#[derive(...)]` generates (this page is the manual version). * [Serde Attributes](/15-serialization/05-attributes/) — `with`, `rename`, `default`, and the attributes that avoid hand-written code. * [Structs and JSON](/15-serialization/03-json/) — struct/enum-to-JSON shapes you may need to reproduce by hand. * [Beyond JSON](/15-serialization/06-other-formats/) — why a format-agnostic impl works for TOML, YAML, and MessagePack. * [Serde Performance](/15-serialization/08-performance/) — zero-copy `Visitor`s and `#[serde(borrow)]`. * [Section 09: Generics & Traits](/09-generics-traits/) and the [orphan rule](/09-generics-traits/12-orphan-rule/) — why remote derive exists. * [Section 13: Testing](/13-testing/) — round-trip tests for custom codecs. * [Section 16: Web APIs](/16-web-apis/) — typed payloads across HTTP. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A custom `Serialize` for a newtype [Section titled “Exercise 1: A custom Serialize for a newtype”](#exercise-1-a-custom-serialize-for-a-newtype) **Difficulty:** Easy **Objective:** Hand-write the `Serialize` trait for a type whose external form differs from its internal one. **Instructions:** 1. Define a tuple struct `Percentage(u8)`. 2. Implement `Serialize` so a `Percentage(75)` serializes to the JSON string `"75%"` (with a literal percent sign), not the number `75`. 3. In `main`, serialize `Percentage(75)` and print the result. ```rust 1 use serde::ser::{Serialize, Serializer}; 2 3 struct Percentage(u8); 4 5 impl Serialize for Percentage { 6 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> 7 where 8 S: Serializer, 9 { 10 // TODO: serialize as the string "75%" 11 todo!() 12 } 13 } 14 15 fn main() { 16 // TODO: serialize Percentage(75) and print it 17 } ``` Solution ```rust 1 use serde::ser::{Serialize, Serializer}; 2 3 struct Percentage(u8); 4 5 impl Serialize for Percentage { 6 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> 7 where 8 S: Serializer, 9 { 10 serializer.serialize_str(&format!("{}%", self.0)) 11 } 12 } 13 14 fn main() { 15 let p = Percentage(75); 16 println!("{}", serde_json::to_string(&p).unwrap()); 17 // "75%" 18 } ``` Real output: ```text 1 "75%" ``` ### Exercise 2: A lenient `deserialize_with` [Section titled “Exercise 2: A lenient deserialize\_with”](#exercise-2-a-lenient-deserialize_with) **Difficulty:** Medium **Objective:** Use `deserialize_with` to accept input in more than one shape: the kind of leniency real-world APIs demand. **Instructions:** 1. Write a free function `flexible_bool` suitable for `#[serde(deserialize_with = "...")]` that accepts either a real JSON boolean *or* a string. The strings `"yes"`, `"true"`, `"1"` mean `true`; `"no"`, `"false"`, `"0"` mean `false` (case-insensitive). Anything else is an error. 2. Put it on a `Settings { dark_mode: bool }` struct. 3. In `main`, deserialize `{"dark_mode":true}`, `{"dark_mode":"yes"}`, and `{"dark_mode":"NO"}`, then show that `{"dark_mode":"maybe"}` produces an error. > **Tip:** A small `#[serde(untagged)]` enum is the cleanest way to accept “a bool *or* a string.” Solution ```rust 1 use serde::de::Error; 2 use serde::{Deserialize, Deserializer}; 3 4 fn flexible_bool<'de, D>(deserializer: D) -> Result<bool, D::Error> 5 where 6 D: Deserializer<'de>, 7 { 8 #[derive(Deserialize)] 9 #[serde(untagged)] 10 enum BoolOrString { 11 Bool(bool), 12 Str(String), 13 } 14 15 match BoolOrString::deserialize(deserializer)? { 16 BoolOrString::Bool(b) => Ok(b), 17 BoolOrString::Str(s) => match s.to_lowercase().as_str() { 18 "yes" | "true" | "1" => Ok(true), 19 "no" | "false" | "0" => Ok(false), 20 other => Err(D::Error::custom(format!("not a boolean: {other:?}"))), 21 }, 22 } 23 } 24 25 #[derive(Debug, Deserialize)] 26 struct Settings { 27 #[serde(deserialize_with = "flexible_bool")] 28 dark_mode: bool, 29 } 30 31 fn main() { 32 for input in [ 33 r#"{"dark_mode":true}"#, 34 r#"{"dark_mode":"yes"}"#, 35 r#"{"dark_mode":"NO"}"#, 36 ] { 37 let s: Settings = serde_json::from_str(input).unwrap(); 38 println!("{input} -> {s:?}"); 39 } 40 let bad: Result<Settings, _> = serde_json::from_str(r#"{"dark_mode":"maybe"}"#); 41 println!("{:?}", bad.err().map(|e| e.to_string())); 42 } ``` Real output: ```text 1 {"dark_mode":true} -> Settings { dark_mode: true } 2 {"dark_mode":"yes"} -> Settings { dark_mode: true } 3 {"dark_mode":"NO"} -> Settings { dark_mode: false } 4 Some("not a boolean: \"maybe\" at line 1 column 21") ``` ### Exercise 3: A full round-tripping `Serialize` + `Deserialize` [Section titled “Exercise 3: A full round-tripping Serialize + Deserialize”](#exercise-3-a-full-round-tripping-serialize--deserialize) **Difficulty:** Hard **Objective:** Implement *both* traits by hand for a type that serializes as a single string and validates strictly on the way back. **Instructions:** 1. Define `struct Version { major: u16, minor: u16, patch: u16 }` deriving `Debug` and `PartialEq`. 2. Implement `Serialize` so it produces the string `"MAJOR.MINOR.PATCH"` (e.g. `"1.4.2"`). 3. Implement `Deserialize` with a `Visitor` whose `visit_str` parses exactly three dot-separated `u16`s. Reject too-few components, non-numeric components, *and* too-many components, each with a descriptive `E::custom` error. 4. In `main`, round-trip a `Version`, `assert_eq!` it survives, and show that `"1.x"` fails with a useful message. Solution ```rust 1 use serde::de::{self, Deserialize, Deserializer, Visitor}; 2 use serde::ser::{Serialize, Serializer}; 3 use std::fmt; 4 5 #[derive(Debug, PartialEq)] 6 struct Version { 7 major: u16, 8 minor: u16, 9 patch: u16, 10 } 11 12 impl Serialize for Version { 13 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> 14 where 15 S: Serializer, 16 { 17 serializer.serialize_str(&format!("{}.{}.{}", self.major, self.minor, self.patch)) 18 } 19 } 20 21 impl<'de> Deserialize<'de> for Version { 22 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> 23 where 24 D: Deserializer<'de>, 25 { 26 struct VersionVisitor; 27 28 impl<'de> Visitor<'de> for VersionVisitor { 29 type Value = Version; 30 31 fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result { 32 f.write_str(r#"a version string like "1.4.2""#) 33 } 34 35 fn visit_str<E>(self, v: &str) -> Result<Version, E> 36 where 37 E: de::Error, 38 { 39 let mut parts = v.split('.'); 40 let mut next = |name: &str| -> Result<u16, E> { 41 parts 42 .next() 43 .ok_or_else(|| E::custom(format!("missing {name}")))? 44 .parse() 45 .map_err(|e| E::custom(format!("bad {name}: {e}"))) 46 }; 47 let major = next("major")?; 48 let minor = next("minor")?; 49 let patch = next("patch")?; 50 if parts.next().is_some() { 51 return Err(E::custom("too many version components")); 52 } 53 Ok(Version { major, minor, patch }) 54 } 55 } 56 57 deserializer.deserialize_str(VersionVisitor) 58 } 59 } 60 61 fn main() { 62 let v = Version { major: 1, minor: 4, patch: 2 }; 63 let json = serde_json::to_string(&v).unwrap(); 64 println!("{json}"); 65 66 let back: Version = serde_json::from_str(&json).unwrap(); 67 println!("{back:?}"); 68 assert_eq!(v, back); 69 70 let bad: Result<Version, _> = serde_json::from_str(r#""1.x""#); 71 println!("{:?}", bad.err().map(|e| e.to_string())); 72 } ``` Real output: ```text 1 "1.4.2" 2 Version { major: 1, minor: 4, patch: 2 } 3 Some("bad minor: invalid digit found in string at line 1 column 5") ``` # Serde Performance: Borrowing, Zero-Copy, Streaming, and Buffer Reuse > JSON.parse always copies every byte into a new tree; Serde lets you borrow with &str, stream values lazily, skip serde_json::Value, and reuse buffers on hot paths. In JavaScript, `JSON.parse` is a black box: it always builds a brand-new tree of objects and strings, copying every byte of input into the heap, and you have no levers to pull. Serde gives you those levers. By choosing the right field types and APIs you can parse JSON that **borrows** directly from the input buffer (zero string copies), **stream** millions of records without ever holding them all in memory, and **reuse** a single allocation across an entire workload. This page is about spending Serde’s flexibility where it pays off. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Serde’s default path (derive `Deserialize`, parse into a struct full of `String`s and `Vec`s) is already fast and is the right default for almost everything. The performance toolkit on top of that is: **borrowed deserialization** (`&str` / `#[serde(borrow)]` so string fields point *into* the input instead of being copied), **streaming** (`from_reader` and `StreamDeserializer` so you process one value at a time), **avoiding `serde_json::Value`** (parse straight into typed structs instead of building a dynamic tree), and **buffer reuse** (`clear()` + `to_writer` into a kept-capacity buffer). For a TypeScript developer the mental shift is that the *shape of your types* is itself a performance decision. There is no single fixed parse like `JSON.parse`. > **Note:** Reach for these techniques only when a profiler points here. Borrowing and streaming add lifetime and structural constraints; the typed `String`-field path is the correct starting point. Optimize the hot loop, not the config-file load that runs once at startup. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Here is a typical Node.js hot path: reading a large newline-delimited JSON (NDJSON) log file and summing a numeric field per category. This is the kind of code where, at scale, allocation pressure starts to dominate. ```typescript 1 import { createReadStream } from "node:fs"; 2 import { createInterface } from "node:readline"; 3 4 interface Sample { 5 metric: string; 6 value: number; 7 } 8 9 async function aggregate(path: string): Promise<Map<string, number>> { 10 const totals = new Map<string, number>(); 11 const rl = createInterface({ input: createReadStream(path) }); 12 13 for await (const line of rl) { 14 if (line.trim() === "") continue; 15 // JSON.parse builds a fresh object AND a fresh copy of the 16 // "metric" string for every single line — no way to avoid it. 17 const sample = JSON.parse(line) as Sample; 18 totals.set(sample.metric, (totals.get(sample.metric) ?? 0) + sample.value); 19 } 20 return totals; 21 } ``` Two costs are unavoidable in this JavaScript version. First, `JSON.parse` allocates a new object plus a fresh `string` for `metric` on every line, even though we only need it briefly to look up a map key. Second, the `as Sample` cast is a compile-time fiction — a malformed line is not caught here, it surfaces as `NaN` or `undefined` somewhere downstream. Rust lets you eliminate the first cost and closes the second by construction. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The Rust version borrows the `metric` string straight out of the line buffer (no per-record string allocation), reuses one `String` for reading lines, and never builds an intermediate dynamic tree. The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically. ```bash 1 cargo new ndjson_agg 2 cd ndjson_agg 3 cargo add serde --features derive 4 cargo add serde_json ``` ```rust 1 use serde::Deserialize; 2 use std::collections::HashMap; 3 use std::io::{BufRead, BufReader, Cursor}; 4 5 // Borrowed: `metric` points INTO the line buffer. No per-record String 6 // allocation for the metric name — Serde hands back a slice of the input. 7 #[derive(Debug, Deserialize)] 8 struct Sample<'a> { 9 metric: &'a str, 10 value: f64, 11 } 12 13 // Process a JSON Lines stream, reusing a single line buffer across all 14 // records and never building a serde_json::Value. 15 fn aggregate<R: BufRead>(mut reader: R) -> std::io::Result<HashMap<String, f64>> { 16 let mut totals: HashMap<String, f64> = HashMap::new(); 17 let mut line = String::new(); 18 19 loop { 20 line.clear(); // reuse the allocation; keeps capacity 21 let n = reader.read_line(&mut line)?; 22 if n == 0 { 23 break; // EOF 24 } 25 let trimmed = line.trim(); 26 if trimmed.is_empty() { 27 continue; 28 } 29 // Borrowed deserialize straight out of `line`. 30 let sample: Sample = match serde_json::from_str(trimmed) { 31 Ok(s) => s, 32 Err(e) => { 33 eprintln!("skipping bad line: {e}"); 34 continue; 35 } 36 }; 37 // We only need an owned key when inserting a NEW entry into the map. 38 *totals.entry(sample.metric.to_owned()).or_insert(0.0) += sample.value; 39 } 40 41 Ok(totals) 42 } 43 44 fn main() -> std::io::Result<()> { 45 let input = "\ 46 {\"metric\":\"requests\",\"value\":12.0} 47 {\"metric\":\"errors\",\"value\":1.0} 48 {\"metric\":\"requests\",\"value\":8.0} 49 {\"metric\":\"errors\",\"value\":2.0} 50 "; 51 let reader = BufReader::new(Cursor::new(input)); 52 let mut totals = aggregate(reader)?; 53 54 // Sort for deterministic output. 55 let mut sorted: Vec<_> = totals.drain().collect(); 56 sorted.sort_by(|a, b| a.0.cmp(&b.0)); 57 for (metric, total) in sorted { 58 println!("{metric}: {total}"); 59 } 60 Ok(()) 61 } ``` Real output from `cargo run`: ```text 1 errors: 3 2 requests: 20 ``` The `Sample<'a>` struct’s `metric: &'a str` is the key move: during parsing, Serde points that field at the bytes already sitting in `line`, instead of allocating and copying a new `String`. The only allocation per record happens when a *new* category appears in the map. Everything else — the line buffer, the parse — reuses memory you already have. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) Let’s unpack each performance lever in the Rust version and contrast it with what JavaScript forces on you. ### Borrowed deserialization (`&str`) [Section titled “Borrowed deserialization (\&str)”](#borrowed-deserialization-str) When you declare a field as `&'a str` instead of `String`, you are telling Serde: *do not copy this string; hand me a slice that points into the input.* This is **zero-copy** deserialization. Compare the two struct definitions: ```rust 1 use serde::Deserialize; 2 3 // Owning: every string field is a fresh heap allocation + memcpy. 4 #[derive(Deserialize)] 5 struct Owned { 6 level: String, 7 message: String, 8 } 9 10 // Borrowing: string fields are slices into the parsed input. No copies. 11 #[derive(Deserialize)] 12 struct Borrowed<'a> { 13 level: &'a str, 14 message: &'a str, 15 } 16 17 fn main() { 18 let data = r#"{"level":"error","message":"disk full"}"#; 19 let owned: Owned = serde_json::from_str(data).unwrap(); 20 let borrowed: Borrowed = serde_json::from_str(data).unwrap(); 21 println!("{} / {}", owned.message, borrowed.message); 22 } ``` The lifetime `'a` ties `Borrowed` to the buffer it was parsed from. The compiler enforces that the struct cannot outlive the input: there is no such thing as a dangling slice in safe Rust. JavaScript has no equivalent: `JSON.parse` always materializes fresh, fully-owned strings, and the GC cleans them up later. Rust’s borrow is the price-free option *when the input outlives the parsed value*, and a compile error otherwise (we hit that error in [Common Pitfalls](#common-pitfalls)). This is the deserialization counterpart of the broader ownership story; if `&str` versus `String` is still fuzzy, see [Section 05: Ownership](/05-ownership/). ### When a borrow can’t happen: escapes and `Cow` [Section titled “When a borrow can’t happen: escapes and Cow”](#when-a-borrow-cant-happen-escapes-and-cow) A `&str` field can only borrow if the string appears **verbatim** in the input. JSON allows escapes (`\n`, `\"`, `\uXXXX`), and the *unescaped* bytes do not exist contiguously in the source; Serde would have to allocate to produce them. A plain `&str` field therefore **fails at runtime** on an escaped string. The escape-tolerant choice is `Cow<'a, str>` (“clone on write”): it borrows when it can and allocates only when it must. ```rust 1 use serde::Deserialize; 2 use std::borrow::Cow; 3 4 // `#[serde(borrow)]` tells the derive to generate a BORROWING impl for Cow. 5 // Without it, Cow always allocates (owns) — see Common Pitfalls. 6 #[derive(Debug, Deserialize)] 7 struct Message<'a> { 8 #[serde(borrow)] 9 text: Cow<'a, str>, 10 } 11 12 fn main() { 13 // No escapes: Cow borrows (zero-copy). 14 let plain = r#"{"text":"hello world"}"#; 15 let m1: Message = serde_json::from_str(plain).unwrap(); 16 println!("{:?} -> borrowed = {}", m1.text, matches!(m1.text, Cow::Borrowed(_))); 17 18 // Contains an escape: Cow must own a freshly-unescaped String. 19 let escaped = r#"{"text":"line1\nline2"}"#; 20 let m2: Message = serde_json::from_str(escaped).unwrap(); 21 println!("{:?} -> borrowed = {}", m2.text, matches!(m2.text, Cow::Borrowed(_))); 22 } ``` Real output from `cargo run`: ```text 1 "hello world" -> borrowed = true 2 "line1\nline2" -> borrowed = false ``` `Cow<'a, str>` is the pragmatic default for borrowed string fields when you cannot guarantee escape-free input: the common (no-escape) case stays zero-copy, and the rare escaped case still works correctly. ### `#[serde(borrow)]` [Section titled “#\[serde(borrow)\]”](#serdeborrow) The derive macro auto-detects the borrow for a plain `&'a str` field. For `Cow<'a, str>`, it does **not** — it defaults to the owning implementation unless you opt in with `#[serde(borrow)]`. That single attribute switches the generated code to the borrowing variant. The other place you need it explicitly is when a borrowed lifetime is buried inside your own generic wrapper types where the derive cannot infer the intent. ### Streaming with `from_reader` and `StreamDeserializer` [Section titled “Streaming with from\_reader and StreamDeserializer”](#streaming-with-from_reader-and-streamdeserializer) `serde_json::from_str` parses one value from a fully-loaded string. For a multi-gigabyte file or a network socket you do not want the whole thing in memory. `Deserializer::from_reader(...).into_iter::<T>()` gives you a `StreamDeserializer`: an iterator that pulls one JSON value at a time from any `Read` source. ```rust 1 use serde::Deserialize; 2 use std::io::Cursor; 3 4 #[derive(Debug, Deserialize)] 5 struct Event { 6 id: u32, 7 kind: String, 8 } 9 10 fn main() { 11 // Whitespace-separated JSON values (JSON Lines style). The stream 12 // reader processes them one at a time — no Vec<Event>, no big String. 13 let ndjson = r#" 14 {"id":1,"kind":"click"} 15 {"id":2,"kind":"scroll"} 16 {"id":3,"kind":"close"} 17 "#; 18 19 let reader = Cursor::new(ndjson); 20 let stream = serde_json::Deserializer::from_reader(reader).into_iter::<Event>(); 21 22 let mut count = 0u32; 23 for event in stream { 24 let event = event.unwrap(); 25 count += 1; 26 println!("event #{count}: id={} kind={}", event.id, event.kind); 27 } 28 println!("processed {count} events"); 29 } ``` Real output from `cargo run`: ```text 1 event #1: id=1 kind=click 2 event #2: id=2 kind=scroll 3 event #3: id=3 kind=close ``` Memory use stays flat regardless of input size, because only one `Event` exists at a time. The catch (which trips up newcomers) is that `from_reader` **cannot borrow** from its input (the reader owns its buffer transiently), so streamed types must be fully owned (`String`, not `&str`). We show that exact compiler error in [Common Pitfalls](#common-pitfalls). ### Avoiding `serde_json::Value` [Section titled “Avoiding serde\_json::Value”](#avoiding-serde_jsonvalue) `serde_json::Value` is the dynamic, JavaScript-object-like representation: an enum tree where every object key is a heap `String`, every nested array/object is its own allocation, and numbers are stored generically. It is the right tool when the shape is genuinely unknown ([Dynamic JSON with `serde_json::Value`](/15-serialization/04-json-manipulation/)), but on a hot path it is the slow option because you pay to build the *entire* tree even if you read one field. ```rust 1 use serde::Deserialize; 2 use serde_json::Value; 3 4 #[derive(Debug, Deserialize)] 5 struct User { 6 id: u64, 7 name: String, 8 } 9 10 fn main() { 11 let data = r#"{"id":42,"name":"Ada","extra":{"nested":[1,2,3]},"flag":true}"#; 12 13 // Approach A: parse into Value (dynamic). Builds the WHOLE tree — 14 // including `extra` and `flag` — allocating a String for every key. 15 let v: Value = serde_json::from_str(data).unwrap(); 16 println!("via Value: id={}, name={}", v["id"], v["name"].as_str().unwrap()); 17 18 // Approach B: parse into a typed struct. Serde skips `extra` and 19 // `flag` entirely and builds only the two fields you declared. 20 let user: User = serde_json::from_str(data).unwrap(); 21 println!("via struct: id={} name={}", user.id, user.name); 22 } ``` Real output from `cargo run`: ```text 1 via Value: id=42, name=Ada 2 via struct: id=42 name=Ada ``` Both print the same two values, but they do very different amounts of work. The typed parse ignores `extra` and `flag` and allocates nothing for them, while the `Value` parse builds and allocates the full nested tree: a `String` for every key, a boxed variant for every value. If you only need a couple of fields, a minimal struct with just those fields (unknown fields are ignored by default) is dramatically cheaper than `Value`. ### Buffer reuse on the serialize side [Section titled “Buffer reuse on the serialize side”](#buffer-reuse-on-the-serialize-side) `serde_json::to_string` allocates a fresh `String` every call. In a loop that serializes many values, reuse one buffer instead: `to_writer` appends into any `Write` target, and `Vec::clear()` drops the contents while **keeping the capacity**. ```rust 1 use serde::Serialize; 2 3 #[derive(Serialize)] 4 struct Metric { 5 name: &'static str, 6 value: f64, 7 } 8 9 fn main() { 10 let metrics = vec![ 11 Metric { name: "cpu", value: 0.42 }, 12 Metric { name: "mem", value: 0.71 }, 13 Metric { name: "disk", value: 0.13 }, 14 ]; 15 16 // ONE byte buffer reused for every record. After the first iteration 17 // no further allocation happens — clear() keeps the capacity. 18 let mut buf: Vec<u8> = Vec::new(); 19 20 for m in &metrics { 21 buf.clear(); 22 serde_json::to_writer(&mut buf, m).unwrap(); 23 // The buffer holds UTF-8 JSON bytes; view them as &str to print. 24 println!("{}", std::str::from_utf8(&buf).unwrap()); 25 } 26 27 println!("final buffer capacity = {}", buf.capacity()); 28 } ``` Real output from `cargo run`: ```text 1 {"name":"cpu","value":0.42} 2 {"name":"mem","value":0.71} 3 {"name":"disk","value":0.13} 4 final buffer capacity = 32 ``` The buffer was allocated once and held its 32-byte capacity through all three serializations. JavaScript gives you no control here: `JSON.stringify` always returns a brand-new string and the GC reclaims the old ones. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concern | TypeScript / JavaScript | Rust + Serde | | -------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------- | | String fields on parse | Always copied into new `string`s | `&str` borrows from input (zero-copy); `String` copies; `Cow` does both | | Who owns parsed strings | The GC; always heap, always owned | You choose: borrow the buffer or own a copy | | Streaming a huge file | Manual `readline` + per-line `JSON.parse` | `StreamDeserializer` iterates values lazily | | Dynamic vs typed | Always dynamic objects (`any`) | `Value` (dynamic, allocates tree) vs typed struct (skips unwanted fields) | | Reusing a serialize buffer | Impossible; `JSON.stringify` returns a fresh string | `to_writer` + `clear()` reuses one allocation | | Unwanted fields on parse | Materialized anyway, then ignored by you | Skipped by the parser; never allocated | | Safety of borrowing | N/A (everything copied) | Borrow checker guarantees no dangling slice, at compile time | Three points deserve emphasis for a TypeScript developer: * **There is no one “parse”.** `JSON.parse` is a single fixed operation. In Rust the *type you parse into* decides how much work happens. A struct with three `&str` fields and one with three `String` fields parse the same JSON very differently. * **Borrowing is checked, not hoped.** A borrowed parse result is tied by lifetime to its input buffer. If you try to keep it after the buffer is gone, the program does not compile. This is the opposite of the “use-after-free” class of bug: it is impossible by construction. * **Cheap-by-default skipping.** A typed struct ignores fields it does not declare *during parsing*, so a 50-field JSON payload from which you need two fields costs roughly two fields’ worth of work. The dynamic-everything `JSON.parse` model cannot do this. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Trying to borrow an escaped string into `&str` [Section titled “Trying to borrow an escaped string into \&str”](#trying-to-borrow-an-escaped-string-into-str) A `&str` field cannot hold an escaped string, because the unescaped bytes are not contiguous in the source. Serde reports this at **runtime** as a deserialization error: ```rust 1 use serde::Deserialize; 2 3 #[derive(Debug, Deserialize)] 4 struct Message<'a> { 5 text: &'a str, 6 } 7 8 fn main() { 9 let escaped = r#"{"text":"line1\nline2"}"#; // contains an escape 10 match serde_json::from_str::<Message>(escaped) { 11 Ok(m) => println!("ok: {}", m.text), 12 Err(e) => println!("error: {e}"), 13 } 14 } ``` Real output from `cargo run`: ```text 1 error: invalid type: string "line1\nline2", expected a borrowed string at line 1 column 22 ``` The fix is to use `Cow<'a, str>` with `#[serde(borrow)]` (borrows when possible, allocates on escapes) or fall back to an owned `String` if borrowing buys you nothing here. ### Returning a borrowed struct that outlives its buffer [Section titled “Returning a borrowed struct that outlives its buffer”](#returning-a-borrowed-struct-that-outlives-its-buffer) This is the classic lifetime error. A borrowed struct points into a buffer; if that buffer is a local that gets dropped, you cannot return the struct: ```rust 1 use serde::Deserialize; 2 3 #[derive(Debug, Deserialize)] 4 struct LogEntry<'a> { 5 level: &'a str, 6 message: &'a str, 7 } 8 9 fn parse_owned() -> LogEntry<'static> { 10 let data = String::from(r#"{"level":"info","message":"started"}"#); 11 let entry: LogEntry = serde_json::from_str(&data).unwrap(); 12 entry // does not compile (error[E0515]): returns a value referencing `data`, dropped here 13 } 14 15 fn main() { 16 let e = parse_owned(); 17 println!("{e:?}"); 18 } ``` The **real** compiler error: ```text 1 error[E0515]: cannot return value referencing local variable `data` 2 --> src/main.rs:12:5 3 | 4 11 | let entry: LogEntry = serde_json::from_str(&data).unwrap(); 5 | ----- `data` is borrowed here 6 12 | entry // does not compile (error[E0515]): returns a value referencing `data`, dropped here 7 | ^^^^^ returns a value referencing data owned by the current function 8 9 For more information about this error, try `rustc --explain E0515`. ``` The fix is to either keep the buffer alive in the caller and parse there, or use an owning struct (`String` fields) so the result does not depend on the buffer’s lifetime. Borrowing is for when the input genuinely outlives the parsed value (as in a request handler that holds the body for the duration of the handler). ### Expecting `from_reader` to borrow [Section titled “Expecting from\_reader to borrow”](#expecting-from_reader-to-borrow) `from_reader` and `StreamDeserializer` work over a transient internal buffer, so they can only produce **owned** types. Asking for a borrowed type is a compile error: ```rust 1 use serde::Deserialize; 2 use std::io::Cursor; 3 4 #[derive(Debug, Deserialize)] 5 struct Borrowed<'a> { 6 name: &'a str, 7 } 8 9 fn main() { 10 let reader = Cursor::new(r#"{"name":"x"}"#); 11 // does not compile: from_reader cannot produce borrowed data. 12 let b: Borrowed = serde_json::from_reader(reader).unwrap(); 13 println!("{b:?}"); 14 } ``` The **real** compiler error: ```text 1 error: implementation of `Deserialize` is not general enough 2 --> src/main.rs:12:23 3 | 4 12 | let b: Borrowed = serde_json::from_reader(reader).unwrap(); 5 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ implementation of `Deserialize` is not general enough 6 | 7 = note: `Borrowed<'_>` must implement `Deserialize<'0>`, for any lifetime `'0`... 8 = note: ...but `Borrowed<'_>` actually implements `Deserialize<'1>`, for some specific lifetime `'1` ``` The cryptic “not general enough” message is Serde’s way of saying the type only implements the *borrowing* `Deserialize<'de>`, but `from_reader` needs the *owning* `DeserializeOwned`. The fix: use `String` fields for streamed types, or, if you must borrow, read the whole input into a `String` first and use `from_str`. ### Forgetting `#[serde(borrow)]` on `Cow` [Section titled “Forgetting #\[serde(borrow)\] on Cow”](#forgetting-serdeborrow-on-cow) Without the attribute, the derive generates the **owning** implementation for a `Cow<'a, str>` field — it always allocates, silently defeating the point: ```rust 1 use serde::Deserialize; 2 use std::borrow::Cow; 3 4 #[derive(Debug, Deserialize)] 5 struct Doc<'a> { 6 body: Cow<'a, str>, // no #[serde(borrow)] -> always owns/allocates 7 } 8 9 fn main() { 10 let data = r#"{"body":"plain text no escapes"}"#; 11 let d: Doc = serde_json::from_str(data).unwrap(); 12 println!("borrowed = {}", matches!(d.body, Cow::Borrowed(_))); 13 } ``` Real output from `cargo run`: ```text 1 borrowed = false ``` It compiles and runs. It is just quietly slower than you intended (`borrowed = false` means it allocated). Adding `#[serde(borrow)]` flips that to `true` for escape-free input. This one bites because it is not an error; it is a silent missed optimization. (A plain `&'a str` field, by contrast, auto-borrows without the attribute.) ### Reaching for `Value` when a typed struct would do [Section titled “Reaching for Value when a typed struct would do”](#reaching-for-value-when-a-typed-struct-would-do) If you find yourself writing `let v: Value = from_str(...)?;` and then `v["a"]["b"].as_str()`, you are paying to build and allocate the whole tree, then indexing it dynamically (which also loses the compile-time type checks). A small typed struct with just the fields you need is faster *and* safer. Save `Value` for genuinely schema-less input; see [Dynamic JSON with `serde_json::Value`](/15-serialization/04-json-manipulation/) for when that is the right call. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Start with owned `String` fields; borrow only when profiling says so.** The owning path is simpler, has no lifetime constraints, and is plenty fast for the vast majority of code. Borrowing is a hot-loop optimization, not a default. * **Prefer `&str` for borrowed fields you control, `Cow<'a, str>` when escapes are possible.** Use `&str` when you can guarantee escape-free input (or are happy to error on escapes); use `Cow<'a, str>` with `#[serde(borrow)]` for the safe, escape-tolerant zero-copy path. * **Parse from `&[u8]` with `from_slice` to skip a `String` step.** When you already hold bytes (an HTTP body, a memory-mapped file), `serde_json::from_slice(&bytes)` borrows directly and avoids constructing an intermediate `String`. Borrowed `&str` fields can point straight into those bytes. * **Stream large or unbounded inputs.** Use `Deserializer::from_reader(BufReader::new(file)).into_iter::<T>()` for files or sockets so memory stays flat. Remember streamed types must be owned. * **Reuse buffers in serialize loops.** `to_writer(&mut buf, &value)` plus `buf.clear()` reuses one allocation across many records. For files and sockets, `to_writer(BufWriter::new(...), &value)` avoids an intermediate `String` entirely. * **Parse into the narrowest typed struct, not `Value`.** Declare only the fields you need; Serde skips the rest during parsing for free. Reserve `serde_json::Value` for dynamic, schema-unknown data. * **Pre-size buffers when the count is known.** `Vec::with_capacity(n)` / `String::with_capacity(n)` avoid reallocation churn when you can estimate the output size up front. * **Benchmark with `criterion`, do not guess.** Before and after any of these changes, measure. Serde’s defaults are well-tuned; confirm the optimization is real on your data and workload. See [Section 13: Testing](/13-testing/) for the testing and benchmarking toolchain. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored task: a metrics ingestion service receives a request body containing many NDJSON samples, parses each with a borrowed struct (zero string copies for the metric label), aggregates per-label totals, and serializes a compact summary back out — reusing a single output buffer. This is a complete, runnable `src/main.rs` using only `serde` (with `derive`) and `serde_json`. ```rust 1 use serde::{Deserialize, Serialize}; 2 use std::collections::BTreeMap; 3 use std::io::{BufRead, BufReader, Read}; 4 5 // Borrowed input: `label` is a slice into the line buffer, not a copy. 6 #[derive(Debug, Deserialize)] 7 struct Sample<'a> { 8 label: &'a str, 9 value: f64, 10 } 11 12 // Owned output: a summary we build and hand back. BTreeMap keeps keys 13 // sorted, which makes the serialized output deterministic. 14 #[derive(Debug, Serialize)] 15 struct Summary { 16 total_samples: u64, 17 sums: BTreeMap<String, f64>, 18 } 19 20 // Ingest a JSON Lines stream from any reader, reusing one line buffer and 21 // borrowing each record's label. Returns a typed Summary. 22 fn ingest<R: Read>(reader: R) -> std::io::Result<Summary> { 23 let mut reader = BufReader::new(reader); 24 let mut line = String::new(); 25 let mut sums: BTreeMap<String, f64> = BTreeMap::new(); 26 let mut total_samples = 0u64; 27 28 loop { 29 line.clear(); // reuse the allocation across all lines 30 if reader.read_line(&mut line)? == 0 { 31 break; // EOF 32 } 33 let trimmed = line.trim(); 34 if trimmed.is_empty() { 35 continue; 36 } 37 match serde_json::from_str::<Sample>(trimmed) { 38 Ok(sample) => { 39 total_samples += 1; 40 // Allocate an owned key only for a new label. 41 *sums.entry(sample.label.to_owned()).or_insert(0.0) += sample.value; 42 } 43 Err(e) => eprintln!("dropping malformed sample: {e}"), 44 } 45 } 46 47 Ok(Summary { total_samples, sums }) 48 } 49 50 fn main() -> Result<(), Box<dyn std::error::Error>> { 51 // Stand-in for an HTTP request body: raw bytes of NDJSON. 52 let body: &[u8] = b"\ 53 {\"label\":\"http_2xx\",\"value\":120.0} 54 {\"label\":\"http_5xx\",\"value\":3.0} 55 {\"label\":\"http_2xx\",\"value\":80.0} 56 {\"label\":\"bogus line, not json\"} 57 {\"label\":\"http_4xx\",\"value\":12.0} 58 "; 59 60 let summary = ingest(body)?; 61 62 // Serialize the response by reusing a single output buffer. 63 let mut out: Vec<u8> = Vec::with_capacity(256); 64 serde_json::to_writer(&mut out, &summary)?; 65 66 println!("response body: {}", std::str::from_utf8(&out)?); 67 println!("accepted {} valid samples", summary.total_samples); 68 Ok(()) 69 } ``` Real output from `cargo run`: ```text 1 dropping malformed sample: missing field `value` at line 1 column 32 2 response body: {"total_samples":4,"sums":{"http_2xx":200.0,"http_4xx":12.0,"http_5xx":3.0}} 3 accepted 4 valid samples ``` Notice the pipeline’s properties: input is read line-by-line into one reused buffer; each valid sample’s `label` is borrowed (no string copy) and only promoted to an owned `String` when it first appears as a map key; the malformed line is rejected at the parse boundary with a precise message rather than poisoning the totals; and the response is written into a pre-sized, reused byte buffer. None of these optimizations changed the readability of the code, and every one of them is checked by the compiler. In a real service this `ingest` function would sit behind an HTTP handler; see [Section 16: Web APIs](/16-web-apis/) for wiring serialized structs to request and response bodies. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [Serde: Understanding deserializer lifetimes](https://serde.rs/lifetimes.html): the authoritative explanation of `'de`, `#[serde(borrow)]`, and zero-copy. * [Serde: Streaming a sequence of values](https://docs.rs/serde_json/latest/serde_json/struct.StreamDeserializer.html): `StreamDeserializer` API. * [`serde_json` functions](https://docs.rs/serde_json/latest/serde_json/#functions) — `from_str`, `from_slice`, `from_reader`, `to_string`, `to_vec`, `to_writer` and when each fits. * [`std::borrow::Cow`](https://doc.rust-lang.org/std/borrow/enum.Cow.html): clone-on-write, the borrow/own hybrid. * [`DeserializeOwned`](https://docs.rs/serde/latest/serde/de/trait.DeserializeOwned.html): the owning bound that `from_reader` requires. * [Serde](/15-serialization/00-serde-intro/): the data-model architecture that makes borrowing and formats orthogonal. * [Dynamic JSON with `serde_json::Value`](/15-serialization/04-json-manipulation/) — `serde_json::Value` and the `json!` macro: when dynamic JSON is the right tool despite the cost. * [Structs and JSON](/15-serialization/03-json/): mapping structs, `Vec`, `HashMap`, `Option`, and enums to JSON. * [Custom Serialization](/15-serialization/07-custom-serialization/) — hand-written (de)serialization and `serialize_with` / `deserialize_with`. * [Beyond JSON](/15-serialization/06-other-formats/): binary formats (MessagePack, bincode) that are often the bigger performance win than tuning JSON. * [Section 05: Ownership](/05-ownership/) — `&str` vs `String`, borrowing, and lifetimes. * [Section 13: Testing](/13-testing/): benchmarking with `criterion` so you measure instead of guess. * [Section 16: Web APIs](/16-web-apis/): serialized structs as HTTP request and response bodies. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Convert an owning struct to a borrowing one [Section titled “Exercise 1: Convert an owning struct to a borrowing one”](#exercise-1-convert-an-owning-struct-to-a-borrowing-one) **Difficulty:** Easy **Objective:** Turn a `String`-based struct into a zero-copy borrowed struct and prove the borrow works. **Instructions:** Start from the owning `Token` below. Rewrite it to borrow its two string fields from the input (`&'a str` with a lifetime parameter), then write a function `first_token(src: &str) -> Token<'_>` that parses it. Parse the literal `{"kind":"ident","lexeme":"user_count"}` and print both fields. Confirm it compiles and runs. ```rust 1 use serde::Deserialize; 2 3 // TODO: make this borrow from the input instead of allocating two Strings. 4 #[derive(Debug, Deserialize)] 5 struct Token { 6 kind: String, 7 lexeme: String, 8 } 9 10 fn main() { 11 let src = r#"{"kind":"ident","lexeme":"user_count"}"#; 12 // TODO: parse `src` into a borrowing Token and print kind + lexeme. 13 } ``` Solution ```rust 1 use serde::Deserialize; 2 3 #[derive(Debug, Deserialize)] 4 struct Token<'a> { 5 kind: &'a str, 6 lexeme: &'a str, 7 } 8 9 fn first_token(src: &str) -> Token<'_> { 10 serde_json::from_str(src).unwrap() 11 } 12 13 fn main() { 14 let src = r#"{"kind":"ident","lexeme":"user_count"}"#; 15 let tok = first_token(src); 16 println!("{} = {:?}", tok.kind, tok.lexeme); 17 } ``` Real output from `cargo run`: ```text 1 ident = "user_count" ``` The `Token<'a>` lifetime ties the parsed struct to `src`. The `-> Token<'_>` return type lets the compiler infer that the returned token borrows from the `src` argument. No `String` is allocated; both fields are slices into `src`. ### Exercise 2: Stream-sum NDJSON without holding it all in memory [Section titled “Exercise 2: Stream-sum NDJSON without holding it all in memory”](#exercise-2-stream-sum-ndjson-without-holding-it-all-in-memory) **Difficulty:** Medium **Objective:** Use `StreamDeserializer` to sum a field across many JSON values without collecting them into a `Vec`. **Instructions:** Write `sum_totals<R: std::io::Read>(reader: R) -> Result<f64, serde_json::Error>` that reads a stream of `{"total": <number>}` objects and returns the sum of all `total` fields. Use `serde_json::Deserializer::from_reader(...).into_iter::<Order>()` and accumulate as you iterate — never build a `Vec<Order>`. Test it on `{"total":19.99}{"total":4.50}{"total":100.00}` (note: no separators needed, JSON values are self-delimiting). Remember that streamed types must be **owned**. ```rust 1 use serde::Deserialize; 2 use std::io::Cursor; 3 4 #[derive(Deserialize)] 5 struct Order { 6 total: f64, 7 } 8 9 // TODO: stream-sum the `total` fields without collecting into a Vec. 10 fn sum_totals<R: std::io::Read>(reader: R) -> Result<f64, serde_json::Error> { 11 todo!() 12 } 13 14 fn main() -> Result<(), serde_json::Error> { 15 let ndjson = r#"{"total":19.99}{"total":4.50}{"total":100.00}"#; 16 let sum = sum_totals(Cursor::new(ndjson))?; 17 println!("sum = {sum:.2}"); 18 Ok(()) 19 } ``` Solution ```rust 1 use serde::Deserialize; 2 use std::io::Cursor; 3 4 #[derive(Deserialize)] 5 struct Order { 6 total: f64, 7 } 8 9 fn sum_totals<R: std::io::Read>(reader: R) -> Result<f64, serde_json::Error> { 10 let stream = serde_json::Deserializer::from_reader(reader).into_iter::<Order>(); 11 let mut sum = 0.0; 12 for order in stream { 13 sum += order?.total; // `order` is Result<Order, _>; `?` propagates errors 14 } 15 Ok(sum) 16 } 17 18 fn main() -> Result<(), serde_json::Error> { 19 let ndjson = r#"{"total":19.99}{"total":4.50}{"total":100.00}"#; 20 let sum = sum_totals(Cursor::new(ndjson))?; 21 println!("sum = {sum:.2}"); 22 Ok(()) 23 } ``` Real output from `cargo run`: ```text 1 sum = 124.49 ``` The `StreamDeserializer` yields `Result<Order, _>` items, so `order?` both unwraps the value and propagates any parse error. Only one `Order` exists at a time — memory stays constant no matter how many records the reader holds. The fields are `f64` (owned), satisfying `from_reader`’s requirement that streamed types be owned. ### Exercise 3: Extract one field without building a `Value` tree [Section titled “Exercise 3: Extract one field without building a Value tree”](#exercise-3-extract-one-field-without-building-a-value-tree) **Difficulty:** Medium **Objective:** Pull a single field out of a large JSON payload using a minimal typed struct instead of `serde_json::Value`, relying on the fact that unknown fields are skipped during parsing. **Instructions:** Given a large JSON payload with many fields, you only need the top-level `version` number. Write `payload_version(json: &str) -> Result<u32, serde_json::Error>` that parses into a struct declaring *only* `version` (Serde ignores the rest at parse time — no full tree is built). Test it on the multi-field literal below and print the version. ```rust 1 use serde::Deserialize; 2 3 // TODO: declare a struct with ONLY the field you need. 4 5 fn payload_version(json: &str) -> Result<u32, serde_json::Error> { 6 todo!() 7 } 8 9 fn main() -> Result<(), serde_json::Error> { 10 let big = r#"{ 11 "version": 3, 12 "data": {"a": [1,2,3,4,5], "b": "lots of text here"}, 13 "signature": "deadbeef", 14 "nested": {"deep": {"deeper": {"x": true}}} 15 }"#; 16 println!("version = {}", payload_version(big)?); 17 Ok(()) 18 } ``` Solution ```rust 1 use serde::Deserialize; 2 3 // Only `version` is declared; `data`, `signature`, and `nested` are 4 // skipped by the parser — they are never allocated into a Value tree. 5 #[derive(Deserialize)] 6 struct VersionOnly { 7 version: u32, 8 } 9 10 fn payload_version(json: &str) -> Result<u32, serde_json::Error> { 11 let parsed: VersionOnly = serde_json::from_str(json)?; 12 Ok(parsed.version) 13 } 14 15 fn main() -> Result<(), serde_json::Error> { 16 let big = r#"{ 17 "version": 3, 18 "data": {"a": [1,2,3,4,5], "b": "lots of text here"}, 19 "signature": "deadbeef", 20 "nested": {"deep": {"deeper": {"x": true}}} 21 }"#; 22 println!("version = {}", payload_version(big)?); 23 Ok(()) 24 } ``` Real output from `cargo run`: ```text 1 version = 3 ``` Because Serde ignores fields the struct does not declare, the `data`, `signature`, and `nested` subtrees are parsed past but never materialized into owned values. Compared with `let v: Value = from_str(big)?; v["version"].as_u64()`, this allocates nothing for the unused fields and gives you a checked `u32` directly instead of an `Option<u64>` you have to unwrap. # Rust Web APIs with Axum > Build web APIs in Rust with Axum, mapping Express's router-handler-middleware model to typed extractors, IntoResponse, and Tower layers on Tokio for a full JSON API. In Node.js you reach for Express, NestJS, or Fastify and trust the framework to wire up routing, body parsing, and middleware. Rust’s web story keeps that same shape but moves the guarantees into the type system: **Axum** — built on the [Tokio](/11-async/) async runtime and the Tower middleware ecosystem — turns request inputs into typed **extractors**, responses into anything that implements `IntoResponse`, and middleware into composable **layers**. This section takes you from a one-route hello-server to a production-flavored JSON API with shared state, validation, typed error handling, CORS, JWT authentication, sessions, WebSockets, Server-Sent Events, multipart uploads, static files, and a Dockerized deployment. Every example targets the **axum 0.8** API line (recorded with 0.8.9): servers are started with `axum::serve(listener, app)` over a `tokio::net::TcpListener` (the removed `Server::bind().serve()` builder is gone), and path parameters use `{id}` brace syntax (the old `:id` colon form was dropped in 0.8). The section uses the repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) and the 2024 edition. *** ## What You’ll Learn [Section titled “What You’ll Learn”](#what-youll-learn) * How the Express mental model — router, handlers, `(req, res)`, middleware — maps onto Axum’s `Router`, async `fn` handlers, extractors, and Tower layers * How to choose between Axum, Actix Web, and Rocket the way you’d choose between Express, NestJS, and Fastify * How to set up a Tokio + Axum project and run a server with `axum::serve` and `tokio::net::TcpListener` * Routing: path params (`{id}` — never `:id` in 0.8), query strings, method routing, nested routers, and fallbacks * Extractors (`Path`, `Query`, `Json`, `State`, headers), how `FromRequest`/`FromRequestParts` work, and why extractor **ordering** matters * Middleware as Tower layers: `tower-http` (`TraceLayer`, `CorsLayer`, compression) and custom `from_fn` middleware * Shared application state with `State<T>` and `Arc`, when to reach for request extensions, and injecting a DB pool or config * Building JSON REST APIs with Serde and the `Json` extractor/response, including a full CRUD resource * Request validation and returning helpful `400 Bad Request` responses * Typed error handling with a custom `AppError` that implements `IntoResponse`, backed by `thiserror` * CORS, authentication (extractor-as-guard and middleware), JWT, and cookie/server-side sessions * Real-time features: WebSockets and Server-Sent Events * Multipart file uploads, serving static files with an SPA fallback, and deploying with a multi-stage Docker build *** ## Topics [Section titled “Topics”](#topics) | Topic | Description | | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | [Framework Comparison](/16-web-apis/00-framework-comparison/) | Axum vs Actix Web vs Rocket (vs Express/NestJS): tradeoffs and when to pick which. | | [Axum Basics](/16-web-apis/01-axum-basics/) | Express.js → Axum fundamentals: `Router`, handlers, async `fn` handlers, running with `axum::serve` + `tokio::net::TcpListener` (0.8). | | [Axum Setup](/16-web-apis/02-axum-setup/) | Setting up an Axum project: tokio + axum deps/features, project layout, and a compile-verified hello-server. | | [Routing](/16-web-apis/03-routing/) | Route handlers, path params (`{id}` in 0.8 — **not** `:id`), query params, method routing, nested routers, and fallback. | | [Extractors](/16-web-apis/04-extractors/) | Request extractors: `Path`, `Query`, `Json`, `State`, headers; how `FromRequest`/`FromRequestParts` work; extractor ordering. | | [Middleware](/16-web-apis/05-middleware/) | Express middleware → Tower/Axum layers; `tower-http` (`TraceLayer`, `CorsLayer`, compression); `from_fn` middleware. | | [State Management](/16-web-apis/06-state-management/) | Shared application state with `State<T>` + `Arc`; when to use extensions; injecting a DB pool or config. | | [Request and Response](/16-web-apis/07-request-response/) | Request/response handling; `IntoResponse`; status codes; setting headers; `(StatusCode, Json)` tuples. | | [JSON APIs](/16-web-apis/08-json-apis/) | Building JSON REST APIs with Serde and the `Json` extractor/response; a small CRUD resource. | | [Validation](/16-web-apis/09-validation/) | Request validation (the `validator` crate and/or manual) and returning `400`s with helpful messages. | | [Error Handling](/16-web-apis/10-error-handling-web/) | Error handling in handlers: a custom `AppError` implementing `IntoResponse`, `thiserror`, mapping errors to status codes. | | [CORS](/16-web-apis/11-cors/) | CORS configuration with `tower-http` `CorsLayer`; permissive vs locked-down. | | [Authentication](/16-web-apis/12-authentication/) | Authentication patterns: extractor-as-guard, middleware auth, an `AuthUser` extractor. | | [JWT](/16-web-apis/13-jwt/) | JWT authentication with the `jsonwebtoken` crate: encoding/decoding, `Claims`, expiry, verifying in an extractor. | | [Sessions](/16-web-apis/14-sessions/) | Session management: cookies, server-side sessions (`tower-sessions`), and CSRF considerations. | | [WebSockets](/16-web-apis/15-websockets/) | WebSocket support with `axum::extract::ws`: upgrade, send/receive loop, echo server. | | [Server-Sent Events](/16-web-apis/16-sse/) | Server-Sent Events with `axum::response::Sse` and a `Stream` of events. | | [File Uploads](/16-web-apis/17-file-uploads/) | Handling multipart file uploads (axum `Multipart`); streaming to disk. | | [Static Files](/16-web-apis/18-static-files/) | Serving static files with `tower-http` `ServeDir`/`ServeFile`; SPA fallback. | | [Deployment](/16-web-apis/19-deployment/) | Deploying Axum apps: release builds, multi-stage Docker, binding `0.0.0.0`, reverse proxy, and env config. | *** ## Learning Objectives [Section titled “Learning Objectives”](#learning-objectives) By the end of this section, you will be able to: * Explain how Axum’s router-plus-handlers model corresponds to Express, and where the analogy breaks down (extractors instead of `req`, `IntoResponse` instead of `res`, lazy futures that need a runtime) * Choose a Rust web framework deliberately based on philosophy, ecosystem fit, and team experience * Stand up an Axum project from scratch and serve it with `axum::serve` + `tokio::net::TcpListener` * Define routes with path and query parameters, method routing, nested routers, and fallbacks using current 0.8 syntax * Pull typed inputs out of requests with the standard extractors and reason about why ordering matters * Compose cross-cutting concerns as Tower layers and write custom middleware with `from_fn` * Share a database pool, configuration, or in-memory store across handlers with `State<T>` and `Arc` * Build a complete JSON CRUD resource that validates input, returns correct status codes, and maps errors to responses through a single `AppError` * Add CORS, JWT-based and middleware-based authentication, and cookie/server-side sessions * Implement real-time endpoints with WebSockets and Server-Sent Events, accept file uploads, serve static assets, and ship the result in a Docker container *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * [Section 11: Async Programming](/11-async/) — Axum is built on Tokio. Handlers are `async fn`s, the server is started inside `#[tokio::main]`, and Rust futures are **lazy** and need a runtime to drive them. The async vocabulary from Section 11 is assumed throughout. * [Section 15: Serialization](/15-serialization/) — request bodies and JSON responses ride on Serde. The `Json` extractor deserializes with `Deserialize` and the `Json` response serializes with `Serialize`, so the derive macros and attributes from Section 15 carry over directly. * Helpful but not required: [Section 08: Error Handling](/08-error-handling/) — the `AppError`/`thiserror`/`?` pattern in [Error Handling](/16-web-apis/10-error-handling-web/) builds on that section’s error vocabulary. *** ## Estimated Time [Section titled “Estimated Time”](#estimated-time) * **Reading:** 8-9 hours * **Hands-on Practice:** 6-7 hours * **Exercises:** 4 hours * **Total:** 18-20 hours > **Tip:** Read [Framework Comparison](/16-web-apis/00-framework-comparison/) → [Axum Basics](/16-web-apis/01-axum-basics/) → [Axum Setup](/16-web-apis/02-axum-setup/) → [Routing](/16-web-apis/03-routing/) → [Extractors](/16-web-apis/04-extractors/) as one connected track — that gives you a working server and the core request model. Then [State Management](/16-web-apis/06-state-management/), [Request and Response](/16-web-apis/07-request-response/), [JSON APIs](/16-web-apis/08-json-apis/), [Validation](/16-web-apis/09-validation/), and [Error Handling](/16-web-apis/10-error-handling-web/) compose into a real API. Treat [Middleware](/16-web-apis/05-middleware/), [CORS](/16-web-apis/11-cors/), [Authentication](/16-web-apis/12-authentication/), [JWT](/16-web-apis/13-jwt/), [Sessions](/16-web-apis/14-sessions/), [WebSockets](/16-web-apis/15-websockets/), [Server-Sent Events](/16-web-apis/16-sse/), [File Uploads](/16-web-apis/17-file-uploads/), [Static Files](/16-web-apis/18-static-files/), and [Deployment](/16-web-apis/19-deployment/) as a toolbox to pull from as each need arises. *** **Next:** [Section 17: Database →](/17-database/) — connecting your Axum API to PostgreSQL, SQLite, MongoDB, and Redis with SQLx, Diesel, and SeaORM, including the connection pool you’ll inject via `State`. # Choosing a Rust Web Framework: Axum vs Actix Web vs Rocket > Map Rust's Axum, Actix Web, and Rocket onto the Express, Nest, and Fastify tradeoffs you know from Node, and see why this guide picks Axum as the default. Coming from Node.js, picking a web framework felt easy: Express for the unopinionated default, Nest for the batteries-included enterprise option, Fastify when you cared about throughput. Rust offers a similar spectrum, but the tradeoffs land in different places. This guide maps the three mainstream Rust web frameworks onto the mental model you already have from Express and Nest, and gives you a concrete way to choose. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Rust’s web ecosystem has consolidated around three production-grade frameworks: **Axum** (the tower/tokio-native default), **Actix Web** (the throughput-focused veteran), and **Rocket** (the ergonomic, macro-driven option). All three are mature and used in production; they differ mainly in *philosophy*: how much magic, how much boilerplate, and how they compose with the wider async ecosystem. For most TypeScript/JavaScript developers building a new API, **Axum is the closest analogue to “modern Express” and the recommended starting point**, which is why the rest of this section focuses on it. > **Note:** A “web framework” in Rust is just a regular crate (Rust’s word for a package; see [Section 01: Cargo Basics](/01-getting-started/03-cargo-basics/)). There is no global install, no CLI scaffolder you must adopt, and no runtime baked in. You add the crate with `cargo add`, you bring your own async runtime (almost always **tokio**), and you compile a single self-contained binary. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In Node.js, the framework choice usually comes down to three archetypes. Here is the same “get a user by id” endpoint in each, so the comparison is apples-to-apples. ```typescript 1 // Express.js — unopinionated, minimal, the lingua franca 2 import express from "express"; 3 4 const app = express(); 5 const users = [{ id: 1, name: "Ada" }]; 6 7 app.get("/users/:id", (req, res) => { 8 const id = Number(req.params.id); 9 const user = users.find((u) => u.id === id); 10 if (!user) return res.status(404).json({ error: "not found" }); 11 res.json(user); 12 }); 13 14 app.listen(3000); ``` ```typescript 1 // NestJS — opinionated, decorator-driven, DI container, "Angular for the backend" 2 import { Controller, Get, Param, NotFoundException } from "@nestjs/common"; 3 4 @Controller("users") 5 export class UsersController { 6 private users = [{ id: 1, name: "Ada" }]; 7 8 @Get(":id") 9 getUser(@Param("id") id: string) { 10 const user = this.users.find((u) => u.id === Number(id)); 11 if (!user) throw new NotFoundException(); 12 return user; // serialized to JSON automatically 13 } 14 } ``` ```typescript 1 // Fastify — Express-shaped but schema-first, optimized for throughput 2 import Fastify from "fastify"; 3 4 const app = Fastify(); 5 const users = [{ id: 1, name: "Ada" }]; 6 7 app.get<{ Params: { id: string } }>("/users/:id", async (req, reply) => { 8 const user = users.find((u) => u.id === Number(req.params.id)); 9 if (!user) return reply.code(404).send({ error: "not found" }); 10 return user; 11 }); 12 13 app.listen({ port: 3000 }); ``` **The Node.js mental model:** * **Express** = unopinionated, glue-it-yourself, huge middleware ecosystem. * **Nest** = opinionated structure, dependency injection, decorators, larger learning curve. * **Fastify** = Express-shaped, but built for speed and schema validation. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same endpoint in each Rust framework. Every snippet below was compiled against current crate versions (axum 0.8.9, actix-web 4.13.0, rocket 0.5.1). ```rust 1 // Axum 0.8 — tower/tokio-native, type-driven extractors, "modern Express" 2 // Cargo.toml: axum = "0.8", tokio = { version = "1", features = ["full"] }, serde = { version = "1", features = ["derive"] } 3 use axum::{routing::get, Router, Json, extract::Path}; 4 use serde::Serialize; 5 6 #[derive(Serialize)] 7 struct User { 8 id: u32, 9 name: String, 10 } 11 12 async fn get_user(Path(id): Path<u32>) -> Json<User> { 13 Json(User { id, name: "Ada".to_string() }) 14 } 15 16 #[tokio::main] 17 async fn main() { 18 // Path params use {id} in 0.8 (NOT the old :id from 0.7). 19 let app: Router = Router::new().route("/users/{id}", get(get_user)); 20 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 21 axum::serve(listener, app).await.unwrap(); 22 } ``` ```rust 1 // Actix Web 4 — actor-influenced, macro routing, raw-throughput focus 2 // Cargo.toml: actix-web = "4", serde = { version = "1", features = ["derive"] } 3 use actix_web::{get, web, App, HttpServer, Responder}; 4 use serde::Serialize; 5 6 #[derive(Serialize)] 7 struct User { 8 id: u32, 9 name: String, 10 } 11 12 #[get("/users/{id}")] 13 async fn get_user(path: web::Path<u32>) -> impl Responder { 14 let id = path.into_inner(); 15 web::Json(User { id, name: "Ada".to_string() }) 16 } 17 18 #[actix_web::main] 19 async fn main() -> std::io::Result<()> { 20 // The app factory closure runs once per worker thread. 21 HttpServer::new(|| App::new().service(get_user)) 22 .bind(("0.0.0.0", 3000))? 23 .run() 24 .await 25 } ``` ```rust 1 // Rocket 0.5 — the most "Nest-like": heavy macros, attribute routing, batteries included 2 // Cargo.toml: rocket = { version = "0.5", features = ["json"] }, serde = { version = "1", features = ["derive"] } 3 #[macro_use] 4 extern crate rocket; 5 6 use rocket::serde::{json::Json, Serialize}; 7 8 #[derive(Serialize)] 9 #[serde(crate = "rocket::serde")] 10 struct User { 11 id: u32, 12 name: String, 13 } 14 15 #[get("/users/<id>")] 16 fn get_user(id: u32) -> Json<User> { 17 Json(User { id, name: "Ada".to_string() }) 18 } 19 20 #[launch] 21 fn rocket() -> _ { 22 rocket::build().mount("/", routes![get_user]) 23 } ``` Notice three things a TypeScript/JavaScript developer will spot immediately: 1. **You bring the runtime.** Axum and Actix start an async runtime explicitly via `#[tokio::main]` / `#[actix_web::main]`; Rocket hides it behind `#[launch]`. There is no always-on event loop like Node’s — see [Section 11: Async](/11-async/) for why Rust futures are lazy and require a runtime. 2. **The type system does the parsing.** `Path<u32>` parses and validates the path segment into a `u32` *before* your handler runs. A non-numeric id never reaches your code. In Express you would call `Number(req.params.id)` by hand and check for `NaN`. 3. **JSON serialization is a return-type concern, not a side effect.** You return `Json<User>` instead of calling `res.json(user)`. The framework turns it into a response with the right `Content-Type`. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Axum: tower-native, type-driven, the recommended default [Section titled “Axum: tower-native, type-driven, the recommended default”](#axum-tower-native-type-driven-the-recommended-default) Axum is built by the tokio team on top of two foundations you will meet repeatedly: **tokio** (the async runtime) and **tower** (a generic middleware abstraction). Its defining idea is **extractors**: a handler’s *parameter types* declare what it needs from the request, and the framework supplies them. ```rust 1 // Cargo.toml: axum = "0.8", tokio = { version = "1", features = ["full"] } 2 // serde = { version = "1", features = ["derive"] } 3 use std::sync::{Arc, RwLock}; 4 5 use axum::{ 6 extract::{Path, State}, 7 http::StatusCode, 8 routing::get, 9 Json, Router, 10 }; 11 use serde::{Deserialize, Serialize}; 12 13 #[derive(Clone, Serialize)] 14 struct Todo { 15 id: u32, 16 title: String, 17 done: bool, 18 } 19 20 #[derive(Deserialize)] 21 struct NewTodo { 22 title: String, 23 } 24 25 #[derive(Clone, Default)] 26 struct AppState { 27 todos: Arc<RwLock<Vec<Todo>>>, 28 } 29 30 async fn create_todo( 31 State(state): State<AppState>, // shared state extractor 32 Json(input): Json<NewTodo>, // parsed + validated JSON body 33 ) -> (StatusCode, Json<Todo>) { // status + body, declared in the type 34 let mut todos = state.todos.write().unwrap(); 35 let id = todos.len() as u32 + 1; 36 let todo = Todo { id, title: input.title, done: false }; 37 todos.push(todo.clone()); 38 (StatusCode::CREATED, Json(todo)) 39 } ``` Each handler argument is an extractor; each return type implements `IntoResponse`. Because everything is “just types,” the compiler checks your wiring. Forget to register the state? You get a compile error (shown in [Common Pitfalls](#common-pitfalls)), not a `undefined is not a function` at 3 a.m. Middleware is `tower::Layer`, which means Axum can reuse the entire tower/tower-http ecosystem (tracing, compression, timeouts, CORS), covered in [Middleware and Layers](/16-web-apis/05-middleware/). > **Tip:** Axum has *no* macros for routing or handlers. A handler is a plain `async fn`. This keeps the model close to Express’s “a route is just a function” while adding compile-time guarantees. ### Actix Web: the throughput veteran [Section titled “Actix Web: the throughput veteran”](#actix-web-the-throughput-veteran) Actix Web is the oldest of the three and historically tops the public throughput benchmarks (TechEmpower). It originally grew out of the `actix` actor framework, but today the actor model is optional; most code looks like the example above. Its distinguishing operational detail is the **multi-threaded, share-nothing worker model**: `HttpServer::new` takes a *closure* that builds a fresh `App` per worker thread, so per-worker state is created once per thread, and truly shared state must live behind `web::Data` (an `Arc` internally). Actix Web is an excellent choice when raw requests-per-second is your top metric, or when your team already knows it. Its API is slightly more “framework-y” than Axum’s (more bespoke types, the `App`/`service` builder, the worker-closure quirk), and it composes with the generic tower ecosystem less directly than Axum does. ### Rocket: the ergonomic, Nest-like option [Section titled “Rocket: the ergonomic, Nest-like option”](#rocket-the-ergonomic-nest-like-option) Rocket optimizes for *developer ergonomics*. It leans hard on attribute macros (`#[get("/users/<id>")]`, `#[launch]`), provides built-in request guards, typed forms, managed state, and a `Rocket.toml` config file: the closest thing in Rust to Nest’s “everything included” feel. It hides the async runtime entirely. The tradeoff: the heavy macro magic makes some compiler errors harder to read, and historically Rocket’s release cadence has been slower (the jump to a stable async 0.5 took years). It composes with the tower ecosystem less naturally than Axum. For learning-by-reading-the-types — the whole premise of this guide — Rocket’s magic can obscure what is actually happening. ### Why this guide standardizes on Axum [Section titled “Why this guide standardizes on Axum”](#why-this-guide-standardizes-on-axum) This entire Section 16 uses Axum because it hits the sweet spot for a TypeScript/JavaScript developer: minimal magic (handlers are plain functions), maximal compile-time help (extractors and `IntoResponse` are checked types), and smooth access to the tower/tokio ecosystem you will also use for databases ([Section 17](/17-database/)), tracing, and more. The concepts transfer: once you understand extractors and layers, picking up Actix or Rocket later is straightforward. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Dimension | Express / Nest / Fastify | Axum | Actix Web | Rocket | | -------------------------------- | --------------------------------- | ------------------------------------ | ----------------------------------- | -------------------- | | Closest JS analogue | — | Modern Express | Fastify (speed) | NestJS (ergonomics) | | Async runtime | Built-in event loop (always on) | tokio (you start it) | tokio via `actix-rt` (you start it) | tokio (hidden) | | Routing style | `app.get("/x", fn)` | `Router::new().route("/x", get(fn))` | `#[get("/x")]` macro | `#[get("/x")]` macro | | Path param syntax | `:id` | `{id}` | `{id}` | `<id>` | | Request parsing | manual (`req.params`, `req.body`) | extractors (typed args) | extractors (typed args) | typed args + guards | | Middleware | `app.use(fn)` | `tower::Layer` (huge ecosystem) | actix middleware | fairings | | Macro magic | low (Express) / high (Nest) | very low | medium | high | | Compile-time route/wiring checks | none (runtime) | strong | medium | medium | | Maturity | very high | high | very high (oldest) | high | | Raw throughput | moderate | very high | highest (typically) | high | | Best when… | — | new API, want the default | max RPS / existing team | ergonomics-first | ### The runtime difference is the big one [Section titled “The runtime difference is the big one”](#the-runtime-difference-is-the-big-one) In Node, the event loop is *always running*: `import express` and you have concurrency for free. In Rust there is no ambient runtime. You opt in with tokio, which is why `main` is `async` and annotated with `#[tokio::main]`. This is the same lazy-future model from [Section 11: Async](/11-async/): a future does nothing until a runtime polls it. The upside is control (you choose thread count, you can run multiple runtimes); the cost is one line of ceremony. ### ”Decorators” are not what they look like [Section titled “”Decorators” are not what they look like”](#decorators-are-not-what-they-look-like) Rocket’s and Actix’s `#[get(...)]` look like Nest’s `@Get()` decorators, but they are **procedural macros** that generate code at compile time, not runtime metadata read by a DI container. Macros are *not* decorators — see [Section 14: Macros](/14-macros/). Axum deliberately avoids them so a route is just `get(handler)`. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Using the old `:id` path syntax in Axum 0.8 [Section titled “Pitfall 1: Using the old :id path syntax in Axum 0.8”](#pitfall-1-using-the-old-id-path-syntax-in-axum-08) Axum 0.7 used Express-style `:id`. Axum 0.8 switched to `{id}` (matching the OpenAPI/RFC 6570 style). The old syntax still *compiles* but **panics at startup**, which can be confusing because the type checker does not catch it. ```rust 1 // panics at runtime (NOT a compile error) 2 let app: Router = Router::new().route("/users/:id", get(handler)); ``` Running it produces this real panic: ```text 1 thread 'main' panicked at src/main.rs:10:37: 2 Path segments must not start with `:`. For capture groups, use `{capture}`. If you meant to literally match a segment starting with a colon, call `without_v07_checks` on the router. 3 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` The fix is to use `{id}`. See [Routing in Axum](/16-web-apis/03-routing/) for the full path-parameter story. ### Pitfall 2: Forgetting `.with_state(...)` in Axum [Section titled “Pitfall 2: Forgetting .with\_state(...) in Axum”](#pitfall-2-forgetting-with_state-in-axum) Because extractors are types, a missing piece of wiring becomes a compile error, but the message names framework internals, which is unfamiliar. If a handler takes `State<AppState>` but you never call `.with_state(...)`, the router’s state type (`()`) does not match the handler’s (`AppState`): ```rust 1 // does not compile (error[E0308]: mismatched types) 2 async fn handler(State(state): State<AppState>) -> String { 3 state.name 4 } 5 6 #[tokio::main] 7 async fn main() { 8 // Forgot `.with_state(AppState::default())` 9 let app: Router = Router::new().route("/", get(handler)); 10 // ... 11 } ``` The actual compiler output: ```text 1 error[E0308]: mismatched types 2 --> src/main.rs:15:48 3 | 4 15 | let app: Router = Router::new().route("/", get(handler)); 5 | ----- ^^^^^^^^^^^^ expected `MethodRouter`, found `MethodRouter<AppState>` 6 | | 7 | arguments to this method are incorrect 8 | 9 = note: expected struct `MethodRouter<()>` 10 found struct `MethodRouter<AppState>` ``` The fix: `Router::new().route("/", get(handler)).with_state(AppState::default())`. Read `MethodRouter<AppState>` as “this router needs `AppState` supplied.” State is covered in depth in [Shared Application State in Axum](/16-web-apis/06-state-management/). ### Pitfall 3: Expecting the framework to start a runtime for you [Section titled “Pitfall 3: Expecting the framework to start a runtime for you”](#pitfall-3-expecting-the-framework-to-start-a-runtime-for-you) A `main` that calls async code without a runtime will not compile, and an `async fn main()` without `#[tokio::main]` will not even be a valid entry point. This trips up developers used to Node’s always-on loop. Always annotate (`#[tokio::main]`, `#[actix_web::main]`, or `#[launch]` for Rocket). See [Setting Up an Axum Project](/16-web-apis/02-axum-setup/). ### Pitfall 4: Choosing on benchmarks alone [Section titled “Pitfall 4: Choosing on benchmarks alone”](#pitfall-4-choosing-on-benchmarks-alone) TechEmpower numbers are real, but for the vast majority of APIs the bottleneck is your database, not the framework’s request dispatch. All three frameworks are *far* faster than Node. Choose on ecosystem fit, team familiarity, and readability — not a 5% benchmark delta. ### Pitfall 5: Mixing up Actix’s worker closure [Section titled “Pitfall 5: Mixing up Actix’s worker closure”](#pitfall-5-mixing-up-actixs-worker-closure) `HttpServer::new(|| App::new()...)` runs the closure **once per worker thread**. State created *inside* the closure is per-worker, not shared. Truly shared state must be created outside and moved in via `web::Data` (see the [exercise solution](#exercises) below). This has no Express equivalent because Node is single-threaded by default. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Default to Axum for new projects** unless you have a specific reason not to. It has the gentlest “read the types to understand the code” story, the broadest middleware ecosystem (tower-http), and first-party alignment with tokio. * **Pick Actix Web** when maximum throughput is a hard requirement, or when your team/codebase already standardizes on it. * **Pick Rocket** when developer ergonomics and a batteries-included feel matter more than ecosystem composability, and you are comfortable with heavier macro magic. * **Don’t fragment your stack.** Standardize on *one* framework per service. The extractor/middleware concepts do not transfer line-for-line between them. * **Lean on the type system.** In all three, prefer typed extractors (`Path<u32>`, `Json<T>`) over hand-parsing strings. Let invalid input fail at the boundary, not deep in a handler. * **Verify the version’s API before you write it.** These crates move fast (the axum 0.7 → 0.8 route-syntax break is a perfect example). Run `cargo add <crate>` in a scratch project and check docs.rs for the version you actually pulled. > **Note:** The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically. All examples here target that toolchain. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small but production-shaped Axum service: an in-memory todo API with shared state, typed JSON in/out, a nested resource, proper status codes, and **graceful shutdown** (drain in-flight requests on Ctrl+C, the equivalent of handling `SIGTERM` in a Node process). This is the shape your real services will take; subsequent files swap the `RwLock<Vec<_>>` for a real database pool ([Section 17](/17-database/)). ```rust 1 // Cargo.toml: 2 // axum = "0.8" 3 // tokio = { version = "1", features = ["full"] } 4 // serde = { version = "1", features = ["derive"] } 5 use std::sync::{Arc, RwLock}; 6 7 use axum::{ 8 extract::{Path, State}, 9 http::StatusCode, 10 routing::get, 11 Json, Router, 12 }; 13 use serde::{Deserialize, Serialize}; 14 15 #[derive(Clone, Serialize)] 16 struct Todo { 17 id: u32, 18 title: String, 19 done: bool, 20 } 21 22 #[derive(Deserialize)] 23 struct NewTodo { 24 title: String, 25 } 26 27 // Shared application state: a thread-safe, in-memory store. 28 // `Arc` lets every worker share one store; `RwLock` guards mutation. 29 #[derive(Clone, Default)] 30 struct AppState { 31 todos: Arc<RwLock<Vec<Todo>>>, 32 } 33 34 async fn list_todos(State(state): State<AppState>) -> Json<Vec<Todo>> { 35 let todos = state.todos.read().unwrap(); 36 Json(todos.clone()) 37 } 38 39 async fn create_todo( 40 State(state): State<AppState>, 41 Json(input): Json<NewTodo>, 42 ) -> (StatusCode, Json<Todo>) { 43 let mut todos = state.todos.write().unwrap(); 44 let id = todos.len() as u32 + 1; 45 let todo = Todo { id, title: input.title, done: false }; 46 todos.push(todo.clone()); 47 (StatusCode::CREATED, Json(todo)) 48 } 49 50 async fn get_todo( 51 State(state): State<AppState>, 52 Path(id): Path<u32>, 53 ) -> Result<Json<Todo>, StatusCode> { 54 let todos = state.todos.read().unwrap(); 55 todos 56 .iter() 57 .find(|t| t.id == id) 58 .cloned() 59 .map(Json) 60 .ok_or(StatusCode::NOT_FOUND) // missing -> 404, no panic 61 } 62 63 fn app() -> Router { 64 Router::new() 65 .route("/todos", get(list_todos).post(create_todo)) 66 .route("/todos/{id}", get(get_todo)) 67 .with_state(AppState::default()) 68 } 69 70 #[tokio::main] 71 async fn main() { 72 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 73 println!("listening on {}", listener.local_addr().unwrap()); 74 axum::serve(listener, app()) 75 .with_graceful_shutdown(shutdown_signal()) 76 .await 77 .unwrap(); 78 } 79 80 async fn shutdown_signal() { 81 tokio::signal::ctrl_c() 82 .await 83 .expect("failed to install Ctrl+C handler"); 84 } ``` This compiles and runs on axum 0.8.9. Once started, `curl localhost:3000/todos` returns `[]`, a `POST` with `{"title":"ship it"}` returns `201 Created` with the new todo, and `GET /todos/99` returns a clean `404`. Pressing Ctrl+C lets in-flight requests finish before the process exits — exactly the lifecycle behavior you want behind a load balancer. The full request/response, error-handling, and validation details are expanded in [JSON REST APIs](/16-web-apis/08-json-apis/), [Error Handling in Web Handlers](/16-web-apis/10-error-handling-web/), and [Request Validation](/16-web-apis/09-validation/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * **Axum docs:** <https://docs.rs/axum/latest/axum/> and the tutorial <https://github.com/tokio-rs/axum/tree/main/examples> * **Actix Web:** <https://actix.rs/docs/> and <https://docs.rs/actix-web/latest/actix_web/> * **Rocket:** <https://rocket.rs/guide/> and <https://docs.rs/rocket/latest/rocket/> * **tower / tower-http** (Axum’s middleware ecosystem): <https://docs.rs/tower-http/latest/tower_http/> * **TechEmpower benchmarks** (read with the grain of salt from Pitfall 4): <https://www.techempower.com/benchmarks/> * Guide cross-links: [Setting Up an Axum Project](/16-web-apis/02-axum-setup/) · [Axum Fundamentals](/16-web-apis/01-axum-basics/) · [Routing in Axum](/16-web-apis/03-routing/) · [Extractors](/16-web-apis/04-extractors/) · [Middleware and Layers](/16-web-apis/05-middleware/) · [Shared Application State in Axum](/16-web-apis/06-state-management/) · [Section 11: Async](/11-async/) · [Section 17: Database](/17-database/) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Read the types, predict the framework [Section titled “Exercise 1: Read the types, predict the framework”](#exercise-1-read-the-types-predict-the-framework) **Difficulty:** Beginner **Objective:** Build the mental model that “a handler’s argument types declare its dependencies.” **Instructions:** Without running anything, decide which framework each snippet is from and what the path parameter syntax is. Then explain, in one sentence, what `Path<u32>` guarantees that Express’s `req.params.id` does not. 1. `#[get("/users/<id>")] fn f(id: u32) -> ...` 2. `Router::new().route("/users/{id}", get(f))` 3. `#[get("/users/{id}")] async fn f(path: web::Path<u32>) -> ...` Solution 1. **Rocket:** angle-bracket `<id>` syntax and a non-`async` `fn` returning `_` under `#[launch]`. 2. **Axum:** the `Router::new().route(..., get(f))` builder with `{id}` path syntax. 3. **Actix Web:** the `#[get(...)]` attribute macro with `web::Path<u32>` extractor. `Path<u32>` (or `web::Path<u32>`) **parses and validates the segment into a `u32` before the handler runs**: a request to `/users/abc` is rejected at the boundary with a 4xx and never reaches your code. Express’s `req.params.id` is always a `string`; you must call `Number(...)` and check for `NaN` yourself, and forgetting to do so is a runtime bug, not a compile error. ### Exercise 2: Axum router with a nested resource and a fallback [Section titled “Exercise 2: Axum router with a nested resource and a fallback”](#exercise-2-axum-router-with-a-nested-resource-and-a-fallback) **Difficulty:** Intermediate **Objective:** Compose an Axum `Router` with a health check, a nested API sub-router, a 404 fallback, and request tracing: the skeleton of a real service. **Instructions:** Write an Axum app that: * serves `GET /health` returning `"ok"`, * nests a sub-router under `/api/v1` that serves `GET /users`, * returns a custom 404 (`"no such route"`) for anything else, * attaches `tower_http::trace::TraceLayer` so each request is logged. Dependencies you will need: `axum`, `tokio`, `tower-http` (feature `trace`), `tracing`, `tracing-subscriber`. Solution ```rust 1 // Cargo.toml: 2 // axum = "0.8" 3 // tokio = { version = "1", features = ["full"] } 4 // tower-http = { version = "0.6", features = ["trace"] } 5 // tracing = "0.1" 6 // tracing-subscriber = "0.3" 7 use axum::{http::StatusCode, routing::get, Router}; 8 use tower_http::trace::TraceLayer; 9 10 async fn list_users() -> &'static str { 11 "users" 12 } 13 14 async fn health() -> &'static str { 15 "ok" 16 } 17 18 async fn fallback() -> (StatusCode, &'static str) { 19 (StatusCode::NOT_FOUND, "no such route") 20 } 21 22 fn api_routes() -> Router { 23 Router::new().route("/users", get(list_users)) 24 } 25 26 fn app() -> Router { 27 Router::new() 28 .route("/health", get(health)) 29 .nest("/api/v1", api_routes()) // -> GET /api/v1/users 30 .fallback(fallback) 31 .layer(TraceLayer::new_for_http()) 32 } 33 34 #[tokio::main] 35 async fn main() { 36 tracing_subscriber::fmt::init(); 37 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 38 axum::serve(listener, app()).await.unwrap(); 39 } ``` `nest` prefixes every route in the sub-router, so `list_users` becomes `GET /api/v1/users`. `fallback` is Axum’s catch-all for unmatched routes (Express’s app-level 404 handler). `TraceLayer` is a `tower::Layer` — middleware that wraps the whole router — and is the idiomatic way to log requests. Routing details are in [Routing in Axum](/16-web-apis/03-routing/); layers in [Middleware and Layers](/16-web-apis/05-middleware/). ### Exercise 3: Shared state across Actix Web’s worker threads [Section titled “Exercise 3: Shared state across Actix Web’s worker threads”](#exercise-3-shared-state-across-actix-webs-worker-threads) **Difficulty:** Advanced **Objective:** Understand why Actix’s per-worker app factory means shared state must be built *outside* the closure, a concept with no Express analogue. **Instructions:** Write an Actix Web app with a single `GET /` route that increments and returns a global visit counter. The counter must be shared across all worker threads (so `/` returns `1, 2, 3, ...` regardless of which worker handles the request). Use an atomic to avoid a lock. Explain why the state cannot be created inside the `HttpServer::new(|| ...)` closure. Solution ```rust 1 // Cargo.toml: actix-web = "4" 2 use std::sync::atomic::{AtomicU64, Ordering}; 3 4 use actix_web::{get, web, App, HttpServer, Responder}; 5 6 struct AppState { 7 visits: AtomicU64, 8 } 9 10 #[get("/")] 11 async fn count(data: web::Data<AppState>) -> impl Responder { 12 let n = data.visits.fetch_add(1, Ordering::Relaxed) + 1; 13 format!("visit #{n}") 14 } 15 16 #[actix_web::main] 17 async fn main() -> std::io::Result<()> { 18 // Build the shared state ONCE, outside the closure... 19 let state = web::Data::new(AppState { visits: AtomicU64::new(0) }); 20 21 // ...then move a CLONE of the handle into each worker. 22 // `web::Data` is an `Arc` internally, so clones share the same AtomicU64. 23 HttpServer::new(move || App::new().app_data(state.clone()).service(count)) 24 .bind(("127.0.0.1", 8080))? 25 .run() 26 .await 27 } ``` The closure passed to `HttpServer::new` runs **once per worker thread**. If you wrote `App::new().app_data(web::Data::new(AppState { ... }))` *inside* the closure, every worker would get its *own* counter, and the returned numbers would depend on which worker happened to serve the request. Creating `state` outside and cloning the `web::Data` (an `Arc`) handle in gives every worker a pointer to the *same* `AtomicU64`. `fetch_add` increments it atomically without a lock. This share-nothing-by-default worker model is unique to a multi-threaded runtime; Node’s single-threaded loop has no equivalent. Axum’s `with_state` solves the same problem with a single `Arc` clone per request — see [Shared Application State in Axum](/16-web-apis/06-state-management/). # Axum Fundamentals: From Express to Axum > Axum's Router, async handlers, and axum::serve mapped from Express: where Express mutates req and res, Rust handlers take typed extractors and return responses. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) [Axum](https://docs.rs/axum) is the most popular Rust web framework, built on top of the [Tokio](/11-async/02-tokio-intro/) async runtime and the Tower middleware ecosystem. If you know Express.js, the mental model transfers almost directly: you build a **router**, attach **handlers** (Express’s “route handlers” or “controllers”) to method-plus-path combinations, and start a server. This page covers the core loop (`Router`, async handler functions, and starting the server with `axum::serve` and a `tokio::net::TcpListener`) so you can build everything else in this section on top of it. > **Note:** This page targets the **axum 0.8** API line (recorded with 0.8.9). Two things changed from older tutorials you may find online: the server is started with `axum::serve(listener, app)` (the old `Server::bind().serve()` builder is gone), and path parameters use `{id}` syntax (the old `:id` colon syntax was removed). If a snippet uses `:id` or `Server::bind`, it targets an older Axum API. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Here is a minimal-but-realistic Express server: a health check, a JSON endpoint that reads a path parameter, and a `POST` that parses a JSON body and replies with `201 Created`. ```typescript 1 // server.ts — Express 4/5 2 import express, { Request, Response } from "express"; 3 4 const app = express(); 5 app.use(express.json()); // body-parsing middleware for JSON 6 7 interface Task { 8 id: number; 9 title: string; 10 done: boolean; 11 } 12 13 // GET / — a plain text response 14 app.get("/", (_req: Request, res: Response) => { 15 res.send("Hello from Express!"); 16 }); 17 18 // GET /health — a JSON response 19 app.get("/health", (_req: Request, res: Response) => { 20 res.json({ status: "ok" }); 21 }); 22 23 // GET /tasks/:id — read a path parameter 24 app.get("/tasks/:id", (req: Request, res: Response) => { 25 const id = Number(req.params.id); 26 const task: Task = { id, title: "Write the docs", done: false }; 27 res.json(task); 28 }); 29 30 // POST /tasks — parse a JSON body, reply 201 31 app.post("/tasks", (req: Request, res: Response) => { 32 const { title } = req.body as { title: string }; 33 const task: Task = { id: 42, title, done: false }; 34 res.status(201).json(task); 35 }); 36 37 app.listen(3000, () => { 38 console.log("listening on http://127.0.0.1:3000"); 39 }); ``` Things a TypeScript developer relies on here: handlers receive `(req, res)`, you pull inputs off `req` (`req.params`, `req.body`, `req.query`), and you push output through `res` (`res.send`, `res.json`, `res.status`). The runtime (Node’s event loop) is always running; `app.listen` just registers the server with it. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same server in Axum. Read it top to bottom. It maps almost one-to-one to the Express version, but the differences are where the learning is. ```rust 1 use axum::{ 2 extract::Path, 3 http::StatusCode, 4 response::IntoResponse, 5 routing::{get, post}, 6 Json, Router, 7 }; 8 use serde::{Deserialize, Serialize}; 9 use std::net::SocketAddr; 10 11 #[derive(Serialize)] 12 struct HealthResponse { 13 status: &'static str, 14 } 15 16 #[derive(Deserialize)] 17 struct CreateTask { 18 title: String, 19 } 20 21 #[derive(Serialize)] 22 struct Task { 23 id: u64, 24 title: String, 25 done: bool, 26 } 27 28 // GET / — a plain text response. `&'static str` is a valid response body. 29 async fn root() -> &'static str { 30 "Hello from Axum!" 31 } 32 33 // GET /health — `Json<T>` serializes T and sets Content-Type: application/json. 34 async fn health() -> Json<HealthResponse> { 35 Json(HealthResponse { status: "ok" }) 36 } 37 38 // GET /tasks/{id} — the `Path` extractor pulls and parses the path parameter. 39 async fn get_task(Path(id): Path<u64>) -> Json<Task> { 40 Json(Task { id, title: "Write the docs".to_string(), done: false }) 41 } 42 43 // POST /tasks — the `Json` extractor parses the body; the tuple sets the status. 44 async fn create_task(Json(payload): Json<CreateTask>) -> impl IntoResponse { 45 let task = Task { id: 42, title: payload.title, done: false }; 46 (StatusCode::CREATED, Json(task)) 47 } 48 49 #[tokio::main] 50 async fn main() { 51 // 1. Build the router: map (method, path) -> handler. 52 let app: Router = Router::new() 53 .route("/", get(root)) 54 .route("/health", get(health)) 55 .route("/tasks", post(create_task)) 56 .route("/tasks/{id}", get(get_task)); 57 58 // 2. Bind a TCP listener — tokio's async listener, not std's. 59 let addr = SocketAddr::from(([127, 0, 0, 1], 3000)); 60 let listener = tokio::net::TcpListener::bind(addr).await.unwrap(); 61 println!("listening on http://{}", listener.local_addr().unwrap()); 62 63 // 3. Hand the listener and the router to axum::serve and await it forever. 64 axum::serve(listener, app).await.unwrap(); 65 } ``` The dependencies (run these in a fresh `cargo new` project; `cargo add` resolves the current versions automatically): ```bash 1 cargo add axum 2 cargo add tokio --features full 3 cargo add serde --features derive 4 cargo add serde_json ``` This produces a `Cargo.toml` with the current stable versions: ```toml 1 [dependencies] 2 axum = "0.8.9" 3 serde = { version = "1.0.228", features = ["derive"] } 4 serde_json = "1.0.150" 5 tokio = { version = "1.52.3", features = ["full"] } ``` Run it with `cargo run`. Hitting the endpoints with `curl` produces this **real** output (captured against the compiled server): ```text 1 $ curl -s http://127.0.0.1:3000/ 2 Hello from Axum! 3 4 $ curl -s http://127.0.0.1:3000/health 5 {"status":"ok"} 6 7 $ curl -s http://127.0.0.1:3000/tasks/7 8 {"id":7,"title":"Write the docs","done":false} 9 10 $ curl -s -i -X POST http://127.0.0.1:3000/tasks \ 11 -H 'content-type: application/json' -d '{"title":"Ship it"}' 12 HTTP/1.1 201 Created 13 content-type: application/json 14 content-length: 40 15 date: Mon, 01 Jun 2026 11:43:49 GMT 16 17 {"id":42,"title":"Ship it","done":false} ``` *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) Let’s walk through each piece and contrast it with Express. ### The handler is just an `async fn` [Section titled “The handler is just an async fn”](#the-handler-is-just-an-async-fn) ```rust 1 async fn root() -> &'static str { 2 "Hello from Axum!" 3 } ``` In Express, a handler is `(req, res) => { ... }` and you produce output by *calling methods on `res`*. In Axum, a handler is an `async fn` (or async closure) and you produce output by **returning a value**. There is no `res` object to mutate; whatever you `return` becomes the response. This is closer to a pure function: input in the signature, response in the return type. > **Note:** Rust futures are **lazy**: an `async fn` does nothing until it is `.await`ed (or driven by a runtime). This is the opposite of JavaScript Promises, which start executing the moment they are created. Axum’s runtime drives your handler futures for you when a request arrives. See [Promises vs Futures](/11-async/00-promises-vs-futures/). ### Inputs come from extractors, not a `req` object [Section titled “Inputs come from extractors, not a req object”](#inputs-come-from-extractors-not-a-req-object) ```rust 1 async fn get_task(Path(id): Path<u64>) -> Json<Task> { /* ... */ } 2 async fn create_task(Json(payload): Json<CreateTask>) -> impl IntoResponse { /* ... */ } ``` Where Express reads `req.params.id` and `req.body`, Axum declares what it needs **in the function parameters**. `Path<u64>` says “pull the path parameter and parse it into a `u64`”. `Json<CreateTask>` says “read the request body and deserialize it into a `CreateTask`”. These are called **extractors**, and they are typed: if the path parameter is not a valid `u64`, or the body is not valid JSON for the target type, Axum returns an error response *before your handler ever runs*. Express, by contrast, hands you whatever string or `any` is there and trusts you to validate it. The `Path(id)` and `Json(payload)` syntax is **pattern destructuring** of a tuple struct: the same `let Point(x, y) = p;` pattern you would use anywhere in Rust. `Path` wraps the extracted value; the pattern unwraps it into a local binding. > Extractors are a deep topic with their own ordering rules. This page only uses them; [Extractors](/16-web-apis/04-extractors/) covers `FromRequest`/`FromRequestParts` and how to write your own. ### Outputs are return values implementing `IntoResponse` [Section titled “Outputs are return values implementing IntoResponse”](#outputs-are-return-values-implementing-intoresponse) ```rust 1 async fn create_task(Json(payload): Json<CreateTask>) -> impl IntoResponse { 2 let task = Task { id: 42, title: payload.title, done: false }; 3 (StatusCode::CREATED, Json(task)) 4 } ``` Anything a handler returns must implement the `IntoResponse` trait, which knows how to turn the value into an HTTP response. Axum implements it for a huge set of types out of the box: * `&'static str` / `String` → `200 OK`, `text/plain` * `Json<T>` (for any `Serialize` `T`) → `200 OK`, `application/json` * `StatusCode` → an empty response with that status * A tuple like `(StatusCode, Json<T>)` → that status **plus** that JSON body * `Result<T, E>` where both `T` and `E` implement `IntoResponse` → success or error response `-> impl IntoResponse` is the idiomatic return type when you want to return *different* concrete response shapes from one handler without naming them all. It’s the Rust equivalent of TypeScript’s “this returns a `Response`, don’t worry about the exact union.” > Status codes, headers, and the full `IntoResponse` story live in [Request and Response Handling](/16-web-apis/07-request-response/). ### `Router`: the Express `app` [Section titled “Router: the Express app”](#router-the-express-app) ```rust 1 let app: Router = Router::new() 2 .route("/", get(root)) 3 .route("/health", get(health)) 4 .route("/tasks", post(create_task)) 5 .route("/tasks/{id}", get(get_task)); ``` `Router::new()` is your `express()`. Instead of `app.get(path, handler)`, you call `.route(path, method_router)`, where the **method router** (`get(...)`, `post(...)`, `put(...)`, `delete(...)`) wraps the handler and declares which HTTP method it answers. Each `.route()` returns the router by value, so you chain them (a *builder pattern*). The path parameter syntax is `{id}`, matching the modern Express 5 / URL Pattern style, **not** the old `:id`. You can attach several methods to the same path by chaining on the method router: ```rust 1 // One path, two methods — like app.route('/tasks').get(...).post(...) 2 .route("/tasks", get(list_tasks).post(create_task)) ``` ### Starting the server: `axum::serve` + `TcpListener` [Section titled “Starting the server: axum::serve + TcpListener”](#starting-the-server-axumserve--tcplistener) ```rust 1 let addr = SocketAddr::from(([127, 0, 0, 1], 3000)); 2 let listener = tokio::net::TcpListener::bind(addr).await.unwrap(); 3 axum::serve(listener, app).await.unwrap(); ``` This is the part most outdated tutorials get wrong. In axum 0.8 you: 1. Create a **`tokio::net::TcpListener`** (the async listener) and `bind` it — note the `.await`, because binding is itself an async operation. 2. Pass the listener and the router to **`axum::serve`**. 3. `.await` the resulting future. It runs until the process is killed (or until a graceful-shutdown signal you wire in). There is no `app.listen(3000, callback)`. The `axum::serve(...).await` *is* the running server, and the line after it never executes under normal operation. ### `#[tokio::main]`: there is no built-in event loop [Section titled “#\[tokio::main\]: there is no built-in event loop”](#tokiomain-there-is-no-built-in-event-loop) ```rust 1 #[tokio::main] 2 async fn main() { 3 // ... 4 } ``` In Node, the event loop exists before your code runs. In Rust, **`async` is just syntax and nothing drives it until you start a runtime.** The `#[tokio::main]` attribute macro rewrites your `async fn main` into a normal `fn main` that boots a Tokio runtime and blocks on your async body. Without a runtime, `axum::serve(...).await` would have nothing to poll it. See [Tokio Setup](/11-async/03-tokio-setup/) for the details and the manual `Runtime::new()` alternative. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | Express.js | Axum (0.8) | | ------------------ | ------------------------------------- | ---------------------------------------------- | | App object | `const app = express()` | `Router::new()` | | Register route | `app.get("/x", handler)` | `.route("/x", get(handler))` | | Path parameter | `:id` → `req.params.id` (string) | `{id}` → `Path<u64>` (parsed, typed) | | Read JSON body | `express.json()` + `req.body` (`any`) | `Json<T>` extractor (typed, validated) | | Query string | `req.query` | `Query<T>` extractor | | Produce a response | call `res.json()` / `res.send()` | **return** a value implementing `IntoResponse` | | Set status | `res.status(201).json(...)` | return `(StatusCode::CREATED, Json(...))` | | Async | optional; callbacks or `async` | every handler is `async`; needs a runtime | | Start server | `app.listen(3000)` | `axum::serve(TcpListener, app).await` | | Runtime | always-on event loop | you start Tokio (`#[tokio::main]`) | | Input validation | manual / middleware | extractors fail with a 4xx before the handler | The deepest conceptual shift: **Express hands you raw, untyped request data and a mutable response object; Axum makes you declare typed inputs and return typed outputs.** A handler signature like `async fn get_task(Path(id): Path<u64>) -> Json<Task>` documents and enforces its contract at compile time. The framework rejects malformed requests for you, which in Express you would write by hand. > **Tip:** A handler in Axum is any `async fn` (or async closure) whose parameters are all extractors and whose return type implements `IntoResponse`. That single sentence defines the entire handler contract. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### 1. Returning a type that isn’t a response [Section titled “1. Returning a type that isn’t a response”](#1-returning-a-type-that-isnt-a-response) Every handler’s return type must implement `IntoResponse`. Returning a bare struct that doesn’t will fail, but with a *confusing* error, because the missing trait shows up as the whole function failing the `Handler` bound: ```rust 1 use axum::{routing::get, Router}; 2 3 struct Task { 4 id: u64, 5 } 6 7 // does not compile: Task does not implement IntoResponse 8 async fn get_task() -> Task { 9 Task { id: 1 } 10 } 11 12 #[tokio::main] 13 async fn main() { 14 let app = Router::new().route("/task", get(get_task)); 15 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 16 axum::serve(listener, app).await.unwrap(); 17 } ``` The real error from `cargo check` points at the `get(get_task)` call site, not the handler: ```text 1 error[E0277]: the trait bound `fn() -> impl Future<Output = Task> {get_task}: Handler<_, _>` is not satisfied 2 --> src/main.rs:14:48 3 | 4 14 | let app = Router::new().route("/task", get(get_task)); 5 | --- ^^^^^^^^ the trait `Handler<_, _>` is not implemented for fn item `fn() -> impl Future<Output = Task> {get_task}` 6 | 7 = note: Consider using `#[axum::debug_handler]` to improve the error message ``` As the note says, annotate the handler with `#[axum::debug_handler]` (enable the `macros` feature: `cargo add axum --features macros`). The error then points at the *actual* problem: ```text 1 error[E0277]: the trait bound `Task: IntoResponse` is not satisfied 2 --> src/main.rs:8:24 3 | 4 8 | async fn get_task() -> Task { 5 | ^^^^ the trait `IntoResponse` is not implemented for `Task` ``` The fix: wrap it in `Json` (and derive `Serialize`), or return a `String`, a `(StatusCode, ...)` tuple, etc. ### 2. Using the old `:id` path syntax [Section titled “2. Using the old :id path syntax”](#2-using-the-old-id-path-syntax) Axum 0.8 removed colon-style parameters. Writing `.route("/tasks/:id", get(get_task))` panics at router-construction time with `Path segments must not start with ":". For capture groups, use {capture}.` — a built-in guard carried over from the 0.7→0.8 migration that fires for **any** `:`-prefixed segment (you don’t need to mix old and new syntax to trigger it). Always use braces: `{id}`. Wildcards use `{*rest}`. See [Routing](/16-web-apis/03-routing/). ### 3. Using `std::net::TcpListener` instead of Tokio’s [Section titled “3. Using std::net::TcpListener instead of Tokio’s”](#3-using-stdnettcplistener-instead-of-tokios) `axum::serve` wants an async listener. If you reach for `std::net::TcpListener` (no `.await` on `bind`), the types won’t line up. Always use `tokio::net::TcpListener::bind(...).await`. A handy detail: binding async means you must be inside the runtime, which `#[tokio::main]` guarantees. ### 4. Forgetting the async runtime [Section titled “4. Forgetting the async runtime”](#4-forgetting-the-async-runtime) If you write a plain `fn main` and call `axum::serve(...).await`, it won’t even parse (`.await` is only valid in an async context). And if you build a runtime but never block on the serve future, the program exits immediately. `#[tokio::main]` handles both: it starts the runtime and blocks on your async `main`. If you see your server “start and instantly exit,” you almost certainly dropped the `.await` on `axum::serve`. ### 5. Expecting handlers to run in parallel by default [Section titled “5. Expecting handlers to run in parallel by default”](#5-expecting-handlers-to-run-in-parallel-by-default) Tokio’s multi-thread scheduler (the default for `#[tokio::main]`) *can* run handlers on different threads, but a single handler is still one future. Don’t block it with synchronous CPU-heavy work or `std::thread::sleep` — that stalls the worker thread. Use `.await`able async operations, or `tokio::task::spawn_blocking` for unavoidable blocking work. Rust is **not** “multi-threaded by default” in the sense of magically parallelizing your code; concurrency is explicit and opt-in. See [Concurrency](/11-async/10-concurrency/). *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Extract a `fn app() -> Router` builder.** Keep router construction separate from `main`. It makes the router reusable from tests (you can call handlers via `tower::ServiceExt::oneshot` without binding a real port) and keeps `main` to just “bind and serve.” * **Bind `0.0.0.0` in containers, `127.0.0.1` locally.** `127.0.0.1` is loopback-only; inside Docker you must bind `0.0.0.0` to accept traffic from outside the container. * **Reach for `#[axum::debug_handler]` when handler errors are cryptic.** It costs nothing at runtime and turns “this function isn’t a `Handler`” into “this specific type isn’t an extractor / isn’t a response.” * **Prefer `-> impl IntoResponse` for handlers that return mixed shapes**, and a concrete type (`Json<T>`, `Result<Json<T>, AppError>`) when the shape is fixed and you want it documented in the signature. * **Let extractors validate.** Don’t accept `String` and parse by hand if `Path<u64>` or `Json<T>` already does it and returns a clean 4xx. Push as much validation into the type system as you can. * **Keep handlers small and `async`-pure.** Inject dependencies (DB pools, config) via shared state rather than globals; see [State Management](/16-web-apis/06-state-management/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small in-memory task API with three endpoints, shared state behind `Arc<Mutex<...>>`, a `Result`-returning handler that maps “not found” to a `404`, and a `fn app()` builder. This is the shape of a real Axum service before you swap the `Vec` for a database. ```rust 1 use axum::{ 2 extract::{Path, State}, 3 http::StatusCode, 4 response::IntoResponse, 5 routing::get, 6 Json, Router, 7 }; 8 use serde::{Deserialize, Serialize}; 9 use std::sync::{Arc, Mutex}; 10 11 #[derive(Clone, Serialize)] 12 struct Task { 13 id: u64, 14 title: String, 15 done: bool, 16 } 17 18 #[derive(Deserialize)] 19 struct NewTask { 20 title: String, 21 } 22 23 // Shared application state. `Clone` is cheap: the Arcs are reference-counted 24 // pointers, so cloning the state just bumps the counters. 25 #[derive(Clone, Default)] 26 struct AppState { 27 tasks: Arc<Mutex<Vec<Task>>>, 28 next_id: Arc<Mutex<u64>>, 29 } 30 31 // GET /tasks — return the whole list. 32 async fn list_tasks(State(state): State<AppState>) -> Json<Vec<Task>> { 33 let tasks = state.tasks.lock().unwrap(); 34 Json(tasks.clone()) 35 } 36 37 // POST /tasks — create a task, reply 201 with the created resource. 38 async fn create_task( 39 State(state): State<AppState>, 40 Json(body): Json<NewTask>, 41 ) -> impl IntoResponse { 42 let mut id_guard = state.next_id.lock().unwrap(); 43 *id_guard += 1; 44 let task = Task { id: *id_guard, title: body.title, done: false }; 45 state.tasks.lock().unwrap().push(task.clone()); 46 (StatusCode::CREATED, Json(task)) 47 } 48 49 // GET /tasks/{id} — 200 with the task, or 404 if it doesn't exist. 50 // Returning Result<T, E> where both implement IntoResponse is idiomatic. 51 async fn get_task( 52 State(state): State<AppState>, 53 Path(id): Path<u64>, 54 ) -> Result<Json<Task>, StatusCode> { 55 let tasks = state.tasks.lock().unwrap(); 56 tasks 57 .iter() 58 .find(|t| t.id == id) 59 .cloned() 60 .map(Json) 61 .ok_or(StatusCode::NOT_FOUND) 62 } 63 64 // The router builder — reusable from tests and from main. 65 fn app() -> Router { 66 let state = AppState::default(); 67 Router::new() 68 .route("/tasks", get(list_tasks).post(create_task)) 69 .route("/tasks/{id}", get(get_task)) 70 .with_state(state) 71 } 72 73 #[tokio::main] 74 async fn main() { 75 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 76 println!("listening on {}", listener.local_addr().unwrap()); 77 axum::serve(listener, app()).await.unwrap(); 78 } ``` A few production-relevant notes on this code: * **`State<AppState>` is the dependency-injection mechanism.** `.with_state(state)` attaches it to the router; the `State(state)` extractor pulls it into each handler. In a real app, `AppState` holds a database connection pool, config, an HTTP client, etc. (Full treatment in [State Management](/16-web-apis/06-state-management/) and [Database Integration](/17-database/).) * **`Arc` + `Mutex` is how you share mutable state across concurrent handlers.** `Arc` gives shared ownership (multiple handlers point at the same data); `Mutex` makes concurrent mutation safe. The compiler will not let you share `&mut` across tasks without one of these — that’s the borrow checker preventing data races at compile time. See [Arc/Mutex Pattern](/11-async/12-arc-mutex-pattern/). * **The `Result<Json<Task>, StatusCode>` return** lets `get_task` produce either a `200` with JSON or a bare `404`. For richer, structured errors (a JSON error body, mapping different error kinds to different statuses), see [Error Handling in Web Apps](/16-web-apis/10-error-handling-web/). > **Note:** Handlers can also be inline async closures, which feel even more Express-like for trivial routes: `.route("/", get(|| async { "root" }))`. Use named `async fn`s once a handler does anything non-trivial — they’re easier to test and read. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [Axum documentation (docs.rs)](https://docs.rs/axum/latest/axum/): the canonical reference; the crate-level docs are excellent. * [Axum examples (GitHub)](https://github.com/tokio-rs/axum/tree/main/examples): runnable examples for nearly every feature in this section. * [`axum::serve` docs](https://docs.rs/axum/latest/axum/fn.serve.html) and [`Router` docs](https://docs.rs/axum/latest/axum/struct.Router.html). * Within this guide: * [Setting Up an Axum Project](/16-web-apis/02-axum-setup/): deps, features, and a hello-server from scratch. * [Routing](/16-web-apis/03-routing/): path/query params, method routing, nested routers, fallbacks. * [Extractors](/16-web-apis/04-extractors/): how `Path`, `Query`, `Json`, `State` work and how to write your own. * [Request and Response Handling](/16-web-apis/07-request-response/) — `IntoResponse`, status codes, headers. * [JSON APIs](/16-web-apis/08-json-apis/) — a fuller CRUD resource with serde. * [State Management](/16-web-apis/06-state-management/) — sharing a DB pool / config via `State<T>`. * [Middleware](/16-web-apis/05-middleware/) — Tower layers, `tower-http`, `from_fn`. * [Framework Comparison](/16-web-apis/00-framework-comparison/) — Axum vs Actix Web vs Rocket vs Express/Nest. * Background: [The Tokio Runtime](/11-async/02-tokio-intro/), [Tokio Setup](/11-async/03-tokio-setup/), [Promises vs Futures](/11-async/00-promises-vs-futures/). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A second endpoint [Section titled “Exercise 1: A second endpoint”](#exercise-1-a-second-endpoint) **Difficulty:** Beginner **Objective:** Get comfortable adding routes and returning JSON. **Instructions:** Starting from the first Rust server in this page, add a `GET /version` route that returns the JSON `{"version":"1.0.0","name":"task-api"}`. Define a `#[derive(Serialize)]` struct for the response and wire it into the router. Solution ```rust 1 use axum::{routing::get, Json, Router}; 2 use serde::Serialize; 3 4 #[derive(Serialize)] 5 struct Version { 6 version: &'static str, 7 name: &'static str, 8 } 9 10 async fn version() -> Json<Version> { 11 Json(Version { version: "1.0.0", name: "task-api" }) 12 } 13 14 #[tokio::main] 15 async fn main() { 16 let app = Router::new().route("/version", get(version)); 17 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 18 println!("listening on {}", listener.local_addr().unwrap()); 19 axum::serve(listener, app).await.unwrap(); 20 } ``` Hitting `GET /version` returns `{"version":"1.0.0","name":"task-api"}`. ### Exercise 2: Echo with a path parameter and a status code [Section titled “Exercise 2: Echo with a path parameter and a status code”](#exercise-2-echo-with-a-path-parameter-and-a-status-code) **Difficulty:** Intermediate **Objective:** Combine a `Path` extractor with a tuple `(StatusCode, ...)` response. **Instructions:** Write a `GET /echo/{message}` handler that returns the message wrapped in JSON as `{"echo":"<message>"}` with an explicit `200 OK` status, using a `(StatusCode, Json<...>)` tuple. The `{message}` parameter is a `String`. Solution ```rust 1 use axum::{ 2 extract::Path, 3 http::StatusCode, 4 response::IntoResponse, 5 routing::get, 6 Json, Router, 7 }; 8 use serde::Serialize; 9 10 #[derive(Serialize)] 11 struct Echo { 12 echo: String, 13 } 14 15 async fn echo(Path(message): Path<String>) -> impl IntoResponse { 16 (StatusCode::OK, Json(Echo { echo: message })) 17 } 18 19 #[tokio::main] 20 async fn main() { 21 let app = Router::new().route("/echo/{message}", get(echo)); 22 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 23 axum::serve(listener, app).await.unwrap(); 24 } ``` `GET /echo/hello` returns `{"echo":"hello"}` with status `200 OK`. ### Exercise 3: Update a task (PUT) against shared state [Section titled “Exercise 3: Update a task (PUT) against shared state”](#exercise-3-update-a-task-put-against-shared-state) **Difficulty:** Advanced **Objective:** Add a mutating endpoint to the real-world example, using `State` and a `Result` return that distinguishes “found and updated” from “not found.” **Instructions:** Extend the Real-World Example with `PUT /tasks/{id}` that accepts a JSON body `{"done": true}` and toggles the matching task’s `done` field. Return `Json<Task>` on success and `StatusCode::NOT_FOUND` if no task has that id. Chain the new method onto the existing `/tasks/{id}` route. Solution ```rust 1 use axum::{ 2 extract::{Path, State}, 3 http::StatusCode, 4 routing::get, 5 Json, Router, 6 }; 7 use serde::{Deserialize, Serialize}; 8 use std::sync::{Arc, Mutex}; 9 10 #[derive(Clone, Serialize)] 11 struct Task { 12 id: u64, 13 title: String, 14 done: bool, 15 } 16 17 #[derive(Deserialize)] 18 struct UpdateTask { 19 done: bool, 20 } 21 22 #[derive(Clone, Default)] 23 struct AppState { 24 tasks: Arc<Mutex<Vec<Task>>>, 25 } 26 27 async fn get_task( 28 State(state): State<AppState>, 29 Path(id): Path<u64>, 30 ) -> Result<Json<Task>, StatusCode> { 31 let tasks = state.tasks.lock().unwrap(); 32 tasks.iter().find(|t| t.id == id).cloned().map(Json).ok_or(StatusCode::NOT_FOUND) 33 } 34 35 // PUT /tasks/{id} — toggle `done`, or 404 if the task is missing. 36 async fn update_task( 37 State(state): State<AppState>, 38 Path(id): Path<u64>, 39 Json(body): Json<UpdateTask>, 40 ) -> Result<Json<Task>, StatusCode> { 41 let mut tasks = state.tasks.lock().unwrap(); 42 match tasks.iter_mut().find(|t| t.id == id) { 43 Some(task) => { 44 task.done = body.done; 45 Ok(Json(task.clone())) 46 } 47 None => Err(StatusCode::NOT_FOUND), 48 } 49 } 50 51 fn app() -> Router { 52 let state = AppState { 53 tasks: Arc::new(Mutex::new(vec![Task { 54 id: 1, 55 title: "Write the docs".to_string(), 56 done: false, 57 }])), 58 }; 59 Router::new() 60 .route("/tasks/{id}", get(get_task).put(update_task)) 61 .with_state(state) 62 } 63 64 #[tokio::main] 65 async fn main() { 66 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 67 axum::serve(listener, app()).await.unwrap(); 68 } ``` `PUT /tasks/1` with body `{"done":true}` returns `{"id":1,"title":"Write the docs","done":true}`; `PUT /tasks/999` returns `404 Not Found`. Note `iter_mut()` — you need a mutable iterator to modify the task in place, and the `Mutex` guard (`tasks`) is what makes that mutation safe across concurrent requests. # Setting Up an Axum Project > Scaffold an Axum project from scratch: the axum plus tokio dependencies, Cargo features, module layout, and a hello-server you can run and curl, vs Express setup. Before you can write a single route, you need a project that compiles. This page is the “create-react-app moment” for Rust web APIs: the exact dependencies, features, project layout, and a hello-server you can run and `curl`. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) [Axum](https://docs.rs/axum) is a web framework built on top of the [Tokio](https://tokio.rs) async runtime and the [Tower](https://docs.rs/tower) middleware ecosystem. Unlike Express, where `npm install express` gives you a server you can start immediately, an Axum app has **two** mandatory pieces: the framework (`axum`) and an async runtime (`tokio`). This page shows you how to wire them together, which Cargo features to turn on, how to lay out a real project, and how to get a server responding on `localhost:3000`. The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the **2024 edition**, which `cargo new` selects automatically. We target **axum 0.8** and **tokio 1.x** throughout. > **Note:** This page covers project *setup*. The mechanics of routing, handlers, and `axum::serve` are covered in [Axum Fundamentals](/16-web-apis/01-axum-basics/); deeper routing in [Routing in Axum](/16-web-apis/03-routing/). For *why* you might choose Axum over Actix Web or Rocket, see [Choosing a Rust Web Framework](/16-web-apis/00-framework-comparison/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In Node, scaffolding an Express server is a two-command affair, and the runtime (Node/V8) is already installed: ```bash 1 # Create the project 2 mkdir my-api && cd my-api 3 npm init -y 4 5 # One dependency gets you a working HTTP server 6 npm install express 7 npm install --save-dev typescript @types/express @types/node tsx ``` A minimal `package.json` and a typical layout: ```json 1 { 2 "name": "my-api", 3 "version": "1.0.0", 4 "type": "module", 5 "scripts": { 6 "dev": "tsx watch src/index.ts", 7 "start": "node dist/index.js", 8 "build": "tsc" 9 }, 10 "dependencies": { 11 "express": "^5.1.0" 12 }, 13 "devDependencies": { 14 "typescript": "^5.6.0", 15 "@types/express": "^5.0.0", 16 "@types/node": "^22.0.0", 17 "tsx": "^4.19.0" 18 } 19 } ``` ```text 1 my-api/ 2 ├── package.json 3 ├── tsconfig.json 4 └── src/ 5 ├── index.ts # entry point: creates the app, listens 6 ├── routes.ts # route definitions 7 └── handlers.ts # request handlers ``` src/index.ts ```typescript 1 import express from "express"; 2 3 const app = express(); 4 5 app.get("/", (_req, res) => { 6 res.send("Hello, world!"); 7 }); 8 9 const port = 3000; 10 app.listen(port, () => { 11 console.log(`listening on http://localhost:${port}`); 12 }); ``` ```bash 1 npm run dev 2 # listening on http://localhost:3000 ``` Two things to notice for the comparison ahead: the **runtime is implicit** (Node ships an event loop), and **one dependency** (`express`) is enough. Rust differs on both counts. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) First, scaffold the project and add dependencies: ```bash 1 cargo new my-api 2 cd my-api 3 cargo add axum 4 cargo add tokio --features full ``` > **Note:** `cargo add` has been built into Cargo since 1.62. There is no separate `cargo-edit` tool to install. It edits `Cargo.toml` for you and resolves the newest compatible version. The resulting `Cargo.toml` looks like this (versions are what resolved at the time of writing; yours may be newer): ```toml 1 [package] 2 name = "my-api" 3 version = "0.1.0" 4 edition = "2024" 5 6 [dependencies] 7 axum = "0.8.9" 8 tokio = { version = "1.52.3", features = ["full"] } ``` Now the entry point: src/main.rs ```rust 1 use axum::{routing::get, Router}; 2 use tokio::net::TcpListener; 3 4 #[tokio::main] 5 async fn main() { 6 // Build the application with a single route. 7 let app = Router::new().route("/", get(hello)); 8 9 // Bind a TCP listener to a local address. 10 let listener = TcpListener::bind("127.0.0.1:3000").await.unwrap(); 11 println!("listening on http://{}", listener.local_addr().unwrap()); 12 13 // Run the server. This future never resolves until the process is stopped. 14 axum::serve(listener, app).await.unwrap(); 15 } 16 17 // A handler is just an async function returning something that implements `IntoResponse`. 18 async fn hello() -> &'static str { 19 "Hello, world!" 20 } ``` Run it: ```bash 1 cargo run ``` Real output: ```text 1 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.16s 2 Running `target/debug/my-api` 3 listening on http://127.0.0.1:3000 ``` In another terminal, `curl` it. This is the real response, headers included: ```bash 1 curl -i http://127.0.0.1:3000/ ``` ```text 1 HTTP/1.1 200 OK 2 content-type: text/plain; charset=utf-8 3 content-length: 13 4 date: Mon, 01 Jun 2026 11:44:03 GMT 5 6 Hello, world! ``` > **Tip:** `cargo run` compiles *and* runs in one step, so it is the closest analogue to `npm run dev`. For an auto-reloading dev loop like `tsx watch`, install `cargo-watch` (`cargo install cargo-watch`) and run `cargo watch -x run`. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) Let’s walk the differences a TypeScript developer will trip over. ### Why two dependencies, not one? [Section titled “Why two dependencies, not one?”](#why-two-dependencies-not-one) In Node, the event loop is part of the runtime; it is always there. In Rust, **the standard library does not ship an async runtime.** `async`/`await` is built into the language, but the thing that actually *drives* those futures to completion (the executor, the I/O reactor, the timer wheel) is a library you choose. Tokio is the de-facto standard. So the split is: * **`axum`** — the web framework: routers, extractors, responses. * **`tokio`** — the async runtime: it polls futures, manages the thread pool, and provides the async `TcpListener`. This is the opposite of JavaScript, where Promises are **eager** (they start running the moment they are created) and the runtime is baked in. Rust futures are **lazy**: nothing happens until a runtime polls them. `axum::serve(...)` returns a future, and it is the `.await`, driven by the Tokio runtime, that actually runs the server. See [Section 11: Async](/11-async/) for the full mental model. ### `#[tokio::main]` [Section titled “#\[tokio::main\]”](#tokiomain) ```rust 1 #[tokio::main] 2 async fn main() { 3 // ... 4 } ``` `main` cannot itself be `async`: the operating system calls a plain, synchronous entry point. The `#[tokio::main]` attribute macro rewrites your `async fn main` into a regular `fn main` that starts the Tokio runtime and blocks on your async body. Conceptually it expands to roughly: ```rust 1 fn main() { 2 tokio::runtime::Runtime::new() 3 .unwrap() 4 .block_on(async { 5 // ... your code ... 6 }); 7 } ``` This is *not* a decorator in the JavaScript/Python sense: macros operate on the syntax tree at compile time and generate new code. (See [Section 14: Macros](/14-macros/).) ### `tokio::net::TcpListener` and `axum::serve` [Section titled “tokio::net::TcpListener and axum::serve”](#tokionettcplistener-and-axumserve) ```rust 1 let listener = TcpListener::bind("127.0.0.1:3000").await.unwrap(); 2 axum::serve(listener, app).await.unwrap(); ``` In axum 0.8 you bind a Tokio `TcpListener` yourself and hand it to `axum::serve(listener, app)`. This is deliberately explicit: *you* own the socket, which makes it trivial to bind to `0.0.0.0` in production, pick a port from the environment, or pass a pre-bound socket from systemd. > **Warning:** Older tutorials show `axum::Server::bind(&addr).serve(app.into_make_service())`. That builder was **removed** in axum 0.7 and does not exist in 0.8. `axum::Server` no longer exists at all. Always use `axum::serve(TcpListener, app)`. See [Common Pitfalls](#common-pitfalls). The two `.unwrap()` calls turn a `Result` into a panic on error (e.g. the port is already taken). That is fine for a setup example; production code should handle these. See [Error Handling in Web Handlers](/16-web-apis/10-error-handling-web/). ### `&'static str` as a response [Section titled “&'static str as a response”](#static-str-as-a-response) ```rust 1 async fn hello() -> &'static str { 2 "Hello, world!" 3 } ``` A handler returns any type implementing axum’s `IntoResponse` trait. `&'static str` implements it, producing a `200 OK` with `content-type: text/plain; charset=utf-8`, which is exactly what the `curl` headers above show. Returning JSON, status codes, or custom types is covered in [Request and Response Handling](/16-web-apis/07-request-response/) and [JSON REST APIs](/16-web-apis/08-json-apis/). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concern | Express (Node) | Axum (Rust) | | --------------------- | --------------------------------------------- | --------------------------------------------------- | | Runtime | Built into Node | Separate crate (`tokio`), you pick it | | Dependencies to start | `express` only | `axum` **and** `tokio` | | Entry point | `app.listen(port, cb)` | `axum::serve(TcpListener, app).await` | | Async model | Eager Promises, implicit loop | Lazy futures, explicit runtime via `#[tokio::main]` | | Socket ownership | Hidden by `app.listen` | Explicit `TcpListener::bind(...)` | | Reload-on-save | `tsx watch` / `nodemon` (built into workflow) | `cargo watch -x run` (extra tool) | | Type checking | Optional layer (TypeScript) | Always on (the compiler) | | Production artifact | `node dist/index.js` + `node_modules/` | A single self-contained binary | The headline difference is the **explicit runtime**. Once you internalize “futures are lazy and a runtime polls them,” the rest of Axum’s design (extractors, layers, `IntoResponse`) feels natural rather than magical. *** ## Choosing Tokio features [Section titled “Choosing Tokio features”](#choosing-tokio-features) `tokio = { version = "1", features = ["full"] }` is the simplest choice and the right default while you are learning. `"full"` turns on every feature (the multi-threaded runtime, networking, timers, the `macros` for `#[tokio::main]`, and more). For production you may want to trim it down. The pieces an Axum server actually needs are: ```toml 1 [dependencies] 2 tokio = { version = "1", features = ["rt-multi-thread", "net", "macros"] } ``` * `rt-multi-thread` — the work-stealing multi-threaded scheduler (the default flavor of `#[tokio::main]`). * `net` — async TCP, used by `TcpListener`. * `macros` — provides `#[tokio::main]` and `#[tokio::test]`. > **Tip:** While learning, just use `features = ["full"]`. Optimizing the feature set is a compile-time and binary-size concern you can revisit later; it does not change runtime behavior. ### What `cargo add axum` enables [Section titled “What cargo add axum enables”](#what-cargo-add-axum-enables) `cargo add axum` prints the feature flags it turned on. Here is the real output (trimmed to the feature list); a `+` means enabled by default, a `-` means available but off: ```text 1 Adding axum v0.8.9 to dependencies 2 Features: 3 + form 4 + http1 5 + json 6 + matched-path 7 + original-uri 8 + query 9 + tokio 10 + tower-log 11 + tracing 12 - http2 13 - macros 14 - multipart 15 - ws ``` The defaults already include JSON, query strings, and form parsing. Three optional features matter for later pages in this section: * `multipart` — required for file uploads (see [File Uploads](/16-web-apis/17-file-uploads/)). Enable with `cargo add axum --features multipart`. * `ws` — required for WebSockets (see [WebSockets with Axum](/16-web-apis/15-websockets/)). Enable with `cargo add axum --features ws`. * `http2` — HTTP/2 support, off by default. *** ## Recommended project layout [Section titled “Recommended project layout”](#recommended-project-layout) A one-file `main.rs` is fine for a toy. Real APIs split routing, handlers, and state into modules. Here is a layout that mirrors the Express `src/index.ts` + `src/routes.ts` + `src/handlers.ts` split and scales cleanly: ```text 1 my-api/ 2 ├── Cargo.toml 3 └── src/ 4 ├── main.rs # entry point: logging, build router, serve 5 ├── routes.rs # assemble the Router 6 └── handlers.rs # the async fn handlers ``` > **Note:** In Rust, modules are declared, not auto-discovered. `mod routes;` in `main.rs` tells the compiler to load `src/routes.rs`. There is no equivalent of Node’s “any file under `src/` is importable.” See [Section 12: Modules & Packages](/12-modules-packages/). **`src/main.rs`** — wires everything together and starts the server: ```rust 1 mod handlers; 2 mod routes; 3 4 use tokio::net::TcpListener; 5 6 #[tokio::main] 7 async fn main() { 8 // Initialize structured logging. RUST_LOG controls the level (e.g. RUST_LOG=info). 9 tracing_subscriber::fmt() 10 .with_env_filter( 11 tracing_subscriber::EnvFilter::try_from_default_env() 12 .unwrap_or_else(|_| "info".into()), 13 ) 14 .init(); 15 16 let app = routes::app(); 17 18 let listener = TcpListener::bind("127.0.0.1:3000").await.unwrap(); 19 tracing::info!("listening on http://{}", listener.local_addr().unwrap()); 20 21 axum::serve(listener, app).await.unwrap(); 22 } ``` **`src/routes.rs`** — the single source of truth for the API surface: ```rust 1 use axum::{routing::get, Router}; 2 3 use crate::handlers; 4 5 /// Assemble the full application router. Keeping this in one place makes the 6 /// API surface easy to read and unit-test. 7 pub fn app() -> Router { 8 Router::new() 9 .route("/", get(handlers::root)) 10 .route("/health", get(handlers::health)) 11 } ``` **`src/handlers.rs`** — the request handlers: ```rust 1 use axum::Json; 2 use serde::Serialize; 3 4 #[derive(Serialize)] 5 pub struct Health { 6 status: &'static str, 7 version: &'static str, 8 } 9 10 pub async fn root() -> &'static str { 11 "Hello, world!" 12 } 13 14 pub async fn health() -> Json<Health> { 15 Json(Health { 16 status: "ok", 17 version: env!("CARGO_PKG_VERSION"), 18 }) 19 } ``` This layout needs four crates. Add them with: ```bash 1 cargo add axum 2 cargo add tokio --features full 3 cargo add serde --features derive 4 cargo add serde_json 5 cargo add tracing 6 cargo add tracing-subscriber --features env-filter ``` `tracing` + `tracing-subscriber` give you structured logging (the Rust analogue of `pino` or `winston`); `serde` powers the JSON response (see [Section 15: Serialization](/15-serialization/)). Running it: ```bash 1 RUST_LOG=info cargo run ``` Real log output (the tracing-subscriber `fmt` formatter; it adds terminal colors when attached to a TTY): ```text 1 2026-06-01T11:49:32.033250Z INFO hello_server: listening on http://127.0.0.1:3000 ``` And the `/health` endpoint returns real JSON: ```bash 1 curl -i http://127.0.0.1:3000/health ``` ```text 1 HTTP/1.1 200 OK 2 content-type: application/json 3 content-length: 33 4 date: Mon, 01 Jun 2026 11:45:03 GMT 5 6 {"status":"ok","version":"0.1.0"} ``` > **Tip:** `env!("CARGO_PKG_VERSION")` reads the `version` from `Cargo.toml` at compile time, so `/health` always reports the right build version with zero maintenance. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting `#[tokio::main]` [Section titled “Pitfall 1: Forgetting #\[tokio::main\]”](#pitfall-1-forgetting-tokiomain) A plain `async fn main` won’t even compile, and a plain `fn main` can’t use `.await`. If you write `fn main` and call `.await` inside, you get a real error: ```rust 1 use axum::{routing::get, Router}; 2 use tokio::net::TcpListener; 3 4 // does not compile (error[E0728]): missing #[tokio::main], so main is not async 5 fn main() { 6 let app = Router::new().route("/", get(|| async { "hi" })); 7 let listener = TcpListener::bind("127.0.0.1:3000").await.unwrap(); 8 axum::serve(listener, app).await.unwrap(); 9 } ``` The compiler says exactly what’s wrong: ```text 1 error[E0728]: `await` is only allowed inside `async` functions and blocks 2 --> src/main.rs:7:56 3 | 4 5 | fn main() { 5 | --------- this is not `async` 6 6 | let app = Router::new().route("/", get(|| async { "hi" })); 7 7 | let listener = TcpListener::bind("127.0.0.1:3000").await.unwrap(); 8 | ^^^^^ only allowed inside `async` functions and blocks ``` **Fix:** add `#[tokio::main]` above `async fn main`. ### Pitfall 2: Adding `tokio` without the runtime features [Section titled “Pitfall 2: Adding tokio without the runtime features”](#pitfall-2-adding-tokio-without-the-runtime-features) A very common surprise: `cargo add tokio` (with no `--features`) adds Tokio with *no* features enabled, so `#[tokio::main]` has no runtime to start: ```toml 1 [dependencies] 2 tokio = "1.52.3" # no features — the macro can't find a runtime ``` ```text 1 error: The default runtime flavor is `multi_thread`, but the `rt-multi-thread` feature is disabled. 2 --> src/main.rs:4:1 3 | 4 4 | #[tokio::main] 5 | ^^^^^^^^^^^^^^ ``` **Fix:** add the features: `cargo add tokio --features full` (simplest) or at minimum `["rt-multi-thread", "net", "macros"]`. ### Pitfall 3: Using the removed `axum::Server` API [Section titled “Pitfall 3: Using the removed axum::Server API”](#pitfall-3-using-the-removed-axumserver-api) The single most common copy-paste failure from old tutorials: ```rust 1 use axum::{routing::get, Router}; 2 3 #[tokio::main] 4 async fn main() { 5 let app = Router::new().route("/", get(|| async { "hi" })); 6 // does not compile (error[E0433]): axum::Server was removed in 0.7 7 axum::Server::bind(&"0.0.0.0:3000".parse().unwrap()) 8 .serve(app.into_make_service()) 9 .await 10 .unwrap(); 11 } ``` ```text 1 error[E0433]: failed to resolve: could not find `Server` in `axum` 2 --> src/main.rs:7:11 3 | 4 7 | axum::Server::bind(&"0.0.0.0:3000".parse().unwrap()) 5 | ^^^^^^ could not find `Server` in `axum` ``` **Fix:** bind a Tokio listener and call `axum::serve`: ```rust 1 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 2 axum::serve(listener, app).await.unwrap(); ``` ### Pitfall 4: Expecting modules to be auto-discovered [Section titled “Pitfall 4: Expecting modules to be auto-discovered”](#pitfall-4-expecting-modules-to-be-auto-discovered) Creating `src/handlers.rs` does **not** make it part of the crate. You must declare `mod handlers;` in `main.rs` (or another module in the tree). A forgotten `mod` produces an “unresolved import” / “failed to resolve” error, not silent omission. This trips up developers used to Node’s filesystem-based importing. ### Pitfall 5: Reaching for `:id`-style routes [Section titled “Pitfall 5: Reaching for :id-style routes”](#pitfall-5-reaching-for-id-style-routes) If you start adding parameterized routes, note that axum 0.8 uses `{id}`, **not** the Express-style `:id`. Writing `:id` is a 0.7-era habit that behaves differently in 0.8. This is covered in [Routing in Axum](/16-web-apis/03-routing/). *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Use `features = ["full"]` for tokio while learning;** trim to `["rt-multi-thread", "net", "macros"]` once the app is real and you care about compile time. * **Keep `main` thin.** Logging setup, router assembly, and serving: that’s it. Push routes into a `routes` module and handlers into a `handlers` module from day one; it costs nothing and scales. * **Expose the router from a function** (`pub fn app() -> Router`). This makes the whole app testable without binding a port; see the test below. * **Add `tracing` early.** Structured logs from the first commit beat retrofitting `println!` later. Request-level logging via `TraceLayer` lives in [Middleware and Layers](/16-web-apis/05-middleware/). * **Bind `127.0.0.1` in development, `0.0.0.0` in production**, and read the address/port from the environment for deployment. See [Deploying Axum Applications](/16-web-apis/19-deployment/). * **Wire in graceful shutdown** before you ship, so in-flight requests finish on deploy (shown below). * **Commit `Cargo.lock`** for binaries (an API is a binary). It pins exact dependency versions for reproducible builds: the equivalent of committing `package-lock.json`. ### Testing the router without a socket [Section titled “Testing the router without a socket”](#testing-the-router-without-a-socket) Because `app()` returns a `Router`, you can drive it directly in tests using Tower’s `oneshot`, with no network involved: ```bash 1 cargo add --dev tower 2 cargo add --dev http-body-util ``` tests/health.rs ```rust 1 use axum::body::Body; 2 use axum::http::{Request, StatusCode}; 3 use http_body_util::BodyExt; 4 use tower::ServiceExt; // brings `oneshot` into scope 5 6 #[tokio::test] 7 async fn health_returns_ok_json() { 8 use axum::{routing::get, Router}; 9 let app = Router::new().route( 10 "/health", 11 get(|| async { axum::Json(serde_json::json!({ "status": "ok" })) }), 12 ); 13 14 let response = app 15 .oneshot( 16 Request::builder() 17 .uri("/health") 18 .body(Body::empty()) 19 .unwrap(), 20 ) 21 .await 22 .unwrap(); 23 24 assert_eq!(response.status(), StatusCode::OK); 25 26 let body = response.into_body().collect().await.unwrap().to_bytes(); 27 assert_eq!(&body[..], br#"{"status":"ok"}"#); 28 } ``` Real test output: ```text 1 running 1 test 2 test health_returns_ok_json ... ok 3 4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` This is far faster and more reliable than booting a real server and `curl`-ing it: the analogue of `supertest` against an Express `app`, but built into the type system. More on testing in [Section 13: Testing](/13-testing/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored entry point: structured logging, configuration from the environment, binding `0.0.0.0`, and graceful shutdown so a deploy doesn’t drop in-flight requests. src/main.rs ```rust 1 use std::net::SocketAddr; 2 3 use axum::{routing::get, Json, Router}; 4 use serde::Serialize; 5 use tokio::net::TcpListener; 6 use tokio::signal; 7 8 #[derive(Serialize)] 9 struct Health { 10 status: &'static str, 11 version: &'static str, 12 } 13 14 async fn root() -> &'static str { 15 "Hello, world!" 16 } 17 18 async fn health() -> Json<Health> { 19 Json(Health { 20 status: "ok", 21 version: env!("CARGO_PKG_VERSION"), 22 }) 23 } 24 25 fn app() -> Router { 26 Router::new() 27 .route("/", get(root)) 28 .route("/health", get(health)) 29 } 30 31 #[tokio::main] 32 async fn main() { 33 // Structured logging; RUST_LOG (e.g. "info") controls verbosity. 34 tracing_subscriber::fmt() 35 .with_env_filter( 36 tracing_subscriber::EnvFilter::try_from_default_env() 37 .unwrap_or_else(|_| "info".into()), 38 ) 39 .init(); 40 41 // Read the bind address from the environment, defaulting to all interfaces. 42 let addr: SocketAddr = std::env::var("BIND_ADDR") 43 .unwrap_or_else(|_| "0.0.0.0:3000".to_string()) 44 .parse() 45 .expect("BIND_ADDR must be a valid socket address"); 46 47 let listener = TcpListener::bind(addr).await.unwrap(); 48 tracing::info!("listening on http://{}", listener.local_addr().unwrap()); 49 50 axum::serve(listener, app()) 51 .with_graceful_shutdown(shutdown_signal()) 52 .await 53 .unwrap(); 54 } 55 56 /// Resolves when the user presses Ctrl-C, letting in-flight requests finish. 57 async fn shutdown_signal() { 58 signal::ctrl_c() 59 .await 60 .expect("failed to install Ctrl-C handler"); 61 tracing::info!("shutdown signal received, draining connections"); 62 } ``` Dependencies for this example: ```bash 1 cargo add axum 2 cargo add tokio --features full 3 cargo add serde --features derive 4 cargo add tracing 5 cargo add tracing-subscriber --features env-filter ``` Three production details worth calling out: * **`with_graceful_shutdown`** stops accepting new connections on Ctrl-C (or `SIGTERM` from an orchestrator if you extend `shutdown_signal`) and waits for active requests to complete before the process exits. * **`BIND_ADDR` from the environment:** twelve-factor config. Default to `0.0.0.0:3000` so it works in a container without extra setup, but allow override. * **No `panic`-on-startup behavior is hidden.** `bind` and `serve` failures still surface; for handler-level errors, use a typed error response as in [Error Handling in Web Handlers](/16-web-apis/10-error-handling-web/). > **Note:** Choosing the runtime flavor is a one-liner. The default is multi-threaded; for a low-concurrency sidecar you can switch to a single-threaded runtime with `#[tokio::main(flavor = "current_thread")]`. Both compile against the same Axum code. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [Axum documentation (docs.rs)](https://docs.rs/axum): the API reference; check `axum::serve` and `Router`. * [Axum GitHub examples](https://github.com/tokio-rs/axum/tree/main/examples): `hello-world`, `graceful-shutdown`, and more, kept current with the latest release. * [Tokio documentation (docs.rs)](https://docs.rs/tokio): runtime, `TcpListener`, and the `#[tokio::main]` macro. * [The Tokio Tutorial](https://tokio.rs/tokio/tutorial): the canonical introduction to the async runtime. * [tracing-subscriber docs](https://docs.rs/tracing-subscriber): configuring logging output and filters. ### Related Sections [Section titled “Related Sections”](#related-sections) * [Section 16 README](/16-web-apis/): the full Web APIs section index. * [Choosing a Rust Web Framework](/16-web-apis/00-framework-comparison/) — Axum vs Actix Web vs Rocket vs Express/Nest. * [Axum Fundamentals](/16-web-apis/01-axum-basics/) — `Router`, handlers, and `axum::serve` fundamentals. * [Routing in Axum](/16-web-apis/03-routing/) — path params (`{id}`), query params, nested routers. * [Shared Application State in Axum](/16-web-apis/06-state-management/) — sharing a DB pool or config with `State<T>`. * [Deploying Axum Applications](/16-web-apis/19-deployment/) — release builds, Docker multi-stage, reverse proxies. * [Section 11: Async](/11-async/) — futures, `async`/`await`, and why Rust futures are lazy. * [Section 12: Modules & Packages](/12-modules-packages/) — `mod`, crates, and project structure. * [Section 15: Serialization](/15-serialization/) — serde and JSON, used by the `/health` handler. * [Section 17: Database](/17-database/): adding a real data store behind your API. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Scaffold and run [Section titled “Exercise 1: Scaffold and run”](#exercise-1-scaffold-and-run) **Difficulty:** Beginner **Objective:** Build the hello-server from scratch and confirm it responds. **Instructions:** 1. Run `cargo new greeter` and `cd` into it. 2. Add `axum` and `tokio` (with the `full` feature). 3. Write a server that responds with `"Hello from Rust!"` on `GET /`. 4. Run it with `cargo run` and verify with `curl http://127.0.0.1:3000/`. Solution ```bash 1 cargo new greeter 2 cd greeter 3 cargo add axum 4 cargo add tokio --features full ``` src/main.rs ```rust 1 use axum::{routing::get, Router}; 2 use tokio::net::TcpListener; 3 4 #[tokio::main] 5 async fn main() { 6 let app = Router::new().route("/", get(hello)); 7 8 let listener = TcpListener::bind("127.0.0.1:3000").await.unwrap(); 9 println!("listening on http://{}", listener.local_addr().unwrap()); 10 11 axum::serve(listener, app).await.unwrap(); 12 } 13 14 async fn hello() -> &'static str { 15 "Hello from Rust!" 16 } ``` ```bash 1 cargo run 2 # in another terminal: 3 curl http://127.0.0.1:3000/ 4 # Hello from Rust! ``` ### Exercise 2: Split into modules and add `/health` [Section titled “Exercise 2: Split into modules and add /health”](#exercise-2-split-into-modules-and-add-health) **Difficulty:** Intermediate **Objective:** Refactor the single-file server into the recommended `main.rs` / `routes.rs` / `handlers.rs` layout, and add a `GET /health` endpoint that returns JSON. **Instructions:** 1. Move the handlers into `src/handlers.rs` and the router into `src/routes.rs`. 2. Declare both modules in `main.rs`. 3. Add a `health` handler returning JSON like `{"status":"ok"}` (add `serde`/`serde_json` and use the `Json` type). 4. Verify both routes with `curl`. Solution ```bash 1 cargo add axum 2 cargo add tokio --features full 3 cargo add serde --features derive 4 cargo add serde_json ``` src/main.rs ```rust 1 mod handlers; 2 mod routes; 3 4 use tokio::net::TcpListener; 5 6 #[tokio::main] 7 async fn main() { 8 let app = routes::app(); 9 let listener = TcpListener::bind("127.0.0.1:3000").await.unwrap(); 10 println!("listening on http://{}", listener.local_addr().unwrap()); 11 axum::serve(listener, app).await.unwrap(); 12 } ``` src/routes.rs ```rust 1 use axum::{routing::get, Router}; 2 3 use crate::handlers; 4 5 pub fn app() -> Router { 6 Router::new() 7 .route("/", get(handlers::root)) 8 .route("/health", get(handlers::health)) 9 } ``` src/handlers.rs ```rust 1 use axum::Json; 2 use serde::Serialize; 3 4 #[derive(Serialize)] 5 pub struct Health { 6 status: &'static str, 7 } 8 9 pub async fn root() -> &'static str { 10 "Hello, world!" 11 } 12 13 pub async fn health() -> Json<Health> { 14 Json(Health { status: "ok" }) 15 } ``` ```bash 1 cargo run 2 curl http://127.0.0.1:3000/ # Hello, world! 3 curl http://127.0.0.1:3000/health # {"status":"ok"} ``` ### Exercise 3: Graceful shutdown and env-configured binding [Section titled “Exercise 3: Graceful shutdown and env-configured binding”](#exercise-3-graceful-shutdown-and-env-configured-binding) **Difficulty:** Advanced **Objective:** Make the server production-ready: bind from an environment variable and shut down cleanly on Ctrl-C. **Instructions:** 1. Read the bind address from a `BIND_ADDR` environment variable, defaulting to `0.0.0.0:3000`. 2. Add graceful shutdown using `axum::serve(...).with_graceful_shutdown(...)` and `tokio::signal::ctrl_c`. 3. Run with `BIND_ADDR=127.0.0.1:8080 cargo run`, confirm it binds there, then press Ctrl-C and confirm it logs a shutdown message before exiting. Solution ```bash 1 cargo add axum 2 cargo add tokio --features full ``` src/main.rs ```rust 1 use std::net::SocketAddr; 2 3 use axum::{routing::get, Router}; 4 use tokio::net::TcpListener; 5 use tokio::signal; 6 7 #[tokio::main] 8 async fn main() { 9 let app = Router::new().route("/", get(|| async { "Hello, world!" })); 10 11 let addr: SocketAddr = std::env::var("BIND_ADDR") 12 .unwrap_or_else(|_| "0.0.0.0:3000".to_string()) 13 .parse() 14 .expect("BIND_ADDR must be a valid socket address"); 15 16 let listener = TcpListener::bind(addr).await.unwrap(); 17 println!("listening on http://{}", listener.local_addr().unwrap()); 18 19 axum::serve(listener, app) 20 .with_graceful_shutdown(shutdown_signal()) 21 .await 22 .unwrap(); 23 } 24 25 async fn shutdown_signal() { 26 signal::ctrl_c() 27 .await 28 .expect("failed to install Ctrl-C handler"); 29 println!("shutting down gracefully"); 30 } ``` ```bash 1 BIND_ADDR=127.0.0.1:8080 cargo run 2 # listening on http://127.0.0.1:8080 3 # ... press Ctrl-C ... 4 # shutting down gracefully ``` # Routing in Axum > Route in Axum vs Express: the {id} path syntax, typed path and query params, method routing, nested routers, and fallbacks, with bad input rejected as a clean 400. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Routing maps an incoming HTTP method and URL path to the function that handles it. If you have written `app.get("/users/:id", handler)` in Express, you already understand the job. Axum does the same with a `Router`, but with compile-time-checked handlers, typed path and query extraction, and a composition model (`nest`, `merge`, `fallback`) that scales cleanly to large APIs. This page covers handlers, path parameters (which use `{id}` in Axum 0.8, **not** the Express-style `:id`), query parameters, method routing, nested routers, and fallbacks. > **Note:** This page assumes you have an Axum project running (see [Axum Setup](/16-web-apis/02-axum-setup/)) and understand the basic `Router` + `axum::serve` shape (see [Axum Basics](/16-web-apis/01-axum-basics/)). The mechanics of *how* extractors like `Path` and `Query` pull data out of a request live in [Extractors](/16-web-apis/04-extractors/); this page focuses on the routing layer that decides *which* handler runs. The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically. All Rust in this page is compile-verified against Axum 0.8.9 and Tokio 1.52. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Here is a realistic Express.js router for a small REST API: a users resource with nested posts, list/create/read/update/delete, a query-string-driven list endpoint, a method-specific 405, and a catch-all 404: ```typescript 1 // app.ts — Express 5 2 import express, { Request, Response } from "express"; 3 4 const app = express(); 5 app.use(express.json()); 6 7 // GET / — a plain string handler 8 app.get("/", (_req: Request, res: Response) => { 9 res.send("API root"); 10 }); 11 12 // A sub-router mounted under /api/users (Express's version of "nesting") 13 const users = express.Router(); 14 15 // GET /api/users?page=2&sort=name — query params arrive as strings 16 users.get("/", (req: Request, res: Response) => { 17 const page = Number(req.query.page ?? 1); 18 const perPage = Number(req.query.per_page ?? 20); 19 const sort = String(req.query.sort ?? "id"); 20 res.json({ page, perPage, sort }); 21 }); 22 23 // POST /api/users — JSON body 24 users.post("/", (req: Request, res: Response) => { 25 res.status(201).json({ id: 42, name: req.body.name }); 26 }); 27 28 // Path params use the ":name" syntax in Express 29 users.get("/:id", (req: Request, res: Response) => { 30 const id = Number(req.params.id); // NOTE: req.params.id is a string! 31 res.json({ id, name: `User ${id}` }); 32 }); 33 34 users.delete("/:id", (_req: Request, res: Response) => { 35 res.status(204).end(); 36 }); 37 38 // Multiple path params 39 users.get("/:userId/posts/:postId", (req: Request, res: Response) => { 40 res.send(`user ${req.params.userId}, post ${req.params.postId}`); 41 }); 42 43 app.use("/api/users", users); 44 45 // Catch-all 404 — must be registered LAST 46 app.use((_req: Request, res: Response) => { 47 res.status(404).send("nothing to see here"); 48 }); 49 50 app.listen(3000, () => console.log("listening on 3000")); ``` Two things a TypeScript/JavaScript developer takes for granted here will change in Rust: * **Everything is a string.** `req.params.id` and `req.query.page` are always `string` (or `undefined`). You parse and validate by hand, and a typo produces `NaN` at runtime, not a compile error. * **Order matters and is implicit.** The catch-all `app.use(...)` works only because it is registered last. Express walks the middleware/route stack top-to-bottom; the first match wins. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same API in Axum 0.8. Notice the typed extractors (`Path<u64>`, `Query<Pagination>`, `Json<CreateUser>`), the `{id}` path syntax, and the `.nest`/`.fallback` composition: ```rust 1 use axum::{ 2 extract::{Path, Query}, 3 http::StatusCode, 4 routing::get, 5 Json, Router, 6 }; 7 use serde::{Deserialize, Serialize}; 8 use std::net::SocketAddr; 9 10 #[derive(Serialize)] 11 struct User { 12 id: u64, 13 name: String, 14 } 15 16 // A plain handler: no extractors, returns a static string. 17 async fn root() -> &'static str { 18 "Hello from Axum" 19 } 20 21 // Single path param. `{id}` in the route binds to `Path<u64>` here. 22 // If the segment is not a valid u64, Axum returns 400 before this runs. 23 async fn get_user(Path(id): Path<u64>) -> Json<User> { 24 Json(User { id, name: format!("User {id}") }) 25 } 26 27 // Two path params destructured into a tuple, in route order. 28 async fn get_post(Path((user_id, post_id)): Path<(u64, u64)>) -> String { 29 format!("user {user_id}, post {post_id}") 30 } 31 32 // Query params with defaults: Option<T> + unwrap_or. 33 #[derive(Deserialize)] 34 struct Pagination { 35 page: Option<u32>, 36 per_page: Option<u32>, 37 sort: Option<String>, 38 } 39 async fn list_users(Query(p): Query<Pagination>) -> String { 40 let page = p.page.unwrap_or(1); 41 let per_page = p.per_page.unwrap_or(20); 42 let sort = p.sort.unwrap_or_else(|| "id".to_string()); 43 format!("page={page} per_page={per_page} sort={sort}") 44 } 45 46 #[derive(Deserialize)] 47 struct CreateUser { 48 name: String, 49 } 50 async fn create_user(Json(payload): Json<CreateUser>) -> (StatusCode, Json<User>) { 51 (StatusCode::CREATED, Json(User { id: 42, name: payload.name })) 52 } 53 54 async fn delete_user(Path(id): Path<u64>) -> StatusCode { 55 let _ = id; // pretend we deleted it 56 StatusCode::NO_CONTENT 57 } 58 59 // The fallback runs when no route matches. 60 async fn not_found() -> (StatusCode, &'static str) { 61 (StatusCode::NOT_FOUND, "nothing to see here") 62 } 63 64 // A sub-router for the users resource — Express's `express.Router()`. 65 fn users_router() -> Router { 66 Router::new() 67 .route("/", get(list_users).post(create_user)) 68 .route("/{id}", get(get_user).delete(delete_user)) 69 .route("/{user_id}/posts/{post_id}", get(get_post)) 70 } 71 72 fn app() -> Router { 73 Router::new() 74 .route("/", get(root)) 75 .nest("/api/users", users_router()) 76 .fallback(not_found) 77 } 78 79 #[tokio::main] 80 async fn main() { 81 let addr = SocketAddr::from(([127, 0, 0, 1], 3000)); 82 let listener = tokio::net::TcpListener::bind(addr).await.unwrap(); 83 println!("listening on {addr}"); 84 axum::serve(listener, app()).await.unwrap(); 85 } ``` Hitting this server with `curl` produces these real responses: ```text 1 $ curl -s http://127.0.0.1:3000/ 2 Hello from Axum 3 4 $ curl -s http://127.0.0.1:3000/api/users/7 5 {"id":7,"name":"User 7"} 6 7 $ curl -s "http://127.0.0.1:3000/api/users?page=2&sort=name" 8 page=2 per_page=20 sort=name 9 10 $ curl -s http://127.0.0.1:3000/api/users 11 page=1 per_page=20 sort=id 12 13 $ curl -s http://127.0.0.1:3000/api/users/3/posts/99 14 user 3, post 99 15 16 $ curl -s -i -X POST http://127.0.0.1:3000/api/users \ 17 -H 'content-type: application/json' -d '{"name":"Ada"}' 18 HTTP/1.1 201 Created 19 content-type: application/json 20 content-length: 22 21 22 {"id":42,"name":"Ada"} 23 24 $ curl -s -o /dev/null -w 'status=%{http_code}\n' -X DELETE http://127.0.0.1:3000/api/users/7 25 status=204 26 27 $ curl -s http://127.0.0.1:3000/nope 28 nothing to see here ``` The big difference from Express is that `Path<u64>` already parsed and validated the id for you: `get_user` never sees a string, and a non-numeric id is rejected automatically (more on that below). *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Handlers are just `async fn`s that return something printable [Section titled “Handlers are just async fns that return something printable”](#handlers-are-just-async-fns-that-return-something-printable) In Express a handler is `(req, res) => { ... }` and you mutate `res`. In Axum a handler is an `async fn` (or async closure) whose **return value** becomes the response. `root` returns `&'static str`; Axum knows how to turn that into a `200 OK` with `text/plain`. `get_user` returns `Json<User>` → `200 OK` with `application/json`. `create_user` returns a `(StatusCode, Json<User>)` tuple → `201 Created` with a JSON body. The trait that powers this is `IntoResponse`, covered in [Request & Response](/16-web-apis/07-request-response/). A handler’s **parameters** are extractors. Axum looks at each parameter’s type, runs the corresponding extraction against the request, and either calls your function with the values or short-circuits with an error response. That is why `get_user(Path(id): Path<u64>)` receives a ready-to-use `u64` instead of a string. ### `route(path, method_router)` and method routing [Section titled “route(path, method\_router) and method routing”](#routepath-method_router-and-method-routing) ```rust 1 Router::new().route("/{id}", get(get_user).delete(delete_user)) ``` `route` takes a path pattern and a **`MethodRouter`**, an object that maps HTTP methods to handlers for that one path. You build a `MethodRouter` by starting with a method function like `get(...)`, `post(...)`, `put(...)`, `patch(...)`, `delete(...)`, `head(...)`, or `options(...)`, then chaining more methods onto it: ```rust 1 use axum::routing::get; 2 // GET and POST on the same path, different handlers: 3 get(list_users).post(create_user) 4 // GET, PUT, and DELETE on the same path: 5 get(get_user).put(update_user).delete(delete_user) ``` This is more explicit than Express, where `users.get(...)` and `users.post(...)` are separate registrations. In Axum, one `route` call owns one path and *all* its methods. If a request hits a known path with an unsupported method, Axum returns `405 Method Not Allowed` with an `Allow` header listing what *is* supported — automatically. There is also `any(handler)` to match every method, and `MethodRouter::fallback` for a per-path method fallback. ### Path parameters: `{id}`, not `:id` [Section titled “Path parameters: {id}, not :id”](#path-parameters-id-not-id) This is the single most important migration detail for an Express developer. Axum’s router uses `matchit`, which uses **curly braces** for captures: | Pattern | Matches | Express equivalent | | ---------------------------------- | ----------------------------------- | ------------------------------ | | `/users/{id}` | `/users/7` | `/users/:id` | | `/users/{user_id}/posts/{post_id}` | `/users/3/posts/9` | `/users/:userId/posts/:postId` | | `/files/{*path}` | `/files/css/app.css` (rest of path) | `/files/*` | You extract them with `Path`: * **One param:** `Path(id): Path<u64>`. The value is parsed to your chosen type. * **Several params:** `Path((user_id, post_id)): Path<(u64, u64)>`, a tuple in route order. * **Several params, named:** deserialize into a struct whose fields match the capture names: ```rust 1 use axum::extract::Path; 2 use serde::Deserialize; 3 4 #[derive(Deserialize)] 5 struct CommentPath { 6 post_id: u64, 7 comment_id: u64, 8 } 9 10 // Route: "/posts/{post_id}/comments/{comment_id}" 11 async fn get_comment(Path(p): Path<CommentPath>) -> String { 12 format!("post {} comment {}", p.post_id, p.comment_id) 13 } ``` ```text 1 $ curl -s http://127.0.0.1:3000/posts/5/comments/8 2 post 5 comment 8 ``` A **catch-all** uses `{*name}` and captures the remaining path (including slashes). This is how static-file servers and SPA fallbacks work (see [Static Files](/16-web-apis/18-static-files/)): ```rust 1 use axum::extract::Path; 2 3 // Route: "/files/{*path}" 4 async fn serve_file(Path(rest): Path<String>) -> String { 5 format!("serving file: {rest}") 6 } ``` ```text 1 $ curl -s http://127.0.0.1:3000/files/css/app.css 2 serving file: css/app.css ``` ### Query parameters [Section titled “Query parameters”](#query-parameters) Query strings are deserialized by `serde_urlencoded` into a struct (or a map). Mark optional fields `Option<T>`, or use serde defaults: ```rust 1 use axum::extract::Query; 2 use serde::Deserialize; 3 4 #[derive(Deserialize)] 5 struct ListParams { 6 #[serde(default = "default_limit")] // used when `limit` is absent 7 limit: u32, 8 tag: Option<String>, // None when absent 9 } 10 fn default_limit() -> u32 { 11 10 12 } 13 14 async fn list(Query(p): Query<ListParams>) -> String { 15 let tag = p.tag.unwrap_or_else(|| "all".into()); 16 format!("limit={} tag={}", p.limit, tag) 17 } ``` For a free-form query string with no fixed schema (like reading `req.query` directly in Express), deserialize into a `HashMap`: ```rust 1 use axum::extract::Query; 2 use std::collections::HashMap; 3 4 async fn raw_query(Query(params): Query<HashMap<String, String>>) -> String { 5 let mut keys: Vec<_> = params.keys().cloned().collect(); 6 keys.sort(); 7 format!("{keys:?}") 8 } ``` ```text 1 $ curl -s "http://127.0.0.1:3000/raw?a=1&b=2&color=red" 2 ["a", "b", "color"] ``` ### Nesting and merging routers [Section titled “Nesting and merging routers”](#nesting-and-merging-routers) Two composition tools replace Express’s `app.use("/prefix", subRouter)`: * **`nest("/prefix", router)`** mounts a router under a path prefix. Routes inside the nested router are written relative to the prefix (`/` inside `users_router` becomes `/api/users`). * **`merge(router)`** combines two routers at the *same* level, useful for splitting a flat set of routes across modules without adding a prefix. ```rust 1 use axum::{routing::get, Router}; 2 3 async fn health() -> &'static str { "ok" } 4 async fn root() -> &'static str { "API root" } 5 6 fn build() -> Router { 7 let api = Router::new().route("/health", get(health)); 8 Router::new() 9 .nest("/api/v1", api) // mounts under a prefix 10 .merge(Router::new().route("/", get(root))) // same level, no prefix 11 } ``` ### Fallbacks: the typed catch-all [Section titled “Fallbacks: the typed catch-all”](#fallbacks-the-typed-catch-all) `fallback(handler)` registers the handler that runs when **no route matches**: the equivalent of Express’s final `app.use(...)`. Unlike Express, where forgetting to put it last silently breaks it, an Axum fallback is a distinct method call and is order-independent: it only ever runs on a miss. You can attach a fallback at the top level or inside a nested router to scope a custom 404 to one subtree. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | Express.js | Axum 0.8 | | ------------------ | ------------------------------------ | -------------------------------------------------------- | | Path param syntax | `:id` | `{id}` | | Catch-all syntax | `*` / `/*splat` | `{*name}` | | Param/query types | always `string` | parsed into your chosen type (`u64`, structs, …) | | Bad param value | your code gets `NaN`/garbage | `400 Bad Request` *before* your handler runs | | Methods per path | separate `get`/`post` calls | one `MethodRouter` per path (`get(h).post(h2)`) | | Unsupported method | you handle it (or 404) | automatic `405` + `Allow` header | | Sub-routers | `app.use("/x", router)` | `nest("/x", router)` or `merge(router)` | | 404 catch-all | last `app.use(...)`; order-sensitive | `fallback(handler)`; order-independent | | Match strategy | first registered match wins | static segments beat dynamic; conflicts panic at startup | ### Static segments win over dynamic ones [Section titled “Static segments win over dynamic ones”](#static-segments-win-over-dynamic-ones) Axum’s router is not “first match wins.” It is a radix-tree router that prefers the **more specific** route. A literal segment always beats a capture at the same position, so you can register both `/users/me` and `/users/{id}` and they coexist: ```rust 1 use axum::{extract::Path, routing::get, Router}; 2 3 async fn me() -> &'static str { "the special /users/me route" } 4 async fn by_id(Path(id): Path<u64>) -> String { format!("user {id}") } 5 6 fn build() -> Router { 7 Router::new() 8 .route("/users/me", get(me)) // static — higher priority 9 .route("/users/{id}", get(by_id)) // dynamic 10 } ``` ```text 1 $ curl -s http://127.0.0.1:3000/users/me 2 the special /users/me route 3 $ curl -s http://127.0.0.1:3000/users/5 4 user 5 ``` In Express you would have to register `/users/me` *before* `/users/:id` to get this behavior; in Axum the order of the two `.route(...)` calls does not matter. ### Routing problems are caught at startup, not at request time [Section titled “Routing problems are caught at startup, not at request time”](#routing-problems-are-caught-at-startup-not-at-request-time) Two routes that capture the same position conflict, and Axum **panics when you build the router**, not silently on some later request. That is a feature: misconfigured routing fails fast and loud at boot. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Using Express’s `:id` syntax [Section titled “Pitfall 1: Using Express’s :id syntax”](#pitfall-1-using-expresss-id-syntax) A reflexive habit from Express. In Axum 0.8 a colon-prefixed segment is rejected: the server **panics at startup** with a message that tells you exactly what to do: ```rust 1 use axum::{routing::get, Router}; 2 3 async fn h() -> &'static str { "x" } 4 5 #[tokio::main] 6 async fn main() { 7 // panics at startup — `:id` is not valid in axum 0.8 8 let app = Router::new().route("/users/:id", get(h)); 9 let listener = tokio::net::TcpListener::bind(("127.0.0.1", 3000)).await.unwrap(); 10 axum::serve(listener, app).await.unwrap(); 11 } ``` Real panic: ```text 1 thread 'main' panicked at src/main.rs:9:29: 2 Path segments must not start with `:`. For capture groups, use `{capture}`. If you meant to literally match a segment starting with a colon, call `without_v07_checks` on the router. ``` The fix is to write `/users/{id}`. (Axum 0.7 used `:id`; the 0.7→0.8 release made the switch to `{id}`, which is why this check exists.) ### Pitfall 2: A path param type mismatch is a 400, not a panic [Section titled “Pitfall 2: A path param type mismatch is a 400, not a panic”](#pitfall-2-a-path-param-type-mismatch-is-a-400-not-a-panic) If a client requests `/api/users/abc` but your handler declares `Path<u64>`, Axum cannot parse `abc` as a `u64`. It does **not** crash and does **not** call your handler — it returns `400 Bad Request`: ```text 1 $ curl -s -i http://127.0.0.1:3000/api/users/abc 2 HTTP/1.1 400 Bad Request 3 4 Invalid URL: Cannot parse `abc` to a `u64` ``` This is usually what you want, but it surprises people expecting the route simply not to match. If you want `/users/abc` to fall through to a *different* route instead, extract `Path<String>` and parse manually, or use distinct path prefixes. ### Pitfall 3: A required query field is also a 400 [Section titled “Pitfall 3: A required query field is also a 400”](#pitfall-3-a-required-query-field-is-also-a-400) Unlike Express where a missing `?q=` just gives you `undefined`, a non-`Option` query field that is absent fails deserialization: ```rust 1 use axum::extract::Query; 2 use serde::Deserialize; 3 4 #[derive(Deserialize)] 5 struct Search { 6 q: String, // required — no Option, no default 7 } 8 async fn search(Query(s): Query<Search>) -> String { 9 format!("searching: {}", s.q) 10 } ``` ```text 1 $ curl -s -i "http://127.0.0.1:3000/search" 2 HTTP/1.1 400 Bad Request 3 4 Failed to deserialize query string: missing field `q` ``` Make the field `Option<String>` (or give it a `#[serde(default)]`) if the parameter is genuinely optional. For friendlier validation messages, see [Validation](/16-web-apis/09-validation/). ### Pitfall 4: Overlapping routes panic at boot [Section titled “Pitfall 4: Overlapping routes panic at boot”](#pitfall-4-overlapping-routes-panic-at-boot) Registering two captures at the same position is a configuration error, and Axum refuses to start: ```rust 1 use axum::{routing::get, Router}; 2 3 async fn a() -> &'static str { "a" } 4 async fn b() -> &'static str { "b" } 5 6 #[tokio::main] 7 async fn main() { 8 // panics at startup — the two routes conflict 9 let app = Router::new() 10 .route("/users/{id}", get(a)) 11 .route("/users/{user_id}", get(b)); 12 let listener = tokio::net::TcpListener::bind(("127.0.0.1", 3000)).await.unwrap(); 13 axum::serve(listener, app).await.unwrap(); 14 } ``` Real panic: ```text 1 thread 'main' panicked at src/main.rs:11:10: 2 Invalid route "/users/{user_id}": Insertion failed due to conflict with previously registered route: /users/{id} ``` The fix is to collapse them into a single `route("/users/{id}", ...)` and branch inside the handler if you really need two behaviors. ### Pitfall 5: Calling `405` a `404` [Section titled “Pitfall 5: Calling 405 a 404”](#pitfall-5-calling-405-a-404) Because Express usually 404s on an unknown-method request unless you wire it up yourself, developers sometimes assume Axum does too. Axum returns a proper `405 Method Not Allowed` with an `Allow` header whenever the *path* exists but the *method* does not: ```text 1 $ curl -s -i -X POST http://127.0.0.1:3000/api/users/7 2 HTTP/1.1 405 Method Not Allowed 3 allow: GET,HEAD,DELETE ``` (Note that `GET` automatically brings `HEAD` along.) This is correct HTTP behavior; don’t “fix” it back to a 404. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Use `{id}` everywhere and grep your codebase for `":"` route literals** when migrating from Express or Axum 0.7. The startup panic will catch you, but a search is faster. * **Build one `Router`-returning function per resource** (`fn users_router() -> Router`, `fn articles_router() -> Router`) and `nest` them. This keeps modules small, makes routes unit-testable in isolation, and mirrors how you would split Express `Router`s across files. See [Modules & Packages](/12-modules-packages/) for the file-organization patterns. * **Prefer named-struct `Path`/`Query` extraction over positional tuples** once you have more than one or two params: `p.comment_id` is clearer than `tuple.1`, and the field names document the route. * **Make a field `Option<T>` or give it `#[serde(default)]` only when it is truly optional.** Letting a missing required value 400 early is a feature, not a bug. * **Version your API with `nest("/api/v1", ...)`.** Adding `/api/v2` later is then a one-line change that cannot collide with v1. * **Attach a typed JSON `fallback`** so unmatched routes return a structured error your front-end can parse, instead of an empty 404 body. * **Reach for `nest` for prefixed subtrees and `merge` for same-level composition.** Don’t hand-build prefixes by string-concatenating paths. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A versioned JSON REST API for an “articles” resource, assembled from small per-resource routers with full method routing, query-driven listing, a typed `404` fallback, and a `merge`d API root. This compiles and runs as-is (`axum = "0.8"`, `tokio = { version = "1", features = ["full"] }`, `serde = { version = "1", features = ["derive"] }`, `serde_json = "1"`): ```rust 1 use axum::{ 2 extract::{Path, Query}, 3 http::StatusCode, 4 routing::get, 5 Json, Router, 6 }; 7 use serde::{Deserialize, Serialize}; 8 9 #[derive(Serialize, Clone)] 10 struct Article { 11 id: u64, 12 title: String, 13 } 14 15 #[derive(Deserialize)] 16 struct NewArticle { 17 title: String, 18 } 19 20 #[derive(Deserialize)] 21 struct ListParams { 22 #[serde(default = "default_limit")] 23 limit: u32, 24 tag: Option<String>, 25 } 26 fn default_limit() -> u32 { 27 10 28 } 29 30 async fn list_articles(Query(p): Query<ListParams>) -> Json<Vec<Article>> { 31 let tag = p.tag.unwrap_or_else(|| "all".into()); 32 Json(vec![Article { 33 id: 1, 34 title: format!("limit={} tag={}", p.limit, tag), 35 }]) 36 } 37 38 async fn create_article(Json(body): Json<NewArticle>) -> (StatusCode, Json<Article>) { 39 (StatusCode::CREATED, Json(Article { id: 100, title: body.title })) 40 } 41 42 // Returning Result<_, StatusCode> lets a handler choose its status code. 43 async fn get_article(Path(id): Path<u64>) -> Result<Json<Article>, StatusCode> { 44 if id == 0 { 45 return Err(StatusCode::NOT_FOUND); 46 } 47 Ok(Json(Article { id, title: format!("Article {id}") })) 48 } 49 50 async fn update_article(Path(id): Path<u64>, Json(body): Json<NewArticle>) -> Json<Article> { 51 Json(Article { id, title: body.title }) 52 } 53 54 async fn delete_article(Path(_id): Path<u64>) -> StatusCode { 55 StatusCode::NO_CONTENT 56 } 57 58 async fn health() -> &'static str { 59 "ok" 60 } 61 62 // A typed JSON 404 instead of an empty body. 63 async fn api_fallback() -> (StatusCode, Json<serde_json::Value>) { 64 ( 65 StatusCode::NOT_FOUND, 66 Json(serde_json::json!({ "error": "route not found" })), 67 ) 68 } 69 70 // One router per resource keeps modules small and testable. 71 fn articles_routes() -> Router { 72 Router::new() 73 .route("/", get(list_articles).post(create_article)) 74 .route( 75 "/{id}", 76 get(get_article).put(update_article).delete(delete_article), 77 ) 78 } 79 80 fn api_v1() -> Router { 81 Router::new() 82 .route("/health", get(health)) 83 .nest("/articles", articles_routes()) 84 } 85 86 fn app() -> Router { 87 Router::new() 88 .nest("/api/v1", api_v1()) 89 .merge(Router::new().route("/", get(|| async { "API root" }))) 90 .fallback(api_fallback) 91 } 92 93 #[tokio::main] 94 async fn main() { 95 let listener = tokio::net::TcpListener::bind(("127.0.0.1", 3000)).await.unwrap(); 96 println!("listening on http://127.0.0.1:3000"); 97 axum::serve(listener, app()).await.unwrap(); 98 } ``` Exercising every endpoint produces these real responses: ```text 1 $ curl -s http://127.0.0.1:3000/ 2 API root 3 4 $ curl -s http://127.0.0.1:3000/api/v1/health 5 ok 6 7 $ curl -s "http://127.0.0.1:3000/api/v1/articles?tag=rust" 8 [{"id":1,"title":"limit=10 tag=rust"}] 9 10 $ curl -s -X POST http://127.0.0.1:3000/api/v1/articles \ 11 -H 'content-type: application/json' -d '{"title":"Hello"}' 12 {"id":100,"title":"Hello"} 13 14 $ curl -s http://127.0.0.1:3000/api/v1/articles/5 15 {"id":5,"title":"Article 5"} 16 17 $ curl -s -o /dev/null -w 'status=%{http_code}\n' http://127.0.0.1:3000/api/v1/articles/0 18 status=404 19 20 $ curl -s -X PUT http://127.0.0.1:3000/api/v1/articles/5 \ 21 -H 'content-type: application/json' -d '{"title":"Edited"}' 22 {"id":5,"title":"Edited"} 23 24 $ curl -s -o /dev/null -w 'status=%{http_code}\n' -X DELETE http://127.0.0.1:3000/api/v1/articles/5 25 status=204 26 27 $ curl -s http://127.0.0.1:3000/api/v1/unknown 28 {"error":"route not found"} ``` This pattern, a tree of small, per-resource `Router` functions stitched together with `nest`, `merge`, and a typed `fallback`, scales from this toy example to a production API with dozens of resources. The next step is to share a database pool and config across these handlers, which is where [State Management](/16-web-apis/06-state-management/) comes in. > **Tip:** This example deliberately returns errors as bare `StatusCode` and an ad-hoc JSON object. In a real application you would define one error type that implements `IntoResponse` so every handler can use `?` and produce consistent error bodies — see [Error Handling in Web APIs](/16-web-apis/10-error-handling-web/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [Axum routing module docs](https://docs.rs/axum/latest/axum/routing/index.html) — `Router`, `MethodRouter`, `nest`, `merge`, `fallback`. * [`axum::extract::Path`](https://docs.rs/axum/latest/axum/extract/struct.Path.html) and [`axum::extract::Query`](https://docs.rs/axum/latest/axum/extract/struct.Query.html) — the official extractor reference. * [`matchit` crate](https://docs.rs/matchit/latest/matchit/) — the radix-tree router Axum uses, including the `{name}` / `{*name}` syntax rules. * [Axum 0.8 changelog / migration notes](https://github.com/tokio-rs/axum/blob/main/axum/CHANGELOG.md) — the `:id` → `{id}` change and other 0.7→0.8 differences. Within this guide: * [Axum Setup](/16-web-apis/02-axum-setup/) and [Axum Basics](/16-web-apis/01-axum-basics/) — getting a server running before you route. * [Extractors](/16-web-apis/04-extractors/) — how `Path`, `Query`, and `Json` actually pull data out of a request, and extractor ordering. * [Request & Response](/16-web-apis/07-request-response/) — what handlers can return and how `IntoResponse` builds the response. * [State Management](/16-web-apis/06-state-management/) — sharing a DB pool and config across the handlers you route to. * [Middleware & Layers](/16-web-apis/05-middleware/) — attaching logging, CORS, and other cross-cutting behavior to routers. * [JSON APIs](/16-web-apis/08-json-apis/) and [Validation](/16-web-apis/09-validation/) — fleshing out a CRUD resource and validating its input. * [Static Files](/16-web-apis/18-static-files/) — the catch-all (`{*path}`) and SPA-fallback patterns in depth. * [Error Handling in Web APIs](/16-web-apis/10-error-handling-web/): a single `AppError` type for consistent error responses. * Foundations: [Why Rust](/00-introduction/), [Basics](/02-basics/), [Error Handling](/08-error-handling/), [Async](/11-async/), and the upcoming [Database](/17-database/) section for wiring real persistence behind these routes. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Add a nested comments resource [Section titled “Exercise 1: Add a nested comments resource”](#exercise-1-add-a-nested-comments-resource) **Difficulty:** Easy **Objective:** Practice path parameters and nested routers. **Instructions:** Starting from the real-world articles API, add a comments resource so that `GET /api/v1/articles/{article_id}/comments/{comment_id}` returns a JSON object containing both ids. Use a named struct for the `Path` extraction (not a tuple). Verify that requesting `/api/v1/articles/3/comments/8` returns `{"article_id":3,"comment_id":8}`. Solution ```rust 1 use axum::{extract::Path, routing::get, Json, Router}; 2 use serde::{Deserialize, Serialize}; 3 4 #[derive(Deserialize)] 5 struct CommentPath { 6 article_id: u64, 7 comment_id: u64, 8 } 9 10 #[derive(Serialize)] 11 struct CommentRef { 12 article_id: u64, 13 comment_id: u64, 14 } 15 16 async fn get_comment(Path(p): Path<CommentPath>) -> Json<CommentRef> { 17 Json(CommentRef { 18 article_id: p.article_id, 19 comment_id: p.comment_id, 20 }) 21 } 22 23 // Nest this under "/api/v1" alongside the articles routes: 24 // .nest("/api/v1", Router::new() 25 // .route("/articles/{article_id}/comments/{comment_id}", get(get_comment))) 26 fn app() -> Router { 27 Router::new().nest( 28 "/api/v1", 29 Router::new().route( 30 "/articles/{article_id}/comments/{comment_id}", 31 get(get_comment), 32 ), 33 ) 34 } 35 36 #[tokio::main] 37 async fn main() { 38 let listener = tokio::net::TcpListener::bind(("127.0.0.1", 3000)).await.unwrap(); 39 axum::serve(listener, app()).await.unwrap(); 40 } ``` Real response: ```text 1 $ curl -s http://127.0.0.1:3000/api/v1/articles/3/comments/8 2 {"article_id":3,"comment_id":8} ``` ### Exercise 2: A search endpoint with required and optional query params [Section titled “Exercise 2: A search endpoint with required and optional query params”](#exercise-2-a-search-endpoint-with-required-and-optional-query-params) **Difficulty:** Medium **Objective:** Distinguish required from optional query parameters and observe the 400 behavior. **Instructions:** Write a `GET /search` handler whose query struct has a **required** `q: String`, an **optional** `limit` that defaults to `5`, and an **optional** `category: Option<String>`. Return a string summarizing all three. Then confirm with `curl` that (a) `/search?q=rust` works and uses the defaults, and (b) `/search` (no `q`) returns `400 Bad Request`. Solution ```rust 1 use axum::{extract::Query, routing::get, Router}; 2 use serde::Deserialize; 3 4 #[derive(Deserialize)] 5 struct SearchParams { 6 q: String, // required: absence -> 400 7 #[serde(default = "default_limit")] 8 limit: u32, 9 category: Option<String>, 10 } 11 fn default_limit() -> u32 { 12 5 13 } 14 15 async fn search(Query(p): Query<SearchParams>) -> String { 16 let category = p.category.unwrap_or_else(|| "any".into()); 17 format!("q={} limit={} category={}", p.q, p.limit, category) 18 } 19 20 fn app() -> Router { 21 Router::new().route("/search", get(search)) 22 } 23 24 #[tokio::main] 25 async fn main() { 26 let listener = tokio::net::TcpListener::bind(("127.0.0.1", 3000)).await.unwrap(); 27 axum::serve(listener, app()).await.unwrap(); 28 } ``` Real responses: ```text 1 $ curl -s "http://127.0.0.1:3000/search?q=rust" 2 q=rust limit=5 category=any 3 4 $ curl -s "http://127.0.0.1:3000/search?q=axum&limit=20&category=web" 5 q=axum limit=20 category=web 6 7 $ curl -s -i "http://127.0.0.1:3000/search" 8 HTTP/1.1 400 Bad Request 9 10 Failed to deserialize query string: missing field `q` ``` ### Exercise 3: A static-vs-dynamic precedence route with a scoped fallback [Section titled “Exercise 3: A static-vs-dynamic precedence route with a scoped fallback”](#exercise-3-a-static-vs-dynamic-precedence-route-with-a-scoped-fallback) **Difficulty:** Hard **Objective:** Combine static-segment precedence, a catch-all, and a nested fallback. **Instructions:** Build a router where: 1. `GET /pages/home` returns the literal string `"home page"`. 2. `GET /pages/{slug}` returns `"dynamic page: <slug>"` for any other single segment. 3. `GET /assets/{*path}` returns `"asset: <path>"` for any path under `/assets`, including ones with slashes. 4. Any other URL under the app returns a `404` with the JSON body `{"error":"not found"}`. Verify that `/pages/home` hits the static route (not the dynamic one), `/pages/about` hits the dynamic route, `/assets/img/logo.png` captures the full sub-path, and `/totally/unknown` hits the fallback. Solution ```rust 1 use axum::{extract::Path, http::StatusCode, routing::get, Json, Router}; 2 3 async fn home() -> &'static str { 4 "home page" 5 } 6 7 async fn dynamic_page(Path(slug): Path<String>) -> String { 8 format!("dynamic page: {slug}") 9 } 10 11 async fn asset(Path(path): Path<String>) -> String { 12 format!("asset: {path}") 13 } 14 15 async fn not_found() -> (StatusCode, Json<serde_json::Value>) { 16 ( 17 StatusCode::NOT_FOUND, 18 Json(serde_json::json!({ "error": "not found" })), 19 ) 20 } 21 22 fn app() -> Router { 23 Router::new() 24 .route("/pages/home", get(home)) // static beats dynamic, regardless of order 25 .route("/pages/{slug}", get(dynamic_page)) 26 .route("/assets/{*path}", get(asset)) // catch-all captures slashes 27 .fallback(not_found) 28 } 29 30 #[tokio::main] 31 async fn main() { 32 let listener = tokio::net::TcpListener::bind(("127.0.0.1", 3000)).await.unwrap(); 33 println!("listening on http://127.0.0.1:3000"); 34 axum::serve(listener, app()).await.unwrap(); 35 } ``` Real responses: ```text 1 $ curl -s http://127.0.0.1:3000/pages/home 2 home page 3 4 $ curl -s http://127.0.0.1:3000/pages/about 5 dynamic page: about 6 7 $ curl -s http://127.0.0.1:3000/assets/img/logo.png 8 asset: img/logo.png 9 10 $ curl -s -i http://127.0.0.1:3000/totally/unknown 11 HTTP/1.1 404 Not Found 12 content-type: application/json 13 14 {"error":"not found"} ``` The key insight: the order of the `/pages/home` and `/pages/{slug}` registrations does not matter — Axum’s router always prefers the more specific static segment. # Extractors > Express reads everything off one req object; Axum extractors like Path, Query, and Json become typed, validated handler parameters, with custom guards in Rust too. In Express.js you reach into a single `req` object for everything: `req.params`, `req.query`, `req.body`, `req.headers`. Axum flips this around: each piece of the request becomes a typed function parameter called an **extractor**, and the framework parses and validates it for you before your handler ever runs. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) An **extractor** is a type that knows how to build itself from an incoming HTTP request. Instead of pulling values out of one big `req` object and hoping they exist, you declare exactly what you need in your handler’s signature — `Path<u64>`, `Query<Pagination>`, `Json<CreateUser>` — and Axum populates them or returns a `400`/`422` automatically. This pushes request parsing and validation into the type system, so a handler that compiles has already been handed correctly-typed data. The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically. This page targets **axum 0.8**. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In Express, the request is a single object and you destructure whatever you need from it. Nothing is typed or validated at the framework level; that is your job. ```typescript 1 // Express.js — everything hangs off `req` 2 import express, { Request, Response } from "express"; 3 4 const app = express(); 5 app.use(express.json()); 6 7 interface Pagination { 8 page: number; 9 perPage: number; 10 } 11 12 interface CreateUser { 13 name: string; 14 email: string; 15 } 16 17 // Path param + query string 18 app.get("/users/:id", (req: Request, res: Response) => { 19 const id = Number(req.params.id); // string -> number by hand 20 if (Number.isNaN(id)) { 21 return res.status(400).json({ error: "id must be a number" }); 22 } 23 24 const page = Number(req.query.page ?? "1"); 25 const perPage = Number(req.query.perPage ?? "20"); 26 const pagination: Pagination = { page, perPage }; 27 28 res.json({ id, ...pagination }); 29 }); 30 31 // JSON body + a header 32 app.post("/users", (req: Request, res: Response) => { 33 const body = req.body as CreateUser; // a lie: nothing was actually checked 34 if (typeof body.name !== "string" || typeof body.email !== "string") { 35 return res.status(400).json({ error: "name and email are required" }); 36 } 37 38 const userAgent = req.get("user-agent") ?? "unknown"; 39 res.status(201).json({ id: 1, ...body, userAgent }); 40 }); 41 42 app.listen(3000); ``` **Key points:** * One `req` object; you destructure `params`, `query`, `body`, headers manually. * `req.params.id` is always a `string` — you convert and validate yourself. * `req.body as CreateUser` is a TypeScript *cast*, not a runtime check. The cast compiles even if the body is `{}` or `null`. * Forgetting `app.use(express.json())` silently leaves `req.body` as `undefined`. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) In Axum each part of the request is a separate, typed parameter. Axum parses it, and if parsing fails the client gets a sensible error before your code runs. ```rust 1 use axum::{ 2 extract::{Json, Path, Query}, 3 http::{header::USER_AGENT, HeaderMap, StatusCode}, 4 routing::get, 5 Router, 6 }; 7 use serde::{Deserialize, Serialize}; 8 9 #[derive(Deserialize)] 10 struct Pagination { 11 page: Option<u32>, 12 per_page: Option<u32>, 13 } 14 15 #[derive(Deserialize, Serialize)] 16 struct CreateUser { 17 name: String, 18 email: String, 19 } 20 21 #[derive(Serialize)] 22 struct UserResponse { 23 id: u64, 24 name: String, 25 email: String, 26 user_agent: String, 27 } 28 29 // Path param + query string. `id` is already a `u64`. 30 async fn get_user(Path(id): Path<u64>, Query(pg): Query<Pagination>) -> String { 31 let page = pg.page.unwrap_or(1); 32 let per_page = pg.per_page.unwrap_or(20); 33 format!("user {id}, page {page}, per_page {per_page}") 34 } 35 36 // JSON body + a header. `body` is guaranteed to have `name` and `email`. 37 async fn create_user( 38 headers: HeaderMap, 39 Json(body): Json<CreateUser>, 40 ) -> (StatusCode, Json<UserResponse>) { 41 let user_agent = headers 42 .get(USER_AGENT) 43 .and_then(|v| v.to_str().ok()) 44 .unwrap_or("unknown") 45 .to_string(); 46 47 let response = UserResponse { 48 id: 1, 49 name: body.name, 50 email: body.email, 51 user_agent, 52 }; 53 (StatusCode::CREATED, Json(response)) 54 } 55 56 #[tokio::main] 57 async fn main() { 58 let app = Router::new() 59 .route("/users/{id}", get(get_user)) 60 .route("/users", get(get_user).post(create_user)); 61 62 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000") 63 .await 64 .unwrap(); 65 axum::serve(listener, app).await.unwrap(); 66 } ``` Cargo.toml ```toml 1 [dependencies] 2 axum = "0.8" 3 serde = { version = "1", features = ["derive"] } 4 serde_json = "1" 5 tokio = { version = "1", features = ["full"] } ``` **Key points:** * `Path<u64>` gives you a real `u64`: the conversion *and* the “is it a number?” check happen for free. * `Query<Pagination>` deserializes the query string into a struct via `serde`. * `Json<CreateUser>` deserializes *and validates the shape* of the body. If `email` is missing, the request never reaches your code. * `HeaderMap` is itself an extractor; no `Header<...>` wrapper needed. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What “extractor” actually means [Section titled “What “extractor” actually means”](#what-extractor-actually-means) An extractor is any type that implements one of two traits: * **`FromRequestParts<S>`** — builds itself from the request *metadata* (method, URI, headers, extensions) without touching the body. `Path`, `Query`, `HeaderMap`, and `State` are all of this kind. You can have many of these in one handler. * **`FromRequest<S>`** — builds itself by consuming the *entire request*, body included. `Json`, `Bytes`, `String`, and `Form` are of this kind. Because the body can only be read once, **at most one** body extractor is allowed, and it must come last. The `S` is your application’s shared state type (covered in [Shared Application State in Axum](/16-web-apis/06-state-management/)). For handlers without state it is inferred. When a request arrives, Axum runs each extractor in declaration order. Each one returns a `Result`; on `Err` it short-circuits and turns the rejection into an HTTP response, and your handler is never called. ### `Path` — one value, a tuple, or a struct [Section titled “Path — one value, a tuple, or a struct”](#path--one-value-a-tuple-or-a-struct) `Path` is generic over how you want the captured segments shaped: ```rust 1 use axum::extract::Path; 2 use serde::Deserialize; 3 4 // Single segment -> single value. 5 async fn one(Path(id): Path<u64>) -> String { 6 format!("user {id}") 7 } 8 9 // Multiple segments -> a tuple, in route order. 10 async fn two(Path((user_id, post_id)): Path<(u64, u64)>) -> String { 11 format!("user {user_id} post {post_id}") 12 } 13 14 // Multiple segments -> a struct, matched by NAME. 15 #[derive(Deserialize)] 16 struct PostPath { 17 user_id: u64, 18 post_id: u64, 19 } 20 21 async fn named(Path(p): Path<PostPath>) -> String { 22 format!("user {} post {}", p.user_id, p.post_id) 23 } ``` The routes would be `/users/{id}`, `/users/{user_id}/posts/{post_id}`, and so on. Note the `{name}` syntax: axum 0.8 replaced the old `:name` form. For the full routing story see [Routing in Axum](/16-web-apis/03-routing/). > **Note:** With a tuple, segments are matched by *position*. With a struct, they are matched by *field name* against the `{name}` captures in the route. The struct form is safer because reordering route segments will not silently swap your values. ### `Query` — the query string as a struct [Section titled “Query — the query string as a struct”](#query--the-query-string-as-a-struct) `Query<T>` percent-decodes the query string and deserializes it into `T`. Use `Option<...>` for parameters that may be absent: ```rust 1 use axum::extract::Query; 2 use serde::Deserialize; 3 use std::collections::HashMap; 4 5 #[derive(Deserialize)] 6 struct Filters { 7 status: Option<String>, 8 limit: Option<u32>, 9 } 10 11 async fn search(Query(f): Query<Filters>) -> String { 12 format!("status={:?} limit={:?}", f.status, f.limit) 13 } 14 15 // When you do not know the keys ahead of time: 16 async fn raw(Query(params): Query<HashMap<String, String>>) -> String { 17 format!("{params:?}") 18 } ``` > **Tip:** Plain `Query` does *not* handle repeated keys like `?tag=a&tag=b` into a `Vec`. For that, add `axum-extra` and use `axum_extra::extract::Query`, which supports `Vec<String>` fields. ### `Json` — the body, deserialized and checked [Section titled “Json — the body, deserialized and checked”](#json--the-body-deserialized-and-checked) `Json<T>` reads the whole body, requires a `Content-Type: application/json` header, and runs `serde` deserialization. A successful extraction means `T`’s required fields were all present and well-typed. `Json` is also a *response* type: returning `Json(value)` serializes `value` and sets the content type. Response usage is covered in [Request and Response Handling](/16-web-apis/07-request-response/) and [JSON REST APIs](/16-web-apis/08-json-apis/); here we focus on its extractor role. ### Headers and `State` [Section titled “Headers and State”](#headers-and-state) `HeaderMap` gives you the full header set. `State<T>` hands you a clone of shared application state (a database pool, config, an in-memory store). Both implement `FromRequestParts`, so they coexist freely with `Path` and `Query`: ```rust 1 use axum::extract::State; 2 use axum::http::{header::USER_AGENT, HeaderMap}; 3 4 #[derive(Clone)] 5 struct AppState { 6 app_name: String, 7 } 8 9 async fn whoami(State(state): State<AppState>, headers: HeaderMap) -> String { 10 let ua = headers 11 .get(USER_AGENT) 12 .and_then(|v| v.to_str().ok()) 13 .unwrap_or("unknown"); 14 format!("{}: {ua}", state.app_name) 15 } ``` `State` deserves its own treatment; see [Shared Application State in Axum](/16-web-apis/06-state-management/). ### What rejections look like over the wire [Section titled “What rejections look like over the wire”](#what-rejections-look-like-over-the-wire) These are the **real** responses from the server above. Notice the status codes are chosen for you: ```text 1 GET /users/42 -> 200 user 42, page 1, per_page 20 2 GET /users/abc -> 400 Invalid URL: Cannot parse `abc` to a `u64` 3 GET /users/42?page=3&per_page=50 -> 200 user 42, page 3, per_page 50 4 GET /users/42?page=abc -> 400 Failed to deserialize query string: page: invalid digit found in string 5 POST /users {"name":"Ada","email":"ada@x.io"} -> 201 {"id":1,"name":"Ada","email":"ada@x.io"} 6 POST /users {"name":"Ada"} -> 422 Failed to deserialize the JSON body into the target type: missing field `email` at line 1 column 14 7 POST /users (no Content-Type) -> 415 Expected request with `Content-Type: application/json` ``` A bad path segment is a `400`, a malformed query is a `400`, a JSON body of the wrong *shape* is a `422 Unprocessable Entity`, and a missing content type is a `415 Unsupported Media Type`, all before your handler runs. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concern | Express.js | Axum | | ---------------------------- | ------------------------------------ | ------------------------------------------------ | | Where data comes from | one `req` object | one typed parameter per piece | | Param types | always `string`; convert by hand | parsed to the type you declare (`u64`, structs) | | Body validation | manual, or a separate library | `Json<T>` checks shape via `serde` automatically | | Missing/invalid input | you write the `400` | framework returns `400`/`422`/`415` | | Body read | `req.body` after `express.json()` | one `FromRequest` extractor, always last | | ”I forgot to parse the body” | `req.body` is `undefined` at runtime | the code does not compile / a 415 is returned | The deeper idea: in Express, request parsing is *imperative work inside the handler*. In Axum it is *declarative metadata in the signature*. The handler body starts from valid, typed data, the same way a function with typed parameters starts from valid arguments. ### `FromRequestParts` vs `FromRequest` [Section titled “FromRequestParts vs FromRequest”](#fromrequestparts-vs-fromrequest) This distinction is the single most important thing to internalize: * `FromRequestParts` extractors read only metadata and are cheap and composable; use as many as you like. * `FromRequest` extractors consume the body — exactly one, and it must be the **last** parameter. You can write your own extractor by implementing `FromRequestParts`. In axum 0.8 the trait uses native `async fn`, so no `#[async_trait]` is needed: ```rust 1 use axum::extract::FromRequestParts; 2 use axum::http::{header::AUTHORIZATION, request::Parts, StatusCode}; 3 4 // Pull a bearer token out of the Authorization header. 5 struct ApiKey(String); 6 7 impl<S> FromRequestParts<S> for ApiKey 8 where 9 S: Send + Sync, 10 { 11 type Rejection = (StatusCode, &'static str); 12 13 async fn from_request_parts( 14 parts: &mut Parts, 15 _state: &S, 16 ) -> Result<Self, Self::Rejection> { 17 let header = parts 18 .headers 19 .get(AUTHORIZATION) 20 .and_then(|v| v.to_str().ok()) 21 .ok_or((StatusCode::UNAUTHORIZED, "missing Authorization header"))?; 22 23 let token = header 24 .strip_prefix("Bearer ") 25 .ok_or((StatusCode::UNAUTHORIZED, "expected a Bearer token"))?; 26 27 Ok(ApiKey(token.to_string())) 28 } 29 } 30 31 // Now `ApiKey` is usable like any built-in extractor: 32 async fn protected(ApiKey(token): ApiKey) -> String { 33 format!("token starts with {}", &token[..token.len().min(4)]) 34 } ``` This “extractor as a guard” pattern is the foundation of [Authentication Patterns](/16-web-apis/12-authentication/) and [JWT Authentication](/16-web-apis/13-jwt/). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Putting a body extractor before another extractor [Section titled “Putting a body extractor before another extractor”](#putting-a-body-extractor-before-another-extractor) A body extractor (`Json`, `Bytes`, `String`, `Form`) must be the **last** parameter. If it is not, the handler fails to satisfy the `Handler` trait and you get a wall of trait-bound errors: ```rust 1 use axum::{extract::{Json, Path}, routing::post, Router}; 2 use serde::Deserialize; 3 4 #[derive(Deserialize)] 5 struct Body { name: String } 6 7 // does not compile (error[E0277]): Json is not the last parameter 8 async fn handler(Json(body): Json<Body>, Path(id): Path<u64>) -> String { 9 format!("{} {id}", body.name) 10 } 11 12 fn build() -> Router { 13 Router::new().route("/items/{id}", post(handler)) 14 } ``` The raw error is the cryptic `the trait bound ... Handler<_, _> is not implemented`. The fix-it nudge in that output is gold: add `#[axum::debug_handler]` to the handler (it needs the `macros` feature on axum). With it, the real message becomes precise: ```text 1 error: `Json<_>` consumes the request body and thus must be the last argument to the handler function 2 --> src/main.rs:8:30 3 | 4 8 | async fn handler(Json(body): Json<Body>, Path(id): Path<u64>) -> String { 5 | ^^^^ ``` The fix is simply to reorder: `async fn handler(Path(id): Path<u64>, Json(body): Json<Body>)`. > **Tip:** Whenever a handler “won’t implement `Handler`” and the error is unreadable, slap `#[axum::debug_handler]` on it. It exists purely to translate those trait errors into plain English. ### Using the old `:id` route syntax [Section titled “Using the old :id route syntax”](#using-the-old-id-route-syntax) axum 0.7 used `:id`; axum 0.8 uses `{id}`. The old form is not a compile error; it **panics at startup**, at the line where you call `.route("/users/:id", ...)`: ```text 1 thread 'main' panicked at src/main.rs:9:37: 2 Path segments must not start with `:`. For capture groups, use `{capture}`. 3 If you meant to literally match a segment starting with a colon, call 4 `without_v07_checks` on the router. ``` ### Trusting `req.body as T` habits — `Json<T>` needs `Deserialize` [Section titled “Trusting req.body as T habits — Json\<T> needs Deserialize”](#trusting-reqbody-as-t-habits--jsont-needs-deserialize) A subtle one: `Json<T>` as an *extractor* requires `T: Deserialize`. If your struct only derives `Serialize` (because you have only ever returned it), using it in a `Json<T>` parameter fails the `Handler` bound. Derive both `Serialize` and `Deserialize` for types that travel in *and* out: ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Serialize, Deserialize)] // both, for a round-trip type 4 struct User { 5 id: u64, 6 name: String, 7 } ``` ### Forgetting that `Query`/`Json` distinguish “missing” from “wrong type” [Section titled “Forgetting that Query/Json distinguish “missing” from “wrong type””](#forgetting-that-queryjson-distinguish-missing-from-wrong-type) A missing optional field is fine if you use `Option<T>`. But a *present but wrong-typed* value is a hard error: `?page=abc` against a `page: Option<u32>` is a `400`, not a `None`. If you want “ignore garbage and default”, parse it as a `String` and convert yourself. ### Reaching for `async-trait` to write a custom extractor [Section titled “Reaching for async-trait to write a custom extractor”](#reaching-for-async-trait-to-write-a-custom-extractor) You do not need it. Native `async fn` in traits has been stable since Rust 1.75, and axum 0.8’s `FromRequestParts`/`FromRequest` use it directly. The `async-trait` crate is only relevant when you need `dyn Trait` dynamic dispatch, which extractors do not. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Declare exactly what you need.** Prefer `Path<u64>` over `Path<String>` so the framework rejects non-numeric ids for you. * **Use structs for `Query` and multi-segment `Path`.** Named fields are self-documenting and survive reordering. Reserve tuples for one or two obvious segments. * **Make optional query params `Option<T>`** and apply defaults in the handler with `unwrap_or`. * **Keep the body extractor last**, always. Treat it as a rule, not a per-handler decision. * **Derive both `Serialize` and `Deserialize`** on DTOs that are accepted *and* returned. * **Write a custom `FromRequestParts` extractor** for cross-cutting concerns (auth, tenant resolution, request ids). A guard that lives in the signature cannot be forgotten the way a manual check inside the body can. * **Override rejections when you want a uniform error body.** Extract `Result<Json<T>, JsonRejection>` to shape the `4xx` yourself, or centralize it as shown in [Error Handling in Web Handlers](/16-web-apis/10-error-handling-web/). * **Reach for `#[axum::debug_handler]` during development** when extractor errors are noisy. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small, authenticated user API that combines shared `State`, a custom `AuthUser` guard extractor, `Path`, `Query`, and a hand-shaped JSON rejection. Every line below is compile-verified against axum 0.8. ```rust 1 use axum::{ 2 extract::{rejection::JsonRejection, FromRequestParts, Json, Path, Query, State}, 3 http::{header::AUTHORIZATION, request::Parts, StatusCode}, 4 response::{IntoResponse, Response}, 5 routing::get, 6 Router, 7 }; 8 use serde::{Deserialize, Serialize}; 9 use std::collections::HashMap; 10 use std::sync::{Arc, Mutex}; 11 12 #[derive(Clone)] 13 struct AppState { 14 users: Arc<Mutex<HashMap<u64, User>>>, 15 api_token: String, 16 } 17 18 #[derive(Clone, Serialize, Deserialize)] 19 struct User { 20 id: u64, 21 name: String, 22 } 23 24 #[derive(Deserialize)] 25 struct ListParams { 26 name_contains: Option<String>, 27 } 28 29 // Guard extractor: validates the bearer token against application state. 30 struct AuthUser; 31 32 impl FromRequestParts<AppState> for AuthUser { 33 type Rejection = (StatusCode, String); 34 35 async fn from_request_parts( 36 parts: &mut Parts, 37 state: &AppState, 38 ) -> Result<Self, Self::Rejection> { 39 let token = parts 40 .headers 41 .get(AUTHORIZATION) 42 .and_then(|v| v.to_str().ok()) 43 .and_then(|s| s.strip_prefix("Bearer ")) 44 .ok_or((StatusCode::UNAUTHORIZED, "missing bearer token".to_string()))?; 45 46 if token != state.api_token { 47 return Err((StatusCode::UNAUTHORIZED, "invalid token".to_string())); 48 } 49 Ok(AuthUser) 50 } 51 } 52 53 // The guard runs first; if it rejects, the rest never runs. 54 async fn list_users( 55 _auth: AuthUser, 56 State(state): State<AppState>, 57 Query(params): Query<ListParams>, 58 ) -> Json<Vec<User>> { 59 let users = state.users.lock().unwrap(); 60 let needle = params.name_contains.unwrap_or_default().to_lowercase(); 61 let out: Vec<User> = users 62 .values() 63 .filter(|u| needle.is_empty() || u.name.to_lowercase().contains(&needle)) 64 .cloned() 65 .collect(); 66 Json(out) 67 } 68 69 async fn get_user( 70 _auth: AuthUser, 71 State(state): State<AppState>, 72 Path(id): Path<u64>, 73 ) -> Result<Json<User>, StatusCode> { 74 state 75 .users 76 .lock() 77 .unwrap() 78 .get(&id) 79 .cloned() 80 .map(Json) 81 .ok_or(StatusCode::NOT_FOUND) 82 } 83 84 #[derive(Serialize)] 85 struct ApiError { 86 error: String, 87 } 88 89 // Take the Result form of the body extractor to shape our own 422 body. 90 async fn create_user(payload: Result<Json<User>, JsonRejection>) -> Response { 91 match payload { 92 Ok(Json(user)) => (StatusCode::CREATED, Json(user)).into_response(), 93 Err(rejection) => ( 94 StatusCode::UNPROCESSABLE_ENTITY, 95 Json(ApiError { error: rejection.body_text() }), 96 ) 97 .into_response(), 98 } 99 } 100 101 #[tokio::main] 102 async fn main() { 103 let mut seed = HashMap::new(); 104 seed.insert(1, User { id: 1, name: "Ada".into() }); 105 106 let state = AppState { 107 users: Arc::new(Mutex::new(seed)), 108 api_token: "secret".into(), 109 }; 110 111 let app = Router::new() 112 .route("/users", get(list_users).post(create_user)) 113 .route("/users/{id}", get(get_user)) 114 .with_state(state); 115 116 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000") 117 .await 118 .unwrap(); 119 axum::serve(listener, app).await.unwrap(); 120 } ``` Exercising it with `curl` produces these **real** responses: ```text 1 GET /users -> 401 missing bearer token 2 GET /users -H 'Authorization: Bearer nope' -> 401 invalid token 3 GET /users -H 'Authorization: Bearer secret' -> 200 [{"id":1,"name":"Ada"}] 4 GET /users/1 -H 'Authorization: Bearer secret' -> 200 {"id":1,"name":"Ada"} 5 GET /users/99 -H 'Authorization: Bearer secret' -> 404 6 POST /users {"id":"oops"} -> 422 {"error":"Failed to deserialize the JSON body into the target type: id: invalid type: string \"oops\", expected u64 at line 1 column 12"} ``` The guard, the state, and the parsing all happen declaratively; the handler bodies only ever see valid, authenticated, typed data. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [axum `extract` module docs](https://docs.rs/axum/latest/axum/extract/index.html) — the canonical list of built-in extractors and the order rules. * [`FromRequestParts`](https://docs.rs/axum/latest/axum/extract/trait.FromRequestParts.html) and [`FromRequest`](https://docs.rs/axum/latest/axum/extract/trait.FromRequest.html) trait reference. * [`axum::debug_handler`](https://docs.rs/axum/latest/axum/attr.debug_handler.html) — turning opaque `Handler` errors into readable messages. * [serde derive docs](https://serde.rs/derive.html) — how `Deserialize` shapes `Query`/`Json` parsing. Within this guide: * [Routing in Axum](/16-web-apis/03-routing/): `{id}` path syntax, method routing, nested routers (where path captures come from). * [Shared Application State in Axum](/16-web-apis/06-state-management/): the `State<T>` extractor, `Arc`, `FromRef`. * [Request and Response Handling](/16-web-apis/07-request-response/): `Json` and tuples as *responses*, `IntoResponse`, status codes. * [JSON REST APIs](/16-web-apis/08-json-apis/): a full CRUD resource built on these extractors. * [Request Validation](/16-web-apis/09-validation/): going beyond shape checks to business-rule validation. * [Error Handling in Web Handlers](/16-web-apis/10-error-handling-web/): a centralized `AppError` and uniform rejection bodies. * [Authentication Patterns](/16-web-apis/12-authentication/) and [JWT Authentication](/16-web-apis/13-jwt/): the guard-extractor pattern in production form. * Foundations: [async/await](/11-async/), [generics and traits](/09-generics-traits/), [error handling](/08-error-handling/), and the language [basics](/02-basics/) / [getting started](/01-getting-started/). * Persisting the data these handlers receive: [Database](/17-database/). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Typed path and optional query [Section titled “Exercise 1: Typed path and optional query”](#exercise-1-typed-path-and-optional-query) **Difficulty:** Easy **Objective:** Build a handler that extracts a numeric product id from the path and an optional `currency` query parameter. **Instructions:** 1. Add a route `/products/{id}`. 2. Write a handler that takes `Path<u64>` and a `Query` of a struct with an `Option<String>` field named `currency`. 3. Return a string like `product 7 priced in USD`, defaulting the currency to `"USD"` when absent. Solution ```rust 1 use axum::{extract::{Path, Query}, routing::get, Router}; 2 use serde::Deserialize; 3 4 #[derive(Deserialize)] 5 struct PriceQuery { 6 currency: Option<String>, 7 } 8 9 async fn show_product(Path(id): Path<u64>, Query(q): Query<PriceQuery>) -> String { 10 let currency = q.currency.unwrap_or_else(|| "USD".to_string()); 11 format!("product {id} priced in {currency}") 12 } 13 14 #[tokio::main] 15 async fn main() { 16 let app = Router::new().route("/products/{id}", get(show_product)); 17 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000") 18 .await 19 .unwrap(); 20 axum::serve(listener, app).await.unwrap(); 21 } ``` `GET /products/7` returns `product 7 priced in USD`; `GET /products/7?currency=EUR` returns `product 7 priced in EUR`; `GET /products/abc` is rejected with a `400`. ### Exercise 2: Fix the ordering bug [Section titled “Exercise 2: Fix the ordering bug”](#exercise-2-fix-the-ordering-bug) **Difficulty:** Medium **Objective:** Repair a handler that fails to compile because its body extractor is in the wrong position. **Instructions:** The following handler does not compile. Identify why (add `#[axum::debug_handler]` if the error is unclear), then fix it so the route works. ```rust 1 use axum::{extract::{Json, Path}, routing::put, Router}; 2 use serde::Deserialize; 3 4 #[derive(Deserialize)] 5 struct Update { 6 name: String, 7 } 8 9 // does not compile 10 async fn rename(Json(body): Json<Update>, Path(id): Path<u64>) -> String { 11 format!("renamed {id} to {}", body.name) 12 } 13 14 fn app() -> Router { 15 Router::new().route("/users/{id}", put(rename)) 16 } ``` Solution `Json` consumes the request body and must be the **last** parameter. Move `Path` (a `FromRequestParts` extractor) ahead of it: ```rust 1 use axum::{extract::{Json, Path}, routing::put, Router}; 2 use serde::Deserialize; 3 4 #[derive(Deserialize)] 5 struct Update { 6 name: String, 7 } 8 9 async fn rename(Path(id): Path<u64>, Json(body): Json<Update>) -> String { 10 format!("renamed {id} to {}", body.name) 11 } 12 13 fn app() -> Router { 14 Router::new().route("/users/{id}", put(rename)) 15 } 16 17 #[tokio::main] 18 async fn main() { 19 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000") 20 .await 21 .unwrap(); 22 axum::serve(listener, app()).await.unwrap(); 23 } ``` `PUT /users/3` with body `{"name":"Bob"}` returns `renamed 3 to Bob`. ### Exercise 3: A custom guard extractor [Section titled “Exercise 3: A custom guard extractor”](#exercise-3-a-custom-guard-extractor) **Difficulty:** Hard **Objective:** Implement a `FromRequestParts` extractor that requires an `X-Request-Id` header and exposes it to handlers. **Instructions:** 1. Define a `RequestId(String)` newtype. 2. Implement `FromRequestParts<S>` for it (generic over any state `S: Send + Sync`). 3. If the `x-request-id` header is missing, reject with `400 Bad Request` and a message. 4. Use it in a handler alongside `Path<u64>` and confirm the ordering rules (metadata extractors can appear in any order among themselves). Solution ```rust 1 use axum::{ 2 extract::{FromRequestParts, Path}, 3 http::{request::Parts, HeaderName, StatusCode}, 4 routing::get, 5 Router, 6 }; 7 8 struct RequestId(String); 9 10 impl<S> FromRequestParts<S> for RequestId 11 where 12 S: Send + Sync, 13 { 14 type Rejection = (StatusCode, &'static str); 15 16 async fn from_request_parts( 17 parts: &mut Parts, 18 _state: &S, 19 ) -> Result<Self, Self::Rejection> { 20 let name = HeaderName::from_static("x-request-id"); 21 let value = parts 22 .headers 23 .get(&name) 24 .and_then(|v| v.to_str().ok()) 25 .ok_or((StatusCode::BAD_REQUEST, "missing X-Request-Id header"))?; 26 Ok(RequestId(value.to_string())) 27 } 28 } 29 30 async fn handler(RequestId(req_id): RequestId, Path(id): Path<u64>) -> String { 31 format!("request {req_id} -> resource {id}") 32 } 33 34 #[tokio::main] 35 async fn main() { 36 let app = Router::new().route("/items/{id}", get(handler)); 37 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000") 38 .await 39 .unwrap(); 40 axum::serve(listener, app).await.unwrap(); 41 } ``` `GET /items/9` without the header returns `400 missing X-Request-Id header`; with `-H 'X-Request-Id: abc123'` it returns `request abc123 -> resource 9`. Because both `RequestId` and `Path` are `FromRequestParts`, their order relative to each other does not matter. # Middleware and Layers > Express app.use becomes Axum's Tower layers and middleware::from_fn: cross-cutting logging, CORS, compression, and auth, plus the inside-out layer ordering in Rust. In Express.js, middleware is the workhorse for cross-cutting concerns: logging, authentication, CORS, compression, error handling. Axum has the same idea, but it borrows its plumbing from **Tower**, a general-purpose library for composing services. This chapter maps Express’s `app.use(fn)` mental model onto Axum’s `.layer(...)` and `middleware::from_fn(...)`, and shows the production-ready building blocks from the `tower-http` crate. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Middleware lets you run code **before and after** a request reaches your handler, without duplicating logic in every handler. Express middleware is a flat list of `(req, res, next)` functions; Axum uses **layers** (Tower’s reusable, composable middleware) plus a `from_fn` escape hatch for one-off async functions. The big payoff is `tower-http`, a battle-tested collection of ready-made layers (tracing, CORS, compression, timeouts, body limits) that you bolt onto a `Router` with one line each. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Here is a typical Express app wired with the usual cross-cutting middleware: a logger, CORS, gzip compression, and a route-specific auth guard. ```typescript 1 // app.ts — Express middleware stack 2 import express, { Request, Response, NextFunction } from "express"; 3 import cors from "cors"; 4 import compression from "compression"; 5 import morgan from "morgan"; 6 7 const app = express(); 8 9 // Global middleware — runs for EVERY request, top to bottom. 10 app.use(morgan("tiny")); // request logging 11 app.use(cors({ origin: "https://app.example.com" })); // CORS headers 12 app.use(compression()); // gzip responses 13 app.use(express.json()); // parse JSON bodies 14 15 // A custom middleware that times each request. 16 app.use((req: Request, res: Response, next: NextFunction) => { 17 const start = Date.now(); 18 res.on("finish", () => { 19 console.log(`${req.method} ${req.url} -> ${res.statusCode} (${Date.now() - start}ms)`); 20 }); 21 next(); // hand control to the next middleware/handler 22 }); 23 24 // Route-specific middleware: an auth guard for /admin only. 25 function requireApiKey(req: Request, res: Response, next: NextFunction) { 26 if (req.headers["x-api-key"] === "secret-token") { 27 next(); 28 } else { 29 res.status(401).end(); // short-circuit: never reaches the handler 30 } 31 } 32 33 app.get("/", (_req, res) => res.send("Hello, world!")); 34 app.get("/admin", requireApiKey, (_req, res) => res.send("Welcome, admin")); 35 36 app.listen(3000); ``` **Key points:** * `app.use(fn)` registers global middleware; order matters (top runs first). * Each middleware receives `next` and must call it (or end the response). * Calling `res.status(401).end()` **without** `next()` short-circuits the chain. * Route-specific middleware is passed as an argument before the handler. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Axum expresses the same stack with `tower-http` layers and a couple of `from_fn` functions. Add the dependencies first: ```bash 1 cargo new my-api 2 cd my-api 3 cargo add axum@0.8 4 cargo add tokio@1 --features full 5 cargo add tower-http --features "trace,cors,compression-full,timeout,limit" 6 cargo add tracing tracing-subscriber --features tracing-subscriber/env-filter ``` ```rust 1 // src/main.rs — equivalent Axum middleware stack 2 use axum::{ 3 Router, 4 routing::get, 5 middleware::{self, Next}, 6 extract::Request, 7 response::Response, 8 http::StatusCode, 9 }; 10 use tower_http::{ 11 trace::TraceLayer, 12 cors::CorsLayer, 13 compression::CompressionLayer, 14 }; 15 use std::time::Instant; 16 17 async fn root() -> &'static str { 18 "Hello, world!" 19 } 20 21 async fn admin() -> &'static str { 22 "Welcome, admin" 23 } 24 25 // A custom middleware that times each request (like the morgan-style logger). 26 // `Next` MUST be the last parameter. 27 async fn time_requests(req: Request, next: Next) -> Response { 28 let method = req.method().clone(); 29 let uri = req.uri().clone(); 30 let start = Instant::now(); 31 32 let response = next.run(req).await; // hand control to the inner layers + handler 33 34 println!("{} {} -> {} ({:?})", method, uri, response.status(), start.elapsed()); 35 response 36 } 37 38 // Route-specific auth guard. Returning Err short-circuits — the handler never runs. 39 async fn require_api_key(req: Request, next: Next) -> Result<Response, StatusCode> { 40 let key = req.headers().get("x-api-key").and_then(|v| v.to_str().ok()); 41 match key { 42 Some("secret-token") => Ok(next.run(req).await), 43 _ => Err(StatusCode::UNAUTHORIZED), 44 } 45 } 46 47 #[tokio::main] 48 async fn main() { 49 tracing_subscriber::fmt::init(); 50 51 let app = Router::new() 52 .route("/", get(root)) 53 // Route-specific middleware: only `/admin` is guarded. 54 .route("/admin", get(admin).route_layer(middleware::from_fn(require_api_key))) 55 // Global middleware, applied to every route on this router. 56 .layer(middleware::from_fn(time_requests)) 57 .layer(CompressionLayer::new()) 58 .layer(CorsLayer::new().allow_origin( 59 "https://app.example.com".parse::<axum::http::HeaderValue>().unwrap(), 60 )) 61 .layer(TraceLayer::new_for_http()); 62 63 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 64 axum::serve(listener, app).await.unwrap(); 65 } ``` **Key points:** * `.layer(...)` adds middleware to the whole router; `.route_layer(...)` scopes it to specific routes. * `tower-http` provides production-ready layers; you rarely hand-roll logging, CORS, or compression. * `middleware::from_fn` wraps a plain async function into a layer. * `next.run(req).await` is the equivalent of Express’s `next()`; returning `Err(...)` short-circuits. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `next.run(req).await` is Express’s `next()` [Section titled “next.run(req).await is Express’s next()”](#nextrunreqawait-is-expresss-next) In Express, you call `next()` to pass control along the chain and (usually) ignore its return value; the response is mutated through the shared `res` object. In Axum, the request flows *in* and a `Response` flows *back out*. `next.run(req)` consumes the request, runs everything “below” this middleware (deeper layers plus the handler), and **returns** the `Response`. Because it is an async function, you must `.await` it. This return-based model is why an Axum middleware can inspect or modify the response *after* the handler ran: ```rust 1 use axum::{extract::Request, middleware::Next, response::Response, http::HeaderValue}; 2 3 // Add a response header after the handler produces the response. 4 async fn add_version_header(req: Request, next: Next) -> Response { 5 let mut response = next.run(req).await; 6 response.headers_mut().insert( 7 "x-app-version", 8 HeaderValue::from_static("1.0.0"), 9 ); 10 response 11 } ``` In Express you would do this with `res.on("finish", ...)` or by wrapping `res.send`; in Axum it is just “mutate the value before you return it.” ### `Next` must come last [Section titled “Next must come last”](#next-must-come-last) `from_fn` lets the function take any number of Axum **extractors** (covered in [Extractors](/16-web-apis/04-extractors/)) before the final two special parameters: the `Request` and the `Next`. The `Next` value represents “the rest of the stack,” so it has to be the last argument. Getting this order wrong is a compile error (see [Common Pitfalls](#common-pitfalls)). ### `.layer()` vs `.route_layer()` [Section titled “.layer() vs .route\_layer()”](#layer-vs-route_layer) * `.layer(L)` wraps **every** route currently on the router (and is also inherited by anything you merge/nest under it). Use it for global concerns: tracing, CORS, compression. * `.route_layer(L)` wraps only the routes defined so far and, importantly, does **not** run for requests that hit the router’s 404 fallback. Use it for per-route guards like authentication. ### Layer ordering: outside-in for requests, inside-out for responses [Section titled “Layer ordering: outside-in for requests, inside-out for responses”](#layer-ordering-outside-in-for-requests-inside-out-for-responses) This is the single most surprising part for Express developers. When you chain calls like: ```rust 1 use axum::{Router, routing::get, middleware, extract::Request, response::Response, middleware::Next}; 2 use tower_http::trace::TraceLayer; 3 4 async fn root() -> &'static str { "ok" } 5 async fn outer(req: Request, next: Next) -> Response { next.run(req).await } 6 async fn inner(req: Request, next: Next) -> Response { next.run(req).await } 7 8 fn router() -> Router { 9 Router::new() 10 .route("/", get(root)) 11 .layer(middleware::from_fn(inner)) // added first -> closer to the handler 12 .layer(middleware::from_fn(outer)) // added last -> closer to the network 13 .layer(TraceLayer::new_for_http()) 14 } ``` The layer added **last** is the **outermost** — it sees the request first and the response last. A request flows `TraceLayer -> outer -> inner -> handler`, and the response unwinds back `handler -> inner -> outer -> TraceLayer`. This is the opposite of Express’s `app.use` order, where the *first* registered middleware runs *first*. (If you prefer Express’s top-to-bottom reading order, use `ServiceBuilder`; see [Best Practices](#best-practices).) We can prove the ordering with a real run. With both a logger (outermost) and an auth guard (inner) on the same route, hitting it without a valid key returns `401`, yet the outer logger still logs it, because the response unwinds back out through it: src/main.rs ```rust 1 use axum::{ 2 Router, routing::get, middleware::{self, Next}, 3 extract::Request, response::Response, http::StatusCode, 4 }; 5 use std::time::Instant; 6 7 async fn root() -> &'static str { "Hello, world!" } 8 9 async fn log_requests(req: Request, next: Next) -> Response { 10 let method = req.method().clone(); 11 let uri = req.uri().clone(); 12 let start = Instant::now(); 13 let response = next.run(req).await; 14 println!("{} {} -> {} ({:?})", method, uri, response.status(), start.elapsed()); 15 response 16 } 17 18 async fn require_api_key(req: Request, next: Next) -> Result<Response, StatusCode> { 19 let key = req.headers().get("x-api-key").and_then(|v| v.to_str().ok()); 20 match key { 21 Some("secret-token") => Ok(next.run(req).await), 22 _ => Err(StatusCode::UNAUTHORIZED), 23 } 24 } 25 26 #[tokio::main] 27 async fn main() { 28 let app = Router::new() 29 .route("/", get(root)) 30 .layer(middleware::from_fn(require_api_key)) // inner: added first 31 .layer(middleware::from_fn(log_requests)); // outer: added last 32 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 33 axum::serve(listener, app).await.unwrap(); 34 } ``` Hitting it twice (once with no key, once with the right key): ```bash 1 curl -i http://127.0.0.1:3000/ # no key 2 curl -i -H "x-api-key: secret-token" http://127.0.0.1:3000/ # valid key ``` The first request really returns `401`, the second `200`: ```plaintext 1 HTTP/1.1 401 Unauthorized 2 content-length: 0 3 4 HTTP/1.1 200 OK 5 content-type: text/plain; charset=utf-8 6 content-length: 13 ``` And the server’s standard output shows the **outer** logger ran for both, including the rejected request, with its real measured latency: ```plaintext 1 GET / -> 401 Unauthorized (25.083µs) 2 GET / -> 200 OK (13µs) ``` That is the inside-out unwinding in action: `require_api_key` produced the `401`, and the response traveled back out through `log_requests`. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | Express.js | Axum / Tower | | ------------------------ | ------------------------------------ | -------------------------------------------------------- | | Register middleware | `app.use(fn)` | `.layer(L)` or `.route_layer(L)` | | Pass control onward | `next()` | `next.run(req).await` | | Short-circuit | end `res` without `next()` | return early (e.g. `Err(StatusCode::...)`) | | Modify the response | mutate `res` / `res.on("finish")` | mutate the returned `Response` value | | Order of execution | first registered runs first | **last** `.layer` is outermost (or use `ServiceBuilder`) | | Reusable building blocks | npm packages (`cors`, `compression`) | `tower-http` layers (`CorsLayer`, `CompressionLayer`) | | Per-route scope | `app.get(path, mw, handler)` | `.route_layer(...)` on a `MethodRouter` | | Underlying abstraction | a function signature convention | the `tower::Service` / `tower::Layer` traits | The deepest difference is conceptual: Express middleware is a *convention* (a function shaped a certain way), while a Tower **layer** is a real type implementing the `Layer` and `Service` traits. That makes Axum middleware composable across frameworks: any Tower layer (from `tower`, `tower-http`, or your own crate) works unchanged, because Axum’s `Router` *is* a `tower::Service`. > **Note:** You almost never implement `tower::Service` by hand. `middleware::from_fn` covers the “I just need a quick async wrapper” case, and `tower-http` covers the common production needs. Hand-written `Service` impls are reserved for advanced, highly reusable middleware. ### The most useful `tower-http` layers [Section titled “The most useful tower-http layers”](#the-most-useful-tower-http-layers) ```rust 1 use tower_http::{ 2 trace::TraceLayer, // structured request/response logging 3 cors::CorsLayer, // CORS headers (see cors.md) 4 compression::CompressionLayer, // gzip/brotli/zstd response compression 5 timeout::TimeoutLayer, // abort slow requests 6 limit::RequestBodyLimitLayer, // reject oversized bodies 7 }; 8 use axum::http::StatusCode; 9 use std::time::Duration; 10 11 // Examples of constructing each (all compile-verified against tower-http 0.6): 12 let _trace = TraceLayer::new_for_http(); 13 let _compress = CompressionLayer::new(); 14 let _timeout = TimeoutLayer::with_status_code(StatusCode::REQUEST_TIMEOUT, Duration::from_secs(30)); 15 let _body_limit = RequestBodyLimitLayer::new(2 * 1024 * 1024); // 2 MiB 16 let _cors = CorsLayer::permissive(); ``` > **Tip:** `tower-http` features are opt-in. Enable only what you use, e.g. `cargo add tower-http --features "trace,cors,compression-full,timeout,limit"`. The `compression-full` feature enables gzip, brotli, deflate, and zstd; pick `compression-gzip` if you only need gzip. ### `TraceLayer`: real output [Section titled “TraceLayer: real output”](#tracelayer-real-output) `TraceLayer::new_for_http()` emits structured `tracing` spans and events for every request. Wire up a subscriber so you can see them: src/main.rs ```rust 1 use axum::{Router, routing::get}; 2 use tower_http::trace::TraceLayer; 3 use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt}; 4 5 async fn root() -> &'static str { "Hello, world!" } 6 7 #[tokio::main] 8 async fn main() { 9 tracing_subscriber::registry() 10 .with( 11 tracing_subscriber::EnvFilter::try_from_default_env() 12 .unwrap_or_else(|_| "my_api=debug,tower_http=debug".into()), 13 ) 14 .with(tracing_subscriber::fmt::layer()) 15 .init(); 16 17 let app = Router::new() 18 .route("/", get(root)) 19 .layer(TraceLayer::new_for_http()); 20 21 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 22 axum::serve(listener, app).await.unwrap(); 23 } ``` Two `curl http://127.0.0.1:3000/` requests produce this real output (run with `RUST_LOG=tower_http=debug`): ```plaintext 1 2026-06-01T11:45:31.785175Z DEBUG request{method=GET uri=/ version=HTTP/1.1}: tower_http::trace::on_request: started processing request 2 2026-06-01T11:45:31.785454Z DEBUG request{method=GET uri=/ version=HTTP/1.1}: tower_http::trace::on_response: finished processing request latency=0 ms status=200 3 2026-06-01T11:45:31.802161Z DEBUG request{method=GET uri=/ version=HTTP/1.1}: tower_http::trace::on_request: started processing request 4 2026-06-01T11:45:31.802222Z DEBUG request{method=GET uri=/ version=HTTP/1.1}: tower_http::trace::on_response: finished processing request latency=0 ms status=200 ``` Notice the `request{...}` **span** that wraps each request: every log inside a handler automatically inherits the method and URI fields, so your application logs are correlated to the request that produced them. That structured correlation is something Express’s string-based loggers do not give you for free. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting `.await` on `next.run(req)` [Section titled “Pitfall 1: Forgetting .await on next.run(req)”](#pitfall-1-forgetting-await-on-nextrunreq) Because `next.run` is async, forgetting the `.await` hands back a `Future` where a `Response` is expected. ```rust 1 use axum::{extract::Request, middleware::Next, response::Response}; 2 3 async fn broken(req: Request, next: Next) -> Response { 4 next.run(req) // does not compile (error[E0308]): forgot `.await`, returns a Future 5 } ``` The real compiler error is clear and even suggests the fix: ```plaintext 1 error[E0308]: mismatched types 2 --> src/main.rs:14:5 3 | 4 14 | next.run(req) // forgot .await — returns a Future, not a Response 5 | ^^^^^^^^^^^^^ expected `Response<Body>`, found future 6 | 7 note: calling an async function returns a future 8 help: consider `await`ing on the `Future` 9 | 10 14 | next.run(req).await 11 | ++++++ ``` ### Pitfall 2: Putting `Next` before the `Request` [Section titled “Pitfall 2: Putting Next before the Request”](#pitfall-2-putting-next-before-the-request) The `Next` argument must be **last**. Swap the order and the function no longer satisfies the trait bound `from_fn` requires, so `.layer(...)` rejects it. ```rust 1 use axum::{extract::Request, middleware::Next, response::Response}; 2 3 async fn wrong_order(next: Next, req: Request) -> Response { // does not compile (error[E0277]) 4 next.run(req).await 5 } ``` The real error points at the failed `Service` bound (trimmed for length): ```plaintext 1 error[E0277]: the trait bound `FromFn<fn(Next, Request<Body>) -> ... {wrong_order}, ...>: Service<...>` is not satisfied 2 --> src/main.rs:19:16 3 | 4 19 | .layer(middleware::from_fn(wrong_order)); 5 | ----- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ unsatisfied trait bound 6 | 7 = help: the trait `tower_service::Service<...Request...>` is not implemented for `FromFn<fn(Next, Request<Body>) -> ...>` 8 note: required by a bound in `Router::<S>::layer` ``` It is not the friendliest message — when you see “the trait bound `FromFn<...>: Service<...>` is not satisfied,” the first thing to check is that your `from_fn` parameters end with `Request` then `Next` (in that order). ### Pitfall 3: Expecting Express’s top-to-bottom layer order [Section titled “Pitfall 3: Expecting Express’s top-to-bottom layer order”](#pitfall-3-expecting-expresss-top-to-bottom-layer-order) Reading a chain of `.layer(a).layer(b).layer(c)` top-to-bottom and assuming `a` runs first is the classic mistake. The **last** layer added is the outermost and runs first. If you want CORS to wrap (and thus run before) your auth middleware, add CORS *after* auth in the chain, or switch to `ServiceBuilder`, where the reading order matches execution order. ### Pitfall 4: `.layer()` not applying to your 404 fallback (or applying when you didn’t want it to) [Section titled “Pitfall 4: .layer() not applying to your 404 fallback (or applying when you didn’t want it to)”](#pitfall-4-layer-not-applying-to-your-404-fallback-or-applying-when-you-didnt-want-it-to) `.layer()` applies to everything currently on the router, including the fallback handler. `.route_layer()` does not run for unmatched routes. Putting an auth guard with `.layer()` instead of `.route_layer()` means unauthenticated requests to nonexistent paths get a `401` instead of a `404`, leaking the difference between “exists but forbidden” and “doesn’t exist.” For per-route guards, prefer `.route_layer()`. ### Pitfall 5: Middleware order causing wasted work [Section titled “Pitfall 5: Middleware order causing wasted work”](#pitfall-5-middleware-order-causing-wasted-work) Compression should sit **outside** (run after) most other layers so it compresses the final response, but **inside** tracing if you want the trace to record the compressed size. Body-limit and timeout layers should be near the outside so they reject bad requests early, before you spend effort parsing JSON or hitting the database. Order is correctness *and* performance. ### Pitfall 6: Stacking `RequestBodyLimitLayer` with `CompressionLayer` inside a `ServiceBuilder` [Section titled “Pitfall 6: Stacking RequestBodyLimitLayer with CompressionLayer inside a ServiceBuilder”](#pitfall-6-stacking-requestbodylimitlayer-with-compressionlayer-inside-a-servicebuilder) Each `tower-http` layer wraps the request and/or response body in its own type. When you compose `RequestBodyLimitLayer` and `CompressionLayer` directly inside a single `ServiceBuilder`, the nested body type (`ResponseBody<CompressionBody<Body>>`) does not satisfy a trait bound the inner stack needs, and you get a confusing `Default`-related error: ```plaintext 1 error[E0277]: the trait bound `tower_http::limit::ResponseBody<CompressionBody<Body>>: std::default::Default` is not satisfied 2 --> src/main.rs:14:10 3 | 4 14 | .layer( 5 | ^^^^^ the trait `std::default::Default` is not implemented for `tower_http::limit::ResponseBody<CompressionBody<Body>>` ``` The fix is to apply the body limit as its **own** chained `.layer(...)` on the `Router`, leaving the rest in the `ServiceBuilder`. Axum normalizes the body type between separate `.layer` calls, which keeps the bounds satisfied: ```rust 1 use axum::{Router, routing::get, http::StatusCode}; 2 use tower::ServiceBuilder; 3 use tower_http::{ 4 trace::TraceLayer, timeout::TimeoutLayer, 5 limit::RequestBodyLimitLayer, compression::CompressionLayer, 6 }; 7 use std::time::Duration; 8 9 async fn root() -> &'static str { "ok" } 10 11 fn build_router() -> Router { 12 Router::new() 13 .route("/", get(root)) 14 // Body limit on its own layer — NOT inside the ServiceBuilder below. 15 .layer(RequestBodyLimitLayer::new(512 * 1024)) 16 .layer( 17 ServiceBuilder::new() 18 .layer(TraceLayer::new_for_http()) 19 .layer(TimeoutLayer::with_status_code( 20 StatusCode::REQUEST_TIMEOUT, 21 Duration::from_secs(10), 22 )) 23 .layer(CompressionLayer::new()), 24 ) 25 } 26 27 #[tokio::main] 28 async fn main() { 29 let app = build_router(); 30 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 31 axum::serve(listener, app).await.unwrap(); 32 } ``` *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Use `ServiceBuilder` for readable ordering [Section titled “Use ServiceBuilder for readable ordering”](#use-servicebuilder-for-readable-ordering) When stacking several layers, `tower::ServiceBuilder` lets you list them in the order they execute (outermost first, the natural top-to-bottom reading order), which is easier to reason about than the “last `.layer` wins” rule. Add the helper feature: ```bash 1 cargo add tower --features util ``` ```rust 1 use axum::{Router, routing::get}; 2 use tower::ServiceBuilder; 3 use tower_http::{trace::TraceLayer, cors::CorsLayer, compression::CompressionLayer}; 4 5 async fn root() -> &'static str { "ok" } 6 7 fn build_router() -> Router { 8 Router::new() 9 .route("/", get(root)) 10 .layer( 11 ServiceBuilder::new() 12 .layer(TraceLayer::new_for_http()) // outermost: runs first 13 .layer(CorsLayer::permissive()) 14 .layer(CompressionLayer::new()), // innermost: runs last 15 ) 16 } 17 18 #[tokio::main] 19 async fn main() { 20 let app = build_router(); 21 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 22 axum::serve(listener, app).await.unwrap(); 23 } ``` > **Tip:** With `ServiceBuilder`, layers execute **top to bottom** for the request, exactly like reading Express’s `app.use` calls. This is the recommended way to assemble a multi-layer stack. ### Reach for `tower-http` before hand-rolling [Section titled “Reach for tower-http before hand-rolling”](#reach-for-tower-http-before-hand-rolling) Do not write your own request logger, CORS handler, or compression middleware. `tower-http` versions are correct, tested, and integrate with `tracing`. Save `from_fn` for genuinely app-specific logic (custom auth, request enrichment, feature flags). ### Pass state into middleware with `from_fn_with_state` [Section titled “Pass state into middleware with from\_fn\_with\_state”](#pass-state-into-middleware-with-from_fn_with_state) When your middleware needs shared state (a database pool, a config value, a key), use `from_fn_with_state`. The state is extracted just like in a handler via `State<T>` (covered in [Shared Application State in Axum](/16-web-apis/06-state-management/)): ```rust 1 use axum::{ 2 Router, routing::get, middleware::{self, Next}, 3 extract::{Request, State}, response::Response, http::StatusCode, 4 }; 5 use std::sync::Arc; 6 7 #[derive(Clone)] 8 struct AppState { 9 api_key: Arc<String>, 10 } 11 12 async fn root() -> &'static str { "ok" } 13 14 // State-aware middleware: `State` extractor first, then `Request`, then `Next`. 15 async fn require_api_key( 16 State(state): State<AppState>, 17 req: Request, 18 next: Next, 19 ) -> Result<Response, StatusCode> { 20 let provided = req.headers().get("x-api-key").and_then(|v| v.to_str().ok()); 21 if provided == Some(state.api_key.as_str()) { 22 Ok(next.run(req).await) 23 } else { 24 Err(StatusCode::UNAUTHORIZED) 25 } 26 } 27 28 fn build_router(state: AppState) -> Router { 29 Router::new() 30 .route("/", get(root)) 31 .route_layer(middleware::from_fn_with_state(state.clone(), require_api_key)) 32 .with_state(state) 33 } 34 35 #[tokio::main] 36 async fn main() { 37 let state = AppState { api_key: Arc::new("secret".to_string()) }; 38 let app = build_router(state); 39 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 40 axum::serve(listener, app).await.unwrap(); 41 } ``` ### Prefer returning a `Result` for short-circuiting [Section titled “Prefer returning a Result for short-circuiting”](#prefer-returning-a-result-for-short-circuiting) Returning `Result<Response, StatusCode>` (or, better, a custom error type that implements `IntoResponse`) from a `from_fn` middleware is the idiomatic way to bail out early. It is type-checked and composes with the error-handling patterns in [Error Handling in Web Handlers](/16-web-apis/10-error-handling-web/). For real authentication, build an extractor-as-guard or an `AuthUser` extractor instead of inline header checks; see [Authentication Patterns](/16-web-apis/12-authentication/) and [JWT Authentication](/16-web-apis/13-jwt/). ### Set sensible defaults for production [Section titled “Set sensible defaults for production”](#set-sensible-defaults-for-production) A production router should almost always include: `TraceLayer` (observability), a `TimeoutLayer` (don’t let slow clients tie up tasks), a `RequestBodyLimitLayer` (reject oversized uploads early), `CompressionLayer`, and a deliberately configured `CorsLayer` (not the permissive default in production; see [CORS with Axum and tower-http](/16-web-apis/11-cors/)). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored API router that combines `tower-http` layers, a custom request-ID middleware, and a state-aware auth guard scoped to protected routes. This compiles against axum 0.8 and tower-http 0.6. src/main.rs ```rust 1 use axum::{ 2 Router, 3 routing::{get, post}, 4 middleware::{self, Next}, 5 extract::{Request, State}, 6 response::Response, 7 http::{StatusCode, HeaderValue, Method, header}, 8 Json, 9 }; 10 use tower_http::{ 11 trace::TraceLayer, 12 cors::CorsLayer, 13 compression::CompressionLayer, 14 timeout::TimeoutLayer, 15 limit::RequestBodyLimitLayer, 16 }; 17 use serde_json::json; 18 use std::{sync::Arc, time::Duration}; 19 use uuid::Uuid; 20 21 #[derive(Clone)] 22 struct AppState { 23 api_key: Arc<String>, 24 } 25 26 // Public health check — no auth. 27 async fn health() -> Json<serde_json::Value> { 28 Json(json!({ "status": "ok" })) 29 } 30 31 // Protected handler. 32 async fn create_widget() -> (StatusCode, Json<serde_json::Value>) { 33 (StatusCode::CREATED, Json(json!({ "id": 1, "name": "widget" }))) 34 } 35 36 // Custom middleware: attach a request ID header to every response. 37 async fn request_id(req: Request, next: Next) -> Response { 38 let id = Uuid::new_v4().to_string(); 39 let mut response = next.run(req).await; 40 if let Ok(value) = HeaderValue::from_str(&id) { 41 response.headers_mut().insert("x-request-id", value); 42 } 43 response 44 } 45 46 // State-aware auth guard for the protected routes. 47 async fn require_api_key( 48 State(state): State<AppState>, 49 req: Request, 50 next: Next, 51 ) -> Result<Response, StatusCode> { 52 let provided = req.headers().get("x-api-key").and_then(|v| v.to_str().ok()); 53 if provided == Some(state.api_key.as_str()) { 54 Ok(next.run(req).await) 55 } else { 56 Err(StatusCode::UNAUTHORIZED) 57 } 58 } 59 60 fn build_router(state: AppState) -> Router { 61 // CORS locked to a known frontend origin. 62 let cors = CorsLayer::new() 63 .allow_origin("https://app.example.com".parse::<HeaderValue>().unwrap()) 64 .allow_methods([Method::GET, Method::POST]) 65 .allow_headers([header::CONTENT_TYPE, header::AUTHORIZATION]) 66 .allow_credentials(true); 67 68 // Protected routes carry their own auth guard via `route_layer`. 69 let protected = Router::new() 70 .route("/widgets", post(create_widget)) 71 .route_layer(middleware::from_fn_with_state(state.clone(), require_api_key)); 72 73 Router::new() 74 .route("/health", get(health)) 75 .merge(protected) 76 // Global stack (last added = outermost). 77 .layer(middleware::from_fn(request_id)) 78 .layer(CompressionLayer::new()) 79 .layer(cors) 80 .layer(TimeoutLayer::with_status_code( 81 StatusCode::REQUEST_TIMEOUT, 82 Duration::from_secs(15), 83 )) 84 .layer(RequestBodyLimitLayer::new(1024 * 1024)) // 1 MiB max body 85 .layer(TraceLayer::new_for_http()) 86 .with_state(state) 87 } 88 89 #[tokio::main] 90 async fn main() { 91 tracing_subscriber::fmt::init(); 92 93 let state = AppState { api_key: Arc::new("secret-token".to_string()) }; 94 let app = build_router(state); 95 96 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 97 println!("listening on http://0.0.0.0:3000"); 98 axum::serve(listener, app).await.unwrap(); 99 } ``` This example needs two extra crates beyond the earlier list: ```bash 1 cargo add serde_json 2 cargo add uuid --features v4 ``` `/health` is open; `POST /widgets` requires `x-api-key: secret-token`. Every response (success or `401`) carries an `x-request-id` header because `request_id` is global and the response unwinds back out through it. Oversized bodies are rejected by `RequestBodyLimitLayer` before they reach a handler, and slow requests are cut off by the timeout — defenses you get for free from `tower-http`. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [axum `middleware` module](https://docs.rs/axum/0.8/axum/middleware/index.html) — `from_fn`, `from_fn_with_state`, and the layering rules * [`tower-http` crate docs](https://docs.rs/tower-http/0.6/tower_http/) — every ready-made layer with examples * [`tower::ServiceBuilder`](https://docs.rs/tower/latest/tower/struct.ServiceBuilder.html) — ordered layer composition * [Tower guide: “Inventing the `Service` trait”](https://tokio.rs/blog/2021-05-14-inventing-the-service-trait) — the abstraction under Axum middleware ### Related Topics [Section titled “Related Topics”](#related-topics) * [Axum Basics](/16-web-apis/01-axum-basics/) — Router and handler fundamentals * [Extractors](/16-web-apis/04-extractors/) — how middleware parameters before `Next` are resolved * [State Management](/16-web-apis/06-state-management/) — sharing a DB pool/config with `from_fn_with_state` * [Request and Response](/16-web-apis/07-request-response/) — `IntoResponse`, status codes, headers * [Error Handling](/16-web-apis/10-error-handling-web/) — short-circuiting with a custom error type * [CORS](/16-web-apis/11-cors/) — configuring `CorsLayer` for production * [Authentication](/16-web-apis/12-authentication/) and [JWT](/16-web-apis/13-jwt/) — turning auth middleware into proper guards * [Async/Await](/11-async/) — why `next.run(req).await` needs the `.await` * [Functions](/03-functions/) and [Ownership](/05-ownership/) — the borrowing rules behind `req.headers()` * Next section: [Databases](/17-database/) — the DB pool you will inject through state and middleware *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A response-timing header [Section titled “Exercise 1: A response-timing header”](#exercise-1-a-response-timing-header) **Difficulty:** Easy **Objective:** Write a `from_fn` middleware that measures how long a request took and adds the duration (in milliseconds) as an `x-response-time-ms` response header. **Instructions:** 1. Capture an `Instant` before calling `next.run(req).await`. 2. After the response comes back, compute the elapsed time in milliseconds. 3. Insert it as the `x-response-time-ms` header on the response, then return the response. 4. Attach it to a one-route router with `.layer(...)`. ```rust 1 use axum::{ 2 Router, routing::get, middleware::{self, Next}, 3 extract::Request, response::Response, http::HeaderValue, 4 }; 5 use std::time::Instant; 6 7 async fn root() -> &'static str { "ok" } 8 9 async fn timing_header(req: Request, next: Next) -> Response { 10 let start = Instant::now(); 11 let mut response = next.run(req).await; 12 // TODO: compute elapsed ms and insert the `x-response-time-ms` header 13 response 14 } 15 16 #[tokio::main] 17 async fn main() { 18 let app = Router::new() 19 .route("/", get(root)) 20 .layer(middleware::from_fn(timing_header)); 21 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 22 axum::serve(listener, app).await.unwrap(); 23 } ``` Solution ```rust 1 use axum::{ 2 Router, routing::get, middleware::{self, Next}, 3 extract::Request, response::Response, http::HeaderValue, 4 }; 5 use std::time::Instant; 6 7 async fn root() -> &'static str { "ok" } 8 9 async fn timing_header(req: Request, next: Next) -> Response { 10 let start = Instant::now(); 11 let mut response = next.run(req).await; 12 13 let ms = start.elapsed().as_millis(); 14 if let Ok(value) = HeaderValue::from_str(&ms.to_string()) { 15 response.headers_mut().insert("x-response-time-ms", value); 16 } 17 response 18 } 19 20 #[tokio::main] 21 async fn main() { 22 let app = Router::new() 23 .route("/", get(root)) 24 .layer(middleware::from_fn(timing_header)); 25 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 26 axum::serve(listener, app).await.unwrap(); 27 } ``` A request now returns a header like `x-response-time-ms: 0`. The header is added *after* `next.run` returns; that “after the handler” hook is exactly what the inside-out unwinding enables. ### Exercise 2: A role-based guard with state [Section titled “Exercise 2: A role-based guard with state”](#exercise-2-a-role-based-guard-with-state) **Difficulty:** Medium **Objective:** Write a `from_fn_with_state` middleware that only allows requests whose `x-role` header matches a required role stored in application state; otherwise return `403 Forbidden`. **Instructions:** 1. Define an `AppState { required_role: Arc<String> }` that derives `Clone`. 2. Write `require_role(State(state), req, next)` returning `Result<Response, StatusCode>`. 3. Read the `x-role` header; if it equals the required role, proceed, else return `StatusCode::FORBIDDEN`. 4. Wire it with `route_layer(middleware::from_fn_with_state(...))` and `with_state`. Solution ```rust 1 use axum::{ 2 Router, routing::get, middleware::{self, Next}, 3 extract::{Request, State}, response::Response, http::StatusCode, 4 }; 5 use std::sync::Arc; 6 7 #[derive(Clone)] 8 struct AppState { 9 required_role: Arc<String>, 10 } 11 12 async fn admin_panel() -> &'static str { "admin panel" } 13 14 async fn require_role( 15 State(state): State<AppState>, 16 req: Request, 17 next: Next, 18 ) -> Result<Response, StatusCode> { 19 let role = req.headers().get("x-role").and_then(|v| v.to_str().ok()); 20 if role == Some(state.required_role.as_str()) { 21 Ok(next.run(req).await) 22 } else { 23 Err(StatusCode::FORBIDDEN) 24 } 25 } 26 27 fn build_router(state: AppState) -> Router { 28 Router::new() 29 .route("/admin", get(admin_panel)) 30 .route_layer(middleware::from_fn_with_state(state.clone(), require_role)) 31 .with_state(state) 32 } 33 34 #[tokio::main] 35 async fn main() { 36 let state = AppState { required_role: Arc::new("admin".to_string()) }; 37 let app = build_router(state); 38 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 39 axum::serve(listener, app).await.unwrap(); 40 } ``` `curl -H "x-role: admin" http://127.0.0.1:3000/admin` succeeds; any other role gets `403`. Because the guard is on a `route_layer`, requests to unknown paths still fall through to a normal `404` rather than being rejected as forbidden. ### Exercise 3: Assemble a production stack with `ServiceBuilder` [Section titled “Exercise 3: Assemble a production stack with ServiceBuilder”](#exercise-3-assemble-a-production-stack-with-servicebuilder) **Difficulty:** Hard **Objective:** Build a router whose layers execute in this order for incoming requests: tracing (outermost), then a 10-second timeout, then a custom `request_id` middleware, then compression (innermost), using `ServiceBuilder` so the code reads top-to-bottom in execution order. **Instructions:** 1. Add `tower` with the `util` feature and `tower-http` with `trace,timeout,compression-full`. 2. Write a `request_id` `from_fn` middleware that adds an `x-request-id` response header. 3. Construct a `ServiceBuilder` listing the four layers in execution order. 4. Apply it to a router with a single `GET /` route via one `.layer(...)` call, return `Router`, and verify it compiles. Solution ```rust 1 use axum::{ 2 Router, routing::get, middleware::{self, Next}, 3 extract::Request, response::Response, http::{StatusCode, HeaderValue}, 4 }; 5 use tower::ServiceBuilder; 6 use tower_http::{trace::TraceLayer, timeout::TimeoutLayer, compression::CompressionLayer}; 7 use std::time::Duration; 8 9 async fn root() -> &'static str { "ok" } 10 11 async fn request_id(req: Request, next: Next) -> Response { 12 let mut response = next.run(req).await; 13 response.headers_mut().insert("x-request-id", HeaderValue::from_static("demo")); 14 response 15 } 16 17 fn build_router() -> Router { 18 Router::new() 19 .route("/", get(root)) 20 .layer( 21 ServiceBuilder::new() 22 .layer(TraceLayer::new_for_http()) // outermost: runs first 23 .layer(TimeoutLayer::with_status_code( 24 StatusCode::REQUEST_TIMEOUT, 25 Duration::from_secs(10), 26 )) 27 .layer(middleware::from_fn(request_id)) 28 .layer(CompressionLayer::new()), // innermost: runs last 29 ) 30 } 31 32 #[tokio::main] 33 async fn main() { 34 let app = build_router(); 35 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 36 axum::serve(listener, app).await.unwrap(); 37 } ``` Required dependencies: ```bash 1 cargo add tower --features util 2 cargo add tower-http --features "trace,timeout,compression-full" ``` With `ServiceBuilder`, the request travels through the layers in the exact order written: tracing wraps everything, the timeout cuts off slow requests, `request_id` tags the response, and compression runs closest to the handler so it compresses the final response. > **Tip:** If you also need a `RequestBodyLimitLayer`, add it as a separate chained `.layer(...)` rather than inside this `ServiceBuilder`; see the body-limit composition pitfall above for why. # Shared Application State in Axum > Where Express threads dependencies through module variables, Axum bundles them in one Clone-able State struct. Share with Arc, mutate with Mutex, split with FromRef. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Almost every real web service needs **shared state**: a database connection pool, parsed configuration, an outbound HTTP client, a cache, a metrics handle. In Express you usually reach for module-level variables or `app.locals`/`req.app.get(...)`; in Axum you put everything in one `State<T>` value that the framework hands to each handler. This page covers the idiomatic pattern: a `Clone`-able state struct, `Arc` for the bits that need sharing, when to use request **extensions** instead, and how to inject a pool or config without globals. > **Note:** This page targets the **axum 0.8** API line (recorded with 0.8.9) and the Rust 2024 edition. State is attached with `Router::with_state(...)` and read with the `State<T>` extractor. There is no `Server::bind()` builder and path parameters use `{id}`, not `:id`. The `#[derive(FromRef)]` macro shown later needs `cargo add axum --features macros`. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) A typical Express service threads dependencies through closures or module scope. Here is a small users API that holds a config object, a database handle, and a request counter: ```typescript 1 // server.ts — Express 5 2 import express, { Request, Response } from "express"; 3 4 // Loaded once at startup. 5 interface Config { 6 serviceName: string; 7 maxItems: number; 8 } 9 10 // Stand-in for a real connection pool (e.g. a `pg.Pool`). 11 class Db { 12 private notes: { id: number; text: string }[] = []; 13 list() { 14 return this.notes; 15 } 16 create(text: string) { 17 const note = { id: this.notes.length + 1, text }; 18 this.notes.push(note); 19 return note; 20 } 21 } 22 23 // Shared, mutable across all requests — just a closure variable. 24 const config: Config = { serviceName: "notes-api", maxItems: 100 }; 25 const db = new Db(); 26 let requestCount = 0; 27 28 const app = express(); 29 app.use(express.json()); 30 31 app.get("/info", (_req: Request, res: Response) => { 32 requestCount += 1; 33 res.json({ app: config.serviceName, maxItems: config.maxItems, requestsServed: requestCount }); 34 }); 35 36 app.get("/notes", (_req: Request, res: Response) => { 37 res.json(db.list()); 38 }); 39 40 app.post("/notes", (req: Request, res: Response) => { 41 if (db.list().length >= config.maxItems) { 42 res.status(409).json({ error: "too many notes" }); 43 return; 44 } 45 const note = db.create(req.body.text as string); 46 res.status(201).json(note); 47 }); 48 49 app.listen(3000, () => console.log("listening on http://127.0.0.1:3000")); ``` This works because JavaScript is single-threaded: `requestCount += 1` and `db.create(...)` can never run concurrently, so nobody worries about data races. The dependencies are just variables in scope. There is also no type-level guarantee that a handler has access to what it needs: if you forget to define `db`, you find out at runtime. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) In Axum you bundle the dependencies into one struct, attach it with `.with_state(...)`, and each handler asks for it via the `State` extractor. The struct must be `Clone`; anything that should be **shared** (rather than copied per request) goes behind an `Arc`. ```rust 1 use axum::{ 2 extract::State, 3 http::StatusCode, 4 response::IntoResponse, 5 routing::get, 6 Json, Router, 7 }; 8 use serde::{Deserialize, Serialize}; 9 use std::sync::{ 10 atomic::{AtomicU64, Ordering}, 11 Arc, Mutex, 12 }; 13 14 // Immutable configuration loaded once at startup. 15 #[derive(Clone)] 16 struct Config { 17 app_name: String, 18 max_items: usize, 19 } 20 21 // A stand-in for a real database connection pool. In a real app this is 22 // `sqlx::PgPool` or similar — already internally an Arc, so cloning is cheap. 23 #[derive(Clone, Default)] 24 struct Db { 25 notes: Arc<Mutex<Vec<Note>>>, 26 } 27 28 #[derive(Clone, Serialize)] 29 struct Note { 30 id: u64, 31 text: String, 32 } 33 34 #[derive(Deserialize)] 35 struct NewNote { 36 text: String, 37 } 38 39 // The whole application state. One struct holds every dependency a handler 40 // might need. It derives `Clone` so the router can hand each request its own 41 // (cheap) clone — every field is itself cheap to clone. 42 #[derive(Clone)] 43 struct AppState { 44 config: Config, 45 db: Db, 46 request_count: Arc<AtomicU64>, 47 } 48 49 // GET /info — read-only config access, plus a lock-free counter bump. 50 async fn info(State(state): State<AppState>) -> Json<serde_json::Value> { 51 let n = state.request_count.fetch_add(1, Ordering::Relaxed) + 1; 52 Json(serde_json::json!({ 53 "app": state.config.app_name, 54 "max_items": state.config.max_items, 55 "requests_served": n, 56 })) 57 } 58 59 // GET /notes — read the shared list behind the mutex. 60 async fn list_notes(State(state): State<AppState>) -> Json<Vec<Note>> { 61 let notes = state.db.notes.lock().unwrap(); 62 Json(notes.clone()) 63 } 64 65 // POST /notes — mutate shared state, honoring a config limit. 66 async fn create_note( 67 State(state): State<AppState>, 68 Json(body): Json<NewNote>, 69 ) -> Result<impl IntoResponse, StatusCode> { 70 let mut notes = state.db.notes.lock().unwrap(); 71 if notes.len() >= state.config.max_items { 72 return Err(StatusCode::CONFLICT); 73 } 74 let note = Note { id: notes.len() as u64 + 1, text: body.text }; 75 notes.push(note.clone()); 76 Ok((StatusCode::CREATED, Json(note))) 77 } 78 79 // Router builder: attach state once with `.with_state(...)`. 80 fn app(state: AppState) -> Router { 81 Router::new() 82 .route("/info", get(info)) 83 .route("/notes", get(list_notes).post(create_note)) 84 .with_state(state) 85 } 86 87 #[tokio::main] 88 async fn main() { 89 let state = AppState { 90 config: Config { app_name: "notes-api".to_string(), max_items: 100 }, 91 db: Db::default(), 92 request_count: Arc::new(AtomicU64::new(0)), 93 }; 94 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 95 println!("listening on {}", listener.local_addr().unwrap()); 96 axum::serve(listener, app(state)).await.unwrap(); 97 } ``` Dependencies (run in a fresh `cargo new` project; `cargo add` resolves current versions): ```bash 1 cargo add axum 2 cargo add tokio --features full 3 cargo add serde --features derive 4 cargo add serde_json ``` ```toml 1 [dependencies] 2 axum = "0.8.9" 3 serde = { version = "1.0.228", features = ["derive"] } 4 serde_json = "1.0.150" 5 tokio = { version = "1.52.3", features = ["full"] } ``` Running it and hitting the endpoints produces this **real** output (captured against the compiled server): ```text 1 $ curl -s http://127.0.0.1:3000/info 2 {"app":"notes-api","max_items":100,"requests_served":1} 3 4 $ curl -s http://127.0.0.1:3000/info 5 {"app":"notes-api","max_items":100,"requests_served":2} 6 7 $ curl -s -i -X POST http://127.0.0.1:3000/notes \ 8 -H 'content-type: application/json' -d '{"text":"buy milk"}' 9 HTTP/1.1 201 Created 10 content-type: application/json 11 content-length: 26 12 date: Mon, 01 Jun 2026 11:49:16 GMT 13 14 {"id":1,"text":"buy milk"} 15 16 $ curl -s http://127.0.0.1:3000/notes 17 [{"id":1,"text":"buy milk"}] ``` *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### One struct, attached once, extracted per handler [Section titled “One struct, attached once, extracted per handler”](#one-struct-attached-once-extracted-per-handler) ```rust 1 #[derive(Clone)] 2 struct AppState { 3 config: Config, 4 db: Db, 5 request_count: Arc<AtomicU64>, 6 } ``` Where Express uses free-floating closure variables, Axum collects them into a single `struct`. You attach it to the router **once** with `.with_state(state)`, and every handler that needs it declares a `State<AppState>` parameter. This is dependency injection done through the type system: a handler’s signature lists exactly what it depends on, and the program will not compile if you wire the state up wrong (more on that in Common Pitfalls). ### Why `State<T>` requires `Clone` [Section titled “Why State\<T> requires Clone”](#why-statet-requires-clone) Axum gives each incoming request access to the state by **cloning** it. That sounds expensive until you see *what* is being cloned: * `Config` is a couple of fields: cloning it copies a `String` and a `usize`. Fine, but you could also wrap it in `Arc` to avoid even that. * `Db { notes: Arc<Mutex<Vec<Note>>> }` clones to a *new `Arc` pointer to the same `Vec`*. Cloning an `Arc` just increments an atomic reference count; it does **not** copy the `Vec`. Every handler shares the same underlying data. * `Arc<AtomicU64>` clones the same way: all clones point at the one counter. So `AppState: Clone` is cheap by construction: the *sharable* parts are `Arc`s, and cloning an `Arc` is a pointer-plus-refcount-bump. This is the central idea — **`Arc` is how you say “shared,” and `Clone` on the state is how Axum distributes that shared handle.** > **Note:** `Arc` stands for *atomically reference-counted*. It is the multi-threaded sibling of `Rc`. Axum’s default scheduler can run handlers on different OS threads, so shared state must be `Arc`, not `Rc`. See [Reference Counting with Rc and Arc](/10-smart-pointers/01-rc-arc/) and [The Arc + Mutex Pattern](/11-async/12-arc-mutex-pattern/). ### Shared *mutable* state needs a lock [Section titled “Shared mutable state needs a lock”](#shared-mutable-state-needs-a-lock) ```rust 1 let mut notes = state.db.notes.lock().unwrap(); 2 notes.push(note.clone()); ``` In JavaScript, `notes.push(...)` is safe by accident: the single-threaded event loop guarantees no two handlers touch `notes` at the same time. Rust makes no such promise: handlers can run on multiple threads concurrently, so the compiler **refuses** to let you mutate shared data without a synchronization primitive. `Arc<Mutex<Vec<Note>>>` is the answer: `Arc` for shared ownership, `Mutex` so only one handler mutates at a time. `.lock()` returns a `Result` (it errors only if a previous holder panicked while holding the lock — “poisoning”); `.unwrap()` is the pragmatic default for a guard you expect to always be healthy. > **Tip:** For a counter you do not need a full `Mutex`. `Arc<AtomicU64>` with `fetch_add(1, Ordering::Relaxed)` is lock-free and faster, exactly what `request_count` uses here. ### Read-only config needs no lock [Section titled “Read-only config needs no lock”](#read-only-config-needs-no-lock) `Config` is never mutated after startup, so `state.config.app_name` reads it directly with no lock. This is the common case: **most state is immutable config plus already-synchronized handles (a pool, a client), so very little of it actually needs a `Mutex`.** Reach for a lock only around data you genuinely mutate at request time. ### `std::sync::Mutex` vs `tokio::sync::Mutex` [Section titled “std::sync::Mutex vs tokio::sync::Mutex”](#stdsyncmutex-vs-tokiosyncmutex) The `Mutex` above is `std::sync::Mutex`. That is the right choice when you lock, do a quick in-memory operation, and unlock **without `.await`ing in between**, which is exactly what `create_note` does. If you need to hold a lock *across* an `.await` (for example, awaiting I/O while the guard is alive), use `tokio::sync::Mutex` (or `RwLock`) instead, because a blocking std guard held across an await can stall the async runtime. The Real-World Example below uses `tokio::sync::RwLock` for precisely that reason. See [Synchronization Primitives in Async Rust](/11-async/11-sync-primitives/). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concern | Express.js | Axum (0.8) | | -------------------- | -------------------------------------- | --------------------------------------------------------- | | Where deps live | closure/module variables, `app.locals` | one `State<T>` struct attached with `.with_state` | | Access in handler | refer to the variable in scope | declare a `State<T>` parameter | | Sharing model | implicit (single thread) | explicit `Arc` for shared ownership | | Mutating shared data | just mutate it | `Mutex`/`RwLock`/atomics — enforced by the compiler | | Missing a dependency | runtime `undefined` | **compile error** for `State`; runtime 500 for extensions | | Per-request data | `req.locals` / monkey-patch `req` | request **extensions** (`Extension<T>`) | | Cost of “sharing” | free (one runtime) | `Arc::clone` = one atomic refcount bump | The conceptual shift: **Express lets you share state implicitly because there is one thread; Rust forces you to name the sharing (`Arc`) and the mutation discipline (`Mutex`/atomics) because handlers may run in parallel.** What feels like ceremony is the compiler eliminating an entire class of data-race bugs at build time. ### State vs Extensions [Section titled “State vs Extensions”](#state-vs-extensions) Axum has two ways to make a value available to handlers, and choosing correctly avoids a lot of confusion: | | `State<T>` | `Extension<T>` | | ------------- | ---------------------------- | ----------------------------------------- | | Attached with | `Router::with_state(value)` | `.layer(Extension(value))` | | Keyed by | the router’s state type | the value’s Rust type | | Missing value | **compile-time** error | **runtime** 500 error | | Type-checked | yes, statically | no, looked up at runtime | | Best for | your app’s main state struct | values injected by middleware, or interop | **Prefer `State<T>` for your application state.** It is checked at compile time. Use `Extension<T>` when a value is produced by a middleware layer (for example, an authenticated user attached by an auth layer; see [Authentication](/16-web-apis/12-authentication/)), or when a library expects the extension mechanism. The cost of `Extension` is that forgetting to add the layer is only caught when a request hits the handler. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### 1. Forgetting `.with_state(...)` (a confusing compile error) [Section titled “1. Forgetting .with\_state(...) (a confusing compile error)”](#1-forgetting-with_state-a-confusing-compile-error) If a handler asks for `State<AppState>` but you never call `.with_state(...)`, the router’s state type stays the default `()`, and the types no longer line up. This is a **compile-time** error, which is good, but the message points at the `route` call, not the missing `with_state`: ```rust 1 use axum::{extract::State, routing::get, Router}; 2 3 #[derive(Clone)] 4 struct AppState { 5 name: String, 6 } 7 8 async fn handler(State(state): State<AppState>) -> String { 9 state.name 10 } 11 12 #[tokio::main] 13 async fn main() { 14 // does not compile (error[E0308]): forgot `.with_state(...)`, 15 // so the router's state type is `()`, not `AppState`. 16 let app: Router = Router::new().route("/", get(handler)); 17 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 18 axum::serve(listener, app).await.unwrap(); 19 } ``` The real error from `cargo check`: ```text 1 error[E0308]: mismatched types 2 --> examples/err_no_state.rs:16:48 3 | 4 16 | let app: Router = Router::new().route("/", get(handler)); 5 | ----- ^^^^^^^^^^^^ expected `MethodRouter`, found `MethodRouter<AppState>` 6 | | 7 | arguments to this method are incorrect 8 | 9 = note: expected struct `MethodRouter<()>` 10 found struct `MethodRouter<AppState>` ``` The fix is to add `.with_state(AppState { ... })`. The phrase “found `MethodRouter<AppState>`” is the tell: a handler in this router wants `AppState`, but the router has no state of that type yet. ### 2. Forgetting the `Extension` layer (a runtime 500) [Section titled “2. Forgetting the Extension layer (a runtime 500)”](#2-forgetting-the-extension-layer-a-runtime-500) With extensions there is no compile-time check. If a handler reads `Extension<Thing>` but no `.layer(Extension(thing))` was added, the request fails at runtime with a `500`: ```text 1 status = 500 Internal Server Error 2 body = Missing request extension: Extension of type `app::Thing` was not found. Perhaps you forgot to add it? See `axum::Extension`. ``` That message (captured by driving the router with `tower`’s `oneshot`) is the runtime cost of extensions. It is the strongest argument for using `State<T>` for your core dependencies and reserving `Extension` for middleware-injected values. ### 3. Holding a `std::sync::Mutex` guard across `.await` [Section titled “3. Holding a std::sync::Mutex guard across .await”](#3-holding-a-stdsyncmutex-guard-across-await) This compiles, but it is a real hazard, and Clippy flags it. A `std::sync::MutexGuard` held while the task is suspended at an `.await` can block the runtime and risks deadlocks: ```rust 1 use std::sync::{Arc, Mutex}; 2 3 struct Store { 4 items: Arc<Mutex<Vec<String>>>, 5 } 6 7 async fn do_async_thing() {} 8 9 async fn handler(store: Store) { 10 let mut items = store.items.lock().unwrap(); 11 // guard is still alive across this await — Clippy warns. 12 do_async_thing().await; 13 items.push("x".to_string()); 14 } 15 16 fn main() {} ``` `cargo clippy` produces this **real** warning: ```text 1 warning: this `MutexGuard` is held across an await point 2 --> examples/clippy_await_lock.rs:10:9 3 | 4 10 | let mut items = store.items.lock().unwrap(); 5 | ^^^^^^^^^ 6 | 7 = help: consider using an async-aware `Mutex` type or ensuring the `MutexGuard` is dropped before calling `await` 8 note: these are all the await points this lock is held through 9 --> examples/clippy_await_lock.rs:12:22 10 | 11 12 | do_async_thing().await; 12 | ^^^^^ 13 = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#await_holding_lock 14 = note: `#[warn(clippy::await_holding_lock)]` on by default ``` Fix it by either dropping the guard before the `.await` (do the locked work in a tight scope, then await), or switching to `tokio::sync::Mutex`/`RwLock` whose guards are designed to be held across awaits. ### 4. Trying to share `Rc` instead of `Arc` [Section titled “4. Trying to share Rc instead of Arc”](#4-trying-to-share-rc-instead-of-arc) `Rc<T>` is single-threaded reference counting; it is **not** `Send`, so it cannot cross threads. Putting an `Rc` in your state will fail to satisfy the `Handler` bounds (state must be `Send + Sync + Clone + 'static`). Use `Arc` for anything shared across handlers. See [Rc vs Arc](/10-smart-pointers/01-rc-arc/). ### 5. Wrapping the whole state in `Arc` *and* deriving `Clone` redundantly [Section titled “5. Wrapping the whole state in Arc and deriving Clone redundantly”](#5-wrapping-the-whole-state-in-arc-and-deriving-clone-redundantly) You have two valid styles and should pick one: * A `#[derive(Clone)] struct AppState { ... }` whose *fields* are `Arc`s (the main example), or * A plain `struct AppState { ... }` used as `State<Arc<AppState>>`, where the **outer** `Arc` is what gets cloned (no `Clone` derive on the struct needed). Doing both — `Arc<AppState>` where `AppState` also has `Arc` fields and a `Clone` derive — is harmless but pointless double-wrapping. Choose field-level `Arc` when different handlers want different *parts* of the state (so you can use `FromRef`, below); choose the outer `Arc<AppState>` when handlers always want the whole thing and the state has private fields you would rather not make individually `Clone`. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **One `AppState` struct, attached once.** Keep router construction in a `fn app(state: AppState) -> Router` so tests can build a router with a fake state and drive it via `tower::ServiceExt::oneshot` (no real port needed). * **`Arc` only what is shared; lock only what mutates.** Config and connection pools are `Arc` (or already internally shared). A `Mutex`/`RwLock` belongs only around data you actually mutate at request time. * **Pools are already `Arc` inside.** `sqlx::PgPool`, `reqwest::Client`, and most ecosystem clients are designed to be cloned cheaply (clone = bump a refcount). Put them directly in `AppState` and `#[derive(Clone)]`; do not wrap them in another `Arc` or a `Mutex`. * **Prefer `State<T>` over `Extension<T>`** for first-party dependencies, so wiring mistakes are compile errors. Reserve `Extension` for middleware-produced, per-request values. * **Use `tokio::sync::RwLock` for read-mostly state held across `.await`,** `std::sync::Mutex` for quick non-async critical sections, and atomics for counters/flags. * **Split big state with `#[derive(FromRef)]`** so a handler can extract just the substate it needs (`State<Config>`, `State<PgPool>`) instead of the whole struct. It documents each handler’s true dependencies. * **Globals (`OnceLock`/`LazyLock`) are a last resort.** For truly process-wide, set-once values you can use a `static` with `OnceLock`, but explicit `State` is more testable and clearer about dependencies. ### Splitting state with `FromRef` [Section titled “Splitting state with FromRef”](#splitting-state-with-fromref) When state grows, forcing every handler to extract the entire blob is noisy. The `FromRef` derive lets handlers ask for a *substate*: ```rust 1 use axum::{ 2 extract::{FromRef, State}, 3 routing::get, 4 Json, Router, 5 }; 6 use std::sync::Arc; 7 8 #[derive(Clone)] 9 struct Config { 10 app_name: String, 11 } 12 13 struct Pool { 14 url: String, 15 } 16 17 // `#[derive(FromRef)]` generates the conversions that let a handler ask for 18 // just `State<Config>` or `State<Arc<Pool>>` instead of the whole `AppState`. 19 #[derive(Clone, FromRef)] 20 struct AppState { 21 config: Config, 22 pool: Arc<Pool>, 23 } 24 25 // This handler only needs the config — so it asks for exactly that substate. 26 async fn info(State(config): State<Config>) -> Json<serde_json::Value> { 27 Json(serde_json::json!({ "app": config.app_name })) 28 } 29 30 // This one only needs the pool. 31 async fn db_status(State(pool): State<Arc<Pool>>) -> String { 32 format!("connected to {}", pool.url) 33 } 34 35 fn app(state: AppState) -> Router { 36 Router::new() 37 .route("/info", get(info)) 38 .route("/db", get(db_status)) 39 .with_state(state) 40 } 41 42 #[tokio::main] 43 async fn main() { 44 let state = AppState { 45 config: Config { app_name: "notes-api".to_string() }, 46 pool: Arc::new(Pool { url: "postgres://localhost/notes".to_string() }), 47 }; 48 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 49 axum::serve(listener, app(state)).await.unwrap(); 50 } ``` `FromRef` requires the `macros` feature: `cargo add axum --features macros`. Each field becomes individually extractable as long as it is `Clone` (note `Arc<Pool>`, so the non-`Clone` `Pool` is still shareable). ### The global alternative (`OnceLock`) [Section titled “The global alternative (OnceLock)”](#the-global-alternative-oncelock) For a value that is set once and read everywhere — and that you do not need to fake in tests — a `static` initialized lazily works without any `State` plumbing: ```rust 1 use std::sync::OnceLock; 2 3 #[derive(Debug)] 4 struct Config { 5 name: String, 6 } 7 8 static CONFIG: OnceLock<Config> = OnceLock::new(); 9 10 fn config() -> &'static Config { 11 CONFIG.get_or_init(|| Config { name: "notes-api".to_string() }) 12 } 13 14 fn main() { 15 println!("{}", config().name); 16 println!("{}", config().name); // same instance; initialized exactly once 17 } ``` Running this prints `notes-api` twice; the closure runs only on the first call. This is occasionally handy for constants, but for anything a handler genuinely *depends on* (and that you want to swap in tests), prefer `State`. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A users API with three real concerns: configuration loaded from the environment, a repository standing in for a database, and a read-mostly cache behind a `tokio::sync::RwLock` (so concurrent reads do not block each other, and the guard can safely be held across `.await`). The state struct bundles all three and is cheap to clone. ```rust 1 use axum::{ 2 extract::{Path, State}, 3 http::StatusCode, 4 routing::get, 5 Json, Router, 6 }; 7 use serde::Serialize; 8 use std::{collections::HashMap, sync::Arc, time::Duration}; 9 use tokio::sync::RwLock; 10 11 // Configuration, loaded once from the environment at startup. 12 #[derive(Clone)] 13 struct Config { 14 cache_ttl: Duration, 15 service_name: String, 16 } 17 18 impl Config { 19 fn from_env() -> Self { 20 let ttl_secs = std::env::var("CACHE_TTL_SECS") 21 .ok() 22 .and_then(|s| s.parse().ok()) 23 .unwrap_or(60); 24 Config { 25 cache_ttl: Duration::from_secs(ttl_secs), 26 service_name: std::env::var("SERVICE_NAME") 27 .unwrap_or_else(|_| "users-api".to_string()), 28 } 29 } 30 } 31 32 #[derive(Clone, Serialize)] 33 struct User { 34 id: u64, 35 name: String, 36 } 37 38 // A fake repository standing in for a real DB pool. Internally Arc-shared, 39 // so cloning the repo is just a refcount bump — like cloning a `sqlx::PgPool`. 40 #[derive(Clone)] 41 struct UserRepo { 42 users: Arc<Vec<User>>, 43 } 44 45 impl UserRepo { 46 fn seed() -> Self { 47 UserRepo { 48 users: Arc::new(vec![ 49 User { id: 1, name: "Ada".to_string() }, 50 User { id: 2, name: "Linus".to_string() }, 51 ]), 52 } 53 } 54 55 fn find(&self, id: u64) -> Option<User> { 56 self.users.iter().find(|u| u.id == id).cloned() 57 } 58 } 59 60 // A read-mostly cache guarded by an async RwLock so reads don't block reads. 61 type Cache = Arc<RwLock<HashMap<u64, User>>>; 62 63 #[derive(Clone)] 64 struct AppState { 65 config: Config, 66 repo: UserRepo, 67 cache: Cache, 68 } 69 70 // GET /healthz — surfaces config without any locking. 71 async fn health(State(state): State<AppState>) -> Json<serde_json::Value> { 72 Json(serde_json::json!({ 73 "service": state.config.service_name, 74 "cache_ttl_secs": state.config.cache_ttl.as_secs(), 75 })) 76 } 77 78 // GET /users/{id} — cache read (shared lock), fall back to the repo on a miss. 79 async fn get_user( 80 State(state): State<AppState>, 81 Path(id): Path<u64>, 82 ) -> Result<Json<User>, StatusCode> { 83 // Fast path: a shared read lock lets many requests read at once. 84 if let Some(user) = state.cache.read().await.get(&id).cloned() { 85 return Ok(Json(user)); 86 } 87 // Miss: look it up, then take a write lock to populate the cache. 88 let user = state.repo.find(id).ok_or(StatusCode::NOT_FOUND)?; 89 state.cache.write().await.insert(id, user.clone()); 90 Ok(Json(user)) 91 } 92 93 fn app(state: AppState) -> Router { 94 Router::new() 95 .route("/healthz", get(health)) 96 .route("/users/{id}", get(get_user)) 97 .with_state(state) 98 } 99 100 #[tokio::main] 101 async fn main() { 102 let state = AppState { 103 config: Config::from_env(), 104 repo: UserRepo::seed(), 105 cache: Arc::new(RwLock::new(HashMap::new())), 106 }; 107 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 108 println!("listening on {}", listener.local_addr().unwrap()); 109 axum::serve(listener, app(state)).await.unwrap(); 110 } ``` Running it and exercising the cache produces this **real** output: ```text 1 $ curl -s http://127.0.0.1:3000/healthz 2 {"cache_ttl_secs":60,"service":"users-api"} 3 4 $ curl -s http://127.0.0.1:3000/users/1 # cache miss → repo lookup 5 {"id":1,"name":"Ada"} 6 7 $ curl -s http://127.0.0.1:3000/users/1 # cache hit 8 {"id":1,"name":"Ada"} 9 10 $ curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3000/users/99 11 404 ``` Production-relevant notes on this design: * **Config comes from `Config::from_env()`, not globals.** It is a plain field of `AppState`, so a test can build the state with any config it likes. Real services parse this with a crate such as `figment` or `config`, or just `std::env::var` as here. See [Deployment](/16-web-apis/19-deployment/) for env-based configuration. * **`UserRepo` models a pool: `Arc` inside, `Clone` cheap.** Swap `Arc<Vec<User>>` for a `sqlx::PgPool` and the shape is identical: clone the pool freely; the connections are pooled internally. See [Database Integration](/17-database/). * **`tokio::sync::RwLock` is deliberate.** The cache is read on every request and written rarely, and the guard is alive across `.await` points (`.read().await`, `.write().await`). An async `RwLock` is correct here; a `std::sync::Mutex` held across those awaits would draw the Clippy warning from Pitfall 3 and risk stalling the runtime. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [Axum `State` extractor (docs.rs)](https://docs.rs/axum/latest/axum/extract/struct.State.html). The canonical reference and examples. * [`FromRef` trait and derive (docs.rs)](https://docs.rs/axum/latest/axum/extract/trait.FromRef.html) — substate extraction. * [`axum::Extension` (docs.rs)](https://docs.rs/axum/latest/axum/struct.Extension.html). The runtime-keyed alternative to `State`. * [Tokio `RwLock` (docs.rs)](https://docs.rs/tokio/latest/tokio/sync/struct.RwLock.html) and [`Mutex`](https://docs.rs/tokio/latest/tokio/sync/struct.Mutex.html). * Within this guide: * [Axum Fundamentals](/16-web-apis/01-axum-basics/) — the `Router`/handler/`axum::serve` loop this builds on. * [Extractors](/16-web-apis/04-extractors/): how `State` fits the extractor system; ordering rules. * [Middleware](/16-web-apis/05-middleware/) — Tower layers, including where `Extension` values come from. * [Authentication](/16-web-apis/12-authentication/): a real use of middleware-injected `Extension<AuthUser>`. * [Error Handling in Web Apps](/16-web-apis/10-error-handling-web/) — turning state/lookup errors into clean responses. * [Database Integration](/17-database/) — putting a `sqlx`/`diesel` pool in your state. * Background: [Rc vs Arc](/10-smart-pointers/01-rc-arc/), [The Arc + Mutex Pattern](/11-async/12-arc-mutex-pattern/), [Synchronization Primitives](/11-async/11-sync-primitives/), [Structs](/06-data-structures/00-structs/). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Split state with `FromRef` [Section titled “Exercise 1: Split state with FromRef”](#exercise-1-split-state-with-fromref) **Difficulty:** Beginner **Objective:** Practice the substate pattern so handlers depend only on what they use. **Instructions:** Build an `AppState` with three fields — a `Config { app_name: String }`, a `Features { dark_mode: bool }`, and a pretend pool (`Arc<String>`). Derive `Clone` and `FromRef` (remember `cargo add axum --features macros`). Write `GET /name` that extracts only `State<Config>` and returns the app name, and `GET /flags` that extracts only `State<Features>` and returns the flags as JSON. Wire both into a router with a single `.with_state(...)`. Solution ```rust 1 use axum::{ 2 extract::{FromRef, State}, 3 routing::get, 4 Json, Router, 5 }; 6 use std::sync::Arc; 7 8 #[derive(Clone)] 9 struct Config { 10 app_name: String, 11 } 12 13 #[derive(Clone)] 14 struct Features { 15 dark_mode: bool, 16 } 17 18 #[derive(Clone, FromRef)] 19 struct AppState { 20 config: Config, 21 features: Features, 22 pool: Arc<String>, // pretend DB pool 23 } 24 25 async fn name(State(config): State<Config>) -> String { 26 config.app_name 27 } 28 29 async fn flags(State(features): State<Features>) -> Json<serde_json::Value> { 30 Json(serde_json::json!({ "dark_mode": features.dark_mode })) 31 } 32 33 fn app(state: AppState) -> Router { 34 Router::new() 35 .route("/name", get(name)) 36 .route("/flags", get(flags)) 37 .with_state(state) 38 } 39 40 #[tokio::main] 41 async fn main() { 42 let state = AppState { 43 config: Config { app_name: "shop".to_string() }, 44 features: Features { dark_mode: true }, 45 pool: Arc::new("postgres://...".to_string()), 46 }; 47 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 48 axum::serve(listener, app(state)).await.unwrap(); 49 } ``` `GET /name` returns `shop`; `GET /flags` returns `{"dark_mode":true}`. Each handler extracts only its slice of the state. ### Exercise 2: Hot-reloadable settings behind `RwLock` [Section titled “Exercise 2: Hot-reloadable settings behind RwLock”](#exercise-2-hot-reloadable-settings-behind-rwlock) **Difficulty:** Intermediate **Objective:** Mutate shared state safely across concurrent requests using an async `RwLock`. **Instructions:** Hold a `Settings { rate_limit: u32 }` (deriving `Serialize`/`Deserialize` and `Clone`) inside `Arc<RwLock<Settings>>` in `AppState`. Add `GET /settings` (read lock → return current settings as JSON) and `PUT /settings` (write lock → replace settings with the JSON body and return the new value). Use `tokio::sync::RwLock`. Solution ```rust 1 use axum::{ 2 extract::State, 3 routing::{get, put}, 4 Json, Router, 5 }; 6 use serde::{Deserialize, Serialize}; 7 use std::sync::Arc; 8 use tokio::sync::RwLock; 9 10 #[derive(Clone, Serialize, Deserialize)] 11 struct Settings { 12 rate_limit: u32, 13 } 14 15 #[derive(Clone)] 16 struct AppState { 17 settings: Arc<RwLock<Settings>>, 18 } 19 20 async fn get_settings(State(state): State<AppState>) -> Json<Settings> { 21 Json(state.settings.read().await.clone()) 22 } 23 24 async fn put_settings( 25 State(state): State<AppState>, 26 Json(new): Json<Settings>, 27 ) -> Json<Settings> { 28 let mut guard = state.settings.write().await; 29 *guard = new; 30 Json(guard.clone()) 31 } 32 33 fn app(state: AppState) -> Router { 34 Router::new() 35 .route("/settings", get(get_settings)) 36 .route("/settings", put(put_settings)) 37 .with_state(state) 38 } 39 40 #[tokio::main] 41 async fn main() { 42 let state = AppState { 43 settings: Arc::new(RwLock::new(Settings { rate_limit: 100 })), 44 }; 45 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 46 axum::serve(listener, app(state)).await.unwrap(); 47 } ``` Verified behavior: `GET /settings` returns `{"rate_limit":100}`; after `PUT /settings` with `{"rate_limit":500}`, a subsequent `GET /settings` returns `{"rate_limit":500}`. The two `.route("/settings", ...)` calls can also be merged into `.route("/settings", get(get_settings).put(put_settings))`. ### Exercise 3: Inject a client and a counter via `Arc<AppState>` [Section titled “Exercise 3: Inject a client and a counter via Arc\<AppState>”](#exercise-3-inject-a-client-and-a-counter-via-arcappstate) **Difficulty:** Advanced **Objective:** Use the outer-`Arc` style for state with private, non-`Clone`-derived fields, combining an injected client with a lock-free atomic counter. **Instructions:** Define a non-`Clone`-deriving `AppState` holding an `ApiClient { base_url: String }` (with an `async fn ping(&self) -> String`) and an `AtomicU64` named `calls`. Use it as `State<Arc<AppState>>`. Write `GET /proxy` that increments the counter with `fetch_add`, calls `client.ping().await`, and returns a string combining the ping result and the call number. Solution ```rust 1 use axum::{extract::State, routing::get, Router}; 2 use std::sync::{ 3 atomic::{AtomicU64, Ordering}, 4 Arc, 5 }; 6 7 // In a real app this is `reqwest::Client` (itself cheaply cloneable). 8 #[derive(Clone)] 9 struct ApiClient { 10 base_url: String, 11 } 12 13 impl ApiClient { 14 async fn ping(&self) -> String { 15 format!("pinged {}", self.base_url) 16 } 17 } 18 19 // No `#[derive(Clone)]` — the outer `Arc` is what gets cloned per request. 20 struct AppState { 21 client: ApiClient, 22 calls: AtomicU64, 23 } 24 25 async fn proxy(State(state): State<Arc<AppState>>) -> String { 26 let n = state.calls.fetch_add(1, Ordering::Relaxed) + 1; 27 let result = state.client.ping().await; 28 format!("{result} (call #{n})") 29 } 30 31 fn app(state: Arc<AppState>) -> Router { 32 Router::new().route("/proxy", get(proxy)).with_state(state) 33 } 34 35 #[tokio::main] 36 async fn main() { 37 let state = Arc::new(AppState { 38 client: ApiClient { base_url: "https://api.example.com".to_string() }, 39 calls: AtomicU64::new(0), 40 }); 41 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 42 axum::serve(listener, app(state)).await.unwrap(); 43 } ``` Each `GET /proxy` returns `pinged https://api.example.com (call #N)` with `N` incrementing. The `AtomicU64` needs no `Mutex` (`fetch_add` is lock-free), and because the whole state lives behind one `Arc`, `AppState` itself does not need to be `Clone`. # Request and Response Handling > Express mutates a res object; an Axum handler returns a value whose type implements IntoResponse. Master status codes, headers, and the (StatusCode, Json) tuple. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In Express you build a response by mutating a `res` object: `res.status(201).set('X-Foo', 'bar').json(data)`. In Axum a handler **returns a value**, and any value whose type implements the `IntoResponse` trait becomes the HTTP response. This page is about the output side of a handler: how `IntoResponse` works, how to set status codes and headers, and the `(StatusCode, Json)` tuple idiom that does most of the day-to-day work. Getting this model right is what lets you stop reaching for a `res` object that does not exist. The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically. This page targets **axum 0.8** (0.8.9), started with `axum::serve` and a `tokio::net::TcpListener`. > **Note:** Inputs (extractors like `Path`, `Query`, `Json` as a *request* body) are covered in [Extractors](/16-web-apis/04-extractors/). This page is the mirror image: it covers `Json`, `StatusCode`, tuples, and `HeaderMap` as *responses*. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) A realistic Express handler set: a JSON read, a `201 Created` with a `Location` header, a `404` with a JSON error body, a redirect, and a CSV download. Notice how every response is built by *calling methods on `res`*. ```typescript 1 // reports.ts — Express 4/5 2 import express, { Request, Response } from "express"; 3 4 const app = express(); 5 app.use(express.json()); 6 7 interface Report { 8 id: number; 9 title: string; 10 body: string; 11 } 12 13 const reports = new Map<number, Report>(); 14 let nextId = 0; 15 16 // 200 with a JSON body 17 app.get("/reports/:id", (req: Request, res: Response) => { 18 const report = reports.get(Number(req.params.id)); 19 if (!report) { 20 // 404 with a structured JSON error 21 return res.status(404).json({ error: "report not found", code: "not_found" }); 22 } 23 res.json(report); // 200, Content-Type: application/json 24 }); 25 26 // 201 with a Location header 27 app.post("/reports", (req: Request, res: Response) => { 28 const { title, body } = req.body as { title: string; body: string }; 29 const report: Report = { id: ++nextId, title, body }; 30 reports.set(report.id, report); 31 res 32 .status(201) 33 .set("Location", `/reports/${report.id}`) 34 .json(report); 35 }); 36 37 // A 303 redirect 38 app.get("/go", (_req: Request, res: Response) => { 39 res.redirect("/reports/1"); 40 }); 41 42 // A non-JSON response: a CSV download 43 app.get("/reports.csv", (_req: Request, res: Response) => { 44 const rows = ["id,title", ...[...reports.values()].map((r) => `${r.id},${r.title}`)]; 45 res 46 .status(200) 47 .set("Content-Type", "text/csv; charset=utf-8") 48 .set("Content-Disposition", 'attachment; filename="reports.csv"') 49 .send(rows.join("\n") + "\n"); 50 }); 51 52 app.listen(3000); ``` Everything funnels through `res`: `res.status(n)` sets the code, `res.set(k, v)` adds a header, `res.json(x)` / `res.send(x)` writes the body and ends the response. The body type is whatever you pass; Express does not check it. If you forget to call a `res` method, the request hangs. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same five responses in Axum. There is no `res` object; each handler **returns** the response it wants. ```rust 1 use axum::{ 2 extract::{Path, State}, 3 http::{header, HeaderValue, StatusCode}, 4 response::{IntoResponse, Redirect, Response}, 5 routing::{get, post}, 6 Json, Router, 7 }; 8 use serde::{Deserialize, Serialize}; 9 use std::sync::{Arc, Mutex}; 10 11 #[derive(Clone, Serialize)] 12 struct Report { 13 id: u64, 14 title: String, 15 body: String, 16 } 17 18 #[derive(Deserialize)] 19 struct NewReport { 20 title: String, 21 body: String, 22 } 23 24 #[derive(Serialize)] 25 struct ApiError { 26 error: &'static str, 27 code: &'static str, 28 } 29 30 #[derive(Clone, Default)] 31 struct AppState { 32 reports: Arc<Mutex<Vec<Report>>>, 33 next_id: Arc<Mutex<u64>>, 34 } 35 36 // 200 with JSON, or 404 with a JSON error. The two arms have DIFFERENT response 37 // shapes, so we return `Response` and call `.into_response()` on each. 38 async fn get_report(State(s): State<AppState>, Path(id): Path<u64>) -> Response { 39 let reports = s.reports.lock().unwrap(); 40 match reports.iter().find(|r| r.id == id) { 41 Some(r) => Json(r.clone()).into_response(), 42 None => ( 43 StatusCode::NOT_FOUND, 44 Json(ApiError { error: "report not found", code: "not_found" }), 45 ) 46 .into_response(), 47 } 48 } 49 50 // 201 Created + a Location header + the created body. 51 async fn create_report( 52 State(s): State<AppState>, 53 Json(body): Json<NewReport>, 54 ) -> impl IntoResponse { 55 let mut id = s.next_id.lock().unwrap(); 56 *id += 1; 57 let report = Report { id: *id, title: body.title, body: body.body }; 58 s.reports.lock().unwrap().push(report.clone()); 59 60 let location = HeaderValue::from_str(&format!("/reports/{}", report.id)) 61 .expect("a numeric id is always a valid header value"); 62 63 (StatusCode::CREATED, [(header::LOCATION, location)], Json(report)) 64 } 65 66 // A 303 redirect — `Redirect` implements IntoResponse. 67 async fn go() -> Redirect { 68 Redirect::to("/reports/1") 69 } 70 71 // A non-JSON body: a CSV download with two headers. 72 async fn export_csv(State(s): State<AppState>) -> impl IntoResponse { 73 let reports = s.reports.lock().unwrap(); 74 let mut csv = String::from("id,title\n"); 75 for r in reports.iter() { 76 csv.push_str(&format!("{},{}\n", r.id, r.title)); 77 } 78 ( 79 StatusCode::OK, 80 [ 81 (header::CONTENT_TYPE, "text/csv; charset=utf-8"), 82 (header::CONTENT_DISPOSITION, "attachment; filename=\"reports.csv\""), 83 ], 84 csv, 85 ) 86 } 87 88 fn app() -> Router { 89 Router::new() 90 .route("/reports", post(create_report)) 91 .route("/reports/{id}", get(get_report)) 92 .route("/reports.csv", get(export_csv)) 93 .route("/go", get(go)) 94 .with_state(AppState::default()) 95 } 96 97 #[tokio::main] 98 async fn main() { 99 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 100 println!("listening on {}", listener.local_addr().unwrap()); 101 axum::serve(listener, app()).await.unwrap(); 102 } ``` The dependencies (in a fresh `cargo new` project, `cargo add` resolves the current versions): ```bash 1 cargo add axum 2 cargo add tokio --features full 3 cargo add serde --features derive 4 cargo add serde_json ``` ```toml 1 [dependencies] 2 axum = "0.8.9" 3 serde = { version = "1.0.228", features = ["derive"] } 4 serde_json = "1.0.150" 5 tokio = { version = "1.52.3", features = ["full"] } ``` Exercising it with `curl -i` produces these **real** responses (captured against the compiled server): ```text 1 $ curl -s -i -X POST http://127.0.0.1:3000/reports \ 2 -H 'content-type: application/json' -d '{"title":"Q1","body":"numbers"}' 3 HTTP/1.1 201 Created 4 content-type: application/json 5 location: /reports/1 6 content-length: 38 7 date: Mon, 01 Jun 2026 11:55:26 GMT 8 9 {"id":1,"title":"Q1","body":"numbers"} 10 11 $ curl -s -i http://127.0.0.1:3000/reports/1 12 HTTP/1.1 200 OK 13 content-type: application/json 14 content-length: 38 15 16 {"id":1,"title":"Q1","body":"numbers"} 17 18 $ curl -s -i http://127.0.0.1:3000/reports/999 19 HTTP/1.1 404 Not Found 20 content-type: application/json 21 content-length: 47 22 23 {"error":"report not found","code":"not_found"} 24 25 $ curl -s -i http://127.0.0.1:3000/reports.csv 26 HTTP/1.1 200 OK 27 content-type: text/csv; charset=utf-8 28 content-disposition: attachment; filename="reports.csv" 29 content-length: 14 30 31 id,title 32 1,Q1 ``` *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `IntoResponse`: the one trait that defines “what a handler may return” [Section titled “IntoResponse: the one trait that defines “what a handler may return””](#intoresponse-the-one-trait-that-defines-what-a-handler-may-return) A handler’s return type must implement `IntoResponse`. That is the entire contract on the output side. The same way `Handler` requires the *parameters* to be extractors, it requires the *return type* to be `IntoResponse`. The trait has a single method: ```rust 1 use axum::response::Response; 2 3 // (signature, from the axum source — for understanding only) 4 trait IntoResponse { 5 fn into_response(self) -> Response; 6 } ``` `Response` is `axum::response::Response`, an alias for `http::Response<Body>`. You rarely build one by hand; instead you return something Axum already knows how to convert, and the framework calls `.into_response()` for you. Axum ships `IntoResponse` impls for a large catalogue of types: | You return | Becomes | | --------------------------------------------- | --------------------------------------------------- | | `&'static str`, `String` | `200 OK`, `content-type: text/plain; charset=utf-8` | | `Json<T>` (where `T: Serialize`) | `200 OK`, `content-type: application/json` | | `StatusCode` | that status, **empty body** | | `()` (the unit type) | `200 OK`, empty body | | `(StatusCode, T)` | `T`’s response, but with that status | | `(StatusCode, headers, T)` | that status, those headers, plus `T`’s body | | `Redirect` | a `3xx` with a `Location` header | | `Result<T, E>` (`T`, `E` both `IntoResponse`) | the `Ok` response or the `Err` response | | `Response` | itself (the identity impl) | This is the deep contrast with Express: there, the *body content* is dynamic and the *status/headers* are mutations on a fixed `res` object. In Axum the **type you return encodes the response shape**, and the compiler checks it. A handler `-> Json<Report>` cannot accidentally send plain text. ### `-> impl IntoResponse` vs a concrete type [Section titled “-> impl IntoResponse vs a concrete type”](#--impl-intoresponse-vs-a-concrete-type) ```rust 1 async fn create_report(/* ... */) -> impl IntoResponse { /* ... */ } 2 async fn get_report(/* ... */) -> Response { /* ... */ } ``` `-> impl IntoResponse` means “I return *some* type that implements `IntoResponse`; don’t make me name it.” It is convenient when the type is an ugly tuple like `(StatusCode, [(HeaderName, HeaderValue); 1], Json<Report>)`. But `impl Trait` still demands **one single concrete type** across the whole function body. If different branches return different concrete types, it will not compile (see Common Pitfalls). When that happens, return `Response` and call `.into_response()` on each branch: that erases the differences into one type. > **Tip:** Rule of thumb: a handler that always returns the *same* shape can use `-> Json<T>` or `-> impl IntoResponse`. A handler that returns *different* shapes per branch should use `-> Response` (or a `Result`, or a custom enum, see [Error Handling in Web Apps](/16-web-apis/10-error-handling-web/)). ### Status codes [Section titled “Status codes”](#status-codes) `StatusCode` comes from the `http` crate, re-exported as `axum::http::StatusCode`. It has named associated constants: `StatusCode::OK` (200), `StatusCode::CREATED` (201), `StatusCode::NO_CONTENT` (204), `StatusCode::NOT_FOUND` (404), `StatusCode::UNPROCESSABLE_ENTITY` (422), and so on. Returned alone it produces an **empty-bodied** response with that status: ```rust 1 use axum::http::StatusCode; 2 3 // 204 No Content — empty body, like Express's res.sendStatus(204). 4 async fn delete_thing() -> StatusCode { 5 StatusCode::NO_CONTENT 6 } ``` ```text 1 $ curl -s -i http://127.0.0.1:3000/no-content 2 HTTP/1.1 204 No Content 3 date: Mon, 01 Jun 2026 11:53:19 GMT ``` To attach a body, pair the status with something in a tuple. ### The `(StatusCode, Json)` tuple — the workhorse [Section titled “The (StatusCode, Json) tuple — the workhorse”](#the-statuscode-json-tuple--the-workhorse) This is the idiom you will type most. A 2-tuple `(StatusCode, T)` produces `T`’s response with the status replaced: ```rust 1 use axum::{http::StatusCode, Json}; 2 use serde::Serialize; 3 4 #[derive(Serialize)] 5 struct Article { 6 id: u64, 7 title: String, 8 } 9 10 async fn created() -> (StatusCode, Json<Article>) { 11 (StatusCode::CREATED, Json(Article { id: 7, title: "New".to_string() })) 12 } ``` ```text 1 $ curl -s -i http://127.0.0.1:3000/created 2 HTTP/1.1 201 Created 3 content-type: application/json 4 content-length: 22 5 6 {"id":7,"title":"New"} ``` `Json` already supplied `content-type: application/json` and the serialized body; the tuple only overrode the status from `200` to `201`. **Order matters**: the status code must come *first*. The body-producing part (`Json`, `String`, etc.) must be *last*. We will see what happens when you flip them in Common Pitfalls. ### Setting headers [Section titled “Setting headers”](#setting-headers) A 3-tuple `(StatusCode, headers, body)` lets you add response headers. The “headers” slot can be an **array of `(HeaderName, value)` pairs**, where the value is anything convertible into a `HeaderValue` (a `&'static str`, a `String`, or a `HeaderValue`): ```rust 1 use axum::{http::{header, HeaderValue, StatusCode}, Json}; 2 use serde::Serialize; 3 4 #[derive(Serialize)] 5 struct Article { id: u64, title: String } 6 7 async fn with_header() -> impl IntoResponse { 8 ( 9 StatusCode::OK, 10 [(header::CACHE_CONTROL, HeaderValue::from_static("max-age=60"))], 11 Json(Article { id: 2, title: "Cached".to_string() }), 12 ) 13 } ``` ```text 1 $ curl -s -i http://127.0.0.1:3000/with-header 2 HTTP/1.1 200 OK 3 content-type: application/json 4 cache-control: max-age=60 5 content-length: 25 6 7 {"id":2,"title":"Cached"} ``` The `header` module (`axum::http::header`) holds constants for standard header names: `header::CACHE_CONTROL`, `header::LOCATION`, `header::CONTENT_TYPE`, `header::ETAG`, etc. For a custom header, use `HeaderName::from_static("x-trace")`. For dynamic header *values*, use `HeaderValue::from_str(&s)`, which returns a `Result` because not every string is a legal header value (control characters, for instance, are rejected: a built-in defense against header injection). When you need many headers, or to *append* multiple values for the same name, use `AppendHeaders`: ```rust 1 use axum::{http::{header, HeaderName}, response::{AppendHeaders, IntoResponse}}; 2 3 async fn multi_header() -> impl IntoResponse { 4 ( 5 AppendHeaders([ 6 (header::CACHE_CONTROL, "no-store"), 7 (HeaderName::from_static("x-trace"), "abc"), 8 ]), 9 "with two headers", 10 ) 11 } ``` ```text 1 $ curl -s -i http://127.0.0.1:3000/multi-header 2 HTTP/1.1 200 OK 3 content-type: text/plain; charset=utf-8 4 cache-control: no-store 5 x-trace: abc 6 content-length: 16 7 8 with two headers ``` You can also return a `HeaderMap` directly as part of a tuple when you build the set imperatively: ```rust 1 use axum::http::{HeaderMap, HeaderValue}; 2 3 async fn header_map() -> (HeaderMap, &'static str) { 4 let mut headers = HeaderMap::new(); 5 headers.insert("x-custom", HeaderValue::from_static("hi")); 6 (headers, "body") 7 } ``` ### `Redirect` [Section titled “Redirect”](#redirect) `axum::response::Redirect` builds a redirect response with the `Location` header set. `Redirect::to(uri)` is a `303 See Other`; there are also `Redirect::permanent` (`308`) and `Redirect::temporary` (`307`): ```rust 1 use axum::response::Redirect; 2 3 async fn go() -> Redirect { 4 Redirect::to("/reports/1") 5 } ``` ```text 1 $ curl -s -i http://127.0.0.1:3000/go 2 HTTP/1.1 303 See Other 3 location: /reports/1 4 content-length: 0 ``` ### Building a `Response` by hand [Section titled “Building a Response by hand”](#building-a-response-by-hand) For full control you can construct a `Response` with the builder from the `http` crate. This is the closest analogue to mutating `res`, and you rarely need it, but it is there: ```rust 1 use axum::{http::{header, StatusCode}, response::{IntoResponse, Response}}; 2 3 async fn manual() -> Response { 4 Response::builder() 5 .status(StatusCode::IM_A_TEAPOT) 6 .header(header::CONTENT_TYPE, "text/plain") 7 .body("I'm a teapot".to_string()) 8 .unwrap() 9 .into_response() 10 } ``` ```text 1 $ curl -s -i http://127.0.0.1:3000/manual 2 HTTP/1.1 418 I'm a teapot 3 content-type: text/plain 4 content-length: 12 5 6 I'm a teapot ``` ### Writing your own `IntoResponse` [Section titled “Writing your own IntoResponse”](#writing-your-own-intoresponse) Because `IntoResponse` is just a trait, you can implement it for your own types. This is how you give a domain type — a CSV export, an error enum, a custom envelope — a single, reusable response shape: ```rust 1 use axum::{http::{header, StatusCode}, response::{IntoResponse, Response}}; 2 3 struct Csv(String); 4 5 impl IntoResponse for Csv { 6 fn into_response(self) -> Response { 7 ( 8 StatusCode::OK, 9 [(header::CONTENT_TYPE, "text/csv; charset=utf-8")], 10 self.0, 11 ) 12 .into_response() 13 } 14 } 15 16 async fn export() -> Csv { 17 Csv("id,title\n1,Hello\n".to_string()) 18 } ``` ```text 1 $ curl -s -i http://127.0.0.1:3000/export 2 HTTP/1.1 200 OK 3 content-type: text/csv; charset=utf-8 4 content-length: 17 5 6 id,title 7 1,Hello ``` Implementing `IntoResponse` for an error type is the foundation of centralized error handling; see [Error Handling in Web Apps](/16-web-apis/10-error-handling-web/). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concern | Express.js | Axum (0.8) | | -------------------------- | ------------------------------------ | -------------------------------------------------------------------- | | How a response is produced | mutate `res` (`res.status().json()`) | **return** a value implementing `IntoResponse` | | Status code | `res.status(201)` | first element of a tuple, or a bare `StatusCode` | | JSON body | `res.json(obj)` | return `Json(value)` (any `T: Serialize`) | | Headers | `res.set(k, v)` | `(status, [(name, value)], body)` tuple, or `HeaderMap` | | Redirect | `res.redirect(url)` | return `Redirect::to(url)` | | Empty body with status | `res.sendStatus(204)` | return `StatusCode::NO_CONTENT` | | Error response | `res.status(404).json(...)` | return `Err(e)` where `e: IntoResponse`, or `(StatusCode, Json(..))` | | Body type checking | none — `res.send(anything)` | type-checked; body must be a known `IntoResponse` | | Forgetting to respond | request hangs | impossible — the function must return a value | The single most important shift: **a handler is a function from request to response, not a procedure that pokes at a mutable response object.** Because the return type is checked, you cannot ship a handler that forgets to send a body, sends two conflicting bodies, or — short of `unwrap` panics — leaves a request hanging. The “shape” of every response is visible in the function signature. > **Note:** `Json` does double duty. As a *parameter* (`Json<T>` where `T: Deserialize`) it is a request-body extractor; as a *return value* (`Json<T>` where `T: Serialize`) it is a response. Same wrapper, opposite direction. The extractor side lives in [Extractors](/16-web-apis/04-extractors/). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### 1. Putting the body before the status in a tuple [Section titled “1. Putting the body before the status in a tuple”](#1-putting-the-body-before-the-status-in-a-tuple) The status code must be the **first** element of a response tuple and the body-producing type must be **last**. Flip them and it does not compile: ```rust 1 use axum::{http::StatusCode, routing::get, Json, Router}; 2 use serde::Serialize; 3 4 #[derive(Serialize)] 5 struct Article { id: u64 } 6 7 // does not compile: Json must be the LAST element, not the first 8 #[axum::debug_handler] 9 async fn bad() -> (Json<Article>, StatusCode) { 10 (Json(Article { id: 1 }), StatusCode::CREATED) 11 } 12 13 fn build() -> Router { 14 Router::new().route("/bad", get(bad)) 15 } ``` Without `#[axum::debug_handler]` you get the usual opaque `the trait bound ... Handler<_, _> is not implemented`. With it (enable the `macros` feature: `cargo add axum --features macros`), the real message is precise: ```text 1 error: `Json<_>` must be the last element in a response tuple 2 --> src/main.rs:11:20 3 | 4 11 | async fn bad() -> (Json<Article>, StatusCode) { 5 | ^^^^^^^^^^^^^ ``` The fix is to swap them: `(StatusCode::CREATED, Json(Article { id: 1 }))`. ### 2. `impl IntoResponse` with branches that return different types [Section titled “2. impl IntoResponse with branches that return different types”](#2-impl-intoresponse-with-branches-that-return-different-types) `-> impl IntoResponse` returns *one* concrete type. If your branches return different concrete types, the error is the plain Rust `if`/`else` mismatch, not an axum-specific message: ```rust 1 use axum::{http::StatusCode, response::IntoResponse, Json}; 2 use serde::Serialize; 3 4 #[derive(Serialize)] 5 struct Item { id: u64 } 6 7 // does not compile (error[E0308]): the two branches are different types 8 async fn handler(ok: bool) -> impl IntoResponse { 9 if ok { 10 Json(Item { id: 1 }) 11 } else { 12 StatusCode::NOT_FOUND 13 } 14 } ``` The real error from `cargo check`: ```text 1 error[E0308]: `if` and `else` have incompatible types 2 --> src/main.rs:11:9 3 | 4 8 | / if ok { 5 9 | | Json(Item { id: 1 }) 6 | | -------------------- expected because of this 7 10 | | } else { 8 11 | | StatusCode::NOT_FOUND 9 | | ^^^^^^^^^^^^^^^^^^^^^ expected `Json<Item>`, found `StatusCode` 10 12 | | } 11 | |_____- `if` and `else` have incompatible types ``` The fix is to unify the types by erasing them to `Response`: ```rust 1 use axum::{http::StatusCode, response::{IntoResponse, Response}, Json}; 2 use serde::Serialize; 3 4 #[derive(Serialize)] 5 struct Item { id: u64 } 6 7 async fn handler(ok: bool) -> Response { 8 if ok { 9 Json(Item { id: 1 }).into_response() 10 } else { 11 StatusCode::NOT_FOUND.into_response() 12 } 13 } ``` ### 3. A header you set is silently overridden by a later part [Section titled “3. A header you set is silently overridden by a later part”](#3-a-header-you-set-is-silently-overridden-by-a-later-part) The parts of a response tuple are applied left to right, but the **header array runs *after* the body’s own headers**, so it can clobber them. If you set `content-type: text/plain` in a tuple *and* include a `Json` body, the explicit header wins and you end up with JSON bytes labelled `text/plain`: ```rust 1 use axum::{http::{header, HeaderValue, StatusCode}, response::IntoResponse, Json}; 2 use serde::Serialize; 3 4 #[derive(Serialize)] 5 struct X { a: u8 } 6 7 // content-type ends up "text/plain" even though the body is JSON — surprising! 8 async fn confused() -> impl IntoResponse { 9 ( 10 StatusCode::OK, 11 [(header::CONTENT_TYPE, HeaderValue::from_static("text/plain"))], 12 Json(X { a: 1 }), 13 ) 14 } ``` Checking the produced response confirms it: the tuple header overrode `Json`’s `application/json`. ```text 1 headers-then-Json content-type = Some("text/plain") 2 Json-only content-type = Some("application/json") ``` Do not set `content-type` by hand alongside a typed body; let `Json` (or `String`) set it. Reserve explicit `content-type` for raw bodies (`String`/`Vec<u8>`) and custom `IntoResponse` impls. ### 4. Building a `HeaderValue` from arbitrary, possibly-invalid input [Section titled “4. Building a HeaderValue from arbitrary, possibly-invalid input”](#4-building-a-headervalue-from-arbitrary-possibly-invalid-input) `HeaderValue::from_static` only accepts a `&'static str` and *panics* on an illegal value, so it is for literals you control. For dynamic strings (a path, a user-derived token) use `HeaderValue::from_str`, which returns a `Result`: ```rust 1 use axum::http::HeaderValue; 2 3 fn check() { 4 // Illegal: a value with a newline (header-injection attempt) is rejected. 5 let bad = HeaderValue::from_str("ok\ninjected"); 6 println!("is_err = {}", bad.is_err()); // is_err = true 7 8 let good = HeaderValue::from_str("fine"); 9 println!("is_ok = {}", good.is_ok()); // is_ok = true 10 } ``` Handle the `Err` rather than `.unwrap()`-ing it on untrusted input, or you turn a malformed header into a `500`. ### 5. Reaching for a `res`-style mutable object [Section titled “5. Reaching for a res-style mutable object”](#5-reaching-for-a-res-style-mutable-object) There is no `res`. New TypeScript-to-Rust developers sometimes look for a `&mut Response` parameter to mutate. The model is different and simpler: assemble the whole response as a value and return it. If you find yourself wanting to “set a header partway through,” build the pieces into local variables and combine them in the `return` expression, or implement `IntoResponse` for a type that carries them. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Default to the `(StatusCode, Json<T>)` tuple.** It is the clearest, most common response and reads almost like `res.status(n).json(x)`. Reach for fancier shapes only when you need headers or branching. * **Use `-> Json<T>` or `-> impl IntoResponse` for single-shape handlers; use `-> Response` (or `Result`/an enum) when branches differ.** Matching the return type to the situation keeps the compiler on your side and the signature honest. * **Let typed bodies own their `content-type`.** `Json` sets `application/json`, `String`/`&str` set `text/plain`. Only set `content-type` manually for raw bytes or custom formats — and never alongside `Json` (pitfall 3). * **Prefer `header::*` constants and `HeaderName::from_static` over stringly-typed names.** Typos in a string header name compile fine and fail silently; the constants do not. * **Use `HeaderValue::from_str` for dynamic values and handle the error.** Reserve `from_static` for compile-time literals. * **Implement `IntoResponse` for your domain/error types.** A `Csv`, an `ApiError`, a `Created<T>` envelope: one impl, reused everywhere, keeps handlers tiny. This is the on-ramp to [centralized error handling](/16-web-apis/10-error-handling-web/). * **Return `StatusCode::NO_CONTENT` for successful deletes and other body-less successes** instead of a `200` with an empty JSON object. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored pattern: a single `ApiResponse` enum with one `IntoResponse` impl that centralizes the status code, headers, and body for every kind of success and failure a resource can produce. Handlers just return the right variant; the response shaping lives in one place. Every line is compile-verified against axum 0.8. ```rust 1 use axum::{ 2 extract::{Path, State}, 3 http::{header, HeaderValue, StatusCode}, 4 response::{IntoResponse, Response}, 5 routing::{get, post}, 6 Json, Router, 7 }; 8 use serde::{Deserialize, Serialize}; 9 use std::sync::{Arc, Mutex}; 10 11 #[derive(Clone, Serialize)] 12 struct Report { 13 id: u64, 14 title: String, 15 body: String, 16 } 17 18 #[derive(Deserialize)] 19 struct NewReport { 20 title: String, 21 body: String, 22 } 23 24 #[derive(Serialize)] 25 struct ApiError { 26 error: String, 27 code: &'static str, 28 } 29 30 // One enum, one IntoResponse impl. Each variant fully specifies its response: 31 // status code, headers, and body. Handlers never touch StatusCode directly. 32 enum ApiResponse { 33 Report(Report), 34 Created(Report), 35 NotFound, 36 Csv(String), 37 } 38 39 impl IntoResponse for ApiResponse { 40 fn into_response(self) -> Response { 41 match self { 42 ApiResponse::Report(r) => (StatusCode::OK, Json(r)).into_response(), 43 ApiResponse::Created(r) => { 44 let location = HeaderValue::from_str(&format!("/reports/{}", r.id)) 45 .unwrap_or_else(|_| HeaderValue::from_static("/reports")); 46 (StatusCode::CREATED, [(header::LOCATION, location)], Json(r)).into_response() 47 } 48 ApiResponse::NotFound => ( 49 StatusCode::NOT_FOUND, 50 Json(ApiError { error: "report not found".to_string(), code: "not_found" }), 51 ) 52 .into_response(), 53 ApiResponse::Csv(body) => ( 54 StatusCode::OK, 55 [ 56 (header::CONTENT_TYPE, HeaderValue::from_static("text/csv; charset=utf-8")), 57 ( 58 header::CONTENT_DISPOSITION, 59 HeaderValue::from_static("attachment; filename=\"reports.csv\""), 60 ), 61 ], 62 body, 63 ) 64 .into_response(), 65 } 66 } 67 } 68 69 #[derive(Clone, Default)] 70 struct AppState { 71 reports: Arc<Mutex<Vec<Report>>>, 72 next_id: Arc<Mutex<u64>>, 73 } 74 75 async fn get_report(State(s): State<AppState>, Path(id): Path<u64>) -> ApiResponse { 76 let reports = s.reports.lock().unwrap(); 77 match reports.iter().find(|r| r.id == id) { 78 Some(r) => ApiResponse::Report(r.clone()), 79 None => ApiResponse::NotFound, 80 } 81 } 82 83 async fn create_report(State(s): State<AppState>, Json(body): Json<NewReport>) -> ApiResponse { 84 let mut id = s.next_id.lock().unwrap(); 85 *id += 1; 86 let report = Report { id: *id, title: body.title, body: body.body }; 87 s.reports.lock().unwrap().push(report.clone()); 88 ApiResponse::Created(report) 89 } 90 91 async fn export_csv(State(s): State<AppState>) -> ApiResponse { 92 let reports = s.reports.lock().unwrap(); 93 let mut csv = String::from("id,title\n"); 94 for r in reports.iter() { 95 csv.push_str(&format!("{},{}\n", r.id, r.title)); 96 } 97 ApiResponse::Csv(csv) 98 } 99 100 fn app() -> Router { 101 Router::new() 102 .route("/reports", post(create_report)) 103 .route("/reports/{id}", get(get_report)) 104 .route("/reports.csv", get(export_csv)) 105 .with_state(AppState::default()) 106 } 107 108 #[tokio::main] 109 async fn main() { 110 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 111 println!("listening on {}", listener.local_addr().unwrap()); 112 axum::serve(listener, app()).await.unwrap(); 113 } ``` Exercising it produces these **real** responses: ```text 1 $ curl -s -i -X POST http://127.0.0.1:3000/reports \ 2 -H 'content-type: application/json' -d '{"title":"Q1","body":"numbers"}' 3 HTTP/1.1 201 Created 4 content-type: application/json 5 location: /reports/1 6 content-length: 38 7 8 {"id":1,"title":"Q1","body":"numbers"} 9 10 $ curl -s -i http://127.0.0.1:3000/reports/999 11 HTTP/1.1 404 Not Found 12 content-type: application/json 13 content-length: 47 14 15 {"error":"report not found","code":"not_found"} 16 17 $ curl -s -i http://127.0.0.1:3000/reports.csv 18 HTTP/1.1 200 OK 19 content-type: text/csv; charset=utf-8 20 content-disposition: attachment; filename="reports.csv" 21 content-length: 14 22 23 id,title 24 1,Q1 ``` Why this pattern scales: the status-code/header/body decisions for the whole resource live in *one* `match`, so they cannot drift apart between handlers. Handlers stay declarative (“this is a `Created`, this is a `NotFound`”), and adding a new response kind is one new enum variant plus one new match arm. For *error* types specifically, the same technique — implementing `IntoResponse` for an error enum, often with [`thiserror`](/08-error-handling/) — is covered in depth in [Error Handling in Web Apps](/16-web-apis/10-error-handling-web/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`axum::response` module docs](https://docs.rs/axum/latest/axum/response/index.html): `IntoResponse`, `Response`, `Redirect`, `AppendHeaders`, and the full list of impls. * [`IntoResponse` trait reference](https://docs.rs/axum/latest/axum/response/trait.IntoResponse.html): the canonical table of what converts into a response. * [`axum::Json`](https://docs.rs/axum/latest/axum/struct.Json.html): the JSON wrapper as both extractor and response. * [`http::StatusCode`](https://docs.rs/http/latest/http/status/struct.StatusCode.html) and [`http::header`](https://docs.rs/http/latest/http/header/index.html): status and header-name constants. Within this guide: * [Axum Fundamentals](/16-web-apis/01-axum-basics/) — the handler loop, `Router`, `axum::serve`; where this page’s return values plug in. * [Extractors](/16-web-apis/04-extractors/) — the input mirror image: `Json`/`Path`/`Query` as request data. * [JSON APIs](/16-web-apis/08-json-apis/): a full CRUD resource built on these response shapes. * [Error Handling in Web Apps](/16-web-apis/10-error-handling-web/): a custom `AppError: IntoResponse` mapping errors to status codes. * [Routing](/16-web-apis/03-routing/): `{id}` path syntax and method routing for the routes these handlers serve. * [State Management](/16-web-apis/06-state-management/): the `State<T>` + `Arc` the Real-World Example relies on. * [Middleware](/16-web-apis/05-middleware/) — Tower layers that wrap or rewrite responses after a handler returns. * Foundations: [traits](/09-generics-traits/) (what `IntoResponse` *is*), [error handling](/08-error-handling/) (`Result` as a response), the language [basics](/02-basics/) and [getting started](/01-getting-started/). * Persisting what these handlers return: [Database](/17-database/). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A cache-friendly health check [Section titled “Exercise 1: A cache-friendly health check”](#exercise-1-a-cache-friendly-health-check) **Difficulty:** Easy **Objective:** Return JSON with a status code and a custom header in one tuple. **Instructions:** 1. Add a `GET /ping` route. 2. Return a `200 OK` whose body is the JSON `{"pong":true}` and which carries a `Cache-Control: no-cache` header. 3. Use a `(StatusCode, [...], Json<...>)` tuple. Define a `#[derive(Serialize)]` struct for the body. Solution ```rust 1 use axum::{ 2 http::{header, HeaderValue, StatusCode}, 3 response::IntoResponse, 4 routing::get, 5 Json, Router, 6 }; 7 use serde::Serialize; 8 9 #[derive(Serialize)] 10 struct Pong { 11 pong: bool, 12 } 13 14 async fn ping() -> impl IntoResponse { 15 ( 16 StatusCode::OK, 17 [(header::CACHE_CONTROL, HeaderValue::from_static("no-cache"))], 18 Json(Pong { pong: true }), 19 ) 20 } 21 22 #[tokio::main] 23 async fn main() { 24 let app = Router::new().route("/ping", get(ping)); 25 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 26 axum::serve(listener, app).await.unwrap(); 27 } ``` `GET /ping` returns `200 OK`, `cache-control: no-cache`, and the body `{"pong":true}`. ### Exercise 2: A reusable error type [Section titled “Exercise 2: A reusable error type”](#exercise-2-a-reusable-error-type) **Difficulty:** Medium **Objective:** Implement `IntoResponse` for an error enum so handlers can return `Result<_, AppError>` and get the right status plus a JSON error body automatically. **Instructions:** 1. Define `enum AppError { NotFound(String), RateLimited }`. 2. Implement `IntoResponse` for it: `NotFound(what)` maps to `404` with body `{"error":"<what> not found"}`; `RateLimited` maps to `429 Too Many Requests` with body `{"error":"slow down"}`. 3. Write two handlers, `Err(AppError::NotFound("widget".into()))` and `Err(AppError::RateLimited)`, returning `Result<&'static str, AppError>`, and confirm the statuses. Solution ```rust 1 use axum::{ 2 http::StatusCode, 3 response::{IntoResponse, Response}, 4 routing::get, 5 Json, Router, 6 }; 7 use serde::Serialize; 8 9 #[derive(Serialize)] 10 struct ErrorBody { 11 error: String, 12 } 13 14 enum AppError { 15 NotFound(String), 16 RateLimited, 17 } 18 19 impl IntoResponse for AppError { 20 fn into_response(self) -> Response { 21 let (status, message) = match self { 22 AppError::NotFound(what) => (StatusCode::NOT_FOUND, format!("{what} not found")), 23 AppError::RateLimited => (StatusCode::TOO_MANY_REQUESTS, "slow down".to_string()), 24 }; 25 (status, Json(ErrorBody { error: message })).into_response() 26 } 27 } 28 29 async fn missing() -> Result<&'static str, AppError> { 30 Err(AppError::NotFound("widget".to_string())) 31 } 32 33 async fn limited() -> Result<&'static str, AppError> { 34 Err(AppError::RateLimited) 35 } 36 37 #[tokio::main] 38 async fn main() { 39 let app = Router::new() 40 .route("/missing", get(missing)) 41 .route("/limited", get(limited)); 42 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 43 axum::serve(listener, app).await.unwrap(); 44 } ``` `GET /missing` returns `404` with `{"error":"widget not found"}`; `GET /limited` returns `429` with `{"error":"slow down"}`. Because `AppError: IntoResponse`, `Result<T, AppError>` is itself a valid handler return type — the `?` operator and `Err(..)` now produce well-formed HTTP errors. This is exactly the seed of [Error Handling in Web Apps](/16-web-apis/10-error-handling-web/). ### Exercise 3: A conditional `304 Not Modified` [Section titled “Exercise 3: A conditional 304 Not Modified”](#exercise-3-a-conditional-304-not-modified) **Difficulty:** Hard **Objective:** Branch on a request header and return *different response shapes* — the case where you must reach for `-> Response`. **Instructions:** 1. Add a `GET /docs/{id}` route. Give the document a fixed ETag, e.g. `"v1"` (including the quotes, per the HTTP spec). 2. Read the `If-None-Match` request header (`HeaderMap` is an extractor). 3. If it equals the current ETag, return `304 Not Modified` with an empty body. Otherwise return `200 OK` with the document as JSON **and** an `ETag` response header. 4. Because the two branches differ, the handler must return `Response`. Solution ```rust 1 use axum::{ 2 extract::Path, 3 http::{header, HeaderMap, StatusCode}, 4 response::{IntoResponse, Response}, 5 routing::get, 6 Json, Router, 7 }; 8 use serde::Serialize; 9 10 #[derive(Serialize)] 11 struct Doc { 12 id: u64, 13 etag: &'static str, 14 } 15 16 async fn get_doc(Path(id): Path<u64>, headers: HeaderMap) -> Response { 17 let current_etag = "\"v1\""; 18 19 let matches = headers 20 .get(header::IF_NONE_MATCH) 21 .and_then(|v| v.to_str().ok()) 22 .map(|v| v == current_etag) 23 .unwrap_or(false); 24 25 if matches { 26 return StatusCode::NOT_MODIFIED.into_response(); 27 } 28 29 ( 30 StatusCode::OK, 31 [(header::ETAG, current_etag)], 32 Json(Doc { id, etag: current_etag }), 33 ) 34 .into_response() 35 } 36 37 #[tokio::main] 38 async fn main() { 39 let app = Router::new().route("/docs/{id}", get(get_doc)); 40 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 41 axum::serve(listener, app).await.unwrap(); 42 } ``` `GET /docs/1` (no `If-None-Match`) returns `200` with `etag: "v1"` and body `{"id":1,"etag":"\"v1\""}`. `GET /docs/1 -H 'If-None-Match: "v1"'` returns `304 Not Modified` with an empty body. The two branches return different concrete types (`StatusCode` vs a 3-tuple), so each is `.into_response()`-ed to the common `Response` type — this is the canonical reason to write `-> Response` instead of `-> impl IntoResponse`. # JSON REST APIs > Build a full CRUD resource in Axum where serde and the Json extractor type-check request and response bodies — no more unsafe req.body cast from Express. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A JSON REST API is the bread and butter of backend work: accept a typed JSON body, do something with it, and return a typed JSON response with a sensible status code. In Express you wire this up with `express.json()` and hand-rolled validation; in **Axum** the `Json` extractor and the `Json` response type, both powered by **serde**, give you the same workflow with the request and response shapes checked at compile time. This page builds a complete CRUD resource (`/notes`) and shows how serde’s derive macros control exactly what your JSON looks like on the wire. > **Note:** The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically. This page targets **axum 0.8** (`axum::serve` + `tokio::net::TcpListener`, `{id}` path captures — not the old `:id`). For the Express-to-Axum fundamentals (router, handlers, starting the server) see [Axum Fundamentals](/16-web-apis/01-axum-basics/); for how `Json` works as an *input* extractor alongside `Path`/`Query`/`State`, see [Extractors](/16-web-apis/04-extractors/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Here is a realistic in-memory CRUD resource in Express: list, create, read, update, and delete “notes”. It is the kind of thing you would write before reaching for a database. ```typescript 1 // notes-api.ts — Express 5 2 import express, { Request, Response } from "express"; 3 import { randomUUID } from "node:crypto"; 4 5 interface Note { 6 id: string; 7 title: string; 8 body: string; 9 done: boolean; 10 } 11 12 // Body shapes accepted from clients (no server-assigned fields). 13 interface CreateNote { 14 title: string; 15 body: string; 16 } 17 interface UpdateNote { 18 title?: string; 19 body?: string; 20 done?: boolean; 21 } 22 23 const notes = new Map<string, Note>(); 24 25 const app = express(); 26 app.use(express.json()); // populate req.body for JSON requests 27 28 // GET /notes — list everything 29 app.get("/notes", (_req: Request, res: Response) => { 30 res.json([...notes.values()]); 31 }); 32 33 // POST /notes — create, reply 201 34 app.post("/notes", (req: Request, res: Response) => { 35 const input = req.body as CreateNote; // a cast, NOT a runtime check 36 if (typeof input.title !== "string" || typeof input.body !== "string") { 37 return res.status(422).json({ error: "title and body are required" }); 38 } 39 const note: Note = { 40 id: randomUUID(), 41 title: input.title, 42 body: input.body, 43 done: false, 44 }; 45 notes.set(note.id, note); 46 res.status(201).json(note); 47 }); 48 49 // GET /notes/:id — one note or 404 50 app.get("/notes/:id", (req: Request, res: Response) => { 51 const note = notes.get(req.params.id); 52 if (!note) return res.status(404).json({ error: "note not found" }); 53 res.json(note); 54 }); 55 56 // PUT /notes/:id — partial update or 404 57 app.put("/notes/:id", (req: Request, res: Response) => { 58 const note = notes.get(req.params.id); 59 if (!note) return res.status(404).json({ error: "note not found" }); 60 const patch = req.body as UpdateNote; 61 if (patch.title !== undefined) note.title = patch.title; 62 if (patch.body !== undefined) note.body = patch.body; 63 if (patch.done !== undefined) note.done = patch.done; 64 res.json(note); 65 }); 66 67 // DELETE /notes/:id — 204 or 404 68 app.delete("/notes/:id", (req: Request, res: Response) => { 69 if (notes.delete(req.params.id)) return res.status(204).end(); 70 res.status(404).json({ error: "note not found" }); 71 }); 72 73 app.listen(3000, () => console.log("listening on http://127.0.0.1:3000")); ``` What a TypeScript developer relies on here: `express.json()` parses the body into `req.body`, but `req.body as CreateNote` is a **compile-time cast that does nothing at runtime**. If the client sends `{}` or `{"title": 42}`, the cast still “succeeds” and you only find out when something downstream breaks. So you write the `typeof` checks by hand. The `UpdateNote` fields are optional (`title?`), giving a PATCH-style partial update. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same resource in Axum. The `Json<T>` extractor deserializes *and* validates the request body’s shape against the target type before the handler runs; returning `Json<T>` serializes the response and sets `Content-Type: application/json`. ```rust 1 use axum::{ 2 extract::{Path, State}, 3 http::StatusCode, 4 response::IntoResponse, 5 routing::get, 6 Json, Router, 7 }; 8 use serde::{Deserialize, Serialize}; 9 use std::collections::HashMap; 10 use std::sync::{Arc, RwLock}; 11 use uuid::Uuid; 12 13 // The resource we store and return. `Serialize` lets it become a JSON response. 14 #[derive(Clone, Serialize)] 15 struct Note { 16 id: Uuid, 17 title: String, 18 body: String, 19 done: bool, 20 } 21 22 // The body shape for POST /notes — no `id`, the server assigns it. 23 // `Deserialize` lets `Json<CreateNote>` parse it out of the request body. 24 #[derive(Deserialize)] 25 struct CreateNote { 26 title: String, 27 body: String, 28 } 29 30 // The body shape for PUT /notes/{id} — every field optional (partial update). 31 #[derive(Deserialize)] 32 struct UpdateNote { 33 title: Option<String>, 34 body: Option<String>, 35 done: Option<bool>, 36 } 37 38 // Shared, thread-safe store. `RwLock` allows many concurrent readers. 39 type Db = Arc<RwLock<HashMap<Uuid, Note>>>; 40 41 #[derive(Clone, Default)] 42 struct AppState { 43 notes: Db, 44 } 45 46 // GET /notes — list every note. A `Vec<T>` serializes to a JSON array. 47 async fn list_notes(State(state): State<AppState>) -> Json<Vec<Note>> { 48 let notes = state.notes.read().unwrap(); 49 Json(notes.values().cloned().collect()) 50 } 51 52 // POST /notes — create one, reply 201 + the created resource. 53 async fn create_note( 54 State(state): State<AppState>, 55 Json(input): Json<CreateNote>, 56 ) -> impl IntoResponse { 57 let note = Note { 58 id: Uuid::new_v4(), 59 title: input.title, 60 body: input.body, 61 done: false, 62 }; 63 state.notes.write().unwrap().insert(note.id, note.clone()); 64 (StatusCode::CREATED, Json(note)) 65 } 66 67 // GET /notes/{id} — one note, or 404. 68 async fn get_note( 69 State(state): State<AppState>, 70 Path(id): Path<Uuid>, 71 ) -> Result<Json<Note>, StatusCode> { 72 state 73 .notes 74 .read() 75 .unwrap() 76 .get(&id) 77 .cloned() 78 .map(Json) 79 .ok_or(StatusCode::NOT_FOUND) 80 } 81 82 // PUT /notes/{id} — partial update; 404 if missing. 83 async fn update_note( 84 State(state): State<AppState>, 85 Path(id): Path<Uuid>, 86 Json(input): Json<UpdateNote>, 87 ) -> Result<Json<Note>, StatusCode> { 88 let mut notes = state.notes.write().unwrap(); 89 let note = notes.get_mut(&id).ok_or(StatusCode::NOT_FOUND)?; 90 if let Some(title) = input.title { 91 note.title = title; 92 } 93 if let Some(body) = input.body { 94 note.body = body; 95 } 96 if let Some(done) = input.done { 97 note.done = done; 98 } 99 Ok(Json(note.clone())) 100 } 101 102 // DELETE /notes/{id} — 204 on success, 404 if it was not there. 103 async fn delete_note( 104 State(state): State<AppState>, 105 Path(id): Path<Uuid>, 106 ) -> StatusCode { 107 if state.notes.write().unwrap().remove(&id).is_some() { 108 StatusCode::NO_CONTENT 109 } else { 110 StatusCode::NOT_FOUND 111 } 112 } 113 114 fn app() -> Router { 115 Router::new() 116 .route("/notes", get(list_notes).post(create_note)) 117 .route( 118 "/notes/{id}", 119 get(get_note).put(update_note).delete(delete_note), 120 ) 121 .with_state(AppState::default()) 122 } 123 124 #[tokio::main] 125 async fn main() { 126 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000") 127 .await 128 .unwrap(); 129 println!("listening on http://{}", listener.local_addr().unwrap()); 130 axum::serve(listener, app()).await.unwrap(); 131 } ``` The dependencies (run these in a fresh `cargo new` project; `cargo add` resolves the current versions automatically): ```bash 1 cargo add axum 2 cargo add tokio --features full 3 cargo add serde --features derive 4 cargo add serde_json 5 cargo add uuid --features v4,serde ``` This produces a `Cargo.toml` with the current stable versions: ```toml 1 [dependencies] 2 axum = "0.8.9" 3 serde = { version = "1.0.228", features = ["derive"] } 4 serde_json = "1.0.150" 5 tokio = { version = "1.52.3", features = ["full"] } 6 uuid = { version = "1.23.2", features = ["v4", "serde"] } ``` > **Note:** `serde_json` is the engine `Json` uses under the hood. The `axum::Json` type pulls it in transitively, but you add `serde_json` explicitly because you will reach for `serde_json::json!` and `serde_json::Value` directly (shown later). The `uuid` crate’s `serde` feature is what lets `Uuid` round-trip through JSON; its `v4` feature provides random id generation. Run it with `cargo run`. Exercising the endpoints with `curl` produces this **real** output (captured against the compiled server): ```text 1 $ curl -s -i -X POST http://127.0.0.1:3000/notes \ 2 -H 'content-type: application/json' -d '{"title":"Buy milk","body":"2 liters"}' 3 HTTP/1.1 201 Created 4 content-type: application/json 5 content-length: 95 6 date: Mon, 01 Jun 2026 11:53:53 GMT 7 8 {"id":"bff6b79a-d1cc-42f0-b7f0-30ff8e4f0094","title":"Buy milk","body":"2 liters","done":false} 9 10 $ curl -s http://127.0.0.1:3000/notes/69ca8514-0ec2-4164-9677-76cb63cd613d 11 {"id":"69ca8514-0ec2-4164-9677-76cb63cd613d","title":"Walk dog","body":"around the block","done":false} 12 13 $ curl -s -i -X PUT http://127.0.0.1:3000/notes/69ca8514-0ec2-4164-9677-76cb63cd613d \ 14 -H 'content-type: application/json' -d '{"done":true}' 15 HTTP/1.1 200 OK 16 content-type: application/json 17 content-length: 102 18 19 {"id":"69ca8514-0ec2-4164-9677-76cb63cd613d","title":"Walk dog","body":"around the block","done":true} 20 21 $ curl -s -i -X DELETE http://127.0.0.1:3000/notes/69ca8514-0ec2-4164-9677-76cb63cd613d 22 HTTP/1.1 204 No Content 23 date: Mon, 01 Jun 2026 11:53:54 GMT ``` The validation you wrote by hand in Express comes for free. These are also **real** responses from the same server: ```text 1 $ curl -s -i http://127.0.0.1:3000/notes/not-a-uuid # bad path param 2 HTTP/1.1 400 Bad Request 3 content-type: text/plain; charset=utf-8 4 5 Invalid URL: Cannot parse `id` with value `not-a-uuid`: UUID parsing failed: invalid character: found `n` at 0 6 7 $ curl -s -i -X POST http://127.0.0.1:3000/notes \ # missing `body` 8 -H 'content-type: application/json' -d '{"title":"oops"}' 9 HTTP/1.1 422 Unprocessable Entity 10 content-type: text/plain; charset=utf-8 11 12 Failed to deserialize the JSON body into the target type: missing field `body` at line 1 column 16 13 14 $ curl -s -i -X POST http://127.0.0.1:3000/notes \ # wrong type for `title` 15 -H 'content-type: application/json' -d '{"title":1,"body":"y"}' 16 HTTP/1.1 422 Unprocessable Entity 17 18 Failed to deserialize the JSON body into the target type: title: invalid type: integer `1`, expected a string at line 1 column 10 19 20 $ curl -s -i -X POST http://127.0.0.1:3000/notes \ # no Content-Type header 21 -d '{"title":"x","body":"y"}' 22 HTTP/1.1 415 Unsupported Media Type 23 24 Expected request with `Content-Type: application/json` 25 26 $ curl -s -i -X POST http://127.0.0.1:3000/notes \ # malformed JSON 27 -H 'content-type: application/json' -d '{"title":' 28 HTTP/1.1 400 Bad Request 29 30 Failed to parse the request body as JSON: title: EOF while parsing a value at line 1 column 9 ``` Note the precise status-code choices, all made *before your handler runs*: a malformed-syntax body is `400`, a body that parses but has the wrong *shape* is `422 Unprocessable Entity`, and a missing/incorrect content type is `415`. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `Json<T>` is both an extractor and a response [Section titled “Json\<T> is both an extractor and a response”](#jsont-is-both-an-extractor-and-a-response) This is the single most important idea on this page. The same type `axum::Json<T>` plays two roles: * **As a handler parameter** (`Json(input): Json<CreateNote>`), it implements `FromRequest`: it reads the whole body, checks `Content-Type: application/json`, and runs `serde_json` deserialization into `T`. `T` must be `Deserialize`. * **As a return value** (`-> Json<Note>` or inside a tuple), it implements `IntoResponse`: it serializes the wrapped value with `serde_json` and sets the `Content-Type` header. `T` must be `Serialize`. ```rust 1 // Input: Json<T> where T: Deserialize (body -> struct) 2 // Output: Json<T> where T: Serialize (struct -> body) ``` This symmetry is why a “round-trip” type — one accepted *and* returned — derives both: `#[derive(Serialize, Deserialize)]`. In our example `Note` is only ever *returned*, so it derives only `Serialize`; `CreateNote`/`UpdateNote` are only ever *received*, so they derive only `Deserialize`. Deriving exactly what each type needs documents its direction. > **Note:** Because `Json` (as an extractor) consumes the request body, it must be the **last** parameter in a handler, after metadata extractors like `State` and `Path`. See [Extractors](/16-web-apis/04-extractors/) for the `FromRequest` vs `FromRequestParts` ordering rule. ### serde does the work; derive macros control the wire format [Section titled “serde does the work; derive macros control the wire format”](#serde-does-the-work-derive-macros-control-the-wire-format) `#[derive(Serialize)]` and `#[derive(Deserialize)]` generate, at compile time, code that maps your struct to and from JSON. By default a Rust field `display_name` becomes the JSON key `"display_name"`. Real APIs usually want `camelCase`, optional fields that disappear when empty, and defaults for missing fields. serde attributes give you all of that declaratively. Here is a compile-verified demonstration: ```rust 1 use serde::{Deserialize, Serialize}; 2 3 #[derive(Serialize, Deserialize, Debug)] 4 #[serde(rename_all = "camelCase")] 5 struct Product { 6 id: u64, 7 display_name: String, // <-> JSON "displayName" 8 #[serde(skip_serializing_if = "Option::is_none")] 9 description: Option<String>, // omitted from output when None 10 #[serde(default)] 11 tags: Vec<String>, // defaults to [] if absent in the input 12 } 13 14 fn main() { 15 // Serialize: snake_case Rust fields become camelCase JSON. 16 let p = Product { 17 id: 1, 18 display_name: "Widget".to_string(), 19 description: None, 20 tags: vec!["new".to_string()], 21 }; 22 println!("OUT: {}", serde_json::to_string(&p).unwrap()); 23 24 // Deserialize: camelCase JSON in, and the missing `tags` defaults to []. 25 let json = r#"{"id":2,"displayName":"Gadget"}"#; 26 let parsed: Product = serde_json::from_str(json).unwrap(); 27 println!("IN: {parsed:?}"); 28 } ``` The **real** output: ```text 1 OUT: {"id":1,"displayName":"Widget","tags":["new"]} 2 IN: Product { id: 2, display_name: "Gadget", description: None, tags: [] } ``` Three attributes earn their keep on almost every API type: | Attribute | Effect | TypeScript analogue | | --------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------ | | `#[serde(rename_all = "camelCase")]` | maps `snake_case` fields to `camelCase` JSON keys | nothing automatic; you name fields by hand | | `#[serde(skip_serializing_if = "Option::is_none")]` | omits a `None` field from the output entirely | `if (x !== undefined) obj.x = x` | | `#[serde(default)]` | uses the type’s `Default` when the key is absent on input | `const x = body.x ?? defaultValue` | This whole topic — serde’s model, attributes, custom (de)serialization — is covered in depth in [Serialization](/15-serialization/). Here we use it specifically to shape an HTTP JSON body. ### `rename_all` keeps idiomatic Rust *and* idiomatic JSON [Section titled “rename\_all keeps idiomatic Rust and idiomatic JSON”](#rename_all-keeps-idiomatic-rust-and-idiomatic-json) JavaScript/TypeScript clients expect `camelCase`; idiomatic Rust uses `snake_case`. You do **not** have to choose. `#[serde(rename_all = "camelCase")]` lets you keep `created_at` in Rust while the JSON says `"createdAt"`, with zero per-field annotation. (Other casings are available too: `"kebab-case"`, `"SCREAMING_SNAKE_CASE"`, etc.) ### `Vec<T>` is a JSON array; `Option<T>` is “field may be absent or null” [Section titled “Vec\<T> is a JSON array; Option\<T> is “field may be absent or null””](#vect-is-a-json-array-optiont-is-field-may-be-absent-or-null) * Returning `Json<Vec<Note>>` produces a JSON array `[...]` (an empty list serializes to `[]`, never `null`). No wrapper object is added unless you ask for one. * An `Option<String>` field deserializes from a present value, an explicit `null`, or — with `#[serde(default)]` or because `Option` defaults to `None` for missing keys — an absent key. This is exactly what powers the PATCH-style `UpdateNote`: any field the client omits stays `None`, so the handler leaves it untouched. ### The status code is part of the response, set by the return type [Section titled “The status code is part of the response, set by the return type”](#the-status-code-is-part-of-the-response-set-by-the-return-type) `create_note` returns `(StatusCode::CREATED, Json(note))`. A tuple `(StatusCode, Json<T>)` implements `IntoResponse` as “this status **plus** this JSON body”. A bare `Json<T>` defaults to `200 OK`. `delete_note` returns a bare `StatusCode` (an empty-bodied response). And `get_note`/`update_note` return `Result<Json<Note>, StatusCode>`: the `Ok` arm is the JSON, the `Err` arm is the status. This is how you express “200 with a body, or 404” as a single type. The full `IntoResponse` story (headers, custom statuses, the `Result` pattern) lives in [Request and Response Handling](/16-web-apis/07-request-response/). ### Why `Uuid` instead of an auto-increment integer [Section titled “Why Uuid instead of an auto-increment integer”](#why-uuid-instead-of-an-auto-increment-integer) For an in-memory store keyed by a `HashMap`, a `Uuid` (`uuid::Uuid` with the `v4` feature) gives unique ids without a shared counter. With the `serde` feature, `Uuid` serializes to its canonical string form (`"bff6b79a-..."`) and deserializes back, with a non-UUID path segment rejected as a `400`. If you prefer integer ids, `Path<u64>` works identically; the database section ([Database](/17-database/)) shows server-assigned ids from a real backing store. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concern | Express.js | Axum | | --------------------- | -------------------------------------------- | ---------------------------------------------------- | | Parse body | `express.json()` middleware, then `req.body` | `Json<T>` extractor parameter | | Body type safety | `req.body as T` (a no-op cast) | `Json<T>` deserializes into `T`, or returns 4xx | | Missing/wrong field | silent `undefined`; you check by hand | `422` with the exact field and reason, automatically | | Field renaming | name fields manually | `#[serde(rename_all = "camelCase")]` | | Optional output field | `if (x) obj.x = x` | `#[serde(skip_serializing_if = "Option::is_none")]` | | Send JSON response | `res.json(value)` | `return Json(value)` | | Set status | `res.status(201).json(...)` | return `(StatusCode::CREATED, Json(...))` | | ”200 or 404” | `if (!x) return res.status(404)...` | `Result<Json<T>, StatusCode>` | | Partial update | optional interface fields | `Option<T>` struct fields | The conceptual shift: in Express, **parsing and validating JSON is imperative work inside the handler**; in Axum it is **declarative metadata on the type and in the signature**. A handler whose parameter is `Json<CreateNote>` cannot run with a malformed or wrong-shaped body. The type system and the framework guarantee it, the same way a function with typed parameters never sees the wrong argument types. > **Tip:** Think of your `Deserialize` DTOs as the runtime-checked version of TypeScript interfaces. A TS `interface CreateNote` vanishes at compile time; a Rust `#[derive(Deserialize)] struct CreateNote` becomes real parsing-and-validation code that rejects bad input at the door. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### 1. Using a type as a `Json` extractor when it only derives `Serialize` [Section titled “1. Using a type as a Json extractor when it only derives Serialize”](#1-using-a-type-as-a-json-extractor-when-it-only-derives-serialize) A type only becomes parseable from a request body when it derives `Deserialize`. If you have so far only *returned* a type (so it derives only `Serialize`) and then try to *accept* it, the handler fails the `Handler` trait bound. Annotating with `#[axum::debug_handler]` (enable the `macros` feature: `cargo add axum --features macros`) turns the cryptic bound error into the real cause: ```rust 1 use axum::{routing::post, Json, Router}; 2 use serde::Serialize; 3 4 #[derive(Serialize)] // only Serialize, not Deserialize 5 struct CreateNote { 6 title: String, 7 } 8 9 // does not compile (error[E0277]): CreateNote is not Deserialize, 10 // so Json<CreateNote> cannot be used as an extractor. 11 #[axum::debug_handler] 12 async fn create(Json(_note): Json<CreateNote>) -> &'static str { 13 "ok" 14 } 15 16 fn main() { 17 let _app: Router = Router::new().route("/notes", post(create)); 18 } ``` The **real** `cargo build` error: ```text 1 error[E0277]: the trait bound `CreateNote: serde::Deserialize<'de>` is not satisfied 2 --> src/bin/badjson.rs:12:30 3 | 4 12 | async fn create(Json(_note): Json<CreateNote>) -> &'static str { 5 | ^^^^ the trait `for<'de> Deserialize<'de>` is not implemented for `CreateNote` 6 | 7 = note: for local types consider adding `#[derive(serde::Deserialize)]` to your `CreateNote` type 8 = note: for types from other crates check whether the crate offers a `serde` feature flag 9 ... 10 = note: required for `CreateNote` to implement `DeserializeOwned` ``` The fix is exactly what the note says: add `#[derive(Deserialize)]` (or both `Serialize, Deserialize` for a round-trip type). ### 2. Expecting extra/unknown fields to be rejected by default [Section titled “2. Expecting extra/unknown fields to be rejected by default”](#2-expecting-extraunknown-fields-to-be-rejected-by-default) By default, serde **ignores** JSON keys that do not match a struct field. A client can send `{"title":"x","body":"y","admin":true}` to `CreateNote` and the `admin` field is silently dropped: handy for forward compatibility, surprising if you wanted to reject it. To make unknown fields an error, add `#[serde(deny_unknown_fields)]`: ```rust 1 use serde::Deserialize; 2 3 #[derive(Deserialize, Debug)] 4 #[serde(deny_unknown_fields)] 5 struct CreateNote { 6 title: String, 7 body: String, 8 } 9 10 fn main() { 11 let extra = r#"{"title":"a","body":"b","admin":true}"#; 12 match serde_json::from_str::<CreateNote>(extra) { 13 Ok(v) => println!("parsed: {v:?}"), 14 Err(e) => println!("ERR: {e}"), 15 } 16 } ``` **Real** output: ```text 1 ERR: unknown field `admin`, expected `title` or `body` at line 1 column 31 ``` Inside a handler, this surfaces as a `422` with that same message in the body. Use `deny_unknown_fields` on inbound DTOs when silently accepting unexpected keys would be a security or correctness problem (e.g. mass-assignment). ### 3. Returning the wrong default status for a write [Section titled “3. Returning the wrong default status for a write”](#3-returning-the-wrong-default-status-for-a-write) A freshly compiled handler that returns `Json(note)` from a `POST` sends `200 OK`, not `201 Created`. Axum will not guess your intent. Be explicit: return `(StatusCode::CREATED, Json(note))` for creates and `StatusCode::NO_CONTENT` (204) for a body-less delete. Forgetting this is not a compiler error; it is a contract bug a test will catch. ### 4. Treating `Option<T>` “absent” and “null” as different in JSON [Section titled “4. Treating Option\<T> “absent” and “null” as different in JSON”](#4-treating-optiont-absent-and-null-as-different-in-json) For a plain `Option<String>` field, both a missing key and an explicit `null` deserialize to `None`. If your API needs to distinguish “the client did not mention this field” from “the client set it to null” (true PATCH semantics), a single `Option` cannot express it: you need a nested `Option<Option<T>>` with `#[serde(default, skip_serializing_if = "Option::is_none")]`, or a dedicated patch enum. For most CRUD this distinction does not matter; just know the default collapses the two. ### 5. Forgetting the `Content-Type` header on the client [Section titled “5. Forgetting the Content-Type header on the client”](#5-forgetting-the-content-type-header-on-the-client) The `Json<T>` extractor requires `Content-Type: application/json`. A request without it gets a `415 Unsupported Media Type` (shown in the real output above) before your handler runs. This trips people testing with `curl` who forget `-H 'content-type: application/json'`. It is a feature: it stops form posts and other content types from being misread as JSON. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Derive exactly the direction each type needs.** `Serialize` for response-only types, `Deserialize` for request-only types, both for round-trip types. It documents intent and avoids the pitfall above. * **Separate the request DTO from the stored/returned model.** `CreateNote` (no `id`, no `done`) is deliberately not `Note`. The client should not be able to set server-owned fields like `id`, `created_at`, or `done`-on-create. Distinct types make that impossible by construction: the Rust equivalent of guarding against mass assignment. * **Apply `#[serde(rename_all = "camelCase")]` at the type level** so Rust stays idiomatic (`snake_case`) and the JSON stays idiomatic for JS/TS clients (`camelCase`). * **Use `Option<T>` + `skip_serializing_if` for sparse responses**, and `Option<T>` fields for PATCH-style partial updates. * **Pick correct status codes deliberately:** `201` for create, `200` for read/update, `204` for delete-with-no-body, `404`/`422`/`400` for the failure paths. Encode “found or not” as `Result<Json<T>, StatusCode>`. * **Reach for a single error type that implements `IntoResponse`** once you have more than one failure mode, so every error returns a consistent JSON envelope (shown next, and fully developed in [Error Handling in Web Apps](/16-web-apis/10-error-handling-web/)). * **Keep an `fn app() -> Router` builder** separate from `main`, so tests can drive the router with `tower::ServiceExt::oneshot` without binding a port. See [Testing](/13-testing/). * **For business-rule validation** (non-empty title, valid email, length limits) go beyond shape-checking; see [Validation](/16-web-apis/09-validation/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored `/notes` API: `camelCase` JSON, server-owned fields the client cannot set, unknown-field rejection on input, and a single `ApiError` type that gives every failure a consistent JSON body (`{"error": "..."}`) with the right status. This is the shape of a real service just before you swap the in-memory `HashMap` for a database. Every line is compile-verified against axum 0.8. ```rust 1 use axum::{ 2 extract::{Path, State}, 3 http::StatusCode, 4 response::{IntoResponse, Response}, 5 routing::get, 6 Json, Router, 7 }; 8 use serde::{Deserialize, Serialize}; 9 use serde_json::json; 10 use std::collections::HashMap; 11 use std::sync::{Arc, RwLock}; 12 use uuid::Uuid; 13 14 // Stored + returned. camelCase on the wire; `created_at` is server-owned. 15 #[derive(Clone, Serialize)] 16 #[serde(rename_all = "camelCase")] 17 struct Note { 18 id: Uuid, 19 title: String, 20 body: String, 21 done: bool, 22 created_at: String, 23 } 24 25 // Inbound create: client supplies only title + body. Unknown keys rejected. 26 #[derive(Deserialize)] 27 #[serde(rename_all = "camelCase", deny_unknown_fields)] 28 struct CreateNote { 29 title: String, 30 body: String, 31 } 32 33 // Inbound partial update: every field optional. 34 #[derive(Deserialize)] 35 #[serde(rename_all = "camelCase", deny_unknown_fields)] 36 struct UpdateNote { 37 title: Option<String>, 38 body: Option<String>, 39 done: Option<bool>, 40 } 41 42 // One error type for the whole resource. Implementing IntoResponse once means 43 // every handler can `?`-propagate or return it and get the same JSON envelope. 44 struct ApiError { 45 status: StatusCode, 46 message: String, 47 } 48 49 impl ApiError { 50 fn not_found(what: &str) -> Self { 51 ApiError { 52 status: StatusCode::NOT_FOUND, 53 message: format!("{what} not found"), 54 } 55 } 56 } 57 58 impl IntoResponse for ApiError { 59 fn into_response(self) -> Response { 60 (self.status, Json(json!({ "error": self.message }))).into_response() 61 } 62 } 63 64 type Db = Arc<RwLock<HashMap<Uuid, Note>>>; 65 66 #[derive(Clone, Default)] 67 struct AppState { 68 notes: Db, 69 } 70 71 async fn list_notes(State(state): State<AppState>) -> Json<Vec<Note>> { 72 Json(state.notes.read().unwrap().values().cloned().collect()) 73 } 74 75 async fn create_note( 76 State(state): State<AppState>, 77 Json(input): Json<CreateNote>, 78 ) -> (StatusCode, Json<Note>) { 79 let note = Note { 80 id: Uuid::new_v4(), 81 title: input.title, 82 body: input.body, 83 done: false, 84 created_at: "2026-06-01T00:00:00Z".to_string(), 85 }; 86 state.notes.write().unwrap().insert(note.id, note.clone()); 87 (StatusCode::CREATED, Json(note)) 88 } 89 90 async fn get_note( 91 State(state): State<AppState>, 92 Path(id): Path<Uuid>, 93 ) -> Result<Json<Note>, ApiError> { 94 state 95 .notes 96 .read() 97 .unwrap() 98 .get(&id) 99 .cloned() 100 .map(Json) 101 .ok_or_else(|| ApiError::not_found("note")) 102 } 103 104 async fn update_note( 105 State(state): State<AppState>, 106 Path(id): Path<Uuid>, 107 Json(input): Json<UpdateNote>, 108 ) -> Result<Json<Note>, ApiError> { 109 let mut notes = state.notes.write().unwrap(); 110 let note = notes.get_mut(&id).ok_or_else(|| ApiError::not_found("note"))?; 111 if let Some(t) = input.title { 112 note.title = t; 113 } 114 if let Some(b) = input.body { 115 note.body = b; 116 } 117 if let Some(d) = input.done { 118 note.done = d; 119 } 120 Ok(Json(note.clone())) 121 } 122 123 async fn delete_note( 124 State(state): State<AppState>, 125 Path(id): Path<Uuid>, 126 ) -> Result<StatusCode, ApiError> { 127 if state.notes.write().unwrap().remove(&id).is_some() { 128 Ok(StatusCode::NO_CONTENT) 129 } else { 130 Err(ApiError::not_found("note")) 131 } 132 } 133 134 fn app() -> Router { 135 Router::new() 136 .route("/notes", get(list_notes).post(create_note)) 137 .route( 138 "/notes/{id}", 139 get(get_note).put(update_note).delete(delete_note), 140 ) 141 .with_state(AppState::default()) 142 } 143 144 #[tokio::main] 145 async fn main() { 146 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000") 147 .await 148 .unwrap(); 149 println!("listening on http://{}", listener.local_addr().unwrap()); 150 axum::serve(listener, app()).await.unwrap(); 151 } ``` Exercising it produces these **real** responses. Note the `camelCase` `createdAt` in the output and the consistent JSON error envelope: ```text 1 $ curl -s -X POST http://127.0.0.1:3000/notes \ 2 -H 'content-type: application/json' -d '{"title":"Ship v1","body":"cut the release"}' 3 {"id":"c2c6d0c5-b545-4817-afee-bec328538892","title":"Ship v1","body":"cut the release","done":false,"createdAt":"2026-06-01T00:00:00Z"} 4 5 $ curl -s -i http://127.0.0.1:3000/notes/00000000-0000-0000-0000-000000000000 6 HTTP/1.1 404 Not Found 7 content-type: application/json 8 content-length: 26 9 10 {"error":"note not found"} 11 12 $ curl -s -i -X POST http://127.0.0.1:3000/notes \ 13 -H 'content-type: application/json' -d '{"title":"x","body":"y","admin":true}' 14 HTTP/1.1 422 Unprocessable Entity 15 content-type: text/plain; charset=utf-8 16 17 Failed to deserialize the JSON body into the target type: admin: unknown field `admin`, expected `title` or `body` at line 1 column 31 ``` Two production-relevant notes on this code: * **The `created_at` field is set by the server, never by the client.** Because `CreateNote` has no `created_at` field and uses `deny_unknown_fields`, a client *cannot* inject one. Separating the inbound DTO from the stored model is how Rust’s type system gives you mass-assignment protection for free. * **`ApiError` centralizes error responses.** Implementing `IntoResponse` once means handlers return `Result<_, ApiError>` and `?`-propagate failures, all yielding the same `{"error": "..."}` JSON shape. The serde extractor rejections (the `422` above) still produce serde’s default plain-text body; to bring *those* into the same JSON envelope, override the `Json` rejection, fully covered in [Error Handling in Web Apps](/16-web-apis/10-error-handling-web/). For real persistence, swap `HashMap` for a database pool in [State Management](/16-web-apis/06-state-management/) and [Database](/17-database/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`axum::Json`](https://docs.rs/axum/latest/axum/struct.Json.html): the extractor/response type used throughout this page. * [serde derive attributes](https://serde.rs/attributes.html): the full list of `#[serde(...)]` knobs (`rename_all`, `default`, `skip_serializing_if`, `deny_unknown_fields`, `flatten`, and more). * [`serde_json`](https://docs.rs/serde_json/latest/serde_json/): the JSON engine, including the `json!` macro and `serde_json::Value`. * [`uuid` crate](https://docs.rs/uuid/latest/uuid/): the `Uuid` type, its `v4` (random) and `serde` features. Within this guide: * [Axum Fundamentals](/16-web-apis/01-axum-basics/): Router, handlers, and starting the server (the foundation for this page). * [Extractors](/16-web-apis/04-extractors/): how `Json` works as an input extractor alongside `Path`, `Query`, `State`, and the body-extractor ordering rule. * [Request and Response Handling](/16-web-apis/07-request-response/): `IntoResponse`, status codes, headers, the `(StatusCode, Json<T>)` tuple, and the `Result` return pattern. * [Validation](/16-web-apis/09-validation/): business-rule validation beyond serde’s shape-checking, and helpful `400` messages. * [Error Handling in Web Apps](/16-web-apis/10-error-handling-web/): a full `AppError` with `thiserror`, mapping error kinds to status codes, and overriding extractor rejections. * [State Management](/16-web-apis/06-state-management/): sharing a database pool / config via `State<T>`. * [Routing](/16-web-apis/03-routing/): `{id}` path captures, method routing, nested routers. * Foundations: [Serialization](/15-serialization/) (serde in depth), [Error Handling](/08-error-handling/) (`Result`, `?`), [Generics and Traits](/09-generics-traits/), the language [Basics](/02-basics/) and [Getting Started](/01-getting-started/). * Persisting these resources: [Database](/17-database/). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Add a `GET /notes/count` endpoint [Section titled “Exercise 1: Add a GET /notes/count endpoint”](#exercise-1-add-a-get-notescount-endpoint) **Difficulty:** Beginner **Objective:** Return a small JSON object built from shared state. **Instructions:** Starting from the first Rust CRUD server in this page, add a `GET /notes/count` route that returns `{"count": N}` where `N` is the number of stored notes. Define a `#[derive(Serialize)]` response struct with a single `count: usize` field and read the length from the `RwLock`. Solution ```rust 1 use axum::{extract::State, routing::get, Json, Router}; 2 use serde::Serialize; 3 use std::collections::HashMap; 4 use std::sync::{Arc, RwLock}; 5 use uuid::Uuid; 6 7 #[derive(Clone, Serialize)] 8 struct Note { 9 id: Uuid, 10 title: String, 11 } 12 13 #[derive(Clone, Default)] 14 struct AppState { 15 notes: Arc<RwLock<HashMap<Uuid, Note>>>, 16 } 17 18 #[derive(Serialize)] 19 struct CountResponse { 20 count: usize, 21 } 22 23 async fn count_notes(State(state): State<AppState>) -> Json<CountResponse> { 24 let count = state.notes.read().unwrap().len(); 25 Json(CountResponse { count }) 26 } 27 28 fn app() -> Router { 29 Router::new() 30 .route("/notes/count", get(count_notes)) 31 .with_state(AppState::default()) 32 } 33 34 #[tokio::main] 35 async fn main() { 36 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000") 37 .await 38 .unwrap(); 39 axum::serve(listener, app()).await.unwrap(); 40 } ``` `GET /notes/count` returns `{"count":0}` on a fresh server. ### Exercise 2: Filter the list by a query parameter [Section titled “Exercise 2: Filter the list by a query parameter”](#exercise-2-filter-the-list-by-a-query-parameter) **Difficulty:** Intermediate **Objective:** Combine the `Json` response with a `Query` extractor to filter results. **Instructions:** Add a `GET /notes?done=true` (or `?done=false`) endpoint. Use a `Query<ListQuery>` extractor where `ListQuery` has a field `done: Option<bool>`. When `done` is provided, return only notes whose `done` matches; when absent, return all of them. Return `Json<Vec<Note>>`. Solution ```rust 1 use axum::{ 2 extract::{Query, State}, 3 routing::get, 4 Json, Router, 5 }; 6 use serde::{Deserialize, Serialize}; 7 use std::sync::{Arc, RwLock}; 8 9 #[derive(Clone, Serialize)] 10 struct Note { 11 id: u64, 12 title: String, 13 done: bool, 14 } 15 16 #[derive(Deserialize)] 17 struct ListQuery { 18 done: Option<bool>, 19 } 20 21 #[derive(Clone)] 22 struct AppState { 23 notes: Arc<RwLock<Vec<Note>>>, 24 } 25 26 async fn list_notes( 27 State(state): State<AppState>, 28 Query(q): Query<ListQuery>, 29 ) -> Json<Vec<Note>> { 30 let notes = state.notes.read().unwrap(); 31 let out: Vec<Note> = notes 32 .iter() 33 // `is_none_or`: keep everything when no filter, else match `done`. 34 .filter(|n| q.done.is_none_or(|d| n.done == d)) 35 .cloned() 36 .collect(); 37 Json(out) 38 } 39 40 fn app() -> Router { 41 let state = AppState { 42 notes: Arc::new(RwLock::new(vec![ 43 Note { id: 1, title: "a".into(), done: true }, 44 Note { id: 2, title: "b".into(), done: false }, 45 ])), 46 }; 47 Router::new() 48 .route("/notes", get(list_notes)) 49 .with_state(state) 50 } 51 52 #[tokio::main] 53 async fn main() { 54 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000") 55 .await 56 .unwrap(); 57 axum::serve(listener, app()).await.unwrap(); 58 } ``` `GET /notes` returns both notes; `GET /notes?done=true` returns `[{"id":1,"title":"a","done":true}]`; `GET /notes?done=false` returns only the second. (Note `Option::is_none_or`, which Clippy recommends over `map_or(true, ...)`.) ### Exercise 3: Reject empty titles with a JSON `400` [Section titled “Exercise 3: Reject empty titles with a JSON 400”](#exercise-3-reject-empty-titles-with-a-json-400) **Difficulty:** Advanced **Objective:** Add a business-rule check on top of serde’s shape-checking and return a structured `400`. **Instructions:** Extend `POST /notes` so that a blank or whitespace-only `title` is rejected with `400 Bad Request` and a JSON body `{"error":"title must not be empty"}`, while a valid create still returns `201` with the note. Use `impl IntoResponse` and the `serde_json::json!` macro to build the error body. (Shape-checking — required fields, correct types — is still handled by `Json<CreateNote>`; you are adding a *value* rule on top.) Solution ```rust 1 use axum::{ 2 extract::State, 3 http::StatusCode, 4 response::IntoResponse, 5 routing::post, 6 Json, Router, 7 }; 8 use serde::{Deserialize, Serialize}; 9 use serde_json::json; 10 use std::sync::{Arc, RwLock}; 11 12 #[derive(Clone, Serialize)] 13 struct Note { 14 id: u64, 15 title: String, 16 done: bool, 17 } 18 19 #[derive(Deserialize)] 20 struct CreateNote { 21 title: String, 22 } 23 24 #[derive(Clone, Default)] 25 struct AppState { 26 notes: Arc<RwLock<Vec<Note>>>, 27 } 28 29 async fn create_note( 30 State(state): State<AppState>, 31 Json(input): Json<CreateNote>, 32 ) -> impl IntoResponse { 33 let title = input.title.trim(); 34 if title.is_empty() { 35 return ( 36 StatusCode::BAD_REQUEST, 37 Json(json!({ "error": "title must not be empty" })), 38 ) 39 .into_response(); 40 } 41 let mut notes = state.notes.write().unwrap(); 42 let id = notes.len() as u64 + 1; 43 let note = Note { id, title: title.to_string(), done: false }; 44 notes.push(note.clone()); 45 (StatusCode::CREATED, Json(note)).into_response() 46 } 47 48 fn app() -> Router { 49 Router::new() 50 .route("/notes", post(create_note)) 51 .with_state(AppState::default()) 52 } 53 54 #[tokio::main] 55 async fn main() { 56 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000") 57 .await 58 .unwrap(); 59 axum::serve(listener, app()).await.unwrap(); 60 } ``` `POST /notes` with `{"title":" "}` returns `400` and `{"error":"title must not be empty"}`; with `{"title":"c"}` it returns `201` and `{"id":1,"title":"c","done":false}`. The `.into_response()` calls are needed because the two arms return different concrete types; both are unified to the `Response` type that `impl IntoResponse` promises. For richer rule-based validation across many fields, see [Validation](/16-web-apis/09-validation/). # Request Validation > Shape-correct isn't valid. Rust's validator crate plays the role of Zod: derive Validate, enforce business rules, and return a structured 422 on failure. In Express.js you reach for a library like Zod, Joi, or `express-validator` and wire it up as middleware that runs before your handler. Axum’s [extractors](/16-web-apis/04-extractors/) already guarantee a request *deserialized* into the right shape, but “shape-correct” is not the same as “valid”. This page covers the next layer: enforcing business rules (a name is 2-50 characters, an email is well-formed, an age is in range) and returning a `400`/`422` with a helpful, structured body when those rules are broken. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Deserialization answers “is this the right *type*?”; validation answers “is this *acceptable*?”. A JSON body can parse perfectly into a `CreateUser { name: String, age: u8 }` and still be garbage: an empty name, an email with no `@`, an age of `0`. In Rust the idiomatic tool is the **`validator`** crate, which adds a `#[derive(Validate)]` macro and field attributes (`length`, `email`, `range`, `custom`, `nested`) that feel a lot like Zod’s schema methods. You then call `.validate()` and translate any `ValidationErrors` into a clean JSON response. The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically. This page targets **axum 0.8** and **validator 0.20**. > **Note:** Axum returns **422 Unprocessable Entity** (not 400) when a JSON body has the right syntax but the wrong shape: e.g. a missing field. We follow the same convention for *semantic* validation failures, and reserve **400 Bad Request** for malformed input (broken JSON, wrong `Content-Type`). Both are perfectly valid choices; pick one and be consistent. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) A typical Express handler validates with Zod, then maps any error into a `400` with a per-field breakdown. ```typescript 1 // Express.js + Zod 2 import express, { Request, Response } from "express"; 3 import { z } from "zod"; 4 5 const app = express(); 6 app.use(express.json()); 7 8 const CreateUser = z.object({ 9 name: z.string().min(2).max(50), 10 email: z.string().email(), 11 age: z.number().int().min(18).max(120), 12 username: z.string().regex(/^[A-Za-z0-9_]+$/, "letters, numbers, underscores only"), 13 }); 14 15 type CreateUser = z.infer<typeof CreateUser>; 16 17 app.post("/users", (req: Request, res: Response) => { 18 const result = CreateUser.safeParse(req.body); 19 20 if (!result.success) { 21 // Map Zod issues into { field: [messages] } 22 const details: Record<string, string[]> = {}; 23 for (const issue of result.error.issues) { 24 const field = issue.path.join("."); 25 (details[field] ??= []).push(issue.message); 26 } 27 return res.status(400).json({ error: "validation failed", details }); 28 } 29 30 const user: CreateUser = result.data; // fully typed AND validated 31 res.status(201).json({ name: user.name }); 32 }); 33 34 app.listen(3000); ``` **Key points:** * The schema is a runtime value; `safeParse` either returns typed `data` or an `error` you inspect. * `z.infer` derives the static TypeScript type from the schema, so the type and the runtime checks stay in sync. * You manually walk `error.issues` to build a client-friendly response. There is no single canonical shape; every team invents its own. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The `validator` crate plays the role of Zod. You annotate the struct that your [`Json` extractor](/16-web-apis/04-extractors/) already produces, then call `.validate()`. Here we wrap both steps in a custom **`ValidatedJson<T>`** extractor so handlers stay clean. The request never reaches the handler body unless it parsed *and* validated. Add the dependencies in a new project: ```bash 1 cargo new user-api && cd user-api 2 cargo add axum 3 cargo add tokio --features full 4 cargo add serde --features derive 5 cargo add serde_json 6 cargo add validator --features derive ``` ```rust 1 use std::collections::HashMap; 2 3 use axum::{ 4 extract::{rejection::JsonRejection, FromRequest, Request}, 5 http::StatusCode, 6 response::{IntoResponse, Response}, 7 routing::post, 8 Json, Router, 9 }; 10 use serde::{de::DeserializeOwned, Deserialize, Serialize}; 11 use serde_json::json; 12 use validator::{Validate, ValidationError, ValidationErrors}; 13 14 #[derive(Debug, Deserialize, Validate)] 15 struct CreateUser { 16 #[validate(length(min = 2, max = 50, message = "name must be 2-50 characters"))] 17 name: String, 18 19 #[validate(email(message = "must be a valid email address"))] 20 email: String, 21 22 #[validate(range(min = 18, max = 120, message = "age must be between 18 and 120"))] 23 age: u8, 24 25 #[validate(custom(function = "validate_username"))] 26 username: String, 27 } 28 29 // A custom validator: takes &str, returns Result<(), ValidationError>. 30 fn validate_username(username: &str) -> Result<(), ValidationError> { 31 if username.chars().all(|c| c.is_ascii_alphanumeric() || c == '_') { 32 Ok(()) 33 } else { 34 let mut err = ValidationError::new("username_charset"); 35 err.message = Some("username may only contain letters, numbers, and underscores".into()); 36 Err(err) 37 } 38 } 39 40 // The JSON shape we return on failure: { "error": ..., "details": { field: [msgs] } } 41 #[derive(Serialize)] 42 struct ValidationProblem { 43 error: &'static str, 44 details: HashMap<String, Vec<String>>, 45 } 46 47 fn to_problem(errors: &ValidationErrors) -> ValidationProblem { 48 let mut details: HashMap<String, Vec<String>> = HashMap::new(); 49 for (field, errs) in errors.field_errors() { 50 let messages = errs 51 .iter() 52 .map(|e| { 53 // Prefer our human message; fall back to the machine code. 54 e.message 55 .as_ref() 56 .map(|m| m.to_string()) 57 .unwrap_or_else(|| e.code.to_string()) 58 }) 59 .collect(); 60 details.insert(field.to_string(), messages); 61 } 62 ValidationProblem { error: "validation failed", details } 63 } 64 65 // A reusable extractor: parse JSON, THEN validate, before the handler runs. 66 struct ValidatedJson<T>(T); 67 68 enum ApiError { 69 JsonRejection(JsonRejection), // bad/missing JSON -> 400/415/422 from axum 70 Validation(ValidationErrors), // shape OK, rules broken -> 422 71 } 72 73 impl<T, S> FromRequest<S> for ValidatedJson<T> 74 where 75 T: DeserializeOwned + Validate, 76 S: Send + Sync, 77 { 78 type Rejection = ApiError; 79 80 async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> { 81 let Json(value) = Json::<T>::from_request(req, state) 82 .await 83 .map_err(ApiError::JsonRejection)?; 84 value.validate().map_err(ApiError::Validation)?; 85 Ok(ValidatedJson(value)) 86 } 87 } 88 89 impl IntoResponse for ApiError { 90 fn into_response(self) -> Response { 91 match self { 92 ApiError::JsonRejection(rejection) => ( 93 rejection.status(), // axum picks 400 / 415 / 422 as appropriate 94 Json(json!({ "error": rejection.body_text() })), 95 ) 96 .into_response(), 97 ApiError::Validation(errors) => { 98 (StatusCode::UNPROCESSABLE_ENTITY, Json(to_problem(&errors))).into_response() 99 } 100 } 101 } 102 } 103 104 // Handlers receive already-valid data. No validation noise here. 105 async fn create_user(ValidatedJson(user): ValidatedJson<CreateUser>) -> impl IntoResponse { 106 (StatusCode::CREATED, Json(json!({ "name": user.name }))) 107 } 108 109 fn app() -> Router { 110 Router::new().route("/users", post(create_user)) 111 } 112 113 #[tokio::main] 114 async fn main() { 115 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000") 116 .await 117 .unwrap(); 118 println!("listening on http://{}", listener.local_addr().unwrap()); 119 axum::serve(listener, app()).await.unwrap(); 120 } ``` Sending an invalid body returns a real `422` with a per-field breakdown. Hitting the running server confirms it: ```bash 1 curl -s -i -X POST http://127.0.0.1:3000/users \ 2 -H 'content-type: application/json' \ 3 -d '{"name":"x","email":"nope","age":9,"username":"bad name!"}' ``` The verified response status and body (captured from an end-to-end request against the server above): ```text 1 STATUS 422 Unprocessable Entity 2 { 3 "details": { 4 "age": [ 5 "age must be between 18 and 120" 6 ], 7 "email": [ 8 "must be a valid email address" 9 ], 10 "name": [ 11 "name must be 2-50 characters" 12 ], 13 "username": [ 14 "username may only contain letters, numbers, and underscores" 15 ] 16 }, 17 "error": "validation failed" 18 } ``` A valid body sails through to the handler: ```text 1 STATUS 201 Created 2 {"name":"Ada Lovelace"} ``` *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) **The attributes mirror Zod methods.** Each `#[validate(...)]` declares one rule on one field: | validator attribute | Zod equivalent | Checks | | ----------------------------- | ------------------------- | ------------------------ | | `length(min = 2, max = 50)` | `.min(2).max(50)` | string/collection length | | `email` | `.email()` | HTML5-style email shape | | `range(min = 18, max = 120)` | `.int().min(18).max(120)` | numeric bounds | | `url` | `.url()` | parseable URL | | `must_match(other = "field")` | `.refine(...)` | two fields are equal | | `contains(pattern = "x")` | `.includes("x")` | substring present | | `custom(function = "fn")` | `.refine(fn, msg)` | arbitrary logic | | `nested` | nested `z.object` | validates a child struct | | `required` | non-optional field | `Option` is `Some` | **`#[validate(custom(function = "validate_username"))]`** points at a free function with the exact signature `fn(&T) -> Result<(), ValidationError>`. Returning `Err(ValidationError::new("code"))` records a failure; setting `.message` gives the client a human-readable string. This is where any rule the built-in attributes can’t express lives (checking a value against a database, cross-field math, format rules). > **Warning:** The custom-function syntax changed in newer `validator` releases. The current form is `custom(function = "name")`. The older `custom = "name"` no longer compiles — see [Common Pitfalls](#common-pitfalls). **`value.validate()`** comes from the `Validate` trait that `#[derive(Validate)]` implements. It returns `Result<(), ValidationErrors>`. On success you have a value you *know* is valid; on failure you get a structured `ValidationErrors`. **`errors.field_errors()`** returns a map of field name to a slice of `ValidationError`. Each `ValidationError` carries a machine `code` (`"length"`, `"email"`, `"range"`, or your custom code) and an optional human `message`. We prefer the message and fall back to the code, then collect into `{ field: [messages] }`: exactly the shape the Zod example produced. Standardizing this in one `to_problem` helper means every endpoint returns identical-looking errors. **The `ValidatedJson<T>` extractor** is the real payoff. By implementing [`FromRequest`](/16-web-apis/04-extractors/) for it, we run *parse-then-validate* before the handler. A handler signature of `ValidatedJson(user): ValidatedJson<CreateUser>` is a compile-time promise that `user` is valid: the type system carries the guarantee, so handler bodies never re-check. This is closer to what Zod gives TypeScript than scattered `if` statements, and it composes with every route. **`JsonRejection` vs `ValidationErrors`.** These are two genuinely different failure modes. `JsonRejection` fires when the bytes are not valid JSON, a required field is missing, a field has the wrong type, or the `Content-Type` header is wrong. Axum already produced a sensible status (400, 415, or 422) and message, so we forward `rejection.status()` and `rejection.body_text()`. `ValidationErrors` fires only after a *successful* parse, so it is always our `422`. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript (Zod) | Rust (validator) | | ---------------------- | ------------------------------------------ | ------------------------------------------------------ | | Schema location | A runtime value (`z.object({...})`) | Attributes on a compile-time `struct` | | Type ↔ rules sync | `z.infer` derives the type from the schema | The struct *is* the type; attributes annotate it | | Run validation | `schema.safeParse(data)` | `data.validate()` | | Result on failure | `error.issues[]` | `ValidationErrors` (map of field -> errors) | | Custom rule | `.refine(fn, msg)` | `fn(&T) -> Result<(), ValidationError>` | | Where it runs | Middleware or top of handler | A reusable `FromRequest` extractor | | Default failure status | Whatever you write (often 400) | You choose; 422 is idiomatic for shape/semantic errors | **The schema is the type, not a separate object.** In Zod the schema is a value you can compose, pass around, and `.partial()`. In Rust the *struct* is the source of truth and validation rules are attributes baked onto it at compile time. You cannot build a validator dynamically at runtime the way you compose Zod schemas — but you also cannot accidentally let the type and the rules drift apart, because there is only one declaration. **Validation is opt-in and explicit.** Deriving `Validate` does nothing on its own; *something* must call `.validate()`. There is no “this struct is automatically validated whenever it’s deserialized.” The `ValidatedJson<T>` extractor is how you make that automatic at the boundary: a deliberate seam, unlike a Zod schema that only validates where you remember to call it. **Parsing and validating are separate phases.** Serde gives you a well-typed value or a parse error; `validator` then judges that value. In Zod both happen in one `safeParse` call. Keeping them separate is why a malformed body and a business-rule violation can return different statuses with almost no extra code. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Using the old `custom = "..."` syntax [Section titled “Using the old custom = "..." syntax”](#using-the-old-custom---syntax) Older tutorials and `validator` versions used `#[validate(custom = "fn_name")]`. In validator 0.20 that is a hard compile error. This snippet does **not** compile: ```rust 1 use serde::Deserialize; 2 use validator::{Validate, ValidationError}; 3 4 #[derive(Deserialize, Validate)] 5 struct Form { 6 #[validate(custom = "validate_username")] // does not compile (Unexpected type `string`) 7 username: String, 8 } 9 10 fn validate_username(_: &str) -> Result<(), ValidationError> { Ok(()) } 11 fn main() {} ``` The real compiler error is: ```text 1 error: Unexpected type `string` 2 --> src/main.rs:6:25 3 | 4 6 | #[validate(custom = "validate_username")] 5 | ^^^^^^^^^^^^^^^^^^^^ ``` Use `custom(function = "validate_username")` instead. The function name is still a string literal, but it must sit inside `function = ...`. ### Deriving `Validate` but never calling `.validate()` [Section titled “Deriving Validate but never calling .validate()”](#deriving-validate-but-never-calling-validate) ```rust 1 #[derive(serde::Deserialize, validator::Validate)] 2 struct CreateUser { 3 #[validate(email)] 4 email: String, 5 } 6 7 // A plain `Json<CreateUser>` parses but is NEVER validated: 8 async fn handler(axum::Json(_user): axum::Json<CreateUser>) { 9 // `email` could be "not-an-email" here. The derive did nothing on its own. 10 } ``` This compiles and runs, accepting invalid emails. The derive only *generates* a `validate` method — nothing calls it for you. Use a `ValidatedJson<T>` extractor (as above) or call `user.validate()?` at the top of the handler. There is no runtime warning; the bug is silent, which is exactly why the extractor pattern is worth the boilerplate. ### Returning the raw `ValidationErrors` debug output to clients [Section titled “Returning the raw ValidationErrors debug output to clients”](#returning-the-raw-validationerrors-debug-output-to-clients) `ValidationErrors` implements `Serialize`, so it is tempting to do `Json(errors)`. But its serialized form leaks internal `code`/`params` details and, for nested structs, a deeply nested object that is awkward to consume: ```text 1 { 2 "quantity": [ 3 { 4 "code": "range", 5 "message": "quantity must be at least 1", 6 "params": { "min": 1, "value": 0 } 7 } 8 ], 9 "shipping": { 10 "country": [ 11 { 12 "code": "length", 13 "message": "country must be a 2-letter code", 14 "params": { "value": "USA", "equal": 2 } 15 } 16 ] 17 } 18 } ``` (That output is real — it comes from serializing a `ValidationErrors` for a struct using `#[validate(nested)]`.) It exposes implementation details and an unstable shape. Map it through a small DTO like `ValidationProblem` so the client contract is *yours*, not the crate’s. ### Confusing a parse failure with a validation failure [Section titled “Confusing a parse failure with a validation failure”](#confusing-a-parse-failure-with-a-validation-failure) A request like `{"name":"Ada Lovelace","email":"ada@example.com"}` (missing `age`) never reaches `.validate()`; serde rejects it first. Against the server above it returns: ```text 1 STATUS 422 Unprocessable Entity 2 {"error":"Failed to deserialize the JSON body into the target type: missing field `age` at line 1 column 49"} ``` And a request with no JSON `Content-Type` is rejected even earlier: ```text 1 STATUS 415 Unsupported Media Type 2 {"error":"Expected request with `Content-Type: application/json`"} ``` If you only handle `ValidationErrors`, these cases fall through to a generic `500`. Handle the `JsonRejection` arm too (the `ApiError` enum above does), or wire a centralized error type; see [Error Handling in Web Handlers](/16-web-apis/10-error-handling-web/). ### Forgetting `#[validate(nested)]` on a child struct [Section titled “Forgetting #\[validate(nested)\] on a child struct”](#forgetting-validatenested-on-a-child-struct) If `Order` contains `shipping: Address` and you omit `#[validate(nested)]` on that field, `order.validate()` checks the `Order`’s own fields but silently skips the `Address`. It compiles and passes invalid children. Always annotate sub-structs you want recursively validated. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Validate at the boundary, once.** A single `ValidatedJson<T>` (or `ValidatedQuery<T>`) extractor means handlers receive types that are *provably* valid. Don’t re-validate deeper in the call stack. * **Own your error contract.** Map `ValidationErrors` into a stable DTO (`{ "error": ..., "details": { field: [msg] } }`). Document it. Clients and your frontend depend on its shape far more than on any single endpoint. * **Write helpful `message`s.** A bare `code` like `"length"` tells the user nothing. `"name must be 2-50 characters"` does. Set `message = "..."` on every attribute, and on custom errors. * **Pick a status and stick to it.** `422 Unprocessable Entity` for semantic/shape failures, `400 Bad Request` for malformed input, `415 Unsupported Media Type` for the wrong content type. Consistency beats cleverness. * **Reach for the validator crate before hand-rolling.** Manual `if` checks (shown below) are fine for one or two fields, but they don’t compose, don’t standardize messages, and grow into a swamp. Use `validator` for anything beyond trivial. * **Keep custom validators pure and synchronous.** `validator`’s `custom` functions are not async and shouldn’t touch a database. Do async checks (uniqueness, existence) in the handler after structural validation passes; see [JSON REST APIs](/16-web-apis/08-json-apis/) and [Database](/17-database/). * **Trim/normalize before validating** when needed (e.g. lowercasing an email) so `" Ada@Example.com "` and `"ada@example.com"` are treated the same. ### When manual validation is enough [Section titled “When manual validation is enough”](#when-manual-validation-is-enough) For a tiny payload you don’t need a crate at all. A function returning `Result<(), Vec<String>>` keeps full control: ```rust 1 use axum::{http::StatusCode, response::{IntoResponse, Response}, Json}; 2 use serde::Deserialize; 3 use serde_json::json; 4 5 #[derive(Deserialize)] 6 struct Signup { 7 email: String, 8 password: String, 9 } 10 11 fn validate_signup(input: &Signup) -> Result<(), Vec<String>> { 12 let mut errors = Vec::new(); 13 if !input.email.contains('@') { 14 errors.push("email must contain @".to_string()); 15 } 16 if input.password.len() < 8 { 17 errors.push("password must be at least 8 characters".to_string()); 18 } 19 if errors.is_empty() { Ok(()) } else { Err(errors) } 20 } 21 22 async fn signup(Json(input): Json<Signup>) -> Response { 23 match validate_signup(&input) { 24 Ok(()) => (StatusCode::CREATED, Json(json!({ "ok": true }))).into_response(), 25 Err(errors) => ( 26 StatusCode::UNPROCESSABLE_ENTITY, 27 Json(json!({ "error": "validation failed", "details": errors })), 28 ) 29 .into_response(), 30 } 31 } ``` > **Tip:** Collect *all* errors and return them together (as above), rather than bailing on the first one. Returning one error at a time forces the client into a frustrating round-trip-per-mistake loop; both Zod and the `validator` crate return the full set by default. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A registration endpoint with realistic rules: name length, a valid email, a password of at least 8 characters that must match a confirmation field, and a custom check that the username has an allowed charset. It uses the `ValidatedJson<T>` extractor so the handler body is pure business logic. ```rust 1 use std::collections::HashMap; 2 3 use axum::{ 4 extract::{rejection::JsonRejection, FromRequest, Request}, 5 http::StatusCode, 6 response::{IntoResponse, Response}, 7 routing::post, 8 Json, Router, 9 }; 10 use serde::{de::DeserializeOwned, Deserialize, Serialize}; 11 use serde_json::json; 12 use validator::{Validate, ValidationError, ValidationErrors}; 13 14 #[derive(Debug, Deserialize, Validate)] 15 struct Register { 16 #[validate(length(min = 2, max = 50, message = "name must be 2-50 characters"))] 17 name: String, 18 19 #[validate(email(message = "must be a valid email address"))] 20 email: String, 21 22 #[validate(custom(function = "validate_username"))] 23 username: String, 24 25 #[validate(length(min = 8, message = "password must be at least 8 characters"))] 26 password: String, 27 28 #[validate(must_match(other = "password", message = "passwords do not match"))] 29 password_confirm: String, 30 } 31 32 fn validate_username(username: &str) -> Result<(), ValidationError> { 33 let ok = !username.is_empty() 34 && username.chars().all(|c| c.is_ascii_alphanumeric() || c == '_'); 35 if ok { 36 Ok(()) 37 } else { 38 let mut err = ValidationError::new("username_charset"); 39 err.message = Some("username may only contain letters, numbers, and underscores".into()); 40 Err(err) 41 } 42 } 43 44 #[derive(Serialize)] 45 struct ValidationProblem { 46 error: &'static str, 47 details: HashMap<String, Vec<String>>, 48 } 49 50 fn to_problem(errors: &ValidationErrors) -> ValidationProblem { 51 let mut details: HashMap<String, Vec<String>> = HashMap::new(); 52 for (field, errs) in errors.field_errors() { 53 let messages = errs 54 .iter() 55 .map(|e| { 56 e.message 57 .as_ref() 58 .map(|m| m.to_string()) 59 .unwrap_or_else(|| e.code.to_string()) 60 }) 61 .collect(); 62 details.insert(field.to_string(), messages); 63 } 64 ValidationProblem { error: "validation failed", details } 65 } 66 67 struct ValidatedJson<T>(T); 68 69 enum ApiError { 70 JsonRejection(JsonRejection), 71 Validation(ValidationErrors), 72 } 73 74 impl<T, S> FromRequest<S> for ValidatedJson<T> 75 where 76 T: DeserializeOwned + Validate, 77 S: Send + Sync, 78 { 79 type Rejection = ApiError; 80 81 async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> { 82 let Json(value) = Json::<T>::from_request(req, state) 83 .await 84 .map_err(ApiError::JsonRejection)?; 85 value.validate().map_err(ApiError::Validation)?; 86 Ok(ValidatedJson(value)) 87 } 88 } 89 90 impl IntoResponse for ApiError { 91 fn into_response(self) -> Response { 92 match self { 93 ApiError::JsonRejection(rejection) => ( 94 rejection.status(), 95 Json(json!({ "error": rejection.body_text() })), 96 ) 97 .into_response(), 98 ApiError::Validation(errors) => { 99 (StatusCode::UNPROCESSABLE_ENTITY, Json(to_problem(&errors))).into_response() 100 } 101 } 102 } 103 } 104 105 async fn register(ValidatedJson(input): ValidatedJson<Register>) -> impl IntoResponse { 106 // Reached only when every rule passed. In a real app, async checks 107 // (is the email already taken?) and the INSERT happen here. 108 ( 109 StatusCode::CREATED, 110 Json(json!({ "username": input.username, "email": input.email })), 111 ) 112 } 113 114 fn app() -> Router { 115 Router::new().route("/register", post(register)) 116 } 117 118 #[tokio::main] 119 async fn main() { 120 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000") 121 .await 122 .unwrap(); 123 println!("listening on http://{}", listener.local_addr().unwrap()); 124 axum::serve(listener, app()).await.unwrap(); 125 } ``` A mismatched-password request: ```bash 1 curl -s -X POST http://127.0.0.1:3000/register \ 2 -H 'content-type: application/json' \ 3 -d '{"name":"Ada","email":"ada@example.com","username":"ada_l","password":"hunter22","password_confirm":"hunter99"}' ``` returns `422` with `{"error":"validation failed","details":{"password_confirm":["passwords do not match"]}}`, while a fully-valid body returns `201` with the created user. The handler itself contains zero validation code. That is the goal. > **Note:** `must_match` compares `password_confirm` against `password`, and the failure is reported on `password_confirm`. Order your fields so the confirmation comes after the original. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`validator` crate docs](https://docs.rs/validator/latest/validator/) — the full attribute list, `Validate` trait, and `ValidationErrors` structure. * [`validator` derive attributes](https://docs.rs/validator/latest/validator/derive.Validate.html) — exact syntax for `length`, `range`, `email`, `must_match`, `custom`, `nested`, and more. * [axum `JsonRejection`](https://docs.rs/axum/latest/axum/extract/rejection/enum.JsonRejection.html) — every way a `Json` extractor can fail and the status each produces. * [HTTP 422 Unprocessable Content (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422) — when to use 422 vs 400. Within this guide: * [Extractors](/16-web-apis/04-extractors/) — `FromRequest`/`FromRequestParts`, how `Json` parses, and the extractor pattern `ValidatedJson<T>` builds on. * [Request and Response Handling](/16-web-apis/07-request-response/) — `IntoResponse`, `(StatusCode, Json)` tuples, and setting status codes. * [JSON REST APIs](/16-web-apis/08-json-apis/) — a full CRUD resource; where validated input gets persisted. * [Error Handling in Web Handlers](/16-web-apis/10-error-handling-web/) — folding validation, parse, and database failures into one `AppError` with `thiserror`. * [Middleware and Layers](/16-web-apis/05-middleware/) — when a tower layer is a better home for cross-cutting concerns than per-handler logic. * Foundations: [error handling](/08-error-handling/) (`Result`, `?`), [serialization](/15-serialization/) (serde derive that powers parsing), the language [basics](/02-basics/), and [getting started](/01-getting-started/) / [introduction](/00-introduction/). * Persisting validated data and doing async uniqueness checks: [Database](/17-database/). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Validate a query string [Section titled “Exercise 1: Validate a query string”](#exercise-1-validate-a-query-string) **Difficulty:** Beginner **Objective:** Apply `#[derive(Validate)]` to a pagination struct and reject out-of-range values. **Instructions:** Define a `Pagination { page: u32, per_page: u32 }` struct. Require `page >= 1` and `per_page` between `1` and `100` using `range`. Write a function `check(p: &Pagination) -> Result<(), validator::ValidationErrors>` that validates it. Test it against `{ page: 0, per_page: 500 }` and confirm both fields fail. Solution ```rust 1 use validator::{Validate, ValidationErrors}; 2 3 #[derive(Debug, Validate)] 4 struct Pagination { 5 #[validate(range(min = 1, message = "page must be at least 1"))] 6 page: u32, 7 #[validate(range(min = 1, max = 100, message = "per_page must be 1-100"))] 8 per_page: u32, 9 } 10 11 fn check(p: &Pagination) -> Result<(), ValidationErrors> { 12 p.validate() 13 } 14 15 fn main() { 16 let bad = Pagination { page: 0, per_page: 500 }; 17 match check(&bad) { 18 Ok(()) => println!("valid"), 19 Err(e) => { 20 for (field, errs) in e.field_errors() { 21 for err in errs { 22 let msg = err 23 .message 24 .as_ref() 25 .map(|m| m.to_string()) 26 .unwrap_or_else(|| err.code.to_string()); 27 println!("{field}: {msg}"); 28 } 29 } 30 } 31 } 32 } ``` Running it prints (field order may vary): ```text 1 page: page must be at least 1 2 per_page: per_page must be 1-100 ``` ### Exercise 2: A custom cross-field validator [Section titled “Exercise 2: A custom cross-field validator”](#exercise-2-a-custom-cross-field-validator) **Difficulty:** Intermediate **Objective:** Use a struct-level custom validator to enforce a rule spanning two fields. **Instructions:** Define a `DateRange { start: u32, end: u32 }` (days since epoch, say). The built-in attributes can’t express “end must be after start”, so write a struct-level validator. Apply `#[validate(schema(function = "validate_range"))]` to the struct and implement `validate_range(value: &DateRange) -> Result<(), ValidationError>`. Reject `{ start: 10, end: 5 }`. Solution ```rust 1 use validator::{Validate, ValidationError}; 2 3 #[derive(Debug, Validate)] 4 #[validate(schema(function = "validate_range"))] 5 struct DateRange { 6 start: u32, 7 end: u32, 8 } 9 10 fn validate_range(range: &DateRange) -> Result<(), ValidationError> { 11 if range.end > range.start { 12 Ok(()) 13 } else { 14 let mut err = ValidationError::new("date_order"); 15 err.message = Some("end must be after start".into()); 16 Err(err) 17 } 18 } 19 20 fn main() { 21 let bad = DateRange { start: 10, end: 5 }; 22 match bad.validate() { 23 Ok(()) => println!("valid"), 24 Err(e) => println!("invalid: {e}"), 25 } 26 27 let good = DateRange { start: 5, end: 10 }; 28 println!("good is_ok: {}", good.validate().is_ok()); 29 } ``` Running it prints: ```text 1 invalid: __all__: end must be after start 2 good is_ok: true ``` Struct-level errors are recorded under the special `__all__` key; map that to a top-level message in your API response rather than to a single field. ### Exercise 3: A `ValidatedJson<T>` extractor with a clean error body [Section titled “Exercise 3: A ValidatedJson\<T> extractor with a clean error body”](#exercise-3-a-validatedjsont-extractor-with-a-clean-error-body) **Difficulty:** Advanced **Objective:** Build the reusable extractor end-to-end and prove it returns a `422` with a per-field map. **Instructions:** Define `ValidatedJson<T>` implementing `FromRequest` (parse with `Json::<T>::from_request`, then `.validate()`). On a `ValidationErrors`, respond `422` with body `{ "error": "validation failed", "details": { field: [messages] } }`; on a `JsonRejection`, forward its status and text. Wire it to a `POST /products` route taking a `Product { name (1-100 chars), price (range 1..=1_000_000) }`, run the server, and POST an invalid product to confirm the response. Solution Dependencies: `cargo add axum tokio --features tokio/full`, then `cargo add serde --features derive`, `cargo add serde_json`, `cargo add validator --features derive`. ```rust 1 use std::collections::HashMap; 2 3 use axum::{ 4 extract::{rejection::JsonRejection, FromRequest, Request}, 5 http::StatusCode, 6 response::{IntoResponse, Response}, 7 routing::post, 8 Json, Router, 9 }; 10 use serde::{de::DeserializeOwned, Deserialize, Serialize}; 11 use serde_json::json; 12 use validator::{Validate, ValidationErrors}; 13 14 #[derive(Debug, Deserialize, Validate)] 15 struct Product { 16 #[validate(length(min = 1, max = 100, message = "name must be 1-100 characters"))] 17 name: String, 18 #[validate(range(min = 1, max = 1_000_000, message = "price must be 1-1000000"))] 19 price: u32, 20 } 21 22 #[derive(Serialize)] 23 struct ValidationProblem { 24 error: &'static str, 25 details: HashMap<String, Vec<String>>, 26 } 27 28 fn to_problem(errors: &ValidationErrors) -> ValidationProblem { 29 let mut details = HashMap::new(); 30 for (field, errs) in errors.field_errors() { 31 let messages = errs 32 .iter() 33 .map(|e| { 34 e.message 35 .as_ref() 36 .map(|m| m.to_string()) 37 .unwrap_or_else(|| e.code.to_string()) 38 }) 39 .collect(); 40 details.insert(field.to_string(), messages); 41 } 42 ValidationProblem { error: "validation failed", details } 43 } 44 45 struct ValidatedJson<T>(T); 46 47 enum ApiError { 48 JsonRejection(JsonRejection), 49 Validation(ValidationErrors), 50 } 51 52 impl<T, S> FromRequest<S> for ValidatedJson<T> 53 where 54 T: DeserializeOwned + Validate, 55 S: Send + Sync, 56 { 57 type Rejection = ApiError; 58 59 async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> { 60 let Json(value) = Json::<T>::from_request(req, state) 61 .await 62 .map_err(ApiError::JsonRejection)?; 63 value.validate().map_err(ApiError::Validation)?; 64 Ok(ValidatedJson(value)) 65 } 66 } 67 68 impl IntoResponse for ApiError { 69 fn into_response(self) -> Response { 70 match self { 71 ApiError::JsonRejection(r) => { 72 (r.status(), Json(json!({ "error": r.body_text() }))).into_response() 73 } 74 ApiError::Validation(errors) => { 75 (StatusCode::UNPROCESSABLE_ENTITY, Json(to_problem(&errors))).into_response() 76 } 77 } 78 } 79 } 80 81 async fn create_product(ValidatedJson(p): ValidatedJson<Product>) -> impl IntoResponse { 82 (StatusCode::CREATED, Json(json!({ "name": p.name, "price": p.price }))) 83 } 84 85 #[tokio::main] 86 async fn main() { 87 let app = Router::new().route("/products", post(create_product)); 88 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000") 89 .await 90 .unwrap(); 91 axum::serve(listener, app).await.unwrap(); 92 } ``` Posting `{"name":"","price":0}`: ```bash 1 curl -s -i -X POST http://127.0.0.1:3000/products \ 2 -H 'content-type: application/json' -d '{"name":"","price":0}' ``` returns `422 Unprocessable Entity` with `{"error":"validation failed","details":{"name":["name must be 1-100 characters"],"price":["price must be 1-1000000"]}}`, while a valid product returns `201 Created`. # Error Handling in Web Handlers > Instead of Express try/catch and four-arg error middleware, an Axum handler returns Result and one IntoResponse impl maps each error to a status. In Express.js, an error usually means an `try/catch` that calls `res.status(500).json(...)`, or a thrown error that lands in a four-argument error middleware. Axum takes a different route: a handler simply *returns* `Result<T, AppError>`, and you teach the framework (once) how to turn `AppError` into an HTTP response. This chapter builds a production-grade error type with `thiserror`, wires it to Axum’s `IntoResponse` trait, and maps every error variant to the right status code. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In a Rust web app you do not throw exceptions and you do not pepper handlers with `try/catch`. Instead you define **one application error type** (an `enum`), implement the `IntoResponse` trait for it so Axum knows the status code and JSON body to send, and let the `?` operator propagate failures out of handlers automatically. The payoff is that error handling becomes part of the type system: a handler’s signature tells you exactly what can go wrong, and you cannot forget to handle an error path because the compiler will not let you. The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically. This page targets **axum 0.8**, **thiserror 2**, and **anyhow 1**. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Here is the way most Express APIs handle errors: a custom error class carrying a status code, `try/catch` in async handlers, and a centralized error-handling middleware as a backstop. ```typescript 1 // errors.ts — a custom error class with an HTTP status 2 export class ApiError extends Error { 3 constructor( 4 public status: number, 5 message: string, 6 public code: string, 7 ) { 8 super(message); 9 this.name = "ApiError"; 10 } 11 12 static notFound(what: string) { 13 return new ApiError(404, `${what} was not found`, "not_found"); 14 } 15 16 static validation(message: string) { 17 return new ApiError(422, message, "validation"); 18 } 19 20 static unauthorized() { 21 return new ApiError(401, "you are not authorized to do that", "unauthorized"); 22 } 23 } ``` ```typescript 1 // app.ts — handlers throw, middleware catches 2 import express, { Request, Response, NextFunction } from "express"; 3 import { ApiError } from "./errors"; 4 5 const app = express(); 6 app.use(express.json()); 7 8 const users = new Map<number, string>([[1, "Alice"]]); 9 10 app.get("/users/:id", (req: Request, res: Response, next: NextFunction) => { 11 try { 12 const id = Number(req.params.id); 13 const name = users.get(id); 14 if (name === undefined) { 15 throw ApiError.notFound(`user ${id}`); // jumps to the error middleware 16 } 17 res.json({ id, name }); 18 } catch (err) { 19 next(err); // hand off to the centralized handler 20 } 21 }); 22 23 // Centralized error-handling middleware: MUST have 4 args, registered LAST. 24 app.use((err: unknown, _req: Request, res: Response, _next: NextFunction) => { 25 if (err instanceof ApiError) { 26 res.status(err.status).json({ error: err.message, code: err.code }); 27 } else { 28 console.error("unhandled error:", err); // log the real thing 29 res.status(500).json({ error: "internal server error" }); // hide details 30 } 31 }); 32 33 app.listen(3000); ``` **Key points and pain points:** * Every async handler needs `try/catch` + `next(err)`, or a thrown error silently hangs the request (in classic Express without `express-async-errors`). * The error middleware is identified *only* by its arity (four parameters). Forget one and Express treats it as a normal middleware, a notorious footgun. * Nothing in a handler’s type signature tells you which errors it can produce; you discover them at runtime. * It is easy to accidentally leak an internal error’s `message` to the client. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Axum’s model: a handler returns `Result<T, AppError>`, the `?` operator replaces `try/catch`, and one `impl IntoResponse for AppError` replaces the error middleware. Set up the dependencies first: ```bash 1 cargo new my-api 2 cd my-api 3 cargo add axum@0.8 4 cargo add tokio@1 --features full 5 cargo add serde --features derive 6 cargo add serde_json 7 cargo add thiserror@2 8 cargo add tracing ``` ```rust 1 // src/main.rs — the same API in Axum, with a typed error 2 use axum::{ 3 extract::{Path, State}, 4 http::StatusCode, 5 response::{IntoResponse, Response}, 6 routing::get, 7 Json, Router, 8 }; 9 use serde::Serialize; 10 use serde_json::json; 11 use std::{collections::HashMap, sync::Arc}; 12 use tokio::sync::RwLock; 13 14 // The application's single error type. `thiserror` derives `Display` + `Error` 15 // from the `#[error("...")]` messages, so we never hand-write a match for them. 16 #[derive(Debug, thiserror::Error)] 17 enum AppError { 18 #[error("user {0} was not found")] 19 NotFound(u64), 20 21 #[error("invalid input: {0}")] 22 Validation(String), 23 24 #[error("you are not authorized to do that")] 25 Unauthorized, 26 27 // `#[from]` lets `?` turn a serde_json::Error into AppError automatically. 28 #[error("failed to (de)serialize JSON")] 29 Json(#[from] serde_json::Error), 30 31 // A catch-all for unexpected failures. We never leak the inner message. 32 #[error("internal server error")] 33 Internal(#[source] Box<dyn std::error::Error + Send + Sync>), 34 } 35 36 // The shape every error sends back to the client. 37 #[derive(Serialize)] 38 struct ErrorBody { 39 error: String, 40 } 41 42 // THIS is the bridge: it teaches Axum how to turn an AppError into an HTTP 43 // response. Each variant chooses its own status code. 44 impl IntoResponse for AppError { 45 fn into_response(self) -> Response { 46 let status = match &self { 47 AppError::NotFound(_) => StatusCode::NOT_FOUND, 48 AppError::Validation(_) => StatusCode::UNPROCESSABLE_ENTITY, 49 AppError::Unauthorized => StatusCode::UNAUTHORIZED, 50 AppError::Json(_) => StatusCode::BAD_REQUEST, 51 AppError::Internal(_) => StatusCode::INTERNAL_SERVER_ERROR, 52 }; 53 54 // Log the *full* error server-side (5xx especially), but only send a 55 // safe, public message to the client. 56 if status.is_server_error() { 57 tracing::error!(error = ?self, "request failed"); 58 } 59 60 let body = Json(ErrorBody { 61 error: self.to_string(), 62 }); 63 (status, body).into_response() 64 } 65 } 66 67 type Db = Arc<RwLock<HashMap<u64, String>>>; 68 69 // Handlers return `Result<T, AppError>`. `T: IntoResponse` for the success arm, 70 // `AppError: IntoResponse` for the failure arm — Axum responds to either. 71 async fn get_user( 72 State(db): State<Db>, 73 Path(id): Path<u64>, 74 ) -> Result<Json<serde_json::Value>, AppError> { 75 let users = db.read().await; 76 let name = users.get(&id).ok_or(AppError::NotFound(id))?; 77 Ok(Json(json!({ "id": id, "name": name }))) 78 } 79 80 async fn risky(Path(n): Path<i64>) -> Result<String, AppError> { 81 if n < 0 { 82 return Err(AppError::Validation("n must be >= 0".into())); 83 } 84 // `?` converts serde_json::Error into AppError::Json via the `#[from]` impl. 85 let parsed: i64 = serde_json::from_str("not a number")?; 86 Ok(parsed.to_string()) 87 } 88 89 async fn secret() -> Result<String, AppError> { 90 Err(AppError::Unauthorized) 91 } 92 93 #[tokio::main] 94 async fn main() { 95 let db: Db = Arc::new(RwLock::new(HashMap::from([(1, "Alice".to_string())]))); 96 97 let app = Router::new() 98 .route("/users/{id}", get(get_user)) 99 .route("/risky/{n}", get(risky)) 100 .route("/secret", get(secret)) 101 .with_state(db); 102 103 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 104 axum::serve(listener, app).await.unwrap(); 105 } ``` Running this server and hitting each route produces the following **real** responses (captured with `curl -w "\nHTTP %{http_code}\n"`): ```text 1 $ curl -s http://127.0.0.1:3000/users/1 2 {"id":1,"name":"Alice"} # HTTP 200 3 4 $ curl -s http://127.0.0.1:3000/users/99 5 {"error":"user 99 was not found"} # HTTP 404 6 7 $ curl -s http://127.0.0.1:3000/risky/-5 8 {"error":"invalid input: n must be >= 0"} # HTTP 422 9 10 $ curl -s http://127.0.0.1:3000/risky/5 11 {"error":"failed to (de)serialize JSON"} # HTTP 400 12 13 $ curl -s http://127.0.0.1:3000/secret 14 {"error":"you are not authorized to do that"} # HTTP 401 ``` One enum, one `IntoResponse` impl, and every handler stays clean. There is no error middleware to register in the right order, and no way to forget the error path: if `get_user` did not handle the missing-user case, the `?` on `ok_or(...)` simply would not type-check. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `thiserror` derives the boilerplate [Section titled “thiserror derives the boilerplate”](#thiserror-derives-the-boilerplate) `thiserror` is the idiomatic crate for **library/application error enums**. The `#[derive(thiserror::Error)]` macro reads each variant’s `#[error("...")]` attribute and generates: * an `impl std::fmt::Display` whose output is the formatted message, and * an `impl std::error::Error` (including `source()` when you mark an inner field with `#[source]` or `#[from]`). The message strings support inline field interpolation: `#[error("user {0} was not found")]` pulls in the tuple field `.0`, just like `format!("user {0}", self.0)`. This is why `self.to_string()` in `into_response` produces the message you saw in the JSON. You write the message once; `thiserror` wires up `Display`, `Error`, and `source()` for free. It is *not* a decorator. It is a compile-time code generator that expands into plain trait impls. > **Note:** `thiserror` adds **zero runtime cost** and no dependency at runtime: it is a `proc-macro` that runs at compile time and disappears. Contrast this with extending an `Error` class in JavaScript, which is an ordinary runtime object. ### `IntoResponse` is the contract [Section titled “IntoResponse is the contract”](#intoresponse-is-the-contract) Axum can only respond with types that implement the `IntoResponse` trait. Many types already do: `String`, `&str`, `StatusCode`, `Json<T>`, and tuples like `(StatusCode, Json<T>)`. By implementing it for `AppError`, you make your error a first-class response. The `match &self` chooses a status code per variant; the success and failure arms of a handler’s `Result` are *both* converted through `IntoResponse`, which is why `Result<Json<...>, AppError>` works as a return type. > **Tip:** The `(StatusCode, Json<T>)` tuple is the workhorse here. Returning `(StatusCode::NOT_FOUND, Json(body)).into_response()` sets the status line and a JSON body in one expression. See [Request and Response](/16-web-apis/07-request-response/) for the full set of `IntoResponse` implementations. ### `?` replaces `try/catch` [Section titled “? replaces try/catch”](#-replaces-trycatch) The `?` operator is the engine of Rust error handling. When you write `users.get(&id).ok_or(AppError::NotFound(id))?`, the `?` says “if this is `Err`/`None`, return that error from the function now.” Because `serde_json::Error` has a `#[from]` conversion into `AppError::Json`, the line `serde_json::from_str("not a number")?` automatically wraps the underlying error. This is the moral equivalent of `throw`, but it is **explicit, local, and visible in the type signature**: you can see at the function boundary exactly what error a handler may emit. See [Section 08: Error Handling](/08-error-handling/) for the `?` operator and the `From`-based conversion mechanics in depth. ### Logging vs. leaking [Section titled “Logging vs. leaking”](#logging-vs-leaking) The branch `if status.is_server_error()` logs the *full* `Debug` representation of the error (including the `#[source]` chain) with `tracing::error!`, but the client only ever receives `self.to_string()`, the public `Display` message. For 5xx errors we deliberately send the generic `"internal server error"` so we never leak a database connection string or a stack-trace-like detail to the outside world. This mirrors the `console.error(err)` + `res.status(500).json({error:"internal server error"})` split in the Express example, but here it is enforced by which field each variant exposes. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concern | Express.js | Axum / Rust | | ------------------------ | --------------------------------------- | ----------------------------------------------- | | Signaling failure | `throw` an exception | `return Err(...)` / the `?` operator | | Error transport | thrown value bubbles up the call stack | `Result<T, E>` returned through the stack | | Central handling | 4-arg error middleware, registered last | one `impl IntoResponse for AppError` | | Status mapping | `err.status` field read at runtime | `match` on the variant, checked at compile time | | ”What can fail here?“ | invisible until runtime | visible in the function’s return type | | Forgetting an error path | silently 500s / hangs | does not compile | | Leaking internals | easy (`err.message` to client) | explicit: choose which field is public | | Cost of the machinery | exception unwinding | a tagged-union return value (no unwinding) | The deepest difference: in TypeScript, error handling is a *runtime convention* you can forget. In Rust, it is a *type-system obligation*. A function that returns `Result<T, AppError>` cannot be used without acknowledging the `Err` case, so a whole class of “forgot to handle that” bugs disappears. > **Note:** Unlike a thrown JavaScript exception that unwinds an arbitrary number of frames, `?` returns from exactly *one* function: the one it appears in. Errors travel up one `Result`-returning call at a time. This is more verbose than `throw`, but it is also why the control flow is obvious from the signatures. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Returning an error type that is not `IntoResponse` [Section titled “Pitfall 1: Returning an error type that is not IntoResponse”](#pitfall-1-returning-an-error-type-that-is-not-intoresponse) A handler may only return types Axum knows how to respond with. If your error does not implement `IntoResponse`, the handler is not a valid `Handler` and you get a confusing trait-bound error rather than a friendly “implement IntoResponse” message. ```rust 1 use axum::{routing::get, Router}; 2 3 // does not compile (error[E0277]): ParseIntError is not IntoResponse, 4 // so this fn does not satisfy the `Handler` trait. 5 async fn handler() -> Result<String, std::num::ParseIntError> { 6 let n: i32 = "x".parse()?; 7 Ok(n.to_string()) 8 } 9 10 fn main() { 11 let _app: Router = Router::new().route("/", get(handler)); 12 } ``` The real error from `cargo check` (axum 0.8.9, Rust 1.96.0) is: ```text 1 error[E0277]: the trait bound `fn() -> impl Future<Output = Result<String, ParseIntError>> {handler}: Handler<_, _>` is not satisfied 2 --> src/bin/pitfall.rs:11:53 3 | 4 11 | let _app: Router = Router::new().route("/", get(handler)); 5 | --- ^^^^^^^ the trait `Handler<_, _>` is not implemented for fn item ... 6 | | 7 | required by a bound introduced by this call 8 | 9 = note: Consider using `#[axum::debug_handler]` to improve the error message 10 note: required by a bound in `axum::routing::get` ``` > **Tip:** When you see “the trait `Handler<_, _>` is not implemented”, add `#[axum::debug_handler]` above the handler (it requires the `macros` feature) and recompile. It rewrites the error to point at the *exact* parameter or return type that is the problem. The fix here is to map `ParseIntError` into your `AppError` (give `AppError` a `#[from] ParseIntError` variant) so the handler returns `Result<String, AppError>`. ### Pitfall 2: Using `unwrap()`/`expect()` instead of returning an error [Section titled “Pitfall 2: Using unwrap()/expect() instead of returning an error”](#pitfall-2-using-unwrapexpect-instead-of-returning-an-error) ```rust 1 async fn get_user(id: u64) -> String { 2 let users = std::collections::HashMap::<u64, String>::new(); 3 users.get(&id).unwrap().clone() // panics if the user is missing 4 } ``` `unwrap()` on a missing key panics, which Axum/Tower catches and turns into a bare `500` with no body, and crashes that task. Always return `Err(AppError::NotFound(id))` via `?` instead. Reserve `unwrap()`/`expect()` for setup code (like `TcpListener::bind(...).await.unwrap()` in `main`) where a failure genuinely means the program cannot start. ### Pitfall 3: Forgetting that built-in extractor rejections are not your error type [Section titled “Pitfall 3: Forgetting that built-in extractor rejections are not your error type”](#pitfall-3-forgetting-that-built-in-extractor-rejections-are-not-your-error-type) Axum’s own extractors (`Path`, `Query`, `Json`) reject malformed input *before your handler runs*, and they reply with their **own** plain-text error, not your JSON shape. Requesting `/users/abc` against the example (where the route is `/users/{id}` with `Path<u64>`) returns this real response: ```text 1 $ curl -s http://127.0.0.1:3000/users/abc 2 Invalid URL: Cannot parse `abc` to a `u64` # HTTP 400, plain text ``` That is a `PathRejection`, not `AppError::NotFound`, so it does not go through your `IntoResponse`. If you want a *consistent* JSON error envelope across both your domain errors and extractor failures, wrap the extractor; see the Real-World example below. ### Pitfall 4: Leaking internal details in 5xx responses [Section titled “Pitfall 4: Leaking internal details in 5xx responses”](#pitfall-4-leaking-internal-details-in-5xx-responses) ```rust 1 // Anti-pattern: sends the raw error (maybe a DB DSN!) to the client. 2 AppError::Internal(e) => (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()), ``` Send a generic message to the client and log the detail server-side, as the working example does. This is a security practice, not just a style preference: internal error strings frequently contain file paths, SQL, or connection details. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **One error type per crate/service.** A single `AppError` enum that every handler returns keeps the response format uniform. Add a variant when you discover a new failure mode. * **`thiserror` for typed enums; `anyhow` for the catch-all.** Use `thiserror` when callers need to *match* on specific variants (the typical web-handler case). Use `anyhow` (or an `anyhow`-wrapping variant) for the “anything unexpected becomes a 500” path. The two compose well; see Exercise 3. * **Map status codes in the `match`, not at the throw site.** Keep the variant-to-status mapping in one `into_response` so it is easy to audit. * **Always log 5xx with the full source chain, return a generic message.** `tracing::error!(error = ?self, ...)` records the `Debug` (with `source()`); the client gets `Display`. * **Use `#[from]` to make `?` ergonomic.** Mark the most common foreign errors (`serde_json::Error`, your DB driver’s error, `std::io::Error`) with `#[from]` so handlers can `?` them directly. * **Initialize a `tracing` subscriber** so those `error!` logs actually appear. Add `cargo add tracing-subscriber --features env-filter` and call `tracing_subscriber::fmt::init();` at the top of `main`. See [Middleware and Layers](/16-web-apis/05-middleware/) for `TraceLayer`, which logs every request/response automatically. * **Pick semantically correct status codes.** `400 Bad Request` for syntactically malformed input, `422 Unprocessable Entity` for well-formed-but-invalid input, `404` for missing resources, `401`/`403` for auth, `409` for conflicts. The [Validation](/16-web-apis/09-validation/) chapter covers returning helpful 400/422 bodies. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production API wants **every** error — whether a domain error you raised or a malformed-JSON rejection from the `Json` extractor — to come back in the same JSON envelope. The clean way to do this in axum 0.8 is a custom extractor built with `#[derive(FromRequest)]` that reuses `Json` but routes its rejection through your `AppError`. This needs the `macros` feature: ```bash 1 cargo add axum@0.8 --features macros 2 cargo add thiserror@2 serde --features serde/derive 3 cargo add serde_json ``` ```rust 1 // src/main.rs — a uniform JSON error envelope for domain + extractor errors 2 use axum::{ 3 extract::{rejection::JsonRejection, FromRequest}, 4 response::{IntoResponse, Response}, 5 routing::post, 6 Json, Router, 7 }; 8 use serde::{Deserialize, Serialize}; 9 use serde_json::json; 10 11 #[derive(Debug, thiserror::Error)] 12 enum AppError { 13 // `#[from]` pulls in axum's own JsonRejection so we can reuse its status code. 14 #[error("invalid request body: {0}")] 15 Body(#[from] JsonRejection), 16 } 17 18 impl IntoResponse for AppError { 19 fn into_response(self) -> Response { 20 // axum's JsonRejection already knows the right code (400 vs 422 vs 415). 21 let status = match &self { 22 AppError::Body(rejection) => rejection.status(), 23 }; 24 (status, Json(json!({ "error": self.to_string() }))).into_response() 25 } 26 } 27 28 // A custom extractor: behaves exactly like `Json<T>`, but its rejection is OUR 29 // AppError, so malformed bodies come back in the same envelope as domain errors. 30 #[derive(FromRequest)] 31 #[from_request(via(Json), rejection(AppError))] 32 struct AppJson<T>(T); 33 34 #[derive(Deserialize, Serialize)] 35 struct NewUser { 36 name: String, 37 } 38 39 async fn create(AppJson(user): AppJson<NewUser>) -> Json<NewUser> { 40 // In a real handler you would persist `user`; here we echo it back. 41 Json(user) 42 } 43 44 #[tokio::main] 45 async fn main() { 46 let app: Router = Router::new().route("/users", post(create)); 47 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 48 axum::serve(listener, app).await.unwrap(); 49 } ``` Hitting `/users` with various bodies gives these **real** responses. Notice the status codes are chosen by axum’s `JsonRejection::status()`, and the body shape is always *ours*: ```text 1 $ curl -s -X POST /users -H 'content-type: application/json' -d '{"name":"Alice"}' 2 {"name":"Alice"} # HTTP 200 3 4 $ curl -s -X POST /users -H 'content-type: application/json' -d '{}' 5 {"error":"invalid request body: Failed to deserialize the JSON body into the target type: missing field `name` at line 1 column 2"} 6 # HTTP 422 7 8 $ curl -s -X POST /users -H 'content-type: application/json' -d '{not json' 9 {"error":"invalid request body: Failed to parse the request body as JSON: key must be a string at line 1 column 2"} 10 # HTTP 400 11 12 $ curl -s -X POST /users -d '{"name":"Alice"}' 13 {"error":"invalid request body: Expected request with `Content-Type: application/json`"} 14 # HTTP 415 ``` Now malformed input (400/422/415) and your domain errors share one error format, and the status codes are still semantically correct: `422` for a well-formed JSON object missing a field, `400` for syntactically broken JSON, `415` for a missing/wrong `Content-Type`. To add domain errors (a `NotFound`, a `Conflict`) you just add variants to `AppError` and extend the `match` in `into_response`. The [JSON APIs](/16-web-apis/08-json-apis/) and [Validation](/16-web-apis/09-validation/) chapters build full CRUD resources on top of this pattern, and [Extractors](/16-web-apis/04-extractors/) explains the `FromRequest`/`FromRequestParts` machinery behind `#[derive(FromRequest)]`. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [axum `error_handling` module](https://docs.rs/axum/0.8/axum/error_handling/index.html) — the framework’s own guidance on the `Result`-returning approach * [`IntoResponse` trait](https://docs.rs/axum/0.8/axum/response/trait.IntoResponse.html): every type Axum can respond with, and how to implement your own * [`#[derive(FromRequest)]` (`axum-macros`)](https://docs.rs/axum/0.8/axum/extract/derive.FromRequest.html) — the `via(...)` + `rejection(...)` attributes used above * [`thiserror` crate docs](https://docs.rs/thiserror/2/thiserror/) — `#[error(...)]`, `#[from]`, `#[source]`, `#[error(transparent)]` * [`anyhow` crate docs](https://docs.rs/anyhow/1/anyhow/): the dynamic catch-all error type * [axum `anyhow-error-response` example](https://github.com/tokio-rs/axum/blob/main/examples/anyhow-error-response/src/main.rs) — the official wrap-`anyhow` pattern ### Related Topics [Section titled “Related Topics”](#related-topics) * [Section 08: Error Handling](/08-error-handling/) — `Result`, `Option`, the `?` operator, and `From`-based conversions (read this first if `?` is new) * [Request and Response](/16-web-apis/07-request-response/): `IntoResponse`, status codes, and `(StatusCode, Json)` tuples * [Extractors](/16-web-apis/04-extractors/) — `FromRequest`/`FromRequestParts` and built-in extractor rejections * [Validation](/16-web-apis/09-validation/): returning helpful `400`/`422` bodies for invalid input * [Middleware and Layers](/16-web-apis/05-middleware/) — `TraceLayer` for request logging and short-circuiting with errors * [JSON APIs](/16-web-apis/08-json-apis/) — a CRUD resource that uses this error type throughout * [Section 02: Basics](/02-basics/) and [Section 01: Getting Started](/01-getting-started/) — enums, `match`, and `cargo add` * Next section: [Databases](/17-database/): mapping `sqlx`/`diesel` errors into `AppError` with `#[from]` *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A `code` field and a new status [Section titled “Exercise 1: A code field and a new status”](#exercise-1-a-code-field-and-a-new-status) **Difficulty:** Easy **Objective:** Extend an `AppError` with a machine-readable `code` field and a `429 Too Many Requests` variant. **Instructions:** 1. Define an `AppError` enum with `NotFound`, `RateLimited`, and `Internal` variants using `thiserror`. 2. Implement `IntoResponse` so each variant returns the right status (`404`, `429`, `500`) and a JSON body of the form `{ "error": "...", "code": "..." }`. 3. The `code` should be a short stable string like `"rate_limited"`. Solution ```rust 1 use axum::{ 2 http::StatusCode, 3 response::{IntoResponse, Response}, 4 routing::get, 5 Json, Router, 6 }; 7 use serde_json::json; 8 9 #[derive(Debug, thiserror::Error)] 10 enum AppError { 11 #[error("resource not found")] 12 NotFound, 13 #[error("rate limit exceeded, retry later")] 14 RateLimited, 15 #[error("internal server error")] 16 Internal, 17 } 18 19 impl AppError { 20 fn status(&self) -> StatusCode { 21 match self { 22 AppError::NotFound => StatusCode::NOT_FOUND, 23 AppError::RateLimited => StatusCode::TOO_MANY_REQUESTS, 24 AppError::Internal => StatusCode::INTERNAL_SERVER_ERROR, 25 } 26 } 27 } 28 29 impl IntoResponse for AppError { 30 fn into_response(self) -> Response { 31 let status = self.status(); 32 let code = match self { 33 AppError::NotFound => "not_found", 34 AppError::RateLimited => "rate_limited", 35 AppError::Internal => "internal", 36 }; 37 (status, Json(json!({ "error": self.to_string(), "code": code }))).into_response() 38 } 39 } 40 41 async fn h() -> Result<String, AppError> { 42 Err(AppError::RateLimited) 43 } 44 45 #[tokio::main] 46 async fn main() { 47 let app: Router = Router::new().route("/", get(h)); 48 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 49 axum::serve(listener, app).await.unwrap(); 50 } ``` `GET /` returns `{"error":"rate limit exceeded, retry later","code":"rate_limited"}` with `HTTP 429`. ### Exercise 2: Convert a foreign error with `#[from]` [Section titled “Exercise 2: Convert a foreign error with #\[from\]”](#exercise-2-convert-a-foreign-error-with-from) **Difficulty:** Medium **Objective:** Let a handler use `?` directly on `str::parse`, converting `ParseIntError` into your `AppError`, and add a second validation step. **Instructions:** 1. Give `AppError` a `Parse(#[from] ParseIntError)` variant (status `400`) and an `OutOfRange` variant (status `422`). 2. Write a function that parses a string to an integer with `?`, then checks it fits in a `u8`, returning `OutOfRange` otherwise. 3. Confirm the `?` conversion compiles without an explicit `.map_err`. Solution ```rust 1 use axum::{ 2 http::StatusCode, 3 response::{IntoResponse, Response}, 4 routing::get, 5 Json, Router, 6 }; 7 use serde_json::json; 8 use std::num::ParseIntError; 9 10 #[derive(Debug, thiserror::Error)] 11 enum AppError { 12 #[error("bad number: {0}")] 13 Parse(#[from] ParseIntError), 14 #[error("value out of range")] 15 OutOfRange, 16 } 17 18 impl IntoResponse for AppError { 19 fn into_response(self) -> Response { 20 let status = match &self { 21 AppError::Parse(_) => StatusCode::BAD_REQUEST, 22 AppError::OutOfRange => StatusCode::UNPROCESSABLE_ENTITY, 23 }; 24 (status, Json(json!({ "error": self.to_string() }))).into_response() 25 } 26 } 27 28 async fn parse_and_check(input: &str) -> Result<u8, AppError> { 29 let n: i64 = input.parse()?; // ParseIntError -> AppError::Parse via `?` 30 u8::try_from(n).map_err(|_| AppError::OutOfRange) 31 } 32 33 async fn h() -> Result<String, AppError> { 34 let n = parse_and_check("300").await?; // 300 doesn't fit in a u8 35 Ok(n.to_string()) 36 } 37 38 #[tokio::main] 39 async fn main() { 40 let app: Router = Router::new().route("/", get(h)); 41 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 42 axum::serve(listener, app).await.unwrap(); 43 } ``` `parse_and_check("abc")` would yield `400 {"error":"bad number: invalid digit found in string"}`, while `"300"` yields `422 {"error":"value out of range"}`. The `?` on `input.parse()` needs no `.map_err` because of the `#[from]` impl. ### Exercise 3: Typed variants plus an `anyhow` catch-all [Section titled “Exercise 3: Typed variants plus an anyhow catch-all”](#exercise-3-typed-variants-plus-an-anyhow-catch-all) **Difficulty:** Hard **Objective:** Build an `AppError` that has explicit domain variants *and* a transparent `anyhow` catch-all, so unmodeled failures become `500`s without you enumerating them, while never leaking the internal message. **Instructions:** 1. Add `anyhow` (`cargo add anyhow`). 2. Define `AppError` with `NotFound(u64)`, `Forbidden`, and `Unexpected(#[from] anyhow::Error)` (use `#[error(transparent)]` on the catch-all). 3. In `IntoResponse`, map domain variants to `404`/`403`, and the catch-all to `500`, but send the generic `"internal server error"` message for the `500`, while logging the real error with `tracing::error!`. 4. Show a function that returns `Err(anyhow::anyhow!("...").into())` and confirm it surfaces as a `500`. Solution ```rust 1 use axum::{ 2 http::StatusCode, 3 response::{IntoResponse, Response}, 4 routing::get, 5 Json, Router, 6 }; 7 use serde::Serialize; 8 use serde_json::json; 9 10 #[derive(Debug, thiserror::Error)] 11 enum AppError { 12 #[error("user {0} not found")] 13 NotFound(u64), 14 #[error("forbidden")] 15 Forbidden, 16 // Catch-all: any error that isn't a known domain case becomes a 500. 17 #[error(transparent)] 18 Unexpected(#[from] anyhow::Error), 19 } 20 21 #[derive(Serialize)] 22 struct ErrorBody { 23 error: String, 24 kind: &'static str, 25 } 26 27 impl IntoResponse for AppError { 28 fn into_response(self) -> Response { 29 let (status, kind) = match &self { 30 AppError::NotFound(_) => (StatusCode::NOT_FOUND, "not_found"), 31 AppError::Forbidden => (StatusCode::FORBIDDEN, "forbidden"), 32 AppError::Unexpected(_) => (StatusCode::INTERNAL_SERVER_ERROR, "internal"), 33 }; 34 35 // Public message: hide the inner detail for 5xx, expose it otherwise. 36 let public_message = match &self { 37 AppError::Unexpected(_) => "internal server error".to_string(), 38 other => other.to_string(), 39 }; 40 41 if status.is_server_error() { 42 tracing::error!(error = ?self, "request failed"); 43 } 44 45 (status, Json(ErrorBody { error: public_message, kind })).into_response() 46 } 47 } 48 49 fn lookup(id: u64) -> Result<String, AppError> { 50 if id == 0 { 51 // A deep failure we never modeled: bubbles up as anyhow -> 500. 52 return Err(anyhow::anyhow!("db connection reset").into()); 53 } 54 if id == 42 { 55 return Err(AppError::Forbidden); 56 } 57 Ok(format!("user-{id}")) 58 } 59 60 async fn h() -> Result<String, AppError> { 61 let name = lookup(0)?; // triggers the anyhow catch-all 62 Ok(name) 63 } 64 65 #[tokio::main] 66 async fn main() { 67 tracing_subscriber::fmt::init(); // needs `cargo add tracing-subscriber` 68 let app: Router = Router::new().route("/", get(h)); 69 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 70 axum::serve(listener, app).await.unwrap(); 71 } ``` `GET /` returns `{"error":"internal server error","kind":"internal"}` with `HTTP 500`, while the server log records the real `db connection reset` cause via `tracing::error!`. Notice `#[error(transparent)]` means `AppError::Unexpected`’s `Display` forwards to the inner `anyhow::Error`, but `into_response` deliberately overrides that for the public 5xx message. Typed domain errors and an open-ended catch-all coexist in one enum. # CORS with Axum and tower-http > Swap Express's cors for tower-http's CorsLayer in Axum: lock down origins, methods, and credentials, and see why the browser enforces CORS, not you. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) **CORS** (Cross-Origin Resource Sharing) is the browser security mechanism that decides whether JavaScript running on `https://app.example.com` is allowed to call your API on `https://api.example.com`. In Express you reach for the `cors` npm package; in Axum you add the `CorsLayer` from `tower-http`. This page shows how to go from the wide-open development default to a deliberately locked-down production configuration, and explains the one rule that trips up every developer the first time: **CORS is enforced by the browser, not by your server**. Your server’s only job is to send the right headers. > **Note:** This page uses **axum 0.8** and **tower-http 0.6**. The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically. Servers start with `axum::serve(listener, app)` and a `tokio::net::TcpListener`. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In Express, CORS is a middleware you mount with `app.use`. The popular [`cors`](https://www.npmjs.com/package/cors) package handles both the preflight `OPTIONS` request and the actual request. ```typescript 1 // server.ts — Express 5 with the `cors` package 2 // npm install express cors 3 // npm install -D @types/express @types/cors 4 import express from "express"; 5 import cors, { CorsOptions } from "cors"; 6 7 const app = express(); 8 app.use(express.json()); 9 10 // 1) Wide open — fine for a quick local prototype, dangerous in production. 11 // app.use(cors()); 12 13 // 2) Locked down — what you actually ship. 14 const corsOptions: CorsOptions = { 15 origin: ["https://app.example.com", "https://admin.example.com"], 16 methods: ["GET", "POST", "PUT", "DELETE"], 17 allowedHeaders: ["Content-Type", "Authorization"], 18 credentials: true, // allow cookies / Authorization to be sent cross-origin 19 maxAge: 86_400, // cache the preflight result for 24h 20 }; 21 app.use(cors(corsOptions)); 22 23 app.get("/tasks", (_req, res) => { 24 res.json([{ id: 1, title: "Write the docs" }]); 25 }); 26 27 app.listen(3000, () => { 28 console.log("listening on http://127.0.0.1:3000"); 29 }); ``` Things a TypeScript developer relies on here: `cors()` with no arguments reflects any origin; passing an `origin` array restricts it; `credentials: true` is required before browsers will send cookies or `Authorization` cross-origin; and the package quietly answers preflight `OPTIONS` requests for you. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same two configurations in Axum. First add the dependency with the `cors` feature: ```bash 1 cargo add tower-http --features cors 2 cargo add tower ``` `tower-http`’s features are opt-in, so you enable only `cors` (compression, tracing, etc. are separate features). Here is the locked-down version that mirrors the Express `corsOptions` above: ```rust 1 use axum::{ 2 http::{header, HeaderValue, Method}, 3 routing::get, 4 Router, 5 }; 6 use std::time::Duration; 7 use tower_http::cors::CorsLayer; 8 9 async fn list_tasks() -> &'static str { 10 r#"[{"id":1,"title":"Write the docs"}]"# 11 } 12 13 fn app() -> Router { 14 let cors = CorsLayer::new() 15 // The browser may read responses for requests from this origin. 16 .allow_origin("https://app.example.com".parse::<HeaderValue>().unwrap()) 17 // Which HTTP methods cross-origin requests may use. 18 .allow_methods([Method::GET, Method::POST]) 19 // Which request headers the client is allowed to send. 20 .allow_headers([header::CONTENT_TYPE, header::AUTHORIZATION]) 21 // Allow cookies / Authorization to be sent cross-origin. 22 .allow_credentials(true) 23 // Cache the preflight result in the browser for an hour. 24 .max_age(Duration::from_secs(3600)); 25 26 Router::new() 27 .route("/tasks", get(list_tasks)) 28 .layer(cors) 29 } 30 31 #[tokio::main] 32 async fn main() { 33 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 34 println!("listening on http://127.0.0.1:3000"); 35 axum::serve(listener, app()).await.unwrap(); 36 } ``` And the wide-open development default — the one-liner equivalent of `app.use(cors())`: ```rust 1 use axum::{routing::get, Router}; 2 use tower_http::cors::CorsLayer; 3 4 async fn list_tasks() -> &'static str { 5 "[]" 6 } 7 8 fn dev_app() -> Router { 9 Router::new() 10 .route("/tasks", get(list_tasks)) 11 // Allows ANY origin, method, and header. Development only. 12 .layer(CorsLayer::permissive()) 13 } 14 15 #[tokio::main] 16 async fn main() { 17 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 18 axum::serve(listener, dev_app()).await.unwrap(); 19 } ``` > **Tip:** Build the `CorsLayer` in its own `fn` (e.g. `fn cors_layer() -> CorsLayer`) and attach it with `.layer(cors_layer())`. It keeps the router declaration readable and makes the CORS policy unit-testable in isolation. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What CORS actually does [Section titled “What CORS actually does”](#what-cors-actually-does) CORS is **not** authentication or a firewall. It does not stop anyone from calling your API: `curl`, Postman, a mobile app, or another server can hit your endpoint regardless of CORS. CORS only governs whether a **browser** will let *its own JavaScript* read the response of a cross-origin request. The enforcement happens entirely in the browser; your server merely advertises a policy via `Access-Control-*` response headers, and the browser decides whether to hand the response to your `fetch().then(...)` or to throw a `TypeError` and log a red CORS error in the console. This is the single most important mental shift. A passing `curl` does **not** prove your CORS config is correct, and a failing browser request does **not** mean your server “rejected” anything. The response very likely arrived fine; the browser just refused to expose it. ### The preflight request [Section titled “The preflight request”](#the-preflight-request) For “non-simple” requests (anything with a JSON `Content-Type`, an `Authorization` header, or a method like `PUT`/`DELETE`), the browser first sends an `OPTIONS` **preflight** request asking “am I allowed to do this?”. `CorsLayer` answers that preflight automatically; you never write an `OPTIONS` handler. Here is the real preflight exchange against the locked-down server above (captured with `curl -X OPTIONS`): ```text 1 $ curl -i -X OPTIONS http://127.0.0.1:3000/tasks \ 2 -H "Origin: https://app.example.com" \ 3 -H "Access-Control-Request-Method: POST" \ 4 -H "Access-Control-Request-Headers: content-type" 5 6 HTTP/1.1 200 OK 7 access-control-allow-credentials: true 8 vary: origin, access-control-request-method, access-control-request-headers 9 access-control-allow-methods: GET,POST 10 access-control-allow-headers: content-type,authorization 11 access-control-max-age: 3600 12 access-control-allow-origin: https://app.example.com 13 allow: GET,HEAD 14 content-length: 0 ``` (Plus a standard `date:` header, omitted here.) Every method (`allow_methods`), header (`allow_headers`), credential (`allow_credentials`), and `max-age` you configured shows up here. The `Vary` header tells caches the response depends on the request’s origin and preflight headers. ### The actual request [Section titled “The actual request”](#the-actual-request) If the preflight passes, the browser sends the real request. The server attaches a smaller set of headers: ```text 1 $ curl -i http://127.0.0.1:3000/tasks -H "Origin: https://app.example.com" 2 3 HTTP/1.1 200 OK 4 vary: origin, access-control-request-method, access-control-request-headers 5 access-control-allow-credentials: true 6 access-control-allow-origin: https://app.example.com ``` ### The behavior that surprises everyone [Section titled “The behavior that surprises everyone”](#the-behavior-that-surprises-everyone) Watch what happens when a request arrives from an origin you did **not** allow, against that same fixed-origin server: ```text 1 $ curl -i http://127.0.0.1:3000/tasks -H "Origin: https://evil.example.com" 2 3 HTTP/1.1 200 OK 4 vary: origin, access-control-request-method, access-control-request-headers 5 access-control-allow-credentials: true 6 access-control-allow-origin: https://app.example.com ``` The request **still returns `200 OK` with the body**, and the `access-control-allow-origin` header still says `https://app.example.com`. The server did not block the request. A real browser at `https://evil.example.com` would compare its own origin (`evil`) against the returned `allow-origin` (`app`), see they differ, and refuse to give the response to the page’s JavaScript. That comparison is what “blocks” the request, and it lives in the browser, not your server. (See [Common Pitfalls](#common-pitfalls) for why testing CORS with `curl` is misleading.) ### Line-by-line [Section titled “Line-by-line”](#line-by-line) * `CorsLayer::new()` starts an empty, *deny-by-default* policy. With no further calls, no `Access-Control-Allow-*` headers are sent and browsers block all cross-origin reads. * `.allow_origin("https://app.example.com".parse::<HeaderValue>().unwrap())` accepts a single `HeaderValue`. The string must include the scheme (`https://`) and must **not** have a trailing slash. `HeaderValue` parsing of an invalid origin returns an `Err`, which `.unwrap()` would turn into a panic. * `.allow_methods([Method::GET, Method::POST])` takes anything convertible into a list of methods. Use the typed `Method::GET` constants rather than stringly-typed values. * `.allow_headers([header::CONTENT_TYPE, header::AUTHORIZATION])` lists the request headers clients may send. If a client sends a header that is not on this list, the preflight fails. * `.allow_credentials(true)` sets `Access-Control-Allow-Credentials: true`, the prerequisite for cookies and `Authorization` to flow cross-origin. This option has an important constraint covered below. * `.max_age(Duration::from_secs(3600))` tells the browser it may cache this preflight result and skip the `OPTIONS` round-trip for an hour. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | Express (`cors` package) | Axum (`tower-http` `CorsLayer`) | | ---------------- | --------------------------------- | --------------------------------------------------------- | | Install | `npm install cors` | `cargo add tower-http --features cors` | | Wide open | `app.use(cors())` | `.layer(CorsLayer::permissive())` | | Allow one origin | `cors({ origin: "https://x" })` | `.allow_origin("https://x".parse::<HeaderValue>()?)` | | Allow a list | `cors({ origin: ["a", "b"] })` | `.allow_origin([a, b])` (typed `HeaderValue`s) | | Dynamic check | `origin: (o, cb) => cb(null, ok)` | `.allow_origin(AllowOrigin::predicate(\|o, parts\| ...))` | | Credentials | `credentials: true` | `.allow_credentials(true)` | | Preflight cache | `maxAge: 86400` | `.max_age(Duration::from_secs(86_400))` | | Bad config | silently misbehaves | typed; some invalid combos **panic** at request time | | Where applied | `app.use(...)` (insertion order) | `.layer(...)` (outer-to-inner; last added runs first) | The conceptual differences worth internalizing: * **Typed, not stringly-typed.** Methods are `Method::GET`, header names are `header::CONTENT_TYPE`, origins are parsed into `HeaderValue`. A typo in `"Athorization"` is a value you must construct deliberately, not a silent string. * **Wildcard origins are a distinct type.** Express overloads `origin: "*"` / `origin: true` / an array / a function on one option. tower-http splits these: `Any` (the wildcard `*`), a concrete `HeaderValue` (or a list of them, echoed back when matched), and `AllowOrigin::predicate(...)` for dynamic logic. The type tells you which behavior you get. * **Some invalid policies are rejected, loudly.** Combining `allow_credentials(true)` with a wildcard origin is forbidden by the CORS spec. The `cors` npm package will happily send the contradictory headers and leave you to debug a browser error; tower-http **panics** when such a request arrives (see Pitfalls). Loud-and-early beats silent-and-wrong. * **Layers, not insertion order.** `CorsLayer` is a Tower layer. It typically belongs near the outside of the stack so preflight responses are produced before auth or other middleware can reject them. See [Middleware and Layers](/16-web-apis/05-middleware/) for how `.layer()` ordering works (the last layer added is the outermost and runs first). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: “I tested it with `curl` and it worked” [Section titled “Pitfall 1: “I tested it with curl and it worked””](#pitfall-1-i-tested-it-with-curl-and-it-worked) `curl`, Postman, and server-to-server HTTP clients do not enforce CORS; they ignore the `Access-Control-*` headers entirely. As shown above, a disallowed origin still gets `200 OK` and a body from `curl`. CORS only matters to a browser running page JavaScript. **Always verify CORS in a real browser** (the DevTools Network tab and Console), or by carefully inspecting the response headers and reasoning about what a browser *would* do with them. A green `curl` is not a passing CORS test. ### Pitfall 2: combining `allow_credentials(true)` with a wildcard origin panics [Section titled “Pitfall 2: combining allow\_credentials(true) with a wildcard origin panics”](#pitfall-2-combining-allow_credentialstrue-with-a-wildcard-origin-panics) The CORS spec forbids `Access-Control-Allow-Origin: *` together with `Access-Control-Allow-Credentials: true`: a credentialed response must name a specific origin. tower-http enforces this at runtime: ```rust 1 use tower_http::cors::{Any, CorsLayer}; 2 3 // does not work: panics when the first request hits this layer. 4 let _cors = CorsLayer::new() 5 .allow_origin(Any) // wildcard * 6 .allow_credentials(true); // contradicts the wildcard ``` The real panic, captured by sending one request to a server built this way: ```text 1 thread 'main' panicked at tower-http-0.6.11/src/cors/mod.rs:797:9: 2 Invalid CORS configuration: Cannot combine `Access-Control-Allow-Credentials: true` with `Access-Control-Allow-Origin: *` ``` > **Warning:** Because this panics at *request* time, not at startup, a server with this misconfiguration boots fine and then crashes the first time a browser sends a request. Note that `CorsLayer::permissive()` does **not** set `allow_credentials`, so it does not hit this, but it also means cookies will not flow. To support credentials, name your origins explicitly (a fixed `HeaderValue`, a list, or a predicate). ### Pitfall 3: a trailing slash or missing scheme in the origin [Section titled “Pitfall 3: a trailing slash or missing scheme in the origin”](#pitfall-3-a-trailing-slash-or-missing-scheme-in-the-origin) The `Origin` header a browser sends never includes a path or trailing slash; it is exactly `https://app.example.com`. If you configure `"https://app.example.com/"` (trailing slash) or `"app.example.com"` (no scheme), it will never match the browser’s `Origin`, and every request silently fails CORS in the browser while looking fine on the server. Match the origin byte-for-byte: scheme + host + optional port, no trailing slash. ### Pitfall 4: expecting a list of origins to send `*` [Section titled “Pitfall 4: expecting a list of origins to send \*”](#pitfall-4-expecting-a-list-of-origins-to-send-) `.allow_origin([origin_a, origin_b])` does **not** emit `Access-Control-Allow-Origin: *`. tower-http inspects the request’s `Origin`, and if it is in your list, echoes that single origin back; otherwise it sends no allow-origin header. This is correct (a response may only name one origin), but if you were expecting the literal header to contain both, you will not see it. ### Pitfall 5: putting `CorsLayer` inside an auth-guarded sub-router [Section titled “Pitfall 5: putting CorsLayer inside an auth-guarded sub-router”](#pitfall-5-putting-corslayer-inside-an-auth-guarded-sub-router) If your authentication middleware runs *before* CORS and rejects the unauthenticated preflight `OPTIONS` request with a `401`, the browser never sees the CORS headers and reports a CORS failure (not an auth failure). Preflight requests carry no credentials by design. Apply `CorsLayer` so it wraps (runs before) auth — typically by layering it on the outer router. See [Authentication Patterns](/16-web-apis/12-authentication/) and [Middleware and Layers](/16-web-apis/05-middleware/). *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Never ship `CorsLayer::permissive()` to production.** It is the equivalent of `cors()` with no options: any website on the internet can drive your API from its users’ browsers. Use it for local development only, ideally gated behind a debug build or an environment flag. * **Allowlist explicit origins.** Name the exact front-end origins you trust. Do not reflect the request’s `Origin` back unconditionally (the dynamic equivalent of `*` while still appearing “specific”) — that defeats the purpose. * **Only enable `allow_credentials(true)` if you actually use cookies or send `Authorization` cross-origin,** and remember it is incompatible with wildcard origins. * **Restrict methods and headers to what you use.** `.allow_methods([Method::GET, Method::POST])` and an explicit `allow_headers` list are tighter than `Any`. * **Set a `max_age`** to cut preflight traffic; browsers cap it (Chromium caps at 7200s), so a value like 24 hours is requested-but-clamped, which is fine. * **Read allowed origins from configuration**, not hard-coded literals, so staging and production can differ without a recompile (shown in the Real-World Example). * **Use `expose_headers` when the browser must read a custom response header** (e.g. a pagination header like `X-Total-Count`). By default browsers only expose a short safelist of response headers to JavaScript: ```rust 1 use axum::http::{header, Method}; 2 use tower_http::cors::CorsLayer; 3 4 let _cors = CorsLayer::new() 5 .allow_origin("https://app.example.com".parse::<axum::http::HeaderValue>().unwrap()) 6 .allow_methods([Method::GET]) 7 // Let the browser's JS read this custom response header. 8 .expose_headers([header::HeaderName::from_static("x-total-count")]); ``` *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored setup: allowed origins come from the `CORS_ALLOWED_ORIGINS` environment variable (comma-separated), credentials are enabled, and the CORS policy is built in its own function so it can be tested and reused. The `CorsLayer` is applied as the outer layer of the router. ```rust 1 use axum::{ 2 extract::State, 3 http::{header, HeaderValue, Method, StatusCode}, 4 routing::get, 5 Json, Router, 6 }; 7 use serde::{Deserialize, Serialize}; 8 use std::{ 9 sync::{Arc, Mutex}, 10 time::Duration, 11 }; 12 use tower_http::cors::CorsLayer; 13 14 #[derive(Clone, Serialize)] 15 struct Task { 16 id: u64, 17 title: String, 18 } 19 20 #[derive(Deserialize)] 21 struct NewTask { 22 title: String, 23 } 24 25 #[derive(Clone, Default)] 26 struct AppState { 27 tasks: Arc<Mutex<Vec<Task>>>, 28 } 29 30 async fn list_tasks(State(state): State<AppState>) -> Json<Vec<Task>> { 31 Json(state.tasks.lock().unwrap().clone()) 32 } 33 34 async fn create_task( 35 State(state): State<AppState>, 36 Json(body): Json<NewTask>, 37 ) -> (StatusCode, Json<Task>) { 38 let mut tasks = state.tasks.lock().unwrap(); 39 let id = tasks.len() as u64 + 1; 40 let task = Task { id, title: body.title }; 41 tasks.push(task.clone()); 42 (StatusCode::CREATED, Json(task)) 43 } 44 45 /// Build the CORS policy from configuration. 46 /// `CORS_ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com` 47 fn cors_from_env() -> CorsLayer { 48 let raw = std::env::var("CORS_ALLOWED_ORIGINS") 49 .unwrap_or_else(|_| "https://app.example.com".to_string()); 50 51 // Parse each comma-separated origin into a typed HeaderValue. 52 let origins: Vec<HeaderValue> = raw 53 .split(',') 54 .filter_map(|s| s.trim().parse::<HeaderValue>().ok()) 55 .collect(); 56 57 CorsLayer::new() 58 .allow_origin(origins) // echoes back whichever listed origin matches 59 .allow_methods([Method::GET, Method::POST, Method::PUT, Method::DELETE]) 60 .allow_headers([header::CONTENT_TYPE, header::AUTHORIZATION]) 61 .allow_credentials(true) 62 .max_age(Duration::from_secs(86_400)) 63 } 64 65 fn app() -> Router { 66 Router::new() 67 .route("/tasks", get(list_tasks).post(create_task)) 68 // Outermost layer: preflights are answered before anything else. 69 .layer(cors_from_env()) 70 .with_state(AppState::default()) 71 } 72 73 #[tokio::main] 74 async fn main() { 75 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 76 println!("listening on http://127.0.0.1:3000"); 77 axum::serve(listener, app()).await.unwrap(); 78 } ``` This compiles and runs against axum 0.8.9 / tower-http 0.6.11. Setting `CORS_ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com` before launch makes both front ends usable; a single value (or the default) restricts it to one. Because the origins are typed `HeaderValue`s and credentials are enabled, this never hits the wildcard-plus-credentials panic from Pitfall 2. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [tower-http `cors` module docs](https://docs.rs/tower-http/latest/tower_http/cors/index.html): the authoritative `CorsLayer` reference. * [`CorsLayer` API](https://docs.rs/tower-http/latest/tower_http/cors/struct.CorsLayer.html) and [`AllowOrigin`](https://docs.rs/tower-http/latest/tower_http/cors/struct.AllowOrigin.html) for dynamic/predicate origins. * [MDN: Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS): how browsers enforce the policy. * [Middleware and Layers](/16-web-apis/05-middleware/) — Tower layers, layer ordering, and where `CorsLayer` fits in the stack. * [Authentication Patterns](/16-web-apis/12-authentication/) — why CORS must wrap auth so preflight `OPTIONS` are not rejected. * [Request and Response Handling](/16-web-apis/07-request-response/): setting headers and status codes on responses. * [Axum Fundamentals](/16-web-apis/01-axum-basics/) and [Routing in Axum](/16-web-apis/03-routing/) — the `Router`/handler foundations these examples build on. * [Deploying Axum Applications](/16-web-apis/19-deployment/) — wiring `CORS_ALLOWED_ORIGINS` and other config through environment variables in production. * Foundations: [Section 00 — Introduction](/00-introduction/), [Section 01 — Getting Started](/01-getting-started/), [Section 02 — Basics](/02-basics/). Next up after web APIs: [Section 17 — Database](/17-database/). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: From permissive to locked-down [Section titled “Exercise 1: From permissive to locked-down”](#exercise-1-from-permissive-to-locked-down) **Difficulty:** Beginner **Objective:** Replace a development `CorsLayer::permissive()` with an explicit single-origin policy. **Instructions:** Start from a router that serves `GET /ping` returning `"pong"` behind `CorsLayer::permissive()`. Rewrite the layer so it allows only the origin `https://app.example.com`, only the `GET` method, and only the `Content-Type` request header. Do not enable credentials. Solution ```rust 1 use axum::{ 2 http::{header, HeaderValue, Method}, 3 routing::get, 4 Router, 5 }; 6 use tower_http::cors::CorsLayer; 7 8 async fn ping() -> &'static str { 9 "pong" 10 } 11 12 fn app() -> Router { 13 let cors = CorsLayer::new() 14 .allow_origin("https://app.example.com".parse::<HeaderValue>().unwrap()) 15 .allow_methods([Method::GET]) 16 .allow_headers([header::CONTENT_TYPE]); 17 18 Router::new().route("/ping", get(ping)).layer(cors) 19 } 20 21 #[tokio::main] 22 async fn main() { 23 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 24 axum::serve(listener, app()).await.unwrap(); 25 } ``` A preflight from `https://app.example.com` returns `access-control-allow-origin: https://app.example.com`, `access-control-allow-methods: GET`, and `access-control-allow-headers: content-type`. No `access-control-allow-credentials` header is sent because credentials were not enabled. ### Exercise 2: A dynamic origin allowlist that supports credentials [Section titled “Exercise 2: A dynamic origin allowlist that supports credentials”](#exercise-2-a-dynamic-origin-allowlist-that-supports-credentials) **Difficulty:** Intermediate **Objective:** Allow several origins *and* credentials without hitting the wildcard-plus-credentials restriction, by checking the origin per request. **Instructions:** Use `AllowOrigin::predicate` so that requests from `https://app.example.com` and `https://admin.example.com` are accepted (the matching origin reflected back), any other origin gets no allow-origin header, and `allow_credentials(true)` is enabled. Serve `GET /tasks`. Solution ```rust 1 use axum::{ 2 http::{header, request::Parts, HeaderValue, Method}, 3 routing::get, 4 Router, 5 }; 6 use tower_http::cors::{AllowOrigin, CorsLayer}; 7 8 async fn list_tasks() -> &'static str { 9 "[]" 10 } 11 12 fn cors_layer() -> CorsLayer { 13 let allowed: &[&str] = &["https://app.example.com", "https://admin.example.com"]; 14 15 CorsLayer::new() 16 .allow_origin(AllowOrigin::predicate( 17 move |origin: &HeaderValue, _parts: &Parts| { 18 origin 19 .to_str() 20 .map(|o| allowed.contains(&o)) 21 .unwrap_or(false) 22 }, 23 )) 24 .allow_methods([Method::GET, Method::POST]) 25 .allow_headers([header::CONTENT_TYPE, header::AUTHORIZATION]) 26 .allow_credentials(true) 27 } 28 29 fn app() -> Router { 30 Router::new() 31 .route("/tasks", get(list_tasks)) 32 .layer(cors_layer()) 33 } 34 35 #[tokio::main] 36 async fn main() { 37 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 38 axum::serve(listener, app()).await.unwrap(); 39 } ``` Verified behavior: a request with `Origin: https://app.example.com` returns `access-control-allow-origin: https://app.example.com`; `Origin: https://admin.example.com` reflects that origin; and `Origin: https://evil.test` returns `200 OK` with **no** `access-control-allow-origin` header — which is exactly what makes a real browser block the cross-origin read. Because each response names a single concrete origin (never `*`), enabling credentials is valid here. ### Exercise 3: Configurable CORS with a fallback and an exposed header [Section titled “Exercise 3: Configurable CORS with a fallback and an exposed header”](#exercise-3-configurable-cors-with-a-fallback-and-an-exposed-header) **Difficulty:** Advanced **Objective:** Read allowed origins from an environment variable, fall back to a safe default, and expose a custom pagination header to the browser. **Instructions:** Write `fn cors_from_env() -> CorsLayer` that reads `CORS_ALLOWED_ORIGINS` (comma-separated). If the variable is unset, default to `https://app.example.com`. Allow `GET` and `POST`, allow the `Content-Type` and `Authorization` request headers, enable credentials, set a 24-hour `max_age`, and expose the response header `X-Total-Count` so client JavaScript can read it. Attach it to a router serving `GET /tasks`. Solution ```rust 1 use axum::{ 2 http::{header, HeaderValue, Method}, 3 routing::get, 4 Router, 5 }; 6 use std::time::Duration; 7 use tower_http::cors::CorsLayer; 8 9 async fn list_tasks() -> &'static str { 10 "[]" 11 } 12 13 fn cors_from_env() -> CorsLayer { 14 let raw = std::env::var("CORS_ALLOWED_ORIGINS") 15 .unwrap_or_else(|_| "https://app.example.com".to_string()); 16 17 let origins: Vec<HeaderValue> = raw 18 .split(',') 19 .filter_map(|s| s.trim().parse::<HeaderValue>().ok()) 20 .collect(); 21 22 CorsLayer::new() 23 .allow_origin(origins) 24 .allow_methods([Method::GET, Method::POST]) 25 .allow_headers([header::CONTENT_TYPE, header::AUTHORIZATION]) 26 .allow_credentials(true) 27 .max_age(Duration::from_secs(86_400)) 28 // Let client JS read this custom response header. 29 .expose_headers([header::HeaderName::from_static("x-total-count")]) 30 } 31 32 fn app() -> Router { 33 Router::new() 34 .route("/tasks", get(list_tasks)) 35 .layer(cors_from_env()) 36 } 37 38 #[tokio::main] 39 async fn main() { 40 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 41 axum::serve(listener, app()).await.unwrap(); 42 } ``` `filter_map(... .ok())` quietly drops any malformed origin entry rather than panicking, so one bad value in the environment variable cannot take the server down at startup. With `CORS_ALLOWED_ORIGINS` unset, the policy allows the single default origin; set it to a comma-separated list to allow several. The `expose_headers` call adds `access-control-expose-headers: x-total-count` to responses, which is required before a browser will let `fetch` read that header off the response. # Authentication Patterns > Express stuffs req.user onto a request; Axum makes auth a guard extractor in the handler signature, so a protected route can't compile without a user. Authentication answers one question on every request: *who is making this call, and are they allowed to?* In Express you usually answer it with a middleware that stuffs a `req.user` onto the request. Axum gives you two cleaner mechanics: a **guard extractor** that lives in the handler’s argument list, and **`from_fn` middleware** that injects the user into request extensions. This chapter shows both, and how to layer role and scope checks on top. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In Axum, authentication is just an **extractor** or a **layer**, not a special framework feature. The idiomatic pattern is an `AuthUser` extractor: a struct that implements `FromRequestParts`, reads the credential (a bearer token, cookie, or API key), looks up the principal, and either yields the authenticated user or short-circuits with a `401`/`403`. Because the guard lives in the handler **signature**, a route that needs a user *cannot compile without asking for one*. The “forgot to add the auth middleware” class of bug largely disappears. This file covers the patterns; the mechanics of decoding a JWT live in [JWT Authentication](/16-web-apis/13-jwt/), and cookie/server-side sessions live in [Sessions and Cookies](/16-web-apis/14-sessions/). > **Scope note:** The credential here is a generic opaque token validated against a store. Swap in JWT verification or a session-cookie lookup without changing the *shape* of the guard. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) A typical Express setup: an auth middleware that verifies a bearer token, attaches `req.user`, and a role guard that builds on it. ```typescript 1 // auth.ts — Express authentication middleware 2 import express, { Request, Response, NextFunction } from "express"; 3 4 interface User { 5 id: number; 6 name: string; 7 role: "admin" | "member"; 8 } 9 10 // Pretend this is a session store / token cache (Redis, a DB, etc.). 11 const sessions = new Map<string, number>([ 12 ["admin-token", 1], 13 ["member-token", 2], 14 ]); 15 const users = new Map<number, User>([ 16 [1, { id: 1, name: "Ada", role: "admin" }], 17 [2, { id: 2, name: "Bob", role: "member" }], 18 ]); 19 20 // Augment Express's Request type so `req.user` type-checks. 21 declare global { 22 namespace Express { 23 interface Request { 24 user?: User; 25 } 26 } 27 } 28 29 // Middleware: authenticate, then attach the user to the request object. 30 function requireAuth(req: Request, res: Response, next: NextFunction) { 31 const header = req.headers.authorization ?? ""; 32 const token = header.startsWith("Bearer ") ? header.slice(7) : null; 33 const userId = token ? sessions.get(token) : undefined; 34 const user = userId ? users.get(userId) : undefined; 35 36 if (!user) { 37 return res.status(401).json({ error: "invalid or missing token" }); 38 } 39 req.user = user; // <-- shared mutable state; downstream handlers read this 40 next(); 41 } 42 43 // Role guard built ON TOP of requireAuth. Must run after it. 44 function requireAdmin(req: Request, res: Response, next: NextFunction) { 45 if (req.user?.role !== "admin") { 46 return res.status(403).json({ error: "admin role required" }); 47 } 48 next(); 49 } 50 51 const app = express(); 52 53 app.get("/me", requireAuth, (req, res) => { 54 res.json(req.user); // non-null only because requireAuth ran first 55 }); 56 57 app.get("/admin/users", requireAuth, requireAdmin, (_req, res) => { 58 res.json([...users.values()]); 59 }); 60 61 app.listen(3000); ``` **The fragile part:** nothing in the type system stops you from writing `app.get("/me", (req, res) => res.json(req.user))` and *forgetting* `requireAuth`. `req.user` is typed `User | undefined`, so `res.json(req.user)` happily compiles and ships `undefined` at runtime. The guarantee that “this handler always has a user” lives only in your memory and your route registration order. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Axum turns that runtime convention into a **compile-time requirement**. We write an `AuthUser` extractor; any handler that wants the user just names it as a parameter. Set up a project: ```bash 1 cargo new auth-demo 2 cd auth-demo 3 cargo add axum@0.8 4 cargo add tokio@1 --features full 5 cargo add serde --features derive 6 cargo add serde_json ``` ```rust 1 // src/main.rs — AuthUser as a guard extractor 2 use axum::{ 3 extract::{FromRequestParts, State}, 4 http::{header::AUTHORIZATION, request::Parts, StatusCode}, 5 response::{IntoResponse, Response}, 6 routing::get, 7 Json, Router, 8 }; 9 use serde::Serialize; 10 use std::collections::HashMap; 11 use std::sync::Arc; 12 13 #[derive(Clone, Serialize)] 14 struct User { 15 id: u64, 16 name: String, 17 role: Role, 18 } 19 20 #[derive(Clone, Copy, PartialEq, Eq, Serialize)] 21 #[serde(rename_all = "lowercase")] 22 enum Role { 23 Admin, 24 Member, 25 } 26 27 // A trivial "session store": token -> user id. A real app hits a DB or Redis. 28 #[derive(Clone)] 29 struct AppState { 30 sessions: Arc<HashMap<String, u64>>, 31 users: Arc<HashMap<u64, User>>, 32 } 33 34 // The authenticated principal, available as a handler argument. 35 struct AuthUser(User); 36 37 // One reusable rejection type so every auth failure looks the same on the wire. 38 struct AuthError(StatusCode, &'static str); 39 40 impl IntoResponse for AuthError { 41 fn into_response(self) -> Response { 42 (self.0, Json(serde_json::json!({ "error": self.1 }))).into_response() 43 } 44 } 45 46 impl FromRequestParts<AppState> for AuthUser { 47 type Rejection = AuthError; 48 49 async fn from_request_parts( 50 parts: &mut Parts, 51 state: &AppState, 52 ) -> Result<Self, Self::Rejection> { 53 let token = parts 54 .headers 55 .get(AUTHORIZATION) 56 .and_then(|v| v.to_str().ok()) 57 .and_then(|s| s.strip_prefix("Bearer ")) 58 .ok_or(AuthError(StatusCode::UNAUTHORIZED, "missing bearer token"))?; 59 60 let user_id = state 61 .sessions 62 .get(token) 63 .ok_or(AuthError(StatusCode::UNAUTHORIZED, "invalid or expired token"))?; 64 65 let user = state 66 .users 67 .get(user_id) 68 .cloned() 69 .ok_or(AuthError(StatusCode::UNAUTHORIZED, "user no longer exists"))?; 70 71 Ok(AuthUser(user)) 72 } 73 } 74 75 // A second guard built ON TOP of AuthUser: requires the admin role. 76 struct AdminUser(User); 77 78 impl FromRequestParts<AppState> for AdminUser { 79 type Rejection = AuthError; 80 81 async fn from_request_parts( 82 parts: &mut Parts, 83 state: &AppState, 84 ) -> Result<Self, Self::Rejection> { 85 let AuthUser(user) = AuthUser::from_request_parts(parts, state).await?; 86 if user.role != Role::Admin { 87 return Err(AuthError(StatusCode::FORBIDDEN, "admin role required")); 88 } 89 Ok(AdminUser(user)) 90 } 91 } 92 93 // Any logged-in user can read their own profile. 94 async fn me(AuthUser(user): AuthUser) -> Json<User> { 95 Json(user) 96 } 97 98 // Only admins reach this handler — the type system enforces it. 99 async fn list_all(AdminUser(_admin): AdminUser, State(state): State<AppState>) -> Json<Vec<User>> { 100 let mut all: Vec<User> = state.users.values().cloned().collect(); 101 all.sort_by_key(|u| u.id); 102 Json(all) 103 } 104 105 fn app() -> Router { 106 let mut users = HashMap::new(); 107 users.insert(1, User { id: 1, name: "Ada".into(), role: Role::Admin }); 108 users.insert(2, User { id: 2, name: "Bob".into(), role: Role::Member }); 109 110 let mut sessions = HashMap::new(); 111 sessions.insert("admin-token".to_string(), 1); 112 sessions.insert("member-token".to_string(), 2); 113 114 let state = AppState { sessions: Arc::new(sessions), users: Arc::new(users) }; 115 116 Router::new() 117 .route("/me", get(me)) 118 .route("/admin/users", get(list_all)) 119 .with_state(state) 120 } 121 122 #[tokio::main] 123 async fn main() { 124 let app = app(); 125 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 126 println!("listening on {}", listener.local_addr().unwrap()); 127 axum::serve(listener, app).await.unwrap(); 128 } ``` Running it and hitting the routes with `curl` produces this **real** output: ```text 1 $ curl -s -i http://127.0.0.1:3000/me | head -1 2 HTTP/1.1 401 Unauthorized 3 $ curl -s http://127.0.0.1:3000/me 4 {"error":"missing bearer token"} 5 6 $ curl -s -H "Authorization: Bearer member-token" http://127.0.0.1:3000/me 7 {"id":2,"name":"Bob","role":"member"} 8 9 $ curl -s -i -H "Authorization: Bearer member-token" http://127.0.0.1:3000/admin/users | head -1 10 HTTP/1.1 403 Forbidden 11 $ curl -s -H "Authorization: Bearer member-token" http://127.0.0.1:3000/admin/users 12 {"error":"admin role required"} 13 14 $ curl -s -H "Authorization: Bearer admin-token" http://127.0.0.1:3000/admin/users 15 [{"id":1,"name":"Ada","role":"admin"},{"id":2,"name":"Bob","role":"member"}] ``` *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The guard lives in the signature [Section titled “The guard lives in the signature”](#the-guard-lives-in-the-signature) `async fn me(AuthUser(user): AuthUser)` is the whole point. Before `me` runs, Axum calls `AuthUser::from_request_parts`. If that returns `Err`, the handler body **never executes** and the rejection becomes the response. There is no `req.user` that *might* be undefined. By the time you are inside `me`, `user` is a concrete, non-optional `User`. Compare this to the Express version, where `req.user` stays `User | undefined` forever. This is the `FromRequestParts` trait, the same mechanism behind `Path`, `Query`, and `State` (see [Extractors](/16-web-apis/04-extractors/) for the full machinery). The key facts: * **`from_request_parts` only sees request *metadata*** — method, URI, headers, extensions — not the body. That is exactly what auth needs, and it means `AuthUser` composes freely with a body extractor like `Json` in the same handler. * **The `State` is handed in as `&AppState`.** Because we implemented `FromRequestParts<AppState>` (a concrete state type, not a generic `S`), we can reach into `state.sessions` directly. That is the difference between this guard and the generic `RequestId` example in [Extractors](/16-web-apis/04-extractors/): a generic guard needs no state, an auth guard usually does. * **The `?` operator threads rejections out.** Every `.ok_or(...)?` converts a `None` into an early `Err(AuthError)`. Rust’s [error handling](/08-error-handling/) machinery does the short-circuiting that `return res.status(401)...` does manually in Express. ### One rejection type, one response shape [Section titled “One rejection type, one response shape”](#one-rejection-type-one-response-shape) `AuthError(StatusCode, &'static str)` implements `IntoResponse`, so the framework knows how to turn a rejected auth into an HTTP response. We build a JSON body with `serde_json::json!`. Every auth failure (missing token, bad token, deleted user) funnels through this single type, so the wire format is consistent. (For a richer application-wide error type using `thiserror`, see [Error Handling in Web Handlers](/16-web-apis/10-error-handling-web/).) ### Layering guards by composition [Section titled “Layering guards by composition”](#layering-guards-by-composition) `AdminUser` does not re-implement token parsing. It calls `AuthUser::from_request_parts(parts, state).await?` and then adds a role check. This mirrors `requireAuth` + `requireAdmin` in Express, but the dependency is explicit: `AdminUser` literally *calls* `AuthUser`, so you cannot accidentally run the role check without the authentication that precedes it. ### Why `Arc` and `Clone` [Section titled “Why Arc and Clone”](#why-arc-and-clone) `AppState` derives `Clone` and wraps its maps in `Arc`. Axum clones the state once per request to hand to extractors; `Arc` makes that clone a cheap pointer-bump rather than a deep copy of every user. This is the standard [shared-state](/16-web-apis/06-state-management/) pattern. (Cloning shared state is covered in depth there; the relevant ownership rules are in [section 05](/05-ownership/).) *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concern | Express.js | Axum | | ----------------------- | ---------------------------------------------- | ----------------------------------------------------------- | | Where auth runs | `app.use` / per-route middleware | extractor in the handler signature, or a `from_fn` layer | | How the user is exposed | mutate `req.user` (typed `User \| undefined`) | a handler **parameter** of type `AuthUser` (always present) | | Forgetting the guard | compiles; `req.user` is `undefined` at runtime | the handler won’t compile without naming the extractor | | Short-circuiting | `return res.status(401)...` and skip `next()` | extractor returns `Err`; handler body never runs | | Role/scope layering | a second middleware that reads `req.user` | a second extractor that calls the first, or a method check | | Rejection format | whatever each middleware writes | one `IntoResponse` type, uniform across the app | The deepest difference: in Express, the link between “this route is protected” and “this handler assumes a user” is a *convention* enforced by route-registration order. In Axum it is a *type*. A handler that takes `AuthUser` is, by construction, only reachable with a valid user. > **Note:** This compile-time guarantee covers *requesting* the user, not *applying* the layer. If you instead use the middleware-injection pattern below (`Extension<CurrentUser>`), you reintroduce a runtime failure mode; see the pitfall on missing extensions. *** ## Middleware-based authentication (the `req.user` analog) [Section titled “Middleware-based authentication (the req.user analog)”](#middleware-based-authentication-the-requser-analog) Sometimes you want the Express feeling exactly: one middleware authenticates, stashes the user, and many downstream handlers read it. Axum supports this with `middleware::from_fn_with_state` plus **request extensions**: a typed bag attached to the request, which is the closest analog to mutating `req`. ```rust 1 // src/main.rs — middleware-based auth that injects the user via request extensions 2 use axum::{ 3 extract::{Request, State}, 4 http::{header::AUTHORIZATION, StatusCode}, 5 middleware::{self, Next}, 6 response::{IntoResponse, Response}, 7 routing::get, 8 Extension, Json, Router, 9 }; 10 use serde::Serialize; 11 use std::collections::HashMap; 12 use std::sync::Arc; 13 14 #[derive(Clone, Serialize)] 15 struct CurrentUser { 16 id: u64, 17 name: String, 18 } 19 20 #[derive(Clone)] 21 struct AppState { 22 sessions: Arc<HashMap<String, CurrentUser>>, 23 } 24 25 // The middleware: authenticate, then stash the user in the request's extensions 26 // so downstream handlers (and other middleware) can read it. 27 async fn auth_middleware( 28 State(state): State<AppState>, 29 mut req: Request, 30 next: Next, 31 ) -> Result<Response, StatusCode> { 32 let token = req 33 .headers() 34 .get(AUTHORIZATION) 35 .and_then(|v| v.to_str().ok()) 36 .and_then(|s| s.strip_prefix("Bearer ")) 37 .ok_or(StatusCode::UNAUTHORIZED)?; 38 39 let user = state.sessions.get(token).ok_or(StatusCode::UNAUTHORIZED)?.clone(); 40 41 // Make the authenticated user available to handlers via Extension<CurrentUser>. 42 req.extensions_mut().insert(user); 43 Ok(next.run(req).await) 44 } 45 46 // Handlers read the injected user with the Extension extractor. 47 async fn me(Extension(user): Extension<CurrentUser>) -> Json<CurrentUser> { 48 Json(user) 49 } 50 51 async fn dashboard(Extension(user): Extension<CurrentUser>) -> impl IntoResponse { 52 format!("Welcome back, {}!", user.name) 53 } 54 55 fn app() -> Router { 56 let mut sessions = HashMap::new(); 57 sessions.insert("member-token".to_string(), CurrentUser { id: 2, name: "Bob".into() }); 58 let state = AppState { sessions: Arc::new(sessions) }; 59 60 // Protected routes share one auth layer applied via route_layer. 61 let protected = Router::new() 62 .route("/me", get(me)) 63 .route("/dashboard", get(dashboard)) 64 .route_layer(middleware::from_fn_with_state(state.clone(), auth_middleware)); 65 66 Router::new() 67 .route("/", get(|| async { "public" })) 68 .merge(protected) 69 .with_state(state) 70 } 71 72 #[tokio::main] 73 async fn main() { 74 let app = app(); 75 let listener = tokio::net::TcpListener::bind("127.0.0.1:3001").await.unwrap(); 76 println!("listening on {}", listener.local_addr().unwrap()); 77 axum::serve(listener, app).await.unwrap(); 78 } ``` Real output: ```text 1 $ curl -s http://127.0.0.1:3001/ 2 public 3 $ curl -s -i http://127.0.0.1:3001/me | head -1 4 HTTP/1.1 401 Unauthorized 5 $ curl -s -H "Authorization: Bearer member-token" http://127.0.0.1:3001/me 6 {"id":2,"name":"Bob"} 7 $ curl -s -H "Authorization: Bearer member-token" http://127.0.0.1:3001/dashboard 8 Welcome back, Bob! ``` **How it maps to Express:** * `auth_middleware` is the `requireAuth` analog. `next.run(req).await` is `next()`. * `req.extensions_mut().insert(user)` is `req.user = user`, except extensions are keyed by **type**, not by string. Each type can hold one value. * `Extension<CurrentUser>` is `req.user` — except the read can *fail at runtime* if nothing inserted it (see the pitfall below). * `.route_layer(...)` applies the middleware to those routes only. Unlike `.layer()`, it does not run for unmatched paths, so a 404 stays a 404. Layer-vs-route\_layer ordering is covered in [Middleware and Layers](/16-web-apis/05-middleware/). ### Extractor guard vs. middleware injection — which to use? [Section titled “Extractor guard vs. middleware injection — which to use?”](#extractor-guard-vs-middleware-injection--which-to-use) | | Extractor (`AuthUser`) | Middleware + `Extension<CurrentUser>` | | ---------------------------------- | -------------------------------------------------------------- | -------------------------------------------------- | | ”Forgot the guard” failure | **compile error** (must name the extractor) | runtime `500` (extension missing) | | Per-handler opt-in | yes — only handlers that name it pay the cost | no — applies to every route under the layer | | Run for *every* route in a group | verbose (repeat in each signature) | one `.route_layer(...)` | | Modify the request before handlers | no | yes (rate-limit headers, request IDs, etc.) | | Best for | authorization that varies per handler; pulling typed user data | a blanket “this whole subtree requires login” gate | A common production setup uses **both**: a `from_fn` layer that authenticates a route group, plus a thin `AuthUser` extractor that reads the injected `CurrentUser` out of extensions and returns a clean `401` if it is absent, getting the compile-time guarantee back even under a blanket layer. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Reading an `Extension` that was never inserted [Section titled “Reading an Extension that was never inserted”](#reading-an-extension-that-was-never-inserted) The middleware pattern’s sharp edge: if a handler asks for `Extension<CurrentUser>` but its route is **not** behind the auth layer, it compiles fine and fails at runtime with a `500`. ```rust 1 // Compiles, but every request 500s: nothing inserts CurrentUser. 2 use axum::{routing::get, Extension, Json, Router}; 3 use serde::Serialize; 4 5 #[derive(Clone, Serialize)] 6 struct CurrentUser { id: u64, name: String } 7 8 async fn me(Extension(user): Extension<CurrentUser>) -> Json<CurrentUser> { 9 Json(user) 10 } 11 12 fn app() -> Router { 13 // No auth middleware here — nothing inserts CurrentUser. 14 Router::new().route("/me", get(me)) 15 } ``` Hitting `/me` returns a real `500` with this body: ```text 1 HTTP/1.1 500 Internal Server Error 2 Missing request extension: Extension of type `probe::CurrentUser` was not found. Perhaps you forgot to add it? See `axum::Extension`. ``` This is the Rust echo of Express’s `req.user` being `undefined`, except Express would silently serialize `undefined`, while Axum at least shouts. The `AuthUser` *extractor* pattern avoids this entirely, since it does the lookup itself rather than trusting a prior layer. ### Reaching into a generic state parameter [Section titled “Reaching into a generic state parameter”](#reaching-into-a-generic-state-parameter) A guard that needs `AppState` must implement `FromRequestParts<AppState>`, a concrete type. Writing it generic over `S` and then touching a field does not compile: ```rust 1 // does not compile (error[E0609]: no field `api_token` on type `&S`) 2 use axum::{extract::FromRequestParts, http::{request::Parts, StatusCode}}; 3 4 struct AppState { api_token: String } 5 struct AuthUser; 6 7 impl<S> FromRequestParts<S> for AuthUser 8 where 9 S: Send + Sync, 10 { 11 type Rejection = StatusCode; 12 async fn from_request_parts(_parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> { 13 if state.api_token.is_empty() { // <-- S is opaque; it has no fields 14 return Err(StatusCode::UNAUTHORIZED); 15 } 16 Ok(AuthUser) 17 } 18 } 19 20 fn main() {} ``` The exact compiler message: ```text 1 error[E0609]: no field `api_token` on type `&S` 2 --> src/main.rs:13:18 3 | 4 7 | impl<S> FromRequestParts<S> for AuthUser 5 | - type parameter 'S' declared here 6 ... 7 13 | if state.api_token.is_empty() { // <-- S is opaque; it has no fields 8 | ^^^^^^^^^ unknown field ``` **Fix:** either implement `FromRequestParts<AppState>` for the concrete state (as in the main example), or keep it generic but require `AppState: FromRef<S>` and call `AppState::from_ref(state)` to pull your sub-state out: the `FromRef` pattern from [Shared Application State in Axum](/16-web-apis/06-state-management/). ### Forgetting that `from_request_parts` is `async` and `Next` is last [Section titled “Forgetting that from\_request\_parts is async and Next is last”](#forgetting-that-from_request_parts-is-async-and-next-is-last) In axum 0.8 the trait uses native `async fn` (stable since Rust 1.75), so you write `async fn from_request_parts(...)` with **no `#[async_trait]`**. For `from_fn` middleware, `next: Next` must be the **last** parameter, after any extractors like `State`. Getting either wrong yields trait-bound errors that name `Handler` or `FromRequestParts` and are easy to misread. The fix is almost always parameter order or a missing `async`. > **Warning:** `async-trait` is **not** needed for extractors or middleware. It is only for `dyn Trait` dynamic dispatch, which authentication does not require. ### Timing-unsafe token comparison [Section titled “Timing-unsafe token comparison”](#timing-unsafe-token-comparison) `token != state.api_token` for a *secret* compares byte-by-byte and can leak length/prefix information through timing. For static API keys or session tokens, prefer a constant-time comparison (e.g. the `subtle` crate’s `ConstantTimeEq`, or comparing fixed-size hashes). For passwords, never compare plaintext — verify against a hash (see the Real-World Example). This matters more for secrets you compare on every request; opaque random session-IDs looked up in a map are less exposed because the map lookup, not a string compare, decides the match. ### Returning `403` when you mean `401` (and vice versa) [Section titled “Returning 403 when you mean 401 (and vice versa)”](#returning-403-when-you-mean-401-and-vice-versa) `401 Unauthorized` means *“I do not know who you are”* (no/invalid credentials). `403 Forbidden` means *“I know who you are, and you may not do this”* (authenticated but lacking the role/scope). The example returns `401` from `AuthUser` and `403` from the role check; keep that distinction, clients and proxies rely on it. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Prefer the extractor guard for authorization that varies per route.** A guard in the signature cannot be forgotten the way a layer can be omitted. * **Compose guards, don’t copy them.** `AdminUser` calls `AuthUser`; a `BillingAdmin` would call `AdminUser`. Each layer adds exactly one check. * **Use one `IntoResponse` error type** for all auth failures so the wire format is uniform; reach for an app-wide error enum (`thiserror`) once you have more than a couple of failure modes — see [Error Handling in Web Handlers](/16-web-apis/10-error-handling-web/). * **Keep `AuthUser` cheap to produce.** If the lookup hits a database, that cost is paid once per request per guarded handler. With the composition pattern, `AdminUser` reuses `AuthUser`’s single lookup rather than querying twice. * **Distinguish `401` from `403`** as above. * **For “whole subtree requires login,” use `.route_layer(from_fn_with_state(...))`** so unmatched paths still 404 instead of 401. * **Never log tokens or `Authorization` headers.** If you use `TraceLayer`, configure it not to record sensitive headers. * **Hash passwords with Argon2 (or bcrypt/scrypt); never store or compare plaintext.** The login flow below shows the Argon2 pattern. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A self-contained mini-API: a `POST /login` endpoint that verifies a password with **Argon2** and issues an opaque session token, an `AuthUser` guard, and an `AdminUser` role guard on top. This is production-shaped (constant-time password verification, identical error for unknown-email vs. wrong-password, unguessable UUID tokens), with the store kept in memory for brevity. Swap `RwLock<HashMap>` for a database pool from [section 17](/17-database/) in a real service. ```bash 1 cargo add axum@0.8 2 cargo add tokio@1 --features full 3 cargo add serde --features derive 4 cargo add serde_json 5 cargo add argon2 --features std 6 cargo add uuid --features v4 ``` ```rust 1 // src/main.rs — login + AuthUser guard + AdminUser role guard 2 use argon2::{ 3 password_hash::{rand_core::OsRng, PasswordHash, PasswordHasher, PasswordVerifier, SaltString}, 4 Argon2, 5 }; 6 use axum::{ 7 extract::{FromRequestParts, State}, 8 http::{header::AUTHORIZATION, request::Parts, StatusCode}, 9 response::{IntoResponse, Response}, 10 routing::{get, post}, 11 Json, Router, 12 }; 13 use serde::{Deserialize, Serialize}; 14 use std::collections::HashMap; 15 use std::sync::{Arc, RwLock}; 16 use uuid::Uuid; 17 18 #[derive(Clone, Serialize)] 19 struct User { 20 id: u64, 21 email: String, 22 role: Role, 23 #[serde(skip)] // never serialize the hash out to clients 24 password_hash: String, 25 } 26 27 #[derive(Clone, Copy, PartialEq, Eq, Serialize)] 28 #[serde(rename_all = "lowercase")] 29 enum Role { 30 Admin, 31 Member, 32 } 33 34 #[derive(Clone)] 35 struct AppState { 36 users: Arc<RwLock<HashMap<String, User>>>, // email -> user 37 sessions: Arc<RwLock<HashMap<String, u64>>>, // token -> user id 38 } 39 40 // ---- One reusable auth error type ------------------------------------------- 41 42 struct AuthError { 43 status: StatusCode, 44 message: &'static str, 45 } 46 47 impl AuthError { 48 fn new(status: StatusCode, message: &'static str) -> Self { 49 Self { status, message } 50 } 51 } 52 53 impl IntoResponse for AuthError { 54 fn into_response(self) -> Response { 55 (self.status, Json(serde_json::json!({ "error": self.message }))).into_response() 56 } 57 } 58 59 // ---- The AuthUser guard extractor ------------------------------------------- 60 61 struct AuthUser(User); 62 63 impl FromRequestParts<AppState> for AuthUser { 64 type Rejection = AuthError; 65 66 async fn from_request_parts( 67 parts: &mut Parts, 68 state: &AppState, 69 ) -> Result<Self, Self::Rejection> { 70 let token = parts 71 .headers 72 .get(AUTHORIZATION) 73 .and_then(|v| v.to_str().ok()) 74 .and_then(|s| s.strip_prefix("Bearer ")) 75 .ok_or_else(|| AuthError::new(StatusCode::UNAUTHORIZED, "missing bearer token"))?; 76 77 let user_id = { 78 let sessions = state.sessions.read().unwrap(); 79 *sessions 80 .get(token) 81 .ok_or_else(|| AuthError::new(StatusCode::UNAUTHORIZED, "invalid session"))? 82 }; 83 84 let user = { 85 let users = state.users.read().unwrap(); 86 users 87 .values() 88 .find(|u| u.id == user_id) 89 .cloned() 90 .ok_or_else(|| AuthError::new(StatusCode::UNAUTHORIZED, "user not found"))? 91 }; 92 93 Ok(AuthUser(user)) 94 } 95 } 96 97 // AdminUser reuses AuthUser, then checks the role. 98 struct AdminUser(User); 99 100 impl FromRequestParts<AppState> for AdminUser { 101 type Rejection = AuthError; 102 103 async fn from_request_parts( 104 parts: &mut Parts, 105 state: &AppState, 106 ) -> Result<Self, Self::Rejection> { 107 let AuthUser(user) = AuthUser::from_request_parts(parts, state).await?; 108 if user.role != Role::Admin { 109 return Err(AuthError::new(StatusCode::FORBIDDEN, "admin role required")); 110 } 111 Ok(AdminUser(user)) 112 } 113 } 114 115 // ---- Handlers ---------------------------------------------------------------- 116 117 #[derive(Deserialize)] 118 struct LoginRequest { 119 email: String, 120 password: String, 121 } 122 123 #[derive(Serialize)] 124 struct LoginResponse { 125 token: String, 126 } 127 128 async fn login( 129 State(state): State<AppState>, 130 Json(body): Json<LoginRequest>, 131 ) -> Result<Json<LoginResponse>, AuthError> { 132 // 1. Look up the user by email. 133 let user = { 134 let users = state.users.read().unwrap(); 135 users.get(&body.email).cloned() 136 } 137 // Same error whether the email is unknown or the password is wrong: 138 // never leak which accounts exist. 139 .ok_or_else(|| AuthError::new(StatusCode::UNAUTHORIZED, "invalid credentials"))?; 140 141 // 2. Verify the password against the stored Argon2 hash (constant-time). 142 let parsed = PasswordHash::new(&user.password_hash) 143 .map_err(|_| AuthError::new(StatusCode::INTERNAL_SERVER_ERROR, "corrupt hash"))?; 144 Argon2::default() 145 .verify_password(body.password.as_bytes(), &parsed) 146 .map_err(|_| AuthError::new(StatusCode::UNAUTHORIZED, "invalid credentials"))?; 147 148 // 3. Issue an opaque, unguessable session token. 149 let token = Uuid::new_v4().to_string(); 150 state.sessions.write().unwrap().insert(token.clone(), user.id); 151 152 Ok(Json(LoginResponse { token })) 153 } 154 155 async fn me(AuthUser(user): AuthUser) -> Json<User> { 156 Json(user) 157 } 158 159 async fn list_users(AdminUser(_admin): AdminUser, State(state): State<AppState>) -> Json<Vec<User>> { 160 let mut all: Vec<User> = state.users.read().unwrap().values().cloned().collect(); 161 all.sort_by_key(|u| u.id); 162 Json(all) 163 } 164 165 // Helper to hash a password when seeding the store. 166 fn hash_password(plain: &str) -> String { 167 let salt = SaltString::generate(&mut OsRng); 168 Argon2::default() 169 .hash_password(plain.as_bytes(), &salt) 170 .unwrap() 171 .to_string() 172 } 173 174 fn app() -> Router { 175 let mut users = HashMap::new(); 176 users.insert( 177 "ada@example.com".to_string(), 178 User { id: 1, email: "ada@example.com".into(), role: Role::Admin, password_hash: hash_password("hunter2") }, 179 ); 180 users.insert( 181 "bob@example.com".to_string(), 182 User { id: 2, email: "bob@example.com".into(), role: Role::Member, password_hash: hash_password("s3cret") }, 183 ); 184 185 let state = AppState { 186 users: Arc::new(RwLock::new(users)), 187 sessions: Arc::new(RwLock::new(HashMap::new())), 188 }; 189 190 Router::new() 191 .route("/login", post(login)) 192 .route("/me", get(me)) 193 .route("/admin/users", get(list_users)) 194 .with_state(state) 195 } 196 197 #[tokio::main] 198 async fn main() { 199 let app = app(); 200 let listener = tokio::net::TcpListener::bind("127.0.0.1:3003").await.unwrap(); 201 println!("listening on {}", listener.local_addr().unwrap()); 202 axum::serve(listener, app).await.unwrap(); 203 } ``` End-to-end with `curl`, every response below is **real**: ```text 1 # Wrong password -> generic 401 (no account enumeration) 2 $ curl -s -i -X POST http://127.0.0.1:3003/login \ 3 -H 'content-type: application/json' \ 4 -d '{"email":"ada@example.com","password":"nope"}' | head -1 5 HTTP/1.1 401 Unauthorized 6 $ curl -s -X POST http://127.0.0.1:3003/login \ 7 -H 'content-type: application/json' \ 8 -d '{"email":"ada@example.com","password":"nope"}' 9 {"error":"invalid credentials"} 10 11 # Correct login -> opaque session token 12 $ curl -s -X POST http://127.0.0.1:3003/login \ 13 -H 'content-type: application/json' \ 14 -d '{"email":"ada@example.com","password":"hunter2"}' 15 {"token":"bc89e48c-02ac-4a46-999c-e900f5e599cd"} 16 17 # Use the token (note: password_hash is omitted thanks to #[serde(skip)]) 18 $ curl -s -H "Authorization: Bearer bc89e48c-02ac-4a46-999c-e900f5e599cd" \ 19 http://127.0.0.1:3003/me 20 {"id":1,"email":"ada@example.com","role":"admin"} 21 22 # Ada is an admin -> allowed 23 $ curl -s -H "Authorization: Bearer bc89e48c-02ac-4a46-999c-e900f5e599cd" \ 24 http://127.0.0.1:3003/admin/users 25 [{"id":1,"email":"ada@example.com","role":"admin"},{"id":2,"email":"bob@example.com","role":"member"}] 26 27 # Bob (member) is forbidden from the admin route 28 $ curl -s -i -H "Authorization: Bearer <bob-token>" \ 29 http://127.0.0.1:3003/admin/users | head -1 30 HTTP/1.1 403 Forbidden 31 $ curl -s -H "Authorization: Bearer <bob-token>" http://127.0.0.1:3003/admin/users 32 {"error":"admin role required"} ``` > **Tip:** This issues an **opaque** server-side token (a session ID). The alternative is a self-contained **JWT** that carries the claims in the token itself: no per-request store lookup, at the cost of harder revocation. See [JWT Authentication](/16-web-apis/13-jwt/). For storing the token in a cookie rather than an `Authorization` header (and the CSRF considerations that follow), see [Sessions and Cookies](/16-web-apis/14-sessions/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`FromRequestParts`](https://docs.rs/axum/latest/axum/extract/trait.FromRequestParts.html) — the trait every guard extractor implements. * [`axum::middleware::from_fn_with_state`](https://docs.rs/axum/latest/axum/middleware/fn.from_fn_with_state.html) — middleware that needs access to state. * [`axum::Extension`](https://docs.rs/axum/latest/axum/struct.Extension.html) — the typed request-extensions extractor. * [`argon2` crate](https://docs.rs/argon2/latest/argon2/) — password hashing used in the login example. * Guide cross-links: * [Extractors](/16-web-apis/04-extractors/): how `FromRequestParts`/`FromRequest` work and extractor ordering. * [Middleware and Layers](/16-web-apis/05-middleware/): `from_fn`, layers, and `route_layer` vs `layer`. * [Shared Application State in Axum](/16-web-apis/06-state-management/): `State<T>`, `Arc`, and the `FromRef` sub-state pattern. * [Error Handling in Web Handlers](/16-web-apis/10-error-handling-web/): building an app-wide `AppError` that implements `IntoResponse`. * [JWT Authentication](/16-web-apis/13-jwt/): verifying JWTs inside an extractor. * [Sessions and Cookies](/16-web-apis/14-sessions/): cookie-based sessions and CSRF. * [CORS with Axum and tower-http](/16-web-apis/11-cors/): CORS for browser clients that send credentials. * [Section 08: Error Handling](/08-error-handling/) and [Section 09: Generics & Traits](/09-generics-traits/) for the trait/`Result` foundations. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: An optional-auth extractor [Section titled “Exercise 1: An optional-auth extractor”](#exercise-1-an-optional-auth-extractor) **Difficulty:** Easy **Objective:** Build a route that personalizes its greeting for logged-in users but still works for anonymous visitors: the auth equivalent of an optional `req.user`. **Instructions:** 1. Implement an `AuthUser(String)` extractor over an `AppState` whose `sessions: Arc<HashMap<String, String>>` maps token to username. 2. Also implement `OptionalFromRequestParts<AppState>` for `AuthUser` so that `Option<AuthUser>` works as a handler argument and *never* rejects. 3. Write `GET /greet` taking `Option<AuthUser>`: greet by name if present, otherwise `"Hello, guest!"`. Solution ```rust 1 use axum::{ 2 extract::{FromRequestParts, OptionalFromRequestParts}, 3 http::{header::AUTHORIZATION, request::Parts, StatusCode}, 4 response::IntoResponse, 5 routing::get, 6 Router, 7 }; 8 use std::collections::HashMap; 9 use std::convert::Infallible; 10 use std::sync::Arc; 11 12 #[derive(Clone)] 13 struct AppState { 14 sessions: Arc<HashMap<String, String>>, // token -> username 15 } 16 17 struct AuthUser(String); 18 19 impl FromRequestParts<AppState> for AuthUser { 20 type Rejection = StatusCode; 21 async fn from_request_parts(parts: &mut Parts, state: &AppState) -> Result<Self, Self::Rejection> { 22 let token = parts 23 .headers 24 .get(AUTHORIZATION) 25 .and_then(|v| v.to_str().ok()) 26 .and_then(|s| s.strip_prefix("Bearer ")) 27 .ok_or(StatusCode::UNAUTHORIZED)?; 28 let name = state.sessions.get(token).cloned().ok_or(StatusCode::UNAUTHORIZED)?; 29 Ok(AuthUser(name)) 30 } 31 } 32 33 // Make `Option<AuthUser>` an extractor: Some on a valid token, None otherwise, 34 // and never an error. 35 impl OptionalFromRequestParts<AppState> for AuthUser { 36 type Rejection = Infallible; 37 async fn from_request_parts( 38 parts: &mut Parts, 39 state: &AppState, 40 ) -> Result<Option<Self>, Self::Rejection> { 41 Ok(<AuthUser as FromRequestParts<AppState>>::from_request_parts(parts, state).await.ok()) 42 } 43 } 44 45 async fn greet(user: Option<AuthUser>) -> impl IntoResponse { 46 match user { 47 Some(AuthUser(name)) => format!("Hello, {name}!"), 48 None => "Hello, guest!".to_string(), 49 } 50 } 51 52 fn app() -> Router { 53 let mut sessions = HashMap::new(); 54 sessions.insert("tok".to_string(), "Ada".to_string()); 55 let state = AppState { sessions: Arc::new(sessions) }; 56 Router::new().route("/greet", get(greet)).with_state(state) 57 } 58 59 #[tokio::main] 60 async fn main() { 61 let app = app(); 62 let listener = tokio::net::TcpListener::bind("127.0.0.1:3004").await.unwrap(); 63 axum::serve(listener, app).await.unwrap(); 64 } ``` Verified behavior: ```text 1 $ curl -s http://127.0.0.1:3004/greet 2 Hello, guest! 3 $ curl -s -H "Authorization: Bearer tok" http://127.0.0.1:3004/greet 4 Hello, Ada! 5 $ curl -s -H "Authorization: Bearer wrong" http://127.0.0.1:3004/greet 6 Hello, guest! ``` In axum 0.8, `Option<T>` and `Result<T, T::Rejection>` are extractors only when `T` implements `OptionalFromRequestParts`/`FromRequestParts`. Implementing it explicitly (delegating to the strict impl with `.ok()`) makes the optional behavior intentional rather than accidental. ### Exercise 2: Fix the missing-guard bug [Section titled “Exercise 2: Fix the missing-guard bug”](#exercise-2-fix-the-missing-guard-bug) **Difficulty:** Medium **Objective:** Diagnose and fix a handler that 500s because it reads an extension nobody inserted. **Instructions:** The router below has `/me` reading `Extension<CurrentUser>`, but the `auth` middleware is only applied to `/dashboard`. Every request to `/me` returns `500 Missing request extension`. Fix it two ways: (a) extend the layer to cover `/me`, and (b) explain why converting `/me` to use the `AuthUser` *extractor* would have made the bug a compile error instead. ```rust 1 // Starting point (buggy): /me 500s. 2 let protected = Router::new() 3 .route("/dashboard", get(dashboard)) 4 .route_layer(middleware::from_fn_with_state(state.clone(), auth)); 5 let app = Router::new() 6 .route("/me", get(me)) // <-- not behind `auth` 7 .merge(protected) 8 .with_state(state); ``` Solution **Fix (a): put `/me` inside the protected group so the layer covers it.** ```rust 1 use axum::{ 2 extract::{Request, State}, 3 http::{header::AUTHORIZATION, StatusCode}, 4 middleware::{self, Next}, 5 response::Response, 6 routing::get, 7 Extension, Json, Router, 8 }; 9 use serde::Serialize; 10 use std::collections::HashMap; 11 use std::sync::Arc; 12 13 #[derive(Clone, Serialize)] 14 struct CurrentUser { id: u64, name: String } 15 16 #[derive(Clone)] 17 struct AppState { sessions: Arc<HashMap<String, CurrentUser>> } 18 19 async fn auth(State(state): State<AppState>, mut req: Request, next: Next) -> Result<Response, StatusCode> { 20 let token = req.headers().get(AUTHORIZATION) 21 .and_then(|v| v.to_str().ok()) 22 .and_then(|s| s.strip_prefix("Bearer ")) 23 .ok_or(StatusCode::UNAUTHORIZED)?; 24 let user = state.sessions.get(token).ok_or(StatusCode::UNAUTHORIZED)?.clone(); 25 req.extensions_mut().insert(user); 26 Ok(next.run(req).await) 27 } 28 29 async fn me(Extension(user): Extension<CurrentUser>) -> Json<CurrentUser> { Json(user) } 30 async fn dashboard(Extension(user): Extension<CurrentUser>) -> String { 31 format!("Welcome back, {}!", user.name) 32 } 33 34 fn app() -> Router { 35 let mut sessions = HashMap::new(); 36 sessions.insert("tok".to_string(), CurrentUser { id: 1, name: "Ada".into() }); 37 let state = AppState { sessions: Arc::new(sessions) }; 38 39 // Both routes now sit under the same auth layer. 40 Router::new() 41 .route("/me", get(me)) 42 .route("/dashboard", get(dashboard)) 43 .route_layer(middleware::from_fn_with_state(state.clone(), auth)) 44 .with_state(state) 45 } 46 47 #[tokio::main] 48 async fn main() { 49 let app = app(); 50 let listener = tokio::net::TcpListener::bind("127.0.0.1:3001").await.unwrap(); 51 axum::serve(listener, app).await.unwrap(); 52 } ``` **Fix (b):** if `me` instead took an `AuthUser` extractor that *does its own lookup*, then a route serving `me` without the necessary state/header would either be rejected with a clean `401` at request time, or — if you forgot to provide the state the extractor needs — fail to compile, because the handler would not satisfy `Handler` for that router’s state type. The extension pattern defers the “is the user here?” question to runtime; the extractor pattern answers it at the type level. That is the core reason to prefer the extractor guard when you can. ### Exercise 3: A scope/permission guard [Section titled “Exercise 3: A scope/permission guard”](#exercise-3-a-scopepermission-guard) **Difficulty:** Hard **Objective:** Go beyond a single `role` field to fine-grained **scopes** (like OAuth `posts:read`, `posts:write`), and enforce a specific scope per handler. **Instructions:** 1. Give `AuthUser` a `scopes: HashSet<String>` and a `require_scope(&self, scope) -> Result<(), Response>` helper that returns a `403` response when the scope is absent. 2. Wire `GET /posts` to require `posts:read` and `POST /posts` to require `posts:write` on the same path. 3. Verify a read-only user can `GET` but not `POST`. Solution ```rust 1 use axum::{ 2 extract::FromRequestParts, 3 http::{header::AUTHORIZATION, request::Parts, StatusCode}, 4 response::{IntoResponse, Response}, 5 routing::get, 6 Router, 7 }; 8 use std::collections::{HashMap, HashSet}; 9 use std::sync::Arc; 10 11 #[derive(Clone)] 12 struct AppState { 13 sessions: Arc<HashMap<String, AuthUser>>, 14 } 15 16 #[derive(Clone)] 17 struct AuthUser { 18 name: String, 19 scopes: HashSet<String>, 20 } 21 22 impl AuthUser { 23 // Guard helper: returns a 403 response unless the user holds the scope. 24 fn require_scope(&self, scope: &str) -> Result<(), Response> { 25 if self.scopes.contains(scope) { 26 Ok(()) 27 } else { 28 Err((StatusCode::FORBIDDEN, format!("missing scope: {scope}")).into_response()) 29 } 30 } 31 } 32 33 impl FromRequestParts<AppState> for AuthUser { 34 type Rejection = (StatusCode, String); 35 async fn from_request_parts(parts: &mut Parts, state: &AppState) -> Result<Self, Self::Rejection> { 36 let token = parts 37 .headers 38 .get(AUTHORIZATION) 39 .and_then(|v| v.to_str().ok()) 40 .and_then(|s| s.strip_prefix("Bearer ")) 41 .ok_or((StatusCode::UNAUTHORIZED, "missing token".to_string()))?; 42 state 43 .sessions 44 .get(token) 45 .cloned() 46 .ok_or((StatusCode::UNAUTHORIZED, "invalid token".to_string())) 47 } 48 } 49 50 async fn read_posts(user: AuthUser) -> Result<Response, Response> { 51 user.require_scope("posts:read")?; 52 Ok(format!("{} can read posts", user.name).into_response()) 53 } 54 55 async fn write_posts(user: AuthUser) -> Result<Response, Response> { 56 user.require_scope("posts:write")?; 57 Ok(format!("{} can write posts", user.name).into_response()) 58 } 59 60 fn app() -> Router { 61 let mut sessions = HashMap::new(); 62 sessions.insert( 63 "reader".to_string(), 64 AuthUser { name: "Bob".into(), scopes: HashSet::from(["posts:read".to_string()]) }, 65 ); 66 sessions.insert( 67 "editor".to_string(), 68 AuthUser { 69 name: "Ada".into(), 70 scopes: HashSet::from(["posts:read".to_string(), "posts:write".to_string()]), 71 }, 72 ); 73 let state = AppState { sessions: Arc::new(sessions) }; 74 Router::new() 75 .route("/posts", get(read_posts).post(write_posts)) 76 .with_state(state) 77 } 78 79 #[tokio::main] 80 async fn main() { 81 let app = app(); 82 let listener = tokio::net::TcpListener::bind("127.0.0.1:3005").await.unwrap(); 83 axum::serve(listener, app).await.unwrap(); 84 } ``` Verified behavior: ```text 1 $ curl -s -H "Authorization: Bearer reader" http://127.0.0.1:3005/posts 2 Bob can read posts 3 $ curl -s -i -X POST -H "Authorization: Bearer reader" http://127.0.0.1:3005/posts | head -1 4 HTTP/1.1 403 Forbidden 5 $ curl -s -X POST -H "Authorization: Bearer reader" http://127.0.0.1:3005/posts 6 missing scope: posts:write 7 $ curl -s -X POST -H "Authorization: Bearer editor" http://127.0.0.1:3005/posts 8 Ada can write posts ``` Using `Result<Response, Response>` as the handler return type lets `require_scope`’s `403` short-circuit with `?` — both arms are already responses, so no extra conversion is needed. For a guard that enforces the scope *before* the handler body runs (so the scope cannot be forgotten), wrap this in a dedicated extractor that reads the scope from a typed marker; the method approach shown here is the simplest stable design and keeps the required scope visible right at the top of each handler. # JWT Authentication > Issue and verify HMAC-signed JWTs in Rust with the jsonwebtoken crate. Where Express casts jwt.verify to any, Axum decodes typed Claims into an auth extractor. In a TypeScript backend you reach for `jsonwebtoken` (`jwt.sign` / `jwt.verify`) and an Express middleware that stuffs the decoded payload onto `req.user`. Rust’s story is almost identical in shape — there is a crate literally called `jsonwebtoken` — but the verification step becomes a typed **extractor**, so a handler that compiles has already been handed a validated set of claims. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **JSON Web Token (JWT)** is a signed, URL-safe string of the form `header.payload.signature`. The server signs it with a secret (or private key), hands it to the client at login, and the client sends it back in the `Authorization: Bearer <token>` header on every request. On each request the server re-verifies the signature and the expiry, then trusts the **claims** inside. This page covers issuing and verifying HMAC-signed tokens with the [`jsonwebtoken`](https://docs.rs/jsonwebtoken) crate, modelling claims as a `struct`, enforcing expiry, and verifying tokens inside an Axum extractor so the rest of your code only ever sees a valid `Claims`. The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically. This page targets **axum 0.8** and **`jsonwebtoken` 10**. > **Note:** `jsonwebtoken` 10 split its cryptography backend into Cargo features. You must enable **exactly one** of `rust_crypto` (pure Rust) or `aws_lc_rs`; the default features do not include a signer, and the program will panic at the first `encode`/`decode` if you forget. This page uses `rust_crypto`, which needs no system C toolchain. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) A typical Express setup: a `/login` route that signs a token, and an auth middleware that verifies it and populates `req.user`. ```typescript 1 // auth.ts — Express 5 + jsonwebtoken 2 import express, { Request, Response, NextFunction } from "express"; 3 import jwt from "jsonwebtoken"; 4 5 const SECRET = process.env.JWT_SECRET; 6 if (!SECRET || Buffer.byteLength(SECRET, "utf8") < 32) { 7 throw new Error("JWT_SECRET must contain at least 32 unpredictable bytes"); 8 } 9 10 interface Claims { 11 sub: string; // user id 12 role: "user" | "admin"; 13 } 14 15 const app = express(); 16 app.use(express.json()); 17 18 // Issue a token at login. 19 app.post("/login", (req: Request, res: Response) => { 20 const { username, password } = req.body as { username: string; password: string }; 21 // A real app verifies a password hash here. 22 if (username !== "alice" || password !== "hunter2") { 23 return res.status(401).json({ error: "invalid credentials" }); 24 } 25 const token = jwt.sign({ sub: username, role: "user" } satisfies Claims, SECRET, { 26 expiresIn: "1h", 27 }); 28 res.json({ access_token: token, token_type: "Bearer" }); 29 }); 30 31 // Verify a token on protected routes. 32 function requireAuth(req: Request, res: Response, next: NextFunction) { 33 const header = req.headers.authorization; 34 const token = header?.startsWith("Bearer ") ? header.slice(7) : undefined; 35 if (!token) return res.status(401).json({ error: "missing bearer token" }); 36 try { 37 // `jwt.verify` checks the signature AND the `exp` claim, throwing on failure. 38 (req as Request & { user: Claims }).user = jwt.verify(token, SECRET) as Claims; 39 next(); 40 } catch { 41 res.status(401).json({ error: "invalid or expired token" }); 42 } 43 } 44 45 app.get("/me", requireAuth, (req: Request, res: Response) => { 46 const user = (req as Request & { user: Claims }).user; 47 res.json({ user: user.sub, role: user.role }); 48 }); 49 50 app.listen(3000, () => console.log("listening on http://127.0.0.1:3000")); ``` Two things to notice, because Rust will tighten both: 1. `jwt.verify(token, SECRET)` returns `any` (you cast it to `Claims`). Nothing guarantees the token actually contained those fields; a typo in a claim name fails silently at runtime. 2. The decoded payload travels on a manually-attached `req.user` property that TypeScript does not know about, hence the `req as Request & { user: Claims }` dance. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) First add the dependencies in a project created with `cargo new`: ```bash 1 cargo add jsonwebtoken --features rust_crypto 2 cargo add serde --features derive 3 cargo add serde_json ``` The signing and verifying logic on its own — no web framework yet — looks like this: ```rust 1 use jsonwebtoken::{ 2 decode, encode, get_current_timestamp, Algorithm, DecodingKey, EncodingKey, Header, 3 Validation, 4 }; 5 use serde::{Deserialize, Serialize}; 6 7 // The claims ARE a struct. serde turns it into the JSON payload and back. 8 #[derive(Debug, Serialize, Deserialize)] 9 struct Claims { 10 sub: String, // subject — usually the user id 11 role: String, // a custom claim 12 exp: u64, // expiry, seconds since the Unix epoch (a registered claim) 13 iat: u64, // issued-at 14 } 15 16 fn make_token(secret: &[u8]) -> String { 17 let now = get_current_timestamp(); 18 let claims = Claims { 19 sub: "user_42".to_string(), 20 role: "admin".to_string(), 21 iat: now, 22 exp: now + 3600, // valid for one hour 23 }; 24 // Header::default() == HS256. EncodingKey::from_secret takes raw bytes. 25 encode(&Header::default(), &claims, &EncodingKey::from_secret(secret)).unwrap() 26 } 27 28 fn verify(token: &str, secret: &[u8]) -> jsonwebtoken::errors::Result<Claims> { 29 // Validation::new(HS256) checks the signature, the algorithm, AND `exp`. 30 let validation = Validation::new(Algorithm::HS256); 31 let data = decode::<Claims>(token, &DecodingKey::from_secret(secret), &validation)?; 32 Ok(data.claims) 33 } 34 35 fn main() { 36 let secret = b"super-secret-key"; 37 let token = make_token(secret); 38 println!("token starts with: {}", &token[..16]); 39 40 let claims = verify(&token, secret).unwrap(); 41 println!("decoded: sub={} role={}", claims.sub, claims.role); 42 } ``` Running it prints real output: ```text 1 token starts with: eyJ0eXAiOiJKV1Qi 2 decoded: sub=user_42 role=admin ``` The key difference from the TypeScript version: `decode::<Claims>(...)` is generic over your claims type. There is no `any`, no cast. If the JSON payload is missing a non-`Option` field or has the wrong type, `decode` returns an `Err` instead of handing you a half-populated struct. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### A JWT is three base64url parts [Section titled “A JWT is three base64url parts”](#a-jwt-is-three-base64url-parts) Decode the token your server hands out and you find three dot-separated, base64url-encoded segments: `header.payload.signature`. The first two are just JSON. Here is a real token issued by the server later in this page, split and decoded: ```text 1 parts: 3 2 header (base64url): eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9 3 4 decoded header: {"typ": "JWT", "alg": "HS256"} 5 decoded payload: {"sub": "alice", "role": "user", "exp": 1780316473, "iat": 1780315573} ``` > **Warning:** The payload is **encoded, not encrypted**. Anyone holding the token can read the claims (paste it into <https://jwt.io> and see). The signature only guarantees the server issued it and nobody tampered with it. Never put secrets (passwords, full credit-card numbers) in a JWT payload. ### `Claims` is a `serde` struct [Section titled “Claims is a serde struct”](#claims-is-a-serde-struct) `encode` takes any `T: Serialize`; `decode::<T>` takes any `T: DeserializeOwned`. So your claims type is an ordinary `serde` struct (see [Serialization](/15-serialization/)). The **registered claim names** from the JWT spec — `exp`, `iat`, `nbf`, `iss`, `aud`, `sub` — are just fields you name accordingly; everything else (`role` here) is a custom claim. Times are seconds since the Unix epoch as a `u64`, and `get_current_timestamp()` gives you “now” in exactly that format. ### `Header::default()` selects HS256 [Section titled “Header::default() selects HS256”](#headerdefault-selects-hs256) `Header::default()` is `Header::new(Algorithm::HS256)`: HMAC-SHA256, a symmetric algorithm where the same secret signs and verifies. That is the right default for a monolith that issues and checks its own tokens. If a third party needs to verify without being able to mint tokens, switch to an asymmetric algorithm (`RS256`, `ES256`, `EdDSA`) and hand out only the public key. With `jsonwebtoken` you would build the keys with `EncodingKey::from_rsa_pem(...)` / `DecodingKey::from_rsa_pem(...)` instead of `from_secret`. ### `Validation` is where the security lives [Section titled “Validation is where the security lives”](#validation-is-where-the-security-lives) `Validation::new(Algorithm::HS256)` does more than name an algorithm. By default it: * requires the `exp` claim to be present and rejects expired tokens (`validate_exp = true`); * allows **60 seconds of clock leeway** so a token that just expired on a slightly-skewed clock still passes; * pins the accepted algorithm to HS256, so an attacker cannot downgrade the token to `alg: none` or swap algorithms. You can tighten it further — `validation.set_audience(&["my-api"])`, `validation.set_issuer(&["my-auth-server"])`, `validation.validate_nbf = true`, `validation.leeway = 0`. Importantly, **pinning the algorithm is automatic** here. In some other languages the classic JWT vulnerability is verifying with whatever algorithm the *token’s own header* claims; `jsonwebtoken` only accepts algorithms you listed in `Validation`. ### `decode` returns a `Result`, not an exception [Section titled “decode returns a Result, not an exception”](#decode-returns-a-result-not-an-exception) Where `jwt.verify` *throws*, `decode` returns `jsonwebtoken::errors::Result<TokenData<T>>`. `TokenData` holds both `.header` and `.claims`. The `?` operator propagates the error; you decide how to map each `ErrorKind` to an HTTP status. This is the same `Result`-vs-exceptions story as the rest of Rust (see [Error Handling](/08-error-handling/)). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concern | TypeScript (`jsonwebtoken`) | Rust (`jsonwebtoken` 10) | | ---------------- | ------------------------------------ | ----------------------------------------------------------- | | Claims type | `object` / cast to interface | A `serde` `struct`; checked at decode time | | Signing | `jwt.sign(payload, secret, opts)` | `encode(&Header, &claims, &EncodingKey)` | | Verifying | `jwt.verify(token, secret)` → throws | `decode::<T>(token, &key, &validation)` → `Result` | | Expiry | `expiresIn: "1h"` string sugar | You set `exp` numerically; `Validation` enforces it | | Algorithm safety | depends on options | Pinned by `Validation`; never trusts the token’s own header | | Crypto backend | bundled (Node `crypto`) | Cargo feature: `rust_crypto` or `aws_lc_rs` | | Decoded payload | attached to `req.user` (untyped) | A typed value extracted into the handler signature | | Failure mode | runtime exception, `any` payload | compile-time-typed claims, explicit error mapping | The biggest conceptual shift: in Express, verification is *middleware that mutates the request*. In Axum, verification is *an extractor that produces a value*. A handler that takes `claims: Claims` as a parameter is, by construction, unreachable without a valid token: there is no `req.user` that might be `undefined`. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### 1. Forgetting to enable a crypto backend (a runtime panic) [Section titled “1. Forgetting to enable a crypto backend (a runtime panic)”](#1-forgetting-to-enable-a-crypto-backend-a-runtime-panic) With `jsonwebtoken` 10, `cargo add jsonwebtoken` alone pulls in the default features, which do **not** include a signer. The code compiles, but the first `encode`/`decode` panics: ```text 1 thread 'main' panicked at jsonwebtoken-10.4.0/src/crypto/mod.rs:124:40: 2 3 Could not automatically determine the process-level CryptoProvider from 4 jsonwebtoken crate features. Call CryptoProvider::install_default() before 5 this point to select a provider manually, or make sure exactly one of the 6 'rust_crypto' and 'aws_lc_rs' features is enabled. 7 See the documentation of the CryptoProvider type for more information. ``` That is the real panic message (file path and line re-wrapping trimmed for width). The fix is to enable a backend: `cargo add jsonwebtoken --features rust_crypto` (or `--features aws_lc_rs`). This is new in version 10; version 9 bundled `ring` and “just worked”, so older tutorials omit the feature. ### 2. Omitting `exp` from your claims struct [Section titled “2. Omitting exp from your claims struct”](#2-omitting-exp-from-your-claims-struct) `Validation` requires the `exp` claim by default. If your `Claims` struct has no `exp` field, every token you mint is missing it, and verification fails — not with a vague error, but a precise one: ```rust 1 use jsonwebtoken::{decode, encode, Algorithm, DecodingKey, EncodingKey, Header, Validation}; 2 use serde::{Deserialize, Serialize}; 3 4 #[derive(Debug, Serialize, Deserialize)] 5 struct NoExpClaims { 6 sub: String, 7 } 8 9 fn main() { 10 let secret = b"k"; 11 let token = encode( 12 &Header::default(), 13 &NoExpClaims { sub: "x".into() }, 14 &EncodingKey::from_secret(secret), 15 ) 16 .unwrap(); 17 18 let v = Validation::new(Algorithm::HS256); 19 let result = decode::<NoExpClaims>(&token, &DecodingKey::from_secret(secret), &v); 20 println!("{:?}", result.unwrap_err().kind()); 21 } ``` Real output: ```text 1 MissingRequiredClaim("exp") ``` Either add an `exp: u64` field (the right answer; tokens should expire) or, only if you have a deliberate reason, relax the validator with `validation.required_spec_claims.clear()` and `validation.validate_exp = false`. ### 3. Returning the raw `jsonwebtoken` error from a handler [Section titled “3. Returning the raw jsonwebtoken error from a handler”](#3-returning-the-raw-jsonwebtoken-error-from-a-handler) A handler’s return type must be something Axum can turn into a response (`impl IntoResponse`). `jsonwebtoken::errors::Error` is not, so this does not compile: ```rust 1 use axum::{routing::get, Json, Router}; 2 use jsonwebtoken::{decode, Algorithm, DecodingKey, Validation}; 3 use serde::{Deserialize, Serialize}; 4 5 #[derive(Serialize, Deserialize)] 6 struct Claims { 7 sub: String, 8 exp: u64, 9 } 10 11 // does not compile (error[E0277]): jsonwebtoken's Error is not IntoResponse, 12 // so this is not a valid Axum handler. 13 async fn me() -> Result<Json<Claims>, jsonwebtoken::errors::Error> { 14 let token = "x.y.z"; 15 let v = Validation::new(Algorithm::HS256); 16 let data = decode::<Claims>(token, &DecodingKey::from_secret(b"k"), &v)?; 17 Ok(Json(data.claims)) 18 } 19 20 #[tokio::main] 21 async fn main() { 22 let app: Router = Router::new().route("/me", get(me)); 23 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 24 axum::serve(listener, app).await.unwrap(); 25 } ``` The real compiler error is the classic “handler not satisfied” message: ```text 1 error[E0277]: the trait bound `fn() -> impl Future<Output = Result<..., ...>> {me}: Handler<_, _>` is not satisfied 2 --> src/main.rs:22:54 3 | 4 22 | let app: Router = Router::new().route("/me", get(me)); 5 | --- ^^ unsatisfied trait bound 6 | 7 = help: the trait `Handler<_, _>` is not implemented for fn item `...Result<axum::Json<Claims>, jsonwebtoken::errors::Error>...` 8 = note: Consider using `#[axum::debug_handler]` to improve the error message ``` The fix is to define your own error type that implements `IntoResponse` (shown in the next section), and `.map_err(...)` into it. As the note suggests, adding `#[axum::debug_handler]` to the function gives a far clearer message about *which* bound failed; reach for it whenever you see “Handler is not satisfied”. See [Error Handling in Web Apps](/16-web-apis/10-error-handling-web/). ### 4. Confusing “decoded” with “verified” [Section titled “4. Confusing “decoded” with “verified””](#4-confusing-decoded-with-verified) `jsonwebtoken::decode_header` and the `dangerous` module can read a token *without* checking the signature. That is only for inspecting the `kid`/`alg` to pick a key; never trust those claims. Real verification is always `decode::<T>(...)` with a real `Validation`. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Always enable exactly one crypto backend** (`rust_crypto` or `aws_lc_rs`) and keep it consistent across your workspace. * **Always include `exp`** and keep access tokens short-lived (minutes, not days). Pair a short access token with a longer-lived refresh token stored server-side or in an `HttpOnly` cookie (see [Sessions](/16-web-apis/14-sessions/)). * **Load the secret from the environment, never hard-code it or provide a fallback.** `std::env::var("JWT_SECRET")` must fail startup when the variable is missing. For HS256, require at least 32 unpredictable bytes; a weak or leaked HMAC secret means anyone can forge tokens. See [Deployment](/16-web-apis/19-deployment/) for env config. * **Build `EncodingKey`/`DecodingKey` once at startup** and store them in your `State`. They own the parsed key material; rebuilding them per request is wasted work. See [State Management](/16-web-apis/06-state-management/). * **Pin the algorithm** via `Validation::new(Algorithm::HS256)` (the default behavior) so a token cannot dictate its own verification algorithm. * **Verify inside an extractor**, not by hand in every handler, so the type system enforces “this route requires auth”. Layer a second extractor for authorization (role checks). * **Map errors deliberately**: a bad signature, an expired token, and a missing header are all `401`, but a valid token whose *role* is insufficient is `403`. Do not leak which one failed in detail to clients. * For password hashing at the `/login` step, use Argon2/bcrypt — never store or compare plaintext (covered in [Section 27: Security](/27-security/)). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-structured auth module: a `Keys` bundle in shared state, a `Claims` struct with a typed `Role`, a custom `AuthError` that implements `IntoResponse`, an `AuthUser` extractor for “any logged-in user”, and an `AdminUser` extractor that layers a role check on top. The credential check remains deliberately hard-coded so the example stays focused on JWT mechanics; replace it with an Argon2-backed user lookup before deploying. Add the crates first: ```bash 1 cargo add axum 2 cargo add tokio --features full 3 cargo add jsonwebtoken --features rust_crypto 4 cargo add serde --features derive 5 cargo add serde_json 6 cargo add thiserror ``` ```rust 1 use axum::{ 2 extract::{FromRequestParts, State}, 3 http::{header, request::Parts, StatusCode}, 4 response::{IntoResponse, Response}, 5 routing::{get, post}, 6 Json, Router, 7 }; 8 use jsonwebtoken::{ 9 decode, encode, get_current_timestamp, Algorithm, DecodingKey, EncodingKey, Header, 10 Validation, 11 }; 12 use serde::{Deserialize, Serialize}; 13 use std::sync::Arc; 14 15 const ACCESS_TTL_SECS: u64 = 15 * 60; // 15 minutes 16 17 #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] 18 #[serde(rename_all = "lowercase")] 19 enum Role { 20 User, 21 Admin, 22 } 23 24 #[derive(Debug, Serialize, Deserialize)] 25 struct Claims { 26 sub: String, 27 role: Role, 28 exp: u64, 29 iat: u64, 30 } 31 32 #[derive(thiserror::Error, Debug)] 33 enum AuthError { 34 #[error("missing or malformed Authorization header")] 35 MissingBearer, 36 #[error("token is invalid or expired")] 37 InvalidToken, 38 #[error("you do not have permission to access this resource")] 39 Forbidden, 40 #[error("invalid credentials")] 41 BadCredentials, 42 } 43 44 impl IntoResponse for AuthError { 45 fn into_response(self) -> Response { 46 let status = match self { 47 AuthError::MissingBearer | AuthError::InvalidToken | AuthError::BadCredentials => { 48 StatusCode::UNAUTHORIZED 49 } 50 AuthError::Forbidden => StatusCode::FORBIDDEN, 51 }; 52 let body = Json(serde_json::json!({ "error": self.to_string() })); 53 (status, body).into_response() 54 } 55 } 56 57 #[derive(Clone)] 58 struct AppState { 59 keys: Arc<Keys>, 60 } 61 62 struct Keys { 63 encoding: EncodingKey, 64 decoding: DecodingKey, 65 validation: Validation, 66 } 67 68 impl Keys { 69 fn new(secret: &[u8]) -> Self { 70 Self { 71 encoding: EncodingKey::from_secret(secret), 72 decoding: DecodingKey::from_secret(secret), 73 validation: Validation::new(Algorithm::HS256), 74 } 75 } 76 } 77 78 // The base extractor: any authenticated user. Verifies the bearer token. 79 struct AuthUser(Claims); 80 81 impl FromRequestParts<AppState> for AuthUser { 82 type Rejection = AuthError; 83 84 async fn from_request_parts( 85 parts: &mut Parts, 86 state: &AppState, 87 ) -> Result<Self, Self::Rejection> { 88 let token = parts 89 .headers 90 .get(header::AUTHORIZATION) 91 .and_then(|v| v.to_str().ok()) 92 .and_then(|s| s.strip_prefix("Bearer ")) 93 .ok_or(AuthError::MissingBearer)?; 94 95 let data = decode::<Claims>(token, &state.keys.decoding, &state.keys.validation) 96 .map_err(|_| AuthError::InvalidToken)?; 97 98 Ok(AuthUser(data.claims)) 99 } 100 } 101 102 // A second extractor that layers an authorization check on top of authentication. 103 struct AdminUser(Claims); 104 105 impl FromRequestParts<AppState> for AdminUser { 106 type Rejection = AuthError; 107 108 async fn from_request_parts( 109 parts: &mut Parts, 110 state: &AppState, 111 ) -> Result<Self, Self::Rejection> { 112 let AuthUser(claims) = AuthUser::from_request_parts(parts, state).await?; 113 if claims.role != Role::Admin { 114 return Err(AuthError::Forbidden); 115 } 116 Ok(AdminUser(claims)) 117 } 118 } 119 120 #[derive(Deserialize)] 121 struct LoginRequest { 122 username: String, 123 password: String, 124 } 125 126 #[derive(Serialize)] 127 struct TokenResponse { 128 access_token: String, 129 token_type: &'static str, 130 expires_in: u64, 131 } 132 133 fn issue_token(keys: &Keys, sub: &str, role: Role) -> Result<String, AuthError> { 134 let now = get_current_timestamp(); 135 let claims = Claims { 136 sub: sub.to_string(), 137 role, 138 iat: now, 139 exp: now + ACCESS_TTL_SECS, 140 }; 141 encode(&Header::default(), &claims, &keys.encoding).map_err(|_| AuthError::InvalidToken) 142 } 143 144 async fn login( 145 State(state): State<AppState>, 146 Json(body): Json<LoginRequest>, 147 ) -> Result<Json<TokenResponse>, AuthError> { 148 // A real implementation looks the user up and verifies an Argon2 hash. 149 let role = match (body.username.as_str(), body.password.as_str()) { 150 ("alice", "hunter2") => Role::User, 151 ("root", "toor") => Role::Admin, 152 _ => return Err(AuthError::BadCredentials), 153 }; 154 let token = issue_token(&state.keys, &body.username, role)?; 155 Ok(Json(TokenResponse { 156 access_token: token, 157 token_type: "Bearer", 158 expires_in: ACCESS_TTL_SECS, 159 })) 160 } 161 162 // `AuthUser(claims)` in the signature is the guard: this only runs for valid tokens. 163 async fn profile(AuthUser(claims): AuthUser) -> Json<serde_json::Value> { 164 Json(serde_json::json!({ "user": claims.sub, "role": claims.role })) 165 } 166 167 async fn admin_metrics(AdminUser(claims): AdminUser) -> Json<serde_json::Value> { 168 Json(serde_json::json!({ "secret_metrics": 42, "viewed_by": claims.sub })) 169 } 170 171 fn app(state: AppState) -> Router { 172 Router::new() 173 .route("/login", post(login)) 174 .route("/me", get(profile)) 175 .route("/admin/metrics", get(admin_metrics)) 176 .with_state(state) 177 } 178 179 #[tokio::main] 180 async fn main() { 181 // Fail closed: starting with a public fallback key would let anyone forge tokens. 182 let secret = std::env::var("JWT_SECRET") 183 .expect("JWT_SECRET must be set to at least 32 unpredictable bytes"); 184 assert!( 185 secret.as_bytes().len() >= 32, 186 "JWT_SECRET must contain at least 32 bytes for HS256", 187 ); 188 let state = AppState { 189 keys: Arc::new(Keys::new(secret.as_bytes())), 190 }; 191 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 192 println!("listening on http://0.0.0.0:3000"); 193 axum::serve(listener, app(state)).await.unwrap(); 194 } ``` Exercising it with `curl` against the running server produces exactly this (tokens trimmed for brevity): ```text 1 # POST /login as the user "alice" 2 {"access_token": "eyJ0eXAiOiJKV1Qi...", "token_type": "Bearer", "expires_in": 900} 3 4 # GET /me with alice's token -> 200 5 {"role":"user","user":"alice"} 6 7 # GET /admin/metrics with alice's token -> 403 (authenticated but not an admin) 8 {"error":"you do not have permission to access this resource"} 9 10 # GET /admin/metrics with root's token -> 200 11 {"secret_metrics":42,"viewed_by":"root"} 12 13 # GET /me with no Authorization header -> 401 14 {"error":"missing or malformed Authorization header"} ``` The payoff: `profile` and `admin_metrics` contain **zero** auth code. The presence of `AuthUser` / `AdminUser` in their signatures means the router cannot route to them without a valid token (and the right role). Authentication and authorization are encoded in the function signature, checked once, and impossible to forget. > **Tip:** This `AuthUser` / `AdminUser` extractor pattern is the heart of the broader [Authentication](/16-web-apis/12-authentication/) page — here we focus on the JWT mechanics; that page compares extractor-guards against middleware-based auth more generally. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`jsonwebtoken` crate docs (docs.rs)](https://docs.rs/jsonwebtoken): `encode`, `decode`, `Validation`, `Header`, and the algorithm list. * [`Validation` (docs.rs)](https://docs.rs/jsonwebtoken/latest/jsonwebtoken/struct.Validation.html). Every knob: leeway, required claims, audience, issuer. * [RFC 7519: JSON Web Token](https://datatracker.ietf.org/doc/html/rfc7519): the spec, including the registered claim names (`exp`, `iat`, `iss`, `aud`, `sub`, `nbf`). * [jwt.io](https://jwt.io): paste a token to inspect its header and payload (a reminder that the payload is readable). * Within this guide: * [Authentication](/16-web-apis/12-authentication/): extractor-guard vs middleware auth; the `AuthUser` pattern in general. * [Extractors](/16-web-apis/04-extractors/): how `FromRequestParts` works and why ordering matters. * [Error Handling in Web Apps](/16-web-apis/10-error-handling-web/): `AppError: IntoResponse`, `thiserror`, mapping errors to status codes. * [Sessions](/16-web-apis/14-sessions/): cookie-based and server-side sessions, and where refresh tokens live. * [State Management](/16-web-apis/06-state-management/): holding your `Keys` in `State<T>` + `Arc`. * [Middleware](/16-web-apis/05-middleware/): Tower layers, if you prefer middleware-based auth. * [Section 27: Security](/27-security/): password hashing (Argon2) for the login step. * Background: [Error Handling](/08-error-handling/), [Serialization](/15-serialization/), [Traits](/09-generics-traits/). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Add audience and issuer validation [Section titled “Exercise 1: Add audience and issuer validation”](#exercise-1-add-audience-and-issuer-validation) **Difficulty:** Beginner **Objective:** Lock a token down to a specific `aud` (audience) and `iss` (issuer), and observe the rejection when they do not match. **Instructions:** Define a `Claims` struct with `sub`, `aud`, `iss`, and `exp`. Encode a token with `aud = "my-api"` and `iss = "my-auth-server"`. Build a `Validation` that calls `set_audience(&["my-api"])` and `set_issuer(&["my-auth-server"])`, and confirm a matching token decodes. Then build a second validator expecting `aud = "other-api"` and confirm it is rejected. Print the `ErrorKind` of the rejection. Solution ```rust 1 use jsonwebtoken::{ 2 decode, encode, errors::ErrorKind, get_current_timestamp, Algorithm, DecodingKey, 3 EncodingKey, Header, Validation, 4 }; 5 use serde::{Deserialize, Serialize}; 6 7 #[derive(Debug, Serialize, Deserialize)] 8 struct Claims { 9 sub: String, 10 aud: String, 11 iss: String, 12 exp: u64, 13 } 14 15 fn main() { 16 let secret = b"k"; 17 let claims = Claims { 18 sub: "user_1".into(), 19 aud: "my-api".into(), 20 iss: "my-auth-server".into(), 21 exp: get_current_timestamp() + 3600, 22 }; 23 let token = encode(&Header::default(), &claims, &EncodingKey::from_secret(secret)).unwrap(); 24 25 // Matching validator. 26 let mut v = Validation::new(Algorithm::HS256); 27 v.set_audience(&["my-api"]); 28 v.set_issuer(&["my-auth-server"]); 29 let ok = decode::<Claims>(&token, &DecodingKey::from_secret(secret), &v); 30 println!("matching aud+iss -> {:?}", ok.is_ok()); 31 32 // Wrong audience. 33 let mut v2 = Validation::new(Algorithm::HS256); 34 v2.set_audience(&["other-api"]); 35 match decode::<Claims>(&token, &DecodingKey::from_secret(secret), &v2) { 36 Err(e) if matches!(e.kind(), ErrorKind::InvalidAudience) => { 37 println!("wrong aud -> InvalidAudience") 38 } 39 Err(e) => println!("wrong aud -> {:?}", e.kind()), 40 Ok(_) => println!("wrong aud -> unexpectedly Ok"), 41 } 42 } ``` Real output: ```text 1 matching aud+iss -> true 2 wrong aud -> InvalidAudience ``` ### Exercise 2: Distinguish the rejection reasons [Section titled “Exercise 2: Distinguish the rejection reasons”](#exercise-2-distinguish-the-rejection-reasons) **Difficulty:** Intermediate **Objective:** Verify that the three common failures — wrong secret, expired token, and tampered body — surface as distinct `ErrorKind`s, and observe the default leeway. **Instructions:** Issue a valid HS256 token. Then (a) verify it with the wrong secret, (b) issue a token whose `exp` is in the past and verify it, and (c) flip one character in the middle of a valid token and verify it. Print the `ErrorKind` for each. Finally, issue a token that expired 30 seconds ago and show it still passes the default validator (60-second leeway). Solution ```rust 1 use jsonwebtoken::{ 2 decode, encode, get_current_timestamp, Algorithm, DecodingKey, EncodingKey, Header, 3 Validation, 4 }; 5 use serde::{Deserialize, Serialize}; 6 7 #[derive(Serialize, Deserialize)] 8 struct Claims { 9 sub: String, 10 exp: u64, 11 } 12 13 fn token_with_exp(secret: &[u8], exp: u64) -> String { 14 let claims = Claims { sub: "u".into(), exp }; 15 encode(&Header::default(), &claims, &EncodingKey::from_secret(secret)).unwrap() 16 } 17 18 fn verify(token: &str, secret: &[u8]) -> jsonwebtoken::errors::Result<()> { 19 decode::<Claims>(token, &DecodingKey::from_secret(secret), &Validation::new(Algorithm::HS256))?; 20 Ok(()) 21 } 22 23 fn main() { 24 let secret = b"super-secret-key"; 25 let now = get_current_timestamp(); 26 let token = token_with_exp(secret, now + 3600); 27 28 // (a) wrong secret 29 println!("wrong secret -> {:?}", verify(&token, b"nope").unwrap_err().kind()); 30 31 // (b) expired an hour ago 32 let expired = token_with_exp(secret, now - 3600); 33 println!("expired -> {:?}", verify(&expired, secret).unwrap_err().kind()); 34 35 // (c) tamper with one char 36 let mut chars: Vec<char> = token.chars().collect(); 37 let mid = chars.len() / 2; 38 chars[mid] = if chars[mid] == 'a' { 'b' } else { 'a' }; 39 let tampered: String = chars.into_iter().collect(); 40 println!("tampered -> {:?}", verify(&tampered, secret).unwrap_err().kind()); 41 42 // (d) leeway: expired 30s ago still passes the default 60s leeway 43 let recent = token_with_exp(secret, now - 30); 44 println!("expired 30s, 60s leeway -> {:?}", verify(&recent, secret).is_ok()); 45 } ``` Real output: ```text 1 wrong secret -> InvalidSignature 2 expired -> ExpiredSignature 3 tampered -> InvalidSignature 4 expired 30s, 60s leeway -> true ``` ### Exercise 3: A `RefreshToken` extractor that rejects access tokens [Section titled “Exercise 3: A RefreshToken extractor that rejects access tokens”](#exercise-3-a-refreshtoken-extractor-that-rejects-access-tokens) **Difficulty:** Hard **Objective:** Model two token *kinds* (`access` and `refresh`) with a `token_type` claim, and write an extractor that only accepts refresh tokens — so an attacker cannot present a short-lived access token at the `/refresh` endpoint. **Instructions:** Add a `token_type: TokenType` field to your claims (an enum serialized as a lowercase string). Issue access tokens at login and refresh tokens separately. Write a `RefreshToken` extractor (`FromRequestParts<AppState>`) that decodes the bearer token and then returns `AuthError::InvalidToken` unless `token_type == TokenType::Refresh`. Wire up `POST /refresh` that takes the `RefreshToken` extractor and mints a fresh access token. Solution ```rust 1 use axum::{ 2 extract::{FromRequestParts, State}, 3 http::{header, request::Parts, StatusCode}, 4 response::{IntoResponse, Response}, 5 routing::post, 6 Json, Router, 7 }; 8 use jsonwebtoken::{ 9 decode, encode, get_current_timestamp, Algorithm, DecodingKey, EncodingKey, Header, 10 Validation, 11 }; 12 use serde::{Deserialize, Serialize}; 13 use std::sync::Arc; 14 15 #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] 16 #[serde(rename_all = "lowercase")] 17 enum TokenType { 18 Access, 19 Refresh, 20 } 21 22 #[derive(Debug, Serialize, Deserialize)] 23 struct Claims { 24 sub: String, 25 token_type: TokenType, 26 exp: u64, 27 } 28 29 #[derive(Debug)] 30 enum AuthError { 31 MissingBearer, 32 InvalidToken, 33 } 34 35 impl IntoResponse for AuthError { 36 fn into_response(self) -> Response { 37 let msg = match self { 38 AuthError::MissingBearer => "missing bearer token", 39 AuthError::InvalidToken => "invalid token", 40 }; 41 (StatusCode::UNAUTHORIZED, Json(serde_json::json!({ "error": msg }))).into_response() 42 } 43 } 44 45 #[derive(Clone)] 46 struct AppState { 47 encoding: Arc<EncodingKey>, 48 decoding: Arc<DecodingKey>, 49 } 50 51 fn mint(state: &AppState, sub: &str, kind: TokenType, ttl: u64) -> String { 52 let claims = Claims { 53 sub: sub.to_string(), 54 token_type: kind, 55 exp: get_current_timestamp() + ttl, 56 }; 57 encode(&Header::default(), &claims, &state.encoding).unwrap() 58 } 59 60 // Only accepts tokens whose token_type is Refresh. 61 struct RefreshToken(Claims); 62 63 impl FromRequestParts<AppState> for RefreshToken { 64 type Rejection = AuthError; 65 66 async fn from_request_parts( 67 parts: &mut Parts, 68 state: &AppState, 69 ) -> Result<Self, Self::Rejection> { 70 let token = parts 71 .headers 72 .get(header::AUTHORIZATION) 73 .and_then(|v| v.to_str().ok()) 74 .and_then(|s| s.strip_prefix("Bearer ")) 75 .ok_or(AuthError::MissingBearer)?; 76 77 let validation = Validation::new(Algorithm::HS256); 78 let data = decode::<Claims>(token, &state.decoding, &validation) 79 .map_err(|_| AuthError::InvalidToken)?; 80 81 if data.claims.token_type != TokenType::Refresh { 82 return Err(AuthError::InvalidToken); 83 } 84 Ok(RefreshToken(data.claims)) 85 } 86 } 87 88 #[derive(Serialize)] 89 struct AccessTokenResponse { 90 access_token: String, 91 } 92 93 // Trade a valid refresh token for a fresh, short-lived access token. 94 async fn refresh( 95 State(state): State<AppState>, 96 RefreshToken(claims): RefreshToken, 97 ) -> Json<AccessTokenResponse> { 98 let access = mint(&state, &claims.sub, TokenType::Access, 15 * 60); 99 Json(AccessTokenResponse { access_token: access }) 100 } 101 102 fn app(state: AppState) -> Router { 103 Router::new().route("/refresh", post(refresh)).with_state(state) 104 } 105 106 #[tokio::main] 107 async fn main() { 108 let secret = std::env::var("JWT_SECRET") 109 .expect("JWT_SECRET must be set to at least 32 unpredictable bytes"); 110 assert!(secret.as_bytes().len() >= 32, "JWT_SECRET is too short"); 111 let state = AppState { 112 encoding: Arc::new(EncodingKey::from_secret(secret.as_bytes())), 113 decoding: Arc::new(DecodingKey::from_secret(secret.as_bytes())), 114 }; 115 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 116 axum::serve(listener, app(state)).await.unwrap(); 117 } ``` Presenting a refresh token at `POST /refresh` returns `200` with a new `access_token`. Presenting an *access* token (or no token) returns `401 {"error":"invalid token"}`, because the extractor rejects any `token_type` that is not `Refresh` before the handler runs. This is exactly why the `token_type` claim matters: signature validity alone is not enough — the token must be the *right kind* for the endpoint. # Sessions and Cookies > Replace Express express-session with Axum's tower-sessions: a session layer, a Session extractor, server-side stores (memory, SQLx, Redis), signed cookies, and CSRF. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **session** is how a stateless HTTP server remembers who you are between requests: the server stores some data, hands the browser a small opaque **cookie**, and the browser returns that cookie on every subsequent request. In Express you reach for `express-session`; in Axum the equivalent is the **`tower-sessions`** crate, which adds a session layer to your `Router` and gives every handler a `Session` extractor. This chapter maps the Express session/cookie workflow onto Axum, covers server-side stores (memory, SQLx, Redis) versus signed client-side cookies, and explains the **CSRF** considerations that come with cookie-based auth. > **Note:** This page is about *sessions* — server-remembered state keyed by a cookie. If you are issuing stateless bearer tokens instead, see [JWT](/16-web-apis/13-jwt/). For the broader question of where auth checks live (guards, middleware), see [Authentication](/16-web-apis/12-authentication/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Here is a typical Express app using `express-session` with a cookie-based login flow: ```typescript 1 // app.ts — Express sessions with express-session 2 import express, { Request, Response } from "express"; 3 import session from "express-session"; 4 5 // Augment the session type so `req.session.user` is typed. 6 declare module "express-session" { 7 interface SessionData { 8 user?: { id: number; username: string }; 9 } 10 } 11 12 const app = express(); 13 app.use(express.json()); 14 const sessionSecret = process.env.SESSION_SECRET; 15 if (!sessionSecret || Buffer.byteLength(sessionSecret, "utf8") < 32) { 16 throw new Error("SESSION_SECRET must contain at least 32 unpredictable bytes"); 17 } 18 19 app.use( 20 session({ 21 name: "id", // cookie name 22 secret: sessionSecret, 23 resave: false, 24 saveUninitialized: false, 25 cookie: { 26 httpOnly: true, // JS cannot read the cookie 27 secure: true, // HTTPS only 28 sameSite: "lax", // sent on top-level navigations, blocked on cross-site POSTs 29 maxAge: 1000 * 60 * 60 * 2, // 2 hours 30 }, 31 }), 32 ); 33 34 app.post("/login", (req: Request, res: Response) => { 35 const { username, password } = req.body; 36 if (username !== "alice" || password !== "correct horse") { 37 return res.status(401).send("invalid credentials"); 38 } 39 // Prevent session fixation: rotate the session ID on privilege change. 40 req.session.regenerate(() => { 41 req.session.user = { id: 1, username }; 42 res.send("logged in"); 43 }); 44 }); 45 46 app.get("/me", (req: Request, res: Response) => { 47 if (!req.session.user) return res.status(401).send("not logged in"); 48 res.json(req.session.user); 49 }); 50 51 app.post("/logout", (req: Request, res: Response) => { 52 req.session.destroy(() => res.redirect("/")); 53 }); 54 55 app.listen(3000); ``` **Key points:** * `app.use(session(...))` adds session middleware globally; every handler then sees `req.session`. * The cookie carries only an opaque **session ID**; the `user` object lives server-side (in memory by default, or Redis/Postgres in production). * `req.session.user = ...` writes; reading `req.session.user` reads; `req.session.destroy()` deletes. * `regenerate()` swaps the session ID to defend against **session fixation**. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Axum delegates sessions to the **`tower-sessions`** crate. You add a `SessionManagerLayer` (the analog of `app.use(session(...))`) and every handler can extract a `Session`. Add the dependencies: ```bash 1 cargo new my-api 2 cd my-api 3 cargo add axum@0.8 4 cargo add tokio@1 --features full 5 cargo add tower-sessions@0.14 6 cargo add serde --features derive 7 cargo add time ``` > **Note:** `tower-sessions` is pinned to `0.14` here, not the absolute latest `tower-sessions` release. The official store crates (`tower-sessions-sqlx-store`, `tower-sessions-redis-store`) currently target the `tower-sessions-core` `0.14` line, so pinning the facade crate to `0.14` keeps every part of the ecosystem on one `-core` version. The `Session` API used below is identical across these releases. See the version-mismatch pitfall below for the exact error you hit if you mix them. ```rust 1 // src/main.rs — equivalent Axum session flow 2 use axum::{ 3 Router, 4 routing::{get, post}, 5 extract::Json, 6 response::{IntoResponse, Redirect}, 7 http::StatusCode, 8 }; 9 use serde::{Deserialize, Serialize}; 10 use tower_sessions::{Session, SessionManagerLayer, MemoryStore, Expiry}; 11 use time::Duration; 12 13 // What we keep in the session. Any Serialize + Deserialize type works. 14 #[derive(Serialize, Deserialize, Clone)] 15 struct SessionUser { 16 id: u64, 17 username: String, 18 } 19 20 // The key under which we store the user inside the session map. 21 const USER_KEY: &str = "user"; 22 23 #[derive(Deserialize)] 24 struct LoginForm { 25 username: String, 26 password: String, 27 } 28 29 // POST /login — verify credentials, then write the user into the session. 30 async fn login(session: Session, Json(form): Json<LoginForm>) -> impl IntoResponse { 31 // Pretend we looked this up in a database and verified the password hash. 32 if form.username != "alice" || form.password != "correct horse" { 33 return (StatusCode::UNAUTHORIZED, "invalid credentials").into_response(); 34 } 35 36 let user = SessionUser { id: 1, username: form.username }; 37 38 // Rotate the session ID on privilege change to prevent session fixation. 39 session.cycle_id().await.expect("failed to cycle session id"); 40 session.insert(USER_KEY, user).await.expect("failed to write session"); 41 42 (StatusCode::OK, "logged in").into_response() 43 } 44 45 // GET /me — read the user back out of the session (None if not logged in). 46 async fn me(session: Session) -> impl IntoResponse { 47 match session.get::<SessionUser>(USER_KEY).await { 48 Ok(Some(user)) => (StatusCode::OK, Json(user)).into_response(), 49 Ok(None) => (StatusCode::UNAUTHORIZED, "not logged in").into_response(), 50 Err(_) => (StatusCode::INTERNAL_SERVER_ERROR, "session error").into_response(), 51 } 52 } 53 54 // POST /logout — destroy the whole server-side session. 55 async fn logout(session: Session) -> impl IntoResponse { 56 session.delete().await.expect("failed to delete session"); 57 Redirect::to("/") 58 } 59 60 #[tokio::main] 61 async fn main() { 62 // In-memory store: fine for a demo, lost on restart. Use Redis/SQL in prod. 63 let store = MemoryStore::default(); 64 let session_layer = SessionManagerLayer::new(store) 65 .with_secure(true) // Secure flag: HTTPS only 66 .with_http_only(true) // JS cannot read the cookie 67 .with_same_site(tower_sessions::cookie::SameSite::Lax) 68 .with_name("id") // cookie name 69 .with_expiry(Expiry::OnInactivity(Duration::hours(2))); 70 71 let app = Router::new() 72 .route("/login", post(login)) 73 .route("/me", get(me)) 74 .route("/logout", post(logout)) 75 .layer(session_layer); 76 77 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 78 axum::serve(listener, app).await.unwrap(); 79 } ``` Hitting this server through HTTPS shows the same cookie-based flow as Express. With `with_secure(true)` as configured above, `POST /login` returns: ```text 1 HTTP/1.1 200 OK 2 set-cookie: id=KT9nUyq52viouFYYwWJFkQ; HttpOnly; SameSite=Lax; Secure; Path=/; Max-Age=7200 ``` That `id=...` value is the opaque session ID. Note it is **not** the username or any user data. Sending the cookie back to `GET /me` returns the stored user (`{"id":1,"username":"alice"}`), and `POST /logout` returns `303 See Other` and wipes the server-side session, so a subsequent `GET /me` replies `not logged in`. > **Tip:** The safe default above intentionally does not work through plain HTTP: browsers refuse to return a `Secure` cookie there. For a local-only `http://localhost` exercise you may temporarily set `with_secure(false)`, but keep that override in development configuration and require `true` at startup in production. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The layer is the middleware [Section titled “The layer is the middleware”](#the-layer-is-the-middleware) `SessionManagerLayer::new(store)` is the Tower layer that does what `app.use(session(...))` does in Express: on each request it reads the session-ID cookie, loads (or lazily creates) the session, and after the handler runs it persists any changes and emits a `Set-Cookie` header if needed. Because it is a layer, it follows the same composition rules as every other Axum middleware; see [Middleware and Layers](/16-web-apis/05-middleware/). Apply it with `.layer(...)` so it wraps all routes that need sessions. ### `Session` is an extractor [Section titled “Session is an extractor”](#session-is-an-extractor) Once the layer is installed, any handler can take a `Session` parameter and Axum injects it, exactly like `Path`, `Query`, or `State` (see [Extractors](/16-web-apis/04-extractors/)). The `Session` itself is a cheap, cloneable handle to an in-memory map that the layer flushes to the store at the end of the request. Its core methods mirror `req.session`: | Express | `tower-sessions` | | ---------------------------- | -------------------------------------- | | `req.session.user = value` | `session.insert("user", value).await?` | | `req.session.user` (read) | `session.get::<T>("user").await?` | | `delete req.session.user` | `session.remove::<T>("user").await?` | | `req.session.destroy(cb)` | `session.delete().await?` | | `req.session.regenerate(cb)` | `session.cycle_id().await?` | ### Everything is `async` and returns `Result` [Section titled “Everything is async and returns Result”](#everything-is-async-and-returns-result) This is the biggest difference from Express. `req.session.user` in Express is a synchronous property access. In Rust, `session.get`/`insert`/`delete` are **async** because the backing store might be a database or Redis, and they return `Result` because that I/O can fail. So you `.await` them and handle the error. That is why `me` matches on `Ok(Some(_))` / `Ok(None)` / `Err(_)` instead of a simple truthiness check. For why these futures must be awaited and do nothing until polled, see [Async/Await](/11-async/). ### Values must be serializable [Section titled “Values must be serializable”](#values-must-be-serializable) `session.insert` has the signature `pub async fn insert(&self, key: &str, value: impl Serialize)`. The store serializes your value (the memory store keeps the deserialized form; SQL/Redis stores serialize to bytes), and `get::<T>` deserializes it back, so `T` must implement `serde::Serialize + DeserializeOwned`. That is why `SessionUser` derives `Serialize, Deserialize`. This is stricter than Express, where you can stash any JS object on `req.session` — but it is the same discipline as [Serialization with serde](/15-serialization/). ### `cycle_id` defends against session fixation [Section titled “cycle\_id defends against session fixation”](#cycle_id-defends-against-session-fixation) `session.cycle_id()` issues a fresh session ID while keeping the data, the analog of Express’s `req.session.regenerate()`. Call it right after a successful login so an attacker who planted a known session ID before login cannot ride the authenticated session afterward. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | Express (`express-session`) | Axum (`tower-sessions`) | | ----------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------- | | Install | `app.use(session({...}))` | `.layer(SessionManagerLayer::new(store))` | | Access in handler | `req.session` (always present) | `session: Session` extractor parameter | | Read/write | Synchronous property access | `async` methods returning `Result` | | Stored value type | Any JS value | Must be `Serialize + DeserializeOwned` | | Default store | `MemoryStore` (with a warning) | `MemoryStore` (explicit; you must choose) | | Cookie config | `cookie: { httpOnly, secure, sameSite }` | `.with_http_only(_)`, `.with_secure(_)`, `.with_same_site(_)` | | Rotate ID | `req.session.regenerate(cb)` | `session.cycle_id().await?` | | Destroy | `req.session.destroy(cb)` | `session.delete().await?` | | Signing secret | `secret:` (always signs the cookie) | The store ID is opaque; cookies are signed only with the `signed`/`private` cookie controllers | ### Why an opaque ID instead of a signed payload? [Section titled “Why an opaque ID instead of a signed payload?”](#why-an-opaque-id-instead-of-a-signed-payload) Both frameworks default to a **server-side** session: the cookie holds only a random ID and the real data lives in the store. The cookie does not need to be cryptographically signed for the data to be safe, because the data never leaves the server: guessing another user’s random ID is the only attack, and IDs are 128-bit random values. The alternative — putting signed data *in* the cookie — is covered under “Best Practices” below; it trades server storage for cookie size and revocation difficulty. ### Lazy persistence [Section titled “Lazy persistence”](#lazy-persistence) `tower-sessions` only writes to the store and only emits a `Set-Cookie` header when the session actually changed during the request. A handler that merely reads the session produces no `Set-Cookie`. This is similar to `express-session`’s `saveUninitialized: false` / `resave: false`, but it is the default and not configurable away. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Storing a non-serializable value [Section titled “Pitfall 1: Storing a non-serializable value”](#pitfall-1-storing-a-non-serializable-value) Because the store must serialize whatever you insert, trying to stash a type that is not `Serialize` is a compile error, not a runtime surprise: ```rust 1 use tower_sessions::Session; 2 use std::time::Instant; // Instant is NOT Serialize 3 4 async fn handler(session: Session) { 5 // does not compile (E0277: Instant does not implement serde::Serialize) 6 session.insert("started", Instant::now()).await.unwrap(); 7 } ``` The real compiler error is: ```text 1 error[E0277]: the trait bound `std::time::Instant: serde::Serialize` is not satisfied 2 --> src/bin/err_nonserialize.rs:7:31 3 | 4 7 | session.insert("started", Instant::now()).await.unwrap(); 5 | ------ ^^^^^^^^^^^^^^ the trait `serde_core::ser::Serialize` is not implemented for `std::time::Instant` 6 | | 7 | required by a bound introduced by this call 8 | 9 = note: for types from other crates check whether the crate offers a `serde` feature flag 10 note: required by a bound in `tower_sessions::Session::insert` ``` The fix is to store something serializable. For a timestamp, use a `time::OffsetDateTime` (with serde) or store the seconds since epoch as an `i64`. ### Pitfall 2: Forgetting the layer [Section titled “Pitfall 2: Forgetting the layer”](#pitfall-2-forgetting-the-layer) If you take a `Session` extractor but never add the `SessionManagerLayer`, the handler will fail at runtime, not compile time: the extractor cannot find the session in the request extensions. The error surfaces as a `500` with a message about a missing required extension. Always remember the layer is what *provides* the extractor, exactly like `State` needs `.with_state(...)`. See [State Management](/16-web-apis/06-state-management/) for the same provide-then-extract pattern. ### Pitfall 3: Mixing incompatible store versions [Section titled “Pitfall 3: Mixing incompatible store versions”](#pitfall-3-mixing-incompatible-store-versions) The store crates lag the facade crate, so a naive `cargo add tower-sessions` + `cargo add tower-sessions-sqlx-store` can pull in two different `tower-sessions-core` versions. The trait bound then fails with a confusing message: ```text 1 error[E0277]: the trait bound `SqliteStore: SessionStore` is not satisfied 2 | 3 note: there are multiple different versions of crate `tower_sessions_core` in the dependency graph 4 | 5 4 | use tower_sessions::{Session, SessionManagerLayer, Expiry}; 6 | -------------- one version of crate `tower_sessions_core` used here, as a dependency of crate `tower_sessions` 7 5 | use tower_sessions_sqlx_store::SqliteStore; 8 | ------------------------- one version of crate `tower_sessions_core` used here, as a dependency of crate `tower_sessions_sqlx_store` ``` The fix is to pin `tower-sessions` to the version line the store targets (here, `tower-sessions = "0.14"` to match `tower-sessions-sqlx-store = "0.15"`). When you add a store, check its `tower-sessions-core` dependency and align the facade crate to it. This is the same kind of duplicate-version trap covered in [Modules and Packages](/12-modules-packages/). ### Pitfall 4: Assuming `same_site` “lax” stops all CSRF [Section titled “Pitfall 4: Assuming same\_site “lax” stops all CSRF”](#pitfall-4-assuming-same_site-lax-stops-all-csrf) `SameSite=Lax` (the default both frameworks use) blocks the cookie on *cross-site* sub-requests like an attacker’s hidden `<form>` POST, which neutralizes the classic CSRF attack for most apps. But it is not a complete defense: `GET` requests count as “safe” navigations and still carry the cookie, and `SameSite` is browser-enforced (older or non-browser clients ignore it). For state-changing endpoints, add an explicit anti-CSRF token (shown below). Do **not** treat `SameSite=Lax` as a license to skip CSRF tokens on sensitive operations. ### Pitfall 5: Leaving the `MemoryStore` in production [Section titled “Pitfall 5: Leaving the MemoryStore in production”](#pitfall-5-leaving-the-memorystore-in-production) `MemoryStore` keeps sessions in a process-local `HashMap`: they vanish on restart and are not shared across multiple instances behind a load balancer (a user “logs out” whenever they hit a different replica). It is great for tests and demos, but pick a persistent, shared store (SQL or Redis) before you scale past one process — exactly as you would replace `express-session`’s default `MemoryStore`, which prints a warning for the same reason. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Always set the cookie security flags [Section titled “Always set the cookie security flags”](#always-set-the-cookie-security-flags) Configure the layer explicitly rather than relying on defaults: ```rust 1 use tower_sessions::{SessionManagerLayer, MemoryStore, Expiry, cookie::SameSite}; 2 use time::Duration; 3 4 fn session_layer() -> SessionManagerLayer<MemoryStore> { 5 SessionManagerLayer::new(MemoryStore::default()) 6 .with_secure(true) // HTTPS only 7 .with_http_only(true) // not readable from JS — blocks XSS cookie theft 8 .with_same_site(SameSite::Lax) // blocks cross-site sends of the cookie 9 .with_name("id") // a neutral name that does not advertise the stack 10 .with_expiry(Expiry::OnInactivity(Duration::hours(2))) 11 } ``` `HttpOnly` is your XSS mitigation (script cannot read the cookie), `Secure` is your eavesdropping mitigation, and `SameSite` is your first line of CSRF defense. ### Wrap the session API in a typed helper [Section titled “Wrap the session API in a typed helper”](#wrap-the-session-api-in-a-typed-helper) Repeating `session.get::<SessionUser>("user")` everywhere invites typos in the key. Centralize it: ```rust 1 use tower_sessions::Session; 2 use serde::{Deserialize, Serialize}; 3 4 #[derive(Serialize, Deserialize, Clone)] 5 struct SessionUser { 6 id: u64, 7 username: String, 8 } 9 10 const USER_KEY: &str = "user"; 11 12 async fn current_user(session: &Session) -> Option<SessionUser> { 13 session.get::<SessionUser>(USER_KEY).await.ok().flatten() 14 } 15 16 async fn set_current_user(session: &Session, user: SessionUser) { 17 let _ = session.insert(USER_KEY, user).await; 18 } ``` This is the seam where a custom guard extractor naturally lives: turn the session lookup into an `AuthUser` extractor so handlers can declare “I need a logged-in user” in their signature (see the Real-World Example). ### Choose the right store for your topology [Section titled “Choose the right store for your topology”](#choose-the-right-store-for-your-topology) * **`MemoryStore`** — tests and single-process demos only. * **`tower-sessions-sqlx-store`** (`SqliteStore` / `PostgresStore` / `MySqlStore`) — when you already run a SQL database; survives restarts, shared across replicas. Reuses the [database connection pool](/17-database/) you already have. * **`tower-sessions-redis-store`** (`RedisStore`) — when you want fast, ephemeral, easily-expiring session storage and already run Redis. ### Prefer server-side sessions; reach for signed cookies deliberately [Section titled “Prefer server-side sessions; reach for signed cookies deliberately”](#prefer-server-side-sessions-reach-for-signed-cookies-deliberately) A client-side **signed cookie** stores the data *in* the cookie, signed so the client cannot tamper with it (but can read it). It needs no server storage, which is appealing for horizontally-scaled stateless services. The trade-offs: the cookie is bigger, the data is visible to the client, and you cannot revoke a session before it expires (there is nothing server-side to delete). Use `axum-extra`’s `SignedCookieJar` (or `PrivateCookieJar` for encrypted, non-readable values) when those trade-offs are acceptable: ```bash 1 cargo add axum-extra --features cookie-signed ``` ```rust 1 use axum::{Router, routing::get, response::IntoResponse}; 2 use axum_extra::extract::cookie::{Cookie, Key, SignedCookieJar}; 3 4 // A signed (tamper-evident) client-side cookie — no server storage at all. 5 // The value is visible to the client but cannot be modified without the key. 6 async fn set_cookie(jar: SignedCookieJar) -> impl IntoResponse { 7 jar.add(Cookie::new("theme", "dark")) 8 } 9 10 async fn read_cookie(jar: SignedCookieJar) -> impl IntoResponse { 11 match jar.get("theme") { 12 Some(c) => format!("theme = {}", c.value()), 13 None => "no theme set".to_string(), 14 } 15 } 16 17 #[tokio::main] 18 async fn main() { 19 // The signing key. Generate once with Key::generate() and load it from an 20 // env var / secret manager in production — never hard-code it. 21 let key = Key::generate(); 22 23 let app = Router::new() 24 .route("/set", get(set_cookie)) 25 .route("/read", get(read_cookie)) 26 // SignedCookieJar reads the key out of router state via FromRef. 27 .with_state(key); 28 29 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 30 axum::serve(listener, app).await.unwrap(); 31 } ``` *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production session setup wants three things the demo lacked: a **persistent store** so sessions survive restarts and span replicas, a **guard extractor** so protected handlers stay terse, and **CSRF protection** for state-changing routes. Here is a compile-verified slice that ties them together. First, the auth guard. By implementing `FromRequestParts`, you make `AuthUser` an extractor that *fails the request* with `401` when there is no logged-in user; protected handlers just list it as a parameter (the pattern from [Authentication](/16-web-apis/12-authentication/), backed here by the session): ```rust 1 // src/auth.rs — a session-backed guard extractor 2 use axum::{ 3 extract::FromRequestParts, 4 http::{request::Parts, StatusCode}, 5 response::{IntoResponse, Response}, 6 }; 7 use serde::{Deserialize, Serialize}; 8 use tower_sessions::Session; 9 10 #[derive(Serialize, Deserialize, Clone)] 11 pub struct SessionUser { 12 pub id: u64, 13 pub username: String, 14 } 15 16 pub const USER_KEY: &str = "user"; 17 18 // A guard extractor: a handler that takes `AuthUser` only runs for logged-in users. 19 pub struct AuthUser(pub SessionUser); 20 21 impl<S> FromRequestParts<S> for AuthUser 22 where 23 S: Send + Sync, 24 { 25 type Rejection = Response; 26 27 async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> { 28 // Pull the Session out of the request first (the session layer inserted it). 29 let session = Session::from_request_parts(parts, state) 30 .await 31 .map_err(|(status, msg)| (status, msg).into_response())?; 32 33 match session.get::<SessionUser>(USER_KEY).await { 34 Ok(Some(user)) => Ok(AuthUser(user)), 35 Ok(None) => Err((StatusCode::UNAUTHORIZED, "login required").into_response()), 36 Err(_) => Err((StatusCode::INTERNAL_SERVER_ERROR, "session error").into_response()), 37 } 38 } 39 } ``` A protected handler now declares its requirement in its signature; no in-body auth check: ```rust 1 use axum::{response::IntoResponse, Json}; 2 // use crate::auth::AuthUser; // (same crate in a real project) 3 4 // This handler is only reachable with a valid session — the extractor enforces it. 5 async fn dashboard(AuthUser(user): AuthUser) -> impl IntoResponse { 6 Json(user) 7 } ``` Next, a **synchronizer CSRF token**: mint a random token, store it in the server-side session, and require the client to echo it in a header on state-changing requests. An attacker’s cross-site request cannot read the token out of the session, so it cannot forge the header: ```bash 1 cargo add rand@0.9 ``` ```rust 1 // src/csrf.rs — synchronizer-token CSRF protection backed by the session 2 use axum::{ 3 response::IntoResponse, 4 http::{HeaderMap, StatusCode}, 5 }; 6 use rand::Rng; 7 use tower_sessions::Session; 8 9 const CSRF_KEY: &str = "csrf_token"; 10 11 fn random_token() -> String { 12 // 32 random bytes, hex-encoded — unpredictable per session. 13 let bytes: [u8; 32] = rand::rng().random(); 14 bytes.iter().map(|b| format!("{b:02x}")).collect() 15 } 16 17 // GET /form — mint a CSRF token, store it in the session, and hand it to the page. 18 async fn show_form(session: Session) -> impl IntoResponse { 19 let token = random_token(); 20 session.insert(CSRF_KEY, token.clone()).await.unwrap(); 21 // The page embeds `token` in a hidden field or a meta tag for the JS client. 22 format!("csrf token: {token}") 23 } 24 25 // POST /transfer — reject the request unless the submitted token matches the session. 26 async fn transfer(session: Session, headers: HeaderMap) -> impl IntoResponse { 27 let expected: Option<String> = session.get(CSRF_KEY).await.unwrap(); 28 let provided = headers.get("x-csrf-token").and_then(|v| v.to_str().ok()); 29 30 match (expected.as_deref(), provided) { 31 (Some(want), Some(got)) if want == got => { 32 (StatusCode::OK, "transfer accepted").into_response() 33 } 34 _ => (StatusCode::FORBIDDEN, "CSRF check failed").into_response(), 35 } 36 } ``` > **Note:** For a true constant-time comparison of the tokens (to avoid a timing side-channel), use the `subtle` crate’s `ConstantTimeEq` instead of `==`. For most apps the random 256-bit token makes a timing attack impractical, but constant-time is the belt-and-suspenders choice. Finally, the **persistent SQL store**. Reuse a `sqlx` pool (the same one your data layer uses — see [Connection Pooling](/17-database/)) so sessions live in the database. Note the matched versions: `tower-sessions = "0.14"` alongside `tower-sessions-sqlx-store = "0.15"`: ```bash 1 cargo add tower-sessions@0.14 2 cargo add tower-sessions-sqlx-store@0.15 --features sqlite 3 cargo add sqlx --features "runtime-tokio,sqlite" ``` ```rust 1 // src/main.rs — Axum with a persistent SQLite-backed session store 2 use axum::{Router, routing::get, response::IntoResponse}; 3 use sqlx::sqlite::SqlitePoolOptions; 4 use time::Duration; 5 use tower_sessions::{Session, SessionManagerLayer, Expiry}; 6 use tower_sessions_sqlx_store::SqliteStore; 7 8 const COUNTER_KEY: &str = "counter"; 9 10 async fn count(session: Session) -> impl IntoResponse { 11 let n: usize = session.get(COUNTER_KEY).await.unwrap().unwrap_or(0) + 1; 12 session.insert(COUNTER_KEY, n).await.unwrap(); 13 format!("visit #{n}") 14 } 15 16 #[tokio::main] 17 async fn main() -> Result<(), Box<dyn std::error::Error>> { 18 // A real connection pool — sessions now survive process restarts. 19 let pool = SqlitePoolOptions::new().connect("sqlite::memory:").await?; 20 21 let store = SqliteStore::new(pool); 22 store.migrate().await?; // creates the session table if it does not exist 23 24 let session_layer = SessionManagerLayer::new(store) 25 .with_secure(true) 26 .with_expiry(Expiry::OnInactivity(Duration::days(1))); 27 28 let app = Router::new() 29 .route("/count", get(count)) 30 .layer(session_layer); 31 32 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await?; 33 axum::serve(listener, app).await?; 34 Ok(()) 35 } ``` Swap `SqliteStore` + `SqlitePoolOptions` for `PostgresStore` + `PgPoolOptions` (feature `postgres`) in production. The handler code does not change; only the store and pool type do, which is the whole point of the `SessionStore` trait abstraction. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [`tower-sessions` crate docs](https://docs.rs/tower-sessions/) — the `Session` API, `SessionManagerLayer`, cookie configuration, and `Expiry` * [`tower-sessions-sqlx-store`](https://docs.rs/tower-sessions-sqlx-store/) and [`tower-sessions-redis-store`](https://docs.rs/tower-sessions-redis-store/) — persistent backends * [`axum-extra` cookie extractors](https://docs.rs/axum-extra/latest/axum_extra/extract/cookie/index.html) — `CookieJar`, `SignedCookieJar`, `PrivateCookieJar` * [MDN: `Set-Cookie` and `SameSite`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie) — the cookie attributes the layer emits * [OWASP: Session Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html) and [CSRF Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html) ### Related Topics [Section titled “Related Topics”](#related-topics) * [Authentication](/16-web-apis/12-authentication/): where auth checks live; turning the session lookup into a guard * [JWT](/16-web-apis/13-jwt/) — the stateless, token-based alternative to server-side sessions * [Extractors](/16-web-apis/04-extractors/): how `Session` and a custom `AuthUser` are injected * [Middleware and Layers](/16-web-apis/05-middleware/) — the layer mechanism `SessionManagerLayer` plugs into * [State Management](/16-web-apis/06-state-management/): the `provide-then-extract` pattern, and sharing the DB pool * [Request and Response](/16-web-apis/07-request-response/) — `IntoResponse`, status codes, and setting headers * [CORS](/16-web-apis/11-cors/): cross-origin rules that interact with cookie credentials * [Serialization](/15-serialization/) — why session values need `Serialize`/`Deserialize` * [Async/Await](/11-async/) — why session methods are awaited * Next section: [Databases](/17-database/) — the SQL pool a persistent session store reuses *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A per-session visit counter [Section titled “Exercise 1: A per-session visit counter”](#exercise-1-a-per-session-visit-counter) **Difficulty:** Easy **Objective:** Practice the read-modify-write session cycle with a non-string value. **Instructions:** 1. Start an Axum app with a `MemoryStore`-backed `SessionManagerLayer`. 2. Add a `GET /count` route whose handler reads a `usize` under the key `"counter"` (defaulting to `0` when absent), increments it, writes it back, and returns `"You have visited this page N time(s) in this session."`. 3. Verify that repeated requests *with the same cookie* increment, while a fresh client starts again at 1. Solution ```rust 1 use axum::{Router, routing::get, response::IntoResponse}; 2 use tower_sessions::{Session, SessionManagerLayer, MemoryStore}; 3 4 const COUNTER_KEY: &str = "counter"; 5 6 // GET /count — increment a per-session view counter and report it. 7 async fn count(session: Session) -> impl IntoResponse { 8 // get::<T> returns Result<Option<T>>; default to 0 the first time. 9 let n: usize = session.get(COUNTER_KEY).await.unwrap().unwrap_or(0); 10 let n = n + 1; 11 session.insert(COUNTER_KEY, n).await.unwrap(); 12 format!("You have visited this page {n} time(s) in this session.") 13 } 14 15 #[tokio::main] 16 async fn main() { 17 let app = Router::new() 18 .route("/count", get(count)) 19 .layer(SessionManagerLayer::new(MemoryStore::default())); 20 21 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 22 axum::serve(listener, app).await.unwrap(); 23 } ``` Dependencies: `cargo add axum@0.8 tokio@1 --features full` (tokio) and `cargo add tower-sessions@0.14`. Because `get::<usize>` returns `Result<Option<usize>>`, `.unwrap().unwrap_or(0)` turns “no error, no value yet” into `0`. ### Exercise 2: A login/logout flow with a guard extractor [Section titled “Exercise 2: A login/logout flow with a guard extractor”](#exercise-2-a-loginlogout-flow-with-a-guard-extractor) **Difficulty:** Medium **Objective:** Combine writing the session at login with a custom `FromRequestParts` extractor that protects a route. **Instructions:** 1. Define `SessionUser { id, username }` deriving `Serialize, Deserialize, Clone`. 2. Add `POST /login` that (for hard-coded valid credentials) calls `cycle_id()` then stores the user, and `POST /logout` that calls `session.delete()`. 3. Implement an `AuthUser` extractor that pulls the `Session`, reads the user, and rejects with `401` when absent. 4. Add a `GET /profile` handler taking `AuthUser` and returning the user as JSON. Solution ```rust 1 use axum::{ 2 Router, 3 routing::{get, post}, 4 extract::{Json, FromRequestParts}, 5 response::{IntoResponse, Response, Redirect}, 6 http::{StatusCode, request::Parts}, 7 }; 8 use serde::{Deserialize, Serialize}; 9 use tower_sessions::{Session, SessionManagerLayer, MemoryStore}; 10 11 #[derive(Serialize, Deserialize, Clone)] 12 struct SessionUser { 13 id: u64, 14 username: String, 15 } 16 17 const USER_KEY: &str = "user"; 18 19 #[derive(Deserialize)] 20 struct LoginForm { 21 username: String, 22 password: String, 23 } 24 25 struct AuthUser(SessionUser); 26 27 impl<S> FromRequestParts<S> for AuthUser 28 where 29 S: Send + Sync, 30 { 31 type Rejection = Response; 32 33 async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> { 34 let session = Session::from_request_parts(parts, state) 35 .await 36 .map_err(|(s, m)| (s, m).into_response())?; 37 match session.get::<SessionUser>(USER_KEY).await { 38 Ok(Some(user)) => Ok(AuthUser(user)), 39 Ok(None) => Err((StatusCode::UNAUTHORIZED, "login required").into_response()), 40 Err(_) => Err((StatusCode::INTERNAL_SERVER_ERROR, "session error").into_response()), 41 } 42 } 43 } 44 45 async fn login(session: Session, Json(form): Json<LoginForm>) -> impl IntoResponse { 46 if form.username != "alice" || form.password != "correct horse" { 47 return (StatusCode::UNAUTHORIZED, "invalid credentials").into_response(); 48 } 49 session.cycle_id().await.unwrap(); 50 session 51 .insert(USER_KEY, SessionUser { id: 1, username: form.username }) 52 .await 53 .unwrap(); 54 (StatusCode::OK, "logged in").into_response() 55 } 56 57 async fn logout(session: Session) -> impl IntoResponse { 58 session.delete().await.unwrap(); 59 Redirect::to("/") 60 } 61 62 async fn profile(AuthUser(user): AuthUser) -> impl IntoResponse { 63 Json(user) 64 } 65 66 #[tokio::main] 67 async fn main() { 68 let app = Router::new() 69 .route("/login", post(login)) 70 .route("/logout", post(logout)) 71 .route("/profile", get(profile)) 72 .layer(SessionManagerLayer::new(MemoryStore::default())); 73 74 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 75 axum::serve(listener, app).await.unwrap(); 76 } ``` The `AuthUser` extractor is the key idea: protected handlers declare `AuthUser` in their signature and the framework rejects anonymous requests *before* the handler body runs, no manual `if (!user) return 401` in every handler. ### Exercise 3: Session-backed synchronizer-token CSRF protection [Section titled “Exercise 3: Session-backed synchronizer-token CSRF protection”](#exercise-3-session-backed-synchronizer-token-csrf-protection) **Difficulty:** Hard **Objective:** Defend a state-changing endpoint with a session-stored CSRF token, and reason about why it works. **Instructions:** 1. Add a `GET /form` route that generates a random token, stores it in the session under `"csrf_token"`, and returns it to the client. 2. Add a `POST /transfer` route that reads the stored token from the session and compares it to an `x-csrf-token` request header, returning `403` on mismatch and `200` on match. 3. In a comment, explain why an attacker’s cross-site form POST cannot pass this check even though the browser *does* send the session cookie. Solution ```rust 1 use axum::{ 2 Router, 3 routing::{get, post}, 4 response::IntoResponse, 5 http::{HeaderMap, StatusCode}, 6 }; 7 use rand::Rng; 8 use tower_sessions::{Session, SessionManagerLayer, MemoryStore}; 9 10 const CSRF_KEY: &str = "csrf_token"; 11 12 fn random_token() -> String { 13 let bytes: [u8; 32] = rand::rng().random(); 14 bytes.iter().map(|b| format!("{b:02x}")).collect() 15 } 16 17 async fn show_form(session: Session) -> impl IntoResponse { 18 let token = random_token(); 19 session.insert(CSRF_KEY, token.clone()).await.unwrap(); 20 format!("csrf token: {token}") 21 } 22 23 async fn transfer(session: Session, headers: HeaderMap) -> impl IntoResponse { 24 // Why this is safe: the token lives only in the server-side session and is 25 // echoed by OUR page's JavaScript into the x-csrf-token header. An attacker's 26 // cross-site page can make the browser send the cookie, but the Same-Origin 27 // Policy stops it from READING our token to put it in the header — so the 28 // forged request arrives with the cookie but no/ wrong token, and fails here. 29 let expected: Option<String> = session.get(CSRF_KEY).await.unwrap(); 30 let provided = headers.get("x-csrf-token").and_then(|v| v.to_str().ok()); 31 32 match (expected.as_deref(), provided) { 33 (Some(want), Some(got)) if want == got => { 34 (StatusCode::OK, "transfer accepted").into_response() 35 } 36 _ => (StatusCode::FORBIDDEN, "CSRF check failed").into_response(), 37 } 38 } 39 40 #[tokio::main] 41 async fn main() { 42 let app = Router::new() 43 .route("/form", get(show_form)) 44 .route("/transfer", post(transfer)) 45 .layer(SessionManagerLayer::new(MemoryStore::default())); 46 47 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); 48 axum::serve(listener, app).await.unwrap(); 49 } ``` Dependencies: `cargo add rand@0.9` plus the usual axum/tokio/tower-sessions. The defense works because the cookie is sent automatically by the browser but the *token* is not: reading it requires same-origin script access, which the attacker’s page does not have. To harden it further, pair this with `SameSite=Lax` cookies and a constant-time comparison via the `subtle` crate. # WebSockets with Axum > Build WebSocket servers in Axum with WebSocketUpgrade. Instead of Node's ws callbacks, you own an async recv loop, split the socket, and broadcast over a channel. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) WebSockets give you a single long-lived, full-duplex TCP connection where both the server and the client can push messages at any time: perfect for chat, live dashboards, multiplayer games, and collaborative editors. In Node you reach for the `ws` library (or Socket.IO); in Axum you use `axum::extract::ws::WebSocketUpgrade`, which turns an ordinary HTTP handler into a connection upgrade and then hands you an `async` send/receive loop. This page covers the full lifecycle: upgrading the request, the receive loop, sending messages, splitting the socket for concurrent reads and writes, and a working echo server. > **Note:** This page targets the **axum 0.8** API line (recorded with 0.8.9) and the repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) on the 2024 edition. The WebSocket types live behind a Cargo feature: `cargo add axum --features ws`. In 0.8 the `Message::Text` variant wraps a `Utf8Bytes` (a cheap, UTF-8-validated byte buffer), not a `String`; a detail that trips up developers following older tutorials. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) A realistic echo-plus-broadcast WebSocket server in Node using the `ws` library. It accepts connections, echoes text back, and also broadcasts every message to all connected clients. ```typescript 1 // server.ts — Node v22, `npm i ws @types/ws` 2 import { WebSocketServer, WebSocket } from "ws"; 3 4 const wss = new WebSocketServer({ port: 3000 }); 5 console.log("listening on ws://127.0.0.1:3000"); 6 7 wss.on("connection", (socket: WebSocket, req) => { 8 console.log(`client connected from ${req.socket.remoteAddress}`); 9 10 // Receive: the event loop calls this every time a frame arrives. 11 socket.on("message", (data: Buffer, isBinary: boolean) => { 12 const text = data.toString(); 13 console.log(`received: ${text}`); 14 15 // Echo back to the sender. 16 socket.send(`echo: ${text}`); 17 18 // Broadcast to everyone else. 19 for (const client of wss.clients) { 20 if (client !== socket && client.readyState === WebSocket.OPEN) { 21 client.send(text); 22 } 23 } 24 }); 25 26 // Lifecycle callbacks. 27 socket.on("close", () => console.log("client disconnected")); 28 socket.on("error", (err) => console.error("socket error:", err)); 29 30 // The server can push at any time — here, a greeting. 31 socket.send("welcome"); 32 }); ``` Things a TypeScript developer relies on here: the server is **callback-driven**. You register `on("message")`, `on("close")`, and `on("error")` handlers, and Node’s event loop invokes them whenever a frame arrives. The connection’s `clients` set lives on the server object, and “broadcast” is a `for` loop over it. There is no explicit loop you write — the runtime owns the loop and calls back into your code. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same echo server in Axum. Instead of registering callbacks, you write one `async fn` that **owns the connection** and loops over incoming messages explicitly. ```rust 1 // Cargo.toml dependencies: 2 // axum = { version = "0.8", features = ["ws"] } 3 // tokio = { version = "1", features = ["full"] } 4 use axum::{ 5 extract::ws::{Message, WebSocket, WebSocketUpgrade}, 6 response::Response, 7 routing::any, 8 Router, 9 }; 10 11 #[tokio::main] 12 async fn main() { 13 let app = Router::new().route("/ws", any(ws_handler)); 14 15 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000") 16 .await 17 .unwrap(); 18 println!("listening on ws://{}", listener.local_addr().unwrap()); 19 axum::serve(listener, app).await.unwrap(); 20 } 21 22 // 1. An ordinary handler that takes the `WebSocketUpgrade` extractor. 23 // Returning `ws.on_upgrade(..)` responds with HTTP 101 Switching Protocols. 24 async fn ws_handler(ws: WebSocketUpgrade) -> Response { 25 ws.on_upgrade(handle_socket) 26 } 27 28 // 2. This runs AFTER the handshake completes, once per connection. 29 // `socket` is owned here — this function IS the connection's lifecycle. 30 async fn handle_socket(mut socket: WebSocket) { 31 // 3. The receive loop. `recv()` returns `Some(Ok(msg))` per frame, 32 // `None` when the client hangs up. 33 while let Some(Ok(msg)) = socket.recv().await { 34 match msg { 35 Message::Text(text) => { 36 // 4. Echo back. `Message::Text` wraps `Utf8Bytes`; 37 // `format!` derefs it to `&str`, then `.into()` converts back. 38 if socket 39 .send(Message::Text(format!("echo: {text}").into())) 40 .await 41 .is_err() 42 { 43 break; // client gone; stop the loop 44 } 45 } 46 Message::Binary(bin) => { 47 if socket.send(Message::Binary(bin)).await.is_err() { 48 break; 49 } 50 } 51 // 5. The protocol's control frames. axum auto-replies to Ping 52 // with Pong, so you usually just observe these. 53 Message::Close(_) => break, 54 Message::Ping(_) | Message::Pong(_) => {} 55 } 56 } 57 // Falling out of the loop drops `socket`, which closes the connection. 58 } ``` This compiles and serves. Here is a real round trip captured by connecting a client, sending `hello` and `world`, then closing (server-side logs added to the loop for the trace): ```text 1 [client] connected to ws://127.0.0.1:65159/ws 2 [server] received text: hello 3 [client] got: echo: hello 4 [server] received text: world 5 [client] got: echo: world 6 [server] client closed: None 7 [server] socket loop ended 8 [client] done ``` > **Tip:** The route uses `any(ws_handler)`, not `get(...)`. A WebSocket handshake is technically a `GET`, so `get(ws_handler)` also works, but `any` is the conventional choice because the upgrade is method-agnostic from your code’s point of view and it avoids surprises if a proxy rewrites the method. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The two-phase handshake [Section titled “The two-phase handshake”](#the-two-phase-handshake) A WebSocket connection starts life as a normal HTTP request with `Upgrade: websocket` headers. Axum models this in two phases, and the split is the key mental shift from Node: 1. **`ws_handler`** is a regular Axum handler. The `WebSocketUpgrade` extractor reads the upgrade headers and validates the handshake. Calling `ws.on_upgrade(callback)` returns a `Response` (HTTP `101 Switching Protocols`). At this point you are still in normal request/response land: you can run other extractors first (auth, query params), reject the request with a different status, and so on. 2. **`handle_socket`** runs only *after* the `101` response has been sent and the TCP connection has been “upgraded”. It receives an owned `WebSocket` and is responsible for the entire conversation. When this `async fn` returns, the socket is dropped and the connection closes. In Node, both phases are collapsed into the `wss.on("connection", ...)` callback, and the library owns the read loop. In Axum **you own the loop**, which is why you write `while let Some(...) = socket.recv().await`. ### `recv()` returns `Option<Result<Message, Error>>` [Section titled “recv() returns Option\<Result\<Message, Error>>”](#recv-returns-optionresultmessage-error) * `Some(Ok(msg))`: a frame arrived. * `Some(Err(e))`: a protocol or I/O error (malformed frame, broken pipe). * `None`: the stream ended cleanly; the client is gone. The pattern `while let Some(Ok(msg)) = socket.recv().await` stops the loop on *either* an error or a clean close, which is the right default for an echo server. If you need to log errors, match all three arms instead of using `while let`. ### The `Message` enum [Section titled “The Message enum”](#the-message-enum) In axum 0.8 the variants are: | Variant | Payload type | Meaning | | ----------------- | -------------------- | --------------------------------------------- | | `Message::Text` | `Utf8Bytes` | A UTF-8 text frame | | `Message::Binary` | `Bytes` | A binary frame | | `Message::Ping` | `Bytes` | Keep-alive ping (axum auto-replies with Pong) | | `Message::Pong` | `Bytes` | Reply to a ping | | `Message::Close` | `Option<CloseFrame>` | Graceful close, optionally with code + reason | `Utf8Bytes` and `Bytes` are reference-counted, cheaply cloneable byte buffers (from the `bytes` crate). `Utf8Bytes` derefs to `&str`, so `format!("echo: {text}")` and `text.to_string()` both work directly. To build a text message you can write `Message::Text(my_string.into())` or the shorthand constructor `Message::text(my_string)`. > **Note:** Axum (via the underlying `tungstenite` library) **automatically responds to Ping frames with Pong**. You generally do not need to handle `Message::Ping` yourself unless you want to observe liveness. You *can* send your own `Message::Ping` to detect dead connections. ### Sending and the back-pressure check [Section titled “Sending and the back-pressure check”](#sending-and-the-back-pressure-check) `socket.send(msg).await` returns a `Result`. An `Err` means the connection is broken (the client vanished mid-write). The idiomatic pattern is `if socket.send(...).await.is_err() { break; }`; there is no point continuing to read a socket you can no longer write to. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | Node (`ws`) | Axum | | ------------------------- | ----------------------------------------------- | --------------------------------------------------- | | Programming model | Callback-driven (`on("message")`) | You own an explicit `async` loop | | Who owns the read loop | The library / event loop | Your `handle_socket` function | | Connection lifetime | Until you call `socket.close()` or it errors | Until `handle_socket` returns (socket dropped) | | Concurrent send + receive | Implicit (both are just callbacks/method calls) | Must `split()` the socket into a sender + receiver | | Text payload type | `Buffer` / `string` | `Utf8Bytes` (derefs to `&str`) | | Ping/Pong | Manual or via library options | Auto-Pong by axum; ping is opt-in | | Tracking all clients | `wss.clients` set on the server | Shared state + a `broadcast` channel (you build it) | | Backpressure | Mostly hidden; `socket.bufferedAmount` | Explicit: `send().await` can fail / suspend | The deepest difference is **ownership of the loop**. In Node the runtime calls your callbacks; a single connection’s logic is scattered across `on("message")`, `on("close")`, etc., sharing state through closures. In Axum, one function reads top-to-bottom and owns everything for that connection, so the control flow (and where the connection ends) is explicit. This is the same async ownership story covered in [the async section](/11-async/) — Rust futures are lazy and driven by the [Tokio](/11-async/02-tokio-intro/) runtime, the opposite of eager JavaScript promises. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: `Message::Text(String)` — wrong payload type [Section titled “Pitfall 1: Message::Text(String) — wrong payload type”](#pitfall-1-messagetextstring--wrong-payload-type) Following an older tutorial, you might write: ```rust 1 use axum::extract::ws::Message; 2 fn main() { 3 // does not compile (error[E0308]: mismatched types) 4 let _m = Message::Text(String::from("hi")); 5 } ``` In axum 0.8 the `Text` variant holds `Utf8Bytes`, not `String`. The real compiler error: ```text 1 error[E0308]: mismatched types 2 --> src/bin/err1.rs:4:28 3 | 4 4 | let _m = Message::Text(String::from("hi")); 5 | ------------- ^^^^^^^^^^^^^^^^^^ expected `Utf8Bytes`, found `String` 6 | | 7 | arguments to this enum variant are incorrect 8 | 9 help: call `Into::into` on this expression to convert `String` into `Utf8Bytes` ``` The compiler tells you the fix: `Message::Text(String::from("hi").into())`, or simply `Message::text("hi")`. ### Pitfall 2: trying to read and write from two tasks without `split()` [Section titled “Pitfall 2: trying to read and write from two tasks without split()”](#pitfall-2-trying-to-read-and-write-from-two-tasks-without-split) A `WebSocket` is a single owned value. If you want to read in one task and write in another (e.g. a heartbeat that pushes while the read loop runs), you cannot move the whole socket into both: ```rust 1 use axum::extract::ws::{Message, WebSocket}; 2 3 async fn handle(mut socket: WebSocket) { 4 // does not compile (error[E0382]: use of moved value: `socket`) 5 tokio::spawn(async move { 6 let _ = socket.send(Message::text("hi")).await; 7 }); 8 tokio::spawn(async move { 9 let _ = socket.recv().await; 10 }); 11 } ``` The real error: ```text 1 error[E0382]: use of moved value: `socket` 2 --> src/bin/err2.rs:8:18 3 | 4 3 | async fn handle(mut socket: WebSocket) { 5 | ---------- move occurs because `socket` has type `WebSocket`, which does not implement the `Copy` trait 6 ... 7 5 | tokio::spawn(async move { 8 | ---------- value moved here 9 ... 10 8 | tokio::spawn(async move { 11 | ^^^^^^^^^^ value used here after move ``` The fix is `socket.split()`, which gives you an owned `SplitSink` (the writer) and an owned `SplitStream` (the reader). Each half can move into its own task — see the chat-room example below. ### Pitfall 3: blocking the read loop with slow work [Section titled “Pitfall 3: blocking the read loop with slow work”](#pitfall-3-blocking-the-read-loop-with-slow-work) Because *you* own the loop, any slow synchronous work inside it (a tight CPU loop, a blocking file read) stalls that connection, and if you use a single-threaded runtime, every connection. Offload heavy work to `tokio::task::spawn_blocking` or a worker task and keep the read loop responsive, exactly as covered in [the async section](/11-async/). ### Pitfall 4: forgetting the `ws` feature [Section titled “Pitfall 4: forgetting the ws feature”](#pitfall-4-forgetting-the-ws-feature) `use axum::extract::ws::WebSocketUpgrade;` will not resolve unless you enabled the feature. Run `cargo add axum --features ws`. Without it you’ll get an unresolved-import error pointing at `ws`. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Split the socket for any non-echo workload.** As soon as the server needs to *push* (chat broadcast, live updates, heartbeats), call `socket.split()` and run a sender task and a receiver task, joined with `tokio::select!` so that when one ends you `abort()` the other. * **Combine the upgrade with other extractors freely.** `WebSocketUpgrade` is a `FromRequestParts` extractor: it inspects only the handshake *headers*, never the request body, so it can sit in any argument position. Put auth/query/path extractors before *or* after it to authenticate or parameterize the connection (see [authentication](/16-web-apis/12-authentication/) and [extractors](/16-web-apis/04-extractors/)). The “must come last” rule applies only to body-consuming `FromRequest` extractors like `Json`, `Bytes`, and `String` — `WebSocketUpgrade` is not one of them. * **Use `tokio::sync::broadcast` for fan-out.** It is the natural analogue of Node’s `wss.clients` loop: every connection `subscribe()`s to a shared sender stored in [application state](/16-web-apis/06-state-management/). * **Send a `Close` frame on graceful shutdown.** It lets the client distinguish a clean close from a dropped connection and carries a status code and reason. * **Cap message size.** `ws.max_message_size(64 * 1024)` and `ws.max_frame_size(...)` guard against memory-exhaustion from hostile clients. * **Send periodic pings** if you need to detect half-open connections (a client that vanished without a TCP FIN); time out if no Pong returns. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small **chat room** that fans messages out to every connected client, structured the way a production service would be: shared state holds a `broadcast` channel, and each connection splits its socket into a sender task (forwarding broadcasts to this client) and a receiver task (publishing this client’s messages). This is the Axum equivalent of the Node `wss.clients` broadcast loop. ```rust 1 // Cargo.toml dependencies: 2 // axum = { version = "0.8", features = ["ws"] } 3 // tokio = { version = "1", features = ["full"] } 4 // futures-util = "0.3" 5 use axum::{ 6 extract::{ 7 ws::{Message, WebSocket, WebSocketUpgrade}, 8 State, 9 }, 10 response::Response, 11 routing::any, 12 Router, 13 }; 14 use futures_util::{sink::SinkExt, stream::StreamExt}; 15 use std::sync::Arc; 16 use tokio::sync::broadcast; 17 18 // Shared application state: one broadcast sender for the whole room. 19 #[derive(Clone)] 20 struct AppState { 21 tx: broadcast::Sender<String>, 22 } 23 24 #[tokio::main] 25 async fn main() { 26 // Capacity 64: how many messages may lag behind a slow client. 27 let (tx, _rx) = broadcast::channel(64); 28 let state = Arc::new(AppState { tx }); 29 30 let app = Router::new() 31 .route("/ws", any(ws_handler)) 32 .with_state(state); 33 34 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000") 35 .await 36 .unwrap(); 37 println!("chat on ws://{}", listener.local_addr().unwrap()); 38 axum::serve(listener, app).await.unwrap(); 39 } 40 41 async fn ws_handler( 42 ws: WebSocketUpgrade, 43 State(state): State<Arc<AppState>>, 44 ) -> Response { 45 ws.on_upgrade(|socket| chat(socket, state)) 46 } 47 48 async fn chat(socket: WebSocket, state: Arc<AppState>) { 49 // Split into an owned writer and an owned reader. 50 let (mut sender, mut receiver) = socket.split(); 51 52 // Each connection gets its own subscription to the shared channel. 53 let mut rx = state.tx.subscribe(); 54 55 // Announce the join to everyone (including future-joined readers). 56 let _ = state.tx.send("* a user joined".to_string()); 57 58 // Task A: forward every broadcast message to THIS client. 59 let mut send_task = tokio::spawn(async move { 60 while let Ok(msg) = rx.recv().await { 61 if sender.send(Message::text(msg)).await.is_err() { 62 break; // this client disconnected 63 } 64 } 65 }); 66 67 // Task B: read THIS client's messages and publish them to the room. 68 let tx = state.tx.clone(); 69 let mut recv_task = tokio::spawn(async move { 70 while let Some(Ok(Message::Text(text))) = receiver.next().await { 71 let _ = tx.send(format!("user: {text}")); 72 } 73 }); 74 75 // When either side ends, abort the other and clean up. 76 tokio::select! { 77 _ = &mut send_task => recv_task.abort(), 78 _ = &mut recv_task => send_task.abort(), 79 } 80 81 let _ = state.tx.send("* a user left".to_string()); 82 } ``` Running this with two clients — client A is already connected, then client B connects (and sees the join announcement), after which A sends `hi from A` — produces this real output on B’s side: ```text 1 [B] * a user joined 2 [B] user: hi from A ``` > **Note:** `broadcast::channel` drops the oldest message for receivers that fall too far behind, and `rx.recv()` then returns a `RecvError::Lagged(n)`. The `while let Ok(msg) = ...` loop above stops on that error; in production you’d match it explicitly and either skip-and-continue or close the slow client. The integer you pass to `broadcast::channel` is that backlog capacity. For wiring the `broadcast` sender into a larger app (alongside a database pool and config), see [state management](/16-web-apis/06-state-management/). For pushing *server-to-client only* updates without the client ever sending (simpler than WebSockets), reach for [Server-Sent Events](/16-web-apis/16-sse/) instead. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`axum::extract::ws` documentation](https://docs.rs/axum/latest/axum/extract/ws/index.html) — the authoritative reference for `WebSocketUpgrade`, `WebSocket`, and `Message`. * [Axum WebSocket example](https://github.com/tokio-rs/axum/tree/main/examples/websockets) — the official, maintained chat example this page is modeled on. * [The WebSocket Protocol (RFC 6455)](https://datatracker.ietf.org/doc/html/rfc6455): frames, close codes, and the handshake. * [`tokio::sync::broadcast`](https://docs.rs/tokio/latest/tokio/sync/broadcast/index.html) — the fan-out channel used for the chat room. * Sibling pages in this section: [Axum basics](/16-web-apis/01-axum-basics/) · [routing](/16-web-apis/03-routing/) · [extractors](/16-web-apis/04-extractors/) · [state management](/16-web-apis/06-state-management/) · [authentication](/16-web-apis/12-authentication/) · [Server-Sent Events](/16-web-apis/16-sse/) · [deployment](/16-web-apis/19-deployment/). * Foundations: [async & futures](/11-async/) · [the Tokio runtime](/11-async/02-tokio-intro/) · [getting started](/01-getting-started/) · [language basics](/02-basics/). Persisting chat history? See [the database section](/17-database/). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Reverse-echo server [Section titled “Exercise 1: Reverse-echo server”](#exercise-1-reverse-echo-server) **Difficulty:** Beginner **Objective:** Get comfortable with the upgrade handler and the receive loop. **Instructions:** Starting from the echo server in the “Rust Equivalent” section, change the handler so that for every text frame it replies with the message **reversed** (e.g. `hello` → `olleh`). Leave binary frames echoed unchanged and break the loop on a close frame. Solution ```rust 1 // Cargo.toml: axum = { version = "0.8", features = ["ws"] } 2 // tokio = { version = "1", features = ["full"] } 3 use axum::{ 4 extract::ws::{Message, WebSocket, WebSocketUpgrade}, 5 response::Response, 6 routing::any, 7 Router, 8 }; 9 10 #[tokio::main] 11 async fn main() { 12 let app = Router::new().route("/ws", any(ws_handler)); 13 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000") 14 .await 15 .unwrap(); 16 println!("listening on ws://{}", listener.local_addr().unwrap()); 17 axum::serve(listener, app).await.unwrap(); 18 } 19 20 async fn ws_handler(ws: WebSocketUpgrade) -> Response { 21 ws.on_upgrade(handle_socket) 22 } 23 24 async fn handle_socket(mut socket: WebSocket) { 25 while let Some(Ok(msg)) = socket.recv().await { 26 match msg { 27 Message::Text(text) => { 28 // `Utf8Bytes` derefs to `&str`; reverse by chars. 29 let reversed: String = text.chars().rev().collect(); 30 if socket.send(Message::text(reversed)).await.is_err() { 31 break; 32 } 33 } 34 Message::Binary(bin) => { 35 if socket.send(Message::Binary(bin)).await.is_err() { 36 break; 37 } 38 } 39 Message::Close(_) => break, 40 _ => {} 41 } 42 } 43 } ``` ### Exercise 2: A broadcast chat room [Section titled “Exercise 2: A broadcast chat room”](#exercise-2-a-broadcast-chat-room) **Difficulty:** Intermediate **Objective:** Practice splitting the socket and sharing state across connections with a `broadcast` channel. **Instructions:** Build a server with a single `/ws` route. Store a `tokio::sync::broadcast::Sender<String>` in `State`. On each connection, split the socket; spawn a task that forwards broadcast messages to the client, and a task that reads the client’s text frames and publishes them (prefixed with `"user: "`) to the channel. Use `tokio::select!` so that when one task ends you abort the other. Announce `"* a user joined"` on connect and `"* a user left"` on disconnect. Solution ```rust 1 // Cargo.toml: axum = { version = "0.8", features = ["ws"] } 2 // tokio = { version = "1", features = ["full"] } 3 // futures-util = "0.3" 4 use axum::{ 5 extract::{ 6 ws::{Message, WebSocket, WebSocketUpgrade}, 7 State, 8 }, 9 response::Response, 10 routing::any, 11 Router, 12 }; 13 use futures_util::{sink::SinkExt, stream::StreamExt}; 14 use std::sync::Arc; 15 use tokio::sync::broadcast; 16 17 #[derive(Clone)] 18 struct AppState { 19 tx: broadcast::Sender<String>, 20 } 21 22 #[tokio::main] 23 async fn main() { 24 let (tx, _rx) = broadcast::channel(64); 25 let state = Arc::new(AppState { tx }); 26 let app = Router::new() 27 .route("/ws", any(handler)) 28 .with_state(state); 29 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000") 30 .await 31 .unwrap(); 32 println!("chat on ws://{}", listener.local_addr().unwrap()); 33 axum::serve(listener, app).await.unwrap(); 34 } 35 36 async fn handler( 37 ws: WebSocketUpgrade, 38 State(state): State<Arc<AppState>>, 39 ) -> Response { 40 ws.on_upgrade(|socket| chat(socket, state)) 41 } 42 43 async fn chat(socket: WebSocket, state: Arc<AppState>) { 44 let (mut sender, mut receiver) = socket.split(); 45 let mut rx = state.tx.subscribe(); 46 47 let _ = state.tx.send("* a user joined".to_string()); 48 49 let mut send_task = tokio::spawn(async move { 50 while let Ok(msg) = rx.recv().await { 51 if sender.send(Message::text(msg)).await.is_err() { 52 break; 53 } 54 } 55 }); 56 57 let tx = state.tx.clone(); 58 let mut recv_task = tokio::spawn(async move { 59 while let Some(Ok(Message::Text(text))) = receiver.next().await { 60 let _ = tx.send(format!("user: {text}")); 61 } 62 }); 63 64 tokio::select! { 65 _ = &mut send_task => recv_task.abort(), 66 _ = &mut recv_task => send_task.abort(), 67 } 68 69 let _ = state.tx.send("* a user left".to_string()); 70 } ``` ### Exercise 3: Typed JSON protocol with a graceful close [Section titled “Exercise 3: Typed JSON protocol with a graceful close”](#exercise-3-typed-json-protocol-with-a-graceful-close) **Difficulty:** Advanced **Objective:** Combine `serde` with the socket: parse a tagged-enum protocol off the wire, respond with typed messages, and close gracefully with a status code. **Instructions:** Define a `ClientMsg` enum (`Chat { text }` and `Ping`) deserialized with `#[serde(tag = "type")]`, and a `ServerMsg` enum (`Echo { text }`, `Pong`, `Error { message }`). In the receive loop, parse each text frame as JSON: `Chat` replies with `Echo`, `Ping` replies with `Pong`, and a parse failure replies with `Error`. On close, send a `Message::Close` with code `1000` (normal) and a reason. Solution ```rust 1 // Cargo.toml: axum = { version = "0.8", features = ["ws"] } 2 // tokio = { version = "1", features = ["full"] } 3 // serde = { version = "1", features = ["derive"] } 4 // serde_json = "1" 5 use axum::extract::ws::{CloseFrame, Message, WebSocket, WebSocketUpgrade}; 6 use axum::{response::Response, routing::any, Router}; 7 use serde::{Deserialize, Serialize}; 8 9 #[derive(Deserialize)] 10 #[serde(tag = "type", rename_all = "snake_case")] 11 enum ClientMsg { 12 Chat { text: String }, 13 Ping, 14 } 15 16 #[derive(Serialize)] 17 #[serde(tag = "type", rename_all = "snake_case")] 18 enum ServerMsg { 19 Echo { text: String }, 20 Pong, 21 Error { message: String }, 22 } 23 24 #[tokio::main] 25 async fn main() { 26 let app = Router::new().route("/ws", any(handler)); 27 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000") 28 .await 29 .unwrap(); 30 println!("listening on ws://{}", listener.local_addr().unwrap()); 31 axum::serve(listener, app).await.unwrap(); 32 } 33 34 async fn handler(ws: WebSocketUpgrade) -> Response { 35 ws.on_upgrade(socket_loop) 36 } 37 38 async fn socket_loop(mut socket: WebSocket) { 39 while let Some(Ok(msg)) = socket.recv().await { 40 // Only act on text frames; break on a close frame. 41 let Message::Text(raw) = msg else { 42 if matches!(msg, Message::Close(_)) { 43 break; 44 } 45 continue; 46 }; 47 48 let reply = match serde_json::from_str::<ClientMsg>(&raw) { 49 Ok(ClientMsg::Chat { text }) => ServerMsg::Echo { text }, 50 Ok(ClientMsg::Ping) => ServerMsg::Pong, 51 Err(e) => ServerMsg::Error { message: e.to_string() }, 52 }; 53 54 let json = serde_json::to_string(&reply).unwrap(); 55 if socket.send(Message::text(json)).await.is_err() { 56 return; 57 } 58 } 59 60 // Graceful close with a status code and reason. 61 let _ = socket 62 .send(Message::Close(Some(CloseFrame { 63 code: axum::extract::ws::close_code::NORMAL, 64 reason: "bye".into(), 65 }))) 66 .await; 67 } ``` # Server-Sent Events with Axum > Push Server-Sent Events from Axum by returning an async Stream, replacing Node's imperative res.write loop with a typed Sse response and throttling. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) **Server-Sent Events (SSE)** is a simple, HTTP-based protocol for pushing a one-way stream of text events from server to browser over a single long-lived connection. Exactly what you reach for to power live dashboards, notification feeds, progress bars, or token-by-token LLM output. In Axum you model an SSE endpoint as an ordinary handler that returns `axum::response::Sse` wrapping an async **`Stream`** of events; this page shows how that `Stream` abstraction replaces the imperative `res.write()` loop you would write in Express. > **Note:** This page targets the **axum 0.8** API line (recorded with 0.8.9), the repository’s [pinned verification toolchain](/00-introduction/05-version-policy/), and the 2024 edition. SSE lives in `axum::response::sse`; you do not need a separate crate for the protocol itself, only a way to build a `Stream` (the `futures-util`, `tokio-stream`, or `async-stream` crates). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) SSE is built into the browser as the `EventSource` API, and on the server it is just a normal HTTP response with `Content-Type: text/event-stream` that you keep open and write to. Here is a realistic Node endpoint (no framework, to make the wire format obvious) that pushes a `tick` event three times and then closes: ```typescript 1 // sse.mts — Node v22, plain http server 2 import http from "node:http"; 3 4 interface Tick { 5 seq: number; 6 message: string; 7 } 8 9 const server = http.createServer((req, res) => { 10 if (req.url === "/events") { 11 // The three headers that make a response an SSE stream. 12 res.writeHead(200, { 13 "Content-Type": "text/event-stream", 14 "Cache-Control": "no-cache", 15 Connection: "keep-alive", 16 }); 17 18 let seq = 0; 19 const timer = setInterval(() => { 20 const tick: Tick = { seq, message: `tick ${seq}` }; 21 // The wire format: optional `event:` line, then `data:`, then a BLANK line. 22 res.write(`event: tick\n`); 23 res.write(`data: ${JSON.stringify(tick)}\n\n`); 24 seq += 1; 25 if (seq >= 3) { 26 clearInterval(timer); 27 res.end(); 28 } 29 }, 150); 30 31 // If the client disconnects, stop the timer so we don't leak it. 32 req.on("close", () => clearInterval(timer)); 33 } else { 34 res.writeHead(404).end(); 35 } 36 }); 37 38 server.listen(3011, () => console.log("listening on http://127.0.0.1:3011")); ``` The browser side is tiny: ```typescript 1 // client.ts — runs in the browser 2 const source = new EventSource("/events"); 3 source.addEventListener("tick", (e: MessageEvent) => { 4 const tick = JSON.parse(e.data) as { seq: number; message: string }; 5 console.log(tick.seq, tick.message); 6 }); 7 source.onerror = () => console.log("connection lost; browser will auto-reconnect"); ``` Things to notice in the Node version: **you** own the timer, **you** format every `data:` line and remember the trailing blank line, and **you** must clean up on `req.on("close")` or you leak the interval. Running it and connecting with `curl -N` yields: ```text 1 event: tick 2 data: {"seq":0,"message":"tick 0"} 3 4 event: tick 5 data: {"seq":1,"message":"tick 1"} 6 7 event: tick 8 data: {"seq":2,"message":"tick 2"} ``` *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) In Axum you do not write to the socket imperatively. You **return a `Stream`**, and Axum’s `Sse` response type handles the headers, the `data:`/`event:` framing, the blank-line separators, keep-alive comments, and cleanup-on-disconnect for you. Add the dependencies in a fresh project (`cargo new sse-demo`): Cargo.toml ```toml 1 [dependencies] 2 axum = "0.8.9" 3 tokio = { version = "1.52.3", features = ["full"] } 4 tokio-stream = "0.1.18" 5 futures-util = "0.3.32" 6 serde = { version = "1.0.228", features = ["derive"] } 7 serde_json = "1.0.150" ``` ```rust 1 use axum::{ 2 response::sse::{Event, KeepAlive, Sse}, 3 routing::get, 4 Router, 5 }; 6 use futures_util::stream::{self, Stream}; 7 use serde::Serialize; 8 use std::{convert::Infallible, time::Duration}; 9 use tokio_stream::StreamExt; 10 11 #[derive(Serialize)] 12 struct Tick { 13 seq: u64, 14 message: String, 15 } 16 17 // GET /events — a Server-Sent Events endpoint. 18 // The return type says: "a stream of `Event`s that can never fail". 19 async fn sse_handler() -> Sse<impl Stream<Item = Result<Event, Infallible>>> { 20 let stream = stream::iter(0..3) 21 .map(|seq| { 22 let tick = Tick { seq, message: format!("tick {seq}") }; 23 // `json_data` serializes with serde and sets the `data:` line. 24 Ok(Event::default().event("tick").json_data(tick).unwrap()) 25 }) 26 // Space the events out in time, just like the Node `setInterval`. 27 .throttle(Duration::from_millis(200)); 28 29 Sse::new(stream).keep_alive(KeepAlive::default()) 30 } 31 32 #[tokio::main] 33 async fn main() { 34 let app = Router::new().route("/events", get(sse_handler)); 35 let listener = tokio::net::TcpListener::bind("127.0.0.1:3007").await.unwrap(); 36 println!("listening on http://{}", listener.local_addr().unwrap()); 37 axum::serve(listener, app).await.unwrap(); 38 } ``` Run it (`cargo run`) and connect with `curl -N http://127.0.0.1:3007/events`. This is the **real** wire output (`-N` disables curl’s buffering so you see events as they arrive): ```text 1 event: tick 2 data: {"seq":0,"message":"tick 0"} 3 4 event: tick 5 data: {"seq":1,"message":"tick 1"} 6 7 event: tick 8 data: {"seq":2,"message":"tick 2"} ``` Byte-for-byte the same protocol the Node server produced, but you never wrote a `data:` prefix, a blank-line separator, or a disconnect handler. The response headers are set for you; inspecting them with `curl -D -` shows: ```text 1 HTTP/1.1 200 OK 2 content-type: text/event-stream 3 cache-control: no-cache 4 transfer-encoding: chunked ``` The same browser `EventSource` client from the TypeScript section talks to this endpoint without changes. SSE is a wire protocol, not a framework feature. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) The whole design hinges on one substitution: **Node’s imperative `res.write()` loop becomes a declarative `Stream`.** Let’s walk the Rust handler line by line and contrast each piece with the Node version. ### The return type is the contract [Section titled “The return type is the contract”](#the-return-type-is-the-contract) ```rust 1 async fn sse_handler() -> Sse<impl Stream<Item = Result<Event, Infallible>>> { ``` `Sse<S>` is an `IntoResponse` wrapper (see [Request and Response Handling](/16-web-apis/07-request-response/) for how `IntoResponse` turns values into HTTP responses). The type parameter `S` must be a `Stream` whose item is `Result<Event, E>`; note the **`Result`**. SSE streams are allowed to yield errors mid-stream (e.g. a database read fails), so every item is a `Result`. When the stream genuinely cannot fail, the error type is [`std::convert::Infallible`](https://doc.rust-lang.org/std/convert/enum.Infallible.html): the empty type that says “this `Err` variant can never be constructed”. A `Stream` is the async cousin of an `Iterator`: instead of `next() -> Option<T>`, it has `poll_next() -> Poll<Option<T>>`, so producing the next item can `.await`. Streams add the async dimension on top of the synchronous iterator model, and are covered in [11-async](/11-async/02-tokio-intro/). ### Building the stream [Section titled “Building the stream”](#building-the-stream) ```rust 1 let stream = stream::iter(0..3) 2 .map(|seq| { /* ... */ Ok(Event::default().event("tick").json_data(tick).unwrap()) }) 3 .throttle(Duration::from_millis(200)); ``` * `stream::iter(0..3)` lifts an ordinary iterator (`0`, `1`, `2`) into a `Stream`. This is the moral equivalent of the Node `seq` counter. * `.map(...)` transforms each number into a `Result<Event, Infallible>`. `Event::default()` builds an empty event; `.event("tick")` sets the `event:` field (the SSE “event name” the browser dispatches on); `.json_data(tick)` serializes the struct with serde and writes the `data:` line. We then wrap it in `Ok(...)`. * `.throttle(Duration::from_millis(200))` (from `tokio_stream::StreamExt`) ensures at least 200ms passes between items: the declarative replacement for `setInterval`. There is no timer handle to clear; when the connection closes, Axum drops the stream and the throttle timer dies with it. ### The `Event` builder [Section titled “The Event builder”](#the-event-builder) `Event` is a builder for all five SSE fields. Each method returns `Self`, so they chain: | Method | SSE wire field | Purpose | | ----------------------------- | -------------- | ------------------------------------------------------------------------------------- | | `.data(s)` / `.json_data(v)?` | `data:` | The payload. `json_data` serializes with serde. | | `.event(name)` | `event:` | Named event type the browser dispatches on (`addEventListener("tick", ...)`). | | `.id(s)` | `id:` | Sets `lastEventId`; the browser echoes it as the `Last-Event-ID` header on reconnect. | | `.retry(duration)` | `retry:` | Tells the browser how long to wait before reconnecting. | | `.comment(s)` | `: ...` | A comment line (ignored by clients); used for keep-alive pings. | > **Note:** `json_data` returns a `Result` because serialization can fail; in handlers prefer `?` over `.unwrap()`, which is why the error-returning patterns below matter. ### Keep-alive [Section titled “Keep-alive”](#keep-alive) ```rust 1 Sse::new(stream).keep_alive(KeepAlive::default()) ``` If your stream is idle for a long time, proxies and load balancers may kill the “dead” connection. `KeepAlive` periodically sends an SSE comment line (`:` plus optional text) that the browser ignores but that keeps the TCP connection and any intermediary timers alive. The default interval is 15 seconds; you can customize it (shown in the real-world example below). The Node version has no equivalent; you would have to schedule your own `res.write(": ping\n\n")`. ### Where the analogy breaks down [Section titled “Where the analogy breaks down”](#where-the-analogy-breaks-down) > **Unlike** the Node example, there is no `req.on("close")` cleanup to write. Cancellation in Rust is **structured**. When the client disconnects, Axum stops polling the stream and **drops** it. Any resources the stream holds (timers, a `broadcast::Receiver`, a database cursor) are released by their `Drop` impls. You get correct cleanup for free precisely because you described *what* the stream is rather than imperatively driving it. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concern | Express / Node | Axum | | ----------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------- | | Mental model | Imperative: keep `res` open, `res.write(...)` repeatedly | Declarative: return a `Stream<Item = Result<Event, E>>` | | Wire framing (`data:`, blank lines) | You format every line by hand | `Event` builder + `Sse` do it | | Headers (`text/event-stream`, `no-cache`) | You set them via `res.writeHead` | Set automatically by the `Sse` response | | Spacing events over time | `setInterval` + a timer handle | A stream combinator (`.throttle`) or an interval stream | | Cleanup on disconnect | Manual `req.on("close")` handler | Automatic: the stream is dropped, `Drop` releases resources | | Errors mid-stream | Throw / `res.destroy()`; ad hoc | First-class: each item is a `Result`, error type in the signature | | Keep-alive pings | Schedule your own comment writes | `.keep_alive(KeepAlive::default())` | | Fan-out to many clients | Track a `Set<res>` and loop-write | Each client subscribes to a `broadcast` channel | The deeper point: SSE in Express is *a pattern you assemble*; in Axum it is *a type you return*. The compiler enforces that you produce `Event`s wrapped in `Result`, and the framework owns the protocol details. > **Tip:** SSE is **one-way** (server → client) and text-only over plain HTTP, with automatic browser reconnection built into `EventSource`. If you need bidirectional or binary traffic, use WebSockets instead — see [WebSockets with Axum](/16-web-apis/15-websockets/) for the tradeoffs. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: forgetting that items must be `Result`, not bare `Event` [Section titled “Pitfall 1: forgetting that items must be Result, not bare Event”](#pitfall-1-forgetting-that-items-must-be-result-not-bare-event) A TypeScript developer reasonably writes a stream that yields `Event` values directly: ```rust 1 use axum::{ 2 response::sse::{Event, Sse}, 3 routing::get, 4 Router, 5 }; 6 use futures_util::stream::{self, Stream}; 7 use futures_util::StreamExt; 8 9 // does not compile (error E0271): items are `Event`, not `Result<Event, E>`. 10 async fn bad_handler() -> Sse<impl Stream<Item = Event>> { 11 let stream = stream::iter(0..3).map(|i| Event::default().data(format!("{i}"))); 12 Sse::new(stream) 13 } 14 15 #[tokio::main] 16 async fn main() { 17 let app: Router = Router::new().route("/events", get(bad_handler)); 18 let listener = tokio::net::TcpListener::bind("127.0.0.1:3009").await.unwrap(); 19 axum::serve(listener, app).await.unwrap(); 20 } ``` The real compiler error: ```text 1 error[E0271]: expected `{closure@main.rs:11:41}` to return `Result<Event, _>`, but it returns `Event` 2 --> src/main.rs:11:45 3 | 4 11 | let stream = stream::iter(0..3).map(|i| Event::default().data(format!("{i}"))); 5 | --- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ expected `Result<Event, _>`, found `Event` 6 | | 7 | this closure 8 12 | Sse::new(stream) 9 | ---------------- closure used here 10 | 11 = note: expected enum `Result<Event, _>` 12 found struct `Event` ``` **Fix:** wrap each event in `Ok(...)` and annotate the error type, e.g. `Result<Event, Infallible>` when nothing can fail. ### Pitfall 2: importing the wrong `StreamExt` [Section titled “Pitfall 2: importing the wrong StreamExt”](#pitfall-2-importing-the-wrong-streamext) Both `futures_util::StreamExt` and `tokio_stream::StreamExt` exist, and they offer *different* combinators. `.throttle(...)` lives on `tokio_stream::StreamExt`; `.enumerate()` lives on `futures_util::StreamExt`. If you call a combinator without its trait in scope, the compiler complains that the trait bounds were not satisfied, but, helpfully, points you at the exact import you need: ```rust 1 // does not compile (error E0599): StreamExt is not in scope. 2 fn main() { 3 let s = futures_util::stream::iter(0..3); 4 let _e = s.enumerate(); 5 } ``` ```text 1 error[E0599]: the method `enumerate` exists for struct `futures_util::stream::Iter<std::ops::Range<{integer}>>`, but its trait bounds were not satisfied 2 --> src/main.rs:3:16 3 | 4 3 | let _e = s.enumerate(); 5 | ^^^^^^^^^ method cannot be called due to unsatisfied trait bounds 6 | 7 = note: the following trait bounds were not satisfied: 8 `futures_util::stream::Iter<std::ops::Range<{integer}>>: Iterator` 9 which is required by `&mut futures_util::stream::Iter<std::ops::Range<{integer}>>: Iterator` 10 = help: items from traits can only be used if the trait is in scope 11 help: trait `StreamExt` which provides `enumerate` is implemented but not in scope; perhaps you want to import it 12 | 13 1 + use futures_util::StreamExt; 14 | ``` **Fix:** read the `help:` line; it names the exact trait to import. Importing *both* `StreamExt` traits causes a method-ambiguity error for the methods they share (like `map`), so pick the one whose combinators you need, or fully-qualify the call. ### Pitfall 3: blocking the async runtime to produce events [Section titled “Pitfall 3: blocking the async runtime to produce events”](#pitfall-3-blocking-the-async-runtime-to-produce-events) Putting a synchronous sleep or a blocking I/O call inside the stream’s closure stalls the entire worker thread, freezing every other request the runtime is handling: ```rust 1 // wrong: std::thread::sleep blocks the async worker thread. 2 .map(|i| { 3 std::thread::sleep(std::time::Duration::from_secs(1)); // never do this in async 4 Ok::<_, std::convert::Infallible>(axum::response::sse::Event::default().data(i.to_string())) 5 }) ``` **Fix:** use async timing — `.throttle(...)`, an `IntervalStream`, or `tokio::time::sleep(...).await` inside an `async_stream::stream! { ... }` block (shown next). See [11-async](/11-async/02-tokio-intro/) for why blocking calls poison cooperative runtimes. ### Pitfall 4: buffering proxies hide your events [Section titled “Pitfall 4: buffering proxies hide your events”](#pitfall-4-buffering-proxies-hide-your-events) If you test through nginx (or a similar reverse proxy) and events arrive all at once at the end instead of trickling in, the proxy is buffering the response. SSE needs `proxy_buffering off;` (nginx) on the relevant location. This is not an Axum issue — Axum already sends `Cache-Control: no-cache` — but it surprises people. Locally, remember `curl -N` to disable curl’s own buffering. Deployment specifics live in [Deploying Axum Applications](/16-web-apis/19-deployment/). *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Always type the stream’s error explicitly.** Use `Infallible` when nothing can fail (it documents intent and lets the compiler optimize), or a real error type when items come from fallible sources. * **Prefer `event.json_data(value)?` over hand-formatting `data:`.** It serializes with serde, escapes newlines correctly, and keeps your payload in one typed struct. * **Set an event `id` when clients should resume.** On reconnect the browser sends `Last-Event-ID`; read it (via the `headers` extractor — see [Extractors](/16-web-apis/04-extractors/)) to replay only what was missed. * **Add a keep-alive.** `KeepAlive::default()` is cheap insurance against idle-connection timeouts in proxies. * **Fan out with a `broadcast` channel, not a shared `Vec` of senders.** `tokio::sync::broadcast` gives each subscriber its own receiver and handles slow-consumer lag for you; combine it with shared `State` (see [Shared Application State in Axum](/16-web-apis/06-state-management/)). * **Use `async_stream::stream!` when emission is inherently sequential/stateful** (a countdown, a job that does work between yields). Use combinators (`stream::iter(...).map(...).throttle(...)`) when the source is already a collection or another stream. * **Set `Content-Type` via `Sse`, never by hand.** Returning `Sse` already sets it; manually adding the header risks duplicates. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A live notification feed: clients open `GET /events` to subscribe, and any process can `POST /messages` to broadcast a message to **every** connected client. This is the canonical SSE production pattern: a `tokio::sync::broadcast` channel held in shared state, with each subscriber getting its own receiver wrapped as a stream. Add `tokio-stream`’s `sync` feature for `BroadcastStream` (`cargo add tokio-stream --features sync`): ```rust 1 use axum::{ 2 extract::State, 3 response::sse::{Event, KeepAlive, Sse}, 4 routing::{get, post}, 5 Json, Router, 6 }; 7 use futures_util::stream::Stream; 8 use serde::{Deserialize, Serialize}; 9 use std::{convert::Infallible, time::Duration}; 10 use tokio::sync::broadcast; 11 use tokio_stream::wrappers::BroadcastStream; 12 use tokio_stream::StreamExt; 13 14 #[derive(Clone, Serialize)] 15 struct ChatMessage { 16 user: String, 17 text: String, 18 } 19 20 #[derive(Clone)] 21 struct AppState { 22 // A broadcast channel: every subscriber gets a clone of every message. 23 tx: broadcast::Sender<ChatMessage>, 24 } 25 26 #[derive(Deserialize)] 27 struct PostMessage { 28 user: String, 29 text: String, 30 } 31 32 // POST /messages — publish to all connected SSE clients. 33 async fn publish(State(state): State<AppState>, Json(body): Json<PostMessage>) -> &'static str { 34 let msg = ChatMessage { user: body.user, text: body.text }; 35 // `send` errors only when there are zero receivers; we ignore that. 36 let _ = state.tx.send(msg); 37 "queued" 38 } 39 40 // GET /events — subscribe; the stream lives as long as the connection. 41 async fn subscribe( 42 State(state): State<AppState>, 43 ) -> Sse<impl Stream<Item = Result<Event, Infallible>>> { 44 let rx = state.tx.subscribe(); 45 let stream = BroadcastStream::new(rx).filter_map(|res| match res { 46 Ok(msg) => Some(Ok(Event::default().json_data(msg).unwrap())), 47 // A slow client that fell behind yields a `Lagged` error; skip it. 48 Err(_lagged) => None, 49 }); 50 51 Sse::new(stream).keep_alive( 52 KeepAlive::new() 53 .interval(Duration::from_secs(15)) 54 .text("keep-alive"), 55 ) 56 } 57 58 #[tokio::main] 59 async fn main() { 60 let (tx, _rx) = broadcast::channel::<ChatMessage>(64); 61 let state = AppState { tx }; 62 63 let app = Router::new() 64 .route("/messages", post(publish)) 65 .route("/events", get(subscribe)) 66 .with_state(state); 67 68 let listener = tokio::net::TcpListener::bind("127.0.0.1:3008").await.unwrap(); 69 println!("listening on http://{}", listener.local_addr().unwrap()); 70 axum::serve(listener, app).await.unwrap(); 71 } ``` Exercise it: start the server, subscribe in one terminal with `curl -N http://127.0.0.1:3008/events`, then post messages from another: ```bash 1 curl -X POST http://127.0.0.1:3008/messages \ 2 -H 'content-type: application/json' -d '{"user":"alice","text":"hello"}' 3 curl -X POST http://127.0.0.1:3008/messages \ 4 -H 'content-type: application/json' -d '{"user":"bob","text":"hi there"}' ``` The subscriber receives, in real time (verified output): ```text 1 data: {"user":"alice","text":"hello"} 2 3 data: {"user":"bob","text":"hi there"} ``` When a subscriber’s `curl` is killed, its `BroadcastStream` is dropped, the underlying `broadcast::Receiver` is dropped, and the channel automatically stops tracking it: no bookkeeping, no leaked slot. In a real app, `AppState` would also hold a database pool (see [Shared Application State in Axum](/16-web-apis/06-state-management/) and [Databases](/17-database/)), and `publish` would persist the message before broadcasting. > **Tip:** `broadcast::channel(64)` sets the per-receiver buffer. If a client cannot keep up and falls more than 64 messages behind, it receives a `Lagged` error (which we map to “skip”). Size the buffer to your tolerance for dropped messages on slow clients. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`axum::response::sse` module docs](https://docs.rs/axum/latest/axum/response/sse/index.html) — `Sse`, `Event`, `KeepAlive`. * [`Event` builder API](https://docs.rs/axum/latest/axum/response/sse/struct.Event.html) — every field method. * [`tokio_stream` wrappers](https://docs.rs/tokio-stream/latest/tokio_stream/wrappers/index.html) — `BroadcastStream`, `IntervalStream`, `ReceiverStream`. * [`async-stream` crate](https://docs.rs/async-stream/latest/async_stream/) — the `stream!` / `try_stream!` macros for sequential emission. * [MDN: Using server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) — the `EventSource` client API and wire format. * Cross-links in this section: [Axum Fundamentals](/16-web-apis/01-axum-basics/) (the handler/router/serve loop), [Extractors](/16-web-apis/04-extractors/) (reading `State` and headers), [Shared Application State in Axum](/16-web-apis/06-state-management/) (sharing the broadcast channel), [Request and Response Handling](/16-web-apis/07-request-response/) (`IntoResponse`), [Error Handling in Web Handlers](/16-web-apis/10-error-handling-web/) (fallible streams), [JSON REST APIs](/16-web-apis/08-json-apis/) (serde + `Json`), and [WebSockets with Axum](/16-web-apis/15-websockets/) (when you need two-way traffic). * Foundations: [The Tokio Runtime](/11-async/02-tokio-intro/) (futures, streams, the runtime), and the project [intro](/00-introduction/), [getting started](/01-getting-started/), and [basics](/02-basics/). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: A server clock [Section titled “Exercise 1: A server clock”](#exercise-1-a-server-clock) **Difficulty:** Beginner **Objective:** Build the simplest possible time-driven SSE endpoint and watch it tick. **Instructions:** Create a `GET /clock` handler that emits one event per second forever, where each event’s `data:` is the current count (`0`, `1`, `2`, …). Use `tokio_stream::wrappers::IntervalStream` over a `tokio::time::interval` plus a stream combinator. Add a default keep-alive. Connect with `curl -N` and confirm one event arrives per second. Solution ```rust 1 use axum::{ 2 response::sse::{Event, KeepAlive, Sse}, 3 routing::get, 4 Router, 5 }; 6 use futures_util::stream::{Stream, StreamExt}; 7 use std::{convert::Infallible, time::Duration}; 8 9 async fn clock() -> Sse<impl Stream<Item = Result<Event, Infallible>>> { 10 let stream = tokio_stream::wrappers::IntervalStream::new( 11 tokio::time::interval(Duration::from_secs(1)), 12 ) 13 .enumerate() 14 .map(|(count, _instant)| Ok(Event::default().data(count.to_string()))); 15 16 Sse::new(stream).keep_alive(KeepAlive::default()) 17 } 18 19 #[tokio::main] 20 async fn main() { 21 let app = Router::new().route("/clock", get(clock)); 22 let listener = tokio::net::TcpListener::bind("127.0.0.1:3012").await.unwrap(); 23 println!("listening on http://{}", listener.local_addr().unwrap()); 24 axum::serve(listener, app).await.unwrap(); 25 } ``` `curl -N http://127.0.0.1:3012/clock` prints (one line pair per second): ```text 1 data: 0 2 3 data: 1 4 5 data: 2 ``` > Note `IntervalStream`’s combinators here come from `futures_util::StreamExt` (`enumerate`, `map`). Import only that `StreamExt` to avoid the method-ambiguity error from Pitfall 2. ### Exercise 2: A resumable metrics stream with event ids [Section titled “Exercise 2: A resumable metrics stream with event ids”](#exercise-2-a-resumable-metrics-stream-with-event-ids) **Difficulty:** Intermediate **Objective:** Emit structured JSON events with monotonically increasing `id`s so a reconnecting client could resume. **Instructions:** Create a `GET /metrics` handler that, once per second, emits a named `metrics` event whose `data:` is a JSON object `{ "cpu": ..., "memory": ..., "at": <RFC 3339 timestamp> }`, and whose SSE `id` is the sequence number. Use serde for the struct and the `chrono` crate for the timestamp (`cargo add chrono --features clock`). Solution ```rust 1 use axum::{ 2 response::sse::{Event, KeepAlive, Sse}, 3 routing::get, 4 Router, 5 }; 6 use chrono::Utc; 7 use futures_util::stream::{Stream, StreamExt}; 8 use serde::Serialize; 9 use std::{convert::Infallible, time::Duration}; 10 11 #[derive(Serialize)] 12 struct Reading { 13 cpu: f64, 14 memory: f64, 15 at: String, 16 } 17 18 async fn metrics() -> Sse<impl Stream<Item = Result<Event, Infallible>>> { 19 let stream = tokio_stream::wrappers::IntervalStream::new( 20 tokio::time::interval(Duration::from_secs(1)), 21 ) 22 .enumerate() 23 .map(|(i, _instant)| { 24 let reading = Reading { 25 cpu: 12.5 + i as f64, 26 memory: 40.0, 27 at: Utc::now().to_rfc3339(), 28 }; 29 Ok(Event::default() 30 .id(i.to_string()) 31 .event("metrics") 32 .json_data(reading) 33 .unwrap()) 34 }); 35 36 Sse::new(stream).keep_alive(KeepAlive::default()) 37 } 38 39 #[tokio::main] 40 async fn main() { 41 let app = Router::new().route("/metrics", get(metrics)); 42 let listener = tokio::net::TcpListener::bind("127.0.0.1:3012").await.unwrap(); 43 println!("listening on http://{}", listener.local_addr().unwrap()); 44 axum::serve(listener, app).await.unwrap(); 45 } ``` `curl -N http://127.0.0.1:3012/metrics` prints (verified output): ```text 1 id: 0 2 event: metrics 3 data: {"cpu":12.5,"memory":40.0,"at":"2026-06-01T12:07:52.873017+00:00"} 4 5 id: 1 6 event: metrics 7 data: {"cpu":13.5,"memory":40.0,"at":"2026-06-01T12:07:53.873344+00:00"} 8 9 id: 2 10 event: metrics 11 data: {"cpu":14.5,"memory":40.0,"at":"2026-06-01T12:07:54.876789+00:00"} ``` To make it truly resumable, add a `headers: HeaderMap` parameter (see [Extractors](/16-web-apis/04-extractors/)) and start the counter from the incoming `Last-Event-ID` header. ### Exercise 3: A countdown with sequential async logic [Section titled “Exercise 3: A countdown with sequential async logic”](#exercise-3-a-countdown-with-sequential-async-logic) **Difficulty:** Intermediate / Advanced **Objective:** Use `async_stream::stream!` to emit events from imperative, stateful async code — the situation where combinators get awkward. **Instructions:** Create a `GET /launch` handler that counts down `T-minus 3`, `T-minus 2`, `T-minus 1` (one event every 150ms), then emits a final `liftoff` named event with payload `Liftoff!`, then ends the stream. Use the `async_stream::stream!` macro (`cargo add async-stream`) so you can write a normal `for` loop with `.await` and `yield`. Solution ```rust 1 use axum::{ 2 response::sse::{Event, KeepAlive, Sse}, 3 routing::get, 4 Router, 5 }; 6 use async_stream::stream; 7 use futures_util::stream::Stream; 8 use std::{convert::Infallible, time::Duration}; 9 10 async fn countdown() -> Sse<impl Stream<Item = Result<Event, Infallible>>> { 11 let s = stream! { 12 for n in (1..=3).rev() { 13 tokio::time::sleep(Duration::from_millis(150)).await; 14 yield Ok(Event::default().data(format!("T-minus {n}"))); 15 } 16 yield Ok(Event::default().event("liftoff").data("Liftoff!")); 17 }; 18 Sse::new(s).keep_alive(KeepAlive::default()) 19 } 20 21 #[tokio::main] 22 async fn main() { 23 let app = Router::new().route("/launch", get(countdown)); 24 let listener = tokio::net::TcpListener::bind("127.0.0.1:3010").await.unwrap(); 25 println!("listening on http://{}", listener.local_addr().unwrap()); 26 axum::serve(listener, app).await.unwrap(); 27 } ``` `curl -N http://127.0.0.1:3010/launch` prints (verified): ```text 1 data: T-minus 3 2 3 data: T-minus 2 4 5 data: T-minus 1 6 7 event: liftoff 8 data: Liftoff! ``` The `stream!` macro turns this imperative async block into a `Stream` whose items are exactly what each `yield` produces — far more readable than chaining combinators when each step depends on the last. For fallible logic, use `try_stream!` and `yield` values directly while propagating errors with `?`. # File Uploads > Handle multipart file uploads in Axum: where Express leans on multer's req.file, the Multipart extractor streams each part to disk with MIME checks. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A file upload is just an HTTP `POST` whose body is encoded as `multipart/form-data`: a sequence of named **parts**, each of which is either a plain form field or a file with a filename and content type. In Express you almost always reach for **multer** to parse that body and hand you `req.file`/`req.files`; in **Axum** the `Multipart` extractor (an opt-in feature) gives you an async stream of parts that you consume one field at a time. The big practical difference is that Axum lets you **stream each file straight to disk** without ever buffering the whole thing in memory, which matters once uploads get large. > **Note:** The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically. This page targets **axum 0.8** (`axum::serve` + `tokio::net::TcpListener`, `{id}` path captures, not the old `:id`). For the request body in general (`Json`, raw `Bytes`) see [Request and Response Handling](/16-web-apis/07-request-response/); for the extractor model that `Multipart` plugs into see [Extractors](/16-web-apis/04-extractors/). Serving the files you save back out is covered in [Static Files](/16-web-apis/18-static-files/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) A realistic Express upload endpoint using **multer** (`npm i multer`, currently 2.x). It accepts an avatar image plus a text field, validates the MIME type, caps the size, and writes the file to disk with a generated name. ```typescript 1 // uploads.ts — Express 5 + multer 2.x 2 import express, { Request, Response } from "express"; 3 import multer from "multer"; 4 import { randomUUID } from "node:crypto"; 5 import path from "node:path"; 6 7 const UPLOAD_DIR = "/var/app/uploads"; 8 const ALLOWED = new Set(["image/png", "image/jpeg", "image/webp"]); 9 10 // multer streams the part to disk; `storage` controls the destination + name. 11 const storage = multer.diskStorage({ 12 destination: (_req, _file, cb) => cb(null, UPLOAD_DIR), 13 filename: (_req, file, cb) => 14 cb(null, `${randomUUID()}${path.extname(file.originalname)}`), 15 }); 16 17 const upload = multer({ 18 storage, 19 limits: { fileSize: 5 * 1024 * 1024 }, // 5 MiB 20 fileFilter: (_req, file, cb) => { 21 if (!ALLOWED.has(file.mimetype)) { 22 cb(new Error(`content type ${file.mimetype} not allowed`)); 23 } else { 24 cb(null, true); 25 } 26 }, 27 }); 28 29 const app = express(); 30 31 // `upload.single("avatar")` parses ONE file field named "avatar". 32 app.post( 33 "/users/:id/avatar", 34 upload.single("avatar"), 35 (req: Request, res: Response) => { 36 if (!req.file) { 37 return res.status(400).json({ error: "no file field named `avatar`" }); 38 } 39 // Plain text fields land on req.body (parsed by multer, not express.json()). 40 const caption = (req.body.caption as string) ?? ""; 41 res.status(201).json({ 42 id: path.basename(req.file.filename), 43 bytes: req.file.size, 44 contentType: req.file.mimetype, 45 caption, 46 }); 47 }, 48 ); 49 50 // multer errors (e.g. LIMIT_FILE_SIZE, or a fileFilter rejection) arrive here. 51 app.use((err: Error, _req: Request, res: Response, _next: express.NextFunction) => { 52 res.status(400).json({ error: err.message }); 53 }); 54 55 app.listen(3000); ``` Two things are worth pinning down because they map directly to the Rust version: * multer does the buffering/streaming and the field parsing for you; your handler only sees the *result* (`req.file`, `req.body`). * The size limit and MIME filter are configured declaratively, and a violation surfaces as a thrown error that your error middleware turns into a response. > **Note:** `express.json()` does **not** parse `multipart/form-data`. If you forget multer (or `busboy`), `req.body` is empty and `req.file` is `undefined`: a classic “why is my upload empty” bug. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same endpoint in Axum. Enable the extractor with `cargo add axum --features multipart`, and add Tokio’s filesystem and stream-bridge helpers: Cargo.toml ```toml 1 [dependencies] 2 axum = { version = "0.8", features = ["multipart"] } 3 tokio = { version = "1", features = ["full"] } 4 tokio-util = { version = "0.7", features = ["io"] } # StreamReader: Stream -> AsyncRead 5 futures-util = "0.3" # TryStreamExt::map_err 6 serde = { version = "1", features = ["derive"] } 7 serde_json = "1" 8 uuid = { version = "1", features = ["v4"] } # random file names ``` ```rust 1 use axum::{ 2 extract::{DefaultBodyLimit, Multipart, State}, 3 http::StatusCode, 4 response::IntoResponse, 5 routing::post, 6 Json, Router, 7 }; 8 use futures_util::TryStreamExt; 9 use serde::Serialize; 10 use std::{io, path::PathBuf, sync::Arc}; 11 use tokio::io::{AsyncWriteExt, BufWriter}; 12 use tokio_util::io::StreamReader; 13 14 #[derive(Clone)] 15 struct AppState { 16 upload_dir: Arc<PathBuf>, 17 } 18 19 #[derive(Serialize)] 20 struct UploadOk { 21 id: String, 22 bytes: u64, 23 content_type: String, 24 } 25 26 const MAX_BYTES: u64 = 5 * 1024 * 1024; // 5 MiB per file 27 const ALLOWED: [&str; 3] = ["image/png", "image/jpeg", "image/webp"]; 28 29 async fn upload_avatar( 30 State(state): State<AppState>, 31 mut multipart: Multipart, 32 ) -> Result<Json<UploadOk>, (StatusCode, String)> { 33 // Pull parts off the stream one at a time. 34 while let Some(field) = multipart 35 .next_field() 36 .await 37 .map_err(|e| (StatusCode::BAD_REQUEST, format!("malformed upload: {e}")))? 38 { 39 // Skip everything that is not the "avatar" file field. 40 if field.name() != Some("avatar") { 41 continue; 42 } 43 44 let content_type = field.content_type().unwrap_or("").to_string(); 45 if !ALLOWED.contains(&content_type.as_str()) { 46 return Err(( 47 StatusCode::UNSUPPORTED_MEDIA_TYPE, 48 format!("content type {content_type} not allowed"), 49 )); 50 } 51 52 let id = uuid::Uuid::new_v4().to_string(); 53 let path = state.upload_dir.join(&id); 54 55 // Stream the body to disk; never hold the whole file in memory. 56 let bytes = stream_to_file(field, &path) 57 .await 58 .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, format!("write failed: {e}")))?; 59 60 return Ok(Json(UploadOk { id, bytes, content_type })); 61 } 62 63 Err((StatusCode::BAD_REQUEST, "no file field named `avatar`".into())) 64 } 65 66 /// Bridge the field's byte stream into an `AsyncRead` and copy it to a file. 67 async fn stream_to_file( 68 field: axum::extract::multipart::Field<'_>, 69 path: &std::path::Path, 70 ) -> io::Result<u64> { 71 // A `Field` is a `Stream<Item = Result<Bytes, MultipartError>>`. 72 // StreamReader needs the error to be `std::io::Error`, so map it first. 73 let body = field.map_err(io::Error::other); 74 let mut reader = StreamReader::new(body); 75 76 let file = tokio::fs::File::create(path).await?; 77 let mut writer = BufWriter::new(file); 78 79 let copied = tokio::io::copy(&mut reader, &mut writer).await?; 80 writer.flush().await?; 81 Ok(copied) 82 } 83 84 #[tokio::main] 85 async fn main() { 86 let upload_dir = PathBuf::from("/var/app/uploads"); 87 tokio::fs::create_dir_all(&upload_dir).await.unwrap(); 88 let state = AppState { upload_dir: Arc::new(upload_dir) }; 89 90 let app = Router::new() 91 .route("/users/{id}/avatar", post(upload_avatar)) 92 // Multipart bodies are NOT covered by the default 2 MiB limit's intent; 93 // set an explicit ceiling. Keep it above MAX_BYTES (see Common Pitfalls). 94 .layer(DefaultBodyLimit::max(8 * 1024 * 1024)) 95 .with_state(state); 96 97 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 98 println!("listening on {}", listener.local_addr().unwrap()); 99 axum::serve(listener, app).await.unwrap(); 100 } ``` Driving it with `curl` produces real, typed JSON responses: ```text 1 $ curl -s -w " HTTP %{http_code}\n" -X POST http://127.0.0.1:3000/users/42/avatar \ 2 -F "avatar=@avatar.png;type=image/png" 3 {"id":"a2c17697-4b96-400f-a4bf-0c29b892e2b5","bytes":4008,"content_type":"image/png"} HTTP 200 4 5 $ curl -s -w " HTTP %{http_code}\n" -X POST http://127.0.0.1:3000/users/42/avatar \ 6 -F "avatar=@notes.txt;type=text/plain" 7 content type text/plain not allowed HTTP 415 ``` (The numbers above are genuine output from running this exact code; your UUID and byte count will differ.) *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) **`Multipart` is an extractor, but a special one.** Like `Json` or `Path`, it implements the extractor machinery (`FromRequest`), so you list it as a handler argument and Axum builds it from the request. Unlike `Json`, it does **not** read the whole body up front — it hands you a cursor over the parts. Because it consumes the request body, `Multipart` must be the **last** argument in your handler (it implements `FromRequest`, not `FromRequestParts`). Put `State`, `Path`, and header extractors before it. See [Extractors](/16-web-apis/04-extractors/) for the ordering rule and why only one body-consuming extractor is allowed. **`next_field().await` walks the parts.** Each call returns `Result<Option<Field>, MultipartError>`: * `Ok(Some(field))`: another part is ready. * `Ok(None)`: the body is exhausted; the loop ends. * `Err(_)`: the body was malformed or violated a limit. You must drive this loop in order. A `Field` borrows the `Multipart` mutably, so you can only hold **one field at a time**. You cannot collect them into a `Vec` and process them later (the borrow checker enforces this; see Common Pitfalls). **Reading a field’s metadata.** `field.name()` is the form field name (the `name="..."` in the part header), `field.file_name()` is the client-supplied original filename (present only for file parts), and `field.content_type()` returns the part’s declared MIME type. All three return `Option<&str>`; a TS dev should treat them like values that might be `undefined`, because a malicious or buggy client can omit any of them. **Reading a field’s body — buffered vs. streamed.** This is the heart of the page: * `field.bytes().await` collects the *entire* part into a `Bytes` (an in-memory buffer). Convenient for small things (a JSON blob, a thumbnail), dangerous for large uploads: it is the moral equivalent of multer’s `memoryStorage`. * `field.text().await` is `bytes()` plus UTF-8 decoding, for plain text fields. * A `Field` is itself a `Stream` of `Bytes` chunks, so you can stream it. Either pull chunks manually with `field.chunk().await` (returns `Ok(Some(Bytes))` per chunk), or — as above — wrap it in `tokio_util::io::StreamReader` to turn the `Stream` into an `AsyncRead` and `tokio::io::copy` it into a file. Nothing larger than one chunk (a few KiB) is ever resident in memory. **The `map_err(io::Error::other)` line.** `StreamReader` requires the stream’s error type to be `std::io::Error`, but a `Field` yields `MultipartError`. `TryStreamExt::map_err` (from `futures-util`) converts each error, and `io::Error::other` wraps any `std::error::Error` into an `io::Error`. This adapter is the small bit of glue that connects Axum’s multipart stream to Tokio’s filesystem I/O. **`DefaultBodyLimit`.** Axum applies a default request-body limit (2 MiB). Multipart uploads routinely exceed that, so you set an explicit limit per route or per router with the `DefaultBodyLimit` layer. This is a coarse, whole-request guard that runs *before* your handler; it is not the same as a per-file cap (more on that contrast below). **No streaming-vs-buffered footgun in Express.** multer’s `diskStorage` already streams to disk for you, so the Express version doesn’t expose this choice. In Axum the choice is explicit and in your hands, which is more code, but also why you can do things like enforce a byte budget mid-stream or pipe directly to S3 without a temp file. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concern | Express + multer | Axum + `Multipart` | | -------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------- | | Parsing the body | Middleware (`multer(...)`) populates `req.file`/`req.body` | `Multipart` extractor yields a `Field` stream you consume | | Streaming to disk | `diskStorage` does it implicitly | Explicit: `StreamReader` + `tokio::io::copy`, or `field.chunk()` | | Buffer in memory | `memoryStorage` (`req.file.buffer`) | `field.bytes().await` | | Field ordering | All fields available after middleware runs | One `Field` at a time, in body order; cannot hold two at once | | Size limit | `limits.fileSize` (per file, enforced by multer) | `DefaultBodyLimit` (whole request) + your own per-field counter | | MIME validation | `fileFilter` callback | `field.content_type()` check in the loop | | Where errors surface | Thrown into error middleware | A `Result` your handler returns, or `MultipartError`’s own response | | Memory profile | Configurable, defaults to streaming via `diskStorage` | Streaming by default *if you write streaming code* | The conceptual shift: multer is a **declarative parser** you configure once; Axum’s `Multipart` is an **imperative stream** you iterate. That costs a few more lines but removes the magic: there is no hidden `req.file`, only the bytes you chose to read and where you chose to put them. > **Tip:** The “trust nothing from the client” rules are identical to Express. `file_name()` can contain `../` or absolute paths; never join it onto a directory unsanitized. The Best Practices section shows the fix. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### 1. Holding two fields at once (the borrow that won’t compile) [Section titled “1. Holding two fields at once (the borrow that won’t compile)”](#1-holding-two-fields-at-once-the-borrow-that-wont-compile) A `Field` borrows the `Multipart` mutably, so you cannot fetch a second field while still holding the first: ```rust 1 use axum::extract::Multipart; 2 3 async fn bad(mut multipart: Multipart) { 4 let first = multipart.next_field().await.unwrap().unwrap(); 5 let second = multipart.next_field().await.unwrap().unwrap(); // does not compile (error[E0499]) 6 println!("{:?} {:?}", first.name(), second.name()); 7 } ``` The real compiler error: ```text 1 error[E0499]: cannot borrow `multipart` as mutable more than once at a time 2 --> examples/bad.rs:5:18 3 | 4 4 | let first = multipart.next_field().await.unwrap().unwrap(); 5 | --------- first mutable borrow occurs here 6 5 | let second = multipart.next_field().await.unwrap().unwrap(); 7 | ^^^^^^^^^ second mutable borrow occurs here 8 6 | println!("{:?} {:?}", first.name(), second.name()); 9 | ----- first borrow later used here ``` The fix is to fully process (or copy out) one field — call `.bytes()`/`.text()`/stream it — before calling `next_field()` again. This is by design: it is what makes true streaming possible without buffering everything. ### 2. Forgetting the `multipart` feature [Section titled “2. Forgetting the multipart feature”](#2-forgetting-the-multipart-feature) `Multipart` does not exist in axum’s default build. Without `features = ["multipart"]`, `use axum::extract::Multipart;` fails to resolve (`error[E0432]: unresolved import`). Run `cargo add axum --features multipart`. ### 3. `DefaultBodyLimit` set *below* your per-field cap — and the resulting status [Section titled “3. DefaultBodyLimit set below your per-field cap — and the resulting status”](#3-defaultbodylimit-set-below-your-per-field-cap--and-the-resulting-status) This one is subtle and bites in production. The `DefaultBodyLimit` layer is a whole-request guard that trips *while the stream is being read*, surfacing inside your handler as a stream error — not as a clean “too large” you can branch on. If you map every multipart error to `400`, an over-limit upload returns `400` with a confusing message: ```text 1 $ curl -s -w "HTTP %{http_code}\n" -X POST http://127.0.0.1:3000/upload-stream \ 2 -F "data=@big.bin" # body > DefaultBodyLimit 3 malformed multipart: Error parsing `multipart/form-data` request 4 HTTP 400 ``` `MultipartError` actually carries the correct status itself. If you let `?` propagate it (handler returns `Result<_, MultipartError>`, since `MultipartError: IntoResponse`), the same request returns the right code: ```text 1 $ curl -s -w "HTTP %{http_code}\n" -X POST http://127.0.0.1:3000/upload-native \ 2 -F "data=@big.bin" 3 Request payload is too large 4 HTTP 413 ``` The practical rule: keep `DefaultBodyLimit` as a generous outer ceiling, and if you want a precise *per-file* limit with a clean `413` and partial-file cleanup, count bytes yourself as you stream (shown in the Real-World Example). If your outer limit is *smaller* than your per-field cap, the outer limit wins and your cap never runs. ### 4. Calling `field.bytes()` on a huge upload [Section titled “4. Calling field.bytes() on a huge upload”](#4-calling-fieldbytes-on-a-huge-upload) `field.bytes().await` allocates the whole part in memory. A handful of concurrent multi-hundred-MB uploads will exhaust RAM. Use it only for fields you know are small; stream everything else. ### 5. Expecting `Json`/`express.json()`-style parsing [Section titled “5. Expecting Json/express.json()-style parsing”](#5-expecting-jsonexpressjson-style-parsing) `multipart/form-data` is not JSON. There is no `Json` extractor that magically parses it, and (mirroring Express) a JSON body parser will not touch it. Use `Multipart`, then read text fields with `field.text()`. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Stream large uploads; buffer only small ones.** Default to `StreamReader` + `tokio::io::copy` (or `field.chunk()`). Reserve `field.bytes()` for parts you *know* are small. * **Always sanitize the client filename.** Never trust `field.file_name()`. Generate your own name (a UUID) for storage and treat the original name as untrusted display metadata. If you must keep the original, run it through `sanitize-filename` (`cargo add sanitize-filename`): ```rust 1 // `safe` strips path separators and other dangerous characters. 2 let safe = sanitize_filename::sanitize(field.file_name().unwrap_or("upload")); ``` * **Validate content type, but don’t trust it.** `field.content_type()` is what the client *claimed*. For security-sensitive uploads, also sniff the first bytes (e.g. magic numbers) or re-encode images server-side. * **Set an explicit `DefaultBodyLimit`** sized to your largest legitimate upload, kept above any per-field cap you enforce in code. * **Write to a temp file, then atomically rename** into place once the upload completes and validation passes, so partial or rejected uploads never appear as real files. * **Clean up on failure.** If a per-field cap or validation fails mid-stream, `remove_file` the partial. * **Put filesystem paths and limits in state/config**, not hardcoded: inject the upload directory via `State<T>` (see [State Management](/16-web-apis/06-state-management/)). * **For a clean error type**, return your own `AppError: IntoResponse` instead of `(StatusCode, String)` tuples once the handler grows. See [Error Handling in Web Apps](/16-web-apis/10-error-handling-web/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A production-flavored avatar endpoint that ties the practices together: it injects the upload directory via `State`, validates the MIME type, enforces a **precise per-file byte budget while streaming** (returning a clean `413` and cleaning up the partial file), and **atomically renames** a `.part` temp file into place on success. The custom `UploadError` maps each failure to the right status code. ```rust 1 use axum::{ 2 extract::{DefaultBodyLimit, Multipart, State}, 3 http::StatusCode, 4 response::IntoResponse, 5 routing::post, 6 Json, Router, 7 }; 8 use futures_util::TryStreamExt; 9 use serde::Serialize; 10 use std::{io, path::PathBuf, sync::Arc}; 11 use tokio::io::{AsyncReadExt, AsyncWriteExt, BufWriter}; 12 use tokio_util::io::StreamReader; 13 14 #[derive(Clone)] 15 struct AppState { 16 upload_dir: Arc<PathBuf>, 17 } 18 19 #[derive(Serialize)] 20 struct UploadOk { 21 id: String, 22 bytes: u64, 23 content_type: String, 24 } 25 26 #[derive(Debug)] 27 enum UploadError { 28 NoFile, 29 BadContentType(String), 30 TooLarge, 31 Multipart(String), 32 Io(io::Error), 33 } 34 35 const MAX_BYTES: u64 = 5 * 1024 * 1024; // 5 MiB per file 36 const ALLOWED: [&str; 3] = ["image/png", "image/jpeg", "image/webp"]; 37 38 // Each variant maps to a meaningful HTTP status + JSON error body. 39 impl IntoResponse for UploadError { 40 fn into_response(self) -> axum::response::Response { 41 let (status, msg) = match self { 42 UploadError::NoFile => { 43 (StatusCode::BAD_REQUEST, "no file field named `avatar`".to_string()) 44 } 45 UploadError::BadContentType(ct) => { 46 (StatusCode::UNSUPPORTED_MEDIA_TYPE, format!("content type {ct} not allowed")) 47 } 48 UploadError::TooLarge => { 49 (StatusCode::PAYLOAD_TOO_LARGE, format!("file exceeds {MAX_BYTES} bytes")) 50 } 51 UploadError::Multipart(e) => (StatusCode::BAD_REQUEST, format!("malformed upload: {e}")), 52 UploadError::Io(e) => { 53 (StatusCode::INTERNAL_SERVER_ERROR, format!("could not store file: {e}")) 54 } 55 }; 56 (status, Json(serde_json::json!({ "error": msg }))).into_response() 57 } 58 } 59 60 async fn upload_avatar( 61 State(state): State<AppState>, 62 mut multipart: Multipart, 63 ) -> Result<Json<UploadOk>, UploadError> { 64 while let Some(field) = multipart 65 .next_field() 66 .await 67 .map_err(|e| UploadError::Multipart(e.to_string()))? 68 { 69 if field.name() != Some("avatar") { 70 continue; 71 } 72 73 let content_type = field.content_type().unwrap_or("").to_string(); 74 if !ALLOWED.contains(&content_type.as_str()) { 75 return Err(UploadError::BadContentType(content_type)); 76 } 77 78 let id = uuid::Uuid::new_v4().to_string(); 79 let final_path = state.upload_dir.join(&id); 80 let tmp_path = state.upload_dir.join(format!("{id}.part")); 81 82 let written = write_capped(field, &tmp_path).await?; 83 84 // Only after a clean, fully-written upload do we publish the file. 85 tokio::fs::rename(&tmp_path, &final_path) 86 .await 87 .map_err(UploadError::Io)?; 88 89 return Ok(Json(UploadOk { id, bytes: written, content_type })); 90 } 91 92 Err(UploadError::NoFile) 93 } 94 95 /// Stream a field to `path`, aborting (and deleting the partial) past MAX_BYTES. 96 async fn write_capped( 97 field: axum::extract::multipart::Field<'_>, 98 path: &std::path::Path, 99 ) -> Result<u64, UploadError> { 100 let reader = StreamReader::new(field.map_err(io::Error::other)); 101 futures_util::pin_mut!(reader); 102 103 let file = tokio::fs::File::create(path).await.map_err(UploadError::Io)?; 104 let mut writer = BufWriter::new(file); 105 106 let mut buf = vec![0u8; 64 * 1024]; 107 let mut total: u64 = 0; 108 loop { 109 let n = reader.read(&mut buf).await.map_err(UploadError::Io)?; 110 if n == 0 { 111 break; // EOF: the part is fully read 112 } 113 total += n as u64; 114 if total > MAX_BYTES { 115 let _ = tokio::fs::remove_file(path).await; // clean up the partial 116 return Err(UploadError::TooLarge); 117 } 118 writer.write_all(&buf[..n]).await.map_err(UploadError::Io)?; 119 } 120 writer.flush().await.map_err(UploadError::Io)?; 121 Ok(total) 122 } 123 124 #[tokio::main] 125 async fn main() { 126 let upload_dir = PathBuf::from("/var/app/uploads"); 127 tokio::fs::create_dir_all(&upload_dir).await.unwrap(); 128 let state = AppState { upload_dir: Arc::new(upload_dir) }; 129 130 let app = Router::new() 131 .route("/users/{id}/avatar", post(upload_avatar)) 132 // Generous outer ceiling; the precise per-file cap is enforced in code. 133 .layer(DefaultBodyLimit::max(50 * 1024 * 1024)) 134 .with_state(state); 135 136 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 137 println!("listening on {}", listener.local_addr().unwrap()); 138 axum::serve(listener, app).await.unwrap(); 139 } ``` This needs `serde_json` in addition to the earlier deps: `cargo add serde_json`. Exercising all three paths against the running server gives real output: ```text 1 $ curl -s -w " HTTP %{http_code}\n" -X POST http://127.0.0.1:3000/users/42/avatar \ 2 -F "avatar=@avatar.png;type=image/png" 3 {"id":"a2c17697-4b96-400f-a4bf-0c29b892e2b5","bytes":4008,"content_type":"image/png"} HTTP 200 4 5 $ curl -s -w " HTTP %{http_code}\n" -X POST http://127.0.0.1:3000/users/42/avatar \ 6 -F "avatar=@notes.txt;type=text/plain" 7 {"error":"content type text/plain not allowed"} HTTP 415 8 9 $ curl -s -w " HTTP %{http_code}\n" -X POST http://127.0.0.1:3000/users/42/avatar \ 10 -F "avatar=@big.png;type=image/png" # 6 MiB, over the per-file cap 11 {"error":"file exceeds 5242880 bytes"} HTTP 413 ``` After these requests, the upload directory contains exactly one complete file (the valid PNG) and **no leftover `.part` file**: the over-limit upload was deleted mid-stream. That cleanup is the payoff of streaming with your own byte counter instead of leaning on `field.bytes()` or the outer body limit alone. > **Note:** For very large uploads in real deployments, prefer streaming straight to object storage (S3 multipart upload) or a reverse proxy that buffers to disk, rather than the application server’s local filesystem. The streaming pattern here is exactly what an S3 sink plugs into: replace the `File` with the storage client’s writer. *** ## Further Reading [Section titled “Further Reading”](#further-reading) * [`axum::extract::Multipart`](https://docs.rs/axum/latest/axum/extract/struct.Multipart.html): the extractor, `next_field`, and the feature flag. * [`axum::extract::multipart::Field`](https://docs.rs/axum/latest/axum/extract/multipart/struct.Field.html): `name`, `file_name`, `content_type`, `bytes`, `text`, `chunk`, and the `Stream` impl. * [`axum::extract::DefaultBodyLimit`](https://docs.rs/axum/latest/axum/extract/struct.DefaultBodyLimit.html): configuring or disabling the request-body limit. * [`tokio_util::io::StreamReader`](https://docs.rs/tokio-util/latest/tokio_util/io/struct.StreamReader.html): turning a `Stream<Bytes>` into an `AsyncRead`. * [`tokio::fs` and `tokio::io::copy`](https://docs.rs/tokio/latest/tokio/io/fn.copy.html): async filesystem I/O. Within this guide: * [Extractors](/16-web-apis/04-extractors/) — why `Multipart` must be the last argument and how `FromRequest` differs from `FromRequestParts`. * [Request and Response Handling](/16-web-apis/07-request-response/) — the body in general, `IntoResponse`, status-code tuples. * [State Management](/16-web-apis/06-state-management/): injecting the upload directory and config via `State<T>` + `Arc`. * [Error Handling in Web Apps](/16-web-apis/10-error-handling-web/) — a fuller `AppError: IntoResponse` than the one shown here. * [Static Files](/16-web-apis/18-static-files/): serving the files you just saved back to clients. * [Routing](/16-web-apis/03-routing/): the `{id}` path syntax used in `/users/{id}/avatar`. * Foundations: async [futures and streams](/11-async/) (a `Field` *is* a stream), [error handling](/08-error-handling/) (`Result` and the `?` operator), [traits](/09-generics-traits/) (what `IntoResponse` is), and the language [basics](/02-basics/) / [getting started](/01-getting-started/). * Persisting upload metadata (filename, owner, size) alongside the bytes: [Database](/17-database/). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1 — Count and summarize fields [Section titled “Exercise 1 — Count and summarize fields”](#exercise-1--count-and-summarize-fields) **Difficulty:** Beginner **Objective:** Get comfortable iterating multipart fields and distinguishing file parts from plain text fields. **Instructions:** Write a handler `summarize(mut multipart: Multipart)` that consumes a `multipart/form-data` body and returns JSON of the form `{ "text_fields": N, "files": M }`, where text fields are parts with no filename and files are parts with one. Read each text field with `.text()` (you may discard the value) and each file with `.bytes()` for now. Map any `MultipartError` to a `400`. Solution ```rust 1 use axum::{extract::Multipart, http::StatusCode, Json}; 2 use serde::Serialize; 3 4 #[derive(Serialize)] 5 struct Counts { 6 text_fields: usize, 7 files: usize, 8 } 9 10 async fn summarize( 11 mut multipart: Multipart, 12 ) -> Result<Json<Counts>, (StatusCode, String)> { 13 let mut text_fields = 0usize; 14 let mut files = 0usize; 15 16 while let Some(field) = multipart 17 .next_field() 18 .await 19 .map_err(|e| (StatusCode::BAD_REQUEST, format!("malformed upload: {e}")))? 20 { 21 if field.file_name().is_some() { 22 // Consume the file body so we can advance to the next field. 23 field 24 .bytes() 25 .await 26 .map_err(|e| (StatusCode::BAD_REQUEST, format!("read failed: {e}")))?; 27 files += 1; 28 } else { 29 field 30 .text() 31 .await 32 .map_err(|e| (StatusCode::BAD_REQUEST, format!("read failed: {e}")))?; 33 text_fields += 1; 34 } 35 } 36 37 Ok(Json(Counts { text_fields, files })) 38 } ``` Mount it with `.route("/summarize", axum::routing::post(summarize))`. A request with one text field and two files returns `{"text_fields":1,"files":2}`. ### Exercise 2 — Stream to disk with a safe filename [Section titled “Exercise 2 — Stream to disk with a safe filename”](#exercise-2--stream-to-disk-with-a-safe-filename) **Difficulty:** Intermediate **Objective:** Stream a single uploaded file to disk without buffering it, using a sanitized, collision-free name. **Instructions:** Write `save_upload(mut multipart: Multipart)` that takes the first file part, builds a storage name of the form `<uuid>-<sanitized-original-name>`, streams the body to `/tmp/uploads/<name>` using `StreamReader` + `tokio::io::copy` (no `.bytes()`), and returns JSON `{ "saved": "<full path>", "bytes": N }`. Use `cargo add sanitize-filename uuid --features uuid/v4`. Skip non-file parts. Solution ```rust 1 use axum::{ 2 extract::Multipart, 3 http::StatusCode, 4 Json, 5 }; 6 use futures_util::TryStreamExt; 7 use serde::Serialize; 8 use std::{io, path::PathBuf}; 9 use tokio::io::AsyncWriteExt; 10 use tokio_util::io::StreamReader; 11 12 #[derive(Serialize)] 13 struct Saved { 14 saved: String, 15 bytes: u64, 16 } 17 18 async fn save_upload( 19 mut multipart: Multipart, 20 ) -> Result<Json<Saved>, (StatusCode, String)> { 21 while let Some(field) = multipart 22 .next_field() 23 .await 24 .map_err(|e| (StatusCode::BAD_REQUEST, format!("malformed upload: {e}")))? 25 { 26 let Some(original) = field.file_name().map(|s| s.to_string()) else { 27 continue; // not a file part 28 }; 29 30 let safe = sanitize_filename::sanitize(&original); 31 let id = uuid::Uuid::new_v4(); 32 let path = PathBuf::from("/tmp/uploads").join(format!("{id}-{safe}")); 33 34 tokio::fs::create_dir_all("/tmp/uploads") 35 .await 36 .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?; 37 38 let bytes = stream_to_file(field, &path) 39 .await 40 .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, format!("write failed: {e}")))?; 41 42 return Ok(Json(Saved { 43 saved: path.display().to_string(), 44 bytes, 45 })); 46 } 47 48 Err((StatusCode::BAD_REQUEST, "no file part found".into())) 49 } 50 51 async fn stream_to_file( 52 field: axum::extract::multipart::Field<'_>, 53 path: &std::path::Path, 54 ) -> io::Result<u64> { 55 let mut reader = StreamReader::new(field.map_err(io::Error::other)); 56 let mut file = tokio::fs::File::create(path).await?; 57 let copied = tokio::io::copy(&mut reader, &mut file).await?; 58 file.flush().await?; 59 Ok(copied) 60 } ``` `sanitize_filename::sanitize("../../etc/passwd")` becomes `"....etcpasswd"`, and the UUID prefix guarantees no two uploads collide. ### Exercise 3 — Per-file size cap returning a clean 413 [Section titled “Exercise 3 — Per-file size cap returning a clean 413”](#exercise-3--per-file-size-cap-returning-a-clean-413) **Difficulty:** Advanced **Objective:** Enforce a precise per-file byte limit while streaming, returning `413 Payload Too Large` with a JSON body and leaving no partial file behind — without relying on `DefaultBodyLimit`. **Instructions:** Implement `write_limited(field, path, max: u64) -> Result<u64, UploadError>` that streams the field to `path` chunk by chunk (manually, or via `StreamReader` + a read loop), tracks the running byte total, and as soon as it exceeds `max`, deletes the partial file and returns an error variant that your `IntoResponse` maps to `413`. Wire it into a handler whose router uses a *generous* `DefaultBodyLimit` (so your cap is the binding constraint). Confirm that an over-cap upload returns `413` and that the directory is empty afterward. Solution ```rust 1 use axum::{ 2 extract::{DefaultBodyLimit, Multipart}, 3 http::StatusCode, 4 response::IntoResponse, 5 routing::post, 6 Json, Router, 7 }; 8 use futures_util::TryStreamExt; 9 use serde::Serialize; 10 use std::{io, path::PathBuf}; 11 use tokio::io::{AsyncReadExt, AsyncWriteExt, BufWriter}; 12 use tokio_util::io::StreamReader; 13 14 const MAX_BYTES: u64 = 1024 * 1024; // 1 MiB 15 16 #[derive(Debug)] 17 enum UploadError { 18 NoFile, 19 TooLarge, 20 Multipart(String), 21 Io(io::Error), 22 } 23 24 impl IntoResponse for UploadError { 25 fn into_response(self) -> axum::response::Response { 26 let (status, msg) = match self { 27 UploadError::NoFile => (StatusCode::BAD_REQUEST, "no file part".to_string()), 28 UploadError::TooLarge => { 29 (StatusCode::PAYLOAD_TOO_LARGE, format!("file exceeds {MAX_BYTES} bytes")) 30 } 31 UploadError::Multipart(e) => (StatusCode::BAD_REQUEST, format!("malformed upload: {e}")), 32 UploadError::Io(e) => (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()), 33 }; 34 (status, Json(serde_json::json!({ "error": msg }))).into_response() 35 } 36 } 37 38 #[derive(Serialize)] 39 struct Saved { 40 bytes: u64, 41 } 42 43 async fn upload(mut multipart: Multipart) -> Result<Json<Saved>, UploadError> { 44 while let Some(field) = multipart 45 .next_field() 46 .await 47 .map_err(|e| UploadError::Multipart(e.to_string()))? 48 { 49 if field.file_name().is_none() { 50 continue; 51 } 52 tokio::fs::create_dir_all("/tmp/capped") 53 .await 54 .map_err(UploadError::Io)?; 55 let path = PathBuf::from("/tmp/capped").join(uuid::Uuid::new_v4().to_string()); 56 let bytes = write_limited(field, &path, MAX_BYTES).await?; 57 return Ok(Json(Saved { bytes })); 58 } 59 Err(UploadError::NoFile) 60 } 61 62 async fn write_limited( 63 field: axum::extract::multipart::Field<'_>, 64 path: &std::path::Path, 65 max: u64, 66 ) -> Result<u64, UploadError> { 67 let reader = StreamReader::new(field.map_err(io::Error::other)); 68 futures_util::pin_mut!(reader); 69 70 let file = tokio::fs::File::create(path).await.map_err(UploadError::Io)?; 71 let mut writer = BufWriter::new(file); 72 73 let mut buf = vec![0u8; 64 * 1024]; 74 let mut total: u64 = 0; 75 loop { 76 let n = reader.read(&mut buf).await.map_err(UploadError::Io)?; 77 if n == 0 { 78 break; 79 } 80 total += n as u64; 81 if total > max { 82 let _ = tokio::fs::remove_file(path).await; 83 return Err(UploadError::TooLarge); 84 } 85 writer.write_all(&buf[..n]).await.map_err(UploadError::Io)?; 86 } 87 writer.flush().await.map_err(UploadError::Io)?; 88 Ok(total) 89 } 90 91 #[tokio::main] 92 async fn main() { 93 let app = Router::new() 94 .route("/upload", post(upload)) 95 .layer(DefaultBodyLimit::max(50 * 1024 * 1024)); // generous outer ceiling 96 97 let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap(); 98 axum::serve(listener, app).await.unwrap(); 99 } ``` Uploading a 2 MiB file returns `{"error":"file exceeds 1048576 bytes"}` with `HTTP 413`, and `/tmp/capped` is left empty because the partial was removed mid-stream. The key design point — and the reason this exercise is “advanced” — is that the *outer* `DefaultBodyLimit` is set far above `MAX_BYTES`, so your in-handler counter is the constraint that actually fires, giving you control over both the status code and the cleanup. # Serving Static Files with Axum > Serve static files in Axum with tower-http's ServeDir and ServeFile, the equivalent of Express express.static, plus the SPA index.html fallback that returns 200. ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Almost every web service eventually needs to hand a browser some bytes off disk — a built **single-page app** (SPA), an `index.html`, CSS/JS bundles, images, a `robots.txt`. In Express you reach for the built-in `express.static` middleware; in Axum you mount a **`tower-http` file-serving service**: `ServeDir` for a whole directory tree, `ServeFile` for one specific file. This page shows how to wire those services into a `Router`, how to combine them with real API routes, and how to do the one thing every SPA needs: a **fallback to `index.html`** so client-side routes like `/dashboard/settings` load the app instead of returning a 404. > **Note:** This page targets **axum 0.8** (recorded with 0.8.9) and **tower-http 0.6** (recorded with 0.6.11). The repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) uses the 2024 edition; `cargo new` selects that edition automatically. Servers start with `axum::serve(listener, app)` and a `tokio::net::TcpListener`. File-serving lives behind tower-http’s opt-in `fs` feature. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In Express, static file serving is a single line: `express.static` returns a middleware that, for each request, tries to find a matching file under a root directory and streams it, complete with the right `Content-Type`, `Last-Modified`, `ETag`, conditional-request (304) handling, and an optional `maxAge` cache header. Anything it does not find, it passes to the next middleware. ```typescript 1 // server.ts — Express 5 2 // npm install express 3 // npm install -D @types/express 4 import express from "express"; 5 6 const app = express(); 7 8 // 1) Serve everything under ./public at the URL root. 9 // GET / -> public/index.html (default index) 10 // GET /style.css -> public/style.css 11 // GET /js/app.js -> public/js/app.js 12 app.use(express.static("public", { maxAge: "1h" })); 13 14 // 2) A real API route still works — it is just another middleware. 15 app.get("/api/health", (_req, res) => { 16 res.json({ status: "ok" }); 17 }); 18 19 app.listen(3000, () => { 20 console.log("listening on http://127.0.0.1:3000"); 21 }); ``` Running this and probing it (with Node v22’s built-in `fetch`) shows the behavior a TypeScript developer relies on: ```text 1 / -> 200 text/html; charset=UTF-8 cc=public, max-age=3600 2 /api/health -> 200 application/json; charset=utf-8 cc=null 3 /missing.html -> 404 text/html; charset=utf-8 cc=null ``` So `express.static` (a) serves `index.html` for a directory, (b) applies the `maxAge` cache header, and (c) returns a 404 for files it cannot find. For a single-page app you typically add one more line so that unknown paths return `index.html`: ```typescript 1 // SPA fallback: any GET that did not match a file or API route gets index.html, 2 // so the client-side router (React Router, etc.) can take over. 3 import path from "node:path"; 4 5 app.get("/{*splat}", (_req, res) => { 6 res.sendFile(path.resolve("public/index.html")); 7 }); ``` Three jobs, then: serve a directory, serve one file, and fall back to the app shell. Axum has a dedicated, well-tested service for each. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The file-serving services live in `tower-http`, gated behind the `fs` feature. Add the dependencies in a fresh project (`cargo new static-demo`): ```bash 1 cargo add axum 2 cargo add tokio --features full 3 cargo add tower-http --features fs ``` ```toml 1 # Cargo.toml (resolved versions) 2 [dependencies] 3 axum = "0.8" 4 tokio = { version = "1", features = ["full"] } 5 tower-http = { version = "0.6", features = ["fs"] } ``` > **Note:** tower-http’s features are opt-in. `ServeDir`/`ServeFile` need `fs`; the same `fs` feature also enables `.precompressed_gzip()` and friends shown later. You do **not** need a separate `compression-gzip` feature just to serve pre-built `.gz` files. Here is the direct equivalent of the Express example: `ServeDir` for the directory, `ServeFile` for a single named file, and an ordinary handler for the API: ```rust 1 use axum::{routing::get, Json, Router}; 2 use serde_json::{json, Value}; 3 use tower_http::services::{ServeDir, ServeFile}; 4 5 async fn health() -> Json<Value> { 6 Json(json!({ "status": "ok" })) 7 } 8 9 fn app() -> Router { 10 // Serve a single file at a specific route. 11 let favicon = ServeFile::new("public/favicon.ico"); 12 13 // Serve a whole directory tree. 14 let static_files = ServeDir::new("public"); 15 16 Router::new() 17 // Real API routes take priority because they are matched first. 18 .route("/api/health", get(health)) 19 // `route_service` mounts a tower Service (not a handler) at one path. 20 .route_service("/favicon.ico", favicon) 21 // Anything not matched above is looked up on disk under ./public. 22 .fallback_service(static_files) 23 } 24 25 #[tokio::main] 26 async fn main() { 27 let listener = tokio::net::TcpListener::bind("127.0.0.1:3007").await.unwrap(); 28 println!("listening on http://{}", listener.local_addr().unwrap()); 29 axum::serve(listener, app()).await.unwrap(); 30 } ``` This also needs `serde_json` (`cargo add serde_json`). Running it and probing with `curl -i` produces this **real output**: ```text 1 $ curl -s -i http://127.0.0.1:3007/ 2 HTTP/1.1 200 OK 3 content-type: text/html 4 accept-ranges: bytes 5 last-modified: Mon, 01 Jun 2026 12:13:21 GMT 6 content-length: 65 7 8 <!doctype html><title>Home

This is the full developer documentation for Rust for TS/JS Developers # Rust for TypeScript & JavaScript Developers > Learn Rust through side-by-side TypeScript and JavaScript comparisons covering ownership, errors, async, web APIs, databases, WebAssembly, and production. free · open source · written for TS/JS developers # Learn Rust from the TS/JS you know This guide assumes you already write TypeScript or JavaScript. It uses familiar code to explain ownership, error handling, traits, async, and the Rust ecosystem, including the points where Rust needs a different approach. $ you’ll learn ownership and borrowing [start the guide](/00-introduction/)[why Rust?](/01-getting-started/00-why-rust/)[view the source](https://github.com/zeybek/rs4ts.dev) // one\_problem\_two\_languages familiar control flow, explicit error types user.ts→user.rs typescript// familiar control flow ```ts 1 type User = { id: string; name: string }; 2 3 async function getUser(id: string): Promise { 4 const response = await fetch("/api/users/" + id); 5 if (!response.ok) throw new Error("request failed"); 6 return response.json(); 7 } ``` rust// failure stays in the return type ```rust 1 struct User { id: String, name: String } 2 3 async fn get_user(id: &str) -> Result { 4 let url = format!("/api/users/{id}"); 5 let response = reqwest::get(url).await?.error_for_status()?; 6 Ok(response.json().await?) 7 } ``` 31Guide sections 6Capstone projects 2024Rust edition MITOpen source // how\_it\_works ## how the guide is organized [Section titled “how the guide is organized”](#how-the-guide-is-organized) ### Start from familiar code Chapters put familiar TS/JS code beside its Rust equivalent, then explain the rules behind the differences. ### Compare semantics, not just syntax The guide marks places where familiar syntax behaves differently, especially around ownership, errors, async execution, and type modeling. ### Read errors with the working code Compiler messages and common mistakes are explained beside the corrected version, so the rejected code has context. ### Practice beyond isolated snippets Exercises reinforce individual topics. Six dependency-locked capstone crates combine them in complete programs checked by CI. // core\_differences ## three differences to understand first [Section titled “three differences to understand first”](#three-differences-to-understand-first) 01 ### ownership\_and\_borrowing/ JavaScript relies on garbage collection. Rust uses ownership and borrowing to make data lifetime and mutation rules explicit at compile time. \[ownership]\[borrow]\[lifetimes]\[drop] ownership.rs ```rust 1 let s = String::from("hello"); 2 let s2 = s; // ownership moves to s2 3 // println!("{s}"); // compile error: s no longer valid 4 println!("{s2}"); // ok: s2 owns the string ``` 02 ### result\_and\_option/ For recoverable failures, Rust returns `Result`; missing values are `Option`. The `?` operator propagates errors without hiding them from the function signature. \[result]\[option]\[question\_mark]\[error\_types] errors.rs ```rust 1 fn parse_double(input: &str) -> Result { 2 let n: i32 = input.trim().parse()?; // ? propagates the error 3 Ok(n * 2) 4 } ``` 03 ### async\_and\_concurrency/ The `async`/`await` syntax is familiar, but Rust futures are lazy and need an executor such as Tokio. Async coordinates waiting; CPU-bound parallelism is a separate choice. \[future]\[tokio]\[tasks]\[channels] async.rs ```rust 1 #[tokio::main] 2 async fn main() { 3 // Tokio's runtime drives both futures concurrently 4 let (a, b) = tokio::join!(fetch_user(1), fetch_user(2)); 5 println!("{a:?} {b:?}"); 6 } ``` // curriculum ## one guide, three stages [Section titled “one guide, three stages”](#one-guide-three-stages) language/00–15 Setup and syntax lead into **ownership**, collections, errors, traits, async, testing, macros, and serialization. ****** applications/ **build here**16–24 Build with **Axum**, SQLx, CLI tooling, WebAssembly, FFI, performance tools, common patterns, and the Rust ecosystem. ****** shipping/25–30 Continue with advanced topics, systems programming, **security**, production operations, migration, and the capstone projects. ****** The chapter order is the default route, not a requirement. Use the sidebar to open a topic directly when a project gives you a concrete question. // capstone\_projects ## use Rust in complete programs [Section titled “use Rust in complete programs”](#use-rust-in-complete-programs) [01REST API/30-projects/00-rest-api/an Express-style CRUD service with Axum, validation, and typed errors→](/30-projects/00-rest-api/)[02CLI task manager/30-projects/01-cli-tool/subcommands, JSON persistence, file I/O, and recoverable errors→](/30-projects/01-cli-tool/)[03WebSocket chat/30-projects/03-websocket-chat/rooms, Tokio broadcast channels, shared state, and JSON messages→](/30-projects/03-websocket-chat/)[04Full-stack notes app/30-projects/05-full-stack/an Axum API and WebAssembly frontend in one Cargo workspace→](/30-projects/05-full-stack/) The project section also includes a WASM Game of Life and a production-shaped URL shortener. [Browse all six projects →](/30-projects/) ## start with the introduction [Section titled “start with the introduction”](#start-with-the-introduction) It explains the intended audience, prerequisites, suggested routes, and how to use the TS/JS comparisons without treating them as exact equivalents. [start the guide](/00-introduction/)[browse the projects](/30-projects/) github.com/zeybek/rs4ts.dev · MIT licensed · no analytics \>\_rs4ts A free guide to Rust for developers who already know TypeScript or JavaScript. [](https://github.com/zeybek/rs4ts.dev)[](https://github.com/zeybek/rs4ts.dev/stargazers)[](/llms.txt) [start reading](/00-introduction/)[projects](/30-projects/)[migration](/29-migration-guide/)[contributing](https://github.com/zeybek/rs4ts.dev/blob/main/CONTRIBUTING.md)[license](https://github.com/zeybek/rs4ts.dev/blob/main/LICENSE) © 2026 rs4ts.dev · MIT licensed · built by [zeybek](https://github.com/zeybek)six capstone crates are checked in CI # Introduction > Welcome to Rust for TS/JS Developers! This section introduces the guide and helps you get oriented. Welcome to **Rust for TS/JS Developers**! This section introduces the guide and helps you get oriented. *** ## What’s in This Section [Section titled “What’s in This Section”](#whats-in-this-section) * **[Target Audience](/00-introduction/00-target-audience/)** - Who this guide is for * **[How to Read This Guide](/00-introduction/01-how-to-read/)** - Learning strategies and navigation * **[Prerequisites](/00-introduction/02-prerequisites/)** - What you need to know before starting *** ## About This Guide [Section titled “About This Guide”](#about-this-guide) This is a thorough, book-style guide designed specifically for TypeScript and JavaScript developers who want to learn Rust. Unlike general Rust tutorials, this guide: ### Leverages Your Existing Knowledge [Section titled “Leverages Your Existing Knowledge”](#leverages-your-existing-knowledge) We assume you already know TypeScript/JavaScript well. Instead of explaining programming from scratch, we: * **Show familiar code first** - Start with TypeScript/JavaScript you already understand * **Compare side-by-side** - See the Rust equivalent next to familiar code * **Explain the differences** - Focus on what’s new, not what you already know * **Flag gotchas** - Point out common mistakes TS/JS developers make ### Example: Variables [Section titled “Example: Variables”](#example-variables) Instead of just teaching Rust variables, we compare: **TypeScript:** ```typescript 1 let x = 5; // mutable 2 const y = 10; // immutable 3 x = 6; // allowed 4 // y = 11; // error ``` **Rust:** ```rust 1 let x = 5; // immutable by default! 2 let mut y = 10; // explicitly mutable 3 // x = 6; // error - x is immutable 4 y = 11; // allowed - y is mut ``` **Key Difference:** Rust is immutable by default (opposite of JavaScript!) *** ## What You’ll Learn [Section titled “What You’ll Learn”](#what-youll-learn) ### Core Rust Concepts [Section titled “Core Rust Concepts”](#core-rust-concepts) 1. **The Ownership System** - Rust’s secret sauce for memory safety without garbage collection 2. **Borrowing & Lifetimes** - How Rust prevents data races at compile time 3. **Type System** - Stronger than TypeScript’s, but for good reasons 4. **Error Handling** - No exceptions, use Result and Option instead 5. **Pattern Matching** - Like switch statements on steroids 6. **Traits** - Similar to interfaces but more capable 7. **Async/Await** - Different syntax, same concepts 8. **Macros** - Compile-time code transforms (closer to Babel plugins than to decorators) ### Practical Skills [Section titled “Practical Skills”](#practical-skills) * Building REST APIs (Axum vs Express) * Working with databases (SQLx, Diesel) * Creating CLI tools (better performance than Node.js CLIs) * WebAssembly (run Rust in the browser) * Systems programming * Performance optimization * Production deployment *** ## Why Learn Rust? [Section titled “Why Learn Rust?”](#why-learn-rust) ### For TypeScript/JavaScript Developers [Section titled “For TypeScript/JavaScript Developers”](#for-typescriptjavascript-developers) **You should learn Rust if you want to:** * Build **high-performance backends** (no GC pauses; far lower p99 latency and memory use than Node.js) * Create **CLI tools** that start instantly (no Node.js startup time) * Eliminate **entire classes of bugs** at compile time * Work on **systems programming** (OS, embedded, game engines) * Add **Rust to JavaScript** via WebAssembly or native addons * Learn a language that **makes you a better programmer** **Rust might NOT be for you if:** * You only build simple web frontends (stick with TypeScript) * You need extremely fast development iteration (Node.js is faster to prototype) * Your team isn’t ready for the learning curve * You’re building CRUD apps where performance isn’t critical ### Real-World Use Cases [Section titled “Real-World Use Cases”](#real-world-use-cases) **Companies using Rust:** * **Discord** - Rewrote its Read States service from Go to Rust, eliminating GC latency spikes * **AWS** - Building Firecracker, Lambda runtime * **Microsoft** - Windows components, Azure services * **Meta** - Source control system (Sapling) * **Cloudflare** - Edge computing platform * **Dropbox** - File sync engine * **npm** - Registry authorization service **Common Rust Projects:** * Web servers (faster than Node.js) * CLI tools (replace Node.js CLIs) * Game engines * Blockchain/crypto * Embedded systems * Operating systems * Database engines * Network tools *** ## Guide Philosophy [Section titled “Guide Philosophy”](#guide-philosophy) ### 1. Side-by-Side Comparisons [Section titled “1. Side-by-Side Comparisons”](#1-side-by-side-comparisons) We **always** show TypeScript/JavaScript first, then Rust. This helps you: * Connect new concepts to existing knowledge * Understand why Rust does things differently * Spot patterns and differences quickly ### 2. Real-World Examples [Section titled “2. Real-World Examples”](#2-real-world-examples) No toy examples or contrived code. Every example: * Uses realistic scenarios * Includes proper error handling * Follows best practices * Could be used in production ### 3. Honest About Trade-offs [Section titled “3. Honest About Trade-offs”](#3-honest-about-trade-offs) We don’t pretend Rust is perfect. We’ll tell you: * When Rust is harder than TypeScript * When Node.js might be a better choice * Where the learning curve gets steep * How to overcome common struggles ### 4. Progressive Learning [Section titled “4. Progressive Learning”](#4-progressive-learning) Content is carefully sequenced: * Foundation → Core Language → Practical Skills → Advanced Topics → Production * Each section builds on previous ones * Dependencies are clearly marked * You can skip ahead, but we don’t recommend it *** ## How This Guide Is Different [Section titled “How This Guide Is Different”](#how-this-guide-is-different) ### vs. The Rust Book [Section titled “vs. The Rust Book”](#vs-the-rust-book) * **The Rust Book:** Thorough, assumes no prior programming knowledge * **This Guide:** Assumes strong TS/JS knowledge, focuses on differences ### vs. Rust by Example [Section titled “vs. Rust by Example”](#vs-rust-by-example) * **Rust by Example:** Brief examples with minimal explanation * **This Guide:** Detailed explanations with side-by-side comparisons ### vs. YouTube Tutorials [Section titled “vs. YouTube Tutorials”](#vs-youtube-tutorials) * **YouTube:** Sequential watching, hard to reference * **This Guide:** Written format, easy to search, return to, and reference ### vs. Rustlings [Section titled “vs. Rustlings”](#vs-rustlings) * **Rustlings:** Small exercises to learn by doing * **This Guide:** Full explanations + exercises **Best approach:** Use this guide as your primary resource, supplement with The Rust Book and Rustlings for practice. *** ## The Journey Ahead [Section titled “The Journey Ahead”](#the-journey-ahead) The guide moves through four phases: **Foundation** (sections 00-05, where ownership lives — take your time here), **Core Language** (06-10: data structures, collections, error handling, traits — you’ll start feeling productive), **Practical Skills** (11-19: web APIs, CLI tools, WASM — where Rust becomes fun), and **Advanced Topics** (20-30: production readiness and complete projects). Time estimates and suggested reading paths live in [How to Read This Guide](/00-introduction/01-how-to-read/). *** ## Overcoming the Learning Curve [Section titled “Overcoming the Learning Curve”](#overcoming-the-learning-curve) ### Common Struggles [Section titled “Common Struggles”](#common-struggles) **Week 1:** “Why won’t the compiler let me do this simple thing?” * Normal! The borrow checker is strict * Your code is probably not wrong, just needs restructuring * This teaches you to write better code **Week 2-3:** “I’m fighting with lifetimes!” * Also normal! Lifetimes are the hardest part * Most code doesn’t need explicit lifetime annotations * It gets easier with practice **Week 4+:** “Oh, I get it now!” * The “aha!” moment * Everything starts to make sense * You begin appreciating Rust’s design ### Tips for Success [Section titled “Tips for Success”](#tips-for-success) 1. **Don’t fight the compiler** - It’s trying to help you 2. **Read error messages carefully** - They’re very helpful 3. **Practice daily** - Even 30 minutes helps 4. **Join the community** - Discord, Reddit, forums 5. **Build projects** - Theory only goes so far 6. **Be patient** - Everyone struggles at first 7. **Celebrate small wins** - You’re learning a hard language! *** ## Next Steps [Section titled “Next Steps”](#next-steps) Ready to begin? Here’s your roadmap: 1. **You’re here!** - Introduction 2. **[Target Audience](/00-introduction/00-target-audience/)** - Make sure this guide is right for you 3. **[How to Read](/00-introduction/01-how-to-read/)** - Learn navigation strategies 4. **[Prerequisites](/00-introduction/02-prerequisites/)** - Verify you’re ready 5. **[Section 01: Getting Started](/01-getting-started/)** - Install Rust and write your first program! *** ## Questions? [Section titled “Questions?”](#questions) * **“Should I learn Rust or Go?”** - Different use cases. Rust for systems/performance, Go for simplicity/concurrency * **“Will this replace JavaScript?”** - No, different domains. But you might build backends in Rust * **“How long until I’m productive?”** - 3-4 weeks for basic projects, 2-3 months for production code * **“Is Rust dying?”** - No! It has topped Stack Overflow’s “most loved/admired language” ranking every year since 2016 * **“Should I learn Rust in 2026?”** - Yes! Adoption is growing, especially in backend/systems *** ## Let’s Begin! [Section titled “Let’s Begin!”](#lets-begin) You’re about to learn one of the most capable programming languages in existence. It will be challenging, but rewarding. ### [Continue to Target Audience](/00-introduction/00-target-audience/) [Section titled “Continue to Target Audience”](#continue-to-target-audience) # Target Audience > This guide is designed specifically for TypeScript and JavaScript developers who want to learn Rust. Let's make sure this is the right resource for you! This guide is designed specifically for TypeScript and JavaScript developers who want to learn Rust. Let’s make sure this is the right resource for you! *** ## This Guide Is Perfect For You If… [Section titled “This Guide Is Perfect For You If…”](#this-guide-is-perfect-for-you-if) ### You’re a TypeScript/JavaScript Developer [Section titled “You’re a TypeScript/JavaScript Developer”](#youre-a-typescriptjavascript-developer) * You have **1+ years** of TypeScript or JavaScript experience * You understand **async/await, promises, and callbacks** * You’ve worked with **npm/yarn** and modern JavaScript tooling * You’re comfortable with **types, interfaces, and generics** (TypeScript) * You’ve built **real applications** (not just tutorials) ### You Want to Learn Rust [Section titled “You Want to Learn Rust”](#you-want-to-learn-rust) * You’re curious about **systems programming** * You want to build **high-performance backends** * You’re interested in **WebAssembly** * You need to create **fast CLI tools** * You want to understand **memory management** without garbage collection * You’re looking for a **“JavaScript alternative”** for certain use cases ### Your Learning Style [Section titled “Your Learning Style”](#your-learning-style) * You learn best by **comparing to what you know** * You appreciate **detailed explanations** * You want **production-ready examples**, not toy code * You’re willing to invest **time to learn properly** * You prefer **written documentation** over video tutorials *** ## This Guide Might Not Be Ideal If… [Section titled “This Guide Might Not Be Ideal If…”](#this-guide-might-not-be-ideal-if) ### Your Background [Section titled “Your Background”](#your-background) * You have **less than 1 year** of programming experience * **Better choice:** Start with [The Rust Book](https://doc.rust-lang.org/book/) which assumes no prior knowledge * You’re **not familiar with TypeScript** or modern JavaScript (ES6+) * **Better choice:** Learn TypeScript first, then come back * You primarily use **vanilla JavaScript** and avoid types * **Note:** You can still use this guide, but TypeScript knowledge helps ### Your Goals [Section titled “Your Goals”](#your-goals) * You only want to build **simple web frontends** * **Stick with:** TypeScript/JavaScript - they’re perfect for that * You need to **ship something quickly** (this week/month) * **Better choice:** Use Node.js for now, learn Rust later * You’re looking for an **“easy” language** * **Reality:** Rust is challenging, but worth it ### Time Commitment [Section titled “Time Commitment”](#time-commitment) * You can only spare **1-2 hours total** * **Reality:** Rust requires 20+ hours minimum to be useful * You want to be **productive immediately** * **Reality:** Expect 3-4 weeks before comfortable productivity *** ## Which Sections Matter Most for You? [Section titled “Which Sections Matter Most for You?”](#which-sections-matter-most-for-you) Different backgrounds, different priorities. Find yourself in this table: | You are… | Why Rust fits | Start with | | ------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------ | | **Backend developer** (Node/Express/NestJS) hitting performance limits or cloud costs | No GC pauses, lower memory, compile-time safety | 16 (Web APIs), 17 (Database), 28 (Production) | | **Full-stack developer** (React/Next.js) expanding your toolkit | WebAssembly, fast CLI tools, lower-level understanding | 19 (WASM), 18 (CLI Tools) | | **Platform engineer** whose Bash/Python tooling is getting complex | Single static binary, no runtime deps, robust error handling | 18 (CLI), 24 (Tooling), 26 (Systems) | | **Career switcher** eyeing systems/blockchain/gamedev roles | Growing demand, future-proof skill | The complete path, in order | | **Performance optimizer** fighting Lambda cold starts and p99 latency | Predictable performance, small binaries, low latency | 16 (Web APIs), 21 (Performance), 28 (Production) | *** ## Skill Level Guide [Section titled “Skill Level Guide”](#skill-level-guide) ### Beginner Level (This Guide Starts Here) [Section titled “Beginner Level (This Guide Starts Here)”](#beginner-level-this-guide-starts-here) **Your TypeScript/JavaScript Skills:** * Can write functions, classes, async code * Understand types, interfaces, generics * Built at least one real application * Comfortable with npm and modern tools **Your Rust Skills:** * None required! * Never written Rust before? Perfect! * Tried Rust but struggled? This will help! **After This Guide:** * Comfortable writing Rust code * Can build web APIs, CLI tools * Understand ownership and lifetimes * Ready for real Rust projects *** ### Advanced Scenarios [Section titled “Advanced Scenarios”](#advanced-scenarios) **You’re a Rust beginner but want to learn from TS/JS perspective:** * Perfect! This guide is designed for you **You know some Rust but from other languages (C++, Java):** * This guide works, but comparisons are TS/JS focused * Still useful for different perspectives **You’re a Rust expert looking to teach TS/JS developers:** * Great! This guide shows you how to explain Rust concepts *** ## Not Sure If This Is For You? [Section titled “Not Sure If This Is For You?”](#not-sure-if-this-is-for-you) ### Try This Quick Assessment [Section titled “Try This Quick Assessment”](#try-this-quick-assessment) **Answer these questions:** 1. Can you explain what `async/await` does in TypeScript? 2. Have you used generics (`Array`, `Promise`) in TypeScript? 3. Can you explain how `strictNullChecks` changes the way you handle `null`/`undefined`? 4. Have you built something with Express, Next.js, or similar? 5. Are you willing to spend 20+ hours learning Rust basics? **Scoring:** * **5 Yes:** Perfect! You’re exactly who this guide is for * **4 Yes:** Great! You’ll do fine, might need to review TS concepts * **3 Yes:** Okay, but consider strengthening TypeScript first * **<3 Yes:** Build a TypeScript project first, then come back *** ## Alternative Resources [Section titled “Alternative Resources”](#alternative-resources) If this guide isn’t quite right, try these: ### Complete Beginners to Programming [Section titled “Complete Beginners to Programming”](#complete-beginners-to-programming) * **[The Rust Book](https://doc.rust-lang.org/book/)** - No prior experience needed * **[Rustlings](https://github.com/rust-lang/rustlings)** - Learn by small exercises ### Coming from Other Languages [Section titled “Coming from Other Languages”](#coming-from-other-languages) * **[Rust for C++ Programmers](https://github.com/nrc/r4cppp)** - If you know C++ * **[Rust for Java Developers](https://github.com/Dhghomon/programming_rust_for_java_devs)** - If you know Java ### Prefer Video Content [Section titled “Prefer Video Content”](#prefer-video-content) * **[Let’s Get Rusty](https://www.youtube.com/c/LetsGetRusty)** - Video tutorials * **[Rust Programming Course](https://www.udemy.com/course/rust-lang/)** - Udemy course ### Just Want to Experiment [Section titled “Just Want to Experiment”](#just-want-to-experiment) * **[Rust Playground](https://play.rust-lang.org/)** - Try Rust in browser * **[Tour of Rust](https://tourofrust.com/)** - Interactive tutorial *** ## Still Here? Let’s Go! [Section titled “Still Here? Let’s Go!”](#still-here-lets-go) If you’ve made it this far, you’re probably in the right place! Here’s what to do next: 1. **You’ve confirmed this guide is for you** 2. **Next: [How to Read This Guide](/00-introduction/01-how-to-read/)** - Learn navigation strategies 3. **Then: [Prerequisites](/00-introduction/02-prerequisites/)** - Make sure you’re ready 4. **Finally: [Section 01](/01-getting-started/)** - Start learning! *** ## Still Have Questions? [Section titled “Still Have Questions?”](#still-have-questions) Common questions from TypeScript/JavaScript developers: **Q: “I only know vanilla JavaScript, not TypeScript. Can I still use this?”**\ A: Yes, but it’ll be harder. Many examples use TypeScript syntax. Consider learning TypeScript basics first. **Q: “I’m a React developer. Is Rust relevant to me?”**\ A: For React only? Not really. But for WebAssembly, CLI tools, or backend work? Absolutely! **Q: “Will this make me abandon JavaScript?”**\ A: No! You’ll use both. Rust for performance-critical backend/systems work, TypeScript for everything else. **Q: “Is Rust harder than TypeScript?”**\ A: Yes, significantly. But this guide makes it easier by relating to what you know. **Q: “How much TypeScript do I need to know?”**\ A: Basic types, interfaces, generics, async/await. If you’ve shipped a TypeScript app, you’re good. # How to Read This Guide > This guide contains 31 sections and hundreds of pages. Here's how to navigate it effectively and get the most out of your learning experience. This guide contains 31 sections and hundreds of pages. Here’s how to navigate it effectively and get the most out of your learning experience. *** ## Navigation Strategies [Section titled “Navigation Strategies”](#navigation-strategies) ### Strategy 1: Sequential (Recommended for Most) [Section titled “Strategy 1: Sequential (Recommended for Most)”](#strategy-1-sequential-recommended-for-most) **Best for:** Beginners, those with time to learn properly **Path:** Read sections 00-30 in order ```plaintext 1 00 → 01 → 02 → 03 → 04 → 05 → ... → 30 ``` **Pros:** * Build strong foundation * No missing context * Everything makes sense **Cons:** * Takes roughly 300-400 hours with the projects and exercises * Slower to “useful” code **Timeline:** About 30-40 weeks at 10 hours/week *** ### Strategy 2: Fast Track (Essentials Only) [Section titled “Strategy 2: Fast Track (Essentials Only)”](#strategy-2-fast-track-essentials-only) **Best for:** Experienced developers, those needing quick results **Path:** Core sections only ```plaintext 1 00 → 01 → 02 → 03 → 04 → 05 → 08 → 11 → 16 ``` Chapter 05 (Ownership) is mandatory on this route; the later chapters assume its model. **Focus on:** * 01: Getting Started * 02: Basics * 03: Functions * 04: Control Flow * **05: Ownership** (Don’t skip!) * 08: Error Handling * 11: Async * 16: Web APIs **Pros:** * Focused route through the essentials (roughly 70-85 hours with practice) * Learn by building **Cons:** * Missing depth * Will need to revisit topics **Timeline:** About 7-9 weeks at 10 hours/week The time ranges in this page are derived from the chapter-level reading, practice, and exercise estimates. Treat them as planning ranges rather than deadlines. *** ### Strategy 3: Project-First (Learn by Doing) [Section titled “Strategy 3: Project-First (Learn by Doing)”](#strategy-3-project-first-learn-by-doing) **Best for:** Hands-on learners, those who hate theory **Path:** Jump to projects, backtrack when stuck ```plaintext 1 00 → 01 → 30 (Pick a project) 2 ↓ 3 Get stuck → Read relevant section 4 ↓ 5 Continue project ``` **Flow:** 1. Read sections 00-01 (basics) 2. Jump to section 30 (projects) 3. Pick a project (REST API, CLI tool, etc.) 4. Try to build it 5. When you don’t understand something, read that section 6. Return to project **Pros:** * Immediately practical * High motivation * Learn what you need, when you need it **Cons:** * Can be frustrating * Might develop bad habits * More time overall (lots of backtracking) **Timeline:** 4-6 weeks at 10-15 hours/week *** ### Strategy 4: Domain-Specific [Section titled “Strategy 4: Domain-Specific”](#strategy-4-domain-specific) **Best for:** Those with specific goals (web dev, CLI, etc.) #### For Web API Developers [Section titled “For Web API Developers”](#for-web-api-developers) ```plaintext 1 00 → 01 → 02 → 05 → 06 → 08 → 11 → 12 → 15 → 16 → 17 → 27 → 28 2 ↑ ↑ └─→ Database 3 Basics Ownership Security & Production ``` #### For CLI Tool Developers [Section titled “For CLI Tool Developers”](#for-cli-tool-developers) ```plaintext 1 00 → 01 → 02 → 05 → 06 → 07 → 08 → 12 → 13 → 18 → 24 2 Basics Own. Data Collections CLI Testing Tooling ``` #### For Systems Programmers [Section titled “For Systems Programmers”](#for-systems-programmers) ```plaintext 1 00 → 01 → 02 → 05 → 10 → 20 → 21 → 26 2 Basics Own. Smart Unsafe Perf Systems 3 Ptr. ``` #### For WebAssembly Developers [Section titled “For WebAssembly Developers”](#for-webassembly-developers) ```plaintext 1 00 → 01 → 02 → 05 → 06 → 12 → 15 → 19 2 Basics Own. Data Mods Serde WASM ``` *** ## How Each Section Is Organized [Section titled “How Each Section Is Organized”](#how-each-section-is-organized) ### Section Structure [Section titled “Section Structure”](#section-structure) Every section follows this pattern: ```plaintext 1 XX-section-name/ 2 ├── index.md # Section overview, navigation 3 ├── 00-topic-1.md # Individual topics 4 ├── 01-topic-2.md 5 └── ... ``` ### Topic File Structure [Section titled “Topic File Structure”](#topic-file-structure) Each **concept topic** includes the parts below. (Orientation pages like this one, and the capstone projects in Section 30, use a tailored subset. For example, projects end with “Extending It” instead of graded exercises.) 1. **Quick Overview** - 2-3 sentence summary 2. **TypeScript/JavaScript Example** - Code you know 3. **Rust Equivalent** - The Rust way 4. **Detailed Explanation** - How and why 5. **Key Differences** - Important changes from TS/JS 6. **Common Pitfalls** - What TS/JS devs get wrong 7. **Best Practices** - Idiomatic Rust 8. **Real-World Example** - Production code 9. **Further Reading** - Additional resources 10. **Exercises** - Practice problems *** ## How to Approach Each Topic [Section titled “How to Approach Each Topic”](#how-to-approach-each-topic) ### Step 1: Read the Overview [Section titled “Step 1: Read the Overview”](#step-1-read-the-overview) Understand what you’re about to learn and why it matters. ### Step 2: Study the TypeScript Example [Section titled “Step 2: Study the TypeScript Example”](#step-2-study-the-typescript-example) This should be familiar. If it’s not, review TypeScript first. ### Step 3: Compare to Rust [Section titled “Step 3: Compare to Rust”](#step-3-compare-to-rust) Look for similarities and differences. Don’t just read the Rust code: compare it line by line to the TypeScript. ### Step 4: Read the Explanation [Section titled “Step 4: Read the Explanation”](#step-4-read-the-explanation) Understand not just “how” but “why” Rust does it this way. ### Step 5: Note the Pitfalls [Section titled “Step 5: Note the Pitfalls”](#step-5-note-the-pitfalls) These are real mistakes TS/JS developers make. Avoid them! ### Step 6: Try It Yourself [Section titled “Step 6: Try It Yourself”](#step-6-try-it-yourself) ```bash 1 # Create a playground 2 cargo new try_this 3 cd try_this 4 5 # Edit src/main.rs 6 # Try the examples yourself! 7 cargo run ``` ### Step 7: Do the Exercises [Section titled “Step 7: Do the Exercises”](#step-7-do-the-exercises) If provided, complete the exercises. They reinforce learning. *** ## Time Management [Section titled “Time Management”](#time-management) ### Daily Learning (30-60 minutes) [Section titled “Daily Learning (30-60 minutes)”](#daily-learning-30-60-minutes) **Best for:** Busy professionals ```plaintext 1 Day 1: Read one topic (30 min) 2 Day 2: Try examples, exercises (30 min) 3 Day 3: Read next topic (30 min) 4 Day 4: Review and practice (30 min) 5 Day 5: Build something small (1 hour) 6 Weekend: Longer project work ``` **Progress:** Complete guide in 2-3 months ### Weekend Warrior (5-10 hours/week) [Section titled “Weekend Warrior (5-10 hours/week)”](#weekend-warrior-5-10-hoursweek) **Best for:** Those with weekday commitments ```plaintext 1 Saturday: 3-4 hours learning 2 Sunday: 2-3 hours practicing 3 Weekdays: Quick reviews (15 min/day) ``` **Progress:** Complete guide in 1.5-2 months ### Intensive (20+ hours/week) [Section titled “Intensive (20+ hours/week)”](#intensive-20-hoursweek) **Best for:** Bootcamp style, career transition ```plaintext 1 Morning: 2-3 hours reading/learning 2 Afternoon: 2-3 hours practicing 3 Evening: 1-2 hours review/projects ``` **Progress:** Complete guide in 3-4 weeks *** ## Reading Tips [Section titled “Reading Tips”](#reading-tips) ### Active Reading [Section titled “Active Reading”](#active-reading) **Don’t just read - engage!** **Bad:** Skim through, think “that makes sense” **Good:** Type every example, modify it, break it, fix it **Bad:** Read code once, move on **Good:** Read it 3 times - once for syntax, once for meaning, once for patterns **Bad:** Skip exercises **Good:** Do all exercises, even if they seem easy ### Taking Notes [Section titled “Taking Notes”](#taking-notes) **Create a Rust learning journal:** ```markdown 1 # Day 1: Variables and Mutability 2 3 ## Key Insight 4 5 Rust is immutable by default! Opposite of JS. 6 7 ## Syntax I Need to Remember 8 9 let x = 5; // immutable 10 let mut y = 5; // mutable 11 12 ## Gotcha 13 14 Forgot `mut` and spent 10 minutes debugging why 15 assignment failed. Compiler error was helpful though! 16 17 ## Try Tomorrow 18 19 Practice with loops and mutable counters ``` ### When You’re Stuck [Section titled “When You’re Stuck”](#when-youre-stuck) **Follow this process:** 1. **Read the error message** - Rust errors are helpful! 2. **Check the relevant section** - Find the topic 3. **Try the Rust Playground** - Isolate the problem 4. **Ask for help** - Discord, Reddit, Stack Overflow 5. **Take a break** - Sometimes you just need to sleep on it *** ## Bookmark These [Section titled “Bookmark These”](#bookmark-these) Keep these sections handy for quick reference: ### Essential References [Section titled “Essential References”](#essential-references) * **[05 - Ownership](/05-ownership/)** - You’ll refer back constantly * **[07 - Collections](/07-collections/)** - String and Vec APIs * **[08 - Error Handling](/08-error-handling/)** - Result and Option * **[09 - Traits](/09-generics-traits/)** - Common trait patterns ### Quick Lookups [Section titled “Quick Lookups”](#quick-lookups) * **[02 - Basics](/02-basics/)** - Type conversion, operators * **[12 - Modules](/12-modules-packages/)** - Import syntax * **[24 - Tooling](/24-tooling/)** - Cargo commands *** ## Study Aids [Section titled “Study Aids”](#study-aids) ### Cheat Sheets (Create Your Own!) [Section titled “Cheat Sheets (Create Your Own!)”](#cheat-sheets-create-your-own) **TypeScript → Rust Quick Reference:** ```typescript 1 // TypeScript 2 const x = 5; 3 let y = [1, 2, 3]; 4 async function f() { ... } 5 interface User { name: string } ``` ```rust 1 // Rust 2 let x = 5; 3 let mut y = vec![1, 2, 3]; 4 async fn f() { ... } 5 struct User { name: String } ``` ### Flashcards [Section titled “Flashcards”](#flashcards) Use Anki, Quizlet, or paper cards for: * Syntax conversions * Ownership rules * Common patterns * Error types ### Practice Projects [Section titled “Practice Projects”](#practice-projects) After each major section, build something: * **After 05:** Simple CLI calculator * **After 08:** Error-handling file reader * **After 11:** Async HTTP client * **After 16:** Basic REST API * **After 30:** Your own project! *** ## Learning with Others [Section titled “Learning with Others”](#learning-with-others) ### Study Groups [Section titled “Study Groups”](#study-groups) Find or create a study group: * Discord channels * Local meetups * Online cohorts * Pair programming **Benefits:** * Stay motivated * Learn from others’ questions * Teach to reinforce learning * Make friends in Rust community ### Code Review [Section titled “Code Review”](#code-review) Share your code: * Reddit r/rust (helpful community!) * Discord #beginners channel * GitHub discussions * Stack Overflow *** ## Track Your Progress [Section titled “Track Your Progress”](#track-your-progress) ### Section Checklist [Section titled “Section Checklist”](#section-checklist) Keep track of what you’ve completed: ```plaintext 1 [ ] 00 - Introduction 2 [ ] 01 - Getting Started 3 [ ] 02 - Basics 4 ... 5 [ ] 30 - Projects ``` ### Skill Assessment [Section titled “Skill Assessment”](#skill-assessment) Periodically check yourself: **Week 1:** * Can I create a new Cargo project? * Do I understand mutable vs immutable? * Have I written a basic function? **Week 2:** * Do I understand ownership? * Can I use borrowing correctly? * Have I successfully used Vec and String? **Week 4:** * Can I handle errors with Result? * Do I understand traits? * Have I written async code? **Week 8:** * Can I build a REST API? * Do I understand lifetimes? * Have I shipped a Rust project? *** ## Goal Setting [Section titled “Goal Setting”](#goal-setting) ### Set Clear Milestones [Section titled “Set Clear Milestones”](#set-clear-milestones) **Bad goal:** “Learn Rust”\ **Good goal:** “Build a REST API that handles user authentication by end of month” **Bad goal:** “Understand ownership”\ **Good goal:** “Complete section 05 and build a CLI tool that manipulates strings without compiler errors” ### Celebrate Wins [Section titled “Celebrate Wins”](#celebrate-wins) Learning Rust is hard! Celebrate progress: * First successful compile * First program without compiler errors * Understanding ownership * First async program * First production code * Helping another beginner *** ## What NOT to Do [Section titled “What NOT to Do”](#what-not-to-do) ### Common Mistakes [Section titled “Common Mistakes”](#common-mistakes) **Skipping Section 05 (Ownership)** → You’ll be confused forever. Don’t skip it! **Rushing through examples** → Type them out, don’t just read **Comparing to JavaScript too much** → Rust is different. Embrace it! **Fighting the compiler** → It’s helping you. Listen to it! **Learning in isolation** → Join the community, ask questions **Giving up after Day 3** → Week 1 is the hardest. Push through! **Trying to memorize everything** → Focus on understanding, reference docs for details *** ## After Completing This Guide [Section titled “After Completing This Guide”](#after-completing-this-guide) ### What’s Next? [Section titled “What’s Next?”](#whats-next) 1. **Build a real project** - Not a tutorial, something you’ll use 2. **Contribute to open source** - Find a Rust project 3. **Read advanced resources** - [Rust for Rustaceans](https://rust-for-rustaceans.com/) 4. **Keep practicing** - Skills decay without use 5. **Teach others** - Best way to solidify knowledge ### Staying Current [Section titled “Staying Current”](#staying-current) Rust evolves. Stay updated: * [This Week in Rust](https://this-week-in-rust.org/) * [Rust Blog](https://blog.rust-lang.org/) * [Reddit r/rust](https://reddit.com/r/rust) * [Rust Discord](https://discord.gg/rust-lang) *** ## Getting Help [Section titled “Getting Help”](#getting-help) ### When You’re Stuck [Section titled “When You’re Stuck”](#when-youre-stuck-1) **Good question template:** ```plaintext 1 I'm trying to [specific goal]. 2 3 I expected [what you thought would happen]. 4 5 Instead, [what actually happened]. 6 7 Here's my code: [minimal example] 8 9 Error message: [full error] 10 11 I've tried: [what you've attempted] ``` ### Where to Ask [Section titled “Where to Ask”](#where-to-ask) * **Beginners:** [Discord #beginners](https://discord.gg/rust-lang) * **Code review:** [r/rust](https://reddit.com/r/rust) * **Specific errors:** Stack Overflow * **General discussion:** [Rust Users Forum](https://users.rust-lang.org/) *** ## You’re Ready! [Section titled “You’re Ready!”](#youre-ready) You now know how to navigate this guide effectively. Choose your strategy and let’s begin! ### Your Next Steps [Section titled “Your Next Steps”](#your-next-steps) 1. **You know how to use this guide** 2. **Next: [Prerequisites](/00-introduction/02-prerequisites/)** - Verify you’re ready 3. **Then: [Section 01](/01-getting-started/)** - Start coding! # Prerequisites > Before you start Rust, let's make sure you have the necessary background knowledge and tools. This will set you up for a smooth learning experience. Before you start Rust, let’s make sure you have the necessary background knowledge and tools. This will set you up for a smooth learning experience. *** ## Required Knowledge [Section titled “Required Knowledge”](#required-knowledge) ### 1. TypeScript/JavaScript Experience (Required) [Section titled “1. TypeScript/JavaScript Experience (Required)”](#1-typescriptjavascript-experience-required) You should be comfortable with: #### Basic Programming [Section titled “Basic Programming”](#basic-programming) ```typescript 1 // Variables and types 2 let name: string = "Alice"; 3 const age: number = 30; 4 let isActive: boolean = true; 5 6 // Functions 7 function greet(name: string): string { 8 return `Hello, ${name}!`; 9 } 10 11 // Arrow functions 12 const add = (a: number, b: number): number => a + b; ``` **Why it matters:** These map directly to Rust concepts. If this looks unfamiliar, review JavaScript/TypeScript basics first. #### Arrays and Objects [Section titled “Arrays and Objects”](#arrays-and-objects) ```typescript 1 // Arrays 2 const numbers: number[] = [1, 2, 3, 4, 5]; 3 const doubled = numbers.map((n) => n * 2); 4 const filtered = numbers.filter((n) => n > 2); 5 6 // Objects and interfaces 7 interface User { 8 id: number; 9 name: string; 10 email: string; 11 } 12 13 const user: User = { 14 id: 1, 15 name: "Alice", 16 email: "alice@example.com", 17 }; ``` **Why it matters:** Collections work similarly in Rust (Vec, HashMap, etc.) #### Async/Await [Section titled “Async/Await”](#asyncawait) ```typescript 1 // Promises and async/await 2 async function fetchUser(id: number): Promise { 3 const response = await fetch(`/api/users/${id}`); 4 const data = await response.json(); 5 return data; 6 } 7 8 // Error handling 9 try { 10 const user = await fetchUser(1); 11 console.log(user); 12 } catch (error) { 13 console.error("Failed:", error); 14 } ``` **Why it matters:** Rust has async/await too, with similar (but not identical) syntax. #### Generics [Section titled “Generics”](#generics) ```typescript 1 // Generic functions 2 function first(arr: T[]): T | undefined { 3 return arr[0]; 4 } 5 6 // Generic interfaces 7 interface Response { 8 data: T; 9 status: number; 10 } 11 12 const userResponse: Response = { 13 data: user, 14 status: 200, 15 }; ``` **Why it matters:** Rust’s generics are similar but can do more. #### Modules and Imports [Section titled “Modules and Imports”](#modules-and-imports) ```typescript 1 // Importing 2 import { User, fetchUser } from "./api"; 3 import type { Config } from "./config"; 4 5 // Exporting 6 export interface Product { 7 id: number; 8 name: string; 9 } 10 11 export function getProducts(): Product[] { 12 // ... 13 } ``` **Why it matters:** Rust’s module system is similar conceptually. *** ### 2. Command Line Basics (Required) [Section titled “2. Command Line Basics (Required)”](#2-command-line-basics-required) You should know how to: ```bash 1 # Navigate directories 2 cd ~/projects 3 ls 4 pwd 5 6 # Create files and directories 7 mkdir my-project 8 touch file.txt 9 10 # Run commands 11 node app.js 12 npm install 13 npm start 14 15 # View file contents 16 cat README.md 17 18 # Basic git 19 git clone 20 git add . 21 git commit -m "message" ``` **Why it matters:** You’ll use terminal commands for Cargo and rustc. *** ### 3. Development Tools (Required) [Section titled “3. Development Tools (Required)”](#3-development-tools-required) #### Text Editor/IDE [Section titled “Text Editor/IDE”](#text-editoride) You need a text editor. Recommended options: **VS Code** (Most popular) ```bash 1 # Install VS Code 2 # Then install rust-analyzer extension 3 code --install-extension rust-lang.rust-analyzer ``` **Other options:** * **IntelliJ IDEA** with Rust plugin * **Vim/Neovim** with rust.vim * **Emacs** with rust-mode * **Sublime Text** with Rust Enhanced **Why it matters:** You’ll write lots of Rust code! #### Terminal/Shell [Section titled “Terminal/Shell”](#terminalshell) * macOS/Linux: Built-in terminal * Windows: PowerShell, WSL2, or Git Bash *** ## Helpful but Not Required [Section titled “Helpful but Not Required”](#helpful-but-not-required) ### Nice to Have [Section titled “Nice to Have”](#nice-to-have) #### System Programming Concepts [Section titled “System Programming Concepts”](#system-programming-concepts) If you’ve heard of these, great! If not, don’t worry, we’ll explain: * **Stack vs Heap** - We’ll teach you * **Pointers** - Rust handles them safely * **Memory management** - Rust’s ownership system makes it easier * **Compilation** - You’ll learn as you go #### Other Compiled Languages [Section titled “Other Compiled Languages”](#other-compiled-languages) Experience with these helps but isn’t necessary: * C, C++, Go, Java, C#, Swift, Kotlin **If you have:** Great! Some concepts will feel familiar\ **If you don’t:** Perfect! You’ll learn Rust’s way without bad habits *** ## What You DON’T Need [Section titled “What You DON’T Need”](#what-you-dont-need) ### You Don’t Need to Know [Section titled “You Don’t Need to Know”](#you-dont-need-to-know) **Computer Science degree** - Nope! **Low-level programming** - We’ll teach you **C or C++** - Actually better if you don’t (fewer preconceptions) **Assembly** - Not at all **Operating systems** - Helpful but not required **Math** - Just basic programming logic ### You Don’t Need to Be [Section titled “You Don’t Need to Be”](#you-dont-need-to-be) **A “10x developer”** - Everyone starts somewhere **A CS major** - Self-taught? Perfect! **Young** - Age doesn’t matter **A native English speaker** - Code is universal *** ## System Requirements [Section titled “System Requirements”](#system-requirements) ### Operating System [Section titled “Operating System”](#operating-system) Rust works on: * **Linux** (any distro) * **macOS** (10.7+) * **Windows** (7+, but 10+ recommended) * **BSD, etc.** **Note for Windows users:** Consider using [WSL2](https://docs.microsoft.com/en-us/windows/wsl/install) for a better experience. Or use PowerShell/CMD - both work fine. ### Hardware [Section titled “Hardware”](#hardware) **Minimum:** * 2 GB RAM (4 GB recommended) * 2 GB disk space * Any processor from the last 10 years **Why it matters:** Rust compilation can be slow on old hardware. ### Internet Connection [Section titled “Internet Connection”](#internet-connection) Required for: * Installing Rust * Downloading dependencies (crates) * Accessing documentation **Tip:** Once you’ve downloaded crates, you can work offline. *** ## Required Software [Section titled “Required Software”](#required-software) ### 1. Node.js (for TypeScript examples) [Section titled “1. Node.js (for TypeScript examples)”](#1-nodejs-for-typescript-examples) ```bash 1 # Check if installed 2 node --version # Should be 22+ (any maintained LTS works) 3 npm --version # Comes bundled with Node 4 5 # If not installed: https://nodejs.org/ ``` **Why:** We’ll compare TypeScript and Rust code side-by-side. ### 2. TypeScript (optional but recommended) [Section titled “2. TypeScript (optional but recommended)”](#2-typescript-optional-but-recommended) ```bash 1 # Install globally 2 npm install -g typescript 3 4 # Verify 5 tsc --version ``` **Why:** To run the TypeScript examples in this guide. ### 3. Git (recommended) [Section titled “3. Git (recommended)”](#3-git-recommended) ```bash 1 # Check if installed 2 git --version 3 4 # If not installed: https://git-scm.com/ ``` **Why:** For cloning examples and managing your code. *** ## Pre-Learning Checklist [Section titled “Pre-Learning Checklist”](#pre-learning-checklist) Before starting Section 01, verify: ### Knowledge Checklist [Section titled “Knowledge Checklist”](#knowledge-checklist) * [ ] I can write TypeScript functions with type annotations * [ ] I understand async/await and Promises * [ ] I’ve used generics (`Array`, `Promise`) * [ ] I know basic terminal commands (cd, ls, mkdir) * [ ] I’ve built at least one TypeScript/JavaScript application ### Tools Checklist [Section titled “Tools Checklist”](#tools-checklist) * [ ] I have a text editor/IDE installed * [ ] I can open and use a terminal * [ ] I have Node.js installed (node —version works) * [ ] I have Git installed (optional but recommended) * [ ] I have at least 2 GB free disk space ### Mindset Checklist [Section titled “Mindset Checklist”](#mindset-checklist) * [ ] I’m ready to invest 20+ hours learning * [ ] I’m okay with compiler errors (they’re helpful!) * [ ] I’m willing to think differently about programming *** ## Quick Self-Assessment [Section titled “Quick Self-Assessment”](#quick-self-assessment) ### Test Your TypeScript Knowledge [Section titled “Test Your TypeScript Knowledge”](#test-your-typescript-knowledge) Try to answer these without looking them up: **Question 1:** ```typescript 1 const numbers = [1, 2, 3, 4, 5]; 2 const result = numbers.map((n) => n * 2).filter((n) => n > 5); ``` What is `result`? Answer `[6, 8, 10]` - Numbers doubled, then filtered to only values > 5 **Question 2:** ```typescript 1 interface User { 2 name: string; 3 age?: number; 4 } ``` What does the `?` mean? Answer Optional property - `age` may or may not be present **Question 3:** ```typescript 1 async function fetchData(): Promise { 2 const response = await fetch("/api/data"); 3 return response.text(); 4 } ``` What does this function return? Answer A `Promise` - The function is async, so it always returns a Promise **Scoring:** * **3/3:** Perfect! You’re ready * **2/3:** Good, review weak areas * **1/3 or less:** Review TypeScript basics first *** ## Recommended Pre-Reading (Optional) [Section titled “Recommended Pre-Reading (Optional)”](#recommended-pre-reading-optional) If you want to prepare even more: ### For TypeScript Review [Section titled “For TypeScript Review”](#for-typescript-review) * [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html) * [TypeScript Deep Dive](https://basarat.gitbook.io/typescript/) ### For Programming Concepts [Section titled “For Programming Concepts”](#for-programming-concepts) * [JavaScript.info](https://javascript.info/) - Modern JavaScript * [MDN Web Docs](https://developer.mozilla.org/) - Web APIs ### For Command Line [Section titled “For Command Line”](#for-command-line) * [Command Line Crash Course](https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Command_line) *** ## Ready to Install Rust? [Section titled “Ready to Install Rust?”](#ready-to-install-rust) If you’ve checked all the boxes above, you’re ready! ### What’s Next? [Section titled “What’s Next?”](#whats-next) 1. **You’ve verified prerequisites** 2. **Next: [Section 01 - Getting Started](/01-getting-started/)** 3. **Install Rust and write your first program!** *** ## Still Not Sure? [Section titled “Still Not Sure?”](#still-not-sure) ### Common Concerns [Section titled “Common Concerns”](#common-concerns) **“I’ve only used JavaScript, not TypeScript.”** → That’s okay! You’ll learn TypeScript concepts as we compare to Rust. Just note that examples use TypeScript syntax. **“I’ve never compiled a program before.”** → Perfect! We’ll walk you through it. Compilation is just turning code into an executable. **“The terminal scares me.”** → Don’t worry! We’ll explain every command. You’ll be comfortable with it soon. **“I don’t have much time.”** → Start with 30 minutes a day. Progress is progress! **“What if I get stuck?”** → Join the [Rust Discord](https://discord.gg/rust-lang) - the community is super helpful! **“Am I too old/young/etc. to learn Rust?”** → Absolutely not! If you can write TypeScript, you can learn Rust. *** ## You’re All Set! [Section titled “You’re All Set!”](#youre-all-set) You have the knowledge and tools needed. Time to write some Rust! # JavaScript & TypeScript to Rust Cheatsheet > The fast map from JavaScript and TypeScript to Rust: variables, array methods, null handling, promises, classes, and modules, each linked to a full chapter. A single-page lookup for the question you will ask most often while learning Rust: *“what is the Rust equivalent of this JavaScript or TypeScript thing?”* Each row pairs the code you already write on the left with its idiomatic Rust counterpart on the right. The mappings are deliberately terse; every section links to the full chapter where the *why* lives. If you only skim one page before starting, make it this one, then keep it open in a tab. *** ## Variables and types [Section titled “Variables and types”](#variables-and-types) | TypeScript / JavaScript | Rust | | ------------------------------------- | ---------------------------------------------------------------------------------------- | | `let x = 1` (reassignable) | `let mut x = 1;` | | `const x = 1` (no reassign) | `let x = 1;` (immutable by default) | | `const MAX = 100` (true constant) | `const MAX: i32 = 100;` | | reassign with a new type | shadowing: `let x = 5; let x = "five";` | | `number` | sized: `i32`, `i64`, `u32`, `usize`, `f64` | | `bigint` (arbitrary precision) | `i128` / `u128` (fixed 128-bit; for true arbitrary precision use the `num-bigint` crate) | | `string` | `String` (owned) and `&str` (borrowed) | | `boolean` | `bool` | | `null` / `undefined` | `Option` with `None` | | `any` | no equivalent; reach for generics, an `enum`, or `serde_json::Value` | | `[1, 2, 3]` | `vec![1, 2, 3]` (a growable `Vec`) | | fixed-length tuple `[string, number]` | `(String, i32)` | | `{ id: 1 }` object | a `struct`, or a `HashMap` for dynamic keys | See: [Variables and Mutability](/02-basics/00-variables/), [Basic Types](/02-basics/01-types/), [Stack vs Heap](/05-ownership/00-stack-heap/). *** ## Functions and closures [Section titled “Functions and closures”](#functions-and-closures) | TypeScript / JavaScript | Rust | | -------------------------------------------- | -------------------------------------------------- | | `function add(a: number, b: number): number` | `fn add(a: i32, b: i32) -> i32` | | `return a + b;` | `a + b` (last expression, no `return`, no `;`) | | `(x) => x + 1` | `\|x\| x + 1` | | capturing closure `() => count++` | `move \|\| count += 1` (see `Fn`/`FnMut`/`FnOnce`) | | default parameter `f(a = 1)` | no defaults; take `Option` or use a builder | | rest parameter `...args` | a slice `args: &[T]` | | `void` return | `()` (the unit type) | | pass a function `g(f)` | `fn g(f: impl Fn() -> T)` | See: [Basic Functions](/03-functions/00-basic-functions/), [Parameters](/03-functions/01-parameters/), [Arrow Functions vs Closures](/03-functions/03-arrow-vs-closures/), [Higher-Order Functions](/03-functions/04-higher-order/). *** ## Control flow [Section titled “Control flow”](#control-flow) | TypeScript / JavaScript | Rust | | ----------------------------- | ----------------------------------------------- | | `cond ? a : b` | `if cond { a } else { b }` (an expression) | | `if (value)` (truthy) | `if value` (must be a real `bool`) | | `switch (x) { ... }` | `match x { ... }` (exhaustive, no fall-through) | | `for (let i = 0; i < n; i++)` | `for i in 0..n` | | `for (const x of arr)` | `for x in &arr` | | `arr.forEach(f)` | `arr.iter().for_each(f)` or a `for` loop | | `while (cond)` | `while cond` | | `while (true) { ... }` | `loop { ... }` (can `break value`) | | labelled `break outer` | `'outer: loop { break 'outer; }` | See: [Conditionals](/04-control-flow/00-conditionals/), [Match](/04-control-flow/02-match/), [Loops](/04-control-flow/01-loops/), [if let / while let](/04-control-flow/03-if-let-while-let/). *** ## Null, undefined, and errors [Section titled “Null, undefined, and errors”](#null-undefined-and-errors) There is no `null` and no `undefined` in Rust. Absence is the `None` variant of `Option`, and a failure is the `Err` variant of `Result`. The type system makes you handle both. | TypeScript / JavaScript | Rust | | --------------------------------- | ---------------------------------------------- | | `value ?? fallback` | `option.unwrap_or(fallback)` | | `obj?.prop` (optional chaining) | `option.map(\|o\| o.prop)` / `.and_then(...)` | | `if (x != null) { use(x) }` | `if let Some(x) = option { use(x) }` | | `throw new Error("boom")` | `return Err(MyError::Boom)` | | `try { ... } catch (e) { ... }` | `match result { Ok(v) => ..., Err(e) => ... }` | | `const v = await f()` (may throw) | `let v = f().await?;` | | rethrow / propagate | the `?` operator | | `class HttpError extends Error` | `enum AppError { ... }` with `thiserror` | See: [Result and Option](/08-error-handling/00-result-option/), [The `?` Operator](/08-error-handling/01-question-mark/), [Option Enum](/06-data-structures/03-option-enum/), [Custom Errors](/08-error-handling/04-custom-errors/). *** ## Collections and array methods [Section titled “Collections and array methods”](#collections-and-array-methods) Most array methods exist in Rust, but on **iterators**, and they are **lazy**: nothing runs until a consumer such as `.collect()`, `.sum()`, or a `for` loop pulls the values through. | TypeScript / JavaScript | Rust | | ------------------------------------- | --------------------------------------------------- | | `arr.map(f)` | `arr.iter().map(f).collect()` | | `arr.filter(f)` | `arr.iter().filter(f).collect()` | | `arr.reduce(f, init)` | `arr.iter().fold(init, f)` | | `arr.find(f)` | `arr.iter().find(f)` (returns `Option`) | | `arr.some(f)` / `arr.every(f)` | `arr.iter().any(f)` / `.all(f)` | | `arr.includes(x)` | `arr.contains(&x)` | | `arr.push(x)` / `arr.length` | `vec.push(x)` / `vec.len()` | | `arr.slice(a, b)` | `&vec[a..b]` | | `arr.sort()` | `vec.sort()` | | `[...a, ...b]` | `a.iter().chain(&b).collect()` | | `new Map()` / `map.get(k)` | `HashMap::new()` / `map.get(&k)` (returns `Option`) | | `new Set()` | `HashSet::new()` | | `Object.keys(o)` / `Object.values(o)` | `map.keys()` / `map.values()` | | `Array.from({ length: n }, ...)` | `(0..n).map(...).collect()` | See: [Vectors](/07-collections/00-vectors/), [Iterators](/07-collections/06-iterators/), [Iterator Consumers](/07-collections/07-iterator-consumers/), [HashMaps](/07-collections/03-hashmaps/). *** ## Strings [Section titled “Strings”](#strings) | TypeScript / JavaScript | Rust | | ---------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `"hello " + name` | `format!("hello {name}")` | | `` `total: ${n}` `` (template) | `format!("total: {n}")` | | `s.length` (UTF-16 code units — `"🎉".length === 2`) | `s.chars().count()` (Unicode scalars) or `s.len()` (UTF-8 bytes); neither matches JS exactly | | `s.toUpperCase()` | `s.to_uppercase()` | | `s.split(",")` | `s.split(',')` | | `s.includes("x")` | `s.contains("x")` | | `s.trim()` | `s.trim()` | | `s.replace(a, b)` | `s.replace(a, b)` | | `s.startsWith("/")` | `s.starts_with('/')` | | accept a string argument | take `&str`, return `String` | See: [Strings](/07-collections/01-strings/), [String Manipulation](/07-collections/02-string-manipulation/). *** ## Structs, enums, classes, and interfaces [Section titled “Structs, enums, classes, and interfaces”](#structs-enums-classes-and-interfaces) Rust has no classes and no inheritance. Data lives in a `struct` or `enum`; behaviour lives in `impl` blocks; shared behaviour is a `trait` (an interface you can implement for any type). | TypeScript / JavaScript | Rust | | ------------------------------- | -------------------------------------------- | | `interface User { id: number }` | `struct User { id: i32 }` | | `class C { method() {} }` | `struct C; impl C { fn method(&self) {} }` | | `type Shape = Circle \| Square` | `enum Shape { Circle, Square }` | | discriminated union with data | `enum` variants carry data | | `implements Serializable` | `impl Serializable for T` | | `extends Base` (inheritance) | composition plus traits (no inheritance) | | `this` | `&self`, `&mut self`, or `self` | | `new C(args)` | `C::new(args)` (a convention, not a keyword) | | `instanceof` | `match` on an `enum` or a trait object | | generic `class Box` | `struct Box` with trait bounds | See: [Structs](/06-data-structures/00-structs/), [Enums](/06-data-structures/02-enums/), [impl Blocks](/06-data-structures/05-impl-blocks/), [Traits](/09-generics-traits/03-traits/), [Trait Objects](/09-generics-traits/06-trait-objects/). *** ## Async [Section titled “Async”](#async) The keywords match, but Rust futures are **lazy** (they do nothing until `.await`ed) and there is no built-in event loop, so you pick a runtime such as Tokio. | TypeScript / JavaScript | Rust | | ------------------------------- | ----------------------------------------------------- | | `Promise` | `impl Future` | | `async function f()` | `async fn f()` | | `await p` | `p.await` | | `Promise.all([a, b])` | `tokio::join!(a, b)` / `futures::future::join_all` | | `Promise.race([a, b])` | `tokio::select!` | | built-in event loop | a runtime via `#[tokio::main]` | | `setTimeout(fn, ms)` | `tokio::time::sleep(Duration::from_millis(ms)).await` | | `for await (const x of stream)` | `while let Some(x) = stream.next().await` | See: [Promises vs Futures](/11-async/00-promises-vs-futures/), [async/await](/11-async/01-async-await/), [select and join](/11-async/07-select-join/), [Async vs Sync](/11-async/13-async-vs-sync/). *** ## Modules, packages, and tooling [Section titled “Modules, packages, and tooling”](#modules-packages-and-tooling) | TypeScript / JavaScript | Rust | | ------------------------- | ---------------------------------------- | | `import { x } from "./m"` | `use crate::m::x;` | | `export function f()` | `pub fn f()` | | `export default` | no default export; name the item | | a file is a module | declare modules with `mod` | | `package.json` | `Cargo.toml` | | `npm install serde` | `cargo add serde` | | `npm run build` | `cargo build --release` | | `node index.js` | `cargo run` | | `npm test` | `cargo test` | | `tsc` (type-check) | `cargo check` | | ESLint / Prettier | `cargo clippy` / `cargo fmt` | | `node_modules/` | `~/.cargo/` plus the `target/` build dir | See: [The Module Tree](/12-modules-packages/01-module-tree/), [The `use` Keyword](/12-modules-packages/02-use-keyword/), [Visibility](/12-modules-packages/03-pub-visibility/), [Cargo](/12-modules-packages/04-cargo/). *** ## Everyday idioms [Section titled “Everyday idioms”](#everyday-idioms) | TypeScript / JavaScript | Rust | | ------------------------------ | ------------------------------------------------------------- | | `console.log(x)` | `println!("{x}")` or `println!("{x:?}")` for any `Debug` type | | `console.error(x)` | `eprintln!("{x}")` | | quick debug print | `dbg!(x)` | | `JSON.stringify(v)` | `serde_json::to_string(&v)?` | | `JSON.parse(s)` | `serde_json::from_str(&s)?` | | `Number("42")` | `"42".parse::()?` | | `x as Y` (numeric) | `x as Y` | | `typeof x` (runtime) | not needed; types are checked at compile time | | object spread `{ ...a, b: 1 }` | struct update `User { b: 1, ..a }` | | immutability by convention | immutable by default; opt in with `mut` | See: [Output](/02-basics/04-output/), [JSON with Serde](/15-serialization/03-json/), [Serde Basics](/15-serialization/01-serde-basics/). *** ## Where to go next [Section titled “Where to go next”](#where-to-go-next) This page is the map; the territory is the rest of the guide. The one idea with no JavaScript analogue, and the one worth learning first, is **ownership**: who is responsible for each value and when it is freed. Start there. * [Why Rust?](/01-getting-started/00-why-rust/) for the motivation. * [Ownership](/05-ownership/) for the concept that makes everything else click. * [Error Handling](/08-error-handling/) to replace `try/catch` with values. * [The Migration Guide](/29-migration-guide/) when you are ready to port real code. # Rust for JavaScript & TypeScript Developers: FAQ > Straight answers to what JS and TS developers actually ask about Rust: ownership, async, null, classes, performance, npm, WebAssembly, and whether to learn it. The questions a JavaScript or TypeScript developer actually types into a search box or asks an AI, answered in a sentence or two each, with a link to the chapter that goes deeper. If you are deciding whether Rust is worth your time, start at the top; if you are mid-learning and stuck on one idea, jump to its section. *** ## Is Rust hard to learn coming from JavaScript or TypeScript? [Section titled “Is Rust hard to learn coming from JavaScript or TypeScript?”](#is-rust-hard-to-learn-coming-from-javascript-or-typescript) The syntax is familiar within a day; the mental model takes longer. The one genuinely new idea is **ownership**, the rule for who is responsible for each value and when it is freed. Most of the early friction is the borrow checker teaching you that rule. Everything else (functions, generics, async, modules) maps closely to what you know. See [Why Rust?](/01-getting-started/00-why-rust/) and [Ownership](/05-ownership/). ## How long does it take to learn Rust? [Section titled “How long does it take to learn Rust?”](#how-long-does-it-take-to-learn-rust) Plan on a few weeks to feel productive and a few months to feel fluent. You can write useful programs in the first week; ownership, lifetimes, and async are where the real time goes. Coming from TypeScript helps, because you already think in types, generics, and `async`/`await`. ## Do I still need JavaScript or TypeScript if I learn Rust? [Section titled “Do I still need JavaScript or TypeScript if I learn Rust?”](#do-i-still-need-javascript-or-typescript-if-i-learn-rust) Yes. Rust is a complement, not a replacement. You will still ship UI in TypeScript and reach for Rust where it pays off: CPU-heavy work, WebAssembly modules, CLIs, services, and native Node addons. The two languages increasingly live in the same codebase. See the [Migration Guide](/29-migration-guide/) and [WebAssembly](/19-wasm/). ## Should a JavaScript developer learn Rust in 2026? [Section titled “Should a JavaScript developer learn Rust in 2026?”](#should-a-javascript-developer-learn-rust-in-2026) If you want to understand memory, performance, and systems, or to write the fast path your JavaScript app calls into, yes. Rust powers parts of Figma, Discord, Cloudflare, and the tooling under many JS frameworks. It is a senior-leaning skill with a real payoff, not a quick win. *** ## How does ownership work coming from JavaScript? [Section titled “How does ownership work coming from JavaScript?”](#how-does-ownership-work-coming-from-javascript) In JavaScript the garbage collector frees memory whenever it likes, and you share references freely. In Rust, every value has exactly **one owner**; assigning it or passing it to a function **moves** ownership, and the value is freed when its owner goes out of scope. No garbage collector, decided at compile time. See [The Three Ownership Rules](/05-ownership/01-ownership-rules/). ## What is the borrow checker, and why does it keep rejecting my code? [Section titled “What is the borrow checker, and why does it keep rejecting my code?”](#what-is-the-borrow-checker-and-why-does-it-keep-rejecting-my-code) It is the compile-time analysis that enforces ownership. The core rule: you can have **many shared `&` references or one mutable `&mut` reference, never both at once**. It rejects exactly the aliasing and use-after-free bugs JavaScript ships to production. The fight early on is normal and fades fast. See [Borrowing](/05-ownership/02-borrowing/) and [Mutable References](/05-ownership/03-mutable-references/). ## Why does Rust not have a garbage collector? [Section titled “Why does Rust not have a garbage collector?”](#why-does-rust-not-have-a-garbage-collector) Because ownership lets the compiler insert the cleanup for you at exactly the right moment, with no runtime that pauses your program to scan for garbage. You get predictable memory use and no GC pauses, at the cost of learning the ownership rules up front. See [Stack vs Heap](/05-ownership/00-stack-heap/) and [The Drop Trait](/05-ownership/08-drop-trait/). ## Why is my Rust code full of `.clone()` and `&`? [Section titled “Why is my Rust code full of .clone() and &?”](#why-is-my-rust-code-full-of-clone-and-) Usually a sign you are fighting ownership instead of borrowing. Reach for `&` to lend a value without giving it away, and treat `.clone()` as a deliberate “make a real copy here,” not a reflex to silence the compiler. The habit clicks after the first few programs. See [Move, Copy, and Clone](/05-ownership/06-move-copy-clone/). *** ## What replaces `null` and `undefined` in Rust? [Section titled “What replaces null and undefined in Rust?”](#what-replaces-null-and-undefined-in-rust) `Option`. A value that might be absent has type `Option` and is either `Some(value)` or `None`, and the compiler forces you to handle the `None` case. The billion-dollar mistake becomes a compile error instead of a runtime `TypeError`. See [Option Enum](/06-data-structures/03-option-enum/) and [Result and Option](/08-error-handling/00-result-option/). ## What is the Rust equivalent of `try`/`catch`? [Section titled “What is the Rust equivalent of try/catch?”](#what-is-the-rust-equivalent-of-trycatch) There are no exceptions. A function that can fail returns `Result`, either `Ok(value)` or `Err(error)`. The `?` operator propagates an error up the call stack in one character, replacing `try`/`catch` with values the type system makes you handle. See [The `?` Operator](/08-error-handling/01-question-mark/) and [Custom Errors](/08-error-handling/04-custom-errors/). ## What is the Rust equivalent of a Promise and `async`/`await`? [Section titled “What is the Rust equivalent of a Promise and async/await?”](#what-is-the-rust-equivalent-of-a-promise-and-asyncawait) The syntax matches: `async fn` and `.await`. The difference is that a Rust **future is lazy** (it does nothing until you `.await` it) and there is no built-in event loop, so you add a runtime like Tokio. `Promise.all` becomes `tokio::join!`. See [Promises vs Futures](/11-async/00-promises-vs-futures/) and [async/await](/11-async/01-async-await/). *** ## What is the Rust equivalent of array `map`, `filter`, and `reduce`? [Section titled “What is the Rust equivalent of array map, filter, and reduce?”](#what-is-the-rust-equivalent-of-array-map-filter-and-reduce) The same names, but on **iterators**, and lazy: `arr.iter().map(...).filter(...).collect()`. `reduce` is `fold`. Nothing runs until a consumer like `.collect()`, `.sum()`, or a `for` loop drives the chain, so chaining adaptors allocates nothing in between. See [Iterators](/07-collections/06-iterators/) and [Iterator Consumers](/07-collections/07-iterator-consumers/). ## What replaces JavaScript objects, `Map`, and `Set`? [Section titled “What replaces JavaScript objects, Map, and Set?”](#what-replaces-javascript-objects-map-and-set) A fixed shape is a `struct`; dynamic string keys are a `HashMap`; a `Set` is a `HashSet`. Unlike a JS object, a `HashMap` has one key type and one value type, and `map.get(&k)` returns an `Option` you must unwrap. See [Structs](/06-data-structures/00-structs/) and [HashMaps](/07-collections/03-hashmaps/). ## What is the difference between `String` and `&str`? [Section titled “What is the difference between String and \&str?”](#what-is-the-difference-between-string-and-str) `String` is an owned, growable, heap-allocated string you own and can mutate. `&str` is a borrowed view into string data you do not own. The rule of thumb: take `&str` as a function argument (it accepts both), and return or store a `String` when you need ownership. See [Strings](/07-collections/01-strings/). *** ## What replaces classes and interfaces in Rust? [Section titled “What replaces classes and interfaces in Rust?”](#what-replaces-classes-and-interfaces-in-rust) Rust splits the three jobs a class does. Data goes in a `struct` or `enum`, methods go in an `impl` block, and a shared contract (an interface) is a `trait` you can implement for any type. There is no inheritance; you compose with traits instead. See [Structs](/06-data-structures/00-structs/), [impl Blocks](/06-data-structures/05-impl-blocks/), and [Traits](/09-generics-traits/03-traits/). ## What is a trait, and how does it differ from a TypeScript interface? [Section titled “What is a trait, and how does it differ from a TypeScript interface?”](#what-is-a-trait-and-how-does-it-differ-from-a-typescript-interface) A trait is a set of methods a type promises to provide, like an interface. The differences: you can implement **your own local trait** for a type you do not own, traits can ship default method bodies, and the compiler usually dispatches them statically with zero runtime cost. Rust’s orphan rule forbids implementing a foreign trait for a foreign type; either the trait or the type must be local to your crate. See [Traits](/09-generics-traits/03-traits/) and [Trait Objects](/09-generics-traits/06-trait-objects/). ## How is Rust’s type system different from TypeScript’s? [Section titled “How is Rust’s type system different from TypeScript’s?”](#how-is-rusts-type-system-different-from-typescripts) TypeScript’s types are erased at runtime and can be bypassed with `any` or a wrong cast. Rust’s types are enforced all the way down, there is no `any`, and the same generics also guarantee memory and thread safety. What TypeScript checks optionally, Rust checks always. See [Basic Types](/02-basics/01-types/) and [Generics and Traits](/09-generics-traits/). *** ## Is Rust faster than Node.js? [Section titled “Is Rust faster than Node.js?”](#is-rust-faster-than-nodejs) For CPU-bound work, usually by a wide margin: no garbage collector, no interpreter warm-up, contiguous memory, and zero-cost abstractions. For I/O-bound work the gap narrows, because both spend most of their time waiting. Measure your real workload before assuming. See the [Performance](/21-performance/) section and [Rust vs Node.js](/21-performance/09-comparison/). ## Can I use Rust in the browser with JavaScript? [Section titled “Can I use Rust in the browser with JavaScript?”](#can-i-use-rust-in-the-browser-with-javascript) Yes, through **WebAssembly**. You compile a Rust crate to a `.wasm` module and call it from JavaScript like any module. WebAssembly runs on the thread that invokes it, so call it from a Web Worker when the goal is to move parsing, image work, or another hot path off the browser’s main thread. `wasm-bindgen` generates the glue and the TypeScript types. See [WebAssembly](/19-wasm/) and [Your First WASM Module](/19-wasm/02-first-wasm/). ## Can Rust call JavaScript or Node libraries? [Section titled “Can Rust call JavaScript or Node libraries?”](#can-rust-call-javascript-or-node-libraries) Both directions work. In the browser, `wasm-bindgen` lets Rust call JS APIs. On the server, you build a native Node addon in Rust with `napi-rs` and `import` it from JavaScript like any package, with generated TypeScript types and no C++. See [Node Addons with napi-rs](/20-unsafe-ffi/06-napi/) and [Calling JavaScript from Rust](/19-wasm/03-js-interop/). *** ## What is the Rust equivalent of npm and `package.json`? [Section titled “What is the Rust equivalent of npm and package.json?”](#what-is-the-rust-equivalent-of-npm-and-packagejson) **Cargo**, plus `Cargo.toml`. `npm install x` is `cargo add x`, `npm run build` is `cargo build --release`, and `npm test` is `cargo test`. Cargo also bundles the formatter, linter, test runner, and docs generator that you wire up separately in the JS world. See [Cargo](/12-modules-packages/04-cargo/) and [Dependencies](/12-modules-packages/06-dependencies/). ## How do I work with JSON in Rust? [Section titled “How do I work with JSON in Rust?”](#how-do-i-work-with-json-in-rust) With **Serde**. Derive `Serialize` and `Deserialize` on a struct and `serde_json` converts to and from JSON, type-checked. `JSON.parse` becomes `serde_json::from_str`, and `JSON.stringify` becomes `serde_json::to_string`, against a concrete type instead of `any`. See [JSON with Serde](/15-serialization/03-json/) and [Serde Basics](/15-serialization/01-serde-basics/). ## What is the Rust equivalent of `console.log`? [Section titled “What is the Rust equivalent of console.log?”](#what-is-the-rust-equivalent-of-consolelog) `println!("{x}")` for normal output and `eprintln!` for stderr. To print any value while debugging, derive `Debug` and use `println!("{x:?}")` or the `dbg!(x)` macro, which also prints the file and line. See [Output and Formatting](/02-basics/04-output/). *** ## What is the hardest part of Rust for JavaScript developers? [Section titled “What is the hardest part of Rust for JavaScript developers?”](#what-is-the-hardest-part-of-rust-for-javascript-developers) Three things, in order: **ownership and borrowing** (the borrow checker), **lifetimes** (proving references stay valid), and **async** (lazy futures and a runtime you choose). None are conceptually huge, but they are unfamiliar. Ownership is the one that unlocks the rest. See [Ownership](/05-ownership/), [Lifetimes](/05-ownership/04-lifetimes/), and [Async vs Sync](/11-async/13-async-vs-sync/). ## Do I need to learn C before Rust? [Section titled “Do I need to learn C before Rust?”](#do-i-need-to-learn-c-before-rust) No. Rust is designed so you almost never touch raw pointers or manual memory management in everyday code; the safe subset covers the vast majority of programs. C knowledge helps only when you reach for `unsafe` or foreign-function interfaces, which most application code never does. See [When to Use Unsafe](/20-unsafe-ffi/09-when-to-use/). ## What can I build with Rust as a web developer? [Section titled “What can I build with Rust as a web developer?”](#what-can-i-build-with-rust-as-a-web-developer) WebAssembly modules for the browser, HTTP services and APIs, command-line tools, native Node addons, and the performance-critical core of an otherwise-JavaScript app. It is a strong fit anywhere you currently hit the ceiling of a single-threaded, garbage-collected runtime. See the [Projects](/30-projects/) section for full worked examples. # Version and Verification Policy > How rs4ts.dev pins Rust, records crate versions, and verifies capstone projects and runnable documentation snippets without calling an old pin the latest stable release. Rust and its crate ecosystem release frequently. This guide therefore separates three ideas that are easy to conflate: * **The Rust edition** is the language compatibility boundary used by a crate. New projects in this guide use the **2024 edition**. * **The repository toolchain** is the exact compiler used for reproducible local and CI checks. Its source of truth is [`rust-toolchain.toml`](https://github.com/zeybek/rs4ts.dev/blob/main/rust-toolchain.toml). * **The latest stable Rust release** changes on Rust’s release cadence. The guide does not hard-code that moving value across chapter prose. At the time of this repository snapshot, the verification toolchain is pinned to **Rust 1.96.0**. That sentence describes a tested baseline, not a claim that 1.96.0 is still the newest stable release. Run `rustup update stable` in a separate project when you specifically want to try the newest compiler; use the repository pin when reproducing this guide’s CI results. ## What CI verifies [Section titled “What CI verifies”](#what-ci-verifies) The repository applies different checks to different kinds of examples: 1. **Six capstone crates** are checked with the pinned toolchain. CI runs rustfmt, Clippy with warnings denied, native tests, and the relevant `wasm32-unknown-unknown` checks. 2. **A deterministic subset of self-contained standard-library `rust playground` programs** is extracted from normal lesson sections and compiled as Rust 2024 code. Fragments, Common Pitfalls/Exercises sections, deliberately failing teaching examples, and snippets requiring external crates or multiple files are outside that automatic subset. CI enforces a minimum selected count so the gate cannot silently shrink to zero. 3. **Internal links and anchors** are checked by the production site build. 4. **External-crate snippets** state their required dependencies beside the example. They still require a focused Cargo project when edited; a green standard-library snippet job does not prove those integrations. This scope is intentionally explicit. “Checked on the pinned toolchain” is a reproducible claim only for the named gate; “every example compiles on current stable” would be broader than the automated evidence. ## Crate versions [Section titled “Crate versions”](#crate-versions) Chapter prose uses a major or compatible line when that is the meaningful API contract (`axum 0.8`, `serde 1`, `tokio 1`). Exact versions belong in the capstone `Cargo.lock` files or in a page only when an API changed across releases and the distinction matters to the lesson. When updating the repository toolchain or a documented dependency: 1. change the single source of truth (`rust-toolchain.toml`, a capstone manifest/lockfile, or the page’s dependency block); 2. run the focused examples affected by the API change; 3. run the documentation snippet checker and full site build; 4. describe historical measurements as “measured with” or “verified with,” never as permanently “current.” That wording keeps old benchmark output reproducible without turning yesterday’s tested version into today’s release claim. # Getting Started with Rust > Welcome to Rust! This section will get you up and running with your first Rust program. Welcome to Rust! This section will get you up and running with your first Rust program. *** ## What’s in This Section [Section titled “What’s in This Section”](#whats-in-this-section) * **[Why Rust](/01-getting-started/00-why-rust/)** - Detailed reasons to learn Rust as a TS/JS developer * **[Installing Rust](/01-getting-started/01-installation/)** - Setup guide for all platforms * **[Hello World](/01-getting-started/02-hello-world/)** - Your first Rust program * **[Understanding Cargo](/01-getting-started/03-cargo-basics/)** - Rust’s build tool and package manager * **[Rust Playground](/01-getting-started/04-playground/)** - Try Rust without installing anything *** ## Learning Objectives [Section titled “Learning Objectives”](#learning-objectives) By the end of this section, you will: * Understand why Rust is valuable for TS/JS developers * Have Rust installed and configured on your system * Write and run your first Rust program * Understand Cargo and its role (think: npm + webpack + more) * Know how to use the online Rust Playground *** ## Time Estimate [Section titled “Time Estimate”](#time-estimate) * **Reading:** 45-60 minutes * **Installation & Setup:** 15-30 minutes * **Hands-on Practice:** 30-45 minutes * **Total:** 1.5-2 hours *** ## Quick Start Path [Section titled “Quick Start Path”](#quick-start-path) If you want to jump right in: 1. **[Install Rust](/01-getting-started/01-installation/)** (15 minutes) 2. **[Hello World](/01-getting-started/02-hello-world/)** (15 minutes) 3. **[Cargo Basics](/01-getting-started/03-cargo-basics/)** (15 minutes) Then come back and read the other topics at your leisure. *** ## Detailed Learning Path [Section titled “Detailed Learning Path”](#detailed-learning-path) ### Recommended Order [Section titled “Recommended Order”](#recommended-order) ```plaintext 1 1. Why Rust (understand the motivation) 2 ↓ 3 2. Installation (get Rust on your machine) 4 ↓ 5 3. Hello World (write your first program) 6 ↓ 7 4. Cargo Basics (learn the tooling) 8 ↓ 9 5. Playground (for quick experiments) ``` ### Alternative: Hands-On First [Section titled “Alternative: Hands-On First”](#alternative-hands-on-first) ```plaintext 1 1. Playground (try Rust immediately, no install) 2 ↓ 3 2. Installation (once you're convinced) 4 ↓ 5 3. Hello World 6 ↓ 7 4. Why Rust (understand what you just did) 8 ↓ 9 5. Cargo Basics ``` *** ## What You’ll Learn [Section titled “What You’ll Learn”](#what-youll-learn) ### Why Rust? (vs TypeScript/Node.js) [Section titled “Why Rust? (vs TypeScript/Node.js)”](#why-rust-vs-typescriptnodejs) Compare Rust to what you already know: **TypeScript/Node.js:** * Interpreted/JIT compiled * Garbage collected * Single-threaded event loop * Runtime errors * 50-100ms startup time * 50-200 MB memory baseline **Rust:** * Compiled to native code * No garbage collection * Safe, compiler-checked, opt-in multithreading (fearless concurrency) * Compile-time error checking * <1ms startup time * 1-5 MB memory baseline ### Installation [Section titled “Installation”](#installation) You’ll learn: * How to install Rust using rustup * How to verify your installation * How to update Rust * Editor setup for the best experience ### Hello World [Section titled “Hello World”](#hello-world) Your first Rust program: ```rust 1 fn main() { 2 println!("Hello, world!"); 3 } ``` Compared to TypeScript, where top-level code runs directly with no required entry-point function: ```typescript 1 console.log("Hello, world!"); ``` ### Cargo: The Complete Toolchain [Section titled “Cargo: The Complete Toolchain”](#cargo-the-complete-toolchain) Cargo is like npm, webpack, and more combined: | Feature | TypeScript/JS | Rust | | --------------- | ------------- | ----------- | | Package Manager | npm/yarn/pnpm | Cargo | | Build Tool | webpack/vite | Cargo | | Test Runner | jest/vitest | Cargo | | Formatter | prettier | rustfmt | | Linter | eslint | clippy | | Documentation | typedoc | rustdoc | | Benchmarking | (various) | Cargo bench | | Task Runner | npm scripts | Cargo | **All in one tool!** ### The Playground [Section titled “The Playground”](#the-playground) [play.rust-lang.org](https://play.rust-lang.org/) lets you: * Try Rust without installing anything * Share code snippets * Test ideas quickly * Learn with instant feedback *** ## What Makes Rust Different [Section titled “What Makes Rust Different”](#what-makes-rust-different) ### 1. Compiled, Not Interpreted [Section titled “1. Compiled, Not Interpreted”](#1-compiled-not-interpreted) **TypeScript/JavaScript:** ```bash 1 node app.js # V8 parses, then JIT-compiles hot code at runtime 2 ts-node app.ts # Strips types, then runs through the same V8 pipeline ``` **Rust:** ```bash 1 rustc main.rs # Compiled to native binary 2 ./main # Execute native code ``` **Impact:** * Faster execution, especially CPU-bound work (no GC pauses) * Smaller deployments (single binary) * No runtime dependencies * Slower build times (seconds vs milliseconds) ### 2. No Garbage Collector [Section titled “2. No Garbage Collector”](#2-no-garbage-collector) **TypeScript/JavaScript:** * Automatic memory management * GC pauses (unpredictable timing) * Memory overhead * Easy to use **Rust:** * Ownership system (compile-time memory management) * No GC pauses (predictable performance) * Minimal memory overhead * Learning curve ### 3. Stronger Type System [Section titled “3. Stronger Type System”](#3-stronger-type-system) **TypeScript:** ```typescript 1 let x: any = "hello"; // Escape hatch — type checking is disabled 2 x = 42; // No complaint from the compiler 3 let y = x.length; // No error: silently `undefined` at runtime ``` **Rust:** ```rust 1 let x = "hello"; // Type inference 2 let y = x.len(); // Always safe, or won't compile ``` ### 4. Explicit Error Handling [Section titled “4. Explicit Error Handling”](#4-explicit-error-handling) **TypeScript:** ```typescript 1 function divide(a: number, b: number): number { 2 if (b === 0) { 3 throw new Error("Division by zero"); // Exception 4 } 5 return a / b; 6 } ``` **Rust:** ```rust 1 fn divide(a: i32, b: i32) -> Result { 2 if b == 0 { 3 Err("Division by zero".to_string()) // Explicit error value 4 } else { 5 Ok(a / b) 6 } 7 } ``` **No exceptions in Rust!** All errors are explicit in the type system. *** ## Your Goals for This Section [Section titled “Your Goals for This Section”](#your-goals-for-this-section) ### Minimum Goals [Section titled “Minimum Goals”](#minimum-goals) * [ ] Install Rust on your machine * [ ] Run `cargo --version` successfully * [ ] Create and run a “Hello World” program * [ ] Understand what Cargo does ### Stretch Goals [Section titled “Stretch Goals”](#stretch-goals) * [ ] Configure your editor with rust-analyzer * [ ] Experiment with the Rust Playground * [ ] Create a custom Cargo project * [ ] Read Cargo.toml and understand its structure *** ## Key Concepts Preview [Section titled “Key Concepts Preview”](#key-concepts-preview) ### Concepts You’ll Encounter [Section titled “Concepts You’ll Encounter”](#concepts-youll-encounter) **rustup** - The Rust toolchain installer (like nvm for Node.js) **cargo** - Build tool and package manager (like npm + webpack) **rustc** - The Rust compiler. Where `tsc` erases types and emits JavaScript that still needs a runtime, `rustc` produces a self-contained native binary. **crates** - Rust packages (like npm packages) **Cargo.toml** - Project manifest (like package.json) **main.rs** - Entry point file (like index.ts) Don’t worry if these don’t make sense yet - they will soon! *** ## Common First-Time Issues [Section titled “Common First-Time Issues”](#common-first-time-issues) ### ”rustup: command not found” [Section titled “”rustup: command not found””](#rustup-command-not-found) **Problem:** Installation didn’t add rustup to PATH **Solution:** ```bash 1 # Restart your terminal first. 2 # On macOS/Linux you can also source the env file in the current shell: 3 source "$HOME/.cargo/env" ``` > **Note:** `source ~/.cargo/env` is a Unix shell command and does **not** work in Windows PowerShell or `cmd.exe`. On Windows, the rustup installer adds Cargo to your `PATH` automatically; just open a new terminal window. ### ”cargo: command not found” [Section titled “”cargo: command not found””](#cargo-command-not-found) **Problem:** Same as above **Solution:** Restart your terminal (Windows), or source the cargo env file in the current shell (macOS/Linux) ### “error: linking with `cc` failed” [Section titled ““error: linking with cc failed””](#error-linking-with-cc-failed) **Problem:** Missing C compiler (Rust needs it for linking) **Solution:** * **macOS:** `xcode-select --install` * **Linux:** `sudo apt install build-essential` * **Windows:** Install Visual Studio Build Tools ### Slow Compilation [Section titled “Slow Compilation”](#slow-compilation) **Problem:** First compile is always slow **Why:** Rust compiles dependencies from source **Tips:** * Use `cargo build` without `--release` during development * Dependencies are cached after first build * Consider using `sccache` for faster recompilation *** ## Additional Resources [Section titled “Additional Resources”](#additional-resources) ### Official Resources [Section titled “Official Resources”](#official-resources) * [Rust Installation Guide](https://www.rust-lang.org/tools/install) * [Cargo Book](https://doc.rust-lang.org/cargo/) * [Rust Playground](https://play.rust-lang.org/) ### Community Resources [Section titled “Community Resources”](#community-resources) * [Rust Discord](https://discord.gg/rust-lang) * [r/rust](https://reddit.com/r/rust) * [This Week in Rust](https://this-week-in-rust.org/) *** ## Ready to Begin? [Section titled “Ready to Begin?”](#ready-to-begin) Let’s get Rust installed and write your first program! ### [Start with Why Rust](/01-getting-started/00-why-rust/) [Section titled “Start with Why Rust”](#start-with-why-rust) Or jump straight to: * [Installation Guide](/01-getting-started/01-installation/) * [Hello World](/01-getting-started/02-hello-world/) # Why Rust for TS/JS Developers? > You already know TypeScript and JavaScript. Why should you invest time learning Rust? Let's compare the two and explore where Rust excels. You already know TypeScript and JavaScript. Why should you invest time learning Rust? Let’s compare the two and explore where Rust excels. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Rust is **not** a replacement for TypeScript/JavaScript. They solve different problems: * **TypeScript/JavaScript:** Web development, rapid prototyping, full-stack apps * **Rust:** Performance-critical backends, systems programming, CLI tools, WebAssembly **Think of it as:** Adding another tool to your toolbox, not replacing your existing tools. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Let’s start with a familiar example - a web server that handles user requests: ```typescript 1 // Express.js server 2 import express from "express"; 3 4 interface User { 5 id: number; 6 name: string; 7 email: string; 8 } 9 10 const app = express(); 11 const users: User[] = []; 12 13 app.get("/users/:id", (req, res) => { 14 const id = parseInt(req.params.id); 15 const user = users.find((u) => u.id === id); 16 17 if (user) { 18 res.json(user); 19 } else { 20 res.status(404).json({ error: "User not found" }); 21 } 22 }); 23 24 app.listen(3000, () => { 25 console.log("Server running on port 3000"); 26 }); ``` **Characteristics:** * Quick to write * Easy to understand * Fast development iteration * The main event loop runs JavaScript on one thread; worker threads and multi-process clustering are explicit options * Startup time and memory depend on the Node version, framework, dependencies, and deployment packaging * Garbage collection can introduce latency pauses; measure whether they matter for your workload * TypeScript checks source types, while runtime input still needs validation *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same server in Rust (using the **Axum** framework, version 0.8): ```rust 1 // Axum server 2 use axum::{ 3 extract::Path, 4 http::StatusCode, 5 routing::get, 6 Json, Router, 7 }; 8 use serde::{Deserialize, Serialize}; 9 use std::sync::Arc; 10 use tokio::sync::RwLock; 11 12 #[derive(Clone, Serialize, Deserialize)] 13 struct User { 14 id: u32, 15 name: String, 16 email: String, 17 } 18 19 type UserDb = Arc>>; 20 21 async fn get_user( 22 Path(id): Path, 23 db: axum::extract::State, 24 ) -> Result, StatusCode> { 25 let users = db.read().await; 26 users 27 .iter() 28 .find(|u| u.id == id) 29 .cloned() 30 .map(Json) 31 .ok_or(StatusCode::NOT_FOUND) 32 } 33 34 #[tokio::main] 35 async fn main() { 36 let db: UserDb = Arc::new(RwLock::new(Vec::new())); 37 38 let app = Router::new() 39 .route("/users/{id}", get(get_user)) 40 .with_state(db); 41 42 println!("Server running on port 3000"); 43 let listener = tokio::net::TcpListener::bind("0.0.0.0:3000") 44 .await 45 .unwrap(); 46 axum::serve(listener, app).await.unwrap(); 47 } ``` **Characteristics:** * Tokio’s multi-thread scheduler can move ready tasks across worker threads * Native startup and memory are often low, but still depend on dependencies, allocator, build profile, and workload * No garbage collection pauses * Strong compile-time guarantees (whole classes of bugs are caught before runtime, though panics like `unwrap()` still exist) * CPU-bound code is often faster, but only a same-work, same-core benchmark can quantify the difference * More verbose * Slower compilation * Steeper learning curve *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Memory Management [Section titled “Memory Management”](#memory-management) **TypeScript/JavaScript:** ```typescript 1 let data = { value: 42 }; 2 let data2 = data; // Both reference same object 3 data = null; // data2 still points to object 4 // Garbage collector cleans up eventually ``` * Memory is automatically managed * Garbage collector runs periodically * Unpredictable pauses (can be 1-100ms) * Memory overhead for GC bookkeeping **Rust:** ```rust 1 let data = String::from("hello"); 2 let data2 = data; // Ownership moved to data2 3 // data is no longer valid - compile error if used! 4 // Memory freed immediately when data2 goes out of scope ``` * Memory is tracked at compile time * No garbage collector needed * Predictable performance (no pauses) * Minimal memory overhead **Why it matters:** For web servers handling thousands of requests, GC pauses can add up. Rust’s approach eliminates these pauses entirely. ### Concurrency [Section titled “Concurrency”](#concurrency) **TypeScript/JavaScript:** ```typescript 1 // Single-threaded, event loop 2 async function processRequests(requests: Request[]) { 3 // Processes one at a time (unless you spawn workers) 4 for (const req of requests) { 5 await handleRequest(req); 6 } 7 } ``` * Single-threaded by default * Worker threads are complex to use * Async/await for I/O concurrency * No true parallelism (without workers) **Rust:** ```rust 1 // I/O concurrency: Tokio can schedule ready tasks on its worker threads 2 async fn process_requests(requests: Vec) { 3 // Requests make progress concurrently while they wait for I/O. 4 let handles: Vec<_> = requests 5 .into_iter() 6 .map(|req| tokio::spawn(handle_request(req))) 7 .collect(); 8 9 for handle in handles { 10 handle.await.unwrap(); 11 } 12 } ``` * Safe, opt-in multithreading (fearless concurrency) * Thread-safety requirements checked at compile time * No data races in safe Rust * Concurrent I/O; use threads or Rayon when the work itself is CPU-bound **Why it matters:** Tokio can keep many I/O-bound requests moving without dedicating one thread to each connection. CPU-intensive work (image processing, data transformation) needs explicit CPU parallelism such as Rayon, `std::thread`, or carefully bounded `spawn_blocking`; wrapping it in `tokio::spawn` does not make the computation faster. ### Error Handling [Section titled “Error Handling”](#error-handling) **TypeScript/JavaScript:** ```typescript 1 function getUser(id: number): User { 2 const user = database.find(id); 3 if (!user) { 4 throw new Error("User not found"); // Exception can crash the app 5 } 6 return user; 7 } 8 9 // Easy to forget error handling 10 const user = getUser(123); // What if this throws? ``` * Exceptions can be thrown anywhere * Easy to forget to catch them * Runtime crashes possible * Try/catch adds noise **Rust:** ```rust 1 fn get_user(id: u32) -> Result { 2 match database.find(id) { 3 Some(user) => Ok(user), 4 None => Err("User not found".to_string()), 5 } 6 } 7 8 // `?` explicitly propagates an error to this function's caller. 9 let user = get_user(123)?; ``` * No exceptions * Errors are explicit in the type system * Using the success value requires matching, propagating, choosing a fallback, or deliberately panicking * `?` operator for convenient error propagation **Why it matters:** In production, unhandled exceptions cause outages. Rust puts recoverable failure in the function signature, and an entirely discarded `Result` produces an `unused_must_use` warning by default. Teams commonly deny warnings in CI, but Rust still lets you make an explicit choice to discard, propagate, or panic. *** ## Key Differences [Section titled “Key Differences”](#key-differences) ### 1. **Performance** [Section titled “1. Performance”](#1-performance) There is no honest universal multiplier between Node.js and Rust. Framework, payload, allocator, warm-up, database latency, concurrency, hardware, and build profile can change the result by orders of magnitude. Compare representative workloads under the same conditions: | Workload | What usually dominates | Fair comparison | | --------------- | ---------------------------------------------- | --------------------------------------------------------------- | | HTTP API | Database/network latency, framework overhead | Same routes, pool sizes, payloads, cores, and load model | | JSON processing | Schema, allocation pattern, payload shape | The real production payload, validated the same way | | Cold start | Runtime initialization, binary/dependency size | Same host and deployment packaging, multiple cold runs | | Memory | V8 heap/GC policy vs. Rust allocations | RSS under the same sustained load, including caches | | CPU kernel | JIT warm-up, AOT optimization, vectorization | Warm Node first; compile Rust with `--release`; use equal cores | The measured [Rust vs Node.js comparison](/21-performance/09-comparison/) publishes its machine, commands, code, and caveats. Use that as a reproducible example, then benchmark your own service before making a migration decision. **When it matters:** * High-traffic APIs (save on cloud costs) * Real-time systems (gaming, trading) * CLI tools (instant startup) * Data processing pipelines **When it doesn’t:** * Low-traffic CRUD apps * Simple websites * Prototypes ### 2. **Safety** [Section titled “2. Safety”](#2-safety) **TypeScript:** ```typescript 1 function getFirst(arr: readonly T[]): T | undefined { 2 return arr[0]; // With noUncheckedIndexedAccess, TypeScript infers this possibility too. 3 } ``` **Rust:** ```rust 1 fn get_first(arr: &[T]) -> Option<&T> { 2 arr.first() // Extracting &T requires matching, propagating, or choosing a fallback. 3 } ``` Strict TypeScript with `noUncheckedIndexedAccess` models this example correctly, so the difference is not “TypeScript cannot express absence.” Rust makes the check language-wide and non-configurable, while TypeScript’s guarantee depends on project settings and is erased at runtime. Both languages still need runtime validation for untrusted JSON. **What Rust prevents at compile time:** * Null/undefined dereferences * Buffer overflows * Data races * Use-after-free * Double-free * Iterator invalidation TypeScript can model many domain-level mistakes when strict options are enabled, but it does not enforce Rust’s memory and thread-safety guarantees and its types do not validate runtime input by themselves. ### 3. **Deployment** [Section titled “3. Deployment”](#3-deployment) **TypeScript/JavaScript:** ```bash 1 # Need Node.js runtime on server 2 node dist/index.js 3 4 # Docker image: ~200-500 MB 5 FROM node:18 6 COPY package*.json ./ 7 RUN npm install 8 COPY . . 9 CMD ["node", "dist/index.js"] ``` **Rust:** ```bash 1 # Single binary, no runtime needed 2 ./my-app 3 4 # Docker image: ~10-20 MB 5 FROM scratch 6 COPY ./my-app / 7 CMD ["/my-app"] ``` **Why it matters:** * Faster deployments * Smaller container images * No runtime vulnerabilities * Easier distribution (single file!) ### 4. **Type System** [Section titled “4. Type System”](#4-type-system) **TypeScript:** ```typescript 1 // Type system can be escaped 2 let x: any = "hello"; 3 x = 123; // Allowed with 'any' 4 5 // Under strict mode, the optional type is enforced 6 let y: string | undefined; 7 console.log(y.length); // Compile error under strict mode: 'y' is possibly 'undefined' ``` **Rust:** ```rust 1 // No escape hatches (except unsafe blocks) 2 let x: String = String::from("hello"); 3 // x = 123; // Compile error! 4 5 // Optional is enforced 6 let y: Option = None; 7 // println!("{}", y.len()); // Compile error! 8 println!("{}", y.unwrap_or_default().len()); // Must handle None case ``` **Why it matters:** Rust catches more bugs at compile time, TypeScript catches some but allows escape hatches. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: “Rust will make me more productive immediately” [Section titled “Pitfall 1: “Rust will make me more productive immediately””](#pitfall-1-rust-will-make-me-more-productive-immediately) **Reality:** Rust has a steep learning curve. Expect 3-4 weeks before you’re comfortable, 2-3 months before you’re productive. **Mitigation:** Start with small projects, don’t rewrite critical systems immediately. ### Pitfall 2: “I should rewrite everything in Rust” [Section titled “Pitfall 2: “I should rewrite everything in Rust””](#pitfall-2-i-should-rewrite-everything-in-rust) **Reality:** Most web apps don’t need Rust’s performance. Node.js is fine for CRUD apps. **Use Rust when:** * You have performance problems * You’re building a new performance-critical service * You need predictable latency * You’re building CLI tools **Stick with Node.js when:** * Rapid prototyping * Simple CRUD apps * Small teams without Rust experience * Time-to-market is critical ### Pitfall 3: “Rust is just like TypeScript with different syntax” [Section titled “Pitfall 3: “Rust is just like TypeScript with different syntax””](#pitfall-3-rust-is-just-like-typescript-with-different-syntax) **Reality:** The ownership system is completely new. You’ll need to think differently about data lifecycle. **What’s similar:** * Async/await syntax * Type system concepts * Generics **What’s different:** * Ownership and borrowing * No garbage collection * No null (use Option instead) * No exceptions (use Result instead) ### Pitfall 4: “Fighting the compiler” [Section titled “Pitfall 4: “Fighting the compiler””](#pitfall-4-fighting-the-compiler) **Reality:** The Rust compiler is strict. Don’t fight it - learn from it! ```rust 1 // This won't compile 2 let s = String::from("hello"); 3 let s2 = s; 4 println!("{}", s); // Error: value borrowed after move ``` **Don’t think:** “The compiler is annoying!”\ **Think:** “The compiler is preventing a bug I would have in production!” *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. **Use Rust for the Right Problems** [Section titled “1. Use Rust for the Right Problems”](#1-use-rust-for-the-right-problems) **Great for:** * High-performance APIs * CLI tools * Systems programming * WebAssembly * Microservices with high load * Replacing Python/Ruby/Node.js bottlenecks **Not ideal for:** * Simple CRUD apps * Rapid prototyping * When team doesn’t know Rust * When time-to-market is critical ### 2. **Hybrid Approach** [Section titled “2. Hybrid Approach”](#2-hybrid-approach) Many companies use **both** Node.js and Rust: ```plaintext 1 TypeScript/Node.js: 2 - Web frontend (Next.js, React) 3 - Simple APIs 4 - Admin dashboards 5 - Internal tools 6 7 Rust: 8 - Performance-critical services 9 - Data processing pipelines 10 - Real-time systems 11 - CLI tools ``` Example: Discord adopted Rust for latency-sensitive backend services (such as their Read States service) while keeping other languages elsewhere in their stack. ### 3. **Gradual Migration** [Section titled “3. Gradual Migration”](#3-gradual-migration) Don’t rewrite everything at once: **Phase 1:** Identify bottlenecks ```typescript 1 // Profile your Node.js app 2 // Find the slow parts ``` **Phase 2:** Extract and rewrite ```rust 1 // Rewrite just the slow service in Rust 2 // Keep the rest in Node.js ``` **Phase 3:** Compare ```plaintext 1 Measure performance improvement 2 If significant: keep Rust version 3 If not: was Node.js the problem? ``` ### 4. **Learn the Ownership System First** [Section titled “4. Learn the Ownership System First”](#4-learn-the-ownership-system-first) Don’t skip the ownership section! It’s the foundation of Rust: 1. Ownership rules 2. Borrowing and references 3. Lifetimes 4. Moving vs copying Everything else in Rust builds on these concepts. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) ### Discord’s Experience [Section titled “Discord’s Experience”](#discords-experience) Discord rewrote their **Read States** service from Go to Rust to eliminate garbage-collection latency: **Before (Go):** * Latency spikes every few minutes (caused by Go’s garbage collector) * Tail-latency tied to GC pauses * Memory pressure under load **After (Rust):** * Consistent low latency * No GC pauses * Lower memory usage **Source:** [Discord: Why Discord is switching from Go to Rust](https://discord.com/blog/why-discord-is-switching-from-go-to-rust) ### Figma’s Experience [Section titled “Figma’s Experience”](#figmas-experience) Figma rewrote performance-critical parts of its multiplayer server (originally TypeScript/Node.js) in Rust: **Why Rust:** * Needed predictable performance * No GC pauses (critical for real-time collaboration) * Multi-threaded performance **Result:** * Handles millions of concurrent users * Consistent low latency * Lower infrastructure costs *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Resources [Section titled “Official Resources”](#official-resources) * [Rust vs Go](https://bitfieldconsulting.com/golang/rust-vs-go) * [Rust for Node Developers](https://github.com/Mercateo/rust-for-node-developers) * [Rust Performance Book](https://nnethercote.github.io/perf-book/) ### Case Studies [Section titled “Case Studies”](#case-studies) * [Discord: From Go to Rust](https://discord.com/blog/why-discord-is-switching-from-go-to-rust) * [AWS: Why We Built Firecracker in Rust](https://aws.amazon.com/blogs/opensource/why-aws-loves-rust-and-how-wed-like-to-help/) * [ZDNet: Microsoft to explore using Rust](https://www.zdnet.com/article/microsoft-to-explore-using-rust/) ### Community Discussions [Section titled “Community Discussions”](#community-discussions) * [r/rust: Success Stories](https://www.reddit.com/r/rust/search?q=success+story) * [Rust Users Forum](https://users.rust-lang.org/) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Benchmark Comparison [Section titled “Exercise 1: Benchmark Comparison”](#exercise-1-benchmark-comparison) Run a simple benchmark comparing Node.js and Rust: **Node.js:** fib.ts ```typescript 1 function fibonacci(n: number): number { 2 if (n <= 1) return n; 3 return fibonacci(n - 1) + fibonacci(n - 2); 4 } 5 6 console.time("fib"); 7 console.log(fibonacci(40)); 8 console.timeEnd("fib"); ``` **Rust:** fib.rs ```rust 1 fn fibonacci(n: u32) -> u32 { 2 if n <= 1 { 3 return n; 4 } 5 fibonacci(n - 1) + fibonacci(n - 2) 6 } 7 8 fn main() { 9 let start = std::time::Instant::now(); 10 println!("{}", fibonacci(40)); 11 println!("Time: {:?}", start.elapsed()); 12 } ``` **Task:** Run both (compile the Rust version with `cargo run --release`) and compare times. The exact ratio depends heavily on your machine, the input, and how well V8’s JIT optimizes the JavaScript — for this naive recursive benchmark expect Rust to be roughly a few times faster, not orders of magnitude. The dramatic wins show up in workloads that are tight loops over typed data, parallelism, or memory layout. ### Exercise 2: Identify Use Cases [Section titled “Exercise 2: Identify Use Cases”](#exercise-2-identify-use-cases) For each scenario, decide: Node.js or Rust? 1. Simple blog with 100 daily users 2. Real-time stock trading system 3. CLI tool to process large CSV files 4. Admin dashboard for internal use 5. API serving 10,000 requests/second 6. Startup MVP with 2-week deadline Solutions 1. **Node.js** - Simple, low traffic 2. **Rust** - Needs predictable low latency 3. **Rust** - CPU-intensive, CLI tools benefit from instant startup 4. **Node.js** - Internal tool, development speed matters 5. **Could be either** - Node.js can handle it, Rust would be more efficient 6. **Node.js** - Speed of development matters most *** ## Summary [Section titled “Summary”](#summary) **Why learn Rust as a TS/JS developer:** 1. **Performance** - often substantially faster for CPU-bound and memory-bound tasks (the exact margin depends on the workload) 2. **Safety** - Catch bugs at compile time 3. **Concurrency** - Fearless multi-threading 4. **Deployment** - Single binary, no runtime 5. **Career Growth** - High demand, interesting problems 6. **Better Developer** - Understanding low-level concepts improves all coding **When to use Rust:** * Performance-critical backends * CLI tools * Systems programming * WebAssembly * Microservices with high load **When to use Node.js:** * Rapid prototyping * Simple CRUD apps * Tight deadlines * Small teams **Remember:** Rust is not a replacement for TypeScript/JavaScript. It’s an additional tool for specific problems. # Installing Rust > Let's get Rust installed on your system. This guide covers all major platforms: macOS, Linux, and Windows. Let’s get Rust installed on your system. This guide covers all major platforms: macOS, Linux, and Windows. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Rust installation is simple using **rustup**, the official Rust toolchain installer. Think of it like nvm for Node.js - it manages Rust versions and tooling. **Time required:** 10-20 minutes *** ## TypeScript/JavaScript Comparison [Section titled “TypeScript/JavaScript Comparison”](#typescriptjavascript-comparison) **Installing Node.js:** ```bash 1 # Download installer from nodejs.org 2 # Or use nvm 3 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash 4 nvm install --lts # Installs current LTS (e.g. Node 22) 5 nvm use --lts ``` **Installing Rust:** ```bash 1 # Use rustup (official installer) 2 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh 3 source $HOME/.cargo/env ``` **Key similarities:** * Both use version managers (nvm/rustup) * Both install command-line tools * Both update your PATH **Key differences:** * The rustup download is larger (\~200 MB) because it bundles the toolchain, but it’s a single step * Rust includes everything (compiler, package manager, formatter, linter) * No separate npm install - Cargo is built-in! *** ## Installation by Platform [Section titled “Installation by Platform”](#installation-by-platform) ### macOS [Section titled “macOS”](#macos) #### Prerequisites [Section titled “Prerequisites”](#prerequisites) First, install Xcode Command Line Tools (if not already installed): ```bash 1 xcode-select --install ``` This provides the C compiler needed for Rust’s linker. #### Install Rust [Section titled “Install Rust”](#install-rust) ```bash 1 # Download and run rustup 2 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ``` **What this does:** 1. Downloads rustup 2. Installs the latest stable Rust 3. Installs cargo (package manager) 4. Adds Rust to your PATH 5. Installs rustfmt (formatter) and cargo-clippy (linter) **Interactive options:** ```plaintext 1 1) Proceed with installation (default) 2 2) Customize installation 3 3) Cancel installation ``` Just press Enter for option 1 (default). #### Configure Your Shell [Section titled “Configure Your Shell”](#configure-your-shell) ```bash 1 # Add cargo to your PATH 2 source $HOME/.cargo/env 3 4 # Or restart your terminal ``` **For zsh (default on macOS):** rustup automatically adds this line to `~/.zshrc`: ```bash 1 . "$HOME/.cargo/env" ``` **For bash:** rustup adds this to `~/.bash_profile`: ```bash 1 . "$HOME/.cargo/env" ``` #### Verify Installation [Section titled “Verify Installation”](#verify-installation) ```bash 1 # Check Rust compiler 2 rustc --version 3 # Output: rustc 1.96.0 (or newer) 4 5 # Check cargo 6 cargo --version 7 # Output: cargo 1.96.0 (or newer) 8 9 # Check rustup 10 rustup --version 11 # Output: rustup 1.29.0 (or newer) ``` *** ### Linux [Section titled “Linux”](#linux) #### Prerequisites [Section titled “Prerequisites”](#prerequisites-1) Install build essentials (C compiler and linker): **Debian/Ubuntu:** ```bash 1 sudo apt update 2 sudo apt install build-essential ``` **Fedora:** ```bash 1 sudo dnf groupinstall "Development Tools" ``` **Arch:** ```bash 1 sudo pacman -S base-devel ``` #### Install Rust [Section titled “Install Rust”](#install-rust-1) ```bash 1 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ``` Follow the same steps as macOS. #### Configure Your Shell [Section titled “Configure Your Shell”](#configure-your-shell-1) ```bash 1 source $HOME/.cargo/env ``` Add to your shell rc file (`~/.bashrc`, `~/.zshrc`, etc.): ```bash 1 . "$HOME/.cargo/env" ``` #### Verify Installation [Section titled “Verify Installation”](#verify-installation-1) ```bash 1 rustc --version 2 cargo --version 3 rustup --version ``` *** ### Windows [Section titled “Windows”](#windows) #### Option 1: Native Windows (Recommended) [Section titled “Option 1: Native Windows (Recommended)”](#option-1-native-windows-recommended) **Prerequisites:** Install Visual Studio C++ Build Tools: 1. Download from: 2. Run the installer 3. Select “C++ build tools” workload 4. Install (takes \~5-10 minutes) **Install Rust:** 1. Download rustup-init.exe from: 2. Run the installer 3. Follow prompts (default options work fine) 4. Restart your terminal **Verify:** ```powershell 1 rustc --version 2 cargo --version ``` #### Option 2: WSL2 (Windows Subsystem for Linux) [Section titled “Option 2: WSL2 (Windows Subsystem for Linux)”](#option-2-wsl2-windows-subsystem-for-linux) If you’re using WSL2, follow the Linux instructions above. **Why WSL2?** * Better compatibility with Unix-based tools * Faster compilation in some cases * More similar to Linux production environments **How to install WSL2:** ```powershell 1 # In PowerShell (Administrator) 2 wsl --install ``` Then follow Linux instructions inside WSL2. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What Gets Installed? [Section titled “What Gets Installed?”](#what-gets-installed) When you run rustup, you get: **1. rustc** - The Rust compiler ```bash 1 rustc main.rs # Compiles to executable ``` **2. cargo** - Package manager and build tool ```bash 1 cargo new my_project # Create new project 2 cargo build # Build project 3 cargo run # Build and run 4 cargo test # Run tests ``` **3. rustup** - Toolchain manager ```bash 1 rustup update # Update Rust 2 rustup default stable # Set default version 3 rustup doc # Open docs ``` **4. rustfmt** - Code formatter ```bash 1 rustfmt main.rs # Format code 2 cargo fmt # Format whole project ``` **5. clippy** - Linter ```bash 1 cargo clippy # Run linter ``` **6. rust-docs** - Offline documentation ```bash 1 rustup doc # Open in browser 2 rustup doc --std # Standard library docs ``` **All included!** No separate installations needed (unlike npm, prettier, eslint, etc. in Node.js). ### Directory Structure [Section titled “Directory Structure”](#directory-structure) Rust installs to: **macOS/Linux:** ```plaintext 1 ~/.cargo/ # Cargo home 2 ├── bin/ # Executables (cargo, rustc, rustfmt, etc.) 3 ├── registry/ # Downloaded crate metadata 4 └── git/ # Git dependencies 5 6 ~/.rustup/ # Rustup home 7 ├── toolchains/ # Installed Rust versions 8 └── settings.toml # Configuration ``` **Windows:** ```plaintext 1 C:\Users\\.cargo\ # Cargo home 2 C:\Users\\.rustup\ # Rustup home ``` ### Environment Variables [Section titled “Environment Variables”](#environment-variables) Rustup adds these to your PATH: ```bash 1 # macOS/Linux 2 export PATH="$HOME/.cargo/bin:$PATH" 3 4 # Windows (added by installer) 5 %USERPROFILE%\.cargo\bin ``` **Compare to Node.js:** ```bash 1 # Node.js (with nvm) 2 export NVM_DIR="$HOME/.nvm" 3 [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" ``` Similar concept, different implementation. *** ## Key Differences from Node.js [Section titled “Key Differences from Node.js”](#key-differences-from-nodejs) ### 1. Single Installer [Section titled “1. Single Installer”](#1-single-installer) **Node.js ecosystem:** ```bash 1 # Multiple separate installs 2 npm install -g typescript 3 npm install -g ts-node 4 npm install -g prettier 5 npm install -g eslint ``` **Rust:** ```bash 1 # All in one! 2 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh 3 # You now have: compiler, package manager, formatter, linter, docs ``` ### 2. One-Step Installation [Section titled “2. One-Step Installation”](#2-one-step-installation) **Node.js:** * Download size: \~50-100 MB * Installation time: 2-5 minutes * node\_modules can be gigabytes per project **Rust:** * Download size: \~200 MB (includes the full toolchain, so the download is larger) * Installation time: 2-5 minutes * A single command sets up the compiler, package manager, formatter, and linter; project dependencies are compiled and cached under `~/.cargo` ### 3. Version Management Built-In [Section titled “3. Version Management Built-In”](#3-version-management-built-in) **Node.js:** ```bash 1 # Need separate tool (nvm, n, fnm) 2 nvm install --lts 3 nvm use --lts 4 nvm list ``` **Rust:** ```bash 1 # Built into rustup 2 rustup install stable 3 rustup default stable 4 rustup toolchain list ``` ### 4. Offline Documentation [Section titled “4. Offline Documentation”](#4-offline-documentation) **Node.js:** ```bash 1 # Online only (mostly) 2 # Browse to nodejs.org or devdocs.io ``` **Rust:** ```bash 1 # Full docs offline! 2 rustup doc # Opens local browser 3 rustup doc --std # Standard library 4 rustup doc --book # The Rust Book ``` *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: “command not found” After Installation [Section titled “Pitfall 1: “command not found” After Installation”](#pitfall-1-command-not-found-after-installation) **Problem:** ```bash 1 rustc --version 2 # zsh: command not found: rustc ``` **Solution:** ```bash 1 # Option 1: Restart your terminal 2 3 # Option 2: Source the cargo env 4 source $HOME/.cargo/env 5 6 # Option 3: Check PATH 7 echo $PATH | grep cargo 8 # Should see: /Users/you/.cargo/bin ``` **Why:** Your shell needs to reload its configuration to see the new PATH. ### Pitfall 2: “linking with `cc` failed” [Section titled “Pitfall 2: “linking with cc failed””](#pitfall-2-linking-with-cc-failed) **Problem:** ```bash 1 cargo build 2 # error: linking with `cc` failed ``` **Solution:** **macOS:** ```bash 1 xcode-select --install ``` **Linux:** ```bash 1 sudo apt install build-essential # Debian/Ubuntu ``` **Windows:** Install Visual Studio C++ Build Tools **Why:** Rust needs a C compiler for linking. The Rust compiler produces object files, but needs a linker to create the final executable. ### Pitfall 3: Old Version of Rust [Section titled “Pitfall 3: Old Version of Rust”](#pitfall-3-old-version-of-rust) **Problem:** Some examples don’t compile because you’re using an old Rust version. **Solution:** ```bash 1 # Update to latest stable 2 rustup update 3 4 # Check version 5 rustc --version ``` **Best practice:** Run `rustup update` periodically; a new stable release ships every 6 weeks. ### Pitfall 4: Permission Errors on Linux [Section titled “Pitfall 4: Permission Errors on Linux”](#pitfall-4-permission-errors-on-linux) **Problem:** ```bash 1 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh 2 # Permission denied ``` **Solution:** Don’t use sudo! Install in your home directory: ```bash 1 # Correct (no sudo) 2 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh 3 4 # Then install system packages with sudo if needed 5 sudo apt install build-essential ``` *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Keep Rust Updated [Section titled “1. Keep Rust Updated”](#1-keep-rust-updated) ```bash 1 # Update Rust (a new stable lands every 6 weeks) 2 rustup update 3 4 # Check for updates 5 rustup check ``` New versions come every 6 weeks with improvements and bug fixes. ### 2. Install rust-analyzer (VS Code) [Section titled “2. Install rust-analyzer (VS Code)”](#2-install-rust-analyzer-vs-code) ```bash 1 # In VS Code, install extension: 2 # rust-lang.rust-analyzer 3 4 # Or from terminal: 5 code --install-extension rust-lang.rust-analyzer ``` **What it provides:** * Code completion * Inline errors * Go to definition * Refactoring tools * Inline type hints **Compare to TypeScript:** ```typescript 1 // TypeScript has built-in language server 2 // Rust needs rust-analyzer extension ``` ### 3. Configure Your Editor [Section titled “3. Configure Your Editor”](#3-configure-your-editor) **VS Code settings.json:** ```json 1 { 2 "[rust]": { 3 "editor.defaultFormatter": "rust-lang.rust-analyzer", 4 "editor.formatOnSave": true 5 }, 6 "rust-analyzer.checkOnSave": true, 7 "rust-analyzer.check.command": "clippy" 8 } ``` This enables: * Format on save (like Prettier) * Clippy linting on save (like ESLint) ### 4. Set Up Shell Completions [Section titled “4. Set Up Shell Completions”](#4-set-up-shell-completions) ```bash 1 # For bash 2 rustup completions bash >> ~/.bash_completion 3 4 # For zsh 5 rustup completions zsh > ~/.zfunc/_rustup 6 7 # For fish 8 rustup completions fish > ~/.config/fish/completions/rustup.fish ``` Now you can tab-complete Rust commands! *** ## Real-World Example: Complete Setup [Section titled “Real-World Example: Complete Setup”](#real-world-example-complete-setup) Here’s a complete setup script for a new machine: **macOS/Linux:** ```bash 1 #!/bin/bash 2 3 # 1. Install prerequisites 4 # macOS 5 xcode-select --install 6 7 # Linux (Ubuntu/Debian) 8 # sudo apt update && sudo apt install build-essential 9 10 # 2. Install Rust 11 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y 12 13 # 3. Source cargo env 14 source $HOME/.cargo/env 15 16 # 4. Verify installation 17 rustc --version 18 cargo --version 19 20 # 5. Install rust-analyzer (if using VS Code) 21 code --install-extension rust-lang.rust-analyzer 22 23 # 6. Configure VS Code 24 mkdir -p ~/.config/Code/User 25 cat > ~/.config/Code/User/settings.json << EOF 26 { 27 "[rust]": { 28 "editor.defaultFormatter": "rust-lang.rust-analyzer", 29 "editor.formatOnSave": true 30 } 31 } 32 EOF 33 34 echo "Rust installed successfully!" ``` **Compare to Node.js setup:** ```bash 1 #!/bin/bash 2 3 # 1. Install nvm 4 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash 5 6 # 2. Install Node.js (current LTS) 7 nvm install --lts 8 nvm use --lts 9 10 # 3. Install global tools 11 npm install -g typescript ts-node prettier eslint 12 13 # 4. Verify 14 node --version 15 npm --version 16 17 echo "Node.js installed successfully!" ``` *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [Rustup Book](https://rust-lang.github.io/rustup/) - Complete rustup guide * [Installation Page](https://www.rust-lang.org/tools/install) - Official installation guide * [Rust Forge](https://forge.rust-lang.org/) - Infrastructure documentation ### Editor Setup [Section titled “Editor Setup”](#editor-setup) * [rust-analyzer Manual](https://rust-analyzer.github.io/manual.html) - VS Code extension docs * [IntelliJ Rust](https://plugins.jetbrains.com/plugin/8182-rust) - For IntelliJ/CLion * [Vim Rust](https://github.com/rust-lang/rust.vim) - For Vim/Neovim ### Platform-Specific [Section titled “Platform-Specific”](#platform-specific) * [Windows Installation Guide](https://doc.rust-lang.org/book/ch01-01-installation.html#installing-rustup-on-windows) * [WSL2 Setup](https://docs.microsoft.com/en-us/windows/wsl/install) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Verify Your Installation [Section titled “Exercise 1: Verify Your Installation”](#exercise-1-verify-your-installation) Run these commands and verify the output: ```bash 1 # Should print version (1.96.0 or newer) 2 rustc --version 3 4 # Should print version 5 cargo --version 6 7 # Should print version 8 rustup --version 9 10 # Should list one toolchain (stable) 11 rustup toolchain list 12 13 # Should open documentation in browser 14 rustup doc 15 16 # Should print help text 17 cargo --help ``` ### Exercise 2: Update Rust [Section titled “Exercise 2: Update Rust”](#exercise-2-update-rust) ```bash 1 # Check for updates 2 rustup check 3 4 # Update all components 5 rustup update 6 7 # Verify new version 8 rustc --version ``` ### Exercise 3: Install Additional Components [Section titled “Exercise 3: Install Additional Components”](#exercise-3-install-additional-components) ```bash 1 # Install nightly (for experimental features) 2 rustup toolchain install nightly 3 4 # Install source code (for rust-analyzer) 5 rustup component add rust-src 6 7 # List installed components 8 rustup component list --installed ``` ### Exercise 4: Configure Your Editor [Section titled “Exercise 4: Configure Your Editor”](#exercise-4-configure-your-editor) 1. Install rust-analyzer for your editor 2. Create a test file: `test.rs` 3. Type: `fn main() {` 4. Verify that auto-completion works 5. Add a syntax error and verify that inline errors appear *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * How to install Rust using rustup * What tools come with Rust (rustc, cargo, rustfmt, clippy) * How to verify your installation * Common pitfalls and solutions * Best practices for editor setup **What you have now:** * Rust compiler (rustc) * Package manager (cargo) * Formatter (rustfmt) * Linter (clippy) * Documentation (rustup doc) * Version manager (rustup) **Compare to Node.js:** * Node.js requires separate tools (npm, prettier, eslint) * Rust includes everything in one install * Both use version managers (nvm/rustup) * Rust has offline documentation built-in **You’re ready to write Rust!** # Hello World in Rust > Your first Rust program! We'll create a classic "Hello World" and compare it to TypeScript/JavaScript. Your first Rust program! We’ll create a classic “Hello World” and compare it to TypeScript/JavaScript. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Rust programs start with a `main` function, just like many other languages. Unlike JavaScript, which is interpreted, Rust is compiled to a native executable. **Time required:** 15-20 minutes *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Let’s start with something familiar: hello.ts ```typescript 1 function main() { 2 console.log("Hello, world!"); 3 } 4 5 main(); ``` **Running it:** ```bash 1 # Option 1: With ts-node 2 ts-node hello.ts 3 4 # Option 2: Compile then run 5 tsc hello.ts # Creates hello.js 6 node hello.js # Runs the JS file ``` **What happens:** 1. TypeScript is transpiled to JavaScript 2. Node.js interprets the JavaScript 3. V8 JIT-compiles hot code paths 4. Output appears in terminal *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) hello.rs ```rust 1 fn main() { 2 println!("Hello, world!"); 3 } ``` **Running it:** ```bash 1 # Compile 2 rustc hello.rs # Creates executable 'hello' 3 4 # Run 5 ./hello # macOS/Linux 6 hello.exe # Windows ``` **What happens:** 1. Rust is compiled to native machine code 2. Linker creates standalone executable 3. No runtime or interpreter needed 4. Output appears in terminal *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Line-by-Line Comparison [Section titled “Line-by-Line Comparison”](#line-by-line-comparison) **TypeScript:** ```typescript 1 function main() { 2 // Function declaration 3 console.log("Hello, world!"); // Print to console 4 } 5 6 main(); // Call the function ``` **Rust:** ```rust 1 fn main() { // Function declaration 2 println!("Hello, world!"); // Print to console (with newline) 3 } 4 // main() is auto-called (entry point) ``` ### Key Syntax Differences [Section titled “Key Syntax Differences”](#key-syntax-differences) | Aspect | TypeScript | Rust | | ---------------- | --------------------------------------- | ----------------------------- | | Function keyword | `function` or `=>` | `fn` | | Print function | `console.log()` | `println!()` | | Statement end | `;` optional (ASI; most styles keep it) | `;` required | | Block style | `{` same line or next | `{` same line (idiomatic) | | Indentation | 2 spaces (common) | 4 spaces (standard) | | Entry point | Call `main()` explicitly | `main()` called automatically | | Macro syntax | None (no macros) | `!` indicates macro | ### The `println!` Macro [Section titled “The println! Macro”](#the-println-macro) Notice the `!` in `println!()`: ```rust 1 println!("Hello, world!"); // Macro (notice the !) ``` **What’s a macro?** * Code that writes code at compile time * Like a template that expands before compilation * `println!` is a macro, not a function **Why `!`?** * The `!` simply marks a **macro invocation** — it has nothing to do with format strings * Macros can do things functions can’t (e.g. accept a variable number of arguments and check the format string at compile time) * You’ll see it on `vec!`, `format!`, `assert!`, and many others **Compare to TypeScript:** ```typescript 1 // TypeScript has no macro system 2 // Closest equivalent: template literals 3 console.log(`Hello, world!`); ``` **Rust also has `print!` (without newline):** ```rust 1 print!("Hello, "); // No newline 2 print!("world!\n"); // Explicit newline ``` *** ## Multiple Ways to Create and Run [Section titled “Multiple Ways to Create and Run”](#multiple-ways-to-create-and-run) ### Method 1: Single File with rustc [Section titled “Method 1: Single File with rustc”](#method-1-single-file-with-rustc) **Create the file:** ```bash 1 # Create hello.rs 2 echo 'fn main() { 3 println!("Hello, world!"); 4 }' > hello.rs ``` **Compile and run:** ```bash 1 # Compile 2 rustc hello.rs 3 4 # Run 5 ./hello ``` **Pros:** * Simple and direct * No additional files needed * Good for learning **Cons:** * No dependency management * No standard project structure * Manual compilation **When to use:** Quick tests, learning exercises *** ### Method 2: Cargo Project (Recommended) [Section titled “Method 2: Cargo Project (Recommended)”](#method-2-cargo-project-recommended) **Create project:** ```bash 1 # Create new project 2 cargo new hello_world 3 cd hello_world ``` **This creates:** ```plaintext 1 hello_world/ 2 ├── Cargo.toml # Project manifest (like package.json) 3 └── src/ 4 └── main.rs # Your code (already has Hello World!) ``` **Run it:** ```bash 1 cargo run ``` **Output:** ```text 1 Compiling hello_world v0.1.0 (/path/to/hello_world) 2 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.16s 3 Running `target/debug/hello_world` 4 Hello, world! ``` **Pros:** * Standard project structure * Dependency management built-in * Automatic compilation * Testing framework included **Cons:** * Slightly more complex for tiny scripts **When to use:** Any real project (always use this!) **Compare to Node.js/TypeScript:** ```bash 1 # Node.js equivalent 2 npm init -y # Create package.json 3 npm install -D typescript @types/node 4 npx tsc --init # Create tsconfig.json 5 # Create src/index.ts 6 npm run dev # (after configuring package.json) ``` Cargo is simpler - one command! *** ### Method 3: Cargo Script (nightly-only, unstable) [Section titled “Method 3: Cargo Script (nightly-only, unstable)”](#method-3-cargo-script-nightly-only-unstable) > **Warning:** Single-file “cargo scripts” are an **unstable** feature. As of Rust 1.96.0 they only work on the **nightly** toolchain behind the `-Zscript` flag. On stable, `cargo` rejects an embedded manifest with `error: embedded manifest ... requires -Zscript`. When enabled, a script carries its dependencies in a `---` TOML **frontmatter** block at the top of the file (this is the real syntax — there is no `// cargo.toml` comment manifest): ```rust 1 #!/usr/bin/env -S cargo +nightly -Zscript 2 --- 3 [package] 4 edition = "2024" 5 --- 6 7 fn main() { 8 println!("Hello, world!"); 9 } ``` **Run directly:** ```bash 1 chmod +x hello.rs 2 ./hello.rs ``` **When to use:** Quick automation scripts — but only once you are on nightly and accept that the format may still change before it stabilizes. For anything real, prefer Method 2 (a Cargo project). *** ## Key Differences from TypeScript/JavaScript [Section titled “Key Differences from TypeScript/JavaScript”](#key-differences-from-typescriptjavascript) ### 1. Compilation [Section titled “1. Compilation”](#1-compilation) **TypeScript:** ```bash 1 tsc hello.ts # Transpiles to hello.js 2 node hello.js # Node.js interprets 3 4 # Size: hello.js is ~same size as hello.ts ``` **Rust:** ```bash 1 rustc hello.rs # Compiles to machine code 2 3 # Size: executable is larger (~400KB for "Hello World") 4 # But runs much faster and needs no runtime ``` **Why Rust binary is larger:** * Includes all dependencies statically * No runtime needed * Can be stripped for production **Strip symbols for smaller binary:** ```bash 1 strip hello # Removes debug symbols (roughly a 20-30% cut for a tiny binary) ``` ### 2. Startup Time [Section titled “2. Startup Time”](#2-startup-time) **TypeScript/Node.js:** ```bash 1 time node hello.js 2 # real 0m0.050s (50ms) ``` **Rust:** ```bash 1 time ./hello 2 # real 0m0.001s (1ms) ``` **Why:** Rust is native code, no runtime or interpreter startup. ### 3. Entry Point [Section titled “3. Entry Point”](#3-entry-point) **TypeScript:** ```typescript 1 // Must explicitly call main 2 function main() { 3 console.log("Hello!"); 4 } 5 6 main(); // ← Required! ``` **Rust:** ```rust 1 // main() is automatically called at program start 2 fn main() { 3 println!("Hello!"); 4 } 5 // No explicit call needed ``` ### 4. Print Statement [Section titled “4. Print Statement”](#4-print-statement) **TypeScript/JavaScript:** ```typescript 1 console.log("Hello"); // No newline is added 2 console.log("World"); // Separate line 3 4 // Output: 5 // Hello 6 // World ``` **Rust:** ```rust 1 println!("Hello"); // Newline added automatically 2 println!("World"); // Separate line 3 4 print!("Hello"); // No newline 5 print!(" World\n"); // Manual newline 6 7 // Both output: 8 // Hello 9 // World ``` *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting the `!` in println [Section titled “Pitfall 1: Forgetting the ! in println”](#pitfall-1-forgetting-the--in-println) **Wrong:** ```rust 1 fn main() { 2 println("Hello, world!"); // Error: expected function, found macro `println` 3 } ``` **Right:** ```rust 1 fn main() { 2 println!("Hello, world!"); // Correct: println! is a macro 3 } ``` **Error message:** ```text 1 error[E0423]: expected function, found macro `println` 2 --> hello.rs:2:5 3 | 4 2 | println("Hello, world!"); 5 | ^^^^^^^ not a function 6 | 7 help: use `!` to invoke the macro 8 | 9 2 | println!("Hello, world!"); 10 | + ``` **Why:** `println!` is a macro, not a function. The `!` is required. ### Pitfall 2: Missing Semicolon [Section titled “Pitfall 2: Missing Semicolon”](#pitfall-2-missing-semicolon) A missing `;` is only an error when another statement follows it (or when a non-`()` value would be silently discarded). A single trailing expression with no semicolon is fine — it just becomes the block’s return value. **Compiles and runs** (the trailing expression evaluates to `()`): ```rust 1 fn main() { 2 println!("Hello, world!") // OK as the last expression — no `;` needed 3 } ``` **Error** — the moment a second statement follows the un-terminated one: ```rust 1 fn main() { 2 println!("Hello, world!") // now this needs a `;` 3 println!("Again!"); 4 } ``` **Error message:** ```text 1 error: expected `;`, found `println` 2 --> hello.rs:2:30 3 | 4 2 | println!("Hello, world!") 5 | ^ help: add `;` here 6 3 | println!("Again!"); 7 | ------- unexpected token 8 9 error: aborting due to 1 previous error ``` **Why:** Unlike JavaScript (which inserts semicolons automatically), Rust uses `;` to separate statements. The safe habit is to end every statement with `;`; omit it only on a deliberate trailing expression. ### Pitfall 3: Wrong File Extension [Section titled “Pitfall 3: Wrong File Extension”](#pitfall-3-wrong-file-extension) **Wrong:** ```bash 1 # Creating hello.js or hello.txt 2 echo 'fn main() { ... }' > hello.js 3 rustc hello.js // Won't work well ``` **Right:** ```bash 1 # Use .rs extension 2 echo 'fn main() { ... }' > hello.rs 3 rustc hello.rs // ``` **Why:** While rustc might compile it, tooling (rust-analyzer, cargo) expects `.rs` files. ### Pitfall 4: Trying to Run the .rs File [Section titled “Pitfall 4: Trying to Run the .rs File”](#pitfall-4-trying-to-run-the-rs-file) **Wrong:** ```bash 1 ./hello.rs // Cannot execute text file ``` **Right:** ```bash 1 # Compile first 2 rustc hello.rs 3 4 # Then run the executable 5 ./hello // ``` **Why:** Rust is compiled, not interpreted. You run the compiled binary, not the source file. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Always Use Cargo for Projects [Section titled “1. Always Use Cargo for Projects”](#1-always-use-cargo-for-projects) ** Don’t:** ```bash 1 rustc my_app.rs 2 rustc module1.rs 3 rustc module2.rs 4 # Manual compilation is painful ``` ** Do:** ```bash 1 cargo new my_app 2 cd my_app 3 cargo run 4 # Cargo handles everything ``` ### 2. Use `cargo run` for Development [Section titled “2. Use cargo run for Development”](#2-use-cargo-run-for-development) **During development:** ```bash 1 cargo run # Debug build, fast compile ``` **For production:** ```bash 1 cargo build --release # Optimized build, slow compile, fast execution 2 ./target/release/hello_world ``` **Compare compile times:** ```bash 1 time cargo build # ~0.5s (debug) 2 time cargo build --release # ~3s (release, but executable is 10x faster) ``` ### 3. Format Your Code [Section titled “3. Format Your Code”](#3-format-your-code) ```bash 1 # Format a single file 2 rustfmt hello.rs 3 4 # Format entire project 5 cargo fmt 6 7 # Check without formatting 8 cargo fmt -- --check ``` **Rust standard style:** * 4-space indentation (not 2!) * Opening brace on same line * No trailing commas in single-line ### 4. Use `println!` for Debugging [Section titled “4. Use println! for Debugging”](#4-use-println-for-debugging) ```rust 1 fn main() { 2 let x = 42; 3 println!("The value is: {}", x); // Format with variables 4 println!("x = {x}"); // Shorter syntax (Rust 2021+) 5 println!("Multiple: {} and {}", x, 10); // Multiple values 6 } ``` **Compare to TypeScript:** ```typescript 1 const x = 42; 2 console.log("The value is:", x); // Comma-separated 3 console.log(`The value is: ${x}`); // Template literal ``` *** ## Real-World Example: Slightly More Complex Hello World [Section titled “Real-World Example: Slightly More Complex Hello World”](#real-world-example-slightly-more-complex-hello-world) Let’s make it more interesting: **TypeScript:** ```typescript 1 function greet(name: string): void { 2 console.log(`Hello, ${name}!`); 3 } 4 5 function main(): void { 6 const names = ["Alice", "Bob", "Charlie"]; 7 names.forEach((name) => greet(name)); 8 } 9 10 main(); ``` **Rust:** ```rust 1 fn greet(name: &str) { 2 println!("Hello, {}!", name); 3 } 4 5 fn main() { 6 let names = vec!["Alice", "Bob", "Charlie"]; 7 for name in names { 8 greet(name); 9 } 10 } ``` **Run it:** ```bash 1 # Save as greet.rs 2 rustc greet.rs 3 ./greet ``` **Output:** ```plaintext 1 Hello, Alice! 2 Hello, Bob! 3 Hello, Charlie! ``` **Key differences:** * `&str` is a string slice (we’ll learn this in section 02) * `vec![]` is a vector (like an array) * `for` loop instead of `.forEach()` * No `void` return type needed *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book - Hello World](https://doc.rust-lang.org/book/ch01-02-hello-world.html) * [println! macro docs](https://doc.rust-lang.org/std/macro.println.html) * [Macros in Rust](https://doc.rust-lang.org/book/ch19-06-macros.html) ### Related Topics [Section titled “Related Topics”](#related-topics) * [Cargo Book - Creating a New Project](https://doc.rust-lang.org/cargo/guide/creating-a-new-project.html) * [rustc Book](https://doc.rust-lang.org/rustc/) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Basic Hello World [Section titled “Exercise 1: Basic Hello World”](#exercise-1-basic-hello-world) Create and run a Hello World program using both methods: ```bash 1 # Method 1: rustc 2 echo 'fn main() { println!("Hello from rustc!"); }' > hello1.rs 3 rustc hello1.rs 4 ./hello1 5 6 # Method 2: cargo 7 cargo new hello2 8 cd hello2 9 cargo run ``` ### Exercise 2: Modify the Message [Section titled “Exercise 2: Modify the Message”](#exercise-2-modify-the-message) Change the program to print your name: ```rust 1 fn main() { 2 println!("Hello, !"); 3 } ``` ### Exercise 3: Multiple Prints [Section titled “Exercise 3: Multiple Prints”](#exercise-3-multiple-prints) Create a program that prints multiple lines: ```rust 1 fn main() { 2 println!("Line 1"); 3 println!("Line 2"); 4 println!("Line 3"); 5 } ``` ### Exercise 4: Print Without Newline [Section titled “Exercise 4: Print Without Newline”](#exercise-4-print-without-newline) Use `print!` to print on the same line: ```rust 1 fn main() { 2 print!("Hello, "); 3 print!("world!"); 4 println!(); // Add newline at end 5 } ``` ### Exercise 5: Format with Variables [Section titled “Exercise 5: Format with Variables”](#exercise-5-format-with-variables) ```rust 1 fn main() { 2 let name = "Rustacean"; 3 let age = 5; 4 println!("My name is {} and I am {} years old", name, age); 5 } ``` All Solutions All solutions are provided in the exercises above! Try modifying them and running with `cargo run`. *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * Basic Rust syntax (`fn main`, `println!`) * How to compile with `rustc` * How to create projects with `cargo` * Differences between `print!` and `println!` * Key differences from TypeScript/JavaScript **Key syntax:** ```rust 1 fn main() { // Entry point 2 println!("Text"); // Print with newline 3 println!("Value: {}", x); // Print with formatting 4 } ``` **Commands to remember:** ```bash 1 rustc file.rs # Compile single file 2 cargo new project # Create new project 3 cargo run # Build and run 4 cargo fmt # Format code ``` **You’re ready to learn Cargo in depth!** # Understanding Cargo > Cargo is Rust's build system and package manager. Think of it as npm, webpack, jest, prettier, and eslint all combined into one tool. Cargo is Rust’s build system and package manager. Think of it as npm, webpack, jest, prettier, and eslint all combined into one tool. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Cargo is **the** Rust tool. It handles: * Project creation * Dependency management * Building and compiling * Running tests * Generating documentation * Publishing packages * Running benchmarks * And much more! **Time required:** 30-40 minutes *** ## TypeScript/JavaScript Comparison [Section titled “TypeScript/JavaScript Comparison”](#typescriptjavascript-comparison) **Node.js ecosystem (multiple tools):** ```bash 1 # Package manager 2 npm init 3 npm install express 4 npm install -D typescript 5 6 # Build tool 7 npx webpack 8 9 # Test runner 10 npx jest 11 12 # Formatter 13 npx prettier --write . 14 15 # Linter 16 npx eslint . 17 18 # Documentation 19 npx typedoc ``` **Rust (one tool - Cargo):** ```bash 1 # All-in-one tool 2 cargo new my_project # Create project 3 cargo add axum # Add dependency 4 cargo build # Build 5 cargo test # Run tests 6 cargo fmt # Format code 7 cargo clippy # Lint 8 cargo doc # Generate docs ``` **Everything through one consistent interface!** *** ## Rust Equivalent: Creating a Project [Section titled “Rust Equivalent: Creating a Project”](#rust-equivalent-creating-a-project) **TypeScript/Node.js:** ```bash 1 # Create directory 2 mkdir my-project 3 cd my-project 4 5 # Initialize 6 npm init -y 7 8 # Install TypeScript 9 npm install -D typescript @types/node 10 11 # Create tsconfig.json 12 npx tsc --init 13 14 # Create src directory 15 mkdir src 16 echo 'console.log("Hello");' > src/index.ts 17 18 # Add scripts to package.json (manual) 19 # ... 20 21 # Run 22 npx ts-node src/index.ts ``` **Result:** `package.json`, `tsconfig.json`, `node_modules/`, `src/` **Rust:** ```bash 1 # Create project (one command!) 2 cargo new my-project 3 cd my-project 4 5 # Run 6 cargo run ``` **Result:** `Cargo.toml`, `src/main.rs`, ready to go! **That’s it!** No configuration needed, batteries included. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Project Structure [Section titled “Project Structure”](#project-structure) When you run `cargo new my_project`, you get: ```plaintext 1 my_project/ 2 ├── Cargo.toml # Project manifest (like package.json) 3 ├── .git/ # Git repository (auto-initialized) 4 ├── .gitignore # Ignores /target (just one line) 5 └── src/ 6 └── main.rs # Entry point (with Hello World) ``` **Compare to Node.js/TypeScript:** ```plaintext 1 my-project/ 2 ├── package.json # Project manifest 3 ├── tsconfig.json # TypeScript config 4 ├── .gitignore # Manual creation 5 ├── node_modules/ # Dependencies (can be huge!) 6 └── src/ 7 └── index.ts # Entry point (empty) ``` ### Cargo.toml vs package.json [Section titled “Cargo.toml vs package.json”](#cargotoml-vs-packagejson) **Cargo.toml (Rust):** ```toml 1 [package] 2 name = "my_project" 3 version = "0.1.0" 4 edition = "2024" 5 6 [dependencies] 7 # Dependencies go here ``` > **Note:** You don’t pick the `edition` yourself. `cargo new` writes the newest edition supported by your toolchain into `Cargo.toml` automatically — on a recent stable toolchain that is `"2024"` (the latest stable edition). Editions are opt-in language revisions; existing code keeps compiling because crates of different editions interoperate. **package.json (Node.js):** ```json 1 { 2 "name": "my-project", 3 "version": "0.1.0", 4 "main": "dist/index.js", 5 "scripts": { 6 "build": "tsc", 7 "start": "node dist/index.js", 8 "dev": "ts-node src/index.ts", 9 "test": "jest" 10 }, 11 "dependencies": {}, 12 "devDependencies": { 13 "typescript": "^5.0.0", 14 "@types/node": "^18.0.0" 15 } 16 } ``` **Key differences:** * Cargo.toml is simpler (TOML vs JSON) * No “scripts” section needed (cargo commands are standard) * No “main” field (uses `src/main.rs` or `src/lib.rs` by convention) * No devDependencies distinction (just `[dependencies]` and `[dev-dependencies]`) *** ## Essential Cargo Commands [Section titled “Essential Cargo Commands”](#essential-cargo-commands) ### 1. Project Creation [Section titled “1. Project Creation”](#1-project-creation) ```bash 1 # Create binary (executable) project 2 cargo new my_app 3 4 # Create library project 5 cargo new my_lib --lib ``` **Compare to npm:** ```bash 1 npm init -y # Creates package.json 2 # But doesn't create any code structure ``` ### 2. Building [Section titled “2. Building”](#2-building) ```bash 1 # Debug build (fast compile, slow runtime) 2 cargo build 3 4 # Release build (slow compile, fast runtime) 5 cargo build --release 6 7 # Check without building (faster) 8 cargo check ``` **Output locations:** * Debug: `target/debug/my_app` * Release: `target/release/my_app` **Compare to TypeScript:** ```bash 1 tsc # Compile to JavaScript 2 npx webpack # Bundle 3 npm run build # (custom script) ``` **Build times comparison:** ```plaintext 1 cargo build # 0.5s (debug) 2 cargo build --release # 3-10s (release, but 10x faster execution) 3 tsc # 0.1-1s (depends on project size) ``` ### 3. Running [Section titled “3. Running”](#3-running) ```bash 1 # Build and run (debug) 2 cargo run 3 4 # Build and run (release) 5 cargo run --release 6 7 # Run with arguments 8 cargo run -- arg1 arg2 ``` **The `--` separator** passes arguments to your program, not to cargo. ```bash 1 # These arguments go to cargo 2 cargo run --release 3 4 # These arguments go to your program 5 cargo run -- --help ``` **Compare to Node.js:** ```bash 1 node dist/index.js # Run compiled JS 2 npx ts-node src/index.ts # Run TS directly 3 npm start # (custom script) ``` ### 4. Testing [Section titled “4. Testing”](#4-testing) ```bash 1 # Run all tests 2 cargo test 3 4 # Run specific test 5 cargo test test_name 6 7 # Run tests with output 8 cargo test -- --nocapture ``` **Compare to JavaScript:** ```bash 1 npm test # (jest, vitest, etc.) 2 npm run test:watch ``` Cargo’s test runner is built-in, no configuration needed! ### 5. Dependencies [Section titled “5. Dependencies”](#5-dependencies) ```bash 1 # Add dependency 2 cargo add serde 3 4 # Add dev dependency 5 cargo add --dev criterion 6 7 # Add with specific version 8 cargo add serde --version 1.0 9 10 # Remove dependency 11 cargo remove serde 12 13 # Update dependencies 14 cargo update ``` **Compare to npm:** ```bash 1 npm install express 2 npm install -D jest 3 npm install express@4.18.0 4 npm uninstall express 5 npm update ``` > **Note:** `cargo add` is built into Cargo (since Cargo 1.62, June 2022) — no extra install needed. You may still see older tutorials say “run `cargo install cargo-edit` first”; that hasn’t been required for years. You can always edit `Cargo.toml` by hand instead if you prefer: ```toml 1 [dependencies] 2 serde = "1.0" ``` ### 6. Code Quality [Section titled “6. Code Quality”](#6-code-quality) ```bash 1 # Format code (like Prettier) 2 cargo fmt 3 4 # Check formatting without changing 5 cargo fmt -- --check 6 7 # Lint (like ESLint) 8 cargo clippy 9 10 # Lint with auto-fix suggestions 11 cargo clippy --fix ``` **Compare to JavaScript:** ```bash 1 npx prettier --write . 2 npx prettier --check . 3 npx eslint . 4 npx eslint --fix . ``` ### 7. Documentation [Section titled “7. Documentation”](#7-documentation) ```bash 1 # Build documentation 2 cargo doc 3 4 # Build and open in browser 5 cargo doc --open 6 7 # Include private items 8 cargo doc --document-private-items ``` **Compare to TypeScript:** ```bash 1 npx typedoc --out docs src/ ``` Cargo docs are generated from code comments: ````rust 1 /// Returns the sum of two numbers 2 /// 3 /// # Examples 4 /// 5 /// ``` 6 /// let result = add(2, 3); 7 /// assert_eq!(result, 5); 8 /// ``` 9 pub fn add(a: i32, b: i32) -> i32 { 10 a + b 11 } ```` **`cargo doc`** automatically generates beautiful HTML documentation! *** ## Key Differences from npm [Section titled “Key Differences from npm”](#key-differences-from-npm) ### 1. No node\_modules! [Section titled “1. No node\_modules!”](#1-no-node_modules) **Node.js:** ```bash 1 npm install 2 # Creates node_modules/ (can be gigabytes!) 3 # Need to .gitignore it 4 # Re-download for every project ``` **Rust:** ```bash 1 cargo build 2 # Downloads to ~/.cargo/registry/ (shared across projects) 3 # Only compiled artifacts in target/ 4 # Reused across projects ``` **Why it matters:** * Faster builds (shared cache) * Less disk space * Faster git operations (no node\_modules to scan) ### 2. Lock Files [Section titled “2. Lock Files”](#2-lock-files) **package-lock.json (npm):** ```json 1 { 2 "name": "my-project", 3 "lockfileVersion": 3, 4 "requires": true, 5 "packages": { 6 "": { 7 // ... hundreds of lines ... 8 } 9 } 10 } ``` * Always commit to git * Ensures reproducible builds * Can be huge (thousands of lines) **Cargo.lock (Rust):** ```toml 1 # This file is automatically @generated by Cargo. 2 # It is not intended for manual editing. 3 [[package]] 4 name = "my_project" 5 version = "0.1.0" 6 7 [[package]] 8 name = "serde" 9 version = "1.0.152" ``` * Commit for binaries, don’t commit for libraries * Ensures reproducible builds * Usually smaller ### 3. Scripts [Section titled “3. Scripts”](#3-scripts) **package.json:** ```json 1 { 2 "scripts": { 3 "build": "tsc", 4 "start": "node dist/index.js", 5 "dev": "ts-node src/index.ts", 6 "test": "jest", 7 "lint": "eslint .", 8 "format": "prettier --write ." 9 } 10 } ``` **Cargo:** No scripts needed! Everything is a standard command: ```bash 1 cargo build # Standard 2 cargo run # Standard 3 cargo test # Standard 4 cargo fmt # Standard 5 cargo clippy # Standard ``` **For custom tasks** (the equivalent of npm `scripts`), Cargo has a couple of native options and several community tools: * **Cargo aliases** — define command shortcuts in `.cargo/config.toml`: .cargo/config.toml ```toml 1 [alias] 2 br = "build --release" ``` Then `cargo br` runs `cargo build --release`. Aliases only chain Cargo subcommands, not arbitrary shell. * **`cargo xtask`** — a convention where build automation lives in an ordinary Rust binary you run with `cargo xtask `. * **`cargo-make`** — a third-party task runner (`cargo install cargo-make`) for richer, cross-platform task definitions. > **Note:** Unlike npm, Cargo has no built-in `scripts` table that runs shell commands. But most projects don’t need one — the standard subcommands cover the common workflow. ### 4. Semantic Versioning [Section titled “4. Semantic Versioning”](#4-semantic-versioning) **Both** use semver, but Cargo enforces it more strictly: **Cargo.toml:** ```toml 1 [dependencies] 2 serde = "1.0" # Caret range: >=1.0.0, <2.0.0 3 tokio = "1.25.0" # ALSO a caret range: >=1.25.0, <2.0.0 (NOT exact!) 4 tokio_exact = "=1.25.0" # THIS is exact: only 1.25.0 5 regex = "1" # Caret range: >=1.0.0, <2.0.0 ``` > **Warning:** A bare version string like `"1.25.0"` is **not** an exact pin — Cargo treats it as the caret requirement `>=1.25.0, <2.0.0`. To require an exact version, prefix it with `=`, as in `"=1.25.0"`. **package.json:** ```json 1 { 2 "dependencies": { 3 "express": "^4.18.0", // 4.18.0 <= version < 5.0.0 4 "lodash": "4.17.21", // Exact 5 "react": "^18" // Latest 18.x 6 } 7 } ``` **Cargo is more conservative** with updates by default. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting to Rebuild [Section titled “Pitfall 1: Forgetting to Rebuild”](#pitfall-1-forgetting-to-rebuild) **Problem:** ```bash 1 # Edit main.rs 2 # Run old binary 3 ./target/debug/my_app # Runs OLD version! ``` **Solution:** ```bash 1 cargo run # Always rebuilds if needed ``` **Or:** ```bash 1 cargo build 2 ./target/debug/my_app # Now runs new version ``` ### Pitfall 2: Large target/ Directory [Section titled “Pitfall 2: Large target/ Directory”](#pitfall-2-large-target-directory) **Problem:** ```bash 1 du -sh target/ 2 # 5.0G target/ # Huge! ``` **Solution:** ```bash 1 # Clean build artifacts 2 cargo clean 3 4 # Or clean all Rust projects 5 cargo install cargo-cache 6 cargo cache --autoclean ``` **Why it gets big:** * Multiple debug/release builds * Dependencies compiled for your project * Test binaries **Compare to node\_modules:** ```bash 1 du -sh node_modules/ 2 # 500M node_modules/ # Also huge! ``` But `target/` can be cleaned and regenerated quickly. ### Pitfall 3: Slow First Build [Section titled “Pitfall 3: Slow First Build”](#pitfall-3-slow-first-build) **Problem:** ```bash 1 cargo build 2 # Compiling 150 crates... (takes 5 minutes) ``` **Why:** Cargo compiles all dependencies from source. **Solutions:** 1. **Use `cargo check` during development:** ```bash 1 cargo check # Faster, just type-checks ``` 2. **Use release mode only when needed:** ```bash 1 cargo build # Debug mode (fast compile) 2 # Only use --release for production ``` 3. **Use `sccache` for caching:** ```bash 1 cargo install sccache 2 export RUSTC_WRAPPER=sccache ``` ### Pitfall 4: Committing Cargo.lock (or not) [Section titled “Pitfall 4: Committing Cargo.lock (or not)”](#pitfall-4-committing-cargolock-or-not) **Rule:** * **Binary projects:** Commit `Cargo.lock` * **Library projects:** Don’t commit `Cargo.lock` **Why:** * Binaries need reproducible builds * Libraries want to test with latest compatible versions **Add to .gitignore (for libraries):** ```text 1 /target/ 2 /Cargo.lock ``` *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Use cargo fmt on Save [Section titled “1. Use cargo fmt on Save”](#1-use-cargo-fmt-on-save) **VS Code settings.json:** ```json 1 { 2 "[rust]": { 3 "editor.formatOnSave": true 4 } 5 } ``` **Or manually:** ```bash 1 cargo fmt ``` **Before commit:** ```bash 1 cargo fmt --check # Verify formatting ``` ### 2. Run clippy Before Commit [Section titled “2. Run clippy Before Commit”](#2-run-clippy-before-commit) ```bash 1 cargo clippy ``` **Or make it strict:** ```bash 1 cargo clippy -- -D warnings # Treat warnings as errors ``` **CI integration:** .github/workflows/ci.yml ```yaml 1 - name: Run clippy 2 run: cargo clippy -- -D warnings ``` ### 3. Use cargo check During Development [Section titled “3. Use cargo check During Development”](#3-use-cargo-check-during-development) **Instead of:** ```bash 1 cargo build # Slow: creates executable ``` **Use:** ```bash 1 cargo check # Fast: only type-checks ``` **3-5x faster!** Use during development, `cargo build` only when you need to run. ### 4. Separate Dev and Prod Dependencies [Section titled “4. Separate Dev and Prod Dependencies”](#4-separate-dev-and-prod-dependencies) ```toml 1 [dependencies] 2 # Production dependencies 3 serde = "1.0" 4 tokio = "1.25" 5 6 [dev-dependencies] 7 # Only used in tests/benchmarks 8 criterion = "0.5" 9 mock_instant = "0.3" ``` **Compare to package.json:** ```json 1 { 2 "dependencies": { 3 /* prod */ 4 }, 5 "devDependencies": { 6 /* dev only */ 7 } 8 } ``` ### 5. Use Workspaces for Monorepos [Section titled “5. Use Workspaces for Monorepos”](#5-use-workspaces-for-monorepos) ```plaintext 1 my-workspace/ 2 ├── Cargo.toml # Workspace manifest 3 ├── api/ 4 │ ├── Cargo.toml 5 │ └── src/ 6 ├── cli/ 7 │ ├── Cargo.toml 8 │ └── src/ 9 └── shared/ 10 ├── Cargo.toml 11 └── src/ ``` **Root Cargo.toml:** ```toml 1 [workspace] 2 members = ["api", "cli", "shared"] ``` **Compare to npm workspaces:** ```json 1 { 2 "workspaces": ["packages/*"] 3 } ``` Similar concept, different implementation. *** ## Real-World Example: Web API Project [Section titled “Real-World Example: Web API Project”](#real-world-example-web-api-project) **Create project:** ```bash 1 cargo new web_api 2 cd web_api ``` **Add dependencies:** ```bash 1 cargo add axum 2 cargo add tokio --features full 3 cargo add serde --features derive ``` **Or manually edit Cargo.toml:** ```toml 1 [package] 2 name = "web_api" 3 version = "0.1.0" 4 edition = "2024" 5 6 [dependencies] 7 axum = "0.8" 8 tokio = { version = "1", features = ["full"] } 9 serde = { version = "1.0", features = ["derive"] } 10 11 [profile.release] 12 opt-level = 3 # Maximum optimization 13 lto = true # Link-time optimization 14 codegen-units = 1 # Better optimization, slower compile ``` **Build and run:** ```bash 1 # Development 2 cargo run 3 4 # Production 5 cargo build --release 6 ./target/release/web_api ``` **Compare to Node.js/Express:** ```bash 1 npm init -y 2 npm install express typescript @types/node @types/express 3 npm install -D ts-node nodemon 4 # Edit tsconfig.json 5 # Edit package.json scripts 6 npm run dev ``` Cargo is simpler! *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Cargo Book](https://doc.rust-lang.org/cargo/) - Complete guide * [Cargo Commands Reference](https://doc.rust-lang.org/cargo/commands/index.html) * [Manifest Format (Cargo.toml)](https://doc.rust-lang.org/cargo/reference/manifest.html) ### Useful Tools [Section titled “Useful Tools”](#useful-tools) * [cargo-edit](https://github.com/killercup/cargo-edit) - `cargo upgrade`, `cargo set-version` (`cargo add`/`cargo remove` are now built into Cargo) * [cargo-watch](https://github.com/watchexec/cargo-watch) - Auto-rebuild on file change * [cargo-expand](https://github.com/dtolnay/cargo-expand) - Expand macros * [cargo-tree](https://doc.rust-lang.org/cargo/commands/cargo-tree.html) - View dependency tree (built-in) ### Comparisons [Section titled “Comparisons”](#comparisons) * [Cargo vs npm](https://www.reddit.com/r/rust/comments/3x4c2h/cargo_vs_npm/) * [Cargo for npm users](https://github.com/Mercateo/rust-for-node-developers/blob/master/Cargo-for-npm-users.md) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Create and Run a Project [Section titled “Exercise 1: Create and Run a Project”](#exercise-1-create-and-run-a-project) ```bash 1 cargo new hello_cargo 2 cd hello_cargo 3 cargo run ``` ### Exercise 2: Add a Dependency [Section titled “Exercise 2: Add a Dependency”](#exercise-2-add-a-dependency) Add the `rand` crate and use it: **Cargo.toml:** ```toml 1 [dependencies] 2 rand = "0.9" ``` **src/main.rs:** ```rust 1 use rand::Rng; 2 3 fn main() { 4 let random_number = rand::rng().random_range(1..=100); 5 println!("Random number: {random_number}"); 6 } ``` > **Note:** rand 0.9 renamed the old `thread_rng()` to `rng()` and `gen_range()` to `random_range()` (because `gen` became a reserved keyword in edition 2024). If you follow a rand 0.8 tutorial, those are the two calls to update. **Run:** ```bash 1 cargo run ``` ### Exercise 3: Explore cargo Commands [Section titled “Exercise 3: Explore cargo Commands”](#exercise-3-explore-cargo-commands) ```bash 1 cargo build # Build 2 cargo clean # Clean 3 cargo doc --open # Generate and open docs 4 cargo tree # Show dependency tree 5 cargo --version # Show version 6 cargo --list # List all commands ``` ### Exercise 4: Create a Library [Section titled “Exercise 4: Create a Library”](#exercise-4-create-a-library) ```bash 1 cargo new my_lib --lib 2 cd my_lib ``` **src/lib.rs:** ```rust 1 pub fn add(a: i32, b: i32) -> i32 { 2 a + b 3 } 4 5 #[cfg(test)] 6 mod tests { 7 use super::*; 8 9 #[test] 10 fn test_add() { 11 assert_eq!(add(2, 3), 5); 12 } 13 } ``` **Run tests:** ```bash 1 cargo test ``` ### Exercise 5: Format and Lint [Section titled “Exercise 5: Format and Lint”](#exercise-5-format-and-lint) ```bash 1 # Format code 2 cargo fmt 3 4 # Check formatting 5 cargo fmt --check 6 7 # Lint 8 cargo clippy ``` *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * Cargo is the all-in-one Rust tool * How to create projects (`cargo new`) * How to build and run (`cargo build`, `cargo run`) * How to manage dependencies (edit `Cargo.toml`) * How to test, format, and lint * Key differences from npm **Essential commands:** ```bash 1 cargo new # Create project 2 cargo run # Build and run 3 cargo test # Run tests 4 cargo fmt # Format code 5 cargo clippy # Lint 6 cargo doc --open # Generate docs 7 cargo clean # Clean build artifacts ``` **Cargo.toml structure:** ```toml 1 [package] 2 name = "my_project" 3 version = "0.1.0" 4 edition = "2024" # cargo new fills in the newest edition for you 5 6 [dependencies] 7 # Add dependencies here ``` **You now understand Rust’s tooling!** # Rust Playground > Try Rust in your browser without installing anything! The Rust Playground is an online tool for experimenting, learning, and sharing code. Try Rust in your browser without installing anything! The Rust Playground is an online tool for experimenting, learning, and sharing code. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) The Rust Playground ([play.rust-lang.org](https://play.rust-lang.org/)) lets you write Rust code in your browser and compile/run it on Rust’s servers (in a sandbox, not in the browser itself). It’s perfect for: * Quick experiments * Learning Rust * Sharing code snippets * Testing ideas **Time required:** 10-15 minutes to explore *** ## TypeScript/JavaScript Comparison [Section titled “TypeScript/JavaScript Comparison”](#typescriptjavascript-comparison) **TypeScript Playground:** * [TypeScript Playground](https://www.typescriptlang.org/play) * Transpiles TypeScript to JavaScript * Shows type errors * Browser-based **Rust Playground:** * [Rust Playground](https://play.rust-lang.org/) * Compiles and runs your code on Rust’s servers in a sandbox (not in your browser) * Shows compiler errors * Can switch between editions * Can run tests * Can format code * Can share via URL **Similar tools:** * [CodeSandbox](https://codesandbox.io/) - Full dev environment * [StackBlitz](https://stackblitz.com/) - Online VS Code * [Replit](https://replit.com/) - Multi-language online IDE *** ## Accessing the Playground [Section titled “Accessing the Playground”](#accessing-the-playground) **URL:** **When you open it, you see:** ```rust 1 fn main() { 2 println!("Hello, world!"); 3 } ``` **Ready to run immediately!** Click “Run” or press `Ctrl+Enter`. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Main Features [Section titled “Main Features”](#main-features) #### 1. Code Editor [Section titled “1. Code Editor”](#1-code-editor) * Syntax highlighting * Auto-completion * Error underlining (as you type!) * Multi-cursor editing (`Ctrl+Click`) **Try this:** ```rust 1 fn main() { 2 let x = 5; 3 println!("x = {}", x); 4 } ``` #### 2. Compiler Output [Section titled “2. Compiler Output”](#2-compiler-output) **Click “Run”** and see: ```plaintext 1 Compiling playground v0.0.1 (/playground) 2 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.50s 3 Running `target/debug/playground` 4 x = 5 ``` * Shows compilation steps * Shows program output * Shows any errors or warnings #### 3. Share Button [Section titled “3. Share Button”](#3-share-button) **Create shareable link:** 1. Write your code 2. Click “Share” 3. Copy the URL 4. Anyone with the URL can see and run your code **Example URL:** ```plaintext 1 https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&gist=abc123xyz ``` **Compare to TypeScript Playground:** * TypeScript encodes code in URL * Rust uses gist (cleaner URLs) #### 4. Configuration Options [Section titled “4. Configuration Options”](#4-configuration-options) **Edition:** * 2015 (original Rust) * 2018 (modern features) * 2021 (widely used) * 2024 (latest stable edition, recommended for new code) **Mode:** * Debug (fast compile, slow runtime) * Release (slow compile, fast runtime) **Channel:** * Stable (most recent release) * Beta (next release preview) * Nightly (latest features, unstable) ### Top Toolbar [Section titled “Top Toolbar”](#top-toolbar) ```plaintext 1 [Run ▶] [Format] [Clippy] [Miri] [Tools ▼] [Config ▼] [Share] [Help] ``` **Run** - Compile and execute **Format** - Auto-format code (like `cargo fmt`) **Clippy** - Lint code (like `cargo clippy`) **Miri** - Advanced interpreter (for unsafe code) **Tools** - ASM, LLVM IR, MIR, macro expansion, etc. **Config** - Edition, mode, channel **Share** - Get shareable link **Help** - Keyboard shortcuts > **Note:** The exact button labels and grouping shift between Playground versions. The capabilities below are stable even if the menu names change. *** ## Key Differences from TypeScript Playground [Section titled “Key Differences from TypeScript Playground”](#key-differences-from-typescript-playground) ### 1. Actual Compilation [Section titled “1. Actual Compilation”](#1-actual-compilation) **TypeScript Playground:** ```typescript 1 let x = 5; 2 console.log(x); 3 // Transpiled to JavaScript, runs in browser JS engine ``` **Rust Playground:** ```rust 1 let x = 5; 2 println!("{}", x); 3 // Sent to Rust's servers, compiled to a native binary, run in a sandbox ``` > **Note:** Unlike the TypeScript Playground (which transpiles and runs entirely in your browser), the Rust Playground sends your code to a backend, compiles it with a real `rustc`/`cargo` toolchain, and runs the resulting native binary in a sandboxed container. That’s why it needs a moment to respond and why it can report genuine compile and runtime errors. **Why it matters:** Rust Playground shows real compile errors, not just type errors. ### 2. More Tool Integration [Section titled “2. More Tool Integration”](#2-more-tool-integration) **TypeScript:** * Basic editor * Type checking * JS output **Rust:** * Editor with completions * Compiler errors/warnings * Format code * Lint code * View assembly * Run tests * View macro expansions ### 3. Shareable Builds [Section titled “3. Shareable Builds”](#3-shareable-builds) **Rust Playground can share:** * Source code * Compiler output * Standard output * Entire configuration **Perfect for:** * Asking questions on forums * Reporting bugs * Teaching examples *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Expecting File System Access [Section titled “Pitfall 1: Expecting File System Access”](#pitfall-1-expecting-file-system-access) **Problem:** ```rust 1 use std::fs; 2 3 fn main() { 4 let content = fs::read_to_string("file.txt").unwrap(); 5 println!("{}", content); 6 } ``` **Error:** ```plaintext 1 No such file or directory (os error 2) ``` **Why:** The playground is sandboxed, no file system access. **Solution:** Use string literals instead: ```rust 1 fn main() { 2 let content = "This is my file content"; 3 println!("{}", content); 4 } ``` ### Pitfall 2: Network Requests Don’t Work [Section titled “Pitfall 2: Network Requests Don’t Work”](#pitfall-2-network-requests-dont-work) **Problem:** ```rust 1 // This won't work! 2 let response = reqwest::get("https://api.example.com").await?; ``` **Why:** No network access in the playground. **Solution:** For network code, install Rust locally. ### Pitfall 3: Limited Dependencies [Section titled “Pitfall 3: Limited Dependencies”](#pitfall-3-limited-dependencies) **Problem:** ```rust 1 use some_obscure_crate::Thing; // Not available ``` **Why:** Playground has only the top 100 crates. **Available crates:** * Standard library (always) * Popular crates (serde, tokio, regex, etc.) **To check if a crate is available:** Look for the “ADD CRATE” button (shows available crates). ### Pitfall 4: Execution Time Limit [Section titled “Pitfall 4: Execution Time Limit”](#pitfall-4-execution-time-limit) **Problem:** ```rust 1 fn main() { 2 loop { 3 // Infinite loop 4 } 5 } ``` **Result:** Timeout after 30 seconds. **Solution:** Write code that completes quickly. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Use for Quick Tests [Section titled “1. Use for Quick Tests”](#1-use-for-quick-tests) **Good use:** ```rust 1 // Test how Option works 2 fn main() { 3 let x: Option = Some(5); 4 match x { 5 Some(val) => println!("Value: {}", val), 6 None => println!("No value"), 7 } 8 } ``` Quick test, immediate feedback! ### 2. Format Before Sharing [Section titled “2. Format Before Sharing”](#2-format-before-sharing) **Always click “Format”** before sharing code: * Makes code readable * Follows Rust conventions * Professional appearance ### 3. Use Clippy for Learning [Section titled “3. Use Clippy for Learning”](#3-use-clippy-for-learning) **Click “Clippy”** to get suggestions. Clippy goes beyond compiler errors and flags non-idiomatic code: ```rust 1 fn main() { 2 let s = String::from("hello"); 3 if s.len() == 0 { 4 println!("empty"); 5 } 6 } ``` **Clippy reports:** ```plaintext 1 warning: length comparison to zero 2 --> src/main.rs:3:8 3 | 4 3 | if s.len() == 0 { 5 | ^^^^^^^^^^^^ help: using `is_empty` is clearer and more explicit: `s.is_empty()` 6 | 7 = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#len_zero 8 = note: `#[warn(clippy::len_zero)]` on by default ``` **Learn from suggestions!** ### 4. Share Examples in Forums [Section titled “4. Share Examples in Forums”](#4-share-examples-in-forums) When asking for help: 1. Write minimal example in playground 2. Click “Share” 3. Post the link **Example:** “I’m having trouble with this: ” Much better than pasting code in a forum post! *** ## Real-World Example: Testing an Idea [Section titled “Real-World Example: Testing an Idea”](#real-world-example-testing-an-idea) **Scenario:** You want to test how Rust’s `Result` type works. **1. Go to playground** **2. Write code:** ```rust 1 fn divide(a: i32, b: i32) -> Result { 2 if b == 0 { 3 Err("Cannot divide by zero".to_string()) 4 } else { 5 Ok(a / b) 6 } 7 } 8 9 fn main() { 10 match divide(10, 2) { 11 Ok(result) => println!("Result: {}", result), 12 Err(e) => println!("Error: {}", e), 13 } 14 15 match divide(10, 0) { 16 Ok(result) => println!("Result: {}", result), 17 Err(e) => println!("Error: {}", e), 18 } 19 } ``` **3. Click “Run”** **Output:** ```plaintext 1 Result: 5 2 Error: Cannot divide by zero ``` **4. Click “Format”** to clean up **5. Click “Clippy”** for suggestions **6. Click “Share”** if you want to save it *** ## Advanced Features [Section titled “Advanced Features”](#advanced-features) ### 1. View Assembly [Section titled “1. View Assembly”](#1-view-assembly) Open the tools/options menu and choose to show the assembly output. See the actual machine code generated (x86-64, the Playground’s target): ```rust 1 pub fn add(a: i32, b: i32) -> i32 { 2 a + b 3 } ``` **Assembly output:** ```asm 1 playground::add: 2 lea eax, [rdi + rsi] 3 ret ``` **Why useful:** Understanding optimization. ### 2. View Macro Expansion [Section titled “2. View Macro Expansion”](#2-view-macro-expansion) Open the tools/options menu and choose to expand macros (this uses the nightly toolchain). See what macros expand to: ```rust 1 fn main() { 2 println!("Hello, {}", "world"); 3 } ``` **Expanded:** ```rust 1 fn main() { 2 { 3 ::std::io::_print(format_args!("Hello, {0}\n", "world")); 4 }; 5 } ``` **Why useful:** Understanding how macros work. ### 3. Run Tests [Section titled “3. Run Tests”](#3-run-tests) ```rust 1 fn add(a: i32, b: i32) -> i32 { 2 a + b 3 } 4 5 #[test] 6 fn test_add() { 7 assert_eq!(add(2, 3), 5); 8 } 9 10 #[test] 11 fn test_add_negative() { 12 assert_eq!(add(-1, 1), 0); 13 } ``` **Click “Test”** instead of “Run”: ```plaintext 1 running 2 tests 2 test test_add ... ok 3 test test_add_negative ... ok 4 5 test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out ``` *** ## Keyboard Shortcuts [Section titled “Keyboard Shortcuts”](#keyboard-shortcuts) The most reliable shortcut is `Ctrl+Enter` (run the code). The editor also supports many of the usual code-editor bindings for commenting, moving lines, multi-cursor editing, and find/replace. | Shortcut | Action (typical) | | --------------- | ---------------------- | | `Ctrl+Enter` | Run code | | `Ctrl+K Ctrl+C` | Comment selection | | `Ctrl+K Ctrl+U` | Uncomment selection | | `Ctrl+/` | Toggle comment | | `Alt+↑/↓` | Move line up/down | | `Ctrl+D` | Select next occurrence | | `Ctrl+F` | Find | | `Ctrl+H` | Find and replace | > **Note:** Editor bindings can differ by browser, platform, and Playground version, so treat the table above as a guide rather than a guarantee. Formatting and Clippy are run from their toolbar buttons. For the current authoritative list, click “Help” in the toolbar. *** ## Comparison to Local Development [Section titled “Comparison to Local Development”](#comparison-to-local-development) | Feature | Playground | Local (cargo) | | -------------------- | --------------- | ------------------------- | | Installation | None needed | rustup install | | Startup time | Instant | cargo run \~0.5s | | File system access | No | Yes | | Network access | No | Yes | | Available crates | Top 100 only | All crates | | Execution time limit | 30 seconds | No limit | | Code sharing | Easy (URL) | Manual (gist, github) | | Editor features | Basic | Full (with rust-analyzer) | | Debugging | Limited | Full (lldb/gdb) | | Performance | Slightly slower | Full native speed | **When to use Playground:** * Learning basics * Quick tests * Sharing examples * No installation needed **When to use local:** * Real projects * Need file system * Need specific crates * Performance testing *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Resources [Section titled “Official Resources”](#official-resources) * [Rust Playground](https://play.rust-lang.org/) * [Playground Repository](https://github.com/rust-lang/rust-playground) * [Available Crates List](https://play.rust-lang.org/help) ### Similar Tools [Section titled “Similar Tools”](#similar-tools) * [Godbolt Compiler Explorer](https://godbolt.org/z/Rust) - View assembly * [Rust Explorer](https://www.rustexplorer.com/) - Another online IDE ### Community [Section titled “Community”](#community) * Share playground links on [r/rust](https://reddit.com/r/rust) * Use in [Rust Discord](https://discord.gg/rust-lang) * Reference in GitHub issues *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Hello Playground [Section titled “Exercise 1: Hello Playground”](#exercise-1-hello-playground) 1. Go to 2. Modify the default program 3. Click “Run” 4. Click “Format” 5. Click “Share” and copy the URL ### Exercise 2: Test Compiler Errors [Section titled “Exercise 2: Test Compiler Errors”](#exercise-2-test-compiler-errors) Try this code: ```rust 1 fn main() { 2 let x = 5; 3 x = 10; // Error! 4 println!("{}", x); 5 } ``` Read the error message. What does it say? Answer ```plaintext 1 error[E0384]: cannot assign twice to immutable variable `x` ``` Variables are immutable by default in Rust! **Fix:** ```rust 1 fn main() { 2 let mut x = 5; // Add 'mut' 3 x = 10; 4 println!("{}", x); 5 } ``` ### Exercise 3: Use Clippy [Section titled “Exercise 3: Use Clippy”](#exercise-3-use-clippy) Write this code: ```rust 1 fn main() { 2 let s = String::from("hello"); 3 let len = s.len(); 4 println!("{}", len); 5 } ``` Click “Clippy”. Does it suggest anything? ### Exercise 4: Format Messy Code [Section titled “Exercise 4: Format Messy Code”](#exercise-4-format-messy-code) Paste this: ```rust 1 fn main(){let x=5;let y=10;println!("{} {}",x,y);} ``` Click “Format”. See the difference! ### Exercise 5: Share Your Code [Section titled “Exercise 5: Share Your Code”](#exercise-5-share-your-code) 1. Write any Rust code 2. Click “Share” 3. Open the link in a private/incognito window 4. Verify your code is there! *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * How to use the Rust Playground * When to use it vs local development * How to share code via URL * Available tools (Format, Clippy, etc.) * Limitations (no file system, network) **Rust Playground features:** * Instant code execution * Compiler error messages * Format and lint tools * Easy sharing * No installation needed **Best for:** * Learning Rust * Quick experiments * Sharing examples * Teaching **Not suitable for:** * Real projects * File I/O * Network requests * Large dependencies **URL to remember:** **You’re now ready to start learning Rust syntax!** # Rust Basics > Learn the fundamental building blocks of Rust: variables, types, operators, and basic syntax. Learn the fundamental building blocks of Rust: variables, types, operators, and basic syntax. *** ## What’s in This Section [Section titled “What’s in This Section”](#whats-in-this-section) * **[Variables and Mutability](/02-basics/00-variables/)** - let, mut, shadowing, constants * **[Basic Types](/02-basics/01-types/)** - Integers, floats, booleans, characters, tuples * **[Operators](/02-basics/02-operators/)** - Arithmetic, comparison, logical, and more * **[Comments](/02-basics/03-comments/)** - Code comments and documentation * **[Output and Formatting](/02-basics/04-output/)** - println!, print!, formatting *** ## Learning Objectives [Section titled “Learning Objectives”](#learning-objectives) By the end of this section, you will: * Understand Rust’s immutability-by-default philosophy * Know all basic data types and when to use them * Use type annotations and type inference * Perform arithmetic and logical operations * Write clear comments and documentation * Format output with println! macro *** ## Time Estimate [Section titled “Time Estimate”](#time-estimate) * **Reading:** 60-90 minutes * **Hands-on Practice:** 45-60 minutes * **Exercises:** 30-45 minutes * **Total:** 2.5-3 hours *** ## Quick Start Path [Section titled “Quick Start Path”](#quick-start-path) If you want to jump right in: 1. **[Variables](/02-basics/00-variables/)** (20 min) - Most important! 2. **[Types](/02-basics/01-types/)** (20 min) 3. **[Output](/02-basics/04-output/)** (15 min) 4. Skip to exercises Then come back for operators and comments. *** ## Detailed Learning Path [Section titled “Detailed Learning Path”](#detailed-learning-path) ### Recommended Order [Section titled “Recommended Order”](#recommended-order) ```plaintext 1 1. Variables and Mutability (the big difference!) 2 ↓ 3 2. Basic Types (integers, floats, etc.) 4 ↓ 5 3. Operators (arithmetic, comparison) 6 ↓ 7 4. Comments (documentation) 8 ↓ 9 5. Output and Formatting (println!) ``` All topics are interconnected, sequential reading recommended. *** ## What You’ll Learn [Section titled “What You’ll Learn”](#what-youll-learn) ### Variables: Immutable by Default [Section titled “Variables: Immutable by Default”](#variables-immutable-by-default) The **biggest** difference from TypeScript/JavaScript: **TypeScript:** ```typescript 1 let x = 5; // mutable 2 x = 6; // OK ``` **Rust:** ```rust 1 let x = 5; // immutable by default! 2 x = 6; // Compile error! 3 4 let mut y = 5; // explicitly mutable 5 y = 6; // OK ``` **Key insight:** Rust makes you think about mutability upfront. ### Rich Type System [Section titled “Rich Type System”](#rich-type-system) **TypeScript:** ```typescript 1 let x: number = 42; // One number type 2 let y = 3.14; // Also number ``` **Rust:** ```rust 1 let x: i32 = 42; // 32-bit signed integer 2 let y: f64 = 3.14; // 64-bit float 3 let z: u8 = 255; // 8-bit unsigned integer ``` **Why:** More control over memory and performance. ### Type Inference [Section titled “Type Inference”](#type-inference) **Both languages have it:** ```typescript 1 let x = 5; // TypeScript infers: number ``` ```rust 1 let x = 5; // Rust infers: i32 ``` But Rust’s inference goes further in complex scenarios! ### Operators [Section titled “Operators”](#operators) **Mostly the same:** ```typescript 1 // TypeScript 2 let sum = 5 + 3; 3 let is_equal = x === y; ``` ```rust 1 // Rust 2 let sum = 5 + 3; 3 let is_equal = x == y; // Note: no ===, just == ``` ### Comments [Section titled “Comments”](#comments) **Similar syntax:** ```typescript 1 // TypeScript 2 // Single line comment 3 /* Multi-line comment */ 4 5 /** JSDoc documentation */ ``` ```rust 1 // Rust 2 // Single line comment 3 /* Multi-line comment */ 4 5 /// Documentation comment (generates docs!) ``` ### Formatted Output [Section titled “Formatted Output”](#formatted-output) **Different, but does more:** ```typescript 1 // TypeScript 2 console.log(`Hello, ${name}!`); 3 console.log("x =", x, "y =", y); ``` ```rust 1 // Rust 2 println!("Hello, {}!", name); 3 println!("x = {} y = {}", x, y); ``` *** ## Key Differences from TypeScript [Section titled “Key Differences from TypeScript”](#key-differences-from-typescript) ### 1. Mutability [Section titled “1. Mutability”](#1-mutability) | Aspect | TypeScript | Rust | | -------------- | --------------- | ----------------- | | Default | Mutable (`let`) | Immutable (`let`) | | Make immutable | Use `const` | Default! | | Make mutable | Default! | Use `let mut` | | Reassignment | Always allowed | Only with `mut` | ### 2. Type System [Section titled “2. Type System”](#2-type-system) | Feature | TypeScript | Rust | | ---------------- | --------------- | ------------------------------ | | Number types | `number` | `i8`, `i32`, `f64`… | | Integer types | `number` | 12 different types! | | Type annotations | `: Type` | `: Type` (same!) | | Type inference | Good | Excellent | | Null safety | `strict` mode | No `null` at all (`Option`) | | Escape hatches | `any` (opt-out) | `unsafe` / `dyn Any` (rare) | ### 3. Variables [Section titled “3. Variables”](#3-variables) **TypeScript:** ```typescript 1 let x = 5; 2 let x = 10; // Error: cannot redeclare ``` **Rust:** ```rust 1 let x = 5; 2 let x = 10; // OK - this is "shadowing"! ``` **Shadowing** is a Rust feature that lets you reuse variable names. ### 4. Constants [Section titled “4. Constants”](#4-constants) **TypeScript:** ```typescript 1 const MAX_SIZE = 100; // Runtime constant ``` **Rust:** ```rust 1 const MAX_SIZE: u32 = 100; // Compile-time constant 2 // ^^^ Must have type annotation! ``` *** ## Important Concepts [Section titled “Important Concepts”](#important-concepts) ### Immutability by Default [Section titled “Immutability by Default”](#immutability-by-default) **Why does Rust do this?** 1. **Safety:** Prevents accidental modification 2. **Concurrency:** Immutable data is thread-safe 3. **Optimization:** Compiler can optimize better 4. **Intent:** Makes mutability explicit **Coming from JavaScript, this feels backwards at first!** ```javascript 1 // JavaScript - everything is mutable 2 let x = 5; 3 x = 6; // No problem ``` ```rust 1 // Rust - explicit mutability 2 let x = 5; 3 // x = 6; // Won't compile 4 5 let mut y = 5; 6 y = 6; // OK ``` **You’ll get used to it!** After a week, you’ll appreciate it. ### Type Annotations vs Inference [Section titled “Type Annotations vs Inference”](#type-annotations-vs-inference) **Rust is smart about types:** ```rust 1 let x = 5; // Inferred as i32 2 let y: u8 = 5; // Explicitly u8 3 let z = 5u8; // Suffix notation ``` **When you need annotations:** ```rust 1 // Compiler can't infer 2 let numbers: Vec = Vec::new(); 3 4 // Multiple possible types 5 let guess: u32 = "42".parse().expect("Not a number!"); ``` ### Expressions vs Statements [Section titled “Expressions vs Statements”](#expressions-vs-statements) **Everything in Rust is an expression (almost):** ```rust 1 let x = { 2 let y = 3; 3 y + 1 // No semicolon - this is the return value! 4 }; 5 // x is now 4 ``` **Compare to TypeScript:** ```typescript 1 // TypeScript - blocks don't return values 2 let x = (() => { 3 let y = 3; 4 return y + 1; 5 })(); ``` *** ## Your Goals for This Section [Section titled “Your Goals for This Section”](#your-goals-for-this-section) ### Minimum Goals [Section titled “Minimum Goals”](#minimum-goals) * [ ] Understand `let` vs `let mut` * [ ] Know the basic integer types (`i32`, `u32`, etc.) * [ ] Use `println!` with formatting * [ ] Write simple arithmetic expressions ### Stretch Goals [Section titled “Stretch Goals”](#stretch-goals) * [ ] Understand shadowing vs reassignment * [ ] Know when to use each integer type * [ ] Use all comparison operators * [ ] Write documentation comments * [ ] Use advanced formatting (debug, alignment) *** ## Common First-Time Issues [Section titled “Common First-Time Issues”](#common-first-time-issues) ### ”cannot assign twice to immutable variable” [Section titled “”cannot assign twice to immutable variable””](#cannot-assign-twice-to-immutable-variable) ```rust 1 let x = 5; 2 x = 6; // Error! ``` **Solution:** Add `mut`: ```rust 1 let mut x = 5; 2 x = 6; // OK ``` ### “type annotations needed” [Section titled ““type annotations needed””](#type-annotations-needed) ```rust 1 let x = Vec::new(); // What type? ``` **Solution:** Add type annotation: ```rust 1 let x: Vec = Vec::new(); // OK ``` ### Integer overflow [Section titled “Integer overflow”](#integer-overflow) ```rust 1 let x: u8 = 255; 2 let y = x + 1; // Compile error: this arithmetic operation will overflow ``` When **both operands are constants**, the compiler catches the overflow at compile time (`error: this arithmetic operation will overflow`). To see the *runtime* behavior, the overflow has to involve a value the compiler can’t fold away: ```rust 1 let mut x: u8 = 255; 2 x += 1; // Panics in debug mode; silently wraps to 0 in release mode ``` In debug builds this panics with `attempt to add with overflow`; in release builds the check is removed and the value wraps around to `0`. **Solution:** When you *want* wraparound, use the explicit wrapping/saturating arithmetic methods (`wrapping_add`, `saturating_add`, `checked_add`); we’ll cover these later. *** ## Section Overview [Section titled “Section Overview”](#section-overview) ### What Makes This Section Important [Section titled “What Makes This Section Important”](#what-makes-this-section-important) **These are the building blocks!** Everything in Rust builds on: * Variables and mutability * The type system * Basic operations **Master these, and the rest becomes easier.** ### How This Relates to Later Sections [Section titled “How This Relates to Later Sections”](#how-this-relates-to-later-sections) * **Section 03 (Functions):** Use these types as parameters * **Section 05 (Ownership):** Immutability is key to ownership * **Section 06 (Data Structures):** Compose basic types * **Section 08 (Error Handling):** Type system enables Result/Option ### Comparison to TypeScript Fundamentals [Section titled “Comparison to TypeScript Fundamentals”](#comparison-to-typescript-fundamentals) | Concept | TypeScript Section | Rust Section | Difficulty | | ----------- | ------------------ | ------------ | ---------- | | Variables | Day 1 | Day 1 | Medium | | Types | Day 1-2 | Day 1-2 | Medium | | Operators | Day 1 | Day 1 | Easy | | Mutability | Not emphasized | Critical | Hard | | Type safety | Optional | Mandatory | Medium | **The mutability concept is the hardest part for JS/TS developers.** *** ## Ready to Begin? [Section titled “Ready to Begin?”](#ready-to-begin) Let’s start with the most important concept: variables and mutability! ### [Start with Variables and Mutability](/02-basics/00-variables/) [Section titled “Start with Variables and Mutability”](#start-with-variables-and-mutability) Or jump to: * [Basic Types](/02-basics/01-types/) * [Operators](/02-basics/02-operators/) * [Comments](/02-basics/03-comments/) * [Output and Formatting](/02-basics/04-output/) *** ## Frequently asked questions [Section titled “Frequently asked questions”](#frequently-asked-questions) ### Are Rust variables mutable like JavaScript’s `let`? [Section titled “Are Rust variables mutable like JavaScript’s let?”](#are-rust-variables-mutable-like-javascripts-let) No. `let x = 5;` is immutable, and you opt into mutation with `let mut x = 5;`. This is the reverse of JavaScript, where `let` is reassignable and only `const` locks a binding. Rust’s `const` is a separate, always-immutable, compile-time constant. See [Variables and Mutability](/02-basics/00-variables/). ### Why does Rust have so many number types instead of one `number`? [Section titled “Why does Rust have so many number types instead of one number?”](#why-does-rust-have-so-many-number-types-instead-of-one-number) JavaScript’s single `f64` loses integer precision past 2^53 and hides cost. Rust’s sized integers (`i32`, `u64`, `usize`, …) and floats (`f32`, `f64`) make range, signedness, and memory explicit. Constant overflow is rejected, debug integer overflow panics by default, and optimized release builds wrap unless overflow checks are enabled; use `checked_*`, `saturating_*`, or `wrapping_*` when the policy matters. See [Basic Types](/02-basics/01-types/). ### What is shadowing? [Section titled “What is shadowing?”](#what-is-shadowing) Re-declaring a name with `let`: `let id = "5"; let id: i32 = id.parse()?;`. The new binding can change type and reuses the name, unlike reassignment, which cannot. It is handy for refining a value through a few steps without inventing new names. See [Variables and Mutability](/02-basics/00-variables/). # Variables and Mutability > Rust variables are immutable by default, the opposite of JavaScript. See how let, let mut, shadowing, and const differ from TypeScript's let and const bindings. Understanding variables in Rust matters. Unlike JavaScript/TypeScript where everything is mutable by default, Rust makes variables **immutable by default**. This is the single biggest mindset shift you’ll need to make. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In Rust, variables are immutable unless explicitly marked as mutable with `mut`. This forces you to think about which data needs to change and which doesn’t, leading to safer and more predictable code. **In short:** `let` creates immutable bindings, `let mut` creates mutable bindings. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // TypeScript/JavaScript - everything mutable by default 2 let x = 5; 3 x = 6; // OK - can reassign 4 5 const y = 10; 6 // y = 11; // Error - const prevents reassignment 7 8 // But const doesn't prevent mutation! 9 const arr = [1, 2, 3]; 10 arr.push(4); // OK - array itself is mutable! 11 arr[0] = 99; // OK 12 // arr = []; // Error - can't reassign 13 14 const obj = { value: 42 }; 15 obj.value = 43; // OK - object is mutable! 16 // obj = {}; // Error - can't reassign ``` **Key points:** * `let` = mutable (can reassign) * `const` = can’t reassign, but contents can mutate * Mutability is the default *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 // Rust - immutable by default! 2 let x = 5; 3 // x = 6; // Compile error: cannot assign twice to immutable variable 4 5 let mut y = 10; 6 y = 11; // OK - explicitly marked as mutable 7 8 // Arrays/vectors 9 let arr = vec![1, 2, 3]; 10 // arr.push(4); // Error - arr is immutable 11 // arr[0] = 99; // Error 12 13 let mut arr2 = vec![1, 2, 3]; 14 arr2.push(4); // OK 15 arr2[0] = 99; // OK 16 17 // Constants (compile-time constants) 18 const MAX_POINTS: u32 = 100_000; 19 // MAX_POINTS = 200_000; // Error - constants are never mutable ``` **Key points:** * `let` = immutable (cannot reassign or mutate) * `let mut` = mutable (can reassign and mutate) * `const` = compile-time constant (must have type annotation) * Immutability is the default *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Immutable Variables [Section titled “Immutable Variables”](#immutable-variables) ```rust 1 fn main() { 2 let x = 5; 3 println!("The value of x is: {}", x); 4 5 // x = 6; // This would cause a compile error: 6 // error[E0384]: cannot assign twice to immutable variable `x` 7 } ``` **Why immutable by default?** 1. **Safety:** Prevents accidental modification 2. **Concurrency:** Immutable data is safe to share across threads 3. **Optimization:** Compiler can make better optimizations 4. **Intent:** Makes your intentions explicit **This is the opposite of JavaScript!** ### Mutable Variables [Section titled “Mutable Variables”](#mutable-variables) ```rust 1 fn main() { 2 let mut x = 5; 3 println!("The value of x is: {}", x); 4 5 x = 6; // OK - x is mutable 6 println!("The value of x is: {}", x); 7 } ``` **Output:** ```plaintext 1 The value of x is: 5 2 The value of x is: 6 ``` **When to use `mut`:** * Counters in loops * Accumulators * Any value that needs to change over time ### Shadowing [Section titled “Shadowing”](#shadowing) Rust has a unique feature called **shadowing** that lets you redeclare a variable: ```rust 1 fn main() { 2 let x = 5; 3 4 let x = x + 1; // OK - shadowing 5 6 { 7 let x = x * 2; // OK - shadows in this scope 8 println!("Inner scope: {}", x); // 12 9 } 10 11 println!("Outer scope: {}", x); // 6 12 } ``` **Output:** ```plaintext 1 Inner scope: 12 2 Outer scope: 6 ``` **Shadowing vs Mutation:** ```rust 1 // Shadowing - creates new variable 2 let x = 5; 3 let x = x + 1; // New variable, can change type 4 5 // Mutation - changes existing variable 6 let mut y = 5; 7 y = y + 1; // Same variable, same type ``` **Shadowing allows type changes:** ```rust 1 let spaces = " "; // &str 2 let spaces = spaces.len(); // OK - now usize 3 4 let mut spaces2 = " "; 5 // spaces2 = spaces2.len(); // Error - type mismatch ``` ### Constants [Section titled “Constants”](#constants) ```rust 1 // Constants must: 2 // 1. Have a type annotation 3 // 2. Be assigned a constant expression (evaluated at compile time) 4 // 3. Use SCREAMING_SNAKE_CASE naming 5 6 const MAX_POINTS: u32 = 100_000; 7 const PI: f64 = 3.14159; 8 const APP_NAME: &str = "MyApp"; 9 10 fn main() { 11 println!("Max points: {}", MAX_POINTS); 12 // MAX_POINTS = 200_000; // Error - constants are always immutable 13 } ``` > **Note:** “Constant expression” does not mean “no function calls.” A `const` can call any **`const fn`** and many standard-library methods that are marked `const`, as long as everything is evaluable at compile time. For example, `const NAME_LEN: usize = "MyApp".len();` and a call to your own `const fn double(n: u32) -> u32 { n * 2 }` both work. What you cannot do is call a *non-`const`* function (anything that needs to run at runtime, like reading the clock or allocating a `Vec`). **Constants vs Immutable Variables:** | Feature | `const` | `let` | | ----------------- | ---------------------- | ------------------- | | Mutability | Never | Unless `mut` | | Type annotation | Required | Optional (inferred) | | Computation | Compile-time only | Runtime OK | | Scope | Global or local | Local only | | Naming convention | SCREAMING\_SNAKE\_CASE | snake\_case | | Can be shadowed | No | Yes | **When to use `const`:** * Configuration values * Mathematical constants * String literals used multiple times * Values that truly never change *** ## Key Differences from TypeScript/JavaScript [Section titled “Key Differences from TypeScript/JavaScript”](#key-differences-from-typescriptjavascript) ### 1. Default Mutability [Section titled “1. Default Mutability”](#1-default-mutability) **JavaScript:** ```javascript 1 let x = 5; // Can change 2 const y = 5; // Can't reassign (but contents can mutate) ``` **Rust:** ```rust 1 let x = 5; // Can't change 2 let mut y = 5; // Can change 3 const Z: i32 = 5; // Can't change, compile-time constant ``` **Mental model shift:** Rust’s `let` is *stricter* than JavaScript’s `const`. JavaScript `const` only blocks **reassignment** of the binding; the value it points to can still be mutated (`arr.push(4)`). Rust’s immutable `let` blocks **both** reassignment *and* mutation of the value. (And don’t confuse this with Rust’s own `const`, which is a separate, compile-time-only construct covered above, not the everyday tool for local bindings.) ### 2. Mutation vs Reassignment [Section titled “2. Mutation vs Reassignment”](#2-mutation-vs-reassignment) **JavaScript `const`:** ```javascript 1 const arr = [1, 2, 3]; 2 arr.push(4); // OK - array is mutable 3 arr[0] = 99; // OK 4 arr = []; // Error - can't reassign ``` **Rust `let`:** ```rust 1 let arr = vec![1, 2, 3]; 2 // arr.push(4); // Error - vector is immutable 3 // arr[0] = 99; // Error 4 // arr = vec![]; // Error ``` **In Rust, immutable means truly immutable!** ### 3. Shadowing [Section titled “3. Shadowing”](#3-shadowing) **JavaScript:** ```javascript 1 let x = 5; 2 let x = 10; // SyntaxError: Identifier 'x' has already been declared ``` **Rust:** ```rust 1 let x = 5; 2 let x = 10; // OK - shadowing ``` ### 4. Type Changes [Section titled “4. Type Changes”](#4-type-changes) **TypeScript:** ```typescript 1 let spaces = " "; 2 spaces = spaces.length; // Type error: string to number ``` **Rust with shadowing:** ```rust 1 let spaces = " "; 2 let spaces = spaces.len(); // OK - shadowing allows type change ``` **Rust with mutation:** ```rust 1 let mut spaces = " "; 2 // spaces = spaces.len(); // Error - can't change type ``` *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting `mut` [Section titled “Pitfall 1: Forgetting mut”](#pitfall-1-forgetting-mut) **Problem:** ```rust 1 fn main() { 2 let counter = 0; 3 4 for i in 1..=5 { 5 counter += 1; // Error: cannot assign to immutable variable 6 } 7 } ``` **Error** (the compiler also warns that `counter` and `i` are unused, since the code never compiles far enough to use them): ```plaintext 1 warning: variable `counter` is assigned to, but never used 2 --> src/main.rs:2:9 3 | 4 2 | let counter = 0; 5 | ^^^^^^^ 6 | 7 = note: consider using `_counter` instead 8 = note: `#[warn(unused_variables)]` on by default 9 10 warning: unused variable: `i` 11 --> src/main.rs:4:9 12 | 13 4 | for i in 1..=5 { 14 | ^ help: if this is intentional, prefix it with an underscore: `_i` 15 16 error[E0384]: cannot assign twice to immutable variable `counter` 17 --> src/main.rs:5:9 18 | 19 2 | let counter = 0; 20 | ------- first assignment to `counter` 21 ... 22 5 | counter += 1; // Error: cannot assign to immutable variable 23 | ^^^^^^^^^^^^ cannot assign twice to immutable variable 24 | 25 help: consider making this binding mutable 26 | 27 2 | let mut counter = 0; 28 | +++ ``` **Solution:** ```rust 1 fn main() { 2 let mut counter = 0; // Add 'mut' 3 4 for i in 1..=5 { 5 counter += 1; // OK 6 } 7 8 println!("Counter: {}", counter); 9 } ``` ### Pitfall 2: Thinking `const` Works Like TypeScript [Section titled “Pitfall 2: Thinking const Works Like TypeScript”](#pitfall-2-thinking-const-works-like-typescript) **Problem:** ```rust 1 const MAX_POINTS = 100_000; // Error: missing type annotation ``` **Error:** ```plaintext 1 error: missing type for `const` item 2 --> src/main.rs:1:17 3 | 4 1 | const MAX_POINTS = 100_000; // Error: missing type annotation 5 | ^ help: provide a type for the constant: `: i32` ``` **Solution:** ```rust 1 const MAX_POINTS: u32 = 100_000; // OK - type annotation required ``` ### Pitfall 3: Trying to Mutate Immutable Data [Section titled “Pitfall 3: Trying to Mutate Immutable Data”](#pitfall-3-trying-to-mutate-immutable-data) **Problem:** ```rust 1 fn main() { 2 let v = vec![1, 2, 3]; 3 v.push(4); // Error: cannot borrow as mutable 4 } ``` **Error:** ```plaintext 1 error[E0596]: cannot borrow `v` as mutable, as it is not declared as mutable 2 --> src/main.rs:3:5 3 | 4 3 | v.push(4); // Error: cannot borrow as mutable 5 | ^ cannot borrow as mutable 6 | 7 help: consider changing this to be mutable 8 | 9 2 | let mut v = vec![1, 2, 3]; 10 | +++ ``` **Solution:** ```rust 1 fn main() { 2 let mut v = vec![1, 2, 3]; // Add 'mut' 3 v.push(4); // OK 4 } ``` ### Pitfall 4: Confusing Shadowing with Mutation [Section titled “Pitfall 4: Confusing Shadowing with Mutation”](#pitfall-4-confusing-shadowing-with-mutation) **Problem thinking:** ```rust 1 let x = 5; 2 let x = 6; // "This is reassignment, right?" ``` **Reality:** It’s shadowing - a new variable with the same name. ```rust 1 fn main() { 2 let x = 5; 3 println!("Address: {:p}", &x); 4 5 let x = 6; 6 println!("Address: {:p}", &x); // a different address 7 } ``` The two `&x` print *different* addresses, which proves these are two separate variables rather than one variable being reassigned. The actual addresses and the gap between them are not specified by the language — they depend on the platform, the optimization level, and stack layout, so don’t read anything into the exact hex values or assume a fixed offset. **These are different variables in memory!** *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Prefer Immutability [Section titled “1. Prefer Immutability”](#1-prefer-immutability) ** Don’t default to `mut`:** ```rust 1 fn main() { 2 let mut x = 5; // Unnecessary mut 3 let mut y = 10; // Unnecessary mut 4 println!("{} {}", x, y); 5 } ``` ** Only use `mut` when needed:** ```rust 1 fn main() { 2 let x = 5; // Immutable - won't change 3 let mut y = 10; // Mutable - will change 4 y += 5; 5 println!("{} {}", x, y); 6 } ``` **Why:** Immutability makes code easier to reason about and enables compiler optimizations. ### 2. Use Shadowing for Transformations [Section titled “2. Use Shadowing for Transformations”](#2-use-shadowing-for-transformations) ** Don’t create new variable names:** ```rust 1 let spaces_str = " "; 2 let spaces_count = spaces_str.len(); 3 let spaces_display = format!("Count: {}", spaces_count); ``` ** Use shadowing for the same concept:** ```rust 1 let spaces = " "; 2 let spaces = spaces.len(); 3 let spaces = format!("Count: {}", spaces); ``` **When shadowing makes sense:** * Type transformations * Progressive calculations * Parsing/validation steps ### 3. Use Constants for True Constants [Section titled “3. Use Constants for True Constants”](#3-use-constants-for-true-constants) ** Don’t use variables for constants:** ```rust 1 fn main() { 2 let max_points = 100_000; // Used everywhere 3 // ... lots of code ... 4 } ``` ** Use `const` for values that never change:** ```rust 1 const MAX_POINTS: u32 = 100_000; 2 3 fn main() { 4 // MAX_POINTS available everywhere 5 } ``` ### 4. Clear Variable Names [Section titled “4. Clear Variable Names”](#4-clear-variable-names) ** Don’t use generic names:** ```rust 1 let mut x = vec![]; 2 let mut y = vec![]; ``` ** Use descriptive names:** ```rust 1 let mut users = vec![]; 2 let mut products = vec![]; ``` **Even with mutability, clarity matters!** *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) ### Calculating Running Average [Section titled “Calculating Running Average”](#calculating-running-average) **TypeScript:** ```typescript 1 function calculateRunningAverage(numbers: number[]): number[] { 2 let sum = 0; 3 const averages = []; 4 5 for (let i = 0; i < numbers.length; i++) { 6 sum += numbers[i]; 7 averages.push(sum / (i + 1)); 8 } 9 10 return averages; 11 } 12 13 const nums = [10, 20, 30, 40, 50]; 14 console.log(calculateRunningAverage(nums)); 15 // [10, 15, 20, 25, 30] ``` **Rust:** ```rust 1 fn calculate_running_average(numbers: &[i32]) -> Vec { 2 let mut sum = 0; 3 let mut averages = Vec::new(); 4 5 for (i, &num) in numbers.iter().enumerate() { 6 sum += num; 7 averages.push(sum as f64 / (i + 1) as f64); 8 } 9 10 averages 11 } 12 13 fn main() { 14 let nums = vec![10, 20, 30, 40, 50]; 15 let result = calculate_running_average(&nums); 16 println!("{:?}", result); 17 // [10.0, 15.0, 20.0, 25.0, 30.0] 18 } ``` **Notice:** * `sum` and `averages` are `mut` (they change) * `numbers` is immutable (just reading) * Clear intent about what changes > **Note:** This example sneaks in a few things from later chapters — `&[i32]` (a borrowed slice, [Section 05](/05-ownership/)), `.iter().enumerate()` ([Section 07: Iterators](/07-collections/06-iterators/)), and `as f64` casts ([Basic Types](/02-basics/01-types/)). Don’t worry about those yet; focus on which bindings are `mut` and which are not. ### Configuration with Constants [Section titled “Configuration with Constants”](#configuration-with-constants) **TypeScript:** ```typescript 1 const CONFIG = { 2 MAX_CONNECTIONS: 100, 3 TIMEOUT_MS: 5000, 4 API_URL: "https://api.example.com", 5 }; 6 7 function connect() { 8 // Use CONFIG.MAX_CONNECTIONS 9 } ``` **Rust:** ```rust 1 const MAX_CONNECTIONS: u32 = 100; 2 const TIMEOUT_MS: u64 = 5000; 3 const API_URL: &str = "https://api.example.com"; 4 5 fn connect() { 6 // Use MAX_CONNECTIONS 7 } 8 9 fn main() { 10 println!("Max connections: {}", MAX_CONNECTIONS); 11 } ``` **Constants are available globally without runtime overhead!** *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book - Variables and Mutability](https://doc.rust-lang.org/book/ch03-01-variables-and-mutability.html) * [Rust Reference - Constants](https://doc.rust-lang.org/reference/items/constant-items.html) * [Rust by Example - Variable Bindings](https://doc.rust-lang.org/rust-by-example/variable_bindings.html) ### Related Topics [Section titled “Related Topics”](#related-topics) * [Ownership](/05-ownership/) - Immutability is key to ownership * [Borrowing](/05-ownership/02-borrowing/) - Mutable vs immutable references *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Fix the Mutability [Section titled “Exercise 1: Fix the Mutability”](#exercise-1-fix-the-mutability) Fix this code: ```rust 1 fn main() { 2 let x = 5; 3 println!("x is: {}", x); 4 5 x = 6; 6 println!("x is now: {}", x); 7 } ``` Solution ```rust 1 fn main() { 2 let mut x = 5; // Add 'mut' 3 println!("x is: {}", x); 4 5 x = 6; 6 println!("x is now: {}", x); 7 } ``` ### Exercise 2: Use Shadowing [Section titled “Exercise 2: Use Shadowing”](#exercise-2-use-shadowing) Rewrite using shadowing to convert a string to its length: ```rust 1 fn main() { 2 let text = "Hello, Rust!"; 3 let text_length = text.len(); 4 println!("Text: '{}' has length {}", text, text_length); 5 } ``` Solution ```rust 1 fn main() { 2 let text = "Hello, Rust!"; 3 println!("Text: '{}'", text); 4 5 let text = text.len(); // Shadow with new type 6 println!("Length: {}", text); 7 } ``` ### Exercise 3: Constants [Section titled “Exercise 3: Constants”](#exercise-3-constants) Create constants for a game: * Maximum health: 100 * Starting gold: 50 * Player name: “Hero” ```rust 1 // Add constants here 2 3 fn main() { 4 println!("Max health: {}", /* use constant */); 5 println!("Starting gold: {}", /* use constant */); 6 println!("Player: {}", /* use constant */); 7 } ``` Solution ```rust 1 const MAX_HEALTH: u32 = 100; 2 const STARTING_GOLD: u32 = 50; 3 const PLAYER_NAME: &str = "Hero"; 4 5 fn main() { 6 println!("Max health: {}", MAX_HEALTH); 7 println!("Starting gold: {}", STARTING_GOLD); 8 println!("Player: {}", PLAYER_NAME); 9 } ``` ### Exercise 4: Counter [Section titled “Exercise 4: Counter”](#exercise-4-counter) Write a function that counts from 1 to n: ```rust 1 fn count_to(n: i32) { 2 // Implement using a mutable counter 3 } 4 5 fn main() { 6 count_to(5); 7 // Should print the numbers 1 to 5, space-separated 8 } ``` Solution ```rust 1 fn count_to(n: i32) { 2 let mut counter = 1; 3 while counter <= n { 4 print!("{} ", counter); 5 counter += 1; 6 } 7 println!(); 8 } 9 10 fn main() { 11 count_to(5); 12 } ``` *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * Rust variables are immutable by default * Use `let mut` for mutable variables * Shadowing lets you reuse names and change types * Constants require type annotations and are compile-time * Immutability leads to safer, more maintainable code **Key syntax:** ```rust 1 let x = 5; // Immutable 2 let mut y = 10; // Mutable 3 const Z: i32 = 100; // Constant 4 5 let x = x + 1; // Shadowing (new variable) 6 y = y + 1; // Mutation (same variable) ``` **Mental model:** * Default to immutable * Add `mut` only when needed * Use shadowing for transformations * Use `const` for true constants **This is the foundation!** Everything else in Rust builds on this concept. # Basic Types > Rust replaces TypeScript's one number type with sized ints, floats, bool, char, and tuples, plus explicit casts and overflow checks, not silent coercion. Rust has a rich type system with explicit types for different sizes and purposes. Unlike TypeScript’s single `number` type, Rust has many numeric types optimized for different use cases. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Rust’s type system is: * **Explicit:** Different types for integers, floats, etc. * **Safe:** No implicit conversions that lose data * **Efficient:** Choose the right size for your needs **Key types:** Integers (`i32`, `u8`…), floats (`f32`, `f64`), booleans (`bool`), characters (`char`), tuples *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // TypeScript - Simple type system 2 let integer: number = 42; 3 let float: number = 3.14; 4 let negative: number = -10; 5 let big: number = 9007199254740991; // Max safe integer 6 7 let flag: boolean = true; 8 let letter: string = "a"; // No char type 9 let tuple: [number, string] = [1, "hello"]; 10 11 // All numbers are the same type 12 let x: number = 42; 13 let y: number = 3.14; 14 console.log(typeof x); // "number" 15 console.log(typeof y); // "number" ``` **Key points:** * One `number` type for all numbers * No distinction between integers and floats * No control over size/memory usage * Strings for single characters *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 // Rust - Rich type system 2 let integer: i32 = 42; // 32-bit signed integer 3 let float: f64 = 3.14; // 64-bit float 4 let negative: i32 = -10; // Signed integer 5 let small: u8 = 255; // 8-bit unsigned (0-255) 6 let big: i64 = 9_223_372_036_854_775_807; // 64-bit signed 7 8 let flag: bool = true; // Boolean 9 let letter: char = 'a'; // Unicode scalar value (4 bytes!) 10 let tuple: (i32, &str) = (1, "hello"); // Tuple 11 12 // Different types for different purposes 13 let x: i32 = 42; // Integer type 14 let y: f64 = 3.14; // Float type 15 // let z = x + y; // Error: can't add i32 and f64! 16 let z = x as f64 + y; // Explicit conversion ``` **Key points:** * Multiple integer types (by size and signedness) * Separate float types (f32, f64) * Explicit conversions required * True character type (Unicode) *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Integer Types [Section titled “Integer Types”](#integer-types) Rust has **12** integer types based on: 1. **Signedness:** Signed (`i`) or unsigned (`u`) 2. **Size:** 8, 16, 32, 64, 128 bits, or architecture-dependent **Signed integers (can be negative):** | Type | Size | Range | | ------- | -------- | ------------------------------- | | `i8` | 8 bits | -128 to 127 | | `i16` | 16 bits | -32,768 to 32,767 | | `i32` | 32 bits | -2,147,483,648 to 2,147,483,647 | | `i64` | 64 bits | -9,223,372,036,854,775,808 to … | | `i128` | 128 bits | Very large range | | `isize` | arch | Depends on CPU (32 or 64 bits) | **Unsigned integers (only positive):** | Type | Size | Range | | ------- | -------- | ------------------------ | | `u8` | 8 bits | 0 to 255 | | `u16` | 16 bits | 0 to 65,535 | | `u32` | 32 bits | 0 to 4,294,967,295 | | `u64` | 64 bits | 0 to 18,446,744,073,709… | | `u128` | 128 bits | Very large range | | `usize` | arch | Depends on CPU | **Default:** When you write `let x = 42;`, Rust infers `i32`. **Examples:** ```rust 1 // Signed integers 2 let a: i8 = -128; // Smallest i8 3 let b: i8 = 127; // Largest i8 4 let c: i32 = -2_000_000; // Default integer type 5 6 // Unsigned integers 7 let d: u8 = 255; // Largest u8 8 let e: u16 = 65_535; // Largest u16 9 let f: u32 = 4_000_000; // Common for large counts 10 11 // Architecture-dependent 12 let idx: usize = 10; // Used for array indices, sizes 13 let offset: isize = -5; // Used for pointer arithmetic ``` **Number literals:** ```rust 1 let decimal = 98_222; // Underscore for readability 2 let hex = 0xff; // Hexadecimal 3 let octal = 0o77; // Octal 4 let binary = 0b1111_0000; // Binary 5 let byte = b'A'; // u8 only (ASCII) 6 7 // Type suffix 8 let x = 42i32; // Explicitly i32 9 let y = 100_u8; // Explicitly u8 10 let z = 3.14f32; // Explicitly f32 ``` ### Floating-Point Types [Section titled “Floating-Point Types”](#floating-point-types) Rust has two floating-point types: | Type | Size | Precision | Default | | ----- | ------- | ------------- | ------- | | `f32` | 32 bits | \~7 decimals | No | | `f64` | 64 bits | \~15 decimals | Yes | **Examples:** ```rust 1 let x = 2.0; // f64 (default) 2 let y: f32 = 3.0; // f32 (explicit) 3 4 let pi: f64 = 3.14159265359; 5 let e: f32 = 2.71828; 6 7 // Scientific notation 8 let large = 1e10; // f64; prints as 10000000000 (whole-valued floats omit the .0) 9 let small = 1e-5; // f64; prints as 0.00001 ``` **When to use f32 vs f64:** * **f32:** Graphics, game engines (GPU prefers f32) * **f64:** Scientific computing, default (more precise) **Compare to TypeScript:** ```typescript 1 // TypeScript - one type 2 let x: number = 3.14; // Always IEEE-754 f64 (Rust's f64) 3 let y: number = 2.0; // Same type; JS has no f32 ``` ### Boolean Type [Section titled “Boolean Type”](#boolean-type) Simple true/false: ```rust 1 let t = true; // Inferred as bool 2 let f: bool = false; // Explicit type 3 4 // Common use in conditionals 5 let is_active = true; 6 if is_active { 7 println!("Active!"); 8 } 9 10 // Size: 1 byte (8 bits) ``` **Same as TypeScript:** ```typescript 1 let t: boolean = true; 2 let f: boolean = false; ``` ### Character Type [Section titled “Character Type”](#character-type) Rust’s `char` is a full **Unicode Scalar Value**, covering far more than ASCII! ```rust 1 let c = 'z'; // Inferred as char 2 let z: char = 'ℤ'; // Unicode 3 let heart = '\u{2764}'; // Emoji (a Unicode scalar) 4 let chinese = '中'; // Chinese character 5 6 // Size: 4 bytes (32 bits) 7 // Range: U+0000 to U+D7FF and U+E000 to U+10FFFF ``` **Compare to TypeScript:** ```typescript 1 // TypeScript - no char type, use string 2 let c: string = "z"; 3 let emoji: string = "\u{2764}"; ``` **Important:** In Rust, `'a'` is a char, `"a"` is a string! ```rust 1 let char_a = 'a'; // char type 2 let string_a = "a"; // &str type (string slice) ``` ### Tuple Type [Section titled “Tuple Type”](#tuple-type) Group multiple values of different types: ```rust 1 let tup: (i32, f64, u8) = (500, 6.4, 1); 2 3 // Destructuring 4 let (x, y, z) = tup; 5 println!("x: {}, y: {}, z: {}", x, y, z); 6 7 // Access by index 8 let five_hundred = tup.0; 9 let six_point_four = tup.1; 10 let one = tup.2; 11 12 // Empty tuple (unit type) 13 let unit: () = (); ``` **Compare to TypeScript:** ```typescript 1 // TypeScript tuples 2 let tup: [number, number, number] = [500, 6.4, 1]; 3 4 // Destructuring 5 let [x, y, z] = tup; 6 7 // Access by index 8 let five_hundred = tup[0]; ``` **Tuple use cases:** * Return multiple values from functions * Group related values temporarily * Pattern matching (we’ll see later) **Unit type `()`:** ```rust 1 fn do_something() { 2 // No return value means returns () 3 } 4 5 fn explicit_unit() -> () { 6 println!("Returns unit"); 7 } ``` This looks like TypeScript’s `void`, but the two differ. TypeScript’s `void` is a type used to say “ignore whatever this returns”; there is no `void` *value* you can hold. Rust’s `()` (the **unit type**) is a real type with exactly one value, also written `()`. A function with no `-> ...` returns `()`, and you can bind it: `let nothing: () = do_something();` is valid Rust. *** ## Key Differences from TypeScript [Section titled “Key Differences from TypeScript”](#key-differences-from-typescript) ### 1. Multiple Number Types [Section titled “1. Multiple Number Types”](#1-multiple-number-types) **TypeScript:** ```typescript 1 let x: number = 42; 2 let y: number = 3.14; 3 let z: number = x + y; // OK ``` **Rust:** ```rust 1 let x: i32 = 42; 2 let y: f64 = 3.14; 3 // let z = x + y; // Error: mismatched types 4 let z = x as f64 + y; // Explicit conversion ``` ### 2. Overflow Behavior [Section titled “2. Overflow Behavior”](#2-overflow-behavior) **TypeScript:** ```typescript 1 let x: number = 255; 2 x = x + 1; // 256 (no problem) ``` **Rust (debug mode):** ```rust 1 let mut x: u8 = 255; 2 let one = std::env::args().count() as u8; // 1 at runtime, not a constant 3 x = x + one; // Panics at runtime: "attempt to add with overflow" ``` **Rust (release mode):** ```rust 1 let mut x: u8 = 255; 2 let one = std::env::args().count() as u8; // 1 at runtime, not a constant 3 x = x + one; // Wraps to 0 (two's complement) ``` > **Note:** Both operands above are computed at runtime on purpose. If you instead write `let x: u8 = 255; x + 1` with two literals, the compiler folds the constants and rejects it outright with `error: this arithmetic operation will overflow` — it never even gets to run. > **Warning:** This release-mode wrap is a *documented logic error*, not a feature to lean on. Relying on the silent wrap is discouraged; if you genuinely want wrapping, say so explicitly with `wrapping_add` so the behavior is the same in debug and release: > > ```rust > 1 > let x: u8 = 255; > 2 > let y = x.wrapping_add(1); // 0, intentional and identical in debug + release > ``` **Explicit overflow handling:** ```rust 1 let x: u8 = 255; 2 3 // Wrapping (always wraps) 4 let y = x.wrapping_add(1); // 0 5 6 // Saturating (clamps to max) 7 let y = x.saturating_add(1); // 255 8 9 // Checked (returns Option) 10 let y = x.checked_add(1); // None 11 12 // Overflowing (returns tuple) 13 let (y, overflowed) = x.overflowing_add(1); // (0, true) ``` ### 3. No Implicit Conversions [Section titled “3. No Implicit Conversions”](#3-no-implicit-conversions) **TypeScript:** ```typescript 1 let x: number = 42; 2 let y: string = String(x); // Explicit, but common 3 let z = x + ""; // Implicit conversion ``` **Rust:** ```rust 1 let x: i32 = 42; 2 // let y: String = x; // Error: can't convert 3 let y: String = x.to_string(); // Explicit 4 5 // Type casting with 'as' 6 let a: i32 = 42; 7 let b: f64 = a as f64; 8 let c: u8 = 255; 9 let d: i32 = c as i32; ``` ### 4. Character vs String [Section titled “4. Character vs String”](#4-character-vs-string) **TypeScript:** ```typescript 1 let c = "a"; // string 2 let s = "hello"; // string (same type) ``` **Rust:** ```rust 1 let c = 'a'; // char (4 bytes) 2 let s = "hello"; // &str (string slice) 3 // Different types! ``` *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Integer Overflow [Section titled “Pitfall 1: Integer Overflow”](#pitfall-1-integer-overflow) **Problem:** ```rust 1 fn add_one(x: u8) -> u8 { 2 x + 1 // Panics in debug, wraps in release when x is 255 3 } 4 5 fn main() { 6 let y = add_one(255); 7 println!("{y}"); 8 } ``` > **Note:** Here `x` arrives as a function argument, so the overflow is only discovered at runtime: debug builds panic with `attempt to add with overflow`, release builds silently wrap to `0`. Writing the same overflow with two literals (`let x: u8 = 255; x + 1`) is caught at compile time instead. The compiler emits `error: this arithmetic operation will overflow`. **Solution:** ```rust 1 fn main() { 2 let x: u8 = 255; 3 4 // Choose appropriate method 5 let y = x.saturating_add(1); // 255 (clamps) 6 let y = x.wrapping_add(1); // 0 (wraps) 7 8 // Or use larger type 9 let x: u16 = 255; 10 let y = x + 1; // 256 11 } ``` ### Pitfall 2: Mixing Integer Types [Section titled “Pitfall 2: Mixing Integer Types”](#pitfall-2-mixing-integer-types) **Problem:** ```rust 1 let x: i32 = 10; 2 let y: i64 = 20; 3 // let z = x + y; // Error: mismatched types ``` **Solution:** ```rust 1 let x: i32 = 10; 2 let y: i64 = 20; 3 let z = (x as i64) + y; // Convert x to i64 ``` ### Pitfall 3: Division Truncation [Section titled “Pitfall 3: Division Truncation”](#pitfall-3-division-truncation) **Problem:** ```rust 1 let x = 5 / 2; // Result is 2, not 2.5! ``` **Why:** Integer division truncates. **Solution:** ```rust 1 let x = 5.0 / 2.0; // 2.5 (float division) 2 let y = 5 as f64 / 2.0; // 2.5 (convert to float) ``` ### Pitfall 4: Char vs String Confusion [Section titled “Pitfall 4: Char vs String Confusion”](#pitfall-4-char-vs-string-confusion) **Problem:** ```rust 1 let c: char = "a"; // Error: expected char, found &str ``` **Solution:** ```rust 1 let c: char = 'a'; // Single quotes for char 2 let s: &str = "a"; // Double quotes for string ``` *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Default to i32, Then Specialize [Section titled “1. Default to i32, Then Specialize”](#1-default-to-i32-then-specialize) The Rust Book’s advice: **start with `i32`** as your default integer. It is fast on modern CPUs and rarely the wrong choice. Reach for a different type only when you have a concrete reason — a domain bound, a memory budget, or an API that demands it. ** Default unless you have a reason:** ```rust 1 let count = 10; // i32 by inference — the sensible default 2 let id: u32 = 123456; // u32 because the ID is never negative 3 let size: usize = 1000; // usize because it indexes a collection ``` **Specialize when the domain or API calls for it:** ```rust 1 let pixel: u8 = 255; // a color channel really is 0-255 2 let port: u16 = 8080; // ports are 0-65535 3 let idx: usize = 10; // indexing/length is always usize ``` > **Tip:** Choosing the *smallest* type that fits is not automatically better. Picking `u8` for an age, for example, buys almost nothing and just invites overflow bugs as soon as you add to it. Optimize the size only where it matters (large arrays, packed structs, fixed protocol fields). **Rough guidance on when to deviate from `i32`:** * `u8`: bytes, color channels, raw ASCII * `u16`: ports, values bounded above (e.g. HTTP status 100-599) * `i64`/`u64`: timestamps, file sizes, values that outgrow 32 bits * `usize`/`isize`: collection indices, lengths, sizes — required by the standard library ### 2. Use Type Inference When Clear [Section titled “2. Use Type Inference When Clear”](#2-use-type-inference-when-clear) ** Don’t over-annotate:** ```rust 1 let x: i32 = 42; 2 let y: i32 = 10; 3 let z: i32 = x + y; ``` ** Let Rust infer:** ```rust 1 let x = 42; // Inferred as i32 2 let y = 10; // Inferred as i32 3 let z = x + y; // Inferred as i32 ``` **Annotate when needed:** ```rust 1 let x: u8 = 42; // Need u8, not i32 2 let y = Vec::new(); // Need to specify: Vec ``` ### 3. Use Suffixes for Clarity [Section titled “3. Use Suffixes for Clarity”](#3-use-suffixes-for-clarity) ** Ambiguous:** ```rust 1 let x = 42; // Is this i32, u32, i64? ``` ** Clear intent:** ```rust 1 let x = 42u8; // Explicitly u8 2 let y = 1_000_000u32; // Explicitly u32 3 let z = 3.14f32; // Explicitly f32 ``` ### 4. Handle Overflow Explicitly [Section titled “4. Handle Overflow Explicitly”](#4-handle-overflow-explicitly) ** Hope for the best:** ```rust 1 let x: u8 = user_input + 10; // What if it overflows? ``` ** Handle explicitly:** ```rust 1 let x: u8 = user_input.saturating_add(10); // Clamps to 255 2 // or 3 let x = user_input.checked_add(10) 4 .expect("Overflow!"); ``` *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) ### Type-Safe Configuration [Section titled “Type-Safe Configuration”](#type-safe-configuration) **TypeScript:** ```typescript 1 interface Config { 2 port: number; // Could be negative! 3 maxConnections: number; 4 timeout: number; // Milliseconds 5 name: string; 6 } 7 8 const config: Config = { 9 port: 8080, 10 maxConnections: 100, 11 timeout: 5000, 12 name: "MyServer", 13 }; ``` **Rust:** ```rust 1 struct Config { 2 port: u16, // 0-65535 (valid port range) 3 max_connections: u32, // Only positive 4 timeout_ms: u64, // Milliseconds, large range 5 name: String, 6 } 7 8 let config = Config { 9 port: 8080, 10 max_connections: 100, 11 timeout_ms: 5000, 12 name: String::from("MyServer"), 13 }; 14 15 // Can't set invalid port 16 // let bad = Config { port: -1, ... }; // Won't compile! 17 // let bad = Config { port: 70000, ... }; // Won't compile! ``` **The type system enforces validity!** ### Pixel Color Representation [Section titled “Pixel Color Representation”](#pixel-color-representation) ```rust 1 // RGB color (0-255 per channel) 2 struct Color { 3 r: u8, // Red: 0-255 4 g: u8, // Green: 0-255 5 b: u8, // Blue: 0-255 6 } 7 8 let red = Color { r: 255, g: 0, b: 0 }; 9 let white = Color { r: 255, g: 255, b: 255 }; 10 11 // Can't set invalid values 12 // let bad = Color { r: 256, g: 0, b: 0 }; // Won't compile! ``` **u8 is perfect for this!** Saves memory and enforces range. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book - Data Types](https://doc.rust-lang.org/book/ch03-02-data-types.html) * [Rust Reference - Types](https://doc.rust-lang.org/reference/types.html) * [Rust by Example - Primitives](https://doc.rust-lang.org/rust-by-example/primitives.html) ### Related Topics [Section titled “Related Topics”](#related-topics) * [Type Conversions](https://doc.rust-lang.org/rust-by-example/types/cast.html) * [Overflow Handling](https://doc.rust-lang.org/std/primitive.u8.html#method.wrapping_add) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Choose the Right Type [Section titled “Exercise 1: Choose the Right Type”](#exercise-1-choose-the-right-type) For each value, choose the most appropriate type: ```rust 1 // 1. Person's age 2 let age: /* what type? */ = 25; 3 4 // 2. HTTP status code (100-599) 5 let status: /* what type? */ = 200; 6 7 // 3. Temperature in Celsius (-273.15 to ∞) 8 let temp: /* what type? */ = -5.5; 9 10 // 4. Array index 11 let idx: /* what type? */ = 10; 12 13 // 5. Unicode emoji 14 let emoji: /* what type? */ = '\u{1F600}'; ``` Solutions ```rust 1 let age: u8 = 25; // 0-255 is enough 2 let status: u16 = 200; // 100-599 fits in u16 3 let temp: f32 = -5.5; // Float for decimals 4 let idx: usize = 10; // usize for indices 5 let emoji: char = '\u{1F600}'; // char for Unicode ``` ### Exercise 2: Fix Type Errors [Section titled “Exercise 2: Fix Type Errors”](#exercise-2-fix-type-errors) Fix this code: ```rust 1 fn main() { 2 let x: i32 = 10; 3 let y: f64 = 3.14; 4 let z = x + y; 5 println!("Result: {}", z); 6 } ``` Solution ```rust 1 fn main() { 2 let x: i32 = 10; 3 let y: f64 = 3.14; 4 let z = x as f64 + y; // Convert x to f64 5 println!("Result: {}", z); 6 } ``` ### Exercise 3: Tuple Destructuring [Section titled “Exercise 3: Tuple Destructuring”](#exercise-3-tuple-destructuring) Create a tuple with (name, age, score) and destructure it: ```rust 1 fn main() { 2 // Create tuple 3 let student = /* create tuple */; 4 5 // Destructure 6 let (/* fill in */) = student; 7 8 println!("Name: {}, Age: {}, Score: {}", name, age, score); 9 } ``` Solution ```rust 1 fn main() { 2 let student = ("Alice", 20, 95.5); 3 let (name, age, score) = student; 4 println!("Name: {}, Age: {}, Score: {}", name, age, score); 5 } ``` ### Exercise 4: Safe Arithmetic [Section titled “Exercise 4: Safe Arithmetic”](#exercise-4-safe-arithmetic) Implement safe addition that doesn’t panic: ```rust 1 fn safe_add(a: u8, b: u8) -> u8 { 2 // Use saturating or checked addition 3 } 4 5 fn main() { 6 println!("{}", safe_add(200, 100)); // Should be 255 7 println!("{}", safe_add(10, 20)); // Should be 30 8 } ``` Solution ```rust 1 fn safe_add(a: u8, b: u8) -> u8 { 2 a.saturating_add(b) // Clamps to 255 3 } 4 5 fn main() { 6 println!("{}", safe_add(200, 100)); // 255 7 println!("{}", safe_add(10, 20)); // 30 8 } ``` *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * Rust has many integer types (i8, i32, u64, etc.) * Two float types (f32, f64) * Boolean and character types * Tuples for grouping values * No implicit conversions (use `as`) * Explicit overflow handling **Key types:** ```rust 1 // Integers 2 i8, i16, i32, i64, i128, isize // Signed 3 u8, u16, u32, u64, u128, usize // Unsigned 4 5 // Floats 6 f32, f64 7 8 // Others 9 bool // true/false 10 char // Unicode scalar value 11 () // Unit type 12 (T, U) // Tuple ``` **Type conversion:** ```rust 1 let x: i32 = 42; 2 let y: f64 = x as f64; // Explicit cast 3 let z: String = x.to_string(); // Method call ``` **Choose types wisely for memory efficiency and correctness!** # Operators > Rust's operators are similar to TypeScript/JavaScript, with a few important differences. Here we cover arithmetic, comparison, logical, and bitwise operators. Rust’s operators are similar to TypeScript/JavaScript, with a few important differences. Here we cover arithmetic, comparison, logical, and bitwise operators. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Most operators work the same way, but Rust: * Has no `===` (just `==`) * Requires same types for operations * Has explicit bitwise operators * No automatic type coercion **You’ll feel right at home with 90% of operators!** *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // Arithmetic 2 let sum = 5 + 3; // 8 3 let diff = 10 - 4; // 6 4 let product = 3 * 4; // 12 5 let quotient = 10 / 3; // 3.333... 6 let remainder = 10 % 3; // 1 7 8 // Comparison 9 let equal = 5 === 5; // true 10 let not_equal = 5 !== 6; // true 11 let greater = 10 > 5; // true 12 13 // Logical 14 let and = true && false; // false 15 let or = true || false; // true 16 let not = !true; // false 17 18 // Type coercion! 19 let result = "5" + 3; // "53" (string) 20 let result2 = "5" - 3; // 2 (number!) ``` **Key characteristic:** Lots of implicit conversions *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 // Arithmetic 2 let sum = 5 + 3; // 8 3 let diff = 10 - 4; // 6 4 let product = 3 * 4; // 12 5 let quotient = 10 / 3; // 3 (integer division!) 6 let remainder = 10 % 3; // 1 7 let float_div = 10.0 / 3.0; // 3.333... 8 9 // Comparison 10 let equal = 5 == 5; // true (no ===!) 11 let not_equal = 5 != 6; // true 12 let greater = 10 > 5; // true 13 14 // Logical 15 let and = true && false; // false 16 let or = true || false; // true 17 let not = !true; // false 18 19 // No type coercion! 20 // let result = "5" + 3; // Error: can't add &str and i32 21 let result = "5".to_string() + &3.to_string(); // Explicit ``` **Key characteristic:** No implicit conversions, explicit types *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Arithmetic Operators [Section titled “Arithmetic Operators”](#arithmetic-operators) ```rust 1 let a = 10; 2 let b = 3; 3 4 // Basic arithmetic 5 let sum = a + b; // 13 6 let difference = a - b; // 7 7 let product = a * b; // 30 8 let quotient = a / b; // 3 (integer division!) 9 let remainder = a % b; // 1 10 11 // Unary minus 12 let negative = -a; // -10 13 14 // Compound assignment 15 let mut x = 5; 16 x += 3; // x = x + 3 → 8 17 x -= 2; // x = x - 2 → 6 18 x *= 4; // x = x * 4 → 24 19 x /= 3; // x = x / 3 → 8 20 x %= 5; // x = x % 5 → 3 ``` **Integer vs Float Division:** ```rust 1 // Integer division (truncates) 2 let a = 10 / 3; // 3 3 4 // Float division 5 let b = 10.0 / 3.0; // 3.333... 6 let c = 10 as f64 / 3 as f64; // 3.333... ``` **Compare to TypeScript:** ```typescript 1 let a = 10 / 3; // 3.333... (always float) 2 let b = Math.floor(10 / 3); // 3 (explicit truncation) ``` ### Comparison Operators [Section titled “Comparison Operators”](#comparison-operators) ```rust 1 let a = 5; 2 let b = 10; 3 4 // Equality 5 let eq = a == b; // false 6 let ne = a != b; // true 7 8 // Ordering 9 let gt = a > b; // false 10 let lt = a < b; // true 11 let ge = a >= b; // false 12 let le = a <= b; // true ``` **No `===` in Rust!** ```rust 1 // Rust only has == 2 let x = 5; 3 let y = 5; 4 let equal = x == y; // true 5 6 // TypeScript has == and === 7 // == does type coercion 8 // === doesn't ``` **In Rust, `==` is always strict** (no type coercion possible). ### Logical Operators [Section titled “Logical Operators”](#logical-operators) ```rust 1 let t = true; 2 let f = false; 3 4 // AND 5 let and1 = t && f; // false 6 let and2 = t && t; // true 7 8 // OR 9 let or1 = t || f; // true 10 let or2 = f || f; // false 11 12 // NOT 13 let not1 = !t; // false 14 let not2 = !f; // true ``` **Short-circuit evaluation (like TypeScript):** ```rust 1 fn expensive_check() -> bool { 2 println!("Called!"); 3 true 4 } 5 6 let x = false && expensive_check(); // "Called!" not printed 7 let y = true || expensive_check(); // "Called!" not printed ``` ### Bitwise Operators [Section titled “Bitwise Operators”](#bitwise-operators) ```rust 1 let a = 0b1100; // 12 in binary 2 let b = 0b1010; // 10 in binary 3 4 // Bitwise AND 5 let and = a & b; // 0b1000 (8) 6 7 // Bitwise OR 8 let or = a | b; // 0b1110 (14) 9 10 // Bitwise XOR 11 let xor = a ^ b; // 0b0110 (6) 12 13 // Bitwise NOT (! on integers, not just bools) 14 let not = !a; // -13: inverts all 32 bits of the i32 15 16 // Left shift 17 let left = a << 2; // 0b110000 (48) 18 19 // Right shift 20 let right = a >> 2; // 0b0011 (3) 21 22 // Compound assignment 23 let mut x = 5; 24 x &= 3; // x = x & 3 25 x |= 2; // x = x | 2 26 x ^= 1; // x = x ^ 1 27 x <<= 1; // x = x << 1 28 x >>= 1; // x = x >> 1 ``` **Compare to TypeScript:** ```typescript 1 let a = 12; 2 let b = 10; 3 4 let and = a & b; // 8 5 let or = a | b; // 14 6 let xor = a ^ b; // 6 7 let not = ~a; // -13 (two's complement) 8 let left = a << 2; // 48 9 let right = a >> 2; // 3 ``` **Same syntax, same behavior!** > **Note:** In Rust the same `!` does both **logical NOT** (on `bool`) and **bitwise NOT** (on integers): there is no separate `~` operator like JavaScript’s. For a signed integer, `!a` inverts all of its bits, which is equal to `-1 - a` (two’s complement). So with `a` inferred as `i32` and equal to `12`, `!a` is `-13`, matching JavaScript’s `~12`. On an unsigned type the result stays non-negative: `!0u8` is `255`. *** ## Key Differences from TypeScript [Section titled “Key Differences from TypeScript”](#key-differences-from-typescript) ### 1. No Type Coercion [Section titled “1. No Type Coercion”](#1-no-type-coercion) **TypeScript:** ```typescript 1 let x = "5" + 3; // "53" (string) 2 let y = "5" - 3; // 2 (number!) 3 let z = "5" == 5; // true with ==, false with === ``` **Rust:** ```rust 1 // let x = "5" + 3; // Error: can't add &str and i32 2 let x = format!("{}{}", "5", 3); // "53" 3 4 // let y = "5" - 3; // Error: can't subtract 5 let y = "5".parse::().unwrap() - 3; // 2 6 7 // let z = "5" == 5; // Error: mismatched types ``` > **Warning:** `.unwrap()` extracts the value from a `Result`/`Option`, but **panics** (crashes) if it is an error or `None`. It is fine for examples and throwaway code where you know the input is valid, but in real code you should handle the error case explicitly with `match`, the `?` operator, or `.expect("message")` (covered in the error handling section). ### 2. Integer Division [Section titled “2. Integer Division”](#2-integer-division) **TypeScript:** ```typescript 1 let x = 10 / 3; // 3.333... (always float) ``` **Rust:** ```rust 1 let x = 10 / 3; // 3 (integer division!) 2 let y = 10.0 / 3.0; // 3.333... (float division) ``` ### 3. No `===` Operator [Section titled “3. No === Operator”](#3-no--operator) **TypeScript:** ```typescript 1 5 == "5"; // true (type coercion) 2 5 === "5"; // false (strict equality) ``` **Rust:** ```rust 1 5 == 5; // true 2 // 5 == "5"; // Error: mismatched types ``` **Rust only has `==`, but it’s always strict!** ### 4. Overflow Behavior [Section titled “4. Overflow Behavior”](#4-overflow-behavior) **TypeScript:** ```typescript 1 let x: number = Number.MAX_SAFE_INTEGER; 2 x = x + 1; // Still works (but loses precision) ``` **Rust (debug mode):** ```rust 1 let mut x: i32 = i32::MAX; 2 // x = x + 1; // Panics! (overflow) 3 x = x.wrapping_add(1); // Wraps around ``` *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Integer Division Surprise [Section titled “Pitfall 1: Integer Division Surprise”](#pitfall-1-integer-division-surprise) **Problem:** ```rust 1 let average = (5 + 10) / 2; // Expected 7.5, got 7! ``` **Why:** Integer division truncates. **Solution:** ```rust 1 let average = (5.0 + 10.0) / 2.0; // 7.5 2 let average = (5 + 10) as f64 / 2.0; // 7.5 ``` ### Pitfall 2: Comparing Different Types [Section titled “Pitfall 2: Comparing Different Types”](#pitfall-2-comparing-different-types) **Problem:** ```rust 1 let x: i32 = 5; 2 let y: i64 = 5; 3 // if x == y { // Error: mismatched types ``` **Solution:** ```rust 1 let x: i32 = 5; 2 let y: i64 = 5; 3 if x as i64 == y { // Convert x to i64 4 println!("Equal!"); 5 } ``` ### Pitfall 3: Expecting `===` [Section titled “Pitfall 3: Expecting ===”](#pitfall-3-expecting-) **Problem:** ```rust 1 // if x === y { // Error: no operator === ``` **Solution:** ```rust 1 if x == y { // Use == 2 println!("Equal!"); 3 } ``` ### Pitfall 4: Overflow Without Handling [Section titled “Pitfall 4: Overflow Without Handling”](#pitfall-4-overflow-without-handling) **Problem:** ```rust 1 fn add_100(x: u8) -> u8 { 2 x + 100 // Panics in debug mode when x is 200! 3 } 4 5 fn main() { 6 println!("{}", add_100(200)); 7 } ``` Running this in debug mode panics with `thread 'main' panicked at ...: attempt to add with overflow`. > **Note:** If you instead write the overflow with two literals the compiler can see (for example `let y = 200u8 + 100;`), it does not even compile: you get `error: this arithmetic operation will overflow` at compile time. The runtime panic only happens when at least one operand isn’t a compile-time constant (here `x` arrives as a function argument). **Solution:** ```rust 1 let x: u8 = 200; 2 let y = x.saturating_add(100); // 255 (clamps) 3 let z = x.wrapping_add(100); // 44 (wraps) 4 let w = x.checked_add(100); // None (returns Option) ``` *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Use Explicit Types for Division [Section titled “1. Use Explicit Types for Division”](#1-use-explicit-types-for-division) ** Ambiguous:** ```rust 1 let result = total / count; // Integer or float division? ``` ** Explicit:** ```rust 1 let result = total as f64 / count as f64; // Clearly float division ``` ### 2. Use Checked Arithmetic for User Input [Section titled “2. Use Checked Arithmetic for User Input”](#2-use-checked-arithmetic-for-user-input) ** Risky:** ```rust 1 let result = user_a + user_b; // Could overflow! ``` ** Safe:** ```rust 1 let result = user_a.checked_add(user_b) 2 .expect("Overflow!"); ``` ### 3. Use Ranges for Bounds Checks [Section titled “3. Use Ranges for Bounds Checks”](#3-use-ranges-for-bounds-checks) Unlike Python, Rust has **no chained comparisons** (`0 < x < 100` does not parse). You either combine two comparisons with `&&`, or — often clearer — use a range’s `.contains()` method: ** Verbose:** ```rust 1 if x > 0 && x < 100 { 2 // ... 3 } ``` ** Clear (when appropriate):** ```rust 1 if (0..100).contains(&x) { 2 // ... 3 } ``` ### 4. Parenthesize Complex Expressions [Section titled “4. Parenthesize Complex Expressions”](#4-parenthesize-complex-expressions) ** Hard to read:** ```rust 1 let result = a + b * c - d / e; ``` ** Clear:** ```rust 1 let result = a + (b * c) - (d / e); ``` *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) ### Temperature Conversion [Section titled “Temperature Conversion”](#temperature-conversion) **TypeScript:** ```typescript 1 function celsiusToFahrenheit(celsius: number): number { 2 return (celsius * 9) / 5 + 32; 3 } 4 5 function fahrenheitToCelsius(fahrenheit: number): number { 6 return ((fahrenheit - 32) * 5) / 9; 7 } 8 9 console.log(celsiusToFahrenheit(0)); // 32 10 console.log(fahrenheitToCelsius(32)); // 0 ``` **Rust:** ```rust 1 fn celsius_to_fahrenheit(celsius: f64) -> f64 { 2 (celsius * 9.0) / 5.0 + 32.0 3 } 4 5 fn fahrenheit_to_celsius(fahrenheit: f64) -> f64 { 6 (fahrenheit - 32.0) * 5.0 / 9.0 7 } 8 9 fn main() { 10 println!("{}", celsius_to_fahrenheit(0.0)); // 32 11 println!("{}", fahrenheit_to_celsius(32.0)); // 0 12 } ``` ### Calculating Percentage [Section titled “Calculating Percentage”](#calculating-percentage) **TypeScript:** ```typescript 1 function percentage(value: number, total: number): number { 2 return (value / total) * 100; 3 } 4 5 console.log(percentage(25, 100)); // 25 6 console.log(percentage(1, 3)); // 33.333... ``` **Rust:** ```rust 1 fn percentage(value: f64, total: f64) -> f64 { 2 (value / total) * 100.0 3 } 4 5 fn main() { 6 println!("{}", percentage(25.0, 100.0)); // 25 7 println!("{:.2}", percentage(1.0, 3.0)); // 33.33 8 } ``` ### Bit Manipulation (Flags) [Section titled “Bit Manipulation (Flags)”](#bit-manipulation-flags) ```rust 1 // Permission flags using bitwise operations 2 const READ: u8 = 0b0001; // 1 3 const WRITE: u8 = 0b0010; // 2 4 const EXECUTE: u8 = 0b0100; // 4 5 const DELETE: u8 = 0b1000; // 8 6 7 fn main() { 8 // Combine permissions 9 let perms = READ | WRITE; // 0b0011 (3) 10 11 // Check permission 12 let has_read = (perms & READ) != 0; // true 13 let has_exec = (perms & EXECUTE) != 0; // false 14 15 // Add permission 16 let perms = perms | EXECUTE; // 0b0111 (7) 17 18 // Remove permission 19 let perms = perms & !WRITE; // 0b0101 (5) 20 21 println!("Permissions: {:04b}", perms); // 0101 22 } ``` *** ## Operator Precedence [Section titled “Operator Precedence”](#operator-precedence) From highest to lowest: 1. Unary: `-`, `!` 2. Multiplicative: `*`, `/`, `%` 3. Additive: `+`, `-` 4. Shift: `<<`, `>>` 5. Bitwise AND: `&` 6. Bitwise XOR: `^` 7. Bitwise OR: `|` 8. Comparison: `==`, `!=`, `<`, `>`, `<=`, `>=` 9. Logical AND: `&&` 10. Logical OR: `||` **Use parentheses when in doubt!** ```rust 1 let result = a + b * c; // b * c first 2 let result = (a + b) * c; // a + b first ``` *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book - Operators](https://doc.rust-lang.org/book/appendix-02-operators.html) * [Rust Reference - Operators](https://doc.rust-lang.org/reference/expressions/operator-expr.html) * [Rust by Example - Operations](https://doc.rust-lang.org/rust-by-example/primitives.html) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Fix Division [Section titled “Exercise 1: Fix Division”](#exercise-1-fix-division) Fix this to return a float: ```rust 1 fn average(a: i32, b: i32) -> f64 { 2 (a + b) / 2 // Returns integer! 3 } 4 5 fn main() { 6 println!("{}", average(5, 10)); // Should be 7.5 7 } ``` Solution ```rust 1 fn average(a: i32, b: i32) -> f64 { 2 (a + b) as f64 / 2.0 3 } 4 5 fn main() { 6 println!("{}", average(5, 10)); // 7.5 7 } ``` ### Exercise 2: Check Range [Section titled “Exercise 2: Check Range”](#exercise-2-check-range) Check if a number is in range 10-20 (inclusive): ```rust 1 fn in_range(x: i32) -> bool { 2 // Implement 3 } 4 5 fn main() { 6 println!("{}", in_range(15)); // true 7 println!("{}", in_range(25)); // false 8 } ``` Solution ```rust 1 fn in_range(x: i32) -> bool { 2 x >= 10 && x <= 20 3 } 4 5 fn main() { 6 println!("{}", in_range(15)); // true 7 println!("{}", in_range(25)); // false 8 } ``` ### Exercise 3: Swap Values [Section titled “Exercise 3: Swap Values”](#exercise-3-swap-values) Swap two values without a temporary variable: ```rust 1 fn main() { 2 let mut a = 5; 3 let mut b = 10; 4 5 // Swap a and b 6 // Hint: Rust gives you two idiomatic, overflow-safe ways 7 8 println!("a: {}, b: {}", a, b); // Should be a: 10, b: 5 9 } ``` Solution The classic “arithmetic swap” (`a = a + b; b = a - b; a = a - b;`) works for small numbers but **overflows and panics in debug** when the values are near the integer bounds (e.g. `a = i32::MAX`). Rust gives you two safe, idiomatic alternatives instead: ```rust 1 fn main() { 2 // Option 1: tuple destructuring assignment 3 let mut a = 5; 4 let mut b = 10; 5 (a, b) = (b, a); 6 println!("a: {}, b: {}", a, b); // a: 10, b: 5 7 8 // Option 2: std::mem::swap 9 let mut c = 5; 10 let mut d = 10; 11 std::mem::swap(&mut c, &mut d); 12 println!("c: {}, d: {}", c, d); // c: 10, d: 5 13 } ``` > **Warning:** The arithmetic trick (`a = a + b; ...`) is a classic interview puzzle, but it is fragile: `a + b` can overflow. In debug builds Rust **panics**, in release builds it **wraps** to the wrong answer. Prefer tuple destructuring or `std::mem::swap`. ### Exercise 4: Check Power of Two [Section titled “Exercise 4: Check Power of Two”](#exercise-4-check-power-of-two) Check if a number is a power of 2 using bitwise operations: ```rust 1 fn is_power_of_two(n: u32) -> bool { 2 // Hint: Powers of 2 have only one bit set 3 // n & (n - 1) == 0 for powers of 2 4 } 5 6 fn main() { 7 println!("{}", is_power_of_two(8)); // true 8 println!("{}", is_power_of_two(10)); // false 9 println!("{}", is_power_of_two(16)); // true 10 } ``` Solution ```rust 1 fn is_power_of_two(n: u32) -> bool { 2 n != 0 && (n & (n - 1)) == 0 3 } 4 5 fn main() { 6 println!("{}", is_power_of_two(8)); // true 7 println!("{}", is_power_of_two(10)); // false 8 println!("{}", is_power_of_two(16)); // true 9 } ``` *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * Arithmetic operators (`+`, `-`, `*`, `/`, `%`) * Comparison operators (`==`, `!=`, `<`, `>`, etc.) * Logical operators (`&&`, `||`, `!`) * Bitwise operators (`&`, `|`, `^`, `<<`, `>>`) * No type coercion in Rust * Integer vs float division * Operator precedence **Key differences from TypeScript:** | Aspect | TypeScript | Rust | | ------------- | --------------------- | ------------------------------- | | Equality | `==`, `===` | Only `==` (strict) | | Division | Always float | Integer if integers | | Type coercion | Implicit | Never! | | Overflow | Loses precision (f64) | Panics (debug), wraps (release) | **Operators work mostly the same, but Rust is more strict!** # Comments and Documentation > Comments in Rust are similar to TypeScript/JavaScript, with built-in additions for generating documentation automatically. Comments in Rust are similar to TypeScript/JavaScript, with built-in additions for generating documentation automatically. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Rust has three types of comments: * **Regular comments:** `//` and `/* */` (like JS/TS) * **Doc comments:** `///` and `//!` (generates HTML docs!) * **No JSDoc needed:** Built into the language **Doc comments are a first-class feature in Rust!** *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // Single-line comment 2 3 /* 4 Multi-line comment 5 across several lines 6 */ 7 8 /** 9 * JSDoc documentation comment 10 * @param name - User's name 11 * @param age - User's age 12 * @returns Greeting message 13 */ 14 function greet(name: string, age: number): string { 15 return `Hello, ${name}! You are ${age} years old.`; 16 } 17 18 // Inline comment at end of line 19 let x = 5; // This is x ``` **JSDoc is a convention, not built into JavaScript.** *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 // Single-line comment 2 3 /* 4 Multi-line comment 5 across several lines 6 */ 7 8 /// Documentation comment for the function 9 /// 10 /// # Arguments 11 /// * `name` - User's name 12 /// * `age` - User's age 13 /// 14 /// # Returns 15 /// A greeting message 16 fn greet(name: &str, age: u32) -> String { 17 format!("Hello, {}! You are {} years old.", name, age) 18 } 19 20 // Inline comment at end of line 21 let x = 5; // This is x ``` **Doc comments are built into Rust and generate HTML docs!** *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Regular Comments [Section titled “Regular Comments”](#regular-comments) ```rust 1 // This is a single-line comment 2 3 // You can chain them 4 // to create multiple lines 5 // of comments 6 7 /* This is a multi-line comment */ 8 9 /* 10 Multi-line comments 11 can span multiple lines 12 and can /* nest */ too! 13 */ 14 15 fn main() { 16 let x = 5; // Inline comment 17 // let y = 10; // Commented-out code 18 } ``` **Same as TypeScript/JavaScript!** ### Documentation Comments [Section titled “Documentation Comments”](#documentation-comments) **Outer doc comments** (document the item that follows): ````rust 1 /// Adds two numbers together 2 /// 3 /// # Examples 4 /// 5 /// ``` 6 /// let result = add(2, 3); 7 /// assert_eq!(result, 5); 8 /// ``` 9 fn add(a: i32, b: i32) -> i32 { 10 a + b 11 } ```` **Inner doc comments** (document the enclosing item): ```rust 1 //! This module provides math utilities 2 //! 3 //! It includes functions for basic arithmetic operations. 4 5 fn add(a: i32, b: i32) -> i32 { 6 a + b 7 } ``` **Generate HTML docs:** ```bash 1 cargo doc --open ``` This creates beautiful HTML documentation automatically! ### Doc Comment Structure [Section titled “Doc Comment Structure”](#doc-comment-structure) **Common sections:** ````rust 1 /// Brief description (one line) 2 /// 3 /// More detailed explanation can go here 4 /// across multiple lines. 5 /// 6 /// # Arguments 7 /// * `x` - The first number 8 /// * `y` - The second number 9 /// 10 /// # Returns 11 /// The sum of x and y 12 /// 13 /// # Examples 14 /// ``` 15 /// let result = add(5, 3); 16 /// assert_eq!(result, 8); 17 /// ``` 18 /// 19 /// # Panics 20 /// This function panics if... 21 /// 22 /// # Errors 23 /// Returns an error if... 24 /// 25 /// # Safety 26 /// This function is unsafe because... 27 fn add(x: i32, y: i32) -> i32 { 28 x + y 29 } ```` **Markdown supported:** ````rust 1 /// This function uses **bold** and *italic* 2 /// 3 /// # Examples 4 /// 5 /// ``` 6 /// let x = my_func(); 7 /// ``` 8 /// 9 /// See also: [other_func] 10 fn my_func() -> i32 { 11 42 12 } ```` ### Code Examples in Docs [Section titled “Code Examples in Docs”](#code-examples-in-docs) ````rust 1 /// Multiplies two numbers 2 /// 3 /// # Examples 4 /// 5 /// ``` 6 /// let result = multiply(2, 3); 7 /// assert_eq!(result, 6); 8 /// ``` 9 /// 10 /// This example shows error handling: 11 /// ``` 12 /// let result = checked_multiply(i32::MAX, 2); 13 /// assert!(result.is_none()); 14 /// ``` 15 fn multiply(a: i32, b: i32) -> i32 { 16 a * b 17 } ```` **Examples are automatically tested!** ```bash 1 cargo test --doc ``` This runs all code examples in your documentation. > **Note:** Each example is compiled and run as its own small crate that depends on yours, so anything it references (your functions, types, etc.) must be `pub` and brought into scope with `use`. To keep that setup out of the rendered docs, prefix the line with `#` (see Pitfall 3 below). *** ## Key Differences from TypeScript/JavaScript [Section titled “Key Differences from TypeScript/JavaScript”](#key-differences-from-typescriptjavascript) ### 1. Built-in Documentation [Section titled “1. Built-in Documentation”](#1-built-in-documentation) **TypeScript:** ```typescript 1 /** 2 * JSDoc comment (convention, not part of TS) 3 * @param x - Number 4 * @returns Result 5 */ 6 function double(x: number): number { 7 return x * 2; 8 } 9 10 // Need external tool (TypeDoc) to generate docs ``` **Rust:** ```rust 1 /// Documentation comment (built into Rust!) 2 /// 3 /// # Arguments 4 /// * `x` - Number 5 /// 6 /// # Returns 7 /// Result 8 fn double(x: i32) -> i32 { 9 x * 2 10 } 11 12 // cargo doc generates HTML automatically ``` ### 2. Testable Examples [Section titled “2. Testable Examples”](#2-testable-examples) **TypeScript:** ````typescript 1 /** 2 * @example 3 * ```typescript 4 * const result = add(2, 3); 5 * // Examples are not automatically tested 6 * ``` 7 */ ```` **Rust:** ````rust 1 /// # Examples 2 /// ``` 3 /// let result = add(2, 3); 4 /// assert_eq!(result, 5); 5 /// // This example is automatically tested! 6 /// ``` ```` ### 3. Nested Comments [Section titled “3. Nested Comments”](#3-nested-comments) **JavaScript:** ```javascript 1 /* 2 /* This won't work! */ 3 Can't nest multi-line comments 4 */ ``` **Rust:** ```rust 1 /* 2 /* This works! */ 3 Rust supports nested comments 4 */ ``` *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Using JSDoc Style [Section titled “Pitfall 1: Using JSDoc Style”](#pitfall-1-using-jsdoc-style) **Problem:** ```rust 1 /** 2 * @param x - A number 3 * @returns The doubled value 4 */ 5 fn double(x: i32) -> i32 { 6 x * 2 7 } ``` **Why:** This works, but isn’t idiomatic Rust. **Solution:** ```rust 1 /// Doubles a number 2 /// 3 /// # Arguments 4 /// * `x` - A number 5 /// 6 /// # Returns 7 /// The doubled value 8 fn double(x: i32) -> i32 { 9 x * 2 10 } ``` ### Pitfall 2: Forgetting Outer Doc Comment After Inner [Section titled “Pitfall 2: Forgetting Outer Doc Comment After Inner”](#pitfall-2-forgetting-outer-doc-comment-after-inner) **Problem:** ```rust 1 //! Module documentation 2 3 fn my_func() { // No doc comment! 4 // ... 5 } ``` **Solution:** ```rust 1 //! Module documentation 2 3 /// Function documentation 4 fn my_func() { 5 // ... 6 } ``` ### Pitfall 3: Items Not in Scope in Doc Examples [Section titled “Pitfall 3: Items Not in Scope in Doc Examples”](#pitfall-3-items-not-in-scope-in-doc-examples) **Problem:** ````rust 1 /// # Examples 2 /// ``` 3 /// let result = add(2, 3); // Will fail doc test! 4 /// assert_eq!(result, 5); 5 /// ``` 6 pub fn add(a: i32, b: i32) -> i32 { 7 a + b 8 } ```` **Why:** A doc test is compiled as a **separate crate** that depends on yours, so your item is not automatically in scope. The example above fails with `error[E0425]: cannot find function add in this scope` and a help line suggesting `use your_crate::add;`. (Note: a missing `main` is *not* the cause — rustdoc automatically wraps each example in a `main` function for you.) **Solution:** ````rust 1 /// # Examples 2 /// ``` 3 /// # use your_crate::add; 4 /// let result = add(2, 3); 5 /// assert_eq!(result, 5); 6 /// ``` 7 pub fn add(a: i32, b: i32) -> i32 { 8 a + b 9 } ```` Use a `#`-prefixed line to hide setup (such as `use` imports) from the rendered docs while still compiling and running it in the test. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Use Doc Comments for Public API [Section titled “1. Use Doc Comments for Public API”](#1-use-doc-comments-for-public-api) ** Don’t document everything:** ```rust 1 // Helper function 2 fn internal_helper(x: i32) -> i32 { 3 x * 2 4 } 5 6 /// Public API should be documented 7 pub fn public_api(x: i32) -> i32 { 8 internal_helper(x) 9 } ``` ** Document public items:** ````rust 1 // Internal, no doc comment needed 2 fn internal_helper(x: i32) -> i32 { 3 x * 2 4 } 5 6 /// Doubles the input number 7 /// 8 /// # Examples 9 /// ``` 10 /// let result = public_api(5); 11 /// assert_eq!(result, 10); 12 /// ``` 13 pub fn public_api(x: i32) -> i32 { 14 internal_helper(x) 15 } ```` ### 2. Include Examples [Section titled “2. Include Examples”](#2-include-examples) ** Just describe:** ```rust 1 /// Adds two numbers 2 fn add(a: i32, b: i32) -> i32 { 3 a + b 4 } ``` ** Show how to use:** ````rust 1 /// Adds two numbers 2 /// 3 /// # Examples 4 /// ``` 5 /// let sum = add(2, 3); 6 /// assert_eq!(sum, 5); 7 /// ``` 8 fn add(a: i32, b: i32) -> i32 { 9 a + b 10 } ```` ### 3. Document Panics and Errors [Section titled “3. Document Panics and Errors”](#3-document-panics-and-errors) ** Don’t hide gotchas:** ```rust 1 /// Divides two numbers 2 fn divide(a: i32, b: i32) -> i32 { 3 a / b // Panics if b is 0! 4 } ``` ** Document behavior:** ````rust 1 /// Divides two numbers 2 /// 3 /// # Panics 4 /// Panics if `b` is zero 5 /// 6 /// # Examples 7 /// ``` 8 /// let result = divide(10, 2); 9 /// assert_eq!(result, 5); 10 /// ``` 11 fn divide(a: i32, b: i32) -> i32 { 12 a / b 13 } ```` ### 4. Use Markdown for Formatting [Section titled “4. Use Markdown for Formatting”](#4-use-markdown-for-formatting) ** Plain text:** ```rust 1 /// Returns the user's age. 2 /// Arguments: 3 /// - name: the user's name 4 /// - id: the user's ID ``` ** Use Markdown:** ```rust 1 /// Returns the user's age 2 /// 3 /// # Arguments 4 /// * `name` - The user's name 5 /// * `id` - The user's ID 6 /// 7 /// # Returns 8 /// The user's age as `u32` ``` *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) ### Documented Math Module [Section titled “Documented Math Module”](#documented-math-module) **TypeScript:** ```typescript 1 /** 2 * Math utilities module 3 */ 4 5 /** 6 * Calculates the factorial of a number 7 * @param n - The number to calculate factorial for 8 * @returns The factorial of n 9 * @throws Error if n is negative 10 */ 11 export function factorial(n: number): number { 12 if (n < 0) throw new Error("Negative number"); 13 if (n === 0) return 1; 14 return n * factorial(n - 1); 15 } 16 17 /** 18 * Checks if a number is prime 19 * @param n - The number to check 20 * @returns true if prime, false otherwise 21 */ 22 export function isPrime(n: number): boolean { 23 if (n < 2) return false; 24 for (let i = 2; i <= Math.sqrt(n); i++) { 25 if (n % i === 0) return false; 26 } 27 return true; 28 } ``` **Rust:** ````rust 1 //! Math utilities module 2 //! 3 //! This module provides common mathematical functions. 4 5 /// Calculates the factorial of a number 6 /// 7 /// # Arguments 8 /// * `n` - The number to calculate factorial for 9 /// 10 /// # Returns 11 /// The factorial of n 12 /// 13 /// # Panics 14 /// Panics if `n` is negative 15 /// 16 /// # Examples 17 /// ``` 18 /// # use math::factorial; 19 /// let result = factorial(5); 20 /// assert_eq!(result, 120); 21 /// ``` 22 pub fn factorial(n: i32) -> i32 { 23 assert!(n >= 0, "factorial is undefined for negative numbers"); 24 if n == 0 { 25 1 26 } else { 27 n * factorial(n - 1) 28 } 29 } 30 31 /// Checks if a number is prime 32 /// 33 /// # Arguments 34 /// * `n` - The number to check 35 /// 36 /// # Returns 37 /// `true` if prime, `false` otherwise 38 /// 39 /// # Examples 40 /// ``` 41 /// # use math::is_prime; 42 /// assert!(is_prime(7)); 43 /// assert!(!is_prime(8)); 44 /// ``` 45 pub fn is_prime(n: u32) -> bool { 46 if n < 2 { 47 return false; 48 } 49 // Use integer arithmetic (`i * i <= n`) for the loop bound. Converting 50 // to `f64` and calling `.sqrt()` works for small values but is a fragile 51 // idiom: float rounding can make the bound off by one for large inputs. 52 let mut i = 2; 53 while i * i <= n { 54 if n % i == 0 { 55 return false; 56 } 57 i += 1; 58 } 59 true 60 } ```` > **Note:** The TypeScript `factorial` above signals invalid input with `throw new Error(...)`, which is a *recoverable* error a caller can catch. The Rust version uses `assert!`/`panic!` to keep the comparison short, but in idiomatic Rust a recoverable failure like this is normally modeled with a return type of `Result` (covered in the error-handling section) rather than a panic. Reserve `panic!` for genuinely unrecoverable bugs. **Generate docs:** ```bash 1 cargo doc --open ``` Beautiful HTML documentation is generated automatically! *** ## Doc Comment Sections [Section titled “Doc Comment Sections”](#doc-comment-sections) Common sections in Rust doc comments: ### Standard Sections [Section titled “Standard Sections”](#standard-sections) ```rust 1 /// Brief one-line description 2 /// 3 /// # Arguments 4 /// Parameter documentation 5 /// 6 /// # Returns 7 /// Return value documentation 8 /// 9 /// # Errors 10 /// Error conditions (for Result) 11 /// 12 /// # Panics 13 /// Panic conditions 14 /// 15 /// # Safety 16 /// Safety requirements (for unsafe) 17 /// 18 /// # Examples 19 /// Usage examples 20 /// 21 /// # See Also 22 /// Related functions ``` ### Custom Sections [Section titled “Custom Sections”](#custom-sections) You can create custom sections: ```rust 1 /// My function 2 /// 3 /// # Performance 4 /// This function runs in O(n) time 5 /// 6 /// # Thread Safety 7 /// This function is thread-safe 8 fn my_func() { 9 // ... 10 } ``` *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book - Comments](https://doc.rust-lang.org/book/ch03-04-comments.html) * [Rust Reference - Comments](https://doc.rust-lang.org/reference/comments.html) * [rustdoc Book](https://doc.rust-lang.org/rustdoc/) ### Related Topics [Section titled “Related Topics”](#related-topics) * [Documentation Guidelines](https://rust-lang.github.io/api-guidelines/documentation.html) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Add Documentation [Section titled “Exercise 1: Add Documentation”](#exercise-1-add-documentation) Add doc comments to this function: ```rust 1 fn square(x: i32) -> i32 { 2 x * x 3 } ``` Solution ````rust 1 /// Calculates the square of a number 2 /// 3 /// # Arguments 4 /// * `x` - The number to square 5 /// 6 /// # Returns 7 /// The square of `x` 8 /// 9 /// # Examples 10 /// ``` 11 /// let result = square(5); 12 /// assert_eq!(result, 25); 13 /// ``` 14 fn square(x: i32) -> i32 { 15 x * x 16 } ```` ### Exercise 2: Document Panic Condition [Section titled “Exercise 2: Document Panic Condition”](#exercise-2-document-panic-condition) Document the panic condition: ```rust 1 fn divide(a: i32, b: i32) -> i32 { 2 if b == 0 { 3 panic!("Division by zero!"); 4 } 5 a / b 6 } ``` Solution ````rust 1 /// Divides two numbers 2 /// 3 /// # Arguments 4 /// * `a` - The dividend 5 /// * `b` - The divisor 6 /// 7 /// # Returns 8 /// The result of a / b 9 /// 10 /// # Panics 11 /// Panics if `b` is zero 12 /// 13 /// # Examples 14 /// ``` 15 /// let result = divide(10, 2); 16 /// assert_eq!(result, 5); 17 /// ``` 18 fn divide(a: i32, b: i32) -> i32 { 19 if b == 0 { 20 panic!("Division by zero!"); 21 } 22 a / b 23 } ```` ### Exercise 3: Module Documentation [Section titled “Exercise 3: Module Documentation”](#exercise-3-module-documentation) Add module-level documentation: math.rs ```rust 1 pub fn add(a: i32, b: i32) -> i32 { 2 a + b 3 } 4 5 pub fn subtract(a: i32, b: i32) -> i32 { 6 a - b 7 } ``` Solution ````rust 1 //! Math utilities module 2 //! 3 //! This module provides basic arithmetic operations. 4 //! 5 //! # Examples 6 //! ``` 7 //! let sum = math::add(2, 3); 8 //! assert_eq!(sum, 5); 9 //! ``` 10 11 /// Adds two numbers 12 /// 13 /// # Examples 14 /// ``` 15 /// let result = add(2, 3); 16 /// assert_eq!(result, 5); 17 /// ``` 18 pub fn add(a: i32, b: i32) -> i32 { 19 a + b 20 } 21 22 /// Subtracts two numbers 23 /// 24 /// # Examples 25 /// ``` 26 /// let result = subtract(5, 3); 27 /// assert_eq!(result, 2); 28 /// ``` 29 pub fn subtract(a: i32, b: i32) -> i32 { 30 a - b 31 } ```` *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * Regular comments (`//`, `/* */`) * Doc comments (`///`, `//!`) * Doc comment structure (Arguments, Returns, Examples, etc.) * Markdown in doc comments * Testable code examples * Generating HTML documentation **Key differences from TypeScript:** | Feature | TypeScript | Rust | | ---------------- | ------------------ | ----------------------- | | Regular comments | `//`, `/* */` | Same | | Doc comments | JSDoc (convention) | `///`, `//!` (built-in) | | Doc generation | TypeDoc (external) | `cargo doc` (built-in) | | Example testing | Manual | Automatic | | Nested comments | No | Yes | **Doc comments are a first-class feature in Rust!** # Output and Formatting > Learn how to print output in Rust using the println! macro and its rich formatting capabilities. Learn how to print output in Rust using the `println!` macro and its rich formatting capabilities. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Rust uses macros for printing: * `println!()` - Print with newline * `print!()` - Print without newline * Format strings use `{}` placeholders * Rich formatting options built-in **Similar to Python’s f-strings or C’s printf!** *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // Simple printing 2 console.log("Hello, world!"); 3 4 // With variables 5 const name = "Alice"; 6 const age = 30; 7 8 // Template literals 9 console.log(`Hello, ${name}!`); 10 console.log(`${name} is ${age} years old`); 11 12 // Multiple values 13 console.log("Name:", name, "Age:", age); 14 15 // Formatting numbers 16 const pi = 3.14159; 17 console.log(pi.toFixed(2)); // "3.14" 18 19 // Objects 20 const user = { name: "Bob", age: 25 }; 21 console.log(user); // { name: 'Bob', age: 25 } 22 console.log(JSON.stringify(user)); // {"name":"Bob","age":25} ``` **TypeScript uses template literals and method calls.** *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 // Simple printing 2 println!("Hello, world!"); 3 4 // With variables 5 let name = "Alice"; 6 let age = 30; 7 8 // Format strings 9 println!("Hello, {}!", name); 10 println!("{} is {} years old", name, age); 11 12 // Inline capture (placeholder names a variable in scope) 13 println!("Hello, {name}!"); 14 15 // Named arguments (placeholder maps to an explicit value) 16 println!("Hello, {who}!", who = name); 17 18 // Formatting numbers 19 let pi = 3.14159; 20 println!("{:.2}", pi); // "3.14" 21 22 // Debug formatting 23 let user = ("Bob", 25); 24 println!("{:?}", user); // ("Bob", 25) 25 26 // Pretty debug 27 println!("{:#?}", user); ``` **Rust uses macros with expressive format strings.** *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Basic Printing [Section titled “Basic Printing”](#basic-printing) ```rust 1 fn main() { 2 // Print with newline 3 println!("Hello!"); 4 println!("World!"); 5 6 // Print without newline 7 print!("Hello, "); 8 print!("World!\n"); 9 10 // Print to stderr 11 eprintln!("Error message!"); 12 } ``` **Output:** ```plaintext 1 Hello! 2 World! 3 Hello, World! 4 Error message! ``` ### Placeholders [Section titled “Placeholders”](#placeholders) ```rust 1 fn main() { 2 let name = "Alice"; 3 let age = 30; 4 5 // Positional 6 println!("{} is {} years old", name, age); 7 8 // Indexed 9 println!("{0} is {1} years old", name, age); 10 println!("{1} is the age of {0}", name, age); // Reorder! 11 12 // Inline capture (names a variable already in scope) 13 println!("{name} is {age} years old"); 14 15 // Named arguments (the placeholder maps to a value you pass) 16 println!("{who} is {years} years old", who = name, years = age); 17 18 // Mixed positional and named 19 println!("{0} is {years} years old", name, years = age); 20 } ``` **Compare to TypeScript:** ```typescript 1 const name = "Alice"; 2 const age = 30; 3 4 // Template literals 5 console.log(`${name} is ${age} years old`); 6 7 // Only sequential order possible ``` ### Display vs Debug [Section titled “Display vs Debug”](#display-vs-debug) **Display (`{}`)** - Human-readable output: ```rust 1 let x = 42; 2 let s = "hello"; 3 let b = true; 4 5 println!("{}", x); // 42 6 println!("{}", s); // hello 7 println!("{}", b); // true ``` **Debug (`{:?}`)** - Programmer-friendly output: ```rust 1 let tuple = (1, "hello", true); 2 let vec = vec![1, 2, 3]; 3 4 // println!("{}", tuple); // Error: tuples don't implement Display 5 println!("{:?}", tuple); // (1, "hello", true) 6 println!("{:?}", vec); // [1, 2, 3] ``` **Pretty Debug (`{:#?}`)** - Formatted debug: ```rust 1 let data = vec![ 2 ("Alice", 30), 3 ("Bob", 25), 4 ("Charlie", 35), 5 ]; 6 7 println!("{:#?}", data); ``` **Output:** ```plaintext 1 [ 2 ( 3 "Alice", 4 30, 5 ), 6 ( 7 "Bob", 8 25, 9 ), 10 ( 11 "Charlie", 12 35, 13 ), 14 ] ``` ### Number Formatting [Section titled “Number Formatting”](#number-formatting) ```rust 1 let pi = 3.14159; 2 3 // Decimal places 4 println!("{:.2}", pi); // 3.14 5 println!("{:.4}", pi); // 3.1416 6 7 // Width and alignment 8 println!("{:10}", 42); // " 42" (right-aligned) 9 println!("{:<10}", 42); // "42 " (left-aligned) 10 println!("{:^10}", 42); // " 42 " (centered) 11 12 // Zero-padding 13 println!("{:05}", 42); // 00042 14 15 // Sign 16 println!("{:+}", 42); // +42 17 println!("{:+}", -42); // -42 18 19 // Hexadecimal 20 println!("{:x}", 255); // ff 21 println!("{:X}", 255); // FF 22 println!("{:#x}", 255); // 0xff 23 24 // Binary 25 println!("{:b}", 42); // 101010 26 println!("{:#b}", 42); // 0b101010 27 28 // Octal 29 println!("{:o}", 42); // 52 30 println!("{:#o}", 42); // 0o52 ``` **Compare to TypeScript:** ```typescript 1 const pi = 3.14159; 2 3 console.log(pi.toFixed(2)); // "3.14" 4 console.log(pi.toPrecision(4)); // "3.142" 5 6 const n = 255; 7 console.log(n.toString(16)); // "ff" 8 console.log(n.toString(2)); // "11111111" ``` ### String Formatting [Section titled “String Formatting”](#string-formatting) ```rust 1 let name = "Alice"; 2 3 // Truncate 4 println!("{:.5}", name); // Alice (already < 5) 5 println!("{:.3}", name); // Ali 6 7 // Width and fill 8 println!("{:10}", name); // "Alice " 9 println!("{:<10}", name); // "Alice " (left) 10 println!("{:>10}", name); // " Alice" (right) 11 println!("{:^10}", name); // " Alice " (center) 12 println!("{:*<10}", name); // "Alice*****" (custom fill) ``` ### Escape Sequences [Section titled “Escape Sequences”](#escape-sequences) ```rust 1 println!("New line\n"); 2 println!("Tab\there"); 3 println!("Backslash: \\"); 4 println!("Quote: \""); 5 println!("Single quote: \'"); 6 println!("Unicode: \u{1F44D}"); // ``` ### Format! Macro [Section titled “Format! Macro”](#format-macro) Create formatted strings without printing: ```rust 1 let name = "Alice"; 2 let age = 30; 3 4 // Create a String 5 let s = format!("{} is {} years old", name, age); 6 println!("{}", s); // Alice is 30 years old 7 8 // Useful for building strings 9 let filename = format!("report_{}.txt", 2024); ``` **Compare to TypeScript:** ```typescript 1 const name = "Alice"; 2 const age = 30; 3 4 const s = `${name} is ${age} years old`; 5 console.log(s); ``` *** ## Key Differences from TypeScript/JavaScript [Section titled “Key Differences from TypeScript/JavaScript”](#key-differences-from-typescriptjavascript) ### 1. Macros vs Functions [Section titled “1. Macros vs Functions”](#1-macros-vs-functions) **TypeScript:** ```typescript 1 console.log("Hello"); // Function call ``` **Rust:** ```rust 1 println!("Hello"); // Macro invocation (note the !) ``` **Why macros?** They’re expanded at compile time and can check format strings! ### 2. Format String Syntax [Section titled “2. Format String Syntax”](#2-format-string-syntax) **TypeScript:** ```typescript 1 const name = "Alice"; 2 console.log(`Hello, ${name}!`); // Template literal ``` **Rust:** ```rust 1 let name = "Alice"; 2 println!("Hello, {}!", name); // Format string ``` ### 3. Debug Printing [Section titled “3. Debug Printing”](#3-debug-printing) **TypeScript:** ```typescript 1 const obj = { name: "Alice", age: 30 }; 2 console.log(obj); // Pretty print in browser/Node.js 3 console.log(JSON.stringify(obj)); // Manual serialization ``` **Rust:** ```rust 1 let tuple = ("Alice", 30); 2 // println!("{}", tuple); // Error 3 println!("{:?}", tuple); // Debug format 4 println!("{:#?}", tuple); // Pretty debug ``` ### 4. Number Formatting [Section titled “4. Number Formatting”](#4-number-formatting) **TypeScript:** ```typescript 1 const n = 42; 2 console.log(n.toString(16)); // "2a" (hex) 3 console.log(n.toString(2)); // "101010" (binary) ``` **Rust:** ```rust 1 let n = 42; 2 println!("{:x}", n); // 2a (hex) 3 println!("{:b}", n); // 101010 (binary) ``` *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting Braces [Section titled “Pitfall 1: Forgetting Braces”](#pitfall-1-forgetting-braces) **Problem:** ```rust 1 let name = "Alice"; 2 println!("Hello, name!"); // Prints literally "Hello, name!" ``` **Solution:** ```rust 1 let name = "Alice"; 2 println!("Hello, {}!", name); // "Hello, Alice!" ``` ### Pitfall 2: Type Doesn’t Implement Display [Section titled “Pitfall 2: Type Doesn’t Implement Display”](#pitfall-2-type-doesnt-implement-display) **Problem:** ```rust 1 let tuple = (1, 2); 2 println!("{}", tuple); // Error: tuple doesn't implement Display ``` **Solution:** ```rust 1 let tuple = (1, 2); 2 println!("{:?}", tuple); // Use debug format ``` ### Pitfall 3: Wrong Number of Arguments [Section titled “Pitfall 3: Wrong Number of Arguments”](#pitfall-3-wrong-number-of-arguments) **Problem:** ```rust 1 println!("{} and {}", 42); // Error: 2 placeholders, 1 argument ``` **Solution:** ```rust 1 println!("{} and {}", 42, 100); // Match placeholders ``` ### Pitfall 4: Trying to Format References [Section titled “Pitfall 4: Trying to Format References”](#pitfall-4-trying-to-format-references) **Problem:** ```rust 1 let s = String::from("hello"); 2 println!("{}", &s); // Works, but... ``` **Why it works:** Rust automatically dereferences for Display. **Better:** ```rust 1 let s = String::from("hello"); 2 println!("{}", s); // Clearer ``` *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Use Debug for Development [Section titled “1. Use Debug for Development”](#1-use-debug-for-development) ** Implement Display for everything:** ```rust 1 struct Point { x: i32, y: i32 } 2 // Lots of boilerplate to implement Display... ``` ** Use derive Debug:** ```rust 1 #[derive(Debug)] 2 struct Point { x: i32, y: i32 } 3 4 let p = Point { x: 10, y: 20 }; 5 println!("{:?}", p); // Point { x: 10, y: 20 } ``` ### 2. Use Inline Captures for Clarity [Section titled “2. Use Inline Captures for Clarity”](#2-use-inline-captures-for-clarity) ** Unclear:** ```rust 1 println!("User {} (ID: {}) logged in at {}", name, id, time); ``` ** Clear:** ```rust 1 println!("User {name} (ID: {id}) logged in at {time}"); ``` > **Tip:** Since Rust 2021, named placeholders capture identifiers from the surrounding scope directly. The older explicit form `println!("{name}", name = name)` is exactly what `clippy::uninlined_format_args` flags, with the suggestion to drop the redundant `name = name` argument. ### 3. Use format! for String Building [Section titled “3. Use format! for String Building”](#3-use-format-for-string-building) ** Concatenation:** ```rust 1 let s = "Hello, ".to_string() + name + "!"; ``` ** Use format!:** ```rust 1 let s = format!("Hello, {}!", name); ``` ### 4. Pretty Print Complex Data [Section titled “4. Pretty Print Complex Data”](#4-pretty-print-complex-data) ** Hard to read:** ```rust 1 println!("{:?}", complex_data); ``` ** Pretty print:** ```rust 1 println!("{:#?}", complex_data); ``` *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) ### Logging with Formatting [Section titled “Logging with Formatting”](#logging-with-formatting) **TypeScript:** ```typescript 1 function log(level: string, message: string) { 2 const timestamp = new Date().toISOString(); 3 console.log(`[${timestamp}] ${level}: ${message}`); 4 } 5 6 log("INFO", "Server started"); 7 log("ERROR", "Connection failed"); ``` **Rust:** ```rust 1 fn log(level: &str, message: &str) { 2 let timestamp = chrono::Local::now().format("%Y-%m-%d %H:%M:%S"); 3 println!("[{}] {}: {}", timestamp, level, message); 4 } 5 6 fn main() { 7 log("INFO", "Server started"); 8 log("ERROR", "Connection failed"); 9 } ``` ### Displaying Table Data [Section titled “Displaying Table Data”](#displaying-table-data) ```rust 1 fn print_table(users: &[(&str, u8, f64)]) { 2 println!("{:<15} {:>5} {:>10}", "Name", "Age", "Score"); 3 println!("{:-<32}", ""); // Separator 4 5 for (name, age, score) in users { 6 println!("{:<15} {:>5} {:>10.2}", name, age, score); 7 } 8 } 9 10 fn main() { 11 let users = [ 12 ("Alice", 30, 95.5), 13 ("Bob", 25, 87.3), 14 ("Charlie", 35, 92.0), 15 ]; 16 17 print_table(&users); 18 } ``` **Output:** ```plaintext 1 Name Age Score 2 -------------------------------- 3 Alice 30 95.50 4 Bob 25 87.30 5 Charlie 35 92.00 ``` *** ## Format Specifiers Reference [Section titled “Format Specifiers Reference”](#format-specifiers-reference) | Specifier | Description | Example | Output | | --------- | --------------------- | ----------------------- | ---------- | | `{}` | Display | `println!("{}", 42)` | 42 | | `{:?}` | Debug | `println!("{:?}", x)` | (1, 2) | | `{:#?}` | Pretty debug | `println!("{:#?}", x)` | Multi-line | | `{:b}` | Binary | `println!("{:b}", 42)` | 101010 | | `{:x}` | Lowercase hex | `println!("{:x}", 42)` | 2a | | `{:X}` | Uppercase hex | `println!("{:X}", 42)` | 2A | | `{:o}` | Octal | `println!("{:o}", 42)` | 52 | | `{:p}` | Pointer | `println!("{:p}", &x)` | 0x7fff… | | `{:e}` | Lowercase exponential | `println!("{:e}", pi)` | 3.14159e0 | | `{:E}` | Uppercase exponential | `println!("{:E}", pi)` | 3.14159E0 | | `{:.N}` | Precision (N digits) | `println!("{:.2}", pi)` | 3.14 | | `{:W}` | Width (W characters) | `println!("{:5}", 42)` | ” 42” | | `{:W}` | Right align | `println!("{:>5}", 42)` | ” 42” | | `{:^W}` | Center align | `println!("{:^5}", 42)` | ” 42 “ | | `{:0W}` | Zero pad | `println!("{:05}", 42)` | 00042 | | `{:+}` | Always show sign | `println!("{:+}", 42)` | +42 | *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [std::fmt module](https://doc.rust-lang.org/std/fmt/) * [The Rust Book - Output](https://doc.rust-lang.org/book/ch03-05-control-flow.html) * [println! macro](https://doc.rust-lang.org/std/macro.println.html) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Basic Printing [Section titled “Exercise 1: Basic Printing”](#exercise-1-basic-printing) Print “Hello, Rust!” three times: ```rust 1 fn main() { 2 // Your code here 3 } ``` Solution ```rust 1 fn main() { 2 println!("Hello, Rust!"); 3 println!("Hello, Rust!"); 4 println!("Hello, Rust!"); 5 } ``` ### Exercise 2: Variable Printing [Section titled “Exercise 2: Variable Printing”](#exercise-2-variable-printing) Print a person’s name and age in format: “Alice is 30 years old” ```rust 1 fn main() { 2 let name = "Alice"; 3 let age = 30; 4 // Your code here 5 } ``` Solution ```rust 1 fn main() { 2 let name = "Alice"; 3 let age = 30; 4 println!("{} is {} years old", name, age); 5 } ``` ### Exercise 3: Number Formatting [Section titled “Exercise 3: Number Formatting”](#exercise-3-number-formatting) Format π (3.14159) with 2 decimal places: ```rust 1 fn main() { 2 let pi = 3.14159; 3 // Your code here 4 } ``` Solution ```rust 1 fn main() { 2 let pi = 3.14159; 3 println!("{:.2}", pi); // 3.14 4 } ``` ### Exercise 4: Debug Printing [Section titled “Exercise 4: Debug Printing”](#exercise-4-debug-printing) Print a vector using debug format: ```rust 1 fn main() { 2 let numbers = vec![1, 2, 3, 4, 5]; 3 // Your code here 4 } ``` Solution ```rust 1 fn main() { 2 let numbers = vec![1, 2, 3, 4, 5]; 3 println!("{:?}", numbers); // [1, 2, 3, 4, 5] 4 } ``` ### Exercise 5: Create Formatted String [Section titled “Exercise 5: Create Formatted String”](#exercise-5-create-formatted-string) Create a string “User: Alice, Score: 95.5” using format!: ```rust 1 fn main() { 2 let name = "Alice"; 3 let score = 95.5; 4 let s = /* your code */; 5 println!("{}", s); 6 } ``` Solution ```rust 1 fn main() { 2 let name = "Alice"; 3 let score = 95.5; 4 let s = format!("User: {}, Score: {}", name, score); 5 println!("{}", s); 6 } ``` *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * `println!` and `print!` macros * Format placeholders (`{}`, `{:?}`, etc.) * Number formatting (precision, width, padding) * Debug vs Display formatting * `format!` macro for string building * Named and positional parameters **Key macros:** ```rust 1 println!() // Print with newline 2 print!() // Print without newline 3 eprintln!() // Print to stderr 4 format!() // Create formatted String ``` **Common patterns:** ```rust 1 println!("{}", x); // Display 2 println!("{:?}", x); // Debug 3 println!("{:#?}", x); // Pretty debug 4 println!("{:.2}", pi); // Precision 5 println!("{:10}", n); // Width ``` **Formatting is expressive and type-safe in Rust!** # Rust Functions & Closures > Map every TypeScript function piece to Rust: signatures, parameters, returns, closures, higher-order functions, fn pointers, and recursion. Functions are the workhorse of any program, and you already write them every day in TypeScript and JavaScript. This section maps each piece you know — declarations, parameters, return values, arrow functions, higher-order functions, function pointers, and recursion — onto its idiomatic Rust counterpart. The syntax is close enough to feel familiar, but a few deeper ideas (typed signatures as hard contracts, the expression-oriented body, the `Fn`/`FnMut`/`FnOnce` closure traits, and the absence of default/rest parameters and guaranteed tail-call optimization) reshape how you read and write Rust code. *** ## What’s in This Section [Section titled “What’s in This Section”](#whats-in-this-section) * **[Basic Functions and Signatures](/03-functions/00-basic-functions/)** - `fn` definitions, typed parameters, return types, statements vs expressions * **[Function Parameters](/03-functions/01-parameters/)** - no default or rest parameters; idiomatic alternatives (`Option`, slices, structs, traits) * **[Return Values](/03-functions/02-return-values/)** - return types, tail expressions, the unit type `()`, early return, returning tuples * **[Arrow Functions vs Closures](/03-functions/03-arrow-vs-closures/)** - `|args|` syntax, `Fn`/`FnMut`/`FnOnce`, capture by reference vs `move` * **[Higher-Order Functions](/03-functions/04-higher-order/)** - `map`/`filter`/`reduce` equivalents, taking and returning closures * **[Function Pointers](/03-functions/05-function-pointers/)** - the `fn` type, passing named functions, function items vs closures * **[Recursion](/03-functions/06-recursion/)** - recursive functions, stack depth, iterative alternatives, recursive enums with `Box` *** ## What You’ll Learn [Section titled “What You’ll Learn”](#what-youll-learn) By the end of this section, you will be able to: * Write Rust functions with `fn`, `snake_case` names, mandatory typed parameters, and a `-> Type` return arrow * Use the **tail expression** (last line, no semicolon) as the return value, and reserve `return` for early exits * Reproduce default, optional, and rest parameters with `Option`, slices `&[T]`, `Default` structs, and the builder pattern * Return multiple values as a **tuple** (or a named struct) instead of mutating out-parameters * Translate arrow functions into Rust closures and understand capture by `&`, `&mut`, and `move` * Distinguish the three closure traits — `Fn`, `FnMut`, `FnOnce` — and accept the weakest one that works * Take closures as parameters (`impl Fn`) and return them (`impl Fn` or `Box`) * Pass named functions and constructors as function pointers (`fn(T) -> R`) * Write recursion safely, knowing Rust has no guaranteed tail-call optimization, and reach for iteration or `Box` when appropriate *** ## Topics [Section titled “Topics”](#topics) | # | Topic | What it covers | | - | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | 1 | [Basic Functions and Signatures](/03-functions/00-basic-functions/) | `fn` definitions, typed parameters, the `->` return type, statements vs expressions; vs TS declarations | | 2 | [Function Parameters](/03-functions/01-parameters/) | No default/rest params; `Option`, slices `&[T]`, `Default` structs, builders, “overloading” via traits | | 3 | [Return Values](/03-functions/02-return-values/) | Return types, implicit tail-expression return, the unit type `()`, early `return`, returning tuples | | 4 | [Arrow Functions vs Closures](/03-functions/03-arrow-vs-closures/) | `(args) =>` becomes `\|args\|`; `Fn`/`FnMut`/`FnOnce`; capture by reference vs move; the `move` keyword | | 5 | [Higher-Order Functions](/03-functions/04-higher-order/) | `map`/`filter`/`reduce` (lazy iterators); taking `impl Fn` and returning `impl Fn` / `Box` | | 6 | [Function Pointers](/03-functions/05-function-pointers/) | The `fn` type, passing named functions, function items vs `fn` pointers vs closures | | 7 | [Recursion](/03-functions/06-recursion/) | Recursive functions, no guaranteed TCO, stack depth, iterative alternatives, recursive enums with `Box` | *** ## Learning Objectives [Section titled “Learning Objectives”](#learning-objectives) After completing this section, a TypeScript/JavaScript developer should be able to: 1. Read any Rust function signature and explain its parameters and return type as a compiler-enforced contract. 2. Explain why a stray semicolon changes a function’s return value to `()`, and fix the resulting `mismatched types` error. 3. Choose the right idiom for “flexible” arguments: `Option`, a slice, a `Default` struct, a builder, or a trait bound. 4. Write closures with inferred types, decide when `move` is required, and pick the correct `Fn`/`FnMut`/`FnOnce` bound. 5. Build lazy iterator pipelines (`iter().filter().map().collect()`) as the replacement for eager `Array.prototype` chains. 6. Decide between a `fn` pointer and a generic `impl Fn` bound for a callback parameter. 7. Recognize when recursion is safe (shallow, recursive data) versus when iteration is the safer Rust default. *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) This section assumes you have completed: * **[Section 02: Basics](/02-basics/)** — variables and mutability (`let mut` is essential for `FnMut`), the basic types you will pass as parameters, and especially the **statement-vs-expression** distinction that underpins tail-expression returns. If the expression-oriented model (`let x = { ...; a + b };`) feels unfamiliar, re-read the Basics section before starting here. > **Note:** Several topics in this section *preview* concepts covered fully later: ownership and `move` ([Section 05](/05-ownership/)), `Option`/`Result` and the `?` operator ([Section 08](/08-error-handling/)), generics and traits ([Section 09](/09-generics-traits/)), and `Box`/`Rc` for recursive types ([Section 10](/10-smart-pointers/)). You do not need those sections first — the links are there for when you want to go deeper. *** ## Estimated Time [Section titled “Estimated Time”](#estimated-time) * **Reading:** 3-4 hours * **Hands-on Practice & Exercises:** 3-4 hours * **Total:** 6-8 hours A reasonable order is the list order above: basics → parameters → return values → closures → higher-order → function pointers → recursion. Closures (topic 4) are the conceptual heart of the section, so do not skip them. *** ## Frequently asked questions [Section titled “Frequently asked questions”](#frequently-asked-questions) ### How do I write a default or optional parameter? [Section titled “How do I write a default or optional parameter?”](#how-do-i-write-a-default-or-optional-parameter) Rust has neither. Model an optional argument as `Option` and pass `None`, or use the builder pattern when there are many optionals. For overloading-like flexibility, take a generic parameter bounded by a trait. See [Function Parameters](/03-functions/01-parameters/). ### What is the difference between a function and a closure? [Section titled “What is the difference between a function and a closure?”](#what-is-the-difference-between-a-function-and-a-closure) A `fn` is a plain named function. A closure (`|x| x + 1`) can capture variables from its surroundings, and the compiler sorts closures into the `Fn`, `FnMut`, and `FnOnce` traits by how they use what they capture. See [Arrow Functions vs Closures](/03-functions/03-arrow-vs-closures/). ### Why doesn’t my function need a `return`? [Section titled “Why doesn’t my function need a return?”](#why-doesnt-my-function-need-a-return) The last expression in a block is its value, so `fn add(a: i32, b: i32) -> i32 { a + b }` returns `a + b` with no `return` and no trailing semicolon. An explicit `return` is reserved for early exits. See [Return Values](/03-functions/02-return-values/). # Basic Functions and Signatures > Rust functions resemble TypeScript's, but every parameter is typed and the last expression returns with no return keyword. Learn fn signatures and unit. Functions are the workhorse of any program, and you already write them every day in TypeScript. The Rust syntax is close enough to feel familiar, but two ideas reshape how you read Rust code: **every parameter and return value is explicitly typed**, and **the function body is an expression** whose final line is the return value. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A Rust function is declared with the `fn` keyword, takes **fully typed** parameters, and declares its return type after a `->` arrow. Unlike TypeScript, Rust never infers parameter types or return types from usage: the signature is a hard contract. And because Rust is **expression-oriented**, the last expression in the body (with no trailing semicolon) is automatically returned. > **Note:** This file covers function definitions, signatures, typed parameters, return types, and the statement-vs-expression model. Parameter patterns (no default or rest parameters), return-value details, and closures each get their own file — see [Further Reading](#further-reading). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // TypeScript - function declarations with optional type annotations 2 function greet(name: string): string { 3 return `Hello, ${name}!`; 4 } 5 6 function add(a: number, b: number): number { 7 return a + b; 8 } 9 10 // Return type can be inferred and omitted 11 function logMessage(level: string, message: string) { 12 console.log(`[${level}] ${message}`); 13 } 14 15 const message = greet("Ada"); 16 console.log(message); // "Hello, Ada!" 17 18 console.log(`2 + 3 = ${add(2, 3)}`); // "2 + 3 = 5" 19 logMessage("INFO", "service started"); // "[INFO] service started" ``` **Key points:** * `function` keyword, `camelCase` names by convention. * Parameter types are optional in plain JavaScript and only enforced by TypeScript at compile time. * The return type can be omitted and TypeScript will infer it. * `return` is always required to produce a value. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 // Rust - every parameter and the return value is explicitly typed 2 fn greet(name: &str) -> String { 3 format!("Hello, {name}!") 4 } 5 6 fn add(a: i32, b: i32) -> i32 { 7 a + b // tail expression: no semicolon, this is the return value 8 } 9 10 fn log_message(level: &str, message: &str) { 11 println!("[{level}] {message}"); 12 } 13 14 fn main() { 15 let message = greet("Ada"); 16 println!("{message}"); 17 18 let sum = add(2, 3); 19 println!("2 + 3 = {sum}"); 20 21 log_message("INFO", "service started"); 22 } ``` **Output (verified):** ```text 1 Hello, Ada! 2 2 + 3 = 5 3 [INFO] service started ``` **Key points:** * `fn` keyword, `snake_case` names by convention (Rust will warn if you use `camelCase`). * Every parameter **must** have a type; there is no inference for parameters. * The return type follows `->`. Omitting it means the function returns the **unit type** `()` (Rust’s “returns nothing”). * The last expression with **no semicolon** is the return value. No `return` keyword needed. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The anatomy of a Rust function [Section titled “The anatomy of a Rust function”](#the-anatomy-of-a-rust-function) ```rust 1 fn add(a: i32, b: i32) -> i32 { 2 // ^ ^ ^ ^ 3 // | | | └─ return type (after the arrow) 4 // | | └───────── second typed parameter 5 // | └─────────────────── first typed parameter 6 // └──────────────────────── the `fn` keyword + function name 7 a + b 8 } ``` Compare this to the TypeScript signature `function add(a: number, b: number): number`. The pieces map almost one-to-one: | Piece | TypeScript | Rust | | --------------- | ---------------------- | --------------------------- | | Keyword | `function` | `fn` | | Name convention | `camelCase` | `snake_case` | | Parameter type | `a: number` (optional) | `a: i32` (mandatory) | | Return type | `: number` (optional) | `-> i32` (defaults to `()`) | | Produce a value | `return a + b;` | `a + b` (tail expression) | ### Parameter types are never inferred [Section titled “Parameter types are never inferred”](#parameter-types-are-never-inferred) In TypeScript you can lean on inference for return types, and in plain JavaScript you can skip types entirely. Rust draws a firm line. **Parameter types are always required**, because a function signature is a public contract the compiler checks at every call site. Return types may be omitted only when the function returns `()` (nothing). ```rust 1 // This is the full, idiomatic form. Nothing here is optional except 2 // the return type — and only because returning `()` is a real choice. 3 fn multiply(a: f64, b: f64) -> f64 { 4 a * b 5 } ``` > **Tip:** If you find yourself wishing for “inferred parameter types,” you usually want **generics** instead — a single function that works across many types. That is covered in [Section 09: Generics & Traits](/09-generics-traits/). ### Statements vs expressions: the core mental shift [Section titled “Statements vs expressions: the core mental shift”](#statements-vs-expressions-the-core-mental-shift) This is the idea that trips up most TypeScript developers. Rust distinguishes between: * **Statements** perform an action and return *nothing*. `let x = 5;` is a statement. * **Expressions** evaluate to a *value*. `5 + 3`, a function call, and even an `if`/`match` block are expressions. A function body is a **block**, and a block is itself an expression: its value is the value of its **final expression**, provided that expression has no trailing semicolon. ```rust 1 // statements vs expressions 2 fn classify(score: u32) -> &'static str { 3 // `if` is an expression in Rust; it evaluates to a value. 4 let grade = if score >= 90 { 5 "A" 6 } else if score >= 80 { 7 "B" 8 } else { 9 "C or below" 10 }; 11 12 grade // tail expression 13 } 14 15 fn main() { 16 // A block is an expression; its value is the last expression in it. 17 let x = { 18 let a = 3; 19 let b = 4; 20 a * a + b * b // no semicolon -> this is the block's value 21 }; 22 println!("x = {x}"); 23 24 println!("{}", classify(95)); 25 println!("{}", classify(83)); 26 println!("{}", classify(40)); 27 } ``` **Output (verified):** ```text 1 x = 25 2 A 3 B 4 C or below ``` In TypeScript, an `if`/`else` is a statement; it cannot be assigned to a variable directly. You reach for the ternary operator (`cond ? a : b`) or an immediately-invoked function for anything bigger. In Rust, `if`, `match`, `loop`, and `{ ... }` blocks are all expressions, so you assign them straight to a binding. (Control-flow expressions are explored in depth in [Section 04: Control Flow](/04-control-flow/).) ### Semicolons matter [Section titled “Semicolons matter”](#semicolons-matter) The trailing semicolon is not optional decoration. It changes meaning: * `a + b` (no semicolon) → an expression that becomes the block’s value. * `a + b;` (semicolon) → a statement that throws the value away and evaluates to `()`. So a function whose last line is `a + b;` returns `()`, not the sum. That is one of the most common early mistakes; see [Common Pitfalls](#common-pitfalls). ### Functions are order-independent (no “hoisting” needed) [Section titled “Functions are order-independent (no “hoisting” needed)”](#functions-are-order-independent-no-hoisting-needed) JavaScript hoists `function` declarations so you can call them before they appear in the file. Rust does not need hoisting because items in a module are resolved regardless of order. You can call a function defined later in the same file (or even later in the same module) freely. ```rust 1 // Functions can be called before their definition (order-independent). 2 fn main() { 3 println!("{}", double(21)); 4 } 5 6 fn double(n: i32) -> i32 { 7 n * 2 8 } ``` **Output (verified):** ```text 1 42 ``` > **Note:** This applies to **items** (functions, structs, constants) at module scope. It does *not* apply to local `let` bindings inside a function body, which must be declared before use, exactly like `let`/`const` in JavaScript. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript | Rust | | ---------------------- | --------------------------------------- | ---------------------------------------------------- | | Keyword | `function` | `fn` | | Naming convention | `camelCase` | `snake_case` (lint-enforced) | | Parameter types | Optional (TS) / absent (JS) | **Always required** | | Return type | Optional, inferred | Declared with `->`; defaults to `()` | | Returning a value | `return` keyword required | Tail expression (no semicolon); `return` is optional | | `if` / blocks | Statements (use ternary to get a value) | Expressions (assign directly) | | Call before definition | Hoisted `function` declarations | Order-independent for module items | | ”Returns nothing” | `void` | `()` (the unit type — a real, zero-size value) | | Overloading | Allowed (multiple signatures) | Not allowed; use generics/traits instead | ### `void` vs the unit type `()` [Section titled “void vs the unit type ()”](#void-vs-the-unit-type-) TypeScript’s `void` is a “don’t use this value” marker. Rust’s `()` is a genuine value (the empty tuple) that every expression-with-no-other-value produces. A function with no `-> Type` returns `()`, and you can even bind it: ```rust 1 // A function with no `-> Type` returns the unit type `()`. 2 fn print_banner(title: &str) { 3 println!("==== {title} ===="); 4 } 5 6 // This is exactly equivalent — explicit unit return type. 7 fn print_banner_explicit(title: &str) -> () { 8 println!("==== {title} ===="); 9 } 10 11 fn main() { 12 print_banner("Report"); 13 print_banner_explicit("Report"); 14 15 // The value of calling a unit-returning function IS `()`. 16 let nothing: () = print_banner("Again"); 17 println!("{nothing:?}"); 18 } ``` **Output (verified):** ```text 1 ==== Report ==== 2 ==== Report ==== 3 ==== Again ==== 4 () ``` You will almost never write `-> ()` explicitly; idiomatic Rust omits it. But understanding that “no return type” means “returns `()`” explains the error messages in the next section. ### No function overloading [Section titled “No function overloading”](#no-function-overloading) TypeScript lets you declare multiple signatures for one name. Rust does not. Instead you parameterize over types with **generics and traits**, or accept an `enum`. We point to the idiomatic alternatives in [Function Parameters](/03-functions/01-parameters/) and [Section 09](/09-generics-traits/). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Accidental semicolon on the return expression [Section titled “Pitfall 1: Accidental semicolon on the return expression”](#pitfall-1-accidental-semicolon-on-the-return-expression) This is *the* classic. You write what looks like a return, add a semicolon out of habit, and the function suddenly returns `()`. ```rust 1 fn add(a: i32, b: i32) -> i32 { 2 a + b; // accidental semicolon turns this into a statement 3 } ``` **Real compiler error:** ```text 1 error[E0308]: mismatched types 2 --> err_semicolon.rs:1:27 3 | 4 1 | fn add(a: i32, b: i32) -> i32 { 5 | --- ^^^ expected `i32`, found `()` 6 | | 7 | implicitly returns `()` as its body has no tail or `return` expression 8 2 | a + b; // accidental semicolon turns this into a statement 9 | - help: remove this semicolon to return this value ``` Notice the compiler points directly at the stray semicolon and tells you to remove it. **Fix:** drop the `;`: ```rust 1 fn add(a: i32, b: i32) -> i32 { 2 a + b 3 } ``` ### Pitfall 2: Omitting a parameter type [Section titled “Pitfall 2: Omitting a parameter type”](#pitfall-2-omitting-a-parameter-type) TypeScript tolerates `function add(a, b)` (with implicit `any` in loose mode). Rust does not: every parameter needs a type. ```rust 1 fn add(a, b) { 2 a + b 3 } ``` **Real compiler error (first message):** ```text 1 error: expected one of `:`, `@`, or `|`, found `,` 2 --> err_noparamtype.rs:1:9 3 | 4 1 | fn add(a, b) { 5 | ^ expected one of `:`, `@`, or `|` 6 | 7 = note: anonymous parameters are removed in the 2018 edition (see RFC 1685) 8 help: if this is a `self` type, give it a parameter name 9 | 10 1 | fn add(self: a, b) { 11 | +++++ 12 help: if this is a parameter name, give it a type 13 | 14 1 | fn add(a: TypeName, b) { 15 | ++++++++++ 16 help: if this is a type, explicitly ignore the parameter name 17 | 18 1 | fn add(_: a, b) { 19 | ++ ``` **Fix:** annotate both parameters and the return type: ```rust 1 fn add(a: i32, b: i32) -> i32 { 2 a + b 3 } ``` ### Pitfall 3: Returning a value without declaring a return type [Section titled “Pitfall 3: Returning a value without declaring a return type”](#pitfall-3-returning-a-value-without-declaring-a-return-type) If you forget the `-> Type`, the compiler assumes the function returns `()` and then complains that your tail expression has the wrong type. ```rust 1 fn square(n: i32) { 2 n * n 3 } ``` **Real compiler error:** ```text 1 error[E0308]: mismatched types 2 --> err_noreturntype.rs:2:5 3 | 4 1 | fn square(n: i32) { 5 | - help: try adding a return type: `-> i32` 6 2 | n * n 7 | ^^^^^ expected `()`, found `i32` ``` The compiler even suggests the exact return type to add. **Fix:** ```rust 1 fn square(n: i32) -> i32 { 2 n * n 3 } ``` ### Pitfall 4: Reaching for `return` everywhere [Section titled “Pitfall 4: Reaching for return everywhere”](#pitfall-4-reaching-for-return-everywhere) Coming from TypeScript, you will instinctively write `return a + b;`. It compiles and works, but it is not idiomatic for the *final* expression of a function, and Clippy (Rust’s linter) will tell you so. ```rust 1 fn add(a: i32, b: i32) -> i32 { 2 return a + b; 3 } ``` **Real `cargo clippy` warning:** ```text 1 warning: unneeded `return` statement 2 --> src/bin/clippy_return.rs:2:5 3 | 4 2 | return a + b; 5 | ^^^^^^^^^^^^ 6 | 7 = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#needless_return 8 = note: `#[warn(clippy::needless_return)]` on by default 9 help: remove `return` 10 | 11 2 - return a + b; 12 2 + a + b 13 | ``` `return` is still useful for **early returns** in the middle of a function; that is covered in [Return Values](/03-functions/02-return-values/). For the final value, use the tail expression. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Use tail expressions for the final value [Section titled “1. Use tail expressions for the final value”](#1-use-tail-expressions-for-the-final-value) ```rust 1 // Idiomatic: tail expression 2 fn area(width: f64, height: f64) -> f64 { 3 width * height 4 } 5 6 // Works, but Clippy flags the needless `return` 7 fn area_verbose(width: f64, height: f64) -> f64 { 8 return width * height; 9 } ``` ### 2. Name functions in `snake_case` [Section titled “2. Name functions in snake\_case”](#2-name-functions-in-snake_case) Rust’s compiler warns (`non_snake_case`) if you use `camelCase`. Embrace `snake_case`: `calculate_total`, not `calculateTotal`. ### 3. Borrow instead of taking ownership for read-only parameters [Section titled “3. Borrow instead of taking ownership for read-only parameters”](#3-borrow-instead-of-taking-ownership-for-read-only-parameters) For a parameter you only need to read, take a **borrow** (`&str`, `&[T]`) rather than an owned `String` or `Vec`. This avoids forcing the caller to give up (or clone) their data. This connects directly to [Section 05: Ownership](/05-ownership/). ```rust 1 // Reads the string without taking ownership 2 fn word_count(text: &str) -> usize { 3 text.split_whitespace().count() 4 } ``` ### 4. Keep signatures honest [Section titled “4. Keep signatures honest”](#4-keep-signatures-honest) The signature is documentation the compiler enforces. Prefer precise types (`u32` for a count that can’t be negative, `f64` for money-free math) over a single catch-all, just as you would prefer precise TypeScript types over `any`. ### 5. Let `()` be implicit [Section titled “5. Let () be implicit”](#5-let--be-implicit) Do not write `-> ()`. Omitting the return type for side-effecting functions is the convention every Rust reader expects. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small order-pricing module that uses several typed functions, tail expressions, and `if`/`match` as expressions. This is the shape of code you would find in a real billing service. ```rust 1 // Real-world example: a tiny order-pricing module. 2 3 /// A line item in a shopping cart. 4 struct LineItem { 5 name: String, 6 unit_price_cents: u32, 7 quantity: u32, 8 } 9 10 /// Returns the subtotal in cents for a single line item. 11 fn line_total_cents(item: &LineItem) -> u32 { 12 item.unit_price_cents * item.quantity 13 } 14 15 /// Applies a percentage discount (0-100) to an amount in cents, 16 /// rounding to the nearest cent. 17 fn apply_discount(amount_cents: u32, percent_off: u8) -> u32 { 18 // `if` is an expression, so we can bind its result directly. 19 let percent_off = if percent_off > 100 { 100 } else { percent_off }; 20 let kept = 100 - u32::from(percent_off); 21 (amount_cents * kept + 50) / 100 // tail expression: rounded result 22 } 23 24 /// Formats an amount of cents as a dollar string, e.g. 1299 -> "$12.99". 25 fn format_price(amount_cents: u32) -> String { 26 let dollars = amount_cents / 100; 27 let cents = amount_cents % 100; 28 format!("${dollars}.{cents:02}") 29 } 30 31 fn main() { 32 let cart = [ 33 LineItem { name: "Keyboard".to_string(), unit_price_cents: 7999, quantity: 1 }, 34 LineItem { name: "Cable".to_string(), unit_price_cents: 599, quantity: 3 }, 35 ]; 36 37 // Sum subtotals across the cart. 38 let mut subtotal = 0; 39 for item in &cart { 40 let total = line_total_cents(item); 41 println!("{:<10} x{} = {}", item.name, item.quantity, format_price(total)); 42 subtotal += total; 43 } 44 45 let total = apply_discount(subtotal, 10); 46 println!("Subtotal: {}", format_price(subtotal)); 47 println!("Total (10% off): {}", format_price(total)); 48 } ``` **Output (verified):** ```text 1 Keyboard x1 = $79.99 2 Cable x3 = $17.97 3 Subtotal: $97.96 4 Total (10% off): $88.16 ``` **What to notice:** * Each function has a precise typed signature. The compiler enforces that `quantity` is a `u32`, so a negative quantity is simply unrepresentable. * `line_total_cents` and `format_price` end in a tail expression; no `return` keyword. * `apply_discount` clamps the percentage with an `if` **expression** bound to a `let`, then returns the computed value as the tail expression. * `for item in &cart` *borrows* each item, so `cart` is still usable afterward — a preview of ownership in [Section 05](/05-ownership/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book – Functions](https://doc.rust-lang.org/book/ch03-03-how-functions-work.html) * [The Rust Book – Statements and Expressions](https://doc.rust-lang.org/book/ch03-03-how-functions-work.html#statements-and-expressions) * [Rust by Example – Functions](https://doc.rust-lang.org/rust-by-example/fn.html) * [Rust Reference – Functions](https://doc.rust-lang.org/reference/items/functions.html) ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Parameters](/03-functions/01-parameters/) — why Rust has no default or rest parameters, and the idiomatic alternatives. * [Return Values](/03-functions/02-return-values/) — tail returns, early `return`, the unit type, and returning tuples. * [Arrow Functions vs Closures](/03-functions/03-arrow-vs-closures/) — `|args|` syntax and the `Fn`/`FnMut`/`FnOnce` traits. * [Higher-Order Functions](/03-functions/04-higher-order/) — passing and returning closures. * [Function Pointers](/03-functions/05-function-pointers/) — the `fn` type and passing named functions. * [Section 02: Variables and Mutability](/02-basics/00-variables/) — the expression-oriented model starts here. * [Section 04: Control Flow](/04-control-flow/) — `if`, `match`, and `loop` as expressions. * [Section 05: Ownership](/05-ownership/) — why read-only parameters should borrow. * [Section 09: Generics & Traits](/09-generics-traits/) — the replacement for parameter-type inference and overloading. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Convert Celsius to Fahrenheit [Section titled “Exercise 1: Convert Celsius to Fahrenheit”](#exercise-1-convert-celsius-to-fahrenheit) **Difficulty:** Easy **Objective:** Write a function with a typed signature that returns a value via a tail expression. **Instructions:** 1. Write a function `celsius_to_fahrenheit` that takes one `f64` parameter and returns an `f64`. 2. Use the formula `c * 9 / 5 + 32`. 3. Do not use the `return` keyword — use a tail expression. 4. Call it from `main` with `100.0`, `0.0`, and `37.0` and print the results. Solution ```rust 1 fn celsius_to_fahrenheit(c: f64) -> f64 { 2 c * 9.0 / 5.0 + 32.0 3 } 4 5 fn main() { 6 println!("{}", celsius_to_fahrenheit(100.0)); // 212 7 println!("{}", celsius_to_fahrenheit(0.0)); // 32 8 println!("{}", celsius_to_fahrenheit(37.0)); // 98.6 9 } ``` **Verified output:** ```text 1 212 2 32 3 98.6 ``` Note the literals are `9.0`, `5.0`, `32.0` — using integer literals like `9` would be a type mismatch against the `f64` value `c`. Rust does not implicitly convert between numeric types. ### Exercise 2: Password strength check returning a `bool` [Section titled “Exercise 2: Password strength check returning a bool”](#exercise-2-password-strength-check-returning-a-bool) **Difficulty:** Medium **Objective:** Combine several boolean sub-checks and return the result as a tail expression. **Instructions:** 1. Write `is_strong_password(password: &str) -> bool`. 2. A password is strong when it is at least 8 characters long, contains at least one digit, and contains at least one uppercase letter. 3. Compute three booleans and combine them with `&&` as the tail expression — no `return`. 4. Test it with `"abc"`, `"password"`, and `"Password1"`. > **Tip:** `str` has handy iterator methods: `password.chars().count()`, and `password.chars().any(|c| c.is_ascii_digit())`. (Closures like `|c| ...` are detailed in [Arrow Functions vs Closures](/03-functions/03-arrow-vs-closures/).) Solution ```rust 1 fn is_strong_password(password: &str) -> bool { 2 let long_enough = password.chars().count() >= 8; 3 let has_digit = password.chars().any(|c| c.is_ascii_digit()); 4 let has_upper = password.chars().any(|c| c.is_ascii_uppercase()); 5 6 // Tail expression returns the combined boolean — no `return` needed. 7 long_enough && has_digit && has_upper 8 } 9 10 fn main() { 11 println!("{}", is_strong_password("abc")); // false 12 println!("{}", is_strong_password("password")); // false 13 println!("{}", is_strong_password("Password1")); // true 14 } ``` **Verified output:** ```text 1 false 2 false 3 true ``` ### Exercise 3: Price tier with a `match` expression [Section titled “Exercise 3: Price tier with a match expression”](#exercise-3-price-tier-with-a-match-expression) **Difficulty:** Medium **Objective:** Use a `match` expression as the body of a function and return a `&'static str`. **Instructions:** 1. Write `price_tier(amount_cents: u32) -> &'static str`. 2. Return `"budget"` for `0`–`999`, `"standard"` for `1000`–`9999`, and `"premium"` for anything higher. 3. Use a `match` expression (a single expression body) rather than a chain of `if`/`else if`. 4. Test it with `500`, `2500`, and `50000`. Solution ```rust 1 /// Returns the price tier name for a given amount in cents. 2 fn price_tier(amount_cents: u32) -> &'static str { 3 // `match` is an expression; the matched arm's value becomes the result. 4 let tier = match amount_cents { 5 0..=999 => "budget", 6 1000..=9999 => "standard", 7 _ => "premium", 8 }; 9 10 tier // tail expression 11 } 12 13 fn main() { 14 println!("{}", price_tier(500)); // budget 15 println!("{}", price_tier(2500)); // standard 16 println!("{}", price_tier(50000)); // premium 17 } ``` **Verified output:** ```text 1 budget 2 standard 3 premium ``` You could shorten this further by making the `match` itself the tail expression (dropping the `let tier` binding). Both are idiomatic; the named binding can aid readability. `match` is covered fully in [Section 04: Control Flow](/04-control-flow/). *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * Rust functions use `fn`, `snake_case` names, **mandatory** parameter types, and a `-> Type` return arrow. * Omitting the return type means the function returns the unit type `()`, Rust’s “nothing.” * Rust is **expression-oriented**: the final expression (no trailing semicolon) is the return value. * A stray semicolon turns a return value into `()`, producing a `mismatched types` error. * Functions are order-independent at module scope; no hoisting needed. * `return` is reserved for early exits; idiomatic final values use the tail expression. # Function Parameters > Rust has no default, optional, or rest parameters like TypeScript. Map each one to its idiomatic replacement: Option, slices, Default structs, builders, and traits. In TypeScript and JavaScript you reach for default parameters, rest parameters, and optional `?` arguments without a second thought. Rust has **none** of these features at the language level, and yet every one of those patterns has a clean, idiomatic Rust equivalent. This page maps each familiar TypeScript parameter trick to the Rust way of doing it. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Rust functions take a fixed number of typed, **positional** parameters: no defaults, no optional `?` markers, no `...rest`, and no overloading by signature. Instead, Rust expresses those needs through the type system: `Option` for “maybe a value,” slices (`&[T]`) for “zero or more,” dedicated structs (often with `Default`) and the **builder pattern** for “lots of optional knobs,” and **traits** for “the same operation on different argument types.” Once you internalize this, function signatures become a precise, self-documenting contract. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Here is a typical TypeScript module that leans on every flexible-parameter feature the language offers: notifications.ts ```typescript 1 // 1. Default parameter 2 function greet(name: string, greeting: string = "Hello"): string { 3 return `${greeting}, ${name}!`; 4 } 5 6 // 2. Optional parameter (`?`) 7 function connect(host: string, port?: number): void { 8 const resolvedPort = port ?? 8080; 9 console.log(`Connecting to ${host}:${resolvedPort}`); 10 } 11 12 // 3. Rest parameters — "zero or more" 13 function sumAll(...numbers: number[]): number { 14 return numbers.reduce((acc, n) => acc + n, 0); 15 } 16 17 // 4. Options object — a big bag of optional settings 18 interface EmailOptions { 19 cc?: string[]; 20 replyTo?: string; 21 priority?: "low" | "normal" | "high"; 22 } 23 24 function sendEmail( 25 to: string[], 26 subject: string, 27 body: string, 28 options: EmailOptions = {}, 29 ): void { 30 const priority = options.priority ?? "normal"; 31 console.log(`To: ${to.join(", ")} | ${subject} [${priority}]`); 32 } 33 34 greet("Ada"); // "Hello, Ada!" 35 greet("Ada", "Welcome"); // "Welcome, Ada!" 36 connect("localhost"); // port defaults to 8080 37 sumAll(1, 2, 3, 4, 5); // 15 38 sendEmail(["ada@example.com"], "Hi", "Body"); // options optional ``` **What this relies on:** * A **default parameter** (`greeting = "Hello"`). * An **optional parameter** (`port?`) plus the nullish-coalescing operator `??`. * **Rest parameters** (`...numbers`) gathering a variable number of arguments. * An **options object** so the caller only sets the fields they care about. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust has no syntax for any of those. Each one maps to a deliberate, type-driven pattern instead: ```rust 1 // 1. Default parameter -> Option + unwrap_or 2 fn greet(name: &str, greeting: Option<&str>) -> String { 3 let greeting = greeting.unwrap_or("Hello"); 4 format!("{greeting}, {name}!") 5 } 6 7 // 2. Optional parameter -> Option (same idea) 8 fn connect(host: &str, port: Option) { 9 let port = port.unwrap_or(8080); 10 println!("Connecting to {host}:{port}"); 11 } 12 13 // 3. Rest parameters -> a slice &[T] 14 fn sum_all(numbers: &[i32]) -> i32 { 15 numbers.iter().sum() 16 } 17 18 // 4. Options object -> a struct with Default 19 #[derive(Debug, Default)] 20 struct EmailOptions { 21 cc: Vec, 22 reply_to: Option, 23 priority: Priority, 24 } 25 26 #[derive(Debug, Default)] 27 enum Priority { 28 Low, 29 #[default] 30 Normal, 31 High, 32 } 33 34 fn send_email(to: &[&str], subject: &str, body: &str, options: EmailOptions) { 35 let _ = body; 36 println!("To: {} | {subject} [{:?}]", to.join(", "), options.priority); 37 } 38 39 fn main() { 40 println!("{}", greet("Ada", None)); // "Hello, Ada!" 41 println!("{}", greet("Ada", Some("Welcome")));// "Welcome, Ada!" 42 43 connect("localhost", None); // port defaults to 8080 44 45 println!("{}", sum_all(&[1, 2, 3, 4, 5])); // 15 46 47 send_email( 48 &["ada@example.com"], 49 "Hi", 50 "Body", 51 EmailOptions::default(), // all options at their defaults 52 ); 53 } ``` **Verified output:** ```text 1 Hello, Ada! 2 Welcome, Ada! 3 Connecting to localhost:8080 4 15 5 To: ada@example.com | Hi [Normal] ``` > **Note:** Rust forces the caller to *say something* for every parameter, even if that something is `None` or `Default::default()`. This verbosity is the price of having no hidden “magic” defaults; in exchange, a function’s full set of inputs is always visible at the call site. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Default and optional parameters become `Option` [Section titled “Default and optional parameters become Option\”](#default-and-optional-parameters-become-optiont) In TypeScript, `port?: number` and `port: number = 8080` both let the caller omit the argument. Rust has no “omit,” so the absence is encoded *in the type* with `Option`. The caller passes `None` to mean “not provided” and `Some(value)` otherwise, and the function decides the fallback: ```rust 1 fn connect(retries: Option, timeout: Option) { 2 // Match handles the present/absent cases explicitly... 3 let retries = match retries { 4 Some(n) => n, 5 None => 3, 6 }; 7 // ...or use a combinator for the common "default value" case. 8 let timeout = timeout.unwrap_or(30); 9 println!("retries={retries}, timeout={timeout}"); 10 } 11 12 fn main() { 13 connect(None, None); // retries=3, timeout=30 14 connect(Some(5), Some(60)); // retries=5, timeout=60 15 connect(Some(0), None); // retries=0, timeout=30 16 } ``` This runs and prints exactly: ```text 1 retries=3, timeout=30 2 retries=5, timeout=60 3 retries=0, timeout=30 ``` Two things worth noticing: * `unwrap_or(30)` is the closest thing to TypeScript’s `port ?? 8080`. (We cover `Option` and its combinators in depth in [Error Handling](/08-error-handling/).) * `Some(0)` is meaningfully different from `None` — the third call keeps `retries = 0`. In JavaScript, `port ?? 8080` correctly preserves `0` too (because `0 != null`), but a sloppy `port || 8080` would wrongly replace `0` with `8080`. Rust’s `Option` has **no** such footgun: only `None` triggers the default. ### Rest parameters become slices [Section titled “Rest parameters become slices”](#rest-parameters-become-slices) TypeScript’s `...numbers: number[]` collects trailing arguments into an array. Rust passes a **slice** — a borrowed view `&[T]` over contiguous elements — so any array or `Vec` works without copying: ```rust 1 fn sum_all(numbers: &[i32]) -> i32 { 2 numbers.iter().sum() 3 } 4 5 fn main() { 6 println!("{}", sum_all(&[1, 2, 3, 4, 5])); // array literal -> 15 7 let v = vec![10, 20, 30]; 8 println!("{}", sum_all(&v)); // &Vec coerces to &[i32] -> 60 9 let arr = [7; 3]; 10 println!("{}", sum_all(&arr)); // [7, 7, 7] -> 21 11 } ``` The trade-off is at the call site: instead of `sumAll(1, 2, 3)` you write `sum_all(&[1, 2, 3])`. You give up the comma-separated ergonomics but gain a single, explicit, allocation-free parameter. Slices are central to Rust; we explore them more in [Collections](/07-collections/). ### Options objects become structs with `Default` [Section titled “Options objects become structs with Default”](#options-objects-become-structs-with-default) When a function has many optional settings, bundle them into a struct and derive `Default`. The caller constructs the struct, overriding only the fields they care about and filling the rest with **struct update syntax** (`..Default::default()`): ```rust 1 #[derive(Debug)] 2 struct ServerConfig { 3 host: String, 4 port: u16, 5 max_connections: u32, 6 tls: bool, 7 } 8 9 impl Default for ServerConfig { 10 fn default() -> Self { 11 ServerConfig { 12 host: "127.0.0.1".to_string(), 13 port: 8080, 14 max_connections: 100, 15 tls: false, 16 } 17 } 18 } 19 20 fn start_server(config: ServerConfig) { 21 println!( 22 "Listening on {}:{} (max={}, tls={})", 23 config.host, config.port, config.max_connections, config.tls 24 ); 25 } 26 27 fn main() { 28 // Override just two fields, keep the rest at their defaults. 29 start_server(ServerConfig { 30 port: 3000, 31 tls: true, 32 ..Default::default() 33 }); 34 35 start_server(ServerConfig::default()); 36 } ``` Output: ```text 1 Listening on 127.0.0.1:3000 (max=100, tls=true) 2 Listening on 127.0.0.1:8080 (max=100, tls=false) ``` The `..Default::default()` line is the Rust analog of spreading defaults into an options object (`{ ...defaults, port: 3000 }`). Here we wrote `Default` by hand to show non-trivial defaults; when every field’s default is also *its type’s* default (empty `Vec`, `None`, `0`, `false`), you can simply `#[derive(Default)]` instead, which is exactly what the `EmailOptions` struct above does. > **Tip:** `#[default]` on an enum variant (as on `Priority::Normal`) lets enums participate in `#[derive(Default)]`. This has been stable since Rust 1.62. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / JavaScript | Rust | | ------------------------- | --------------------------------- | ---------------------------------------------------------- | | Default value | `function f(x = 10)` | `Option` + `unwrap_or(10)`, or a `Default` struct field | | Optional argument | `function f(x?: number)` | `Option` parameter; caller passes `None` | | Nullish fallback | `x ?? fallback` | `opt.unwrap_or(fallback)` / `unwrap_or_else(..)` | | Variable arity (“rest”) | `...args: T[]` | `&[T]` slice (or `Vec` to take ownership) | | Options bag | optional object literal | `struct` + `#[derive(Default)]` + `..Default::default()` | | Many-step construction | options object | **builder pattern** (chained methods returning `Self`) | | Overload by argument type | declaration merging / union types | **trait** bound (`fn log(x: T)`) | | Named arguments | object destructuring `{ a, b }` | not supported; use a struct | | True variadics | `...args` | `macro_rules!` (e.g. `println!`), not functions | The unifying idea: **TypeScript bends the call syntax; Rust bends the type.** Optionality, variadicity, and overloading are all encoded into a parameter’s *type* rather than into special calling conventions. That keeps every Rust function a plain, monomorphic, statically-dispatched target with one obvious signature. ### ”Overloading” via traits [Section titled “”Overloading” via traits”](#overloading-via-traits) Rust has no function overloading: you cannot declare `fn log(x: i32)` and `fn log(x: &str)` in the same scope. The idiomatic substitute is a **trait** that both types implement, plus one generic function: ```rust 1 trait Describe { 2 fn describe(&self) -> String; 3 } 4 5 impl Describe for i32 { 6 fn describe(&self) -> String { 7 format!("the integer {self}") 8 } 9 } 10 11 impl Describe for &str { 12 fn describe(&self) -> String { 13 format!("the string {self:?}") 14 } 15 } 16 17 impl Describe for bool { 18 fn describe(&self) -> String { 19 format!("the boolean {self}") 20 } 21 } 22 23 // One generic function accepts any type that implements Describe. 24 fn log(value: T) { 25 println!("Logging {}", value.describe()); 26 } 27 28 fn main() { 29 log(42); 30 log("hello"); 31 log(true); 32 } ``` Output: ```text 1 Logging the integer 42 2 Logging the string "hello" 3 Logging the boolean true ``` Unlike TypeScript overloads (which are erased at runtime and resolved purely by the type checker), Rust **monomorphizes** `log`: the compiler generates a separate specialized copy for each concrete `T` actually used. Traits and generics get a full treatment in [Generics & Traits](/09-generics-traits/). ### Accepting “either type” with `impl Into` [Section titled “Accepting “either type” with impl Into\”](#accepting-either-type-with-impl-intot) A lighter-weight form of polymorphic parameter is `impl Trait` in argument position. The classic case is “accept either a `&str` or an owned `String`”: ```rust 1 // `impl Into` accepts anything convertible into a String. 2 fn add_tag(tags: &mut Vec, tag: impl Into) { 3 tags.push(tag.into()); 4 } 5 6 fn main() { 7 let mut tags: Vec = Vec::new(); 8 add_tag(&mut tags, "rust"); // &str 9 add_tag(&mut tags, String::from("web")); // String 10 println!("{tags:?}"); // ["rust", "web"] 11 } ``` `tag: impl Into` is shorthand for a generic `>` parameter. It is a common ergonomic choice in library APIs because the caller never has to think about whether they’re holding a borrowed or owned string. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Expecting default parameters to exist [Section titled “Pitfall 1: Expecting default parameters to exist”](#pitfall-1-expecting-default-parameters-to-exist) A TypeScript developer’s muscle memory says “I’ll just leave that argument off.” Rust rejects the call: ```rust 1 fn greet(name: &str, greeting: &str) -> String { 2 format!("{greeting}, {name}!") 3 } 4 5 fn main() { 6 println!("{}", greet("Ada")); // missing the second argument 7 } ``` Real compiler error: ```text 1 error[E0061]: this function takes 2 arguments but 1 argument was supplied 2 --> src/main.rs:6:20 3 | 4 6 | println!("{}", greet("Ada")); 5 | ^^^^^------- argument #2 of type `&str` is missing 6 | 7 note: function defined here 8 --> src/main.rs:1:4 9 | 10 1 | fn greet(name: &str, greeting: &str) -> String { 11 | ^^^^^ -------------- 12 help: provide the argument 13 | 14 6 | println!("{}", greet("Ada", /* &str */)); 15 | ++++++++++++ ``` The fix is to design the parameter as `Option<&str>` (and pass `None`) or to give the caller an overload-free default via a wrapper function. ### Pitfall 2: Writing a default value in the signature [Section titled “Pitfall 2: Writing a default value in the signature”](#pitfall-2-writing-a-default-value-in-the-signature) Trying to port `greeting: &str = "Hello"` directly does not even parse: ```rust 1 fn greet(name: &str, greeting: &str = "Hello") -> String { 2 format!("{greeting}, {name}!") 3 } ``` Real compiler error (first of several): ```text 1 error: expected parameter name, found `=` 2 --> src/main.rs:1:37 3 | 4 1 | fn greet(name: &str, greeting: &str = "Hello") -> String { 5 | ^ expected parameter name ``` There is no syntax for default argument values in Rust. Reach for `Option`, a `Default` struct, or a builder instead. ### Pitfall 3: Forgetting to borrow when passing a `Vec` to a slice parameter [Section titled “Pitfall 3: Forgetting to borrow when passing a Vec to a slice parameter”](#pitfall-3-forgetting-to-borrow-when-passing-a-vec-to-a-slice-parameter) A slice parameter (`&[T]`) needs a *reference*. Passing a `Vec` by value is a type mismatch: ```rust 1 fn sum_all(numbers: &[i32]) -> i32 { 2 numbers.iter().sum() 3 } 4 5 fn main() { 6 let v = vec![1, 2, 3]; 7 println!("{}", sum_all(v)); // forgot the & 8 } ``` Real compiler error: ```text 1 error[E0308]: mismatched types 2 --> src/main.rs:7:28 3 | 4 7 | println!("{}", sum_all(v)); // forgot the & 5 | ------- ^ expected `&[i32]`, found `Vec<{integer}>` 6 | | 7 | arguments to this function are incorrect 8 | 9 = note: expected reference `&[i32]` 10 found struct `Vec<{integer}>` 11 note: function defined here 12 --> src/main.rs:1:4 13 | 14 1 | fn sum_all(numbers: &[i32]) -> i32 { 15 | ^^^^^^^ --------------- 16 help: consider borrowing here 17 | 18 7 | println!("{}", sum_all(&v)); // forgot the & 19 | + ``` The compiler even suggests the fix: add `&`. Rust will *deref-coerce* `&Vec` to `&[i32]`, but it will not insert the `&` for you. (Why borrowing matters is the subject of [Ownership](/05-ownership/).) ### Pitfall 4: Treating `None` and `Some(0)` the same [Section titled “Pitfall 4: Treating None and Some(0) the same”](#pitfall-4-treating-none-and-some0-the-same) Because `Option` is a real enum, a present-but-zero value is distinct from an absent value, exactly the distinction JavaScript’s `||` operator loses. Decide up front whether you want `unwrap_or(default)` (only `None` falls back) or genuinely want to coalesce zero too. The former is almost always correct and is one reason `Option` is safer than nullable numbers. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Use `Option` for one or two optional parameters.** It is the lightest tool and reads clearly at the call site (`f(x, None)`). * **Prefer `unwrap_or` / `unwrap_or_else` / `unwrap_or_default`** over a hand-written `match` when you just need a fallback value. Use `unwrap_or_else` when the default is expensive to compute, so it is only built when actually needed. * **Reach for a `struct` with `#[derive(Default)]`** once a function grows three or more optional settings. Name the struct after the operation (`EmailOptions`, `ServerConfig`); it doubles as documentation. * **Use the builder pattern** when construction is multi-step, has interdependent fields, or benefits from validation in `build()`. Builders read fluently and keep required-vs-optional fields obvious. * **Use slices `&[T]`** for “borrow zero-or-more” and `Vec` only when the function must *own* the elements. A `&[T]` parameter is strictly more flexible: it accepts arrays, `Vec`s, and sub-slices alike. * **Use `impl Into` (or `impl AsRef`)** in public APIs that take strings, so callers can pass either `&str` or `String` without ceremony. * **Model overloading with a trait**, not with several same-named functions (which Rust forbids anyway). One generic function plus per-type `impl` blocks is the idiom. * **Avoid the temptation to overuse `impl Trait` everywhere**: concrete types keep error messages and signatures simpler. Add abstraction only where callers genuinely need the flexibility. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small email-sending API that combines several techniques: required fields are positional parameters, recipients use a slice (the “rest params” stand-in), the subject accepts both `&str` and `String` via `impl Into`, and the grab-bag of optional settings lives in a `Default` struct. ```rust 1 #[derive(Debug, Default)] 2 struct EmailOptions { 3 cc: Vec, 4 reply_to: Option, 5 priority: Priority, 6 } 7 8 #[derive(Debug, Default)] 9 enum Priority { 10 Low, 11 #[default] 12 Normal, 13 High, 14 } 15 16 /// Send an email. 17 /// 18 /// `to` is one-or-more recipients (slice = "rest" parameter). 19 /// `subject` accepts either a `&str` or an owned `String`. 20 /// `options` bundles everything optional, defaulting via `EmailOptions::default()`. 21 fn send_email(to: &[&str], subject: impl Into, body: &str, options: EmailOptions) { 22 let subject = subject.into(); 23 println!("To: {}", to.join(", ")); 24 println!("Subject: {subject}"); 25 if let Some(reply_to) = &options.reply_to { 26 println!("Reply-To: {reply_to}"); 27 } 28 if !options.cc.is_empty() { 29 println!("Cc: {}", options.cc.join(", ")); 30 } 31 println!("Priority: {:?}", options.priority); 32 println!("Body: {body}"); 33 } 34 35 fn main() { 36 // Minimal call: defaults for everything optional. 37 send_email( 38 &["ada@example.com"], 39 "Welcome!", 40 "Thanks for signing up.", 41 EmailOptions::default(), 42 ); 43 44 println!("---"); 45 46 // Full call: multiple recipients + overridden options. 47 send_email( 48 &["ada@example.com", "grace@example.com"], 49 String::from("Deploy finished"), 50 "Build #128 is live.", 51 EmailOptions { 52 cc: vec!["ops@example.com".to_string()], 53 priority: Priority::High, 54 reply_to: Some("noreply@example.com".to_string()), 55 }, 56 ); 57 } ``` Verified output: ```text 1 To: ada@example.com 2 Subject: Welcome! 3 Priority: Normal 4 Body: Thanks for signing up. 5 --- 6 To: ada@example.com, grace@example.com 7 Subject: Deploy finished 8 Reply-To: noreply@example.com 9 Cc: ops@example.com 10 Priority: High 11 Body: Build #128 is live. ``` > **Note:** For long-lived or interdependent configuration (say, an `HttpRequest` with method, headers, timeout, and retries), promote `EmailOptions` to a full builder so each setting gets its own validating method. See Exercise 3 for a worked builder. ### What about *true* variadics? [Section titled “What about true variadics?”](#what-about-true-variadics) If you genuinely want `println!`-style “any number of arguments of mixed types,” that is the job of **macros**, not functions. `macro_rules!` can match a repetition of expressions: ```rust 1 // A variadic sum macro (one or more arguments). 2 macro_rules! sum { 3 ($($x:expr),+ $(,)?) => {{ 4 let mut total = 0; 5 $( total += $x; )+ 6 total 7 }}; 8 } 9 10 fn main() { 11 println!("{}", sum!(1, 2, 3)); // 6 12 println!("{}", sum!(10, 20, 30, 40)); // 100 13 } ``` This compiles and prints `6` then `100`. Macros can do a lot, but they are a different tool with different rules; they are covered in [Macros](/14-macros/). For ordinary “many values of one type,” a slice is simpler and almost always the right choice. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Functions](https://doc.rust-lang.org/book/ch03-03-how-functions-work.html) * [The Rust Book — `Option`](https://doc.rust-lang.org/book/ch06-01-defining-an-enum.html#the-option-enum-and-its-advantages-over-null-values) * [`Option::unwrap_or` (std docs)](https://doc.rust-lang.org/std/option/enum.Option.html#method.unwrap_or) * [The `Default` trait (std docs)](https://doc.rust-lang.org/std/default/trait.Default.html) * [Rust by Example — Slices](https://doc.rust-lang.org/rust-by-example/primitives/array.html) * [Rust Design Patterns — Builder](https://rust-unofficial.github.io/patterns/patterns/creational/builder.html) ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Basic Functions](/03-functions/00-basic-functions/) — `fn` definitions, typed parameters, and return types * [Return Values](/03-functions/02-return-values/) — return types, tail expressions, returning tuples * [Arrow Functions vs Closures](/03-functions/03-arrow-vs-closures/) — passing behavior as a parameter * [Higher-Order Functions](/03-functions/04-higher-order/) — functions that take closures (`impl Fn`) as parameters * [Function Pointers](/03-functions/05-function-pointers/) — the `fn` type as a parameter * [Basics — Types](/02-basics/01-types/) — the parameter types you will be passing * [Generics & Traits](/09-generics-traits/) — trait bounds and `impl Trait` parameters * [Ownership](/05-ownership/) — why slice parameters are borrowed * [Control Flow](/04-control-flow/) — the next section, building on functions *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Optional parameter with a default [Section titled “Exercise 1: Optional parameter with a default”](#exercise-1-optional-parameter-with-a-default) **Difficulty:** Easy **Objective:** Translate a TypeScript default parameter into idiomatic Rust using `Option`. **Instructions:** Port the following TypeScript function to Rust. The `exponent` should default to `2` when not provided. Make `power(5, None)` return `25` and `power(2, Some(10))` return `1024`. ```typescript 1 function power(base: number, exponent: number = 2): number { 2 return base ** exponent; 3 } ``` Solution ```rust 1 fn power(base: i64, exponent: Option) -> i64 { 2 let exponent = exponent.unwrap_or(2); 3 base.pow(exponent) 4 } 5 6 fn main() { 7 assert_eq!(power(5, None), 25); 8 assert_eq!(power(2, Some(10)), 1024); 9 println!("ok"); 10 } ``` `unwrap_or(2)` supplies the default exactly when the caller passes `None`. Note the integer method `i64::pow`, which takes a `u32` exponent; there is no `**` operator in Rust. ### Exercise 2: Rest parameters as a slice [Section titled “Exercise 2: Rest parameters as a slice”](#exercise-2-rest-parameters-as-a-slice) **Difficulty:** Medium **Objective:** Replace TypeScript rest parameters with a slice parameter, and handle the empty case safely. **Instructions:** Port `average` to Rust. It must accept any number of `f64` values via a slice and return the arithmetic mean. For an empty input, return `None` instead of dividing by zero (so the signature is `fn average(values: &[f64]) -> Option`). `average(&[2.0, 4.0, 6.0])` should be `Some(4.0)`; `average(&[])` should be `None`. ```typescript 1 function average(...values: number[]): number | null { 2 if (values.length === 0) return null; 3 return values.reduce((a, b) => a + b, 0) / values.length; 4 } ``` Solution ```rust 1 fn average(values: &[f64]) -> Option { 2 if values.is_empty() { 3 return None; 4 } 5 let sum: f64 = values.iter().sum(); 6 Some(sum / values.len() as f64) 7 } 8 9 fn main() { 10 assert_eq!(average(&[2.0, 4.0, 6.0]), Some(4.0)); 11 assert_eq!(average(&[]), None); 12 println!("ok"); 13 } ``` Returning `Option` makes the “no values” case impossible to ignore: the caller must handle `None`, which is far safer than TypeScript’s `number | null`. `values.len() as f64` performs the explicit `usize`-to-`f64` cast Rust requires. ### Exercise 3: A builder for many optional settings [Section titled “Exercise 3: A builder for many optional settings”](#exercise-3-a-builder-for-many-optional-settings) **Difficulty:** Hard **Objective:** Replace an options object with the builder pattern. **Instructions:** Implement a `QueryBuilder` for a `Query { table, limit, ascending }`. `QueryBuilder::new(table)` should start with `limit = 100` and `ascending = true`. Provide chained methods `.limit(n)` and `.descending()`, and a `.build()` that returns the `Query`. The expression `QueryBuilder::new("users").limit(10).descending().build()` should equal `Query { table: "users".into(), limit: 10, ascending: false }`. Solution ```rust 1 #[derive(Debug, PartialEq)] 2 struct Query { 3 table: String, 4 limit: u32, 5 ascending: bool, 6 } 7 8 struct QueryBuilder { 9 table: String, 10 limit: u32, 11 ascending: bool, 12 } 13 14 impl QueryBuilder { 15 fn new(table: impl Into) -> Self { 16 QueryBuilder { table: table.into(), limit: 100, ascending: true } 17 } 18 19 fn limit(mut self, n: u32) -> Self { 20 self.limit = n; 21 self 22 } 23 24 fn descending(mut self) -> Self { 25 self.ascending = false; 26 self 27 } 28 29 fn build(self) -> Query { 30 Query { 31 table: self.table, 32 limit: self.limit, 33 ascending: self.ascending, 34 } 35 } 36 } 37 38 fn main() { 39 let q = QueryBuilder::new("users").limit(10).descending().build(); 40 assert_eq!( 41 q, 42 Query { table: "users".into(), limit: 10, ascending: false } 43 ); 44 println!("{q:?}"); 45 } ``` Each setter takes `mut self` by value and returns `Self`, which is what enables method chaining: ownership flows through the chain and the final `build()` consumes the builder. `impl Into` lets `new` accept both `&str` and `String`. This pattern scales to dozens of optional settings far better than a function with a dozen `Option` parameters. # Return Values > Rust functions return their final expression with no return keyword, use the unit type instead of void, and hand back multiple values as tuples, unlike TypeScript. How a function hands a result back to its caller looks superficially similar in Rust and TypeScript, but the mechanics are different. Rust functions return the value of their final **expression** (usually with no `return` keyword at all), and a function that returns “nothing” actually returns a real value called the **unit type**. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In Rust, the last expression in a function body is its return value (no `return`, no semicolon). The `return` keyword exists but is reserved for **early returns**. Functions that produce no meaningful value return `()` (the **unit type**), and when you need to hand back several values at once you return a **tuple** rather than mutating out-parameters. **In short:** A semicolon turns an expression into a statement that evaluates to `()`. Whether your function returns a useful value or `()` often comes down to whether that last semicolon is present. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // Explicit `return` on every path is the norm in TS/JS. 2 function square(n: number): number { 3 return n * n; 4 } 5 6 // A "void" function still returns something: `undefined`. 7 function logMessage(msg: string): void { 8 console.log(`[log] ${msg}`); 9 } 10 11 // Early return (guard clause) to avoid deep nesting. 12 function classify(score: number): string { 13 if (score < 0) return "invalid"; 14 if (score >= 90) return "excellent"; 15 if (score >= 60) return "passing"; 16 return "failing"; 17 } 18 19 // Returning "multiple values" means returning an array or an object, 20 // then destructuring at the call site. 21 function minMax(values: number[]): [number, number] { 22 return [Math.min(...values), Math.max(...values)]; 23 } 24 25 const [lo, hi] = minMax([7, 2, 9, 4, 1]); 26 console.log(lo, hi); // 1 9 27 28 const result = logMessage("hi"); 29 console.log(result); // undefined <-- void really means `undefined` ``` **Key points:** * Every value-producing path needs an explicit `return`. * A `void` function implicitly returns `undefined`. * “Multiple return values” are an array (positional) or object (named) plus destructuring. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 // The last expression IS the return value: no `return`, no semicolon. 2 fn square(n: i32) -> i32 { 3 n * n 4 } 5 6 // No `-> Type` means the function returns `()`, the unit type. 7 fn log_message(msg: &str) { 8 println!("[log] {msg}"); 9 } 10 11 // `return` is kept for EARLY returns (guard clauses). 12 fn classify(score: i32) -> &'static str { 13 if score < 0 { 14 return "invalid"; 15 } 16 if score >= 90 { 17 return "excellent"; 18 } 19 if score >= 60 { 20 return "passing"; 21 } 22 "failing" // final value: tail expression, no semicolon 23 } 24 25 // Multiple values come back as a tuple. 26 fn min_max(values: &[i32]) -> (i32, i32) { 27 let mut min = values[0]; 28 let mut max = values[0]; 29 for &v in &values[1..] { 30 if v < min { 31 min = v; 32 } 33 if v > max { 34 max = v; 35 } 36 } 37 (min, max) 38 } 39 40 fn main() { 41 println!("{}", square(5)); // 25 42 log_message("hi"); 43 44 let (lo, hi) = min_max(&[7, 2, 9, 4, 1]); 45 println!("min={lo}, max={hi}"); // min=1, max=9 46 } ``` Running the full version of this program prints: ```plaintext 1 25 2 [log] hi 3 min=1, max=9 ``` **Key points:** * The **tail expression** (last expression, no semicolon) is the return value. * Omitting `-> Type` is the same as `-> ()`. * `return` is for leaving early, not for the normal final result. * A **tuple** is the idiomatic way to return several values. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### The tail expression is the return value [Section titled “The tail expression is the return value”](#the-tail-expression-is-the-return-value) Rust is an **expression-oriented** language. A function body is a block, and a block evaluates to its final expression, provided that expression has no trailing semicolon. ```rust 1 fn square(n: i32) -> i32 { 2 n * n // tail expression: this is what the function returns 3 } ``` The `-> i32` after the parameter list is the **return type annotation** (TypeScript writes it after a colon: `(n: number): number`). The body’s last expression must produce that type. You *can* write `return`, and it compiles: ```rust 1 fn square_explicit(n: i32) -> i32 { 2 return n * n; // legal, but not idiomatic 3 } ``` But in idiomatic Rust the `return` keyword is reserved for leaving a function *before* the end. Using it on the last line is so unidiomatic that Clippy flags it (see [Common Pitfalls](#common-pitfalls)). > **Tip:** “No semicolon means return” is the single most useful rule to internalize from this page. If you find yourself writing `return x;` as the very last line, delete the `return` and the `;`. ### Statements vs. expressions: the role of the semicolon [Section titled “Statements vs. expressions: the role of the semicolon”](#statements-vs-expressions-the-role-of-the-semicolon) This is where TypeScript intuition can mislead you. In Rust: * An **expression** evaluates to a value (`n * n`, `if c { a } else { b }`, a block `{ ... }`). * A **statement** performs an action and evaluates to `()` (a `let` binding, or *any expression followed by a semicolon*). Adding a semicolon to the tail expression discards its value and substitutes `()`: ```rust 1 fn square(n: i32) -> i32 { 2 n * n; // BUG: now this is a statement; the function "falls off the end" with () 3 } ``` That mismatch (`()` where `i32` is expected) is a compile error, covered below. The fix is to remove the semicolon. > **Note:** This statement/expression distinction was introduced in [Section 02 — Basics](/02-basics/). Functions are where it bites hardest, so it is worth re-reading if it feels shaky. See also [Basic Functions and Signatures](/03-functions/00-basic-functions/) for the statement-vs-expression fundamentals. ### `if` (and `match`, and blocks) are expressions [Section titled “if (and match, and blocks) are expressions”](#if-and-match-and-blocks-are-expressions) Because `if` is an expression, you can use it directly as the tail expression; no need for a temporary mutable variable: ```rust 1 fn abs_diff(a: i32, b: i32) -> i32 { 2 if a > b { 3 a - b 4 } else { 5 b - a 6 } 7 } ``` Every branch must produce the same type, and there must be an `else` (otherwise the value of the `if` would be `()` when the condition is false). A plain block is also an expression: ```rust 1 fn block_expr_demo() -> i32 { 2 let y = { 3 let a = 3; 4 let b = 4; 5 a * a + b * b // tail expression of the inner block -> 25 6 }; 7 y 8 } ``` Even `loop` is an expression: `break value` makes the whole `loop` evaluate to `value`. ```rust 1 fn first_power_over(limit: u32) -> u32 { 2 let mut n = 1; 3 loop { 4 n *= 2; 5 if n > limit { 6 break n; // the value of the whole `loop` expression 7 } 8 } 9 } ``` > Control-flow-as-expression is explored fully in [Section 04 — Control Flow](/04-control-flow/). ### The unit type `()` [Section titled “The unit type ()”](#the-unit-type-) When a function has no `-> Type`, its return type is `()`, pronounced “unit”. Unit is a real type with exactly one value, also written `()`. These two signatures are identical: ```rust 1 fn log_message(msg: &str) { 2 println!("[log] {msg}"); 3 } 4 5 // Exactly the same thing, written explicitly: 6 fn log_message_explicit(msg: &str) -> () { 7 println!("[log] {msg}"); 8 } ``` `()` is the closest Rust analogue to TypeScript’s `void`, but they differ in an important way: * TypeScript’s `void` is a *type-system marker*; at runtime such functions return the value `undefined`. * Rust’s `()` is a genuine zero-size value. It has no runtime representation (it takes up zero bytes), yet you can store it, pass it, and pattern-match on it like any other value. You almost never write `-> ()` explicitly; idiomatic Rust just omits the return type. ### Early return with `return` [Section titled “Early return with return”](#early-return-with-return) Guard clauses translate directly. Use `return value;` (with a semicolon — it is a statement) to leave early, and let the final value be a tail expression: ```rust 1 fn classify(score: i32) -> &'static str { 2 if score < 0 { 3 return "invalid"; // early return 4 } 5 if score >= 90 { 6 return "excellent"; 7 } 8 if score >= 60 { 9 return "passing"; 10 } 11 "failing" // tail expression for the remaining case 12 } ``` Note the asymmetry that trips people up: early `return` statements end with a semicolon, but the final tail expression does **not**. They are different syntactic roles, not an inconsistency. ### Returning multiple values: tuples [Section titled “Returning multiple values: tuples”](#returning-multiple-values-tuples) JavaScript reaches for an array (`[a, b]`) or object (`{ a, b }`); Rust returns a **tuple**, then you destructure it: ```rust 1 fn min_max(values: &[i32]) -> (i32, i32) { 2 // ... 3 (min, max) 4 } 5 6 // Destructure at the call site: 7 let (lo, hi) = min_max(&[7, 2, 9, 4, 1]); 8 9 // Or access positionally if you didn't destructure: 10 let pair = min_max(&[7, 2, 9, 4, 1]); 11 println!("{} {}", pair.0, pair.1); ``` Tuple fields are accessed by position (`.0`, `.1`, …), and the type `(i32, i32)` is checked at compile time: there is no risk of reading `pair[2]` and getting `undefined`. Tuples are statically sized and typed, unlike a JS array. Once you have more than two or three fields, or the positions stop being self-explanatory, prefer a named **struct**, the Rust analogue of returning an object with named keys: ```rust 1 struct Stats { 2 min: i32, 3 max: i32, 4 sum: i32, 5 } 6 7 fn stats(values: &[i32]) -> Stats { 8 let mut s = Stats { min: values[0], max: values[0], sum: 0 }; 9 for &v in values { 10 if v < s.min { s.min = v; } 11 if v > s.max { s.max = v; } 12 s.sum += v; 13 } 14 s 15 } ``` (Structs get full treatment in [Section 06 — Data Structures](/06-data-structures/).) ### Bonus: the never type `!` [Section titled “Bonus: the never type !”](#bonus-the-never-type-) A function that *never returns normally* (it loops forever or always panics) has the special return type `!`, the **never type**. `!` coerces to any type, which is why a panicking branch can sit alongside an `i32` branch: ```rust 1 fn bail(msg: &str) -> ! { 2 panic!("fatal: {msg}"); 3 } 4 5 fn get_config(present: bool) -> i32 { 6 if present { 7 42 8 } else { 9 bail("config missing"); // type `!` coerces to i32 10 } 11 } ``` TypeScript has a direct counterpart: the `never` type, used for functions that always throw or loop forever. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript | Rust | | ----------------------------- | --------------------------------------------- | ------------------------------------------ | | Normal return | `return value;` on every path | Tail expression (no `return`, no `;`) | | `return` keyword | The only way to return a value | Reserved for **early** returns | | ”No value” function | `void` → returns `undefined` at runtime | `()` (unit), a zero-size real value | | Return type position | After params: `(x: number): number` | After params with arrow: `(x: i32) -> i32` | | Multiple values | Array `[a, b]` or object `{ a, b }` | Tuple `(a, b)` or a named `struct` | | Index access on returned pair | `arr[0]`, may be `undefined` if out of bounds | `tuple.0`, checked at compile time | | Block produces a value | No (needs IIFE or explicit `return`) | Yes — a block is an expression | | Never-returns marker | `never` | `!` (the never type) | ### Why does Rust make the last expression the return value? [Section titled “Why does Rust make the last expression the return value?”](#why-does-rust-make-the-last-expression-the-return-value) It is a consequence of being expression-oriented. Once `if`, `match`, blocks, and `loop` all produce values, “the function returns its body’s value” falls out naturally and removes a whole category of mistakes (forgetting `return` on one branch). TypeScript can flag missing returns with `noImplicitReturns`, but it remains an opt-in lint; in Rust the type system enforces it structurally: every path must produce the declared type or it does not compile. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Accidental semicolon on the tail expression [Section titled “Pitfall 1: Accidental semicolon on the tail expression”](#pitfall-1-accidental-semicolon-on-the-tail-expression) **Problem:** ```rust 1 fn square(n: i32) -> i32 { 2 n * n; // BUG: trailing semicolon makes this a statement, returns () 3 } ``` **Real compiler error:** ```plaintext 1 error[E0308]: mismatched types 2 --> src/main.rs:1:22 3 | 4 1 | fn square(n: i32) -> i32 { 5 | ------ ^^^ expected `i32`, found `()` 6 | | 7 | implicitly returns `()` as its body has no tail or `return` expression 8 2 | n * n; // BUG: trailing semicolon makes this a statement, not the return value 9 | - help: remove this semicolon to return this value 10 11 For more information about this error, try `rustc --explain E0308`. ``` **Solution:** Remove the semicolon. The compiler even points at it (`help: remove this semicolon to return this value`). ```rust 1 fn square(n: i32) -> i32 { 2 n * n 3 } ``` ### Pitfall 2: Forgetting the return type annotation [Section titled “Pitfall 2: Forgetting the return type annotation”](#pitfall-2-forgetting-the-return-type-annotation) Rust does **not** infer the return type of a top-level function from its body (unlike closures, and unlike TypeScript inferring `: number`). If the body produces a value, you must declare the type. **Problem:** ```rust 1 fn add(a: i32, b: i32) { 2 a + b 3 } ``` **Real compiler error:** ```plaintext 1 error[E0308]: mismatched types 2 --> src/main.rs:3:5 3 | 4 2 | fn add(a: i32, b: i32) { 5 | - help: try adding a return type: `-> i32` 6 3 | a + b 7 | ^^^^^ expected `()`, found `i32` 8 9 For more information about this error, try `rustc --explain E0308`. ``` The compiler assumed `-> ()` because none was given, then found an `i32`. **Solution:** add `-> i32`. ```rust 1 fn add(a: i32, b: i32) -> i32 { 2 a + b 3 } ``` ### Pitfall 3: Mismatched `if`/`else` branch types [Section titled “Pitfall 3: Mismatched if/else branch types”](#pitfall-3-mismatched-ifelse-branch-types) Because `if` is an expression used as the return value, every branch must yield the **same** type. TypeScript would happily widen to a union (`number | string`); Rust will not. **Problem:** ```rust 1 fn describe(n: i32) -> i32 { 2 if n > 0 { 3 n 4 } else { 5 "negative or zero" // wrong type! 6 } 7 } ``` **Real compiler error:** ```plaintext 1 error[E0308]: mismatched types 2 --> src/main.rs:6:9 3 | 4 2 | fn describe(n: i32) -> i32 { 5 | --- expected `i32` because of return type 6 ... 7 6 | "negative or zero" // wrong type! 8 | ^^^^^^^^^^^^^^^^^^ expected `i32`, found `&str` 9 10 For more information about this error, try `rustc --explain E0308`. ``` **Solution:** make both arms the same type (e.g. return a `&str` describing the number, or an `enum`). If you genuinely need “either a number or a message,” model it with an `enum` or `Result`; see [Section 08 — Error Handling](/08-error-handling/). ### Pitfall 4: Writing `return` as the last line [Section titled “Pitfall 4: Writing return as the last line”](#pitfall-4-writing-return-as-the-last-line) It compiles and runs, but it is not idiomatic, and Clippy will tell you so. **Code:** ```rust 1 fn square(n: i32) -> i32 { 2 return n * n; 3 } ``` **Real `cargo clippy` warning:** ```plaintext 1 warning: unneeded `return` statement 2 --> src/main.rs:2:5 3 | 4 2 | return n * n; // clippy will flag this needless return 5 | ^^^^^^^^^^^^ 6 | 7 = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#needless_return 8 = note: `#[warn(clippy::needless_return)]` on by default 9 help: remove `return` ``` **Solution:** drop the `return` and the trailing semicolon, leaving the bare tail expression `n * n`. ### Pitfall 5: Expecting `void`/`()` to behave like `undefined` [Section titled “Pitfall 5: Expecting void/() to behave like undefined”](#pitfall-5-expecting-void-to-behave-like-undefined) In TypeScript you might write `const r = doThing();` and then check `if (r === undefined)`. In Rust, a function returning `()` gives you a value you cannot meaningfully test; there is exactly one `()`. Trying to print or compare it is almost always a sign you wanted a real return type (often `Option` or `Result`). If a function “might not produce a value,” return `Option`, not `()`. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Prefer tail expressions over `return` [Section titled “Prefer tail expressions over return”](#prefer-tail-expressions-over-return) ```rust 1 // Idiomatic 2 fn fahrenheit(c: f64) -> f64 { 3 c * 9.0 / 5.0 + 32.0 4 } 5 6 // Not idiomatic (Clippy: needless_return) 7 fn fahrenheit_verbose(c: f64) -> f64 { 8 return c * 9.0 / 5.0 + 32.0; 9 } ``` ### Use `return` for genuine early exits / guard clauses [Section titled “Use return for genuine early exits / guard clauses”](#use-return-for-genuine-early-exits--guard-clauses) Guard clauses keep the happy path un-nested and are the canonical reason to reach for `return`: ```rust 1 fn paginate(total_items: u32, page: u32, per_page: u32) -> (u32, u32) { 2 if per_page == 0 { 3 return (0, 0); // guard clause 4 } 5 let offset = page.saturating_sub(1) * per_page; 6 (offset, per_page) 7 } ``` ### Return tuples for 2-3 unnamed values; use a struct beyond that [Section titled “Return tuples for 2-3 unnamed values; use a struct beyond that”](#return-tuples-for-2-3-unnamed-values-use-a-struct-beyond-that) A `(width, height)` tuple is clear. A `(u32, u32, u32, bool, String)` tuple is not: give the fields names with a struct. When absence is possible, return `Option<(A, B)>` rather than a sentinel value like `(-1, -1)`. ### Let the type system enforce totality [Section titled “Let the type system enforce totality”](#let-the-type-system-enforce-totality) Don’t disable return checking. Every path producing the declared type is a feature: it is impossible to forget a branch, the way you can in JavaScript without `noImplicitReturns`. ### Don’t annotate `-> ()` [Section titled “Don’t annotate -> ()”](#dont-annotate---) Omit the return type for unit-returning functions; `fn f() {}` is preferred over `fn f() -> () {}`. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small slice of an API layer: computing pagination metadata (early returns + a tuple result) and parsing a `key=value` line (early return + `Option` of a tuple). ```rust 1 /// Compute pagination metadata for a list endpoint. 2 /// 3 /// Returns `(offset, limit, total_pages)`. Uses early returns to clamp 4 /// invalid input instead of nesting the happy path inside `if` blocks. 5 fn paginate(total_items: u32, page: u32, per_page: u32) -> (u32, u32, u32) { 6 // Guard clause: a zero page size has no sensible offset/limit. 7 if per_page == 0 { 8 return (0, 0, 0); 9 } 10 11 // Pages are 1-based for the caller; treat 0 as "first page". 12 let page = if page == 0 { 1 } else { page }; 13 14 let total_pages = total_items.div_ceil(per_page); 15 let offset = (page - 1) * per_page; 16 let limit = per_page; 17 18 (offset, limit, total_pages) 19 } 20 21 /// Parse a `key=value` configuration line. 22 /// 23 /// Returns `None` for malformed input — the absence is modeled with 24 /// `Option`, not a sentinel string. The `?` propagates the `None` from 25 /// `split_once` as an early return. 26 fn parse_kv(input: &str) -> Option<(String, String)> { 27 let (key, value) = input.split_once('=')?; 28 let key = key.trim(); 29 let value = value.trim(); 30 if key.is_empty() { 31 return None; // explicit early return for the empty-key case 32 } 33 Some((key.to_string(), value.to_string())) 34 } 35 36 fn main() { 37 let (offset, limit, pages) = paginate(95, 3, 20); 38 println!("offset={offset}, limit={limit}, total_pages={pages}"); 39 40 let (offset, limit, pages) = paginate(95, 0, 0); 41 println!("offset={offset}, limit={limit}, total_pages={pages}"); 42 43 println!("{:?}", parse_kv(" host = localhost ")); 44 println!("{:?}", parse_kv("=oops")); 45 println!("{:?}", parse_kv("no-equals")); 46 } ``` **Output:** ```plaintext 1 offset=40, limit=20, total_pages=5 2 offset=0, limit=0, total_pages=0 3 Some(("host", "localhost")) 4 None 5 None ``` Notice three return-value techniques working together: a **tuple** for `(offset, limit, total_pages)`, **early returns** for guard clauses, and `?` — which is itself an early return that yields `None` from a function returning `Option`. The `?` operator is covered in depth in [Section 08 — Error Handling](/08-error-handling/). > **Note:** `u32::div_ceil` (ceiling division) is a stable standard-library method, handy for computing page counts without floating point. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Functions](https://doc.rust-lang.org/book/ch03-03-how-functions-work.html): statements, expressions, and return values * [Rust Reference — Functions](https://doc.rust-lang.org/reference/items/functions.html): the formal definition of function items and return types * [Rust Reference — The `()` type](https://doc.rust-lang.org/std/primitive.unit.html): the unit type * [Rust Reference — The `!` type](https://doc.rust-lang.org/std/primitive.never.html): the never type * [Clippy: `needless_return`](https://rust-lang.github.io/rust-clippy/master/index.html#needless_return): why `return` on the last line is flagged ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Basic Functions](/03-functions/00-basic-functions/): `fn` signatures, statements vs. expressions * [Parameters](/03-functions/01-parameters/): passing data in (the counterpart to this page) * [Arrow Functions vs Closures](/03-functions/03-arrow-vs-closures/): closures *do* infer their return type * [Higher-Order Functions](/03-functions/04-higher-order/): returning closures with `impl Fn` / `Box` * [Recursion](/03-functions/06-recursion/): returning from recursive calls * [Section 02 — Basics](/02-basics/) — the expression/statement distinction * [Section 04 — Control Flow](/04-control-flow/) — `if`/`match`/`loop` as expressions * [Section 06 — Data Structures](/06-data-structures/) — structs for named multi-value returns * [Section 08 — Error Handling](/08-error-handling/) — `Option`/`Result` and the `?` operator *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: From explicit `return` to tail expression [Section titled “Exercise 1: From explicit return to tail expression”](#exercise-1-from-explicit-return-to-tail-expression) **Difficulty:** Beginner **Objective:** Internalize that the last expression is the return value. **Instructions:** Rewrite this function in idiomatic Rust style (no `return`, no trailing semicolon on the result). It converts Celsius to Fahrenheit. ```rust 1 fn celsius_to_fahrenheit(c: f64) -> f64 { 2 return c * 9.0 / 5.0 + 32.0; 3 } 4 5 fn main() { 6 println!("{}", celsius_to_fahrenheit(100.0)); // 212 7 } ``` Solution ```rust 1 fn celsius_to_fahrenheit(c: f64) -> f64 { 2 c * 9.0 / 5.0 + 32.0 3 } 4 5 fn main() { 6 println!("{}", celsius_to_fahrenheit(100.0)); // 212 7 } ``` Running it prints `212`. Dropping both the `return` keyword and the trailing semicolon leaves a bare tail expression, which is what the function returns. ### Exercise 2: Return multiple values with a tuple [Section titled “Exercise 2: Return multiple values with a tuple”](#exercise-2-return-multiple-values-with-a-tuple) **Difficulty:** Intermediate **Objective:** Return more than one value and destructure it at the call site. **Instructions:** Implement `divmod`, which returns both the integer quotient and the remainder of `a / b` as a tuple `(quotient, remainder)`. Destructure the result in `main` and print both parts. ```rust 1 fn divmod(a: i32, b: i32) -> (i32, i32) { 2 // TODO: return (quotient, remainder) 3 } 4 5 fn main() { 6 let (q, r) = divmod(17, 5); 7 println!("q={q}, r={r}"); // q=3, r=2 8 } ``` Solution ```rust 1 fn divmod(a: i32, b: i32) -> (i32, i32) { 2 (a / b, a % b) // tuple tail expression 3 } 4 5 fn main() { 6 let (q, r) = divmod(17, 5); 7 println!("q={q}, r={r}"); // q=3, r=2 8 } ``` Running it prints `q=3, r=2`. The tuple `(a / b, a % b)` is the function’s value, and `let (q, r) = ...` destructures it. ### Exercise 3: Early return + `Option` of a tuple [Section titled “Exercise 3: Early return + Option of a tuple”](#exercise-3-early-return--option-of-a-tuple) **Difficulty:** Advanced **Objective:** Combine guard clauses, the `?` operator, and a tuple return modeled with `Option`. **Instructions:** Implement `parse_kv` so it parses a `key=value` string into `Some((key, value))` with both parts trimmed. Return `None` if there is no `=` **or** if the key is empty after trimming. Use `str::split_once` and the `?` operator. ```rust 1 fn parse_kv(input: &str) -> Option<(String, String)> { 2 // TODO: split on '=', trim both sides, reject empty keys 3 } 4 5 fn main() { 6 println!("{:?}", parse_kv(" host = localhost ")); // Some(("host", "localhost")) 7 println!("{:?}", parse_kv("=oops")); // None 8 println!("{:?}", parse_kv("no-equals")); // None 9 } ``` Solution ```rust 1 fn parse_kv(input: &str) -> Option<(String, String)> { 2 let (key, value) = input.split_once('=')?; // `?` returns None early if no '=' 3 let key = key.trim(); 4 let value = value.trim(); 5 if key.is_empty() { 6 return None; // explicit early return 7 } 8 Some((key.to_string(), value.to_string())) 9 } 10 11 fn main() { 12 println!("{:?}", parse_kv(" host = localhost ")); 13 println!("{:?}", parse_kv("=oops")); 14 println!("{:?}", parse_kv("no-equals")); 15 } ``` Output: ```plaintext 1 Some(("host", "localhost")) 2 None 3 None ``` The `?` after `split_once` is an early return that yields `None` when there is no `=`; the explicit `return None` handles the empty-key case; and `Some((..., ...))` is the tuple tail expression for the success path. *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * A function returns its **tail expression**: last line, no semicolon, no `return`. * A trailing semicolon turns that expression into a statement of type `()`. * `return` is reserved for **early** exits (guard clauses, `?`). * Functions with no `-> Type` return `()`, the unit type (Rust’s `void`-like value). * Return several values as a **tuple** (or a named **struct** when the fields deserve names). * Every code path must produce the declared type, enforced by the compiler. **Key syntax:** ```rust 1 fn f(x: i32) -> i32 { x + 1 } // tail expression 2 fn g() { /* ... */ } // returns () 3 fn h(n: i32) -> i32 { // early return + tail expression 4 if n < 0 { return 0; } 5 n * 2 6 } 7 fn pair() -> (i32, i32) { (1, 2) } // tuple of multiple values ``` # Arrow Functions vs Closures > Rust closures are JavaScript arrow functions with |args| syntax, but the compiler tracks how they capture state via the Fn, FnMut, and FnOnce traits. If there is one Rust feature that feels immediately *familiar* to a TypeScript/JavaScript developer, it is the **closure**. Rust closures are the direct counterpart of JavaScript arrow functions: small, anonymous functions that capture variables from the surrounding scope. The syntax is different (`|args|` instead of `(args) =>`), and Rust’s ownership system adds rules that JavaScript never enforces, but the mental model transfers almost perfectly. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **closure** is an anonymous function that can **capture** values from the scope in which it is defined. In TypeScript/JavaScript you write these as arrow functions (`(x) => x * 2`); in Rust you write them with vertical-bar parameter lists (`|x| x * 2`). The big new idea is *how* a closure captures its environment: Rust tracks whether a closure reads, mutates, or takes ownership of captured values, and encodes that in three traits: `Fn`, `FnMut`, and `FnOnce`. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // A "counter factory" — a classic use of closures in JavaScript. 2 // The returned arrow function closes over the `count` variable. 3 function makeCounter(): () => number { 4 let count = 0; 5 return () => { 6 count += 1; // mutates a captured variable 7 return count; 8 }; 9 } 10 11 const next = makeCounter(); 12 console.log(next()); // 1 13 console.log(next()); // 2 14 console.log(next()); // 3 15 16 // Arrow functions capturing a value from the enclosing scope: 17 const factor = 3; 18 const scale = (n: number) => n * factor; // closes over `factor` 19 console.log(scale(5)); // 15 20 21 // Closures are also the everyday argument to array methods: 22 const numbers = [1, 2, 3, 4, 5, 6]; 23 const threshold = 3; 24 const big = numbers.filter((n) => n > threshold); // closes over `threshold` 25 console.log(big); // [4, 5, 6] ``` **Key points:** * Arrow functions can read **and** mutate variables from the enclosing scope. * Capture is implicit and always by reference to the variable. * There is no notion of “ownership”; the garbage collector keeps captured values alive as long as the closure exists. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 fn main() { 2 // The same closures, written the Rust way. 3 let double = |n: i32| n * 2; 4 println!("{}", double(10)); // 20 5 6 let add = |a: i32, b: i32| a + b; 7 println!("{}", add(3, 4)); // 7 8 9 // A multi-line body uses braces, just like a block expression: 10 let describe = |n: i32| { 11 let parity = if n % 2 == 0 { "even" } else { "odd" }; 12 format!("{n} is {parity}") 13 }; 14 println!("{}", describe(7)); // 7 is odd 15 16 // A zero-argument closure has empty bars: 17 let greet = || println!("Hello from a closure!"); 18 greet(); 19 20 // Capturing a value from the environment (by reference): 21 let factor = 3; 22 let scale = |n: i32| n * factor; // borrows `factor` 23 println!("{}", scale(5)); // 15 24 println!("factor still usable: {factor}"); // 3 25 26 // Capturing and MUTATING a value (an FnMut closure): 27 let mut count = 0; 28 let mut increment = || { 29 count += 1; 30 count 31 }; 32 println!("{}", increment()); // 1 33 println!("{}", increment()); // 2 34 35 // Taking OWNERSHIP of a captured value with `move` (an FnOnce closure here): 36 let name = String::from("Ada"); 37 let consume = move || name.to_uppercase(); // `name` was moved in 38 println!("{}", consume()); // ADA 39 } ``` **Output:** ```plaintext 1 20 2 7 3 7 is odd 4 Hello from a closure! 5 15 6 factor still usable: 3 7 1 8 2 9 ADA ``` **Key points:** * Parameters go between `|bars|`; the body is a single expression or a `{ block }`. * Parameter and return types are usually *inferred* — you rarely annotate them. * How a closure captures (`borrow`, `mutable borrow`, or `move`) is decided by the compiler based on what the body does, and you can force a move with the `move` keyword. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Syntax: `|args|` is the new `(args) =>` [Section titled “Syntax: |args| is the new (args) =>”](#syntax-args-is-the-new-args-) The translation is mechanical: | TypeScript/JavaScript | Rust | | --------------------------- | ------------------ | | `(n) => n * 2` | `\|n\| n * 2` | | `(a, b) => a + b` | `\|a, b\| a + b` | | `() => doThing()` | `\|\| do_thing()` | | `(n) => { ...; return x; }` | `\|n\| { ...; x }` | In Rust the body after `|args|` is an expression. A single expression needs no braces (`|n| n * 2`). For multiple statements you use a `{ }` block, and (as everywhere in Rust) the final expression *without* a semicolon is the return value. (See [Statements vs expressions](/03-functions/00-basic-functions/) and [return values](/03-functions/02-return-values/) for the full story.) > **Note:** Closure parameter types are usually inferred, unlike a top-level `fn`, which *must* annotate every parameter. When inference needs help you can annotate: `|n: i32| -> i32 { n * 2 }`. The `-> ReturnType` is only allowed when the body is a braced block. ### How capture works: the three traits [Section titled “How capture works: the three traits”](#how-capture-works-the-three-traits) This is the part with no JavaScript equivalent. When a closure uses a variable from its surroundings, the compiler picks the *least invasive* way to capture it, and that choice determines which of three **traits** the closure implements: * **`Fn`**: the closure captures values **by immutable reference** (`&T`). It only reads them, so it can be called many times and even from several places at once. * **`FnMut`**: the closure captures **by mutable reference** (`&mut T`). It changes captured state, so it can be called many times but needs a `mut` binding. * **`FnOnce`**: the closure captures **by value** (it takes ownership / moves things in). It may only be guaranteed to be callable **once**, because calling it might consume the captured values. These form a hierarchy: every `Fn` is also an `FnMut`, and every `FnMut` is also an `FnOnce`. (Anything you can call repeatedly, you can certainly call once.) When you *accept* a closure as a parameter, ask for the **weakest** trait that works: `FnOnce` if you call it once, `FnMut` if you call it repeatedly and it mutates, `Fn` if it only reads. ```rust 1 // Reads its environment only — call it as many times as you like. 2 fn apply_twice i32>(f: F, x: i32) -> i32 { 3 f(f(x)) 4 } 5 6 // Mutates state across calls — note `mut f`. 7 fn repeat(mut f: F, times: u32) { 8 for _ in 0..times { 9 f(); 10 } 11 } 12 13 // May consume captured values — called exactly once. 14 fn call_once String>(f: F) -> String { 15 f() 16 } 17 18 fn main() { 19 println!("{}", apply_twice(|n| n + 3, 10)); // 16 20 21 let mut total = 0; 22 repeat(|| total += 1, 5); 23 println!("{total}"); // 5 24 25 let greeting = String::from("hi"); 26 let msg = call_once(move || greeting + " there"); // moves `greeting` in 27 println!("{msg}"); // hi there 28 } ``` **Output:** ```plaintext 1 16 2 5 3 hi there ``` The compiler chose the trait for each closure automatically: `|n| n + 3` only reads, so it is `Fn`; `|| total += 1` mutates `total`, so it is `FnMut`; `move || greeting + " there"` consumes `greeting` (the `+` operator on `String` takes ownership of the left side), so it is only `FnOnce`. ### Capture by reference is the default [Section titled “Capture by reference is the default”](#capture-by-reference-is-the-default) In the earlier `scale` example, `|n: i32| n * factor` only *reads* `factor`, so the closure borrows it immutably. That is why `factor` is still usable on the next line: the closure holds a shared reference, not the value itself. This is exactly like JavaScript closing over a `const`, except Rust’s borrow checker enforces that nobody mutates `factor` while the closure’s borrow is alive. ### `move`: forcing capture by value [Section titled “move: forcing capture by value”](#move-forcing-capture-by-value) The `move` keyword forces a closure to take **ownership** of everything it captures, instead of borrowing. You need it whenever the closure must outlive the scope that created the captured values, most importantly when spawning threads or returning a closure from a function: ```rust 1 use std::thread; 2 3 fn main() { 4 let data = vec![1, 2, 3]; 5 6 // `move` transfers ownership of `data` into the new thread, so the 7 // closure can safely outlive `main`'s stack frame. 8 let handle = thread::spawn(move || { 9 let sum: i32 = data.iter().sum(); 10 println!("sum in thread: {sum}"); 11 }); 12 13 handle.join().unwrap(); 14 } ``` **Output:** ```plaintext 1 sum in thread: 6 ``` Without `move`, the closure would try to *borrow* `data`, but the new thread might run after `main` returns and frees `data`: a use-after-free that the borrow checker refuses to allow. The `move` keyword resolves this by handing ownership of `data` to the closure. > **Tip:** `move` does not automatically make a closure `FnOnce`. A `move` closure that only *reads* its captured values (or captures only `Copy` types) is still `Fn`. `move` controls *how* values are captured (by value vs by reference); the `Fn`/`FnMut`/`FnOnce` traits describe what *calling* the closure does to those captured values. For `Copy` types (like integers), `move` copies the value in, leaving the original usable: ```rust 1 fn main() { 2 let x = 10; // i32 is Copy 3 let add_x = move |n: i32| n + x; // copies x into the closure 4 println!("{}", add_x(5)); // 15 5 println!("x still usable: {x}"); // 10 — Copy types are duplicated, not moved away 6 } ``` **Output:** ```plaintext 1 15 2 10 ``` *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript | Rust | | ------------------------- | --------------------------------------- | ---------------------------------------------------------------- | | Syntax | `(a, b) => a + b` | `\|a, b\| a + b` | | Parameter types | Optional annotations; erased at runtime | Usually inferred; can annotate `\|n: i32\|` | | How capture is decided | Always by reference to the variable | Compiler picks `&`, `&mut`, or by-value (override with `move`) | | Mutating captured state | Always allowed | Closure must be `FnMut` and bound with `let mut` | | Lifetime of captured data | GC keeps it alive forever if needed | Borrow checker enforces captured borrows do not outlive the data | | Calling repeatedly | Always allowed | `Fn`/`FnMut` yes; `FnOnce` only guaranteed once | | Each closure’s type | Structural: same signature = same type | Every closure has a unique, anonymous, compiler-generated type | ### Every closure has its own unique type [Section titled “Every closure has its own unique type”](#every-closure-has-its-own-unique-type) In TypeScript, two arrow functions with the same signature share the type `(n: number) => number`. In Rust, **each closure has its own anonymous type** generated by the compiler — even two closures with identical signatures are different types. This is why functions that take closures use generics (`F: Fn(...)`) or trait objects (`Box`), a topic covered in detail in [Higher-Order Functions](/03-functions/04-higher-order/) and [Function Pointers](/03-functions/05-function-pointers/). ### Closures vs. plain functions [Section titled “Closures vs. plain functions”](#closures-vs-plain-functions) A Rust closure can capture its environment; a named `fn` cannot. That captured environment is stored inline in the closure value, so closures are *not* the same as a `fn` pointer. The relationship between the two, and when a closure can coerce to a function pointer, is the subject of [Function Pointers](/03-functions/05-function-pointers/). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: A closure’s parameter type is locked in at first use [Section titled “Pitfall 1: A closure’s parameter type is locked in at first use”](#pitfall-1-a-closures-parameter-type-is-locked-in-at-first-use) Because closure types are inferred, the compiler fixes the parameter and return types the **first time** the closure is called (or otherwise constrained). Calling it later with a different type is an error; there is no implicit polymorphism like a JavaScript function would have. ```rust 1 fn main() { 2 let identity = |x| x; 3 let a = identity(5); 4 let b = identity("hello"); // ← different type! 5 println!("{a} {b}"); 6 } ``` **Real compiler error:** ```plaintext 1 error[E0308]: mismatched types 2 --> src/main.rs:4:22 3 | 4 4 | let b = identity("hello"); 5 | -------- ^^^^^^^ expected integer, found `&str` 6 | | 7 | arguments to this function are incorrect 8 | 9 note: expected because the closure was earlier called with an argument of type `{integer}` 10 --> src/main.rs:3:22 11 | 12 3 | let a = identity(5); 13 | -------- ^ expected because this argument is of type `{integer}` 14 | | 15 | in this closure call 16 note: closure parameter defined here 17 --> src/main.rs:2:21 18 | 19 2 | let identity = |x| x; 20 | ^ ``` If you genuinely need “one function, many types,” that is what *generics* are for — use a generic `fn` (see [Generics & Traits](/09-generics-traits/)), not a closure. ### Pitfall 2: Using a value after a `move` closure took it [Section titled “Pitfall 2: Using a value after a move closure took it”](#pitfall-2-using-a-value-after-a-move-closure-took-it) A `move` closure that captures a non-`Copy` value (like a `String` or `Vec`) takes ownership. The original variable is then gone: ```rust 1 fn main() { 2 let name = String::from("Ada"); 3 let consume = move || println!("{name}"); 4 consume(); 5 println!("{name}"); // ← `name` was moved into the closure 6 } ``` **Real compiler error:** ```plaintext 1 error[E0382]: borrow of moved value: `name` 2 --> src/main.rs:5:16 3 | 4 2 | let name = String::from("Ada"); 5 | ---- move occurs because `name` has type `String`, which does not implement the `Copy` trait 6 3 | let consume = move || println!("{name}"); 7 | ------- ---- variable moved due to use in closure 8 | | 9 | value moved into closure here 10 4 | consume(); 11 5 | println!("{name}"); // ← `name` was moved into the closure 12 | ^^^^ value borrowed here after move 13 | 14 = note: this error originates in the macro `$crate::format_args_nl` which comes from the expansion of the macro `println` (in Nightly builds, run with -Z macro-backtrace for more info) 15 help: consider cloning the value before moving it into the closure 16 | 17 3 ~ let value = name.clone(); 18 4 ~ let consume = move || println!("{value}"); 19 | ``` As the compiler suggests, clone the value first if you need both copies, or simply do not use `move` if a borrow is sufficient. This is ownership in action; see [Ownership](/05-ownership/) for the full model. ### Pitfall 3: Forgetting `let mut` for an `FnMut` closure [Section titled “Pitfall 3: Forgetting let mut for an FnMut closure”](#pitfall-3-forgetting-let-mut-for-an-fnmut-closure) A closure that mutates captured state must itself be stored in a `mut` binding, because *calling* it mutably borrows the closure: ```rust 1 fn main() { 2 let mut count = 0; 3 let increment = || { 4 count += 1; 5 }; 6 increment(); // ← needs a mutable binding 7 println!("{count}"); 8 } ``` **Real compiler error:** ```plaintext 1 error[E0596]: cannot borrow `increment` as mutable, as it is not declared as mutable 2 --> src/main.rs:6:5 3 | 4 4 | count += 1; 5 | ----- calling `increment` requires mutable binding due to mutable borrow of `count` 6 5 | }; 7 6 | increment(); // ← needs a mutable binding 8 | ^^^^^^^^^ cannot borrow as mutable 9 | 10 help: consider changing this to be mutable 11 | 12 3 | let mut increment = || { 13 | +++ ``` The fix is exactly what the compiler says: `let mut increment = || { ... };`. This trips up TypeScript/JavaScript developers because in JavaScript a mutating closure is indistinguishable from a non-mutating one: there is no `mut` to forget. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Let types be inferred [Section titled “1. Let types be inferred”](#1-let-types-be-inferred) Idiomatic Rust closures are terse. Prefer `|n| n * 2` over `|n: i32| -> i32 { n * 2 }` unless the compiler cannot infer the types or an annotation genuinely aids readability. ### 2. Only use `move` when you need it [Section titled “2. Only use move when you need it”](#2-only-use-move-when-you-need-it) Reach for `move` when the closure must outlive its defining scope: spawning threads, returning a closure, or storing one in a struct or `async` task. For ordinary inline use with iterator adapters, the default borrowing capture is usually what you want and avoids unnecessary clones. ### 3. Accept the weakest trait that works [Section titled “3. Accept the weakest trait that works”](#3-accept-the-weakest-trait-that-works) When writing a function that takes a closure, choose `FnOnce` if you call it once, `FnMut` if it mutates and you call it repeatedly, and `Fn` if it only reads. Asking for less makes your function callable with more closures. (Details and the `impl Fn` / `Box` return patterns live in [Higher-Order Functions](/03-functions/04-higher-order/).) ### 4. Use closures with iterator adapters [Section titled “4. Use closures with iterator adapters”](#4-use-closures-with-iterator-adapters) The single most common place you will write closures is in iterator chains: `map`, `filter`, `fold`, and friends. This replaces the `Array.prototype` methods you know from JavaScript: ```rust 1 fn main() { 2 let numbers = vec![1, 2, 3, 4, 5, 6]; 3 let threshold = 3; 4 // `into_iter` consumes the vec; the closure captures `threshold` by reference. 5 let big: Vec = numbers.into_iter().filter(|&n| n > threshold).collect(); 6 println!("{big:?}"); // [4, 5, 6] 7 } ``` **Output:** ```plaintext 1 [4, 5, 6] ``` > **Tip:** `|&n|` here is *pattern matching* in the parameter position: `filter` hands the closure a `&i32`, and `&n` destructures it so `n` is a plain `i32`. Without it you would write `|n| *n > threshold`. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A retry helper is a production-flavored use of an `FnMut` closure: real retries often mutate state between attempts (bumping a counter, rotating an endpoint). This mirrors a hand-rolled `retry` utility you might write in TypeScript. **TypeScript:** ```typescript 1 function retry(operation: () => T, maxAttempts: number): T { 2 let lastErr: unknown; 3 for (let i = 0; i < maxAttempts; i++) { 4 try { 5 return operation(); 6 } catch (e) { 7 lastErr = e; 8 } 9 } 10 throw lastErr; 11 } 12 13 let attempt = 0; 14 const result = retry(() => { 15 attempt += 1; // the closure mutates captured state 16 if (attempt < 3) throw new Error(`attempt ${attempt} failed`); 17 return `succeeded on attempt ${attempt}`; 18 }, 5); 19 20 console.log(result); // "succeeded on attempt 3" ``` **Rust:** ```rust 1 /// Runs `operation` up to `max_attempts` times, stopping at the first `Ok`. 2 /// The operation is `FnMut` because real-world retries often mutate state 3 /// (bump an attempt counter, rotate an endpoint, etc.). 4 fn retry(mut operation: F, max_attempts: u32) -> Result 5 where 6 F: FnMut() -> Result, 7 { 8 let mut last_err = None; 9 for _ in 0..max_attempts { 10 match operation() { 11 Ok(value) => return Ok(value), 12 Err(e) => last_err = Some(e), 13 } 14 } 15 Err(last_err.expect("max_attempts must be > 0")) 16 } 17 18 fn main() { 19 // Simulate a flaky service that fails twice, then succeeds. 20 let mut attempt = 0; 21 let result = retry( 22 || { 23 attempt += 1; // the closure mutates captured state -> FnMut 24 if attempt < 3 { 25 Err(format!("attempt {attempt} failed")) 26 } else { 27 Ok(format!("succeeded on attempt {attempt}")) 28 } 29 }, 30 5, 31 ); 32 33 match result { 34 Ok(msg) => println!("OK: {msg}"), 35 Err(e) => println!("gave up: {e}"), 36 } 37 } ``` **Output:** ```plaintext 1 OK: succeeded on attempt 3 ``` Notice the contrasts with the TypeScript version. Rust uses `Result` instead of exceptions (no `try`/`catch`), the closure parameter is constrained with `F: FnMut() -> Result` in a `where` clause, and `operation` is declared `mut` so it can be called repeatedly while mutating `attempt`. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Closures: Anonymous Functions that Capture Their Environment](https://doc.rust-lang.org/book/ch13-01-closures.html) * [Rust by Example — Closures](https://doc.rust-lang.org/rust-by-example/fn/closures.html) * [Rust Reference — Closure expressions](https://doc.rust-lang.org/reference/expressions/closure-expr.html) * [`std::ops::Fn`](https://doc.rust-lang.org/std/ops/trait.Fn.html), [`FnMut`](https://doc.rust-lang.org/std/ops/trait.FnMut.html), [`FnOnce`](https://doc.rust-lang.org/std/ops/trait.FnOnce.html) ### Related Topics in This Guide [Section titled “Related Topics in This Guide”](#related-topics-in-this-guide) * [Basic Functions](/03-functions/00-basic-functions/) — `fn` definitions, signatures, statements vs expressions * [Function Parameters](/03-functions/01-parameters/) — Rust’s alternatives to default and rest parameters * [Return Values](/03-functions/02-return-values/) — tail expressions, the unit type, returning tuples * [Higher-Order Functions](/03-functions/04-higher-order/) — taking and returning closures (`impl Fn`, `Box`); `map`/`filter`/`fold` * [Function Pointers](/03-functions/05-function-pointers/) — the `fn` type, named functions, closures vs function items * [Ownership](/05-ownership/) — the model behind `move` and capture * [Variables and Mutability](/02-basics/00-variables/) — why `let mut` matters for `FnMut` * [Control Flow](/04-control-flow/) — the iterator chains where closures live *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Translate the arrow functions [Section titled “Exercise 1: Translate the arrow functions”](#exercise-1-translate-the-arrow-functions) **Difficulty:** Easy **Objective:** Get comfortable with `|args|` syntax and capture-by-reference. **Instructions:** Rewrite this TypeScript snippet in Rust. Keep `threshold` as a captured variable; do not hardcode it into the closure. ```typescript 1 const numbers = [1, 2, 3, 4, 5, 6]; 2 const threshold = 3; 3 const big = numbers.filter((n) => n > threshold); 4 console.log(big); // [4, 5, 6] ``` Solution ```rust 1 fn main() { 2 let numbers = vec![1, 2, 3, 4, 5, 6]; 3 let threshold = 3; 4 let big: Vec = numbers.into_iter().filter(|&n| n > threshold).collect(); 5 println!("{big:?}"); // [4, 5, 6] 6 } ``` The closure `|&n| n > threshold` captures `threshold` by immutable reference (so the closure is `Fn`) and uses a `&n` pattern to destructure the `&i32` that `filter` provides. ### Exercise 2: A counter factory [Section titled “Exercise 2: A counter factory”](#exercise-2-a-counter-factory) **Difficulty:** Medium **Objective:** Return a closure that owns and mutates its own state — the Rust version of JavaScript’s `makeCounter`. **Instructions:** Implement `make_counter` so that it returns a closure which yields `1`, then `2`, then `3` on successive calls. The closure must own its count (it outlives `make_counter`), so you will need `move` and an `FnMut` return type. ```rust 1 fn make_counter() -> /* ??? */ { 2 // ... 3 } 4 5 fn main() { 6 let mut counter = make_counter(); 7 println!("{}", counter()); // 1 8 println!("{}", counter()); // 2 9 println!("{}", counter()); // 3 10 } ``` Solution ```rust 1 // `impl FnMut() -> u32` means "some concrete type that implements FnMut". 2 fn make_counter() -> impl FnMut() -> u32 { 3 let mut count = 0; 4 move || { 5 count += 1; 6 count 7 } 8 } 9 10 fn main() { 11 let mut counter = make_counter(); 12 println!("{}", counter()); // 1 13 println!("{}", counter()); // 2 14 println!("{}", counter()); // 3 15 } ``` **Output:** ```plaintext 1 1 2 2 3 3 ``` `move` is required because `count` is local to `make_counter` and must travel out with the returned closure. The binding in `main` must be `let mut counter`, because calling an `FnMut` closure mutably borrows it. Returning closures with `impl Fn` is explored further in [Higher-Order Functions](/03-functions/04-higher-order/). ### Exercise 3: Consume a captured value once [Section titled “Exercise 3: Consume a captured value once”](#exercise-3-consume-a-captured-value-once) **Difficulty:** Medium **Objective:** Build intuition for `FnOnce` and `move` capturing an owned `String`. **Instructions:** Write a function `run_once` that accepts a closure returning a `String` and calls it a single time, returning its result. Then call it with a `move` closure that consumes a captured `String` by concatenating to it. Concatenating with `+` on a `String` takes ownership of the left operand, which forces the closure to be `FnOnce`. ```rust 1 fn run_once(f: F) -> String { 2 // ... 3 } 4 5 fn main() { 6 let banner = String::from("DEPLOYING"); 7 // Build a closure that produces "DEPLOYING... done" and pass it to run_once. 8 } ``` Solution ```rust 1 fn run_once String>(f: F) -> String { 2 f() 3 } 4 5 fn main() { 6 let banner = String::from("DEPLOYING"); 7 let job = move || format!("{banner}... done"); // captures `banner` by value 8 let report = run_once(job); 9 println!("{report}"); // DEPLOYING... done 10 } ``` **Output:** ```plaintext 1 DEPLOYING... done ``` Because `run_once` only ever calls `f` once, `FnOnce` is the correct (weakest) bound — it accepts closures that consume their captured values, as well as any `Fn`/`FnMut` closure. This is the best-practice “ask for the weakest trait” rule in action. *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * Rust closures are arrow functions with `|args|` syntax instead of `(args) =>`. * Parameter and return types are usually inferred; bodies are expressions or `{ }` blocks. * Closures capture their environment by `&`, `&mut`, or by value — the compiler picks the least invasive option. * `Fn` reads, `FnMut` mutates, `FnOnce` consumes; they form a hierarchy, and you accept the weakest one that works. * `move` forces capture by value, needed when a closure must outlive its scope (threads, returned closures). * Every closure has a unique anonymous type — unlike TypeScript, where any two functions with the same structural signature share a type. **The mental model:** A closure is a small struct holding its captured variables plus a call method. JavaScript hides that machinery and lets the garbage collector sort out lifetimes; Rust makes capture explicit and proves at compile time that no captured borrow outlives its data. # Higher-Order Functions > Rust's map, filter, and fold mirror TypeScript array methods but run lazily on iterators. Pass closures with impl Fn and return them via impl Fn or Box. Higher-order functions are functions that take other functions as parameters or return functions as results. If you write TypeScript, you already use them constantly: `array.map`, `array.filter`, `array.reduce`, event handlers, and middleware are all higher-order functions. Rust has the same toolkit, but the type system makes the relationships explicit. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **higher-order function** either accepts a function (or closure) as an argument, returns one, or both. In TypeScript these are everywhere and untyped at runtime; in Rust the compiler needs to know *how* a function is passed — by generic bound (`impl Fn`), or behind a pointer (`Box`) — because closures have no single fixed size or type. This matters to a TypeScript/JavaScript developer because the iterator methods you reach for daily (`map`, `filter`, `reduce`) exist in Rust too, just lazier and with a few extra rules. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // TypeScript - higher-order functions are the bread and butter of array work 2 const numbers = [1, 2, 3, 4, 5]; 3 4 // map: transform every element 5 const doubled = numbers.map((n) => n * 2); 6 console.log(doubled); // [2, 4, 6, 8, 10] 7 8 // filter: keep elements that pass a predicate 9 const evens = numbers.filter((n) => n % 2 === 0); 10 console.log(evens); // [2, 4] 11 12 // reduce: fold everything into a single value 13 const sum = numbers.reduce((acc, n) => acc + n, 0); 14 console.log(sum); // 15 15 16 // Chaining is idiomatic 17 const sumOfOddSquares = numbers 18 .filter((n) => n % 2 === 1) 19 .map((n) => n * n) 20 .reduce((acc, n) => acc + n, 0); 21 console.log(sumOfOddSquares); // 35 22 23 // A function that RETURNS a function (a closure factory) 24 function makeAdder(n: number): (x: number) => number { 25 return (x) => x + n; 26 } 27 const add5 = makeAdder(5); 28 console.log(add5(10)); // 15 29 30 // A function that TAKES a function 31 function applyTwice(f: (x: number) => number, x: number): number { 32 return f(f(x)); 33 } 34 console.log(applyTwice((x) => x + 3, 10)); // 16 ``` **Key points:** * `map`/`filter`/`reduce` are methods on `Array`, and they run **eagerly** — each one builds a new array immediately. * A function type is just `(args) => ret`; you can store it, pass it, and return it without ceremony. * At runtime there is no difference between a closure that captures variables and one that does not — they are all just JavaScript functions (objects). *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 fn main() { 2 let numbers = vec![1, 2, 3, 4, 5]; 3 4 // map: transform every element (note: .iter() then .collect()) 5 let doubled: Vec = numbers.iter().map(|n| n * 2).collect(); 6 println!("{:?}", doubled); // [2, 4, 6, 8, 10] 7 8 // filter: keep elements that pass a predicate 9 let evens: Vec = numbers.iter().filter(|&&n| n % 2 == 0).copied().collect(); 10 println!("{:?}", evens); // [2, 4] 11 12 // reduce -> fold (with an explicit initial accumulator) 13 let sum: i32 = numbers.iter().fold(0, |acc, &n| acc + n); 14 println!("{}", sum); // 15 15 16 // Chaining is idiomatic here too 17 let sum_of_odd_squares: i32 = numbers 18 .iter() 19 .filter(|&&n| n % 2 == 1) 20 .map(|&n| n * n) 21 .sum(); 22 println!("{}", sum_of_odd_squares); // 35 23 } 24 25 // A function that RETURNS a closure (impl Fn) 26 fn make_adder(n: i32) -> impl Fn(i32) -> i32 { 27 move |x| x + n 28 } 29 30 // A function that TAKES a closure (generic over F: Fn) 31 fn apply_twice i32>(f: F, x: i32) -> i32 { 32 f(f(x)) 33 } ``` Calling those last two: ```rust 1 fn main() { 2 let add5 = make_adder(5); 3 println!("{}", add5(10)); // 15 4 5 println!("{}", apply_twice(|x| x + 3, 10)); // 16 6 } ``` **Key points:** * The iterator adapters (`map`, `filter`) are **lazy**: they build a description of work, and nothing happens until a *consumer* like `collect`, `sum`, or `fold` drives them. * `reduce` in JavaScript with an initial value maps to Rust’s `fold`. (Rust also has a `reduce` method, but it has no seed and returns an `Option`.) * Passing a closure uses a **generic bound** (`F: Fn(i32) -> i32`); returning one uses `impl Fn(...) -> ...` or, when the concrete type can vary, `Box ...>`. > **Note:** `Fn`, `FnMut`, and `FnOnce` are the three closure traits. They are covered in depth in [Arrow Functions vs Closures](/03-functions/03-arrow-vs-closures/); here we focus on *using* them in higher-order signatures. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Why `.iter()` and `.collect()`? [Section titled “Why .iter() and .collect()?”](#why-iter-and-collect) In JavaScript, `numbers.map(...)` is a method on the array that returns a brand-new array. In Rust, `map` is a method on an **iterator**, not on the `Vec` itself. So you first turn the collection into an iterator, then adapt it, then collect the results back into a concrete collection: ```rust 1 fn main() { 2 let numbers = vec![1, 2, 3, 4, 5]; 3 let doubled: Vec = numbers.iter().map(|n| n * 2).collect(); 4 // ^^^^^^^ ^^^ ^^^^^^^ 5 // make iterator transform materialize 6 println!("{:?}", doubled); 7 } ``` The `: Vec` annotation on the left is usually required because `collect` is generic over *what* it collects into (it could build a `Vec`, a `HashSet`, a `String`, etc.). The annotation tells the compiler which one you want. This is one of the few places Rust’s inference needs a hint that TypeScript would not. > **Tip:** `iter()` borrows each element (`&i32`), `iter_mut()` borrows mutably (`&mut i32`), and `into_iter()` *consumes* the collection and yields owned values (`i32`). Choosing the right one is an ownership decision, covered in [Section 05: Ownership](/05-ownership/). ### Laziness: the big difference from JavaScript [Section titled “Laziness: the big difference from JavaScript”](#laziness-the-big-difference-from-javascript) JavaScript’s array methods are eager. Each `.map(...)` allocates a new array on the spot. Rust’s iterator adapters are **lazy**: they do nothing until consumed. This is closer to a generator pipeline than to `Array.prototype.map`. ```rust 1 fn main() { 2 let numbers = vec![1, 2, 3, 4, 5]; 3 4 // This line allocates NOTHING and runs NO closures yet: 5 let pipeline = numbers.iter().filter(|&&n| n % 2 == 1).map(|&n| n * n); 6 7 // The work happens here, when a consumer drives the iterator: 8 let total: i32 = pipeline.sum(); 9 println!("{}", total); // 35 10 } ``` The payoff is that a long chain of adapters fuses into a single pass with no intermediate `Vec` allocations: `filter().map().sum()` walks the data once. In JavaScript the same chain would allocate one array per step. ### The `|&&n|` double-reference pattern [Section titled “The |&\&n| double-reference pattern”](#the-n-double-reference-pattern) You will see odd-looking patterns like `|&&n|` in `filter`. Here is the why: `numbers.iter()` yields `&i32`. `filter`’s closure receives a *reference to the item*, so it gets `&&i32`. The pattern `|&&n|` destructures both references, binding `n` to a plain `i32` you can compare: ```rust 1 fn main() { 2 let numbers = vec![1, 2, 3, 4, 5]; 3 let evens: Vec = numbers 4 .iter() // yields &i32 5 .filter(|&&n| n % 2 == 0) // closure gets &&i32; &&n -> n: i32 6 .copied() // &i32 -> i32 7 .collect(); 8 println!("{:?}", evens); // [2, 4] 9 } ``` `map`, by contrast, receives the item by value-of-the-iterator (`&i32` here), so `|&n| n * n` destructures one layer. This referencing dance has no parallel in TypeScript, where everything is a reference under the hood and you never write it out. ### Passing a closure: `impl Fn` vs generic bound [Section titled “Passing a closure: impl Fn vs generic bound”](#passing-a-closure-impl-fn-vs-generic-bound) There are three equivalent ways to write “this function takes a closure.” All three monomorphize: the compiler stamps out a specialized copy of the function for each closure type you pass, with zero indirection at runtime (like how TypeScript generics work in your head, except TypeScript erases them and Rust keeps them). ```rust 1 // 1. Generic with an inline trait bound 2 fn apply_twice i32>(f: F, x: i32) -> i32 { 3 f(f(x)) 4 } 5 6 // 2. The same thing, using `impl Trait` in argument position (sugar for #1) 7 fn apply_twice_impl(f: impl Fn(i32) -> i32, x: i32) -> i32 { 8 f(f(x)) 9 } 10 11 // 3. The same thing again, moving the bound into a `where` clause 12 fn apply_twice_where(f: F, x: i32) -> i32 13 where 14 F: Fn(i32) -> i32, 15 { 16 f(f(x)) 17 } ``` Use `Fn` when the closure only reads captured state, `FnMut` when it mutates captured state, and `FnOnce` when it consumes captured state. Asking for the *least* demanding trait you need makes your function accept the *most* callers. ```rust 1 // FnMut: the closure mutates state it captured 2 fn call_n_times(mut f: F, n: usize) { 3 for _ in 0..n { 4 f(); 5 } 6 } 7 8 // FnOnce: the closure may consume what it captured (called at most once) 9 fn consume String>(f: F) -> String { 10 f() 11 } 12 13 fn main() { 14 let mut count = 0; 15 call_n_times(|| count += 1, 5); 16 println!("count = {}", count); // count = 5 17 18 let owned = String::from("hello"); 19 let joined = consume(move || owned + " world"); // moves `owned` in 20 println!("{}", joined); // hello world 21 } ``` > **Note:** Notice `mut f` in `call_n_times`. Calling an `FnMut` closure requires a mutable binding, so the parameter itself is declared `mut`. This is a small ownership detail TypeScript never surfaces. ### Returning a closure: `impl Fn` vs `Box` [Section titled “Returning a closure: impl Fn vs Box\”](#returning-a-closure-impl-fn-vs-boxdyn-fn) Returning a function is where Rust diverges most sharply from TypeScript, because every closure has a unique, compiler-generated, anonymous type, and you cannot name it. You have two options. **Option 1 — `impl Fn`** when there is exactly one closure shape returned. This is zero-cost (no heap allocation, no indirection): ```rust 1 fn make_adder(n: i32) -> impl Fn(i32) -> i32 { 2 move |x| x + n 3 } ``` The `move` keyword forces the closure to *take ownership* of `n` so the closure can outlive the `make_adder` call. Without it, the closure would try to borrow a local that is about to be destroyed (see Pitfall 3). **Option 2 — `Box`** when the concrete closure type can differ between branches. Because `impl Fn` means “one specific hidden type,” you cannot return two different closures from two `if`/`match` arms with it. Boxing them behind a trait object (`dyn Fn`) erases the difference, at the cost of a heap allocation and dynamic dispatch: ```rust 1 fn make_op(kind: &str) -> Box i32> { 2 match kind { 3 "double" => Box::new(|x| x * 2), 4 "negate" => Box::new(|x| -x), 5 _ => Box::new(|x| x), 6 } 7 } 8 9 fn main() { 10 let double = make_op("double"); 11 let negate = make_op("negate"); 12 println!("{} {}", double(21), negate(7)); // 42 -7 13 } ``` This `dyn` (dynamic dispatch through a pointer) is the closest analogy to how a TypeScript function value works at runtime: a pointer you call indirectly. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript | Rust | | ---------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------- | | `map` / `filter` | Methods on `Array`, **eager** | Methods on `Iterator`, **lazy** until consumed | | `reduce(fn, init)` | `Array.prototype.reduce` | `Iterator::fold(init, fn)` | | `reduce(fn)` (no init) | Uses the first element as the seed; throws `TypeError` on an empty array | `Iterator::reduce(fn)` returns `Option` | | Building the result | Returns a new array automatically | `.collect()` / `.sum()` / `.count()` etc. | | Taking a function | `(x) => T` param, untyped at runtime | `impl Fn` / `F: Fn` (monomorphized, zero-cost) | | Returning a function | `(): (x) => T` | `impl Fn` (one type) or `Box` (varying types) | | Capturing variables | Always by reference to the closure scope | By ref / by mut ref / by move; `Fn`/`FnMut`/`FnOnce` | | Cost | Heap-allocated function objects, GC | `impl Fn`: zero-cost; `Box`: one allocation + dynamic dispatch | The mental model shift: in TypeScript a function is *a value of one type*. In Rust, every closure has its *own* type, so “a function parameter” must be expressed as a generic bound or a trait object. There is no single `Function` type that covers them all. > **Note:** Unlike TypeScript, where `array.map` always produces a fresh array, a Rust adapter chain produces nothing until consumed and then runs in a single fused pass. If you write a `map` and never collect or otherwise consume it, the closure never runs at all (see Pitfall 1). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Treating iterators as eager (forgetting to consume) [Section titled “Pitfall 1: Treating iterators as eager (forgetting to consume)”](#pitfall-1-treating-iterators-as-eager-forgetting-to-consume) A TypeScript developer expects `map` to *do something*. In Rust, an unconsumed adapter does nothing, and the compiler warns you: ```rust 1 fn main() { 2 let names = vec!["alice", "bob"]; 3 names.iter().map(|n| println!("Hello, {n}!")); 4 println!("done"); 5 } ``` The “Hello” lines never print. The real compiler warning: ```plaintext 1 warning: unused `Map` that must be used 2 --> src/main.rs:3:5 3 | 4 3 | names.iter().map(|n| println!("Hello, {n}!")); 5 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6 | 7 = note: iterators are lazy and do nothing unless consumed 8 = note: `#[warn(unused_must_use)]` on by default 9 help: use `let _ = ...` to ignore the resulting value 10 | 11 3 | let _ = names.iter().map(|n| println!("Hello, {n}!")); 12 | +++++++ 13 14 warning: `Iterator::map` call that discard the iterator's values 15 --> src/main.rs:3:18 16 | 17 3 | names.iter().map(|n| println!("Hello, {n}!")); 18 | ^^^^---------------------------^ 19 ... 20 help: you might have meant to use `Iterator::for_each` 21 | 22 3 - names.iter().map(|n| println!("Hello, {n}!")); 23 3 + names.iter().for_each(|n| println!("Hello, {n}!")); 24 | ``` **Fix:** if you only want side effects, use `for_each` (or a plain `for` loop); if you want results, `collect` them. ```rust 1 fn main() { 2 let names = vec!["alice", "bob"]; 3 names.iter().for_each(|n| println!("Hello, {n}!")); 4 } ``` ### Pitfall 2: Returning two different closures from one `impl Fn` [Section titled “Pitfall 2: Returning two different closures from one impl Fn”](#pitfall-2-returning-two-different-closures-from-one-impl-fn) This looks fine to a TypeScript eye but does not compile, because the two `move` closures capture `n` and are therefore *distinct anonymous types*: ```rust 1 fn make_op(double: bool, n: i32) -> impl Fn(i32) -> i32 { 2 if double { 3 move |x| x * n 4 } else { 5 move |x| x + n 6 } 7 } ``` The real error: ```plaintext 1 error[E0308]: `if` and `else` have incompatible types 2 --> src/main.rs:5:9 3 | 4 2 | / if double { 5 3 | | move |x| x * n 6 | | -------------- 7 | | | 8 | | the expected closure 9 | | expected because of this 10 4 | | } else { 11 5 | | move |x| x + n 12 | | ^^^^^^^^^^^^^^ expected closure, found a different closure 13 6 | | } 14 | |_____- `if` and `else` have incompatible types 15 | 16 = note: expected closure `{closure@src/main.rs:3:9: 3:17}` 17 found closure `{closure@src/main.rs:5:9: 5:17}` 18 = note: no two closures, even if identical, have the same type 19 = help: consider boxing your closure and/or using it as a trait object 20 help: you could change the return type to be a boxed trait object 21 | 22 1 - fn make_op(double: bool, n: i32) -> impl Fn(i32) -> i32 { 23 1 + fn make_op(double: bool, n: i32) -> Box i32> { 24 | ``` **Fix:** box them, exactly as the compiler suggests: ```rust 1 fn make_op(double: bool, n: i32) -> Box i32> { 2 if double { 3 Box::new(move |x| x * n) 4 } else { 5 Box::new(move |x| x + n) 6 } 7 } ``` ### Pitfall 3: Returning a closure that borrows a local (missing `move`) [Section titled “Pitfall 3: Returning a closure that borrows a local (missing move)”](#pitfall-3-returning-a-closure-that-borrows-a-local-missing-move) ```rust 1 fn make_greeter(name: String) -> impl Fn() -> String { 2 || format!("Hello, {name}!") 3 } ``` The closure borrows `name`, but `name` is dropped when `make_greeter` returns. The real error: ```plaintext 1 error[E0373]: closure may outlive the current function, but it borrows `name`, which is owned by the current function 2 --> src/main.rs:2:5 3 | 4 2 | || format!("Hello, {name}!") 5 | ^^ ---- `name` is borrowed here 6 | | 7 | may outlive borrowed value `name` 8 | 9 note: closure is returned here 10 --> src/main.rs:2:5 11 | 12 2 | || format!("Hello, {name}!") 13 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14 help: to force the closure to take ownership of `name` (and any other referenced variables), use the `move` keyword 15 | 16 2 | move || format!("Hello, {name}!") 17 | ++++ ``` **Fix:** add `move` so the closure owns `name`: ```rust 1 fn make_greeter(name: String) -> impl Fn() -> String { 2 move || format!("Hello, {name}!") 3 } ``` ### Pitfall 4: Reaching for `reduce` when you mean `fold` [Section titled “Pitfall 4: Reaching for reduce when you mean fold”](#pitfall-4-reaching-for-reduce-when-you-mean-fold) JavaScript’s `reduce(fn, init)` is Rust’s `fold(init, fn)`. Rust’s `reduce` is the *seedless* variant and returns `Option` (because an empty iterator has no first element to start from): ```rust 1 fn main() { 2 let numbers = vec![1, 2, 3, 4, 5]; 3 4 // fold: has a seed, returns the accumulator type directly 5 let sum: i32 = numbers.iter().fold(0, |acc, &n| acc + n); 6 println!("{}", sum); // 15 7 8 // reduce: no seed, returns Option 9 let max = numbers.iter().copied().reduce(|a, b| if a > b { a } else { b }); 10 println!("{:?}", max); // Some(5) 11 } ``` Mixing up the argument order (`fold(fn, init)`) or forgetting that `reduce` yields an `Option` are the two most common slips. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Prefer `impl Fn` in arguments and returns; box only when forced [Section titled “Prefer impl Fn in arguments and returns; box only when forced”](#prefer-impl-fn-in-arguments-and-returns-box-only-when-forced) `impl Fn` (and the generic `F: Fn` form) is zero-cost. Reach for `Box` only when you genuinely need to return or store closures of *different* concrete types (e.g., from different `match` arms, or in a `Vec` of callbacks). ```rust 1 // Good: zero-cost, single closure shape 2 fn scaler(factor: f64) -> impl Fn(f64) -> f64 { 3 move |x| x * factor 4 } 5 6 // Necessary boxing: heterogeneous callbacks in one collection 7 fn pipeline() -> Vec i32>> { 8 vec![ 9 Box::new(|x| x + 1), 10 Box::new(|x| x * 3), 11 Box::new(|x| x - 2), 12 ] 13 } 14 15 fn main() { 16 let half = scaler(0.5); 17 println!("{}", half(10.0)); // 5 18 19 let result = pipeline().iter().fold(5, |acc, step| step(acc)); 20 println!("{}", result); // ((5+1)*3)-2 = 16 21 } ``` ### Ask for the weakest closure trait that works [Section titled “Ask for the weakest closure trait that works”](#ask-for-the-weakest-closure-trait-that-works) Bound on `Fn` if you only read, `FnMut` if you mutate, `FnOnce` if you consume. A function bounded on `FnOnce` accepts the widest set of closures; a function bounded on `Fn` is the most restrictive but composes most freely (you can call it many times). Pick based on what your function actually does with the closure. ### Use the purpose-built consumers instead of `fold` where they exist [Section titled “Use the purpose-built consumers instead of fold where they exist”](#use-the-purpose-built-consumers-instead-of-fold-where-they-exist) `sum()`, `product()`, `count()`, `max()`, `min()`, `any()`, `all()`, and `find()` express intent more clearly than a hand-rolled `fold` and are just as fast. ```rust 1 fn main() { 2 let prices = vec![19.99, 5.49, 120.0]; 3 let total: f64 = prices.iter().sum(); // clearer than fold 4 let expensive = prices.iter().any(|&p| p > 100.0); // clearer than fold 5 println!("total={total:.2} expensive={expensive}"); 6 } ``` ### Store closures behind a trait object for plugin-style designs [Section titled “Store closures behind a trait object for plugin-style designs”](#store-closures-behind-a-trait-object-for-plugin-style-designs) A struct field typed `Box` lets you hold a callback whose body you do not know at compile time — the Rust equivalent of stashing a TypeScript function on an object. ```rust 1 struct Button { 2 on_click: Box, 3 } 4 5 fn main() { 6 let btn = Button { 7 on_click: Box::new(|| println!("clicked!")), 8 }; 9 (btn.on_click)(); // clicked! 10 } ``` *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small order-processing report, the kind of thing you would write in a backend service. It demonstrates a higher-order function that *returns* a reusable predicate (`min_total`), plus a `filter`/`map`/`fold` pipeline that processes the data in a single pass. ```rust 1 #[derive(Debug)] 2 struct Order { 3 id: u32, 4 customer: String, 5 total: f64, 6 paid: bool, 7 } 8 9 /// Returns a reusable predicate closure. The `impl Fn(&Order) -> bool` 10 /// return type means callers get a zero-cost, directly-callable filter. 11 fn min_total(threshold: f64) -> impl Fn(&Order) -> bool { 12 move |order| order.total >= threshold 13 } 14 15 fn main() { 16 let orders = vec![ 17 Order { id: 1, customer: "Alice".into(), total: 120.0, paid: true }, 18 Order { id: 2, customer: "Bob".into(), total: 35.5, paid: false }, 19 Order { id: 3, customer: "Carol".into(), total: 250.0, paid: true }, 20 Order { id: 4, customer: "Dan".into(), total: 80.0, paid: true }, 21 ]; 22 23 let is_big = min_total(100.0); 24 25 // Keep paid + big orders, format "#id Name", collect into a Vec. 26 let vip: Vec = orders 27 .iter() 28 .filter(|o| o.paid) 29 .filter(|o| is_big(o)) 30 .map(|o| format!("#{} {}", o.id, o.customer)) 31 .collect(); 32 println!("VIP customers: {:?}", vip); 33 34 // Total revenue from paid orders via fold. 35 let revenue: f64 = orders 36 .iter() 37 .filter(|o| o.paid) 38 .fold(0.0, |acc, o| acc + o.total); 39 println!("Paid revenue: {:.2}", revenue); 40 41 // Count unpaid orders. 42 let unpaid = orders.iter().filter(|o| !o.paid).count(); 43 println!("Unpaid orders: {}", unpaid); 44 } ``` **Output:** ```plaintext 1 VIP customers: ["#1 Alice", "#3 Carol"] 2 Paid revenue: 450.00 3 Unpaid orders: 1 ``` The equivalent TypeScript would chain `.filter(...).filter(...).map(...)` (allocating an array per step) and a `.reduce(...)` for revenue. The Rust version reads almost identically but runs each pipeline in one fused, allocation-free pass, and `min_total` hands back a typed, reusable predicate. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Closures and the `Fn` traits](https://doc.rust-lang.org/book/ch13-01-closures.html) * [The Rust Book — Processing a Series of Items with Iterators](https://doc.rust-lang.org/book/ch13-02-iterators.html) * [`std::iter::Iterator` — all adapters and consumers](https://doc.rust-lang.org/std/iter/trait.Iterator.html) * [Rust by Example — Higher Order Functions](https://doc.rust-lang.org/rust-by-example/fn/hof.html) ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Arrow Functions vs Closures](/03-functions/03-arrow-vs-closures/): the `|args|` syntax, `Fn`/`FnMut`/`FnOnce`, and capture-by-ref vs `move` * [Function Pointers](/03-functions/05-function-pointers/): the `fn` type, passing named functions, and how function items differ from closures * [Basic Functions](/03-functions/00-basic-functions/): `fn` signatures and the expression-vs-statement model the closures here rely on * [Return Values](/03-functions/02-return-values/): tail expressions and returning multiple values * [Section 05: Ownership](/05-ownership/): why `iter` vs `into_iter` and `move` matter * [Section 04: Control Flow](/04-control-flow/): loops as an alternative to iterator chains * [Section 02: Variables and Mutability](/02-basics/00-variables/): the `mut` rule behind `FnMut` *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Translate a `map`/`filter`/`reduce` chain [Section titled “Exercise 1: Translate a map/filter/reduce chain”](#exercise-1-translate-a-mapfilterreduce-chain) **Difficulty:** Easy **Objective:** Build muscle memory for the lazy iterator pipeline and `fold`. **Instructions:** Given the TypeScript below, write the equivalent Rust. It should take a slice of word lengths, keep the ones longer than 3, double each, and sum them. ```typescript 1 const lengths = [2, 5, 3, 8, 1, 4]; 2 const result = lengths 3 .filter((n) => n > 3) 4 .map((n) => n * 2) 5 .reduce((acc, n) => acc + n, 0); 6 console.log(result); // (5+8+4)*2 = 34 ``` Solution ```rust 1 fn main() { 2 let lengths = [2, 5, 3, 8, 1, 4]; 3 let result: i32 = lengths 4 .iter() 5 .filter(|&&n| n > 3) 6 .map(|&n| n * 2) 7 .sum(); // sum() is the idiomatic consumer for "+ with 0 seed" 8 println!("{}", result); // 34 9 } ``` You could also write the last step as `.fold(0, |acc, n| acc + n)`, which mirrors the TypeScript `reduce` exactly; `sum()` is the idiomatic shorthand. ### Exercise 2: Write a closure factory [Section titled “Exercise 2: Write a closure factory”](#exercise-2-write-a-closure-factory) **Difficulty:** Medium **Objective:** Practice returning a closure with `impl Fn` and capturing with `move`. **Instructions:** Write a function `make_multiplier(factor: i32)` that returns a closure multiplying its argument by `factor`. Then write `compose(f, g)` that returns a closure applying `f` first, then `g`. Use them so that multiplying by 3 then adding 1 turns `10` into `31`. Solution ```rust 1 fn make_multiplier(factor: i32) -> impl Fn(i32) -> i32 { 2 move |x| x * factor 3 } 4 5 // Generic over the input/intermediate/output types. 6 fn compose(f: impl Fn(A) -> B, g: impl Fn(B) -> C) -> impl Fn(A) -> C { 7 move |x| g(f(x)) 8 } 9 10 fn main() { 11 let times3 = make_multiplier(3); 12 let add1 = |x: i32| x + 1; 13 14 let times3_then_add1 = compose(times3, add1); 15 println!("{}", times3_then_add1(10)); // (10*3)+1 = 31 16 } ``` `move` is required in both factories so the returned closures own the values they captured (`factor`, and the inner `f`/`g`). ### Exercise 3: A boxed-callback pipeline [Section titled “Exercise 3: A boxed-callback pipeline”](#exercise-3-a-boxed-callback-pipeline) **Difficulty:** Hard **Objective:** Use `Box` to store and run a heterogeneous list of transformations, and combine it with `filter_map`. **Instructions:** Write `total_valid(inputs: &[&str]) -> i32` that parses each string to an `i32`, discards the ones that fail to parse (use `filter_map` with `.parse().ok()`), keeps only positive numbers, and sums the rest. Then build a `Vec i32>>` of three steps (`+1`, `*3`, `-2`) and fold the seed `5` through them. Verify the parse step yields `35` for `["10", "-3", "abc", "5", "0", "20"]` and the pipeline yields `16`. Solution ```rust 1 fn total_valid(inputs: &[&str]) -> i32 { 2 inputs 3 .iter() 4 .filter_map(|s| s.parse::().ok()) // keep only the Ok values 5 .filter(|&n| n > 0) 6 .sum() 7 } 8 9 fn main() { 10 let inputs = ["10", "-3", "abc", "5", "0", "20"]; 11 println!("{}", total_valid(&inputs)); // 10 + 5 + 20 = 35 12 13 // A heterogeneous pipeline of boxed closures. 14 let steps: Vec i32>> = vec![ 15 Box::new(|x| x + 1), 16 Box::new(|x| x * 3), 17 Box::new(|x| x - 2), 18 ]; 19 let result = steps.iter().fold(5, |acc, step| step(acc)); 20 println!("{}", result); // ((5+1)*3)-2 = 16 21 } ``` `filter_map` fuses a `map` and a `filter`: the closure returns an `Option`, and `None` values are dropped. `.parse::()` returns a `Result`, and `.ok()` converts it to an `Option`, throwing away the error. Boxing the steps is required because each closure has a distinct anonymous type, yet they must live together in one `Vec`. # Function Pointers > Rust's fn pointer type is TypeScript's (x) => x, but Rust splits named functions, fn pointers, and closures into distinct types, and only non-capturing ones coerce. In JavaScript and TypeScript, functions are just values: you assign them to variables, stash them in objects, and pass them around without a second thought. Rust lets you do the same, but it draws a sharp line between a **function pointer** (the `fn` type) and a **closure**, and it even gives every named function its own unique zero-sized type. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **function pointer** in Rust is a value whose type is written `fn(Args) -> Ret`: a plain pointer to compiled code, exactly like passing a named function in TypeScript. The twist is that each named function actually has its own unique **function item** type (with size 0), which Rust silently coerces to a `fn` pointer when needed. Function pointers are the lightweight cousin of closures: they cannot capture surrounding state, so reach for them when you only need to pass an existing named function around. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // A couple of named functions with the same shape. 2 function double(x: number): number { 3 return x * 2; 4 } 5 6 function increment(x: number): number { 7 return x + 1; 8 } 9 10 // A higher-order function: its parameter `f` is itself a function. 11 // In TypeScript a function type is written `(arg: T) => R`. 12 function applyTwice(f: (x: number) => number, value: number): number { 13 return f(f(value)); 14 } 15 16 console.log(applyTwice(double, 5)); // double(double(5)) = 20 17 console.log(applyTwice(increment, 5)); // increment(increment(5)) = 7 18 19 // Functions are values: store them in arrays, objects, anywhere. 20 const ops: Array<(x: number) => number> = [double, increment]; 21 for (const op of ops) { 22 console.log(op(10)); 23 } ``` In TypeScript every function is a first-class object. There is exactly one notion of “a function value”, and whether it captures variables (a closure) or not makes no difference to its type: `(x: number) => number` describes both. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 fn double(x: i32) -> i32 { 2 x * 2 3 } 4 5 fn increment(x: i32) -> i32 { 6 x + 1 7 } 8 9 // `f: fn(i32) -> i32` is a function POINTER parameter. 10 fn apply_twice(f: fn(i32) -> i32, value: i32) -> i32 { 11 f(f(value)) 12 } 13 14 fn main() { 15 // Bind a named function to a variable of fn-pointer type. 16 let f: fn(i32) -> i32 = double; 17 println!("{}", f(21)); // 42 18 19 println!("{}", apply_twice(double, 5)); // 20 20 println!("{}", apply_twice(increment, 5)); // 7 21 22 // Store function pointers in an array, just like in TypeScript. 23 let ops: [fn(i32) -> i32; 2] = [double, increment]; 24 for op in ops { 25 println!("{}", op(10)); 26 } 27 } ``` Output (real, from `cargo run`): ```text 1 42 2 20 3 7 4 20 5 11 ``` The `fn(i32) -> i32` type is the Rust spelling of TypeScript’s `(x: number) => number`, *for named functions and non-capturing closures only*. The moment a function needs to capture state, you need a closure type instead, which is what the [Arrow Functions and Closures](/03-functions/03-arrow-vs-closures/) topic covers. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Two types hide behind one function [Section titled “Two types hide behind one function”](#two-types-hide-behind-one-function) When you write `fn double(x: i32) -> i32 { .. }`, Rust creates a value `double` whose type is **not** `fn(i32) -> i32`. It is a unique, anonymous **function item type**: the compiler refers to it as `fn(i32) -> i32 {double}`. Every named function gets its own distinct item type, and that type is **zero-sized**: it carries no data at runtime because the identity of the function is known at compile time. A **function pointer** (`fn(i32) -> i32`, with no name in braces) is the runtime-flavored version: an actual pointer to code, the size of one machine word. You rarely write the function-item type yourself. Rust coerces a function item to a function pointer automatically wherever a `fn` type is expected (assigning to an annotated variable, passing to a `fn` parameter, putting items of different functions into the same collection, and so on). ```rust 1 fn double(x: i32) -> i32 { x * 2 } 2 3 fn main() { 4 // The function ITEM `double` is a zero-sized type. 5 println!("size of function item: {}", std::mem::size_of_val(&double)); 6 7 // A function POINTER is a real pointer (8 bytes on a 64-bit target). 8 let p: fn(i32) -> i32 = double; 9 println!("size of fn pointer: {}", std::mem::size_of_val(&p)); 10 } ``` Real output: ```text 1 size of function item: 0 2 size of fn pointer: 8 ``` > **Note:** The zero-sized function item is a performance feature. When you call `double` directly, or pass it to a generic `fn foo(f: F)`, the compiler knows the exact function and can inline the call with no indirection. Coercing to a `fn` pointer erases that identity, so calls go through a real (cheap, but non-inlinable) indirect jump. ### Passing a named function by name [Section titled “Passing a named function by name”](#passing-a-named-function-by-name) To “pass a function” you just use its name as a value, no `&`, no parentheses, no special syntax: ```rust 1 fn square(x: i32) -> i32 { x * x } 2 3 fn main() { 4 let nums = [1, 2, 3]; 5 // `square` (a function item) is accepted because `map` takes anything 6 // implementing `Fn`, and every function item/pointer implements `Fn`. 7 let squared: Vec = nums.iter().copied().map(square).collect(); 8 println!("{squared:?}"); // [1, 4, 9] 9 } ``` This is the direct analogue of `numbers.map(square)` in JavaScript. The difference is purely in the type machinery: `map` is generic over `Fn`, and `square`’s function-item type implements `Fn`, so it fits. ### `fn` pointers versus closures [Section titled “fn pointers versus closures”](#fn-pointers-versus-closures) A closure is a function bundled with the environment it captured. A `fn` pointer has *no* environment. It is just an address. That leads to the single most important rule: > A closure can be coerced to a `fn` pointer **only if it captures nothing**. ```rust 1 fn run(f: fn(i32) -> i32, x: i32) -> i32 { 2 f(x) 3 } 4 5 // Generic over `Fn` — accepts BOTH fn pointers and capturing closures. 6 fn run_any i32>(f: F, x: i32) -> i32 { 7 f(x) 8 } 9 10 fn square(x: i32) -> i32 { x * x } 11 12 fn main() { 13 // A non-capturing closure coerces to a fn pointer. 14 let f: fn(i32) -> i32 = |x| x + 100; 15 println!("{}", run(f, 1)); // 101 16 17 // A capturing closure is NOT a fn pointer, but satisfies `Fn`. 18 let factor = 3; 19 let scale = |x: i32| x * factor; 20 println!("{}", run_any(scale, 10)); // 30 21 22 // Function items satisfy `Fn` too, so they also work with generics/adapters. 23 println!("{:?}", [1, 2, 3].map(square)); // [1, 4, 9] 24 } ``` Real output: ```text 1 101 2 30 3 [1, 4, 9] ``` The takeaway for API design: **accept `impl Fn(...)` (a generic), not `fn(...)`**, unless you specifically need a plain pointer (an FFI boundary, a `static` table, or storing many functions of identical type compactly). A `fn` parameter is the most restrictive choice; `impl Fn` accepts function pointers *and* closures. ### Constructors are functions too [Section titled “Constructors are functions too”](#constructors-are-functions-too) A subtle, delightful Rust feature: tuple-struct constructors and enum-variant constructors are themselves callable function values. You can pass their name anywhere a function is expected. ```rust 1 #[derive(Debug)] 2 struct Meters(f64); 3 4 #[derive(Debug)] 5 enum Token { 6 Word(String), 7 } 8 9 fn main() { 10 // `Meters` is a function value of type `fn(f64) -> Meters`. 11 let readings: Vec = [1.0, 2.5, 3.0].into_iter().map(Meters).collect(); 12 println!("{readings:?}"); 13 14 // `String::from` and `Token::Word` used as function values. 15 let tokens: Vec = ["hi", "there"] 16 .into_iter() 17 .map(String::from) // associated fn as a value 18 .map(Token::Word) // enum variant constructor as a value 19 .collect(); 20 println!("{tokens:?}"); 21 } ``` Real output: ```text 1 [Meters(1.0), Meters(2.5), Meters(3.0)] 2 [Word("hi"), Word("there")] ``` > **Note:** Compiling this exact snippet also emits two benign `dead_code` warnings (`field `0` is never read`), because the tuple fields are only observed through the derived `Debug` impl, which the dead-code analysis intentionally ignores. The program still runs and prints the output above; add `#[allow(dead_code)]` to silence the warnings if you copy this into a probe. There is no TypeScript equivalent: a `class`/tuple type does not give you a free `(x) => new T(x)` function to pass around. In Rust, `Meters` *is* that function. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | TypeScript/JavaScript | Rust | | --------------------------- | ---------------------------------------------- | -------------------------------------------------------------- | | Function type syntax | `(x: number) => number` | `fn(i32) -> i32` | | One type for all functions? | Yes: closures and plain functions share a type | No: function *items*, `fn` pointers, and closures are distinct | | Capturing state | Any function may close over variables | Only closures capture; `fn` pointers never do | | Size of a function value | Heap-allocated object reference | Function item: `0` bytes; `fn` pointer: 1 word | | Passing a named function | `arr.map(double)` | `arr.map(double)` (identical syntax) | | Constructors as values | Not available | Tuple-struct / enum-variant constructors *are* functions | | Storing mixed functions | Trivial (`Function[]`) | Need a common `fn` type, or `Box` for closures | ### The trait hierarchy in one breath [Section titled “The trait hierarchy in one breath”](#the-trait-hierarchy-in-one-breath) Every function pointer and function item implements all three closure traits — `Fn`, `FnMut`, and `FnOnce` — because it has no state to mutate or consume. That is why a `fn` pointer is accepted by any generic bounded on the least restrictive trait it needs: ```rust 1 fn shout(s: &str) -> String { s.to_uppercase() } 2 3 fn call_fn String>(f: F, s: &str) -> String { f(s) } 4 fn call_fnmut String>(mut f: F, s: &str) -> String { f(s) } 5 fn call_fnonce String>(f: F, s: &str) -> String { f(s) } 6 7 fn main() { 8 let p: fn(&str) -> String = shout; 9 println!("{}", call_fn(p, "hi")); // HI 10 println!("{}", call_fnmut(p, "hi")); // HI 11 println!("{}", call_fnonce(p, "hi")); // HI 12 } ``` Real output: ```text 1 HI 2 HI 3 HI ``` > **Tip:** The relationship is one-directional. A `fn` pointer is usable wherever `Fn`/`FnMut`/`FnOnce` is required, but a capturing closure is *not* usable where a `fn` pointer is required. The `Fn` traits are the more general abstraction; `fn` is the concrete, capture-free special case. The full story of `Fn`/`FnMut`/`FnOnce` lives in [Arrow Functions and Closures](/03-functions/03-arrow-vs-closures/). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Expecting a capturing closure to be a `fn` pointer [Section titled “Pitfall 1: Expecting a capturing closure to be a fn pointer”](#pitfall-1-expecting-a-capturing-closure-to-be-a-fn-pointer) Coming from TypeScript, where `(x) => x * factor` is “just a function”, it is natural to write a `fn`-typed parameter and hand it a closure that captures a variable. ```rust 1 fn run(f: fn(i32) -> i32, x: i32) -> i32 { 2 f(x) 3 } 4 5 fn main() { 6 let factor = 3; 7 let scale = |x: i32| x * factor; // captures `factor` 8 println!("{}", run(scale, 10)); // does not compile 9 } ``` The real compiler error: ```text 1 error[E0308]: mismatched types 2 --> src/main.rs:8:24 3 | 4 7 | let scale = |x: i32| x * factor; // captures `factor` 5 | -------- the found closure 6 8 | println!("{}", run(scale, 10)); // does not compile 7 | --- ^^^^^ expected fn pointer, found closure 8 | | 9 | arguments to this function are incorrect 10 | 11 = note: expected fn pointer `fn(i32) -> i32` 12 found closure `{closure@src/main.rs:7:17: 7:25}` 13 note: closures can only be coerced to `fn` types if they do not capture any variables 14 --> src/main.rs:7:30 15 | 16 7 | let scale = |x: i32| x * factor; // captures `factor` 17 | ^^^^^^ `factor` captured here ``` **Fix:** make the parameter generic so it accepts closures too: `fn run i32>(f: F, x: i32) -> i32`. Unlike TypeScript, the *capture* changes the type, and the compiler points exactly at the captured variable. ### Pitfall 2: Storing two different functions and getting a “different fn item” error [Section titled “Pitfall 2: Storing two different functions and getting a “different fn item” error”](#pitfall-2-storing-two-different-functions-and-getting-a-different-fn-item-error) Each named function has its own type, so inferring a binding from one function fixes it to *that* item type. Assigning a second function then fails. ```rust 1 fn double(x: i32) -> i32 { x * 2 } 2 fn triple(x: i32) -> i32 { x * 3 } 3 4 fn main() { 5 let mut op = double; // type inferred as the item type of `double` 6 op = triple; // a different item type 7 println!("{}", op(4)); 8 } ``` The real compiler error: ```text 1 error[E0308]: mismatched types 2 --> src/main.rs:6:10 3 | 4 5 | let mut op = double; // type inferred as the item type of `double` 5 | ------ expected due to this value 6 6 | op = triple; // a different item type 7 | ^^^^^^ expected fn item, found a different fn item 8 | 9 = note: expected fn item `fn(_) -> _ {double}` 10 found fn item `fn(_) -> _ {triple}` 11 = note: different fn items have unique types, even if their signatures are the same 12 = help: consider casting both fn items to fn pointers using `as fn(i32) -> i32` ``` **Fix:** force the function-pointer type, either with an annotation (`let mut op: fn(i32) -> i32 = double;`) or with an `as` cast, exactly as the compiler suggests: ```rust 1 fn double(x: i32) -> i32 { x * 2 } 2 fn triple(x: i32) -> i32 { x * 3 } 3 4 fn main() { 5 // Cast to a fn pointer up front so both branches share one type. 6 let mut op = double as fn(i32) -> i32; 7 println!("{}", op(4)); // 8 8 op = triple; // OK: same fn-pointer type 9 println!("{}", op(4)); // 12 10 } ``` Real output: ```text 1 8 2 12 ``` > **Note:** Array and `vec!` literals are smart enough to coerce a mix of function items to a common `fn` pointer on their own, so `let ops = [double, triple];` compiles fine. The reassignment case above does not get that help because the binding’s type is locked in by the *first* value. ### Pitfall 3: Reaching for `fn` when you mean “any callable” [Section titled “Pitfall 3: Reaching for fn when you mean “any callable””](#pitfall-3-reaching-for-fn-when-you-mean-any-callable) A `fn(T) -> R` parameter quietly rejects every closure that captures anything, which, in practice, is most closures. If your function takes a callback, default to a generic `impl Fn` bound. Use a bare `fn` pointer only when you have a concrete reason (FFI, a `static`/`const` table, or you genuinely want the smaller, non-generic type to avoid monomorphization bloat). ### Pitfall 4: Thinking `&function` is how you pass a function [Section titled “Pitfall 4: Thinking \&function is how you pass a function”](#pitfall-4-thinking-function-is-how-you-pass-a-function) In TypeScript you never take the address of a function — and you do not in Rust either. Writing `apply(&double, 5)` produces `&fn`-of-item confusion. Pass the bare name: `apply(double, 5)`. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Prefer `impl Fn(...)` for callback parameters.** It accepts function pointers *and* closures and stays zero-cost via monomorphization. Reserve `fn(...)` for the special cases below. See [Higher-Order Functions](/03-functions/04-higher-order/) for the full pattern of accepting and returning closures. * **Use `fn` pointers for homogeneous, capture-free tables.** A registry of commands, a parser’s keyword-to-handler map, or a state machine’s transition table are all naturally `HashMap ..>`: small, copyable, and storable in `static`/`const`. * **Add a `type` alias for repeated signatures.** `type Handler = fn(&Request) -> Response;` reads far better than repeating `fn(&Request) -> Response` across a codebase. * **Pass constructors directly.** `iter.map(Meters)` or `iter.map(Some)` is idiomatic and clearer than `iter.map(|x| Meters(x))`. * **Annotate the binding when collecting heterogeneous functions.** `let ops: Vec i32> = vec![double, triple];` sidesteps the “different fn item” trap before it happens. * **Mark FFI callbacks `extern "C" fn`.** When a function pointer crosses into C, its type must carry the C ABI: `extern "C" fn(c_int) -> c_int`. This is covered in [Unsafe and FFI](/20-unsafe-ffi/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A command dispatch table, the kind of thing you would build for a calculator REPL, a chat-bot command router, or a tiny scripting layer. Each command is a plain function with an identical signature, and the registry maps names to function pointers. This is where `fn` pointers genuinely shine: every value is a single word, copyable, and storable in a `HashMap`. ```rust 1 use std::collections::HashMap; 2 3 // Each command is a plain function with the same signature. 4 fn cmd_add(args: &[f64]) -> f64 { 5 args.iter().sum() 6 } 7 8 fn cmd_max(args: &[f64]) -> f64 { 9 args.iter().copied().fold(f64::MIN, f64::max) 10 } 11 12 fn cmd_mean(args: &[f64]) -> f64 { 13 if args.is_empty() { 14 0.0 15 } else { 16 args.iter().sum::() / args.len() as f64 17 } 18 } 19 20 // A readable alias for the shared signature. 21 type Command = fn(&[f64]) -> f64; 22 23 fn build_registry() -> HashMap<&'static str, Command> { 24 let mut registry: HashMap<&'static str, Command> = HashMap::new(); 25 registry.insert("add", cmd_add); 26 registry.insert("max", cmd_max); 27 registry.insert("mean", cmd_mean); 28 registry 29 } 30 31 fn main() { 32 let registry = build_registry(); 33 let data = [10.0, 4.0, 6.0]; 34 35 for name in ["add", "max", "mean", "nope"] { 36 match registry.get(name) { 37 Some(command) => println!("{name} -> {}", command(&data)), 38 None => println!("{name} -> unknown command"), 39 } 40 } 41 } ``` Real output: ```text 1 add -> 20 2 max -> 10 3 mean -> 6.666666666666667 4 nope -> unknown command ``` Compare the TypeScript shape you would write today: ```typescript 1 type Command = (args: number[]) => number; 2 3 const registry: Record = { 4 add: (args) => args.reduce((a, b) => a + b, 0), 5 max: (args) => Math.max(...args), 6 mean: (args) => (args.length ? args.reduce((a, b) => a + b, 0) / args.length : 0), 7 }; 8 9 const data = [10, 4, 6]; 10 for (const name of ["add", "max", "mean", "nope"]) { 11 const cmd = registry[name]; 12 console.log(name, "->", cmd ? cmd(data) : "unknown command"); 13 } ``` The structure is nearly identical. The differences are Rust-flavored: the registry value type is the concrete `fn(&[f64]) -> f64` (not a closure type), the lookup returns an `Option` you must handle, and `cmd_max` passes `f64::max` itself as the folding function, a method path used as a function value, just like passing `Meters` earlier. > **Tip:** If any command needed to capture state — say, a counter or a shared config — you could no longer use `fn`. The registry value would become `Box f64>`. That trade-off (cheap copyable `fn` vs. heap-allocated, capturing `dyn Fn`) is the practical reason to know the difference between the two. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Reference - Function pointer types](https://doc.rust-lang.org/reference/types/function-pointer.html) * [The Rust Reference - Function item types](https://doc.rust-lang.org/reference/types/function-item.html) * [`std::primitive::fn`](https://doc.rust-lang.org/std/primitive.fn.html) * [The Rust Book - Function Pointers](https://doc.rust-lang.org/book/ch13-01-closures.html) (closures chapter; function pointers appear near the end) * [Rust by Example - Higher Order Functions](https://doc.rust-lang.org/rust-by-example/fn/hof.html) ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Basic Functions](/03-functions/00-basic-functions/) — how `fn` definitions and signatures are built in the first place * [Function Parameters](/03-functions/01-parameters/) — passing data into functions; idiomatic alternatives to default/rest params * [Arrow Functions and Closures](/03-functions/03-arrow-vs-closures/) — closures, capture modes, and the `Fn`/`FnMut`/`FnOnce` traits in depth * [Higher-Order Functions](/03-functions/04-higher-order/) — taking `impl Fn` and returning closures * [Recursion](/03-functions/06-recursion/) — recursive functions and their stack considerations * [Section 02: Basic Types](/02-basics/01-types/) — the `i32`, `f64`, and tuple types used throughout these signatures * [Section 04: Control Flow](/04-control-flow/) — `match` and pattern matching, used to select a function above * [Unsafe and FFI](/20-unsafe-ffi/) — `extern "C" fn` pointers across the C boundary *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Operator lookup [Section titled “Exercise 1: Operator lookup”](#exercise-1-operator-lookup) **Difficulty:** Easy **Objective:** Return a function pointer chosen at runtime. **Instructions:** Write `fn operation(symbol: char) -> Option i32>` that returns `Some(..)` containing the matching binary function for `'+'`, `'-'`, and `'*'`, and `None` for anything else. Call it from `main` and apply the returned function to two numbers. Solution ```rust 1 fn add(a: i32, b: i32) -> i32 { a + b } 2 fn sub(a: i32, b: i32) -> i32 { a - b } 3 fn mul(a: i32, b: i32) -> i32 { a * b } 4 5 fn operation(symbol: char) -> Option i32> { 6 match symbol { 7 '+' => Some(add), 8 '-' => Some(sub), 9 '*' => Some(mul), 10 _ => None, 11 } 12 } 13 14 fn main() { 15 if let Some(op) = operation('*') { 16 println!("{}", op(6, 7)); // 42 17 } 18 } ``` Each `match` arm returns a different function *item*, but the declared return type `fn(i32, i32) -> i32` makes Rust coerce all of them to the same `fn` pointer. Output: `42`. ### Exercise 2: Transform with a function pointer [Section titled “Exercise 2: Transform with a function pointer”](#exercise-2-transform-with-a-function-pointer) **Difficulty:** Medium **Objective:** Write a higher-order function whose callback parameter is a `fn` pointer. **Instructions:** Implement `fn transform_all(values: &[i32], f: fn(i32) -> i32) -> Vec` that applies `f` to every element and collects the results. Test it by passing a named `negate` function. Then, in a comment, explain why you could *not* pass `|x| x * some_local` to it. Solution ```rust 1 fn transform_all(values: &[i32], f: fn(i32) -> i32) -> Vec { 2 values.iter().map(|&v| f(v)).collect() 3 } 4 5 fn negate(x: i32) -> i32 { 6 -x 7 } 8 9 fn main() { 10 println!("{:?}", transform_all(&[1, 2, 3], negate)); // [-1, -2, -3] 11 12 // A closure that captures a local, e.g. `|x| x * some_local`, has a closure 13 // type, not `fn(i32) -> i32`, so it would NOT compile here. To accept such 14 // closures, change the bound to a generic: `f: impl Fn(i32) -> i32`. 15 } ``` Output: `[-1, -2, -3]`. ### Exercise 3: A retry runner [Section titled “Exercise 3: A retry runner”](#exercise-3-a-retry-runner) **Difficulty:** Medium/Hard **Objective:** Pass a fallible function as a `fn` pointer and call it repeatedly. **Instructions:** Write `fn retry(f: fn(u32) -> Result, max: u32) -> Result` that calls `f` with attempt numbers `1..=max`, returning the first `Ok`, or the last `Err` if every attempt fails. Test it with a `flaky` function that only succeeds once `attempt >= 3`. Solution ```rust 1 fn flaky(attempt: u32) -> Result { 2 if attempt >= 3 { 3 Ok(attempt) 4 } else { 5 Err(format!("failed on attempt {attempt}")) 6 } 7 } 8 9 fn retry(f: fn(u32) -> Result, max: u32) -> Result { 10 let mut last = Err(String::from("never ran")); 11 for attempt in 1..=max { 12 last = f(attempt); 13 if last.is_ok() { 14 return last; 15 } 16 } 17 last 18 } 19 20 fn main() { 21 println!("{:?}", retry(flaky, 5)); // Ok(3) 22 println!("{:?}", retry(flaky, 2)); // Err("failed on attempt 2") 23 } ``` Output: ```text 1 Ok(3) 2 Err("failed on attempt 2") ``` Because `flaky` neither captures state nor needs to, a `fn` pointer is the perfect parameter type. If `retry` had to accept a closure that captured, say, a shared HTTP client, you would switch the bound to `f: impl FnMut(u32) -> Result`. # Recursion > Recursion looks identical to TypeScript, but Rust guarantees no tail-call optimization, aborts on stack overflow, and needs Box for recursive enums like a cons list. A function that calls itself is **recursion**, and it works the same way in Rust as it does in TypeScript: you split a problem into a smaller version of itself plus a base case. The surprises for a TypeScript/JavaScript developer are not about syntax — they are about *limits*. Rust does **not** guarantee tail-call optimization, so deep recursion overflows the stack just like it does in V8, and Rust’s strict type system forces you to reach for `Box` the moment you write a **recursive data type**. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) **Recursion** is a function defined in terms of itself: a **base case** that stops the recursion and a **recursive case** that calls the function with a smaller input. Rust supports recursion fully, but, like JavaScript engines, it makes **no guarantee** of tail-call optimization, so each call consumes a real stack frame and very deep recursion will abort with a stack overflow. This file shows recursive functions, why deep recursion is risky, how to convert recursion to iteration, and a first look at recursive data types that need `Box`. > **Note:** This file focuses on *recursive functions*, *stack depth*, and *iterative alternatives*, with a teaser of *recursive enums*. The function-definition basics (typed parameters, return types, tail expressions) live in [Basic Functions and Signatures](/03-functions/00-basic-functions/); recursive data structures get full treatment in [Section 10: Smart Pointers](/10-smart-pointers/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // TypeScript - classic recursion: factorial and a recursive list sum. 2 function factorial(n: number): number { 3 if (n <= 1) { 4 return 1; // base case 5 } 6 return n * factorial(n - 1); // recursive case 7 } 8 9 function sumArray(numbers: number[]): number { 10 if (numbers.length === 0) { 11 return 0; // base case 12 } 13 const [first, ...rest] = numbers; // head + tail 14 return first + sumArray(rest); 15 } 16 17 console.log(factorial(5)); // 120 18 console.log(sumArray([3, 1, 4, 1, 5, 9, 2, 6])); // 31 19 20 // Deep recursion blows the JS call stack, too: 21 function sumTo(n: number): number { 22 return n === 0 ? 0 : n + sumTo(n - 1); 23 } 24 // sumTo(1_000_000); // RangeError: Maximum call stack size exceeded ``` **Key points:** * A recursive function needs a **base case** or it loops forever (or until the stack runs out). * JavaScript engines impose a call-stack limit; exceeding it throws `RangeError: Maximum call stack size exceeded`. * The ES2015 spec defined tail-call optimization, but in practice **only Safari/JavaScriptCore ships it** — V8 (Node, Chrome) does not. So you cannot rely on it either. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 // Recursive factorial with a base case. 2 fn factorial(n: u64) -> u64 { 3 if n <= 1 { 4 1 // base case 5 } else { 6 n * factorial(n - 1) // recursive case 7 } 8 } 9 10 // Recursive sum over a slice using "head + recurse on the tail". 11 fn sum_slice(numbers: &[i64]) -> i64 { 12 match numbers { 13 [] => 0, // base case: empty slice 14 [first, rest @ ..] => first + sum_slice(rest), // head + tail 15 } 16 } 17 18 fn main() { 19 println!("5! = {}", factorial(5)); 20 println!("10! = {}", factorial(10)); 21 22 let data = [3, 1, 4, 1, 5, 9, 2, 6]; 23 println!("sum = {}", sum_slice(&data)); 24 } ``` **Output (verified):** ```text 1 5! = 120 2 10! = 3628800 3 sum = 31 ``` **Key points:** * A recursive `fn` in Rust looks just like any other function — it simply calls itself. * The slice pattern `[first, rest @ ..]` binds the first element to `first` and the **remaining slice** to `rest`, the idiomatic Rust analog of JavaScript’s `const [first, ...rest] = numbers`. It does **not** allocate a new array; `rest` is a borrowed view into the same data. * Just like V8, Rust has a finite stack and **no guaranteed tail-call optimization**. The next sections show exactly what that means. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Anatomy of a recursive function [Section titled “Anatomy of a recursive function”](#anatomy-of-a-recursive-function) Every correct recursion has two parts: 1. A **base case** that returns without recursing. In `factorial`, that is `n <= 1 => 1`. 2. A **recursive case** that calls the function on a *smaller* input so the recursion makes progress toward the base case. In `factorial`, that is `n * factorial(n - 1)`. If you forget the base case, or the recursive case never shrinks the input, the function recurses forever, which in Rust means it runs until the stack is exhausted (covered below), not an infinite hang. ### Slice patterns replace `[first, ...rest]` [Section titled “Slice patterns replace \[first, ...rest\]”](#slice-patterns-replace-first-rest) In TypeScript, `const [first, ...rest] = numbers` copies the tail into a brand-new array on every call, so a recursive `sumArray` is quietly O(n²) in allocations. Rust’s `[first, rest @ ..]` pattern binds `rest` to a **sub-slice** (a pointer + length) that borrows the original data with **zero copying**. The recursion is still linear in stack depth, but it allocates nothing. > **Note:** Slice patterns and `match` are part of Rust’s pattern-matching system, covered in depth in [Section 04: Control Flow](/04-control-flow/). Here we use them only to express “head and tail.” ### The call stack is finite — and Rust does not hide it [Section titled “The call stack is finite — and Rust does not hide it”](#the-call-stack-is-finite--and-rust-does-not-hide-it) Each function call pushes a **stack frame** holding its parameters and locals. When the function returns, the frame is popped. Recursion stacks up one frame per pending call, and the call stack has a fixed size — the main thread defaults to about **8 MiB** on most platforms. Pure tail-recursive functions *could* in principle reuse a single frame, but **Rust makes no guarantee that it will do so**, so you must assume every recursive call costs a frame. ```rust 1 // Deeply recursive sum 1..=n. Each call adds a frame to the call stack. 2 // There is no guaranteed tail-call optimization, so this overflows the 3 // stack for large n. 4 fn sum_to(n: u64) -> u64 { 5 if n == 0 { 6 0 7 } else { 8 n + sum_to(n - 1) 9 } 10 } 11 12 fn main() { 13 // A few hundred thousand frames is enough to blow the default 8 MiB stack. 14 println!("{}", sum_to(1_000_000)); 15 } ``` This compiles cleanly, but running it aborts the process. **Real output (verified):** ```text 1 thread 'main' has overflowed its stack 2 fatal runtime error: stack overflow, aborting ``` The process exits with a failure (code 134 / `SIGABRT` on this machine). This is the direct counterpart to V8’s `RangeError: Maximum call stack size exceeded` — the difference is that JavaScript throws a *catchable error*, whereas a Rust stack overflow **aborts the whole process** and cannot be caught. That makes uncontrolled recursion depth more dangerous in Rust than in Node, and it is why production Rust code prefers iteration for anything that scales with input size. ### ”Tail position” does not save you (no guaranteed TCO) [Section titled “”Tail position” does not save you (no guaranteed TCO)”](#tail-position-does-not-save-you-no-guaranteed-tco) A call is in **tail position** if it is the very last thing the function does — its result is returned directly without any further work. The factorial above is *not* tail-recursive (it still has to multiply by `n` after the call returns), but an accumulator-passing version is: ```rust 1 // Accumulator style: still recursive, but the recursive call is in 2 // "tail position". Rust does NOT guarantee this is optimized away, 3 // so it can still overflow - shown here only to contrast the shape. 4 fn sum_to_acc(n: u64, acc: u64) -> u64 { 5 if n == 0 { 6 acc 7 } else { 8 sum_to_acc(n - 1, acc + n) // tail call: nothing happens after it returns 9 } 10 } 11 12 fn main() { 13 println!("sum_to_acc(100, 0) = {}", sum_to_acc(100, 0)); 14 } ``` **Output (verified):** ```text 1 sum_to_acc(100, 0) = 5050 ``` In a language with **guaranteed** tail-call optimization (such as Scheme, or Safari’s JavaScript engine for proper tail calls), the compiler would rewrite this into a loop and it would handle any depth. Rust gives **no such guarantee**. The optimizer (LLVM) *may* turn a tail call into a jump at higher optimization levels, but this is an implementation detail you must never depend on. There is no `become` keyword in stable Rust to *require* it. Treat tail-position recursion exactly like any other recursion: bounded by stack size. ### Mutual recursion works too [Section titled “Mutual recursion works too”](#mutual-recursion-works-too) Two functions can call each other. Because Rust resolves module items regardless of order (no hoisting needed — see [Basic Functions and Signatures](/03-functions/00-basic-functions/)), neither has to be declared “first.” ```rust 1 // Mutual recursion: two functions that call each other. 2 fn is_even(n: u64) -> bool { 3 if n == 0 { 4 true 5 } else { 6 is_odd(n - 1) 7 } 8 } 9 10 fn is_odd(n: u64) -> bool { 11 if n == 0 { 12 false 13 } else { 14 is_even(n - 1) 15 } 16 } 17 18 fn main() { 19 println!("is_even(10) = {}", is_even(10)); 20 println!("is_odd(7) = {}", is_odd(7)); 21 } ``` **Output (verified):** ```text 1 is_even(10) = true 2 is_odd(7) = true ``` The same stack-depth caveat applies: mutual recursion consumes one frame per call, alternating between the two functions. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript (Node/V8) | Rust | | ------------------------- | ------------------------------------------------------- | -------------------------------------------------------------- | | Recursion syntax | Function calls itself | Identical: function calls itself | | Head/tail destructuring | `const [first, ...rest]` (copies the tail) | `[first, rest @ ..]` slice pattern (borrows, no copy) | | Stack-overflow behavior | Throws `RangeError` (catchable with `try/catch`) | **Aborts the process**; not catchable on the main thread | | Tail-call optimization | Spec’d in ES2015, but V8/Node does **not** implement it | **No guarantee**; no `become` keyword in stable Rust | | Recursive data types | Just nest objects (`{ value, next }`) | Need indirection (`Box`, `Rc`) or the type has “infinite size” | | Default main-thread stack | \~984 KiB in Node (V8), tunable via `--stack-size` | \~8 MiB on most platforms; spawned threads are configurable | | Idiomatic preference | Recursion or iteration, both common | Iteration strongly preferred for input-scaled depth | ### Why iteration is the default in Rust [Section titled “Why iteration is the default in Rust”](#why-iteration-is-the-default-in-rust) In JavaScript you often reach for recursion because it reads nicely and the engine’s limit feels far away. In Rust, iterators (`for`, `while`, and the `Iterator` methods like `.fold()`, `.sum()`) are **zero-cost abstractions** that compile down to tight loops with no per-element stack growth. So the idiomatic Rust instinct is: *use an iterator unless the data itself is recursive (a tree) and shallow.* This is the same code, rewritten iteratively: ```rust 1 // Iterative factorial: a loop instead of recursion - constant stack usage. 2 fn factorial_iter(n: u64) -> u64 { 3 let mut result = 1u64; 4 for i in 2..=n { 5 result *= i; 6 } 7 result 8 } 9 10 // Iterative sum 1..=n - no stack growth, handles huge n with one line. 11 fn sum_to_iter(n: u64) -> u64 { 12 (1..=n).sum() 13 } 14 15 fn main() { 16 println!("10! = {}", factorial_iter(10)); 17 println!("sum 1..=1_000_000 = {}", sum_to_iter(1_000_000)); 18 } ``` **Output (verified):** ```text 1 10! = 3628800 2 sum 1..=1_000_000 = 500000500000 ``` Note that `sum_to_iter(1_000_000)` runs fine, while the recursive `sum_to(1_000_000)` aborted with a stack overflow. Same result, radically different runtime safety. (Iterators and their combinators are covered in [Higher-Order Functions](/03-functions/04-higher-order/) and [Section 07: Collections](/07-collections/).) *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: A recursive `enum` without indirection won’t compile [Section titled “Pitfall 1: A recursive enum without indirection won’t compile”](#pitfall-1-a-recursive-enum-without-indirection-wont-compile) This is unique to Rust and surprises every TypeScript developer. In TypeScript, a linked-list node is just `{ value: number; next: Node | null }`; objects are heap references, so the size is always “one pointer.” In Rust, a value’s size must be known at compile time, and a type that *contains itself by value* would be infinitely large. ```rust 1 // A recursive enum WITHOUT a Box - this does NOT compile. 2 enum List { 3 Cons(i32, List), 4 Nil, 5 } 6 7 fn main() { 8 let _ = List::Nil; 9 } ``` **Real compiler error:** ```text 1 error[E0072]: recursive type `List` has infinite size 2 --> src/main.rs:2:1 3 | 4 2 | enum List { 5 | ^^^^^^^^^ 6 3 | Cons(i32, List), 7 | ---- recursive without indirection 8 | 9 help: insert some indirection (e.g., a `Box`, `Rc`, or `&`) to break the cycle 10 | 11 3 | Cons(i32, Box), 12 | ++++ + ``` The compiler tells you exactly how to fix it: wrap the recursive field in a `Box` (a heap pointer of known size). See the [recursive enum teaser](#a-recursive-enum-teaser-box) below. ### Pitfall 2: A missing or unreachable base case → stack overflow at runtime [Section titled “Pitfall 2: A missing or unreachable base case → stack overflow at runtime”](#pitfall-2-a-missing-or-unreachable-base-case--stack-overflow-at-runtime) This compiles fine — the bug only shows up when you run it. ```rust 1 // BUG: the recursive call never shrinks toward a base case. 2 fn count_down_forever(n: u32) { 3 println!("{n}"); 4 count_down_forever(n - 1); // u32 wraps below 0 in release, panics in debug 5 } ``` In **debug builds** the `n - 1` panics with `attempt to subtract with overflow` once `n` hits `0`. In **release builds** the subtraction wraps `0` to `u32::MAX` and the recursion runs effectively forever until it aborts with `thread 'main' has overflowed its stack`. Either way, the fix is a real base case: `if n == 0 { return; }`. > **Warning:** A Rust stack overflow **aborts the process** and cannot be recovered with error handling. Unlike a Node `RangeError` you can `catch`, there is no safety net — design recursion so its depth is bounded by something small (like tree height), not by raw input size. ### Pitfall 3: Assuming tail recursion is free [Section titled “Pitfall 3: Assuming tail recursion is free”](#pitfall-3-assuming-tail-recursion-is-free) Coming from a functional background (or Safari’s engine), you might write a tail-recursive loop expecting it to run in constant stack space. Rust does not promise this: ```rust 1 // Looks tail-recursive, but Rust gives NO guarantee it becomes a loop. 2 fn sum_to_acc(n: u64, acc: u64) -> u64 { 3 if n == 0 { acc } else { sum_to_acc(n - 1, acc + n) } 4 } 5 // sum_to_acc(10_000_000, 0) may still overflow the stack. ``` There is no stable `become` keyword to force a tail call. If you need guaranteed constant stack usage, **write a loop** — do not rely on the optimizer. ### Pitfall 4: Exponential recursion (the naive Fibonacci trap) [Section titled “Pitfall 4: Exponential recursion (the naive Fibonacci trap)”](#pitfall-4-exponential-recursion-the-naive-fibonacci-trap) This is not Rust-specific, but it bites hard because Rust is fast enough that you might not notice the algorithmic blowup until the input grows: ```rust 1 // O(2^n): recomputes the same values exponentially many times. 2 fn fib_rec(n: u32) -> u64 { 3 match n { 4 0 => 0, 5 1 => 1, 6 _ => fib_rec(n - 1) + fib_rec(n - 2), 7 } 8 } ``` `fib_rec(50)` recomputes lower Fibonacci numbers billions of times. The recursion *depth* is fine (only \~50 frames), but the *number of calls* explodes. The fix is the same as in TypeScript: memoize, or rewrite iteratively (see [Best Practices](#best-practices) and Exercise 3). *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Prefer iteration when depth scales with input [Section titled “1. Prefer iteration when depth scales with input”](#1-prefer-iteration-when-depth-scales-with-input) If your recursion depth grows with the size of a list, a number, or any unbounded input, write a loop or use an iterator. Reserve recursion for cases where the **data structure itself** is recursive and **shallow** (a parse tree, a small directory tree, JSON). ```rust 1 // Iterative: O(1) stack, handles any n. 2 fn fib_iter(n: u32) -> u64 { 3 let (mut a, mut b) = (0u64, 1u64); 4 for _ in 0..n { 5 let next = a + b; 6 a = b; 7 b = next; 8 } 9 a 10 } ``` ### 2. Recurse on bounded structures, iterate over sequences [Section titled “2. Recurse on bounded structures, iterate over sequences”](#2-recurse-on-bounded-structures-iterate-over-sequences) Walking a binary tree recursively is idiomatic and safe — the depth is the tree’s height (often `log n`). Summing a million-element list recursively is not — its depth is the list length. Match the technique to the shape of the data. ### 3. Reach for `Box` (or `Rc`) for recursive types [Section titled “3. Reach for Box (or Rc) for recursive types”](#3-reach-for-box-or-rc-for-recursive-types) A self-referential `enum` or `struct` needs heap indirection so its size is finite. `Box` is the simplest choice; `Rc` when you need shared ownership. This is introduced below and detailed in [Section 10: Smart Pointers](/10-smart-pointers/). ### 4. Bound recursion explicitly when accepting untrusted input [Section titled “4. Bound recursion explicitly when accepting untrusted input”](#4-bound-recursion-explicitly-when-accepting-untrusted-input) If recursion depth can be influenced by external input (parsing user-supplied JSON, deserializing nested data), add an explicit `depth` parameter and return an error past a limit, rather than risking an unrecoverable stack overflow. This is a security-relevant pattern; see [Section 27: Security](/27-security/). ### 5. Memoize or tabulate exponential recursions [Section titled “5. Memoize or tabulate exponential recursions”](#5-memoize-or-tabulate-exponential-recursions) For overlapping-subproblem recursions like Fibonacci, cache results in a `HashMap` (memoization) or build a table bottom-up (tabulation / iteration). The iterative `fib_iter` above is tabulation taken to its limit. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) Recursion shines on genuinely recursive data. Here is a directory-tree size calculator, the kind of traversal a build tool, bundler, or `du`-style utility performs. The tree is a recursive `enum` (a directory owns its children), and both the traversal functions are naturally recursive. Importantly, the recursion depth equals the **tree’s depth**, which is small and bounded, so this is exactly where recursion belongs. ```rust 1 // Real-world example: compute the total size of a directory tree. 2 // The tree is a recursive data structure (a node owns its children), 3 // and the traversal is naturally recursive. 4 5 /// A node in a filesystem tree. 6 enum Node { 7 /// A file with a size in bytes. 8 File { name: String, size: u64 }, 9 /// A directory containing child nodes. 10 Dir { name: String, children: Vec }, 11 } 12 13 /// Recursively sums the byte size of a node and everything under it. 14 fn total_size(node: &Node) -> u64 { 15 match node { 16 Node::File { size, .. } => *size, 17 Node::Dir { children, .. } => children.iter().map(total_size).sum(), 18 } 19 } 20 21 /// Recursively prints the tree with indentation showing depth. 22 fn print_tree(node: &Node, depth: usize) { 23 let indent = " ".repeat(depth); 24 match node { 25 Node::File { name, size } => println!("{indent}{name} ({size} bytes)"), 26 Node::Dir { name, children } => { 27 println!("{indent}{name}/"); 28 for child in children { 29 print_tree(child, depth + 1); 30 } 31 } 32 } 33 } 34 35 fn main() { 36 let tree = Node::Dir { 37 name: "src".to_string(), 38 children: vec![ 39 Node::File { name: "main.rs".to_string(), size: 1200 }, 40 Node::Dir { 41 name: "utils".to_string(), 42 children: vec![ 43 Node::File { name: "parse.rs".to_string(), size: 3400 }, 44 Node::File { name: "format.rs".to_string(), size: 900 }, 45 ], 46 }, 47 ], 48 }; 49 50 print_tree(&tree, 0); 51 println!("total size: {} bytes", total_size(&tree)); 52 } ``` **Output (verified):** ```text 1 src/ 2 main.rs (1200 bytes) 3 utils/ 4 parse.rs (3400 bytes) 5 format.rs (900 bytes) 6 total size: 5500 bytes ``` **What to notice:** * `Node` is a recursive type, but `children: Vec` already provides the heap indirection (`Vec` stores its elements behind a pointer), so no explicit `Box` is needed here. (You only need `Box` when a variant contains the type *directly*, as in the `Cons` list below.) * `total_size` recurses on each child; `children.iter().map(total_size).sum()` is the idiomatic combination of iteration *over siblings* and recursion *into depth*. * `print_tree` passes a `depth` parameter, a common pattern for tracking how deep you are, useful both for formatting and for enforcing a depth limit on untrusted input. * Because the depth is the directory nesting level (typically a handful), there is no stack-overflow risk. This is the right shape for recursion. ### A recursive `enum` teaser (`Box`) [Section titled “A recursive enum teaser (Box)”](#a-recursive-enum-teaser-box) When a type contains *itself directly* (a classic cons list) you need explicit indirection. `Box` is a heap pointer with a fixed size (one machine word), which breaks the “infinite size” cycle from [Pitfall 1](#pitfall-1-a-recursive-enum-without-indirection-wont-compile). ```rust 1 // A recursive enum: a cons-style linked list. 2 // `Box` gives the variant a known, finite size (a pointer). 3 #[derive(Debug)] 4 enum List { 5 Cons(i32, Box), 6 Nil, 7 } 8 9 use List::{Cons, Nil}; 10 11 fn sum_list(list: &List) -> i32 { 12 match list { 13 Cons(value, rest) => value + sum_list(rest), 14 Nil => 0, 15 } 16 } 17 18 fn main() { 19 // 1 -> 2 -> 3 -> Nil 20 let list = Cons(1, Box::new(Cons(2, Box::new(Cons(3, Box::new(Nil)))))); 21 println!("list = {list:?}"); 22 println!("sum = {}", sum_list(&list)); 23 } ``` **Output (verified):** ```text 1 list = Cons(1, Cons(2, Cons(3, Nil))) 2 sum = 6 ``` This is only a teaser. `Box`, `Rc`, and recursive data structures get full coverage in [Section 10: Smart Pointers](/10-smart-pointers/). The takeaway for now: **recursive *functions* need a base case; recursive *types* need indirection.** *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book – Recursive Types with Box](https://doc.rust-lang.org/book/ch15-01-box.html#enabling-recursive-types-with-boxes) * [The Rust Book – Defining an Enum](https://doc.rust-lang.org/book/ch06-01-defining-an-enum.html) * [Rust by Example – Functions](https://doc.rust-lang.org/rust-by-example/fn.html) * [Rust Reference – Recursive type errors (E0072)](https://doc.rust-lang.org/error_codes/E0072.html) * [Rust Reference – Slice patterns](https://doc.rust-lang.org/reference/patterns.html#slice-patterns) ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Basic Functions](/03-functions/00-basic-functions/) — function signatures, tail expressions, and why items need no hoisting. * [Parameters](/03-functions/01-parameters/) — accumulator-style parameters and slices `&[T]` as inputs. * [Return Values](/03-functions/02-return-values/): early `return` for base cases, and returning the unit type. * [Higher-Order Functions](/03-functions/04-higher-order/) — iterator combinators (`map`, `fold`, `sum`) that often replace recursion. * [Function Pointers](/03-functions/05-function-pointers/) — passing a function (such as a recursive one) by name. * [Section 04: Control Flow](/04-control-flow/) — `match`, slice patterns, and `loop`/`while` for the iterative alternatives. * [Section 07: Collections](/07-collections/): `Vec`, `HashMap` (for memoization), and iterators over sequences. * [Section 10: Smart Pointers](/10-smart-pointers/) — `Box`, `Rc`, and recursive data structures in full. * [Section 27: Security](/27-security/): bounding recursion depth on untrusted input. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Recursive countdown [Section titled “Exercise 1: Recursive countdown”](#exercise-1-recursive-countdown) **Difficulty:** Easy **Objective:** Write a recursive function with a clear base case that performs a side effect. **Instructions:** 1. Write `fn countdown(n: u32)` that prints each number from `n` down to `1`, then prints `"liftoff!"`. 2. The base case is `n == 0` (print `"liftoff!"` and stop). 3. The recursive case prints `n` and calls `countdown(n - 1)`. 4. Call `countdown(3)` from `main`. Solution ```rust 1 fn countdown(n: u32) { 2 if n == 0 { 3 println!("liftoff!"); // base case 4 } else { 5 println!("{n}"); 6 countdown(n - 1); // recursive case 7 } 8 } 9 10 fn main() { 11 countdown(3); 12 } ``` **Verified output:** ```text 1 3 2 2 3 1 4 liftoff! ``` This is safe because the depth (`n`) is tiny. If `n` could be in the millions, you would write a `for` loop instead to avoid a stack overflow. ### Exercise 2: Greatest common divisor (Euclid’s algorithm) [Section titled “Exercise 2: Greatest common divisor (Euclid’s algorithm)”](#exercise-2-greatest-common-divisor-euclids-algorithm) **Difficulty:** Medium **Objective:** Implement a naturally recursive numeric algorithm and return a value via a tail expression. **Instructions:** 1. Write `fn gcd(a: u64, b: u64) -> u64`. 2. The base case: when `b == 0`, return `a`. 3. The recursive case: return `gcd(b, a % b)`. 4. Test it with `gcd(48, 18)` (should be `6`). > **Tip:** This recursion is shallow (its depth grows only logarithmically) so recursion is perfectly safe here. Note that the recursive call is in tail position, but remember Rust does not *guarantee* that helps with stack usage; it simply does not matter at this depth. Solution ```rust 1 fn gcd(a: u64, b: u64) -> u64 { 2 if b == 0 { 3 a // base case 4 } else { 5 gcd(b, a % b) // recursive case 6 } 7 } 8 9 fn main() { 10 println!("gcd(48, 18) = {}", gcd(48, 18)); 11 } ``` **Verified output:** ```text 1 gcd(48, 18) = 6 ``` ### Exercise 3: Fibonacci, recursive vs. iterative [Section titled “Exercise 3: Fibonacci, recursive vs. iterative”](#exercise-3-fibonacci-recursive-vs-iterative) **Difficulty:** Medium **Objective:** Feel the difference between an exponential recursion and an efficient loop, and understand why Rust developers reach for iteration. **Instructions:** 1. Write `fn fib_rec(n: u32) -> u64` using the naive recursive definition (`fib(0) = 0`, `fib(1) = 1`, otherwise `fib(n-1) + fib(n-2)`). 2. Write `fn fib_iter(n: u32) -> u64` that computes the same value with a single loop and two accumulators — O(n) time, O(1) stack. 3. Print `fib_rec(10)`, `fib_iter(10)` (both `55`), and `fib_iter(90)`. 4. Reflect: why would calling `fib_rec(90)` be a terrible idea even though `fib_iter(90)` is instant? (The recursive version makes an exponential number of calls.) Solution ```rust 1 // O(2^n): recomputes the same subproblems exponentially many times. 2 fn fib_rec(n: u32) -> u64 { 3 match n { 4 0 => 0, 5 1 => 1, 6 _ => fib_rec(n - 1) + fib_rec(n - 2), 7 } 8 } 9 10 // O(n) time, O(1) stack: tabulate with two rolling accumulators. 11 fn fib_iter(n: u32) -> u64 { 12 let (mut a, mut b) = (0u64, 1u64); 13 for _ in 0..n { 14 let next = a + b; 15 a = b; 16 b = next; 17 } 18 a 19 } 20 21 fn main() { 22 println!("fib_rec(10) = {}", fib_rec(10)); 23 println!("fib_iter(10) = {}", fib_iter(10)); 24 println!("fib_iter(90) = {}", fib_iter(90)); 25 } ``` **Verified output:** ```text 1 fib_rec(10) = 55 2 fib_iter(10) = 55 3 fib_iter(90) = 2880067194370816120 ``` `fib_rec`’s recursion *depth* is only about `n`, so it will not overflow the stack at `n = 90`, but its *number of calls* roughly doubles with each step, so `fib_rec(90)` would take longer than the age of the universe. The iterative version computes it instantly. This is the classic illustration of why, in Rust, iteration (or memoization) is the default for anything with overlapping subproblems. *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * A recursive function needs a **base case** and a **recursive case** that shrinks toward it — identical in concept to TypeScript. * Rust has a finite call stack and makes **no guarantee of tail-call optimization**; deep recursion **aborts the process** with a stack overflow that you cannot catch. * Slice patterns (`[first, rest @ ..]`) express “head and tail” by **borrowing**, not copying like JavaScript’s `[first, ...rest]`. * The idiomatic Rust default is **iteration** (loops and iterators) whenever recursion depth scales with input; reserve recursion for shallow, naturally recursive data like trees. * Recursive *data types* (a cons list) need heap indirection (`Box`) or the compiler rejects them with `error[E0072]: recursive type has infinite size`. # Rust Control Flow > Rust control flow is expression-based: if, match, and loop each return a value, replacing the ternary and switch. Plus no truthiness and exhaustive matching. You already write conditionals, loops, and `switch` statements every day in TypeScript and JavaScript. Rust gives you the same building blocks — `if`/`else`, `for`/`while`/`loop`, and the `match` expression — but with one defining shift. Rust control flow is **expression-based**, not statement-based. An `if`, a `match`, and even a `loop` each *evaluate to a value*, so they replace the ternary, the discriminated-union `switch`, and the “declare a `let` outside the loop and mutate it” pattern all at once. Two more rules ripple through everything: conditions must be a real `bool` (there is no truthiness), and `match` is exhaustive (the compiler refuses to let you forget a case). *** ## What You’ll Learn [Section titled “What You’ll Learn”](#what-youll-learn) * Treat `if`/`else` and `match` as **expressions** that produce values, replacing the ternary `? :` and `switch` * Write conditions as explicit `bool` tests. Rust has **no truthiness**, so `if count`, `if name`, and `if 0` are all compile errors * Iterate over **ranges** (`0..n`, `1..=n`) and collections instead of a C-style `for` counter, which Rust does not have * Use the dedicated infinite `loop` and return a value from it with `break value` * Replace `switch` with `match`: exhaustiveness, the `_` catch-all, guards, `|` alternatives, ranges, `@` bindings, and destructuring, with no fall-through * Reach for the lightweight `if let`, `while let`, and `let ... else` when only one case matters * Control nested loops with **labeled loops** (`'outer:`) and understand how they differ from JavaScript labels *** ## Topics [Section titled “Topics”](#topics) | # | Topic | What it covers | | - | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | 1 | [Conditionals](/04-control-flow/00-conditionals/) | `if`/`else`; the ternary becomes `if` as an **expression**; no truthiness (conditions are `bool` only); an `if let` teaser | | 2 | [Loops](/04-control-flow/01-loops/) | `for` over ranges/iterators, `while`, the infinite `loop`; `loop` returning a value via `break`; why there is **no C-style `for`** | | 3 | [`match`](/04-control-flow/02-match/) | `switch` becomes `match`: exhaustiveness, the `_` arm, guards, `\|` patterns, ranges, the `@` binding, and destructuring | | 4 | [`if let` / `while let`](/04-control-flow/03-if-let-while-let/) | Concise pattern matching: `if let` / `else`, `while let`, and `let ... else` for early-return guard clauses | | 5 | [`break` and `continue`](/04-control-flow/04-break-continue/) | `break`/`continue`; `break` carrying a value out of a `loop`; `continue` in `for` and `while` | | 6 | [Labeled Loops](/04-control-flow/05-labeled-loops/) | Labeled loops (`'outer:`); `break`/`continue` to a label; nested-loop control versus JavaScript labels | *** ## Learning Objectives [Section titled “Learning Objectives”](#learning-objectives) After completing this section, a TypeScript/JavaScript developer should be able to: 1. Bind the result of an `if`/`else` or `match` directly to a `let`, and explain why both arms must unify to a single type. 2. Rewrite any truthiness-based condition (`if (x)`, `while (queue.length)`) as an explicit `bool` test (`if x != 0`, `while !queue.is_empty()`). 3. Translate a C-style `for (let i = 0; i < n; i++)` into a range loop, and use `.enumerate()` when an index is genuinely needed. 4. Produce a value from a loop with `loop { ... break value; }` instead of a pre-declared mutable variable. 5. Replace a `switch` with an exhaustive `match`, using `|`, ranges, guards, `@`, and destructuring, and know why `match` never falls through. 6. Choose the lightest pattern-matching tool: `if let`, `while let`, `let ... else`, or a full `match`. 7. Use `break 'label` / `continue 'label` to control nested loops, and recognize when an iterator method is clearer. *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) This section assumes you have completed: * **[Section 03: Functions](/03-functions/)**: the `fn` signature, typed parameters, and especially the **tail expression** (a block’s last line, with no semicolon, becomes its value). That expression-as-value rule is exactly what makes `if`, `match`, and `loop` usable as values here. If the expression-oriented model (`let x = { ...; a + b };`) or the statement-vs-expression distinction feels unfamiliar, revisit [Section 02 — Variables and Mutability](/02-basics/00-variables/) before starting. > **Note:** A few topics here *preview* concepts covered fully later. `Option` and the `?` operator are introduced in [Section 08 — Error Handling](/08-error-handling/); the borrow-checker rules behind “you can’t mutate a collection while iterating it” belong to [Section 05 — Ownership](/05-ownership/); and the full iterator toolbox (`map`/`filter`/`find`/`take_while`) lives in [Section 07 — Collections](/07-collections/). You do not need those sections first; the links are there for when you want to go deeper. > **Tip:** The apostrophe in a loop label (`'outer:`) is the same sigil Rust uses for **lifetimes** in [Section 05 — Ownership](/05-ownership/04-lifetimes/). They are unrelated concepts that share punctuation; the compiler always knows which one you mean from context. *** ## Estimated Time [Section titled “Estimated Time”](#estimated-time) * **Reading:** 2.5-3.5 hours * **Hands-on Practice & Exercises:** 2.5-3.5 hours * **Total:** 5-7 hours A reasonable order is the list order above: conditionals → loops → `match` → `if let`/`while let` → `break`/`continue` → labeled loops. `match` (topic 3) is the conceptual heart of the section — it underpins `if let`, `while let`, and `let ... else` — so do not skip it. *** ## Frequently asked questions [Section titled “Frequently asked questions”](#frequently-asked-questions) ### Does Rust have a ternary operator? [Section titled “Does Rust have a ternary operator?”](#does-rust-have-a-ternary-operator) No, because `if` is itself an expression: `let max = if a > b { a } else { b };`. Both branches must produce the same type. This replaces `cond ? a : b` and removes the need for a separate ternary. See [Conditionals](/04-control-flow/00-conditionals/). ### How is `match` different from `switch`? [Section titled “How is match different from switch?”](#how-is-match-different-from-switch) `match` is exhaustive (the compiler rejects unhandled cases), has no fall-through, returns a value, and can destructure and bind variables. A forgotten case is a compile error, not a silent bug. See [Match](/04-control-flow/02-match/). ### How do I write a C-style `for (i = 0; …)` loop? [Section titled “How do I write a C-style for (i = 0; …) loop?”](#how-do-i-write-a-c-style-for-i--0--loop) You iterate a range instead: `for i in 0..n`. To count down use `(0..n).rev()`, and to get the index while iterating use `.enumerate()`. Rust has no three-clause `for`. See [Loops](/04-control-flow/01-loops/). # Conditionals: `if` / `else` > Rust has no ternary because if is an expression: let x = if cond { a } else { b }. Conditions must be a real bool, since Rust, unlike JavaScript, has no truthiness. In TypeScript, `if` is a **statement** and the ternary `? :` is the only conditional that produces a value. In Rust, there is no ternary at all, because `if` itself is an **expression** that produces a value. This single shift, plus the fact that Rust conditions must be a real `bool` (no “truthiness”), is most of what you need to know. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) Rust’s `if`/`else` looks almost identical to TypeScript’s, but two things are different in ways that matter every day: * **`if` is an expression.** It evaluates to a value, so `let x = if cond { a } else { b };` replaces the ternary `cond ? a : b`. No separate `?:` operator exists. * **Conditions must be `bool`.** There is no truthiness. `if 0`, `if ""`, `if someObject` — all of those are *compile errors* in Rust. You write the comparison explicitly. If you internalize “the condition is always a `bool`, and the whole `if` can be a value,” you already understand 90% of Rust conditionals. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // A small shipping-cost calculator, the way you'd write it in TS. 2 function shippingCost(weightKg: number, isMember: boolean): number { 3 let cost: number; 4 5 // if/else statement: assigns into a pre-declared `let`. 6 if (weightKg > 20) { 7 cost = 25; 8 } else if (weightKg > 5) { 9 cost = 12; 10 } else { 11 cost = 5; 12 } 13 14 // Ternary expression: the ONLY conditional in JS that yields a value. 15 const discount = isMember ? cost * 0.1 : 0; 16 17 return cost - discount; 18 } 19 20 // Truthiness: JS coerces non-booleans in a condition. 21 function describe(name?: string) { 22 if (name) { 23 // "" , undefined, null, 0, NaN are all falsy 24 console.log(`Hello, ${name}`); 25 } else { 26 console.log("Hello, stranger"); 27 } 28 } 29 30 console.log(shippingCost(3, true)); // 4.5 31 console.log(shippingCost(8, false)); // 12 32 describe("Ada"); // Hello, Ada 33 describe(""); // Hello, stranger (empty string is falsy) ``` Two TypeScript habits to notice: the `let cost` declared-then-assigned pattern, and `if (name)` relying on the empty string being **falsy**. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 // The same calculator, written idiomatically in Rust. 2 fn shipping_cost(weight_kg: f64, is_member: bool) -> f64 { 3 // `if` is an EXPRESSION: it evaluates to a value we bind with `let`. 4 // This replaces the declared-then-assigned `let cost` pattern. 5 let cost = if weight_kg > 20.0 { 6 25.0 7 } else if weight_kg > 5.0 { 8 12.0 9 } else { 10 5.0 11 }; 12 13 // This `if`-expression is Rust's ternary. There is no `? :` operator. 14 let discount = if is_member { cost * 0.1 } else { 0.0 }; 15 16 cost - discount 17 } 18 19 // No truthiness: the condition must be an explicit `bool`. 20 fn describe(name: &str) { 21 if !name.is_empty() { 22 println!("Hello, {name}"); 23 } else { 24 println!("Hello, stranger"); 25 } 26 } 27 28 fn main() { 29 println!("{}", shipping_cost(3.0, true)); // 4.5 30 println!("{}", shipping_cost(8.0, false)); // 12 31 describe("Ada"); // Hello, Ada 32 describe(""); // Hello, stranger 33 } ``` Real output from `cargo run`: ```text 1 4.5 2 12 3 Hello, Ada 4 Hello, stranger ``` > **Note:** The `cost` binding is computed once by the whole `if`-expression. There is no mutable, uninitialized variable waiting to be filled in. This is more than a style preference: the compiler *knows* `cost` is always initialized to exactly one value, which is why it never needs `let mut`. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `if` is an expression, not a statement [Section titled “if is an expression, not a statement”](#if-is-an-expression-not-a-statement) In TypeScript, an `if` block does not evaluate to anything; you reach a value either by mutating an outer variable or by using the ternary. In Rust, the `if`/`else` construct *is* a value: ```rust 1 fn main() { 2 let score = 72; 3 4 // The whole `if`/`else` evaluates to one of the two branch values. 5 let grade = if score >= 60 { "pass" } else { "fail" }; 6 7 println!("grade = {grade}"); // grade = pass 8 } ``` The key mechanic: a block `{ ... }` in Rust evaluates to its **last expression** when that expression has **no trailing semicolon**. So `{ "pass" }` is a block whose value is `"pass"`. Each arm of the `if` is such a block, and the `if` takes the value of whichever arm runs. This is the same block-as-value rule you saw with function bodies in [Section 03 — Functions](/03-functions/02-return-values/), now applied to control flow. (Expressions vs. statements were introduced back in [Section 02 — Variables](/02-basics/00-variables/).) A block arm can contain multiple lines; only the final unterminated expression is the value: ```rust 1 fn main() { 2 let n = 7; 3 4 let label = if n % 2 == 0 { 5 let kind = "even"; // intermediate statement (note the semicolon) 6 format!("{n} is {kind}") // final expression -> the block's value 7 } else { 8 format!("{n} is odd") 9 }; 10 11 println!("{label}"); // 7 is odd 12 } ``` ### Why there is no ternary operator [Section titled “Why there is no ternary operator”](#why-there-is-no-ternary-operator) Because `if` is already an expression, a separate `? :` would be redundant. The Rust form is slightly longer than `cond ? a : b`, but it reads the same and, importantly, it is the *exact same construct* whether you use one branch or ten. You never switch syntaxes between “I want a value” and “I want side effects.” ```rust 1 fn main() { 2 let is_member = true; 3 let cost = 100.0; 4 5 // TS: const discount = isMember ? cost * 0.1 : 0; 6 let discount = if is_member { cost * 0.1 } else { 0.0 }; 7 8 println!("{discount}"); // 10 9 } ``` ### Both arms must have the same type [Section titled “Both arms must have the same type”](#both-arms-must-have-the-same-type) Since an `if`-expression produces a single value, every branch that can be reached must produce the **same type**. The compiler unifies the arm types; if they disagree, it is a compile error (see Common Pitfalls). TypeScript’s ternary, by contrast, happily produces a *union* type like `string | number`. ### No truthiness — the condition is always `bool` [Section titled “No truthiness — the condition is always bool”](#no-truthiness--the-condition-is-always-bool) In JavaScript, `if (x)` runs `Boolean(x)` for you: `0`, `""`, `null`, `undefined`, `NaN` are falsy; everything else is truthy. Rust does **none** of this. The condition between `if` and `{` must already be of type `bool`. You make the comparison explicit: ```rust 1 fn main() { 2 let count = 3; 3 let name = "Bob"; 4 5 // JS: if (count) -> Rust: compare to get a bool 6 if count != 0 { 7 println!("count is non-zero"); 8 } 9 10 // JS: if (name) -> Rust: ask the value a yes/no question 11 if !name.is_empty() { 12 println!("name has {} chars", name.len()); 13 } 14 } ``` Output: ```text 1 count is non-zero 2 name has 3 chars ``` This is verbose at first, but it removes an entire class of bugs (the infamous `if (count)` that silently skips when `count` is legitimately `0`). ### `if let` — a teaser for pattern matching [Section titled “if let — a teaser for pattern matching”](#if-let--a-teaser-for-pattern-matching) Rust has a second flavor of `if` that pattern-matches and binds in one step. You will reach for it constantly with `Option` (Rust’s `null`-free alternative; see [Section 02 — Types](/02-basics/01-types/)): ```rust 1 fn main() { 2 let maybe_user: Option<&str> = Some("ada"); 3 4 // "If this Option is a `Some`, bind its inner value to `user`." 5 if let Some(user) = maybe_user { 6 println!("logged in as {user}"); 7 } else { 8 println!("anonymous"); 9 } 10 } ``` Output: ```text 1 logged in as ada ``` Think of `if let` as the conditional cousin of TypeScript’s `if (user !== undefined)` narrowing, except it also **unwraps** the value for you in the same line. This is just a preview; the full treatment (including `while let` and `let ... else`) lives in [if let / while let](/04-control-flow/03-if-let-while-let/), and the general pattern-matching tool is [match](/04-control-flow/02-match/). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | TypeScript / JavaScript | Rust | | ------------------------------- | -------------------------------------------------- | --------------------------------------------- | | Is `if` a value? | No. `if` is a statement; only `? :` yields a value | Yes. `if` is an expression | | Ternary operator | `cond ? a : b` | None; use `if cond { a } else { b }` | | Condition type | Any value (coerced via truthiness) | Must be exactly `bool` | | `if (0)` / `if ("")` | Runs the else branch (falsy) | Compile error: `expected bool` | | Branch result types | May differ — produces a union (`string \| number`) | Must unify to one type | | `if` without `else` as a value | Ternary requires both sides | `()` only — can’t bind to a typed `let` | | Parentheses around condition | Required: `if (x > 0)` | Omitted: `if x > 0` (braces required) | | Chained comparison `0 < x < 10` | Allowed (and usually a bug) | Compile error — must write `0 < x && x < 10` | ### Why Rust makes these choices [Section titled “Why Rust makes these choices”](#why-rust-makes-these-choices) * **Expression-orientation** means fewer mutable, half-initialized variables. The value and the decision that produces it live in one place. * **No truthiness** means the compiler can guarantee a condition is a genuine boolean question, never an accidental coercion. The cost, a slightly longer `x != 0`, is paid once at write time and saves you at debug time. * **Type unification across arms** is what makes `if` usable as an expression at all: a value has to have *one* type. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Using a number or string as a condition (expecting truthiness) [Section titled “Pitfall 1: Using a number or string as a condition (expecting truthiness)”](#pitfall-1-using-a-number-or-string-as-a-condition-expecting-truthiness) ```rust 1 fn main() { 2 let count = 3; 3 if count { 4 // does not compile (error[E0308]: mismatched types) 5 println!("non-zero"); 6 } 7 } ``` Real compiler output: ```text 1 error[E0308]: mismatched types 2 --> src/main.rs:3:8 3 | 4 3 | if count { 5 | ^^^^^ expected `bool`, found integer ``` The same happens with strings: `if name { ... }` reports `expected bool, found &str`. **Fix:** write the comparison you actually mean: `if count != 0` or `if !name.is_empty()`. ### Pitfall 2: `if` and `else` arms with different types [Section titled “Pitfall 2: if and else arms with different types”](#pitfall-2-if-and-else-arms-with-different-types) ```rust 1 fn main() { 2 let score = 72; 3 // does not compile (error[E0308]: `if` and `else` have incompatible types) 4 let result = if score >= 60 { "pass" } else { 0 }; 5 println!("{result:?}"); 6 } ``` Real compiler output: ```text 1 error[E0308]: `if` and `else` have incompatible types 2 --> src/main.rs:3:51 3 | 4 3 | let result = if score >= 60 { "pass" } else { 0 }; 5 | ------ ^ expected `&str`, found integer 6 | | 7 | expected because of this ``` Unlike a TypeScript ternary (which would infer `string | number`), Rust needs a single type. **Fix:** make both arms the same type, or model the two cases with an `enum` and `match` (see [match](/04-control-flow/02-match/)). ### Pitfall 3: Using a bare `if` (no `else`) as an expression [Section titled “Pitfall 3: Using a bare if (no else) as an expression”](#pitfall-3-using-a-bare-if-no-else-as-an-expression) ```rust 1 fn main() { 2 let score = 72; 3 // does not compile (error[E0317]: `if` may be missing an `else` clause) 4 let grade = if score >= 60 { "pass" }; 5 println!("{grade:?}"); 6 } ``` Real compiler output: ```text 1 error[E0317]: `if` may be missing an `else` clause 2 --> src/main.rs:3:17 3 | 4 3 | let grade = if score >= 60 { "pass" }; 5 | ^^^^^^^^^^^^^^^^^------^^ 6 | | | 7 | | found here 8 | expected `&str`, found `()` 9 | 10 = note: `if` expressions without `else` evaluate to `()` 11 = help: consider adding an `else` block that evaluates to the expected type ``` An `if` with no `else` evaluates to the unit type `()` (Rust’s “nothing” — comparable to `void`). You can only bind such an `if` to nothing, not to a `&str`. **Fix:** add an `else` arm that returns the same type, or restructure (often a `match` or a default value). ### Pitfall 4: Trying to chain comparisons like in math [Section titled “Pitfall 4: Trying to chain comparisons like in math”](#pitfall-4-trying-to-chain-comparisons-like-in-math) ```rust 1 fn main() { 2 let x = 5; 3 // does not compile (error: comparison operators cannot be chained) 4 let ok = 0 < x < 10; 5 println!("{ok}"); 6 } ``` Real compiler output: ```text 1 error: comparison operators cannot be chained 2 --> src/main.rs:3:16 3 | 4 3 | let ok = 0 < x < 10; 5 | ^ ^ 6 | 7 help: split the comparison into two 8 | 9 3 | let ok = 0 < x && x < 10; 10 | ++++ ``` JavaScript *allows* `0 < x < 10`, but it means `(0 < x) < 10` → `true < 10` → `1 < 10` → `true`, which is almost never what you want. Rust rejects it outright. **Fix:** `0 < x && x < 10`, or the more readable `(0..10).contains(&x)` for ranges. (See [Operators](/02-basics/02-operators/) for the logical operators.) ### Pitfall 5: Putting a semicolon after a branch value [Section titled “Pitfall 5: Putting a semicolon after a branch value”](#pitfall-5-putting-a-semicolon-after-a-branch-value) ```rust 1 fn main() { 2 let n = 4; 3 // Adding `;` turns the branch into a statement that yields `()`, 4 // so both arms become `()` and `kind` is `()` — not what you wanted. 5 let _kind = if n % 2 == 0 { 6 "even"; // ← stray semicolon discards the value 7 } else { 8 "odd"; 9 }; 10 // _kind is now (), not "even" 11 } ``` This *compiles* (both arms are `()`), so it is a silent logic bug rather than a hard error. **Fix:** drop the semicolons inside the arms so each block’s final expression becomes its value. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Prefer `let x = if ... { } else { };` over a mutable, assigned-later variable.** It keeps the binding immutable and proves to the reader (and compiler) that exactly one value is chosen. * **Make conditions read as questions.** `if !name.is_empty()`, `if count > 0`, `if user.is_some()`. Method calls like `.is_empty()`, `.is_some()`, `.contains(&x)` are idiomatic and clearer than re-deriving truthiness. * **Reach for `match` once you have three-plus mutually exclusive branches** on the same value — it gives you exhaustiveness checking that `else if` chains don’t. See [match](/04-control-flow/02-match/). * **Use `if let` instead of an `if` + manual unwrap** when you only care about one variant of an `Option`/`Result`. It’s shorter and avoids panics. See [if let / while let](/04-control-flow/03-if-let-while-let/). * **Keep arm types identical and small.** If arms want to return different shapes, that’s a signal to introduce an `enum`. * **Don’t wrap conditions in parentheses.** `if (x > 0)` compiles but `clippy` will nudge you toward `if x > 0`; the braces already delimit the body. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A retry policy for an HTTP client: classify a response by status code and decide whether to succeed, retry with backoff, or give up. Every decision is driven by `if`/`else` expressions, and every condition is an explicit `bool`. ```rust 1 #[derive(Debug)] 2 enum RetryDecision { 3 Succeed, 4 RetryAfter(u64), // milliseconds to wait before retrying 5 Fail, 6 } 7 8 fn classify(status: u16, attempt: u32) -> RetryDecision { 9 // No truthiness: each condition is a concrete boolean test. 10 // `(200..300).contains(&status)` reads better than `status >= 200 && status < 300`. 11 if (200..300).contains(&status) { 12 RetryDecision::Succeed 13 } else if status == 429 || (500..600).contains(&status) { 14 // `if` as an expression computes exponential backoff inline, 15 // capping it after a few attempts. 16 let backoff = if attempt < 5 { 100 * 2u64.pow(attempt) } else { 3200 }; 17 RetryDecision::RetryAfter(backoff) 18 } else { 19 RetryDecision::Fail 20 } 21 } 22 23 fn main() { 24 let responses = [(200, 0), (404, 0), (503, 2), (429, 6)]; 25 26 for (status, attempt) in responses { 27 match classify(status, attempt) { 28 RetryDecision::Succeed => println!("status {status}: ok"), 29 RetryDecision::RetryAfter(ms) => println!("status {status}: retry in {ms} ms"), 30 RetryDecision::Fail => println!("status {status}: giving up"), 31 } 32 } 33 } ``` Real output from `cargo run`: ```text 1 status 200: ok 2 status 404: giving up 3 status 503: retry in 400 ms 4 status 429: retry in 3200 ms ``` Notice how the inner `let backoff = if ... { ... } else { ... };` and the outer `if`/`else if`/`else` are the same construct used at two scales, and how `(200..300).contains(&status)` replaces a truthiness-laden range check. The `match` at the end is a preview of the next tool in your control-flow toolbox. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book – Control Flow (`if` expressions)](https://doc.rust-lang.org/book/ch03-05-control-flow.html#if-expressions) * [The Rust Book – `if let` Concise Control Flow](https://doc.rust-lang.org/book/ch06-03-if-let.html) * [Rust Reference – `if` and `if let` expressions](https://doc.rust-lang.org/reference/expressions/if-expr.html) * [Rust by Example – `if`/`else`](https://doc.rust-lang.org/rust-by-example/flow_control/if_else.html) ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Loops](/04-control-flow/01-loops/) — `for`, `while`, and the value-returning `loop`; why there is no C-style `for`. * [`match`](/04-control-flow/02-match/) — the exhaustive, pattern-matching successor to `switch` and long `else if` chains. * [`if let` / `while let`](/04-control-flow/03-if-let-while-let/) — the full story behind the `if let` teaser above, plus `let ... else`. * [Variables and Mutability](/02-basics/00-variables/) — expressions vs. statements, and why immutable bindings pair so well with `if`-expressions. * [Operators](/02-basics/02-operators/) — the comparison and logical operators that build your conditions. * [Section 05 — Ownership](/05-ownership/) — how values flow out of `if` branches once types get more complex than `&str`. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Ternary to `if`-expression [Section titled “Exercise 1: Ternary to if-expression”](#exercise-1-ternary-to-if-expression) **Difficulty:** Easy **Objective:** Translate a TypeScript ternary into an idiomatic Rust `if`-expression. **Instructions:** The TypeScript below returns `"adult"` or `"minor"`. Implement the Rust `category` function so it returns the same `&str`, binding the result of a single `if`-expression. Do not use a mutable variable. ```typescript 1 // TypeScript original 2 function category(age: number): string { 3 return age >= 18 ? "adult" : "minor"; 4 } ``` ```rust 1 fn category(age: u32) -> &'static str { 2 // TODO: return "adult" if age >= 18, otherwise "minor" 3 /* ??? */ 4 } 5 6 fn main() { 7 println!("{}", category(20)); // adult 8 println!("{}", category(12)); // minor 9 } ``` Solution ```rust 1 fn category(age: u32) -> &'static str { 2 if age >= 18 { "adult" } else { "minor" } 3 } 4 5 fn main() { 6 println!("{}", category(20)); // adult 7 println!("{}", category(12)); // minor 8 } ``` The whole `if`/`else` is the function’s tail expression, so it becomes the return value: no `return` keyword and no mutable variable needed. Output: ```text 1 adult 2 minor ``` ### Exercise 2: Kill the truthiness [Section titled “Exercise 2: Kill the truthiness”](#exercise-2-kill-the-truthiness) **Difficulty:** Medium **Objective:** Convert truthiness-based JavaScript conditions into explicit Rust `bool` tests, using nested `if`-expressions for a tiered result. **Instructions:** Port this JS pricing function to Rust. A `"premium"` role pays no base fee; everyone else pays `5`. On top of that, add a surcharge of `20` for more than 100 monthly orders, `10` for more than 10, and `0` otherwise. Return the total as a `u32`. ```javascript 1 // JavaScript original (relies on string comparison, not truthiness here, 2 // but watch the branching) 3 function feeFor(role, monthlyOrders) { 4 const base = role === "premium" ? 0 : 5; 5 let surcharge; 6 if (monthlyOrders > 100) surcharge = 20; 7 else if (monthlyOrders > 10) surcharge = 10; 8 else surcharge = 0; 9 return base + surcharge; 10 } ``` ```rust 1 fn fee_for(role: &str, monthly_orders: u32) -> u32 { 2 // TODO: compute base and surcharge with if-expressions, then sum them 3 /* ??? */ 4 } 5 6 fn main() { 7 println!("{}", fee_for("premium", 150)); // 20 8 println!("{}", fee_for("free", 50)); // 15 9 println!("{}", fee_for("free", 3)); // 5 10 } ``` Solution ```rust 1 fn fee_for(role: &str, monthly_orders: u32) -> u32 { 2 let base = if role == "premium" { 0 } else { 5 }; 3 let surcharge = if monthly_orders > 100 { 4 20 5 } else if monthly_orders > 10 { 6 10 7 } else { 8 0 9 }; 10 base + surcharge 11 } 12 13 fn main() { 14 println!("{}", fee_for("premium", 150)); // 20 15 println!("{}", fee_for("free", 50)); // 15 16 println!("{}", fee_for("free", 3)); // 5 17 } ``` Both `base` and `surcharge` are immutable bindings produced by `if`-expressions; no `let mut surcharge;` declared-then-assigned dance. Output: ```text 1 20 2 15 3 5 ``` ### Exercise 3: `if let` instead of a default value [Section titled “Exercise 3: if let instead of a default value”](#exercise-3-if-let-instead-of-a-default-value) **Difficulty:** Medium **Objective:** Use the `if let` teaser to greet a user by name when one is present, falling back to a guest greeting otherwise. **Instructions:** Implement `greet` so that, given `Some(name)`, it returns `"Welcome back, {name}!"`, and given `None`, it returns `"Welcome, guest!"`. Use `if let ... else`, and make the whole thing an expression that produces the returned `String`. ```rust 1 fn greet(config: Option<&str>) -> String { 2 // TODO: if there's a name, welcome them back by name; otherwise greet a guest 3 /* ??? */ 4 } 5 6 fn main() { 7 println!("{}", greet(Some("Ada"))); 8 println!("{}", greet(None)); 9 } ``` Solution ```rust 1 fn greet(config: Option<&str>) -> String { 2 if let Some(name) = config { 3 format!("Welcome back, {name}!") 4 } else { 5 "Welcome, guest!".to_string() 6 } 7 } 8 9 fn main() { 10 println!("{}", greet(Some("Ada"))); 11 println!("{}", greet(None)); 12 } ``` `if let Some(name) = config` both *tests* that `config` is a `Some` and *binds* its inner value to `name` in one step: the conditional cousin of TypeScript’s `if (config !== undefined)` narrowing, but it unwraps for you. Both arms produce a `String`, so the `if let`/`else` is itself the returned expression. Output: ```text 1 Welcome back, Ada! 2 Welcome, guest! ``` For the deeper dive on `if let`, `while let`, and `let ... else`, head to [if let / while let](/04-control-flow/03-if-let-while-let/). # Loops > Rust drops the C-style for entirely: you iterate ranges and collections, not counters. for, while, and loop cover it, and loop can return a value via break value. Rust gives you three loop keywords (`for`, `while`, and `loop`), but the way you actually iterate is different from JavaScript. You loop over **ranges** and **iterators** instead of incrementing a counter by hand, and `loop` is a real expression that can hand a value back. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In TypeScript/JavaScript you reach for `for (let i = 0; i < n; i++)` constantly. Rust has **no C-style `for`** at all. Instead you iterate over a **range** (`0..n`) or directly over the elements of a collection, which eliminates an entire class of off-by-one and out-of-bounds bugs. Rust also has `while` (same as you know it) and a dedicated infinite `loop` keyword that — uniquely — can produce a value with `break value`. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // The four loop shapes a TS/JS dev reaches for every day. 2 const scores = [88, 92, 75]; 3 4 // 1. Classic C-style index loop 5 for (let i = 0; i < scores.length; i++) { 6 console.log(`index ${i}: ${scores[i]}`); 7 } 8 9 // 2. for...of over the values 10 for (const score of scores) { 11 console.log(`score ${score}`); 12 } 13 14 // 3. while with a manual counter 15 let countdown = 3; 16 while (countdown > 0) { 17 console.log(`T-minus ${countdown}`); 18 countdown--; 19 } 20 21 // 4. "Infinite" loop with break (often hides a return value in a mutable var) 22 let n = 1; 23 let firstBig: number; 24 while (true) { 25 n *= 2; 26 if (n > 100) { 27 firstBig = n; 28 break; 29 } 30 } 31 console.log(`first power of two over 100: ${firstBig}`); ``` **Key characteristic:** the index loop is the default, and “loop until I find something” usually means mutating an outer variable and `break`-ing. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 fn main() { 2 let scores = [88, 92, 75]; 3 4 // 1. There is NO C-style for. To iterate by index, loop over a range: 5 for i in 0..scores.len() { 6 println!("index {i}: {}", scores[i]); 7 } 8 9 // 2. for over the values (the idiomatic default) 10 for score in &scores { 11 println!("score {score}"); 12 } 13 14 // 3. while with a manual counter — identical idea to JavaScript 15 let mut countdown = 3; 16 while countdown > 0 { 17 println!("T-minus {countdown}"); 18 countdown -= 1; 19 } 20 21 // 4. `loop` is an expression: `break value` hands a value back out. 22 let mut n = 1; 23 let first_big = loop { 24 n *= 2; 25 if n > 100 { 26 break n; // <-- the loop *evaluates* to this value 27 } 28 }; 29 println!("first power of two over 100: {first_big}"); 30 } ``` ```text 1 index 0: 88 2 index 1: 92 3 index 2: 75 4 score 88 5 score 92 6 score 75 7 T-minus 3 8 T-minus 2 9 T-minus 1 10 first power of two over 100: 128 ``` **Key characteristic:** iterate over ranges/collections, not hand-rolled counters; and `loop` can be the right-hand side of a `let`. > **Note:** `0..scores.len()` is shown here only to make the comparison concrete. In real Rust you almost never index like this; prefer `for score in &scores`. See [Common Pitfalls](#common-pitfalls). *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `for` iterates over an iterator, never a counter [Section titled “for iterates over an iterator, never a counter”](#for-iterates-over-an-iterator-never-a-counter) In Rust, `for pattern in expression { ... }` requires `expression` to be something that can turn into an **iterator** (anything implementing `IntoIterator`). Each pass binds the next item to `pattern`. There is no init/condition/increment triple, because there is no counter; the iterator decides when it is exhausted. The most common iterables: ```rust 1 fn main() { 2 // A range: 1, 2, 3 (the end is EXCLUSIVE) 3 for i in 1..4 { 4 println!("range {i}"); 5 } 6 7 // An inclusive range with ..= : 1, 2, 3 8 for i in 1..=3 { 9 println!("inclusive {i}"); 10 } 11 12 // An array/slice/Vec, borrowed with & 13 let names = ["Alice", "Bob", "Carol"]; 14 for name in &names { 15 println!("name {name}"); 16 } 17 } ``` ```text 1 range 1 2 range 2 3 range 3 4 inclusive 1 5 inclusive 2 6 inclusive 3 7 name Alice 8 name Bob 9 name Carol ``` A **range** like `1..4` is the closest thing to `for (let i = 1; i < 4; i++)`. Note the boundary: `start..end` **excludes** `end` (like `Array.prototype.slice`), while `start..=end` **includes** it. JavaScript has no range literal at all; the nearest equivalents are `Array.from({length: n}, (_, i) => i)` or a manual counter. ### `.enumerate()` when you genuinely need the index [Section titled “.enumerate() when you genuinely need the index”](#enumerate-when-you-genuinely-need-the-index) If you want both the index and the value — the legitimate reason a TS/JS dev uses the C-style loop — call `.enumerate()` on the iterator. It yields `(index, value)` tuples, which you destructure right in the `for` pattern: ```rust 1 fn main() { 2 let names = ["Alice", "Bob", "Carol"]; 3 for (index, name) in names.iter().enumerate() { 4 println!("{index}: {name}"); 5 } 6 } ``` ```text 1 0: Alice 2 1: Bob 3 2: Carol ``` This is the Rust equivalent of JavaScript’s `array.forEach((value, index) => ...)` or `for (const [index, value] of array.entries())`. ### Iterator adapters give you ranges JavaScript can’t express in a header [Section titled “Iterator adapters give you ranges JavaScript can’t express in a header”](#iterator-adapters-give-you-ranges-javascript-cant-express-in-a-header) Because the thing after `in` is just an iterator, you compose adapters instead of editing a loop header: ```rust 1 fn main() { 2 // Count down: rev() reverses any iterator that supports it 3 for i in (0..3).rev() { 4 println!("rev {i}"); 5 } 6 7 // Step by 3: 0, 3, 6, 9 — like `for (i = 0; i < 10; i += 3)` 8 for i in (0..10).step_by(3) { 9 println!("step {i}"); 10 } 11 } ``` ```text 1 rev 2 2 rev 1 3 rev 0 4 step 0 5 step 3 6 step 6 7 step 9 ``` > **Tip:** `rev()` and `step_by()` replace the `i--` and `i += 3` you would write in a C-style loop header. The whole iterator toolbox (`filter`, `map`, `take`, `zip`, …) is covered in [Section 07 — Collections](/07-collections/). ### `while` is exactly what you expect [Section titled “while is exactly what you expect”](#while-is-exactly-what-you-expect) `while condition { ... }` runs the body while the condition is `true`. The only catch (covered in [conditionals](/04-control-flow/00-conditionals/)) is that the condition must be a real `bool`. There is no truthiness, so `while queue.length` does not compile; you write `while !queue.is_empty()`. ```rust 1 fn main() { 2 let mut count = 3; 3 while count > 0 { 4 println!("while {count}"); 5 count -= 1; 6 } 7 } ``` ```text 1 while 3 2 while 2 3 while 1 ``` ### `loop` is an infinite loop — and an expression [Section titled “loop is an infinite loop — and an expression”](#loop-is-an-infinite-loop--and-an-expression) `loop { ... }` repeats forever until you `break`. That alone is just `while (true)`. What is genuinely new for a JavaScript developer is that `loop` is an **expression**: `break value` makes the entire `loop` evaluate to `value`, so you can assign it to a binding. ```rust 1 fn main() { 2 let mut n = 1; 3 let result = loop { 4 n *= 2; 5 if n > 100 { 6 break n; // the loop produces 128 7 } 8 }; 9 println!("result {result}"); // result 128 10 } ``` ```text 1 result 128 ``` In JavaScript you simulate this by declaring a `let result;` outside the loop and assigning to it before `break`. In Rust the value flows *out of* the loop, so there is no uninitialized outer variable to forget about. (`while` and `for` cannot do this; they always evaluate to `()`, because they may run zero times, leaving no value to produce.) > **Note:** This is the same expression-orientation you saw with [`if`](/04-control-flow/00-conditionals/): in Rust, control-flow constructs are values in their own right, going beyond plain statements. Returning a value from `loop` via `break` and from named blocks is detailed in [break & continue](/04-control-flow/04-break-continue/). *** ## Key Differences from TypeScript [Section titled “Key Differences from TypeScript”](#key-differences-from-typescript) | Aspect | TypeScript/JavaScript | Rust | | --------------------------------- | -------------------------------- | --------------------------------------------------- | | C-style `for (init; cond; step)` | Yes, the default | **Does not exist** | | Iterate values | `for...of` | `for x in &collection` | | Iterate with index | `for (let i...)` or `.entries()` | `for (i, x) in coll.iter().enumerate()` | | Numeric range | `Array.from(...)` / manual | `start..end` (exclusive), `start..=end` (inclusive) | | Condition type | any value (truthy/falsy) | must be `bool` | | Infinite loop | `while (true)` | `loop { ... }` | | Loop produces a value | No (mutate an outer `let`) | `loop` can: `let x = loop { break v; };` | | Mutate collection while iterating | Allowed (often buggy) | Rejected by the borrow checker at compile time | | `for...in` over object keys | Yes | No equivalent; iterate a `HashMap` instead | ### Why no C-style `for`? [Section titled “Why no C-style for?”](#why-no-c-style-for) The C-style header is three independent pieces — initialization, a re-checked condition, and a mutation — that the programmer must keep in sync. Almost every classic loop bug (off-by-one, `<` vs `<=`, forgetting to increment, indexing past the end) lives in that header. Rust deletes the whole category by making you say *what you are iterating over* (a range or a collection) rather than *how to advance a counter*. The compiler then guarantees the index can never go out of bounds. ### Why does `loop` exist when `while true` would do? [Section titled “Why does loop exist when while true would do?”](#why-does-loop-exist-when-while-true-would-do) `loop` signals intent (“this runs until an explicit `break`”) and, importantly, the compiler treats it specially for **type inference and reachability**. Because `loop` has no condition, code after it is reachable only via `break`, so a `loop` with no `break` has type `!` (“never”), and a `loop { break v; }` can produce a value. `while true` does not get this treatment; it always has type `()`. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Writing a C-style `for` [Section titled “Pitfall 1: Writing a C-style for”](#pitfall-1-writing-a-c-style-for) A TS/JS dev’s fingers will type this automatically: ```rust 1 fn main() { 2 for (let mut i = 0; i < 5; i += 1) { // does not compile 3 println!("{i}"); 4 } 5 } ``` The real compiler error is a parse failure. Rust tries to read `(let mut i = 0; ...)` as a **pattern** to bind, not a loop header: ```text 1 error: expected pattern, found `let` 2 --> src/main.rs:2:10 3 | 4 2 | for (let mut i = 0; i < 5; i += 1) { 5 | ^^^ 6 | 7 help: remove the unnecessary `let` keyword ``` **Fix:** loop over a range. ```rust 1 fn main() { 2 for i in 0..5 { 3 println!("{i}"); 4 } 5 } ``` ### Pitfall 2: Reaching for `0..len` and indexing [Section titled “Pitfall 2: Reaching for 0..len and indexing”](#pitfall-2-reaching-for-0len-and-indexing) This compiles, but it is not idiomatic and reintroduces bounds checks and off-by-one risk: ```rust 1 fn main() { 2 let scores = [88, 92, 75]; 3 // Works, but un-idiomatic: 4 for i in 0..scores.len() { 5 println!("idx {}: {}", i, scores[i]); 6 } 7 } ``` **Fix:** iterate the elements directly; use `.enumerate()` only if you actually need the index. ```rust 1 fn main() { 2 let scores = [88, 92, 75]; 3 for score in &scores { 4 println!("score {score}"); 5 } 6 } ``` ### Pitfall 3: Off-by-one with `..` vs `..=` [Section titled “Pitfall 3: Off-by-one with .. vs ..=”](#pitfall-3-off-by-one-with--vs-) `1..4` yields `1, 2, 3` — **not** `4`. Coming from `for (i = 1; i <= 4; i++)`, you will reach for the wrong one. ```rust 1 fn main() { 2 let exclusive: Vec = (1..4).collect(); // [1, 2, 3] 3 let inclusive: Vec = (1..=4).collect(); // [1, 2, 3, 4] 4 println!("{exclusive:?} vs {inclusive:?}"); 5 } ``` ```text 1 [1, 2, 3] vs [1, 2, 3, 4] ``` > **Tip:** Read `..` as “up to” and `..=` as “up to and including”. The exclusive form matches `array.length` indexing perfectly: `0..arr.len()` covers exactly the valid indices. ### Pitfall 4: Mutating a collection while iterating over it [Section titled “Pitfall 4: Mutating a collection while iterating over it”](#pitfall-4-mutating-a-collection-while-iterating-over-it) In JavaScript, pushing to an array while looping over it is legal (and a common source of subtle bugs). Rust rejects it at compile time, because the `for` loop holds an **immutable borrow** of the collection while a `push` needs a **mutable** one: ```rust 1 fn main() { 2 let mut numbers = vec![1, 2, 3]; 3 for n in &numbers { 4 if *n == 2 { 5 numbers.push(99); // does not compile (error[E0502]) 6 } 7 } 8 } ``` ```text 1 error[E0502]: cannot borrow `numbers` as mutable because it is also borrowed as immutable 2 --> src/main.rs:5:13 3 | 4 3 | for n in &numbers { 5 | -------- 6 | | 7 | immutable borrow occurs here 8 | immutable borrow later used here 9 4 | if *n == 2 { 10 5 | numbers.push(99); // try to mutate while borrowed 11 | ^^^^^^^^^^^^^^^^ mutable borrow occurs here ``` **Fix:** collect the changes first, or build a new collection, then apply them after the loop ends. The rules behind this error are the subject of [Section 05 — Ownership](/05-ownership/). ```rust 1 fn main() { 2 let mut numbers = vec![1, 2, 3]; 3 let mut to_add = Vec::new(); 4 for n in &numbers { 5 if *n == 2 { 6 to_add.push(99); 7 } 8 } 9 numbers.extend(to_add); // mutate after the borrow ends 10 println!("{numbers:?}"); // [1, 2, 3, 99] 11 } ``` ### Pitfall 5: Using a value moved by `for` [Section titled “Pitfall 5: Using a value moved by for”](#pitfall-5-using-a-value-moved-by-for) `for x in collection` (without `&`) **consumes** the collection: each element is moved into `x`. Afterward the original is gone: ```rust 1 fn main() { 2 let owned = vec![String::from("a"), String::from("b")]; 3 for s in owned { // moves each String out of `owned` 4 println!("{s}"); 5 } 6 // println!("{}", owned.len()); // would not compile: `owned` was moved 7 } ``` **Fix:** borrow with `&` if you still need the collection after the loop: ```rust 1 fn main() { 2 let owned = vec![String::from("a"), String::from("b")]; 3 for s in &owned { // borrows; `owned` survives 4 println!("{s}"); 5 } 6 println!("still have {} items", owned.len()); // 7 } ``` *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Default to iterating values, not indices [Section titled “1. Default to iterating values, not indices”](#1-default-to-iterating-values-not-indices) ```rust 1 // index-heavy, easy to get wrong 2 for i in 0..items.len() { 3 process(&items[i]); 4 } 5 6 // clear and bounds-safe 7 for item in &items { 8 process(item); 9 } ``` ### 2. Use `.enumerate()` instead of a side counter [Section titled “2. Use .enumerate() instead of a side counter”](#2-use-enumerate-instead-of-a-side-counter) ```rust 1 // manual counter alongside the loop 2 let mut i = 0; 3 for line in &lines { 4 println!("{i}: {line}"); 5 i += 1; 6 } 7 8 // index comes from the iterator 9 for (i, line) in lines.iter().enumerate() { 10 println!("{i}: {line}"); 11 } ``` ### 3. Use `loop { break value }` instead of a sentinel variable [Section titled “3. Use loop { break value } instead of a sentinel variable”](#3-use-loop--break-value--instead-of-a-sentinel-variable) ```rust 1 // JavaScript-style: outer mutable var + while true 2 let mut found = -1; 3 let mut i = 0; 4 while i < 1000 { 5 if is_target(i) { found = i; break; } 6 i += 1; 7 } 8 9 // the loop produces the value directly 10 let found = loop { 11 let candidate = next_candidate(); 12 if is_target(candidate) { 13 break candidate; 14 } 15 }; ``` ### 4. Prefer iterator methods when you are computing a single result [Section titled “4. Prefer iterator methods when you are computing a single result”](#4-prefer-iterator-methods-when-you-are-computing-a-single-result) A `for` loop that just accumulates is often clearer as an iterator chain, and the compiler optimizes it just as well: ```rust 1 fn main() { 2 let scores = [88, 92, 75]; 3 4 // manual accumulation 5 let mut total = 0; 6 for s in &scores { 7 total += s; 8 } 9 10 // expresses intent directly 11 let total: i32 = scores.iter().sum(); 12 13 println!("{total}"); // 255 14 } ``` > **Note:** Reach for a `for` loop when the body has side effects or early exits; reach for iterator adapters (`map`/`filter`/`sum`/`collect`) when you are transforming data into a value. Both are idiomatic. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small slice of a job-runner: poll a backend until a job finishes (using `loop` + `break value`), render a text progress bar with a `for` range, then drain a work queue with `while`. ```rust 1 #[derive(Debug)] 2 struct Job { 3 id: u32, 4 status: &'static str, 5 } 6 7 // Pretend this calls an API. The job "completes" on the 3rd poll. 8 fn poll_job(attempt: u32) -> Job { 9 let status = if attempt >= 3 { "done" } else { "running" }; 10 Job { id: 42, status } 11 } 12 13 fn main() { 14 // `loop` + `break value`: poll until done, hand the finished job back out. 15 let mut attempt = 0; 16 let finished = loop { 17 attempt += 1; 18 let job = poll_job(attempt); 19 println!("attempt {attempt}: job {} is {}", job.id, job.status); 20 21 if job.status == "done" { 22 break job; // the loop evaluates to this Job 23 } 24 if attempt >= 5 { 25 break job; // give up after 5 tries 26 } 27 }; 28 println!("final: {finished:?}"); 29 30 // `for` over a range to render a 10-segment progress bar. 31 let percent = 60; 32 let filled = percent / 10; 33 let mut bar = String::new(); 34 for i in 0..10 { 35 bar.push(if i < filled { '#' } else { '-' }); 36 } 37 println!("[{bar}] {percent}%"); 38 39 // `while` to drain a stack of remaining tasks. 40 let mut queue = vec!["build", "test", "deploy"]; 41 while !queue.is_empty() { 42 let task = queue.pop().unwrap(); 43 println!("running {task}"); 44 } 45 } ``` ```text 1 attempt 1: job 42 is running 2 attempt 2: job 42 is running 3 attempt 3: job 42 is done 4 final: Job { id: 42, status: "done" } 5 [######----] 60% 6 running deploy 7 running test 8 running build ``` > **Note:** Draining the queue with `while let Some(task) = queue.pop()` is even more idiomatic than `while !queue.is_empty()` + `unwrap()`. That `while let` pattern is covered in [if let / while let](/04-control-flow/03-if-let-while-let/). *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Control Flow: Repetition with Loops](https://doc.rust-lang.org/book/ch03-05-control-flow.html#repetition-with-loops) * [The Rust Book — Processing a Series of Items with Iterators](https://doc.rust-lang.org/book/ch13-02-iterators.html) * [Rust by Example — Loops](https://doc.rust-lang.org/rust-by-example/flow_control.html) * [`std::ops::Range` documentation](https://doc.rust-lang.org/std/ops/struct.Range.html) * [`Iterator` trait (adapters like `enumerate`, `rev`, `step_by`)](https://doc.rust-lang.org/std/iter/trait.Iterator.html) ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Conditionals](/04-control-flow/00-conditionals/): `if` as an expression; why loop/`while` conditions must be `bool` * [match](/04-control-flow/02-match/): the other major control-flow expression * [if let / while let](/04-control-flow/03-if-let-while-let/): concise pattern-driven looping (e.g. `while let Some(x) = ...`) * [break & continue](/04-control-flow/04-break-continue/): early exit, skipping iterations, and returning values from a `loop` * [Labeled loops](/04-control-flow/05-labeled-loops/): `break`/`continue` targeting an outer loop by label * [Section 02 — Basics](/02-basics/): variables, types, and operators used above * [Section 03 — Functions](/03-functions/): functions are also expression-based * [Section 05 — Ownership](/05-ownership/): the borrowing rules behind the “mutate while iterating” error * [Section 07 — Collections](/07-collections/): the full iterator toolbox *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: FizzBuzz with a range [Section titled “Exercise 1: FizzBuzz with a range”](#exercise-1-fizzbuzz-with-a-range) **Difficulty:** Easy **Objective:** Practice `for` over an inclusive range and combine it with `if`/`else if`. **Instructions:** Print the numbers `1` through `15`, but print `Fizz` for multiples of 3, `Buzz` for multiples of 5, and `FizzBuzz` for multiples of both. ```rust 1 fn main() { 2 for n in 1..=15 { 3 // TODO: print Fizz / Buzz / FizzBuzz / the number 4 } 5 } ``` Solution ```rust 1 fn main() { 2 for n in 1..=15 { 3 let line = if n % 15 == 0 { 4 "FizzBuzz".to_string() 5 } else if n % 3 == 0 { 6 "Fizz".to_string() 7 } else if n % 5 == 0 { 8 "Buzz".to_string() 9 } else { 10 n.to_string() 11 }; 12 println!("{line}"); 13 } 14 } ``` ```text 1 1 2 2 3 Fizz 4 4 5 Buzz 6 Fizz 7 7 8 8 9 Fizz 10 Buzz 11 11 12 Fizz 13 13 14 14 15 FizzBuzz ``` ### Exercise 2: Return a value from `loop` [Section titled “Exercise 2: Return a value from loop”](#exercise-2-return-a-value-from-loop) **Difficulty:** Medium **Objective:** Use `loop` + `break value` to produce a result, instead of mutating an outer variable. **Instructions:** Write `next_power_of_two_above(target: u32) -> u32` that returns the smallest power of two strictly greater than `target`. Use a `loop` that `break`s with the answer. (Start at `1` and keep doubling.) ```rust 1 fn next_power_of_two_above(target: u32) -> u32 { 2 // TODO: use `loop { ... break p; ... }` 3 } 4 5 fn main() { 6 println!("{}", next_power_of_two_above(100)); // 128 7 println!("{}", next_power_of_two_above(5)); // 8 8 } ``` Solution ```rust 1 fn next_power_of_two_above(target: u32) -> u32 { 2 let mut p = 1u32; 3 loop { 4 if p > target { 5 break p; // the loop evaluates to p, which the fn returns 6 } 7 p *= 2; 8 } 9 } 10 11 fn main() { 12 println!("{}", next_power_of_two_above(100)); // 128 13 println!("{}", next_power_of_two_above(5)); // 8 14 } ``` ```text 1 128 2 8 ``` > The `loop` expression is the function’s tail expression, so its `break` value becomes the return value, no `return` keyword needed. ### Exercise 3: Collatz step counter with `while` [Section titled “Exercise 3: Collatz step counter with while”](#exercise-3-collatz-step-counter-with-while) **Difficulty:** Medium **Objective:** Drive a `while` loop with a changing condition and mutate a counter. **Instructions:** Write `collatz_steps(n: u64) -> u32` that counts how many steps it takes to reach `1` under the Collatz rule: if `n` is even, halve it; if odd, compute `3 * n + 1`. Count each transformation. ```rust 1 fn collatz_steps(mut n: u64) -> u32 { 2 // TODO: loop with `while n != 1 { ... }` 3 } 4 5 fn main() { 6 println!("{}", collatz_steps(27)); // 111 7 println!("{}", collatz_steps(6)); // 8 8 } ``` Solution ```rust 1 fn collatz_steps(mut n: u64) -> u32 { 2 let mut steps = 0; 3 while n != 1 { 4 n = if n % 2 == 0 { n / 2 } else { 3 * n + 1 }; 5 steps += 1; 6 } 7 steps 8 } 9 10 fn main() { 11 println!("{}", collatz_steps(27)); // 111 12 println!("{}", collatz_steps(6)); // 8 13 } ``` ```text 1 111 2 8 ``` > Note `mut n` in the parameter list: parameters are immutable by default in Rust, so you opt into mutating the local copy. The `if`/`else` here is used as an **expression** producing the next value of `n`; see [conditionals](/04-control-flow/00-conditionals/). *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * Rust has **no C-style `for`**: you iterate over ranges and collections * `for x in start..end` (exclusive) and `start..=end` (inclusive) * `.enumerate()` gives you `(index, value)` when you need the index * `.rev()` and `.step_by(n)` replace counting down / stepping * `while condition` works like JavaScript, but the condition must be `bool` * `loop { ... }` is the dedicated infinite loop, and `break value` makes it an expression * Borrowing (`&`) vs moving in `for`, and why you cannot mutate a collection mid-loop **The big mental shift:** stop thinking “advance a counter” and start thinking “iterate over a sequence.” It eliminates off-by-one and out-of-bounds bugs by construction. # Pattern Matching with `match` > Rust's match is JS's switch with no fall-through and no forgotten case: an exhaustive expression that destructures, binds, and matches ranges. Rust’s `match` is the spiritual successor to JavaScript’s `switch`, but it does far more: it is an **expression** that produces a value, and the compiler forces you to handle *every* possible case. If you have ever shipped a bug because a `switch` fell through or missed a case, `match` is about to become your favorite control-flow construct. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **`match` expression** compares a value against a series of **patterns** and runs the code for the first one that fits. Unlike `switch`, it is **exhaustive** (you must cover all cases or the code will not compile), it **never falls through** (no `break` needed), and it can **destructure** data and **bind** parts of it to variables in the same step. For a TypeScript/JavaScript developer, think “`switch` + destructuring + a type-checker that refuses to let you forget a case.” *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) Here is a realistic `switch` you might write to turn a typed status object into a message, plus the kind of fall-through bug that `switch` invites: ```typescript 1 type Status = 2 | { kind: "ok" } 3 | { kind: "notFound" } 4 | { kind: "serverError"; code: number }; 5 6 function describeStatus(status: Status): string { 7 switch (status.kind) { 8 case "ok": 9 return "All good"; 10 case "notFound": 11 return "Resource missing"; 12 case "serverError": 13 return `Server error ${status.code}`; 14 default: 15 return "Unknown"; 16 } 17 } 18 19 // Grouping cases relies on intentional fall-through: 20 function classify(n: number): string { 21 switch (n) { 22 case 1: 23 case 2: 24 case 3: 25 return "small"; 26 case 0: 27 return "zero"; 28 default: 29 return "other"; 30 } 31 } 32 33 // The classic accidental fall-through bug: 34 function risky(x: number): string[] { 35 const out: string[] = []; 36 switch (x) { 37 case 1: 38 out.push("one"); // forgot `break`! 39 case 2: 40 out.push("two"); 41 break; 42 default: 43 out.push("other"); 44 } 45 return out; 46 } 47 48 console.log(describeStatus({ kind: "serverError", code: 503 })); // "Server error 503" 49 console.log(risky(1)); // [ 'one', 'two' ] ← the bug: both ran ``` Running this with Node v22 prints `[ 'one', 'two' ]` for `risky(1)`: case `1` “fell through” into case `2` because the `break` was missing. The `default` branch is also opt-in: drop it and TypeScript will *not* complain that you missed a `kind`. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 #[derive(Debug)] 2 enum HttpStatus { 3 Ok, 4 NotFound, 5 ServerError(u16), 6 } 7 8 fn describe_status(status: &HttpStatus) -> String { 9 // `match` is an expression: this whole thing is the function's return value. 10 match status { 11 HttpStatus::Ok => "All good".to_string(), 12 HttpStatus::NotFound => "Resource missing".to_string(), 13 HttpStatus::ServerError(code) => format!("Server error {code}"), 14 } 15 } 16 17 fn classify(n: i32) -> &'static str { 18 match n { 19 0 => "zero", 20 1 | 2 | 3 => "small", // `|` groups patterns — no fall-through trickery 21 _ => "other", // `_` is the catch-all, like `default` 22 } 23 } 24 25 fn main() { 26 println!("{}", describe_status(&HttpStatus::ServerError(503))); // Server error 503 27 println!("{}", classify(2)); // small 28 println!("{}", classify(0)); // zero 29 } ``` Output (real): ```text 1 Server error 503 2 small 3 zero ``` There is no `break`, there is no fall-through, and there is no `default` you can forget: if you delete one of the three `HttpStatus` arms, the program **will not compile**. > **Note:** Each arm is `pattern => expression,`. The `=>` is a “fat arrow,” not a closure (Rust closures use `|args| body`). All arms must produce the **same type**, because the `match` itself evaluates to that type. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `match` is an expression, not a statement [Section titled “match is an expression, not a statement”](#match-is-an-expression-not-a-statement) In JavaScript a `switch` is a statement — it *does* things, it does not *evaluate to* a value. That is why `describeStatus` had to `return` inside each `case`. In Rust, `match` is an expression, so you can assign its result directly: ```rust 1 fn main() { 2 let code = 503; 3 // The match evaluates to a String, which we bind to `message`. 4 let message = match code { 5 200 => "OK".to_string(), 6 404 => "Not Found".to_string(), 7 500..=599 => format!("Server error {code}"), 8 _ => "Unhandled".to_string(), 9 }; 10 println!("{message}"); // Server error 503 11 } ``` This is the same expression-oriented model you saw with `if` in [Conditionals](/04-control-flow/00-conditionals/) and blocks in [Section 02 — Variables](/02-basics/00-variables/). The last expression of each arm (with **no trailing semicolon**) is that arm’s value. ### Exhaustiveness: the compiler has your back [Section titled “Exhaustiveness: the compiler has your back”](#exhaustiveness-the-compiler-has-your-back) The single biggest upgrade over `switch` is **exhaustiveness checking**. The compiler knows every possible value an `enum` can take, so it refuses to compile a `match` that leaves a case unhandled. This turns “I forgot a case” from a runtime bug into a compile error, and it is *especially* valuable when you later add a new variant to an enum: every `match` that does not handle it lights up red. ### Patterns, not just values [Section titled “Patterns, not just values”](#patterns-not-just-values) A `switch` case can only test for equality against a constant. A `match` arm is a **pattern**, which can: * match a literal (`0`, `'a'`, `"hi"`), * match a range (`1..=9`), * match several alternatives with `|`, * **destructure** a tuple, struct, or enum and pull its fields into variables, * **bind** the whole matched value to a name with `@`, * and add an extra runtime condition with a **guard** (`if ...`). The arms below combine destructuring (`ServerError(code)`) with formatting in one step; no separate `status.code` access needed: ```rust 1 #[derive(Debug)] 2 enum HttpStatus { 3 Ok, 4 NotFound, 5 ServerError(u16), 6 } 7 8 fn main() { 9 let status = HttpStatus::ServerError(503); 10 match &status { 11 HttpStatus::ServerError(code) => println!("got code {code}"), // code is bound to 503 12 other => println!("other: {other:?}"), 13 } 14 } ``` ### Order matters: top to bottom, first match wins [Section titled “Order matters: top to bottom, first match wins”](#order-matters-top-to-bottom-first-match-wins) Like `switch`, arms are tried in order and the **first** matching pattern wins. Unlike `switch`, evaluation stops there; control never falls into the next arm. This means the **catch-all `_` must come last**; put it first and every arm below it becomes dead code (a real warning, shown in Common Pitfalls). *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | JavaScript `switch` | Rust `match` | | ------------------ | ------------------------------------------ | -------------------------------------- | | Produces a value? | No (statement) | Yes (expression) | | Fall-through | Default behavior; needs `break` | Never; no `break` exists | | Missing a case | Silently allowed | **Compile error** (must be exhaustive) | | Grouping cases | Stacked empty `case`s | `pattern1 \| pattern2` | | Ranges | Not supported (`case 1..5` is not a thing) | `1..=9`, `'a'..='z'` | | Destructuring | Done separately, before/after the switch | Built into the pattern | | Extra conditions | An `if` inside the `case` body | Guard: `pattern if cond =>` | | Equality semantics | Uses `===` (strict) | Structural pattern match (no coercion) | | Catch-all | `default:` (optional, position-free) | `_` (must be last to be reachable) | The deepest difference is the mindset: a `switch` *executes statements*; a `match` *describes the shape of data and computes a value from it*. Rust leans hard on this everywhere: `Option`, `Result`, and most enums are designed to be consumed by `match`. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting a case (non-exhaustive match) [Section titled “Pitfall 1: Forgetting a case (non-exhaustive match)”](#pitfall-1-forgetting-a-case-non-exhaustive-match) Coming from `switch`, it is natural to handle “the cases you care about” and stop. Rust will not let you: ```rust 1 enum Direction { 2 North, 3 South, 4 East, 5 West, 6 } 7 8 fn turn(d: Direction) -> &'static str { 9 match d { 10 Direction::North => "up", 11 Direction::South => "down", 12 // does not compile (error[E0004]): forgot East and West 13 } 14 } ``` The real compiler error: ```text 1 error[E0004]: non-exhaustive patterns: `Direction::East` and `Direction::West` not covered 2 --> src/main.rs:9:11 3 | 4 9 | match d { 5 | ^ patterns `Direction::East` and `Direction::West` not covered 6 | 7 note: `Direction` defined here 8 ... 9 4 | East, 10 | ---- not covered 11 5 | West, 12 | ---- not covered 13 = note: the matched value is of type `Direction` 14 help: ensure that all possible cases are being handled by adding a match arm with a wildcard pattern, a match arm with multiple or-patterns as shown, or multiple match arms ``` Add the missing arms, or a `_` catch-all if they really should be treated the same. > **Tip:** Resist the urge to reach for `_` just to silence this error. An explicit `_` means “any new variant added later is also handled here,” which can hide bugs. When the variants are a closed set you control, listing them all means the compiler will remind you to update this `match` the day you add a fifth direction. ### Pitfall 2: Guards do not count toward exhaustiveness [Section titled “Pitfall 2: Guards do not count toward exhaustiveness”](#pitfall-2-guards-do-not-count-toward-exhaustiveness) A guard (`if ...`) makes an arm *conditional*, so the compiler cannot assume it covers the pattern. This is exhaustive-looking but does not compile: ```rust 1 fn main() { 2 let opt = Some(5); 3 let _ = match opt { 4 Some(x) if x > 0 => "positive", 5 None => "none", 6 // does not compile (error[E0004]): `Some(_)` not covered 7 }; 8 } ``` Real error: ```text 1 error[E0004]: non-exhaustive patterns: `Some(_)` not covered 2 --> src/main.rs:3:19 3 | 4 3 | let _ = match opt { 5 | ^^^ pattern `Some(_)` not covered ``` `Some(x)` where `x <= 0` falls through every arm. Add an unguarded arm (e.g. `Some(_) => "non-positive"`) to cover it. ### Pitfall 3: Putting `_` (or a catch-all) too early [Section titled “Pitfall 3: Putting \_ (or a catch-all) too early”](#pitfall-3-putting-_-or-a-catch-all-too-early) In a `switch`, `default` can sit anywhere. In a `match`, arms are tried top-to-bottom, so a catch-all above a specific pattern makes the specific one **unreachable**: ```rust 1 fn main() { 2 let n = 3; 3 let label = match n { 4 _ => "anything", 5 1 => "one", // warning: unreachable 6 }; 7 println!("{label}"); 8 } ``` This compiles but warns: ```text 1 warning: unreachable pattern 2 --> src/main.rs:5:9 3 | 4 4 | _ => "anything", 5 | - matches any value 6 5 | 1 => "one", 7 | ^ no value can reach this 8 | 9 = note: `#[warn(unreachable_patterns)]` on by default ``` Move specific patterns above the catch-all. ### Pitfall 4: Arms must all return the same type [Section titled “Pitfall 4: Arms must all return the same type”](#pitfall-4-arms-must-all-return-the-same-type) Every arm feeds the same `match` expression, so they must agree on a type: ```rust 1 fn main() { 2 let n = 1; 3 // let x = match n { 4 // 1 => "one", // &str 5 // _ => 0, // i32 6 // }; // does not compile (error[E0308]): `match` arms have incompatible types 7 let _ = n; 8 } ``` The fix is to make the arms produce one consistent type (e.g. both `String`, or both `i32`). ### Pitfall 5: Expecting C-style range *case* syntax [Section titled “Pitfall 5: Expecting C-style range case syntax”](#pitfall-5-expecting-c-style-range-case-syntax) There is no `case 1..5:` in `switch`, and the Rust *expression* range `1..5` you use in a `for` loop ([Loops](/04-control-flow/01-loops/)) is **not** the same as a range *pattern*. In a pattern you write `1..=9` (inclusive) or `1..10` (exclusive); you cannot use a runtime range variable as a pattern. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Match on enums and let exhaustiveness guide you [Section titled “Match on enums and let exhaustiveness guide you”](#match-on-enums-and-let-exhaustiveness-guide-you) Model your states as an `enum` and `match` on it. The compiler then guarantees every state is handled, and reminds you to revisit each `match` whenever you add a variant. This is the Rust replacement for discriminated-union `switch`es in TypeScript. ### Prefer explicit arms over `_` for closed enums [Section titled “Prefer explicit arms over \_ for closed enums”](#prefer-explicit-arms-over-_-for-closed-enums) For your own enums, list the variants. Reserve `_` for genuinely open-ended values like integers and chars, where enumerating everything is impossible. ### Reach for `if let` when you only care about one case [Section titled “Reach for if let when you only care about one case”](#reach-for-if-let-when-you-only-care-about-one-case) If a `match` has one meaningful arm and a do-nothing `_ => {}`, an `if let` is cleaner. That is its own topic; see [Concise Pattern Matching](/04-control-flow/03-if-let-while-let/): ```rust 1 fn main() { 2 let config_value: Option = Some(8080); 3 4 // Instead of: match config_value { Some(port) => {...}, None => {} } 5 if let Some(port) = config_value { 6 println!("listening on {port}"); 7 } 8 } ``` ### Use `|`, ranges, and guards to keep arms readable [Section titled “Use |, ranges, and guards to keep arms readable”](#use--ranges-and-guards-to-keep-arms-readable) Group alternatives with `|`, collapse contiguous values into a range, and use a guard for the one extra condition that does not fit the pattern. Keep the heavy logic in a `{ }` block or a helper function so the arm stays scannable. ### Bind with `@` when you need both the test *and* the value [Section titled “Bind with @ when you need both the test and the value”](#bind-with--when-you-need-both-the-test-and-the-value) When you want to check that a value is in a range *and* keep the value, `name @ pattern` does both in one step instead of re-reading the variable. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A tiny command interpreter — the kind you might build for a REPL, a chat bot, or a debug console. It shows `|` patterns, ranges, the `@` binding, guards, destructuring, and nested `match`es all working together to parse and execute typed commands. ```rust 1 /// A tiny command interpreter, the kind you'd build for a REPL or a chat bot. 2 #[derive(Debug)] 3 enum Command { 4 Help, 5 Echo(String), 6 Add(i64, i64), 7 SetVolume(u8), 8 Quit, 9 Unknown(String), 10 } 11 12 /// Parse a raw line into a typed Command. 13 fn parse(line: &str) -> Command { 14 let mut parts = line.trim().splitn(2, ' '); 15 let verb = parts.next().unwrap_or(""); 16 let rest = parts.next().unwrap_or("").trim(); 17 18 match verb { 19 "help" | "?" => Command::Help, // `|` = multiple aliases 20 "echo" => Command::Echo(rest.to_string()), 21 "add" => { 22 let mut nums = rest.split_whitespace(); 23 // Nested match on a tuple of two parse results. 24 match (nums.next(), nums.next()) { 25 (Some(a), Some(b)) => match (a.parse(), b.parse()) { 26 (Ok(x), Ok(y)) => Command::Add(x, y), 27 _ => Command::Unknown(line.to_string()), 28 }, 29 _ => Command::Unknown(line.to_string()), 30 } 31 } 32 "volume" => match rest.parse::() { 33 // `v @ 0..=100`: bind the value AND require it to be in range. 34 Ok(v @ 0..=100) => Command::SetVolume(v), 35 _ => Command::Unknown(line.to_string()), 36 }, 37 "quit" | "exit" => Command::Quit, 38 _ => Command::Unknown(line.to_string()), 39 } 40 } 41 42 /// Execute a command and return the user-facing response. 43 fn run(cmd: Command) -> String { 44 match cmd { 45 Command::Help => "commands: help, echo, add, volume, quit".to_string(), 46 // Guard: an empty echo is a special case. 47 Command::Echo(text) if text.is_empty() => "(nothing to echo)".to_string(), 48 Command::Echo(text) => text, 49 Command::Add(a, b) => format!("{a} + {b} = {}", a + b), 50 Command::SetVolume(v) => format!("volume set to {v}"), 51 Command::Quit => "bye!".to_string(), 52 Command::Unknown(raw) => format!("unknown command: {raw:?}"), 53 } 54 } 55 56 fn main() { 57 let session = [ 58 "help", 59 "echo hello there", 60 "add 19 23", 61 "volume 80", 62 "volume 250", 63 "dance now", 64 "quit", 65 ]; 66 67 for line in session { 68 let cmd = parse(line); 69 println!("> {line}"); 70 println!(" {}", run(cmd)); 71 } 72 } ``` Real output: ```text 1 > help 2 commands: help, echo, add, volume, quit 3 > echo hello there 4 hello there 5 > add 19 23 6 19 + 23 = 42 7 > volume 80 8 volume set to 80 9 > volume 250 10 unknown command: "volume 250" 11 > dance now 12 unknown command: "dance now" 13 > quit 14 bye! ``` Notice `volume 250` falls through to `Unknown`: the `v @ 0..=100` pattern rejects `250` because it is out of range, so `parse` returns `Command::Unknown`. The range check is part of the *pattern*, not a separate `if`. ### Bonus: the patterns toolbox [Section titled “Bonus: the patterns toolbox”](#bonus-the-patterns-toolbox) A compact tour of every pattern feature in this file’s scope, all in one program: ```rust 1 #[derive(Debug)] 2 struct Point { 3 x: i32, 4 y: i32, 5 z: i32, 6 } 7 8 fn char_kind(c: char) -> &'static str { 9 match c { 10 'a'..='z' => "lowercase", // char ranges work too 11 'A'..='Z' => "uppercase", 12 '0'..='9' => "digit", 13 _ => "other", 14 } 15 } 16 17 fn classify(n: i32) -> &'static str { 18 match n { 19 0 => "zero", 20 1 | 2 | 3 => "small", // `|` alternatives 21 4..=9 => "medium", // inclusive range 22 _ if n < 0 => "negative", // guard on the catch-all 23 _ => "large", 24 } 25 } 26 27 fn main() { 28 for c in ['k', 'Q', '7', '#'] { 29 println!("{c}: {}", char_kind(c)); 30 } 31 32 for n in [-5, 0, 2, 7, 42] { 33 println!("{n} is {}", classify(n)); 34 } 35 36 // Destructure a struct; `..` ignores the rest of the fields. 37 let p = Point { x: 1, y: 2, z: 3 }; 38 match p { 39 Point { x: 0, y: 0, z: 0 } => println!("at origin"), 40 Point { x, .. } => println!("x is {x}, ignoring y and z"), 41 } 42 43 // Tuple destructuring with literal + binding patterns. 44 let point = (0, 7); 45 let desc = match point { 46 (0, 0) => "origin".to_string(), 47 (x, 0) => format!("on x-axis at {x}"), 48 (0, y) => format!("on y-axis at {y}"), 49 (x, y) => format!("at ({x}, {y})"), 50 }; 51 println!("{desc}"); 52 53 // `@` binding: capture the value while also range-checking it. 54 let id = 5; 55 let label = match id { 56 n @ 1..=9 => format!("single digit: {n}"), 57 n @ 10..=99 => format!("double digit: {n}"), 58 n => format!("big: {n}"), 59 }; 60 println!("{label}"); 61 62 // Slice patterns: first and last with `..` in the middle. 63 let numbers = [1, 2, 3]; 64 match numbers { 65 [first, .., last] => println!("first {first}, last {last}"), 66 } 67 } ``` Real output: ```text 1 k: lowercase 2 Q: uppercase 3 7: digit 4 #: other 5 -5 is negative 6 0 is zero 7 2 is small 8 7 is medium 9 42 is large 10 x is 1, ignoring y and z 11 on y-axis at 7 12 single digit: 5 13 first 1, last 3 ``` *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Rust Book — The `match` Control Flow Construct](https://doc.rust-lang.org/book/ch06-02-match.html) * [The Rust Book — Patterns and Matching (Chapter 19)](https://doc.rust-lang.org/book/ch19-00-patterns.html) * [The Rust Book — All the Places Patterns Can Be Used](https://doc.rust-lang.org/book/ch19-01-all-the-places-for-patterns.html) * [Rust Reference — Patterns](https://doc.rust-lang.org/reference/patterns.html) * [Rust by Example — `match`](https://doc.rust-lang.org/rust-by-example/flow_control/match.html) ### Related sections in this guide [Section titled “Related sections in this guide”](#related-sections-in-this-guide) * [Conditionals](/04-control-flow/00-conditionals/) — `if`/`else` as expressions; the `if let` teaser. * [Loops](/04-control-flow/01-loops/) — where expression ranges like `1..5` come from (different from range *patterns*). * [`if let` and `while let`](/04-control-flow/03-if-let-while-let/) — concise pattern matching for one or two cases. * [Break, continue, and labeled loops](/04-control-flow/04-break-continue/) — controlling iteration that wraps a `match`. * [Section 02 — Types](/02-basics/01-types/) — tuples, chars, and the integer types you match on. * [Section 02 — Operators](/02-basics/02-operators/) — why `match` patterns are not `==` comparisons. * [Section 05 — Ownership](/05-ownership/) — how matching on a reference (`match &value`) avoids moving the value out. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: FizzBuzz, the pattern-matching way [Section titled “Exercise 1: FizzBuzz, the pattern-matching way”](#exercise-1-fizzbuzz-the-pattern-matching-way) **Difficulty:** Easy **Objective:** Practice matching on a tuple and using the `_` wildcard inside a pattern. **Instructions:** Implement `fizzbuzz(n)` so that it returns `"Fizz"` when `n` is divisible by 3, `"Buzz"` when divisible by 5, `"FizzBuzz"` when divisible by both, and the number itself otherwise. Do it with a single `match` on the tuple `(n % 3, n % 5)`, no `if`/`else`. ```rust 1 fn fizzbuzz(n: u32) -> String { 2 match (n % 3, n % 5) { 3 /* ??? */ 4 } 5 } 6 7 fn main() { 8 for n in [1, 3, 5, 15, 7] { 9 println!("{n} -> {}", fizzbuzz(n)); 10 } 11 } ``` Solution ```rust 1 fn fizzbuzz(n: u32) -> String { 2 match (n % 3, n % 5) { 3 (0, 0) => "FizzBuzz".to_string(), 4 (0, _) => "Fizz".to_string(), // divisible by 3 only 5 (_, 0) => "Buzz".to_string(), // divisible by 5 only 6 (_, _) => n.to_string(), // neither 7 } 8 } 9 10 fn main() { 11 for n in [1, 3, 5, 15, 7] { 12 println!("{n} -> {}", fizzbuzz(n)); 13 } 14 } ``` Output: ```text 1 1 -> 1 2 3 -> Fizz 3 5 -> Buzz 4 15 -> FizzBuzz 5 7 -> 7 ``` The `(0, 0)` arm must come first: order matters, and a number divisible by both 3 and 5 would otherwise be caught by `(0, _)`. ### Exercise 2: HTTP status categories with ranges [Section titled “Exercise 2: HTTP status categories with ranges”](#exercise-2-http-status-categories-with-ranges) **Difficulty:** Medium **Objective:** Use inclusive range patterns and a catch-all to classify values. **Instructions:** Implement `status_category(code: u16)` that returns `"informational"` for `100..=199`, `"success"` for `200..=299`, `"redirect"` for `300..=399`, `"client error"` for `400..=499`, `"server error"` for `500..=599`, and `"invalid"` for anything else. ```rust 1 fn status_category(code: u16) -> &'static str { 2 match code { 3 // TODO: fill in the range arms 4 } 5 } 6 7 fn main() { 8 for code in [101, 204, 301, 404, 503, 999] { 9 println!("{code} -> {}", status_category(code)); 10 } 11 } ``` Solution ```rust 1 fn status_category(code: u16) -> &'static str { 2 match code { 3 100..=199 => "informational", 4 200..=299 => "success", 5 300..=399 => "redirect", 6 400..=499 => "client error", 7 500..=599 => "server error", 8 _ => "invalid", 9 } 10 } 11 12 fn main() { 13 for code in [101, 204, 301, 404, 503, 999] { 14 println!("{code} -> {}", status_category(code)); 15 } 16 } ``` Output: ```text 1 101 -> informational 2 204 -> success 3 301 -> redirect 4 404 -> client error 5 503 -> server error 6 999 -> invalid ``` The `_ => "invalid"` arm is required: `u16` can hold values like `999` and `0` that no range covers, so without it the match would not be exhaustive. ### Exercise 3: Evaluate an expression tree [Section titled “Exercise 3: Evaluate an expression tree”](#exercise-3-evaluate-an-expression-tree) **Difficulty:** Hard **Objective:** Destructure a recursive enum, bind its fields, and combine `match` with a guard and a nested `match` for error handling. **Instructions:** Given the `Expr` enum below, implement `eval(expr: &Expr) -> Result` that evaluates the tree. Numbers evaluate to themselves; `Add`/`Sub`/`Mul` combine their operands; `Div` returns `Err("division by zero")` when the divisor evaluates to `0.0`. Use the `?` operator to propagate errors from sub-evaluations. (`Box`, `Result`, and `?` are previewed in [Section 03](/03-functions/) and covered fully in [Section 08 — Error Handling](/08-error-handling/).) ```rust 1 #[derive(Debug)] 2 enum Expr { 3 Num(f64), 4 Add(Box, Box), 5 Sub(Box, Box), 6 Mul(Box, Box), 7 Div(Box, Box), 8 } 9 10 fn eval(expr: &Expr) -> Result { 11 // TODO: match on `expr` 12 } 13 14 fn main() { 15 // (2 + 3) * 4 - 1 16 let expr = Expr::Sub( 17 Box::new(Expr::Mul( 18 Box::new(Expr::Add(Box::new(Expr::Num(2.0)), Box::new(Expr::Num(3.0)))), 19 Box::new(Expr::Num(4.0)), 20 )), 21 Box::new(Expr::Num(1.0)), 22 ); 23 println!("{:?}", eval(&expr)); 24 25 let bad = Expr::Div(Box::new(Expr::Num(10.0)), Box::new(Expr::Num(0.0))); 26 println!("{:?}", eval(&bad)); 27 } ``` Solution ```rust 1 #[derive(Debug)] 2 enum Expr { 3 Num(f64), 4 Add(Box, Box), 5 Sub(Box, Box), 6 Mul(Box, Box), 7 Div(Box, Box), 8 } 9 10 fn eval(expr: &Expr) -> Result { 11 match expr { 12 // `Num(n)` binds n: &f64, so dereference with *n. 13 Expr::Num(n) => Ok(*n), 14 Expr::Add(a, b) => Ok(eval(a)? + eval(b)?), 15 Expr::Sub(a, b) => Ok(eval(a)? - eval(b)?), 16 Expr::Mul(a, b) => Ok(eval(a)? * eval(b)?), 17 // Nested match on the divisor catches division by zero. 18 Expr::Div(a, b) => match eval(b)? { 19 0.0 => Err("division by zero".to_string()), 20 divisor => Ok(eval(a)? / divisor), 21 }, 22 } 23 } 24 25 fn main() { 26 // (2 + 3) * 4 - 1 27 let expr = Expr::Sub( 28 Box::new(Expr::Mul( 29 Box::new(Expr::Add(Box::new(Expr::Num(2.0)), Box::new(Expr::Num(3.0)))), 30 Box::new(Expr::Num(4.0)), 31 )), 32 Box::new(Expr::Num(1.0)), 33 ); 34 println!("{:?}", eval(&expr)); // Ok(19.0) 35 36 let bad = Expr::Div(Box::new(Expr::Num(10.0)), Box::new(Expr::Num(0.0))); 37 println!("{:?}", eval(&bad)); // Err("division by zero") 38 } ``` Output: ```text 1 Ok(19.0) 2 Err("division by zero") ``` A few things to notice: `eval(a)?` recursively evaluates the sub-tree and short-circuits the whole function if it returns `Err`. Because we matched on `&Expr`, the bindings `a` and `b` are `&Box`, which auto-dereference cleanly when passed back into `eval`. The nested `match eval(b)?` is how you inspect a computed value mid-pattern. # Concise Pattern Matching: `if let`, `while let`, and `let ... else` > When only one case matters, if let, while let, and let-else fuse the check and binding in one step, replacing TypeScript's if (x !== null) narrowing. A full [`match`](/04-control-flow/02-match/) is wonderful when you genuinely care about *every* variant, but a lot of real code only cares about *one* case: “if this `Option` is `Some`, use it.” Rust gives you three lightweight tools for exactly that — `if let`, `while let`, and `let ... else` — and they will quickly become the workhorses you reach for when you would have written `if (x !== null)` in TypeScript. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) `if let` runs a block only when a value matches a single pattern, binding the inner data in one step. Think of it as `if` fused with destructuring. `while let` is the loop version: keep looping as long as the pattern keeps matching. `let ... else` (often called **let-else**) binds a pattern unconditionally and runs a diverging `else` block (like `return` or `break`) when it *doesn’t* match, which is the cleanest way to do early-return “guard clauses” in Rust. > **Note:** These are all *syntactic sugar* over `match`. Learning them after [`match`](/04-control-flow/02-match/) makes the sugar obvious; learning them first makes `match` feel like a natural generalization. Either order is fine. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript, you constantly narrow a possibly-absent value before using it. There is no destructuring-in-the-condition, so you check first and read the field on the next line. ```typescript 1 // TypeScript: narrow-then-use, the everyday pattern 2 interface Session { 3 userId: number; 4 token: string; 5 } 6 7 function currentSession(): Session | null { 8 return Math.random() > 0.5 ? { userId: 7, token: "abc" } : null; 9 } 10 11 const session = currentSession(); 12 if (session !== null) { 13 // `session` is narrowed to Session inside this block 14 console.log(`User ${session.userId} is logged in`); 15 } else { 16 console.log("No active session"); 17 } 18 19 // "Keep going while there's work" — the while-let shape 20 const stack: number[] = [1, 2, 3, 4, 5]; 21 let top: number | undefined; 22 while ((top = stack.pop()) !== undefined) { 23 console.log(`popped ${top}`); 24 } 25 26 // Guard clause / early return to avoid nesting 27 function parsePort(input: string): string { 28 const port = Number(input); 29 if (!Number.isInteger(port)) { 30 return `'${input}' is not a valid port`; 31 } 32 // `port` is usable for the rest of the function 33 return `listening on port ${port}`; 34 } ``` Notice three friction points a Rust developer will recognize: you re-read `session` after narrowing, the `while` loop needs an extra mutable `top` declared *outside* the loop, and the guard clause re-checks a condition rather than binding the success value directly. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust folds the check and the binding together. Each block below is **compile-verified**. ```rust 1 #[derive(Debug)] 2 struct Session { 3 user_id: u32, 4 token: String, 5 } 6 7 fn current_session() -> Option { 8 Some(Session { user_id: 7, token: "abc".to_string() }) 9 } 10 11 fn parse_port(input: &str) -> String { 12 // let-else: bind on success, diverge on failure — no re-check, no nesting 13 let Ok(port) = input.parse::() else { 14 return format!("'{input}' is not a valid port"); 15 }; 16 format!("listening on port {port}") 17 } 18 19 fn main() { 20 // if let: check + destructure in one step 21 if let Some(session) = current_session() { 22 println!("User {} is logged in", session.user_id); 23 } else { 24 println!("No active session"); 25 } 26 27 // while let: loop as long as `pop()` keeps returning Some 28 let mut stack = vec![1, 2, 3, 4, 5]; 29 while let Some(top) = stack.pop() { 30 println!("popped {top}"); 31 } 32 33 println!("{}", parse_port("8080")); 34 println!("{}", parse_port("not-a-port")); 35 } ``` Running it prints: ```text 1 User 7 is logged in 2 popped 5 3 popped 4 4 popped 3 5 popped 2 6 popped 1 7 listening on port 8080 8 'not-a-port' is not a valid port ``` The mutable `top` variable that TypeScript needed outside the loop is gone. `while let` declares and binds `top` fresh on every iteration, scoped to the loop body. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `if let`: “match one pattern, ignore the rest” [Section titled “if let: “match one pattern, ignore the rest””](#if-let-match-one-pattern-ignore-the-rest) `if let PATTERN = EXPRESSION { ... }` evaluates `EXPRESSION`, tries to match it against `PATTERN`, and runs the block only on a match. On a match, any variables in the pattern are bound and **scoped to the block**. ```rust 1 fn main() { 2 let maybe_user: Option<&str> = Some("Ada"); 3 4 if let Some(name) = maybe_user { 5 // `name` is the &str inside the Some, only visible here 6 println!("Welcome, {name}!"); 7 } else { 8 // optional else, runs on no-match 9 println!("No user logged in"); 10 } 11 } ``` This is exactly equivalent to the more verbose: ```rust 1 fn main() { 2 let maybe_user: Option<&str> = Some("Ada"); 3 4 match maybe_user { 5 Some(name) => println!("Welcome, {name}!"), 6 None => println!("No user logged in"), 7 } 8 } ``` `if let` shines when one of the `match` arms would be a do-nothing `_ => {}`. It works on *any* pattern, not just `Option`: enums, structs, tuples, and ranges all work: ```rust 1 #[derive(Debug)] 2 enum Event { 3 Click { x: i32, y: i32 }, 4 KeyPress(char), 5 Close, 6 } 7 8 fn main() { 9 let event = Event::Click { x: 10, y: 20 }; 10 // Struct-variant destructuring directly in the condition 11 if let Event::Click { x, y } = event { 12 println!("Clicked at ({x}, {y})"); 13 } 14 15 let key = Event::KeyPress('q'); 16 if let Event::KeyPress(c) = key { 17 println!("Key pressed: {c}"); 18 } 19 20 let _ = Event::Close; // (just to use the variant) 21 } ``` This prints: ```text 1 Clicked at (10, 20) 2 Key pressed: q ``` ### `else if let` chains [Section titled “else if let chains”](#else-if-let-chains) You can chain alternatives with `else if let`, mixing in regular `else if` and a final `else`: ```rust 1 fn main() { 2 let setting: Option = None; 3 let fallback: Option = Some(42); 4 5 if let Some(v) = setting { 6 println!("setting = {v}"); 7 } else if let Some(v) = fallback { 8 println!("fallback = {v}"); 9 } else { 10 println!("nothing set"); 11 } 12 } ``` This prints `fallback = 42`. Each `if let` tries its own pattern; the first match wins. ### `if let` chains with `&&` (Rust 2024) [Section titled “if let chains with && (Rust 2024)”](#if-let-chains-with--rust-2024) Since the latest stable edition (2024, stabilized in Rust 1.88), you can join a pattern match and ordinary boolean conditions with `&&` in a single `if let`. All conditions must hold, and bindings from earlier links are visible to later ones: ```rust 1 fn main() { 2 let opt: Option = Some(7); 3 let flag = true; 4 5 // let-chain: pattern match AND boolean tests together 6 if let Some(n) = opt && n > 5 && flag { 7 println!("matched and n={n} > 5"); 8 } 9 } ``` This prints `matched and n=7 > 5`. Before this feature you had to nest an `if let` inside an `if`, or push the extra condition into a `match` guard. > **Note:** Let-chains require the 2024 edition. A fresh `cargo new` selects it automatically, so you get this for free in new projects. ### `while let`: loop while the pattern keeps matching [Section titled “while let: loop while the pattern keeps matching”](#while-let-loop-while-the-pattern-keeps-matching) `while let PATTERN = EXPRESSION { ... }` re-evaluates `EXPRESSION` before every iteration and stops the first time it does *not* match. It is the idiomatic way to drain anything that yields `Option`: ```rust 1 fn main() { 2 // Drain a stack: pop() returns Some(x) until empty, then None 3 let mut stack = vec![1, 2, 3]; 4 while let Some(top) = stack.pop() { 5 println!("popped {top}"); 6 } 7 8 // Pull values straight from an iterator 9 let mut numbers = vec![10, 20, 30].into_iter(); 10 while let Some(n) = numbers.next() { 11 println!("got {n}"); 12 } 13 } ``` > **Tip:** A `while let ... = iter.next()` loop is almost always better written as a plain `for n in iter { ... }`, which handles the `next()`/`None` dance for you. Reach for `while let` when the source is a mutable container you are *consuming* (like `stack.pop()` or `channel.recv()`), where `for` does not directly apply. See [Loops](/04-control-flow/01-loops/) for the `for`/`while`/`loop` trio. ### `let ... else`: early-return guard clauses [Section titled “let ... else: early-return guard clauses”](#let--else-early-return-guard-clauses) `let PATTERN = EXPRESSION else { ... }` binds `PATTERN` for the **rest of the enclosing scope** when it matches. When it does *not* match, the `else` block runs, and that block **must diverge**, meaning it has to leave the current scope via `return`, `break`, `continue`, or a `panic!`. This is Rust’s answer to the guard-clause / early-return style. ```rust 1 fn first_word(text: &str) -> &str { 2 let Some(word) = text.split_whitespace().next() else { 3 return ""; 4 }; 5 // `word` is in scope here, with no extra indentation 6 word 7 } 8 9 fn main() { 10 println!("{}", first_word("hello world")); // hello 11 println!("{}", first_word(" ")); // 12 } ``` The key difference from `if let`: with `if let`, the binding lives *inside* the block. With `let ... else`, the binding lives *after* the statement, in the surrounding scope — which is precisely what you want for “validate, then proceed with the validated value.” Compare the shapes: ```rust 1 // if let: success path is INSIDE, nesting grows with each check 2 fn describe_if_let(input: &str) -> String { 3 if let Ok(n) = input.parse::() { 4 if n > 0 { 5 return format!("positive: {n}"); 6 } 7 } 8 "invalid".to_string() 9 } 10 11 // let-else: success path is the MAIN body, failures bail early 12 fn describe_let_else(input: &str) -> String { 13 let Ok(n) = input.parse::() else { 14 return "invalid".to_string(); 15 }; 16 if n <= 0 { 17 return "invalid".to_string(); 18 } 19 format!("positive: {n}") 20 } ``` `let ... else` also works mid-loop, where the divergence is `continue` or `break`: ```rust 1 fn sum_even_strings(items: &[&str]) -> i32 { 2 let mut total = 0; 3 for item in items { 4 // Skip anything that isn't a number, without nesting the happy path 5 let Ok(n) = item.parse::() else { 6 continue; 7 }; 8 if n % 2 == 0 { 9 total += n; 10 } 11 } 12 total 13 } 14 15 fn main() { 16 println!("{}", sum_even_strings(&["2", "x", "4", "5", "6"])); // 12 17 } ``` *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript | Rust | | ------------------------ | ----------------------------------------------------- | --------------------------------------------------------- | | Narrow-then-use | `if (x !== null) { use x }`, re-read `x` | `if let Some(v) = x { use v }`, binds in one step | | Binding scope on success | Whole block after the narrowing check | `if let`: inside block; `let ... else`: rest of scope | | Loop while value present | `while ((v = next()) !== undefined)` with outer `let` | `while let Some(v) = next()`, fresh binding each pass | | Early-return guard | `if (!ok) return;` then re-fetch the value | `let Ok(v) = ... else { return; };` binds `v` directly | | Combine match + boolean | nest `if` inside `if` | `if let P = x && cond` (let-chains, edition 2024) | | What you can match | runtime `typeof` / property checks | any pattern: enums, structs, tuples, ranges, `@` bindings | ### The conceptual shift [Section titled “The conceptual shift”](#the-conceptual-shift) In TypeScript you *test* a value and the compiler *narrows* its static type for the rest of the block. In Rust you *match a pattern* and the compiler *binds* the inner data. The mechanisms differ, but the ergonomics line up: `if let Some(v) = opt` feels like `if (opt != null)`, and `let Some(v) = opt else { return; }` feels like `if (opt == null) return;`. Unlike TypeScript, the success binding from `if let` does **not** leak past the closing brace. There is no flow-based narrowing that survives the block. When you want the value afterward, that is the signal to use `let ... else` instead. ### `if let` is refutable; `let` is irrefutable [Section titled “if let is refutable; let is irrefutable”](#if-let-is-refutable-let-is-irrefutable) A plain `let x = ...;` requires an **irrefutable** pattern — one that always matches (like a bare name or a tuple of names). `if let`, `while let`, and the pattern in `let ... else` accept **refutable** patterns — ones that might fail (like `Some(x)` or `Ok(x)`). That refutability is exactly what gives them a “didn’t match” path to run. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Expecting the `if let` binding to survive the block [Section titled “Pitfall 1: Expecting the if let binding to survive the block”](#pitfall-1-expecting-the-if-let-binding-to-survive-the-block) A TypeScript developer expects the narrowed value to be usable after the `if`. In Rust the binding is scoped to the block and disappears. ```rust 1 fn main() { 2 let maybe_name: Option<&str> = Some("Grace"); 3 if let Some(name) = maybe_name { 4 println!("inside: {name}"); 5 } 6 // `name` only existed inside the if-let block: 7 println!("outside: {name}"); // does not compile (error[E0425]) 8 } ``` The real compiler error: ```text 1 error[E0425]: cannot find value `name` in this scope 2 --> src/main.rs:7:25 3 | 4 7 | println!("outside: {name}"); 5 | ^^^^ not found in this scope ``` **Fix:** if you need the value afterward, use `let ... else`, which binds for the rest of the scope: ```rust 1 fn main() { 2 let maybe_name: Option<&str> = Some("Grace"); 3 let Some(name) = maybe_name else { 4 println!("no name"); 5 return; 6 }; 7 println!("inside or outside, {name} is in scope now"); 8 } ``` ### Pitfall 2: A `let ... else` block that doesn’t diverge [Section titled “Pitfall 2: A let ... else block that doesn’t diverge”](#pitfall-2-a-let--else-block-that-doesnt-diverge) The `else` block must leave the scope. If it just prints and falls through, the compiler rejects it, because `name` would otherwise be unbound on that path. ```rust 1 fn get_count(input: &str) -> i32 { 2 let Ok(n) = input.parse::() else { 3 println!("not a number"); 4 // does not compile (error[E0308]): forgot to diverge 5 }; 6 n 7 } 8 9 fn main() { 10 println!("{}", get_count("5")); 11 } ``` The real compiler error: ```text 1 error[E0308]: `else` clause of `let...else` does not diverge 2 --> src/main.rs:2:43 3 | 4 2 | let Ok(n) = input.parse::() else { 5 | ___________________________________________^ 6 3 | | println!("not a number"); 7 4 | | // forgot to diverge (no return/break/panic) 8 5 | | }; 9 | |_____^ expected `!`, found `()` 10 | 11 = note: expected type `!` 12 found unit type `()` 13 = help: try adding a diverging expression, such as `return` or `panic!(..)` 14 = help: ...or use `match` instead of `let...else` ``` **Fix:** end the `else` with `return`, `break`, `continue`, or `panic!` (or another expression of the never type `!`). ### Pitfall 3: Using `if let` with a pattern that always matches [Section titled “Pitfall 3: Using if let with a pattern that always matches”](#pitfall-3-using-if-let-with-a-pattern-that-always-matches) If the pattern can never fail, `if let` is pointless, and Clippy/rustc will tell you so with a built-in lint. ```rust 1 fn main() { 2 let point = (3, 4); 3 // A tuple pattern always matches a tuple -> irrefutable 4 if let (x, y) = point { // irrefutable_let_patterns warning 5 println!("{x}, {y}"); 6 } 7 } ``` The real warning: ```text 1 warning: irrefutable `if let` pattern 2 --> src/main.rs:4:8 3 | 4 4 | if let (x, y) = point { 5 | ^^^^^^^^^^^^^^^^^^ 6 | 7 = note: this pattern will always match, so the `if let` is useless 8 = help: consider replacing the `if let` with a `let` 9 = note: `#[warn(irrefutable_let_patterns)]` on by default ``` **Fix:** use a plain `let (x, y) = point;`; no conditional needed. ### Pitfall 4: `if let` where every variant matters [Section titled “Pitfall 4: if let where every variant matters”](#pitfall-4-if-let-where-every-variant-matters) `if let` silently ignores the non-matching cases. That is a feature when you truly do not care, but a bug when you do. If you find yourself writing `else if let ... else if let ...` over an enum’s variants, you have re-implemented `match` badly and lost its exhaustiveness checking. Prefer [`match`](/04-control-flow/02-match/) when you want the compiler to force you to handle every case. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Reach for the lightest tool that fits [Section titled “Reach for the lightest tool that fits”](#reach-for-the-lightest-tool-that-fits) * **One case matters, nothing needed afterward → `if let`** (optionally with `else`). * **One case matters, value needed for the rest of the scope → `let ... else`.** * **Repeatedly consume a source that yields `Option` → `while let`** (but prefer `for` when iterating). * **Every variant matters → [`match`](/04-control-flow/02-match/).** ### Use `let ... else` to flatten guard clauses [Section titled “Use let ... else to flatten guard clauses”](#use-let--else-to-flatten-guard-clauses) Early returns keep the happy path un-indented. This scales far better than a pyramid of nested `if let`s: ```rust 1 fn extract_user_id(header: &str) -> Result { 2 let Some(token) = header.strip_prefix("Bearer ") else { 3 return Err("missing Bearer prefix".to_string()); 4 }; 5 let Ok(id) = token.parse::() else { 6 return Err(format!("invalid id: {token}")); 7 }; 8 Ok(id) 9 } 10 11 fn main() { 12 println!("{:?}", extract_user_id("Bearer 42")); // Ok(42) 13 println!("{:?}", extract_user_id("Basic 42")); // Err("missing Bearer prefix") 14 println!("{:?}", extract_user_id("Bearer notanum")); // Err("invalid id: notanum") 15 } ``` > **Tip:** Inside a function returning `Result` or `Option`, the [`?` operator](/03-functions/) is often even shorter than `let ... else` for plain “propagate the error” cases. Use `let ... else` when you need a *custom* failure action (a different error, a log line, a `continue`), not just propagation. ### Combine conditions with let-chains instead of nesting [Section titled “Combine conditions with let-chains instead of nesting”](#combine-conditions-with-let-chains-instead-of-nesting) When you need a pattern match *and* an extra check, a let-chain (`if let P = x && cond`) reads better than nesting and keeps both the binding and the condition in one place. ### Don’t reach for `if let` over an exhaustive enum [Section titled “Don’t reach for if let over an exhaustive enum”](#dont-reach-for-if-let-over-an-exhaustive-enum) If the compiler could be checking exhaustiveness for you, let it. `match` turns “I forgot the `Disconnected` variant” into a compile error; a chain of `if let`s turns it into a silent runtime no-op. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small command interpreter that reads lines, parses each into a typed `Command`, and builds up a profile. It uses `while let` to drain a work queue, `if let` to react only to recognized commands, `let ... else` (via `?`) inside the parser, and an `if let` with a tuple pattern at the end. This compiles and runs as-is. ```rust 1 use std::collections::VecDeque; 2 3 /// A command parsed from a line of user input. 4 #[derive(Debug)] 5 enum Command { 6 SetName(String), 7 SetAge(u32), 8 Quit, 9 } 10 11 /// Parse one line into a `Command`, or `None` if it is not recognized. 12 fn parse_command(line: &str) -> Option { 13 let mut parts = line.split_whitespace(); 14 let verb = parts.next()?; // `?` returns None if the line is empty 15 match verb { 16 "name" => { 17 let rest = parts.next()?; 18 Some(Command::SetName(rest.to_string())) 19 } 20 "age" => { 21 // let-else: bail out of THIS function cleanly on a bad number 22 let Ok(age) = parts.next()?.parse::() else { 23 return None; 24 }; 25 Some(Command::SetAge(age)) 26 } 27 "quit" => Some(Command::Quit), 28 _ => None, 29 } 30 } 31 32 #[derive(Debug, Default)] 33 struct Profile { 34 name: Option, 35 age: Option, 36 } 37 38 fn main() { 39 let input = [ 40 "name Ada", 41 "age 36", 42 "age not-a-number", 43 "unknown verb", 44 "quit", 45 ]; 46 47 // Feed lines into a queue and drain it with `while let`. 48 let mut queue: VecDeque<&str> = input.iter().copied().collect(); 49 let mut profile = Profile::default(); 50 51 while let Some(line) = queue.pop_front() { 52 // `if let` to react only when parsing succeeds. 53 if let Some(command) = parse_command(line) { 54 match command { 55 Command::SetName(name) => profile.name = Some(name), 56 Command::SetAge(age) => profile.age = Some(age), 57 Command::Quit => { 58 println!("Quit received, stopping."); 59 break; 60 } 61 } 62 } else { 63 println!("Ignoring unrecognized line: {line:?}"); 64 } 65 } 66 67 // `if let` with a tuple pattern: only print once BOTH fields are present. 68 if let (Some(name), Some(age)) = (&profile.name, profile.age) { 69 println!("Profile complete: {name}, age {age}"); 70 } else { 71 println!("Profile incomplete: {profile:?}"); 72 } 73 } ``` Output: ```text 1 Ignoring unrecognized line: "age not-a-number" 2 Ignoring unrecognized line: "unknown verb" 3 Quit received, stopping. 4 Profile complete: Ada, age 36 ``` Notice how `"age 36"` parses, `"age not-a-number"` is rejected by the `let ... else` inside `parse_command` (which returns `None`), and the loop stops cleanly at `"quit"` via `break` — three different control-flow idioms cooperating in one tidy loop. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Concise Control Flow with `if let` and `let ... else`](https://doc.rust-lang.org/book/ch06-03-if-let.html) * [The Rust Reference — `if let` expressions](https://doc.rust-lang.org/reference/expressions/if-expr.html#if-let-expressions) * [The Rust Reference — `let` statements (`let ... else`)](https://doc.rust-lang.org/reference/statements.html#let-statements) * [Rust by Example — `if let`](https://doc.rust-lang.org/rust-by-example/flow_control/if_let.html) and [`while let`](https://doc.rust-lang.org/rust-by-example/flow_control/while_let.html) ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Conditionals](/04-control-flow/00-conditionals/): `if`/`else` as an expression and why Rust has no truthiness * [Loops](/04-control-flow/01-loops/): `for`, `while`, and `loop`, and when to prefer `for` over `while let` * [`match`](/04-control-flow/02-match/): the full pattern-matching expression these tools are sugar for * [`break` and `continue`](/04-control-flow/04-break-continue/): the divergence options for a `let ... else` inside a loop * [Labeled loops](/04-control-flow/05-labeled-loops/) — breaking out of nested `while let` loops * [Functions and the `?` operator](/03-functions/) — the other tool for early returns * [Variables and Mutability](/02-basics/00-variables/): how binding and scope work in Rust * [Ownership](/05-ownership/) — why a binding’s scope matters for borrows and moves *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Greet or fall back [Section titled “Exercise 1: Greet or fall back”](#exercise-1-greet-or-fall-back) **Difficulty:** Easy **Objective:** Practice `if let` with an `else` branch. **Instructions:** Implement `greet` so that `greet(Some("Lin"))` prints `Hello, Lin!` and `greet(None)` prints `Hello, guest!`. ```rust 1 fn greet(user: Option<&str>) { 2 // TODO: use `if let` with an `else` 3 } 4 5 fn main() { 6 greet(Some("Lin")); 7 greet(None); 8 } ``` Solution ```rust 1 fn greet(user: Option<&str>) { 2 if let Some(name) = user { 3 println!("Hello, {name}!"); 4 } else { 5 println!("Hello, guest!"); 6 } 7 } 8 9 fn main() { 10 greet(Some("Lin")); // Hello, Lin! 11 greet(None); // Hello, guest! 12 } ``` ### Exercise 2: Drain a job queue [Section titled “Exercise 2: Drain a job queue”](#exercise-2-drain-a-job-queue) **Difficulty:** Medium **Objective:** Use `while let` to consume a container until it is empty. **Instructions:** Implement `drain_report` so it repeatedly pops the last job off `queue`, prints `processing job N` for each, and finally prints `queue empty`. (`Vec::pop` returns `Option`.) ```rust 1 fn drain_report(mut queue: Vec) { 2 // TODO: use `while let` and `queue.pop()` 3 } 4 5 fn main() { 6 drain_report(vec![1, 2, 3]); 7 } ``` Solution ```rust 1 fn drain_report(mut queue: Vec) { 2 while let Some(job) = queue.pop() { 3 println!("processing job {job}"); 4 } 5 println!("queue empty"); 6 } 7 8 fn main() { 9 drain_report(vec![1, 2, 3]); 10 // processing job 3 11 // processing job 2 12 // processing job 1 13 // queue empty 14 } ``` > The `mut` on the parameter lets the function mutate its own copy of the `Vec`. For more on this, see [Variables and Mutability](/02-basics/00-variables/). ### Exercise 3: Parse an auth header with `let ... else` [Section titled “Exercise 3: Parse an auth header with let ... else”](#exercise-3-parse-an-auth-header-with-let--else) **Difficulty:** Hard **Objective:** Use `let ... else` for two early-return guard clauses, keeping the happy path un-indented. **Instructions:** Implement `extract_user_id` to return `Ok(u64)` when `header` looks like `"Bearer 42"`. If the `"Bearer "` prefix is missing, return `Err("missing Bearer prefix")`. If the remainder is not a valid `u64`, return `Err(format!("invalid id: {token}"))`. Use `str::strip_prefix` (returns `Option`) and `str::parse::()` (returns `Result`). Do **not** nest `if let`s. ```rust 1 fn extract_user_id(header: &str) -> Result { 2 // TODO: two `let ... else` guards, then `Ok(id)` 3 /* ??? */ 4 } 5 6 fn main() { 7 println!("{:?}", extract_user_id("Bearer 42")); 8 println!("{:?}", extract_user_id("Basic 42")); 9 println!("{:?}", extract_user_id("Bearer notanum")); 10 } ``` Solution ```rust 1 fn extract_user_id(header: &str) -> Result { 2 let Some(token) = header.strip_prefix("Bearer ") else { 3 return Err("missing Bearer prefix".to_string()); 4 }; 5 let Ok(id) = token.parse::() else { 6 return Err(format!("invalid id: {token}")); 7 }; 8 Ok(id) 9 } 10 11 fn main() { 12 println!("{:?}", extract_user_id("Bearer 42")); // Ok(42) 13 println!("{:?}", extract_user_id("Basic 42")); // Err("missing Bearer prefix") 14 println!("{:?}", extract_user_id("Bearer notanum")); // Err("invalid id: notanum") 15 } ``` Each guard binds its success value (`token`, then `id`) for the rest of the function, so the final `Ok(id)` reads as the clean, un-nested happy path. This is the same shape as the [`?` operator](/03-functions/), but with custom error messages on each failure. # Break and Continue > break and continue work like JavaScript inside a loop, but Rust's loop is an expression: break value hands a result out, replacing the mutate-a-variable pattern. `break` and `continue` are the two keywords you reach for when you want to *interrupt* the normal flow of a loop. If you’ve written `for`/`while` loops in JavaScript, you already know the basic idea. Rust keeps the familiar parts and adds one genuinely new superpower: a loop can **`break` with a value**, turning the whole loop into an expression that produces a result. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In both TypeScript/JavaScript and Rust, `break` exits the nearest enclosing loop and `continue` skips to the next iteration. The big difference is that Rust’s `loop` is an **expression**, so `break value;` can hand a value back out of the loop, something JavaScript simply cannot do. This single feature replaces a lot of the “declare a `let` outside the loop, mutate it inside” boilerplate you write in JavaScript. > **Note:** This page focuses narrowly on `break`/`continue` themselves and on `break`-with-a-value. The loop constructs they live in (`for`, `while`, `loop`) are covered in [Loops](/04-control-flow/01-loops/), and breaking/continuing across *nested* loops with labels is covered in [Labeled Loops](/04-control-flow/05-labeled-loops/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) ```typescript 1 // Scan log entries: ignore "debug" noise, stop at the first "fatal". 2 interface LogEntry { 3 level: "debug" | "info" | "warn" | "error" | "fatal"; 4 message: string; 5 } 6 7 function collectUntilFatal(entries: LogEntry[]): string[] { 8 const collected: string[] = []; 9 10 for (const entry of entries) { 11 if (entry.level === "debug") continue; // skip noisy debug lines 12 if (entry.level === "fatal") break; // stop scanning entirely 13 collected.push(entry.message); 14 } 15 16 return collected; 17 } 18 19 const entries: LogEntry[] = [ 20 { level: "debug", message: "connecting" }, 21 { level: "warn", message: "slow response" }, 22 { level: "error", message: "timeout" }, 23 { level: "fatal", message: "out of memory" }, 24 { level: "info", message: "never reached" }, 25 ]; 26 27 console.log(collectUntilFatal(entries)); 28 // [ 'slow response', 'timeout' ] ``` **Key points:** * `continue` jumps straight to the next iteration, skipping the rest of the loop body. * `break` leaves the loop entirely; everything after the `fatal` entry is never visited. * `break`/`continue` are **statements** in JavaScript — they don’t produce values. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) ```rust 1 #[derive(Debug)] 2 struct LogEntry { 3 level: String, 4 message: String, 5 } 6 7 /// Scan log entries, skip "debug" lines, and stop at the first "fatal". 8 fn collect_until_fatal(entries: &[LogEntry]) -> Vec { 9 let mut collected = Vec::new(); 10 11 for entry in entries { 12 match entry.level.as_str() { 13 "debug" => continue, // ignore noisy debug lines 14 "fatal" => break, // stop scanning entirely 15 _ => collected.push(entry.message.clone()), 16 } 17 } 18 19 collected 20 } 21 22 fn main() { 23 let entries = vec![ 24 LogEntry { level: "debug".into(), message: "connecting".into() }, 25 LogEntry { level: "warn".into(), message: "slow response".into() }, 26 LogEntry { level: "error".into(), message: "timeout".into() }, 27 LogEntry { level: "fatal".into(), message: "out of memory".into() }, 28 LogEntry { level: "info".into(), message: "never reached".into() }, 29 ]; 30 31 let important = collect_until_fatal(&entries); 32 println!("{:#?}", important); 33 } ``` **Output:** ```text 1 [ 2 "slow response", 3 "timeout", 4 ] ``` **Key points:** * `continue` and `break` work exactly like JavaScript inside a `for` loop. * Here they appear as arms of a `match`, which reads cleanly, but a plain `if`/`else if` works identically. * `break`/`continue` with **no value** is the form allowed in `for` and `while` loops (more on values below). *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### `continue`: skip the rest of this iteration [Section titled “continue: skip the rest of this iteration”](#continue-skip-the-rest-of-this-iteration) `continue` immediately abandons the current iteration and moves to the next one. Anything in the loop body *after* the `continue` is skipped for that pass only. ```rust 1 fn main() { 2 let mut i = 0; 3 let mut kept = String::new(); 4 while i < 10 { 5 i += 1; 6 if i % 3 == 0 { 7 continue; // skip multiples of 3 8 } 9 kept.push_str(&i.to_string()); 10 kept.push(' '); 11 } 12 println!("non-multiples of 3: {}", kept.trim()); 13 } ``` **Output:** ```text 1 non-multiples of 3: 1 2 4 5 7 8 10 ``` > **Warning:** In a `while` loop, `continue` does **not** re-run any “update” step for you; there is no `i++` clause like in a C-style `for`. Notice that `i += 1` is the *first* line of the body above, on purpose. If you put `i += 1` at the *end* and then `continue` before reaching it, the counter never advances and you get an infinite loop. This is a very common JavaScript-to-Rust slip, because JS `for (let i = 0; ...; i++)` runs `i++` even after a `continue`. Rust has no C-style `for` (see [Loops](/04-control-flow/01-loops/)), so you manage the counter yourself. ### `break`: leave the loop entirely [Section titled “break: leave the loop entirely”](#break-leave-the-loop-entirely) `break` exits the nearest enclosing loop. Execution resumes at the first statement *after* the loop. ```rust 1 fn main() { 2 let mut sum = 0; 3 for n in 1..=10 { 4 if n % 2 == 0 { 5 continue; // skip even numbers 6 } 7 if n > 7 { 8 break; // stop once we pass 7 9 } 10 sum += n; 11 } 12 println!("sum of odd numbers <= 7: {}", sum); // 1 + 3 + 5 + 7 = 16 13 } ``` **Output:** ```text 1 sum of odd numbers <= 7: 16 ``` ### `break` with a value — Rust’s superpower [Section titled “break with a value — Rust’s superpower”](#break-with-a-value--rusts-superpower) This is the part with no JavaScript equivalent. Because `loop { ... }` is an **expression**, you can give `break` a value and that value becomes the value of the whole loop: ```rust 1 fn main() { 2 let mut attempts = 0; 3 let result = loop { 4 attempts += 1; 5 if attempts * attempts > 50 { 6 break attempts; // hand this value out of the loop 7 } 8 }; 9 println!("first n where n*n > 50: {}", result); 10 } ``` **Output:** ```text 1 first n where n*n > 50: 8 ``` Read `break attempts;` as “stop looping, and the loop expression evaluates to `attempts`.” In JavaScript you’d declare `let result;` *before* the loop, assign to it inside, and `break;` separately. Rust folds those three steps into one and lets the result be immutable (`let result`, no `mut`). > **Note:** `break value` is only valid in a `loop` (or a labeled block — see [Labeled Loops](/04-control-flow/05-labeled-loops/)). A `for` or `while` loop always evaluates to the unit value `()`, so `break` there must be value-less. The loops page covers *why* `loop` is the construct that returns values. ### Combining both: a retry / first-match pattern [Section titled “Combining both: a retry / first-match pattern”](#combining-both-a-retry--first-match-pattern) A `loop` that `continue`s on failure and `break`s with a value on success is an extremely common idiom. Think “find the first item that parses, otherwise a sentinel”: ```rust 1 fn main() { 2 let inputs = ["abc", "not a number", "42", "99"]; 3 let mut idx = 0; 4 5 let parsed: i32 = loop { 6 if idx >= inputs.len() { 7 break -1; // sentinel: nothing parsed 8 } 9 let candidate = inputs[idx]; 10 idx += 1; 11 match candidate.parse::() { 12 Ok(n) => break n, // success: hand the value back out of the loop 13 Err(_) => continue, // bad input: try the next one 14 } 15 }; 16 17 println!("first parseable value: {}", parsed); 18 } ``` **Output:** ```text 1 first parseable value: 42 ``` > **Tip:** When the sentinel feels hacky, return `Option` instead: `break Some(n)` / `break None`. You’ll see exactly that in the [Real-World Example](#real-world-example) and the exercises below. Often an iterator method like `.find_map(...)` is even cleaner; see [Best Practices](#best-practices). *** ## Key Differences from TypeScript/JavaScript [Section titled “Key Differences from TypeScript/JavaScript”](#key-differences-from-typescriptjavascript) | Concept | TypeScript/JavaScript | Rust | | ----------------------------- | ------------------------------------------- | ----------------------------------------------------- | | `break` exits nearest loop | Yes | Yes | | `continue` skips iteration | Yes | Yes | | `break` returns a value | Not possible | `break value` (in `loop` / labeled block) | | `continue` returns a value | No | No (it’s value-less everywhere) | | Loop as an expression | Statements only | `let x = loop { ... break v; };` | | C-style `for (;;i++)` update | Runs even after `continue` | n/a — no C-style `for`; you advance counters manually | | `break`/`continue` to a label | `break outer;` (label is a statement label) | `break 'outer;` (label is a lifetime-style name) | ### Why does Rust let `break` carry a value? [Section titled “Why does Rust let break carry a value?”](#why-does-rust-let-break-carry-a-value) Because Rust is **expression-oriented**. Almost everything produces a value: `if`/`else` (see [Conditionals](/04-control-flow/00-conditionals/)), `match` (see [Pattern Matching with `match`](/04-control-flow/02-match/)), and blocks all evaluate to something. A `loop` would be the odd one out if it didn’t, so Rust closes the gap: `break value` makes a `loop` produce a result the same way `return value` makes a function produce one. This eliminates the “uninitialized variable mutated inside the loop” pattern that’s so common (and so bug-prone) in JavaScript. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: `break value` in a `for` loop [Section titled “Pitfall 1: break value in a for loop”](#pitfall-1-break-value-in-a-for-loop) A `for` loop can never produce a non-unit value, so attaching a value to its `break` is a compile error. TypeScript developers reach for this because they expect any loop to be assignable. ```rust 1 fn main() { 2 let found = for n in 1..10 { 3 if n == 5 { 4 break n; // does not compile (error E0571: `break` with value from a `for` loop) 5 } 6 }; 7 println!("{:?}", found); 8 } ``` **Real compiler error:** ```text 1 error[E0571]: `break` with value from a `for` loop 2 --> src/main.rs:4:13 3 | 4 2 | let found = for n in 1..10 { 5 | -------------- you can't `break` with a value in a `for` loop 6 3 | if n == 5 { 7 4 | break n; // trying to return a value from a `for` 8 | ^^^^^^^ can only break with a value inside `loop` or breakable block 9 | 10 help: use `break` on its own without a value inside this `for` loop 11 | 12 4 - break n; // trying to return a value from a `for` 13 4 + break; // trying to return a value from a `for` 14 | ``` **Fix:** Use `loop` when you need a value, or restructure with an iterator method like `.find()`: ```rust 1 fn main() { 2 let found = (1..10).find(|&n| n == 5); // Option 3 println!("{:?}", found); // Some(5) 4 } ``` ### Pitfall 2: Mismatched types across multiple `break` values [Section titled “Pitfall 2: Mismatched types across multiple break values”](#pitfall-2-mismatched-types-across-multiple-break-values) Every `break value` in the same `loop` must produce the *same* type. The loop has exactly one result type, just like a function has one return type. ```rust 1 fn main() { 2 let x = loop { 3 break 5; 4 break "done"; // does not compile (error E0308: mismatched types) 5 }; 6 println!("{}", x); 7 } ``` **Real compiler error** (the unreachable second `break` also triggers a warning): ```text 1 warning: unreachable statement 2 --> src/main.rs:4:9 3 | 4 3 | break 5; 5 | ------- any code following this expression is unreachable 6 4 | break "done"; // type mismatch with earlier break 7 | ^^^^^^^^^^^^^ unreachable statement 8 | 9 = note: `#[warn(unreachable_code)]` on by default 10 11 error[E0308]: mismatched types 12 --> src/main.rs:4:15 13 | 14 3 | break 5; 15 | ------- expected because of this `break` 16 4 | break "done"; // type mismatch with earlier break 17 | ^^^^^^ expected integer, found `&str` ``` **Fix:** Make all `break` values share a type (here, both `&str`): ```rust 1 fn main() { 2 let x = loop { 3 if true { 4 break "five"; 5 } 6 break "done"; 7 }; 8 println!("{}", x); // five 9 } ``` ### Pitfall 3: `break`/`continue` outside any loop [Section titled “Pitfall 3: break/continue outside any loop”](#pitfall-3-breakcontinue-outside-any-loop) In JavaScript these are also illegal outside a loop, but the error fires at parse time. Rust gives you a precise, named diagnostic. ```rust 1 fn main() { 2 let n = 5; 3 if n > 3 { 4 break; // does not compile (error E0268: `break` outside of a loop) 5 } 6 } ``` **Real compiler error:** ```text 1 error[E0268]: `break` outside of a loop or labeled block 2 --> src/main.rs:4:9 3 | 4 4 | break; // not inside any loop 5 | ^^^^^ cannot `break` outside of a loop or labeled block ``` > **Note:** The message says “loop **or labeled block**.” Rust does let you `break` out of a labeled *block* (`'name: { ... break 'name value; }`) even though it isn’t a loop — a niche feature covered in [Labeled Loops](/04-control-flow/05-labeled-loops/). A bare `if` block is not breakable. ### Pitfall 4: Expecting `continue` to carry a value [Section titled “Pitfall 4: Expecting continue to carry a value”](#pitfall-4-expecting-continue-to-carry-a-value) `continue` never takes a value — not even in a `loop`. There’s no “continue with X” concept in Rust (or JavaScript). Trying it is a syntax error: ```rust 1 fn main() { 2 let mut total = 0; 3 for n in 1..5 { 4 total += continue 0; // does not compile (syntax error: continue takes no value) 5 } 6 println!("{}", total); 7 } ``` **Real compiler error:** ```text 1 error: expected one of `.`, `;`, `?`, `}`, or an operator, found `0` 2 --> src/main.rs:4:27 3 | 4 4 | total += continue 0; // continue does not take a value 5 | ^ expected one of `.`, `;`, `?`, `}`, or an operator ``` **Fix:** `continue` stands alone. If you wanted to add `0` and move on, just `continue;` (adding `0` is a no-op anyway). *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Reach for `break value` instead of a pre-declared mutable [Section titled “1. Reach for break value instead of a pre-declared mutable”](#1-reach-for-break-value-instead-of-a-pre-declared-mutable) ** JavaScript-style: declare, mutate, break separately** ```rust 1 fn main() { 2 let mut result = 0; // needs `mut`, starts as a meaningless 0 (rustc warns this initial value is never read — which is exactly the point) 3 let mut n = 0; 4 loop { 5 n += 1; 6 if n * n > 50 { 7 result = n; 8 break; 9 } 10 } 11 println!("{}", result); 12 } ``` ** Idiomatic Rust: let the loop be the value** ```rust 1 fn main() { 2 let mut n = 0; 3 let result = loop { 4 n += 1; 5 if n * n > 50 { 6 break n; 7 } 8 }; 9 println!("{}", result); // 8 10 } ``` The second version makes `result` immutable and removes the meaningless initial value. ### 2. Prefer iterator adapters over manual `break`/`continue` when the intent is “filter” or “stop early” [Section titled “2. Prefer iterator adapters over manual break/continue when the intent is “filter” or “stop early””](#2-prefer-iterator-adapters-over-manual-breakcontinue-when-the-intent-is-filter-or-stop-early) `continue` to skip and `break` to stop early often map directly onto `filter`, `take_while`, `find`, and friends. The iterator version states the *intent* and is harder to get wrong. ```rust 1 fn main() { 2 // Imperative: `continue` to skip evens, `break` to stop past 19. 3 let mut sum_imperative = 0; 4 for n in 1..=100 { 5 if n % 2 == 0 { 6 continue; 7 } 8 if n > 19 { 9 break; 10 } 11 sum_imperative += n; 12 } 13 14 // Iterator-idiomatic equivalent. 15 let sum_iter: i32 = (1..=100) 16 .take_while(|&n| n <= 19) 17 .filter(|&n| n % 2 != 0) 18 .sum(); 19 20 println!("imperative = {}, iterator = {}", sum_imperative, sum_iter); 21 assert_eq!(sum_imperative, sum_iter); 22 } ``` **Output:** ```text 1 imperative = 100, iterator = 100 ``` > **Tip:** Use `take_while` for the `break` (stop when a condition stops holding) and `filter` for the `continue` (skip items that don’t match). For “find the first match and return it,” `find` / `find_map` replace the whole `loop { ... break value; }` dance. Reach for explicit `break`/`continue` when the control flow is genuinely irregular (multiple exit conditions, side effects, mutation of outside state). ### 3. Keep the loop body small enough that the exit conditions are obvious [Section titled “3. Keep the loop body small enough that the exit conditions are obvious”](#3-keep-the-loop-body-small-enough-that-the-exit-conditions-are-obvious) A loop with three `break`s and four `continue`s buried in nested `if`s is hard to follow. If you find yourself there, extract the body into a function that returns an enum describing what to do (`Keep`, `Skip`, `Stop`), or switch to an iterator pipeline. ### 4. Don’t forget to advance counters in `while` loops before `continue` [Section titled “4. Don’t forget to advance counters in while loops before continue”](#4-dont-forget-to-advance-counters-in-while-loops-before-continue) As noted above, a `continue` in a `while` loop bypasses any code below it, including a counter increment. Put the increment first, or use a `for` over a range so the iterator advances for you. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small networking utility: given a list of candidate port strings (from a config file, environment variable, CLI args, etc.), find the first one that is both a valid port number and a non-privileged port (>= 1024). This combines `continue` (skip invalid candidates) with `break Some(_)` / `break None` (produce a typed result). ```rust 1 /// Return the first candidate that parses as a valid, non-privileged port. 2 fn first_valid_port(candidates: &[&str]) -> Option { 3 let mut idx = 0; 4 let port = loop { 5 if idx >= candidates.len() { 6 break None; // exhausted all candidates 7 } 8 let raw = candidates[idx]; 9 idx += 1; 10 match raw.parse::() { 11 Ok(p) if p >= 1024 => break Some(p), // valid, non-privileged port 12 _ => continue, // skip invalid / privileged 13 } 14 }; 15 port 16 } 17 18 fn main() { 19 let candidates = ["not-a-port", "80", "8080", "3000"]; 20 println!("{:?}", first_valid_port(&candidates)); // Some(8080) 21 22 let none_valid = ["xyz", "22", "443"]; 23 println!("{:?}", first_valid_port(&none_valid)); // None 24 } ``` **Output:** ```text 1 Some(8080) 2 None ``` Notice how `break Some(8080)` and `break None` give the `loop` a uniform `Option` type, and the whole result flows into an immutable `port`. In TypeScript you’d track a `result` variable and a found-flag, or `return` early from a helper. Rust lets the loop itself be the answer. > **Tip:** This exact “find the first match” shape is what `Iterator::find_map` exists for: `candidates.iter().find_map(|raw| raw.parse::().ok().filter(|&p| p >= 1024))`. Use the explicit `loop` when the iteration also needs side effects or an index you can’t easily express as an adapter. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Repetition with Loops](https://doc.rust-lang.org/book/ch03-05-control-flow.html#repetition-with-loops) — covers `break`, `continue`, and returning values from loops. * [Rust Reference — `break` expressions](https://doc.rust-lang.org/reference/expressions/loop-expr.html#break-expressions) * [Rust Reference — `continue` expressions](https://doc.rust-lang.org/reference/expressions/loop-expr.html#continue-expressions) * [Rust by Example — Loops: `break` and `continue`](https://doc.rust-lang.org/rust-by-example/flow_control/loop.html) ### Related Topics in This Guide [Section titled “Related Topics in This Guide”](#related-topics-in-this-guide) * [Loops](/04-control-flow/01-loops/): `for`, `while`, and `loop`; the constructs `break`/`continue` operate on, and how `loop` returns a value. * [Labeled Loops](/04-control-flow/05-labeled-loops/) — `break`/`continue` to an outer loop with a `'label`, and breaking out of labeled blocks. * [Conditionals](/04-control-flow/00-conditionals/): `if`/`else` as an expression, which pairs with the conditions that trigger `break`/`continue`. * [Match](/04-control-flow/02-match/) — using `match` arms (as in the log-scanning example) to decide between `continue`, `break`, and normal work. * [if let and while let](/04-control-flow/03-if-let-while-let/): concise pattern-matching loop conditions that often remove the need for a manual `break`. * [Functions: Return Values](/03-functions/02-return-values/) — `return` from a function is the function-level analogue of `break` from a loop. * [Ownership](/05-ownership/): why immutable bindings (which `break value` enables) are central to Rust. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Skip and Stop [Section titled “Exercise 1: Skip and Stop”](#exercise-1-skip-and-stop) **Difficulty:** Beginner **Objective:** Practice using `continue` to skip and `break` to terminate within a single `for` loop. **Instructions:** Implement `sum_positive_until_zero`. It should iterate over a slice of `i32`, *ignore* any negative numbers (use `continue`), *stop* completely as soon as it sees a `0` (use `break`), and return the sum of the positive numbers seen before the zero. ```rust 1 fn sum_positive_until_zero(nums: &[i32]) -> i32 { 2 let mut sum = 0; 3 // TODO: loop with continue (skip negatives) and break (stop at 0) 4 sum 5 } 6 7 fn main() { 8 let data = [3, -1, 4, -5, 2, 0, 100]; 9 println!("{}", sum_positive_until_zero(&data)); // expected: 9 10 } ``` Solution ```rust 1 fn sum_positive_until_zero(nums: &[i32]) -> i32 { 2 let mut sum = 0; 3 for &n in nums { 4 if n == 0 { 5 break; // 0 is a terminator 6 } 7 if n < 0 { 8 continue; // ignore negatives 9 } 10 sum += n; 11 } 12 sum 13 } 14 15 fn main() { 16 let data = [3, -1, 4, -5, 2, 0, 100]; 17 println!("{}", sum_positive_until_zero(&data)); // 3 + 4 + 2 = 9 18 } ``` **Output:** ```text 1 9 ``` The `100` after the `0` is never added because `break` ends the loop at the zero. ### Exercise 2: Break with a Value [Section titled “Exercise 2: Break with a Value”](#exercise-2-break-with-a-value) **Difficulty:** Intermediate **Objective:** Use `loop` plus `break value` to compute and return a result without a pre-declared mutable. **Instructions:** Implement `first_square_over(limit)`. Starting from `1`, find the smallest positive integer `n` whose square is strictly greater than `limit`, and return `n`. Use a `loop` and `break n;` — do **not** declare a separate `result` variable. ```rust 1 fn first_square_over(limit: u32) -> u32 { 2 // TODO: use `loop` and `break n;` 3 } 4 5 fn main() { 6 println!("{}", first_square_over(50)); // expected: 8 (8*8 = 64) 7 println!("{}", first_square_over(100)); // expected: 11 (11*11 = 121) 8 } ``` Solution ```rust 1 fn first_square_over(limit: u32) -> u32 { 2 let mut n = 0; 3 loop { 4 n += 1; 5 if n * n > limit { 6 break n; // the loop expression evaluates to n 7 } 8 } 9 } 10 11 fn main() { 12 println!("{}", first_square_over(50)); // 8 13 println!("{}", first_square_over(100)); // 11 14 } ``` **Output:** ```text 1 8 2 11 ``` Because the `loop` is the last expression in the function, its broken-out value is also the function’s return value; no `return` keyword needed. ### Exercise 3: First Valid Result or `None` [Section titled “Exercise 3: First Valid Result or None”](#exercise-3-first-valid-result-or-none) **Difficulty:** Advanced **Objective:** Combine `continue` (skip failures) with `break Some(_)` / `break None` to make a `loop` produce a typed `Option`. **Instructions:** Implement `first_even_parse(candidates: &[&str]) -> Option`. Walk the candidates in order; parse each as `i32`. Skip ones that fail to parse *or* are odd (use `continue`). Return `Some(n)` for the first candidate that parses to an **even** number, or `None` if none qualify. Use a `loop` with an index — not an iterator adapter — so you practice the pattern explicitly. ```rust 1 fn first_even_parse(candidates: &[&str]) -> Option { 2 // TODO: loop over an index; continue on failures/odds; break Some/None 3 } 4 5 fn main() { 6 println!("{:?}", first_even_parse(&["x", "3", "10", "12"])); // Some(10) 7 println!("{:?}", first_even_parse(&["1", "abc", "7"])); // None 8 } ``` Solution ```rust 1 fn first_even_parse(candidates: &[&str]) -> Option { 2 let mut idx = 0; 3 loop { 4 if idx >= candidates.len() { 5 break None; // ran out of candidates 6 } 7 let raw = candidates[idx]; 8 idx += 1; 9 match raw.parse::() { 10 Ok(n) if n % 2 == 0 => break Some(n), // first even wins 11 _ => continue, // unparseable or odd: skip 12 } 13 } 14 } 15 16 fn main() { 17 println!("{:?}", first_even_parse(&["x", "3", "10", "12"])); // Some(10) 18 println!("{:?}", first_even_parse(&["1", "abc", "7"])); // None 19 } ``` **Output:** ```text 1 Some(10) 2 None ``` > **Tip:** The idiomatic one-liner is `candidates.iter().find_map(|s| s.parse::().ok().filter(|n| n % 2 == 0))`. Reach for the explicit `loop` form when you need the index or extra side effects; reach for `find_map` when you don’t. *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * `continue` skips to the next iteration; `break` exits the loop, same as JavaScript. * A `loop` is an **expression**: `break value;` makes the loop evaluate to `value`. * `for`/`while` loops always evaluate to `()`, so their `break` must be value-less. * All `break value` expressions in one loop must share a single type. * `continue` never carries a value. * The “skip with `continue`, return with `break value`” pattern frequently has a cleaner iterator equivalent (`filter`, `take_while`, `find`, `find_map`). **Key syntax** (skeleton, not runnable — `skip`/`done`/`work`/`found`/`value` are placeholders): ```text 1 for x in iter { 2 if skip(x) { continue; } // skip this item 3 if done(x) { break; } // value-less break (for/while) 4 work(x); 5 } 6 7 let answer = loop { 8 if found() { break value; } // break WITH a value (loop only) 9 }; ``` # Labeled Loops > Name an outer loop with 'label to break or continue it from nested loops. Like JavaScript labels, but type-checked in Rust and able to break with a value. When you nest loops, a plain `break` or `continue` only affects the *innermost* loop. **Labeled loops** let you name an outer loop and target it directly, so you can break out of several loops at once or skip to the next iteration of an outer loop. JavaScript has the exact same feature, so the concept will be familiar. But Rust’s version is type-checked, can carry a value, and even works on plain blocks. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **loop label** is an identifier prefixed with an apostrophe (`'outer:`) placed before a `loop`, `while`, or `for`. You then write `break 'outer` or `continue 'outer` to control *that* loop from anywhere inside the nested loops. This is Rust’s clean, structured alternative to flag variables or `goto`, and unlike JavaScript labels, a labeled `loop` can also `break` *with a value*. > **Note:** This page focuses on the **labeling** mechanism. Plain `break`/`continue` (including `break` returning a value from a single `loop`) is covered in [Break and Continue](/04-control-flow/04-break-continue/), and the loop forms themselves in [Loops](/04-control-flow/01-loops/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) JavaScript has supported labeled statements since the beginning. A label is an identifier followed by a colon, and `break`/`continue` can name it: ```typescript 1 // Find the first cell matching a target in a 2-D grid. 2 const grid: number[][] = [ 3 [1, 2, 3], 4 [4, 5, 99], 5 [7, 8, 9], 6 ]; 7 const target = 99; 8 let found: [number, number] | null = null; 9 10 outer: for (let r = 0; r < grid.length; r++) { 11 for (let c = 0; c < grid[r].length; c++) { 12 if (grid[r][c] === target) { 13 found = [r, c]; 14 break outer; // breaks BOTH loops at once 15 } 16 } 17 } 18 19 console.log( 20 found ? `Found ${target} at row ${found[0]}, col ${found[1]}` : "not found", 21 ); 22 // → Found 99 at row 1, col 2 23 24 // `continue` to a label: abandon the current row, move to the next one. 25 const matrix: number[][] = [ 26 [1, 2, -1, 4], 27 [5, 6, 7, 8], 28 ]; 29 30 rows: for (const row of matrix) { 31 let sum = 0; 32 for (const val of row) { 33 if (val < 0) { 34 console.log("negative -> skip rest of row"); 35 continue rows; // jump to the next iteration of `rows` 36 } 37 sum += val; 38 } 39 console.log("row sum:", sum); 40 } 41 // → negative -> skip rest of row 42 // → row sum: 26 ``` Two things to note about JavaScript labels: there is **no leading sigil** (just `outer:`), and a labeled `break` can *never* produce a value. Labels are purely control-flow markers. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same two programs in Rust. The structure is nearly identical: the differences are the leading apostrophe on the label and that we iterate with iterators instead of C-style index loops: ```rust 1 fn main() { 2 // Find the first cell matching a target in a 2-D grid. 3 let grid = [ 4 [1, 2, 3], 5 [4, 5, 99], 6 [7, 8, 9], 7 ]; 8 let target = 99; 9 let mut found = None; 10 11 'rows: for (r, row) in grid.iter().enumerate() { 12 for (c, &val) in row.iter().enumerate() { 13 if val == target { 14 found = Some((r, c)); 15 break 'rows; // breaks BOTH loops at once 16 } 17 } 18 } 19 20 match found { 21 Some((r, c)) => println!("Found {target} at row {r}, col {c}"), 22 None => println!("{target} not found"), 23 } 24 } ``` Real output: ```text 1 Found 99 at row 1, col 2 ``` And `continue` to a label: ```rust 1 fn main() { 2 let matrix = [ 3 [1, 2, -1, 4], 4 [5, 6, 7, 8], 5 [9, -1, 11, 12], 6 ]; 7 8 'rows: for row in &matrix { 9 let mut sum = 0; 10 for &val in row { 11 if val < 0 { 12 println!("Negative found, skipping rest of this row"); 13 continue 'rows; // jump to the next iteration of `'rows` 14 } 15 sum += val; 16 } 17 println!("Row sum: {sum}"); 18 } 19 } ``` Real output: ```text 1 Negative found, skipping rest of this row 2 Row sum: 26 3 Negative found, skipping rest of this row ``` > **Note:** The label is written `'rows` with a leading apostrophe, the same syntax Rust uses for [lifetimes](/05-ownership/04-lifetimes/). They are unrelated concepts that happen to share the apostrophe sigil; a loop label is never a lifetime, and the compiler always knows which one you mean from context. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Defining and targeting a label [Section titled “Defining and targeting a label”](#defining-and-targeting-a-label) A label is an identifier with a leading apostrophe, written immediately before the loop keyword and followed by a colon: ```rust 1 'outer: for i in 0..3 { 2 'inner: for j in 0..3 { 3 // ... 4 } 5 } ``` Inside the nested loops, `break`/`continue` take an *optional* label argument: | Statement | Effect | | ----------------- | ------------------------------------------------------------------ | | `break` | Exits the **innermost** enclosing loop. | | `break 'outer` | Exits the loop labeled `'outer` (and everything nested inside it). | | `continue` | Skips to the next iteration of the **innermost** loop. | | `continue 'outer` | Skips to the next iteration of the loop labeled `'outer`. | Without a label, control flow always targets the closest loop, exactly like JavaScript. The label simply lets you “reach past” inner loops. ### Walking through the grid search [Section titled “Walking through the grid search”](#walking-through-the-grid-search) ```rust 1 'rows: for (r, row) in grid.iter().enumerate() { // (1) 2 for (c, &val) in row.iter().enumerate() { // (2) 3 if val == target { 4 found = Some((r, c)); // (3) 5 break 'rows; // (4) 6 } 7 } 8 } ``` 1. The outer loop is labeled `'rows`. `.enumerate()` pairs each row with its index `r`. 2. The inner loop is **unlabeled**; we never need to target it specifically. 3. We record the coordinates in `found` (a `mut` variable) before leaving. 4. `break 'rows` exits *both* loops in one statement. A plain `break` here would only end the inner loop, and the outer loop would keep scanning the remaining rows. ### Why a label instead of a flag? [Section titled “Why a label instead of a flag?”](#why-a-label-instead-of-a-flag) Without labels, escaping nested loops in many languages requires a boolean flag that you check after the inner loop: ```rust 1 fn main() { 2 let grid = [[1, 2, 3], [4, 5, 99], [7, 8, 9]]; 3 let target = 99; 4 let mut found = None; 5 6 let mut done = false; // extra bookkeeping 7 for (r, row) in grid.iter().enumerate() { 8 for (c, &val) in row.iter().enumerate() { 9 if val == target { 10 found = Some((r, c)); 11 done = true; 12 break; // only breaks the inner loop 13 } 14 } 15 if done { // ...so we re-check out here 16 break; 17 } 18 } 19 20 println!("{found:?}"); 21 } ``` The labeled version removes the flag and the second check entirely. It is shorter, has no extra mutable state, and makes the intent (“leave the whole search”) obvious at the `break` site. ### `continue 'label` vs `break 'label` [Section titled “continue 'label vs break 'label”](#continue-label-vs-break-label) `continue 'rows` does **not** leave the outer loop. It abandons the rest of the *current* outer iteration and advances `'rows` to its next value. In the matrix example, when a negative number appears we stop summing that row and move straight to the next row, which is why `Row sum:` is never printed for rows containing a negative. ### Labeled `loop` can break *with a value* [Section titled “Labeled loop can break with a value”](#labeled-loop-can-break-with-a-value) This is where Rust goes beyond JavaScript. A plain `loop` can return a value via `break value` (see [Break and Continue](/04-control-flow/04-break-continue/)), and that works through a label too. So you can search nested loops and produce the result as an expression: ```rust 1 fn main() { 2 let needle = 7; 3 let haystack = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]; 4 5 // The whole search is an expression that evaluates to the position. 6 let position = 'search: loop { 7 for (r, row) in haystack.iter().enumerate() { 8 for (c, &v) in row.iter().enumerate() { 9 if v == needle { 10 break 'search Some((r, c)); // exits the loop WITH a value 11 } 12 } 13 } 14 break 'search None; // searched everything, found nothing 15 }; 16 17 println!("position = {position:?}"); 18 } ``` Real output: ```text 1 position = Some((2, 0)) ``` Here `'search` labels a `loop`, the inner `for` loops do the scanning, and `break 'search ` jumps out and hands `position` its value. The outer `loop` runs its body exactly once; it exists purely so we have a breakable construct that can carry a value. > **Important:** Only `loop` can `break` with a value. You **cannot** `break 'label some_value` out of a `for` or `while` loop — see the Common Pitfalls section for the exact compiler error. ### Labeled blocks (no loop required) [Section titled “Labeled blocks (no loop required)”](#labeled-blocks-no-loop-required) Since Rust 1.65, you can label a *plain block* and `break` out of it, no loop involved. This is handy for “compute a value with early exits” without a function: ```rust 1 fn classify(score: i32) -> &'static str { 2 let label = 'check: { 3 if score < 0 { 4 break 'check "invalid"; 5 } 6 if score >= 90 { 7 break 'check "A"; 8 } 9 if score >= 80 { 10 break 'check "B"; 11 } 12 "C or below" // the block's final value if no `break` fired 13 }; 14 label 15 } 16 17 fn main() { 18 println!("{}", classify(95)); // A 19 println!("{}", classify(82)); // B 20 println!("{}", classify(50)); // C or below 21 println!("{}", classify(-3)); // invalid 22 } ``` Real output: ```text 1 A 2 B 3 C or below 4 invalid ``` A labeled block uses `break 'label value` to short-circuit, and the block evaluates to that value. JavaScript has no equivalent; its labeled blocks support `break label` but cannot produce a value. *** ## Key Differences from TypeScript/JavaScript [Section titled “Key Differences from TypeScript/JavaScript”](#key-differences-from-typescriptjavascript) | Aspect | JavaScript | Rust | | -------------------------------- | ------------------------------------ | --------------------------------------------------------- | | Label syntax | `outer:` (no sigil) | `'outer:` (leading apostrophe) | | `break label` / `continue label` | Supported | Supported (`break 'label` / `continue 'label`) | | Break **with a value** | Not possible; labels are flow only | A labeled **`loop`** can `break 'label value` | | Label on a plain block | `block: { break block; }` (no value) | `'block: { break 'block value; }` (yields a value, 1.65+) | | Unused label | Silently allowed | Triggers a `warning: unused label` | | Typo’d / unknown label | `SyntaxError: Undefined label` | Compile error `E0426` with a “did you mean” suggestion | | `continue label` to a non-loop | `SyntaxError` | Compile error | The headline differences: Rust requires the apostrophe, treats labels as type-checked control flow (so a wrong name is a compile error, not a runtime surprise), warns when a label is unused, and lets a labeled `loop` carry a value out, something JavaScript labels can never do. > **Tip:** Conventionally Rust labels describe what the loop iterates over (`'rows`, `'pixels`, `'retry`, `'search`) rather than generic `'outer`/`'inner`. A descriptive name makes `break 'rows` read like a sentence. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting the leading apostrophe [Section titled “Pitfall 1: Forgetting the leading apostrophe”](#pitfall-1-forgetting-the-leading-apostrophe) JavaScript labels have no sigil, so it is natural to write `outer:` in Rust. The compiler rejects it: ```rust 1 fn main() { 2 outer: for i in 0..3 { // does not compile (error: malformed loop label) 3 for j in 0..3 { 4 if i + j == 2 { break outer; } 5 } 6 } 7 } ``` The real error (abridged): ```text 1 error: malformed loop label 2 --> src/main.rs:2:5 3 | 4 2 | outer: for i in 0..3 { // does not compile (error: malformed loop label) 5 | ^^^^^ 6 | 7 help: use the correct loop label format 8 | 9 2 | 'outer: for i in 0..3 { // does not compile (error: malformed loop label) 10 | + ``` The fix is exactly what the compiler suggests: add the `'`, giving `'outer: for ...` and `break 'outer`. ### Pitfall 2: Misspelling the label [Section titled “Pitfall 2: Misspelling the label”](#pitfall-2-misspelling-the-label) A label name that doesn’t exist is a compile-time error (`E0426`), not a runtime failure as in some languages. The compiler even suggests the nearest match: ```rust 1 fn main() { 2 'outer: for i in 0..3 { 3 for j in 0..3 { 4 if i + j == 2 { 5 break 'outr; // does not compile (error[E0426]: use of undeclared label `'outr`) 6 } 7 } 8 } 9 } ``` The real error (abridged): ```text 1 error[E0426]: use of undeclared label `'outr` 2 --> src/main.rs:5:23 3 | 4 2 | 'outer: for i in 0..3 { 5 | ------ a label with a similar name is reachable 6 ... 7 5 | break 'outr; // typo: label doesn't exist 8 | ^^^^^ undeclared label `'outr` 9 | help: try using similarly named label: `'outer` ``` ### Pitfall 3: Trying to `break` with a value out of a labeled `for`/`while` [Section titled “Pitfall 3: Trying to break with a value out of a labeled for/while”](#pitfall-3-trying-to-break-with-a-value-out-of-a-labeled-forwhile) Because plain `loop` is the only construct that returns a value, attempting `break 'label value` from a `for` (or `while`) is rejected with `E0571`: ```rust 1 fn main() { 2 let x = 'outer: for i in 0..5 { 3 for j in 0..5 { 4 if i * j > 6 { 5 break 'outer i * j; // does not compile (error[E0571]) 6 } 7 } 8 }; 9 println!("{x:?}"); 10 } ``` The real error (abridged): ```text 1 error[E0571]: `break` with value from a `for` loop 2 --> src/main.rs:5:17 3 | 4 2 | let x = 'outer: for i in 0..5 { 5 | --------------------- you can't `break` with a value in a `for` loop 6 ... 7 5 | break 'outer i * j; 8 | ^^^^^^^^^^^^^^^^^^ can only break with a value inside `loop` or breakable block 9 help: use `break` on its own without a value inside this `for` loop ``` **Fixes:** either (a) set a `mut` variable before a plain `break 'outer`, or (b) restructure as a labeled `loop` (which *can* carry a value), or (c) use a labeled block. The Real-World Example below uses approach (b). ### Pitfall 4: A label you never target (dead label) [Section titled “Pitfall 4: A label you never target (dead label)”](#pitfall-4-a-label-you-never-target-dead-label) If you label a loop but every `break`/`continue` inside is unlabeled, the label does nothing, and Rust warns you, which often reveals a bug (you *meant* to write `break 'rows`): ```rust 1 fn main() { 2 'outer: for i in 0..3 { // label defined but never targeted 3 for j in 0..3 { 4 if i + j == 2 { 5 break; // breaks only the inner loop 6 } 7 } 8 } 9 } ``` The real warning: ```text 1 warning: unused label 2 --> src/main.rs:2:5 3 | 4 2 | 'outer: for i in 0..3 { // label defined but never targeted 5 | ^^^^^^ 6 | 7 = note: `#[warn(unused_labels)]` on by default ``` ### Pitfall 5: Reaching for labels when an iterator method is clearer [Section titled “Pitfall 5: Reaching for labels when an iterator method is clearer”](#pitfall-5-reaching-for-labels-when-an-iterator-method-is-clearer) Labeled loops are great for genuinely nested control flow, but a flat search over a single sequence is usually better expressed with iterator adapters. Prefer `.find()`/`.position()`/`.any()` (covered in [Loops](/04-control-flow/01-loops/) and the collections section) when there is no real nesting; they are shorter and harder to get wrong than a hand-rolled labeled loop. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Name labels after what they iterate [Section titled “1. Name labels after what they iterate”](#1-name-labels-after-what-they-iterate) `'rows`, `'tiles`, `'retry`, `'connections` read far better at the `break` site than `'outer`/`'l1`. The label is documentation: `continue 'rows` should tell the reader exactly what is being skipped. ### 2. Use a labeled `loop` (not `for`) when you need a value out [Section titled “2. Use a labeled loop (not for) when you need a value out”](#2-use-a-labeled-loop-not-for-when-you-need-a-value-out) If the goal of the search is to produce a result, model it as `let result = 'name: loop { ...; break 'name value; };`. This keeps the result as a single immutable binding instead of a `mut` flag mutated across iterations. ### 3. Only label the loop you actually target [Section titled “3. Only label the loop you actually target”](#3-only-label-the-loop-you-actually-target) Adding a label to a loop you never `break`/`continue` to is noise, and Rust warns about it. Label exactly the loop(s) that need targeting; leave the rest unlabeled. ### 4. Don’t nest deeper than you can read [Section titled “4. Don’t nest deeper than you can read”](#4-dont-nest-deeper-than-you-can-read) Three or more nested labeled loops are a smell. Consider extracting the inner work into a function that returns `Option`/`Result` and using `?` or an early `return`, which often removes the need for labels altogether. (Early `return` from a helper is frequently the cleanest “break out of everything”.) ### 5. Reach for iterators first for non-nested logic [Section titled “5. Reach for iterators first for non-nested logic”](#5-reach-for-iterators-first-for-non-nested-logic) As in Pitfall 5: a label on a single loop scanning one collection usually wants to be `.find()`/`.any()`/`.filter()` instead. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) ### Connection failover with bounded retries [Section titled “Connection failover with bounded retries”](#connection-failover-with-bounded-retries) A common production pattern: try a list of endpoints, and for each, retry a few times before moving on. The moment any attempt succeeds, abandon *all* remaining endpoints and attempts. A labeled `loop` returning a value expresses this cleanly: ```rust 1 #[derive(Debug)] 2 struct Endpoint { 3 name: &'static str, 4 // For the demo: the attempt number on which this endpoint starts working. 5 // 0 means it never succeeds. 6 succeeds_on_attempt: u32, 7 } 8 9 fn try_connect(ep: &Endpoint, attempt: u32) -> Result { 10 if ep.succeeds_on_attempt != 0 && attempt >= ep.succeeds_on_attempt { 11 Ok(format!("connected to {} on attempt {attempt}", ep.name)) 12 } else { 13 Err(format!("{} refused (attempt {attempt})", ep.name)) 14 } 15 } 16 17 fn main() { 18 let endpoints = [ 19 Endpoint { name: "primary", succeeds_on_attempt: 0 }, // never succeeds 20 Endpoint { name: "replica", succeeds_on_attempt: 2 }, // works on the 2nd try 21 Endpoint { name: "fallback", succeeds_on_attempt: 1 }, 22 ]; 23 const MAX_ATTEMPTS: u32 = 3; 24 25 // The whole failover dance is one expression yielding the connection. 26 let connection = 'endpoints: loop { 27 for ep in &endpoints { 28 for attempt in 1..=MAX_ATTEMPTS { 29 match try_connect(ep, attempt) { 30 Ok(conn) => break 'endpoints Some(conn), // success: leave everything 31 Err(e) => { 32 eprintln!("warn: {e}"); 33 if attempt == MAX_ATTEMPTS { 34 eprintln!("giving up on {}, trying next endpoint", ep.name); 35 } 36 } 37 } 38 } 39 } 40 break 'endpoints None; // every endpoint exhausted 41 }; 42 43 match connection { 44 Some(conn) => println!("OK: {conn}"), 45 None => println!("ERROR: all endpoints failed"), 46 } 47 } ``` Real output: ```text 1 warn: primary refused (attempt 1) 2 warn: primary refused (attempt 2) 3 warn: primary refused (attempt 3) 4 giving up on primary, trying next endpoint 5 warn: replica refused (attempt 1) 6 OK: connected to replica on attempt 2 ``` The `break 'endpoints Some(conn)` punches straight out of the attempt loop *and* the endpoint loop *and* the outer `loop`, delivering the successful connection as `connection` in one move. Without the label this would need a flag checked after each loop level, or the whole thing extracted into a helper that `return`s early. > **Tip:** In real networking code each retry would be spaced out with a backoff delay and `try_connect` would be `async`. The control-flow shape — labeled loop, break-with-value on success — stays exactly the same; async control flow is covered later in the guide. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Loop Labels to Disambiguate Between Multiple Loops](https://doc.rust-lang.org/book/ch03-05-control-flow.html#loop-labels-to-disambiguate-between-multiple-loops) * [Rust Reference — Loop labels](https://doc.rust-lang.org/reference/expressions/loop-expr.html#loop-labels) * [Rust Reference — Labelled block expressions](https://doc.rust-lang.org/reference/expressions/loop-expr.html#labelled-block-expressions) * [MDN — `label` statement (JavaScript)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/label) ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Loops](/04-control-flow/01-loops/): `for`, `while`, and `loop`; `break` returning a value from a single `loop`; no C-style `for`. * [break / continue](/04-control-flow/04-break-continue/): the unlabeled forms these statements build on. * [match](/04-control-flow/02-match/): exhaustive pattern matching, often pairs with labeled loops in search code. * [if let / while let](/04-control-flow/03-if-let-while-let/) — concise pattern matching that can replace some labeled-loop bookkeeping. * [Conditionals](/04-control-flow/00-conditionals/): `if` as an expression; Rust has no truthiness. * [Section 04 overview](/04-control-flow/) * Earlier groundwork: [Getting Started](/01-getting-started/), [Basics](/02-basics/), and the [Introduction](/00-introduction/). * Next up: [Ownership](/05-ownership/) — where the apostrophe shows up again as a *lifetime* (a different concept). *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: First common element [Section titled “Exercise 1: First common element”](#exercise-1-first-common-element) **Difficulty:** Beginner **Objective:** Use a labeled loop to break out of two nested loops at once. **Instructions:** Implement `first_common`, which returns the first element of `a` that also appears in `b` (scanning `a` in order), or `None` if there is no overlap. Break out of both loops as soon as you find a match. ```rust 1 fn first_common(a: &[i32], b: &[i32]) -> Option { 2 // TODO: scan `a`; for each element scan `b`; on a match, break out of BOTH loops. 3 /* ??? */ 4 } 5 6 fn main() { 7 println!("{:?}", first_common(&[1, 2, 3, 4], &[9, 8, 3, 1])); // Some(1) 8 println!("{:?}", first_common(&[1, 2], &[3, 4])); // None 9 } ``` Solution Because a `for` loop cannot `break` with a value, record the hit in a `mut` variable and then break the labeled loop: ```rust 1 fn first_common(a: &[i32], b: &[i32]) -> Option { 2 let mut result = None; 3 'outer: for &x in a { 4 for &y in b { 5 if x == y { 6 result = Some(x); 7 break 'outer; // leave both loops; value is returned below 8 } 9 } 10 } 11 result 12 } 13 14 fn main() { 15 println!("{:?}", first_common(&[1, 2, 3, 4], &[9, 8, 3, 1])); // Some(1) 16 println!("{:?}", first_common(&[1, 2], &[3, 4])); // None 17 } ``` Real output: ```text 1 Some(1) 2 None ``` > **Note:** The answer is `Some(1)`, not `Some(3)`: we scan `a` in order, and `1` (the first element of `a`) is present in `b`, so it matches before we ever reach `3`. ### Exercise 2: Skip invalid rows with `continue 'label` [Section titled “Exercise 2: Skip invalid rows with continue 'label”](#exercise-2-skip-invalid-rows-with-continue-label) **Difficulty:** Intermediate **Objective:** Use `continue` to a label to abandon a whole outer iteration. **Instructions:** Implement `sum_valid_rows`. Sum every row of the grid, but if a row contains a `0`, treat the entire row as invalid and exclude it from the total. Use `continue 'rows` so that hitting a `0` immediately skips the rest of that row. ```rust 1 fn sum_valid_rows(grid: &[[i32; 3]]) -> i32 { 2 // TODO: a labeled outer loop; `continue 'rows` when you see a 0. 3 /* ??? */ 4 } 5 6 fn main() { 7 let grid = [ 8 [1, 2, 3], // valid -> 6 9 [4, 0, 6], // has a 0 -> discarded 10 [7, 8, 9], // valid -> 24 11 ]; 12 println!("{}", sum_valid_rows(&grid)); // 30 13 } ``` Solution ```rust 1 fn sum_valid_rows(grid: &[[i32; 3]]) -> i32 { 2 let mut total = 0; 3 'rows: for row in grid { 4 let mut row_sum = 0; 5 for &v in row { 6 if v == 0 { 7 continue 'rows; // discard this row entirely, move to the next 8 } 9 row_sum += v; 10 } 11 total += row_sum; // only reached if no 0 was found in the row 12 } 13 total 14 } 15 16 fn main() { 17 let grid = [ 18 [1, 2, 3], 19 [4, 0, 6], 20 [7, 8, 9], 21 ]; 22 println!("{}", sum_valid_rows(&grid)); // 30 23 } ``` Real output: ```text 1 30 ``` The key is that `continue 'rows` skips the `total += row_sum;` line for the discarded row, because it jumps directly to the next iteration of the outer loop. ### Exercise 3: 3-D search with a value-returning labeled loop [Section titled “Exercise 3: 3-D search with a value-returning labeled loop”](#exercise-3-3-d-search-with-a-value-returning-labeled-loop) **Difficulty:** Advanced **Objective:** Combine three nested loops with a labeled `loop` that breaks *with a value*. **Instructions:** Implement `find_in_cube`, which searches a 2x2x2 cube of integers and returns the `(x, y, z)` coordinates of the first cell equal to `target`, or `None`. Model the search as a labeled `loop` so you can `break 'search Some((x, y, z))` directly with the coordinates. ```rust 1 fn find_in_cube(cube: &[[[i32; 2]; 2]; 2], target: i32) -> Option<(usize, usize, usize)> { 2 // TODO: 'search: loop { for x { for y { for z { ... break 'search Some(...) } } } break 'search None } 3 /* ??? */ 4 } 5 6 fn main() { 7 let cube = [ 8 [[0, 1], [2, 3]], 9 [[4, 5], [6, 7]], 10 ]; 11 println!("{:?}", find_in_cube(&cube, 6)); // Some((1, 1, 0)) 12 println!("{:?}", find_in_cube(&cube, 99)); // None 13 } ``` Solution ```rust 1 fn find_in_cube(cube: &[[[i32; 2]; 2]; 2], target: i32) -> Option<(usize, usize, usize)> { 2 'search: loop { 3 for (x, plane) in cube.iter().enumerate() { 4 for (y, row) in plane.iter().enumerate() { 5 for (z, &v) in row.iter().enumerate() { 6 if v == target { 7 break 'search Some((x, y, z)); // out of all three loops, with the coords 8 } 9 } 10 } 11 } 12 break 'search None; // searched the whole cube, found nothing 13 } 14 } 15 16 fn main() { 17 let cube = [ 18 [[0, 1], [2, 3]], 19 [[4, 5], [6, 7]], 20 ]; 21 println!("{:?}", find_in_cube(&cube, 6)); // Some((1, 1, 0)) 22 println!("{:?}", find_in_cube(&cube, 99)); // None 23 } ``` Real output: ```text 1 Some((1, 1, 0)) 2 None ``` Wrapping the three `for` loops in a single `'search: loop` gives you one breakable construct that can carry the `Option` straight out of all the nesting: no `mut` flag, no post-loop bookkeeping. *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * Labels are identifiers with a leading apostrophe (`'rows:`) placed before `loop`, `while`, or `for`. * `break 'label` exits that loop (and everything nested in it); `continue 'label` skips to its next iteration. * A labeled **`loop`** can `break 'label value`; JavaScript labels can never produce a value. * Labeled **blocks** (1.65+) let you `break` out of a plain block with a value. * The compiler warns on unused labels (`unused_labels`) and rejects misspelled (`E0426`), malformed, and value-breaking-`for` (`E0571`) labels at compile time. **Key differences from JavaScript:** the apostrophe sigil, type-checked labels (errors not runtime surprises), the unused-label warning, and value-returning labeled `loop`s/blocks. # Rust Ownership Explained > Rust ownership replaces garbage collection: stack vs heap, the three rules, borrowing, lifetimes, move/copy/clone, Rc/Arc, and Drop, mapped from TypeScript. **Ownership** is the single biggest idea that separates Rust from garbage-collected TypeScript and JavaScript, and the reason a Rust program can be memory-safe with no garbage collector and no manual `free`. Instead of a runtime that periodically scans for unreachable objects, the Rust compiler tracks, at *compile time*, exactly who owns each value and inserts cleanup at precisely the right moment. This section builds that model from the ground up: the **stack/heap** memory layout it rests on, the three **ownership rules**, **borrowing** with `&` and `&mut`, **lifetimes**, **move/copy/clone** semantics, **reference counting** for shared ownership, and **Drop/RAII** for deterministic cleanup. > **Note:** This is the steepest part of the climb for a TypeScript/JavaScript developer, and the most rewarding. Almost everything that feels strange about Rust at first (why you can’t use a variable after passing it, why the compiler talks about “borrows,” why `&` is everywhere) comes from this one system. Once it clicks, the rest of Rust gets dramatically easier. *** ## What You’ll Learn [Section titled “What You’ll Learn”](#what-youll-learn) * Where values live — the **stack** vs the **heap** — and why Rust makes this visible when TypeScript/JavaScript hides it behind a GC * The **three ownership rules** that replace garbage collection: one owner per value, move on assignment, drop at end of scope * How to **borrow** data with `&` (shared/immutable references) without copying or transferring ownership, and how the borrow checker prevents dangling references * How `&mut` works and the **one-mutable-XOR-many-shared** rule that prevents data races at compile time * Why a value is **moved**, **copied**, or **cloned**, and how to control which one happens (`Copy` vs `Clone`) * What **lifetimes** (`'a`) are, why they exist, and when **elision** lets you omit the annotations entirely * How to share a single value among several owners with `Rc` (single-threaded) and `Arc` (thread-safe) * How the **`Drop` trait** and **RAII** give you deterministic, leak-resistant cleanup: the opposite of JavaScript’s GC and `FinalizationRegistry` *** ## Topics [Section titled “Topics”](#topics) Read these in order; each one builds on the last. The numbered order matches the navigation links inside the files. | # | Topic | What it covers | | - | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | [Stack and Heap](/05-ownership/00-stack-heap/) | The stack vs heap memory model: what lives where, fixed-size handles vs heap buffers, versus JavaScript’s GC-managed heap and value/reference split, and why it matters in Rust. | | 2 | [The Three Ownership Rules](/05-ownership/01-ownership-rules/) | Each value has exactly one **owner**; ownership **moves** on assignment and when passed to a function; the value is **dropped** at the end of the owner’s scope. | | 3 | [Borrowing and References](/05-ownership/02-borrowing/) | Shared/immutable borrows with `&`; how Rust references differ from JavaScript object references; the borrow checker and how dangling references are prevented. | | 4 | [Mutable References](/05-ownership/03-mutable-references/) | `&mut`; the one-mutable-XOR-many-shared rule; non-lexical lifetimes; how data races are ruled out at compile time. | | 5 | [Lifetimes](/05-ownership/04-lifetimes/) | Lifetime annotations (`'a`), why they exist, and how they relate input and output lifetimes in function signatures and structs. | | 6 | [Lifetime Elision](/05-ownership/05-lifetime-elision/) | The three elision rules, when annotations can be omitted, and the common patterns that “just work” without `'a`. | | 7 | [Move, Copy, and Clone](/05-ownership/06-move-copy-clone/) | Move semantics vs JavaScript’s reference copy; the `Copy` trait (cheap stack duplicates); `Clone` (explicit deep copy); exactly when each happens. | | 8 | [Reference Counting (`Rc`/`Arc`)](/05-ownership/07-reference-counting/) | `Rc` (single-thread) and `Arc` (thread-safe) for shared ownership; strong counts. A light intro; the full treatment is in [Section 10](/10-smart-pointers/). | | 9 | [The Drop Trait and RAII](/05-ownership/08-drop-trait/) | RAII and deterministic, scope-based cleanup; the `Drop` trait; drop order; `std::mem::drop`; versus JavaScript GC / `FinalizationRegistry`. | *** ## Learning Objectives [Section titled “Learning Objectives”](#learning-objectives) By the end of this section, a TypeScript/JavaScript developer should be able to: 1. Explain, in plain terms, where a value lives (stack vs heap) and why that determines whether assignment **moves** or **copies** it. 2. State the three ownership rules and trace, by reading the code, exactly when each value is dropped. 3. Choose deliberately between **borrowing**, **cloning**, and **shared ownership** for a given design, and reach for `.clone()` intentionally rather than reflexively. 4. Read and write `&` and `&mut` references that satisfy the borrow checker, and apply the one-mutable-XOR-many-shared rule. 5. Add lifetime annotations (`'a`) only where the compiler genuinely needs them, and recognize where the three elision rules let you omit them. 6. Use `Rc`/`Arc` to model shared ownership and inspect a strong count. 7. Use the `Drop` trait and RAII (and `std::mem::drop` for early cleanup) to manage resources deterministically. 8. Recognize and fix the common borrow-checker errors: `E0382` (use after move), `E0499` (two `&mut`), `E0502` (`&` and `&mut` together), `E0515`/`E0597` (returning/holding a dangling reference). *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) This section assumes you have completed: * **[Section 03: Functions](/03-functions/)**: typed parameters and return values. Ownership crosses **every** function boundary, so the difference between an owned parameter (`String`) and a borrowed one (`&str`) is central here. * **[Section 04: Control Flow](/04-control-flow/)**: scopes and blocks. A value is dropped at the closing `}` of its scope, so knowing exactly where scopes begin and end is what makes drop timing predictable. If immutability-by-default (`let` vs `let mut`) or the stack/heap idea feels unfamiliar, revisit **[Section 02 — Variables and Mutability](/02-basics/00-variables/)** first. Ownership builds directly on it. > **Tip:** The apostrophe in a lifetime (`'a`) is the same sigil Rust uses for loop **labels** (`'outer:`) in [Section 04 — Labeled Loops](/04-control-flow/05-labeled-loops/). They are unrelated concepts that merely share punctuation; the compiler always knows which one you mean from context. *** ## Estimated Time [Section titled “Estimated Time”](#estimated-time) This is the most important — and most demanding — section in the guide, so budget extra time and work through every example by hand. * **Reading:** 5-6 hours * **Hands-on Practice:** 4-5 hours * **Exercises:** 3-5 hours * **Total:** 12-16 hours > **Tip:** Do not rush this section. The recommended order is the list order above: stack/heap → ownership rules → borrowing → mutable references → lifetimes → lifetime elision → move/copy/clone → reference counting → Drop. Start with [Stack and Heap](/05-ownership/00-stack-heap/): the memory model it builds is the foundation everything else rests on. If a borrow-checker error frustrates you, that frustration *is* the learning — read the compiler’s suggestion, it is unusually good at proposing the fix. *** ## Frequently asked questions [Section titled “Frequently asked questions”](#frequently-asked-questions) ### Why does the compiler say a value was “moved”? [Section titled “Why does the compiler say a value was “moved”?”](#why-does-the-compiler-say-a-value-was-moved) Assigning a non-`Copy` value or passing it to a function transfers ownership, leaving the original binding unusable. Borrow it with `&` to lend access instead, or call `.clone()` when you genuinely need a second independent copy. See [The Three Ownership Rules](/05-ownership/01-ownership-rules/). ### What is the difference between `&` and `&mut`? [Section titled “What is the difference between & and \&mut?”](#what-is-the-difference-between--and-mut) `&T` is a shared, read-only borrow; `&mut T` is an exclusive, writable borrow. The rule is one `&mut` XOR any number of `&` at the same time, which is how Rust rules out data races at compile time. See [Borrowing](/05-ownership/02-borrowing/). ### When do I need `Rc` or `Arc`? [Section titled “When do I need Rc or Arc?”](#when-do-i-need-rc-or-arc) When one value genuinely needs several owners, such as a node pointed to by multiple parents. `Rc` is for a single thread and `Arc` is thread-safe. For single ownership, plain ownership or `&` references are cheaper. See [Reference Counting](/05-ownership/07-reference-counting/). # Stack and Heap: Where Your Data Lives > Where Rust values live: fixed-size data on the stack, growable data like String and Vec on the heap — what JS hides behind its GC, Rust makes explicit. Before you can understand Rust’s ownership system, you need a mental model of **where** values live in memory: the **stack** or the **heap**. In TypeScript/JavaScript a garbage collector hides this distinction from you completely. In Rust the distinction is front and center: it is the reason ownership exists at all. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) The **stack** is a fast, fixed-size region where values of a known, fixed size are stored and freed automatically as functions enter and exit. The **heap** is a larger, flexible region for values whose size can grow or is not known at compile time (like a growable string). In TypeScript/JavaScript every object lives on a garbage-collected heap and you never think about it; in Rust, knowing what lives where explains *moves*, *borrows*, and why there is no garbage collector. > **Note:** This file covers the **memory model**: what the stack and heap are, what lives where, and why it matters. The *rules* that govern this memory (one owner, move-on-assign, drop-at-scope-end) are covered in [The Three Ownership Rules](/05-ownership/01-ownership-rules/), and the mechanics of moving versus copying live in [Move, Copy, and Clone](/05-ownership/06-move-copy-clone/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In JavaScript, you never allocate or free memory yourself. Primitives feel like values; objects, arrays, and functions are handled by reference. A garbage collector reclaims anything you stop using. ```typescript 1 // TypeScript/JavaScript — the engine decides where everything goes 2 const age = 30; // a number (always IEEE-754 f64 under the hood) 3 const name = "Grace Hopper"; // a string 4 const scores = [90, 85, 100]; // an array object 5 6 // Assignment of an object copies the *reference*, not the object itself. 7 const a = { count: 1 }; 8 const b = a; // b points at the SAME object as a 9 b.count = 99; 10 console.log(a.count); // 99 — they are the same object 11 12 // Primitives behave as if copied by value. 13 let x = 5; 14 let y = x; // y is an independent copy 15 y = 6; 16 console.log(x, y); // 5 6 ``` **Key points:** * You never write `malloc`/`free`; the V8 garbage collector (GC) reclaims memory when nothing references it anymore. * Primitives (`number`, `boolean`, `string` handles, `null`, `undefined`) are passed and assigned **by value**. * Objects, arrays, and functions are passed and assigned **by reference**: `b = a` makes `a` and `b` aliases of one heap object. * The cost: GC pauses, extra memory headroom, and non-deterministic cleanup timing. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust makes the same program work without a garbage collector. The size and location of every value is decided at compile time, and cleanup happens deterministically when a value goes out of scope. ```rust 1 fn main() { 2 // --- Lives entirely on the stack: fixed, known size --- 3 let age: i32 = 30; // 4 bytes 4 let price: f64 = 19.99; // 8 bytes 5 let is_active: bool = true; // 1 byte 6 let point: (i32, i32) = (3, 4); // 8 bytes (two i32s, inline) 7 let scores: [i32; 3] = [90, 85, 100]; // 12 bytes (three i32s, inline) 8 9 // --- Uses the heap: size can grow / is not known at compile time --- 10 let name: String = String::from("Grace Hopper"); // text bytes on the heap 11 let numbers: Vec = vec![1, 2, 3, 4, 5]; // elements on the heap 12 13 println!("age = {age}"); 14 println!("point = {point:?}"); 15 println!("name = {name}"); 16 println!("numbers = {numbers:?}"); 17 } ``` **Output (verified):** ```text 1 age = 30 2 point = (3, 4) 3 name = Grace Hopper 4 numbers = [1, 2, 3, 4, 5] ``` **Key points:** * Numbers, `bool`, `char`, fixed-size tuples, and fixed-size arrays live **on the stack**. * `String` and `Vec` store a small **handle** on the stack that points to a buffer **on the heap**. * There is no garbage collector. When a value’s owner goes out of scope, its heap memory is freed immediately and deterministically (see [The Drop Trait and RAII](/05-ownership/08-drop-trait/)). *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What the stack is [Section titled “What the stack is”](#what-the-stack-is) The **stack** is a region of memory that works exactly like the data-structure of the same name: last-in, first-out. Every time a function is called, a **stack frame** is pushed holding that function’s local variables. When the function returns, its entire frame is popped in one cheap operation. The CPU tracks the top of the stack in a register, so “allocating” a stack value is just moving a pointer, essentially free. The catch: the stack only works for data whose size is **known at compile time**. The compiler must know how many bytes each local needs in order to lay out the frame. The stack is also small (commonly a few megabytes for the main thread), so it is for short-lived, fixed-size values. We can observe stack values sitting next to each other in memory: ```rust 1 fn main() { 2 let a: i32 = 1; 3 let b: i32 = 2; 4 let c: i32 = 3; 5 6 // `{:p}` formats a reference as a pointer (hex address). 7 println!("a is at {:p}", &a); 8 println!("b is at {:p}", &b); 9 println!("c is at {:p}", &c); 10 } ``` **Output (one real run, your addresses will differ):** ```text 1 a is at 0x16d4e1b44 2 b is at 0x16d4e1b48 3 c is at 0x16d4e1b4c ``` Each `i32` sits 4 bytes from the next; they are packed tightly into the current stack frame. > **Warning:** Do not read meaning into the exact addresses or whether they ascend or descend. The actual values depend on the platform, the optimization level, and the OS, and the compiler is free to reorder or even eliminate variables. The point is only that stack locals are cheap, contiguous, fixed-size slots. ### What the heap is [Section titled “What the heap is”](#what-the-heap-is) The **heap** is a larger, general-purpose region for data whose size can change at runtime or is not known up front. Asking the allocator for heap memory (“allocating”) and giving it back (“freeing”) is more expensive than a stack push/pop because the allocator has to find a suitable free block and track it. A `String` is the textbook example. Its growable text cannot live on the stack because you might `push_str` more characters later. So a `String` is really **two parts**: 1. A fixed-size **handle on the stack**: a pointer to the heap buffer, a length, and a capacity. 2. The **actual bytes on the heap**, which the pointer points to. ```rust 1 fn main() { 2 let greeting = String::from("hi"); 3 4 // The String *handle* is a stack local. 5 println!("the String handle (stack) is at {:p}", &greeting); 6 // Its text bytes live somewhere else entirely — on the heap. 7 println!("its heap buffer starts at {:p}", greeting.as_ptr()); 8 } ``` **Output (one real run):** ```text 1 the String handle (stack) is at 0x16d4e1c68 2 its heap buffer starts at 0x600000d9c060 ``` Notice the two addresses are in completely different regions of memory: the handle is on the stack (`0x16d4...`), the buffer is on the heap (`0x6000...`). This split is the single most important picture to keep in your head for the rest of this section. ```text 1 STACK HEAP 2 ┌──────────────┐ ┌───────────────────┐ 3 │ greeting │ │ 'h' 'i' │ 4 │ ptr ───────┼──────────▶ │ (the text bytes) │ 5 │ len = 2 │ └───────────────────┘ 6 │ cap = 2 │ 7 └──────────────┘ ``` ### The size of a handle is fixed [Section titled “The size of a handle is fixed”](#the-size-of-a-handle-is-fixed) Even though the *contents* of a `String` or `Vec` can grow, the *handle* on the stack is always the same fixed size. We can prove it: ```rust 1 fn main() { 2 println!("size_of i32 = {}", std::mem::size_of::()); 3 println!("size_of f64 = {}", std::mem::size_of::()); 4 println!("size_of bool = {}", std::mem::size_of::()); 5 println!("size_of char = {}", std::mem::size_of::()); 6 println!("size_of (i32,i32) = {}", std::mem::size_of::<(i32, i32)>()); 7 println!("size_of [i32; 3] = {}", std::mem::size_of::<[i32; 3]>()); 8 println!("size_of String = {}", std::mem::size_of::()); 9 println!("size_of Vec = {}", std::mem::size_of::>()); 10 println!("size_of &str = {}", std::mem::size_of::<&str>()); 11 println!("size_of Box = {}", std::mem::size_of::>()); 12 } ``` **Output (verified, 64-bit platform):** ```text 1 size_of i32 = 4 2 size_of f64 = 8 3 size_of bool = 1 4 size_of char = 4 5 size_of (i32,i32) = 8 6 size_of [i32; 3] = 12 7 size_of String = 24 8 size_of Vec = 24 9 size_of &str = 16 10 size_of Box = 8 ``` A `String` is 24 bytes on the stack regardless of whether it holds `"hi"` or a megabyte of text; those 24 bytes are the pointer (8) + length (8) + capacity (8). A `Vec` is the same shape. A `&str` is 16 bytes: a pointer plus a length (no capacity, because you cannot grow through a shared reference). A `Box` is just 8 bytes: a single pointer to a heap-allocated `i32`. > **Note:** A `char` is 4 bytes, not 1, because Rust’s `char` is a full Unicode scalar value (any code point from `'a'` to `'\u{1F600}'`), unlike C’s 1-byte `char`. Text encoding is covered more in [Section 02 — Basic Types](/02-basics/01-types/). ### Putting a value on the heap on purpose: `Box` [Section titled “Putting a value on the heap on purpose: Box\”](#putting-a-value-on-the-heap-on-purpose-boxt) Most of the time the standard library decides heap usage for you (`String`, `Vec`). When you want to *explicitly* move a single value to the heap, you use `Box`. The box itself is one pointer on the stack; the value it owns lives on the heap. ```rust 1 fn main() { 2 let boxed: Box = Box::new(42); 3 println!("boxed value = {}", *boxed); // deref to read the heap value 4 5 // The handle is tiny even when the boxed data is large. 6 let on_stack: [u64; 4] = [1, 2, 3, 4]; 7 let on_heap: Box<[u64; 4]> = Box::new([1, 2, 3, 4]); 8 println!("[u64; 4] on the stack = {} bytes", std::mem::size_of_val(&on_stack)); 9 println!("Box<[u64; 4]> handle = {} bytes", std::mem::size_of_val(&on_heap)); 10 println!("on_heap[0] = {}", on_heap[0]); 11 } ``` **Output (verified):** ```text 1 boxed value = 42 2 [u64; 4] on the stack = 32 bytes 3 Box<[u64; 4]> handle = 8 bytes ``` `Box` is the simplest of Rust’s smart pointers; the others (`Rc`, `Arc`, and friends) get a light intro in [Reference Counting with `Rc` and `Arc`](/05-ownership/07-reference-counting/) and full coverage in [Section 10 — Smart Pointers](/10-smart-pointers/). ### Why Rust cares (and JavaScript doesn’t) [Section titled “Why Rust cares (and JavaScript doesn’t)”](#why-rust-cares-and-javascript-doesnt) In JavaScript, the engine puts almost everything on a managed heap and a garbage collector decides when to free it. You trade control for convenience. In Rust there is no GC, so the compiler needs a deterministic rule for *when* heap memory is freed. That rule is **ownership**: each heap value has exactly one owner, and when the owner goes out of scope the value is freed. Because copying a 24-byte handle is cheap but duplicating its heap buffer is not, Rust *moves* the handle by default instead of deep-copying it, which is exactly what you saw in the `let b = a` examples above and what the next files explore in depth. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript | Rust | | ------------------------- | ------------------------------------ | ----------------------------------------------------- | | Who decides stack vs heap | The engine; hidden from you | Determined by type, visible and meaningful | | Freeing memory | Garbage collector, non-deterministic | At end of scope, deterministic (no GC) | | Primitive assignment | Copy by value | Copy by value (for `Copy` types) | | Object/array assignment | Copies the **reference** (aliasing) | **Moves** ownership of the handle | | `number` | Always IEEE-754 f64 | Pick a size: `i8`..`i128`, `u8`..`u128`, `f32`, `f64` | | A growable string | A heap object, GC-managed | `String`: stack handle + heap buffer | | Cost model | Opaque; GC pauses possible | Explicit; you can predict allocations | ### ”Reference” means two different things [Section titled “”Reference” means two different things”](#reference-means-two-different-things) This is the trap that confuses every JavaScript developer. In JavaScript, “reference” describes how *assignment* works: `b = a` makes two names for one heap object, and mutating through one is visible through the other. In Rust, that automatic-aliasing-on-assignment does **not** happen: `let b = a` *moves* ownership (for heap types) or *copies* (for stack `Copy` types). Rust does have references, written `&a`, but they are an explicit, separate concept called **borrowing**, covered in [Borrowing and References](/05-ownership/02-borrowing/). Do not assume Rust assignment behaves like JavaScript object assignment; it does not. ### No “boxing” surprises [Section titled “No “boxing” surprises”](#no-boxing-surprises) In JavaScript even a humble `number` can end up boxed and the engine may move data around behind your back. In Rust the type *is* the layout. An `i32` is four bytes wherever it appears; a `[u8; 1024]` is exactly 1024 contiguous bytes on the stack. There is no hidden indirection unless you write it (`Box`, `Vec`, `String`, a reference, etc.). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Expecting JavaScript “shared reference” semantics from assignment [Section titled “Pitfall 1: Expecting JavaScript “shared reference” semantics from assignment”](#pitfall-1-expecting-javascript-shared-reference-semantics-from-assignment) Coming from JavaScript, you might expect `let b = a` to make `a` and `b` aliases. For a heap type, Rust *moves* instead, and using the old name afterward is a compile error. ```rust 1 fn main() { 2 let s1 = String::from("hello"); 3 let s2 = s1; // ownership of the heap buffer moves to s2 4 println!("{s1}"); // does not compile (error[E0382]: borrow of moved value: `s1`) 5 println!("{s2}"); 6 } ``` **Real compiler error:** ```text 1 error[E0382]: borrow of moved value: `s1` 2 --> src/main.rs:4:16 3 | 4 2 | let s1 = String::from("hello"); 5 | -- move occurs because `s1` has type `String`, which does not implement the `Copy` trait 6 3 | let s2 = s1; // ownership of the heap buffer moves to s2 7 | -- value moved here 8 4 | println!("{s1}"); // does not compile (error[E0382]: borrow of moved value: `s1`) 9 | ^^ value borrowed here after move 10 | 11 help: consider cloning the value if the performance cost is acceptable 12 | 13 3 | let s2 = s1.clone(); // ownership of the heap buffer moves to s2 14 | ++++++++ ``` The fix depends on intent: borrow with `&s1` if you only need to read it, or `.clone()` if you genuinely want a second independent heap buffer. Why the move happens (and why `i32` would have been fine here) is the subject of [Move, Copy, and Clone](/05-ownership/06-move-copy-clone/). ### Pitfall 2: Trying to put a recursive type entirely on the stack [Section titled “Pitfall 2: Trying to put a recursive type entirely on the stack”](#pitfall-2-trying-to-put-a-recursive-type-entirely-on-the-stack) A type that contains itself has no finite size, so the compiler cannot lay it out on the stack. This is a real (and famous) error: ```rust 1 // does not compile (error[E0072]: recursive type `List` has infinite size) 2 enum List { 3 Cons(i32, List), 4 Nil, 5 } 6 7 fn main() { 8 let _list = List::Cons(1, List::Cons(2, List::Nil)); 9 } ``` **Real compiler error (key part):** ```text 1 error[E0072]: recursive type `List` has infinite size 2 --> src/main.rs:2:1 3 | 4 2 | enum List { 5 | ^^^^^^^^^ 6 3 | Cons(i32, List), 7 | ---- recursive without indirection 8 | 9 help: insert some indirection (e.g., a `Box`, `Rc`, or `&`) to break the cycle 10 | 11 3 | Cons(i32, Box), 12 | ++++ + ``` The fix is exactly what the compiler suggests: put the recursive part behind a pointer (`Box`) so each node is a fixed size. We use this in Exercise 3. ### Pitfall 3: Overflowing the stack with deep recursion or huge arrays [Section titled “Pitfall 3: Overflowing the stack with deep recursion or huge arrays”](#pitfall-3-overflowing-the-stack-with-deep-recursion-or-huge-arrays) The stack is small. Two ways to blow past it: * **Unbounded recursion**: every call pushes a frame and they are never popped. * **A giant fixed-size array as a local** — `let big = [0u8; 50_000_000];` tries to put 50 MB on the stack. Here is real unbounded recursion: ```rust 1 // Each call pushes another stack frame; this never returns. 2 fn count_up(n: u64) -> u64 { 3 println!("{n}"); 4 count_up(n + 1) // no base case: recurses forever 5 } 6 7 fn main() { 8 count_up(0); 9 } ``` This compiles (with an `unconditional_recursion` warning: *function cannot return without recursing*), but at runtime it aborts once the stack is exhausted: ```text 1 thread 'main' has overflowed its stack 2 fatal runtime error: stack overflow, aborting ``` (The process exits with code 134.) The fix for huge data is to put it on the heap — `Box`, `Vec`, etc. — where there is room to grow. The fix for recursion is a base case, or rewriting as a loop. ### Pitfall 4: Assuming `number`-style behavior from Rust integers [Section titled “Pitfall 4: Assuming number-style behavior from Rust integers”](#pitfall-4-assuming-number-style-behavior-from-rust-integers) In JavaScript `number` is always an f64, so very large integers silently **lose precision** (they do not wrap): ```typescript 1 console.log(9007199254740993); // 9007199254740992 — precision lost, not wrapped ``` In Rust you choose a concrete integer type, and overflow is checked in debug builds (it panics) rather than silently losing precision. This is not strictly a stack/heap issue, but it is the same theme: **Rust makes the representation explicit** instead of hiding it. Integer types and overflow are covered in [Section 02 — Basic Types](/02-basics/01-types/). *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Prefer the stack; reach for the heap only when you need it [Section titled “Prefer the stack; reach for the heap only when you need it”](#prefer-the-stack-reach-for-the-heap-only-when-you-need-it) Stack values are faster to allocate, faster to access (better cache locality), and freed for free when the frame pops. Use plain values, tuples, and fixed-size arrays for small, fixed-size data. Reach for `String`, `Vec`, or `Box` when the data is growable, large, or its size is unknown at compile time. ### Borrow instead of moving or cloning when you only need to read [Section titled “Borrow instead of moving or cloning when you only need to read”](#borrow-instead-of-moving-or-cloning-when-you-only-need-to-read) If a function just reads a `String`, take `&str` (a borrow), not an owned `String`. You avoid both a move (which would strand the caller’s value) and a clone (which would duplicate the heap buffer). Borrowing is the subject of [Borrowing and References](/05-ownership/02-borrowing/), but the memory reason is here: a borrow is a cheap 16-byte pointer-plus-length, never a heap copy. ```rust 1 // reads without taking ownership or copying the heap buffer 2 fn char_count(text: &str) -> usize { 3 text.chars().count() 4 } 5 6 fn main() { 7 let name = String::from("Grace Hopper"); 8 println!("{}", char_count(&name)); // name is still usable afterward 9 println!("{name}"); 10 } ``` **Output (verified):** ```text 1 12 2 Grace Hopper ``` ### Don’t reach for `Box` reflexively [Section titled “Don’t reach for Box reflexively”](#dont-reach-for-box-reflexively) A JavaScript developer’s instinct is “everything is a reference, so box everything.” In Rust, most values should be plain stack values; the compiler and `Vec`/`String` handle heap allocation where it is actually needed. Use `Box` specifically for recursive types, very large values you want to move cheaply, or trait objects (`Box`, covered later). Boxing a small `i32` for no reason just adds an indirection. ### Let scope-based cleanup do its job [Section titled “Let scope-based cleanup do its job”](#let-scope-based-cleanup-do-its-job) You never call `free`. Design your code so values live exactly as long as they are needed and let them drop at the end of their scope. Deterministic, scope-based cleanup (RAII) is one of Rust’s quiet superpowers and is detailed in [The Drop Trait and RAII](/05-ownership/08-drop-trait/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A common back-end task: ingesting telemetry events. A single event mixes small fixed-size fields (IDs, timestamps, flags) with variable-length data (an endpoint string, a list of tags). This is exactly where the stack/heap split shows up in everyday code. ```rust 1 /// A telemetry event ingested from a client. Mixes stack-only fields 2 /// (fixed-size numbers, a bool) with heap-backed fields (String, Vec). 3 #[derive(Debug)] 4 struct TelemetryEvent { 5 user_id: u64, // 8 bytes, stored inline in the struct 6 timestamp_ms: u64, // 8 bytes, inline 7 is_error: bool, // 1 byte, inline 8 endpoint: String, // 24-byte handle inline; the text bytes live on the heap 9 tags: Vec, // 24-byte handle inline; the elements live on the heap 10 } 11 12 impl TelemetryEvent { 13 fn new(user_id: u64, timestamp_ms: u64, endpoint: &str) -> Self { 14 TelemetryEvent { 15 user_id, 16 timestamp_ms, 17 is_error: false, 18 endpoint: endpoint.to_string(), 19 tags: Vec::new(), 20 } 21 } 22 23 /// Render a one-line summary, reading each field. 24 fn summary(&self) -> String { 25 let status = if self.is_error { "ERROR" } else { "ok" }; 26 format!( 27 "user={} ts={} {} {} tags={:?}", 28 self.user_id, self.timestamp_ms, status, self.endpoint, self.tags 29 ) 30 } 31 } 32 33 fn main() { 34 let mut event = TelemetryEvent::new(42, 1_717_000_000_000, "/api/v1/checkout"); 35 event.is_error = true; 36 event.tags.push("payment".to_string()); 37 event.tags.push("timeout".to_string()); 38 39 // The struct value itself is a fixed-size block: the inline fields plus 40 // the String/Vec handles. The variable-length text lives on the heap. 41 println!( 42 "size of TelemetryEvent struct = {} bytes", 43 std::mem::size_of::() 44 ); 45 println!("{}", event.summary()); 46 } ``` **Output (verified):** ```text 1 size of TelemetryEvent struct = 72 bytes 2 user=42 ts=1717000000000 ERROR /api/v1/checkout tags=["payment", "timeout"] ``` The struct is a fixed **72 bytes** no matter how long the endpoint or how many tags it carries: 8 + 8 + 1 (rounded up for alignment) + 24 (the `String` handle) + 24 (the `Vec` handle). The actual endpoint text and tag strings live on the heap, reached through those handles. When `event` goes out of scope at the end of `main`, Rust frees the struct *and* every heap buffer it owns, automatically, with no garbage collector and no `free` call. > **Tip:** Struct field layout (and how `#[derive(Debug)]` lets you print a value with `{:?}`) is covered in [Section 06 — Data Structures](/06-data-structures/). The exact 72 is also affected by alignment and field ordering, which the compiler may optimize. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official documentation [Section titled “Official documentation”](#official-documentation) * [The Rust Book — What Is Ownership? (the stack and the heap)](https://doc.rust-lang.org/book/ch04-01-what-is-ownership.html#the-stack-and-the-heap) * [The Rust Book — Using `Box` to Point to Data on the Heap](https://doc.rust-lang.org/book/ch15-01-box.html) * [`std::boxed::Box` API documentation](https://doc.rust-lang.org/std/boxed/struct.Box.html) * [`std::mem::size_of` API documentation](https://doc.rust-lang.org/std/mem/fn.size_of.html) ### Related sections in this guide [Section titled “Related sections in this guide”](#related-sections-in-this-guide) * [Section 05 — Ownership (overview)](/05-ownership/): how this fits into the whole ownership story. * [The Three Ownership Rules](/05-ownership/01-ownership-rules/): the three rules that govern this memory. * [Move, Copy, and Clone](/05-ownership/06-move-copy-clone/): why heap handles move and stack values copy. * [Borrowing and References](/05-ownership/02-borrowing/): references (`&T`), the cheap way to read without owning. * [The Drop Trait and RAII](/05-ownership/08-drop-trait/): deterministic, scope-based cleanup instead of a garbage collector. * [Reference Counting with `Rc` and `Arc`](/05-ownership/07-reference-counting/): `Rc`/`Arc` for shared heap ownership. * [Section 02 — Basic Types](/02-basics/01-types/) — sizes of integers, floats, `char`, and arrays. * [Section 06 — Data Structures](/06-data-structures/) — how struct fields are laid out. * [Section 01 — Why Rust?](/01-getting-started/00-why-rust/) — the case for no garbage collector. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Classify each value’s home [Section titled “Exercise 1: Classify each value’s home”](#exercise-1-classify-each-values-home) **Difficulty:** Easy **Objective:** Build the mental model of which values live on the stack and which need the heap. **Instructions:** 1. Create these four bindings: a `u32`, a `String`, a tuple `(f64, f64)`, and a `Vec`. 2. For each, decide whether it lives entirely on the stack or has a stack handle plus heap data. 3. Use `std::mem::size_of_val(&value)` to print the size of each *stack* representation, and add a comment stating where the rest (if any) lives. Solution ```rust 1 fn main() { 2 let count: u32 = 100; // stack only 3 let label = String::from("temp"); // handle on stack, bytes on heap 4 let coords = (1.0_f64, 2.0_f64); // stack only (fixed-size tuple) 5 let readings = vec![9.8, 10.1]; // handle on stack, elements on heap 6 7 println!("count -> stack, {} bytes", std::mem::size_of_val(&count)); 8 println!( 9 "label -> handle on stack ({} bytes) + bytes on heap", 10 std::mem::size_of_val(&label) 11 ); 12 println!("coords -> stack, {} bytes", std::mem::size_of_val(&coords)); 13 println!( 14 "readings -> handle on stack ({} bytes) + elements on heap", 15 std::mem::size_of_val(&readings) 16 ); 17 } ``` **Verified output:** ```text 1 count -> stack, 4 bytes 2 label -> handle on stack (24 bytes) + bytes on heap 3 coords -> stack, 16 bytes 4 readings -> handle on stack (24 bytes) + elements on heap ``` The `u32` and the `(f64, f64)` tuple are pure stack values. The `String` and `Vec` are 24-byte handles on the stack (pointer + length + capacity) that point to buffers on the heap. ### Exercise 2: Return heap-owned data without dangling [Section titled “Exercise 2: Return heap-owned data without dangling”](#exercise-2-return-heap-owned-data-without-dangling) **Difficulty:** Medium **Objective:** See that returning an owned `String` *moves* its heap buffer out to the caller, so nothing dangles: the opposite of the classic “returning a pointer to a local” bug in C. **Instructions:** 1. Write `build_greeting(name: &str) -> String` that creates a new `String`, appends `name` and a `'!'`, and returns it. 2. Use `String::from`, `push_str`, and `push`. 3. Return the `String` as a tail expression (no `return` keyword needed) and print the result from `main`. > **Tip:** Returning the value *moves* ownership of the heap buffer to the caller. Rust statically guarantees the buffer is still alive — you cannot accidentally return a reference to freed memory. Solution ```rust 1 fn build_greeting(name: &str) -> String { 2 let mut greeting = String::from("Hello, "); 3 greeting.push_str(name); 4 greeting.push('!'); 5 greeting // ownership of the heap buffer moves out to the caller 6 } 7 8 fn main() { 9 let msg = build_greeting("Ada"); 10 println!("{msg}"); 11 } ``` **Verified output:** ```text 1 Hello, Ada! ``` The `greeting` buffer was allocated inside the function, but returning it *moves* ownership to `main`. There is no copy of the bytes and no dangling pointer; the heap allocation simply has a new owner. ### Exercise 3: Use `Box` to give a recursive type a finite size [Section titled “Exercise 3: Use Box to give a recursive type a finite size”](#exercise-3-use-box-to-give-a-recursive-type-a-finite-size) **Difficulty:** Medium **Objective:** Fix the “infinite size” error by adding heap indirection, and observe the resulting node size. **Instructions:** 1. Start from this broken definition (it does not compile; ``error[E0072]: recursive type `List` has infinite size``): ```rust 1 enum List { 2 Cons(i32, List), // recursive without indirection 3 Nil, 4 } ``` 2. Wrap the recursive field in a `Box` so each node has a fixed size. 3. Build the list `1 -> 2 -> 3 -> Nil`, then print `size_of::()` and the list itself (derive `Debug`). Solution ```rust 1 #[derive(Debug)] 2 enum List { 3 Cons(i32, Box), // the recursive part now lives behind a pointer 4 Nil, 5 } 6 7 use List::{Cons, Nil}; 8 9 fn main() { 10 let list = Cons(1, Box::new(Cons(2, Box::new(Cons(3, Box::new(Nil)))))); 11 println!("size of List node = {} bytes", std::mem::size_of::()); 12 println!("{list:?}"); 13 } ``` **Verified output:** ```text 1 size of List node = 16 bytes 2 Cons(1, Cons(2, Cons(3, Nil))) ``` `Box` is a single pointer of known size, so each `List` node is a fixed 16 bytes (a discriminant for the enum variant plus the `i32` and the pointer, with alignment padding). The nodes themselves live on the heap, chained by their boxes. `Box` is the gateway to the other smart pointers in [Reference Counting with `Rc` and `Arc`](/05-ownership/07-reference-counting/) and [Section 10 — Smart Pointers](/10-smart-pointers/). > **Note:** This compiles and runs; the compiler may emit a harmless `dead_code` warning for the enum fields because it analyzes derived `Debug` impls conservatively. The program output above is unaffected. *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * The **stack** holds fixed-size, short-lived values and is freed automatically as functions return; the **heap** holds growable or unknown-size data. * `String`, `Vec`, and `Box` keep a small fixed-size **handle on the stack** that points to a buffer on the **heap**. * TypeScript/JavaScript hides this behind a garbage collector and aliases objects on assignment; Rust makes it explicit and **moves** heap handles instead. * There is **no garbage collector** in Rust; deterministic, scope-based cleanup is possible precisely because every heap value has a single owner. * Knowing what lives where is the foundation for understanding moves, borrows, and lifetimes in the rest of this section. **Mental model:** * Small + fixed size → stack, copied cheaply. * Growable / large / unknown size → heap, reached through a handle, moved by default. * No `malloc`, no `free`, no GC: the compiler frees heap memory when the owner’s scope ends. # The Three Rules of Rust Ownership > One owner per value, ownership moves on assignment or a function call, and values drop at scope end. How Rust frees memory deterministically without JavaScript's GC. Ownership is the mechanism Rust uses to manage memory **without a garbage collector**. Instead of a runtime that periodically scans for unreachable objects (the JavaScript model), Rust determines when each value is freed from the structure of your code — almost always statically, at scope exit. (In rare cases where a value is only *conditionally* moved, the compiler inserts a hidden runtime “drop flag”, but the rule of thumb holds: cleanup happens at a predictable point, not whenever a GC gets around to it.) The whole system rests on three short rules, and this page is about those rules and nothing more. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) In Rust, every value has exactly one **owner**; ownership **moves** when you assign the value or pass it to a function; and when the owner goes out of scope, the value is **dropped** (its memory freed) automatically. There is no `new`/`delete`, no `free()`, and no garbage collector. The compiler tracks ownership and inserts cleanup for you. For a TypeScript/JavaScript developer, the surprising part is not the cleanup (the GC already hides that) but that *handing a value to someone else can make your own variable unusable*. > **Note:** This page covers the rules themselves and the **move** that happens on assignment and function calls. Borrowing (`&`), which lets you lend access *without* giving up ownership, is the subject of [Borrowing and References](/05-ownership/02-borrowing/). The stack/heap distinction that explains *why* moves matter lives in [Stack and Heap](/05-ownership/00-stack-heap/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In JavaScript and TypeScript you never think about who “owns” a value. You create objects, pass them around, and the **garbage collector** (GC) frees them whenever it decides nothing can reach them anymore. ```typescript 1 // TypeScript/JavaScript: values are shared freely, GC cleans up "eventually" 2 function archiveOrder(orderId: string): void { 3 console.log(`Archiving ${orderId}`); 4 } 5 6 let orderId = "ORD-2026-0531"; 7 let archived = orderId; // both names now refer to the same string value 8 9 console.log(orderId); // "ORD-2026-0531" — still usable 10 console.log(archived); // "ORD-2026-0531" 11 12 archiveOrder(orderId); // pass it to a function... 13 console.log(orderId); // still usable afterward — nothing was "consumed" 14 15 // When `orderId` and `archived` become unreachable, the GC frees the memory 16 // at some unspecified later time. You never decide when. ``` **Key points:** * Assigning `archived = orderId` makes a second handle to the same data (for objects/arrays it is a shared reference; for primitives like strings it is a copy, but either way the original stays valid). * Passing a value to a function does **not** invalidate the caller’s variable. * Cleanup timing is **non-deterministic**: the GC runs when it wants. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust enforces a stricter discipline. The same `let archived = order_id;` **moves** ownership, and the original binding becomes unusable. ```rust 1 fn print_receipt(id: String) { 2 println!("Receipt: {id}"); 3 } // `id` dropped here, its heap buffer freed 4 5 fn main() { 6 // ---- Rule 1 & 2: single owner, move on assignment ---- 7 let order_id = String::from("ORD-2026-0531"); 8 let archived = order_id; // value MOVES; `order_id` is no longer valid 9 println!("Archived order: {archived}"); 10 11 // ---- Rule 3: drop at end of scope ---- 12 { 13 let temp = String::from("temporary buffer"); 14 println!("Inside block: {temp}"); 15 } // `temp` goes out of scope here -> its heap buffer is freed 16 17 // ---- move into a function ---- 18 let receipt = String::from("RCPT-9001"); 19 print_receipt(receipt); // ownership moves into print_receipt 20 // println!("{receipt}"); // would not compile: value moved 21 22 // ---- Copy types are duplicated, not moved ---- 23 let total = 42_u32; 24 let copy = total; // u32 is Copy: bitwise copy, both stay valid 25 println!("total={total}, copy={copy}"); 26 } ``` **Output:** ```plaintext 1 Archived order: ORD-2026-0531 2 Inside block: temporary buffer 3 Receipt: RCPT-9001 4 total=42, copy=42 ``` **Key points:** * `let archived = order_id;` **moves** ownership; `order_id` can no longer be used. * Passing `receipt` to `print_receipt` moves it *into* the function. * `temp` is freed precisely at the closing `}` of its block, deterministically. * Small stack-only types like `u32` are `Copy`, so `let copy = total;` duplicates instead of moving. (`Copy` vs `Clone` is the topic of [Move, Copy, and Clone](/05-ownership/06-move-copy-clone/).) *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) The Rust Book states the three rules verbatim: 1. **Each value in Rust has an owner.** 2. **There can only be one owner at a time.** 3. **When the owner goes out of scope, the value is dropped.** Let’s take them one at a time, line by line, and contrast each with what TypeScript/JavaScript does. ### Rule 1 — Each value has an owner [Section titled “Rule 1 — Each value has an owner”](#rule-1--each-value-has-an-owner) A **value** is a piece of data (a `String`, a `Vec`, a struct, a number). A **variable** (more precisely, a *binding*) is the name that owns it. ```rust 1 let order_id = String::from("ORD-2026-0531"); ``` Here `order_id` is the owner of the heap-allocated string buffer. Ownership is a property the compiler tracks; it is not stored at runtime and costs nothing. There is no header, no reference count, no GC bookkeeping attached to the value. The compiler simply *knows* who the owner is at every point in the program. In JavaScript there is no analogous concept. A value can be reachable through any number of variables and object fields simultaneously, and “who owns it” is a meaningless question because the GC owns everything. ### Rule 2 — One owner at a time: the move [Section titled “Rule 2 — One owner at a time: the move”](#rule-2--one-owner-at-a-time-the-move) This is the rule that bites TypeScript/JavaScript developers. Assigning a value to a new binding **transfers** ownership rather than copying or aliasing it: ```rust 1 let order_id = String::from("ORD-2026-0531"); 2 let archived = order_id; // ownership MOVED into `archived` ``` A `String` is a three-word value on the stack — a pointer to a heap buffer, a length, and a capacity. The move copies those three words into `archived` and then **invalidates** `order_id`. It does *not* copy the heap buffer, and it does *not* create a second valid pointer to the same buffer. If both `order_id` and `archived` were allowed to be used, both would try to free the same buffer when they went out of scope: a classic *double-free* bug. The move rule makes that impossible. > **Tip:** Read `let archived = order_id;` as “`archived` takes over ownership from `order_id`,” not “`archived` is a copy of `order_id`.” After this line, `order_id` is gone — not empty, not null, just *not a thing you can name anymore*. Passing a value to a function is also a move, because the parameter is a new binding: ```rust 1 let receipt = String::from("RCPT-9001"); 2 print_receipt(receipt); // `receipt` moved into the parameter `id` ``` After this call, `receipt` is no longer usable in `main`. Its ownership now belongs to `print_receipt`, and when that function ends, the value is dropped there. **Why doesn’t this happen with numbers?** Types whose data lives entirely on the stack and is cheap to duplicate — integers, floats, `bool`, `char`, and tuples of them — implement the `Copy` trait. For those, `let copy = total;` makes an independent bitwise copy and leaves the original valid. There is no heap buffer to double-free, so copying is safe. `String`, `Vec`, and most structs are **not** `Copy`, so they move. See [Move, Copy, and Clone](/05-ownership/06-move-copy-clone/) for the full story. ### Rule 3 — Dropped at end of scope [Section titled “Rule 3 — Dropped at end of scope”](#rule-3--dropped-at-end-of-scope) When a binding goes out of scope, Rust automatically runs cleanup for the value it owns. For a `String` or `Vec`, that means freeing the heap buffer; for a file handle, closing the file; for a lock guard, releasing the lock. This is **deterministic** and tied to lexical scope: ```rust 1 { 2 let temp = String::from("temporary buffer"); 3 println!("Inside block: {temp}"); 4 } // `temp` dropped HERE — exactly at this `}`, every time ``` You can *see* this happen by implementing the `Drop` trait so the value prints when it is cleaned up: ```rust 1 struct Connection { 2 label: &'static str, 3 } 4 5 impl Drop for Connection { 6 fn drop(&mut self) { 7 println!("Closing connection: {}", self.label); 8 } 9 } 10 11 fn main() { 12 println!("Start of main"); 13 let first = Connection { label: "first" }; 14 let second = Connection { label: "second" }; 15 println!("Opened {} and {}", first.label, second.label); 16 17 { 18 let inner = Connection { label: "inner-block" }; 19 println!("Inside inner block with {}", inner.label); 20 } // `inner` dropped here 21 22 println!("Back in main"); 23 } // `second` then `first` dropped here (reverse declaration order) ``` **Output:** ```plaintext 1 Start of main 2 Opened first and second 3 Inside inner block with inner-block 4 Closing connection: inner-block 5 Back in main 6 Closing connection: second 7 Closing connection: first ``` Two things to notice. First, `inner` is dropped at the inner `}`, *before* `Back in main` prints; cleanup is scope-bound, not deferred to the end of the program. Second, within a scope, values are dropped in **reverse order of declaration** (`second` before `first`), like unwinding a stack. The mechanics of `Drop` and this ordering are explored in depth in [The Drop Trait and RAII](/05-ownership/08-drop-trait/); here the point is simply that **Rule 3 frees memory automatically, at a moment you can predict by reading the code**. This is the polar opposite of JavaScript. The JS engine’s GC frees objects at an unspecified time after they become unreachable, and `FinalizationRegistry` callbacks are explicitly documented as offering *no timing guarantees* and may never run at all. Rust gives you precise, source-visible cleanup with zero runtime tracking. ### What “move” actually invalidates [Section titled “What “move” actually invalidates”](#what-move-actually-invalidates) A natural question: if you give a value away, how do you keep using your data? Three answers, in increasing order of preference: 1. **Get it back.** A function can take ownership and return it (possibly alongside other results): ```rust 1 fn measure(s: String) -> (String, usize) { 2 let len = s.len(); 3 (s, len) // hand the String back to the caller 4 } 5 6 fn main() { 7 let s = String::from("ownership"); 8 let (s, len) = measure(s); // re-bind `s` from the returned tuple 9 println!("'{s}' has length {len}"); 10 } ``` Output: `'ownership' has length 9` 2. **Clone it.** Make an explicit, independent deep copy so each binding owns its own data: ```rust 1 let original = String::from("config.toml"); 2 let backup = original.clone(); // explicit, potentially expensive deep copy 3 println!("original = {original}"); 4 println!("backup = {backup}"); ``` 3. **Borrow it (best).** Lend a reference so no move happens at all; the caller keeps ownership: ```rust 1 fn char_count(s: &str) -> usize { 2 s.chars().count() 3 } 4 5 let path = String::from("/etc/hosts"); 6 let length = char_count(&path); // pass a reference; no move 7 println!("'{path}' has {length} chars"); // `path` still owned here ``` Borrowing is usually the right tool and is the subject of the [next page](/05-ownership/02-borrowing/). Returning ownership and cloning are covered above so you understand the alternatives the compiler keeps suggesting. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / JavaScript | Rust | | -------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | Who frees memory | Garbage collector, at an unspecified time | The compiler, deterministically at scope exit | | Assignment (`b = a`) | New handle/reference (or value copy for primitives); `a` stays valid | **Move**: ownership transfers; `a` becomes unusable (unless the type is `Copy`) | | Passing to a function | Caller’s variable stays valid | Argument is **moved in**; caller’s variable becomes unusable (unless `Copy` or you pass a reference) | | Number of live references to one value | Unlimited | Exactly one *owner* (plus borrows, governed separately) | | Cleanup timing | Non-deterministic; `FinalizationRegistry` gives no guarantees | Deterministic, at the closing `}` of the owner’s scope | | Runtime cost | GC pauses, allocation headers, tracing | Zero — ownership is a compile-time-only concept | | Double-free / use-after-free | Not possible (GC), but memory leaks via retained references are | Prevented at compile time by the move rule | **The core mental shift:** in JavaScript, *naming a value more times keeps it alive longer*. In Rust, naming a value a second time (by assignment or passing it) usually **consumes the first name**. You move the responsibility of freeing the value, and only one binding can hold that responsibility at a time. > **Note:** “Move” in Rust is a *compile-time bookkeeping* operation. At runtime, moving a `String` is just copying three machine words (pointer, length, capacity); the heap buffer is untouched. The compiler then refuses to let you use the old binding. So a move is cheap *and* safe — you are not paying for a deep copy, and you cannot accidentally alias the buffer. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Using a value after it was moved by assignment [Section titled “Pitfall 1: Using a value after it was moved by assignment”](#pitfall-1-using-a-value-after-it-was-moved-by-assignment) This is the first error nearly every newcomer hits. ```rust 1 fn main() { 2 let order_id = String::from("ORD-2026-0531"); 3 let archived = order_id; 4 println!("{order_id}"); // does not compile (error[E0382]): use after move 5 println!("{archived}"); 6 } ``` The compiler is precise and even suggests the fix: ```plaintext 1 error[E0382]: borrow of moved value: `order_id` 2 --> src/main.rs:4:16 3 | 4 2 | let order_id = String::from("ORD-2026-0531"); 5 | -------- move occurs because `order_id` has type `String`, which does not implement the `Copy` trait 6 3 | let archived = order_id; 7 | -------- value moved here 8 4 | println!("{order_id}"); // does not compile (error[E0382]): use after move 9 | ^^^^^^^^ value borrowed here after move 10 | 11 = note: this error originates in the macro `$crate::format_args_nl` which comes from the expansion of the macro `println` (in Nightly builds, run with -Z macro-backtrace for more info) 12 help: consider cloning the value if the performance cost is acceptable 13 | 14 3 | let archived = order_id.clone(); 15 | ++++++++ ``` **Fix:** clone if you genuinely need two independent owners (`order_id.clone()`), or borrow if you only need to read it. The phrase “does not implement the `Copy` trait” is the compiler telling you *why* this was a move rather than a copy. ### Pitfall 2: Using a value after passing it to a function [Section titled “Pitfall 2: Using a value after passing it to a function”](#pitfall-2-using-a-value-after-passing-it-to-a-function) Coming from JavaScript, you expect the caller’s variable to survive a function call. It does not, if the value was moved in. ```rust 1 fn print_receipt(id: String) { 2 println!("Receipt: {id}"); 3 } 4 5 fn main() { 6 let receipt = String::from("RCPT-9001"); 7 print_receipt(receipt); 8 println!("Still have: {receipt}"); // does not compile (error[E0382]): moved into function 9 } ``` Real compiler output (abbreviated; note the targeted hint about the parameter type): ```plaintext 1 error[E0382]: borrow of moved value: `receipt` 2 --> src/main.rs:8:28 3 | 4 6 | let receipt = String::from("RCPT-9001"); 5 | ------- move occurs because `receipt` has type `String`, which does not implement the `Copy` trait 6 7 | print_receipt(receipt); 7 | ------- value moved here 8 8 | println!("Still have: {receipt}"); // does not compile (error[E0382]): moved into function 9 | ^^^^^^^ value borrowed here after move 10 | 11 note: consider changing this parameter type in function `print_receipt` to borrow instead if owning the value isn't necessary 12 --> src/main.rs:1:22 13 | 14 1 | fn print_receipt(id: String) { 15 | ------------- ^^^^^^ this parameter takes ownership of the value 16 ... (rustc continues with a "help: consider cloning the value" suggestion) ``` **Fix:** if the function only needs to *read* the value, take `&str`/`&String` instead of `String`, so the call borrows rather than moves. (That is exactly what [Borrowing and References](/05-ownership/02-borrowing/) teaches.) ### Pitfall 3: Moving a value inside a loop [Section titled “Pitfall 3: Moving a value inside a loop”](#pitfall-3-moving-a-value-inside-a-loop) A move that is fine once becomes an error when it repeats: ```rust 1 fn print_banner(text: String) { 2 println!("{text}"); 3 } 4 5 fn main() { 6 let banner = String::from("=== Report ==="); 7 for _ in 0..3 { 8 print_banner(banner); // does not compile (error[E0382]): moved in previous iteration 9 } 10 } ``` The compiler specifically calls out the loop (output abbreviated): ```plaintext 1 error[E0382]: use of moved value: `banner` 2 --> src/main.rs:8:22 3 | 4 6 | let banner = String::from("=== Report ==="); 5 | ------ move occurs because `banner` has type `String`, which does not implement the `Copy` trait 6 7 | for _ in 0..3 { 7 | ------------- inside of this loop 8 8 | print_banner(banner); // does not compile (error[E0382]): moved in previous iteration 9 | ^^^^^^ value moved here, in previous iteration of loop 10 ... (rustc continues with "help: consider moving the expression out of the loop" and "help: consider cloning the value" suggestions) ``` **Fix:** pass a borrow (`print_banner(&banner)` with the parameter typed `&str`), or `.clone()` inside the loop if each iteration truly needs its own owned copy. ### Pitfall 4: Partial moves out of a struct [Section titled “Pitfall 4: Partial moves out of a struct”](#pitfall-4-partial-moves-out-of-a-struct) Moving one field out of a struct leaves the struct only *partially* valid: you can still read the fields that were not moved, but you can no longer use the struct as a whole. ```rust 1 #[derive(Debug)] 2 struct User { 3 name: String, 4 email: String, 5 } 6 7 fn main() { 8 let user = User { 9 name: String::from("Grace"), 10 email: String::from("grace@example.com"), 11 }; 12 let name = user.name; // moves the `name` field out 13 println!("{}", user.email); // this field is still readable 14 println!("{:?}", user); // does not compile (error[E0382]): partial move 15 println!("{name}"); 16 } ``` Real output: ```plaintext 1 error[E0382]: borrow of partially moved value: `user` 2 --> src/main.rs:14:22 3 | 4 12 | let name = user.name; // moves the `name` field out 5 | --------- value partially moved here 6 13 | println!("{}", user.email); // this field is still readable 7 14 | println!("{:?}", user); // does not compile (error[E0382]): partial move 8 | ^^^^ value borrowed here after partial move 9 | 10 = note: partial move occurs because `user.name` has type `String`, which does not implement the `Copy` trait ``` **Fix:** clone the field you want to take (`let name = user.name.clone();`), or borrow it (`let name = &user.name;`), so the struct stays whole. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Borrow by default; move only when you mean to give the value away.** If a function just reads or inspects data, take `&T` (or `&str`/`&[T]`). Reserve owned parameters (`String`, `Vec`) for functions that store, consume, or transform the value into something they return. This single habit eliminates most `E0382` errors. * **Reach for `.clone()` deliberately, not reflexively.** The compiler’s “consider cloning” hint is a convenient escape hatch, but a clone is a real allocation and copy. When you find yourself sprinkling `.clone()` to silence the borrow checker, pause and ask whether a borrow would do; that is usually the idiomatic answer. * **Let scope drive cleanup.** Don’t look for a `free`, `dispose`, or `close` to call manually. Structure your code so a value’s scope matches its lifetime, and Rule 3 frees it at the right moment. If you need a value gone *early*, that is what `std::mem::drop(value)` is for (covered in [The Drop Trait and RAII](/05-ownership/08-drop-trait/)). * **Return ownership instead of mutating shared state.** Where JavaScript code might push into a shared array passed by reference, idiomatic Rust often takes ownership of a value, transforms it, and returns the new owner: a clear, linear flow of who owns what. * **Name the move when reading code.** When you see `let b = a;` or `f(a)`, train yourself to ask “is `a` `Copy`? If not, `a` is gone after this line.” This makes ownership errors obvious before the compiler points them out. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A common production scenario: an upload pipeline that receives raw bytes from a client, validates and parses them, and produces a stored document. Ownership makes the *stages* explicit: the raw bytes have exactly one owner at each step, and once they are parsed, the original buffer is consumed and cannot be accidentally reused. ```rust 1 /// A raw upload received from a client. 2 struct Upload { 3 filename: String, 4 bytes: Vec, 5 } 6 7 /// A validated, parsed document ready to store. 8 struct Document { 9 filename: String, 10 line_count: usize, 11 } 12 13 /// Consumes the `Upload` (takes ownership) and hands back a `Document`. 14 /// Because `upload` is moved in, the caller can no longer use it afterward — 15 /// the type system guarantees the raw bytes have exactly one owner per stage. 16 fn parse(upload: Upload) -> Result { 17 let text = String::from_utf8(upload.bytes) 18 .map_err(|_| format!("{} is not valid UTF-8", upload.filename))?; 19 let line_count = text.lines().count(); 20 Ok(Document { 21 filename: upload.filename, // move the String out of `upload` 22 line_count, 23 }) 24 } // `text` is dropped here; any unused bytes are freed automatically 25 26 fn main() { 27 let upload = Upload { 28 filename: String::from("notes.txt"), 29 bytes: b"first line\nsecond line\nthird line".to_vec(), 30 }; 31 32 // Ownership of `upload` moves into `parse`; we get a `Document` back. 33 match parse(upload) { 34 Ok(doc) => println!("Stored {} ({} lines)", doc.filename, doc.line_count), 35 Err(e) => eprintln!("Rejected upload: {e}"), 36 } 37 // `upload` is gone here — referencing it would not compile. 38 } ``` **Output:** ```plaintext 1 Stored notes.txt (3 lines) ``` **Why this is idiomatic:** * `parse` takes `upload` by value because it genuinely *consumes* it: once parsed, the raw bytes are no longer meaningful, and the type system enforces that nobody touches the stale upload. * `upload.filename` is moved (not cloned) into the new `Document`, reusing the existing allocation rather than copying the string. * When `parse` returns the `Document`, ownership flows to the `match` arm, and the `Document` is dropped at the end of that arm — no manual cleanup, no leak. * The compiler would reject any attempt to use `upload` after the `parse(upload)` call, catching a whole class of “I accidentally reused the consumed input” bugs that a JavaScript reviewer would have to spot by eye. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — What Is Ownership?](https://doc.rust-lang.org/book/ch04-01-what-is-ownership.html): the canonical statement of the three rules. * [Rust by Example — Ownership and Moves](https://doc.rust-lang.org/rust-by-example/scope/move.html) * [`std::mem::drop`](https://doc.rust-lang.org/std/mem/fn.drop.html): drop a value before the end of its scope. ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Stack vs Heap](/05-ownership/00-stack-heap/): *why* moving a `String` is cheap and *why* it cannot be aliased. * [Borrowing](/05-ownership/02-borrowing/) — lend access with `&` so you don’t have to move or clone. * [Mutable References](/05-ownership/03-mutable-references/): the one-mutable-XOR-many-shared rule. * [Move, Copy, and Clone](/05-ownership/06-move-copy-clone/) — when assignment moves vs copies, and what `Copy`/`Clone` mean. * [Reference Counting (`Rc`/`Arc`)](/05-ownership/07-reference-counting/): when you genuinely need *shared* ownership. * [The Drop Trait and RAII](/05-ownership/08-drop-trait/) — the mechanics behind Rule 3, drop order, and early drop. * [Variables and Mutability](/02-basics/00-variables/): immutability by default, the foundation ownership builds on. * [Function Parameters](/03-functions/01-parameters/) — choosing between owned and borrowed parameters. * [Data Structures](/06-data-structures/) — how ownership flows through structs and enums. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1 [Section titled “Exercise 1”](#exercise-1) **Difficulty:** Easy **Objective:** Recognize a use-after-move and fix it with a clone. **Instructions:** The following code does not compile because `username` is moved into `greet` and then used again. Make it compile while still logging the username *and* greeting with it. Do not change the signature of `greet`. ```rust 1 fn greet(name: String) { 2 println!("Welcome, {name}!"); 3 } 4 5 fn main() { 6 let username = String::from("ada_lovelace"); 7 greet(username); 8 println!("Logging in: {username}"); // does not compile (error[E0382]) 9 } ``` Solution Clone before moving so each call has its own owned `String`, and log first for clarity: ```rust 1 fn greet(name: String) { 2 println!("Welcome, {name}!"); 3 } 4 5 fn main() { 6 let username = String::from("ada_lovelace"); 7 let display = username.clone(); // clone so both names own data 8 println!("Logging in: {username}"); 9 greet(display); // move the clone into greet 10 } ``` Output: ```plaintext 1 Logging in: ada_lovelace 2 Welcome, ada_lovelace! ``` > A borrow (`fn greet(name: &str)`) would be even better here, but the exercise fixed the signature, so cloning is the right tool. You’ll learn the borrow version in [Borrowing and References](/05-ownership/02-borrowing/). ### Exercise 2 [Section titled “Exercise 2”](#exercise-2) **Difficulty:** Medium **Objective:** Use the “give it away, get it back” pattern to keep working with a value after a function consumes it. **Instructions:** Write a function `append_event` that takes ownership of a `String` log and an event name (`&str`), appends `" "` to the log, and **returns the updated `String`** so the caller can keep using it. Call it twice in `main` to build up a log, then print it. Starter: ```rust 1 fn main() { 2 let mut log = String::from("event:"); 3 log = append_event(log, "login"); 4 log = append_event(log, "click"); 5 println!("{log}"); // should print: event: login click 6 } 7 8 fn append_event(/* ??? */) -> String { 9 // TODO 10 } ``` Solution ```rust 1 fn main() { 2 let mut log = String::from("event:"); 3 log = append_event(log, "login"); // give it away, get the updated one back 4 log = append_event(log, "click"); 5 println!("{log}"); 6 } 7 8 fn append_event(mut log: String, event: &str) -> String { 9 log.push(' '); 10 log.push_str(event); 11 log // return ownership to the caller 12 } ``` Output: ```plaintext 1 event: login click ``` Note the `mut log: String` parameter: the binding takes ownership *and* is allowed to mutate the value it owns, then hands the same allocation back. No clone, no extra allocation per call. ### Exercise 3 [Section titled “Exercise 3”](#exercise-3) **Difficulty:** Medium/Hard **Objective:** Demonstrate that Rule 3 (drop at end of scope) is deterministic and predict the cleanup order. **Instructions:** Define a `Timer` struct holding a `name: String` and implement `Drop` for it so that dropping prints `[] finished, cleaning up`. In `main`, create a `Timer` named `"handle_request"`, then in an *inner block* create a second `Timer` named `"db_query"` and print `Running query...` inside that block. After the block, print `Sending response...`. Before running it, write down the order in which the two messages will print, then confirm. Solution ```rust 1 struct Timer { 2 name: String, 3 } 4 5 impl Drop for Timer { 6 fn drop(&mut self) { 7 println!("[{}] finished, cleaning up", self.name); 8 } 9 } 10 11 fn main() { 12 println!("Program start"); 13 let _request = Timer { name: String::from("handle_request") }; 14 { 15 let _db = Timer { name: String::from("db_query") }; 16 println!("Running query..."); 17 } // _db dropped here — at the end of the inner block 18 println!("Sending response..."); 19 } // _request dropped here — at the end of main ``` Output: ```plaintext 1 Program start 2 Running query... 3 [db_query] finished, cleaning up 4 Sending response... 5 [handle_request] finished, cleaning up ``` The inner `db_query` timer is cleaned up the instant its block ends, *before* `Sending response...` prints: that is Rule 3 in action. The outer `handle_request` timer survives until the end of `main`. This deterministic, scope-bound cleanup is the foundation of RAII patterns like database transactions and lock guards, explored in [The Drop Trait and RAII](/05-ownership/08-drop-trait/). > **Note:** The bindings are named with a leading underscore (`_request`, `_db`) so the compiler doesn’t warn that they’re “unused”; they exist only for their drop side effect, which is a perfectly legitimate use. # Borrowing & References in Rust > A &T reference lends read-only access without moving a value, so the owner keeps it. Rust's borrow checker proves at compile time no reference ever dangles. In TypeScript and JavaScript, you pass objects and arrays around by reference all day without thinking about it, and you accept the consequence that any function might quietly mutate your data. Rust gives you references too, but with a twist: the compiler tracks every borrow and guarantees, at compile time, that a reference can never outlive the data it points to. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **reference** (written `&value`) lets a function read or use a value **without taking ownership of it**: the original owner keeps the value and can use it again afterward. Rust’s **borrow checker** verifies, while compiling, that every reference points to live data, which is how Rust eliminates an entire category of bugs (dangling pointers, use-after-free) that you would otherwise debug at runtime. This page covers **shared (immutable) references**: the `&T` borrow that lets you read. Mutable references (`&mut T`) and their exclusivity rule have their own page: see [Mutable References](/05-ownership/03-mutable-references/). *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In JavaScript, objects and arrays are always handled through references. When you pass one to a function, the function receives a pointer to the same underlying object, so it can mutate your data, and the change is visible to you afterward. ```typescript 1 // TypeScript/JavaScript - objects are passed by reference 2 interface User { 3 name: string; 4 email: string; 5 loginCount: number; 6 } 7 8 function describe(user: User): string { 9 return `${user.name} <${user.email}> logged in ${user.loginCount} times`; 10 } 11 12 // A function can mutate the object you handed it... 13 function recordLogin(user: User): void { 14 user.loginCount += 1; // mutates the caller's object! 15 } 16 17 const user: User = { name: "Ada", email: "ada@example.com", loginCount: 7 }; 18 19 console.log(describe(user)); // read it 20 recordLogin(user); // and silently change it 21 console.log(user.loginCount); // 8 — the original object changed 22 23 // Aliasing: two names, one object 24 const alias = user; 25 alias.loginCount = 0; 26 console.log(user.loginCount); // 0 — `user` and `alias` ARE the same object ``` **Key points:** * Objects/arrays are passed and assigned **by reference**. * Any holder of the reference can mutate the shared object. * There is no language-level distinction between “I want to read this” and “I want to change this.” You rely on convention, documentation, or defensive copies (`structuredClone`, spreads) to stay safe. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust makes the distinction explicit. A plain `&` reference is a **read-only loan**: the borrower may look at the value but not change it. The owner keeps the value the whole time. ```rust 1 #[derive(Debug)] 2 struct User { 3 name: String, 4 email: String, 5 login_count: u32, 6 } 7 8 // `&User` is a SHARED reference: read-only access, no ownership taken. 9 fn describe(user: &User) -> String { 10 format!( 11 "{} <{}> logged in {} times", 12 user.name, user.email, user.login_count 13 ) 14 } 15 16 fn is_active(user: &User) -> bool { 17 user.login_count > 0 18 } 19 20 fn main() { 21 let user = User { 22 name: String::from("Ada"), 23 email: String::from("ada@example.com"), 24 login_count: 7, 25 }; 26 27 // Borrow the same value as many times as we like. 28 println!("{}", describe(&user)); 29 println!("active? {}", is_active(&user)); 30 31 // `user` is still fully owned here — nothing was moved or consumed. 32 println!("{:?}", user); 33 } ``` **Output (compile-verified):** ```text 1 Ada logged in 7 times 2 active? true 3 User { name: "Ada", email: "ada@example.com", login_count: 7 } ``` **Key points:** * `&user` creates a **shared borrow**; `&User` is the type “shared reference to a `User`.” * The function borrows the value, uses it, and gives it back; `user` is usable afterward. * A shared reference cannot be used to mutate. To change the value, you would need a mutable reference (`&mut`), covered on the next page. > **Note:** Without borrowing, passing `user` into `describe` would **move** it (transfer ownership) and you could no longer use `user` afterward. Borrowing is how you avoid that. See [Ownership Rules](/05-ownership/01-ownership-rules/) and [Move, Copy, Clone](/05-ownership/06-move-copy-clone/) for the full story on moves. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What a reference actually is [Section titled “What a reference actually is”](#what-a-reference-actually-is) A reference is a pointer: a small value that holds the **memory address** of something else. The `&` operator creates a reference; the `*` operator **dereferences** it (follows the pointer to read the value behind it). ```rust 1 fn main() { 2 let x = 10; 3 let r = &x; // r is a reference to x (a pointer under the hood) 4 5 println!("x = {}", x); 6 println!("*r = {}", *r); // explicitly follow the pointer 7 println!("r = {}", r); // most operations auto-deref, so *r is often optional 8 9 // A reference holds the address of what it points at. 10 println!("address of x : {:p}", &x); 11 println!("value held by r : {:p}", r); 12 println!("equal? {}", std::ptr::eq(&x, r)); 13 } ``` **Output (compile-verified; the exact hex addresses vary by run and platform, but the two are always equal):** ```text 1 x = 10 2 *r = 10 3 r = 10 4 address of x : 0x16d025c44 5 value held by r : 0x16d025c44 6 equal? true ``` The two printed addresses are identical because `r` literally points at `x`. In most everyday code you rarely write `*` yourself; Rust auto-dereferences for method calls and field access (`user.name` works whether `user` is a `User` or a `&User`). You reach for `*` mainly when you need the value itself, such as in arithmetic (`*r + 1`). > **Note:** Unlike a JavaScript reference, a Rust reference is **guaranteed non-null and always valid** for as long as it exists. There is no `null`, no `undefined`, and no dangling pointer; the compiler proves this before your program ever runs. ### Borrowing instead of moving [Section titled “Borrowing instead of moving”](#borrowing-instead-of-moving) Here is the canonical example. We borrow a `String` so the function can measure it without consuming it. ```rust 1 fn main() { 2 let message = String::from("hello, borrow"); 3 4 // Borrow `message` immutably — `len` only needs to read it. 5 let length = calculate_length(&message); 6 7 // `message` is still valid here because we only lent it out. 8 println!("'{}' has length {}", message, length); 9 } 10 11 fn calculate_length(s: &String) -> usize { 12 s.len() 13 } // `s` (the reference) goes out of scope here, but because it is only a 14 // borrow, the underlying String is NOT dropped — the caller still owns it. ``` **Output (compile-verified):** ```text 1 'hello, borrow' has length 13 ``` The action of creating a reference is called **borrowing**. The function `calculate_length` borrows `message`, reads its length, and when `s` goes out of scope only the *reference* is dropped, never the `String` it pointed at. The owner (`main`) gets its value back intact. > **Note:** `&String` is used here purely to mirror the owned-vs-borrowed contrast against the moving version. In production you would write `s: &str` (see [Best Practice #2](#best-practices)), and `cargo clippy` will in fact suggest exactly that via the `clippy::ptr_arg` lint, since `&str` accepts both `&String` and string slices. ### Many shared borrows at once are fine [Section titled “Many shared borrows at once are fine”](#many-shared-borrows-at-once-are-fine) A shared reference promises **read-only** access. Because no one can mutate, it is perfectly safe to hand out any number of shared references simultaneously: ```rust 1 fn main() { 2 let data = vec![1, 2, 3, 4, 5]; 3 4 let first = &data; 5 let second = &data; 6 let third = &data; 7 8 // Many simultaneous shared borrows are allowed: nobody can mutate. 9 println!("sum via first = {}", first.iter().sum::()); 10 println!("len via second = {}", second.len()); 11 println!("max via third = {:?}", third.iter().max()); 12 13 // The original owner is still usable too. 14 println!("data = {:?}", data); 15 } ``` **Output (compile-verified):** ```text 1 sum via first = 15 2 len via second = 5 3 max via third = Some(5) 4 data = [1, 2, 3, 4, 5] ``` This is the “shared” half of Rust’s central borrowing rule: **either many shared (`&`) references, or exactly one mutable (`&mut`) reference, but never both at the same time.** The exclusivity of `&mut` is the subject of the [Mutable References](/05-ownership/03-mutable-references/) page; here it is enough to know that as long as you only borrow with `&`, you can have as many borrows as you want. ### The borrow checker [Section titled “The borrow checker”](#the-borrow-checker) The **borrow checker** is the part of the Rust compiler that tracks the lifetime of every reference and rejects any program where a reference could point at data that is gone or is being mutated out from under it. It runs at compile time, so the checks cost nothing at runtime. The two guarantees most relevant to shared references are: 1. A reference may never outlive the value it borrows (no dangling references). 2. While any shared reference exists, the borrowed value cannot be mutated or moved. (The exception is *interior mutability* — types like `Cell`, `RefCell`, and `Mutex` that allow controlled mutation behind `&T`; they are the subject of [Smart Pointers](/10-smart-pointers/02-refcell-mutex/).) You do not call the borrow checker; it is simply part of `cargo build` / `cargo check`. When it rejects your code you get an error like `E0597` (“does not live long enough”) or `E0502` (“cannot borrow as mutable because it is also borrowed as immutable”). Reading those errors is a core Rust skill — they almost always point at exactly the right fix. ### Dangling references are impossible [Section titled “Dangling references are impossible”](#dangling-references-are-impossible) In C you can return a pointer to a local variable and get undefined behavior. In JavaScript you can’t even express the problem because the GC keeps anything reachable alive. Rust takes a third path: it makes the dangling case a **compile error**. ```rust 1 // does not compile (error[E0106]: missing lifetime specifier) 2 fn dangle() -> &String { 3 let s = String::from("temporary"); 4 &s // returning a reference to `s`... 5 } // ...but `s` is dropped here, so the reference would dangle ``` The compiler refuses this outright (see [Common Pitfalls](#common-pitfalls) for the full message). The fix is to return the **owned** `String` instead of a reference to it. Then ownership moves out to the caller and nothing is left dangling: ```rust 1 fn no_dangle() -> String { 2 let s = String::from("temporary"); 3 s // ownership moves out to the caller — perfectly safe 4 } 5 6 fn main() { 7 let owned = no_dangle(); 8 println!("{}", owned); 9 } ``` *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | TypeScript/JavaScript | Rust | | --------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------- | | How objects are passed | Always by reference, implicitly | You choose: by value (move/copy) or by reference (`&` / `&mut`) | | Read vs. write intent | Not expressed in the language | `&T` = read-only, `&mut T` = read/write | | Can the callee mutate my data? | Yes, silently, unless you copy defensively | Only if you explicitly lend a `&mut` | | Dangling references | Impossible (GC keeps things alive) | Impossible (compiler rejects them), but **without** a garbage collector | | Multiple holders mutating at once | Allowed (a common bug source) | Forbidden at compile time for `&mut`; unlimited for `&` | | Cost | GC bookkeeping, allocation pressure | Zero runtime cost; checks happen at compile time | | `null` / `undefined` references | Possible (`obj?.field`) | A `&T` is never null; absence is modeled with `Option<&T>` | ### The big mental shift [Section titled “The big mental shift”](#the-big-mental-shift) In JavaScript, “passing a reference” is the *only* option and it always grants full mutation rights to the callee. In Rust, references are **explicit, typed, and read-only by default**. A function signature like `fn save(user: &User)` is a machine-checked promise: “I will look at your `User`, I will not change it, and I will not keep it after I return.” That promise is enforced by the compiler, not by code review. > **Tip:** When migrating a mental model, read `&T` as “a temporary read-only loan of a `T`.” The owner is guaranteed to still have the value when the loan ends. ### Borrowing vs. cloning [Section titled “Borrowing vs. cloning”](#borrowing-vs-cloning) A JavaScript habit is to defensively copy (`{ ...obj }`, `structuredClone(obj)`) to avoid accidental shared mutation. In Rust, borrowing usually replaces that copy entirely: you hand out a cheap `&` reference instead of duplicating data. Reach for `.clone()` only when you genuinely need a second independent owner — see [Move, Copy, Clone](/05-ownership/06-move-copy-clone/). *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Returning a reference to a local value [Section titled “Pitfall 1: Returning a reference to a local value”](#pitfall-1-returning-a-reference-to-a-local-value) This is the dangling-reference attempt. The borrowed value would be destroyed at the end of the function. ```rust 1 // does not compile 2 fn dangle() -> &String { 3 let s = String::from("temporary"); 4 &s 5 } 6 7 fn main() { 8 let r = dangle(); 9 println!("{}", r); 10 } ``` **Real compiler error:** ```text 1 error[E0106]: missing lifetime specifier 2 --> src/main.rs:2:16 3 | 4 2 | fn dangle() -> &String { 5 | ^ expected named lifetime parameter 6 | 7 = help: this function's return type contains a borrowed value, but there is no value for it to be borrowed from 8 help: consider using the `'static` lifetime, but this is uncommon unless you're returning a borrowed value from a `const` or a `static` 9 | 10 2 | fn dangle() -> &'static String { 11 | +++++++ 12 help: instead, you are more likely to want to return an owned value 13 | 14 2 - fn dangle() -> &String { 15 2 + fn dangle() -> String { 16 | ``` **Fix:** Return the owned `String` (drop the `&`). The compiler’s last suggestion is exactly right. When you genuinely need to return a borrow, it must borrow from one of the function’s *inputs*, which is what [Lifetimes](/05-ownership/04-lifetimes/) are about. ### Pitfall 2: Using a value after its referent has been dropped [Section titled “Pitfall 2: Using a value after its referent has been dropped”](#pitfall-2-using-a-value-after-its-referent-has-been-dropped) A subtler version: the reference outlives the value’s scope. ```rust 1 // does not compile 2 fn main() { 3 let reference; 4 { 5 let value = String::from("short-lived"); 6 reference = &value; 7 } // `value` is dropped here 8 println!("{}", reference); // tries to use the freed value 9 } ``` **Real compiler error:** ```text 1 error[E0597]: `value` does not live long enough 2 --> src/main.rs:6:21 3 | 4 5 | let value = String::from("short-lived"); 5 | ----- binding `value` declared here 6 6 | reference = &value; 7 | ^^^^^^ borrowed value does not live long enough 8 7 | } // `value` is dropped here 9 | - `value` dropped here while still borrowed 10 8 | println!("{}", reference); // tries to use the freed value 11 | --------- borrow later used here ``` **Fix:** Make the borrowed value live at least as long as the reference, usually by declaring `value` in the outer scope. In a GC language this code would “work” by keeping `value` alive; Rust instead tells you the lifetimes don’t line up. ### Pitfall 3: Passing by value when you meant to borrow [Section titled “Pitfall 3: Passing by value when you meant to borrow”](#pitfall-3-passing-by-value-when-you-meant-to-borrow) A very common beginner mistake: forgetting the `&`, which **moves** the value into the function. ```rust 1 // does not compile 2 fn print_it(s: String) { 3 println!("{}", s); 4 } 5 6 fn main() { 7 let owned = String::from("data"); 8 print_it(owned); // moves `owned` into the function 9 println!("{}", owned); // try to use it again 10 } ``` **Real compiler error (abridged):** ```text 1 error[E0382]: borrow of moved value: `owned` 2 --> src/main.rs:9:20 3 | 4 7 | let owned = String::from("data"); 5 | ----- move occurs because `owned` has type `String`, which does not implement the `Copy` trait 6 8 | print_it(owned); // moves `owned` into the function 7 | ----- value moved here 8 9 | println!("{}", owned); // try to use it again 9 | ^^^^^ value borrowed here after move 10 | 11 note: consider changing this parameter type in function `print_it` to borrow instead if owning the value isn't necessary 12 help: consider cloning the value if the performance cost is acceptable 13 | 14 8 | print_it(owned.clone()); // moves `owned` into the function 15 | ++++++++ ``` **Fix:** Borrow instead of moving: change the signature to `fn print_it(s: &String)` (or better, `s: &str`) and call it as `print_it(&owned)`. Cloning also compiles, but it needlessly duplicates the data; prefer borrowing. ### Pitfall 4: Trying to mutate through a shared reference [Section titled “Pitfall 4: Trying to mutate through a shared reference”](#pitfall-4-trying-to-mutate-through-a-shared-reference) A shared `&` reference is read-only. Attempting to write through it is a compile error. ```rust 1 // does not compile 2 fn main() { 3 let mut count = 0; 4 let r = &count; // shared (immutable) reference 5 *r += 1; // try to mutate through it 6 println!("{}", count); 7 } ``` **Real compiler error (abridged):** ```text 1 error[E0594]: cannot assign to `*r`, which is behind a `&` reference 2 --> src/main.rs:4:5 3 | 4 4 | *r += 1; // try to mutate through it 5 | ^^^^^^^ `r` is a `&` reference, so the data it refers to cannot be written 6 | 7 help: consider changing this to be a mutable reference 8 | 9 3 | let r = &mut count; 10 | +++ ``` **Fix:** Use `&mut count` to get a mutable reference (and note that `count` is already `let mut`). Mutable borrows have their own exclusivity rule — read [Mutable References](/05-ownership/03-mutable-references/) next. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Borrow by default; take ownership only when you must [Section titled “1. Borrow by default; take ownership only when you must”](#1-borrow-by-default-take-ownership-only-when-you-must) If a function only needs to *read* a value, take it by shared reference. This is the most flexible and cheapest signature — callers keep their data and pay nothing for the call. ```rust 1 // Idiomatic: read-only access via a shared borrow 2 fn word_count(text: &str) -> usize { 3 text.split_whitespace().count() 4 } ``` ### 2. Prefer `&str` over `&String`, and `&[T]` over `&Vec` [Section titled “2. Prefer \&str over \&String, and &\[T\] over \&Vec\”](#2-prefer-str-over-string-and-t-over-vect) A `&str` accepts both string literals and borrowed `String`s (via automatic deref coercion), so it is strictly more general. Likewise, `&[T]` accepts arrays, `Vec`s, and other slices. ```rust 1 fn shout(text: &str) -> String { 2 text.to_uppercase() 3 } 4 5 fn main() { 6 let owned = String::from("hello"); 7 println!("{}", shout(&owned)); // &String coerces to &str 8 println!("{}", shout("world")); // &str literal works too 9 } ``` > **Tip:** Clippy will actively suggest changing `&String` parameters to `&str` and `&Vec` to `&[T]`. Following this makes your APIs accept more callers for free. ### 3. Let the compiler guide you [Section titled “3. Let the compiler guide you”](#3-let-the-compiler-guide-you) The borrow-checker errors are unusually good. When you hit one, read the `help:` lines — they frequently contain the literal fix (add `&`, add `mut`, return an owned value). Treat the borrow checker as a pair programmer, not an adversary. ### 4. Reach for references before `.clone()` [Section titled “4. Reach for references before .clone()”](#4-reach-for-references-before-clone) If you find yourself cloning to “make the error go away,” pause: a borrow is usually the right answer and avoids the allocation. Clone only when you truly need a second independent owner. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small order-processing module. Three functions all **borrow** a slice of orders; none takes ownership, so the caller can run every report in sequence on the same data without any copying. ```rust 1 use std::collections::HashMap; 2 3 #[derive(Debug)] 4 struct Order { 5 id: u32, 6 customer: String, 7 total_cents: u64, 8 status: String, 9 } 10 11 // Borrow the orders read-only; sum the paid ones. 12 fn total_revenue(orders: &[Order]) -> u64 { 13 orders 14 .iter() 15 .filter(|o| o.status == "paid") 16 .map(|o| o.total_cents) 17 .sum() 18 } 19 20 // The returned map borrows customer names FROM `orders`, so its keys 21 // (`&str`) live exactly as long as the borrowed slice. No strings copied. 22 fn revenue_by_customer(orders: &[Order]) -> HashMap<&str, u64> { 23 let mut totals: HashMap<&str, u64> = HashMap::new(); 24 for order in orders { 25 if order.status == "paid" { 26 *totals.entry(order.customer.as_str()).or_insert(0) += order.total_cents; 27 } 28 } 29 totals 30 } 31 32 // Return a borrow of one order that lives as long as the input slice. 33 fn find_order<'a>(orders: &'a [Order], id: u32) -> Option<&'a Order> { 34 orders.iter().find(|o| o.id == id) 35 } 36 37 fn main() { 38 let orders = vec![ 39 Order { id: 1, customer: String::from("Ada"), total_cents: 4_500, status: String::from("paid") }, 40 Order { id: 2, customer: String::from("Linus"), total_cents: 9_900, status: String::from("refunded") }, 41 Order { id: 3, customer: String::from("Ada"), total_cents: 1_200, status: String::from("paid") }, 42 ]; 43 44 println!("Total revenue: ${:.2}", total_revenue(&orders) as f64 / 100.0); 45 46 let by_customer = revenue_by_customer(&orders); 47 let mut rows: Vec<_> = by_customer.iter().collect(); 48 rows.sort(); 49 for (customer, cents) in rows { 50 println!(" {customer}: ${:.2}", *cents as f64 / 100.0); 51 } 52 53 match find_order(&orders, 3) { 54 Some(order) => println!("Found order {}: {} cents", order.id, order.total_cents), 55 None => println!("No such order"), 56 } 57 58 // `orders` is still fully owned and usable here. 59 println!("Processed {} orders.", orders.len()); 60 } ``` **Output (compile-verified):** ```text 1 Total revenue: $57.00 2 Ada: $57.00 3 Found order 3: 1200 cents 4 Processed 3 orders. ``` Notice that `revenue_by_customer` returns a `HashMap<&str, u64>` whose keys are *borrowed* from the orders: the borrow checker guarantees the map cannot outlive the data it points into. And `find_order` uses an explicit lifetime (`'a`) to say “the returned reference lives as long as the `orders` slice you gave me.” That annotation is your bridge to the next topics: [Lifetimes](/05-ownership/04-lifetimes/) and [Lifetime Elision](/05-ownership/05-lifetime-elision/). > **Note:** `cargo clippy` will flag `find_order`’s `'a` with `clippy::needless_lifetimes`, because the elision rules let you write `fn find_order(orders: &[Order], id: u32) -> Option<&Order>` and the compiler infers the same lifetime. The explicit `'a` is shown here on purpose, to make the “returned reference borrows from the input” relationship visible before we cover elision. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — References and Borrowing](https://doc.rust-lang.org/book/ch04-02-references-and-borrowing.html) * [The Rust Book — The Slice Type](https://doc.rust-lang.org/book/ch04-03-slices.html) * [Rust by Example — Borrowing](https://doc.rust-lang.org/rust-by-example/scope/borrow.html) * [Rust Reference — References (`&` and `&mut`)](https://doc.rust-lang.org/reference/types/pointer.html) > **Note:** This guide targets the repository’s [pinned verification toolchain](/00-introduction/05-version-policy/) and the 2024 edition; `cargo new` selects that edition automatically. The pin is a reproducible baseline, not a moving “latest stable” claim. ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Section 05 — Ownership (overview)](/05-ownership/) * [Stack vs. Heap](/05-ownership/00-stack-heap/): where the value a reference points at actually lives * [Ownership Rules](/05-ownership/01-ownership-rules/): the rules that make borrowing necessary * [Mutable References](/05-ownership/03-mutable-references/): `&mut` and the one-writer-XOR-many-readers rule * [Lifetimes](/05-ownership/04-lifetimes/): naming how long references stay valid * [Lifetime Elision](/05-ownership/05-lifetime-elision/): when you can omit lifetime annotations * [Move, Copy, Clone](/05-ownership/06-move-copy-clone/): what happens when you *don’t* borrow * [Reference Counting (`Rc` / `Arc`)](/05-ownership/07-reference-counting/): shared ownership when a single owner isn’t enough * [Variables and Mutability](/02-basics/00-variables/): `let` vs `let mut`, the foundation for `&` vs `&mut` * [Introduction](/00-introduction/) and [Getting Started](/01-getting-started/): if you need a refresher on setup * [Section 06 — Data Structures](/06-data-structures/): structs and enums you’ll be borrowing next *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Borrow instead of move [Section titled “Exercise 1: Borrow instead of move”](#exercise-1-borrow-instead-of-move) **Difficulty:** Beginner **Objective:** Convert a function that consumes its argument into one that borrows it. **Instructions:** The function below takes ownership of the `Vec`, so the call site can’t use `names` afterward. Rewrite `longest_name` to **borrow** the data so that `main` can still print `names` at the end. Implement the body so it returns a reference to the longest name. ```rust 1 fn longest_name(names: Vec) -> String { 2 // TODO: borrow instead of consuming; return a reference to the longest name 3 /* ??? */ 4 } 5 6 fn main() { 7 let names = vec![ 8 String::from("Bo"), 9 String::from("Alexander"), 10 String::from("Kai"), 11 ]; 12 println!("Longest: {}", longest_name(/* ??? */)); 13 println!("All names still here: {:?}", names); // must still compile 14 } ``` Solution ```rust 1 fn longest_name(names: &[String]) -> &String { 2 let mut longest = &names[0]; 3 for name in names { 4 if name.len() > longest.len() { 5 longest = name; 6 } 7 } 8 longest 9 } 10 11 fn main() { 12 let names = vec![ 13 String::from("Bo"), 14 String::from("Alexander"), 15 String::from("Kai"), 16 ]; 17 println!("Longest: {}", longest_name(&names)); 18 println!("All names still here: {:?}", names); 19 } ``` **Output:** ```text 1 Longest: Alexander 2 All names still here: ["Bo", "Alexander", "Kai"] ``` Taking `&[String]` (a slice) instead of `Vec` borrows the data, so `names` remains owned by `main`. Returning `&String` hands back a reference into that borrowed slice. ### Exercise 2: Return a borrowed slice [Section titled “Exercise 2: Return a borrowed slice”](#exercise-2-return-a-borrowed-slice) **Difficulty:** Intermediate **Objective:** Write a function that returns a `&str` slice borrowed from its input. **Instructions:** Implement `first_word` so it returns the first whitespace-delimited word of the input as a borrowed slice (no allocation, no `String`). It should accept both `&String` and `&str` literals. ```rust 1 fn first_word(s: &str) -> &str { 2 // TODO: return everything up to the first space, or the whole string 3 /* ??? */ 4 } 5 6 fn main() { 7 let sentence = String::from("borrow checker rules"); 8 println!("{}", first_word(&sentence)); // "borrow" 9 println!("{}", first_word("hello world")); // "hello" 10 println!("{}", sentence); // sentence still usable 11 } ``` Solution ```rust 1 fn first_word(s: &str) -> &str { 2 match s.find(' ') { 3 Some(i) => &s[..i], 4 None => s, 5 } 6 } 7 8 fn main() { 9 let sentence = String::from("borrow checker rules"); 10 println!("{}", first_word(&sentence)); 11 println!("{}", first_word("hello world")); 12 println!("{}", sentence); 13 } ``` **Output:** ```text 1 borrow 2 hello 3 borrow checker rules ``` The returned `&str` borrows from `s`, so it can never outlive the string it slices into; the borrow checker enforces that automatically. Accepting `&str` (rather than `&String`) lets the same function serve both a borrowed `String` and a string literal. ### Exercise 3: Prove that shared borrows alias safely [Section titled “Exercise 3: Prove that shared borrows alias safely”](#exercise-3-prove-that-shared-borrows-alias-safely) **Difficulty:** Intermediate **Objective:** Show that multiple shared references to one value can coexist, and that the value remains usable afterward. **Instructions:** Given the `Counter` struct, write a function `read_twice` that takes **two** shared references to a `Counter` and returns the sum of their `value` fields. In `main`, call it with two borrows of the *same* counter, then print the counter to confirm it was never consumed. ```rust 1 #[derive(Debug)] 2 struct Counter { 3 value: i32, 4 } 5 6 fn read_twice(/* ??? */) -> i32 { 7 // TODO 8 /* ??? */ 9 } 10 11 fn main() { 12 let c = Counter { value: 21 }; 13 println!("Doubled: {}", read_twice(/* ??? */)); 14 println!("{:?}", c); 15 } ``` Solution ```rust 1 #[derive(Debug)] 2 struct Counter { 3 value: i32, 4 } 5 6 fn read_twice(a: &Counter, b: &Counter) -> i32 { 7 a.value + b.value 8 } 9 10 fn main() { 11 let c = Counter { value: 21 }; 12 // Two shared borrows of the same value, at once — perfectly legal. 13 println!("Doubled: {}", read_twice(&c, &c)); 14 println!("{:?}", c); 15 } ``` **Output:** ```text 1 Doubled: 42 2 Counter { value: 21 } ``` Passing `&c` twice creates two simultaneous shared borrows. Because neither can mutate, this is allowed, and `c` is still owned by `main` afterward. (Try changing one parameter to `&mut Counter` and calling `read_twice(&mut c, &c)`: the borrow checker will reject it, which is the exclusivity rule covered in [Mutable References](/05-ownership/03-mutable-references/).) # Mutable References > &mut T borrows a value to mutate it under one rule: one writer XOR many readers, catching at compile time the aliasing bugs JS ships to production. A **mutable reference** (`&mut T`) lets you temporarily borrow a value so you can *change* it without taking ownership. It is the counterpart to the shared, read-only borrows you saw in [Borrowing](/05-ownership/02-borrowing/), but it comes with one strict, far-reaching rule that does not exist in TypeScript or JavaScript. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A mutable reference is a borrow that grants write access. Rust enforces a single rule around them: at any given moment a value may have **either one mutable reference, or any number of shared (read-only) references, never both at once**. This “one writer XOR many readers” rule is checked entirely at compile time, and it is how Rust eliminates whole categories of bugs (iterator invalidation, aliasing surprises, and data races) that a TypeScript/JavaScript developer normally only catches at runtime, if at all. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In JavaScript, objects and arrays are passed by reference, and *any* number of references can read **and** write the same value at the same time. Nothing stops you. ```typescript 1 // TypeScript - any number of aliases can mutate freely 2 interface Account { 3 balance: number; 4 } 5 6 function deposit(account: Account, amount: number): void { 7 account.balance += amount; 8 } 9 10 const account: Account = { balance: 100 }; 11 12 // Two names for the SAME object - both can mutate it: 13 const alias = account; 14 deposit(account, 50); 15 alias.balance -= 10; 16 17 console.log(account.balance); // 140 18 console.log(alias === account); // true - same reference 19 20 // A classic runtime bug: mutating an array while iterating it 21 const nums = [1, 2, 3]; 22 for (const n of nums) { 23 if (n === 1) nums.push(n + 1); // appends a 2 the first (and only) time n is 1 24 } 25 console.log(nums); // [1, 2, 3, 2] - the loop also visited the pushed 2 ``` Two things are worth noticing: * `alias` and `account` are two bindings to **one** object; mutating through either is visible through the other, and there is no compiler check coordinating them. * Mutating `nums` while a `for...of` loop is iterating it is perfectly legal JavaScript. The `1` matches once, so a single `2` is appended; the loop then visits that newly pushed element before ending, because `for...of` re-reads the live array on each step. It does not throw. With a condition that always matched the new last element (e.g. `if (n < 3) nums.push(n + 1)`), this same pattern becomes an accidental infinite loop, and the compiler would never warn you. > **Note:** The output above is real. In Node v22, `for...of` over an array re-reads the live array on each step, so pushed elements *are* visited. `Array.prototype.forEach`, by contrast, silently *ignores* elements added during iteration. Either way, JavaScript hands you a foot-gun and trusts you not to pull the trigger. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust models “I want to change this value through a borrow” explicitly with `&mut`. The compiler then guarantees no other live reference exists while you hold it. ```rust 1 fn deposit(balance: &mut f64, amount: f64) { 2 *balance += amount; // `*` dereferences to reach the value behind the reference 3 } 4 5 fn main() { 6 let mut balance = 100.0; 7 8 deposit(&mut balance, 50.0); // hand out a mutable borrow, then take it back 9 deposit(&mut balance, 25.0); // and again - each borrow is short-lived 10 11 println!("Balance: {}", balance); 12 } ``` ```text 1 Balance: 175 ``` And the JavaScript loop bug? Rust will not even compile it: ```rust 1 fn main() { 2 let mut nums = vec![1, 2, 3]; 3 for n in &nums { // shared borrow held for the whole loop 4 if *n == 2 { 5 nums.push(99); // does not compile (error[E0502]): mutate while borrowed 6 } 7 } 8 } ``` ```text 1 error[E0502]: cannot borrow `nums` as mutable because it is also borrowed as immutable 2 --> src/main.rs:5:13 3 | 4 3 | for n in &nums { // shared borrow for the whole loop 5 | ----- 6 | | 7 | immutable borrow occurs here 8 | immutable borrow later used here 9 4 | if *n == 2 { 10 5 | nums.push(99); // mutate while iterating 11 | ^^^^^^^^^^^^^ mutable borrow occurs here ``` The very bug that JavaScript ships to production is a compile error in Rust. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Creating and using a `&mut` [Section titled “Creating and using a \&mut”](#creating-and-using-a-mut) There are two pieces of syntax to learn: * `&mut value` — *create* a mutable reference (you must own a `mut` binding to do this). * `*reference` — *dereference*: follow the reference to read or write the underlying value. ```rust 1 fn main() { 2 let mut count = 0; // the binding must be `mut` to be mutably borrowed 3 let r = &mut count; // r has type &mut i32 4 5 *r += 1; // write through the reference 6 *r += 1; 7 8 println!("{}", count); // 2 - the change is visible through the owner 9 } ``` When you call a method on a reference, Rust inserts the `*` for you (this is *automatic dereferencing*), which is why `r.push(...)` works without writing `(*r).push(...)`. ### `&mut self` methods [Section titled “\&mut self methods”](#mut-self-methods) The most common place you will write `&mut` is method receivers. A method that takes `&mut self` can mutate the struct it is called on: ```rust 1 struct Counter { 2 value: i32, 3 } 4 5 impl Counter { 6 fn increment(&mut self) { 7 self.value += 1; 8 } 9 } 10 11 fn bump_twice(c: &mut Counter) { 12 c.increment(); // reborrow of *c happens automatically 13 c.increment(); 14 } 15 16 fn main() { 17 let mut counter = Counter { value: 0 }; 18 bump_twice(&mut counter); 19 println!("value = {}", counter.value); // value = 2 20 } ``` ```text 1 value = 2 ``` > **Tip:** `&mut self`, `&self`, and `self` are the Rust equivalents of asking “does this method mutate the object, just read it, or consume it entirely?” In a TypeScript class every method silently has full mutable access to `this`; in Rust the receiver type makes the answer part of the signature. ### The one rule: mutable XOR shared [Section titled “The one rule: mutable XOR shared”](#the-one-rule-mutable-xor-shared) This is the heart of the topic. While a `&mut T` to a value is alive, **nothing else** may reference that value: not another `&mut`, and not even a read-only `&`. Conversely, while one or more shared `&T` borrows are alive, **no** `&mut` may exist. You get one of two states: | State | Mutable refs | Shared refs | Analogy | | --------------- | ------------ | ----------- | --------------------- | | Exclusive write | exactly 1 | 0 | A `RwLock` write lock | | Shared read | 0 | many | A `RwLock` read lock | This is sometimes called **“Aliasing XOR Mutability”**: you can have aliasing (many references) *or* mutability (the ability to write), but never both for the same data at the same time. ```rust 1 fn main() { 2 let mut data = vec![1, 2, 3]; 3 4 let a = &mut data; 5 let b = &mut data; // does not compile (error[E0499]): second &mut while first is live 6 7 a.push(4); 8 b.push(5); 9 } ``` ```text 1 error[E0499]: cannot borrow `data` as mutable more than once at a time 2 --> src/main.rs:5:13 3 | 4 4 | let a = &mut data; 5 | --------- first mutable borrow occurs here 6 5 | let b = &mut data; // does not compile (error[E0499]): second &mut while first is live 7 | ^^^^^^^^^ second mutable borrow occurs here 8 6 | 9 7 | a.push(4); 10 | - first borrow later used here ``` ### Non-lexical lifetimes (NLL): a borrow ends at its last use [Section titled “Non-lexical lifetimes (NLL): a borrow ends at its last use”](#non-lexical-lifetimes-nll-a-borrow-ends-at-its-last-use) Earlier (pre-2018) the rule above would have been painfully strict, because a borrow used to last until the end of its enclosing `{}` block. Modern Rust uses **non-lexical lifetimes**: a borrow ends at its **last use**, not at the closing brace. That makes the rule far more pleasant in practice: borrows you are “done with” stop counting immediately. ```rust 1 fn main() { 2 let mut scores = vec![10, 20, 30]; 3 4 let first = &scores[0]; // shared borrow starts 5 println!("First score: {}", first); // ...and ends here (last use of `first`) 6 7 scores.push(40); // mutable borrow is fine now - the shared borrow already ended 8 println!("Scores: {:?}", scores); 9 } ``` ```text 1 First score: 10 2 Scores: [10, 20, 30, 40] ``` Both borrows touch `scores`, yet this compiles: the shared borrow’s lifetime ends after the first `println!`, so the later mutable borrow does not overlap it. If you reordered the code so `first` were used *after* `scores.push(40)`, the borrows would overlap and you would get the `E0502` error from the Quick Overview. > **Note:** “Lifetime” here means the span of code over which a reference is actually used, not a wall-clock duration and not the lexical scope. Annotated lifetimes (`'a`) are a related but separate topic; see [Lifetimes](/05-ownership/04-lifetimes/). ### Why this prevents data races at compile time [Section titled “Why this prevents data races at compile time”](#why-this-prevents-data-races-at-compile-time) A **data race** is when two or more threads access the same memory at the same time, at least one access is a write, and there is no synchronization. The mutable-XOR-shared rule makes data races *structurally impossible*: if writing requires exclusive access, two threads can never both hold a writer to the same data. The borrow checker enforces this even across threads. Here two scoped threads each try to mutate the same counter: ```rust 1 use std::thread; 2 3 fn main() { 4 let mut total = 0u64; 5 6 thread::scope(|s| { 7 s.spawn(|| { 8 total += 1; // does not compile (error[E0499]): both closures want &mut total 9 }); 10 s.spawn(|| { 11 total += 1; 12 }); 13 }); 14 15 println!("{}", total); 16 } ``` ```text 1 error[E0499]: cannot borrow `total` as mutable more than once at a time 2 --> src/main.rs:10:17 3 | 4 6 | thread::scope(|s| { 5 | - has type `&'1 Scope<'1, '_>` 6 7 | s.spawn(|| { 7 | - -- first mutable borrow occurs here 8 | _________| 9 | | 10 8 | | total += 1; // both closures want &mut total 11 | | ----- first borrow occurs due to use of `total` in closure 12 9 | | }); 13 | |__________- argument requires that `total` is borrowed for `'1` 14 10 | s.spawn(|| { 15 | ^^ second mutable borrow occurs here ``` The exact code that would be a *runtime* heisenbug in JavaScript (if JavaScript had shared-memory threads) is a *compile-time* error in Rust. To actually share writable state across threads you must reach for a synchronization type such as `Mutex` or `Arc>`, which re-establish the “one writer at a time” guarantee at runtime, covered in [Reference Counting](/05-ownership/07-reference-counting/) and Section 10. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript | Rust | | ------------------------------ | ------------------------------------------------------- | -------------------------------------------------------- | | Mutating through an alias | Always allowed; unlimited aliases can write | At most one `&mut` at a time; checked at compile time | | Read + write at once | Allowed (reader sees writer’s changes mid-flight) | Forbidden: `&mut` excludes all `&` and vice versa | | Mutating a collection mid-loop | Allowed; silent bugs / accidental infinite loops | Compile error (`E0502`) | | Data races | N/A (single-threaded) / possible with SharedArrayBuffer | Impossible by construction; the type system forbids them | | When a “borrow” ends | No concept; GC reclaims when unreachable | At the reference’s last use (non-lexical lifetimes) | | Declaring intent to mutate | Implicit: every method can mutate `this` | Explicit: `&mut` in the type, `mut` on the binding | ### Mutability is a property of the borrow, not just the value [Section titled “Mutability is a property of the borrow, not just the value”](#mutability-is-a-property-of-the-borrow-not-just-the-value) In JavaScript, a `const` binding to an object still lets you mutate the object. Rust separates three independent questions: 1. Is the **binding** mutable? (`let` vs `let mut`) 2. Is this particular **borrow** allowed to write? (`&` vs `&mut`) 3. Does anyone *else* hold a borrow right now? (the XOR rule) You need a `mut` binding to create a `&mut`, the reference type must be `&mut`, and the borrow checker must confirm exclusivity. All three line up to make “who can change this, and when” explicit. ### `&mut` is not a “pointer you copy around” [Section titled “\&mut is not a “pointer you copy around””](#mut-is-not-a-pointer-you-copy-around) A `&mut T` cannot be freely copied the way a JavaScript reference can. If you pass it along, the original is **reborrowed** (temporarily lent out) and you cannot use it until the reborrow ends. This is what keeps “exactly one writer” true even as the reference travels through function calls. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Forgetting `mut` on the binding [Section titled “Pitfall 1: Forgetting mut on the binding”](#pitfall-1-forgetting-mut-on-the-binding) You cannot take a `&mut` to a value bound with plain `let`. ```rust 1 fn main() { 2 let config = String::from("debug=false"); 3 let r = &mut config; // does not compile (error[E0596]) 4 r.push_str(";verbose=true"); 5 println!("{}", config); 6 } ``` Real compiler output: ```text 1 error[E0596]: cannot borrow `config` as mutable, as it is not declared as mutable 2 --> src/main.rs:3:13 3 | 4 3 | let r = &mut config; // cannot borrow immutable binding as mutable 5 | ^^^^^^^^^^^ cannot borrow as mutable 6 | 7 help: consider changing this to be mutable 8 | 9 2 | let mut config = String::from("debug=false"); 10 | +++ ``` **Fix:** change `let config` to `let mut config`. The compiler even tells you exactly that. ### Pitfall 2: Holding a shared borrow, then trying to mutate [Section titled “Pitfall 2: Holding a shared borrow, then trying to mutate”](#pitfall-2-holding-a-shared-borrow-then-trying-to-mutate) This is the iterator-invalidation bug from the intro, but it also bites in simpler code: ```rust 1 fn main() { 2 let mut items = vec![1, 2, 3]; 3 4 let shared = &items; // shared (immutable) borrow 5 items.push(4); // does not compile (error[E0502]) 6 println!("{:?}", shared); // shared borrow used here, so it is still live 7 } ``` Real compiler output: ```text 1 error[E0502]: cannot borrow `items` as mutable because it is also borrowed as immutable 2 --> src/main.rs:5:5 3 | 4 4 | let shared = &items; // shared (immutable) borrow 5 | ------ immutable borrow occurs here 6 5 | items.push(4); // mutable borrow while shared borrow is live 7 | ^^^^^^^^^^^^^ mutable borrow occurs here 8 6 | println!("{:?}", shared); // shared borrow used here 9 | ------ immutable borrow later used here ``` **Fix:** finish using `shared` *before* the mutation (NLL will then let the borrow end), or take a fresh `&items` after the `push`. ### Pitfall 3: Two `&mut` to the same value [Section titled “Pitfall 3: Two \&mut to the same value”](#pitfall-3-two-mut-to-the-same-value) Expecting JavaScript-style aliasing, a newcomer might hand a function the same mutable reference twice, or split out two mutable borrows. The borrow checker stops the second one (`E0499`, shown in the Detailed Explanation). **Fix:** restructure so only one `&mut` is live at a time, or — for genuinely disjoint parts of a collection — use `split_at_mut` (see Best Practices). ### Pitfall 4: Assuming `*` is optional everywhere [Section titled “Pitfall 4: Assuming \* is optional everywhere”](#pitfall-4-assuming--is-optional-everywhere) Method calls auto-dereference, so `r.push(4)` works. But plain operators do not: writing `r += 1` when `r: &mut i32` fails because you are trying to add to the reference, not the value. You must write `*r += 1`. The rule of thumb: **use `*` whenever you read or assign the value itself** rather than calling a method on it. *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### Keep mutable borrows as short as possible [Section titled “Keep mutable borrows as short as possible”](#keep-mutable-borrows-as-short-as-possible) Because a `&mut` blocks all other access, the idiom is to take it, do the mutation, and let it end immediately. NLL rewards this: the sooner the reference’s last use, the sooner the value is free again. ```rust 1 fn main() { 2 let mut log = Vec::new(); 3 log.push("started"); // implicit short-lived &mut log 4 let len = log.len(); // read access after the &mut already ended 5 println!("{len} entries: {log:?}"); 6 } ``` ### Use `iter_mut()` to mutate every element of a collection [Section titled “Use iter\_mut() to mutate every element of a collection”](#use-iter_mut-to-mutate-every-element-of-a-collection) Do not index in a loop with manual bookkeeping; ask the collection for mutable references to its elements. ```rust 1 fn restock_all(inventory: &mut [u32], extra: u32) { 2 for stock in inventory.iter_mut() { // each `stock` is &mut u32 3 *stock += extra; 4 } 5 } 6 7 fn main() { 8 let mut levels = [10, 20, 30]; 9 restock_all(&mut levels, 5); 10 println!("{levels:?}"); // [15, 25, 35] 11 } ``` ### Reach for `split_at_mut` when you truly need two `&mut` into one collection [Section titled “Reach for split\_at\_mut when you truly need two \&mut into one collection”](#reach-for-split_at_mut-when-you-truly-need-two-mut-into-one-collection) The XOR rule forbids two `&mut` to the *same* value, but two `&mut` to *disjoint* parts are perfectly safe. The standard library exposes this with `split_at_mut`, which hands you two non-overlapping mutable slices: ```rust 1 fn main() { 2 let mut data = vec![1, 2, 3, 4, 5, 6]; 3 4 // Split into two non-overlapping mutable slices. 5 let (left, right) = data.split_at_mut(3); 6 7 left[0] += 100; 8 right[0] += 200; 9 10 println!("{:?}", data); // [101, 2, 3, 204, 5, 6] 11 } ``` ```text 1 [101, 2, 3, 204, 5, 6] ``` ### Prefer `std::mem::swap` / `take` / `replace` over fighting the borrow checker [Section titled “Prefer std::mem::swap / take / replace over fighting the borrow checker”](#prefer-stdmemswap--take--replace-over-fighting-the-borrow-checker) When you need to move a value *out* through a `&mut` (e.g. to reset a field), these helpers do it without a second borrow: ```rust 1 fn main() { 2 let mut a = String::from("first"); 3 let mut b = String::from("second"); 4 std::mem::swap(&mut a, &mut b); 5 println!("a={a}, b={b}"); // a=second, b=first 6 7 // `take` leaves Default::default() behind and returns the old value. 8 let mut owned = vec![1, 2, 3]; 9 let stolen = std::mem::take(&mut owned); 10 println!("stolen={stolen:?}, owned={owned:?}"); // stolen=[1, 2, 3], owned=[] 11 } ``` ```text 1 a=second, b=first 2 stolen=[1, 2, 3], owned=[] ``` ### Expose mutation through `&mut self` methods, not public fields [Section titled “Expose mutation through \&mut self methods, not public fields”](#expose-mutation-through-mut-self-methods-not-public-fields) Returning a `&mut` to internal state ties that reference’s lifetime to the borrow of `self`, so the XOR rule still protects your invariants: ```rust 1 struct Config { 2 retries: u32, 3 } 4 5 impl Config { 6 fn retries_mut(&mut self) -> &mut u32 { 7 &mut self.retries 8 } 9 } 10 11 fn main() { 12 let mut config = Config { retries: 3 }; 13 *config.retries_mut() += 2; 14 println!("retries = {}", config.retries); // retries = 5 15 } ``` *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small inventory service. Notice how each mutation goes through a clearly scoped mutable borrow: `apply_sale` borrows one product, `restock_all` borrows the whole slice, and the final read-only loop only runs once all mutable borrows have ended. ```rust 1 #[derive(Debug)] 2 struct Product { 3 name: String, 4 stock: u32, 5 price_cents: u64, 6 } 7 8 /// Applies a sale to a single product: drops the price by `percent` 9 /// and reserves `qty` units. Mutates in place through `&mut Product`. 10 fn apply_sale(product: &mut Product, percent: u64, qty: u32) { 11 product.price_cents -= product.price_cents * percent / 100; 12 product.stock = product.stock.saturating_sub(qty); 13 } 14 15 /// Bulk update: one mutable borrow of the whole slice, mutating each element. 16 fn restock_all(inventory: &mut [Product], extra: u32) { 17 for product in inventory.iter_mut() { 18 product.stock += extra; 19 } 20 } 21 22 fn main() { 23 let mut inventory = vec![ 24 Product { name: "Keyboard".into(), stock: 12, price_cents: 7999 }, 25 Product { name: "Mouse".into(), stock: 30, price_cents: 2999 }, 26 ]; 27 28 // One mutable borrow at a time, scoped to the call: 29 apply_sale(&mut inventory[0], 25, 2); 30 31 // A mutable borrow of the whole slice for a bulk update: 32 restock_all(&mut inventory, 5); 33 34 // Read-only pass: no &mut is alive here, so a shared borrow is fine. 35 for product in &inventory { 36 println!( 37 "{:<10} stock={:>3} price=${:.2}", 38 product.name, 39 product.stock, 40 product.price_cents as f64 / 100.0 41 ); 42 } 43 } ``` ```text 1 Keyboard stock= 15 price=$60.00 2 Mouse stock= 35 price=$29.99 ``` In TypeScript you would write the equivalent freely, with several aliases all able to mutate `inventory` concurrently. The Rust version reads almost the same, but the compiler has verified that no two parts of the program can mutate the same product at the same time, and it cost you nothing at runtime. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — References and Borrowing](https://doc.rust-lang.org/book/ch04-02-references-and-borrowing.html) * [The Rust Book — Fearless Concurrency](https://doc.rust-lang.org/book/ch16-00-concurrency.html) * [The Rust Reference — Lifetime and Borrow Rules](https://doc.rust-lang.org/reference/expressions.html#mutability) * [`slice::split_at_mut`](https://doc.rust-lang.org/std/primitive.slice.html#method.split_at_mut) * [`std::mem::swap`](https://doc.rust-lang.org/std/mem/fn.swap.html), [`std::mem::take`](https://doc.rust-lang.org/std/mem/fn.take.html), [`std::mem::replace`](https://doc.rust-lang.org/std/mem/fn.replace.html) ### Related Topics in This Guide [Section titled “Related Topics in This Guide”](#related-topics-in-this-guide) * [Borrowing](/05-ownership/02-borrowing/): shared `&` references, where mutable references build from * [Ownership Rules](/05-ownership/01-ownership-rules/): the rules that mutable references operate within * [Stack and Heap](/05-ownership/00-stack-heap/): what `&mut` actually points at * [Lifetimes](/05-ownership/04-lifetimes/) and [Lifetime Elision](/05-ownership/05-lifetime-elision/) — how long a reference is valid * [Move, Copy, and Clone](/05-ownership/06-move-copy-clone/): moving values vs borrowing them * [Reference Counting](/05-ownership/07-reference-counting/) — shared *ownership* (`Rc`/`Arc`) when one owner is not enough * [Variables and Mutability](/02-basics/00-variables/): the `mut` keyword on bindings * [Data Structures](/06-data-structures/) — `&mut self` methods on structs and enums *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Increment in Place [Section titled “Exercise 1: Increment in Place”](#exercise-1-increment-in-place) **Difficulty:** Easy **Objective:** Write a function that adds 1 to every element of a slice through a mutable reference. **Instructions:** Complete `increment_all` so that it mutates the caller’s data in place (no allocation, no return value). ```rust 1 fn increment_all(values: &mut [i32]) { 2 // TODO: add 1 to every element 3 } 4 5 fn main() { 6 let mut nums = vec![1, 2, 3]; 7 increment_all(&mut nums); 8 println!("{nums:?}"); // expected: [2, 3, 4] 9 } ``` Solution ```rust 1 fn increment_all(values: &mut [i32]) { 2 for v in values.iter_mut() { 3 *v += 1; // `v` is &mut i32, so dereference to write 4 } 5 } 6 7 fn main() { 8 let mut nums = vec![1, 2, 3]; 9 increment_all(&mut nums); 10 println!("{nums:?}"); // [2, 3, 4] 11 } ``` Output: ```text 1 [2, 3, 4] ``` ### Exercise 2: Normalize a Vector [Section titled “Exercise 2: Normalize a Vector”](#exercise-2-normalize-a-vector) **Difficulty:** Medium **Objective:** Mutate a vector of `f64` in place so every value is divided by the maximum, without holding two conflicting borrows. **Instructions:** Implement `normalize`. First compute the maximum (a read-only pass), then scale every element (a mutable pass). The trick is to make sure the read borrow has fully ended before the write borrow begins; non-lexical lifetimes will allow this if you compute `max` into its own variable first. ```rust 1 fn normalize(values: &mut Vec) { 2 // TODO: divide every element by the maximum value 3 } 4 5 fn main() { 6 let mut samples = vec![2.0, 4.0, 8.0]; 7 normalize(&mut samples); 8 println!("{samples:?}"); // expected: [0.25, 0.5, 1.0] 9 } ``` Solution ```rust 1 fn normalize(values: &mut Vec) { 2 // Read pass: the shared borrow inside `iter()` ends when `max` is computed. 3 let max = values.iter().cloned().fold(f64::MIN, f64::max); 4 if max == 0.0 { 5 return; // avoid dividing by zero 6 } 7 // Write pass: now the &mut is exclusive. 8 for v in values.iter_mut() { 9 *v /= max; 10 } 11 } 12 13 fn main() { 14 let mut samples = vec![2.0, 4.0, 8.0]; 15 normalize(&mut samples); 16 println!("{samples:?}"); // [0.25, 0.5, 1.0] 17 } ``` Output: ```text 1 [0.25, 0.5, 1.0] ``` ### Exercise 3: A Counter with `&mut self` [Section titled “Exercise 3: A Counter with \&mut self”](#exercise-3-a-counter-with-mut-self) **Difficulty:** Medium **Objective:** Build a `Counter` struct whose `increment` method mutates the counter through `&mut self` and returns the new value. **Instructions:** Implement `Counter::new` and `Counter::increment`. Calling `increment` twice on a fresh counter should print `1` then `2`. Think about why the binding in `main` must be `mut`. ```rust 1 struct Counter { 2 count: u32, 3 } 4 5 impl Counter { 6 fn new() -> Self { 7 // TODO 8 } 9 10 fn increment(&mut self) -> u32 { 11 // TODO: bump the count and return the new value 12 } 13 } 14 15 fn main() { 16 let mut c = Counter::new(); 17 println!("{}", c.increment()); // 1 18 println!("{}", c.increment()); // 2 19 } ``` Solution ```rust 1 struct Counter { 2 count: u32, 3 } 4 5 impl Counter { 6 fn new() -> Self { 7 Counter { count: 0 } 8 } 9 10 fn increment(&mut self) -> u32 { 11 self.count += 1; 12 self.count 13 } 14 } 15 16 fn main() { 17 let mut c = Counter::new(); // `mut` is required to call a &mut self method 18 println!("{}", c.increment()); // 1 19 println!("{}", c.increment()); // 2 20 } ``` Output: ```text 1 1 2 2 ``` `main`’s binding must be `let mut c` because `increment` takes `&mut self`: calling it implicitly creates a mutable borrow of `c`, which is only allowed on a mutable binding. # Rust Lifetimes Explained > Rust lifetimes ('a) prove every reference stays valid without a garbage collector. Learn what TypeScript's GC hides and when to annotate functions and structs. In TypeScript and JavaScript, the garbage collector quietly keeps any object alive for as long as *something* still points at it. Rust has no garbage collector, so the compiler must instead **prove** that every reference points at data that is still alive. **Lifetimes** are the labels the compiler uses to track and relate how long borrowed data stays valid, and `'a` annotations are how you spell those relationships out when the compiler cannot figure them out alone. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) A **lifetime** is a region of code during which a reference is guaranteed to be valid. The borrow checker (introduced in [Borrowing](/05-ownership/02-borrowing/) and [Mutable References](/05-ownership/03-mutable-references/)) already tracks lifetimes for *every* reference automatically; **lifetime annotations** like `'a` are simply the syntax you use to describe the *relationship between* the lifetimes of inputs and outputs when a function or struct hands out a reference. They never change how long anything actually lives; they are a contract the compiler verifies, not a runtime mechanism. For a TypeScript developer, the closest mental model is “type-level documentation that the borrow points back into one of the arguments,” enforced at compile time. > **Note:** Lifetimes are the part of Rust that feels most alien at first. The good news: thanks to [lifetime elision](/05-ownership/05-lifetime-elision/), you will write explicit `'a` annotations far less often than you fear. This page explains what they *mean* so the elided cases make sense. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In TypeScript, a function that returns “whichever string is longer” is trivial, and a class that holds a reference to a shared object is just as easy. Nothing forces you to think about how long the underlying data lives: strings.ts ```typescript 1 // Returns whichever argument is longer. The returned string is the 2 // SAME object as one of the inputs (strings are immutable, but the point 3 // stands for objects: no copy is made). 4 function longest(x: string, y: string): string { 5 return x.length > y.length ? x : y; 6 } 7 8 // A class that holds a reference to data it does NOT own. 9 class Parser { 10 private position = 0; 11 12 // `source` is just a reference; the GC keeps it alive as long as 13 // this Parser (or anything else) can still reach it. 14 constructor(private source: string) {} 15 16 nextWord(): string | null { 17 const remaining = this.source.slice(this.position); 18 const match = remaining.match(/\S+/); 19 if (!match) return null; 20 this.position += (match.index ?? 0) + match[0].length; 21 return match[0]; 22 } 23 } 24 25 const result = longest("a long string", "short"); 26 console.log(result); // "a long string" 27 28 const parser = new Parser(" hello world "); 29 let word: string | null; 30 while ((word = parser.nextWord()) !== null) { 31 console.log(word); // "hello", then "world" 32 } ``` **What the runtime does for you here:** * `longest` returns one of its arguments by reference. JavaScript does not care which — the GC keeps both alive until nobody references them. * `Parser` stores `source`. Even if the original variable that created the string goes out of scope, the GC keeps the string alive because the `Parser` still points at it. This “the GC will sort it out” freedom is exactly what Rust removes, and lifetimes are what replace it. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same two patterns in Rust require us to *name* the lifetime relationship with `'a`: ```rust 1 // A function that returns one of its borrowed inputs must declare a 2 // lifetime: the output borrows for as long as BOTH inputs are valid. 3 fn longest<'a>(x: &'a str, y: &'a str) -> &'a str { 4 if x.len() > y.len() { x } else { y } 5 } 6 7 // A struct that holds a reference must declare the lifetime of that reference. 8 // `Parser<'a>` means "this Parser cannot outlive the str it borrows". 9 struct Parser<'a> { 10 source: &'a str, 11 position: usize, 12 } 13 14 impl<'a> Parser<'a> { 15 fn new(source: &'a str) -> Parser<'a> { 16 Parser { source, position: 0 } 17 } 18 19 // The returned slice borrows from `self.source`, so it shares lifetime 'a. 20 fn next_word(&mut self) -> Option<&'a str> { 21 let remaining = &self.source[self.position..]; 22 let start = remaining.find(|c: char| !c.is_whitespace())?; 23 let rest = &remaining[start..]; 24 let end = rest.find(char::is_whitespace).unwrap_or(rest.len()); 25 self.position += start + end; 26 Some(&rest[..end]) 27 } 28 } 29 30 fn main() { 31 let result = longest("a long string", "short"); 32 println!("{result}"); // a long string 33 34 let text = String::from(" hello world "); 35 let mut parser = Parser::new(&text); 36 while let Some(word) = parser.next_word() { 37 println!("{word:?}"); // "hello", then "world" 38 } 39 } ``` Running it prints exactly what the TypeScript version did: ```text 1 a long string 2 "hello" 3 "world" ``` The `<'a>` after the function or struct name introduces a **generic lifetime parameter**, just like `` introduces a generic type parameter. The annotations `&'a str` then say “this reference lives for the region `'a`,” and reusing the same `'a` across multiple spots is how you tie them together. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Why does Rust need lifetimes at all? [Section titled “Why does Rust need lifetimes at all?”](#why-does-rust-need-lifetimes-at-all) Every reference in Rust has a lifetime: the span during which it is valid. Usually the compiler infers it silently (you have already written dozens of references without annotations). Annotations become necessary only when the compiler **cannot tell, from the signature alone, how the lifetimes relate**. Consider `longest` without any annotation: ```rust 1 fn longest(x: &str, y: &str) -> &str { // does not compile (error[E0106]) 2 if x.len() > y.len() { x } else { y } 3 } ``` The compiler rejects this. The returned `&str` borrows from *something*, but which one — `x` or `y`? The body decides at runtime based on `len()`, so the signature is genuinely ambiguous. The real error is: ```text 1 error[E0106]: missing lifetime specifier 2 --> src/main.rs:1:33 3 | 4 1 | fn longest(x: &str, y: &str) -> &str { 5 | ---- ---- ^ expected named lifetime parameter 6 | 7 = help: this function's return type contains a borrowed value, but the 8 signature does not say whether it is borrowed from `x` or `y` 9 help: consider introducing a named lifetime parameter 10 | 11 1 | fn longest<'a>(x: &'a str, y: &'a str) -> &'a str { 12 | ++++ ++ ++ ++ ``` The compiler even suggests the fix. By writing `<'a>` and tagging `x`, `y`, and the return with the same `'a`, you promise: *the returned reference is valid only for as long as **both** `x` and `y` are valid.* That is enough information to check every call site. ### Annotations describe relationships, not durations [Section titled “Annotations describe relationships, not durations”](#annotations-describe-relationships-not-durations) This is the single most important idea, and the one that trips up newcomers most: > **`'a` does not make anything live longer or shorter. It only describes how the lifetime of one reference relates to another.** `<'a>` is generic. At each call site, the compiler picks the *smallest concrete region* that satisfies all the `'a` constraints, typically the overlap of all the inputs’ lifetimes. You are not choosing a duration; you are stating a rule the borrow checker must respect. ### How the constraint is enforced at the call site [Section titled “How the constraint is enforced at the call site”](#how-the-constraint-is-enforced-at-the-call-site) The annotation pays off when references have *different* scopes. This compiles, because both inputs and the use of `result` all overlap: ```rust 1 fn longest<'a>(x: &'a str, y: &'a str) -> &'a str { 2 if x.len() > y.len() { x } else { y } 3 } 4 5 fn main() { 6 let s1 = String::from("a long string"); 7 let result; 8 { 9 let s2 = String::from("short"); 10 result = longest(s1.as_str(), s2.as_str()); 11 println!("The longest string is: {result}"); // used INSIDE the inner scope 12 } 13 } ``` ```text 1 The longest string is: a long string ``` But move the `println!` *out* of the inner block, so `result` is used after `s2` has been dropped, and the borrow checker stops you, because the return *might* have borrowed from `s2`: ```rust 1 fn main() { 2 let s1 = String::from("a long string"); 3 let result; 4 { 5 let s2 = String::from("short"); 6 result = longest(s1.as_str(), s2.as_str()); 7 } // s2 dropped here 8 println!("The longest string is: {result}"); // does not compile (error[E0597]) 9 } ``` The real compiler error is precise about the cause: ```text 1 error[E0597]: `s2` does not live long enough 2 --> src/main.rs:10:39 3 | 4 9 | let s2 = String::from("short"); 5 | -- binding `s2` declared here 6 10 | result = longest(s1.as_str(), s2.as_str()); 7 | ^^ borrowed value does not live long enough 8 11 | } // s2 dropped here 9 | - `s2` dropped here while still borrowed 10 12 | println!("The longest string is: {result}"); // does not compile (error[E0597]) 11 | ------ borrow later used here ``` In TypeScript this code is perfectly fine: the GC keeps `s2`’s string alive because `result` still references it. Rust has no GC, so it forbids the dangling reference *at compile time*. This is the same dangling-prevention guarantee from [Borrowing](/05-ownership/02-borrowing/), now lifted to function boundaries. ### Lifetimes in struct definitions [Section titled “Lifetimes in struct definitions”](#lifetimes-in-struct-definitions) When a struct field is a reference, the struct must be parameterized by that reference’s lifetime. `Parser<'a>` means “a `Parser` that borrows a `str` for the region `'a`, and therefore the `Parser` itself cannot outlive that `str`.” ```rust 1 struct Highlight<'a> { 2 text: &'a str, 3 } ``` If you let the borrowed data drop while the struct still holds the reference, the same `E0597` fires: ```rust 1 struct Highlight<'a> { 2 text: &'a str, 3 } 4 5 fn main() { 6 let highlight; 7 { 8 let sentence = String::from("important note"); 9 highlight = Highlight { text: &sentence }; // does not compile (error[E0597]) 10 } // sentence dropped here while still borrowed 11 println!("{}", highlight.text); 12 } ``` ```text 1 error[E0597]: `sentence` does not live long enough 2 --> src/main.rs:9:39 3 | 4 8 | let sentence = String::from("important note"); 5 | -------- binding `sentence` declared here 6 9 | highlight = Highlight { text: &sentence }; 7 | ^^^^^^^^^ borrowed value does not live long enough 8 10 | } 9 | - `sentence` dropped here while still borrowed 10 11 | println!("{}", highlight.text); 11 | -------------- borrow later used here ``` > **Tip:** If a struct holding a reference starts causing lifetime headaches, ask whether it should **own** its data instead (`text: String`). Owning is the simpler default; borrowing structs are an optimization for short-lived “view” types like parsers and iterators. See [Move, Copy, Clone](/05-ownership/06-move-copy-clone/) and [`Rc`/`Arc`](/05-ownership/07-reference-counting/) for the owning alternatives. ### Lifetimes on `impl` blocks [Section titled “Lifetimes on impl blocks”](#lifetimes-on-impl-blocks) The `impl<'a> Parser<'a>` line declares `'a` for the impl and then uses it on the type. The `<'a>` after `impl` is the *declaration*; the `<'a>` after `Parser` is the *use*, exactly mirroring how generic types work with `impl Wrapper`. ### Distinct lifetimes when inputs are unrelated [Section titled “Distinct lifetimes when inputs are unrelated”](#distinct-lifetimes-when-inputs-are-unrelated) You do **not** have to give every reference the same `'a`. If the output only ever borrows from *one* argument, give the others their own lifetime so callers are not over-constrained: ```rust 1 // The return is only ever borrowed from `text`, never from `prefix`, 2 // so they get independent lifetimes 'a and 'b. 3 fn strip_prefix<'a, 'b>(text: &'a str, prefix: &'b str) -> &'a str { 4 if let Some(rest) = text.strip_prefix(prefix) { 5 rest 6 } else { 7 text 8 } 9 } 10 11 fn main() { 12 let path = String::from("/api/users"); 13 let stripped; 14 { 15 let prefix = String::from("/api"); // shorter-lived than `path` 16 stripped = strip_prefix(&path, &prefix); 17 } // `prefix` dropped here — fine, the output never borrowed from it 18 println!("{stripped}"); // /users 19 } ``` ```text 1 /users ``` Had we forced `prefix: &'a str`, the compiler would have demanded `prefix` live as long as the output — an unnecessary restriction that would reject this perfectly safe program. **Use the loosest annotations that are still correct.** ### The `'static` lifetime [Section titled “The 'static lifetime”](#the-static-lifetime) `'static` is a special, built-in lifetime meaning “valid for the entire program.” Every string literal has type `&'static str` because the text is baked into the binary: ```rust 1 fn app_name() -> &'static str { 2 "ts-to-rust" 3 } ``` > **Warning:** Do not reach for `'static` to silence a lifetime error — it almost always makes the problem worse by demanding data live *forever*. The fix is usually to relate lifetimes correctly or to own the data, not to claim `'static`. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / JavaScript | Rust | | ---------------------------------- | ------------------------------------------ | -------------------------------------------------------- | | Keeping referenced data alive | Garbage collector, at runtime | Lifetimes, proven at compile time | | Returning “one of the arguments” | Always fine | Needs a lifetime relating output to inputs | | A class/struct holding a reference | Free; GC tracks reachability | Struct must declare `<'a>`; cannot outlive borrowed data | | Dangling reference | Impossible (GC) but stale data is possible | Rejected by the compiler (`E0597`/`E0515`) | | Runtime cost of the mechanism | GC pauses, extra memory | **Zero**: lifetimes are erased after checking | | ”Forever” reference | Any long-lived object | `'static` | | Where you write it | Nowhere | Function signatures, struct defs, `impl` blocks | The deepest contrast: **lifetimes are a compile-time-only construct.** Like TypeScript types (which are erased before the JS runs), `'a` annotations vanish entirely after the borrow checker has done its job. There is no runtime representation of a lifetime, no overhead, and no equivalent of a GC pause. They are pure, checked documentation of an invariant the machine code already upholds. A second contrast worth internalizing: in TypeScript, a *reference is the cheap default* and copying is the thing you opt into. In Rust, the borrow checker treats every borrow as a liability it must account for, which is precisely why borrowed return values and borrowed struct fields require you to spell out the relationship. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Returning a reference to a local variable [Section titled “Pitfall 1: Returning a reference to a local variable”](#pitfall-1-returning-a-reference-to-a-local-variable) A classic mistake, and one no annotation can rescue, because the data genuinely dies: ```rust 1 fn dangling<'a>() -> &'a str { 2 let s = String::from("temporary"); 3 &s // does not compile (error[E0515]): returns a reference to data owned by the current function 4 } ``` ```text 1 error[E0515]: cannot return reference to local variable `s` 2 --> src/main.rs:3:5 3 | 4 3 | &s // does not compile (error[E0515]): returns a reference to data owned by the current function 5 | ^^ returns a reference to data owned by the current function ``` `s` is dropped when `dangling` returns, so any reference to it would dangle. The compiler is not asking for a lifetime annotation here — it is telling you the design is impossible. **Fix:** return the owned `String` instead of a reference. ### Pitfall 2: Thinking `'a` extends a value’s life [Section titled “Pitfall 2: Thinking 'a extends a value’s life”](#pitfall-2-thinking-a-extends-a-values-life) Newcomers often add `'static` or a longer-looking lifetime hoping to “keep the data around.” It does the opposite of what you imagine — it *requires* the caller to supply data that lives that long, usually producing a worse error. `'a` constrains; it never extends. The fix for “this data does not live long enough” is almost always to restructure ownership (own the data, or make the borrower’s scope shorter), not to relabel the lifetime. ### Pitfall 3: Over-constraining with a single shared lifetime [Section titled “Pitfall 3: Over-constraining with a single shared lifetime”](#pitfall-3-over-constraining-with-a-single-shared-lifetime) Reusing one `'a` for every parameter when the output only borrows from one of them forces callers to keep *all* arguments alive as long as the result. This compiles but needlessly rejects valid call sites (as in the `strip_prefix` example). Give unrelated inputs their own lifetimes. ### Pitfall 4: Forgetting the lifetime on the `impl` [Section titled “Pitfall 4: Forgetting the lifetime on the impl”](#pitfall-4-forgetting-the-lifetime-on-the-impl) Writing `impl Parser` instead of `impl<'a> Parser<'a>` fails because `Parser` is not a complete type without its lifetime parameter, just as `impl Wrapper` would fail for `Wrapper`. You must declare `<'a>` after `impl` and then apply it to the type. ### Pitfall 5: Reaching for annotations the compiler does not want [Section titled “Pitfall 5: Reaching for annotations the compiler does not want”](#pitfall-5-reaching-for-annotations-the-compiler-does-not-want) Because of [lifetime elision](/05-ownership/05-lifetime-elision/), many single-reference functions need *no* annotation. Adding `<'a>` everywhere is noise; Clippy’s `needless_lifetimes` lint will flag the redundant ones. Write annotations only when the compiler asks for them or when elision would pick the wrong relationship. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Let elision do the work.** Annotate only when the compiler demands it. See [Lifetime Elision](/05-ownership/05-lifetime-elision/) for the three rules that cover the common cases. * **Prefer owning over borrowing in stored data.** If a struct does not *need* to borrow, store `String`/`Vec` instead of `&str`/`&[T]`. Lifetime-parameterized structs ripple their `'a` through every function that touches them. * **Use the loosest correct lifetimes.** Give unrelated references distinct lifetime parameters so you do not over-constrain callers. * **Name lifetimes meaningfully when there are several.** `'a` is conventional for one; for multiple, descriptive names like `<'input, 'config>` read better than `<'a, 'b, 'c>`. * **Reach for `'static` only when the data truly is static** (literals, leaked allocations, lazily-initialized globals), never as a quick fix. * **When fighting the borrow checker, change the design, not the annotation.** Shorter borrows, cloning ([Move, Copy, Clone](/05-ownership/06-move-copy-clone/)), or shared ownership via [`Rc`/`Arc`](/05-ownership/07-reference-counting/) are usually the real answer. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A log-line parser is a realistic place where borrowing (and therefore lifetimes) earns its keep: parsing a `&str` into structured fields that are *slices of the original buffer* avoids allocating new strings for every line, important in a hot logging path. ```rust 1 /// A parsed log line whose fields borrow directly from the original buffer. 2 /// `LogLine<'a>` cannot outlive the string it was parsed from. 3 #[derive(Debug)] 4 struct LogLine<'a> { 5 level: &'a str, 6 message: &'a str, 7 } 8 9 /// Parse "LEVEL: message" into borrowed slices. The `'_` in the return type 10 /// is the elided lifetime tied to `line` (covered in lifetime-elision.md). 11 fn parse_log_line(line: &str) -> Option> { 12 let (level, message) = line.split_once(": ")?; 13 Some(LogLine { 14 level, 15 message: message.trim(), 16 }) 17 } 18 19 fn main() { 20 let raw = String::from("WARN: disk almost full"); 21 let parsed = parse_log_line(&raw).expect("well-formed line"); 22 23 println!("{parsed:?}"); 24 assert_eq!(parsed.level, "WARN"); 25 assert_eq!(parsed.message, "disk almost full"); 26 println!("ok"); 27 } ``` ```text 1 LogLine { level: "WARN", message: "disk almost full" } 2 ok ``` No heap allocation happens during parsing: `level` and `message` are *windows into* `raw`. The `LogLine<'a>` annotation is what lets the compiler guarantee those windows can never outlive `raw`. In TypeScript you would get this “view” behavior for free (substrings reference the same backing data, GC permitting), but you would also have zero compile-time protection against using a `LogLine` after its source buffer became unreachable. Rust makes the same zero-copy design *and* makes the dangling case a compile error. > **Tip:** When a borrowing parser like this becomes awkward to thread through your program, switch the fields to owned `String`s. You trade a small allocation per line for freedom from lifetime parameters, often the right call outside of hot paths. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Validating References with Lifetimes](https://doc.rust-lang.org/book/ch10-03-lifetime-syntax.html) * [The Rust Book — Lifetime Annotations in Struct Definitions](https://doc.rust-lang.org/book/ch10-03-lifetime-syntax.html#lifetime-annotations-in-struct-definitions) * [Rust by Example — Lifetimes](https://doc.rust-lang.org/rust-by-example/scope/lifetime.html) * [Rust Reference — Lifetime elision](https://doc.rust-lang.org/reference/lifetime-elision.html) * [The `'static` lifetime (std docs)](https://doc.rust-lang.org/std/keyword.static.html) * [Error index — E0106](https://doc.rust-lang.org/error_codes/E0106.html), [E0515](https://doc.rust-lang.org/error_codes/E0515.html), [E0597](https://doc.rust-lang.org/error_codes/E0597.html) ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Borrowing](/05-ownership/02-borrowing/): references `&`, shared borrows, and dangling prevention (the foundation for lifetimes) * [Mutable References](/05-ownership/03-mutable-references/): `&mut`, the borrow rules, and non-lexical lifetimes * [Lifetime Elision](/05-ownership/05-lifetime-elision/) — the three rules that let you *omit* most `'a` annotations * [Ownership Rules](/05-ownership/01-ownership-rules/): owners, moves, and scope-based drops that lifetimes build on * [Move, Copy, Clone](/05-ownership/06-move-copy-clone/): owning your data as an alternative to borrowing it * [Reference Counting (`Rc`/`Arc`)](/05-ownership/07-reference-counting/) — shared ownership when a single lifetime will not do * [Stack vs Heap](/05-ownership/00-stack-heap/): where the borrowed data actually lives * [Functions — Parameters](/03-functions/01-parameters/): why slice and `&str` parameters are borrowed * [Basics — Types](/02-basics/01-types/) — the underlying types (`str`, slices) you borrow * [Data Structures](/06-data-structures/): structs and enums that may carry lifetime parameters * [Ownership — Section Overview](/05-ownership/) *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Your first explicit lifetime [Section titled “Exercise 1: Your first explicit lifetime”](#exercise-1-your-first-explicit-lifetime) **Difficulty:** Easy **Objective:** Write a function that returns a borrowed slice of one of its inputs, declaring the lifetime relationship yourself. **Instructions:** Implement `first_word` so it returns the first whitespace-delimited word of `s` as a `&str` borrowed from `s`. If there is no space, return the whole string. Make `first_word("hello world")` return `"hello"` and `first_word("single")` return `"single"`. Write the lifetime annotation explicitly (do not rely on elision for this exercise). ```rust 1 fn first_word<'a>(s: &'a str) -> &'a str { 2 // TODO: find the first space; return the slice before it, or all of `s`. 3 todo!() 4 } ``` Solution ```rust 1 fn first_word<'a>(s: &'a str) -> &'a str { 2 match s.find(' ') { 3 Some(i) => &s[..i], 4 None => s, 5 } 6 } 7 8 fn main() { 9 assert_eq!(first_word("hello world"), "hello"); 10 assert_eq!(first_word("single"), "single"); 11 println!("ex1 ok"); 12 } ``` The single `'a` ties the output slice to the input string, so the compiler knows the returned `&str` cannot outlive `s`. (Thanks to elision, you could drop the annotations entirely here, but writing them out shows what the compiler infers.) ### Exercise 2: A struct that borrows [Section titled “Exercise 2: A struct that borrows”](#exercise-2-a-struct-that-borrows) **Difficulty:** Medium **Objective:** Define a struct that holds a reference, parameterized by a lifetime, and add a method that returns borrows tied to that same lifetime. **Instructions:** Define `Tokenizer<'a>` holding an `input: &'a str`. Add `new(input: &'a str) -> Self` and a method `tokens(&self) -> Vec<&'a str>` that splits `input` on commas and trims whitespace from each token. For input `"a, b ,c"`, `tokens()` must return `vec!["a", "b", "c"]`. Solution ```rust 1 struct Tokenizer<'a> { 2 input: &'a str, 3 } 4 5 impl<'a> Tokenizer<'a> { 6 fn new(input: &'a str) -> Self { 7 Tokenizer { input } 8 } 9 10 fn tokens(&self) -> Vec<&'a str> { 11 self.input.split(',').map(|t| t.trim()).collect() 12 } 13 } 14 15 fn main() { 16 let data = String::from("a, b ,c"); 17 let tk = Tokenizer::new(&data); 18 assert_eq!(tk.tokens(), vec!["a", "b", "c"]); 19 println!("ex2 ok"); 20 } ``` Note that `tokens` returns `Vec<&'a str>`, not `Vec<&str>` tied to `&self`: each token borrows from `self.input` (lifetime `'a`), so the returned slices are valid for as long as the original `data` string lives, independent of how long the `Tokenizer` itself does. ### Exercise 3: Borrowing from a slice and handling emptiness [Section titled “Exercise 3: Borrowing from a slice and handling emptiness”](#exercise-3-borrowing-from-a-slice-and-handling-emptiness) **Difficulty:** Medium–Hard **Objective:** Return a reference into a borrowed collection, relating the output lifetime to the slice, while handling the empty case without panicking. **Instructions:** Implement `longest_in(items: &[String]) -> Option<&str>` that returns the longest string in the slice as a borrowed `&str`, or `None` if the slice is empty. The returned reference must borrow from `items` (so it stays valid as long as `items` does). `longest_in(&["a".into(), "ccc".into(), "bb".into()])` should be `Some("ccc")`; an empty slice should give `None`. Solution ```rust 1 fn longest_in<'a>(items: &'a [String]) -> Option<&'a str> { 2 items 3 .iter() 4 .max_by_key(|s| s.len()) 5 .map(|s| s.as_str()) 6 } 7 8 fn main() { 9 let words = vec![ 10 String::from("a"), 11 String::from("ccc"), 12 String::from("bb"), 13 ]; 14 assert_eq!(longest_in(&words), Some("ccc")); 15 16 let empty: Vec = Vec::new(); 17 assert_eq!(longest_in(&empty), None); 18 println!("ex3 ok"); 19 } ``` `max_by_key` returns `Option<&String>` borrowed from the slice; `.map(|s| s.as_str())` converts the inner `&String` to a `&str` *without* changing the lifetime, so the result is `Option<&'a str>`. The `None` arm handles the empty slice: there is no panic and no need for a sentinel value, mirroring the TypeScript `string | null` return but enforced by the type system. As in Exercise 1, the `'a` here is elidable: `fn longest_in(items: &[String]) -> Option<&str>` compiles identically and is what Clippy’s `needless_lifetimes` lint will nudge you toward. It is written explicitly above to keep the input→output borrow relationship visible while you are still learning to read it. # Lifetime Elision > Rust's three lifetime elision rules let you omit 'a annotations the compiler can infer. See exactly when they apply and why TypeScript never needs them. In the [previous topic](/05-ownership/04-lifetimes/) you saw that references in function signatures sometimes need explicit lifetime annotations like `'a`. But you’ve also written (and will write) hundreds of functions that take and return references *without* a single `'a` in sight. That’s not magic. It’s a small, deterministic set of rules the compiler applies for you called **lifetime elision**. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) **Lifetime elision** is a set of three rules the Rust compiler uses to *infer* lifetimes in function and method signatures so you don’t have to write them by hand. When the rules fully determine every lifetime, you can omit the annotations entirely; when they don’t, the compiler asks you to be explicit. Understanding the rules tells you *exactly* when annotations are required and when they’re just noise: the difference between fighting the borrow checker and ignoring it. **The point:** Elision is not inference of *behavior*; it’s a fixed, predictable shorthand. The same rules run every time, and you can apply them in your head. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) TypeScript has no concept of lifetimes at all, so there’s nothing to elide. The garbage collector keeps any object alive as long as *something* references it, and the type system says nothing about how long a returned reference stays valid: ```typescript 1 // TypeScript: a function that returns part of its input. 2 // The returned string and the input are completely independent 3 // objects as far as the type system is concerned. 4 function firstWord(sentence: string): string { 5 const spaceIndex = sentence.indexOf(" "); 6 return spaceIndex === -1 ? sentence : sentence.slice(0, spaceIndex); 7 } 8 9 class Headers { 10 constructor(private raw: string) {} 11 12 // Returns a substring of `this.raw`. TypeScript tracks the *type* 13 // (string), but nothing about how the result relates to `this`. 14 get(name: string): string | undefined { 15 for (const line of this.raw.split("\n")) { 16 const [key, value] = line.split(": "); 17 if (key.toLowerCase() === name.toLowerCase()) return value; 18 } 19 return undefined; 20 } 21 } 22 23 const headers = new Headers("Host: example.com\nAccept: */*"); 24 console.log(headers.get("host")); // example.com ``` > **Note:** In JavaScript, `slice` returns a brand-new string, so there is no “borrowing” relationship to track. The whole problem lifetime elision solves (*which input does this returned reference borrow from?*) simply does not exist in a garbage-collected language. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Here is the same code in Rust. Notice that **none** of these signatures carry a `'a` annotation, even though they take and return references. The elision rules fill them in: ```rust 1 // One reference in, one reference out: the compiler infers the lifetime. 2 fn first_word(s: &str) -> &str { 3 let bytes = s.as_bytes(); 4 for (i, &byte) in bytes.iter().enumerate() { 5 if byte == b' ' { 6 return &s[..i]; 7 } 8 } 9 s 10 } 11 12 struct Headers<'a> { 13 raw: &'a str, 14 } 15 16 impl<'a> Headers<'a> { 17 fn new(raw: &'a str) -> Self { 18 Headers { raw } 19 } 20 21 // `&self` plus another reference parameter, returning a reference: 22 // elision ties the output to `&self`, so no annotation is needed. 23 fn get(&self, name: &str) -> Option<&str> { 24 self.raw 25 .lines() 26 .filter_map(|line| line.split_once(": ")) 27 .find(|(key, _)| key.eq_ignore_ascii_case(name)) 28 .map(|(_, value)| value) 29 } 30 } 31 32 fn main() { 33 let sentence = String::from("hello world rust"); 34 println!("first word: {}", first_word(&sentence)); 35 36 let headers = Headers::new("Host: example.com\nAccept: */*"); 37 println!("host: {:?}", headers.get("host")); 38 } ``` Running it: ```plaintext 1 first word: hello 2 host: Some("example.com") ``` The signatures are as clean as the TypeScript versions. That’s the whole point of elision. But unlike TypeScript, the compiler has *still verified* that every returned reference is valid for exactly as long as the thing it borrows from. You get the safety guarantee without the syntactic ceremony. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What “elision” actually means [Section titled “What “elision” actually means”](#what-elision-actually-means) Every reference in Rust has a lifetime; that’s non-negotiable. **Elision** (from “to elide,” meaning to omit) is purely about whether *you* have to write that lifetime down. When you write: ```rust 1 fn first_word(s: &str) -> &str { 2 s.split_whitespace().next().unwrap_or("") 3 } ``` the compiler treats it *exactly* as if you had written the fully annotated version: ```rust 1 fn first_explicit<'a>(s: &'a str) -> &'a str { 2 s.split_whitespace().next().unwrap_or("") 3 } ``` Both compile and behave identically; the second is just the *desugared* form of the first. The compiler runs a mechanical procedure to expand the short form into the long form. If that procedure succeeds, the annotations were unnecessary. If it gets stuck, it stops and asks you to annotate. > **Tip:** “Elided” does not mean “ignored” or “inferred from the function body.” The compiler decides lifetimes purely from the *signature*, before it ever looks at the body. This is deliberate: changing a function’s body can never silently change its public lifetime contract. ### The three elision rules [Section titled “The three elision rules”](#the-three-elision-rules) The compiler applies these rules **in order**, to the function signature: 1. **Each elided lifetime in the *parameters* gets its own distinct lifetime.** `fn f(x: &str, y: &str)` is treated as `fn f<'a, 'b>(x: &'a str, y: &'b str)`. The two parameters get *separate* lifetimes. The compiler never assumes two input references live the same length. 2. **If there is exactly one input lifetime (elided or not), it is assigned to every elided *output* lifetime.** `fn f(x: &str) -> &str` becomes `fn f<'a>(x: &'a str) -> &'a str`. The single input is the only thing the output could possibly borrow from, so the compiler wires them together. 3. **If there are multiple input lifetimes *but one of them is `&self` or `&mut self`*, the lifetime of `self` is assigned to every elided output lifetime.** This is the rule that makes methods so ergonomic: a method that returns a reference almost always returns a piece of `self`, so the compiler defaults to that. If, after applying all three rules, any output lifetime is *still* unassigned, elision **fails** and the compiler demands explicit annotations. ### Walking the rules through `first_word` [Section titled “Walking the rules through first\_word”](#walking-the-rules-through-first_word) ```rust 1 fn first_word(s: &str) -> &str { /* ... */ } ``` * **Rule 1** gives the single parameter its own lifetime: `fn first_word<'a>(s: &'a str) -> &str`. * **Rule 2** applies because there is exactly one input lifetime, so it’s copied to the output: `fn first_word<'a>(s: &'a str) -> &'a str`. * Every output lifetime is now assigned. Elision succeeds. No annotation required. ### Walking the rules through `Headers::get` [Section titled “Walking the rules through Headers::get”](#walking-the-rules-through-headersget) ```rust 1 fn get(&self, name: &str) -> Option<&str> { /* ... */ } ``` * **Rule 1** gives each parameter its own lifetime: `&self` gets `'s`, `name` gets `'n`. * **Rule 2** does *not* apply: there are two input lifetimes, not one. * **Rule 3** applies because one parameter is `&self`. The output’s elided lifetime becomes `'s` (the `self` lifetime): `fn get<'s, 'n>(&'s self, name: &'n str) -> Option<&'s str>`. * Output lifetime assigned. Elision succeeds. This is exactly what you want: `get` returns a slice of `self.raw`, and the result is valid for as long as the `Headers` value is borrowed, *not* for as long as the `name` argument lives. ### When the rules run out: multiple inputs, no `self` [Section titled “When the rules run out: multiple inputs, no self”](#when-the-rules-run-out-multiple-inputs-no-self) ```rust 1 fn longest(a: &str, b: &str) -> &str { /* ... */ } // does not compile (error E0106) ``` * **Rule 1** gives `a` lifetime `'a` and `b` lifetime `'b`. * **Rule 2** does not apply (two input lifetimes). * **Rule 3** does not apply (no `self`). * The output lifetime is still unassigned. **Elision fails**, so you must annotate. The real compiler error spells this out precisely: ```plaintext 1 error[E0106]: missing lifetime specifier 2 --> src/main.rs:1:33 3 | 4 1 | fn longest(a: &str, b: &str) -> &str { 5 | ---- ---- ^ expected named lifetime parameter 6 | 7 = help: this function's return type contains a borrowed value, but the signature does not say whether it is borrowed from `a` or `b` 8 help: consider introducing a named lifetime parameter 9 | 10 1 | fn longest<'a>(a: &'a str, b: &'a str) -> &'a str { 11 | ++++ ++ ++ ++ ``` Notice the help text: *“the signature does not say whether it is borrowed from `a` or `b`.”* That’s the elision rules failing in plain English: the compiler genuinely cannot pick for you, so you have to. (The fix, and *why* you write `'a` here, is the subject of the [lifetimes topic](/05-ownership/04-lifetimes/).) *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript/JavaScript | Rust | | -------------------------------------- | ----------------------------------- | ----------------------------------------- | | Tracking how long a reference is valid | Not tracked; GC keeps things alive | Tracked at compile time via lifetimes | | Writing lifetime annotations | N/A — no such thing | Required only when elision can’t infer | | Where lifetimes are inferred from | N/A | The **signature**, never the body | | Returning a substring | New independent string (heap copy) | A *borrow* whose lifetime must be derived | | ”One input → output” case | No annotation (nothing to annotate) | No annotation (rule 2 handles it) | | Method returning part of `self` | No annotation | No annotation (rule 3 handles it) | | Function with two refs, returning one | No annotation | **Annotation required** (elision fails) | ### Elision applies to functions and methods — *not* to structs [Section titled “Elision applies to functions and methods — not to structs”](#elision-applies-to-functions-and-methods--not-to-structs) An important boundary: the three rules apply only to **function and method signatures**. They do **not** apply to struct (or enum) definitions. A struct that holds a reference must always name the lifetime explicitly: ```rust 1 struct Wrapper { 2 text: &str, // does not compile (error E0106): no elision for struct fields 3 } ``` The real error: ```plaintext 1 error[E0106]: missing lifetime specifier 2 --> src/main.rs:3:11 3 | 4 3 | text: &str, // no elision for struct fields 5 | ^ expected named lifetime parameter 6 | 7 help: consider introducing a named lifetime parameter 8 | 9 2 ~ struct Wrapper<'a> { 10 3 ~ text: &'a str, // no elision for struct fields 11 | ``` The fix is `struct Wrapper<'a> { text: &'a str }`. Storing a reference is a long-term commitment, and the compiler refuses to guess how long it must stay valid. See [Lifetimes](/05-ownership/04-lifetimes/) for structs that hold references. ### Elision is about *omitting*, not *changing*, the rules [Section titled “Elision is about omitting, not changing, the rules”](#elision-is-about-omitting-not-changing-the-rules) A common misconception is that elided code is “less strict” than annotated code. It isn’t. The elided form `fn first_word(s: &str) -> &str` enforces *exactly* the same contract as the explicit `fn first_word<'a>(s: &'a str) -> &'a str`. Elision changes the *amount you type*, never the *guarantees you get*. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Assuming the output borrows from “the obvious” parameter [Section titled “Pitfall 1: Assuming the output borrows from “the obvious” parameter”](#pitfall-1-assuming-the-output-borrows-from-the-obvious-parameter) When a method takes `&self` **and** another reference, rule 3 *always* ties the elided output to `self`, even if your code returns a slice of the *other* parameter. This produces a confusing error if your intent differs: ```rust 1 struct Config { 2 name: String, 3 } 4 5 impl Config { 6 // Intent: return a slice of `text`. But rule 3 ties the output to `&self`. 7 fn extract<'b>(&self, text: &'b str) -> &str { // does not compile 8 &text[..3] 9 } 10 } ``` The real compiler error makes the mismatch explicit: ```plaintext 1 error: lifetime may not live long enough 2 --> src/main.rs:8:9 3 | 4 7 | fn extract<'b>(&self, text: &'b str) -> &str { 5 | -- - let's call the lifetime of this reference `'1` 6 | | 7 | lifetime `'b` defined here 8 8 | &text[..3] 9 | ^^^^^^^^^^ method was supposed to return data with lifetime `'1` but it is returning data with lifetime `'b` 10 | 11 help: consider reusing a named lifetime parameter and update trait if needed 12 | 13 7 | fn extract<'b>(&self, text: &'b str) -> &'b str { 14 | ++ ``` The compiler is saying: elision made the return `&'self`, but your body returns `&'b` data. The fix is to *opt out* of rule 3 by annotating explicitly: write `-> &'b str` so the output borrows from `text`, exactly as the help suggests. > **Warning:** Rule 3 is a convenience, not a mind reader. When a method returns a borrow of a *parameter* rather than of `self`, you must annotate to override the default. ### Pitfall 2: Trying to return a reference with no input to borrow from [Section titled “Pitfall 2: Trying to return a reference with no input to borrow from”](#pitfall-2-trying-to-return-a-reference-with-no-input-to-borrow-from) If a function returns a reference but has *no* reference parameters, none of the rules can supply an output lifetime, because there is nothing to borrow from: ```rust 1 fn make_greeting() -> &str { // does not compile (error E0106) 2 "hello" 3 } ``` The real error even guesses your two likely intentions: ```plaintext 1 error[E0106]: missing lifetime specifier 2 --> src/main.rs:1:23 3 | 4 1 | fn make_greeting() -> &str { 5 | ^ expected named lifetime parameter 6 | 7 = help: this function's return type contains a borrowed value, but there is no value for it to be borrowed from 8 help: consider using the `'static` lifetime, but this is uncommon unless you're returning a borrowed value from a `const` or a `static` 9 | 10 1 | fn make_greeting() -> &'static str { 11 | +++++++ 12 help: instead, you are more likely to want to return an owned value 13 | 14 1 - fn make_greeting() -> &str { 15 1 + fn make_greeting() -> String { 16 | ``` For a string literal, `&'static str` is correct (literals live for the whole program). But the more common fix, as the compiler hints, is to return an **owned** `String`. Returning owned data is the right move whenever the function *creates* the value rather than borrowing it from a caller; see [Move, Copy, and Clone](/05-ownership/06-move-copy-clone/). ### Pitfall 3: Believing two input references share a lifetime [Section titled “Pitfall 3: Believing two input references share a lifetime”](#pitfall-3-believing-two-input-references-share-a-lifetime) Rule 1 gives each input its *own* lifetime. TypeScript developers sometimes assume both arguments “must be the same,” but Rust deliberately keeps them separate so the most flexible signature is the default: ```rust 1 // Elided form... 2 fn f(a: &str, b: &str) -> usize { a.len() + b.len() } 3 // ...desugars to TWO distinct lifetimes, NOT one: 4 fn f_explicit<'a, 'b>(a: &'a str, b: &'b str) -> usize { a.len() + b.len() } ``` This only matters once you start *returning* a reference. At that point you usually *do* want to relate the lifetimes, which is why such functions can’t be elided and force you to annotate (Pitfall 1’s `longest` is the canonical case). ### Pitfall 4: Expecting elision in closures or function pointers the same way [Section titled “Pitfall 4: Expecting elision in closures or function pointers the same way”](#pitfall-4-expecting-elision-in-closures-or-function-pointers-the-same-way) The three rules are defined for `fn` and method signatures. Closures infer lifetimes through a separate mechanism, and trait objects / `dyn` types have their own default-lifetime rules. Don’t assume a hand-written `fn(&str) -> &str` type alias elides the same way a function definition does. When in doubt, annotate. (Closures are covered in [Arrow Functions vs Closures](/03-functions/03-arrow-vs-closures/).) *** ## Best Practices [Section titled “Best Practices”](#best-practices) ### 1. Omit lifetimes whenever elision allows it [Section titled “1. Omit lifetimes whenever elision allows it”](#1-omit-lifetimes-whenever-elision-allows-it) Idiomatic Rust does **not** write annotations the compiler can infer. Adding `'a` where it isn’t needed is noise that the Clippy lint `needless_lifetimes` will flag: ```rust 1 // Unidiomatic: explicit lifetime the rules would infer anyway. 2 fn first<'a>(s: &'a str) -> &'a str { s.split_whitespace().next().unwrap_or("") } 3 4 // Idiomatic: let elision do its job. 5 fn first(s: &str) -> &str { s.split_whitespace().next().unwrap_or("") } ``` ### 2. Reach for annotations only when the compiler asks [Section titled “2. Reach for annotations only when the compiler asks”](#2-reach-for-annotations-only-when-the-compiler-asks) The right workflow is: write the clean, elided signature *first*. If it compiles, you’re done. If you get `E0106` or a “lifetime may not live long enough” error, *then* add exactly the annotation the error suggests. Don’t preemptively annotate “to be safe.” ### 3. Run the three rules in your head before reaching for `'a` [Section titled “3. Run the three rules in your head before reaching for 'a”](#3-run-the-three-rules-in-your-head-before-reaching-for-a) When you hit a lifetime error, mentally apply rules 1–3 to the signature. If you can see *why* the output lifetime is unassigned (multiple inputs, no `self`) or *wrong* (rule 3 picked `self` but you meant a parameter), the fix is obvious and you avoid guessing. ### 4. Prefer owned return types when the function creates the data [Section titled “4. Prefer owned return types when the function creates the data”](#4-prefer-owned-return-types-when-the-function-creates-the-data) If a function builds a new string or vector rather than borrowing from an argument, return `String` / `Vec`, not a reference. There’s no lifetime to elide because there’s no borrow, and the API is simpler for callers. Borrow in, own out is a common and healthy pattern. > **Tip:** A function whose every reference is handled by elision is a sign of a well-shaped API: it either passes borrows straight through (one input → output) or returns part of `self`. When you find yourself needing many explicit `'a`s, consider whether returning owned data would be cleaner. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A small, production-flavored HTTP header parser. It borrows the raw request text and hands back slices into it. Almost every method relies on elision. The only explicit lifetime is on the struct itself (where elision never applies) and on a free function that overrides rule defaults: ```rust 1 /// A zero-copy view over raw HTTP header text. 2 /// The struct borrows the buffer, so it needs an explicit lifetime. 3 struct Headers<'a> { 4 raw: &'a str, 5 } 6 7 impl<'a> Headers<'a> { 8 fn new(raw: &'a str) -> Self { 9 Headers { raw } 10 } 11 12 // Rule 3: `&self` + `name: &str` → output borrows from `&self`. 13 // No annotation needed; the returned slice points into `self.raw`. 14 fn get(&self, name: &str) -> Option<&str> { 15 self.raw 16 .lines() 17 .filter_map(|line| line.split_once(": ")) 18 .find(|(key, _)| key.eq_ignore_ascii_case(name)) 19 .map(|(_, value)| value) 20 } 21 22 // Rule 3 again: returns a slice of `self.raw`. 23 fn first_line(&self) -> &str { 24 self.raw.lines().next().unwrap_or("") 25 } 26 } 27 28 // Free function, one reference input → rule 2 supplies the output lifetime. 29 // `prefix` is NOT a reference we return, so its lifetime is irrelevant here. 30 fn trim_prefix<'p>(s: &'p str, prefix: &str) -> &'p str { 31 s.strip_prefix(prefix).unwrap_or(s) 32 } 33 34 fn main() { 35 let raw = "Host: example.com\nContent-Type: text/html\nAccept: */*"; 36 let headers = Headers::new(raw); 37 38 println!("first line: {}", headers.first_line()); 39 println!("content-type: {:?}", headers.get("content-type")); 40 println!("missing: {:?}", headers.get("authorization")); 41 42 println!("trimmed: {}", trim_prefix("v1.2.3", "v")); 43 } ``` Real output: ```plaintext 1 first line: Host: example.com 2 content-type: Some("text/html") 3 missing: None 4 trimmed: 1.2.3 ``` > **Note:** `trim_prefix` is written with an explicit `'p` *only on `s`* to document that the return value borrows from `s`, not `prefix`. Rule 2 would actually elide this correctly because `prefix`’s lifetime never reaches the output, but here the annotation is intentional documentation, not a requirement. This is the rare case where being explicit aids the reader. The struct’s `<'a>`, by contrast, is mandatory: elision never applies to fields. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — Lifetime Elision](https://doc.rust-lang.org/book/ch10-03-lifetime-syntax.html#lifetime-elision) — the canonical explanation of the three rules. * [The Rustonomicon — Lifetime Elision](https://doc.rust-lang.org/nomicon/lifetime-elision.html) — a precise, table-driven restatement with edge cases. * [Rust Reference — Lifetime Elision](https://doc.rust-lang.org/reference/lifetime-elision.html) — the formal specification, including `impl` and trait-object defaults. ### Related Topics in This Guide [Section titled “Related Topics in This Guide”](#related-topics-in-this-guide) * [Lifetimes](/05-ownership/04-lifetimes/) — what the `'a` annotations *mean* and why they exist; required reading if elision fails. * [Borrowing](/05-ownership/02-borrowing/) — shared references, the foundation lifetimes track. * [Mutable References](/05-ownership/03-mutable-references/) — `&mut` and non-lexical lifetimes. * [Ownership Rules](/05-ownership/01-ownership-rules/) — moves, owners, and scope-based drop. * [Move, Copy, Clone](/05-ownership/06-move-copy-clone/) — when to return owned data instead of a borrow. * [Section 05 overview](/05-ownership/) — the full ownership system. * [Functions: parameters](/03-functions/01-parameters/) and [arrow vs closures](/03-functions/03-arrow-vs-closures/) — where references in signatures first appear. * [Variables and Mutability](/02-basics/00-variables/) — the immutability foundation. * [Data Structures](/06-data-structures/) — structs that own vs. borrow their fields. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Spot the elision [Section titled “Exercise 1: Spot the elision”](#exercise-1-spot-the-elision) **Difficulty:** Easy **Objective:** Predict whether a signature needs annotations, then confirm by writing the desugared form. **Instructions:** For the function below, decide whether lifetime elision succeeds. Then write out the fully annotated (desugared) signature the compiler produces, and add a second function `last_char` that returns `Option` from a `&str`. ```rust 1 fn last_char(s: &str) -> Option { 2 /* ??? */ 3 } 4 5 fn main() { 6 assert_eq!(last_char("abc"), Some('c')); 7 assert_eq!(last_char(""), None); 8 println!("ok"); 9 } ``` Solution Elision **succeeds**: there is one input lifetime (rule 1), and rule 2 copies it to any elided output lifetime. Here the return type is `Option` — `char` is an owned `Copy` type, not a reference — so there’s no output lifetime to assign at all. No annotation is needed either way. ```rust 1 fn last_char(s: &str) -> Option { 2 s.chars().last() 3 } 4 5 fn main() { 6 assert_eq!(last_char("abc"), Some('c')); 7 assert_eq!(last_char(""), None); 8 println!("ok"); 9 } ``` The desugared signature is simply `fn last_char<'a>(s: &'a str) -> Option`; the lifetime exists on the input but is never used in the output. ### Exercise 2: Make a method compile via rule 3 [Section titled “Exercise 2: Make a method compile via rule 3”](#exercise-2-make-a-method-compile-via-rule-3) **Difficulty:** Medium **Objective:** Use a method that returns a borrow of `self`, relying on elision rule 3. **Instructions:** Complete the `head` method so it returns the first `n` bytes of the buffer as a `&str` (clamped to the buffer’s length). Do **not** add any explicit lifetime annotations to `head` — let elision handle it. ```rust 1 struct Buffer { 2 data: String, 3 } 4 5 impl Buffer { 6 fn head(&self, n: usize) -> &str { 7 /* ??? */ 8 } 9 } 10 11 fn main() { 12 let buf = Buffer { data: "hello world".to_string() }; 13 assert_eq!(buf.head(5), "hello"); 14 assert_eq!(buf.head(100), "hello world"); 15 println!("ok"); 16 } ``` Solution Rule 3 ties the elided output lifetime to `&self`, so the returned slice borrows from `self.data` with no annotation needed: ```rust 1 struct Buffer { 2 data: String, 3 } 4 5 impl Buffer { 6 fn head(&self, n: usize) -> &str { 7 &self.data[..n.min(self.data.len())] 8 } 9 } 10 11 fn main() { 12 let buf = Buffer { data: "hello world".to_string() }; 13 assert_eq!(buf.head(5), "hello"); 14 assert_eq!(buf.head(100), "hello world"); 15 println!("ok"); 16 } ``` `n.min(self.data.len())` clamps the index so slicing never panics past the end. ### Exercise 3: When elision fails [Section titled “Exercise 3: When elision fails”](#exercise-3-when-elision-fails) **Difficulty:** Hard **Objective:** Recognize a signature elision cannot resolve and supply the correct annotation. **Instructions:** Write `pick` so it returns `a` when `flag` is true and `b` otherwise. Because the function has two reference parameters and no `self`, elision fails, so you must add the annotation that says “the result lives as long as both inputs.” Explain in one sentence why elision can’t do this for you. ```rust 1 fn pick(flag: bool, a: &str, b: &str) -> &str { 2 /* ??? */ 3 } 4 5 fn main() { 6 assert_eq!(pick(true, "yes", "no"), "yes"); 7 assert_eq!(pick(false, "yes", "no"), "no"); 8 println!("ok"); 9 } ``` Solution Rule 1 gives `a` and `b` separate lifetimes; rule 2 doesn’t apply (two inputs); rule 3 doesn’t apply (no `self`). With the output lifetime unassigned, elision fails. Tie both inputs and the output to a single lifetime `'a`: ```rust 1 fn pick<'a>(flag: bool, a: &'a str, b: &'a str) -> &'a str { 2 if flag { a } else { b } 3 } 4 5 fn main() { 6 assert_eq!(pick(true, "yes", "no"), "yes"); 7 assert_eq!(pick(false, "yes", "no"), "no"); 8 println!("ok"); 9 } ``` **Why elision can’t decide:** the compiler infers lifetimes from the *signature alone*, and the signature is honest that the result could come from `a` *or* `b` — so it cannot know which input the output borrows from without you saying so. The `bool` parameter (which the body uses to choose) is invisible to the elision rules. See [Lifetimes](/05-ownership/04-lifetimes/) for the full meaning of `'a` here. *** ## Summary [Section titled “Summary”](#summary) **What you’ve learned:** * Lifetime **elision** lets you omit `'a` annotations the compiler can infer from a signature. * The **three rules**, applied in order: (1) each input reference gets its own lifetime; (2) one input lifetime → copied to all outputs; (3) `&self` present → its lifetime → all outputs. * Elision runs on the **signature**, never the body, and never changes the guarantees, only the typing. * It applies to **functions and methods only**; struct fields always need explicit lifetimes. * When the rules leave an output lifetime unassigned (multiple inputs, no `self`) or assign the *wrong* one (rule 3 picks `self` but you meant a parameter), the compiler asks you to annotate. **Mental model:** * Write the clean, un-annotated signature first. * If it compiles, elision handled it. Leave it alone. * If it doesn’t, run the three rules in your head, find the unassigned output, and add exactly that one annotation. # Move, Copy, and Clone > Rust's move, Copy, and Clone replace JavaScript's invisible reference sharing. See when assignment transfers ownership, duplicates a value, or deep-copies. In TypeScript and JavaScript, assigning one variable to another never duplicates the underlying object; both names point at the same garbage-collected value, and you rarely think about *who owns what*. Rust replaces that quiet sharing with three precise behaviors: a value is **moved** (ownership transfers, the old name becomes unusable), **copied** (a cheap bit-for-bit duplicate of a stack value), or **cloned** (an explicit, possibly expensive deep duplicate). Understanding which one happens, and when, is the difference between fighting the compiler and writing fluent Rust. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) When you write `let b = a;` in Rust, one of two things happens: if `a`’s type implements the **`Copy`** trait (small, stack-only values like `i32` or `bool`), `a` is duplicated and both `a` and `b` stay usable; otherwise the value is **moved**: `b` takes ownership and `a` becomes inaccessible. To get a duplicate of a non-`Copy` value (like a `String` or `Vec`), you call **`.clone()`** explicitly, which performs a deep copy you can *see* in the source. This is the opposite of JavaScript, where `const b = a` for an object simply aliases the same heap value and the GC keeps it alive for as long as anyone references it. > **Note:** This page builds directly on [Ownership Rules](/05-ownership/01-ownership-rules/) (each value has one owner; assignment moves it) and [Stack vs Heap](/05-ownership/00-stack-heap/) (why some types are cheap to copy and others are not). If those ideas are new, skim them first. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In JavaScript, every variable holding an object holds a *reference*. Assignment copies the reference, never the object, and primitives are copied by value. You never explicitly “move” or “clone”; the engine and garbage collector handle lifetime for you. inventory.ts ```typescript 1 interface Product { 2 sku: string; 3 tags: string[]; 4 } 5 6 // Assigning an object copies the REFERENCE, not the object. 7 const original: Product = { sku: "A-100", tags: ["new"] }; 8 const alias = original; 9 alias.tags.push("sale"); 10 console.log(original.tags); // [ 'new', 'sale' ] — they are the SAME object 11 12 // Primitives are copied by value. 13 let count = 5; 14 let backup = count; 15 backup += 1; 16 console.log(count, backup); // 5 6 — independent copies 17 18 // To get a genuinely separate object you must clone EXPLICITLY, 19 // and even then a shallow clone shares nested arrays/objects. 20 const shallow = { ...original }; 21 const deep = structuredClone(original); 22 shallow.tags.push("shallow"); // mutates original.tags too! 23 deep.tags.push("deep"); // safe: deep has its own array 24 console.log(original.tags); // [ 'new', 'sale', 'shallow' ] 25 console.log(deep.tags); // [ 'new', 'sale', 'deep' ] 26 27 // Passing an object to a function passes the reference; the original 28 // is still usable afterward, and mutations leak back to the caller. 29 function addTag(p: Product, tag: string): void { 30 p.tags.push(tag); 31 } 32 addTag(original, "fn"); // original is fine after the call ``` **What the runtime does for you here:** * `const alias = original` aliases the same heap object. Both names see each other’s mutations. * `let backup = count` copies the primitive `5`. The two numbers are independent. * After passing `original` to `addTag`, you can keep using `original`. The function only borrowed a reference, and the GC keeps the object alive. Rust makes every one of these distinctions explicit and enforces them at compile time. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) The same three behaviors (alias-by-reference, copy-by-value, and explicit deep copy) become **move**, **`Copy`**, and **`Clone`**: ```rust 1 #[derive(Debug, Clone)] 2 struct Account { 3 id: u64, 4 owner: String, 5 balance: f64, 6 } 7 8 // Takes ownership of `account` (it is MOVED in), mutates it, and returns it. 9 fn deposit(mut account: Account, amount: f64) -> Account { 10 account.balance += amount; 11 account 12 } 13 14 fn main() { 15 // --- Copy: i32 is a small stack value, so `=` duplicates it. --- 16 let x = 5; 17 let y = x; // x is COPIED, not moved 18 println!("x = {x}, y = {y}"); // both usable 19 20 // --- Move: String owns heap data, so `=` transfers ownership. --- 21 let s1 = String::from("hello"); 22 let s2 = s1; // s1 is MOVED into s2 23 println!("{s2}"); 24 // println!("{s1}"); // does not compile (error[E0382]): s1 was moved 25 26 // --- Clone: ask explicitly for a deep copy. --- 27 let s3 = String::from("world"); 28 let s4 = s3.clone(); // duplicates the heap buffer 29 println!("{s3} {s4}"); // BOTH valid 30 31 // --- Move into a function and get ownership back via the return. --- 32 let acct = Account { id: 1, owner: String::from("Ada"), balance: 100.0 }; 33 let acct = deposit(acct, 50.0); // `acct` moved in, rebound to the result 34 println!("{acct:?}"); 35 36 // --- Clone a whole struct (deep-copies the String inside). --- 37 let original = Account { id: 2, owner: String::from("Bob"), balance: 0.0 }; 38 let copy = original.clone(); 39 println!("{}", original.owner); // original still usable 40 println!("{}", copy.owner); 41 } ``` This compiles and prints: ```text 1 x = 5, y = 5 2 hello 3 world world 4 Account { id: 1, owner: "Ada", balance: 150.0 } 5 Bob 6 Bob ``` Notice what is *visible* in the source: every potentially expensive duplication is a `.clone()` call you can grep for, and every place a value becomes unusable is an ordinary `=` or function call. There is no hidden deep-copy and no hidden aliasing. *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### Move: the default for owned, heap-backed values [Section titled “Move: the default for owned, heap-backed values”](#move-the-default-for-owned-heap-backed-values) A `String` is a three-word handle on the stack: a pointer to a heap buffer, a length, and a capacity (see [Stack vs Heap](/05-ownership/00-stack-heap/)). When you write `let s2 = s1;`, Rust copies those three stack words into `s2`. But now two handles would point at the *same* heap buffer, and when both went out of scope they would each try to free it — a double-free. Rust’s solution is the **move**: after the assignment, `s1` is statically marked invalid, so only `s2` is responsible for the buffer. The copy of the stack handle is cheap; what is forbidden is *continuing to use the old name*. This is the single biggest mental shift from JavaScript. In JS, `const s2 = s1` gives you a second name for the same live object. In Rust, the second name *takes over* and the first is retired. ### Copy: opting out of move for cheap stack values [Section titled “Copy: opting out of move for cheap stack values”](#copy-opting-out-of-move-for-cheap-stack-values) Some types are so cheap to duplicate that moving them would be pointless ceremony. Integers, floats, `bool`, `char`, and tuples/arrays of such types implement the **`Copy`** trait. For these, `let y = x;` performs a bitwise copy and leaves `x` fully usable — exactly like a JavaScript primitive: ```rust 1 fn square(n: i32) -> i32 { 2 n * n 3 } 4 5 fn main() { 6 let n = 7; 7 let sq = square(n); // n is COPIED into the function 8 println!("{n} squared is {sq}"); // n still usable 9 } ``` ```text 1 7 squared is 49 ``` A type can be `Copy` only if *all* of its parts are `Copy` and it does not own a heap allocation or any other resource. That is why `String` (owns heap memory) and `Vec` are **not** `Copy`, while `(i32, bool)` is. ### Clone: explicit, deep, possibly expensive [Section titled “Clone: explicit, deep, possibly expensive”](#clone-explicit-deep-possibly-expensive) `Copy` happens implicitly because it is guaranteed cheap. Anything that might be expensive (duplicating a heap buffer, recursively copying a tree) must be requested with **`.clone()`**. `String::clone` allocates a new buffer and copies the bytes; `Vec::clone` allocates a new array and clones each element. The cost is real, so Rust makes you write it down. ```rust 1 let words = vec![String::from("a"), String::from("b")]; 2 // `iter()` borrows; `cloned()` clones each &String into an owned String. 3 let joined: String = words.iter().cloned().collect::>().join("-"); 4 println!("{joined}"); // a-b 5 println!("still have words: {words:?}"); // words was only borrowed, still valid ``` ```text 1 a-b 2 still have words: ["a", "b"] ``` ### Moving into functions (and getting ownership back) [Section titled “Moving into functions (and getting ownership back)”](#moving-into-functions-and-getting-ownership-back) Passing a non-`Copy` value to a function *moves* it, just like assignment. The function now owns it; the caller does not. If the caller still needs the value, the idiomatic options are (in rough order of preference): **borrow** instead of moving (`&T`, covered in [Borrowing](/05-ownership/02-borrowing/)), **return the value back** out of the function (as `deposit` does above), or **clone** before the call. Borrowing is almost always the right answer when the function only needs to *read or temporarily mutate* the data. ### Partial moves out of a struct [Section titled “Partial moves out of a struct”](#partial-moves-out-of-a-struct) You can move a single field out of a struct. After that, the field is invalid but `Copy` fields remain readable: ```rust 1 #[derive(Debug)] 2 struct Profile { 3 username: String, 4 age: u32, 5 } 6 7 fn main() { 8 let p = Profile { username: String::from("rustacean"), age: 30 }; 9 let name = p.username; // partial MOVE of the String field out of p 10 let age = p.age; // u32 is Copy, so this is a copy 11 println!("{name} is {age}"); 12 // println!("{:?}", p); // does not compile: p is partially moved 13 } ``` ```text 1 rustacean is 30 ``` *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Aspect | TypeScript/JavaScript | Rust | | ------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `let b = a` for an object | Copies the **reference**; both names alias one live object | **Moves** ownership; `a` becomes unusable (unless the type is `Copy`) | | `let b = a` for a number | Copies the value; both independent | **Copies** (`Copy` types); both independent | | Deep duplicate | `structuredClone(a)` / spread (shallow) | `a.clone()` (depth depends on the type’s `Clone` impl) | | Passing to a function | Passes a reference (objects) or a copy (primitives); original stays usable | **Moves** the value in (non-`Copy`), or copies it (`Copy`); to keep it, borrow or clone | | Who frees the memory | The garbage collector, eventually | The single current owner, deterministically at end of scope ([Drop](/05-ownership/08-drop-trait/)) | | Cost of duplication | Invisible; sharing is implicit and free | Explicit: cheap `Copy` is automatic, expensive `Clone` is spelled out | The deepest difference is *honesty about cost*. JavaScript hides whether you are sharing or copying; the GC papers over the lifetime question entirely. Rust forces the choice into the open: a move is a cheap ownership transfer, a `Copy` is a guaranteed-cheap duplicate, and a `Clone` is the one place where an allocation might happen, and it is always visible in the source. > **Tip:** A quick rule of thumb: if a type is `Copy`, treating it like a JavaScript primitive (free to duplicate, no aliasing surprises) is exactly right. If it is not `Copy`, assume `=` and function calls *consume* the value unless you borrow with `&`. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Using a value after it was moved [Section titled “Pitfall 1: Using a value after it was moved”](#pitfall-1-using-a-value-after-it-was-moved) This is the error every TypeScript developer hits first, because in JavaScript the original would still be valid: ```rust 1 fn main() { 2 let s1 = String::from("hello"); 3 let s2 = s1; // value moved here 4 println!("{s1}"); // does not compile (error[E0382]) 5 println!("{s2}"); 6 } ``` The real compiler output: ```text 1 error[E0382]: borrow of moved value: `s1` 2 --> src/main.rs:4:16 3 | 4 2 | let s1 = String::from("hello"); 5 | -- move occurs because `s1` has type `String`, which does not implement the `Copy` trait 6 3 | let s2 = s1; 7 | -- value moved here 8 4 | println!("{s1}"); 9 | ^^ value borrowed here after move 10 | 11 = note: this error originates in the macro `$crate::format_args_nl` which comes from the expansion of the macro `println` (in Nightly builds, run with -Z macro-backtrace for more info) 12 help: consider cloning the value if the performance cost is acceptable 13 | 14 3 | let s2 = s1.clone(); 15 | ++++++++ ``` The fix is whichever matches your intent: `let s2 = s1.clone();` if you genuinely need two owners, or `let s2 = &s1;` if you only need a second *view* ([Borrowing](/05-ownership/02-borrowing/)). ### Pitfall 2: Moving a value into a function, then using it again [Section titled “Pitfall 2: Moving a value into a function, then using it again”](#pitfall-2-moving-a-value-into-a-function-then-using-it-again) Same error, but it surprises people because the move is hidden inside a call: ```rust 1 fn print_len(s: String) { 2 println!("{}", s.len()); 3 } 4 5 fn main() { 6 let name = String::from("Grace Hopper"); 7 print_len(name); // value moved here 8 println!("{name}"); // does not compile (error[E0382]) 9 } ``` The real output even tells you the better design: ```text 1 error[E0382]: borrow of moved value: `name` 2 --> src/main.rs:8:16 3 | 4 6 | let name = String::from("Grace Hopper"); 5 | ---- move occurs because `name` has type `String`, which does not implement the `Copy` trait 6 7 | print_len(name); 7 | ---- value moved here 8 8 | println!("{name}"); 9 | ^^^^ value borrowed here after move 10 | 11 note: consider changing this parameter type in function `print_len` to borrow instead if owning the value isn't necessary 12 --> src/main.rs:1:17 13 | 14 1 | fn print_len(s: String) { 15 | --------- ^^^^^^ this parameter takes ownership of the value 16 | | 17 | in this function 18 = note: this error originates in the macro `$crate::format_args_nl` which comes from the expansion of the macro `println` (in Nightly builds, run with -Z macro-backtrace for more info) 19 help: consider cloning the value if the performance cost is acceptable 20 | 21 7 | print_len(name.clone()); 22 | ++++++++ ``` The idiomatic fix is to make `print_len` borrow: `fn print_len(s: &str)` and call `print_len(&name)`. The function never needed to own the string. ### Pitfall 3: Deriving `Copy` on a type that owns heap data [Section titled “Pitfall 3: Deriving Copy on a type that owns heap data”](#pitfall-3-deriving-copy-on-a-type-that-owns-heap-data) You cannot make a `String`-holding struct `Copy`, because copying it bit-for-bit would create two owners of one buffer, exactly what move semantics prevent: ```rust 1 #[derive(Copy, Clone)] // does not compile (error[E0204]) 2 struct Wrapper { 3 name: String, 4 } ``` ```text 1 error[E0204]: the trait `Copy` cannot be implemented for this type 2 --> src/main.rs:1:10 3 | 4 1 | #[derive(Copy, Clone)] 5 | ^^^^ 6 2 | struct Wrapper { 7 3 | name: String, 8 | ------------ this field does not implement `Copy` ``` The fix: derive only `Clone` (`#[derive(Clone)]`) and call `.clone()` when you need a duplicate. ### Pitfall 4: Reaching for the whole struct after a partial move [Section titled “Pitfall 4: Reaching for the whole struct after a partial move”](#pitfall-4-reaching-for-the-whole-struct-after-a-partial-move) Moving one field out invalidates the *whole* binding for purposes of using it as a unit: ```rust 1 let _name = p.username; // moves the String field out 2 println!("{:?}", p); // does not compile ``` ```text 1 error[E0382]: borrow of partially moved value: `p` 2 --> src/main.rs:10:22 3 | 4 9 | let _name = p.username; 5 | ---------- value partially moved here 6 10 | println!("{:?}", p); 7 | ^ value borrowed here after partial move 8 | 9 = note: partial move occurs because `p.username` has type `String`, which does not implement the `Copy` trait 10 = note: this error originates in the macro `$crate::format_args_nl` which comes from the expansion of the macro `println` (in Nightly builds, run with -Z macro-backtrace for more info) ``` If you need both the field and the rest of the struct, clone the field (`p.username.clone()`) or borrow it (`&p.username`). ### Pitfall 5: “Cloning” to silence the borrow checker [Section titled “Pitfall 5: “Cloning” to silence the borrow checker”](#pitfall-5-cloning-to-silence-the-borrow-checker) When the compiler suggests `.clone()`, it is one valid fix — but reaching for it reflexively can hide a design that should borrow instead, adding needless allocations on a hot path. Clone is a tool, not a panic button. Prefer borrowing first (see [Borrowing](/05-ownership/02-borrowing/)); clone when you genuinely need two independent owners. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Borrow before you clone before you move.** If a function only reads, take `&T`. If it temporarily mutates, take `&mut T`. Move (take `T`) only when the function truly needs to *own* and store the value. Reserve `.clone()` for when you genuinely need a second independent owner. * **Derive `Copy` for small, plain value types**: IDs, coordinates, enums without data, fixed-size numeric wrappers. It makes them ergonomic to pass around exactly like JavaScript primitives. Always derive `Clone` alongside `Copy` (`#[derive(Clone, Copy)]`); `Copy` requires `Clone` as a supertrait. * **Never derive `Copy` on anything that owns a heap allocation or other resource** (`String`, `Vec`, `Box`, file handles). Those are move-only by design. * **Make clones visible and intentional.** When you do clone, a brief comment on *why* (e.g. “config is shared across threads”) helps reviewers distinguish a deliberate clone from a borrow-checker workaround. * **Return ownership instead of cloning when a function transforms a value.** The `deposit` pattern (`value in → modified value out`) avoids both a clone and a borrow dance. * **Reach for `Rc`/`Arc` for shared ownership, not repeated `.clone()` of large data.** When many parts of a program need to *share* one immutable value, reference counting is cheaper than deep cloning. See [Reference Counting](/05-ownership/07-reference-counting/). *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A job-processing loop shows all three behaviors working together: a `Copy` ID type passed freely, a shared `Config` that is only *borrowed* (never cloned), and jobs that are *moved* into the processor and consumed. ```rust 1 use std::collections::HashMap; 2 3 /// Shared, read-only configuration loaded once at startup. 4 #[derive(Debug, Clone)] 5 struct Config { 6 service_name: String, 7 max_retries: u32, 8 endpoints: Vec, 9 } 10 11 /// A small, all-`Copy` value: cheap to pass and store by value. 12 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] 13 struct JobId(u64); 14 15 #[derive(Debug)] 16 struct Job { 17 id: JobId, 18 payload: String, 19 } 20 21 /// Consumes the job (it is MOVED in) and only BORROWS the config, 22 /// so one `Config` serves every job without a single clone. 23 fn process(job: Job, config: &Config) -> String { 24 let _ = &config.endpoints; // (would be used to dispatch in real code) 25 format!( 26 "[{}] job {} -> {} (retries={})", 27 config.service_name, job.id.0, job.payload, config.max_retries 28 ) 29 } 30 31 fn main() { 32 let config = Config { 33 service_name: String::from("ingest"), 34 max_retries: 3, 35 endpoints: vec![String::from("https://a"), String::from("https://b")], 36 }; 37 38 let jobs = vec![ 39 Job { id: JobId(1), payload: String::from("resize-image") }, 40 Job { id: JobId(2), payload: String::from("send-email") }, 41 ]; 42 43 let mut results: HashMap = HashMap::new(); 44 for job in jobs { 45 let id = job.id; // JobId is Copy: this does NOT consume `job` 46 // `job` is moved into `process`; `&config` is only borrowed. 47 let summary = process(job, &config); 48 results.insert(id, summary); 49 } 50 51 // `config` is still fully usable — it was only ever borrowed. 52 println!("service still available: {}", config.service_name); 53 let mut ids: Vec<_> = results.keys().copied().collect(); 54 ids.sort_by_key(|j| j.0); 55 for id in ids { 56 println!("{}", results[&id]); 57 } 58 } ``` This compiles and prints: ```text 1 service still available: ingest 2 [ingest] job 1 -> resize-image (retries=3) 3 [ingest] job 2 -> send-email (retries=3) ``` The key design wins, all enforced at compile time: `JobId` being `Copy` lets us grab `job.id` for the map key *without* consuming `job`; the `&config` borrow means the single config object is reused for every iteration with zero allocations; and each `Job` is moved into `process` and dropped at the end of that call, so memory is reclaimed deterministically with no GC pauses. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — What Is Ownership? (Move semantics)](https://doc.rust-lang.org/book/ch04-01-what-is-ownership.html) * [The Rust Book — References and Borrowing](https://doc.rust-lang.org/book/ch04-02-references-and-borrowing.html) * [`std::marker::Copy` (trait docs)](https://doc.rust-lang.org/std/marker/trait.Copy.html) * [`std::clone::Clone` (trait docs)](https://doc.rust-lang.org/std/clone/trait.Clone.html) * [Rust by Example — Ownership and moves](https://doc.rust-lang.org/rust-by-example/scope/move.html) * [Error index — E0382 (use of moved value)](https://doc.rust-lang.org/error_codes/E0382.html), [E0204 (cannot derive `Copy`)](https://doc.rust-lang.org/error_codes/E0204.html) ### Related Sections in This Guide [Section titled “Related Sections in This Guide”](#related-sections-in-this-guide) * [Stack vs Heap](/05-ownership/00-stack-heap/) — why `Copy` types are cheap and `String`/`Vec` are not. * [Ownership Rules](/05-ownership/01-ownership-rules/): one owner per value; move on assignment; drop at end of scope. * [Borrowing](/05-ownership/02-borrowing/) — `&T` shared references: the alternative to moving or cloning. * [Mutable References](/05-ownership/03-mutable-references/): `&mut T` for in-place mutation without moving. * [Lifetimes](/05-ownership/04-lifetimes/) — relating the validity of borrows you hand out. * [Reference Counting (`Rc`/`Arc`)](/05-ownership/07-reference-counting/): shared ownership without deep clones. * [The `Drop` Trait](/05-ownership/08-drop-trait/) — what happens when the final owner goes out of scope. * [Section 05 overview](/05-ownership/): the full ownership system. * [Functions — Parameters](/03-functions/01-parameters/) — choosing between by-value, `&`, and `&mut` parameters. * [Basics — Variables and Mutability](/02-basics/00-variables/) and [Types](/02-basics/01-types/): the building blocks moved and copied here. * [Data Structures](/06-data-structures/) — structs and enums that own vs. borrow their fields. *** ## Exercises [Section titled “Exercises”](#exercises) ### Exercise 1: Clone to keep two owners [Section titled “Exercise 1: Clone to keep two owners”](#exercise-1-clone-to-keep-two-owners) **Difficulty:** Easy **Objective:** Recognize a move and fix it by cloning when two independent owners are genuinely required. **Instructions:** The snippet below does not compile because `a` is moved into `b` and then used again. Make it compile *without* changing the fact that both `a` and `b` must be usable afterward and must hold equal contents. ```rust 1 fn main() { 2 let a = String::from("data"); 3 let b = a; // TODO: a gets used below — make this work 4 println!("{a} {b}"); 5 assert_eq!(a, b); 6 } ``` Solution ```rust 1 fn main() { 2 let a = String::from("data"); 3 let b = a.clone(); // explicit deep copy: now there are two owners 4 println!("{a} {b}"); 5 assert_eq!(a, b); 6 println!("ex1 ok"); 7 } ``` `a.clone()` allocates a second heap buffer with the same bytes, so `a` and `b` are independent owners. (If you only needed to *read* `a` through `b`, `let b = &a;` would have avoided the allocation entirely, but the exercise requires two owners.) ### Exercise 2: Make a type `Copy` [Section titled “Exercise 2: Make a type Copy”](#exercise-2-make-a-type-copy) **Difficulty:** Medium **Objective:** Derive `Copy` on a small value type so it can be used multiple times without moving. **Instructions:** Define a `Meters(f64)` newtype and an `add(a: Meters, b: Meters) -> Meters` function. Then call `add(d, d)` using the *same* variable `d` twice and also read `d` afterward. This is only possible if `Meters` is `Copy`; add the right derive. ```rust 1 struct Meters(f64); // TODO: derive what you need 2 3 fn add(a: Meters, b: Meters) -> Meters { 4 // TODO 5 todo!() 6 } 7 8 fn main() { 9 let d = Meters(3.0); 10 let total = add(d, d); // d used twice 11 assert_eq!(total.0, 6.0); 12 assert_eq!(d.0, 3.0); // d still usable 13 println!("ok"); 14 } ``` Solution ```rust 1 #[derive(Debug, Clone, Copy, PartialEq)] 2 struct Meters(f64); 3 4 fn add(a: Meters, b: Meters) -> Meters { 5 Meters(a.0 + b.0) 6 } 7 8 fn main() { 9 let d = Meters(3.0); 10 let total = add(d, d); // `d` is COPIED into each argument, not moved 11 assert_eq!(total, Meters(6.0)); 12 assert_eq!(d, Meters(3.0)); // still usable 13 println!("ok"); 14 } ``` Because `f64` is `Copy`, a `Meters` wrapping a single `f64` can derive `Copy` too. `Copy` requires `Clone` as a supertrait, so you must derive both. Now passing `d` twice copies it twice instead of moving it. ### Exercise 3: Borrow, then own only what you keep [Section titled “Exercise 3: Borrow, then own only what you keep”](#exercise-3-borrow-then-own-only-what-you-keep) **Difficulty:** Medium–Hard **Objective:** Take borrowed input, clone only the pieces you decide to keep, and return owned data: the common “build an owned result from borrowed inputs” pattern. **Instructions:** Implement `collect_unique(items: &[&str]) -> Vec` that returns the input strings in first-seen order with duplicates removed. The parameter is borrowed (the function does not own the strings), so you must turn each kept `&str` into an owned `String`. `collect_unique(&["a", "b", "a", "c", "b"])` must return `vec!["a", "b", "c"]` (as `String`s). ```rust 1 fn collect_unique(items: &[&str]) -> Vec { 2 // TODO: keep first occurrences, return owned Strings 3 todo!() 4 } 5 6 fn main() { 7 let result = collect_unique(&["a", "b", "a", "c", "b"]); 8 assert_eq!(result, vec!["a".to_string(), "b".to_string(), "c".to_string()]); 9 println!("ok"); 10 } ``` Solution ```rust 1 fn collect_unique(items: &[&str]) -> Vec { 2 let mut out: Vec = Vec::new(); 3 for &item in items { 4 let owned = item.to_string(); // clone the borrowed &str into an owned String 5 if !out.contains(&owned) { 6 out.push(owned); // moved into the Vec; `out` now owns it 7 } 8 } 9 out 10 } 11 12 fn main() { 13 let result = collect_unique(&["a", "b", "a", "c", "b"]); 14 assert_eq!(result, vec!["a".to_string(), "b".to_string(), "c".to_string()]); 15 println!("ok"); 16 } ``` The slice `&[&str]` is borrowed, so the original strings stay owned by the caller. `item.to_string()` allocates an owned `String` (a kind of clone from a borrowed `&str`), which is then *moved* into `out`. The function returns the owned `Vec` by value: ownership transfers to the caller, no borrow-checker gymnastics required. # Reference Counting with `Rc` and `Arc` > Rust's Rc and Arc give a value multiple owners with deterministic cleanup, the explicit counterpart to JavaScript's shared object references and garbage collector. So far every value in Rust has had exactly **one owner**. But some data is genuinely shared — a configuration object read by many parts of a program, a node referenced by several edges in a graph. Reference counting is Rust’s safe, opt-in way to give one value **multiple owners**, with cleanup that still happens automatically and deterministically. *** ## Quick Overview [Section titled “Quick Overview”](#quick-overview) `Rc` (**reference counted**) and `Arc` (**atomically reference counted**) are smart pointers that let a value have more than one owner. Each holds a count of how many owners currently exist; when the last one goes away, the value is dropped. For a TypeScript/JavaScript developer this feels like normal shared object references, except the “garbage collector” here is a tiny integer counter the compiler manages, with `Rc` for single-threaded code and `Arc` for sharing across threads. > **Note:** This page is a focused, practical introduction. `Rc`/`Arc` are *smart pointers*, and the full family (`Box`, `RefCell`, `Weak`, reference cycles, and the `Deref`/`Drop` machinery behind them) is covered in [Section 10: Smart Pointers](/10-smart-pointers/). Here we cover what you need to share ownership safely and read a strong count. *** ## TypeScript/JavaScript Example [Section titled “TypeScript/JavaScript Example”](#typescriptjavascript-example) In JavaScript and TypeScript, sharing is the default and invisible. Assigning an object to another variable, pushing it into an array, or storing it on another object all create additional references to the **same** object. The garbage collector (GC) frees it only once nothing can reach it anymore. ```typescript 1 // TypeScript/JavaScript: object references are shared implicitly 2 interface Config { 3 baseUrl: string; 4 timeoutMs: number; 5 } 6 7 const config: Config = { 8 baseUrl: "https://api.example.com", 9 timeoutMs: 5000, 10 }; 11 12 // Every one of these is the SAME object, not a copy: 13 const forLogger = config; 14 const forRetry = config; 15 const sinks = [config, forLogger]; // array also holds the same reference 16 17 forRetry.timeoutMs = 10000; // mutating through one handle... 18 console.log(forLogger.timeoutMs); // 10000 — ...is visible through all of them 19 20 // You never count references and never free anything. When `config`, 21 // `forLogger`, `forRetry`, and `sinks` all become unreachable, the GC 22 // reclaims the object at some unspecified later time. ``` **Key points:** * Assignment shares a reference; there is no count you can see and no `free` to call. * Any handle can mutate the shared object, and the change is visible everywhere. * Cleanup is **non-deterministic** — the GC decides when. *** ## Rust Equivalent [Section titled “Rust Equivalent”](#rust-equivalent) Rust will not let you alias an owned value freely (that is the whole point of [the ownership rules](/05-ownership/01-ownership-rules/)). To opt into shared ownership, you wrap the value in `Rc` and create additional owners with `Rc::clone`. Each clone bumps a strong count; each drop lowers it; the value is freed when the count hits zero. ```rust 1 use std::rc::Rc; 2 3 #[derive(Debug)] 4 struct Config { 5 base_url: String, 6 timeout_ms: u32, 7 } 8 9 fn main() { 10 // ---- Rc basics: shared ownership, strong count ---- 11 let config = Rc::new(Config { 12 base_url: String::from("https://api.example.com"), 13 timeout_ms: 5000, 14 }); 15 println!("after create: count = {}", Rc::strong_count(&config)); 16 17 let for_logger = Rc::clone(&config); 18 println!("after 1 clone: count = {}", Rc::strong_count(&config)); 19 20 { 21 let for_retry = Rc::clone(&config); 22 println!("inside block: count = {}", Rc::strong_count(&config)); 23 println!("retry sees timeout = {}", for_retry.timeout_ms); 24 } // `for_retry` dropped here -> count goes back down 25 26 println!("after block: count = {}", Rc::strong_count(&config)); 27 println!("logger sees url = {}", for_logger.base_url); 28 } ``` **Output:** ```text 1 after create: count = 1 2 after 1 clone: count = 2 3 inside block: count = 3 4 retry sees timeout = 5000 5 after block: count = 2 6 logger sees url = https://api.example.com ``` **Key points:** * `Rc::new(value)` puts `value` on the heap with a strong count of `1`. * `Rc::clone(&config)` creates another owner and increments the count. It does **not** deep-copy the `Config`. * When `for_retry` goes out of scope at the inner `}`, the count drops back from `3` to `2`, deterministically. * The `Config` is freed exactly when the last `Rc` is dropped — no GC, no leak (caveat: reference cycles, covered below). *** ## Detailed Explanation [Section titled “Detailed Explanation”](#detailed-explanation) ### What `Rc` actually is [Section titled “What Rc\ actually is”](#what-rct-actually-is) `Rc` is a smart pointer that owns a heap allocation containing two things: your value of type `T`, and a small bookkeeping header with the counts. Conceptually: ```text 1 stack heap 2 ┌─────────┐ ┌───────────────────────────────┐ 3 │ config │ ─────▶ │ strong: 2 | weak: 0 | T value │ 4 └─────────┘ └───────────────────────────────┘ 5 ┌─────────┐ ▲ 6 │for_logger│ ─────────┘ (both Rc handles point at the same allocation) 7 └─────────┘ ``` Each `Rc` handle is a pointer; cloning one copies the pointer and bumps `strong` by one. The value `T` is allocated **once** and shared. This is the same layout idea as a JavaScript object reference (multiple variables pointing at one heap object), but the count is explicit and the deallocation is driven by it. ### `Rc::clone` is cheap and explicit [Section titled “Rc::clone is cheap and explicit”](#rcclone-is-cheap-and-explicit) ```rust 1 let for_logger = Rc::clone(&config); ``` Read this as “make another owner of the same allocation.” It copies a pointer and increments an integer — it is **not** the expensive deep `clone()` you saw in [Move, Copy, and Clone](/05-ownership/06-move-copy-clone/). `Rc` does implement the `Clone` trait, so `config.clone()` works and does exactly the same thing. The community convention is to write `Rc::clone(&config)` (the *associated-function* form) rather than `config.clone()`, because it makes clear at the call site that you are cheaply bumping a refcount, not deep-copying the data. You can confirm all clones point at the same heap value: `Rc::as_ptr` returns the address of the inner `T`, and it is identical across clones (the exact address varies per run): ```rust 1 use std::rc::Rc; 2 3 fn main() { 4 let original = Rc::new(vec![10, 20, 30]); 5 let via_method = original.clone(); // calls Rc's Clone impl 6 let via_assoc = Rc::clone(&original); // identical behavior 7 8 println!("original ptr: {:p}", Rc::as_ptr(&original)); 9 println!("method ptr: {:p}", Rc::as_ptr(&via_method)); 10 println!("assoc ptr: {:p}", Rc::as_ptr(&via_assoc)); 11 println!("strong_count = {}", Rc::strong_count(&original)); 12 } ``` All three printed pointers are the same address, and `strong_count` is `3`. No `Vec` was copied. ### The strong count and automatic drop [Section titled “The strong count and automatic drop”](#the-strong-count-and-automatic-drop) `Rc::strong_count(&rc)` reports how many owners exist right now. The count goes up on every clone and down on every drop, including the implicit drop at the end of a scope and the explicit `std::mem::drop` (the same `drop` from [the Drop trait page](/05-ownership/08-drop-trait/)): ```rust 1 use std::rc::Rc; 2 3 fn main() { 4 let data = Rc::new(vec![1, 2, 3]); // count = 1 5 let a = Rc::clone(&data); // count = 2 6 let b = Rc::clone(&data); // count = 3 7 println!("after two clones: {}", Rc::strong_count(&data)); 8 9 drop(a); // count = 2 10 println!("after drop(a): {}", Rc::strong_count(&data)); 11 12 drop(b); // count = 1 13 println!("after drop(b): {}", Rc::strong_count(&data)); 14 15 println!("data still usable: {:?}", data); 16 } ``` **Output:** ```text 1 after two clones: 3 2 after drop(a): 2 3 after drop(b): 1 4 data still usable: [1, 2, 3] ``` When the count would reach `0`, the inner `Vec` is dropped and its heap memory freed. This is still **deterministic** RAII (it happens at a point you can identify by reading the code); it is just that “the owner” is now “the last surviving handle” instead of a single binding. ### Shared means read-only [Section titled “Shared means read-only”](#shared-means-read-only) `Rc` gives you shared ownership, and shared access in Rust means **immutable** access (the same one-mutable-XOR-many-shared rule from [Mutable References](/05-ownership/03-mutable-references/), now enforced at the type level). You cannot get a `&mut T` out of an `Rc` while it might be shared, so you cannot mutate the inner value directly. To have shared *and* mutable data, you combine `Rc` with a cell type that provides **interior mutability**, almost always `RefCell` (single-threaded): ```rust 1 use std::cell::RefCell; 2 use std::rc::Rc; 3 4 fn main() { 5 // Shared, mutable counter: many handles, interior mutability via RefCell. 6 let hits = Rc::new(RefCell::new(0u32)); 7 8 let a = Rc::clone(&hits); 9 let b = Rc::clone(&hits); 10 11 *a.borrow_mut() += 1; // mutate through one handle 12 *b.borrow_mut() += 1; // mutate through another 13 14 println!("hits = {}", hits.borrow()); 15 println!("strong_count = {}", Rc::strong_count(&hits)); 16 } ``` **Output:** ```text 1 hits = 2 2 strong_count = 3 ``` `RefCell` moves the borrow-checking from compile time to *runtime* (it panics if you break the borrowing rules), and it is the standard partner for `Rc`. The full `RefCell` story lives in [Section 10](/10-smart-pointers/); the takeaway here is the pattern `Rc>` for shared mutable state on one thread. ### `Arc`: the same idea, safe across threads [Section titled “Arc\: the same idea, safe across threads”](#arct-the-same-idea-safe-across-threads) `Rc` deliberately uses a **non-atomic** counter, which is fast but not safe to touch from multiple threads. The compiler enforces this: an `Rc` is not `Send`, so you cannot move one into another thread. When you need to share across threads, switch to `Arc` — identical API, but the count is updated with **atomic** operations: ```rust 1 use std::sync::Arc; 2 use std::thread; 3 4 #[derive(Debug)] 5 struct Settings { 6 workers: u32, 7 region: String, 8 } 9 10 fn main() { 11 let settings = Arc::new(Settings { 12 workers: 4, 13 region: String::from("eu-west-1"), 14 }); 15 16 let mut handles = Vec::new(); 17 for id in 0..3 { 18 let settings = Arc::clone(&settings); // each thread gets its own handle 19 let handle = thread::spawn(move || { 20 println!( 21 "worker {id} reading region={} workers={}", 22 settings.region, settings.workers 23 ); 24 }); 25 handles.push(handle); 26 } 27 28 for handle in handles { 29 handle.join().unwrap(); 30 } 31 32 println!("final strong_count = {}", Arc::strong_count(&settings)); 33 } ``` **Output** (the three worker lines may appear in any order because they run concurrently; the final count is always `1`): ```text 1 worker 0 reading region=eu-west-1 workers=4 2 worker 1 reading region=eu-west-1 workers=4 3 worker 2 reading region=eu-west-1 workers=4 4 final strong_count = 1 ``` Each `Arc::clone` gives a thread its own owner; the `move` closure takes that clone with it. After all threads `join`, their clones have been dropped, so the count is back to `1` (just the original binding). For shared *mutable* state across threads you pair `Arc` with `Mutex` or `RwLock` (`Arc>`), the thread-safe analog of `Rc>`. Threads and these locks are the subject of [Section 26: Systems Programming](/26-systems-programming/); for now, just remember the swap: **`Rc` + `RefCell`** on one thread, **`Arc` + `Mutex`** across threads. > **Note:** Rust’s compiler will *stop you* from using `Rc` across threads — you don’t have to remember the rule. The error (`Rc<...> cannot be sent between threads safely`) is shown in the Pitfalls section below. *** ## Key Differences [Section titled “Key Differences”](#key-differences) | Concept | TypeScript / JavaScript | Rust `Rc` / `Arc` | | ----------------------- | ------------------------------------------ | --------------------------------------------------------- | | Shared ownership | Default and implicit (object references) | Opt-in: wrap in `Rc`/`Arc` and `clone` | | How sharing happens | Assignment / passing aliases the object | `Rc::clone(&x)` bumps a strong count | | Cleanup trigger | GC decides when nothing can reach it | Strong count reaches `0` → value dropped | | Cleanup timing | Non-deterministic | Deterministic (at the drop of the last owner) | | Mutation of shared data | Any handle can mutate freely | Shared = immutable; need `RefCell`/`Mutex` for mutation | | Cost of a “reference” | Hidden GC bookkeeping + tracing | One pointer + one integer increment/decrement | | Thread safety | Single-threaded model (event loop) | `Rc` single-thread only; `Arc` for threads (atomic count) | | Cycles | Collected by the GC’s reachability tracing | **Leak** unless broken with `Weak` | **The core mental shift:** in JavaScript, *every* object reference is traced for you (the engine periodically walks reachability and frees what it can no longer reach), invisibly, by the runtime. In Rust, the default is single ownership with zero runtime cost; `Rc`/`Arc` is how you *deliberately* buy shared ownership, and you pay a small, visible price (a counter, an allocation header, and, for `Arc`, atomic operations). > **Tip:** Reach for `Rc`/`Arc` only when ownership is *genuinely* shared and you cannot express the relationship with a plain borrow (`&T`). Many designs that look like they need shared ownership are actually fine with borrowing plus [lifetimes](/05-ownership/04-lifetimes/). Shared ownership is a tool, not a default. *** ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) ### Pitfall 1: Trying to mutate the value inside an `Rc` [Section titled “Pitfall 1: Trying to mutate the value inside an Rc”](#pitfall-1-trying-to-mutate-the-value-inside-an-rc) Coming from JavaScript, you expect `rc.field = x` or `*rc += 1` to just work, because shared objects are mutable there. In Rust, `Rc` only gives shared (immutable) access: ```rust 1 use std::rc::Rc; 2 3 fn main() { 4 let count = Rc::new(0u32); 5 let _other = Rc::clone(&count); 6 *count += 1; // does not compile (error[E0594]): can't mutate through Rc 7 println!("{count}"); 8 } ``` Real compiler output: ```text 1 error[E0594]: cannot assign to data in an `Rc` 2 --> src/main.rs:6:5 3 | 4 6 | *count += 1; // does not compile (error[E0594]): can't mutate through Rc 5 | ^^^^^^^^^^^ cannot assign 6 | 7 = help: trait `DerefMut` is required to modify through a dereference, but it is not implemented for `Rc` ``` **Fix:** wrap the inner value in a cell type for interior mutability, `Rc>` (single-threaded) or `Arc>` (across threads), then mutate through `.borrow_mut()` / `.lock()`. See the `Rc>` example above. ### Pitfall 2: Sending an `Rc` to another thread [Section titled “Pitfall 2: Sending an Rc to another thread”](#pitfall-2-sending-an-rc-to-another-thread) `Rc` uses a non-atomic counter, so the compiler refuses to move it into a thread: ```rust 1 use std::rc::Rc; 2 use std::thread; 3 4 fn main() { 5 let shared = Rc::new(String::from("config")); 6 let handle = Rc::clone(&shared); 7 thread::spawn(move || { 8 println!("{handle}"); // does not compile (error[E0277]): Rc is not Send 9 }); 10 } ``` Real compiler output (trimmed): ```text 1 error[E0277]: `Rc` cannot be sent between threads safely 2 --> src/main.rs:7:19 3 | 4 7 | thread::spawn(move || { 5 | ------------- ^------ 6 | | | 7 | _____|_____________within this `{closure@src/main.rs:7:19: 7:26}` 8 | | | 9 | | required by a bound introduced by this call 10 ... | 11 | |_____^ `Rc` cannot be sent between threads safely 12 | 13 = help: within `{closure@src/main.rs:7:19: 7:26}`, the trait `Send` is not implemented for `Rc` ``` **Fix:** use `Arc` instead of `Rc`. The API is identical; just swap the type and `use std::sync::Arc;`. ### Pitfall 3: Reference cycles leak memory [Section titled “Pitfall 3: Reference cycles leak memory”](#pitfall-3-reference-cycles-leak-memory) This is the one case where reference counting fails to clean up. If two `Rc`s point at each other (directly or through a chain), their counts never reach zero, so neither is ever dropped — a real memory **leak**, even in safe Rust: ```rust 1 use std::cell::RefCell; 2 use std::rc::Rc; 3 4 struct Node { 5 name: String, 6 next: RefCell>>, 7 } 8 9 impl Drop for Node { 10 fn drop(&mut self) { 11 println!("dropping node {}", self.name); 12 } 13 } 14 15 fn main() { 16 let a = Rc::new(Node { name: String::from("A"), next: RefCell::new(None) }); 17 let b = Rc::new(Node { name: String::from("B"), next: RefCell::new(None) }); 18 19 // Create a cycle: a -> b -> a 20 *a.next.borrow_mut() = Some(Rc::clone(&b)); 21 *b.next.borrow_mut() = Some(Rc::clone(&a)); 22 23 println!("a strong_count = {}", Rc::strong_count(&a)); 24 println!("b strong_count = {}", Rc::strong_count(&b)); 25 println!("end of main — watch for drop messages..."); 26 } // a and b go out of scope, but each is still held by the other -> NO drops -> leak ``` **Output** (note: the `dropping node` messages **never print**; the nodes leak): ```text 1 a strong_count = 2 2 b strong_count = 2 3 end of main — watch for drop messages... ``` This compiles and runs fine; it is not a crash, just a leak. A JavaScript GC would collect this cycle via reachability tracing; reference counting alone cannot. **Fix:** make one direction of the cycle a **non-owning** reference using `Weak` (a weak handle that does not contribute to the strong count). `Weak`, cycles, and the parent/child pattern are covered in depth in [Section 10: Smart Pointers](/10-smart-pointers/). ### Pitfall 4: Using `.clone()` and not realizing it is cheap (or expecting it to be cheap when it isn’t) [Section titled “Pitfall 4: Using .clone() and not realizing it is cheap (or expecting it to be cheap when it isn’t)”](#pitfall-4-using-clone-and-not-realizing-it-is-cheap-or-expecting-it-to-be-cheap-when-it-isnt) Two confusions, opposite directions: * On an `Rc`, calling `.clone()` is cheap — it bumps a count, it does not copy `BigThing`. New Rust developers sometimes avoid it thinking it is expensive. * On a plain `BigThing` (no `Rc`), `.clone()` *is* a deep copy. Wrapping in `Rc` is precisely how you turn an expensive clone into a cheap one when the data is shared and read-only. **Fix:** prefer the explicit `Rc::clone(&x)` / `Arc::clone(&x)` form so reviewers can see at a glance that a clone is a refcount bump, not a deep copy. *** ## Best Practices [Section titled “Best Practices”](#best-practices) * **Borrow first; reach for `Rc`/`Arc` only for genuine shared ownership.** If a single owner with borrowed access (`&T`) models your data, use that; it is faster and has no runtime bookkeeping. Use `Rc`/`Arc` when *multiple parts of the program must independently keep the value alive* and you cannot tie them to a single owner’s lifetime. * **Use the associated-function clone form.** Write `Rc::clone(&x)` / `Arc::clone(&x)`, not `x.clone()`, so the intent (“share, don’t deep-copy”) is obvious at the call site. This is the idiom recommended by the Rust Book. * **Pick `Rc` by default, upgrade to `Arc` only when crossing threads.** `Arc`’s atomic counter is slightly slower; don’t pay for thread safety you don’t use. And you won’t accidentally use the wrong one — the compiler enforces it via `Send`/`Sync`. * **Combine with the right cell for mutation.** `Rc>` for single-threaded shared-mutable; `Arc>` (or `Arc>`) across threads. Keep the locked/borrowed region small. * **Watch for cycles in graph-shaped data.** Parent→child links can own (`Rc`/`Arc`); child→parent back-links should be `Weak` to avoid leaks. If you find yourself building doubly-linked structures, design the ownership direction up front. * **Reading the count is for diagnostics, not control flow.** `strong_count` is great in tests and logging, but in concurrent code it can change the instant after you read it. Don’t branch on it to decide whether you are the “last” owner; use the value’s own logic instead. *** ## Real-World Example [Section titled “Real-World Example”](#real-world-example) A common production scenario: a parsed form/schema where many fields reuse the **same** validated field type. Instead of cloning the `FieldType` into every `Field` (wasteful) or threading borrows and lifetimes through the whole structure (awkward when fields are built dynamically), you share one canonical `FieldType` via `Rc`. Every field is an independent owner of the shared type; the type is freed only when the last field referencing it is gone. ```rust 1 use std::rc::Rc; 2 3 /// A reusable field definition that several form sections share. 4 #[derive(Debug)] 5 struct FieldType { 6 name: String, 7 max_len: usize, 8 } 9 10 #[derive(Debug)] 11 struct Field { 12 label: String, 13 ty: Rc, // shared, not owned exclusively 14 } 15 16 fn main() { 17 // One canonical "email" type, shared by every field that is an email. 18 let email_type = Rc::new(FieldType { 19 name: String::from("email"), 20 max_len: 254, 21 }); 22 23 let fields = vec![ 24 Field { label: String::from("Primary email"), ty: Rc::clone(&email_type) }, 25 Field { label: String::from("Billing email"), ty: Rc::clone(&email_type) }, 26 Field { label: String::from("Backup email"), ty: Rc::clone(&email_type) }, 27 ]; 28 29 for field in &fields { 30 println!( 31 "{:<14} -> type '{}' (max {} chars)", 32 field.label, field.ty.name, field.ty.max_len 33 ); 34 } 35 36 // 3 fields each hold a handle + the original `email_type` binding = 4. 37 println!("shared FieldType strong_count = {}", Rc::strong_count(&email_type)); 38 } ``` **Output:** ```text 1 Primary email -> type 'email' (max 254 chars) 2 Billing email -> type 'email' (max 254 chars) 3 Backup email -> type 'email' (max 254 chars) 4 shared FieldType strong_count = 4 ``` **Why this is idiomatic:** * The `FieldType` is allocated **once**. Three `Field`s and the original binding share it; no string is deep-copied per field. * Each `Field` is a real, independent owner — a field can be moved into another collection, stored, or dropped without invalidating the others, because the `Rc` keeps the shared type alive until the last owner is gone. * `strong_count` is `4` because there are four live owners: the original `email_type` plus one inside each of the three fields. When `fields` and `email_type` go out of scope, the count walks down to `0` and the `FieldType` is freed — deterministically, no GC. * If this were a read-heavy server reused across requests/threads, you would change `Rc` to `Arc` and the rest of the code would stay the same. *** ## Further Reading [Section titled “Further Reading”](#further-reading) ### Official Documentation [Section titled “Official Documentation”](#official-documentation) * [The Rust Book — `Rc`, the Reference Counted Smart Pointer](https://doc.rust-lang.org/book/ch15-04-rc.html) * [The Rust Book — Reference Cycles Can Leak Memory](https://doc.rust-lang.org/book/ch15-06-reference-cycles.html) (`Weak`) * [The Rust Book — Shared-State Concurrency](https://doc.rust-lang.org/book/ch16-03-shared-state.html) (`Arc

Hello from index.html