Merge remote-tracking branch 'upstream/master' into format-with-capacity

8 files changed, 138 insertions, 66 deletions

diff --git a/src/libcore/cell.rs b/src/libcore/cell.rs
index c3f862e7c54..ab44342ebf0 100644
--- a/src/libcore/cell.rs
+++ b/src/libcore/cell.rs
@@ -15,10 +15,18 @@
 //! references. We say that `Cell<T>` and `RefCell<T>` provide 'interior mutability', in contrast
 //! with typical Rust types that exhibit 'inherited mutability'.
 //!
-//! Cell types come in two flavors: `Cell<T>` and `RefCell<T>`. `Cell<T>` provides `get` and `set`
-//! methods that change the interior value with a single method call. `Cell<T>` though is only
-//! compatible with types that implement `Copy`. For other types, one must use the `RefCell<T>`
-//! type, acquiring a write lock before mutating.
+//! Cell types come in two flavors: `Cell<T>` and `RefCell<T>`. `Cell<T>` implements interior
+//! mutability by moving values in and out of the `Cell<T>`. To use references instead of values,
+//! one must use the `RefCell<T>` type, acquiring a write lock before mutating. `Cell<T>` provides
+//! methods to retrieve and change the current interior value:
+//!
+//!  - For types that implement `Copy`, the `get` method retrieves the current interior value.
+//!  - For types that implement `Default`, the `take` method replaces the current interior value
+//!    with `Default::default()` and returns the replaced value.
+//!  - For all types, the `replace` method replaces the current interior value and returns the
+//!    replaced value and the `into_inner` method consumes the `Cell<T>` and returns the interior
+//!    value. Additionally, the `set` method replaces the interior value, dropping the replaced
+//!    value.
 //!
 //! `RefCell<T>` uses Rust's lifetimes to implement 'dynamic borrowing', a process whereby one can
 //! claim temporary, exclusive, mutable access to the inner value. Borrows for `RefCell<T>`s are
@@ -176,9 +184,10 @@
 use cmp::Ordering;
 use fmt::{self, Debug, Display};
 use marker::Unsize;
+use mem;
 use ops::{Deref, DerefMut, CoerceUnsized};
 
-/// A mutable memory location that admits only `Copy` data.
+/// A mutable memory location.
 ///
 /// See the [module-level documentation](index.html) for more.
 #[stable(feature = "rust1", since = "1.0.0")]
@@ -187,23 +196,6 @@ pub struct Cell<T> {
 }
 
 impl<T:Copy> Cell<T> {
-    /// Creates a new `Cell` containing the given value.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// use std::cell::Cell;
-    ///
-    /// let c = Cell::new(5);
-    /// ```
-    #[stable(feature = "rust1", since = "1.0.0")]
-    #[inline]
-    pub const fn new(value: T) -> Cell<T> {
-        Cell {
-            value: UnsafeCell::new(value),
-        }
-    }
-
     /// Returns a copy of the contained value.
     ///
     /// # Examples
@@ -221,25 +213,6 @@ impl<T:Copy> Cell<T> {
         unsafe{ *self.value.get() }
     }
 
-    /// Sets the contained value.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// use std::cell::Cell;
-    ///
-    /// let c = Cell::new(5);
-    ///
-    /// c.set(10);
-    /// ```
-    #[inline]
-    #[stable(feature = "rust1", since = "1.0.0")]
-    pub fn set(&self, value: T) {
-        unsafe {
-            *self.value.get() = value;
-        }
-    }
-
     /// Returns a reference to the underlying `UnsafeCell`.
     ///
     /// # Examples
@@ -378,6 +351,100 @@ impl<T: Copy> From<T> for Cell<T> {
     }
 }
 
