Rust Programming Notes

These are my notes from the Rust: The Complete Developer's Guide course. You can find the actual codes at my GitHub repo.

Core Concepts: The Building Blocks of Rust

Representing Data with Structs

Structs in Rust are used to create custom data types that group related values together. Unlike classes in object-oriented languages, structs primarily focus on data representation.

A struct is defined using the struct keyword followed by a name and a list of fields enclosed in curly braces:

1
2
3

struct Deck {
    cards: Vec<String>,
}

This code defines a struct named Deck with a single field named cards. The field is of type Vec<String>, which is a vector (a growable array) of strings.

To create an instance of a struct, the struct name is used followed by curly braces containing the field values:

1

let deck: Deck = Deck { cards: vec![] };

In this example:

• let deck: Deck declares a variable named deck of type Deck
• Deck { cards: vec![] } creates a new instance of the Deck struct with an empty vector for the cards field
• vec![] is a macro that creates an empty vector

For debugging purposes, adding the #[derive(Debug)] attribute above a struct definition enables printing the struct with the {:?} or {:#?} format specifiers:

1
2
3
4
5
6
7

#[derive(Debug)]
struct Deck {
    cards: Vec<String>,
}

// Later in code
println!("Here's your deck: {:#?}", deck);

The #[derive(Debug)] attribute instructs the Rust compiler to automatically implement the Debug trait, which provides a standardized way to format the struct for debugging output.

Arrays vs Vectors

Rust provides two primary collection types for storing sequences of values: arrays and vectors.

Arrays have a fixed size that cannot change after creation. They’re defined using square brackets with the type and size specified:

1
2

let suits = ["Hearts", "Spades", "Diamonds"];
let values = ["Ace", "Two", "Three"];

Vectors are dynamically sized and can grow or shrink at runtime. They’re created using the vec! macro or Vec::new() function:

1
2
3

let mut cards = vec![];
// or
let mut cards = Vec::new();

The key differences between arrays and vectors are:

1. Size flexibility: Arrays have a fixed size, while vectors can grow or shrink
2. Performance: Arrays have a slight performance advantage since their size is known at compile time
3. Usage intent: Arrays signal to other developers that the collection’s size won’t change

When choosing between arrays and vectors, it should be considered whether the collection’s size might need to change during program execution.

Mutable vs Immutable Bindings

In Rust, variables (called “bindings”) are immutable by default. This means once a value is assigned to a variable, it cannot be changed. To create a mutable variable, the mut keyword is used:

1
2
3
4
5
6
7

// Immutable binding
let cards = vec![];
// cards.push("card"); // Error! Cannot modify immutable binding

// Mutable binding
let mut cards = vec![];
cards.push("card"); // Works!

This immutability-by-default design helps prevent unexpected changes to data and is a core aspect of Rust’s safety guarantees. When a binding is declared as mutable, it means:

1. The value it points to can be modified
2. The binding itself can be reassigned to point to a different value

1
2

let mut x = 5;
x = 6; // Reassignment works with mutable bindings

When working with vectors or other collections, a mutable binding is needed to add or remove elements:

1
2
3
4
5
6
7

let mut cards = vec![];
for suit in suits {
    for value in values {
        let card = format!("{} of {}", value, suit);
        cards.push(card); // Requires `cards` to be mutable
    }
}

It should always be considered whether a binding truly needs to be mutable. Using immutable bindings where possible helps prevent bugs and makes code easier to reason about.

Implementations and Methods

Structs can have associated functionality through implementation blocks. An implementation block is created using the impl keyword:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

impl Deck {
    fn new() -> Self {
        let suits = ["Hearts", "Spades", "Diamonds"];
        let values = ["Ace", "Two", "Three"];
        let mut cards = vec![];

        for suit in suits {
            for value in values {
                let card = format!("{} of {}", value, suit);
                cards.push(card);
            }
        }
        Deck { cards }
    }
    
    fn shuffle(&mut self) {
        // Implementation of shuffle...
    }
}

There are two types of functions that can be defined within an implementation block:

1. Associated functions: Functions that don’t take self as their first parameter

   • Called using the syntax Deck::new()
   • Similar to “static methods” in other languages
   • Typically used for constructors or utility functions

2. Methods: Functions that take self as their first parameter

   • Called using the syntax deck.shuffle()
   • Operate on a specific instance of the struct
   • First parameter is one of:
     • &self (immutable reference to the instance)
     • &mut self (mutable reference to the instance)
     • self (takes ownership of the instance)

Methods are used when access to or modification of the data within a struct instance is needed:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

impl Deck {
    fn shuffle(&mut self) {
        let mut rng = thread_rng();
        self.cards.shuffle(&mut rng);
    }
    
    fn deal(&mut self, num_cards: usize) -> Vec<String> {
        self.cards.split_off(self.cards.len() - num_cards)
    }
}

The shuffle method takes &mut self because it needs to modify the cards within the deck. The deal method also takes &mut self and returns a vector of strings representing the dealt cards.

Implicit Returns

Rust functions return the value of their last expression if it doesn’t end with a semicolon. This is called an implicit return:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// Explicit return
fn new() -> Self {
    let deck = Deck { cards };
    return deck;
}

