Learn Rust from absolute zero

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

rustc --version
cargo --version
rustup update          # upgrade to the latest stable, anytime
rustup default stable  # or: stable / beta / nightly
rustup component add clippy rustfmt rust-src

cargo new hello_rust
cd hello_rust
cargo run

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

hello_rust/
├── Cargo.toml        # the manifest: name, version, dependencies, metadata
├── Cargo.lock        # exact resolved versions (commit this for binaries!)
├── .gitignore        # ignores target/
├── src/
│   ├── main.rs       # binary crate root — this is your program
│   └── lib.rs        # (optional) library crate root
├── tests/            # integration tests (black-box, one file = one test binary)
├── examples/         # small runnable examples: cargo run --example foo
├── benches/          # benchmarks (criterion)
└── target/           # ALL build output. never edit, safe to delete

[package]
name = "hello_rust"
version = "0.1.0"
edition = "2021"          # language version: 2015 | 2018 | 2021 | 2024

[dependencies]
serde = { version = "1.0", features = ["derive"] }
rand = "0.8"

[dev-dependencies]
criterion = "0.5"         # only used by tests & benchmarks

[profile.release]
opt-level = 3             # maximum optimisation
lto = true                # link-time optimisation
codegen-units = 1
panic = "abort"

use std::io;   // bring the I/O module into scope

fn main() {
    println!("What is your name?");

    let mut name = String::new();          // a growable, heap-allocated string

    io::stdin()
        .read_line(&mut name)              // &mut = "please fill THIS in"
        .expect("failed to read line");    // handle the error (see Chapter 09)

    let name = name.trim();                // shadow the variable with a cleaned version

    println!("Hello, {name}! Welcome to Rust.");  // inline variable interpolation
}

fn main() {
    let x = 5;              // immutable: that's it, x is 5 forever
    // x = 6;               // ❌ compile error E0384: cannot assign twice

    let mut y = 5;          // explicitly mutable
    y = 6;                  // ✅ fine
    println!("y = {y}");    // y = 6

    // constants: ALWAYS immutable, must be ANNOTATED, chosen at compile time,
    // may be declared anywhere (even at module scope), conventionally SCREAMING_CASE.
    const MAX_POINTS: u32 = 100_000;
    const SECONDS_IN_DAY: u64 = 24 * 60 * 60;
    println!("{MAX_POINTS} / {SECONDS_IN_DAY}");

    // static: like const, but has a fixed memory address and can implement Sync.
    static GREETING: &str = "hello from a static";

    let spaces = "   ";     // type &str (a string slice) — inferred from the literal
    let mut spaces = spaces.len(); // ⚠️ this is a NEW variable (shadowing), type usize
    spaces += 1;
    println!("{spaces}");
}

fn main() {
    let input = "  42  ";
    let input = input.trim();        // now a &str without whitespace
    let input: u32 = input.parse().expect("not a number");  // now a number!

    println!("{input} + 1 = {}", input + 1);   // 42 + 1 = 43

    // Shadowing lets you CHANGE TYPE. `mut` does not:
    let spaces = "   ";
    // let spaces = spaces.len();   // ✅ allowed: new variable, new type
    let mut sp = "   ";
    // sp = sp.len();               // ❌ E0308: expected &str, found usize
}

fn main() {
    // Floating point: f64 is the default (same speed as f32 on modern CPUs, twice precision)
    let pi = 3.141592653589793;     // f64
    let small: f32 = 2.5;           // explicit f32 when memory matters (GPU, embedded)
    println!("{} {}", pi, 1.0_f64.sqrt());

    // Booleans are exactly 1 byte
    let is_rust_fun: bool = true;
    let nope = false;

    // char is a 4-byte Unicode scalar value — NOT a byte!
    let letter = 'A';
    let emoji = '🦀';               // yes, a char
    let heart = '❤';
    println!("{letter} {emoji} {heart} — all chars are 4 bytes");

    // Arithmetic and explicit casting with `as`
    let a: i32 = 7;
    let b: i32 = -3;
    println!("{} {} {} {}", a + b, a - b, a * b, a / b);  // 4 10 21 -2 (integer division!)
    println!("remainder: {}", a % b);                      // 1
    println!("7.0 / 2.0 = {}", 7.0 / 2.0);                 // 3.5 (floats divide normally)
    println!("cast: {}", a as f64 / 2.0);                  // 3.5
    println!("bool as int: {}", is_rust_fun as i32);       // 1
}

fn main() {
    let point: (i32, f64, char) = (10, 2.5, 'x');

    // Destructure with a pattern:
    let (x, y, z) = point;
    println!("{x} {y} {z}");

    // Or access with zero-based dot indices:
    println!("{} {}", point.0, point.2);

    // The empty tuple () is the "unit type" — it means "no meaningful value"
    let nothing: () = ();
    println!("() occupies {} bytes", std::mem::size_of_val(&nothing)); // 0 bytes

    // A 1-tuple needs a trailing comma:
    let one = (42,);
    println!("{:?}", one);
}

fn main() {
    // ARRAY: fixed length, lives on the stack, one contiguous block, type [T; N]
    let months: [&str; 12] = ["Jan","Feb","Mar","Apr","May","Jun",
                              "Jul","Aug","Sep","Oct","Nov","Dec"];
    let zeros = [0; 5];            // [0, 0, 0, 0, 0] — repeat initialiser
    println!("{months:?}  {zeros:?}");

    // Indexing is CHECKED at runtime — out of bounds panics instead of corrupting memory
    println!("{}", months[2]);     // "Mar"
    // println!("{}", months[99]); // 💥 panic: index out of bounds: len is 12, index is 99

    // Prefer .get() when the index might be invalid — it returns Option<&T>, never panics
    match months.get(99) {
        Some(m) => println!("{m}"),
        None    => println!("no month at that index"),
    }

    // SLICE: a *view* into part of an array/string — just (pointer, length), 2 words
    let slice = &months[1..4];     // ["Feb", "Mar", "Apr"]
    println!("{slice:?}  len={}", slice.len());
    println!("size of the slice handle itself: {}", std::mem::size_of_val(&slice)); // 16 on 64-bit (ptr + length)

    // Vec<T>: heap-allocated, growable. See Chapter 08.
    let mut nums: Vec<i32> = vec![1, 2, 3];
    nums.push(4);
    println!("{nums:?}");
}

//   ┌── fn keyword      ┌─ parameter: name: Type (ANNOTATIONS REQUIRED)
//   │                   │
fn  add(a: i32, b: i32) -> i32 {
    a + b                // ← no semicolon: this is an EXPRESSION, returned automatically
}

fn shout(text: &str) -> String {   // return type after the arrow
    format!("{text}!!!")            // last expression is the return value
}

fn do_something() {                 // no -> means it returns ()  (the unit type)
    println!("side effect only");
    // an implicit `; ()` is appended here
}

fn early_return(x: i32) -> i32 {
    if x < 0 {
        return 0;        // explicit early return with `return` keyword
    }
    x * 2                // tail expression
}

// Never returns (diverging function) — used for panic!, exit(), infinite loops
fn never() -> ! {
    panic!("this function never returns a value")
}

fn main() {
    println!("{}", add(2, 3));        // 5
    println!("{}", shout("hello"));   // hello!!!
    do_something();
    println!("{}", early_return(-7)); // 0
}

fn main() {
    // A STATEMENT performs an action and returns () — it does NOT return a value
    let y = 6;                          // statement

    // AN EXPRESSION evaluates to a value
    let z = {                           // a block is an expression!
        let inner = 3 * 2;
        inner + 1                       // ← no semicolon → this block evaluates to 7
    };
    println!("z = {z}");                // 7

    // Adding a semicolon turns an expression into a statement returning ()
    let w = { 5; };                     // type is () — the 5 is thrown away
    println!("w = {w:?}");              // ()

    // ❌ This is the classic beginner error:
    // let bad = (let x = 5);          // error: `let` is a statement, not an expression
}

