Rust — Modules

Why modules exist

Real programs outgrow one file. Modules group related code, control what's public, and keep names from colliding:

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

    fn secret_helper() {}          // private by default!

    pub fn double(x: i32) -> i32 {
        add(x, x)                  // siblings see each other
    }
}

fn main() {
    println!("{}", math::add(2, 3));      // path via ::
    // math::secret_helper();             ❌ private — invisible outside
}

Visibility — everything is private by default

pub is the opt-in to being seen from outside:

Declaration	Visible to
fn helper()	same module + children only
pub fn api()	anyone who can reach the module

This default forces deliberate API design — you choose the surface area.

use — importing into scope

Typing full paths everywhere is noisy; use creates shortcuts:

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

use math::add;              // now just call add(…)
use crate::math::add as sum;   // rename to avoid collisions

add(2, 2);
sum(1, 1);

Idiomatic style: bring in the function, not the whole module, for frequent calls; keep mod::fn paths for rare ones.

File-based modules

Inline mod math { … } scales badly. Move it to a file instead:

src/
├── main.rs        ← mod math;   (declaration only)
└── math.rs        ← actual contents

main.rs

mod math;            // tells Rust: look for math.rs

fn main() {
    println!("{}", math::add(1, 2));
}

math.rs contains the functions directly (no wrapping mod math {} needed at top level of that file).

Nested modules → folders

src/
├── main.rs          ← mod shop;
└── shop/
    ├── mod.rs       ← pub mod cart;  pub mod pricing;
    ├── cart.rs
    └── pricing.rs

use crate::shop::cart;
// or modern style without mod.rs:
// src/shop.rs  +  src/shop/cart.rs

Paths start from crate:: — the root of your binary/library.

re-exports clean up APIs

In shop/mod.rs:

pub mod cart;
pub mod pricing;

pub use pricing::calculate_total;    // lift into shop::

Consumers write shop::calculate_total(...) regardless of internal layout — refactoring stays invisible to users.

Common errors decoded

Message	Cause
unresolved name add	forgot use, or item isn't pub
module is private	parent module itself lacks pub
file not found for module	filename ≠ module name

Mini Practice

1. Inline module with one pub + one private fn; try calling both.
2. Extract it into math.rs with mod math;.
3. Create a two-level folder package and import from main.
4. Re-export a deep function up two levels.
5. Break compilation by removing pub; read the privacy error.

Next: packages →