// Implicit return (preferred style)
fn new() -> Self {
    Deck { cards }
}

Similarly, in conditional expressions:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

fn is_even(num: i32) -> bool {
    if num % 2 == 0 {
        true // No semicolon here - this value is returned
    } else {
        false // No semicolon here - this value is returned
    }
}

// Or more concisely:
fn is_even(num: i32) -> bool {
    num % 2 == 0 // No semicolon - this expression's value is returned
}

Implicit returns make the code more concise and are the preferred style in Rust. It should be remembered that adding a semicolon turns an expression into a statement, which doesn’t return a value.

Installing External Crates

Rust uses packages called “crates” for code reuse. The standard library is automatically included, but external crates must be explicitly added.

To add an external crate:

1. The cargo add command can be used:

   cargo add rand
   

2. Or Cargo.toml can be manually edited:

   1 2	[dependencies] rand = "0.9.0"

External crates are listed on crates.io, and documentation is often available on docs.rs.

Using Code from Crates

After adding an external crate, its functionality must be brought into scope using the use statement:

1
2
3
4
5
6
7
8

use rand::{seq::SliceRandom, thread_rng};

impl Deck {
    fn shuffle(&mut self) {
        let mut rng = thread_rng();
        self.cards.shuffle(&mut rng);
    }
}

The use statement employs path syntax:

• rand is the crate name
• seq::SliceRandom is a path inside the crate
• Using {} allows importing multiple items from the same crate

When a crate contains multiple modules, navigation through them may be necessary:

1
2
3
4
5
6

// Import individual items
use rand::seq::SliceRandom;
use rand::thread_rng;

// Or use nested paths
use rand::{seq::SliceRandom, thread_rng};

This improves code readability by avoiding repeated references to the same crate.

Ownership and Borrowing: Rust’s Unique Memory System

The Basics of Ownership

Ownership is one of Rust’s most distinctive features. The ownership system manages memory without a garbage collector while ensuring memory safety at compile time.

The core rules of ownership are:

1. Every value has a single owner: At any given time, a value is owned by exactly one variable.
2. When the owner goes out of scope, the value is dropped: Rust automatically frees the memory when the owner variable is no longer valid.
3. When a value is assigned to another variable, ownership is transferred (moved).

This example demonstrates ownership transfer:

1
2
3
4
5
6

fn main() {
    let bank = Bank::new();
    let other_bank = bank;
    
    println!("{:#?}", bank); // Error: use of moved value: 'bank'
}

When bank is assigned to other_bank, the value is moved. After this point, bank no longer owns any value, so attempting to use it results in a compile-time error.

The ownership system prevents multiple variables from having write access to the same data, eliminating entire categories of bugs like use-after-free and double-free errors.

Visualizing Ownership and Moves

Understanding when values are moved is crucial for working with Rust. Here are several examples:

1. Assigning to another variable:

   1 2 3

   let account = Account::new(1, String::from("me")); let other_account = account; // account is now invalid

2. Passing to a function:

   1 2 3 4 5 6 7

   fn print_account(account: Account) { println!("{:#?}", account); } let account = Account::new(1, String::from("me")); print_account(account); // account is now invalid

3. Storing in a collection:

   1 2 3

   let account = Account::new(1, String::from("me")); let list_of_accounts = vec![account]; // account is now invalid

4. Accessing fields after partial moves:

   1 2 3 4 5 6 7

   fn print_holder(holder: String) { println!("{}", holder); } let account = Account::new(1, String::from("me")); print_holder(account.holder); // account.holder is now invalid, but other fields remain

These examples show how ownership is moved in different contexts. Understanding these patterns helps prevent common errors in Rust programming.

Writing Useful Code with Ownership

The ownership system might initially seem restrictive, but Rust provides mechanisms to work within these constraints. One approach is to return values that were passed in:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

fn print_account(account: Account) -> Account {
    println!("{:#?}", account);
    account // Return the account so the caller regains ownership
}

fn main() {
    let mut account = Account::new(1, String::from("me"));
    account = print_account(account); // Regain ownership
    account = print_account(account); // Can use it again
}

While this pattern works, it can become cumbersome for complex functions. This leads to Rust’s borrowing system, which provides a more elegant solution.

Introducing the Borrow System

Borrowing allows referencing a value without taking ownership of it. This is done using references, created with the & operator:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

fn print_account(account: &Account) {
    println!("{:#?}", account);
}

fn main() {
    let account = Account::new(1, String::from("me"));
    let account_ref = &account;
    
    print_account(account_ref);
    println!("{:#?}", account); // Still valid because ownership wasn't transferred
}

References are like pointers in other languages but with safety guarantees. They ensure the referenced data remains valid for the reference’s lifetime and prevent data races.

By default, references are immutable (read-only). The key benefits of references include:

1. The original owner retains ownership
2. Multiple references can access the same data simultaneously
3. The data remains available after the function call

This allows for more flexible and ergonomic code while maintaining Rust’s safety guarantees.

Immutable References

Immutable references (also called “shared references”) allow read-only access to data. Key rules for immutable references:

1. Any number of immutable references to a value can exist simultaneously
2. While immutable references exist, the original owner cannot modify the value
3. References must not outlive the data they refer to

1
2
3
4
5
6
7
8
9

fn main() {
    let account = Account::new(1, String::from("me"));
    let account_ref1 = &account;
    let account_ref2 = &account;
    
    print_account(account_ref1);
    print_account(account_ref2);
    println!("{:#?}", account); // Still valid
}

The ability to have multiple immutable references stems from Rust’s commitment to preventing data races. Since these references are read-only, multiple parts of code can safely access the data simultaneously.

This pattern is particularly useful for:

• Passing large structures to functions without copying them
• Sharing access to data across multiple functions
• Implementing algorithms that need to examine but not modify data

Mutable References

When modification of borrowed data is needed, mutable references can be used:

1
2
3
4
5
6
7
8
9

fn change_account(account: &mut Account) {
    account.balance = 10;
}

fn main() {
    let mut account = Account::new(1, String::from("me"));
    change_account(&mut account);
    println!("{:#?}", account); // Shows modified account
}

Mutable references have stricter rules:

1. Only one mutable reference to a particular piece of data can exist at a time
2. Both mutable and immutable references to the same data cannot exist simultaneously
3. The owner cannot modify or access the data while a mutable reference exists

These restrictions prevent data races at compile time. A data race occurs when:

• Two or more pointers access the same data simultaneously
• At least one of them is writing
• There’s no synchronization

By enforcing these rules, Rust eliminates an entire category of concurrency bugs without runtime overhead.

Copy-able Values

Some simple types in Rust are automatically copied instead of moved when assigned or passed to functions:

1
2
3
4
5
6

fn main() {
    let num = 5;
    let other_num = num; // num is copied, not moved
    
    println!("{} {}", num, other_num); // Both valid
}

Types that implement the Copy trait behave this way. These include:

• All integer types (i32, u64, etc.)
• Boolean (bool)
• Floating point types (f32, f64)
• Characters (char)
• Tuples if all elements are Copy (e.g., (i32, bool))
• Arrays of fixed size if the elements are Copy
• References (&T)

Understanding which types are Copy helps predict when values will be copied rather than moved. This behavior can initially seem inconsistent but becomes intuitive with practice.

Enums Unleashed: Pattern Matching and Options

Defining Enums

Enums (enumerations) in Rust allow defining a type that can be one of several variants. Unlike enums in many other languages, Rust enums can contain data within each variant:

1
2
3
4
5
6

#[derive(Debug)]
enum Media {
    Book { title: String, author: String },
    Movie { title: String, director: String },
    Audiobook { title: String },
}

This enum defines a Media type that can be either a Book, Movie, or Audiobook, each containing different data fields. This makes enums in Rust much more powerful than simple enumerations in most languages.

The #[derive(Debug)] attribute enables printing enum instances for debugging purposes.

Declaring Enum Values

To create an instance of an enum, the variant is specified and the required data is provided:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

let audiobook = Media::Audiobook {
    title: String::from("An Audiobook"),
};

let good_movie = Media::Movie {
    title: String::from("Good Movie"),
    director: String::from("Good Director"),
};

let bad_book = Media::Book {
    title: String::from("Bad Book"),
    author: String::from("Bad Author"),
};

Each variant uses the :: syntax to indicate it’s part of the Media enum. The fields are provided using struct-like syntax within curly braces.

Adding Implementations to Enums

Like structs, enums can have methods through implementation blocks:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

impl Media {
    fn description(&self) -> String {
        if let Media::Book { title, author } = self {
            format!("Book: {} {}", title, author)
        } else if let Media::Movie { title, director } = self {
            format!("Movie: {} {}", title, director)
        } else if let Media::Audiobook { title } = self {
            format!("Audiobook {}", title)
        } else {
            String::from("Media description")
        }
    }
}

This implementation adds a description method to all Media values. Inside the method, pattern matching is used to determine which variant the self value is and extract its fields.

Pattern Matching with Enums

Pattern matching is a powerful feature in Rust that works particularly well with enums. The match statement provides a concise way to handle different enum variants:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

impl Media {
    fn description(&self) -> String {
        match self {
            Media::Book { title, author } => {
                format!("Book: {} {}", title, author)
            }
            Media::Movie { title, director } => {
                format!("Movie: {} {}", title, director)
            }
            Media::Audiobook { title } => {
                format!("Audiobook: {}", title)
            }
            Media::Podcast(id) => {
                format!("Podcast: {}", id)
            }
            Media::Placeholder => {
                format!("Placeholder")
            }
        }
    }
}

The match expression:

1. Takes a value to match against (self in this case)
2. Lists patterns to compare against the value
3. Executes the code associated with the first matching pattern
4. Is exhaustive - all possible values must be covered

Pattern matching can also destructure the data within enum variants, allowing direct access to the fields.

When to Use Structs vs Enums

The choice between structs and enums is based on how data is organized:

• Enums are used when: A fixed set of variants exists where each variant might have different fields but shares the same set of methods. Enums are ideal for representing data that can be one of several distinct types.