fn main() {
    let temperature = 28;

    // Conditions MUST be bool — Rust never coerces numbers/strings to boolean
    if temperature > 25 {
        println!("hot");
    } else if temperature > 10 {
        println!("pleasant");
    } else {
        println!("cold");
    }
    // if temperature { }  // ❌ E0308: expected `bool`, found integer

    // Use `if` as an expression to choose a value — no ternary operator needed
    let mood = if temperature > 25 { "melting" } else { "fine" };
    println!("{mood}");

    // Both branches must have the SAME type
    let n = if temperature > 25 { 10 } else { "ten" };  // ❌ E0308: mismatched types
}

fn main() {
    // ── loop: repeats forever… but can RETURN A VALUE ────────────────────
    let mut counter = 0;
    let result = loop {
        counter += 1;
        if counter == 10 {
            break counter * 2;      // break with a value → the loop evaluates to 20
        }
    };
    println!("result = {result}");  // 20

    // ── while: conditional looping ───────────────────────────────────────
    let mut n = 3;
    while n != 0 {
        println!("{n}!");
        n -= 1;
    }
    println!("LIFTOFF 🚀");

    // ── for: iterate over anything (ranges, arrays, iterators) ───────────
    for i in 0..4 {                 // 0,1,2,3  (end is exclusive)
        print!("{i} ");
    }
    println!();
    for i in 0..=4 {                // 0,1,2,3,4  (inclusive)
        print!("{i} ");
    }
    println!();
    for (index, letter) in ["a","b","c"].iter().enumerate() {
        print!("[{index}]={letter} ");
    }
    println!();

    // for loops over ITERATORS are the idiomatic Rust way (and they're optimised
    // to exactly the same machine code as the equivalent `while` loop)
    let sum: i32 = (1..=100).sum();
    println!("sum 1..=100 = {sum}");   // 5050

    // ── labelled breaks: escape nested loops ────────────────────────────
    'outer: for x in 0..5 {
        for y in 0..5 {
            if x + y == 6 { break 'outer; }   // exits BOTH loops
            if y == 2 { continue 'outer; }    // continues the OUTER loop
        }
    }
}

fn main() {
    {                                   // s is not yet valid
        let s = String::from("hello");  // s is valid from here onward
        println!("{s}");                // use s — it's alive
    }                                   // ← scope ends: `drop(s)` is called HERE automatically
    // s is no longer valid — trying to use it is a compile error

    println!("s is gone, and the memory was already freed.");
}

fn main() {
    let s1 = String::from("hello");
    let s2 = s1.clone();        // DEEP copy of the heap data — explicit and deliberate
    println!("{s1} {s2}");      // both valid

    // `clone()` is always available on types implementing Clone.
    // It is EXPLICIT by design: Rust wants you to know when you're allocating.
    // Compare with Python/Java where every assignment may secretly copy or retain.
}

fn takes_ownership(s: String) {      // s comes into scope: it now owns the String
    println!("got: {s}");
}                                    // s is dropped here → memory freed ✅

fn makes_copy(x: i32) {              // i32 is Copy, so nothing is moved
    println!("got: {x}");
}

fn gives_ownership() -> String {     // creates a String and hands it to the caller
    String::from("mine now")
}

fn takes_and_gives_back(s: String) -> String {   // borrows it, then gives it back
    println!("borrowed: {s}");
    s
}

fn main() {
    let s = String::from("hello");
    takes_ownership(s);              // s is MOVED into the function
    // println!("{s}");              // ❌ E0382: s was moved

    let x = 5;
    makes_copy(x);                   // fine — x is Copy
    println!("{x}");                 // still fine ✅

    let s1 = gives_ownership();      // s1 owns the returned String
    let s2 = takes_and_gives_back(s1); // s1 moved in, result moved into s2
    // println!("{s1}");             // ❌ moved
    println!("{s2}");                // ✅
}

fn calculate_length(s: &String) -> usize {   // s is a reference: it borrows
    s.len()                                   // s points to a String it does NOT own
}                                             // s goes out of scope… but nothing is dropped

fn append_greeting(s: &mut String) {          // mutable borrow: may modify
    s.push_str(", world!");
}

fn main() {
    let s1 = String::from("hello");

    let len = calculate_length(&s1);   // pass a reference — s1 is only borrowed
    println!("'{s1}' is {len} chars"); // ✅ s1 is still valid! No move happened

    let mut s2 = String::from("hello");
    append_greeting(&mut s2);          // pass a MUTABLE reference
    println!("{s2}");                  // hello, world!

    // Reference syntax recap:
    //   &T     → shared/immutable borrow ("read-only lens")
    //   &mut T → exclusive/mutable borrow ("read-write lens")
    //   *&T    → dereference: access the value a reference points to
    let n = 42;
    let r = &n;
    println!("{}", *r + 1);            // 43 — explicit deref
    println!("{}", r + 1);             // 43 — Rust auto-derefs in most contexts
}

// Taking &str instead of &String is more flexible:
// it accepts string literals, &String, and slices alike.
fn first_word(s: &str) -> &str {
    let bytes = s.as_bytes();
    for (i, &b) in bytes.iter().enumerate() {
        if b == b' ' {
            return &s[..i];     // slice from start up to (not including) i
        }
    }
    &s[..]                       // no space: the whole string
}

fn sum(numbers: &[i32]) -> i32 {  // works with arrays AND Vecs
    numbers.iter().sum()
}

fn main() {
    let sentence = String::from("hello wonderful world");
    let word = first_word(&sentence);
    println!("first word: {word}");      // hello

    let array = [1, 2, 3, 4, 5];
    let vector = vec![10, 20, 30];
    println!("{}", sum(&array));          // 15  — array auto-coerces to slice
    println!("{}", sum(&vector));        // 60  — Vec auto-coerces to slice

    // Slicing syntax: &collection[a..b]  (b exclusive), &collection[a..=b] (inclusive)
    let mid = &array[1..4];              // [2, 3, 4]
    println!("{mid:?}");

    // ⚠️ Slices must land on valid UTF-8 boundaries for str:
    let s = "héllo";
    // let bad = &s[0..2];              // 💥 panic: byte index 2 is not a char boundary
    println!("{:?}", &s[0..1]);          // "h" — safe because é starts at byte 1..3
}

//                 'a is just a NAME for "the region where x and y are valid"
//                 ┌───┘        ┌───┘
fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
    if x.len() > y.len() { x } else { y }
}
// Reads as: "given two string slices that live AT LEAST as long as 'a,
//            return a string slice that also lives at least as long as 'a."
// In other words: the returned reference is valid for as long as BOTH inputs are.

fn main() {
    let s1 = String::from("long string");
    let result;
    {
        let s2 = String::from("xyz");
        result = longest(s1.as_str(), s2.as_str());
        println!("longest inside the block: {result}");   // ✅ fine
    }
    // println!("{result}");   // ❌ E0597: `s2` does not live long enough
                              // because 'a had to cover both s1 and s2
}

// A struct that borrows data must declare how long that borrow lasts.
// The instance of Excerpt can never outlive the data it points to.
struct Excerpt<'a> {
    part: &'a str,          // a borrowed string slice
    highlight: usize,
}

impl<'a> Excerpt<'a> {
    // Lifetime elision: one &self input → the output lifetime is assumed to be self's
    fn announce(&self) -> &str {
        self.part
    }
}

fn main() {
    let novel = String::from("Call me Ishmael. Some years ago...");
    let first = novel.split('.').next().expect("no sentence");
    let e = Excerpt { part: first, highlight: 7 };
    println!("{}", e.announce());
}   // e drops, then novel drops — order is always reverse of declaration

