names.md

Names

An entity is a language construct that can be referred to in some way within the source program, usually via a path. Entities include types, items, generic parameters, variable bindings, loop labels, lifetimes, fields, attributes, and lints.

A declaration is a syntactical construct that can introduce a name to refer to an entity. Entity names are valid within a scope --- a region of source text where that name may be referenced.

Some entities are explicitly declared in the source code, and some are implicitly declared as part of the language or compiler extensions.

Paths are used to refer to an entity, possibly in another module or type. Lifetimes and loop labels use a dedicated syntax using a leading quote.

Names are segregated into different namespaces, allowing entities in different namespaces to share the same name without conflict.

Name resolution is the compile-time process of tying paths, identifiers, and labels to entity declarations.

Access to certain names may be restricted based on their visibility.

Explicitly declared entities

Entities that explicitly introduce a name in the source code are:

• Items:
  • Module declarations
  • External crate declarations
  • Use declarations
  • Function declarations and function parameters
  • Type aliases
  • struct, union, enum, enum variant declarations, and their named fields
  • Constant item declarations
  • Static item declarations
  • Trait item declarations and their associated items
  • External block items
  • macro_rules declarations and matcher metavariables
  • Implementation associated items
• Expressions:
  • Closure parameters
  • while let pattern bindings
  • for pattern bindings
  • if let pattern bindings
  • match pattern bindings
  • Loop labels
• Generic parameters
• Higher ranked trait bounds
• let statement pattern bindings
• The macro_use attribute can introduce macro names from another crate
• The macro_export attribute can introduce an alias for the macro into the crate root

Additionally, macro invocations and attributes can introduce names by expanding to one of the above items.

Implicitly declared entities

The following entities are implicitly defined by the language, or are introduced by compiler options and extensions:

• Language prelude:
  • Boolean type --- bool
  • Textual types --- char and str
  • Integer types --- i8, i16, i32, i64, i128, u8, u16, u32, u64, u128
  • Machine-dependent integer types --- usize and isize
  • floating-point types --- f32 and f64
• Built-in attributes
• Standard library prelude items, attributes, and macros
• Standard library crates in the root module
• External crates linked by the compiler
• Tool attributes
• Lints and tool lint attributes
• Derive helper attributes are valid within an item without being explicitly imported
• The 'static lifetime

Additionally, the crate root module does not have a name, but can be referred to with certain path qualifiers or aliases.