From 69289c93666cad424627c0d696841c8f78e96448 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Fri, 8 Apr 2016 01:56:45 +0200 Subject: [PATCH] Add doc example for Iter and IterMut --- src/libcore/slice.rs | 166 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 162 insertions(+), 4 deletions(-) diff --git a/src/libcore/slice.rs b/src/libcore/slice.rs index 6e0e972fa0c..39ef2207187 100644 --- a/src/libcore/slice.rs +++ b/src/libcore/slice.rs @@ -38,6 +38,7 @@ use cmp::{Ordering, PartialEq, PartialOrd, Eq, Ord}; use cmp::Ordering::{Less, Equal, Greater}; use cmp; use default::Default; +use fmt; use intrinsics::assume; use iter::*; use ops::{FnMut, self, Index}; @@ -632,8 +633,7 @@ impl ops::Index> for [T] { #[inline] fn index(&self, index: ops::RangeToInclusive) -> &[T] { - // SNAP 4d3eebf change this to `0...index.end` - self.index(ops::RangeInclusive::NonEmpty { start: 0, end: index.end }) + self.index(0...index.end) } } @@ -723,8 +723,7 @@ impl ops::IndexMut> for [T] { impl ops::IndexMut> for [T] { #[inline] fn index_mut(&mut self, index: ops::RangeToInclusive) -> &mut [T] { - // SNAP 4d3eebf change this to `0...index.end` - self.index_mut(ops::RangeInclusive::NonEmpty { start: 0, end: index.end }) + self.index_mut(0...index.end) } } @@ -872,6 +871,20 @@ macro_rules! make_mut_slice { } /// Immutable slice iterator +/// +/// # Examples +/// +/// Basic usage: +/// +/// ``` +/// // First, we declare a type which has `iter` method to get the `Iter` struct (&[usize here]): +/// let slice = &[1, 2, 3]; +/// +/// // Then, we iterate over it: +/// for element in slice.iter() { +/// println!("{}", element); +/// } +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub struct Iter<'a, T: 'a> { ptr: *const T, @@ -879,6 +892,15 @@ pub struct Iter<'a, T: 'a> { _marker: marker::PhantomData<&'a T>, } +#[stable(feature = "core_impl_debug", since = "1.9.0")] +impl<'a, T: 'a + fmt::Debug> fmt::Debug for Iter<'a, T> { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.debug_tuple("Iter") + .field(&self.as_slice()) + .finish() + } +} + #[stable(feature = "rust1", since = "1.0.0")] unsafe impl<'a, T: Sync> Sync for Iter<'a, T> {} #[stable(feature = "rust1", since = "1.0.0")] @@ -889,6 +911,26 @@ impl<'a, T> Iter<'a, T> { /// /// This has the same lifetime as the original slice, and so the /// iterator can continue to be used while this exists. + /// + /// # Examples + /// + /// Basic usage: + /// + /// ``` + /// // First, we declare a type which has the `iter` method to get the `Iter` + /// // struct (&[usize here]): + /// let slice = &[1, 2, 3]; + /// + /// // Then, we get the iterator: + /// let mut iter = slice.iter(); + /// // So if we print what `as_slice` method returns here, we have "[1, 2, 3]": + /// println!("{:?}", iter.as_slice()); + /// + /// // Next, we move to the second element of the slice: + /// iter.next(); + /// // Now `as_slice` returns "[2, 3]": + /// println!("{:?}", iter.as_slice()); + /// ``` #[stable(feature = "iter_to_slice", since = "1.4.0")] pub fn as_slice(&self) -> &'a [T] { make_slice!(self.ptr, self.end) @@ -920,6 +962,24 @@ impl<'a, T> Clone for Iter<'a, T> { } /// Mutable slice iterator. +/// +/// # Examples +/// +/// Basic usage: +/// +/// ``` +/// // First, we declare a type which has `iter_mut` method to get the `IterMut` +/// // struct (&[usize here]): +/// let mut slice = &mut [1, 2, 3]; +/// +/// // Then, we iterate over it and increment each element value: +/// for element in slice.iter_mut() { +/// *element += 1; +/// } +/// +/// // We now have "[2, 3, 4]": +/// println!("{:?}", slice); +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub struct IterMut<'a, T: 'a> { ptr: *mut T, @@ -927,6 +987,15 @@ pub struct IterMut<'a, T: 'a> { _marker: marker::PhantomData<&'a mut T>, } +#[stable(feature = "core_impl_debug", since = "1.9.0")] +impl<'a, T: 'a + fmt::Debug> fmt::Debug for IterMut<'a, T> { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.debug_tuple("IterMut") + .field(&make_slice!(self.ptr, self.end)) + .finish() + } +} + #[stable(feature = "rust1", since = "1.0.0")] unsafe impl<'a, T: Sync> Sync for IterMut<'a, T> {} #[stable(feature = "rust1", since = "1.0.0")] @@ -939,6 +1008,35 @@ impl<'a, T> IterMut<'a, T> { /// to consume the iterator. Consider using the `Slice` and /// `SliceMut` implementations for obtaining slices with more /// restricted lifetimes that do not consume the iterator. + /// + /// # Examples + /// + /// Basic usage: + /// + /// ``` + /// // First, we declare a type which has `iter_mut` method to get the `IterMut` + /// // struct (&[usize here]): + /// let mut slice = &mut [1, 2, 3]; + /// + /// { + /// // Then, we get the iterator: + /// let mut iter = slice.iter_mut(); + /// // We move to next element: + /// iter.next(); + /// // So if we print what `into_slice` method returns here, we have "[2, 3]": + /// println!("{:?}", iter.into_slice()); + /// } + /// + /// // Now let's modify a value of the slice: + /// { + /// // First we get back the iterator: + /// let mut iter = slice.iter_mut(); + /// // We change the value of the first element of the slice returned by the `next` method: + /// *iter.next().unwrap() += 1; + /// } + /// // Now slice is "[2, 2, 3]": + /// println!("{:?}", slice); + /// ``` #[stable(feature = "iter_to_slice", since = "1.4.0")] pub fn into_slice(self) -> &'a mut [T] { make_mut_slice!(self.ptr, self.end) @@ -982,6 +1080,16 @@ pub struct Split<'a, T:'a, P> where P: FnMut(&T) -> bool { finished: bool } +#[stable(feature = "core_impl_debug", since = "1.9.0")] +impl<'a, T: 'a + fmt::Debug, P> fmt::Debug for Split<'a, T, P> where P: FnMut(&T) -> bool { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.debug_struct("Split") + .field("v", &self.v) + .field("finished", &self.finished) + .finish() + } +} + // FIXME(#19839) Remove in favor of `#[derive(Clone)]` #[stable(feature = "rust1", since = "1.0.0")] impl<'a, T, P> Clone for Split<'a, T, P> where P: Clone + FnMut(&T) -> bool { @@ -1055,6 +1163,16 @@ pub struct SplitMut<'a, T:'a, P> where P: FnMut(&T) -> bool { finished: bool } +#[stable(feature = "core_impl_debug", since = "1.9.0")] +impl<'a, T: 'a + fmt::Debug, P> fmt::Debug for SplitMut<'a, T, P> where P: FnMut(&T) -> bool { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.debug_struct("SplitMut") + .field("v", &self.v) + .field("finished", &self.finished) + .finish() + } +} + impl<'a, T, P> SplitIter for SplitMut<'a, T, P> where P: FnMut(&T) -> bool { #[inline] fn finish(&mut self) -> Option<&'a mut [T]> { @@ -1129,6 +1247,7 @@ impl<'a, T, P> DoubleEndedIterator for SplitMut<'a, T, P> where /// An private iterator over subslices separated by elements that /// match a predicate function, splitting at most a fixed number of /// times. +#[derive(Debug)] struct GenericSplitN { iter: I, count: usize, @@ -1164,6 +1283,15 @@ pub struct SplitN<'a, T: 'a, P> where P: FnMut(&T) -> bool { inner: GenericSplitN> } +#[stable(feature = "core_impl_debug", since = "1.9.0")] +impl<'a, T: 'a + fmt::Debug, P> fmt::Debug for SplitN<'a, T, P> where P: FnMut(&T) -> bool { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.debug_struct("SplitN") + .field("inner", &self.inner) + .finish() + } +} + /// An iterator over subslices separated by elements that match a /// predicate function, limited to a given number of splits, starting /// from the end of the slice. @@ -1172,6 +1300,15 @@ pub struct RSplitN<'a, T: 'a, P> where P: FnMut(&T) -> bool { inner: GenericSplitN> } +#[stable(feature = "core_impl_debug", since = "1.9.0")] +impl<'a, T: 'a + fmt::Debug, P> fmt::Debug for RSplitN<'a, T, P> where P: FnMut(&T) -> bool { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.debug_struct("RSplitN") + .field("inner", &self.inner) + .finish() + } +} + /// An iterator over subslices separated by elements that match a predicate /// function, limited to a given number of splits. #[stable(feature = "rust1", since = "1.0.0")] @@ -1179,6 +1316,15 @@ pub struct SplitNMut<'a, T: 'a, P> where P: FnMut(&T) -> bool { inner: GenericSplitN> } +#[stable(feature = "core_impl_debug", since = "1.9.0")] +impl<'a, T: 'a + fmt::Debug, P> fmt::Debug for SplitNMut<'a, T, P> where P: FnMut(&T) -> bool { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.debug_struct("SplitNMut") + .field("inner", &self.inner) + .finish() + } +} + /// An iterator over subslices separated by elements that match a /// predicate function, limited to a given number of splits, starting /// from the end of the slice. @@ -1187,6 +1333,15 @@ pub struct RSplitNMut<'a, T: 'a, P> where P: FnMut(&T) -> bool { inner: GenericSplitN> } +#[stable(feature = "core_impl_debug", since = "1.9.0")] +impl<'a, T: 'a + fmt::Debug, P> fmt::Debug for RSplitNMut<'a, T, P> where P: FnMut(&T) -> bool { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.debug_struct("RSplitNMut") + .field("inner", &self.inner) + .finish() + } +} + macro_rules! forward_iterator { ($name:ident: $elem:ident, $iter_of:ty) => { #[stable(feature = "rust1", since = "1.0.0")] @@ -1214,6 +1369,7 @@ forward_iterator! { SplitNMut: T, &'a mut [T] } forward_iterator! { RSplitNMut: T, &'a mut [T] } /// An iterator over overlapping subslices of length `size`. +#[derive(Debug)] #[stable(feature = "rust1", since = "1.0.0")] pub struct Windows<'a, T:'a> { v: &'a [T], @@ -1307,6 +1463,7 @@ impl<'a, T> ExactSizeIterator for Windows<'a, T> {} /// /// When the slice len is not evenly divided by the chunk size, the last slice /// of the iteration will be the remainder. +#[derive(Debug)] #[stable(feature = "rust1", since = "1.0.0")] pub struct Chunks<'a, T:'a> { v: &'a [T], @@ -1407,6 +1564,7 @@ impl<'a, T> ExactSizeIterator for Chunks<'a, T> {} /// An iterator over a slice in (non-overlapping) mutable chunks (`size` /// elements at a time). When the slice len is not evenly divided by the chunk /// size, the last slice of the iteration will be the remainder. +#[derive(Debug)] #[stable(feature = "rust1", since = "1.0.0")] pub struct ChunksMut<'a, T:'a> { v: &'a mut [T],