Grammar: types

Author: ehuss

src/tokens.md

@@ -548,7 +548,7 @@ usages and meanings are defined in the linked pages.
 | `>=`   | Ge          | [Greater than or equal to][comparison], [Generics]
 | `<=`   | Le          | [Less than or equal to][comparison]
 | `@`    | At          | [Subpattern binding]
-| `_`    | Underscore  | [Wildcard patterns], Inferred types
+| `_`    | Underscore  | [Wildcard patterns], [Inferred types]
 | `.`    | Dot         | [Field access][field], [Tuple index]
 | `..`   | DotDot      | [Range][range], [Struct expressions], [Patterns]
 | `...`  | DotDotDot   | [Variadic functions][extern], [Range patterns]
@@ -576,6 +576,7 @@ them are referred to as "token trees" in [macros].  The three types of brackets
 | `(` `)` | Parentheses     |
 
 
+[Inferred types]: types.html#inferred-type
 [Operator expressions]: expressions/operator-expr.html
 [Range patterns]: patterns.html#range-patterns
 [Reference patterns]: patterns.html#reference-patterns

src/types.md

@@ -1,5 +1,32 @@
 # Types
 
+> **<sup>Syntax</sup>**\
+> _Type_ :\
+> &nbsp;&nbsp; &nbsp;&nbsp; _TypeCommon_\
+> &nbsp;&nbsp; | _ParenthesizedType_&nbsp;(`+` [_TypeParamBounds_])<sup>?</sup>\
+> &nbsp;&nbsp; | [_TypePath_]&nbsp;(`+` [_TypeParamBounds_])<sup>?</sup>\
+> &nbsp;&nbsp; | [_ImplTraitType_]\
+> &nbsp;&nbsp; | [_TraitObjectType_]
+>
+> _TypeNoBounds_ :\
+> &nbsp;&nbsp; &nbsp;&nbsp; _TypeCommon_\
+> &nbsp;&nbsp; | _ParenthesizedType_\
+> &nbsp;&nbsp; | [_TypePath_]
+>
+> _TypeCommon_ :\
+> &nbsp;&nbsp; &nbsp;&nbsp; [_TupleType_]\
+> &nbsp;&nbsp; | [_NeverType_]\
+> &nbsp;&nbsp; | [_RawPointerType_]\
+> &nbsp;&nbsp; | [_ReferenceType_]\
+> &nbsp;&nbsp; | [_ArrayType_]\
+> &nbsp;&nbsp; | [_SliceType_]\
+> &nbsp;&nbsp; | [_InferredType_]\
+> &nbsp;&nbsp; | [_QualifiedPathInType_]\
+> &nbsp;&nbsp; | [_BareFunctionType_]
+>
+> _ParenthesizedType_ :\
+> &nbsp;&nbsp; &nbsp;&nbsp; `(` _Type_ `)`
+
 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.
 
@@ -107,12 +134,21 @@ instantiated through a pointer type, such as `&str`.
 
 ## Never type
 
+> **<sup>Syntax</sup>**\
+> _NeverType_ : `!`
+
 The never type `!` is a type with no values, representing the result of
 computations that never complete. Expressions of type `!` can be coerced into
 any other type.
 
 ## Tuple types
 
+> **<sup>Syntax</sup>**\
+> _TupleType_ :\
+> &nbsp;&nbsp; &nbsp;&nbsp; `(` `)`\
+> &nbsp;&nbsp; | `(` [_Type_] `,` `)`\
+> &nbsp;&nbsp; | `(` [_Type_]&nbsp;( `,` [_Type_] ) <sup>+</sup> `,`<sup>?</sup> `)`
+
 A tuple *type* is a heterogeneous product of other types, called the *elements*
 of the tuple. It has no nominal name and is instead structurally typed.
 
@@ -141,13 +177,21 @@ is often called ‘unit’ or ‘the unit type’.
 
 ## Array, and Slice types
 
-Rust has two different types for a list of items:
+> **<sup>Syntax</sup>**\
+> _ArrayType_ :\
+> &nbsp;&nbsp; `[` [_Type_] `;` [_Expression_] `]`
+>
+> _SliceType_ :\
+> &nbsp;&nbsp; `[` [_Type_] `]`
+
+Rust has two different types for a list of items of the same type:
 
 * `[T; N]`, an 'array'
 * `[T]`, a 'slice'
 
 An array has a fixed size, and can be allocated on either the stack or the
-heap.
+heap. The size is an expression that evaluates to a
+[`usize`](#machine-dependent-integer-types).
 
 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
@@ -276,6 +320,10 @@ copied, stored into data structs, and returned from functions.
 
 ### Shared references (`&`)
 
+> **<sup>Syntax</sup>**\
+> _ReferenceType_ :\
+> &nbsp;&nbsp; `&` [_Lifetime_]<sup>?</sup> `mut`<sup>?</sup> [_TypeNoBounds_]
+
 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.html) provides an exception for this in certain
