Rust Language Reference for Developers

Ownership, borrowing, lifetimes, traits, and the compiler model

🔗The Ownership Model

Rust enforces memory safety at compile time through three rules: every value has one owner, ownership can be moved or borrowed, and values are dropped when their owner goes out of scope. No garbage collector, no runtime overhead.

 1    // Move: ownership transfers to `b`, `a` is no longer valid
 2    let a = String::from("hello");
 3    let b = a;              // a is MOVED into b
 4    // println!("{}", a);  // COMPILE ERROR: value borrowed after move
 5
 6    // Clone: explicit deep copy, both live independently
 7    let a = String::from("hello");
 8    let b = a.clone();      // b is a new independent String
 9    println!("{} {}", a, b); // both valid
10
11    // Copy types: i32, bool, char, f64, tuples of Copy types
12    let x: i32 = 5;
13    let y = x;              // x is COPIED (not moved), both valid
14    println!("{} {}", x, y);

🔗Borrowing: Shared and Mutable References

References let you use a value without taking ownership. The borrow checker enforces the rule at compile time: you can have many shared references OR one mutable reference — never both at the same time.

 1    // Shared reference (&T): read-only, many allowed simultaneously
 2    let s = String::from("hello");
 3    let r1 = &s;
 4    let r2 = &s;            // fine — multiple shared refs are OK
 5    println!("{} {}", r1, r2);
 6
 7    // Mutable reference (&mut T): exclusive, only one at a time
 8    let mut s = String::from("hello");
 9    let r = &mut s;
10    r.push_str(", world");
11    // let r2 = &mut s;    // COMPILE ERROR: cannot borrow `s` as mutable more than once
12
13    // Cannot mix shared and mutable refs to same data simultaneously
14    let r1 = &s;
15    // let r2 = &mut s;    // COMPILE ERROR: cannot borrow `s` as mutable because it is also borrowed as immutable

The borrow checker works at the scope level, not the line level. In newer Rust (NLL — Non-Lexical Lifetimes), a borrow ends at its last use, not at the end of its scope. This means you can sometimes take a mutable ref after a shared ref as long as the shared ref is no longer used.

🔗Ownership in Functions

 1    // Passing by value: ownership moves into the function
 2    fn take(s: String) {
 3        println!("{}", s);
 4    } // s is dropped here
 5
 6    let s = String::from("hi");
 7    take(s);
 8    // println!("{}", s); // COMPILE ERROR: s was moved
 9
10    // Passing by reference: borrow, caller retains ownership
11    fn borrow(s: &String) {
12        println!("{}", s);
13    } // borrow ends here, s is not dropped
14
15    let s = String::from("hi");
16    borrow(&s);
17    println!("{}", s); // still valid — we only borrowed
18
19    // Returning ownership: function gives back what it owns
20    fn make() -> String {
21        String::from("new string") // returned, not dropped
22    }
23    let s = make(); // s owns the string

🔗The Stack vs the Heap

String vs &str. String is heap-allocated, owned, growable. &str is a borrowed reference to string data (often a string literal in the binary, or a slice of a String). Functions that only read strings should generally take &str — it's more flexible and avoids forcing the caller to allocate.

🔗Scalar Types

🔗Compound Types

 1    // Tuple: fixed-length, can mix types
 2    let t: (i32, f64, bool) = (1, 2.0, true);
 3    println!("{}", t.0); // access by index
 4    let (x, y, z) = t; // destructure
 5
 6    // Array: fixed-length, same type, stack-allocated
 7    let arr: [i32; 5] = [1, 2, 3, 4, 5];
 8    let zeros = [0; 10]; // [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
 9    // arr[5];           // RUNTIME PANIC: index out of bounds (checked)
10
11    // Vec: heap-allocated, growable array
12    let mut v: Vec<i32> = Vec::new();
13    v.push(1);
14    v.push(2);
15    let v2 = vec![1, 2, 3]; // macro shorthand
16
17    // Slice: view into an array or Vec (doesn't own data)
18    let slice: &[i32] = &v[0..2]; // first two elements
19
20    // HashMap
21    use std::collections::HashMap;
22    let mut map = HashMap::new();
23    map.insert("key", 42);
24    let val = map.get("key"); // returns Option<&i32>

