Merge pull request #186 from RalfJung/structs

ASCII art for structs

Author: gnzlbg

reference/src/layout/structs-and-tuples.md

@@ -72,7 +72,26 @@ struct Foo {
 (In fact, one may use such field names in patterns or in accessor
 expressions like `foo.0`.)
 
-Structs can have various `#[repr]` flags that influence their layout:
+The degrees of freedom the compiler has when computing the layout of a struct or
+tuple is to determine the order of the fields, and the "gaps" (often called
+*padding*) before, between, and after the fields. The layout of these fields
+themselves is already entirely determined by their types, and since we intend to
+allow creating references to fields (`&s.f1`), structs do not have any
+wiggle-room there.
+
+This can be visualized as follows:
+```text
+[ <--> [field 3] <-----> [field 1] <-> [  field 2  ] <--> ]
+```
+**Figure 1** (struct-field layout): The `<-...->` and `[ ... ]` denote the differently-sized gaps and fields, respectively.
+
+Here, the individual fields are blocks of fixed size (determined by the field's
+layout).  The compiler freely picks an order for the fields to be in (this does
+not have to be the order of declaration in the source), and it picks the gaps
+between the fields (under some constraints, such as alignment).
+
+How exactly the compiler picks order and gaps, as well as other aspects of
+layout beyond size and field offset, can be controlled by a `#[repr]` attribute:
 
 - `#[repr(Rust)]` -- the default.
 - `#[repr(C)]` -- request C compatibility