Mastering Rust: A Comprehensive Guide from Basics to Advanced

let s1 = String::from("hello");
let s2 = s1; // Ownership of s1 moves to s2
// println!("{s1}"); // Compile error! s1 is no longer valid
println!("{s2}"); // Works fine

let x = 5;
let y = x; // i32 implements the Copy trait, so x is still valid
println!("x = {x}, y = {y}"); // No problem at all

fn calculate_length(s: &String) -> usize { // s borrows the String
    s.len()
} // s goes out of scope, but since it doesn't own the data, nothing is dropped
 
fn main() {
    let s1 = String::from("hello");
    let len = calculate_length(&s1); // borrow s1
    println!("The length of '{s1}' is {len}."); // s1 is still valid
}

let mut s = String::from("hello");
 
let r1 = &s;     // OK
let r2 = &s;     // OK — multiple immutable references are allowed
// let r3 = &mut s; // Compile error! Cannot create a mutable reference
                     // while immutable references exist
println!("{r1}, {r2}");
 
let r3 = &mut s; // OK — r1 and r2 are no longer in use
println!("{r3}");

// Tell the compiler: the returned reference lives at least as long as the inputs
fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
    if x.len() > y.len() {
        x
    } else {
        y
    }
}
 
fn main() {
    let string1 = String::from("long string is long");
    let result;
    {
        let string2 = String::from("xyz");
        result = longest(string1.as_str(), string2.as_str());
        println!("Longest string: {result}");
    }
    // Using result here would be a compile error, since string2 was dropped
}

enum Message {
    Quit,                       // No data
    Move { x: i32, y: i32 },   // Named fields, like a struct
    Write(String),              // Contains a String
    ChangeColor(i32, i32, i32), // Contains three i32s
}
 
fn process(msg: Message) {
    match msg {
        Message::Quit => println!("Quit"),
        Message::Move { x, y } => println!("Move to ({x}, {y})"),
        Message::Write(text) => println!("Write: {text}"),
        Message::ChangeColor(r, g, b) => println!("Color: ({r}, {g}, {b})"),
    }
}

let some_number: Option<i32> = Some(42);
let no_number: Option<i32> = None;
 
// You can't use Option<i32> directly as i32
// let sum = some_number + 5; // Compile error! Must handle None first
 
match some_number {
    Some(n) => println!("Value is: {n}"),
    None => println!("No value"),
}

use std::fs::File;
use std::io::{self, Read};
 
fn read_username_from_file() -> Result<String, io::Error> {
    let mut username = String::new();
    File::open("username.txt")?.read_to_string(&mut username)?;
    Ok(username)
}

pub trait Summary {
    fn summarize_author(&self) -> String;
 
    // Default implementations can call other trait methods
    fn summarize(&self) -> String {
        format!("(Read more from {}...)", self.summarize_author())
    }
}
 
pub struct Article {
    pub title: String,
    pub author: String,
}
 
impl Summary for Article {
    fn summarize_author(&self) -> String {
        format!("@{}", self.author)
    }
    // summarize uses the default implementation
}

// impl Trait syntax — accepts any type that implements Summary
pub fn notify(item: &impl Summary) {
    println!("Breaking news! {}", item.summarize());
}
 
// Trait bound syntax — more flexible constraint form
pub fn notify_bound<T: Summary>(item: &T) {
    println!("Breaking news! {}", item.summarize());
}
 
// where clause — clearer when constraints get complex
fn some_function<T, U>(t: &T, u: &U) -> i32
where
    T: std::fmt::Display + Clone,
    U: Clone + std::fmt::Debug,
{
    unimplemented!()
}

let x = 5;          // immutable
// x = 6;           // compile error
let mut y = 5;      // mutable
y = 6;              // fine
 
let z = 5;          // shadowing
let z = z + 1;      // creates a new variable, doesn't modify the original
let z = z * 2;      // can even change type
let spaces = "   ";
let spaces = spaces.len(); // changed from &str to usize — shadowing allows this

const MAX_POINTS: u32 = 100_000;

// Integers: i8, i16, i32, i64, i128, u8, u16, u32, u64, u128, isize, usize
let a: i32 = -42;          // signed 32-bit
let b: u8 = 255;           // unsigned 8-bit
let c = 98_222;            // numeric readability separator
let d = 0xff;              // hexadecimal
let e = 0o77;              // octal
let f = 0b1111_0000;       // binary
let g = b'A';              // byte (u8)
 