@@ -295,6 +343,10 @@ borrowed) is the only way to access the value it points to, so is not `Copy`.
 
 ### Raw pointers (`*const` and `*mut`)
 
+> **<sup>Syntax</sup>**\
+> _RawPointerType_ :\
+> &nbsp;&nbsp; `*` ( `mut` | `const` ) [_TypeNoBounds_]
+
 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
@@ -366,6 +418,16 @@ All function items implement [`Fn`], [`FnMut`], [`FnOnce`], [`Copy`],
 
 ## Function pointer types
 
+> **<sup>Syntax</sup>**\
+> _BareFunctionType_ :\
+> &nbsp;&nbsp; [_ForLifetimes_]<sup>?</sup> [_FunctionFront_] `fn`\
+> &nbsp;&nbsp; &nbsp;&nbsp;  `(` [_FunctionParametersMaybeNamedVariadic_]<sup>?</sup> `)` _BareFunctionReturnType_<sup>?</sup>
+>
+> _BareFunctionReturnType_:\
+> &nbsp;&nbsp; `->` [_TypeNoBounds_]
+
+<!-- TODO: _FunctionParametersMaybeNamedVariadic_ -->
+
 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
@@ -560,7 +622,7 @@ Because captures are often by reference, the following general rules arise:
 
 > **<sup>Syntax</sup>**\
 > _TraitObjectType_ :\
-> &nbsp;&nbsp; `dyn`<sup>?</sup> _TypeParamBounds_
+> &nbsp;&nbsp; `dyn`<sup>?</sup> [_TypeParamBounds_]
 
 A *trait object* is an opaque value of another type that implements a set of
 traits. The set of traits is made up of an [object safe] *base trait* plus any
@@ -658,6 +720,24 @@ inferred with a sensible choice.
 
 [defaults]: lifetime-elision.html#default-trait-object-lifetimes
 
+## Inferred type
+> **<sup>Syntax</sup>**\
+> _InferredType_ : `_`
+
+The inferred type asks the compiler to infer the type if possible based on the
+surrounding information available. It cannot be used in item signatures. It is
+often used in generic arguments:
+
+```rust
+let x: Vec<_> = (0..10).collect();
+```
+
+<!--
+  What else should be said here?
+  The only documentation I am aware of is https://rust-lang-nursery.github.io/rustc-guide/type-inference.html
+  Should there be a broader discussion of type inference somewhere?
+-->
+
 ## Type parameters
 
 Within the body of an item that has type parameter declarations, the names of
@@ -678,7 +758,12 @@ fn to_vec<A: Clone>(xs: &[A]) -> Vec<A> {
 Here, `first` has type `A`, referring to `to_vec`'s `A` type parameter; and
 `rest` has type `Vec<A>`, a vector with element type `A`.
 
-## Anonymous type parameters
+## Impl trait
+
+> **<sup>Syntax</sup>**\
+> _ImplTraitType_ : `impl` [_TypeParamBounds_]
+
+### Anonymous type parameters
 
 > Note: This section is a placeholder for more comprehensive reference
 > material.
@@ -692,7 +777,7 @@ bounds of the anonymous type parameter.
 
 They are written as `impl` followed by a set of trait bounds.
 
-## Abstract return types
+### Abstract return types
 
 > Note: This section is a placeholder for more comprehensive reference
 > material.
@@ -740,6 +825,27 @@ impl Printable for String {
 
 > Note: The notation `&self` is a shorthand for `self: &Self`.
 
+[_ArrayType_]: #array-and-slice-types
+[_BareFunctionType_]: #function-pointer-types
+[_Expression_]: expressions.html
+[_ForLifetimes_]: items/generics.html#where-clauses
+[_FunctionFront_]: items/functions.html
+[_FunctionParametersMaybeNamed_]: items/functions.html
+[_ImplTraitType_]: #impl-trait
+[_InferredType_]: #inferred-type
+[_Lifetime_]: trait-bounds.html
+[_NeverType_]: #never-type
+[_ParenthesizedType_]: #parenthesized-type
+[_QualifiedPathInType_]: paths.html#qualified-paths
+[_RawPointerType_]: #raw-pointers-const-and-mut
+[_ReferenceType_]: #shared-references-
+[_SliceType_]: #array-and-slice-types
+[_TraitObjectType_]: #trait-objects
+[_TupleType_]: #tuple-types
+[_TypeNoBounds_]: #types
+[_TypeParamBounds_]: trait-bounds.html
+[_TypePath_]: paths.html#paths-in-types
+[_Type_]: #types
 [`Fn`]: ../std/ops/trait.Fn.html
 [`FnMut`]: ../std/ops/trait.FnMut.html
 [`FnOnce`]: ../std/ops/trait.FnOnce.html