trpl/enums: Rewrite

Author: geofft

src/doc/trpl/SUMMARY.md

@@ -27,9 +27,9 @@
     * [References and Borrowing](references-and-borrowing.md)
     * [Lifetimes](lifetimes.md)
     * [Mutability](mutability.md)
-    * [Enums](enums.md)
     * [Match](match.md)
     * [Structs](structs.md)
+    * [Enums](enums.md)
     * [Patterns](patterns.md)
     * [Method Syntax](method-syntax.md)
     * [Vectors](vectors.md)

src/doc/trpl/enums.md

@@ -2,67 +2,76 @@
 
 Rust has a ‘sum type’, an `enum`. Enums are an incredibly useful feature of
 Rust, and are used throughout the standard library. An `enum` is a type which
-relates a set of alternates to a specific name. For example, below we define
-`Character` to be either a `Digit` or something else.
+relates a set of alternates to a specific name. Each variant of an
+`enum` is defined like a struct, and can hold any data (or no data, like
+a unit-like struct).
 
 ```rust
-enum Character {
-    Digit(i32),
-    Other,
+enum Message {
+    Quit,
+    ChangeColor(i32, i32, i32),
+    Move { x: i32, y: i32 },
+    Write(String),
 }
 ```
 
-Most types are allowed as the variant components of an `enum`. Here are some
-examples:
+We use the `::` syntax to use the name of each variant: they’re scoped by the name
+of the `enum` itself. This allows both of these to work:
 
 ```rust
-struct Empty;
-struct Color(i32, i32, i32);
-struct Length(i32);
-struct Stats { Health: i32, Mana: i32, Attack: i32, Defense: i32 }
-struct HeightDatabase(Vec<i32>);
-```
-
-You see that, depending on its type, an `enum` variant may or may not hold data.
-In `Character`, for instance, `Digit` gives a meaningful name for an `i32`
-value, where `Other` is only a name. However, the fact that they represent
-distinct categories of `Character` is a very useful property.
-
-The variants of an `enum` by default are not comparable with equality operators
-(`==`, `!=`), have no ordering (`<`, `>=`, etc.), and do not support other
-binary operations such as `*` and `+`. As such, the following code is invalid
-for the example `Character` type:
+# enum Message {
+#     Move { x: i32, y: i32 },
+# }
+let x = Message::Move { x: 3, y: 4 };
 
-```rust,ignore
-// These assignments both succeed
-let ten  = Character::Digit(10);
-let four = Character::Digit(4);
-
-// Error: `*` is not implemented for type `Character`
-let forty = ten * four;
-
-// Error: `<=` is not implemented for type `Character`
-let four_is_smaller = four <= ten;
+enum BoardGame {
+    Move { squares: i32 },
+    Pass,
+}
 
-// Error: `==` is not implemented for type `Character`
-let four_equals_ten = four == ten;
+let y = BoardGame::Move { squares: 1 };
 ```
 
-We use the `::` syntax to use the name of each variant: They’re scoped by the name
-of the `enum` itself. This allows both of these to work:
+Both variants are named `Move`, but since they’re scoped to the name of
+the enum, they can both be used without conflict.
+
+Rust’s enums are similar to C’s enums, but they can also hold data. In
+this respect, they are also somewhat similar to C unions. Unlike C
+unions, however, Rust enums carry information about which variant a
+particular instance of the union is. (This is sometimes referred to as a
+‘tagged union’ in other languages.) The compiler uses this information
+to enforce that you’re accessing the data in the enum safely:
 
 ```rust,ignore
-Character::Digit(10);
-Hand::Digit;
+fn process_color_change(msg: Message) {
+    let Message::ChangeColor(r, g, b) = msg; // compile-time error
+}
 ```
 
-Both variants are named `Digit`, but since they’re scoped to the `enum` name,
+You can use [matches][match] to process all possible variants of a union (or
+the [`if let`][if-let] statement, which we’ll see later, to match on a
+single one):
 
-Not supporting these operations may seem rather limiting, but it’s a limitation
-which we can overcome. There are two ways: by implementing equality ourselves,
-or by pattern matching variants with [`match`][match] expressions, which you’ll
-learn in the next section. We don’t know enough about Rust to implement
-equality yet, but we’ll find out in the [`traits`][traits] section.
+```rust
+# enum Message {
+#     Quit,
+#     ChangeColor(i32, i32, i32),
+#     Move { x: i32, y: i32 },
+#     Write(String),
+# }
+fn quit() { /* ... */ }
+fn change_color(r: i32, g: i32, b: i32) { /* ... */ }
+fn move_cursor(x: i32, y: i32) { /* ... */ }
+
+fn process_message(msg: Message) {
+    match msg {
+        Message::Quit => quit(),
+        Message::ChangeColor(r, g, b) => change_color(r, g, b),
+        Message::Move { x: x, y: y } => move_cursor(x, y),
+        Message::Write(s) => println!("{}", s),
+    }
+}
+```
 
 [match]: match.html
-[traits]: traits.html
+[if-let]: if-let.html