• Structs are used when: A single concept with a fixed set of fields exists. Structs are better for representing a single data type with consistent attributes.

A good rule of thumb: If all variants need the same methods with the same signatures, an enum is appropriate. If different variants need different methods, separate structs might be better.

Unlabeled Fields

Enum variants can contain data in different ways:

1. Named fields (like structs):

   1	Book { title: String, author: String }

2. Unnamed fields (tuple-like):

   1	Podcast(u32)

3. No data (unit-like):

   1	Placeholder

Unnamed fields are accessed by position rather than by name:

1
2
3
4
5
6

match media {
    Media::Podcast(episode_number) => {
        format!("Podcast: {}", episode_number)
    }
    // Other cases...
}

Unit-like variants are useful for simple flags or states that don’t need associated data.

The Option Enum

Option is a built-in enum in Rust’s standard library that represents a value that might be present or absent:

1
2
3
4

enum Option<T> {
    Some(T),
    None,
}

Option<T> is generic over type T, meaning it can wrap any type. It’s used instead of null references found in many other languages.

1
2
3
4
5
6
7

fn get_by_index(index: usize) -> Option<&Media> {
    if index < self.items.len() {
        Some(&self.items[index])
    } else {
        None
    }
}

To use an Option, both the Some and None cases must be handled:

1
2
3
4
5
6
7
8

match catalog.get_by_index(0) {
    Some(value) => {
        println!("Item: {:#?}", value);
    }
    None => {
        println!("Nothing at that index");
    }
}

This forces explicit handling of the case where a value might be missing, preventing null pointer exceptions at runtime.

Option From Another Perspective

To understand Option better, a similar enum can be implemented:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

enum MightHaveAValue<'a> {
    ThereIsAValue(&'a Media),
    NoValueAvailable,
}

fn get_by_index(&self, index: usize) -> MightHaveAValue {
    if index < self.items.len() {
        MightHaveAValue::ThereIsAValue(&self.items[index])
    } else {
        MightHaveAValue::NoValueAvailable
    }
}

This custom enum serves the same purpose as Option - representing a value that might not exist. The standard Option enum is preferred in practice, but building a custom one helps understand the concept.

Replacing a Custom Enum with Option

Refactoring to use the standard Option enum is straightforward:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

fn get_by_index(&self, index: usize) -> Option<&Media> {
    if index < self.items.len() {
        Some(&self.items[index])
    } else {
        None
    }
}

// Usage
match catalog.get_by_index(index) {
    Some(value) => {
        println!("Item in pattern match: {:#?}", value);
    }
    None => {
        println!("No value here!!!");
    }
}

Using Option brings several benefits:

1. Standard, widely recognized API
2. Access to many built-in methods for working with optional values
3. Compiler optimizations specific to this common enum

Other Ways of Handling Options

Beyond match statements, Option provides several methods for extracting or working with values:

1. unwrap() - Get the value or panic if None:

   1	let item = catalog.get_by_index(0).unwrap(); // Panics if None

2. expect() - Like unwrap() but with a custom error message:

   1	let item = catalog.get_by_index(0).expect("Expected there to be an item here");

3. unwrap_or() - Get the value or a default if None:

   1	let item = catalog.get_by_index(40).unwrap_or(&placeholder);

These methods should be used carefully:

• unwrap() and expect() are appropriate for prototyping or when certainty about a value’s existence is established
• unwrap_or() is safer for production code as it handles the None case gracefully

For robust error handling, match or if let statements are usually preferred.

Project Architecture: Mastering Modules in Rust

Modules Overview

Modules in Rust organize code into logical units, improving maintainability and readability. They allow:

1. Grouping related code together
2. Controlling the visibility of items (public/private)
3. Creating clear namespaces

There are three main ways to create modules:

1. Inline modules within a file:

   1 2 3 4

   mod content { pub enum Media { /*...*/ } pub struct Catalog { /*...*/ } }

2. File-based modules (one module per file):

   1 2 3 4 5 6

   // content.rs pub enum Media { /*...*/ } pub struct Catalog { /*...*/ } // main.rs mod content;

3. Directory-based modules with submodules:

   src/
   ├── main.rs
   └── content/
       ├── mod.rs
       ├── media.rs
       └── catalog.rs
   

Each approach has different organizational implications and visibility rules.

Rules of Modules

Understanding module visibility rules is essential:

1. Items are private by default - The pub keyword is used to make items visible outside their module
2. Child modules see parent modules - Code in child modules can access items in parent modules
3. Parent modules don’t automatically see child modules - Parent modules need explicit pub declarations to access child items
4. Siblings don’t see each other - Sibling modules need pub declarations to access each other’s items

For directory-based modules:

1. Each directory creates a module named after the directory
2. Each directory must contain a mod.rs file that serves as the module’s root
3. A directory’s mod.rs must explicitly declare submodules with pub mod filename;

This structure creates a module hierarchy that matches the file system.

Refactoring with Multiple Modules

A practical example of refactoring code into modules:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// Before: Everything in main.rs
enum Media { /*...*/ }
impl Media { /*...*/ }
struct Catalog { /*...*/ }
impl Catalog { /*...*/ }

