Rust

Rust programming language

Start #

Install #

For Windows go to Rust install page and download the installer. For Unix systems install by downloading the rustup utility:

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

This will install rust in $HOME/.cargo/bin or %USERPROFILE%\.cargo\bin.

# Uninstall Rust
rustup self uninstall

# Update Rust
rustup update

# Validate installation
rustc --version
cargo --version
rustdoc --version

Toolchain #

The installation tool rustup installs itself and three core tools: rustc, rustdoc and cargo. Rust is designed to be built and executed using cargo (it wraps the other two).

rustc #

The compiler, it takes .rs files and produces native executables.

1
fn main(){
2
  println! ("Hello World");
3
}

rustc main.rs
./main

rustdoc #

The HTML documentation generator from doc comments (/// for items and //! for modules/crates) into ./doc/ directory.

rustdoc src/lib.rs

1
/// Adds two numbers and returns the result.
2
///
3
/// Returns `a + b` as an `i32`.
4
pub fn add(a: i32, b: i32) -> i32 {
5
  a + b
6
}

rustdoc src/lib.rs

cargo #

Build system and package manager. Used to create projects, resolve dependencies, compile and execute Rust.

new #

Create a new cargo project.

cargo new my_project   # To create a binary project (default)
cargo new my_lib --lib # To create a library project

1
my_project/
2
├── Cargo.toml      # Manifest: name, version, dependencies
3
├── cargo.lock      # Locked dependency versions for build
4
├── src/
5
│   └── main.rs     # Entry point (lib.rs for libraries)
6
└── target/         # Build artifacts (generated on build)

check #

Check if the project code will compile.

cargo check

build #

Compile a project with all its dependencies. (invokes rustc with flags)

cargo build                # Debug build  → target/debug/
cargo build --release      # Optimized    → target/release/

Resolves Cargo.toml crates and updates the Cargo.lock file, then invokes rustc with a set of flags placing the output in target/<profile>.

run #

Build and then execute the resulting binary (invokes rustc with flags and executes).

cargo run            # Build + run (default dev build profile)

cargo run --release        # Build + run (release profile)
cargo test                 # Build + run with test profile (runs all tests)
cargo bench                # Build + run with bench profile (runs all benchmarks)

doc #

Create the HTML documentation (invokes rustdoc).

cargo doc --open           # Build docs and open in browser
cargo doc --no-deps        # Only generate your crate docs, skip dependencies

crates #

Dependencies are defined in Cargo.toml and fetched from crates.io.

cargo install dependency_name        # Install crate globally into ~/.cargo/bin
cargo install --list                 # Display globally installed crates
cargo uninstall dependency_name      # Uninstall crate globally
cargo add dependency_name            # Fetch and add latest version to project
cargo update -p dependency_name      # Update crate to latest compatible ver
cargo remove dependency_name         # Remove crate from project

cargo update                                 # Update all dependencies within semver constraints
cargo clean                                  # Remove all build artifacts and dependency builds
cargo add dependency_name@1.0                # Add specific crate version
cargo add dependency_name --features derive  # Add with feature flags
cargo add --dev dependency_name              # Add crate as a dev dependency
cargo add --build dependency_name
cargo tree                                   # Full dependency tree with versions
cargo tree -i dependency_name                # Reverse: who pulls in dependency_name?
cargo tree --duplicates                      # Find multiple versions of the same crate
cargo search dependency_name                 # Search for specific crate
cargo outdated                               # Check for outdated crates (requires cargo-outdated)
cargo audit                                  # Audit crates against CVEs (requires cargo-audit)

Cargo.toml #

The manifest declares package metadata, dependencies, targets, features and build configuration.

Metadata #

The mimimum required fields are name, version and edition:

1
[package]
2
name = "my_project"
3
version = "0.1.0"
4
edition = "2024"

1
[package]
2
name         = "my_project"                   # crates.io name (required, must be unique)
3
version      = "0.1.0"                        # semver (required)
4
edition      = "2024"                         # Rust edition: 2015, 2018, 2021, 2024
5
authors      = ["Name <me@example.com>"]      # Author name and email
6
description  = "A short blurb"                # Required for publishing to crates.io
7
license      = "MIT"                          # SPDX expression
8
repository   = "https://github.com/user/repo" # Git repository
9
readme       = "README.md"                    # Readme file
10
keywords     = ["cli", "parser"]              # Max 5, for crates.io search
11
categories   = ["command-line-utilities"]     # creates.io package category
12
rust-version = "1.75"                         # Minimum Supported Rust Version (MSRV)

Dependencies #

Dependencies must have a context and a semver requirement. They can be fetched from crates.io, a git repo or a local path. They can have specific feature flags enabled.

Context #

1. [dependencies] is what src/ imports. Ships in the final binary or library. e.g. serde, tokio, clap, anyhow.
2. [dev-dependencies] is what tests/, benches/, examples/, and #[cfg(test)] blocks use. Stripped from the published crate. e.g. criterion, proptest, mockall, assert_cmd.
3. [build-dependencies] is what build.rs uses to do code generation, native compilation, or linker setup before your crate is built. Never touched by src/. e.g. cc, bindgen, prost-build.

1
[dependencies]            # Used by src and release artifacts.
2
dependency_name = "1.0"
3
[dev-dependencies]        # Used only by src for test, bench and example artifacts.
4
dependency_name = "1.0"
5
[build-dependencies]      # Not used by artifacts, used by buils.rs at compile time.
6
dependency_name = "1.0"

Semver #

All dependencies require a semver requirement string. Cargo updates dependencies only within the range specified by the semver string, by default jumps between major versions 1.x -> 2.x have to be added explicitly with cargo add.

1
# Plain semver string are implicitly caret-prefixed
2
dep_name = "0"                    # >=0.0.0, <1.0.0
3
dep_name = "1"                    # >=1.0.0, <2.0.0
4
dep_name = "~1"                   # >=1.0.0, <2.0.0
5
dep_name = "1.*"                  # >=1.0.0, <2.0.0
6
dep_name = "1.2"                  # >=1.2.0, <2.0.0
7
dep_name = "1.2.3"                # >=1.2.3, <2.0.0
8
# For 0.x minor instead of major bumb is breaking
9
dep_name = "0.0"                  # >=0.0.0, <0.1.0
10
dep_name = "0.5"                  # >=0.5.0, <0.6.0
11
dep_name = "0.5.3"                # >=0.5.3, <0.6.0
12
dep_name = "~1.2"                 # >=1.2.0, <1.3.0
13
dep_name = "1.2.*"                # >=1.2.0, <1.3.0
14
# For 0.0.x patch instead of minor bumb is breaking
15
dep_name = "0.0.0"                # >=0.0.0, <0.0.1
16
dep_name = "0.0.5"                # >=0.0.5, <0.0.6
17
dep_name = "~1.2.3"               # >=1.2.3, <1.2.4
18
# Wildcards are best avoided
19
dep_name = "*"                    # Any version - blocked by crates.io
20
# Comparisons are more loose
21
dep_name = ">=1.2.3"              # At least 1.2.3, no upper bound
22
dep_name = ">1.2.3"               # Greater than 1.2.3, no upper bound
23
dep_name = "<1.2.3"               # Less than 1.2.3, no lower bound
24
dep_name = "<=1.2.3"              # At most 1.2.3, no lower bound
25
dep_name = "=1.2.3"               # Exactly 1.2.3, disables updates
26
dep_name = ">=1.2, <1.5"          # 1.2.0 to 1.4.x
27
dep_name = ">1.0, <=1.4.5"        # 0.x.x to 1.4.5
28
# Pre-releases are outside the normal range, this means that "<1"
29
# does not include 0.0.1-beta even though technically it is lower
30
dep_name = "1.0.0-beta.2"         # Opt into 1.0.0-beta line
31
dep_name = ">=1.0.0-alpha"        # Opt into 1.0.0 pre-releases and stable forward
32
# Inline table explicit form
33
# This notation is used to add features, optional, path, git and other options
34
dep_name = { version = "1", features = ["full"], optional=true }

Source #

We can specify the source from which we fetch the crates.

1
[dependencies]
2
dep_name = "1"                                                                        # Fetched from crates.io (default)
3
dep_name = { version = "1", path = "../my_utils"}                                     # Fetched from local path
4
dep_name = { version = "1", git = "https://github.com/usr/repo", branch = "main"}     # Fetched from git repo branch
5
dep_name = { version = "1", git = "https://github.com/usr/repo", rev = "abc123"}      # Fetched from git repo commit
6
dep_name = { version = "1", optional = true}                                          # Fetched async only when enabled by a feature

Feature #

Feature are opt-in compile flags that toggle extra code paths or pull optional dependencies.

1
[dependencies]
2
json_dependency = { version = "1", optional = true }
3
async_dependency = { version = "1", optional = true }
4
[features]
5
default = ["json"]                 # Always enabled (unless --no-default-features is set)
6
json = ["dep:json_dependency"]     # If json is enabled it pulls json_dependency
7
async = ["dep:async_dependency"]   # If async is enabled it pulls async_dependency
8
full = ["json, async"]             # If full is enabled it enables json and async

cargo build --no-default-features
cargo build --features async
cargo build --features json
cargo build --features full
cargo build --all-features

Profile #

You can override one of the compiler build profiles or create a custom one. This is mainly used to fine tune the release artifacts build process.

1
[profile.release]
2
opt-level = 3      # 0 to 3 levels of optimization
3
lto = "fat"        # Link-time optimizations - off, thin, fat
4
codegen-units = 1  # Lower equals better optimizations and slower compile
5
strip = "symbols"  # Strip debug symbols
6
panic = "abort"    # Smaller binary with no unwinding

Target #

The target is auto-detected by cargo but you can declare it explicitly. Note the double brackets since toml will treat it as an array of tables (a crate can produce multiple artifacts).

1
[[bin]]
2
name = "cli"              # Build as cli artifact from cli.rs
3
path = "src/bin/cli.rs"
4
[[example]]               # Build demo from examples/demo.rs
5
name = "demo"
6
[[bench]]                 # Build bench from benches/perf.rs
7
name = "perf"
8
harness = false           # Also disable, nightly built-in bench harness

Workspace #

Some projects contain multiple crates, in this case the root cargo.toml can act as a workspace root file so that all members share a single cargo.lock file and target/ directory. This improves build speeds and the project structure.

1
[workspace]
2
members  = ["app", "core", "utils"]
3
resolver = "2"                                       # Default in edition 2021+
4
[workspace.dependencies]                             # Shared dependencies, defined once
5
serde = "1.0"
6
tokio = { version = "1.0", features = ["full"] }

Then each member crate just inherits:

1
[dependencies]
2
serde = { workspace = true, features = ["derive"] }
3
tokio = { workspace = true }

Fundamentals #

Variables #

Variables are named storage locations that map a symbolic name to a value in memory, the name is replaced with the memory location at compile time. Declared with let, immutable by default; opt into mutability with mut.

1
fn main(){
2
  let x = 2;
3
  println! ("x = {}", x);
4
  let mut y = 2;
5
  y = 3;
6
  println! ("y = {}", y);
7
}

Shadowing #

Rebinding a variable name with a new let shadows the previous binding. Unlike mut, shadowing creates a fresh binding and therefore can change the type.

1
rustfn main() {
2
    let x = "5";                         // &str
3
    let x = x.parse::<i32>().unwrap();   // Shadowing the string into i32
4
    let x = x + 1;                       // i32, value = 6
5
    println!("x = {}", x);
6
}

Constants #

Use const to declare a compile-time constant. Constants must be annotated, their values must be a constant expression and they conventionally use SCREAMING_SNAKE_CASE. They are inlined when used, meaning they don’t necessarily have a fixed memory address.

1
rustconst MAX_USERS: u32 = 100_000;

Use static to declare a value with a fixed memory address. They are usually used to define the global state of the program, creating a mutable static requires an unsafe memory access point.

1
ruststatic APP_NAME: &str = "my-app";

Data Types #

Rust is statically typed, data types must be known at compile time. The type can be inferred or explicitly annotated with a colon. Variables can be declared without a value as long as they are annotated (however they must be initialized before being read).

1
fn main() {
2
  let _int: i32 = 42;
3
  println! ("Int = {}", _int);
4
  let _float: f64 = 3.141;
5
  let _boolean: bool = true;
6
  let _character: char = 'R';
7
  let _tuple: (i32, f64, char, bool) = (42, 3.141, 'R', true);
8
  let _unit_tuple: () = ();
9
  let _array: [i32; 5] = [1, 2, 3, 4, 5];
10
}

Data types can be broadly subdivided into scalar and compound data types.

Integers #

Signed go from $-(2^{n-1})$ to $2^{n-1}-1$. Unsigned go from $0$ to $2^n-1$. Signed are stored using two’s complement representation.

The primary use for isize/usize is indexing collections. Literals accept _ as a visual separator and type suffixes: Hex as 0xff, octal as 0o77, binary as 0b11110000 or byte as b'A' (u8 only). Dev and test artifacts include an overflow panic check, however release artifacts wrap overflows via two’s complement.

Overflow #

In debug (dev, test) normal arithmetic operators + - * / will panic when overflown but silently wrap in release (releease, bench). If you expect overflow to happen you can explicitly handle it by calling an overflow method and the intended arithmetic operator (_add, _sub, _mul, _div, _neg, _rem, _pow, _shl, _shr, etc.).

1
fn main() {
2
    let max_u8 = u8::MAX;
3
    let wrapped = max_u8.wrapping_add(1);
4
    println!("Wrapped: {}", wrapped);  // Outputs Wrapped: 0
5
}

Scalar #

Compound #

Casting #

Rust never coerces between types implicitly, type casting is usually done explicitly with as. This defaults to truncating or wrapping on narrowing conversions (e.g i32 -> i8).

1
fn main() {
2
    let a: i32 = 5;
3
    let b: f64 = 2.5;
4
    let sum = a as f64 + b;    // 7.5
5
    println!("{}", sum);
6
}

For safe, fallible conversions use TryFrom and TryInto, for lossless conversions use From and Into.

Comments #

Single-line comments use double forward slash while multi-line comments use a comment block:

1
fn main() {
2
  // This is a single-line comment
3
  /* This is a multi-line
4
     comment
5
  */
6
}

Functions #

Functions organize code into reusable units. main() is the entry point of every Rust program. Declared with fn, followed by name, parameters with explicit types, optional return type, and a body. The convention is to use snake_case for the function name and parameters.

1
fn function_name(arg1:type, arg2:type,...) -> ReturnType{
2
  // Body1
3
}

Statement, Expression #

A function’s body consists of statements and or expressions. Statements perform an action and return a unit touple (meaning no value), they end with a ;. Expressions evaluate to a value they return, they have no trailing ;.

1
fn main() {
2
    let x = 5;            // statement does not return a value (simply binds to 5)
3
    let y = { x + 1 };    // the expression (x+1) does evaluates to a value (6)
4
    println!("{}", y);
5
}

Return Single #

You can annotate a function’s return type with -> and return a value explicitly with return or implicitly by ending the function’s body with an expression.

1
fn sum(x: i16, y: i16) -> i16 {
2
    x + y // no `;` so it implicitly returns this expression's value
3
}
4

5
fn abs(x: i32) -> i32 {
6
    if x < 0 { return -x; } // early explicit return
7
    x
8
}
9

10
fn main() {
11
    println!("{}", sum(2, 3));   // 5
12
    println!("{}", abs(-7));     // 7
13
}

Return Multiple #

To return multiple values at the same time we can use a tuple and then destructure it at the call site.

1
fn min_max(a: i32, b: i32) -> (i32, i32) {
2
    if a < b { (a, b) } else { (b, a) }
3
}
4

5
fn main() {
6
    let (lo, hi) = min_max(7, 3);
7
    println!("lo={}, hi={}", lo, hi);   // lo=3, hi=7
8
}

Control Flow #

Control flow tools allow us to execute code based on certain conditions or execute repeating code.

If - Else #

We use if to conditionally execute code based on an explicit boolean condition (Rust does not coerce integers, options or similar into truthy-falsy).

For mutually exclusive blocks we can use if - else expressions and for multiple non-overlapping conditions we can use if - else if expressions. if expression branches that implicitly return a value of the same data type can be assigned into a variable.

1
fn main() {
2
  let a = 10;
3
  if a == 10 {
4
    println!("a is 10");
5
  } else {
6
    println!("a is not 10");
7
  }
8

9
  let grade = 67;
10
  let letter = if grade > 90 { 'A' }
11
                else if grade > 80 { 'B' }
12
                else if grade > 70 { 'C' }
13
                else if grade > 60 { 'D' }
14
                else { 'F' };
15
  println!("Grade: {}", letter);
16
}

Match #

match is an alternative to if - else if expression branches that compare a value against a pattern and return a value, match branches must be exhaustive meaning that they cover every possible value. The pattern can be a literal (0), an OR pipe pattern (1|2), a range (3..=9) or any (_).

1
fn main() {
2
  let n = 3;
3
  let label = match n {
4
      0       => "zero",
5
      1 | 2   => "small",
6
      3..=9   => "medium",
7
      _       => "large",
8
  };
9
  println!("{}", label);
10
}

Loops #

We can repeatidly execute a block of code with a loop (infinite), while (condition-driven) or a for (iterator-driven) loop method.

Loop #

Runs until it encounters a break, else it runs indefinitely. You can pass a value to break in order to return it from the loop.

1
fn main() {
2
  let mut a = 5;
3
  let final_a = loop {
4
    a -= 1;
5
    if a == 2 { break a; }
6
  };
7
  println!("Loop result = {}", final_a);  // 2
8
}

While #

Runs until a condition goes from true to false.

1
fn main() {
2
  let mut b = 5;
3
  while b > 2 {
4
    b -= 1;
5
    println!("b = {}", b); // 5,4,3
6
  }
7
}

For #

Runs until it finishes iterating over the elements of a collection. A for loop can be considered a while loop with a counter but it is optimized for this use case.

1
fn main() {
2
  for i in 0..3   { println!("{}", i); }   // 0, 1, 2
3
  for i in 0..=3  { println!("{}", i); }   // 0, 1, 2, 3
4
  let values = [1, 2, 3, 4];
5
  for v in &values {
6
    println!("value = {}", v);   // 1,2,3,4
7
  }
8
}

Break, Continue, Labels #

To exit the innermost loop use break. To skip the next iteration use continue. To target a specific loop within nested loops you can add a label to it 'loop_name:.

1
fn main() {
2
    'outer: for i in 0..5 {
3
        for j in 0..5 {
4
            if i * j > 6 { break 'outer; }
5
            println!("{}, {}", i, j);
6
        }
7
    }
8
}

Questions #

Does this compile? If not, why and how to correct?

1
fn main() {
2
  let a=2;
3
  let b=3.0;
4
  println!("Sum of a and b = {}", a+b);
5
}

You have an array of 4 floats, implement find_mean()

1
fn main() {
2
  let ar = [2.5, 3.0, 4.5, 2.0];
3
  println!("Mean of ar = {}", find_mean(ar));
4
}

1
fn find_mean(ar: [f64; 4]) -> f64 {
2
 let mut sum = 0.0;
3
 for v in ar.iter() { sum += v; }
4
 sum / ar.len() as f64
5
}

Write down the output of this program

1
fn main() {
2
  let mut a:i8 = 125;
3
  a = a+3;
4
  println!("a={}", a);
5
}

State if true or false:

1. f32 is the default for floats = false, it is f64
2. Doing let a = 5; the data type of x is i8 = false, it is i32
3. Floats are compound data types = false, it is scalar
4. Statements do not produce a result = true, statements evaluate to ().
5. What is shadowing = rebinding an existing name, creates a fresh bind

Ownership #

Principle #

All programs need to manage memory, here are some common strategies:

• Manual (C/C++): the programmer allocates and frees explicitly. Fast but error-prone with leaks, double-frees, use-after-free.
• Garbage collected (Go, Java, Python): a runtime periodically scans for unreachable memory and frees it. Safe, but adds overhead and unpredictable pauses.
• Ownership (Rust): the compiler tracks who owns each value and inserts the deallocation calls at compile time. No runtime cost, no manual frees.

The three rules of ownership enforced at compile time:

1. Every value has exactly one owner (a variable).
2. There can only be one owner at a time.
3. When the owner goes out of scope, the value is dropped (memory freed).

1
fn main() {
2
    {
3
        let s = String::from("hello");   // s owns the String
4
        println!("{}", s);
5
    }                                    // s out of scope → String dropped
6
    // println!("{}", s);                // error: cannot find value `s`
7
}

Stack-Heap #

A running program uses two memory regions: the stack and the heap.

The stack stores values in LIFO order (last in, first out). Push and pop are fast, just a pointer bump. Every value on the stack must have a size known at compile time.

The heap stores values whose size is unknown at compile time or values that are expected to change at runtime.

Heap allocation first asks the allocator for a chunk of memory and returns a pointer, then access requires dereferencing that pointer. Both operations are slower than the stack push and pop.

graph LR
    subgraph Stack
        direction TB
        S1[main frame]
        S2[fn frame]
        S3["string<br>ptr | len | cap"]
    end
    subgraph Heap
        H1["[ h | e | l | l | o ]"]
    end
    S3 -.-> H1

String #

Many Rust types live on the heap because their size can change at runtime: String, Vec<T>, Box<T>, and other custom types that contain them.

String Literal #

A string literal (&str) is a collection of char bytes that are hardcoded into the binary and loaded into read-only memory at startup.

They are lightweight and fast, but immutable and fixed in size.

1
let s: &str = "hello";   // string literal, immutable

String Type #

A String is heap-allocated string that can grow at runtime.

1
fn main() {
2
    let mut s = String::from("hello");
3
    s.push_str(", world");
4
    println!("{}", s);                  // hello, world
5
}

From #

String::from is an associated function on the String type, accessed with ::. It asks the allocator for heap memory, copies the literal string into it, and returns ownership of the new String to the caller.

Memory is returned automatically when the owner goes out of scope, Rust inserts a call to the type’s drop method.

1
fn main() {
2
    let s = String::from("hello");      // allocator gives heap memory
3
}                                       // s out of scope → drop(s) → memory freed

Components #

A String has three components on the stack, a pointer, a length, and a capacity, with the pointer at the start of the heap buffer.

graph LR
    subgraph Stack
        direction TB
        P["ptr"]
        L["len: 5"]
        C["cap: 5"]
    end
    subgraph Heap
        B["[ h | e | l | l | o ]"]
    end
    P --> B

• len: bytes currently used.
• cap: bytes the heap buffer can hold before re-allocation.
• ptr: address of the first byte.

Each component is observable:

1
fn main() {
2
    let s = String::from("hello");
3
    println!("ptr = {:p}", s.as_ptr());
4
    println!("len = {}",   s.len());
5
    println!("cap = {}",   s.capacity());
6
}

The pointer might be different on every run because the OS uses address-space layout randomisation (ASLR) to make heap addresses unpredictable, a security measure against memory exploits.

Move #

Reassigning a non-Copy value (like String) to another variable moves the stack components, causing the original String variable to become invalid, now only the new variable one can reference the value.

Before let s2 = s1;:

graph LR
    subgraph Stack1["Stack"]
        A1["s1<br>ptr | len: 5 | cap: 5"]
    end
    subgraph Heap1["Heap"]
        B1["[ h, e, l, l, o ]"]
    end
    A1 --> B1

After let s2 = s1;:

graph LR
    subgraph Stack2["Stack"]
        A2["s1 (invalid)"]
        A3["s2<br>ptr | len: 5 | cap: 5"]
    end
    subgraph Heap2["Heap"]
        B2["[ h, e, l, l, o ]"]
    end
    A3 --> B2

The heap buffer remains untouched, only the three-word stack handle is transferred. Using s1 after the move is a compile error: borrow of moved value: s1.

1
fn main() {
2
    let s1 = String::from("hello");
3
    let s2 = s1;
4
    // println!("{}", s1);              // error: borrow of moved value
5
    println!("{}", s2);                 // ok
6
}

This rule keeps exactly one owner, which guarantees drop runs exactly once on the heap buffer (no double-frees).

Heap Parameters #

Passing a String to a function moves ownership in. Returning one moves ownership out.

1
fn takes(s: String) {
2
    println!("{}", s);
3
}                                       // s dropped here
4

5
fn gives() -> String {
6
    String::from("world")               // ownership moved to caller
7
}
8

9
fn main() {
10
    let s = String::from("hello");
11
    takes(s);
12
    // println!("{}", s);               // error: s was moved
13
    let s = gives();                    // shadow with the returned String
14
    println!("{}", s);
15
}

Clone #

When you genuinely need a deep copy of the heap and stack, call .clone(). This allocates a fresh heap buffer, copies the contents, and returns a new independent owner.

1
fn main() {
2
    let s1 = String::from("hello");
3
    let s2 = s1.clone();
4
    println!("s1 = {}, s2 = {}", s1, s2);   // both valid
5
}

graph LR
    subgraph Stack
        direction TB
        A1["s1<br>ptr | len | cap"]
        A2["s2<br>ptr | len | cap"]
    end
    subgraph Heap
        B1["[ h, e, l, l, o ]"]
        B2["[ h, e, l, l, o ]"]
    end
    A1 --> B1
    A2 --> B2

Cloning is always an explicit operation, it never happens implicitly by Rust. Seeing .clone() in code means that a new heap allocation just happened.

Copy #

Primitive types (i32, f64, bool, char, and tuples containing only Copy types) implement the Copy trait. Assigning a Copy type to another variable duplicates the bits on the stack (both variables remain valid).

1
fn main() {
2
    let x = 5;
3
    let y = x;
4
    println!("x = {}, y = {}", x, y);   // both valid
5
}

Copy types have no heap component, so duplicating the stack is enough. Calling .clone() on a Copy type does essentially the same operation as the assignment.

A type cannot have the Copy trait and own heap data, this would introduce a risk of double freeing the memory for both copies.

References #

If a function needs to read a String value without taking ownership you can pass a reference instead with &.

1
fn len(s: &String) -> usize {
2
    s.len()
3
}
4

5
fn main() {
6
    let s = String::from("hello");
7
    let n = len(&s);
8
    println!("'{}' has {} bytes", s, n);   // s still valid
9
}

A reference is a pointer that does not own the data. When the reference goes out of scope, nothing is dropped, only the owner can drop the data.

graph LR
    subgraph Stack
        direction TB
        S["s<br>ptr | len | cap"]
        R["r: &s"]
    end
    subgraph Heap
        B["[ h, e, l, l, o ]"]
    end
    S --> B
    R --> S

Borrowing #

Using a reference is called borrowing, there are two flavors:

This are the borrowing rules, enforced at compile time:

• At any point: either one &mut T, or any number of &T can exist but never both.
• All references must point to valid data (no dangling references).

These rules prevent data races and use-after-free, statically.

1
fn add_world(s: &String) {
2
    // s.push_str(", world");           // error: cannot borrow since reference is immutable
3
}

1
fn add_world(s: &mut String) {
2
    s.push_str(", world");
3
}
4

5
fn main() {
6
    let mut s = String::from("hello");
7
    add_world(&mut s);
8
    println!("{}", s);                  // hello, world
9
}

To pass a mutable reference, three things must align: the variable must be declared let mut, the call site must say &mut s, and the parameter must be &mut T.

Slices #

A slice is a reference to a contiguous subsequence of a collection, it is a range or window, usually not the whole thing. Like any reference, a slice does not own the data.

For strings the slice type is &str; for arrays/vecs it’s &[T].

1
fn main() {
2
    let s = String::from("hello world");
3

4
    let hello = &s[0..5];               // "hello"
5
    let world = &s[6..11];              // "world"
6

7
    let hello = &s[..5];                // start can be omitted (= 0)
8
    let world = &s[6..];                // end can be omitted (= s.len())
9
    let whole = &s[..];                 // both omitted = full slice
10
}

Internally a slice is a pointer + a length, pointing into the middle of the original buffer.

graph LR
    subgraph Stack
        direction TB
        S["s: String<br>ptr | len: 11 | cap: 11"]
        W["world: &str<br>ptr | len: 5"]
    end
    subgraph Heap
        B["h | e | l | l | o | _ | w | o | r | l | d"]
    end
    S --> B
    W -.-> B

(The world slice’s pointer points to index 6 of the same buffer.)

Reference Preference #

Functions should generally accept &str rather than &String. &str references are more general since they point directly to the char bytes with their pointer and length components, everything needed to refer to a string literal, a heap buffer owned by a String (coerced into &str by Rust), or a slice of either.

On the other hand a &String, with its three component stack handle (pointer, length and capacity) can only point to an existing String heap buffer, that when used as a parameter would be auto-coerced to &str anyway.

1
fn first_word(s: &str) -> &str {
2
    for (i, &b) in s.as_bytes().iter().enumerate() {
3
        if b == b' ' { return &s[..i]; }
4
    }
5
    s
6
}
7

8
fn main() {
9
    let owned = String::from("hello world");
10
    println!("{}", first_word(&owned));     // hello — from a String
11
    println!("{}", first_word("ok"));       // ok    — from a literal
12
}

graph LR
    subgraph "&str — one hop"
        direction TB
        A1["&str<br>ptr | len"] --> A2["[ h, e, l, l, o ]"]
    end
    subgraph "&String — two hops"
        direction TB
        B1["&String"] --> B2["String<br>ptr | len | cap"] --> B3["[ h, e, l, l, o ]"]
    end

Questions #

List the rules of ownership.

Stack vs heap, when and why?

Write a first_word function: This is a function that takes a &String reference and returns a reference to the first word of the value.

1
fn first_word(s: &String) -> &str {
2
    for (i, &b) in s.as_bytes().iter().enumerate() {
3
        if b == b' ' { return &s[..i]; }
4
    }
5
    &s[..]
6
}

1
fn first_word(s: &str) -> &str {
2
    match s.find(' ') {
3
        Some(i) => &s[..i],
4
        None    => s,
5
    }
6
}

Two ways of working with strings

True or false

1. let x = 5; stores x on the heap. = False, it is a copy living on the stack.
2. After let x = 5; let y = x;, x is no longer usable. = False, it is a copy so the bits are duplicated.
3. After let s1 = String::from("hello"); let s2 = s1;, s1 is no longer usable = True, it is not a copy so ownership is moved.
4. You may have one &mut and one & to the same String in the same scope. = False, a mutable borrow excludes other borrows for its lifetime.
5. You may have multiple & to the same String in the same scope. = True, shared borrows is allowed provided none are mutable.

Structs, Enums, Collections #

Structs #

Structs are group named, typed fields under a single type. Similar to tuples, but with fields that have names so access is order-independent. We use struct to define the template, create an instance of the struct template and then we can access the fields with dot notation.

1
struct Student {
2
    name: String,
3
    id: String,
4
    age: u8,
5
    class: u8,
6
}
7

8
let student1 = Student {
9
    name: String::from("Jose"),
10
    age: 20,
11
    id: String::from("2023Student12345"),
12
    class: 10,
13
};
14

15
println!("class = {}", student1.class);

To mutate fields, the binding must be mut. Rust mutates the whole struct or none of it, you can’t have some fields mutable and some not.

1
let mut student2 = Student {
2
    name: String::from("Jose"),
3
    age: 20,
4
    id: String::from("2023Student12345"),
5
    class: 10,
6
};
7
student2.class += 1;

Init Shorthand #

When a function parameter and a field share their name, we can drop the name: name repetition:

1
fn create_student(name: String, id: String) -> Student {
2
    Student { name, id, age: 20, class: 10 }
3
}
4

5
let student4 = create_student(
6
    String::from("Ivy"),
7
    String::from("2023Student12347"),
8
);

Struct Update Syntax #

Copy the remaining fields from another instance with ..other:

1
let student6 = Student {
2
    name: String::from("Dar"),
3
    id: String::from("2023Student12349"),
4
    ..student5
5
};

Tuple Structs #

A named struct with unnamed, positional fields. Useful when labels would add noise (3D points, RGB colors). Access by position with .0, .1, .2.

1
struct Point3D(i32, i32, i32);
2
let p = Point3D(10, 5, -10);
3
println!("x = {}", p.0);

Methods #

Methods are functions attached to a type. They live inside an impl block and take self as the first parameter. We can have multiple impl blocks attached to the same type. Methods are called with dot notation:

• &self — read-only borrow (most common)
• &mut self — mutable borrow (mutating methods)
• self — takes ownership, consuming the instance

1
impl Student {
2
    fn name(&self) -> &str {
3
        &self.name
4
    }
5
    fn promote(&mut self, new_class: u8) {
6
        self.class = new_class;
7
    }
8
    fn print(&self) {
9
        println!(
10
            "Student: name = {}, age = {}, id = {}, class = {}",
11
            self.name, self.age, self.id, self.class
12
        );
13
    }
14
}
15

16
let mut student7 = Student {
17
    name: String::from("Jose"),
18
    age: 20,
19
    id: String::from("2023EE1234"),
20
    class: 10,
21
};
22
student7.promote(11);
23
student7.print();

Associated Functions #

Associated functions live in the same impl block but take no self, they’re tied to the type, not an instance. Associated functions are called with ::. A natural example would be a constructor:

1
// We are using "Self" here as an alias for "Student"
2
// This keeps the constructor generic
3
impl Student {
4
    fn new(name: String, id: String) -> Self {
5
        Self { name, id, age: 20, class: 10 }
6
    }
7
}
8

9
let student8 = Student::new(
10
    String::from("Jose"),
11
    String::from("2023EE3214"),
12
);

Enums #

An enum defines a type whose value is exactly one of a fixed set of variants. Each variant can carry different data (or none).

1
#[derive(Debug)]
2
enum Location {
3
    UnitedStates(String),
4
    India(String),
5
    Singapore(String),
6
}
7

8
#[derive(Debug)]
9
struct Student {
10
    name: String,
11
    id: String,
12
    age: u8,
13
    class: u8,
14
    location: Location,
15
}
16

17
let blr = Location::India(String::from("Bangalore"));
18

19
let student9 = Student {
20
    name: String::from("Carlo"),
21
    age: 7,
22
    id: String::from("2023EE123"),
23
    class: 2,
24
    location: blr,
25
};
26
println!("student : {:?}", student9);

Use an enum when each instance is a mutually exclusive state and the carried data, fields and values differ per state. Use a struct when every instance has the same set of fields (even if their value changes). A natural example of this would be a user login state:

1
enum LoginResult {
2
    Success { user_id: u64, token: String },
3
    InvalidCredentials,
4
    RateLimited { retry_after_seconds: u32 },
5
    ServerError(String),
6
}

The struct version of the same thing forces optional or nullable fields and admits invalid states (success: false with a token set, etc.):

1
struct LoginResult {
2
    success: bool,
3
    user_id: Option<u64>,
4
    token: Option<String>,
5
    rate_limited: bool,
6
    retry_after_seconds: Option<u32>,
7
    error_message: Option<String>,
8
}

Enums are closed entities meaning that only the defining crate can add variants. If you need an enum-like object that can be extended by a third-party crate use a trait instead.

Pattern Matching #

Enums pair with match for exhaustive handling. Adding a new variant forces every match to be updated, the compiler will refuse to build until they are.

1
match result {
2
    LoginResult::Success { user_id, token } => {
3
        println!("welcome {user_id}, token: {token}");
4
    }
5
    LoginResult::InvalidCredentials => println!("wrong password"),
6
    LoginResult::RateLimited { retry_after_seconds } => {
7
        println!("wait {retry_after_seconds}s");
8
    }
9
    LoginResult::ServerError(msg) => println!("error: {msg}"),
10
}
11

12
// If we add another variant to LoginResult this match
13
// will fail to compile until we handle it

For quick single-variant checks, if let is shorter:

1
if let LoginResult::Success { user_id, .. } = result {
2
    println!("logged in as {user_id}");
3
}

Option Enum #

Rust has no null, instead there is an Option<T> enum defined by the standard library that can be in a Stome<T> state or a None state (similar to null).

1
enum Option<T> {
2
    Some(T),
3
    None,
4
}

1
fn divide(num: i32, den: i32) -> Option<i32> {
2
    if den == 0 { None } else { Some(num / den) }
3
}

Result Enum #

For fallible operations that might produce an error, use Result<T, E> instead:

1
enum Result<T, E> {
2
    Ok(T),
3
    Err(E),
4
}

1
fn parse_age(s: &str) -> Result<u8, std::num::ParseIntError> {
2
    s.parse::<u8>()
3
}

Unwrapping #

The ? operator unwraps Ok/Some or returns the Err/None early. It only works inside a function whose return type is a Result or Option.

1
fn read_age(s: &str) -> Result<u8, std::num::ParseIntError> {
2
    let age = match s.parse::<u8>() {
3
        Ok(n) => n,
4
        Err(e) => return Err(e),
5
    };
6
    Ok(age)
7
}