# Items
An _item_ is a component of a crate. Items are organized within a crate by a
-nested set of [modules](#modules). Every crate has a single "outermost"
-anonymous module; all further items within the crate have [paths](#paths)
+nested set of [modules]. Every crate has a single "outermost"
+anonymous module; all further items within the crate have [paths]
within the module tree of the crate.
+[modules]: modules.html
+[paths]: paths.html
+
Items are entirely determined at compile-time, generally remain fixed during
execution, and may reside in read-only memory.
* [modules](#modules)
* [function definitions](#functions)
* [`extern` blocks](#external-blocks)
-* [type definitions](grammar.html#type-definitions)
+* [type definitions](../grammar.html#type-definitions)
* [struct definitions](#structs)
* [enumeration definitions](#enumerations)
* [constant items](#constant-items)
Type parameters are given as a comma-separated list of identifiers enclosed in
angle brackets (`<...>`), after the name of the item and before its definition.
The type parameters of an item are considered "part of the name", not part of
-the type of the item. A referencing [path](#paths) must (in principle) provide
+the type of the item. A referencing [path] must (in principle) provide
type arguments as a list of comma-separated types enclosed within angle
brackets, in order to refer to the type-parameterized item. In practice, the
type-inference system can usually infer such argument types from context. There
has no notion of type abstraction: there are no higher-ranked (or "forall") types
abstracted over other types, though higher-ranked types do exist for lifetimes.
+[path]: paths.html
+
## Modules
-A module is a container for zero or more [items](#items).
+A module is a container for zero or more [items].
+
+[items]: items.html
A _module item_ is a module, surrounded in braces, named, and prefixed with the
keyword `mod`. A module item introduces a new, named module into the tree of
An example of a module:
-```
+```rust
mod math {
type Complex = (f64, f64);
fn sin(f: f64) -> f64 {
loaded from an external file, it is loaded from a subdirectory path that
mirrors the module hierarchy.
-```{.ignore}
+```rust,ignore
// Load the `vec` module from `vec.rs`
mod vec;
The directories and files used for loading external file modules can be
influenced with the `path` attribute.
-```{.ignore}
+```rust,ignore
#[path = "thread_files"]
mod thread {
// Load the `local_data` module from `thread_files/tls.rs`
Three examples of `extern crate` declarations:
-```{.ignore}
+```rust,ignore
extern crate pcre;
extern crate std; // equivalent to: extern crate std as std;
Here is an example:
-```{.ignore}
+```rust,ignore
// Importing the Cargo package hello-world
extern crate hello_world; // hyphen replaced with an underscore
```
### Use declarations
A _use declaration_ creates one or more local name bindings synonymous with
-some other [path](#paths). Usually a `use` declaration is used to shorten the
+some other [path]. Usually a `use` declaration is used to shorten the
path required to refer to a module item. These declarations may appear in
-[modules](#modules) and [blocks](grammar.html#block-expressions), usually at the top.
+[modules] and [blocks], usually at the top.
+
+[path]: paths.html
+[modules]: #modules
+[blocks]: ../grammar.html#block-expressions
> **Note**: Unlike in many languages,
> `use` declarations in Rust do *not* declare linkage dependency with external crates.
An example of re-exporting:
-```
+```rust
# fn main() { }
mod quux {
pub use quux::foo::{bar, baz};
An example of what will and will not work for `use` items:
-```
+```rust
# #![allow(unused_imports)]
use foo::baz::foobaz; // good: foo is at the root of the crate
## Functions
-A _function item_ defines a sequence of [statements](#statements) and a
-final [expression](#expressions), along with a name and a set of
+A _function item_ defines a sequence of [statements] and a
+final [expression], along with a name and a set of
parameters. Other than a name, all these are optional.
Functions are declared with the keyword `fn`. Functions may declare a
-set of *input* [*variables*](#variables) as parameters, through which the caller
-passes arguments into the function, and the *output* [*type*](#types)
+set of *input* [*variables*][variables] as parameters, through which the caller
+passes arguments into the function, and the *output* [*type*][type]
of the value the function will return to its caller on completion.
+[statements]: statements.html
+[expression]: expressions.html
+[variables]: variables.html
+[type]: types.html
+
A function may also be copied into a first-class *value*, in which case the
-value has the corresponding [*function type*](#function-types), and can be used
+value has the corresponding [*function type*][function type], and can be used
otherwise exactly as a function item (with a minor additional cost of calling
the function indirectly).
+[function type]: types.html#function-types
+
Every control path in a function logically ends with a `return` expression or a
diverging expression. If the outermost block of a function has a
value-producing expression in its final-expression position, that expression is
An example of a function:
-```
+```rust
fn add(x: i32, y: i32) -> i32 {
x + y
}
As with `let` bindings, function arguments are irrefutable patterns, so any
pattern that is valid in a let binding is also valid as an argument.
-```
+```rust
fn first((value, _): (i32, i32)) -> i32 { value }
```
When a generic function is referenced, its type is instantiated based on the
context of the reference. For example, calling the `foo` function here:
-```
+```rust
use std::fmt::Debug;
fn foo<T>(x: &[T]) where T: Debug {
will instantiate type parameter `T` with `i32`.
The type parameters can also be explicitly supplied in a trailing
-[path](#paths) component after the function name. This might be necessary if
+[path] component after the function name. This might be necessary if
there is not sufficient context to determine the type parameters. For example,
`mem::size_of::<u32>() == 4`.
+[path]: paths.html
+
### Diverging functions
A special kind of function can be declared with a `!` character where the
output type would normally be. For example:
-```
+```rust
fn my_err(s: &str) -> ! {
println!("{}", s);
panic!();
It might be necessary to declare a diverging function because as mentioned
previously, the typechecker checks that every control path in a function ends
-with a [`return`](#return-expressions) or diverging expression. So, if `my_err`
+with a [`return`] or diverging expression. So, if `my_err`
were declared without the `!` annotation, the following code would not
typecheck:
-```
+[`return`]: expressions.html#return-expressions
+
+```rust
# fn my_err(s: &str) -> ! { panic!() }
fn f(i: i32) -> i32 {
in the same way as any other Rust function, except that they have the `extern`
modifier.
-```
+```rust
// Declares an extern fn, the ABI defaults to "C"
extern fn new_i32() -> i32 { 0 }
Unlike normal functions, extern fns have type `extern "ABI" fn()`. This is the
same type as the functions declared in an extern block.
-```
+```rust
# extern fn new_i32() -> i32 { 0 }
let fptr: extern "C" fn() -> i32 = new_i32;
```
## Type aliases
-A _type alias_ defines a new name for an existing [type](#types). Type
+A _type alias_ defines a new name for an existing [type]. Type
aliases are declared with the keyword `type`. Every value has a single,
specific type, but may implement several different traits, or be compatible with
several different type constraints.
+[type]: types.html
+
For example, the following defines the type `Point` as a synonym for the type
`(u8, u8)`, the type of pairs of unsigned 8 bit integers:
-```
+```rust
type Point = (u8, u8);
let p: Point = (41, 68);
```
Currently a type alias to an enum type cannot be used to qualify the
constructors:
-```
+```rust
enum E { A }
type F = E;
let _: F = E::A; // OK
## Structs
-A _struct_ is a nominal [struct type](#struct-types) defined with the
+A _struct_ is a nominal [struct type] defined with the
keyword `struct`.
An example of a `struct` item and its use:
-```
+```rust
struct Point {x: i32, y: i32}
let p = Point {x: 10, y: 11};
let px: i32 = p.x;
```
-A _tuple struct_ is a nominal [tuple type](#tuple-types), also defined with
+A _tuple struct_ is a nominal [tuple type], also defined with
the keyword `struct`. For example:
-```
+[struct type]: types.html#struct-types
+[tuple type]: types.html#tuple-types
+
+```rust
struct Point(i32, i32);
let p = Point(10, 11);
let px: i32 = match p { Point(x, _) => x };
the list of fields entirely. Such a struct implicitly defines a constant of
its type with the same name. For example:
-```
+```rust
struct Cookie;
let c = [Cookie, Cookie {}, Cookie, Cookie {}];
```
is equivalent to
-```
+```rust
struct Cookie {}
const Cookie: Cookie = Cookie {};
let c = [Cookie, Cookie {}, Cookie, Cookie {}];
```
The precise memory layout of a struct is not specified. One can specify a
-particular layout using the [`repr` attribute](#ffi-attributes).
+particular layout using the [`repr` attribute].
+
+[`repr` attribute]: attributes.html#ffi-attributes
## Enumerations
An _enumeration_ is a simultaneous definition of a nominal [enumerated
-type](#enumerated-types) as well as a set of *constructors*, that can be used
+type] as well as a set of *constructors*, that can be used
to create or pattern-match values of the corresponding enumerated type.
+[enumerated type]: types.html#enumerated-types
+
Enumerations are declared with the keyword `enum`.
An example of an `enum` item and its use:
-```
+```rust
enum Animal {
Dog,
Cat,
Each enum value has a _discriminant_ which is an integer associated to it. You
can specify it explicitly:
-```
+```rust
enum Foo {
Bar = 123,
}
The right hand side of the specification is interpreted as an `isize` value,
but the compiler is allowed to use a smaller type in the actual memory layout.
-The [`repr` attribute](#ffi-attributes) can be added in order to change
+The [`repr` attribute] can be added in order to change
the type of the right hand side and specify the memory layout.
+[`repr` attribute]: attributes.html#ffi-attributes
+
If a discriminant isn't specified, they start at zero, and add one for each
variant, in order.
You can cast an enum to get its discriminant:
-```
+```rust
# enum Foo { Bar = 123 }
let x = Foo::Bar as u32; // x is now 123u32
```
is unable to resolve the lifetimes by its usual rules, it will default to using
the `'static` lifetime. By way of example:
-[elision-nomicon]: https://doc.rust-lang.org/nomicon/lifetime-elision.html
+[elision-nomicon]: ../nomicon/lifetime-elision.html
```rust,ignore
// Resolved as `fn<'a>(&'a str) -> &'a str`.
Trait bounds on `Self` are considered "supertraits". These are
required to be acyclic. Supertraits are somewhat different from other
constraints in that they affect what methods are available in the
-vtable when the trait is used as a [trait object](#trait-objects).
+vtable when the trait is used as a [trait object].
Traits are implemented for specific types through separate
-[implementations](#implementations).
+[implementations].
Consider the following trait:
-```
+```rust
# type Surface = i32;
# type BoundingBox = i32;
trait Shape {
```
This defines a trait with two methods. All values that have
-[implementations](#implementations) of this trait in scope can have their
+[implementations] of this trait in scope can have their
`draw` and `bounding_box` methods called, using `value.bounding_box()`
-[syntax](#method-call-expressions).
+[syntax].
+
+[trait object]: types.html#trait-objects
+[implementations]: #implementations
+[syntax]: expressions.html#method-call-expressions
Traits can include default implementations of methods, as in:
-```
+```rust
trait Foo {
fn bar(&self);
fn baz(&self) { println!("We called baz."); }
after the trait name, using the same syntax used in [generic
functions](#generic-functions).
-```
+```rust
trait Seq<T> {
fn len(&self) -> u32;
fn elt_at(&self, n: u32) -> T;
following example of a `Container` trait. Notice how the type is available
for use in the method signatures:
-```
+```rust
trait Container {
type E;
fn empty() -> Self;
implementations for every method, but it must specify the type `E`. Here's
an implementation of `Container` for the standard library type `Vec`:
-```
+```rust
# trait Container {
# type E;
# fn empty() -> Self;
For example:
-```
+```rust
# type Surface = i32;
# trait Shape { fn draw(&self, Surface); }
fn draw_twice<T: Shape>(surface: Surface, sh: T) {
}
```
-Traits also define a [trait object](#trait-objects) with the same
+Traits also define a [trait object] with the same
name as the trait. Values of this type are created by coercing from a
pointer of some specific type to a pointer of trait type. For example,
`&T` could be coerced to `&Shape` if `T: Shape` holds (and similarly
for `Box<T>`). This coercion can either be implicit or
-[explicit](#type-cast-expressions). Here is an example of an explicit
+[explicit]. Here is an example of an explicit
coercion:
-```
+[trait object]: types.html#trait-objects
+[explicit]: expressions.html#type-cast-expressions
+
+```rust
trait Shape { }
impl Shape for i32 { }
let mycircle = 0i32;
The resulting value is a box containing the value that was cast, along with
information that identifies the methods of the implementation that was used.
-Values with a trait type can have [methods called](#method-call-expressions) on
+Values with a trait type can have [methods called] on
them, for any method in the trait, and can be used to instantiate type
parameters that are bounded by the trait.
+[methods called]: expressions.html#method-call-expressions
+
Trait methods may be static, which means that they lack a `self` argument.
This means that they can only be called with function call syntax (`f(x)`) and
not method call syntax (`obj.f()`). The way to refer to the name of a static
method is to qualify it with the trait name, treating the trait name like a
module. For example:
-```
+```rust
trait Num {
fn from_i32(n: i32) -> Self;
}
Traits may inherit from other traits. Consider the following example:
-```
+```rust
trait Shape { fn area(&self) -> f64; }
trait Circle : Shape { fn radius(&self) -> f64; }
```
values of subtrait-bound type parameters. Referring to the previous example of
`trait Circle : Shape`:
-```
+```rust
# trait Shape { fn area(&self) -> f64; }
# trait Circle : Shape { fn radius(&self) -> f64; }
fn radius_times_area<T: Circle>(c: T) -> f64 {
Likewise, supertrait methods may also be called on trait objects.
-```{.ignore}
+```rust,ignore
# trait Shape { fn area(&self) -> f64; }
# trait Circle : Shape { fn radius(&self) -> f64; }
# impl Shape for i32 { fn area(&self) -> f64 { 0.0 } }
Implementations are defined with the keyword `impl`.
-```
+```rust
# #[derive(Copy, Clone)]
# struct Point {x: f64, y: f64};
# type Surface = i32;
to nominal types (enums, structs, trait objects), and the implementation must
appear in the same crate as the `self` type:
-```
+```rust
struct Point {x: i32, y: i32}
impl Point {
type parameters taken by the trait it implements. Implementation parameters
are written after the `impl` keyword.
-```
+```rust
# trait Seq<T> { fn dummy(&self, _: T) { } }
impl<T> Seq<T> for Vec<T> {
/* ... */
Functions within external blocks may be variadic by specifying `...` after one
or more named arguments in the argument list:
-```ignore
+```rust,ignore
extern {
fn foo(x: i32, ...);
}
```
-A number of [attributes](#ffi-attributes) control the behavior of external blocks.
+A number of [attributes] control the behavior of external blocks.
+
+[attributes]: attributes.html#ffi-attributes
By default external blocks assume that the library they are calling uses the
standard C ABI on the specific platform. Other ABIs may be specified using an
`abi` string, as shown here:
-```ignore
+```rust,ignore
// Interface to the Windows API
extern "stdcall" { }
```
specified the compiler will attempt to link against the native library of the
specified name.
-```{.ignore}
+```rust,ignore
#[link(name = "crypto")]
extern { }
```
projects / rust.git / commitdiff