// 'static means "lives for the entire duration of the program".
// String literals are 'static: they're baked into the compiled binary.
fn returns_static() -> &'static str {
    "I live forever"
}

fn main() {
    let s: &'static str = returns_static();
    println!("{s}");

    // ⚠️ Common beginner instinct: "I'll just add 'static to make it compile."
    // That is almost always wrong. 'static is not a fix — it's a promise the
    // compiler will demand you keep. Fix the ownership structure instead.
}

// Deriving traits gives you useful behaviour for free:
// Debug → println!("{:?}"), Clone → .clone(), PartialEq → ==
#[derive(Debug, Clone, PartialEq)]
struct User {
    username: String,
    email: String,
    sign_in_count: u64,
    active: bool,
}

// Tuple struct: useful for lightweight wrappers / newtypes
struct Color(u8, u8, u8);
struct Meters(f64);

// Unit struct: no data, but has a type identity (great as markers/traits)
struct AlwaysEqual;

fn build_user(email: String, username: String) -> User {
    User {
        email,               // field init shorthand: same name as the variable
        username,
        sign_in_count: 1,
        active: true,
    }
}

fn main() {
    let mut user = build_user(String::from("a@b.com"), String::from("ada"));
    user.email = String::from("new@b.com");     // mutate: needs `mut`

    // Struct update syntax: fill remaining fields from another instance
    let user2 = User { email: String::from("x@y.com"), ..user.clone() };

    println!("{user:?}");    // pretty-print with :?  (or {:#?} for multi-line)
    println!("{}", user2.username);

    let black = Color(0, 0, 0);
    println!("({}, {}, {})", black.0, black.1, black.2);

    let d = Meters(10.0);
    println!("{}m", d.0);
}

#[derive(Debug)]
struct Rectangle { width: f64, height: f64 }

impl Rectangle {
    // ── associated function ("static method") — called as Rectangle::square(3.0)
    fn square(size: f64) -> Self {          // Self = Rectangle
        Self { width: size, height: size }
    }

    // ── methods take `self` in one of three flavours:
    fn area(&self) -> f64 {                 // borrow: read-only, most common
        self.width * self.height
    }

    fn scale(&mut self, factor: f64) {      // mutable borrow: modify in place
        self.width *= factor;
        self.height *= factor;
    }

    fn into_parts(self) -> (f64, f64) {     // take ownership: consume the value
        (self.width, self.height)
    }

    // ── multiple impl blocks are allowed (used for traits and conditional impls)
}

impl Rectangle {
    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

fn main() {
    let mut rect = Rectangle::square(5.0);
    println!("area = {}", rect.area());          // 25
    rect.scale(2.0);
    println!("scaled = {}", rect.area());        // 100
    println!("{:?}", rect);                      // Rectangle { width: 10.0, height: 10.0 }
    let (w, h) = rect.into_parts();              // rect is consumed here
    println!("{w} x {h}");
}

#[derive(Debug)]
enum Shape {
    Circle(f64),                            // variant with one field: radius
    Rectangle { width: f64, height: f64 },  // variant with named fields
    Triangle(f64, f64, f64),                // variant with three fields
    Nothing,                                // unit variant
}

// The most important enum in the entire language —
// it replaces null with a type you are FORCED to check.
enum Option<T> {
    None,        // no value
    Some(T),     // a value of type T
}

#[derive(Debug)]
enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
    ChangeColor(i32, i32, i32),
}

// Enums can have methods too
impl Message {
    fn summary(&self) -> String {
        match self {
            Message::Quit => String::from("quit"),
            Message::Move { x, y } => format!("move to {x},{y}"),
            Message::Write(text) => format!("write: {text}"),
            Message::ChangeColor(r, g, b) => format!("colour {r},{g},{b}"),
        }
    }
}

fn area(shape: &Shape) -> f64 {
    match shape {
        Shape::Circle(r) => std::f64::consts::PI * r * r,
        Shape::Rectangle { width, height } => width * height,
        Shape::Triangle(a, b, c) => {
            let s = (a + b + c) / 2.0;
            (s * (s - a) * (s - b) * (s - c)).sqrt()   // Heron's formula
        }
        Shape::Nothing => 0.0,
    }
}

fn main() {
    let shapes = [
        Shape::Circle(2.0),
        Shape::Rectangle { width: 3.0, height: 4.0 },
        Shape::Triangle(3.0, 4.0, 5.0),
        Shape::Nothing,
    ];
    for s in &shapes {
        println!("{s:?} has area {:.2}", area(s));
    }

    let m = Message::Write(String::from("hi"));
    println!("{}", m.summary());
}

fn main() {
    // ── literals, ranges, and catch-alls ────────────────────────────────
    let n = 13;
    match n {
        1 => println!("one"),
        2 | 3 | 5 | 7 | 11 => println!("small prime"),   // multiple patterns with |
        12..=19 => println!("teenager"),                  // inclusive range
        _ => println!("something else"),                  // catch-all (required!)
    }

    // ── binding values with @ and destructuring ─────────────────────────
    let point = (3, -7);
    match point {
        (0, 0) => println!("origin"),
        (x, 0) => println!("on the x axis at {x}"),
        (0, y) => println!("on the y axis at {y}"),
        (x, y) if x == y => println!("diagonal"),         // match GUARD
        (x, y) => println!("point ({x}, {y})"),
    }

    // ── destructuring enums, structs and references ─────────────────────
    #[derive(Debug)]
    enum Coin { Penny, Nickel, Dime, Quarter(String) }

    fn value(c: &Coin) -> u8 {
        match c {
            Coin::Penny => 1,
            Coin::Nickel => 5,
            Coin::Dime => 10,
            Coin::Quarter(state) => { println!("quarter from {state}"); 25 }
        }
    }
    println!("{}", value(&Coin::Quarter(String::from("Texas"))));

    // ── nested patterns with .. ─────────────────────────────────────────
    let triple = (1, 2, 3, 4, 5);
    match triple {
        (first, .., last) => println!("first={first}, last={last}"),
    }
}

fn main() {
    let config_max: Option<u8> = Some(3);

    // if let: when you only care about ONE case
    if let Some(max) = config_max {
        println!("max is {max}");
    } else {
        println!("no maximum");
    }

    // while let: loop while a pattern keeps matching
    let mut stack = vec![1, 2, 3];
    while let Some(top) = stack.pop() {
        print!("{top} ");       // 3 2 1
    }
    println!();

    // let-else: handle the failure case and continue (Rust 1.65+)
    fn get_id() -> Option<u32> { Some(42) }
    let Some(id) = get_id() else {
        println!("no id available");
        return;
    };
    println!("id = {id}");

    // matches!: a bool macro — great inside .filter() or assertions
    let x = Some(3);
    println!("{}", matches!(x, Some(3)));            // true
    let nums = [1, 2, 3, 4, 5];
    let evens: Vec<_> = nums.iter().filter(|&&n| matches!(n, x if x % 2 == 0)).collect();
    println!("{evens:?}");
}