+impl<T> Cell<T> {
+    /// Creates a new `Cell` containing the given value.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::cell::Cell;
+    ///
+    /// let c = Cell::new(5);
+    /// ```
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[inline]
+    pub const fn new(value: T) -> Cell<T> {
+        Cell {
+            value: UnsafeCell::new(value),
+        }
+    }
+
+    /// Sets the contained value.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::cell::Cell;
+    ///
+    /// let c = Cell::new(5);
+    ///
+    /// c.set(10);
+    /// ```
+    #[inline]
+    #[stable(feature = "rust1", since = "1.0.0")]
+    pub fn set(&self, val: T) {
+        let old = self.replace(val);
+        drop(old);
+    }
+
+    /// Replaces the contained value.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(move_cell)]
+    /// use std::cell::Cell;
+    ///
+    /// let c = Cell::new(5);
+    /// let old = c.replace(10);
+    ///
+    /// assert_eq!(5, old);
+    /// ```
+    #[unstable(feature = "move_cell", issue = "39264")]
+    pub fn replace(&self, val: T) -> T {
+        mem::replace(unsafe { &mut *self.value.get() }, val)
+    }
+
+    /// Unwraps the value.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(move_cell)]
+    /// use std::cell::Cell;
+    ///
+    /// let c = Cell::new(5);
+    /// let five = c.into_inner();
+    ///
+    /// assert_eq!(five, 5);
+    /// ```
+    #[unstable(feature = "move_cell", issue = "39264")]
+    pub fn into_inner(self) -> T {
+        unsafe { self.value.into_inner() }
+    }
+}
+
+impl<T: Default> Cell<T> {
+    /// Takes the value of the cell, leaving `Default::default()` in its place.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(move_cell)]
+    /// use std::cell::Cell;
+    ///
+    /// let c = Cell::new(5);
+    /// let five = c.take();
+    ///
+    /// assert_eq!(five, 5);
+    /// assert_eq!(c.into_inner(), 0);
+    /// ```
+    #[unstable(feature = "move_cell", issue = "39264")]
+    pub fn take(&self) -> T {
+        self.replace(Default::default())
+    }
+}
+
 #[unstable(feature = "coerce_unsized", issue = "27732")]
 impl<T: CoerceUnsized<U>, U> CoerceUnsized<Cell<U>> for Cell<T> {}
 
diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs
index 830bbc079ad..abd686b15e2 100644
--- a/src/libcore/convert.rs
+++ b/src/libcore/convert.rs
@@ -18,25 +18,33 @@
 //! support arguments of multiple types.
 //!
 //! - Impl the `As*` traits for reference-to-reference conversions
-//! - Impl the `Into` trait when you want to consume the value in the conversion
-//! - The `From` trait is the most flexible, useful for value _and_ reference conversions
-//! - The `TryFrom` and `TryInto` traits behave like `From` and `Into`, but allow for the
+//! - Impl the [`Into`] trait when you want to consume the value in the conversion
+//! - The [`From`] trait is the most flexible, useful for value _and_ reference conversions
+//! - The [`TryFrom`] and [`TryInto`] traits behave like [`From`] and [`Into`], but allow for the
 //!   conversion to fail
 //!
-//! As a library author, you should prefer implementing `From<T>` or `TryFrom<T>` rather than
-//! `Into<U>` or `TryInto<U>`, as `From` and `TryFrom` provide greater flexibility and offer
-//! equivalent `Into` or `TryInto` implementations for free, thanks to a blanket implementation
+//! As a library author, you should prefer implementing [`From<T>`][`From`] or
+//! [`TryFrom<T>`][`TryFrom`] rather than [`Into<U>`][`Into`] or [`TryInto<U>`][`TryInto`],
+//! as [`From`] and [`TryFrom`] provide greater flexibility and offer
+//! equivalent [`Into`] or [`TryInto`] implementations for free, thanks to a blanket implementation
 //! in the standard library.
 //!
 //! # Generic impl
 //!
