Organizing Code: Modules and Crates

Working Code

As code grows, putting everything in one file gets messy. Modules let you organize code into logical groups.

mod math {
    pub fn add(a: i32, b: i32) -> i32 {
        a + b
    }

    pub fn multiply(a: i32, b: i32) -> i32 {
        a * b
    }

    fn secret_formula(x: i32) -> i32 {
        x * 42  // private function!
    }
}

fn main() {
    let sum = math::add(3, 5);
    let product = math::multiply(4, 6);
    println!("3 + 5 = {sum}");
    println!("4 x 6 = {product}");
    // math::secret_formula(1); // error! private
}

mod math creates a module. You call its functions with the path math::add().

Try It Yourself

1. Uncomment math::secret_formula(1). What error do you get?
2. Add pub to secret_formula. Does the error go away?

"Why?" — pub and Private by Default

In Rust, items inside a module are private by default. You must explicitly add pub to make them accessible from outside.

This follows the same philosophy as ownership — safety is the default. Expose only what's necessary and hide the rest.

| Keyword | Meaning | | ------- | ------------------------------------------------ | | (none) | Private — accessible only within the same module | | pub | Public — accessible from outside |

use — Shorter Paths

If you want to skip writing math::add() every time, use use:

mod math {
    pub fn add(a: i32, b: i32) -> i32 {
        a + b
    }

    pub fn multiply(a: i32, b: i32) -> i32 {
        a * b
    }
}

use math::add;
use math::multiply;

fn main() {
    println!("3 + 5 = {}", add(3, 5));
    println!("4 x 6 = {}", multiply(4, 6));
}

You can import multiple items at once:

use math::{add, multiply};

Splitting Modules Into Files

As code grows further, you can move modules to separate files. This is the most common pattern in real projects.

src/
├── main.rs
└── math.rs

src/math.rs:

pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

pub fn multiply(a: i32, b: i32) -> i32 {
    a * b
}

src/main.rs:

mod math;  // loads the math.rs file as a module

fn main() {
    println!("3 + 5 = {}", math::add(3, 5));
}

Just write mod math; and Rust finds and links the math.rs file automatically.

Using External Crates

You used the rand crate in Lesson 07. External crates are available on crates.io.

cargo add rand

This command automatically adds the crate to the [dependencies] section of Cargo.toml:

[dependencies]
rand = "0.8"

Then import and use it:

use rand::Rng;

fn main() {
    let mut rng = rand::thread_rng();
    let number: i32 = rng.gen_range(1..=100);
    println!("Random number: {number}");
}

Standard Library Modules

Rust comes with a standard library (std) full of commonly used features. Import them with use — no installation needed.

use std::collections::HashMap;

fn main() {
    let mut scores = HashMap::new();
    scores.insert("Alice", 95);
    scores.insert("Bob", 88);

    for (name, score) in &scores {
        println!("{name}: {score}");
    }
}

Commonly used standard library modules:

| Module | Purpose | | ------------------ | ----------------------- | | std::io | Input/output | | std::collections | HashMap, BTreeMap, etc. | | std::fs | File read/write | | std::fmt | Formatting |

// Absolute path: starts from crate
crate::math::add(1, 2);

// Relative path: from current location
math::add(1, 2);

// Parent module reference
super::some_function();

mod geometry {
    // circle_area: takes radius, returns area of a circle
    // rectangle_area: takes width and height, returns area
    // Both should be pub!
    // Hint: PI is std::f64::consts::PI
}

fn main() {
    println!("Circle: {:.2}", geometry::circle_area(5.0));
    println!("Rectangle: {:.2}", geometry::rectangle_area(4.0, 6.0));
}

fn main() {
    let mut map = std::collections::HashMap::new();
    map.insert("a", 1);
    map.insert("b", 2);

    let mut set = std::collections::HashSet::new();
    set.insert("x");
    set.insert("y");

    println!("{:?}", map);
    println!("{:?}", set);
}

mod secrets {
    fn hidden() -> i32 { 42 }
}

fn main() {
    println!("{}", secrets::hidden());
}