From 7ef3985a17c3cf793e820bac405f69a86300a39b Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 25 Jan 2026 09:09:27 -0800 Subject: [PATCH 01/11] Remove bullet list from use restrictions As with other parts of the reference, the structure is moving more towards a set of rules, and the bullet list here isn't necessary. --- src/items/use-declarations.md | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index 1afe92ab17..c2fcfe9c31 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -333,31 +333,33 @@ 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. +`use crate;` must use `as` to define the name to which to bind the crate root. r[items.use.restrictions.self] -* `use {self};` is an error; there must be a leading segment when using `self`. +`use {self};` is an error; there must be a leading segment when using `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. +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] -* `use` paths with `$crate` are not allowed in a [`macro_rules`] expansion. +`use` paths with `$crate` are not allowed in a [`macro_rules`] expansion. 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 MyEnum::MyVariant; //~ OK - use TypeAlias::MyVariant; //~ ERROR - ``` +`use` paths cannot refer to enum variants through a [type alias]. + +> [!EXAMPLE] +> ```rust,compile_fail +> enum MyEnum { +> MyVariant +> } +> type TypeAlias = MyEnum; +> +> use MyEnum::MyVariant; //~ OK +> use TypeAlias::MyVariant; //~ ERROR +> ``` [Attributes]: ../attributes.md [Built-in types]: ../types.md From c45d08caf491b55cd3588a9126bad5ddc1e620d3 Mon Sep 17 00:00:00 2001 From: mu001999 Date: Fri, 16 Jan 2026 23:00:48 +0800 Subject: [PATCH 02/11] Document importing path-segment keyword --- src/items/use-declarations.md | 71 +++++++++++++++++++++++++++++++++-- 1 file changed, 68 insertions(+), 3 deletions(-) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index c2fcfe9c31..22ec8e3945 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -170,6 +170,22 @@ Braces can be used in the last segment of the path to import multiple entities f use std::collections::{BTreeSet, hash_map::{self, HashMap}}; ``` +Braces may also import `self` from the current scope when it is explicitly renamed: + +```rust +mod m { + pub fn f() {} + + use {f as local_f, self as this_module}; + + pub fn g() { + local_f(); + this_module::f(); + } +} +# fn main() {} +``` + r[items.use.multiple-syntax.empty] An empty brace does not import anything, though the leading path is validated that it is accessible. @@ -336,16 +352,65 @@ r[items.use.restrictions] 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. +Importing the crate root (`crate`) must use `as` to define the name to which to bind it. + +> [!EXAMPLE] +> ```rust +> use crate as root; +> use crate::{self as root2}; +> +> // Not allowed: +> // use crate; +> // use crate::{self}; +> ``` r[items.use.restrictions.self] -`use {self};` is an error; there must be a leading segment when using `self`. +Importing `self` as an entity must use `as` to define the binding name (this does not affect `self` used within a prefixed brace import like `use a::b::{self, c};`). + +> [!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] +Importing `super` (including repeated `super::super`) as an entity must use `as` to define the binding name (this does not affect importing items from ancestors like `use super::item;`). + +> [!EXAMPLE] +> ```rust +> 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.macro-crate] -`use` paths with `$crate` are not allowed in a [`macro_rules`] expansion. +Within a macro transcriber, `$crate` may be used in `use` paths as the first segment (see `$crate` in the paths chapter). Importing `$crate` as an entity 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.variant] `use` paths cannot refer to enum variants through a [type alias]. From e80245a45cbaa37206e867e1f6ca9bb576312ffc Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 25 Jan 2026 09:13:12 -0800 Subject: [PATCH 03/11] Move `self` note This note was more of a general commentary on `self`, and was not specifically attached to its previous rule of items.use.self.namespace. --- src/items/use-declarations.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index 22ec8e3945..fe6cb97fec 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -216,6 +216,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: @@ -234,9 +237,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 From 5cc8e77ed4136b035836340af1a434de91999f2d Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 25 Jan 2026 09:21:34 -0800 Subject: [PATCH 04/11] Remove this statement about `self` in braces This is somewhat duplicated with the `self` section and the restrictions section which already describes about renaming. --- src/items/use-declarations.md | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index fe6cb97fec..7404faf657 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -170,22 +170,6 @@ Braces can be used in the last segment of the path to import multiple entities f use std::collections::{BTreeSet, hash_map::{self, HashMap}}; ``` -Braces may also import `self` from the current scope when it is explicitly renamed: - -```rust -mod m { - pub fn f() {} - - use {f as local_f, self as this_module}; - - pub fn g() { - local_f(); - this_module::f(); - } -} -# fn main() {} -``` - r[items.use.multiple-syntax.empty] An empty brace does not import anything, though the leading path is validated that it is accessible. From 82e4b294caf85ca180e33e66d6c5b3464d99def8 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 25 Jan 2026 09:22:36 -0800 Subject: [PATCH 05/11] Move items.use.restrictions.macro-crate This moves `$crate` to be next to `crate` since they are closely related. --- src/items/use-declarations.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index 7404faf657..aa3c0cab4a 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -348,6 +348,19 @@ Importing the crate root (`crate`) must use `as` to define the name to which to > // use crate::{self}; > ``` +r[items.use.restrictions.macro-crate] +Within a macro transcriber, `$crate` may be used in `use` paths as the first segment (see `$crate` in the paths chapter). Importing `$crate` as an entity 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.self] Importing `self` as an entity must use `as` to define the binding name (this does not affect `self` used within a prefixed brace import like `use a::b::{self, c};`). @@ -383,19 +396,6 @@ Importing `super` (including repeated `super::super`) as an entity must use `as` 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] -Within a macro transcriber, `$crate` may be used in `use` paths as the first segment (see `$crate` in the paths chapter). Importing `$crate` as an entity 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.variant] `use` paths cannot refer to enum variants through a [type alias]. From 73c1e788167b554c5dea3da51bddf940c5b699a8 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 25 Jan 2026 10:45:11 -0800 Subject: [PATCH 06/11] Tweak wording for `use` restrictions This tries to simplify the wording and to maintain consistency, since they are all essentially saying the same thing. --- src/items/use-declarations.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index aa3c0cab4a..da86effae0 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -335,8 +335,8 @@ r[items.use.restrictions] The following rules are restrictions for valid `use` declarations. -r[items.use.restrictions.crate] -Importing the crate root (`crate`) must use `as` to define the name to which to bind it. +r[items.use.restrictions.crate-alias] +When using `crate` to import the current crate, you must use `as` to define the binding name. > [!EXAMPLE] > ```rust @@ -348,8 +348,8 @@ Importing the crate root (`crate`) must use `as` to define the name to which to > // use crate::{self}; > ``` -r[items.use.restrictions.macro-crate] -Within a macro transcriber, `$crate` may be used in `use` paths as the first segment (see `$crate` in the paths chapter). Importing `$crate` as an entity must use `as` to define the binding name. +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 @@ -361,8 +361,8 @@ Within a macro transcriber, `$crate` may be used in `use` paths as the first seg > } > ``` -r[items.use.restrictions.self] -Importing `self` as an entity must use `as` to define the binding name (this does not affect `self` used within a prefixed brace import like `use a::b::{self, c};`). +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 @@ -376,8 +376,8 @@ Importing `self` as an entity must use `as` to define the binding name (this doe > // use self::{self}; > ``` -r[items.use.restrictions.super] -Importing `super` (including repeated `super::super`) as an entity must use `as` to define the binding name (this does not affect importing items from ancestors like `use super::item;`). +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 @@ -410,6 +410,7 @@ r[items.use.restrictions.variant] > use TypeAlias::MyVariant; //~ ERROR > ``` +[`$crate`]: paths.qualifiers.macro-crate [Attributes]: ../attributes.md [Built-in types]: ../types.md [Derive macros]: macro.proc.derive From c6514b7731867acc4dc9952b2f69ce3a1df855bb Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 25 Jan 2026 10:47:14 -0800 Subject: [PATCH 07/11] Add a note in paths that `use` paths have differences The rules in the paths chapter don't entirely reflect what a valid path in a `use` declaration is. I'm not entirely sure what's the best approach for describing how paths work since there are several differences between `use` paths and expression paths. --- src/paths.md | 4 ++++ 1 file changed, 4 insertions(+) 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 From d543bfad96b8ed1712c3afca40be13ca81293ec1 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 25 Jan 2026 11:00:09 -0800 Subject: [PATCH 08/11] Fix broken example --- src/items/use-declarations.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index da86effae0..a4851dd3f7 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -381,16 +381,20 @@ When using `super` to import a parent module, you must use `as` to define the bi > [!EXAMPLE] > ```rust -> use super as parent; -> use super::{self as parent2}; -> use super::super as grandparent; -> use super::super::{self as grandparent2}; +> 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}; +> // Not allowed: +> // use super; +> // use super::{self}; +> // use super::super; +> // use super::super::{self}; +> } +> } > ``` r[items.use.restrictions.duplicate-name] From 6e7c4f8d6655b3458adbe7bda19654e93c059e35 Mon Sep 17 00:00:00 2001 From: mu001999 Date: Mon, 16 Feb 2026 11:48:21 +0800 Subject: [PATCH 09/11] Add a restriction about extern-prelude --- src/items/use-declarations.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index a4851dd3f7..6821931388 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -397,6 +397,21 @@ When using `super` to import a parent module, you must use `as` to define the bi > } > ``` +r[items.use.restrictions.extern-prelude] +`::` as the [extern prelude] cannot be imported. + +> [!EXAMPLE] +> ```rust,edition2018,compile_fail +> use ::{self as root}; //~ Error +> ``` + +> [!EDITION-2015] +> In edition 2015, `use ::{self as root};` is allowed because it is same as `use crate::{self as root};`. +> +> ```rust,edition2015 +> use ::{self as root}; //~ Ok +> ``` + 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. From 99480154008eeefaf73af8f482316a5bf845958b Mon Sep 17 00:00:00 2001 From: mu001999 Date: Tue, 17 Feb 2026 08:47:56 +0800 Subject: [PATCH 10/11] Refine edition block for `::` Co-authored-by: Eric Huss --- src/items/use-declarations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index 6821931388..3ca1a4d967 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -405,8 +405,8 @@ r[items.use.restrictions.extern-prelude] > use ::{self as root}; //~ Error > ``` -> [!EDITION-2015] -> In edition 2015, `use ::{self as root};` is allowed because it is same as `use crate::{self as root};`. +> [!EDITION-2018] +> In the 2015 edition, the prefix `::` refers to the crate root, so `use ::{self as root};` is allowed because it is same as `use crate::{self as root};`. Starting with the 2018 edition the `::` prefix refers to the extern prelude, which cannot be directly imported. > > ```rust,edition2015 > use ::{self as root}; //~ Ok From f9c4187a206e32d42cf3d024bda7887ea854574c Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Feb 2026 10:52:46 -0800 Subject: [PATCH 11/11] Include self::super in the examples Per what was discussed in https://github.com/rust-lang/rust/pull/146972#issuecomment-3849792716 --- src/items/use-declarations.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index 3ca1a4d967..697472c14f 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -385,12 +385,14 @@ When using `super` to import a parent module, you must use `as` to define the bi > mod b { > use super as parent; > use super::{self as parent2}; +> use self::super as parent3; > use super::super as grandparent; > use super::super::{self as grandparent2}; > > // Not allowed: > // use super; > // use super::{self}; +> // use self::super; > // use super::super; > // use super::super::{self}; > }