// After refactoring:
// src/main.rs
mod content;
use content::media::Media;
use content::catalog::Catalog;

// src/content/mod.rs
pub mod media;
pub mod catalog;

// src/content/media.rs
#[derive(Debug)]
pub enum Media { /*...*/ }
impl Media { /*...*/ }

// src/content/catalog.rs
use super::media::Media;
#[derive(Debug)]
pub struct Catalog {
    items: Vec<Media>,
}
impl Catalog { /*...*/ }

This refactoring separates concerns and creates a clear module hierarchy.

Key points:

1. mod content; in main.rs tells Rust to look for a module named “content”
2. pub mod media; in content/mod.rs re-exports the media module
3. use super::media::Media; in catalog.rs references a module from a parent directory using super
4. The pub keyword is used strategically to control visibility

The refactored code is more maintainable and better organized, with clear separation between components.

Handling the Unexpected: Errors and Results

Project Overview

In this section, an application for processing log files will be built. The primary focus is on handling errors effectively when working with file operations in Rust.

The application will:

1. Read content from a logs.txt file
2. Extract and filter error lines
3. Write these errors to a new file
4. Handle any potential errors that may occur during these operations

This project serves as an introduction to Rust’s error handling mechanisms, particularly the Result enum.

Reading a File

The first task is to read a file’s contents. In Rust, file operations are handled through the standard library’s fs module.

1
2
3
4
5
6
7

use std::fs;

fn main() {
    let text = fs::read_to_string("logs.txt");
    
    println!("{:#?}", text);
}

When running this code, something interesting appears in the console output - there’s an Ok wrapping the file content. This is the first encounter with Rust’s Result enum, which will be explored in depth.

The Result Enum

The Result enum is a fundamental part of error handling in Rust. Similar to the Option enum (which represents a value that might be present or absent), the Result enum represents an operation that might succeed or fail.

The Result enum has two variants:

1. Ok(T) - Contains a success value of type T
2. Err(E) - Contains an error value of type E

1
2
3
4

enum Result<T, E> {
    Ok(T),
    Err(E),
}

To understand this concept better, a simple divide function can be implemented:

1
2
3
4
5
6
7
8
9

use std::io::Error;

fn divide(a: f64, b: f64) -> Result<f64, Error> {
    if b == 0.0 {
        Err(Error::other("Can't divide by 0"))
    } else {
        Ok(a / b)
    }
}

This function returns a Result with:

• Ok variant containing the division result when successful
• Err variant containing an error when division by zero is attempted

The Result type is used whenever an operation might fail, making errors explicit and ensuring they are handled appropriately.

The Result Enum in Action

To use the divide function and handle potential errors, a match statement can be used to check which variant was received:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

fn main() {
    match divide(5.0, 0.0) {
        Ok(result_of_division) => {
            println!("{}", result_of_division);
        }
        Err(what_went_wrong) => {
            println!("{}", what_went_wrong);
        }
    }
}

The match statement allows explicit handling of both success and failure cases. When calling divide(5.0, 0.0), the function returns an Err variant, and the second arm of the match statement executes.

Types of Errors

In the divide function, Error from the std::io module was used. This is just one of many error types available in Rust.

1
2
3
4
5
6
7
8
9

use std::io::Error;

fn divide(a: f64, b: f64) -> Result<f64, Error> {
    if b == 0.0 {
        Err(Error::other("Can't divide by 0"))
    } else {
        Ok(a / b)
    }
}

The standard library contains various error types for different modules:

• std::io::Error for input/output operations
• std::fmt::Error for formatting operations
• std::num::ParseIntError for integer parsing errors

Different functions across the standard library return these specific error types to provide context about what went wrong.

Empty OK Variants

Sometimes, operations don’t have a meaningful value to return upon success but can still fail. For these cases, Rust uses a special type called the unit type, written as () (empty parentheses).

For example, a simple email validation function can be created:

1
2
3
4
5
6
7

fn validate_email(email: String) -> Result<(), Error> {
    if email.contains("@") {
        Ok(())
    } else {
        Err(Error::other("emails must have an @"))
    }
}

When matching on a Result with an empty Ok variant, Ok(..) can be used to acknowledge the value without binding it:

1
2
3
4
5
6

match validate_email(String::from("asdf@asdf.com")) {
    Ok(..) => println!("email is valid"),
    Err(reason_this_failed_validation) => {
        println!("{}", reason_this_failed_validation)
    }
}

The (..) syntax indicates recognition that there’s a value in the Ok variant, but it doesn’t need to be used.

Using a Result When Reading Files

With an understanding of the Result enum, the file reading example can be revisited and potential errors handled:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

use std::fs;

fn main() {
    match fs::read_to_string("logs.txt") {
        Ok(text_that_was_read) => {
            println!("{}", text_that_was_read.len());
        }
        Err(why_this_failed) => {
            println!("Failed to read file: {}", why_this_failed)
        }
    }
}

This pattern explicitly handles both success and failure cases. If the file exists and is readable, its length will be seen. If not, an error message explaining why the operation failed will be displayed.

