diff options
| -rw-r--r-- | src/doc/reference.md | 62 |
1 files changed, 55 insertions, 7 deletions
diff --git a/src/doc/reference.md b/src/doc/reference.md index 2ddec9ba424..76446876160 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -1346,6 +1346,8 @@ vtable when the trait is used as a [trait object](#trait-objects). Traits are implemented for specific types through separate [implementations](#implementations). +Consider the following trait: + ``` # type Surface = i32; # type BoundingBox = i32; @@ -1360,6 +1362,20 @@ This defines a trait with two methods. All values that have `draw` and `bounding_box` methods called, using `value.bounding_box()` [syntax](#method-call-expressions). +Traits can include default implementations of methods, as in: + +``` +trait Foo { + fn bar(&self); + + fn baz(&self) { println!("We called baz."); } +} +``` + +Here the `baz` method has a default implementation, so types that implement +`Foo` need only implement `bar`. It is also possible for implementing types +to override a method that has a default implementation. + Type parameters can be specified for a trait to make it generic. These appear after the trait name, using the same syntax used in [generic functions](#generic-functions). @@ -1372,6 +1388,30 @@ trait Seq<T> { } ``` +It is also possible to define associated types for a trait. Consider the +following example of a `Container` trait. Notice how the type is available +for use in the method signatures: + +``` +trait Container { + type E; + fn empty() -> Self; + fn insert(&mut self, Self::E); +} +``` + +In order for a type to implement this trait, it must not only provide +implementations for every method, but it must specify the type `E`. Here's +an implementation of `Container` for the standard library type `Vec`: + +``` +impl<T> Container for Vec<T> { + type E = T; + fn empty() -> Vec<T> { Vec::new() } + fn insert(&mut self, x: T) { self.push(x); } +} +``` + Generic functions may use traits as _bounds_ on their type parameters. This will have two effects: only types that have the trait may instantiate the parameter, and within the generic function, the methods of the trait can be @@ -3470,13 +3510,21 @@ more of the closure traits: ### Trait objects -Every trait item (see [traits](#traits)) defines a type with the same name as -the trait. This type is called the _trait object_ of the trait. Trait objects -permit "late binding" of methods, dispatched using _virtual method tables_ -("vtables"). Whereas most calls to trait methods are "early bound" (statically -resolved) to specific implementations at compile time, a call to a method on an -trait objects is only resolved to a vtable entry at compile time. The actual -implementation for each vtable entry can vary on an object-by-object basis. +In Rust, a type like `&SomeTrait` or `Box<SomeTrait>` is called a _trait object_. +Each instance of a trait object includes: + + - a pointer to an instance of a type `T` that implements `SomeTrait` + - a _virtual method table_, often just called a _vtable_, which contains, for + each method of `SomeTrait` that `T` implements, a pointer to `T`'s + implementation (i.e. a function pointer). + +The purpose of trait objects is to permit "late binding" of methods. A call to +a method on a trait object is only resolved to a vtable entry at compile time. +The actual implementation for each vtable entry can vary on an object-by-object +basis. + +Note that for a trait object to be instantiated, the trait must be +_object-safe_. Object safety rules are defined in [RFC 255][rfc255]. Given a pointer-typed expression `E` of type `&T` or `Box<T>`, where `T` implements trait `R`, casting `E` to the corresponding pointer type `&R` or |