From 50483d5fa3cf67bf97f1823af0561344e51799ce Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Fri, 8 Jul 2016 17:21:16 +0200 Subject: [PATCH] Improve slice docs --- src/libcollections/slice.rs | 245 ++++++++++++++++++++++++++++++++++-- 1 file changed, 236 insertions(+), 9 deletions(-) diff --git a/src/libcollections/slice.rs b/src/libcollections/slice.rs index cef8a33703b..313b01e3c1a 100644 --- a/src/libcollections/slice.rs +++ b/src/libcollections/slice.rs @@ -200,7 +200,18 @@ impl [T] { core_slice::SliceExt::first(self) } - /// Returns a mutable pointer to the first element of a slice, or `None` if it is empty + /// Returns a mutable pointer to the first element of a slice, or `None` if it is empty. + /// + /// # Examples + /// + /// ``` + /// let x = &mut [0, 1, 2]; + /// + /// if let Some(first) = x.first_mut() { + /// *first = 5; + /// } + /// assert_eq!(x, &[5, 1, 2]); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[inline] pub fn first_mut(&mut self) -> Option<&mut T> { @@ -208,6 +219,17 @@ impl [T] { } /// Returns the first and all the rest of the elements of a slice. + /// + /// # Examples + /// + /// ``` + /// let x = &[0, 1, 2]; + /// + /// if let Some((first, elements)) = x.split_first() { + /// assert_eq!(first, &0); + /// assert_eq!(elements, &[1, 2]); + /// } + /// ``` #[stable(feature = "slice_splits", since = "1.5.0")] #[inline] pub fn split_first(&self) -> Option<(&T, &[T])> { @@ -215,6 +237,19 @@ impl [T] { } /// Returns the first and all the rest of the elements of a slice. + /// + /// # Examples + /// + /// ``` + /// let x = &mut [0, 1, 2]; + /// + /// if let Some((first, elements)) = x.split_first_mut() { + /// *first = 3; + /// elements[0] = 4; + /// elements[1] = 5; + /// } + /// assert_eq!(x, &[3, 4, 5]); + /// ``` #[stable(feature = "slice_splits", since = "1.5.0")] #[inline] pub fn split_first_mut(&mut self) -> Option<(&mut T, &mut [T])> { @@ -222,6 +257,17 @@ impl [T] { } /// Returns the last and all the rest of the elements of a slice. + /// + /// # Examples + /// + /// ``` + /// let x = &[0, 1, 2]; + /// + /// if let Some((last, elements)) = x.split_last() { + /// assert_eq!(last, &2); + /// assert_eq!(elements, &[0, 1]); + /// } + /// ``` #[stable(feature = "slice_splits", since = "1.5.0")] #[inline] pub fn split_last(&self) -> Option<(&T, &[T])> { @@ -230,6 +276,19 @@ impl [T] { } /// Returns the last and all the rest of the elements of a slice. + /// + /// # Examples + /// + /// ``` + /// let x = &mut [0, 1, 2]; + /// + /// if let Some((last, elements)) = x.split_last_mut() { + /// *last = 3; + /// elements[0] = 4; + /// elements[1] = 5; + /// } + /// assert_eq!(x, &[4, 5, 3]); + /// ``` #[stable(feature = "slice_splits", since = "1.5.0")] #[inline] pub fn split_last_mut(&mut self) -> Option<(&mut T, &mut [T])> { @@ -254,6 +313,17 @@ impl [T] { } /// Returns a mutable pointer to the last item in the slice. + /// + /// # Examples + /// + /// ``` + /// let x = &mut [0, 1, 2]; + /// + /// if let Some(last) = x.last_mut() { + /// *last = 10; + /// } + /// assert_eq!(x, &[0, 1, 10]); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[inline] pub fn last_mut(&mut self) -> Option<&mut T> { @@ -276,7 +346,18 @@ impl [T] { core_slice::SliceExt::get(self, index) } - /// Returns a mutable reference to the element at the given index, + /// Returns a mutable reference to the element at the given index. + /// + /// # Examples + /// + /// ``` + /// let x = &mut [0, 1, 2]; + /// + /// if let Some(elem) = x.get_mut(1) { + /// *elem = 42; + /// } + /// assert_eq!(x, &[0, 42, 2]); + /// ``` /// or `None` if the index is out of bounds #[stable(feature = "rust1", since = "1.0.0")] #[inline] @@ -285,14 +366,37 @@ impl [T] { } /// Returns a pointer to the element at the given index, without doing - /// bounds checking. + /// bounds checking. So use it very carefully! + /// + /// # Examples + /// + /// ``` + /// let x = &[1, 2, 4]; + /// + /// unsafe { + /// assert_eq!(x.get_unchecked(1), &2); + /// } + /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[inline] pub unsafe fn get_unchecked(&self, index: usize) -> &T { core_slice::SliceExt::get_unchecked(self, index) } - /// Returns an unsafe mutable pointer to the element in index + /// Returns an unsafe mutable pointer to the element in index. So use it + /// very carefully! + /// + /// # Examples + /// + /// ``` + /// let x = &mut [1, 2, 4]; + /// + /// unsafe { + /// let elem = x.get_unchecked_mut(1); + /// *elem = 13; + /// } + /// assert_eq!(x, &[1, 13, 4]); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[inline] pub unsafe fn get_unchecked_mut(&mut self, index: usize) -> &mut T { @@ -306,6 +410,19 @@ impl [T] { /// /// Modifying the slice may cause its buffer to be reallocated, which /// would also make any pointers to it invalid. + /// + /// # Examples + /// + /// ``` + /// let x = &[1, 2, 4]; + /// let x_ptr = x.as_ptr(); + /// + /// unsafe { + /// for i in 0..x.len() { + /// assert_eq!(x.get_unchecked(i), &*x_ptr.offset(i as isize)); + /// } + /// } + /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[inline] pub fn as_ptr(&self) -> *const T { @@ -319,6 +436,20 @@ impl [T] { /// /// Modifying the slice may cause its buffer to be reallocated, which /// would also make any pointers to it invalid. + /// + /// # Examples + /// + /// ``` + /// let x = &mut [1, 2, 4]; + /// let x_ptr = x.as_mut_ptr(); + /// + /// unsafe { + /// for i in 0..x.len() { + /// *x_ptr.offset(i as isize) += 2; + /// } + /// } + /// assert_eq!(x, &[3, 4, 6]); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[inline] pub fn as_mut_ptr(&mut self) -> *mut T { @@ -336,7 +467,7 @@ impl [T] { /// /// Panics if `a` or `b` are out of bounds. /// - /// # Example + /// # Examples /// /// ```rust /// let mut v = ["a", "b", "c", "d"]; @@ -365,13 +496,39 @@ impl [T] { } /// Returns an iterator over the slice. + /// + /// # Examples + /// + /// ``` + /// let x = &[1, 2, 4]; + /// let mut iterator = x.iter(); + /// + /// assert_eq!(iterator.next(), Some(&1)); + /// assert_eq!(iterator.next(), Some(&2)); + /// assert_eq!(iterator.next(), Some(&4)); + /// assert_eq!(iterator.next(), None); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[inline] pub fn iter(&self) -> Iter { core_slice::SliceExt::iter(self) } - /// Returns an iterator that allows modifying each value + /// Returns an iterator that allows modifying each value. + /// + /// # Examples + /// + /// ``` + /// let x = &mut [1, 2, 4]; + /// { + /// let iterator = x.iter_mut(); + /// + /// for elem in iterator { + /// *elem += 2; + /// } + /// } + /// assert_eq!(x, &[3, 4, 6]); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[inline] pub fn iter_mut(&mut self) -> IterMut { @@ -419,6 +576,7 @@ impl [T] { /// /// ```rust /// let v = &[1, 2, 3, 4, 5]; + /// /// for chunk in v.chunks(2) { /// println!("{:?}", chunk); /// } @@ -437,6 +595,21 @@ impl [T] { /// # Panics /// /// Panics if `chunk_size` is 0. + /// + /// # Examples + /// + /// ``` + /// let v = &mut [0, 0, 0, 0, 0]; + /// let mut count = 1; + /// + /// for chunk in v.chunks_mut(2) { + /// for elem in chunk.iter_mut() { + /// *elem += count; + /// } + /// count += 1; + /// } + /// assert_eq!(v, &[1, 1, 2, 2, 3]); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[inline] pub fn chunks_mut(&mut self, chunk_size: usize) -> ChunksMut { @@ -477,7 +650,7 @@ impl [T] { /// /// Panics if `mid > len`. /// - /// # Example + /// # Examples /// /// ```rust /// let mut v = [1, 2, 3, 4, 5, 6]; @@ -508,7 +681,7 @@ impl [T] { } /// Returns an iterator over subslices separated by elements that match - /// `pred`. The matched element is not contained in the subslices. + /// `pred`. The matched element is not contained in the subslices. /// /// # Examples /// @@ -517,6 +690,7 @@ impl [T] { /// /// ``` /// let v = [10, 40, 30, 20, 60, 50]; + /// /// for group in v.split(|num| *num % 3 == 0) { /// println!("{:?}", group); /// } @@ -530,7 +704,18 @@ impl [T] { } /// Returns an iterator over mutable subslices separated by elements that - /// match `pred`. The matched element is not contained in the subslices. + /// match `pred`. The matched element is not contained in the subslices. + /// + /// # Examples + /// + /// ``` + /// let mut v = [10, 40, 30, 20, 60, 50]; + /// + /// for group in v.split_mut(|num| *num % 3 == 0) { + /// group[0] = 1; + /// } + /// assert_eq!(v, [1, 40, 30, 1, 60, 1]); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[inline] pub fn split_mut(&mut self, pred: F) -> SplitMut @@ -553,6 +738,7 @@ impl [T] { /// /// ``` /// let v = [10, 40, 30, 20, 60, 50]; + /// /// for group in v.splitn(2, |num| *num % 3 == 0) { /// println!("{:?}", group); /// } @@ -571,6 +757,17 @@ impl [T] { /// /// The last element returned, if any, will contain the remainder of the /// slice. + /// + /// # Examples + /// + /// ``` + /// let mut v = [10, 40, 30, 20, 60, 50]; + /// + /// for group in v.splitn_mut(2, |num| *num % 3 == 0) { + /// group[0] = 1; + /// } + /// assert_eq!(v, [1, 40, 30, 1, 60, 50]); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[inline] pub fn splitn_mut(&mut self, n: usize, pred: F) -> SplitNMut @@ -594,6 +791,7 @@ impl [T] { /// /// ``` /// let v = [10, 40, 30, 20, 60, 50]; + /// /// for group in v.rsplitn(2, |num| *num % 3 == 0) { /// println!("{:?}", group); /// } @@ -613,6 +811,17 @@ impl [T] { /// /// The last element returned, if any, will contain the remainder of the /// slice. + /// + /// # Examples + /// + /// ``` + /// let mut s = [10, 40, 30, 20, 60, 50]; + /// + /// for group in s.rsplitn_mut(2, |num| *num % 3 == 0) { + /// group[0] = 1; + /// } + /// assert_eq!(s, [1, 40, 30, 20, 60, 1]); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[inline] pub fn rsplitn_mut(&mut self, n: usize, pred: F) -> RSplitNMut @@ -892,6 +1101,14 @@ impl [T] { /// Copies `self` into a new `Vec`. + /// + /// # Examples + /// + /// ``` + /// let s = [10, 40, 30]; + /// let x = s.to_vec(); + /// // Here, `s` and `x` can be modified independently. + /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[inline] pub fn to_vec(&self) -> Vec @@ -902,6 +1119,16 @@ impl [T] { } /// Converts `self` into a vector without clones or allocation. + /// + /// # Examples + /// + /// ``` + /// let s: Box<[i32]> = Box::new([10, 40, 30]); + /// let x = s.into_vec(); + /// // `s` cannot be used anymore because it has been converted into `x`. + /// + /// assert_eq!(x, vec!(10, 40, 30)); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[inline] pub fn into_vec(self: Box) -> Vec {