Tricky Strings

Before proceeding with the log processing application, understanding how Rust handles strings is necessary. Unlike many other languages, Rust has several string types that serve different purposes.

Three common string types can be examined:

1
2
3
4
5
6
7
8
9

fn string_test(a: String, b: &String, c: &str) {}

fn main() {
    string_test(
        "red".to_string(),
        &String::from("red"),
        String::from("red").as_str(),
    );
}

1. String - An owned, growable string (on heap)
2. &String - A reference to a String
3. &str - A string slice, which is a reference to string data owned by another value

The Stack and Heap

To understand these string types better, understanding how Rust uses memory is necessary:

1. Stack: Fast but limited size memory (2-8MB). Stores values with known, fixed sizes.
2. Heap: Slower but can grow to store large amounts of data.
3. Data segment: Stores literal values written directly into source code.

When a vector or a String is created, Rust uses a common pattern:

• Store metadata (length, capacity, pointer) on the stack
• Store the actual data on the heap

1

let numbers = vec![1, 2, 3, 4, 5];

In this example:

• The stack stores a Vec struct with length (5), capacity (5), and a pointer
• The heap stores the actual numbers [1, 2, 3, 4, 5]

This approach prevents stack overflow when data grows large while maintaining efficient access.

Strings, String Refs, and String Slices

Now the application of these memory concepts to the three string types can be examined:

1. String (e.g., let color = String::from("blue");)

   • Stack: Contains length, capacity, and pointer
   • Heap: Contains the actual text data “blue”

2. &String (e.g., let color_ref = &color;)

   • A reference to the String struct on the stack
   • Points to the metadata, not directly to the text

3. &str (e.g., let color_slice = "blue";)

   • Stack: Contains pointer and length
   • Points directly to text data (either in the data segment for literals or on the heap for slices of owned strings)

A key advantage of &str is efficiency when working with string literals or portions of existing strings. Unlike creating a new String, a string slice doesn’t require new heap allocations.

When to Use Which String

Based on the above distinctions, here’s when to use each string type:

1. String - Used when:

   • Ownership of text data is needed
   • A string that can grow or shrink is needed
   • Strings need to be stored in a collection

2. &String - Rarely used explicitly, as Rust automatically converts &String to &str in most contexts

3. &str - Used when:

   • Ownership is not needed
   • Reference to all or part of an existing string is desired
   • Working with string literals

Finding Error Logs

Now the function to extract error logs from file content can be implemented:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

fn extract_errors(text: &str) -> Vec<String> {
    let split_text = text.split("\n");
    
    let mut results = vec![];
    
    for line in split_text {
        if line.starts_with("ERROR") {
            results.push(line.to_string());
        }
    }
    
    results
}

This function:

1. Takes a string slice (&str) as input
2. Splits it by newline characters
3. Checks each line to see if it starts with “ERROR”
4. Collects matching lines into a vector

In the main function, this can now be used to extract errors:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

fn main() {
    match fs::read_to_string("logs.txt") {
        Ok(text_that_was_read) => {
            let error_logs = extract_errors(text_that_was_read.as_str());
            println!("{:#?}", error_logs)
        }
        Err(why_this_failed) => {
            println!("Failed to read file: {}", why_this_failed)
        }
    }
}

Understanding the Issue

When modifying the code to declare error_logs outside the match statement, a lifetime error is encountered:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

fn main() {
    let mut error_logs = vec![];
    
    match fs::read_to_string("logs.txt") {
        Ok(text_that_was_read) => {
            error_logs = extract_errors(text_that_was_read.as_str());
        }
        Err(why_this_failed) => {
            println!("Failed to read file: {}", why_this_failed)
        }
    }
    
    println!("{:#?}", error_logs);
}

This error occurs because:

1. text_that_was_read is a String that owns its data
2. text_that_was_read.as_str() creates a string slice that borrows from that String
3. The extract_errors function returns a vector of string slices that borrow from text_that_was_read
4. When text_that_was_read goes out of scope at the end of the match arm, those borrowed slices become invalid

Fixing Errors Around String Slices

To fix this issue, the extract_errors function needs to be modified to take ownership of the strings it returns:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

fn extract_errors(text: &str) -> Vec<String> {
    let split_text = text.split("\n");
    
    let mut results = vec![];
    
    for line in split_text {
        if line.starts_with("ERROR") {
            results.push(line.to_string());
        }
    }
    
    results
}

By changing the return type from Vec<&str> to Vec<String> and converting each line to an owned String with to_string(), the returned values don’t depend on the lifetime of the input text.

Writing Data to a File

Now that the error logs have been obtained, the final step is to write them to a file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

fn main() {
    match fs::read_to_string("logs.txt") {
        Ok(text_that_was_read) => {
            let error_logs = extract_errors(text_that_was_read.as_str());
            
            match fs::write("errors.txt", error_logs.join("\n")) {
                Ok(..) => println!("Wrote errors.txt"),
                Err(reason_write_failed) => {
                    println!("Writing of errors.txt failed: {}", reason_write_failed);
                }
            }
        }
        Err(why_this_failed) => {
            println!("Failed to read file: {}", why_this_failed)
        }
    }
}

