src/doc/trpl/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 Do you remember 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 define a trait with just the method
  26 signature, then implement the trait for that struct. Like this:
  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 where the left-hand side is an arbitrary type (`i32` in this case), not just a
 403 plain type parameter (like `T`). In this example, `i32` must implement
 404 `ConvertTo<T>`. Rather than defining what `i32` is (since that's obvious), the
 405 `where` clause here is a constraint on `T`.
 406
 407 # Default methods
 408
 409 If you already know how a typical implementor will define a method, you can
 410 let your trait supply a default:
 411
 412 ```rust
 413 trait Foo {
 414     fn is_valid(&self) -> bool;
 415
 416     fn is_invalid(&self) -> bool { !self.is_valid() }
 417 }
 418 ```
 419
 420 Implementors of the `Foo` trait need to implement `is_valid()`, but they don’t
 421 need to implement `is_invalid()`. They’ll get this default behavior. They can
 422 override the default if they so choose:
 423
 424 ```rust
 425 # trait Foo {
 426 #     fn is_valid(&self) -> bool;
 427 #
 428 #     fn is_invalid(&self) -> bool { !self.is_valid() }
 429 # }
 430 struct UseDefault;
 431
 432 impl Foo for UseDefault {
 433     fn is_valid(&self) -> bool {
 434         println!("Called UseDefault.is_valid.");
 435         true
 436     }
 437 }
 438
 439 struct OverrideDefault;
 440
 441 impl Foo for OverrideDefault {
 442     fn is_valid(&self) -> bool {
 443         println!("Called OverrideDefault.is_valid.");
 444         true
 445     }
 446
 447     fn is_invalid(&self) -> bool {
 448         println!("Called OverrideDefault.is_invalid!");
 449         true // this implementation is a self-contradiction!
 450     }
 451 }
 452
 453 let default = UseDefault;
 454 assert!(!default.is_invalid()); // prints "Called UseDefault.is_valid."
 455
 456 let over = OverrideDefault;
 457 assert!(over.is_invalid()); // prints "Called OverrideDefault.is_invalid!"
 458 ```
 459
 460 # Inheritance
 461
 462 Sometimes, implementing a trait requires implementing another trait:
 463
 464 ```rust
 465 trait Foo {
 466     fn foo(&self);
 467 }
 468
 469 trait FooBar : Foo {
 470     fn foobar(&self);
 471 }
 472 ```
 473
 474 Implementors of `FooBar` must also implement `Foo`, like this:
 475
 476 ```rust
 477 # trait Foo {
 478 #     fn foo(&self);
 479 # }
 480 # trait FooBar : Foo {
 481 #     fn foobar(&self);
 482 # }
 483 struct Baz;
 484
 485 impl Foo for Baz {
 486     fn foo(&self) { println!("foo"); }
 487 }
 488
 489 impl FooBar for Baz {
 490     fn foobar(&self) { println!("foobar"); }
 491 }
 492 ```
 493
 494 If we forget to implement `Foo`, Rust will tell us:
 495
 496 ```text
 497 error: the trait `main::Foo` is not implemented for the type `main::Baz` [E0277]
 498 ```
 499
 500 # Deriving
 501
 502 Implementing traits like `Debug` and `Default` over and over again can become
 503 quite tedious. For that reason, Rust provides an [attribute][attributes] that
 504 allows you to let Rust automatically implement traits for you:
 505
 506 ```rust
 507 #[derive(Debug)]
 508 struct Foo;
 509
 510 fn main() {
 511     println!("{:?}", Foo);
 512 }
 513 ```
 514
 515 [attributes]: attributes.html
 516
 517 However, deriving is limited to a certain set of traits:
 518
 519 - [`Clone`](../core/clone/trait.Clone.html)
 520 - [`Copy`](../core/marker/trait.Copy.html)
 521 - [`Debug`](../core/fmt/trait.Debug.html)
 522 - [`Default`](../core/default/trait.Default.html)
 523 - [`Eq`](../core/cmp/trait.Eq.html)
 524 - [`Hash`](../core/hash/trait.Hash.html)
 525 - [`Ord`](../core/cmp/trait.Ord.html)
 526 - [`PartialEq`](../core/cmp/trait.PartialEq.html)
 527 - [`PartialOrd`](../core/cmp/trait.PartialOrd.html)