fn main() {
    // Creating
    let mut v: Vec<i32> = Vec::new();       // empty, type inferred from use
    let mut v2 = vec![1, 2, 3];             // macro with initial values
    let zeros = vec![0u8; 1024];            // 1024 zero bytes

    // Adding & removing
    v.push(10);
    v.push(20);
    v.push(30);
    let last = v.pop();                     // Option<i32> — Some(30) or None if empty
    println!("{last:?}");

    // Reading — two ways:
    let third = &v2[2];                     // panics if out of bounds (fast path)
    let maybe = v2.get(99);                 // returns Option<&i32> — never panics
    match maybe {
        Some(val) => println!("found {val}"),
        None      => println!("no element there"),
    }

    // Iterating — note: &v (borrow), v.iter(), or v.into_iter() (consume)
    for x in &v2 { print!("{x} "); }        // 1 2 3
    println!();
    for x in &mut v2 { *x *= 10; }          // mutate in place
    println!("{v2:?}");                     // [10, 20, 30]

    // Storing different types: use an enum or Box<dyn Trait>
    #[derive(Debug)]
    enum Cell { Int(i32), Text(String) }
    let row = vec![Cell::Int(1), Cell::Text(String::from("hello"))];
    println!("{row:?}");

    // Common operations
    let mut nums = vec![5, 2, 8, 1, 9];
    nums.sort();                             // [1, 2, 5, 8, 9]
    nums.dedup();                            // removes consecutive duplicates
    nums.retain(|&n| n > 2);               // keep only matching elements
    println!("{nums:?}");                    // [5, 8, 9]
    println!("{}", nums.iter().sum::<i32>()); // 22
    let doubled: Vec<i32> = nums.iter().map(|n| n * 2).collect();
    println!("{doubled:?}");                 // [10, 16, 18]
}

use std::collections::{HashMap, HashSet, BTreeMap};

fn main() {
    let mut scores: HashMap<String, i32> = HashMap::new();
    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);

    // Insert-if-absent / update-if-present — the `entry` API prevents double lookups
    scores.entry(String::from("Blue")).or_insert(25);      // stays 10 (already there)
    scores.entry(String::from("Red")).or_insert(99);       // inserted as 99

    // Count words — the classic `entry` idiom
    let text = "hello world wonderful hello";
    let mut counts: HashMap<&str, usize> = HashMap::new();
    for word in text.split_whitespace() {
        *counts.entry(word).or_insert(0) += 1;
    }
    println!("{counts:?}");

    // Iterating yields (&K, &V)
    for (team, score) in &scores {
        println!("{team}: {score}");
    }

    // Lookup returns Option<&V> — never a null, never a panic
    let blue = scores.get("Blue");        // Option<&i32>
    println!("{blue:?}");

    // Ownership rules apply! These would move the strings out of the map:
    // scores.insert(String::from("x"), 1); let k = String::from("x"); scores.get(&k);

    // BTreeMap: sorted keys, O(log n) — use when you need ordered iteration
    let ordered: BTreeMap<&str, i32> = [("b", 2), ("a", 1), ("c", 3)].into();
    println!("{ordered:?}");

    // HashSet: uniqueness with O(1) membership checks
    let mut seen: HashSet<String> = HashSet::new();
    seen.insert(String::from("alice"));
    println!("{}", seen.contains("alice"));   // true
}

fn main() {
    // Creating & converting
    let s1 = String::from("hello");
    let s2 = s1.clone();
    let s3 = "literal".to_string();
    let s4 = format!("{}-{}", "a", "b");     // like println! but returns a String
    let borrowed: &str = &s1;                // borrow a String as a slice
    let owned: String = borrowed.to_owned(); // back to an owned String

    // Building
    let mut s = String::from("hello");
    s.push(' ');                             // single char
    s.push_str("world");                     // string slice
    s += "!";                                // via AddAssign
    let combined = format!("{s} again");     // format! never moves its inputs
    println!("{combined}");

    // ⚠️ Slicing by BYTES — this trips everyone up
    let s = "Здравствуйте";                  // Cyrillic: 2 bytes per character
    println!("chars: {}", s.chars().count());        // 12
    println!("bytes: {}", s.len());                  // 24
    // let slice = &s[0..2];                         // 💥 panics: not a char boundary

    // Iterate safely
    for c in "नमस्ते".chars() { print!("{c}"); }       // by Unicode scalar value
    println!();
    for b in "abc".bytes() { print!("{b} "); }       // 97 98 99
    println!();

    // Searching & transforming
    let sentence = "the quick brown fox jumps over the lazy dog";
    println!("{}", sentence.contains("brown"));           // true
    println!("{}", sentence.starts_with("the"));          // true
    println!("{}", sentence.replace("dog", "cat"));
    let words: Vec<&str> = sentence.split_whitespace().collect();
    println!("{} words", words.len());                    // 9
    println!("{}", sentence.to_uppercase());
    println!("{:?}", sentence.split(',').collect::<Vec<_>>());
}

fn main() {
    // Explicit panic with a message
    // panic!("crashed and burned");

    // These all panic automatically:
    let v = vec![1, 2, 3];
    // let x = v[99];                       // 💥 index out of bounds
    // let y: u8 = 255; let z = y + 1;      // 💥 overflow (debug builds only)
    // let n: i32 = "abc".parse().unwrap(); // 💥 called `Option::unwrap()` on `Err`

    // A graceful way to stop the program when there's no sensible recovery:
    let config = std::fs::read_to_string("config.toml")
        .expect("config.toml must exist for the app to run");  // `.expect(msg)` = unwrap + message

    println!("{config}");
}

use std::num::ParseIntError;

// The signature TELLS you this can fail. No documentation needed.
fn parse_age(input: &str) -> Result<u8, ParseIntError> {
    input.trim().parse::<u8>()      // `parse` already returns Result
}

fn main() {
    // Pattern matching is the most explicit way to handle it
    match parse_age("42") {
        Ok(age)  => println!("age is {age}"),
        Err(e)   => println!("could not parse: {e}"),
    }

    // if let for one-sided handling
    if let Ok(age) = parse_age("29") {
        println!("got {age}");
    }

    // Combinators: transform without branching
    let doubled = parse_age("21").map(|age| age * 2);        // Result<u8, _>
    println!("{doubled:?}");                                  // Ok(42)

    // Fallbacks
    let age = parse_age("oops").unwrap_or(0);                 // 0 on failure
    let age = parse_age("oops").unwrap_or_else(|_| 18);       // compute a default
    let age = parse_age("oops").unwrap_or_default();          // 0 (Default trait)
    println!("{age}");

    // `?` — the propagating operator (the idiomatic way)
    fn process() -> Result<u8, ParseIntError> {
        let a = parse_age("10")?;      // on Err: return early from `process`
        let b = parse_age("20")?;
        Ok(a + b)
    }
    println!("{:?}", process());       // Ok(30)
}

use std::fs::File;
use std::io::{self, Read};
use std::num::ParseIntError;

// A custom error type — see `thiserror` for a derive macro that writes this for you
#[derive(Debug)]
enum AppError {
    Io(io::Error),
    Parse(ParseIntError),
    Invalid(String),
}

// Implementing `From` lets `?` convert automatically
impl From<io::Error> for AppError {
    fn from(e: io::Error) -> Self { AppError::Io(e) }
}
impl From<ParseIntError> for AppError {
    fn from(e: ParseIntError) -> Self { AppError::Parse(e) }
}

fn read_number_from(path: &str) -> Result<i32, AppError> {
    let mut file = File::open(path)?;             // io::Error → AppError via From
    let mut contents = String::new();
    file.read_to_string(&mut contents)?;          // same
    let n = contents.trim().parse::<i32>()?;      // ParseIntError → AppError
    if n < 0 {
        return Err(AppError::Invalid(String::from("must be positive")));
    }
    Ok(n)
}

fn main() {
    match read_number_from("number.txt") {
        Ok(n)  => println!("read {n}"),
        Err(e) => println!("failed: {e:?}"),
    }
}

