src/doc/book/traits.md

   1 % Traits
   2
   3 A trait is a language feature that tells the Rust compiler about
   4 functionality a type must provide.
   5
   6 Recall the `impl` keyword, used to call a function with [method
   7 syntax][methodsyntax]:
   8
   9 ```rust
  10 struct Circle {
  11     x: f64,
  12     y: f64,
  13     radius: f64,
  14 }
  15
  16 impl Circle {
  17     fn area(&self) -> f64 {
  18         std::f64::consts::PI * (self.radius * self.radius)
  19     }
  20 }
  21 ```
  22
  23 [methodsyntax]: method-syntax.html
  24
  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`:
  27
  28 ```rust
  29 struct Circle {
  30     x: f64,
  31     y: f64,
  32     radius: f64,
  33 }
  34
  35 trait HasArea {
  36     fn area(&self) -> f64;
  37 }
  38
  39 impl HasArea for Circle {
  40     fn area(&self) -> f64 {
  41         std::f64::consts::PI * (self.radius * self.radius)
  42     }
  43 }
  44 ```
  45
  46 As you can see, the `trait` block looks very similar to the `impl` block,
  47 but we don’t define a body, just a type signature. When we `impl` a trait,
  48 we use `impl Trait for Item`, rather than just `impl Item`.
  49
  50 ## Trait bounds on generic functions
  51
  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:
  55
  56 [bounds]: glossary.html#bounds
  57
  58 ```rust,ignore
  59 fn print_area<T>(shape: T) {
  60     println!("This shape has an area of {}", shape.area());
  61 }
  62 ```
  63
  64 Rust complains:
  65
  66 ```text
  67 error: no method named `area` found for type `T` in the current scope
  68 ```
  69
  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
  72 that it does:
  73
  74 ```rust
  75 # trait HasArea {
  76 #     fn area(&self) -> f64;
  77 # }
  78 fn print_area<T: HasArea>(shape: T) {
  79     println!("This shape has an area of {}", shape.area());
  80 }
  81 ```
  82
  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.
  86
  87 Here’s an extended example of how this works:
  88
  89 ```rust
  90 trait HasArea {
  91     fn area(&self) -> f64;
  92 }
  93
  94 struct Circle {
  95     x: f64,
  96     y: f64,
  97     radius: f64,
  98 }
  99
 100 impl HasArea for Circle {
 101     fn area(&self) -> f64 {
 102         std::f64::consts::PI * (self.radius * self.radius)
 103     }
 104 }
 105
 106 struct Square {
 107     x: f64,
 108     y: f64,
 109     side: f64,
 110 }
 111
 112 impl HasArea for Square {
 113     fn area(&self) -> f64 {
 114         self.side * self.side
 115     }
 116 }
 117
 118 fn print_area<T: HasArea>(shape: T) {
 119     println!("This shape has an area of {}", shape.area());
 120 }
 121
 122 fn main() {
 123     let c = Circle {
 124         x: 0.0f64,
 125         y: 0.0f64,
 126         radius: 1.0f64,
 127     };
 128
 129     let s = Square {
 130         x: 0.0f64,
 131         y: 0.0f64,
 132         side: 1.0f64,
 133     };
 134
 135     print_area(c);
 136     print_area(s);
 137 }
 138 ```
 139
 140 This program outputs:
 141
 142 ```text
 143 This shape has an area of 3.141593
 144 This shape has an area of 1
 145 ```
 146
 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:
 149
 150 ```rust,ignore
 151 print_area(5);
 152 ```
 153
 154 We get a compile-time error:
 155
 156 ```text
 157 error: the trait `HasArea` is not implemented for the type `_` [E0277]
 158 ```
 159
 160 ## Trait bounds on generic structs
 161
 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()`:
 165
 166 ```rust
 167 struct Rectangle<T> {
 168     x: T,
 169     y: T,
 170     width: T,
 171     height: T,
 172 }
 173
 174 impl<T: PartialEq> Rectangle<T> {
 175     fn is_square(&self) -> bool {
 176         self.width == self.height
 177     }
 178 }
 179
 180 fn main() {
 181     let mut r = Rectangle {
 182         x: 0,
 183         y: 0,
 184         width: 47,
 185         height: 47,
 186     };
 187
 188     assert!(r.is_square());
 189
 190     r.height = 42;
 191     assert!(!r.is_square());
 192 }
 193 ```
 194
 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:
 197
 198 ```ignore
 199 impl<T: PartialEq> Rectangle<T> { ... }
 200 ```
 201
 202 Now, a rectangle can be defined in terms of any type that can be compared for
 203 equality.
 204
 205 [PartialEq]: ../core/cmp/trait.PartialEq.html
 206
 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].
 212
 213 [operators-and-overloading]: operators-and-overloading.html
 214
 215 # Rules for implementing traits
 216
 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`
 219 for `i32`:
 220
 221 ```rust
 222 trait HasArea {
 223     fn area(&self) -> f64;
 224 }
 225
 226 impl HasArea for i32 {
 227     fn area(&self) -> f64 {
 228         println!("this is silly");
 229
 230         *self as f64
 231     }
 232 }
 233
 234 5.area();
 235 ```
 236
 237 It is considered poor style to implement methods on such primitive types, even
 238 though it is possible.
 239
 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:
 246
 247 [write]: ../std/io/trait.Write.html
 248
 249 ```rust,ignore
 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
 254 ```
 255
 256 Here’s the error:
 257
 258 ```text
 259 error: type `std::fs::File` does not implement any method in scope named `write`
 260 let result = f.write(buf);
 261                ^~~~~~~~~~
 262 ```
 263
 264 We need to `use` the `Write` trait first:
 265
 266 ```rust,ignore
 267 use std::io::Write;
 268
 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
 273 ```
 274
 275 This will compile without error.
 276
 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.
 279
 280 There’s one more restriction on implementing traits: either the trait, or the
 281 type you’re writing the `impl` for, must be defined by you. So, we could
 282 implement the `HasArea` type for `i32`, because `HasArea` is in our code. But
 283 if we tried to implement `ToString`, a trait provided by Rust, for `i32`, we could
 284 not, because neither the trait nor the type are in our code.
 285
 286 One last thing about traits: generic functions with a trait bound use
 287 ‘monomorphization’ (mono: one, morph: form), so they are statically dispatched.
 288 What’s that mean? Check out the chapter on [trait objects][to] for more details.
 289
 290 [to]: trait-objects.html
 291
 292 # Multiple trait bounds
 293
 294 You’ve seen that you can bound a generic type parameter with a trait:
 295
 296 ```rust
 297 fn foo<T: Clone>(x: T) {
 298     x.clone();
 299 }
 300 ```
 301
 302 If you need more than one bound, you can use `+`:
 303
 304 ```rust
 305 use std::fmt::Debug;
 306
 307 fn foo<T: Clone + Debug>(x: T) {
 308     x.clone();
 309     println!("{:?}", x);
 310 }
 311 ```
 312
 313 `T` now needs to be both `Clone` as well as `Debug`.
 314
 315 # Where clause
 316
 317 Writing functions with only a few generic types and a small number of trait
 318 bounds isn’t too bad, but as the number increases, the syntax gets increasingly
 319 awkward:
 320
 321 ```rust
 322 use std::fmt::Debug;
 323
 324 fn foo<T: Clone, K: Clone + Debug>(x: T, y: K) {
 325     x.clone();
 326     y.clone();
 327     println!("{:?}", y);
 328 }
 329 ```
 330
 331 The name of the function is on the far left, and the parameter list is on the
 332 far right. The bounds are getting in the way.
 333
 334 Rust has a solution, and it’s called a ‘`where` clause’:
 335
 336 ```rust
 337 use std::fmt::Debug;
 338
 339 fn foo<T: Clone, K: Clone + Debug>(x: T, y: K) {
 340     x.clone();
 341     y.clone();
 342     println!("{:?}", y);
 343 }
 344
 345 fn bar<T, K>(x: T, y: K) where T: Clone, K: Clone + Debug {
 346     x.clone();
 347     y.clone();
 348     println!("{:?}", y);
 349 }
 350
 351 fn main() {
 352     foo("Hello", "world");
 353     bar("Hello", "world");
 354 }
 355 ```
 356
 357 `foo()` uses the syntax we showed earlier, and `bar()` uses a `where` clause.
 358 All you need to do is leave off the bounds when defining your type parameters,
 359 and then add `where` after the parameter list. For longer lists, whitespace can
 360 be added:
 361
 362 ```rust
 363 use std::fmt::Debug;
 364
 365 fn bar<T, K>(x: T, y: K)
 366     where T: Clone,
 367           K: Clone + Debug {
 368
 369     x.clone();
 370     y.clone();
 371     println!("{:?}", y);
 372 }
 373 ```
 374
 375 This flexibility can add clarity in complex situations.
 376
 377 `where` is also more powerful than the simpler syntax. For example:
 378
 379 ```rust
 380 trait ConvertTo<Output> {
 381     fn convert(&self) -> Output;
 382 }
 383
 384 impl ConvertTo<i64> for i32 {
 385     fn convert(&self) -> i64 { *self as i64 }
 386 }
 387
 388 // can be called with T == i32
 389 fn normal<T: ConvertTo<i64>>(x: &T) -> i64 {
 390     x.convert()
 391 }
 392
 393 // can be called with T == i64
 394 fn inverse<T>() -> T
 395         // this is using ConvertTo as if it were "ConvertTo<i64>"
 396         where i32: ConvertTo<T> {
 397     42.convert()
 398 }
 399 ```
 400
 401 This shows off the additional feature of `where` clauses: they allow bounds
 402 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
 403 `ConvertTo<T>`. Rather than defining what `i32` is (since that's obvious), the
 404 `where` clause here constrains `T`.
 405
 406 # Default methods
 407
 408 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()`:
 409
 410 ```rust
 411 trait Foo {
 412     fn is_valid(&self) -> bool;
 413
 414     fn is_invalid(&self) -> bool { !self.is_valid() }
 415 }
 416 ```
 417
 418 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:
 419
 420 ```rust
 421 # trait Foo {
 422 #     fn is_valid(&self) -> bool;
 423 #
 424 #     fn is_invalid(&self) -> bool { !self.is_valid() }
 425 # }
 426 struct UseDefault;
 427
 428 impl Foo for UseDefault {
 429     fn is_valid(&self) -> bool {
 430         println!("Called UseDefault.is_valid.");
 431         true
 432     }
 433 }
 434
 435 struct OverrideDefault;
 436
 437 impl Foo for OverrideDefault {
 438     fn is_valid(&self) -> bool {
 439         println!("Called OverrideDefault.is_valid.");
 440         true
 441     }
 442
 443     fn is_invalid(&self) -> bool {
 444         println!("Called OverrideDefault.is_invalid!");
 445         true // overrides the expected value of is_invalid()
 446     }
 447 }
 448
 449 let default = UseDefault;
 450 assert!(!default.is_invalid()); // prints "Called UseDefault.is_valid."
 451
 452 let over = OverrideDefault;
 453 assert!(over.is_invalid()); // prints "Called OverrideDefault.is_invalid!"
 454 ```
 455
 456 # Inheritance
 457
 458 Sometimes, implementing a trait requires implementing another trait:
 459
 460 ```rust
 461 trait Foo {
 462     fn foo(&self);
 463 }
 464
 465 trait FooBar : Foo {
 466     fn foobar(&self);
 467 }
 468 ```
 469
 470 Implementors of `FooBar` must also implement `Foo`, like this:
 471
 472 ```rust
 473 # trait Foo {
 474 #     fn foo(&self);
 475 # }
 476 # trait FooBar : Foo {
 477 #     fn foobar(&self);
 478 # }
 479 struct Baz;
 480
 481 impl Foo for Baz {
 482     fn foo(&self) { println!("foo"); }
 483 }
 484
 485 impl FooBar for Baz {
 486     fn foobar(&self) { println!("foobar"); }
 487 }
 488 ```
 489
 490 If we forget to implement `Foo`, Rust will tell us:
 491
 492 ```text
 493 error: the trait `main::Foo` is not implemented for the type `main::Baz` [E0277]
 494 ```
 495
 496 # Deriving
 497
 498 Implementing traits like `Debug` and `Default` repeatedly can become
 499 quite tedious. For that reason, Rust provides an [attribute][attributes] that
 500 allows you to let Rust automatically implement traits for you:
 501
 502 ```rust
 503 #[derive(Debug)]
 504 struct Foo;
 505
 506 fn main() {
 507     println!("{:?}", Foo);
 508 }
 509 ```
 510
 511 [attributes]: attributes.html
 512
 513 However, deriving is limited to a certain set of traits:
 514
 515 - [`Clone`](../core/clone/trait.Clone.html)
 516 - [`Copy`](../core/marker/trait.Copy.html)
 517 - [`Debug`](../core/fmt/trait.Debug.html)
 518 - [`Default`](../core/default/trait.Default.html)
 519 - [`Eq`](../core/cmp/trait.Eq.html)
 520 - [`Hash`](../core/hash/trait.Hash.html)
 521 - [`Ord`](../core/cmp/trait.Ord.html)
 522 - [`PartialEq`](../core/cmp/trait.PartialEq.html)
 523 - [`PartialOrd`](../core/cmp/trait.PartialOrd.html)