14.1. Entities¶

Syntax

Name ::=
    Identifier

Legality Rules

14.1:1 An entity is a construct that can be referred to within program text, usually via a field access expression or a path.

14.1:2 A name is an identifier that refers to an entity.

14.1:3 A declaration is a construct that introduces a name for an entity.

14.1:4 An explicitly declared entity is an entity that has a declaration. The following entities are explicitly declared entities:

• 14.1:5 Associated items,

• 14.1:6 Bindings,

• 14.1:7 Constants,

• 14.1:8 Declarative macros,

• 14.1:9 Enum types,

• 14.1:10 Enum variants,

• 14.1:11 Fields,

• 14.1:12 Functions,

• 14.1:13 Generic parameters,

• 14.1:14 Implementations,

• 14.1:15 Labels,

• 14.1:16 Modules,

• 14.1:17 Statics,

• 14.1:18 Struct types,

• 14.1:19 Traits,

• 14.1:20 Type aliases,

• 14.1:21 Union types.

14.1:22 An implicitly declared entity is an entity that lacks an explicit declaration. The following entities are implicitly declared entities:

• 14.1:23 Built-in attributes.

• 14.1:24 Language prelude entities.

14.2. Visibility¶

Syntax

VisibilityModifier ::=
    CratePublicModifier
  | SelfPublicModifier
  | SimplePathPublicModifier
  | SimplePublicModifier
  | SuperPublicModifier

CratePublicModifier ::=
    pub ( crate )

SelfPublicModifier ::=
    pub ( self )

SimplePathPublicModifier ::=
    pub ( in SimplePath )

SimplePublicModifier ::=
    pub

SuperPublicModifier ::=
    pub ( super )

Legality Rules

14.2:1 Visibility is a property of fields and items that determines which modules can refer to the name of the field or item.

14.2:2 Public visibility is a kind of visibility that allows for a name to be referred to from arbitrary module M as long as the ancestor modules of the related entity can be referred to from M.

14.2:3 Private visibility is a kind of visibility that allows a name to be referred to only by the current module of the entity, and its descendant modules.

14.2:4 A visibility modifier sets the visibility of a name.

14.2:5 A crate public modifier is a visibility modifier that grants a name public visibility within the current crate only.

14.2:6 A self public modifier is a visibility modifier that grants a name private visibility. A self public modifier is equivalent to a simple path public modifier where the simple path denotes keyword self.

14.2:7 A simple path public modifier is a visibility modifier that grants a name public visibility within the provided simple path only.

14.2:8 The simple path of a simple path public modifier shall start with a path segment expressed by either keyword crate, keyword self, or keyword super.

14.2:9 The simple path of a simple path public modifier shall resolve to an ancestor module of the current module or the current module itself.

14.2:10 A simple public modifier is a visibility modifier that grants a name public visibility.

14.2:11 A super public modifier is a visibility modifier that grants a name public visibility within the parent module only. A super public modifier is equivalent to a simple path public modifier where the simple path denotes keyword super.

14.2:12 An external item, a field, or an item that appears without a visibility modifier has private visibility by default.

14.2:13 An associated item of a trait has the same visibility as the trait.

14.2:14 An enum variant and its fields have the same visibility as the containing enum type.

Examples

pub mod outer_module {
    pub mod inner_module {
        pub(crate) fn crate_visible_function() {}

        pub(self) fn inner_module_visible_function() {}

        pub(super) fn outer_module_visible_function() {}

        pub fn visible_function() {}

        fn caller() {
            crate_visible_function();
            inner_module_visible_function();
            visible_function();
        }
    }

    fn caller() {
        inner_module::crate_visible_function();
        inner_module::outer_module_visible_function();
        inner_module::visible_function();
    }
}

fn caller() {
    outer_module::inner_module::crate_visible_function();
    outer_module::inner_module::visible_function();
}

14.3. Paths¶

Syntax

SimplePath ::=
    ::? SimplePathSegment (:: SimplePathSegment)*

SimplePathSegment ::=
    Identifier
  | crate
  | $crate
  | self
  | super

SimplePathList ::=
    SimplePath (, SimplePath)* ,?

QualifiedType ::=
    < TypeSpecification QualifyingTrait? >