// Floating-point
let pi: f64 = 3.14159;     // f64 is default, speed similar to f32 on modern CPUs
 
// Boolean
let t: bool = true;
 
// Character — Unicode scalar value
let heart = '❤';
let z = 'ℤ';

// Tuple — fixed length, can have different types
let tup: (i32, f64, bool) = (500, 6.4, true);
let (x, y, z) = tup;       // destructuring
let first = tup.0;         // index access
 
// Array — fixed length, same type
let arr: [i32; 5] = [1, 2, 3, 4, 5];
let first = arr[0];
let repeat = [3; 5];       // [3, 3, 3, 3, 3]

fn add(x: i32, y: i32) -> i32 {
    x + y // the last expression is the return value (no semicolon)
    // x + y; // with a semicolon, this becomes a statement returning (),
              // causing a compile error
}
 
fn print_sum(x: i32, y: i32) {
    println!("Sum: {}", x + y); // no return value, returns ()
}
 
// Statements don't return values; expressions do
let y = {
    let x = 3;
    x + 1 // expression — note the missing semicolon
};

// if is an expression — can be used in assignments
let condition = true;
let number = if condition { 5 } else { 6 };
 
// loop — infinite loop, can return a value with break
let mut counter = 0;
let result = loop {
    counter += 1;
    if counter == 10 {
        break counter * 2; // the loop expression evaluates to 20
    }
};
 
// Loop labels — specify break/continue targets in nested loops
'outer: for i in 0..5 {
    for j in 0..5 {
        if i == 2 && j == 2 {
            break 'outer;
        }
    }
}
 
// while
let mut n = 3;
while n != 0 {
    println!("{n}!");
    n -= 1;
}
 
// for — the most common loop in Rust
let arr = [10, 20, 30, 40, 50];
for element in arr.iter() {
    println!("Value: {element}");
}
for number in (1..4).rev() { // Range: 3, 2, 1
    println!("{number}!");
}

// String memory layout: stores (ptr, len, capacity) on the stack,
// actual data on the heap
let s1 = String::from("hello");
let s2 = s1; // shallow-copies the stack's (ptr, len, capacity), then invalidates s1
// s1 has been moved — can no longer be used
 
// clone — deep copy
let s3 = String::from("world");
let s4 = s3.clone();
println!("{s3}, {s4}"); // both are valid
 
// Function arguments also cause moves
let s = String::from("hello");
takes_ownership(s);
// println!("{s}"); // compile error: s's value has been moved
 
let x = 5;
makes_copy(x);
println!("{x}"); // fine: i32 implements Copy
 
// Return values also transfer ownership
let s1 = gives_ownership(); // return value moves into s1
 
fn takes_ownership(some_string: String) {
    println!("{some_string}");
} // some_string goes out of scope, drop is called
 
fn makes_copy(some_integer: i32) {
    println!("{some_integer}");
}
 
fn gives_ownership() -> String {
    String::from("yours")
}

// Immutable borrows — can have multiple
let s = String::from("hello");
let r1 = &s;
let r2 = &s;
println!("{r1} and {r2}"); // multiple immutable borrows coexist, no problem
 
// Mutable borrows — only one at a time
let mut s = String::from("hello");
let r1 = &mut s;
r1.push_str(", world");
// let r2 = &mut s; // compile error: cannot have two mutable borrows simultaneously
println!("{r1}");
 
// Immutable and mutable cannot coexist
let mut s = String::from("hello");
let r1 = &s;
let r2 = &s;
println!("{r1} and {r2}"); // last use of r1 and r2 is here
let r3 = &mut s; // fine: r1 and r2 are no longer used
println!("{r3}");

let s = String::from("hello world");
 
// String slices
let hello = &s[0..5];   // "hello"
let world = &s[6..11];  // "world"
let whole = &s[..];     // "hello world"
let from_start = &s[..5];  // "hello"
let to_end = &s[6..];     // "world"
 
// A practical function: return the first word
fn first_word(s: &str) -> &str {
    let bytes = s.as_bytes();
    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }
    &s[..]
}

// Regular struct
struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}
 
