src/doc/reference/src/items/use-declarations.md

   1 # Use declarations
   2
   3 > **<sup>Syntax:<sup>**
   4 > _UseDeclaration_ :
   5 > &nbsp;&nbsp; &nbsp;&nbsp; `use` [_SimplePath_]&nbsp;(`as` [IDENTIFIER])<sup>?</sup> `;`
   6 > &nbsp;&nbsp; | `use` ([_SimplePath_]<sup>?</sup> `::`)<sup>?</sup> `{` _UseDeclarationItems_ `}` `;`
   7 > &nbsp;&nbsp; | `use` ([_SimplePath_]<sup>?</sup> `::`)<sup>?</sup> `*` `;`
   8 >
   9 > _UseDeclarationItems_ :
  10 > &nbsp;&nbsp; _UseDeclarationItem_ ( `,` _UseDeclarationItem_ )<sup>*</sup> `,`<sup>?<sup>
  11 >
  12 > _UseDeclarationItem_ :
  13 > &nbsp;&nbsp; ( `self` | [IDENTIFIER] ) ( `as` [IDENTIFIER] )<sup>?</sup>
  14
  15 A _use declaration_ creates one or more local name bindings synonymous with
  16 some other [path]. Usually a `use` declaration is used to shorten the path
  17 required to refer to a module item. These declarations may appear in [modules]
  18 and [blocks], usually at the top.
  19
  20 [path]: paths.html
  21 [modules]: items/modules.html
  22 [blocks]: expressions/block-expr.html
  23
  24 > **Note**: Unlike in many languages, `use` declarations in Rust do *not*
  25 > declare linkage dependency with external crates. Rather, [`extern crate`
  26 > declarations](items/extern-crates.html) declare linkage dependencies.
  27
  28 Use declarations support a number of convenient shortcuts:
  29
  30 * Simultaneously binding a list of paths differing only in their final element,
  31   using the glob-like brace syntax `use a::b::{c,d,e,f};`
  32 * Simultaneously binding a list of paths differing only in their final element
  33   and their immediate parent module, using the `self` keyword, such as `use
  34   a::b::{self, c, d};`
  35 * Rebinding the target name as a new local name, using the syntax `use p::q::r
  36   as x;`. This can also be used with the last two features: `use a::b::{self as
  37   ab, c as abc}`.
  38 * Binding all paths matching a given prefix, using the asterisk wildcard syntax
  39   `use a::b::*;`
  40
  41 An example of `use` declarations:
  42
  43 ```rust
  44 use std::option::Option::{Some, None};
  45 use std::collections::hash_map::{self, HashMap};
  46
  47 fn foo<T>(_: T){}
  48 fn bar(map1: HashMap<String, usize>, map2: hash_map::HashMap<String, usize>){}
  49
  50 fn main() {
  51     // Equivalent to 'foo(vec![std::option::Option::Some(1.0f64),
  52     // std::option::Option::None]);'
  53     foo(vec![Some(1.0f64), None]);
  54
  55     // Both `hash_map` and `HashMap` are in scope.
  56     let map1 = HashMap::new();
  57     let map2 = hash_map::HashMap::new();
  58     bar(map1, map2);
  59 }
  60 ```
  61
  62 Like items, `use` declarations are private to the containing module, by
  63 default. Also like items, a `use` declaration can be public, if qualified by
  64 the `pub` keyword. Such a `use` declaration serves to _re-export_ a name. A
  65 public `use` declaration can therefore _redirect_ some public name to a
  66 different target definition: even a definition with a private canonical path,
  67 inside a different module. If a sequence of such redirections form a cycle or
  68 cannot be resolved unambiguously, they represent a compile-time error.
  69
  70 An example of re-exporting:
  71
  72 ```rust
  73 # fn main() { }
  74 mod quux {
  75     pub use quux::foo::{bar, baz};
  76
  77     pub mod foo {
  78         pub fn bar() { }
  79         pub fn baz() { }
  80     }
  81 }
  82 ```
  83
  84 In this example, the module `quux` re-exports two public names defined in
  85 `foo`.
  86
  87 Also note that the paths contained in `use` items are relative to the crate
  88 root. So, in the previous example, the `use` refers to `quux::foo::{bar, baz}`,
  89 and not simply to `foo::{bar, baz}`. This also means that top-level module
  90 declarations should be at the crate root if direct usage of the declared
  91 modules within `use` items is desired. It is also possible to use `self` and
  92 `super` at the beginning of a `use` item to refer to the current and direct
  93 parent modules respectively. All rules regarding accessing declared modules in
  94 `use` declarations apply to both module declarations and `extern crate`
  95 declarations.
  96
  97 An example of what will and will not work for `use` items:
  98
  99 ```rust
 100 # #![allow(unused_imports)]
 101 use foo::baz::foobaz;    // good: foo is at the root of the crate
 102
 103 mod foo {
 104
 105     mod example {
 106         pub mod iter {}
 107     }
 108
 109     use foo::example::iter; // good: foo is at crate root
 110 //  use example::iter;      // bad:  example is not at the crate root
 111     use self::baz::foobaz;  // good: self refers to module 'foo'
 112     use foo::bar::foobar;   // good: foo is at crate root
 113
 114     pub mod bar {
 115         pub fn foobar() { }
 116     }
 117
 118     pub mod baz {
 119         use super::bar::foobar; // good: super refers to module 'foo'
 120         pub fn foobaz() { }
 121     }
 122 }
 123
 124 fn main() {}
 125 ```
 126
 127 [IDENTIFIER]: identifiers.html
 128 [_SimplePath_]: paths.html