17.3 Modules: Structuring Code Within a Crate

While crates split your project at a higher level, modules partition the code inside each crate. Modules let you define namespaces for your structs, enums, functions, traits, and constants—controlling how these items are exposed internally and externally.

17.3.1 Module Basics

By default, an item in a module is private to that module. Marking an item as pub makes it accessible beyond its defining module. You can reference a module’s items with a path such as module_name::item_name, or you can import them into scope with use.

17.3.2 Defining Modules and File Organization

Modules can be defined inline (in the same file) or in separate files. Larger crates typically place modules in their own files or directories for clarity.

Inline Modules

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

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

File-Based Modules

Moving the math module into a separate file might look like this:

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

In main.rs:

mod math;

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

In math.rs:

#![allow(unused)]
fn main() {
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}
}

17.3.3 Submodules

Modules can contain other modules, allowing you to nest them as needed:

my_crate/
├── src/
│   ├── main.rs
│   ├── math.rs
│   └── math/
│       └── operations.rs
  • main.rs: 
    mod math;

fn main() {
    let product = math::operations::multiply(5, 3);
    println!("Product: {}", product);
}
  • math.rs: 
    pub mod operations; // Declare and re-export
  • math/operations.rs: 
    pub fn multiply(a: i32, b: i32) -> i32 {
    a * b
}

You must declare each submodule in its parent module with mod. Rust then knows where to locate the file based on standard naming conventions.

17.3.4 Alternate Layouts

Older Rust projects often store child modules in a file named mod.rs. For example, math/mod.rs instead of math.rs and a subdirectory for the module’s items. While this is still supported, the modern approach is to avoid mod.rs and name files directly after the module. Mixing both styles in the same crate can be confusing, so pick one layout and stick to it.

17.3.5 Visibility and Privacy

By default, items are private within their defining module. You can modify their visibility:

  • pub: Publicly visible outside the module.
  • pub(crate): Visible anywhere in the same crate.
  • pub(super): Visible to the parent module.
  • pub(in path): Visible within a specified ancestor.
  • pub(self): Equivalent to private visibility (same module).

For structures, marking the struct with pub doesn’t automatically expose its fields. You must mark each field pub if you want it publicly accessible.

17.3.6 Paths and Imports

Use absolute or relative paths to reference items:

  • Absolute: 
    crate::some_module::some_item();
std::collections::HashMap::new();
  • Relative (using self or super): 
    self::helper_function();
super::sibling_function();

use Keyword

use can bring items (or modules) into local scope:

use std::collections::HashMap;

fn main() {
    let mut map = HashMap::new();
    map.insert("banana", 25);
    println!("{:?}", map);
}

If a submodule also needs HashMap, you must either use a fully qualified path (std::collections::HashMap) or declare use again within that submodule’s scope.

Wildcard Imports and Nested Paths
  • Wildcard Imports (use std::collections::*;) are discouraged because they can obscure where items originate and cause name collisions.
  • Nested Paths reduce repetition when importing multiple items from the same parent: 
    use std::{cmp::Ordering, io::{self, Write}};
Aliasing

Use as to rename an import locally:

use std::collections::HashMap as Map;

fn main() {
    let mut scores = Map::new();
    scores.insert("player1", 10);
    println!("{:?}", scores);
}

17.3.7 Re-exporting

You can expose internal items under a simpler or more convenient path using pub use. This technique is called re-exporting:

mod hidden {
    pub fn internal_greet() {
        println!("Hello from a hidden module!");
    }
}

// Re-export under a new name
pub use hidden::internal_greet as greet;

fn main() {
    greet();
}

17.3.8 The #[path] Attribute

Occasionally, you may need to place module files in a non-standard directory layout. You can override the default paths using #[path]:

#[path = "custom/dir/utils.rs"]
mod utils;

fn main() {
    utils::do_something();
}

This is rare but can be handy when dealing with legacy or generated file structures.

17.3.9 Prelude and Common Imports

Rust automatically imports several fundamental types and traits (e.g., Option, Result, Clone, Copy) through the prelude. Anything not in the prelude must be explicitly imported, which increases clarity and prevents naming collisions.