Use declarations

^Syntax:
UseDeclaration :
use SimplePath (as IDENTIFIER)^? ;
| use (SimplePath^? ::)^? { UseDeclarationItems } ;
| use (SimplePath^? ::)^? * ;

UseDeclarationItems :
UseDeclarationItem ( , UseDeclarationItem )^* ,^?

UseDeclarationItem :
( self | IDENTIFIER ) ( as IDENTIFIER )^?

A use declaration creates one or more local name bindings synonymous with some other path. Usually a use declaration is used to shorten the path required to refer to a module item. These declarations may appear in modules and blocks, usually at the top.

Note: Unlike in many languages, use declarations in Rust do not declare linkage dependency with external crates. Rather, extern crate declarations declare linkage dependencies.

Use declarations support a number of convenient shortcuts:

• Simultaneously binding a list of paths differing only in their final element, using the glob-like brace syntax use a::b::{c,d,e,f};
• Simultaneously binding a list of paths differing only in their final element and their immediate parent module, using the self keyword, such as use a::b::{self, c, d};
• 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::*;

An example of use declarations:

use std::option::Option::{Some, None};
use std::collections::hash_map::{self, HashMap};

fn foo<T>(_: T){}
fn bar(map1: HashMap<String, usize>, map2: hash_map::HashMap<String, usize>){}

fn main() {
    // Equivalent to 'foo(vec![std::option::Option::Some(1.0f64),
    // std::option::Option::None]);'
    foo(vec![Some(1.0f64), None]);

    // Both `hash_map` and `HashMap` are in scope.
    let map1 = HashMap::new();
    let map2 = hash_map::HashMap::new();
    bar(map1, map2);
}

Like items, use declarations are private to the containing module, by default. Also like items, a use declaration can be public, if qualified by the pub keyword. Such a use declaration serves to re-export a name. A public use declaration can therefore redirect some public name to a different target definition: even a definition with a private canonical path, inside a different module. If a sequence of such redirections form a cycle or cannot be resolved unambiguously, they represent a compile-time error.

An example of re-exporting:

# fn main() { }
mod quux {
    pub use quux::foo::{bar, baz};

    pub mod foo {
        pub fn bar() { }
        pub fn baz() { }
    }
}

In this example, the module quux re-exports two public names defined in foo.

Also note that the paths contained in use items are relative to the crate root. So, in the previous example, the use refers to quux::foo::{bar, baz}, and not simply to foo::{bar, baz}. This also means that top-level module declarations should be at the crate root if direct usage of the declared modules within use items is desired. It is also possible to use self and super at the beginning of a use item to refer to the current and direct parent modules respectively. All rules regarding accessing declared modules in use declarations apply to both module declarations and extern crate declarations.

An example of what will and will not work for use items:

# #![allow(unused_imports)]
use foo::baz::foobaz;    // good: foo is at the root of the crate

mod foo {

    mod example {
        pub mod iter {}
    }

    use foo::example::iter; // good: foo is at crate root
//  use example::iter;      // bad:  example is not at the crate root
    use self::baz::foobaz;  // good: self refers to module 'foo'
    use foo::bar::foobar;   // good: foo is at crate root

    pub mod bar {
        pub fn foobar() { }
    }

    pub mod baz {
        use super::bar::foobar; // good: super refers to module 'foo'
        pub fn foobaz() { }
    }
}

fn main() {}