Auto merge of #57714 - matthewjasper:wellformed-unreachable, r=pnkfelix

[rust.git] / src / libcore / option.rs

diff --git a/src/libcore/option.rs b/src/libcore/option.rs
index 9db7e47b08cfaced674208f781203104369af318..0e54397db02476942bdda8998f04f4447b64a5a4 100644 (file)
--- a/src/libcore/option.rs
+++ b/src/libcore/option.rs
@@ -1,13 +1,3 @@
-// Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT
-// file at the top-level directory of this distribution and at
-// http://rust-lang.org/COPYRIGHT.
-//
-// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
-// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
-// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
-// option. This file may not be copied, modified, or distributed
-// except according to those terms.
-
 //! Optional values.
 //!
 //! Type [`Option`] represents an optional value: every [`Option`]
@@ -273,7 +263,7 @@ pub fn as_mut(&mut self) -> Option<&mut T> {
 
     /// Converts from `Pin<&Option<T>>` to `Option<Pin<&T>>`
     #[inline]
-    #[unstable(feature = "pin", issue = "49150")]
+    #[stable(feature = "pin", since = "1.33.0")]
     pub fn as_pin_ref<'a>(self: Pin<&'a Option<T>>) -> Option<Pin<&'a T>> {
         unsafe {
             Pin::get_ref(self).as_ref().map(|x| Pin::new_unchecked(x))
@@ -282,10 +272,10 @@ pub fn as_pin_ref<'a>(self: Pin<&'a Option<T>>) -> Option<Pin<&'a T>> {
 
     /// Converts from `Pin<&mut Option<T>>` to `Option<Pin<&mut T>>`
     #[inline]
-    #[unstable(feature = "pin", issue = "49150")]
+    #[stable(feature = "pin", since = "1.33.0")]
     pub fn as_pin_mut<'a>(self: Pin<&'a mut Option<T>>) -> Option<Pin<&'a mut T>> {
         unsafe {
-            Pin::get_mut_unchecked(self).as_mut().map(|x| Pin::new_unchecked(x))
+            Pin::get_unchecked_mut(self).as_mut().map(|x| Pin::new_unchecked(x))
         }
     }
 
@@ -1023,8 +1013,6 @@ impl<T, E> Option<Result<T, E>> {
     /// # Examples
     ///
     /// ```
-    /// #![feature(transpose_result)]
-    ///
     /// #[derive(Debug, Eq, PartialEq)]
     /// struct SomeErr;
     ///
@@ -1033,7 +1021,7 @@ impl<T, E> Option<Result<T, E>> {
     /// assert_eq!(x, y.transpose());
     /// ```
     #[inline]
-    #[unstable(feature = "transpose_result", issue = "47338")]
+    #[stable(feature = "transpose_result", since = "1.33.0")]
     pub fn transpose(self) -> Result<Option<T>, E> {
         match self {
             Some(Ok(x)) => Ok(Some(x)),
@@ -1295,19 +1283,41 @@ impl<A, V: FromIterator<A>> FromIterator<Option<A>> for Option<V> {
     /// returned. Should no [`None`][Option::None] occur, a container with the
     /// values of each [`Option`] is returned.
     ///
-    /// Here is an example which increments every integer in a vector,
-    /// checking for overflow:
+    /// # Examples
+    ///
+    /// Here is an example which increments every integer in a vector.
+    /// `We use the checked variant of `add` that returns `None` when the
+    /// calculation would result in an overflow.
+    ///
+    /// ```
+    /// let items = vec![0_u16, 1, 2];
+    ///
+    /// let res: Option<Vec<u16>> = items
+    ///     .iter()
+    ///     .map(|x| x.checked_add(1))
+    ///     .collect();
     ///
+    /// assert_eq!(res, Some(vec![1, 2, 3]));
     /// ```
-    /// use std::u16;
     ///
-    /// let v = vec![1, 2];
-    /// let res: Option<Vec<u16>> = v.iter().map(|&x: &u16|
-    ///     if x == u16::MAX { None }
-    ///     else { Some(x + 1) }
-    /// ).collect();
-    /// assert!(res == Some(vec![2, 3]));
+    /// As you can see, this will return the expected, valid items.
+    ///
+    /// Here is another example that tries to subtract one from another list
+    /// of integers, this time checking for underflow:
+    ///
     /// ```
+    /// let items = vec![2_u16, 1, 0];
+    ///
+    /// let res: Option<Vec<u16>> = items
+    ///     .iter()
+    ///     .map(|x| x.checked_sub(1))
+    ///     .collect();
+    ///
+    /// assert_eq!(res, None);
+    /// ```
+    ///
+    /// Since the last element is zero, it would underflow. Thus, the resulting
+    /// value is `None`.
     ///
     /// [`Iterator`]: ../iter/trait.Iterator.html
     #[inline]