// Creating an instance
let mut user1 = User {
    active: true,
    username: String::from("alice"),
    email: String::from("alice@example.com"),
    sign_in_count: 1,
};
 
// Struct update syntax — borrow values from another instance
let user2 = User {
    email: String::from("bob@example.com"),
    ..user1 // remaining fields moved from user1 (user1's String fields are no longer usable)
};
 
// Tuple struct — a named tuple
struct Color(i32, i32, i32);
let black = Color(0, 0, 0);
 
// Unit struct — no fields at all
struct AlwaysEqual;
 
// Methods
impl User {
    // &self borrows the instance
    fn summary(&self) -> String {
        format!("{} ({})", self.username, self.email)
    }
 
    // Associated function — doesn't take self, like a "constructor"
    fn new(username: String, email: String) -> User {
        User {
            active: true,
            username,
            email,
            sign_in_count: 0,
        }
    }
}

enum WebEvent {
    PageLoad,
    KeyPress(char),
    Paste(String),
    Click { x: i64, y: i64 },
}
 
fn inspect(event: WebEvent) {
    match event {
        WebEvent::PageLoad => println!("Page loaded"),
        WebEvent::KeyPress(c) => println!("Key pressed: '{c}'"),
        WebEvent::Paste(s) => println!("Pasted: \"{s}\""),
        WebEvent::Click { x, y } => println!("Clicked at: ({x}, {y})"),
    }
}
 
// if let — when you only care about one variant
let config_max = Some(3u8);
if let Some(max) = config_max {
    println!("The maximum is {max}");
}
 
// let else — introduced in Rust 1.65+
fn get_count(item: &Item) -> usize {
    let Item::Count(count) = item else {
        return 0;
    };
    count
}

use std::fs::File;
use std::io::{self, Read};
 
// Result<T, E> definition
// enum Result<T, E> {
//     Ok(T),
//     Err(E),
// }
 
// Basic usage
let f = File::open("hello.txt");
let f = match f {
    Ok(file) => file,
    Err(error) => match error.kind() {
        io::ErrorKind::NotFound => {
            File::create("hello.txt").unwrap_or_else(|error| {
                panic!("Failed to create file: {error:?}");
            })
        }
        other_error => {
            panic!("Failed to open file: {other_error:?}");
        }
    },
};
 
// unwrap and expect — quick handling for prototyping
// let f = File::open("hello.txt").unwrap(); // panics on failure
// let f = File::open("hello.txt").expect("Could not open hello.txt"); // custom message
 
// Chaining with the ? operator
fn read_file_contents(path: &str) -> Result<String, io::Error> {
    let mut contents = String::new();
    File::open(path)?.read_to_string(&mut contents)?;
    Ok(contents)
}
 
// Common Option methods
let some_value: Option<i32> = Some(42);
some_value.unwrap();          // 42 — panics on None
some_value.unwrap_or(0);     // 42 — returns 0 on None
some_value.unwrap_or_default(); // 42 — returns default on None
some_value.expect("must have a value"); // 42 — panics with message on None
some_value.map(|x| x * 2);   // Some(84)
some_value.and_then(|x| Some(x + 1)); // Some(43)
some_value.filter(|&x| x > 40); // Some(42)
some_value.ok_or("no value");   // Ok(42) — converts to Result

// Generic function
fn largest<T: PartialOrd>(list: &[T]) -> &T {
    let mut largest = &list[0];
    for item in &list[1..] {
        if item > largest {
            largest = item;
        }
    }
    largest
}
 
// Generic struct
struct Point<T> {
    x: T,
    y: T,
}
 
// Generics with different type parameters
struct Point2D<T, U> {
    x: T,
    y: U,
}
 
// Implementing methods on generic types
impl<T: std::fmt::Display> Point<T> {
    fn to_string(&self) -> String {
        format!("({}, {})", self.x, self.y)
    }
}
 
// Implementing methods for a concrete type
impl Point<f32> {
    fn distance_from_origin(&self) -> f32 {
        (self.x.powi(2) + self.y.powi(2)).sqrt()
    }
}

use std::fmt::{Display, Debug};
 
// Defining a trait
pub trait Describe {
    fn describe_author(&self) -> String;
 
    fn describe(&self) -> String {
        format!("Created by {}", self.describe_author())
    }
}
 