🔗Structs

 1    // Named-field struct
 2    struct User {
 3        name: String,
 4        age: u32,
 5        active: bool,
 6    }
 7
 8    let user = User {
 9        name: String::from("Alice"),
10        age: 30,
11        active: true,
12    };
13    println!("{}", user.name);
14
15    // Struct update syntax
16    let user2 = User {
17        name: String::from("Bob"),
18        ..user  // fill remaining fields from `user`
19                // NOTE: moves `user` if non-Copy fields are used
20    };
21
22    // Tuple struct
23    struct Point(f64, f64);
24    let p = Point(1.0, 2.0);
25    println!("{}", p.0);
26
27    // Unit struct (no fields, used as marker type)
28    struct Marker;

🔗impl Blocks: Methods on Structs

 1    struct Rectangle {
 2        width: f64,
 3        height: f64,
 4    }
 5
 6    impl Rectangle {
 7        // Associated function (no `self`): called as Rectangle::new()
 8        fn new(width: f64, height: f64) -> Self {
 9            Self { width, height }
10        }
11
12        // Method: takes `&self` (shared borrow of the instance)
13        fn area(&self) -> f64 {
14            self.width * self.height
15        }
16
17        // Mutable method: takes `&mut self`
18        fn scale(&mut self, factor: f64) {
19            self.width *= factor;
20            self.height *= factor;
21        }
22    }
23
24    let mut r = Rectangle::new(4.0, 5.0);
25    println!("{}", r.area());  // 20.0
26    r.scale(2.0);
27    println!("{}", r.area());  // 80.0

self, &self, &mut self. self consumes the value (rare). &self borrows immutably (most common — for reads). &mut self borrows mutably (for mutations). Pick the least powerful you need.

🔗Traits

Traits define shared behaviour across types. They're similar to interfaces in other languages, but more powerful — they can have default method implementations, and you can implement them on types you didn't define.

 1    // Define a trait
 2    trait Summary {
 3        fn summarize(&self) -> String;
 4
 5        // Default implementation — types can override or use as-is
 6        fn preview(&self) -> String {
 7            format!("{}...", &self.summarize()[..50])
 8        }
 9    }
10
11    // Implement for a struct
12    struct Article { title: String, content: String }
13
14    impl Summary for Article {
15        fn summarize(&self) -> String {
16            format!("{}: {}", self.title, self.content)
17        }
18    }
19
20    // Use trait bound in a function (monomorphized at compile time)
21    fn print_summary<T: Summary>(item: &T) {
22        println!("{}", item.summarize());
23    }
24
25    // Equivalent using `impl Trait` syntax (simpler for single params)
26    fn print_summary(item: &impl Summary) {
27        println!("{}", item.summarize());
28    }
29
30    // Dynamic dispatch with `dyn Trait` (runtime cost, allows mixed types)
31    fn print_any(item: &dyn Summary) {
32        println!("{}", item.summarize());
33    }

🔗Common Standard Traits

// Deriving multiple traits
#[derive(Debug, Clone, PartialEq)]
struct Point { x: f64, y: f64 }

let p1 = Point { x: 1.0, y: 2.0 };
let p2 = p1.clone();
println!("{:?}", p1); // Point { x: 1.0, y: 2.0 }
println!("{}", p1 == p2); // true

// Implementing Display manually
use std::fmt;
impl fmt::Display for Point {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "({}, {})", self.x, self.y)
    }
}
println!("{}", p1); // (1.0, 2.0)

Orphan rule: You can only implement a trait for a type if either the trait or the type is defined in your crate. You cannot implement Display for Vec<T> — neither is yours. This prevents conflicting implementations across crates.

🔗Enums

Rust enums are algebraic data types — each variant can hold different data. Combined with pattern matching, they're the primary tool for modelling states and outcomes.

 1    // Simple enum
 2    enum Direction { North, South, East, West }
 3
 4    // Enum with data in variants
 5    enum Shape {
 6        Circle(f64),              // radius
 7        Rectangle(f64, f64),     // width, height
 8        Point { x: f64, y: f64 }, // named fields
 9    }
10
11    let s = Shape::Circle(3.14);
12
13    // Pattern match to extract data
14    let area = match s {
15        Shape::Circle(r)        => std::f64::consts::PI * r * r,
16        Shape::Rectangle(w, h)  => w * h,
17        Shape::Point { .. }     => 0.0,
18    };

🔗Option