QualifyingTrait ::=
    as TypePath

UnqualifiedPathExpression ::=
    ::? PathExpressionSegment (:: PathExpressionSegment)*

PathExpressionSegment ::=
    PathSegment (:: GenericArgumentList)?

PathSegment ::=
    SimplePathSegment
  | Self

QualifiedPathExpression ::=
    QualifiedType (:: PathExpressionSegment)+

TypePath ::=
    ::? TypePathSegment (:: TypePathSegment)*

TypePathSegment ::=
    PathSegment ::? (GenericArgumentList | QualifiedFnTrait)?

QualifiedFnTrait ::=
    ( TypeSpecificationList? ) ReturnType?

QualifiedTypePath ::=
    QualifiedType (:: TypePathSegment)+

Legality Rules

14.3:1 A path is a sequence of path segments logically separated by namespace qualifier :: that resolves to an entity.

14.3:2 A path segment is an element of a path.

14.3:3 A path is subject to path resolution.

14.3:4 If a path segment is expressed as either keyword crate, keyword $crate, keyword self, or keyword Self, then the path segment shall be the first path segment of a path.

14.3:5 A path that starts with a path segment that is expressed as keyword $crate shall appear only within a macro transcriber.

14.3:6 If a path segment is expressed as keyword super, then the path segment shall either be the first path segment of a path, or the previous path segment of the path shall also be expressed as keyword super.

14.3:7 A global path is a path that starts with namespace qualifier ::.

14.3:8 A simple path is a path whose path segments consist of either identifiers or certain keywords as defined in the syntax rules above.

14.3:9 A path prefix is a path with its last path segment and namespace qualifier :: stripped.

14.3:10 If a simple path appears in a use import and starts with a path segment expressed as either keyword crate, keyword $crate, keyword self, or keyword super, then the path shall be the simple path prefix of a glob import or a nesting import, or the simple path of a simple import.

14.3:11 If a simple path appears in a use import and starts with a path segment expressed as keyword self, then the path shall be part of the UseImportContent of a nesting import as long as the path is a single segment path.

14.3:12 A simple path is subject to simple path resolution.

14.3:13 A single segment path is a path consisting of exactly one path segment.

14.3:14 A multi segment path is a path consisting of more than one path segment.

14.3:15 An unqualified path expression is a path expression without a qualified type.

14.3:16 A path expression is subject to path expression resolution.

14.3:17 A type path is a path that acts as a type specification.

14.3:18 A type path is subject to type path resolution.

14.3:19 A qualifying trait is a trait that imposes a restriction on a qualified type.

14.3:20 A qualifying trait shall resolve to a trait.

14.3:21 A qualified type is a type that is restricted to a set of implementations that exhibit implementation conformance to a qualifying trait.

14.3:22 A qualified type shall resolve to a type.

14.3:23 A qualified type shall implement its related qualifying trait.

14.3:24 A qualified path expression is a path expression that resolves through a qualified type.

14.3:25 A qualified type path is a type path that resolves through a qualified type.

14.3:26 An associated type projection is a qualified type path of the form <type as trait>::associated_type, where type is a type, trait is a qualifying trait, and associated type is an associated type.

14.3:27 A qualified fn trait is a construct that refers to the core::ops::Fn, core::ops::FnMut, or core::ops::FnOnce trait.

14.3:28 If a path contains a path segment with a qualified fn trait, then the path segment shall be the last path segment of the path.

Examples

14.3:29 The following is a simple path. See Paragraph 14.2. for the declaration of crate_visible_function.

crate::outer_module::inner_module::crate_visible_function();

