TRPL: operators and overloading

I forgot these heavily use associated types, so move it after that
as well.

Author: steveklabnik

src/doc/trpl/SUMMARY.md

@@ -37,7 +37,6 @@
     * [Strings](strings.md)
     * [Generics](generics.md)
     * [Traits](traits.md)
-    * [Operators and Overloading](operators-and-overloading.md)
     * [Drop](drop.md)
     * [if let](if-let.md)
     * [Trait Objects](trait-objects.md)
@@ -51,6 +50,7 @@
     * [Casting between types](casting-between-types.md)
     * [Associated Types](associated-types.md)
     * [Unsized Types](unsized-types.md)
+    * [Operators and Overloading](operators-and-overloading.md)
     * [Deref coercions](deref-coercions.md)
     * [Macros](macros.md)
     * [Raw Pointers](raw-pointers.md)

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

@@ -1,3 +1,85 @@
 % Operators and Overloading
 
-Coming soon!
+Rust does not have general support for overloading operators or creating new
+operators. However, there are certain operators in Rust that _are_ able to
+be overloaded. To support a particular operator between types, there’s a
+specific trait that you can implement, which then overloads the operator.
+
+For example, the `+` operator can be overloaded with the `Add` trait:
+
+```rust
+use std::ops::Add;
+
+#[derive(Debug)]
+struct Point {
+    x: i32,
+    y: i32,
+}
+
+impl Add for Point {
+    type Output = Point;
+
+    fn add(self, other: Point) -> Point {
+        Point { x: self.x + other.x, y: self.y + other.y }
+    }
+}
+
+fn main() {
+    let p1 = Point { x: 1, y: 0 };
+    let p2 = Point { x: 2, y: 3 };
+
+    let p3 = p1 + p2;
+
+    println!("{:?}", p3);
+}
+```
+
+In `main`, we can use `+` on our two `Point`s, since `we’ve implemented
+`Add<Output=Point>` for `Point`.
+
+All of these traits follow a similar pattern. Let’s look at [`Add`][] in more detail:
+
+```rust
+# mod foo {
+pub trait Add<RHS = Self> {
+    type Output;
+
+    fn add(self, rhs: RHS) -> Self::Output;
+}
+# }
+```
+
+[add]: ../std/ops/trait.Add.html
+
+There’s three types in total involved here: the type you `impl Add` for, and
+two [associated types][at]: `RHS`, which defaults to `Self`, and `Output`. They
+correspond to the three parts of `x + y = z`: the type you `impl` for is `x`,
+`RHS` is `y`, and `Output` is `z`. So this:
+
+```rust
+# struct Point;
+# use std::ops::Add;
+impl Add<i32> for Point {
+    type Output = f64;
+
+    fn add(self, rhs: i32) -> f64 {
+        // add an i32 to a Point and get an f64
+# 1.0
+    }
+}
+```
+
+[at]: associated-types.html
+
+will let you do this:
+
+```rust,ignore
+let p: Point = // ...
+let x: f64 = p + 2i32;
+```
+
+There are a number of operators that can be overloaded this way, and all of
+their associated traits live in the [`std::ops`][stdops] module. Check out its
+documentation for the details.
+
+[stdops]: ../std/ops/index.html