Merge branch 'master' into frewsxcv-dyn

8 files changed, 146 insertions, 36 deletions

diff --git a/src/libcore/any.rs b/src/libcore/any.rs
index 6b26093439e..c2113dfd2a0 100644
--- a/src/libcore/any.rs
+++ b/src/libcore/any.rs
@@ -39,7 +39,7 @@
 //!
 //! // Logger function for any type that implements Debug.
 //! fn log<T: Any + Debug>(value: &T) {
-//!     let value_any = value as &Any;
+//!     let value_any = value as &dyn Any;
 //!
 //!     // try to convert our value to a String.  If successful, we want to
 //!     // output the String's length as well as its value.  If not, it's a
@@ -95,7 +95,7 @@ pub trait Any: 'static {
     ///
     /// use std::any::{Any, TypeId};
     ///
-    /// fn is_string(s: &Any) -> bool {
+    /// fn is_string(s: &dyn Any) -> bool {
     ///     TypeId::of::<String>() == s.get_type_id()
     /// }
     ///
@@ -151,7 +151,7 @@ impl dyn Any {
     /// ```
     /// use std::any::Any;
     ///
-    /// fn is_string(s: &Any) {
+    /// fn is_string(s: &dyn Any) {
     ///     if s.is::<String>() {
     ///         println!("It's a string!");
     ///     } else {
@@ -185,7 +185,7 @@ impl dyn Any {
     /// ```
     /// use std::any::Any;
     ///
-    /// fn print_if_string(s: &Any) {
+    /// fn print_if_string(s: &dyn Any) {
     ///     if let Some(string) = s.downcast_ref::<String>() {
     ///         println!("It's a string({}): '{}'", string.len(), string);
     ///     } else {
@@ -218,7 +218,7 @@ impl dyn Any {
     /// ```
     /// use std::any::Any;
     ///
-    /// fn modify_if_u32(s: &mut Any) {
+    /// fn modify_if_u32(s: &mut dyn Any) {
     ///     if let Some(num) = s.downcast_mut::<u32>() {
     ///         *num = 42;
     ///     }
@@ -256,7 +256,7 @@ impl dyn Any+Send {
     /// ```
     /// use std::any::Any;
     ///
-    /// fn is_string(s: &(Any + Send)) {
+    /// fn is_string(s: &(dyn Any + Send)) {
     ///     if s.is::<String>() {
     ///         println!("It's a string!");
     ///     } else {
@@ -282,7 +282,7 @@ impl dyn Any+Send {
     /// ```
     /// use std::any::Any;
     ///
-    /// fn print_if_string(s: &(Any + Send)) {
+    /// fn print_if_string(s: &(dyn Any + Send)) {
     ///     if let Some(string) = s.downcast_ref::<String>() {
     ///         println!("It's a string({}): '{}'", string.len(), string);
     ///     } else {
@@ -308,7 +308,7 @@ impl dyn Any+Send {
     /// ```
     /// use std::any::Any;
     ///
-    /// fn modify_if_u32(s: &mut (Any + Send)) {
+    /// fn modify_if_u32(s: &mut (dyn Any + Send)) {
     ///     if let Some(num) = s.downcast_mut::<u32>() {
     ///         *num = 42;
     ///     }
@@ -340,7 +340,7 @@ impl dyn Any+Send+Sync {
     /// ```
     /// use std::any::Any;
     ///
-    /// fn is_string(s: &(Any + Send + Sync)) {
+    /// fn is_string(s: &(dyn Any + Send + Sync)) {
     ///     if s.is::<String>() {
     ///         println!("It's a string!");
     ///     } else {
@@ -366,7 +366,7 @@ impl dyn Any+Send+Sync {
     /// ```
     /// use std::any::Any;
     ///
-    /// fn print_if_string(s: &(Any + Send + Sync)) {
+    /// fn print_if_string(s: &(dyn Any + Send + Sync)) {
     ///     if let Some(string) = s.downcast_ref::<String>() {
     ///         println!("It's a string({}): '{}'", string.len(), string);
     ///     } else {
@@ -392,7 +392,7 @@ impl dyn Any+Send+Sync {
     /// ```
     /// use std::any::Any;
     ///
-    /// fn modify_if_u32(s: &mut (Any + Send + Sync)) {
+    /// fn modify_if_u32(s: &mut (dyn Any + Send + Sync)) {
     ///     if let Some(num) = s.downcast_mut::<u32>() {
     ///         *num = 42;
     ///     }
diff --git a/src/libcore/benches/num/mod.rs b/src/libcore/benches/num/mod.rs
index 55f0bdb57ec..b57e167b05d 100644
--- a/src/libcore/benches/num/mod.rs
+++ b/src/libcore/benches/num/mod.rs
@@ -10,3 +10,108 @@
 
 mod flt2dec;
 mod dec2flt;
+
+use test::Bencher;
+use std::str::FromStr;
+
+const ASCII_NUMBERS: [&str; 19] = [
+    "0",
+    "1",
+    "2",
+    "43",
+    "765",
+    "76567",
+    "987245987",
+    "-4aa32",
+    "1786235",
+    "8723095",
+    "f##5s",
+    "83638730",
+    "-2345",
+    "562aa43",
+    "-1",
+    "-0",
+    "abc",
+    "xyz",
+    "c0ffee",
+];
+
+macro_rules! from_str_bench {
+    ($mac:ident, $t:ty) => (
+        #[bench]
+        fn $mac(b: &mut Bencher) {
+            b.iter(|| {
+                ASCII_NUMBERS
+                    .iter()
+                    .cycle()
+                    .take(5_000)
+                    .filter_map(|s| <($t)>::from_str(s).ok())
+                    .max()
+            })
+        }
+    )
+}
+
+macro_rules! from_str_radix_bench {
+    ($mac:ident, $t:ty, $radix:expr) => (
+        #[bench]
+        fn $mac(b: &mut Bencher) {
+            b.iter(|| {
+                ASCII_NUMBERS
+                    .iter()
+                    .cycle()
+                    .take(5_000)
+                    .filter_map(|s| <($t)>::from_str_radix(s, $radix).ok())
+                    .max()
+            })
+        }
+    )
+}
+
+from_str_bench!(bench_u8_from_str, u8);
+from_str_radix_bench!(bench_u8_from_str_radix_2, u8, 2);
+from_str_radix_bench!(bench_u8_from_str_radix_10, u8, 10);
+from_str_radix_bench!(bench_u8_from_str_radix_16, u8, 16);
+from_str_radix_bench!(bench_u8_from_str_radix_36, u8, 36);
+
+from_str_bench!(bench_u16_from_str, u16);
+from_str_radix_bench!(bench_u16_from_str_radix_2, u16, 2);
+from_str_radix_bench!(bench_u16_from_str_radix_10, u16, 10);
+from_str_radix_bench!(bench_u16_from_str_radix_16, u16, 16);
+from_str_radix_bench!(bench_u16_from_str_radix_36, u16, 36);
+
+from_str_bench!(bench_u32_from_str, u32);
+from_str_radix_bench!(bench_u32_from_str_radix_2, u32, 2);
+from_str_radix_bench!(bench_u32_from_str_radix_10, u32, 10);
+from_str_radix_bench!(bench_u32_from_str_radix_16, u32, 16);
+from_str_radix_bench!(bench_u32_from_str_radix_36, u32, 36);
+
+from_str_bench!(bench_u64_from_str, u64);
+from_str_radix_bench!(bench_u64_from_str_radix_2, u64, 2);
+from_str_radix_bench!(bench_u64_from_str_radix_10, u64, 10);
+from_str_radix_bench!(bench_u64_from_str_radix_16, u64, 16);
+from_str_radix_bench!(bench_u64_from_str_radix_36, u64, 36);
+
+from_str_bench!(bench_i8_from_str, i8);
+from_str_radix_bench!(bench_i8_from_str_radix_2, i8, 2);
+from_str_radix_bench!(bench_i8_from_str_radix_10, i8, 10);
+from_str_radix_bench!(bench_i8_from_str_radix_16, i8, 16);
+from_str_radix_bench!(bench_i8_from_str_radix_36, i8, 36);
+
+from_str_bench!(bench_i16_from_str, i16);
+from_str_radix_bench!(bench_i16_from_str_radix_2, i16, 2);
+from_str_radix_bench!(bench_i16_from_str_radix_10, i16, 10);
+from_str_radix_bench!(bench_i16_from_str_radix_16, i16, 16);
+from_str_radix_bench!(bench_i16_from_str_radix_36, i16, 36);
+
+from_str_bench!(bench_i32_from_str, i32);
+from_str_radix_bench!(bench_i32_from_str_radix_2, i32, 2);
+from_str_radix_bench!(bench_i32_from_str_radix_10, i32, 10);
+from_str_radix_bench!(bench_i32_from_str_radix_16, i32, 16);
+from_str_radix_bench!(bench_i32_from_str_radix_36, i32, 36);
+
+from_str_bench!(bench_i64_from_str, i64);
+from_str_radix_bench!(bench_i64_from_str_radix_2, i64, 2);
+from_str_radix_bench!(bench_i64_from_str_radix_10, i64, 10);
+from_str_radix_bench!(bench_i64_from_str_radix_16, i64, 16);
+from_str_radix_bench!(bench_i64_from_str_radix_36, i64, 36);
diff --git a/src/libcore/char/convert.rs b/src/libcore/char/convert.rs
index e9ccdd0ea3c..160728f923d 100644
--- a/src/libcore/char/convert.rs
+++ b/src/libcore/char/convert.rs
@@ -19,7 +19,7 @@ use super::MAX;
 /// Converts a `u32` to a `char`.
 ///
 /// Note that all [`char`]s are valid [`u32`]s, and can be cast to one with
-/// [`as`]:
+/// `as`:
 ///
 /// ```
 /// let c = '💯';
@@ -34,7 +34,6 @@ use super::MAX;
 ///
 /// [`char`]: ../../std/primitive.char.html
 /// [`u32`]: ../../std/primitive.u32.html
-/// [`as`]: ../../book/first-edition/casting-between-types.html#as
 ///
 /// For an unsafe version of this function which ignores these checks, see
 /// [`from_u32_unchecked`].
@@ -71,7 +70,7 @@ pub fn from_u32(i: u32) -> Option<char> {
 /// Converts a `u32` to a `char`, ignoring validity.
 ///
 /// Note that all [`char`]s are valid [`u32`]s, and can be cast to one with
-/// [`as`]:
+/// `as`:
 ///
 /// ```
 /// let c = '💯';
@@ -86,7 +85,6 @@ pub fn from_u32(i: u32) -> Option<char> {
 ///
 /// [`char`]: ../../std/primitive.char.html
 /// [`u32`]: ../../std/primitive.u32.html
-/// [`as`]: ../../book/first-edition/casting-between-types.html#as
 ///
 /// # Safety
 ///
diff --git a/src/libcore/iter/iterator.rs b/src/libcore/iter/iterator.rs
index 2903c370df8..fd4189ef50d 100644
--- a/src/libcore/iter/iterator.rs
+++ b/src/libcore/iter/iterator.rs
@@ -532,7 +532,7 @@ pub trait Iterator {
     /// If you're doing some sort of looping for a side effect, it's considered
     /// more idiomatic to use [`for`] than `map()`.
     ///
-    /// [`for`]: ../../book/first-edition/loops.html#for
+    /// [`for`]: ../../book/ch03-05-control-flow.html#looping-through-a-collection-with-for
     ///
     /// # Examples
     ///
@@ -580,7 +580,7 @@ pub trait Iterator {
     /// cases `for_each` may also be faster than a loop, because it will use
     /// internal iteration on adaptors like `Chain`.
     ///
-    /// [`for`]: ../../book/first-edition/loops.html#for
+    /// [`for`]: ../../book/ch03-05-control-flow.html#looping-through-a-collection-with-for
     ///
     /// # Examples
     ///
@@ -1669,7 +1669,7 @@ pub trait Iterator {
     /// use a `for` loop with a list of things to build up a result. Those
     /// can be turned into `fold()`s:
     ///
-    /// [`for`]: ../../book/first-edition/loops.html#for
+    /// [`for`]: ../../book/ch03-05-control-flow.html#looping-through-a-collection-with-for
     ///
     /// ```
     /// let numbers = [1, 2, 3, 4, 5];
diff --git a/src/libcore/mem.rs b/src/libcore/mem.rs
index d8eec2bd9a6..56ba10c49f4 100644
--- a/src/libcore/mem.rs
+++ b/src/libcore/mem.rs
@@ -132,7 +132,6 @@ pub use intrinsics::transmute;
 /// [uninit]: fn.uninitialized.html
 /// [clone]: ../clone/trait.Clone.html
 /// [swap]: fn.swap.html
-/// [FFI]: ../../book/first-edition/ffi.html
 /// [box]: ../../std/boxed/struct.Box.html
 /// [leak]: ../../std/boxed/struct.Box.html#method.leak
 /// [into_raw]: ../../std/boxed/struct.Box.html#method.into_raw
@@ -479,7 +478,7 @@ pub const fn needs_drop<T>() -> bool {
 ///
 /// This has the same effect as allocating space with
 /// [`mem::uninitialized`][uninit] and then zeroing it out. It is useful for
-/// [FFI] sometimes, but should generally be avoided.
+/// FFI sometimes, but should generally be avoided.
 ///
 /// There is no guarantee that an all-zero byte-pattern represents a valid value of
 /// some type `T`. If `T` has a destructor and the value is destroyed (due to
@@ -490,7 +489,6 @@ pub const fn needs_drop<T>() -> bool {
 /// many of the same caveats.
 ///
 /// [uninit]: fn.uninitialized.html
-/// [FFI]: ../../book/first-edition/ffi.html
 /// [ub]: ../../reference/behavior-considered-undefined.html
 ///
 /// # Examples
@@ -514,11 +512,9 @@ pub unsafe fn zeroed<T>() -> T {
 /// **This is incredibly dangerous and should not be done lightly. Deeply
 /// consider initializing your memory with a default value instead.**
 ///
-/// This is useful for [FFI] functions and initializing arrays sometimes,
+/// This is useful for FFI functions and initializing arrays sometimes,
 /// but should generally be avoided.
 ///
-/// [FFI]: ../../book/first-edition/ffi.html
-///
 /// # Undefined behavior
 ///
 /// It is [undefined behavior][ub] to read uninitialized memory, even just an
@@ -689,10 +685,9 @@ pub fn replace<T>(dest: &mut T, mut src: T) -> T {
 /// While this does call the argument's implementation of [`Drop`][drop],
 /// it will not release any borrows, as borrows are based on lexical scope.
 ///
-/// This effectively does nothing for
-/// [types which implement `Copy`](../../book/first-edition/ownership.html#copy-types),
-/// e.g. integers. Such values are copied and _then_ moved into the function,
-/// so the value persists after this function call.
+/// This effectively does nothing for types which implement `Copy`, e.g.
+/// integers. Such values are copied and _then_ moved into the function, so the
+/// value persists after this function call.
 ///
 /// This function is not magic; it is literally defined as
 ///
@@ -1021,7 +1016,7 @@ impl<T: ?Sized> ManuallyDrop<T> {
 impl<T: ?Sized> Deref for ManuallyDrop<T> {
     type Target = T;
     #[inline]
-    fn deref(&self) -> &Self::Target {
+    fn deref(&self) -> &T {
         &self.value
     }
 }
@@ -1029,7 +1024,7 @@ impl<T: ?Sized> Deref for ManuallyDrop<T> {
 #[stable(feature = "manually_drop", since = "1.20.0")]
 impl<T: ?Sized> DerefMut for ManuallyDrop<T> {
     #[inline]
-    fn deref_mut(&mut self) -> &mut Self::Target {
+    fn deref_mut(&mut self) -> &mut T {
         &mut self.value
     }
 }
diff --git a/src/libcore/ptr.rs b/src/libcore/ptr.rs
index a7bfc3f5124..e9cf11424ca 100644
--- a/src/libcore/ptr.rs
+++ b/src/libcore/ptr.rs
@@ -58,7 +58,7 @@
 //! [`NonNull::dangling`] in such cases.
 //!
 //! [aliasing]: ../../nomicon/aliasing.html
-//! [book]: ../../book/second-edition/ch19-01-unsafe-rust.html#dereferencing-a-raw-pointer
+//! [book]: ../../book/ch19-01-unsafe-rust.html#dereferencing-a-raw-pointer
 //! [ub]: ../../reference/behavior-considered-undefined.html
 //! [null]: ./fn.null.html
 //! [zst]: ../../nomicon/exotic-sizes.html#zero-sized-types-zsts
diff --git a/src/libcore/raw.rs b/src/libcore/raw.rs
index b7597795b5e..3d4bccb4f9d 100644
--- a/src/libcore/raw.rs
+++ b/src/libcore/raw.rs
@@ -21,11 +21,7 @@
 /// The representation of a trait object like `&SomeTrait`.
 ///
 /// This struct has the same layout as types like `&SomeTrait` and
-/// `Box<dyn AnotherTrait>`. The [Trait Objects chapter of the
-/// Book][moreinfo] contains more details about the precise nature of
-/// these internals.
-///
-/// [moreinfo]: ../../book/first-edition/trait-objects.html#representation
+/// `Box<dyn AnotherTrait>`.
 ///
 /// `TraitObject` is guaranteed to match layouts, but it is not the
 /// type of trait objects (e.g. the fields are not directly accessible
diff --git a/src/libcore/slice/mod.rs b/src/libcore/slice/mod.rs
index fece328f51f..8c55a16f3c8 100644
--- a/src/libcore/slice/mod.rs
+++ b/src/libcore/slice/mod.rs
@@ -1510,6 +1510,22 @@ impl<T> [T] {
     /// This sort is unstable (i.e. may reorder equal elements), in-place (i.e. does not allocate),
     /// and `O(n log n)` worst-case.
     ///
+    /// The comparator function must define a total ordering for the elements in the slice. If
+    /// the ordering is not total, the order of the elements is unspecified. An order is a
+    /// total order if it is (for all a, b and c):
+    ///
+    /// * total and antisymmetric: exactly one of a < b, a == b or a > b is true; and
+    /// * transitive, a < b and b < c implies a < c. The same must hold for both == and >.
+    ///
+    /// For example, while [`f64`] doesn't implement [`Ord`] because `NaN != NaN`, we can use
+    /// `partial_cmp` as our sort function when we know the slice doesn't contain a `NaN`.
+    ///
+    /// ```
+    /// let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
+    /// floats.sort_by(|a, b| a.partial_cmp(b).unwrap());
+    /// assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);
+    /// ```
+    ///
     /// # Current implementation
     ///
     /// The current algorithm is based on [pattern-defeating quicksort][pdqsort] by Orson Peters,