Clarifications to traits post

Author: aturon

_posts/2015-05-11-traits.md

@@ -145,9 +145,9 @@ impl Hash for i64 {
 }
 ```
 
-Unlike interfaces in languages like Java, C# or Scala, new traits can be implemented
-for existing types (as with `Hash` above). **Code in upstream crates can be
-adapted to interfaces in downstream crates**.
+Unlike interfaces in languages like Java, C# or Scala, **new traits can be
+implemented for existing types** (as with `Hash` above). That means abstractions
+can be created after-the-fact, and applied to existing libraries.
 
 Unlike inherent methods, trait methods are in scope only when their trait
 is. But assuming `Hash` is in scope, you can write `true.hash()`, so
@@ -181,7 +181,13 @@ C++ templates, the compiler will generate *two copies* of the `print_hash`
 method to handle the above code, one for each concrete argument type.  That in
 turn means that the internal call to `t.hash()` -- the point where the
 abstraction is actually used -- has zero cost: it will be compiled to a direct,
-static call to the relevant implementation.
+static call to the relevant implementation:
+
+```rust
+// The compiled code:
+__print_hash_bool(&true);  // invoke specialized bool version directly
+__print_hash_i64(&true);   // invoke specialized i64 version directly
+```
 
 This compilation model isn't so useful for a function like `print_hash`, but
 it's *very* useful for more realistic uses of hashing. Suppose we also introduce
@@ -214,6 +220,7 @@ The static compilation model for generics will then yield several benefits:
   there is no extra cost dispatching to calls to `hash` and `eq`, as above.  It
   also means that the optimizer gets to work with the fully concrete code --
   that is, from the point of view of the optimizer, *there is no abstraction*.
+  In particular, static dispatch allows for *inlining* across uses of generics.
 
 Altogether, just as in C++ templates, these aspects of generics mean that you
 can write quite high-level abstractions that are *guaranteed* to compile down to
@@ -226,36 +233,6 @@ rather than being checked repeatedly when applied to concrete types. That means
 earlier, clearer compilation errors for library authors, and less typechecking
 overhead for clients.
 
-#### Conditional trait implementation
-
-Generics also make it possible to implement a trait *conditionally*:
-
-```rust
-struct Pair<A, B> {
-    first: A,
-    second: B,
-}
-
-impl<A: Hash, B: Hash> Hash for Pair<A, B> {
-    fn hash(&self) -> u64 {
-        self.first.hash()
-            .xor(self.second.hash())
-            .wrapping_mul(0x100000001b3);
-    }
-}
-```
-
-Here, the `Pair` type implements `Hash` if, and only if, its components
-do. Conditional implementation enables flexible reuse of code: it would be a
-shame to have to introduce separate `Pair` types that varied by the traits their
-components implement. It's such a common pattern in Rust that there is built-in
-support for generating certain kinds of "mechanical" implementations automatically:
-
-```rust
-#[derive(Hash)]
-struct Pair<A, B> { .. }
-```
-
 ### Dynamic dispatch
 
 We've seen one compilation model for traits, where all abstraction is compiled
@@ -330,6 +307,32 @@ wind up playing a few other important roles in Rust. Here's a taste:
   simply particular traits. You can read more about how this works in
   Huon Wilson's [in-depth post][closures] on the topic.
 
+* **Conditional APIs**. Generics make it possible to implement a trait
+  conditionally:
+
+  ```rust
+  struct Pair<A, B> { first: A, second: B }
+
+  impl<A: Hash, B: Hash> Hash for Pair<A, B> {
+      fn hash(&self) -> u64 {
+          self.first.hash()
+              .xor(self.second.hash())
+              .wrapping_mul(0x100000001b3);
+      }
+  }
+  ```
+
+  Here, the `Pair` type implements `Hash` if, and only if, its components do --
+  allowing the single `Pair` type to be used in different contexts, while
+  supporting the largest API available for each context.  It's such a common
+  pattern in Rust that there is built-in support for generating certain kinds of
+  "mechanical" implementations automatically:
+
+  ```rust
+  #[derive(Hash)]
+  struct Pair<A, B> { .. }
+  ```
+
 * **Extension methods**. Traits can be used to extend an existing type (defined
   elsewhere) with new methods, for convenience, similarly to C#'s extension
   methods. This falls directly out of the scoping rules for traits: you just