]> git.proxmox.com Git - rustc.git/blob - src/doc/book/traits.md
Imported Upstream version 1.9.0+dfsg1
[rustc.git] / 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)