]>
Commit | Line | Data |
---|---|---|
5869c6ff XL |
1 | # Namespaces |
2 | ||
3 | A *namespace* is a logical grouping of declared [names]. Names are segregated | |
4 | into separate namespaces based on the kind of entity the name refers to. | |
5 | Namespaces allow the occurrence of a name in one namespace to not conflict | |
6 | with the same name in another namespace. | |
7 | ||
8 | Within a namespace, names are organized in a hierarchy, where each level of | |
9 | the hierarchy has its own collection of named entities. | |
10 | ||
11 | There are several different namespaces that each contain different kinds of | |
12 | entities. The usage of a name will look for the declaration of that name in | |
13 | different namespaces, based on the context, as described in the [name | |
14 | resolution] chapter. | |
15 | ||
16 | The following is a list of namespaces, with their corresponding entities: | |
17 | ||
18 | * Type Namespace | |
19 | * [Module declarations] | |
20 | * [External crate declarations] | |
21 | * [External crate prelude] items | |
22 | * [Struct], [union], [enum], enum variant declarations | |
23 | * [Trait item declarations] | |
24 | * [Type aliases] | |
25 | * [Associated type declarations] | |
26 | * Built-in types: [boolean], [numeric], and [textual] | |
27 | * [Generic type parameters] | |
28 | * [`Self` type] | |
29 | * [Tool attribute modules] | |
30 | * Value Namespace | |
31 | * [Function declarations] | |
32 | * [Constant item declarations] | |
33 | * [Static item declarations] | |
34 | * [Struct constructors] | |
35 | * [Enum variant constructors] | |
36 | * [`Self` constructors] | |
37 | * [Generic const parameters] | |
38 | * [Associated const declarations] | |
39 | * [Associated function declarations] | |
40 | * Local bindings — [`let`], [`if let`], [`while let`], [`for`], [`match`] | |
41 | arms, [function parameters], [closure parameters] | |
42 | * Captured [closure] variables | |
43 | * Macro Namespace | |
44 | * [`macro_rules` declarations] | |
45 | * [Built-in attributes] | |
46 | * [Tool attributes] | |
47 | * [Function-like procedural macros] | |
48 | * [Derive macros] | |
49 | * [Derive macro helpers] | |
50 | * [Attribute macros] | |
51 | * Lifetime Namespace | |
52 | * [Generic lifetime parameters] | |
923072b8 | 53 | * Label Namespace |
5869c6ff XL |
54 | * [Loop labels] |
55 | ||
56 | An example of how overlapping names in different namespaces can be used unambiguously: | |
57 | ||
58 | ```rust | |
59 | // Foo introduces a type in the type namespace and a constructor in the value | |
60 | // namespace. | |
61 | struct Foo(u32); | |
62 | ||
63 | // The `Foo` macro is declared in the macro namespace. | |
64 | macro_rules! Foo { | |
65 | () => {}; | |
66 | } | |
67 | ||
68 | // `Foo` in the `f` parameter type refers to `Foo` in the type namespace. | |
69 | // `'Foo` introduces a new lifetime in the lifetime namespace. | |
70 | fn example<'Foo>(f: Foo) { | |
71 | // `Foo` refers to the `Foo` constructor in the value namespace. | |
72 | let ctor = Foo; | |
73 | // `Foo` refers to the `Foo` macro in the macro namespace. | |
74 | Foo!{} | |
75 | // `'Foo` introduces a label in the label namespace. | |
76 | 'Foo: loop { | |
77 | // `'Foo` refers to the `'Foo` lifetime parameter, and `Foo` | |
78 | // refers to the type namespace. | |
79 | let x: &'Foo Foo; | |
80 | // `'Foo` refers to the label. | |
81 | break 'Foo; | |
82 | } | |
83 | } | |
84 | ``` | |
85 | ||
86 | ## Named entities without a namespace | |
87 | ||
88 | The following entities have explicit names, but the names are not a part of | |
89 | any specific namespace. | |
90 | ||
91 | ### Fields | |
92 | ||
93 | Even though struct, enum, and union fields are named, the named fields do not | |
94 | live in an explicit namespace. They can only be accessed via a [field | |
95 | expression], which only inspects the field names of the specific type being | |
96 | accessed. | |
97 | ||
98 | ### Use declarations | |
99 | ||
100 | A [use declaration] has named aliases that it imports into scope, but the | |
101 | `use` item itself does not belong to a specific namespace. Instead, it can | |
102 | introduce aliases into multiple namespaces, depending on the item kind being | |
103 | imported. | |
104 | ||
105 | <!-- TODO: describe how `use` works on the use-declarations page, and link to it here. --> | |
106 | ||
136023e0 XL |
107 | ## Sub-namespaces |
108 | ||
109 | The macro namespace is split into two sub-namespaces: one for [bang-style macros] and one for [attributes]. | |
110 | When an attribute is resolved, any bang-style macros in scope will be ignored. | |
111 | And conversely resolving a bang-style macro will ignore attribute macros in scope. | |
112 | This prevents one style from shadowing another. | |
113 | ||
114 | For example, the [`cfg` attribute] and the [`cfg` macro] are two different entities with the same name in the macro namespace, but they can still be used in their respective context. | |
115 | ||
116 | It is still an error for a [`use` import] to shadow another macro, regardless of their sub-namespaces. | |
117 | ||
136023e0 XL |
118 | [`cfg` attribute]: ../conditional-compilation.md#the-cfg-attribute |
119 | [`cfg` macro]: ../conditional-compilation.md#the-cfg-macro | |
5869c6ff XL |
120 | [`for`]: ../expressions/loop-expr.md#iterator-loops |
121 | [`if let`]: ../expressions/if-expr.md#if-let-expressions | |
122 | [`let`]: ../statements.md#let-statements | |
123 | [`macro_rules` declarations]: ../macros-by-example.md | |
124 | [`match`]: ../expressions/match-expr.md | |
125 | [`Self` constructors]: ../paths.md#self-1 | |
126 | [`Self` type]: ../paths.md#self-1 | |
136023e0 | 127 | [`use` import]: ../items/use-declarations.md |
5869c6ff XL |
128 | [`while let`]: ../expressions/loop-expr.md#predicate-pattern-loops |
129 | [Associated const declarations]: ../items/associated-items.md#associated-constants | |
130 | [Associated function declarations]: ../items/associated-items.md#associated-functions-and-methods | |
131 | [Associated type declarations]: ../items/associated-items.md#associated-types | |
132 | [Attribute macros]: ../procedural-macros.md#attribute-macros | |
136023e0 XL |
133 | [attributes]: ../attributes.md |
134 | [bang-style macros]: ../macros.md | |
5869c6ff XL |
135 | [boolean]: ../types/boolean.md |
136 | [Built-in attributes]: ../attributes.md#built-in-attributes-index | |
137 | [closure parameters]: ../expressions/closure-expr.md | |
138 | [closure]: ../expressions/closure-expr.md | |
139 | [Constant item declarations]: ../items/constant-items.md | |
140 | [Derive macro helpers]: ../procedural-macros.md#derive-macro-helper-attributes | |
141 | [Derive macros]: ../procedural-macros.md#derive-macros | |
142 | [entity]: ../glossary.md#entity | |
143 | [Enum variant constructors]: ../items/enumerations.md | |
144 | [enum]: ../items/enumerations.md | |
145 | [External crate declarations]: ../items/extern-crates.md | |
146 | [External crate prelude]: preludes.md#extern-prelude | |
147 | [field expression]: ../expressions/field-expr.md | |
148 | [Function declarations]: ../items/functions.md | |
149 | [function parameters]: ../items/functions.md#function-parameters | |
150 | [Function-like procedural macros]: ../procedural-macros.md#function-like-procedural-macros | |
151 | [Generic const parameters]: ../items/generics.md#const-generics | |
152 | [Generic lifetime parameters]: ../items/generics.md | |
153 | [Generic type parameters]: ../items/generics.md | |
154 | [Loop labels]: ../expressions/loop-expr.md#loop-labels | |
155 | [Module declarations]: ../items/modules.md | |
156 | [name resolution]: name-resolution.md | |
157 | [names]: ../names.md | |
158 | [numeric]: ../types/numeric.md | |
159 | [Static item declarations]: ../items/static-items.md | |
160 | [Struct constructors]: ../items/structs.md | |
161 | [Struct]: ../items/structs.md | |
162 | [textual]: ../types/textual.md | |
163 | [Tool attribute modules]: ../attributes.md#tool-attributes | |
164 | [Tool attributes]: ../attributes.md#tool-attributes | |
165 | [Trait item declarations]: ../items/traits.md | |
166 | [Type aliases]: ../items/type-aliases.md | |
167 | [union]: ../items/unions.md | |
168 | [use declaration]: ../items/use-declarations.md |