diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index 5ea891cef2..513ded7019 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -223,6 +223,9 @@ mod example { # fn main() {} ``` +> [!NOTE] +> `self` may also be used as the first segment of a path. The usage of `self` as the first segment and inside a `use` brace is logically the same; it means the current module of the parent segment, or the current module if there is no parent segment. See [`self`] in the paths chapter for more information on the meaning of a leading `self`. + r[items.use.self.namespace] `self` only creates a binding from the [type namespace] of the parent entity. For example, in the following, only the `foo` mod is imported: @@ -242,9 +245,6 @@ fn main() { } ``` -> [!NOTE] -> `self` may also be used as the first segment of a path. The usage of `self` as the first segment and inside a `use` brace is logically the same; it means the current module of the parent segment, or the current module if there is no parent segment. See [`self`] in the paths chapter for more information on the meaning of a leading `self`. - r[items.use.glob] ## Glob imports @@ -367,32 +367,88 @@ m!(use std as _;); r[items.use.restrictions] ## Restrictions -The following are restrictions for valid `use` declarations: +The following rules are restrictions for valid `use` declarations. -r[items.use.restrictions.crate] -* `use crate;` must use `as` to define the name to which to bind the crate root. +r[items.use.restrictions.crate-alias] +When using `crate` to import the current crate, you must use `as` to define the binding name. -r[items.use.restrictions.self] -* `use {self};` is an error; there must be a leading segment when using `self`. +> [!EXAMPLE] +> ```rust +> use crate as root; +> use crate::{self as root2}; +> +> // Not allowed: +> // use crate; +> // use crate::{self}; +> ``` -r[items.use.restrictions.duplicate-name] -* As with any item definition, `use` imports cannot create duplicate bindings of the same name in the same namespace in a module or block. +r[items.use.restrictions.macro-crate-alias] +When using [`$crate`] in a macro transcriber to import the current crate, you must use `as` to define the binding name. + +> [!EXAMPLE] +> ```rust +> macro_rules! import_crate_root { +> () => { +> use $crate as my_crate; +> use $crate::{self as my_crate2}; +> }; +> } +> ``` -r[items.use.restrictions.macro-crate] -* `use` paths with `$crate` are not allowed in a [`macro_rules`] expansion. +r[items.use.restrictions.self-alias] +When using `self` to import the current module, you must use `as` to define the binding name. + +> [!EXAMPLE] +> ```rust +> use {self as this_module}; +> use self as this_module2; +> use self::{self as this_module3}; +> +> // Not allowed: +> // use {self}; +> // use self; +> // use self::{self}; +> ``` + +r[items.use.restrictions.super-alias] +When using `super` to import a parent module, you must use `as` to define the binding name. + +> [!EXAMPLE] +> ```rust +> mod a { +> mod b { +> use super as parent; +> use super::{self as parent2}; +> use super::super as grandparent; +> use super::super::{self as grandparent2}; +> +> // Not allowed: +> // use super; +> // use super::{self}; +> // use super::super; +> // use super::super::{self}; +> } +> } +> ``` + +r[items.use.restrictions.duplicate-name] +As with any item definition, `use` imports cannot create duplicate bindings of the same name in the same namespace in a module or block. r[items.use.restrictions.variant] -* `use` paths cannot refer to enum variants through a [type alias]. For example: - ```rust,compile_fail - enum MyEnum { - MyVariant - } - type TypeAlias = MyEnum; +`use` paths cannot refer to enum variants through a [type alias]. - use MyEnum::MyVariant; //~ OK - use TypeAlias::MyVariant; //~ ERROR - ``` +> [!EXAMPLE] +> ```rust,compile_fail +> enum MyEnum { +> MyVariant +> } +> type TypeAlias = MyEnum; +> +> use MyEnum::MyVariant; //~ OK +> use TypeAlias::MyVariant; //~ ERROR +> ``` +[`$crate`]: paths.qualifiers.macro-crate [Attributes]: ../attributes.md [Built-in types]: ../types.md [Derive macros]: macro.proc.derive diff --git a/src/paths.md b/src/paths.md index d28877d2a5..0c80ff2f4a 100644 --- a/src/paths.md +++ b/src/paths.md @@ -188,6 +188,9 @@ r[paths.qualifiers] Paths can be denoted with various leading qualifiers to change the meaning of how it is resolved. +> [!NOTE] +> [`use` declarations] have additional behaviors and restrictions for `self`, `super`, `crate`, and `$crate`. + r[paths.qualifiers.global-root] ### `::` @@ -486,5 +489,6 @@ mod without { // crate::without [traits]: items/traits.md [types]: types.md [union]: items/unions.md +[`use` declarations]: items/use-declarations.md [value namespace]: names/namespaces.md [visibility]: visibility-and-privacy.md