Here, fs::write is used to write the joined error logs to a file. This function also returns a Result, which is handled with another match statement.

The nested match statements work but make the code harder to read.

Alternatives to Nested Matches

To simplify error handling, methods provided by the Result enum can be used:

1
2
3
4
5

fn main() {
    let text = fs::read_to_string("logs.txt").expect("failed to read logs.txt");
    let error_logs = extract_errors(text.as_str());
    fs::write("errors.txt", error_logs.join("\n")).expect("failed to write errors.txt");
}

The expect method:

1. Unwraps the value from an Ok variant
2. Causes a panic with the provided message if the variant is Err

This approach is more concise but will terminate the program if an error occurs.

The Try Operator

Rust provides an even more elegant solution with the ? operator (try operator):

1
2
3
4
5
6
7
8
9

use std::io::Error;

fn main() -> Result<(), Error> {
    let text = fs::read_to_string("logs.txt")?;
    let error_logs = extract_errors(text.as_str());
    fs::write("errors.txt", error_logs.join("\n"))?;

    Ok(())
}

The ? operator:

1. Unwraps the value from an Ok variant
2. Returns early from the function with the error if the variant is Err

This approach requires the function to return a Result type.

When to Use Each Technique

Each error handling technique has its appropriate use case:

1. Match statements - Used when there is a meaningful way to handle the error in the current function

   1 2 3 4

   match fs::read_to_string("config.txt") { Ok(config) => parse_config(config), Err(_) => use_default_config() }

2. Expect/unwrap - Used for quick prototyping or when an error would indicate a programming mistake

   1	let config = fs::read_to_string("config.txt").expect("Config file must exist");

3. Try operator (?) - Used when errors should be propagated to the calling function

   1 2 3 4

   fn read_config() -> Result<Config, Error> { let text = fs::read_to_string("config.txt")?; Ok(parse_config(text)) }

The recommended approach for production code is to use the ? operator in functions that return Result, allowing errors to bubble up to a point where they can be meaningfully handled.

Iterator Deep Dive: Efficient Data Processing

Project Overview

In this section, iterators, a powerful feature in Rust for processing collections of data, will be explored. Iterators facilitate clean, efficient code when working with sequences of elements.

A small project that performs various operations on vectors of strings will be built, using iterators to:

1. Print elements
2. Shorten strings
3. Convert strings to uppercase
4. Move elements between collections
5. Split strings into characters
6. Find elements with fallbacks

Basics of Iterators

An iterator in Rust is an object that allows traversal through elements in a collection. Iterators are the foundation of many looping constructs in Rust.

Starting with a basic vector and exploring iterators:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

fn main() {
    let colors = vec![
        String::from("red"),
        String::from("green"),
        String::from("blue"),
    ];

    let mut colors_iter = colors.iter();

    println!("{:#?}", colors_iter.next());
    println!("{:#?}", colors_iter.next());
    println!("{:#?}", colors_iter.next());
    println!("{:#?}", colors_iter.next());
}

When executed, this code will output:

Some("red")
Some("green")
Some("blue")
None

An iterator is created with the iter() method. The key things to understand about iterators:

1. Iterators are separate from the collections they iterate over
2. The next() method advances the iterator and returns the next element
3. Elements are wrapped in Some until exhausted, then None is returned
4. Iterators are mutable because they maintain internal state about their position

Behind the scenes, an iterator maintains:

• A reference to the collection
• A position pointer to the current element
• A pointer to the end of the collection

Using For Loops with Iterators

For everyday use, calling next() manually is rare. Instead, for loops are used, which handle iterators automatically:

1
2
3
4
5

fn print_elements(elements: &Vec<String>) {
    for element in elements {
        println!("{}", element);
    }
}

When a for loop is used, Rust:

1. Creates an iterator from the collection
2. Repeatedly calls next() on that iterator
3. Unwraps the Some values automatically
4. Stops the loop when None is encountered

This makes iterating much cleaner and less error-prone.

Iterator Consumers

Beyond for loops, Rust provides higher-level functions for working with iterators. These functions are called “consumers” because they consume the iterator, producing a final result:

1
2
3
4
5
6
7

fn print_elements(elements: &Vec<String>) {
    elements
        .iter()
        .for_each(|element| {
            println!("{}", element);
        });
}

The for_each method is an iterator consumer. It:

1. Takes a closure (anonymous function)
2. Applies that closure to each element
3. Automatically handles calling next() until exhaustion

Important: Iterators in Rust are “lazy”, meaning they don’t do any work until a consumer is called. Creating an iterator with iter() doesn’t start iteration - calling a consumer like for_each() does.

Iterator Adaptors

Iterator adaptors transform elements as they flow through the iterator pipeline. Unlike consumers, adaptors don’t cause iteration to occur - they’re intermediate operations:

1
2
3
4
5
6
7
8

fn print_elements(elements: &Vec<String>) {
    elements
        .iter()
        .map(|element| format!("{} {}", element, element))
        .for_each(|element| {
            println!("{}", element);
        });
}

In this example:

1. iter() creates the iterator
2. map() is an adaptor that transforms each element
3. for_each() is a consumer that causes iteration to happen

If the consumer is removed:

1

elements.iter().map(|element| format!("{} {}", element, element));

Nothing happens! Rust will warn: “iterators are lazy and do nothing unless consumed.”

Vector Slices

When writing functions that take collections, it’s often beneficial to use slices instead of specific collection types:

1
2
3
4
5

// Less flexible - requires a full vector
fn print_elements(elements: &Vec<String>) { ... }

// More flexible - works with full vectors or portions of vectors
fn print_elements(elements: &[String]) { ... }

A slice (&[T]) is a view into a contiguous sequence of elements. Benefits include:

1. More flexible function signatures
2. Works with any contiguous sequence, not just vectors
3. Allows working with portions of collections without copying

For example, with vector slices:

1
2

print_elements(&colors);         // Use the whole vector
print_elements(&colors[1..3]);   // Use just elements 1 and 2

Reminder on Ownership and Borrowing

Before implementing more iterator functions, it’s important to review ownership and borrowing rules:

1. If an argument needs to be stored → Take ownership
2. If an argument needs to be read → Take a reference (&T)
3. If an argument needs to be modified → Take a mutable reference (&mut T)

For a string-shortening function, the strings need to be modified in place:

1
2
3

fn shorten_strings(elements: &mut [String]) {
    // Implementation coming soon
}

Iterators with Mutable References

To modify elements in a collection, an iterator that provides mutable references is needed. This is done with iter_mut():

1
2
3
4
5
6
7

fn shorten_strings(elements: &mut [String]) {
    elements
        .iter_mut()
        .for_each(|element| {
            element.truncate(1);
        });
}

There are three main iterator methods in Rust:

1. iter() - Returns immutable references (&T)
2. iter_mut() - Returns mutable references (&mut T)
3. into_iter() - Takes ownership of elements (behavior varies)

Using iter() in the function above would cause an error because the closure would receive immutable references that it can’t modify.

Collecting Elements from an Iterator

Often transformation of elements and collection into a new collection is desired. The collect() method does this:

1
2
3
4
5
6

fn to_uppercase(elements: &[String]) -> Vec<String> {
    elements
        .iter()
        .map(|element| element.to_uppercase())
        .collect()
}

Here:

1. An iterator is created with iter()
2. Each element is transformed with map()
3. The transformed elements are collected into a new collection with collect()

The collect() method is special because it can create different collection types.

How Collect Works

The collect() method needs to know what type of collection to create. There are three ways to specify this:

1. Return type inference:

1
2
3

fn to_uppercase(elements: &[String]) -> Vec<String> {
    elements.iter().map(|e| e.to_uppercase()).collect()
}

1. Variable type annotation:

1

let uppercase: Vec<String> = elements.iter().map(|e| e.to_uppercase()).collect();

1. Turbofish syntax:

1

elements.iter().map(|e| e.to_uppercase()).collect::<Vec<String>>()

The turbofish syntax is often preferred because it makes the target collection type explicit at the point of collection.

Moving Ownership with into_iter()

When ownership of elements is needed (rather than just borrowing them), into_iter() is used:

1
2
3
4
5
6
7

fn move_elements(vec_a: Vec<String>, vec_b: &mut Vec<String>) {
    vec_a
        .into_iter()
        .for_each(|element| {
            vec_b.push(element);
        });
}

The behavior of into_iter() depends on what it’s called on:

1. On a value (vec_a.into_iter()): Returns owned values
2. On a reference ((&vec_a).into_iter()): Returns immutable references
3. On a mutable reference ((&mut vec_a).into_iter()): Returns mutable references

This function takes ownership of vec_a and moves its elements into vec_b.

Inner Maps

Iterators can be used for complex transformations, including nested operations:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

fn explode(elements: &[String]) -> Vec<Vec<String>> {
    elements
        .iter()
        .map(|element| {
            element
                .chars()
                .map(|c| c.to_string())
                .collect::<Vec<String>>()
        })
        .collect::<Vec<Vec<String>>>()
}

This function:

1. Takes each string in the input vector
2. Converts it to a vector of single-character strings
3. Returns a vector of these character vectors

Notice how iterators are chained: the outer map operates on strings, while the inner map operates on characters.

Reminder on Lifetimes

When working with references in iterators, lifetimes come into play. Consider this function:

1
2
3
4
5
6

fn find_color_or<'a>(elements: &'a [String], search: &str, fallback: &'a str) -> &'a str {
    elements
        .iter()
        .find(|element| element.contains(search))
        .map_or(fallback, |element| element.as_str())
}

The 'a lifetime annotations ensure that:

1. The returned string slice doesn’t outlive the collection it might come from
2. The fallback string lives at least as long as the returned reference

Iterators Wrapup

The final function demonstrates several advanced iterator concepts:

1
2
3
4
5
6
7
8
9

fn find_color_or(elements: &[String], search: &str, fallback: &str) -> String {
    elements
        .iter()
        .find(|element| element.contains(search))
        .map_or_else(
            || String::from(fallback),
            |element| element.to_string()
        )
}