Rust has no null. Instead, optional values use Option<T>. The compiler forces you to handle the None case. No null pointer exceptions.

 1    enum Option<T> {
 2        Some(T),
 3        None,
 4    }
 5
 6    let maybe: Option<i32> = Some(42);
 7    let nothing: Option<i32> = None;
 8
 9    // Pattern match
10    match maybe {
11        Some(n) => println!("got {}", n),
12        None    => println!("nothing"),
13    }
14
15    // Convenient methods
16    maybe.unwrap();              // panics if None — use only when certain
17    maybe.unwrap_or(0);          // default value if None
18    maybe.unwrap_or_else(|| compute()); // lazily computed default
19    maybe.map(|n| n * 2);        // transform if Some, pass through None
20    maybe.and_then(|n| lookup(n)); // chain operations that may fail
21    maybe.is_some();              // bool check
22    maybe.is_none();              // bool check
23
24    // if let: concise pattern match for one case
25    if let Some(n) = maybe {
26        println!("got {}", n);
27    }

🔗Pattern Matching

 1    // match must be exhaustive — compiler enforces all cases are covered
 2    let n = 7;
 3    match n {
 4        1         => println!("one"),
 5        2 | 3     => println!("two or three"),
 6        4..=6     => println!("four to six"),
 7        x if x < 0 => println!("negative: {}", x),
 8        _          => println!("something else"), // catch-all
 9    }
10
11    // Destructure structs in match
12    let p = Point { x: 3.0, y: 4.0 };
13    match p {
14        Point { x: 0.0, y } => println!("on y-axis at {}", y),
15        Point { x, y }      => println!("({}, {})", x, y),
16    }
17
18    // while let: loop while pattern matches
19    let mut stack = vec![1, 2, 3];
20    while let Some(top) = stack.pop() {
21        println!("{}", top);
22    }

🔗Result<T, E>

Operations that can fail return Result<T, E>. The compiler forces you to handle failures — you cannot accidentally ignore an error.

 1    enum Result<T, E> {
 2        Ok(T),
 3        Err(E),
 4    }
 5
 6    // Parsing a string: can succeed (Ok) or fail (Err)
 7    let r: Result<i32, _> = "42".parse();
 8    match r {
 9        Ok(n)  => println!("parsed: {}", n),
10        Err(e) => println!("failed: {}", e),
11    }
12
13    // Convenient Result methods (mirror Option)
14    r.unwrap();              // panic on Err — use in tests or when certain
15    r.unwrap_or(0);          // default on Err
16    r.expect("parse failed"); // panic with message on Err (better than unwrap)
17    r.map(|n| n * 2);        // transform Ok value
18    r.map_err(|e| MyErr(e)); // transform Err value
19    r.and_then(|n| next(n)); // chain fallible operations
20    r.is_ok(); r.is_err();   // bool checks

🔗The ? Operator

The ? operator is shorthand for: if Ok, unwrap and continue; if Err, return the error immediately from the current function. It eliminates boilerplate match chains for error propagation.

 1    use std::fs;
 2    use std::io;
 3
 4    // Without ?: manual propagation
 5    fn read_file_verbose() -> Result<String, io::Error> {
 6        let content = match fs::read_to_string("file.txt") {
 7            Ok(s)  => s,
 8            Err(e) => return Err(e),
 9        };
10        Ok(content)
11    }
12
13    // With ?: concise propagation
14    fn read_file() -> Result<String, io::Error> {
15        let content = fs::read_to_string("file.txt")?; // returns Err if it fails
16        Ok(content)
17    }
18
19    // Chaining with ?
20    fn parse_config() -> Result<Config, MyError> {
21        let raw = fs::read_to_string("config.toml")?;
22        let config: Config = toml::from_str(&raw)?;
23        Ok(config)
24    }

? works on both Result and Option. In a function returning Option<T>, ? returns None early if applied to a None value. In a function returning Result, it returns the Err. The function's return type determines behavior.

