Rollup of 15 pull requests

src/doc/book/syntax-index.md

@@ -94,7 +94,7 @@
 * `|` (`|…| expr`): closures.  See [Closures].
 * `|=` (`var |= expr`): bitwise or & assignment. Overloadable (`BitOrAssign`).
 * `||` (`expr || expr`): logical or.
-* `_`: "ignored" pattern binding.  See [Patterns (Ignoring bindings)].
+* `_`: "ignored" pattern binding (see [Patterns (Ignoring bindings)]). Also used to make integer-literals readable (see [Reference (Integer literals)]).
 
 ## Other Syntax
 
@@ -231,6 +231,7 @@
 [Primitive Types (Tuples)]: primitive-types.html#tuples
 [Raw Pointers]: raw-pointers.html
 [Reference (Byte String Literals)]: ../reference.html#byte-string-literals
+[Reference (Integer literals)]: ../reference.html#integer-literals
 [Reference (Raw Byte String Literals)]: ../reference.html#raw-byte-string-literals
 [Reference (Raw String Literals)]: ../reference.html#raw-string-literals
 [References and Borrowing]: references-and-borrowing.html

src/doc/book/trait-objects.md

@@ -123,7 +123,6 @@ dispatch with trait objects by casting:
 # trait Foo { fn method(&self) -> String; }
 # impl Foo for u8 { fn method(&self) -> String { format!("u8: {}", *self) } }
 # impl Foo for String { fn method(&self) -> String { format!("string: {}", *self) } }
-
 fn do_something(x: &Foo) {
     x.method();
 }
@@ -140,7 +139,6 @@ or by coercing:
 # trait Foo { fn method(&self) -> String; }
 # impl Foo for u8 { fn method(&self) -> String { format!("u8: {}", *self) } }
 # impl Foo for String { fn method(&self) -> String { format!("string: {}", *self) } }
-
 fn do_something(x: &Foo) {
     x.method();
 }

src/doc/nomicon/phantom-data.md

@@ -50,7 +50,7 @@ struct Vec<T> {
 }
 ```
 
-Unlike the previous example it *appears* that everything is exactly as we
+Unlike the previous example, it *appears* that everything is exactly as we
 want. Every generic argument to Vec shows up in at least one field.
 Good to go!
 
@@ -84,4 +84,3 @@ standard library made a utility for itself called `Unique<T>` which:
 * includes a `PhantomData<T>`
 * auto-derives Send/Sync as if T was contained
 * marks the pointer as NonZero for the null-pointer optimization
-

src/doc/reference.md

@@ -1653,14 +1653,43 @@ the Rust ABI and the foreign ABI.
 A number of [attributes](#ffi-attributes) control the behavior of external blocks.
 
 By default external blocks assume that the library they are calling uses the
-standard C "cdecl" ABI. Other ABIs may be specified using an `abi` string, as
-shown here:
+standard C ABI on the specific platform. Other ABIs may be specified using an
+`abi` string, as shown here:
 
 ```ignore
 // Interface to the Windows API
 extern "stdcall" { }
 ```
 
+There are three ABI strings which are cross-platform, and which all compilers
+are guaranteed to support:
+
+* `extern "Rust"` -- The default ABI when you write a normal `fn foo()` in any
+  Rust code.
+* `extern "C"` -- This is the same as `extern fn foo()`; whatever the default
+  your C compiler supports.
+* `extern "system"` -- Usually the same as `extern "C"`, except on Win32, in
+  which case it's `"stdcall"`, or what you should use to link to the Windows API
+  itself
+
+There are also some platform-specific ABI strings:
+
+* `extern "cdecl"` -- The default for x86\_32 C code.
+* `extern "stdcall"` -- The default for the Win32 API on x86\_32.
+* `extern "win64"` -- The default for C code on x86\_64 Windows.
+* `extern "aapcs"` -- The default for ARM.
+* `extern "fastcall"` -- The `fastcall` ABI -- corresponds to MSVC's
+  `__fastcall` and GCC and clang's `__attribute__((fastcall))`
+* `extern "vectorcall"` -- The `vectorcall` ABI -- corresponds to MSVC's
+  `__vectorcall` and clang's `__attribute__((vectorcall))`
+
+Finally, there are some rustc-specific ABI strings:
+
+* `extern "rust-intrinsic"` -- The ABI of rustc intrinsics.
+* `extern "rust-call"` -- The ABI of the Fn::call trait functions.
+* `extern "platform-intrinsic"` -- Specific platform intrinsics -- like, for
+  example, `sqrt` -- have this ABI. You should never have to deal with it.
+
 The `link` attribute allows the name of the library to be specified. When
 specified the compiler will attempt to link against the native library of the
 specified name.

src/libcollections/slice.rs

@@ -691,15 +691,40 @@ impl<T> [T] {
     ///
     /// # Examples
     ///
-    /// Print the slice split by numbers divisible by 3 (i.e. `[10, 40]`,
-    /// `[20]`, `[50]`):
+    /// ```
+    /// let slice = [10, 40, 33, 20];
+    /// let mut iter = slice.split(|num| num % 3 == 0);
     ///
