Formatting chapter: Add example about Show

examples/staging/fmt/input.md

@@ -0,0 +1,34 @@
+We've seen that formatting is specified via a *format string*:
+
+* `format!("{}", foo)` -> `"3735928559"`
+* `format!("0x{:X}", foo)` ->
+  [`"0xDEADBEEF"`](https://en.wikipedia.org/wiki/Deadbeef#Magic_debug_values)
+* `format!("0o{:o}", foo)` -> `"0o33653337357"`
+
+The same variable (`foo`) can be formatted differently depending on which
+*argument type* is used: `X` vs `o` vs *unspecified*.
+
+This formatting functionality is implemented via traits, and there is one trait
+for each argument type. The most common formatting trait is `Show`, which
+handles cases where the argument type is left unspecified: `{}` for instance.
+
+{show.play}
+
+Here's the full list of formatting traits and their respective argument types:
+
+* *unspecified* -> `Show`
+* `d` and `i` -> `Signed`
+* `u` -> `Unsigned`
+* `b` -> `Bool`
+* `c` -> `Char`
+* `o` -> `Octal`
+* `x` -> `LowerHex`
+* `X` -> `UpperHex`
+* `s` -> `String`
+* `p` -> `Pointer`
+* `t` -> `Binary`
+* `f` -> `Float`
+* `e` -> `LowerExp`
+* `E` -> `UpperExp`
+* `?` -> `Poly`
+

examples/staging/fmt/show.rs

@@ -0,0 +1,34 @@
+use std::fmt::{mod,Formatter,Show};
+use std::num::abs;
+
+struct City {
+    name: &'static str,
+    // Latitude
+    lat: f32,
+    // Longitude
+    lon: f32,
+}
+
+impl Show for City {
+    // `f` is a buffer, this method must write the formatted string into it
+    fn fmt(&self, f: &mut Formatter) -> fmt::Result {
+        let lat_c = if self.lat >= 0.0 { 'N' } else { 'S' };
+        let lon_c = if self.lon >= 0.0 { 'E' } else { 'W' };
+
+        // `write!` is like `format!`, but it will write the formatted string
+        // into a buffer (the first argument)
+        write!(f, "{}: {:.3f}°{} {:.3f}°{}",
+               self.name, abs(self.lat), lat_c, abs(self.lon), lon_c)
+    }
+}
+
+fn main() {
+    for city in [
+        City { name: "Dublin", lat: 53.347778, lon: -6.259722 },
+        City { name: "Oslo", lat: 59.95, lon: 10.75 },
+        City { name: "Vancouver", lat: 49.25, lon: -123.1 },
+    ].iter() {
+        println!("{}", city);
+    }
+}
+

examples/structure.json

@@ -112,7 +112,8 @@
         { "id": "json-enum", "title": "`Json`", "children": null },
         { "id": "decodable", "title": "`Decodable`", "children": null },
         { "id": "encodable", "title": "`Encodable`", "children": null }
-    ] }
+    ] },
+    { "id": "fmt", "title": "Formatting", "children": null }
   ] },
   { "id": "todo", "title": "TODO", "children": [
     { "id": "arg", "title": "Program arguments", "children": null },