src/doc/reference/src/glossary.md

   1 # Glossary
   2
   3 ### Abstract syntax tree
   4
   5 An ‘abstract syntax tree’, or ‘AST’, is an intermediate representation of
   6 the structure of the program when the compiler is compiling it.
   7
   8 ### Alignment
   9
  10 The alignment of a value specifies what addresses values are preferred to
  11 start at. Always a power of two. References to a value must be aligned.
  12 [More][alignment].
  13
  14 ### Arity
  15
  16 Arity refers to the number of arguments a function or operator takes.
  17 For some examples, `f(2, 3)` and `g(4, 6)` have arity 2, while `h(8, 2, 6)`
  18 has arity 3. The `!` operator has arity 1.
  19
  20 ### Array
  21
  22 An array, sometimes also called a fixed-size array or an inline array, is a value
  23 describing a collection of elements, each selected by an index that can be computed
  24 at run time by the program. It occupies a contiguous region of memory.
  25
  26 ### Associated item
  27
  28 An associated item is an item that is associated with another item. Associated
  29 items are defined in [implementations] and declared in [traits]. Only
  30 functions, constants, and type aliases can be associated. Contrast to a [free
  31 item].
  32
  33 ### Blanket implementation
  34
  35 Any implementation where a type appears [uncovered](#uncovered-type). `impl<T> Foo
  36 for T`, `impl<T> Bar<T> for T`, `impl<T> Bar<Vec<T>> for T`, and `impl<T> Bar<T>
  37 for Vec<T>` are considered blanket impls. However, `impl<T> Bar<Vec<T>> for
  38 Vec<T>` is not a blanket impl, as all instances of `T` which appear in this `impl`
  39 are covered by `Vec`.
  40
  41 ### Bound
  42
  43 Bounds are constraints on a type or trait. For example, if a bound
  44 is placed on the argument a function takes, types passed to that function
  45 must abide by that constraint.
  46
  47 ### Combinator
  48
  49 Combinators are higher-order functions that apply only functions and
  50 earlier defined combinators to provide a result from its arguments.
  51 They can be used to manage control flow in a modular fashion.
  52
  53 ### Crate
  54
  55 A crate is the unit of compilation and linking. There are different [types of
  56 crates], such as libraries or executables. Crates may link and refer to other
  57 library crates, called external crates. A crate has a self-contained tree of
  58 [modules], starting from an unnamed root module called the crate root. [Items]
  59 may be made visible to other crates by marking them as public in the crate
  60 root, including through [paths] of public modules.
  61 [More][crate].
  62
  63 ### Dispatch
  64
  65 Dispatch is the mechanism to determine which specific version of code is actually
  66 run when it involves polymorphism. Two major forms of dispatch are static dispatch and
  67 dynamic dispatch. While Rust favors static dispatch, it also supports dynamic dispatch
  68 through a mechanism called ‘trait objects’.
  69
  70 ### Dynamically sized type
  71
  72 A dynamically sized type (DST) is a type without a statically known size or alignment.
  73
  74 ### Entity
  75
  76 An [*entity*] is a language construct that can be referred to in some way
  77 within the source program, usually via a [path][paths]. Entities include
  78 [types], [items], [generic parameters], [variable bindings], [loop labels],
  79 [lifetimes], [fields], [attributes], and [lints].
  80
  81 ### Expression
  82
  83 An expression is a combination of values, constants, variables, operators
  84 and functions that evaluate to a single value, with or without side-effects.
  85
  86 For example, `2 + (3 * 4)` is an expression that returns the value 14.
  87
  88 ### Free item
  89
  90 An [item] that is not a member of an [implementation], such as a *free
  91 function* or a *free const*. Contrast to an [associated item].
  92
  93 ### Fundamental traits
  94
  95 A fundamental trait is one where adding an impl of it for an existing type is a breaking change.
  96 The `Fn` traits and `Sized` are fundamental.
  97
  98 ### Fundamental type constructors
  99
 100 A fundamental type constructor is a type where implementing a [blanket implementation](#blanket-implementation) over it
 101 is a breaking change. `&`, `&mut`, `Box`, and `Pin`  are fundamental.
 102
 103 Any time a type `T` is considered [local](#local-type), `&T`, `&mut T`, `Box<T>`, and `Pin<T>`
 104 are also considered local. Fundamental type constructors cannot [cover](#uncovered-type) other types.
 105 Any time the term "covered type" is used,
 106 the `T` in `&T`, `&mut T`, `Box<T>`, and `Pin<T>` is not considered covered.
 107
 108 ### Inhabited
 109
 110 A type is inhabited if it has constructors and therefore can be instantiated. An inhabited type is
 111 not "empty" in the sense that there can be values of the type. Opposite of
 112 [Uninhabited](#uninhabited).
 113
 114 ### Inherent implementation
 115
 116 An [implementation] that applies to a nominal type, not to a trait-type pair.
 117 [More][inherent implementation].
 118
 119 ### Inherent method
 120
 121 A [method] defined in an [inherent implementation], not in a trait
 122 implementation.
 123
 124 ### Initialized
 125
 126 A variable is initialized if it has been assigned a value and hasn't since been
 127 moved from. All other memory locations are assumed to be uninitialized. Only
 128 unsafe Rust can create such a memory without initializing it.
 129
 130 ### Local trait
 131
 132 A `trait` which was defined in the current crate. A trait definition is local
 133 or not independent of applied type arguments. Given `trait Foo<T, U>`,
 134 `Foo` is always local, regardless of the types substituted for `T` and `U`.
 135
 136 ### Local type
 137
 138 A `struct`, `enum`, or `union` which was defined in the current crate.
 139 This is not affected by applied type arguments. `struct Foo` is considered local, but
 140 `Vec<Foo>` is not. `LocalType<ForeignType>` is local. Type aliases do not
 141 affect locality.
 142
 143 ### Module
 144
 145 A module is a container for zero or more [items]. Modules are organized in a
 146 tree, starting from an unnamed module at the root called the crate root or the
 147 root module. [Paths] may be used to refer to items from other modules, which
 148 may be restricted by [visibility rules].
 149 [More][modules]
 150
 151 ### Name
 152
 153 A [*name*] is an [identifier] or [lifetime or loop label] that refers to an
 154 [entity](#entity). A *name binding* is when an entity declaration introduces
 155 an identifier or label associated with that entity. [Paths],
 156 identifiers, and labels are used to refer to an entity.
 157
 158 ### Name resolution
 159
 160 [*Name resolution*] is the compile-time process of tying [paths],
 161 [identifiers], and [labels] to [entity](#entity) declarations.
 162
 163 ### Namespace
 164
 165 A *namespace* is a logical grouping of declared [names](#name) based on the
 166 kind of [entity](#entity) the name refers to. Namespaces allow the occurrence
 167 of a name in one namespace to not conflict with the same name in another
 168 namespace.
 169
 170 Within a namespace, names are organized in a hierarchy, where each level of
 171 the hierarchy has its own collection of named entities.
 172
 173 ### Nominal types
 174
 175 Types that can be referred to by a path directly. Specifically [enums],
 176 [structs], [unions], and [trait objects].
 177
 178 ### Object safe traits
 179
 180 [Traits] that can be used as [trait objects]. Only traits that follow specific
 181 [rules][object safety] are object safe.
 182
 183 ### Path
 184
 185 A [*path*] is a sequence of one or more path segments used to refer to an
 186 [entity](#entity) in the current scope or other levels of a
 187 [namespace](#namespace) hierarchy.
 188
 189 ### Prelude
 190
 191 Prelude, or The Rust Prelude, is a small collection of items - mostly traits - that are
 192 imported into every module of every crate. The traits in the prelude are pervasive.
 193
 194 ### Scope
 195
 196 A [*scope*] is the region of source text where a named [entity](#entity) may
 197 be referenced with that name.
 198
 199 ### Scrutinee
 200
 201 A scrutinee is the expression that is matched on in `match` expressions and
 202 similar pattern matching constructs. For example, in `match x { A => 1, B => 2 }`,
 203 the expression `x` is the scrutinee.
 204
 205 ### Size
 206
 207 The size of a value has two definitions.
 208
 209 The first is that it is how much memory must be allocated to store that value.
 210
 211 The second is that it is the offset in bytes between successive elements in an
 212 array with that item type.
 213
 214 It is a multiple of the alignment, including zero. The size can change
 215 depending on compiler version (as new optimizations are made) and target
 216 platform (similar to how `usize` varies per-platform).
 217
 218 [More][alignment].
 219
 220 ### Slice
 221
 222 A slice is dynamically-sized view into a contiguous sequence, written as `[T]`.
 223
 224 It is often seen in its borrowed forms, either mutable or shared. The shared
 225 slice type is `&[T]`, while the mutable slice type is `&mut [T]`, where `T` represents
 226 the element type.
 227
 228 ### Statement
 229
 230 A statement is the smallest standalone element of a programming language
 231 that commands a computer to perform an action.
 232
 233 ### String literal
 234
 235 A string literal is a string stored directly in the final binary, and so will be
 236 valid for the `'static` duration.
 237
 238 Its type is `'static` duration borrowed string slice, `&'static str`.
 239
 240 ### String slice
 241
 242 A string slice is the most primitive string type in Rust, written as `str`. It is
 243 often seen in its borrowed forms, either mutable or shared. The shared
 244 string slice type is `&str`, while the mutable string slice type is `&mut str`.
 245
 246 Strings slices are always valid UTF-8.
 247
 248 ### Trait
 249
 250 A trait is a language item that is used for describing the functionalities a type must provide.
 251 It allows a type to make certain promises about its behavior.
 252
 253 Generic functions and generic structs can use traits to constrain, or bound, the types they accept.
 254
 255 ### Turbofish
 256
 257 Paths with generic parameters in expressions must prefix the opening brackets with a `::`.
 258 Combined with the angular brackets for generics, this looks like a fish `::<>`.
 259 As such, this syntax is colloquially referred to as turbofish syntax.
 260
 261 Examples:
 262
 263 ```rust
 264 let ok_num = Ok::<_, ()>(5);
 265 let vec = [1, 2, 3].iter().map(|n| n * 2).collect::<Vec<_>>();
 266 ```
 267
 268 This `::` prefix is required to disambiguate generic paths with multiple comparisons in a comma-separate list.
 269 See [the bastion of the turbofish][turbofish test] for an example where not having the prefix would be ambiguous.
 270
 271 ### Uncovered type
 272
 273 A type which does not appear as an argument to another type. For example,
 274 `T` is uncovered, but the `T` in `Vec<T>` is covered. This is only relevant for
 275 type arguments.
 276
 277 ### Undefined behavior
 278
 279 Compile-time or run-time behavior that is not specified. This may result in,
 280 but is not limited to: process termination or corruption; improper, incorrect,
 281 or unintended computation; or platform-specific results.
 282 [More][undefined-behavior].
 283
 284 ### Uninhabited
 285
 286 A type is uninhabited if it has no constructors and therefore can never be instantiated. An
 287 uninhabited type is "empty" in the sense that there are no values of the type. The canonical
 288 example of an uninhabited type is the [never type] `!`, or an enum with no variants
 289 `enum Never { }`. Opposite of [Inhabited](#inhabited).
 290
 291 [alignment]: type-layout.md#size-and-alignment
 292 [associated item]: #associated-item
 293 [attributes]: attributes.md
 294 [*entity*]: names.md
 295 [crate]: crates-and-source-files.md
 296 [enums]: items/enumerations.md
 297 [fields]: expressions/field-expr.md
 298 [free item]: #free-item
 299 [generic parameters]: items/generics.md
 300 [identifier]: identifiers.md
 301 [identifiers]: identifiers.md
 302 [implementation]: items/implementations.md
 303 [implementations]: items/implementations.md
 304 [inherent implementation]: items/implementations.md#inherent-implementations
 305 [item]: items.md
 306 [items]: items.md
 307 [labels]: tokens.md#lifetimes-and-loop-labels
 308 [lifetime or loop label]: tokens.md#lifetimes-and-loop-labels
 309 [lifetimes]: tokens.md#lifetimes-and-loop-labels
 310 [lints]: attributes/diagnostics.md#lint-check-attributes
 311 [loop labels]: tokens.md#lifetimes-and-loop-labels
 312 [method]: items/associated-items.md#methods
 313 [modules]: items/modules.md
 314 [*Name resolution*]: names/name-resolution.md
 315 [*name*]: names.md
 316 [*namespace*]: names/namespaces.md
 317 [never type]: types/never.md
 318 [object safety]: items/traits.md#object-safety
 319 [*path*]: paths.md
 320 [Paths]: paths.md
 321 [*scope*]: names/scopes.md
 322 [structs]: items/structs.md
 323 [trait objects]: types/trait-object.md
 324 [traits]: items/traits.md
 325 [turbofish test]: https://github.com/rust-lang/rust/blob/master/src/test/ui/bastion-of-the-turbofish.rs
 326 [types of crates]: linkage.md
 327 [types]: types.md
 328 [undefined-behavior]: behavior-considered-undefined.md
 329 [unions]: items/unions.md
 330 [variable bindings]: patterns.md
 331 [visibility rules]: visibility-and-privacy.md