// Implementing a trait
struct Article {
    author: String,
    title: String,
}
 
impl Describe for Article {
    fn describe_author(&self) -> String {
        self.author.clone()
    }
}
 
// Trait as a parameter
fn print_description(item: &impl Describe) {
    println!("{}", item.describe());
}
 
// Equivalent trait bound syntax
fn print_description_bound<T: Describe>(item: &T) {
    println!("{}", item.describe());
}
 
// Multiple trait bounds
fn print_debug_and_display(item: &(impl Debug + Display)) {
    println!("Debug: {:?}", item);
    println!("Display: {}", item);
}
 
// where clause
fn compare_and_print<T, U>(t: &T, u: &U)
where
    T: Display + PartialOrd,
    U: Display,
{
    println!("t = {t}, u = {u}");
}
 
// Blanket implementation — the standard library example:
// impl<T: Display> ToString for T { ... }
let s = 42.to_string(); // i32 implements Display, so it gets to_string

// Lifetime annotation syntax: 'a is a lifetime parameter
fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
    if x.len() > y.len() { x } else { y }
}
 
// Lifetimes in structs
struct ImportantExcerpt<'a> {
    part: &'a str,
}
 
fn main() {
    let novel = String::from("Once upon a time. There was a temple...");
    let first_sentence = novel.split('.').next().expect("Could not find '.'");
    let excerpt = ImportantExcerpt {
        part: first_sentence,
    };
}
 
// Lifetime elision rules (three rules the compiler uses to infer lifetimes)
// 1. Each reference parameter gets its own lifetime parameter
// 2. If there's exactly one input lifetime, it's assigned to all outputs
// 3. If there are multiple inputs but one is &self or &mut self, self's
//    lifetime is assigned to outputs
 
// The static lifetime 'static — valid for the entire program duration
let s: &'static str = "I am a static string";
 
// Lifetimes combined with generics
fn longest_with_announcement<'a, T>(
    x: &'a str,
    y: &'a str,
    ann: T,
) -> &'a str
where
    T: Display,
{
    println!("Announcement: {ann}");
    if x.len() > y.len() { x } else { y }
}

use std::boxed::Box;
use std::rc::Rc;
use std::sync::Arc;
use std::cell::RefCell;
use std::sync::Mutex;
 
// Box<T> — heap allocation, single owner
let b = Box::new(5);
println!("b = {b}");
 
// Typical use for Box: recursive types
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))))));
 
// Rc<T> — reference counting, multiple owners (single-threaded only)
use std::rc::Rc;
let a = Rc::new(5);
let b = Rc::clone(&a); // increments reference count, no deep copy
let c = Rc::clone(&a);
println!("Reference count: {}", Rc::strong_count(&a)); // 3
 
// RefCell<T> — interior mutability, enforces borrowing rules at runtime
let value = Rc::new(RefCell::new(5));
let a = Rc::clone(&value);
*borrow_mut = 6;
println!("value = {value:?}");
 
// Arc<T> — atomic reference counting, thread-safe multiple ownership
let data = Arc::new(Mutex::new(vec![1, 2, 3]));

use std::thread;
use std::sync::{mpsc, Arc, Mutex};
use std::time::Duration;
 
// Spawning threads
let handle = thread::spawn(|| {
    for i in 1..10 {
        println!("Spawned thread number: {i}");
        thread::sleep(Duration::from_millis(1));
    }
});
 
for i in 1..5 {
    println!("Main thread number: {i}");
    thread::sleep(Duration::from_millis(1));
}
handle.join().unwrap();
 
// Using move closures to capture ownership
let v = vec![1, 2, 3];
let handle = thread::spawn(move || {
    println!("Vector: {v:?}");
});
 
// Message passing (Channels)
let (tx, rx) = mpsc::channel();
thread::spawn(move || {
    let vals = vec![
        String::from("Hello"),
        String::from("from"),
        String::from("the spawned thread"),
    ];
    for val in vals {
        tx.send(val).unwrap();
    }
});
for received in rx {
    println!("Received: {received}");
}
 
// Shared-state concurrency — Mutex + Arc
let counter = Arc::new(Mutex::new(0));
let mut handles = vec![];
 
