src/doc/trpl/operators-and-overloading.md

   1 % Operators and Overloading
   2
   3 Rust allows for a limited form of operator overloading. There are certain
   4 operators that are able to be overloaded. To support a particular operator
   5 between types, there’s a specific trait that you can implement, which then
   6 overloads the operator.
   7
   8 For example, the `+` operator can be overloaded with the `Add` trait:
   9
  10 ```rust
  11 use std::ops::Add;
  12
  13 #[derive(Debug)]
  14 struct Point {
  15     x: i32,
  16     y: i32,
  17 }
  18
  19 impl Add for Point {
  20     type Output = Point;
  21
  22     fn add(self, other: Point) -> Point {
  23         Point { x: self.x + other.x, y: self.y + other.y }
  24     }
  25 }
  26
  27 fn main() {
  28     let p1 = Point { x: 1, y: 0 };
  29     let p2 = Point { x: 2, y: 3 };
  30
  31     let p3 = p1 + p2;
  32
  33     println!("{:?}", p3);
  34 }
  35 ```
  36
  37 In `main`, we can use `+` on our two `Point`s, since we’ve implemented
  38 `Add<Output=Point>` for `Point`.
  39
  40 There are a number of operators that can be overloaded this way, and all of
  41 their associated traits live in the [`std::ops`][stdops] module. Check out its
  42 documentation for the full list.
  43
  44 [stdops]: ../std/ops/index.html
  45
  46 Implementing these traits follows a pattern. Let’s look at [`Add`][add] in more
  47 detail:
  48
  49 ```rust
  50 # mod foo {
  51 pub trait Add<RHS = Self> {
  52     type Output;
  53
  54     fn add(self, rhs: RHS) -> Self::Output;
  55 }
  56 # }
  57 ```
  58
  59 [add]: ../std/ops/trait.Add.html
  60
  61 There’s three types in total involved here: the type you `impl Add` for, `RHS`,
  62 which defaults to `Self`, and `Output`. For an expression `let z = x + y`, `x`
  63 is the `Self` type, `y` is the RHS, and `z` is the `Self::Output` type.
  64
  65 ```rust
  66 # struct Point;
  67 # use std::ops::Add;
  68 impl Add<i32> for Point {
  69     type Output = f64;
  70
  71     fn add(self, rhs: i32) -> f64 {
  72         // add an i32 to a Point and get an f64
  73 # 1.0
  74     }
  75 }
  76 ```
  77
  78 will let you do this:
  79
  80 ```rust,ignore
  81 let p: Point = // ...
  82 let x: f64 = p + 2i32;
  83 ```
  84
  85 # Using operator traits in generic structs
  86
  87 Now that we know how operator traits are defined, we can define our `HasArea`
  88 trait and `Square` struct from the [traits chapter][traits] more generically:
  89
  90 [traits]: traits.html
  91
  92 ```rust
  93 use std::ops::Mul;
  94
  95 trait HasArea<T> {
  96     fn area(&self) -> T;
  97 }
  98
  99 struct Square<T> {
 100     x: T,
 101     y: T,
 102     side: T,
 103 }
 104
 105 impl<T> HasArea<T> for Square<T>
 106         where T: Mul<Output=T> + Copy {
 107     fn area(&self) -> T {
 108         self.side * self.side
 109     }
 110 }
 111
 112 fn main() {
 113     let s = Square {
 114         x: 0.0f64,
 115         y: 0.0f64,
 116         side: 12.0f64,
 117     };
 118
 119     println!("Area of s: {}", s.area());
 120 }
 121 ```
 122
 123 For `HasArea` and `Square`, we just declare a type parameter `T` and replace
 124 `f64` with it. The `impl` needs more involved modifications:
 125
 126 ```ignore
 127 impl<T> HasArea<T> for Square<T>
 128         where T: Mul<Output=T> + Copy { ... }
 129 ```
 130
 131 The `area` method requires that we can multiply the sides, so we declare that
 132 type `T` must implement `std::ops::Mul`. Like `Add`, mentioned above, `Mul`
 133 itself takes an `Output` parameter: since we know that numbers don't change
 134 type when multiplied, we also set it to `T`. `T` must also support copying, so
 135 Rust doesn't try to move `self.side` into the return value.