src/doc/book/src/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 `Self` may be used in a type annotation to refer to an instance of the type
  51 implementing this trait passed as a parameter. `Self`, `&Self` or `&mut Self`
  52 may be used depending on the level of ownership required.
  53
  54 ```rust
  55 struct Circle {
  56     x: f64,
  57     y: f64,
  58     radius: f64,
  59 }
  60
  61 trait HasArea {
  62     fn area(&self) -> f64;
  63
  64     fn is_larger(&self, &Self) -> bool;
  65 }
  66
  67 impl HasArea for Circle {
  68     fn area(&self) -> f64 {
  69         std::f64::consts::PI * (self.radius * self.radius)
  70     }
  71
  72     fn is_larger(&self, other: &Self) -> bool {
  73         self.area() > other.area()
  74     }
  75 }
  76 ```
  77
  78 ## Trait bounds on generic functions
  79
  80 Traits are useful because they allow a type to make certain promises about its
  81 behavior. Generic functions can exploit this to constrain, or [bound][bounds], the types they
  82 accept. Consider this function, which does not compile:
  83
  84 [bounds]: glossary.html#bounds
  85
  86 ```rust,ignore
  87 fn print_area<T>(shape: T) {
  88     println!("This shape has an area of {}", shape.area());
  89 }
  90 ```
  91
  92 Rust complains:
  93
  94 ```text
  95 error: no method named `area` found for type `T` in the current scope
  96 ```
  97
  98 Because `T` can be any type, we can’t be sure that it implements the `area`
  99 method. But we can add a trait bound to our generic `T`, ensuring
 100 that it does:
 101
 102 ```rust
 103 # trait HasArea {
 104 #     fn area(&self) -> f64;
 105 # }
 106 fn print_area<T: HasArea>(shape: T) {
 107     println!("This shape has an area of {}", shape.area());
 108 }
 109 ```
 110
 111 The syntax `<T: HasArea>` means “any type that implements the `HasArea` trait.”
 112 Because traits define function type signatures, we can be sure that any type
 113 which implements `HasArea` will have an `.area()` method.
 114
 115 Here’s an extended example of how this works:
 116
 117 ```rust
 118 trait HasArea {
 119     fn area(&self) -> f64;
 120 }
 121
 122 struct Circle {
 123     x: f64,
 124     y: f64,
 125     radius: f64,
 126 }
 127
 128 impl HasArea for Circle {
 129     fn area(&self) -> f64 {
 130         std::f64::consts::PI * (self.radius * self.radius)
 131     }
 132 }
 133
 134 struct Square {
 135     x: f64,
 136     y: f64,
 137     side: f64,
 138 }
 139
 140 impl HasArea for Square {
 141     fn area(&self) -> f64 {
 142         self.side * self.side
 143     }
 144 }
 145
 146 fn print_area<T: HasArea>(shape: T) {
 147     println!("This shape has an area of {}", shape.area());
 148 }
 149
 150 fn main() {
 151     let c = Circle {
 152         x: 0.0f64,
 153         y: 0.0f64,
 154         radius: 1.0f64,
 155     };
 156
 157     let s = Square {
 158         x: 0.0f64,
 159         y: 0.0f64,
 160         side: 1.0f64,
 161     };
 162
 163     print_area(c);
 164     print_area(s);
 165 }
 166 ```
 167
 168 This program outputs:
 169
 170 ```text
 171 This shape has an area of 3.141593
 172 This shape has an area of 1
 173 ```
 174
 175 As you can see, `print_area` is now generic, but also ensures that we have
 176 passed in the correct types. If we pass in an incorrect type:
 177
 178 ```rust,ignore
 179 print_area(5);
 180 ```
 181
 182 We get a compile-time error:
 183
 184 ```text
 185 error: the trait bound `_ : HasArea` is not satisfied [E0277]
 186 ```
 187
 188 ## Trait bounds on generic structs
 189
 190 Your generic structs can also benefit from trait bounds. All you need to
 191 do is append the bound when you declare type parameters. Here is a new
 192 type `Rectangle<T>` and its operation `is_square()`:
 193
 194 ```rust
 195 struct Rectangle<T> {
 196     x: T,
 197     y: T,
 198     width: T,
 199     height: T,
 200 }
 201
 202 impl<T: PartialEq> Rectangle<T> {
 203     fn is_square(&self) -> bool {
 204         self.width == self.height
 205     }
 206 }
 207
 208 fn main() {
 209     let mut r = Rectangle {
 210         x: 0,
 211         y: 0,
 212         width: 47,
 213         height: 47,
 214     };
 215
 216     assert!(r.is_square());
 217
 218     r.height = 42;
 219     assert!(!r.is_square());
 220 }
 221 ```
 222
 223 `is_square()` needs to check that the sides are equal, so the sides must be of
 224 a type that implements the [`core::cmp::PartialEq`][PartialEq] trait:
 225
 226 ```rust,ignore
 227 impl<T: PartialEq> Rectangle<T> { ... }
 228 ```
 229
 230 Now, a rectangle can be defined in terms of any type that can be compared for
 231 equality.
 232
 233 [PartialEq]: ../core/cmp/trait.PartialEq.html
 234
 235 Here we defined a new struct `Rectangle` that accepts numbers of any
 236 precision—really, objects of pretty much any type—as long as they can be
 237 compared for equality. Could we do the same for our `HasArea` structs, `Square`
 238 and `Circle`? Yes, but they need multiplication, and to work with that we need
 239 to know more about [operator traits][operators-and-overloading].
 240
 241 [operators-and-overloading]: operators-and-overloading.html
 242
 243 # Rules for implementing traits
 244
 245 So far, we’ve only added trait implementations to structs, but you can
 246 implement a trait for any type such as `f32`:
 247
 248 ```rust
 249 trait ApproxEqual {
 250     fn approx_equal(&self, other: &Self) -> bool;
 251 }
 252 impl ApproxEqual for f32 {
 253     fn approx_equal(&self, other: &Self) -> bool {
 254         // Appropriate for `self` and `other` being close to 1.0.
 255         (self - other).abs() <= ::std::f32::EPSILON
 256     }
 257 }
 258
 259 println!("{}", 1.0.approx_equal(&1.00000001));
 260 ```
 261
 262 This may seem like the Wild West, but there are two restrictions around
 263 implementing traits that prevent this from getting out of hand. The first is
 264 that if the trait isn’t defined in your scope, it doesn’t apply. Here’s an
 265 example: the standard library provides a [`Write`][write] trait which adds
 266 extra functionality to `File`s, for doing file I/O. By default, a `File`
 267 won’t have its methods:
 268
 269 [write]: ../std/io/trait.Write.html
 270
 271 ```rust,ignore
 272 let mut f = std::fs::File::create("foo.txt").expect("Couldn’t create foo.txt");
 273 let buf = b"whatever"; // buf: &[u8; 8], a byte string literal.
 274 let result = f.write(buf);
 275 # result.unwrap(); // Ignore the error.
 276 ```
 277
 278 Here’s the error:
 279
 280 ```text
 281 error: type `std::fs::File` does not implement any method in scope named `write`
 282 let result = f.write(buf);
 283                ^~~~~~~~~~
 284 ```
 285
 286 We need to `use` the `Write` trait first:
 287
 288 ```rust,no_run
 289 use std::io::Write;
 290
 291 let mut f = std::fs::File::create("foo.txt").expect("Couldn’t create foo.txt");
 292 let buf = b"whatever";
 293 let result = f.write(buf);
 294 # result.unwrap(); // Ignore the error.
 295 ```
 296
 297 This will compile without error.
 298
 299 This means that even if someone does something bad like add methods to `i32`,
 300 it won’t affect you, unless you `use` that trait.
 301
 302 There’s one more restriction on implementing traits: either the trait
 303 or the type you’re implementing it for must be defined by you. Or more
 304 precisely, one of them must be defined in the same crate as the `impl`
 305 you're writing. For more on Rust's module and package system, see the
 306 chapter on [crates and modules][cm].
 307
 308 So, we could implement the `HasArea` type for `i32`, because we defined
 309 `HasArea` in our code. But if we tried to implement `ToString`, a trait
 310 provided by Rust, for `i32`, we could not, because neither the trait nor
 311 the type are defined in our crate.
 312
 313 One last thing about traits: generic functions with a trait bound use
 314 ‘monomorphization’ (mono: one, morph: form), so they are statically dispatched.
 315 What’s that mean? Check out the chapter on [trait objects][to] for more details.
 316
 317 [cm]: crates-and-modules.html
 318 [to]: trait-objects.html
 319
 320 # Multiple trait bounds
 321
 322 You’ve seen that you can bound a generic type parameter with a trait:
 323
 324 ```rust
 325 fn foo<T: Clone>(x: T) {
 326     x.clone();
 327 }
 328 ```
 329
 330 If you need more than one bound, you can use `+`:
 331
 332 ```rust
 333 use std::fmt::Debug;
 334
 335 fn foo<T: Clone + Debug>(x: T) {
 336     x.clone();
 337     println!("{:?}", x);
 338 }
 339 ```
 340
 341 `T` now needs to be both `Clone` as well as `Debug`.
 342
 343 # Where clause
 344
 345 Writing functions with only a few generic types and a small number of trait
 346 bounds isn’t too bad, but as the number increases, the syntax gets increasingly
 347 awkward:
 348
 349 ```rust
 350 use std::fmt::Debug;
 351
 352 fn foo<T: Clone, K: Clone + Debug>(x: T, y: K) {
 353     x.clone();
 354     y.clone();
 355     println!("{:?}", y);
 356 }
 357 ```
 358
 359 The name of the function is on the far left, and the parameter list is on the
 360 far right. The bounds are getting in the way.
 361
 362 Rust has a solution, and it’s called a ‘`where` clause’:
 363
 364 ```rust
 365 use std::fmt::Debug;
 366
 367 fn foo<T: Clone, K: Clone + Debug>(x: T, y: K) {
 368     x.clone();
 369     y.clone();
 370     println!("{:?}", y);
 371 }
 372
 373 fn bar<T, K>(x: T, y: K) where T: Clone, K: Clone + Debug {
 374     x.clone();
 375     y.clone();
 376     println!("{:?}", y);
 377 }
 378
 379 fn main() {
 380     foo("Hello", "world");
 381     bar("Hello", "world");
 382 }
 383 ```
 384
 385 `foo()` uses the syntax we showed earlier, and `bar()` uses a `where` clause.
 386 All you need to do is leave off the bounds when defining your type parameters,
 387 and then add `where` after the parameter list. For longer lists, whitespace can
 388 be added:
 389
 390 ```rust
 391 use std::fmt::Debug;
 392
 393 fn bar<T, K>(x: T, y: K)
 394     where T: Clone,
 395           K: Clone + Debug {
 396
 397     x.clone();
 398     y.clone();
 399     println!("{:?}", y);
 400 }
 401 ```
 402
 403 This flexibility can add clarity in complex situations.
 404
 405 `where` is also more powerful than the simpler syntax. For example:
 406
 407 ```rust
 408 trait ConvertTo<Output> {
 409     fn convert(&self) -> Output;
 410 }
 411
 412 impl ConvertTo<i64> for i32 {
 413     fn convert(&self) -> i64 { *self as i64 }
 414 }
 415
 416 // Can be called with T == i32.
 417 fn normal<T: ConvertTo<i64>>(x: &T) -> i64 {
 418     x.convert()
 419 }
 420
 421 // Can be called with T == i64.
 422 fn inverse<T>(x: i32) -> T
 423         // This is using ConvertTo as if it were "ConvertTo<i64>".
 424         where i32: ConvertTo<T> {
 425     x.convert()
 426 }
 427 ```
 428
 429 This shows off the additional feature of `where` clauses: they allow bounds
 430 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
 431 `ConvertTo<T>`. Rather than defining what `i32` is (since that's obvious), the
 432 `where` clause here constrains `T`.
 433
 434 # Default methods
 435
 436 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()`:
 437
 438 ```rust
 439 trait Foo {
 440     fn is_valid(&self) -> bool;
 441
 442     fn is_invalid(&self) -> bool { !self.is_valid() }
 443 }
 444 ```
 445
 446 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:
 447
 448 ```rust
 449 # trait Foo {
 450 #     fn is_valid(&self) -> bool;
 451 #
 452 #     fn is_invalid(&self) -> bool { !self.is_valid() }
 453 # }
 454 struct UseDefault;
 455
 456 impl Foo for UseDefault {
 457     fn is_valid(&self) -> bool {
 458         println!("Called UseDefault.is_valid.");
 459         true
 460     }
 461 }
 462
 463 struct OverrideDefault;
 464
 465 impl Foo for OverrideDefault {
 466     fn is_valid(&self) -> bool {
 467         println!("Called OverrideDefault.is_valid.");
 468         true
 469     }
 470
 471     fn is_invalid(&self) -> bool {
 472         println!("Called OverrideDefault.is_invalid!");
 473         true // Overrides the expected value of `is_invalid()`.
 474     }
 475 }
 476
 477 let default = UseDefault;
 478 assert!(!default.is_invalid()); // Prints "Called UseDefault.is_valid."
 479
 480 let over = OverrideDefault;
 481 assert!(over.is_invalid()); // Prints "Called OverrideDefault.is_invalid!"
 482 ```
 483
 484 # Inheritance
 485
 486 Sometimes, implementing a trait requires implementing another trait:
 487
 488 ```rust
 489 trait Foo {
 490     fn foo(&self);
 491 }
 492
 493 trait FooBar : Foo {
 494     fn foobar(&self);
 495 }
 496 ```
 497
 498 Implementors of `FooBar` must also implement `Foo`, like this:
 499
 500 ```rust
 501 # trait Foo {
 502 #     fn foo(&self);
 503 # }
 504 # trait FooBar : Foo {
 505 #     fn foobar(&self);
 506 # }
 507 struct Baz;
 508
 509 impl Foo for Baz {
 510     fn foo(&self) { println!("foo"); }
 511 }
 512
 513 impl FooBar for Baz {
 514     fn foobar(&self) { println!("foobar"); }
 515 }
 516 ```
 517
 518 If we forget to implement `Foo`, Rust will tell us:
 519
 520 ```text
 521 error: the trait bound `main::Baz : main::Foo` is not satisfied [E0277]
 522 ```
 523
 524 # Deriving
 525
 526 Implementing traits like `Debug` and `Default` repeatedly can become
 527 quite tedious. For that reason, Rust provides an [attribute][attributes] that
 528 allows you to let Rust automatically implement traits for you:
 529
 530 ```rust
 531 #[derive(Debug)]
 532 struct Foo;
 533
 534 fn main() {
 535     println!("{:?}", Foo);
 536 }
 537 ```
 538
 539 [attributes]: attributes.html
 540
 541 However, deriving is limited to a certain set of traits:
 542
 543 - [`Clone`](../core/clone/trait.Clone.html)
 544 - [`Copy`](../core/marker/trait.Copy.html)
 545 - [`Debug`](../core/fmt/trait.Debug.html)
 546 - [`Default`](../core/default/trait.Default.html)
 547 - [`Eq`](../core/cmp/trait.Eq.html)
 548 - [`Hash`](../core/hash/trait.Hash.html)
 549 - [`Ord`](../core/cmp/trait.Ord.html)
 550 - [`PartialEq`](../core/cmp/trait.PartialEq.html)
 551 - [`PartialOrd`](../core/cmp/trait.PartialOrd.html)