3 A trait is a language feature that tells the Rust compiler about
4 functionality a type must provide.
6 Recall the `impl` keyword, used to call a function with [method
17 fn area(&self) -> f64 {
18 std::f64::consts::PI * (self.radius * self.radius)
23 [methodsyntax]: method-syntax.html
25 Traits are similar, except that we first define a trait with a method
26 signature, then implement the trait for a type. In this example, we implement the trait `HasArea` for `Circle`:
36 fn area(&self) -> f64;
39 impl HasArea for Circle {
40 fn area(&self) -> f64 {
41 std::f64::consts::PI * (self.radius * self.radius)
46 As you can see, the `trait` block looks very similar to the `impl` block,
47 but we don’t define a body, only a type signature. When we `impl` a trait,
48 we use `impl Trait for Item`, rather than only `impl Item`.
50 ## Trait bounds on generic functions
52 Traits are useful because they allow a type to make certain promises about its
53 behavior. Generic functions can exploit this to constrain, or [bound][bounds], the types they
54 accept. Consider this function, which does not compile:
56 [bounds]: glossary.html#bounds
59 fn print_area<T>(shape: T) {
60 println!("This shape has an area of {}", shape.area());
67 error: no method named `area` found for type `T` in the current scope
70 Because `T` can be any type, we can’t be sure that it implements the `area`
71 method. But we can add a trait bound to our generic `T`, ensuring
76 # fn area(&self) -> f64;
78 fn print_area<T: HasArea>(shape: T) {
79 println!("This shape has an area of {}", shape.area());
83 The syntax `<T: HasArea>` means “any type that implements the `HasArea` trait.”
84 Because traits define function type signatures, we can be sure that any type
85 which implements `HasArea` will have an `.area()` method.
87 Here’s an extended example of how this works:
91 fn area(&self) -> f64;
100 impl HasArea for Circle {
101 fn area(&self) -> f64 {
102 std::f64::consts::PI * (self.radius * self.radius)
112 impl HasArea for Square {
113 fn area(&self) -> f64 {
114 self.side * self.side
118 fn print_area<T: HasArea>(shape: T) {
119 println!("This shape has an area of {}", shape.area());
140 This program outputs:
143 This shape has an area of 3.141593
144 This shape has an area of 1
147 As you can see, `print_area` is now generic, but also ensures that we have
148 passed in the correct types. If we pass in an incorrect type:
154 We get a compile-time error:
157 error: the trait bound `_ : HasArea` is not satisfied [E0277]
160 ## Trait bounds on generic structs
162 Your generic structs can also benefit from trait bounds. All you need to
163 do is append the bound when you declare type parameters. Here is a new
164 type `Rectangle<T>` and its operation `is_square()`:
167 struct Rectangle<T> {
174 impl<T: PartialEq> Rectangle<T> {
175 fn is_square(&self) -> bool {
176 self.width == self.height
181 let mut r = Rectangle {
188 assert!(r.is_square());
191 assert!(!r.is_square());
195 `is_square()` needs to check that the sides are equal, so the sides must be of
196 a type that implements the [`core::cmp::PartialEq`][PartialEq] trait:
199 impl<T: PartialEq> Rectangle<T> { ... }
202 Now, a rectangle can be defined in terms of any type that can be compared for
205 [PartialEq]: ../core/cmp/trait.PartialEq.html
207 Here we defined a new struct `Rectangle` that accepts numbers of any
208 precision—really, objects of pretty much any type—as long as they can be
209 compared for equality. Could we do the same for our `HasArea` structs, `Square`
210 and `Circle`? Yes, but they need multiplication, and to work with that we need
211 to know more about [operator traits][operators-and-overloading].
213 [operators-and-overloading]: operators-and-overloading.html
215 # Rules for implementing traits
217 So far, we’ve only added trait implementations to structs, but you can
218 implement a trait for any type. So technically, we _could_ implement `HasArea`
223 fn area(&self) -> f64;
226 impl HasArea for i32 {
227 fn area(&self) -> f64 {
228 println!("this is silly");
237 It is considered poor style to implement methods on such primitive types, even
238 though it is possible.
240 This may seem like the Wild West, but there are two restrictions around
241 implementing traits that prevent this from getting out of hand. The first is
242 that if the trait isn’t defined in your scope, it doesn’t apply. Here’s an
243 example: the standard library provides a [`Write`][write] trait which adds
244 extra functionality to `File`s, for doing file I/O. By default, a `File`
245 won’t have its methods:
247 [write]: ../std/io/trait.Write.html
250 let mut f = std::fs::File::open("foo.txt").expect("Couldn’t open foo.txt");
251 let buf = b"whatever"; // byte string literal. buf: &[u8; 8]
252 let result = f.write(buf);
253 # result.unwrap(); // ignore the error
259 error: type `std::fs::File` does not implement any method in scope named `write`
260 let result = f.write(buf);
264 We need to `use` the `Write` trait first:
269 let mut f = std::fs::File::open("foo.txt").expect("Couldn’t open foo.txt");
270 let buf = b"whatever";
271 let result = f.write(buf);
272 # result.unwrap(); // ignore the error
275 This will compile without error.
277 This means that even if someone does something bad like add methods to `i32`,
278 it won’t affect you, unless you `use` that trait.
280 There’s one more restriction on implementing traits: either the trait
281 or the type you’re implementing it for must be defined by you. Or more
282 precisely, one of them must be defined in the same crate as the `impl`
283 you're writing. For more on Rust's module and package system, see the
284 chapter on [crates and modules][cm].
286 So, we could implement the `HasArea` type for `i32`, because we defined
287 `HasArea` in our code. But if we tried to implement `ToString`, a trait
288 provided by Rust, for `i32`, we could not, because neither the trait nor
289 the type are defined in our crate.
291 One last thing about traits: generic functions with a trait bound use
292 ‘monomorphization’ (mono: one, morph: form), so they are statically dispatched.
293 What’s that mean? Check out the chapter on [trait objects][to] for more details.
295 [cm]: crates-and-modules.html
296 [to]: trait-objects.html
298 # Multiple trait bounds
300 You’ve seen that you can bound a generic type parameter with a trait:
303 fn foo<T: Clone>(x: T) {
308 If you need more than one bound, you can use `+`:
313 fn foo<T: Clone + Debug>(x: T) {
319 `T` now needs to be both `Clone` as well as `Debug`.
323 Writing functions with only a few generic types and a small number of trait
324 bounds isn’t too bad, but as the number increases, the syntax gets increasingly
330 fn foo<T: Clone, K: Clone + Debug>(x: T, y: K) {
337 The name of the function is on the far left, and the parameter list is on the
338 far right. The bounds are getting in the way.
340 Rust has a solution, and it’s called a ‘`where` clause’:
345 fn foo<T: Clone, K: Clone + Debug>(x: T, y: K) {
351 fn bar<T, K>(x: T, y: K) where T: Clone, K: Clone + Debug {
358 foo("Hello", "world");
359 bar("Hello", "world");
363 `foo()` uses the syntax we showed earlier, and `bar()` uses a `where` clause.
364 All you need to do is leave off the bounds when defining your type parameters,
365 and then add `where` after the parameter list. For longer lists, whitespace can
371 fn bar<T, K>(x: T, y: K)
381 This flexibility can add clarity in complex situations.
383 `where` is also more powerful than the simpler syntax. For example:
386 trait ConvertTo<Output> {
387 fn convert(&self) -> Output;
390 impl ConvertTo<i64> for i32 {
391 fn convert(&self) -> i64 { *self as i64 }
394 // can be called with T == i32
395 fn normal<T: ConvertTo<i64>>(x: &T) -> i64 {
399 // can be called with T == i64
401 // this is using ConvertTo as if it were "ConvertTo<i64>"
402 where i32: ConvertTo<T> {
407 This shows off the additional feature of `where` clauses: they allow bounds
408 on the left-hand side not only of type parameters `T`, but also of types (`i32` in this case). In this example, `i32` must implement
409 `ConvertTo<T>`. Rather than defining what `i32` is (since that's obvious), the
410 `where` clause here constrains `T`.
414 A default method can be added to a trait definition if it is already known how a typical implementor will define a method. For example, `is_invalid()` is defined as the opposite of `is_valid()`:
418 fn is_valid(&self) -> bool;
420 fn is_invalid(&self) -> bool { !self.is_valid() }
424 Implementors of the `Foo` trait need to implement `is_valid()` but not `is_invalid()` due to the added default behavior. This default behavior can still be overridden as in:
428 # fn is_valid(&self) -> bool;
430 # fn is_invalid(&self) -> bool { !self.is_valid() }
434 impl Foo for UseDefault {
435 fn is_valid(&self) -> bool {
436 println!("Called UseDefault.is_valid.");
441 struct OverrideDefault;
443 impl Foo for OverrideDefault {
444 fn is_valid(&self) -> bool {
445 println!("Called OverrideDefault.is_valid.");
449 fn is_invalid(&self) -> bool {
450 println!("Called OverrideDefault.is_invalid!");
451 true // overrides the expected value of is_invalid()
455 let default = UseDefault;
456 assert!(!default.is_invalid()); // prints "Called UseDefault.is_valid."
458 let over = OverrideDefault;
459 assert!(over.is_invalid()); // prints "Called OverrideDefault.is_invalid!"
464 Sometimes, implementing a trait requires implementing another trait:
476 Implementors of `FooBar` must also implement `Foo`, like this:
482 # trait FooBar : Foo {
488 fn foo(&self) { println!("foo"); }
491 impl FooBar for Baz {
492 fn foobar(&self) { println!("foobar"); }
496 If we forget to implement `Foo`, Rust will tell us:
499 error: the trait bound `main::Baz : main::Foo` is not satisfied [E0277]
504 Implementing traits like `Debug` and `Default` repeatedly can become
505 quite tedious. For that reason, Rust provides an [attribute][attributes] that
506 allows you to let Rust automatically implement traits for you:
513 println!("{:?}", Foo);
517 [attributes]: attributes.html
519 However, deriving is limited to a certain set of traits:
521 - [`Clone`](../core/clone/trait.Clone.html)
522 - [`Copy`](../core/marker/trait.Copy.html)
523 - [`Debug`](../core/fmt/trait.Debug.html)
524 - [`Default`](../core/default/trait.Default.html)
525 - [`Eq`](../core/cmp/trait.Eq.html)
526 - [`Hash`](../core/hash/trait.Hash.html)
527 - [`Ord`](../core/cmp/trait.Ord.html)
528 - [`PartialEq`](../core/cmp/trait.PartialEq.html)
529 - [`PartialOrd`](../core/cmp/trait.PartialOrd.html)