for _ in 0..10 {
    let counter = Arc::clone(&counter);
    let handle = thread::spawn(move || {
        let mut num = counter.lock().unwrap();
        *num += 1;
    });
    handles.push(handle);
}
for handle in handles {
    handle.join().unwrap();
}
println!("Result: {}", *counter.lock().unwrap()); // 10
 
// Send and Sync traits
// Send — types can transfer ownership across threads (most types auto-implement)
// Sync — types can share references across threads (&T is safe to pass)
// Rc<T> is neither Send nor Sync, so it can't cross thread boundaries
// Arc<T> is both Send + Sync

// Closures — anonymous functions that can capture environment variables
let plus_one = |x: i32| x + 1;
println!("{}", plus_one(5)); // 6
 
// Capturing environment variables
let x = 4;
let equal_to_x = |z| z == x; // immutably borrows x
println!("{}", equal_to_x(4)); // true
 
// move closure — forces taking ownership
let x = vec![1, 2, 3];
let equal_to_x = move |z| z == x; // x's ownership is moved into the closure
 
// Iterators
let v = vec![1, 2, 3, 4, 5];
 
// Lazy evaluation — iterator adapters don't execute immediately
let v2: Vec<i32> = v.iter()
    .map(|x| x + 1)         // each element +1
    .filter(|x| *x > 3)     // filter for values > 3
    .collect();              // consume the iterator, collect results
 
// Common iterator methods
let sum: i32 = v.iter().sum();                     // sum
let has_even = v.iter().any(|&x| x % 2 == 0);      // any even?
let all_positive = v.iter().all(|&x| x > 0);        // all positive?
let first_even = v.iter().find(|&&x| x % 2 == 0);   // find first even
 
// Custom iterator
struct Counter {
    count: u32,
}
 
impl Counter {
    fn new() -> Counter {
        Counter { count: 0 }
    }
}
 
impl Iterator for Counter {
    type Item = u32;
 
    fn next(&mut self) -> Option<Self::Item> {
        if self.count < 5 {
            self.count += 1;
            Some(self.count)
        } else {
            None
        }
    }
}

// Declarative macros — defined with pattern matching
macro_rules! say_hello {
    () => {
        println!("Hello!");
    };
    ($name:expr) => {
        println!("Hello, {}!", $name);
    };
}
 
say_hello!();           // Hello!
say_hello!("Rust");     // Hello, Rust!
 
// Simplified vec! macro implementation
macro_rules! my_vec {
    ($($x:expr),*) => {
        {
            let mut temp_vec = Vec::new();
            $(temp_vec.push($x);)*
            temp_vec
        }
    };
}
 
let v = my_vec![1, 2, 3];

// Module declaration
mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
        fn seat_at_table() {} // private (default)
    }
 
    mod serving {
        fn take_order() {}
        fn serve_order() {}
        fn take_payment() {}
    }
}
 
// Using use to bring paths into scope
use crate::front_of_house::hosting; // absolute path
use self::front_of_house::hosting;  // relative path
 
// Renaming with use as
use std::fmt::Result as FmtResult;
use std::io::Result as IoResult;
 
// Re-exporting with pub use
pub use crate::front_of_house::hosting;
 
// Splitting modules into separate files
// src/lib.rs:
// mod front_of_house; // tells the compiler to look for src/front_of_house.rs

// Iterator zero-cost abstraction example
fn sum_iterator(data: &[i32]) -> i32 {
    data.iter().sum()
}
 
fn sum_manual(data: &[i32]) -> i32 {
    let mut total = 0;
    for &item in data {
        total += item;
    }
    total
}
// After compilation, the machine code for both is nearly identical

use tokio::time::{sleep, Duration};
 
async fn fetch_data(id: u32) -> String {
    sleep(Duration::from_millis(100)).await;
    format!("Data {id}")
}
 
async fn process() {
    // Execute multiple futures concurrently
    let (a, b) = tokio::join!(
        fetch_data(1),
        fetch_data(2),
    );
    println!("Results: {a}, {b}");
}
 
#[tokio::main]
async fn main() {
    process().await;
}

unsafe fn dangerous() {}
 
unsafe {
    dangerous();
}
 
// FFI — calling C functions
extern "C" {
    fn abs(input: i32) -> i32;
}
 
fn main() {
    let x = unsafe { abs(-5) };
    println!("{x}");
}