[rustc.git] / src / doc / reference / src / glossary.md

# Glossary

### Abstract syntax tree

An ‘abstract syntax tree’, or ‘AST’, is an intermediate representation of
the structure of the program when the compiler is compiling it.

### Alignment

The alignment of a value specifies what addresses values are preferred to
start at. Always a power of two. References to a value must be aligned.
[More][alignment].

### Arity

Arity refers to the number of arguments a function or operator takes.
For some examples, `f(2, 3)` and `g(4, 6)` have arity 2, while `h(8, 2, 6)`
has arity 3. The `!` operator has arity 1.

### Array

An array, sometimes also called a fixed-size array or an inline array, is a value
describing a collection of elements, each selected by an index that can be computed
at run time by the program. It occupies a contiguous region of memory.

### Associated item

An associated item is an item that is associated with another item. Associated
items are defined in [implementations] and declared in [traits]. Only
functions, constants, and type aliases can be associated. Contrast to a [free
item].

### Blanket implementation

Any implementation where a type appears [uncovered](#uncovered-type). `impl<T> Foo
for T`, `impl<T> Bar<T> for T`, `impl<T> Bar<Vec<T>> for T`, and `impl<T> Bar<T>
for Vec<T>` are considered blanket impls. However, `impl<T> Bar<Vec<T>> for
Vec<T>` is not a blanket impl, as all instances of `T` which appear in this `impl`
are covered by `Vec`.

### Bound

Bounds are constraints on a type or trait. For example, if a bound
is placed on the argument a function takes, types passed to that function
must abide by that constraint.

### Combinator

Combinators are higher-order functions that apply only functions and
earlier defined combinators to provide a result from its arguments.
They can be used to manage control flow in a modular fashion.

### Dispatch

Dispatch is the mechanism to determine which specific version of code is actually
run when it involves polymorphism. Two major forms of dispatch are static dispatch and
dynamic dispatch. While Rust favors static dispatch, it also supports dynamic dispatch
through a mechanism called ‘trait objects’.

### Dynamically sized type

A dynamically sized type (DST) is a type without a statically known size or alignment.

### Expression

An expression is a combination of values, constants, variables, operators
and functions that evaluate to a single value, with or without side-effects.

For example, `2 + (3 * 4)` is an expression that returns the value 14.

### Free item

An [item] that is not a member of an [implementation], such as a *free
function* or a *free const*. Contrast to an [associated item].

### Fundamental traits

A fundamental trait is one where adding an impl of it for an existing type is a breaking change. 
The `Fn` traits and `Sized` are fundamental.

### Fundamental type constructors

A fundamental type constructor is a type where implementing a [blanket implementation](#blanket-implementation) over it 
is a breaking change. `&`, `&mut`, `Box`, and `Pin`  are fundamental. 

Any time a type `T` is considered [local](#local-type), `&T`, `&mut T`, `Box<T>`, and `Pin<T>` 
are also considered local. Fundamental type constructors cannot [cover](#uncovered-type) other types. 
Any time the term "covered type" is used, 
the `T` in `&T`, `&mut T`, `Box<T>`, and `Pin<T>` is not considered covered.

### Inhabited

A type is inhabited if it has constructors and therefore can be instantiated. An inhabited type is
not "empty" in the sense that there can be values of the type. Opposite of
[Uninhabited](#uninhabited).

### Inherent implementation

An [implementation] that applies to a nominal type, not to a trait-type pair.
[More][inherent implementation].

### Inherent method

A [method] defined in an [inherent implementation], not in a trait
implementation.

### Initialized

A variable is initialized if it has been assigned a value and hasn't since been
moved from. All other memory locations are assumed to be uninitialized. Only
unsafe Rust can create such a memory without initializing it.

### Local trait

A `trait` which was defined in the current crate. A trait definition is local
or not independent of applied type arguments. Given `trait Foo<T, U>`,
`Foo` is always local, regardless of the types substituted for `T` and `U`.

### Local type

A `struct`, `enum`, or `union` which was defined in the current crate.
This is not affected by applied type arguments. `struct Foo` is considered local, but
`Vec<Foo>` is not. `LocalType<ForeignType>` is local. Type aliases do not 
affect locality.

### Nominal types

Types that can be referred to by a path directly. Specifically [enums],
[structs], [unions], and [trait objects].

### Object safe traits

[Traits] that can be used as [trait objects]. Only traits that follow specific
[rules][object safety] are object safe.

### Prelude

Prelude, or The Rust Prelude, is a small collection of items - mostly traits - that are
imported into every module of every crate. The traits in the prelude are pervasive.

### Scrutinee

A scrutinee is the expression that is matched on in `match` expressions and
similar pattern matching constructs. For example, in `match x { A => 1, B => 2 }`,
the expression `x` is the scrutinee.

### Size

The size of a value has two definitions.

The first is that it is how much memory must be allocated to store that value.

The second is that it is the offset in bytes between successive elements in an
array with that item type.

It is a multiple of the alignment, including zero. The size can change
depending on compiler version (as new optimizations are made) and target
platform (similar to how `usize` varies per-platform).

[More][alignment].

### Slice

A slice is dynamically-sized view into a contiguous sequence, written as `[T]`.

It is often seen in its borrowed forms, either mutable or shared. The shared
slice type is `&[T]`, while the mutable slice type is `&mut [T]`, where `T` represents
the element type.

### Statement

A statement is the smallest standalone element of a programming language
that commands a computer to perform an action.

### String literal

A string literal is a string stored directly in the final binary, and so will be
valid for the `'static` duration.

Its type is `'static` duration borrowed string slice, `&'static str`.

### String slice

A string slice is the most primitive string type in Rust, written as `str`. It is
often seen in its borrowed forms, either mutable or shared. The shared
string slice type is `&str`, while the mutable string slice type is `&mut str`.

Strings slices are always valid UTF-8.

### Trait

A trait is a language item that is used for describing the functionalities a type must provide.
It allows a type to make certain promises about its behavior.

Generic functions and generic structs can use traits to constrain, or bound, the types they accept.

### Uncovered type

A type which does not appear as an argument to another type. For example,
`T` is uncovered, but the `T` in `Vec<T>` is covered. This is only relevant for
type arguments.

### Undefined behavior

Compile-time or run-time behavior that is not specified. This may result in,
but is not limited to: process termination or corruption; improper, incorrect,
or unintended computation; or platform-specific results.
[More][undefined-behavior].

### Uninhabited

A type is uninhabited if it has no constructors and therefore can never be instantiated. An
uninhabited type is "empty" in the sense that there are no values of the type. The canonical
example of an uninhabited type is the [never type] `!`, or an enum with no variants
`enum Never { }`. Opposite of [Inhabited](#inhabited).

[alignment]: type-layout.md#size-and-alignment
[associated item]: #associated-item
[enums]: items/enumerations.md
[free item]: #free-item
[implementation]: items/implementations.md
[implementations]: items/implementations.md
[inherent implementation]: items/implementations.md#inherent-implementations
[item]: items.md
[method]: items/associated-items.md#methods
[never type]: types/never.md
[object safety]: items/traits.md#object-safety
[structs]: items/structs.md
[trait objects]: types/trait-object.md
[traits]: items/traits.md
[undefined-behavior]: behavior-considered-undefined.md
[unions]: items/unions.md
Commit	Line	Data
3b2f2976 XL	1	# Glossary
3b2f2976 XL	2
532ac7d7	3	### Abstract syntax tree
3b2f2976 XL	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
ff7c6d11 XL	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
3b2f2976 XL	14	### Arity
3b2f2976 XL	15
ff7c6d11 XL	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.
3b2f2976 XL	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
532ac7d7	26	### Associated item
ff7c6d11 XL	27
ff7c6d11 XL	28	An associated item is an item that is associated with another item. Associated
532ac7d7 XL	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].
ff7c6d11	32
60c5eb7d XL	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
3b2f2976 XL	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
abe05a73	50	earlier defined combinators to provide a result from its arguments.
3b2f2976 XL	51	They can be used to manage control flow in a modular fashion.
	52
	53	### Dispatch
	54
	55	Dispatch is the mechanism to determine which specific version of code is actually
	56	run when it involves polymorphism. Two major forms of dispatch are static dispatch and
	57	dynamic dispatch. While Rust favors static dispatch, it also supports dynamic dispatch
	58	through a mechanism called ‘trait objects’.
	59
532ac7d7	60	### Dynamically sized type
3b2f2976	61
abe05a73	62	A dynamically sized type (DST) is a type without a statically known size or alignment.
3b2f2976 XL	63
	64	### Expression
	65
abe05a73	66	An expression is a combination of values, constants, variables, operators
3b2f2976 XL	67	and functions that evaluate to a single value, with or without side-effects.
	68
	69	For example, `2 + (3 * 4)` is an expression that returns the value 14.
	70
532ac7d7 XL	71	### Free item
	72
	73	An [item] that is not a member of an [implementation], such as a *free
	74	function* or a free const. Contrast to an [associated item].
	75
60c5eb7d XL	76	### Fundamental traits
	77
	78	A fundamental trait is one where adding an impl of it for an existing type is a breaking change.
	79	The `Fn` traits and `Sized` are fundamental.
	80
	81	### Fundamental type constructors
	82
	83	A fundamental type constructor is a type where implementing a [blanket implementation](#blanket-implementation) over it
	84	is a breaking change. `&`, `&mut`, `Box`, and `Pin` are fundamental.
	85
	86	Any time a type `T` is considered [local](#local-type), `&T`, `&mut T`, `Box<T>`, and `Pin<T>`
	87	are also considered local. Fundamental type constructors cannot [cover](#uncovered-type) other types.
	88	Any time the term "covered type" is used,
	89	the `T` in `&T`, `&mut T`, `Box<T>`, and `Pin<T>` is not considered covered.
	90
e74abb32 XL	91	### Inhabited
	92
	93	A type is inhabited if it has constructors and therefore can be instantiated. An inhabited type is
	94	not "empty" in the sense that there can be values of the type. Opposite of
	95	[Uninhabited](#uninhabited).
	96
532ac7d7 XL	97	### Inherent implementation
	98
	99	An [implementation] that applies to a nominal type, not to a trait-type pair.
	100	[More][inherent implementation].
	101
	102	### Inherent method
	103
	104	A [method] defined in an [inherent implementation], not in a trait
	105	implementation.
	106
abe05a73 XL	107	### Initialized
	108
	109	A variable is initialized if it has been assigned a value and hasn't since been
532ac7d7	110	moved from. All other memory locations are assumed to be uninitialized. Only
ff7c6d11 XL	111	unsafe Rust can create such a memory without initializing it.
ff7c6d11 XL	112
60c5eb7d XL	113	### Local trait
	114
	115	A `trait` which was defined in the current crate. A trait definition is local
	116	or not independent of applied type arguments. Given `trait Foo<T, U>`,
	117	`Foo` is always local, regardless of the types substituted for `T` and `U`.
	118
	119	### Local type
	120
	121	A `struct`, `enum`, or `union` which was defined in the current crate.
	122	This is not affected by applied type arguments. `struct Foo` is considered local, but
	123	`Vec<Foo>` is not. `LocalType<ForeignType>` is local. Type aliases do not
	124	affect locality.
	125
532ac7d7	126	### Nominal types
ff7c6d11 XL	127
	128	Types that can be referred to by a path directly. Specifically [enums],
	129	[structs], [unions], and [trait objects].
	130
532ac7d7	131	### Object safe traits
ff7c6d11	132
2c00a5a8	133	[Traits] that can be used as [trait objects]. Only traits that follow specific
8faf50e0	134	[rules][object safety] are object safe.
abe05a73	135
3b2f2976 XL	136	### Prelude
	137
	138	Prelude, or The Rust Prelude, is a small collection of items - mostly traits - that are
2c00a5a8	139	imported into every module of every crate. The traits in the prelude are pervasive.
3b2f2976	140
9fa01778 XL	141	### Scrutinee
	142
	143	A scrutinee is the expression that is matched on in `match` expressions and
	144	similar pattern matching constructs. For example, in `match x { A => 1, B => 2 }`,
	145	the expression `x` is the scrutinee.
	146
ff7c6d11 XL	147	### Size
	148
	149	The size of a value has two definitions.
	150
	151	The first is that it is how much memory must be allocated to store that value.
	152
	153	The second is that it is the offset in bytes between successive elements in an
	154	array with that item type.
	155
	156	It is a multiple of the alignment, including zero. The size can change
	157	depending on compiler version (as new optimizations are made) and target
	158	platform (similar to how `usize` varies per-platform).
	159
	160	[More][alignment].
	161
3b2f2976 XL	162	### Slice
3b2f2976 XL	163
abe05a73	164	A slice is dynamically-sized view into a contiguous sequence, written as `[T]`.
3b2f2976	165
abe05a73	166	It is often seen in its borrowed forms, either mutable or shared. The shared
3b2f2976 XL	167	slice type is `&[T]`, while the mutable slice type is `&mut [T]`, where `T` represents
	168	the element type.
	169
	170	### Statement
	171
	172	A statement is the smallest standalone element of a programming language
	173	that commands a computer to perform an action.
	174
	175	### String literal
	176
abe05a73 XL	177	A string literal is a string stored directly in the final binary, and so will be
abe05a73 XL	178	valid for the `'static` duration.
3b2f2976 XL	179
	180	Its type is `'static` duration borrowed string slice, `&'static str`.
	181
	182	### String slice
	183
	184	A string slice is the most primitive string type in Rust, written as `str`. It is
	185	often seen in its borrowed forms, either mutable or shared. The shared
	186	string slice type is `&str`, while the mutable string slice type is `&mut str`.
	187
	188	Strings slices are always valid UTF-8.
	189
	190	### Trait
	191
	192	A trait is a language item that is used for describing the functionalities a type must provide.
ff7c6d11 XL	193	It allows a type to make certain promises about its behavior.
	194
	195	Generic functions and generic structs can use traits to constrain, or bound, the types they accept.
	196
60c5eb7d XL	197	### Uncovered type
	198
	199	A type which does not appear as an argument to another type. For example,
	200	`T` is uncovered, but the `T` in `Vec<T>` is covered. This is only relevant for
	201	type arguments.
	202
532ac7d7 XL	203	### Undefined behavior
	204
	205	Compile-time or run-time behavior that is not specified. This may result in,
	206	but is not limited to: process termination or corruption; improper, incorrect,
	207	or unintended computation; or platform-specific results.
	208	[More][undefined-behavior].
	209
e74abb32 XL	210	### Uninhabited
	211
	212	A type is uninhabited if it has no constructors and therefore can never be instantiated. An
	213	uninhabited type is "empty" in the sense that there are no values of the type. The canonical
	214	example of an uninhabited type is the [never type] `!`, or an enum with no variants
	215	`enum Never { }`. Opposite of [Inhabited](#inhabited).
	216
416331ca	217	[alignment]: type-layout.md#size-and-alignment
532ac7d7	218	[associated item]: #associated-item
416331ca	219	[enums]: items/enumerations.md
532ac7d7	220	[free item]: #free-item
416331ca XL	221	[implementation]: items/implementations.md
	222	[implementations]: items/implementations.md
	223	[inherent implementation]: items/implementations.md#inherent-implementations
	224	[item]: items.md
	225	[method]: items/associated-items.md#methods
e74abb32	226	[never type]: types/never.md
416331ca XL	227	[object safety]: items/traits.md#object-safety
	228	[structs]: items/structs.md
	229	[trait objects]: types/trait-object.md
	230	[traits]: items/traits.md
	231	[undefined-behavior]: behavior-considered-undefined.md
	232	[unions]: items/unions.md