🔗Custom Error Types

 1    // Simple custom error with thiserror crate (recommended)
 2    use thiserror::Error;
 3
 4    #[derive(Error, Debug)]
 5    enum AppError {
 6        #[error("IO error: {0}")]
 7        Io(#[from] std::io::Error),
 8
 9        #[error("parse failed: {msg}")]
10        Parse { msg: String },
11
12        #[error("not found: {0}")]
13        NotFound(String),
14    }
15
16    // anyhow crate: for applications where you don't need typed errors
17    use anyhow::Result;
18    fn run() -> Result<()> {   // Result<(), anyhow::Error>
19        let s = fs::read_to_string("file")?; // any error works
20        Ok(())
21    }

thiserror for libraries, anyhow for applications. thiserror gives you typed errors callers can match on. anyhow is ergonomic for binaries where you just want to propagate and display errors. Use Box<dyn Error> if you want no deps but accept the ergonomic cost.

🔗Lifetimes

Lifetimes are the compiler's way of tracking how long references are valid. Most of the time the compiler infers them (lifetime elision). You only write them explicitly when the compiler can't figure it out — usually when a function returns a reference and the compiler can't determine which input it came from.

 1    // The problem: which input does the returned reference point to?
 2    // The compiler needs to know to ensure the output doesn't outlive the input.
 3    fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
 4        if x.len() > y.len() { x } else { y }
 5    }
 6    // 'a means: "the returned reference lives as long as the shorter of x and y"
 7
 8    // Lifetime in a struct: struct holds a reference, must not outlive what it points to
 9    struct Excerpt<'a> {
10        text: &'a str,
11    }
12
13    let novel = String::from("Call me Ishmael...");
14    let first = novel.split('.').next().unwrap();
15    let excerpt = Excerpt { text: first };
16    // `excerpt` cannot outlive `novel` — compiler enforces this

🔗Lifetime Elision Rules

You don't write lifetimes in most function signatures because the compiler applies three elision rules automatically:

 1    // These three signatures are equivalent after elision:
 2    fn first_word(s: &str) -> &str
 3    // is the same as:
 4    fn first_word<'a>(s: &'a str) -> &'a str
 5
 6    // Method on a struct: rule 3 applies
 7    impl Excerpt<'_> {
 8        fn announce(&self, msg: &str) -> &str {
 9            println!("Attention: {}", msg);
10            self.text  // lifetime of return = lifetime of &self (rule 3)
11        }
12    }

🔗The 'static Lifetime

 1    // 'static: lives for the entire program duration
 2    let s: &'static str = "I live forever"; // string literals are 'static
 3
 4    // Common in trait objects and thread-spawning
 5    fn spawn_worker(f: impl Fn() + Send + 'static) {
 6        std::thread::spawn(f);
 7    }
 8    // `'static` here means the closure must not borrow from the current stack frame
 9    // (the thread might outlive the current function call)

Don't reach for lifetimes first. If you find yourself writing complex lifetime annotations, consider whether you could own the data (use String instead of &str, Vec<T> instead of &[T]) or restructure the code. Explicit lifetimes are sometimes unavoidable but often a design smell.

🔗Threads

Rust's ownership system makes data races impossible to compile. The Send and Sync traits mark what's safe to share across thread boundaries — the compiler enforces them automatically.

 1    use std::thread;
 2
 3    // Spawn a thread, move data into it
 4    let data = String::from("hello");
 5    let handle = thread::spawn(move || {
 6        println!("in thread: {}", data); // `move` transfers ownership
 7    });
 8    handle.join().unwrap(); // wait for thread to finish
 9
10    // Spawn many threads and collect results
11    let handles: Vec<_> = (0..10)
12        .map(|i| thread::spawn(move || i * i))
13        .collect();
14
15    let results: Vec<_> = handles.into_iter()
16        .map(|h| h.join().unwrap())
17        .collect();

🔗Sharing State: Arc and Mutex

 1    use std::sync::{Arc, Mutex};
 2    use std::thread;
 3
 4    // Arc = Atomically Reference Counted: shared ownership across threads
 5    // Mutex = Mutual Exclusion: only one thread can access data at a time
 6    let counter = Arc::new(Mutex::new(0));
 7
 8    let handles: Vec<_> = (0..10).map(|_| {
 9        let c = Arc::clone(&counter);
10        thread::spawn(move || {
11            let mut num = c.lock().unwrap(); // lock — blocks until available
12            *num += 1;
13        }) // lock released automatically when `num` goes out of scope
14    }).collect();
15
16    handles.into_iter().for_each(|h| h.join().unwrap());
17    println!("count: {}", *counter.lock().unwrap()); // 10