14.3:30 The following is an unqualified path expression` with a generic argument.

Vec::<u8>::with_capacity(42);

14.3:31 The following is a type path with a generic argument.

std::boxed::Box<dyn std::ops::FnOnce(isize) -> size>;

struct S;
impl S {
    fn f() { println!("f of S"); }
}
trait T {
    fn f() { println!("f of T"); }
}
impl T for S {}

14.3:32 The following is a qualified path expression. The call expression invokes the associated function of S’s trait implementation of trait T.

<S as T>::f();

14.3:33 The following is a qualified type path. It resolves to the associated type of S’s trait implementation of trait T.

type T = <S as T>::Assoc;

14.4. Scopes¶

Legality Rules

14.4:1 A scope is a region of program text where an entity can be referred to. An entity is in scope when it can be referred to.

14.5. Namespaces¶

Legality Rules

14.5:1 A namespace is a logical grouping of names such that the occurrence of a name in one namespace does not conflict with an occurrence of the same name in another namespace.

14.5:2 Names are segregated into one of five namespaces based on the kind of entity the name refers to.

14.5:3 A label namespace contains labels.

14.5:4 A lifetime namespace contains the names of lifetime parameters.

14.5:5 A macro namespace contains the names of the following kinds of entities:

• 14.5:6 Attribute macros,

• 14.5:7 Built-in attributes,

• 14.5:8 Declarative macros,

• 14.5:9 Derive macros,

• 14.5:10 Function-like macros.

14.5:11 A type namespace contains the names of the following kinds of entities:

• 14.5:12 Associated types,

• 14.5:13 bool types,

• 14.5:14 Enum types,

• 14.5:15 Enum variants,

• 14.5:16 Modules,

• 14.5:17 Numeric types,

• 14.5:18 Self,

• 14.5:19 Struct types,

• 14.5:20 Textual types,

• 14.5:21 Traits,

• 14.5:22 Type aliases,

• 14.5:23 Type parameters,

• 14.5:24 Union types.

14.5:25 A value namespace contains the names of the following kinds of entities:

• 14.5:26 Associated constants,

• 14.5:27 Associated functions,

• 14.5:28 Bindings,

• 14.5:29 Constants,

• 14.5:30 Constant parameters,

• 14.5:31 Enum variant constructors,

• 14.5:32 Functions,

• 14.5:33 Self constructors,

• 14.5:34 Statics,

• 14.5:35 Struct constructors.

14.5:36 The names of the following kinds of entities are not part of any namespace:

• 14.5:37 Enum fields,

• 14.5:38 Struct fields,

• 14.5:39 Union fields.

14.6. Preludes¶

Legality Rules

14.6:1 A prelude is a collection of entities that are automatically brought in scope of every module in a crate. Such entities are referred to as prelude entities. The name of a prelude entity is referred to as a prelude name.

14.6:2 The core prelude is a prelude that brings in scope of every module all re-exported entities from the core::prelude::rust_2021 module.

14.6:3 An external prelude is a prelude that brings in scope of the crate root module the entities of the crates imported using external crate imports or supplied by a tool. If the external crate import uses a renaming, then the identifier of the renaming is instead added to the external prelude. The core crate is always added to the external prelude unless the crate root is subject to attribute no_core.

14.6:4 The language prelude is a prelude that brings in scope of every module the following entities:

• 14.6:5 Boolean type bool.

• 14.6:6 Built-in attributes.

• 14.6:7 Floating-point types f32 and f64.

• 14.6:8 Integer types i8, i16, i32, i64, i128, isize, u8, u16, u32, u64, u128, and usize.

• 14.6:9 Textual types char and str.

14.6:10 The macro_use prelude is a prelude that brings in scope of the crate root module the entities of macros from external crates that were imported using an external crate import.

14.7. Use Imports¶

Syntax

UseImport ::=
    use UseImportContent ;

UseImportContent ::=
    GlobImport
  | NestingImport
  | SimpleImport

GlobImport ::=
    SimplePathPrefix? *

NestingImport ::=
    SimplePathPrefix? { UseImportContentList? }

SimpleImport ::=
    SimplePath Renaming?

SimplePathPrefix ::=
    SimplePath? ::

UseImportContentList ::=
    UseImportContent (, UseImportContent)* ,?

Legality Rules

14.7:1 A use import brings entities in scope within the block expression of an expression-with-block or module where the use import resides.

14.7:2 A simple path prefix is the leading simple path of a glob import or a nesting import.

14.7:3 An import path prefix is the fully constructed path prefix of a use import. An import path prefix for a given simple import or glob import is constructed as follows:

1. 14.7:4 Start the import path prefix as follows:

   • 14.7:5 If the use import is a simple import then start with the path segments of the simple import‘s simple path path prefix.

   • 14.7:6 If the use import is a glob import then start with the path segments of the glob import‘s simple path prefix.

   • 14.7:7 If the use import is a nesting import then start with the path segments of the nesting import‘s simple path prefix.

2. 14.7:8 Then if the current use import is the child of a nesting import, prepend the nesting import‘s simple path prefix to the import path prefix. Repeat this step with the nesting import as the current use import.

14.7:9 A simple import is a use import that brings all entities it refers to into scope, optionally with a different name than they are declared with by using a renaming.

14.7:10 A glob import is a use import that brings all entities exported by the module or enum its import path prefix resolves to into scope.

14.7:11 An import path prefix shall resolve to a module or enum.

14.7:12 A glob import brings names into scope as follows:

• 14.7:13 If the import path prefix resolves to a module, bring all names in the module that are visible from the location of the glob import into scope.

• 14.7:14 If the import path prefix resolves to an enum, bring the names of all of the enum‘s enum variants into scope.

14.7:15 A simple import path is the path constructed by appending the last path segment of a simple import‘s simple path to the import path prefix.

14.7:16 A simple import brings names into scope as follows:

• 14.7:17 If the simple path is keyword self and:

  • 14.7:18 The simple import is in a nesting import, then bring the entity in type namespace that the import path prefix resolves to into scope.

  • 14.7:19 Otherwise bring the containing module into scope.

• 14.7:20 Otherwise bring all entities that the simple import path resolves to that are visible from the location of the simple import into scope.

14.7:21 An Entity imported by a simple import subject to a renaming with identifier is brought into scope under the name declared by the renaming.

14.7:22 A trait imported by a simple import subject to a renaming with character underscore _ is added into scope without a name.

14.7:23 A nesting import is a use import that provides a common simple path prefix for its nested use imports.

14.7:24 A glob import outside of a nesting import without a simple path prefix is rejected, but may still be consumed by macros.

14.7:25 A simple import with a simple path with a single path segment of keyword self shall be subject to the following:

• 14.7:26 It shall either appear in a nesting import with a non-empty import path prefix, or

• 14.7:27 It shall be subject to a renaming.

14.7:28 It is a static error if two glob imports import the same name in the same namespace but refer to different entities if the name is used or shadowed.

14.7:29 If two glob imports import the same entity under the same name, the visibility of the name is the most permissive one.

Examples

14.7:30 The following is a glob import. See Paragraph 14.2. for the declaration of modules and functions. The imported functions are create_visible_function, outer_module_visible_function, visible_function.

use outer_module::inner_module::*;

14.7:31 The following is a renaming import. The imported function is visible_function under the name f.

use outer_module::inner_module::visible_function as f;

14.7:32 The following is a selective import. The imported functions are crate_visible_function and visible_function.

use outer_module::inner_module
    {crate_visible_function, visible_function}

Legality Rules

14.8. Shadowing¶

Legality Rules

14.8:1 Shadowing is a property of names. A name is said to be shadowed when another name with the same characters is introduced in the same scope within the same namespace, effectively hiding it. A name cannot be referred to by any means once it is shadowed.

14.8:2 No name shall be shadowed except for

• 14.8:3 Prelude names,

• 14.8:4 The names of macros within textual macro scope,

• 14.8:5 The names of variables.

14.8:6 A prelude name shadows other prelude names depending on which preludes are included in a module. The order of shadowing is as follows, where a later prelude name shadows earlier prelude name:

1. 14.8:7 Language prelude names.

2. 14.8:8 Standard library prelude names.

3. 14.8:9 macro_use prelude names.

4. 14.8:10 Tool prelude names.

5. 14.8:11 External prelude names.

14.9. Resolution¶

Legality Rules

14.9:1 Resolution is the process of finding a unique interpretation for a field access expression, a method call expression, a call expression or a path.

14.9:2 A construct that is being resolved is said to be under resolution.

14.9:3 A dereference type is either a reference type or a type that implements the core::ops::Deref trait.

14.9:4 A dereference type chain is a sequence of dereference types. A dereference type chain starts with an initial dereference type. From then on, the dereference type chain continues as follows:

• 14.9:5 If the previous dereference type is a reference type, then the dereference type chain continues with the inner type of the previous dereference type.

• 14.9:6 Otherwise the dereference type chain continues with type core::ops::Deref::Target of the previous dereference type.