fn main() {
    let x: Option<i32> = Some(5);
    let e: Option<i32> = None;

    // Transform
    println!("{:?}", x.map(|n| n * 2));             // Some(10)
    println!("{:?}", e.map(|n| n * 2));             // None

    // Chain operations that themselves return Option
    println!("{:?}", x.and_then(|n| Some(n + 1)));  // Some(6)

    // Provide defaults
    println!("{}", e.unwrap_or(0));                 // 0
    println!("{}", e.unwrap_or_else(|| expensive()));  // computed only when None
    println!("{}", e.unwrap_or_default());          // 0

    // Combine two Options
    let a = Some(1); let b = Some(2);
    println!("{:?}", a.zip(b));                     // Some((1, 2))
    println!("{:?}", a.and(b));                     // Some(2)  (both must exist)
    println!("{:?}", a.or(e));                      // Some(1)  (first one that exists)

    // Convert
    println!("{:?}", x.ok_or("missing"));           // Result<i32, &str> = Ok(5)
    let r: Result<i32, String> = Ok(3);
    println!("{:?}", r.ok());                       // Some(3)

    // Side effects without unwrapping
    if let Some(n) = x { println!("have {n}"); }
    x.inspect(|n| println!("found {n}"));
    println!("{}", x.is_some_and(|n| n > 3));       // true
}

fn expensive() -> i32 { 42 }

// Without generics you'd write this twice (or three times, or ten times):
fn largest_i32(list: &[i32]) -> i32 { let mut m = list[0]; for &n in list { if n > m { m = n; } } m }
fn largest_f64(list: &[f64]) -> f64 { let mut m = list[0]; for &n in list { if n > m { m = n; } } m }

// With generics: one implementation
fn largest<T: PartialOrd>(list: &[T]) -> &T {
    let mut biggest = &list[0];
    for item in list {
        if item > biggest { biggest = item; }
    }
    biggest
}

// Generic structs
struct Point<T> { x: T, y: T }
struct Pair<A, B> { first: A, second: B }

// Generic methods — the <T> after `impl` declares the type parameter
impl<T> Point<T> {
    fn x(&self) -> &T { &self.x }
}

// Specialised: only for Point<f64>
impl Point<f64> {
    fn distance_from_origin(&self) -> f64 {
        (self.x.powi(2) + self.y.powi(2)).sqrt()
    }
}

fn main() {
    let nums = vec![34, 50, 25, 100, 65];
    println!("largest = {}", largest(&nums));       // 100

    let ints = Point { x: 5, y: 10 };
    let floats = Point { x: 1.5, y: 4.2 };
    println!("{} {}", ints.x(), floats.distance_from_origin());

    let pair = Pair { first: 1, second: "one" };
    println!("{:?} {:?}", pair.first, pair.second);
}

// Define a trait: a named set of methods
trait Summary {
    // Required method
    fn summarize(&self) -> String;

    // Default method — implementors may override it
    fn headline(&self) -> String {
        format!("Read more… ({})", self.summarize())
    }
}

struct Article { title: String, author: String, content: String }
struct Tweet { username: String, body: String }

impl Summary for Article {
    fn summarize(&self) -> String {
        format!("{}, by {}", self.title, self.author)
    }
    // headline() uses the default
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("@{}: {}", self.username, self.body)
    }
    fn headline(&self) -> String {
        format!("New tweet from @{}", self.username)   // override the default
    }
}

// ── Trait bounds: "any type that implements Summary" ─────────────────────
fn notify(item: &impl Summary) {                 // clean syntax
    println!("Breaking: {}", item.summarize());
}

fn notify_verbose<T: Summary>(item: &T) {        // identical meaning
    println!("Breaking: {}", item.summarize());
}

// Multiple bounds with `+`
fn both(item: &(impl Summary + std::fmt::Display)) {}

// Where clauses make complex bounds readable
fn complex<T, U>(t: &T, u: &U) -> String
where
    T: Summary + Clone,
    U: Summary + std::fmt::Debug + ?Sized,
{
    format!("{} and {:?}", t.summarize(), u)
}

fn main() {
    let a = Article { title: String::from("Rust 1.80"), author: String::from("Ferris"),
                      content: String::from("…") };
    let t = Tweet { username: String::from("rustlang"), body: String::from("new release!") };
    notify(&a);
    notify(&t);
    println!("{}", t.headline());
}

use std::fmt::Debug;

trait Shape {
    fn area(&self) -> f64;
    fn name(&self) -> &str { "shape" }
}

struct Circle(f64);
struct Rect { w: f64, h: f64 }

impl Shape for Circle {
    fn area(&self) -> f64 { std::f64::consts::PI * self.0 * self.0 }
    fn name(&self) -> &str { "circle" }
}
impl Shape for Rect {
    fn area(&self) -> f64 { self.w * self.h }
    fn name(&self) -> &str { "rectangle" }
}

fn main() {
    // Static dispatch: generic, fast, but `shapes` must be homogeneous
    fn total_static(items: &[&dyn Shape]) -> f64 {
        items.iter().map(|s| s.area()).sum()
    }

    // Dynamic dispatch: one Vec can hold DIFFERENT concrete types
    let shapes: Vec<Box<dyn Shape>> = vec![
        Box::new(Circle(1.0)),
        Box::new(Rect { w: 2.0, h: 3.0 }),
    ];
    for s in &shapes {
        println!("{}: {:.2}", s.name(), s.area());
    }
    println!("total: {:.2}", total_static(&[&Circle(1.0), &Rect{w:2.0,h:3.0}]));

    // impl Trait in return position: "some type that implements Display"
    fn make_greeting() -> impl std::fmt::Display {
        String::from("hello")
    }
    println!("{}", make_greeting());
}

use std::fmt;

#[derive(Debug, PartialEq)]
struct Color { r: u8, g: u8, b: u8 }

// Display must be implemented by hand — Rust wants your human output to be deliberate
impl fmt::Display for Color {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "#{:02x}{:02x}{:02x}", self.r, self.g, self.b)
    }
}

// From<&str> gives us Into<Color> automatically
impl From<&str> for Color {
    fn from(hex: &str) -> Self {
        let n = u32::from_str_radix(hex.trim_start_matches('#'), 16).unwrap_or(0);
        Color { r: ((n >> 16) & 0xFF) as u8, g: ((n >> 8) & 0xFF) as u8, b: (n & 0xFF) as u8 }
    }
}

fn main() {
    let c = Color { r: 249, g: 115, b: 22 };
    println!("Display: {c}");          // #f97316
    println!("Debug:   {c:?}");        // Color { r: 249, g: 115, b: 22 }
    let c2: Color = "#22c55e".into();  // uses From<&str>
    println!("{c2}");                  // #22c55e
    println!("{}", c == c2);           // false (PartialEq)
}

// NEWTYPE: a tuple struct wrapping a primitive gives you type safety at ZERO cost.
struct Meters(f64);
struct Seconds(f64);

fn speed(distance: Meters, time: Seconds) -> f64 {
    distance.0 / time.0
}

// Now `speed(Seconds(10.0), Meters(100.0))` is a COMPILE ERROR.
// You cannot accidentally mix units — a huge win for numerical code.

// EXTENSION TRAIT: add methods to types you don't own
trait StrExt {
    fn shout(&self) -> String;
}

impl StrExt for str {
    fn shout(&self) -> String {
        format!("{}!!!", self.to_uppercase())
    }
}

// ASSOCIATED TYPES: cleaner when a trait has exactly one sensible type per implementor
trait Container {
    type Item;                       // one type, chosen by the implementor
    fn insert(&mut self, item: Self::Item);
    fn first(&self) -> Option<&Self::Item>;
}

fn main() {
    let d = Meters(100.0);
    let t = Seconds(9.58);
    println!("speed = {:.2} m/s", speed(d, t));
    println!("{}", "hello".shout());
}

// Declaring modules: the compiler looks for either a `garden` directory
// or a `garden.rs` file next to this one.
pub mod garden;              // src/garden.rs  (or src/garden/mod.rs)

// Inline module — good for small ones
mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
        fn seat_at_table() {}        // private: invisible outside `hosting`
    }
}

use crate::front_of_house::hosting;   // import: now you can write `hosting::…`
use self::garden::Vegetables;         // explicit self::
use std::collections::HashMap;        // external crate
use std::fmt::Result as FmtResult;    // rename to avoid collisions
use std::io::{self, Write};           // import `io` AND `io::Write`