🔗Channels: Message Passing

 1    use std::sync::mpsc; // multi-producer, single-consumer
 2    use std::thread;
 3
 4    let (tx, rx) = mpsc::channel();
 5
 6    // Sender can be cloned for multiple producers
 7    let tx2 = tx.clone();
 8
 9    thread::spawn(move || {
10        tx.send(String::from("from thread 1")).unwrap();
11    });
12
13    thread::spawn(move || {
14        tx2.send(String::from("from thread 2")).unwrap();
15    });
16
17    // Receive (blocks until a message arrives)
18    for msg in rx {
19        println!("{}", msg);
20    }

🔗Async / Await

 1    // Async functions return a Future — they don't run until polled
 2    // Requires a runtime like tokio or async-std
 3
 4    // Cargo.toml: tokio = { version = "1", features = ["full"] }
 5
 6    use tokio;
 7
 8    #[tokio::main]
 9    async fn main() {
10        let result = fetch_data().await;
11        println!("{:?}", result);
12    }
13
14    async fn fetch_data() -> Result<String, reqwest::Error> {
15        let body = reqwest::get("https://httpbin.org/get")
16            .await?
17            .text()
18            .await?;
19        Ok(body)
20    }
21
22    // Spawn concurrent async tasks
23    let (a, b) = tokio::join!(task_a(), task_b()); // run concurrently, wait for both
24    let handle = tokio::task::spawn(task_c());        // fire and forget (or .await later)

Async ≠ multithreaded by default. async/await is cooperative concurrency on one (or a pool of) thread(s). tokio::task::spawn can run on a thread pool, but a Future alone doesn't create threads. Use threads for CPU-bound work; use async for I/O-bound work.

🔗Cargo: The Build Tool and Package Manager

 1    # Create a new project
 2    cargo new my_project         # binary (has src/main.rs)
 3    cargo new my_lib --lib       # library (has src/lib.rs)
 4
 5    # Build and run
 6    cargo build                  # compile (debug mode, fast compile, slow binary)
 7    cargo build --release        # optimized (slow compile, fast binary)
 8    cargo run                    # build + run
 9    cargo run --release
10    cargo run -- arg1 arg2       # pass args to the binary
11
12    # Check and test
13    cargo check                  # type-check only, no codegen — very fast
14    cargo test                   # run all tests
15    cargo test test_name         # run tests matching a name
16    cargo test -- --nocapture    # show println! output in tests
17
18    # Dependency management
19    cargo add serde              # add crate (requires cargo-edit or Rust 1.62+)
20    cargo add serde --features derive
21    cargo update                 # update Cargo.lock to latest compatible versions
22    cargo outdated               # show outdated deps (requires cargo-outdated)
23
24    # Other
25    cargo fmt                    # format all code with rustfmt
26    cargo clippy                 # lint: catch common mistakes and style issues
27    cargo doc --open             # build and open documentation in browser
28    cargo publish                # publish crate to crates.io

🔗Cargo.toml

 1    [package]
 2    name = "my_project"
 3    version = "0.1.0"
 4    edition = "2021"         # always use 2021
 5
 6    [dependencies]
 7    serde = { version = "1", features = ["derive"] }
 8    serde_json = "1"
 9    tokio = { version = "1", features = ["full"] }
10    reqwest = { version = "0.12", features = ["json"] }
11    thiserror = "1"
12    anyhow = "1"
13
14    [dev-dependencies]           # only for tests and benchmarks
15    mockall = "0.12"
16
17    [features]
18    default = []
19    my-feature = ["some-optional-dep"]
20
21    [[bin]]                      # multiple binaries in one project
22    name = "server"
23    path = "src/bin/server.rs"

🔗Essential Crates

🔗Testing

 1    // Unit tests: in the same file, inside a `#[cfg(test)]` module
 2    #[cfg(test)]
 3    mod tests {
 4        use super::*; // bring parent module into scope
 5
 6        #[test]
 7        fn test_add() {
 8            assert_eq!(add(2, 3), 5);
 9        }
10
11        #[test]
12        #[should_panic(expected = "divide by zero")]
13        fn test_panic() {
14            divide(1, 0);
15        }
16
17        #[test]
18        fn test_result() -> Result<(), String> {
19            let n: i32 = "5".parse().map_err(|e: _| e.to_string())?;
20            assert_eq!(n, 5);
21            Ok(())
22        }
23    }
24
25    // Integration tests: in tests/ directory (separate crate, public API only)
26    // tests/integration_test.rs
27    use my_project;
28
29    #[test]
30    fn it_works() {
31        assert!(my_project::public_fn());
32    }