-//! - `AsRef` and `AsMut` auto-dereference if the inner type is a reference
-//! - `From<U> for T` implies `Into<T> for U`
-//! - `TryFrom<U> for T` implies `TryInto<T> for U`
-//! - `From` and `Into` are reflexive, which means that all types can `into()`
+//! - [`AsRef`] and [`AsMut`] auto-dereference if the inner type is a reference
+//! - [`From`]`<U> for T` implies [`Into`]`<T> for U`
+//! - [`TryFrom`]`<U> for T` implies [`TryInto`]`<T> for U`
+//! - [`From`] and [`Into`] are reflexive, which means that all types can `into()`
 //!   themselves and `from()` themselves
 //!
 //! See each trait for usage examples.
+//!
+//! [`Into`]: trait.Into.html
+//! [`From`]: trait.From.html
+//! [`TryFrom`]: trait.TryFrom.html
+//! [`TryInto`]: trait.TryInto.html
+//! [`AsRef`]: trait.AsRef.html
+//! [`AsMut`]: trait.AsMut.html
 
 #![stable(feature = "rust1", since = "1.0.0")]
 
diff --git a/src/libcore/hash/mod.rs b/src/libcore/hash/mod.rs
index 92657a6d0b1..dd6edc7d39a 100644
--- a/src/libcore/hash/mod.rs
+++ b/src/libcore/hash/mod.rs
@@ -307,6 +307,7 @@ pub trait BuildHasher {
 /// [`BuildHasher`]: trait.BuildHasher.html
 /// [`Default`]: ../default/trait.Default.html
 /// [`Hasher`]: trait.Hasher.html
+/// [`HashMap`]: ../../std/collections/struct.HashMap.html
 #[stable(since = "1.7.0", feature = "build_hasher")]
 pub struct BuildHasherDefault<H>(marker::PhantomData<H>);
 
diff --git a/src/libcore/iter/iterator.rs b/src/libcore/iter/iterator.rs
index 91c09c55305..3b406873d4b 100644
--- a/src/libcore/iter/iterator.rs
+++ b/src/libcore/iter/iterator.rs
@@ -1108,9 +1108,9 @@ pub trait Iterator {
     ///
     /// One of the keys to `collect()`'s power is that many things you might
     /// not think of as 'collections' actually are. For example, a [`String`]
-    /// is a collection of [`char`]s. And a collection of [`Result<T, E>`] can
-    /// be thought of as single [`Result`]`<Collection<T>, E>`. See the examples
-    /// below for more.
+    /// is a collection of [`char`]s. And a collection of
+    /// [`Result<T, E>`][`Result`] can be thought of as single
+    /// [`Result`]`<Collection<T>, E>`. See the examples below for more.
     ///
     /// Because `collect()` is so general, it can cause problems with type
     /// inference. As such, `collect()` is one of the few times you'll see
diff --git a/src/libcore/option.rs b/src/libcore/option.rs
index 8871e1fa840..c4d7b2dcf96 100644
--- a/src/libcore/option.rs
+++ b/src/libcore/option.rs
@@ -60,7 +60,7 @@
 //! the optional owned box, [`Option`]`<`[`Box<T>`]`>`.
 //!
 //! The following example uses [`Option`] to create an optional box of
-//! [`i32`]. Notice that in order to use the inner [`i32`] value first the
+//! [`i32`]. Notice that in order to use the inner [`i32`] value first, the
 //! `check_optional` function needs to use pattern matching to
 //! determine whether the box has a value (i.e. it is [`Some(...)`][`Some`]) or
 //! not ([`None`]).
@@ -74,8 +74,8 @@
 //!
 //! fn check_optional(optional: &Option<Box<i32>>) {
 //!     match *optional {
-//!         Some(ref p) => println!("have value {}", p),
-//!         None => println!("have no value"),
+//!         Some(ref p) => println!("has value {}", p),
+//!         None => println!("has no value"),
 //!     }
 //! }
 //! ```
diff --git a/src/libcore/ptr.rs b/src/libcore/ptr.rs
index bf5a59c45e4..02851c224e2 100644
--- a/src/libcore/ptr.rs
+++ b/src/libcore/ptr.rs
@@ -448,7 +448,6 @@ impl<T: ?Sized> *const T {
     /// Basic usage:
     ///
     /// ```
-    /// #![feature(ptr_wrapping_offset)]
     /// // Iterate using a raw pointer in increments of two elements
     /// let data = [1u8, 2, 3, 4, 5];
     /// let mut ptr: *const u8 = data.as_ptr();
@@ -463,7 +462,7 @@ impl<T: ?Sized> *const T {
     ///     ptr = ptr.wrapping_offset(step);
     /// }
     /// ```
-    #[unstable(feature = "ptr_wrapping_offset", issue = "37570")]
+    #[stable(feature = "ptr_wrapping_offset", since = "1.16.0")]
     #[inline]
     pub fn wrapping_offset(self, count: isize) -> *const T where T: Sized {
         unsafe {
@@ -572,7 +571,6 @@ impl<T: ?Sized> *mut T {
     /// Basic usage:
     ///
     /// ```
-    /// #![feature(ptr_wrapping_offset)]
     /// // Iterate using a raw pointer in increments of two elements
     /// let mut data = [1u8, 2, 3, 4, 5];
     /// let mut ptr: *mut u8 = data.as_mut_ptr();
@@ -587,7 +585,7 @@ impl<T: ?Sized> *mut T {
     /// }
     /// assert_eq!(&data, &[0, 2, 0, 4, 0]);
     /// ```
-    #[unstable(feature = "ptr_wrapping_offset", issue = "37570")]
+    #[stable(feature = "ptr_wrapping_offset", since = "1.16.0")]
     #[inline]
     pub fn wrapping_offset(self, count: isize) -> *mut T where T: Sized {
         unsafe {
diff --git a/src/libcore/result.rs b/src/libcore/result.rs
index f02df88bb2e..0a2e3639653 100644
--- a/src/libcore/result.rs
+++ b/src/libcore/result.rs
@@ -840,8 +840,6 @@ impl<T: Default, E> Result<T, E> {
     /// `Err` on error.
     ///
     /// ```
-    /// #![feature(result_unwrap_or_default)]
-    ///
     /// let good_year_from_input = "1909";
     /// let bad_year_from_input = "190blarg";
     /// let good_year = good_year_from_input.parse().unwrap_or_default();
@@ -854,7 +852,7 @@ impl<T: Default, E> Result<T, E> {
     /// [`FromStr`]: ../../std/str/trait.FromStr.html
     /// ```
     #[inline]
-    #[unstable(feature = "result_unwrap_or_default", issue = "37516")]
+    #[stable(feature = "result_unwrap_or_default", since = "1.16.0")]
     pub fn unwrap_or_default(self) -> T {
         match self {
             Ok(x) => x,
diff --git a/src/libcore/sync/atomic.rs b/src/libcore/sync/atomic.rs
index a3cb1284477..743e3c41170 100644
--- a/src/libcore/sync/atomic.rs
+++ b/src/libcore/sync/atomic.rs
@@ -24,7 +24,7 @@
 //! same as [LLVM atomic orderings][1]. For more information see the [nomicon][2].
 //!
 //! [1]: http://llvm.org/docs/LangRef.html#memory-model-for-concurrent-operations
-//! [2]: https://doc.rust-lang.org/nomicon/atomics.html
+//! [2]: ../../../nomicon/atomics.html
 //!
 //! Atomic variables are safe to share between threads (they implement `Sync`)
 //! but they do not themselves provide the mechanism for sharing and follow the
@@ -144,7 +144,7 @@ unsafe impl<T> Sync for AtomicPtr<T> {}
 /// LLVM's](http://llvm.org/docs/LangRef.html#memory-model-for-concurrent-operations).
 ///
 /// For more information see the [nomicon][1].
-/// [1]: https://doc.rust-lang.org/nomicon/atomics.html
+/// [1]: ../../../nomicon/atomics.html
 #[stable(feature = "rust1", since = "1.0.0")]
 #[derive(Copy, Clone, Debug)]
 pub enum Ordering {