nordic-dev.net/rust
nordic-dev.net/rust
2
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2024-11-25 16:24:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Auto merge of #34725 - GuillaumeGomez:doc_slice, r=steveklabnik

Browse Source 
Improve slice docs

Fixes  #29337.

r? @steveklabnik
This commit is contained in:
bors 2016-07-11 07:13:50 -07:00 committed by GitHub
commit 3ab8054ac1
1 changed files with 236 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

245
src/libcollections/slice.rs
View File

@ -199,7 +199,18 @@ impl<T> [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> {
@ -207,6 +218,17 @@ impl<T> [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])> {
@ -214,6 +236,19 @@ impl<T> [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])> {
@ -221,6 +256,17 @@ impl<T> [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])> {
@ -229,6 +275,19 @@ impl<T> [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])> {
@ -253,6 +312,17 @@ impl<T> [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> {
@ -275,7 +345,18 @@ impl<T> [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]
@ -284,14 +365,37 @@ impl<T> [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 {
@ -305,6 +409,19 @@ impl<T> [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 {
@ -318,6 +435,20 @@ impl<T> [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 {
@ -335,7 +466,7 @@ impl<T> [T] {
///
/// Panics if `a` or `b` are out of bounds.
///
/// # Example
/// # Examples
///
/// ```rust
/// let mut v = ["a", "b", "c", "d"];
@ -364,13 +495,39 @@ impl<T> [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<T> {
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<T> {
@ -418,6 +575,7 @@ impl<T> [T] {
///
/// ```rust
/// let v = &[1, 2, 3, 4, 5];
///
/// for chunk in v.chunks(2) {
/// println!("{:?}", chunk);
/// }
@ -436,6 +594,21 @@ impl<T> [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<T> {
@ -476,7 +649,7 @@ impl<T> [T] {
///
/// Panics if `mid > len`.
///
/// # Example
/// # Examples
///
/// ```rust
/// let mut v = [1, 2, 3, 4, 5, 6];
@ -507,7 +680,7 @@ impl<T> [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
///
@ -516,6 +689,7 @@ impl<T> [T] {
///
/// ```
/// let v = [10, 40, 30, 20, 60, 50];
///
/// for group in v.split(|num| *num % 3 == 0) {
/// println!("{:?}", group);
/// }
@ -529,7 +703,18 @@ impl<T> [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<F>(&mut self, pred: F) -> SplitMut<T, F>
@ -552,6 +737,7 @@ impl<T> [T] {
///
/// ```
/// let v = [10, 40, 30, 20, 60, 50];
///
/// for group in v.splitn(2, |num| *num % 3 == 0) {
/// println!("{:?}", group);
/// }
@ -570,6 +756,17 @@ impl<T> [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<F>(&mut self, n: usize, pred: F) -> SplitNMut<T, F>
@ -593,6 +790,7 @@ impl<T> [T] {
///
/// ```
/// let v = [10, 40, 30, 20, 60, 50];
///
/// for group in v.rsplitn(2, |num| *num % 3 == 0) {
/// println!("{:?}", group);
/// }
@ -612,6 +810,17 @@ impl<T> [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<F>(&mut self, n: usize, pred: F) -> RSplitNMut<T, F>
@ -891,6 +1100,14 @@ impl<T> [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<T>
@ -901,6 +1118,16 @@ impl<T> [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<Self>) -> Vec<T> {