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, only a type signature. When we `impl` a trait,
  48 we use `impl Trait for Item`, rather than only `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 bound `_ : HasArea` is not satisfied [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
 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].
 285
 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.
 290
 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.
 294
 295 [cm]: crates-and-modules.html
 296 [to]: trait-objects.html
 297
 298 # Multiple trait bounds
 299
 300 You’ve seen that you can bound a generic type parameter with a trait:
 301
 302 ```rust
 303 fn foo<T: Clone>(x: T) {
 304     x.clone();
 305 }
 306 ```
 307
 308 If you need more than one bound, you can use `+`:
 309
 310 ```rust
 311 use std::fmt::Debug;
 312
 313 fn foo<T: Clone + Debug>(x: T) {
 314     x.clone();
 315     println!("{:?}", x);
 316 }
 317 ```
 318
 319 `T` now needs to be both `Clone` as well as `Debug`.
 320
 321 # Where clause
 322
 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
 325 awkward:
 326
 327 ```rust
 328 use std::fmt::Debug;
 329
 330 fn foo<T: Clone, K: Clone + Debug>(x: T, y: K) {
 331     x.clone();
 332     y.clone();
 333     println!("{:?}", y);
 334 }
 335 ```
 336
 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.
 339
 340 Rust has a solution, and it’s called a ‘`where` clause’:
 341
 342 ```rust
 343 use std::fmt::Debug;
 344
 345 fn foo<T: Clone, K: Clone + Debug>(x: T, y: K) {
 346     x.clone();
 347     y.clone();
 348     println!("{:?}", y);
 349 }
 350
 351 fn bar<T, K>(x: T, y: K) where T: Clone, K: Clone + Debug {
 352     x.clone();
 353     y.clone();
 354     println!("{:?}", y);
 355 }
 356
 357 fn main() {
 358     foo("Hello", "world");
 359     bar("Hello", "world");
 360 }
 361 ```
 362
 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
 366 be added:
 367
 368 ```rust
 369 use std::fmt::Debug;
 370
 371 fn bar<T, K>(x: T, y: K)
 372     where T: Clone,
 373           K: Clone + Debug {
 374
 375     x.clone();
 376     y.clone();
 377     println!("{:?}", y);
 378 }
 379 ```
 380
 381 This flexibility can add clarity in complex situations.
 382
 383 `where` is also more powerful than the simpler syntax. For example:
 384
 385 ```rust
 386 trait ConvertTo<Output> {
 387     fn convert(&self) -> Output;
 388 }
 389
 390 impl ConvertTo<i64> for i32 {
 391     fn convert(&self) -> i64 { *self as i64 }
 392 }
 393
 394 // can be called with T == i32
 395 fn normal<T: ConvertTo<i64>>(x: &T) -> i64 {
 396     x.convert()
 397 }
 398
 399 // can be called with T == i64
 400 fn inverse<T>() -> T
 401         // this is using ConvertTo as if it were "ConvertTo<i64>"
 402         where i32: ConvertTo<T> {
 403     42.convert()
 404 }
 405 ```
 406
 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`.
 411
 412 # Default methods
 413
 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()`:
 415
 416 ```rust
 417 trait Foo {
 418     fn is_valid(&self) -> bool;
 419
 420     fn is_invalid(&self) -> bool { !self.is_valid() }
 421 }
 422 ```
 423
 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:
 425
 426 ```rust
 427 # trait Foo {
 428 #     fn is_valid(&self) -> bool;
 429 #
 430 #     fn is_invalid(&self) -> bool { !self.is_valid() }
 431 # }
 432 struct UseDefault;
 433
 434 impl Foo for UseDefault {
 435     fn is_valid(&self) -> bool {
 436         println!("Called UseDefault.is_valid.");
 437         true
 438     }
 439 }
 440
 441 struct OverrideDefault;
 442
 443 impl Foo for OverrideDefault {
 444     fn is_valid(&self) -> bool {
 445         println!("Called OverrideDefault.is_valid.");
 446         true
 447     }
 448
 449     fn is_invalid(&self) -> bool {
 450         println!("Called OverrideDefault.is_invalid!");
 451         true // overrides the expected value of is_invalid()
 452     }
 453 }
 454
 455 let default = UseDefault;
 456 assert!(!default.is_invalid()); // prints "Called UseDefault.is_valid."
 457
 458 let over = OverrideDefault;
 459 assert!(over.is_invalid()); // prints "Called OverrideDefault.is_invalid!"
 460 ```
 461
 462 # Inheritance
 463
 464 Sometimes, implementing a trait requires implementing another trait:
 465
 466 ```rust
 467 trait Foo {
 468     fn foo(&self);
 469 }
 470
 471 trait FooBar : Foo {
 472     fn foobar(&self);
 473 }
 474 ```
 475
 476 Implementors of `FooBar` must also implement `Foo`, like this:
 477
 478 ```rust
 479 # trait Foo {
 480 #     fn foo(&self);
 481 # }
 482 # trait FooBar : Foo {
 483 #     fn foobar(&self);
 484 # }
 485 struct Baz;
 486
 487 impl Foo for Baz {
 488     fn foo(&self) { println!("foo"); }
 489 }
 490
 491 impl FooBar for Baz {
 492     fn foobar(&self) { println!("foobar"); }
 493 }
 494 ```
 495
 496 If we forget to implement `Foo`, Rust will tell us:
 497
 498 ```text
 499 error: the trait bound `main::Baz : main::Foo` is not satisfied [E0277]
 500 ```
 501
 502 # Deriving
 503
 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:
 507
 508 ```rust
 509 #[derive(Debug)]
 510 struct Foo;
 511
 512 fn main() {
 513     println!("{:?}", Foo);
 514 }
 515 ```
 516
 517 [attributes]: attributes.html
 518
 519 However, deriving is limited to a certain set of traits:
 520
 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)