// Re-export: make an internal type part of your public API
pub use garden::Vegetables;

fn eat_at_restaurant() {
    hosting::add_to_waitlist();       // via the `use`
    crate::front_of_house::hosting::add_to_waitlist();   // absolute path
}

// Privacy rules:
// • Items are PRIVATE by default, including struct fields.
// • A child module may access its ancestors' private items.
// • A parent may NOT access a child's private items.
// • `pub(crate)` = visible within the current crate only (very useful).

src/
├── lib.rs              # crate root: `pub mod gui;` `pub mod models;`
├── main.rs             # thin binary that calls into the library crate
├── gui/
│   ├── mod.rs          # declares `pub mod buttons;` `pub mod panels;`
│   ├── buttons.rs
│   └── panels.rs
├── models/
│   ├── mod.rs
│   ├── user.rs
│   └── order.rs
└── utils.rs

# NOTE: in Rust 2018+ you may use `gui.rs` + a `gui/` folder instead of `mod.rs`
# (both work; `foo.rs` + `foo/bar.rs` is now the recommended style)

cargo add serde --features derive    # adds a dependency with a feature flag
cargo add tokio --features full
cargo search regex                   # search crates.io from the terminal
cargo tree --duplicates              # find duplicated dependencies
cargo update -p serde                # update one crate only

[dependencies]
serde = { version = "1.0", features = ["derive"] }
reqwest = { version = "0.12", features = ["json"] }
chrono = "0.4"                       # caret requirement: ^0.4 (semver compatible)
uuid = { version = "1", features = ["v4"] }

[dependencies.my_internal_lib]
path = "../my_internal_lib"          # local path dependency

[features]
default = ["json"]
json = ["serde"]
cli = ["clap"]

[workspace]
members = ["core", "cli", "web"]     # multi-crate workspace: one Cargo.lock, shared build

fn main() {
    // Syntax: |params| body    (Type annotations optional — inferred from use)
    let add = |a: i32, b: i32| a + b;
    let square = |x: i32| { x * x };        // braces when you need multiple statements
    let greeting = || println!("hi");       // no params

    println!("{} {}", add(2, 3), square(4));

    // Closures capture variables from their enclosing scope
    let offset = 10;
    let add_offset = |x: i32| x + offset;   // borrows `offset`
    println!("{}", add_offset(5));          // 15

    // move closures TAKE ownership of captured variables
    let name = String::from("Ferris");
    let greet = move || println!("hello, {name}");  // `name` moved into the closure
    greet();
    // println!("{name}");   // ❌ E0382: name was moved into the closure

    // This is essential for threads and async: the closure must outlive the scope
    let data = vec![1, 2, 3];
    let handle = std::thread::spawn(move || {
        println!("thread sees {data:?}");   // owns `data` now
    });
    handle.join().unwrap();
}

fn apply<F: Fn(i32) -> i32>(f: F, x: i32) -> i32 { f(x) }

fn call_twice<F: FnMut()>(mut f: F) { f(); f(); }

fn consume_once<F: FnOnce() -> String>(f: F) -> String { f() }

fn main() {
    println!("{}", apply(|x| x * 2, 21));         // 42

    let mut count = 0;
    call_twice(|| { count += 1; });                // FnMut closure
    println!("count = {count}");                   // 2

    let name = String::from("Ferris");
    let result = consume_once(move || name);       // FnOnce: consumes `name`
    println!("{result}");
}

pub trait Iterator {
    type Item;
    fn next(&mut self) -> Option<Self::Item>;
    // …50+ provided methods come free
}

fn main() {
    let numbers = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

    // ── adapters (lazy) ────────────────────────────────────────────────
    let evens_doubled: Vec<i32> = numbers.iter()
        .filter(|&&n| n % 2 == 0)      // &&n because .iter() yields &i32 and filter passes &&i32
        .map(|n| n * 2)
        .collect();                     // ← consumer: this is when it runs
    println!("{evens_doubled:?}");      // [4, 8, 12, 16, 20]

    // ── enumerate, zip, chain ──────────────────────────────────────────
    for (i, value) in numbers.iter().enumerate() {
        if i > 2 { break; }
        print!("[{i}]={value} ");
    }
    println!();

    let names = vec!["ada", "grace", "alan"];
    let years = vec![1815, 1906, 1912];
    for (name, year) in names.iter().zip(years.iter()) {
        println!("{name} ({year})");
    }

    let chained: Vec<i32> = (1..=3).chain([10, 20]).collect();
    println!("{chained:?}");             // [1, 2, 3, 10, 20]

    // ── fold / reduce: the universal accumulator ───────────────────────
    let sum = numbers.iter().fold(0, |acc, &n| acc + n);
    println!("sum = {sum}");             // 55

    // ── find, any, all, position ───────────────────────────────────────
    let first_big = numbers.iter().find(|&&n| n > 7);
    println!("{first_big:?}");           // Some(8)
    println!("{}", numbers.iter().any(|&n| n == 5));   // true
    println!("{}", numbers.iter().all(|&n| n > 0));    // true
    println!("{:?}", numbers.iter().position(|&n| n == 4)); // Some(3)

    // ── sorting & grouping ─────────────────────────────────────────────
    let mut words = vec!["pear", "apple", "fig"];
    words.sort_by_key(|w| w.len());      // by length
    println!("{words:?}");               // ["fig", "pear", "apple"]

    let (min, max) = numbers.iter().fold((i32::MAX, i32::MIN), |(lo, hi), &n| {
        (lo.min(n), hi.max(n))
    });
    println!("min={min} max={max}");

    // ── infinite iterators + take = finite work ────────────────────────
    let squares: Vec<u64> = (1u64..)
        .map(|n| n * n)
        .take(5)
        .collect();
    println!("{squares:?}");             // [1, 4, 9, 16, 25]

    // ── chunks, windows, step_by ───────────────────────────────────────
    println!("{:?}", numbers.chunks(3).collect::<Vec<_>>());
    println!("{:?}", numbers.windows(3).collect::<Vec<_>>());
    println!("{:?}", numbers.iter().step_by(3).collect::<Vec<_>>());
}

use std::mem;

fn main() {
    // 1. A value on the heap, with a stack pointer to it
    let b = Box::new(5);
    println!("{b}");
    // `b` behaves exactly like the i32 it holds, thanks to Deref
    println!("{}", b + 1);      // 6

    // 2. BREAKING infinite-size recursion
    // This would be infinitely large, so it's a compile error:
    // enum List { Cons(i32, List), Nil }
    // Box gives the type a known, finite size:
    #[derive(Debug)]
    enum List { Cons(i32, Box<List>), Nil }
    use List::{Cons, Nil};
    let list = Cons(1, Box::new(Cons(2, Box::new(Cons(3, Box::new(Nil))))));
    println!("{list:?}");

    // 3. Trait objects: dynamically sized values
    let shape: Box<dyn std::fmt::Display> = Box::new("a boxed string");

    // 4. Large data you want off the stack
    let big = Box::new([0u8; 1_000_000]);

    // A Box is 8 bytes on the stack (just the pointer)
    println!("size of Box: {}", mem::size_of_val(&b));    // 8
    println!("size of List: {}", mem::size_of_val(&list)); // 16
}

use std::rc::Rc;
use std::sync::Arc;
use std::thread;

fn main() {
    // ── Rc: shared ownership on one thread ──────────────────────────────
    let shared = Rc::new(String::from("shared data"));
    let a = Rc::clone(&shared);      // note: Rc::clone, not .clone() — makes the intent visible
    let b = Rc::clone(&shared);
    println!("{} {} {}", shared, a, b);
    println!("refcount = {}", Rc::strong_count(&shared));   // 3

    // ── Arc: the same, but safe to send across threads ─────────────────
    let numbers = Arc::new(vec![1, 2, 3, 4, 5]);
    let mut handles = vec![];
    for i in 0..3 {
        let nums = Arc::clone(&numbers);
        handles.push(thread::spawn(move || {
            let sum: i32 = nums.iter().sum();
            println!("thread {i} sums to {sum}");
        }));
    }
    for h in handles { h.join().unwrap(); }
}