+    /// assert_eq!(iter.next().unwrap(), &[10, 40]);
+    /// assert_eq!(iter.next().unwrap(), &[20]);
+    /// assert!(iter.next().is_none());
     /// ```
-    /// let v = [10, 40, 30, 20, 60, 50];
     ///
-    /// for group in v.split(|num| *num % 3 == 0) {
-    ///     println!("{:?}", group);
-    /// }
+    /// If the first element is matched, an empty slice will be the first item
+    /// returned by the iterator. Similarly, if the last element in the slice
+    /// is matched, an empty slice will be the last item returned by the
+    /// iterator:
+    ///
+    /// ```
+    /// let slice = [10, 40, 33];
+    /// let mut iter = slice.split(|num| num % 3 == 0);
+    ///
+    /// assert_eq!(iter.next().unwrap(), &[10, 40]);
+    /// assert_eq!(iter.next().unwrap(), &[]);
+    /// assert!(iter.next().is_none());
+    /// ```
+    ///
+    /// If two matched elements are directly adjacent, an empty slice will be
+    /// present between them:
+    ///
+    /// ```
+    /// let slice = [10, 6, 33, 20];
+    /// let mut iter = slice.split(|num| num % 3 == 0);
+    ///
+    /// assert_eq!(iter.next().unwrap(), &[10]);
+    /// assert_eq!(iter.next().unwrap(), &[]);
+    /// assert_eq!(iter.next().unwrap(), &[20]);
+    /// assert!(iter.next().is_none());
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     #[inline]

src/libcollections/vec_deque.rs

@@ -402,6 +402,8 @@ impl<T> VecDeque<T> {
 
     /// Retrieves an element in the `VecDeque` by index.
     ///
+    /// Element at index 0 is the front of the queue.
+    ///
     /// # Examples
     ///
     /// ```
@@ -425,6 +427,8 @@ impl<T> VecDeque<T> {
 
     /// Retrieves an element in the `VecDeque` mutably by index.
     ///
+    /// Element at index 0 is the front of the queue.
+    ///
     /// # Examples
     ///
     /// ```
@@ -456,6 +460,8 @@ impl<T> VecDeque<T> {
     ///
     /// Fails if there is no element with either index.
     ///
+    /// Element at index 0 is the front of the queue.
+    ///
     /// # Examples
     ///
     /// ```
@@ -1180,6 +1186,8 @@ impl<T> VecDeque<T> {
     ///
     /// Returns `None` if `index` is out of bounds.
     ///
+    /// Element at index 0 is the front of the queue.
+    ///
     /// # Examples
     ///
     /// ```
@@ -1214,6 +1222,8 @@ impl<T> VecDeque<T> {
     ///
     /// Returns `None` if `index` is out of bounds.
     ///
+    /// Element at index 0 is the front of the queue.
+    ///
     /// # Examples
     ///
     /// ```
@@ -1245,6 +1255,8 @@ impl<T> VecDeque<T> {
     /// end is closer to the insertion point will be moved to make room,
     /// and all the affected elements will be moved to new positions.
     ///
+    /// Element at index 0 is the front of the queue.
+    ///
     /// # Panics
     ///
     /// Panics if `index` is greater than `VecDeque`'s length
@@ -1472,6 +1484,8 @@ impl<T> VecDeque<T> {
     /// room, and all the affected elements will be moved to new positions.
     /// Returns `None` if `index` is out of bounds.
     ///
+    /// Element at index 0 is the front of the queue.
+    ///
     /// # Examples
     ///
     /// ```
@@ -1651,6 +1665,8 @@ impl<T> VecDeque<T> {
     ///
     /// Note that the capacity of `self` does not change.
     ///
+    /// Element at index 0 is the front of the queue.
+    ///
     /// # Panics
     ///
     /// Panics if `at > len`