src/doc/reference/src/paths.md

   1 # Paths
   2
   3 A _path_ is a sequence of one or more path components _logically_ separated by
   4 a namespace qualifier (`::`). If a path consists of only one component, it may
   5 refer to either an [item] or a [variable] in a local control
   6 scope. If a path has multiple components, it refers to an item.
   7
   8 [item]: items.html
   9 [variable]: variables.html
  10
  11 Every item has a _canonical path_ within its crate, but the path naming an item
  12 is only meaningful within a given crate. There is no global namespace across
  13 crates; an item's canonical path merely identifies it within the crate.
  14
  15 Two examples of simple paths consisting of only identifier components:
  16
  17 ```{.ignore}
  18 x;
  19 x::y::z;
  20 ```
  21
  22 Path components are usually [identifiers], but they may
  23 also include angle-bracket-enclosed lists of type arguments. In
  24 [expression] context, the type argument list is given
  25 after a `::` namespace qualifier in order to disambiguate it from a
  26 relational expression involving the less-than symbol (`<`). In type
  27 expression context, the final namespace qualifier is omitted.
  28
  29 [identifiers]: identifiers.html
  30 [expression]: expressions.html
  31
  32 Two examples of paths with type arguments:
  33
  34 ```rust
  35 # struct HashMap<K, V>(K,V);
  36 # fn f() {
  37 # fn id<T>(t: T) -> T { t }
  38 type T = HashMap<i32,String>; // Type arguments used in a type expression
  39 let x  = id::<i32>(10);       // Type arguments used in a call expression
  40 # }
  41 ```
  42
  43 Paths can be denoted with various leading qualifiers to change the meaning of
  44 how it is resolved:
  45
  46 * Paths starting with `::` are considered to be global paths where the
  47   components of the path start being resolved from the crate root. Each
  48   identifier in the path must resolve to an item.
  49
  50 ```rust
  51 mod a {
  52     pub fn foo() {}
  53 }
  54 mod b {
  55     pub fn foo() {
  56         ::a::foo(); // call a's foo function
  57     }
  58 }
  59 # fn main() {}
  60 ```
  61
  62 * Paths starting with the keyword `super` begin resolution relative to the
  63   parent module. Each further identifier must resolve to an item.
  64
  65 ```rust
  66 mod a {
  67     pub fn foo() {}
  68 }
  69 mod b {
  70     pub fn foo() {
  71         super::a::foo(); // call a's foo function
  72     }
  73 }
  74 # fn main() {}
  75 ```
  76
  77 * Paths starting with the keyword `self` begin resolution relative to the
  78   current module. Each further identifier must resolve to an item.
  79
  80 ```rust
  81 fn foo() {}
  82 fn bar() {
  83     self::foo();
  84 }
  85 # fn main() {}
  86 ```
  87
  88 Additionally keyword `super` may be repeated several times after the first
  89 `super` or `self` to refer to ancestor modules.
  90
  91 ```rust
  92 mod a {
  93     fn foo() {}
  94
  95     mod b {
  96         mod c {
  97             fn foo() {
  98                 super::super::foo(); // call a's foo function
  99                 self::super::super::foo(); // call a's foo function
 100             }
 101         }
 102     }
 103 }
 104 # fn main() {}
 105 ```