New upstream version 1.23.0+dfsg1

[rustc.git] / src / doc / reference / src / items / use-declarations.md

# Use declarations

> **<sup>Syntax:<sup>**  
> _UseDeclaration_ :  
> &nbsp;&nbsp; &nbsp;&nbsp; `use` [_SimplePath_]&nbsp;(`as` [IDENTIFIER])<sup>?</sup> `;`  
> &nbsp;&nbsp; | `use` ([_SimplePath_]<sup>?</sup> `::`)<sup>?</sup> `{` _UseDeclarationItems_ `}` `;`  
> &nbsp;&nbsp; | `use` ([_SimplePath_]<sup>?</sup> `::`)<sup>?</sup> `*` `;`  
>  
> _UseDeclarationItems_ :  
> &nbsp;&nbsp; _UseDeclarationItem_ ( `,` _UseDeclarationItem_ )<sup>*</sup> `,`<sup>?<sup>  
>  
> _UseDeclarationItem_ :  
> &nbsp;&nbsp; ( `self` | [IDENTIFIER] ) ( `as` [IDENTIFIER] )<sup>?</sup>  

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.

[path]: paths.html
[modules]: items/modules.html
[blocks]: expressions/block-expr.html

> **Note**: Unlike in many languages, `use` declarations in Rust do *not*
> declare linkage dependency with external crates. Rather, [`extern crate`
> declarations](items/extern-crates.html) 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:

```rust
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:

```rust
# 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:

```rust
# #![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() {}
```

[IDENTIFIER]: identifiers.html
[_SimplePath_]: paths.html