đŸȘŽ Anil's Garden

Rust

02 Apr 202524 min read

Rust Resources 🩀

Official Rust Resources

3rd Party 🩀 Resources

Libraries

Rust Notes

3. Common Programming Concepts

4. Understanding Ownership

  • Stack-Only Data: Copy: Rust has a special annotation called the Copy trait that we can place on types that are stored on the stack, as integers are. If a type implements the Copy trait, variables that use it do not move, but rather are trivially copied, making them still valid after assignment to another variable.
    • Rust won’t let us annotate a type with Copy if the type, or any of its parts, has implemented the Drop trait. (If the type needs something special to happen when the value goes out of scope and we add the Copy annotation to that type, we’ll get a compile-time error.)
    • More on traits in: Chapter 10
    • To learn about how to add the Copy annotation to your type to implement the trait, see “Derivable Traits” in Appendix C.
  • Rust Docs: Open with rustup doc
    • Rust’s standard library has extensive API documentation, with explanations of how to use various things, as well as example code for accomplishing various tasks. Code examples have a “Run” button on hover that opens the sample in the playground.
    • Your Personal Documentation: Whenever you are working in a crate, cargo doc --open will generate documentation for your project and all its dependencies in their correct version, and open it in your browser. Add the flag --document-private-items to also show items not marked pub.
  • References and Borrowing
    • A reference is like a pointer in that it’s an address we can follow to access the data stored at that address; that data is owned by some other variable. Unlike a pointer, a reference is guaranteed to point to a valid value of a particular type for the life of that reference.
    • Note: The opposite of referencing by using & is dereferencing, which is accomplished with the dereference operator, *.
    • Mutable references have one big restriction: if you have a mutable reference to a value, you can have no other references to that value. This code that attempts to create two mutable references to s will fail.
    • The benefit of having this restriction is that Rust can prevent data races at compile time. A data race is similar to a race condition and happens when these three behaviors occur:
      1. Two or more pointers access the same data at the same time.
      2. At least one of the pointers is being used to write to the data.
      3. There’s no mechanism being used to synchronize access to the data.
    • Allowing for multiple (distinctly scoped) mutable references: we can use curly brackets to create a new scope, allowing for multiple mutable references, just not simultaneous ones
    • reference’s scope starts from where it is introduced and continues through the last time that reference is used - see code example main_mutable_vs_immutable_ref.rs
      • imposed by the compiler: “the compiler can tell that the reference is no longer being used at a point before the end of the scope”
    • We also cannot have a mutable reference while we have an immutable one to the same value.
      • Rationale: Users of an immutable reference don’t expect the value to suddenly change out from under them.
    • Lessons Recap:
      • At any given time, you can have either one mutable reference or any number of immutable references.
      • References must always be valid.
  • struct has fields - filled in in arbitrary order with curly braces and key-value syntax
  • whole struct has to be mutable to mutate a field; can init new struct instance from existing one
  • possible to use the Field Init Shorthand when building struct factories (like “partial” types) to eliminate redundant key: value when using the field name as function parameter name in function signature
  • Struct update syntax to create new instance of same struct (type) from existing: syntax .. specifies that the remaining fields not explicitly set should have the same value as the fields in the given instance
    • using struct update syntax with an instance containing heap-allocated fields without creating new values in the new instance, moves out those heap-allocated fields’ data rendering the old instance unusable as a whole, but we can still use individual fields whose data has not been moved i.e. stack-allocated or copied (to the new instance) data
  • tuple structs: have order, no field names, different types from tuples
    • syntax: struct Color(i32, i32, i32); then later let black = Color(0, 0, 0);
  • Unit-like structs useful to implement a trait on some type without data that you want to store in the type itself
    • syntax: struct AlwaysEqual; then later let subject = AlwaysEqual;
  • Are Rust’s structs classes, and if not why not? from Grok 3
    • No Inherent Methods
    • No Inheritance:
    • No Constructors by Default
    • Encapsulation is Optional
    • Traits, Not Classes
      • “Rust uses traits to define shared behavior, somewhat like interfaces or abstract classes in OOP, but more flexible. A struct can implement multiple traits, providing a way to attach behavior without the baggage of a class hierarchy”
    • A class in a language like C++ or Python is a single entity that combines data, methods, and often inheritance into one package. Rust splits this into:
      • struct for data
      • impl for methods
      • trait for shared behaviour
      • Composition or trait objects for polymorphism.
    • This modularity gives you more control and aligns with Rust’s goals of performance and safety, but it means structs don’t carry the full weight of what “class” implies in OOP.
  • References can be stored in structs using lifetimes
  • 5.3. Method Syntax:
    • start an impl (implementation) block for the struct (type)
    • defined within the context of a struct, enum or trait object
    • first parameter is always self, which represents the instance of the struct the method is being called on
    • &self is actually short for self: &Self
    • & in front of the self shorthand to indicate that this method borrows the Self instance
    • Methods can take ownership of self, borrow self immutably, as we’ve done here, or borrow self mutably, just as they can any other parameter.
    • for methods that mutate (e.g. perform a transformation on) the instance, you can use &mut self
    • methods taking ownership of the instance are rare e.g. transformations where you want to stop the caller from using the original instance after the transformation
      • use cases: destructive operations; chaining with consumption; transfer of ownership e.g. to another thread; more from Grok 3
    • we can choose to give a method the same name as one of the struct’s fields - distinguished by following with parentheses
    • can define getters: “useful because you can make the field private but the method public”
    • Rust doesn’t have an equivalent to the -> operator from C++ - Rust has a feature called automatic referencing and dereferencing.
      • Calling methods is one of the few places in Rust with this behaviour
      • see section [[#wheres-the---operator|Where’s the -> Operator?]], which I’ve directly saved from the docs because I know I’ll get confused about this later 🙃
    • All functions defined within an impl block are called associated functions because they’re associated with the type named after the impl.
      • We can define associated functions that don’t have self as their first parameter (and thus are not methods) because they don’t need an instance of the type to work with.
      • Associated functions that aren’t methods are often used for constructors that will return a new instance of the struct.
        • These are often called new, but new isn’t a special name and isn’t built into the language; e.g. square associated function example for Rectangle struct
  • structs can have multiple impl blocks which can be useful e.g. for generic types and traits or for e.g. separating methods/associated functions which are exported by PyO3 versus not, as (used to be done in a previous version of) in tiktoken

6. Enums and Pattern Matching

Enums: allow you to define a type by enumerating its possible variants

  • How can I create enums with constant values in Rust? - specifically this answer which uses a struct with associated constants and #[non_exhaustive]
    • question this seems like a bit of an abuse of the language though since the object will not be an enum type ??
  • syntax: let four = IpAddrKind::V4; creates an instance of the V4 variant which has type IpAddrKind via :: namespacing
  • can attach data to each variant of the enum directly e.g. V4(u8, u8, u8, u8), inside enum IpAddr {...} - can be arbitrarily complex/complicated e.g. standard library IpAddr enum which has variants like V4(Ipv4Addr), where Ipv4Addr is a struct
  • the name of each enum variant that we define also becomes a function that constructs an instance of the enum
    • allows for the syntax like: Quarter(UsState), in the Coin enum
  • can define variants with different data structures
    • similar to defining different kinds of struct definitions, except the enum doesn’t use the struct keyword and all the variants are grouped together under the enum’s type.
  • Option<T> (enum in the std library) expresses that a value can be either something or nothing (defined by the standard library)
    • Rust has this; Rust does not have a null value
      • “Expressing this concept in terms of the type system means the compiler can check whether you’ve handled all the cases you should be handling”
      • “In languages with null, variables can always be in one of two states: null or not-null.”
      • Null References The Billion Dollar Mistake from Tony Hoare
    • included in prelude (std lib) as well as Some and None hence why you can directly write: Some(5);
    • Option<T> syntax is for generic type and using different (“concrete”) <T> induces Option<T> to be of different type
    • syntax: let absent_number: Option<i32> = None; or let some_number = Some(5);
    • the compiler can’t infer the type that the corresponding Some variant will hold by looking only at a None value
    • Option is useful because Option<T> and T (where T can be any type) are different types, the compiler won’t let us use an Option<T> value as if it were definitely a valid value.
    • to have a value that can possibly be null, you must explicitly opt in by making the type of that value Option<T>. Then, when you use that value, you are required to explicitly handle the case when the value is null.
    • Everywhere that a value has a type that isn’t an Option<T>, you can safely assume that the value isn’t null.
    • Arguments passed to map_or are eagerly evaluated; if you are passing the result of a function call, it is recommended to use map_or_else, which is lazily evaluated.
  • match: used to evaluate which variant of an enum is matched
    • big difference: with if, the condition needs to evaluate to a Boolean value, but here it can be any type
    • syntax: Coin::Penny => 1, with possible pattern values (and code that handles them; arms) separated by commas
    • multi-line code to handle case uses {} and no trailing comma required
    • recall: the name of each enum variant that we define also becomes a function that constructs an instance of the enum hence we’re allows a function-like syntax as in Coin::Quarter(state) => { println!("State quarter from {state:?}!"); 25 } because indeed
    • You’ll see this pattern a lot in Rust code: match against an enum, bind a variable to the data inside, and then execute code based on it. It’s a bit tricky at first, but once you get used to it, you’ll wish you had it in all languages. It’s consistently a user favorite.
    • Matches are exhaustive
    • catch all: other ??
      • have to put the catch-all arm last because the patterns are evaluated in order
      • catch-all without using the value in the catch-all pattern: _
        • special pattern that matches any value and does not bind to that value (Rust won’t warn us about an unused variable)
    • Can use unit () as match value to indicate no code execution
  • if let: concise idiom that combines if and let to succinctly handle values that match one pattern while ignoring the rest
    • syntax: if let takes a pattern and expression separated by an equal sign: if let Some(max) = config_max {...}
      • can then use variant in the body of the if let block in the same way we would use variant in the corresponding match arm
    • can include an else with an if let (like the _ case in the match expression)
  • The let-else syntax takes a pattern on the left side and an expression on the right, very similar to if let, but it does not have an if branch, only an else branch. If the pattern matches, it will bind the value from the pattern in the outer scope. If the pattern does not match, the program will flow into the else arm, which must return from the function.
    • syntax: let Coin::Quarter(state) = coin else { return None; };
      • bit confusing to me as the value from the pattern is bound in the outer scope without a visible assignment to a symbol of this name (in this example, the state variable)question usage examples/patterns
    • refer to section Staying on the “happy path” with let else

7. Managing Growing Projects with Packages, Crates, and Modules

  • Crates: binaries or library
  • A package can contain multiple binary crates and optionally one library crate
  • encapsulating implementation details: other code can call your code via its public interface without having to know how the implementation works - public vs private
  • scope: the nested context in which code is written has a set of names that are defined as “in scope”
  • the module system includes:
    • Packages: A Cargo feature that lets you build, test, and share crates
    • Crates: A tree of modules that produces a library or executable
    • Modules and use: Let you control the organization, scope, and privacy of paths
    • Paths: A way of naming an item, such as a struct, function, or module
  • crate root is a source file that the Rust compiler starts from and makes up the root module of your crate
    • src/main.rs and src/lib.rs are called crate roots
    • the contents of either of these two files form a module named crate at the root of the crate’s module structure, known as the module tree
    • the entire module tree is rooted under the implicit module named crate
    • analogous to a filesystem
  • package is a bundle of one or more crates that provides a set of functionality. A package contains a Cargo.toml file that describes how to build those crates
  • A package can have multiple binary crates by placing files in the src/bin directory: each file will be a separate binary crate
  • Modules let us organize code within a crate for readability and easy reuse. Modules also allow us to control the privacy of items because code within a module is private by default.
  • Modules can be inline: mod front_of_house {...<module contents>...}
  • Modules can be nested: mod front_of_house {... mod {...} ...}
  • A path can take two forms:
    • An absolute path is the full path starting from a crate root; for code from an external crate, the absolute path begins with the crate name, and for code from the current crate, it starts with the literal crate.
    • A relative path starts from the current module and uses self, super, or an identifier in the current module.
  • Both absolute and relative paths are followed by one or more identifiers separated by double colons: ::
  • In Rust, all items (functions, methods, structs, enums, modules, and constants) are private to parent modules by default. If you want to make an item like a function or struct private, you put it in a module.
  • Items in a parent module can’t use the private items inside child modules, but items in child modules can use the items in their ancestor modules.
  • making the module public doesn’t make its contents public The pub keyword on a module only lets code in its ancestor modules refer to it, not access its inner code.
  • see The Rust API Guidelines for considerations around managing changes to your public API to make it easier for people to depend on your crate
  • See section below: Best Practices for Packages with a Binary and a Library
  • super: We can construct relative paths that begin in the parent module, rather than the current module or the crate root, by using super at the start of the path. This is like starting a filesystem path with the .. syntax.
  • Making Structs and Enums Public
    • If we use pub before a struct definition, we make the struct public, but the struct’s fields will still be private. We can make each field public or not on a case-by-case basis
    • In contrast, if we make an enum public, all of its variants are then public. We only need the pub before the enum keyword
  • use and as
    • Adding use and a path in a scope is similar to creating a symbolic link in the filesystem. By adding use crate::front_of_house::hosting in the crate root, hosting is now a valid name in that scope, just as though the hosting module had been defined in the crate root
    • use only creates the shortcut for the particular scope in which the use occurs

8. Common Collections

Vectors

  • vectors cannot be mutated e.g. via the push method whilst a reference exists to them or any of their elements (in the same scope; per the borrowing rules)
    • because they are heap-allocated and the mutation may require a reallocation (e.g. if the memory they currently occupy is insufficient) which would invalidate the (slice or element) reference
  • Iterating Over the Values in a Vector: use reference & (usually I guess) and dereference with * to change (mutate) a mutable reference
  • For more on the implementation details of the Vec<T> type, see # Example: Implementing Vec in “The Rustonomicon”
  • use Enums to Store Multiple Types in vectors
    • still need to be explicit about what types are allowed in a vector so the compiler knows exactly how much memory on the heap will be needed to store each element at compile time
    • using an enum plus a match expression means that Rust will ensure at compile time that every possible case is handled
  • see Struct Vec

Strings

  • strings are implemented as a collection of bytes, plus some methods to provide useful functionality when those bytes are interpreted as text
  • What Is a String? very important - return to reread this section and expand it out herequestion
  • the to_string method is available on any type that implements the Display trait e.g. string literals e.g. let s = "initial contents".to_string();

10. Generic Types, Traits, and Lifetimes

Cargo Notes

Rust for ML

Rust Extended Notes

Where’s the -> Operator?

From Where’s the -> Operator? which compares Rust's method calling syntax to that of C++ and C

In C and C++, two different operators are used for calling methods: you use . if you’re calling a method on the object directly and -> if you’re calling the method on a pointer to the object and need to dereference the pointer first. In other words, if object is a pointer, object->something() is similar to (*object).something().

Rust doesn’t have an equivalent to the -> operator; instead, Rust has a feature called automatic referencing and dereferencing. Calling methods is one of the few places in Rust with this behavior.

Here’s how it works: when you call a method with object.something(), Rust automatically adds in &, &mut, or * so object matches the signature of the method. In other words, the following are the same:

p1.distance(&p2); (&p1).distance(&p2);

The first one looks much cleaner. This automatic referencing behavior works because methods have a clear receiver—the type of self. Given the receiver and name of a method, Rust can figure out definitively whether the method is reading (&self), mutating (&mut self), or consuming (self). The fact that Rust makes borrowing implicit for method receivers is a big part of making ownership ergonomic in practice.

Modules Cheat Sheet

From Modules Cheat Sheet

Before we get to the details of modules and paths, here we provide a quick reference on how modules, paths, the use keyword, and the pub keyword work in the compiler, and how most developers organize their code. We’ll be going through examples of each of these rules throughout this chapter, but this is a great place to refer to as a reminder of how modules work.

  • Start from the crate root: When compiling a crate, the compiler first looks in the crate root file (usually src/lib.rs for a library crate or src/main.rs for a binary crate) for code to compile.
  • Declaring modules: In the crate root file, you can declare new modules; say you declare a “garden” module with mod garden;. The compiler will look for the module’s code in these places:
    • Inline, within curly brackets that replace the semicolon following mod garden
    • In the file src/garden.rs
    • In the file src/garden/mod.rs
  • Declaring submodules: In any file other than the crate root, you can declare submodules. For example, you might declare mod vegetables; in src/garden.rs. The compiler will look for the submodule’s code within the directory named for the parent module in these places:
    • Inline, directly following mod vegetables, within curly brackets instead of the semicolon
    • In the file src/garden/vegetables.rs
    • In the file src/garden/vegetables/mod.rs
  • Paths to code in modules: Once a module is part of your crate, you can refer to code in that module from anywhere else in that same crate, as long as the privacy rules allow, using the path to the code. For example, an Asparagus type in the garden vegetables module would be found at crate::garden::vegetables::Asparagus.
  • Private vs. public: Code within a module is private from its parent modules by default. To make a module public, declare it with pub mod instead of mod. To make items within a public module public as well, use pub before their declarations.
  • The use keyword: Within a scope, the use keyword creates shortcuts to items to reduce repetition of long paths. In any scope that can refer to crate::garden::vegetables::Asparagus, you can create a shortcut with use crate::garden::vegetables::Asparagus; and from then on you only need to write Asparagus to make use of that type in the scope.

Here, we create a binary crate named backyard that illustrates these rules. The crate’s directory, also named backyard, contains these files and directories:

backyard
├── Cargo.lock
├── Cargo.toml
└── src
    ├── garden
    │   └── vegetables.rs
    ├── garden.rs
    └── main.rs

The crate root file in this case is src/main.rs, and it contains:

Filename: src/main.rs

use crate::garden::vegetables::Asparagus;
 
pub mod garden;
 
fn main() {
    let plant = Asparagus {};
    println!("I'm growing {plant:?}!");
}

The pub mod garden; line tells the compiler to include the code it finds in src/garden.rs, which is:

Filename: src/garden.rs

pub mod vegetables;

Here, pub mod vegetables; means the code in src/garden/vegetables.rs is included too. That code is:

#[derive(Debug)] 
pub struct Asparagus {}

Best Practices for Packages with a Binary and a Library

From Best Practices for Packages with a Binary and a Library

We mentioned that a package can contain both a src/main.rs binary crate root as well as a src/lib.rs library crate root, and both crates will have the package name by default. Typically, packages with this pattern of containing both a library and a binary crate will have just enough code in the binary crate to start an executable that calls code within the library crate. This lets other projects benefit from most of the functionality that the package provides because the library crate’s code can be shared.

The module tree should be defined in src/lib.rs. Then, any public items can be used in the binary crate by starting paths with the name of the package. The binary crate becomes a user of the library crate just like a completely external crate would use the library crate: it can only use the public API. This helps you design a good API; not only are you the author, you’re also a client!

In Chapter 12, we’ll demonstrate this organizational practice with a command-line program that will contain both a binary crate and a library crate.

Listing 7-12: A use statement only applies in the scope it’s in

From Bringing Paths into Scope with the use Keyword

This example is interesting because it also shows that the module and then function scope does not look up into a parent scope.question I’m not sure if the term parent scope is valid or correct here.

I guess this is to do with module boundaries? (maybe the function scope captures its enclosing namespace/scope and allows use of variables from it)question

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}
 
use crate::front_of_house::hosting;
 
mod customer {
    pub fn eat_at_restaurant() {
        hosting::add_to_waitlist(); // <- error[E0433]: failed to resolve: use of undeclared crate or module `hosting`
    }
}

Articles

Graph View

Backlinks