use std::cell::RefCell;
use std::rc::Rc;

fn main() {
    let data = RefCell::new(vec![1, 2, 3]);

    // Runtime borrow rules: same as compile-time, but checked when you call
    {
        let mut borrowed = data.borrow_mut();   // exclusive runtime borrow
        borrowed.push(4);
    }                                           // borrow ends here
    println!("{:?}", data.borrow());            // [1, 2, 3, 4]

    // data.borrow_mut() while borrowed → 💥 panic: already borrowed

    // The classic combination: Rc<RefCell<T>> = shared AND mutable
    let shared_list = Rc::new(RefCell::new(Vec::new()));
    let a = Rc::clone(&shared_list);
    let b = Rc::clone(&shared_list);
    a.borrow_mut().push(10);
    b.borrow_mut().push(20);
    println!("{:?}", shared_list.borrow());     // [10, 20]
}

use std::ops::Deref;
use std::fmt;

// A custom smart pointer
struct MyBox<T>(T);

impl<T> MyBox<T> {
    fn new(x: T) -> MyBox<T> { MyBox(x) }
}

impl<T> Deref for MyBox<T> {
    type Target = T;
    fn deref(&self) -> &T { &self.0 }      // enables `*my_box` and method auto-deref
}

impl<T: fmt::Debug> Drop for MyBox<T> {
    fn drop(&mut self) {
        println!("dropping MyBox with {:?}", self.0);
    }
}

fn hello(name: &str) { println!("Hello, {name}!"); }

fn main() {
    let x = MyBox::new(String::from("Rust"));
    hello(&x);          // auto-deref: &MyBox<String> → &String → &str
                        // (the compiler inserts derefs — zero runtime cost)
}                       // "dropping MyBox with ..." printed HERE, deterministically

use std::thread;
use std::time::Duration;

fn main() {
    let mut handles = vec![];

    for i in 0..4 {
        // `move` transfers ownership of `i` into the thread — required because
        // the thread may outlive the current scope.
        let handle = thread::spawn(move || {
            for step in 0..3 {
                println!("thread {i}: step {step}");
                thread::sleep(Duration::from_millis(10));
            }
            i * 10                    // the closure's return value
        });
        handles.push(handle);
    }

    // Join: wait for each thread and collect its result
    for h in handles {
        let result = h.join().unwrap();
        println!("thread returned {result}");
    }

    // Scoped threads (Rust 1.63+): borrow data safely without `move`,
    // guaranteed to finish before the scope ends.
    let data = vec![1, 2, 3, 4];
    thread::scope(|s| {
        let half = &data[..2];
        s.spawn(|| println!("first half: {half:?}"));
        s.spawn(|| println!("sum: {}", data.iter().sum::<i32>()));
    });
    // `data` is still usable here — the threads were scoped
    println!("{data:?}");
}

use std::sync::mpsc;
use std::thread;
use std::time::Duration;

fn main() {
    let (tx, rx) = mpsc::channel();          // transmitter, receiver

    // Multiple producers: just clone the transmitter
    let tx2 = tx.clone();
    thread::spawn(move || {
        let messages = vec![String::from("hi"), String::from("from")];
        for m in messages {
            tx.send(m).unwrap();
            thread::sleep(Duration::from_millis(20));
        }
    });
    thread::spawn(move || {
        tx2.send(String::from("the thread!")).unwrap();
    });

    // rx.recv() blocks until a message arrives; try_recv() returns Result immediately.
    // When all senders drop, iteration ends cleanly.
    for received in rx {
        println!("got: {received}");
    }
}

use std::sync::{Arc, Mutex};
use std::thread;

fn main() {
    // Arc for shared ownership across threads, Mutex for safe mutation
    let counter = Arc::new(Mutex::new(0));
    let mut handles = vec![];

    for _ in 0..10 {
        let counter = Arc::clone(&counter);
        handles.push(thread::spawn(move || {
            let mut num = counter.lock().unwrap();   // acquire the lock (guard)
            *num += 1;
            // lock released automatically when `num` (the MutexGuard) drops here
        }));
    }

    for h in handles { h.join().unwrap(); }
    println!("result = {}", *counter.lock().unwrap());   // 100
}

use tokio::time::{sleep, Duration};

// `async fn` returns a Future: a lazily-evaluated state machine, NOT a result
async fn fetch_user(id: u32) -> String {
    sleep(Duration::from_millis(100)).await;   // yields control back to the executor
    format!("user-{id}")
}

async fn fetch_all() -> Vec<String> {
    // Run both concurrently and await both results
    let (a, b) = tokio::join!(fetch_user(1), fetch_user(2));
    vec![a, b]
}

// The `#[tokio::main]` macro builds the runtime (executor + I/O driver + timer)
#[tokio::main]
async fn main() {
    let users = fetch_all().await;            // .await drives the future to completion
    println!("{users:?}");

    // Spawn independent tasks that run concurrently
    let mut handles = vec![];
    for i in 0..100 {
        handles.push(tokio::spawn(async move {
            fetch_user(i).await
        }));
    }
    for h in handles {
        println!("{}", h.await.unwrap());
    }
}

use rayon::prelude::*;

fn main() {
    let mut data: Vec<u64> = (0..10_000_000).collect();

    // Just change `.iter()` to `.par_iter()` — that's the whole migration.
    // Rayon splits the work across all CPU cores automatically.
    let sum: u64 = data.par_iter().map(|x| x * x).sum();

    data.par_sort_unstable();     // parallel sort, often 4-8x faster

    println!("{sum}");
}

fn main() {
    let mut num = 5;

    // Creating raw pointers is SAFE. Dereferencing them is not.
    let r1 = &num as *const i32;
    let r2 = &mut num as *mut i32;

    unsafe {
        println!("r1 = {r1:?}, value = {}", *r1);   // deref requires unsafe
        *r2 = 10;                                   // write through a raw pointer
    }
    println!("num = {num}");                        // 10

    // Calling an unsafe function
    unsafe fn dangerous() {
        // …the contract must be documented and upheld by every caller
    }
    unsafe { dangerous(); }

    // Safe abstraction over unsafe internals — the idiomatic pattern.
    // The `unsafe` is contained in ONE small function with a documented invariant.
    fn split_at_mut<T>(slice: &mut [T], mid: usize) -> (&mut [T], &mut [T]) {
        let len = slice.len();
        let ptr = slice.as_mut_ptr();
        assert!(mid <= len);
        unsafe {
            (
                std::slice::from_raw_parts_mut(ptr, mid),
                std::slice::from_raw_parts_mut(ptr.add(mid), len - mid),
            )
        }
    }

    let mut v = vec![1, 2, 3, 4];
    let (a, b) = split_at_mut(&mut v, 2);
    println!("{a:?} {b:?}");                        // [1, 2] [3, 4]
}

// Declare an external C function (linked at build time)
extern "C" {
    fn abs(input: i32) -> i32;
    fn sqrt(input: f64) -> f64;
}

// Make a Rust function callable from C
#[no_mangle]
pub extern "C" fn rust_add(a: i32, b: i32) -> i32 {
    a + b
}

// Layout compatible with C structs
#[repr(C)]
pub struct CPoint {
    pub x: f64,
    pub y: f64,
}

// A callback that C code can invoke
pub type Callback = extern "C" fn(i32) -> i32;

fn main() {
    unsafe {
        println!("abs(-3) = {}", abs(-3));
        println!("sqrt(2) = {:.4}", sqrt(2.0));
    }
}

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

