Clean up and improvements to the types chapter

Author: matthewjasper

src/types.md

@@ -3,21 +3,42 @@
 Every variable, item and value in a Rust program has a type. The _type_ of a
 *value* defines the interpretation of the memory holding it.
 
-Built-in types and type-constructors are tightly integrated into the language,
-in nontrivial ways that are not possible to emulate in user-defined types.
-User-defined types have limited capabilities.
+Built-in types are tightly integrated into the language, in nontrivial ways
+that are not possible to emulate in user-defined types. User-defined types have
+limited capabilities.
 
 ## Primitive types
 
-The primitive types are the following:
+Some types are defined by the language, rather than as part of the standard library,
+these are called _primitive types_. Some of these are induvidual types:
 
 * The boolean type `bool` with values `true` and `false`.
-* The machine types (integer and floating-point).
-* The machine-dependent integer types.
-* Arrays
-* Tuples
-* Slices
-* Function pointers
+* The [machine types] (integer and floating-point).
+* The [machine-dependent integer types].
+* The [textual types] `char` and `str`.
+
+There are also some primitive constructs for generic types built in to the language
+
+* [Tuples]
+* [Arrays]
+* [Slices]
+* [Function pointers]
+* [References]
+* [Pointers]
+
+[machine types]: #machine-types
+[machine-dependent integer types]: #machine-dependent-integer-types
+[textual types]: #textual-types
+[Tuples]: #tuple-types
+[Arrays]: #array-and-slice-types
+[Slices]: #array-and-slice-types
+[References]: #pointer-types
+[Pointers]: #raw-pointers
+[Function pointers]: #function-pointer-types
+[function]: #function-types
+[closure]: #closure-types
+
+## Numeric types
 
 ### Machine types
 
@@ -52,13 +73,13 @@ The types `char` and `str` hold textual data.
 
 A value of type `char` is a [Unicode scalar value](
 http://www.unicode.org/glossary/#unicode_scalar_value) (i.e. a code point that
-is not a surrogate) represented as a 32-bit unsigned word in the 0x0000 to
-0xD7FF or 0xE000 to 0x10FFFF range. A `[char]` array is effectively a UCS-4 /
-UTF-32 string.
+is not a surrogate), represented as a 32-bit unsigned word in the 0x0000 to
+0xD7FF or 0xE000 to 0x10FFFF range. A `[char]` is effectively a UCS-4 / UTF-32
+string.
 
 A value of type `str` is a Unicode string, represented as an array of 8-bit
-unsigned bytes holding a sequence of UTF-8 code points. Since `str` is of
-unknown size, it is not a _first-class_ type, but can only be instantiated
+unsigned bytes holding a sequence of UTF-8 code points. Since `str` is a
+[dynamically sized type], it is not a _first-class_ type, but can only be instantiated
 through a pointer type, such as `&str`.
 
 ## Tuple types
@@ -94,42 +115,46 @@ is often called ‘unit’ or ‘the unit type’.
 Rust has two different types for a list of items:
 
 * `[T; N]`, an 'array'
-* `&[T]`, a 'slice'
+* `[T]`, a 'slice'
 
 An array has a fixed size, and can be allocated on either the stack or the
 heap.
 
-A slice is a 'view' into an array. It doesn't own the data it points
-to, it borrows it.
+A slice is a [dynamically sized type] representing a 'view' into an array. To
+use a slice type it generally has to be used behind a pointer for example as
+
+* `&[T]`, a 'shared slice', often just called a 'slice', it doesn't own the
+  data it points to, it borrows it.
+* `&mut [T]`, a 'mutable slice', mutably borrows the data it points to.
+* `Box<[T]>`, a 'boxed slice'
 
 Examples:
 
 ```rust
 // A stack-allocated array
 let array: [i32; 3] = [1, 2, 3];
 
-// A heap-allocated array
-let vector: Vec<i32> = vec![1, 2, 3];
+// A heap-allocated array, coerced to a slice
+let boxed_array: Box<[i32]> = Box::new([1, 2, 3]);
 
-// A slice into an array
-let slice: &[i32] = &vector[..];
+// A (shared) slice into an array
+let slice: &[i32] = &boxed_array[..];
 ```
 
