use Keyword

Avoid Writing Full Paths with the use Keyword

The use⮳ keyword creates a shortcut for a path. The shorter name can be used everywhere else in the scope.

//! This example demonstrates how to use the `use` keyword to bring items into
//! scope without having to write their full path.

/// Modules are used to organize code into logical units.
mod a {
    /// Nested module.
    /// We prefix `mod b` with `pub` to make it public.
    pub mod b {
        /// Define a (public) function within a module.
        pub fn fn_in_b() {
            println!("in b!");
        }
    }
}

fn main() {
    // Call a function in module `b` using its full path.
    a::b::fn_in_b();

    // Bring the `b` module in scope with the `use` keyword.
    // A relative path starts from the current module and uses
    // `self`, or an identifier in the current module.
    use a::b;
    // You could also write: `use self::a::b;`.

    // Call a function using its shortened path.
    b::fn_in_b();
}

Bring a Function in Scope

It is idiomatic to bring the function's parent module into scope, not the function itself:

/// This module represents the front of the house in a restaurant.
mod front_of_house {
    /// This module handles hosting duties within the front of the house.
    pub mod hosting {
        /// Adds a customer to the waitlist.
        pub fn add_to_waitlist() {
            println!("Add to waitlist.");
        }
    }
}

// Bring the hosting module in scope.
use front_of_house::hosting;

fn eat_at_restaurant() {
    // We can now access the function within the `hosting` module,
    // without writing the whole path e.g.
    // `front_of_house::hosting::add_to_waitlist()`.
    //
    // IDIOM: we imported the module, not the function itself.
    hosting::add_to_waitlist();
}

fn main() {
    eat_at_restaurant();
}

Bring a Struct or Enum in Scope

On the other hand, when bringing in structs, enums, and other items with use, it is idiomatic to specify the full path.

// This `use` statement allows us to use `HashMap` directly without having to
// specify its full path.
// IDIOM: we imported the `struct` itself, not its parent module.
use std::collections::HashMap;

// `HashMap` is declared in the standard library (`std`), which is an external
// crate. We therefore prefix the path with the crate's name.

fn main() {
    // We now refer to `HashMap` without using its full path.
    let mut mymap: HashMap<u32, String> = HashMap::new();

    // Let's add something to it then print...
    mymap.entry(42).or_insert("my favorite number".into());
    println!("{:?}", mymap);
}

Bring an Item from an External Crate into Scope

//! This example demonstrates how to use the `use` keyword to bring items from
//! external crates into scope, without having to write their full paths.

// Import a module from an external crate (here, `std`, the standard library).
// The absolute path begins with the crate name.
use std::array;
// Import a struct from an external crate.
// With the following, `HashMap` can be used without prefix in the current
// module.
use std::collections::HashMap;

fn main() {
    // Use a function from the `array` module of the `std` crate.
    let _arr = array::from_ref(&1);

    // Use `HashMap` from the `collections` module of the `std` crate.
    let _h: HashMap<String, String> = HashMap::new();
}