Modules | Functions and Modules Tutorial

Rust Programming: Functions and Modules - Modules

Modules are a fundamental part of Rust's organization system. They allow you to break down large programs into smaller, manageable, and reusable pieces. They help with code organization, prevent naming conflicts, and control visibility.

What are Modules?

Think of modules as namespaces. They encapsulate code (functions, structs, enums, constants, etc.) and provide a way to group related items together. This prevents naming collisions when you have multiple parts of your program defining things with the same name.

Defining Modules

You define a module using the mod keyword. Here's a basic example:

mod greetings {
    pub fn hello() {
        println!("Hello from the greetings module!");
    }

    fn goodbye() { // Not public, so not accessible outside the module
        println!("Goodbye from the greetings module!");
    }
}

fn main() {
    greetings::hello(); // Accessing the public function
    // greetings::goodbye(); // This would cause a compile error - not public
}

Explanation:

mod greetings { ... }: This declares a module named greetings.
pub fn hello() { ... }: The pub keyword makes the hello function public. Public items are accessible from outside the module.
fn goodbye() { ... }: The goodbye function is private by default. It's only accessible within the greetings module itself.
greetings::hello(): To access a public item within a module, you use the module name followed by :: and then the item's name.

Module Organization - Files

As your modules grow, you'll want to organize them into separate files. Rust supports this directly.

Create a directory for your module: Let's say you want to create a module called math. Create a directory named math.

Create a mod.rs file inside the directory: Inside the math directory, create a file named mod.rs. This file will contain the module's code.

// math/mod.rs
pub fn add(x: i32, y: i32) -> i32 {
    x + y
}

pub fn subtract(x: i32, y: i32) -> i32 {
    x - y
}

fn internal_function() {
    println!("This is an internal function.");
}

Declare the module in the parent file: In the file where you want to use the math module (e.g., main.rs), you need to declare the module using mod math;.

// main.rs
mod math; // Declares the math module

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

    // math::internal_function(); // Error: private function
}

Important: The mod math; statement in main.rs tells the compiler to look for a math directory and load the mod.rs file within it.

Nested Modules

You can nest modules within other modules to create a hierarchical structure.

mod outer {
    pub fn outer_function() {
        println!("Outer function");
    }

    mod inner {
        pub fn inner_function() {
            println!("Inner function");
        }
    }
}

fn main() {
    outer::outer_function();
    outer::inner::inner_function();
}

Alternatively, you can define nested modules in a single file:

mod outer {
    mod inner {
        pub fn inner_function() {
            println!("Inner function");
        }
    }

    pub fn outer_function() {
        println!("Outer function");
    }
}

fn main() {
    outer::outer_function();
    outer::inner::inner_function();
}

`use` Declarations

Typing module_name::item_name repeatedly can be verbose. The use keyword allows you to bring items into the current scope.

mod greetings {
    pub fn hello() {
        println!("Hello!");
    }
}

fn main() {
    use greetings::hello; // Bring the hello function into scope

    hello(); // Now you can call hello directly
}

You can also use use to rename items:

use greetings::hello as greet;

fn main() {
    greet(); // Call the function using the new name
}

You can use use to bring all public items from a module into scope using the wildcard *:

use greetings::*; // Bring all public items from greetings into scope

fn main() {
    hello(); // Call hello directly
}

Caution: Using use * can make your code harder to read and maintain, as it's not immediately clear where items are coming from. It's generally better to be explicit with your use declarations.

Visibility Rules

Private by default: Items (functions, structs, enums, etc.) are private to their module by default.
pub for public: Use the pub keyword to make an item public, allowing it to be accessed from outside the module.

Re-exporting with pub use: You can re-export items from other modules using pub use. This allows you to provide a simplified interface to your module's users.

mod inner {
    pub fn inner_function() {
        println!("Inner function");
    }
}

pub use inner::inner_function; // Re-export inner_function

fn main() {
    inner_function(); // Accessible directly through the outer module
}

`super` and `self`

self: Refers to the current module. Useful for disambiguating names within a module.
super: Refers to the parent module. Useful for accessing items in the parent module.

mod outer {
    pub fn outer_function() {
        println!("Outer function");
    }

    mod inner {
        pub fn inner_function() {
            println!("Inner function");
            super::outer_function(); // Call outer_function from the parent module
        }
    }

    pub fn call_inner() {
        inner::inner_function();
    }
}

fn main() {
    outer::call_inner();
}

Summary

Modules are essential for organizing Rust code. They provide:

Namespacing: Prevent naming conflicts.
Encapsulation: Control visibility of code.
Organization: Break down large programs into smaller, manageable units.
Reusability: Modules can be reused in different parts of your project or in other projects.

By understanding and utilizing modules effectively, you can write cleaner, more maintainable, and more scalable Rust code.