-As you can see, the `vec!` macro allows you to create a `Vec<T>` easily. The
-`vec!` macro is also part of the standard library, rather than the language.
-
 All in-bounds elements of arrays and slices are always initialized, and access
-to an array or slice is always bounds-checked.
+to an array or slice is always bounds-checked in safe methods and operators.
+
+The [`Vec<T>`] standard library type provides a heap allocated resizable array
+type.
+
+[dynamically sized type]: #dynamically-sized-types
+[`Vec<T>`]: ../std/vec/struct.Vec.html
 
 ## Struct types
 
 A `struct` *type* is a heterogeneous product of other types, called the
 *fields* of the type.[^structtype]
 
-[^structtype]: `struct` types are analogous to `struct` types in C,
-    the *record* types of the ML family,
-    or the *struct* types of the Lisp family.
-
 New instances of a `struct` can be constructed with a [struct
 expression](expressions.html#struct-expressions).
 
@@ -151,39 +176,42 @@ fields. The one value constructed by the associated [struct
 expression](expressions.html#struct-expressions) is the only value that inhabits such a
 type.
 
+[^structtype]: `struct` types are analogous to `struct` types in C,
+    the *record* types of the ML family,
+    or the *struct* types of the Lisp family.
+
 ## Enumerated types
 
 An *enumerated type* is a nominal, heterogeneous disjoint union type, denoted
 by the name of an [`enum` item](items.html#enumerations). [^enumtype]
 
-[^enumtype]: The `enum` type is analogous to a `data` constructor declaration in
-             ML, or a *pick ADT* in Limbo.
+An [`enum` item](items.html#enumerations) declares both the type and a number
+of *variants*, each of which is independently named and has the syntax of a
+struct, tuple struct or unit-like struct.
 
-An [`enum` item](items.html#enumerations) declares both the type and a number of *variant
-constructors*, each of which is independently named and takes an optional tuple
-of arguments.
+New instances of an `enum` can be constructed in an [enumeration variant
+expression](expressions.html#enumeration-variant-expressions).
 
-New instances of an `enum` can be constructed by calling one of the variant
-constructors, in a [call expression](expressions.html#call-expressions).
-
-Any `enum` value consumes as much memory as the largest variant constructor for
-its corresponding `enum` type.
+Any `enum` value consumes as much memory as the largest variant for its
+corresponding `enum` type, as well as the size needed to store a discriminant.
 
 Enum types cannot be denoted *structurally* as types, but must be denoted by
 named reference to an [`enum` item](items.html#enumerations).
 
+[^enumtype]: The `enum` type is analogous to a `data` constructor declaration in
+             ML, or a *pick ADT* in Limbo.
+
 ## Recursive types
 
-Nominal types &mdash; [enumerations](#enumerated-types) and
-[structs](#struct-types) &mdash; may be recursive. That is, each `enum`
-constructor or `struct` field may refer, directly or indirectly, to the
-enclosing `enum` or `struct` type itself. Such recursion has restrictions:
+Nominal types &mdash; [structs](#struct-types),
+[enumerations](#enumerated-types) and [unions](#union-types) &mdash; may be
+recursive. That is, each `enum` variant or `struct` or `union` field may refer,
+directly or indirectly, to the enclosing `enum` or `struct` type itself. Such
+recursion has restrictions:
 
 * Recursive types must include a nominal type in the recursion
   (not mere [type definitions](../grammar.html#type-definitions),
    or other structural types such as [arrays](#array-and-slice-types) or [tuples](#tuple-types)).
-* A recursive `enum` item must have at least one non-recursive constructor
-  (in order to give the recursion a basis case).
 * The size of a recursive type must be finite;
   in other words the recursive fields of the type must be [pointer types](#pointer-types).
 * Recursive type definitions can cross module boundaries, but not module *visibility* boundaries,
@@ -206,38 +234,48 @@ All pointers in Rust are explicit first-class values. They can be copied,
 stored into data structs, and returned from functions. There are two
 varieties of pointer in Rust:
 
-* References (`&`)
-  : These point to memory _owned by some other value_.
-    A reference type is written `&type`,
-    or `&'a type` when you need to specify an explicit lifetime.
-    Copying a reference is a "shallow" operation:
-    it involves only copying the pointer itself.
-    Releasing a reference has no effect on the value it points to,
-    but a reference of a temporary value will keep it alive during the scope
-    of the reference itself.
-
-* Raw pointers (`*`)
-  : Raw pointers are pointers without safety or liveness guarantees.
-    Raw pointers are written as `*const T` or `*mut T`,
-    for example `*const i32` means a raw pointer to a 32-bit integer.
-    Copying or dropping a raw pointer has no effect on the lifecycle of any
-    other value. Dereferencing a raw pointer or converting it to any other
-    pointer type is an [`unsafe` operation](unsafe-functions.html).
-    Raw pointers are generally discouraged in Rust code;
-    they exist to support interoperability with foreign code,
-    and writing performance-critical or low-level functions.
+### Shared references (`&`)
+
+These point to memory _owned by some other value_. When a shared reference to a
+value is created it prevents direct mutation of the value. [Interior
+mutability](#interior-mutability) provides an exception for this in certain
+circumstances. As the name suggests, any number of shared references to a value
+may exit. A shared reference type is written `&type`, or `&'a type` when you
+need to specify an explicit lifetime. Copying a reference is a "shallow"
+operation: it involves only copying the pointer itself, that is, pointers are
+`Copy`. Releasing a reference has no effect on the value it points to, but
+referencing of a [temporary value](expressions.html#temporary-lifetimes) will
+keep it alive during the scope of the reference itself.
+
+### Raw pointers (`*const` and `*mut`)
+
+Raw pointers are pointers without safety or liveness guarantees. Raw pointers
+are written as `*const T` or `*mut T`, for example `*const i32` means a raw
+pointer to a 32-bit integer. Copying or dropping a raw pointer has no effect on
+the lifecycle of any other value. Dereferencing a raw pointer is an [`unsafe`
+operation](unsafe-functions.html), this can also be used to convert a raw
+pointer to a reference by reborrowing it (`&*` or `&mut *`). Raw pointers are
+generally discouraged in Rust code; they exist to support interoperability with
+foreign code, and writing performance-critical or low-level functions.
+
+When comparing pointers they are compared by their address, rather than by what
+they point to. When comparing pointers to [dynamically sized
+types](#dynamically-sized-types) they also have their addition data compared.
+
+### Smart Pointers
 
 The standard library contains additional 'smart pointer' types beyond references
 and raw pointers.
 
 ## Function item types
 
-When referred to, a function item yields a zero-sized value of its
-_function item type_. That type explicitly identifies the function - its name,
-its type arguments, and its early-bound lifetime arguments (but not its
-late-bound lifetime arguments, which are only assigned when the function
-is called) - so the value does not need to contain an actual function pointer,
-and no indirection is needed when the function is called.
+When referred to, a function item, or the constructor of a tuple-like struct or
+enum variant, yields a zero-sized value of its _function item type_. That type
+explicitly identifies the function - its name, its type arguments, and its
+early-bound lifetime arguments (but not its late-bound lifetime arguments,
+which are only assigned when the function is called) - so the value does not
+need to contain an actual function pointer, and no indirection is needed when
+the function is called.
 
 There is currently no syntax that directly refers to a function item type, but
 the compiler will display the type as something like `fn() {foo::<u32>}` in error
@@ -247,7 +285,7 @@ Because the function item type explicitly identifies the function, the item
 types of different functions - different items, or the same item with different
 generics - are distinct, and mixing them will create a type error:
 
-```rust,ignore
+```rust,compile_fail,E0308
 fn foo<T>() { }
 let x = &mut foo::<i32>;
 *x = foo::<u32>; //~ ERROR mismatched types
@@ -278,16 +316,16 @@ let foo_ptr_2 = if want_i32 {
 
 ## Function pointer types
 
-Function pointer types, created using the `fn` type constructor, refer
-to a function whose identity is not necessarily known at compile-time. They
-can be created via a coercion from both [function items](#function-item-types)
-and non-capturing [closures](#closure-types).
+Function pointer types, written using the `fn` keyword, refer to a function
+whose identity is not necessarily known at compile-time. They can be created
+via a coercion from both [function items](#function-item-types) and
+non-capturing [closures](#closure-types).
 
 A function pointer type consists of a possibly-empty set of function-type
 modifiers (such as `unsafe` or `extern`), a sequence of input types and an
 output type.
 
-An example of a `fn` type:
+An example where `Binop` is defined as a function pointer type:
 
 ```rust
 fn add(x: i32, y: i32) -> i32 {
@@ -319,10 +357,12 @@ more of the closure traits:
     `FnOnce` (i.e. anything implementing `FnMut` also implements `FnOnce`).
 
 * `Fn`
-  : The closure can be called multiple times through a shared reference.
-    A closure called as `Fn` can neither move out from nor mutate values
-    from its environment, but read-only access to such values is allowed.
-    `Fn` inherits from `FnMut`, which itself inherits from `FnOnce`.
+  : The closure can be called multiple times through a shared reference. A
+    closure called as `Fn` can neither move out from nor mutate captured
+    variables, but read-only access to such values is allowed. Using `move` to
+    capture variables by value is allowed so long as they aren't mutated or
+    moved in the body of the closure. `Fn` inherits from `FnMut`, which itself
+    inherits from `FnOnce`.
 
 Closures that don't use anything from their environment ("non capturing closures")
 can be coerced to function pointers (`fn`) with the matching signature.
@@ -340,8 +380,9 @@ x = bo(5,7);
 
 ## Trait objects
 
-In Rust, a type like `&SomeTrait` or `Box<SomeTrait>` is called a _trait object_.
-Each instance of a trait object includes:
+In Rust, trait names also refer to [dynamically sized types] called _trait
+objects_. Like all DSTs, trait objects are used behind some kind of pointer:
+`&SomeTrait` or `Box<SomeTrait>`. Each instance of a trait object includes:
 
  - a pointer to an instance of a type `T` that implements `SomeTrait`
  - a _virtual method table_, often just called a _vtable_, which contains, for
@@ -354,11 +395,18 @@ function pointer is loaded from the trait object vtable and invoked indirectly.
 The actual implementation for each vtable entry can vary on an object-by-object
 basis.
 
-Note that for a trait object to be instantiated, the trait must be
-_object-safe_. Object safety rules are defined in [RFC 255].
+Note that for a trait object types only exist for _object-safe_ traits ([RFC 255]):
 
 [RFC 255]: https://github.com/rust-lang/rfcs/blob/master/text/0255-object-safety.md
 
+* It must not require `Self: Sized`
+* All associated functions must either have a `where Self: Sized` bound or
+    * Not have any type parameters (lifetime parameters are allowed)
+    * Must be a method: its first parameter must be called self, with type
+      `Self`, `&Self`, `&mut Self`, `Box<Self>`.
+    * `Self` may only be used in the type of the receiver.
+* It must not have any associated constants.
+
 Given a pointer-typed expression `E` of type `&T` or `Box<T>`, where `T`
 implements trait `R`, casting `E` to the corresponding pointer type `&R` or
 `Box<R>` results in a value of the _trait object_ `R`. This result is
@@ -434,7 +482,7 @@ default bound for trait objects of that type. For example, `std::cell::Ref<'a,
 T>` contains a `T: 'a` bound, therefore trait objects of type `Ref<'a,
 SomeTrait>` are the same as `Ref<'a, (SomeTrait + 'a)>`.
 
-### Type parameters
+## Type parameters
 
 Within the body of an item that has type parameter declarations, the names of
 its type parameters are types:
@@ -487,6 +535,4 @@ impl Printable for String {
 }
 ```
 
-The notation `&self` is a shorthand for `self: &Self`. In this case,
-in the impl, `Self` refers to the value of type `String` that is the
-receiver for a call to the method `make_string`.
+The notation `&self` is a shorthand for `self: &Self`.