Merge branch 'master' into Add-u128-and-i128-tokens

Author: markmmm

.travis.yml

@@ -4,7 +4,7 @@ rust:
   - nightly
 
 before_script:
-  - (cargo install mdbook --git https://github.com/rust-lang-nursery/mdBook.git --force || true)
+  - (cargo install mdbook --version =0.1.7)
 
 script: 
   - export PATH=$PATH:/home/travis/.cargo/bin && mdbook test

src/crates-and-source-files.md

@@ -11,11 +11,11 @@
 > UTF8BOM : `\uFEFF`  
 > SHEBANG : `#!` ~[`[` `\n`] ~`\n`<sup>*</sup>
 
-Although Rust, like any other language, can be implemented by an interpreter as
-well as a compiler, the only existing implementation is a compiler,
-and the language has
-always been designed to be compiled. For these reasons, this section assumes a
-compiler.
+
+> Note: Although Rust, like any other language, can be implemented by an
+> interpreter as well as a compiler, the only existing implementation is a
+> compiler,and the language has always been designed to be compiled. For these
+> reasons, this section assumes a compiler.
 
 Rust's semantics obey a *phase distinction* between compile-time and
 run-time.[^phase-distinction] Semantic rules that have a *static
@@ -66,9 +66,17 @@ apply to the crate as a whole.
 #![warn(non_camel_case_types)]
 ```
 
-A crate that contains a `main` function can be compiled to an executable. If a
-`main` function is present, its return type must be `()`
-("[unit]") and it must take no arguments.
+A crate that contains a `main` [function] can be compiled to an executable. If a
+`main` function is present, it must take no arguments, must not declare any
+[trait or lifetime bounds], must not have any [where clauses], and  its return
+type must  be one of the following:
+
+* `()`
+<!-- * `!` -->
+* `Result<T, E> where T: on this list, E: Error`
+
+> Note: The implementation of which return types are allowed is determined by
+> the unstable [`Termination`] trait.
 
 The optional [_UTF8 byte order mark_] (UTF8BOM production) indicates that the
 file is encoded in UTF8. It can only occur at the beginning of the file and
@@ -98,9 +106,13 @@ fn main() {
 
 [module]: items/modules.html
 [module path]: paths.html
-[attributes]: items-and-attributes.html
+[attributes]: attributes.html
 [unit]: types.html#tuple-types
 [_InnerAttribute_]: attributes.html
 [_Item_]: items.html
 [_shebang_]: https://en.wikipedia.org/wiki/Shebang_(Unix)
 [_utf8 byte order mark_]: https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8
+[function]: items/functions.html
+[`Termination`]: ../std/process/trait.Termination.html
+[where clause]: items/where-clauses.html
+[trait or lifetime bounds]: trait-bounds.html

src/expressions/method-call-expr.md

@@ -94,5 +94,6 @@ and function invocation.
 [array]: types.html#array-and-slice-types
 [trait objects]: types.html#trait-objects
 [disambiguate call]: expressions/call-expr.html#disambiguating-function-calls
+[disambiguating function call syntax]: expressions/call-expr.html#disambiguating-function-calls
 [dereference]: expressions/operator-expr.html#the-dereference-operator
 [methods]: items/associated-items.html#methods

src/expressions/operator-expr.md

@@ -87,7 +87,7 @@ let a = & & & & mut 10;
 The `*` (dereference) operator is also a unary prefix operator. When applied to
 a [pointer](types.html#pointer-types) it denotes the pointed-to location. If
 the expression is of type `&mut T` and `*mut T`, and is either a local
-variable, a (nested) field of a local variance or is a mutable [place 
+variable, a (nested) field of a local variable or is a mutable [place 
 expression], then the resulting memory location can be assigned to.
 Dereferencing a raw pointer requires `unsafe`.
 
@@ -207,15 +207,17 @@ expression context][value expression] so are moved or copied.
 | `+`    | Addition                |             | Addition       | `std::ops::Add`    |
 | `-`    | Subtraction             |             | Subtraction    | `std::ops::Sub`    |
 | `*`    | Multiplication          |             | Multiplication | `std::ops::Mul`    |
-| `/`    | Division                |             | Division       | `std::ops::Div`    |
+| `/`    | Division*                |             | Division       | `std::ops::Div`    |
 | `%`    | Remainder               |             | Remainder      | `std::ops::Rem`    |
 | `&`    | Bitwise AND             | Logical AND |                | `std::ops::BitAnd` |
 | <code>&#124;</code> | Bitwise OR | Logical OR  |                | `std::ops::BitOr`  |
 | `^`    | Bitwise XOR             | Logical XOR |                | `std::ops::BitXor` |
 | `<<`   | Left Shift              |             |                | `std::ops::Shl`    |
-| `>>`   | Right Shift*            |             |                | `std::ops::Shr`    |
+| `>>`   | Right Shift**            |             |                | `std::ops::Shr`    |
 
-\* Arithmetic right shift on signed integer types, logical right shift on
+\* Integer division rounds towards zero.
+
+\*\* Arithmetic right shift on signed integer types, logical right shift on
 unsigned integer types.
 
 Here are examples of these operators being used.
@@ -345,10 +347,13 @@ well as the following additional casts. Here `*T` means either `*const T` or
 | `&[T; n]`             | `*const T`            | Array to pointer cast            |
 | [Function pointer](types.html#function-pointer-types) | `*V` where `V: Sized` | Function pointer to pointer cast |
 | Function pointer      | Integer               | Function pointer to address cast |
+| Closure \*\*          | Function pointer      | Closure to function pointer cast |
 
 \* or `T` and `V` are compatible unsized types, e.g., both slices, both the
 same trait object.
 
+\*\* only for closures that do capture (close over) any local variables
+
 ### Semantics
 
 * Numeric cast
@@ -390,7 +395,8 @@ same trait object.
 > &nbsp;&nbsp; | [_Expression_] `=` [_Expression_]  
 
 An _assignment expression_ consists of a [place expression] followed by an
-equals sign (`=`) and a [value expression].
+equals sign (`=`) and a [value expression]. Such an expression always has
+the [`unit` type].
 
 Evaluating an assignment expression [drops](destructors.html) the left-hand
 operand, unless it's an uninitialized local variable or field of a local variable,

src/items/implementations.md

@@ -94,7 +94,7 @@ impl Shape for Circle {
 
 ### Trait Implementation Coherence
 
-A trait implementation is consider incoherent if either the orphan check fails
+A trait implementation is considered incoherent if either the orphan check fails
 or there are overlapping implementation instances. 
 
 Two trait implementations overlap when there is a non-empty intersection of the

src/items/traits.md

@@ -9,8 +9,8 @@ interface consists of [associated items], which come in three varieties:
 
 All traits define an implicit type parameter `Self` that refers to "the type
 that is implementing this interface". Traits may also contain additional type
-parameters. These type parameters (including `Self`) may be constrained by
-other traits and so forth as usual.
+parameters. These type parameters, including `Self`, may be constrained by
+other traits and so forth [as usual][generics].
 
 Traits are implemented for specific types through separate [implementations].
 
@@ -26,8 +26,7 @@ Generic items may use traits as [bounds] on their type parameters.
 ## Generic Traits
 
 Type parameters can be specified for a trait to make it generic. These appear
-after the trait name, using the same syntax used in [generic
-functions](items/functions.html#generic-functions).
+after the trait name, using the same syntax used in [generic functions].
 
 ```rust
 trait Seq<T> {
@@ -48,71 +47,72 @@ Object safe traits can be the base trait of a [trait object]. A trait is
       and
     * Be a [method] that does not use `Self` except in the type of the receiver.
 * It must not have any associated constants.
+* All supertraits must also be object safe.
 
 ## Supertraits
 
-Trait bounds on `Self` are considered "supertraits". These are required to be
-acyclic. Supertraits are somewhat different from other constraints in that
-they affect what methods are available in the vtable when the trait is used as
-a [trait object]. Consider the following example:
+**Supertraits** are traits that are required to be implemented for a type to
+implement a specific trait. Furthermore, anywhere a [generic] or [trait object]
+is bounded by a trait, it has access to the associated items of its supertraits.
+
+Supertraits are declared by trait bounds on the `Self` type of a trait and
+transitively the supertraits of the traits declared in those trait bounds. It is
+an error for a trait to be its own supertrait.
+
+The trait with a supertrait is called a **subtrait** of its supertrait.
+
+The following is an example of declaring `Shape` to be a supertrait of `Circle`.
 
 ```rust
 trait Shape { fn area(&self) -> f64; }
 trait Circle : Shape { fn radius(&self) -> f64; }
 ```
 
-The syntax `Circle : Shape` means that types that implement `Circle` must also
-have an implementation for `Shape`. Multiple supertraits are separated by `+`,
-`trait Circle : Shape + PartialEq { }`. In an implementation of `Circle` for a
-given type `T`, methods can refer to `Shape` methods, since the typechecker
-checks that any type with an implementation of `Circle` also has an
-implementation of `Shape`:
+And the following is the same example, except using [where clauses].
 
 ```rust
-struct Foo;
-
 trait Shape { fn area(&self) -> f64; }
-trait Circle : Shape { fn radius(&self) -> f64; }
-impl Shape for Foo {
-    fn area(&self) -> f64 {
-        0.0
-    }
-}
-impl Circle for Foo {
-    fn radius(&self) -> f64 {
-        println!("calling area: {}", self.area());
+trait Circle where Self: Shape { fn radius(&self) -> f64; }
+```
 
-        0.0
+This next example gives `radius` a default implementation using the `area`
+function from `Shape`.
+
+```rust
+# trait Shape { fn area(&self) -> f64; }
+trait Circle where Self: Shape {
+    fn radius(&self) -> f64 {
+        // A = pi * r^2
+        // so algebraically,
+        // r = sqrt(A / pi)
+        (self.area() /std::f64::consts::PI).sqrt()
     }
 }
-
-let c = Foo;
-c.radius();
 ```
 
-In type-parameterized functions, methods of the supertrait may be called on
-values of subtrait-bound type parameters. Referring to the previous example of
-`trait Circle : Shape`:
+This next example calls a supertrait method on a generic parameter.
 
 ```rust
 # trait Shape { fn area(&self) -> f64; }
 # trait Circle : Shape { fn radius(&self) -> f64; }
-fn radius_times_area<T: Circle>(c: T) -> f64 {
-    // `c` is both a Circle and a Shape
-    c.radius() * c.area()
+fn print_area_and_radius<C: Circle>(c: C) {
+    // Here we call the area method from the supertrait `Shape` of `Circle`.
+    println!("Area: {}", c.area());
+    println!("Radius: {}", c.radius());
 }
 ```
 
-Likewise, supertrait methods may also be called on trait objects.
+Similarly, here is an example of calling supertrait methods on trait objects.
 
 ```rust
 # trait Shape { fn area(&self) -> f64; }
 # trait Circle : Shape { fn radius(&self) -> f64; }
-# impl Shape for i32 { fn area(&self) -> f64 { 0.0 } }
-# impl Circle for i32 { fn radius(&self) -> f64 { 0.0 } }
-# let mycircle = 0i32;
-let mycircle = Box::new(mycircle) as Box<Circle>;
-let nonsense = mycircle.radius() * mycircle.area();
+# struct UnitCircle;
+# impl Shape for UnitCircle { fn area(&self) -> f64 { std::f64::consts::PI } }
+# impl Circle for UnitCircle { fn radius(&self) -> f64 { 1.0 } }
+# let circle = UnitCircle;
+let circle = Box::new(circle) as Box<dyn Circle>;
+let nonsense = circle.radius() * circle.area();
 ```
 
 [bounds]: trait-bounds.html
@@ -121,3 +121,7 @@ let nonsense = mycircle.radius() * mycircle.area();
 [RFC 255]: https://github.com/rust-lang/rfcs/blob/master/text/0255-object-safety.md
 [associated items]: items/associated-items.html
 [method]: items/associated-items.html#methods
+[implementations]: items/implementations.html
+[generics]: items/generics.html
+[where clauses]: items/generics.html#where-clauses
+[generic functions]: items/functions.html#generic-functions

src/tokens.md

@@ -20,13 +20,15 @@ evaluated (primarily) at compile time.
 #### Characters and strings
 
 |                                              | Example         | `#` sets   | Characters  | Escapes             |
-|----------------------------------------------|-----------------|------------|-------------|---------------------|
-| [Character](#character-literals)             | `'H'`           | `N/A`      | All Unicode | [Quote](#quote-escapes) & [ASCII](#ascii-escapes) & [Unicode](#unicode-escapes) |
-| [String](#string-literals)                   | `"hello"`       | `N/A`      | All Unicode | [Quote](#quote-escapes) & [ASCII](#ascii-escapes) & [Unicode](#unicode-escapes) |
-| [Raw](#raw-string-literals)                  | `r#"hello"#`    | `0...`     | All Unicode | `N/A`                                                      |
-| [Byte](#byte-literals)                       | `b'H'`          | `N/A`      | All ASCII   | [Quote](#quote-escapes) & [Byte](#byte-escapes)                               |
-| [Byte string](#byte-string-literals)         | `b"hello"`      | `N/A`      | All ASCII   | [Quote](#quote-escapes) & [Byte](#byte-escapes)                               |
-| [Raw byte string](#raw-byte-string-literals) | `br#"hello"#`   | `0...`     | All ASCII   | `N/A`                                                      |
+|----------------------------------------------|-----------------|-------------|-------------|---------------------|
+| [Character](#character-literals)             | `'H'`           | 0           | All Unicode | [Quote](#quote-escapes) & [ASCII](#ascii-escapes) & [Unicode](#unicode-escapes) |
+| [String](#string-literals)                   | `"hello"`       | 0           | All Unicode | [Quote](#quote-escapes) & [ASCII](#ascii-escapes) & [Unicode](#unicode-escapes) |
+| [Raw](#raw-string-literals)                  | `r#"hello"#`    | 0 or more\* | All Unicode | `N/A`                                                      |
+| [Byte](#byte-literals)                       | `b'H'`          | 0           | All ASCII   | [Quote](#quote-escapes) & [Byte](#byte-escapes)                               |
+| [Byte string](#byte-string-literals)         | `b"hello"`      | 0           | All ASCII   | [Quote](#quote-escapes) & [Byte](#byte-escapes)                               |
+| [Raw byte string](#raw-byte-string-literals) | `br#"hello"#`   | 0 or more\* | All ASCII   | `N/A`                                                      |
+
+\* The number of `#`s on each side of the same literal must be equivalent
 
 #### ASCII escapes
 
@@ -142,7 +144,7 @@ Some additional _escapes_ are available in either character or non-raw string
 literals. An escape starts with a `U+005C` (`\`) and continues with one of the
 following forms:
 
-* An _8-bit code point escape_ starts with `U+0078` (`x`) and is
+* A _7-bit code point escape_ starts with `U+0078` (`x`) and is
   followed by exactly two _hex digits_ with value up to `0x7F`. It denotes the
   ASCII character with value equal to the provided hex value. Higher values are
   not permitted because it is ambiguous whether they mean Unicode code points or
@@ -202,7 +204,7 @@ r##"foo #"# bar"##;                // foo #"# bar
 >    `b'` ( ASCII_FOR_CHAR | BYTE_ESCAPE )  `'`  
 >  
 > ASCII_FOR_CHAR :  
->    _any ASCII (i.e. 0x00 to 0x7F), except_ `'`, `/`, \\n, \\r or \\t  
+>    _any ASCII (i.e. 0x00 to 0x7F), except_ `'`, `\`, \\n, \\r or \\t  
 >  
 > BYTE_ESCAPE :  
 >       `\x` HEX_DIGIT HEX_DIGIT  
@@ -222,7 +224,7 @@ _number literal_.
 > &nbsp;&nbsp; `b"` ( ASCII_FOR_STRING | BYTE_ESCAPE | STRING_CONTINUE )<sup>\*</sup> `"`  
 >  
 > ASCII_FOR_STRING :  
-> &nbsp;&nbsp; _any ASCII (i.e 0x00 to 0x7F), except_ `"`, `/` _and IsolatedCR_ 
+> &nbsp;&nbsp; _any ASCII (i.e 0x00 to 0x7F), except_ `"`, `\` _and IsolatedCR_ 
 
 A non-raw _byte string literal_ is a sequence of ASCII characters and _escapes_,
 preceded by the characters `U+0062` (`b`) and `U+0022` (double-quote), and
@@ -324,10 +326,8 @@ literal_. The grammar for recognizing the two kinds of literals is mixed.
 > HEX_DIGIT : [`0`-`9` `a`-`f` `A`-`F`]  
 >  
 > INTEGER_SUFFIX :  
-> &nbsp;&nbsp; &nbsp;&nbsp; `u8` | `u16` | `u32` | `u64` | `usize`  
-> &nbsp;&nbsp; | `i8` | `i16` | `i32` | `i64` | `isize`
-
-<!-- FIXME: u128 and i128 -->
+> &nbsp;&nbsp; &nbsp;&nbsp; `u8` | `u16` | `u32` | `u64` | `u128` | `usize`  
+> &nbsp;&nbsp; | `i8` | `i16` | `i32` | `i64` | `i128` | `isize`
 
 An _integer literal_ has one of four forms:
 

src/types.md

@@ -57,7 +57,7 @@ The machine types are the following:
   [-(2^15), 2^15 - 1], [-(2^31), 2^31 - 1], [-(2^63), 2^63 - 1], and
   [-(2^127), 2^127 - 1] respectively.
 
-* The IEEE 754-2008 `binary32` and `binary64` floating-point types: `f32` and
+* The IEEE 754-2008 "binary32" and "binary64" floating-point types: `f32` and
   `f64`, respectively.
 
 ### Machine-dependent integer types
@@ -545,7 +545,7 @@ 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
 number of [auto traits].
 
-Trait objects implement the base trait, its auto traits, and any super traits
+Trait objects implement the base trait, its auto traits, and any [supertraits]
 of the base trait.
 
 Trait objects are written as the optional keyword `dyn` followed by a set of
@@ -597,8 +597,8 @@ behind some type of pointer; for example `&dyn SomeTrait` or
 
  - a pointer to an instance of a type `T` that implements `SomeTrait`
  - a _virtual method table_, often just called a _vtable_, which contains, for
-   each method of `SomeTrait` that `T` implements, a pointer to `T`'s
-   implementation (i.e. a function pointer).
+   each method of `SomeTrait` and its [supertraits] that `T` implements, a
+   pointer to `T`'s implementation (i.e. a function pointer).
 
 The purpose of trait objects is to permit "late binding" of methods. Calling a
 method on a trait object results in virtual dispatch at runtime: that is, a
@@ -712,3 +712,4 @@ impl Printable for String {
 [issue 33140]: https://github.com/rust-lang/rust/issues/33140
 [_PATH_]: paths.html
 [_LIFETIME_OR_LABEL_]: tokens.html#lifetimes-and-loop-labels
+[supertraits]: items/traits.html#supertraits