Module std::use_keyword

source ·
Expand description

Import or rename items from other crates or modules.

Usually a use keyword is used to shorten the path required to refer to a module item. The keyword may appear in modules, blocks and even functions, usually at the top.

The most basic usage of the keyword is use path::to::item;, though a number of convenient shortcuts are supported:

  • Simultaneously binding a list of paths with a common prefix, using the glob-like brace syntax use a::b::{c, d, e::f, g::h::i};
  • Simultaneously binding a list of paths with a common prefix and their common parent module, using the self keyword, such as use a::b::{self, c, d::e};
  • Rebinding the target name as a new local name, using the syntax use p::q::r as x;. This can also be used with the last two features: use a::b::{self as ab, c as abc}.
  • Binding all paths matching a given prefix, using the asterisk wildcard syntax use a::b::*;.
  • Nesting groups of the previous features multiple times, such as use a::b::{self as ab, c, d::{*, e::f}};
  • Reexporting with visibility modifiers such as pub use a::b;
  • Importing with _ to only import the methods of a trait without binding it to a name (to avoid conflict for example): use ::std::io::Read as _;.

Using path qualifiers like crate, super or self is supported: use crate::a::b;.

Note that when the wildcard * is used on a type, it does not import its methods (though for enums it imports the variants, as shown in the example below).

enum ExampleEnum {
    VariantA,
    VariantB,
}

impl ExampleEnum {
    fn new() -> Self {
        Self::VariantA
    }
}

use ExampleEnum::*;

// Compiles.
let _ = VariantA;

// Does not compile !
let n = new();
Run

For more information on use and paths in general, see the Reference.

The differences about paths and the use keyword between the 2015 and 2018 editions can also be found in the Reference.