Rollup merge of #42370 - mbrubeck:docs, r=frewsxcv

[rust.git] / src / libcollections / slice.rs

diff --git a/src/libcollections/slice.rs b/src/libcollections/slice.rs
index dd3259f0cb4d7d44c758d4d5ff77a91212aa33ec..97d6687c79b5749aaa3d69e5d0d64a373cb0f133 100644 (file)
--- a/src/libcollections/slice.rs
+++ b/src/libcollections/slice.rs
@@ -393,7 +393,12 @@ pub fn get_mut<I>(&mut self, index: I) -> Option<&mut I::Output>
     }
 
     /// Returns a reference to an element or subslice, without doing bounds
-    /// checking. So use it very carefully!
+    /// checking.
+    ///
+    /// This is generally not recommended, use with caution! For a safe
+    /// alternative see [`get`].
+    ///
+    /// [`get`]: #method.get
     ///
     /// # Examples
     ///
@@ -413,7 +418,12 @@ pub unsafe fn get_unchecked<I>(&self, index: I) -> &I::Output
     }
 
     /// Returns a mutable reference to an element or subslice, without doing
-    /// bounds checking. So use it very carefully!
+    /// bounds checking.
+    ///
+    /// This is generally not recommended, use with caution! For a safe
+    /// alternative see [`get_mut`].
+    ///
+    /// [`get_mut`]: #method.get_mut
     ///
     /// # Examples
     ///
@@ -1337,19 +1347,17 @@ pub fn sort_unstable_by_key<B, F>(&mut self, f: F)
         core_slice::SliceExt::sort_unstable_by_key(self, f);
     }
 
-    /// Permutes the slice in-place such that `self[mid..]` move to the
-    /// beginning of the slice while `self[..mid]` move to the end of the
+    /// Permutes the slice in-place such that `self[mid..]` moves to the
+    /// beginning of the slice while `self[..mid]` moves to the end of the
     /// slice.  Equivalently, rotates the slice `mid` places to the left
     /// or `k = self.len() - mid` places to the right.
     ///
-    /// Rotation by `mid` and rotation by `k` are inverse operations.
-    /// The method returns `k`, which is also the new location of
-    /// the formerly-first element.
-    ///
     /// This is a "k-rotation", a permutation in which item `i` moves to
     /// position `i + k`, modulo the length of the slice.  See _Elements
     /// of Programming_ [§10.4][eop].
     ///
+    /// Rotation by `mid` and rotation by `k` are inverse operations.
+    ///
     /// [eop]: https://books.google.com/books?id=CO9ULZGINlsC&pg=PA178&q=k-rotation
     ///
     /// # Panics
@@ -1368,8 +1376,10 @@ pub fn sort_unstable_by_key<B, F>(&mut self, f: F)
     /// #![feature(slice_rotate)]
     ///
     /// let mut a = [1, 2, 3, 4, 5, 6, 7];
-    /// let k = a.rotate(2);
+    /// let mid = 2;
+    /// a.rotate(mid);
     /// assert_eq!(&a, &[3, 4, 5, 6, 7, 1, 2]);
+    /// let k = a.len() - mid;
     /// a.rotate(k);
     /// assert_eq!(&a, &[1, 2, 3, 4, 5, 6, 7]);
     ///
@@ -1388,8 +1398,8 @@ pub fn sort_unstable_by_key<B, F>(&mut self, f: F)
     /// assert_eq!(&v, &[0, 3, 7, 4, 5, 6, 1, 2, 8, 9]);
     /// ```
     #[unstable(feature = "slice_rotate", issue = "41891")]
-    pub fn rotate(&mut self, mid: usize) -> usize {
-        core_slice::SliceExt::rotate(self, mid)
+    pub fn rotate(&mut self, mid: usize) {
+        core_slice::SliceExt::rotate(self, mid);
     }
 
     /// Copies the elements from `src` into `self`.
@@ -1465,6 +1475,9 @@ pub fn to_vec(&self) -> Vec<T>
 
     /// Converts `self` into a vector without clones or allocation.
     ///
+    /// The resulting vector can be converted back into a box via
+    /// `Vec<T>`'s `into_boxed_slice` method.
+    ///
     /// # Examples
     ///
     /// ```
@@ -1502,6 +1515,7 @@ pub trait SliceConcatExt<T: ?Sized> {
     ///
     /// ```
     /// assert_eq!(["hello", "world"].concat(), "helloworld");
+    /// assert_eq!([[1, 2], [3, 4]].concat(), [1, 2, 3, 4]);
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     fn concat(&self) -> Self::Output;
@@ -1513,6 +1527,7 @@ pub trait SliceConcatExt<T: ?Sized> {
     ///
     /// ```
     /// assert_eq!(["hello", "world"].join(" "), "hello world");
+    /// assert_eq!([[1, 2], [3, 4]].join(&0), [1, 2, 0, 3, 4]);
     /// ```
     #[stable(feature = "rename_connect_to_join", since = "1.3.0")]
     fn join(&self, sep: &T) -> Self::Output;