pub fn greeting(name: &str) -> String {
    format!("Hello, {name}!")
}

// Tests live in a module gated behind #[cfg(test)] — compiled ONLY for `cargo test`
#[cfg(test)]
mod tests {
    use super::*;                     // import everything from the parent module

    #[test]
    fn test_add() {
        assert_eq!(add(2, 3), 5);
        assert_ne!(add(2, 2), 5);
    }

    #[test]
    fn greeting_contains_name() {
        let g = greeting("Rust");
        assert!(g.contains("Rust"), "greeting was: {g}");
    }

    #[test]
    #[should_panic(expected = "divided by zero")]
    fn test_panic() {
        let _ = 1 / 0;
    }

    #[test]
    #[ignore]                         // skip unless run with: cargo test -- --ignored
    fn expensive_test() { }

    // Returning Result from a test lets you use `?` — elegant for fallible tests
    #[test]
    fn returns_result() -> Result<(), std::num::ParseIntError> {
        let n: i32 = "42".parse()?;
        assert_eq!(n, 42);
        Ok(())
    }
}

// tests/ holds BLACK-BOX tests: they use your crate as an external user would.
use my_library;                        // the crate name

#[test]
fn full_workflow() {
    assert_eq!(my_library::add(2, 2), 4);
}

/// Adds two numbers.
///
/// # Examples
///
/// ```
/// let result = my_library::add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 { a + b }

//! Crate-level documentation (goes at the top of lib.rs)
//! ```
//! use my_library::add;
//! ```

cargo test                       # run everything (unit + integration + doc)
cargo test test_add              # filter by name
cargo test -- --threads=1        # single-threaded output is easier to read
cargo test -- --nocapture        # show println! output
cargo test --release             # test optimised code too
cargo tarpaulin --out Html       # code coverage report (install: cargo install cargo-tarpaulin)
cargo llvm-cov                   # faster coverage using LLVM instrumentation

[profile.release]
opt-level = 3          # 0-3, or "s"/"z" for size optimisation
lto = "fat"            # link-time optimisation: slower build, faster binary
codegen-units = 1      # maximum optimisation across the whole crate
panic = "abort"        # smaller binary (no unwinding machinery)
strip = true           # remove debug symbols from the final binary
incremental = false    # release builds don't need incremental compilation

[profile.dev]
opt-level = 0          # fast compilation for the inner loop
debug = true           # keep symbols for the debugger

use std::collections::HashMap;

fn main() {
    let text = "the quick brown fox jumps over the lazy dog the fox";

    let counts: HashMap<&str, usize> = text
        .split_whitespace()
        .fold(HashMap::new(), |mut acc, word| {
            *acc.entry(word).or_insert(0) += 1;
            acc
        });

    let mut sorted: Vec<_> = counts.into_iter().collect();
    sorted.sort_by(|a, b| b.1.cmp(&a.1));

    for (word, n) in sorted {
        println!("{word:>6}: {}", "█".repeat(n));
    }
}

error[E0382]: borrow of moved value: `s1`
 --> src/main.rs:5:15
  |
2 |     let s1 = String::from("hello");
  |         -- move occurs because `s1` has type `String`
3 |     let s2 = s1;
  |              -- value moved here
4 |     println!("{s2}");
5 |     println!("{s1}");
  |               ^^^^ value borrowed here after move
  |
  = note: move occurs because `s1` has type `String`, which does not implement the `Copy` trait
help: consider cloning the value if the performance cost is acceptable
  |
3 |     let s2 = s1.clone();
  |                   ++++++

// ─── VARIABLES ────────────────────────────────────────────────────────────
let x = 5;                      // immutable
let mut y = 5;                  // mutable
let z: f64 = 2.5;               // explicit type
const N: u32 = 100;             // compile-time constant
let shadow = "hi"; let shadow = shadow.len();   // shadowing (may change type)

// ─── TYPES ────────────────────────────────────────────────────────────────
i8 i16 i32 i64 i128 isize       // signed integers
u8 u16 u32 u64 u128 usize       // unsigned integers
f32 f64                         // floats
bool char                       // 1 byte / 4 bytes (Unicode scalar)
()                              // unit type (like void)
(i32, f64)                      // tuple
[i32; 4]                        // fixed array
&[i32]                          // slice
Vec<i32>                        // growable list
String  /  &str                 // owned string / string slice
HashMap<K, V>  HashSet<T>       // hash collections
Option<T>  Result<T, E>         // absence / fallibility
Box<T>  Rc<T>  Arc<T>           // smart pointers

// ─── FUNCTIONS ────────────────────────────────────────────────────────────
fn add(a: i32, b: i32) -> i32 { a + b }        // tail expression
fn nothing() { }                               // returns ()
fn never() -> ! { panic!() }                   // diverging
fn generic<T: Trait>(x: &T) -> &T { x }       // generics
|a, b| a + b                                    // closure

// ─── CONTROL FLOW ─────────────────────────────────────────────────────────
if cond { } else if cond2 { } else { }
let v = if cond { 1 } else { 2 };              // if is an expression
let v = loop { break 42; };                    // loop with a value
while cond { }
for i in 0..10 { }                             // exclusive range
for x in &collection { }                       // borrow iteration
'outer: for x in 0..5 { break 'outer; }        // labelled break

// ─── MATCHING ─────────────────────────────────────────────────────────────
match value {
    Pattern => expr,
    1 | 2 => expr,                             // alternation
    10..=20 => expr,                           // range
    x if x > 5 => expr,                        // guard
    _ => expr,                                 // catch-all (required)
}
if let Some(x) = opt { }                       // single-case match
while let Some(x) = iter.next() { }
let Some(x) = opt else { return; };            // let-else

// ─── DATA ─────────────────────────────────────────────────────────────────
struct User { name: String }                    // named fields
struct Point(f64, f64);                         // tuple struct
struct Marker;                                  // unit struct
enum Color { Red, Rgb(u8,u8,u8) }               // data-carrying enum
impl User {
    fn new() -> Self { … }                      // associated fn: User::new()
    fn name(&self) -> &str { &self.name }       // method: u.name()
}

// ─── TRAITS ───────────────────────────────────────────────────────────────
trait Greet { fn hi(&self) -> String; }         // required method
trait Greet { fn hi(&self) -> String { … } }    // default method
impl Greet for User { … }                       // implement
fn f<T: Greet + Clone>(x: &T) { … }            // bounds
fn f(x: &impl Greet) { … }                      // impl Trait
fn f(x: &dyn Greet) { … }                       // dynamic dispatch
Box<dyn Error>                                  // trait object

// ─── ERROR HANDLING ───────────────────────────────────────────────────────
fn f() -> Result<i32, Box<dyn Error>> {
    let n = may_fail()?;                        // propagate
    Ok(n)
}
opt.unwrap_or(0);  opt.expect("why");  opt.map(f);  opt.and_then(f);
res.unwrap_or_else(|e| 0);  res.map_err(f);  res.ok_or("err");

// ─── CONCURRENCY ──────────────────────────────────────────────────────────
thread::spawn(move || { … });                   // OS thread
let (tx, rx) = mpsc::channel();                 // channel
Arc::new(Mutex::new(v))                         // shared mutable state
async fn f() { g().await; }                     // async

// ─── MODULES ──────────────────────────────────────────────────────────────
mod foo;                                        // declares a module
use crate::foo::Bar;                            // import
pub use foo::Bar;                               // re-export
pub(crate) fn helper() { }                      // crate-visible

// ─── ATTRIBUTES ───────────────────────────────────────────────────────────
#[derive(Debug, Clone, PartialEq)]
#[cfg(test)]
#[allow(dead_code)]
#[inline]
#[must_use]
#[repr(C)]
#[tokio::main]