From 857a12a01ed8a9249cea8f48b39a0f8bdfd95cbd Mon Sep 17 00:00:00 2001 From: Nick Hamann Date: Tue, 12 May 2015 23:33:10 -0500 Subject: [PATCH 1/2] Expand the "Traits" section of the reference. --- src/doc/reference.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/src/doc/reference.md b/src/doc/reference.md index 2ddec9ba424f2..03b5530983697 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 { } ``` +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 Container for Vec { + type E = T; + fn empty() -> Vec { 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 From b2f486feafa99124479d1b5e74c9acc6ed7cc233 Mon Sep 17 00:00:00 2001 From: Nick Hamann Date: Tue, 12 May 2015 21:47:25 -0500 Subject: [PATCH 2/2] Improve wording for the "Trait objects" section of the reference. --- src/doc/reference.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/src/doc/reference.md b/src/doc/reference.md index 03b5530983697..764468761607a 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -3510,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` 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`, where `T` implements trait `R`, casting `E` to the corresponding pointer type `&R` or